diff --git a/TOC.md b/TOC.md new file mode 100644 index 000000000000..013f601a2131 --- /dev/null +++ b/TOC.md @@ -0,0 +1,490 @@ +# TiDB 中文用户文档 + + + + +## 目录 + ++ 关于 TiDB + - [TiDB 简介](/overview.md) + + Benchmark 测试 + - [如何用 Sysbench 测试 TiDB](/benchmark/how-to-run-sysbench.md) + - [如何对 TiDB 进行 TPC-C 测试](/benchmark/how-to-run-tpcc.md) + - [Sysbench 性能对比 - v3.0 对比 v2.1](/benchmark/sysbench-v4.md) + - [TPC-C 性能对比 - v3.0 对比 v2.1](/benchmark/tpcc.md) + - [线上负载与 `Add Index` 相互影响测试](/benchmark/add-index-with-load.md) + - [TiDB in Kubernetes Sysbench 性能测试](/benchmark/sysbench-in-k8s.md) + - [DM 1.0-GA 性能测试](/benchmark/dm-v1.0-ga.md) ++ 主要概念 + - [整体架构](/architecture.md) + + 核心特性 + - [水平扩展](/key-features.md#水平扩展) + - [高可用](/key-features.md#高可用) ++ 操作指南 + + 快速上手 + - [使用 Docker Compose 部署 TiDB](/how-to/get-started/deploy-tidb-from-docker-compose.md) + - [SQL 基本操作](/how-to/get-started/explore-sql.md) + - [读取历史数据](/how-to/get-started/read-historical-data.md) + - [TiDB Binlog 教程](/how-to/get-started/tidb-binlog.md) + - [TiDB Data Migration 教程](/how-to/get-started/data-migration.md) + - [TiDB Lightning 教程](/how-to/get-started/tidb-lightning.md) + - [TiSpark 教程](/how-to/get-started/tispark.md) + + 部署 + - [软硬件环境需求](/how-to/deploy/hardware-recommendations.md) + + 集群部署方式 + - [使用 Ansible 部署（推荐）](/how-to/deploy/orchestrated/ansible.md) + - [使用 Ansible 离线部署](/how-to/deploy/orchestrated/offline-ansible.md) + - [使用 Docker 部署](/how-to/deploy/orchestrated/docker.md) + + 跨地域冗余 + - [跨数据中心部署方案](/how-to/deploy/geographic-redundancy/overview.md) + - [配置集群拓扑](/how-to/deploy/geographic-redundancy/location-awareness.md) + - [使用 Ansible 部署 DM 集群](/how-to/deploy/data-migration-with-ansible.md) + + 配置 + - [时区](/how-to/configure/time-zone.md) + - [内存控制](/how-to/configure/memory-control.md) + + 安全 + + 安全传输层协议 (TLS) + - [为 MySQL 客户端开启 TLS](/how-to/secure/enable-tls-clients.md) + - [为 TiDB 组件间开启 TLS](/how-to/secure/enable-tls-between-components.md) + - [生成自签名证书](/how-to/secure/generate-self-signed-certificates.md) + + 监控 + - [概述](/how-to/monitor/overview.md) + - [监控 TiDB 集群](/how-to/monitor/monitor-a-cluster.md) + + 迁移 + - [迁移工具使用指南](/reference/tools/user-guide.md) + + 从 MySQL 迁移 + - [以 Amazon Aurora MySQL 为例](/how-to/migrate/from-mysql-aurora.md) + - [从 CSV 迁移](/reference/tools/tidb-lightning/csv.md) + + 运维 + - [Ansible 常见运维操作](/how-to/maintain/ansible-operations.md) + + 备份与恢复 + - [使用 Mydumper/TiDB Lightning 进行备份与恢复](/how-to/maintain/backup-and-restore/mydumper-lightning.md) + - [使用 BR 进行备份与恢复](/reference/tools/br/br.md) + - [BR 备份与恢复场景示例](/reference/tools/br/use-cases.md) + + 定位异常查询 + - [定位慢查询](/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) + - [定位消耗系统资源多的查询](/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md) + + 扩容缩容 + - [使用 Ansible 扩容缩容](/how-to/scale/with-ansible.md) + + 升级 + - [升级至最新开发版](/how-to/upgrade/from-previous-version.md) + + 故障诊断 + - [集群配置诊断](/how-to/troubleshoot/cluster-setup.md) + - [TiDB Lightning 故障诊断](/how-to/troubleshoot/tidb-lightning.md) ++ 参考手册 + + SQL + - [与 MySQL 兼容性对比](/reference/mysql-compatibility.md) + + SQL 语言结构 + - [字面值](/reference/sql/language-structure/literal-values.md) + - [Schema 对象名](/reference/sql/language-structure/schema-object-names.md) + - [关键字和保留字](/reference/sql/language-structure/keywords-and-reserved-words.md) + - [用户自定义变量](/reference/sql/language-structure/user-defined-variables.md) + - [表达式语法](/reference/sql/language-structure/expression-syntax.md) + - [注释语法](/reference/sql/language-structure/comment-syntax.md) + + 数据类型 + - [概述](/reference/sql/data-types/overview.md) + - [默认值](/reference/sql/data-types/default-values.md) + + 数值类型 + - [`BIT`](/reference/sql/data-types/numeric.md#bit-类型) + - [`BOOL|BOOLEAN`](/reference/sql/data-types/numeric.md#boolean-类型) + - [`TINYINT`](/reference/sql/data-types/numeric.md#tinyint-类型) + - [`SMALLINT`](/reference/sql/data-types/numeric.md#smallint-类型) + - [`MEDIUMINT`](/reference/sql/data-types/numeric.md#mediumint-类型) + - [`INT|INTEGER`](/reference/sql/data-types/numeric.md#integer-类型) + - [`BIGINT`](/reference/sql/data-types/numeric.md#bigint-类型) + - [`DECIMAL`](/reference/sql/data-types/numeric.md#decimal-类型) + - [`FLOAT`](/reference/sql/data-types/numeric.md#float-类型) + - [`DOUBLE`](/reference/sql/data-types/numeric.md#double-类型) + + 日期和时间类型 + - [`DATE`](/reference/sql/data-types/date-and-time.md#date-类型) + - [`DATETIME`](/reference/sql/data-types/date-and-time.md#datetime-类型) + - [`TIMESTAMP`](/reference/sql/data-types/date-and-time.md#timestamp-类型) + - [`TIME`](/reference/sql/data-types/date-and-time.md#time-类型) + - [`YEAR`](/reference/sql/data-types/date-and-time.md#year-类型) + + 字符串类型 + - [`CHAR`](/reference/sql/data-types/string.md#char-类型) + - [`VARCHAR`](/reference/sql/data-types/string.md#varchar-类型) + - [`TEXT`](/reference/sql/data-types/string.md#text-类型) + - [`LONGTEXT`](/reference/sql/data-types/string.md#longtext-类型) + - [`BINARY`](/reference/sql/data-types/string.md#binary-类型) + - [`VARBINARY`](/reference/sql/data-types/string.md#varbinary-类型) + - [`TINYBLOB`](/reference/sql/data-types/string.md#tinyblob-类型) + - [`BLOB`](/reference/sql/data-types/string.md#blob-类型) + - [`MEDIUMBLOB`](/reference/sql/data-types/string.md#mediumblob-类型) + - [`LONGBLOB`](/reference/sql/data-types/string.md#longblob-类型) + - [`ENUM`](/reference/sql/data-types/string.md#enum-类型) + - [`SET`](/reference/sql/data-types/string.md#set-类型) + - [JSON Type](/reference/sql/data-types/json.md) + + 函数与操作符 + - [函数与操作符概述](/reference/sql/functions-and-operators/reference.md) + - [表达式求值的类型转换](/reference/sql/functions-and-operators/type-conversion.md) + - [操作符](/reference/sql/functions-and-operators/operators.md) + - [控制流程函数](/reference/sql/functions-and-operators/control-flow-functions.md) + - [字符串函数](/reference/sql/functions-and-operators/string-functions.md) + - [数值函数与操作符](/reference/sql/functions-and-operators/numeric-functions-and-operators.md) + - [日期和时间函数](/reference/sql/functions-and-operators/date-and-time-functions.md) + - [位函数和操作符](/reference/sql/functions-and-operators/bit-functions-and-operators.md) + - [Cast 函数和操作符](/reference/sql/functions-and-operators/cast-functions-and-operators.md) + - [加密和压缩函数](/reference/sql/functions-and-operators/encryption-and-compression-functions.md) + - [信息函数](/reference/sql/functions-and-operators/information-functions.md) + - [JSON 函数](/reference/sql/functions-and-operators/json-functions.md) + - [GROUP BY 聚合函数](/reference/sql/functions-and-operators/aggregate-group-by-functions.md) + - [窗口函数](/reference/sql/functions-and-operators/window-functions.md) + - [其它函数](/reference/sql/functions-and-operators/miscellaneous-functions.md) + - [精度数学](/reference/sql/functions-and-operators/precision-math.md) + - [下推到 TiKV 的表达式列表](/reference/sql/functions-and-operators/expressions-pushed-down.md) + + SQL 语句 + - [`ADD COLUMN`](/reference/sql/statements/add-column.md) + - [`ADD INDEX`](/reference/sql/statements/add-index.md) + - [`ADMIN`](/reference/sql/statements/admin.md) + - [`ALTER DATABASE`](/reference/sql/statements/alter-database.md) + - [`ALTER TABLE`](/reference/sql/statements/alter-table.md) + - [`ALTER USER`](/reference/sql/statements/alter-user.md) + - [`ANALYZE TABLE`](/reference/sql/statements/analyze-table.md) + - [`BEGIN`](/reference/sql/statements/begin.md) + - [`COMMIT`](/reference/sql/statements/commit.md) + - [`CREATE DATABASE`](/reference/sql/statements/create-database.md) + - [`CREATE INDEX`](/reference/sql/statements/create-index.md) + - [`CREATE TABLE LIKE`](/reference/sql/statements/create-table-like.md) + - [`CREATE TABLE`](/reference/sql/statements/create-table.md) + - [`CREATE USER`](/reference/sql/statements/create-user.md) + - [`CREATE VIEW`](/reference/sql/statements/create-view.md) + - [`DEALLOCATE`](/reference/sql/statements/deallocate.md) + - [`DELETE`](/reference/sql/statements/delete.md) + - [`DESC`](/reference/sql/statements/desc.md) + - [`DESCRIBE`](/reference/sql/statements/describe.md) + - [`DO`](/reference/sql/statements/do.md) + - [`DROP COLUMN`](/reference/sql/statements/drop-column.md) + - [`DROP DATABASE`](/reference/sql/statements/drop-database.md) + - [`DROP INDEX`](/reference/sql/statements/drop-index.md) + - [`DROP TABLE`](/reference/sql/statements/drop-table.md) + - [`DROP USER`](/reference/sql/statements/drop-user.md) + - [`DROP VIEW`](/reference/sql/statements/drop-view.md) + - [`EXECUTE`](/reference/sql/statements/execute.md) + - [`EXPLAIN ANALYZE`](/reference/sql/statements/explain-analyze.md) + - [`EXPLAIN`](/reference/sql/statements/explain.md) + - [`FLUSH PRIVILEGES`](/reference/sql/statements/flush-privileges.md) + - [`FLUSH STATUS`](/reference/sql/statements/flush-status.md) + - [`FLUSH TABLES`](/reference/sql/statements/flush-tables.md) + - [`GRANT `](/reference/sql/statements/grant-privileges.md) + - [`INSERT`](/reference/sql/statements/insert.md) + - [`KILL [TIDB]`](/reference/sql/statements/kill.md) + - [`LOAD DATA`](/reference/sql/statements/load-data.md) + - [`MODIFY COLUMN`](/reference/sql/statements/modify-column.md) + - [`PREPARE`](/reference/sql/statements/prepare.md) + - [`RECOVER TABLE`](/reference/sql/statements/recover-table.md) + - [`RENAME INDEX`](/reference/sql/statements/rename-index.md) + - [`RENAME TABLE`](/reference/sql/statements/rename-table.md) + - [`REPLACE`](/reference/sql/statements/replace.md) + - [`REVOKE `](/reference/sql/statements/revoke-privileges.md) + - [`ROLLBACK`](/reference/sql/statements/rollback.md) + - [`SELECT`](/reference/sql/statements/select.md) + - [`SET [NAMES|CHARACTER SET]`](/reference/sql/statements/set-names.md) + - [`SET PASSWORD`](/reference/sql/statements/set-password.md) + - [`SET TRANSACTION`](/reference/sql/statements/set-transaction.md) + - [`SET [GLOBAL|SESSION] `](/reference/sql/statements/set-variable.md) + - [`SHOW CHARACTER SET`](/reference/sql/statements/show-character-set.md) + - [`SHOW COLLATION`](/reference/sql/statements/show-collation.md) + - [`SHOW [FULL] COLUMNS FROM`](/reference/sql/statements/show-columns-from.md) + - [`SHOW CREATE TABLE`](/reference/sql/statements/show-create-table.md) + - [`SHOW CREATE USER`](/reference/sql/statements/show-create-user.md) + - [`SHOW DATABASES`](/reference/sql/statements/show-databases.md) + - [`SHOW ENGINES`](/reference/sql/statements/show-engines.md) + - [`SHOW ERRORS`](/reference/sql/statements/show-errors.md) + - [`SHOW [FULL] FIELDS FROM`](/reference/sql/statements/show-fields-from.md) + - [`SHOW GRANTS`](/reference/sql/statements/show-grants.md) + - [`SHOW INDEXES [FROM|IN]`](/reference/sql/statements/show-indexes.md) + - [`SHOW INDEX [FROM|IN]`](/reference/sql/statements/show-index.md) + - [`SHOW KEYS [FROM|IN]`](/reference/sql/statements/show-keys.md) + - [`SHOW PRIVILEGES`](/reference/sql/statements/show-privileges.md) + - [`SHOW [FULL] PROCESSSLIST`](/reference/sql/statements/show-processlist.md) + - [`SHOW SCHEMAS`](/reference/sql/statements/show-schemas.md) + - [`SHOW [FULL] TABLES`](/reference/sql/statements/show-tables.md) + - [`SHOW TABLE REGIONS`](/reference/sql/statements/show-table-regions.md) + - [`SHOW TABLE STATUS`](/reference/sql/statements/show-table-status.md) + - [`SHOW [GLOBAL|SESSION] VARIABLES`](/reference/sql/statements/show-variables.md) + - [`SHOW WARNINGS`](/reference/sql/statements/show-warnings.md) + - [`SPLIT REGION`](/reference/sql/statements/split-region.md) + - [`START TRANSACTION`](/reference/sql/statements/start-transaction.md) + - [`TRACE`](/reference/sql/statements/trace.md) + - [`TRUNCATE`](/reference/sql/statements/truncate.md) + - [`UPDATE`](/reference/sql/statements/update.md) + - [`USE`](/reference/sql/statements/use.md) + - [约束](/reference/sql/constraints.md) + - [生成列](/reference/sql/generated-columns.md) + - [分区表](/reference/sql/partitioning.md) + - [字符集](/reference/sql/character-set.md) + - [SQL 模式](/reference/sql/sql-mode.md) + - [视图](/reference/sql/view.md) + + 配置 + + tidb-server + - [MySQL 系统变量](/reference/configuration/tidb-server/mysql-variables.md) + - [TiDB 特定系统变量](/reference/configuration/tidb-server/tidb-specific-variables.md) + - [配置参数](/reference/configuration/tidb-server/configuration.md) + - [配置文件描述](/reference/configuration/tidb-server/configuration-file.md) + + pd-server + - [配置参数](/reference/configuration/pd-server/configuration.md) + - [配置文件描述](/reference/configuration/pd-server/configuration-file.md) + + tikv-server + - [配置参数](/reference/configuration/tikv-server/configuration.md) + - [配置文件描述](/reference/configuration/tikv-server/configuration-file.md) + + 安全 + - [与 MySQL 的安全特性差异](/reference/security/compatibility.md) + - [TiDB 数据库权限管理](/reference/security/privilege-system.md) + - [TiDB 用户账户管理](/reference/security/user-account-management.md) + - [基于角色的访问控制](/reference/security/role-based-access-control.md) + - [TiDB 证书鉴权使用指南](/reference/security/cert-based-authentication.md) + + 事务 + - [事务概览](/reference/transactions/overview.md) + - [隔离级别](/reference/transactions/transaction-isolation.md) + - [乐观事务](/reference/transactions/transaction-optimistic.md) + - [悲观事务](/reference/transactions/transaction-pessimistic.md) + + 系统数据库 + - [`mysql`](/reference/system-databases/mysql.md) + - [`information_schema`](/reference/system-databases/information-schema.md) + - [错误码](/reference/error-codes.md) + - [支持的连接器和 API](/reference/supported-clients.md) + + 垃圾回收 (GC) + - [GC 机制简介](/reference/garbage-collection/overview.md) + - [GC 配置](/reference/garbage-collection/configuration.md) + + 性能调优 + - [SQL 优化流程](/reference/performance/sql-optimizer-overview.md) + - [理解 TiDB 执行计划](/reference/performance/understanding-the-query-execution-plan.md) + - [执行计划绑定](/reference/performance/execution-plan-bind.md) + - [统计信息概述](/reference/performance/statistics.md) + - [Optimizer Hints](/reference/performance/optimizer-hints.md) + - [Follower Read](/reference/performance/follower-read.md) + - [使用 SQL 语句检查 TiDB 集群状态](/reference/performance/check-cluster-status-using-sql-statements.md) + - [Statement Summary Table](/reference/performance/statement-summary.md) + - [TiKV 调优](/reference/performance/tune-tikv.md) + - [TiDB 最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/) + + 监控指标 + - [Overview 面板](/reference/key-monitoring-metrics/overview-dashboard.md) + - [TiDB 面板](/reference/key-monitoring-metrics/tidb-dashboard.md) + - [PD 面板](/reference/key-monitoring-metrics/pd-dashboard.md) + - [TiKV 面板](/reference/key-monitoring-metrics/tikv-dashboard.md) + - [报警规则](/reference/alert-rules.md) + + 最佳实践 + - [HAProxy 最佳实践](/reference/best-practices/haproxy.md) + - [Java 应用开发最佳实践](/reference/best-practices/java-app.md) + - [高并发写入场景最佳实践](/reference/best-practices/high-concurrency.md) + - [Grafana 监控最佳实践](/reference/best-practices/grafana-monitor.md) + - [PD 调度策略最佳实践](/reference/best-practices/pd-scheduling.md) + - [海量 Region 集群调优最佳实践](/reference/best-practices/massive-regions.md) + + [TiSpark 使用指南](/reference/tispark.md) + + TiDB Binlog + - [概述](/reference/tidb-binlog/overview.md) + - [部署使用](/reference/tidb-binlog/deploy.md) + - [运维管理](/reference/tidb-binlog/maintain.md) + - [版本升级](/reference/tidb-binlog/upgrade.md) + - [监控告警](/reference/tidb-binlog/monitor.md) + - [增量恢复](/reference/tidb-binlog/reparo.md) + - [Kafka 自定义开发](/reference/tidb-binlog/binlog-slave-client.md) + - [TiDB Binlog Relay Log](/reference/tidb-binlog/relay-log.md) + - [术语表](/reference/tidb-binlog/glossary.md) + + 故障诊断 + - [故障诊断](/reference/tidb-binlog/troubleshoot/binlog.md) + - [常见错误修复](/reference/tidb-binlog/troubleshoot/error-handling.md) + - [FAQ](/reference/tidb-binlog/faq.md) + + 周边工具 + - [工具使用指南](/reference/tools/user-guide.md) + - [Mydumper](/reference/tools/mydumper.md) + - [Loader](/reference/tools/loader.md) + - [Syncer](/reference/tools/syncer.md) + + Data Migration + + 概述 + - [DM 架构](/reference/tools/data-migration/overview.md#dm-架构) + - [同步功能介绍](/reference/tools/data-migration/overview.md#同步功能介绍) + - [使用限制](/reference/tools/data-migration/overview.md#使用限制) + - [DM-worker 简介](/reference/tools/data-migration/dm-worker-intro.md) + - [DM Relay Log](/reference/tools/data-migration/relay-log.md) + + 核心特性 + - [Table Routing](/reference/tools/data-migration/features/overview.md#table-routing) + - [Black & White Lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists) + - [Binlog Event Filter](/reference/tools/data-migration/features/overview.md#binlog-event-filter) + - [同步延迟监控](/reference/tools/data-migration/features/overview.md#同步延迟监控) + + Shard Support + - [简介](/reference/tools/data-migration/features/shard-merge.md) + - [使用限制](/reference/tools/data-migration/features/shard-merge.md#使用限制) + - [手动处理 Sharding DDL Lock](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) + + 使用场景 + - [简单的从库同步场景](/reference/tools/data-migration/usage-scenarios/simple-synchronization.md) + - [分库分表合并场景](/reference/tools/data-migration/usage-scenarios/shard-merge.md) + - [分表合并数据迁移最佳实践](/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md) + - [DM-worker 在上游 MySQL 主从间切换](/reference/tools/data-migration/usage-scenarios/master-slave-switch.md) + + [部署使用](/reference/tools/data-migration/deploy.md) + + 配置 + - [概述](/reference/tools/data-migration/configure/overview.md) + - [DM-master 配置](/reference/tools/data-migration/configure/dm-master-configuration-file.md) + - [DM-worker 配置](/reference/tools/data-migration/configure/dm-worker-configuration-file.md) + - [任务配置](/reference/tools/data-migration/configure/task-configuration-file.md) + + DM 集群管理 + - [集群操作](/reference/tools/data-migration/cluster-operations.md) + - [集群升级](/reference/tools/data-migration/dm-upgrade.md) + + DM 同步任务管理 + - [管理数据同步任务](/reference/tools/data-migration/manage-tasks.md) + - [任务前置检查](/reference/tools/data-migration/precheck.md) + - [任务状态查询](/reference/tools/data-migration/query-status.md) + - [跳过或替代执行异常的 SQL 语句](/reference/tools/data-migration/skip-replace-sqls.md) + - [监控 DM 集群](/reference/tools/data-migration/monitor.md) + + 从与 MySQL 兼容的数据库迁移数据 + - [从 MySQL/Amazon Aurora MySQL 迁移数据](/how-to/migrate/from-mysql-aurora.md) + - [DM Portal](/reference/tools/data-migration/dm-portal.md) + + DM 故障诊断 + - [故障诊断](/reference/tools/data-migration/troubleshoot/dm.md) + - [错误含义](/reference/tools/data-migration/troubleshoot/error-system.md) + - [常见错误修复](/reference/tools/data-migration/troubleshoot/error-handling.md) + - [DM FAQ](/reference/tools/data-migration/faq.md) + + 版本发布历史 + + v1.0 + - [1.0.2](/reference/tools/data-migration/releases/1.0.2.md) + - [1.0.3](/reference/tools/data-migration/releases/1.0.3.md) + - [TiDB DM 术语表](/reference/tools/data-migration/glossary.md) + + TiDB Lightning + - [概述](/reference/tools/tidb-lightning/overview.md) + - [部署执行](/reference/tools/tidb-lightning/deployment.md) + - [参数说明](/reference/tools/tidb-lightning/config.md) + - [断点续传](/reference/tools/tidb-lightning/checkpoints.md) + - [表库过滤](/reference/tools/tidb-lightning/table-filter.md) + - [CSV 支持](/reference/tools/tidb-lightning/csv.md) + - [TiDB-backend](/reference/tools/tidb-lightning/tidb-backend.md) + - [Web 界面](/reference/tools/tidb-lightning/web.md) + - [监控告警](/reference/tools/tidb-lightning/monitor.md) + - [故障诊断](/how-to/troubleshoot/tidb-lightning.md) + - [FAQ](/faq/tidb-lightning.md) + - [术语表](/reference/tools/tidb-lightning/glossary.md) + - [sync-diff-inspector](/reference/tools/sync-diff-inspector/overview.md) + - [PD Control](/reference/tools/pd-control.md) + - [PD Recover](/reference/tools/pd-recover.md) + - [TiKV Control](/reference/tools/tikv-control.md) + - [TiDB Controller](/reference/tools/tidb-control.md) + - [工具下载](/reference/tools/download.md) ++ TiDB in Kubernetes + - [TiDB Operator 简介](/tidb-in-kubernetes/tidb-operator-overview.md) + + 快速上手 + - [kind](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) + - [GKE](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) + - [Minikube](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md) + + 部署 + - [集群环境要求](/tidb-in-kubernetes/deploy/prerequisites.md) + - [部署 TiDB Operator](/tidb-in-kubernetes/deploy/tidb-operator.md) + - [标准 Kubernetes 上的 TiDB 集群](/tidb-in-kubernetes/deploy/general-kubernetes.md) + - [AWS EKS 上的 TiDB 集群](/tidb-in-kubernetes/deploy/aws-eks.md) + - [GCP 上的 TiDB 集群](/tidb-in-kubernetes/deploy/gcp-gke.md) + - [阿里云上的 TiDB 集群](/tidb-in-kubernetes/deploy/alibaba-cloud.md) + - [访问 Kubernetes 上的 TiDB 集群](/tidb-in-kubernetes/deploy/access-tidb.md) + + 配置 + - [初始化集群](/tidb-in-kubernetes/initialize-cluster.md) + - [监控](/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) + + 运维 + - [销毁 TiDB 集群](/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md) + - [维护 TiDB 集群所在节点](/tidb-in-kubernetes/maintain/kubernetes-node.md) + - [备份与恢复](/tidb-in-kubernetes/maintain/backup-and-restore.md) + - [恢复 Kubernetes 上的 TiDB 集群数据](/tidb-in-kubernetes/maintain/lightning.md) + - [收集日志](/tidb-in-kubernetes/maintain/log-collecting.md) + - [集群故障自动转移](/tidb-in-kubernetes/maintain/auto-failover.md) + - [TiDB Binlog](/tidb-in-kubernetes/maintain/tidb-binlog.md) + - [重启 TiDB 集群](/tidb-in-kubernetes/maintain/restart.md) + - [扩缩容](/tidb-in-kubernetes/scale-in-kubernetes.md) + + 升级 + - [TiDB 集群](/tidb-in-kubernetes/upgrade/tidb-cluster.md) + - [TiDB Operator](/tidb-in-kubernetes/upgrade/tidb-operator.md) + + 参考信息 + + 配置 + - [集群配置](/tidb-in-kubernetes/reference/configuration/tidb-cluster.md) + - [备份配置](/tidb-in-kubernetes/reference/configuration/backup.md) + - [PV 配置](/tidb-in-kubernetes/reference/configuration/storage-class.md) + - [TiDB Drainer](/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) + + 工具 + - [tkctl](/tidb-in-kubernetes/reference/tools/tkctl.md) + - [相关工具使用](/tidb-in-kubernetes/reference/tools/in-kubernetes.md) + - [故障诊断](/tidb-in-kubernetes/troubleshoot.md) + - [常见问题](/tidb-in-kubernetes/faq.md) ++ 常见问题 (FAQ) + - [TiDB FAQ](/faq/tidb.md) + - [TiDB Lightning FAQ](/faq/tidb-lightning.md) + - [升级 FAQ](/faq/upgrade.md) ++ 技术支持 + - [支持渠道](/support-resources.md) + - [反馈问题](/report-issue.md) ++ [贡献](/contribute.md) + - [贡献代码](/contribute.md#成为-tidb-的贡献者) + - [改进文档](/contribute.md#改进文档) ++ [TiDB 路线图](/roadmap.md) ++ [版本发布历史](/releases/rn.md) + + v4.0 + - [4.0.0-beta](/releases/4.0.0-beta.md) + + v3.1 + - [3.1.0-beta.1](/releases/3.1.0-beta.1.md) + - [3.1.0-beta](/releases/3.1.0-beta.md) + + v3.0 + - [3.0.10](/releases/3.0.10.md) + - [3.0.9](/releases/3.0.9.md) + - [3.0.8](/releases/3.0.8.md) + - [3.0.7](/releases/3.0.7.md) + - [3.0.6](/releases/3.0.6.md) + - [3.0.5](/releases/3.0.5.md) + - [3.0.4](/releases/3.0.4.md) + - [3.0.3](/releases/3.0.3.md) + - [3.0.2](/releases/3.0.2.md) + - [3.0.1](/releases/3.0.1.md) + - [3.0 GA](/releases/3.0-ga.md) + - [3.0.0-rc.3](/releases/3.0.0-rc.3.md) + - [3.0.0-rc.2](/releases/3.0.0-rc.2.md) + - [3.0.0-rc.1](/releases/3.0.0-rc.1.md) + - [3.0.0-beta.1](/releases/3.0.0-beta.1.md) + - [3.0.0-beta](/releases/3.0beta.md) + + v2.1 + - [2.1.19](/releases/2.1.19.md) + - [2.1.18](/releases/2.1.18.md) + - [2.1.17](/releases/2.1.17.md) + - [2.1.16](/releases/2.1.16.md) + - [2.1.15](/releases/2.1.15.md) + - [2.1.14](/releases/2.1.14.md) + - [2.1.13](/releases/2.1.13.md) + - [2.1.12](/releases/2.1.12.md) + - [2.1.11](/releases/2.1.11.md) + - [2.1.10](/releases/2.1.10.md) + - [2.1.9](/releases/2.1.9.md) + - [2.1.8](/releases/2.1.8.md) + - [2.1.7](/releases/2.1.7.md) + - [2.1.6](/releases/2.1.6.md) + - [2.1.5](/releases/2.1.5.md) + - [2.1.4](/releases/2.1.4.md) + - [2.1.3](/releases/2.1.3.md) + - [2.1.2](/releases/2.1.2.md) + - [2.1.1](/releases/2.1.1.md) + - [2.1 GA](/releases/2.1ga.md) + - [2.1 RC5](/releases/21rc5.md) + - [2.1 RC4](/releases/21rc4.md) + - [2.1 RC3](/releases/21rc3.md) + - [2.1 RC2](/releases/21rc2.md) + - [2.1 RC1](/releases/21rc1.md) + - [2.1 Beta](/releases/21beta.md) + + v2.0 + - [2.0.11](/releases/2.0.11.md) + - [2.0.10](/releases/2.0.10.md) + - [2.0.9](/releases/209.md) + - [2.0.8](/releases/208.md) + - [2.0.7](/releases/207.md) + - [2.0.6](/releases/206.md) + - [2.0.5](/releases/205.md) + - [2.0.4](/releases/204.md) + - [2.0.3](/releases/203.md) + - [2.0.2](/releases/202.md) + - [2.0.1](/releases/201.md) + - [2.0](/releases/2.0ga.md) + - [2.0 RC5](/releases/2rc5.md) + - [2.0 RC4](/releases/2rc4.md) + - [2.0 RC3](/releases/2rc3.md) + - [2.0 RC1](/releases/2rc1.md) + - [1.1 Beta](/releases/11beta.md) + - [1.1 Alpha](/releases/11alpha.md) + + v1.0 + - [1.0](/releases/ga.md) + - [Pre-GA](/releases/prega.md) + - [RC4](/releases/rc4.md) + - [RC3](/releases/rc3.md) + - [RC2](/releases/rc2.md) + - [RC1](/releases/rc1.md) ++ [术语表](/glossary.md) diff --git a/_index.md b/_index.md index a118993c7f76..6711da8b498b 100755 --- a/_index.md +++ b/_index.md @@ -11,7 +11,7 @@ TiDB 具备如下特性： - 高度兼容 MySQL - [大多数情况下](/v3.0/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 + [大多数情况下](/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - 水平弹性扩展 @@ -33,7 +33,7 @@ TiDB 具备如下特性： TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，使部署、配置和维护变得十分简单。 -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v3.0/reference/tispark.md)来完成。 +TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/reference/tispark.md)来完成。 TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 @@ -47,10 +47,10 @@ TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间 TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： -- [使用 Ansible 部署](/v3.0/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v3.0/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 Docker Compose 部署](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v3.0/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 +- [使用 Ansible 部署](/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 +- [使用 Ansible 离线部署](/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 +- [使用 Docker Compose 部署](/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 +- [使用 Docker 部署](/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 ## 项目源码 diff --git a/architecture.md b/architecture.md new file mode 100644 index 000000000000..7dcbe72f59fe --- /dev/null +++ b/architecture.md @@ -0,0 +1,32 @@ +--- +title: TiDB 整体架构 +category: introduction +--- + +# TiDB 整体架构 + +要深入了解 TiDB 的水平扩展和高可用特点，首先需要了解 TiDB 的整体架构。TiDB 集群主要包括三个核心组件：TiDB Server，PD Server 和 TiKV Server。此外，还有用于解决用户复杂 OLAP 需求的 [TiSpark](https://github.com/pingcap/tispark/) 组件和简化云上部署管理的 [TiDB Operator](/tidb-in-kubernetes/tidb-operator-overview.md) 组件。 + +![TiDB Architecture](/media/tidb-architecture.png) + +## TiDB Server + +TiDB Server 负责接收 SQL 请求，处理 SQL 相关的逻辑，并通过 PD 找到存储计算所需数据的 TiKV 地址，与 TiKV 交互获取数据，最终返回结果。TiDB Server 是无状态的，其本身并不存储数据，只负责计算，可以无限水平扩展，可以通过负载均衡组件（如LVS、HAProxy 或 F5）对外提供统一的接入地址。 + +## PD Server + +Placement Driver (简称 PD) 是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。 + +PD 通过 Raft 协议保证数据的安全性。Raft 的 leader server 负责处理所有操作，其余的 PD server 仅用于保证高可用。建议部署奇数个 PD 节点。 + +## TiKV Server + +TiKV Server 负责存储数据，从外部看 TiKV 是一个分布式的提供事务的 Key-Value 存储引擎。存储数据的基本单位是 Region，每个 Region 负责存储一个 Key Range（从 StartKey 到 EndKey 的左闭右开区间）的数据，每个 TiKV 节点会负责多个 Region。TiKV 使用 Raft 协议做复制，保持数据的一致性和容灾。副本以 Region 为单位进行管理，不同节点上的多个 Region 构成一个 Raft Group，互为副本。数据在多个 TiKV 之间的负载均衡由 PD 调度，这里也是以 Region 为单位进行调度。 + +## TiSpark + +TiSpark 作为 TiDB 中解决用户复杂 OLAP 需求的主要组件，将 Spark SQL 直接运行在 TiDB 存储层上，同时融合 TiKV 分布式集群的优势，并融入大数据社区生态。至此，TiDB 可以通过一套系统，同时支持 OLTP 与 OLAP，免除用户数据同步的烦恼。 + +## TiDB Operator + +TiDB Operator 提供在主流云基础设施（Kubernetes）上部署管理 TiDB 集群的能力。它结合云原生社区的容器编排最佳实践与 TiDB 的专业运维知识，集成一键部署、多集群混部、自动运维、故障自愈等能力，极大地降低了用户使用和管理 TiDB 的门槛与成本。 diff --git a/dev/benchmark/add-index-with-load.md b/benchmark/add-index-with-load.md similarity index 100% rename from dev/benchmark/add-index-with-load.md rename to benchmark/add-index-with-load.md diff --git a/dev/benchmark/dm-v1.0-ga.md b/benchmark/dm-v1.0-ga.md similarity index 100% rename from dev/benchmark/dm-v1.0-ga.md rename to benchmark/dm-v1.0-ga.md diff --git a/benchmark/how-to-run-sysbench.md b/benchmark/how-to-run-sysbench.md new file mode 100644 index 000000000000..d6b7bab5934b --- /dev/null +++ b/benchmark/how-to-run-sysbench.md @@ -0,0 +1,277 @@ +--- +title: 如何用 Sysbench 测试 TiDB +category: benchmark +--- + +# 如何用 Sysbench 测试 TiDB + +本次测试使用的是 TiDB 3.0 Beta 和 Sysbench 1.0.14。建议使用 Sysbench 1.0 或之后的更新版本，可在 [Sysbench Release 1.0.14 页面](https://github.com/akopytov/sysbench/releases/tag/1.0.14)下载。 + +## 测试环境 + +- [硬件要求](/how-to/deploy/hardware-recommendations.md) + +- 参考 [TiDB 部署文档](/how-to/deploy/orchestrated/ansible.md)部署 TiDB 集群。在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD，和 1 个 TiKV 实例。关于磁盘，以 32 张表、每张表 10M 行数据为例，建议 TiKV 的数据目录所在的磁盘空间大于 512 GB。 + 对于单个 TiDB 的并发连接数，建议控制在 500 以内，如需增加整个系统的并发压力，可以增加 TiDB 实例，具体增加的 TiDB 个数视测试压力而定。 + +IDC 机器： + +| 类别 | 名称 | +|:---- |:---- | +| OS | Linux (CentOS 7.3.1611) | +| CPU | 40 vCPUs, Intel® Xeon® CPU E5-2630 v4 @ 2.20GHz | +| RAM | 128GB | +| DISK | Intel Optane SSD P4800X 375G * 1 | +| NIC | 10Gb Ethernet | + +## 测试方案 + +### TiDB 版本信息 + +| 组件 | GitHash | +|:---- |:---- | +| TiDB | 7a240818d19ae96e4165af9ea35df92466f59ce6 | +| TiKV | e26ceadcdfe94fb6ff83b5abb614ea3115394bcd | +| PD | 5e81548c3c1a1adab056d977e7767307a39ecb70 | + +### 集群拓扑 + +| 机器 IP | 部署实例 | +|:---- |:---- | +| 172.16.30.31 | 3*sysbench | +| 172.16.30.33 | 1\*tidb 1\*pd 1\*tikv | +| 172.16.30.34 | 1\*tidb 1\*pd 1\*tikv | +| 172.16.30.35 | 1\*tidb 1\*pd 1\*tikv | + +### TiDB 配置 + +升高日志级别，可以减少打印日志数量，对 TiDB 的性能有积极影响。开启 TiDB 配置中的 `prepared plan cache`，以减少优化执行计划的开销。具体在 TiDB 配置文件中加入： + +```toml +[log] +level = "error" +[prepared-plan-cache] +enabled = true +``` + +### TiKV 配置 + +升高 TiKV 的日志级别同样有利于提高性能表现。 + +由于 TiKV 是以集群形式部署的，在 Raft 算法的作用下，能保证大多数节点已经写入数据。因此，除了对数据安全极端敏感的场景之外，raftstore 中的 `sync-log` 选项可以关闭。 + +TiKV 集群存在两个 Column Family（Default CF 和 Write CF），主要用于存储不同类型的数据。对于 Sysbench 测试，导入数据的 Column Family 在 TiDB 集群中的比例是固定的。这个比例是： + +Default CF : Write CF = 4 : 1 + +在 TiKV 中需要根据机器内存大小配置 RocksDB 的 block cache，以充分利用内存。以 40 GB 内存的虚拟机部署一个 TiKV 为例，其 block cache 建议配置如下: + +```toml +log-level = "error" +[raftstore] +sync-log = false +[rocksdb.defaultcf] +block-cache-size = "24GB" +[rocksdb.writecf] +block-cache-size = "6GB" +``` + +对于 3.0 及以后的版本，还可以使用共享 block cache 的方式进行设置： + +```toml +log-level = "error" +[raftstore] +sync-log = false +[storage.block-cache] +capacity = "30GB" +``` + +更详细的 TiKV 参数调优请参考 [TiKV 性能参数调优](/reference/performance/tune-tikv.md)。 + +## 测试过程 + +> **注意：** +> +> 此次测试并没有使用如 HAproxy 等负载均衡工具。在 TiDB 单一节点上进行 Sysbench 测试，并把结果相加。负载均衡工具和不同版本参数也会影响性能表现。 + +### Sysbench 配置 + +以下为 Sysbench 配置文件样例： + +```txt +mysql-host={TIDB_HOST} +mysql-port=4000 +mysql-user=root +mysql-password=password +mysql-db=sbtest +time=600 +threads={8, 16, 32, 64, 128, 256} +report-interval=10 +db-driver=mysql +``` + +可根据实际需求调整其参数，其中 `TIDB_HOST` 为 TiDB server 的 IP 地址（配置文件中不能写多个地址），`threads` 为测试中的并发连接数，可在 “8, 16, 32, 64, 128, 256” 中调整，导入数据时，建议设置 threads = 8 或者 16。调整后，将该文件保存为名为 **config** 的文件。 + +**配置文件**参考示例如下： + +```txt +mysql-host=172.16.30.33 +mysql-port=4000 +mysql-user=root +mysql-password=password +mysql-db=sbtest +time=600 +threads=16 +report-interval=10 +db-driver=mysql +``` + +### 数据导入 + +在数据导入前，需要对 TiDB 进行简单设置。在 MySQL 客户端中执行如下命令： + +{{< copyable "sql" >}} + +```sql +set global tidb_disable_txn_auto_retry = off; +``` + +然后退出客户端。TiDB 使用乐观事务模型，当发现并发冲突时，会回滚事务。将 `tidb_disable_txn_auto_retry` 设置为 `off` 会开启事务冲突后的自动重试机制，可以尽可能避免事务冲突报错导致 Sysbench 程序退出的问题。 + +重新启动 MySQL 客户端执行以下 SQL 语句，创建数据库 `sbtest`： + +{{< copyable "sql" >}} + +```sql +create database sbtest; +``` + +调整 Sysbench 脚本创建索引的顺序。Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。该方式对于 TiDB 需要花费更多的导入时间。用户可以通过调整顺序来加速数据的导入。 + +假设用户使用的 [Sysbench](https://github.com/akopytov/sysbench/tree/1.0.14) 版本。我们可以通过以下两种方式来修改。 + +1. 直接下载为 TiDB 修改好的 [oltp_common.lua](https://raw.githubusercontent.com/pingcap/tidb-bench/master/sysbench/sysbench-patch/oltp_common.lua) 文件，覆盖 `/usr/share/sysbench/oltp_common.lua` 文件。 +2. 将 `/usr/share/sysbench/oltp_common.lua` 的第 [235](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L235) 行到第 [240](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L240) 行移动到第 198 行以后。 + +> **注意：** +> +> 此操作为可选操作，仅节约了数据导入时间。 + +命令行输入以下命令，开始导入数据，config 文件为上一步中配置的文件： + +{{< copyable "shell-regular" >}} + +```bash +sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 prepare +``` + +### 数据预热与统计信息收集 + +数据预热可将磁盘中的数据载入内存的 block cache 中，预热后的数据对系统整体的性能有较大的改善，建议在每次重启集群后进行一次数据预热。 + +Sysbench 1.0.14 没有提供数据预热的功能，因此需要手动进行数据预热。如果使用更新的 Sysbench 版本，可以使用自带的预热功能。 + +以 Sysbench 中某张表 sbtest7 为例，执行如下 SQL 语句 进行数据预热： + +{{< copyable "sql" >}} + +```sql +SELECT COUNT(pad) FROM sbtest7 USE INDEX (k_7); +``` + +统计信息收集有助于优化器选择更为准确的执行计划，可以通过 `analyze` 命令来收集表 sbtest 的统计信息，每个表都需要统计。 + +{{< copyable "sql" >}} + +```sql +ANALYZE TABLE sbtest7; +``` + +### Point select 测试命令 + +{{< copyable "shell-regular" >}} + +```bash +sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 run +``` + +### Update index 测试命令 + +{{< copyable "shell-regular" >}} + +```bash +sysbench --config-file=config oltp_update_index --tables=32 --table-size=10000000 run +``` + +### Read-only 测试命令 + +{{< copyable "shell-regular" >}} + +```bash +sysbench --config-file=config oltp_read_only --tables=32 --table-size=10000000 run +``` + +## 测试结果 + +测试了数据 32 表，每表有 10M 数据。 + +对每个 tidb-server 进行了 Sysbench 测试，将结果相加，得出最终结果： + +### oltp_point_select + +| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | +|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | +| point_select | 3\*8 | 67502.55 | 67502.55 | 0.36 | 0.42 | 141.92 | +| point_select | 3\*16 | 120141.84 | 120141.84 | 0.40 | 0.52 | 20.99 | +| point_select | 3\*32 | 170142.92 | 170142.92 | 0.58 | 0.99 | 28.08 | +| point_select | 3\*64 | 195218.54 | 195218.54 | 0.98 | 2.14 | 21.82 | +| point_select | 3\*128 | 208189.53 | 208189.53 | 1.84 | 4.33 | 31.02 | + +![oltp_point_select](/media/oltp_point_select.png) + +### oltp_update_index + +| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | +|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | +| oltp_update_index | 3\*8 | 9668.98 | 9668.98 | 2.51 | 3.19 | 103.88| +| oltp_update_index | 3\*16 | 12834.99 | 12834.99 | 3.79 | 5.47 | 176.90 | +| oltp_update_index | 3\*32 | 15955.77 | 15955.77 | 6.07 | 9.39 | 4787.14 | +| oltp_update_index | 3\*64 | 18697.17 | 18697.17 | 10.34 | 17.63 | 4539.04 | +| oltp_update_index | 3\*128 | 20446.81 | 20446.81 | 18.98 | 40.37 | 5394.75 | +| oltp_update_index | 3\*256 | 23563.03 | 23563.03 | 32.86 | 78.60 | 5530.69 | + +![oltp_update_index](/media/oltp_update_index.png) + +### oltp_read_only + +| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | +|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | +| oltp_read_only | 3\*8 | 2411.00 | 38575.96 | 9.92 | 20.00 | 92.23 | +| oltp_read_only | 3\*16 | 3873.53 | 61976.50 | 12.25 | 16.12 | 56.94 | +| oltp_read_only | 3\*32 | 5066.88 | 81070.16 | 19.42 | 26.20 | 123.41 | +| oltp_read_only | 3\*64 | 5466.36 | 87461.81 | 34.65 | 63.20 | 231.19 | +| oltp_read_only | 3\*128 | 6684.16 | 106946.59 | 57.29 | 97.55 | 180.85 | + +![oltp_read_only](/media/oltp_read_only.png) + +## 常见问题 + +### 在高并发压力下，TiDB、TiKV 的配置都合理，为什么整体性能还是偏低？ + +这种情况可能与使用了 proxy 有关。可以尝试直接对单个 TiDB 加压，将求和后的结果与使用 proxy 的情况进行对比。 + +以 HAproxy 为例。`nbproc` 参数可以增加其最大启动的进程数，较新版本的 HAproxy 还支持 `nbthread` 和 `cpu-map` 等。这些都可以减少对其性能的不利影响。 + +### 在高并发压力下，为什么 TiKV 的 CPU 利用率依然很低？ + +TiKV 虽然整体 CPU 偏低，但部分模块的 CPU 可能已经达到了很高的利用率。 + +TiKV 的其他模块，如 storage readpool、coprocessor 和 gRPC 的最大并发度限制是可以通过 TiKV 的配置文件进行调整的。 + +通过 Grafana 的 TiKV Thread CPU 监控面板可以观察到其实际使用率。如出现多线程模块瓶颈，可以通过增加该模块并发度进行调整。 + +### 在高并发压力下，TiKV 也未达到 CPU 使用瓶颈，为什么 TiDB 的 CPU 利用率依然很低？ + +在某些高端设备上，使用的是 NUMA 架构的 CPU，跨 CPU 访问远端内存将极大降低性能。TiDB 默认将使用服务器所有 CPU，goroutine 的调度不可避免地会出现跨 CPU 内存访问。 + +因此，建议在 NUMA 架构服务器上，部署 *n* 个 TiDB（*n* = NUMA CPU 的个数），同时将 TiDB 的 `max-procs` 变量的值设置为与 NUMA CPU 的核数相同。 diff --git a/benchmark/how-to-run-tpcc.md b/benchmark/how-to-run-tpcc.md new file mode 100644 index 000000000000..449e37363beb --- /dev/null +++ b/benchmark/how-to-run-tpcc.md @@ -0,0 +1,258 @@ +--- +title: 如何对 TiDB 进行 TPC-C 测试 +category: benchmark +--- + +# 如何对 TiDB 进行 TPC-C 测试 + +本文介绍如何对 TiDB 进行 [TPC-C](http://www.tpc.org/tpcc/) 测试。 + +## 准备测试程序 + +TPC-C 是一个对 OLTP（联机交易处理）系统进行测试的规范，使用一个商品销售模型对 OLTP 系统进行测试，其中包含五类事务： + +* NewOrder – 新订单的生成 +* Payment – 订单付款 +* OrderStatus – 最近订单查询 +* Delivery – 配送 +* StockLevel – 库存缺货状态分析 + +在测试开始前，TPC-C Benchmark 规定了数据库的初始状态，也就是数据库中数据生成的规则，其中 ITEM 表中固定包含 10 万种商品，仓库的数量可进行调整，假设 WAREHOUSE 表中有 W 条记录，那么： + +* STOCK 表中应有 W \* 10 万条记录（每个仓库对应 10 万种商品的库存数据） +* DISTRICT 表中应有 W \* 10 条记录（每个仓库为 10 个地区提供服务） +* CUSTOMER 表中应有 W \* 10 \* 3000 条记录（每个地区有 3000 个客户） +* HISTORY 表中应有 W \* 10 \* 3000 条记录（每个客户一条交易历史） +* ORDER 表中应有 W \* 10 \* 3000 条记录（每个地区 3000 个订单），并且最后生成的 900 个订单被添加到 NEW-ORDER 表中，每个订单随机生成 5 ~ 15 条 ORDER-LINE 记录。 + +我们将以 1000 WAREHOUSE 为例进行测试。 + +TPC-C 使用 tpmC 值（Transactions per Minute）来衡量系统最大有效吞吐量 (MQTh, Max Qualified Throughput)，其中 Transactions 以 NewOrder Transaction 为准，即最终衡量单位为每分钟处理的新订单数。 + +本文使用开源的 BenchmarkSQL 5.0 作为 TPC-C 测试实现并添加了对 MySQL 协议的支持，可以通过以下命令下载测试程序: + +{{< copyable "shell-regular" >}} + +```shell +git clone -b 5.0-mysql-support-opt-2.1 https://github.com/pingcap/benchmarksql.git +``` + +安装 java 和 ant，以 CentOS 为例，可以执行以下命令进行安装 + +{{< copyable "shell-regular" >}} + +```shell +sudo yum install -y java ant +``` + +进入 benchmarksql 目录并执行 ant 构建 + +{{< copyable "shell-regular" >}} + +```shell +cd benchmarksql +ant +``` + +## 部署 TiDB 集群 + +对于 1000 WAREHOUSE 我们将在 3 台服务器上部署集群。 + +在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD 和 1 个 TiKV 实例。 + +比如这里采用的机器硬件配置是： + +| 类别 | 名称 | +| :-: | :-: | +| OS | Linux (CentOS 7.3.1611) | +| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | +| RAM | 128GB | +| DISK | Optane 500GB SSD | + +因为该型号 CPU 是 NUMA 架构，建议先用 `taskset` 进行绑核，首先用 `lscpu` 查看 NUMA node，比如： + +```text +NUMA node0 CPU(s): 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 +NUMA node1 CPU(s): 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 +``` + +之后可以通过下面的命令来启动 TiDB： + +{{< copyable "shell-regular" >}} + +```shell +nohup taskset -c 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 bin/tidb-server && \ +nohup taskset -c 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 bin/tidb-server +``` + +最后，可以选择部署一个 HAproxy 来进行多个 TiDB node 的负载均衡，推荐配置 nbproc 为 CPU 核数。 + +## 配置调整 + +### TiDB 配置 + +```toml +[log] +level = "error" + +[performance] +# 根据 NUMA 配置，设置单个 TiDB 最大使用的 CPU 核数 +max-procs = 20 + +[prepared_plan_cache] +# 开启 TiDB 配置中的 prepared plan cache，以减少优化执行计划的开销 +enabled = true +``` + +### TiKV 配置 + +开始可以使用基本的配置，压测运行后可以通过观察 Grafana 并参考 [TiKV 调优说明](/reference/performance/tune-tikv.md)进行调整。 + +### BenchmarkSQL 配置 + +修改 `benchmarksql/run/props.mysql`： + +```text +conn=jdbc:mysql://{HAPROXY-HOST}:{HAPROXY-PORT}/tpcc?useSSL=false&useServerPrepStmts=true&useConfigs=maxPerformance +warehouses=1000 # 使用 1000 个 warehouse +terminals=500 # 使用 500 个终端 +loadWorkers=32 # 导入数据的并发数 +``` + +## 导入数据 + +**导入数据通常是整个 TPC-C 测试中最耗时，也是最容易出问题的阶段。** + +首先用 MySQL 客户端连接到 TiDB-Server 并执行： + +{{< copyable "sql" >}} + +```sql +create database tpcc +``` + +之后在 shell 中运行 BenchmarkSQL 建表脚本： + +{{< copyable "shell-regular" >}} + +```shell +cd run && \ +./runSQL.sh props.mysql sql.mysql/tableCreates.sql && \ +./runSQL.sh props.mysql sql.mysql/indexCreates.sql +``` + +### 直接使用 BenchmarkSQL 导入 + +运行导入数据脚本： + +{{< copyable "shell-regular" >}} + +```shell +./runLoader.sh props.mysql +``` + +根据机器配置这个过程可能会持续几个小时。 + +### 通过 TiDB Lightning 导入 + +由于导入数据量随着 warehouse 的增加而增加，当需要导入 1000 warehouse 以上数据时，可以先用 BenchmarkSQL 生成 csv 文件，再将文件通过 TiDB Lightning（以下简称 Lightning）导入的方式来快速导入。生成的 csv 文件也可以多次复用，节省每次生成所需要的时间。 + +#### 修改 BenchmarkSQL 的配置文件 + +1 warehouse 的 csv 文件需要 77 MB 磁盘空间，在生成之前要根据需要分配足够的磁盘空间来保存 csv 文件。可以在 `benchmarksql/run/props.mysql` 文件中增加一行： + +```text +fileLocation=/home/user/csv/ # 存储 csv 文件的目录绝对路径，需保证有足够的空间 +``` + +因为最终要使用 Lightning 导入数据，所以 csv 文件名最好符合 Lightning 要求，即 `{database}.{table}.csv` 的命名法。这里可以将以上配置改为： + +```text +fileLocation=/home/user/csv/tpcc. # 存储 csv 文件的目录绝对路径 + 文件名前缀（database） +``` + +这样生成的 csv 文件名将会是类似 `tpcc.bmsql_warehouse.csv` 的样式，符合 Lightning 的要求。 + +#### 生成 csv 文件 + +{{< copyable "shell-regular" >}} + +```shell +./runLoader.sh props.mysql +``` + +#### 通过 Lightning 导入 + +通过 Lightning 导入数据请参考 [Lightning 部署执行](/reference/tools/tidb-lightning/deployment.md)章节。这里我们介绍下通过 tidb-ansible 部署 Lightning 导入数据的方法。 + +##### 修改 inventory.ini + +这里最好手动指定清楚部署的 IP、端口、目录，避免各种冲突问题带来的异常，其中 import_dir 的磁盘空间参考 [Lightning 部署执行](/reference/tools/tidb-lightning/deployment.md)，data_source_dir 就是存储上一节 csv 数据的目录。 + +```ini +[importer_server] +IS1 ansible_host=172.16.5.34 deploy_dir=/data2/is1 tikv_importer_port=13323 import_dir=/data2/import + +[lightning_server] +LS1 ansible_host=172.16.5.34 deploy_dir=/data2/ls1 tidb_lightning_pprof_port=23323 data_source_dir=/home/user/csv +``` + +##### 修改 conf/tidb-lightning.yml + +```yaml +mydumper: + no-schema: true + csv: + separator: ',' + delimiter: '' + header: false + not-null: false + 'null': 'NULL' + backslash-escape: true + trim-last-separator: false +``` + +##### 部署 Lightning 和 Importer + +{{< copyable "shell-regular" >}} + +```shell +ansible-playbook deploy.yml --tags=lightning +``` + +##### 启动 + +* 登录到部署 Lightning 和 Importer 的服务器 +* 进入部署目录 +* 在 Importer 目录下执行 `scripts/start_importer.sh`，启动 Importer +* 在 Lightning 目录下执行 `scripts/start_lightning.sh`，开始导入数据 + +由于是用 ansible 进行部署的，可以在监控页面看到 Lightning 的导入进度，或者通过日志查看导入是否结束。 + +### 导入完成后 + +数据导入完成之后，可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句都返回结果为空，即为数据导入正确。 + +## 运行测试 + +执行 BenchmarkSQL 测试脚本： + +{{< copyable "shell-regular" >}} + +```shell +nohup ./runBenchmark.sh props.mysql &> test.log & +``` + +运行结束后通过 `test.log` 查看结果： + +```text +07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmC (NewOrders) = 77373.25 +07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmTOTAL = 171959.88 +07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Session Start = 2019-03-21 07:07:52 +07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Session End = 2019-03-21 07:09:53 +07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Transaction Count = 345240 +``` + +tpmC 部分即为测试结果。 + +测试完成之后，也可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句的返回结果都为空，即为数据测试过程正确。 diff --git a/dev/benchmark/sysbench-in-k8s.md b/benchmark/sysbench-in-k8s.md similarity index 100% rename from dev/benchmark/sysbench-in-k8s.md rename to benchmark/sysbench-in-k8s.md diff --git a/dev/benchmark/sysbench-v2.md b/benchmark/sysbench-v2.md similarity index 100% rename from dev/benchmark/sysbench-v2.md rename to benchmark/sysbench-v2.md diff --git a/dev/benchmark/sysbench-v3.md b/benchmark/sysbench-v3.md similarity index 100% rename from dev/benchmark/sysbench-v3.md rename to benchmark/sysbench-v3.md diff --git a/dev/benchmark/sysbench-v4.md b/benchmark/sysbench-v4.md similarity index 100% rename from dev/benchmark/sysbench-v4.md rename to benchmark/sysbench-v4.md diff --git a/dev/benchmark/sysbench.md b/benchmark/sysbench.md similarity index 100% rename from dev/benchmark/sysbench.md rename to benchmark/sysbench.md diff --git a/dev/benchmark/tpcc.md b/benchmark/tpcc.md similarity index 100% rename from dev/benchmark/tpcc.md rename to benchmark/tpcc.md diff --git a/dev/benchmark/tpch-v2.md b/benchmark/tpch-v2.md similarity index 100% rename from dev/benchmark/tpch-v2.md rename to benchmark/tpch-v2.md diff --git a/dev/benchmark/tpch.md b/benchmark/tpch.md similarity index 100% rename from dev/benchmark/tpch.md rename to benchmark/tpch.md diff --git a/dev/contribute.md b/contribute.md similarity index 100% rename from dev/contribute.md rename to contribute.md diff --git a/dev/TOC.md b/dev/TOC.md deleted file mode 100644 index 5166bc4cef18..000000000000 --- a/dev/TOC.md +++ /dev/null @@ -1,490 +0,0 @@ -# TiDB 中文用户文档 - - - - -## 目录 - -+ 关于 TiDB - - [TiDB 简介](/dev/overview.md) - + Benchmark 测试 - - [如何用 Sysbench 测试 TiDB](/dev/benchmark/how-to-run-sysbench.md) - - [如何对 TiDB 进行 TPC-C 测试](/dev/benchmark/how-to-run-tpcc.md) - - [Sysbench 性能对比 - v3.0 对比 v2.1](/dev/benchmark/sysbench-v4.md) - - [TPC-C 性能对比 - v3.0 对比 v2.1](/dev/benchmark/tpcc.md) - - [线上负载与 `Add Index` 相互影响测试](/dev/benchmark/add-index-with-load.md) - - [TiDB in Kubernetes Sysbench 性能测试](/dev/benchmark/sysbench-in-k8s.md) - - [DM 1.0-GA 性能测试](/dev/benchmark/dm-v1.0-ga.md) -+ 主要概念 - - [整体架构](/dev/architecture.md) - + 核心特性 - - [水平扩展](/dev/key-features.md#水平扩展) - - [高可用](/dev/key-features.md#高可用) -+ 操作指南 - + 快速上手 - - [使用 Docker Compose 部署 TiDB](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md) - - [SQL 基本操作](/dev/how-to/get-started/explore-sql.md) - - [读取历史数据](/dev/how-to/get-started/read-historical-data.md) - - [TiDB Binlog 教程](/dev/how-to/get-started/tidb-binlog.md) - - [TiDB Data Migration 教程](/dev/how-to/get-started/data-migration.md) - - [TiDB Lightning 教程](/dev/how-to/get-started/tidb-lightning.md) - - [TiSpark 教程](/dev/how-to/get-started/tispark.md) - + 部署 - - [软硬件环境需求](/dev/how-to/deploy/hardware-recommendations.md) - + 集群部署方式 - - [使用 Ansible 部署（推荐）](/dev/how-to/deploy/orchestrated/ansible.md) - - [使用 Ansible 离线部署](/dev/how-to/deploy/orchestrated/offline-ansible.md) - - [使用 Docker 部署](/dev/how-to/deploy/orchestrated/docker.md) - + 跨地域冗余 - - [跨数据中心部署方案](/dev/how-to/deploy/geographic-redundancy/overview.md) - - [配置集群拓扑](/dev/how-to/deploy/geographic-redundancy/location-awareness.md) - - [使用 Ansible 部署 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md) - + 配置 - - [时区](/dev/how-to/configure/time-zone.md) - - [内存控制](/dev/how-to/configure/memory-control.md) - + 安全 - + 安全传输层协议 (TLS) - - [为 MySQL 客户端开启 TLS](/dev/how-to/secure/enable-tls-clients.md) - - [为 TiDB 组件间开启 TLS](/dev/how-to/secure/enable-tls-between-components.md) - - [生成自签名证书](/dev/how-to/secure/generate-self-signed-certificates.md) - + 监控 - - [概述](/dev/how-to/monitor/overview.md) - - [监控 TiDB 集群](/dev/how-to/monitor/monitor-a-cluster.md) - + 迁移 - - [迁移工具使用指南](/dev/reference/tools/user-guide.md) - + 从 MySQL 迁移 - - [以 Amazon Aurora MySQL 为例](/dev/how-to/migrate/from-mysql-aurora.md) - - [从 CSV 迁移](/dev/reference/tools/tidb-lightning/csv.md) - + 运维 - - [Ansible 常见运维操作](/dev/how-to/maintain/ansible-operations.md) - + 备份与恢复 - - [使用 Mydumper/TiDB Lightning 进行备份与恢复](/dev/how-to/maintain/backup-and-restore/mydumper-lightning.md) - - [使用 BR 进行备份与恢复](/dev/reference/tools/br/br.md) - - [BR 备份与恢复场景示例](/dev/reference/tools/br/use-cases.md) - + 定位异常查询 - - [定位慢查询](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) - - [定位消耗系统资源多的查询](/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md) - + 扩容缩容 - - [使用 Ansible 扩容缩容](/dev/how-to/scale/with-ansible.md) - + 升级 - - [升级至最新开发版](/dev/how-to/upgrade/from-previous-version.md) - + 故障诊断 - - [集群配置诊断](/dev/how-to/troubleshoot/cluster-setup.md) - - [TiDB Lightning 故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md) -+ 参考手册 - + SQL - - [与 MySQL 兼容性对比](/dev/reference/mysql-compatibility.md) - + SQL 语言结构 - - [字面值](/dev/reference/sql/language-structure/literal-values.md) - - [Schema 对象名](/dev/reference/sql/language-structure/schema-object-names.md) - - [关键字和保留字](/dev/reference/sql/language-structure/keywords-and-reserved-words.md) - - [用户自定义变量](/dev/reference/sql/language-structure/user-defined-variables.md) - - [表达式语法](/dev/reference/sql/language-structure/expression-syntax.md) - - [注释语法](/dev/reference/sql/language-structure/comment-syntax.md) - + 数据类型 - - [概述](/dev/reference/sql/data-types/overview.md) - - [默认值](/dev/reference/sql/data-types/default-values.md) - + 数值类型 - - [`BIT`](/dev/reference/sql/data-types/numeric.md#bit-类型) - - [`BOOL|BOOLEAN`](/dev/reference/sql/data-types/numeric.md#boolean-类型) - - [`TINYINT`](/dev/reference/sql/data-types/numeric.md#tinyint-类型) - - [`SMALLINT`](/dev/reference/sql/data-types/numeric.md#smallint-类型) - - [`MEDIUMINT`](/dev/reference/sql/data-types/numeric.md#mediumint-类型) - - [`INT|INTEGER`](/dev/reference/sql/data-types/numeric.md#integer-类型) - - [`BIGINT`](/dev/reference/sql/data-types/numeric.md#bigint-类型) - - [`DECIMAL`](/dev/reference/sql/data-types/numeric.md#decimal-类型) - - [`FLOAT`](/dev/reference/sql/data-types/numeric.md#float-类型) - - [`DOUBLE`](/dev/reference/sql/data-types/numeric.md#double-类型) - + 日期和时间类型 - - [`DATE`](/dev/reference/sql/data-types/date-and-time.md#date-类型) - - [`DATETIME`](/dev/reference/sql/data-types/date-and-time.md#datetime-类型) - - [`TIMESTAMP`](/dev/reference/sql/data-types/date-and-time.md#timestamp-类型) - - [`TIME`](/dev/reference/sql/data-types/date-and-time.md#time-类型) - - [`YEAR`](/dev/reference/sql/data-types/date-and-time.md#year-类型) - + 字符串类型 - - [`CHAR`](/dev/reference/sql/data-types/string.md#char-类型) - - [`VARCHAR`](/dev/reference/sql/data-types/string.md#varchar-类型) - - [`TEXT`](/dev/reference/sql/data-types/string.md#text-类型) - - [`LONGTEXT`](/dev/reference/sql/data-types/string.md#longtext-类型) - - [`BINARY`](/dev/reference/sql/data-types/string.md#binary-类型) - - [`VARBINARY`](/dev/reference/sql/data-types/string.md#varbinary-类型) - - [`TINYBLOB`](/dev/reference/sql/data-types/string.md#tinyblob-类型) - - [`BLOB`](/dev/reference/sql/data-types/string.md#blob-类型) - - [`MEDIUMBLOB`](/dev/reference/sql/data-types/string.md#mediumblob-类型) - - [`LONGBLOB`](/dev/reference/sql/data-types/string.md#longblob-类型) - - [`ENUM`](/dev/reference/sql/data-types/string.md#enum-类型) - - [`SET`](/dev/reference/sql/data-types/string.md#set-类型) - - [JSON Type](/dev/reference/sql/data-types/json.md) - + 函数与操作符 - - [函数与操作符概述](/dev/reference/sql/functions-and-operators/reference.md) - - [表达式求值的类型转换](/dev/reference/sql/functions-and-operators/type-conversion.md) - - [操作符](/dev/reference/sql/functions-and-operators/operators.md) - - [控制流程函数](/dev/reference/sql/functions-and-operators/control-flow-functions.md) - - [字符串函数](/dev/reference/sql/functions-and-operators/string-functions.md) - - [数值函数与操作符](/dev/reference/sql/functions-and-operators/numeric-functions-and-operators.md) - - [日期和时间函数](/dev/reference/sql/functions-and-operators/date-and-time-functions.md) - - [位函数和操作符](/dev/reference/sql/functions-and-operators/bit-functions-and-operators.md) - - [Cast 函数和操作符](/dev/reference/sql/functions-and-operators/cast-functions-and-operators.md) - - [加密和压缩函数](/dev/reference/sql/functions-and-operators/encryption-and-compression-functions.md) - - [信息函数](/dev/reference/sql/functions-and-operators/information-functions.md) - - [JSON 函数](/dev/reference/sql/functions-and-operators/json-functions.md) - - [GROUP BY 聚合函数](/dev/reference/sql/functions-and-operators/aggregate-group-by-functions.md) - - [窗口函数](/dev/reference/sql/functions-and-operators/window-functions.md) - - [其它函数](/dev/reference/sql/functions-and-operators/miscellaneous-functions.md) - - [精度数学](/dev/reference/sql/functions-and-operators/precision-math.md) - - [下推到 TiKV 的表达式列表](/dev/reference/sql/functions-and-operators/expressions-pushed-down.md) - + SQL 语句 - - [`ADD COLUMN`](/dev/reference/sql/statements/add-column.md) - - [`ADD INDEX`](/dev/reference/sql/statements/add-index.md) - - [`ADMIN`](/dev/reference/sql/statements/admin.md) - - [`ALTER DATABASE`](/dev/reference/sql/statements/alter-database.md) - - [`ALTER TABLE`](/dev/reference/sql/statements/alter-table.md) - - [`ALTER USER`](/dev/reference/sql/statements/alter-user.md) - - [`ANALYZE TABLE`](/dev/reference/sql/statements/analyze-table.md) - - [`BEGIN`](/dev/reference/sql/statements/begin.md) - - [`COMMIT`](/dev/reference/sql/statements/commit.md) - - [`CREATE DATABASE`](/dev/reference/sql/statements/create-database.md) - - [`CREATE INDEX`](/dev/reference/sql/statements/create-index.md) - - [`CREATE TABLE LIKE`](/dev/reference/sql/statements/create-table-like.md) - - [`CREATE TABLE`](/dev/reference/sql/statements/create-table.md) - - [`CREATE USER`](/dev/reference/sql/statements/create-user.md) - - [`CREATE VIEW`](/dev/reference/sql/statements/create-view.md) - - [`DEALLOCATE`](/dev/reference/sql/statements/deallocate.md) - - [`DELETE`](/dev/reference/sql/statements/delete.md) - - [`DESC`](/dev/reference/sql/statements/desc.md) - - [`DESCRIBE`](/dev/reference/sql/statements/describe.md) - - [`DO`](/dev/reference/sql/statements/do.md) - - [`DROP COLUMN`](/dev/reference/sql/statements/drop-column.md) - - [`DROP DATABASE`](/dev/reference/sql/statements/drop-database.md) - - [`DROP INDEX`](/dev/reference/sql/statements/drop-index.md) - - [`DROP TABLE`](/dev/reference/sql/statements/drop-table.md) - - [`DROP USER`](/dev/reference/sql/statements/drop-user.md) - - [`DROP VIEW`](/dev/reference/sql/statements/drop-view.md) - - [`EXECUTE`](/dev/reference/sql/statements/execute.md) - - [`EXPLAIN ANALYZE`](/dev/reference/sql/statements/explain-analyze.md) - - [`EXPLAIN`](/dev/reference/sql/statements/explain.md) - - [`FLUSH PRIVILEGES`](/dev/reference/sql/statements/flush-privileges.md) - - [`FLUSH STATUS`](/dev/reference/sql/statements/flush-status.md) - - [`FLUSH TABLES`](/dev/reference/sql/statements/flush-tables.md) - - [`GRANT `](/dev/reference/sql/statements/grant-privileges.md) - - [`INSERT`](/dev/reference/sql/statements/insert.md) - - [`KILL [TIDB]`](/dev/reference/sql/statements/kill.md) - - [`LOAD DATA`](/dev/reference/sql/statements/load-data.md) - - [`MODIFY COLUMN`](/dev/reference/sql/statements/modify-column.md) - - [`PREPARE`](/dev/reference/sql/statements/prepare.md) - - [`RECOVER TABLE`](/dev/reference/sql/statements/recover-table.md) - - [`RENAME INDEX`](/dev/reference/sql/statements/rename-index.md) - - [`RENAME TABLE`](/dev/reference/sql/statements/rename-table.md) - - [`REPLACE`](/dev/reference/sql/statements/replace.md) - - [`REVOKE `](/dev/reference/sql/statements/revoke-privileges.md) - - [`ROLLBACK`](/dev/reference/sql/statements/rollback.md) - - [`SELECT`](/dev/reference/sql/statements/select.md) - - [`SET [NAMES|CHARACTER SET]`](/dev/reference/sql/statements/set-names.md) - - [`SET PASSWORD`](/dev/reference/sql/statements/set-password.md) - - [`SET TRANSACTION`](/dev/reference/sql/statements/set-transaction.md) - - [`SET [GLOBAL|SESSION] `](/dev/reference/sql/statements/set-variable.md) - - [`SHOW CHARACTER SET`](/dev/reference/sql/statements/show-character-set.md) - - [`SHOW COLLATION`](/dev/reference/sql/statements/show-collation.md) - - [`SHOW [FULL] COLUMNS FROM`](/dev/reference/sql/statements/show-columns-from.md) - - [`SHOW CREATE TABLE`](/dev/reference/sql/statements/show-create-table.md) - - [`SHOW CREATE USER`](/dev/reference/sql/statements/show-create-user.md) - - [`SHOW DATABASES`](/dev/reference/sql/statements/show-databases.md) - - [`SHOW ENGINES`](/dev/reference/sql/statements/show-engines.md) - - [`SHOW ERRORS`](/dev/reference/sql/statements/show-errors.md) - - [`SHOW [FULL] FIELDS FROM`](/dev/reference/sql/statements/show-fields-from.md) - - [`SHOW GRANTS`](/dev/reference/sql/statements/show-grants.md) - - [`SHOW INDEXES [FROM|IN]`](/dev/reference/sql/statements/show-indexes.md) - - [`SHOW INDEX [FROM|IN]`](/dev/reference/sql/statements/show-index.md) - - [`SHOW KEYS [FROM|IN]`](/dev/reference/sql/statements/show-keys.md) - - [`SHOW PRIVILEGES`](/dev/reference/sql/statements/show-privileges.md) - - [`SHOW [FULL] PROCESSSLIST`](/dev/reference/sql/statements/show-processlist.md) - - [`SHOW SCHEMAS`](/dev/reference/sql/statements/show-schemas.md) - - [`SHOW [FULL] TABLES`](/dev/reference/sql/statements/show-tables.md) - - [`SHOW TABLE REGIONS`](/dev/reference/sql/statements/show-table-regions.md) - - [`SHOW TABLE STATUS`](/dev/reference/sql/statements/show-table-status.md) - - [`SHOW [GLOBAL|SESSION] VARIABLES`](/dev/reference/sql/statements/show-variables.md) - - [`SHOW WARNINGS`](/dev/reference/sql/statements/show-warnings.md) - - [`SPLIT REGION`](/dev/reference/sql/statements/split-region.md) - - [`START TRANSACTION`](/dev/reference/sql/statements/start-transaction.md) - - [`TRACE`](/dev/reference/sql/statements/trace.md) - - [`TRUNCATE`](/dev/reference/sql/statements/truncate.md) - - [`UPDATE`](/dev/reference/sql/statements/update.md) - - [`USE`](/dev/reference/sql/statements/use.md) - - [约束](/dev/reference/sql/constraints.md) - - [生成列](/dev/reference/sql/generated-columns.md) - - [分区表](/dev/reference/sql/partitioning.md) - - [字符集](/dev/reference/sql/character-set.md) - - [SQL 模式](/dev/reference/sql/sql-mode.md) - - [视图](/dev/reference/sql/view.md) - + 配置 - + tidb-server - - [MySQL 系统变量](/dev/reference/configuration/tidb-server/mysql-variables.md) - - [TiDB 特定系统变量](/dev/reference/configuration/tidb-server/tidb-specific-variables.md) - - [配置参数](/dev/reference/configuration/tidb-server/configuration.md) - - [配置文件描述](/dev/reference/configuration/tidb-server/configuration-file.md) - + pd-server - - [配置参数](/dev/reference/configuration/pd-server/configuration.md) - - [配置文件描述](/dev/reference/configuration/pd-server/configuration-file.md) - + tikv-server - - [配置参数](/dev/reference/configuration/tikv-server/configuration.md) - - [配置文件描述](/dev/reference/configuration/tikv-server/configuration-file.md) - + 安全 - - [与 MySQL 的安全特性差异](/dev/reference/security/compatibility.md) - - [TiDB 数据库权限管理](/dev/reference/security/privilege-system.md) - - [TiDB 用户账户管理](/dev/reference/security/user-account-management.md) - - [基于角色的访问控制](/dev/reference/security/role-based-access-control.md) - - [TiDB 证书鉴权使用指南](/dev/reference/security/cert-based-authentication.md) - + 事务 - - [事务概览](/dev/reference/transactions/overview.md) - - [隔离级别](/dev/reference/transactions/transaction-isolation.md) - - [乐观事务](/dev/reference/transactions/transaction-optimistic.md) - - [悲观事务](/dev/reference/transactions/transaction-pessimistic.md) - + 系统数据库 - - [`mysql`](/dev/reference/system-databases/mysql.md) - - [`information_schema`](/dev/reference/system-databases/information-schema.md) - - [错误码](/dev/reference/error-codes.md) - - [支持的连接器和 API](/dev/reference/supported-clients.md) - + 垃圾回收 (GC) - - [GC 机制简介](/dev/reference/garbage-collection/overview.md) - - [GC 配置](/dev/reference/garbage-collection/configuration.md) - + 性能调优 - - [SQL 优化流程](/dev/reference/performance/sql-optimizer-overview.md) - - [理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md) - - [执行计划绑定](/dev/reference/performance/execution-plan-bind.md) - - [统计信息概述](/dev/reference/performance/statistics.md) - - [Optimizer Hints](/dev/reference/performance/optimizer-hints.md) - - [Follower Read](/dev/reference/performance/follower-read.md) - - [使用 SQL 语句检查 TiDB 集群状态](/dev/reference/performance/check-cluster-status-using-sql-statements.md) - - [Statement Summary Table](/dev/reference/performance/statement-summary.md) - - [TiKV 调优](/dev/reference/performance/tune-tikv.md) - - [TiDB 最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/) - + 监控指标 - - [Overview 面板](/dev/reference/key-monitoring-metrics/overview-dashboard.md) - - [TiDB 面板](/dev/reference/key-monitoring-metrics/tidb-dashboard.md) - - [PD 面板](/dev/reference/key-monitoring-metrics/pd-dashboard.md) - - [TiKV 面板](/dev/reference/key-monitoring-metrics/tikv-dashboard.md) - - [报警规则](/dev/reference/alert-rules.md) - + 最佳实践 - - [HAProxy 最佳实践](/dev/reference/best-practices/haproxy.md) - - [Java 应用开发最佳实践](/dev/reference/best-practices/java-app.md) - - [高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md) - - [Grafana 监控最佳实践](/dev/reference/best-practices/grafana-monitor.md) - - [PD 调度策略最佳实践](/dev/reference/best-practices/pd-scheduling.md) - - [海量 Region 集群调优最佳实践](/dev/reference/best-practices/massive-regions.md) - + [TiSpark 使用指南](/dev/reference/tispark.md) - + TiDB Binlog - - [概述](/dev/reference/tidb-binlog/overview.md) - - [部署使用](/dev/reference/tidb-binlog/deploy.md) - - [运维管理](/dev/reference/tidb-binlog/maintain.md) - - [版本升级](/dev/reference/tidb-binlog/upgrade.md) - - [监控告警](/dev/reference/tidb-binlog/monitor.md) - - [增量恢复](/dev/reference/tidb-binlog/reparo.md) - - [Kafka 自定义开发](/dev/reference/tidb-binlog/binlog-slave-client.md) - - [TiDB Binlog Relay Log](/dev/reference/tidb-binlog/relay-log.md) - - [术语表](/dev/reference/tidb-binlog/glossary.md) - + 故障诊断 - - [故障诊断](/dev/reference/tidb-binlog/troubleshoot/binlog.md) - - [常见错误修复](/dev/reference/tidb-binlog/troubleshoot/error-handling.md) - - [FAQ](/dev/reference/tidb-binlog/faq.md) - + 周边工具 - - [工具使用指南](/dev/reference/tools/user-guide.md) - - [Mydumper](/dev/reference/tools/mydumper.md) - - [Loader](/dev/reference/tools/loader.md) - - [Syncer](/dev/reference/tools/syncer.md) - + Data Migration - + 概述 - - [DM 架构](/dev/reference/tools/data-migration/overview.md#dm-架构) - - [同步功能介绍](/dev/reference/tools/data-migration/overview.md#同步功能介绍) - - [使用限制](/dev/reference/tools/data-migration/overview.md#使用限制) - - [DM-worker 简介](/dev/reference/tools/data-migration/dm-worker-intro.md) - - [DM Relay Log](/dev/reference/tools/data-migration/relay-log.md) - + 核心特性 - - [Table Routing](/dev/reference/tools/data-migration/features/overview.md#table-routing) - - [Black & White Lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) - - [Binlog Event Filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) - - [同步延迟监控](/dev/reference/tools/data-migration/features/overview.md#同步延迟监控) - + Shard Support - - [简介](/dev/reference/tools/data-migration/features/shard-merge.md) - - [使用限制](/dev/reference/tools/data-migration/features/shard-merge.md#使用限制) - - [手动处理 Sharding DDL Lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) - + 使用场景 - - [简单的从库同步场景](/dev/reference/tools/data-migration/usage-scenarios/simple-synchronization.md) - - [分库分表合并场景](/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md) - - [分表合并数据迁移最佳实践](/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md) - - [DM-worker 在上游 MySQL 主从间切换](/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md) - + [部署使用](/dev/reference/tools/data-migration/deploy.md) - + 配置 - - [概述](/dev/reference/tools/data-migration/configure/overview.md) - - [DM-master 配置](/dev/reference/tools/data-migration/configure/dm-master-configuration-file.md) - - [DM-worker 配置](/dev/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - - [任务配置](/dev/reference/tools/data-migration/configure/task-configuration-file.md) - + DM 集群管理 - - [集群操作](/dev/reference/tools/data-migration/cluster-operations.md) - - [集群升级](/dev/reference/tools/data-migration/dm-upgrade.md) - + DM 同步任务管理 - - [管理数据同步任务](/dev/reference/tools/data-migration/manage-tasks.md) - - [任务前置检查](/dev/reference/tools/data-migration/precheck.md) - - [任务状态查询](/dev/reference/tools/data-migration/query-status.md) - - [跳过或替代执行异常的 SQL 语句](/dev/reference/tools/data-migration/skip-replace-sqls.md) - - [监控 DM 集群](/dev/reference/tools/data-migration/monitor.md) - + 从与 MySQL 兼容的数据库迁移数据 - - [从 MySQL/Amazon Aurora MySQL 迁移数据](/dev/how-to/migrate/from-mysql-aurora.md) - - [DM Portal](/dev/reference/tools/data-migration/dm-portal.md) - + DM 故障诊断 - - [故障诊断](/dev/reference/tools/data-migration/troubleshoot/dm.md) - - [错误含义](/dev/reference/tools/data-migration/troubleshoot/error-system.md) - - [常见错误修复](/dev/reference/tools/data-migration/troubleshoot/error-handling.md) - - [DM FAQ](/dev/reference/tools/data-migration/faq.md) - + 版本发布历史 - + v1.0 - - [1.0.2](/dev/reference/tools/data-migration/releases/1.0.2.md) - - [1.0.3](/dev/reference/tools/data-migration/releases/1.0.3.md) - - [TiDB DM 术语表](/dev/reference/tools/data-migration/glossary.md) - + TiDB Lightning - - [概述](/dev/reference/tools/tidb-lightning/overview.md) - - [部署执行](/dev/reference/tools/tidb-lightning/deployment.md) - - [参数说明](/dev/reference/tools/tidb-lightning/config.md) - - [断点续传](/dev/reference/tools/tidb-lightning/checkpoints.md) - - [表库过滤](/dev/reference/tools/tidb-lightning/table-filter.md) - - [CSV 支持](/dev/reference/tools/tidb-lightning/csv.md) - - [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) - - [Web 界面](/dev/reference/tools/tidb-lightning/web.md) - - [监控告警](/dev/reference/tools/tidb-lightning/monitor.md) - - [故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md) - - [FAQ](/dev/faq/tidb-lightning.md) - - [术语表](/dev/reference/tools/tidb-lightning/glossary.md) - - [sync-diff-inspector](/dev/reference/tools/sync-diff-inspector/overview.md) - - [PD Control](/dev/reference/tools/pd-control.md) - - [PD Recover](/dev/reference/tools/pd-recover.md) - - [TiKV Control](/dev/reference/tools/tikv-control.md) - - [TiDB Controller](/dev/reference/tools/tidb-control.md) - - [工具下载](/dev/reference/tools/download.md) -+ TiDB in Kubernetes - - [TiDB Operator 简介](/dev/tidb-in-kubernetes/tidb-operator-overview.md) - + 快速上手 - - [kind](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) - - [GKE](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) - - [Minikube](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md) - + 部署 - - [集群环境要求](/dev/tidb-in-kubernetes/deploy/prerequisites.md) - - [部署 TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md) - - [标准 Kubernetes 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/general-kubernetes.md) - - [AWS EKS 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/aws-eks.md) - - [GCP 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/gcp-gke.md) - - [阿里云上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md) - - [访问 Kubernetes 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/access-tidb.md) - + 配置 - - [初始化集群](/dev/tidb-in-kubernetes/initialize-cluster.md) - - [监控](/dev/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) - + 运维 - - [销毁 TiDB 集群](/dev/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md) - - [维护 TiDB 集群所在节点](/dev/tidb-in-kubernetes/maintain/kubernetes-node.md) - - [备份与恢复](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md) - - [恢复 Kubernetes 上的 TiDB 集群数据](/dev/tidb-in-kubernetes/maintain/lightning.md) - - [收集日志](/dev/tidb-in-kubernetes/maintain/log-collecting.md) - - [集群故障自动转移](/dev/tidb-in-kubernetes/maintain/auto-failover.md) - - [TiDB Binlog](/dev/tidb-in-kubernetes/maintain/tidb-binlog.md) - - [重启 TiDB 集群](/dev/tidb-in-kubernetes/maintain/restart.md) - - [扩缩容](/dev/tidb-in-kubernetes/scale-in-kubernetes.md) - + 升级 - - [TiDB 集群](/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md) - - [TiDB Operator](/dev/tidb-in-kubernetes/upgrade/tidb-operator.md) - + 参考信息 - + 配置 - - [集群配置](/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md) - - [备份配置](/dev/tidb-in-kubernetes/reference/configuration/backup.md) - - [PV 配置](/dev/tidb-in-kubernetes/reference/configuration/storage-class.md) - - [TiDB Drainer](/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - + 工具 - - [tkctl](/dev/tidb-in-kubernetes/reference/tools/tkctl.md) - - [相关工具使用](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md) - - [故障诊断](/dev/tidb-in-kubernetes/troubleshoot.md) - - [常见问题](/dev/tidb-in-kubernetes/faq.md) -+ 常见问题 (FAQ) - - [TiDB FAQ](/dev/faq/tidb.md) - - [TiDB Lightning FAQ](/dev/faq/tidb-lightning.md) - - [升级 FAQ](/dev/faq/upgrade.md) -+ 技术支持 - - [支持渠道](/dev/support-resources.md) - - [反馈问题](/dev/report-issue.md) -+ [贡献](/dev/contribute.md) - - [贡献代码](/dev/contribute.md#成为-tidb-的贡献者) - - [改进文档](/dev/contribute.md#改进文档) -+ [TiDB 路线图](/dev/roadmap.md) -+ [版本发布历史](/dev/releases/rn.md) - + v4.0 - - [4.0.0-beta](/dev/releases/4.0.0-beta.md) - + v3.1 - - [3.1.0-beta.1](/dev/releases/3.1.0-beta.1.md) - - [3.1.0-beta](/dev/releases/3.1.0-beta.md) - + v3.0 - - [3.0.10](/dev/releases/3.0.10.md) - - [3.0.9](/dev/releases/3.0.9.md) - - [3.0.8](/dev/releases/3.0.8.md) - - [3.0.7](/dev/releases/3.0.7.md) - - [3.0.6](/dev/releases/3.0.6.md) - - [3.0.5](/dev/releases/3.0.5.md) - - [3.0.4](/dev/releases/3.0.4.md) - - [3.0.3](/dev/releases/3.0.3.md) - - [3.0.2](/dev/releases/3.0.2.md) - - [3.0.1](/dev/releases/3.0.1.md) - - [3.0 GA](/dev/releases/3.0-ga.md) - - [3.0.0-rc.3](/dev/releases/3.0.0-rc.3.md) - - [3.0.0-rc.2](/dev/releases/3.0.0-rc.2.md) - - [3.0.0-rc.1](/dev/releases/3.0.0-rc.1.md) - - [3.0.0-beta.1](/dev/releases/3.0.0-beta.1.md) - - [3.0.0-beta](/dev/releases/3.0beta.md) - + v2.1 - - [2.1.19](/dev/releases/2.1.19.md) - - [2.1.18](/dev/releases/2.1.18.md) - - [2.1.17](/dev/releases/2.1.17.md) - - [2.1.16](/dev/releases/2.1.16.md) - - [2.1.15](/dev/releases/2.1.15.md) - - [2.1.14](/dev/releases/2.1.14.md) - - [2.1.13](/dev/releases/2.1.13.md) - - [2.1.12](/dev/releases/2.1.12.md) - - [2.1.11](/dev/releases/2.1.11.md) - - [2.1.10](/dev/releases/2.1.10.md) - - [2.1.9](/dev/releases/2.1.9.md) - - [2.1.8](/dev/releases/2.1.8.md) - - [2.1.7](/dev/releases/2.1.7.md) - - [2.1.6](/dev/releases/2.1.6.md) - - [2.1.5](/dev/releases/2.1.5.md) - - [2.1.4](/dev/releases/2.1.4.md) - - [2.1.3](/dev/releases/2.1.3.md) - - [2.1.2](/dev/releases/2.1.2.md) - - [2.1.1](/dev/releases/2.1.1.md) - - [2.1 GA](/dev/releases/2.1ga.md) - - [2.1 RC5](/dev/releases/21rc5.md) - - [2.1 RC4](/dev/releases/21rc4.md) - - [2.1 RC3](/dev/releases/21rc3.md) - - [2.1 RC2](/dev/releases/21rc2.md) - - [2.1 RC1](/dev/releases/21rc1.md) - - [2.1 Beta](/dev/releases/21beta.md) - + v2.0 - - [2.0.11](/dev/releases/2.0.11.md) - - [2.0.10](/dev/releases/2.0.10.md) - - [2.0.9](/dev/releases/209.md) - - [2.0.8](/dev/releases/208.md) - - [2.0.7](/dev/releases/207.md) - - [2.0.6](/dev/releases/206.md) - - [2.0.5](/dev/releases/205.md) - - [2.0.4](/dev/releases/204.md) - - [2.0.3](/dev/releases/203.md) - - [2.0.2](/dev/releases/202.md) - - [2.0.1](/dev/releases/201.md) - - [2.0](/dev/releases/2.0ga.md) - - [2.0 RC5](/dev/releases/2rc5.md) - - [2.0 RC4](/dev/releases/2rc4.md) - - [2.0 RC3](/dev/releases/2rc3.md) - - [2.0 RC1](/dev/releases/2rc1.md) - - [1.1 Beta](/dev/releases/11beta.md) - - [1.1 Alpha](/dev/releases/11alpha.md) - + v1.0 - - [1.0](/dev/releases/ga.md) - - [Pre-GA](/dev/releases/prega.md) - - [RC4](/dev/releases/rc4.md) - - [RC3](/dev/releases/rc3.md) - - [RC2](/dev/releases/rc2.md) - - [RC1](/dev/releases/rc1.md) -+ [术语表](/dev/glossary.md) diff --git a/dev/_index.md b/dev/_index.md deleted file mode 100755 index ee1c68515efe..000000000000 --- a/dev/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/dev/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/dev/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/dev/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/dev/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 Docker Compose 部署](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/dev/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/dev/architecture.md b/dev/architecture.md deleted file mode 100644 index ca3ff2c925b8..000000000000 --- a/dev/architecture.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB 整体架构 -category: introduction ---- - -# TiDB 整体架构 - -要深入了解 TiDB 的水平扩展和高可用特点，首先需要了解 TiDB 的整体架构。TiDB 集群主要包括三个核心组件：TiDB Server，PD Server 和 TiKV Server。此外，还有用于解决用户复杂 OLAP 需求的 [TiSpark](https://github.com/pingcap/tispark/) 组件和简化云上部署管理的 [TiDB Operator](/dev/tidb-in-kubernetes/tidb-operator-overview.md) 组件。 - -![TiDB Architecture](/media/tidb-architecture.png) - -## TiDB Server - -TiDB Server 负责接收 SQL 请求，处理 SQL 相关的逻辑，并通过 PD 找到存储计算所需数据的 TiKV 地址，与 TiKV 交互获取数据，最终返回结果。TiDB Server 是无状态的，其本身并不存储数据，只负责计算，可以无限水平扩展，可以通过负载均衡组件（如LVS、HAProxy 或 F5）对外提供统一的接入地址。 - -## PD Server - -Placement Driver (简称 PD) 是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。 - -PD 通过 Raft 协议保证数据的安全性。Raft 的 leader server 负责处理所有操作，其余的 PD server 仅用于保证高可用。建议部署奇数个 PD 节点。 - -## TiKV Server - -TiKV Server 负责存储数据，从外部看 TiKV 是一个分布式的提供事务的 Key-Value 存储引擎。存储数据的基本单位是 Region，每个 Region 负责存储一个 Key Range（从 StartKey 到 EndKey 的左闭右开区间）的数据，每个 TiKV 节点会负责多个 Region。TiKV 使用 Raft 协议做复制，保持数据的一致性和容灾。副本以 Region 为单位进行管理，不同节点上的多个 Region 构成一个 Raft Group，互为副本。数据在多个 TiKV 之间的负载均衡由 PD 调度，这里也是以 Region 为单位进行调度。 - -## TiSpark - -TiSpark 作为 TiDB 中解决用户复杂 OLAP 需求的主要组件，将 Spark SQL 直接运行在 TiDB 存储层上，同时融合 TiKV 分布式集群的优势，并融入大数据社区生态。至此，TiDB 可以通过一套系统，同时支持 OLTP 与 OLAP，免除用户数据同步的烦恼。 - -## TiDB Operator - -TiDB Operator 提供在主流云基础设施（Kubernetes）上部署管理 TiDB 集群的能力。它结合云原生社区的容器编排最佳实践与 TiDB 的专业运维知识，集成一键部署、多集群混部、自动运维、故障自愈等能力，极大地降低了用户使用和管理 TiDB 的门槛与成本。 diff --git a/dev/benchmark/how-to-run-sysbench.md b/dev/benchmark/how-to-run-sysbench.md deleted file mode 100644 index faee8da77632..000000000000 --- a/dev/benchmark/how-to-run-sysbench.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: 如何用 Sysbench 测试 TiDB -category: benchmark ---- - -# 如何用 Sysbench 测试 TiDB - -本次测试使用的是 TiDB 3.0 Beta 和 Sysbench 1.0.14。建议使用 Sysbench 1.0 或之后的更新版本，可在 [Sysbench Release 1.0.14 页面](https://github.com/akopytov/sysbench/releases/tag/1.0.14)下载。 - -## 测试环境 - -- [硬件要求](/dev/how-to/deploy/hardware-recommendations.md) - -- 参考 [TiDB 部署文档](/dev/how-to/deploy/orchestrated/ansible.md)部署 TiDB 集群。在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD，和 1 个 TiKV 实例。关于磁盘，以 32 张表、每张表 10M 行数据为例，建议 TiKV 的数据目录所在的磁盘空间大于 512 GB。 - 对于单个 TiDB 的并发连接数，建议控制在 500 以内，如需增加整个系统的并发压力，可以增加 TiDB 实例，具体增加的 TiDB 个数视测试压力而定。 - -IDC 机器： - -| 类别 | 名称 | -|:---- |:---- | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel® Xeon® CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Intel Optane SSD P4800X 375G * 1 | -| NIC | 10Gb Ethernet | - -## 测试方案 - -### TiDB 版本信息 - -| 组件 | GitHash | -|:---- |:---- | -| TiDB | 7a240818d19ae96e4165af9ea35df92466f59ce6 | -| TiKV | e26ceadcdfe94fb6ff83b5abb614ea3115394bcd | -| PD | 5e81548c3c1a1adab056d977e7767307a39ecb70 | - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|:---- |:---- | -| 172.16.30.31 | 3*sysbench | -| 172.16.30.33 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.34 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.35 | 1\*tidb 1\*pd 1\*tikv | - -### TiDB 配置 - -升高日志级别，可以减少打印日志数量，对 TiDB 的性能有积极影响。开启 TiDB 配置中的 `prepared plan cache`，以减少优化执行计划的开销。具体在 TiDB 配置文件中加入： - -```toml -[log] -level = "error" -[prepared-plan-cache] -enabled = true -``` - -### TiKV 配置 - -升高 TiKV 的日志级别同样有利于提高性能表现。 - -由于 TiKV 是以集群形式部署的，在 Raft 算法的作用下，能保证大多数节点已经写入数据。因此，除了对数据安全极端敏感的场景之外，raftstore 中的 `sync-log` 选项可以关闭。 - -TiKV 集群存在两个 Column Family（Default CF 和 Write CF），主要用于存储不同类型的数据。对于 Sysbench 测试，导入数据的 Column Family 在 TiDB 集群中的比例是固定的。这个比例是： - -Default CF : Write CF = 4 : 1 - -在 TiKV 中需要根据机器内存大小配置 RocksDB 的 block cache，以充分利用内存。以 40 GB 内存的虚拟机部署一个 TiKV 为例，其 block cache 建议配置如下: - -```toml -log-level = "error" -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "24GB" -[rocksdb.writecf] -block-cache-size = "6GB" -``` - -对于 3.0 及以后的版本，还可以使用共享 block cache 的方式进行设置： - -```toml -log-level = "error" -[raftstore] -sync-log = false -[storage.block-cache] -capacity = "30GB" -``` - -更详细的 TiKV 参数调优请参考 [TiKV 性能参数调优](/dev/reference/performance/tune-tikv.md)。 - -## 测试过程 - -> **注意：** -> -> 此次测试并没有使用如 HAproxy 等负载均衡工具。在 TiDB 单一节点上进行 Sysbench 测试，并把结果相加。负载均衡工具和不同版本参数也会影响性能表现。 - -### Sysbench 配置 - -以下为 Sysbench 配置文件样例： - -```txt -mysql-host={TIDB_HOST} -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads={8, 16, 32, 64, 128, 256} -report-interval=10 -db-driver=mysql -``` - -可根据实际需求调整其参数，其中 `TIDB_HOST` 为 TiDB server 的 IP 地址（配置文件中不能写多个地址），`threads` 为测试中的并发连接数，可在 “8, 16, 32, 64, 128, 256” 中调整，导入数据时，建议设置 threads = 8 或者 16。调整后，将该文件保存为名为 **config** 的文件。 - -**配置文件**参考示例如下： - -```txt -mysql-host=172.16.30.33 -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads=16 -report-interval=10 -db-driver=mysql -``` - -### 数据导入 - -在数据导入前，需要对 TiDB 进行简单设置。在 MySQL 客户端中执行如下命令： - -{{< copyable "sql" >}} - -```sql -set global tidb_disable_txn_auto_retry = off; -``` - -然后退出客户端。TiDB 使用乐观事务模型，当发现并发冲突时，会回滚事务。将 `tidb_disable_txn_auto_retry` 设置为 `off` 会开启事务冲突后的自动重试机制，可以尽可能避免事务冲突报错导致 Sysbench 程序退出的问题。 - -重新启动 MySQL 客户端执行以下 SQL 语句，创建数据库 `sbtest`： - -{{< copyable "sql" >}} - -```sql -create database sbtest; -``` - -调整 Sysbench 脚本创建索引的顺序。Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。该方式对于 TiDB 需要花费更多的导入时间。用户可以通过调整顺序来加速数据的导入。 - -假设用户使用的 [Sysbench](https://github.com/akopytov/sysbench/tree/1.0.14) 版本。我们可以通过以下两种方式来修改。 - -1. 直接下载为 TiDB 修改好的 [oltp_common.lua](https://raw.githubusercontent.com/pingcap/tidb-bench/master/sysbench/sysbench-patch/oltp_common.lua) 文件，覆盖 `/usr/share/sysbench/oltp_common.lua` 文件。 -2. 将 `/usr/share/sysbench/oltp_common.lua` 的第 [235](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L235) 行到第 [240](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L240) 行移动到第 198 行以后。 - -> **注意：** -> -> 此操作为可选操作，仅节约了数据导入时间。 - -命令行输入以下命令，开始导入数据，config 文件为上一步中配置的文件： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 prepare -``` - -### 数据预热与统计信息收集 - -数据预热可将磁盘中的数据载入内存的 block cache 中，预热后的数据对系统整体的性能有较大的改善，建议在每次重启集群后进行一次数据预热。 - -Sysbench 1.0.14 没有提供数据预热的功能，因此需要手动进行数据预热。如果使用更新的 Sysbench 版本，可以使用自带的预热功能。 - -以 Sysbench 中某张表 sbtest7 为例，执行如下 SQL 语句 进行数据预热： - -{{< copyable "sql" >}} - -```sql -SELECT COUNT(pad) FROM sbtest7 USE INDEX (k_7); -``` - -统计信息收集有助于优化器选择更为准确的执行计划，可以通过 `analyze` 命令来收集表 sbtest 的统计信息，每个表都需要统计。 - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE sbtest7; -``` - -### Point select 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 run -``` - -### Update index 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_update_index --tables=32 --table-size=10000000 run -``` - -### Read-only 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_read_only --tables=32 --table-size=10000000 run -``` - -## 测试结果 - -测试了数据 32 表，每表有 10M 数据。 - -对每个 tidb-server 进行了 Sysbench 测试，将结果相加，得出最终结果： - -### oltp_point_select - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| point_select | 3\*8 | 67502.55 | 67502.55 | 0.36 | 0.42 | 141.92 | -| point_select | 3\*16 | 120141.84 | 120141.84 | 0.40 | 0.52 | 20.99 | -| point_select | 3\*32 | 170142.92 | 170142.92 | 0.58 | 0.99 | 28.08 | -| point_select | 3\*64 | 195218.54 | 195218.54 | 0.98 | 2.14 | 21.82 | -| point_select | 3\*128 | 208189.53 | 208189.53 | 1.84 | 4.33 | 31.02 | - -![oltp_point_select](/media/oltp_point_select.png) - -### oltp_update_index - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_update_index | 3\*8 | 9668.98 | 9668.98 | 2.51 | 3.19 | 103.88| -| oltp_update_index | 3\*16 | 12834.99 | 12834.99 | 3.79 | 5.47 | 176.90 | -| oltp_update_index | 3\*32 | 15955.77 | 15955.77 | 6.07 | 9.39 | 4787.14 | -| oltp_update_index | 3\*64 | 18697.17 | 18697.17 | 10.34 | 17.63 | 4539.04 | -| oltp_update_index | 3\*128 | 20446.81 | 20446.81 | 18.98 | 40.37 | 5394.75 | -| oltp_update_index | 3\*256 | 23563.03 | 23563.03 | 32.86 | 78.60 | 5530.69 | - -![oltp_update_index](/media/oltp_update_index.png) - -### oltp_read_only - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_read_only | 3\*8 | 2411.00 | 38575.96 | 9.92 | 20.00 | 92.23 | -| oltp_read_only | 3\*16 | 3873.53 | 61976.50 | 12.25 | 16.12 | 56.94 | -| oltp_read_only | 3\*32 | 5066.88 | 81070.16 | 19.42 | 26.20 | 123.41 | -| oltp_read_only | 3\*64 | 5466.36 | 87461.81 | 34.65 | 63.20 | 231.19 | -| oltp_read_only | 3\*128 | 6684.16 | 106946.59 | 57.29 | 97.55 | 180.85 | - -![oltp_read_only](/media/oltp_read_only.png) - -## 常见问题 - -### 在高并发压力下，TiDB、TiKV 的配置都合理，为什么整体性能还是偏低？ - -这种情况可能与使用了 proxy 有关。可以尝试直接对单个 TiDB 加压，将求和后的结果与使用 proxy 的情况进行对比。 - -以 HAproxy 为例。`nbproc` 参数可以增加其最大启动的进程数，较新版本的 HAproxy 还支持 `nbthread` 和 `cpu-map` 等。这些都可以减少对其性能的不利影响。 - -### 在高并发压力下，为什么 TiKV 的 CPU 利用率依然很低？ - -TiKV 虽然整体 CPU 偏低，但部分模块的 CPU 可能已经达到了很高的利用率。 - -TiKV 的其他模块，如 storage readpool、coprocessor 和 gRPC 的最大并发度限制是可以通过 TiKV 的配置文件进行调整的。 - -通过 Grafana 的 TiKV Thread CPU 监控面板可以观察到其实际使用率。如出现多线程模块瓶颈，可以通过增加该模块并发度进行调整。 - -### 在高并发压力下，TiKV 也未达到 CPU 使用瓶颈，为什么 TiDB 的 CPU 利用率依然很低？ - -在某些高端设备上，使用的是 NUMA 架构的 CPU，跨 CPU 访问远端内存将极大降低性能。TiDB 默认将使用服务器所有 CPU，goroutine 的调度不可避免地会出现跨 CPU 内存访问。 - -因此，建议在 NUMA 架构服务器上，部署 *n* 个 TiDB（*n* = NUMA CPU 的个数），同时将 TiDB 的 `max-procs` 变量的值设置为与 NUMA CPU 的核数相同。 diff --git a/dev/benchmark/how-to-run-tpcc.md b/dev/benchmark/how-to-run-tpcc.md deleted file mode 100644 index 23389e04b005..000000000000 --- a/dev/benchmark/how-to-run-tpcc.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: 如何对 TiDB 进行 TPC-C 测试 -category: benchmark ---- - -# 如何对 TiDB 进行 TPC-C 测试 - -本文介绍如何对 TiDB 进行 [TPC-C](http://www.tpc.org/tpcc/) 测试。 - -## 准备测试程序 - -TPC-C 是一个对 OLTP（联机交易处理）系统进行测试的规范，使用一个商品销售模型对 OLTP 系统进行测试，其中包含五类事务： - -* NewOrder – 新订单的生成 -* Payment – 订单付款 -* OrderStatus – 最近订单查询 -* Delivery – 配送 -* StockLevel – 库存缺货状态分析 - -在测试开始前，TPC-C Benchmark 规定了数据库的初始状态，也就是数据库中数据生成的规则，其中 ITEM 表中固定包含 10 万种商品，仓库的数量可进行调整，假设 WAREHOUSE 表中有 W 条记录，那么： - -* STOCK 表中应有 W \* 10 万条记录（每个仓库对应 10 万种商品的库存数据） -* DISTRICT 表中应有 W \* 10 条记录（每个仓库为 10 个地区提供服务） -* CUSTOMER 表中应有 W \* 10 \* 3000 条记录（每个地区有 3000 个客户） -* HISTORY 表中应有 W \* 10 \* 3000 条记录（每个客户一条交易历史） -* ORDER 表中应有 W \* 10 \* 3000 条记录（每个地区 3000 个订单），并且最后生成的 900 个订单被添加到 NEW-ORDER 表中，每个订单随机生成 5 ~ 15 条 ORDER-LINE 记录。 - -我们将以 1000 WAREHOUSE 为例进行测试。 - -TPC-C 使用 tpmC 值（Transactions per Minute）来衡量系统最大有效吞吐量 (MQTh, Max Qualified Throughput)，其中 Transactions 以 NewOrder Transaction 为准，即最终衡量单位为每分钟处理的新订单数。 - -本文使用开源的 BenchmarkSQL 5.0 作为 TPC-C 测试实现并添加了对 MySQL 协议的支持，可以通过以下命令下载测试程序: - -{{< copyable "shell-regular" >}} - -```shell -git clone -b 5.0-mysql-support-opt-2.1 https://github.com/pingcap/benchmarksql.git -``` - -安装 java 和 ant，以 CentOS 为例，可以执行以下命令进行安装 - -{{< copyable "shell-regular" >}} - -```shell -sudo yum install -y java ant -``` - -进入 benchmarksql 目录并执行 ant 构建 - -{{< copyable "shell-regular" >}} - -```shell -cd benchmarksql -ant -``` - -## 部署 TiDB 集群 - -对于 1000 WAREHOUSE 我们将在 3 台服务器上部署集群。 - -在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD 和 1 个 TiKV 实例。 - -比如这里采用的机器硬件配置是： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD | - -因为该型号 CPU 是 NUMA 架构，建议先用 `taskset` 进行绑核，首先用 `lscpu` 查看 NUMA node，比如： - -```text -NUMA node0 CPU(s): 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 -NUMA node1 CPU(s): 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 -``` - -之后可以通过下面的命令来启动 TiDB： - -{{< copyable "shell-regular" >}} - -```shell -nohup taskset -c 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 bin/tidb-server && \ -nohup taskset -c 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 bin/tidb-server -``` - -最后，可以选择部署一个 HAproxy 来进行多个 TiDB node 的负载均衡，推荐配置 nbproc 为 CPU 核数。 - -## 配置调整 - -### TiDB 配置 - -```toml -[log] -level = "error" - -[performance] -# 根据 NUMA 配置，设置单个 TiDB 最大使用的 CPU 核数 -max-procs = 20 - -[prepared_plan_cache] -# 开启 TiDB 配置中的 prepared plan cache，以减少优化执行计划的开销 -enabled = true -``` - -### TiKV 配置 - -开始可以使用基本的配置，压测运行后可以通过观察 Grafana 并参考 [TiKV 调优说明](/dev/reference/performance/tune-tikv.md)进行调整。 - -### BenchmarkSQL 配置 - -修改 `benchmarksql/run/props.mysql`： - -```text -conn=jdbc:mysql://{HAPROXY-HOST}:{HAPROXY-PORT}/tpcc?useSSL=false&useServerPrepStmts=true&useConfigs=maxPerformance -warehouses=1000 # 使用 1000 个 warehouse -terminals=500 # 使用 500 个终端 -loadWorkers=32 # 导入数据的并发数 -``` - -## 导入数据 - -**导入数据通常是整个 TPC-C 测试中最耗时，也是最容易出问题的阶段。** - -首先用 MySQL 客户端连接到 TiDB-Server 并执行： - -{{< copyable "sql" >}} - -```sql -create database tpcc -``` - -之后在 shell 中运行 BenchmarkSQL 建表脚本： - -{{< copyable "shell-regular" >}} - -```shell -cd run && \ -./runSQL.sh props.mysql sql.mysql/tableCreates.sql && \ -./runSQL.sh props.mysql sql.mysql/indexCreates.sql -``` - -### 直接使用 BenchmarkSQL 导入 - -运行导入数据脚本： - -{{< copyable "shell-regular" >}} - -```shell -./runLoader.sh props.mysql -``` - -根据机器配置这个过程可能会持续几个小时。 - -### 通过 TiDB Lightning 导入 - -由于导入数据量随着 warehouse 的增加而增加，当需要导入 1000 warehouse 以上数据时，可以先用 BenchmarkSQL 生成 csv 文件，再将文件通过 TiDB Lightning（以下简称 Lightning）导入的方式来快速导入。生成的 csv 文件也可以多次复用，节省每次生成所需要的时间。 - -#### 修改 BenchmarkSQL 的配置文件 - -1 warehouse 的 csv 文件需要 77 MB 磁盘空间，在生成之前要根据需要分配足够的磁盘空间来保存 csv 文件。可以在 `benchmarksql/run/props.mysql` 文件中增加一行： - -```text -fileLocation=/home/user/csv/ # 存储 csv 文件的目录绝对路径，需保证有足够的空间 -``` - -因为最终要使用 Lightning 导入数据，所以 csv 文件名最好符合 Lightning 要求，即 `{database}.{table}.csv` 的命名法。这里可以将以上配置改为： - -```text -fileLocation=/home/user/csv/tpcc. # 存储 csv 文件的目录绝对路径 + 文件名前缀（database） -``` - -这样生成的 csv 文件名将会是类似 `tpcc.bmsql_warehouse.csv` 的样式，符合 Lightning 的要求。 - -#### 生成 csv 文件 - -{{< copyable "shell-regular" >}} - -```shell -./runLoader.sh props.mysql -``` - -#### 通过 Lightning 导入 - -通过 Lightning 导入数据请参考 [Lightning 部署执行](/dev/reference/tools/tidb-lightning/deployment.md)章节。这里我们介绍下通过 tidb-ansible 部署 Lightning 导入数据的方法。 - -##### 修改 inventory.ini - -这里最好手动指定清楚部署的 IP、端口、目录，避免各种冲突问题带来的异常，其中 import_dir 的磁盘空间参考 [Lightning 部署执行](/dev/reference/tools/tidb-lightning/deployment.md)，data_source_dir 就是存储上一节 csv 数据的目录。 - -```ini -[importer_server] -IS1 ansible_host=172.16.5.34 deploy_dir=/data2/is1 tikv_importer_port=13323 import_dir=/data2/import - -[lightning_server] -LS1 ansible_host=172.16.5.34 deploy_dir=/data2/ls1 tidb_lightning_pprof_port=23323 data_source_dir=/home/user/csv -``` - -##### 修改 conf/tidb-lightning.yml - -```yaml -mydumper: - no-schema: true - csv: - separator: ',' - delimiter: '' - header: false - not-null: false - 'null': 'NULL' - backslash-escape: true - trim-last-separator: false -``` - -##### 部署 Lightning 和 Importer - -{{< copyable "shell-regular" >}} - -```shell -ansible-playbook deploy.yml --tags=lightning -``` - -##### 启动 - -* 登录到部署 Lightning 和 Importer 的服务器 -* 进入部署目录 -* 在 Importer 目录下执行 `scripts/start_importer.sh`，启动 Importer -* 在 Lightning 目录下执行 `scripts/start_lightning.sh`，开始导入数据 - -由于是用 ansible 进行部署的，可以在监控页面看到 Lightning 的导入进度，或者通过日志查看导入是否结束。 - -### 导入完成后 - -数据导入完成之后，可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句都返回结果为空，即为数据导入正确。 - -## 运行测试 - -执行 BenchmarkSQL 测试脚本： - -{{< copyable "shell-regular" >}} - -```shell -nohup ./runBenchmark.sh props.mysql &> test.log & -``` - -运行结束后通过 `test.log` 查看结果： - -```text -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmC (NewOrders) = 77373.25 -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmTOTAL = 171959.88 -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Session Start = 2019-03-21 07:07:52 -07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Session End = 2019-03-21 07:09:53 -07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Transaction Count = 345240 -``` - -tpmC 部分即为测试结果。 - -测试完成之后，也可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句的返回结果都为空，即为数据测试过程正确。 diff --git a/dev/faq/tidb-lightning.md b/dev/faq/tidb-lightning.md deleted file mode 100644 index 1e6b7ac7ad94..000000000000 --- a/dev/faq/tidb-lightning.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: TiDB Lightning 常见问题 -category: FAQ ---- - -# TiDB Lightning 常见问题 - -本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。 - ->**注意：** -> -> 使用 TiDB Lightning 的过程中如遇错误，参考 [TiDB Lightning 故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md)进行排查。 - -## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ - -TiDB Lightning 的版本应与集群相同。最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。 - -## TiDB Lightning 支持导入多个库吗？ - -支持。 - -## TiDB Lightning 对下游数据库的账号权限要求是怎样的？ - -TiDB Lightning 需要以下权限： - -* SELECT -* UPDATE -* ALTER -* CREATE -* DROP - -如果选择 [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) 模式，或目标数据库用于存储断点，则 TiBD Lightning 额外需要以下权限： - -* INSERT -* DELETE - -+Importer-backend 无需以上两个权限，因为数据直接被 Ingest 到 TiKV 中，所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问，就可以保证安全。 - -如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？ - -如果只是个别表报错，不会影响整体。报错的那个表会停止处理，继续处理其他的表。 - -## 如何正确重启 TiDB Lightning？ - -根据 `tikv-importer` 的状态，重启 TiDB Lightning 的基本顺序如下： - -如果 `tikv-importer` 仍在运行： - -1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 -3. 如果上面的修改操作更改了任何表，你还需要[清除对应的断点](/dev/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-remove)。 -4. 重启 `tidb-lightning`。 - -如果 `tikv-importer` 需要重启： - -1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. [结束 `tikv-importer` 进程](#如何正确结束-tikv-importer-进程)。 -3. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 -4. 重启 `tikv-importer`。 -5. 重启 `tidb-lightning` 并等待，**直到程序因校验和错误（如果有的话）而失败**。 - * 重启 `tikv-importer` 将清除所有仍在写入的引擎文件，但是 `tidb-lightning` 并不会感知到该操作。从 v3.0 开始，最简单的方法是让 `tidb-lightning` 继续，然后再重试。 -6. [清除失败的表及断点](/dev/how-to/troubleshoot/tidb-lightning.md#checkpoint-for--has-invalid-status错误码)。 -7. 再次重启 `tidb-lightning`。 - -## 如何校验导入的数据的正确性？ - -TiDB Lightning 默认会对导入数据计算校验和 (checksum)，如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。 - -TiDB 也支持从 MySQL 命令行运行 `ADMIN CHECKSUM TABLE` 指令来计算校验和。 - -{{< copyable "sql" >}} - -```sql -ADMIN CHECKSUM TABLE `schema`.`table`; -``` - -``` -+---------+------------+---------------------+-----------+-------------+ -| Db_name | Table_name | Checksum_crc64_xor | Total_kvs | Total_bytes | -+---------+------------+---------------------+-----------+-------------+ -| schema | table | 5505282386844578743 | 3 | 96 | -+---------+------------+---------------------+-----------+-------------+ -1 row in set (0.01 sec) -``` - -## TiDB Lightning 支持哪些格式的数据源？ - -TiDB Lightning 只支持两种格式的数据源： - -1. [Mydumper](/dev/reference/tools/mydumper.md) 生成的 SQL dump -2. 储存在本地文件系统的 [CSV](/dev/reference/tools/tidb-lightning/csv.md) 文件 - -## 我已经在下游创建好库和表了，TiDB Lightning 可以忽略建库建表操作吗？ - -可以。在配置文档中的 `[mydumper]` 部分将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。 - -## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入？ - -可以。Lightning 默认的 [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) 为 `"STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"`。 - -这个设置不允许一些非法的数值，例如 `1970-00-00` 这样的日期。可以修改配置文件 `[tidb]` 下的 `sql-mode` 值。 - -```toml -... -[tidb] -sql-mode = "" -... -``` - -## 可以启用一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？ - -只要每个 Lightning 操作的表互不相同就可以。 - -## 如何正确结束 `tikv-importer` 进程？ - -根据部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh`。 - -- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程 ID，然后通过 `kill «pid»` 结束进程。 - -## 如何正确结束 `tidb-lightning` 进程？ - -根据部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh`。 - -- 手动部署：如果 `tidb-lightning` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tidb-lightning` 获取进程 ID，然后通过 `kill -2 «pid»` 结束进程。 - -## `tidb-lightning` 在服务器上运行，进程莫名其妙地退出了，是怎么回事呢？ - -这种情况可能是启动方式不正确，导致收到 SIGHUP 信号而退出。此时 `tidb-lightning.log` 通常有如下日志： - -``` -[2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup] -``` - -不推荐在命令行中直接使用 `nohup` 启动进程，推荐[使用脚本启动 `tidb-lightning`](/dev/reference/tools/tidb-lightning/deployment.md)。 - -## 为什么用过 TiDB Lightning 之后，TiDB 集群变得又慢又耗 CPU？ - -如果 `tidb-lightning` 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)： - -{{< copyable "shell-regular" >}} - -```sh -tidb-lightning-ctl --switch-mode=normal -``` - -## TiDB Lightning 可以使用千兆网卡吗？ - -使用 TiDB Lightning 建议配置万兆网卡。**不推荐**使用千兆网卡，尤其是在部署 `tikv-importer` 的机器上。 - -千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。为了避免这种情况，你可以在 [`tikv-importer` 的配置文件](/dev/reference/tools/tidb-lightning/config.md#tikv-importer-配置参数)中**限制上传速度**。 - -```toml -[import] -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# 建议将该速度设为 100 MB/s 或更小。 -upload-speed-limit = "100MB" -``` - -## 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间？ - -当使用默认的 3 副本设置时，TiDB Lightning 需要 TiKV 集群预留数据源大小 6 倍的空间。多出来的 2 倍是算上下列没储存在数据源的因素的保守估计： - -- 索引会占据额外的空间 -- RocksDB 的空间放大效应 - -## TiDB Lightning 使用过程中是否可以重启 TiKV Importer？ - -不能，Importer 会在内存中存储一些引擎文件，Importer 重启后，`tidb-lightning` 会因连接失败而停止。此时，你需要[清除失败的断点](/dev/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-error-destroy)，因为这些 Importer 特有的信息丢失了。你可以在之后[重启 Lightning](#如何正确重启-tidb-lightning)。 - -## 如何清除所有与 TiDB Lightning 相关的中间数据？ - -1. 删除断点文件。 - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all - ``` - - 如果出于某些原因而无法运行该命令，你可以尝试手动删除 `/tmp/tidb_lightning_checkpoint.pb` 文件。 - -2. 删除 `tikv-importer` 所在机器上的整个 “import” 文件目录。 - -3. 如果需要的话，删除 TiDB 集群上创建的所有表和库。 diff --git a/dev/faq/tidb.md b/dev/faq/tidb.md deleted file mode 100755 index 69658c01255a..000000000000 --- a/dev/faq/tidb.md +++ /dev/null @@ -1,1082 +0,0 @@ ---- -title: TiDB FAQ -category: FAQ ---- - -# FAQ - -## 一、 TiDB 介绍、架构、原理 - -### 1.1 TiDB 介绍及整体架构 - -#### 1.1.1 TiDB 整体架构 - -[TiDB 简介](/dev/overview.md#tidb-简介) - -#### 1.1.2 TiDB 是什么？ - -TiDB 是一个分布式 NewSQL 数据库。它支持水平弹性扩展、ACID 事务、标准 SQL、MySQL 语法和 MySQL 协议，具有数据强一致的高可用特性，是一个不仅适合 OLTP 场景还适合 OLAP 场景的混合数据库。 - -#### 1.1.3 TiDB 是基于 MySQL 开发的吗？ - -不是，虽然 TiDB 支持 MySQL 语法和协议，但是 TiDB 是由 PingCAP 团队完全自主开发的产品。 - -#### 1.1.4 TiDB、TiKV、Placement Driver (PD) 主要作用？ - -- TiDB 是 Server 计算层，主要负责 SQL 的解析、制定查询计划、生成执行器。 -- TiKV 是分布式 Key-Value 存储引擎，用来存储真正的数据，简而言之，TiKV 是 TiDB 的存储引擎。 -- PD 是 TiDB 集群的管理组件，负责存储 TiKV 的元数据，同时也负责分配时间戳以及对 TiKV 做负载均衡调度。 - -#### 1.1.5 TiDB 易用性如何？ - -TiDB 使用起来很简单，可以将 TiDB 集群当成 MySQL 来用，你可以将 TiDB 用在任何以 MySQL 作为后台存储服务的应用中，并且基本上不需要修改应用代码，同时你可以用大部分流行的 MySQL 管理工具来管理 TiDB。 - -#### 1.1.6 TiDB 和 MySQL 兼容性如何？ - -TiDB 目前还不支持触发器、存储过程、自定义函数、外键，除此之外，TiDB 支持绝大部分 MySQL 5.7 的语法。 - -详情参见[与 MySQL 兼容性对比](/dev/reference/mysql-compatibility.md)。 - -#### 1.1.7 TiDB 具备高可用的特性吗？ - -TiDB 天然具备高可用特性，TiDB、TiKV、PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。具体见 [TiDB 高可用性](/dev/key-features.md#高可用)。 - -#### 1.1.8 TiDB 数据是强一致的吗？ - -TiDB 实现了快照隔离 (Snapshot Isolation) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。 - -在底层，TiKV 使用复制日志 + 状态机 (State Machine) 的模型来复制数据。对于写入请求，数据被写入 Leader，然后 Leader 以日志的形式将命令复制到它的 Follower 中。当集群中的大多数节点收到此日志时，日志会被提交，状态机会相应作出变更。 - -#### 1.1.9 TiDB 支持分布式事务吗？ - -支持。无论是一个地方的几个节点，还是[跨多个数据中心的多个节点](/dev/how-to/deploy/geographic-redundancy/overview.md)，TiDB 均支持 ACID 分布式事务。 - -TiDB 事务模型灵感源自 Google Percolator 模型，主体是一个两阶段提交协议，并进行了一些实用的优化。该模型依赖于一个时间戳分配器，为每个事务分配单调递增的时间戳，这样就检测到事务冲突。在 TiDB 集群中，[PD](/dev/architecture.md#pd-server) 承担时间戳分配器的角色。 - -#### 1.1.10 TiDB 支持哪些编程语言？ - -只要支持 MySQL Client/Driver 的编程语言，都可以直接使用 TiDB。 - -#### 1.1.11 TiDB 是否支持其他存储引擎？ - -是的，除了 TiKV 之外，TiDB 还支持一些流行的单机存储引擎，比如 GolevelDB、RocksDB、BoltDB 等。如果一个存储引擎是支持事务的 KV 引擎，并且能提供一个满足 TiDB 接口要求的 Client，即可接入 TiDB。 - -#### 1.1.12 官方有没有三中心跨机房多活部署的推荐方案？ - -从 TiDB 架构来讲，支持真正意义上的跨中心异地多活，从操作层面讲，依赖数据中心之间的网络延迟和稳定性，一般建议延迟在 5ms 以下，目前我们已经有相似客户方案，具体请咨询官方 [info@pingcap.com](mailto:info@pingcap.com)。 - -#### 1.1.13 除了官方文档，有没有其他 TiDB 知识获取途径？ - -目前[官方文档](/dev/overview.md#tidb-简介)是获取 TiDB 相关知识最主要、最及时的发布途径。除此之外，我们也有一些技术沟通群，如有需求可发邮件至 [info@pingcap.com](mailto:info@pingcap.com) 获取。 - -#### 1.1.14 TiDB 对哪些 MySQL variables 兼容？ - -详细可参考[系统变量](/dev/reference/configuration/tidb-server/mysql-variables.md)。 - -#### 1.1.15 TiDB 是否支持 select for update？ - -支持，但语义上和 MySQL 有区别，TiDB 是分布式数据库，采用的乐观锁机制，也就说 select for update 不在事务开启就锁住数据，而是其他事务在提交的时候进行冲突检查，如有冲突，会进行回滚。 - -#### 1.1.16 TiDB 的 codec 能保证 UTF8 的字符串是 memcomparable 的吗？我们的 key 需要支持 UTF8，有什么编码建议吗？ - -TiDB 字符集默认就是 UTF8 而且目前只支持 UTF8，字符串就是 memcomparable 格式的。 - -#### 1.1.17 TiDB 用户名长度限制？ - -在 TiDB 中用户名最长为 32 字符。 - -#### 1.1.18 一个事务中的语句数量最大是多少？ - -一个事务中的语句数量，默认限制最大为 5000 条。 - -#### 1.1.19 TiDB 是否支持 XA？ - -虽然 TiDB 的 JDBC 驱动用的就是 MySQL JDBC（Connector / J），但是当使用 Atomikos 的时候，数据源要配置成类似这样的配置：`type="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"`。MySQL JDBC XADataSource 连接 TiDB 的模式目前是不支持的。MySQL JDBC 中配置好的 XADataSource 模式，只对 MySQL 数据库起作用（DML 去修改 redo 等）。 - -Atomikos 配好两个数据源后，JDBC 驱动都要设置成 XA 模式，然后 Atomikos 在操作 TM 和 RM（DB）的时候，会通过数据源的配置，发起带有 XA 指令到 JDBC 层，JDBC 层 XA 模式启用的情况下，会对 InnoDB（如果是 MySQL 的话）下发操作一连串 XA 逻辑的动作，包括 DML 去变更 redo log 等，就是两阶段递交的那些操作。TiDB 目前的引擎版本中，没有对上层应用层 JTA / XA 的支持，不解析这些 Atomikos 发过来的 XA 类型的操作。 - -MySQL 是单机数据库，只能通过 XA 来满足跨数据库事务，而 TiDB 本身就通过 Google 的 Percolator 事务模型支持分布式事务，性能稳定性比 XA 要高出很多，所以不会也不需要支持 XA。 - -#### 1.1.20 show processlist 是否显示系统进程号？ - -TiDB 的 `show processlist` 与 MySQL 的 `show processlist` 显示内容基本一样，不会显示系统进程号，而 ID 表示当前的 session ID。其中 TiDB 的 `show processlist` 和 MySQL 的 `show processlist` 区别如下： - -1）由于 TiDB 是分布式数据库，tidb-server 实例是无状态的 SQL 解析和执行引擎（详情可参考 [TiDB 整体架构](/dev/overview.md#tidb-整体架构)），用户使用 MySQL 客户端登录的是哪个 tidb-server，`show processlist` 就会显示当前连接的这个 tidb-server 中执行的 session 列表，不是整个集群中运行的全部 session 列表；而 MySQL 是单机数据库，`show processlist` 列出的是当前整个 MySQL 数据库的全部执行 SQL 列表。 - -2）TiDB 的 `show processlist` 显示内容比起 MySQL 来讲，多了一个当前 session 使用内存的估算值（单位 Byte）。 - -#### 1.1.21 如何修改用户名密码和权限？ - -TiDB 作为分布式数据库，在 TiDB 中修改用户密码建议使用 `set password for 'root'@'%' = '0101001';` 或 `alter` 方法，不推荐使用 `update mysql.user` 的方法进行，这种方法可能会造成其它节点刷新不及时的情况。修改权限也一样，都建议采用官方的标准语法。详情可参考 [TiDB 用户账户管理](/dev/reference/security/user-account-management.md)。 - -#### 1.1.22 TiDB 中，为什么出现后插入数据的自增 ID 反而小？ - -TiDB 的自增 ID (`AUTO_INCREMENT`) 只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。当多个线程并发往不同的 tidb-server 插入数据的时候，有可能会出现后插入的数据自增 ID 小的情况。此外，TiDB允许给整型类型的字段指定 AUTO_INCREMENT，且一个表只允许一个属性为 `AUTO_INCREMENT` 的字段。详情可参考[CREATE TABLE 语法](/dev/reference/mysql-compatibility.md#自增-id)。 - -#### 1.1.23 sql_mode 默认除了通过命令 set 修改，配置文件怎么修改？ - -TiDB 的 sql_mode 与 MySQL 的 sql_mode 设置方法有一些差别，TiDB 不支持配置文件配置设置数据库的 sql\_mode，而只能使用 set 命令去设置，具体方法为：`set @@global.sql_mode = 'STRICT_TRANS_TABLES';`。 - -#### 1.1.24 TiDB 支持哪些认证协议，过程是怎样的？ - -这一层跟 MySQL 一样，走的 SASL 认证协议，用于用户登录认证，对密码的处理流程。 - -客户端连接 TiDB 的时候，走的是 challenge-response（挑战-应答）的认证模式，过程如下： - -第一步：客户端连接服务器； - -第二步：服务器发送随机字符串 challenge 给客户端； - -第三步：客户端发送 username + response 给服务器； - -第四步：服务器验证 response。 - -### 1.2 TiDB 原理 - -#### 1.2.1 存储 TiKV - -##### 1.2.1.1 TiKV 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说存储](http://t.cn/RTKRRWv) - -#### 1.2.2 计算 TiDB - -##### 1.2.2.1 TiDB 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说计算](http://t.cn/RTKRkBh) - -#### 1.2.3 调度 PD - -##### 1.2.3.1 PD 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 谈调度](http://t.cn/RTKEZ0U) - -## 二、安装部署升级 - -### 2.1 环境准备 - -#### 2.1.1 操作系统版本要求 - -| **Linux 操作系统平台** | **版本** | -| --- | --- | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | - -##### 2.1.1.1 为什么要在 CentOS 7 上部署 TiDB 集群？ - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络，作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境，具体可以参考 TiDB 的[官方部署要求](/dev/how-to/deploy/hardware-recommendations.md)。其中 TiDB 在 CentOS 7.3 的环境下进行大量的测试，同时也有很多这个操作系统的部署最佳实践，因此，我们推荐客户在部署 TiDB 的时候使用 CentOS 7.3+ 以上的Linux 操作系统。 - -#### 2.1.2 硬件要求 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -##### 2.1.2.1 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | -| | | | | 服务器总计 | 4 | - -##### 2.1.2.2 线上环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 48 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 8核+ | 16 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 48 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | -| | | | | 服务器总计 | 9 | - -##### 2.1.2.3 2 块网卡的目的是？万兆的目的是？ - -作为一个分布式集群，TiDB 对时间的要求还是比较高的，尤其是 PD 需要分发唯一的时间戳，如果 PD 时间不统一，如果有 PD 切换，将会等待更长的时间。2 块网卡可以做 bond，保证数据传输的稳定，万兆可以保证数据传输的速度，千兆网卡容易出现瓶颈，我们强烈建议使用万兆网卡。 - -##### 2.1.2.4 SSD 不做 RAID 是否可行？ - -资源可接受的话，我们建议做 RAID 10，如果资源有限，也可以不做 RAID。 - -##### 2.1.2.5 TiDB 集群各个组件的配置推荐？ - -- TiDB 需要 CPU 和内存比较好的机器，参考官网配置要求，如果后期需要开启 Binlog，根据业务量的评估和 GC 时间的要求，也需要本地磁盘大一点，不要求 SSD 磁盘； -- PD 里面存了集群元信息，会有频繁的读写请求，对磁盘 I/O 要求相对比较高，磁盘太差会影响整个集群性能，推荐 SSD 磁盘，空间不用太大。另外集群 Region 数量越多对 CPU、内存的要求越高； -- TiKV 对 CPU、内存、磁盘要求都比较高，一定要用 SSD 磁盘。 - -详情可参考 [TiDB 软硬件环境需求](/dev/how-to/deploy/hardware-recommendations.md)。 - -### 2.2 安装部署 - -#### 2.2.1 Ansible 部署方式（强烈推荐） - -详细可参考[使用 TiDB Ansible 部署 TiDB 集群](/dev/how-to/deploy/orchestrated/ansible.md)。 - -##### 2.2.1.1 为什么修改了 TiKV/PD 的 toml 配置文件，却没有生效？ - -这种情况一般是因为没有使用 `--config` 参数来指定配置文件（目前只会出现在 binary 部署的场景），TiKV/PD 会按默认值来设置。如果要使用配置文件，请设置 TiKV/PD 的 `--config` 参数。对于 TiKV 组件，修改配置后重启服务即可；对于 PD 组件，只会在第一次启动时读取配置文件，之后可以使用 pd-ctl 的方式来修改配置，详情可参考 [PD 配置参数](/dev/reference/configuration/pd-server/configuration.md)。 - -##### 2.2.1.2 TiDB 监控框架 Prometheus + Grafana 监控机器建议单独还是多台部署？ - -监控机建议单独部署。建议 CPU 8 core，内存 16 GB 以上，硬盘 500 GB 以上。 - -##### 2.2.1.3 有一部分监控信息显示不出来？ - -查看访问监控的机器时间跟集群内机器的时间差，如果比较大，更正时间后即可显示正常。 - -##### 2.2.1.4 supervise/svc/svstat 服务具体起什么作用？ - -- supervise 守护进程 -- svc 启停服务 -- svstat 查看进程状态 - -##### 2.2.1.5 inventory.ini 变量参数解读 - -| **变量** | **含义** | -| --- | --- | -| cluster_name | 集群名称，可调整 | -| tidb_version | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| deployment_method | 部署方式，默认为 binary，可选 docker | -| process_supervision | 进程监管方式，默认为 systemd，可选 supervise | -| timezone | 修改部署目标机器时区，默认为 Asia/Shanghai, 可调整，与set_timezone 变量结合使用 | -| set_timezone | 默认为 True，即修改部署目标机器时区，关闭可修改为 False | -| enable_elk | 目前不支持，请忽略 | -| enable_firewalld | 开启防火墙，默认不开启 | -| enable_ntpd | 检测部署目标机器 NTP 服务，默认为 True，请勿关闭 | -| machine_benchmark | 检测部署目标机器磁盘 IOPS，默认为 True，请勿关闭 | -| set_hostname | 根据 IP 修改部署目标机器主机名，默认为 False | -| enable_binlog | 是否部署 pump 并开启 binlog，默认为 False，依赖 Kafka 集群，参见 zookeeper_addrs 变量 | -| zookeeper_addrs | binlog Kafka 集群的 zookeeper 地址 | -| enable_slow_query_log | TiDB 慢查询日志记录到单独文件({{ deploy_dir }}/log/tidb_slow_query.log)，默认为 False，记录到 tidb 日志 | -| deploy_without_tidb | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 inventory.ini 文件中 tidb_servers 主机组 IP 设置为空。 | - -#### 2.2.2 TiDB 离线 Ansible 部署方案 - -首先这不是我们建议的方式，如果中控机没有外网，也可以通过离线 Ansible 部署方式，详情可参考[离线 TiDB Ansible 部署方案](/dev/how-to/deploy/orchestrated/offline-ansible.md)。 - -#### 2.2.3 Docker Compose 快速构建集群（单机部署） - -使用 docker-compose 在本地一键拉起一个集群，包括集群监控，还可以根据需求自定义各个组件的软件版本和实例个数，以及自定义配置文件，这种只限于开发环境，详细可参考[官方文档](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -#### 2.2.4 如何单独记录 TiDB 中的慢查询日志，如何定位慢查询 SQL？ - -1）TiDB 中，对慢查询的定义在 tidb-ansible 的 `conf/tidb.yml` 配置文件中，`slow-threshold: 300`，这个参数是配置慢查询记录阈值的，单位是 ms。 - -慢查询日志默认记录到 tidb.log 中，如果希望生成单独的慢查询日志文件，修改 inventory.ini 配置文件的参数 `enable_slow_query_log` 为 True。 - -如上配置修改之后，需要执行 `ansible-playbook rolling_update.yml --tags=tidb`，对 tidb-server 实例进行滚动升级，升级完成后，tidb-server 将在 `tidb_slow_query.log` -文件中记录慢查询日志。 - -2）如果出现了慢查询，可以从 Grafana 监控定位到出现慢查询的 tidb-server 以及时间点，然后在对应节点查找日志中记录的 SQL 信息。 - -3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md#admin-show-slow-命令)。 - -#### 2.2.5 首次部署 TiDB 集群时，没有配置 tikv 的 Label 信息，在后续如何添加配置 Label？ - -TiDB 的 Label 设置是与集群的部署架构相关的，是集群部署中的重要内容，是 PD 进行全局管理和调度的依据。如果集群在初期部署过程中没有设置 Label，需要在后期对部署结构进行调整，就需要手动通过 PD 的管理工具 pd-ctl 来添加 location-labels 信息，例如：`config set location-labels "zone,rack,host"`（根据实际的 label 层级名字配置）。 - -pd-ctl 的使用参考 [PD Control 使用说明](/dev/reference/tools/pd-control.md)。 - -#### 2.2.6 为什么测试磁盘的 dd 命令用 oflag=direct 这个选项？ - -Direct 模式就是把写入请求直接封装成 I/O 指令发到磁盘，这样是为了绕开文件系统的缓存，可以直接测试磁盘的真实的 I/O 读写能力。 - -#### 2.2.7 如何用 fio 命令测试 TiKV 实例的磁盘性能？ - -- 随机读测试： - - {{< copyable "shell-regular" >}} - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randread -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json - ``` - -- 顺序写和随机读混合测试： - - {{< copyable "shell-regular" >}} - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randrw -percentage_random=100,0 -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json - ``` - -#### 2.2.8 使用 TiDB Ansible 部署 TiDB 集群的时候，遇到 `UNREACHABLE! "msg": "Failed to connect to the host via ssh: "` 报错是什么原因？ - -有两种可能性： - -- ssh 互信的准备工作未做好，建议严格参照我们的[官方文档步骤](/dev/how-to/deploy/orchestrated/ansible.md)配置互信，并使用命令 `ansible -i inventory.ini all -m shell -a 'whoami' -b` 来验证互信配置是否成功。 - -- 如果涉及到单服务器分配了多角色的场景，例如多组件混合部署或单台服务器部署了多个 TiKV 实例，可能是由于 ssh 复用的机制引起这个报错，可以使用 `ansible … -f 1` 的选项来规避这个报错。 - -### 2.3 升级 - -#### 2.3.1 如何使用 Ansible 滚动升级？ - -滚动升级 TiKV 节点( 只升级单独服务 ) - -`ansible-playbook rolling_update.yml --tags=tikv` - -滚动升级所有服务 - -`ansible-playbook rolling_update.yml` - -#### 2.3.2 滚动升级有那些影响? - -滚动升级 TiDB 服务，滚动升级期间不影响业务运行，需要配置最小集群拓扑（TiDB \* 2、PD \* 3、TiKV \* 3），如果集群环境中有 Pump/Drainer 服务，建议先停止 Drainer 后滚动升级（升级 TiDB 时会升级 Pump）。 - -#### 2.3.3 Binary 如何升级？ - -Binary 不是我们建议的安装方式，对升级支持也不友好，建议换成 Ansible 部署。 - -#### 2.3.4 一般升级选择升级 TiKV 还是所有组件都升级？ - -常规需要一起升，因为整个版本都是一起测试的，单独升级只限当发生一个紧急故障时，需要单独对一个有问题的角色做升级。 - -#### 2.3.5 启动集群或者升级集群过程中出现 “Timeout when waiting for search string 200 OK” 是什么原因？如何处理？ - -可能有以下几种原因：进程没有正常启动；端口被占用；进程没有正常停掉；停掉集群的情况下使用 rolling_update.yml 来升级集群（操作错误）。 - -处理方式：登录到相应节点查看进程或者端口的状态；纠正错误的操作步骤。 - -## 三、集群管理 - -### 3.1 集群日常管理 - -#### 3.1.1 Ansible 常见运维操作有那些？ - -| **任务** | **Playbook** | -| --- | --- | -| 启动集群 | ansible-playbook start.yml | -| 停止集群 | ansible-playbook stop.yml | -| 销毁集群 | ansible-playbook unsafe\_cleanup.yml (若部署目录为挂载点，会报错，可忽略） | -| 清除数据(测试用) | ansible-playbook cleanup\_data.yml | -| 滚动升级 | ansible-playbook rolling\_update.yml | -| 滚动升级 TiKV | ansible-playbook rolling\_update.yml --tags=tikv | -| 滚动升级除 PD 外模块 | ansible-playbook rolling\_update.yml --skip-tags=pd | -| 滚动升级监控组件 | ansible-playbook rolling\_update\_monitor.yml | - -#### 3.1.2 TiDB 如何登录？ - -和 MySQL 登录方式一样，可以按照下面例子进行登录。 - -`mysql -h 127.0.0.1 -uroot -P4000` - -#### 3.1.3 TiDB 如何修改数据库系统变量？ - -和 MySQL 一样，TiDB 也分为静态参数和固态参数，静态参数可以直接通过`set global xxx = n`的方式进行修改，不过新参数值只限于该实例生命周期有效。 - -#### 3.1.4 TiDB (TiKV) 有哪些数据目录？ - -默认在 [`--data-dir`](/dev/reference/configuration/tikv-server/configuration.md#--data-dir) 目录下，其中包括 backup、db、raft、snap 四个目录，分别存储备份、数据、raft 数据及镜像数据。 - -#### 3.1.5 TiDB 有哪些系统表？ - -和 MySQL 类似，TiDB 中也有系统表，用于存放数据库运行时所需信息，具体信息参考 [TiDB 系统数据库](/dev/reference/system-databases/mysql.md)文档。 - -#### 3.1.6 TiDB 各节点服务器下是否有日志文件，如何管理？ - -默认情况下各节点服务器会在日志中输出标准错误，如果启动的时候通过 `--log-file` 参数指定了日志文件，那么日志会输出到指定的文件中，并且按天做 rotation。 - -#### 3.1.7 如何规范停止 TiDB？ - -如果是用 Ansible 部署的，可以使用 `ansible-playbook stop.yml` 命令停止 TiDB 集群。如果不是 Ansible 部署的，可以直接 kill 掉所有服务。如果使用 kill 命令，TiDB 的组件会做 graceful 的 shutdown。 - -#### 3.1.8 TiDB 里面可以执行 kill 命令吗？ - -- 可以 kill DML 语句，首先使用 `show processlist`，找到对应 session 的 id，然后执行 `kill tidb [session id]`。 -- 可以 kill DDL 语句，首先使用 `admin show ddl jobs`，查找需要 kill 的 DDL job ID，然后执行 `admin cancel ddl jobs 'job_id' [, 'job_id'] ...`。具体可以参考 [admin 操作](/dev/reference/sql/statements/admin.md)。 - -#### 3.1.9 TiDB 是否支持会话超时？ - -TiDB 暂不支持数据库层面的会话超时，目前想要实现超时，在没 LB（Load Balancing）的时候，需要应用侧记录发起的 Session 的 ID，通过应用自定义超时，超时以后需要到发起 Query 的节点上用 `kill tidb [session id]` 来杀掉 SQL。目前建议使用应用程序来实现会话超时，当达到超时时间，应用层就会抛出异常继续执行后续的程序段。 - -#### 3.1.10 TiDB 生产环境的版本管理策略是怎么样的？如何尽可能避免频繁升级？ - -TiDB 版本目前逐步标准化，每次 Release 都包含详细的 Change log，版本功能[变化详情](https://github.com/pingcap/TiDB/releases)，生产环境是否有必要升级取决于业务系统，建议升级之前详细了解前后版本的功能差异。 - -版本号说明参考：Release Version: `v1.0.3-1-ga80e796` - -- `v1.0.3` 表示 GA 标准版 -- `1` 表示该版本 commit 1 次 -- `ga80e796` 代表版本的 `git-hash` - -#### 3.1.11 分不清 TiDB master 版本之间的区别，经常用错 TiDB Ansible 版本? - -TiDB 目前社区非常活跃，在 1.0 GA 版本发布后，还在不断的优化和修改 BUG，因此 TiDB 的版本更新周期比较快，会不定期有新版本发布，请关注我们的[新版本发布官方网站](https://pingcap.com/weekly/)。此外 TiDB 安装推荐使用 TiDB Ansible 进行安装，TiDB Ansible 的版本也会随着 TiDB 的版本发布进行更新，因此建议用户在安装升级新版本的时候使用最新的 TiDB Ansible 安装包版本进行安装。此外，在 TiDB 1.0 GA 版本后，对 TiDB 的版本号进行了统一管理，TiDB 的版本可以通过以下两种方式进行查看： - -- 通过 `select tidb_version()` 进行查看 -- 通过执行 `tidb-server -V` 进行查看 - -#### 3.1.12 有没有图形化部署 TiDB 的工具？ - -暂时没有。 - -#### 3.1.13 TiDB 如何进行水平扩展？ - -当您的业务不断增长时，数据库可能会面临三方面瓶颈，第一是存储空间，第二是计算资源，第三是读写容量，这时可以对 TiDB 集群做水平扩展。 - -- 如果是存储资源不够，可以通过添加 TiKV Server 节点来解决，新节点启动后，PD 会自动将其他节点的部分数据迁移过去，无需人工介入。 -- 如果是计算资源不够，可以查看 TiDB Server 和 TiKV Server 节点的 CPU 消耗情况，再考虑添加 TiDB Server 节点或者是 TiKV Server 节点来解决，如添加 TiDB Server 节点，将其添加到前端 Load Balancer 配置之中即可。 -- 如果是容量跟不上，一般可以考虑同时增加 TiDB Server 和 TiKV Server 节点。 - -#### 3.1.14 Percolator 用了分布式锁，crash 的客户端会保持锁，会造成锁没有 release？ - -详细可参考 [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/)。 - -#### 3.1.15 TiDB 为什么选用 gRPC 而不选用 Thrift，是因为 Google 在用吗？ - -不只是因为 Google 在用，有一些比较好的特性我们需要，比如流控、加密还有 Streaming。 - -#### 3.1.16 like(bindo.customers.name, jason%, 92) 这个92代表什么？ - -那个是转义字符，默认是 (ASCII 92)。 - -#### 3.1.17 为什么 `information_schema.tables.data_length` 记录的大小和 TiKV 监控面板上的 store size 不一样？ - -这是因为两者计算的角度不一样。`information_schema.tables.data_length` 是通过统计信息（平均每行的大小）得到的估算值。TiKV 监控面板上的 store size 是单个 TiKV 实例的数据文件（RocksDB 的 SST 文件）的大小总和。由于多版本和 TiKV 会压缩数据，所以两者显示的大小不一样。 - -### 3.2 PD 管理 - -#### 3.2.1 访问 PD 报错：TiKV cluster is not bootstrapped - -PD 的大部分 API 需要在初始化 TiKV 集群以后才能使用，如果在部署新集群的时候只启动了 PD，还没有启动 TiKV，这时候访问 PD 就会报这个错误。遇到这个错误应该先把要部署的 TiKV 启动起来，TiKV 会自动完成初始化工作，然后就可以正常访问 PD。 - -#### 3.2.2 PD 启动报错：etcd cluster ID mismatch - -PD 启动参数中的 `--initial-cluster` 包含了某个不属于该集群的成员。遇到这个错误时请检查各个成员的所属集群，剔除错误的成员后即可正常启动。 - -#### 3.2.3 PD 能容忍的时间同步误差是多少？ - -理论上，时间同步误差越小越好。PD 可容忍任意时长的误差，但是，时间同步误差越大意味着 PD 分配的时间戳与真实的物理时间相差越大，这个差距会影响读历史版本等功能。 - -#### 3.2.4 Client 连接是如何寻找 PD 的？ - -Client 连接只能通过 TiDB 访问集群，TiDB 负责连接 PD 与 TiKV，PD 与 TiKV 对 Client 透明。当 TiDB 连接任意一台 PD 的时候，PD 会告知 TiDB 当前的 leader 是谁，如果此台 PD 不是 leader，TiDB 将会重新连接至 leader PD。 - -#### 3.2.5 PD 参数中 leader-schedule-limit 和 region-schedule-limit 调度有什么区别？ - -- leader-schedule-limit 调度是用来均衡不同 TiKV 的 leader 数，影响处理查询的负载。 -- region-schedule-limit 调度是均衡不同 TiKV 的副本数，影响不同节点的数据量。 - -#### 3.2.6 每个 region 的 replica 数量可配置吗？调整的方法是？ - -可以，目前只能调整全局的 replica 数量。首次启动时 PD 会读配置文件（conf/pd.yml），使用其中的 max-replicas 配置，之后修改需要使用 pd-ctl 配置命令 `config set max-replicas $num`，配置后可通过 `config show all` 来查看已生效的配置。调整的时候，不会影响业务，会在后台添加，注意总 TiKV 实例数总是要大于等于设置的副本数，例如 3 副本需要至少 3 个 TiKV。增加副本数量之前需要预估额外的存储需求。pd-ctl 的详细用法可参考 [PD Control 使用说明](/dev/reference/tools/pd-control.md)。 - -#### 3.2.7 缺少命令行集群管理工具，整个集群的健康度当前是否正常，不好确认？ - -可以通过 pd-ctl 等工具来判断集群大概的状态，详细的集群状态还是需要通过监控来确认。 - -#### 3.2.8 集群下线节点后，怎么删除老集群节点监控信息？ - -下线节点一般指 TiKV 节点通过 pd-ctl 或者监控判断节点是否下线完成。节点下线完成后，手动停止下线节点上相关的服务。从 Prometheus 配置文件中删除对应节点的 node_exporter 信息。从 Ansible inventory.ini 中删除对应节点的信息。 - -#### 3.2.9 使用 PD Control 连接 PD Server 时，为什么只能通过本机 IP 连接，不能通过 127.0.0.1 连接？ - -因为使用 TiDB Ansible 部署的集群，PD 对外服务端口不会绑定到 127.0.0.1，所以 PD Control 不会识别 127.0.0.1。 - -### 3.3 TiDB server 管理 - -#### 3.3.1 TiDB 的 lease 参数应该如何设置？ - -启动 TiDB Server 时，需要通过命令行参数设置 lease 参数（--lease=60），其值会影响 DDL 的速度（只会影响当前执行 DDL 的 session，其他的 session 不会受影响）。在测试阶段，lease 的值可以设为 1s，加快测试进度；在生产环境下，我们推荐这个值设为分钟级（一般可以设为 60），这样可以保证 DDL 操作的安全。 - -#### 3.3.2 DDL 在正常情况下的耗时是多少？ - -一般情况下处理一个 DDL 操作（之前没有其他 DDL 操作在处理）的耗时基本可以分如下为三种： - -- add index 操作，且此操作对应表数据行数比较少，耗时约为 3s。 -- add index 操作，且此操作对应表数据行数比较多，耗时具体由表中数据行数和当时 QPS 情况定（add index 操作优先级比一般 SQL 低）。 -- 其他 DDL 操作耗时约为 1s。 - -此外，如果接收 DDL 请求的 TiDB 和 DDL owner 所处的 TiDB 是一台，那么上面列举的第一和第三种可能的耗时应该在几十到几百毫秒。 - -#### 3.3.3 为什么有的时候执行 DDL 会很慢？ - -可能原因如下： - -- 多个 DDL 语句一起执行的时候，后面的几个 DDL 语句会比较慢。原因是当前 TiDB 集群中 DDL 操作是串行执行的。 -- 在正常集群启动后，第一个 DDL 操作的执行时间可能会比较久，一般在 30s 左右，这个原因是刚启动时 TiDB 在竞选处理 DDL 的 leader。 -- 由于停 TiDB 时不能与 PD 正常通信（包括停电情况）或者用 `kill -9` 指令停 TiDB 导致 TiDB 没有及时从 PD 清理注册数据，那么会影响 TiDB 启动后 10min 内的 DDL 语句处理时间。这段时间内运行 DDL 语句时，每个 DDL 状态变化都需要等待 2 * lease（默认 lease = 45s）。 -- 当集群中某个 TiDB 与 PD 之间发生通信问题，即 TiDB 不能从 PD 及时获取或更新版本信息，那么这时候 DDL 操作的每个状态处理需要等待 2 * lease。 - -#### 3.3.4 TiDB 可以使用 S3 作为后端存储吗？ - -不可以，目前 TiDB 只支持分布式存储引擎和 GolevelDB/RocksDB/BoltDB 引擎。 - -#### 3.3.5 Information_schema 能否支持更多真实信息？ - -Information_schema 库里面的表主要是为了兼容 MySQL 而存在，有些第三方软件会查询里面的信息。在目前 TiDB 的实现中，里面大部分只是一些空表。后续随着 TiDB 的升级，会提供更多的参数信息。当前 TiDB 支持的 Information\_schema 请参考 [TiDB 系统数据库说明文档](/dev/reference/system-databases/information-schema.md)。 - -#### 3.3.6 TiDB Backoff type 主要原因? - -TiDB-server 与 TiKV-server 随时进行通信，在进行大量数据操作过程中，会出现 `Server is busy` 或者 `backoff.maxsleep 20000ms` 的日志提示信息，这是由于 TiKV-server 在处理过程中系统比较忙而出现的提示信息，通常这时候可以通过系统资源监控到 TiKV 主机系统资源使用率比较高的情况出现。如果这种情况出现，可以根据资源使用情况进行相应的扩容操作。 - -#### 3.3.7 TiDB TiClient type 主要原因？ - -TiClient Region Error 该指标描述的是在 TiDB-server 作为客户端通过 KV 接口访问 TiKV-server 进行数据操作过程中，TiDB-server 操作 TiKV-server 中的 Region 数据出现的错误类型与 metric 指标，错误类型包括 not_leader、stale_epoch。出现这些错误的情况是当 TiDB-server 根据自己的缓存信息去操作 Region leader 数据的时候，Region leader 发生了迁移或者 TiKV 当前的 Region 信息与 TiDB 缓存的路由信息不一致而出现的错误提示。一般这种情况下，TiDB-server 都会自动重新从 PD 获取最新的路由数据，重做之前的操作。 - -#### 3.3.8 TiDB 同时支持的最大并发连接数？ - -当前版本 TiDB 没有最大连接数的限制，如果并发过大导致响应时间增加，可以通过增加 TiDB 节点进行扩容。 - -#### 3.3.9 如何查看某张表创建的时间？ - -information_schema 库中的 tables 表里的 create_time 即为表的真实创建时间。 - -#### 3.3.9 TiDB 的日志中 EXPENSIVE_QUERY 是什么意思？ - -TiDB 在执行 SQL 时，预估出来每个 operator 处理了超过 10000 条数据就认为这条 query 是 expensive query。可以通过修改 tidb-server 配置参数来对这个门限值进行调整，调整后需要重新启动 tidb-server。 - -#### 3.3.10 在 TiDB 中如何控制或改变 SQL 提交的执行优先级？ - -TiDB 支持改变 [per-session](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_force_priority)、[全局](/dev/reference/configuration/tidb-server/configuration-file.md#force-priority)或单个语句的优先级。优先级包括： - -- HIGH_PRIORITY：该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句 -- LOW_PRIORITY：该语句为低优先级语句，TiDB 在执行阶段会降低这条语句的优先级 - -以上两种参数可以结合 TiDB 的 DML 语言进行使用，使用方法举例如下： - -1. 通过在数据库中写 SQL 的方式来调整优先级： - - {{< copyable "sql" >}} - - ```sql - select HIGH_PRIORITY | LOW_PRIORITY count(*) from table_name; - insert HIGH_PRIORITY | LOW_PRIORITY into table_name insert_values; - delete HIGH_PRIORITY | LOW_PRIORITY from table_name; - update HIGH_PRIORITY | LOW_PRIORITY table_reference set assignment_list where where_condition; - replace HIGH_PRIORITY | LOW_PRIORITY into table_name; - ``` - -2. 全表扫会自动调整为低优先级，analyze 也是默认低优先级。 - -#### 3.3.11 在 TiDB 中 auto analyze 的触发策略是怎样的？ - -触发策略：新表达到 1000 条，并且在 1 分钟内没有写入，会自动触发。 - -当表的（修改数/当前总行数）大于 `tidb_auto_analyze_ratio` 的时候，会自动触发 `analyze` 语句。`tidb_auto_analyze_ratio` 的默认值为 0.5，即默认开启此功能。为了保险起见，在开启此功能的时候，保证了其最小值为 0.3。但是不能大于等于 `pseudo-estimate-ratio`（默认值为 0.8），否则会有一段时间使用 pseudo 统计信息，建议设置值为 0.5。 - -#### 3.3.12 SQL 中如何通过 hint 使用一个具体的 index？ - -同 MySQL 的用法一致，例如： -`select column_name from table_name use index（index_name）where where_condition;` - -#### 3.3.13 触发 Information schema is changed 错误的原因？ - -TiDB 在执行 SQL 语句时，会使用当时的 `schema` 来处理该 SQL 语句，而且 TiDB 支持在线异步变更 DDL。那么，在执行 DML 的时候可能有 DDL 语句也在执行，而你需要确保每个 SQL 语句在同一个 `schema` 上执行。所以当执行 DML 时，遇到正在执行中的 DDL 操作就可能会报 `Information schema is changed` 的错误。为了避免太多的 DML 语句报错，已做了一些优化。 - -现在会报此错的可能原因如下（后两个报错原因与表无关）： - -- 执行的 DML 语句中涉及的表和集群中正在执行的 DDL 的表有相同的，那么这个 DML 语句就会报此错。 -- 这个 DML 执行时间很久，而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 1024 （此为默认值，可以通过 `tidb_max_delta_schema_count` 变量修改）。 -- 接受 DML 请求的 TiDB 长时间不能加载到 `schema information`（TiDB 与 PD 或 TiKV 之间的网络连接故障等会导致此问题），而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 100。 - -> **注意：** -> -> + 目前 TiDB 未缓存所有的 `schema` 版本信息。 -> + 对于每个 DDL 操作，`schema` 版本变更的数量与对应 `schema state` 变更的次数一致。 -> + 不同的 DDL 操作版本变更次数不一样。例如，`create table` 操作会有 1 次 `schema` 版本变更；`add column` 操作有 4 次 `schema` 版本变更。 - -#### 3.3.14 触发 Information schema is out of date 错误的原因？ - -当执行 DML 时，TiDB 超过一个 DDL lease 时间（默认 45s）没能加载到最新的 schema 就可能会报 `Information schema is out of date` 的错误。遇到此错的可能原因如下： - -- 执行此 DML 的 TiDB 被 kill 后准备退出，且此 DML 对应的事务执行时间超过一个 DDL lease，在事务提交时会报这个错误。 -- TiDB 在执行此 DML 时，有一段时间内连不上 PD 或者 TiKV，导致 TiDB 超过一个 DDL lease 时间没有 load schema，或者导致 TiDB 断开与 PD 之间带 keep alive 设置的连接。 - -#### 3.3.15 高并发情况下执行 DDL 时报错的原因？ - -高并发情况下执行 DDL（比如批量建表）时，极少部分 DDL 可能会由于并发执行时 key 冲突而执行失败。 - -并发执行 DDL 时，建议将 DDL 数量保持在 20 以下，否则你需要在应用端重试失败的 DDL 语句。 - -### 3.4 TiKV 管理 - -#### 3.4.1 TiKV 集群副本建议配置数量是多少，是不是最小高可用配置（3个）最好？ - -如果是测试环境 3 副本足够；在生产环境中，不可让集群副本数低于 3，需根据架构特点、业务系统及恢复能力的需求，适当增加副本数。值得注意的是，副本升高，性能会有下降，但是安全性更高。 - -#### 3.4.2 TiKV 启动报错：cluster ID mismatch - -TiKV 本地存储的 cluster ID 和指定的 PD 的 cluster ID 不一致。在部署新的 PD 集群的时候，PD 会随机生成一个 cluster ID，TiKV 第一次初始化的时候会从 PD 获取 cluster ID 存储在本地，下次启动的时候会检查本地的 cluster ID 与 PD 的 cluster ID 是否一致，如果不一致则会报错并退出。出现这个错误一个常见的原因是，用户原先部署了一个集群，后来把 PD 的数据删除了并且重新部署了新的 PD，但是 TiKV 还是使用旧的数据重启连到新的 PD 上，就会报这个错误。 - -#### 3.4.3 TiKV 启动报错：duplicated store address - -启动参数中的地址已经被其他的 TiKV 注册在 PD 集群中了。造成该错误的常见情况：TiKV `--data-dir` 指定的路径下没有数据文件夹（删除或移动后没有更新 --data-dir），用之前参数重新启动该 TiKV。请尝试用 pd-ctl 的 [store delete](https://github.com/pingcap/pd/tree/55db505e8f35e8ab4e00efd202beb27a8ecc40fb/tools/pd-ctl#store-delete--label--weight-store_id----jqquery-string) 功能，删除之前的 store，然后重新启动 TiKV 即可。 - -#### 3.4.4 TiKV master 和 slave 用的是一样的压缩算法，为什么效果不一样? - -目前来看 master 有些文件的压缩率会高一些，这个取决于底层数据的分布和 RocksDB 的实现，数据大小偶尔有些波动是正常的，底层存储引擎会根据需要调整数据。 - -#### 3.4.5 TiKV block cache 有哪些特性？ - -TiKV 使用了 RocksDB 的 Column Family (CF) 特性，KV 数据最终存储在默认 RocksDB 内部的 default、write、lock 3 个 CF 内。 - -- default CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中。 -- write CF 存储的是数据的版本信息（MVCC）、索引、小表相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中。 -- lock CF 存储的是锁信息，系统使用默认参数。 -- Raft RocksDB 实例存储 Raft log。default CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 -- 所有 CF 共享一个 Block-cache，用于缓存数据块，加速 RocksDB 的读取速度，Block-cache 的大小通过参数 `block-cache-size` 控制，`block-cache-size` 越大，能够缓存的热点数据越多，对读取操作越有利，同时占用的系统内存也会越多。 -- 每个 CF 有各自的 Write-buffer，大小通过 `write-buffer-size` 控制。 - -#### 3.4.6 TiKV channel full 是什么原因？ - -- Raftstore 线程太忙，或者因 I/O 而卡住。可以看一下 Raftstore 的 CPU 使用情况。 -- TiKV 过忙（CPU、磁盘 I/O 等），请求处理不过来。 - -#### 3.4.7 TiKV 频繁切换 Region leader 是什么原因？ - -- 网络问题导致节点间通信卡了，查看 Report failures 监控。 -- 原主 Leader 的节点卡了，导致没有及时给 Follower 发送消息。 -- Raftstore 线程卡了。 - -#### 3.4.8 如果一个节点挂了会影响服务吗？影响会持续多久？ - -TiDB 使用 Raft 在多个副本之间做数据同步（默认为每个 Region 3 个副本）。当一份备份出现问题时，其他的副本能保证数据的安全。根据 Raft 协议，当某个节点挂掉导致该节点里的 Leader 失效时，在最大 2 * lease time（leasetime 是 10 秒）时间后，通过 Raft 协议会很快将一个另外一个节点里的 Follower 选为新的 Region Leader 来提供服务。 - -#### 3.4.9 TiKV 在分别在那些场景下占用大量 IO、内存、CPU（超过参数配置的多倍）？ - -在大量写入、读取的场景中会占用大量的磁盘 IO、内存、CPU。在执行很复杂的查询，比如会产生很大中间结果集的情况下，会消耗很多的内存和 CPU 资源。 - -#### 3.4.10 TiKV 是否可以使用 SAS/SATA 盘或者进行 SSD/SAS 混合部署？ - -不可以使用，TiDB 在进行 OLTP 场景中，数据访问和操作需要高 IO 磁盘的支持，TiDB 作为强一致的分布式数据库，存在一定的写放大，如副本复制、存储底层 Compaction，因此，TiDB 部署的最佳实践中推荐用户使用 NVMe SSD 磁盘作为数据存储磁盘。另外，TiKV 与 PD 不能混合部署。 - -#### 3.4.11 数据表 Key 的 Range 范围划分是在数据接入之前就已经划分好了吗？ - -不是的，这个和 MySQL 分表规则不一样，需要提前设置好，TiKV 是根据 Region 的大小动态分裂的。 - -#### 3.4.12 Region 是如何进行分裂的？ - -Region 不是前期划分好的，但确实有 Region 分裂机制。当 Region 的大小超过参数 `region-max-size` 或 `region-max-keys` 的值时，就会触发分裂，分裂后的信息会汇报给 PD。 - -#### 3.4.13 TiKV 是否有类似 MySQL 的 `innodb_flush_log_trx_commit` 参数，来保证提交数据不丢失？ - -是的，TiKV 单机的存储引擎目前使用两个 RocksDB 实例，其中一个存储 raft-log，TiKV 有个 sync-log 参数，在 ture 的情况下，每次提交都会强制刷盘到 raft-log，如果发生 crash 后，通过 raft-log 进行 KV 数据的恢复。 - -#### 3.4.14 对 WAL 存储有什么推荐的硬件配置，例如 SSD，RAID 级别，RAID 卡 cache 策略，NUMA 设置，文件系统选择，操作系统的 IO 调度策略等？ - -WAL 属于顺序写，目前我们并没有单独对他进行配置，建议 SSD，RAID 如果允许的话，最好是 RAID 10，RAID 卡 cache、操作系统 I/O 调度目前没有针对性的最佳实践，Linux 7 以上默认配置即可，NUMA 没有特别建议，NUMA 内存分配策略可以尝试使用 `interleave = all`，文件系统建议 ext4。 - -#### 3.4.15 在最严格的 `sync-log = true` 数据可用模式下，写入性能如何？ - -一般来说，开启 `sync-log` 会让性能损耗 30% 左右。关闭 `sync-log` 时的性能表现，请参见 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 - -#### 3.4.16 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠，单机存储引擎是否需要最严格模式？ - -通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。但理论上两个节点也可能同时发生故障，所以除非是对性能要求高于数据安全的场景，一般都强烈推荐开启 `sync-log`。 - -另外，还有一种 `sync-log` 的替代方案，即在 Raft group 中用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 - -对于单机存储引擎也同样推荐打开 `sync-log` 模式。否则如果节点宕机可能会丢失最后一次写入数据。 - -#### 3.4.17 使用 Raft 协议，数据写入会有多次网络的 roundtrip，实际写入延迟如何？ - -理论上，和单机数据库相比，数据写入会多四个网络延迟。 - -#### 3.4.18 有没有类似 MySQL 的 InnoDB Memcached plugin，可以直接使用 KV 接口，可以不需要独立的 Cache？ - -TiKV 支持单独进行接口调用，理论上也可以起个实例做为 Cache，但 TiDB 最大的价值是分布式关系型数据库，我们原则上不对 TiKV 单独进行支持。 - -#### 3.4.19 Coprocessor 组件的主要作用？ - -- 减少 TiDB 与 TiKV 之间的数据传输。 -- 计算下推，充分利用 TiKV 的分布式计算资源。 - -#### 3.4.20 IO error: No space left on device While appending to file - -这是磁盘空间不足导致的，需要加节点或者扩大磁盘空间。 - -#### 3.4.21 为什么 TiKV 容易出现 OOM？ - -TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总内存的 40%。当 TiKV 容易出现 OOM 时，检查 `block-cache-size` 配置是否过高。还需要注意，当单机部署了多个 TiKV 实例时，需要显式地配置该参数，以防止多个实例占用过多系统内存导致 OOM。 - -#### 3.4.22 TiDB 数据和 RawKV 数据可存储于同一个 TiKV 集群里吗？ - -不可以。TiDB 数据（或使用其他事务 API 生成的数据）依赖于一种特殊的键值格式，和 RawKV API 数据（或其他基于 RawKV 的服务生成的数据）并不兼容。 - -### 3.5 TiDB 测试 - -#### 3.5.1 TiDB Sysbench 基准测试结果如何？ - -很多用户在接触 TiDB 都习惯做一个基准测试或者 TiDB 与 MySQL 的对比测试，官方也做了一个类似测试，汇总很多测试结果后，我们发现虽然测试的数据有一定的偏差，但结论或者方向基本一致，由于 TiDB 与 MySQL 由于架构上的差别非常大，很多方面是很难找到一个基准点，所以官方的建议两点： - -- 大家不要用过多精力纠结这类基准测试上，应该更多关注 TiDB 的场景上的区别。 -- 大家可以直接参考 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 - -#### 3.5.2 TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？ - -- 在 10 节点内，TiDB 写入能力（Insert TPS）和节点数量基本成 40% 线性递增，MySQL 由于是单节点写入，所以不具备写入扩展能力。 -- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://t.cn/RTD18qV)。 -- TiDB 不管是读流量、还是写流量都可以通过添加节点快速方便的进行扩展。 - -#### 3.5.3 我们的 DBA 测试过 MySQL 性能，单台 TiDB 的性能没有 MySQL 性能那么好？ - -TiDB 设计的目标就是针对 MySQL 单台容量限制而被迫做的分库分表的场景，或者需要强一致性和完整分布式事务的场景。它的优势是通过尽量下推到存储节点进行并行计算。对于小表（比如千万级以下），不适合 TiDB，因为数据量少，Region 有限，发挥不了并行的优势，最极端的就是计数器表，几行记录高频更新，这几行在 TiDB 里，会变成存储引擎上的几个 KV，然后只落在一个 Region 里，而这个 Region 只落在一个节点上。加上后台强一致性复制的开销，TiDB 引擎到 TiKV 引擎的开销，最后表现出来的就是没有单个 MySQL 好。 - -### 3.6 TiDB 备份恢复 - -#### 3.6.1 TiDB 主要备份方式？ - -目前，推荐的备份方式是使用 [PingCAP fork 的 Mydumper](/dev/reference/tools/mydumper.md)。尽管 TiDB 也支持使用 MySQL 官方工具 `mysqldump` 进行数据备份、恢复，但其性能低于 [`mydumper`](/dev/reference/tools/mydumper.md)/[`loader`](/dev/reference/tools/loader.md)，并且该工具备份、恢复大量数量时，要耗费更多时间。 - -使用 Mydumper 导出来的数据文件尽可能的小, 最好不要超过 64M, 可以设置参数 -F 64； - -loader 的 -t 参数可以根据 TiKV 的实例个数以及负载进行评估调整，例如 3 个 TiKV 的场景， 此值可以设为 3 * (1 ～ n)，当 TiKV 负载过高，loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 可以适当调小该值，当 TiKV 负载不是太高的时候，可以适当调大该值。 - -## 四、数据、流量迁移 - -### 4.1 全量数据导出导入 - -#### 4.1.1 Mydumper - -参见 [Mydumper 使用文档](/dev/reference/tools/mydumper.md)。 - -#### 4.1.2 Loader - -参见 [Loader 使用文档](/dev/reference/tools/loader.md)。 - -#### 4.1.3 如何将一个运行在 MySQL 上的应用迁移到 TiDB 上？ - -TiDB 支持绝大多数 MySQL 语法，一般不需要修改代码。 - -#### 4.1.4 不小心把 MySQL 的 user 表导入到 TiDB 了，或者忘记密码，无法登录，如何处理？ - -重启 TiDB 服务，配置文件中增加 `-skip-grant-table=true` 参数，无密码登录集群后，可以根据情况重建用户，或者重建 mysql.user 表，具体表结构搜索官网。 - -#### 4.1.5 在 Loader 运行的过程中，TiDB 可以对外提供服务吗？ - -该操作进行逻辑插入，TiDB 仍可对外提供服务，但不要执行相关 DDL 操作。 - -#### 4.1.6 如何导出 TiDB 数据？ - -TiDB 目前暂时不支持 `select into outfile`，可以通过以下方式导出 TiDB 数据：参考 [MySQL 使用 mysqldump 导出某个表的部分数据](https://blog.csdn.net/xin_yu_xin/article/details/7574662)，使用 mysqldump 加 where 条件导出，使用 MySQL client 将 select 的结果输出到一个文件。 - -#### 4.1.7 如何从 DB2、Oracle 数据库迁移到 TiDB？ - -DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： - -- 使用 Oracle 官方迁移工具，如 OGG、Gateway（透明网关）、CDC（Change Data Capture）。 -- 自研数据导出导入程序实现。 -- 导出（Spool）成文本文件，然后通过 Load infile 进行导入。 -- 使用第三方数据迁移工具。 - -目前看来 OGG 最为合适。 - -#### 4.1.8 用 Sqoop 批量写入 TiDB 数据，虽然配置了 `--batch` 选项，但还是会遇到 `java.sql.BatchUpdateExecption:statement count 5001 exceeds the transaction limitation` 的错误，该如何解决？ - -- 在 Sqoop 中，`--batch` 是指每个批次提交 100 条 statement，但是默认每个 statement 包含 100 条 SQL 语句，所以此时 100 * 100 = 10000 条 SQL 语句，超出了 TiDB 的事务限制 5000 条，可以增加选项 `-Dsqoop.export.records.per.statement=10` 来解决这个问题，完整的用法如下： - - {{< copyable "shell-regular" >}} - - ```bash - sqoop export \ - -Dsqoop.export.records.per.statement=10 \ - --connect jdbc:mysql://mysql.example.com/sqoop \ - --username sqoop ${user} \ - --password ${passwd} \ - --table ${tab_name} \ - --export-dir ${dir} \ - --batch - ``` - -- 也可以选择增大 tidb 的单个事物语句数量限制，不过这个会导致内存上涨。 - -#### 4.1.9 TiDB 有像 Oracle 那样的 Flashback Query 功能么，DDL 支持么？ - -有，也支持 DDL。详细参考 [TiDB 历史数据回溯](/dev/how-to/get-started/read-historical-data.md)。 - -### 4.2 在线数据同步 - -#### 4.2.1 Syncer 架构 - -详细参考 [解析 TiDB 在线数据同步工具 Syncer](https://pingcap.com/blog-cn/tidb-syncer/)。 - -##### 4.2.1.1 Syncer 使用文档 - -详细参考 [Syncer 使用文档](/dev/reference/tools/syncer.md)。 - -##### 4.2.1.2 如何配置监控 Syncer 运行情况？ - -下载 [Syncer Json](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json) 导入到 Grafana，修改 Prometheus 配置文件，添加以下内容： - -- job_name: 'syncer_ops' // 任务名字 - static_configs: -- targets: ['10.10.1.1:10096'] //Syncer 监听地址与端口，通知 prometheus 拉取 Syncer 的数据。 - -重启 Prometheus 即可。 - -##### 4.2.1.3 有没有现成的同步方案，可以将数据同步到 Hbase、Elasticsearh 等其他存储？ - -没有，目前依赖程序自行实现。 - -##### 4.2.1.4 利用 Syncer 做数据同步的时候是否支持只同步部分表？ - -支持，具体参考 Syncer 使用手册 [Syncer 使用文档](/dev/reference/tools/syncer.md) - -##### 4.2.1.5 频繁的执行 DDL 会影响 Syncer 同步速度吗？ - -频繁执行 DDL 对同步速度会有影响。对于 Sycner 来说，DDL 是串行执行的，当同步遇到了 DDL，就会以串行的方式执行，所以这种场景就会导致同步速度下降。 - -##### 4.2.1.6 使用 Syncer gtid 的方式同步时，同步过程中会不断更新 syncer.meta 文件，如果 Syncer 所在的机器坏了，导致 syncer.meta 文件所在的目录丢失，该如何处理？ - -当前 Syncer 版本的没有进行高可用设计，Syncer 目前的配置信息 syncer.meta 直接存储在硬盘上，其存储方式类似于其他 MySQL 生态工具，比如 Mydumper。因此，要解决这个问题当前可以有两个方法： - -1）把 syncer.meta 数据放到比较安全的磁盘上，例如磁盘做好 raid1； - -2）可以根据 Syncer 定期上报到 Prometheus 的监控信息来还原出历史同步的位置信息，该方法的位置信息在大量同步数据时由于延迟会可能不准确。 - -##### 4.2.1.7 Syncer 下游 TiDB 数据和 MySQL 数据不一致，DML 会退出么？ - -- 上游 MySQL 中存在数据，下游 TiDB 中该数据不存在，上游 MySQL 执行 `UPDATE` 或 `DELETE`（更新/删除）该条数据的操作时，Syncer 同步过程即不会报错退出也没有该条数据。 -- 下游有主键索引或是唯一索引冲突时，执行 `UPDATE` 会退出，执行 `INSERT` 不会退出。 - -### 4.3 业务流量迁入 - -#### 4.3.1 如何快速迁移业务流量？ - -我们建议通过 Syncer 工具搭建成多源 MySQL -> TiDB 实时同步环境，读写流量可以按照需求分阶段通过修改网络配置进行流量迁移，建议 DB 上层部署一个稳定的网络 LB（HAproxy、LVS、F5、DNS 等），这样直接修改网络配置就能实现无缝流量迁移。 - -#### 4.3.2 TiDB 总读写流量有限制吗？ - -TiDB 读流量可以通过增加 TiDB server 进行扩展，总读容量无限制，写流量可以通过增加 TiKV 节点进行扩容，基本上写容量也没有限制。 - -#### 4.3.3 Transaction too large 是什么原因，怎么解决？ - -由于分布式事务要做两阶段提交，并且底层还需要做 Raft 复制，如果一个事务非常大，会使得提交过程非常慢，并且会卡住下面的 Raft 复制流程。为了避免系统出现被卡住的情况，我们对事务的大小做了限制： - -- 单个事务包含的 SQL 语句不超过 5000 条（默认） -- 单条 KV entry 不超过 6MB -- KV entry 的总大小不超过 100MB - -在 Google 的 Cloud Spanner 上面，也有类似的[限制](https://cloud.google.com/spanner/docs/limits)。 - -#### 4.3.4 如何批量导入？ - -导入数据的时候，可以分批插入，每批最好不要超过 1w 行。 - -#### 4.3.5 TiDB 中删除数据后会立即释放空间吗？ - -DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DROP 操作，在达到 TiDB 的 GC (garbage collection) 时间后（默认 10 分钟），TiDB 的 GC 机制会删除数据并释放空间。对于 DELETE 操作 TiDB 的 GC 机制会删除数据，但不会释放空间，而是当后续数据写入 RocksDB 且进行 compact 时对空间重新利用。 - -#### 4.3.6 Load 数据时可以对目标表执行 DDL 操作吗？ - -不可以，加载数据期间不能对目标表执行任何 DDL 操作，这会导致数据加载失败。 - -#### 4.3.7 TiDB 是否支持 replace into 语法？ - -支持，但是 load data 不支持 replace into 语法。 - -#### 4.3.8 数据删除后查询速度为何会变慢？ - -大量删除数据后，会有很多无用的 key 存在，影响查询效率。目前正在开发 Region Merge 功能，完善之后可以解决这个问题，具体看参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 - -#### 4.3.9 数据删除最高效最快的方式？ - -在删除大量数据的时候，建议使用 `Delete * from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -#### 4.3.10 TiDB 如何提高数据加载速度？ - -主要有两个方面： - -- 目前已开发分布式导入工具 [Lightning](/dev/reference/tools/tidb-lightning/overview.md)，需要注意的是数据导入过程中为了性能考虑，不会执行完整的事务流程，所以没办法保证导入过程中正在导入的数据的 ACID 约束，只能保证整个导入过程结束以后导入数据的 ACID 约束。因此适用场景主要为新数据的导入（比如新的表或者新的索引），或者是全量的备份恢复（先 Truncate 原表再导入）。 -- TiDB 的数据加载与磁盘以及整体集群状态相关，加载数据时应关注该主机的磁盘利用率，TiClient Error/Backoff/Thread CPU 等相关 metric，可以分析相应瓶颈。 - -#### 4.3.11 对数据做删除操作之后，空间回收比较慢，如何处理？ - -可以设置并行 GC，加快对空间的回收速度。默认并发为 1，最大可调整为 tikv 实例数量的 50%。可使用 `update mysql.tidb set VARIABLE_VALUE="3" where VARIABLE_NAME="tikv_gc_concurrency";` 命令来调整。 - -## 五、SQL 优化 - -### 5.1 TiDB 执行计划解读 - -详细解读 [理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.1 统计信息收集 - -详细解读 [统计信息](/dev/reference/performance/statistics.md)。 - -#### 5.1.2 Count 如何加速？ - -Count 就是暴力扫表，提高并发度能显著的提升速度，修改并发度可以参考 `tidb_distsql_scan_concurrency` 变量，但是也要看 CPU 和 I/O 资源。TiDB 每次查询都要访问 TiKV，在数据量小的情况下，MySQL 都在内存里，TiDB 还需要进行一次网络访问。 - -提升建议： - -- 建议提升硬件配置，可以参考[部署建议](/dev/how-to/deploy/hardware-recommendations.md)。 -- 提升并发度，默认是 10，可以提升到 50 试试，但是一般提升在 2-4 倍之间。 -- 测试大数据量的 count。 -- 调优 TiKV 配置，可以参考[性能调优](/dev/reference/performance/tune-tikv.md)。 - -#### 5.1.3 查看当前 DDL 的进度？ - -通过 `admin show ddl` 查看当前 job 进度。操作如下： - -{{< copyable "sql" >}} - -```sql -admin show ddl; -``` - -``` -*************************** 1. row *************************** - SCHEMA_VER: 140 - OWNER: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -RUNNING_JOBS: ID:121, Type:add index, State:running, SchemaState:write reorganization, SchemaID:1, TableID:118, RowCount:77312, ArgLen:0, start time: 2018-12-05 16:26:10.652 +0800 CST, Err:, ErrCount:0, SnapshotVersion:404749908941733890 - SELF_ID: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -``` - -从上面操作结果可知，当前正在处理的是 `add index` 操作。且从 `RUNNING_JOBS` 列的 `RowCount` 字段可以知道当前 `add index` 操作已经添加了 77312 行索引。 - -#### 5.1.4 如何查看 DDL job？ - -可以使用 `admin show ddl` 语句查看正在运行的 DDL 作业。 - -- `admin show ddl jobs`：用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 -- `admin show ddl job queries 'job_id' [, 'job_id'] ...`：用于显示 `job_id` 对应的 DDL 任务的原始 SQL 语句。此 `job_id` 只搜索正在执行中的任务以及 DDL 历史作业队列中的最近十条结果。 - -#### 5.1.5 TiDB 是否支持基于 COST 的优化（CBO），如果支持，实现到什么程度？ - -是的，TiDB 使用的基于成本的优化器（CBO），我们有一个小组单独会对代价模型、统计信息持续优化，除此之外，我们支持 hash join、soft merge 等关联算法。 - -#### 5.1.6 如何确定某张表是否需要做 analyze ？ - -可以通过 `show stats_healthy` 来查看 Healthy 字段，一般小于等于 60 的表需要做 analyze。 - -#### 5.1.7 SQL 的执行计划展开成了树，ID 的序号有什么规律吗？这棵树的执行顺序会是怎么样的？ - -ID 没什么规律，只要是唯一就行，不过生成的时候，是有一个计数器，生成一个 plan 就加一，执行的顺序和序号无关，整个执行计划是一颗树，执行时从根节点开始，不断地向上返回数据。执行计划的理解，请参考[理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.8 TiDB 执行计划中，task cop 在一个 root 下，这个是并行的么？ - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指被下推到 KV 端分布式执行的计算任务，root task 是指在 TiDB 端单点执行的计算任务。一般来讲 root task 的输入数据是来自于 cop task 的；但是 root task 在处理数据的时候，TiKV 上的 cop task 也可以同时处理数据，等待 TiDB 的 root task 拉取，所以从这个观点上来看，他们是并行的；但是存在数据上下游关系；在执行的过程中，某些时间段其实也是并行的，第一个 cop task 在处理 [100, 200] 的数据，第二个 cop task 在处理 [1, 100] 的数据。执行计划的理解，请参考[理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md)。 - -## 六、数据库优化 - -### 6.1 TiDB - -#### 6.1.1 TiDB 参数及调整 - -详情参考 [TiDB 配置参数](/dev/reference/configuration/tidb-server/configuration.md)。 - -#### 6.1.2 如何打散热点 - -TiDB 中以 Region 分片来管理数据库，通常来讲，TiDB 的热点指的是 Region 的读写访问热点。而 TiDB 中对于 PK 非整数或没有 PK 的表，可以通过设置 `SHARD_ROW_ID_BITS` 来适度分解 Region 分片，以达到打散 Region 热点的效果。详情可参考官网 [TiDB 专用系统变量和语法](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)中 `SHARD_ROW_ID_BITS` 的介绍。 - -### 6.2 TiKV - -#### 6.2.1 TiKV 性能参数调优 - -详情参考 [TiKV 性能参数调优](/dev/reference/performance/tune-tikv.md)。 - -## 七、监控 - -### 7.1 Prometheus 监控框架 - -详细参考 [TiDB 监控框架概述](/dev/how-to/monitor/overview.md)。 - -### 7.2 监控指标解读 - -详细参考 [重要监控指标详解](/dev/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.1 目前的监控使用方式及主要监控指标，有没有更好看的监控？ - -TiDB 使用 Prometheus + Grafana 组成 TiDB 数据库系统的监控系统，用户在 Grafana 上通过 dashboard 可以监控到 TiDB 的各类运行指标，包括系统资源的监控指标，包括客户端连接与 SQL 运行的指标，包括内部通信和 Region 调度的指标，通过这些指标，可以让数据库管理员更好的了解到系统的运行状态，运行瓶颈等内容。在监控指标的过程中，我们按照 TiDB 不同的模块，分别列出了各个模块重要的指标项，一般用户只需要关注这些常见的指标项。具体指标请参见[官方文档](/dev/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.2 Prometheus 监控数据默认 15 天自动清除一次，可以自己设定成 2 个月或者手动删除吗？ - -可以的，在 Prometheus 启动的机器上，找到启动脚本，然后修改启动参数，然后重启 Prometheus 生效。 - -```config ---storage.tsdb.retention="60d" -``` - -#### 7.2.3 Region Health 监控项 - -TiDB-2.0 版本中，PD metric 监控页面中，对 Region 健康度进行了监控，其中 Region Health 监控项是对所有 Region 副本状况的一些统计。其中 miss 是缺副本，extra 是多副本。同时也增加了按 Label 统计的隔离级别，level-1 表示这些 Region 的副本在第一级 Label 下是物理隔离的，没有配置 location label 时所有 Region 都在 level-0。 - -#### 7.2.4 Statement Count 监控项中的 selectsimplefull 是什么意思？ - -代表全表扫，但是可能是很小的系统表。 - -#### 7.2.5 监控上的 QPS 和 Statement OPS 有什么区别？ - -QPS 会统计执行的所有 SQL 命令，包括 use database、load data、begin、commit、set、show、insert、select 等。 - -Statement OPS 只统计 select、update、insert 等业务相关的，所以 Statement OPS 的统计和业务比较相符。 - -## 八、Cloud TiDB - -### 8.1 腾讯云 - -#### 8.1.1 目前 Cloud TiDB 都有那些云厂商？ - -Cloud TiDB 目前已经在腾讯云、UCloud 上线，都是数据库一级入口，欢迎大家使用。 - -## 九、故障排除 - -### 9.1 TiDB 自定义报错汇总 - -#### 9.1.1 ERROR 8005 (HY000) : Write Conflict, txnStartTS is stale - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -#### 9.1.2 ERROR 9001 (HY000) : PD Server Timeout - -请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络。 - -#### 9.1.3 ERROR 9002 (HY000) : TiKV Server Timeout - -请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络。 - -#### 9.1.4 ERROR 9003 (HY000) : TiKV Server is Busy - -TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.5 ERROR 9004 (HY000) : Resolve Lock Timeout - -清理锁超时，当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码是否有锁争用。 - -#### 9.1.6 ERROR 9005 (HY000) : Region is unavailable - -访问的 Region 不可用，某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.7 ERROR 9006 (HY000) : GC life time is shorter than transaction duration - -`GC Life Time` 间隔时间过短，长事务本应读到的数据可能被清理了，可使用如下命令增加 `GC Life Time`： - -{{< copyable "sql" >}} - -```sql -update mysql.tidb set variable_value='30m' where variable_name='tikv_gc_life_time'; -``` - -其中 30m 代表仅清理 30 分钟前的数据，这可能会额外占用一定的存储空间。 - -#### 9.1.8 ERROR 9007 (HY000) : Write Conflict - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -### 9.2 MySQL 原生报错汇总 - -#### 9.2.1 ERROR 2013 (HY000): Lost connection to MySQL server during query 问题的排查方法？ - -- log 中是否有 panic -- dmesg 中是否有 oom，命令：`dmesg -T | grep -i oom` -- 长时间没有访问，也会收到这个报错，一般是 tcp 超时导致的，tcp 长时间不用, 会被操作系统 kill。 - -#### 9.2.2 ERROR 1105 (HY000): other error: unknown error Wire Error(InvalidEnumValue(4004)) 是什么意思？ - -这类问题一般是 TiDB 和 TiKV 版本不匹配，在升级过程尽量一起升级，避免版本 mismatch。 - -#### 9.2.3 ERROR 1148 (42000): the used command is not allowed with this TiDB version 问题的处理方法？ - -这个问题是因为在执行 `LOAD DATA LOCAL` 语句的时候，MySQL 客户端不允许执行此语句（即 `local_infile` 选项为 0）。解决方法是在启动 MySQL 客户端时，用 `--local-infile=1` 选项。具体启动指令类似：`mysql --local-infile=1 -u root -h 127.0.0.1 -P 4000`。有些 MySQL 客户端需要设置而有些不需要设置，原因是不同版本的 MySQL 客户端对 `local-infile` 的默认值不同。 - -#### 9.2.4 ERROR 9001 (HY000): PD server timeout start timestamp may fall behind safe point - -这个报错一般是 TiDB 访问 PD 出了问题，TiDB 后台有个 worker 会不断地从 PD 查询 safepoint，如果超过 100s 查不成功就会报这个错。一般是因为 PD 磁盘操作过忙、反应过慢，或者 TiDB 和 PD 之间的网络有问题。TiDB 常见错误码请参考[错误码与故障诊断](/dev/reference/error-codes.md)。 - -### 9.3 TiDB 日志中的报错信息 - -#### 9.3.1 EOF - -当客户端或者 proxy 断开连接时，TiDB 不会立刻察觉连接已断开，而是等到开始往连接返回数据时，才发现连接已断开，此时日志会打印 EOF 错误。 diff --git a/dev/how-to/deploy/data-migration-with-ansible.md b/dev/how-to/deploy/data-migration-with-ansible.md deleted file mode 100644 index bdb3bdaef8e1..000000000000 --- a/dev/how-to/deploy/data-migration-with-ansible.md +++ /dev/null @@ -1,570 +0,0 @@ ---- -title: 使用 DM-Ansible 部署 DM 集群 -category: how-to ---- - -# 使用 DM-Ansible 部署 DM 集群 - -DM-Ansible 是 PingCAP 基于 [Ansible](https://docs.ansible.com/ansible/latest/index.html) 的 [Playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html#about-playbooks) 研发的 DM (Data Migration) 集群部署工具。本文将介绍如何使用 DM-Ansible 快速部署 DM 集群。 - -## 准备工作 - -在开始之前，先确保您准备好了以下配置的机器： - -1. 部署目标机器若干，配置如下： - - - CentOS 7.3 (64-bit) 或更高版本，x86_64 架构（AMD64） - - 机器之间内网互通 - - 关闭防火墙，或开放服务端口 - -2. 一台中控机，配置如下： - - - 包含 Python 2.7 的 CentOS 7.3（64-bit）或更高版本 - - Ansible 2.5 或更高版本 - - 互联网访问 - -## 第 1 步：在中控机上安装依赖包 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -根据中控机的操作系统版本，运行相应命令如下： - -- CentOS 7： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && - yum -y install python-pip - ``` - -- Ubuntu： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH 密钥 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 为 `tidb` 用户设置密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 在 sudo 文件尾部加上 `tidb ALL=(ALL) NOPASSWD: ALL`，为 `tidb` 用户设置免密使用 sudo。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH 密钥。 - - 执行以下 `su` 命令，将登录用户从 `root` 切换至 `tidb`。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 为 `tidb` 用户创建 SSH 密钥。当提示 `Enter passphrase` 时，按 Enter 键。命令成功执行后，生成的 SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为`/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：下载 DM-Ansible 至中控机 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -1. 打开 `/home/tidb` 目录。 -2. 执行以下命令下载 DM-Ansible。 - - {{< copyable "shell-regular" >}} - - ```bash - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz - ``` - - `{version}` 为期望下载的 DM 版本，如 `v1.0.1`、`v1.0.2` 等， - 可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 第 4 步：安装 DM-Ansible 及其依赖至中控机 - -> **注意：** -> -> - 请确保使用 `tidb` 账户登录中控机。 -> - 您需要使用 `pip` 方式下载安装 Ansible 及其依赖，否则可能会遇到兼容性问题。 DM-Ansible 当前与 Ansible 2.5 或更高版本兼容。 - -1. 在中控机上安装 DM-Ansible 及其依赖包： - - {{< copyable "shell-regular" >}} - - ```bash - tar -xzvf dm-ansible-{version}.tar.gz && - mv dm-ansible-{version} dm-ansible && - cd /home/tidb/dm-ansible && - sudo pip install -r ./requirements.txt - ``` - - Ansible 和相关依赖包含于 `dm-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 版本： - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 第 5 步：在中控机上配置 SSH 互信和 sudo 规则 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录至中控机。 - -1. 将您部署的目标机器的 IP 地址加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.71 - 172.16.10.72 - 172.16.10.73 - - [all:vars] - username = tidb - ``` - -2. 运行如下命令，然后输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，创建 sudo 规则，并为中控机和部署目标机器之间配置 SSH 互信。 - -## 第 6 步：下载 DM 及监控组件安装包至中控机 - -> **注意：** -> -> 请确保中控机接入互联网。 - -在中控机上，运行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 第 7 步：编辑 `inventory.ini` 配置文件 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -打开并编辑 `/home/tidb/dm-ansible/inventory.ini` 文件如下，以管控 DM 集群。 - -```ini -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -根据场景需要，您可以在以下两种集群拓扑中任选一种： - -- [单节点上单个 DM-worker 实例的集群拓扑](#选项-1使用单节点上单个-dm-worker-实例的集群拓扑) -- [单节点上多个 DM-worker 实例的集群拓扑](#选项-2使用单节点上多个-dm-worker-实例的集群拓扑) - -通常情况下，我们推荐每个节点上部署单个 DM-Worker 实例。但如果您的机器拥有性能远超 [TiDB 软件和硬件环境要求](/dev/how-to/deploy/hardware-recommendations.md)中推荐配置的 CPU 和内存，并且每个节点配置 2 块以上的硬盘或大于 2T 的 SSD，您可以在单个节点上部署不超过 2 个 DM-Worker 实例。 - -### 选项 1：使用单节点上单个 DM-Worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1 | -| node3 | 172.16.10.73 | DM-worker2 | -| mysql-replica-01| 172.16.10.81 | MySQL | -| mysql-replica-02| 172.16.10.82 | MySQL | - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2 ansible_host=172.16.10.73 server_id=102 source_id="mysql-replica-02" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。关于 DM-worker 参数的更多信息，请参考 [DM-worker 配置及参数描述](#dm-worker-配置及参数描述)。 - -### 选项 2：使用单节点上多个 DM-worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1-1, DM-worker1-2 | -| node3 | 172.16.10.73 | DM-worker2-1, DM-worker2-2 | - -编辑 `inventory.ini` 文件时，请注意区分这些变量：`server_id`，`deploy_dir`，和 `dm_worker_port`。 - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1_1 ansible_host=172.16.10.72 server_id=101 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker1_2 ansible_host=172.16.10.72 server_id=102 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2_1 ansible_host=172.16.10.73 server_id=103 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker2_2 ansible_host=172.16.10.73 server_id=104 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.84 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。 - -### DM-worker 配置及参数描述 - -| 变量名称 | 描述 | -| ------------- | ------- -| source_id | DM-worker 绑定到的一个数据库实例或是具有主从架构的复制组。当发生主从切换的时候，只需要更新 `mysql_host` 或 `mysql_port` 而不用更改该 ID 标识。 | -| server_id | DM-worker 伪装成一个 MySQL slave，该变量即为这个 slave 的 server ID，在 MySQL 集群中需保持全局唯一。取值范围 0 ~ 4294967295。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置。 | -| mysql_host | 上游 MySQL 主机。 | -| mysql_user | 上游 MySQL 用户名，默认值为 “root”。| -| mysql_password | 上游 MySQL 用户密码，需使用 `dmctl` 工具加密。请参考[使用 dmctl 加密上游 MySQL 用户密码](#使用-dmctl-加密上游-mysql-用户密码)。 | -| mysql_port | 上游 MySQL 端口， 默认 3306。 | -| enable_gtid | DM-worker 是否使用全局事务标识符（GTID）拉取 binlog。使用前提是在上游 MySQL 已开启 GTID 模式。 | -| relay_binlog_name | DM-worker 是否从指定 binlog 文件位置开始拉取 binlog。仅适用于本地无有效 relay log 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。| -| relay_binlog_gtid | DM-worker 是否从指定 GTID 位置开始拉取 binlog。仅适用于本地无有效 relay log，且 `enable_gtid` 设置为 true 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| flavor | 代表 MySQL 的版本发布类型。 如果是官方版本，Percona 版，或 Cloud MySQL 版，其值为 “mysql”。 如果是 MariaDB，其值为 "mariadb"。默认值是 "mysql"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置。 | - -关于 `deploy_dir` 配置的更多信息，请参考[配置部署目录](#配置部署目录)。 - -### 使用 dmctl 加密上游 MySQL 用户密码 - -假定上游 MySQL 的用户密码为 `123456`，运行以下命令，并将生成的字符串添加至 DM-worker 的 `mysql_password` 变量。 - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/dm-ansible/resources/bin && -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -## 第 8 步：编辑 `inventory.ini` 文件中的变量 - -此步介绍如何编辑部署目录中的变量，如何配置 relay log 同步位置以及 relay log GTID 的同步模式。此外，还会描述 `inventory.ini` 中的全局变量。 - -### 配置部署目录 - -编辑 `deploy_dir` 变量以配置部署目录。 - -- 全局变量默认设为 `/home/tidb/deploy`，适用于所有服务。如果数据盘挂载于 `/data1` 目录，您可以通过以下修改将其变更至 `/data1/dm`。 - - ```ini - ## Global variables. - [all:vars] - deploy_dir = /data1/dm - ``` - -- 如果需要为某个服务创建单独的部署目录，您可以在 `inventory.ini` 中配置服务主机列表的同时设置 host 变量。此操作需要您添加第一列别名，以避免在混合服务部署场景下产生混淆。 - - ```ini - dm-master ansible_host=172.16.10.71 deploy_dir=/data1/deploy - ``` - -### 配置 relay log 同步位置 - -首次启动 DM-worker 时，您需要配置 `relay_binlog_name` 变量以指定 DM-worker 拉取上游 MySQL 或 MariaDB binlog 的起始位置。 - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 relay_binlog_name="binlog.000011" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name="binlog.000002" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -> **注意：** -> -> 如未设定 `relay_binlog_name`，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 - -### 开启 relay log GTID 同步模式 - -在 DM 集群中，DM-worker 的 relay log 处理单元负责与上游 MySQL 或 MariaDB 通信，从而将 binlog 拉取至本地文件系统。 - -DM 目前支持 MySQL GTID 和 MariaDB GTID。您可以通过配置以下项目开启 relay log GTID 同步模式： - -- `enable_gtid`：打开 relay log GTID 同步模式以处理 master 和 slave 易位的场景 - -- `relay_binlog_gtid`：指定 DM-worker 开始拉取对应上游 MySQL 或 MariaDB binlog 的起始位置 - -示例配置如下： - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 enable_gtid=true relay_binlog_gtid="aae3683d-f77b-11e7-9e3b-02a495f8993c:1-282967971,cc97fa93-f5cf-11e7-ae19-02915c68ee2e:1-284361339" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name=binlog.000002 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -### 全局变量 - -| 变量名称 | 描述 | -| --------------- | ---------------------------------------------------------- | -| cluster_name | 集群名称，可调整 | -| dm_version | DM 版本，默认已配置 | -| grafana_admin_user | Grafana 管理员用户名称，默认值 `admin` | -| grafana_admin_password | Grafana 管理员账户的密码，用于通过 Ansible 导入 Dashboard。默认值为 `admin`。如果您在 Grafana 网页端修改了密码，请更新此变量。 | - -## 第 9 步：部署 DM 集群 - -使用 `ansible-playbook` 运行 Playbook，默认并发数量是 5。如果部署目标机器较多，您可以使用 `-f` 参数增加并发数量，例如，`ansible-playbook deploy.yml -f 10`。 - -以下部署操作示例使用中运行服务的用户为 `tidb`： - -1. 编辑 `dm-ansible/inventory.ini` 文件，确保 `ansible_user = tidb`。 - - ```ini - ansible_user = tidb - ``` - - > **注意：** - > - > 请勿将 `ansible_user` 设为 `root`，因为 `tidb-ansible` 限制服务需以普通用户运行。 - - 运行以下命令。如果所有服务都返回 `tidb`，则 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 运行以下命令。如果所有服务都返回 `root`，则 `tidb` 用户免密 sudo 操作配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 修改内核参数，并部署 DM 集群组件和监控组件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - -3. 启动 DM 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - - 此操作会按顺序启动 DM 集群的所有组件，包括 DM-master，DM-worker，以及监控组件。当一个 DM 集群被关闭后，您可以使用该命令将其开启。 - -## 第 10 步：关闭 DM 集群 - -如果您需要关闭一个 DM 集群，运行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -该操作会按顺序关闭整个 DM 集群中的所有组件，包括 DM-master，DM-worker，以及监控组件。 - -## 常见部署问题 - -### 默认服务端口 - -| 组件 | 端口变量 | 默认端口 | 描述 | -| :-- | :-- | :-- | :-- | -| DM-master | `dm_master_port` | 8261 | DM-master 服务交流端口 | -| DM-worker | `dm_worker_port` | 8262 | DM-worker 服务交流端口 | -| Prometheus | `prometheus_port` | 9090 | Prometheus 服务交流端口 | -| Grafana | `grafana_port` | 3000 | 外部 Web 监控服务及客户端（浏览器）访问端口 | -| Alertmanager | `alertmanager_port` | 9093 | Alertmanager 服务交流端口 | - -### 自定义端口 - -编辑 `inventory.ini` 文件，将服务端口的相关主机变量添加在对应服务 IP 地址后： - -```ini -dm_master ansible_host=172.16.10.71 dm_master_port=18261 -``` - -### 更新 DM-Ansible - -1. 使用 `tidb` 账户登录至中控机，进入 `/home/tidb` 目录，然后备份`dm-ansible` 文件夹。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - mv dm-ansible dm-ansible-bak - ``` - -2. 下载指定版本 DM-Ansible，解压。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz && \ - tar -xzvf dm-ansible-{version}.tar.gz && \ - mv dm-ansible-{version} dm-ansible - ``` - -3. 迁移 `inventory.ini` 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - cp dm-ansible-bak/inventory.ini dm-ansible/inventory.ini - ``` - -4. 迁移 `dmctl` 配置。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible-bak/dmctl && \ - cp * /home/tidb/dm-ansible/dmctl/ - ``` - -5. 用 Playbook 下载最新的 DM 二进制文件。此文件会自动替换 `/home/tidb/dm-ansible/resource/bin/` 目录下的二进制文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` diff --git a/dev/how-to/deploy/data-migration-with-binary.md b/dev/how-to/deploy/data-migration-with-binary.md deleted file mode 100644 index d75bf8f71dd7..000000000000 --- a/dev/how-to/deploy/data-migration-with-binary.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: 使用 DM binary 部署 DM 集群 -category: how-to ---- - -# 使用 DM binary 部署 DM 集群 - -本文将介绍如何使用 DM binary 快速部署 DM 集群。 - -## 准备工作 - -下载官方 binary，链接地址：[DM 下载](/dev/reference/tools/download.md#tidb-dm-data-migration)。 - -下载的文件中包括子目录 bin 和 conf。bin 目录下包含 dm-master、dm-worker、dmctl 以及 Mydumper 的二进制文件。conf 目录下有相关的示例配置文件。 - -## 使用样例 - -假设在两台服务器上部署 MySQL，在一台服务器上部署 TiDB（mocktikv 模式），另外在三台服务器上部署两个 DM-worker 实例和一个 DM-master 实例。各个节点的信息如下： - -| 实例 | 服务器地址 | -| :---------- | :----------- | -| MySQL1 | 192.168.0.1 | -| MySQL2 | 192.168.0.2 | -| TiDB | 192.168.0.3 | -| DM-master | 192.168.0.4 | -| DM-worker1 | 192.168.0.5 | -| DM-worker2 | 192.168.0.6 | - -MySQL1 和 MySQL2 中需要开启 binlog。DM-worker1 负责同步 MySQL1 的数据，DM-worker2 负责同步 MySQL2 的数据。下面以此为例，说明如何部署 DM。 - -### DM-worker 的部署 - -DM-worker 需要连接上游 MySQL，且为了安全，强制用户配置加密后的密码。首先使用 dmctl 对 MySQL 的密码进行加密，以密码为 "123456" 为例： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dmctl --encrypt "123456" -``` - -``` -fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg= -``` - -记录该加密后的值，用于下面部署 DM-worker 时的配置。 - -DM-worker 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -查看 DM-worker 的命令行参数说明： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dm-worker --help -``` - -``` -Usage of worker: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值："info"） - -V 输出版本信息 - -checker-backoff-max duration - 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔（默认值："5m0s"，一般情况下不需要修改。如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-backoff-rollback duration - 任务检查模块中，调整自动恢复等待时间的间隔（默认值："5m0s"，一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-check-enable - 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务（默认值：true） - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -print-sample-config - 打印示例配置 - -purge-expires int - relay log 的过期时间。DM-worker 会尝试自动删除最后修改时间超过了过期时间的 relay log（单位：小时） - -purge-interval int - 定期检查 relay log 是否过期的间隔时间（默认值：3600）（单位：秒） - -purge-remain-space int - 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log（默认值：15）（单位：GB） - -relay-dir string - 存储 relay log 的路径（默认值："./relay_log"） - -worker-addr string - DM-worker 的地址 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件来配置 DM-worker，把以下配置文件内容写入到 `conf/dm-worker1.toml` 中。 - -DM-worker 的配置文件： - -```toml -# Worker Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker 的地址 -worker-addr = ":8262" - -# 作为 MySQL slave 的 server ID，用于获取 MySQL 的 binlog -# 在一个 replication group 中，每个实例（master 和 slave）都应该有唯一的 server ID -# v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置 -server-id = 101 - -# 用于标识一个 replication group 或者 MySQL/MariaDB 实例 -source-id = "mysql-replica-01" - -# 上游实例类型，值可为 "mysql" 或者 "mariadb" -# v1.0.2 及以上版本的 DM 会自动识别上游实例类型，不需要手动配置 -flavor = "mysql" - -# MySQL 的连接地址 -[from] -host = "192.168.0.1" -user = "root" -password = "fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg=" -port = 3306 -``` - -在终端中使用下面的命令运行 DM-worker： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-worker -config conf/dm-worker1.toml -``` - -对于 DM-worker2，修改配置文件中的 `source-id` 为 `mysql-replica-02`，并将 `from` 配置部分修改为 MySQL2 的地址即可。如果因为没有多余的机器，将 DM-worker2 与 DM-worker1 部署在一台机器上，需要把两个 DM-worker 实例部署在不同的路径下，否则保存元信息和 relay log 的默认路径会冲突。 - -### DM-master 的部署 - -DM-master 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -DM-master 的命令行参数说明： - -```bash -./bin/dm-master --help -``` - -``` -Usage of dm-master: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值为 "info"） - -V 输出版本信息 - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -master-addr string - DM-master 的地址 - -print-sample-config - 打印出 DM-master 的示例配置 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件，把以下配置文件内容写入到 `conf/dm-master.toml` 中。 - -DM-master 的配置文件： - -```toml -# Master Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-master.log" - -# DM-master 监听地址 -master-addr = ":8261" - -# DM-Worker 的配置 -[[deploy]] -# 对应 DM-worker1 配置文件中的 source-id -source-id = "mysql-replica-01" -# DM-worker1 的服务地址 -dm-worker = "192.168.0.5:8262" - -[[deploy]] -# 对应 DM-worker2 配置文件中的 source-id -source-id = "mysql-replica-02" -# DM-worker2 的服务地址 -dm-worker = "192.168.0.6:8262" -``` - -在终端中使用下面的命令运行 DM-master： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-master -config conf/dm-master.toml -``` - -这样，DM 集群就部署成功了。下面创建简单的数据同步任务来使用 DM 集群。 - -### 创建数据同步任务 - -假设在 MySQL1 和 MySQL2 实例中有若干个分表，这些分表的结构相同，所在库的名称都以 "sharding" 开头，表名称都以 "t" 开头，并且主键或唯一键不存在冲突（即每张分表的主键或唯一键各不相同）。现在需要把这些分表同步到 TiDB 中的 `db_target.t_target` 表中。 - -首先创建任务的配置文件： - -{{< copyable "" >}} - -```yaml ---- -name: test -task-mode: all -is-sharding: true - -target-database: - host: "192.168.0.3" - port: 4000 - user: "root" - password: "" # 如果密码不为空，也需要配置 dmctl 加密后的密码 - -mysql-instances: - - source-id: "mysql-replica-01" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - -black-white-list: - instance: - do-dbs: ["~^sharding[\\d]+"] - do-tables: - - db-name: "~^sharding[\\d]+" - tbl-name: "~^t[\\d]+" - -routes: - sharding-route-rules-table: - schema-pattern: sharding* - table-pattern: t* - target-schema: db_target - target-table: t_target - - sharding-route-rules-schema: - schema-pattern: sharding* - target-schema: db_target -``` - -将以上配置内容写入到 `conf/task.yaml` 文件中，使用 dmctl 创建任务： - -{{< copyable "shell-regular" >}} - -```bash -bin/dmctl -master-addr 192.168.0.4:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 -» -``` - -{{< copyable "" >}} - -```bash -» start-task conf/task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "192.168.0.5:8262", - "msg": "" - }, - { - "result": true, - "worker": "192.168.0.6:8262", - "msg": "" - } - ] -} -``` - -这样就成功创建了一个将 MySQL1 和 MySQL2 实例中的分表数据同步到 TiDB 的任务。 diff --git a/dev/how-to/deploy/geographic-redundancy/location-awareness.md b/dev/how-to/deploy/geographic-redundancy/location-awareness.md deleted file mode 100644 index 9047a34424a7..000000000000 --- a/dev/how-to/deploy/geographic-redundancy/location-awareness.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: 集群拓扑信息配置 -category: how-to ---- - -# 集群拓扑信息配置 - -## 概述 - -PD 能够根据 TiKV 集群的拓扑结构进行调度，使得 TiKV 的容灾能力最大化。 - -阅读本章前，请先确保阅读 [Ansible 部署方案](/dev/how-to/deploy/orchestrated/ansible.md) 和 [Docker 部署方案](/dev/how-to/deploy/orchestrated/docker.md)。 - -## TiKV 上报拓扑信息 - -可以通过 TiKV 的启动参数或者配置文件来让 TiKV 上报拓扑信息给 PD。 - -假设拓扑结构分为三级：zone > rack > host，可以通过 labels 来指定这些信息。 - -启动参数： - -``` -tikv-server --labels zone=,rack=,host= -``` - -配置文件： - -{{< copyable "" >}} - -```toml -[server] -labels = "zone=,rack=,host=" -``` - -## PD 理解 TiKV 拓扑结构 - -可以通过 PD 的配置文件让 PD 理解 TiKV 集群的拓扑结构。 - -{{< copyable "" >}} - -```toml -[replication] -max-replicas = 3 -location-labels = ["zone", "rack", "host"] -``` - -其中 `location-labels` 需要与 TiKV 的 `labels` 名字对应，这样 PD 才能知道这些 `labels` 代表了 TiKV 的拓扑结构。 - -> **注意：** -> -> 必须同时配置 PD 的 `location-labels` 和 TiKV 的 `labels` 参数，否则 `labels` 不会生效。 - -## PD 基于 TiKV 拓扑结构进行调度 - -PD 能够根据我们提供的拓扑信息作出最优的调度，我们只需要关心什么样的拓扑结构能够达到我们想要的效果。 - -假设我们使用三副本，并且希望一个数据中心挂掉的情况下，还能继续保持 TiDB 集群的高可用状态，我们至少需要四个数据中心。 - -假设我们有四个数据中心 (zone)，每个数据中心有两个机架 (rack)，每个机架上有两个主机 (host)。 -每个主机上面启动一个 TiKV 实例： - -``` -# zone=z1 -tikv-server --labels zone=z1,rack=r1,host=h1 -tikv-server --labels zone=z1,rack=r1,host=h2 -tikv-server --labels zone=z1,rack=r2,host=h1 -tikv-server --labels zone=z1,rack=r2,host=h2 - -# zone=z2 -tikv-server --labels zone=z2,rack=r1,host=h1 -tikv-server --labels zone=z2,rack=r1,host=h2 -tikv-server --labels zone=z2,rack=r2,host=h1 -tikv-server --labels zone=z2,rack=r2,host=h2 - -# zone=z3 -tikv-server --labels zone=z3,rack=r1,host=h1 -tikv-server --labels zone=z3,rack=r1,host=h2 -tikv-server --labels zone=z3,rack=r2,host=h1 -tikv-server --labels zone=z3,rack=r2,host=h2 - -# zone=z4 -tikv-server --labels zone=z4,rack=r1,host=h1 -tikv-server --labels zone=z4,rack=r1,host=h2 -tikv-server --labels zone=z4,rack=r2,host=h1 -tikv-server --labels zone=z4,rack=r2,host=h2 -``` - -也就是说，我们有 16 个 TiKV 实例，分布在 4 个不同的数据中心，8 个不同的机架，16 个不同的机器。 - -在这种拓扑结构下，PD 会优先把每一份数据的不同副本调度到不同的数据中心。 -这时候如果其中一个数据中心挂了，不会影响 TiDB 集群的高可用状态。 -如果这个数据中心一段时间内恢复不了，PD 会把这个数据中心的副本迁移出去。 - -总的来说，PD 能够根据当前的拓扑结构使得集群容灾能力最大化，所以如果我们希望达到某个级别的容灾能力， -就需要根据拓扑机构在不同的地理位置提供多于备份数 (`max-replicas`) 的机器。 diff --git a/dev/how-to/deploy/hardware-recommendations.md b/dev/how-to/deploy/hardware-recommendations.md deleted file mode 100644 index 335f609f8dc2..000000000000 --- a/dev/how-to/deploy/hardware-recommendations.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: TiDB 软件和硬件环境建议配置 -category: how-to ---- - -# TiDB 软件和硬件环境建议配置 - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 - -## Linux 操作系统版本要求 - -| Linux 操作系统平台 | 版本 | -| :----------------------- | :----------: | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | -| Ubuntu LTS | 16.04 及以上 | - -> **注意：** -> -> - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 -> - TiDB 在 CentOS 7.3 的环境下进行过大量的测试，同时社区也有很多该操作系统部署的最佳实践，因此，建议使用 CentOS 7.3 以上的 Linux 操作系统来部署 TiDB。 -> - 以上 Linux 操作系统可运行在物理服务器以及 VMware、KVM、XEN 主流虚拟化环境上。 - -## 服务器建议配置 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -### 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | 无特殊要求 | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 4核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | - -> **注意：** -> -> - 验证测试环境中的 TiDB 和 PD 可以部署在同一台服务器上。 -> - 如进行性能相关的测试，避免采用低性能存储和网络硬件配置，防止对测试结果的正确性产生干扰。 -> - TiKV 的 SSD 盘推荐使用 NVME 接口以保证读写更快。 -> - 如果仅验证功能，建议使用 [Docker Compose 部署方案](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 -> - TiDB 对于磁盘的使用以存放日志为主，因此在测试环境中对于磁盘类型和容量并无特殊要求。 - -### 生产环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 32 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 4核+ | 8 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 32 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | - -> **注意：** -> -> - 生产环境中的 TiDB 和 PD 可以部署和运行在同服务器上，如对性能和可靠性有更高的要求，应尽可能分开部署。 -> - 生产环境强烈推荐使用更高的配置。 -> - TiKV 硬盘大小配置建议 PCI-E SSD 不超过 2 TB，普通 SSD 不超过 1.5 TB。 - -## 网络要求 - -TiDB 作为开源分布式 NewSQL 数据库，其正常运行需要网络环境提供如下的网络端口配置要求，管理员可根据实际环境中 TiDB 组件部署的方案，在网络侧和主机侧开放相关端口： - -| 组件 | 默认端口 | 说明 | -| :-- | :-- | :-- | -| TiDB | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | 20160 | TiKV 通信端口 | -| PD | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | 2380 | PD 集群节点间通信端口 | -| Pump | 8250 | Pump 通信端口 | -| Drainer | 8249 | Drainer 通信端口 | -| Prometheus | 9090 | Prometheus 服务通信端口 | -| Pushgateway | 9091 | TiDB，TiKV，PD 监控聚合和上报端口 | -| Node_exporter | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | 9308 | Kafka_exporter 通信端口，用于监控 binlog kafka 集群 | - -## 客户端 Web 浏览器要求 - -TiDB 提供了基于 [Grafana](https://grafana.com/) 的技术平台，对数据库集群的各项指标进行可视化展现。采用支持 Javascript 的微软 IE、Google Chrome、Mozilla Firefox 的较新版本即可访问监控入口。 diff --git a/dev/how-to/deploy/orchestrated/ansible.md b/dev/how-to/deploy/orchestrated/ansible.md deleted file mode 100644 index eb40e6ca1633..000000000000 --- a/dev/how-to/deploy/orchestrated/ansible.md +++ /dev/null @@ -1,966 +0,0 @@ ---- -title: 使用 TiDB Ansible 部署 TiDB 集群 -category: how-to ---- - -# 使用 TiDB Ansible 部署 TiDB 集群 - -## 概述 - -Ansible 是一款自动化运维工具，[TiDB Ansible](https://github.com/pingcap/tidb-ansible) 是 PingCAP 基于 Ansible playbook 功能编写的集群部署工具。本文档介绍如何使用 TiDB Ansible 部署一个完整的 TiDB 集群。 - -本部署工具可以通过配置文件设置集群拓扑，完成以下各项运维工作： - -- 初始化操作系统参数 -- 部署 TiDB 集群（包括 PD、TiDB、TiKV 等组件和监控组件） -- [启动集群](/dev/how-to/maintain/ansible-operations.md#启动集群) -- [关闭集群](/dev/how-to/maintain/ansible-operations.md#关闭集群) -- [变更组件配置](/dev/how-to/upgrade/from-previous-version.md#编辑-tidb-集群组件配置文件) -- [集群扩容缩容](/dev/how-to/scale/with-ansible.md) -- [升级组件版本](/dev/how-to/upgrade/from-previous-version.md#滚动升级-tidb-集群组件) -- [集群开启 binlog](/dev/reference/tidb-binlog/overview.md) -- [清除集群数据](/dev/how-to/maintain/ansible-operations.md#清除集群数据) -- [销毁集群](/dev/how-to/maintain/ansible-operations.md#销毁集群) - -> **注意：** -> -> 对于生产环境，须使用 TiDB Ansible 部署 TiDB 集群。如果只是用于测试 TiDB 或体验 TiDB 的特性，建议[使用 Docker Compose 在单机上快速部署 TiDB 集群](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -## 准备机器 - -1. 部署目标机器若干 - - - 建议 4 台及以上，TiKV 至少 3 实例，且与 TiDB、PD 模块不位于同一主机，详见[部署建议](/dev/how-to/deploy/hardware-recommendations.md)。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统，x86_64 架构 (amd64)。 - - 机器之间内网互通。 - - > **注意：** - > - > 使用 Ansible 方式部署时，TiKV 及 PD 节点数据目录所在磁盘请使用 SSD 磁盘，否则无法通过检测。** 如果仅验证功能，建议使用 [Docker Compose 部署方案](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 - -2. 部署中控机一台 - - - 中控机可以是部署目标机器中的某一台。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统（默认包含 Python 2.7）。 - - 该机器需开放外网访问，用于下载 TiDB 及相关软件安装包。 - -## 第 1 步：在中控机上安装系统依赖包 - -以 `root` 用户登录中控机，然后根据操作系统类型执行相应的安装命令。 - -- 如果中控机使用的是 CentOS 7 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && \ - yum -y install python2-pip - ``` - -- 如果中控机使用的是 Ubuntu 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH key - -以 `root` 用户登录中控机，执行以下步骤： - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 设置 `tidb` 用户密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 配置 `tidb` 用户 sudo 免密码，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾即可。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH key。 - - 执行 `su` 命令，从 `root` 用户切换到 `tidb` 用户下。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 创建 `tidb` 用户 SSH key，提示 `Enter passphrase` 时直接回车即可。执行成功后，SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为 `/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录。使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 master 分支的 TiDB Ansible，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone https://github.com/pingcap/tidb-ansible.git -``` - -> **注意：** -> -> - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 -> - 请务必按文档操作，将 `tidb-ansible` 下载到 `/home/tidb` 目录下，权限为 `tidb` 用户，不要下载到 `/root` 下，否则会遇到权限问题。 - -## 第 4 步：在中控机器上安装 Ansible 及其依赖 - -以 `tidb` 用户登录中控机，请务必按以下方式通过 `pip` 安装 Ansible 及其相关依赖的指定版本，否则会有兼容问题。目前，TiDB release-2.0、release-2.1、release-3.0、release-3.1 以及最新开发版本兼容 Ansible 2.4 ~ 2.7.11 (2.4 ≤ Ansible ≤ 2.7.11)。 - -1. 在中控机器上安装 Ansible 及其依赖。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - sudo pip install -r ./requirements.txt - ``` - - Ansible 及相关依赖的版本信息记录在 `tidb-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 的版本。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.7.11 - ``` - -## 第 5 步：在中控机上配置部署机器 SSH 互信及 sudo 规则 - -以 `tidb` 用户登录中控机，然后执行以下步骤： - -1. 将你的部署目标机器 IP 添加到 `hosts.ini` 文件的 `[servers]` 区块下。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - vi hosts.ini - ``` - - ```ini - [servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - - [all:vars] - username = tidb - ntp_server = pool.ntp.org - ``` - -2. 执行以下命令，按提示输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，并配置 sudo 规则，配置中控机与部署目标机器之间的 SSH 互信。 - -如果要手工配置 SSH 互信及 sudo 免密码，可参考[如何手工配置 ssh 互信及 sudo 免密码](#如何手工配置-ssh-互信及-sudo-免密码)。 - -## 第 6 步：在部署目标机器上安装 NTP 服务 - -> **注意：** -> -> 如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略。可参考[如何检测 NTP 服务是否正常](#如何检测-ntp-服务是否正常)。 - -以 `tidb` 用户登录中控机，执行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/tidb-ansible && \ -ansible-playbook -i hosts.ini deploy_ntp.yml -u tidb -b -``` - -该步骤将在部署目标机器上使用系统自带软件源联网安装并启动 NTP 服务，服务使用安装包默认的 NTP server 列表，见配置文件 `/etc/ntp.conf` 中 server 参数。如果使用默认的 NTP server，你的机器需要连接外网。 - -为了让 NTP 尽快开始同步，启动 NTP 服务前，系统会执行 `ntpdate` 命令，与用户在 `hosts.ini` 文件中指定的 `ntp_server` 同步日期与时间。默认的服务器为 `pool.ntp.org`，也可替换为你的 NTP server。 - -## 第 7 步：在部署目标机器上配置 CPUfreq 调节器模式 - -为了让 CPU 发挥最大性能，请将 CPUfreq 调节器模式设置为 `performance` 模式。如需了解 CPUfreq 的更多信息，可查看[使用 CPUFREQ 调控器](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/power_management_guide/cpufreq_governors#cpufreq_setup)文档。 - -### 查看系统支持的调节器模式 - -执行以下 `cpupower` 命令，可查看系统支持的调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: performance powersave -``` - -> **注意：** -> -> 本例中系统支持设置 `performance` 和 `powersave` 模式。如果返回 `Not Available`，表示当前系统不支持配置 CPUfreq，跳过该步骤即可。 - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: Not Available -``` - -### 查看系统当前的 CPUfreq 调节器模式 - -执行以下 `cpupower` 命令，可查看系统当前的 CPUfreq 调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --policy -``` - -``` -analyzing CPU 0: - current policy: frequency should be within 1.20 GHz and 3.20 GHz. - The governor "powersave" may decide which speed to use - within this range. -``` - -如上述代码所示，本例中的当前配置是 `powersave` 模式。 - -### 修改调节器模式 - -你可以通过以下两种方法来修改调节器模式。本例中，当前调节器模式为 `powersave`，以下命令会将模式变更为 `performance`。 - -- 使用 `cpupower frequency-set --governor` 命令来修改。 - - {{< copyable "shell-root" >}} - - ```bash - cpupower frequency-set --governor performance - ``` - -- 使用以下命令在部署目标机器上批量设置。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i hosts.ini all -m shell -a "cpupower frequency-set --governor performance" -u tidb -b - ``` - -## 第 8 步：在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -使用 `root` 用户登录目标机器，将部署目标机器数据盘格式化成 ext4 文件系统，挂载时添加 `nodelalloc` 和 `noatime` 挂载参数。`nodelalloc` 是必选参数，否则 Ansible 安装时检测无法通过；`noatime` 是可选建议参数。 - -> **注意：** -> -> 如果你的数据盘已经格式化成 ext4 并挂载了磁盘，可先执行 `umount /dev/nvme0n1p1` 命令卸载，从编辑 `/etc/fstab` 文件步骤开始执行，添加挂载参数重新挂载即可。 - -以 `/dev/nvme0n1` 数据盘为例，具体操作步骤如下： - -1. 查看数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - fdisk -l - ``` - - ``` - Disk /dev/nvme0n1: 1000 GB - ``` - -2. 创建分区表。 - - {{< copyable "shell-root" >}} - - ```bash - parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1 - ``` - - > **注意：** - > - > 使用 `lsblk` 命令查看分区的设备号：对于 nvme 磁盘，生成的分区设备号一般为 `nvme0n1p1`；对于普通磁盘（例如 `/dev/sdb`），生成的的分区设备号一般为 `sdb1`。 - -3. 格式化文件系统。 - - {{< copyable "shell-root" >}} - - ```bash - mkfs.ext4 /dev/nvme0n1p1 - ``` - -4. 查看数据盘分区 UUID。 - - 本例中 `nvme0n1p1` 的 UUID 为 `c51eb23b-195c-4061-92a9-3fad812cc12f`。 - - {{< copyable "shell-root" >}} - - ```bash - lsblk -f - ``` - - ``` - NAME FSTYPE LABEL UUID MOUNTPOINT - sda - ├─sda1 ext4 237b634b-a565-477b-8371-6dff0c41f5ab /boot - ├─sda2 swap f414c5c0-f823-4bb1-8fdf-e531173a72ed - └─sda3 ext4 547909c1-398d-4696-94c6-03e43e317b60 / - sr0 - nvme0n1 - └─nvme0n1p1 ext4 c51eb23b-195c-4061-92a9-3fad812cc12f - ``` - -5. 编辑 `/etc/fstab` 文件，添加 `nodelalloc` 挂载参数。 - - {{< copyable "shell-root" >}} - - ```bash - vi /etc/fstab - ``` - - ``` - UUID=c51eb23b-195c-4061-92a9-3fad812cc12f /data1 ext4 defaults,nodelalloc,noatime 0 2 - ``` - -6. 挂载数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - mkdir /data1 && \ - mount -a - ``` - -7. 执行以下命令，如果文件系统为 ext4，并且挂载参数中包含 `nodelalloc`，则表示已生效。 - - {{< copyable "shell-root" >}} - - ```bash - mount -t ext4 - ``` - - ``` - /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered) - ``` - -## 第 9 步：编辑 `inventory.ini` 文件，分配机器资源 - -以 `tidb` 用户登录中控机，编辑 `/home/tidb/tidb-ansible/inventory.ini` 文件为 TiDB 集群分配机器资源。一个标准的 TiDB 集群需要 6 台机器：2 个 TiDB 实例，3 个 PD 实例，3 个 TiKV 实例。 - -- 至少需部署 3 个 TiKV 实例。 -- 不要将 TiKV 实例与 TiDB 或 PD 实例混合部署在同一台机器上。 -- 将第一台 TiDB 机器同时用作监控机。 - -> **注意：** -> -> 请使用内网 IP 来部署集群，如果部署目标机器 SSH 端口非默认的 22 端口，需添加 `ansible_port` 变量，如 `TiDB1 ansible_host=172.16.10.1 ansible_port=5555`。 - -你可以根据实际场景从以下两种集群拓扑中选择一种： - -- [单机单 TiKV 实例集群拓扑](#单机单-tikv-实例集群拓扑) - - 默认情况下，建议在每个 TiKV 节点上仅部署一个 TiKV 实例，以提高性能。但是，如果你的 TiKV 部署机器的 CPU 和内存配置是[部署建议](/dev/how-to/deploy/hardware-recommendations.md)的两倍或以上，并且一个节点拥有两块 SSD 硬盘或者单块 SSD 硬盘的容量大于 2 TB，则可以考虑部署两实例，但不建议部署两个以上实例。 - -- [单机多 TiKV 实例集群拓扑](#单机多-tikv-实例集群拓扑) - -### 单机单 TiKV 实例集群拓扑 - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -[tikv_servers] -172.16.10.4 -172.16.10.5 -172.16.10.6 - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 -``` - -### 单机多 TiKV 实例集群拓扑 - -以两实例为例： - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1-1, TiKV1-2 | -| node5 | 172.16.10.5 | TiKV2-1, TiKV2-2 | -| node6 | 172.16.10.6 | TiKV3-1, TiKV3-2 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -# 注意：要使用 TiKV 的 labels，必须同时配置 PD 的 location_labels 参数，否则 labels 设置不生效。 -[tikv_servers] -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv1" -TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv1" -TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv2" -TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv2" -TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv3" -TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv3" - -# 部署 3.0 版本的 TiDB 集群时，多实例场景需要额外配置 status 端口，示例如下： -# TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" -# TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" -# TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" -# TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" -# TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" -# TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 - -# 注意：为使 TiKV 的 labels 设置生效，部署集群时必须设置 PD 的 location_labels 参数。 -[pd_servers:vars] -location_labels = ["host"] -``` - -- 服务配置文件参数调整 - - 1. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `block-cache-size` 下面的 `capacity` 参数： - - ```yaml - storage: - block-cache: - capacity: "1GB" - ``` - - > **注意：** - > - > TiKV 实例数量指每个服务器上 TiKV 的进程数量。 - > - > 推荐设置：`capacity` = MEM_TOTAL * 0.5 / TiKV 实例数量 - - 2. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ```yaml - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 推荐设置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 - - 3. 如果多个 TiKV 实例部署在同一块物理磁盘上，需要修改 `conf/tikv.yml` 中的 `capacity` 参数： - - ```yaml - raftstore: - capacity: 0 - ``` - - > **注意：** - > - > 推荐配置：`capacity` = 磁盘总容量 / TiKV 实例数量 - > - > 例如：`capacity: "100GB"` - -## 第 10 步：调整 `inventory.ini` 文件中的变量 - -本小节介绍如何编辑部署目录的变量和 `inventory.ini` 文件中的其它变量。 - -### 调整部署目录 - -部署目录通过 `deploy_dir` 变量控制，默认全局变量已设置为 `/home/tidb/deploy`，对所有服务生效。如数据盘挂载目录为 `/data1`，可设置为 `/data1/deploy`，样例如下： - -```ini -## Global variables -[all:vars] -deploy_dir = /data1/deploy -``` - -如为某一服务单独设置部署目录，可在配置服务主机列表时配置主机变量，以 TiKV 节点为例，其他服务类推，请务必添加第一列别名，以免服务混布时混淆。 - -```ini -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy -``` - -### 调整其它变量（可选） - -> **注意：** -> -> 以下控制变量开启请使用首字母大写 `True`，关闭请使用首字母大写 `False`。 - -| 变量 | 含义 | -| :--------------- | :-------------------------------------------------------- | -| `cluster_name` | 集群名称，可调整 | -| `tidb_version` | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| `process_supervision` | 进程监管方式，默认为 `systemd`，可选 `supervise` | -| `timezone` | 新安装 TiDB 集群第一次启动 bootstrap（初始化）时，将 TiDB 全局默认时区设置为该值。TiDB 使用的时区后续可通过 `time_zone` 全局变量和 session 变量来修改，参考[时区支持](/dev/how-to/configure/time-zone.md)。默认为 `Asia/Shanghai`，可选值参考 [timzone 列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。 | -| `enable_firewalld` | 开启防火墙，默认不开启，如需开启，请将[部署建议-网络要求](/dev/how-to/deploy/hardware-recommendations.md#网络要求) 中的端口加入白名单 | -| `enable_ntpd` | 检测部署目标机器 NTP 服务，默认为 `True`，请勿关闭 | -| `set_hostname` | 根据 IP 修改部署目标机器主机名，默认为 `False` | -| `enable_binlog` | 是否部署 Pump 并开启 binlog，默认为 `False`，依赖 Kafka 集群，参见 `zookeeper_addrs` 变量 | -| `zookeeper_addrs` | binlog Kafka 集群的 zookeeper 地址 | -| `deploy_without_tidb` | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 `inventory.ini` 文件中 `tidb_servers` 主机组 IP 设置为空。| -| `alertmanager_target` | 可选：如果你已单独部署 alertmanager，可配置该变量，格式：`alertmanager_host:alertmanager_port` | -| `grafana_admin_user` | Grafana 管理员帐号用户名，默认为 admin | -| `grafana_admin_password` | Grafana 管理员帐号密码，默认为 admin，用于 Ansible 导入 Dashboard 和创建 API Key，如后期通过 grafana web 修改了密码，请更新此变量 | -| `collect_log_recent_hours` | 采集日志时，采集最近几个小时的日志，默认为 2 小时 | -| `enable_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时，是否限速，默认为 `True`，与 `collect_bandwidth_limit` 变量结合使用 | -| `collect_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时限速多少，单位: Kbit/s，默认 10000，即 10Mb/s，如果是单机多 TiKV 实例部署方式，需除以单机实例个数 | -| `prometheus_storage_retention` | Prometheus 监控数据的保留时间（默认为 30 天）；2.1.7、3.0 以及之后的 tidb-ansible 版本中，`group_vars/monitoring_servers.yml` 文件里新增的配置 | - -## 第 11 步：部署 TiDB 集群 - -`ansible-playbook` 执行 Playbook 时，默认并发为 5。部署目标机器较多时，可添加 `-f` 参数指定并发数，例如 `ansible-playbook deploy.yml -f 10`。以下示例使用 `tidb` 用户作为服务运行用户： - -1. 在 `tidb-ansible/inventory.ini` 文件中，确认 `ansible_user = tidb`。 - - ```ini - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - > **注意：** - > - > 不要将 `ansible_user` 设置为 `root` 用户，因为 `tidb-ansible` 限制了服务以普通用户运行。 - - 执行以下命令，如果所有 server 均返回 `tidb`，表示 SSH 互信配置成功： - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 执行以下命令，如果所有 server 均返回 `root`，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 至中控机。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -3. 初始化系统环境，修改内核参数。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml - ``` - -4. 部署 TiDB 集群软件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - - > **注意：** - > - > Grafana Dashboard 上的 **Report** 按钮可用来生成 PDF 文件，此功能依赖 `fontconfig` 包和英文字体。如需使用该功能，登录 **grafana_servers** 机器，用以下命令安装： - > - > {{< copyable "shell-regular" >}} - > - > ```bash - > sudo yum install fontconfig open-sans-fonts - > ``` - -5. 启动 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - -## 测试集群 - -TiDB 兼容 MySQL，因此可使用 MySQL 客户端直接连接 TiDB。推荐配置负载均衡以提供统一的 SQL 接口。 - -1. 使用 MySQL 客户端连接 TiDB 集群。TiDB 服务的默认端口为 `4000`。 - - {{< copyable "sql" >}} - - ```sql - mysql -u root -h 172.16.10.1 -P 4000 - ``` - -2. 通过浏览器访问监控平台。 - - - 地址： - - 默认帐号与密码：`admin`；`admin` - -## 常见部署问题 - -本小节介绍使用 Ansible 部署 TiDB 集群过程中的常见问题与解决方案。 - -### 如何自定义端口 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 端口变量 | 默认端口 | 说明 | -| :-- | :-- | :-- | :-- | -| TiDB | tidb_port | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | tidb_status_port | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | tikv_port | 20160 | TiKV 通信端口 | -| TiKV | tikv_status_port | 20180 | 上报 TiKV 状态的通信端口 | -| PD | pd_client_port | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | pd_peer_port | 2380 | PD 集群节点间通信端口 | -| Pump | pump_port | 8250 | Pump 通信端口 | -| Prometheus | prometheus_port | 9090 | Prometheus 服务通信端口 | -| Pushgateway | pushgateway_port | 9091 | TiDB， TiKV， PD 监控聚合和上报端口 | -| Node_exporter | node_exporter_port | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | blackbox_exporter_port | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | grafana_port | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | grafana_collector_port | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | kafka_exporter_port | 9308 | Kafka_exporter 通信端口，用于监控 binlog Kafka 集群 | - -### 如何自定义部署目录 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 目录变量 | 默认目录 | 说明 | -| :-- | :-- | :-- | :-- | -| 全局 | deploy_dir | /home/tidb/deploy | 部署目录 | -| TiDB | tidb_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_data_dir | {{ deploy_dir }}/data | 数据目录 | -| TiKV | wal_dir | "" | rocksdb write-ahead 日志目录，为空时与 TiKV 数据目录一致 | -| TiKV | raftdb_path | "" | raftdb 目录，为空时为 tikv_data_dir/raft | -| PD | pd_log_dir | {{ deploy_dir }}/log | 日志目录 | -| PD | pd_data_dir | {{ deploy_dir }}/data.pd | 数据目录 | -| pump | pump_log_dir | {{ deploy_dir }}/log | 日志目录 | -| pump | pump_data_dir | {{ deploy_dir }}/data.pump | 数据目录 | -| prometheus | prometheus_log_dir | {{ deploy_dir }}/log | 日志目录 | -| prometheus | prometheus_data_dir | {{ deploy_dir }}/data.metrics | 数据目录 | -| pushgateway | pushgateway_log_dir | {{ deploy_dir }}/log | 日志目录 | -| node_exporter | node_exporter_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_data_dir | {{ deploy_dir }}/data.grafana | 数据目录 | - -### 如何检测 NTP 服务是否正常 - -1. 执行以下命令，如果输出 `running` 表示 NTP 服务正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl status ntpd.service - ``` - - ``` - ntpd.service - Network Time Service - Loaded: loaded (/usr/lib/systemd/system/ntpd.service; disabled; vendor preset: disabled) - Active: active (running) since 一 2017-12-18 13:13:19 CST; 3s ago - ``` - -2. 执行 `ntpstat` 命令，如果输出 `synchronised to NTP server`（正在与 NTP server 同步），表示在正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - synchronised to NTP server (85.199.214.101) at stratum 2 - time correct to within 91 ms - polling server every 1024 s - ``` - -> **注意：** -> -> Ubuntu 系统需安装 `ntpstat` 软件包。 - -- 以下情况表示 NTP 服务未正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - unsynchronised - ``` - -- 以下情况表示 NTP 服务未正常运行： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - Unable to talk to NTP daemon. Is it running? - ``` - -- 如果要使 NTP 服务尽快开始同步，执行以下命令。可以将 `pool.ntp.org` 替换为你的 NTP server： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl stop ntpd.service && \ - sudo ntpdate pool.ntp.org && \ - sudo systemctl start ntpd.service - ``` - -- 如果要在 CentOS 7 系统上手动安装 NTP 服务，可执行以下命令： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install ntp ntpdate && \ - sudo systemctl start ntpd.service && \ - sudo systemctl enable ntpd.service - ``` - -### 如何调整进程监管方式从 supervise 到 systemd - -{{< copyable "shell-root" >}} - -```shell -process supervision, [systemd, supervise] -``` - -``` -process_supervision = systemd -``` - -TiDB Anisble 在 TiDB v1.0.4 版本之前进程监管方式默认为 `supervise`。之前安装的集群可保持不变，如需更新为 `systemd`，需关闭集群，按以下方式变更： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml && \ -ansible-playbook deploy.yml -D && \ -ansible-playbook start.yml -``` - -### 如何手工配置 SSH 互信及 sudo 免密码 - -1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 - - {{< copyable "shell-root" >}} - - ```bash - useradd tidb && \ - passwd tidb - ``` - -2. 执行以下命令，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾，即配置好 sudo 免密码。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -3. 以 `tidb` 用户登录到中控机，执行以下命令。将 `172.16.10.61` 替换成你的部署目标机器 IP，按提示输入部署目标机器 `tidb` 用户密码，执行成功后即创建好 SSH 互信，其他机器同理。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-copy-id -i ~/.ssh/id_rsa.pub 172.16.10.61 - ``` - -4. 以 `tidb` 用户登录中控机，通过 `ssh` 的方式登录目标机器 IP。如果不需要输入密码并登录成功，即表示 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh 172.16.10.61 - ``` - - ``` - [tidb@172.16.10.61 ~]$ - ``` - -5. 以 `tidb` 用户登录到部署目标机器后，执行以下命令，不需要输入密码并切换到 `root` 用户，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - sudo -su root - ``` - - ``` - [root@172.16.10.61 tidb]# - ``` - -### You need to install jmespath prior to running json_query filter 报错 - -1. 请参照[在中控机器上安装 Ansible 及其依赖](#在中控机器上安装-ansible-及其依赖) 在中控机上通过 `pip` 安装 Ansible 及相关依赖的指定版本，默认会安装 `jmespath`。 - -2. 执行以下命令，验证 `jmespath` 是否安装成功： - - {{< copyable "shell-regular" >}} - - ```bash - pip show jmespath - ``` - - ``` - Name: jmespath - Version: 0.9.0 - ``` - -3. 在中控机上 Python 交互窗口里执行 `import jmespath`。 - - - 如果没有报错，表示依赖安装成功。 - - 如果有 `ImportError: No module named jmespath` 报错，表示未成功安装 Python `jmespath` 模块。 - - {{< copyable "shell-regular" >}} - - ```bash - python - ``` - - ``` - Python 2.7.5 (default, Nov 6 2016, 00:28:07) - [GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - ``` - - {{< copyable "shell-regular" >}} - - ```shell - import jmespath - ``` - -### 启动 Pump/Drainer 报 `zk: node does not exist` 错误 - -请检查 `inventory.ini` 里的 `zookeeper_addrs` 参数配置与 Kafka 集群内的配置是否相同、是否填写了命名空间。关于命名空间的配置说明如下： - -```ini -# ZooKeeper connection string (see ZooKeeper docs for details). -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes. Example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -``` diff --git a/dev/how-to/deploy/orchestrated/docker.md b/dev/how-to/deploy/orchestrated/docker.md deleted file mode 100644 index ccf8ee40f616..000000000000 --- a/dev/how-to/deploy/orchestrated/docker.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: TiDB Docker 部署方案 -category: how-to ---- - -# TiDB Docker 部署方案 - -本文介绍如何使用 Docker 部署一个多节点的 TiDB 集群。 - -> **警告：** -> -> 对于生产环境，不要使用 Docker 进行部署，而应[使用 Ansible 部署 TiDB 集群](/dev/how-to/deploy/orchestrated/ansible.md)。 - -## 环境准备 - -### 安装 Docker - -Docker 可以方便地在 Linux / Mac OS / Windows 平台安装，安装方法请参考 [Docker 官方文档](https://www.docker.com/products/docker)。 - -### 拉取 TiDB 的 Docker 镜像 - -部署 TiDB 集群主要包括 3 个服务组件: - -- TiDB -- TiKV -- PD - -对应的最新 Docker 镜像可以通过 [Docker 官方镜像仓库](https://hub.docker.com/u/pingcap) 获取： - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/tidb:latest -``` - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/tikv:latest -``` - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/pd:latest -``` - -## 部署一个多节点集群 - -假设我们打算在 6 台主机上部署一个 TiDB 集群: - -| 主机名 | IP | 部署服务 | 数据盘挂载 | -| --------- | ------------- | ---------- | ----- | -| host1 | 192.168.1.101 | PD1 & TiDB | /data | -| host2 | 192.168.1.102 | PD2 | /data | -| host3 | 192.168.1.103 | PD3 | /data | -| host4 | 192.168.1.104 | TiKV1 | /data | -| host5 | 192.168.1.105 | TiKV2 | /data | -| host6 | 192.168.1.106 | TiKV3 | /data | - -### 启动 PD - -登录 **host1** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host2** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd2 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd2" \ - --data-dir="/data/pd2" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.102:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.102:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host3** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd3 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd3" \ - --data-dir="/data/pd3" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.103:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.103:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -### 启动 TiKV - -登录 **host4** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host5** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv2 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.105:20160" \ - --data-dir="/data/tikv2" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host6** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv3 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.106:20160" \ - --data-dir="/data/tikv3" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 启动 TiDB - -登录 **host1** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tidb \ - -p 4000:4000 \ - -p 10080:10080 \ - -v /etc/localtime:/etc/localtime:ro \ - pingcap/tidb:latest \ - --store=tikv \ - --path="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 使用 MySQL 标准客户端连接 TiDB 测试 - -登录 **host1** 并确保已安装 [MySQL 命令行客户端](http://dev.mysql.com/downloads/mysql/)，执行： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -D test -``` - -{{< copyable "sql" >}} - -```sql -show databases; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -### 如何自定义配置文件 - -TiKV 和 PD 可以通过指定配置文件的方式来加载更加丰富的启动参数，用于性能调优。 - -假定配置文件在宿主机上的存放路径 `/path/to/config/pd.toml` 和 `/path/to/config/tikv.toml`。启动 Docker 时需要调整相应的启动参数，以 tikv1 和 pd1 为例： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/tikv.toml:/tikv.toml:ro \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" \ - --config="/tikv.toml" -``` - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/pd.toml:/pd.toml:ro \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" \ - --config="/pd.toml" -``` diff --git a/dev/how-to/deploy/orchestrated/offline-ansible.md b/dev/how-to/deploy/orchestrated/offline-ansible.md deleted file mode 100644 index cc1fad9acc7c..000000000000 --- a/dev/how-to/deploy/orchestrated/offline-ansible.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: 离线 TiDB Ansible 部署方案 -category: how-to ---- - -# 离线 TiDB Ansible 部署方案 - -## 准备机器 - -1. 下载机一台 - - - 该机器需开放外网访问，用于下载 TiDB Ansible、TiDB 及相关软件安装包。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统。 - -2. 部署目标机器若干及部署中控机一台 - - - 系统要求及配置参考[准备机器](/dev/how-to/deploy/orchestrated/ansible.md#准备机器)。 - - 可以无法访问外网。 - -## 在中控机上安装系统依赖包 - -1. 在下载机上下载[系统依赖离线安装包](https://download.pingcap.org/ansible-system-rpms.el7.tar.gz)，然后上传至中控机。该离线包仅支持 CentOS 7 系统，包含 `pip` 及 `sshpass`。 - -2. 在中控机上安装系统依赖包： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-system-rpms.el7.tar.gz && - cd ansible-system-rpms.el7 && - chmod u+x install_ansible_system_rpms.sh && - ./install_ansible_system_rpms.sh - ``` - -3. 安装完成后，可通过 `pip -V` 验证 pip 是否安装成功： - - {{< copyable "shell-root" >}} - - ```bash - pip -V - ``` - - ``` - pip 8.1.2 from /usr/lib/python2.7/site-packages (python 2.7) - ``` - -> **注意：** -> -> 如果你的系统已安装 pip，请确认版本 >= 8.1.2，否则离线安装 ansible 及其依赖时，会有兼容问题。 - -## 在中控机上创建 tidb 用户，并生成 ssh key - -参考[在中控机上创建 tidb 用户，并生成 ssh key](/dev/how-to/deploy/orchestrated/ansible.md#第-2-步在中控机上创建-tidb-用户并生成-ssh-key) 即可。 - -## 在中控机器上离线安装 Ansible 及其依赖 - -以下是 CentOS 7 系统 Ansible 离线安装方式： - -建议使用 Ansible 2.4 至 2.7.11 版本，Ansible 及相关依赖版本记录在 `tidb-ansible/requirements.txt` 文件中。下面步骤以安装 Ansible 2.5 为例。 - -1. 在下载机上下载 [Ansible 2.5 离线安装包](https://download.pingcap.org/ansible-2.5.0-pip.tar.gz)，然后上传至中控机。 - -2. 离线安装 Ansible 及相关依赖： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-2.5.0-pip.tar.gz && - cd ansible-2.5.0-pip/ && - chmod u+x install_ansible.sh && - ./install_ansible.sh - ``` - -3. 安装完成后，可通过 `ansible --version` 查看版本： - - {{< copyable "shell-root" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 在下载机上下载 TiDB Ansible 及 TiDB 安装包 - -1. 在下载机上安装 Ansible： - - 请按以下方式在 CentOS 7 系统的下载机上在线安装 Ansible。安装完成后，可通过 `ansible --version` 查看版本，请务必确认是 **Ansible 2.5.0** 版本，否则会有兼容问题。 - - {{< copyable "shell-root" >}} - - ```bash - yum install epel-release && - yum install ansible curl && - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -2. 下载 tidb-ansible： - - 使用以下命令从 Github [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应版本，默认的文件夹名称为 `tidb-ansible`。 - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-ansible.git - ``` - - > **注意：** - > - > 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 - -3. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到下载机： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-ansible && - ansible-playbook local_prepare.yml - ``` - -4. 将执行完以上命令之后的 `tidb-ansible` 文件夹拷贝到中控机 `/home/tidb` 目录下，文件属主权限需是 `tidb` 用户。 - -## 在中控机上配置部署机器 SSH 互信及 sudo 规则 - -参考[在中控机上配置部署机器 SSH 互信及 sudo 规则](/dev/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)即可。 - -## 在部署目标机器上安装 NTP 服务 - -如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略，可参考[如何检测 NTP 服务是否正常](/dev/how-to/deploy/orchestrated/ansible.md#如何检测-ntp-服务是否正常)。 - -参考[在部署目标机器上安装 NTP 服务](/dev/how-to/deploy/orchestrated/ansible.md#第-6-步在部署目标机器上安装-ntp-服务)即可。 - -## 在部署目标机器上配置 CPUfreq 调节器模式 - -参考[在部署目标机器上配置 CPUfreq 调节器模式](/dev/how-to/deploy/orchestrated/ansible.md#第-7-步在部署目标机器上配置-cpufreq-调节器模式)即可。 - -## 在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -参考[在部署目标机器上添加数据盘 ext4 文件系统挂载参数](/dev/how-to/deploy/orchestrated/ansible.md#第-8-步在部署目标机器上添加数据盘-ext4-文件系统挂载参数)即可。 - -## 分配机器资源，编辑 inventory.ini 文件 - -参考[分配机器资源，编辑 inventory.ini 文件](/dev/how-to/deploy/orchestrated/ansible.md#第-9-步编辑-inventoryini-文件分配机器资源)即可。 - -## 部署任务 - -1. `ansible-playbook local_prepare.yml` 该 playbook 不需要再执行。 - -2. 参考[部署任务](/dev/how-to/deploy/orchestrated/ansible.md#第-11-步部署-tidb-集群)即可。 - -## 测试集群 - -参考[测试集群](/dev/how-to/deploy/orchestrated/ansible.md#测试集群)即可。 diff --git a/dev/how-to/get-started/data-migration.md b/dev/how-to/get-started/data-migration.md deleted file mode 100644 index fe5898cd414c..000000000000 --- a/dev/how-to/get-started/data-migration.md +++ /dev/null @@ -1,523 +0,0 @@ ---- -title: TiDB Data Migration 教程 -category: how-to ---- - -# TiDB Data Migration 教程 - -TiDB Data Migration (DM) 是一体化的数据同步任务管理平台，支持将大量、复杂的生产环境中的数据从 MySQL 或 MariaDB 迁移到 TiDB。 - -DM 功能如下： - -- 数据迁移 - - 支持导出与导入源数据库的初始全量数据，并在数据迁移过程中读取、应用来自源数据库存储的 binlog，从而保持数据的同步。 - - 通过合并上游的多个 MySQL 或 MariaDB 实例或集群的表，DM 能迁移生产环境中的分库分表。 -- 将 TiDB 作为 MySQL 或 MariaDB 的从库时，DM 能持续提高数据库水平扩展的能力，或在无需 ETL 作业的情况下，在 TiDB 上进行数据实时分析。 - -本教程主要介绍如何使用 DM 迁移上游多个 MySQL 实例的一个分片表。包括两种场景： - -- 合并若干个互不冲突的表或分片，即这些表或分片的表结构并不会造成唯一键的冲突； -- 合并唯一键存在冲突的表。 - -本教程假设目前使用的是一台新的、纯净版 CentOS 7 实例，你能（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为需要运行多个服务，建议内存最好在 1 GB 以上。 - -> **警告：** -> -> 本教程中 TiDB 的部署方法并**不适用**于生产或开发环境。 - -## Data Migration 架构 - -![TiDB Data Migration 架构](/media/dm-architecture.png) - -TiDB Data Migration 平台由 3 部分组成：DM-master、DM-worker 和 dmctl。 - -* DM-master 负责管理和调度数据同步任务的操作。 -* DM-worker 负责执行特定的数据同步任务。 -* dmctl 是一个命令行工具，用于控制 DM 集群。 - -`.yaml` 文件中定义了各个数据同步任务，dmctl 会读取这些文件，并且这些文件会被提交给 DM-master。DM-master 再将关于给定任务的相应职责告知每个 DM-worker 实例。 - -详情参见 [Data Migration 简介](/dev/reference/tools/data-migration/overview.md)。 - -## 安装 - -本部分介绍如何部署 3 个 MySQL Server 实例及 `pd-server`、`tikv-server` 和 `tidb-server` 实例各 1 个，以及如何启动 1 个 DM-master 和 3 个 DM-worker 实例。 - -1. 安装 MySQL 5.7，下载或提取 TiDB v3.0 以及 DM v1.0.2 安装包： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install -y http://repo.mysql.com/yum/mysql-5.7-community/el/7/x86_64/mysql57-community-release-el7-10.noarch.rpm && - sudo yum install -y mysql-community-server && - curl https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - && - curl https://download.pingcap.org/dm-v1.0.2-linux-amd64.tar.gz | tar xzf - && - curl -L https://github.com/pingcap/docs/raw/master/dev/how-to/get-started/dm-cnf/dm-cnf.tgz | tar xvzf - - ``` - -2. 创建目录和符号链接： - - {{< copyable "shell-regular" >}} - - ```bash - mkdir -p bin data logs && - ln -sf -t bin/ "$HOME"/*/bin/* && - [[ :$PATH: = *:$HOME/bin:* ]] || echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile && . ~/.bash_profile - ``` - -3. 安装 3 个 MySQL Server 实例的配置： - - {{< copyable "shell-regular" >}} - - ```bash - tee -a "$HOME/.my.cnf" <}} - - ```bash - for i in 1 2 3 - do - echo "mysql$i" - mysqld --defaults-group-suffix="$i" --initialize-insecure - mysqld --defaults-group-suffix="$i" & - done - ``` - -5. 执行 `jobs` 和/或 `pgrep -a mysqld` 以确保 MySQL Server 实例都在运行状态。 - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running mysqld --defaults-group-suffix="$i" & - [2]- Running mysqld --defaults-group-suffix="$i" & - [3]+ Running mysqld --defaults-group-suffix="$i" & - ``` - - {{< copyable "shell-regular" >}} - - ```bash - pgrep -a mysqld - ``` - - ``` - 17672 mysqld --defaults-group-suffix=1 - 17727 mysqld --defaults-group-suffix=2 - 17782 mysqld --defaults-group-suffix=3 - ``` - -## 同步分片数据 - -本示例场景包含 3 个分片，这些分片表结构相同，但自增主键并不重叠。 - -在 `.my.cnf` 文件中设置 `auto-increment-increment=5` 和 `auto-increment-offset` 可以实现这种情况。将 `auto-increment-increment` 设置为 5，则这些实例的自增 ID 以 5 为单位递增；每个实例的 `auto-increment-offset` 都设置得不同，则这些实例的偏移为 0 到开始计数的值。例如，若一个实例的 `auto-increment-increment` 为 5，`auto-increment-offset` 为 2，则会生成自增 ID 序列 {2,7,12,17,22,…}。 - -1. 对于这 3 个 MySQL Server 实例，每个实例都分别创建数据库和表： - - {{< copyable "shell-regular" >}} - - ```bash - for i in 1 2 3 - do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root <}} - - ```bash - for i in 1 2 3; do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root dmtest1 <}} - - ```bash - for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select * from dmtest1.t1' - done | sort -n - ``` - -注意返回的列表左侧是一列递增的、无重叠的 ID，右侧的端口编号显示这些数据插入到哪些实例以及从哪些实例中查询： - -``` -... -1841 e8dfff4676a47048d6f0c4ef899593dd 3307 -1842 57c0531e13f40b91b3b0f1a30b529a1d 3308 -1843 4888241374e8c62ddd9b4c3cfd091f96 3309 -1846 f45a1078feb35de77d26b3f7a52ef502 3307 -1847 82cadb0649a3af4968404c9f6031b233 3308 -1848 7385db9a3f11415bc0e9e2625fae3734 3309 -1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 -1852 eb1e78328c46506b46a4ac4a1e378b91 3308 -1853 7503cfacd12053d309b6bed5c89de212 3309 -1856 3c947bc2f7ff007b86a9428b74654de5 3307 -1857 a3545bd79d31f9a72d3a78690adf73fc 3308 -1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 -``` - -### 启动 DM-master 和 DM-worker - -本小节介绍如何使用 DM 将来自不同的 MySQL 实例的数据合并到 TiDB 的一张表里。 - -配置文件包 `dm-cnf.tgz` 包含： - -- TiDB 集群组件和 DM 组件的配置 -- 本教程后文介绍的 2 个 DM 任务的配置 - -1. 启动单个 `tidb-server` 实例、每个 MySQL Server 实例 （总共 3 个实例）的 DM-worker 进程和一个 DM-master 进程： - - {{< copyable "shell-regular" >}} - - ```bash - tidb-server --log-file=logs/tidb-server.log & - for i in 1 2 3; do dm-worker --config=dm-cnf/dm-worker$i.toml & done - dm-master --config=dm-cnf/dm-master.toml & - ``` - -2. 执行 `jobs` 和/或 `ps -a`，确保这些进程都正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running mysqld --defaults-group-suffix="$i" & - [2] Running mysqld --defaults-group-suffix="$i" & - [3] Running mysqld --defaults-group-suffix="$i" & - [4] Running tidb-server --log-file=logs/tidb-server.log & - [5] Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [6] Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [7]- Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [8]+ Running dm-master --config=dm-cnf/dm-master.toml & - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ps -a - ``` - - ``` - PID TTY TIME CMD - 17317 pts/0 00:00:00 screen - 17672 pts/1 00:00:04 mysqld - 17727 pts/1 00:00:04 mysqld - 17782 pts/1 00:00:04 mysqld - 18586 pts/1 00:00:02 tidb-server - 18587 pts/1 00:00:00 dm-worker - 18588 pts/1 00:00:00 dm-worker - 18589 pts/1 00:00:00 dm-worker - 18590 pts/1 00:00:00 dm-master - 18892 pts/1 00:00:00 ps - ``` - -每个上游的 MySQL Server 实例对应一个单独的 DM-worker 实例，每个 DM-worker 实例都有各自的配置文件。这些文件内容包括： - -- 连接到上游 MySQL Server 的详细信息 -- relay log（上游服务器的 binlog）的存储路径 -- mydumper 的输出 - -各个 DM-worker 通过不同的端口监听（由 `worker-addr` 定义）。 - -以下为 `dm-worker1.toml` 的示例： - -{{< copyable "" >}} - -```toml -# DM-worker 配置 - -server-id = 1 -source-id = "mysql1" -flavor = "mysql" -worker-addr = ":8262" -log-file = "logs/worker1.log" -relay-dir = "data/relay1" -meta-dir = "data/meta1" -dir = "data/dump1" - -[from] -host = "127.0.0.1" -user = "root" -password = "" -port = 3307 -``` - -- 如果从 MySQL Server、Percona Server、Percona XtraDB Cluster、Amazon Aurora 或 RDS 迁移数据，则 `flavor` 配置项应设为 "mysql"（默认值，支持 5.5 < MySQL 版本 < 8.0）。 -- 如果从 MariaDB Server 或 MariaDB (Galera) Cluster 迁移数据，则设置 `flavor = "mariadb"`（仅支持 10.1.2 以上 MariaDB 版本）。 -- 从 DM 1.0.2 版本开始，`flavor`、`server-id` 项均会由 DM 自动生成，一般情况下不需要手动配置。 -- `from` 中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见[使用 dmctl 加密上游 MySQL 用户密码](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -任务在 YAML 文件中定义。以下为一个 `dmtask1.yaml` 文件示例： - -{{< copyable "" >}} - -```yaml -name: dmtask1 -task-mode: all -is-sharding: true -enable-heartbeat: true -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - source-id: "mysql1" - server-id: 1 - black-white-list: "dmtest1" - loader-config-name: "loader1" - - source-id: "mysql2" - server-id: 2 - black-white-list: "dmtest1" - loader-config-name: "loader2" - - source-id: "mysql3" - server-id: 3 - black-white-list: "dmtest1" - loader-config-name: "loader3" - -black-white-list: - dmtest1: - do-dbs: ["dmtest1"] - -loaders: - loader1: - dir: "data/dump1" - loader2: - dir: "data/dump2" - loader3: - dir: "data/dump3" -``` - -以上文件包含一些全局配置项和几组定义各种行为的配置项。 - -* `task-mode: all`：DM 导入上游实例的全量备份，并使用上游 MySQL Server 的 binlog 进行增量同步。 - - * 此外，可将 `task-mode` 设置为 `full` 或 `incremental` 以分别进行全量备份或增量同步。 - -* `is-sharding: true`：多个 DM-worker 实例进行同一个任务，这些实例将上游的若干分片合并到一个下游的表中。 - -* `ignore-checking-items: ["auto_increment_ID"]`：关闭 DM 对上游实例中潜在的自增 ID 冲突的检测。DM 能检测出上游表结构相同、并包含自增列的分片间潜在的列值冲突。通过配置 `auto-increment-increment` 和 `auto-increment-offset` 可使每个 MySQL Server 的 ID 都不重叠，从而避免不同表之间冲突的产生。因此，可以让 DM 关闭对自增 ID 冲突的检测。 - -* `black-white-list`：将一个任务限制在数据库 `dmtest` 中。 - -* `loaders`：定义由各个 DM-worker 实例执行的每个 mydumper 实例的输出地址。 - -* `target-database`：定义目标数据库的链接信息，其中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见 [使用 dmctl 加密上游 MySQL 用户密码](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -`dmctl` 是控制 DM 集群的命令行工具，用于启动任务、查询任务状态。执行 `dmctl -master-addr :8261` 获取如下交互提示，从而启动该工具： - -{{< copyable "shell-regular" >}} - -```bash -dmctl -master-addr :8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-alpha-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 - -» -``` - -执行 `start-task dm-cnf/dmtask1.yaml` 启动 `dmtask1`： - -{{< copyable "shell-regular" >}} - -```bash -start-task dm-cnf/dmtask1.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - }, - { - "result": true, - "worker": "127.0.0.1:8264", - "msg": "" - } - ] -} -``` - -启动该任务意味着启动任务配置文件中定义的行为，包括执行 mydumper 和 loader 实例，加载初次 dump 的数据后，将 DM-worker 作为同步任务的 slave 连接到上游的 MySQL Server。 - -所有的行数据都被迁移到 TiDB Server： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -... -1843 4888241374e8c62ddd9b4c3cfd091f96 3309 -1846 f45a1078feb35de77d26b3f7a52ef502 3307 -1847 82cadb0649a3af4968404c9f6031b233 3308 -1848 7385db9a3f11415bc0e9e2625fae3734 3309 -1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 -1852 eb1e78328c46506b46a4ac4a1e378b91 3308 -1853 7503cfacd12053d309b6bed5c89de212 3309 -1856 3c947bc2f7ff007b86a9428b74654de5 3307 -1857 a3545bd79d31f9a72d3a78690adf73fc 3308 -1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 -``` - -现在 DM 正作为每个 MySQL Server 的 slave，读取 MySQL Server 的 binlog，将更新的数据实时同步到下游的 TiDB Server： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3 -do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select host, command, state from information_schema.processlist where command="Binlog Dump"' -done -``` - -输出结果： - -``` -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:42168 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:42922 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:56798 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -``` - -向上游 MySQL Server 插入几行数据，更新 MySQL 中的这些行，并再次查询这些行： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'insert into t1 (id) select null from t1' dmtest1 -done -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -6313 NULL NULL -6316 NULL NULL -6317 NULL NULL -6318 NULL NULL -6321 NULL NULL -6322 NULL NULL -6323 NULL NULL -6326 NULL NULL -6327 NULL NULL -6328 NULL NULL -``` - -更新这些行，则可见更新的数据已同步到 TiDB 中： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'update t1 set c=md5(id), port=@@port' dmtest1 -done | sort -n -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -6313 2118d8a1b7004ed5baf5347a4f99f502 3309 -6316 6107d91fc9a0b04bc044aa7d8c1443bd 3307 -6317 0e9b734aa25ca8096cb7b56dc0dd8929 3308 -6318 b0eb9a95e8b085e4025eae2f0d76a6a6 3309 -6321 7cb36e23529e4de4c41460940cc85e6e 3307 -6322 fe1f9c70bdf347497e1a01b6c486bdb9 3308 -6323 14eac0d254a6ccaf9b67584c7830a5c0 3309 -6326 17b65afe58c49edc1bdd812c554ee3bb 3307 -6327 c54bc2ded4480856dc9f39bdcf35a3e7 3308 -6328 b294504229c668e750dfcc4ea9617f0a 3309 -``` - -只要 DM-master 和 DM-worker 运行 `dmtest1` 任务，下游的 TiDB Server 将持续和上游的 MySQL Server 实例保持同步的状态。 - -## 结论 - -本教程完成了上游 3 个 MySQL Server 实例的分片迁移，介绍了分片迁移中，DM 如何在集群中导入初始数据，以及如何读取 MySQL 的 binlog 来同步增量数据，从而使下游 TiDB 集群与上游实例保持同步。 - -关于 DM 的更多详情，请参考 [Data Migration 简介](/dev/reference/tools/data-migration/overview.md)，或加入 [TiDB Community Slack](https://pingcap.com/tidbslack/) channel 参与讨论。 diff --git a/dev/how-to/get-started/deploy-tidb-from-docker-compose.md b/dev/how-to/get-started/deploy-tidb-from-docker-compose.md deleted file mode 100644 index 16d3971fd1b1..000000000000 --- a/dev/how-to/get-started/deploy-tidb-from-docker-compose.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: 使用 Docker Compose 快速构建 TiDB 集群 -category: how-to ---- - -# 使用 Docker Compose 快速构建 TiDB 集群 - -本文档介绍如何在单机上通过 Docker Compose 快速一键部署一套 TiDB 测试集群。[Docker Compose](https://docs.docker.com/compose/overview) 可以通过一个 YAML 文件定义多个容器的应用服务，然后一键启动或停止。 - -> **警告：** -> -> 对于生产环境，不要使用 Docker Compose 进行部署，而应[使用 Ansible 部署 TiDB 集群](/dev/how-to/deploy/orchestrated/ansible.md)。 - -## 准备环境 - -确保你的机器上已安装： - -- Docker（17.06.0 及以上版本） -- Docker Compose -- Git - -## 快速部署 - -1. 下载 `tidb-docker-compose` - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -2. 创建并启动集群 - - 获取最新 Docker 镜像： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-docker-compose && docker-compose pull && docker-compose up -d - ``` - -3. 访问集群 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - [集群数据可视化](https://github.com/pingcap/tidb-vision)： - -## 自定义集群 - -在完成快速部署后，以下组件已默认部署：3 个 PD，3 个 TiKV，1 个 TiDB 和监控组件 Prometheus，Pushgateway，Grafana 以及 tidb-vision。 - -如果想自定义集群，可以直接修改 `docker-compose.yml`，但是手动修改比较繁琐而且容易出错，强烈建议使用 [Helm](https://helm.sh) 模板引擎生成 `docker-compose.yml` 文件。 - -1. 安装 Helm - - [Helm](https://helm.sh) 可以用作模板渲染引擎，只需要下载其 binary 文件即可以使用。 - - {{< copyable "shell-regular" >}} - - ```bash - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果是 Mac 系统，也可以通过 Homebrew 安装： - - {{< copyable "shell-regular" >}} - - ```bash - brew install kubernetes-helm - ``` - -2. 下载 `tidb-docker-compose` - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -3. 自定义集群 - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-docker-compose && - cp compose/values.yaml values.yaml && - vim values.yaml - ``` - - 修改 `values.yaml` 里面的配置，例如集群规模，TiDB 镜像版本等。 - - [tidb-vision](https://github.com/pingcap/tidb-vision) 是 TiDB 集群可视化页面，可以可视化地显示 PD 对 TiKV 数据的调度。如果不想部署该组件，可以将 `tidbVision` 项留空。 - - PD，TiKV，TiDB 和 tidb-vision 支持从 GitHub 源码或本地文件构建 Docker 镜像，供开发测试使用。 - - - 如果希望从本地已编译好的 binary 文件构建 PD，TiKV 或 TiDB 镜像，需要将其 `image` 字段留空，并将已编译好的 binary 拷贝到对应的 `pd/bin/pd-server`，`tikv/bin/tikv-server`，`tidb/bin/tidb-server`。 - - - 如果希望从本地构建 tidb-vision 镜像，需要将其 `image` 字段留空，并将 tidb-vision 项目拷贝到 `tidb-vision/tidb-vision`。 - -4. 生成 `docker-compose.yml` 文件 - - {{< copyable "shell-regular" >}} - - ```bash - helm template -f values.yaml compose > generated-docker-compose.yml - ``` - -5. 使用生成的 `docker-compose.yml` 创建并启动集群 - - 获取最新 Docker 镜像： - - {{< copyable "shell-regular" >}} - - ```bash - docker-compose -f generated-docker-compose.yml pull - ``` - - {{< copyable "shell-regular" >}} - - ```bash - docker-compose -f generated-docker-compose.yml up -d - ``` - -6. 访问集群 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - 如果启用了 tidb-vision，可以通过 查看。 - -## 访问 Spark shell 并加载 TiSpark - -向 TiDB 集群中插入一些样本数据： - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master bash && -cd /opt/spark/data/tispark-sample-data && -mysql -h tidb -P 4000 -u root < dss.ddl -``` - -当样本数据加载到 TiDB 集群之后，可以使用 `docker-compose exec tispark-master /opt/spark/bin/spark-shell` 来访问 Spark shell。 - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master /opt/spark/bin/spark-shell -``` - -``` -... -Spark context available as 'sc' (master = local[*], app id = local-1527045927617). -Spark session available as 'spark'. -Welcome to - ____ __ - / __/__ ___ _____/ /__ - _\ \/ _ \/ _ `/ __/ '_/ - /___/ .__/\_,_/_/ /_/\_\ version 2.1.1 - /_/ - -Using Scala version 2.11.8 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_172) -Type in expressions to have them evaluated. -Type :help for more information. -``` - -```shell -scala> import org.apache.spark.sql.TiContext -... -scala> val ti = new TiContext(spark) -... -scala> ti.tidbMapDatabase("TPCH_001") -... -scala> spark.sql("select count(*) from lineitem").show -``` - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -你也可以通过 Python 或 R 来访问 Spark： - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master /opt/spark/bin/pyspark && -docker-compose exec tispark-master /opt/spark/bin/sparkR -``` - -更多关于 TiSpark 的信息，参见 [TiSpark 的详细文档](/dev/how-to/get-started/tispark.md)。 diff --git a/dev/how-to/get-started/explore-sql.md b/dev/how-to/get-started/explore-sql.md deleted file mode 100644 index b88da0235dc1..000000000000 --- a/dev/how-to/get-started/explore-sql.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: TiDB 中的基本 SQL 操作 -category: how-to ---- - -# TiDB 中的基本 SQL 操作 - -成功部署 TiDB 集群之后，便可以在 TiDB 中执行 SQL 语句了。因为 TiDB 兼容 MySQL，你可以使用 MySQL 客户端连接 TiDB，并且[大多数情况下](/dev/reference/mysql-compatibility.md)可以直接执行 MySQL 语句。 - -本文介绍 CRUD 操作等基本的 SQL 语句。完整的 SQL 语句列表，参见 [TiDB SQL 语法详解](https://pingcap.github.io/sqlgram/)。 - -## 创建、查看和删除数据库 - -使用 `CREATE DATABASE` 语句创建数据库。语法如下： - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE db_name [options]; -``` - -例如，要创建一个名为 `samp_db` 的数据库，可使用以下语句： - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE IF NOT EXISTS samp_db; -``` - -使用 `SHOW DATABASES` 语句查看数据库： - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -使用 `DROP DATABASE` 语句删除数据库，例如： - -{{< copyable "sql" >}} - -```sql -DROP DATABASE samp_db; -``` - -## 创建、查看和删除表 - -使用 `CREATE TABLE` 语句创建表。语法如下： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE table_name column_name data_type constraint; -``` - -例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - number INT(11), - name VARCHAR(255), - birthday DATE - ); -``` - -如果表已存在，添加 `IF NOT EXISTS` 可防止发生错误： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE IF NOT EXISTS person ( - number INT(11), - name VARCHAR(255), - birthday DATE -); -``` - -使用 `SHOW CREATE` 语句查看建表语句。例如： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE table person; -``` - -使用 `SHOW FULL COLUMNS` 语句查看表的列。 例如： - -{{< copyable "sql" >}} - -```sql -SHOW FULL COLUMNS FROM person; -``` - -使用 `DROP TABLE` 语句删除表。例如： - -{{< copyable "sql" >}} - -```sql -DROP TABLE person; -``` - -或者 - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS person; -``` - -使用 `SHOW TABLES` 语句查看数据库中的所有表。例如： - -{{< copyable "sql" >}} - -```sql -SHOW TABLES FROM samp_db; -``` - -## 创建、查看和删除索引 - -对于值不唯一的列，可使用 `CREATE INDEX` 或 `ALTER TABLE` 语句。例如： - -{{< copyable "sql" >}} - -```sql -CREATE INDEX person_num ON person (number); -``` - -或者 - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person ADD INDEX person_num (number); -``` - -对于值唯一的列，可以创建唯一索引。例如： - -{{< copyable "sql" >}} - -```sql -CREATE UNIQUE INDEX person_num ON person (number); -``` - -或者 - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person ADD UNIQUE person_num (number); -``` - -使用 `SHOW INDEX` 语句查看表内所有索引： - -{{< copyable "sql" >}} - -```sql -SHOW INDEX from person; -``` - -使用 `ALTER TABLE` 或 `DROP INDEX` 语句来删除索引。与 `CREATE INDEX` 语句类似，`DROP INDEX` 也可以嵌入 `ALTER TABLE` 语句。例如： - -{{< copyable "sql" >}} - -```sql -DROP INDEX person_num ON person; -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person DROP INDEX person_num; -``` - -## 增删改查数据 - -使用 `INSERT` 语句向表内插入数据。例如： - -{{< copyable "sql" >}} - -```sql -INSERT INTO person VALUES("1","tom","20170912"); -``` - -使用 `SELECT` 语句检索表内数据。例如： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-09-12 | -+--------+------+------------+ -``` - -使用 `UPDATE` 语句修改表内数据。例如： - -{{< copyable "sql" >}} - -```sql -UPDATE person SET birthday='20171010' WHERE name='tom'; -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-10-10 | -+--------+------+------------+ -``` - -使用 `DELETE` 语句删除表内数据： - -{{< copyable "sql" >}} - -```sql -DELETE FROM person WHERE number=1; -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -Empty set (0.00 sec) -``` - -## 创建、授权和删除用户 - -使用 `CREATE USER` 语句创建一个用户 `tiuser`，密码为 `123456`： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456'; -``` - -授权用户 `tiuser` 可检索数据库 `samp_db` 内的表： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost'; -``` - -查询用户 `tiuser` 的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS for tiuser@localhost; -``` - -删除用户 `tiuser`： - -{{< copyable "sql" >}} - -```sql -DROP USER 'tiuser'@'localhost'; -``` diff --git a/dev/how-to/get-started/read-historical-data.md b/dev/how-to/get-started/read-historical-data.md deleted file mode 100644 index 4918803e5c69..000000000000 --- a/dev/how-to/get-started/read-historical-data.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: 读取历史数据 -category: how-to ---- - -# 读取历史数据 - -本文档介绍 TiDB 如何读取历史版本数据，包括具体的操作流程以及历史数据的保存策略。 - -## 功能说明 - -TiDB 实现了通过标准 SQL 接口读取历史数据功能，无需特殊的 client 或者 driver。当数据被更新、删除后，依然可以通过 SQL 接口将更新/删除前的数据读取出来。 - -另外即使在更新数据之后，表结构发生了变化，TiDB 依旧能用旧的表结构将数据读取出来。 - -## 操作流程 - -为支持读取历史版本数据， 引入了一个新的 system variable: tidb_snapshot ，这个变量是 Session 范围有效，可以通过标准的 Set 语句修改其值。其值为文本，能够存储 TSO 和日期时间。TSO 即是全局授时的时间戳，是从 PD 端获取的; 日期时间的格式可以为： -“2016-10-08 16:45:26.999”，一般来说可以只写到秒，比如”2016-10-08 16:45:26”。 -当这个变量被设置时，TiDB 会用这个时间戳建立 Snapshot（没有开销，只是创建数据结构），随后所有的 Select 操作都会在这个 Snapshot 上读取数据。 - -> **注意：** -> -> TiDB 的事务是通过 PD 进行全局授时，所以存储的数据版本也是以 PD 所授时间戳作为版本号。在生成 Snapshot 时，是以 tidb_snapshot 变量的值作为版本号，如果 TiDB Server 所在机器和 PD Server 所在机器的本地时间相差较大，需要以 PD 的时间为准。 - -当读取历史版本操作结束后，可以结束当前 Session 或者是通过 Set 语句将 tidb_snapshot 变量的值设为 ""，即可读取最新版本的数据。 - -## 历史数据保留策略 - -TiDB 使用 MVCC 管理版本，当更新/删除数据时，不会做真正的数据删除，只会添加一个新版本数据，所以可以保留历史数据。历史数据不会全部保留，超过一定时间的历史数据会被彻底删除，以减小空间占用以及避免历史版本过多引入的性能开销。 - -TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理，关于 GC 的详细介绍参见 [TiDB 垃圾回收 (GC)](/dev/reference/garbage-collection/overview.md)。 - -这里需要重点关注的是 `tikv_gc_life_time` 和 `tikv_gc_safe_point` 这条。`tikv_gc_life_time` 用于配置历史版本保留时间，可以手动修改；`tikv_gc_safe_point` 记录了当前的 safePoint，用户可以安全地使用大于 safePoint 的时间戳创建 snapshot 读取历史版本。safePoint 在每次 GC 开始运行时自动更新。 - -## 示例 - -1. 初始化阶段，创建一个表，并插入几行数据： - - {{< copyable "sql" >}} - - ```sql - create table t (c int); - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - insert into t values (1), (2), (3); - ``` - - ``` - Query OK, 3 rows affected (0.00 sec) - ``` - -2. 查看表中的数据： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -3. 查看当前时间： - - {{< copyable "sql" >}} - - ```sql - select now(); - ``` - - ``` - +---------------------+ - | now() | - +---------------------+ - | 2016-10-08 16:45:26 | - +---------------------+ - 1 row in set (0.00 sec) - ``` - -4. 更新某一行数据： - - {{< copyable "sql" >}} - - ```sql - update t set c=22 where c=2; - ``` - - ``` - Query OK, 1 row affected (0.00 sec) - ``` - -5. 确认数据已经被更新： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -6. 设置一个特殊的环境变量，这个是一个 session scope 的变量，其意义为读取这个时间之前的最新的一个版本。 - - {{< copyable "sql" >}} - - ```sql - set @@tidb_snapshot="2016-10-08 16:45:26"; - ``` - - ``` - Query OK, 0 rows affected (0.00 sec) - ``` - - > **注意：** - > - > - 这里的时间设置的是 update 语句之前的那个时间。 - > - 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 - - 这里读取到的内容即为 update 之前的内容，也就是历史版本： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -7. 清空这个变量后，即可读取最新版本数据： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_snapshot=""; - ``` - - ``` - Query OK, 0 rows affected (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - - > **注意：** - > - > 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 diff --git a/dev/how-to/get-started/tidb-binlog.md b/dev/how-to/get-started/tidb-binlog.md deleted file mode 100644 index e9b7f3c8f8c8..000000000000 --- a/dev/how-to/get-started/tidb-binlog.md +++ /dev/null @@ -1,521 +0,0 @@ ---- -title: TiDB Binlog 教程 -category: how-to ---- - -# TiDB Binlog 教程 - -本文档主要介绍如何使用 TiDB Binlog 将数据从 TiDB 推送到 MariaDB 实例。文中的 TiDB Binlog 集群包含 Pump 和 Drainer 的单个节点，TiDB 集群包含 TiDB、TiKV 和 Placement Driver (PD) 各组件的单个节点。 - -希望上手实践 TiDB Binlog 工具的用户需要对 [TiDB 架构](/dev/architecture.md)有一定的了解，最好有创建过 TiDB 集群的经验。该文档也有助于简单快速了解 TiDB Binlog 架构以及相关概念。 - -> **警告：** -> -> 该文档中部署 TiDB 的操作指导**不适用于**在生产或研发环境中部署 TiDB 的情况。 - -该文档假设用户使用的是现代 Linux 发行版本中的 x86-64。示例中使用的是 VMware 中运行的 CentOS 7 最小化安装。建议在一开始就进行清洁安装，以避免受现有环境中未知情况的影响。如果不想使用本地虚拟环境，也可以使用云服务启动 CentOS 7 VM。 - -## TiDB Binlog 简介 - -TiDB Binlog 用于收集 TiDB 中二进制日志数据、提供实时数据备份和同步以及将 TiDB 集群的数据增量同步到下游。 - -TiDB Binlog 支持以下功能场景： - -- 增量备份，将 TiDB 集群中的数据增量同步到另一个集群，或通过 Kafka 增量同步到选择的下游。 -- 当使用 TiDB DM (Data Migration) 将数据从上游 MySQL 或者 MariaDB 迁移到 TiDB 集群时，可使用 TiDB Binlog 保持 TiDB 集群与其一个独立下游 MySQL 或 MariaDB 实例或集群同步。当 TiDB 集群上游数据迁移过程中出现问题，下游数据同步过程中可使用 TiDB Binlog 恢复数据到原先的状态。 - -更多信息参考 [TiDB Binlog Cluster 版本用户文档](/dev/reference/tidb-binlog/overview.md)。 - -## 架构 - -TiDB Binlog 集群由 **Pump** 和 **Drainer** 两个组件组成。一个 Pump 集群中有若干个 Pump 节点。TiDB 实例连接到各个 Pump 节点并发送 binlog 数据到 Pump 节点。Pump 集群连接到 Drainer 节点，Drainer 将接收到的更新数据转换到某个特定下游（例如 Kafka、另一个 TiDB 集群或 MySQL 或 MariaDB Server）指定的正确格式。 - -![TiDB Binlog architecture](/media/tidb_binlog_cluster_architecture.png) - -Pump 的集群架构能确保 TiDB 或 Pump 集群中有新的实例加入或退出时更新数据不会丢失。 - -## 安装 - -由于 RHEL/CentOS 7 的默认包装库中包括 MariaDB Server，本示例选择的是 MariaDB Server。后续除了安装服务器，也需要安装客户端。安装指令如下： - -{{< copyable "shell-regular" >}} - -```bash -sudo yum install -y mariadb-server -``` - -{{< copyable "shell-regular" >}} - -```bash -curl -LO https://download.pingcap.org/tidb-latest-linux-amd64.tar.gz | tar xzf - && -cd tidb-latest-linux-amd64 -``` - -预期输出： - -``` - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 368M 100 368M 0 0 8394k 0 0:00:44 0:00:44 --:--:-- 11.1M -``` - -## 配置 - -通过执行以下步骤配置一个 TiDB 集群，该集群包括 `pd-server`、`tikv-server` 和 `tidb-server` 各组件的单个实例。 - -1. 填充配置文件： - - {{< copyable "shell-regular" >}} - - ```bash - printf > pd.toml %s\\n 'log-file="pd.log"' 'data-dir="pd.data"' && - printf > tikv.toml %s\\n 'log-file="tikv.log"' '[storage]' 'data-dir="tikv.data"' '[pd]' 'endpoints=["127.0.0.1:2379"]' '[rocksdb]' max-open-files=1024 '[raftdb]' max-open-files=1024 && - printf > pump.toml %s\\n 'log-file="pump.log"' 'data-dir="pump.data"' 'addr="127.0.0.1:8250"' 'advertise-addr="127.0.0.1:8250"' 'pd-urls="http://127.0.0.1:2379"' && - printf > tidb.toml %s\\n 'store="tikv"' 'path="127.0.0.1:2379"' '[log.file]' 'filename="tidb.log"' '[binlog]' 'enable=true' && - printf > drainer.toml %s\\n 'log-file="drainer.log"' '[syncer]' 'db-type="mysql"' '[syncer.to]' 'host="127.0.0.1"' 'user="root"' 'password=""' 'port=3306' - ``` - -2. 查看配置细节： - - {{< copyable "shell-regular" >}} - - ```bash - for f in *.toml; do echo "$f:"; cat "$f"; echo; done - ``` - - 预期输出： - - ``` - drainer.toml: - log-file="drainer.log" - [syncer] - db-type="mysql" - [syncer.to] - host="127.0.0.1" - user="root" - password="" - port=3306 - - pd.toml: - log-file="pd.log" - data-dir="pd.data" - - pump.toml: - log-file="pump.log" - data-dir="pump.data" - addr="127.0.0.1:8250" - advertise-addr="127.0.0.1:8250" - pd-urls="http://127.0.0.1:2379" - - tidb.toml: - store="tikv" - path="127.0.0.1:2379" - [log.file] - filename="tidb.log" - [binlog] - enable=true - - tikv.toml: - log-file="tikv.log" - [storage] - data-dir="tikv.data" - [pd] - endpoints=["127.0.0.1:2379"] - [rocksdb] - max-open-files=1024 - [raftdb] - max-open-files=1024 - ``` - -## 启动程序 - -现在可启动各个组件。推荐启动顺序依次为 Placement Driver (PD)、TiKV、Pump（TiDB 发送 binlog 日志必须连接 Pump 服务）、TiDB。 - -1. 启动所有服务： - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pd-server --config=pd.toml &>pd.out & - ``` - - ``` - [1] 20935 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/tikv-server --config=tikv.toml &>tikv.out & - ``` - - ``` - [2] 20944 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump --config=pump.toml &>pump.out & - ``` - - ``` - [3] 21050 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - sleep 3 && - ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - ``` - [4] 21058 - ``` - -2. 如果执行 `jobs`，可以看到后台正在运行的程序，列表如下： - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running ./bin/pd-server --config=pd.toml &>pd.out & - [2] Running ./bin/tikv-server --config=tikv.toml &>tikv.out & - [3]- Running ./bin/pump --config=pump.toml &>pump.out & - [4]+ Running ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - 如果有服务启动失败（例如出现 “`Exit 1`” 而不是 “`Running`”），尝试重启单个组件。 - -## 连接 - -按以上步骤操作后，TiDB 的 4 个组件开始运行。接下来可以使用以下 MariaDB 或 MySQL 命令行客户端，通过 4000 端口连接到 TiDB 服务： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select tidb_version();' -``` - -预期输出： - -``` -*************************** 1. row *************************** -tidb_version(): Release Version: v3.0.0-beta.1-154-gd5afff70c -Git Commit Hash: d5afff70cdd825d5fab125c8e52e686cc5fb9a6e -Git Branch: master -UTC Build Time: 2019-04-24 03:10:00 -GoVersion: go version go1.12 linux/amd64 -Race Enabled: false -TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e -Check Table Before Drop: false -``` - -连接后TiDB 集群已开始运行，`pump` 读取集群中的 binlog 数据，并在其数据目录中将 binlog 数据存储为 relay log。下一步是启动一个可供 `drainer` 写入的 MariaDB Server。 - -1. 启动 `drainer`： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl start mariadb && - ./bin/drainer --config=drainer.toml &>drainer.out & - ``` - - 如果你的操作系统更易于安装 MySQL，只需保证监听 3306 端口。另外，可使用密码为空的 "root" 用户连接到 MySQL，或调整 `drainer.toml` 连接到 MySQL。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 3306 -u root - ``` - - 预期输出： - - ``` - Welcome to the MariaDB monitor. Commands end with ; or \g. - Your MariaDB connection id is 20 - Server version: 5.5.60-MariaDB MariaDB Server - - Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - MariaDB [(none)]> - ``` - - {{< copyable "sql" >}} - - ```sql - show databases; - ``` - - 预期输出： - - ``` - +--------------------+ - | Database | - +--------------------+ - | information_schema | - | mysql | - | performance_schema | - | test | - | tidb_binlog | - +--------------------+ - 5 rows in set (0.01 sec) - ``` - - 如下表格是包含 `checkpoint` 表格的 `tidb_binlog` 数据库。`drainer` 使用 `checkpoint` 表格，记录 TiDB 集群中的 binlog 已经更新到了哪个位置。 - - {{< copyable "sql" >}} - - ```sql - use tidb_binlog; - ``` - - ``` - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - select * from checkpoint; - ``` - - ``` - +---------------------+---------------------------------------------+ - | clusterID | checkPoint | - +---------------------+---------------------------------------------+ - | 6678715361817107733 | {"commitTS":407637466476445697,"ts-map":{}} | - +---------------------+---------------------------------------------+ - 1 row in set (0.00 sec) - ``` - - 打开另一个连接到 TiDB 的客户端，创建一个表格并插入几行数据。建议在 GNU Screen 软件中操作，从而同时打开多个客户端。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 --prompt='TiDB [\d]> ' -u root - ``` - - {{< copyable "sql" >}} - - ```sql - create database tidbtest; - ``` - - ``` - Query OK, 0 rows affected (0.12 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - use tidbtest; - ``` - - ``` - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - create table t1 (id int unsigned not null AUTO_INCREMENT primary key); - ``` - - ``` - Query OK, 0 rows affected (0.11 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - insert into t1 () values (),(),(),(),(); - ``` - - ``` - Query OK, 5 rows affected (0.01 sec) - Records: 5 Duplicates: 0 Warnings: 0 - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t1; - ``` - - ``` - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 切换回 MariaDB 客户端可看到新的数据库、新的表格和最近插入的行数据。 - - {{< copyable "sql" >}} - - ```sql - use tidbtest; - ``` - - ``` - Reading table information for completion of table and column names - You can turn off this feature to get a quicker startup with -A - - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - show tables; - ``` - - ``` - +--------------------+ - | Tables_in_tidbtest | - +--------------------+ - | t1 | - +--------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t1; - ``` - - ``` - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 可看到查询 MariaDB 时插入到 TiDB 相同的行数据，表明 TiDB Binlog 安装成功。 - -## binlogctl - -加入到集群的 Pump 和 Drainer 的数据存储在 Placement Driver (PD) 中。binlogctl 可用于查询和修改状态信息。更多信息请参考 [binlogctl guide](/dev/reference/tidb-binlog/maintain.md#binlogctl-工具)。 - -使用 `binlogctl` 查看集群中 Pump 和 Drainer 的当前状态： - -{{< copyable "shell-regular" >}} - -```bash -./bin/binlogctl -cmd drainers -``` - -``` -[2019/04/11 17:44:10.861 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: online, MaxCommitTS: 407638907719778305, UpdateTime: 2019-04-11 17:44:10 -0400 EDT}"] -``` - -{{< copyable "shell-regular" >}} - -```bash -./bin/binlogctl -cmd pumps -``` - -``` -[2019/04/11 17:44:13.904 -04:00] [INFO] [nodes.go:47] ["query node"] [type=pump] [node="{NodeID: localhost.localdomain:8250, Addr: 192.168.236.128:8250, State: online, MaxCommitTS: 407638914024079361, UpdateTime: 2019-04-11 17:44:13 -0400 EDT}"] -``` - -如果结束 Drainer 进程，集群会改进程设置“已暂停（即集群等待 Drainer 重新加入）”的状态。 - -{{< copyable "shell-regular" >}} - -```bash -pkill drainer && -./bin/binlogctl -cmd drainers -``` - -预期输出： - -``` -[2019/04/11 17:44:22.640 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: paused, MaxCommitTS: 407638915597467649, UpdateTime: 2019-04-11 17:44:18 -0400 EDT}"] -``` - -使用 binlogctl 的 "NodeIDs" 可控制单个对应节点。在该情况下，Drainer 的节点 ID 是 "localhost.localdomain:8249"，Pump 的节点 ID 是 "localhost.localdomain:8250"。 - -本文档中的 binlogctl 主要用于集群重启。如果在 TiDB 集群中终止并尝试重启所有的进程，由于 Pump 无法连接 Drainer 且认为 Drainer 依旧“在线”，Pump 会拒绝启动。这里的进程并不包括下游的 MySQL 或 MariaDB 或 Drainer。 - -以下有三个方案可解决上述问题： - -- 使用 binlogctl 停止 Drainer，而不是结束进程： - - ```bash - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=drainers && - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=pause-drainer --node-id=localhost.localdomain:8249 - ``` - -- 在启动 Pump **之前**先启动 Drainer。 - -- 在启动 PD 之后但在启动 Drainer 和 Pump 之前，使用 binlogctl 更新已暂定 Drainer 的状态。 - - ```bash - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=update-drainer --node-id=localhost.localdomain:8249 --state=paused - ``` - -## 清理 - -在 shell 终端里可启动创建集群的所有进程（`pd-server` 、`tikv-server`、`pump`、`tidb-server`、`drainer`）。可通过在 shell 终端中执行 `pkill -P $$` 停止 TiDB 集群服务和 TiDB Binlog 进程。按一定的顺序停止这些进程有利于留出足够的时间彻底关闭每个组件。 - -{{< copyable "shell-regular" >}} - -```bash -for p in tidb-server drainer pump tikv-server pd-server; do pkill "$p"; sleep 1; done -``` - -预期输出： - -``` -[4]- Done ./bin/tidb-server --config=tidb.toml &>tidb.out -[5]+ Done ./bin/drainer --config=drainer.toml &>drainer.out -[3]+ Done ./bin/pump --config=pump.toml &>pump.out -[2]+ Done ./bin/tikv-server --config=tikv.toml &>tikv.out -[1]+ Done ./bin/pd-server --config=pd.toml &>pd.out -``` - -如果需要所有服务退出后重启集群，可以使用一开始启动服务的命令。如以上 [`binlogctl`](#binlogctl) 部分所述，需要先启动 Drainer 再启动 Pump，最后启动 `tidb-server`。 - -{{< copyable "shell-regular" >}} - -```bash -./bin/pd-server --config=pd.toml &>pd.out & -./bin/tikv-server --config=tikv.toml &>tikv.out & -./bin/drainer --config=drainer.toml &>drainer.out & -sleep 3 -./bin/pump --config=pump.toml &>pump.out & -sleep 3 -./bin/tidb-server --config=tidb.toml &>tidb.out & -``` - -如果有组件启动失败，请尝试单独重启该组件。 - -## 总结 - -本文档介绍了如何通过设置 TiDB Binlog，使用单个 Pump 和 Drainer 组成的集群同步 TiDB 集群数据到下游的 MariaDB。可以发现，TiDB Binlog 是用于获取处理 TiDB 集群中更新数据的综合性平台工具。 - -在更稳健的开发、测试或生产部署环境中，可以使用多个 TiDB 服务以实现高可用性和扩展性。使用多个 Pump 实例可以避免 Pump 集群中的问题影响发送到 TiDB 实例的应用流量。或者可以使用增加的 Drainer 实例同步数据到不同的下游或实现数据增量备份。 -binlog \ No newline at end of file diff --git a/dev/how-to/get-started/tidb-lightning.md b/dev/how-to/get-started/tidb-lightning.md deleted file mode 100644 index ac8d266d81ad..000000000000 --- a/dev/how-to/get-started/tidb-lightning.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: TiDB Lightning 教程 -category: how-to ---- - -# TiDB Lightning 教程 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -TiDB Lightning 主要包含两个部分: - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键/值对 (KV 对) 发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，把 `tidb-lightning` 写入的 KV 对缓存、排序、切分并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -本教程假设使用的是若干新的、纯净版 CentOS 7 实例，你可以（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为 TiDB Lightning 对计算机资源消耗较高，建议分配 4 GB 以上的内存。 - -> **警告：** -> -> 本教程中的部署方法只适用于测试及功能体验，并不适用于生产或开发环境。 - -## 准备全量备份数据 - -我们使用 [`mydumper`](/dev/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -这样全量备份数据就导出到了 `/data/my_database` 目录中。 - -## 部署 TiDB Lightning - -### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群（版本要求 2.0.9 以上），本教程使用 TiDB 3.0.4 版本。部署方法可参考 [TiDB 快速入门指南](/dev/overview.md#部署方式)。 - -### 第 2 步：下载 TiDB Lightning 安装包 - -通过以下链接获取 TiDB Lightning 安装包（选择与 TiDB 集群相同的版本）： - -- **v3.0.4**: [tidb-toolkit-v3.0.4-linux-amd64.tar.gz](https://download.pingcap.org/tidb-toolkit-v3.0.0-linux-amd64.tar.gz) - -### 第 3 步：启动 `tikv-importer` - -1. 将安装包里的 `bin/tikv-importer` 上传至部署 TiDB Lightning 的服务器。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -### 第 4 步：启动 `tidb-lightning` - -1. 将安装包里的 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。 - -2. 将数据源也上传到同样的服务器。 - -3. 配置合适的参数运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning \ - --importer 172.16.31.10:8287 \ - -d /data/my_database/ \ - --tidb-server 172.16.31.2 \ - --tidb-user root \ - --log-file tidb-lightning.log \ - > nohup.out & - ``` - -### 第 5 步：检查数据 - -导入完毕后，TiDB Lightning 会自动退出。若导入成功，日志的最后一行会显示 `tidb lightning exit`。 - -如果出错，请参见 [TiDB Lightning 错误排解](/dev/how-to/troubleshoot/tidb-lightning.md)。 - -## 总结 - -本教程对 TiDB Lightning 进行了简单的介绍，并快速部署了一套简单的 TiDB Lightning 集群，将全量备份数据导入到 TiDB 集群中。 - -关于 TiDB Lightning 的详细功能和使用，参见 [TiDB Lightning 简介](/dev/reference/tools/tidb-lightning/overview.md)。 diff --git a/dev/how-to/get-started/tispark.md b/dev/how-to/get-started/tispark.md deleted file mode 100644 index 5c067b9e69aa..000000000000 --- a/dev/how-to/get-started/tispark.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: TiSpark 快速入门指南 -category: how-to ---- - -# TiSpark 快速入门指南 - -为了让大家快速体验 [TiSpark](/dev/reference/tispark.md)，通过 TiDB Ansible 安装的 TiDB 集群中默认已集成 Spark、TiSpark jar 包及 TiSpark sample data。 - -## 部署信息 - -- Spark 默认部署在 TiDB 实例部署目录下 spark 目录中 -- TiSpark jar 包默认部署在 Spark 部署目录 jars 文件夹下：`spark/jars/tispark-${name_with_version}.jar` -- TiSpark sample data 及导入脚本默认部署在 TiDB Ansible 目录下：`tidb-ansible/resources/bin/tispark-sample-data` - -## 环境准备 - -### 在 TiDB 实例上安装 JDK - -在 [Oracle JDK 官方下载页面](http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html) 下载 JDK 1.8 当前最新版，本示例中下载的版本为 `jdk-8u141-linux-x64.tar.gz`。 - -解压并根据您的 JDK 部署目录设置环境变量，编辑 `~/.bashrc` 文件，比如： - -{{< copyable "shell-regular" >}} - -```bash -export JAVA_HOME=/home/pingcap/jdk1.8.0_144 && -export PATH=$JAVA_HOME/bin:$PATH -``` - -验证 JDK 有效性： - -```bash -java -version -``` - -``` -java version "1.8.0_144" -Java(TM) SE Runtime Environment (build 1.8.0_144-b01) -Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode) -``` - -### 导入样例数据 - -假设 TiDB 集群已启动，其中一台 TiDB 实例服务 IP 为 192.168.0.2，端口为 4000，用户名为 root, 密码为空。 - -{{< copyable "shell-regular" >}} - -```bash -cd tidb-ansible/resources/bin/tispark-sample-data -``` - -修改 `sample_data.sh` 中 TiDB 登录信息，比如： - -{{< copyable "shell-regular" >}} - -```bash -mysql --local-infile=1 -h 192.168.0.2 -P 4000 -u root < dss.ddl -``` - -执行脚本 - -{{< copyable "shell-regular" >}} - -```bash -./sample_data.sh -``` - -> **注意：** -> -> 执行脚本的机器上需要安装 MySQL client，CentOS 用户可通过 `yum -y install mysql`来安装。 - -登录 TiDB 并验证数据包含 `TPCH_001` 库及以下表： - -{{< copyable "shell-regular" >}} - -```bash -mysql -uroot -P4000 -h192.168.0.2 -``` - -{{< copyable "sql" >}} - -```sql -show databases; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| TPCH_001 | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -use TPCH_001; -``` - -``` -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -``` - -{{< copyable "sql" >}} - -```sql -show tables; -``` - -``` -+--------------------+ -| Tables_in_TPCH_001 | -+--------------------+ -| CUSTOMER | -| LINEITEM | -| NATION | -| ORDERS | -| PART | -| PARTSUPP | -| REGION | -| SUPPLIER | -+--------------------+ -8 rows in set (0.00 sec) -``` - -## 使用范例 - -进入 spark 部署目录启动 spark-shell: - -{{< copyable "shell-regular" >}} - -```bash -cd spark && -bin/spark-shell -``` - -然后像使用原生 Spark 一样查询 TiDB 表： - -```shell -scala> spark.sql("select count(*) from lineitem").show -``` - -结果为 - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -下面执行另一个复杂一点的 Spark SQL: - -```shell -scala> spark.sql( - """select - | l_returnflag, - | l_linestatus, - | sum(l_quantity) as sum_qty, - | sum(l_extendedprice) as sum_base_price, - | sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, - | sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, - | avg(l_quantity) as avg_qty, - | avg(l_extendedprice) as avg_price, - | avg(l_discount) as avg_disc, - | count(*) as count_order - |from - | lineitem - |where - | l_shipdate <= date '1998-12-01' - interval '90' day - |group by - | l_returnflag, - | l_linestatus - |order by - | l_returnflag, - | l_linestatus - """.stripMargin).show -``` - -结果为： - -``` -+------------+------------+---------+--------------+--------------+ -|l_returnflag|l_linestatus| sum_qty|sum_base_price|sum_disc_price| -+------------+------------+---------+--------------+--------------+ -| A| F|380456.00| 532348211.65|505822441.4861| -| N| F| 8971.00| 12384801.37| 11798257.2080| -| N| O|742802.00| 1041502841.45|989737518.6346| -| R| F|381449.00| 534594445.35|507996454.4067| -+------------+------------+---------+--------------+--------------+ -(续) ------------------+---------+------------+--------+-----------+ - sum_charge| avg_qty| avg_price|avg_disc|count_order| ------------------+---------+------------+--------+-----------+ - 526165934.000839|25.575155|35785.709307|0.050081| 14876| - 12282485.056933|25.778736|35588.509684|0.047759| 348| -1029418531.523350|25.454988|35691.129209|0.049931| 29181| - 528524219.358903|25.597168|35874.006533|0.049828| 14902| ------------------+---------+------------+--------+-----------+ -``` - -更多样例请参考 [`pingcap/tispark-test`](https://github.com/pingcap/tispark-test/tree/master/tpch/sparksql) diff --git a/dev/how-to/maintain/backup-and-restore/mydumper-lightning.md b/dev/how-to/maintain/backup-and-restore/mydumper-lightning.md deleted file mode 100644 index ac8a54e2bed9..000000000000 --- a/dev/how-to/maintain/backup-and-restore/mydumper-lightning.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: 使用 Mydumper/TiDB Lightning 进行备份与恢复 -category: how-to -aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/'] ---- - -# 使用 Mydumper/TiDB Lightning 进行备份与恢复 - -本文档将详细介绍如何使用 Mydumper/TiDB Lightning 对 TiDB 进行全量备份与恢复。增量备份与恢复可使用 [TiDB Binlog](/dev/reference/tidb-binlog/overview.md)。 - -这里假定 TiDB 服务信息如下： - -|Name|Address|Port|User|Password| -|----|-------|----|----|--------| -|TiDB|127.0.0.1|4000|root|*| - -在这个备份恢复过程中，会用到下面的工具： - -- [Mydumper](/dev/reference/tools/mydumper.md) 从 TiDB 导出数据 -- [TiDB Lightning](/dev/reference/tools/tidb-lightning/overview.md) 导入数据到 TiDB - -## 使用 Mydumper/TiDB Lightning 全量备份恢复数据 - -`mydumper` 是一个强大的数据备份工具，具体可以参考 [`maxbube/mydumper`](https://github.com/maxbube/mydumper)。 - -可使用 [Mydumper](/dev/reference/tools/mydumper.md) 从 TiDB 导出数据进行备份，然后用 [TiDB Lightning](/dev/reference/tools/tidb-lightning/overview.md) 将其导入到 TiDB 里面进行恢复。 - -> **注意：** -> -> PingCAP 研发团队对 `mydumper` 进行了针对 TiDB 的适配性改造，建议使用 PingCAP 官方提供的 [Mydumper](/dev/reference/tools/mydumper.md)。由于使用 `mysqldump` 进行数据备份和恢复都要耗费许多时间，这里也并不推荐。 - -### Mydumper/TiDB Lightning 全量备份恢复最佳实践 - -为了快速地备份恢复数据 (特别是数据量巨大的库)，可以参考以下建议： - -* 导出来的数据文件应当尽可能的小，可以通过设置参数 `-F` 来控制导出来的文件大小。如果后续使用 TiDB Lightning 对备份文件进行恢复，建议把 `mydumper` -F 参数的值设置为 `256`（单位 MB）；如果使用 `loader` 恢复，则建议设置为 `64`（单位 MB）。 - -## 从 TiDB 备份数据 - -我们使用 `mydumper` 从 TiDB 备份数据，如下: - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -P 4000 -u root -t 32 -F 256 -B test -T t1,t2 --skip-tz-utc -o ./var/test -``` - -上面，我们使用 `-B test` 表明是对 `test` 这个 database 操作，然后用 `-T t1,t2` 表明只导出 `t1`，`t2` 两张表。 - -`-t 32` 表明使用 32 个线程去导出数据。`-F 256` 是将实际的表切分成一定大小的 chunk，这里的 chunk 大小为 256MB。 - -添加 `--skip-tz-utc` 参数后，会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果 `mydumper` 出现以下报错： - -``` -** (mydumper:27528): CRITICAL **: 13:25:09.081: Could not read data from testSchema.testTable: GC life time is shorter than transaction duration, transaction starts at 2019-08-05 21:10:01.451 +0800 CST, GC safe point is 2019-08-05 21:14:53.801 +0800 CST -``` - -就再执行两步命令： - -1. 执行 `mydumper` 命令前，查询 TiDB 集群的 [GC](/dev/reference/garbage-collection/overview.md) 值并使用 MySQL 客户端将其调整为合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 执行 `mydumper` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -## 向 TiDB 恢复数据 - -使用 TiDB Lightning 将之前导出的数据导入到 TiDB，完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/dev/reference/tools/tidb-lightning/tidb-backend.md) diff --git a/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md b/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md deleted file mode 100644 index 53260976e8d2..000000000000 --- a/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: 定位消耗系统资源多的查询 -category: how-to ---- - -# 定位消耗系统资源多的查询 - -TiDB 会将执行时间超过 [tidb_expensive_query_time_threshold](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_expensive_query_time_threshold)（默认值为 60s），或使用内存超过 [mem-quota-query](/dev/reference/configuration/tidb-server/configuration-file.md#mem-quota-query)（默认值为 32 GB）的语句输出到 [tidb-server 日志文件](/dev/reference/configuration/tidb-server/configuration-file.md#logfile)（默认文件为：“tidb.log”）中，用于在语句执行结束前定位消耗系统资源多的查询语句（以下简称为 expensive query），帮助用户分析和解决语句执行的性能问题。 - -注意，expensive query 日志和[慢查询日志](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)的区别是，慢查询日志是在语句执行完后才打印，expensive query 日志可以将正在执行的语句的相关信息打印出来。当一条语句在执行过程中达到资源使用阈值时（执行时间/使用内存量），TiDB 会即时将这条语句的相关信息写入日志。 - -## Expensive query 日志示例 - -```sql -[2020/02/05 15:32:25.096 +08:00] [WARN] [expensivequery.go:167] [expensive_query] [cost_time=60.008338935s] [wait_time=0s] [request_count=1] [total_keys=70] [process_keys=65] [num_cop_tasks=1] [process_avg_time=0s] [process_p90_time=0s] [process_max_time=0s] [process_max_addr=10.0.1.9:20160] [wait_avg_time=0.002s] [wait_p90_time=0.002s] [wait_max_time=0.002s] [wait_max_addr=10.0.1.9:20160] [stats=t:pseudo] [conn_id=60026] [user=root] [database=test] [table_ids="[122]"] [txn_start_ts=414420273735139329] [mem_max="1035 Bytes (1.0107421875 KB)"] [sql="insert into t select sleep(1) from t"] -``` - -## 字段含义说明 - -基本字段： - -* `cost_time`：日志打印时语句已经花费的执行时间。 -* `stats`：语句涉及到的表或索引使用的统计信息版本。值为 pesudo 时表示无可用统计信息，需要对表或索引进行 analyze。 -* `table_ids`：语句涉及到的表的 ID。 -* `txn_start_ts`：事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `sql`：SQL 语句。 - -和内存使用相关的字段： - -* `mem_max`：日志打印时语句已经使用的内存空间。该项使用两种单位标识内存使用量，分别为 Bytes 以及易于阅读的自适应单位（比如 MB、GB 等）。 - -和 SQL 执行的用户相关的字段： - -* `user`：执行语句的用户名。 -* `conn_id`：用户的连接 ID，可以用类似 `con:60026` 的关键字在 TiDB 日志中查找该连接相关的其他日志。 -* `database`：执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `wait_time`：该语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `request_count`：该语句发送的 Coprocessor 请求的数量。 -* `total_keys`：Coprocessor 扫过的 key 的数量。 -* `processed_keys`：Coprocessor 处理的 key 的数量。与 total_keys 相比，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `num_cop_tasks`：该语句发送的 Coprocessor 请求的数量。 -* `process_avg_time`：Coprocessor 执行 task 的平均执行时间。 -* `process_p90_time`：Coprocessor 执行 task 的 P90 分位执行时间。 -* `process_max_time`：Coprocessor 执行 task 的最长执行时间。 -* `process_max_addr`：task 执行时间最长的 Coprocessor 所在地址。 -* `wait_avg_time`：Coprocessor 上 task 的等待时间。 -* `wait_p90_time`：Coprocessor 上 task 的 P90 分位等待时间。 -* `wait_max_time`：Coprocessor 上 task 的最长等待时间。 -* `wait_max_addr`：task 等待时间最长的 Coprocessor 所在地址。 diff --git a/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md b/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md deleted file mode 100644 index c1bd188e1bc1..000000000000 --- a/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: 慢查询日志 -category: how-to -aliases: ['/docs-cn/sql/slow-query/','/docs-cn/dev/how-to/maintain/identify-slow-queries/'] ---- - -# 慢查询日志 - -TiDB 会将执行时间超过 [slow-threshold](/dev/reference/configuration/tidb-server/configuration-file.md#slow-threshold)（默认值为 300 毫秒）的语句输出到 [slow-query-file](/dev/reference/configuration/tidb-server/configuration-file.md#slow-query-file)（默认值："tidb-slow.log"）日志文件中，用于帮助用户定位慢查询语句，分析和解决 SQL 执行的性能问题。 - -## 日志示例 - -```sql -# Time: 2019-08-14T09:26:59.487776265+08:00 -# Txn_start_ts: 410450924122144769 -# User: root@127.0.0.1 -# Conn_ID: 3086 -# Query_time: 1.527627037 -# Parse_time: 0.000054933 -# Compile_time: 0.000129729 -# Process_time: 0.07 Request_count: 1 Total_keys: 131073 Process_keys: 131072 Prewrite_time: 0.335415029 Commit_time: 0.032175429 Get_commit_ts_time: 0.000177098 Local_latch_wait_time: 0.106869448 Write_keys: 131072 Write_size: 3538944 Prewrite_region: 1 -# DB: test -# Is_internal: false -# Digest: 50a2e32d2abbd6c1764b1b7f2058d428ef2712b029282b776beb9506a365c0f1 -# Stats: t:pseudo -# Num_cop_tasks: 1 -# Cop_proc_avg: 0.07 Cop_proc_p90: 0.07 Cop_proc_max: 0.07 Cop_proc_addr: 172.16.5.87:20171 -# Cop_wait_avg: 0 Cop_wait_p90: 0 Cop_wait_max: 0 Cop_wait_addr: 172.16.5.87:20171 -# Mem_max: 525211 -# Succ: true -# Plan: tidb_decode_plan('ZJAwCTMyXzcJMAkyMAlkYXRhOlRhYmxlU2Nhbl82CjEJMTBfNgkxAR0AdAEY1Dp0LCByYW5nZTpbLWluZiwraW5mXSwga2VlcCBvcmRlcjpmYWxzZSwgc3RhdHM6cHNldWRvCg==') -insert into t select * from t; -``` - -## 字段含义说明 - -> **注意：** -> -> 慢查询日志中所有时间相关字段的单位都是 **“秒”** - -Slow Query 基础信息： - -* `Time`：表示日志打印时间。 -* `Query_time`：表示执行这个语句花费的时间。 -* `Parse_time`：表示这个语句在语法解析阶段花费的时间。 -* `Compile_time`：表示这个语句在查询优化阶段花费的时间。 -* `Query`：表示 SQL 语句。慢日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 -* `Digest`：表示 SQL 语句的指纹。 -* `Txn_start_ts`：表示事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `Is_internal`：表示是否为 TiDB 内部的 SQL 语句。`true` 表示 TiDB 系统内部执行的 SQL 语句，`false` 表示用户执行的 SQL 语句。 -* `Index_ids`：表示语句涉及到的索引的 ID。 -* `Succ`：表示语句是否执行成功。 -* `Backoff_time`：表示语句遇到需要重试的错误时在重试前等待的时间，常见的需要重试的错误有以下几种：遇到了 lock、Region 分裂、`tikv server is busy`。 -* `Plan`：表示语句的执行计划，用 `select tidb_decode_plan('xxx...')` SQL 语句可以解析出具体的执行计划。 - -和事务执行相关的字段： - -* `Prewrite_time`：表示事务两阶段提交中第一阶段（prewrite 阶段）的耗时。 -* `Commit_time`：表示事务两阶段提交中第二阶段（commit 阶段）的耗时。 -* `Get_commit_ts_time`：表示事务两阶段提交中第二阶段（commit 阶段）获取 commit 时间戳的耗时。 -* `Local_latch_wait_time`：表示事务两阶段提交中第二阶段（commit 阶段）发起前在 TiDB 侧等锁的耗时。 -* `Write_keys`：表示该事务向 TiKV 的 Write CF 写入 Key 的数量。 -* `Write_size`：表示事务提交时写 key 或 value 的总大小。 -* `Prewrite_region`：表示事务两阶段提交中第一阶段（prewrite 阶段）涉及的 TiKV Region 数量。每个 Region 会触发一次远程过程调用。 - -和内存使用相关的字段： - -* `Memory_max`：表示执行期间 TiDB 使用的最大内存空间，单位为 byte。 - -和 SQL 执行的用户相关的字段： - -* `User`：表示执行语句的用户名。 -* `Conn_ID`：表示用户的链接 ID，可以用类似 `con:3` 的关键字在 TiDB 日志中查找该链接相关的其他日志。 -* `DB`：表示执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `Request_count`：表示这个语句发送的 Coprocessor 请求的数量。 -* `Total_keys`：表示 Coprocessor 扫过的 key 的数量。 -* `Process_time`：执行 SQL 在 TiKV 的处理时间之和，因为数据会并行的发到 TiKV 执行，这个值可能会超过 `Query_time`。 -* `Wait_time`：表示这个语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `Process_keys`：表示 Coprocessor 处理的 key 的数量。相比 total_keys，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `Cop_proc_avg`：cop-task 的平均执行时间。 -* `Cop_proc_p90`：cop-task 的 P90 分位执行时间。 -* `Cop_proc_max`：cop-task 的最大执行时间。 -* `Cop_proc_addr`：执行时间最长的 cop-task 所在地址。 -* `Cop_wait_avg`：cop-task 的平均等待时间。 -* `Cop_wait_p90`：cop-task 的 P90 分位等待时间。 -* `Cop_wait_max`：cop-task 的最大等待时间。 -* `Cop_wait_addr`：等待时间最长的 cop-task 所在地址。 - -## 慢日志内存映射表 - -用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢日志中字段名一一对应，表结构可查看 [Information Schema](/dev/reference/system-databases/information-schema.md#information-schema) 中关于 `SLOW_QUERY` 表的介绍。 - -> **注意：** -> -> 每次查询 `SLOW_QUERY` 表时，TiDB 都会去读取和解析一次当前的慢查询日志。 - -## 查询 `SLOW_QUERY` 示例 - -### 搜索 Top N 的慢查询 - -查询 Top 2 的用户慢查询。`is_internal=false` 表示排除 TiDB 内部的慢查询，只看用户的慢查询： - -{{< copyable "sql" >}} - -```sql -select query_time, query -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+--------------+------------------------------------------------------------------+ -| query_time | query | -+--------------+------------------------------------------------------------------+ -| 12.77583857 | select * from t_slim, t_wide where t_slim.c0=t_wide.c0; | -| 0.734982725 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c0; | -+--------------+------------------------------------------------------------------+ -``` - -### 搜索某个用户的 Top N 慢查询 - -下面例子中搜索 test 用户执行的慢查询 SQL，且按执行消耗时间逆序排序显式前 2 条： - -{{< copyable "sql" >}} - -```sql -select query_time, query, user -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL - and user = "test" -- 查找的用户名 -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+-------------+------------------------------------------------------------------+----------------+ -| Query_time | query | user | -+-------------+------------------------------------------------------------------+----------------+ -| 0.676408014 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c1; | test | -+-------------+------------------------------------------------------------------+----------------+ -``` - -### 根据 SQL 指纹搜索同类慢查询 - -在得到 Top N 的慢查询 SQL 后，可通过 SQL 指纹继续搜索同类慢查询 SQL。 - -先获取 Top N 的慢查询和对应的 SQL 指纹： - -{{< copyable "sql" >}} - -```sql -select query_time, query, digest -from information_schema.slow_query -where is_internal = false -order by query_time desc -limit 1; -``` - -输出样例： - -``` -+-------------+-----------------------------+------------------------------------------------------------------+ -| query_time | query | digest | -+-------------+-----------------------------+------------------------------------------------------------------+ -| 0.302558006 | select * from t1 where a=1; | 4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa | -+-------------+-----------------------------+------------------------------------------------------------------+ -``` - -再根据 SQL 指纹搜索同类慢查询： - -{{< copyable "sql" >}} - -```sql -select query, query_time -from information_schema.slow_query -where digest = "4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa"; -``` - -输出样例： - -``` -+-----------------------------+-------------+ -| query | query_time | -+-----------------------------+-------------+ -| select * from t1 where a=1; | 0.302558006 | -| select * from t1 where a=2; | 0.401313532 | -+-----------------------------+-------------+ -``` - -### 搜索统计信息为 pseudo 的慢查询 SQL 语句 - -{{< copyable "sql" >}} - -```sql -select query, query_time, stats -from information_schema.slow_query -where is_internal = false - and stats like '%pseudo%'; -``` - -输出样例： - -``` -+-----------------------------+-------------+---------------------------------+ -| query | query_time | stats | -+-----------------------------+-------------+---------------------------------+ -| select * from t1 where a=1; | 0.302558006 | t1:pseudo | -| select * from t1 where a=2; | 0.401313532 | t1:pseudo | -| select * from t1 where a>2; | 0.602011247 | t1:pseudo | -| select * from t1 where a>3; | 0.50077719 | t1:pseudo | -| select * from t1 join t2; | 0.931260518 | t1:407872303825682445,t2:pseudo | -+-----------------------------+-------------+---------------------------------+ -``` - -## 解析其他的 TiDB 慢日志文件 - -TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHEMA.SLOW_QUERY` 时要读取和解析的文件，可通过修改改 session 变量的值来查询其他慢查询日志文件的内容： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_query_file = "/path-to-log/tidb-slow.log" -``` - -## 用 `pt-query-digest` 工具分析 TiDB 慢日志 - -可以用 `pt-query-digest` 工具分析 TiDB 慢日志。 - -> **注意：** -> -> 建议使用 pt-query-digest 3.0.13 及以上版本。 - -示例如下： - -{{< copyable "shell" >}} - -```shell -pt-query-digest --report tidb-slow.log -``` - -输出样例： - -``` -# 320ms user time, 20ms system time, 27.00M rss, 221.32M vsz -# Current date: Mon Mar 18 13:18:51 2019 -# Hostname: localhost.localdomain -# Files: tidb-slow.log -# Overall: 1.02k total, 21 unique, 0 QPS, 0x concurrency _________________ -# Time range: 2019-03-18-12:22:16 to 2019-03-18-13:08:52 -# Attribute total min max avg 95% stddev median -# ============ ======= ======= ======= ======= ======= ======= ======= -# Exec time 218s 10ms 13s 213ms 30ms 1s 19ms -# Query size 175.37k 9 2.01k 175.89 158.58 122.36 158.58 -# Commit time 46ms 2ms 7ms 3ms 7ms 1ms 3ms -# Conn ID 71 1 16 8.88 15.25 4.06 9.83 -# Process keys 581.87k 2 103.15k 596.43 400.73 3.91k 400.73 -# Process time 31s 1ms 10s 32ms 19ms 334ms 16ms -# Request coun 1.97k 1 10 2.02 1.96 0.33 1.96 -# Total keys 636.43k 2 103.16k 652.35 793.42 3.97k 400.73 -# Txn start ts 374.38E 0 16.00E 375.48P 1.25P 89.05T 1.25P -# Wait time 943ms 1ms 19ms 1ms 2ms 1ms 972us -. -. -. -``` - -### 定位问题语句的方法 - -并不是所有 SLOW_QUERY 的语句都是有问题的。会造成集群整体压力增大的，是那些 process_time 很大的语句。wait_time 很大，但 process_time 很小的语句通常不是问题语句，是因为被问题语句阻塞，在执行队列等待造成的响应时间过长。 - -## `admin show slow` 命令 - -除了获取 TiDB 日志，还有一种定位慢查询的方式是通过 `admin show slow` SQL 命令： - -{{< copyable "sql" >}} - -```sql -admin show slow recent N; -``` - -{{< copyable "sql" >}} - -```sql -admin show slow top [internal | all] N; -``` - -`recent N` 会显示最近的 N 条慢查询记录，例如： - -{{< copyable "sql" >}} - -```sql -admin show slow recent 10; -``` - -`top N` 则显示最近一段时间（大约几天）内，最慢的查询记录。如果指定 `internal` 选项，则返回查询系统内部 SQL 的慢查询记录；如果指定 `all` 选项，返回系统内部和用户 SQL 汇总以后的慢查询记录；默认只返回用户 SQL 中的慢查询记录。 - -{{< copyable "sql" >}} - -```sql -admin show slow top 3; -admin show slow top internal 3; -admin show slow top all 5; -``` - -由于内存限制，保留的慢查询记录的条数是有限的。当命令查询的 `N` 大于记录条数时，返回的结果记录条数会小于 `N`。 - -输出内容详细说明，如下： - -| 列名 | 描述 | -|:------|:---- | -| start | SQL 语句执行开始时间 | -| duration | SQL 语句执行持续时间 | -| details | 执行语句的详细信息 | -| succ | SQL 语句执行是否成功，1: 成功，0: 失败 | -| conn_id | session 连接 ID | -| transcation_ts | 事务提交的 commit ts | -| user | 执行该语句的用户名 | -| db | 执行该 SQL 涉及到 database | -| table_ids | 执行该 SQL 涉及到表的 ID | -| index_ids | 执行该 SQL 涉及到索引 ID | -| internal | 表示为 TiDB 内部的 SQL 语句 | -| digest | 表示 SQL 语句的指纹 | -| sql | 执行的 SQL 语句 | diff --git a/dev/how-to/migrate/from-mysql-aurora.md b/dev/how-to/migrate/from-mysql-aurora.md deleted file mode 100644 index cb321c508b87..000000000000 --- a/dev/how-to/migrate/from-mysql-aurora.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 -summary: 使用 DM 从 MySQL/Amazon Aurora MySQL 迁移数据。 -category: how-to -aliases: ['/docs-cn/dev/how-to/migrate/from-aurora/'] ---- - -# 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 - -本文以 [Amazon Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 为例介绍如何使用 DM 从 MySQL 协议数据库迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/dev/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务（`task.yaml` 是之前编辑的配置文件） - - {{< copyable "shell-regular" >}} - - ```bash - start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "shell-regular" >}} - -```bash -query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ``` -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 `task.yaml` 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/dev/how-to/scale/horizontally.md b/dev/how-to/scale/horizontally.md deleted file mode 100644 index cb4e9d38865a..000000000000 --- a/dev/how-to/scale/horizontally.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: TiDB 集群扩容缩容方案 -category: how-to ---- - -# TiDB 集群扩容缩容方案 - -TiDB 集群可以在不影响线上服务的情况下动态进行扩容和缩容。 - -> **注意：** -> -> 如果使用 Ansible 部署 TiDB 集群，请参考[使用 Ansible 扩容缩容](/dev/how-to/scale/with-ansible.md)。 - -下面分别介绍如何增加或者删除 PD，TiKV 以及 TiDB 的节点。 - -下面用到的 pd-ctl 文档可以参考 [pd-control](/dev/reference/tools/pd-control.md)。 - -## PD - -假设现在我们有三个 PD 服务，详细信息如下： - -|Name|ClientUrls|PeerUrls| -|----|----------|--------| -|pd1|`http://host1:2379`|`http://host1:2380`| -|pd2|`http://host2:2379`|`http://host2:2380`| -|pd3|`http://host3:2379`|`http://host3:2380`| - -我们可以通过 pd-ctl 来查看当前所有 PD 节点的信息： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 -i ->> member -``` - -### 动态添加节点 - -我们可以使用 `join` 参数，将一个新的 PD 服务加入到现有的 PD 集群里面。 -如果我们需要添加 `pd4`，只需要在 `--join` 参数里面填入当前 PD 集群任意一个 PD 服务的 client url，比如： - -{{< copyable "shell-regular" >}} - -```bash -./bin/pd-server --name=pd4 \ - --client-urls="http://host4:2379" \ - --peer-urls="http://host4:2380" \ - --join="http://host1:2379" -``` - -### 动态删除节点 - -如果我们需要删除 `pd4`，可以通过 pd-ctl 来完成： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> member delete name pd4 -``` - -### 动态迁移节点 - -如果想把现有的 PD 节点迁移到新的机器上，我们可以先在新的机器上添加节点，然后把旧的机器上的节点删除掉。迁移过程中应该一个节点一个节点逐个迁移，每完成一个步骤可以先查看一下当前的所有节点信息来进行确认。 - -## TiKV - -我们可以通过 pd-ctl 来查看当前所有 TiKV 节点的信息： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store -``` - -### 动态添加节点 - -动态添加一个新的 TiKV 服务非常容易，只需要在新的机器上启动一个 TiKV 服务，不需要其他特殊操作。 -新启动的 TiKV 服务会自动注册到现有集群的 PD 中，PD 会自动做负载均衡，逐步地把一部分数据迁移到新的TiKV 服务中，从而降低现有 TiKV 服务的压力。 - -### 动态删除节点 - -安全地删除（下线）一个 TiKV 服务需要先告诉 PD，这样 PD 可以先把这个 TiKV 服务上面的数据迁移到其他 TiKV 服务上，保证数据有足够的副本数。 - -假设我们需要删除 store id 为 1 的 TiKV 服务，可以通过 pd-ctl 来完成： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store delete 1 -``` - -然后可以查看这个 TiKV 服务的状态： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store 1 -``` - -``` -{ - "store": { - "id": 1, - "address": "127.0.0.1:21060", - "state": 1, - "state_name": "Offline" - }, - "status": { - ... - } -} -``` - -我们可以通过这个 store 的 state_name 来确定这个 store 的状态： - -- Up：这个 store 正常服务 -- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 -- Down：超过一小时（可通过 `max-down-time` 配置）没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 -- Offline：这个 store 正在将其中的 Region 转移到其他节点，此时这个 store 仍在服务中 -- Tombstone：这个 store 已经完成下线，此时 store 上已经没有数据，可以关闭实例 - -### 动态迁移节点 - -迁移 TiKV 服务也是通过先在新的机器上添加节点，然后把旧的机器上的节点下线来完成。迁移过程中可以先把新集群的机器全部添加到已有的集群中，然后再把旧的节点一个一个地下线。可以通过查看正在下线的节点的状态信息来确定这个节点是否已经完成下线，确认完成以后再下线下一个节点。 - -## TiDB - -TiDB 是一个无状态的服务，这也就意味着我们能直接添加和删除 TiDB。需要注意的是，如果我们在 TiDB 的服务的前面搭建了一个 proxy（譬如 HAProxy），则需要更新 proxy 的配置并重新载入。 diff --git a/dev/how-to/scale/with-ansible.md b/dev/how-to/scale/with-ansible.md deleted file mode 100644 index 5eb3eda0644f..000000000000 --- a/dev/how-to/scale/with-ansible.md +++ /dev/null @@ -1,527 +0,0 @@ ---- -title: 使用 TiDB Ansible 扩容缩容 TiDB 集群 -category: how-to ---- - -# 使用 TiDB Ansible 扩容缩容 TiDB 集群 - -TiDB 集群可以在不影响线上服务的情况下进行扩容和缩容。 - -> **注意：** -> -> 以下缩容示例中，被移除的节点没有混合部署其他服务；如果混合部署了其他服务，不能按如下操作。 - -假设拓扑结构如下所示： - -| Name | Host IP | Services | -| ---- | ------- | -------- | -| node1 | 172.16.10.1 | PD1 | -| node2 | 172.16.10.2 | PD2 | -| node3 | 172.16.10.3 | PD3, Monitor | -| node4 | 172.16.10.4 | TiDB1 | -| node5 | 172.16.10.5 | TiDB2 | -| node6 | 172.16.10.6 | TiKV1 | -| node7 | 172.16.10.7 | TiKV2 | -| node8 | 172.16.10.8 | TiKV3 | -| node9 | 172.16.10.9 | TiKV4 | - -## 扩容 TiDB/TiKV 节点 - -例如，如果要添加两个 TiDB 节点（node101、node102），IP 地址为 172.16.10.101、172.16.10.102，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.101 - 172.16.10.102 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - 172.16.10.101 - 172.16.10.102 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | **node101** | **172.16.10.101**|**TiDB3** | - | **node102** | **172.16.10.102**|**TiDB4** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml -l 172.16.10.101,172.16.10.102 - ``` - - > **注意：** - > - > 如果 `inventory.ini` 中为节点配置了别名，如 `node101 ansible_host=172.16.10.101`，执行 ansible-playbook 时 -l 请指定别名，以下步骤类似。例如：`ansible-playbook bootstrap.yml -l node101,node102` - -3. 部署新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml -l 172.16.10.101,172.16.10.102 - ``` - -4. 启动新节点服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml -l 172.16.10.101,172.16.10.102 - ``` - -5. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - - 可使用同样的步骤添加 TiKV 节点。但如果要添加 PD 节点，则需手动更新一些配置文件。 - -## 扩容 PD 节点 - -例如，如果要添加一个 PD 节点（node103），IP 地址为 172.16.10.103，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息置于 `[pd_servers]` 主机组最后一行： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | **node103** | **172.16.10.103** | **PD4** | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml -l 172.16.10.103 - ``` - -3. 部署新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml -l 172.16.10.103 - ``` - -4. 登录新增的 PD 节点，编辑启动脚本：`{deploy_dir}/scripts/run_pd.sh` - - 1. 移除 `--initial-cluster="xxxx" \` 配置，注意这里不能在行开头加注释符 #。 - - 2. 添加 `--join="http://172.16.10.1:2379" \`，IP 地址 （172.16.10.1） 可以是集群内现有 PD IP 地址中的任意一个。 - - 3. 在新增 PD 节点中手动启动 PD 服务： - - {{< copyable "shell-regular" >}} - - ```bash - {deploy_dir}/scripts/start_pd.sh - ``` - - > **注意：** - > - > 启动前，需要通过 [PD Control](/dev/reference/tools/pd-control.md) 工具确认当前 PD 节点的 `health` 状态均为 "true"，否则 PD 服务会启动失败，同时日志中报错 `["join meet error"] [error="etcdserver: unhealthy cluster"]`。 - - 4. 使用 `pd-ctl` 检查新节点是否添加成功： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -5. 滚动升级整个集群： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -6. 启动监控服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml -l 172.16.10.103 - ``` - -7. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -8. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - -## 缩容 TiDB 节点 - -例如，如果要移除一个 TiDB 节点（node5），IP 地址为 172.16.10.5，可以进行如下操作： - -1. 停止 node5 节点上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.5 - ``` - -2. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | **node5** | **172.16.10.5** | **TiDB2 已删除** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -3. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -4. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 TiKV 节点 - -例如，如果要移除一个 TiKV 节点（node9），IP 地址为 172.16.10.9，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node9 节点的 store id： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store - ``` - - 2. 从集群中移除 node9，假如 store id 为 10： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store delete 10 - ``` - -2. 使用 Grafana 或者 `pd-ctl` 检查节点是否下线成功（下线需要一定时间，下线节点的状态变为 Tombstone 就说明下线成功了）： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store 10 - ``` - -3. 下线成功后，停止 node9 上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.9 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | **node9** | **172.16.10.9** | **TiKV4 已删除** | - -5. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 PD 节点 - -例如，如果要移除一个 PD 节点（node2），IP 地址为 172.16.10.2，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node2 节点的 name： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - - 2. 从集群中移除 node2，假如 name 为 pd2： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member delete name pd2 - ``` - -2. 使用 `pd-ctl` 检查节点是否下线成功（PD 下线会很快，结果中没有 node2 节点信息即为下线成功）： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -3. 下线成功后，停止 node2 上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.2 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | **node2** | **172.16.10.2** | **PD2 已删除** | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -5. 滚动升级整个集群： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -6. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -7. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 diff --git a/dev/how-to/secure/enable-tls-between-components.md b/dev/how-to/secure/enable-tls-between-components.md deleted file mode 100644 index 0aca650377c2..000000000000 --- a/dev/how-to/secure/enable-tls-between-components.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 为 TiDB 组件间开启 TLS 和数据加密存储 -category: how-to ---- - -# 为 TiDB 组件间开启 TLS 和数据加密存储 - -本文档介绍 TiDB 集群如何开启 TLS 验证和数据加密存储。 - -## 开启 TLS 验证 - -本部分介绍 TiDB 集群如何开启 TLS 验证，TLS 验证支持： - -- TiDB 组件之间的双向验证，包括 TiDB、TiKV、PD 相互之间，TiKV Control 与 TiKV、PD Control 与 PD 的双向认证，以及 TiKV peer 之间、PD peer 之间。一旦开启，所有组件之间均使用验证，不支持只开启某一部分的验证。 -- MySQL Client 与 TiDB 之间的客户端对服务器身份的单向验证以及双向验证。 - -MySQL Client 与 TiDB 之间使用一套证书，TiDB 集群组件之间使用另外一套证书。 - -### TiDB 集群组件间开启 TLS（双向认证） - -1. 准备证书。 - - 推荐为 TiDB、TiKV、PD 分别准备一个 server 证书，并保证可以相互验证，而它们的各种客户端共用 client 证书。 - - 有多种工具可以生成自签名证书，如 `openssl`，`easy-rsa`，`cfssl`。 - - 这里提供一个使用 `cfssl` 生成证书的示例：[生成自签名证书](/dev/how-to/secure/generate-self-signed-certificates.md)。 - -2. 配置证书。 - - - TiDB - - 在 `config` 文件或命令行参数中设置： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs for connection with cluster components. - cluster-ssl-ca = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format for connection with cluster components. - cluster-ssl-cert = "/path/to/tidb-server.pem" - # Path of file that contains X509 key in PEM format for connection with cluster components. - cluster-ssl-key = "/path/to/tidb-server-key.pem" - ``` - - - TiKV - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # set the path for certificates. Empty string means disabling secure connectoins. - ca-path = "/path/to/ca.pem" - cert-path = "/path/to/tikv-server.pem" - key-path = "/path/to/tikv-server-key.pem" - ``` - - - PD - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs. if set, following four settings shouldn't be empty - cacert-path = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format. - cert-path = "/path/to/pd-server.pem" - # Path of file that contains X509 key in PEM format. - key-path = "/path/to/pd-server-key.pem" - ``` - - 此时 TiDB 集群各个组件间已开启双向验证。 - - > **注意：** - > - > 若 TiDB 集群各个组件间已开启 TLS，在使用 tikv-ctl 或 pd-ctl 工具连接集群时，需要指定 client 证书，示例： - - {{< copyable "shell-regular" >}} - - ```bash - ./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/clinet-key.pem" - ``` - -### MySQL 与 TiDB 间开启 TLS - -请参考 [使用加密连接](/dev/how-to/secure/enable-tls-clients.md)。 - -## 开启数据加密存储 - -在 TiDB 集群中，用户的数据都存储在 TiKV 中，配置了 TiKV 数据加密存储功能，就代表 TiDB 集群已经加密存储了用户的数据。本部分主要介绍如何配置 TiKV 的加密存储功能。 - -### 操作流程 - -1. 生成 token 文件。 - - token 文件存储的是密钥，用于对用户数据进行加密，以及对已加密的数据进行解密。 - - {{< copyable "shell-regular" >}} - - ```bash - ./tikv-ctl random-hex --len 256 > cipher-file-256 - ``` - - > **注意：** - > - > TiKV 只接受 hex 格式的 token 文件，文件的长度必须是 2^n，并且小于等于 1024。 - -2. 配置 TiKV。 - - ```toml - [security] - # Cipher file 的存储路径 - cipher-file = "/path/to/cipher-file-256" - ``` - -> **注意：** -> -> 若使用 [Lightning](/dev/reference/tools/tidb-lightning/overview.md) 向集群导入数据，如果目标集群开启了加密功能，Lightning 生成的 sst 文件也必须是加密的格式。 - -### 使用限制 - -目前 TiKV 数据加密存储存在以下限制： - -- 对之前没有开启加密存储的集群，不支持开启该功能。 -- 已经开启加密功能的集群，不允许关闭加密存储功能。 -- 同一集群内部，不允许部分 TiKV 实例开启该功能，部分 TiKV 实例不开启该功能。对于加密存储功能，所有 TiKV 实例要么都开启该功能，要么都不开启该功能。这是由于 TiKV 实例之间会有数据迁移，如果开启了加密存储功能，迁移过程中数据也是加密的。 diff --git a/dev/how-to/secure/enable-tls-clients.md b/dev/how-to/secure/enable-tls-clients.md deleted file mode 100644 index 9f4486082d9b..000000000000 --- a/dev/how-to/secure/enable-tls-clients.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: 使用加密连接 -category: how-to ---- - -# 使用加密连接 - -TiDB 服务端默认采用非加密连接，因而具备监视信道流量能力的第三方可以知悉 TiDB 服务端与客户端之间发送和接受的数据，包括但不限于查询语句内容、查询结果等。若信道是不可信的，例如客户端是通过公网连接到 TiDB 服务端的，则非加密连接容易造成信息泄露，建议使用加密连接确保安全性。 - -TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接，协议与 MySQL 加密连接一致，现有 MySQL 客户端如 MySQL 运维工具和 MySQL 驱动等能直接支持。TLS 的前身是 SSL，因而 TLS 有时也被称为 SSL，但由于 SSL 协议有已知安全漏洞，TiDB 实际上并未支持。TiDB 支持的 TLS/SSL 协议版本为 TLS 1.0、TLS 1.1、TLS 1.2。 - -使用加密连接后，连接将具有以下安全性质： - -- 保密性：流量明文无法被窃听； -- 完整性：流量明文无法被篡改； -- 身份验证（可选）：客户端和服务端能验证双方身份，避免中间人攻击。 - -TiDB 的加密连接支持默认是关闭的，必须在 TiDB 服务端通过配置开启加密连接的支持后，才能在客户端中使用加密连接。另外，与 MySQL 一致，TiDB 加密连接是以单个连接为单位的，并且是可选的，因而对于开启了加密连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。大部分 MySQL 客户端默认不采用加密连接，因此一般还要显式地要求客户端使用加密连接。 - -简单来说，要使用加密连接必须同时满足以下两个条件： - -1. TiDB 服务端配置开启加密连接的支持 -2. 客户端指定使用加密连接 - -## 配置 TiDB 启用加密连接支持 - -在启动 TiDB 时，至少需要在配置文件中同时指定 `ssl-cert` 和 `ssl-key` 参数，才能使 TiDB 服务端接受加密连接。还可以指定 `ssl-ca` 参数进行客户端身份验证（请参见[配置启用身份验证](#配置启用身份验证)章节）。 - -- [`ssl-cert`](/dev/reference/configuration/tidb-server/configuration-file.md#ssl-cert)：指定 SSL 证书文件路径 -- [`ssl-key`](/dev/reference/configuration/tidb-server/configuration-file.md#ssl-key)：指定证书文件对应的私钥 -- [`ssl-ca`](/dev/reference/configuration/tidb-server/configuration-file.md#ssl-ca)：可选，指定受信任的 CA 证书文件路径 - -参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端加密连接到 TiDB 服务端。 - -上述证书及密钥可以使用 OpenSSL 签发和生成，也可以使用 MySQL 自带的工具 `mysql_ssl_rsa_setup` 快捷生成： - -{{< copyable "shell-regular" >}} - -```bash -mysql_ssl_rsa_setup --datadir=./certs -``` - -以上命令将在 `certs` 目录下生成以下文件： - -``` -certs -├── ca-key.pem -├── ca.pem -├── client-cert.pem -├── client-key.pem -├── private_key.pem -├── public_key.pem -├── server-cert.pem -└── server-key.pem -``` - -对应的 TiDB 配置文件参数为： - -```toml -[security] -ssl-cert = "certs/server-cert.pem" -ssl-key = "certs/server-key.pem" -``` - -若证书参数无误，则 TiDB 在启动时将会输出 `Secure connection is enabled`，否则 TiDB 会输出 `Secure connection is NOT ENABLED`。 - -## 配置 MySQL 客户端使用加密连接 - -MySQL 5.7 及以上版本自带的客户端默认尝试使用安全连接，若服务端不支持安全连接则自动退回到使用非安全连接；MySQL 5.7 以下版本自带的客户端默认采用非安全连接。 - -可以通过命令行参数修改客户端的连接行为，包括： - -- 强制使用安全连接，若服务端不支持安全连接则连接失败 (`--ssl-mode=REQUIRED`) -- 尝试使用安全连接，若服务端不支持安全连接则退回使用不安全连接 -- 使用不安全连接 (`--ssl-mode=DISABLED`) - -详细信息请参阅 MySQL 文档中关于[客户端配置安全连接](https://dev.mysql.com/doc/refman/5.7/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration)的部分。 - -## 配置启用身份验证 - -若在 TiDB 服务端或 MySQL 客户端中未指定 `ssl-ca` 参数，则默认不会进行客户端或服务端身份验证，无法抵御中间人攻击，例如客户端可能会“安全地”连接到了一个伪装的服务端。可以在服务端和客户端中配置 `ssl-ca` 参数进行身份验证。一般情况下只需验证服务端身份，但也可以验证客户端身份进一步增强安全性。 - -- 若要使 MySQL 客户端验证 TiDB 服务端身份，TiDB 服务端需至少配置 `ssl-cert` 和 `ssl-key` 参数，客户端需至少指定 `--ssl-ca` 参数，且 `--ssl-mode` 至少为 `VERIFY_CA`。必须确保 TiDB 服务端配置的证书（`ssl-cert`）是由客户端 `--ssl-ca` 参数所指定的 CA 所签发的，否则身份验证失败。 -- 若要使 TiDB 服务端验证 MySQL 客户端身份，TiDB 服务端需配置 `ssl-cert`、`ssl-key`、`ssl-ca` 参数，客户端需至少指定 `--ssl-cert`、`--ssl-key` 参数。必须确保服务端配置的证书和客户端配置的证书都是由服务端配置指定的 `ssl-ca` 签发的。 -- 若要进行双向身份验证，请同时满足上述要求。 - -> **注意：** -> -> 目前 TiDB 尚不支持强制验证客户端身份，即服务端对客户端的身份验证是可选的。若客户端在 TLS 握手时未出示自己的身份证书，也能正常建立 TLS 连接。 - -## 检查当前连接是否是加密连接 - -可以通过 `SHOW STATUS LIKE "%Ssl%";` 了解当前连接的详细情况，包括是否使用了安全连接、安全连接采用的加密协议、TLS 版本号等。 - -以下是一个安全连接中执行该语句的结果。由于客户端支持的 TLS 版本号和加密协议会有所不同，执行结果相应地也会有所变化。 - -{{< copyable "sql" >}} - -```sql -SHOW STATUS LIKE "%Ssl%"; -``` - -``` -...... -| Ssl_verify_mode | 5 | -| Ssl_version | TLSv1.2 | -| Ssl_cipher | ECDHE-RSA-AES128-GCM-SHA256 | -...... -``` - -除此以外，对于 MySQL 自带客户端，还可以使用 `STATUS` 或 `\s` 语句查看连接情况： - -{{< copyable "sql" >}} - -```sql -\s -``` - -``` -... -SSL: Cipher in use is ECDHE-RSA-AES128-GCM-SHA256 -... -``` - -## 支持的 TLS 版本及密钥交换协议和加密算法 - -TiDB 支持的 TLS 版本及密钥交换协议和加密算法由 Golang 官方库决定。 - -### 支持的 TLS 版本 - -- TLS 1.0 -- TLS 1.1 -- TLS 1.2 - -### 支持的密钥交换协议及加密算法 - -- TLS\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 -- TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 diff --git a/dev/how-to/troubleshoot/cluster-setup.md b/dev/how-to/troubleshoot/cluster-setup.md deleted file mode 100644 index a480f8c62ca5..000000000000 --- a/dev/how-to/troubleshoot/cluster-setup.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: TiDB 集群故障诊断 -category: how-to ---- - -# TiDB 集群故障诊断 - -当试用 TiDB 遇到问题时，请先参考本篇文档。如果问题未解决，请按文档要求收集必要的信息通过 Github [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - -## 如何给 TiDB 开发者报告错误 - -当使用 TiDB 遇到问题并且通过后面所列信息无法解决时，请收集以下信息并[创建新 Issue](https://github.com/pingcap/tidb/issues/new/choose): - -+ 具体的出错信息以及正在执行的操作 -+ 当前所有组件的状态 -+ 出问题组件 log 中的 error/fatal/panic 信息 -+ 机器配置以及部署拓扑 -+ dmesg 中 TiDB 组件相关的问题 - -## 数据库连接不上 - -首先请确认集群的各项服务是否已经启动，包括 tidb-server、pd-server、tikv-server。请用 ps 命令查看所有进程是否在。如果某个组件的进程已经不在了，请参考对应的章节排查错误。 - -如果所有的进程都在，请查看 tidb-server 的日志，看是否有报错？常见的错误包括： - -+ InformationSchema is out of date - - 无法连接 tikv-server，请检查 pd-server 以及 tikv-server 的状态和日志。 - -+ panic - - 程序有错误，请将具体的 panic log [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - - 如果是清空数据并重新部署服务，请确认以下信息： - -+ pd-server、tikv-server 数据都已清空 - - tikv-server 存储具体的数据，pd-server 存储 tikv-server 中数据的的元信息。如果只清空 pd-server 或只清空 tikv-server 的数据，会导致两边数据不匹配。 - -+ 清空 pd-server 和 tikv-server 的数据并重启后，也需要重启 tidb-server - - 集群 ID 是由 pd-server 在集群初始化时随机分配，所以重新部署集群后，集群 ID 会发生变化。tidb-server 业务需要重启以获取新的集群 ID。 - -## tidb-server 启动报错 - -tidb-server 无法启动的常见情况包括： - -+ 启动参数错误 - - 请参考 [TiDB 命令行参数](/dev/reference/configuration/tidb-server/configuration.md)。 - -+ 端口被占用：`lsof -i:port` - - 请确保 tidb-server 启动所需要的端口未被占用。 - -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志，确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tidb-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。 - - 例如，假设 tidb 服务位于 `192.168.1.100`，无法连接的 pd 位于 `192.168.1.101`，且 2379 为其 client port， - 则可以在 tidb 机器上执行 `nc -v -z 192.168.1.101 2379`，测试是否可以访问端口。 - 或使用 `curl -v 192.168.1.101:2379/pd/api/v1/leader` 直接检查 pd 是否正常服务。 - -## tikv-server 启动报错 - -+ 启动参数错误 - - 请参考 [TiKV 启动参数](/dev/reference/configuration/tikv-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 tikv-server 启动所需要的端口未被占用：`lsof -i:port`。 -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志。确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tikv-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。具体命令参考上一节。 - -+ 文件被占用 - - 不要在一个数据库文件目录上打开两个 tikv。 - -## pd-server 启动报错 - -+ 启动参数错误 - - 请参考 [PD 命令行参数](/dev/reference/configuration/pd-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 pd-server 启动所需要的端口未被占用：`lsof -i:port`。 - -## TiDB/TiKV/PD 进程异常退出 - -+ 进程是否是启动在前台 - - 当前终端退出给其所有子进程发送 HUP 信号，从而导致进程退出。 - -+ 是否是在命令行用过 `nohup+&` 方式直接运行 - - 这样依然可能导致进程因终端连接突然中断，作为终端 SHELL 的子进程被杀掉。 - - 推荐将启动命令写在脚本中，通过脚本运行（相当于二次 fork 启动）。 - -## TiKV 进程异常重启 - -+ 检查 dmesg 或者 syslog 里面是否有 OOM 信息 - - 如果有 OOM 信息并且杀掉的进程为 TiKV，请减少 TiKV 的 RocksDB 的各个 CF 的 `block-cache-size` 值。 - -+ 检查 TiKV 日志是否有 panic 的 log - - 提交 Issue 并附上 panic 的 log。 - -## TiDB panic - -请提供 panic 的 log。 - -## 连接被拒绝 - -+ 请确保操作系统的网络参数正确，包括但不限于 - - 连接字符串中的端口和 tidb-server 启动的端口需要一致 - - 请保证防火墙的配置正确 - -## Too many open files - -在启动进程之前，请确保 `ulimit -n` 的结果足够大，推荐设为 unlimited 或者是大于 1000000。 - -## 数据库访问超时，系统负载高 - -首先检查 [SLOW-QUERY](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息： - -+ 部署的拓扑结构 - - tidb-server/pd-server/tikv-server 部署了几个实例 - - 这些实例在机器上是如何分布的 -+ 机器的硬件配置 - - CPU 核数 - - 内存大小 - - 硬盘类型（SSD 还是机械硬盘） - - 是实体机还是虚拟机 -+ 机器上除了 TiDB 集群之外是否还有其他服务 -+ pd-server 和 tikv-server 是否分开部署 -+ 目前正在进行什么操作 -+ 用 `top -H` 命令查看当前占用 CPU 的线程名 -+ 最近一段时间的网络/IO 监控数据是否有异常 diff --git a/dev/how-to/troubleshoot/tidb-lightning.md b/dev/how-to/troubleshoot/tidb-lightning.md deleted file mode 100644 index 0a7e274623b1..000000000000 --- a/dev/how-to/troubleshoot/tidb-lightning.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: TiDB Lightning 故障诊断 -category: reference ---- - -# TiDB Lightning 故障诊断 - -当 Lightning 遇到不可恢复的错误时便会异常退出，并在日志中记下错误原因。一般可在日志底部找到，也可以搜索 `[error]` 字符串找出中间发生的错误。本文主要描述一些常见的错误及其解决方法。 - -## 导入速度太慢 - -TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件，如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 `restore chunk … takes` 的记录，或者观察 Grafana 的监控信息。 - -导入速度太慢一般有几个原因： - -**原因 1**：`region-concurrency` 设定太高，线程间争用资源反而减低了效率。 - -1. 从日志的开头搜寻 `region-concurrency` 能知道 Lightning 读到的参数是多少。 -2. 如果 Lightning 与其他服务（如 Importer）共用一台服务器，必需**手动**将 `region-concurrency` 设为该服务器 CPU 数量的 75%。 -3. 如果 CPU 设有限额（例如从 Kubernetes 指定的上限），Lightning 可能无法自动判断出来，此时亦需要**手动**调整 `region-concurrency`。 - -**原因 2**：表结构太复杂。 - -每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 - -**原因 3**：Lightning 版本太旧。 - -试试最新的版本吧！可能会有改善。 - -## checksum failed: checksum mismatched remote vs local - -**原因**：本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因： - -1. 这张表可能本身已有数据，影响最终结果。 -2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。 -3. 如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如： - - * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。 - * 唯一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。 -4. 如果 TiDB Lightning 之前失败停机过，但没有正确重启，可能会因为数据不同步而出现校验和不一致。 - -**解决办法**： - -1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。 - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。 - -3. 参考[如何正确重启 TiDB Lightning](/dev/faq/tidb-lightning.md#如何正确重启-tidb-lightning)中的解决办法。 - -## Checkpoint for … has invalid status:（错误码） - -**原因**：[断点续传](/dev/reference/tools/tidb-lightning/checkpoints.md)已启用。Lightning 或 Importer 之前发生了异常退出。为了防止数据意外损坏，Lightning 在错误解决以前不会启动。 - -错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。 - -**解决办法**： - -如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。 - -{{< copyable "shell-regular" >}} - -```sh -tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all -``` - -其他解决方法请参考[断点续传的控制](/dev/reference/tools/tidb-lightning/checkpoints.md#断点续传的控制)。 - -## ResourceTemporarilyUnavailable("Too many open engines …: …") - -**原因**：并行打开的引擎文件 (engine files) 超出 `tikv-importer` 里的限制。这可能由配置错误引起。即使配置没问题，如果 `tidb-lightning` 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。 - -**解决办法**： - -1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为： - - 最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number` - -2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。 - -3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录： - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -## cannot guess encoding for input file, please convert to UTF-8 manually - -**原因**：Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如，因为在不同的环境运行过 `ALTER TABLE`，使表架构同时出现 UTF-8 和 GB-18030 的字符。 - -**解决办法**： - -1. 编辑数据源，保存为纯 UTF-8 或 GB-18030 的文件。 -2. 手动在目标数量库创建所有的表，然后设置 `[mydumper] no-schema = true` 跳过创建表的步骤。 -3. 设置 `[mydumper] character-set = "binary"` 跳过这个检查。但是这样可能使数据库出现乱码。 - -## [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 …}' - -**原因**: 一个 `timestamp` 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。 - -**解决办法**: - -1. 确保 Lightning 与数据源时区一致。 - - * 使用 Ansible 部署的话，修正 [`inventory.ini`] 下的 `timezone` 变量。 - - ```ini - # inventory.ini - [all:vars] - timezone = Asia/Shanghai - ``` - - * 手动部署的话，通过设定 `$TZ` 环境变量强制时区设定。 - - 强制使用 Asia/Shanghai 时区： - - {{< copyable "shell-regular" >}} - - ```sh - TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml - ``` - -2. 导出数据时，必须加上 `--skip-tz-utc` 选项。 - -3. 确保整个集群使用的是同一最新版本的 `tzdata` (2018i 或更高版本)。 - - 如果你使用的是 CentOS 机器，你可以运行 `yum info tzdata` 命令查看 `tzdata` 的版本及是否有更新。然后运行 `yum upgrade tzdata` 命令升级 `tzdata`。 diff --git a/dev/how-to/upgrade/from-previous-version.md b/dev/how-to/upgrade/from-previous-version.md deleted file mode 100644 index a59bcf2a416d..000000000000 --- a/dev/how-to/upgrade/from-previous-version.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: TiDB 最新开发版升级操作指南 -category: how-to -aliases: ['/docs-cn/dev/how-to/upgrade/to-tidb-3.0/','/docs-cn/dev/how-to/upgrade/rolling-updates-with-ansible/'] ---- - -# TiDB 最新开发版升级操作指南 - -本文档适用于从 TiDB 2.0、2.1、3.0、3.1 版本升级至 TiDB 最新开发版 (latest) 以及从开发版的较低版本升级至最新版本。目前，TiDB 最新开发版兼容 [TiDB Binlog Cluster 版本](/dev/reference/tidb-binlog/overview.md)。 - -> **警告：** -> -> TiDB 最新开发版为非稳定版本，不建议用于生产环境。 - -## 升级兼容性说明 - -- 不支持在升级后回退至 2.1.x 或更旧版本 -- 从 2.0.6 之前的版本升级到 latest 之前，需要确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 `Add Index` 操作，等 DDL 操作完成后再执行升级操作 -- 2.1 及之后版本启用了并行 DDL，早于 2.0.1 版本的集群，无法滚动升级到 latest 版本，可以选择下面两种方案： - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 latest 版本 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 latest 版本 - -> **注意：** -> -> 在升级的过程中不要执行 DDL 请求，否则可能会出现行为未定义的问题。 - -## 在中控机器上安装 Ansible 及其依赖 - -> **注意：** -> -> 如果已经安装了 Ansible 及其依赖，可跳过该步骤。 - -TiDB Ansible 最新开发版依赖 2.4.2 及以上但不高于 2.7.11 的 Ansible 版本（`2.4.2 ≦ ansible ≦ 2.7.11`，建议 2.7.11 版本），另依赖 Python 模块：`jinja2 ≧ 2.9.6` 和 `jmespath ≧ 0.9.0`。为方便管理依赖，建议使用 `pip` 安装 Ansible 及其依赖，可参照[在中控机器上安装 Ansible 及其依赖](/dev/how-to/deploy/orchestrated/ansible.md#在中控机器上安装-ansible-及其依赖) 进行安装。离线环境参照[在中控机器上离线安装 Ansible 及其依赖](/dev/how-to/deploy/orchestrated/offline-ansible.md#在中控机器上离线安装-ansible-及其依赖)。 - -安装完成后，可通过以下命令查看版本： - -{{< copyable "shell-regular" >}} - -```bash -ansible --version -``` - -``` -ansible 2.7.11 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jinja2 -``` - -``` -Name: Jinja2 -Version: 2.10 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jmespath -``` - -``` -Name: jmespath -Version: 0.9.0 -``` - -> **注意：** -> -> 请务必按以上文档安装 Ansible 及其依赖。确认 Jinja2 版本是否正确，否则启动 Grafana 时会报错。确认 jmespath 版本是否正确，否则滚动升级 TiKV 时会报错。 - -## 在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录，备份 TiDB 2.0、2.1、3.0 或其他低版本的 tidb-ansible 文件夹： - -{{< copyable "shell-regular" >}} - -```bash -mv tidb-ansible tidb-ansible-bak -``` - -下载 TiDB latest 版本对应的 tidb-ansible [**下载 TiDB Ansible**](/dev/how-to/deploy/orchestrated/ansible.md#在中控机器上下载-tidb-ansible)，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone https://github.com/pingcap/tidb-ansible.git -``` - -## 编辑 inventory.ini 文件和配置文件 - -以 `tidb` 用户登录中控机并进入 `/home/tidb/tidb-ansible` 目录。 - -### 编辑 `inventory.ini` 文件 - -编辑 `inventory.ini` 文件，IP 信息参照备份文件 `/home/tidb/tidb-ansible-bak/inventory.ini`。 - -以下变量配置，需要重点确认，变量含义可参考 [inventory.ini 变量调整](/dev/how-to/deploy/orchestrated/ansible.md#调整其它变量可选)。 - -1. 请确认 `ansible_user` 配置的是普通用户。为统一权限管理，不再支持使用 root 用户远程安装。默认配置中使用 `tidb` 用户作为 SSH 远程用户及程序运行用户。 - - ``` - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - 可参考[如何配置 SSH 互信及 sudo 规则](/dev/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)自动配置主机间互信。 - -2. `process_supervision` 变量请与之前版本保持一致，默认推荐使用 `systemd`。 - - ``` - # process supervision, [systemd, supervise] - process_supervision = systemd - ``` - - 如需变更，可参考[如何调整进程监管方式从 supervise 到 systemd](/dev/how-to/deploy/orchestrated/ansible.md#如何调整进程监管方式从-supervise-到-systemd)，先使用备份 `/home/tidb/tidb-ansible-bak/` 分支变更进程监管方式再升级。 - -### 编辑 TiDB 集群组件配置文件 - -如之前自定义过 TiDB 集群组件配置文件，请参照备份文件修改 `/home/tidb/tidb-ansible/conf` 下对应配置文件。 - -**注意以下参数变更：** - -- TiKV 配置中 `end-point-concurrency` 变更为 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ``` - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 2.0 版本升级且单机多 TiKV 实例（进程）情况下，需要修改这三个参数。 - > - > 推荐设置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 - -- TiKV 配置中不同 CF 中的 `block-cache-size` 参数变更为 `block-cache`： - - ``` - storage: - block-cache: - capacity: "1GB" - ``` - - > **注意：** - > - > 单机多 TiKV 实例（进程）情况下，需要修改 `capacity` 参数。 - > - > 推荐设置：`capacity` = (MEM_TOTAL * 0.5 / TiKV 实例数量) - -- TiKV 配置中单机多实例场景需要额外配置 `tikv_status_port` 端口： - - ``` - [tikv_servers] - TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" - TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" - TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" - TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" - TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" - TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - ``` - - > **注意：** - > - > 最新开发版单机多 TiKV 实例（进程）情况下，需要添加 `tikv_status_port` 参数。 - > - > 配置前，注意检查端口是否有冲突。 - -## 下载 TiDB latest binary 到中控机 - -确认 `tidb-ansible/inventory.ini` 文件中 `tidb_version = latest`，然后执行以下命令下载 TiDB latest binary 到中控机。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 滚动升级 TiDB 集群组件 - -- 如果 `process_supervision` 变量使用默认的 `systemd` 参数： - - - 当前集群版本 < 3.0，则通过 `excessive_rolling_update.yml` 滚动升级 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook excessive_rolling_update.yml - ``` - - - 当前集群版本 ≥ 3.0.0，滚动升级及日常滚动重启 TiDB 集群，使用 `rolling_update.yml`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -- 如果 `process_supervision` 变量使用的是 `supervise` 参数，无论当前集群为哪个版本，均通过 `rolling_update.yml` 来滚动升级 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -## 滚动升级 TiDB 监控组件 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook rolling_update_monitor.yml -``` diff --git a/dev/overview.md b/dev/overview.md deleted file mode 100644 index acfb689d4c3b..000000000000 --- a/dev/overview.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/dev/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，配合 [TiDB Operator 项目](/dev/tidb-in-kubernetes/tidb-operator-overview.md) 可实现自动化运维，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/dev/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/dev/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，推荐使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/dev/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 TiDB Operator 部署](/dev/tidb-in-kubernetes/deploy/tidb-operator.md)：使用 TiDB Operator 在 Kubernetes 集群上部署生产就绪的 TiDB 集群，支持[部署到 AWS EKS](/dev/tidb-in-kubernetes/deploy/aws-eks.md)、[部署到谷歌云 GKE (beta)](/dev/tidb-in-kubernetes/deploy/gcp-gke.md)、[部署到阿里云 ACK](/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md) 等。 -- [使用 Docker Compose 部署](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/dev/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 -- [使用 TiDB Operator 部署到 Minikube](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：你可以使用 TiDB Opeartor 将 TiDB 集群部署到本地 Minikube 启动的 Kubernetes 集群中。该部署方式不适用于生产环境。 -- [使用 TiDB Operator 部署到 kind](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：你可以使用 TiDB Operator 将 TiDB 集群部署到以 kind 方式启动的 Kubernetes 本地集群中。该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/dev/reference/alert-rules.md b/dev/reference/alert-rules.md deleted file mode 100644 index 4f4ad8089bbb..000000000000 --- a/dev/reference/alert-rules.md +++ /dev/null @@ -1,1161 +0,0 @@ ---- -title: TiDB 集群报警规则 -summary: TiDB 集群中各组件的报警规则详解。 -category: reference ---- - -# TiDB 集群报警规则 - -本文介绍了 TiDB 集群中各组件的报警规则，包括 TiDB、TiKV、PD、TiDB Binlog、Node_exporter 和 Blackbox_exporter 的各报警项的规则描述及处理方法。 - -## TiDB 报警规则 - -本节介绍了 TiDB 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_schema_error` - -* 报警规则： - - `increase(tidb_session_schema_lease_error_total{type="outdated"}[15m]) > 0` - -* 规则描述： - - TiDB 在一个 Lease 时间内没有重载到最新的 Schema 信息。如果 TiDB 无法继续对外提供服务，则报警。 - -* 处理方法： - - 该问题通常由于 TiKV Region 不可用或超时导致，需要看 TiKV 的监控指标定位问题。 - -#### `TiDB_tikvclient_region_err_total` - -* 报警规则： - - `increase(tidb_tikvclient_region_err_total[10m]) > 6000` - -* 规则描述： - - TiDB 访问 TiKV 时发生了 Region 错误。如果在 10 分钟之内该错误多于 6000 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_domain_load_schema_total` - -* 报警规则： - - `increase(tidb_domain_load_schema_total{type="failed"}[10m]) > 10` - -* 规则描述： - - TiDB 重载最新的 Schema 信息失败的总次数。如果在 10 分钟之内重载失败次数超过 10 次，则报警。 - -* 处理方法： - - 参考 [`TiDB_schema_error`](#tidb_schema_error) 的处理方法。 - -#### `TiDB_monitor_keep_alive` - -* 报警规则： - - `increase(tidb_monitor_keep_alive_total[10m]) < 100` - -* 规则描述： - - 表示 TiDB 的进程是否仍然存在。如果在 10 分钟之内 `tidb_monitor_keep_alive_total` 增加次数少于 100，则 TiDB 的进程可能已经退出，此时会报警。 - -* 处理方法： - - * 检查 TiDB 进程是否 OOM。 - * 检查机器是否发生了重启。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiDB_server_panic_total` - -* 报警规则： - - `increase(tidb_server_panic_total[10m]) > 0` - -* 规则描述： - - 发生崩溃的 TiDB 线程的数量。当出现崩溃的时候会报警。该线程通常会被恢复，否则 TiDB 会频繁重启。 - -* 处理方法： - - 收集 panic 日志，定位原因。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiDB_memory_abnormal` - -* 报警规则： - - `go_memstats_heap_inuse_bytes{job="tidb"} > 1e+10` - -* 规则描述： - - 对 TiDB 内存使用量的监控。如果内存使用大于 10 G，则报警。 - -* 处理方法： - - 通过 HTTP API 来排查 goroutine 泄露的问题。 - -#### `TiDB_query_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tidb_server_handle_query_duration_seconds_bucket[1m])) BY (le, instance)) > 1` - -* 规则描述： - - TiDB 处理请求的延时。如果 .99 的延迟大于 1 秒，则报警。 - -* 处理方法： - - 查看 TiDB 的日志，搜索 SLOW_QUERY 和 TIME_COP_PROCESS 关键字，查找慢 SQL。 - -#### `TiDB_server_event_error` - -* 报警规则： - - `increase(tidb_server_event_total{type=~"server_start|server_hang"}[15m]) > 0` - -* 规则描述： - - TiDB 服务中发生的事件数量。当出现以下事件的时候会报警： - - 1. start：TiDB 服务启动。 - 2. hang：当发生了 Critical 级别的事件时（目前只有 Binlog 写不进去一种情况），TiDB 进入 `hang` 模式，并等待人工 Kill。 - -* 处理方法： - - * 重启 TiDB 以恢复服务。 - * 检查 TiDB Binlog 服务是否正常。 - -#### `TiDB_tikvclient_backoff_total` - -* 报警规则： - - `increase(tidb_tikvclient_backoff_total[10m]) > 10` - -* 规则描述： - - TiDB 访问 TiKV 发生错误时发起重试的次数。如果在 10 分钟之内重试次数多于 10 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_monitor_time_jump_back_error` - -* 报警规则： - - `increase(tidb_monitor_time_jump_back_total[10m]) > 0` - -* 规则描述： - - 如果 TiDB 所在机器的时间发生了回退，则报警。 - -* 处理方法： - - 排查 NTP 配置。 - -#### `TiDB_ddl_waiting_jobs` - -* 报警规则： - - `sum(tidb_ddl_waiting_jobs) > 5` - -* 规则描述： - - 如果 TiDB 中等待执行的 DDL 任务的数量大于 5，则报警。 - -* 处理方法： - - 通过 `admin show ddl` 语句检查是否有耗时的 add index 操作正在执行。 - -## PD 报警规则 - -本节介绍了 PD 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `PD_cluster_offline_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_down_count"}) > 0` - -* 规则描述： - - PD 长时间（默认配置是 30 分钟）没有收到 TiKV 心跳。 - -* 处理方法： - - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `PD_etcd_write_disk_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[1m])) by (instance,job,le)) > 1` - -* 规则描述： - - etcd 写盘慢，这很容易引起 PD leader 超时或者 TSO 无法及时存盘等问题，从而导致整个集群停止服务。 - -* 处理方法： - - * 排查写入慢的原因。可能是由于其他服务导致系统负载过高。可以检查 PD 本身是否占用了大量 CPU 或 IO 资源。 - * 可尝试重启 PD 或手动 transfer leader 至其他的 PD 来恢复服务。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_miss_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="miss_peer_region_count"}) > 100` - -* 规则描述： - - Region 的副本数小于 `max-replicas` 配置的值。这通常是由于 TiKV 宕机等问题导致一段时间内一些 Region 缺副本，下线 TiKV 节点也会导致少量 Region 缺副本（对于有 pending peer 的 Region 会走先减后加的流程）。 - -* 处理方法： - - * 查看是否有 TiKV 宕机或在做下线操作，尝试定位问题产生的原因。 - * 观察 region health 面板，查看 `miss_peer_region_count` 是否在不断减少。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `PD_cluster_lost_connect_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_disconnected_count"}) > 0` - -* 规则描述： - - PD 在 20 秒之内未收到 TiKV 上报心跳。正常情况下是每 10 秒收到 1 次心跳。 - -* 处理方法： - - * 排查是否在重启 TiKV。 - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - * 如果确定 TiKV 可以恢复，但在短时间内还无法恢复，可以考虑延长 `max-down-time` 配置，防止超时后 TiKV 被判定为无法恢复并开始搬移数据。 - -#### `PD_cluster_low_space` - -* 报警规则： - - `sum(pd_cluster_status{type="store_low_space_count"}) > 0` - -* 规则描述： - - 表示 TiKV 节点空间不足。 - -* 处理方法： - - * 检查集群中的空间是否普遍不足。如果是，则需要扩容。 - * 检查 Region balance 调度是否有问题。如果有问题，会导致数据分布不均衡。 - * 检查是否有文件占用了大量磁盘空间，比如日志、快照、core dump 等文件。 - * 降低该节点的 Region weight 来减少数据量。 - * 无法释放空间时，可以考虑主动下线该节点，防止由于磁盘空间不足而宕机。 - -#### `PD_etcd_network_peer_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_network_peer_round_trip_time_seconds_bucket[1m])) by (To,instance,job,le)) > 1` - -* 规则描述： - - PD 节点之间网络延迟高，严重情况下会导致 leader 超时和 TSO 存盘超时，从而影响集群服务。 - -* 处理方法： - - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_tidb_handle_requests_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(pd_client_request_handle_requests_duration_seconds_bucket{type="tso"}[1m])) by (instance,job,le)) > 0.1` - -* 规则描述： - - PD 处理 TSO 请求耗时过长，一般是由于负载过高。 - -* 处理方法： - - * 检查服务器负载状况。 - * 使用 pprof 抓取 PD 的 CPU profile 进行分析。 - * 手动切换 PD leader。 - * 如果是环境问题，则将有问题的 PD 下线替换。 - -#### `PD_down_peer_region_nums` - -* 报警规则： - - `sum(pd_regions_status{type="down_peer_region_count"}) > 0` - -* 规则描述： - - Raft leader 上报有不响应 peer 的 Region 数量。 - -* 处理方法： - - * 检查是否有 TiKV 宕机，或刚发生重启，或者繁忙。 - * 观察 region health 面板，检查 `down_peer_region_count` 是否在不断减少。 - * 检查是否有 TiKV 之间网络不通。 - -#### `PD_pending_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="pending_peer_region_count"}) > 100` - -* 规则描述： - - Raft log 落后的 Region 过多。由于调度产生少量的 pending peer 是正常的，但是如果持续很高，就可能有问题。 - -* 处理方法： - - * 观察 region health 面板，检查 `pending_peer_region_count` 是否在不断减少。 - * 检查 TiKV 之间的网络状况，特别是带宽是否足够。 - -#### `PD_leader_change` - -* 报警规则： - - `count(changes(pd_server_tso{type="save"}[10m]) > 0) >= 2` - -* 规则描述： - - 近期发生了 PD leader 切换。 - -* 处理方法： - - * 排除人为因素，比如重启 PD、手动 transfer leader 或调整 leader 优先级等。 - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `TiKV_space_used_more_than_80%` - -* 报警规则： - - `sum(pd_cluster_status{type="storage_size"}) / sum(pd_cluster_status{type="storage_capacity"}) * 100 > 80` - -* 规则描述： - - 集群空间占用超过 80%。 - -* 处理方法： - - * 确认是否需要扩容。 - * 排查是否有文件占用了大量磁盘空间，比如日志、快照或 core dump等文件。 - -#### `PD_system_time_slow` - -* 报警规则： - - `changes(pd_server_tso{type="system_time_slow"}[10m]) >= 1` - -* 规则描述： - - 系统时间可能发生回退。 - -* 处理方法： - - 检查系统时间设置是否正确。 - -#### `PD_no_store_for_making_replica` - -* 报警规则： - - `increase(pd_checker_event_count{type="replica_checker", name="no_target_store"}[1m]) > 0` - -* 规则描述： - - 没有合适的 store 用来补副本。 - -* 处理方法： - - * 检查 store 是否空间不足。 - * 根据 label 配置（如果有这个配置的话）来检查是否有可以补副本的 store。 - -## TiKV 报警规则 - -本节介绍了 TiKV 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiKV_memory_used_too_fast` - -* 报警规则： - - `process_resident_memory_bytes{job=~"tikv",instance=~".*"} - (process_resident_memory_bytes{job=~"tikv",instance=~".*"} offset 5m) > 5*1024*1024*1024` - -* 规则描述： - - 目前没有和内存相关的 TiKV 的监控，你可以通过 Node_exporter 监控集群内机器的内存使用情况。如上规则表示，如果在 5 分钟之内内存使用超过 5GB（TiKV 内存占用的太快），则报警。 - -* 处理方法： - - 调整 `rockdb.defaultcf` 和 `rocksdb.writecf` 的 `block-cache-size` 的大小。 - -#### `TiKV_GC_can_not_work` - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="success"}[6h])) < 1` - - > **注意：** - > - > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 - -* 规则描述： - - 在 6 小时内 Region 上没有成功执行 GC，说明 GC 不能正常工作了。短期内 GC 不运行不会造成太大的影响，但如果 GC 一直不运行，版本会越来越多，从而导致查询变慢。 - -* 处理方法： - - 1. 执行 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME="tikv_gc_leader_desc"` 来找到 gc leader 对应的 `tidb-server`； - 2. 查看该 `tidb-server` 的日志，grep gc_worker tidb.log； - 3. 如果发现这段时间一直在 resolve locks（最后一条日志是 `start resolve locks`）或者 delete ranges（最后一条日志是 `start delete {number} ranges`），说明 GC 进程是正常的。否则需要报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiKV_server_report_failure_msg_total` - -* 报警规则： - - `sum(rate(tikv_server_report_failure_msg_total{type="unreachable"}[10m])) BY (store_id) > 10` - -* 规则描述： - - 表明无法连接远端的 TiKV。 - -* 处理方法： - - 1. 检查网络是否通畅。 - 2. 检查远端 TiKV 是否挂掉。 - 3. 如果远端 TiKV 没有挂掉，检查压力是否太大，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 处理方法。 - -#### `TiKV_channel_full_total` - -* 报警规则： - - `sum(rate(tikv_channel_full_total[10m])) BY (type, instance) > 0` - -* 规则描述： - - 该错误通常是因为 Raftstore 线程卡死，TiKV 的压力已经非常大了。 - -* 处理方法： - - 1. 观察 Raft Propose 监控，看这个报警的 TiKV 节点是否明显有比其他 TiKV 高很多。如果是，表明这个 TiKV 上有热点，需要检查热点调度是否能正常工作。 - 2. 观察 Raft IO 监控，看延迟是否升高。如果延迟很高，表明磁盘可能有瓶颈。一个能缓解但不怎么安全的办法是将 `sync-log` 改成 `false`。 - 3. 观察 Raft Process 监控，看 tick duration 是否很高。如果是，需要在 `[raftstore]` 配置下加上 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_write_stall` - -* 报警规则： - - `delta(tikv_engine_write_stall[10m]) > 0` - -* 规则描述： - - RocksDB 写入压力太大，出现了 stall。 - -* 处理方法： - - 1. 观察磁盘监控，排除磁盘问题。 - 2. 看 TiKV 是否有写入热点。 - 3. 在 `[rocksdb]` 和 `[raftdb]` 配置下调大 `max-sub-compactions` 的值。 - -#### `TiKV_raft_log_lag` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_log_lag_bucket[1m])) by (le, instance)) > 5000` - -* 规则描述： - - 这个值偏大，表明 Follower 已经远远落后于 Leader，Raft 没法正常同步了。可能的原因是 Follower 所在的 TiKV 卡住或者挂掉了。 - -#### `TiKV_async_request_snapshot_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="snapshot"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raftstore 负载压力很大，可能已经卡住。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_async_request_write_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="write"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raft write 耗时很长。 - -* 处理方法： - - 1. 检查 Raftstore 上的压力，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 检查 apply worker 线程的压力。 - -#### `TiKV_coprocessor_request_wait_seconds` - -* 报警规则： - - `histogram_quantile(0.9999, sum(rate(tikv_coprocessor_request_wait_seconds_bucket[1m])) by (le, instance, req)) > 10` - -* 规则描述： - - 这个值偏大，表明 Coprocessor worker 压力很大。可能有比较慢的任务卡住了 Coprocessor 线程。 - -* 处理方法： - - 1. 从 TiDB 日志中查看慢查询日志，看查询是否用到了索引或全表扫，或者看是否需要做 analyze。 - 2. 排查是否有热点。 - 3. 查看 Coprocessor 监控，看 `coporcessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 - -#### `TiKV_raftstore_thread_cpu_seconds_total` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"raftstore_.*"}[1m])) by (instance, name) > 1.6` - -* 规则描述： - - Raftstore 线程压力太大。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_raft_append_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_append_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 append Raft log 的耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_raft_apply_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_apply_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 apply Raft log 耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_scheduler_latch_wait_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_latch_wait_duration_seconds_bucket[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - Scheduler 中写操作获取内存锁时的等待时间。如果这个值高，表明写操作冲突较多，也可能是某些引起冲突的操作耗时较长，阻塞了其它等待相同锁的操作。 - -* 处理方法： - - 1. 查看 Scheduler-All 监控中的 scheduler command duration，看哪一个命令耗时最大。 - 2. 查看 Scheduler-All 监控中的 scheduler scan details，看 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描，另外观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 - 3. 查看 Storage 监控中的 storage async snapshot/write duration，看是否 Raft 操作不及时。 - -#### `TiKV_thread_apply_worker_cpu_seconds` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name="apply_worker"}[1m])) by (instance) > 1.8` - -* 规则描述： - - Apply Raft log 线程压力太大，通常是因为写入太猛了。 - -#### `TiDB_tikvclient_gc_action_fail`（基本不发生，只在特殊配置下才会发生） - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="fail”}[1m])) > 10` - - > **注意：** - > - > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 - -* 规则描述： - - GC 失败的 Region 较多。 - -* 处理方法： - - 1. 一般是因为并行 GC 开的太高了，可以适当降低 GC 并行度。你需要先确认 GC 失败是由于服务器繁忙导致的。 - 2. 通过执行 `update set VARIABLE_VALUE=”{number}” where VARIABLE_NAME=”tikv_gc_concurrency”` 适当降低并行度。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiKV_leader_drops` - -* 报警规则： - - `delta(tikv_pd_heartbeat_tick_total{type="leader"}[30s]) < -10` - -* 规则描述： - - 该问题通常是因为 Raftstore 线程卡住了。 - -* 处理方法： - - 1. 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 如果 TiKV 压力很小，考虑 PD 的调度是否太频繁。可以查看 PD 页面的 Operator Create 面板，排查 PD 产生调度的类型和数量。 - -#### `TiKV_raft_process_ready_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type='ready'}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft ready 的耗时。这个值大，通常是因为 append log 任务卡住了。 - -#### `TiKV_raft_process_tick_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type=’tick’}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft tick 的耗时，这个值大，通常是因为 Region 太多导致的。 - -* 处理方法： - - 1. 考虑使用更高等级的日志，比如 `warn` 或者 `error`。 - 2. 在 `[raftstore]` 配置下添加 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_scheduler_context_total` - -* 报警规则： - - `abs(delta( tikv_scheduler_context_total[5m])) > 1000` - -* 规则描述： - - Scheduler 正在执行的写命令数量。这个值高，表示任务完成得不及时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_scheduler_command_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_command_duration_seconds_bucket[1m])) by (le, instance, type) / 1000) > 1` - -* 规则描述： - - 表明 Scheduler 执行命令的耗时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_coprocessor_outdated_request_wait_seconds` - -* 报警规则： - - `delta(tikv_coprocessor_outdated_request_wait_seconds_count[10m]) > 0` - -* 规则描述： - - Coprocessor 已经过期的请求等待的时间。这个值高，表示 Coprocessor 压力已经非常大了。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_coprocessor_request_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason!="lock"}[10m]) > 100` - -* 规则描述： - - Coprocessor 的请求错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”和“full”等。“outdated”表示请求超时，很可能是由于排队时间过久，或者单个请求的耗时比较长。“full”表示 Coprocessor 的请求队列已经满了，可能是正在执行的请求比较耗时，导致新来的请求都在排队。耗时比较长的查询需要查看下对应的执行计划是否正确。 - -#### `TiKV_coprocessor_request_lock_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason="lock"}[10m]) > 10000` - -* 规则描述： - - Coprocessor 请求锁的错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”、“full”等。“lock”表示读到的数据正在写入，需要等待一会再读（TiDB 内部会自动重试）。少量这种错误不用关注，如果有大量这种错误，需要查看写入和查询是否有冲突。 - -#### `TiKV_coprocessor_pending_request` - -* 报警规则： - - `delta(tikv_coprocessor_pending_request[10m]) > 5000` - -* 规则描述： - - Coprocessor 排队的请求。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_batch_request_snapshot_nums` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"cop_.*"}[1m])) by (instance) / (count(tikv_thread_cpu_seconds_total{name=~"cop_.*"}) * 0.9) / count(count(tikv_thread_cpu_seconds_total) by (instance)) > 0` - -* 规则描述： - - 某个 TiKV 的 Coprocessor CPU 使用率超过了 90%。 - -#### `TiKV_pending_task` - -* 报警规则： - - `sum(tikv_worker_pending_task_total) BY (instance,name) > 1000` - -* 规则描述： - - TiKV 等待的任务数量。 - -* 处理方法： - - 查看是哪一类任务的值偏高，通常 Coprocessor、apply worker 这类任务都可以在其他指标里找到解决办法。 - -#### `TiKV_low_space_and_add_region` - -* 报警规则： - - `count((sum(tikv_store_size_bytes{type="available"}) by (instance) / sum(tikv_store_size_bytes{type="capacity"}) by (instance) < 0.2) and (sum(tikv_raftstore_snapshot_traffic_total{type="applying"}) by (instance) > 0)) > 0` - -#### `TiKV_approximate_region_size` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_region_size_bucket[1m])) by (le)) > 1073741824` - -* 规则描述： - - TiKV split checker 扫描到的最大的 Region approximate size 在 1 分钟内持续大于 1 GB。 - -* 处理方法： - - Region 分裂的速度不及写入的速度。为缓解这种情况，建议更新到支持 batch-split 的版本 (>= 2.1.0-rc1)。如暂时无法更新，可以使用 `pd-ctl operator add split-region --policy=approximate` 手动分裂 Region。 - -## TiDB Binlog 报警规则 - -关于 TiDB Binlog 报警规则的详细描述，参见 [TiDB Binlog 集群监控报警文档](/dev/reference/tidb-binlog/monitor.md#监控报警规则)。 - -## Node_exporter 主机报警规则 - -本节介绍了 Node_exporter 主机的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `NODE_disk_used_more_than_80%` - -* 报警规则： - - `node_filesystem_avail{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} / node_filesystem_size{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} * 100 <= 20` - -* 规则描述： - - 机器磁盘空间使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -h` 命令，查看磁盘空间使用率，做好扩容计划。 - -#### `NODE_disk_inode_more_than_80%` - -* 报警规则： - - `node_filesystem_files_free{fstype=~"(ext.|xfs)"} / node_filesystem_files{fstype=~"(ext.|xfs)"} * 100 < 20` - -* 规则描述： - - 机器磁盘挂载目录文件系统 inode 使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -i` 命令，查看磁盘挂载目录文件系统 inode 使用率，做好扩容计划。 - -#### `NODE_disk_readonly` - -* 报警规则： - - `node_filesystem_readonly{fstype=~"(ext.|xfs)"} == 1` - -* 规则描述： - - 磁盘挂载目录文件系统只读，无法写入数据，一般是因为磁盘故障或文件系统损坏。 - -* 处理方法： - - * 登录机器创建文件测试是否正常。 - * 检查该服务器硬盘指示灯是否正常，如异常，需更换磁盘并修复该机器文件系统。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `NODE_memory_used_more_than_80%` - -* 报警规则： - - `(((node_memory_MemTotal-node_memory_MemFree-node_memory_Cached)/(node_memory_MemTotal)*100)) >= 80` - -* 规则描述： - - 机器内存使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node Exporter 页面查看该主机的 Memory 面板，检查 `Used` 是否过高，`Available` 内存是否过低。 - * 登录机器，执行 `free -m` 命令查看内存使用情况，执行 `top` 看是否有异常进程的内存使用率过高。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `NODE_node_overload` - -* 报警规则： - - `(node_load5 / count without (cpu, mode) (node_cpu{mode="system"})) > 1` - -* 规则描述： - - 机器 CPU 负载较高。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_cpu_used_more_than_80%` - -* 报警规则： - - `avg(irate(node_cpu{mode="idle"}[5m])) by(instance) * 100 <= 20` - -* 规则描述： - - 机器 CPU 使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_tcp_estab_num_more_than_50000` - -* 报警规则： - - `node_netstat_Tcp_CurrEstab > 50000` - -* 规则描述： - - 机器 `establish` 状态的 TCP 链接超过 50,000。 - -* 处理方法： - - 登录机器执行 `ss -s` 可查看当前系统 `estab` 状态的 TCP 链接数，执行 `netstat` 查看是否有异常链接。 - -#### `NODE_disk_read_latency_more_than_32ms` - -* 报警规则： - - `((rate(node_disk_read_time_ms{device=~".+"}[5m]) / rate(node_disk_reads_completed{device=~".+"}[5m])) or (irate(node_disk_read_time_ms{device=~".+"}[5m]) / irate(node_disk_reads_completed{device=~".+"}[5m]))) > 32` - -* 规则描述： - - 磁盘读延迟超过 32 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板观察磁盘的读延迟。 - * 查看 Disk IO Utilization 面板观察 IO 使用率。 - -#### `NODE_disk_write_latency_more_than_16ms` - -* 报警规则： - - `((rate(node_disk_write_time_ms{device=~".+"}[5m]) / rate(node_disk_writes_completed{device=~".+"}[5m])) or (irate(node_disk_write_time_ms{device=~".+"}[5m]) / irate(node_disk_writes_completed{device=~".+"}[5m])))> 16` - -* 规则描述： - - 机器磁盘写延迟超过 16 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板可查看磁盘的写延迟。 - * 查看 Disk IO Utilization 面板可查看 IO 使用率。 - -## Blackbox_exporter TCP、ICMP 和 HTTP 报警规则 - -本节介绍了 Blackbox_exporter TCP、ICMP 和 HTTP 的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_server_is_down` - -* 报警规则： - - `probe_success{group="tidb"} == 0` - -* 规则描述： - - TiDB 服务端口探测失败。 - -* 处理方法： - - * 检查 TiDB 服务所在机器是否宕机。 - * 检查 TiDB 进程是否存在。 - * 检查监控机与 TiDB 服务所在机器之间网络是否正常。 - -#### `Pump_server_is_down` - -* 报警规则： - - `probe_success{group="pump"} == 0` - -* 规则描述： - - Pump 服务端口探测失败。 - -* 处理方法： - - * 检查 Pump 服务所在机器是否宕机。 - * 检查 Pump 进程是否存在。 - * 检查监控机与 Pump 服务所在机器之间网络是否正常。 - -#### `Drainer_server_is_down` - -* 报警规则： - - `probe_success{group="drainer"} == 0` - -* 规则描述： - - Drainer 服务端口探测失败。 - -* 处理方法： - - * 检查 Drainer 服务所在机器是否宕机。 - * 检查 Drainer 进程是否存在。 - * 检查监控机与 Drainer 服务所在机器之间网络是否正常。 - -#### `TiKV_server_is_down` - -* 报警规则： - - `probe_success{group="tikv"} == 0` - -* 规则描述： - - TiKV 服务端口探测失败。 - -* 处理方法： - - * 检查 TiKV 服务所在机器是否宕机。 - * 检查 TiKV 进程是否存在。 - * 检查监控机与 TiKV 服务所在机器之间网络是否正常。 - -#### `PD_server_is_down` - -* 报警规则： - - `probe_success{group="pd"} == 0` - -* 规则描述： - - PD 服务端口探测失败。 - -* 处理方法： - - * 检查 PD 服务所在机器是否宕机。 - * 检查 PD 进程是否存在。 - * 检查监控机与 PD 服务所在机器之间网络是否正常。 - -#### `Node_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="node_exporter"} == 0` - -* 规则描述： - - Node_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Node_exporter 服务所在机器是否宕机。 - * 检查 Node_exporter 进程是否存在。 - * 检查监控机与 Node_exporter 服务所在机器之间网络是否正常。 - -#### `Blackbox_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="blackbox_exporter"} == 0` - -* 规则描述： - - Blackbox_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Blackbox_exporter 服务所在机器是否宕机。 - * 检查 Blackbox_exporter 进程是否存在。 - * 检查监控机与 Blackbox_exporter 服务所在机器之间网络是否正常。 - -#### `Grafana_server_is_down` - -* 报警规则： - - `probe_success{group="grafana"} == 0` - -* 规则描述： - - Grafana 服务端口探测失败。 - -* 处理方法： - - * 检查 Grafana 服务所在机器是否宕机。 - * 检查 Grafana 进程是否存在。 - * 检查监控机与 Grafana 服务所在机器之间网络是否正常。 - -#### `Pushgateway_server_is_down` - -* 报警规则： - - `probe_success{group="pushgateway"} == 0` - -* 规则描述： - - Pushgateway 服务端口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -#### `Kafka_exporter_is_down` - -* 报警规则： - - `probe_success{group="kafka_exporter"} == 0` - -* 规则描述： - - Kafka_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Kafka_exporter 服务所在机器是否宕机。 - * 检查 Kafka_exporter 进程是否存在。 - * 检查监控机与 Kafka_exporter 服务所在机器之间网络是否正常。 - -#### `Pushgateway_metrics_interface` - -* 报警规则： - - `probe_success{job="blackbox_exporter_http"} == 0` - -* 规则描述： - - Pushgateway 服务 http 接口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `BLACKER_ping_latency_more_than_1s` - -* 报警规则： - - `max_over_time(probe_duration_seconds{job=~"blackbox_exporter.*_icmp"}[1m]) > 1` - -* 规则描述： - - Ping 延迟超过 1 秒。 - -* 处理方法： - - * 在 Grafana Blackbox Exporter dashboard 上检查两个节点间的 ping 延迟是否太高。 - * 在 Grafana Blackbox Exporter dashboard 的 tcp 面板上检查是否有丢包。 diff --git a/dev/reference/best-practices/grafana-monitor.md b/dev/reference/best-practices/grafana-monitor.md deleted file mode 100644 index 000c8eab2025..000000000000 --- a/dev/reference/best-practices/grafana-monitor.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 使用 Grafana 监控 TiDB 的最佳实践 -summary: 了解高效利用 Grafana 监控 TiDB 的七个技巧。 -category: reference ---- - -# 使用 Grafana 监控 TiDB 的最佳实践 - -[使用 TiDB Ansible 部署 TiDB 集群](/dev/how-to/deploy/orchestrated/ansible.md)时，会同时部署一套 [Grafana + Prometheus 的监控平台](/dev/how-to/monitor/overview.md)，用于收集和展示 TiDB 集群各个组件和机器的 metric 信息。本文主要介绍使用 TiDB 监控的最佳实践，旨在帮助 TiDB 用户高效利用丰富的 metric 信息来分析 TiDB 的集群状态或进行故障诊断。 - -## 监控架构 - -Prometheus 是一个拥有多维度数据模型和灵活查询语句的时序数据库。Grafana 是一个开源的 metric 分析及可视化系统。 - -![TiDB 监控整体架构](/media/prometheus-in-tidb.png) - -从 TiDB 2.1.3 版本开始，监控采用 pull 的方式，而之前版本采用的是 push 的方式，这是一个非常好的调整，它有以下几个优点： - -- 如果 Prometheus 需要迁移，无需重启整个 TiDB 集群。调整前，因为组件要调整 push 的目标地址，迁移 Prometheus 需要重启整个集群。 -- 支持部署 2 套独立的 Grafana + Prometheus 的监控平台（非 HA），防止监控的单点。方法是使用 ansible 用不同的 ip 各执行一次部署命令。 -- 去掉了 Pushgateway 这个单点组件。 - -## 监控数据的来源与展示 - -TiDB 的 3 个核心组件（TiDB server、TiKV server 和 PD server）可以通过 HTTP 接口来获取 metric 数据。这些 metric 均是从程序代码中上传的，默认端口如下： - -| 组件 | 端口 | -|:------------|:-------| -| TiDB server | 10080 | -| TiKV server | 20181 | -| PD server | 2379 | - -下面以 TiDB server 为例，展示如何通过 HTTP 接口查看一个语句的 QPS 数据： - -{{< copyable "shell-regular" >}} - -```bash -curl http://__tidb_ip__:10080/metrics |grep tidb_executor_statement_total -``` - -``` -# 可以看到实时 QPS 数据，并根据不同 type 对 SQL 语句进行了区分，value 是 counter 类型的累计值（科学计数法）。 -tidb_executor_statement_total{type="Delete"} 520197 -tidb_executor_statement_total{type="Explain"} 1 -tidb_executor_statement_total{type="Insert"} 7.20799402e+08 -tidb_executor_statement_total{type="Select"} 2.64983586e+08 -tidb_executor_statement_total{type="Set"} 2.399075e+06 -tidb_executor_statement_total{type="Show"} 500531 -tidb_executor_statement_total{type="Use"} 466016 -``` - -这些数据会存储在 Prometheus 中，然后在 Grafana 上进行展示。在面板上点击鼠标右键会出现 **Edit** 按钮（或直接按 E 键），如下图所示： - -![Metrics 面板的编辑入口](/media/best-practices/metric-board-edit-entry.png) - -点击 **Edit** 按钮之后，在 Metrics 面板上可以看到利用该 metric 的 query 表达式。面板上一些细节的含义如下： - -- `rate[1m]`：表示 1 分钟的增长速率，只能用于 counter 类型的数据。 -- `sum`：表示 value 求和。 -- `by type`：表示将求和后的数据按 metric 原始值中的 type 进行分组。 -- `Legend format`：表示指标名称的格式。 -- `Resolution`：默认打点步长是 15s，Resolution 表示是否将多个样本数据合并成一个点。 - -Metrics 面板中的表达式如下： - -![Metric 面板中的表达式](/media/best-practices/metric-board-expression.jpeg) - -Prometheus 支持很多表达式与函数，更多表达式请参考 [Prometheus 官网页面](https://prometheus.io/docs/prometheus/latest/querying)。 - -## Grafana 使用技巧 - -本小节介绍高效利用 Grafana 监控分析 TiDB 指标的七个技巧。 - -### 技巧 1：查看所有维度并编辑表达式 - -在[监控数据的来源与展示](#监控数据的来源与展示)一节的示例中，数据是按照 type 进行分组的。如果你想知道是否还能按其它维度分组，并快速查看还有哪些维度，可采用以下技巧：**在 query 的表达式上只保留指标名称，不做任何计算，`Legend format` 也留空**。这样就能显示出原始的 metric 数据。比如，下图能看到有 3 个维度（`instance`、`job` 和 `type`）： - -![编辑表达式并查看所有维度](/media/best-practices/edit-expression-check-dimensions.jpg) - -然后调整表达式，在原有的 `type` 后面加上 `instance` 这个维度，在 `Legend format` 处增加 `{{instance}}`，就可以看到每个 TiDB server 上执行的不同类型 SQL 语句的 QPS 了。如下图所示： - -![给表达式增加一个 instance 维度](/media/best-practices/add-instance-dimension.jpeg) - -### 技巧 2：调整 Y 轴标尺的计算方式 - -以 Query Duration 指标为例，默认的比例尺采用 2 的对数计算，显示上会将差距缩小。为了观察到明显的变化，可以将比例尺改为线性，从下面两张图中可以看到显示上的区别，明显发现那个时刻有个 SQL 语句运行较慢。 - -当然也不是所有场景都适合用线性，比如观察 1 个月的性能趋势，用线性可能就会有很多噪点，不好观察。 - -标尺默认的比例尺为 2 的对数： - -![标尺默认的比例尺为 2 的对数](/media/best-practices/default-axes-scale.jpg) - -将标尺的比例尺调整为线性： - -![调整标尺的比例尺为线性](/media/best-practices/axes-scale-linear.jpg) - -> **建议：** -> -> 结合技巧 1，会发现这里还有一个 `sql_type` 的维度，可以立刻分析出是 `SELECT` 慢还是 `UPDATE` 慢；并且可以分析出是哪个 instance 上的语句慢。 - -### 技巧 3：调整 Y 轴基线，放大变化 - -有时已经用了线性比例尺，却还是看不出变化趋势。比如下图中，在扩容后想观察 `Store size` 的实时变化效果，但由于基数较大，观察不到微弱的变化。这时可以将 Y 轴最小值从 `0` 改为 `auto`，将上部放大。观察下面两张图的区别，可以看出数据已开始迁移了。 - -基线默认为 `0`： - -![基线默认为 0](/media/best-practices/default-y-min.jpeg) - -将基线调整为 `auto`： - -![调整基线为 auto](/media/best-practices/y-min-auto.jpg) - -### 技巧 4：标尺联动 - -在 **Settings** 面板中，有一个 **Graph Tooltip** 设置项，默认使用 **Default**。 - -![图形展示工具](/media/best-practices/graph-tooltip.jpeg) - -下面将图形展示工具分别调整为 **Shared crosshair** 和 **Shared Tooltip** 看看效果。可以看到标尺能联动展示了，方便排查问题时确认 2 个指标的关联性。 - -将图形展示工具调整为 **Shared crosshair**： - -![调整图形展示工具为 Shared crosshair](/media/best-practices/graph-tooltip-shared-crosshair.jpeg) - -将图形展示工具调整为 **Shared Tooltip**： - -![调整图形展示工具为 Shared Tooltip](/media/best-practices/graph-tooltip-shared-tooltip.jpg) - -### 技巧 5：手动输入 `ip:端口号` 查看历史信息 - -PD 的 dashboard 只展示当前 leader 的 metric 信息，而有时想看历史上 PD leader 当时的状况，但是 `instance` 下拉列表中已不存在这个成员了。此时，可以手动输入 `ip:2379` 来查看当时的数据。 - -![查看历史 metric 信息](/media/best-practices/manually-input-check-metric.jpeg) - -### 技巧 6：巧用 `Avg` 函数 - -通常默认图例中只有 `Max` 和 `Current` 函数。当指标波动较大时，可以增加 `Avg` 等其它汇总函数的图例，来看一段时间的整体趋势。 - -增加 `Avg` 等汇总函数： - -![增加 Avg 等汇总函数](/media/best-practices/add-avg-function.jpeg) - -然后查看整体趋势： - -![增加 Avg 函数查看整体趋势](/media/best-practices/add-avg-function-check-trend.jpg) - -### 技巧 7：使用 Prometheus 的 API 接口获得表达式的结果 - -Grafana 通过 Prometheus 的接口获取数据，你也可以用该接口来获取数据，这个用法还可以衍生出许多功能： - -- 自动获取集群规模、状态等信息。 -- 对表达式稍加改动给报表提供数据，如统计每天的 QPS 总量、每天的 QPS 峰值和每天的响应时间。 -- 将重要的指标进行定期健康巡检。 - -Prometheus 的 API 接口如下： - -![Prometheus 的 API 接口](/media/best-practices/prometheus-api-interface.jpg) - -{{< copyable "shell-regular" >}} - -```bash -curl -u user:pass 'http://__grafana_ip__:3000/api/datasources/proxy/1/api/v1/query_range?query=sum(tikv_engine_size_bytes%7Binstancexxxxxxxxx20181%22%7D)%20by%20(instance)&start=1565879269&end=1565882869&step=30' |python -m json.tool -``` - -``` -{ - "data": { - "result": [ - { - "metric": { - "instance": "xxxxxxxxxx:20181" - }, - "values": [ - [ - 1565879269, - "1006046235280" - ], - [ - 1565879299, - "1006057877794" - ], - [ - 1565879329, - "1006021550039" - ], - [ - 1565879359, - "1006021550039" - ], - [ - 1565882869, - "1006132630123" - ] - ] - } - ], - "resultType": "matrix" - }, - "status": "success" -} -``` - -## 总结 - -Grafana + Prometheus 监控平台是一套非常强大的组合工具，用好这套工具可以为分析节省很多时间，提高效率，更重要的是，我们可以更容易发现问题。在运维 TiDB 集群，尤其是数据量大的情况下，这套工具能派上大用场。 diff --git a/dev/reference/best-practices/high-concurrency.md b/dev/reference/best-practices/high-concurrency.md deleted file mode 100644 index aecbb59f5c9b..000000000000 --- a/dev/reference/best-practices/high-concurrency.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: TiDB 高并发写入场景最佳实践 -summary: 了解 TiDB 在高并发写入场景下的最佳实践。 -category: reference ---- - -# TiDB 高并发写入场景最佳实践 - -在 TiDB 的使用过程中，一个典型场景是高并发批量写入数据到 TiDB。本文阐述了该场景中的常见问题，旨在给出一个业务的最佳实践，帮助读者避免因使用 TiDB 不当而影响业务开发。 - -## 目标读者 - -本文假设你已对 TiDB 有一定的了解，推荐先阅读 TiDB 原理相关的三篇文章（[讲存储](https://pingcap.com/blog-cn/tidb-internal-1/)，[说计算](https://pingcap.com/blog-cn/tidb-internal-2/)，[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)），以及 [TiDB Best Practice](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -## 高并发批量插入场景 - -高并发批量插入的场景通常出现在业务系统的批量任务中，例如清算以及结算等业务。此类场景存在以下特点： - -- 数据量大 -- 需要短时间内将历史数据入库 -- 需要短时间内读取大量数据 - -这就对 TiDB 提出了以下挑战： - -- 写入/读取能力是否可以线性水平扩展 -- 随着数据持续大并发写入，数据库性能是否稳定不衰减 - -对于分布式数据库来说，除了本身的基础性能外，最重要的就是充分利用所有节点能力，避免让单个节点成为瓶颈。 - -## TiDB 数据分布原理 - -如果要解决以上挑战，需要从 TiDB 数据切分以及调度的原理开始讲起。这里只作简单说明，详情可参阅[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)。 - -TiDB 以 Region 为单位对数据进行切分，每个 Region 有大小限制（默认 96M）。Region 的切分方式是范围切分。每个 Region 会有多副本，每一组副本，称为一个 Raft Group。每个 Raft Group 中由 Leader 负责执行这块数据的读 & 写（TiDB 即将支持 [Follower-Read](https://zhuanlan.zhihu.com/p/78164196)）。Leader 会自动地被 PD 组件均匀调度在不同的物理节点上，用以均分读写压力。 - -![TiDB 数据概览](/media/best-practices/tidb-data-overview.png) - -只要业务的写入没有 `AUTO_INCREMENT` 的主键，或没有单调递增的索引（即没有业务上的写入热点，更多细节可参阅 [TiDB 正确使用方式](https://zhuanlan.zhihu.com/p/25574778)），从原理上来说，TiDB 依靠这个架构可具备线性扩展的读写能力，并且可以充分利用分布式资源。从这一点看，TiDB 尤其适合高并发批量写入场景的业务。 - -但理论场景和实际情况往往存在不同。以下实例说明了热点是如何产生的。 - -## 热点产生的实例 - -以下为一张示例表： - -```sql -CREATE TABLE IF NOT EXISTS TEST_HOTSPOT( - id BIGINT PRIMARY KEY, - age INT, - user_name VARCHAR(32), - email VARCHAR(128) -) -``` - -这个表的结构非常简单，除了 `id` 为主键以外，没有额外的二级索引。将数据写入该表的语句如下，`id` 通过随机数离散生成： - -{{< copyable "sql" >}} - -```sql -INSERT INTO TEST_HOTSPOT(id, age, user_name, email) values(%v, %v, '%v', '%v'); -``` - -负载是短时间内密集地执行以上写入语句。 - -以上操作看似符合理论场景中的 TiDB 最佳实践，业务上没有热点产生。只要有足够的机器，就可以充分利用 TiDB 的分布式能力。要验证是否真的符合最佳实践，可以在实验环境中进行测试。 - -部署拓扑 2 个 TiDB 节点，3 个 PD 节点，6 个 TiKV 节点。请忽略 QPS，因为测试只是为了阐述原理，并非 benchmark。 - -![QPS1](/media/best-practices/QPS1.png) - -客户端在短时间内发起了“密集”的写入，TiDB 收到的请求是 3K QPS。理论上，压力应该均摊给 6 个 TiKV 节点。但是从 TiKV 节点的 CPU 使用情况上看，存在明显的写入倾斜（tikv - 3 节点是写入热点）： - -![QPS2](/media/best-practices/QPS2.png) - -![QPS3](/media/best-practices/QPS3.png) - -[Raft store CPU](/dev/reference/key-monitoring-metrics/tikv-dashboard.md) 为 `raftstore` 线程的 CPU 使用率，通常代表写入的负载。在这个场景下 tikv-3 为 Raft Leader，tikv-0 和 tikv-1 是 Raft 的 Follower，其他的 TiKV 节点的负载几乎为空。 - -从 PD 的监控中也可以证明热点的产生： - -![QPS4](/media/best-practices/QPS4.png) - -## 热点问题产生的原因 - -以上测试并未达到理论场景中最佳实践，因为刚创建表的时候，这个表在 TiKV 中只会对应为一个 Region，范围是： - -``` -[CommonPrefix + TableID, CommonPrefix + TableID + 1) -``` - -短时间内大量数据会持续写入到同一个 Region 上。 - -![TiKV Region 分裂流程](/media/best-practices/tikv-Region-split.png) - -上图简单描述了这个过程，随着数据持续写入，TiKV 会将一个 Region 切分为多个。但因为首先发起选举的是原 Leader 所在的 Store，所以新切分好的两个 Region 的 Leader 很可能还会在原 Store 上。新切分好的 Region 2，3 上，也会重复之前发生在 Region 1 上的过程。也就是压力会密集地集中在 TiKV-Node 1 上。 - -在持续写入的过程中，PD 发现 Node 1 中产生了热点，会将 Leader 均分到其他的 Node 上。如果 TiKV 的节点数多于副本数的话，TiKV 会尽可能将 Region 迁移到空闲的节点上。这两个操作在数据插入的过程中，也能在 PD 监控中得到印证： - -![QPS5](/media/best-practices/QPS5.png) - -在持续写入一段时间后，整个集群会被 PD 自动地调度成一个压力均匀的状态，到那个时候整个集群的能力才会真正被利用起来。在大多数情况下，以上热点产生的过程是没有问题的，这个阶段属于表 Region 的预热阶段。 - -但是对于高并发批量密集写入场景来说，应该避免这个阶段。 - -## 热点问题的规避方法 - -为了达到场景理论中的最佳性能，可跳过这个预热阶段，直接将 Region 切分为预期的数量，提前调度到集群的各个节点中。 - -TiDB 在 v3.0.x 以及 v2.1.13 后支持一个叫 [Split Region](/dev/reference/sql/statements/split-region.md) 的新特性。这个特性提供了新的语法： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] -``` - -但是 TiDB 并不会自动提前完成这个切分操作。原因如下： - -![Table Region Range](/media/best-practices/table-Region-range.png) - -从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 - -如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 - -作为一款通用数据库，TiDB 并不对数据的分布作假设，所以开始只用一个 Region 来对应一个表。等到真实数据插入进来以后，TiDB 自动根据数据的分布来作切分。这种方式是较通用的。 - -所以 TiDB 提供了 `Split Region` 语法，专门针对短时批量写入场景作优化。基于以上案例，下面尝试用 `Split Region` 语法提前切散 Region，再观察负载情况。 - -由于测试的写入数据在正数范围内完全离散，所以用以下语句，在 Int64 空间内提前将表切分为 128 个 Region： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; -``` - -切分完成以后，可以通过 `SHOW TABLE test_hotspot REGIONS;` 语句查看打散的情况。如果 `SCATTERING` 列值全部为 `0`，代表调度成功。 - -也可以通过 [table-regions.py](https://github.com/pingcap/tidb-ansible/blob/dabf60baba5e740a4bee9faf95e77563d8084be1/scripts/table-regions.py) 脚本，查看 Region 的分布。目前分布已经比较均匀了： - -``` -[root@172.16.4.4 scripts]# python table-regions.py --host 172.16.4.3 --port 31453 test test_hotspot -[RECORD - test.test_hotspot] - Leaders Distribution: - total leader count: 127 - store: 1, num_leaders: 21, percentage: 16.54% - store: 4, num_leaders: 20, percentage: 15.75% - store: 6, num_leaders: 21, percentage: 16.54% - store: 46, num_leaders: 21, percentage: 16.54% - store: 82, num_leaders: 23, percentage: 18.11% - store: 62, num_leaders: 21, percentage: 16.54% -``` - -再重新运行写入负载： - -![QPS6](/media/best-practices/QPS6.png) - -![QPS7](/media/best-practices/QPS7.png) - -![QPS8](/media/best-practices/QPS8.png) - -可以看到已经消除了明显的热点问题了。 - -本示例仅为一个简单的表，还有索引热点的问题需要考虑。读者可参阅 [Split Region](/dev/reference/sql/statements/split-region.md) 文档来了解如何预先切散索引相关的 Region。 - -### 更复杂的热点问题 - -如果表没有主键或者主键不是 Int 类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 - -要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/dev/reference/sql/statements/split-region.md#pre_split_regions)）。 - -`SHARD_ROW_ID_BITS` 用于将 `_tidb_rowid` 列生成的行 ID 随机打散。`pre_split_regions` 用于在建完表后预先进行 Split region。 - -> **注意：** -> -> `pre_split_regions` 必须小于或等于 `shard_row_id_bits`。 - -示例： - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; -``` - -- `SHARD_ROW_ID_BITS = 4` 表示 tidb_rowid 的值会随机分布成 16 （16=2^4） 个范围区间。 -- `pre_split_regions=3` 表示建完表后提前切分出 8 (2^3) 个 Region。 - -开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 - -## 参数配置 - -TiDB 2.1 版本中在 SQL 层引入了 [latch 机制](/dev/reference/configuration/tidb-server/configuration-file.md#txn-local-latches)，用于在写入冲突比较频繁的场景中提前发现事务冲突，减少 TiDB 和 TiKV 事务提交时写写冲突导致的重试。通常，跑批场景使用的是存量数据，所以并不存在事务的写入冲突。可以把 TiDB 的 latch 功能关闭，以减少为细小对象分配内存： - -``` -[txn-local-latches] -enabled = false -``` diff --git a/dev/reference/best-practices/massive-regions.md b/dev/reference/best-practices/massive-regions.md deleted file mode 100644 index a1f389282146..000000000000 --- a/dev/reference/best-practices/massive-regions.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 海量 Region 集群调优最佳实践 -summary: 了解海量 Region 导致性能问题的原因和优化方法。 -category: reference ---- - -# 海量 Region 集群调优最佳实践 - -在 TiDB 的架构中，所有数据以一定 key range 被切分成若干 Region 分布在多个 TiKV 实例上。随着数据的写入，一个集群中会产生上百万个甚至千万个 Region。单个 TiKV 实例上产生过多的 Region 会给集群带来较大的负担，影响整个集群的性能表现。 - -本文将介绍 TiKV 核心模块 Raftstore 的工作流程，海量 Region 导致性能问题的原因，以及优化性能的方法。 - -## Raftstore 的工作流程 - -一个 TiKV 实例上有多个 Region。Region 消息是通过 Raftstore 模块驱动 Raft 状态机来处理的。这些消息包括 Region 上读写请求的处理、Raft log 的持久化和复制、Raft 的心跳处理等。但是，Region 数量增多会影响整个集群的性能。为了解释这一点，需要先了解 TiKV 的核心模块 Raftstore 的工作流程。 - -![图 1 Raftstore 处理流程示意图](/media/best-practices/raft-process.png) - -> **注意：** -> -> 该图仅为示意，不代表代码层面的实际结构。 - -上图是 Raftstore 处理流程的示意图。如图所示，从 TiDB 发来的请求会通过 gRPC 和 storage 模块变成最终的 KV 读写消息，并被发往相应的 Region，而这些消息并不会被立即处理而是被暂存下来。Raftstore 会轮询检查每个 Region 是否有需要处理的消息。如果 Region 有需要处理的消息，那么 Raftstore 会驱动 Raft 状态机去处理这些消息，并根据这些消息所产生的状态变更去进行后续操作。例如，在有写请求时，Raft 状态机需要将日志落盘并且将日志发送给其他 Region 副本；在达到心跳间隔时，Raft 状态机需要将心跳信息发送给其他 Region 副本。 - -## 性能问题 - -从 Raftstore 处理流程示意图可以看出，需要依次处理各个 Region 的消息。那么在 Region 数量较多的情况下，Raftstore 需要花费一些时间去处理大量 Region 的心跳，从而带来一些延迟，导致某些读写请求得不到及时处理。如果读写压力较大，Raftstore 线程的 CPU 使用率容易达到瓶颈，导致延迟进一步增加，进而影响性能表现。 - -通常在有负载的情况下，如果 Raftstore 的 CPU 使用率达到了 85% 以上，即可视为达到繁忙状态且成为了瓶颈，同时 `propose wait duration` 可能会高达百毫秒级别。 - -> **注意：** -> -> + Raftstore 的 CPU 使用率是指单线程的情况。如果是多线程 Raftstore，可等比例放大使用率。 -> + 由于 Raftstore 线程中有 I/O 操作，所以 CPU 使用率不可能达到 100%。 - -### 性能监控 - -可在 Grafana 的 TiKV 面板下查看相关的监控 metrics： - -+ Thread-CPU 下的 `Raft store CPU` - - 参考值：低于 `raftstore.store-pool-size * 85%`。在 v2.1 版本中无此配置项，因此在 v2.1 中可视为 `raftstore.store-pool-size = 1`。 - - ![图 2 查看 Raftstore CPU](/media/best-practices/raft-store-cpu.png) - -+ Raft Propose 下的 `Propose wait duration` - - `Propose wait duration` 是从发送请求给 Raftstore，到 Raftstore 真正开始处理请求之间的延迟时间。如果该延迟时间较长，说明 Raftstore 比较繁忙或者处理 append log 比较耗时导致 Raftstore 不能及时处理请求。 - - 参考值：低于 50-100ms。 - - ![图 3 查看 Propose wait duration](/media/best-practices/propose-wait-duration.png) - -## 性能优化方法 - -找到性能问题的根源后，可从以下两个方向来解决性能问题： - -+ 减少单个 TiKV 实例的 Region 数 -+ 减少单个 Region 的消息数 - -### 方法一：增加 TiKV 实例 - -如果 I/O 资源和 CPU 资源都比较充足，可在单台机器上部署多个 TiKV 实例，以减少单个 TiKV 实例上的 Region 个数；或者增加 TiKV 集群的机器数。 - -### 方法二：调整 `raft-base-tick-interval` - -除了减少 Region 个数外，还可以通过减少 Region 单位时间内的消息数量来减小 Raftstore 的压力。例如，在 TiKV 配置中适当调大 `raft-base-tick-interval`： - -{{< copyable "" >}} - -``` -[raftstore] -raft-base-tick-interval = "2s" -``` - -`raft-base-tick-interval` 是 Raftstore 驱动每个 Region 的 Raft 状态机的时间间隔，也就是每隔该时长就需要向 Raft 状态机发送一个 tick 消息。增加该时间间隔，可以有效减少 Raftstore 的消息数量。 - -需要注意的是，该 tick 消息的间隔也决定了 `election timeout` 和 `heartbeat` 的间隔。示例如下： - -{{< copyable "" >}} - -``` -raft-election-timeout = raft-base-tick-interval * raft-election-timeout-ticks -raft-heartbeat-interval = raft-base-tick-interval * raft-heartbeat-ticks -``` - -如果 Region Follower 在 `raft-election-timeout` 间隔内未收到来自 Leader 的心跳，就会判断 Leader 出现故障而发起新的选举。`raft-heartbeat-interval` 是 Leader 向 Follower 发送心跳的间隔，因此调大 `raft-base-tick-interval` 可以减少单位时间内 Raft 发送的网络消息，但也会让 Raft 检测到 Leader 故障的时间更长。 - -### 方法三：提高 Raftstore 并发数 - -v3.0 版本中的 Raftstore 已经扩展为多线程，极大降低了 Raftstore 线程成为瓶颈的可能性。 - -TiKV 默认将 `raftstore.store-pool-size` 配置为 `2`。如果 Raftstore 出现瓶颈，可以根据实际情况适当调高该参数值，但不建议设置过高以免引入不必要的线程切换开销。 - -### 方法四：开启 Hibernate Region 功能 - -在实际情况中，读写请求并不会均匀分布到每个 Region 上，而是集中在少数的 Region 上。那么可以尽量减少暂时空闲的 Region 的消息数量，这也就是 Hibernate Region 的功能。无必要时可不进行 `raft-base-tick`，即不驱动空闲 Region 的 Raft 状态机，那么就不会触发这些 Region 的 Raft 产生心跳信息，极大地减小了 Raftstore 的工作负担。 - -截至 TiDB v3.0.5，Hibernate Region 仍是一个实验功能，在 [TiKV master](https://github.com/tikv/tikv/tree/master) 分支上已经默认开启。可根据实际情况和需求来开启该功能。Hibernate Region 的配置说明请参考[配置 Hibernate Region](https://github.com/tikv/tikv/blob/master/docs/reference/configuration/raftstore-config.md#hibernate-region)。 - -### 方法五：开启 `Region Merge` - -> **注意：** -> -> `Region Merge` 已在 TiDB v3.0 中默认开启。 - -开启 `Region Merge` 也能减少 Region 的个数。与 `Region Split` 相反，`Region Merge` 是通过调度把相邻的小 Region 合并的过程。在集群中删除数据或者执行 `Drop Table`/`Truncate Table` 语句后，可以将小 Region 甚至空 Region 进行合并以减少资源的消耗。 - -通过 pd-ctl 设置以下参数即可开启 `Region Merge`： - -{{< copyable "" >}} - -``` ->> pd-ctl config set max-merge-region-size 20 ->> pd-ctl config set max-merge-region-keys 200000 ->> pd-ctl config set merge-schedule-limit 8 -``` - -详情请参考[如何配置 Region Merge](https://github.com/tikv/tikv/blob/master/docs/how-to/configure/region-merge.md) 和 [PD 配置文件描述](/dev/reference/configuration/pd-server/configuration-file.md#schedule)。 - -同时，默认配置的 `Region Merge` 的参数设置较为保守，可以根据需求参考 [PD 调度策略最佳实践](/dev/reference/best-practices/pd-scheduling.md#region-merge-速度慢) 中提供的方法加快 `Region Merge` 过程的速度。 - -## 其他问题和解决方案 - -### 切换 PD Leader 的速度慢 - -PD 需要将 Region Meta 信息持久化在 etcd 上，以保证切换 PD Leader 节点后 PD 能快速继续提供 Region 路由服务。随着 Region 数量的增加，etcd 出现性能问题，使得 PD 在切换 Leader 时从 etcd 获取 Region Meta 信息的速度较慢。在百万 Region 量级时，从 etcd 获取信息的时间可能需要十几秒甚至几十秒。 - -因此在 v3.0 版本中，PD 默认开启配置项 `use-region-storage`，将 Region Meta 信息存在本地的 LevelDB 中，并通过其他机制同步 PD 节点间的信息。 - -### PD 路由信息更新不及时 - -在 TiKV 中，pd-worker 模块将 Region Meta 信息定期上报给 PD，在 TiKV 重启或者切换 Region Leader 时需要通过统计信息重新计算 Region 的 `approximate size/keys`。因此在 Region 数量较多的情况下，pd-worker 单线程可能成为瓶颈，造成任务得不到及时处理而堆积起来。因此 PD 不能及时获取某些 Region Meta 信息以致路由信息更新不及时。该问题不会影响实际的读写，但可能导致 PD 调度不准确以及 TiDB 更新 Region cache 时需要多几次 round-trip。 - -可在 TiKV Grafana 面板中查看 Task 下的 Worker pending tasks 来确定 pd-worker 是否有任务堆积。通常来说，pending tasks 应该维持在一个比较低的值。 - -![图 4 查看 pd-worker](/media/best-practices/pd-worker-metrics.png) - -目前已经在 [TiKV master](https://github.com/tikv/tikv/tree/master) 上对 pd-worker 进行了[效率优化](https://github.com/tikv/tikv/pull/5620)。[TiDB v3.0.5](https://pingcap.com/docs-cn/stable/releases/3.0.5/) 中已带上该优化。如果碰到类似问题，建议升级至 v3.0.5。 - -### Prometheus 查询 metrics 的速度慢 - -在大规模集群中，随着 TiKV 实例数的增加，Prometheus 查询 metrics 时的计算压力较大，导致 Grafana 查看 metrics 的速度较慢。v3.0 版本中设置了一些 metrics 的预计算，让这个问题有所缓解。 diff --git a/dev/reference/best-practices/pd-scheduling.md b/dev/reference/best-practices/pd-scheduling.md deleted file mode 100644 index 7f7b44cac97b..000000000000 --- a/dev/reference/best-practices/pd-scheduling.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: PD 调度策略最佳实践 -summary: 了解 PD 调度策略的最佳实践和调优方式 -category: reference ---- - -# PD 调度策略最佳实践 - -本文将详细介绍 PD 调度系统的原理，并通过几个典型场景的分析和处理方式，分享调度策略的最佳实践和调优方式，帮助大家在使用过程中快速定位问题。本文假定你对 TiDB，TiKV 以及 PD 已经有一定的了解，相关核心概念如下： - -- [Leader/Follower/Learner](/dev/glossary.md#leaderfollowerlearner) -- [Operator](/dev/glossary.md#operator) -- [Operator Step](/dev/glossary.md#operator-step) -- [Pending/Down](/dev/glossary.md#pendingdown) -- [Region/Peer/Raft Group](/dev/glossary.md#regionpeerraft-group) -- [Region Split](/dev/glossary.md#region-split) -- [Scheduler](/dev/glossary.md#scheduler) -- [Store](/dev/glossary.md#store) - -> **注意：** -> -> 本文内容基于 TiDB 3.0 版本，更早的版本（2.x）缺少部分功能的支持，但是基本原理类似，也可以以本文作为参考。 - -## PD 调度原理 - -该部分介绍调度系统涉及到的相关原理和流程。 - -### 调度流程 - -宏观上来看，调度流程大体可划分为 3 个部分： - -1. 信息收集 - - TiKV 节点周期性地向 PD 上报 `StoreHeartbeat` 和 `RegionHeartbeat` 两种心跳消息： - - * `StoreHeartbeat` 包含 Store 的基本信息、容量、剩余空间和读写流量等数据。 - * `RegionHeartbeat` 包含 Region 的范围、副本分布、副本状态、数据量和读写流量等数据。 - - PD 梳理并转存这些信息供调度进行决策。 - -2. 生成调度 - - 不同的调度器从自身的逻辑和需求出发，考虑各种限制和约束后生成待执行的 Operator。这里所说的限制和约束包括但不限于： - - - 不往断连中、下线中、繁忙、空间不足、在大量收发 snapshot 等各种异常状态的 Store 添加副本 - - Balance 时不选择状态异常的 Region - - 不尝试把 Leader 转移给 Pending Peer - - 不尝试直接移除 Leader - - 不破坏 Region 各种副本的物理隔离 - - 不破坏 Label property 等约束 - -3. 执行调度 - - 调度执行的步骤为： - - a. Operator 先进入一个由 `OperatorController` 管理的等待队列。 - - b. `OperatorController` 会根据配置以一定的并发量从等待队列中取出 Operator 并执行。执行的过程就是依次把每个 Operator Step 下发给对应 Region 的 Leader。 - - c. 标记 Operator 为 “finish” 或 “timeout” 状态，然后从执行列表中移除。 - -### 负载均衡 - -Region 负载均衡调度主要依赖 `balance-leader` 和 `balance-region` 两个调度器。二者的调度目标是将 Region 均匀地分散在集群中的所有 Store 上，但它们各有侧重：`balance-leader` 关注 Region 的 Leader，目的是分散处理客户端请求的压力；`balance-region` 关注 Region 的各个 Peer，目的是分散存储的压力，同时避免出现爆盘等状况。 - -`balance-leader` 与 `balance-region` 有着相似的调度流程： - -1. 根据不同 Store 的对应资源量的情况分别打分。 -2. 不断从得分较高的 Store 选择 Leader 或 Peer 迁移到得分较低的 Store 上。 - -两者的分数计算上也有一定差异：`balance-leader` 比较简单，使用 Store 上所有 Leader 所对应的 Region Size 加和作为得分。因为不同节点存储容量可能不一致，计算 `balance-region` 得分会分以下三种情况： - -- 当空间富余时使用数据量计算得分（使不同节点数据量基本上均衡） -- 当空间不足时由使用剩余空间计算得分（使不同节点剩余空间基本均衡） -- 处于中间态时则同时考虑两个因素做加权和当作得分 - -此外，为了应对不同节点可能在性能等方面存在差异的问题，还可为 Store 设置负载均衡的权重。`leader-weight` 和 `region-weight` 分别用于控制 Leader 权重以及 Region 权重（默认值都为 “1”）。假如把某个 Store 的 `leader-weight` 设为 “2”，调度稳定后，则该节点的 Leader 数量约为普通节点的 2 倍；假如把某个 Store 的 `region-weight` 设为 “0.5”，那么调度稳定后该节点的 Region 数量约为其他节点的一半。 - -### 热点调度 - -热点调度对应的调度器是 `hot-region-scheduler`。在 3.0 版本中，统计热点 Region 的方式为： - -1. 根据 Store 上报的信息，统计出持续一段时间读或写流量超过一定阈值的 Region。 -2. 用与负载均衡类似的方式把这些 Region 分散开来。 - -对于写热点，热点调度会同时尝试打散热点 Region 的 Peer 和 Leader；对于读热点，由于只有 Leader 承载读压力，热点调度会尝试将热点 Region 的 Leader 打散。 - -### 集群拓扑感知 - -让 PD 感知不同节点分布的拓扑是为了通过调度使不同 Region 的各个副本尽可能分散，保证高可用和容灾。PD 会在后台不断扫描所有 Region，当发现 Region 的分布不是当前的最优化状态时，会生成调度以替换 Peer，将 Region 调整至最佳状态。 - -负责这个检查的组件叫 `replicaChecker`（跟 Scheduler 类似，但是不可关闭）。它依赖于 `location-labels` 配置项来进行调度。比如配置 `[zone,rack,host]` 定义了三层的拓扑结构：集群分为多个 zone（可用区），每个 zone 下有多个 rack（机架），每个 rack 下有多个 host（主机）。PD 在调度时首先会尝试将 Region 的 Peer 放置在不同的 zone，假如无法满足（比如配置 3 副本但总共只有 2 个 zone）则保证放置在不同的 rack；假如 rack 的数量也不足以保证隔离，那么再尝试 host 级别的隔离，以此类推。 - -### 缩容及故障恢复 - -缩容是指预备将某个 Store 下线，通过命令将该 Store 标记为 “Offline“ 状态，此时 PD 通过调度将待下线节点上的 Region 迁移至其他节点。 - -故障恢复是指当有 Store 发生故障且无法恢复时，有 Peer 分布在对应 Store 上的 Region 会产生缺少副本的状况，此时 PD 需要在其他节点上为这些 Region 补副本。 - -这两种情况的处理过程基本上是一样的。`replicaChecker` 检查到 Region 存在异常状态的 Peer后，生成调度在健康的 Store 上创建新副本替换异常的副本。 - -### Region merge - -Region merge 指的是为了避免删除数据后大量小甚至空的 Region 消耗系统资源，通过调度把相邻的小 Region 合并的过程。Region merge 由 `mergeChecker` 负责，其过程与 `replicaChecker` 类似：PD 在后台遍历，发现连续的小 Region 后发起调度。 - -## 查询调度状态 - -你可以通过观察 PD 相关的 Metrics 或使用 pd-ctl 工具等方式查看调度系统状态。更具体的信息可以参考 [PD 监控](/dev/reference/key-monitoring-metrics/pd-dashboard.md)和 [PD Control](/dev/reference/tools/pd-control.md)。 - -### Operator 状态 - -**Grafana PD/Operator** 页面展示了 Operator 的相关统计信息。其中比较重要的有： - -- Schedule Operator Create：Operator 的创建情况 -- Operator finish duration：Operator 执行耗时的情况 -- Operator Step duration：不同 Operator Step 执行耗时的情况 - -查询 Operator 的 pd-ctl 命令有： - -- `operator show`：查询当前调度生成的所有 Operator -- `operator show [admin | leader | region]`：按照类型查询 Operator - -### Balance 状态 - -**Grafana PD/Statistics - Balance** 页面展示了负载均衡的相关统计信息，其中比较重要的有： - -- Store Leader/Region score：每个 Store 的得分 -- Store Leader/Region count：每个 Store 的 Leader/Region 数量 -- Store available：每个 Store 的剩余空间 - -使用 pd-ctl 的 `store` 命令可以查询 Store 的得分、数量、剩余空间和 weight 等信息。 - -### 热点调度状态 - -**Grafana PD/Statistics - hotspot** 页面展示了热点 Region 的相关统计信息，其中比较重要的有： - -- Hot write Region’s leader/peer distribution：写热点 Region 的 Leader/Peer 分布情况 -- Hot read Region’s leader distribution：读热点 Region 的 Leader 分布情况 - -使用 pd-ctl 同样可以查询上述信息，可以使用的命令有： - -- `hot read`：查询读热点 Region 信息 -- `hot write`：查询写热点 Region 信息 -- `hot store`：按 Store 统计热点分布情况 -- `region topread [limit]`：查询当前读流量最大的 Region -- `region topwrite [limit]`：查询当前写流量最大的 Region - -### Region 健康度 - -**Grafana PD/Cluster/Region health** 面板展示了异常 Region 的相关统计信息，包括 Pending Peer、Down Peer、Offline Peer，以及副本数过多或过少的 Region。 - -通过 pd-ctl 的 `region check` 命令可以查看具体异常的 Region 列表： - -- `region check miss-peer`：缺副本的 Region -- `region check extra-peer`：多副本的 Region -- `region check down-peer`：有副本状态为 Down 的 Region -- `region check pending-peer`：有副本状态为 Pending 的 Region - -## 调度策略控制 - -使用 pd-ctl 可以从以下三个方面来调整 PD 的调度策略。更具体的信息可以参考 [PD Control](/dev/reference/tools/pd-control.md)。 - -### 启停调度器 - -pd-ctl 支持动态创建和删除 Scheduler，你可以通过这些操作来控制 PD 的调度行为，如： - -- `scheduler show`：显示当前系统中的 Scheduler -- `scheduler remove balance-leader-scheduler`：删除（停用）balance region 调度器 -- `scheduler add evict-leader-scheduler-1`：添加移除 Store 1 的所有 Leader 的调度器 - -### 手动添加 Operator - -PD 支持直接通过 pd-ctl 来创建或删除 Operator，如： - -- `operator add add-peer 2 5`：在 Store 5 上为 Region 2 添加 Peer -- `operator add transfer-leader 2 5`：将 Region 2 的 Leader 迁移至 Store 5 -- `operator add split-region 2`：将 Region 2 拆分为 2 个大小相当的 Region -- `operator remove 2`：取消 Region 2 当前待执行的 Operator - -### 调度参数调整 - -使用 pd-ctl 执行 `config show` 命令可以查看所有的调度参数，执行 `config set {key} {value}` 可以调整对应参数的值。常见调整如下： - -- `leader-schedule-limit`：控制 Transfer Leader 调度的并发数 -- `region-schedule-limit`：控制增删 Peer 调度的并发数 -- `disable-replace-offline-replica`：停止处理节点下线的调度 -- `disable-location-replacement`：停止处理调整 Region 隔离级别相关的调度 -- `max-snapshot-count`：每个 Store 允许的最大收发 Snapshot 的并发数 - -## 典型场景分析与处理 - -该部分通过几个典型场景及其应对方式说明 PD 调度策略的最佳实践。 - -### Leader/Region 分布不均衡 - -PD 的打分机制决定了一般情况下，不同 Store 的 Leader Count 和 Region Count 不能完全说明负载均衡状态，所以需要从 TiKV 的实际负载或者存储空间占用来判断是否有负载不均衡的状况。 - -确认 Leader/Region 分布不均衡后，首先观察不同 Store 的打分情况。 - -如果不同 Store 的打分是接近的，说明 PD 认为此时已经是均衡状态了，可能的原因有： - -- 存在热点导致负载不均衡。可以参考[热点分布不均匀](#热点分布不均匀)中的解决办法进行分析处理。 -- 存在大量空 Region 或小 Region，因此不同 Store 的 Leader 数量差别特别大，导致 Raftstore 负担过重。此时需要开启 [Region Merge](#region-merge) 并尽可能加速合并。 -- 不同 Store 的软硬件环境存在差异。可以酌情调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 -- 其他不明原因。仍可以通过调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 - -如果不同 Store 的分数差异较大，需要进一步检查 Operator 的相关 Metrics，特别关注 Operator 的生成和执行情况，这时大体上又分两种情况： - -- 生成的调度是正常的，但是调度的速度很慢。可能的原因有： - - - 调度速度受限于 limit 配置。PD 默认配置的 limit 比较保守，在不对正常业务造成显著影响的前提下，可以酌情将 `leader-schedule-limit` 或 `region-schedule-limit` 调大一些。此外， `max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 - - 系统中同时运行有其他的调度任务产生竞争，导致 balance 速度上不去。这种情况下如果 balance 调度的优先级更高，可以先停掉其他的调度或者限制其他调度的速度。例如 Region 没均衡的情况下做下线节点操作，下线的调度与 Region Balance 会抢占 `region-schedule-limit` 配额，此时你可以调小 `replica-schedule-limit` 以限制下线调度的速度，或者设置 `disable-replace-offline-replica = true` 来暂时关闭下线流程。 - - 调度执行得太慢。可以通过 **Operator step duration** 进行判断。通常不涉及到收发 Snapshot 的 Step（比如 `TransferLeader`，`RemovePeer`，`PromoteLearner` 等）的完成时间应该在毫秒级，涉及到 Snapshot 的 Step（如 `AddLearner`，`AddPeer` 等）的完成时间为数十秒。如果耗时明显过高，可能是 TiKV 压力过大或者网络等方面的瓶颈导致的，需要具体情况具体分析。 - -- 没能生成对应的 balance 调度。可能的原因有： - - - 调度器未被启用。比如对应的 Scheduler 被删除了，或者 limit 被设置为 “0”。 - - 由于其他约束无法进行调度。比如系统中有 `evict-leader-scheduler`，此时无法把 Leader 迁移至对应的 Store。再比如设置了 Label property，也会导致部分 Store 不接受 Leader。 - - 集群拓扑的限制导致无法均衡。比如 3 副本 3 数据中心的集群，由于副本隔离的限制，每个 Region 的 3 个副本都分别分布在不同的数据中心，假如这 3 个数据中心的 Store 数不一样，最后调度就会收敛在每个数据中心均衡，但是全局不均衡的状态。 - -### 节点下线速度慢 - -这个场景需要从 Operator 相关的 Metrics 入手，分析 Operator 的生成执行情况。 - -如果调度在正常生成，只是速度很慢，可能的原因有： - -- 调度速度受限于 limit 配置。可以适当调大 `replica-schedule-limit`，`max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 -- 系统中同时运行有其他的调度任务产生竞争。处理方法参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡)。 -- 下线单个节点时，由于待操作的 Region 有很大一部分（3 副本配置下约 1/3）的 Leader 都集中在下线的节点上，下线速度会受限于这个单点生成 Snapshot 的速度。你可以通过手动给该节点添加一个 `evict-leader-scheduler` 调度器迁走 Leader 来加速。 - -如果没有对应的 Operator 调度生成，可能的原因有： - -- 下线调度被关闭，或者 `replica-schedule-limit` 被设为 “0”。 -- 找不到节点来转移 Region。例如相同 Label 的替代节点可用容量都不足 20%，PD 为了避免爆盘的风险会停止调度。这种情况需要添加更多节点，或者删除一些数据释放空间。 - -### 节点上线速度慢 - -目前 PD 没有对节点上线特殊处理。节点上线实际上是依靠 balance region 机制来调度的，所以参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡) 中的排查步骤即可。 - -### 热点分布不均匀 - -热点调度的问题大体上可以分为以下几种情况： - -- 从 PD 的 Metrics 能看出来有不少 hot Region，但是调度速度跟不上，不能及时地把热点 Region 分散开来。 - - **解决方法**：调大 `hot-region-schedule-limit` 并减少其他调度器的 limit 配额，从而加快热点调度的速度。还可调小 `hot-region-cache-hits-threshold` 使 PD 对更快响应流量的变化。 - -- 单一 Region 形成热点，比如大量请求频繁 scan 一个小表，这个可以从业务角度或者 Metrics 统计的热点信息看出来。由于单 Region 热点现阶段无法使用打散的手段来消除，需要确认热点 Region 后手动添加 `split-region` 调度将这样的 Region 拆开。 - -- 从 PD 的统计来看没有热点，但是从 TiKV 的相关 Metrics 可以看出部分节点负载明显高于其他节点，成为整个系统的瓶颈。这是因为目前 PD 统计热点 Region 的维度比较单一，仅针对流量进行分析，在某些场景下无法准确定位热点。例如部分 Region 有大量的点查请求，从流量上来看并不显著，但是过高的 QPS 导致关键模块达到瓶颈。 - - **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) 文档。 - -### Region Merge 速度慢 - -Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-schedule-limit` 及 `region-schedule-limit`），或者是与其他调度器产生了竞争。具体来说，可有如下处理方式： - -- 假如已经从相关 Metrics 得知系统中有大量的空 Region，这时可以通过把 `max-merge-region-size` 和 `max-merge-region-keys` 调整为较小值来加快 Merge 速度。这是因为 Merge 的过程涉及到副本迁移，所以 Merge 的 Region 越小，速度就越快。如果生成 Merge Operator 的速度很快，想进一步加快 Region Merge 过程，还可以把 `patrol-region-interval` 调整为 "10ms" ，这个能加快巡检 Region 的速度，但是会消耗更多的 CPU 资源。 - -- 创建过大量 Table 后（包括执行 `Truncate Table` 操作）又清空了。此时如果开启了 split table 特性，这些空 Region 是无法合并的，此时需要调整以下参数关闭这个特性： - - - TiKV: `split-region-on-table` 设为 false - - PD: `namespace-classifier` 设为 “” - -- 对于 3.0.4 和 2.1.16 以前的版本，Region 中 Key 的个数（`approximate_keys`）在特定情况下（大部分发生在删表之后）统计不准确，造成 keys 的统计值很大，无法满足 `max-merge-region-keys` 的约束。你可以通过调大 `max-merge-region-keys` 来避免这个问题。 - -### TiKV 节点故障处理策略 - -没有人工介入时，PD 处理 TiKV 节点故障的默认行为是，等待半小时之后（可通过 `max-store-down-time` 配置调整），将此节点设置为 Down 状态，并开始为涉及到的 Region 补充副本。 - -实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 diff --git a/dev/reference/configuration/pd-server/configuration-file.md b/dev/reference/configuration/pd-server/configuration-file.md deleted file mode 100644 index 0d2f96488086..000000000000 --- a/dev/reference/configuration/pd-server/configuration-file.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: PD 配置文件描述 -category: reference ---- - -# PD 配置文件描述 - - - -PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/config.toml](https://github.com/pingcap/pd/blob/master/conf/config.toml) 找到默认的配置文件。 - -本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [PD 配置参数](/dev/reference/configuration/pd-server/configuration.md)。 - -### `lease` - -+ PD Leader Key 租约超时时间，超时系统重新选举 Leader。 -+ 默认：3 -+ 单位：秒 - -### `tso-save-interval` - -+ TSO 分配的时间窗口,实时持久存储。 -+ 默认：3s - -### `initial-cluster-state` - -+ 集群初始状态 -+ 默认：new - -### `enable-prevote` - -+ 开启 raft prevote 的开关。 -+ 默认：true - -### `quota-backend-bytes` - -+ 元信息数据库存储空间的大小，默认 2GB。 -+ 默认：2147483648 - -### `auto-compaction-mod` - -+ 元信息数据库自动压缩的模式，可选项为 periodic（按周期），revision（按版本数）。 -+ 默认：periodic - -### `auto-compaction-retention` - -+ compaction-mode 为 periodic 时为元信息数据库自动压缩的间隔时间；compaction-mode 设置为 revision 时为自动压缩的版本数。 -+ 默认：1h - -### `force-new-cluster` - -+ 强制让该 PD 以一个新集群启动，且修改 raft 成员数为 1。 -+ 默认：false - -### `tick-interval` - -+ etcd raft 的 tick 周期。 -+ 默认：100ms - -### `election-interval` - -+ etcd leader 选举的超时时间。 -+ 默认：3s - -### `use-region-storage` - -+ 开启独立的 region 存储。 -+ 默认：false - -## security - -安全相关配置项。 - -### `cacert-path` - -+ CA 文件路径 -+ 默认："" - -### `cert-path` - -+ 包含 X509 证书的 PEM 文件路径 -+ 默认："" - -### `key-path` - -+ 包含 X509 key 的 PEM 文件路径 -+ 默认："" - -## log - -日志相关的配置项。 - -### `format` - -+ 日志格式，可指定为"text"，"json"， "console"。 -+ 默认：text - -### `disable-timestamp` - -+ 是否禁用日志中自动生成的时间戳。 -+ 默认：false - -## log.file - -日志文件相关的配置项。 - -### `max-size` - -+ 单个日志文件最大大小，超过该值系统自动切分成多个文件。 -+ 默认：300 -+ 单位：MiB -+ 最小值为 1 - -### `max-days` - -+ 日志保留的最长天数。 -+ 默认: 28 -+ 最小值为 1 - -### `max-backups` - -+ 日志文件保留的最大个数。 -+ 默认: 7 -+ 最小值为 1 - -## metric - -监控相关的配置项。 - -### `interval` - -+ 向 promethus 推送监控指标数据的间隔时间。 -+ 默认: 15s - -## schedule - -调度相关的配置项。 - -### `max-merge-region-size` - -+ 控制 Region Merge 的 size 上限，当 Region Size 大于指定值时 PD 不会将其与相邻的 Region 合并。 -+ 默认: 20 - -### `max-merge-region-keys` - -+ 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 -+ 默认: 200000 - -### `patrol-region-interval` - -+ 控制 replicaChecker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整 -+ 默认: 100ms - -### `split-merge-interval` - -+ 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。 -+ 默认: 1h - -### `max-snapshot-count` - -+ 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。 -+ 默认: 3 - -### `max-pending-peer-count` - -+ 控制单个 store 的 pending peer 上限，调度受制于这个配置来防止在部分节点产生大量日志落后的 Region。 -+ 默认：16 - -### `max-store-down-time` - -+ PD 认为失联 store 无法恢复的时间，当超过指定的时间没有收到 store 的心跳后，PD 会在其他节点补充副本。 -+ 默认：30m - -### `leader-schedule-limit` - -+ 同时进行 leader 调度的任务个数。 -+ 默认：4 - -### `region-schedule-limit` - -+ 同时进行 Region 调度的任务个数 -+ 默认：4 - -### `replica-schedule-limit` - -+ 同时进行 replica 调度的任务个数。 -+ 默认：8 - -### `merge-schedule-limit` - -+ 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 -+ 默认：8 - -### `high-space-ratio` - -+ 设置 store 空间充裕的阈值。 -+ 默认：0.6 -+ 最小值：大于 0 -+ 最大值：小于 1 - -### `low-space-ratio` - -+ 设置 store 空间不足的阈值。 -+ 默认：0.8 -+ 最小值：大于 0 -+ 最大值：小于 1 - -### `tolerant-size-ratio` - -+ 控制 balance 缓冲区大小。 -+ 默认：5 -+ 最小值：0 - -### `disable-remove-down-replica` - -+ 关闭自动删除 DownReplica 的特性的开关，当设置为 true 时，PD 不会自动清理宕机状态的副本。 -+ 默认：false - -### `disable-replace-offline-replica` - -+ 关闭迁移 OfflineReplica 的特性的开关，当设置为 true 时，PD 不会迁移下线状态的副本。 -+ 默认：false - -### `disable-make-up-replica` - -+ 关闭补充副本的特性的开关，当设置为 true 时，PD 不会为副本数不足的 Region 补充副本。 -+ 默认：false - -### `disable-remove-extra-replica` - -+ 关闭删除多余副本的特性开关，当设置为 true 时，PD 不会为副本数过多的 Region 删除多余副本。 -+ 默认：false - -### `disable-location-replacement` - -+ 关闭隔离级别检查的开关，当设置为 true 时，PD 不会通过调度来提升 Region 副本的隔离级别。 -+ 默认：false - -## replication - -副本相关的配置项。 - -### `max-replicas` - -+ 副本数量。 -+ 默认：3 - -### `location-labels` - -+ TiKV 集群的拓扑信息。 -+ 默认：[] - -## label-property - -标签相关的配置项。 - -### `key` - -+ 拒绝 leader 的 store 带有的 label key。 -+ 默认："" - -### `value` - -+ 拒绝 leader 的 store 带有的 label value。 -+ 默认："" diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md deleted file mode 100644 index 73a81a629ca6..000000000000 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ /dev/null @@ -1,444 +0,0 @@ ---- -title: TiDB 配置文件描述 -category: reference ---- - - - -# TiDB 配置文件描述 - -TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/config.toml.example](https://github.com/pingcap/tidb/blob/master/config/config.toml.example) 找到默认值的配置文件，重命名为 `config.toml` 即可。本文档只介绍未包含在[命令行参数](https://pingcap.com/docs-cn/dev/reference/configuration/tidb-server/configuration)中的参数。 - -### `split-table` - -+ 为每个 table 建立单独的 Region。 -+ 默认值：true -+ 如果需要创建大量的表，我们建议把这个参数设置为 false。 - -### `oom-action` - -+ 指定 TiDB 发生 out-of-memory 错误时的操作。 -+ 默认值："log" -+ 现在合法的选项是 ["log", "cancel"]，如果为 "log"，仅仅是打印日志，不作实质处理。如果为 "cancel"，我们会取消执行这个操作，并且输出日志。 - -### `mem-quota-query` - -+ 单条 SQL 语句可以占用的最大内存阈值。 -+ 默认值：34359738368 -+ 超过该值的请求会被 `oom-action` 定义的行为所处理。 - -### `enable-streaming` - -+ 开启 coprocessor 的 streaming 获取数据模式。 -+ 默认值：false - -### `lower-case-table-names` - -+ 这个选项可以设置 TiDB 的系统变量 `lower_case_table_names` 的值。 -+ 默认值：2 -+ 具体可以查看 MySQL 关于这个变量的[描述](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_lower_case_table_names) - -> **注意：** -> -> 目前 TiDB 只支持将该选项的值设为 2，即按照大小写来保存表名，按照小写来比较（不区分大小写）。 - -### `lease` - -+ DDL 租约超时时间。 -+ 默认值：45s -+ 单位：秒 - -### `compatible-kill-query` - -+ 设置 `KILL` 语句的兼容性。 -+ 默认值：false -+ TiDB 中 `KILL xxx` 的行为和 MySQL 中的行为不相同。为杀死一条查询，在 TiDB 里需要加上 `TIDB` 关键词，即 `KILL TIDB xxx`。但如果把 `compatible-kill-query` 设置为 true，则不需要加上 `TIDB` 关键词。 -+ 这种区别很重要，因为当用户按下 Ctrl+C 时，MySQL 命令行客户端的默认行为是：创建与后台的新连接，并在该新连接中执行 `KILL` 语句。如果负载均衡器或代理已将该新连接发送到与原始会话不同的 TiDB 服务器实例，则该错误会话可能被终止，从而导致使用 TiDB 集群的业务中断。只有当您确定在 `KILL` 语句中引用的连接正好位于 `KILL` 语句发送到的服务器上时，才可以启用 `compatible-kill-query`。 - -### `check-mb4-value-in-utf8` - -+ 开启检查 utf8mb4 字符的开关，如果开启此功能，字符集是 utf8，且在 utf8 插入 mb4 字符，系统将会报错。 -+ 默认值：true - -### `treat-old-version-utf8-as-utf8mb4` - -+ 将旧表中的 utf8 字符集当成 utf8mb4的开关。 -+ 默认值：true - -### `alter-primary-key` - -+ 用于控制添加或者删除主键功能。 -+ 默认值：false -+ 默认情况下，不支持增删主键。将此变量被设置为 true 后，支持增删主键功能。不过对在此开关开启前已经存在的表，且主键是整型类型时，即使之后开启此开关也不支持对此列表删除主键。 - -### `repair-mode` - -+ 用于开启非可信修复模式，启动该模式后，可以过滤 `repair-table-list` 名单中坏表的加载。 -+ 默认值：false -+ 默认情况下，不支持修复语法，默认启动时会加载所有表信息。 - -### `repair-table-list` - -+ 配合 `repair-mode` 为 true 时使用，用于列出实例中需要修复的坏表的名单，该名单的写法为 ["db.table1","db.table2"...]。 -+ 默认值：[] -+ 默认情况下，该 list 名单为空，表示没有所需修复的坏表信息。 - -## log - -日志相关的配置项。 - -### `format` - -+ 指定日志输出的格式，可选项为 [json, text, console]。 -+ 默认值："text" - -### `enable-timestamp` - -+ 是否在日志中输出时间戳。 -+ 默认值：true -+ 如果设置为 false，那么日志里面将不会输出时间戳。 - -> **注意：** -> -> 考虑后向兼容性，原来的配置项 `disable-timestamp` 仍然有效，但如果和 `enable-timestamp` 配置的值在语义上冲突（例如在配置中把 `enable-timestamp` 和 `disable-timestamp` 同时设置为 `true`），则 TiDB 会忽略 `disable-timestamp` 的值。在未来的版本中，`disable-timestamp` 配置项将被彻底移除，请废弃 `disable-timestamp` 的用法，使用语义上更易于理解的 `enable-timestamp`。 - -### `slow-query-file` - -+ 慢查询日志的文件名。 -+ 默认值："tidb-slow.log"，注：由于 TiDB V2.1.8 更新了慢日志格式，所以将慢日志单独输出到了慢日志文件。V2.1.8 之前的版本，该变量的默认值是 ""。 -+ 设置后，慢查询日志会单独输出到该文件。 - -### `slow-threshold` - -+ 输出慢日志的耗时阈值。 -+ 默认值：300ms -+ 当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。 - -### `expensive-threshold` - -+ 输出 `expensive` 操作的行数阈值。 -+ 默认值：10000 -+ 当查询的行数（包括中间结果，基于统计信息）大于这个值，我们就会当成是一个 `expensive` 的操作，输出一个前缀带有 `[EXPENSIVE_QUERY]` 的日志。 - -### `query-log-max-len` - -+ 最长的 SQL 输出长度。 -+ 默认值：2048 -+ 当语句的长度大于 `query-log-max-len`，将会被截断输出。 - -### `max-server-connections` - -+ TiDB 中同时允许的最大客户端连接数，用于资源控制。 -+ 默认值：4096 -+ 当客户端连接数到达 `max-server-connections` 时，TiDB 服务端将会拒绝新的客户端连接。 - -## log.file - -日志文件相关的配置项。 - -#### `filename` - -+ 一般日志文件名字。 -+ 默认值："" -+ 如果设置，会输出一般日志到这个文件。 - -#### `max-size` - -+ 日志文件的大小限制。 -+ 默认值：300MB -+ 最大设置上限为 4GB。 - -#### `max-days` - -+ 日志最大保留的天数。 -+ 默认值：0 -+ 默认不清理；如果设置了参数值，在 `max-days` 之后 TiDB 会清理过期的日志文件。 - -#### `max-backups` - -+ 保留的日志的最大数量。 -+ 默认值：0 -+ 默认全部保存；如果设置为 7，会最多保留 7 个老的日志文件。 - -#### `log-rotate` - -+ 是否每日创建一个新的日志文件。 -+ 默认值：true -+ 如果设置为 true，每天会新建新的日志文件，如果设置为 false，那么只会输出到一个日志文件。 - -## security - -安全相关配置。 - -### `ssl-ca` - -+ PEM 格式的受信任 CA 的证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-cert`、`--ssl-key` 选项时，TiDB 将在客户端出示证书的情况下根据该选项指定的受信任的 CA 列表验证客户端证书。若验证失败，则连接会被终止。 -+ 即使设置了该选项，若客户端没有出示证书，则安全连接仍然继续，不会进行客户端证书验证。 - -### `ssl-cert` - -+ PEM 格式的 SSL 证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-key` 选项时，TiDB 将接受（但不强制）客户端使用 TLS 安全地连接到 TiDB。 -+ 若指定的证书或私钥无效，则 TiDB 会照常启动，但无法接受安全连接。 - -### `ssl-key` - -+ PEM 格式的 SSL 证书密钥文件路径，即 `--ssl-cert` 所指定的证书的私钥。 -+ 默认值："" -+ 目前 TiDB 不支持加载由密码保护的私钥。 - -### `cluster-ssl-ca` - -+ CA 根证书，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-cert` - -+ ssl 证书文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-key` - -+ ssl 私钥文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `skip-grant-table` - -+ 是否跳过权限检查 -+ 默认值：false - -## performance - -性能相关配置。 - -### `max-procs` - -+ TiDB 的 CPU 使用数量。 -+ 默认值：0 -+ 默认值为 0 表示使用机器上所有的 CPU；如果设置成 n，那么 TiDB 会使用 n 个 CPU 数量。 - -### `max-memory` - -+ Prepare cache LRU 使用的最大内存限制，超过 performance.max-memory * (1 - prepared-plan-cache.memory-guard-ratio)会 剔除 LRU 中的元素。 -+ 默认值：0 -+ 这个配置只有在 prepared-plan-cache.enabled 为 true 的情况才会生效。在 LRU 的 size 大于 prepared-plan-cache.capacity 的情况下，也会剔除 LRU 中的元素。 - -### `stmt-count-limit` - -+ TiDB 一个事务允许的最大语句条数限制。 -+ 默认值：5000 -+ 在一个事务中，超过 `stmt-count-limit` 条语句后还没有 rollback 或者 commit，TiDB 将会返回 `statement count 5001 exceeds the transaction limitation, autocommit = false` 错误。 - -### `tcp-keep-alive` - -+ TiDB 在 TCP 层开启 keepalive。 -+ 默认值：false - -### `cross-join` - -+ 默认值：true -+ 默认可以执行在做 join 时两边表没有任何条件（where 字段）的语句；如果设置为 false，则有这样的 join 语句出现时，server 会拒绝执行 - -### `stats-lease` - -+ TiDB 重载统计信息，更新表行数，检查是否需要自动 analyze，利用 feedback 更新统计信息以及加载列的统计信息的时间间隔。 -+ 默认值：3s - - 每隔 `stats-lease` 时间，TiDB 会检查统计信息是否有更新，如果有会将其更新到内存中 - - 每隔 `20 * stats-lease` 时间，TiDB 会将 DML 产生的总行数以及修改的行数变化更新到系统表中 - - 每隔 `stats-lease` 时间，TiDB 会检查是否有表或者索引需要自动 analyze - - 每隔 `stats-lease` 时间，TiDB 会检查是否有列的统计信息需要被加载到内存中 - - 每隔 `200 * stats-lease` 时间，TiDB 会将内存中缓存的 feedback 写入系统表中 - - 每隔 `5 * stats-lease` 时间，TiDB 会读取系统表中的 feedback，更新内存中缓存的统计信息 -+ 当 `stats-lease` 为 0 时，TiDB 会以 3s 的时间间隔周期性的读取系统表中的统计信息并更新内存中缓存的统计信息。但不会自动修改统计信息相关系统表，具体来说，TiDB 不再自动修改这些表： - - `mysql.stats_meta`：TiDB 不再自动记录事务中对某张表的修改行数，也不会更新到这个系统表中 - - `mysql.stats_histograms`/`mysql.stats_buckets` 和 `mysql.stats_top_n`：TiDB 不再自动 analyze 和主动更新统计信息 - - `mysql.stats_feedback`：TiDB 不再根据被查询的数据反馈的部分统计信息更新表和索引的统计信息 - -### `run-auto-analyze` - -+ TiDB 是否做自动的 Analyze。 -+ 默认值：true - -### `feedback-probability` - -+ TiDB 对查询收集统计信息反馈的概率。 -+ 默认值：0.05 -+ 对于每一个查询，TiDB 会以 `feedback-probability` 的概率收集查询的反馈，用于更新统计信息。 - -### `query-feedback-limit` - -+ 在内存中缓存的最大 Query Feedback 数量，超过这个数量的 Feedback 会被丢弃。 -+ 默认值：1024 - -### `pseudo-estimate-ratio` - -+ 修改过的行数/表的总行数的比值，超过该值时系统会认为统计信息已经过期，会采用 pseudo 的统计信息。 -+ 默认值：0.8 -+ 最小值为 0；最大值为 1。 - -### `force-priority` - -+ 把所有的语句优先级设置为 force-priority 的值。 -+ 默认值：NO_PRIORITY -+ 可选值：NO_PRIORITY, LOW_PRIORITY, HIGH_PRIORITY, DELAYED。 - -## prepared-plan-cache - -prepare 语句的 Plan cache 设置。 - -### `enabled` - -+ 开启 prepare 语句的 plan cache。 -+ 默认值：false - -### `capacity` - -+ 缓存语句的数量。 -+ 默认值：100 - -### `memory-guard-ratio` - -+ 用于防止超过 performance.max-memory, 超过 max-proc * (1 - prepared-plan-cache.memory-guard-ratio)会剔除 LRU 中的元素。 -+ 默认值：0.1 -+ 最小值为 0；最大值为 1。 - -## tikv-client - -### `grpc-connection-count` - -+ 跟每个 TiKV 之间建立的最大连接数。 -+ 默认值：16 - -### `grpc-keepalive-time` - -+ TiDB 与 TiKV 节点之间 rpc 连接 keepalive 时间间隔，如果超过该值没有网络包，grpc client 会 ping 一下 TiKV 查看是否存活。 -+ 默认值：10 -+ 单位：秒 - -### `grpc-keepalive-timeout` - -+ TiDB 与 TiKV 节点 rpc keepalive 检查的超时时间 -+ 默认值：3 -+ 单位：秒 - -### `commit-timeout` - -+ 执行事务提交时，最大的超时时间。 -+ 默认值：41s -+ 这个值必须是大于两倍 Raft 选举的超时时间。 - -### `max-txn-time-use` - -+ 单个事务允许的最大执行时间。 -+ 默认值：590 -+ 单位：秒 - -### `max-batch-size` - -+ 批量发送 rpc 封包的最大数量，如果不为 0，将使用 BatchCommands api 发送请求到 TiKV，可以在并发度高的情况降低 rpc 的延迟，推荐不修改该值。 -+ 默认值：128 - -### `max-batch-wait-time` - -+ 等待 `max-batch-wait-time` 纳秒批量将此期间的数据包封装成一个大包发送给 TiKV 节点，仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 -+ 默认值：0 -+ 单位：纳秒 - -### `batch-wait-size` - -+ 批量向 TiKV 发送的封包最大数量，不推荐修改该值。 -+ 默认值：8 -+ 若此值为 0 表示关闭此功能。 - -### `overload-threshold` - -+ TiKV 的负载阈值，如果超过此阈值，会收集更多的 batch 封包，来减轻 TiKV 的压力。仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 -+ 默认值：200 - -## txn-local-latches - -事务内存锁相关配置，当本地事务冲突比较多时建议开启。 - -### `enable` - -+ 开启或关闭事务内存锁 -+ 默认值：false - -### `capacity` - -+ Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。 -+ 默认值：2048000 - -## binlog - -TiDB Binlog 相关配置。 - -### `enable` - -+ binlog 开关。 -+ 默认值：false - -### `write-timeout` - -+ 写 binlog 的超时时间，推荐不修改该值。 -+ 默认值：15s -+ 单位：秒 - -### `ignore-error` - -+ 忽略写 binlog 发生的错误时处理开关，推荐不修改该值。 -+ 默认值：false -+ 如果设置为 `true`，发生错误时，TiDB 会停止写入 binlog，并且在监控项 `tidb_server_critical_error_total` 上计数加 1；如果设置为 `false`，写入 binlog 失败，会停止整个 TiDB 的服务。 - -### `binlog-socket` - -+ binlog 输出网络地址。 -+ 默认值："" - -### `strategy` - -+ binlog 输出时选择 pump 的策略，仅支持 hash，range 方法。 -+ 默认值："range" - -## status - -TiDB 服务状态相关配置。 - -### `report-status` - -+ 开启 HTTP API 服务的开关。 -+ 默认值：true - -### `record-db-qps` - -+ 输与 database 相关的 QPS metrics 到 Prometheus 的开关。 -+ 默认值：false - -## stmt-summary 从 v3.0.4 版本开始引入 - -系统表 `events_statement_summary_by_digest` 的相关配置。 - -### max-stmt-count - -+ `events_statement_summary_by_digest` 表中保存的 SQL 种类的最大数量。 -+ 默认值：100 - -### max-sql-length - -+ `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 -+ 默认值：4096 - -## pessimistic-txn - -### enable - -+ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/dev/reference/transactions/transaction-pessimistic.md)。 -+ 默认值：true - -### max-retry-count - -+ 悲观事务中每个语句最大重试次数，超出该限制将会报错。 -+ 默认值：256 diff --git a/dev/reference/configuration/tidb-server/configuration.md b/dev/reference/configuration/tidb-server/configuration.md deleted file mode 100644 index 8235a306537b..000000000000 --- a/dev/reference/configuration/tidb-server/configuration.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: TiDB 配置参数 -category: reference ---- - -# TiDB 配置参数 - -在启动 TiDB 时，你可以使用命令行参数或环境变量来配置 TiDB。本文将详细介绍 TiDB 的命令行启动参数。TiDB 的默认端口为 4000（客户端请求）与 10080（状态报告）。 - -## `--advertise-address` - -+ 登录 TiDB 的 IP 地址 -+ 默认："" -+ 必须确保用户和集群中的其他机器都能够访问到该 IP 地址 - -## `--binlog-socket` - -+ TiDB 服务使用 unix socket file 方式接受内部连接，如 Pump 服务 -+ 默认："" -+ 例如，可以使用 "/tmp/pump.sock" 来接受 Pump unix socket file 通信 - -## `--config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiDB 会首先读取配置文件的配置。如果对应的配置在命令行参数里面也存在，TiDB 就会使用命令行参数的配置来覆盖配置文件中的配置。详细的配置项请参阅 [TiDB 配置文件描述](/dev/reference/configuration/tidb-server/configuration-file.md)。 - -## `--cors` - -+ 用于设置 TiDB HTTP 状态服务的 Access-Control-Allow-Origin -+ 默认："" - -## `--host` - -+ TiDB 服务监听的 host -+ 默认："0.0.0.0" -+ 0.0.0.0 默认会监听所有的网卡地址。如果有多块网卡，可以指定对外提供服务的网卡，如 192.168.100.113 - -## `-L` - -+ Log 级别 -+ 默认："info" -+ 可选项为：debug、info、warn、error、fatal - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 "stderr"；如果设置了该参数，log 会输出到对应的文件中。每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--log-slow-query` - -+ 慢查询日志文件路径 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 `--log-file` 指定的文件中 - -## `--metrics-addr` - -+ Prometheus Pushgateway 地址 -+ 默认："" -+ 如果该参数为空，TiDB 不会将统计信息推送给 Pushgateway。参数格式示例：`--metrics-addr=192.168.100.115:9091` - -## `--metrics-interval` - -+ 推送统计信息到 Prometheus Pushgateway 的时间间隔 -+ 默认：15s -+ 设置为 0 表示不推送统计信息给 Pushgateway。示例：`--metrics-interval=2` 指每两秒推送到 Pushgateway - -## `-P` - -+ TiDB 服务监听端口 -+ 默认："4000" -+ TiDB 服务会使用该端口接受 MySQL 客户端发来的请求 - -## `--path` - -+ 对于本地存储引擎 "mocktikv" 来说，path 指定的是实际的数据存放路径 -+ 当 `--store = tikv` 时，必须指定 path；当 `--store = mocktikv` 时，如果不指定 path，会使用默认值。 -+ 对于 "TiKV" 存储引擎来说，path 指定的是实际的 PD 地址。假如在 192.168.100.113:2379、192.168.100.114:2379 和 192.168.100.115:2379 上面部署了 PD，那么 path 为 "192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379" -+ 默认："/tmp/tidb" -+ 可以通过 `tidb-server --store=mocktikv --path=""` 来启动一个纯内存引擎的 TiDB - -## `--proxy-protocol-networks` - -+ PROXY Protocol 允许的代理服务器地址列表。如需配置多个地址，用 `,` 分隔。 -+ 默认："" -+ 如果该参数为空，TiDB 会禁用 PROXY Protocol 功能。地址可以使用 IP 地址 (192.168.1.50) 或者 CIDR (192.168.1.0/24)，`*` 代表所有地址。 - -## `--proxy-protocol-header-timeout` - -+ PROXY Protocol 请求头读取超时时间 -+ 默认：5 -+ 单位：秒 - -> **注意：** -> -> 不要将该参数配置为 `0`。除非特殊情况，一般使用默认值即可。 - -## `--report-status` - -+ 用于打开或者关闭服务状态监听端口 -+ 默认：true -+ 将参数值设置为 `true` 表明开启状态监听端口；设置为 `false` 表明关闭状态监听端口 - -## `--run-ddl` - -+ tidb-server 是否运行 DDL 语句，集群内至少需要有一台 tidb-server 设置该参数 -+ 默认：true -+ 值可以为 `true` 或者 `false`。设置为 `true` 表明自身会运行 DDL；设置为 `false` 表明自身不会运行 DDL - -## `--socket string` - -+ TiDB 服务使用 unix socket file 方式接受外部连接 -+ 默认："" -+ 例如可以使用 "/tmp/tidb.sock" 来打开 unix socket file - -## `--status` - -+ TiDB 服务状态监听端口 -+ 默认："10080" -+ 该端口用于展示 TiDB 内部数据，包括 [prometheus 统计](https://prometheus.io/) 和 [pprof](https://golang.org/pkg/net/http/pprof/) -+ Prometheus 统计可以通过 `http://host:status_port/metrics` 访问 -+ pprof 数据可以通过 `http://host:status_port/debug/pprof` 访问 - -## `--status-host` - -+ TiDB 服务状态监听 host -+ 默认："0.0.0.0" - -## `--store` - -+ 用来指定 TiDB 底层使用的存储引擎 -+ 默认："mocktikv" -+ 可以选择 "mocktikv"（本地存储引擎）或者 "tikv"（分布式存储引擎） - -## `--token-limit` - -+ TiDB 中同时允许运行的 Session 数量，用于流量控制 -+ 默认：1000 -+ 如果当前运行的连接多于该 token-limit，那么请求会阻塞，等待已经完成的操作释放 Token - -## `-V` - -+ 输出 TiDB 的版本 -+ 默认："" diff --git a/dev/reference/configuration/tidb-server/mysql-variables.md b/dev/reference/configuration/tidb-server/mysql-variables.md deleted file mode 100644 index 6e3efe90095a..000000000000 --- a/dev/reference/configuration/tidb-server/mysql-variables.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 系统变量 -category: reference ---- - -# 系统变量 - -MySQL 系统变量 (System Variables) 是一些系统参数，用于调整数据库运行时的行为，根据变量的作用范围分为全局范围有效（Global Scope）以及会话级别有效（Session Scope）。TiDB 支持 MySQL5.7 的所有系统变量，大部分变量仅仅是为了兼容性而支持，不会影响运行时行为。 - -## 设置系统变量 - -通过 [`SET` 语句](/dev/reference/sql/statements/admin.md#set-语句)可以修改系统变量的值。进行修改时，还要考虑变量可修改的范围，不是所有的变量都能在全局/会话范围内进行修改。具体的可修改范围参考 [MySQL 动态变量文档](https://dev.mysql.com/doc/refman/5.7/en/dynamic-system-variables.html)。 - -### 全局范围值 - -* 在变量名前加 `GLOBAL` 关键词或者是使用 `@@global.` 作为修饰符: - - {{< copyable "sql" >}} - - ```sql - SET GLOBAL autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@global.autocommit = 1; - ``` - -> **注意：** -> -> 在分布式 TiDB 中，`GLOBAL` 变量的设置会持久化到存储层中，单个 TiDB 实例每 2 秒会主动进行一次全变量的获取并形成 `gvc` (global variables cache) 缓存，该缓存有效时间最多可持续 2 秒。在设置 `GLOBAL` 变量之后，为了保证新会话的有效性，请确保两个操作之间的间隔大于 2 秒。相关细节可以查看 [Issue #14531](https://github.com/pingcap/tidb/issues/14531)。 - -### 会话范围值 - -* 在变量名前加 `SESSION` 关键词或者是使用 `@@session.` 作为修饰符，或者是不加任何修饰符: - - {{< copyable "sql" >}} - - ```sql - SET SESSION autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@session.autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@autocommit = 1; - ``` - -* `LOCAL` 以及 `@@local.` 是 `SESSION` 以及 `@@session.` 的同义词 - -### 系统变量的作用机制 - -* 会话范围的系统变量仅仅会在创建会话时才会根据全局范围系统变量初始化自己的值。更改全局范围的系统变量不会改变已经创建的会话正在使用的系统变量的值。 - - {{< copyable "sql" >}} - - ```sql - SELECT @@GLOBAL.autocommit; - ``` - - ``` - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | ON | - +---------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SET GLOBAL autocommit = OFF; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - 会话范围的系统变量不会改变，会话中执行的事务依旧是以自动提交的形式来进行： - - {{< copyable "sql" >}} - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SELECT @@GLOBAL.autocommit; - ``` - - ``` - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | OFF | - +---------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - exit - ``` - - ``` - Bye - ``` - - {{< copyable "shell-regular" >}} - - ```shell - mysql -h 127.0.0.1 -P 4000 -u root -D test - ``` - - ``` - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 3 - Server version: 5.7.25-TiDB-None MySQL Community Server (Apache License 2.0) - - Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. - - Oracle is a registered trademark of Oracle Corporation and/or its - affiliates. Other names may be trademarks of their respective - owners. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - mysql> - ``` - - 新建的会话会使用新的全局变量： - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | OFF | - +----------------------+ - 1 row in set (0.00 sec) - ``` - -## TiDB 支持的 MySQL 系统变量 - -下列系统变量是 TiDB 真正支持并且行为和 MySQL 一致： - -| 变量名 | 作用域 | 说明 | -| ---------------- | -------- | -------------------------------------------------- | -| autocommit | GLOBAL \| SESSION | 是否自动 Commit 事务 | -| sql_mode | GLOBAL \| SESSION | 支持部分 MySQL SQL mode，| -| time_zone | GLOBAL \| SESSION | 数据库所使用的时区 | -| tx_isolation | GLOBAL \| SESSION | 事务隔离级别 | -| max\_execution\_time | GLOBAL \| SESSION | 语句超时时间，单位为毫秒 | -| innodb\_lock\_wait\_timeout | GLOBAL \| SESSION | 悲观事务语句等锁时间，单位为秒 | - -> **注意：** -> -> `max_execution_time` 目前对所有类型的 `statement` 生效，并非只对 `SELECT` 语句生效。实际精度在 100ms 级别，而非更准确的毫秒级别。 - -## TiDB 特有的系统变量 - -参见 [TiDB 专用系统变量](/dev/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/dev/reference/configuration/tidb-server/tidb-specific-variables.md b/dev/reference/configuration/tidb-server/tidb-specific-variables.md deleted file mode 100644 index c37ee6f13e00..000000000000 --- a/dev/reference/configuration/tidb-server/tidb-specific-variables.md +++ /dev/null @@ -1,668 +0,0 @@ ---- -title: TiDB 专用系统变量和语法 -category: reference ---- - -# TiDB 专用系统变量和语法 - -TiDB 在 MySQL 的基础上，定义了一些专用的系统变量和语法用来优化性能。 - -## 系统变量 - -变量可以通过 SET 语句设置，例如 - -{{< copyable "sql" >}} - -```sql -set @@tidb_distsql_scan_concurrency = 10; -``` - -如果需要设置全局变量，执行 - -{{< copyable "sql" >}} - -```sql -set @@global.tidb_distsql_scan_concurrency = 10; -``` - -### tidb_snapshot - -作用域：SESSION - -默认值：空字符串 - -这个变量用来设置当前会话期待读取的历史数据所处时刻。比如当设置为 "2017-11-11 20:20:20" 时或者一个 TSO 数字 "400036290571534337"，当前会话将能读取到该时刻的数据。 - -### tidb_import_data - -作用域：SESSION - -默认值：0 - -这个变量用来表示当前状态是否为从 dump 文件中导入数据。 -当这个变量被设置为 1 时，唯一索引约束不被检查以加速导入速度。 -这个变量不对外用，只是给 lightning 使用，请用户不要自行修改。 - -### tidb_opt_agg_push_down - -作用域：SESSION - -默认值：0 - -这个变量用来设置优化器是否执行聚合函数下推到 Join 之前的优化操作。 -当查询中聚合操作执行很慢时，可以尝试设置该变量为 1。 - -### tidb_auto_analyze_ratio - -作用域：GLOBAL - -默认值：0.5 - -这个变量用来设置自动 ANALYZE 更新的阈值。当某个表 `tbl` 的修改行数与总行数的比值大于 tidb_auto_analyze_ratio，并且当前时间在 tidb_auto_analyze_start_time 和 tidb_auto_analyze_end_time 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句以自动更新该表的统计信息。注意：只有在 TiDB 的启动配置文件中开启了 run-auto-analyze 选项，该 TiDB 才会触发 auto_analyze。 - -### tidb_auto_analyze_start_time - -作用域：GLOBAL - -默认值：00:00 +0000 - -这个变量用来设置一天中允许自动 ANALYZE 更新的开始时间。 - -### tidb_auto_analyze_end_time - -作用域：GLOBAL - -默认值：23:59 +0000 - -这个变量用来设置一天中允许自动 ANALYZE 更新的结束时间。 - -### tidb_build_stats_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ANALYZE 语句执行时并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_checksum_table_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ADMIN CHECKSUM TABLE 语句执行时扫描索引的并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_current_ts - -作用域：SESSION - -默认值：0 - -这个变量是一个只读变量，用来获取当前事务的时间戳。 - -### tidb_config - -作用域：SESSION - -默认值：空字符串 - -这个变量是一个只读变量，用来获取当前 TiDB Server 的配置信息。 - -### tidb_distsql_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：15 - -这个变量用来设置 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 -对于 AP 类应用，最大值建议不要超过所有 TiKV 节点的 CPU 核数。 - -### tidb_index_lookup_size - -作用域：SESSION | GLOBAL - -默认值：20000 - -这个变量用来设置 index lookup 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup join 算法的并发度。 - -### tidb_hash_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：5 - -这个变量用来设置 hash join 算法的并发度。 - -### tidb_index_serial_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来设置顺序 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_projection_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 Projection 算子的并发度。 - -### tidb_hashagg_partial_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 partial 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_hashagg_final_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 final 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_index_join_batch_size - -作用域：SESSION | GLOBAL - -默认值：25000 - -这个变量用来设置 index lookup join 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_skip_utf8_check - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来设置是否跳过 UTF-8 字符的验证。 -验证 UTF-8 字符需要消耗一定的性能，当可以确认输入的字符串为有效的 UTF-8 字符时，可以将其设置为 1。 - -### tidb_init_chunk_size - -作用域：SESSION | GLOBAL - -默认值：32 - -这个变量用来设置执行过程中初始 chunk 的行数。默认值是 32。 - -### tidb_max_chunk_size - -作用域：SESSION | GLOBAL - -默认值：1024 - -这个变量用来设置执行过程中一个 chunk 最大的行数。 - -### tidb_mem_quota_query - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置一条查询语句的内存使用阈值。 -如果一条查询语句执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_hashjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 HashJoin 算子的内存使用阈值。 -如果 HashJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_mergejoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 MergeJoin 算子的内存使用阈值。 -如果 MergeJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_sort - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 Sort 算子的内存使用阈值。 -如果 Sort 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_topn - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 TopN 算子的内存使用阈值。 -如果 TopN 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupreader - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupReader 算子的内存使用阈值。 - -如果 IndexLookupReader 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupJoin 算子的内存使用阈值。 -如果 IndexLookupJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_nestedloopapply - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 NestedLoopApply 算子的内存使用阈值。 -如果 NestedLoopApply 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_general_log - -作用域：SERVER - -默认值：0 - -这个变量用来设置是否在日志里记录所有的 SQL 语句。 - -### tidb_enable_streaming - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否启用 Streaming。 - -### tidb_retry_limit - -作用域：SESSION | GLOBAL - -默认值：10 - -这个变量用来设置最大重试次数。一个事务执行中遇到可重试的错误（例如事务冲突、事务提交过慢或表结构变更）时，会根据该变量的设置进行重试。注意当 `tidb_retry_limit = 0` 时，也会禁用自动重试。 - -### tidb_disable_txn_auto_retry - -作用域：SESSION | GLOBAL - -默认值：on - -这个变量用来设置是否禁用显式事务自动重试，设置为 `on` 时，不会自动重试，如果遇到事务冲突需要在应用层重试。 - -如果将该变量的值设为 `off`，TiDB 将会自动重试事务，这样在事务提交时遇到的错误更少。需要注意的是，这样可能会导致数据更新丢失。 - -这个变量不会影响自动提交的隐式事务和 TiDB 内部执行的事务，它们依旧会根据 `tidb_retry_limit` 的值来决定最大重试次数。 - -是否需要禁用自动重试，请参考[重试的局限性](/dev/reference/transactions/transaction-optimistic.md#重试的局限性)。 - -### tidb_backoff_weight - -作用域：SESSION | GLOBAL - -默认值：2 - -这个变量用来给 TiDB 的 `backoff` 最大时间增加权重，即内部遇到网络或其他组件（TiKV、PD）故障等时，发送重试请求的最大重试时间。可以通过这个变量来调整最大重试时间，最小值为 1。 - -例如，TiDB 向 PD 取 TSO 的基础超时时间是 15 秒，当 `tidb_backoff_weight = 2` 时，取 TSO 的最大超时时间为：基础时间 * 2 等于 30 秒。 - -在网络环境较差的情况下，适当增大该变量值可以有效缓解因为超时而向应用端报错的情况；而如果应用端希望更快地接到报错信息，则应该尽量减小该变量的值。 - -### tidb_enable_table_partition - -作用域：SESSION - -默认值："auto" - -这个变量用来设置是否开启 TABLE PARTITION 特性。默认值 `auto` 表示开启 range partition 和 hash partion。`off` 表示关闭 TABLE PARTITION 的特性，此时语法还是会依旧兼容，只是建立的 partition table 实际上并不是真正的 partition table，而是和普通的 table 一样。`on` 表示开启，目前的作用和 `auto` 一样。 - -注意，目前 TiDB 只支持 range partition 和 hash partition。 - -### tidb_backoff_lock_fast - -作用域：SESSION | GLOBAL - -默认值：100 - -这个变量用来设置读请求遇到锁的 backoff 时间。 - -### tidb_ddl_reorg_worker_cnt - -作用域：GLOBAL - -默认值：16 - -这个变量用来设置 DDL 操作 re-organize 阶段的并发度。 - -### tidb_ddl_reorg_batch_size - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置 DDL 操作 re-organize 阶段的 batch size。比如 Add Index 操作，需要回填索引数据，通过并发 tidb_ddl_reorg_worker_cnt 个 worker 一起回填数据，每个 worker 以 batch 为单位进行回填。如果 Add Index 时有较多 Update 操作或者 Replace 等更新操作，batch size 越大，事务冲突的概率也会越大，此时建议调小 batch size 的值，最小值是 32。在没有事务冲突的情况下，batch size 可设为较大值，最大值是 10240，这样回填数据的速度更快，但是 TiKV 的写入压力也会变大。 - -### tidb_ddl_reorg_priority - -作用域：SESSION | GLOBAL - -默认值：PRIORITY_LOW - -这个变量用来设置 `ADD INDEX` 操作 re-organize 阶段的执行优先级，可设置为 PRIORITY_LOW/PRIORITY_NORMAL/PRIORITY_HIGH。 - -### tidb_ddl_error_count_limit - -作用域：GLOBAL - -默认值：512 - -这个变量用来控制 DDL 操作失败重试的次数。失败重试次数超过该参数的值后，会取消出错的 DDL 操作。 - -### tidb_max_delta_schema_count - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置缓存 schema 版本信息（对应版本修改的相关 table IDs）的个数限制，可设置的范围 100 - 16384。此变量在 2.1.18 及之后版本支持。 - -### tidb_force_priority - -作用域：SESSION - -默认值：`NO_PRIORITY` - -这个变量用于改变 TiDB server 上执行的语句的默认优先级。例如，你可以通过设置该变量来确保正在执行 OLAP 查询的用户优先级低于正在执行 OLTP 查询的用户。 - -可设置为 `NO_PRIORITY`、`LOW_PRIORITY`、`DELAYED` 或 `HIGH_PRIORITY`。 - -### tidb_opt_write_row_id - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否允许 insert、replace 和 update 操作 `_tidb_rowid` 列，默认是不允许操作。该选项仅用于 TiDB 工具导数据时使用。 - -### SHARD_ROW_ID_BITS - -对于 PK 非整数或没有 PK 的表，TiDB 会使用一个隐式的自增 rowid，大量 `INSERT` 时会把数据集中写入单个 Region，造成写入热点。 - -通过设置 `SHARD_ROW_ID_BITS`，可以把 rowid 打散写入多个不同的 Region，缓解写入热点问题。但是设置的过大会造成 RPC 请求数放大，增加 CPU 和网络开销。 - -- `SHARD_ROW_ID_BITS = 4` 表示 16 个分片 -- `SHARD_ROW_ID_BITS = 6` 表示 64 个分片 -- `SHARD_ROW_ID_BITS = 0` 表示默认值 1 个分片 - -语句示例： - -- `CREATE TABLE`：`CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` -- `ALTER TABLE`：`ALTER TABLE t SHARD_ROW_ID_BITS = 4;` - -### tidb_slow_log_threshold - -作用域：SESSION - -默认值：300 - -输出慢日志的耗时阈值。当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。默认为 300ms。 - -示例： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_log_threshold = 200; -``` - -### tidb_query_log_max_len - -作用域：SESSION - -默认值：2048 (bytes) - -最长的 SQL 输出长度。当语句的长度大于 query-log-max-len，将会被截断输出。 - -示例： - -{{< copyable "sql" >}} - -```sql -set tidb_query_log_max_len = 20; -``` - -### tidb_txn_mode - -作用域：SESSION | GLOBAL - -默认值："pessimistic" - -这个变量用于设置事务模式。TiDB v3.0 支持了悲观事务，自 v3.0.8 开始，默认使用[悲观事务模式](/dev/reference/transactions/transaction-pessimistic.md)。 - -但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 - -将该变量设置为 "optimistic" 或 "" 时，将会使用[乐观事务模式](/dev/reference/transactions/transaction-optimistic.md)。 - -### tidb_constraint_check_in_place - -作用域：SESSION | GLOBAL - -默认值：0 - -TiDB 支持乐观事务模型，即在执行写入时，假设不存在冲突。冲突检查是在最后 commit 提交时才去检查。这里的检查指 unique key 检查。 - -这个变量用来控制是否每次写入一行时就执行一次唯一性检查。注意，开启该变量后，在大批量写入场景下，对性能会有影响。 - -示例： - -默认关闭 tidb_constraint_check_in_place 时的行为： - -{{< copyable "sql" >}} - -```sql -create table t (i int key); -insert into t values (1); -begin; -insert into t values (1); -``` - -``` -Query OK, 1 row affected -``` - -commit 时才去做检查： - -{{< copyable "sql" >}} - -```sql -commit; -``` - -``` -ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' -``` - -打开 tidb_constraint_check_in_place 后： - -{{< copyable "sql" >}} - -```sql -set @@tidb_constraint_check_in_place=1; -begin; -insert into t values (1); -``` - -``` -ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' -``` - -### tidb_check_mb4_value_in_utf8 - -作用域：SERVER - -默认值：1 - -这个变量用来设置是否开启对字符集为 UTF8 类型的数据做合法性检查，默认值 `1` 表示开启检查。这个默认行为和 MySQL 是兼容的。 - -注意，如果是旧版本升级时，可能需要关闭该选项，否则由于旧版本（v2.1.1 以及之前）没有对数据做合法性检查，所以旧版本写入非法字符串是可以写入成功的，但是新版本加入合法性检查后会报写入失败。具体可以参考[升级后常见问题](/dev/faq/upgrade.md)。 - -### tidb_opt_insubq_to_join_and_agg - -作用域：SESSION | GLOBAL - -默认值：1 - -这个用来设置是否开启优化规则：将子查询转成 join 和 aggregation。 - -示例： - -打开这个优化规则后，会将下面子查询做如下变化： - -{{< copyable "sql" >}} - -```sql -select * from t where t.a in (select aa from t1); -``` - -将子查询转成 join 如下： - -{{< copyable "sql" >}} - -```sql -select * from t, (select aa from t1 group by aa) tmp_t where t.a = tmp_t.aa; -``` - -如果 t1 在列 aa 上有 unique 且 not null 的限制，可以直接改写为如下，不需要添加 aggregation。 - -{{< copyable "sql" >}} - -```sql -select * from t, t1 where t.a=t1.a; -``` - -### tidb_opt_correlation_threshold - -作用域：SESSION | GLOBAL - -默认值：0.9 - -这个变量用来设置优化器启用交叉估算 row count 方法的阈值。如果列和 handle 列之间的顺序相关性超过这个阈值，就会启用交叉估算方法。 - -交叉估算方法可以简单理解为，利用这个列的直方图来估算 handle 列需要扫的行数。 - -### tidb_opt_correlation_exp_factor - -作用域：SESSION | GLOBAL - -默认值：1 - -当交叉估算方法不可用时，会采用启发式估算方法。这个变量用来控制启发式方法的行为。当值为 0 时不用启发式估算方法，大于 0 时，该变量值越大，启发式估算方法越倾向 index scan，越小越倾向 table scan。 - -### tidb_enable_window_function - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来控制是否开启窗口函数的支持。默认值 1 代表开启窗口函数的功能。 - -由于窗口函数会使用一些保留关键字，可能导致原先可以正常执行的 SQL 语句在升级 TiDB 后无法被解析语法，此时可以将 `tidb_enable_window_function` 设置为 `0`。 - -### tidb_slow_query_file - -作用域：SESSION - -默认值："" - -查询 `INFORMATION_SCHEMA.SLOW_QUERY` 只会解析配置文件中 `slow-query-file` 设置的慢日志文件名，默认是 "tidb-slow.log"。但如果想要解析其他的日志文件，可以通过设置 session 变量 `tidb_slow_query_file` 为具体的文件路径，然后查询 `INFORMATION_SCHEMA.SLOW_QUERY` 就会按照设置的路径去解析慢日志文件。更多详情可以参考 [SLOW_QUERY 文档](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 - -### tidb_enable_fast_analyze - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来控制是否启用统计信息快速分析功能。默认值 0 表示不开启。 - -快速分析功能开启后，TiDB 会随机采样约 10000 行的数据来构建统计信息。因此在数据分布不均匀或者数据量比较少的情况下，统计信息的准确度会比较低。这可能导致执行计划不优，比如选错索引。如果可以接受普通 `ANALYZE` 语句的执行时间，则推荐关闭快速分析功能。 - -### tidb_expensive_query_time_threshold - -作用域：SERVER - -默认值：60 - -这个变量用来控制打印 expensive query 日志的阈值时间，单位是秒，默认值是 60 秒。expensive query 日志和慢日志的差别是，慢日志是在语句执行完后才打印，expensive query 日志可以把正在执行中的语句且执行时间超过阈值的语句及其相关信息打印出来。 - -### tidb_wait_split_region_finish - -作用域：SESSION - -默认值：1 - -由于打散 region 的时间可能比较长，主要由 PD 调度以及 TiKV 的负载情况所决定。这个变量用来设置在执行 `SPLIT REGION` 语句时，是否同步等待所有 region 都打散完成后再返回结果给客户端。默认 1 代表等待打散完成后再返回结果。0 代表不等待 Region 打散完成就返回。 - -需要注意的是，在 region 打散期间，对正在打散 region 上的写入和读取的性能会有一定影响，对于批量写入，导数据等场景，还是建议等待 region 打散完成后再开始导数据。 - -### tidb_wait_split_region_timeout - -作用域：SESSION - -默认值：300 - -这个变量用来设置 `SPLIT REGION` 语句的执行超时时间，单位是秒，默认值是 300 秒，如果超时还未完成，就返回一个超时错误。 - -### tidb_scatter_region - -作用域：GLOBAL - -默认值：0 - -TiDB 默认会在建表时为新表分裂 Region。开启该变量后，会在建表语句执行时，同步打散刚分裂出的 Region。适用于批量建表后紧接着批量写入数据，能让刚分裂出的 Region 先在 TiKV 分散而不用等待 PD 进行调度。为了保证后续批量写入数据的稳定性，建表语句会等待打散 Region 完成后再返回建表成功，建表语句执行时间会是关闭该变量的数倍。 - -### tidb_allow_remove_auto_inc 从 v2.1.18 和 v3.0.4 版本开始引入 - -作用域：SESSION - -默认值：0 - -这个变量用来控制是否允许通过 `ALTER TABLE MODIFY` 或 `ALTER TABLE CHANGE` 来移除某个列的 `AUTO_INCREMENT` 属性。默认为不允许。 - -### tidb_enable_stmt_summary 从 v3.0.4 版本开始引入 - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来控制是否开启 statement summary 功能。如果开启，SQL 的耗时等执行信息将被记录到系统表 `performance_schema.events_statements_summary_by_digest` 中，用于定位和排查 SQL 性能问题。 diff --git a/dev/reference/configuration/tikv-server/configuration-file.md b/dev/reference/configuration/tikv-server/configuration-file.md deleted file mode 100644 index 77cfd2555a35..000000000000 --- a/dev/reference/configuration/tikv-server/configuration-file.md +++ /dev/null @@ -1,1092 +0,0 @@ ---- -title: TiKV 配置文件描述 -category: reference ---- - -# TiKV 配置文件描述 - -TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/config-template.toml](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 找到默认值的配置文件，重命名为 config.toml 即可。 - -本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [TiKV 配置参数](/dev/reference/configuration/tikv-server/configuration.md)。 - - -### `status-thread-pool-size` - -+ Http API 服务的工作线程数量。 -+ 默认值：1 -+ 最小值：1 - -### `grpc-compression-type` - -+ gRPC 消息的压缩算法，取值：none， deflate， gzip。 -+ 默认值：none - -### `grpc-concurrency` - -+ gRPC 工作线程的数量。 -+ 默认值：4 -+ 最小值：1 - -### `grpc-concurrent-stream` - -+ 一个 gRPC 链接中最多允许的并发请求数量。 -+ 默认值：1024 -+ 最小值：1 - -### `server.grpc-raft-conn-num` - -+ tikv 节点之间用于 raft 通讯的链接最大数量。 -+ 默认值：10 -+ 最小值：1 - -### `server.grpc-stream-initial-window-size` - -+ gRPC stream 的 window 大小。 -+ 默认值：2MB -+ 单位：KB|MB|GB -+ 最小值：1KB - -### `server.grpc-keepalive-time` - -+ gRPC 发送 keep alive ping 消息的间隔时长。 -+ 默认值：10s -+ 最小值：1s - -### `server.grpc-keepalive-timeout` - -+ 关闭 gRPC 链接的超时时长。 -+ 默认值：3s -+ 最小值：1s - -### `server.concurrent-send-snap-limit` - -+ 同时发送 snapshot 的最大个数，默认值：32 -+ 默认值：32 -+ 最小值：1 - -### `server.concurrent-recv-snap-limit` - -+ 同时接受 snapshot 的最大个数，默认值：32 -+ 默认值：32 -+ 最小值：1 - -### `server.end-point-recursion-limit` - -+ endpoint 下推查询请求解码消息时，最多允许的递归层数。 -+ 默认值：1000 -+ 最小值：1 - -### `server.end-point-request-max-handle-duration` - -+ endpoint 下推查询请求处理任务最长允许的时长。 -+ 默认值：60s -+ 最小值：1s - -### `server.snap-max-write-bytes-per-sec` - -+ 处理 snapshot 时最大允许使用的磁盘带宽 -+ 默认值：1000MB -+ 单位：KB|MB|GB -+ 最小值：1KB - -## readpool.storage - -存储线程池相关的配置项。 - -### `high-concurrency` - -+ 处理高优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `normal-concurrency` - -+ 处理普通优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `low-concurrency` - -+ 处理低优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `max-tasks-per-worker-high` - -+ 高优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-normal` - -+ 普通优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-low` - -+ 低优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `stack-size` - -+ Storage 读线程池中线程的栈大小。 -+ 默认值：10MB -+ 单位：KB|MB|GB -+ 最小值：2MB - -## readpool.coprocessor - -协处理器线程池相关的配置项。 - -### `high-concurrency` - -+ 处理高优先级 Coprocessor 请求（如点查）的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `normal-concurrency` - -+ 处理普通优先级 Coprocessor 请求的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `low-concurrency` - -+ 处理低优先级 Coprocessor 请求（如扫表）的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `max-tasks-per-worker-high` - -+ 高优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-normal` - -+ 普通优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-low` - -+ 低优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `stack-size` - -Coprocessor 线程池中线程的栈大小，默认值：10，单位：KiB|MiB|GiB。 - -+ 默认值：10MB -+ 单位：KB|MB|GB -+ 最小值：2MB - -## storage - -存储相关的配置项。 - -### `scheduler-notify-capacity` - -+ scheduler 一次获取最大消息个数 -+ 默认值：10240 -+ 最小值：1 - -### `scheduler-concurrency` - -+ scheduler 内置一个内存锁机制，防止同时对一个 key 进行操作。每个 key hash 到不同的槽。 -+ 默认值：2048000 -+ 最小值：1 - -### `scheduler-worker-pool-size` - -+ scheduler 线程个数，主要负责写入之前的事务一致性检查工作。 -+ 默认值：4 -+ 最小值：1 - -### `scheduler-pending-write-threshold` - -+ 写入数据队列的最大值，超过该值之后对于新的写入 TiKV 会返回 Server Is Busy 错误。 -+ 默认值：100MB -+ 单位: MB|GB - -## raftstore - -raftstore 相关的配置项。 - -### `sync-log` - -+ 数据、log 落盘是否 sync，注意：设置成 false 可能会丢数据。 -+ 默认值：true - -### `prevote` - -+ 开启 Prevote 的开关，开启有助于减少隔离恢复后对系统造成的抖动。 -+ 默认值：true - -### `raftdb-path` - -+ raft 库的路径，默认存储在 storage.data-dir/raft 下。 -+ 默认值："" - -### `raft-base-tick-interval` - -+ 状态机 tick 一次的间隔时间。 -+ 默认值：1s -+ 最小值：大于 0 - -### `raft-heartbeat-ticks` - -+ 发送心跳时经过的 tick 个数，即每隔 raft-base-tick-interval * raft-heartbeat-ticks 时间发送一次心跳。 -+ 默认值：2 -+ 最小值：大于 0 - -### `raft-election-timeout-ticks` - -+ 发起选举时经过的 tick 个数，即如果处于无主状态，大约经过 raft-base-tick-interval * raft-election-timeout-ticks 时间以后发起选举。 -+ 默认值：10 -+ 最小值：raft-heartbeat-ticks - -### `raft-min-election-timeout-ticks` - -+ 发起选举时至少经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks，不能比 raft-election-timeout-ticks 小。 -+ 默认值：0 -+ 最小值：0 - -### `raft-max-election-timeout-ticks` - -+ 发起选举时最多经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks * 2。 -+ 默认值：0 -+ 最小值：0 - -### `raft-max-size-per-message` - -+ 产生的单个消息包的大小限制，软限制。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：MB - -### `raft-max-inflight-msgs` - -+ 待确认日志个数的数量，如果超过这个数量将会减缓发送日志的个数。 -+ 默认值：256 -+ 最小值：大于0 - -### `raft-entry-max-size` - -+ 单个日志最大大小，硬限制。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：MB|GB - -### `raft-log-gc-tick-interval` - -+ 删除 raft 日志的轮询任务调度间隔时间，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `raft-log-gc-threshold` - -+ 允许残余的 raft 日志个数，这是一个软限制。 -+ 默认值：50 -+ 最小值：1 - -### `raft-log-gc-count-limit` - -+ 允许残余的 raft 日志个数，这是一个硬限制。默认值为按照每个日志 1MB 而计算出来的 3/4 region 大小所能容纳的日志个数。 -+ 最小值：0 - -### `raft-log-gc-size-limit` - -+ 允许残余的 raft 日志大小，这是一个硬限制，默认为 region 大小的 3/4。 -+ 最小值：大于 0 - -### `raft-entry-cache-life-time` - -+ 内存中日志 cache 允许的最长残留时间。 -+ 默认值：30s -+ 最小值：0 - -### `raft-reject-transfer-leader-duration` - -+ 新节点保护时间，控制迁移 leader 到新加节点的最小时间，设置过小容易导致迁移 leader 失败。 -+ 默认值：3s -+ 最小值：0 - -### `raftstore.hibernate-regions` (**实验特性**) - -+ 打开或关闭静默 Region。打开后，如果 Region 长时间处于非活跃状态，即被自动设置为静默状态。静默状态的 Region 可以降低 Leader 和 Follower 之间心跳信息的系统开销。可以通过 `raftstore.peer-stale-state-check-interval` 调整 Leader 和 Follower 之间的心跳间隔。 -+ 默认值：true - -### `raftstore.peer-stale-state-check-interval` - -+ 修改对 Region 的状态检查间隔时间。 -+ 默认值：5 min - -### `split-region-check-tick-interval` - -+ 检查 region 是否需要分裂的时间间隔，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `region-split-check-diff` - -+ 允许 region 数据超过指定大小的最大值，默认为 region 大小的 1/16。 -+ 最小值：0 - -### `region-compact-check-interval` - -+ 检查是否需要人工触发 rocksdb compaction 的时间间隔，0 表示不启用。 -+ 默认值：5m -+ 最小值：0 - -### `clean-stale-peer-delay` - -+ 延迟删除过期副本数据的时间。 -+ 默认值：10m -+ 最小值：0 - -### `region-compact-check-step` - -+ 每轮校验人工 compaction 时，一次性检查的 region 个数。 -+ 默认值：100 -+ 最小值：0 - -### `region-compact-min-tombstones` - -+ 触发 rocksdb compaction 需要的 tombstone 个数。 -+ 默认值：10000 -+ 最小值：0 - -### `region-compact-tombstones-percent` - -+ 触发 rocksdb compaction 需要的 tombstone 所占比例。 -+ 默认值：30 -+ 最小值：1 -+ 最大值：100 - -### `pd-heartbeat-tick-interval` - -+ 触发 region 对 PD 心跳的时间间隔，0 表示不启用。 -+ 默认值：1m -+ 最小值：0 - -### `pd-store-heartbeat-tick-interval` - -+ 触发 store 对 PD 心跳的时间间隔，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `snap-mgr-gc-tick-interval` - -+ 触发回收过期 snapshot 文件的时间间隔，0 表示不启用。 -+ 默认值：5s -+ 最小值：0 - -### `snap-gc-timeout` - -+ snapshot 文件的最长保存时间。 -+ 默认值：4h -+ 最小值：0 - -### `lock-cf-compact-interval` - -+ 触发对 lock CF compact 检查的时间间隔。 -+ 默认值：10m -+ 最小值：0 - -### `lock-cf-compact-bytes-threshold` - -+ 触发对 lock CF 进行 compact 的大小。 -+ 默认值：256MB -+ 最小值：0 -+ 单位：MB - -### `notify-capacity` - -+ region 消息队列的最长长度。 -+ 默认值：40960 -+ 最小值：0 - -### `messages-per-tick` - -+ 每轮处理的消息最大个数。 -+ 默认值：4096 -+ 最小值：0 - -### `max-peer-down-duration` - -+ 副本允许的最长未响应时间，超过将被标记为 down，后续 PD 会尝试将其删掉。 -+ 默认值：5m -+ 最小值：0 - -### `max-leader-missing-duration` - -+ 允许副本处于无主状态的最长时间，超过将会向 PD 校验自己是否已经被删除。 -+ 默认值：2h -+ 最小值：> abnormal-leader-missing-duration - -### `abnormal-leader-missing-duration` - -+ 允许副本处于无主状态的时间，超过将视为异常，标记在 metrics 和日志中。 -+ 默认值：10m -+ 最小值：> peer-stale-state-check-interval - -### `peer-stale-state-check-interval` - -+ 触发检验副本是否处于无主状态的时间间隔。 -+ 默认值：5m -+ 最小值：> 2 * election-timeout - -### `leader-transfer-max-log-lag` - -+ 尝试转移领导权时被转移者允许的最大日志缺失个数。 -+ 默认值：10 -+ 最小值：10 - -### `snap-apply-batch-size` - -+ 当导入 snapshot 文件需要写数据时，内存写缓存的大小 -+ 默认值：10MB -+ 最小值：0 -+ 单位：MB - -### `consistency-check-interval` - -+ 触发一致性检查的时间间隔, 0 表示不启用。 -+ 默认值：0s -+ 最小值：0 - -### `raft-store-max-leader-lease` - -+ region 主可信任期的最长时间。 -+ 默认值：9s -+ 最小值：0 - -### `right-derive-when-split` - -+ 为 true 时，以最大分裂 key 为起点的 region 复用原 region 的 key；否则以原 region 起点 key 作为起点的 region 复用原 region 的 key。 -+ 默认值：true - -### `allow-remove-leader` - -+ 允许删除主开关。 -+ 默认值：false - -### `merge-max-log-gap` - -+ 进行 merge 时，允许的最大日志缺失个数。 -+ 默认值：10 -+ 最小值：> raft-log-gc-count-limit - -### `merge-check-tick-interval` - -+ 触发 merge 完成检查的时间间隔。 -+ 默认值：10s -+ 最小值：大于 0 - -### `use-delete-range` - -+ 开启 rocksdb delete_range 接口删除数据的开关。 -+ 默认值：false - -### `cleanup-import-sst-interval` - -+ 触发检查过期 SST 文件的时间间隔，0 表示不启用。 -+ 默认值：10m -+ 最小值：0 - -### `local-read-batch-size` - -+ 一轮处理读请求的最大个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `apply-max-batch-size` - -+ 一轮处理数据落盘的最大请求个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `apply-pool-size` - -+ 处理数据落盘的线程池线程数。 -+ 默认值：2 -+ 最小值：大于 0 - -### `store-max-batch-size` - -+ 一轮处理的最大请求个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `store-pool-size` - -+ 处理 raft 的线程池线程数。 -+ 默认值：2 -+ 最小值：大于 0 - -### `future-poll-size` - -+ 驱动 future 的线程池线程数。 -+ 默认值：1 -+ 最小值：大于 0 - -## coprocessor - -协处理器相关的配置项。 - -### `split-region-on-table` - -+ 开启按 table 分裂 Region的开关，建议仅在 TiDB 模式下使用。 -+ 默认值：true - -### `batch-split-limit` - -+ 批量分裂 Region 的阈值，调大该值可加速分裂 Region。 -+ 默认值：10 -+ 最小值：1 - -### `region-max-size` - -+ Region 容量空间最大值，超过时系统分裂成多个 Region。 -+ 默认值：144MB -+ 单位：KB|MB|GB - -### `region-split-size` - -+ 分裂后新 Region 的大小，此值属于估算值。 -+ 默认值：96MB -+ 单位：KB|MB|GB - -### `region-max-keys` - -+ Region 最多允许的 key 的个数，超过时系统分裂成多个 Region。 -+ 默认值：1440000 - -### `region-split-keys` - -+ 分裂后新 Region 的 key 的个数，此值属于估算值。 -+ 默认值：960000 - -## rocksdb - -rocksdb 相关的配置项。 - -### `max-background-jobs` - -+ RocksDB 后台线程个数。 -+ 默认值：8 -+ 最小值：1 - -### `max-sub-compactions` - -+ RocksDB 进行 subcompaction 的并发个数。 -+ 默认值：1 -+ 最小值：1 - -### `max-open-files` - -+ RocksDB 可以打开的文件总数。 -+ 默认值：40960 -+ 最小值：-1 - -### `max-manifest-file-size` - -+ RocksDB Manifest 文件最大大小。 -+ 默认值：128MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `create-if-missing` - -+ 自动创建 DB 开关。 -+ 默认值：true - -### `wal-recovery-mode` - -+ WAL 恢复模式，取值：0（TolerateCorruptedTailRecords），1（AbsoluteConsistency），2（PointInTimeRecovery），3（SkipAnyCorruptedRecords）。 -+ 默认值：2 -+ 最小值：0 -+ 最大值：3 - -### `wal-dir` - -+ WAL 存储目录，默认：“tmp/tikv/store”。 -+ 默认值：/tmp/tikv/store - -### `wal-ttl-seconds` - -+ 归档 WAL 生存周期，超过该值时，系统会删除相关 WAL。 -+ 默认值：0 -+ 最小值：0 -+ 单位：秒 - -### `wal-size-limit` - -+ 归档 WAL 大小限制，超过该值时，系统会删除相关 WAL。 -+ 默认值：0 -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `enable-statistics` - -+ 开启自动优化 Rate LImiter 的配置的开关。 -+ 默认值：false - -### `stats-dump-period` - -+ 开启 Pipelined Write 的开关。 -+ 默认值：true - -### `compaction-readahead-size` - -+ 异步 Sync 限速速率。 -+ 默认值：0 -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `writable-file-max-buffer-size` - -+ WritableFileWrite 所使用的最大的 buffer 大小。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `use-direct-io-for-flush-and-compaction` - -+ flush 或者 compaction 开启 DirectIO 的开关。 -+ 默认值：false - -### `rate-bytes-per-sec` - -+ Rate Limiter 限制速率。 -+ 默认值：0 -+ 最小值：0 -+ 单位：Bytes - -### `rate-limiter-mode` - -+ Rate LImiter 模式，取值：1（ReadOnly），2（WriteOnly），3（AllIo）。 -+ 默认值：2 -+ 最小值：1 -+ 最大值：3 - -### `auto-tuned` - -+ 开启自动优化 Rate LImiter 的配置的开关。 -+ 默认值：false - -### `enable-pipelined-write` - -+ 开启 Pipelined Write 的开关。 -+ 默认值：true - -### `bytes-per-sync` - -+ 异步 Sync 限速速率。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `wal-bytes-per-sync` - -+ WAL Sync 限速速率，默认：512KB。 -+ 默认值：512KB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `info-log-max-size` - -+ Info 日志的最大大小。 -+ 默认值：1GB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `info-log-roll-time` - -+ 日志截断间隔时间，如果为0则不截断。 -+ 默认值：0 - -### `info-log-keep-log-file-num` - -+ 保留日志文件最大个数。 -+ 默认值：10 -+ 最小值：0 - -### `info-log-dir` - -+ 日志存储目录。 -+ 默认值："" - -## rocksdb.titan - -Titan 相关的配置项。 - -### `enabled` - -+ 开启 Titan 开关。 -+ 默认值：false - -### `dirname` - -+ Titan Blob 文件存储目录。 -+ 默认值：titandb - -### `disable-gc` - -+ 关闭 Titan 对 Blob 文件的 GC 的开关。 -+ 默认值：false - -### `max-background-gc` - -+ Titan 后台 GC 的线程个数。 -+ 默认值：1 -+ 最小值：1 - -## rocksdb.defaultcf - -rocksdb defaultcf 相关的配置项。 - -### `block-size` - -+ rocksdb block size。 -+ 默认值：64KB -+ 最小值：1KB -+ 单位：KB|MB|GB - -### `block-cache-size` - -+ rocksdb block cache size。 -+ 默认值：机器总内存 / 4 -+ 最小值：0 -+ 单位：KB|MB|GB - -### `disable-block-cache` - -+ 开启 block cache 开关。 -+ 默认值：false - -### `cache-index-and-filter-blocks` - -+ 开启 缓存 index 和 filter 的开关。 -+ 默认值：true - -### `pin-l0-filter-and-index-blocks` - -+ 是否 pin 住 L0 的 index 和 filter。 -+ 默认值：true - -### `use-bloom-filter` - -+ 开启 bloom filter 的开关。 -+ 默认值：true - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：true - -### `whole_key_filtering` - -+ 开启将整个 key 放到 bloom filter 中的开关。 -+ 默认值：true - -### `bloom-filter-bits-per-key` - -bloom filter 为每个 key 预留的长度。 - -+ 默认值：10 -+ 单位：字节 - -### `block-based-bloom-filter` - -+ 开启每个 block 建立 bloom filter 的开关。 -+ 默认值：false - -### `read-amp-bytes-per-bit` - -+ 开启读放大统计的开关，0：不开启，> 0 开启。 -+ 默认值：0 -+ 最小值：0 - -### `compression-per-level` - -+ 每一层默认压缩算法，默认：前两层为 No，后面 5 层为 lz4。 -+ 默认值：["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -### `write-buffer-size` - -+ memtable 大小。 -+ 默认值：128MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `max-write-buffer-number` - -+ 最大 memtable 个数。 -+ 默认值：5 -+ 最小值：0 - -### `min-write-buffer-number-to-merge` - -+ 触发 flush 的最小 memtable 个数。 -+ 默认值：1 -+ 最小值：0 - -### `max-bytes-for-level-base` - -+ base level (L1) 最大字节数，一般设置为 memtable 大小 4 倍。 -+ 默认值：512MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `target-file-size-base` - -+ base level 的目标文件大小。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `level0-file-num-compaction-trigger` - -+ 触发 compaction 的 L0 文件最大个数。 -+ 默认值：4 -+ 最小值：0 - -### `level0-slowdown-writes-trigger` - -+ 触发 write stall 的 L0 文件最大个数。 -+ 默认值：20 -+ 最小值：0 - -### `level0-stop-writes-trigger` - -+ 完全阻停写入的 L0 文件最大个数。 -+ 默认值：36 -+ 最小值：0 - -### `max-compaction-bytes` - -+ 一次 compaction 最大写入字节数，默认 2GB。 -+ 默认值：2GB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `compaction-pri` - -Compaction 优先类型，默认：3（MinOverlappingRatio），0（ByCompensatedSize）， -1（OldestLargestSeqFirst），2（OldestSmallestSeqFirst）。 - -+ 默认值：3 - -### `dynamic-level-bytes` - -+ 开启 dynamic level bytes 优化的开关。 -+ 默认值：true - -### `num-levels` - -+ RocksDB 文件最大层数。 -+ 默认值：7 - -### `max-bytes-for-level-multiplier` - -+ 每一层的默认放大倍数。 -+ 默认值：10 - -### `rocksdb.defaultcf.compaction-style` - -+ Compaction 方法，可选值为 level，universal。 -+ 默认值：level - -### `disable-auto-compactions` - -+ 开启自动 compaction 的开关。 -+ 默认值：false - -### `soft-pending-compaction-bytes-limit` - -+ pending compaction bytes 的软限制。 -+ 默认值：64GB -+ 单位：KB|MB|GB - -### `hard-pending-compaction-bytes-limit` - -+ pending compaction bytes 的硬限制。 -+ 默认值：256GB -+ 单位：KB|MB|GB - -## rocksdb.defaultcf.titan - -rocksdb defaultcf titan 相关的配置项。 - -### `min-blob-size` - -+ 最小存储在 Blob 文件中 value 大小，低于该值的 value 还是存在 LSM-Tree 中。 -+ 默认值：1KB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `blob-file-compression` - -+ Blob 文件所使用的压缩算法，可选值：no, snappy, zlib, bzip2, lz4, lz4hc, zstd。 -+ 默认值：lz4 - -### `blob-cache-size` - -+ Blob 文件的 cache 大小，默认：0GB。 -+ 默认值：0GB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `min-gc-batch-size` - -+ 做一次 GC 所要求的最低 Blob 文件大小总和。 -+ 默认值：16MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `max-gc-batch-size` - -+ 做一次 GC 所要求的最高 Blob 文件大小总和。 -+ 默认值：64MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `discardable-ratio` - -+ Blob 文件 GC 的触发比例，如果某 Blob 文件中的失效 value 的比例高于该值才可能被 GC 选中。 -+ 默认值：0.5 -+ 最小值：0 -+ 最大值：1 - -### `sample-ratio` - -+ 进行 GC 时，对 Blob 文件进行采样时读取数据占整个文件的比例。 -+ 默认值：0.1 -+ 最小值：0 -+ 最大值：1 - -### `merge-small-file-threshold` - -+ Blob 文件的大小小于该值时，无视 discardable-ratio 仍可能被 GC 选中。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：KB|MB|GB - -## rocksdb.writecf - -rocksdb writecf 相关的配置项。 - -### `block-cache-size` - -+ block cache size。 -+ 默认值：机器总内存 * 15% -+ 单位：MB|GB - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：false - -### `whole-key-filtering` - -+ 开启将整个 key 放到 bloom filter 中的开关。 -+ 默认值：false - -## rocksdb.lockcf - -rocksdb lockcf 相关配置项。 - -### `block-cache-size` - -+ block cache size。 -+ 默认值：机器总内存 * 2% -+ 单位：MB|GB - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：false - -### `level0-file-num-compaction-trigger` - -+ 触发 compaction 的 L0 文件个数。 -+ 默认值：1 - -## raftdb - -raftdb 相关配置项。 - -### `max-background-jobs` - -+ RocksDB 后台线程个数。 -+ 默认值：2 -+ 最小值：1 - -### `max-sub-compactions` - -+ RocksDB 进行 subcompaction 的并发数。 -+ 默认值：1 -+ 最小值：1 - -### `wal-dir` - -+ WAL 存储目录。 -+ 默认值：/tmp/tikv/store - -## security - -安全相关配置项。 - -### `ca-path` - -+ CA 文件路径 -+ 默认值："" - -### `cert-path` - -+ 包含 X509 证书的 PEM 文件路径 -+ 默认值："" - -### `key-path` - -+ 包含 X509 key 的 PEM 文件路径 -+ 默认值："" - -## import - -import 相关的配置项。 - -### `num-threads` - -+ 处理 RPC 请求线程数。 -+ 默认值：8 -+ 最小值：1 - -### `num-import-jobs` - -+ 并发导入工作任务数。 -+ 默认值：8 -+ 最小值：1 - -## pessimistic-txn - -### `enabled` - -+ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/dev/reference/transactions/transaction-pessimistic.md)。 -+ 默认值：true - -### `wait-for-lock-timeout` - -+ 悲观事务在 TiKV 中等待其他事务释放锁的最长时间，单位为毫秒。若超时则会返回错误给 TiDB 并由 TiDB 重试加锁，语句最长等锁时间由 `innodb_lock_wait_timeout` 控制。 -+ 默认值：1000 -+ 最小值：1 - -### `wait-up-delay-duration` - -+ 悲观事务释放锁时，只会唤醒等锁事务中 start ts 最小的事务，其他事务将会延迟 `wake-up-delay-duration` 毫秒之后被唤醒。 -+ 默认值：20 diff --git a/dev/reference/error-codes.md b/dev/reference/error-codes.md deleted file mode 100644 index b55a14b651be..000000000000 --- a/dev/reference/error-codes.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: 错误码与故障诊断 -category: reference ---- - -# 错误码与故障诊断 - -本篇文档描述在使用 TiDB 过程中会遇到的问题以及解决方法。 - -## 错误码 - -TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样的错误码。另外还有一些特有的错误码： - -| 错误码 | 说明 | -| --------------------- | -------------------------------------------------- | -| 8001 | 请求使用的内存超过 TiDB 内存使用的阈值限制 | -| 8002 | 带有 `SELECT FOR UPDATE` 语句的事务，在遇到写入冲突时，为保证一致性无法进行重试，事务将进行回滚并返回该错误 | -| 8003 | `ADMIN CHECK TABLE` 命令在遇到行数据跟索引不一致的时候返回该错误 | -| 8004 | 单个事务过大，原因及解决方法请参考[这里](/dev/faq/tidb.md#433-transaction-too-large-是什么原因怎么解决) | -| 8005 | 事务在 TiDB 中遇到了写入冲突，原因及解决方法请参考[这里](/dev/faq/tidb.md#九故障排除) | -| 8018 | 插件无法重新载入，原因是没有载入过 | -| 8019 | 重新载入的插件版本与之前不同，无法重新载入 | -| 8020 | 表被锁 | -| 8021 | key 不存在 | -| 8022 | 事务提交失败，但可以进行重试 | -| 8023 | 不能设置空值 | -| 8024 | 非法的事务 | -| 8025 | 写入的单条键值对过大 | -| 8026 | 没有实现的接口 | -| 8027 | 表结构版本过期 | -| 8028 | 表结构发生了变化 | -| 8029 | 错误值 | -| 8030 | 转变为带符号正整数时发生了越界，显示为负数 | -| 8031 | 负数转变为无符号数时，被转变为正数 | -| 8032 | 非法的 year 格式 | -| 8033 | 非法的 year 值 | -| 8034 | 不正确的 datetime 值 | -| 8036 | 非法的 time 格式 | -| 8037 | 非法的 week 格式 | -| 8038 | 字段无法获取到默认值 | -| 8039 | 索引的偏移量超出范围 | -| 8042 | 表结构的状态为不存在 | -| 8043 | 列信息的状态为不存在 | -| 8044 | 索引的状态为不存在 | -| 8045 | 非法的表数据 | -| 8046 | 列信息的状态为不可见 | -| 8047 | 设置了不支持的系统变量值，通常在用户设置了数据库不支持的变量值后的告警信息里出现 | -| 8048 | 设置了不支持的数据库隔离级别 | -| 8049 | 载入权限相关表失败 | -| 8050 | 设置了不支持的权限类型 | -| 8051 | 未知的字段类型 | -| 8052 | 来自客户端的数据包的序列号错误 | -| 8053 | 获取到了非法的自增列值 | -| 8055 | 当前快照过旧，数据可能已经被 GC | -| 8056 | 非法的表 ID | -| 8057 | 非法的字段类型 | -| 8058 | 申请了不存在的自动变量类型 | -| 8059 | 获取自动随机量失败 | -| 8060 | 非法的自增列偏移量 | -| 8061 | 不支持的 SQL Hint | -| 8062 | SQL Hint 中使用了非法的 token，与 Hint 的保留字冲突 | -| 8063 | SQL Hint 中限制内存使用量超过系统设置的上限，设置被忽略 | -| 8064 | 解析 SQL Hint 失败 | -| 8065 | SQL Hint 中使用了非法的整数 | -| 8066 | JSON_OBJECTAGG 函数的第二个参数是非法参数 | -| 8101 | 插件 ID 格式错误，正确的格式是 `[name]-[version]` 并且 name 和 version 中不能带有 '-' | -| 8102 | 无法读取插件定义信息 | -| 8103 | 插件名称错误 | -| 8104 | 插件版本不匹配 | -| 8105 | 插件被重复载入 | -| 8106 | 插件定义的系统变量名称没有以插件名作为开头 | -| 8107 | 载入的插件未指定版本或指定的版本过低 | -| 8108 | 不支持的执行计划类型 | -| 8109 | analyze 索引时找不到指定的索引 | -| 8110 | 不能进行笛卡尔积运算，需要将配置文件里的 `cross-join` 设置为 `true` | -| 8111 | execute 语句执行时找不到对应的 prepare 语句 | -| 8112 | execute 语句的参数个数与 prepare 语句不符合 | -| 8113 | execute 语句涉及的表结构在 prepare 语句执行后发生了变化 | -| 8114 | 未知的执行计划类型 | -| 8115 | 不支持 prepare 多行语句 | -| 8116 | 不支持 prepare DDL 语句 | -| 8118 | 构建执行器失败 | -| 8120 | 获取不到事务的 start tso | -| 8121 | 权限检查失败 | -| 8122 | 指定了通配符，但是找不到对应的表名 | -| 8123 | 带聚合函数的 SQL 中返回非聚合的列，违反了 only_full_group_by 模式 | -| 8200 | 尚不支持的 DDL 语法 | -| 8201 | 当前 TiDB 不是 DDL owner | -| 8202 | 不能对该索引解码 | -| 8203 | 非法的 DDL worker | -| 8204 | 非法的 DDL job | -| 8205 | 非法的 DDL job 标志 | -| 8206 | DDL 的 Reorg 阶段执行超时 | -| 8207 | 非法的存储节点 | -| 8210 | 非法的 DDL 状态 | -| 8211 | DDL 的 Reorg 阶段发生了 panic | -| 8212 | 非法的 region 切分范围 | -| 8213 | 非法的 DDL job 版本 | -| 8214 | DDL 操作被终止 | -| 8215 | Admin Repair 表失败 | -| 8216 | 非法的自动随机列 | -| 8221 | Key 编码错误 | -| 8222 | 索引 Key 编码错误 | -| 8223 | 检测出数据与索引不一致的错误 | -| 8224 | 找不到 DDL job | -| 8225 | DDL 已经完成，无法被取消 | -| 8226 | DDL 几乎要完成了，无法被取消 | -| 8227 | 创建 Sequence 时使用了不支持的选项 | -| 9001 | 请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络 | -| 9002 | 请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络 | -| 9003 | TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志 | -| 9004 | 当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码 | -| 9005 | 某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志 | -| 9006 | GC Life Time 间隔时间过短，长事务本应读到的数据可能被清理了，应增加 GC Life Time | -| 9007 | 事务在 TiKV 中遇到了写入冲突，原因及解决方法请参考[这里](/dev/faq/tidb.md#九故障排除) | -| 9008 | 同时向 TiKV 发送的请求过多，超过了限制 | - -## 故障诊断 - -参见[故障诊断文档](/dev/how-to/troubleshoot/cluster-setup.md)以及 [FAQ](/dev/faq/tidb.md)。 diff --git a/dev/reference/garbage-collection/configuration.md b/dev/reference/garbage-collection/configuration.md deleted file mode 100644 index 2a7449fcae4d..000000000000 --- a/dev/reference/garbage-collection/configuration.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: GC 配置 -category: reference ---- - -# GC 配置 - -TiDB 的 GC 相关的配置存储于 `mysql.tidb` 系统表中，可以通过 SQL 语句对这些参数进行查询和更改： - -{{< copyable "sql" >}} - -```sql -select VARIABLE_NAME, VARIABLE_VALUE from mysql.tidb; -``` - -``` -+--------------------------+----------------------------------------------------------------------------------------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+--------------------------+----------------------------------------------------------------------------------------------------+ -| bootstrapped | True | -| tidb_server_version | 33 | -| system_tz | UTC | -| tikv_gc_leader_uuid | 5afd54a0ea40005 | -| tikv_gc_leader_desc | host:tidb-cluster-tidb-0, pid:215, start at 2019-07-15 11:09:14.029668932 +0000 UTC m=+0.463731223 | -| tikv_gc_leader_lease | 20190715-12:12:14 +0000 | -| tikv_gc_enable | true | -| tikv_gc_run_interval | 10m0s | -| tikv_gc_life_time | 10m0s | -| tikv_gc_last_run_time | 20190715-12:09:14 +0000 | -| tikv_gc_safe_point | 20190715-11:59:14 +0000 | -| tikv_gc_auto_concurrency | true | -| tikv_gc_mode | distributed | -+--------------------------+----------------------------------------------------------------------------------------------------+ -13 rows in set (0.00 sec) -``` - -例如，如果需要将 GC 调整为保留最近一天以内的数据，只需执行下列语句即可： - -{{< copyable "sql" >}} - -```sql -update mysql.tidb set VARIABLE_VALUE="24h" where VARIABLE_NAME="tikv_gc_life_time"; -``` - -> **注意：** -> -> `mysql.tidb` 系统表中除了下文将要列出的 GC 的配置以外，还包含一些 TiDB 用于储存部分集群状态（包括 GC 状态）的记录。请勿手动更改这些记录。其中，与 GC 有关的记录如下： -> -> - `tikv_gc_leader_uuid`，`tikv_gc_leader_desc` 和 `tikv_gc_leader_lease` 用于记录 GC leader 的状态 -> - `tikv_gc_last_run_time`：上次 GC 运行时间 -> - `tikv_gc_safe_point`：当前 GC 的 safe point - -## `tikv_gc_enable` - -- 控制是否启用 GC。 -- 默认值：`true` - -## `tikv_gc_run_interval` - -- 指定 GC 运行时间间隔。Duration 类型，使用 Go 的 Duration 字符串格式，如 `"1h30m"`，`"15m"` 等。 -- 默认值：`"10m0s"` - -## `tikv_gc_life_time` - -- 每次 GC 时，保留数据的时限。Duration 类型。每次 GC 时将以当前时间减去该配置的值作为 safe point。 -- 默认值：`"10m0s"` - -> **注意：** -> -> - `tikv_gc_life_time` 的值必须大于 TiDB 的配置文件中的 [`max-txn-time-use`](/dev/reference/configuration/tidb-server/configuration-file.md#max-txn-time-use) 的值至少 10 秒，且不低于 10 分钟。 -> -> - 在数据更新频繁的场景下，如果将 `tikv_gc_life_time` 设置得比较大（如数天甚至数月），可能会有一些潜在的问题，如： -> - 磁盘空间占用较多。 -> - 大量的历史版本会在一定程度上影响性能，尤其是范围查询（如 `select count(*) from t`）。 - -## `tikv_gc_mode` - -指定 GC 模式。可选值如下： - -- `"distributed"`（默认）：分布式 GC 模式。在此模式下，[Do GC](/dev/reference/garbage-collection/overview.md#do-gc) 阶段由 TiDB 上的 GC leader 向 PD 发送 safe point，每个 TiKV 节点各自获取该 safe point 并对所有当前节点上作为 leader 的 Region 进行 GC。此模式于 TiDB 3.0 引入。 - -- `"central"`：集中 GC 模式。在此模式下，[Do GC](/dev/reference/garbage-collection/overview.md#do-gc) 阶段由 GC leader 向所有的 Region 发送 GC 请求。TiDB 2.1 及更早版本采用此 GC 模式。 - -## `tikv_gc_auto_concurrency` - -控制是否由 TiDB 自动决定 GC concurrency，即同时进行 GC 的线程数。 - -当 `tikv_gc_mode` 设为 `"distributed"`，GC concurrency 将应用于 [Resolve Locks](/dev/reference/garbage-collection/overview.md#resolve-locks) 阶段。当 [`tikv_gc_mode`](#tikv_gc_mode) 设为 `"central"` 时，GC concurrency 将应用于 Resolve Locks 以及 [Do GC](/dev/reference/garbage-collection/overview.md#do-gc) 两个阶段。 - -- `true`（默认）：自动以 TiKV 节点的个数作为 GC concurrency -- `false`：使用 [`tikv_gc_concurrency`](#tikv_gc_concurrency) 的值作为 GC 并发数 - -## `tikv_gc_concurrency` - -- 手动设置 GC concurrency。要使用该参数，必须将 [`tikv_gc_auto_concurrency`](#tikv_gc_auto_concurrency) 设为 `false` 。 -- 默认值：2 - -## 关于 GC 流程的说明 - -从 TiDB 3.0 版本起，由于对分布式 GC 模式和并行 Resolve Locks 的支持，部分配置选项的作用发生了变化。可根据下表理解不同版本中这些配置的区别： - -| 版本/配置 | Resolve Locks | Do GC | -|-------------------|---------------|----------------| -| 2.x | 串行 | 并行 | -| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = false` | 并行 | 并行 | -| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = true` | 自动并行 | 自动并行 | -| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = false` | 并行 | 分布式 | -| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = true`
（默认配置） | 自动并行 | 分布式 | - -表格内容说明： - -- 串行：由 TiDB 逐个向 Region 发送请求。 -- 并行：使用 `tikv_gc_concurrency` 选项所指定的线程数，并行地向每个 Region 发送请求。 -- 自动并行：使用 TiKV 节点的个数作为线程数，并行地向每个 Region 发送请求。 -- 分布式：无需 TiDB 通过对 TiKV 发送请求的方式来驱动，而是每台 TiKV 自行工作。 - -## 流控 - -TiKV 在 3.0.6 版本开始支持 GC 流控，可通过配置 `gc.max-write-bytes-per-sec` 限制 GC worker 每秒数据写入量，降低对正常请求的影响，`0` 为关闭该功能。该配置可通过 tikv-ctl 动态修改： - -{{< copyable "shell-regular" >}} - -```bash -tikv-ctl --host=ip:port modify-tikv-config -m server -n gc.max_write_bytes_per_sec -v 10MB -``` diff --git a/dev/reference/garbage-collection/overview.md b/dev/reference/garbage-collection/overview.md deleted file mode 100644 index 00c86883f616..000000000000 --- a/dev/reference/garbage-collection/overview.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: GC 机制简介 -category: reference ---- - -# GC 机制简介 - -TiDB 的事务的实现采用了 MVCC（多版本并发控制）机制，当新写入的数据覆盖旧的数据时，旧的数据不会被替换掉，而是与新写入的数据同时保留，并以时间戳来区分版本。GC 的任务便是清理不再需要的旧数据。 - -## 整体流程 - -一个 TiDB 集群中会有一个 TiDB 实例被选举为 GC leader，GC 的运行由 GC leader 来控制。 - -GC 会被定期触发，默认情况下每 10 分钟一次。每次 GC 时，首先，TiDB 会计算一个称为 safe point 的时间戳（默认为当前时间减去 10 分钟），接下来 TiDB 会在保证 safe point 之后的快照全部拥有正确数据的前提下，删除更早的过期数据。具体而言，分为以下三个步骤： - -1. Resolve Locks -2. Delete Ranges -3. Do GC - -### Resolve Locks - -TiDB 的事务是基于 [Google Percolator](https://ai.google/research/pubs/pub36726) 模型实现的，事务的提交是一个两阶段提交的过程。第一阶段完成时，所有涉及的 key 会加上一个锁，其中一个锁会被设定为 Primary，其余的锁（Secondary）则会指向 Primary；第二阶段会将 Primary 锁所在的 key 加上一个 Write 记录，并去除锁。这里的 Write 记录就是历史上对该 key 进行写入或删除，或者该 key 上发生事务回滚的记录。Primary 锁被替换为何种 Write 记录标志着该事务提交成功与否。接下来，所有 Secondary 锁也会被依次替换。如果替换这些 Secondary 锁的线程死掉了，锁就残留了下来。 - -Resolve Locks 这一步的任务即对 safe point 之前的锁进行回滚或提交，取决于其 Primary 是否被提交。如果一个 Primary 锁也残留了下来，那么该事务应当视为超时并进行回滚。这一步是必不可少的，因为如果其 Primary 的 Write 记录由于太老而被 GC 清除掉了，那么就再也无法知道该事务是否成功。如果该事务存在残留的 Secondary 锁，那么也无法知道它应当被回滚还是提交，也就无法保证一致性。 - -Resolve Locks 的执行方式是由 GC leader 对所有的 Region 发送请求进行处理。从 3.0 起，这个过程默认会并行地执行，并发数量默认与 TiKV 节点个数相同。 - -### Delete Ranges - -在执行 `DROP TABLE/INDEX` 等操作时，会有大量连续的数据被删除。如果对每个 key 都进行删除操作、再对每个 key 进行 GC 的话，那么执行效率和空间回收速度都可能非常的低下。事实上，这种时候 TiDB 并不会对每个 key 进行删除操作，而是将这些待删除的区间及删除操作的时间戳记录下来。Delete Ranges 会将这些时间戳在 safe point 之前的区间进行快速的物理删除。 - -### Do GC - -这一步即删除所有 key 的过期版本。为了保证 safe point 之后的任何时间戳都具有一致的快照，这一步删除 safe point 之前提交的数据，但是会保留 safe point 前的最后一次写入（除非最后一次写入是删除）。 - -TiDB 2.1 及更早版本使用的 GC 方式是由 GC leader 向所有 Region 发送 GC 请求。从 3.0 起，GC leader 只需将 safe point 上传至 PD。每个 TiKV 节点都会各自从 PD 获取 safe point。当 TiKV 发现 safe point 发生更新时，便会对当前节点上所有作为 leader 的 Region 进行 GC。与此同时，GC leader 可以继续触发下一轮 GC。 - -> **注意：** -> -> 通过修改配置可以继续使用旧的 GC 方式，详情请参考 [GC 配置](/dev/reference/garbage-collection/configuration.md)。 diff --git a/dev/reference/key-monitoring-metrics/overview-dashboard.md b/dev/reference/key-monitoring-metrics/overview-dashboard.md deleted file mode 100644 index d5ff54a8d647..000000000000 --- a/dev/reference/key-monitoring-metrics/overview-dashboard.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Overview 面板重要监控指标详解 -category: reference ---- - -# Overview 面板重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/dev/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们单独挑选出重要的 Metrics 放在 Overview 页面，方便日常运维人员观察集群组件 (PD, TiDB, TiKV) 使用状态以及集群使用状态。 - -以下为 Overview Dashboard 监控说明： - -## Services Port Status - -- Services Online：各服务在线节点数量 -- Services Offline：各服务 Down 掉节点数量 - -## PD - -- Storage Capacity：TiDB 集群总可用数据库空间大小 -- Current Storage Size：TiDB 集群目前已用数据库空间大小 -- Number of Regions：当前集群的 Region 总量 -- Leader Balance Ratio：Leader 数量最多和最少节点相差的百分比，一般小于 5%，节点重启时会有比较大的波动 -- Region Balance Ratio：Region 数量最多和最少节点相差的百分比，一般小于 5%，新增/下线节点时相差比较大 -- Store Status：集群 TiKV 节点的状态 - - Up Stores：正常运行的 TiKV 节点数量 - - Disconnect Stores：短时间内通信异常的 TiKV 节点数量 - - LowSpace Stores：剩余可用空间小于 20% 的 TiKV 节点数量 - - Down Stores：停止工作的 TiKV 节点数量，如果大于 0，说明有节点不正常 - - Offline Stores：正在下线的 TiKV 节点数量（正在下线的 TiKV 节点还在提供服务） - - Tombstone Stores：下线成功的 TiKV 节点数量 -- 99% completed\_cmds\_duration\_seconds：单位时间内，99% 的 pd-server 请求执行时间小于监控曲线的值，一般 <= 5ms -- handle\_requests\_duration\_seconds：PD 发送请求的网络耗时 - -## TiDB - -- Statement OPS：SQL 执行数量统计（包含 select、insert、update 等） -- Duration：SQL 执行的时间 -- QPS By Instance：每个 TiDB 上的 QPS -- Failed Query OPM：失败 SQL 的统计，例如语法错误、主键冲突等 -- Connection count：每个 TiDB 的连接数 -- Heap Memory Usage：每个 TiDB 使用的堆内存大小 -- Transaction OPS：事务执行数量统计 -- Transaction Duration：事务执行的时间 -- KV Cmd OPS：KV 命令执行数量统计 -- KV Cmd Duration 99：KV 命令执行的时间 -- PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 -- PD TSO Wait Duration：TiDB 从 PD 获取 TS 的时间 -- TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 -- Lock Resolve OPS：事务冲突相关的数量 -- Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 -- KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - -## TiKV - -- leader：各个 TiKV 节点上 Leader 的数量分布 -- region：各个 TiKV 节点上 Region 的数量分布 -- CPU：各个 TiKV 节点的 CPU 使用率 -- Memory：各个 TiKV 节点的内存使用量 -- store size：各个 TiKV 节点存储的数据量 -- cf size：集群不同 CF 存储的数据量 -- channel full：正常情况显示 No data，如果有了监控值，说明对应 TiKV 节点的消息处理不过来了 -- server report failures：正常情况显示 No data，如果出现了 Unreachable，说明 TiKV 之间通信有问题 -- scheduler pending commands：写入堆积的数量，偶尔出现峰值属于正常现象 -- coprocessor pending requests：正常情况监控为 0 或者数量很少 -- coprocessor executor count：不同类型的查询操作数量 -- coprocessor request duration：TiKV 中查询消耗的时间 -- raft store CPU：raftstore 线程的 CPU 使用率，线程数量默认为 2 (通过 `raftstore.store-pool-size` 配置)。如果单个线程使用率超过 80%，说明使用率很高 -- Coprocessor CPU：TiKV 查询线程的 CPU 使用率，和业务相关，复杂查询会使用大量的 CPU 资源 - -## System Info - -- Vcores：CPU 核心数量 -- Memory：内存总大小 -- CPU Usage：CPU 使用率，最大为 100% -- Load [1m]：1 分钟的负载情况 -- Memory Available：剩余内存大小 -- Network Traffic：网卡流量统计 -- TCP Retrans：网络监控，TCP 相关信息统计 -- IO Util：磁盘使用率，最高为 100%，一般到 80% - 90% 就需要考虑加节点 - -## 图例 - -![overview](/media/overview.png) diff --git a/dev/reference/key-monitoring-metrics/pd-dashboard.md b/dev/reference/key-monitoring-metrics/pd-dashboard.md deleted file mode 100644 index 7c93efdfaf64..000000000000 --- a/dev/reference/key-monitoring-metrics/pd-dashboard.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: PD 重要监控指标详解 -category: reference ---- - -# PD 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/dev/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 PD 面板上的 Metrics，可以了解 PD 当前的状态。 - -以下为 PD Dashboard 监控说明： - -## Cluster - -- PD role：当前 PD 的角色 -- Storage capacity：TiDB 集群总可用数据库空间大小 -- Current storage size：TiDB 集群目前已用数据库空间大小 -- Current storage usage：TiDB 集群存储空间的使用率 -- Normal stores：处于正常状态的节点数目 -- Number of Regions：当前集群的 Region 总量 -- PD scheduler config：PD 调度配置列表 -- Region label isolation level：不同 label 所在的 level 的 Region 数量 -- Label distribution：集群中 TiKV 节点的 label 分布情况 -- Abnormal stores：处于异常状态的节点数目，正常情况应当为 0 -- pd_cluster_metadata：记录集群 ID，时间戳和生成的 ID -- Current peer count：当前集群 peer 的总量 -- Region health：每个 Region 的状态，通常情况下，pending 的 peer 应该少于 100，miss 的 peer 不能一直大于 0 - -![PD Dashboard - Cluster metrics](/media/pd-dashboard-cluster-v2.png) - -## Operator - -- Schedule operator create：新创建的不同 operator 的数量 -- Schedule operator check：已检查的 operator 的数量，主要检查是否当前步骤已经执行完成，如果是，则执行下一个步骤 -- Schedule operator finish：已完成调度的 operator 的数量 -- Schedule operator timeout：已超时的 operator 的数量 -- Schedule operator replaced or canceled：已取消或者被替换的 operator 的数量 -- Schedule operators count by state：不同状态的 operator 的数量 -- 99% Operator finish duration：99% 已完成 operator 所花费的最长时间 -- 50% Operator finish duration：50% 已完成 operator 所花费的最长时间 -- 99% Operator step duration：99% 已完成的 operator 步骤所花费的最长时间 -- 50% Operator step duration：50% 已完成的 operator 步骤所花费的最长时间 - -![PD Dashboard - Operator metrics](/media/pd-dashboard-operator-v2.png) - -## Statistics - Balance - -- Store capacity：每个 TiKV 实例的总的空间大小 -- Store available：每个 TiKV 实例的可用空间大小 -- Store used：每个 TiKV 实例的已使用空间大小 -- Size amplification：每个 TiKV 实例的空间放大比率 -- Size available ratio：每个 TiKV 实例的可用空间比率 -- Store leader score：每个 TiKV 实例的 leader 分数 -- Store Region score：每个 TiKV 实例的 Region 分数 -- Store leader size：每个 TiKV 实例上所有 leader 的大小 -- Store Region size：每个 TiKV 实例上所有 Region 的大小 -- Store leader count：每个 TiKV 实例上所有 leader 的数量 -- Store Region count：每个 TiKV 实例上所有 Region 的数量 - -![PD Dashboard - Balance metrics](/media/pd-dashboard-balance-v2.png) - -## Statistics - hotspot - -- Hot write Region's leader distribution：每个 TiKV 实例上是写入热点的 leader 的数量 -- Hot write Region's peer distribution：每个 TiKV 实例上是写入热点的 peer 的数量 -- Hot write Region's leader written bytes：每个 TiKV 实例上热点的 leader 的写入大小 -- Hot write Region's peer written bytes：每个 TiKV 实例上热点的 peer 的写入大小 -- Hot read Region's leader distribution：每个 TiKV 实例上是读取热点的 leader 的数量 -- Hot read Region's peer distribution：每个 TiKV 实例上是读取热点的 peer 的数量 -- Hot read Region's leader read bytes：每个 TiKV 实例上热点的 leader 的读取大小 -- Hot read Region's peer read bytes：每个 TiKV 实例上热点的 peer 的读取字节数 - -![PD Dashboard - Hotspot metrics](/media/pd-dashboard-hotspot.png) - -## Scheduler - -- Scheduler is running：所有正在运行的 scheduler -- Balance leader movement：leader 移动的详细情况 -- Balance Region movement：Region 移动的详细情况 -- Balance leader event：balance leader 的事件数量 -- Balance Region event：balance Region 的事件数量 -- Balance leader scheduler：balance-leader scheduler 的状态 -- Balance Region scheduler：balance-region scheduler 的状态 -- Namespace checker：namespace checker 的状态 -- Replica checker：replica checker 的状态 -- Region merge checker：merge checker 的状态 -- Filter target：尝试选择 Store 作为调度 taget 时没有通过 Filter 的计数 -- Filter source：尝试选择 Store 作为调度 source 时没有通过 Filter 的计数 -- Balance Direction：Store 被选作调度 target 或 source 的次数 -- Store Limit：Store 的调度限流状态 - -![PD Dashboard - Scheduler metrics](/media/pd-dashboard-scheduler-v2.png) - -## gRPC - -- Completed commands rate：gRPC 命令的完成速率 -- 99% Completed commands duration：99% 命令的最长消耗时间 - -![PD Dashboard - gRPC metrics](/media/pd-dashboard-grpc-v2.png) - -## etcd - -- Handle transactions count：etcd 的事务个数 -- 99% Handle transactions duration：99% 的情况下，处理 etcd 事务所需花费的时间 -- 99% WAL fsync duration：99% 的情况下，持久化 WAL 所需花费的时间，这个值通常应该小于 1s -- 99% Peer round trip time seconds：99% 的情况下，etcd 的网络延时，这个值通常应该小于 1s -- etcd disk WAL fsync rate：etcd 持久化 WAL 的速率 -- Raft term：当前 Raft 的 term -- Raft committed index：最后一次 commit 的 Raft index -- Raft applied index：最后一次 apply 的 Raft index - -![PD Dashboard - etcd metrics](/media/pd-dashboard-etcd-v2.png) - -## TiDB - -- Handle requests count：TiDB 的请求数量 -- Handle requests duration：每个请求所花费的时间，99% 的情况下，应该小于 100ms - -![PD Dashboard - TiDB metrics](/media/pd-dashboard-tidb-v2.png) - -## Heartbeat - -- Region heartbeat report：TiKV 向 PD 发送的心跳个数 -- Region heartbeat report error：TiKV 向 PD 发送的异常的心跳个数 -- Region heartbeat report active：TiKV 向 PD 发送的正常的心跳个数 -- Region schedule push：PD 向 TiKV 发送的调度命令的个数 -- 99% Region heartbeat latency：99% 的情况下，心跳的延迟 - -![PD Dashboard - Heartbeat metrics](/media/pd-dashboard-heartbeat-v2.png) - -## Region storage - -- Syncer Index：Leader 记录 Region 变更历史的最大 index -- history last index：Follower 成功同步的 Region 变更历史的 index - -![PD Dashboard - Region storage](/media/pd-dashboard-region-storage.png) diff --git a/dev/reference/key-monitoring-metrics/tidb-dashboard.md b/dev/reference/key-monitoring-metrics/tidb-dashboard.md deleted file mode 100644 index 36e7a0a9f8bb..000000000000 --- a/dev/reference/key-monitoring-metrics/tidb-dashboard.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: TiDB 重要监控指标详解 -category: reference ---- - -# TiDB 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/dev/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等，TiDB 分为 TiDB 和 TiDB Summary 面板（其中 TiDB 面板包含 TiDB Summary 面板的内容）。 - -以下为 TiDB Dashboard 部分监控说明： - -## 说明 - -- Query Summary - - Duration：SQL 执行的时间 - - QPS：每个 TiDB 上的 SQL 执行结果按照 OK/Error 统计 - - Statement OPS：SQL 执行数量统计（包含 `SELECT`、`INSERT`、`UPDATE` 等） - - QPS By Instance：每个 TiDB 上的 QPS - - Failed Query OPM：每个 TiDB 实例上，执行 SQL 语句发生错误按照错误类型的统计（例如语法错误、主键冲突等） - - Slow query：慢查询处理时间统计（整个慢查询耗时、Coprocessor 耗时、Coprocessor 调度等待时间） - - 999/99/95/80 Duration：不同类型的 SQL 语句执行耗时统计（不同百分位） - -- Query Detail - - Duration 80/95/99/999 By Instance：每个 TiDB 实例执行 SQL 语句的耗时统计（不同百分位） - - Failed Query OPM Detail：整个集群执行 SQL 语句发生的错误按照错误类型统计（例如语法错误、主键冲突等） - - Internal SQL OPS：TiDB 内部 SQL 语句执行数量统计 - -- Server - - Uptime：TiDB 运行时间 - - Memory Usage：不同 TiDB 实例的内存使用统计 - - CPU Usage：不同 TiDB 实例的 CPU 使用统计 - - Connection Count：每个 TiDB 的连接数 - - Open FD Count：不同 TiDB 实例的打开的文件描述符统计 - - Goroutine Count：不同 TiDB 实例的 Goroutine 数量 - - Go GC Duration：不同 TiDB 实例的 GC 耗时统计 - - Go Threads：不同 TiDB 实例的线程数量 - - Go GC Count：不同 TiDB 实例的 GC 执行次数统计 - - Go GC CPU Usage：不同 TiDB 实例的 GC CPU 统计 - - Events OPM：统计关键事件，例如 start，close，graceful-shutdown，kill，hang 等 - - Keep Alive OPM：不同 TiDB 实例每分钟刷新监控的次数 - - Prepare Statement Count：不同 TiDB 实例执行 Prepare 语句数以及总数统计 - - Time Jump Back OPS：不同 TiDB 实例上每秒钟时间回跳的次数 - - Heap Memory Usage：每个 TiDB 使用的堆内存大小 - - Uncommon Error OPM：TiDB 非正常错误的统计，包括 panic，binlog 写失败等 - - Handshake Error OPS：不同 TiDB 实例每秒握手错误的次数统计 - - Get Token Duration：建立连接后获取 Token 耗时 - -- Transaction - - Transaction OPS：事务执行数量统计 - - Duration：事务执行的时间 - - Transaction Retry Num：事务重试次数 - - Transaction Statement Num：一个事务中的 SQL 语句数量 - - Session Retry Error OPS：事务重试时遇到的错误数量 - - Local Latch Wait Duration：本地事务等待时间 - -- Executor - - Parse Duration：SQL 语句解析耗时统计 - - Compile Duration：将 SQL AST 编译成执行计划耗时统计 - - Execution Duration：SQL 语句执行耗时统计 - - Expensive Executor OPS：消耗系统资源比较多的算子统计，包括 Merge Join，Hash Join，Index Look Up Join，Hash Agg，Stream Agg，Sort，TopN 等 - - Queries Using Plan Cache OPS：使用 Plan Cache 的查询数量统计 - -- Distsql - - Distsql Duration：Distsql 处理的时长 - - Distsql QPS：Distsql 的数量统计 - - Distsql Partial QPS：每秒 Partial Results 的数量 - - Scan Keys Num：每个 Query 扫描的 Key 的数量 - - Scan Keys Partial Num：每一个 Partial Result 扫描的 Key 的数量 - - Partial Num：每个 SQL 语句 Partial Results 的数量 - -- KV Errors - - KV Retry Duration：KV 重试请求的时间 - - TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 - - KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - - Lock Resolve OPS：事务冲突相关的数量 - - Other Errors OPS：其他类型的错误数量，包括清锁和更新 SafePoint - -- KV Duration - - KV Request Duration 999 by store：KV Request 执行时间，根据 TiKV 显示 - - KV Request Duration 999 by type：KV Request 执行时间，根据请求类型显示 - - KV Cmd Duration 99/999：KV 命令执行的时间 - -- KV Count - - KV Cmd OPS：KV 命令执行数量统计 - - KV Txn OPS：启动事务的数量统计 - - Txn Regions Num 90：事务使用的 Region 数量统计 - - Txn Write Size Bytes 100：事务写入的字节数统计 - - Txn Write KV Num 100：事务写入的 KV 数量统计 - - Load SafePoint OPS：更新 SafePoint 的数量统计 - -- PD Client - - PD Client CMD OPS：PD Client 执行命令数量统计 - - PD Client CMD Duration: PD Client 执行命令耗时 - - PD Client CMD Fail OPS：PD Client 执行命令失败统计 - - PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 - - PD TSO Wait Duration：TiDB 从 PD 获取 TSO 的时间 - - PD TSO RPC Duration：TiDB 从调用 PD 获取 TSO gRPC 接口花费的时间 - -- Schema Load - - Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 - - Load Schema OPS：TiDB 从 TiKV 获取 Schema 的数量统计 - - Schema Lease Error OPM：Schema Lease 出错，包括 change 和 outdate 两种，出现 outdate 错误时会报警 - -- DDL - - DDL Duration 95：DDL 语句处理时间统计 - - Batch Add Index Duration 100：创建索引时每个 Batch 所花费的时间统计 - - DDL Waiting Jobs Count：等待的 DDL 任务数量 - - DDL META OPM：DDL 每分钟获取 META 的次数 - - Deploy Syncer Duration：Schema Version Syncer 初始化，重启，清空等操作耗时 - - Owner Handle Syncer Duration：DDL Owner 在执行更新，获取以及检查 Schema Version 的耗时 - - Update Self Version Duration：Schema Version Syncer 更新版本信息耗时 - -- Statistics - - Auto Analyze Duration 95：自动 ANALYZE 耗时统计 - - Auto Analyze QPS：自动 ANALYZE 数量统计 - - Stats Inaccuracy Rate：统计信息不准确度统计 - - Pseudo Estimation OPS：使用假的统计信息优化 SQL 的数量统计 - - Dump Feedback OPS：存储统计信息 Feedback 的数量统计 - - Update Stats OPS：利用 Feedback 更新统计信息的数量统计 - - Significant Feedback：重要的 Feedback 更新统计信息的数量统计 - -- Meta - - AutoID QPS：AutoID 相关操作的数量统计，包括全局 ID 分配、单个 Table AutoID 分配、单个 Table AutoID Rebase 三种操作 - - AutoID Duration：AutoID 相关操作的耗时 - - Meta Operations Duration 99：Meta 操作延迟 - -- GC - - Worker Action OPM：GC 相关操作的数量统计，包括 run\_job，resolve\_lock，delete\_range 等操作 - - Duration 99：GC 相关操作的耗时统计 - - GC Failure OPM：GC 相关操作失败数量统计 - - Action Result OPM：GC 相关操作结果数量统计 - - Too Many Locks Error OPM：GC 清锁过多错误的数量统计 - -- Batch Client - - Pending Request Count by TiKV：等待处理的 Batch 消息数量统计 - - Wait Duration 95：等待处理的 Batch 消息延迟统计 - - Batch Client Unavailable Duration 95：Batch 客户端不可用的时间统计 diff --git a/dev/reference/key-monitoring-metrics/tikv-dashboard.md b/dev/reference/key-monitoring-metrics/tikv-dashboard.md deleted file mode 100644 index 887d27c7a072..000000000000 --- a/dev/reference/key-monitoring-metrics/tikv-dashboard.md +++ /dev/null @@ -1,429 +0,0 @@ ---- -title: TiKV 重要监控指标详解 -category: reference ---- - -# TiKV 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/dev/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 TiKV 面板上的 Metrics，可以了解 TiKV 当前的状态。 - -以下为 TiKV Dashboard 监控说明： - -## Cluster - -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Available size：每个 TiKV 实例的可用的存储空间的大小 -- Capacity size：每个 TiKV 实例的存储容量的大小 -- CPU：每个 TiKV 实例 CPU 的使用率 -- Memory：每个 TiKV 实例内存的使用情况 -- IO utilization：每个 TiKV 实例 IO 的使用率 -- MBps：每个 TiKV 实例写入和读取的数据量大小 -- QPS：每个 TiKV 实例上各种命令的 QPS -- Errps：每个 TiKV 实例上 gRPC 消息失败的个数 -- leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 - -![TiKV Dashboard - Cluster metrics](/media/tikv-dashboard-cluster.png) - -## Errors - -- Server is busy：各种会导致 server 繁忙的事件个数，如 write stall，channel full 等，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Raftstore error：每个 TiKV 实例上 raftstore 发生错误的个数 -- Scheduler error：每个 TiKV 实例上 scheduler 发生错误的个数 -- Coprocessor error：每个 TiKV 实例上 coprocessor 发生错误的个数 -- gRPC message error：每个 TiKV 实例上 gRPC 消息发生错误的个数 -- Leader drop：每个 TiKV 实例上 drop leader 的个数 -- Leader missing：每个 TiKV 实例上 missing leader 的个数 - -![TiKV Dashboard - Errors metrics](/media/tikv-dashboard-errors.png) - -## Server - -- Leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 -- CF size：每个 CF 的大小 -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Channel full：每个 TiKV 实例上 channel full 错误的数量，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Region average written keys：每个 TiKV 实例上所有 Region 的平均 key 写入个数 -- Region average written bytes：每个 TiKV 实例上所有 Region 的平均写入大小 -- Active written leaders：每个 TiKV 实例上有效的 leader 个数 -- Approximate Region size：每个 Region 近似的大小 - -![TiKV Dashboard - Server metrics](/media/tikv-dashboard-server.png) - -## Raft IO - -- Apply log duration：Raft apply 日志所花费的时间 -- Apply log duration per server：每个 TiKV 实例上 Raft apply 日志所花费的时间 -- Append log duration：Raft append 日志所花费的时间 -- Append log duration per server：每个 TiKV 实例上 Raft append 日志所花费的时间 - -![TiKV Dashboard - Raft IO metrics](/media/tikv-dashboard-raftio.png) - -## Raft process - -- Ready handled：Raft 中不同 ready 类型的个数 -- Process ready duration per server：每个 TiKV 实例处理 ready 所花费的时间，99.99% 的情况下，应该小于 2s -- Process tick duration per server：每个 TiKV 实例处理 tick 所花费的时间 -- 0.99 Duration of Raft store events：99% 的 raftstore 事件所花费的时间 - -![TiKV Dashboard - Raft process metrics](/media/tikv-dashboard-raft-process.png) - -## Raft message - -- Sent messages per server：每个 TiKV 实例发送 Raft 消息的个数 -- Flush messages per server：每个 TiKV 实例持久化 Raft 消息的个数 -- Receive messages per server：每个 TiKV 实例接受 Raft 消息的个数 -- Messages：发送不同类型的 Raft 消息的个数 -- Vote：Raft 投票消息发送的个数 -- Raft dropped messages：丢弃不同类型的 Raft 消息的个数 - -![TiKV Dashboard - Raft message metrics](/media/tikv-dashboard-raft-message.png) - -## Raft propose - -- Raft proposals per ready：在一个 mio tick 内，所有 Region proposal 的个数 -- Raft read/write proposals：不同类型的 proposal 的个数 -- Raft read proposals per server：每个 TiKV 实例发起读 proposal 的个数 -- Raft write proposals per server：每个 TiKV 实例发起写 proposal 的个数 -- Propose wait duration：每个 proposal 的等待时间 -- Propose wait duration per server：每个 TiKV 实例上每个 proposal 的等待时间 -- Raft log speed：peer propose 日志的速度 - -![TiKV Dashboard - Raft propose metrics](/media/tikv-dashboard-raft-propose.png) - -## Raft admin - -- Admin proposals：admin proposal 的个数 -- Admin apply：apply 命令的个数 -- Check split：split check 命令的个数 -- 99.99% Check split duration：99.99% 的情况下，split check 所需花费的时间 - -![TiKV Dashboard - Raft admin metrics](/media/tikv-dashboard-raft-admin.png) - -## Local reader - -- Local reader requests：所有请求的总数以及 local read 线程拒绝的请求数量 -- Local read requests duration：local read 请求的等待时间 -- Local read requests batch size：local read 请求的批量大小 - -![TiKV Dashboard - Local reader metrics](/media/tikv-dashboard-local-reader.png) - -## Storage - -- Storage command total：收到不同命令的个数 -- Storage async request error：异步请求出错的个数 -- Storage async snapshot duration：异步处理 snapshot 所花费的时间，99% 的情况下，应该小于 1s -- Storage async write duration：异步写所花费的时间，99% 的情况下，应该小于 1s - -![TiKV Dashboard - Storage metrics](/media/tikv-dashboard-storage.png) - -## Scheduler - -- Scheduler stage total：每种命令不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler priority commands：不同优先级命令的个数 -- Scheduler pending commands：每个 TiKV 实例上 pending 命令的个数 - -![TiKV Dashboard - Scheduler metrics](/media/tikv-dashboard-scheduler.png) - -## Scheduler - batch_get - -- Scheduler stage total：batch_get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 batch_get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：batch_get 命令读取 key 的个数 -- Scheduler keys written：batch_get 命令写入 key 的个数 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 batch_get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 batch_get 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - batch_get metrics](/media/tikv-dashboard-scheduler-batch-get.png) - -## Scheduler - cleanup - -- Scheduler stage total：cleanup 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 cleanup 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：cleanup 命令读取 key 的个数 -- Scheduler keys written：cleanup 命令写入 key 的个数 -- Scheduler scan details：执行 cleanup 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 cleanup 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 cleanup 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 cleanup 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - cleanup metrics](/media/tikv-dashboard-scheduler-cleanup.png) - -## Scheduler - commit - -- Scheduler stage total：commit 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 commit 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：commit 命令读取 key 的个数 -- Scheduler keys written：commit 命令写入 key 的个数 -- Scheduler scan details：执行 commit 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 commit 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 commit 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 commit 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler commit metrics](/media/tikv-dashboard-scheduler-commit.png) - -## Scheduler - gc - -- Scheduler stage total：gc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 gc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：gc 命令读取 key 的个数 -- Scheduler keys written：gc 命令写入 key 的个数 -- Scheduler scan details：执行 gc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 gc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 gc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 gc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - get - -- Scheduler stage total：get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：get 命令读取 key 的个数 -- Scheduler keys written：get 命令写入 key 的个数 -- Scheduler scan details：执行 get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 get 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - key_mvcc - -- Scheduler stage total：key_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 key_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：key_mvcc 命令读取 key 的个数 -- Scheduler keys written：key_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 key_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 key_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 key_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 key_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - prewrite - -- Scheduler stage total：prewrite 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 prewrite 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：prewrite 命令读取 key 的个数 -- Scheduler keys written：prewrite 命令写入 key 的个数 -- Scheduler scan details：执行 prewrite 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 prewrite 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 prewrite 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 prewrite 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - resolve_lock - -- Scheduler stage total：resolve_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 resolve_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：resolve_lock 命令读取 key 的个数 -- Scheduler keys written：resolve_lock 命令写入 key 的个数 -- Scheduler scan details：执行 resolve_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 resolve_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 resolve_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 resolve_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan - -- Scheduler stage total：scan 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan 命令读取 key 的个数 -- Scheduler keys written：scan 命令写入 key 的个数 -- Scheduler scan details：执行 scan 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan_lock - -- Scheduler stage total：scan_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan_lock 命令读取 key 的个数 -- Scheduler keys written：scan_lock 命令写入 key 的个数 -- Scheduler scan details：执行 scan_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - start_ts_mvcc - -- Scheduler stage total：start_ts_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 start_ts_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：start_ts_mvcc 命令读取 key 的个数 -- Scheduler keys written：start_ts_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 start_ts_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 start_ts_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 start_ts_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 start_ts_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - unsafe_destroy_range - -- Scheduler stage total：unsafe_destroy_range 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 unsafe_destroy_range 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：unsafe_destroy_range 命令读取 key 的个数 -- Scheduler keys written：unsafe_destroy_range 命令写入 key 的个数 -- Scheduler scan details：执行 unsafe_destroy_range 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 unsafe_destroy_range 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 unsafe_destroy_range 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 unsafe_destroy_range 命令时，扫描每个 default CF 中 key 的详细情况 - -## Coprocessor - -- Request duration：处理 coprocessor 读请求所花费的时间 -- Wait duration：coprocessor 请求的等待时间，99.99% 的情况下，应该小于 10s -- Handle duration：处理 coprocessor 请求所花费的时间 -- 95% Request duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 读请求所花费的时间 -- 95% Wait duration by store：95% 的情况下，每个 TiKV 实例上 coprocessor 请求的等待时间 -- 95% Handle duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 请求所花费的时间 -- Request errors：下推的请求发生错误的个数，正常情况下，短时间内不应该有大量的错误 -- DAG executors：DAG executor 的个数 -- Scan keys：每个请求 scan key 的个数 -- Scan details：scan 每个 CF 的详细情况 -- Table Scan - Details by CF：table scan 针对每个 CF 的详细情况 -- Index Scan - Details by CF：index scan 针对每个 CF 的详细情况 -- Table Scan - Perf Statistics：执行 table sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 -- Index Scan - Perf Statistics：执行 index sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 - -## GC - -- MVCC versions：每个 key 的版本个数 -- MVCC delete versions：GC 删除掉的每个 key 的版本个数 -- GC tasks：由 gc_worker 处理的 GC 任务的个数 -- GC tasks Duration：执行 GC 任务时所花费的时间 -- GC keys (write CF)：在 GC 过程中，write CF 中 受影响的 key 的个数 -- TiDB GC actions result：TiDB Region 层面的 GC 结果 -- TiDB GC worker actions：TiDB GC worker 的不同 action 的个数 -- TiDB GC seconds：TiDB 执行 GC 花费的时间 -- TiDB GC failure：TiDB GC job 失败的个数 -- GC lifetime：TiDB 设置的 GC lifetime -- GC interval：TiDB 设置的 GC 间隔 - -## Snapshot - -- Rate snapshot message：发送 Raft snapshot 消息的速率 -- 99% Handle snapshot duration：99% 的情况下，处理 snapshot 所需花费的时间 -- Snapshot state count：不同状态的 snapshot 的个数 -- 99.99% Snapshot size：99.99% 的 snapshot 的大小 -- 99.99% Snapshot KV count：99.99% 的 snapshot 包含的 key 的个数 - -## Task - -- Worker handled tasks：worker 处理的任务个数 -- Worker pending tasks：当前 worker 中，pending 和 running 的任务个数，正常情况下，应该小于 1000 -- FuturePool handled tasks：future pool 处理的任务个数 -- FuturePool pending tasks：当前 future pool 中，pending 和 running 的任务个数 - -## Thread CPU - -- Raft store CPU：raftstore 线程的 CPU 使用率，通常应低于 80% -- Async apply CPU：async apply 线程的 CPU 使用率，通常应低于 90% -- Scheduler CPU：scheduler 线程的 CPU 使用率，通常应低于 80% -- Scheduler worker CPU：scheduler worker 线程的 CPU 使用率 -- Storage ReadPool CPU：Readpool 线程的 CPU 使用率 -- Coprocessor CPU：coprocessor 线程的 CPU 使用率 -- Snapshot worker CPU：snapshot worker 线程的 CPU 使用率 -- Split check CPU：split check 线程的 CPU 使用率 -- RocksDB CPU：RocksDB 线程的 CPU 使用率 -- gRPC poll CPU：gRPC 线程的 CPU 使用率，通常应低于 80% - -## RocksDB - kv - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## RocksDB - raft - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## gRPC - -- gRPC message count：每种 gRPC 消息的个数 -- gRPC message failed：失败的 gRPC 消息的个数 -- 99% gRPC message duration：在 99% gRPC 消息的执行时间 -- gRPC GC message count：gRPC GC 消息的个数 -- 99% gRPC KV GC message duration：在 99% 情况下，gRPC GC 消息的执行时间 - -## PD - -- PD requests：TiKV 发送给 PD 的请求个数 -- PD request duration (average)：TiKV 发送给 PD 的请求所需的平均时间 -- PD heartbeats：发送给 PD 的心跳个数 -- PD validate peers：通过 PD 验证 TiKV 的 peer 有效的个数 diff --git a/dev/reference/mysql-compatibility.md b/dev/reference/mysql-compatibility.md deleted file mode 100644 index 5e2e30fd442d..000000000000 --- a/dev/reference/mysql-compatibility.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: 与 MySQL 兼容性对比 -category: reference ---- - -# 与 MySQL 兼容性对比 - -TiDB 支持 MySQL 传输协议及其绝大多数的语法。这意味着您现有的 MySQL 连接器和客户端都可以继续使用。大多数情况下您现有的应用都可以迁移至 TiDB，无需任何代码修改。 - -当前 TiDB 服务器官方支持的版本为 MySQL 5.7。大部分 MySQL 运维工具（如 PHPMyAdmin, Navicat, MySQL Workbench 等），以及备份恢复工具（如 mysqldump, Mydumper/myloader）等都可以直接使用。 - -不过一些特性由于在分布式环境下没法很好的实现，目前暂时不支持或者是表现与 MySQL 有差异。一些 MySQL 语法在 TiDB 中可以解析通过，但是不会做任何后续的处理，例如 `Create Table` 语句中 `Engine`，是解析并忽略。 - -> **注意：** -> -> 本页内容仅涉及 MySQL 与 TiDB 的总体差异。关于[安全特性](/dev/reference/security/compatibility.md)、[悲观事务模型](/dev/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)的兼容信息请查看各自具体页面。 - -## 不支持的特性 - -* 存储过程与函数 -* 触发器 -* 事件 -* 自定义函数 -* 外键约束 -* 全文/空间函数与索引 -* 非 `ascii`/`latin1`/`binary`/`utf8`/`utf8mb4` 的字符集 -* `BINARY` 之外的排序规则 -* 增加/删除主键 -* SYS schema -* MySQL 追踪优化器 -* XML 函数 -* X Protocol -* Savepoints -* 列级权限 -* `XA` 语法（TiDB 内部使用两阶段提交，但并没有通过 SQL 接口公开） -* `CREATE TABLE tblName AS SELECT stmt` 语法 -* `CREATE TEMPORARY TABLE` 语法 -* `CHECK TABLE` 语法 -* `CHECKSUM TABLE` 语法 -* `SELECT INTO FILE` 语法 - -## 与 MySQL 有差异的特性 - -### 自增 ID - -TiDB 中，自增列只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配 ID 的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。 - -在集群中有多个 tidb-server 实例时，如果表结构中有自增 ID，建议不要混用缺省值和自定义值，否则在如下情况下会遇到问题。 - -假设有这样一个带有自增 ID 的表： - -{{< copyable "sql" >}} - -```sql -create table t(id int unique key AUTO_INCREMENT, c int); -``` - -TiDB 实现自增 ID 的原理是每个 tidb-server 实例缓存一段 ID 值用于分配（目前会缓存 30000 个 ID），用完这段值再去取下一段。 - -假设集群中有两个 tidb-server 实例 A 和 B（A 缓存 [1,30000] 的自增 ID，B 缓存 [30001,60000] 的自增 ID），依次执行如下操作： - -1. 客户端向 B 插入一条将 `id` 设置为 1 的语句 `insert into t values (1, 1)`，并执行成功。 -2. 客户端向 A 发送 Insert 语句 `insert into t (c) (1)`，这条语句中没有指定 `id` 的值，所以会由 A 分配，当前 A 缓存了 [1, 30000] 这段 ID，所以会分配 1 为自增 ID 的值，并把本地计数器加 1。而此时数据库中已经存在 `id` 为 1 的数据，最终返回 `Duplicated Error` 错误。 - -另外，从 TiDB 2.1.18 和 3.0.4 版本开始，TiDB 将通过系统变量 `@@tidb_allow_remove_auto_inc` 控制是否允许通过 `alter table modify` 或 `alter table change` 来移除列的 `AUTO_INCREMENT` 属性，默认是不允许移除。 - -### Performance schema - -Performance schema 表在 TiDB 中返回结果为空。TiDB 使用 [Prometheus 和 Grafana](/dev/how-to/monitor/monitor-a-cluster.md) 来监测性能指标。 - -从 TiDB 3.0.4 版本开始，TiDB 支持 `events_statements_summary_by_digest`，参见 [Statement Summary Table](/dev/reference/performance/statement-summary.md)。 - -### 查询计划 - -TiDB 的查询计划（`EXPLAIN`/`EXPLAIN FOR`）输出格式与 MySQL 差别较大，同时 `EXPLAIN FOR` 的输出内容与权限设置与 MySQL 不一致，参见[理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md)。 - -### 内建函数 - -TiDB 支持常用的 MySQL 内建函数，但是不是所有的函数都已经支持，具体请参考[语法文档](https://pingcap.github.io/sqlgram/#functioncallkeyword)。 - -### DDL - -在 TiDB 中，运行的 DDL 操作不会影响对表的读取或写入。但是，目前 DDL 变更有如下一些限制： - -+ Add Index - - 不支持同时创建多个索引 - - 不支持 `VISIBLE/INVISIBLE` 的索引 - - 不支持通过 `ALTER TABLE` 在所生成的列上添加索引 - - 其他类型的 Index Type (HASH/BTREE/RTREE) 只有语法支持，功能不支持 -+ Add Column - - 不支持同时创建多个列 - - 不支持将新创建的列设为主键或唯一索引，也不支持将此列设成 AUTO_INCREMENT 属性 -+ Drop Column: 不支持删除主键列或索引列 -+ Change/Modify Column - - 不支持有损变更，比如从 `BIGINT` 变为 `INTEGER`，或者从 `VARCHAR(255)` 变为 `VARCHAR(10)` - - 不支持修改 `DECIMAL` 类型的精度 - - 不支持更改 `UNSIGNED` 属性 - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ Alter Database - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}`: TiDB 支持的语法，但是在 TiDB 中不会生效。所有支持的 DDL 变更都不会锁表。 -+ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}`: TiDB 完全支持 `ALGORITHM=INSTANT` 和 `ALGORITHM=INPLACE` 语法，但运行过程与 MySQL 有所不同，因为 MySQL 中的一些 `INPLACE` 操作实际上是 TiDB 中的 `INSTANT` 操作。`ALGORITHM=COPY` 语法在 TiDB 中不会生效，会返回警告信息。 -+ Table Option 不支持以下语法 - - `WITH/WITHOUT VALIDATION` - - `SECONDARY_LOAD/SECONDARY_UNLOAD` - - `CHECK/DROP CHECK` - - `STATS_AUTO_RECALC/STATS_SAMPLE_PAGES` - - `SECONDARY_ENGINE` - - `ENCRYPTION` -+ Table Partition 不支持以下语法 - - `PARTITION BY LIST` - - `PARTITION BY KEY` - - `SUBPARTITION` - - `{CHECK|EXCHANGE|TRUNCATE|OPTIMIZE|REPAIR|IMPORT|DISCARD|REBUILD|REORGANIZE} PARTITION` - -### `ANALYZE TABLE` - -- [`ANALYZE TABLE`](/dev/reference/performance/statistics.md#手动收集) 语句在 TiDB 和 MySQL 中表现不同。在 MySQL/InnoDB 中，它是一个轻量级语句，执行过程较短；而在 TiDB 中，它会完全重构表的统计数据，语句执行过程较长。 - -### 视图 - -目前 TiDB 不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 - -### 存储引擎 - -出于兼容性原因，TiDB 支持使用备用存储引擎创建表的语法。元数据命令将表描述为 InnoDB 存储引擎： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT) ENGINE=MyISAM; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -从架构上讲，TiDB 确实支持类似 MySQL 的存储引擎抽象，在启动 TiDB（通常是 `tikv`）时 [`--store`](/dev/reference/configuration/tidb-server/configuration.md#store) 选项指定的引擎中创建用户表。 - -### SQL 模式 - -TiDB 支持 MySQL 5.7 中 **绝大多数的 SQL 模式**，以下几种模式除外： - -- TiDB 不支持兼容模式（例如 `ORACLE` 和 `POSTGRESQL`）。MySQL 5.7 已弃用兼容模式，MySQL 8.0 已移除兼容模式。 -- TiDB 中的 `ONLY_FULL_GROUP_BY` 与 MySQL 5.7 相比有细微的[语义差别](/dev/reference/sql/functions-and-operators/aggregate-group-by-functions.md#与-mysql-的区别)，此问题日后将予以解决。 -- `NO_DIR_IN_CREATE` 和 `NO_ENGINE_SUBSTITUTION` 这两种 SQL 模式用于解决兼容问题，但并不适用于 TiDB。 - -### 默认设置的区别 - -+ 默认字符集与 MySQL 不同： - + TiDB 中为 `utf8mb4` - + MySQL 5.7 中为 `latin1`，MySQL 8.0 中修改为 `utf8mb4` -+ 默认排序规则不同： - + TiDB 中，`utf8mb4` 的默认排序规则为 `utf8mb4_bin` - + MySQL 5.7 中，`utf8mb4` 的默认排序规则为 `utf8mb4_general_ci`，MySQL 8.0 中修改为 `utf8mb4_0900_ai_ci` - + 请使用 [`SHOW CHARACTER SET`](/dev/reference/sql/statements/show-character-set.md) 语句查看所有字符集的默认排序规则 -+ `foreign_key_checks` 的默认值不同： - + TiDB 中该值默认为 `OFF`，并且目前 TiDB 只支持设置该值为 `OFF`。 - + MySQL 5.7 中该值默认为 `ON`。 -+ 默认 SQL mode 与 MySQL 5.7 相同，与 MySQL 8.0 不同： - + TiDB 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` - + MySQL 中默认设置： - + MySQL 5.7 的默认 SQL mode 与 TiDB 相同 - + MySQL 8.0 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION` -+ `lower_case_table_names` 的默认值不同： - + TiDB 中该值默认为 2，并且目前 TiDB 只支持设置该值为 2 - + MySQL 中默认设置： - + Linux 系统中该值为 0 - + Windows 系统中该值为 1 - + macOS 系统中该值为 2 -+ `explicit_defaults_for_timestamp` 的默认值不同： - + TiDB 中该值默认为 `ON`，并且目前 TiDB 只支持设置该值为 `ON` - + MySQL 中默认设置： - + MySQL 5.7：`OFF` - + MySQL 8.0：`ON` - -### 日期时间处理的区别 - -#### 时区 - -MySQL 默认使用本地时区，依赖于系统内置的当前的时区规则（例如什么时候开始夏令时等）进行计算；且在未[导入时区表数据](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation)的情况下不能通过时区名称来指定时区。 - -TiDB 不需要导入时区表数据也能使用所有时区名称，采用系统当前安装的所有时区规则进行计算（一般为 `tzdata` 包），且无法通过导入时区表数据的形式修改计算规则。 - -> **注意：** -> -> 能下推到 TiKV 的时间相关表达式会由 TiKV 进行计算。TiKV 总是采用 TiKV 内置时区规则计算，而不依赖于系统所安装的时区规则。若系统安装的时区规则与 TiKV 内置的时区规则版本不匹配，则在少数情况下可能发生能插入的时间数据无法再读出来的问题。例如，若系统上安装了 tzdata 2018a 时区规则，则在时区设置为 Asia/Shanghai 或时区设置为本地时区且本地时区为 Asia/Shanghai 的情况下，时间 `1988-04-17 02:00:00` 可以被正常插入 TiDB 3.0 RC.1，但该记录对于特定类型 SQL 则无法再读出来，原因是 TiKV 3.0 RC.1 依据的 tzdata 2018i 规则中该时间在 Asia/Shanghai 时区中不存在（夏令时时间后移一小时）。 -> -> TiKV 各个版本内置的时区规则如下： -> -> - 3.0.0 RC.1 及以后：[tzdata 2018i](https://github.com/eggert/tz/tree/2018i) -> - 2.1.0 RC.1 及以后：[tzdata 2018e](https://github.com/eggert/tz/tree/2018e) - -#### 零月和零日 - -目前 TiDB 尚不能完整支持月为 `0` 或日为 `0`（但年不为 `0`）的日期。在非严格模式下，此类日期时间能被正常插入。但对于特定类型的 SQL 语句，可能出现无法读出来的情况。 - -#### 字符串类型行末空格的处理 - -目前 TiDB 在进行数据插入时，对于 `VARCHAR` 类型会保留行末空格，对于 `CHAR` 类型会插入截断空格后的数据。在没有索引的情况下，TiDB 和 MySQL 行为保持一致。如果 `VARCHAR` 类型上有 `UNIQUE` 索引，MySQL 在判断是否重复的时候，和处理 `CHAR` 类型一样，先截断 `VARCHAR` 数据末行空格再作判断；TiDB 则是按照保留空格的情况处理。 - -在做比较时，MySQL 会先截去常量和 Column 的末尾空格再作比较，而 TiDB 则是保留常量和 Column 的末尾空格来做精确比较。 - -### 类型系统的区别 - -以下的列类型 MySQL 支持，但 TiDB 不支持： - -+ FLOAT4/FLOAT8 -+ FIXED (alias for DECIMAL) -+ SERIAL (alias for BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE) -+ SQL_TSI_* （包括 SQL_TSI_YEAR、SQL_TSI_MONTH、SQL_TSI_WEEK、SQL_TSI_DAY、SQL_TSI_HOUR、SQL_TSI_MINUTE 和 SQL_TSI_SECOND） diff --git a/dev/reference/performance/check-cluster-status-using-sql-statements.md b/dev/reference/performance/check-cluster-status-using-sql-statements.md deleted file mode 100644 index 9fe477c2fb53..000000000000 --- a/dev/reference/performance/check-cluster-status-using-sql-statements.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 使用 SQL 语句检查 TiDB 集群状态 -category: reference ---- - -# 使用 SQL 语句检查 TiDB 集群状态 - -为了方便排查问题，TiDB 提供了一些 SQL 语句和系统表以查询一些有用的信息。 - -`INFORMATION_SCHEMA` 中提供了如下几个系统表，用于查询集群状态，诊断常见的集群问题。 - -- [`TABLES`](/dev/reference/system-databases/information-schema.md#tables-表) -- [`TIDB_INDEXES`](/dev/reference/system-databases/information-schema.md#tidb_indexes-表) -- [`ANALYZE_STATUS`](/dev/reference/system-databases/information-schema.md#analyze_status-表) -- [`TIDB_HOT_REGIONS`](/dev/reference/system-databases/information-schema.md#tidb_hot_regions-表) -- [`TIKV_STORE_STATUS`](/dev/reference/system-databases/information-schema.md#tikv_store_status-表) -- [`TIKV_REGION_STATUS`](/dev/reference/system-databases/information-schema.md#tikv_region_status-表) -- [`TIKV_REGION_PEERS`](/dev/reference/system-databases/information-schema.md#tikv_region_peers-表) - -除此之外，执行下列语句也可获得对排查问题或查询集群状态有用的信息： - -- `ADMIN SHOW DDL` 可以获得是 `DDL owner` 角色的 TiDB 的 ID 及 `IP:PORT` 等具体信息。 -- `SHOW ANALYZE STATUS` 和 [`ANALYZE_STATUS`](/dev/reference/system-databases/information-schema.md#analyze_status-表) 表的功能相同。 -- 特殊的 `EXPLAIN` 语句： - - `EXPLAIN ANALYZE` 语句可以获得一个 SQL 语句执行中的一些具体信息。 - - `EXPLAIN FOR CONNECTION` 可以获得一个连接中最后执行的查询的执行计划。可以配合 `SHOW PROCESSLIST` 使用。 - - 关于 `EXPLAIN` 相关的更具体的信息，参考文档[理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md)。 diff --git a/dev/reference/performance/execution-plan-bind.md b/dev/reference/performance/execution-plan-bind.md deleted file mode 100644 index 1683b8e1bc71..000000000000 --- a/dev/reference/performance/execution-plan-bind.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: 执行计划绑定 -category: reference ---- - -# 执行计划绑定 - -在[优化器 Hints](/dev/reference/performance/optimizer-hints.md) 中介绍了可以通过 Hint 的方式选择指定的执行计划，但有的时候需要在不修改 SQL 语句的情况下干预执行计划的选择。执行计划绑定提供了一系列功能使得可以在不修改 SQL 语句的情况下选择指定的执行计划。 - -## 语法 - -### 创建绑定 - -{{< copyable "sql" >}} - -```sql -CREATE [GLOBAL | SESSION] BINDING FOR SelectStmt USING SelectStmt; -``` - -该语句可以在 GLOBAL 或者 SESSION 作用域内为 SQL 绑定执行计划。在不指定作用域时，隐式作用域为 SESSION。被绑定的 SQL 会被参数化后存储到系统表中。在处理 SQL 查询时，只要参数化后的 SQL 和系统表中某个被绑定的 SQL 语句一致，并且系统变量 `tidb_use_plan_baselines` 的值为 `on`（其默认值为 `on`），即可使用相应的优化器 Hint。如果存在多个可匹配的执行计划，优化器会从中选择代价最小的一个进行绑定。 - -`参数化`：把 SQL 中的常量变成变量参数，并对 SQL 中的空格和换行符等做标准化处理。例如： - -```sql -select * from t where a > 1 --- 参数化后： -select * from t where a > ？ -``` - -需要注意的是原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本必须相同，否则创建会失败，例如： - -{{< copyable "sql" >}} - -```sql -CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE a > 2; -``` - -可以创建成功，因为原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本都是 `select * from t where a > ?`，而 - -{{< copyable "sql" >}} - -```sql -CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE b > 2; -``` - -则不可以创建成功，因为原始 SQL 在经过处理后是 `select * from t where a > ?`，而绑定 SQL 在经过处理后是 `select * from t where b > ?`。 - -### 删除绑定 - -{{< copyable "sql" >}} - -```sql -DROP [GLOBAL | SESSION] BINDING FOR SelectStmt; -``` - -该语句可以在 GLOBAL 或者 SESSION 作用域内删除指定的执行计划绑定，在不指定作用域时默认作用域为 SESSION。 - -### 查看绑定 - -{{< copyable "sql" >}} - -```sql -SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere]; -``` - -该语句会输出 GLOBAL 或者 SESSION 作用域内的执行计划绑定，在不指定作用域时默认作用域为 SESSION。目前 `SHOW BINDINGS` 会输出 8 列，具体如下： - -| 列名 | 说明 | -| -------- | ------------- | -| original_sql | 参数化后的原始 SQL | -| bind_sql | 带 Hint 的绑定 SQL | -| default_db | 默认数据库名 | -| status | 状态，包括 using（正在使用）、deleted（已删除）和 invalid（无效） | -| create_time | 创建时间 | -| update_time | 更新时间 | -| charset | 字符集 | -| collation | 排序规则 | - -### 自动创建绑定 - -通过将 `tidb_capture_plan_baselines` 的值设置为 `on`（其默认值为 `off`）可以打开自动创建绑定功能。 - -> **注意：** -> -> 自动绑定功能依赖于 [Statement Summary](/dev/reference/performance/statement-summary.md)，因此在使用自动绑定之前需打开 Statement Summary 开关。 - -开启自动绑定功能后，每隔 `bind-info-lease`（默认值为 `3s`）会遍历一次 Statement Summary 中的历史 SQL 语句，并为至少出现两次的 SQL 语句自动创建绑定。 - -### 自动演进绑定 - -随着数据的变更，有可能原先绑定的执行计划已经不是最优的了，自动演进绑定功能可以自动优化已经绑定的执行计划。 - -{{< copyable "sql" >}} - -```sql -set global tidb_evolve_plan_baselines = on; -``` - -`tidb_evolve_plan_baselines` 的默认值为 `off`。 - -在打开自动演进功能后，如果优化器选出的最优执行计划不在之前绑定的执行计划之中，会将其记录为待验证的执行计划。每隔 `bind-info-lease`（默认值为 `3s`），会选出一个待验证的执行计划，将其和已经绑定的执行计划中代价最小的比较实际运行时间。如果待验证的运行时间更优的话，会将其标记为可使用的绑定。 - -为了减少自动演进对集群的影响，可以通过 `tidb_evolve_plan_task_max_time` 来限制每个执行计划运行的最长时间，其默认值为 `600s`；通过 `tidb_evolve_plan_task_start_time` 和 `tidb_evolve_plan_task_end_time` 可以限制运行演进任务的时间窗口，默认值分别为 `00:00 +0000` 和 `23:59 +0000`。 diff --git a/dev/reference/security/role-based-access-control.md b/dev/reference/security/role-based-access-control.md deleted file mode 100644 index 4a5aa9a036ab..000000000000 --- a/dev/reference/security/role-based-access-control.md +++ /dev/null @@ -1,386 +0,0 @@ ---- -title: 基于角色的访问控制 -category: reference ---- - -# 基于角色的访问控制 - -TiDB 的基于角色的访问控制 (RBAC) 系统的实现类似于 MySQL 8.0 的 RBAC 系统。TiDB 兼容大部分 MySQL RBAC 系统的语法。 - -本文档主要介绍 TiDB 基于角色的访问控制相关操作及实现。 - -## 角色访问控制相关操作 - -角色是一系列权限的集合。用户可以创建角色、删除角色、将权限赋予角色；也可以将角色授予给其他用户，被授予的用户在启用角色后，可以得到角色所包含的权限。 - -### 创建角色 - -创建角色 r_1 和 r_2： - -{{< copyable "sql" >}} - -```sql -CREATE ROLE `r_1`@`%`, `r_2`@`%`; -``` - -角色名的格式和规范可以参考 [TiDB 用户账户管理](/dev/reference/security/user-account-management.md)。 - -角色会被保存在 `mysql.user` 表中，如果表中有同名角色或用户，角色会创建失败并报错。 -创建角色的用户需要拥有 `CREATE ROLE` 或 `CREATE USER` 权限。 - -### 删除角色 - -删除角色 r_1 和 r_2： - -{{< copyable "sql" >}} - -```sql -DROP ROLE `r_1`@`%`, `r_2`@`%`; -``` - -这个操作会清除角色在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录，解除和其相关的授权关系。 -执行删除角色的用户需要拥有 `DROP ROLE` 或 `DROP USER` 权限。 - -### 授予角色权限 - -为角色授予权限和为用户授予权限操作相同，可参考 [TiDB 权限管理](/dev/reference/security/privilege-system.md)。 - -为 `analyst` 角色授予数据库 `test` 的读权限： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO 'analyst'@'%'; -``` - -为 `analyst` 角色授予所有数据库的全部权限： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'analyst'@'%'; -``` - -### 收回权限 - -`REVOKE` 语句与 `GRANT` 对应： - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `test`.* FROM 'analyst'@'%'; -``` - -具体可参考 [TiDB 权限管理](/dev/reference/security/privilege-system.md)。 - -### 将角色授予给用户 - -将角色 role1 和 role2 同时授予给用户 `user1@localhost` 和 `user2@localhost`。 - -{{< copyable "sql" >}} - -```sql -GRANT 'role1', 'role2' TO 'user1'@'localhost', 'user2'@'localhost'; -``` - -用户执行将角色授予给其他用户或者收回角色的命令，需要用户拥有 `SUPER` 权限。 -将角色授予给用户时并不会启用该角色，启用角色需要额外的操作。 - -以下操作可能会形成一个“关系环”： - -```sql -CREATE USER 'u1', 'u2'; -CREATE ROLE 'r1', 'r2'; - -GRANT 'u1' TO 'u1'; -GRANT 'r1' TO 'r1'; - -GRANT 'r2' TO 'u2'; -GRANT 'u2' TO 'r2'; -``` - -TiDB 允许这种多层授权关系存在，可以使用多层授权关系实现权限继承。 - -### 收回角色 - -解除角色 role1、role2 与用户 `user1@localhost`、`user2@localhost` 的授权关系。 - -{{< copyable "sql" >}} - -```sql -REVOKE 'role1', 'role2' FROM 'user1'@'localhost', 'user2'@'localhost'; -``` - -解除角色授权具有原子性，如果在撤销授权操作中失败会回滚。 - -### 设置默认启用角色 - -角色在授予给用户之后，并不会生效；只有在用户启用了某些角色之后，才可以使用角色拥有的权限。 - -可以对用户设置默认启用的角色；用户在登陆时，默认启用的角色会被自动启用。 - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE - {NONE | ALL | role [, role ] ...} - TO user [, user ] -``` - -比如将 administrator 和 developer 设置为 `test@localhost` 的默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE administrator, developer TO 'test'@'localhost'; -``` - -将 `test@localhost` 的所有角色，设为其默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE ALL TO 'test'@'localhost'; -``` - -关闭 `test@localhost` 的所有默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE NONE TO 'test'@'localhost'; -``` - -需要注意的是，设置为默认启用角色的角色必须已经授予给那个用户。 - -### 在当前 session 启用角色 - -除了使用 `SET DEFAULT ROLE` 启用角色外，TiDB 还提供让用户在当前 session 启用某些角色的功能。 - -```sql -SET ROLE { - DEFAULT - | NONE - | ALL - | ALL EXCEPT role [, role ] ... - | role [, role ] ... -} -``` - -例如，为当前用户启用角色 role1 和 role2 ，仅在当前 session 有效： - -{{< copyable "sql" >}} - -```sql -SET ROLE 'role1', 'role2'; -``` - -启用当前用户的默认角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE DEFAULT -``` - -启用授予给当前用户的所有角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE ALL -``` - -不启用任何角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE NONE -``` - -启用除 role1 和 role2 外的角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE ALL EXCEPT 'role1', 'role2' -``` - -> **注意：** -> -> 使用 `SET ROLE` 启用的角色只有在当前 session 才会有效。 - -### 查看当前启用角色 - -当前用户可以通过 `CURRENT_ROLE()` 函数查看当前用户启用了哪些角色。 - -例如，先对 `u1'@'localhost` 授予角色： - -{{< copyable "sql" >}} - -```sql -GRANT 'r1', 'r2' TO 'u1'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE ALL TO 'u1'@'localhost'; -``` - -在 u1 登陆后： - -{{< copyable "sql" >}} - -```sql -SELECT CURRENT_ROLE(); -``` - -``` -+-------------------+ -| CURRENT_ROLE() | -+-------------------+ -| `r1`@`%`,`r2`@`%` | -+-------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SET ROLE 'r1'; SELECT CURRENT_ROLE(); -``` - -``` -+----------------+ -| CURRENT_ROLE() | -+----------------+ -| `r1`@`%` | -+----------------+ -``` - -### 查看角色拥有的权限 - -可以通过 `SHOW GRANTS` 语句查看用户被授予了哪些角色。 -当用户查看其他用户权限相关信息时，需要对 `mysql` 数据库拥有 `SELECT` 权限。 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost'; -``` - -``` -+---------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------+ -``` - -可以通过使用 `SHOW GRANTS` 的 `USING` 选项来查看角色对应的权限。 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r1'; -``` - -``` -+---------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Select ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r2'; -``` - -``` -+-------------------------------------------------------------+ -| Grants for u1@localhost | -+-------------------------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+-------------------------------------------------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r1', 'r2'; -``` - -``` -+---------------------------------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Select, Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------------------------------+ -``` - -可以使用 `SHOW GRANTS` 或 `SHOW GRANTS FOR CURRENT_USER()` 查看当前用户的权限。 -这两个语句有细微的差异，`SHOW GRANTS` 会显示当前用户的启用角色的权限，而 `SHOW GRANTS FOR CURRENT_USER()` 则不会显示启用角色的权限。 - -### 授权表 - -在原有的四张[系统权限表](/dev/reference/security/privilege-system.md#授权表)的基础上，角色访问控制引入了两张新的系统表： - -- `mysql.role_edges`：记录角色与用户的授权关系 -- `mysql.default_roles`：记录每个用户默认启用的角色 - -以下是 `mysql.role_edges` 所包含的数据。 - -{{< copyable "sql" >}} - -```sql -select * from mysql.role_edges; -``` - -``` -+-----------+-----------+---------+---------+-------------------+ -| FROM_HOST | FROM_USER | TO_HOST | TO_USER | WITH_ADMIN_OPTION | -+-----------+-----------+---------+---------+-------------------+ -| % | r_1 | % | u_1 | N | -+-----------+-----------+---------+---------+-------------------+ -1 row in set (0.00 sec) -``` - -其中 `FROM_HOST` 和 `FROM_USER` 分别表示角色的主机名和用户名，`TO_HOST` 和 `TO_USER` 分别表示被授予角色的用户的主机名和用户名。 - -`mysql.default_roles` 中包含了每个用户默认启用了哪些角色。 - -{{< copyable "sql" >}} - -```sql -select * from mysql.default_roles; -``` - -``` -+------+------+-------------------+-------------------+ -| HOST | USER | DEFAULT_ROLE_HOST | DEFAULT_ROLE_USER | -+------+------+-------------------+-------------------+ -| % | u_1 | % | r_1 | -| % | u_1 | % | r_2 | -+------+------+-------------------+-------------------+ -2 rows in set (0.00 sec) -``` - -`HOST` 和 `USER` 分别表示用户的主机名和用户名，`DEFAULT_ROLE_HOST` 和 `DEFAULT_ROLE_USER` 分别表示默认启用的角色的主机名和用户名。 - -### 其他 - -由于基于角色的访问控制模块和用户管理以及权限管理结合十分紧密，因此需要参考一些操作的细节： - -- [TiDB 权限管理](/dev/reference/security/privilege-system.md) -- [TiDB 用户账户管理](/dev/reference/security/user-account-management.md) diff --git a/dev/reference/security/user-account-management.md b/dev/reference/security/user-account-management.md deleted file mode 100644 index 145d7f95b0e0..000000000000 --- a/dev/reference/security/user-account-management.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: TiDB 用户账户管理 -category: reference ---- - -# TiDB 用户账户管理 - -本文档主要介绍如何管理 TiDB 用户账户。 - -## 用户名和密码 - -TiDB 将用户账户存储在 `mysql.user` 系统表里面。每个账户由用户名和 host 作为标识。每个账户可以设置一个密码。 - -通过 MySQL 客户端连接到 TiDB 服务器，通过指定的账户和密码登录： - -{{< copyable "shell-regular" >}} - -``` -mysql --port 4000 --user xxx --password -``` - -使用缩写的命令行参数则是： - -{{< copyable "shell-regular" >}} - -``` -mysql -P 4000 -u xxx -p -``` - -## 添加用户 - -添加用户有两种方式： - -* 通过标准的用户管理的 SQL 语句创建用户以及授予权限，比如 `CREATE USER` 和 `GRANT`。 -* 直接通过 `INSERT`、`UPDATE` 和 `DELETE` 操作授权表。 - -推荐使用第一种方式。第二种方式修改容易导致一些不完整的修改，因此不推荐。还有另一种可选方式是使用第三方工具的图形化界面工具。 - -{{< copyable "sql" >}} - -```sql -CREATE USER [IF NOT EXISTS] - user [auth_spec] [, user [auth_spec]] ... -``` - -{{< copyable "sql" >}} - -```sql -auth_spec: { - IDENTIFIED BY 'auth_string' - | IDENTIFIED BY PASSWORD 'hash_string' -} -``` - -* `IDENTIFIED BY 'auth_string'`：设置登录密码时，`auth_string` 会被 TiDB 经过加密存储在 `mysql.user` 表中。 -* `IDENTIFIED BY PASSWORD 'hash_string'`：设置登录密码，`hash_string` 是一个类似于 `*EBE2869D7542FCE37D1C9BBC724B97BDE54428F1` 的 41 位字符串，会被 TiDB 直接存储在 `mysql.user` 表中，该字符串可以通过 `SELECT password('auth_string')` 加密得到。 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'127.0.0.1' IDENTIFIED BY 'xxx'; -``` - -TiDB 的用户账户名由一个用户名和一个主机名组成。账户名的语法为 `'user_name'@'host_name'`。 - -- `user_name` 大小写敏感。 -- `host_name` 可以是一个主机名或 IP 地址。主机名或 IP 地址中允许使用通配符 `%` 和 `_`。例如，名为 `'%'` 的主机名可以匹配所有主机，`'192.168.1.%'` 可以匹配子网中的所有主机。 - -host 支持模糊匹配，比如： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'192.168.10.%'; -``` - -允许 `test` 用户从 `192.168.10` 子网的任何一个主机登录。 - -如果没有指定 host，则默认是所有 IP 均可登录。如果没有指定密码，默认为空： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'; -``` - -等价于： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'%' IDENTIFIED BY ''; -``` - -下面的例子用 `CREATE USER` 和 `GRANT` 语句创建了四个账户： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'localhost' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'localhost' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'%' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'%' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'dummy'@'localhost'; -``` - -使用 `SHOW GRANTS` 可以看到为一个用户授予的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'admin'@'localhost'; -``` - -``` -+-----------------------------------------------------+ -| Grants for admin@localhost | -+-----------------------------------------------------+ -| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' | -+-----------------------------------------------------+ -``` - -## 删除用户 - -使用 `DROP USER` 语句可以删除用户，例如： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'@'localhost'; -``` - -这个操作会清除用户在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录。 - -## 保留用户账户 - -TiDB 在数据库初始化时会生成一个 `'root'@'%'` 的默认账户。 - -## 设置资源限制 - -暂不支持。 - -## 设置密码 - -TiDB 将密码存在 `mysql.user` 系统数据库里面。只有拥有 `CREATE USER` 权限，或者拥有 `mysql` 数据库权限（`INSERT` 权限用于创建，`UPDATE` 权限用于更新）的用户才能够设置或修改密码。 - -- 在 `CREATE USER` 创建用户时可以通过 `IDENTIFIED BY` 指定密码： - - {{< copyable "sql" >}} - - ```sql - CREATE USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -- 为一个已存在的账户修改密码，可以通过 `SET PASSWORD FOR` 或者 `ALTER USER` 语句完成： - - {{< copyable "sql" >}} - - ```sql - SET PASSWORD FOR 'root'@'%' = 'xxx'; - ``` - - 或者： - - {{< copyable "sql" >}} - - ```sql - ALTER USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -## 忘记 `root` 密码 - -1. 修改配置文件，在 `security` 部分添加 `skip-grant-table`： - - {{< copyable "" >}} - - ``` - [security] - skip-grant-table = true - ``` - -2. 然后使用 `root` 登录后修改密码： - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -## `FLUSH PRIVILEGES` - -如果授权表已被直接修改，运行如下命令可使改动立即生效： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -详情参见[权限管理](/dev/reference/security/privilege-system.md)。 diff --git a/dev/reference/sql/constraints.md b/dev/reference/sql/constraints.md deleted file mode 100644 index 69c7e603fc69..000000000000 --- a/dev/reference/sql/constraints.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: 约束 -category: reference ---- - -# 约束 - -TiDB 支持的基本约束与 MySQL 的基本相同，但有以下区别： - -- 默认对唯一约束进行[惰性检查](/dev/reference/transactions/overview.md#事务的惰性检查)。通过在事务提交时再进行批量检查，TiDB 能够减少网络开销、提升性能。您可通过设置 `tidb_constraint_check_in_place` 为 `TRUE` 改变此行为。 - -- TiDB 支持创建外键约束，但不会在 DML 语句中对外键进行约束（即外键约束不生效）。 - -## 外键约束 - -目前，TiDB 支持创建外键。例如： - -```sql -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - doc JSON -); -CREATE TABLE orders ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - user_id INT NOT NULL, - doc JSON, - FOREIGN KEY fk_user_id (user_id) REFERENCES users(id) -); -``` - -{{< copyable "sql" >}} - -```sql -SELECT table_name, column_name, constraint_name, referenced_table_name, referenced_column_name -FROM information_schema.key_column_usage WHERE table_name IN ('users', 'orders'); -``` - -``` -+------------+-------------+-----------------+-----------------------+------------------------+ -| table_name | column_name | constraint_name | referenced_table_name | referenced_column_name | -+------------+-------------+-----------------+-----------------------+------------------------+ -| users | id | PRIMARY | NULL | NULL | -| orders | id | PRIMARY | NULL | NULL | -| orders | user_id | fk_user_id | users | id | -+------------+-------------+-----------------+-----------------------+------------------------+ -3 rows in set (0.00 sec) -``` - -TiDB 也支持使用 `ALTER TABLE` 命令来删除外键（`DROP FOREIGN KEY`）和添加外键（`ADD FOREIGN KEY`）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE orders DROP FOREIGN KEY fk_user_id; -ALTER TABLE orders ADD FOREIGN KEY fk_user_id (user_id) REFERENCES users(id); -``` - -### 注意 - -* TiDB 支持外键是为了在将其他数据库迁移到 TiDB 时，不会因为此语法报错。但是，TiDB 不会在 DML 语句中对外键进行约束。例如，即使 `users` 表中不存在 `id=123` 的记录，下列事务也能提交成功： - - ``` - START TRANSACTION; - INSERT INTO orders (user_id, doc) VALUES (123, NULL); - COMMIT; - ``` - -* TiDB 在执行 `SHOW CREATE TABLE` 语句的结果中不显示外键信息。 - -## 非空约束 - -TiDB 支持的非空约束规则与 MySQL 支持的一致。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - age INT NOT NULL, - last_login TIMESTAMP -); -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,123,NOW()); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,NULL,NOW()); -``` - -``` -ERROR 1048 (23000): Column 'age' cannot be null -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,123,NULL); -``` - -``` -Query OK, 1 row affected (0.03 sec) -``` - -* 第一条 `INSERT` 语句成功，因为对于定义为 `AUTO_INCREMENT` 的列，允许 `NULL` 作为其特殊值。TiDB 将为其分配下一个自动值。 - -* 第二条 `INSERT` 语句失败，因为 `age` 列被定义为 `NOT NULL`。 - -* 第三条 `INSERT` 语句成功，因为 `last_login` 列没有被明确地指定为 `NOT NULL`。默认允许 `NULL` 值。 - -## 主键约束 - -TiDB 支持的主键约束规则与 MySQL 支持的相似。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 (a INT NULL PRIMARY KEY); -``` - -``` -ERROR 1171 (42000): All parts of a PRIMARY KEY must be NOT NULL; if you need NULL in a key, use UNIQUE instead -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t3 (a INT NOT NULL PRIMARY KEY, b INT NOT NULL PRIMARY KEY); -``` - -``` -ERROR 1068 (42000): Multiple primary key defined -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t4 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b)); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -* 表 `t2` 创建失败，因为定义为主键的列 `a` 不能允许 `NULL` 值。 -* 表 `t3` 创建失败，因为一张表只能有一个主键。 -* 表 `t4` 创建成功，因为虽然只能有一个主键，但 TiDB 支持定义一个多列组合作为复合主键。 - -除上述规则外，TiDB 还强加了另一个限制，即一旦一张表创建成功，其主键就不能再改变。 - -## 唯一约束 - -在 TiDB 中，默认会对唯一约束进行惰性检查。通过直到事务提交时才进行批量检查，TiDB 能够减少网络通信开销。例如： - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -``` - -``` -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('steve'),('elizabeth'); -``` - -``` -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -``` - -* 第一条 `INSERT` 语句不会导致重复键错误，这同 MySQL 的规则一致。该检查将推迟到事务提交时才会进行。 - -如果将 `tidb_constraint_check_in_place` 更改为 `TRUE`，则会在执行语句时就对唯一约束进行检查。例如： - -```sql -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -``` - -{{< copyable "sql" >}} - -```sql -SET tidb_constraint_check_in_place = TRUE; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -``` - -``` -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -.. -``` - -* 第一条 `INSERT` 语句导致了重复键错误。这会造成额外的网络通信开销，并可能降低插入操作的吞吐量。 diff --git a/dev/reference/sql/data-types/overview.md b/dev/reference/sql/data-types/overview.md deleted file mode 100644 index 23a9df9e8272..000000000000 --- a/dev/reference/sql/data-types/overview.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 数据类型概述 -category: reference ---- - -# 数据类型概述 - -TiDB 支持除空间类型 (`SPATIAL`) 之外的所有 MySQL 数据类型，包括[数值型类型](/dev/reference/sql/data-types/numeric.md)、[字符串类型](/dev/reference/sql/data-types/string.md)、[时间和日期类型](/dev/reference/sql/data-types/date-and-time.md)、[JSON 类型](/dev/reference/sql/data-types/json.md)。 - -数据类型定义一般为 `T(M[, D])`，其中： - -* `T` 表示具体的类型。 -* `M` 在整数类型中表示最大显示长度；在浮点数或者定点数中表示精度；在字符类型中表示最大长度。`M` 的最大值取决于具体的类型。 -* `D` 表示浮点数、定点数的小数位长度。 -* `fsp` 在时间和日期类型里的 `TIME`、`DATETIME` 以及 `TIMESTAMP` 中表示秒的精度，其取值范围是 0 到 6。值为 0 表示没有小数部分。如果省略，则默认精度为 0。 diff --git a/dev/reference/sql/functions-and-operators/aggregate-group-by-functions.md b/dev/reference/sql/functions-and-operators/aggregate-group-by-functions.md deleted file mode 100644 index 4a6fb637dfc9..000000000000 --- a/dev/reference/sql/functions-and-operators/aggregate-group-by-functions.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: GROUP BY 聚合函数 -category: reference ---- - -# GROUP BY 聚合函数 - -本文将详细介绍 TiDB 支持的聚合函数。 - -## TiDB 支持的聚合函数 - -TiDB 支持的 MySQL GROUP BY 聚合函数如下所示： - -| 函数名 | 功能描述 | -|:---------|:--------------------| -| [`COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count) | 返回检索到的行的数目| -| [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count-distinct) | 返回不同值的数目 | -| [`SUM()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_sum) | 返回和 | -| [`AVG()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_avg) | 返回平均值 | -| [`MAX()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_max) | 返回最大值 | -| [`MIN()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_min) | 返回最小值 | -| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_group-concat) | 返回连接的字符串 | - -> **注意：** -> -> - 除非另有说明，否则聚合函数默认忽略 `NULL` 值。 -> - 如果在不包含 `GROUP BY` 子句的语句中使用聚合函数，则相当于对所有行进行分组。 - -## GROUP BY 修饰符 - -TiDB 目前不支持 `GROUP BY` 修饰符，例如 `WITH ROLLUP`，将来会提供支持。详情参阅 [#4250](https://github.com/pingcap/tidb/issues/4250)。 - -## 对 SQL 模式的支持 - -TiDB 支持 SQL 模式 `ONLY_FULL_GROUP_BY`，当启用该模式时，TiDB 拒绝不明确的非聚合列的查询。例如，以下查询在启用 `ONLY_FULL_GROUP_BY` 时是不合规的，因为 `SELECT` 列表中的非聚合列 "b" 在 `GROUP BY` 语句中不显示： - -{{< copyable "sql" >}} - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 3), (2, 2, 3), (3, 2, 3); -``` - -{{< copyable "sql" >}} - -```sql -select a, b, sum(c) from t group by a; -``` - -``` -+------+------+--------+ -| a | b | sum(c) | -+------+------+--------+ -| 1 | 2 | 3 | -| 2 | 2 | 3 | -| 3 | 2 | 3 | -+------+------+--------+ -3 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -set sql_mode = 'ONLY_FULL_GROUP_BY'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select a, b, sum(c) from t group by a; -``` - -``` -ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP BY clause and contains nonaggregated column 'b' which is not functionally dependent on columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by -``` - -目前，TiDB 默认开启 SQL 模式 [`ONLY_FULL_GROUP_BY`](/dev/reference/mysql-compatibility.md#默认设置的区别)。 - -### 与 MySQL 的区别 - -TiDB 目前实现的 `ONLY_FULL_GROUP_BY` 没有 MySQL 5.7 严格。例如，假设我们执行以下查询，希望结果按 "c" 排序： - -{{< copyable "sql" >}} - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 1), (1, 2, 2), (1, 3, 1), (1, 3, 2); -select distinct a, b from t order by c; -``` - -要对结果进行排序，必须先清除重复。但选择保留哪一行会影响 `c` 的保留值，也会影响排序，并使其具有任意性。 - -在 MySQL 中，`ORDER BY` 表达式需至少满足以下条件之一，否则 `DISTINCT` 和 `ORDER BY` 查询将因不合规而被拒绝： - -- 表达式等同于 `SELECT` 列表中的一个。 -- 表达式引用并属于查询选择表的所有列都是 `SELECT` 列表的元素。 - -但是在 TiDB 中，上述查询是合规的，详情参阅 [#4254](https://github.com/pingcap/tidb/issues/4254)。 - -TiDB 中另一个标准 SQL 的扩展允许 `HAVING` 子句中的引用使用 `SELECT` 列表中的别名表达式。例如：以下查询返回在 `orders` 中只出现一次的 `name` 值： - -{{< copyable "sql" >}} - -```sql -select name, count(name) from orders -group by name -having count(name) = 1; -``` - -这个 TiDB 扩展允许在聚合列的 `HAVING` 子句中使用别名： - -{{< copyable "sql" >}} - -```sql -select name, count(name) as c from orders -group by name -having c = 1; -``` - -标准 SQL 只支持 `GROUP BY` 子句中的列表达式，以下语句不合规，因为 `FLOOR(value/100)` 是一个非列表达式： - -{{< copyable "sql" >}} - -```sql -select id, floor(value/100) -from tbl_name -group by id, floor(value/100); -``` - -TiDB 对标准 SQL 的扩展支持 `GROUP BY` 子句中非列表达式，认为上述语句合规。 - -标准 SQL 也不支持 `GROUP BY` 子句中使用别名。TiDB 对标准 SQL 的扩展支持使用别名，查询的另一种写法如下： - -{{< copyable "sql" >}} - -```sql -select id, floor(value/100) as val -from tbl_name -group by id, val; -``` - -## TiDB 不支持的聚合函数 - -TiDB 目前不支持的聚合函数如下所示，相关进展参阅 [TiDB #7623](https://github.com/pingcap/tidb/issues/7623)。 - -- `STD`, `STDDEV`, `STDDEV_POP` -- `STDDEV_SAMP` -- `VARIANCE`, `VAR_POP` -- `VAR_SAMP` -- `JSON_ARRAYAGG` -- `JSON_OBJECTAGG` diff --git a/dev/reference/sql/functions-and-operators/expressions-pushed-down.md b/dev/reference/sql/functions-and-operators/expressions-pushed-down.md deleted file mode 100644 index f764062359af..000000000000 --- a/dev/reference/sql/functions-and-operators/expressions-pushed-down.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: 下推到 TiKV 的表达式列表 -summary: TiDB 中下推到 TiKV 的表达式列表及相关设置。 -category: reference ---- - -# 下推到 TiKV 的表达式列表 - -当 TiDB 从 TiKV 中读取数据的时候，TiDB 会尽量下推一些表达式运算到 TiKV 中，从而减少数据传输量以及 TiDB 单一节点的计算压力。本文将介绍 TiDB 已支持下推的表达式，以及如何禁止下推特定表达式。 - -## 已支持下推的表达式列表 - -| 表达式分类 | 具体操作 | -| :-------------- | :------------------------------------- | -| [逻辑运算](/dev/reference/sql/functions-and-operators/operators.md#逻辑操作符) | AND (&&), OR (||), NOT (!) | -| [比较运算](/dev/reference/sql/functions-and-operators/operators.md#比较方法和操作符) | <, <=, =, != (<>), >, >=, [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to), [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in), IS NULL, LIKE, IS TRUE, IS FALSE, [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | -| [数值运算](/dev/reference/sql/functions-and-operators/numeric-functions-and-operators.md) | +, -, *, /, [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs), [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil), [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling), [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | -| [控制流运算](/dev/reference/sql/functions-and-operators/control-flow-functions.md) | [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case), [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if), [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | -| [JSON运算](/dev/reference/sql/functions-and-operators/json-functions.md) | [JSON_TYPE(json_val)][json_type],
[JSON_EXTRACT(json_doc, path[, path] ...)][json_extract],
[JSON_UNQUOTE(json_val)][json_unquote],
[JSON_OBJECT(key, val[, key, val] ...)][json_object],
[JSON_ARRAY([val[, val] ...])][json_array],
[JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge],
[JSON_SET(json_doc, path, val[, path, val] ...)][json_set],
[JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert],
[JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace],
[JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | -| [日期运算](/dev/reference/sql/functions-and-operators/date-and-time-functions.md) | [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | - -## 禁止特定表达式下推 - -当函数的计算过程由于下推而出现异常时，可通过黑名单功能禁止其下推来快速恢复业务。具体而言，你可以将上述支持的函数或运算符名加入黑名单 `mysql.expr_pushdown_blacklist` 中，以禁止特定表达式下推。 - -### 加入黑名单 - -执行以下步骤，可将一个或多个函数或运算符加入黑名单： - -1. 向 `mysql.expr_pushdown_blacklist` 插入对应的函数名或运算符名。 -2. 执行 `admin reload expr_pushdown_blacklist;`。 - -### 移出黑名单 - -执行以下步骤，可将一个或多个函数及运算符移出黑名单： - -1. 从 `mysql.expr_pushdown_blacklist` 表中删除对应的函数名或运算符名。 -2. 执行 `admin reload expr_pushdown_blacklist;`。 - -### 黑名单用法示例 - -以下示例首先将运算符 `<` 及 `>` 加入黑名单，然后将运算符 `>` 从黑名单中移出。 - -黑名单是否生效可以从 `explain` 结果中进行观察（参见[如何理解 `explain` 结果](/dev/reference/performance/understanding-the-query-execution-plan.md)）。 - -```sql -tidb> create table t(a int); -Query OK, 0 rows affected (0.01 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+---------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+------------------------------------------------------------+ -| TableReader_7 | 0.00 | root | data:Selection_6 | -| └─Selection_6 | 0.00 | cop | gt(test.t.a, 2), lt(test.t.a, 2) | -| └─TableScan_5 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+------------------------------------------------------------+ -3 rows in set (0.00 sec) - -tidb> insert into mysql.expr_pushdown_blacklist values('<'), ('>'); -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 - -tidb> admin reload expr_pushdown_blacklist; -Query OK, 0 rows affected (0.00 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+---------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+------------------------------------------------------------+ -| Selection_5 | 8000.00 | root | gt(test.t.a, 2), lt(test.t.a, 2) | -| └─TableReader_7 | 10000.00 | root | data:TableScan_6 | -| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+------------------------------------------------------------+ -3 rows in set (0.00 sec) - -tidb> delete from mysql.expr_pushdown_blacklist where name = '>'; -Query OK, 1 row affected (0.00 sec) - -tidb> admin reload expr_pushdown_blacklist; -Query OK, 0 rows affected (0.00 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+-----------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+-----------------------+----------+------+------------------------------------------------------------+ -| Selection_5 | 2666.67 | root | lt(test.t.a, 2) | -| └─TableReader_8 | 3333.33 | root | data:Selection_7 | -| └─Selection_7 | 3333.33 | cop | gt(test.t.a, 2) | -| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+-----------------------+----------+------+------------------------------------------------------------+ -4 rows in set (0.00 sec) -``` - -> **注意：** -> -> - `admin reload expr_pushdown_blacklist` 只对执行该 SQL 语句的 TiDB server 生效。若需要集群中所有 TiDB server 生效，需要在每台 TiDB server 上执行该 SQL 语句。 -> - 表达式黑名单功能在 v3.0.0 及以上版本中支持。 -> - 在 v3.0.3 及以下版本中，不支持将某些运算符的原始名称文本（如 ">"、"+" 和 "is null"）加入黑名单中，部分运算符在黑名单中需使用别名。已支持下推的表达式中，别名与原始名不同的运算符见下表（区分大小写）。 - -| 运算符原始名称 | 运算符别名 | -| :-------- | :---------- | -| < | lt | -| > | gt | -| <= | le | -| >= | ge | -| = | eq | -| != | ne | -| <> | ne | -| <=> | nulleq | -| | | bitor | -| && | bitand| -| || | or | -| ! | not | -| in | in | -| + | plus| -| - | minus | -| * | mul | -| / | div | -| DIV | intdiv| -| IS NULL | isnull | -| IS TRUE | istrue | -| IS FALSE | isfalse | - -[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract -[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path -[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path -[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote -[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type -[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set -[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert -[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace -[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove -[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge -[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve -[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object -[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array -[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys -[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length -[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid -[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote -[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains -[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path -[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg -[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/dev/reference/sql/functions-and-operators/reference.md b/dev/reference/sql/functions-and-operators/reference.md deleted file mode 100644 index fbd7d93c241d..000000000000 --- a/dev/reference/sql/functions-and-operators/reference.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: 函数和操作符概述 -category: reference ---- - -# 函数和操作符概述 - -TiDB 中函数和操作符使用方法与 MySQL 基本一致，详情参见: [Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/functions.html)。 - -在 SQL 语句中，表达式可用于诸如 `SELECT` 语句的 `ORDER BY` 或 `HAVING` 子句，`SELECT`/`DELETE`/`UPDATE` 语句的 `WHERE` 子句，或 `SET` 语句之类的地方。 - -可使用字面值，列名，NULL，内置函数，操作符等来书写表达式。其中有些表达式下推到 TiKV 上执行，详见[下推到 TiKV 的表达式列表](/dev/reference/sql/functions-and-operators/expressions-pushed-down.md)。 diff --git a/dev/reference/sql/generated-columns.md b/dev/reference/sql/generated-columns.md deleted file mode 100644 index 10796fc678a9..000000000000 --- a/dev/reference/sql/generated-columns.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: 生成列 -category: reference ---- - -# 生成列 - -为了在功能上兼容 MySQL 5.7，TiDB 支持生成列 (generated column)。生成列的主要的作用之一：从 JSON 数据类型中解出数据，并为该数据建立索引。 - -## 使用 generated column 对 JSON 建索引 - -MySQL 5.7 及 TiDB 都不能直接为 JSON 类型的列添加索引，即**不支持**如下表结构： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - KEY (address_info) -); -``` - -为 JSON 列添加索引之前，首先必须抽取该列为 generated column。 - -以 `city` generated stored column 为例，你可以添加索引： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED, - KEY (city) -); -``` - -该表中，`city` 列是一个 **generated stored column**。顾名思义，此列由该表的其他列生成，对此列进行插入或更新操作时，并不能对之赋值。此列按其定义的表达式生成，并存储在数据库中，这样在读取此列时，就可以直接读取，不用再读取其依赖的 `address_info` 列后再计算得到。`city` 列的索引**存储在数据库中**，并使用和 `varchar(64)` 类的其他索引相同的结构。 - -可使用 generated stored column 的索引，以提高如下语句的执行速度： - -{{< copyable "sql" >}} - -```sql -SELECT name, id FROM person WHERE city = 'Beijing'; -``` - -如果 `$.city` 路径中无数据，则 `JSON_EXTRACT` 返回 `NULL`。如果想增加约束，`city` 列必须是 `NOT NULL`，则可按照以下方式定义 virtual column： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED NOT NULL, - KEY (city) -); -``` - -`INSERT` 和 `UPDATE` 语句都会检查 virtual column 的定义。未通过有效性检测的行会返回错误： - -{{< copyable "sql" >}} - -```sql -INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada')); -``` - -``` -ERROR 1048 (23000): Column 'city' cannot be null -``` - -## 使用 generated virtual column - -TiDB 也支持 generated virtual column，和 generated store column 不同的是，此列按需生成，并不存储在数据库中，也不占用内存空间，因而是**虚拟的**。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) VIRTUAL -); -``` - -## 局限性 - -目前 JSON and generated column 有以下局限性： - -- 不能通过 `ALTER TABLE` 增加 `STORED` 存储方式的 generated column； -- 不能通过 `ALTER TABLE` 将 generated stored column 转换为普通列，也不能将普通列转换成 generated stored column； -- 不能通过 `ALTER TABLE` 修改 generated stored column 的**生成列表达式**； -- 并未支持所有的 [JSON 函数](/dev/reference/sql/functions-and-operators/json-functions.md)。 \ No newline at end of file diff --git a/dev/reference/sql/language-structure/comment-syntax.md b/dev/reference/sql/language-structure/comment-syntax.md deleted file mode 100644 index 8c67a32a3196..000000000000 --- a/dev/reference/sql/language-structure/comment-syntax.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: 注释语法 -category: reference ---- - -# 注释语法 - -TiDB 支持三种注释风格： - -* 用 `#` 注释一行 -* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。 -* 用 `/* */` 注释一块，可以注释多行。 - -例： - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; # 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; -- 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1 /* 这是行内注释文字 */ + 1; -``` - -``` -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+ - -> /* - /*> 这是一条 - /*> 多行注释 - /*> */ - -> 1; -``` - -``` -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1--1; -``` - -``` -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) -``` - -TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： - -``` -/*! Specific code */ -``` - -在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 - -例如：`SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...` - -在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` - -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。 - -还有一种注释会被当做是优化器 Hint 特殊对待： - -{{< copyable "sql" >}} - -```sql -SELECT /*+ hint */ FROM ...; -``` - -由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments - -TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/dev/reference/performance/optimizer-hints.md)。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 diff --git a/dev/reference/sql/language-structure/keywords-and-reserved-words.md b/dev/reference/sql/language-structure/keywords-and-reserved-words.md deleted file mode 100644 index 30aa376fa563..000000000000 --- a/dev/reference/sql/language-structure/keywords-and-reserved-words.md +++ /dev/null @@ -1,483 +0,0 @@ ---- -title: 关键字和保留字 -category: reference ---- - -# 关键字和保留字 - -关键字在 SQL 中有特殊的意义， 例如 `SELECT`，`UPDATE`，`DELETE`，在作为表名跟函数名的时候，需要特殊对待，例如作为表名，保留字需要被反引号包住： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE select (a INT); -``` - -``` -ERROR 1105 (HY000): line 0 column 19 near " (a INT)" (total length 27) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `select` (a INT); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -`BEGIN` 和 `END` 是关键字， 但不是保留字，所以不需要反引号： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `select` (BEGIN int, END int); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -有一种特殊情况， 如果使用了限定符 `.`，那么也不需要用反引号： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.select (BEGIN int, END int); -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -下表列出了 TiDB 中的关键字和保留字。保留字用 `(R)` 来标识。[窗口函数](/dev/reference/sql/functions-and-operators/window-functions.md)的保留字用 `(R-Window)` 来标识： - -{{< tabs-panel "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z" >}} - -A - -- ACTION -- ADD (R) -- ADDDATE -- ADMIN -- AFTER -- ALL (R) -- ALTER (R) -- ALWAYS -- ANALYZE(R) -- AND (R) -- ANY -- AS (R) -- ASC (R) -- ASCII -- AUTO_INCREMENT -- AVG -- AVG_ROW_LENGTH - -B - -- BEGIN -- BETWEEN (R) -- BIGINT (R) -- BINARY (R) -- BINLOG -- BIT -- BIT_XOR -- BLOB (R) -- BOOL -- BOOLEAN -- BOTH (R) -- BTREE -- BY (R) -- BYTE - -C - -- CASCADE (R) -- CASE (R) -- CAST -- CHANGE (R) -- CHAR (R) -- CHARACTER (R) -- CHARSET -- CHECK (R) -- CHECKSUM -- COALESCE -- COLLATE (R) -- COLLATION -- COLUMN (R) -- COLUMNS -- COMMENT -- COMMIT -- COMMITTED -- COMPACT -- COMPRESSED -- COMPRESSION -- CONNECTION -- CONSISTENT -- CONSTRAINT (R) -- CONVERT (R) -- COUNT -- CREATE (R) -- CROSS (R) -- CUME_DIST (R-Window) -- CURRENT_DATE (R) -- CURRENT_TIME (R) -- CURRENT_TIMESTAMP (R) -- CURRENT_USER (R) -- CURTIME - -D - -- DATA -- DATABASE (R) -- DATABASES (R) -- DATE -- DATE_ADD -- DATE_SUB -- DATETIME -- DAY -- DAY_HOUR (R) -- DAY_MICROSECOND (R) -- DAY_MINUTE (R) -- DAY_SECOND (R) -- DDL -- DEALLOCATE -- DEC -- DECIMAL (R) -- DEFAULT (R) -- DELAY_KEY_WRITE -- DELAYED (R) -- DELETE (R) -- DENSE_RANK (R-Window) -- DESC (R) -- DESCRIBE (R) -- DISABLE -- DISTINCT (R) -- DISTINCTROW (R) -- DIV (R) -- DO -- DOUBLE (R) -- DROP (R) -- DUAL (R) -- DUPLICATE -- DYNAMIC - -E - -- ELSE (R) -- ENABLE -- ENCLOSED -- END -- ENGINE -- ENGINES -- ENUM -- ESCAPE -- ESCAPED -- EVENTS -- EXCLUSIVE -- EXECUTE -- EXISTS -- EXPLAIN (R) -- EXTRACT - -F - -- FALSE (R) -- FIELDS -- FIRST -- FIRST_VALUE (R-Window) -- FIXED -- FLOAT (R) -- FLUSH -- FOR (R) -- FORCE (R) -- FOREIGN (R) -- FORMAT -- FROM (R) -- FULL -- FULLTEXT (R) -- FUNCTION - -G - -- GENERATED (R) -- GET_FORMAT -- GLOBAL -- GRANT (R) -- GRANTS -- GROUP (R) -- GROUP_CONCAT -- GROUPS (R-Window) - -H - -- HASH -- HAVING (R) -- HIGH_PRIORITY (R) -- HOUR -- HOUR_MICROSECOND (R) -- HOUR_MINUTE (R) -- HOUR_SECOND (R) - -I - -- IDENTIFIED -- IF (R) -- IGNORE (R) -- IN (R) -- INDEX (R) -- INDEXES -- INFILE (R) -- INNER (R) -- INSERT (R) -- INT (R) -- INTEGER (R) -- INTERVAL (R) -- INTO (R) -- IS (R) -- ISOLATION - -J - -- JOBS -- JOIN (R) -- JSON - -K - -- KEY (R) -- KEY_BLOCK_SIZE -- KEYS (R) -- KILL (R) - -L - -- LAG (R-Window) -- LAST_VALUE (R-Window) -- LEAD (R-Window) -- LEADING (R) -- LEFT (R) -- LESS -- LEVEL -- LIKE (R) -- LIMIT (R) -- LINES (R) -- LOAD (R) -- LOCAL -- LOCALTIME (R) -- LOCALTIMESTAMP (R) -- LOCK (R) -- LONGBLOB (R) -- LONGTEXT (R) -- LOW_PRIORITY (R) - -M - -- MAX -- MAX_ROWS -- MAXVALUE (R) -- MEDIUMBLOB (R) -- MEDIUMINT (R) -- MEDIUMTEXT (R) -- MICROSECOND -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND (R) -- MINUTE_SECOND (R) -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND -- MINUTE_SECOND -- MOD (R) -- MODE -- MODIRY -- MONTH - -N - -- NAMES -- NATIONAL -- NATURAL (R) -- NO -- NO_WRITE_TO_BINLOG (R) -- NONE -- NOT (R) -- NOW -- NTH_VALUE (R-Window) -- NTILE (R-Window) -- NULL (R) -- NUMERIC (R) -- NVARCHAR (R) - -O - -- OFFSET -- ON (R) -- ONLY -- OPTION (R) -- OR (R) -- ORDER (R) -- OUTER (R) -- OVER (R-Window) - -P - -- PARTITION (R) -- PARTITIONS -- PASSWORD -- PERCENT_RANK (R-Window) -- PLUGINS -- POSITION -- PRECISION (R) -- PREPARE -- PRIMARY (R) -- PRIVILEGES -- PROCEDURE (R) -- PROCESS -- PROCESSLIST - -Q - -- QUARTER -- QUERY -- QUICK - -R - -- RANGE (R) -- RANK (R-Window) -- READ (R) -- REAL (R) -- REDUNDANT -- REFERENCES (R) -- REGEXP (R) -- RENAME (R) -- REPEAT (R) -- REPEATABLE -- REPLACE (R) -- RESTRICT (R) -- REVERSE -- REVOKE (R) -- RIGHT (R) -- RLIKE (R) -- ROLLBACK -- ROW -- ROW_COUNT -- ROW_FORMAT -- ROW_NUMBER (R-Window) -- ROWS (R-Window) - -S - -- SCHEMA -- SCHEMAS -- SECOND -- SECOND_MICROSECOND (R) -- SELECT (R) -- SERIALIZABLE -- SESSION -- SET (R) -- SHARE -- SHARED -- SHOW (R) -- SIGNED -- SMALLINT (R) -- SNAPSHOT -- SOME -- SQL_CACHE -- SQL_CALC_FOUND_ROWS (R) -- SQL_NO_CACHE -- START -- STARTING (R) -- STATS -- STATS_BUCKETS -- STATS_HISTOGRAMS -- STATS_META -- STATS_PERSISTENT -- STATUS -- STORED (R) -- SUBDATE -- SUBSTR -- SUBSTRING -- SUM -- SUPER - -T - -- TABLE (R) -- TABLES -- TERMINATED (R) -- TEXT -- THAN -- THEN (R) -- TIDB -- TIDB_INLJ -- TIDB_SMJ -- TIME -- TIMESTAMP -- TIMESTAMPADD -- TIMESTAMPDIFF -- TINYBLOB (R) -- TINYINT (R) -- TINYTEXT (R) -- TO (R) -- TRAILING (R) -- TRANSACTION -- TRIGGER (R) -- TRIGGERS -- TRIM -- TRUE (R) -- TRUNCATE - -U - -- UNCOMMITTED -- UNION (R) -- UNIQUE (R) -- UNKNOWN -- UNLOCK (R) -- UNSIGNED (R) -- UPDATE (R) -- USE (R) -- USER -- USING (R) -- UTC_DATE (R) -- UTC_TIME (R) -- UTC_TIMESTAMP (R) - -V - -- VALUE -- VALUES (R) -- VARBINARY (R) -- VARCHAR (R) -- VARIABLES -- VIEW -- VIRTUAL (R) - -W - -- WARNINGS -- WEEK -- WHEN (R) -- WHERE (R) -- WINDOW (R-Window) -- WITH (R) -- WRITE (R) - -X - -- XOR (R) - -Y - -- YEAR -- YEAR_MONTH (R) - -Z - -- ZEROFILL (R) diff --git a/dev/reference/sql/statements/add-column.md b/dev/reference/sql/statements/add-column.md deleted file mode 100644 index b702ea6aa8e2..000000000000 --- a/dev/reference/sql/statements/add-column.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: ADD COLUMN -summary: TiDB 数据库中 ADD COLUMN 的使用概况。 -category: reference ---- - -# ADD COLUMN - -`ALTER TABLE.. ADD COLUMN` 语句用于在已有表中添加列。在 TiDB 中，`ADD COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (NULL); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+ -| id | -+----+ -| 1 | -+----+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD COLUMN c1 INT NOT NULL; -``` - -``` -Query OK, 0 rows affected (0.28 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 0 | -+----+----+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD c2 INT NOT NULL AFTER c1; -``` - -``` -Query OK, 0 rows affected (0.28 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+----+ -| id | c1 | c2 | -+----+----+----+ -| 1 | 0 | 0 | -+----+----+----+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持同时添加多列。 -* 不支持将新添加的列设为 `PRIMARY KEY`。 -* 不支持将新添加的列设为 `AUTO_INCREMENT`。 - -## 另请参阅 - -* [ADD INDEX](/dev/reference/sql/statements/add-index.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) diff --git a/dev/reference/sql/statements/add-index.md b/dev/reference/sql/statements/add-index.md deleted file mode 100644 index 1948b37d059c..000000000000 --- a/dev/reference/sql/statements/add-index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: ADD INDEX -summary: TiDB 数据库中 ADD INDEX 的使用概况。 -category: reference ---- - -# ADD INDEX - -`ALTER TABLE.. ADD INDEX` 语句用于在已有表中添加一个索引。在 TiDB 中，`ADD INDEX` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引（类似于 MySQL 5.7）。 -* 目前尚不支持同时添加多个索引。 -* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/dev/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [CREATE INDEX](/dev/reference/sql/statements/create-index.md) -* [DROP INDEX](/dev/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/dev/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/dev/reference/sql/statements/add-column.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [EXPLAIN](/dev/reference/sql/statements/explain.md) diff --git a/dev/reference/sql/statements/admin.md b/dev/reference/sql/statements/admin.md deleted file mode 100644 index 653f2b02e0be..000000000000 --- a/dev/reference/sql/statements/admin.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: ADMIN -category: reference ---- - -# ADMIN - -`ADMIN` 语句是 TiDB 扩展语法，用于查看 TiDB 自身的状态，并对 TiDB 中的表数据进行校验。示例如下。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL; -``` - -`ADMIN SHOW DDL` 用于查看当前正在执行的 DDL 作业。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOBS [NUM] [WHERE where_condition]; -``` - -* `NUM`：查看已经执行完成的 DDL 作业队列中最近 `NUM` 条结果，未指定时，默认值为 10。 -* `WHERE`：`WHERE` 子句，可以添加过滤条件。 - -`ADMIN SHOW DDL JOBS` 用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CANCEL DDL JOBS job_id [, job_id] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CHECK TABLE tbl_name [, tbl_name] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN REPAIR TABLE tbl_name CREATE TABLE STATEMENT; -``` - -## 语句概览 - -**AdminStmt**： - -![AdminStmt](/media/sqlgram/AdminStmt.png) - -## 使用示例 - -执行以下命令，可查看正在执行的 DDL 任务中最近 10 条已经完成的 DDL 任务。未指定 `NUM` 时，默认只显示最近 10 条已经执行完的 DDL 任务。 - -{{< copyable "sql" >}} - -```sql -admin show ddl jobs; -``` - -``` -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | END_TIME | STATE | -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | | running | -| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | 2019-01-10 12:36:55.852 +0800 CST | rollback done | -| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | 2019-01-10 12:35:14.925 +0800 CST | synced | -| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | 2019-01-10 12:34:36.958 +0800 CST | synced | -| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | 2019-01-10 12:33:24.625 +0800 CST | synced | -| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | 2019-01-10 12:33:09.78 +0800 CST | synced | -| 39 | test | t1 | add column | public | 32 | 37 | 0 | 2019-01-10 12:32:55.42 +0800 CST | 2019-01-10 12:32:56.24 +0800 CST | synced | -| 38 | test | t1 | create table | public | 32 | 37 | 0 | 2019-01-10 12:32:41.956 +0800 CST | 2019-01-10 12:32:43.956 +0800 CST | synced | -| 36 | test | | drop table | none | 32 | 34 | 0 | 2019-01-10 11:29:59.982 +0800 CST | 2019-01-10 11:30:00.45 +0800 CST | synced | -| 35 | test | | create table | public | 32 | 34 | 0 | 2019-01-10 11:29:40.741 +0800 CST | 2019-01-10 11:29:41.682 +0800 CST | synced | -| 33 | test | | create schema | public | 32 | 0 | 0 | 2019-01-10 11:29:22.813 +0800 CST | 2019-01-10 11:29:23.954 +0800 CST | synced | -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -``` - -执行以下命令，可查看正在执行的 DDL 任务中最近 5 条已经执行完的 DDL 任务： - -{{< copyable "sql" >}} - -```sql -admin show ddl jobs 5; -``` - -``` -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | END_TIME | STATE | -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | | running | -| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | 2019-01-10 12:36:55.852 +0800 CST | rollback done | -| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | 2019-01-10 12:35:14.925 +0800 CST | synced | -| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | 2019-01-10 12:34:36.958 +0800 CST | synced | -| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | 2019-01-10 12:33:24.625 +0800 CST | synced | -| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | 2019-01-10 12:33:09.78 +0800 CST | synced | -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -``` - -执行以下命令，可查看 test 数据库中未执行完成的 DDL 任务，包括正在执行中以及最近 5 条已经执行完但是执行失败的 DDL 任务。 - -{{< copyable "sql" >}} - -```sql -admin show ddl jobs 5 where state!='synced' and db_name='test'; -``` - -``` -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | END_TIME | STATE | -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | | running | -| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | 2019-01-10 12:36:55.852 +0800 CST | rollback done | -+--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ -``` - -* `JOB_ID`：每个 DDL 操作对应一个 DDL 作业，`JOB_ID` 全局唯一。 -* `DB_NAME`：执行 DDL 操作的数据库的名称。 -* `TABLE_NAME`：执行 DDL 操作的表的名称。 -* `JOB_TYPE`：DDL 操作的类型。 -* `SCHEMA_STATE`：schema 的当前状态。如果 `JOB_TYPE` 是 `add index`，则为 index 的状态；如果是 `add column`，则为 column 的状态，如果是 `create table`，则为 table 的状态。常见的状态有以下几种： - * `none`：表示不存在。一般 `drop` 操作或者 `create` 操作失败回滚后，会变为 `none` 状态。 - * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在[Online, Asynchronous Schema Change in F1](http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。 - * `public`：表示存在且可用。一般 `create table` 和 `add index/column` 等操作完成后，会变为 `public` 状态，表示新建的 table/column/index 可以正常读写了。 -* `SCHEMA_ID`：执行 DDL 操作的数据库的 ID。 -* `TABLE_ID`：执行 DDL 操作的表的 ID。 -* `ROW_COUNT`：执行 `add index` 操作时，当前已经添加完成的数据行数。 -* `START_TIME`：DDL 操作的开始时间。 -* `END_TIME`：DDL 操作的结束时间。 -* `STATE`：DDL 操作的状态。常见的状态有以下几种： - * `none`：表示该操作任务已经进入 DDL 作业队列中，但尚未执行，因为还在排队等待前面的 DDL 作业完成。另一种原因可能是执行 `drop` 操作后，会变为 `none` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。 - * `running`：表示该操作正在执行。 - * `synced`：表示该操作已经执行成功，且所有 TiDB 实例都已经同步该状态。 - * `rollback done`：表示该操作执行失败，回滚完成。 - * `rollingback`：表示该操作执行失败，正在回滚。 - * `cancelling`：表示正在取消该操作。这个状态只有在用 `ADMIN CANCEL DDL JOBS` 命令取消 DDL 作业时才会出现。 - -- `ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...`：用于查看 `job_id` 对应的 DDL 任务的原始 SQL 语句。这个 `job_id` 只会搜索正在运行中的 DDL 作业以及 DDL 历史作业队列中最近的十条结果。 -- `ADMIN CANCEL DDL JOBS job_id [, job_id] ...`：用于取消当前正在运行的 DDL 作业，并返回对应作业是否取消成功。如果取消失败，会显示失败的具体原因。 - - > **注意：** - > - > - 只有该操作可以取消 DDL 作业，其他所有的操作和环境变更（例如机器重启、集群重启）都不会取消 DDL 作业。 - > - 该操作可以同时取消多个 DDL 作业。可以通过 `ADMIN SHOW DDL JOBS` 语句来获取 DDL 作业的 ID。 - > - 如果希望取消的作业已经完成，则取消操作将会失败。 - -- `ADMIN CHECK TABLE tbl_name [, tbl_name] ...`：用于对给定表中的所有数据和对应索引进行一致性校验，若通过校验，则返回空的查询结果；否则返回数据不一致的错误信息。 - -- `ADMIN REPAIR TABLE tbl_name CREATE TABLE STATEMENT`：在极端情况下，用于对存储层中的表的元信息进行非可信的覆盖，“非可信”是指需要人为保证原表的元信息可以完全由 `CREATE TABLE STATEMENT` 提供。该语句需要打开配置文件项中的 [`repair-mode`](/dev/reference/configuration/tidb-server/configuration-file.md#repair-mode) 开关，并且需要确保所修复的表名在 [`repair-table-list`](/dev/reference/configuration/tidb-server/configuration-file.md#repair-table-list) 名单中。 - -## MySQL 兼容性 - -ADMIN 语句是 TiDB 对于 MySQL 语法的扩展。 diff --git a/dev/reference/sql/statements/alter-database.md b/dev/reference/sql/statements/alter-database.md deleted file mode 100644 index 5f540d8fe644..000000000000 --- a/dev/reference/sql/statements/alter-database.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: ALTER DATABASE -summary: TiDB 数据库中 ALTER DATABASE 的使用概况。 -category: reference ---- - -# ALTER DATABASE - -`ALTER DATABASE` 用于修改指定或当前数据库的默认字符集和排序规则。`ALTER SCHEMA` 跟 `ALTER DATABASE` 操作效果一样。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -ALTER {DATABASE | SCHEMA} [db_name] - alter_specification ... -alter_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -`alter_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/dev/reference/sql/character-set.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/dev/reference/sql/statements/create-database.md) -* [SHOW DATABASES](/dev/reference/sql/statements/show-databases.md) diff --git a/dev/reference/sql/statements/alter-table.md b/dev/reference/sql/statements/alter-table.md deleted file mode 100644 index 92aca261dc78..000000000000 --- a/dev/reference/sql/statements/alter-table.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: ALTER TABLE -summary: TiDB 数据库中 ALTER TABLE 的使用概况。 -category: reference ---- - -# ALTER TABLE - -`ALTER TABLE` 语句用于对已有表进行修改，以符合新表结构。`ALTER TABLE` 语句可用于： - -* [`ADD`](/dev/reference/sql/statements/add-index.md)，[`DROP`](/dev/reference/sql/statements/drop-index.md)，或 [`RENAME`](/dev/reference/sql/statements/rename-index.md) 索引 -* [`ADD`](/dev/reference/sql/statements/add-column.md)，[`DROP`](/dev/reference/sql/statements/drop-column.md)，[`MODIFY`](/dev/reference/sql/statements/modify-column.md) 或 [`CHANGE`](/dev/reference/sql/statements/change-column.md) 列 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 支持除空间类型外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 - -## 另请参阅 - -* [ADD COLUMN](/dev/reference/sql/statements/add-column.md) -* [DROP COLUMN](/dev/reference/sql/statements/drop-column.md) -* [ADD INDEX](/dev/reference/sql/statements/add-index.md) -* [DROP INDEX](/dev/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/dev/reference/sql/statements/rename-index.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/alter-user.md b/dev/reference/sql/statements/alter-user.md deleted file mode 100644 index 2125c364e9e5..000000000000 --- a/dev/reference/sql/statements/alter-user.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: ALTER USER -summary: TiDB 数据库中 ALTER USER 的使用概况。 -category: reference ---- - -# ALTER USER - -`ALTER USER` 语句用于更改 TiDB 权限系统内的已有用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**AlterUserStmt:** - -![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'newuser'; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*5806E04BBEE79E1899964C6A04D68BCA69B1A879' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER USER 'newuser' IDENTIFIED BY 'newnewpassword'; -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'newuser'; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*FB8A1EA1353E8775CA836233E367FBDFCB37BE73' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，`ALTER` 语句用于更改属性，例如使密码失效。但 TiDB 尚不支持此功能。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/dev/reference/security/compatibility.md) -* [CREATE USER](/dev/reference/sql/statements/create-user.md) -* [DROP USER](/dev/reference/sql/statements/drop-user.md) -* [SHOW CREATE USER](/dev/reference/sql/statements/show-create-user.md) diff --git a/dev/reference/sql/statements/analyze-table.md b/dev/reference/sql/statements/analyze-table.md deleted file mode 100644 index e926b205aa96..000000000000 --- a/dev/reference/sql/statements/analyze-table.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: ANALYZE TABLE -summary: TiDB 数据库中 ANALYZE TABLE 的使用概况。 -category: reference ---- - -# ANALYZE TABLE - -`ANALYZE TABLE` 语句用于更新 TiDB 在表和索引上留下的统计信息。执行大批量更新或导入记录后，或查询执行计划不是最佳时，建议运行 `ANALYZE TABLE`。 - -当 TiDB 逐渐发现这些统计数据与预估不一致时，也会自动更新其统计数据。 - -## 语法图 - -**AnalyzeTableStmt:** - -![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -analyze table t1; -``` - -``` -Query OK, 0 rows affected (0.13 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+---------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------------------------------------------+ -| IndexReader_6 | 1.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 1.00 | cop | table:t1, index:c1, range:[3,3], keep order:false | -+-------------------+-------+------+---------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`ANALYZE TABLE` 在语法上与 MySQL 类似。但 `ANALYZE TABLE` 在 TiDB 上执行所需时间可能长得多，因为它的内部运行方式不同。 - -## 另请参阅 - -* [EXPLAIN](/dev/reference/sql/statements/explain.md) -* [EXPLAIN ANALYZE](/dev/reference/sql/statements/explain-analyze.md) diff --git a/dev/reference/sql/statements/begin.md b/dev/reference/sql/statements/begin.md deleted file mode 100644 index ef45fdad30cc..000000000000 --- a/dev/reference/sql/statements/begin.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: BEGIN -summary: TiDB 数据库中 BEGIN 的使用概况。 -category: reference ---- - -# BEGIN - -`BEGIN` 语句用于在 TiDB 内启动一个新事务，类似于 `START TRANSACTION` 和 `SET autocommit=0` 语句。 - -在没有 `BEGIN` 语句的情况下，每个语句默认在各自的事务中自动提交，从而确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`BEGIN` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上[提交 issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/dev/reference/sql/statements/commit.md) -* [ROLLBACK](/dev/reference/sql/statements/rollback.md) -* [START TRANSACTION](/dev/reference/sql/statements/start-transaction.md) diff --git a/dev/reference/sql/statements/change-column.md b/dev/reference/sql/statements/change-column.md deleted file mode 100644 index 45938dd52d55..000000000000 --- a/dev/reference/sql/statements/change-column.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: CHANGE COLUMN -summary: TiDB 数据库中 CHANGE COLUMN 的使用概况。 -category: reference ---- - -# CHANGE COLUMN - -`ALTER TABLE.. CHANGE COLUMN` 语句用于在已有表上更改列，包括对列进行重命名，和将数据改为兼容类型。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col1 col2 INT; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col2 col3 BIGINT, ALGORITHM=INSTANT; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col3 INT; -``` - -``` -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col3 BLOB; -``` - -``` -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col4 BIGINT, CHANGE id id2 INT NOT NULL; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前尚不支持在单个 `ALTER TABLE` 语句中进行多个更改。 -* 仅支持特定的数据类型更改。例如，支持将 `INTEGER` 更改为 `BIGINT`，但不支持将 `BIGINT` 更改为 `INTEGER`。不支持从整数更改为字符串格式或 BLOB 类型。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/dev/reference/sql/statements/add-column.md) -* [DROP COLUMN](/dev/reference/sql/statements/drop-column.md) -* [MODIFY COLUMN](/dev/reference/sql/statements/modify-column.md) diff --git a/dev/reference/sql/statements/commit.md b/dev/reference/sql/statements/commit.md deleted file mode 100644 index 1e498b19866a..000000000000 --- a/dev/reference/sql/statements/commit.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: COMMIT -summary: TiDB 数据库中 COMMIT 的使用概况。 -category: reference ---- - -# COMMIT - -`COMMIT` 语句用于在 TiDB 服务器内部提交事务。 - -在不使用 `BEGIN` 或 `START TRANSACTION` 语句的情况下，TiDB 中每一个查询语句本身也会默认作为事务处理，自动提交，确保了与 MySQL 的兼容。 - -## 语法图 - -**CommitStmt:** - -![CommitStmt](/media/sqlgram/CommitStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，除了有多个 primary 的群组复制以外，`COMMIT` 语句通常不会导致错误。相比之下，TiDB 使用乐观并发控制，冲突可能导致 `COMMIT` 返回错误。 -* 默认情况下，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。 - -## 另请参阅 - -* [START TRANSACTION](/dev/reference/sql/statements/start-transaction.md) -* [ROLLBACK](/dev/reference/sql/statements/rollback.md) -* [BEGIN](/dev/reference/sql/statements/begin.md) -* [事务的惰性检查](/dev/reference/transactions/overview.md#事务的惰性检查) diff --git a/dev/reference/sql/statements/create-database.md b/dev/reference/sql/statements/create-database.md deleted file mode 100644 index 9aad7635014a..000000000000 --- a/dev/reference/sql/statements/create-database.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: CREATE DATABASE -summary: TiDB 数据库中 CREATE DATABASE 的使用概况。 -category: reference ---- - -# CREATE DATABASE - -`CREATE DATABASE` 语句用于在 TiDB 上创建新数据库。按照 SQL 标准，“数据库” 一词在 MySQL 术语中最接近 “schema”。 - -## 语法图 - -**CreateDatabaseStmt:** - -![CreateDatabaseStmt](/media/sqlgram/CreateDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -**DatabaseOptionListOpt:** - -![DatabaseOptionListOpt](/media/sqlgram/DatabaseOptionListOpt.png) - -## 语法说明 - -`CREATE DATABASE` 用于创建数据库，并可以指定数据库的默认属性（如数据库默认字符集、排序规则）。`CREATE SCHEMA` 跟 `CREATE DATABASE` 操作效果一样。 - -{{< copyable "sql" >}} - -```sql -CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name - [create_specification] ... - -create_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -当创建已存在的数据库且不指定使用 `IF NOT EXISTS` 时会报错。 - -`create_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/dev/reference/sql/character-set.md)。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE mynewdatabase; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -USE mynewdatabase; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+-------------------------+ -| Tables_in_mynewdatabase | -+-------------------------+ -| t1 | -+-------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [USE](/dev/reference/sql/statements/use.md) -* [ALTER DATABASE](/dev/reference/sql/statements/alter-database.md) -* [DROP DATABASE](/dev/reference/sql/statements/drop-database.md) -* [SHOW DATABASES](/dev/reference/sql/statements/show-databases.md) diff --git a/dev/reference/sql/statements/create-index.md b/dev/reference/sql/statements/create-index.md deleted file mode 100644 index dcd8f36f58ae..000000000000 --- a/dev/reference/sql/statements/create-index.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: CREATE INDEX -summary: CREATE INDEX 在 TiDB 中的使用概况 -category: reference ---- - -# CREATE INDEX - -`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 `ALTER TABLE .. ADD INDEX`。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**CreateIndexStmt:** - -![CreateIndexStmt](/media/sqlgram/CreateIndexStmt.png) - -**CreateIndexStmtUnique:** - -![CreateIndexStmtUnique](/media/sqlgram/CreateIndexStmtUnique.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -**IndexTypeOpt:** - -![IndexTypeOpt](/media/sqlgram/IndexTypeOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**IndexColNameList:** - -![IndexColNameList](/media/sqlgram/IndexColNameList.png) - -**IndexOptionList:** - -![IndexOptionList](/media/sqlgram/IndexOptionList.png) - -**IndexOption:** - -![IndexOption](/media/sqlgram/IndexOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE UNIQUE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.31 sec) -``` - -## 相关 session 变量 - -和 `CREATE INDEX` 语句相关的全局变量有 `tidb_ddl_reorg_worker_cnt`，`tidb_ddl_reorg_batch_size` 和 `tidb_ddl_reorg_priority`，具体可以参考 [TiDB 特定系统变量](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_ddl_reorg_worker_cnt)。 - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引 （类似于 MySQL 5.7）。 -* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/dev/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [ADD INDEX](/dev/reference/sql/statements/add-index.md) -* [DROP INDEX](/dev/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/dev/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/dev/reference/sql/statements/add-column.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [EXPLAIN](/dev/reference/sql/statements/explain.md) diff --git a/dev/reference/sql/statements/create-table-like.md b/dev/reference/sql/statements/create-table-like.md deleted file mode 100644 index 320738c0a338..000000000000 --- a/dev/reference/sql/statements/create-table-like.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: CREATE TABLE LIKE -summary: TiDB 数据库中 CREATE TABLE LIKE 的使用概况。 -category: reference ---- - -# CREATE TABLE LIKE - -`CREATE TABLE LIKE` 语句用于复制已有表的定义，但不复制任何数据。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**LikeTableWithOrWithoutParen:** - -![LikeTableWithOrWithoutParen](/media/sqlgram/LikeTableWithOrWithoutParen.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.13 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE TABLE LIKE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/create-table.md b/dev/reference/sql/statements/create-table.md deleted file mode 100644 index d1bc93424d8b..000000000000 --- a/dev/reference/sql/statements/create-table.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: CREATE TABLE -summary: TiDB 数据库中 CREATE TABLE 的使用概况 -category: reference ---- - -# CREATE TABLE - -`CREATE TABLE` 语句用于在当前所选数据库中创建新表。另可参阅单独的 `CREATE TABLE LIKE` 文档。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**TableElementListOpt:** - -![TableElementListOpt](/media/sqlgram/TableElementListOpt.png) - -**TableElement:** - -![TableElement](/media/sqlgram/TableElement.png) - -**PartitionOpt:** - -![PartitionOpt](/media/sqlgram/PartitionOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**Type:** - -![Type](/media/sqlgram/Type.png) - -**ColumnOptionListOpt:** - -![ColumnOptionListOpt](/media/sqlgram/ColumnOptionListOpt.png) - -**TableOptionListOpt:** - -![TableOptionListOpt](/media/sqlgram/TableOptionListOpt.png) - -## 语法说明 - -`CREATE TABLE` 用于创建一个表。目前不支持临时表，不支持 `CHECK` 约束，不支持创建表的同时从其它表导入数据功能。在语法上也支持一些 `Partition_options`，但是并不完全，就不做列举了。 - -以下是 `CREATE TABLE` 相关的语法说明： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - (create_definition,...) - [table_options] -``` - -使用 `IF NOT EXIST` 时，即使创建的表已经存在，也不会报错，如果不指定时，则报错。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - { LIKE old_tbl_name | (LIKE old_tbl_name) } -``` - -使用 `LIKE` 基于一个表的定义创建一个空表，包括这个表中的列属性和索引属性。 - -```sql -create_definition: - col_name column_definition - | [CONSTRAINT [symbol]] PRIMARY KEY [index_type] (index_col_name,...) - [index_option] ... - | {INDEX|KEY} [index_name] [index_type] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY] - [index_name] [index_type] (index_col_name,...) - [index_option] ... - | {FULLTEXT} [INDEX|KEY] [index_name] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] FOREIGN KEY - [index_name] (index_col_name,...) reference_definition -``` - -`create_definition` 中 `FULLTEXT` 和 `FOREIGN KEY` 目前只是语法上支持。 - -```sql -column_definition: - data_type [NOT NULL | NULL] [DEFAULT default_value] - [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] - [COMMENT 'string'] - [reference_definition] - | data_type [GENERATED ALWAYS] AS (expression) - [VIRTUAL | STORED] [UNIQUE [KEY]] [COMMENT comment] - [NOT NULL | NULL] [[PRIMARY] KEY] - -data_type: - BIT[(length)] - | TINYINT[(length)] [UNSIGNED] [ZEROFILL] - | SMALLINT[(length)] [UNSIGNED] [ZEROFILL] - | MEDIUMINT[(length)] [UNSIGNED] [ZEROFILL] - | INT[(length)] [UNSIGNED] [ZEROFILL] - | INTEGER[(length)] [UNSIGNED] [ZEROFILL] - | BIGINT[(length)] [UNSIGNED] [ZEROFILL] - | REAL[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DOUBLE[(length,decimals)] [UNSIGNED] [ZEROFILL] - | FLOAT[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DECIMAL[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | NUMERIC[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | DATE - | TIME[(fsp)] - | TIMESTAMP[(fsp)] - | DATETIME[(fsp)] - | YEAR - | CHAR[(length)] [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | VARCHAR(length) [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | BINARY[(length)] - | VARBINARY(length) - | TINYBLOB - | BLOB - | MEDIUMBLOB - | LONGBLOB - | TINYTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | TEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | MEDIUMTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | LONGTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | ENUM(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | SET(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | JSON -``` - -`data_type` 请参考[数据类型](/dev/reference/sql/data-types/overview.md)章节。 - -```sql -index_col_name: - col_name [(length)] [ASC | DESC] -``` - -`index_col_name` 中 `[ASC | DESC]` 目前只是语法上支持。 - -```sql -index_type: - USING {BTREE | HASH} -``` - -`index_type` 目前只是语法上支持。 - -```sql -index_option: - KEY_BLOCK_SIZE [=] value - | index_type - | COMMENT 'string' -``` - -`index_option` 中 `KEY_BLOCK_SIZE` 目前只是语法上支持。 - -```sql -reference_definition: - REFERENCES tbl_name (index_col_name,...) - [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] - [ON DELETE reference_option] - [ON UPDATE reference_option] - -reference_option: - RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT -``` - -```sql -table_options: - table_option [[,] table_option] ... - -table_option: - AUTO_INCREMENT [=] value - | AVG_ROW_LENGTH [=] value - | SHARD_ROW_ID_BITS [=] value - | PRE_SPLIT_REGIONS [=] value - | [DEFAULT] CHARACTER SET [=] charset_name - | CHECKSUM [=] {0 | 1} - | [DEFAULT] COLLATE [=] collation_name - | COMMENT [=] 'string' - | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'} - | CONNECTION [=] 'connect_string' - | DELAY_KEY_WRITE [=] {0 | 1} - | ENGINE [=] engine_name - | KEY_BLOCK_SIZE [=] value - | MAX_ROWS [=] value - | MIN_ROWS [=] value - | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT} - | STATS_PERSISTENT [=] {DEFAULT|0|1} -``` - -`table_option` 目前支持的只有 `AUTO_INCREMENT`、`SHARD_ROW_ID_BITS`（详情介绍请参考 [TiDB 专用系统变量和语法](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）、`PRE_SPLIT_REGIONS`、`CHARACTER SET`、`COLLATE` 和 `COMMENT`，其它只是语法上支持。具体内容参考下表，各个子句之间用逗号隔开。 - -| 参数 |含义 |举例 | -|----------------|--------------------------------------|----------------------------| -|`AUTO_INCREMENT`|自增字段初始值 |`AUTO_INCREMENT` = 5| -|`SHARD_ROW_ID_BITS`|用来设置隐式 _tidb_rowid 的分片数量的 bit 位数 |`SHARD_ROW_ID_BITS` = 4| -|`PRE_SPLIT_REGIONS`|用来在建表时预先均匀切分 `2^(PRE_SPLIT_REGIONS)` 个 Region |`PRE_SPLIT_REGIONS` = 4| -|`CHARACTER SET` |指定该表所使用的字符集 | `CHARACTER SET` = 'utf8mb4'| -|`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| -|`COMMENT` |注释信息 | `COMMENT` = 'comment info'| - -`split-table` 配置项默认情况下会开启，在此配置项开启时，建表操作会为每个表建立单独的 Region。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESC t1; -``` - -``` -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 不支持 `CREATE TEMPORARY TABLE` 语法。 -* 支持除空间类型以外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* `KEY_BLOCK_SIZE` 和 `ENGINE` 属性可被解析，但会被忽略。 -* `index_col_name` 属性支持 length 选项，最大长度限制为 3072 字节。此长度限制不会更改，具体取决于存储引擎和建表时使用的字符集。 -* `index_col_name` 属性支持 `ASC` 和 `DESC` 的索引排序选项。 -* `COMMENT` 属性最多支持 1024 个字符，不支持 `WITH PARSER` 选项。 -* TiDB 在单个表中最多支持 512 列。InnoDB 中相应的数量限制为 1017，MySQL 中的硬限制为 4096。 - -## 另请参阅 - -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [CREATE TABLE LIKE](/dev/reference/sql/statements/create-table-like.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/create-user.md b/dev/reference/sql/statements/create-user.md deleted file mode 100644 index dc71a86879e9..000000000000 --- a/dev/reference/sql/statements/create-user.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: CREATE USER -summary: TiDB 数据库中 CREATE USER 的使用概况。 -category: reference ---- - -# CREATE USER - -`CREATE USER` 语句用于创建带有指定密码的新用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**CreateUserStmt:** - -![CreateUserStmt](/media/sqlgram/CreateUserStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -**AuthOption:** - -![AuthOption](/media/sqlgram/AuthOption.png) - -**StringName:** - -![StringName](/media/sqlgram/StringName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser2'@'192.168.1.1' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -## MySQL 兼容性 - -* TiDB 尚不支持若干 `CREATE` 选项。这些选项可被解析，但会被忽略。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/dev/reference/security/compatibility.md) -* [DROP USER](/dev/reference/sql/statements/drop-user.md) -* [SHOW CREATE USER](/dev/reference/sql/statements/show-create-user.md) -* [ALTER USER](/dev/reference/sql/statements/alter-user.md) -* [Privilege Management](/dev/reference/security/privilege-system.md) diff --git a/dev/reference/sql/statements/create-view.md b/dev/reference/sql/statements/create-view.md deleted file mode 100644 index 7101453e3f9a..000000000000 --- a/dev/reference/sql/statements/create-view.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: CREATE VIEW -summary: TiDB 数据库中 CREATE VIEW 的使用概况。 -category: reference ---- - -# CREATE VIEW - -使用 `CREATE VIEW` 语句将 `SELECT` 语句保存为类似于表的可查询对象。TiDB 中的视图是非物化的，这意味着在查询视图时，TiDB 将在内部重写查询，以将视图定义与 SQL 查询结合起来。 - -## 语法图 - -**CreateViewStmt:** - -![CreateViewStmt](/media/sqlgram/CreateViewStmt.png) - -**OrReplace:** - -![OrReplace](/media/sqlgram/OrReplace.png) - -**ViewAlgorithm:** - -![ViewAlgorithm](/media/sqlgram/ViewAlgorithm.png) - -**ViewDefiner:** - -![ViewDefiner](/media/sqlgram/ViewDefiner.png) - -**ViewSQLSecurity:** - -![ViewSQLSecurity](/media/sqlgram/ViewSQLSecurity.png) - -**ViewName:** - -![ViewName](/media/sqlgram/ViewName.png) - -**ViewFieldList:** - -![ViewFieldList](/media/sqlgram/ViewFieldList.png) - -**ViewCheckOption:** - -![ViewCheckOption](/media/sqlgram/ViewCheckOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (6); -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -| 6 | 6 | -+----+----+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO v1 (c1) VALUES (7); -``` - -``` -ERROR 1105 (HY000): insert into view v1 is not supported now. -``` - -## MySQL 兼容性 - -* 目前 TiDB 中的视图不可插入且不可更新。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) diff --git a/dev/reference/sql/statements/deallocate.md b/dev/reference/sql/statements/deallocate.md deleted file mode 100644 index bab570283582..000000000000 --- a/dev/reference/sql/statements/deallocate.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: DEALLOCATE -summary: TiDB 数据库中 DEALLOCATE 的使用概况。 -category: reference ---- - -# DEALLOCATE - -`DEALLOCATE` 语句用于为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**DeallocateStmt:** - -![DeallocateStmt](/media/sqlgram/DeallocateStmt.png) - -**DeallocateSym:** - -![DeallocateSym](/media/sqlgram/DeallocateSym.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`DEALLOCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/dev/reference/sql/statements/prepare.md) -* [EXECUTE](/dev/reference/sql/statements/execute.md) diff --git a/dev/reference/sql/statements/delete.md b/dev/reference/sql/statements/delete.md deleted file mode 100644 index 7c0a5834958a..000000000000 --- a/dev/reference/sql/statements/delete.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: DELETE -summary: TiDB 数据库中 DELETE 的使用概况。 -category: reference ---- - -# DELETE - -`DELETE` 语句用于从指定的表中删除行。 - -## 语法图 - -**DeleteFromStmt:** - -![DeleteFromStmt](/media/sqlgram/DeleteFromStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DELETE FROM t1 WHERE id = 4; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 5 | 5 | -+----+----+ -4 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DELETE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/dev/reference/sql/statements/insert.md) -* [SELECT](/dev/reference/sql/statements/select.md) -* [UPDATE](/dev/reference/sql/statements/update.md) -* [REPLACE](/dev/reference/sql/statements/replace.md) diff --git a/dev/reference/sql/statements/desc.md b/dev/reference/sql/statements/desc.md deleted file mode 100644 index 138016dda9c3..000000000000 --- a/dev/reference/sql/statements/desc.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESC -summary: TiDB 数据库中 DESC 的使用概况。 -category: reference ---- - -# DESC - -`DESC` 语句是 [`EXPLAIN`](/dev/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/dev/reference/sql/statements/describe.md b/dev/reference/sql/statements/describe.md deleted file mode 100644 index 75b481b55056..000000000000 --- a/dev/reference/sql/statements/describe.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESCRIBE -summary: TiDB 数据库中 DESCRIBE 的使用概况。 -category: reference ---- - -# DESCRIBE - -`DESCRIBE` 语句为 [`EXPLAIN`](/dev/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/dev/reference/sql/statements/do.md b/dev/reference/sql/statements/do.md deleted file mode 100644 index 02d53b83bf37..000000000000 --- a/dev/reference/sql/statements/do.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: DO | TiDB SQL Statement Reference -summary: TiDB 数据库中 DO 的使用概况。 -category: reference ---- - -# DO - -`DO` 语句用于执行表达式，而不返回结果。在 MySQL 中，`DO` 的一个常见用例是执行存储的程序，而无需处理结果。但是 TiDB 不提供存储例程，因此该功能的使用较为受限。 - -## 语法图 - -**DoStmt:** - -![DoStmt](/media/sqlgram/DoStmt.png) - -**ExpressionList:** - -![ExpressionList](/media/sqlgram/ExpressionList.png) - -**Expression:** - -![Expression](/media/sqlgram/Expression.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SELECT SLEEP(5); -``` - -``` -+----------+ -| SLEEP(5) | -+----------+ -| 0 | -+----------+ -1 row in set (5.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DO SLEEP(5); -``` - -``` -Query OK, 0 rows affected (5.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DO SLEEP(1), SLEEP(1.5); -``` - -``` -Query OK, 0 rows affected (2.50 sec) -``` - -## MySQL 兼容性 - -`DO` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SELECT](/dev/reference/sql/statements/select.md) diff --git a/dev/reference/sql/statements/drop-column.md b/dev/reference/sql/statements/drop-column.md deleted file mode 100644 index e1cadbfaafe7..000000000000 --- a/dev/reference/sql/statements/drop-column.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: DROP COLUMN -summary: TiDB 数据库中 DROP COLUMN 的使用概况。 -category: reference ---- - -# DROP COLUMN - -`DROP COLUMN` 语句用于从指定的表中删除列。在 TiDB 中，`COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, col1 INT NOT NULL, col2 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1,col2) VALUES (1,1),(2,2),(3,3),(4,4),(5,5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP COLUMN col1, DROP COLUMN col2; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP COLUMN col1; -``` - -``` -Query OK, 0 rows affected (0.27 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+ -| id | col2 | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持使用相同语句删除多个列。 - -## 另请参阅 - -* [ADD COLUMN](/dev/reference/sql/statements/add-column.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) diff --git a/dev/reference/sql/statements/drop-database.md b/dev/reference/sql/statements/drop-database.md deleted file mode 100644 index 5b9dac5955d7..000000000000 --- a/dev/reference/sql/statements/drop-database.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: DROP DATABASE -summary: TiDB 数据库中 DROP DATABASE 的使用概况。 -category: reference ---- - -# DROP DATABASE - -`DROP DATABASE` 语句用于永久删除指定的数据库 schema，以及删除所有在 schema 中创建的表和视图。与被删数据库相关联的用户权限不受影响。 - -## 语法图 - -**DropDatabaseStmt:** - -![DropDatabaseStmt](/media/sqlgram/DropDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfExists:** - -![IfExists](/media/sqlgram/IfExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP DATABASE test; -``` - -``` -Query OK, 0 rows affected (0.25 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -+--------------------+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/dev/reference/sql/statements/create-database.md) -* [ALTER DATABASE](/dev/reference/sql/statements/alter-database.md) diff --git a/dev/reference/sql/statements/drop-index.md b/dev/reference/sql/statements/drop-index.md deleted file mode 100644 index 07d3e088bffa..000000000000 --- a/dev/reference/sql/statements/drop-index.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: DROP INDEX -summary: TiDB 数据库中 DROP INDEX 的使用概况。 -category: reference ---- - -# DROP INDEX - -`DROP INDEX` 语句用于从指定的表中删除索引，并在 TiKV 中将空间标记为释放。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -## MySQL 兼容性 - -* 默认不支持删除 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/dev/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [SHOW INDEX](/dev/reference/sql/statements/show-index.md) -* [CREATE INDEX](/dev/reference/sql/statements/create-index.md) -* [ADD INDEX](/dev/reference/sql/statements/add-index.md) -* [RENAME INDEX](/dev/reference/sql/statements/rename-index.md) diff --git a/dev/reference/sql/statements/drop-table.md b/dev/reference/sql/statements/drop-table.md deleted file mode 100644 index 2779febc3b7b..000000000000 --- a/dev/reference/sql/statements/drop-table.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: DROP TABLE -summary: TiDB 数据库中 DROP TABLE 的使用概况。 -category: reference ---- - -# DROP TABLE - -`DROP TABLE` 语句用于从当前所选的数据库中删除表。如果表不存在则会报错，除非使用 `IF EXISTS` 修饰符。 - -按照设计，`DROP TABLE` 也会删除视图，因为视图与表共享相同的命名空间。 - -## 语法图 - -**DropTableStmt:** - -![DropTableStmt](/media/sqlgram/DropTableStmt.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE t1; -``` - -``` -Query OK, 0 rows affected (0.22 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE table_not_exists; -``` - -``` -ERROR 1051 (42S02): Unknown table 'test.table_not_exists' -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS table_not_exists; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT 1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE v1; -``` - -``` -Query OK, 0 rows affected (0.23 sec) -``` - -## MySQL 兼容性 - -* 在尝试删除不存在的表时，使用 `IF EXISTS` 删除表不会返回警告。[Issue #7867](https://github.com/pingcap/tidb/issues/7867) - -## 另请参阅 - -* [DROP VIEW](/dev/reference/sql/statements/drop-view.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [SHOW TABLES](/dev/reference/sql/statements/show-tables.md) diff --git a/dev/reference/sql/statements/drop-user.md b/dev/reference/sql/statements/drop-user.md deleted file mode 100644 index c47128f41bce..000000000000 --- a/dev/reference/sql/statements/drop-user.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: DROP USER -summary: TiDB 数据库中 DROP USER 的使用概况。 -category: reference ---- - -# DROP USER - -`DROP USER` 语句用于从 TiDB 系统数据库中删除用户。如果用户不存在，使用关键词 `IF EXISTS` 可避免出现警告。 - -## 语法图 - -**DropUserStmt:** - -![DropUserStmt](/media/sqlgram/DropUserStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -DROP USER idontexist; -``` - -``` -ERROR 1396 (HY000): Operation DROP USER failed for idontexist@% -``` - -{{< copyable "sql" >}} - -```sql -DROP USER IF EXISTS idontexist; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REVOKE ALL ON test.* FROM 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP USER newuser; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR newuser; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -* 在 TiDB 中删除不存在的用户时，使用 `IF EXISTS` 可避免出现警告。[Issue #10196](https://github.com/pingcap/tidb/issues/10196)。 - -## 另请参阅 - -* [CREATE USER](/dev/reference/sql/statements/create-user.md) -* [ALTER USER](/dev/reference/sql/statements/alter-user.md) -* [SHOW CREATE USER](/dev/reference/sql/statements/show-create-user.md) -* [Privilege Management](/dev/reference/security/privilege-system.md) diff --git a/dev/reference/sql/statements/drop-view.md b/dev/reference/sql/statements/drop-view.md deleted file mode 100644 index db00773c2c13..000000000000 --- a/dev/reference/sql/statements/drop-view.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: DROP VIEW -summary: TiDB 数据库中 DROP VIEW 的使用概况。 -category: reference ---- - -# DROP VIEW - -`DROP VIEW` 语句用于从当前所选定的数据库中删除视图对象。视图所引用的基表不受影响。 - -## 语法图 - -**DropViewStmt:** - -![DropViewStmt](/media/sqlgram/DropViewStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP VIEW v1; -``` - -``` -Query OK, 0 rows affected (0.23 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP VIEW` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## See also - -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [CREATE VIEW](/dev/reference/sql/statements/create-view.md) diff --git a/dev/reference/sql/statements/execute.md b/dev/reference/sql/statements/execute.md deleted file mode 100644 index 859b1c53612d..000000000000 --- a/dev/reference/sql/statements/execute.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: EXECUTE -summary: TiDB 数据库中 EXECUTE 的使用概况。 -category: reference ---- - -# EXECUTE - -`EXECUTE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**ExecuteStmt:** - -![ExecuteStmt](/media/sqlgram/ExecuteStmt.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`EXECUTE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/dev/reference/sql/statements/prepare.md) -* [DEALLOCATE](/dev/reference/sql/statements/deallocate.md) diff --git a/dev/reference/sql/statements/explain-analyze.md b/dev/reference/sql/statements/explain-analyze.md deleted file mode 100644 index 5d1d16a4c191..000000000000 --- a/dev/reference/sql/statements/explain-analyze.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: EXPLAIN ANALYZE -summary: TiDB 数据库中 EXPLAIN ANALYZE 的使用概况。 -category: reference ---- - -# EXPLAIN ANALYZE - -`EXPLAIN ANALYZE` 语句的工作方式类似于 `EXPLAIN`，主要区别在于前者实际上会执行语句。这样可以将查询计划中的估计值与执行时所遇到的实际值进行比较。如果估计值与实际值显著不同，那么应考虑在受影响的表上运行 `ANALYZE TABLE`。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN ANALYZE SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+---------------------------+ -| id | count | task | operator info | execution info | -+-------------+-------+------+--------------------+---------------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | time:0ns, loops:0, rows:0 | -+-------------+-------+------+--------------------+---------------------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN ANALYZE SELECT * FROM t1; -``` - -``` -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| id | count | task | operator info | execution info | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| TableReader_5 | 10000.00 | root | data:TableScan_4 | time:931.759µs, loops:2, rows:3 | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | time:0s, loops:0, rows:3 | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -该语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/dev/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN](/dev/reference/sql/statements/explain.md) -* [ANALYZE TABLE](/dev/reference/sql/statements/analyze-table.md) -* [TRACE](/dev/reference/sql/statements/trace.md) diff --git a/dev/reference/sql/statements/explain.md b/dev/reference/sql/statements/explain.md deleted file mode 100644 index b158e8359ff6..000000000000 --- a/dev/reference/sql/statements/explain.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: EXPLAIN -summary: TiDB 数据库中 EXPLAIN 的使用概况。 -category: reference ---- - -# EXPLAIN - -`EXPLAIN` 语句仅用于显示查询的执行计划，而不执行查询。`EXPLAIN ANALYZE` 可执行查询，补充 `EXPLAIN` 语句。如果 `EXPLAIN` 的输出与预期结果不匹配，可考虑在查询的每个表上执行 `ANALYZE TABLE`。 - -语句 `DESC` 和 `DESCRIBE` 是 `EXPLAIN` 的别名。`EXPLAIN ` 的替代用法记录在 [`SHOW [FULL] COLUMNS FROM`](/dev/reference/sql/statements/show-columns-from.md) 下。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT 1; -``` - -``` -+-------------------+-------+------+---------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------+ -| Projection_3 | 1.00 | root | 1 | -| └─TableDual_4 | 1.00 | root | rows:1 | -+-------------------+-------+------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESC SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESCRIBE SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN INSERT INTO t1 (c1) VALUES (4); -``` - -``` -ERROR 1105 (HY000): Unsupported type *core.Insert -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN UPDATE t1 SET c1=5 WHERE c1=3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN DELETE FROM t1 WHERE c1=3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -如果未指定 `FORMAT`，或未指定 `FORMAT ="row"`，那么 `EXPLAIN` 语句将以表格格式输出结果。更多信息，可参阅 [Understand the Query Execution Plan](https://pingcap.com/docs/dev/reference/performance/understanding-the-query-execution-plan/)。 - -除 MySQL 标准结果格式外，TiDB 还支持 DotGraph。需按照下列所示指定 `FORMAT ="dot"`： - -{{< copyable "sql" >}} - -```sql -create table t(a bigint, b bigint); -desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10; -``` - -```+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dot contents | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| -digraph HashRightJoin_7 { -subgraph cluster7{ -node [style=filled, color=lightgrey] -color=black -label = "root" -"HashRightJoin_7" -> "TableReader_10" -"HashRightJoin_7" -> "TableReader_12" -} -subgraph cluster9{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"Selection_9" -> "TableScan_8" -} -subgraph cluster11{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"TableScan_11" -} -"TableReader_10" -> "Selection_9" -"TableReader_12" -> "TableScan_11" -} - | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -如果你的计算机上安装了 `dot` 程序（在 `graphviz` 包中），可使用以下方法生成 PNG 文件： - -{{< copyable "shell-regular" >}} - -```bash -dot xx.dot -T png -O -``` - -The `xx.dot` is the result returned by the above statement. - -如果你的计算机上未安装 `dot` 程序，可将结果复制到 [本网站](http://www.webgraphviz.com/) 以获取树形图： - -![Explain Dot](/media/explain_dot.png) - -## MySQL 兼容性 - -* `EXPLAIN` 的格式和 TiDB 中潜在的执行计划都与 MySQL 有很大不同。 -* TiDB 不像 MySQL 那样支持 `EXPLAIN FORMAT = JSON`。 -* TiDB 目前不支持插入语句的 `EXPLAIN`。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/dev/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN ANALYZE](/dev/reference/sql/statements/explain-analyze.md) -* [ANALYZE TABLE](/dev/reference/sql/statements/analyze-table.md) -* [TRACE](/dev/reference/sql/statements/trace.md) diff --git a/dev/reference/sql/statements/flush-privileges.md b/dev/reference/sql/statements/flush-privileges.md deleted file mode 100644 index 6d5d5a1f4ac1..000000000000 --- a/dev/reference/sql/statements/flush-privileges.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: FLUSH PRIVILEGES -summary: TiDB 数据库中 FLUSH PRIVILEGES 的使用概况。 -category: reference ---- - -# FLUSH PRIVILEGES - -`FLUSH PRIVILEGES` 语句可触发 TiDB 从权限表中重新加载权限的内存副本。在对如 `mysql.user` 一类的表进行手动编辑后，应当执行 `FLUSH PRIVILEGES`。使用如 `GRANT` 或 `REVOKE` 一类的权限语句后，不需要执行 `FLUSH PRIVILEGES` 语句。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`FLUSH PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [GRANT](/dev/reference/sql/statements/grant-privileges.md) -* [REVOKE ](/dev/reference/sql/statements/revoke-privileges.md) -* [Privilege Management](/dev/reference/security/privilege-system.md) diff --git a/dev/reference/sql/statements/flush-status.md b/dev/reference/sql/statements/flush-status.md deleted file mode 100644 index 6cf7d47f28bd..000000000000 --- a/dev/reference/sql/statements/flush-status.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: FLUSH STATUS -summary: TiDB 数据库中 FLUSH STATUS 的使用概况。 -category: reference ---- - -# FLUSH STATUS - -`FLUSH STATUS` 语句用于提供 MySQL 兼容性，但在 TiDB 上并无作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -show global status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -flush status; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| ddl_schema_version | 141 | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `FLUSH STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] STATUS](/dev/reference/sql/statements/show-status.md) diff --git a/dev/reference/sql/statements/flush-tables.md b/dev/reference/sql/statements/flush-tables.md deleted file mode 100644 index f6b57a47f74b..000000000000 --- a/dev/reference/sql/statements/flush-tables.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: FLUSH TABLES -summary: TiDB 数据库中 FLUSH TABLES 的使用概况。 -category: reference ---- - -# FLUSH TABLES - -`FLUSH TABLES` 语句用于提供 MySQL 兼容性，但在 TiDB 中并无有效用途。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameListOpt:** - -![TableNameListOpt](/media/sqlgram/TableNameListOpt.png) - -**WithReadLockOpt:** - -![WithReadLockOpt](/media/sqlgram/WithReadLockOpt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -FLUSH TABLES; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -FLUSH TABLES WITH READ LOCK; -``` - -``` -ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported. Please use @@tidb_snapshot -``` - -## MySQL 兼容性 - -* TiDB 没有 MySQL 中的表缓存这一概念。所以，`FLUSH TABLES` 因 MySQL 兼容性会在 TiDB 中解析出但会被忽略掉。 -* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads] 来实现锁表。 - -## 另请参阅 - -* [Read historical data](/dev/how-to/get-started/read-historical-data.md) diff --git a/dev/reference/sql/statements/grant-privileges.md b/dev/reference/sql/statements/grant-privileges.md deleted file mode 100644 index e0f58a379d51..000000000000 --- a/dev/reference/sql/statements/grant-privileges.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: GRANT -summary: TiDB 数据库中 GRANT 的使用概况。 -category: reference ---- - -# GRANT - -`GRANT ` 语句用于为 TiDB 中已存在的用户分配权限。TiDB 中的权限系统同 MySQL 一样，都基于数据库/表模式来分配凭据。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 与 MySQL 类似，`USAGE` 权限表示登录 TiDB 服务器的能力。 -* 目前不支持列级权限。 -* 与 MySQL 类似，不存在 `NO_AUTO_CREATE_USER` sql 模式时，`GRANT` 语句将在用户不存在时自动创建一个空密码的新用户。删除此 sql-mode（默认情况下已启用）会带来安全风险。 - -## 另请参阅 - -* [REVOKE ](/dev/reference/sql/statements/revoke-privileges.md) -* [SHOW GRANTS](/dev/reference/sql/statements/show-grants.md) -* [Privilege Management](/dev/reference/security/privilege-system.md) diff --git a/dev/reference/sql/statements/insert.md b/dev/reference/sql/statements/insert.md deleted file mode 100644 index ec94b72c16c5..000000000000 --- a/dev/reference/sql/statements/insert.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: INSERT -summary: TiDB 数据库中 INSERT 的使用概况。 -category: reference ---- - -# INSERT - -使用 `INSERT` 语句在表中插入新行。 - -## 语法图 - -**InsertIntoStmt:** - -![InsertIntoStmt](/media/sqlgram/InsertIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IgnoreOptional:** - -![IgnoreOptional](/media/sqlgram/IgnoreOptional.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (a) VALUES (1); -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t2 SELECT * FROM t1; -``` - -``` -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t2 VALUES (2),(3),(4); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -| 2 | -| 3 | -| 4 | -+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`INSERT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/dev/reference/sql/statements/delete.md) -* [SELECT](/dev/reference/sql/statements/select.md) -* [UPDATE](/dev/reference/sql/statements/update.md) -* [REPLACE](/dev/reference/sql/statements/replace.md) diff --git a/dev/reference/sql/statements/kill.md b/dev/reference/sql/statements/kill.md deleted file mode 100644 index 44df5874bd00..000000000000 --- a/dev/reference/sql/statements/kill.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: KILL [TIDB] -summary: TiDB 数据库中 KILL [TIDB] 的使用概况。 -category: reference ---- - -# KILL [TIDB] - -`KILL TIDB` 语句用于终止 TiDB 中的连接。 - -按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。 - -## 语法图 - -**KillStmt:** - -![KillStmt](/media/sqlgram/KillStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW PROCESSLIST; -``` - -``` -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -KILL TIDB 2; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -* `KILL TIDB` 语句是 TiDB 的扩展语法。如果正尝试终止的会话位于同一个 TiDB 服务器上，可在配置文件里设置 [`compatible-kill-query = true`](/dev/reference/configuration/tidb-server/configuration-file.md#compatible-kill-query)。 - -## 另请参阅 - -* [SHOW \[FULL\] PROCESSLIST](/dev/reference/sql/statements/show-processlist.md) diff --git a/dev/reference/sql/statements/load-data.md b/dev/reference/sql/statements/load-data.md deleted file mode 100644 index 94a27adaaa63..000000000000 --- a/dev/reference/sql/statements/load-data.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: LOAD DATA -summary: TiDB 数据库中 LOAD DATA 的使用概况。 -category: reference ---- - -# LOAD DATA - -`LOAD DATA` 语句用于将数据批量加载到 TiDB 表中。 - -## 语法图 - -**LoadDataStmt:** - -![LoadDataStmt](/media/sqlgram/LoadDataStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE trips ( - -> trip_id bigint NOT NULL PRIMARY KEY AUTO_INCREMENT, - -> duration integer not null, - -> start_date datetime, - -> end_date datetime, - -> start_station_number integer, - -> start_station varchar(255), - -> end_station_number integer, - -> end_station varchar(255), - -> bike_number varchar(255), - -> member_type varchar(255) - -> ); -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); -``` - -``` -Query OK, 815264 rows affected (39.63 sec) -Records: 815264 Deleted: 0 Skipped: 0 Warnings: 0 -``` - -`LOAD DATA` 也支持使用十六进制 ASCII 字符表达式或二进制 ASCII 字符表达式作为 `FIELDS ENCLOSED BY` 和 `FIELDS TERMINATED BY` 的参数。示例如下： - -{{< copyable "sql" >}} - -```sql -LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY x'2c' ENCLOSED BY b'100010' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); -``` - -以上示例中 `x'2c'` 是字符 `,` 的十六进制表示，`b'100010'` 是字符 `"` 的二进制表示。 - -## MySQL 兼容性 - -* 默认情况下，TiDB 每 20,000 行会进行一次提交。这类似于 MySQL NDB Cluster，但并非 InnoDB 存储引擎的默认配置。 - -> **注意：** -> -> 这种拆分事务提交的方式是以打破事务的原子性和隔离性为代价的，使用该特性时，使用者需要保证没有其他对正在处理的表的**任何**操作，并且在出现报错时，需要及时**人工介入，检查数据的一致性和完整性**。因此，不建议在生产环境中使用。 - -## 另请参阅 - -* [INSERT](/dev/reference/sql/statements/insert.md) -* [乐观事务模型](/dev/reference/transactions/transaction-optimistic.md) diff --git a/dev/reference/sql/statements/modify-column.md b/dev/reference/sql/statements/modify-column.md deleted file mode 100644 index 5494fbe7f2ca..000000000000 --- a/dev/reference/sql/statements/modify-column.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: MODIFY COLUMN -summary: TiDB 数据库中 MODIFY COLUMN 的使用概况。 -category: reference ---- - -# MODIFY COLUMN - -`ALTER TABLE .. MODIFY COLUMN` 语句用于修改已有表上的列，包括列的数据类型和属性。若要同时重命名，可改用 [`CHANGE COLUMN`](/dev/reference/sql/statements/change-column.md) 语句。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BIGINT; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `col1` bigint(20) DEFAULT NULL, - PRIMARY KEY (`id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=30001 -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 INT; -``` - -``` -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BLOB; -``` - -``` -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BIGINT, MODIFY id BIGINT NOT NULL; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前不支持使用单个 `ALTER TABLE` 语句进行多个修改。 -* 仅支持特定类型的数据类型更改。例如，支持将 `INTEGER` 改为 `BIGINT`，但不支持将 `BIGINT` 改为 `INTEGER`。不支持将整数改为字符串格式或 BLOB 格式。 -* 不支持修改 decimal 类型的精度。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/dev/reference/sql/statements/add-column.md) -* [DROP COLUMN](/dev/reference/sql/statements/drop-column.md) -* [CHANGE COLUMN](/dev/reference/sql/statements/change-column.md) diff --git a/dev/reference/sql/statements/prepare.md b/dev/reference/sql/statements/prepare.md deleted file mode 100644 index 47fa7a8f84b4..000000000000 --- a/dev/reference/sql/statements/prepare.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: PREPARE -summary: TiDB 数据库中 PREPARE 的使用概况。 -category: reference ---- - -# PREPARE - -`PREPARE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**PreparedStmt:** - -![PreparedStmt](/media/sqlgram/PreparedStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`PREPARE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [EXECUTE](/dev/reference/sql/statements/execute.md) -* [DEALLOCATE](/dev/reference/sql/statements/deallocate.md) diff --git a/dev/reference/sql/statements/recover-table.md b/dev/reference/sql/statements/recover-table.md deleted file mode 100644 index 4069bfddbe8f..000000000000 --- a/dev/reference/sql/statements/recover-table.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: RECOVER TABLE -category: reference ---- - -# RECOVER TABLE - -`RECOVER TABLE` 的功能是恢复被删除的表及其数据。在 `DROP TABLE` 后，在 GC life time 时间内，可以用 `RECOVER TABLE` 语句恢复被删除的表以及其数据。 - -## 语法 - -{{< copyable "sql" >}} - -```sql -RECOVER TABLE table_name -``` - -{{< copyable "sql" >}} - -```sql -RECOVER TABLE BY JOB ddl_job_id -``` - -## 注意事项 - -如果删除表后并过了 GC lifetime，就不能再用 `RECOVER TABLE` 来恢复被删除的表了，执行 `RECOVER TABLE` 语句会返回类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -对于 3.0.0 及之后的 TiDB 版本，不推荐在使用 TiDB Binlog 的情况下使用 `RECOVER TABLE` 功能。 - -TiDB Binlog 在 3.0.1 支持 `RECOVER TABLE` 后，可在下面的情况下使用 `RECOVER TABLE`： - -* 3.0.1+ 版本的 TiDB Binlog -* 主从集群都使用 TiDB 3.0 -* 从集群 GC lifetime 一定要长于主集群（不过由于上下游同步的延迟，可能也会造成下游 recover 失败） - -### TiDB Binlog 同步错误处理 - -当使用 TiDB Binlog 同步工具时，上游 TiDB 使用 `RECOVER TABLE` 后，TiDB Binlog 可能会因为下面几个原因造成同步中断： - -* 下游数据库不支持 `RECOVER TABLE` 语句。类似错误：`check the manual that corresponds to your MySQL server version for the right syntax to use near 'RECOVER TABLE table_name'`。 - -* 上下游数据库的 GC lifetime 不一样。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -* 上下游数据库的同步延迟。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -只能通过重新[全量导入被删除的表](/dev/reference/tools/user-guide.md#tidb-集群数据的全量备份及恢复-1)来恢复 TiDB Binlog 的数据同步。 - -## 示例 - -- 根据表名恢复被删除的表。 - - {{< copyable "sql" >}} - - ```sql - DROP TABLE t; - ``` - - {{< copyable "sql" >}} - - ```sql - RECOVER TABLE t; - ``` - - 根据表名恢复被删除的表需满足以下条件： - - - 最近 DDL JOB 历史中找到的第一个 `DROP TABLE` 操作，且 - - `DROP TABLE` 所删除的表的名称与 `RECOVER TABLE` 语句指定表名相同 - -- 根据删除表时的 DDL JOB ID 恢复被删除的表。 - - 如果第一次删除表 t 后，又新建了一个表 t，然后又把新建的表 t 删除了，此时如果想恢复最开始删除的表 t, 就需要用到指定 DDL JOB ID 的语法了。 - - {{< copyable "sql" >}} - - ```sql - DROP TABLE t; - ``` - - {{< copyable "sql" >}} - - ```sql - ADMIN SHOW DDL JOBS 1; - ``` - - 上面这个语句用来查找删除表 t 时的 DDL JOB ID，这里是 53： - - ``` - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - | JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - | 53 | test | | drop table | none | 1 | 41 | 0 | 2019-07-10 13:23:18.277 +0800 CST | synced | - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - ``` - - {{< copyable "sql" >}} - - ```sql - RECOVER TABLE BY JOB 53; - ``` - - 根据删除表时的 DDL JOB ID 恢复被删除的表，会直接用 DDL JOB ID 找到被删除表进行恢复。如果指定的 DDL JOB ID 的 DDL JOB 不是 `DROP TABLE` 类型，会报错。 - -## 原理 - -TiDB 在删除表时，实际上只删除了表的元信息，并将需要删除的表数据（行数据和索引数据）写一条数据到 `mysql.gc_delete_range` 表。TiDB 后台的 GC Worker 会定期从 `mysql.gc_delete_range` 表中取出超过 GC lifetime 相关范围的 key 进行删除。 - -所以，RECOVER TABLE 只需要在 GC Worker 还没删除表数据前，恢复表的元信息并删除 `mysql.gc_delete_range` 表中相应的行记录就可以了。恢复表的元信息可以用 TiDB 的快照读实现。具体的快照读内容可以参考[读取历史数据](/dev/how-to/get-started/read-historical-data.md)文档。 - -TiDB 中表的恢复是通过快照读获取表的元信息后，再走一次类似于 `CREATE TABLE` 的建表流程，所以 `RECOVER TABLE` 实际上也是一种 DDL。 diff --git a/dev/reference/sql/statements/rename-index.md b/dev/reference/sql/statements/rename-index.md deleted file mode 100644 index a948e2728090..000000000000 --- a/dev/reference/sql/statements/rename-index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: RENAME INDEX -summary: TiDB 数据库中 RENAME INDEX 的使用概况。 -category: reference ---- - -# RENAME INDEX - -`ALTER TABLE .. RENAME INDEX` 语句用于对已有索引进行重命名。这在 TiDB 中是即时操作的，仅需更改元数据。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL, INDEX col1 (c1)); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `col1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 RENAME INDEX col1 TO c1; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `c1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME INDEX` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [CREATE INDEX](/dev/reference/sql/statements/create-index.md) -* [DROP INDEX](/dev/reference/sql/statements/drop-index.md) -* [SHOW INDEX](/dev/reference/sql/statements/show-index.md) diff --git a/dev/reference/sql/statements/rename-table.md b/dev/reference/sql/statements/rename-table.md deleted file mode 100644 index 3fc2fc27f857..000000000000 --- a/dev/reference/sql/statements/rename-table.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: RENAME TABLE -summary: TiDB 数据库中 RENAME TABLE 的使用概况。 -category: reference ---- - -# RENAME TABLE - -`RENAME TABLE` 语句用于对已有表进行重命名。 - -## 语法图 - -**RenameTableStmt:** - -![RenameTableStmt](/media/sqlgram/RenameTableStmt.png) - -**TableToTable:** - -![TableToTable](/media/sqlgram/TableToTable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -+----------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -RENAME TABLE t1 TO t2; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t2 | -+----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW TABLES](/dev/reference/sql/statements/show-tables.md) -* [ALTER TABLE](/dev/reference/sql/statements/alter-table.md) diff --git a/dev/reference/sql/statements/replace.md b/dev/reference/sql/statements/replace.md deleted file mode 100644 index fe1cbff93a49..000000000000 --- a/dev/reference/sql/statements/replace.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: REPLACE -summary: TiDB 数据库中 REPLACE 的使用概况。 -category: reference ---- - -# REPLACE - -从语义上看，`REPLACE` 语句是 `DELETE` 语句和 `INSERT` 语句的结合，可用于简化应用程序代码。 - -## 语法图 - -**ReplaceIntoStmt:** - -![ReplaceIntoStmt](/media/sqlgram/ReplaceIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REPLACE INTO t1 (id, c1) VALUES(3, 99); -``` - -``` -Query OK, 2 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 99 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`REPLACE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/dev/reference/sql/statements/delete.md) -* [INSERT](/dev/reference/sql/statements/insert.md) -* [SELECT](/dev/reference/sql/statements/select.md) -* [UPDATE](/dev/reference/sql/statements/update.md) diff --git a/dev/reference/sql/statements/revoke-privileges.md b/dev/reference/sql/statements/revoke-privileges.md deleted file mode 100644 index 82aa56698db1..000000000000 --- a/dev/reference/sql/statements/revoke-privileges.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: REVOKE -summary: TiDB 数据库中 REVOKE 的使用概况。 -category: reference ---- - -# REVOKE - -`REVOKE ` 语句用于删除已有用户的权限。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REVOKE ALL ON test.* FROM 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP USER newuser; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR newuser; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -`REVOKE ` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [GRANT ](/dev/reference/sql/statements/grant-privileges.md) -* [SHOW GRANTS](/dev/reference/sql/statements/show-grants.md) -* [Privilege Management](/dev/reference/security/privilege-system.md) diff --git a/dev/reference/sql/statements/rollback.md b/dev/reference/sql/statements/rollback.md deleted file mode 100644 index 9cdcf5f148a7..000000000000 --- a/dev/reference/sql/statements/rollback.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: ROLLBACK -summary: TiDB 数据库中 ROLLBACK 的使用概况。 -category: reference ---- - -# ROLLBACK - -`ROLLBACK` 语句用于还原 TiDB 内当前事务中的所有更改，作用与 `COMMIT` 语句相反。 - -## 语法图 - -**Statement:** - -![Statement](/media/sqlgram/Statement.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -Empty set (0.01 sec) -``` - -## MySQL 兼容性 - -`ROLLBACK` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/dev/reference/sql/statements/commit.md) -* [BEGIN](/dev/reference/sql/statements/begin.md) -* [START TRANSACTION](/dev/reference/sql/statements/start-transaction.md) diff --git a/dev/reference/sql/statements/select.md b/dev/reference/sql/statements/select.md deleted file mode 100644 index e8b83945c812..000000000000 --- a/dev/reference/sql/statements/select.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: SELECT -summary: TiDB 数据库中 SELECT 的使用概况。 -category: reference ---- - -# SELECT - -`SELECT` 语句用于从 TiDB 读取数据。 - -## 语法图 - -**SelectStmt:** - -![SelectStmt](/media/sqlgram/SelectStmt.png) - -**FromDual:** - -![FromDual](/media/sqlgram/FromDual.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtOpts:** - -![SelectStmtOpts](/media/sqlgram/SelectStmtOpts.png) - -**SelectStmtFieldList:** - -![SelectStmtFieldList](/media/sqlgram/SelectStmtFieldList.png) - -**TableRefsClause:** - -![TableRefsClause](/media/sqlgram/TableRefsClause.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtGroup:** - -![SelectStmtGroup](/media/sqlgram/SelectStmtGroup.png) - -**HavingClause:** - -![HavingClause](/media/sqlgram/HavingClause.png) - -**OrderByOptional:** - -![OrderByOptional](/media/sqlgram/OrderByOptional.png) - -**SelectStmtLimit:** - -![SelectStmtLimit](/media/sqlgram/SelectStmtLimit.png) - -**SelectLockOpt:** - -![SelectLockOpt](/media/sqlgram/SelectLockOpt.png) - -## 语法元素说明 - -|语法元素 | 说明 | -| --------------------- | -------------------------------------------------- | -|`ALL`、`DISTINCT`、`DISTINCTROW` | 查询结果集中可能会包含重复值。指定 DISTINCT/DISTINCTROW 则在查询结果中过滤掉重复的行；指定 ALL 则列出所有的行。默认为 ALL。| -|`HIGH_PRIORITY` | 该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句| -|`SQL_CALC_FOUND_ROWS` | TiDB 出于兼容性解析这个语法，但是不做任何处理| -|`SQL_CACHE`、`SQL_NO_CACHE` | 是否把请求结果缓存到 TiKV (RocksDB) 的 `BlockCache` 中。对于一次性的大数据量的查询，比如 `count(*)` 查询，为了避免冲掉 `BlockCache` 中用户的热点数据，建议填上 `SQL_NO_CACHE` | -|`STRAIGHT_JOIN`|`STRAIGHT_JOIN` 会强制优化器按照 `FROM` 子句中所使用的表的顺序做联合查询。当优化器选择的 Join 顺序并不优秀时，你可以使用这个语法来加速查询的执行| -|`select_expr` | 投影操作列表，一般包括列名、表达式，或者是用 '\*' 表示全部列| -|`FROM table_references` | 表示数据来源，数据来源可以是一个表（`select * from t;`）或者是多个表 (`select * from t1 join t2;`) 或者是0个表 (`select 1+1 from dual;`, 等价于 `select 1+1;`)| -|`WHERE where_condition` | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据| -|`GROUP BY` | GroupBy 子句用于对查询结果集进行分组| -|`HAVING where_condition` | Having 子句与 Where 子句作用类似，Having 子句可以让过滤 GroupBy 后的各种数据，Where 子句用于在聚合前过滤记录。| -|`ORDER BY` | OrderBy 子句用于指定结果排序顺序，可以按照列、表达式或者是 `select_expr` 列表中某个位置的字段进行排序。| -|`LIMIT` | Limit 子句用于限制结果条数。Limit 接受一个或两个数字参数，如果只有一个参数，那么表示返回数据的最大行数；如果是两个参数，那么第一个参数表示返回数据的第一行的偏移量（第一行数据的偏移量是 0），第二个参数指定返回数据的最大条目数。| -|`FOR UPDATE` | 对查询结果集所有行上锁（对于在查询条件内，但是不在结果集的行，将不会加锁，如事务启动后由其他事务写入的行），以监测其他事务对这些的并发修改。使用[乐观事务模型](/dev/reference/transactions/transaction-optimistic.md)时，语句执行期间不会检测锁，因此，不会像 PostgreSQL 之类的数据库一样，在当前事务结束前阻止其他事务执行 `UPDATE`、`DELETE` 和 `SELECT FOR UPDATE`。在事务的提交阶段 `SELECT FOR UPDATE` 读到的行，也会进行两阶段提交，因此，它们也可以参与事务冲突检测。如发生写入冲突，那么包含 `SELECT FOR UPDATE` 语句的事务会提交失败。如果没有冲突，事务将成功提交，当提交结束时，这些被加锁的行，会产生一个新版本，可以让其他尚未提交的事务，在将来提交时发现写入冲突。若使用悲观事务，则行为与其他数据库基本相同，不一致之处参考[和 MySQL InnoDB 的差异](/dev/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)。 | -|`LOCK IN SHARE MODE` | TiDB 出于兼容性解析这个语法，但是不做任何处理| - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SELECT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/dev/reference/sql/statements/insert.md) -* [DELETE](/dev/reference/sql/statements/delete.md) -* [UPDATE](/dev/reference/sql/statements/update.md) -* [REPLACE](/dev/reference/sql/statements/replace.md) diff --git a/dev/reference/sql/statements/set-names.md b/dev/reference/sql/statements/set-names.md deleted file mode 100644 index 1930a7d80b96..000000000000 --- a/dev/reference/sql/statements/set-names.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: SET [NAMES|CHARACTER SET] -summary: TiDB 数据库中 SET [NAMES|CHARACTER SET] 的使用概况。 -category: reference ---- - -# SET [NAMES|CHARACTER SET] - -`SET NAMES`，`SET CHARACTER SET` 和 `SET CHARSET` 语句用于修改当前连接的变量 `character_set_client`，`character_set_results` 和 `character_set_connection`。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET NAMES utf8; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8 | -| character_set_system | utf8 | -| character_set_results | utf8 | -| character_set_client | utf8 | -| character_set_server | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET CHARACTER SET utf8mb4; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [NAMES|CHARACTER SET]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/dev/reference/sql/statements/show-variables.md) -* [SET ](/dev/reference/sql/statements/set-variable.md) -* [Character Set Support](/dev/reference/sql/character-set.md) diff --git a/dev/reference/sql/statements/set-password.md b/dev/reference/sql/statements/set-password.md deleted file mode 100644 index 24418564481d..000000000000 --- a/dev/reference/sql/statements/set-password.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: SET PASSWORD -summary: TiDB 数据库中 SET PASSWORD 的使用概况。 -category: reference ---- - -# SET PASSWORD - -`SET PASSWORD` 语句用于更改 TiDB 系统数据库中的用户密码。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SET PASSWORD='test'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'test'; -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET PASSWORD FOR newuser = 'test'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET PASSWORD FOR newuser = PASSWORD('test'); -``` - -上述语法是早期 MySQL 版本的过时语法。 - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET PASSWORD` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE USER](/dev/reference/sql/statements/create-user.md) -* [Privilege Management](/dev/reference/security/privilege-system.md) diff --git a/dev/reference/sql/statements/set-transaction.md b/dev/reference/sql/statements/set-transaction.md deleted file mode 100644 index 96df37a7f5f4..000000000000 --- a/dev/reference/sql/statements/set-transaction.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: SET TRANSACTION -summary: TiDB 数据库中 SET TRANSACTION 的使用概况。 -category: reference ---- - -# SET TRANSACTION - -`SET TRANSACTION` 语句用于在 `GLOBAL` 或 `SESSION` 的基础上更改当前的隔离级别，是 `SET transaction_isolation ='new-value'` 的替代语句，提供 MySQL 和 SQL 标准的兼容性。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -**TransactionChar:** - -![TransactionChar](/media/sqlgram/TransactionChar.png) - -**IsolationLevel:** - -![IsolationLevel](/media/sqlgram/IsolationLevel.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+----------------+ -| Variable_name | Value | -+-----------------------+----------------+ -| transaction_isolation | READ-COMMITTED | -+-----------------------+----------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION transaction_isolation = 'REPEATABLE-READ'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 支持仅在语法中将事务设置为只读的功能。 -* 不支持隔离级别 `READ-UNCOMMITTED` 和 `SERIALIZABLE`。 -* 隔离级别 `REPEATABLE-READ` 在技术上属于快照隔离（Snapshot Isolation）。在 TiDB 中称为 `REPEATABLE-READ` 是为了和 MySQL 保持一致。 - -## 另请参阅 - -* [SET \[GLOBAL|SESSION\] ](/dev/reference/sql/statements/set-variable.md) -* [Isolation Levels](/dev/reference/transactions/transaction-isolation.md) diff --git a/dev/reference/sql/statements/set-variable.md b/dev/reference/sql/statements/set-variable.md deleted file mode 100644 index 3d01198a8ae8..000000000000 --- a/dev/reference/sql/statements/set-variable.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: SET [GLOBAL|SESSION] -summary: TiDB 数据库中 SET [GLOBAL|SESSION] 的使用概况。 -category: reference ---- - -# SET [GLOBAL|SESSION] - -`SET [GLOBAL|SESSION]` 语句用于在 `SESSION` 或 `GLOBAL` 的范围内，对某个 TiDB 的内置变量进行更改。需注意，对 `GLOBAL` 变量的更改不适用于已有连接或本地连接，这与 MySQL 类似。只有新会话才会反映值的变化。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [GLOBAL|SESSION]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/dev/reference/sql/statements/show-variables.md) diff --git a/dev/reference/sql/statements/show-character-set.md b/dev/reference/sql/statements/show-character-set.md deleted file mode 100644 index d61beff9e1d7..000000000000 --- a/dev/reference/sql/statements/show-character-set.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: SHOW CHARACTER SET -summary: TiDB 数据库中 SHOW CHARACTER SET 的使用概况。 -category: reference ---- - -# SHOW CHARACTER SET - -`SHOW CHARACTER SET` 语句提供 TiDB 中可用字符集的静态列表。此列表不反映当前连接或用户的任何属性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**CharsetKw:** - -![CharsetKw](/media/sqlgram/CharsetKw.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW CHARACTER SET; -``` - -``` -+---------+---------------+-------------------+--------+ -| Charset | Description | Default collation | Maxlen | -+---------+---------------+-------------------+--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------+---------------+-------------------+--------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CHARACTER SET` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW COLLATION](/dev/reference/sql/statements/show-collation.md) diff --git a/dev/reference/sql/statements/show-collation.md b/dev/reference/sql/statements/show-collation.md deleted file mode 100644 index 4c7804797019..000000000000 --- a/dev/reference/sql/statements/show-collation.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: SHOW COLLATION -summary: TiDB 数据库中 SHOW COLLATION 的使用概况。 -category: reference ---- - -# SHOW COLLATION - -`SHOW COLLATION` 语句用于提供一个静态的排序规则列表，确保与 MySQL 客户端库的兼容性。 - -> **注意:** TiDB 目前仅支持二进制排序规则。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW COLLATION; -``` - -``` -+--------------------------+----------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+--------------------------+----------+------+---------+----------+---------+ -| big5_chinese_ci | big5 | 1 | Yes | Yes | 1 | -| latin2_czech_cs | latin2 | 2 | | Yes | 1 | -| dec8_swedish_ci | dec8 | 3 | Yes | Yes | 1 | -| cp850_general_ci | cp850 | 4 | Yes | Yes | 1 | -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| hp8_english_ci | hp8 | 6 | Yes | Yes | 1 | -| koi8r_general_ci | koi8r | 7 | Yes | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin2_general_ci | latin2 | 9 | Yes | Yes | 1 | -| swe7_swedish_ci | swe7 | 10 | Yes | Yes | 1 | -| ascii_general_ci | ascii | 11 | Yes | Yes | 1 | -| ujis_japanese_ci | ujis | 12 | Yes | Yes | 1 | -| sjis_japanese_ci | sjis | 13 | Yes | Yes | 1 | -| cp1251_bulgarian_ci | cp1251 | 14 | | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| hebrew_general_ci | hebrew | 16 | Yes | Yes | 1 | -| tis620_thai_ci | tis620 | 18 | Yes | Yes | 1 | -| euckr_korean_ci | euckr | 19 | Yes | Yes | 1 | -| latin7_estonian_cs | latin7 | 20 | | Yes | 1 | -| latin2_hungarian_ci | latin2 | 21 | | Yes | 1 | -| koi8u_general_ci | koi8u | 22 | Yes | Yes | 1 | -| cp1251_ukrainian_ci | cp1251 | 23 | | Yes | 1 | -| gb2312_chinese_ci | gb2312 | 24 | Yes | Yes | 1 | -| greek_general_ci | greek | 25 | Yes | Yes | 1 | -| cp1250_general_ci | cp1250 | 26 | Yes | Yes | 1 | -| latin2_croatian_ci | latin2 | 27 | | Yes | 1 | -| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | -| cp1257_lithuanian_ci | cp1257 | 29 | | Yes | 1 | -| latin5_turkish_ci | latin5 | 30 | Yes | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| armscii8_general_ci | armscii8 | 32 | Yes | Yes | 1 | -| utf8_general_ci | utf8 | 33 | Yes | Yes | 1 | -| cp1250_czech_cs | cp1250 | 34 | | Yes | 1 | -| ucs2_general_ci | ucs2 | 35 | Yes | Yes | 1 | -| cp866_general_ci | cp866 | 36 | Yes | Yes | 1 | -| keybcs2_general_ci | keybcs2 | 37 | Yes | Yes | 1 | -| macce_general_ci | macce | 38 | Yes | Yes | 1 | -| macroman_general_ci | macroman | 39 | Yes | Yes | 1 | -| cp852_general_ci | cp852 | 40 | Yes | Yes | 1 | -| latin7_general_ci | latin7 | 41 | Yes | Yes | 1 | -| latin7_general_cs | latin7 | 42 | | Yes | 1 | -| macce_bin | macce | 43 | | Yes | 1 | -| cp1250_croatian_ci | cp1250 | 44 | | Yes | 1 | -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| cp1251_bin | cp1251 | 50 | | Yes | 1 | -| cp1251_general_ci | cp1251 | 51 | Yes | Yes | 1 | -| cp1251_general_cs | cp1251 | 52 | | Yes | 1 | -| macroman_bin | macroman | 53 | | Yes | 1 | -| utf16_general_ci | utf16 | 54 | Yes | Yes | 1 | -| utf16_bin | utf16 | 55 | | Yes | 1 | -| utf16le_general_ci | utf16le | 56 | Yes | Yes | 1 | -| cp1256_general_ci | cp1256 | 57 | Yes | Yes | 1 | -| cp1257_bin | cp1257 | 58 | | Yes | 1 | -| cp1257_general_ci | cp1257 | 59 | Yes | Yes | 1 | -| utf32_general_ci | utf32 | 60 | Yes | Yes | 1 | -| utf32_bin | utf32 | 61 | | Yes | 1 | -| utf16le_bin | utf16le | 62 | | Yes | 1 | -| binary | binary | 63 | Yes | Yes | 1 | -| armscii8_bin | armscii8 | 64 | | Yes | 1 | -| ascii_bin | ascii | 65 | | Yes | 1 | -| cp1250_bin | cp1250 | 66 | | Yes | 1 | -| cp1256_bin | cp1256 | 67 | | Yes | 1 | -| cp866_bin | cp866 | 68 | | Yes | 1 | -| dec8_bin | dec8 | 69 | | Yes | 1 | -| greek_bin | greek | 70 | | Yes | 1 | -| hebrew_bin | hebrew | 71 | | Yes | 1 | -| hp8_bin | hp8 | 72 | | Yes | 1 | -| keybcs2_bin | keybcs2 | 73 | | Yes | 1 | -| koi8r_bin | koi8r | 74 | | Yes | 1 | -| koi8u_bin | koi8u | 75 | | Yes | 1 | -| latin2_bin | latin2 | 77 | | Yes | 1 | -| latin5_bin | latin5 | 78 | | Yes | 1 | -| latin7_bin | latin7 | 79 | | Yes | 1 | -| cp850_bin | cp850 | 80 | | Yes | 1 | -| cp852_bin | cp852 | 81 | | Yes | 1 | -| swe7_bin | swe7 | 82 | | Yes | 1 | -| utf8_bin | utf8 | 83 | | Yes | 1 | -| big5_bin | big5 | 84 | | Yes | 1 | -| euckr_bin | euckr | 85 | | Yes | 1 | -| gb2312_bin | gb2312 | 86 | | Yes | 1 | -| gbk_bin | gbk | 87 | | Yes | 1 | -| sjis_bin | sjis | 88 | | Yes | 1 | -| tis620_bin | tis620 | 89 | | Yes | 1 | -| ucs2_bin | ucs2 | 90 | | Yes | 1 | -| ujis_bin | ujis | 91 | | Yes | 1 | -| geostd8_general_ci | geostd8 | 92 | Yes | Yes | 1 | -| geostd8_bin | geostd8 | 93 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -| cp932_japanese_ci | cp932 | 95 | Yes | Yes | 1 | -| cp932_bin | cp932 | 96 | | Yes | 1 | -| eucjpms_japanese_ci | eucjpms | 97 | Yes | Yes | 1 | -| eucjpms_bin | eucjpms | 98 | | Yes | 1 | -| cp1250_polish_ci | cp1250 | 99 | | Yes | 1 | -| utf16_unicode_ci | utf16 | 101 | | Yes | 1 | -| utf16_icelandic_ci | utf16 | 102 | | Yes | 1 | -| utf16_latvian_ci | utf16 | 103 | | Yes | 1 | -| utf16_romanian_ci | utf16 | 104 | | Yes | 1 | -| utf16_slovenian_ci | utf16 | 105 | | Yes | 1 | -| utf16_polish_ci | utf16 | 106 | | Yes | 1 | -| utf16_estonian_ci | utf16 | 107 | | Yes | 1 | -| utf16_spanish_ci | utf16 | 108 | | Yes | 1 | -| utf16_swedish_ci | utf16 | 109 | | Yes | 1 | -| utf16_turkish_ci | utf16 | 110 | | Yes | 1 | -| utf16_czech_ci | utf16 | 111 | | Yes | 1 | -| utf16_danish_ci | utf16 | 112 | | Yes | 1 | -| utf16_lithuanian_ci | utf16 | 113 | | Yes | 1 | -| utf16_slovak_ci | utf16 | 114 | | Yes | 1 | -| utf16_spanish2_ci | utf16 | 115 | | Yes | 1 | -| utf16_roman_ci | utf16 | 116 | | Yes | 1 | -| utf16_persian_ci | utf16 | 117 | | Yes | 1 | -| utf16_esperanto_ci | utf16 | 118 | | Yes | 1 | -| utf16_hungarian_ci | utf16 | 119 | | Yes | 1 | -| utf16_sinhala_ci | utf16 | 120 | | Yes | 1 | -| utf16_german2_ci | utf16 | 121 | | Yes | 1 | -| utf16_croatian_ci | utf16 | 122 | | Yes | 1 | -| utf16_unicode_520_ci | utf16 | 123 | | Yes | 1 | -| utf16_vietnamese_ci | utf16 | 124 | | Yes | 1 | -| ucs2_unicode_ci | ucs2 | 128 | | Yes | 1 | -| ucs2_icelandic_ci | ucs2 | 129 | | Yes | 1 | -| ucs2_latvian_ci | ucs2 | 130 | | Yes | 1 | -| ucs2_romanian_ci | ucs2 | 131 | | Yes | 1 | -| ucs2_slovenian_ci | ucs2 | 132 | | Yes | 1 | -| ucs2_polish_ci | ucs2 | 133 | | Yes | 1 | -| ucs2_estonian_ci | ucs2 | 134 | | Yes | 1 | -| ucs2_spanish_ci | ucs2 | 135 | | Yes | 1 | -| ucs2_swedish_ci | ucs2 | 136 | | Yes | 1 | -| ucs2_turkish_ci | ucs2 | 137 | | Yes | 1 | -| ucs2_czech_ci | ucs2 | 138 | | Yes | 1 | -| ucs2_danish_ci | ucs2 | 139 | | Yes | 1 | -| ucs2_lithuanian_ci | ucs2 | 140 | | Yes | 1 | -| ucs2_slovak_ci | ucs2 | 141 | | Yes | 1 | -| ucs2_spanish2_ci | ucs2 | 142 | | Yes | 1 | -| ucs2_roman_ci | ucs2 | 143 | | Yes | 1 | -| ucs2_persian_ci | ucs2 | 144 | | Yes | 1 | -| ucs2_esperanto_ci | ucs2 | 145 | | Yes | 1 | -| ucs2_hungarian_ci | ucs2 | 146 | | Yes | 1 | -| ucs2_sinhala_ci | ucs2 | 147 | | Yes | 1 | -| ucs2_german2_ci | ucs2 | 148 | | Yes | 1 | -| ucs2_croatian_ci | ucs2 | 149 | | Yes | 1 | -| ucs2_unicode_520_ci | ucs2 | 150 | | Yes | 1 | -| ucs2_vietnamese_ci | ucs2 | 151 | | Yes | 1 | -| ucs2_general_mysql500_ci | ucs2 | 159 | | Yes | 1 | -| utf32_unicode_ci | utf32 | 160 | | Yes | 1 | -| utf32_icelandic_ci | utf32 | 161 | | Yes | 1 | -| utf32_latvian_ci | utf32 | 162 | | Yes | 1 | -| utf32_romanian_ci | utf32 | 163 | | Yes | 1 | -| utf32_slovenian_ci | utf32 | 164 | | Yes | 1 | -| utf32_polish_ci | utf32 | 165 | | Yes | 1 | -| utf32_estonian_ci | utf32 | 166 | | Yes | 1 | -| utf32_spanish_ci | utf32 | 167 | | Yes | 1 | -| utf32_swedish_ci | utf32 | 168 | | Yes | 1 | -| utf32_turkish_ci | utf32 | 169 | | Yes | 1 | -| utf32_czech_ci | utf32 | 170 | | Yes | 1 | -| utf32_danish_ci | utf32 | 171 | | Yes | 1 | -| utf32_lithuanian_ci | utf32 | 172 | | Yes | 1 | -| utf32_slovak_ci | utf32 | 173 | | Yes | 1 | -| utf32_spanish2_ci | utf32 | 174 | | Yes | 1 | -| utf32_roman_ci | utf32 | 175 | | Yes | 1 | -| utf32_persian_ci | utf32 | 176 | | Yes | 1 | -| utf32_esperanto_ci | utf32 | 177 | | Yes | 1 | -| utf32_hungarian_ci | utf32 | 178 | | Yes | 1 | -| utf32_sinhala_ci | utf32 | 179 | | Yes | 1 | -| utf32_german2_ci | utf32 | 180 | | Yes | 1 | -| utf32_croatian_ci | utf32 | 181 | | Yes | 1 | -| utf32_unicode_520_ci | utf32 | 182 | | Yes | 1 | -| utf32_vietnamese_ci | utf32 | 183 | | Yes | 1 | -| utf8_unicode_ci | utf8 | 192 | | Yes | 1 | -| utf8_icelandic_ci | utf8 | 193 | | Yes | 1 | -| utf8_latvian_ci | utf8 | 194 | | Yes | 1 | -| utf8_romanian_ci | utf8 | 195 | | Yes | 1 | -| utf8_slovenian_ci | utf8 | 196 | | Yes | 1 | -| utf8_polish_ci | utf8 | 197 | | Yes | 1 | -| utf8_estonian_ci | utf8 | 198 | | Yes | 1 | -| utf8_spanish_ci | utf8 | 199 | | Yes | 1 | -| utf8_swedish_ci | utf8 | 200 | | Yes | 1 | -| utf8_turkish_ci | utf8 | 201 | | Yes | 1 | -| utf8_czech_ci | utf8 | 202 | | Yes | 1 | -| utf8_danish_ci | utf8 | 203 | | Yes | 1 | -| utf8_lithuanian_ci | utf8 | 204 | | Yes | 1 | -| utf8_slovak_ci | utf8 | 205 | | Yes | 1 | -| utf8_spanish2_ci | utf8 | 206 | | Yes | 1 | -| utf8_roman_ci | utf8 | 207 | | Yes | 1 | -| utf8_persian_ci | utf8 | 208 | | Yes | 1 | -| utf8_esperanto_ci | utf8 | 209 | | Yes | 1 | -| utf8_hungarian_ci | utf8 | 210 | | Yes | 1 | -| utf8_sinhala_ci | utf8 | 211 | | Yes | 1 | -| utf8_german2_ci | utf8 | 212 | | Yes | 1 | -| utf8_croatian_ci | utf8 | 213 | | Yes | 1 | -| utf8_unicode_520_ci | utf8 | 214 | | Yes | 1 | -| utf8_vietnamese_ci | utf8 | 215 | | Yes | 1 | -| utf8_general_mysql500_ci | utf8 | 223 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+--------------------------+----------+------+---------+----------+---------+ -219 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -TiDB 不支持二进制以外的排序规则。`SHOW COLLATION` 语句仅用于确保与 MySQL 的兼容性。 - -## 另请参阅 - -* [SHOW CHARACTER SET](/dev/reference/sql/statements/show-character-set.md) diff --git a/dev/reference/sql/statements/show-columns-from.md b/dev/reference/sql/statements/show-columns-from.md deleted file mode 100644 index e9a82051c8ef..000000000000 --- a/dev/reference/sql/statements/show-columns-from.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: SHOW [FULL] COLUMNS FROM -summary: TiDB 数据库中 SHOW [FULL] COLUMNS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] COLUMNS FROM - -`SHOW [FULL] COLUMNS FROM` 语句用于以表格格式描述表或视图中的列。可选关键字 `FULL` 用于显示当前用户对该列的权限，以及表定义中的 `comment`。 - -`SHOW [FULL] FIELDS FROM`，`DESC `，`DESCRIBE
` 和 `EXPLAIN
` 语句都是 `SHOW [FULL] COLUMNS FROM` 的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -create view v1 as select 1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -show columns from v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -desc v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -describe v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -explain v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show fields from v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show full columns from v1; -``` - -``` -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| 1 | bigint(1) | NULL | YES | | NULL | | select,insert,update,references | | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show full columns from mysql.user; -``` - -``` -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Host | char(64) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| User | char(32) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| Password | char(41) | utf8mb4_bin | YES | | NULL | | select,insert,update,references | | -| Select_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Insert_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Update_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Delete_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Process_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Grant_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| References_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_db_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Super_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_tmp_table_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Lock_tables_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Execute_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Index_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_user_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Event_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Trigger_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Account_locked | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -29 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] COLUMNS FROM` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/show-create-table.md b/dev/reference/sql/statements/show-create-table.md deleted file mode 100644 index eef8ba5e97aa..000000000000 --- a/dev/reference/sql/statements/show-create-table.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: SHOW CREATE TABLE -summary: TiDB 数据库中 SHOW CREATE TABLE 的使用概况。 -category: reference ---- - -# SHOW CREATE TABLE - -`SHOW CREATE TABLE` 语句用于显示用 SQL 重新创建已有表的确切语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -+-------+------------------------------------------------------------------------------------------------------------+ -| Table | Create Table | -+-------+------------------------------------------------------------------------------------------------------------+ -| t1 | CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | -+-------+------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CREATE TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [SHOW TABLES](/dev/reference/sql/statements/show-tables.md) -* [SHOW COLUMNS FROM](/dev/reference/sql/statements/show-columns-from.md) diff --git a/dev/reference/sql/statements/show-create-user.md b/dev/reference/sql/statements/show-create-user.md deleted file mode 100644 index b0eaca64f847..000000000000 --- a/dev/reference/sql/statements/show-create-user.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: SHOW CREATE USER -summary: TiDB 数据库中 SHOW CREATE USER 的使用概况。 -category: reference ---- - -# SHOW CREATE USER - -`SHOW CREATE USER` 语句用于显示如何使用 `CREATE USER` 语法来重新创建用户。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'root'; -``` - -```+--------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for root@% | -+--------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'root'@'%' IDENTIFIED WITH 'mysql_native_password' AS '' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+--------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SHOW GRANTS FOR 'root'; -+-------------------------------------------+ -| Grants for root@% | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `SHOW CREATE USER` 的输出结果旨在匹配 MySQL，但 TiDB 尚不支持若干 `CREATE` 选项。尚未支持的选项在语句执行过程中会被解析但会被跳过执行。详情可参阅 [security compatibility]。 - -## 另请参阅 - -* [CREATE USER](/dev/reference/sql/statements/create-user.md) -* [SHOW GRANTS](/dev/reference/sql/statements/show-grants.md) -* [DROP USER](/dev/reference/sql/statements/drop-user.md) diff --git a/dev/reference/sql/statements/show-databases.md b/dev/reference/sql/statements/show-databases.md deleted file mode 100644 index d99e3da1d8b5..000000000000 --- a/dev/reference/sql/statements/show-databases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: SHOW DATABASES -summary: TiDB 数据库中 SHOW DATABASES 的使用概况。 -category: reference ---- - -# SHOW DATABASES - -`SHOW DATABASES` 语句用于显示当前用户有权访问的数据库列表。当前用户无权访问的数据库将从列表中隐藏。`information_schema` 数据库始终出现在列表的最前面。 - -`SHOW SCHEMAS` 是 `SHOW DATABASES` 语句的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE mynewdb; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mynewdb | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW DATABASES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW SCHEMAS](/dev/reference/sql/statements/show-schemas.md) -* [DROP DATABASE](/dev/reference/sql/statements/drop-database.md) -* [CREATE DATABASE](/dev/reference/sql/statements/create-database.md) diff --git a/dev/reference/sql/statements/show-errors.md b/dev/reference/sql/statements/show-errors.md deleted file mode 100644 index d2c5ff58b228..000000000000 --- a/dev/reference/sql/statements/show-errors.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: SHOW ERRORS -summary: TiDB 数据库中 SHOW ERRORS 的使用概况。 -category: reference ---- - -# SHOW ERRORS - -`SHOW ERRORS` 语句用于显示已执行语句中的错误。一旦先前的语句成功执行，就会清除错误缓冲区，这时 `SHOW ERRORS` 会返回一个空集。 - -当前的 `sql_mode` 很大程度决定了哪些语句会产生错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -select invalid; -``` - -``` -ERROR 1054 (42S22): Unknown column 'invalid' in 'field list' -``` - -{{< copyable "sql" >}} - -```sql -create invalid; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" -``` - -{{< copyable "sql" >}} - -```sql -SHOW ERRORS; -``` - -``` -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Level | Code | Message | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Error | 1054 | Unknown column 'invalid' in 'field list' | -| Error | 1064 | You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE invalid2; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 15 near "invalid2" -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1; -``` - -``` -+------+ -| 1 | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW ERRORS; -``` - -``` -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW ERRORS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW WARNINGS](/dev/reference/sql/statements/show-warnings.md) diff --git a/dev/reference/sql/statements/show-fields-from.md b/dev/reference/sql/statements/show-fields-from.md deleted file mode 100644 index 75f2ff268250..000000000000 --- a/dev/reference/sql/statements/show-fields-from.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW [FULL] FIELDS FROM -summary: TiDB 数据库中 SHOW [FULL] FIELDS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] FIELDS FROM - -`SHOW [FULL] FIELDS FROM` 是 [`SHOW [FULL] COLUMNS FROM`](/dev/reference/sql/statements/show-columns-from.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/dev/reference/sql/statements/show-grants.md b/dev/reference/sql/statements/show-grants.md deleted file mode 100644 index b6f4f51f95d3..000000000000 --- a/dev/reference/sql/statements/show-grants.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: SHOW GRANTS -summary: TiDB 数据库中 SHOW GRANTS 的使用概况。 -category: reference ---- - -# SHOW GRANTS - -`SHOW GRANTS` 语句用于显示与用户关联的权限列表。与在 MySQL 中一样，`USAGE` 权限表示登录 TiDB 的能力。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS; -``` - -``` -+-------------------------------------------+ -| Grants for User | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'u1' on host '%' -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER u1; -``` - -``` -Query OK, 1 row affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO u1; -``` - -``` -Query OK, 0 rows affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR u1; -``` - -``` -+------------------------------------+ -| Grants for u1@% | -+------------------------------------+ -| GRANT USAGE ON *.* TO 'u1'@'%' | -| GRANT Select ON test.* TO 'u1'@'%' | -+------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW GRANTS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE USER](/dev/reference/sql/statements/show-create-user.md) -* [GRANT](/dev/reference/sql/statements/grant-privileges.md) diff --git a/dev/reference/sql/statements/show-index.md b/dev/reference/sql/statements/show-index.md deleted file mode 100644 index a22b9bf576be..000000000000 --- a/dev/reference/sql/statements/show-index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW INDEX [FROM|IN] -summary: TiDB 数据库中 SHOW INDEX [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEX [FROM|IN] - -`SHOW INDEX [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/dev/reference/sql/statements/show-indexes.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/dev/reference/sql/statements/show-indexes.md b/dev/reference/sql/statements/show-indexes.md deleted file mode 100644 index ab0a6cd356a6..000000000000 --- a/dev/reference/sql/statements/show-indexes.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: SHOW INDEXES [FROM|IN] -summary: TiDB 数据库中 SHOW INDEXES [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEXES [FROM|IN] - -`SHOW INDEXES [FROM|IN]` 语句用于列出指定表上的索引。`SHOW INDEX [FROM | IN]` 和 `SHOW KEYS [FROM | IN]` 是该语句的别名。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowIndexKwd:** - -![ShowIndexKwd](/media/sqlgram/ShowIndexKwd.png) - -**FromOrIn:** - -![FromOrIn](/media/sqlgram/FromOrIn.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT, INDEX(col1)); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEXES FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEX FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW KEYS FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW INDEXES [FROM|IN]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) -* [DROP INDEX](/dev/reference/sql/statements/drop-index.md) -* [CREATE INDEX](/dev/reference/sql/statements/create-index.md) diff --git a/dev/reference/sql/statements/show-keys.md b/dev/reference/sql/statements/show-keys.md deleted file mode 100644 index 531445ca1807..000000000000 --- a/dev/reference/sql/statements/show-keys.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW KEYS [FROM|IN] -summary: TiDB 数据库中 SHOW KEYS [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW KEYS [FROM|IN] - -`SHOW KEYS [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/dev/reference/sql/statements/show-indexes.md) 语句的别名。包含该语句提供了 MySQL 兼容性。。 diff --git a/dev/reference/sql/statements/show-privileges.md b/dev/reference/sql/statements/show-privileges.md deleted file mode 100644 index 89101930569a..000000000000 --- a/dev/reference/sql/statements/show-privileges.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: SHOW PRIVILEGES -summary: TiDB 数据库中 SHOW PRIVILEGES 的使用概况。 -category: reference ---- - -# SHOW PRIVILEGES - -`SHOW PRIVILEGES` 语句用于显示 TiDB 中可分配权限的列表。此列表为静态列表，不反映当前用户的权限。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show privileges; -``` - -``` -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Privilege | Context | Comment | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Alter | Tables | To alter the table | -| Alter | Tables | To alter the table | -| Alter routine | Functions,Procedures | To alter or drop stored functions/procedures | -| Create | Databases,Tables,Indexes | To create new databases and tables | -| Create routine | Databases | To use CREATE FUNCTION/PROCEDURE | -| Create temporary tables | Databases | To use CREATE TEMPORARY TABLE | -| Create view | Tables | To create new views | -| Create user | Server Admin | To create new users | -| Delete | Tables | To delete existing rows | -| Drop | Databases,Tables | To drop databases, tables, and views | -| Event | Server Admin | To create, alter, drop and execute events | -| Execute | Functions,Procedures | To execute stored routines | -| File | File access on server | To read and write files on the server | -| Grant option | Databases,Tables,Functions,Procedures | To give to other users those privileges you possess | -| Index | Tables | To create or drop indexes | -| Insert | Tables | To insert data into tables | -| Lock tables | Databases | To use LOCK TABLES (together with SELECT privilege) | -| Process | Server Admin | To view the plain text of currently executing queries | -| Proxy | Server Admin | To make proxy user possible | -| References | Databases,Tables | To have references on tables | -| Reload | Server Admin | To reload or refresh tables, logs and privileges | -| Replication client | Server Admin | To ask where the slave or master servers are | -| Replication slave | Server Admin | To read binary log events from the master | -| Select | Tables | To retrieve rows from table | -| Show databases | Server Admin | To see all databases with SHOW DATABASES | -| Show view | Tables | To see views with SHOW CREATE VIEW | -| Shutdown | Server Admin | To shut down the server | -| Super | Server Admin | To use KILL thread, SET GLOBAL, CHANGE MASTER, etc. | -| Trigger | Tables | To use triggers | -| Create tablespace | Server Admin | To create/alter/drop tablespaces | -| Update | Tables | To update existing rows | -| Usage | Server Admin | No privileges - allow connect only | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -32 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW GRANTS](/dev/reference/sql/statements/show-grants.md) -* [GRANT ](/dev/reference/sql/statements/grant-privileges.md) diff --git a/dev/reference/sql/statements/show-processlist.md b/dev/reference/sql/statements/show-processlist.md deleted file mode 100644 index 5b36a345e0bd..000000000000 --- a/dev/reference/sql/statements/show-processlist.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: SHOW [FULL] PROCESSLIST -summary: TiDB 数据库中 SHOW [FULL] PROCESSLIST 的使用概况。 -category: reference ---- - -# SHOW [FULL] PROCESSLIST - -`SHOW [FULL] PROCESSLIST` 语句列出连接到相同 TiDB 服务器的当前会话。`Info` 列包含查询文本，除非指定可选关键字 `FULL`，否则文本会被截断。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW PROCESSLIST; -``` - -``` -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 中的 `State` 列是非描述性的。在 TiDB 中，将状态表示为单个值更复杂，因为查询是并行执行的，而且每个 GO 线程在任一时刻都有不同的状态。 - -## 另请参阅 - -* [KILL \[TIDB\]](/dev/reference/sql/statements/kill.md) diff --git a/dev/reference/sql/statements/show-schemas.md b/dev/reference/sql/statements/show-schemas.md deleted file mode 100644 index b07d9096c189..000000000000 --- a/dev/reference/sql/statements/show-schemas.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW SCHEMAS -summary: TiDB 数据库中 SHOW SCHEMAS 的使用概况。 -category: reference ---- - -# SHOW SCHEMAS - -`SHOW SCHEMAS` 语句是 [`SHOW DATABASES`](/dev/reference/sql/statements/show-databases.md) 的别名。包含该语句提供了 MySQL 兼容性。。 diff --git a/dev/reference/sql/statements/show-status.md b/dev/reference/sql/statements/show-status.md deleted file mode 100644 index ae31d81d9ccc..000000000000 --- a/dev/reference/sql/statements/show-status.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] STATUS -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] STATUS 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] STATUS - -`SHOW [GLOBAL|SESSION] STATUS` 语句用于提供 MySQL 兼容性，对 TiDB 没有作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -show global status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [FLUSH STATUS](/dev/reference/sql/statements/flush-status.md) diff --git a/dev/reference/sql/statements/show-table-regions.md b/dev/reference/sql/statements/show-table-regions.md deleted file mode 100644 index a2bba5757798..000000000000 --- a/dev/reference/sql/statements/show-table-regions.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: SHOW TABLE REGIONS -summary: 了解如何使用 TiDB 数据库中的 SHOW TABLE REGIONS。 -category: reference ---- - -# SHOW TABLE REGIONS - -`SHOW TABLE REGIONS` 语句用于显示 TiDB 中某个表的 Region 信息。 - -## 语法图 - -```sql -SHOW TABLE [table_name] REGIONS [WhereClauseOptional]; - -SHOW TABLE [table_name] INDEX [index_name] REGIONS [WhereClauseOptional]; -``` - -`SHOW TABLE REGIONS` 会返回如下列： - -* `REGION_ID`：Region 的 ID。 -* `START_KEY`：Region 的 Start key。 -* `END_KEY`：Region 的 End key。 -* `LEADER_ID`：Region 的 Leader ID。 -* `LEADER_STORE_ID`：Region leader 所在的 store (TiKV) ID。 -* `PEERS`：Region 所有副本的 ID。 -* `SCATTERING`：Region 是否正在调度中。1 表示正在调度。 -* `WRITTEN_BYTES`：估算的 Region 在 1 个心跳周期内的写入数据量大小，单位是 byte。 -* `READ_BYTES`：估算的 Region 在 1 个心跳周期内的读数据量大小，单位是 byte。 -* `APPROXIMATE_SIZE(MB)`：估算的 Region 的数据量大小，单位是 MB。 -* `APPROXIMATE_KEYS`：估算的 Region 内 Key 的个数。 - -> **注意：** -> -> `WRITTEN_BYTES`，`READ_BYTES`，`APPROXIMATE_SIZE(MB)`，`APPROXIMATE_KEYS` 的值是 PD 根据 Region 的心跳汇报信息统计，估算出来的数据，所以不是精确的数据。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -create table t (id int key,name varchar(50), index (name)); -``` - -``` -Query OK, 0 rows affected -``` - -默认新建表后会单独 split 出一个 Region 来存放该表的数据，开始时行数据和索引数据都会写到这个 Region。 - -{{< copyable "sql" >}} - -```sql -show table t regions; -``` - -``` -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -| 3 | t_43_ | | 73 | 9 | 5, 73, 93 | 0 | 35 | 0 | 1 | 0 | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -1 row in set -``` - -解释： - -- 上面 START_KEY 列的值 t_43_ 中，t 是表数据的前缀，43 是表 t 的 table ID。 -- END_KEY 列的值为空（""）表示无穷大。 - -用 `SPLIT TABLE REGION` 语法切分行数据的 Region，下面语法把表 t 的行数据切分成 5 个 Region。 - -{{< copyable "sql" >}} - -```sql -split table t between (0) and (100000) regions 5; -``` - -``` -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 5 | 1.0 | -+--------------------+----------------------+ -1 row in set -``` - -解释： - -- TOTAL_SPLIT_REGION 表示新切的 region 数量，这是新切了 5 个 region. -- SCATTER_FINISH_RATIO 表示新切的 region 的打散成功率，1.0 表示都已经打散了。 - -表 t 现在一共有 6 个 Region，其中 102、106、110、114、3 用来存行数据，Region 98 用来存索引数据。 - -{{< copyable "sql" >}} - -```sql -show table t regions; -``` - -``` -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | -| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 107, 108, 120 | 0 | 23 | 0 | 1 | 0 | -| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | -| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | -| 3 | t_43_r_80000 | | 93 | 8 | 5, 73, 93 | 0 | 0 | 0 | 1 | 0 | -| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -6 rows in set -``` - -解释： - -- Region 102 的 START_KEY 和 END_KEY 中，t_43 是表数据前缀和 table ID，_r 是表 t record 数据的前缀，索引数据的前缀是 _i，所以 Region 102 的 START_KEY 和 END_KEY 表示用来存储 [-inf, 20000) 之前的 record 数据。其他 Region (103, 109, 113, 2) 的存储范围依次类推。 -- Region 98 用来存储索引数据存储。表 t 索引数据的起始 key 是 t_43_i，处于 Region 98 的存储范围内。 - -查看表 t 在 store 1 上的 region，用 where 条件过滤。 - -{{< copyable "sql" >}} - -```sql -show table t regions where leader_store_id =1; -``` - -``` -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -``` - -用 `SPLIT TABLE REGION` 语法切分索引数据的 Region，下面语法把表 t 的索引 name 数据在 [a,z] 范围内切分成 2 个 Region。 - -{{< copyable "sql" >}} - -```sql -split table t index name between ("a") and ("z") regions 2; -``` - -``` -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 2 | 1.0 | -+--------------------+----------------------+ -1 row in set -``` - -现在表 t 一共有 7 个 Region，其中 5 个 Region (102, 106, 110, 114, 3) 用来存表 t 的 record 数据，另外 2 个 Region (135, 98) 用来存 name 索引的数据。 - -{{< copyable "sql" >}} - -```sql -show table t regions; -``` - -``` -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | -| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 108, 120, 126 | 0 | 0 | 0 | 1 | 0 | -| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | -| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | -| 3 | t_43_r_80000 | | 93 | 8 | 73, 93, 128 | 0 | 0 | 0 | 1 | 0 | -| 135 | t_43_i_1_ | t_43_i_1_016d80000000000000 | 139 | 2 | 138, 139, 140 | 0 | 35 | 0 | 1 | 0 | -| 98 | t_43_i_1_016d80000000000000 | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -7 rows in set -``` - -## 另请参阅 - -* [SPLIT REGION](/dev/reference/sql/statements/split-region.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) diff --git a/dev/reference/sql/statements/show-table-status.md b/dev/reference/sql/statements/show-table-status.md deleted file mode 100644 index 167bbce47ece..000000000000 --- a/dev/reference/sql/statements/show-table-status.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: SHOW TABLE STATUS -summary: TiDB 数据库中 SHOW TABLE STATUS 的使用概况。 -category: reference ---- - -# SHOW TABLE STATUS - -`SHOW TABLE STATUS` 语句用于显示 TiDB 中表的各种统计信息。如果显示统计信息过期，建议运行 [`ANALYZE TABLE`](/dev/reference/sql/statements/analyze-table.md)。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLE STATUS LIKE 't1'; -``` - -``` -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 0 - Avg_row_length: 0 - Data_length: 0 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -analyze table t1; -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLE STATUS LIKE 't1'; -``` - -``` -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 5 - Avg_row_length: 16 - Data_length: 80 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW TABLE STATUS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW TABLES](/dev/reference/sql/statements/show-tables.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/show-tables.md b/dev/reference/sql/statements/show-tables.md deleted file mode 100644 index 1a1a6a4c169d..000000000000 --- a/dev/reference/sql/statements/show-tables.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: SHOW [FULL] TABLES -summary: TiDB 数据库中 SHOW [FULL] TABLES 的使用概况。 -category: reference ---- - -# SHOW [FULL] TABLES - -`SHOW [FULL] TABLES` 语句用于显示当前所选数据库中表和视图的列表。可选关键字 `FULL` 说明表的类型是 `BASE TABLE` 还是 `VIEW`。 - -若要在不同的数据库中显示表，可使用 `SHOW TABLES IN DatabaseName` 语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.12 sec) - -mysql> CREATE VIEW v1 AS SELECT 1; -Query OK, 0 rows affected (0.10 sec) - -mysql> SHOW TABLES; -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -| v1 | -+----------------+ -2 rows in set (0.00 sec) - -mysql> SHOW FULL TABLES; -+----------------+------------+ -| Tables_in_test | Table_type | -+----------------+------------+ -| t1 | BASE TABLE | -| v1 | VIEW | -+----------------+------------+ -2 rows in set (0.00 sec) - -mysql> SHOW TABLES IN mysql; -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] TABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/show-variables.md b/dev/reference/sql/statements/show-variables.md deleted file mode 100644 index 2320601b808e..000000000000 --- a/dev/reference/sql/statements/show-variables.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] VARIABLES -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] VARIABLES 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] VARIABLES - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句用于显示 `GLOBAL` 或 `SESSION` 范围的变量列表。如果未指定范围，则应用默认范围 `SESSION`。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'tidb%'; -``` - -``` -+-------------------------------------+---------------+ -| Variable_name | Value | -+-------------------------------------+---------------+ -| tidb_ddl_error_count_limit | 512 | -| tidb_dml_batch_size | 20000 | -| tidb_force_priority | NO_PRIORITY | -| tidb_batch_insert | 0 | -| tidb_skip_utf8_check | 0 | -| tidb_backoff_lock_fast | 100 | -| tidb_opt_join_reorder_threshold | 0 | -| tidb_auto_analyze_end_time | 23:59 +0000 | -| tidb_slow_log_threshold | 300 | -| tidb_opt_correlation_exp_factor | 1 | -| tidb_mem_quota_sort | 34359738368 | -| tidb_current_ts | 0 | -| tidb_ddl_reorg_batch_size | 256 | -| tidb_checksum_table_concurrency | 4 | -| tidb_check_mb4_value_in_utf8 | 1 | -| tidb_distsql_scan_concurrency | 15 | -| tidb_optimizer_selectivity_level | 0 | -| tidb_opt_agg_push_down | 0 | -| tidb_max_chunk_size | 1024 | -| tidb_low_resolution_tso | 0 | -| tidb_index_lookup_size | 20000 | -| tidb_skip_isolation_level_check | 0 | -| tidb_opt_write_row_id | 0 | -| tidb_wait_split_region_finish | 1 | -| tidb_index_lookup_join_concurrency | 4 | -| tidb_mem_quota_indexlookupjoin | 34359738368 | -| tidb_replica_read | leader | -| tidb_ddl_reorg_priority | PRIORITY_LOW | -| tidb_batch_commit | 0 | -| tidb_mem_quota_mergejoin | 34359738368 | -| tidb_mem_quota_query | 34359738368 | -| tidb_batch_delete | 0 | -| tidb_build_stats_concurrency | 4 | -| tidb_enable_index_merge | 0 | -| tidb_enable_radix_join | 0 | -| tidb_retry_limit | 10 | -| tidb_query_log_max_len | 2048 | -| tidb_config | | -| tidb_ddl_reorg_worker_cnt | 4 | -| tidb_opt_insubq_to_join_and_agg | 1 | -| tidb_enable_vectorized_expression | 1 | -| tidb_mem_quota_hashjoin | 34359738368 | -| tidb_disable_txn_auto_retry | 1 | -| tidb_enable_window_function | 1 | -| tidb_init_chunk_size | 32 | -| tidb_constraint_check_in_place | 0 | -| tidb_wait_split_region_timeout | 300 | -| tidb_hash_join_concurrency | 5 | -| tidb_enable_fast_analyze | 0 | -| tidb_enable_cascades_planner | 0 | -| tidb_txn_mode | | -| tidb_index_serial_scan_concurrency | 1 | -| tidb_projection_concurrency | 4 | -| tidb_enable_noop_functions | 0 | -| tidb_index_lookup_concurrency | 4 | -| tidb_hashagg_partial_concurrency | 4 | -| tidb_general_log | 0 | -| tidb_enable_streaming | 0 | -| tidb_backoff_weight | 2 | -| tidb_mem_quota_topn | 34359738368 | -| tidb_scatter_region | 0 | -| tidb_index_join_batch_size | 25000 | -| tidb_snapshot | | -| tidb_expensive_query_time_threshold | 60 | -| tidb_slow_query_file | tidb-slow.log | -| tidb_auto_analyze_ratio | 0.5 | -| tidb_enable_table_partition | auto | -| tidb_auto_analyze_start_time | 00:00 +0000 | -| tidb_mem_quota_nestedloopapply | 34359738368 | -| tidb_mem_quota_indexlookupreader | 34359738368 | -| tidb_hashagg_final_concurrency | 4 | -| tidb_opt_correlation_threshold | 0.9 | -+-------------------------------------+---------------+ -68 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'time_zone%'; -``` - -``` -+---------------+--------+ -| Variable_name | Value | -+---------------+--------+ -| time_zone | SYSTEM | -+---------------+--------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SET](/dev/reference/sql/statements/set-variable.md) diff --git a/dev/reference/sql/statements/show-warnings.md b/dev/reference/sql/statements/show-warnings.md deleted file mode 100644 index 3db6916fffca..000000000000 --- a/dev/reference/sql/statements/show-warnings.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: SHOW WARNINGS -summary: TiDB 数据库中 SHOW WARNINGS 的使用概况。 -category: reference ---- - -# SHOW WARNINGS - -`SHOW WARNINGS` 语句用于显示当前客户端连接中已执行语句的报错列表。与在 MySQL 中一样，`sql_mode` 极大地影响哪些语句会导致错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT UNSIGNED); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (0); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1/a FROM t1; -``` - -``` -+------+ -| 1/a | -+------+ -| NULL | -+------+ -1 row in set, 1 warning (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW WARNINGS; -``` - -``` -+---------+------+---------------+ -| Level | Code | Message | -+---------+------+---------------+ -| Warning | 1365 | Division by 0 | -+---------+------+---------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (-1); -``` - -``` -ERROR 1264 (22003): Out of range value for column 'a' at row 1 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 0 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET sql_mode=''; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (-1); -``` - -``` -Query OK, 1 row affected, 1 warning (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW WARNINGS; -``` - -``` -+---------+------+---------------------------+ -| Level | Code | Message | -+---------+------+---------------------------+ -| Warning | 1690 | constant -1 overflows int | -+---------+------+---------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 0 | -| 0 | -+------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW WARNINGS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [SHOW ERRORS](/dev/reference/sql/statements/show-errors.md) diff --git a/dev/reference/sql/statements/split-region.md b/dev/reference/sql/statements/split-region.md deleted file mode 100644 index cc83c86dc6b9..000000000000 --- a/dev/reference/sql/statements/split-region.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Split Region 使用文档 -category: reference ---- - -# Split Region 使用文档 - -在 TiDB 中新建一个表后，默认会单独切分出 1 个 Region 来存储这个表的数据，这个默认行为由配置文件中的 `split-table` 控制。当这个 Region 中的数据超过默认 Region 大小限制后，这个 Region 会开始分裂成 2 个 Region。 - -上述情况中，如果在新建的表上发生大批量写入，则会造成热点，因为开始只有一个 Region，所有的写请求都发生在该 Region 所在的那台 TiKV 上。 - -为解决上述场景中的热点问题，TiDB 引入了预切分 Region 的功能，即可以根据指定的参数，预先为某个表切分出多个 Region，并打散到各个 TiKV 上去。 - -## Split Region 的使用 - -Split Region 有 2 种不同的语法，具体如下： - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -`BETWEEN lower_value AND upper_value REGIONS region_num` 语法是通过指定上、下边界和 Region 数量，然后在上、下边界之间均匀切分出 `region_num` 个 Region。 - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ... -``` - -`BY value_list…` 语法将手动指定一系列的点，然后根据这些指定的点切分 Region，适用于数据不均匀分布的场景。 - -### Split Table Region - -表中行数据的 key 由 `table_id` 和 `row_id` 编码组成，格式如下： - -```go -t[table_id]_r[row_id] -``` - -例如，当 `table_id` 是 22，`row_id` 是 11 时： - -```go -t22_r11 -``` - -同一表中行数据的 `table_id` 是一样的，但 `row_id` 肯定不一样，所以可以根据 `row_id` 来切分 Region。 - -#### 均匀切分 - -由于 `row_id` 是整数，所以根据指定的 `lower_value`、`upper_value` 以及 `region_num`，可以推算出需要切分的 key。TiDB 先计算 step（`step = (upper_value - lower_value)/num`），然后在 `lower_value` 和 `upper_value` 之间每隔 step 区间切一次，最终切出 `num` 个 Region。 - -例如，对于表 t，如果想要从 `minInt64`~`maxInt64` 之间均匀切割出 16 个 Region，可以用以下语句： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 从 minInt64 到 maxInt64 之间均匀切割出 16 个 Region。如果已知主键的范围没有这么大，比如只会在 0~1000000000 之间，那可以用 0 和 1000000000 分别代替上面的 minInt64 和 maxInt64 来切分 Region。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (0) AND (1000000000) REGIONS 16; -``` - -#### 不均匀切分 - -如果已知数据不是均匀分布的，比如想要 -inf ~ 10000 切一个 Region，10000 ~ 90000 切一个 Region，90000 ~ +inf 切一个 Region，可以通过手动指定点来切分 Region，示例如下： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BY (10000), (90000); -``` - -### Split Index Region - -表中索引数据的 key 由 `table_id`、`index_id` 以及索引列的值编码组成，格式如下： - -```go -t[table_id]_i[index_id][index_value] -``` - -例如，当 `table_id` 是 22，`index_id` 是 5，`index_value` 是 abc 时： - -```go -t22_i5abc -``` - -同一表中同一索引数据的 `table_id` 和 `index_id` 是一样的，所以要根据 `index_value` 切分索引 Region。 - -#### 均匀切分 - -索引均匀切分与行数据均匀切分的原理一样，只是计算 step 的值较为复杂，因为 `index_value` 可能不是整数。 - -`upper` 和 `lower` 的值会先编码成 byte 数组，去掉 `lower` 和 `upper` byte 数组的最长公共前缀后，从 `lower` 和 `upper` 各取前 8 字节转成 uint64，再计算 `step = (upper - lower)/num`。计算出 step 后再将 step 编码成 byte 数组，添加到之前 `upper`和 `lower`的最长公共前缀后面组成一个 key 后去做切分。示例如下： - -如果索引 idx 的列也是整数类型，可以用如下 SQL 语句切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 中 idx 索引数据 Region 从 `minInt64` 到 `maxInt64` 之间均匀切割出 16 个 Region。 - -如果索引 idx1 的列是 varchar 类型，希望根据前缀字母来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx1 BETWEEN ("a") AND ("z") REGIONS 26; -``` - -该语句会把表 t 中 idx1 索引数据的 Region 从 a~z 切成 26 个 Region，region1 的范围是 [minIndexValue, b)，region2 的范围是 [b, c)，……，region26 的范围是 [z, maxIndexValue)。对于 idx 索引以 a 为前缀的数据都会写到 region1，以 b 为前缀的索引数据都会写到 region2，以此类推。 - -如果索引 idx2 的列是 timestamp/datetime 等时间类型，希望根据时间区间来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx2 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -该语句会把表 t 中 idx2 的索引数据 Region 从 `2010-01-01 00:00:00` 到 `2020-01-01 00:00:00` 切成 10 个 Region。region1 的范围是从 `[minIndexValue, 2011-01-01 00:00:00)`，region2 的范围是 `[2011-01-01 00:00:00, 2012-01-01 00:00:00)`…… - -其他索引列类型的切分方法也是类似的。 - -对于联合索引的数据 Region 切分，唯一不同的是可以指定多个 column 的值。 - -比如索引 `idx3 (a, b)` 包含 2 列，a 是 timestamp，b 是 int。如果只想根据 a 列做时间范围的切分，可以用切分单列时间索引的 SQL 语句来切分，`lower_value` 和 `upper_velue` 中不指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -如果想在时间相同的情况下，根据 b 列再做一次切分，在切分时指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00", "a") AND ("2010-01-01 00:00:00", "z") REGIONS 10; -``` - -该语句在 a 列时间前缀相同的情况下，根据 b 列的值从 a~z 切了 10 个 Region。如果指定的 a 列的值不相同，那么可能不会用到 b 列的值。 - -#### 不均匀切分 - -索引数据也可以根据用户指定的索引值来做切分。 - -假如有 idx4 (a,b)，其中 a 列是 varchar 类型， b 列是 timestamp 类型。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t1 INDEX idx4 BY ("a", "2000-01-01 00:00:01"), ("b", "2019-04-17 14:26:19"), ("c", ""); -``` - -该语句指定了 3 个值，会切分出 4 个 Region，每个 Region 的范围如下。 - -``` -region1 [ minIndexValue , ("a", "2000-01-01 00:00:01")) -region2 [("a", "2000-01-01 00:00:01") , ("b", "2019-04-17 14:26:19")) -region3 [("b", "2019-04-17 14:26:19") , ("c", "") ) -region4 [("c", "") , maxIndexValue ) -``` - -## pre_split_regions - -使用带有 `shard_row_id_bits` 的表时，如果希望建表时就均匀切分 Region，可以考虑配合 `pre_split_regions` 一起使用，用来在建表成功后就开始预均匀切分 `2^(pre_split_regions)` 个 Region。 - -> **注意：** -> -> `pre_split_regions` 必须小于等于 `shard_row_id_bits`。 - -### 示例 - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int,index idx1(a)) shard_row_id_bits = 4 pre_split_regions=2; -``` - -该语句在建表后，会对这个表 t 预切分出 4 + 1 个 Region。4 (2^2) 个 Region 是用来存 table 的行数据的，1 个 Region 是用来存 idx1 索引的数据。 - -4 个 table Region 的范围区间如下： - -``` -region1: [ -inf , 1<<61 ) -region2: [ 1<<61 , 2<<61 ) -region3: [ 2<<61 , 3<<61 ) -region4: [ 3<<61 , +inf ) -``` - -## 相关 session 变量 - -和 `SPLIT REGION` 语句相关的 session 变量有 `tidb_scatter_region`，`tidb_wait_split_region_finish` 和 `tidb_wait_split_region_timeout`，具体可参考 [TiDB 专用系统变量和语法](/dev/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/dev/reference/sql/statements/start-transaction.md b/dev/reference/sql/statements/start-transaction.md deleted file mode 100644 index 305f424d2982..000000000000 --- a/dev/reference/sql/statements/start-transaction.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: START TRANSACTION -summary: TiDB 数据库中 START TRANSACTION 的使用概况。 -category: reference ---- - -# START TRANSACTION - -`START TRANSACTION` 语句用于在 TiDB 内部启动新事务。它类似于语句 `BEGIN` 和 `SET autocommit = 0`。 - -在没有 `START TRANSACTION` 语句的情况下，每个语句都会在各自的事务中自动提交，这样可确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`START TRANSACTION` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/dev/reference/sql/statements/commit.md) -* [ROLLBACK](/dev/reference/sql/statements/rollback.md) -* [BEGIN](/dev/reference/sql/statements/begin.md) diff --git a/dev/reference/sql/statements/trace.md b/dev/reference/sql/statements/trace.md deleted file mode 100644 index 299735d2b964..000000000000 --- a/dev/reference/sql/statements/trace.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: TRACE -summary: TiDB 数据库中 TRACE 的使用概况。 -category: reference ---- - -# TRACE - -`TRACE` 语句用于提供查询执行的详细信息，可通过 TiDB 服务器状态端口所公开的图形界面进行查看。 - -## 语法图 - -**TraceStmt:** - -![TraceStmt](/media/sqlgram/TraceStmt.png) - -**TraceableStmt:** - -![TraceableStmt](/media/sqlgram/TraceableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -trace format='row' select * from mysql.user; -``` - -``` -+---------------------------+-----------------+------------+ -| operation | startTS | duration | -+---------------------------+-----------------+------------+ -| session.getTxnFuture | 10:33:34.647148 | 3.847µs | -| ├─session.Execute | 10:33:34.647146 | 536.233µs | -| ├─session.ParseSQL | 10:33:34.647182 | 19.868µs | -| ├─executor.Compile | 10:33:34.647219 | 295.688µs | -| ├─session.runStmt | 10:33:34.647533 | 116.229µs | -| ├─session.CommitTxn | 10:33:34.647631 | 5.44µs | -| ├─recordSet.Next | 10:33:34.647707 | 833.103µs | -| ├─tableReader.Next | 10:33:34.647709 | 806.783µs | -| ├─recordSet.Next | 10:33:34.648572 | 19.367µs | -| └─tableReader.Next | 10:33:34.648575 | 1.783µs | -+---------------------------+-----------------+------------+ -10 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -TRACE FORMAT='json' SELECT * FROM t1 WHERE id = 2; -``` - -``` -operation: [ - {"ID":{"Trace":"60d20d005593de87","Span":"44e5b309242ffe2f","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5nZXRUeG5GdXR1cmU="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTQ3ODYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MjA0MDYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":[ - {"ID":{"Trace":"60d20d005593de87","Span":"4dbf8f2ca373b4b0","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5QYXJzZVNRTA=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2NjE1MTQtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MDYxNjgtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6b6d6916df809604","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"ZXhlY3V0b3IuQ29tcGlsZQ=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NTcyODUtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MzE0MjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"3f1bcdd402a72911","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5Db21taXRUeG4="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3OTgyNjItMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MDU1NzYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"58c1f7d66dc5afbc","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5ydW5TdG10"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Msg","Value":"eyJzcWwiOiJTRUxFQ1QgKiBGUk9NIHQxIFdIRVJFIGlkID0gMiJ9"}, - {"Key":"Time","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3ODA1NjgtMDY6MDA="}, - {"Key":"_schema:log","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MTk5MzMtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NzcyNDItMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6bd8cc440fb31ed7","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5FeGVjdXRl"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTEwODktMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NTU0My0wNjowMA=="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"61d0b809f6cc018b","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NzQ1NTYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIyOTg4NjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"2bd2c3d47ccb1133","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjY0ODgtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjkwMDMtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null} - ] - } -] -1 row in set (0.00 sec) -``` - -可将 JSON 格式的跟踪文件粘贴到跟踪查看器中。查看器可通过 TiDB 状态端口访问： - -![TiDB Trace Viewer-1](/media/trace-paste.png) - -![TiDB Trace Viewer-2](/media/trace-view.png) - -## MySQL 兼容性 - -`TRACE` 语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [EXPLAIN ANALYZE](/dev/reference/sql/statements/explain-analyze.md) diff --git a/dev/reference/sql/statements/truncate.md b/dev/reference/sql/statements/truncate.md deleted file mode 100644 index f46944a94dbb..000000000000 --- a/dev/reference/sql/statements/truncate.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: TRUNCATE -summary: TiDB 数据库中 TRUNCATE 的使用概况。 -category: reference ---- - -# TRUNCATE - -`TRUNCATE` 语句以非事务方式从表中删除所有数据。可认为 `TRUNCATE` 语句同 `DROP TABLE` + `CREATE TABLE` 组合在语义上相同，定义与 `DROP TABLE` 语句相同。 - -`TRUNCATE TABLE tableName` 和 `TRUNCATE tableName` 均为有效语法。 - -## 语法图 - -**TruncateTableStmt:** - -![TruncateTableStmt](/media/sqlgram/TruncateTableStmt.png) - -**OptTable:** - -![OptTable](/media/sqlgram/OptTable.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -TRUNCATE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sqlS -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -TRUNCATE TABLE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -## MySQL 兼容性 - -`TRUNCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [DROP TABLE](/dev/reference/sql/statements/drop-table.md) -* [DELETE](/dev/reference/sql/statements/delete.md) -* [CREATE TABLE](/dev/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/dev/reference/sql/statements/show-create-table.md) diff --git a/dev/reference/sql/statements/update.md b/dev/reference/sql/statements/update.md deleted file mode 100644 index a2e8a60bf79f..000000000000 --- a/dev/reference/sql/statements/update.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: UPDATE -summary: TiDB 数据库中 UPDATE 的使用概况。 -category: reference ---- - -# UPDATE - -`UPDATE` 语句用于修改指定表中的数据。 - -## 语法图 - -**UpdateStmt:** - -![UpdateStmt](/media/sqlgram/UpdateStmt.png) - -**TableRef:** - -![TableRef](/media/sqlgram/TableRef.png) - -**TableRefs:** - -![TableRefs](/media/sqlgram/TableRefs.png) - -**AssignmentList:** - -![AssignmentList](/media/sqlgram/AssignmentList.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -UPDATE t1 SET c1=5 WHERE c1=3; -``` - -``` -Query OK, 1 row affected (0.01 sec) -Rows matched: 1 Changed: 1 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`UPDATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/dev/reference/sql/statements/insert.md) -* [SELECT](/dev/reference/sql/statements/select.md) -* [DELETE](/dev/reference/sql/statements/delete.md) -* [REPLACE](/dev/reference/sql/statements/replace.md) diff --git a/dev/reference/sql/statements/use.md b/dev/reference/sql/statements/use.md deleted file mode 100644 index 16728a688c89..000000000000 --- a/dev/reference/sql/statements/use.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: USE -summary: TiDB 数据库中 USE 的使用概况。 -category: reference ---- - -# USE - -`USE` 语句可为用户会话选择当前数据库。 - -## 语法图 - -**UseStmt:** - -![UseStmt](/media/sqlgram/UseStmt.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -USE mysql; -``` - -``` -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE newtest; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -USE newtest; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+-------------------+ -| Tables_in_newtest | -+-------------------+ -| t1 | -+-------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`USE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/dev/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/dev/reference/sql/statements/create-database.md) -* [SHOW TABLES](/dev/reference/sql/statements/show-tables.md) diff --git a/dev/reference/sql/view.md b/dev/reference/sql/view.md deleted file mode 100644 index 580076fc21ea..000000000000 --- a/dev/reference/sql/view.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: 视图 -category: reference ---- - -# 视图 - -TiDB 支持视图，视图是一张虚拟表，该虚拟表的结构由创建视图时的 `SELECT` 语句定义。使用视图一方面可以对用户只暴露安全的字段及数据，进而保证底层表的敏感字段及数据的安全。另一方面，将频繁出现的复杂查询定义为视图，可以使复杂查询更加简单便捷。 - -## 查询视图 - -查询一个视图和查询一张普通表类似。但是 TiDB 在真正执行查询视图时，会将视图展开成创建视图时定义的 `SELECT` 语句，进而执行展开后的查询语句。 - -## 样例 - -以下例子将创建一个视图，并在该视图上进行查询，最后删除该视图。 - -{{< copyable "sql" >}} - -```sql -create table t(a int, b int); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values(1, 1),(2,2),(3,3); -``` - -``` -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -create table s(a int); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into s values(2),(3); -``` - -``` -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -create view v as select s.a from t left join s on t.a = s.a; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from v; -``` - -``` -+------+ -| a | -+------+ -| NULL | -| 2 | -| 3 | -+------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -drop view v; -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -## 局限性 - -目前 TiDB 中的视图有以下局限性： - -- 不支持物化视图。 -- TiDB 中视图为只读视图，不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 -- 对已创建的视图仅支持 `DROP` 的 DDL 操作，即 `DROP [VIEW | TABLE]`。 - -## 扩展阅读 - -- [创建视图](/dev/reference/sql/statements/create-view.md) -- [删除视图](/dev/reference/sql/statements/drop-view.md) diff --git a/dev/reference/system-databases/information-schema.md b/dev/reference/system-databases/information-schema.md deleted file mode 100644 index 77bf530a1fcb..000000000000 --- a/dev/reference/system-databases/information-schema.md +++ /dev/null @@ -1,767 +0,0 @@ ---- -title: Information Schema -category: reference ---- - -# Information Schema - -为了和 MySQL 保持兼容，TiDB 支持很多 `INFORMATION_SCHEMA` 表，其中有不少表都支持相应的 `SHOW` 命令。查询 `INFORMATION_SCHEMA` 表也为表的连接操作提供了可能。 - -## ANALYZE_STATUS 表 - -`ANALYZE_STATUS` 表提供正在执行的收集统计信息的任务以及有限条历史任务记录。 - -{{< copyable "sql" >}} - -```sql -select * from `ANALYZE_STATUS`; -``` - -``` -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -| TABLE_SCHEMA | TABLE_NAME | PARTITION_NAME | JOB_INFO | PROCESSED_ROWS | START_TIME | STATE | -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -| test | t | | analyze index idx | 2 | 2019-06-21 19:51:14 | finished | -| test | t | | analyze columns | 2 | 2019-06-21 19:51:14 | finished | -| test | t1 | p0 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p3 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p1 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p2 | analyze columns | 1 | 2019-06-21 19:51:15 | finished | -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -6 rows in set -``` - -## CHARACTER_SETS 表 - -`CHARACTER_SETS` 表提供[字符集](/dev/reference/sql/character-set.md)相关的信息。TiDB 目前仅支持部分字符集。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM character_sets; -``` - -``` -+--------------------+----------------------+---------------+--------+ -| CHARACTER_SET_NAME | DEFAULT_COLLATE_NAME | DESCRIPTION | MAXLEN | -+--------------------+----------------------+---------------+--------+ -| utf8 | utf8_bin | UTF-8 Unicode | 3 | -| utf8mb4 | utf8mb4_bin | UTF-8 Unicode | 4 | -| ascii | ascii_bin | US ASCII | 1 | -| latin1 | latin1_bin | Latin1 | 1 | -| binary | binary | binary | 1 | -+--------------------+----------------------+---------------+--------+ -5 rows in set (0.00 sec) -``` - -## COLLATIONS 表 - -`COLLATIONS` 表提供了 `CHARACTER_SETS` 表中字符集对应的排序规则列表。TiDB 当前仅支持二进制排序规则，包含该表仅为兼容 MySQL。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM collations WHERE character_set_name='utf8mb4'; -``` - -``` -+------------------------+--------------------+------+------------+-------------+---------+ -| COLLATION_NAME | CHARACTER_SET_NAME | ID | IS_DEFAULT | IS_COMPILED | SORTLEN | -+------------------------+--------------------+------+------------+-------------+---------+ -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+------------------------+--------------------+------+------------+-------------+---------+ -26 rows in set (0.00 sec) -``` - -## COLLATION_CHARACTER_SET_APPLICABILITY 表 - -`COLLATION_CHARACTER_SET_APPLICABILITY` 表将排序规则映射至适用的字符集名称。和 `COLLATIONS` 表一样，包含此表也是为了兼容 MySQL。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM collation_character_set_applicability WHERE character_set_name='utf8mb4'; -``` - -``` -+------------------------+--------------------+ -| COLLATION_NAME | CHARACTER_SET_NAME | -+------------------------+--------------------+ -| utf8mb4_general_ci | utf8mb4 | -| utf8mb4_bin | utf8mb4 | -| utf8mb4_unicode_ci | utf8mb4 | -| utf8mb4_icelandic_ci | utf8mb4 | -| utf8mb4_latvian_ci | utf8mb4 | -| utf8mb4_romanian_ci | utf8mb4 | -| utf8mb4_slovenian_ci | utf8mb4 | -| utf8mb4_polish_ci | utf8mb4 | -| utf8mb4_estonian_ci | utf8mb4 | -| utf8mb4_spanish_ci | utf8mb4 | -| utf8mb4_swedish_ci | utf8mb4 | -| utf8mb4_turkish_ci | utf8mb4 | -| utf8mb4_czech_ci | utf8mb4 | -| utf8mb4_danish_ci | utf8mb4 | -| utf8mb4_lithuanian_ci | utf8mb4 | -| utf8mb4_slovak_ci | utf8mb4 | -| utf8mb4_spanish2_ci | utf8mb4 | -| utf8mb4_roman_ci | utf8mb4 | -| utf8mb4_persian_ci | utf8mb4 | -| utf8mb4_esperanto_ci | utf8mb4 | -| utf8mb4_hungarian_ci | utf8mb4 | -| utf8mb4_sinhala_ci | utf8mb4 | -| utf8mb4_german2_ci | utf8mb4 | -| utf8mb4_croatian_ci | utf8mb4 | -| utf8mb4_unicode_520_ci | utf8mb4 | -| utf8mb4_vietnamese_ci | utf8mb4 | -+------------------------+--------------------+ -26 rows in set (0.00 sec) -``` - -## COLUMNS 表 - -`COLUMNS` 表提供了表的所有列的信息。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.t1 (a int); -``` - -``` -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM information_schema.columns WHERE table_schema='test' AND TABLE_NAME='t1'; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: t1 - COLUMN_NAME: a - ORDINAL_POSITION: 1 - COLUMN_DEFAULT: NULL - IS_NULLABLE: YES - DATA_TYPE: int -CHARACTER_MAXIMUM_LENGTH: NULL - CHARACTER_OCTET_LENGTH: NULL - NUMERIC_PRECISION: 11 - NUMERIC_SCALE: 0 - DATETIME_PRECISION: NULL - CHARACTER_SET_NAME: NULL - COLLATION_NAME: NULL - COLUMN_TYPE: int(11) - COLUMN_KEY: - EXTRA: - PRIVILEGES: select,insert,update,references - COLUMN_COMMENT: - GENERATION_EXPRESSION: -1 row in set (0.01 sec) -``` - -对应的 `SHOW` 语句如下： - -{{< copyable "sql" >}} - -```sql -SHOW COLUMNS FROM t1 FROM test; -``` - -``` -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -## ENGINES 表 - -`ENGINES` 表提供了关于存储引擎的信息。从和 MySQL 兼容性上考虑，TiDB 会一直将 InnoDB 描述为唯一支持的引擎。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM engines; -``` - -``` -*************************** 1. row *************************** - ENGINE: InnoDB - SUPPORT: DEFAULT - COMMENT: Supports transactions, row-level locking, and foreign keys -TRANSACTIONS: YES - XA: YES - SAVEPOINTS: YES -1 row in set (0.00 sec) -``` - -## KEY_COLUMN_USAGE 表 - -`KEY_COLUMN_USAGE` 表描述了列的键约束，比如主键约束。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM key_column_usage WHERE table_schema='mysql' and table_name='user'; -``` - -``` -*************************** 1. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: Host - ORDINAL_POSITION: 1 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -*************************** 2. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: User - ORDINAL_POSITION: 2 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -2 rows in set (0.00 sec) -``` - -## PROCESSLIST 表 - -`PROCESSLIST` 和 `show processlist` 的功能一样，都是查看当前正在处理的请求。 - -`PROCESSLIST` 表会比 `show processlist` 多一个 `MEM` 列，`MEM` 是指正在处理的请求已使用的内存，单位是 byte。 - -```sql -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -| ID | USER | HOST | DB | COMMAND | TIME | STATE | INFO | MEM | -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -| 1 | root | ::1 | INFORMATION_SCHEMA | Query | 0 | 2 | select * from PROCESSLIST | 0 | -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -``` - -## SCHEMATA 表 - -`SCHEMATA` 表提供了关于数据库的信息。表中的数据与 `SHOW DATABASES` 语句的执行结果等价。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM schemata; -``` - -``` -+--------------+--------------------+----------------------------+------------------------+----------+ -| CATALOG_NAME | SCHEMA_NAME | DEFAULT_CHARACTER_SET_NAME | DEFAULT_COLLATION_NAME | SQL_PATH | -+--------------+--------------------+----------------------------+------------------------+----------+ -| def | INFORMATION_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | mynewdb | utf8mb4 | utf8mb4_bin | NULL | -| def | mysql | utf8mb4 | utf8mb4_bin | NULL | -| def | PERFORMANCE_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | test | utf8mb4 | utf8mb4_bin | NULL | -+--------------+--------------------+----------------------------+------------------------+----------+ -5 rows in set (0.00 sec) -``` - -## SESSION_VARIABLES 表 - -`SESSION_VARIABLES` 表提供了关于 session 变量的信息。表中的数据跟 `SHOW SESSION VARIABLES` 语句执行结果类似。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM session_variables LIMIT 10; -``` - -``` -+----------------------------------+----------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+----------------------------------+----------------------+ -| max_write_lock_count | 18446744073709551615 | -| server_id_bits | 32 | -| net_read_timeout | 30 | -| innodb_online_alter_log_max_size | 134217728 | -| innodb_optimize_fulltext_only | OFF | -| max_join_size | 18446744073709551615 | -| innodb_read_io_threads | 4 | -| session_track_gtids | OFF | -| have_ssl | DISABLED | -| max_binlog_cache_size | 18446744073709547520 | -+----------------------------------+----------------------+ -10 rows in set (0.00 sec) -``` - -## SLOW_QUERY 表 - -`SLOW_QUERY` 表中提供了慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，列名和慢日志中的字段名是一一对应。关于如何使用该表调查和改善慢查询请参考[慢查询日志文档](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 - -```sql -mysql> desc information_schema.slow_query; -+---------------+---------------------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+------+---------+-------+ -| Time | timestamp unsigned | YES | | NULL | | -| Txn_start_ts | bigint(20) unsigned | YES | | NULL | | -| User | varchar(64) | YES | | NULL | | -| Host | varchar(64) | YES | | NULL | | -| Conn_ID | bigint(20) unsigned | YES | | NULL | | -| Query_time | double unsigned | YES | | NULL | | -| Process_time | double unsigned | YES | | NULL | | -| Wait_time | double unsigned | YES | | NULL | | -| Backoff_time | double unsigned | YES | | NULL | | -| Request_count | bigint(20) unsigned | YES | | NULL | | -| Total_keys | bigint(20) unsigned | YES | | NULL | | -| Process_keys | bigint(20) unsigned | YES | | NULL | | -| DB | varchar(64) | YES | | NULL | | -| Index_ids | varchar(100) | YES | | NULL | | -| Is_internal | tinyint(1) unsigned | YES | | NULL | | -| Digest | varchar(64) | YES | | NULL | | -| Stats | varchar(512) | YES | | NULL | | -| Cop_proc_avg | double unsigned | YES | | NULL | | -| Cop_proc_p90 | double unsigned | YES | | NULL | | -| Cop_proc_max | double unsigned | YES | | NULL | | -| Cop_proc_addr | varchar(64) | YES | | NULL | | -| Cop_wait_avg | double unsigned | YES | | NULL | | -| Cop_wait_p90 | double unsigned | YES | | NULL | | -| Cop_wait_max | double unsigned | YES | | NULL | | -| Cop_wait_addr | varchar(64) | YES | | NULL | | -| Mem_max | bigint(20) unsigned | YES | | NULL | | -| Succ | tinyint(1) unsigned | YES | | NULL | | -| Query | longblob unsigned | YES | | NULL | | -+---------------+---------------------+------+------+---------+-------+ -``` - -## STATISTICS 表 - -`STATISTICS` 表提供了关于表索引的信息。 - -{{< copyable "sql" >}} - -```sql -desc statistics; -``` - -``` -+---------------|---------------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------|---------------------|------|------|---------|-------+ -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| TABLE_SCHEMA | varchar(64) | YES | | NULL | | -| TABLE_NAME | varchar(64) | YES | | NULL | | -| NON_UNIQUE | varchar(1) | YES | | NULL | | -| INDEX_SCHEMA | varchar(64) | YES | | NULL | | -| INDEX_NAME | varchar(64) | YES | | NULL | | -| SEQ_IN_INDEX | bigint(2) UNSIGNED | YES | | NULL | | -| COLUMN_NAME | varchar(21) | YES | | NULL | | -| COLLATION | varchar(1) | YES | | NULL | | -| CARDINALITY | bigint(21) UNSIGNED | YES | | NULL | | -| SUB_PART | bigint(3) UNSIGNED | YES | | NULL | | -| PACKED | varchar(10) | YES | | NULL | | -| NULLABLE | varchar(3) | YES | | NULL | | -| INDEX_TYPE | varchar(16) | YES | | NULL | | -| COMMENT | varchar(16) | YES | | NULL | | -| INDEX_COMMENT | varchar(1024) | YES | | NULL | | -+---------------|---------------------|------|------|---------|-------+ -``` - -下列语句是等价的： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM INFORMATION_SCHEMA.STATISTICS - WHERE table_name = 'tbl_name' - AND table_schema = 'db_name' -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEX - FROM tbl_name - FROM db_name -``` - -## TABLES 表 - -`TABLES` 表提供了数据库里面关于表的信息。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - TABLE_TYPE: BASE TABLE - ENGINE: InnoDB - VERSION: 10 - ROW_FORMAT: Compact - TABLE_ROWS: 0 - AVG_ROW_LENGTH: 0 - DATA_LENGTH: 0 - MAX_DATA_LENGTH: 0 - INDEX_LENGTH: 0 - DATA_FREE: 0 - AUTO_INCREMENT: 0 - CREATE_TIME: 2019-03-29 09:17:27 - UPDATE_TIME: NULL - CHECK_TIME: NULL - TABLE_COLLATION: utf8mb4_bin - CHECKSUM: NULL - CREATE_OPTIONS: - TABLE_COMMENT: - TIDB_TABLE_ID: 5 -TIDB_ROW_ID_SHARDING_INFO: NULL -1 row in set (0.00 sec) -``` - -以下操作是等价的： - -{{< copyable "sql" >}} - -```sql -SELECT table_name FROM INFORMATION_SCHEMA.TABLES - WHERE table_schema = 'db_name' - [AND table_name LIKE 'wild'] -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES - FROM db_name - [LIKE 'wild'] -``` - -表中的信息大部分定义自 MySQL，此外有两列是 TiDB 新增的： - -* `TIDB_TABLE_ID`：标识表的内部 ID，该 ID 在一个 TiDB 集群内部唯一。 -* `TIDB_ROW_ID_SHARDING_INFO`：标识表的 Sharding 类型，可能的值为： - - `"NOT_SHARDED"`：表未被 Shard。 - - `"NOT_SHARDED(PK_IS_HANDLE)"`：一个定义了整型主键的表未被 Shard。 - - `"PK_AUTO_RANDOM_BITS={bit_number}"`：一个定义了整型主键的表由于定义了 `AUTO_RANDOM` 而被 Shard。 - - `"SHARD_BITS={bit_number}"`：表使用 `SHARD_ROW_ID_BITS={bit_number}` 进行了 Shard。 - - NULL：表属于系统表或 View，无法被 Shard。 - -## TABLE_CONSTRAINTS 表 - -`TABLE_CONSTRAINTS` 表记录了表的约束信息。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM table_constraints WHERE constraint_type='UNIQUE'; -``` - -``` -*************************** 1. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: name - TABLE_SCHEMA: mysql - TABLE_NAME: help_topic - CONSTRAINT_TYPE: UNIQUE -*************************** 2. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_meta - CONSTRAINT_TYPE: UNIQUE -*************************** 3. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_histograms - CONSTRAINT_TYPE: UNIQUE -*************************** 4. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_buckets - CONSTRAINT_TYPE: UNIQUE -*************************** 5. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range - CONSTRAINT_TYPE: UNIQUE -*************************** 6. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_done_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range_done - CONSTRAINT_TYPE: UNIQUE -6 rows in set (0.00 sec) -``` - -其中： - -* `CONSTRAINT_TYPE` 的取值可以是 `UNIQUE`，`PRIMARY KEY`，或者 `FOREIGN KEY`。 -* `UNIQUE` 和 `PRIMARY KEY` 信息与 `SHOW INDEX` 语句的执行结果类似。 - -## TIDB_HOT_REGIONS 表 - -`TIDB_HOT_REGIONS` 表提供了关于热点 REGION 的相关信息。 - -{{< copyable "sql" >}} - -```sql -desc TIDB_HOT_REGIONS; -``` - -``` -+----------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------+---------------------+------+-----+---------+-------+ -| TABLE_ID | bigint(21) unsigned | YES | | | | -| INDEX_ID | bigint(21) unsigned | YES | | | | -| DB_NAME | varchar(64) | YES | | | | -| TABLE_NAME | varchar(64) | YES | | | | -| INDEX_NAME | varchar(64) | YES | | | | -| TYPE | varchar(64) | YES | | | | -| MAX_HOT_DEGREE | bigint(21) unsigned | YES | | | | -| REGION_COUNT | bigint(21) unsigned | YES | | | | -| FLOW_BYTES | bigint(21) unsigned | YES | | | | -+----------------+---------------------+------+-----+---------+-------+ -``` - -## TIDB_INDEXES 表 - -`TIDB_INDEXES` 记录了所有表中的 INDEX 信息。 - -{{< copyable "sql" >}} - -```sql -desc TIDB_INDEXES; -``` - -``` -+---------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+-----+---------+-------+ -| TABLE_SCHEMA | varchar(64) | YES | | | | -| TABLE_NAME | varchar(64) | YES | | | | -| NON_UNIQUE | bigint(21) unsigned | YES | | | | -| KEY_NAME | varchar(64) | YES | | | | -| SEQ_IN_INDEX | bigint(21) unsigned | YES | | | | -| COLUMN_NAME | varchar(64) | YES | | | | -| SUB_PART | bigint(21) unsigned | YES | | | | -| INDEX_COMMENT | varchar(2048) | YES | | | | -| INDEX_ID | bigint(21) unsigned | YES | | | | -+---------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_REGION_PEERS 表 - -`TIKV_REGION_PEERS` 表提供了所有 REGION 的 peer 信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_REGION_PEERS; -``` - -``` -+--------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+---------------------+------+-----+---------+-------+ -| REGION_ID | bigint(21) unsigned | YES | | | | -| PEER_ID | bigint(21) unsigned | YES | | | | -| STORE_ID | bigint(21) unsigned | YES | | | | -| IS_LEARNER | tinyint(1) unsigned | YES | | | | -| IS_LEADER | tinyint(1) unsigned | YES | | | | -| STATUS | varchar(10) | YES | | | | -| DOWN_SECONDS | bigint(21) unsigned | YES | | | | -+--------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_REGION_STATUS 表 - -`TIKV_REGION_STATUS` 表提供了所有 REGION 的状态信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_REGION_STATUS; -``` - -``` -+------------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+------------------+---------------------+------+-----+---------+-------+ -| REGION_ID | bigint(21) unsigned | YES | | | | -| START_KEY | text | YES | | | | -| END_KEY | text | YES | | | | -| EPOCH_CONF_VER | bigint(21) unsigned | YES | | | | -| EPOCH_VERSION | bigint(21) unsigned | YES | | | | -| WRITTEN_BYTES | bigint(21) unsigned | YES | | | | -| READ_BYTES | bigint(21) unsigned | YES | | | | -| APPROXIMATE_SIZE | bigint(21) unsigned | YES | | | | -| APPROXIMATE_KEYS | bigint(21) unsigned | YES | | | | -+------------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_STORE_STATUS 表 - -`TIKV_STORE_STATUS` 表提供了所有 TiKV Store 的状态信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_STORE_STATUS; -``` - -``` -+-------------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------------------+---------------------+------+-----+---------+-------+ -| STORE_ID | bigint(21) unsigned | YES | | | | -| ADDRESS | varchar(64) | YES | | | | -| STORE_STATE | bigint(21) unsigned | YES | | | | -| STORE_STATE_NAME | varchar(64) | YES | | | | -| LABEL | json unsigned | YES | | | | -| VERSION | varchar(64) | YES | | | | -| CAPACITY | varchar(64) | YES | | | | -| AVAILABLE | varchar(64) | YES | | | | -| LEADER_COUNT | bigint(21) unsigned | YES | | | | -| LEADER_WEIGHT | bigint(21) unsigned | YES | | | | -| LEADER_SCORE | bigint(21) unsigned | YES | | | | -| LEADER_SIZE | bigint(21) unsigned | YES | | | | -| REGION_COUNT | bigint(21) unsigned | YES | | | | -| REGION_WEIGHT | bigint(21) unsigned | YES | | | | -| REGION_SCORE | bigint(21) unsigned | YES | | | | -| REGION_SIZE | bigint(21) unsigned | YES | | | | -| START_TS | datetime unsigned | YES | | | | -| LAST_HEARTBEAT_TS | datetime unsigned | YES | | | | -| UPTIME | varchar(64) | YES | | | | -+-------------------+---------------------+------+-----+---------+-------+ -``` - -## USER_PRIVILEGES 表 - -`USER_PRIVILEGES` 表提供了关于全局权限的信息。该表的数据根据 `mysql.user` 系统表生成。 - -{{< copyable "sql" >}} - -```sql -desc USER_PRIVILEGES; -``` - -``` -+----------------|--------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------|--------------|------|------|---------|-------+ -| GRANTEE | varchar(81) | YES | | NULL | | -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| PRIVILEGE_TYPE | varchar(64) | YES | | NULL | | -| IS_GRANTABLE | varchar(3) | YES | | NULL | | -+----------------|--------------|------|------|---------|-------+ -4 rows in set (0.00 sec) -``` - -## VIEWS 表 - -`VIEWS` 表提供了关于 SQL 视图的信息。 - -{{< copyable "sql" >}} - -```sql -create view test.v1 as select 1; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from views; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: v1 - VIEW_DEFINITION: select 1 - CHECK_OPTION: CASCADED - IS_UPDATABLE: NO - DEFINER: root@127.0.0.1 - SECURITY_TYPE: DEFINER -CHARACTER_SET_CLIENT: utf8 -COLLATION_CONNECTION: utf8_general_ci -1 row in set (0.00 sec) -``` - -## 不支持的 Information Schema 表 - -TiDB 包含以下 `INFORMATION_SCHEMA` 表，但仅会返回空行： - -* `COLUMN_PRIVILEGES` -* `EVENTS` -* `FILES` -* `GLOBAL_STATUS` -* `GLOBAL_VARIABLES` -* `OPTIMIZER_TRACE` -* `PARAMETERS` -* `PARTITIONS` -* `PLUGINS` -* `PROFILING` -* `REFERENTIAL_CONSTRAINTS` -* `ROUTINES` -* `SCHEMA_PRIVILEGES` -* `SESSION_STATUS` -* `TABLESPACES` -* `TABLE_PRIVILEGES` -* `TRIGGERS` diff --git a/dev/reference/tidb-binlog/deploy.md b/dev/reference/tidb-binlog/deploy.md deleted file mode 100644 index 5a0806b4c40c..000000000000 --- a/dev/reference/tidb-binlog/deploy.md +++ /dev/null @@ -1,629 +0,0 @@ ---- -title: TiDB Binlog 集群部署 -category: reference -aliases: ['/docs-cn/dev/how-to/deploy/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/deploy/'] ---- - -# TiDB Binlog 集群部署 - -## 服务器要求 - -Pump 和 Drainer 均可部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台上。在开发、测试和生产环境下，对服务器硬件配置的要求和建议如下： - -| 服务 | 部署数量 | CPU | 磁盘 | 内存 | -| :-------- | :-------- | :--------| :--------------- | :------ | -| Pump | 3 | 8核+ | SSD, 200 GB+ | 16G | -| Drainer | 1 | 8核+ | SAS, 100 GB+ （如果输出 binlog 为本地文件，磁盘大小视保留数据天数而定） | 16G | - -## 使用 TiDB Ansible 部署 TiDB Binlog - -### 第 1 步：下载 TiDB Ansible - -1. 以 TiDB 用户登录中控机并进入 `/home/tidb` 目录。以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - - | TiDB Ansible 分支 | TiDB 版本 | 备注 | - | ---------------- | --------- | --- | - | master | master 版本 | 包含最新特性，每日更新。 | - -2. 使用以下命令从 GitHub [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应分支，默认的文件夹名称为 `tidb-ansible`。 - - - 下载 master 版本： - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-ansible.git - ``` - -### 第 2 步：部署 Pump - -1. 修改 tidb-ansible/inventory.ini 文件 - - 1. 设置 `enable_binlog = True`，表示 TiDB 集群开启 binlog。 - - ```ini - ## binlog trigger - enable_binlog = True - ``` - - 2. 为 `pump_servers` 主机组添加部署机器 IP。 - - ```ini - ## Binlog Part - [pump_servers] - 172.16.10.72 - 172.16.10.73 - 172.16.10.74 - ``` - - 默认 Pump 保留 7 天数据，如需修改可修改 `tidb-ansible/conf/pump.yml`（TiDB 3.0.0~3.0.2 版本中为 `tidb-ansible/conf/pump-cluster.yml`）文件中 `gc` 变量值，并取消注释。 - - {{< copyable "" >}} - - ```yaml - global: - # an integer value to control the expiry date of the binlog data, which indicates for how long (in days) the binlog data would be stored - # must be bigger than 0 - # gc: 7 - ``` - - 请确保部署目录有足够空间存储 binlog，详见[调整部署目录](/dev/how-to/deploy/orchestrated/ansible.md#调整部署目录)，也可为 Pump 设置单独的部署目录。 - - ```ini - ## Binlog Part - [pump_servers] - pump1 ansible_host=172.16.10.72 deploy_dir=/data1/pump - pump2 ansible_host=172.16.10.73 deploy_dir=/data2/pump - pump3 ansible_host=172.16.10.74 deploy_dir=/data3/pump - ``` - -2. 部署并启动含 Pump 组件的 TiDB 集群 - - 参照上文配置完 `inventory.ini` 文件后，从以下两种方式中选择一种进行部署。 - - **方式一**：在已有的 TiDB 集群上增加 Pump 组件，需按以下步骤逐步进行。 - - 1. 部署 pump_servers 和 node_exporters - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=pump -l ${pump1_ip},${pump2_ip},[${alias1_name},${alias2_name}] - ``` - - > **注意：** - > - > 以上命令中，逗号后不要加空格，否则会报错。 - - 2. 启动 pump_servers - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=pump - ``` - - 3. 更新并重启 tidb_servers - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=tidb - ``` - - 4. 更新监控信息 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - - **方式二**：从零开始部署含 Pump 组件的 TiDB 集群 - - 使用 Ansible 部署 TiDB 集群，方法参考 [使用 TiDB Ansible 部署 TiDB 集群](/dev/how-to/deploy/orchestrated/ansible.md)。 - -3. 查看 Pump 服务状态 - - 使用 binlogctl 查看 Pump 服务状态，pd-urls 参数请替换为集群 PD 地址，结果 State 为 online 表示 Pump 启动成功。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && - resources/bin/binlogctl -pd-urls=http://172.16.10.72:2379 -cmd pumps - ``` - - ``` - INFO[0000] pump: {NodeID: ip-172-16-10-72:8250, Addr: 172.16.10.72:8250, State: online, MaxCommitTS: 403051525690884099, UpdateTime: 2018-12-25 14:23:37 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-73:8250, Addr: 172.16.10.73:8250, State: online, MaxCommitTS: 403051525703991299, UpdateTime: 2018-12-25 14:23:36 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-74:8250, Addr: 172.16.10.74:8250, State: online, MaxCommitTS: 403051525717360643, UpdateTime: 2018-12-25 14:23:35 +0800 CST} - ``` - -### 第 3 步：部署 Drainer - -1. 获取 initial_commit_ts 的值 - - Drainer 初次启动时需要获取 initial_commit_ts 这个时间戳信息。 - - - 如果从最近的时间点开始同步，initial_commit_ts 使用 `-1` 即可。 - - - 如果下游为 MySQL 或 TiDB，为了保证数据的完整性，需要进行全量数据的备份与恢复。此时 initial_commit_ts 的值必须是全量备份的时间戳。 - - 如果使用 mydumper 进行全量备份，可以在导出目录中找到 metadata 文件，其中的 `Pos` 字段值即全量备份的时间戳。metadata 文件示例如下： - - ``` - Started dump at: 2019-12-30 13:25:41 - SHOW MASTER STATUS: - Log: tidb-binlog - Pos: 413580274257362947 - GTID: - - Finished dump at: 2019-12-30 13:25:41 - ``` - -2. 修改 `tidb-ansible/inventory.ini` 文件 - - 为 `drainer_servers` 主机组添加部署机器 IP，initial_commit_ts 请设置为获取的 initial_commit_ts，仅用于 Drainer 第一次启动。 - - - 以下游为 MySQL 为例，别名为 `drainer_mysql`。 - - ```ini - [drainer_servers] - drainer_mysql ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - - - 以下游为 file 为例，别名为 `drainer_file`。 - - ```ini - [drainer_servers] - drainer_file ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - -3. 修改配置文件 - - - 以下游为 MySQL 为例 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible/conf && - cp drainer.toml drainer_mysql_drainer.toml && - vi drainer_mysql_drainer.toml - ``` - - > **注意：** - > - > 配置文件名命名规则为 `别名_drainer.toml`，否则部署时无法找到自定义配置文件。 - - db-type 设置为 "mysql"， 配置下游 MySQL 信息。 - - {{< copyable "" >}} - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "mysql" - - # the downstream MySQL protocol database - [syncer.to] - host = "172.16.10.72" - user = "root" - password = "123456" - port = 3306 - ``` - - - 以下游为增量备份文件为例 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible/conf && - cp drainer.toml drainer_file_drainer.toml && - vi drainer_file_drainer.toml - ``` - - db-type 设置为 "file"。 - - {{< copyable "" >}} - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "file" - - # Uncomment this if you want to use "file" as "db-type". - [syncer.to] - # default data directory: "{{ deploy_dir }}/data.drainer" - dir = "data.drainer" - ``` - -4. 部署 Drainer - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy_drainer.yml - ``` - -5. 启动 Drainer - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start_drainer.yml - ``` - -## 使用 Binary 部署 TiDB Binlog - -### 下载官方 Binary - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，Pump 和 Drainer 已经包含在 TiDB 的下载包中，其他版本需要单独下载 Pump 和 Drainer: - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-binlog-latest-linux-amd64.sha256 -``` - -### 使用样例 - -假设有三个 PD，一个 TiDB，另外有两台机器用于部署 Pump，一台机器用于部署 Drainer。各个节点信息如下： - -``` -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -Pump="192.168.0.11" -Pump="192.168.0.12" -Drainer="192.168.0.13" -``` - -下面以此为例，说明 Pump/Drainer 的使用。 - -1. 使用 binary 部署 Pump - - - Pump 命令行参数说明（以在 “192.168.0.11” 上部署为例） - - ```bash - Usage of Pump: - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.11:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.11:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置; - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里的配置。 - -data-dir string - Pump 数据存储位置路径 - -gc int - Pump 只保留多少天以内的数据 (默认 7) - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -node-id string - Pump 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -fake-binlog-interval int - Pump 节点生成 fake binlog 的频率 (默认 3，单位 秒) - ``` - - - Pump 配置文件（以在 “192.168.0.11” 上部署为例） - - ```toml - # Pump Configuration - - # Pump 绑定的地址 - addr = "192.168.0.11:8250" - - # Pump 对外提供服务的地址 - advertise-addr = "192.168.0.11:8250" - - # Pump 只保留多少天以内的数据 (默认 7) - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 2 - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/drainer.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/drainer-key.pem" - - # [storage] - # 设置为 true（默认值）来保证可靠性，确保 binlog 数据刷新到磁盘 - # sync-log = true - - # 当可用磁盘容量小于该设置值时，Pump 将停止写入数据 - # 42 MB -> 42000000, 42 mib -> 44040192 - # default: 10 gib - # stop-write-at-available-space = "10 gib" - - # Pump 内嵌的 LSM DB 设置，除非对该部分很了解，否则一般注解掉 - # [storage.kv] - # block-cache-capacity = 8388608 - # block-restart-interval = 16 - # block-size = 4096 - # compaction-L0-trigger = 8 - # compaction-table-size = 67108864 - # compaction-total-size = 536870912 - # compaction-total-size-multiplier = 8.0 - # write-buffer = 67108864 - # write-L0-pause-trigger = 24 - # write-L0-slowdown-trigger = 17 - ``` - - - 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -2. 使用 binary 部署 Drainer - - - Drainer 命令行参数说明（以在 “192.168.0.13” 上部署为例） - - ```bash - Usage of Drainer - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.13:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -cache-binlog-count int - 缓存中的 binlog 数目限制（默认 8） - 如果上游的单个 binlog 较大导致 Drainer 出现 OOM 时，可尝试调小该值减少内存使用 - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的配置 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql，支持 tidb、kafka、file) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-detect - 是否禁用冲突监测 - -disable-dispatch - 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则每个 binlog - 按顺序依次还原成单个事务进行同步（下游服务类型为 MySQL，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts（默认为 `-1`） - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - 该参数值为 `-1` 时，Drainer 会自动从 PD 获取一个最新的时间戳 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位：秒） - -node-id string - drainer 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -safe-mode - 是否开启安全模式使得下游 MySQL/TiDB 可被重复写入 - 即将 insert 语句换为 replace 语句，将 update 语句拆分为 delete + replace 语句 - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - - - Drainer 配置文件（以在 “192.168.0.13” 上部署为例） - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.13:8249") - addr = "192.168.0.13:8249" - - # Drainer 对外提供服务的地址 - advertise-addr = "192.168.0.13:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Drainer 从 Pump 获取 binlog 时对数据进行压缩，值可以为 "gzip"，如果不配置则不进行压缩 - # compressor = "gzip" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/pump.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/pump-key.pem" - - # Syncer Configuration - [syncer] - # 如果设置了该项，会使用该 sql-mode 解析 DDL 语句，此时如果下游是 MySQL 或 TiDB 则 - # 下游的 sql-mode 也会被设置为该值 - # sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" - - # 输出到下游数据库一个事务的 SQL 语句数量 (默认 20) - txn-batch = 20 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (默认 16) - worker-count = 16 - - # 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 MySQL, 该项设置为 False） - disable-dispatch = false - - # safe mode 会使写下游 MySQL/TiDB 可被重复写入 - # 会用 replace 替换 insert 语句，用 delete + replace 替换 update 语句 - safe-mode = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql"，"tidb"，"file"，"kafka" - db-type = "mysql" - - # 事务的 commit ts 若在该列表中，则该事务将被过滤，不会同步至下游 - ignore-txn-commit-ts = [] - - # db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - # 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。 - # 以 '~' 开始声明使用正则表达式 - - # replicate-do-db = ["~^b.*","s1"] - - # [syncer.relay] - # 保存 relay log 的目录，空值表示不开启。 - # 只有下游是 TiDB 或 MySQL 时该配置才生效。 - # log-dir = "" - # 每个文件的大小上限 - # max-file-size = 10485760 - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "log" - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "~^a.*" - - # 忽略同步某些表 - # [[syncer.ignore-table]] - # db-name = "test" - # tbl-name = "log" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.13" - user = "root" - password = "" - # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 - # encrypted_password 非空时 password 会被忽略 - encrypted_password = "" - port = 3306 - - [syncer.to.checkpoint] - # 当 checkpoint type 是 mysql 或 tidb 时可以开启该选项，以改变保存 checkpoint 的数据库 - # schema = "tidb_binlog" - # 目前只支持 mysql 或者 tidb 类型。可以去掉注释来控制 checkpoint 保存的位置。 - # db-type 默认的 checkpoint 保存方式是: - # mysql/tidb -> 对应的下游 mysql/tidb - # file/kafka -> file in `data-dir` - # type = "mysql" - # host = "127.0.0.1" - # user = "root" - # password = "" - # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 - # encrypted_password 非空时 password 会被忽略 - # encrypted_password = "" - # port = 3306 - - - # db-type 设置为 file 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - - # db-type 设置为 kafka 时，Kafka 相关配置 - # [syncer.to] - # kafka-addrs 和 zookeeper-addrs 只需要一个，两者都有时程序会优先用 zookeeper 中的 kafka 地址 - # zookeeper-addrs = "127.0.0.1:2181" - # kafka-addrs = "127.0.0.1:9092" - # kafka-version = "0.8.2.0" - # kafka-max-messages = 1024 - - # 保存 binlog 数据的 Kafka 集群的 topic 名称，默认值为 _obinlog - # 如果运行多个 Drainer 同步数据到同一个 Kafka 集群，每个 Drainer 的 topic-name 需要设置不同的名称 - # topic-name = "" - ``` - - - 启动示例 - - > **注意：** - > - > 如果下游为 MySQL/TiDB，为了保证数据的完整性，在 Drainer 初次启动前需要获取 `initial-commit-ts` 的值，并进行全量数据的备份与恢复。详细信息参见[部署 Drainer](#第-3-步部署-drainer)。 - - 初次启动时使用参数 `initial-commit-ts`， 命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml -initial-commit-ts {initial-commit-ts} - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -> **注意：** -> -> - 在运行 TiDB 时，需要保证至少一个 Pump 正常运行。 -> - 通过给 TiDB 增加启动参数 `enable-binlog` 来开启 binlog 服务。尽量保证同一集群的所有 TiDB 都开启了 binlog 服务，否则在同步数据时可能会导致上下游数据不一致。如果要临时运行一个不开启 binlog 服务的 TiDB 实例，需要在 TiDB 的配置文件中设置 `run_ddl= false`。 -> - Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 -> - 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取**快照时间戳**，然后导入全量备份，最后启动 Drainer 从对应的快照时间戳开始同步增量数据。 -> - 下游使用 MySQL 或 TiDB 时应当保证上下游数据库的 sql_mode 具有一致性，即下游数据库同步每条 SQL 语句时的 sql_mode 应当与上游数据库执行该条 SQL 语句时的 sql_mode 保持一致。可以在上下游分别执行 `select @@sql_mode;` 进行查询和比对。 -> - 如果存在上游 TiDB 能运行但下游 MySQL 不支持的 DDL 语句时（例如下游 MySQL 使用 InnoDB 引擎时同步语句 `CREATE TABLE t1(a INT) ROW_FORMAT=FIXED;`），Drainer 也会同步失败，此时可以在 Drainer 配置中跳过该事务，同时在下游手动执行兼容的语句，详见[跳过事务](/dev/reference/tidb-binlog/faq.md#同步时出现上游数据库支持但是下游数据库执行会出错的-ddl应该怎么办)。 diff --git a/dev/reference/tidb-binlog/faq.md b/dev/reference/tidb-binlog/faq.md deleted file mode 100644 index 1a25fd54e9ff..000000000000 --- a/dev/reference/tidb-binlog/faq.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: TiDB Binlog 常见问题 -category: FAQ -aliases: ['/docs-cn/dev/faq/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/faq/'] ---- - -# TiDB Binlog 常见问题 - -本文介绍 TiDB Binlog 使用过程中的常见问题及解决方案。 - -## 开启 binog 对 TiDB 的性能有何影响？ - -- 对于查询无影响。 - -- 对于有写入或更新数据的事务有一点性能影响。延迟上，在 Prewrite 阶段要并发写一条 p-binlog 成功后才可以提交事务，一般写 binlog 比 KV Prewrite 快，所以不会增加延迟。可以在 Pump 的监控面板看到写 binlog 的响应时间。 - -## Drainer 同步下游 TiDB/MySQL 的帐号需要哪些权限？ - -Drainer 同步帐号需要有如下权限： - -* Insert -* Update -* Delete -* Create -* Drop -* Alter -* Execute -* Index -* Select - -## Pump 磁盘快满了怎么办？ - -确认 GC 正常： - -- 确认 pump 监控面板 **gc_tso** 时间是否与配置一致。 - -如 gc 正常以下调整可以降低单个 pump 需要的空间大小： - -- 调整 pump **GC** 参数减少保留数据天数。 -- 添加 pump 结点。 - -## Drainer 同步中断怎么办？ - -使用以下 binlogctl 命令查看 Pump 状态是否正常，以及是否全部非 `offline` 状态的 Pump 都在正常运行。 - -{{< copyable "shell-regular" >}} - -```bash -binlogctl -cmd pumps -``` - -查看 Drainer 监控与日志是否有对应报错，根据具体问题进行处理。 - -## Drainer 同步下游 TiDB/MySQL 慢怎么办？ - -特别关注以下监控项： - -- 通过 Drainer 监控 **drainer event**，可以看到 Drainer 当前每秒同步 Insert/Update/Delete 事件到下游的速度。 -- 通过 Drainer 监控 **sql query time**，可以看到 Drainer 在下游执行 SQL 的响应时间。 - -同步慢的可能原因与解决方案： - -- 同步的数据库包含没有主键或者唯一索引的表，需要给表加上主键。 -- Drainer 与下游之间延迟大，可以调大 Drainer `worker-count` 参数（跨机房同步建议将 Drainer 部署在下游）。 -- 下游负载不高，可以尝试调大 Drainer `worker-count` 参数。 - -## 假如有一个 Pump crash 了会怎样？ - -Drainer 会因为获取不到这个 Pump 的数据没法同步数据到下游。如果这个 Pump 能恢复，Drainer 就能恢复同步。 - -如果 Pump 没法恢复，可采用以下方式进行处理： - -1. 使用 [binlogctl 将该 Pump 状态修改为 `offline`](/dev/reference/tidb-binlog/maintain.md)（丢失这个 Pump 的数据） -2. Drainer 获取到的数据会丢失这个 Pump 上的数据，下游跟上游数据会不一致，需要重新做全量 + 增量同步。具体步骤如下： - 1. 停止当前 Drainer。 - 2. 上游做全量备份。 - 3. 清理掉下游数据，包括 checkpoint 表 `tidb_binlog.checkpoint`。 - 4. 使用上游的全量备份恢复下游数据。 - 5. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 什么是 checkpoint？ - -Checkpoint 记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 -Drainer 日志 `["write save point"] [ts=411222863322546177]` 表示保存对应时间戳的 checkpoint。 - -下游类型不同，checkpoint 的保存方式也不同： - -- 下游 MySQL/TiDB 保存在 `tidb_binlog.checkpoint` 表。 -- 下游 kafka/file 保存在对应配置目录里的文件。 - -因为 kafka/file 的数据内容包含了 commit-ts，所以如果 checkpoint 丢失，可以消费下游最新的一条数据看写到下游数据的最新 commit-ts。 - -Drainer 启动的时候会去读取 checkpoint，如果读取不到，就会使用配置的 `initial-commit-ts` 做为初次启动开始的同步时间点。 - -## Drainer 机器发生故障，下游数据还在，如何在新机器上重新部署 Drainer？ - -如果下游数据还在，只要保证能从对应 checkpoint 接着同步即可。 - -假如 checkpoint 还在，可采用以下方式进行处理： - -1. 部署新的 Drainer 并启动即可（参考 checkpoint 介绍，Drainer 可以读取 checkpoint 接着同步）。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/dev/reference/tidb-binlog/maintain.md)。 - -假如 checkpoint 不在，可以如下处理： - -1. 获取之前 Drainer 的 checkpoint `commit-ts`，做为新部署 Drainer 的 `initial-commit-ts` 配置来部署新的 Drainer。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/dev/reference/tidb-binlog/maintain.md)。 - -## 如何用全量 + binlog 备份文件来恢复一个集群？ - -1. 清理集群数据并使用全部备份恢复数据。 -2. 使用 reparo 设置 `start-tso` = {全量备份文件快照时间戳+1}，`end-ts` = 0（或者指定时间点），恢复到备份文件最新的数据。 - -## 主从同步开启 `ignore-error` 触发 critical error 后如何重新部署？ - -TiDB 配置开启 `ignore-error` 写 binlog 失败后触发 critical error 告警，后续都不会再写 binlog，所以会有 binlog 数据丢失。如果要恢复同步，需要如下处理： - -1. 停止当前 Drainer。 -2. 重启触发 critical error 的 `tidb-server` 实例重新开始写 binlog（触发 critical error 后不会再写 binlog 到 pump）。 -3. 上游做全量备份。 -4. 清理掉下游数据包括 checkpoint 表 `tidb_binlog.checkpoint`。 -5. 使用上游的全量备份恢复下游。 -6. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 同步时出现上游数据库支持但是下游数据库执行会出错的 DDL，应该怎么办？ - -1. 查看 drainer.log 日志，查找 `exec failed` 找到 Drainer 退出前最后一条执行失败的 DDL。 -2. 将 DDL 改为下游兼容支持的版本，在下游数据库中手动执行。 -3. 查看 drainer.log 日志，查找执行失败的 DDL 语句，可以查询到该 DDL 的 commit-ts。 -4. 编辑 `drainer.toml` 配置文件，在 `ignore-txn-commit-ts` 项中添加该 commit-ts，重启 Drainer。 - -在绝大部分情况下，TiDB 和 MySQL 的语句都是兼容的。用户需要注意的是上下游的 `sql_mode` 应当保持一致。 - -## 在什么情况下暂停和下线 Pump/Drainer？ - -首先需要通过以下内容来了解 Pump/Drainer 的状态定义和启动、退出的流程。 - -暂停主要针对临时需要停止服务的场景，例如： - -- 版本升级：停止进程后使用新的 binary 启动服务。 -- 服务器维护：需要对服务器进行停机维护。退出进程，等维护完成后重启服务。 - -下线主要针对永久（或长时间）不再使用该服务的场景，例如： - -- Pump 缩容：不再需要那么多 Pump 服务了，所以下线部分服务。 -- 同步任务取消：不再需要将数据同步到某个下游，所以下线对应的 Drainer。 -- 服务器迁移：需要将服务迁移到其他服务器。下线服务，在新的服务器上重新部署。 - -## 可以通过哪些方式暂停 Pump/Drainer？ - -- 直接 kill 进程。 - - >**注意：** - > - > 不能使用 `kill -9` 命令，否则 Pump/Drainer 无法对信号进行处理。 - -- 如果 Pump/Drainer 运行在前台，则可以通过按下 Ctrl+C 来暂停。 -- 使用 binlogctl 的 `pause-pump` 或 `pause-drainer` 命令。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来下线 Pump/Drainer 服务吗？ - -不可以。使用 `update-pump`/`update-drainer` 命令会直接修改 PD 中保存的状态信息，并且不会通知 Pump/Drainer 做相应的操作。使用不当时，可能会干扰数据同步，某些情况下还可能会造成**数据不一致**的严重后果。例如： - -- 当 Pump 正常运行或者处于暂停状态时，如果使用 `update-pump` 将该 Pump 设置为 `offline`，那么 Drainer 会放弃获取处于 `offline` 状态的 Pump 的 binlog 数据，导致该 Pump 最新的 binlog 数据没有同步到 Drainer，造成上下游数据不一致。 -- 当 Drainer 正常运行时，使用 `update-drainer` 命令将该 Drainer 设置为 `offline`。如果这时启动一个 Pump 节点，Pump 只会通知 `online` 状态的 Drainer，导致该 Drainer 没有及时获取到该 Pump 的 binlog 数据，造成上下游数据不一致。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来暂停 Pump/Drainer 服务吗？ - -不可以。`update-pump`/`update-drainer` 命令直接修改 PD 中保存的状态信息。执行这个命令并不会通知 Pump/Drainer 做相应的操作，**而且使用不当会使数据同步中断，甚至造成数据丢失。** - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `paused`？ - -在某些异常情况下，Pump 没有正确维护自己的状态，实际上状态应该为 `paused`。这时可以使用 `update-pump` 对状态进行修正，例如： - -- Pump 异常退出（可能由 panic 或者误操作执行 `kill -9` 命令直接 kill 掉进程导致），Pump 保存在 PD 中的状态仍然为 `online`。如果暂时不需要重启 Pump 恢复服务，可以使用 `update-pump` 把该 Pump 状态设置为 `paused`，避免对 TiDB 写 binlog 和 Drainer 获取 binlog 造成干扰。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `paused`？ - -在某些异常情况下，Drainer 没有正确维护自己的状态，，对数据同步造成了影响，实际上状态应该为 `paused`。这时可以使用 `update-drainer` 对状态进行修正，例如： - -- Drainer 异常退出（出现 panic 直接退出进程，或者误操作执行 `kill -9` 命令直接 kill 掉进程），Drainer 保存在 PD 中的状态仍然为 `online`。当 Pump 启动时无法正常通知该 Drainer（报错 `notify drainer ...`），导致 Pump 无法正常运行。这个时候可以使用 `update-drainer` 将 Drainer 状态更新为 `paused`，再启动 Pump。 - -## 可以通过哪些方式下线 Pump/Drainer？ - -目前只可以使用 binlogctl 的 `offline-pump` 和 `offline-drainer` 命令来下线 Pump 和 Drainer。 - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `offline`? - -> **警告：** -> -> 仅在可以容忍 binlog **数据丢失、上下游数据不一致**或者确认不再需要使用该 Pump 存储的 binlog 数据的情况下，才能使用 `update-pump` 修改 Pump 状态为 `offline`。 - -可以使用 `update-pump` 修改 Pump 状态为 `offline` 的情况有： - -- 在某些情况下，Pump 异常退出进程，且无法恢复服务，同步就会中断。如果希望恢复同步且可以容忍部分 binlog 数据丢失，可以使用 `update-pump` 命令将该 Pump 状态设置为 `offline`，则 Drainer 会放弃拉取该 Pump 的 binlog 然后继续同步数据。 -- 有从历史任务遗留下来且不再使用的 Pump 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-pump` 将该 Pump 设置为 `offline`。 - -在其他情况下一定要使用 `offline-pump` 命令让 Pump 走正常的下线处理流程。 - -## Pump 进程已经退出，且状态为 `paused`，现在不想使用这个 Pump 节点了，能否用 binlogctl 的 `update-pump` 命令设置节点状态为 `offline`？ - -Pump 以 `paused` 状态退出进程时，不保证所有 binlog 数据被下游 Drainer 消费。所以这样做会有上下游数据不一致的风险。正确的做法是重新启动 Pump，然后使用 `offline-pump` 下线该 Pump。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `offline`？ - -- 有从历史任务遗留下来且不再使用的 Drainer 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-drainer` 将该 Drainer 设置为 `offline`。 - -## 可以使用 `change pump`、`change drainer` 等 SQL 操作来暂停或者下线 Pump/Drainer 服务吗？ - -目前还不支持。这种 SQL 操作会直接修改 PD 中保存的状态，在功能上等同于使用 binlogctl 的 `update-pump`、`update-drainer` 命令。如果需要暂停或者下线，仍然要使用 binlogctl。 diff --git a/dev/reference/tidb-binlog/overview.md b/dev/reference/tidb-binlog/overview.md deleted file mode 100644 index 3f8b4d8f0a46..000000000000 --- a/dev/reference/tidb-binlog/overview.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiDB Binlog 简介 -category: reference -aliases: ['/docs-cn/dev/reference/tidb-binlog-overview/','/docs-cn/dev/reference/tools/tidb-binlog/overview/'] ---- - -# TiDB Binlog 简介 - -TiDB Binlog 是一个用于收集 TiDB 的 binlog，并提供准实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景： - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog 整体架构 - -![TiDB Binlog 架构](/media/tidb_binlog_cluster_architecture.png) - -TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl 工具： - -### Pump - -[Pump](https://github.com/pingcap/tidb-binlog/blob/master/pump) 用于实时记录 TiDB 产生的 Binlog，并将 Binlog 按照事务的提交时间进行排序，再提供给 Drainer 进行消费。 - -### Drainer - -[Drainer](https://github.com/pingcap/tidb-binlog/tree/master/drainer) 从各个 Pump 中收集 Binlog 进行归并，再将 Binlog 转化成 SQL 或者指定格式的数据，最终同步到下游。 - -### binlogctl 工具 - -[`binlogctl`](https://github.com/pingcap/tidb-binlog/tree/master/binlogctl) 是一个 TiDB Binlog 配套的运维工具，具有如下功能： - -* 获取 TiDB 集群当前的 TSO -* 查看 Pump/Drainer 状态 -* 修改 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer - -## 主要特性 - -* 多个 Pump 形成一个集群，可以水平扩容。 -* TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。 -* Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。 -* Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。 -* Drainer 支持 [relay log](/dev/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。 - -## 注意事项 - -* 需要使用 TiDB v2.0.8-binlog、v2.1.0-rc.5 及以上版本，否则不兼容该版本的 TiDB Binlog。 - -* Drainer 支持将 Binlog 同步到 MySQL、TiDB、Kafka 或者本地文件。如果需要将 Binlog 同步到其他 Drainer 不支持的类型的系统中，可以设置 Drainer 将 Binlog 同步到 Kafka，然后根据 binlog slave protocol 进行定制处理，参考 [binlog slave client 用户文档](/dev/reference/tidb-binlog/binlog-slave-client.md)。 - -* 如果 TiDB Binlog 用于增量恢复，可以设置配置项 `db-type="file"`，Drainer 会将 binlog 转化为指定的 [proto buffer 格式](https://github.com/pingcap/tidb-binlog/blob/master/proto/binlog.proto)的数据，再写入到本地文件中。这样就可以使用 [Reparo](/dev/reference/tidb-binlog/reparo.md) 恢复增量数据。 - - 关于 `db-type` 的取值，应注意： - - - 如果 TiDB 版本 < 2.1.9，则 `db-type="pb"`。 - - 如果 TiDB 版本 > = 2.1.9，则 `db-type="file"` 或 `db-type="pb"`。 - -* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/dev/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。 diff --git a/dev/reference/tidb-binlog/tidb-binlog-local.md b/dev/reference/tidb-binlog/tidb-binlog-local.md deleted file mode 100644 index 5d34a452cc78..000000000000 --- a/dev/reference/tidb-binlog/tidb-binlog-local.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -title: TiDB Binlog Local 部署方案 -category: reference -aliases: ['/docs-cn/dev/reference/tools/tidb-binlog/tidb-binlog-local/'] ---- - -# TiDB Binlog Local 部署方案 - -## TiDB Binlog Local 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -* **数据同步**：同步 TiDB 集群数据到其他数据库。 -* **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复。 - -## TiDB Binlog Local 架构 - -下图为 TiDB Binlog Local的整体架构。 - -![TiDB Binlog 架构](/media/architecture.jpeg) - -TiDB Binlog Local 主要分为两个组件： - -- **Pump** 是一个守护进程，在每个 TiDB 的主机上后台运行。他的主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入磁盘文件 - -- **Drainer** 从各个 Pump 节点收集 Binlog，并按照在 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件 - -## TiDB Binlog Local 安装 - -### TiDB Binlog Local 下载 - -TiDB Binlog 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/dev/reference/tools/download.md)。 - -### TiDB Binlog Local 部署 - -#### 注意 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 方式的输出 binlog。 -* 手动部署时， 启动顺序为： Pump > TiDB，停止顺序为 TiDB > Pump - - 我们设置 TiDB 启动参数 binlog-socket 为对应的 Pump 的参数 socket 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* drainer 不支持对 ignore schemas（在过滤列表中的 schemas） 的 table 进行 rename DDL 操作 - -* 在已有的 TiDB 集群中启动 drainer，一般需要全量备份 并且获取 savepoint，然后导入全量备份，最后启动 drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 pump 运行 10 分钟左右后按顺序进行下面的操作 - - * 以 gen-savepoint model 运行 drainer 生成 drainer savepint 文件，`bin/drainer -gen-savepoint --data-dir= ${drainer_savepoint_dir} --pd-urls=${pd_urls}` - * 全量备份，例如 Mydumper 备份 tidb - * 全量导入备份到目标系统 - * 设置 savepoint 文件路径，然后启动 drainer，`bin/drainer --config=conf/drainer.toml --data-dir=${drainer_savepoint_dir}` - -* drainer 输出的 pb, 需要在配置文件设置下面的参数 - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -#### 使用 TiDB Ansible 部署 Pump (推荐) - -* 搭建全新的 TiDB Cluster，启动顺序 pd-server -> tikv-server -> pump -> tidb-server -> drainer - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook deploy.yml - * 执行 ansible-playbook start.yml - * drainer 目前需要手动部署 - -* 对已有的 TiDB Cluster 部署 binlog - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook rolling_update.yml --tags=tidb - * drainer 目前需要手动部署 - -#### 使用 Binary 部署 Pump - -1. PUMP 命令行参数说明 - - ``` - Usage of pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -advertise-addr string - pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -config string - 配置文件路径,如果你指定了配置文件，pump 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，pump 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - pump 数据存储位置路径 - -gc int - 日志最大保留天数 (默认 7)， 设置为 0 可永久保存 - -heartbeat-interval uint - pump 向 pd 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -socket string - unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - ``` - - 2. PUMP 配置文件 - - ```toml - # pump Configuration. - # pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - addr = "127.0.0.1:8250" - # pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - advertise-addr = "" - # binlog 最大保留天数 (默认 7)， 设置为 0 可永久保存 - gc = 7 - # pump 数据存储位置路径 - data-dir = "data.pump" - # pump 向 pd 发送心跳间隔 (单位 秒) - heartbeat-interval = 3 - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of drainer: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - drainer 提供服务的地址(默认 "127.0.0.1:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径, drainer 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 pd 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - -gen-savepoint - 如果设置为 true, 则只生成 drainer 的 savepoint meta 文件, 可以配合 Mydumper 使用 - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -txn-batch int - 输出到下游数据库一个事务的 sql 数量 (default 1) - ``` - -2. Drainer 配置文件 - - ```toml - # drainer Configuration. - - # drainer 提供服务的地址(默认 "127.0.0.1:8249") - addr = "127.0.0.1:8249" - - # 向 pd 查询在线 pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 sql 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - disable-dispatch = false - - # drainer 下游服务类型 (默认为 mysql) - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db priority over replicate-do-table if have same db name - # and we support regex expression , - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "127.0.0.1" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时,存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## TiDB Binlog Local 监控 - -这部分主要对 TiDB Binlog 的状态、性能做监控，通过 Prometheus + Grafana 展现 metrics 数据， - -### pump/drainer 配置 - -使用 ansible 部署的 pump 服务，已经在启动参数设置 metrics 。 - -drainer 启动时可以设置 `--metrics-addr` 和 `--metrics-interval` 两个参数，其中 metrics-addr 设为 Push Gateway 的地址，metrics-interval 为 push 的频率，单位为秒，默认值为15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号: admin 密码: admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 ( 注: Type 选 Prometheus，Url 为 Prometheus 地址，根据实际情况 添加/填写 ） - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/binlog.json)上传 -> 选择对应的 data source diff --git a/dev/reference/tidb-binlog/troubleshoot/binlog.md b/dev/reference/tidb-binlog/troubleshoot/binlog.md deleted file mode 100644 index 9e30262f815d..000000000000 --- a/dev/reference/tidb-binlog/troubleshoot/binlog.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: TiDB Binlog 故障诊断 -category: reference -aliases: ['/docs-cn/dev/how-to/troubleshoot/tidb-binlog/'] ---- - -# TiDB Binlog 故障诊断 - -本文总结了在 TiDB Binlog 的使用过程中遇到问题的诊断流程，并指引用户通过监控、状态、日志等信息查找相应的解决方案。 - -如果你在使用 TiDB Binlog 时出现了异常，请尝试以下方式排查问题： - -1. 查看各个监控指标是否异常，参见[TiDB Binlog 集群监控](/dev/reference/tidb-binlog/monitor.md)。 - -2. 使用 [binlogctl 工具](/dev/reference/tidb-binlog/maintain.md#binlogctl-工具)查看各个 Pump、Drainer 的状态是否有异常。 - -3. 查看 Pump、Drainer 日志中是否有 `ERROR`、`WARN`，并根据详细的日志信息初步判断问题原因。 - -通过以上方式定位到问题后，在 [FAQ](/dev/reference/tidb-binlog/faq.md) 以及 [常见错误及修复](/dev/reference/tidb-binlog/troubleshoot/error-handling.md) 中查找解决方案，如果没有查找到解决方案或者提供的解决方案无法解决问题，请提交 [issue](https://github.com/pingcap/tidb-binlog/issues) 或者联系相关技术支持人员。 diff --git a/dev/reference/tidb-binlog/troubleshoot/error-handling.md b/dev/reference/tidb-binlog/troubleshoot/error-handling.md deleted file mode 100644 index 44f3836f2e0e..000000000000 --- a/dev/reference/tidb-binlog/troubleshoot/error-handling.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB Binlog 常见错误修复 -category: reference ---- - -# TiDB Binlog 常见错误修复 - -本文档介绍 TiDB Binlog 中常见的错误以及修复方法。 - -## Drainer 同步数据到 Kafka 时报错 "kafka server: Message was too large, server rejected it to avoid allocation error" - -报错原因：如果在 TiDB 中执行了大事务，则生成的 binlog 数据会比较大，可能超过了 Kafka 的消息大小限制。 - -解决方法：需要调整 Kafka 的配置参数，如下所示。 - -``` -message.max.bytes=1073741824 -replica.fetch.max.bytes=1073741824 -fetch.message.max.bytes=1073741824 -``` - -## Pump 报错 "no space left on device" - -报错原因：本地磁盘空间不足，Pump 无法正常写 binlog 数据。 - -解决方法：需要清理磁盘空间，然后重启 Pump。 - -## Pump 启动时报错 "fail to notify all living drainer" - -报错原因：Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。 - -解决方法：可以使用 [binlogctl 工具](/dev/reference/tidb-binlog/maintain.md#binlogctl-工具)查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。 diff --git a/dev/reference/tidb-binlog/upgrade.md b/dev/reference/tidb-binlog/upgrade.md deleted file mode 100644 index 18a8d410c78a..000000000000 --- a/dev/reference/tidb-binlog/upgrade.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: TiDB Binlog 版本升级方法 -category: reference -aliases: ['/docs-cn/dev/how-to/upgrade/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/upgrade/'] ---- - -# TiDB Binlog 版本升级方法 - -如未特别指明，文中出现的 TiDB Binlog 均指最新的 [Cluster](/dev/reference/tidb-binlog/overview.md) 版本。 - -本文会分 Ansible 部署和手动部署两种情况介绍 TiDB Binlog 版本升级的方法，另外有一小节介绍如何从更早的不兼容版本（Kafka/Local 版本）升级到最新版本。 - -## Ansible 部署 - -本节适用于使用 [TiDB Ansible Playbook](https://github.com/pingcap/tidb-ansible) 部署的情况。 - -### 升级 Pump - -1. 将新版本的二进制文件 `pump` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook rolling_update.yml --tags=pump` 命令来滚动升级 Pump - -### 升级 Drainer - -1. 将新版本的二进制文件 `drainer` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook stop_drainer.yml --tags=drainer` 命令 -3. 执行 `ansible-playbook start_drainer.yml --tags=drainer` 命令 - -## 手动部署 - -### 升级 Pump - -对集群里的每个 Pump 逐一升级，确保集群中总有 Pump 可以接收 TiDB 发来的 Binlog。 - -1. 用新版本的 `pump` 替换原来的文件 -2. 重启 Pump 进程 - -### 升级 Drainer - -1. 用新版本的 `drainer` 替换原来的文件 -2. 重启 Drainer 进程 - -## 从 Kafka/Local 版本升级到 Cluster 版本 - -新版本的 TiDB（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）不兼容 [Kafka 版本](/dev/reference/tidb-binlog/tidb-binlog-kafka.md)以及 [Local 版本](/dev/reference/tidb-binlog/tidb-binlog-local.md)的 TiDB Binlog，集群升级到新版本后只能使用 Cluster 版本的 TiDB Binlog。如果在升级前已经使用了 Kafka／Local 版本的 TiDB Binlog，必须将其升级到 Cluster 版本。 - -TiDB Binlog 版本与 TiDB 版本的对应关系如下： - -| TiDB Binlog 版本 | TiDB 版本 | 说明 | -|---|---|---| -| Local | TiDB 1.0 及更低版本 || -| Kafka | TiDB 1.0 ~ TiDB 2.1 RC5 | TiDB 1.0 支持 local 版本和 Kafka 版本的 TiDB Binlog。 | -| Cluster | TiDB v2.0.8-binlog，TiDB 2.1 RC5 及更高版本 | TiDB v2.0.8-binlog 是一个支持 Cluster 版本 TiDB Binlog 的 2.0 特殊版本。 | - -### 升级流程 - -> **注意：** -> -> 如果能接受重新导全量数据，则可以直接废弃老版本，按 [TiDB Binlog 集群部署](/dev/reference/tidb-binlog/deploy.md)中的步骤重新部署。 - -如果想从原来的 checkpoint 继续同步，使用以下升级流程： - -1. 部署新版本 Pump。 -2. 暂停 TiDB 集群业务。 -3. 更新 TiDB 以及配置，写 Binlog 到新的 Pump Cluster。 -4. TiDB 集群重新接入业务。 -5. 确认老版本的 Drainer 已经将老版本的 Pump 的数据完全同步到下游。 - - 查询 Drainer 的 `status` 接口，示例命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - curl 'http://172.16.10.49:8249/status' - ``` - - ``` - {"PumpPos":{"172.16.10.49:8250":{"offset":32686}},"Synced": true ,"DepositWindow":{"Upper":398907800202772481,"Lower":398907799455662081}} - ``` - - 如果返回的 `Synced` 为 true，则可以认为 Binlog 数据已经全部同步到了下游。 - -6. 启动新版本 Drainer； -7. 下线老版本的 Pump、Drainer 以及依赖的 Kafka 和 ZookeSeper。 diff --git a/dev/reference/tispark.md b/dev/reference/tispark.md deleted file mode 100644 index 7be75ed13ec0..000000000000 --- a/dev/reference/tispark.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: TiSpark 用户指南 -category: reference ---- - -# TiSpark 用户指南 - -TiSpark 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。TiSpark 依赖于 TiKV 集群和 Placement Driver (PD)，也需要你搭建一个 Spark 集群。 - -本文简单介绍如何部署和使用 TiSpark。本文假设你对 Spark 有基本认知。你可以参阅 [Apache Spark 官网](https://spark.apache.org/docs/latest/index.html) 了解 Spark 的相关信息。 - -## 概述 - -TiSpark 是将 Spark SQL 直接运行在分布式存储引擎 TiKV 上的 OLAP 解决方案。其架构图如下： - -![TiSpark Architecture](/media/tispark-architecture.png) - -+ TiSpark 深度整合了 Spark Catalyst 引擎, 可以对计算提供精确的控制，使 Spark 能够高效的读取 TiKV 中的数据，提供索引支持以实现高速的点查。 -+ 通过多种计算下推减少 Spark SQL 需要处理的数据大小，以加速查询；利用 TiDB 的内建的统计信息选择更优的查询计划。 -+ 从数据集群的角度看，TiSpark + TiDB 可以让用户无需进行脆弱和难以维护的 ETL，直接在同一个平台进行事务和分析两种工作，简化了系统架构和运维。 -+ 除此之外，用户借助 TiSpark 项目可以在 TiDB 上使用 Spark 生态圈提供的多种工具进行数据处理。例如，使用 TiSpark 进行数据分析和 ETL；使用 TiKV 作为机器学习的数据源；借助调度系统产生定时报表等等。 - -## 环境准备 - -现有 TiSpark 2.x 版本支持 Spark 2.3.x 和 Spark 2.4.x。如果你希望使用 Spark 2.1.x 版本，需使用 TiSpark 1.x。 - -TiSpark 需要 JDK 1.8+ 以及 Scala 2.11（Spark2.0+ 默认 Scala 版本）。 - -TiSpark 可以在 YARN，Mesos，Standalone 等任意 Spark 模式下运行。 - -## 推荐配置 - -本部分描述了 TiKV 与 TiSpark 集群分开部署、Spark 与 TiSpark 集群独立部署，以及TiSpark 与 TiKV 集群混合部署的建议配置。 - -### TiKV 与 TiSpark 集群分开部署的配置 - -对于 TiKV 与 TiSpark 分开部署的场景，可以参考如下建议配置： - -+ 硬件配置建议 - - 普通场景可以参考 [TiDB 和 TiKV 硬件配置建议](/dev/how-to/deploy/hardware-recommendations.md)，但是如果是偏重分析的场景，可以将 TiKV 节点增加到至少 64G 内存。 - -### Spark 与 TiSpark 集群独立部署的配置 - -关于 Spark 的详细硬件推荐配置请参考[官网](https://spark.apache.org/docs/latest/hardware-provisioning.html)，如下是 TiSpark 所需环境的简单描述： - -Spark 推荐 32G 内存以上的配额。请在配置中预留 25% 的内存给操作系统。 - -Spark 推荐每台计算节点配备 CPU 累计 8 到 16 核以上。你可以初始设定分配所有 CPU 核给 Spark。 - -Spark 的具体配置方式也请参考[官方说明](https://spark.apache.org/docs/latest/spark-standalone.html)。以下为根据 `spark-env.sh` 配置的范例： - -{{< copyable "" >}} - -``` -SPARK_EXECUTOR_CORES: 5 -SPARK_EXECUTOR_MEMORY: 10g -SPARK_WORKER_CORES: 5 -SPARK_WORKER_MEMORY: 10g -``` - -在 `spark-defaults.conf` 中，增加如下配置： - -{{< copyable "" >}} - -``` -spark.tispark.pd.addresses $your_pd_servers -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -`your_pd_servers` 是用逗号分隔的 PD 地址，每个地址使用 `地址:端口` 的格式。 - -例如你有一组 PD 在`10.16.20.1`，`10.16.20.2`，`10.16.20.3`，那么 PD 配置格式是`10.16.20.1:2379,10.16.20.2:2379,10.16.20.3:2379`。 - -### TiSpark 与 TiKV 集群混合部署的配置 - -对于 TiKV 与 TiSpark 混合部署的场景，需在原有 TiKV 预留资源之外累加 Spark 所需部分，并分配 25% 的内存作为系统本身占用。 - -## 部署 TiSpark - -TiSpark 的 jar 包可以在 [TiSpark Releases 页面](https://github.com/pingcap/tispark/releases)下载对应版本的 jar 包并拷贝到合适的目录。 - -### 已有 Spark 集群的部署方式 - -如果在已有 Spark 集群上运行 TiSpark，无需重启集群。可以使用 Spark 的 `--jars` 参数将 TiSpark 作为依赖引入： - -{{< copyable "shell-regular" >}} - -```shell -spark-shell --jars $TISPARK_FOLDER/tispark-${name_with_version}.jar -``` - -### 没有 Spark 集群的部署方式 - -如果没有使用中的 Spark 集群，推荐使用 Saprk Standalone 方式部署。这里简单介绍下 Standalone 部署方式。如果遇到问题，可以去官网寻求[帮助](https://spark.apache.org/docs/latest/spark-standalone.html)；也欢迎在我们的 GitHub 上提 [issue](https://github.com/pingcap/tispark/issues/new)。 - -#### 下载安装包并安装 - -你可以在 [Download Apache Spark™ 页面](https://spark.apache.org/downloads.html)下载 Apache Spark。 - -对于 Standalone 模式且无需 Hadoop 支持，则选择 Spark 2.3.x 或者 Spark 2.4.x 且带有 Hadoop 依赖的 Pre-build with Apache Hadoop 2.x 任意版本。如有需要配合使用的 Hadoop 集群，则选择对应的 Hadoop 版本号。你也可以选择从源代码[自行构建](https://spark.apache.org/docs/latest/building-spark.html)以配合官方 Hadoop 2.x 之前的版本。 - -如果你已经有了 Spark 二进制文件，并且当前 PATH 为 SPARKPATH，需将 TiSpark jar 包拷贝到 `${SPARKPATH}/jars` 目录下。 - -#### 启动 Master - -在选中的 Spark Master 节点执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd $SPARKPATH -``` - -{{< copyable "shell-regular" >}} - -```bash -./sbin/start-master.sh -``` - -在这步完成以后，屏幕上会打印出一个 log 文件。检查 log 文件确认 Spark-Master 是否启动成功。你可以打开 查看集群信息（如果你没有改动 Spark-Master 默认 Port Numebr）。在启动 Spark-Slave 的时候，也可以通过这个面板来确认 Slave 是否已经加入集群。 - -#### 启动 Slave - -类似地，可以用如下命令启动 Spark-Slave 节点： - -{{< copyable "shell-regular" >}} - -```bash -./sbin/start-slave.sh spark://spark-master-hostname:7077 -``` - -命令返回以后，即可通过刚才的面板查看这个 Slave 是否已经正确地加入了 Spark 集群。在所有 Slave 节点重复刚才的命令。确认所有的 Slave 都可以正确连接 Master，这样你就拥有了一个 Standalone 模式的 Spark 集群。 - -#### Spark SQL shell 和 JDBC 服务器 - -当前版本的 TiSpark 可以直接使用 `spark-sql` 和 Spark 的 ThriftServer JDBC 服务器。 - -## 一个使用范例 - -假设你已经按照上述步骤成功启动了 TiSpark 集群，下面简单介绍如何使用 Spark SQL 来做 OLAP 分析。这里我们用名为 tpch 数据库中的 lineitem 表作为范例。 - -假设你的 PD 节点位于 192.168.1.100，端口为 2379，在 `$SPARK_HOME/conf/spark-defaults.conf` 加入： - -{{< copyable "" >}} - -``` -spark.tispark.pd.addresses 192.168.1.100:2379 -``` - -{{< copyable "" >}} - -``` -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -然后在 Spark-Shell 里像原生 Spark 一样输入下面的命令： - -{{< copyable "" >}} - -```scala -spark.sql("use tpch") -``` - -{{< copyable "" >}} - -```scala -spark.sql("select count(*) from lineitem").show -``` - -结果为： - -``` -+-------------+ -| Count (1) | -+-------------+ -| 600000000 | -+-------------+ -``` - -Spark SQL 交互 Shell 和原生 Spark 一致： - -{{< copyable "" >}} - -```shell -spark-sql> use tpch; -``` - -``` -Time taken: 0.015 seconds -``` - -{{< copyable "" >}} - -```shell -spark-sql> select count(*) from lineitem; -``` - -``` -2000 -Time taken: 0.673 seconds, Fetched 1 row(s) -``` - -SQuirreLSQL 和 hive-beeline 可以使用 JDBC 连接 Thrift 服务器。 -例如，使用 beeline 连接： - -{{< copyable "shell-regular" >}} - -```shell -./beeline -``` - -``` -Beeline version 1.2.2 by Apache Hive -``` - -{{< copyable "" >}} - -```shell -beeline> !connect jdbc:hive2://localhost:10000 -``` - -{{< copyable "" >}} - -```shell -1: jdbc:hive2://localhost:10000> use testdb; -``` - -``` -+---------+--+ -| Result | -+---------+--+ -+---------+--+ -No rows selected (0.013 seconds) -``` - -{{< copyable "sql" >}} - -```sql -select count(*) from account; -``` - -``` -+-----------+--+ -| count(1) | -+-----------+--+ -| 1000000 | -+-----------+--+ -1 row selected (1.97 seconds) -``` - -## 和 Hive 一起使用 TiSpark - -TiSpark 可以和 Hive 混合使用。 -在启动 Spark 之前，需要添加 HADOOP_CONF_DIR 环境变量指向 Hadoop 配置目录并且将 `hive-site.xml` 拷贝到 `$SPARK_HOME/conf` 目录下。 - -``` -val tisparkDF = spark.sql("select * from tispark_table").toDF -tisparkDF.write.saveAsTable("hive_table") // save table to hive -spark.sql("select * from hive_table a, tispark_table b where a.col1 = b.col1").show // join table across Hive and Tispark -``` - -## 通过 JDBC 将 DataFrame 写入 TiDB - -暂时 TiSpark 不支持直接将数据写入 TiDB 集群，但可以使用 Spark 原生的 JDBC 支持进行写入： - -```scala -import org.apache.spark.sql.execution.datasources.jdbc.JDBCOptions - -val customer = spark.sql("select * from customer limit 100000") -// you might repartition source to make it balance across nodes -// and increase concurrency -val df = customer.repartition(32) -df.write -.mode(saveMode = "append") -.format("jdbc") -.option("driver", "com.mysql.jdbc.Driver") - // replace host and port as your and be sure to use rewrite batch -.option("url", "jdbc:mysql://127.0.0.1:4000/test?rewriteBatchedStatements=true") -.option("useSSL", "false") -// As tested, 150 is good practice -.option(JDBCOptions.JDBC_BATCH_INSERT_SIZE, 150) -.option("dbtable", s"cust_test_select") // database name and table name here -.option("isolationLevel", "NONE") // recommended to set isolationLevel to NONE if you have a large DF to load. -.option("user", "root") // TiDB user here -.save() -``` - -推荐将 `isolationLevel` 设置为 `NONE`，否则单一大事务有可能造成 TiDB 服务器内存溢出。 - -## 统计信息 - -TiSpark 可以使用 TiDB 的统计信息： - -1. 选择代价最低的索引或扫表访问 -2. 估算数据大小以决定是否进行广播优化 - -如果希望使用统计信息支持，需要确保所涉及的表已经被分析。请阅读[这份文档](https://pingcap.com/docs-cn/dev/reference/performance/statistics/)了解如何进行表分析。 - -从 TiSpark 2.0 开始，统计信息将会默认被读取。 - -统计信息将在 Spark Driver 进行缓存，请确定 Driver 内存足够缓存统计信息。 -可以在`spark-defaults.conf`中开启或关闭统计信息读取： - -| Property Name | Default | Description -| -------- | -----: | :----: | -| spark.tispark.statistics.auto_load | true | 是否默认进行统计信息读取 | - -## TiSpark FAQ - -- Q. 是独立部署还是和现有 Spark／Hadoop 集群共用资源？ - - A. 可以利用现有 Spark 集群无需单独部署，但是如果现有集群繁忙，TiSpark 将无法达到理想速度。 - -- Q. 是否可以和 TiKV 混合部署？ - - A. 如果 TiDB 以及 TiKV 负载较高且运行关键的线上任务，请考虑单独部署 TiSpark；并且考虑使用不同的网卡保证 OLTP 的网络资源不被侵占而影响线上业务。如果线上业务要求不高或者机器负载不大，可以考虑与 TiKV 混合部署。 - -- Q. Spark 执行中报 warning：WARN ObjectStore:568 - Failed to get database - - A. Warning 忽略即可，原因是 Spark 找不到对应的 hive 库，因为这个库是在 TIKV 中，而不是在 hive 中。可以考虑调整 [log4j 日志](https://github.com/pingcap/tidb-docker-compose/blob/master/tispark/conf/log4j.properties#L43)，将该参数添加到 spark 下 conf 里 log4j 文件(如果后缀是 template 那先 mv 成后缀 properties)。 - -- Q. Spark 执行中报 java.sql.BatchUpdateException: Data Truncated - - A. 写入的数据长度超过了数据库定义的数据类型的长度，可以确认 target table 的字段长度，进行调整。 - -- Q. TiSpark 任务是否默认读取 Hive 的元数据？ - - A. TiSpark 通过读取 hive-site 里的 meta 来搜寻 hive 的库。如果搜寻不到，就通过读取 tidb meta 搜寻 tidb 库。如果不需要该行为，可不在 hive site 中配置 hive 的 meta。 - -- Q. TiSpark 执行 Spark 任务时报：Error：java.io.InvalidClassException: com.pingcap.tikv.region.TiRegion; local class incompatible: stream classdesc serialVersionUID ... - - A. 该报错日志中显示 serialVersionUID 冲突，说明存在不同版本的 class 和 TiRegion。因为 TiRegion 是 TiSpark 独有的，所以可能存在多个版本的 TiSpark 包。要解决该报错，请确保集群中各节点的 TiSpark 依赖包版本一致。 diff --git a/dev/reference/tools/br/br.md b/dev/reference/tools/br/br.md deleted file mode 100644 index 9454f93ee557..000000000000 --- a/dev/reference/tools/br/br.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -title: 使用 BR 进行备份与恢复 -summary: 了解如何使用 BR 工具进行集群数据备份和恢复。 -category: how-to -aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/br/'] ---- - -# 使用 BR 进行备份与恢复 - -Backup & Restore（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`mydumper`/`loader`](/dev/how-to/maintain/backup-and-restore/mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。 - -## 使用限制 - -- BR 只支持 TiDB v3.1 及以上版本。 -- 目前只支持在全新的集群上执行恢复操作。 -- BR 备份最好串行执行，否则不同备份任务之间会相互影响。 - -## 推荐部署配置 - -- 推荐 BR 部署在 PD 节点上。 -- 推荐使用一块高性能 SSD 网盘，挂载到 BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。 - -## 下载 Binary - -详见[下载链接](/dev/reference/tools/download.md#快速备份和恢复br)。 - -## 工作原理 - -BR 是分布式备份恢复的工具，它将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。 - -### 备份原理 - -BR 执行备份操作时，会先从 PD 获取到以下信息： - -- 当前的 TS 作为备份快照的时间点 -- 当前集群的 TiKV 节点信息 - -然后 BR 根据这些信息，在内部启动一个 TiDB 实例，获取对应 TS 的数据库或表信息，同时过滤掉系统库 (`information_schema`，`performance_schema`，`mysql`)。 - -此时根据备份子命令，会有两种备份逻辑： - -- 全量备份：BR 遍历全部库表，并且根据每一张表构建需要备份的 KV Range -- 单表备份：BR 根据该表构建需要备份的 KV Range - -最后，BR 将需要备份的 KV Range 收集后，构造完整的备份请求分发给集群内的 TiKV 节点。 - -该请求的主要结构如下： - -``` -BackupRequest{ - ClusterId, // 集群 ID - StartKey, // 备份起始点，startKey 会被备份 - EndKey, // 备份结束点，endKey 不会被备份 - EndVersion, // 备份快照时间点 - StorageBackend, // 备份文件存储地址 - RateLimit, // 备份速度 (MB/s) - Concurrency, // 执行备份操作的线程数（默认为 4） -} -``` - -TiKV 节点收到备份请求后，会遍历节点上所有的 Region Leader，找到和请求中 KV Range 有重叠范围的 Region，将该范围下的部分或者全部数据进行备份，在备份路径下生成对应的 SST 文件。 - -TiKV 节点在备份完对应 Region Leader 的数据后将元信息返回给 BR。BR 将这些元信息收集并存储进 `backupmeta` 文件中，等待恢复时使用。 - -如果执行命令时开启了 checksum，那么 BR 在最后会对备份的每一张表计算 checksum 用于校验。 - -#### 备份文件类型 - -备份路径下会生成以下两种类型文件： - -- SST 文件：存储 TiKV 备份下来的数据信息 -- `backupmeta` 文件：存储本次备份的元信息，包括备份文件数、备份文件的 Key 区间、备份文件大小和备份文件 Hash (sha256) 值 - -#### SST 文件命名格式 - -SST 文件以 `storeID_regionID_regionEpoch_keyHash_cf` 的格式命名。格式名的解释如下： - -- storeID：TiKV 节点编号 -- regionID：Region 编号 -- regionEpoch：Region 版本号 -- keyHash：Range startKey 的 Hash (sha256) 值，确保唯一性 -- cf：RocksDB 的 ColumnFamily（默认为 `default` 或 `write`） - -### 恢复原理 - -BR 执行恢复操作时，会按顺序执行以下任务： - -1. 解析备份路径下的 backupMeta 文件，根据解析出来的库表信息，在内部启动一个 TiDB 实例在新集群创建对应的库表。 - -2. 把解析出来的 SST 文件，根据表进行聚合。 - -3. 根据 SST 文件的 Key Range 进行预切分 Region，使得每个 Region 至少对应一个 SST 文件。 - -4. 遍历要恢复的每一张表，以及这个表对应的 SST 文件。 - -5. 找到该文件对应的 Region，发送下载文件的请求到对应的 TiKV 节点，并在下载成功后，发送加载请求。 - -TiKV 收到加载 SST 文件的请求后，利用 Raft 机制保证加载 SST 数据的强一致性。在加载成功后，下载下来的 SST 文件会被异步删除。 - -在执行完恢复操作后，BR 会对恢复后的数据进行 checksum 计算，用于和备份下来的数据进行对比。 - -![br-arch](/media/br-arch.png) - -## BR 命令行描述 - -一条 `br` 命令是由子命令、选项和参数组成的。子命令即不带 `-` 或者 `--` 的字符。选项即以 `-` 或者 `--` 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。 - -以下是一条完整的 `br` 命令行： - -`br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"` - -命令行各部分的解释如下： - -* `backup`：`br` 的子命令 -* `full`：`backup` 的子命令 -* `-s` 或 `--storage`：备份保存的路径 -* `"local:///tmp/backup"`：`-s` 的参数，保存的路径为本地磁盘的 `/tmp/backup` -* `--pd`：PD 服务地址 -* `"${PDIP}:2379"`：`--pd` 的参数 - -### 命令和子命令 - -BR 由多层命令组成。目前，BR 包含 `backup`、`restore` 和 `version` 三个子命令: - -* `br backup` 用于备份 TiDB 集群 -* `br restore` 用于恢复 TiDB 集群 -* `br version` 用于查看 BR 工具版本信息 - -以上三个子命令可能还包含这些子命令： - -* `full`：可用于备份或恢复全部数据。 -* `db`：可用于备份或恢复集群中的指定数据库。 -* `table`：可用于备份或恢复集群指定数据库中的单张表。 - -### 常用选项 - -* `--pd`：用于连接的选项，表示 PD 服务地址，例如 `"${PDIP}:2379"`。 -* `-h`/`--help`：获取所有命令和子命令的使用帮助。例如 `br backup --help`。 -* `--ca`：指定 PEM 格式的受信任 CA 的证书文件路径。 -* `--cert`：指定 PEM 格式的 SSL 证书文件路径。 -* `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。 -* `--status-addr`：BR 向 Prometheus 提供统计数据的监听地址。 - -## 备份集群数据 - -使用 `br backup` 命令来备份集群数据。可选择添加 `full` 或 `table` 子命令来指定备份的范围：全部集群数据或单张表的数据。 - -如果备份时间可能超过设定的 [`tikv_gc_life_time`](/dev/reference/garbage-collection/configuration.md#tikv_gc_life_time)（默认 `10m0s`），则需要将该参数调大。 - -例如，将 `tikv_gc_life_time` 调整为 `720h`： - -{{< copyable "sql" >}} - -```sql -mysql -h${TiDBIP} -P4000 -u${TIDB_USER} ${password_str} -Nse \ - "update mysql.tidb set variable_value='720h' where variable_name='tikv_gc_life_time'"; -``` - -### 备份全部集群数据 - -要备份全部集群数据，可使用 `br backup full` 命令。该命令的使用帮助可以通过 `br backup full -h` 或 `br backup full --help` 来获取。 - -用例：将所有集群数据备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backupfull.log -``` - -以上命令中，`--ratelimit` 和 `--concurrency` 选项限制了**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）和并发数上限。`--log-file` 选项指定把 BR 的 log 写到 `backupfull.log` 文件中。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。进度条效果如下： - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backupfull.log -Full Backup <---------/................................................> 17.12%. -``` - -### 备份单个数据库的数据 - -要备份集群中指定单个数据库的数据，可使用 `br backup db` 命令。同样可通过 `br backup db -h` 或 `br backup db --help` 来获取子命令 `db` 的使用帮助。 - -用例：将数据库 `test` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup db \ - --pd "${PDIP}:2379" \ - --db test \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backuptable.log -``` - -`db` 子命令的选项为 `--db`，用来指定数据库名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 - -### 备份单张表的数据 - -要备份集群中指定单张表的数据，可使用 `br backup table` 命令。同样可通过 `br backup table -h` 或 `br backup table --help` 来获取子命令 `table` 的使用帮助。 - -用例：将表 `test.usertable` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup table \ - --pd "${PDIP}:2379" \ - --db test \ - --table usertable \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backuptable.log -``` - -`table` 子命令有 `--db` 和 `--table` 两个选项，分别用来指定数据库名和表名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 - -## 恢复集群数据 - -使用 `br restore` 命令来恢复备份数据。可选择添加 `full`、`db` 或 `table` 子命令来指定恢复操作的范围：全部集群数据、某个数据库或某张数据表。 - -> **注意：** -> -> 如果备份的集群没有网络存储，在恢复前需要将所有备份的 SST 文件拷贝到各个 TiKV 节点上 `--storage` 指定的目录下。 - -### 恢复全部备份数据 - -要将全部备份数据恢复到集群中来，可使用 `br restore full` 命令。该命令的使用帮助可以通过 `br restore full -h` 或 `br restore full --help` 来获取。 - -用例：将 `/tmp/backup` 路径中的全部备份数据恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --concurrency 128 \ - --log-file restorefull.log -``` - -`--concurrency` 指定了该恢复任务内部的子任务的并发数。`--log-file` 选项指定把 BR 的 log 写到 `restorefull.log` 文件中。 - -恢复期间还有进度条会在终端中显示，当进度条前进到 100% 时，说明恢复已完成。在完成恢复后，BR 为了确保数据安全性，还会校验恢复数据。进度条效果如下： - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -Full Restore <---------/...............................................> 17.12%. -``` - -### 恢复单个数据库的数据 - -要将备份数据中的某个数据库恢复到集群中，可以使用 `br restore db` 命令。该命令的使用帮助可以通过 `br restore db -h` 或 `br restore db --help` 来获取。 - -用例：将 `/tmp/backup` 路径中备份数据中的某个数据库恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore db \ - --pd "${PDIP}:2379" \ - --db "test" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -以上命令中 `--db` 选项指定了需要恢复的数据库名字。其余选项的含义与[恢复全部备份数据](#恢复全部备份数据)相同。 - -### 恢复单张表的数据 - -要将备份数据中的某张数据表恢复到集群中，可以使用 `br restore table` 命令。该命令的使用帮助可通过 `br restore table -h` 或 `br restore table --help` 来获取。 - -用例：将 `/tmp/backup` 路径下的备份数据中的某个数据表恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore table \ - --pd "${PDIP}:2379" \ - --db "test" \ - --table "usertable" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -以上命令中 `--table` 选项指定了需要恢复的表名。其余选项的含义与[恢复某个数据库](#恢复某个数据库)相同。 - -## 最佳实践 - -- 推荐在 `-s` 指定的备份路径上挂载一个共享存储，例如 NFS。这样能方便收集和管理备份文件。 -- 在使用共享存储时，推荐使用高吞吐的存储硬件，因为存储的吞吐会限制备份或恢复的速度。 -- 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。 - -更多最佳实践内容，参见 [BR 备份与恢复场景示例](/dev/reference/tools/br/use-cases.md)。 - -## 备份和恢复示例 - -本示例展示如何对已有的集群数据进行备份和恢复操作。可以根据机器性能、配置、数据规模来预估一下备份和恢复的性能。 - -### 数据规模和机器配置 - -假设对 TiKV 集群中的 10 张表进行备份和恢复。每张表有 500 万行数据，数据总量为 35 GB。 - -```sql -MySQL [sbtest]> show tables; -+------------------+ -| Tables_in_sbtest | -+------------------+ -| sbtest1 | -| sbtest10 | -| sbtest2 | -| sbtest3 | -| sbtest4 | -| sbtest5 | -| sbtest6 | -| sbtest7 | -| sbtest8 | -| sbtest9 | -+------------------+ - -MySQL [sbtest]> select count(*) from sbtest1; -+----------+ -| count(*) | -+----------+ -| 5000000 | -+----------+ -1 row in set (1.04 sec) -``` - -表结构如下： - -```sql -CREATE TABLE `sbtest1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `k` int(11) NOT NULL DEFAULT '0', - `c` char(120) NOT NULL DEFAULT '', - `pad` char(60) NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=5138499 -``` - -示例假设有 4 个 TiKV 节点，每个节点配置如下： - -| CPU | 内存 | 磁盘 | 副本数 | -| :--- | :--- | :--- | :--- | -| 16 核 | 32 GB | SSD | 3 | - -### 备份示例 - -- 备份前需确认已将 GC 时间调长，确保备份期间不会因为数据丢失导致中断 -- 备份前需确认 TiDB 集群没有执行 DDL 操作 - -执行以下命令对集群中的全部数据进行备份： - -{{< copyable "shell-regular" >}} - -``` -bin/br backup full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file backup.log -``` - -``` -[INFO] [collector.go:165] ["Full backup summary: total backup ranges: 2, total success: 2, total failed: 0, total take(s): 0.00, total kv: 4, total size(Byte): 133, avg speed(Byte/s): 27293.78"] ["backup total regions"=2] ["backup checksum"=1.640969ms] ["backup fast checksum"=227.885µs] -``` - -### 恢复示例 - -恢复操作前，需确认待恢复的 TiKV 集群是全新的集群。 - -执行以下命令对全部数据进行恢复： - -{{< copyable "shell-regular" >}} - -``` -bin/br restore full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file restore.log -``` - -``` -[INFO] [collector.go:165] ["Full Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 0.26, total kv: 20000, total size(MB): 10.98, avg speed(MB/s): 41.95"] ["restore files"=3] ["restore ranges"=2] ["split region"=0.562369381s] ["restore checksum"=36.072769ms] -``` diff --git a/dev/reference/tools/br/use-cases.md b/dev/reference/tools/br/use-cases.md deleted file mode 100644 index fff5ac6d99f7..000000000000 --- a/dev/reference/tools/br/use-cases.md +++ /dev/null @@ -1,415 +0,0 @@ ---- -title: BR 备份与恢复场景示例 -category: reference -aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/br-best-practices/','/docs-cn/dev/reference/tools/br/br-best-practices/'] ---- - -# BR 备份与恢复场景示例 - -[Backup & Restore](/dev/reference/tools/br/br.md)（下文简称 BR）一款分布式的快速备份和恢复工具。本文展示了[四种备份和恢复场景](#使用场景)下的 BR 操作过程，以帮助读者达到以下目标： - -* 正确使用网络盘或本地盘进行备份或恢复 -* 通过相关监控指标了解备份或恢复的状态 -* 了解在备份或恢复时如何调优性能 -* 处理备份时可能发生的异常 - -> **注意：** -> -> 使用 BR 时应注意[使用限制](/dev/reference/tools/br/br.md#使用限制)。 - -## 目标读者 - -读者需要对 TiDB 和 TiKV 有一定的了解。在阅读本文前，推荐先阅读[使用 BR 进行备份与恢复](/dev/reference/tools/br/br.md)。 - -## 环境准备 - -本部分介绍推荐的 TiDB 的部署方式、示例中的集群版本、TiKV 集群硬件信息和集群配置。读者可根据自己的硬件和配置来预估备份恢复的性能。 - -### 部署方式 - -推荐使用 [TiDB Ansible](/dev/how-to/deploy/orchestrated/ansible.md) 部署 TiDB 集群，再下载 [TiDB Toolkit](/dev/reference/tools/download.md#快速备份和恢复br) 获取 BR 应用。 - -### 集群版本 - -* TiKV: v3.1.0-beta.1 -* PD: v3.1.0-beta.1 -* br: v3.1.0-beta.1 - -### TiKV 集群硬件信息 - -* 操作系统：CentOS Linux release 7.6.1810 (Core) -* CPU：16-Core Common KVM processor -* RAM：32GB -* 硬盘：500G SSD * 2 -* 网卡：10000MB/s - -### 配置 - -BR 可以直接将命令下发到 TiKV 集群来执行备份和恢复，不依赖 TiDB server 组件，因此无需对 TiDB server 进行配置。 - -* TiKV: 默认配置 -* PD : 默认配置 - -## 使用场景 - -本文描述以下四种使用场景： - -* [将单表数据备份到网络盘（推荐）](#将单表数据备份到网络盘推荐) -* [从网络磁盘恢复备份数据（推荐）](#从网络磁盘恢复备份数据推荐) -* [将单表数据备份到本地磁盘](#将单表数据备份到本地磁盘) -* [从本地磁盘恢复备份数据](#从本地磁盘恢复备份数据) - -推荐使用网络盘来进行备份和恢复操作，这样可以省去收集备份数据文件的繁琐步骤。尤其在 TiKV 集群规模较大的情况下，使用网络盘可以大幅提升操作效率。 - -> **注意：** -> -> 在进行备份或恢复操作前，需要先进行备份或恢复的准备工作。 - -### 备份前的准备工作 - -`br backup` 命令的详细使用方法请参考 [BR 命令行描述](/dev/reference/tools/br/br.md#br-命令行描述)。 - -1. 运行 `br backup` 命令前，查询 TiDB 集群的 [`tikv_gc_life_time`](/dev/reference/garbage-collection/configuration.md#tikv_gc_life_time) 配置项的值，并使用 MySQL 客户端将该项调整至合适的值，确保备份期间不会发生 [Garbage Collection](/dev/reference/garbage-collection/overview.md) (GC)。 - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - UPDATE mysql.tidb SET VARIABLE_VALUE = '720h' WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 在备份完成后，将该参数调回原来的值。 - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -### 恢复前的准备工作 - -`br restore` 命令的详细使用方法请参考 [BR 命令行描述](/dev/reference/tools/br/br.md#br-命令行描述)。 - -> **注意：** -> -> 运行 `br restore` 前检查新集群确保没有同名的表。 - -### 将单表数据备份到网络盘（推荐） - -使用 `br backup` 命令，将单表数据 `--db batchmark --table order_line` 备份到指定的网络盘路径 `local:///br_data` 下。 - -#### 前置要求 - -* 配置一台高性能 SSD 硬盘主机为 NFS server 存储数据。其他所有 BR 节点和 TiKV 节点为 NFS client，挂载相同的路径（例如 `/br_data`）到 NFS server 上以访问 NFS server。 -* NFS server 和 NFS client 间的数据传输速率至少要达到备份集群的 `TiKV 实例数 * 150MB/s`。否则网络 I/O 有可能成为性能瓶颈。 - -#### 部署拓扑 - -部署拓扑如下图所示： - -![img](/media/br/backup-nfs-deploy.png) - -#### 运行备份 - -备份操作前，在 TiDB 中使用 `admin checksum table order_line` 命令获得备份目标表 `--db batchmark --table order_line` 的统计信息。统计信息示例如下： - -![img](/media/br/total-data.png) - -运行 BR 备份命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br backup table --db batchmark --table order_line -s local:///br_data --pd 172.16.5.198:2379 --log-file backup-nfs.log -``` - -#### 备份过程中的运行指标 - -在 BR 备份过程中，需关注以下监控面版中的运行指标来了解备份的状态。 - -**Backup CPU Utilization**：参与备份的 TiKV 节点（例如 backup-worker 和 backup-endpoint）的 CPU 使用率。 - -![img](/media/br/backup-cpu.png) - -**IO Utilization**：参与备份的 TiKV 节点的 I/O 使用率。 - -![img](/media/br/backup-io.png) - -**BackupSST Generation Throughput**：参与备份的 TiKV 节点生成 backupSST 文件的吞吐。正常时单个 TiKV 节点的吞吐在 150MB/s 左右。 - -![img](/media/br/backup-throughput.png) - -**One Backup Range Duration**：备份一个 range 的操作耗时，包括扫描耗时 (scan KV) 和保存耗时（保存为 backupSST 文件）。 - -![img](/media/br/backup-range-duration.png) - -**One Backup Subtask Duration**： 一次备份任务会被拆分成多个子任务。该监控项显示子任务的耗时。 - -> **注意：** -> -> * 虽然本次任务是备份单表，但因为表中有 3 个索引，所以正常会拆分成 4 个子任务。 -> * 下图中有 13 个点，说明有 9 次 (13-4) 重试。备份过程中可能发生 Region 调度行为，少量重试是正常的。 - -![img](/media/br/backup-subtask-duration.png) - -**Backup Errors**：备份过程中的错误。正常时无错误。即使出现少量错误，备份操作也有重试机制，可能会导致备份时间增加，但不会影响备份的正确性。 - -![img](/media/br/backup-errors.png) - -**Checksum Request Duration**：对备份集群执行 admin checksum 的耗时统计。 - -![img](/media/br/checksum-duration.png) - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从路径下存放的日志中可以获取此次备份的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table backup summary: total backup ranges: 4, total success: 4, total failed: 0, total take(s): 986.43, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 358.09"] ["backup total regions"=7196] ["backup checksum"=6m28.291772955s] ["backup fast checksum"=24.950298ms] -``` - -以上日志信息中包含以下内容： - -* 备份耗时：`total take(s): 986.43` -* 数据大小：`total size(MB): 353227.18` -* 备份吞吐：`avg speed(MB/s): 358.09` -* 校验耗时：`take=6m28.29s` - -通过以上数据可以计算得到单个 TiKV 实例的吞吐为：`avg speed(MB/s)`/`tikv_count` = `89`。 - -#### 性能调优 - -如果 TiKV 的资源使用没有出现明显的瓶颈（例如[备份过程中的运行指标](#备份过程中的运行指标)中的 **Backup CPU Utilization** 最高为 `1500%` 左右，**IO Utilization** 普遍低于 `30%`），可以尝试调大 `--concurrency` 参数以进行性能调优。该方法不适用于存在许多小表的场景。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -bin/br backup table --db batchmark --table order_line -s local:///br_data/ --pd 172.16.5.198:2379 --log-file backup-nfs.log --concurrency 16 -``` - -![img](/media/br/backup-diff.png) - -![img](/media/br/backup-diff2.png) - -性能调优后的结果如下所示（保持数据大小不变）： - -* 备份耗时：`total take(s)` 从 `986.43` 减少到 `535.53` -* 数据大小：`total size(MB): 353227.18` -* 备份吞吐：`avg speed(MB/s)` 从 `358.09` 提升到 `659.59` -* 单个 TiKV 实例的吞吐：`avg speed(MB/s)/tikv_count` 从 `89` 提升到 `164.89` - -### 从网络磁盘恢复备份数据（推荐） - -使用 `br restore` 命令，将一份完整的备份数据恢复到一个离线集群。暂不支持恢复到在线集群。 - -#### 前置要求 - -无 - -#### 部署拓扑 - -部署拓扑如下图所示： - -![img](/media/br/restore-nfs-deploy.png) - -#### 运行恢复 - -运行 `br restore` 命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br restore table --db batchmark --table order_line -s local:///br_data --pd 172.16.5.198:2379 --log-file restore-nfs.log -``` - -#### 恢复过程中的运行指标 - -在 BR 恢复过程中，需关注以下监控面版中的运行指标来了解恢复的状态。 - -**CPU Utilization**：参与恢复的 TiKV 节点 CPU 使用率。 - -![img](/media/br/restore-cpu.png) - -**IO Utilization**：参与恢复的 TiKV 节点的 I/O 使用率。 - -![img](/media/br/restore-io.png) - -**Region** 分布：Region 分布越均匀，说明恢复资源利用越充分。 - -![img](/media/br/restore-region.png) - -**Process SST Duration**：处理 SST 文件的延迟。恢复一张表时时，如果 `tableID` 发生了变化，需要对 `tableID` 进行 `rewrite`，否则会进行 `rename`。通常 `rewrite` 延迟要高于 `rename` 的延迟。 - -![img](/media/br/restore-process-sst.png) - -**DownLoad SST Throughput**：从 External Storage 下载 SST 文件的吞吐。 - -![img](/media/br/restore-download-sst.png) - -**Restore Errors**：恢复过程中的错误。 - -![img](/media/br/restore-errors.png) - -**Checksum Request duration**：对恢复集群执行 admin checksum 的耗时统计，会比备份时的 checksum 延迟高。 - -![img](/media/br/restore-checksum.png) - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从路径下存放的日志中可以获取此次恢复的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 961.37, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 367.42"] ["restore files"=9263] ["restore ranges"=6888] ["split region"=49.049182743s] ["restore checksum"=6m34.879439498s] -``` - -以上日志信息中包含以下内容： - -* 恢复耗时：`total take(s):961.37` -* 数据大小：`total size(MB): 353227.18` -* 恢复吞吐：`avg speed(MB/s): 367.42` -* `Region Split` 耗时：`take=49.049182743s` -* 校验耗时：`take=6m34.879439498s` - -根据上表数据可以计算得到： - -* 单个 TiKV 吞吐：`avg speed(MB/s)`/`tikv_count` = `91.8` -* 单个 TiKV 平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` = `87.4` - -#### 性能调优 - -如果 TiKV 资源使用没有明显的瓶颈，可以尝试调大 `--concurrency` 参数（默认为 `128`），示例如下： - -{{< copyable "shell-regular" >}} - -```shell -bin/br restore table --db batchmark --table order_line -s local:///br_data/ --pd 172.16.5.198:2379 --log-file restore-concurrency.log --concurrency 1024 -``` - -性能调优后的结果如下表所示（保持数据大小不变）： - -* 恢复耗时：`total take(s)` 从 `961.37` 减少到 `443.49` -* 恢复吞吐：`avg speed(MB/s)` 从 `367.42` 提升到 `796.47` -* 单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` 从 `91.8` 提升到 `199.1` -* 单个 TiKV 实例的平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` 从 `87.4` 提升到 `162.3` - -### 将单表数据备份到本地磁盘 - -使用 `br backup 命令`，将单表数据 `--db batchmark --table order_line` 备份到指定的本地磁盘路径 `local:///home/tidb/backup_local` 下。 - -#### 前置要求 - -* 各个 TiKV 节点有单独的磁盘用来存放 backupSST 数据。 -* `backup_endpoint` 节点有单独的磁盘用来存放备份的 `backupmeta` 文件。 -* TiKV 和 `backup_endpoint` 节点需要有相同的备份目录，例如 `/home/tidb/backup_local`。 - -#### 部署拓扑 - -![img](/media/br/backup-local-deploy.png) - -#### 运行备份 - -备份前在 TiDB 里通过 `admin checksum table order_line` 获得备份的目标表 `--db batchmark --table order_line` 的统计信息。统计信息示例如下： - -![img](/media/br/total-data.png) - -运行 `br backup` 命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br backup table --db batchmark --table order_line -s local:///home/tidb/backup_local/ --pd 172.16.5.198:2379 --log-file backup_local.log -``` - -运行备份时，参考[备份过程中的运行指标](#备份过程中的运行指标)对相关指标进行监控，以了解备份状态。 - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从该路径下存放的日志获取此次备份的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table backup summary: total backup ranges: 4, total success: 4, total failed: 0, total take(s): 551.31, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 640.71"] ["backup total regions"=6795] ["backup checksum"=6m33.962719217s] ["backup fast checksum"=22.995552ms] -``` - -以上日志信息中包含以下内容： - -* 备份耗时：`total take(s): 551.31` -* 数据大小：`total size(MB): 353227.18` -* 备份吞吐：`avg speed(MB/s): 640.71` -* 校验耗时：`take=6m33.962719217s` - -根据上表数据可以计算得到单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` = `160`。 - -### 从本地磁盘恢复备份数据 - -使用 `br restore` 命令，将一份完整的备份数据恢复到一个离线集群。暂不支持恢复到在线集群。 - -#### 前置要求 - -* 集群中没有与备份数据相同的库表。目前 BR 不支持 table route。 -* 集群中各个 TiKV 节点有单独的磁盘用来存放要恢复的 backupSST 数据。 -* `restore_endpoint` 节点有单独的磁盘用来存放要恢复的 `backupmeta` 文件。 -* 集群中 TiKV 和 `restore_endpoint` 节点需要有相同的备份目录，例如 `/home/tidb/backup_local/`。 - -如果备份数据存放在本地磁盘，那么需要执行以下的步骤： - -1. 汇总所有 backupSST 文件到一个统一的目录下。 -2. 将汇总后的 backupSST 文件到复制到集群的所有 TiKV 节点下。 -3. 将 `backupmeta` 文件复制到到 `restore endpoint` 节点下。 - -#### 部署拓扑 - -![img](/media/br/restore-local-deploy.png) - -#### 运行恢复 - -运行 `br restore` 命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br restore table --db batchmark --table order_line -s local:///home/tidb/backup_local/ --pd 172.16.5.198:2379 --log-file restore_local.log -``` - -运行恢复时，参考[恢复过程中的运行指标](#恢复过程中的运行指标)对相关指标进行监控，以了解恢复状态。 - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从该日志中可以获取此次恢复的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 908.42, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 388.84"] ["restore files"=9263] ["restore ranges"=6888] ["split region"=58.7885518s] ["restore checksum"=6m19.349067937s] -``` - -以上日志信息中包含以下内容： - -* 恢复耗时：`total take(s): 908.42` -* 数据大小：`total size(MB): 353227.18` -* 恢复吞吐：`avg speed(MB/s): 388.84` -* `Region Split` 耗时：`take=58.7885518s` -* 校验耗时：`take=6m19.349067937s` - -根据上表数据可以计算得到： - -* 单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` = `97.2` -* 单个 TiKV 实例的平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` = `92.4` - -### 异常处理 - -本部分介绍如何处理备份过程中出现的常见错误。 - -#### 备份日志中出现 `key locked Error` - -日志中的错误消息：`log - ["backup occur kv error"][error="{\"KvError\":{\"locked\":` - -如果在备份过程中遇到 key 被锁住，目前 BR 会尝试清锁。少量报错不会影响备份的正确性。 - -#### 备份失败 - -日志中的错误消息：`log - Error: msg:"Io(Custom { kind: AlreadyExists, error: \"[5_5359_42_123_default.sst] is already exists in /dir/backup_local/\" })"` - -若备份失败并出现以上错误消息，采取以下其中一种操作后再重新备份： - -* 更换备份数据目录。例如将 `/dir/backup-2020-01-01/` 改为 `/dir/backup_local/`。 -* 删除所有 TiKV 和 BR 节点的备份目录。 diff --git a/dev/reference/tools/data-migration/cluster-operations.md b/dev/reference/tools/data-migration/cluster-operations.md deleted file mode 100644 index 6694d731a1c1..000000000000 --- a/dev/reference/tools/data-migration/cluster-operations.md +++ /dev/null @@ -1,489 +0,0 @@ ---- -title: DM 集群操作 -category: reference ---- - -# DM 集群操作 - -本文介绍 DM 集群操作以及使用 DM-Ansible 管理 DM 集群时需要注意的事项。 - -## 启动集群 - -运行以下命令以启动整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook start.yml -``` - -## 下线集群 - -运行以下命令以下线整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -## 重启集群组件 - -在以下情况下，需要更新 DM 集群组件： - -- 您想要[更新组件版本](#更新组件版本)。 -- 发生了严重的错误，您需要重启组件完成临时恢复。 -- DM 集群所在的机器由于某种原因重启。 - -### 重启注意事项 - -该部分描述重启 DM 各组件时需要了解的事项。 - -#### DM-worker 重启事项 - -**全量数据导入过程中：** - -对于全量数据导入时的 SQL 文件，DM 使用下游数据库记录断点信息，DM-worker 会在本地 meta 文件记录子任务信息。DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -**增量数据同步过程中：** - -对于增量数据导入过程中的 binlog，DM 使用下游数据库记录断点信息，并会在同步任务开始或恢复后的第一个五分钟之内开启安全模式。 - -+ 未启用 sharding DDL 同步 - - 如果 DM-worker 上运行的任务未启用 sharding DDL 同步功能，DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -+ 已启用 sharding DDL 同步 - - - DM 同步 sharding DDL 语句时，如果 DM-worker 成功执行（或跳过）sharding DDL 的 binlog event，与 DM-worker 中的 sharding DDL 语句相关的所有表的断点信息都会被更新至 DDL 语句对应的 binlog event 之后的位置。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步开始前或完成后，DM-worker 会根据断点信息和本地记录的子任务信息自动恢复数据同步。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步过程中，可能会出现作为 DDL lock owner 的 DM-worker 实例已执行了 DDL 语句并成功变更了下游数据库表结构，但其他 DM-worker 实例重启而无法跳过 DDL 语句也无法更新断点的情况。 - - 此时 DM 会再次尝试同步这些未跳过执行的 DDL 语句。然而，由于未重启的 DM-worker 实例已经执行到了此 DDL 对应的 binlog event 之后，重启的 DM-worker 实例会被阻滞在重启前 DDL binlog event 对应的位置。 - - 要解决这个问题，请按照[手动处理 Sharding DDL Lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#场景二unlock-过程中部分-dm-worker-重启) 中描述的步骤操作。 - -**总结**：尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -#### DM-master 重启事项 - -由 DM-master 维护的信息包括以下两种。重启 DM-master 不会持久化保存这些信息的相关数据。 - -- 任务信息 -- Sharding DDL lock 信息 - -DM-master 重启时会自动向每个 DM-worker 实例请求任务信息，重建任务与 DM-worker 之间的对应关系，并从每个 DM-worker 实例获取 sharding DDL 信息。这样，就可以准确重建相应的 DDL lock，也可以自动解除 sharding DDL lock。 - -### 重启 DM-worker - -> **注意：** -> -> 尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -使用以下两种方法中任一种重启 DM-worker 组件： - -- 对 DM-worker 执行滚动升级。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - -- 先停止 DM-worker，然后重启。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker && - ansible-playbook start.yml --tags=dm-worker - ``` - -### 重启 DM-master - -在以下两种方法中任选一种，重启 DM-master 组件： - -- 对 DM-master 执行滚动升级。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -- 停止 DM-master，然后重启。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-master && - ansible-playbook start.yml --tags=dm-master - ``` - -## 更新组件版本 - -1. 下载 DM 二进制文件。 - - 1. 从 `downloads` 目录删除已有文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - rm -rf downloads - ``` - - 2. 用 Playbook 下载 inventory.ini 文件中指定版本的最新 DM 二进制文件。这会自动替换 `/home/tidb/dm-ansible/resource/bin/` 中已有文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -2. 使用 Ansible 执行滚动升级。 - - 1. 对 DM-worker 实例执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - - 2. 对 DM-master 实例执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - - 3. 升级 dmctl： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dmctl - ``` - - 4. 对 DM-worker， DM-master， 以及 dmctl 整体执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -## 创建 DM-worker 实例 - -假设您想要在机器 `172.16.10.74` 上创建一个名为 `dm_worker3` 的 DM-worker 实例，按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/dev/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 用户登录至中控机，并将 `172.16.10.74` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.74 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.74`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.74` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 修改 `inventory.ini` 文件，创建新 DM-worker 实例 `dm_worker3`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -3. 部署新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-worker -l dm_worker3 - ``` - -4. 启用新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-worker -l dm_worker3 - ``` - -5. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -6. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 下线 DM-worker 实例 - -假设您想要下线的 DM-worker 实例为 `dm_worker3`。按以下步骤操作： - -1. 关闭您想要下线的 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker -l dm_worker3 - ``` - -2. 修改 `inventory.ini` 文件，注释或删除 `dm_worker3` 实例所在行。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - # dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 # Comment or delete this line - ``` - -3. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -4. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 替换/迁移 DM-master 实例 - -假设机器 `172.16.10.71` 需要进行维护或者已崩溃，需要将 DM-master 实例从 `172.16.10.71` 迁移至 `172.16.10.80`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/dev/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.80` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.80 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.80`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.80` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 关闭待替换的 DM-master 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-master - ``` - -3. 修改 `inventory.ini` 文件。注释或删除待替换实例所在行，同时为新 DM-master 实例添加相关信息。 - - ```ini - [dm_master_servers] - # dm_master ansible_host=172.16.10.71 - dm_master ansible_host=172.16.10.80 - ``` - -4. 部署新 DM-master 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-master - ``` - -5. 启用新 DM-master 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-master - ``` - -6. 更新 dmctl 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dmctl - ``` - -## 替换/迁移 DM-worker 实例 - -假设机器 `172.16.10.72` 需要进行维护或者已崩溃，您需要将 `dm_worker1` 实例从 `172.16.10.72` 迁移至 `172.16.10.75`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/dev/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.75` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.75 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.85`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.75` 上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 下线待替换 DM-worker 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker -l dm_worker1 - ``` - -3. 修改 `inventory.ini` 文件，为新 DM-worker 实例添加相关信息。 - - 修改 `inventory.ini` 文件。注释或删除旧 `dm_worker1` 实例所在行；同时为新 `dm_worker1` 实例添加相关信息。 - - 如果希望从不同的 binlog position 或 GTID Sets 拉取 relay log，则也需要更新对应的 `{relay_binlog_name}` 或 `{relay_binlog_gtid}`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.75 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - # dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -4. 部署新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-worker -l dm_worker1 - ``` - -5. 迁移 relay log 数据。 - - - 如果待替换 DM-worker 实例所在机器仍能访问，则可直接将该实例的 `{dm_worker_relay_dir}` 目录下的所有数据复制到新 DM-worker 实例的对应目录。 - - - 如果待替换 DM-worker 实例所在机器已无法访问，可能需在第 9 步中手动恢复 relay log 目录等信息。 - -6. 启动新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-worker -l dm_worker1 - ``` - -7. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -8. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -9. 启动并验证数据迁移任务。 - - 使用 `start-task` 命令启动数据迁移任务，如果任务运行正常，则表示 DM-worker 迁移顺利完成；如果报类似如下错误，则需要对 relay log 目录进行手动修复。 - - ```log - fail to initial unit Sync of subtask test-task : UUID suffix 000002 with UUIDs [1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001] not found - ``` - - 如果待替换 DM-worker 所连接的上游 MySQL 已发生过切换，则会产生如上错误。此时可通过如下步骤手动修复： - - 1. 使用 `stop-task` 命令停止数据迁移任务。 - - 2. 通过 `$ ansible-playbook stop.yml --tags=dm-worker -l dm_worker1` 停止 DM-worker 实例。 - - 3. 更新 relay log 子目录的后缀，例如将 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 重命名为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 4. 更新 relay log 子目录索引文件 `server-uuid.index`，例如将其中的内容由 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 变更为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 5. 通过 `$ ansible-playbook start.yml --tags=dm-worker -l dm_worker1` 启动 DM-worker 实例。 - - 6. 再次启动并验证数据迁移任务。 diff --git a/dev/reference/tools/data-migration/configure/dm-worker-configuration-file.md b/dev/reference/tools/data-migration/configure/dm-worker-configuration-file.md deleted file mode 100644 index a00700da68ad..000000000000 --- a/dev/reference/tools/data-migration/configure/dm-worker-configuration-file.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: DM-worker 配置文件介绍 -category: reference ---- - -# DM-worker 配置文件介绍 - -本文档主要介绍 DM-worker 的基础配置文件。在一般场景中，用户只需要使用基础配置即可完成 DM-worker 的部署。 - -完整配置项参考 [DM-worker 完整配置说明](/dev/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-file = "dm-worker.log" - -# DM-worker listen address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in replication group should have different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory that used to store relay log. -relay-dir = "./relay_log" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。| -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。| -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -> **注意：** -> -> 以上配置为部署 DM-worker 的基础配置，一般情况下使用基础配置即可，更多配置项参考 [DM-worker 完整配置说明](/dev/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 diff --git a/dev/reference/tools/data-migration/configure/overview.md b/dev/reference/tools/data-migration/configure/overview.md deleted file mode 100644 index 0bcd1bf94866..000000000000 --- a/dev/reference/tools/data-migration/configure/overview.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: DM 配置简介 -category: reference ---- - -# DM 配置简介 - -本文档简要介绍 DM (Data Migration) 的配置文件和数据同步任务的配置。 - -## 配置文件 - -- `inventory.ini`：使用 DM-Ansible 部署 DM 集群的配置文件。需要根据所选用的集群拓扑来进行编辑。详见[编辑 `inventory.ini` 配置文件](/dev/how-to/deploy/data-migration-with-ansible.md#第-7-步编辑-inventoryini-配置文件)。 -- `dm-master.toml`：DM-master 进程的配置文件，包括 DM 集群的拓扑信息、MySQL 实例与 DM-worker 之间的关系（必须为一对一的关系）。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-master.toml` 文件，各项配置说明详见 [DM-master 配置文件介绍](/dev/reference/tools/data-migration/configure/dm-master-configuration-file.md) -- `dm-worker.toml`：DM-worker 进程的配置文件，包括上游 MySQL 实例的配置和 relay log 的配置。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-worker.toml` 文件，各项配置说明详见 [DM-worker 配置文件介绍](/dev/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - -## 同步任务配置 - -### 任务配置文件 - -使用 DM-Ansible 部署 DM 集群时，`/conf` 中提供了任务配置文件模板：`task.yaml.exmaple` 文件。该文件是 DM 同步任务配置的标准文件，每一个具体的任务对应一个 `task.yaml` 文件。关于该配置文件的详细介绍，参见 [任务配置文件](/dev/reference/tools/data-migration/configure/task-configuration-file.md)。 - -### 创建数据同步任务 - -你可以基于 `task.yaml.example` 文件来创建数据同步任务，具体步骤如下： - -1. 复制 `task.yaml.example` 为 `your_task.yaml`。 -2. 参考[任务配置文件](/dev/reference/tools/data-migration/configure/task-configuration-file.md)来修改 `your_task.yaml` 文件。 -3. [使用 dmctl 创建数据同步任务](/dev/reference/tools/data-migration/manage-tasks.md#创建数据同步任务)。 - -### 关键概念 - -DM 配置的关键概念如下： - -| 概念 | 解释 | 配置文件 | -| :------------ | :------------ | :------------------ | -| source-id | 唯一确定一个 MySQL 或 MariaDB 实例，或者一个具有主从结构的复制组，字符串长度不大于 32 | `inventory.ini` 的 `source_id`；
`dm-master.toml` 的 `source-id`；
`task.yaml` 的 `source-id` | -| DM-worker ID | 唯一确定一个 DM-worker（取值于 `dm-worker.toml` 的 `worker-addr` 参数） | `dm-worker.toml` 的 `worker-addr`；
dmctl 命令行的 `-worker` / `-w` flag | diff --git a/dev/reference/tools/data-migration/configure/task-configuration-file-full.md b/dev/reference/tools/data-migration/configure/task-configuration-file-full.md deleted file mode 100644 index b0d6b739c3ed..000000000000 --- a/dev/reference/tools/data-migration/configure/task-configuration-file-full.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: DM 任务完整配置文件介绍 -category: reference ---- - -# DM 任务完整配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务完整的配置文件 [`task_advanced.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_advanced.yaml)，包含[全局配置](#全局配置) 和[实例配置](#实例配置) 两部分。 - -关于各配置项的功能和配置，请参阅[数据同步功能](/dev/reference/tools/data-migration/features/overview.md#同步功能介绍)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/dev/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 完整配置文件示例 - -下面是一个完整的配置文件示例，通过该示例可以完成复杂的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" -is-sharding: true # 是否为分库分表合并任务 -meta-schema: "dm_meta" # 下游储存 `meta` 信息的数据库 -remove-meta: false # 是否在任务同步开始前移除该任务名对应的 `meta`（`checkpoint` 和 `onlineddl` 等）。 -enable-heartbeat: false # 是否开启 `heartbeat` 功能 - -target-database: # 下游数据库实例配置 - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - - -## ******** 功能配置集 ********** - -routes: # 上游和下游表之间的路由 table routing 规则集 - route-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - target-schema: "test" # 目标库名称 - target-table: "t" # 目标表名称 - route-rule-2: - schema-pattern: "test_*" - target-schema: "test" - -filters: # 上游数据库实例匹配的表的 binlog event filter 规则集 - filter-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - events: ["truncate table", "drop table"] # 匹配哪些 event 类型 - action: Ignore # 对与符合匹配规则的 binlog 同步（Do）还是忽略(Ignore) - filter-rule-2: - schema-pattern: "test_*" - events: ["all dml"] - action: Do - -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 配置名称 - do-dbs: ["~^test.*", "user"] # 同步哪些库 - ignore-dbs: ["mysql", "account"] # 忽略哪些库 - do-tables: # 同步哪些表 - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "user" - tbl-name: "information" - ignore-tables: # 忽略哪些表 - - db-name: "user" - tbl-name: "log" - -mydumpers: # mydumper 处理单元运行配置参数 - global: # 配置名称 - mydumper-path: "./bin/mydumper" # mydumper binary 文件地址，默认值为 "./bin/mydumper" - threads: 4 # mydumper 从上游数据库实例导出数据的线程数量，默认值为 4 - chunk-filesize: 64 # mydumper 生成的数据文件大小，默认值为 64，单位为 MB - skip-tz-utc: true # 忽略对时间类型数据进行时区转化，默认值为 true - extra-args: "--no-locks" # mydumper 的其他参数，在 v1.0.2 版本中 DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置 - -loaders: # loader 处理单元运行配置参数 - global: # 配置名称 - pool-size: 16 # loader 并发执行 mydumper 的 SQL 文件的线程数量，默认值为 16 - dir: "./dumped_data" # loader 读取 mydumper 输出文件的地址，同实例对应的不同任务必须不同（mydumper 会根据这个地址输出 SQL 文件），默认值为 "./dumped_data" - -syncers: # syncer 处理单元运行配置参数 - global: # 配置名称 - worker-count: 16 # syncer 并发同步 binlog event 的线程数量，默认值为 16 - batch: 100 # syncer 同步到下游数据库的一个事务批次 SQL 语句数，默认值为 100 - -# ----------- 实例配置 ----------- -mysql-instances: - - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - meta: # `task-mode` 为 `incremental` 且下游数据库的 `checkpoint` 不存在时 binlog 同步开始的位置; 如果 checkpoint 存在，则以 `checkpoint` 为准 - binlog-name: binlog.000001 - binlog-pos: 4 - - route-rules: ["route-rule-1", "route-rule-2"] # 该上游数据库实例匹配的表到下游数据库的 table routing 规则名称 - filter-rules: ["filter-rule-1"] # 该上游数据库实例匹配的表的 binlog event filter 规则名称 - black-white-list: "bw-rule-1" # 该上游数据库实例匹配的表的 black & white list 过滤规则名称 - - mydumper-config-name: "global" # mydumper 配置名称 - loader-config-name: "global" # loader 配置名称 - syncer-config-name: "global" # Syncer 配置名称 - - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，等同于 mydumper 处理单元配置中的 `threads`，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，等同于 loader 处理单元配置中的 `pool-size`, 在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，等同于 syncer 处理单元配置中的 `worker-count`，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基本信息配置`和`实例配置`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。其中 `task-mode` 需要特殊说明： - -`task-mode` - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -全局配置主要包含下列功能配置集： - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `routes` | 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/dev/reference/tools/data-migration/features/overview.md#table-routing) | -| `filters` | 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) | -| `black-white-list` | 该上游数据库实例匹配的表的 black & white list 过滤规则集。建议通过该项指定需要同步的库和表，否则会同步所有的库和表。使用场景及示例配置参见 [Black & White Lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) | -| `mydumpers` | mydumper 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 | -| `loaders` | loader 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 | -| `syncers` | syncer 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 | - -各个功能配置集的参数及解释参见[完整配置文件示例](#完整配置文件示例)中的注释说明。 - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 - -在该项配置中设置数据同步子任务中各个功能对应的配置集中的配置名称，关于这些配置项的更多配置细节，参见[功能配置集](#功能配置集)的相关配置项，对应关系如下： - -| 配置项 | 相关配置项 | -| :------ | :------------------ | -| `route-rules` | `routes` | -| `filter-rules` | `filters` | -| `black-white-list` | `black-white-list` | -| `mydumper-config-name` | `mydumpers` | -| `loader-config-name` | `loaders` | -| `syncer-config-name` | `syncers` | diff --git a/dev/reference/tools/data-migration/configure/task-configuration-file.md b/dev/reference/tools/data-migration/configure/task-configuration-file.md deleted file mode 100644 index 1fcbc162521f..000000000000 --- a/dev/reference/tools/data-migration/configure/task-configuration-file.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: DM 任务配置文件介绍 -category: reference ---- - -# DM 任务配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务基础配置文件 [`task_basic.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_basic.yaml)，包含[全局配置](#全局配置)和[实例配置](#实例配置)两部分。 - -完整的任务配置参见 [DM 任务完整配置文件介绍](/dev/reference/tools/data-migration/configure/task-configuration-file-full.md) - -关于各配置项的功能和配置，请参阅[数据同步功能](/dev/reference/tools/data-migration/features/overview.md)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/dev/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 基础配置文件示例 - -下面是一个基础的配置文件示例，通过该示例可以完成简单的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" - -target-database: # 下游数据库实例配置 - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - -## ******** 功能配置集 ********** -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 黑白名单配置的名称 - do-dbs: ["all_mode"] # 同步哪些库 - -# ----------- 实例配置 ----------- -mysql-instances: - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基础信息配置`和`功能配置集`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。关于 `task-mode` 的特殊说明如下： - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -对于一般的业务场景，只需要配置黑白名单过滤规则集，配置说明参见以上示例配置文件中 `black-white-list` 的注释以及 [Black & white table lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 -配置项说明参见以上示例配置文件中 `mysql-instances` 的注释。 diff --git a/dev/reference/tools/data-migration/deploy.md b/dev/reference/tools/data-migration/deploy.md deleted file mode 100644 index d33fa6ecfd1b..000000000000 --- a/dev/reference/tools/data-migration/deploy.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: 使用 DM 同步数据 -category: reference ---- - -# 使用 DM 同步数据 - -本文介绍如何使用 DM (Data Migration) 同步数据。 - -## 第 1 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照 [使用 DM-Ansible 部署 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md)；也可以使用 binary 部署 DM 集群用于体验或者测试，具体部署方法参照[使用 DM binary 部署 DM 集群](/dev/how-to/deploy/data-migration-with-binary.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 2 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 MySQL-1 | 172.16.10.81 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 MySQL-2 | 172.16.10.82 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - - > **注意：** - > - > `{ansible deploy}/conf/dm-master.toml` 中的 `{ansible deploy}` 表示使用 DM-Ansible 部署 DM 时通过 `deploy_dir` 参数指定的目录。 - -## 第 3 步：配置任务 - -假设需要将 MySQL-1 和 MySQL-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - mydumper-path: "./bin/mydumper" # Mydumper 二进制文件的路径。 - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 4 步：启动任务 - -为了提前发现数据同步任务的一些配置错误，DM 中增加了[前置检查](/dev/reference/tools/data-migration/precheck.md)功能： - -- 启动数据同步任务时，DM 自动检查相应的权限和配置。 -- 也可使用 `check-task` 命令手动前置检查上游的 MySQL 实例配置是否符合 DM 的配置要求。 - -> **注意：** -> -> 第一次启动数据同步任务时，必须确保上游数据库已配置。否则，启动任务时会报错。 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/`。 - -2. 执行以下命令启动 dmctl。 - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务。其中，`task.yaml` 是之前编辑的配置文件。 - - {{< copyable "" >}} - - ```bash - » start-task ./task.yaml - ``` - - - 如果执行该命令后返回的结果如下，则表明任务已成功启动。 - - ```json - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.10.72:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.10.73:8262", - "msg": "" - } - ] - } - ``` - - - 如果任务启动失败，可根据返回结果的提示进行配置变更后执行 `start-task task.yaml` 命令重新启动任务。 - -## 第 5 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "" >}} - -```bash -» query-status -``` - -## 第 6 步：停止任务 - -如果不再需要进行数据同步，可以在 dmctl 内使用以下命令停止同步任务： - -{{< copyable "" >}} - -```bash -» stop-task test -``` - -其中的 `test` 是 `task.yaml` 配置文件中 `name` 配置项设置的任务名。 - -## 第 7 步：监控任务与查看日志 - -如果使用 DM-Ansible 部署 DM 集群时，正确部署了 Prometheus 与 Grafana，且 Grafana 的地址为 `172.16.10.71`，可在浏览器中打开 进入 Grafana，选择 DM 的 dashboard 即可查看 DM 相关监控项。 - -DM 在运行过程中，DM-worker, DM-master 及 dmctl 都会通过日志输出相关信息。各组件的日志目录如下： - -- DM-master 日志目录：通过 DM-master 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-master 节点的 `{ansible deploy}/log/dm-master.log`。 -- DM-worker 日志目录：通过 DM-worker 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-worker 节点的 `{ansible deploy}/log/dm-worker.log`。 -- dmctl 日志目录：与其二进制文件目录相同。 diff --git a/dev/reference/tools/data-migration/dm-portal.md b/dev/reference/tools/data-migration/dm-portal.md deleted file mode 100644 index e08828b6b0f4..000000000000 --- a/dev/reference/tools/data-migration/dm-portal.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: DM Portal 简介 -category: reference ---- - -# DM Portal 简介 - -当前版本的 DM 提供了丰富多样的功能特性，包括 [Table routing](/dev/reference/tools/data-migration/features/overview.md#table-routing)，[Black & white table lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists)，[Binlog event filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) 等。但这些功能特性同时也增加了用户使用 DM 的复杂度，尤其在编写 [DM 任务配置](/dev/reference/tools/data-migration/configure/task-configuration-file.md)的时候。 - -针对这个问题，DM 提供了一个精简的网页程序 DM Portal，能够帮助用户以可视化的方式去配置需要的同步任务，并且生成可以直接让 DM 直接执行的 `task.yaml` 文件。 - -## 功能描述 - -### 同步模式配置 - -支持 DM 的三种同步模式： - -- 全量同步 -- 增量同步 -- All（全量+增量） - -### 实例信息配置 - -支持配置库表同步路由方式，能够支持 DM 中分库分表合并的配置方式。 - -### binlog 过滤配置 - -支持对数据库、数据表配置 binlog event 过滤。 - -### 配置文件生成 - -支持配置文件创建，能够将配置文件下载到本地并且同时会在 dm-portal 服务器的 `/tmp/` 目录下自动创建。 - -### 使用限制 - -当前的 DM 配置可视化生成页面能够覆盖绝大部分的 DM 配置场景，但也有一定的使用限制： - -- 不支持 [Binlog event filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) 的 SQL pattern 方式 -- 编辑功能不支持解析用户之前写的 `task.yaml` 文件，页面只能编辑由页面生成的 `task.yaml` 文件 -- 编辑功能不支持修改实例配置信息，如果用户需要调整实例配置，需要重新生成 `task.yaml` 文件 -- 页面的上游实例配置仅用于获取上游库表结构，DM-worker 里依旧需要配置对应的上游实例信息 -- 生成的 `task.yaml` 中，默认 mydumper-path 为 `./bin/mydumper`，如果实际使用其他路径，需要在生成的配置文件中进行手动修改。 - -## 部署使用 - -### Binary 部署 - -DM Portal 可以在 [dm-portal-latest-linux-amd64.tar.gz](https://download.pingcap.org/dm-portal-latest-linux-amd64.tar.gz) 下载，通过 `./dm-portal` 的命令即可直接启动。 - -* 如果在本地启动，浏览器访问 `127.0.0.1:8280` 即可使用。 -* 如果在服务器上启动，需要为服务器上配置访问代理。 - -### DM Ansible 部署 - -可以使用 DM Ansible 部署 DM Portal，具体部署方法参照[使用 DM Ansible 部署 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md)。 - -## 使用说明 - -### 新建规则 - -#### 功能描述 - -用于新建一个 `task.yaml` 文件，需要选择同步模式、配置上下游实例、配置库表路由，配置 binlog 过滤。 - -#### 操作步骤 - -登录 dm-portal 页面，点击**新建任务规则**。 - -### 基础信息配置 - -#### 功能描述 - -用于填写任务名称，以及选择任务类型。 - -#### 前置条件 - -已选择**新建同步规则**。 - -#### 操作步骤 - -1. 填写任务名称。 -2. 选择任务类型。 - -![DM Portal BasicConfig](/media/dm-portal-basicconfig.png) - -### 实例信息配置 - -#### 功能描述 - -用于配置上下游实例信息，包括 Host、Port、Username、Password。 - -#### 前置条件 - -已填写任务名称和选择任务类型。 - -#### 注意事项 - -如果任务类型选择**增量**或者 **All**，在配置上游实例信息时候，还需要配置 binlog-file 和 binlog-pos。 - -#### 操作步骤 - -1. 填写上游实例信息。 -2. 填写下游实例信息。 -3. 点击**下一步**。 - -![DM Portal InstanceConfig](/media/dm-portal-instanceconfig.png) - -### binlog 过滤配置 - -#### 功能描述 - -用于配置上游的 binlog 过滤，可以选择需要过滤的 DDL/DML，并且在数据库上配置的 filter 后会自动给其下的数据表继承。 - -#### 前置条件 - -已经配置好上下游实例信息并且连接验证没问题。 - -#### 注意事项 - -* binlog 过滤配置只能在上游实例处进行修改编辑，一旦数据库或者数据表被移动到下游实例后，就不可以进行修改编辑。 -* 在数据库上配置的 binlog 过滤会自动被其下的数据表继承。 - -#### 操作步骤 - -1. 点击需要配置的数据库或者数据表。 -2. 点击编辑按钮，选择需要过滤的 binlog 类型。 - -![DM Portal InstanceShow](/media/dm-portal-instanceshow.png) - -![DM Portal BinlogFilter 1](/media/dm-portal-binlogfilter-1.png) - -![DM Portal BinlogFilter 2](/media/dm-portal-binlogfilter-2.png) - -### 库表路由配置 - -#### 功能描述 - -可以选择需要同步的数据库和数据表，并且进行修改名称、合并库、合并表等操作。可以对上一步操作进行撤销，可以对库表路由配置进行全部重置。在完成任务配置后，DM Portal 会帮忙生成对应的 `task.yaml` 文件。 - -#### 前置条件 - -* 已经配置好需要的 binlog 过滤规则。 - -#### 注意事项 - -* 在合并库表操作的时候，不允许批量操作，只能逐一拖动。 -* 在合表库表操作的时候，只能对数据表进行拖动操作，不能对数据库进行数据库进行拖动操作。 - -#### 操作步骤 - -1. 在**上游实例**处，选择需要同步的数据库和数据表。 -2. 点击移动按钮，将需要同步的库表移动至**下游实例**处。 -3. 点击右键按钮，可以对库表进行改名操作。 -4. 选中需要操作的数据表，可以拖动至别的数据表图标上创建出合并表；可以拖动到数据库图标上移动至该库下；可以拖动到 target-instance 图标上移动到一个新的数据库下。 -5. 点击**完成**，自动下载 `task.yaml` 到本地，并且在 DM Portal 服务器上的 `/tmp/` 目录下自动创建一份 `task.yaml` 配置文件。 - -##### 移动同步库表 - -![DM Portal TableRoute 1](/media/dm-portal-tableroute-1.png) - -![DM Portal TableRoute 2](/media/dm-portal-tableroute-2.png) - -##### 右键修改库表名称 - -![DM Portal ChangeTableName](/media/dm-portal-changetablename.png) - -##### 合并数据表操作 - -![DM Portal MergeTable 1](/media/dm-portal-mergetable-1.png) - -![DM Portal MergeTable 2](/media/dm-portal-mergetable-2.png) - -##### 移动数据表至其他数据库 - -![DM Portal MoveToDB 1](/media/dm-portal-movetodb-1.png) - -![DM Portal MoveToDB 2](/media/dm-portal-movetodb-2.png) - -##### 移动数据表至新建默认数据库 - -![DM Portal MoveToNewDB 1](/media/dm-portal-movetonewdb-1.png) - -![DM Portal MoveToNewDB 2](/media/dm-portal-movetonewdb-2.png) - -##### 撤销本次操作 - -![DM Portal Revert](/media/dm-portal-revert.png) - -##### 清空下游实例 - -![DM Portal Reset](/media/dm-portal-reset.png) - -##### 完成并下载 - -![DM Portal GenerateConfig](/media/dm-portal-generateconfig.png) - -### 编辑规则 - -#### 功能描述 - -可以将之前创建的 `task.yaml` 上传后，解析出来之前的填写的配置信息，对部分配置进行修改。 - -#### 前置条件 - -* 已经创建出 `task.yaml` 文件。 -* 非 DM Portal 创建出来的 `task.yaml` 文件不可使用。 - -#### 注意事项 - -* 不允许修改实例配置信息 - -#### 操作步骤 - -1. 在首页，点击**编辑同步规则**。 -2. 选择上传 `task.yaml` 文件。 -3. 解析成功后，页面会自动跳转。 - -![DM Portal EditConfig](/media/dm-portal-editconfig.png) - -![DM Portal UploadConfig](/media/dm-portal-uploadconfig.png) diff --git a/dev/reference/tools/data-migration/dm-upgrade.md b/dev/reference/tools/data-migration/dm-upgrade.md deleted file mode 100644 index 0f08bc0856eb..000000000000 --- a/dev/reference/tools/data-migration/dm-upgrade.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: DM 版本升级 -category: reference ---- - -# DM 版本升级 - -本文档主要介绍各 DM (Data Migration) 版本间的升级操作步骤。 - -> **注意：** -> -> - 若无特殊说明，各版本的升级操作均为从前一个有升级指引的版本向当前版本升级。 -> - 若无特殊说明，各升级操作示例均假定已经下载了对应版本的 DM 和 DM-Ansible 且 DM binary 存在于 DM-Ansible 的相应目录中（下载 DM binary 可以参考[更新组件版本](/dev/reference/tools/data-migration/cluster-operations.md#更新组件版本)）。 -> - 若无特殊说明，各升级操作示例均假定升级前已停止所有同步任务，升级完成后手动重新启动所有同步任务。 -> - 以下版本升级指引逆序展示。 - -## 升级到 v1.0.3 - -### 版本信息 - -```bash -Release Version: v1.0.3 -Git Commit Hash: 41426af6cffcff9a325697a3bdebeadc9baa8aa6 -Git Branch: release-1.0 -UTC Build Time: 2019-12-13 07:04:53 -Go Version: go version go1.13 linux/amd64 -``` - -### 主要变更 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.3` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.3 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.2 - -### 版本信息 - -```bash -Release Version: v1.0.2 -Git Commit Hash: affc6546c0d9810b0630e85502d60ed5c800bf25 -Git Branch: release-1.0 -UTC Build Time: 2019-10-30 05:08:50 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 支持自动为 DM-worker 生成部分配置项，减少人工配置成本 -- 支持自动生成 mydumper 库表参数，减少人工配置成本 -- 优化 `query-status` 默认输出，突出重点信息 -- 直接管理到下游的 DB 连接而不是使用内置连接池，优化 SQL 错误处理与重试 -- 修复 DM-worker 进程启动时、执行 DML 失败时可能 panic 的 bug -- 修复执行 sharding DDL（如 `ADD INDEX`）超时后可能造成后续 sharding DDL 无法正确协调的 bug -- 修复了有部分 DM-worker 不可访问时无法 `start-task` 的 bug -- 完善了对 1105 错误的自动重试策略 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.2` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.2 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.1 - -### 版本信息 - -```bash -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 修复某些情况下 DM 会频繁重建数据库连接的问题 -- 修复使用 `query-status` 时潜在的 panic 问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.1` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.1 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-10-geb2889c9 (1.0 GA) - -### 版本信息 - -```bash -Release Version: v1.0.0-10-geb2889c9 -Git Commit Hash: eb2889c9dcfbff6653be9c8720a32998b4627db9 -Git Branch: release-1.0 -UTC Build Time: 2019-09-06 03:18:48 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 常见的异常场景支持自动尝试恢复同步任务 -- 提升 DDL 语法兼容性 -- 修复上游数据库连接异常时可能丢失数据的 bug - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.0` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0 GA 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-rc.1-12-gaa39ff9 - -### 版本信息 - -```bash -Release Version: v1.0.0-rc.1-12-gaa39ff9 -Git Commit Hash: aa39ff981dfb3e8c0fa4180127246b253604cc34 -Git Branch: dm-master -UTC Build Time: 2019-07-24 02:26:08 -Go Version: go version go1.11.2 linux/amd64 -``` - -### 主要变更 - -从此版本开始，将对所有的配置进行严格检查，遇到无法识别的配置会报错，以确保用户始终准确地了解自己的配置。 - -### 升级操作示例 - -启动 DM-master 或 DM-worker 前，必须确保已经删除废弃的配置信息，且没有多余的配置项，否则会启动失败。可根据失败信息删除多余的配置。 -可能遗留的废弃配置： - -- `dm-worker.toml` 中的 `meta-file` -- `task.yaml` 中的 `mysql-instances` 中的 `server-id` diff --git a/dev/reference/tools/data-migration/faq.md b/dev/reference/tools/data-migration/faq.md deleted file mode 100644 index 0604ed09d127..000000000000 --- a/dev/reference/tools/data-migration/faq.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Data Migration 常见问题 -category: reference -aliases: ['/docs-cn/dev/faq/data-migration/'] ---- - -# Data Migration 常见问题 - -## DM 是否支持同步阿里 RDS 以及其他云数据库的数据？ - -DM 仅支持解析标准版本的 MySQL/MariaDB 的 binlog，对于阿里云 RDS 以及其他云数据库没有进行过测试，如果确认其 binlog 为标准格式，则可以支持。 - -## task 配置中的黑白名单的正则表达式是否支持`非获取匹配`（?!）？ - -目前不支持，DM 仅支持 golang 标准库的正则，可以通过 [re2-syntax](https://github.com/google/re2/wiki/Syntax) 了解 golang 支持的正则表达式。 - -## 如果在上游执行的一个 statement 包含多个 DDL 操作，DM 是否支持同步？ - -DM 会尝试将包含多个 DDL 变更操作的单条语句拆分成只包含一个 DDL 操作的多条语句，但是可能没有覆盖所有的场景。建议在上游执行的一条 statement 中只包含一个 DDL 操作，或者在测试环境中验证一下，如果不支持，可以给 DM 提 [issue](https://github.com/pingcap/dm/issues)。 - -## 如何处理不兼容的 DDL 语句？ - -你需要使用 dmctl 手动处理 TiDB 不兼容的 DDL 语句（包括手动跳过该 DDL 语句或使用用户指定的 DDL 语句替换原 DDL 语句，详见[跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句](/dev/reference/tools/data-migration/skip-replace-sqls.md)）。 - -> **注意：** -> -> TiDB 目前并不兼容 MySQL 支持的所有 DDL 语句。 - -## 如何重置数据同步任务？ - -在以下情况中，你需要重置整个数据同步任务： - -- 上游数据库中人为执行了 `RESET MASTER`，造成 relay log 同步出错 - -- relay log 或上游 binlog event 损坏或者丢失 - -此时，relay 处理单元通常会发生错误而退出，且无法优雅地自动恢复，因此需要通过手动方式恢复数据同步： - -1. 使用 `stop-task` 命令停止当前正在运行的所有同步任务。 - -2. 使用 Ansible [停止整个 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md#第-10-步关闭-dm-集群)。 - -3. 手动清理掉与 binlog event 被重置的 MySQL master 相对应的 DM-worker 的 relay log 目录。 - - - 如果是使用 Ansible 部署，relay log 目录即 `/relay_log` 目录。 - - 如果是使用二进制文件手动部署，relay log 目录即 relay-dir 参数设置的目录。 - -4. 清理掉下游已同步的数据。 - -5. 使用 Ansible [启动整个 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md#第-9-步部署-dm-集群)。 - -6. 以新的任务名重启数据同步任务，或设置 `remove-meta` 为 `true` 且 `task-mode` 为 `all`。 diff --git a/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md b/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md deleted file mode 100644 index 93504f66abb6..000000000000 --- a/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md +++ /dev/null @@ -1,540 +0,0 @@ ---- -title: 手动处理 Sharding DDL Lock -category: reference ---- - -# 手动处理 Sharding DDL Lock - -DM (Data Migration) 使用 sharding DDL lock 来确保分库分表的 DDL 操作可以正确执行。绝大多数情况下，该锁定机制可自动完成；但在部分异常情况发生时，需要使用 `unlock-ddl-lock`/`break-ddl-lock` 手动处理异常的 DDL lock。 - -> **注意：** -> -> - 不要轻易使用 `unlock-ddl-lock`/`break-ddl-lock` 命令，除非完全明确当前场景下使用这些命令可能会造成的影响，并能接受这些影响。 -> - 在手动处理异常的 DDL lock 前，请确保已经了解 DM 的[分库分表合并同步原理](/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)。 - -## 命令介绍 - -### `show-ddl-locks` - -该命令用于查询当前 DM-master 上存在的 DDL lock 信息。 - -#### 命令示例 - -{{< copyable "shell-regular" >}} - -```bash -show-ddl-locks [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，查询所有 DM-worker 相关的 lock 信息；指定时，仅查询与这组 DM-worker 相关的 lock 信息，可重复多次指定 - -+ `task-name`： - - 非 flag 参数，string，可选 - - 不指定时，查询与所有任务相关的 lock 信息；指定时，仅查询特定任务相关的 lock 信息 - -#### 返回结果示例 - -{{< copyable "shell-regular" >}} - -```bash -show-ddl-locks test -``` - -``` -{ - "result": true, # 查询 lock 操作本身是否成功 - "msg": "", # 查询 lock 操作失败时的原因或其它描述信息（如不存在任务 lock） - "locks": [ # DM-master 上存在的 lock 信息列表 - { - "ID": "test-`shard_db`.`shard_table`", # lock 的 ID 标识，当前由任务名与 DDL 对应的 schema/table 信息组成 - "task": "test", # lock 所属的任务名 - "owner": "127.0.0.1:8262", # lock 的 owner（第一个遇到该 DDL 的 DM-worker） - "DDLs": [ # lock 对应的 DDL 列表 - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;" - ], - "synced": [ # 已经收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8262" - ], - "unsynced": [ # 尚未收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8263" - ] - } - ] -} -``` - -### `unlock-ddl-lock` - -该命令用于主动请求 DM-master 解除指定的 DDL lock，包括的操作：请求 owner 执行 DDL 操作，请求其他非 owner 的 DM-worker 跳过 DDL 操作，移除 DM-master 上的 lock 信息。 - -#### 命令示例 - -{{< copyable "shell-regular" >}} - -```bash -unlock-ddl-lock [--worker=127.0.0.1:8262] [--owner] [--force-remove] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，对所有已经在等待该 lock 的 DM-worker 发起跳过 DDL 操作请求；指定时，仅对这组 DM-worker 发起跳过 DDL 操作请求，可重复多次指定 - -+ `owner`： - - flag 参数，string，`--owner`，可选 - - 不指定时，请求默认的 owner（`show-ddl-locks` 返回结果中的 `owner`）执行 DDL 操作；指定时，请求该 DM-worker（替代默认的 owner）执行 DDL 操作 - -+ `force-remove`： - - flag 参数，boolean，`--force-remove`，可选 - - 不指定时，仅在 owner 执行 DDL 成功时移除 lock 信息；指定时，即使 owner 执行 DDL 失败也强制移除 lock 信息（此后将无法再次查询或操作该 lock） - -+ `lock-ID`： - - 非 flag 参数，string，必选 - - 指定需要执行 unlock 操作的 DDL lock ID（即 `show-ddl-locks` 返回结果中的 `ID`） - -#### 返回结果示例 - -{{< copyable "shell-regular" >}} - -```bash -unlock-ddl-lock test-`shard_db`.`shard_table` -``` - -``` -{ - "result": true, # unlock lock 操作是否成功 - "msg": "", # unlock lock 操作失败时的原因 - "workers": [ # 各 DM-worker 执行/跳过 DDL 操作结果信息列表 - { - "result": true, # 该 DM-worker 执行/跳过 DDL 操作是否成功 - "worker": "127.0.0.1:8262", # DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker 执行/跳过 DDL 失败时的原因 - } - ] -} -``` - -### break-ddl-lock - -该命令用于主动请求 DM-worker 强制打破当前正在等待 unlock 的 DDL lock，包括请求 DM-worker 执行或跳过 DDL 操作、移除该 DM-worker 上的 DDL lock 信息。 - -#### 命令示例 - -{{< copyable "shell-regular" >}} - -```bash -break-ddl-lock <--worker=127.0.0.1:8262> [--remove-id] [--exec] [--skip] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，必选 - - 指定需要执行 break 操作的 DM-worker - -+ `remove-id`：已废弃 - -+ `exec`： - - flag 参数，boolean，`--exec`，可选 - - 不可与 `--skip` 参数同时指定 - - 指定时，请求该 DM-worker 执行（execute）当前 lock 对应的 DDL - -+ `skip`： - - flag 参数，boolean，`--skip`，可选 - - 不可与 `--exec` 参数同时指定 - - 指定时，请求该 DM-worker 跳过（skip）当前 lock 对应的 DDL - -+ `task-name`： - - 非 flag 参数，string，必选 - - 指定要执行 break 操作的 lock 所在的 task 名称（要查看各 task 上是否存在 lock，可通过 [query-status](/dev/reference/tools/data-migration/query-status.md) 获得） - -#### 返回结果示例 - -{{< copyable "shell-regular" >}} - -```bash -break-ddl-lock -w 127.0.0.1:8262 --exec test -``` - -``` -{ - "result": true, # break lock 操作是否成功 - "msg": "", # break lock 操作失败时的原因 - "workers": [ # 执行 break lock 操作的 DM-worker 列表（当前单次操作仅支持对一个 DM-worker 执行 break lock） - { - "result": false, # 该 DM-worker break lock 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker break lock 失败时的原因 - } - ] -} -``` - -## 支持场景 - -目前，使用 `unlock-ddl-lock`/`break-ddl-lock` 命令仅支持处理以下三种 sharding DDL lock 异常情况。 - -### 场景一：部分 DM-worker 下线 - -#### Lock 异常原因 - -在 DM-master 尝试自动 unlock sharding DDL lock 之前，需要等待所有 DM-worker 的 sharding DDL events 全部到达（详见[分库分表合并同步原理](/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)）。如果 sharding DDL 已经在同步过程中，且有部分 DM-worker 下线，并且不再计划重启它们（按业务需求移除了这部分 DM-worker），则会由于永远无法等齐所有的 DDL 而造成 lock 无法自动 unlock。 - -#### 手动处理示例 - -假设上游有 MySQL-1 和 MySQL-2 两个实例，其中 MySQL-1 中有 `shard_db_1`.`shard_table_1` 和 `shard_db_1`.`shard_table_2` 两个表，MySQL-2 中有 `shard_db_2`.`shard_table_1` 和 `shard_db_2`.`shard_table_2` 两个表。现在需要将这 4 个表合并后同步到下游 TiDB 的 `shard_db`.`shard_table` 表中。 - -初始表结构如下： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE shard_db_1.shard_table_1; -``` - -``` -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -上游分表将执行以下 DDL 语句变更表结构： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE shard_db_*.shard_table_* ADD COLUMN c2 INT; -``` - -MySQL 及 DM 操作与处理流程如下： - -1. MySQL-1 对应的 DM-worker-1 的两个分表执行了对应的 DDL 操作进行表结构变更。 - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE shard_db_1.shard_table_1 ADD COLUMN c2 INT; - ``` - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE shard_db_1.shard_table_2 ADD COLUMN c2 INT; - ``` - -2. DM-worker-1 接受到两个分表的 DDL 之后，将对应 MySQL-1 相关的 DDL 信息发送给 DM-master，DM-master 创建相应的 DDL lock。 -3. 使用 `show-ddl-lock` 查看当前的 DDL lock 信息。 - - {{< copyable "shell-regular" >}} - - ```bash - show-ddl-locks test - ``` - - ``` - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8262", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8262" - ], - "unsynced": [ - "127.0.0.1:8263" - ] - } - ] - } - ``` - -4. 由于业务需要，DM-worker-2 对应的 MySQL-2 的数据不再需要同步到下游 TiDB，对 DM-worker-2 执行了下线处理。 -5. DM-master 上 ID 为 ```test-`shard_db`.`shard_table` ``` 的 lock 无法等到 DM-worker-2 的 DDL 操作信息。 - - `show-ddl-locks` 返回的 `unsynced` 中一直包含 DM-worker-2 的信息（`127.0.0.1:8263`）。 - -6. 使用 `unlock-dll-lock` 来请求 DM-master 主动 unlock 该 DDL lock。 - - - 如果 DDL lock 的 owner 也已经下线，可以使用 `--owner` 参数指定其他 DM-worker 作为新 owner 来执行 DDL。 - - 当存在任意 DM-worker 报错时，`result` 将为 `false`，此时请仔细检查各 DM-worker 的错误是否是预期可接受的。 - - 已下线的 DM-worker 会返回 `rpc error: code = Unavailable` 错误属于预期行为，可以忽略。 - - 如果其它未下线的 DM-worker 返回错误，则需要根据情况额外处理。 - - {{< copyable "shell-regular" >}} - - ```bash - unlock-ddl-lock test-`shard_db`.`shard_table` - ``` - - ``` - { - "result": false, - "msg": "github.com/pingcap/tidb-enterprise-tools/dm/master/server.go:1472: DDL lock test-`shard_db`.`shard_table` owner ExecuteDDL successfully, so DDL lock removed. but some dm-workers ExecuteDDL fail, you should to handle dm-worker directly", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": false, - "worker": "127.0.0.1:8263", - "msg": "rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = \"transport: Error while dialing dial tcp 127.0.0.1:8263: connect: connection refused\"" - } - ] - } - ``` - -7. 使用 `show-dd-locks` 确认 DDL lock 是否被成功 unlock。 - - ```bash - show-ddl-locks test - ``` - - ``` - { - "result": true, - "msg": "no DDL lock exists", - "locks": [ - ] - } - ``` - -8. 查看下游 TiDB 中的表结构是否变更成功。 - - {{< copyable "sql" >}} - - ```sql - SHOW CREATE TABLE shard_db.shard_table; - ``` - - ``` - +-------------+--------------------------------------------------+ - | Table | Create Table | - +-------------+--------------------------------------------------+ - | shard_table | CREATE TABLE `shard_table` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 COLLATE=latin1_bin | - +-------------+--------------------------------------------------+ - ``` - -9. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -使用 `unlock-ddl-lock` 手动执行 unlock 操作后，由于该任务的配置信息中仍然包含了已下线的 DM-worker，如果不进行处理，则当下次 sharding DDL 到达时，仍会出现 lock 无法自动完成同步的情况。 - -因此，在手动解锁 DDL lock 后，需要再执行以下操作： - -1. 使用 `stop-task` 停止运行中的任务。 -2. 更新任务配置文件，将已下线 DM-worker 对应的信息从配置文件中移除。 -3. 使用 `start-task` 及新任务配置文件重新启动任务。 - -> **注意：** -> -> 在 `unlock-ddl-lock` 之后，如果已下线的 DM-worker 重新上线并尝试对其中的分表进行数据同步，则会由于数据与下游的表结构不匹配而发生错误。 - -### 场景二：unlock 过程中部分 DM-worker 重启 - -#### Lock 异常原因 - -在 DM-master 收到所有 DM-worker 的 DDL 信息后，执行自动 unlock DDL lock 的操作主要包括以下步骤： - -1. 请求 lock owner 执行 DDL 操作，并更新对应分表的 checkpoint。 -2. 在 owner 执行 DDL 操作成功后，移除 DM-master 上保存的 DDL lock 信息。 -3. 在 owner 执行 DDL 操作成功后，请求其他所有 DM-worker 跳过 DDL 操作并更新对应分表的 checkpoint。 - -上述 unlock DDL lock 的操作不是原子的，当 owner 执行 DDL 操作成功后，请求其他 DM-worker 跳过 DDL 操作时，如果该 DM-worker 发生了重启，则会造成该 DM-worker 跳过 DDL 操作失败。 - -此时 DM-master 上的 lock 信息被移除，但该 DM-worker 重启后将尝试继续重新同步该 DDL 操作。但是，由于其他 DM-worker（包括原 owner）已经同步完该 DDL 操作，并已经在继续后续的同步，该 DM-worker 将永远无法等待该 DDL 操作对应 lock 的自动 unlock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -当在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息；但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于 DM-worker-2 发生了重启而跳过 DDL 操作失败。 - -DM-worker-2 重启后，将尝试重新同步重启前已经在等待的 DDL lock。此时将在 DM-master 上创建一个新的 lock，并且该 DM-worker 将成为 lock 的 owner（其他 DM-worker 此时已经执行或跳过 DDL 操作并在进行后续同步）。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上存在该 DDL 操作对应的 lock。 - - 应该仅有该重启的 DM-worker（`127.0.0.1:8263`）处于 `syned` 状态： - - {{< copyable "shell-regular" >}} - - ```bash - show-ddl-locks - ``` - - ``` - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8263", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8263" - ], - "unsynced": [ - "127.0.0.1:8262" - ] - } - ] - } - ``` - -2. 使用 `unlock-ddl-lock` 请求 DM-master unlock 该 lock。 - - - 使用 `--worker` 参数限定操作仅针对该重启的 DM-worker（`127.0.0.1:8263`）。 - - Lock 过程中该 DM-worker 会尝试再次向下游执行该 DDL 操作（重启前的原 owner 已向下游执行过该 DDL 操作），需要确保该 DDL 操作可被多次执行。 - - {{< copyable "shell-regular" >}} - - ```bash - unlock-ddl-lock --worker=127.0.0.1:8263 test-`shard_db`.`shard_table` - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -3. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 -4. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -手动 unlock sharding DDL lock 后，后续的 sharding DDL 将可以自动正常同步。 - -### 场景三：unlock 过程中部分 DM-worker 临时不可达 - -#### Lock 异常原因 - -与 [unlock 过程中部分 DM-worker 重启](#场景二unlock-过程中部分-dm-worker-重启) 造成 lock 异常的原因类似。当请求 DM-worker 跳过 DDL 操作时，如果该 DM-worker 临时不可达，则会造成该 DM-worker 跳过 DDL 操作失败。此时 DM-master 上的 lock 信息被移除，但该 DM-worker 将处于等待一个不再存在的 DDL lock 的状态。 - -场景三与[场景二](#场景二unlock-过程中部分-dm-worker-重启)的区别在于，场景三中 DM-master 没有 lock，而场景二中 DM-master 有一个新的 lock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息，但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于网络原因等临时不可达而跳过 DDL 操作失败。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上不再存在该 DDL 操作对应的 lock。 -2. 使用 `query-status` 确认 DM-worker 仍在等待 lock 同步。 - - {{< copyable "shell-regular" >}} - - ```bash - query-status test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - ... - { - ... - "worker": "127.0.0.1:8263", - "subTaskStatus": [ - { - ... - "unresolvedDDLLockID": "test-`shard_db`.`shard_table`", - "sync": { - ... - "blockingDDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "unresolvedGroups": [ - { - "target": "`shard_db`.`shard_table`", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "firstPos": "(mysql-bin|000001.000003, 1752)", - "synced": [ - "`shard_db_2`.`shard_table_1`", - "`shard_db_2`.`shard_table_2`" - ], - "unsynced": [ - ] - } - ], - "synced": false - } - } - ] - ... - } - ] - } - ``` - -3. 使用 `break-ddl-lock` 请求强制 break 该 DM-worker 当前正在等待的 DDL lock。 - - 由于 owner 已经向下游执行了 DDL 操作，因此在 break 时使用 `--skip` 参数。 - - {{< copyable "shell-regular" >}} - - ```bash - break-ddl-lock --worker=127.0.0.1:8263 --skip test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -4. 使用 `query-status` 确认同步任务是否正常且不再处于等待 lock 的状态。 - -#### 手动处理后的影响 - -手动强制 break lock 后，后续 sharding DDL 将可以自动正常同步。 diff --git a/dev/reference/tools/data-migration/features/overview.md b/dev/reference/tools/data-migration/features/overview.md deleted file mode 100644 index 898ca9ddffd0..000000000000 --- a/dev/reference/tools/data-migration/features/overview.md +++ /dev/null @@ -1,529 +0,0 @@ ---- -title: 数据同步功能 -summary: DM 提供的功能及其配置介绍 -category: reference ---- - -# 数据同步功能 - -本文将详细介绍 DM 提供的数据同步功能，以及相关的配置选项。 - -## Table routing - -Table routing 提供将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的功能。 - -> **注意：** -> -> - 不支持对同一个表设置多个不同的路由规则。 -> - Schema 的匹配规则需要单独设置，用来同步 `create/drop schema xx`，例如下面[参数配置](#参数配置)中的 rule-2。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -routes: - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -### 参数解释 - -将根据 [`schema-pattern`/`table-pattern`](/dev/reference/tools/data-migration/table-selector.md) 匹配上该规则的上游 MySQL/MariaDB 实例的表同步到下游的 `target-schema`/`target-table`。 - -### 使用示例 - -下面展示了三个不同场景下的配置示例。 - -#### 分库分表合并 - -假设存在分库分表场景，需要将上游两个 MySQL 实例的表 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的一张表 `test`.`t`。 - -为了同步到下游实例的表 `test`.`t` 需要创建两个 table routing 规则： - -- `rule-1` 用来同步匹配上 `schema-pattern: "test_*"` 和 `table-pattern: "t_*"` 的表的 DML/DDL 语句到下游的 `test`.`t`。 -- `rule-2` 用来同步匹配上 `schema-pattern: "test_*"` 的库的 DDL 语句，例如 `create/drop schema xx`。 - -> **注意：** -> -> - 如果下游 TiDB `schema: test` 已经存在， 并且不会被删除，则可以省略 `rule-2`。 -> - 如果下游 TiDB `schema: test` 不存在，只设置了 `rule_1`，则同步会报错 `schema test doesn't exist`。 - -{{< copyable "" >}} - -```yaml - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 分库合并 - -假设存在分库场景，将上游两个 MySQL 实例 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t_{1,2,3...}`，创建一条路由规则即可： - -{{< copyable "" >}} - -```yaml - rule-1: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 错误的 table routing - -假设存在下面两个路由规则，`test_1_bak`.`t_1_bak` 可以匹配上 `rule-1` 和 `rule-2`，违反 table 路由的限制而报错。 - -{{< copyable "" >}} - -```yaml - rule-0: - schema-pattern: "test_*" - target-schema: "test" - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_1_bak" - table-pattern: "t_1_bak" - target-schema: "test" - target-table: "t_bak" -``` - -## Black & white table lists - -上游数据库实例表的黑白名单过滤规则，可以用来过滤或者只同步某些 `database/table` 的所有操作。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -black-white-list: - rule-1: - do-dbs: ["~^test.*"] # 以 ~ 字符开头，表示规则是正则表达式 -​ ignore-dbs: ["mysql"] - do-tables: - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "test" - tbl-name: "t" - ignore-tables: - - db-name: "test" - tbl-name: "log" -``` - -### 参数解释 - -- `do-dbs`：要同步的库的白名单，类似于 MySQL 中的 [`replicate-do-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-db)。 -- `ignore-dbs`：要同步的库的黑名单，类似于 MySQL 中的 [`replicate-ignore-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-db)。 -- `do-tables`：要同步的表的白名单，类似于 MySQL 中的 [`replicate-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-table)。 -- `ignore-tables`：要同步的表的黑名单，类似于 MySQL 中的 [`replicate-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-table)。 - -以上参数值以 `~` 开头时均支持使用[正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)来匹配库名、表名。 - -### 过滤规则 - -`do-dbs` 与 `ignore-dbs` 对应的过滤规则与 MySQL 中的 [Evaluation of Database-Level Replication and Binary Logging Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-db-options.html) 类似，`do-tables` 与 `ignore-tables` 对应的过滤规则与 MySQL 中的 [Evaluation of Table-Level Replication Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-table-options.html) 类似。 - -> **注意：** -> -> DM 中黑白名单过滤规则与 MySQL 中相应规则存在以下区别： -> -> - MySQL 中存在 [`replicate-wild-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-do-table) 与 [`replicate-wild-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-ignore-table) 用于支持通配符，DM 中各配置参数直接支持以 `~` 字符开头的正则表达式。 -> - DM 当前只支持 `ROW` 格式的 binlog，不支持 `STATEMENT`/`MIXED` 格式的 binlog，因此应与 MySQL 中 `ROW` 格式下的规则对应。 -> - 对于 DDL，MySQL 仅依据默认的 database 名称（`USE` 语句显式指定的 database）进行判断，而 DM 优先依据 DDL 中的 database 名称部分进行判断，并当 DDL 中不包含 database 名称时再依据 `USE` 部分进行判断。假设需要判断的 SQL 为 `USE test_db_2; CREATE TABLE test_db_1.test_table (c1 INT PRIMARY KEY)`，且 MySQL 配置了 `replicate-do-db=test_db_1`、DM 配置了 `do-dbs: ["test_db_1"]`，则对于 MySQL 该规则不会生效，而对于 DM 该规则会生效。 - -判断 table `test`.`t` 是否应该被过滤的过滤流程如下： - -1. 首先 **schema 过滤判断** - - - 如果 `do-dbs` 不为空，判断 `do-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则进入 **table 过滤判断**。 - - 如果不存在，则过滤 `test`.`t`。 - - - 如果 `do-dbs` 为空并且 `ignore-dbs` 不为空，判断 `ignore-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则过滤 `test`.`t`。 - - 如果不存在，则进入 **table 过滤判断**。 - - - 如果 `do-dbs` 和 `ignore-dbs` 都为空，则进入 **table 过滤判断**。 - -2. 进行 **table 过滤判断** - - 1. 如果 `do-tables` 不为空，判断 `do-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则同步 `test`.`t`。 - - 如果不存在，则过滤 `test`.`t`。 - - 2. 如果 `ignore-tables` 不为空，判断 `ignore-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则过滤 `test`.`t`. - - 如果不存在，则同步 `test`.`t`。 - - 3. 如果 `do-tables` 和 `ignore-tables` 都为空，则同步 `test`.`t`。 - -> **注意：** -> -> 判断 schema `test` 是否被过滤，只进行 **schema 过滤判断** - -### 使用示例 - -假设上游 MySQL 实例包含以下表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -``` - -配置如下： - -{{< copyable "" >}} - -```yaml -black-white-list: - bw-rule: - do-dbs: ["forum_backup_2018", "forum"] - ignore-dbs: ["~^forum_backup_"] - do-tables: - - db-name: "logs" - tbl-name: "~_2018$" - - db-name: "~^forum.*" -​ tbl-name: "messages" - ignore-tables: - - db-name: "~.*" -​ tbl-name: "^messages.*" -``` - -应用 `bw-rule` 规则后： - -| table | 是否过滤| 过滤的原因 | -|:----|:----|:--------------| -| `logs`.`messages_2016` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2017` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2018` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2016`.`messages` | 是 | schema `forum_backup_2016` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2017`.`messages` | 是 | schema `forum_backup_2017` 没有匹配到 `do-dbs` 任意一项 | -| `forum`.`users` | 是 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 没有匹配到 `do-tables` 和 `ignore-tables` 中任意一项，并且 `do-tables` 不为空，因此过滤 | -| `forum`.`messages` | 否 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | -| `forum_backup_2018`.`messages` | 否 | 1. schema `forum_backup_2018` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | - -## Binlog event filter - -Binlog event filter 是比同步表黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema / table` 的指定类型 binlog，比如 `INSERT`，`TRUNCATE TABLE`。 - -> **注意：** -> -> 同一个表匹配上多个规则，将会顺序应用这些规则，并且黑名单的优先级高于白名单，即如果同时存在规则 `Ignore` 和 `Do` 应用在某个 table 上，那么 `Ignore` 生效。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -filters: - rule-1: - schema-pattern: "test_*" - ​table-pattern: "t_*" - ​events: ["truncate table", "drop table"] - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - ​action: Ignore -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/dev/reference/tools/data-migration/table-selector.md)：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句进行以下规则过滤。 - -- `events`：binlog events 数组。 - - | Event | 分类 | 解释 | - | --------------- | ---- | ----------------------------- | - | all | | 代表包含下面所有的 events | - | all dml | | 代表包含下面所有 DML events | - | all ddl | | 代表包含下面所有 DDL events | - | none | | 代表不包含下面所有 events | - | none ddl | | 代表不包含下面所有 DDL events | - | none dml | | 代表不包含下面所有 DML events | - | insert | DML | insert DML event | - | update | DML | update DML event | - | delete | DML | delete DML event | - | create database | DDL | create database event | - | drop database | DDL | drop database event | - | create table | DDL | create table event | - | create index | DDL | create index event | - | drop table | DDL | drop table event | - | truncate table | DDL | truncate table event | - | rename table | DDL | rename table event | - | drop index | DDL | drop index event | - | alter table | DDL | alter table event | - -- `sql-pattern`：用于过滤指定的 DDL SQL 语句，支持正则表达式匹配，例如上面示例 `"^DROP\\s+PROCEDURE"`。 - -- `action`：string(`Do` / `Ignore`)；进行下面规则判断，满足其中之一则过滤，否则不过滤。 - - - `Do`：白名单。binlog event 如果满足下面两个条件之一就会被过滤掉： - - 不在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 没有匹配上 `sql-pattern` 中任意一项。 - - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉： - - 在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 可以匹配上 `sql-pattern` 中任意一项。 - -### 使用示例 - -#### 过滤分库分表的所有删除操作 - -需要设置下面两个 `Binlog event filter rule` 来过滤掉所有的删除操作： - -- `filter-table-rule` 过滤掉所有匹配到 pattern `test_*`.`t_*` 的 table 的 `turncate table`、`drop table`、`delete statement` 操作。 -- `filter-schema-rule` 过滤掉所有匹配到 pattern `test_*` 的 schema 的 `drop database` 操作。 - -{{< copyable "" >}} - -```yaml -filters: - filter-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - filter-schema-rule: - schema-pattern: "test_*" - events: ["drop database"] - action: Ignore -``` - -#### 只同步分库分表的 DML 操作 - -需要设置下面两个 `Binlog event filter rule` 只同步 DML 操作： - -- `do-table-rule` 只同步所有匹配到 pattern `test_*`.`t_*` 的 table 的 `create table`、`insert`、`update`、`delete` 操作。 -- `do-schema-rule` 只同步所有匹配到 pattern `test_*` 的 schema 的 `create database` 操作。 - -> **注意：** -> -> 同步 `create database/table` 的原因是创建库和表后才能同步 `DML`。 - -{{< copyable "" >}} - -```yaml -filters: - do-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["create table", "all dml"] - action: Do - do-schema-rule: - schema-pattern: "test_*" - events: ["create database"] - action: Do -``` - -#### 过滤 TiDB 不支持的 SQL 语句 - -可设置如下规则过滤 TiDB 不支持的 `PROCEDURE` 语句： - -{{< copyable "" >}} - -```yaml -filters: - filter-procedure-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - action: Ignore -``` - -#### 过滤 TiDB parser 不支持的 SQL 语句 - -对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 `schema`/`table` 信息，因此需要使用全局过滤规则：`schema-pattern: "*"`。 - -> **注意：** -> -> 全局过滤规则的设置必须尽可能严格，以避免预期之外地过滤掉需要同步的数据。 - -可设置如下规则过滤 TiDB parser 不支持的 `PARTITION` 语句： - -{{< copyable "" >}} - -```yaml -filters: - filter-partition-rule: - schema-pattern: "*" - sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"] - action: Ignore -``` - -## Column mapping - -> **注意：** -> -> 由于 Column mapping 的使用限制较多，我们不推荐使用 Column mapping 功能作为首选方案。我们优先推荐的方案请参考 [自增主键冲突处理](/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)。 - -Column mapping 提供对表的列值进行修改的功能。可以根据不同的表达式对表的指定列做不同的修改操作，目前只支持 DM 提供的内置表达式。 - -> **注意：** -> -> - 不支持修改 column 的类型和表结构。 -> - 不支持对同一个表设置多个不同的列值转换规则。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/dev/reference/tools/data-migration/table-selector.md)：对匹配上该规则的上游 MySQL/MariaDB 实例的表按照指定 `expression` 进行列值修改操作。 -- `source-column`，`target-column`：对 `source-column` 列的值按照指定 `expression` 进行修改，将修改后的值赋值给 `target-column`。 -- `expression`：对数据进行转换的表达式，目前只支持下面的内置计算表达式。 - -#### `partition id` 表达式 - -`partition id` 目的是为了解决分库分表合并同步的自增主键的冲突。 - -**`partition id` 限制** - -注意下面的限制： - -- 只支持类型为 bigint 的列，通常为自增主键，联合主键或者联合唯一索引的其中一列 -- 如果 `schema 前缀` 不为空，则库名的组成必须为 `schema 前缀` 或者 `schema 前缀 + 分隔符 + 数字（即 schema ID）`，例如：支持 `s` 和 `s_1`，不支持 `s_a` -- 如果 `table 前缀` 不为空，则表名的组成必须为 `table 前缀` 或者 `table 前缀 + 分隔符 + 数字（即 table ID）` -- 如果库名/表名不包含 `… + 分隔符 + 数字` 部分，则对应的 ID 默认为 0 -- 对分库分表的规模支持限制如下 - - 支持最多 16 个 MySQL/MariaDB 实例，且需要满足 0 <= instance ID <= 15。 - - 每个实例支持最多 128 个 schema，且需要满足 0 <= schema ID <= 127。 - - 每个实例的每个 schema 支持最多 256 个 table，且需要满足 0 <= table ID <= 255。 - - 进行 Column mapping 的列的范围需要满足 0 <= ID <= 17592186044415。 - - `{instance ID, schema ID, table ID}` 组合需要保持唯一。 -- 目前该功能是定制功能，如果需要调整请联系相关开发人员进行调整 - -**`partition id` 参数配置** - -用户需要在 arguments 里面按顺序设置以下三个或四个参数： - -- `instance_id`：客户指定的上游分库分表的 MySQL/MariaDB instance ID（0 <= instance ID <= 15） -- `schema 前缀`：用来解析库名并获取 `schema ID` -- `table 前缀`：用来解释表名并获取 `table ID` -- 分隔符：用来分隔前缀与 ID，可省略，省略时分隔符默认为空字符串 - -`instance_id`、`schema 前缀` 和 `table 前缀` 这三个参数均可被设置为空字符串（`""`），表示对应的部分不会被编码进 `partition id`。 - -**`partition id` 表达式规则** - -`partition id` 会用 arguments 里面的数字来填充自增主键 ID 的首个比特位，计算出来一个 int64（即 MySQL bigint）类型的值，具体规则如下： - -| instance_id | schema 前缀 | table 前缀 | 编码 | -|:------------|:--------------|:-------------|---------:| -| ☑ 已定义 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 44 比特位] | -| ☐ 空 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 48 比特位] | -| ☑ 已定义 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`T`: 8 比特位] [`P`: 51 比特位] | -| ☑ 已定义 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`P`: 52 比特位] | -| ☐ 空 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`T`: 8 比特位] [`P`: 55 比特位] | -| ☐ 空 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`D`: 7 比特位] [`P`: 56 比特位] | -| ☑ 已定义 | ☐ 空 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`P`: 59 比特位] | - -- `S`：符号位，保留 -- `I`：instance ID，默认 4 比特位 -- `D`：schema ID，默认 7 比特位 -- `T`：table ID，默认 8 比特位 -- `P`：自增主键 ID，占据剩下的比特位（≥44 比特位） - -### 使用示例 - -假设存在分库分表场景：将上游两个 MySQL 实例的 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t`，并且这些表都有自增主键。 - -需要设置下面两个规则： - -{{< copyable "" >}} - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -- MySQL instance 1 的表 `test_1`.`t_1` 的 `ID = 1` 的行经过转换后 ID = 1 变为 `1 << (64-1-4) | 1 << (64-1-4-7) | 1 << 44 | 1 = 580981944116838401` -- MySQL instance 2 的表 `test_1`.`t_2` 的 `ID = 1` 的行经过转换后 ID = 2 变为 `2 << (64-1-4) | 1 << (64-1-4-7) | 2 << 44 | 2 = 1157460288606306306` - -## 同步延迟监控 - -DM 支持通过 heartbeat 真实同步数据来计算每个同步任务与 MySQL/MariaDB 的实时同步延迟。 - -> **注意：** -> -> - 同步延迟的估算的精度在秒级别。 -> - heartbeat 相关的 binlog 不会同步到下游，在计算延迟后会被丢弃。 - -### 系统权限 - -如果开启 heartbeat 功能，需要上游 MySQL/MariaDB 实例提供下面的权限： - -- SELECT -- INSERT -- CREATE (databases, tables) - -### 参数配置 - -在 task 的配置文件中设置： - -``` -enable-heartbeat: true -``` - -### 原理介绍 - -- DM-worker 在对应的上游 MySQL/MariaDB 创建库 `dm_heartbeat`（当前不可配置） -- DM-worker 在对应的上游 MySQL/MariaDB 创建表 `heartbeat`（当前不可配置） -- DM-worker 每秒钟（当前不可配置）在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 表中，利用 `replace statement` 更新当前时间戳 `TS_master` -- DM-worker 每个任务拿到 `dm_heartbeat`.`heartbeat` 的 binlog 后，更新自己的同步时间 `TS_slave_task` -- DM-worker 每 10 秒在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 查询当前的 `TS_master`，并且对每个任务计算 `task_lag` = `TS_master` - `TS_slave_task` - -可以在 metrics 的 [binlog replication](/dev/reference/tools/data-migration/monitor.md#binlog-replication) 处理单元找到 replicate lag 监控项。 diff --git a/dev/reference/tools/data-migration/features/shard-merge.md b/dev/reference/tools/data-migration/features/shard-merge.md deleted file mode 100644 index fa33669463c3..000000000000 --- a/dev/reference/tools/data-migration/features/shard-merge.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: 分库分表合并同步 -category: reference ---- - -# 分库分表合并同步 - -本文介绍了 DM 提供的分库分表合并同步功能。此功能用于将上游 MySQL/MariaDB 实例中结构相同的表同步到下游 TiDB 的同一个表中。DM 不仅支持同步上游的 DML 数据，也支持协调同步多个上游分表的 DDL 表结构变更。 - -> **注意：** -> -> 要执行分库分表合并同步任务，必须在任务配置文件中设置 `is-sharding: true`。 - -## 使用限制 - -DM 进行分表 DDL 的同步有以下几点使用限制： - -- 在一个逻辑 sharding group（需要合并同步到下游同一个表的所有分表组成的 group）内，所有上游分表必须以相同的顺序执行相同的 DDL 语句（库名和表名可以不同），并且只有在所有分表执行完当前一条 DDL 语句后，下一条 DDL 语句才能执行。 - - - 比如，如果在 table_1 表中先增加列 a 后再增加列 b，则在 table_2 表中就不能先增加列 b 后再增加列 a，因为 DM 不支持以不同的顺序来执行相同的 DDL 语句。 - -- 对于每个逻辑 sharding group，推荐使用一个独立的任务进行同步。 - - - 如果一个任务内存在多个 sharding group，则必须等待一个 sharding group 的 DDL 语句同步完成后，才能开始对其他 sharding group 执行 DDL 语句。 - -- 在一个逻辑 sharding group 内，所有上游分表都应该执行对应的 DDL 语句。 - - - 比如，若 DM-worker-2 对应的一个或多个上游分表未执行 DDL 语句，则其他已执行 DDL 语句的 DM-worker 都会暂停同步任务，直到等到 DM-worker-2 收到上游对应的 DDL 语句。 - -- sharding group 数据同步任务不支持 `DROP DATABASE/TABLE` 语句。 - - - DM-worker 中的 binlog 同步单元（sync）会自动忽略掉上游分表的 `DROP DATABASE` 和 `DROP TABLE` 语句。 - -- sharding group 数据同步任务支持 `RENAME TABLE` 语句，但有如下限制（online DDL 中的 `RENAME` 有特殊方案进行支持）： - - - 只支持 `RENAME TABLE` 到一个不存在的表。 - - 一条 `RENAME TABLE` 语句只能包含一个 `RENAME` 操作。 - -- 增量同步任务需要确认开始同步的 binlog position 上各分表的表结构必须一致，才能确保来自不同分表的 DML 语句能够同步到表结构确定的下游，并且后续各分表的 DDL 语句能够正确匹配与同步。 - -- 如果需要变更 [table routing 规则](/dev/reference/tools/data-migration/features/overview.md#table-routing)，必须先等所有 sharding DDL 语句同步完成。 - - - 在 sharding DDL 语句同步过程中，使用 dmctl 尝试变更 router-rules 会报错。 - -- 如果需要创建新表加入到一个正在执行 DDL 语句的 sharding group 中，则必须保持新表结构和最新更改的表结构一致。 - - - 比如，原 table_1, table_2 表初始时有 (a, b) 两列，sharding DDL 语句执行后有 (a, b, c) 三列，则同步完成后新创建的表也应当有 (a, b, c) 三列。 - -- 由于已经收到 DDL 语句的 DM-worker 会暂停任务以等待其他 DM-worker 收到对应的 DDL 语句，因此数据同步延迟会增加。 - -## 背景 - -目前，DM 使用 ROW 格式的 binlog 进行数据同步，且 binlog 中不包含表结构信息。在 ROW 格式的 binlog 同步过程中，如果不需要将多个上游表合并同步到下游的同一个表，则只存在一个上游表的 DDL 语句会更新对应下游表结构。ROW 格式的 binlog 可以认为是具有 self-description 属性。 - -分库分表合并同步过程中，可以根据 column values 及下游的表结构构造出相应的 DML 语句，但此时若上游的分表执行 DDL 语句进行了表结构变更，则必须对该 DDL 语句进行额外同步处理，以避免因为表结构和 binlog 数据不一致而造成同步出错的问题。 - -以下是一个简化后的例子： - -![shard-ddl-example-1](/media/shard-ddl-example-1.png) - -在上图的例子中，分表的合库合表过程简化成了上游只有两个 MySQL 实例，每个实例内只有一个表。假设在数据同步开始时，将两个分表的表结构版本记为 schema V1，将 DDL 语句执行完后的表结构版本记为 schema V2。 - -现在，假设数据同步过程中，DM-worker 内的 binlog 同步单元（sync）从两个上游分表收到的 binlog 数据有如下时序： - -1. 开始同步时，sync 从两个分表收到的都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到实例 1 上分表的 DDL 语句。 - -3. 从 t2 时刻开始，sync 从实例 1 收到的是 schema V2 版本的 DML 语句；但从实例 2 收到的仍是 schema V1 版本的 DML 语句。 - -4. 在 t3 时刻，sync 收到实例 2 上分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从实例 2 收到的也是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当实例 1 的 DDL 语句同步到下游后，下游的表结构会变更成为 schema V2 版本。但在 t2 到 t3 这段时间内，sync 从实例 2 上收到的仍是 schema V1 版本的 DML 语句。当尝试把这些 schema V1 版本的 DML 语句同步到下游时，就会由于 DML 语句与表结构的不一致而发生错误，从而无法正确同步数据。 - -## 实现原理 - -基于上述例子，本部分介绍了 DM 在合库合表过程中进行 DDL 同步的实现原理。 - -![shard-ddl-flow](/media/shard-ddl-flow.png) - -在这个例子中，DM-worker-1 负责同步来自 MySQL 实例 1 的数据，DM-worker-2 负责同步来自 MySQL 实例 2 的数据，DM-master 负责协调多个 DM-worker 间的 DDL 同步。 - -从 DM-worker-1 收到 DDL 语句开始，简化后的 DDL 同步流程为： - -1. 在 t1 时刻，DM-worker-1 收到来自 MySQL 实例 1 的 DDL 语句，自身暂停该 DDL 语句对应任务的 DDL 及 DML 数据同步，并将 DDL 相关信息发送给 DM-master。 - -2. DM-master 根据收到的 DDL 信息判断得知需要协调该 DDL 语句的同步，于是为该 DDL 语句创建一个锁，并将 DDL 锁信息发回给 DM-worker-1，同时将 DM-worker-1 标记为这个锁的 owner。 - -3. DM-worker-2 继续进行 DML 语句的同步，直到在 t3 时刻收到来自 MySQL 实例 2 的 DDL 语句，自身暂停该 DDL 语句对应任务的数据同步，并将 DDL 相关信息发送给 DM-master。 - -4. DM-master 根据收到的 DDL 信息判断得知该 DDL 语句对应的锁信息已经存在，于是直接将对应锁信息发回给 DM-worker-2。 - -5. 根据任务启动时的配置信息、上游 MySQL 实例分表信息、部署拓扑信息等，DM-master 判断得知自身已经收到了来自待合表的所有上游分表的 DDL 语句，于是请求 DDL 锁的 owner（DM-worker-1）向下游同步执行该 DDL。 - -6. DM-worker-1 根据第二步收到的 DDL 锁信息验证 DDL 语句执行请求；向下游执行 DDL，并将执行结果反馈给 DM-master；若 DDL 语句执行成功，则自身开始继续同步后续的（从 t2 时刻对应的 binlog 开始的）DML 语句。 - -7. DM-master 收到来自 owner 执行 DDL 语句成功的响应，于是请求在等待该 DDL 锁的所有其他 DM-worker（DM-worker-2）忽略该 DDL 语句，直接继续同步后续的（从 t4 时刻对应的 binlog 开始的）DML 语句。 - -根据上面的流程，可以归纳出 DM 协调多个 DM-worker 间 sharding DDL 同步的特点： - -- 根据任务配置与 DM 集群部署拓扑信息，DM-master 内部也会建立一个逻辑 sharding group 来协调 DDL 同步，group 中的成员为负责处理该同步任务拆解后的各子任务的 DM-worker。 - -- 各 DM-worker 从 binlog event 中收到 DDL 语句后，会将 DDL 信息发送给 DM-master。 - -- DM-master 根据来自 DM-worker 的 DDL 信息及 sharding group 信息创建或更新 DDL 锁。 - -- 如果 sharding group 的所有成员都收到了某一条相同的 DDL 语句，则表明上游分表在该 DDL 执行前的 DML 语句都已经同步完成，此时可以执行该 DDL 语句，并继续后续的 DML 同步。 - -- 上游所有分表的 DDL 在经过 [table router](/dev/reference/tools/data-migration/features/overview.md#table-routing) 转换后需要保持一致，因此仅需 DDL 锁的 owner 执行一次该 DDL 语句即可，其他 DM-worker 可直接忽略对应的 DDL 语句。 - -在上面的示例中，每个 DM-worker 对应的上游 MySQL 实例中只有一个待合并的分表。但在实际场景下，一个 MySQL 实例可能有多个分库内的多个分表需要进行合并，这种情况下，sharding DDL 的协调同步过程将更加复杂。 - -假设同一个 MySQL 实例中有 table_1 和 table_2 两个分表需要进行合并： - -![shard-ddl-example-2](/media/shard-ddl-example-2.png) - -在这个例子中，由于数据来自同一个 MySQL 实例，因此所有数据都是从同一个 binlog 流中获得，时序如下： - -1. 开始同步时，DM-worker 内的 sync 从两个分表收到的数据都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到 table_1 分表的 DDL 语句。 - -3. 从 t2 到 t3 时刻，sync 收到的数据同时包含 table_1 的 DML 语句（schema V2 版本）及 table_2 的 DML 语句（schema V1 版本）。 - -4. 在 t3 时刻，sync 收到 table_2 分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从两个分表收到的数据都是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当 table_1 的 DDL 语句同步到下游从而变更下游表结构后，table_2 的 DML 语句（schema V1 版本）将无法正常同步。因此，在单个 DM-worker 内部，我们也构造了与 DM-master 内类似的逻辑 sharding group，但 group 的成员是同一个上游 MySQL 实例的不同分表。 - -DM-worker 内协调处理 sharding group 的同步与 DM-master 处理 DM-worker 之间的同步不完全一致，主要原因包括： - -- 当 DM-worker 收到 table_1 分表的 DDL 语句时，同步不能暂停，需要继续解析 binlog 才能获得后续 table_2 分表的 DDL 语句，即需要从 t2 时刻继续解析直到 t3 时刻。 - -- 在继续解析 t2 到 t3 时刻的 binlog 的过程中，table_1 分表的 DML 语句（schema V2 版本）不能向下游同步；但当 sharding DDL 同步并执行成功后，这些 DML 语句则需要同步到下游。 - -DM-worker 内部 sharding DDL 同步的简化流程为： - -1. 在 t1 时刻，DM-worker 收到 table_1 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -2. DM-worker 继续向前解析 t2 到 t3 时刻的 binlog。 - -3. 对于 table_1 的 DML 语句（schema V2 版本），忽略；对于 table_2 的 DML 语句（schema V1 版本），正常同步到下游。 - -4. 在 t3 时刻，DM-worker 收到 table_2 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -5. 根据同步任务配置信息、上游库表信息等，DM-worker 判断得知该 MySQL 实例上所有分表的 DDL 语句都已收到；于是将该 DDL 语句同步到下游执行并变更下游表结构。 - -6. DM-worker 设置 binlog 流的新解析起始位置点为第一步时保存的位置点。 - -7. DM-worker 重新开始解析从 t2 到 t3 时刻的 binlog。 - -8. 对于 table_1 的 DML 语句（schema V2 版本），正常同步到下游；对于 table_2 的 DML 语句（schema V1 版本），忽略。 - -9. 解析到达第四步时保存的 binlog 位置点，可得知在第三步时被忽略的所有 DML 语句都已经重新同步到下游。 - -10. DM-worker 继续从 t4 时刻对应的 binlog 位置点开始正常同步。 - -综上可知，DM 在处理 sharding DDL 同步时，主要通过两级 sharding group 来进行协调控制，简化的流程为： - -1. 各 DM-worker 独立地协调对应上游 MySQL 实例内多个分表组成的 sharding group 的 DDL 同步。 - -2. 当 DM-worker 收到所有分表的 DDL 语句时，向 DM-master 发送 DDL 相关信息。 - -3. DM-master 根据 DM-worker 发来的 DDL 信息，协调由各 DM-worker 组成的 sharing group 的 DDL 同步。 - -4. 当 DM-master 收到所有 DM-worker 的 DDL 信息时，请求 DDL 锁的 owner（某个 DM-worker） 执行该 DDL 语句。 - -5. DDL 锁的 owner 执行 DDL 语句，并将结果反馈给 DM-master；自身开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -6. 当 DM-master 收到 owner 执行 DDL 成功的消息后，请求其他所有 DM-worker 继续开始同步。 - -7. 其他所有 DM-worker 各自开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -8. 在完成被忽略的 DML 语句的重新同步后，所有 DM-worker 继续正常同步。 diff --git a/dev/reference/tools/data-migration/from-aurora.md b/dev/reference/tools/data-migration/from-aurora.md deleted file mode 100644 index 15d6fbb259bb..000000000000 --- a/dev/reference/tools/data-migration/from-aurora.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 从 AWS Aurora MySQL 迁移数据 -summary: 使用 DM 从 AWS Aurora MySQL 迁移数据。 -category: reference ---- - -# 从 AWS Aurora MySQL 迁移数据 - -本文介绍如何使用 DM 从 [AWS Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/dev/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 - - {{< copyable "" >}} - - ```bash - » start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "" >}} - -```bash -» query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ```bash -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 task.yaml 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/dev/reference/tools/data-migration/glossary.md b/dev/reference/tools/data-migration/glossary.md deleted file mode 100644 index f245fab65a39..000000000000 --- a/dev/reference/tools/data-migration/glossary.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: TiDB Data Migration 术语表 -summary: 学习 TiDB Data Migration 相关术语 -category: glossary ---- - -# TiDB Data Migration 术语表 - -本文档介绍 TiDB Data Migration (TiDB DM) 相关术语。 - -## B - -### Binlog - -在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/internals/en/binary-log.html) 与 [MariaDB Binary Log](https://mariadb.com/kb/en/library/binary-log/)。 - -### Binlog event - -MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/internals/en/binlog-event.html) 与 [MariaDB Binlog Event](https://mariadb.com/kb/en/library/1-binlog-events/)。 - -### Binlog event filter - -比 Black & white table list 更加细粒度的过滤功能，具体可参考 [Binlog event filter](/dev/reference/tools/data-migration/overview.md#binlog-event-filter)。 - -### Binlog position - -特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/kb/en/library/show-binlog-events/)。 - -### Binlog replication 处理单元 - -DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游的处理单元，每个 Subtask 对应一个 Binlog replication 处理单元。在当前文档中，有时也称作 Sync 处理单元。 - -### Black & white table list - -针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Black & white table lists](/dev/reference/tools/data-migration/overview.md#black--white-table-lists)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。 - -## C - -### Checkpoint - -TiDB DM 在全量导入与增量复制过程中的断点信息，用于在重新启动或恢复任务时从之前已经处理过的位置继续执行。 - -- 对于全量导入，Checkpoint 信息对应于每个数据文件已经被成功导入的数据对应的文件内偏移量等信息，其在每个导入数据的事务中同步更新； -- 对于增量复制，Checkpoint 信息对应于已经成功解析并导入到下游的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 等信息，其在 DDL 导入成功后或距上次更新时间超过 30 秒等条件下更新。 - -另外，[Relay 处理单元](#relay-处理单元) 对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#GTID) 信息。 - -## D - -### Dump 处理单元 - -DM-worker 内部用于从上游导出全量数据的处理单元，每个 Subtask 对应一个 Dump 处理单元。 - -## G - -### GTID - -MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/kb/en/library/gtid/)。 - -## H - -### Heartbeat - -在增量数据迁移过程中，用于估算数据从在上游写入后到达 Binlog replication 处理单元延迟时间的机制，具体可参考[同步延迟监控](/dev/reference/tools/data-migration/features/overview.md#同步延迟监控)。 - -## L - -### Load 处理单元 - -DM-worker 内部用于将全量导出数据导入到下游的处理单元，每个 Subtask 对应一个 Load 处理单元。在当前文档中，有时也称作 Import 处理单元。 - -## R - -### Relay log - -DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/kb/en/library/relay-log/) 相近。 - -有关 TiDB DM 内 Relay log 的目录结构、初始同步规则、数据清理等内容，可参考 [TiDB DM Relay Log](https://pingcap.com/docs-cn/stable/reference/tools/data-migration/relay-log/)。 - -### Relay 处理单元 - -DM-worker 内部用于从上游拉取 Binlog 并写入数据到 Relay log 的处理单元，每个 DM-worker 实例内部仅存在一个该处理单元。 - -## S - -### Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在启动或恢复增量迁移任务的前 5 分钟 TiDB DM 会自动启动 Safe mode，另外也可以在任务配置文件中通过 `safe-mode` 参数手动开启。 - -### Shard DDL - -指合库合表迁移过程中，在上游各分表 (shard) 上执行的需要 TiDB DM 进行协调迁移的 DDL。在当前文档中，有时也称作 Sharding DDL。 - -### Shard DDL lock - -用于协调 Shard DDL 迁移的锁机制，具体原理可查看[分库分表合并同步实现原理](/dev/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding DDL lock。 - -### Shard group - -指合库合表迁移过程中，需要合并迁移到下游同一张表的所有上游分表 (shard)，TiDB DM 内部具体实现时使用了两级抽象的 Shard group，具体可查看[分库分表合并同步实现原理](/dev/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding group。 - -### Subtask - -数据迁移子任务，即数据迁移任务运行在单个 DM-worker 实例上的部分。根据任务配置的不同，单个数据迁移任务可能只有一个子任务，也可能有多个子任务。 - -### Subtask status - -数据迁移子任务所处的状态，目前包括 `New`、`Running`、`Paused`、`Stopped` 及 `Finished` 5 种状态。有关数据迁移任务、子任务状态的更多信息可参考[任务状态](/dev/reference/tools/data-migration/query-status.md#任务状态)。 - -## T - -### Table routing - -用于支持将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步，具体可参考 [Table routing](/dev/reference/tools/data-migration/features/overview.md#table-routing)。 - -### Task - -数据迁移任务，执行 `start-task` 命令成功后即启动一个数据迁移任务。根据任务配置的不同，单个数据迁移任务既可能只在单个 DM-worker 实例上运行，也可能同时在多个 DM-worker 实例上运行。 - -### Task status - -数据迁移子任务所处的状态，由 [Subtask status](#subtask-status) 整合而来，具体信息可查看[任务状态](/dev/reference/tools/data-migration/query-status.md#任务状态)。 diff --git a/dev/reference/tools/data-migration/manage-tasks.md b/dev/reference/tools/data-migration/manage-tasks.md deleted file mode 100644 index 579f7afba2d3..000000000000 --- a/dev/reference/tools/data-migration/manage-tasks.md +++ /dev/null @@ -1,956 +0,0 @@ ---- -title: 管理数据同步任务 -category: reference ---- - -# 管理数据同步任务 - -本文介绍了如何使用 [dmctl](/dev/reference/tools/data-migration/overview.md#dmctl) 组件来进行数据同步任务的管理和维护。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 `dm-ansible/dmctl`。 - -dmctl 支持交互模式用于人工操作，同时也支持命令模式用于脚本。 - -## dmctl 交互模式 - -本部分描述了在交互模式下一些 dmctl 命令的基本用法。 - -### dmctl 使用帮助 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl --help -``` - -``` -Usage of dmctl: - -V prints version and exit - -config string - path to config file - # 按照 DM 提供的加密方法加密数据库密码，用于 DM 的配置文件 - -encrypt string - encrypt plaintext to ciphertext - # DM-master 访问地址，dmctl 与 DM-master 交互以完成任务管理操作 - -master-addr string - master API server addr - -rpc-timeout string - rpc timeout, default is 10m (default "10m") -``` - -### 加密数据库密码 - -在 DM 相关配置文件中，要求必须使用经 dmctl 加密后的密码，否则会报错。对于同一个原始密码，每次加密后密码不同。 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -### 任务管理概览 - -进入交互模式，与 DM-master 进行交互： - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 - -» help -DM control - -Usage: - dmctl [command] - -Available Commands: - break-ddl-lock forcefully break DM-worker's DDL lock - check-task check the config file of the task - help help about any command - migrate-relay migrate DM-worker's relay unit - pause-relay pause DM-worker's relay unit - pause-task pause a specified running task - purge-relay purge relay log files of the DM-worker according to the specified filename - query-error query task error - query-status query task status - refresh-worker-tasks refresh worker -> tasks mapper - resume-relay resume DM-worker's relay unit - resume-task resume a specified paused task - show-ddl-locks show un-resolved DDL locks - sql-inject inject (limited) SQLs into binlog replication unit as binlog events - sql-replace replace SQLs matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern); each SQL must end with a semicolon - sql-skip skip the binlog event matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern) - start-task start a task as defined in the config file - stop-task stop a specified task - switch-relay-master switch the master server of the DM-worker's relay unit - unlock-ddl-lock forcefully unlock DDL lock - update-master-config update the config of the DM-master - update-relay update the relay unit config of the DM-worker - update-task update a task's config for routes, filters, or black-white-list - -Flags: - -h, --help help for dmctl - -w, --worker strings DM-worker ID - -# 使用 `dmctl [command] --help` 来获取某个命令的更多信息 -``` - -## 管理数据同步任务 - -本部分描述了如何使用不同的任务管理命令来执行相应操作。 - -### 创建数据同步任务 - -`start-task` 命令用于创建数据同步任务。 当数据同步任务启动时，DM 将[自动对相应权限和配置进行前置检查](/dev/reference/tools/data-migration/precheck.md)。 - -{{< copyable "" >}} - -```bash -help start-task -``` - -``` -start a task as defined in the config file - -Usage: - dmctl start-task [-w worker ...] [flags] - -Flags: - -h, --help help for start-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -start-task [ -w "172.16.30.15:8262"] ./task.yaml -``` - -#### 参数解释 - -+ `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上执行 `task.yaml` - - 如果设置，则只启动指定任务在该组 DM-workers 上的子任务 -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -start-task task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -### 查询数据同步任务状态 - -`query-status` 命令用于查询数据同步任务状态。有关查询结果及子任务状态，详见[查询状态](/dev/reference/tools/data-migration/query-status.md)。 - -{{< copyable "" >}} - -```bash -help query-status -``` - -``` -query task status - -Usage: - dmctl query-status [-w worker ...] [task-name] [flags] - -Flags: - -h, --help help for query-status - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -query-status -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 查询在指定的一组 DM-workers 上运行的数据同步任务的子任务 -- `task-name`： - - 可选 - - 指定任务名称 - - 如果未设置，则返回全部数据同步任务的查询结果 - -#### 返回结果示例 - -有关查询结果中各参数的意义，详见[查询状态结果](/dev/reference/tools/data-migration/query-status.md#查询结果)。 - -### 查询运行错误 - -`query-error` 可用于查询数据同步任务与 relay 处理单元的错误信息。相比于 `query-status`，`query-error` 一般不用于获取除错误信息之外的其他信息。 - -`query-error` 常用于获取 `sql-skip`/`sql-replace` 所需的 binlog position 信息，有关 `query-error` 的参数与结果解释，请参考 [跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 文档中的 query-error](/dev/reference/tools/data-migration/skip-replace-sqls.md#query-error)。 - -### 暂停数据同步任务 - -`pause-task` 命令用于暂停数据同步任务。 - -> **注意：** -> -> 有关 `pause-task` 与 `stop-task` 的区别如下： -> -> - 使用 `pause-task` 仅暂停同步任务的执行，但仍然会在内存中保留任务的状态信息等，且可通过 `query-status` 进行查询；使用 `stop-task` 会停止同步任务的执行，并移除内存中与该任务相关的信息，且不可再通过 `query-status` 进行查询，但不会移除已经写入到下游数据库中的数据以及其中的 checkpoint 等 `dm_meta` 信息。 -> - 使用 `pause-task` 暂停同步任务期间，由于任务本身仍然存在，因此不能再启动同名的新任务，且会阻止对该任务所需 relay log 的清理；使用 `stop-task` 停止任务后，由于任务不再存在，因此可以再启动同名的新任务，且不会阻止对 relay log 的清理。 -> - `pause-task` 一般用于临时暂停同步任务以排查问题等；`stop-task` 一般用于永久删除同步任务或通过与 `start-task` 配合以更新配置信息。 - -{{< copyable "" >}} - -```bash -help pause-task -``` - -``` -pause a specified running task - -Usage: - dmctl pause-task [-w worker ...] [flags] - -Flags: - -h, --help help for pause-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上暂停数据同步任务的子任务 - - 如果设置，则只暂停该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-task test -``` - -``` -{ - "op": "Pause", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - } - ] -} -``` - -### 恢复数据同步任务 - -`resume-task` 命令用于恢复处于 `Paused` 状态的数据同步任务，通常用于在人为处理完造成同步任务暂停的故障后手动恢复同步任务。 - -{{< copyable "" >}} - -```bash -help resume-task -``` - -``` -resume a specified paused task - -Usage: - dmctl resume-task [-w worker ...] [flags] - -Flags: - -h, --help help for resume-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上恢复数据同步任务的子任务 - - 如果设置，则只恢复该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-task test -``` - -``` -{ - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - } - ] -} -``` - -### 停止数据同步任务 - -`stop-task` 命令用于停止数据同步任务。有关 `stop-task` 与 `pause-task` 的区别，请参考[暂停数据同步任务](#暂停数据同步任务)中的相关说明。 - -{{< copyable "" >}} - -```bash -help stop-task -``` - -``` -stop a specified task - -Usage: - dmctl stop-task [-w worker ...] [flags] - -Flags: - -h, --help help for stop-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -stop-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上停止数据同步任务的子任务 - - 如果设置，则只停止该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -stop-task test -``` - -``` -{ - "op": "Stop", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - } - ] -} -``` - -### 更新数据同步任务 - -`update-task` 命令用于更新数据同步任务。 - -支持的更新项包括： - -- Table routing 规则 -- Black & white table lists 规则 -- Binlog event filter 规则 - -其余项均不支持更新。 - -> **注意：** -> -> 如果能确保同步任务所需的 relay log 在任务停止期间不会被清理，则推荐使用[不支持更新项的更新步骤](#不支持更新项的更新步骤)来以统一的方式更新任务配置信息。 - -#### 支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若 `stage` 不为 `Paused`，则先使用 `pause-task ` 暂停任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `update-task task.yaml` 更新任务配置。 - -4. 使用 `resume-task ` 恢复任务。 - -#### 不支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若任务存在，则通过 `stop-task ` 停止任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `start-task ` 重启恢复任务。 - -{{< copyable "" >}} - -```bash -help update-task -``` - -``` -update a task's config for routes, filters, or black-white-list - -Usage: - dmctl update-task [-w worker ...] [flags] - -Flags: - -h, --help help for update-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -update-task [-w "127.0.0.1:8262"] ./task.yaml -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上更新数据同步任务的子任务 - - 如果设置，则只更新指定 DM-workers 上的子任务配置 -- `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -update-task task_all_black.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -## 管理 DDL lock - -目前与 DDL lock 相关的命令主要包括 `show-ddl-locks`、`unlock-ddl-lock`、`break-ddl-lock` 等。有关它们的功能、用法以及适用场景等，请参考[手动处理 sharding DDL lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 其他任务与集群管理命令 - -除上述常用的任务管理命令外，DM 还提供了其他一些命令用于管理数据同步任务或 DM 集群本身。 - -### 检查任务配置文件 - -`check-task` 命令用于检查指定的数据同步任务配置文件（`task.yaml`）是否合法以及上下游数据库的配置、权限、表结构等是否满足同步需要。具体可参考[上游 MySQL 实例配置前置检查](/dev/reference/tools/data-migration/precheck.md)。 - -在使用 `start-task` 启动同步任务时，DM 也会执行 `check-task` 所做的全部检查。 - -{{< copyable "" >}} - -```bash -help check-task -``` - -``` -check the config file of the task - -Usage: - dmctl check-task [flags] - -Flags: - -h, --help help for check-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -check-task task.yaml -``` - -#### 参数解释 - -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -check-task task-test.yaml -``` - -``` -{ - "result": true, - "msg": "check pass!!!" -} -``` - -### 暂停 relay 处理单元 - -relay 处理单元在 DM-worker 进程启动后即开始自动运行。通过使用 `pause-relay` 命令，我们可以暂停 relay 处理单元的运行。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `pause-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help pause-relay -``` - -``` -pause DM-worker's relay unit - -Usage: - dmctl pause-relay <-w worker ...> [flags] - -Flags: - -h, --help help for pause-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要暂停 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "PauseRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 恢复 relay 处理单元 - -`resume-relay` 用于恢复处于 `Paused` 状态的 relay 处理单元。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `resume-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help resume-relay -``` - -``` -resume DM-worker's relay unit - -Usage: - dmctl resume-relay <-w worker ...> [flags] - -Flags: - -h, --help help for resume-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要恢复 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "ResumeRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 切换 relay log 到新的子目录 - -relay 处理单元通过使用不同的子目录来存储来自上游不同 MySQL 实例的 binlog 数据。通过使用 `switch-relay-master` 命令，我们可以变更 relay 处理单元以开始使用一个新的子目录。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `switch-relay-master` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help switch-relay-master -``` - -``` -switch the master server of the DM-worker's relay unit - -Usage: - dmctl switch-relay-master <-w worker ...> [flags] - -Flags: - -h, --help help for switch-relay-master - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要切换 relay 处理单元使用子目录的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "172.16.30.15:8262" -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 手动清理 relay log - -DM 支持[自动清理 relay log](/dev/reference/tools/data-migration/relay-log.md#自动数据清理)，但同时 DM 也支持使用 `purge-relay` 命令[手动清理 relay log](/dev/reference/tools/data-migration/relay-log.md#手动数据清理)。 - -{{< copyable "" >}} - -```bash -help purge-relay -``` - -``` -purge relay log files of the DM-worker according to the specified filename - -Usage: - dmctl purge-relay <-w worker> [--filename] [--sub-dir] [flags] - -Flags: - -f, --filename string name of the terminal file before which to purge relay log files. Sample format: "mysql-bin.000006" - -h, --help help for purge-relay - -s, --sub-dir string specify relay sub directory for --filename. If not specified, the latest one will be used. Sample format: "2ae76434-f79f-11e8-bde2-0242ac130008.000001" - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要执行 relay log 清理操作的 DM-worker -- `--filename`： - - 必选 - - 指定标识 relay log 将要停止清理的文件名。如指定为 `mysql-bin.000100`，则只尝试清理到 `mysql-bin.000099` -- `--sub-dir`： - - 可选 - - 指定 `--filename` 对应的 relay log 子目录，如果不指定则会使用当前最新的子目录 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -``` -[warn] no --sub-dir specified for --filename; the latest one will be used -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] -} -``` - -### 预设跳过 DDL 操作 - -`sql-skip` 命令用于预设一个跳过操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。相关参数与结果解释，请参考[`sql-skip`](/dev/reference/tools/data-migration/skip-replace-sqls.md#sql-skip)。 - -### 预设替换 DDL 操作 - -`sql-replace` 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替换执行操作。相关参数与结果解释，请参考[`sql-replace`](/dev/reference/tools/data-migration/skip-replace-sqls.md#sql-replace)。 - -### 强制刷新 `task => DM-workers` 映射关系 - -`refresh-worker-tasks` 命令用于强制刷新 DM-master 内存中维护的 `task => DM-workers` 映射关系。 - -> **注意：** -> -> 一般不需要使用此命令。仅当已确定 `task => DM-workers` 映射关系存在，但执行其它命令时仍提示必须刷新它时，你才需要使用此命令。 - -## dmctl 命令模式 - -命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。 - -> **注意：** -> -> + 一条 dmctl 命令只能跟一个任务操作 -> + 任务操作只能放在 dmctl 命令的最后 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 start-task task.yaml -./dmctl -master-addr 172.16.30.14:8261 stop-task task -./dmctl -master-addr 172.16.30.14:8261 query-status -``` - -``` -Available Commands: - break-ddl-lock break-ddl-lock <-w worker ...> [--remove-id] [--exec] [--skip] - check-task check-task - migrate-relay migrate-relay - pause-relay pause-relay <-w worker ...> - pause-task pause-task [-w worker ...] - purge-relay purge-relay <-w worker> [--filename] [--sub-dir] - query-error query-error [-w worker ...] [task-name] - query-status query-status [-w worker ...] [task-name] - refresh-worker-tasks refresh-worker-tasks - resume-relay resume-relay <-w worker ...> - resume-task resume-task [-w worker ...] - show-ddl-locks show-ddl-locks [-w worker ...] [task-name] - sql-inject sql-inject <-w worker> - sql-replace sql-replace <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - sql-skip sql-skip <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - start-task start-task [-w worker ...] - stop-task stop-task [-w worker ...] - switch-relay-master switch-relay-master <-w worker ...> - unlock-ddl-lock unlock-ddl-lock [-w worker ...] - update-master-config update-master-config - update-relay update-relay [-w worker ...] - update-task update-task [-w worker ...] -``` - -## 废弃或不推荐使用的命令 - -以下命令已经被废弃或仅用于 debug，在接下来的版本中可能会被移除或修改其语义，**强烈不推荐使用**。 - -- `migrate-relay` -- `sql-inject` -- `update-master-config` -- `update-relay` diff --git a/dev/reference/tools/data-migration/monitor.md b/dev/reference/tools/data-migration/monitor.md deleted file mode 100644 index a80acd21f294..000000000000 --- a/dev/reference/tools/data-migration/monitor.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: DM 监控指标 -summary: 介绍 DM 的监控指标 -category: reference ---- - -# DM 监控指标 - -使用 DM-Ansible 部署 DM 集群的时候，会默认部署一套[监控系统](/dev/reference/tools/data-migration/deploy.md#第-7-步监控任务与查看日志)。 - -> **注意：** -> -> 目前只有 DM-worker 提供了 metrics，DM-master 暂未提供。 - -## Task - -在 Grafana dashboard 中，DM 默认名称为 `DM-task`。 - -### overview - -overview 下包含运行当前选定 task 的所有 DM-worker instance 的部分监控指标。当前默认告警规则只针对于单个 DM-worker instance。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | N/A | N/A | -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | N/A | N/A | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -### task 状态 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时| critical | - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒| N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### Dump/Load unit - -下面 metrics 仅在 `task-mode` 为 `full` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| data file size | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的总大小 | N/A | N/A | -| dump process exits with error | dump unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| load process exits with error | load unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| table count | load unit 导入的全量数据中 table 的数量总和 | N/A | N/A | -| data file count | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的数量总和| N/A | N/A | -| latency of execute transaction | load unit 在执行事务的时延，单位：秒 | N/A | N/A | -| latency of query | load unit 执行 query 的耗时，单位：秒 | N/A | N/A | - -### Binlog replication - -下面 metrics 仅在 `task-mode` 为 `incremental` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| remaining time to sync | 预计 Syncer 还需要多少分钟可以和 master 完全同步，单位：分钟 | N/A | N/A | -| replicate lag | master 到 Syncer 的 binlog 复制延迟时间，单位：秒 | N/A | N/A | -| process exist with error | binlog replication 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| binlog file gap between master and syncer | 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog file gap between relay and syncer | 与 relay 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog event qps | 单位时间内接收到的 binlog event 数量 (不包含需要跳过的 event) | N/A | N/A | -| skipped binlog event qps | 单位时间内接收到的需要跳过的 binlog event 数量 | N/A | N/A | -| cost of binlog event transform | Syncer 解析并且转换 binlog 成 SQLs 的耗时，单位：秒 | N/A | N/A | -| total sqls jobs | 单位时间内新增的 job 数量 | N/A | N/A | -| finished sqls jobs | 单位时间内完成的 job 数量 | N/A | N/A | -| execution latency | Syncer 执行 transaction 到下游的耗时，单位：秒 | N/A | N/A | -| unsynced tables | 当前子任务内还未收到 shard DDL 的分表数量 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -## Instance - -在 Grafana dashboard 中，instance 的默认名称为 `DM-instance`。 - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒 | N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### task - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时 | critical | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | diff --git a/dev/reference/tools/data-migration/overview.md b/dev/reference/tools/data-migration/overview.md deleted file mode 100644 index 8f3a3b5ea6bb..000000000000 --- a/dev/reference/tools/data-migration/overview.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Data Migration 简介 -category: reference ---- - -# Data Migration 简介 - -[DM](https://github.com/pingcap/dm) (Data Migration) 是一体化的数据同步任务管理平台，支持从 MySQL 或 MariaDB 到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化错误处理流程，降低运维成本。 - -## DM 架构 - -DM 主要包括三个组件：DM-master，DM-worker 和 dmctl。 - -![Data Migration architecture](/media/dm-architecture.png) - -### DM-master - -DM-master 负责管理和调度数据同步任务的各项操作。 - -- 保存 DM 集群的拓扑信息 -- 监控 DM-worker 进程的运行状态 -- 监控数据同步任务的运行状态 -- 提供数据同步任务管理的统一入口 -- 协调分库分表场景下各个实例分表的 DDL 同步 - -### DM-worker - -DM-worker 负责执行具体的数据同步任务。 - -- 将 binlog 数据持久化保存在本地 -- 保存数据同步子任务的配置信息 -- 编排数据同步子任务的运行 -- 监控数据同步子任务的运行状态 - -DM-worker 启动后，会自动同步上游 binlog 至本地配置目录（如果使用 DM-Ansible 部署 DM 集群，默认的同步目录为 `/relay_log`）。关于 DM-worker，详见 [DM-worker 简介](/dev/reference/tools/data-migration/dm-worker-intro.md)。关于 relay log，详见 [DM Relay Log](/dev/reference/tools/data-migration/relay-log.md)。 - -### dmctl - -dmctl 是用来控制 DM 集群的命令行工具。 - -- 创建、更新或删除数据同步任务 -- 查看数据同步任务状态 -- 处理数据同步任务错误 -- 校验数据同步任务配置的正确性 - -## 同步功能介绍 - -下面简单介绍 DM 数据同步功能的核心特性。 - -### Table routing - -[Table routing](/dev/reference/tools/data-migration/features/overview.md#table-routing) 是指将上游 MySQL 或 MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步。 - -### Black & white table lists - -[Black & white table lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) 是指上游数据库实例表的黑白名单过滤规则。其过滤规则类似于 MySQL `replication-rules-db`/`replication-rules-table`，可以用来过滤或只同步某些数据库或某些表的所有操作。 - -### Binlog event filter - -[Binlog event filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) 是比库表同步黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema`/`table` 的指定类型的 binlog events，比如 `INSERT`，`TRUNCATE TABLE`。 - -### Shard support - -DM 支持对原分库分表进行合库合表操作，但需要满足一些[使用限制](/dev/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -## 使用限制 - -在使用 DM 工具之前，需了解以下限制： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - - > **注意：** - > - > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则 - > - > - 5.7.1 < MySQL 版本 < 8.0 - > - MariaDB 版本 >= 10.1.3 - - 在使用 dmctl 启动任务时，DM 会自动对任务上下游数据库的配置、权限等进行[前置检查](/dev/reference/tools/data-migration/precheck.md)。 - -+ DDL 语法 - - - 目前，TiDB 部分兼容 MySQL 支持的 DDL 语句。因为 DM 使用 TiDB parser 来解析处理 DDL 语句，所以目前仅支持 TiDB parser 支持的 DDL 语法。详见 [TiDB DDL 语法支持](/dev/reference/mysql-compatibility.md#ddl)。 - - - DM 遇到不兼容的 DDL 语句时会报错。要解决此报错，需要使用 dmctl 手动处理，要么跳过该 DDL 语句，要么用指定的 DDL 语句来替换它。详见[如何处理不兼容的 DDL 语句](/dev/reference/tools/data-migration/faq.md#如何处理不兼容的-ddl-语句)。 - -+ 分库分表 - - - 如果业务分库分表之间存在数据冲突，可以参考[自增主键冲突处理](/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决；否则不推荐使用 DM 进行同步，如果进行同步则有冲突的数据会相互覆盖造成数据丢失。 - - 关于分库分表合并场景的其它限制，参见[使用限制](/dev/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -+ 操作限制 - - - DM-worker 重启后不能自动恢复数据同步任务，需要使用 dmctl 手动执行 `start-task`。详见[管理数据同步任务](/dev/reference/tools/data-migration/manage-tasks.md)。 - - 在一些情况下，DM-worker 重启后不能自动恢复 DDL lock 同步，需要手动处理。详见[手动处理 Sharding DDL Lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -+ DM-worker 切换 MySQL - - - 当 DM-worker 通过虚拟 IP（VIP）连接到 MySQL 且要切换 VIP 指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。如需切换 VIP 指向的 MySQL 实例，请参考[虚拟 IP 环境下的上游主从切换](/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-ip-环境下切换-dm-worker-与-mysql-实例的连接)对 DM 手动执行变更。 diff --git a/dev/reference/tools/data-migration/precheck.md b/dev/reference/tools/data-migration/precheck.md deleted file mode 100644 index 4e02cc8abb52..000000000000 --- a/dev/reference/tools/data-migration/precheck.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 上游 MySQL 实例配置前置检查 -category: reference ---- - -# 上游 MySQL 实例配置前置检查 - -本文介绍了 DM 提供的前置检查功能，此功能用于在数据同步任务启动时提前检测出上游 MySQL 实例配置中可能存在的一些错误。 - -## 使用命令 - -`check-task` 命令用于对上游 MySQL 实例配置是否满足 DM 要求进行前置检查。 - -## 检查内容 - -上下游数据库用户必须具备相应读写权限。当数据同步任务启动时，DM 会自动检查下列权限和配置： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - -+ MySQL binlog 配置 - - - binlog 是否开启（DM 要求 binlog 必须开启） - - 是否有 `binlog_format=ROW`（DM 只支持 ROW 格式的 binlog 同步） - - 是否有 `binlog_row_image=FULL`（DM 只支持 `binlog_row_image=FULL`） - -+ 上游 MySQL 实例用户的权限 - - DM 配置中的 MySQL 用户至少需要具备以下权限： - - - REPLICATION SLAVE - - REPLICATION CLIENT - - RELOAD - - SELECT - -+ 上游 MySQL 表结构的兼容性 - - TiDB 和 MySQL 的兼容性存在以下一些区别： - - - TiDB 不支持外键 - - 字符集的兼容性不同，详见 [TiDB 支持的字符集](/dev/reference/sql/character-set.md) - -+ 上游 MySQL 多实例分库分表的一致性 - - + 所有分表的表结构是否一致，检查内容包括： - - - Column 数量 - - Column 名称 - - Column 位置 - - Column 类型 - - 主键 - - 唯一索引 - - + 分表中自增主键冲突检查 - - - 在两种情况下会造成检查失败： - - - 分表存在自增主键，且自增主键 column 类型不为 bigint - - 分表存在自增主键，自增主键 column 类型为 bigint，但没有为其配置列值转换 - - - 其他情况下检查将成功 diff --git a/dev/reference/tools/data-migration/query-status.md b/dev/reference/tools/data-migration/query-status.md deleted file mode 100644 index d733ae930068..000000000000 --- a/dev/reference/tools/data-migration/query-status.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: DM 查询状态 -category: reference ---- - -# DM 查询状态 - -本文介绍 DM（Data Migration）`query-status` 命令的查询结果、任务状态与子任务状态。 - -## 查询结果 - -{{< copyable "" >}} - -```bash -» query-status -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "tasks": [ # 迁移 task 列表 - { - "taskName": "test-1", # 任务名称 - "taskStatus": "Running", # 任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped”，“Finished” 以及 “Error”。 - "workers": [ # 该任务所使用的 DM-workers 列表 - "127.0.0.1:8262" - ] - }, - { - "taskName": "test-2", - "taskStatus": "Error - Some error occurred in subtask", # 该任务的子任务存在运行错误并暂停的现象 - "workers": [ - "127.0.0.1:8262", - "127.0.0.1:8263" - ] - }, - { - "taskName": "test-3", - "taskStatus": "Error - Relay status is Error", # 该任务的某个处于 Sync 阶段的子任务对应的 Relay 处理单元出错 - "workers": [ - "127.0.0.1:8263", - "127.0.0.1:8264" - ] - } - ] -} -``` - -关于 tasks 下的 taskStatus 状态的详细定义，请参阅[任务状态](#任务状态)。 - -推荐的 `query-status` 使用方法是： - -1. 首先使用 query-status 查看各个 task 的运行状态是否正常。 -2. 如果发现其中某一 task 状态有问题，通过 `query-status <出错任务的 taskName>` 来得到更详细的错误信息。 - -## 任务状态 - -DM 的迁移任务状态取决于其分配到 DM-worker 上的[子任务状态](#子任务状态)，定义见下表： - -| 任务对应的所有子任务的状态 | 任务状态 | -| :--- | :--- | -| 任一子任务处于 “Paused” 状态且返回结果有错误信息 | Error - Some error occurred in subtask | -| 任一处于 Sync 阶段的子任务处于 “Running” 状态但其 Relay 处理单元未运行（处于 Error/Paused/Stopped 状态） | Error - Relay status is Error/Paused/Stopped | -| 任一子任务处于 “Paused” 状态且返回结果没有错误信息 | Paused | -| 所有子任务处于 “New” 状态 | New | -| 所有子任务处于 “Finished” 状态 | Finished | -| 所有子任务处于 “Stopped” 状态 | Stopped | -| 其他情况 | Running | - -## 详情查询结果 - -{{< copyable "" >}} - -```bash -» query-status test -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "workers": [ # DM-worker 列表。 - { - "result": true, - "worker": "172.17.0.2:8262", # DM-worker ID。 - "msg": "", - "subTaskStatus": [ # DM-worker 所有子任务的信息。 - { - "name": "test", # 子任务名称。 - "stage": "Running", # 子任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped” 以及 “Finished”。 - "unit": "Sync", # DM 的处理单元，包括 “Check”，“Dump“，“Load” 以及 “Sync”。 - "result": null, # 子任务失败时显示错误信息。 - "unresolvedDDLLockID": "test-`test`.`t_target`", # sharding DDL lock ID，可用于异常情况下手动处理 sharding DDL lock。 - "sync": { # 当前 `Sync` 处理单元的同步信息。 - "totalEvents": "12", # 该子任务中同步的 binlog event 总数。 - "totalTps": "1", # 该子任务中每秒同步的 binlog event 数量。 - "recentTps": "1", # 该子任务中最后一秒同步的 binlog event 数量。 - "masterBinlog": "(bin.000001, 3234)", # 上游数据库当前的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库当前的 GTID 信息。 - "syncerBinlog": "(bin.000001, 2525)", # 已被 `Sync` 处理单元同步的 binlog position。 - "syncerBinlogGtid": "", # 当前版本总是为空（因为 `Sync` 处理单元暂不使用 GTID 同步数据）。 - "blockingDDLs": [ # 当前被阻塞的 DDL 列表。该项仅在当前 DM-worker 所有上游表都处于 “synced“ 状态时才有数值，此时该列表包含的是待执行或待跳过的 sharding DDL 语句. - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "unresolvedGroups": [ # 没有被解决的 sharding group 信息。 - { - "target": "`test`.`t_target`", # 待同步的下游表。 - "DDLs": [ - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "firstPos": "(bin|000001.000001, 3130)", # sharding DDL 语句起始 binlog position。 - "synced": [ # `Sync` 处理单元已经读到该 sharding DDL 的上游分表。 - "`test`.`t2`" - "`test`.`t3`" - "`test`.`t1`" - ], - "unsynced": [ # `Sync` 处理单元未读到该 sharding DDL 的上游分表。如有上游分表未完成同步，`blockingDDLs` 为空。 - ] - } - ], - "synced": false # 增量同步是否已追上上游。由于后台 `Sync` 单元并不会实时刷新保存点，当前值为 “false“ 并不一定代表发生了同步延迟。 - } - } - ], - "relayStatus": { # relay 单元的同步状态. - "masterBinlog": "(bin.000001, 3234)", # 上游数据库的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库的 binlog GTID 信息。 - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", # 当前使用的 relay log 子目录。 - "relayBinlog": "(bin.000001, 3234)", # 已被拉取至本地存储的 binlog position。 - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 已被拉取至本地存储的 binlog GTID 信息。 - "relayCatchUpMaster": true, # 本地 relay log 同步进度是否与上游一致。 - "stage": "Running", # relay 处理单元状态 - "result": null - }, - "sourceID": "172.17.0.2:3306" # 上游实例或者复制组 ID - }, - { - "result": true, - "worker": "172.17.0.3:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Running", - "unit": "Load", - "result": null, - "unresolvedDDLLockID": "", - "load": { # `Load` 处理单元的同步信息。 - "finishedBytes": "115", # 已全量导入字节数。 - "totalBytes": "452", # 总计需要导入的字节数。 - "progress": "25.44 %" # 全量导入进度。 - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 28507)", - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", - "relayBinlog": "(bin.000001, 28507)", - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - }, - "sourceID": "172.17.0.3:3306" - }, - { - "result": true, - "worker": "172.17.0.6:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Paused", - "unit": "Load", - "result": { # 错误示例 - "isCanceled": false, - "errors": [ - { - "Type": "ExecSQL", - "msg": "Error 1062: Duplicate entry '1155173304420532225' for key 'PRIMARY'\n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:160: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:105: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/loader.go:138: file test.t1.sql" - } - ], - "detail": null - }, - "unresolvedDDLLockID": "", - "load": { - "finishedBytes": "0", - "totalBytes": "156", - "progress": "0.00 %" - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 1691)", - "masterBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relaySubDir": "97b5142f-e19c-11e8-808c-0242ac110005.000001", - "relayBinlog": "(bin.000001, 1691)", - "relayBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - }, - "sourceID": "172.17.0.6:3306" - } - ] -} -``` - -关于 `workers` 下 `subTaskStatus` 中 `stage` 状态和状态转换关系的详细信息，请参阅[子任务状态](#子任务状态)。 - -关于 `workers` 下 `subTaskStatus` 中 `unresolvedDDLLockID`的操作细节，请参阅[手动处理 Sharding DDL Lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 子任务状态 - -### 状态描述 - -- `New`： - - - 初始状态。 - - 如果子任务没有发生错误，状态切换为 `Running`，其他情况则切换为 `Paused`。 - -- `Running`：正常运行状态。 - -- `Paused`： - - - 暂停状态。 - - 子任务发生错误，状态切换为 `Paused`。 - - 如在子任务为 `Running` 状态下执行 `pause-task` 命令，任务状态会切换为 `Paused`。 - - 如子任务处于该状态，可以使用 `resume-task` 命令恢复任务。 - -- `Stopped`： - - - 停止状态。 - - 如在子任务为 `Running` 或 `Paused` 状态下执行 `stop-task` 命令，任务状态会切换为 `Stopped`。 - - 如子任务处于该状态，不可使用 `resume-task` 命令恢复任务。 - -- `Finished`： - - - 任务完成状态。 - - 只有 `task-mode` 为 `full` 的任务正常完成后，任务才会切换为该状态。 - -### 状态转换图 - -``` - error occurs - New --------------------------------| - | | - | resume-task | - | |----------------------------| | - | | | | - | | | | - v v error occurs | v - Finished <-------------- Running -----------------------> Paused - ^ | or pause-task | - | | | - start task | | stop task | - | | | - | v stop task | - Stopped <-------------------------| -``` diff --git a/dev/reference/tools/data-migration/skip-replace-sqls.md b/dev/reference/tools/data-migration/skip-replace-sqls.md deleted file mode 100644 index b14b8a27cc0d..000000000000 --- a/dev/reference/tools/data-migration/skip-replace-sqls.md +++ /dev/null @@ -1,663 +0,0 @@ ---- -title: 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 -category: reference ---- - -# 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 - -本文介绍了如何使用 DM 来处理异常的 SQL 语句。 - -目前，TiDB 并不完全兼容所有的 MySQL 语法（详见 [TiDB 已支持的 DDL 语句](/dev/reference/mysql-compatibility.md#ddl)）。当使用 DM 从 MySQL 同步数据到 TiDB 时，如果 TiDB 不支持对应的 SQL 语句，可能会造成错误并中断同步任务。在这种情况下，DM 提供以下两种方式来恢复同步： - -- 使用 dmctl 来手动跳过该 SQL 语句对应的 binlog event。 - -- 使用 dmctl 来手动指定其他 SQL 语句来替代该 SQL 语句对应的 binlog event，并向下游执行。 - -如果提前预知将要同步 TiDB 不支持的 SQL 语句，也可以使用 dmctl 来手动预设跳过/替代执行操作。当 DM 尝试将该 SQL 语句对应的 binlog event 同步到下游时，该预设的操作将自动执行，从而避免同步过程被中断。 - - - -#### 使用限制 - -- 跳过/替代执行操作只适合用于一次性跳过/替代执行**下游 TiDB 不支持执行的 SQL 语句**，其它同步错误请不要使用此方式进行处理。 - - - 其它同步错误可尝试使用 [black & white table lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) 或 [binlog event filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter)。 - -- 如果业务不能接受下游 TiDB 跳过异常的 DDL 语句，也不接受使用其他 DDL 语句作为替代，则不适合使用此方式进行处理。 - - - 比如：`DROP PRIMARY KEY` - - 这种情况下，只能在下游重建一个（DDL 执行完后的）新表结构对应的表，并将原表的全部数据重新导入该新表。 - -- 单次跳过/替代执行操作都是针对单个 binlog event 的。 - -- `--sharding` 仅用于对 sharding group 预设一些操作，并且必须在 DDL 语句执行之前预设，不能在 DDL 语句已经执行后预设。 - - - `--sharding` 模式下只支持预设，并只能使用 `--sql-pattern` 来匹配 binlog event。 - - 有关使用 DM 处理 sharding DDL 同步的原理，请参阅[分库分表合并同步原理](/dev/reference/tools/data-migration/features/shard-merge.md#实现原理)。 - -#### 匹配 binlog event - -当同步任务由于执行 SQL 语句出错而中断时，可以使用 `query-error` 命令获取对应 binlog event 的 position 信息。在执行 `sql-skip` / `sql-replace` 时，通过指定该 position 信息，即可与对应的 binlog event 进行匹配。 - -然而，在同步中断前主动处理不被支持的 SQL 语句的情况下，由于无法提前预知 binlog event 的 position 信息，则需要使用其他方式来确保与后续将到达的 binlog event 进行匹配。 - -在 DM 中，支持如下两种 binlog event 匹配模式（两种模式只能选择其中一种）： - -1. binlog position：binlog event 的 position 信息 - - - binlog position 在命令中使用 `--binlog-pos` 参数传入，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - DM 中 binlog filename 的格式与上游 MySQL 中 binlog filename 的格式不完全一致。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -2. DDL pattern：（仅限于 DDL 语句的）正则表达式匹配模式 - - - DDL pattern 在命令中使用 `--sql-pattern` 参数传入，如要匹配 ```ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` ```，则对应的正则表达式为 ```~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` ```。 - - 正则表达式必须以 `~` 为前缀，且不包含任何原始空格（正则表达式字符串中的空格均以 `\s` 或 `\s+` 表示）。 - -对于合库合表场景，如果需要由 DM 自动选择 DDL lock owner 来执行跳过/替代执行操作，则由于不同 DM-worker 上 DDL 语句对应的 binlog position 无逻辑关联且难以确定，因此只能使用 DDL pattern 匹配模式。 - -> **注意：** -> -> - 一个 binlog event 只能注册一个使用 `--binlog-pos` 指定的 operator，后注册的 operator 会覆盖之前已经注册的 operator。 -> - 不要尝试为一个 binlog event 同时使用 `--binlog-pos` 和 `--sql-pattern` 指定 operator。 -> - operator 在与 binlog event 匹配成功后（而非执行成功后）即会被删除，后续如果需要再进行（`--sql-pattern`）匹配则必须重新注册。 - -### 支持场景 - -- 场景一：同步过程中，上游执行了 TiDB 不支持的 DDL 语句并同步到了 DM，造成同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 跳过对该 DDL 语句的同步以恢复同步任务。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 替代该 DDL 的同步以恢复同步任务。 - -- 场景二：同步过程中，预先知道了上游将执行 TiDB 不支持的 DDL 语句，则需要提前处理以避免同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 预设一个跳过该 DDL 语句的操作，当执行到该 DDL 语句时即自动跳过。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 预设一个替代该 DDL 语句的操作，当执行到该 DDL 语句时即自动替代。 - -### 实现原理 - -DM 在进行增量数据同步时，简化后的流程大致为： - -1. relay 处理单元从上游拉取 binlog 存储在本地作为 relay log。 - -2. binlog 同步单元（sync）读取本地 relay log，获取其中的 binlog event。 - -3. binlog 同步单元解析该 binlog event 并构造 DDL/DML 语句，然后将这些语句向下游 TiDB 执行。 - -在 binlog 同步单元解析完 binlog event 并向下游 TiDB 执行时，可能会由于 TiDB 不支持对应的 SQL 语句而报错并造成同步中断。 - -在 DM 中，可以为 binlog event 注册一些跳过/替代执行操作（operator）。在向下游 TiDB 执行 SQL 语句前，将当前的 binlog event 信息（position、DDL 语句）与注册的 operator 进行比较。如果 position 或 DDL 语句与注册的某个 operator 匹配，则执行该 operator 对应的操作并将该 operator 移除。 - -**同步中断后使用 `sql-skip` 或 `sql-replace` 恢复同步的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 binlog position 或 DDL pattern 注册 operator。 - -2. 使用 `resume-task` 恢复之前由于同步出错导致中断的任务。 - -3. 重新解析获得之前造成同步出错的 binlog event。 - -4. 该 binlog event 与第一步注册的 operator 匹配成功。 - -5. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -**同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 DDL pattern 注册 operator。 - -2. 从 relay log 中解析获得 binlog event。 - -3. （包含 TiDB 不支持 SQL 语句的）binlog event 与第一步注册的 operator 匹配成功。 - -4. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务，任务不发生中断。 - -**合库合表同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace`（在 DM-master 上）为指定的 DDL pattern 注册 operator。 - -2. 各 DM-worker 从 relay log 中解析获得 binlog event。 - -3. DM-master 协调各个 DM-worker 进行 DDL lock 同步。 - -4. DM-master 判断得知 DDL lock 同步成功后，将第一步注册的 operator 发送给 DDL lock owner。 - -5. DM-master 请求 DDL lock owner 执行 DDL 语句。 - -6. DDL lock owner 将要执行的 DDL 语句与第四步收到的 operator 匹配成功。 - -7. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -### 命令介绍 - -使用 dmctl 手动处理 TiDB 不支持的 SQL 语句时，主要使用的命令包括 `query-status`、`query-error`、`sql-skip` 和 `sql-replace`。 - -#### query-status - -`query-status` 命令用于查询当前 DM-worker 内子任务及 relay 单元等的状态，详见[查询状态](/dev/reference/tools/data-migration/query-status.md)。 - -#### query-error - -`query-error` 命令用于查询 DM-worker 内子任务及 relay 单元当前在运行中存在的错误。 - -##### 命令用法 - -```bash -query-error [--worker=127.0.0.1:8262] [task-name] -``` - -##### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选； - - 不指定时查询所有 DM-worker 上的错误，指定时仅查询特定一组 DM-worker 上的错误。 - -+ `task-name`： - - 非 flag 参数，string，可选； - - 不指定时查询所有任务内的错误，指定时仅查询特定任务内的错误。 - -##### 结果示例 - -{{< copyable "" >}} - -```bash -» query-error test -``` - -``` -{ - "result": true, # query-error 操作本身是否成功 - "msg": "", # query-error 操作失败的说明信息 - "workers": [ # DM-worker 信息列表 - { - "result": true, # 该 DM-worker 上 query-error 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 的 IP:port（worker-id） - "msg": "", # 该 DM-worker 上 query-error 操作失败的说明信息 - "subTaskError": [ # 该 DM-worker 上运行子任务的错误信息 - { - "name": "test", # 任务名 - "stage": "Paused", # 当前任务的状态 - "unit": "Sync", # 当前正在处理任务的处理单元 - "sync": { # binlog 同步单元（sync）的错误信息 - "errors": [ # 当前处理单元的错误信息列表 - { - // 错误信息描述 - "msg": "exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, err:Error 1105: unsupported modify column length 10 is less than origin 11", - // 发生错误的 binlog event 的 position - "failedBinlogPosition": "mysql-bin|000001.000003:34642", - // 发生错误的 SQL 语句 - "errorSQL": "[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]" - } - ] - } - } - ], - "RelayError": { # 该 DM-worker 上 relay 处理单元的错误信息 - "msg": "" # 错误信息描述 - } - } - ] -} -``` - -#### sql-skip - -`sql-skip` 命令用于预设一个跳过操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。 - -##### 命令用法 - -```bash -sql-skip <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -##### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`； - - 未指定 `--sharding` 时必选，指定 `--sharding` 时禁止使用； - - `worker` 指定预设操作将生效的 DM-worker。 - -+ `binlog-pos`： - - flag 参数，string，`--binlog-pos`； - - `binlog-pos` 与 `--sql-pattern` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `binlog-pos` 与 binlog event 的 position 匹配时生效，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -+ `sql-pattern`： - - flag 参数，string，`--sql-pattern`； - - `--sql-pattern` 与 `binlog-pos` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `sql-pattern` 与 binlog event 对应的（经过可选的 router-rule 转换后的）DDL 语句匹配时生效。格式为以 `~` 为前缀的正则表达式，如 ```~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT```。 - - 暂时不支持正则表达式中包含原始空格，需要使用 `\s` 或 `\s+` 替代空格。 - - 正则表达式必须以 `~` 为前缀，详见[正则表达式语法](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。 - - 正则表达式中的库名和表名必须是经过可选的 router-rule 转换后的名字，即对应下游的目标库名和表名。如上游为 ``` `shard_db_1`.`shard_tbl_1` ```，下游为 ``` `shard_db`.`shard_tbl` ```，则应该尝试匹配 ``` `shard_db`.`shard_tbl` ```。 - - 正则表达式中的库名、表名及列名需要使用 ``` ` ``` 标记，如 ``` `db1`.`tbl1` ```。 - -+ `sharding`： - - flag 参数，boolean，`--sharding`； - - 未指定 `--worker` 时必选，指定 `--worker` 时禁止使用； - - 在指定时表示预设的操作将在 sharding DDL 同步过程中的 DDL lock owner 内生效。 - -+ `task-name`： - - 非 flag 参数，string，必选； - - 指定预设的操作将生效的任务。 - -#### sql-replace - -`sql-replace` 命令用于预设一个替代执行操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替代执行操作。 - -##### 命令用法 - -```bash -sql-replace <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -##### 参数解释 - -+ `worker`： - - 与 `sql-skip` 命令的 `--worker` 参数解释一致。 - -+ `binlog-pos`： - - 与 `sql-skip` 命令的 `--binlog-pos` 参数解释一致。 - -+ `sql-pattern`： - - 与 `sql-skip` 命令的 `--sql-pattern` 参数解释一致。 - -+ `sharding`： - - 与 `sql-skip` 命令的 `--sharding` 参数解释一致。 - -+ `task-name`： - - 与 `sql-skip` 命令的 `task-name` 参数解释一致。 - -+ `SQLs`： - - 非 flag 参数，string，必选； - - `SQLs` 指定将用于替代原 binlog event 的新的 SQL 语句。多条 SQL 语句间以 `;` 分隔，如 ```ALTER TABLE shard_db.shard_table drop index idx_c2;ALTER TABLE shard_db.shard_table DROP COLUMN c2;```。 - -### 使用示例 - -#### 同步中断后被动执行跳过操作 - -##### 应用场景 - -假设现在需要将上游的 `db1.tbl1` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE db1.tbl1; -``` - -``` -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl1 | CREATE TABLE `tbl1` ( - `c1` int(11) NOT NULL, - `c2` decimal(11,3) DEFAULT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（将列的 DECIMAL(11, 3) 修改为 DECIMAL(10, 3)）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE db1.tbl1 CHANGE c2 c2 DECIMAL (10, 3); -``` - -则会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -``` -exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, -err:Error 1105: unsupported modify column length 10 is less than origin 11 -``` - -此时使用 `query-status` 查询任务状态，可看到 `stage` 转为了 `Paused`，且 `errors` 中有相关的错误描述信息。 - -使用 `query-error` 可以获取该错误的详细信息。比如，执行 `query-error test` 可获得出错的 binlog event 的 position（`failedBinlogPosition`）为 `mysql-bin|000001.000003:34642`。 - -##### 被动跳过 SQL 语句 - -假设业务上可以接受下游 TiDB 不执行此 DDL 语句（即继续保持原有的表结构），则可以通过使用 `sql-skip` 命令跳过该 DDL 语句以恢复同步任务。操作步骤如下： - -1. 使用 `query-error` 获取同步出错的 binlog event 的 position 信息。 - - position 信息可直接由 `query-error` 返回的 `failedBinlogPosition` 获得。 - - 本示例中的 position 为 `mysql-bin|000001.000003:34642`。 - -2. 使用 `sql-skip` 预设一个 binlog event 跳过操作，该操作将在使用 `resume-task` 后同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-skip --worker=127.0.0.1:8262 --binlog-pos=mysql-bin|000001.000003:34642 test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 11:17:51 operator.go:121: [info] [sql-operator] set a new operator - uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - on replication unit - ``` - -3. 使用 `resume-task` 恢复之前出错中断的同步任务。 - - {{< copyable "" >}} - - ```bash - » resume-task --worker=127.0.0.1:8262 test - ``` - - ``` - { - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "op": "Resume", - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 11:27:46 operator.go:158: [info] [sql-operator] binlog-pos (mysql-bin|000001.000003, 34642) matched, - applying operator uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - ``` - -4. 使用 `query-status` 确认该任务的 `stage` 已经转为 `Running`。 - -5. 使用 `query-error` 确认原错误信息已不再存在。 - -#### 同步中断前主动执行替代执行操作 - -##### 应用场景 - -假设现在需要将上游的 `db2.tbl2` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE db2.tbl2; -``` - -``` -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl2 | CREATE TABLE `tbl2` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE db2.tbl2 DROP COLUMN c2; -``` - -当同步该 DDL 语句对应的 binlog event 到下游时，会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -``` -exec sqls[[USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 为该 DDL 语句预设一个跳过（skip）或替代执行（replace）操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP 列 c2。 - -##### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的 DDL 语句（经过可选的 router-rule 转换后的 DDL 语句）设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE db2.tbl2 DROP COLUMN c2;`。 - - 由于该 DDL 语句不存在 router-rule 转换，可设计如下正则表达式： - - ``` - ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`; - ``` - -3. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-replace --worker=127.0.0.1:8262 --sql-pattern=~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 15:33:13 operator.go:121: [info] [sql-operator] set a new operator - uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - on replication unit - ``` - -4. 在上游 MySQL 执行该 DDL 语句。 - -5. 观察下游表结构是否变更成功，对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 15:33:45 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;, - applying operator uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, - pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - -6. 使用 `query-status` 确认该任务的 `stage` 持续为 `Running`。 - -7. 使用 `query-error` 确认不存在 DDL 执行错误。 - -#### 合库合表场景下同步中断后被动执行跳过操作 - -##### 应用场景 - -假设现在通过多个 DM-worker 将上游多个 MySQL 实例内的多个表进行合库合表同步到下游 TiDB 的同一个表，并且上游各分表执行了 TiDB 不支持的 DDL 语句。 - -DM-master 通过 DDL lock 协调 DDL 同步、并请求 DDL lock owner 向下游 TiDB 执行该 DDL 语句后，由于 TiDB 不支持该 DDL 语句，同步任务会报错并中断。 - -##### 被动跳过 SQL 语句 - -合库合表场景下，被动跳过 TiDB 不支持的 DDL 语句的处理方式与非合库合表场景下的[同步中断后被动执行跳过操作](#同步中断后被动执行跳过操作)基本一致。 - -但在合库合表场景下，只需要 DDL lock owner 向下游同步该 DDL 语句，因此在两种场景下的处理过程主要存在以下区别： - -1. 合库合表场景下，仅需要对 DDL lock owner 执行 `sql-skip`（`--worker={DDL-lock-owner}`）。 - -2. 合库合表场景下，仅需要对 DDL lock owner 执行 `resume-task`（`--worker={DDL-lock-owner}`）。 - -#### 合库合表场景下同步中断前主动执行替代执行操作 - -##### 应用场景 - -假设现在存在如下四个上游表需要合并同步到下游的同一个表 ``` `shard_db`.`shard_table` ```： - -- MySQL 实例 1 内有 `shard_db_1` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 -- MySQL 实例 2 内有 `shard_db_2` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 - -初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE shard_db_1.shard_table_1; -``` - -``` -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -此时，在上游所有分表上都执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2; -``` - -则当 DM 通过 sharding DDL lock 协调两个 DM-worker 同步该 DDL 语句、并请求 DDL lock owner 向下游执行该 DDL 语句时，会由于 TiDB 不支持该 DDL 语句而导致同步任务中断且报如下错误： - -``` -exec sqls[[USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 命令为该 DDL 语句预设一个跳过/替代执行操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP c2 列。 - -##### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的（经过可选的 router-rule 转换后的）DDL 语句设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2`。 - - 由于存在 router-rule 会将表名转换为 ``` `shard_db`.`shard_table` ```，可设计如下正则表达式： - - ``` - ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - -3. 由于这是合库合表场景，因此使用 `--sharding` 参数来由 DM 自动确定替代执行操作只发生在 DDL lock owner 上。 - -4. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-replace --sharding --sql-pattern=~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - ``` - { - "result": true, - "msg": "request with --sharding saved and will be sent to DDL lock's owner when resolving DDL lock", - "workers": [ - ] - } - ``` - - **DM-master** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:53:33 operator.go:105: [info] [sql-operator] set a new operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" - op:REPLACE args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -5. 在上游 MySQL 实例的分表上执行 DDL 语句。 - -6. 观察下游表结构是否变更成功，对应的 DDL lock **owner** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:54:35 operator.go:121: [info] [sql-operator] set a new operator - uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - on replication unit - ``` - - ``` - 2018/12/28 16:54:35 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;, - applying operator uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - 另外，**DM-master** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:54:35 operator.go:122: [info] [sql-operator] get an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - with key ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - - ``` - 2018/12/28 16:54:36 operator.go:145: [info] [sql-operator] remove an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -7. 使用 `query-status` 确认任务的 `stage` 持续为 `Running`，且不存在正阻塞同步的 DDL 语句（`blockingDDLs`）与待解决的 sharding group（`unresolvedGroups`）。 - -8. 使用 `query-error` 确认不存在 DDL 执行错误。 - -9. 使用 `show-ddl-locks` 确认不存在待解决的 DDL lock。 diff --git a/dev/reference/tools/data-migration/troubleshoot/dm.md b/dev/reference/tools/data-migration/troubleshoot/dm.md deleted file mode 100644 index ed9efb77b294..000000000000 --- a/dev/reference/tools/data-migration/troubleshoot/dm.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Data Migration 故障诊断 -category: reference -aliases: ['/docs-cn/dev/how-to/troubleshoot/data-migration/'] ---- - -# Data Migration 故障诊断 - -本文总结了在 DM 工具使用过程中遇到问题的诊断流程，并指引用户通过错误信息查找相应的解决方案。 - -如果你在运行 DM 工具时出现了错误，请尝试以下解决方案： - -1. 执行 `query-status` 命令查看任务运行状态以及相关错误输出。 - -2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [Data Migration 错误含义](/dev/reference/tools/data-migration/troubleshoot/error-system.md) 获取错误的关键信息，然后查看 [Data Migration 常见错误及修复](/dev/reference/tools/data-migration/troubleshoot/error-handling.md)以寻找相应的解决方案。 - -3. 如果该错误还没有相应的解决方案，并且你无法通过查询日志或监控指标自行解决此问题，你可以联系相关销售人员进行支持。 - -4. 一般情况下，错误处理完成后，只需使用 dmctl 重启任务即可。 - - {{< copyable "shell-regular" >}} - - ```bash - resume-task ${task name} - ``` - -但在某些情况下，你还需要重置数据同步任务。有关何时需要重置以及如何重置，详见[重置数据同步任务](/dev/reference/tools/data-migration/faq.md#重置数据同步任务)。 diff --git a/dev/reference/tools/data-migration/troubleshoot/error-handling.md b/dev/reference/tools/data-migration/troubleshoot/error-handling.md deleted file mode 100644 index 9d76605bd0cf..000000000000 --- a/dev/reference/tools/data-migration/troubleshoot/error-handling.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Data Migration 常见错误修复 -category: reference ---- - -# Data Migration 常见错误修复 - -本文档介绍 DM 中常见的错误以及修复方法。 - -## 常见错误说明和处理方法 - -| 错误码 | 错误说明 | 解决方法 | -| :----------- | :------------------------------------------------------------ | :----------------------------------------------------------- | -| `code=10001` | 数据库操作异常 | 进一步分析错误信息和错误堆栈 | -| `code=10002` | 数据库底层的 `bad connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 | DM 提供针对此类错误的自动恢复。如果长时间未恢复，需要用户检查网络或 TiDB 状态。 | -| `code=10003` | 数据库底层 `invalid connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 | DM 提供针对此类错误的自动恢复。如果未能正常恢复，需要用户进一步检查错误信息并根据具体场景进行分析。 | -| `code=10005` | 数据库查询类语句出错 | | -| `code=10006` | 数据库 `EXECUTE` 类型语句出错，包括 DDL 和 `INSERT`/`UPDATE`/`DELETE` 类型的 DML。更详细的错误信息可通过错误 message 获取。错误 message 中通常包含操作数据库所返回的错误码和错误信息。 | | -| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/dev/reference/tools/data-migration/faq.md#处理不兼容的-ddl-语句) 提供的解决方案 | -| `code=20010` | 处理任务配置时，解密数据库的密码出错 | 检查任务配置中提供的下游数据库密码是否有[使用 dmctl 正确加密](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码) | -| `code=26002` | 任务检查创建数据库连接失败。更详细的错误信息可通过错误 message 获取。错误 message 中包含操作数据库所返回的错误码和错误信息。 | 检查 DM-master 所在的机器是否有权限访问上游 | -| `code=32001` | dump 处理单元异常 | 如果报错 `msg` 包含 `mydumper: argument list too long.`，则需要用户根据 black-white list，在 `task.yaml` 的 mydumper `extra-args` 参数中手动加上 `--regex` 正则表达式设置要导出的库表。例如，如果要导出所有库中表名字为 `hello` 的表，可加上 `--regex '.*\\.hello$'`，如果要导出所有表，可加上 `--regex '.*'`。 | -| `code=38008` | DM 组件间的 gRPC 通信出错 | 检查 `class`， 定位错误发生在哪些组件的交互环节，根据错误 message 判断是哪类通信错误。如果是 gRPC 建立连接出错，可检查通信服务端是否运行正常。 | - -## 同步任务中断并包含 `invalid connection` 错误 - -发生 `invalid connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 - -由于 DM 中存在同步任务并发向下游复制数据的特性，因此在任务中断时可能同时包含多个错误（可通过 `query-status` 或 `query-error` 查询当前错误）。 - -- 如果错误中仅包含 `invalid connection` 类型的错误且当前处于增量复制阶段，则 DM 会自动进行重试。 -- 如果 DM 由于版本问题等未自动进行重试或自动重试未能成功，则可尝试先使用 `stop-task` 停止任务，然后再使用 `start-task` 重启任务。 - -## 同步任务中断并包含 `driver: bad connection` 错误 - -发生 `driver: bad connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 - -当前版本 DM 发生该类型错误时，需要先使用 `stop-task` 停止任务后再使用 `start-task` 重启任务。后续 DM 会完善对此错误类型的自动重试机制。 - -## relay 处理单元报错 `event from * in * diff from passed-in event *` 或同步任务中断并包含 `get binlog error ERROR 1236 (HY000)`、`binlog checksum mismatch, data may be corrupted` 等 binlog 获取或解析失败错误 - -在 DM 进行 relay log 拉取与增量同步过程中，如果遇到了上游超过 4GB 的 binlog 文件，就可能出现这两个错误。 - -原因是 DM 在写 relay log 时需要依据 binlog position 及文件大小对 event 进行验证，且需要保存同步的 binlog position 信息作为 checkpoint。但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，进而出现上面的错误。 - -对于 relay 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 停止 DM-worker。 -3. 将上游对应的 binlog 文件复制到 relay log 目录作为 relay log 文件。 -4. 更新 relay log 目录内对应的 `relay.meta` 文件以从下一个 binlog 开始拉取。 - - 例如：报错时有 `binlog-name = "mysql-bin.004451"` 与`binlog-pos = 2453`，则将其分别更新为 `binlog-name = "mysql-bin.004452"` 与`binlog-pos = 4`。 -5. 重启 DM-worker。 - -对于 binlog replication 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 通过 `stop-task` 停止同步任务。 -3. 将下游 `dm_meta` 数据库中 global checkpoint 与每个 table 的 checkpoint 中的 `binlog_name` 更新为出错的 binlog 文件，将 `binlog_pos` 更新为已同步过的一个合法的 position 值，比如 4。 - - 例如：出错任务名为 `dm_test`，对应的 `source-id` 为 `replica-1`，出错时对应的 binlog 文件为 `mysql-bin|000001.004451`，则执行 `UPDATE dm_test_syncer_checkpoint SET binlog_name='mysql-bin|000001.004451', binlog_pos = 4 WHERE id='replica-1';`。 -4. 在同步任务配置中为 `syncers` 部分设置 `safe-mode: true` 以保证可重入执行。 -5. 通过 `start-task` 启动同步任务。 -6. 通过 `query-status` 观察同步任务状态，当原造成出错的 relay log 文件同步完成后，即可还原 `safe-mode` 为原始值并重启同步任务。 - -## 执行 `query-status` 或查看日志时出现 `Access denied for user 'root'@'172.31.43.27' (using password: YES)` - -在所有 DM 配置文件中，数据库相关的密码都必须使用经 dmctl 加密后的密文（若数据库密码为空，则无需加密）。有关如何使用 dmctl 加密明文密码，参见[使用 dmctl 加密上游 MySQL 用户密码](/dev/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -此外，在 DM 运行过程中，上下游数据库的用户必须具备相应的读写权限。在启动同步任务过程中，DM 会自动进行相应权限的前置检查，详见[上游 MySQL 实例配置前置检查](/dev/reference/tools/data-migration/precheck.md)。 diff --git a/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md b/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md deleted file mode 100644 index 1570d07a3b0a..000000000000 --- a/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 分表合并数据迁移最佳实践 -summary: 使用 DM 对分库分表进行合并迁移时的最佳实践。 -category: reference ---- -# 分表合并数据迁移最佳实践 - -本文阐述了使用 TiDB Data Migration（以下简称 DM）对分库分表进行合并迁移的场景中，DM 相关功能的支持和限制，旨在给出一个业务的最佳实践。 - -## 独立的数据迁移任务 - -在[分库分表合并同步的实现原理部分](/dev/reference/tools/data-migration/features/shard-merge.md#实现原理)，我们介绍了 sharding group 的概念，简单来说可以理解为需要合并到下游同一个表的所有上游表即组成一个 sharding group。 - -当前的 sharding DDL 算法为了能协调在不同分表执行 DDL 对 schema 变更的影响，加入了一些[使用限制](/dev/reference/tools/data-migration/features/shard-merge.md#使用限制)。而当这些使用限制由于某些异常原因被打破时，我们需要[手动处理 Sharding DDL Lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) 甚至是完整重做整个数据迁移任务。 - -因此，为了减小异常发生时对数据迁移的影响，我们推荐将每一个 sharding group 拆分成一个独立的数据迁移任务。**这样当异常发生时，可能只有少部分迁移任务需要进行手动处理，其他数据迁移任务可以不受影响。** - -## 手动处理 sharding DDL lock - -从[分库分表合并同步的实现原理部分](/dev/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，DM 中的 sharding DDL lock 是用于协调不同上游分表向下游执行 DDL 的一种机制，本身并不是异常。 - -因此，当通过 `show-ddl-locks` 查看到 DM-master 上存在 sharding DDL lock 时，或通过 `query-status` 查看到某些 DM-worker 有 `unresolvedGroups` 或 `blockingDDLs` 时，并不要急于使用 `unlock-ddl-lock` 或 `break-ddl-lock` 尝试去手动解除 sharding DDL lock。 - -只有在确认当前未能自动解除 sharding DDL lock 是文档中所列的[支持场景](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#支持场景)之一时，才能参照对应支持场景中的手动处理示例进行处理。对于其他未被支持的场景，我们建议完整重做整个数据迁移任务，即清空下游数据库中的数据以及该数据迁移任务相关的 `dm_meta` 信息后，重新执行全量数据及增量数据的迁移。 - -## 自增主键冲突处理 - -在 DM 中，我们提供了 [Column mapping](/dev/reference/tools/data-migration/features/overview.md#column-mapping) 用于处理 bigint 类型的自增主键在合并时可能出现冲突的问题，但我们**强烈不推荐**使用该功能。如果业务上允许，我们推荐使用以下两种处理方式。 - -### 去掉自增主键的主键属性 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_no_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -- `auto_pk_c1` 列对业务无意义，且不依赖该列的 `PRIMARY KEY` 属性。 -- `uk_c2` 列有 `UNIQUE KEY` 属性，且能保证在所有上游分表间全局唯一。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但将 `auto_pk_c1` 的 `PRIMARY KEY` 属性修改为普通索引。 - - ```sql - CREATE TABLE `tbl_no_pk_2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - INDEX (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 使用联合主键 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_multi_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -* 业务不依赖 `auto_pk_c1` 的 `PRIMARY KEY` 属性。 -* `auto_pk_c1` 与 `uuid_c2` 的组合能确保全局唯一。 -* 业务能接受将 `auto_pk_c1` 与 `uuid_c2` 组成联合 `PRIMARY KEY`。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但不为 `auto_pk_c1` 指定 `PRIMARY KEY` 属性，而是将 `auto_pk_c1` 与 `uuid_c2` 一起组成 `PRIMARY KEY`。 - - ```sql - CREATE TABLE `tbl_multi_pk_c2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`,`uuid_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 - -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -## 合表迁移过程中在上游增/删表 - -从[分库分表合并同步的实现原理部分](/dev/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，sharding DDL lock 的协调依赖于是否已收到上游已有各分表对应的 DDL，且当前 DM 在合表迁移过程中暂时**不支持**在上游动态增加或删除分表。如果需要在合表迁移过程中，对上游执行增、删分表操作，推荐按以下方式进行处理。 - -### 在上游增加分表 - -如果需要在上游增加新的分表，推荐按以下顺序执行操作： - -1. 等待在上游分表上执行过的所有 sharding DDL 协调同步完成。 -2. 通过 `stop-task` 停止任务。 -3. 在上游添加新的分表。 -4. 确保 `task.yaml` 配置能使新添加的分表与其他已有的分表能合并到同一个下游表。 -5. 通过 `start-task` 启动任务。 -6. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 在上游删除分表 - -如果需要在上游删除原有的分表，推荐按以下顺序执行操作： - -1. 在上游删除原有的分表，并通过 [`SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/5.7/en/show-binlog-events.html) 获取该 `DROP TABLE` 语句在 binlog 中对应的 `End_log_pos`，记为 _Pos-M_。 -2. 通过 `query-status` 获取当前 DM 已经处理完成的 binlog event 对应的 position（`syncerBinlog`），记为 _Pos-S_。 -3. 当 _Pos-S_ 比 _Pos-M_ 更大后，则说明 DM 已经处理完 `DROP TABLE` 语句，且该表在被删除前的数据都已经同步到下游，可以进行后续操作；否则，继续等待 DM 进行数据同步。 -4. 通过 `stop-task` 停止任务。 -5. 确保 `task.yaml` 配置能忽略上游已删除的分表。 -6. 通过 `start-task` 启动任务。 -7. 通过 `query-status` 验证数据迁移任务是否正常。 - -## 数据迁移限速/流控 - -当将多个上游 MySQL/MariaDB 实例的数据合并迁移到下游同一个 TiDB 集群时，由于每个与上游 MySQL/MariaDB 对应的 DM-worker 都会并发地进行全量与增量数据迁移，默认的并发度（全量阶段的 `pool-size` 与增量阶段的 `worker-count`）通过多个 DM-worker 累加后，可能会给下游造成过大的压力，此时应根据 TiDB 监控及 DM 监控进行初步的性能分析后，适当地调整各并发度参数的大小。后续 DM 也将考虑支持部分自动的流控策略。 diff --git a/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md b/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md deleted file mode 100644 index 88e0dde84ac4..000000000000 --- a/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: DM 分库分表合并场景 -category: reference ---- - -# DM 分库分表合并场景 - -本文介绍如何在分库分表合并场景中使用 Data Migration (DM)。使用场景中，三个上游 MySQL 实例的分库和分表数据需要同步至下游 TiDB 集群。 - -## 上游实例 - -假设上游库结构如下： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log_north, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log_east, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log_south, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -## 同步需求 - -1. 合并三个实例中的 `user`.`information` 表至下游 TiDB 中的 `user`.`information` 表。 -2. 合并三个实例中的 `user`.`log_{north|south|east}` 表至下游TiDB中的 `user`.`log_{north|south|east}` 表。 -3. 合并三个实例中的 `store_{01|02}`.`sale_{01|02}` 表至下游TiDB中的 `store`.`sale` 表。 -4. 过滤掉三个实例的 `user`.`log_{north|south|east}` 表的所有删除操作。 -5. 过滤掉三个实例的 `user`.`information` 表的所有删除操作。 -6. 过滤掉三个实例的 `store_{01|02}`.`sale_{01|02}` 表的所有删除操作。 -7. 过滤掉三个实例的 `user`.`log_bak` 表。 -8. 因为 `store_{01|02}`.`sale_{01|02}` 表带有 bigint 型的自增主键，将其合并至 TiDB 时会引发冲突。你需要有相应的方案来避免冲突。 - -## 下游实例 - -假设同步后下游库结构如下： - -| Schema | Tables | -|:------|:------| -| user | information, log_north, log_east, log_south| -| store | sale | - -## 同步方案 - -- 要满足同步需求 #1 和 #2，配置 [Table routing 规则](/dev/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - {{< copyable "" >}} - - ```yaml - routes: - ... - user-route-rule: - schema-pattern: "user" - target-schema: "user" - ``` - -- 要满足同步需求 #3，配置 [table routing 规则](/dev/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - {{< copyable "" >}} - - ```yaml - routes: - ... - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - ``` - -- 要满足同步需求 #4 和 #5，配置 [Binlog event filter 规则](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - {{< copyable "" >}} - - ```yaml - filters: - ... - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - ``` - - > **注意：** - > - > 同步需求 #4、#5 和 #7 的操作意味着过滤掉所有对 `user` 库的删除操作，所以此处配置了库级别的过滤规则。但是 `user` 库以后加入表的删除操作也都会被过滤。 - -- 要满足同步需求 #6，配置 [Binlog event filter 规则](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - {{< copyable "" >}} - - ```yaml - filters: - ... - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - ``` - -- 要满足同步需求 #7，配置 [Black & white table lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) 如下： - - {{< copyable "" >}} - - ```yaml - black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - ``` - -- 要满足同步需求 #8，首先参考[自增主键冲突处理](/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决冲突，保证在同步到下游时不会因为分表中有相同的主键值而使同步出现异常；然后需要配置 `ignore-checking-items` 来跳过自增主键冲突的检查： - - {{< copyable "" >}} - - ```yaml - ignore-checking-items: ["auto_increment_ID"] - ``` - -## 同步任务配置 - -同步任务的完整配置如下。详情请参阅 [Data Migration 任务配置文件](/dev/reference/tools/data-migration/configure/task-configuration-file.md)。 - -{{< copyable "" >}} - -```yaml -name: "shard_merge" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - - source-id: "instance-2" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例共享的其他通用配置 - -routes: - user-route-rule: - schema-pattern: "user" - target-schema: "user" - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - -filters: - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - -black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/dev/reference/tools/data-migration/usage-scenarios/simple-synchronization.md b/dev/reference/tools/data-migration/usage-scenarios/simple-synchronization.md deleted file mode 100644 index 1da1c21860b5..000000000000 --- a/dev/reference/tools/data-migration/usage-scenarios/simple-synchronization.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Data Migration 简单使用场景 -category: reference ---- - -# Data Migration 简单使用场景 - -本文介绍了 DM 工具的一个简单使用场景（非分库分表合并场景）：将三个上游 MySQL 实例的数据同步到一个下游 TiDB 集群中。 - -## 上游实例 - -假设上游结构为： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_bj, store_tj | - | log | messages | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_sh, store_sz | - | log | messages | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_gz, store_sz | - | log | messages | - -## 同步要求 - -1. 不合并 `user` 库。 - - 1. 将实例 1 中的 `user` 库同步到下游 TiDB 的 `user_north` 库中。 - - 2. 将实例 2 中的 `user` 库同步到下游 TiDB 的 `user_east` 库中。 - - 3. 将实例 3 中的 `user` 库同步到下游 TiDB 的 `user_south` 库中。 - - 4. 任何情况下都不删除 `log` 表的任何数据。 - -2. 将上游 `store` 库同步到下游 `store` 库中，且同步过程中不合并表。 - - 1. 实例 2 和实例 3 中都存在 `store_sz` 表，且这两个 `store_sz` 表分别被同步到下游的 `store_suzhou` 表和 `store_shenzhen` 表中。 - - 2. 任何情况下都不删除 `store` 库的任何数据。 - -3. `log` 库需要被过滤掉。 - -## 下游实例 - -假设下游结构为： - -| Schema | Tables | -|:------|:------| -| user_north | information, log | -| user_east | information, log | -| user_south | information, log | -| store | store_bj, store_tj, store_sh, store_suzhou, store_gz, store_shenzhen | - -## 同步方案 - -- 为了满足[同步要求](#同步要求)中第一点的前三条要求，需要配置以下 [table routing 规则](/dev/reference/tools/data-migration/features/overview.md#table-routing)： - - {{< copyable "" >}} - - ```yaml - routes: - ... - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第一条要求，需要配置以下 [table routing 规则](/dev/reference/tools/data-migration/features/overview.md#table-routing)： - - {{< copyable "" >}} - - ```yaml - routes: - ... - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - ``` - -- 为了满足[同步要求](#同步要求)中第一点的第四条要求，需要配置以下 [binlog event filter 规则](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - {{< copyable "" >}} - - ```yaml - filters: - ... - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第二条要求，需要配置以下 [binlog event filter 规则](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - {{< copyable "" >}} - - ```yaml - filters: - ... - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - ``` - - > **注意：** - > - > `store-filter-rule` 不同于 `log-filter-rule` 和 `user-filter-rule`。`store-filter-rule` 是针对整个 `store` 库的规则，而 `log-filter-rule` 和 `user-filter-rule` 是针对 `user` 库中 `log` 表的规则。 - -- 为了满足[同步要求](#同步要求)中的第三点要求，需要配置以下 [black & white table lists 规则](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists)： - - {{< copyable "" >}} - - ```yaml - black-white-list: - log-ignored: - ignore-dbs: ["log"] - ``` - -## 同步任务配置 - -以下是完整的同步任务配置，详见[配置介绍](/dev/reference/tools/data-migration/configure/task-configuration-file.md)。 - -{{< copyable "" >}} - -```yaml -name: "one-tidb-slave" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["instance-1-user-rule"] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-2" - route-rules: ["instance-2-user-rule", instance-2-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["instance-3-user-rule", instance-3-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例的共有配置 - -routes: - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - -filters: - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - -black-white-list: - log-ignored: - ignore-dbs: ["log"] - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/dev/reference/tools/download.md b/dev/reference/tools/download.md deleted file mode 100644 index 4561fd02e82e..000000000000 --- a/dev/reference/tools/download.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: TiDB 工具下载 -category: reference ---- - -# TiDB 工具下载 - -本页面汇总了 TiDB 周边工具官方维护版本的下载链接。 - -## TiDB Binlog - -如需下载最新版本的 [TiDB Binlog](/dev/reference/tidb-binlog/overview.md)，直接下载 TiDB 安装包即可，因为 TiDB Binlog 包含在 TiDB 安装包中。 - -以下表格中也提供了 Kafka 版本的 TiDB Binlog 下载链接。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (TiDB Binlog) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | -| `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz`（Kafka 版本的 TiDB Binlog）| Linux | amd64 | `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB Lightning - -使用下表中的链接下载 [TiDB Lightning](/dev/reference/tools/tidb-lightning/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB Lightning 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 快速备份和恢复（BR） - -使用下表中的链接下载 [快速备份和恢复（BR）](/dev/reference/tools/br/br.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 BR 的版本号。例如，`v3.1.0-beta` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.1.0-beta-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB DM (Data Migration) - -使用下表中的链接下载 [DM](/dev/reference/tools/data-migration/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/dm-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/dm-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 DM 的版本号。例如，`v1.0.1` 版本的下载链接为 `https://download.pingcap.org/dm-v1.0.1-linux-amd64.tar.gz`。可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## Syncer，Loader 和 Mydumper - -如需下载最新版本的 [Syncer](/dev/reference/tools/syncer.md)，[Loader](/dev/reference/tools/loader.md) 或 [Mydumper](/dev/reference/tools/mydumper.md)，直接下载 tidb-enterprise-tools 安装包即可，因为这些工具均包含在此安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| [tidb-enterprise-tools-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) | Linux | amd64 | [tidb-enterprise-tools-latest-linux-amd64.sha256](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256) | - -tidb-enterprise-tools 安装包包含以下工具： - -- Syncer -- Loader -- Mydumper -- ddl_checker -- [sync-diff-inspector](/dev/reference/tools/sync-diff-inspector/overview.md) diff --git a/dev/reference/tools/error-case-handling/lightning-misuse-handling.md b/dev/reference/tools/error-case-handling/lightning-misuse-handling.md deleted file mode 100644 index 6a1b3d99cb08..000000000000 --- a/dev/reference/tools/error-case-handling/lightning-misuse-handling.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: TiDB Lightning 常见的错误用法 -category: reference ---- - -# TiDB Lightning 常见的错误用法 - -本文介绍了 [TiDB Lightning](/dev/reference/tools/tidb-lightning/overview.md) 使用过程中常见的出错场景以及相应的处理方式。 - -## 报错：`checksum mismatched remote vs local` - -在数据导入过程中遇到下面的报错 - -```log -Error: checksum mismatched remote vs local => (checksum: 3828723015727756136 vs 7895534721177712659) (total_kvs: 1221416844 vs 1501500000) (total_bytes:237660308510 vs 292158203078) -``` - -### 原因 - -* 先前使用过 TiDB Lightning 进行数据导入，但是对应的 [checkpoint](/dev/reference/tools/tidb-lightning/checkpoints.md) 的数据没有被清理，存在残留的数据。可以通过查看 TiDB Lightning 第一次启动 log 来确认： - * `[checkpoint] driver = file`，如果对应 TiDB Lightning 导入时间点的 log 存在 `open checkpoint file failed, going to create a new one`，那么 `checkpoint` 已经被正确清理，否则存在残留数据可能导致导入数据缺失； - * `[checkpoint] driver = mysql`，可以通过使用 TiDB API `curl http://{TiDBIP}:10080/schema/{checkpoint.schema}/{checkpoint.table}` 来查询对应 `checkpoint table` 的创建时间，从而判断是否正确清理了 `checkpoint`。 - -* TiDB Lightning 导入的数据源存在冲突的数据 - * 不同行的数据具有相同的主键或唯一键 - -### 解决方案 - -* 删除出现 `checksum mismatch` 错误的表的数据 - - ``` - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -* 需要寻找办法检测数据源是否存在冲突数据，TiDB Lightning 一般需要处理大量的数据，所以目前还未提供有效的冲突检测和处理措施。 diff --git a/dev/reference/tools/error-case-handling/load-misuse-handling.md b/dev/reference/tools/error-case-handling/load-misuse-handling.md deleted file mode 100644 index 2792b35fa4f1..000000000000 --- a/dev/reference/tools/error-case-handling/load-misuse-handling.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: 全量数据导入过程常见报错处理 -category: reference ---- - -# 全量数据导入过程常见报错处理 - -本文介绍了使用 [Loader](/dev/reference/tools/loader.md) 或者 [TiDB Data Migration](/dev/reference/tools/data-migration/overview.md)（以下简称为 DM）进行全量数据导入过程中常见的因为使用造成的出错场景，以及这些错误发生的原因和处理方式。 - -## 报错：```Try adjusting the `max_allowed_packet` variable``` - -在全量数据导入过程中遇到下面的报错 - -``` -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -### 原因 - -* MySQL client 和 MySQL/TiDB Server 都有 `max_allowed_packet` 配额的限制，如果在使用过程中违反其中任何一个 `max_allowed_packet` 配额，客户端程序就会收到对应的报错。目前最新版本的 Syncer、Loader、DM 和 TiDB Server 的默认 `max_allowed_packet` 配额都为 `64M`。 - * 请使用最新版本，或者最新稳定版本的工具。[下载页面](/dev/reference/tools/download.md)。 -* Loader 或 DM 的全量数据导入处理模块不支持对 dump sqls 文件进行切分，原因是 Mydumper 采用了最简单的编码实现，正如 Mydumper 代码注释 `/* Poor man's data dump code */` 所言。如果在 Loader 或 DM 实现文件切分，那么需要在 `TiDB parser` 基础上实现一个完备的解析器才能正确的处理数据切分，但是随之会带来以下的问题： - * 工作量大 - * 复杂度高，不容易保证正确性 - * 性能的极大降低 - -### 解决方案 - -* 依据上面的原因，在代码层面不能简单的解决这个困扰，我们推荐的方式是：利用 Mydumper 提供的控制 `Insert Statement` 大小的功能 `-s, --statement-size`: `Attempted size of INSERT statement in bytes, default 1000000`。 - - 依据默认的 `--statement-size` 设置，Mydumper 默认生成的 `Insert Statement` 大小会尽量接近在 `1M` 左右，使用默认值就可以确保绝大部分情况不会出现该问题。 - - 有时候在 dump 过程中会出现下面的 `WARN` log，但是这个报错不影响 dump 的过程，只是表达了 dump 的表可能是宽表。 - - ``` - Row bigger than statement_size for xxx - ``` - -* 如果宽表的单行超过了 `64M`，那么需要修改以下两个配置，并且使之生效。 - * 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728` （`134217728 = 128M`） - * 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M`，然后重启进程或者任务 diff --git a/dev/reference/tools/loader.md b/dev/reference/tools/loader.md deleted file mode 100644 index f8d8b2db4c6d..000000000000 --- a/dev/reference/tools/loader.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Loader 使用文档 -category: reference ---- - -# Loader 使用文档 - -## Loader 简介 - -Loader 是由 PingCAP 开发的数据导入工具，用于向 TiDB 中导入数据。 - -Loader 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/dev/reference/tools/download.md)。 - -## 为什么我们要做这个工具 - -当数据量比较大的时候，如果用 mysqldump 这样的工具迁移数据会比较慢。我们尝试了 [Mydumper/myloader 套件](https://github.com/maxbube/mydumper)，能够多线程导出和导入数据。在使用过程中，Mydumper 问题不大，但是 myloader 由于缺乏出错重试、断点续传这样的功能，使用起来很不方便。所以我们开发了 loader，能够读取 Mydumper 的输出数据文件，通过 MySQL protocol 向 TiDB/MySQL 中导入数据。 - -## Loader 有哪些优点 - -* 多线程导入 -* 支持表级别的并发导入，分散写入热点 -* 支持对单个大表并发导入，分散写入热点 -* 支持 Mydumper 数据格式 -* 出错重试 -* 断点续导 -* 通过 system variable 优化 TiDB 导入数据速度 - -## 使用方法 - -### 注意事项 - -请勿使用 loader 导入 MySQL 实例中 `mysql` 系统数据库到下游 TiDB。 - -如果 Mydumper 使用 -m 参数，会导出不带表结构的数据，这时 loader 无法导入数据。 - -如果使用默认的 `checkpoint-schema` 参数，在导完一个 database 数据库后，请 `drop database tidb_loader` 后再开始导入下一个 database。 - -推荐数据库开始导入的时候，明确指定 `checkpoint-schema = "tidb_loader"` 参数。 - -### 参数说明 - -``` - -L string - log 级别设置，可以设置为 debug, info, warn, error, fatal (默认为 "info") - -P int - TiDB/MySQL 的端口 (默认为 4000) - -V - 打印 loader 版本 - -c string - 指定配置文件启动 loader - -checkpoint-schema string - checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后，会通过这个库获取上次运行的进度 (默认为 "tidb_loader") - -d string - 需要导入的数据存放路径 (default "./") - -h string - TiDB 服务 host IP (default "127.0.0.1") - -p string - TiDB 账户密码 - -status-addr string - Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 - -t int - 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 - -u string - TiDB 的用户名 (默认为 "root") -``` - -### 配置文件 - -除了使用命令行参数外，还可以使用配置文件来配置，配置文件的格式如下： - -```toml -# 日志输出等级；可以设置为 debug, info, warn, error, fatal (默认为 "info") -log-level = "info" - -# 指定 loader 日志目录 -log-file = "loader.log" - -# 需要导入的数据存放路径 (default "./") -dir = "./" - -## Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 -status-addr = ":8272" - -# checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后， -# 会通过这个库获取上次运行的进度 (默认为 "tidb_loader") -checkpoint-schema = "tidb_loader" - -# 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 -pool-size = 16 - -# 目标数据库信息 -[db] -host = "127.0.0.1" -user = "root" -password = "" -port = 4000 - -# 导入数据时数据库连接所使用的 session 级别的 `sql_mode`。如果 `sql-mode` 的值没有提供或者设置为 "@DownstreamDefault"，会使用下游 global 级别的 `sql_mode`。 -# sql-mode = "" -# `max-allowed-packet` 设置数据库连接允许的最大数据包大小，对应于系统参数中的 `max_allowed_packet`。 如果设置为 0，会使用下游数据库 global 级别的 `max_allowed_packet`。 -max-allowed-packet = 67108864 - -# sharding 同步规则，采用 wildcharacter -# 1\. 星号字符 (*) 可以匹配零个或者多个字符, -# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; -# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 -# 2\. 问号字符 (?) 匹配任一一个字符 - -# [[route-rules]] -# pattern-schema = "shard_db_*" -# pattern-table = "shard_table_*" -# target-schema = "shard_db" -# target-table = "shard_table" -``` - -### 使用示例 - -通过命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -d ./test -h 127.0.0.1 -u root -P 4000 -``` - -或者使用配置文件 "config.toml": - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -c=config.toml -``` - -## FAQ - -### 合库合表场景案例说明 - -根据配置文件的 route-rules 可以支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则： - -+ 是否可以利用 route-rules 的语义规则表示 -+ 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 - -Loader 需要配置文件中开启 route-rules 参数以提供合库合表功能 - -+ 如果使用该功能，必须填写 `pattern-schema` 与 `target-schema` -+ 如果 `pattern-table` 与 `target-table` 为空，将不进行表名称合并或转换 - -```toml -[[route-rules]] -pattern-schema = "example_db" -pattern-table = "table_*" -target-schema = "example_db" -target-table = "table" -``` diff --git a/dev/reference/tools/mydumper.md b/dev/reference/tools/mydumper.md deleted file mode 100644 index 492a6ba20f2b..000000000000 --- a/dev/reference/tools/mydumper.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Mydumper 使用文档 -summary: 使用 Mydumper 从 TiDB 导出数据。 -category: reference ---- - -# Mydumper 使用文档 - -## Mydumper 简介 - -[Mydumper](https://github.com/pingcap/mydumper) 是一个 fork 项目，针对 TiDB 的特性进行了优化，推荐使用此工具对 TiDB 进行逻辑备份。 - -Mydumper 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/dev/reference/tools/download.md)。 - -### 相比于普通的 Mydumper，此工具有哪些改进之处？ - -+ 对于 TiDB 可以设置 [tidb_snapshot](/dev/how-to/get-started/read-historical-data.md#操作流程) 的值指定备份数据的时间点，从而保证备份的一致性，而不是通过 `FLUSH TABLES WITH READ LOCK` 来保证备份一致性。 - -+ 使用 TiDB 的隐藏列 `_tidb_rowid` 优化了单表内数据的并发导出性能。 - -## 基本用法 - -### 新添参数 - -- `-z` 或 `--tidb-snapshot`：设置 `tidb_snapshot` 用于备份。默认值为当前 TSO（`SHOW MASTER STATUS` 输出的 `Position` 字段）。此参数可设为 TSO 或有效的 `datetime` 时间，例如：`-z "2016-10-08 16:45:26"`。 - -### 需要的权限 - -- SELECT -- RELOAD -- LOCK TABLES -- REPLICATION CLIENT - -### 使用举例 - -执行如下命令从 TiDB 备份数据，需要根据实际情况添加命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -``` - -## 表内并发 Dump - -### 原理 - -Mydumper 首先计算 `min(_tidb_rowid)` 和 `max(_tidb_rowid)`，然后按照 `-r` 设定的值对表划分 chunks，将 chunks 分配到不同线程并发导出。 - -### 并发 Dump 相关参数 - -- `-t` 或 `--threads`：并发线程数，默认值为 `4`。 -- `-r` 或 `--rows`：每个 chunks 包含的最大行数。设置该值后，Mydumper 将会忽略 `--chunk-filesize` 值。 - -### 示例 - -以下是一条完整的 Mydumper 命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -r 10000 -t 4 -``` - -### 支持 `_tidb_rowid` 索引的 TiDB 版本 - -由于表内并发使用 TiDB 的隐藏列 `_tidb_rowid`，数据库需要支持 `_tidb_rowid` 索引才能发挥并发导出的优势。 - -以下 TiDB 版本支持 `_tidb_rowid` 索引： - -- v2.1.3 及以上 -- v3.0 及以上，包括 v3.1 及未来版本 - -### 性能评估 - -在 Dump 操作前需要进行性能评估。由于并发 Scan 操作对 TiDB、TiKV 集群都会产生一定压力，所以需要评估与测试 Dump 操作对数据库集群和业务的影响。 - -## FAQ - -### 如何判断使用的 Mydumper 是否为 PingCAP 优化的版本？ - -执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -V -``` - -如果输出结果中包含 `githash`（如下列示例输出中的 `d3e6fec8b069daee772d0dbaa47579f67a5947e7`），则使用的 Mydumper 为 PingCAP 优化的版本。 - -``` -mydumper 0.9.5 (d3e6fec8b069daee772d0dbaa47579f67a5947e7), built against MySQL 5.7.24 -``` - -### 使用 Loader 恢复 Mydumper 备份出来的数据时报错 "invalid mydumper files for there are no `-schema-create.sql` files found"，应该如何解决？ - -检查使用 Mydumper 备份数据时是否使用了 `-T` 或者 `--tables-list` 配置，如果使用了这些配置，Mydumper 就不会生成包含建库 SQL 的文件。 - -**解决方法**：在 Mydumper 备份数据目录下创建文件 `{schema-name}-schema-create.sql`，在文件中写入 "CREATE DATABASE `{schema-name}`"，再运行 Loader 即可。 - -### 为什么使用 Mydumper 导出来的 TIMESTAMP 类型的数据和数据库中的数据不一致？ - -检查一下运行 Mydumper 的服务器的时区与数据库的时区是否一致，Mydumper 会根据运行所在服务器的时区对 TIMESTAMP 类型的数据进行转化，可以给 Mydumper 加上 `--skip-tz-utc` 参数禁止这种转化。 - -### 如何配置 Mydumper 的参数 `-F, --chunk-filesize`？ - -Mydumper 在备份时会根据这个参数的值把每个表的数据划分成多个 chunk，每个 chunk 保存到一个文件中，大小约为 `chunk-filesize`。根据这个参数把数据切分到多个文件中，这样就可以利用 Loader/TiDB Lightning 的并行处理逻辑提高导入速度。如果后续使用 Loader 对备份文件进行恢复，建议把该参数的值设置为 `64`（单位 MB）；如果使用 TiDB Lightning 恢复，则建议设置为 `256`（单位 MB）。 - -### 如何配置 Mydumper 的参数 `-s --statement-size`？ - -Mydumper 使用该参数控制 `Insert Statement` 的大小，默认值为 `10000000`（约 1 MB）。使用该参数来尽量避免在恢复数据时报以下错误： - -```log -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -默认值在绝大部分情况下都可以满足需求，但是**如果表为宽表，单行数据的大小可能超过 statement-size 的限制，Mydumper 会报如下的 Warning**： - -```log -Row bigger than statement_size for xxx -``` - -此时恢复数据时仍然会报 `packet for query is too large` 的错误日志，这个时候需要修改以下两个配置（以设置为 `128M` 为例）： - -* 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728`（`134217728` = `128M`）。 -* 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M` 的语句，然后重启进程或者任务。 - -### 如何设置 Mydumper 的参数 `-l, --long-query-guard`？ - -把该参数设置为预估备份需要消耗的时间，如果 Mydumper 运行时间超过该参数的值，就会报错退出。推荐初次备份设置为 `7200`（单位：秒），之后可根据具体备份时间进行调整。 - -### 如何设置 Mydumper 的参数 `--tidb-force-priority`？ - -仅当备份 TiDB 的数据时才可以设置该参数，值可以为 `LOW_PRIORITY`，`DELAYED` 或者 `HIGH_PRIORITY`。如果不希望数据备份对线上业务造成影响，推荐将该参数设置为 `LOW_PRIORITY`；如果备份的优先级更高，则可以设置为 `HIGH_PRIORITY`。 - -### Mydumper 备份 TiDB 数据报错 "GC life time is shorter than transaction duration" 应该怎么解决？ - -Mydumper 备份 TiDB 数据时为了保证数据的一致性使用了 TiDB 的 snapshot 特性，如果备份过程中 snapshot 对应的历史数据被 TiDB GC 处理了，则会报该错误。解决步骤如下： - -1. 在备份前，使用 MySQL 客户端查询 TiDB 集群的 `tikv_gc_life_time` 的值，并将其调整为一个合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 备份完成后，将 `tikv_gc_life_time` 调整为原来的值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m0s' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -### Mydumper 的参数 `--tidb-rowid` 是否需要配置？ - -如果设置该参数为 true，则导出的数据中会包含 TiDB 的隐藏列的数据。将数据恢复到 TiDB 的时候使用隐藏列会有数据不一致的风险，目前不推荐使用该参数。 - -### Mydumper 报错 "Segmentation fault" 怎么解决？ - -该 bug 已修复。如果仍然报错，可尝试升级到最新版本。 - -### Mydumper 报错 "Error dumping table ({schema}.{table}) data: line ...... (total length ...)" 怎么解决？ - -Mydumper 解析 SQL 时报错，可尝试使用最新版本。如果仍然报错，可以提 issue 到 [mydumper/issues](https://github.com/pingcap/mydumper/issues)。 - -### Mydumper 报错 "Failed to set tidb_snapshot: parsing time \"20190901-10:15:00 +0800\" as \"20190901-10:15:00 +0700 MST\": cannot parse \"\" as \"MST\"" 如何解决？ - -检查 TiDB 的版本是否低于 v2.1.11。如果是的话，需要升级 TiDB 到 v2.1.11 或以上版本。 - -### 未来是否计划让 PingCAP 对 Mydumper 的改动合并到上游？ - -是的，PingCAP 团队计划将对 Mydumper 的改动合并到上游。参见 [PR #155](https://github.com/maxbube/mydumper/pull/155)。 diff --git a/dev/reference/tools/sync-diff-inspector/overview.md b/dev/reference/tools/sync-diff-inspector/overview.md deleted file mode 100644 index 83075b206356..000000000000 --- a/dev/reference/tools/sync-diff-inspector/overview.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: sync-diff-inspector 用户文档 -category: tools ---- - -# sync-diff-inspector 用户文档 - -sync-diff-inspector 是一个用于校验 MySQL／TiDB 中两份数据是否一致的工具。该工具提供了修复数据的功能（适用于修复少量不一致的数据）。 - -主要功能： - -* 对比表结构和数据 -* 如果数据不一致，则生成用于修复数据的 SQL 语句 -* 支持[不同库名或表名的数据校验](/dev/reference/tools/sync-diff-inspector/route-diff.md) -* 支持[分库分表场景下的数据校验](/dev/reference/tools/sync-diff-inspector/shard-diff.md) -* 支持 [TiDB 主从集群的数据校验](/dev/reference/tools/sync-diff-inspector/tidb-diff.md) - -GitHub 地址：[sync-diff-inspector](https://github.com/pingcap/tidb-tools/tree/master/sync_diff_inspector) - -下载地址：[tidb-enterprise-tools-latest-linux-amd64](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) - -## sync-diff-inspector 的使用 - -### 使用限制 - -* 目前不支持在线校验，需要保证上下游校验的表中没有数据写入，或者保证某个范围内的数据不再变更，通过配置 `range` 来校验这个范围内的数据。 - -* 不支持 JSON、BIT、BINARY、BLOB 等类型的数据，在校验时需要设置 `ignore-columns` 忽略检查这些类型的数据。 - -* FLOAT、DOUBLE 等浮点数类型在 TiDB 和 MySQL 中的实现方式不同，在计算 checksum 时可能存在差异，如果发现因为这些类型的数据导致的数据校验不一致，需要设置 `ignore-columns` 忽略这些列的检查。 - -### 数据库权限 - -sync-diff-inspector 需要获取表结构信息、查询数据、建 checkpoint 库保存断点信息，需要的数据库权限如下： - -- 上游数据库 - - - SELECT（查数据进行对比） - - - SHOW_DATABASES (查看库名) - - - RELOAD (查看表结构) - -- 下游数据库 - - - SELECT （查数据进行对比） - - - CREATE （创建 checkpoint 库和表） - - - DELETE （删除 checkpoint 表中的信息） - - - INSERT （写入 checkpoint 表） - - - UPDATE（修改 checkpoint 表） - - - SHOW_DATABASES (查看库名) - - - RELOAD (查看表结构) - -### 配置文件说明 - -sync-diff-inspector 的配置总共分为三个部分： - -- Global config: 通用配置，包括日志级别、划分 chunk 的大小、校验的线程数量等。 -- Tables config: 配置校验哪些表，如果有的表在上下游有一定的映射关系或者有一些特殊要求，则需要对指定的表进行配置。 -- Databases config: 配置上下游数据库实例。 - -下面是一个完整配置文件的说明： - -```toml -# Diff Configuration. - -######################### Global config ######################### - -# 日志级别，可以设置为 info、debug -log-level = "info" - -# sync-diff-inspector 根据主键／唯一键／索引将数据划分为多个 chunk， -# 对每一个 chunk 的数据进行对比。使用 chunk-size 设置 chunk 的大小 -chunk-size = 1000 - -# 检查数据的线程数量 -check-thread-count = 4 - -# 抽样检查的比例，如果设置为 100 则检查全部数据 -sample-percent = 100 - -# 通过计算 chunk 的 checksum 来对比数据，如果不开启则逐行对比数据 -use-checksum = true - -# 如果设置为 true 则只会通过计算 checksum 来校验数据，如果上下游的 checksum 不一致也不会查出数据再进行校验 -only-use-checksum = false - -# 是否使用上次校验的 checkpoint，如果开启，则只校验上次未校验以及校验失败的 chunk -use-checkpoint = true - -# 不对比数据 -ignore-data-check = false - -# 不对比表结构 -ignore-struct-check = false - -# 保存用于修复数据的 sql 的文件名称 -fix-sql-file = "fix.sql" - -######################### Tables config ######################### - -# 如果需要对比大量的不同库名或者表名的表的数据，可以通过 table-rule 来设置映射关系。可以只配置 schema 或者 table 的映射关系，也可以都配置 -#[[table-rules]] - # schema-pattern 和 table-pattern 支持通配符 *? - #schema-pattern = "test_*" - #table-pattern = "t_*" - #target-schema = "test" - #target-table = "t" - -# 配置需要对比的*目标数据库*中的表 -[[check-tables]] - # 目标库中数据库的名称 - schema = "test" - - # 需要检查的表 - tables = ["test1", "test2", "test3"] - - # 支持使用正则表达式配置检查的表，需要以‘~’开始， - # 下面的配置会检查所有表名以‘test’为前缀的表 - # tables = ["~^test.*"] - # 下面的配置会检查配置库中所有的表 - # tables = ["~^"] - -# 对部分表进行特殊的配置，配置的表必须包含在 check-tables 中 -[[table-config]] - # 目标库中数据库的名称 - schema = "test" - - # 表名 - table = "test3" - - # 指定用于划分 chunk 的列，如果不配置该项，sync-diff-inspector 会选取一个合适的列（主键／唯一键／索引） - index-field = "id" - - # 指定检查的数据的范围，需要符合 sql 中 where 条件的语法 - range = "age > 10 AND age < 20" - - # 如果是对比多个分表与总表的数据，则设置为 true - is-sharding = false - - # 在某些情况下字符类型的数据的排序会不一致，通过指定 collation 来保证排序的一致， - # 需要与数据库中 charset 的设置相对应 - # collation = "latin1_bin" - - # 忽略某些列的检查，例如 sync-diff-inspector 目前还不支持的一些类型（json，bit，blob 等）， - # 或者是浮点类型数据在 TiDB 和 MySQL 中的表现可能存在差异，可以使用 ignore-columns 忽略检查这些列 - # ignore-columns = ["name"] - -# 下面是一个对比不同库名和表名的两个表的配置示例 -[[table-config]] - # 目标库名 - schema = "test" - - # 目标表名 - table = "test2" - - # 非分库分表场景，设置为 false - is-sharding = false - - # 源数据的配置 - [[table-config.source-tables]] - # 源库的实例 id - instance-id = "source-1" - # 源数据库的名称 - schema = "test" - # 源表的名称 - table = "test1" - -######################### Databases config ######################### - -# 源数据库实例的配置 -[[source-db]] - host = "127.0.0.1" - port = 3306 - user = "root" - password = "123456" - # 源数据库实例的 id，唯一标识一个数据库实例 - instance-id = "source-1" - # 使用 TiDB 的 snapshot 功能，如果开启的话会使用历史数据进行对比 - # snapshot = "2016-10-08 16:45:26" - # 设置数据库的 sql-mode，用于解析表结构 - # sql-mode = "" - -# 目标数据库实例的配置 -[target-db] - host = "127.0.0.1" - port = 4000 - user = "root" - password = "123456" - # 使用 TiDB 的 snapshot 功能，如果开启的话会使用历史数据进行对比 - # snapshot = "2016-10-08 16:45:26" - # 设置数据库的 sql-mode，用于解析表结构 - # sql-mode = "" -``` - -### 运行 sync-diff-inspector - -执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/sync_diff_inspector --config=./config.toml -``` - -该命令最终会在日志中输出一个检查报告，说明每个表的检查情况。如果数据存在不一致的情况，sync-diff-inspector 会生成 SQL 修复不一致的数据，并将这些 SQL 语句保存到 `fix.sql` 文件中。 - -### 注意事项 - -* sync-diff-inspector 在校验数据时会消耗一定的服务器资源，需要避免在业务高峰期间校验。 -* TiDB 使用的 collation 为 `utf8_bin`。如果对 MySQL 和 TiDB 的数据进行对比，需要注意 MySQL 中表的 collation 设置。如果表的主键／唯一键为 varchar 类型，且 MySQL 中 collation 设置与 TiDB 不同，可能会因为排序问题导致最终校验结果不正确，需要在 sync-diff-inspector 的配置文件中增加 collation 设置。 -* sync-diff-inspector 会优先使用 TiDB 的统计信息来划分 chunk，需要尽量保证统计信息精确，可以在**业务空闲期**手动执行 `analyze table {table_name}`。 -* table-rule 的规则需要特殊注意，例如设置了 `schema-pattern="test1"`，`target-schema="test2"`，会对比 source 中的 `test1` 库和 target 中的 `test2` 库；如果 source 中有 `test2` 库，该库也会和 target 中的 `test2` 库进行对比。 -* 生成的 `fix.sql` 仅作为修复数据的参考，需要确认后再执行这些 SQL 修复数据。 diff --git a/dev/reference/tools/syncer.md b/dev/reference/tools/syncer.md deleted file mode 100644 index 77576e289887..000000000000 --- a/dev/reference/tools/syncer.md +++ /dev/null @@ -1,604 +0,0 @@ ---- -title: Syncer 使用文档 -category: reference ---- - -# Syncer 使用文档 - -## Syncer 简介 - -Syncer 是一个数据导入工具，能方便地将 MySQL 的数据增量导入到 TiDB。 - -Syncer 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/dev/reference/tools/download.md)。 - -## Syncer 架构 - -![Syncer 架构](/media/syncer-architecture.png) - -## Syncer 部署位置 - -Syncer 可以部署在任一台可以连通对应的 MySQL 和 TiDB 集群的机器上，推荐部署在 TiDB 集群。 - -## Syncer 增量导入数据示例 - -使用前请详细阅读 [Syncer 同步前预检查](#syncer-同步前检查)。 - -### 设置同步开始的 position - -设置 Syncer 的 meta 文件, 这里假设 meta 文件是 `syncer.meta`: - -{{< copyable "shell-regular" >}} - -```bash -cat syncer.meta -``` - -``` -binlog-name = "mysql-bin.000003" -binlog-pos = 930143241 -binlog-gtid = "2bfabd22-fff7-11e6-97f7-f02fa73bcb01:1-23,61ccbb5d-c82d-11e6-ac2e-487b6bd31bf7:1-4" -``` - -> **注意：** -> -> - `syncer.meta` 只需要第一次使用的时候配置，后续 Syncer 同步新的 binlog 之后会自动将其更新到最新的 position。 -> - 如果使用 binlog position 同步则只需要配置 `binlog-name` 和 `binlog-pos`；如果使用 `binlog-gtid` 同步则需要设置 `binlog-gtid`，且启动 Syncer 时带有 `--enable-gtid`。 - -### 启动 Syncer - -Syncer 的命令行参数说明： - -``` -Usage of Syncer: - -L string - 日志等级: debug, info, warn, error, fatal (默认为 "info") - -V - 输出 Syncer 版本；默认 false - -auto-fix-gtid - 当 mysql master/slave 切换时，自动修复 gtid 信息；默认 false - -b int - batch 事务大小 (默认 100) - -c int - Syncer 处理 batch 线程数 (默认 16) - -config string - 指定相应配置文件启动 Sycner 服务；如 `--config config.toml` - -enable-ansi-quotes - 使用 ANSI_QUOTES sql_mode 来解析 SQL 语句 - -enable-gtid - 使用 gtid 模式启动 Syncer；默认 false，开启前需要上游 MySQL 开启 GTID 功能 - -flavor string - 上游数据库实例类型，目前支持 "mysql" 和 "mariadb" - -log-file string - 指定日志文件目录；如 `--log-file ./syncer.log` - -log-rotate string - 指定日志切割周期, hour/day (默认 "day") - -max-retry int - SQL 请求由于网络异常等原因出错时的最大重试次数（默认值为 100） - -meta string - 指定 Syncer 上游 meta 信息文件 (默认与配置文件相同目录下 "syncer.meta") - -persistent-dir string - 指定同步过程中历史 schema 结构的保存文件地址，如果设置为空，则不保存历史 schema 结构；如果不为空，则根据 binlog 里面包含的数据的 column 长度选择 schema 来还原 DML 语句 - -safe-mode - 指定是否开启 safe mode，让 Syncer 在任何情况下可重入 - -server-id int - 指定 MySQL slave sever-id (默认 101) - -status-addr string - 指定 Syncer metric 信息; 如 `--status-addr 127:0.0.1:10088` - -timezone string - 目标数据库使用的时区，请使用 IANA 时区标识符，如 `Asia/Shanghai` -``` - -Syncer 的配置文件 `config.toml`： - -```toml -log-level = "info" -log-file = "syncer.log" -log-rotate = "day" - -server-id = 101 - -## meta 文件地址 -meta = "./syncer.meta" -worker-count = 16 -batch = 100 -flavor = "mysql" - -## Prometheus 可以通过该地址拉取 Syncer metrics，也是 Syncer 的 pprof 调试地址 -status-addr = ":8271" - -## 如果设置为 true，Syncer 遇到 DDL 语句时就会停止退出 -stop-on-ddl = false - -## SQL 请求由于网络异常等原因出错时的最大重试次数 -max-retry = 100 - -## 指定目标数据库使用的时区，binlog 中所有 timestamp 字段会按照该时区进行转换，默认使用 Syncer 本地时区 -# timezone = "Asia/Shanghai" - -## 跳过 DDL 语句，格式为 **前缀完全匹配**，如：`DROP TABLE ABC` 至少需要填入 `DROP TABLE` -# skip-ddls = ["ALTER USER", "CREATE USER"] - -## 在使用 route-rules 功能后， -## replicate-do-db & replicate-ignore-db 匹配合表之后 (target-schema & target-table) 数值 -## 优先级关系: replicate-do-db --> replicate-do-table --> replicate-ignore-db --> replicate-ignore-table -## 指定要同步数据库名；支持正则匹配，表达式语句必须以 `~` 开始 -#replicate-do-db = ["~^b.*","s1"] - -## 指定 **忽略** 同步数据库；支持正则匹配，表达式语句必须以 `~` 开始 -#replicate-ignore-db = ["~^b.*","s1"] - -# skip-dmls 支持跳过 DML binlog events，type 字段的值可为：'insert'，'update' 和 'delete' -# 跳过 foo.bar 表的所有 delete 语句 -# [[skip-dmls]] -# db-name = "foo" -# tbl-name = "bar" -# type = "delete" -# -# 跳过所有表的 delete 语句 -# [[skip-dmls]] -# type = "delete" -# -# 跳过 foo.* 表的 delete 语句 -# [[skip-dmls]] -# db-name = "foo" -# type = "delete" - -## 指定要同步的 db.table 表 -## db-name 与 tbl-name 不支持 `db-name ="dbname，dbname2"` 格式 -#[[replicate-do-table]] -#db-name ="dbname" -#tbl-name = "table-name" - -#[[replicate-do-table]] -#db-name ="dbname1" -#tbl-name = "table-name1" - -## 指定要同步的 db.table 表；支持正则匹配，表达式语句必须以 `~` 开始 -#[[replicate-do-table]] -#db-name ="test" -#tbl-name = "~^a.*" - -## 指定 **忽略** 同步数据库 -## db-name & tbl-name 不支持 `db-name ="dbname，dbname2"` 语句格式 -#[[replicate-ignore-table]] -#db-name = "your_db" -#tbl-name = "your_table" - -## 指定要 **忽略** 同步数据库名；支持正则匹配，表达式语句必须以 `~` 开始 -#[[replicate-ignore-table]] -#db-name ="test" -#tbl-name = "~^a.*" - -# sharding 同步规则，采用 wildcharacter -# 1. 星号字符 (*) 可以匹配零个或者多个字符, -# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; -# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 -# 2. 问号字符 (?) 匹配任一一个字符 - -#[[route-rules]] -#pattern-schema = "route_*" -#pattern-table = "abc_*" -#target-schema = "route" -#target-table = "abc" - -#[[route-rules]] -#pattern-schema = "route_*" -#pattern-table = "xyz_*" -#target-schema = "route" -#target-table = "xyz" - -[from] -host = "127.0.0.1" -user = "root" -password = "" -port = 3306 - -[to] -host = "127.0.0.1" -user = "root" -password = "" -port = 4000 -``` - -启动 Syncer： - -{{< copyable "shell-regular" >}} - -```bash -./bin/syncer -config config.toml -``` - -``` -2016/10/27 15:22:01 binlogsyncer.go:226: [info] begin to sync binlog from position (mysql-bin.000003, 1280) -2016/10/27 15:22:01 binlogsyncer.go:130: [info] register slave for master server 127.0.0.1:3306 -2016/10/27 15:22:01 binlogsyncer.go:552: [info] rotate to (mysql-bin.000003, 1280) -2016/10/27 15:22:01 syncer.go:549: [info] rotate binlog to (mysql-bin.000003, 1280) -``` - -### 在 MySQL 中插入新的数据 - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (4, 4), (5, 5); -``` - -登录到 TiDB 查看： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h127.0.0.1 -P4000 -uroot -p -``` - -{{< copyable "sql" >}} - -```sql -select * from t1; -``` - -``` -+----+------+ -| id | age | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+------+ -``` - -Syncer 每隔 30s 会输出当前的同步统计，如下所示： - -``` -2017/06/08 01:18:51 syncer.go:934: [info] [syncer]total events = 15, total tps = 130, recent tps = 4, -master-binlog = (ON.000001, 11992), master-binlog-gtid=53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-74, -syncer-binlog = (ON.000001, 2504), syncer-binlog-gtid = 53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-17 -2017/06/08 01:19:21 syncer.go:934: [info] [syncer]total events = 15, total tps = 191, recent tps = 2, -master-binlog = (ON.000001, 11992), master-binlog-gtid=53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-74, -syncer-binlog = (ON.000001, 2504), syncer-binlog-gtid = 53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-35 -``` - -由上述示例可见，使用 Syncer 可以自动将 MySQL 的更新同步到 TiDB。 - -## Syncer 配置说明 - -### 指定数据库同步 - -本部分将通过实际案例描述 Syncer 同步数据库参数的优先级关系。 - -- 如果使用 route-rules 规则，参考 [Sharding 同步支持](#sharding-同步支持) -- 优先级：replicate-do-db --> replicate-do-table --> replicate-ignore-db --> replicate-ignore-table - -```toml -# 指定同步 ops 数据库 -# 指定同步以 ti 开头的数据库 -replicate-do-db = ["ops","~^ti.*"] - -# china 数据库下有 guangzhou / shanghai / beijing 等多张表，只同步 shanghai 与 beijing 表。 -# 指定同步 china 数据库下 shanghai 表 -[[replicate-do-table]] -db-name ="china" -tbl-name = "shanghai" - -# 指定同步 china 数据库下 beijing 表 -[[replicate-do-table]] -db-name ="china" -tbl-name = "beijing" - -# ops 数据库下有 ops_user / ops_admin / weekly 等数据表，只需要同步 ops_user 表。 -# 因 replicate-do-db 优先级比 replicate-do-table 高，所以此处设置只同步 ops_user 表无效，实际工作会同步 ops 整个数据库 -[[replicate-do-table]] -db-name ="ops" -tbl-name = "ops_user" - -# history 数据下有 2017_01 2017_02 ... 2017_12 / 2016_01 2016_02 ... 2016_12 等多张表，只需要同步 2017 年的数据表 -[[replicate-do-table]] -db-name ="history" -tbl-name = "~^2017_.*" - -# 忽略同步 ops 与 fault 数据库 -# 忽略同步以 www 开头的数据库 -## 因 replicate-do-db 优先级比 replicate-ignore-db 高，所以此处忽略同步 ops 不生效。 -replicate-ignore-db = ["ops","fault","~^www"] - -# fault 数据库下有 faults / user_feedback / ticket 等数据表 -# 忽略同步 user_feedback 数据表 -# 因 replicate-ignore-db 优先级比 replicate-ignore-table 高，所以此处设置只忽略同步 user_feedback 表无效，实际工作会忽略同步 fault 整个数据库 -[[replicate-ignore-table]] -db-name = "fault" -tbl-name = "user_feedback" - -# order 数据下有 2017_01 2017_02 ... 2017_12 / 2016_01 2016_02 ... 2016_12 等多张表，忽略 2016 年的数据表 -[[replicate-ignore-table]] -db-name ="order" -tbl-name = "~^2016_.*" -``` - -### Sharding 同步支持 - -根据配置文件的 route-rules，支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则，如下： - -- 是否可以利用 route-rules 的语义规则表示 -- 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 - -暂时对 DDL 支持不完善。 - -![sharding](/media/syncer-sharding.png) - -#### 分库分表同步示例 - -1. 只需在所有 MySQL 实例下面，启动 Syncer, 并设置 route-rules。 -2. `replicate-do-db` & `replicate-ignore-db` 与 route-rules 同时使用场景下，`replicate-do-db` & `replicate-ignore-db` 需要指定 route-rules 中 `target-schema` & `target-table` 的内容。 - -```toml -# 场景如下: -# 数据库A 下有 order_2016 / history_2016 等多个数据库 -# 数据库B 下有 order_2017 / history_2017 等多个数据库 -# 指定同步数据库A order_2016 数据库，数据表如下 2016_01 2016_02 ... 2016_12 -# 指定同步数据库B order_2017 数据库，数据表如下 2017_01 2017_02 ... 2017_12 -# 表内使用 order_id 作为主键，数据之间主键不冲突 -# 忽略同步 history_2016 与 history_2017 数据库 -# 目标库需要为 order ，目标数据表为 order_2017 / order_2016 - -# Syncer 获取到上游数据后，发现 route-rules 规则启用，先做合库合表操作，再进行 do-db & do-table 判定 -## 此处需要设置 target-schema & target-table 判定需要同步的数据库 -[[replicate-do-table]] -db-name ="order" -tbl-name = "order_2016" - -[[replicate-do-table]] -db-name ="order" -tbl-name = "order_2017" - -[[route-rules]] -pattern-schema = "order_2016" -pattern-table = "2016_??" -target-schema = "order" -target-table = "order_2016" - -[[route-rules]] -pattern-schema = "order_2017" -pattern-table = "2017_??" -target-schema = "order" -target-table = "order_2017" -``` - -### Syncer 同步前检查 - -1. 检查数据库版本。 - - 使用 `select @@version;` 命令检查数据库版本。目前，Syncer 只支持以下版本： - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2（更早版本的 binlog 部分字段类型格式与 MySQL 不一致） - - > **注意：** - > - > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则 - > - > - 5.7.1 < MySQL 版本 < 8.0 - > - MariaDB 版本 >= 10.1.3 - -2. 检查源库 `server-id`。 - - 可通过以下命令查看 `server-id`： - - {{< copyable "sql" >}} - - ```sql - show global variables like 'server_id'; - ``` - - ``` - +---------------+-------+ - | Variable_name | Value | - +---------------+-------+ - | server_id | 1 | - +---------------+-------+ - 1 row in set (0.01 sec) - ``` - - - 结果为空或者为 0，Syncer 无法同步数据。 - - Syncer `server-id` 与 MySQL `server-id` 不能相同，且必须在 MySQL cluster 中唯一。 - -3. 检查 Binlog 相关参数。 - - 1. 检查 MySQL 是否开启了 binlog。 - - 使用如下命令确认是否开启了 binlog： - - {{< copyable "sql" >}} - - ```sql - show global variables like 'log_bin'; - ``` - - ``` - +--------------------+---------+ - | Variable_name | Value | - +--------------------+---------+ - | log_bin | ON | - +--------------------+---------+ - 1 row in set (0.00 sec) - ``` - - 如果结果是 `log_bin` = `OFF`，则需要开启 binlog，开启方式请参考[官方文档](https://dev.mysql.com/doc/refman/5.7/en/replication-howto-masterbaseconfig.html)。 - - 2. binlog 格式必须为 `ROW`，且参数 `binlog_row_image` 必须设置为 `FULL`，可使用如下命令查看参数设置： - - {{< copyable "shell-regular" >}} - - ```sql - select variable_name, variable_value from information_schema.global_variables where variable_name in ('binlog_format','binlog_row_image'); - ``` - - ``` - +------------------+----------------+ - | variable_name | variable_value | - +------------------+----------------+ - | BINLOG_FORMAT | ROW | - | BINLOG_ROW_IMAGE | FULL | - +------------------+----------------+ - 2 rows in set (0.001 sec) - ``` - - - 如果以上设置出现错误，则需要修改磁盘上的配置文件，然后重启 MySQL。 - - 将配置的更改持久化存储在磁盘上很重要，这样在 MySQL 重启之后才能显示相应更改。 - - 由于现有的连接会保留全局变量原先的值，所以**不可以**使用 `SET` 语句动态修改这些设置。 - -4. 检查用户权限。 - - 1. 全量导出的 Mydumper 需要的用户权限。 - - - Mydumper 导出数据至少拥有以下权限：`select, reload`。 - - Mydumper 操作对象为 RDS 时，可以添加 `--no-locks` 参数，避免申请 `reload` 权限。 - - 2. 增量同步 Syncer 需要的上游 MySQL/MariaDB 用户权限。 - - 需要上游 MySQL 同步账号至少赋予以下权限： - - ``` - select, replication slave, replication client - ``` - - 3. 下游 TiDB 需要的权限 - - | 权限 | 作用域 | - |----:|:------| - | SELECT | Tables | - | INSERT | Tables | - | UPDATE | Tables | - | DELETE | Tables | - | CREATE | Databases,tables | - | DROP | Databases, tables | - | ALTER | Tables | - | INDEX | Tables | - - 为所同步的数据库或者表，执行下面的 GRANT 语句： - - {{< copyable "sql" >}} - - ```sql - GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,INDEX ON db.table TO 'your_user'@'your_wildcard_of_host'; - ``` - -5. 检查 SQL mode。 - - 必须确认上下游的 SQL mode 一致；如果不一致，则会出现数据同步的错误。 - - {{< copyable "sql" >}} - - ```sql - show variables like '%sql_mode%'; - ``` - - ``` - +---------------+-----------------------------------------------------------------------------------+ - | Variable_name | Value | - +---------------+-----------------------------------------------------------------------------------+ - | sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | - +---------------+-----------------------------------------------------------------------------------+ - 1 row in set (0.01 sec) - ``` - -6. 检查字符集。 - - TiDB 和 MySQL 的字符集的兼容性不同，详见 [TiDB 支持的字符集](/dev/reference/sql/character-set.md)。 - -7. 检查同步的表是否都有主键或者唯一索引。 - - 如果表没有主键或唯一索引，就没法实现幂等，并且此时在下游更新每条数据时都是扫全表，可能导致同步速度变慢，所以建议同步的表都加上主键。 - -## 监控方案 - -Syncer 使用开源时序数据库 Prometheus 作为监控和性能指标信息存储方案，使用 Grafana 作为可视化组件进行展示，配合 AlertManager 来实现报警。其方案如下图所示： - -![monitor_scheme](/media/syncer-monitor-scheme.png) - -### 配置 Syncer 监控与告警 - -Syncer 对外提供 metric 接口，需要 Prometheus 主动获取数据。配置 Syncer 监控与告警的操作步骤如下： - -1. 在 Prometheus 中添加 Syncer job 信息，将以下内容刷新到 Prometheus 配置文件，重启 Prometheus 后生效。 - - ```yaml - - job_name: 'syncer_ops' // 任务名字，区分数据上报 - static_configs: - - targets: ['10.1.1.4:10086'] // Syncer 监听地址与端口，通知 Prometheus 获取 Syncer 的监控数据。 - ``` - -2. 配置 Prometheus [告警](https://prometheus.io/docs/alerting/alertmanager/)，将以下内容刷新到 `alert.rule` 配置文件，重启 Prometheus 后生效。 - - ``` - # syncer - ALERT syncer_status - IF syncer_binlog_file{node='master'} - ON(instance, job) syncer_binlog_file{node='syncer'} > 1 - FOR 1m - LABELS {channels="alerts", env="test-cluster"} - ANNOTATIONS { - summary = "syncer status error", - description="alert: syncer_binlog_file{node='master'} - ON(instance, job) syncer_binlog_file{node='syncer'} > 1 instance: {{ $labels.instance }} values: {{ $value }}", - } - ``` - -#### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000` ，默认账号: admin 密码: admin） - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 Dashboard [配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json)上传 -> 选择对应的 data source - -### Grafana Syncer metrics 说明 - -#### title: binlog events - -- metrics: `rate(syncer_binlog_event_count[1m])` -- info: 统计 Syncer 每秒已经收到的 binlog 个数 - -#### title: binlog event transform - -- metrics: `histogram_quantile(0.8, sum(rate(syncer_binlog_event_bucket[1m])) by (le))` -- info: Syncer 把 binlog 转换为 SQL 语句的耗时 - -#### title: transaction latency - -- metrics: `histogram_quantile(0.95, sum(rate(syncer_txn_cost_in_second_bucket[1m])) by (le))` -- info: Syncer 在下游 TiDB 执行 transaction 的耗时 - -#### title: transaction tps - -- metrics: `rate(syncer_txn_cost_in_second_count[1m])` -- info: Syncer 在下游 TiDB 每秒执行的 transaction 个数 - -#### title: binlog file gap - -- metrics: `syncer_binlog_file{node="master"} - ON(instance, job) syncer_binlog_file{node="syncer"}` -- info: Syncer 已经同步到的 binlog position 的文件编号距离上游 MySQL 当前 binlog position 的文件编号的值；注意 MySQL 当前 binlog position 是定期查询，在一些情况下该 metrics 会出现负数的情况 - -#### title: binlog skipped events - -- metrics: `rate(syncer_binlog_skipped_events_total[1m])` -- info: Syncer 跳过的 binlog 的个数，你可以在配置文件中配置 `skip-ddls` 和 `skip-dmls` 来跳过指定的 binlog - -#### title: position of binlog position - -- metrics: `syncer_binlog_pos{node="syncer"}` and `syncer_binlog_pos{node="master"}` -- info: 需配合 `file number of binlog position` 一起看。`syncer_binlog_pos{node="master"}` 表示上游 MySQL 当前 binlog position 的 position 值，`syncer_binlog_pos{node="syncer"}` 表示上游 Syncer 已经同步到的 binlog position 的 position 值 - -#### title: file number of binlog position - -- metrics: `syncer_binlog_file{node="syncer"}` and `syncer_binlog_file{node="master"}` -- info: 需要配置 `position of binlog position` 一起看。`syncer_binlog_file{node="master"}` 表示上游 MySQL 当前 binlog position 的文件编号，`syncer_binlog_file{node="syncer"}` 表示上游 Syncer 已经同步到的 binlog 位置的文件编号 - -#### title: execution jobs - -- metrics: `sum(rate(syncer_add_jobs_total[1m])) by (queueNo)` -- info: Syncer 把 binlog 转换成 SQL 语句后，将 SQL 语句以 jobs 的方式加到执行队列中，这个 metrics 表示已经加入执行队列的 jobs 总数 - -#### title: pending jobs - -- metrics: `sum(rate(syncer_add_jobs_total[1m]) - rate(syncer_finished_jobs_total[1m])) by (queueNo)` -- info: 已经加入执行队列但是还没有执行的 jobs 数量 diff --git a/dev/reference/tools/tidb-lightning/config.md b/dev/reference/tools/tidb-lightning/config.md deleted file mode 100644 index e590153139a9..000000000000 --- a/dev/reference/tools/tidb-lightning/config.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -title: TiDB Lightning 配置参数 -summary: 使用配置文件或命令行配置 TiDB Lightning。 -category: reference ---- - -# TiDB Lightning 配置参数 - -你可以使用配置文件或命令行配置 TiDB Lightning。本文主要介绍 TiDB Lightning 的全局配置、任务配置和 TiKV Importer 的配置，以及如何使用命令行进行参数配置。 - -## 配置文件 - -TiDB Lightning 的配置文件分为“全局”和“任务”两种类别，二者在结构上兼容。只有当[服务器模式](/dev/reference/tools/tidb-lightning/web.md)开启时，全局配置和任务配置才会有区别；默认情况下，服务器模式为禁用状态，此时 TiDB Lightning 只会执行一个任务，且全局和任务配置使用同一配置文件。 - -### TiDB Lightning 全局配置 - -```toml -### tidb-lightning 全局配置 - -[lightning] -# 用于拉取 web 界面和 Prometheus 监控项的 HTTP 端口。设置为 0 时为禁用状态。 -status-addr = ':8289' - -# 切换为服务器模式并使用 web 界面 -# 详情参见“TiDB Lightning web 界面”文档 -server-mode = false - -# 日志 -level = "info" -file = "tidb-lightning.log" -max-size = 128 # MB -max-days = 28 -max-backups = 14 -``` - -### TiDB Lightning 任务配置 - -```toml -### tidb-lightning 任务配置 - -[lightning] -# 启动之前检查集群是否满足最低需求。 -# check-requirements = true - -# 引擎文件的最大并行数。 -# 每张表被切分成一个用于存储索引的“索引引擎”和若干存储行数据的“数据引擎”。 -# 这两项设置控制两种引擎文件的最大并发数。 -# 这两项设置的值会影响 tikv-importer 的内存和磁盘用量。 -# 两项数值之和不能超过 tikv-importer 的 max-open-engines 的设定。 -index-concurrency = 2 -table-concurrency = 6 - -# 数据的并发数。默认与逻辑 CPU 的数量相同。 -# 混合部署的情况下可以将其大小配置为逻辑 CPU 数的 75%，以限制 CPU 的使用。 -# region-concurrency = - -# I/O 最大并发数。I/O 并发量太高时，会因硬盘内部缓存频繁被刷新 -# 而增加 I/O 等待时间，导致缓存未命中和读取速度降低。 -# 对于不同的存储介质，此参数可能需要调整以达到最佳效率。 -io-concurrency = 5 - -[checkpoint] -# 是否启用断点续传。 -# 导入数据时，TiDB Lightning 会记录当前表导入的进度。 -# 所以即使 Lightning 或其他组件异常退出，在重启时也可以避免重复再导入已完成的数据。 -enable = true -# 存储断点的数据库名称。 -schema = "tidb_lightning_checkpoint" -# 存储断点的方式。 -# - file：存放在本地文件系统。 -# - mysql：存放在兼容 MySQL 的数据库服务器。 -driver = "file" - -# dsn 是数据源名称 (data source name)，表示断点的存放位置。 -# 若 driver = "file"，则 dsn 为断点信息存放的文件路径。 -#若不设置该路径，则默认存储路径为“/tmp/CHECKPOINT_SCHEMA.pb”。 -# 若 driver = "mysql"，则 dsn 为“用户:密码@tcp(地址:端口)/”格式的 URL。 -# 若不设置该 URL，则默认会使用 [tidb] 部分指定的 TiDB 服务器来存储断点。 -# 为减少目标 TiDB 集群的压力，建议指定另一台兼容 MySQL 的数据库服务器来存储断点。 -# dsn = "/tmp/tidb_lightning_checkpoint.pb" - -# 所有数据导入成功后是否保留断点。设置为 false 时为删除断点。 -# 保留断点有利于进行调试，但会泄漏关于数据源的元数据。 -# keep-after-success = false - -[tikv-importer] -# 选择后端：“importer” 或 “tidb“ -# backend = "importer" -# 当后端是 “importer” 时，tikv-importer 的监听地址（需改为实际地址）。 -addr = "172.16.31.10:8287" -# 当后端是 “tidb” 时，插入重复数据时执行的操作。 -# - replace：新数据替代已有数据 -# - ignore：保留已有数据，忽略新数据 -# - error：中止导入并报错 -# on-duplicate = "replace" - -[mydumper] -# 设置文件读取的区块大小，确保该值比数据源的最长字符串长。 -read-block-size = 65536 # Byte (默认为 64 KB) - -# （源数据文件）单个导入区块大小的最小值。 -# Lightning 根据该值将一张大表分割为多个数据引擎文件。 -batch-size = 107_374_182_400 # Byte (默认为 100 GB) - -# 引擎文件需按顺序导入。由于并行处理，多个数据引擎几乎在同时被导入， -# 这样形成的处理队列会造成资源浪费。因此，为了合理分配资源，Lightning -# 稍微增大了前几个区块的大小。该参数也决定了比例系数，即在完全并发下 -# “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GB 大小的 -# 单张表的（导入时长/写入时长）得到。在日志文件中可以看到精确的时间。 -# 如果“导入”更快，区块大小的差异就会更小；比值为 0 时则说明区块大小一致。 -# 取值范围为（0 <= batch-import-ratio < 1）。 -batch-import-ratio = 0.75 - -# mydumper 本地源数据目录。 -data-source-dir = "/data/my_database" -# 如果 no-shcema = false，那么 TiDB Lightning 假设目标 TiDB 集群上 -# 已有表结构，并且不会执行 `CREATE TABLE` 语句。 -no-schema = false -# 指定包含 `CREATE TABLE` 语句的表结构文件的字符集。只支持下列选项： -# - utf8mb4：表结构文件必须使用 UTF-8 编码，否则 Lightning 会报错。 -# - gb18030：表结构文件必须使用 GB-18030 编码，否则 Lightning 会报错。 -# - auto：自动判断文件编码是 UTF-8 还是 GB-18030，两者皆非则会报错（默认）。 -# - binary：不尝试转换编码。 -# 注意：**数据** 文件始终解析为 binary 文件。 -character-set = "auto" - -# 配置 CSV 文件的解析方式。 -[mydumper.csv] -# 字段分隔符，应为单个 ASCII 字符。 -separator = ',' -# 引用定界符，可为单个 ASCII 字符或空字符串。 -delimiter = '"' -# CSV 文件是否包含表头。 -# 如果 header = true，将跳过首行。 -# CSV 文件是否包含 NULL。 -# 如果 not-null = true，CSV 所有列都不能解析为 NULL。 -not-null = false -# 如果 not-null = false（即 CSV 可以包含 NULL）， -# 为以下值的字段将会被解析为 NULL。 -null = '\N' -# 是否对字段内“\“进行转义 -backslash-escape = true -# 如果有行以分隔符结尾，删除尾部分隔符。 -trim-last-separator = false - -[tidb] -# 目标集群的信息。tidb-server 的地址，填一个即可。 -host = "172.16.31.1" -port = 4000 -user = "root" -password = "" -# 表结构信息从 TiDB 的“status-port”获取。 -status-port = 10080 -# pd-server 的地址，填一个即可。 -pd-addr = "172.16.31.4:2379" -# tidb-lightning 引用了 TiDB 库，并生成产生一些日志。 -# 设置 TiDB 库的日志等级。 -log-level = "error" - -# 设置 TiDB 会话变量，提升 Checksum 和 Analyze 的速度。 -# 各参数定义可参阅”控制 Analyze 并发度“文档 -build-stats-concurrency = 20 -distsql-scan-concurrency = 100 -index-serial-scan-concurrency = 20 -checksum-table-concurrency = 16 - -# 解析和执行 SQL 语句的默认 SQL 模式。 -sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" -# `max-allowed-packet` 设置数据库连接允许的最大数据包大小， -# 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0， -# 会使用下游数据库 global 级别的 `max_allowed_packet`。 -max-allowed-packet = 67_108_864 - -# 数据导入完成后，tidb-lightning 可以自动执行 Checksum、Compact 和 Analyze 操作。 -# 在生产环境中，建议这将些参数都设为 true。 -# 执行的顺序为：Checksum -> Compact -> Analyze。 -[post-restore] -# 如果设置为 true，会对所有表逐个执行 `ADMIN CHECKSUM TABLE
` 操作 -# 来验证数据的完整性。 -checksum = true -# 如果设置为 true，会在导入每张表后执行一次 level-1 Compact。 -# 默认值为 false。 -level-1-compact = false -# 如果设置为 true，会在导入过程结束时对整个 TiKV 集群执行一次 full Compact。 -# 默认值为 false。 -compact = false -# 如果设置为 true，会对所有表逐个执行 `ANALYZE TABLE
` 操作。 -analyze = true - -# 设置周期性后台操作。 -# 支持的单位：h（时）、m（分）、s（秒）。 -[cron] -# Lightning 自动刷新导入模式状态的持续时间，该值应小于 TiKV 对应的设定值。 -switch-mode = "5m" -# 在日志中打印导入进度的持续时间。 -log-progress = "5m" - -# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 -# [black-white-list] -# ... -``` - -### TiKV Importer 配置参数 - -```toml -# TiKV Importer 配置文件模版 - -# 日志文件 -log-file = "tikv-importer.log" -# 日志等级：trace, debug, info, warn, error 和 off -log-level = "info" - -[server] -# tikv-importer 的监听地址，tidb-lightning 需要连到这个地址进行数据写入。 -addr = "192.168.20.10:8287" -# gRPC 服务器的线程池大小。 -grpc-concurrency = 16 - -[metric] -# 给 Prometheus 客户端推送的 job 名称。 -job = "tikv-importer" -# 给 Prometheus 客户端推送的间隔。 -interval = "15s" -# Prometheus Pushgateway 的地址。 -address = "" - -[rocksdb] -# background job 的最大并发数。 -max-background-jobs = 32 - -[rocksdb.defaultcf] -# 数据在刷新到硬盘前能存于内存的容量上限。 -write-buffer-size = "1GB" -# 内存中写缓冲器的最大数量。 -max-write-buffer-number = 8 - -# 各个压缩层级使用的算法。 -# 第 0 层的算法用于压缩 KV 数据。 -# 第 6 层的算法用于压缩 SST 文件。 -# 第 1 至 5 层的算法目前尚未使用。 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[rocksdb.writecf] -# 同上 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[import] -# 存储引擎文件的文件夹路径 -import-dir = "/mnt/ssd/data.import/" -# 处理 RPC 请求的线程数 -num-threads = 16 -# 导入 job 的并发数。 -num-import-jobs = 24 -# 预处理 Region 最长时间。 -# max-prepare-duration = "5m" -# 把要导入的数据切分为这个大小的 Region。 -#region-split-size = "512MB" -# 设置 stream-channel-window 的大小。 -# channel 满了之后 stream 会处于阻塞状态。 -# stream-channel-window = 128 -# 同时打开引擎文档的最大数量。 -max-open-engines = 8 -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# upload-speed-limit = "512MB" -# 目标存储可用空间比率（store_available_space/store_capacity）的最小值。 -# 如果目标存储空间的可用比率低于该值，Importer 将会暂停上传 SST -# 来为 PD 提供足够时间进行 Regions 负载均衡。 -min-available-ratio = 0.05 -``` - -## 命令行参数 - -### `tidb-lightning` - -使用 `tidb-lightning` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:----| -| --config *file* | 从 *file* 读取全局设置。如果没有指定则使用默认设置。 | | -| -V | 输出程序的版本 | | -| -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | -| -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | -| --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/dev/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | -| --log-file *file* | 日志文件路径 | `lightning.log-file` | -| --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | -| --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | -| --pd-urls *host:port* | PD endpoint 的地址 | `tidb.pd-addr` | -| --tidb-host *host* | TiDB Server 的 host | `tidb.host` | -| --tidb-port *port* | TiDB Server 的端口（默认为 4000） | `tidb.port` | -| --tidb-status *port* | TiDB Server 的状态端口的（默认为 10080） | `tidb.status-port` | -| --tidb-user *user* | 连接到 TiDB 的用户名 | `tidb.user` | -| --tidb-password *password* | 连接到 TiDB 的密码 | `tidb.password` | - -如果同时对命令行参数和配置文件中的对应参数进行更改，命令行参数将优先生效。例如，在 `cfg.toml` 文件中，不管对日志等级做出什么修改，运行 `./tidb-lightning -L debug --config cfg.toml` 命令总是将日志级别设置为 “debug”。 - -### `tidb-lightning-ctl` - -使用 `tidb-lightning-ctl` 可以对下列参数进行配置： - -| 参数 | 描述 | -|:----|:----------| -| --compact | 执行 full compact | -| --switch-mode *mode* | 将每个 TiKV Store 切换到指定模式（normal 或 import） | -| --import-engine *uuid* | 将 TiKV Importer 上关闭的引擎文件导入到 TiKV 集群 | -| --cleanup-engine *uuid* | 删除 TiKV Importer 上的引擎文件 | -| --checkpoint-dump *folder* | 将当前的断点以 CSV 格式存储到文件夹中 | -| --checkpoint-error-destroy *tablename* | 删除断点，如果报错则删除该表 | -| --checkpoint-error-ignore *tablename* | 忽略指定表中断点的报错 | -| --checkpoint-remove *tablename* | 无条件删除表的断点 | - -*tablename* 必须是`` `db`.`tbl` `` 中的限定表名（包括反引号），或关键词 `all`。 - -此外，上表中所有 `tidb-lightning` 的参数也适用于 `tidb-lightning-ctl`。 - -### `tikv-importer` - -使用 `tikv-importer` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:-------| -| -C, --config *file* | 从 *file* 读取配置。如果没有指定，则使用默认设置| | -| -V, --version | 输出程序的版本 | | -| -A, --addr *ip:port* | TiKV Importer 服务器的监听地址 | `server.addr` | -| --import-dir *dir* | 引擎文件的存储目录 | `import.import-dir` | -| --log-level *level* | 日志的等级： trace、debug、info、warn、error 或 off | `log-level` | -| --log-file *file* | 日志文件路径 | `log-file` | diff --git a/dev/reference/tools/tidb-lightning/deployment.md b/dev/reference/tools/tidb-lightning/deployment.md deleted file mode 100644 index 11a358bb9da9..000000000000 --- a/dev/reference/tools/tidb-lightning/deployment.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: TiDB Lightning 部署与执行 -category: reference ---- - -# TiDB Lightning 部署与执行 - -本文主要介绍 TiDB Lightning 使用 Importer-backend（默认）进行数据导入的硬件需求，以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 - -如果你想改用 TiDB-backend 进行数据导入，参考 [TiDB Lightning TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 - -## 注意事项 - -在使用 TiDB Lightning 前，需注意以下事项： - -- TiDB Lightning 运行后，TiDB 集群将无法正常对外提供服务。 -- 若 `tidb-lightning` 崩溃，集群会留在“导入模式”。若忘记转回“普通模式”，集群会产生大量未压缩的文件，继而消耗 CPU 并导致延迟。此时，需要使用 `tidb-lightning-ctl` 手动将集群转回“普通模式”： - - {{< copyable "shell-regular" >}} - - ```sh - bin/tidb-lightning-ctl -switch-mode=normal - ``` - -- TiDB Lightning 需要下游 TiDB 有如下权限： - - | 权限 | 作用域 | - |:----|:------| - | SELECT | Tables | - | INSERT | Tables | - | UPDATE | Tables | - | DELETE | Tables | - | CREATE | Databases, tables | - | DROP | Databases, tables | - | ALTER | Tables | - - 如果配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## 硬件需求 - -`tidb-lightning` 和 `tikv-importer` 这两个组件皆为资源密集程序，建议各自单独部署。 - -为了优化效能，建议硬件配置如下： - -- `tidb-lightning` - - - 32+ 逻辑核 CPU - - 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程默认会占满 CPU，建议单独部署。条件不允许的情况下可以和其他组件（比如 `tidb-server`）部署在同一台机器上，然后通过配置 `region-concurrency` 限制 `tidb-lightning` 使用 CPU 资源。 - -- `tikv-importer` - - - 32+ 逻辑核 CPU - - 40 GB+ 内存 - - 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000） - * 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程中 CPU、I/O 和网络带宽都可能占满，建议单独部署。 - -如果机器充裕的话，可以部署多套 `tidb-lightning` + `tikv-importer`，然后将源数据以表为粒度进行切分，并发导入。 - -> **注意：** -> -> - `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 资源分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 “24”。 -> -> - `tikv-importer` 将中间数据存储缓存到内存上以加速导入过程。占用内存大小可以通过 **(`max-open-engines` × `write-buffer-size` × 2) + (`num-import-jobs` × `region-split-size` × 2)** 计算得来。如果磁盘写入速度慢，缓存可能会带来更大的内存占用。 - -此外，目标 TiKV 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](/dev/how-to/deploy/hardware-recommendations.md)以外，目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](/dev/faq/tidb.md#326-每个-region-的-replica-数量可配置吗调整的方法是) × 2**。例如集群默认使用 3 副本，那么总存储空间需为数据源大小的 6 倍以上。 - -## 导出数据 - -使用 [`mydumper`](/dev/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果数据源是 CSV 文件，请参考 [CSV 支持](/dev/reference/tools/tidb-lightning/csv.md)获取配置信息。 - -## 部署 TiDB Lightning - -本节介绍 TiDB Lightning 的两种部署方式：[使用 Ansible 部署](#使用-ansible-部署-tidb-lightning)和[手动部署](#手动部署-tidb-lightning)。 - -### 使用 Ansible 部署 TiDB Lightning - -TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/dev/how-to/deploy/orchestrated/ansible.md)。 - -1. 编辑 `inventory.ini`，分别配置一个 IP 来部署 `tidb-lightning` 和 `tikv-importer`。 - - ```ini - ... - - [importer_server] - 192.168.20.9 - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 修改 `group_vars/*.yml` 的变量配置这两个工具。 - - - `group_vars/all.yml` - - ```yaml - ... - # tikv-importer 的监听端口。需对 tidb-lightning 服务器开放。 - tikv_importer_port: 8287 - ... - ``` - - - `group_vars/lightning_server.yml` - - ```yaml - --- - dummy: - - # 提供监控告警的端口。需对监控服务器 (monitoring_server) 开放。 - tidb_lightning_pprof_port: 8289 - - # 获取数据源（Mydumper SQL dump 或 CSV）的路径。 - data_source_dir: "{{ deploy_dir }}/mydumper" - ``` - - - `group_vars/importer_server.yml` - - ```yaml - --- - dummy: - - # 储存引擎文件的路径。需存放在空间足够大的分区。 - import_dir: "{{ deploy_dir }}/data.import" - ``` - -3. 开始部署。 - - {{< copyable "shell-regular" >}} - - ```sh - ansible-playbook bootstrap.yml && - ansible-playbook deploy.yml - ``` - -4. 将数据源写入 `data_source_dir` 指定的路径。 - -5. 登录 `tikv-importer` 的服务器，并执行以下命令来启动 Importer。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_importer.sh - ``` - -6. 登录 `tidb-lightning` 的服务器，并执行以下命令来启动 Lightning，开始导入过程。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_lightning.sh - ``` - -7. 完成后，在 `tikv-importer` 的服务器执行 `scripts/stop_importer.sh` 来关闭 Importer。 - -### 手动部署 TiDB Lightning - -#### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群 (版本要求 2.0.9 以上)，建议使用最新版。部署方法可参考 [TiDB 快速入门指南](/dev/overview.md#部署方式)。 - -#### 第 2 步：下载 TiDB Lightning 安装包 - -在[工具下载](/dev/reference/tools/download.md#tidb-lightning)页面下载 TiDB Lightning 安装包（需选择与 TiDB 集群相同的版本）。 - -#### 第 3 步：启动 `tikv-importer` - -1. 从安装包上传 `bin/tikv-importer`。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [metric] - # 给 Prometheus 客户端的推送任务名称。 - job = "tikv-importer" - # 给 Prometheus 客户端的推送间隔。 - interval = "15s" - # Prometheus Pushgateway 地址。 - address = "" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - - 上面仅列出了 `tikv-importer` 的基本配置。完整配置请参考[`tikv-importer` 配置说明](/dev/reference/tools/tidb-lightning/config.md#tikv-importer)。 - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -#### 第 4 步：启动 `tidb-lightning` - -1. 从安装包上传 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl`。 - -2. 将数据源写入到同样的机器。 - -3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置，TiDB Lightning 给出配置错误的提醒并退出。 - - ```toml - [lightning] - - # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。 - # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。 - # region-concurrency = - - # 日志 - level = "info" - file = "tidb-lightning.log" - - [tikv-importer] - # tikv-importer 的监听地址，需改成 tikv-importer 服务器的实际地址。 - addr = "172.16.31.10:8287" - - [mydumper] - # Mydumper 源数据目录。 - data-source-dir = "/data/my_database" - - [tidb] - # 目标集群的信息。tidb-server 的监听地址，填一个即可。 - host = "172.16.31.1" - port = 4000 - user = "root" - password = "" - # 表架构信息在从 TiDB 的“状态端口”获取。 - status-port = 10080 - ``` - - 上面仅列出了 `tidb-lightning` 的基本配置信息。完整配置信息请参考[`tidb-lightning` 配置说明](/dev/reference/tools/tidb-lightning/config.md#tidb-lightning-全局配置)。 - -4. 运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & - ``` - -## 升级 TiDB Lightning - -你可以通过替换二进制文件升级 TiDB Lightning，无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/dev/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 - -如果当前有运行的导入任务，推荐任务完成后再升级 TiDB Lightning。否则，你可能需要从头重新导入，因为无法保证断点可以跨版本工作。 diff --git a/dev/reference/tools/tidb-lightning/glossary.md b/dev/reference/tools/tidb-lightning/glossary.md deleted file mode 100644 index c467770e48f9..000000000000 --- a/dev/reference/tools/tidb-lightning/glossary.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: TiDB Lightning 术语表 -summary: 了解 TiDB Lightning 相关的术语及定义。 -category: glossary ---- - -# TiDB Lightning 术语表 - -本术语表提供了 TiDB Lightning 相关的术语和定义，这些术语会出现在 TiDB Lightning 的日志、监控指标、配置和文档中。 - - - -## A - -### Analyze - -统计信息分析。指重建 TiDB 表中的统计信息，即运行 [`ANALYZE TABLE`](/dev/reference/sql/statements/analyze-table.md) 语句。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，统计信息不会自动更新，所以 TiDB Lightning 在导入后显式地分析每个表。如果不需要该操作，可以将 `post-restore.analyze` 设置为 `false`。 - -### `AUTO_INCREMENT_ID` - -用于为自增列分配默认值的自增 ID 计数器。每张表都有一个相关联的 `AUTO_INCREMENT_ID` 计数器。在 TiDB 中，该计数器还用于分配行 ID。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，`AUTO_INCREMENT_ID` 计数器不会自动更新，所以 TiDB Lightning 显式地将 `AUTO_INCREMENT_ID` 改为一个有效值。即使表中没有自增列，这步仍是会执行。 - - - -## B - -### Backend - -也称作 Back end（后端），用于接受 TiDB Lightning 解析结果。 - -详情参阅 [TiDB Lightning TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md)。 - -### Black-white list - -黑白名单配置列表。用于指定要导入、忽略哪些表和库。 - -详情参阅 [TiDB Lightning 表库过滤](/dev/reference/tools/tidb-lightning/table-filter.md)。 - - - -## C - -### Checkpoint - -断点。用于保证 TiDB Lightning 在导入数据时不断地将进度保存到本地文件或远程数据库中。这样即使进程崩溃，TiDB Lightning 也能从中间状态恢复。 - -详情参见 [TiDB Lightning 断点续传](/dev/reference/tools/tidb-lightning/checkpoints.md)。 - -### Checksum - -校验和。一种用于[验证导入数据正确性](/dev/faq/tidb-lightning.md#如何校验导入的数据的正确性)的方法。 - -在 TiDB Lightning 中，表的校验和是由 3 个数字组成的集合，由该表中每个键值对的内容计算得出。这些数字分别是： - -* 键值对的数量 -* 所有键值对的总长度 -* 每个键值对 [CRC-64-ECMA](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) 按位异或的结果 - -TiDB Lightning 通过比较每个表的[本地校验和](#local-checksum)和[远程校验和](#remote-checksum)来验证导入数据的正确性。如果有任一对校验和不匹配，导入进程就会停止。如果你需要跳过校验和检查，可以将 `post-restore.checksum` 设置为 `false` 。 - -遇到校验和不匹配的问题时，参考[故障排查](/dev/how-to/troubleshoot/tidb-lightning.md#checksum-failed-checksum-mismatched-remote-vs-local)进行处理。 - -### Chunk - -指数据源中的单个文件。 - -### Compaction - -压缩。指将多个小 SST 文件合并为一个大 SST 文件并清理已删除的条目。TiDB Lightning 导入数据时，TiKV 在后台会自动压缩数据。 - -> **注意：** -> -> 出于遗留原因，你仍然可以将 TiDB Lightning 配置为在每次导入表时进行显式压缩，但是官方不推荐采用该操作，且该操作的相关设置默认是禁用的。 -> -> 技术细节参阅 [RocksDB 关于压缩的说明](https://github.com/facebook/rocksdb/wiki/Compaction)。 - - - -## D - -### Data engine - -数据引擎。用于对实际的行数据进行排序的[引擎](#engine)。 - -当一个表数据很多的时候，表的数据会被放置在多个数据引擎中以改善任务流水线并节省 TiKV Importer 的空间。默认条件下，每 100 GB 的 SQL 数据会打开一个新的数据引擎（可通过 `mydumper.batch-size` 配置项进行更改）。 - -TiDB Lightning 同时处理多个数据引擎（可通过 `lightning.table-concurrency` 配置项进行更改）。 - - - -## E - -### Engine - -引擎。在 TiKV Importer 中，一个引擎就是一个用于排序键值对的 RocksDB 实例。 - -TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先打开一个引擎，向其发送未排序的键值对，然后关闭引擎。随后，引擎会对收到的键值对进行排序操作。这些关闭的引擎可以进一步上传至 TiKV store 中为 [Ingest](#ingest) 做准备。 - -引擎使用 TiKV Importer 的 `import-dir` 作为临时存储，有时也会被称为引擎文件 (engine files)。 - -另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 - - - -## I - -### Import mode - -导入模式。指通过降低读取速度和减少空间使用，来优化 TiKV 写入的配置模式。 - -导入过程中，TiDB Lightning 自动在导入模式和[普通模式](#normal-mode)中来回切换。如果 TiKV 卡在导入模式，你可以使用 `tidb-lightning-ctl` [强制切换回普通模式](/dev/faq/tidb-lightning.md#为什么用过-tidb-lightning-之后tidb-集群变得又慢又耗-cpu)。 - -### Index engine - -索引引擎。用于对索引进行排序的[引擎](#engine)。 - -不管表中有多少索引，每张表都只对应**一个**索引引擎。 - -TiDB Lightning 可同时处理多个索引引擎（可通过 `lightning.index-concurrency` 配置项进行更改）。由于每张表正好对应一个索引引擎，`lightning.index-concurrency` 配置项也限定了可同时处理的表的最大数量。 - -### Ingest - -指将 [SST 文件](#sst-file)的全部内容插入到 RocksDB（TiKV）store 中的操作。 - -与逐个插入键值对相比，Ingest 的效率非常高。因此，该操作直接决定了 TiDB Lightning 的性能。 - -技术细节参阅 [RocksDB 关于创建、Ingest SST 文件的 wiki 页面](https://github.com/facebook/rocksdb/wiki/Creating-and-Ingesting-SST-files)。 - - - -## K - -### KV pair - -即 key-value pair（键值对）。 - -### KV encoder - -用于将 SQL 或 CSV 行解析为键值对的例程。多个 KV encoder 会并行运行以加快处理速度。 - - - -## L - -### Local checksum - -本地校验和。在将键值对发送到 TiKV Importer 前，由 TiDB Lightning 计算的表的校验和。 - - - -## N - -### Normal mode - -普通模式。未启用[导入模式](#import-mode)时的模式。 - - - -## P - -### Post-processing - -指整个数据源被解析发送到 TiKV Importer 之后的一段时间。此时 TiDB Lightning 正在等待 TiKV Importer 上传、[Ingest](#ingest) [SST 文件](#sst-file)。 - - - -## R - -### Remote checksum - -远程校验和。指导入 TiDB 后所计算的表的[校验和](#checksum)。 - - - -## S - -### Scattering - -指随机再分配 [Region](/dev/glossary.md#regionpeerraft-group) 中 leader 和 peer 的操作。Scattering 确保导入的数据在 TiKV store 中均匀分布，这样可以降低 PD 调度的压力。 - -### Splitting - -指 TiKV Importer 在上传之前会将单个引擎文件拆分为若干小 [SST 文件](#sst-file)的操作。这是因为引擎文件通常很大（约为 100 GB），在 TiKV 中不适合视为单一的 [Region](/dev/glossary.md#regionpeerraft-group)。拆分的文件大小可通过 `import.region-split-size` 配置项更改。 - -### SST file - -Sorted string table file（排序字符串表文件）。SST 文件是一种在 RocksDB 中（因而也是 TiKV 中）键值对集合在本地的存储形式。 - -TiKV Importer 从关闭的[引擎](#engine)中生成 SST 文件。这些 SST 文件接着被上传、[ingest](#ingest) 到 TiKV store 中。 diff --git a/dev/reference/tools/tidb-lightning/overview.md b/dev/reference/tools/tidb-lightning/overview.md deleted file mode 100644 index d897139b4f3a..000000000000 --- a/dev/reference/tools/tidb-lightning/overview.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: TiDB Lightning 简介 -category: reference ---- - -# TiDB Lightning 简介 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量数据的备份恢复。目前，支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -## TiDB Lightning 整体架构 - -TiDB Lightning 主要包含两个部分： - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键值对（KV 对）发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，对 `tidb-lightning` 写入的键值对进行缓存、排序、切分操作并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -TiDB Lightning 整体工作原理如下： - -1. 在导数据之前，`tidb-lightning` 会自动将 TiKV 集群切换为“导入模式” (import mode)，优化写入效率并停止自动压缩。 - -2. `tidb-lightning` 会在目标数据库建立架构和表，并获取其元数据。 - -3. 每张表都会被分割为多个连续的**区块**，这样来自大表 (200 GB+) 的数据就可以用增量方式导入。 - -4. `tidb-lightning` 会通过 gRPC 让 `tikv-importer` 为每一个区块准备一个“引擎文件 (engine file)”来处理键值对。`tidb-lightning` 会并发读取 SQL dump，将数据源转换成与 TiDB 相同编码的键值对，然后发送到 `tikv-importer` 里对应的引擎文件。 - -5. 当一个引擎文件数据写入完毕时，`tikv-importer` 便开始对目标 TiKV 集群数据进行分裂和调度，然后导入数据到 TiKV 集群。 - - 引擎文件包含两种：**数据引擎**与**索引引擎**，各自又对应两种键值对：行数据和次级索引。通常行数据在数据源里是完全有序的，而次级索引是无序的。因此，数据引擎文件在对应区块写入完成后会被立即上传，而所有的索引引擎文件只有在整张表所有区块编码完成后才会执行导入。 - -6. 整张表相关联的所有引擎文件完成导入后，`tidb-lightning` 会对比本地数据源及下游集群的校验和 (checksum)，确保导入的数据无损，然后让 TiDB 分析 (`ANALYZE`) 这些新增的数据，以优化日后的操作。同时，`tidb-lightning` 调整 `AUTO_INCREMENT` 值防止之后新增数据时发生冲突。 - - 表的自增 ID 是通过行数的**上界**估计值得到的，与表的数据文件总大小成正比。因此，最后的自增 ID 通常比实际行数大得多。这属于正常现象，因为在 TiDB 中自增 ID [不一定是连续分配的](/dev/reference/mysql-compatibility.md#auto-increment-id)。 - -7. 在所有步骤完毕后，`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode)，此后 TiDB 集群可以正常对外提供服务。 - -TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似，使用 TiDB-backend 时，`tidb-lightning` 将数据转换为 `INSERT` 语句，然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md)。 diff --git a/dev/reference/tools/tidb-lightning/tidb-backend.md b/dev/reference/tools/tidb-lightning/tidb-backend.md deleted file mode 100644 index c846f33605c7..000000000000 --- a/dev/reference/tools/tidb-lightning/tidb-backend.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: TiDB Lightning TiDB-Backend -summary: 了解 TiDB Lightning TiDB-backend。 -category: reference ---- - -# TiDB Lightning TiDB-Backend - -TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前，TiDB Lightning 支持 Importer-backend（默认）和 TiDB-backend 两种后端，两者导入数据的区别如下： - -* **Importer-backend**：`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对，由 `tikv-importer` 对写入的键值对进行排序，然后把这些键值对 Ingest 到 TiKV 节点中。 - -* **TiDB-backend**：`tidb-lightning` 先将数据编码成 `INSERT` 语句，然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 - -| 后端 | Importer-backend | TiDB-backend | -|:---|:---|:---| -| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | -| 资源使用率 | 高 | 低 | -| 导入时是否满足 ACID | 否 | 是 | -| 目标表 | 必须为空 | 可以不为空 | - -## 部署 TiDB-backend - -使用 TiDB-backend 时，你无需部署 `tikv-importer`。与[标准部署过程](/dev/reference/tools/tidb-lightning/deployment.md)相比，部署 TiDB-backend 时有如下不同： - -* 可以跳过所有涉及 `tikv-importer` 的步骤。 -* 必须更改相应配置申明使用的是 TiDB-backend。 - -### 硬件需求 - -使用 TiDB-backend 时， TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此，即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下： - -* 16 逻辑核 CPU -* 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 -* 千兆网卡 - -### 使用 Ansible 部署 - -1. `inventory.ini` 文件中，`[importer_server]` 部分可以留空。 - - ```ini - ... - - [importer_server] - # keep empty - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置，`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 - - ```yaml - ... - tikv_importer: - backend: "tidb" # <-- 改成 “tidb” - ... - ``` - -3. 启动、部署集群。 - -4. 为 TiDB Lightning 挂载数据源。 - -5. 启动 `tidb-lightning`。 - -### 手动部署 - -手动部署时，你无需下载和配置 `tikv-importer`。 - -在运行 `tidb-lightning` 之前，在配置文件中加上如下几行： - -```toml -[tikv-importer] -backend = "tidb" -``` - -或者在用命令行启动 `tidb-lightning` 时，传入参数 `--backend tidb`。 - -## 冲突解决 - -TiDB-backend 支持导入到已填充的表（非空表）。但是，新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为： - -```toml -[tikv-importer] -backend = "tidb" -on-duplicate = "replace" # 或者 “error”、“ignore” -``` - -| 设置 | 冲突时默认行为 | 对应 SQL 语句 | -|:---|:---|:---| -| replace | 新数据替代旧数据 | `REPLACE INTO ...` | -| ignore | 保留旧数据，忽略新数据 | `INSERT IGNORE INTO ...` | -| error | 中止导入 | `INSERT INTO ...` | - -## 从 Loader 迁移到 TiDB Lightning TiDB-backend - -TiDB Lightning TiDB-backend 可以完全取代 [Loader](/dev/reference/tools/loader.md)。下表说明了如何将 [Loader](/dev/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/dev/reference/tools/tidb-lightning/config.md)中： - -
- - - - - - - - - -
LoaderTiDB Lightning
- -```toml -# 日志 -log-level = "info" -log-file = "loader.log" -# Prometheus -status-addr = ":8272" -# 线程数 -pool-size = 16 -``` - - - -```toml -[lightning] -# 日志 -level = "info" -file = "tidb-lightning.log" -# Prometheus -pprof-port = 8289 -# 并发度 (最好使用默认设置) -#region-concurrency = 16 -``` - -
- -```toml -# 断点数据库名 -checkpoint-schema = "tidb_loader" -``` - - - -```toml -[checkpoint] -# 断点存储 -enable = true -schema = "tidb_lightning_checkpoint" -# 断点默认存储在本地的文件系统，这样更高效。但你也可以 -# 选择将断点存储在目标数据库中，设置如下： -# driver = "mysql" -``` - -
- -```toml -``` - - - -```toml -[tikv-importer] -# 使用 TiDB-backend -backend = "tidb" -``` - -
- -```toml -# 数据源目录 -dir = "/data/export/" -``` - - - -```toml -[mydumper] -# 数据源目录 -data-source-dir = "/data/export" -``` - -
- -```toml -[db] -# TiDB 连接参数 -host = "127.0.0.1" -port = 4000 -user = "root" -password = "" -#sql-mode = "" -``` - - - -```toml -[tidb] -# TiDB 连接参数 -host = "127.0.0.1" -port = 4000 -status-port = 10080 # <- 必须有的参数 -user = "root" -password = "" -#sql-mode = "" -``` - -
diff --git a/dev/reference/tools/tidb-lightning/web.md b/dev/reference/tools/tidb-lightning/web.md deleted file mode 100644 index 0834577ed5e8..000000000000 --- a/dev/reference/tools/tidb-lightning/web.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: TiDB Lightning Web 界面 -summary: 了解 TiDB Lightning 的服务器模式——通过 Web 界面来控制 TiDB Lightning。 -category: reference ---- - -# TiDB Lightning Web 界面 - -TiDB Lightning 支持在网页上查看导入进度或执行一些简单任务管理，这就是 TiDB Lightning 的**服务器模式**。本文将介绍服务器模式下的 Web 界面和一些常见操作。 - -启用服务器模式的方式有如下几种： - -1. 在启动 `tidb-lightning` 时加上命令行参数 `--server-mode`。 - - ```sh - ./tidb-lightning --server-mode --status-addr :8289 - ``` - -2. 在配置文件中设置 `lightning.server-mode`。 - - ```toml - [lightning] - server-mode = true - status-addr = ':8289' - ``` - -TiDB Lightning 启动后，可以访问 `http://127.0.0.1:8289` 来管理程序（实际的 URL 取决于你的 `status-addr` 设置）。 - -服务器模式下，TiDB Lightning 不会立即开始运行，而是通过用户在 web 页面提交（多个）**任务**来导入数据。 - -## TiDB Lightning Web 首页 - -![TiDB Lightning Web 首页](/media/lightning-web-frontpage.png) - -标题栏上图标所对应的功能，从左到右依次为： - -| 图标 | 功能 | -|:----|:----| -| "TiDB Lightning" | 点击即返回首页 | -| ⚠ | 显示**前一个**任务的所有错误信息 | -| ⓘ | 列出当前及队列中的任务，可能会出现一个标记提示队列中任务的数量 | -| + | 提交单个任务 | -| ⏸/▶ | 暂停/继续当前操作 | -| ⟳ | 设置网页自动刷新 | - -标题栏下方的三个面板显示了不同状态下的所有表： - -* Active：当前正在导入这些表 -* Completed：这些表导入成功或失败 -* Pending：这些表还没有被处理 - -每个面板都包含用于描述表状态的卡片。 - -## 提交任务 - -点击标题栏的 **+** 图标提交任务。 - -![提交任务对话框](/media/lightning-web-submit.png) - -任务 (task) 为 TOML 格式的文件，具体参考 [TiDB Lightning 任务配置](/dev/reference/tools/tidb-lightning/config.md#tidb-lightning-任务配置参数)。你也可以点击 **UPLOAD** 上传一个本地的 TOML 文件。 - -点击 **SUBMIT** 运行任务。如果当前有任务正在运行，新增任务会加入队列并在当前任务结束后执行。 - -## 查看导入进度 - -点击首页表格卡片上的 **>** 图标，查看表格导入的详细进度。 - -![表格导入进度](/media/lightning-web-table.png) - -该页显示每张表的引擎文件的导入过程。 - -点击标题栏上的 **TiDB Lightning** 返回首页。 - -## 管理任务 - -单击标题栏上的 **ⓘ** 图标来管理当前及队列中的任务。 - -![任务管理页面](/media/lightning-web-queue.png) - -每个任务都是依据提交时间来标记。点击该任务将显示 JSON 格式的配置文件。 - -点击任务上的 **⋮** 可以对该任务进行管理。你可以立即停止任务，或重新排序队列中的任务。 diff --git a/dev/reference/tools/user-guide.md b/dev/reference/tools/user-guide.md deleted file mode 100644 index 47b53f962d59..000000000000 --- a/dev/reference/tools/user-guide.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: TiDB 生态工具使用指南 -category: reference -aliases: ['/docs-cn/dev/how-to/migrate/from-mysql/', '/docs-cn/dev/how-to/migrate/incrementally-from-mysql/', '/docs-cn/dev/how-to/migrate/overview/', '/docs-cn/dev/reference/tools/use-guide/'] ---- - -# TiDB 生态工具使用指南 - -目前 TiDB 生态工具较多，有些工具之间有功能重叠，也有些属于版本迭代关系。本文档将对各个工具进行介绍，说明各个工具之间的关系，并且说明各个版本、场景下应该使用哪些工具。 - -## TiDB 生态工具概览 - -TiDB 生态工具可以分为几种： - -- 数据导入类，包括全量导入工具、备份和恢复工具、增量导入工具等 -- 数据导出类，包括全量导出工具、增量导出工具等 - -下面将分别介绍这两类工具。 - -### 数据导入类 - -#### 全量导入工具 Loader（停止维护，不推荐使用） - -[Loader](/dev/reference/tools/loader.md) 是一款轻量级的全量数据导入工具，数据以 SQL 的形式导入到 TiDB 中。目前这个工具正在逐步被 [TiDB Lightning](#全量导入工具-tidb-lightning) 替换掉，参见 [TiDB Lightning TiDB-backend 文档](/dev/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。 - -以下是 Loader 的一些基本信息： - -- Loader 的输入：Mydumper 输出的文件 -- Loader 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：[备份与恢复](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md) - -#### 全量导入工具 TiDB Lightning - -[TiDB Lightning](/dev/reference/tools/tidb-lightning/overview.md) 是将全量数据快速导入到一个新的 TiDB 集群的工具。 - -注意用 TiDB Lightning 导入数据到 TiDB 的时候，有两种模式： - -- 默认模式：`tikv-importer` 为后端，这种模式下导入数据过程中集群无法提供正常的服务，用于导入大量的数据（TB 级别）。 -- 第二种模式：`TiDB` 为后端（相当于 Loader 的功能），相对默认模式导入速度较慢，但是可以在线导入。 - -以下是 TiDB Lightning 的一些基本信息： - -- Lightning 的输入 - - Mydumper 输出文件 - - CSV 格式文件 -- 适用 TiDB 版本：v2.1 及以上 -- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](/dev/tidb-in-kubernetes/maintain/lightning.md) - -#### 备份和恢复工具 BR - -[BR](/dev/reference/tools/br/br.md) 是 TiDB 进行分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 Mydumper 和 Loader，BR 更适合大数据量的场景，有更高效的备份和恢复效率。 - -以下是 BR 的一些基本信息： - -- [备份输出和恢复输入的文件类型](/dev/reference/tools/br/br.md#备份文件类型)：SST + `backupmeta` 文件 -- 适用 TiDB 版本：v3.1 及 v4.0 -- Kubernetes 支持：已支持，文档撰写中 - -#### 增量导入工具 Syncer（已停止维护，不推荐使用） - -[Syncer](/dev/reference/tools/syncer.md) 是将 MySQL/MariaDB 增量 binlog 数据实时复制导入到 TiDB 的工具。目前推荐使用 [TiDB Data Migration](#增量导入工具-tidb-data-migration) 替换该工具。 - -以下是 Syncer 的一些基本信息： - -- Syncer 的输入：MySQL/MariaDB 的 binlog -- Syncer 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：不支持 - -#### 增量导入工具 TiDB Data Migration - -[TiDB Data Migration (DM)](/dev/reference/tools/data-migration/overview.md) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的同步。 - -以下是 DM 的一些基本信息： - -- DM 的输入：MySQL/MariaDB 的全量数据以及 binlog -- DM 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：开发中 - -### 数据导出类 - -#### 全量导出工具 Mydumper - -[Mydumper](/dev/reference/tools/mydumper.md) 用于对 MySQL/TiDB 进行全量逻辑备份。 - -以下是 Mydumper 的一些基本信息： - -- Mydumper 的输入：MySQL/TiDB 集群 -- Mydumper 的输出：SQL 文件 -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：[备份与恢复](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md) - -#### 增量导出工具 TiDB Binlog - -[TiDB Binlog](/dev/reference/tidb-binlog/overview.md) 是收集 TiDB 的 binlog，并提供准实时同步和备份的工具。 - -以下是 TiDB Binlog 的一些基本信息： - -- TiDB Binlog 的输入：TiDB 集群 -- TiDB Binlog 的输出：MySQL、TiDB、Kafka 或者增量备份文件 -- 适用 TiDB 版本：v2.1 及以上 -- Kubernetes 支持：[TiDB Binlog 运维文档](/dev/tidb-in-kubernetes/maintain/tidb-binlog.md)，[Kubernetes 上的 TiDB Binlog Drainer 配置](/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - -## 工具演进路线 - -下面简单的介绍一下 TiDB 生态工具集的演进，方便大家了解工具之间的关系。 - -### TiDB 备份与恢复 - -Mydumper、Loader -> BR： - -Mydumper 和 Loader 都是在逻辑层面进行备份和恢复，效率较低；BR 使用 TiDB 的特性进行备份和恢复，适合数据量比较大的场景，备份效率大大提升。 - -### TiDB 全量恢复 - -Loader -> TiDB Lightning： - -Loader 使用 SQL 的方式进行全量数据恢复，效率较低。TiDB Lightning 将数据直接导入 TiKV，大大提升了全量数据恢复的效率，适合将大量数据（TB 级别以上数据）快速导入到一个全新的 TiDB 集群中；且 TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/dev/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，支持在线导入数据。 - -### MySQL 数据迁移 - -- Mydumper、Loader、Syncer -> DM： - - 使用 Mydumper、Loader、Syncer 将 MySQL 数据迁移到 TiDB，迁移过程比较繁琐。DM 提供了一体化的数据迁移方案，提高了易用性，而且 DM 还支持分库分表的合并。 - -- Loader -> TiDB Lightning： - - TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/dev/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，由 TiDB Lightning 统一提供全量数据恢复功能。 - -## 数据迁移解决方案 - -针对 TiDB 的 2.1，3.0 以及 3.1 版本，下面给出典型业务场景下的数据迁移方案。 - -### TiDB 3.0 全链路数据迁移方案 - -#### MySQL 数据迁移到 TiDB - -如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： - -1. 使用 Mydumper 导出 MySQL 全量数据 -2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 -3. 使用 DM 同步 MySQL 增量数据到 TiDB - -如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 - -#### TiDB 集群数据的同步 - -使用 TiDB Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 - -#### TiDB 集群数据的全量备份及恢复 - -推荐步骤： - -1. 使用 Mydumper 进行全量数据的备份 -2. 使用 TiDB Lightning 将全量数据恢复到 TiDB/MySQL - -### TiDB 3.1 全链路数据迁移方案 - -#### MySQL 数据迁移到 TiDB - -如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： - -1. 使用 Mydumper 导出 MySQL 全量数据 -2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 -3. 使用 DM 同步 MySQL 增量数据到 TiDB - -如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 - -#### TiDB 集群数据的同步 - -使用 TiDB-Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 - -#### TiDB 集群数据的全量备份及恢复 - -- 恢复到 TiDB - - - 使用 BR 进行全量数据的备份 - - 使用 BR 进行全量数据的恢复 - -- 恢复到 MySQL - - - 使用 Mydumper 进行全量数据的备份 - - 使用 TiDB Lightning 进行全量数据的恢复 diff --git a/dev/reference/transactions/overview.md b/dev/reference/transactions/overview.md deleted file mode 100644 index f0b40f2687b0..000000000000 --- a/dev/reference/transactions/overview.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB 事务概览 -summary: 了解 TiDB 中的事务。 -category: reference ---- - -# TiDB 事务概览 - -TiDB 支持完整的分布式事务，提供[乐观事务](/dev/reference/transactions/transaction-optimistic.md)与[悲观事务](/dev/reference/transactions/transaction-pessimistic.md)（TiDB 3.0 中引入）两种事务模型。本文主要介绍涉及到事务的语句、显式/隐式事务、事务的隔离级别和惰性检查，以及事务大小的限制。 - -常用的变量包括 [`autocommit`](#自动提交)、[`tidb_disable_txn_auto_retry`](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_disable_txn_auto_retry) 以及 [`tidb_retry_limit`](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_retry_limit)。 - -## 常用事务语句 - -### `BEGIN` 和 `START TRANSACTION` - -语法： - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION WITH CONSISTENT SNAPSHOT; -``` - -以上三条语句都用于开启事务，效果相同。执行开启事务语句可以显式地开启一个新的事务。如果执行以上语句时，当前 Session 正处于一个事务的中间过程，那么系统会先自动提交当前事务，再开启一个新的事务。 - -### `COMMIT` - -语法： - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -该语句用于提交当前的事务，包括从 `[BEGIN|START TRANSACTION]` 到 `COMMIT` 之间的所有修改。 - -### `ROLLBACK` - -语法： - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -该语句用于回滚当前事务，撤销从 `[BEGIN|START TRANSACTION]` 到 `ROLLBACK` 之间的所有修改。 - -## 自动提交 - -语法： - -{{< copyable "sql" >}} - -```sql -SET autocommit = {0 | 1} -``` - -当 `autocommit = 1` 时（默认），当前的 Session 为自动提交状态，即每条语句运行后，TiDB 会自动将修改提交到数据库中。设置 `autocommit = 0` 时更改当前 Session 更改为非自动提交状态，通过执行 `COMMIT` 语句来手动提交事务。 - -> **注意：** -> -> 某些语句执行后会导致隐式提交。例如，执行 `[BEGIN|START TRANCATION]` 语句时，TiDB 会试图提交上一个事务，并开启一个新的事务。详情参见 [implicit commit](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html)。 - -另外，`autocommit` 也是一个系统变量，你可以通过变量赋值语句修改当前 Session 或 Global 的值。 - -{{< copyable "sql" >}} - -```sql -SET @@SESSION.autocommit = {0 | 1}; -``` - -{{< copyable "sql" >}} - -```sql -SET @@GLOBAL.autocommit = {0 | 1}; -``` - -## 显式事务和隐式事务 - -TiDB 可以显式地使用事务（通过 `[BEGIN|START TRANSACTION]`/`COMMIT` 语句定义事务的开始和结束) 或者隐式地使用事务 (`SET autocommit = 1`)。 - -在自动提交状态下，使用 `[BEGIN|START TRANSACTION]` 语句会显式地开启一个事务，同时也会禁用自动提交，使隐式事务变成显式事务。直到执行 `COMMIT` 或 `ROLLBACK` 语句时才会恢复到此前默认的自动提交状态。 - -对于 DDL 语句，会自动提交并且不能回滚。如果运行 DDL 的时候，正在一个事务的中间过程中，会先自动提交当前事务，再执行 DDL。 - -## 事务隔离级别 - -TiDB **只支持** `SNAPSHOT ISOLATION`，可以通过下面的语句将当前 Session 的隔离级别设置为 `READ COMMITTED`，这只是语法上的兼容，事务依旧是以 `SNAPSHOT ISOLATION` 来执行。 - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -## 惰性检查 - -TiDB 中，对于普通的 `INSERT` 语句写入的值，会进行惰性检查。惰性检查的含义是，不在 `INSERT` 语句执行时进行唯一约束的检查，而在事务提交时进行唯一约束的检查。 - -举例： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE T (I INT KEY); -INSERT INTO T VALUES (1); -BEGIN; -INSERT INTO T VALUES (1); -- MySQL 返回错误；TiDB 返回成功 -INSERT INTO T VALUES (2); -COMMIT; -- MySQL 提交成功；TiDB 返回错误，事务回滚 -SELECT * FROM T; -- MySQL 返回 1 2；TiDB 返回 1 -``` - -惰性检查的意义在于，如果对事务中每个 `INSERT` 语句都立刻进行唯一性约束检查，将造成很高的网络开销。而在提交时进行一次批量检查，将会大幅提升性能。 - -> **注意：** -> -> 本优化仅对普通的 `INSERT` 语句生效，对 `INSERT IGNORE` 和 `INSERT ON DUPLICATE KEY UPDATE` 不会生效。 - -## 语句回滚 - -TiDB 支持语句执行的原子性回滚。在事务内部执行一个语句，遇到错误时，该语句整体不会生效。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -commit; -``` - -上面的例子里面，第二条语句执行失败，但第一和第三条语句仍然能正常提交。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -rollback; -``` - -以上例子中，第二条语句执行失败。由于调用了 `ROLLBACK`，因此事务不会将任何数据写入数据库。 - -## 事务大小 - -对于 TiDB 事务而言，事务太大或太小，都会影响事务的执行效率。 - -### 小事务 - -以如下 query 为例，当 `autocommit = 1` 时，下面三条语句各为一个事务： - -{{< copyable "sql" >}} - -```sql -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -``` - -此时每一条语句都需要经过两阶段提交，频繁的网络交互致使延迟率高。为提升事务执行效率，可以选择使用显式事务，即在一个事务内执行三条语句。 - -优化后版本： - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -COMMIT; -``` - -同理，执行 `INSERT` 语句时，建议使用显式事务。 - -> **注意：** -> -> 由于 TiDB 中的资源是分布式的，TiDB 中单线程 workload 可能不会很好地利用分布式资源，因此性能相比于单实例部署的 MySQL 较低。这与 TiDB 中的事务延迟较高的情況类似。 - -### 大事务 - -由于 TiDB 两阶段提交的要求，修改数据的单个事务过大时会存在以下问题： - -* 客户端在提交之前，数据都写在内存中，而数据量过多时易导致 OOM (Out of Memory) 错误。 -* 在第一阶段写入数据耗时增加，与其他事务出现写冲突的概率会指数级增长。 -* 最终导致事务完成提交的耗时增加。 - -因此，TiDB 对事务做了一些限制： - -* 单个事务包含的 SQL 语句不超过 5000 条（默认） -* 每个键值对不超过 6 MB - -为了使性能达到最优，建议每 100～500 行写入一个事务。 - -TiDB 设置了键值对的总大小不超过 100 MB 默认限制，可以通过配置文件中的配置项 `txn-total-size-limit` 进行修改，最大支持到 10GB。实际的单个事务大小限制还取决于用户的内存，执行大事务时 TiDB 进程的内存消耗大约是事务大小 6 倍以上。 \ No newline at end of file diff --git a/dev/reference/transactions/transaction-isolation.md b/dev/reference/transactions/transaction-isolation.md deleted file mode 100644 index 2c64a949fd4b..000000000000 --- a/dev/reference/transactions/transaction-isolation.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: TiDB 事务隔离级别 -summary: 了解 TiDB 事务的隔离级别。 -category: reference ---- - -# TiDB 事务隔离级别 - -事务隔离级别是数据库事务处理的基础，[ACID](/dev/glossary.md#acid) 中的 “I”，即 Isolation，指的就是事务的隔离性。 - -SQL-92 标准定义了 4 种隔离级别：读未提交 (READ UNCOMMITTED)、读已提交 (READ COMMITTED)、可重复读 (REPEATABLE READ)、串行化 (SERIALIZABLE)。详见下表： - -| Isolation Level | Dirty Write | Dirty Read | Fuzzy Read | Phantom | -| ---------------- | ------------ | ------------ | ------------ | ------------ | -| READ UNCOMMITTED | Not Possible | Possible | Possible | Possible | -| READ COMMITTED | Not Possible | Not possible | Possible | Possible | -| REPEATABLE READ | Not Possible | Not possible | Not possible | Possible | -| SERIALIZABLE | Not Possible | Not possible | Not possible | Not possible | - -TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](#与-ansi-可重复读隔离级别的区别)和 [MySQL 可重复读隔离级别](#与-mysql-可重复读隔离级别的区别)。 - -> **注意：** -> -> 在 TiDB v3.0 中，事务的自动重试功能默认为禁用状态。关于该项功能对隔离级别的影响以及如何开启该项功能，请参考[事务重试](/dev/reference/transactions/transaction-optimistic.md#重试机制)。 - -## 可重复读隔离级别 (Repeatable Read) - -当事务隔离级别为可重复读时，只能读到该事务启动时已经提交的其他事务修改的数据，未提交的数据或在事务启动后其他事务提交的数据是不可见的。对于本事务而言，事务语句可以看到之前的语句做出的修改。 - -对于运行于不同节点的事务而言，不同事务启动和提交的顺序取决于从 PD 获取时间戳的顺序。 - -处于可重复读隔离级别的事务不能并发的更新同一行，当时事务提交时发现该行在该事务启动后，已经被另一个已提交的事务更新过，那么该事务会回滚并启动自动重试。示例如下： - -```sql -create table t1(id int); -insert into t1 values(0); - -start transaction; | start transaction; -select * from t1; | select * from t1; -update t1 set id=id+1; | update t1 set id=id+1; -commit; | - | commit; -- 事务提交失败，回滚 -``` - -### 与 ANSI 可重复读隔离级别的区别 - -尽管名称是可重复读隔离级别，但是 TiDB 中可重复读隔离级别和 ANSI 可重复隔离级别是不同的。按照 [A Critique of ANSI SQL Isolation Levels](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf) 论文中的标准，TiDB 实现的是论文中的快照隔离级别。该隔离级别不会出现狭义上的幻读 (A3)，但不会阻止广义上的幻读 (P3)，同时，SI 还会出现写偏斜，而 ANSI 可重复读隔离级别不会出现写偏斜，会出现幻读。 - -### 与 MySQL 可重复读隔离级别的区别 - -MySQL 可重复读隔离级别在更新时并不检验当前版本是否可见，也就是说，即使该行在事务启动后被更新过，同样可以继续更新。这种情况在 TiDB 会导致事务回滚，导致事务最终失败，而 MySQL 是可以更新成功的。MySQL 的可重复读隔离级别并非 Snapshot 隔离级别，MySQL 可重复读隔离级别的一致性要弱于 Snapshot 隔离级别，也弱于 TiDB 的可重复读隔离级别。 - -## 读已提交隔离级别 (Read Committed) - -TiDB 仅在[悲观事务模式](/dev/reference/transactions/transaction-pessimistic.md)下支持读已提交隔离级别。在乐观事务模式下设置事务隔离级别为读已提交将不会生效，事务将仍旧使用可重复读隔离级别。 - -由于历史原因，当前主流数据库的读已提交隔离级别本质上都是 Oracle 定义的一致性读隔离级别。TiDB 为了适应这一历史原因，悲观事务中的读已提交隔离级别的实质行为也是一致性读。 - -### 与 MySQL 读已提交隔离级别的区别 - -MySQL 的读已提交隔离级别大部分符合一致性读特性，但其中存在某些特例，如半一致性读 ([semi-consistent read](https://dev.mysql.com/doc/refman/8.0/en/innodb-transaction-isolation-levels.html))，TiDB 没有兼容这个特殊行为。 - -## 更多阅读 - -- [TiKV 的 MVCC (Multi-Version Concurrency Control) 机制](https://pingcap.com/blog-cn/mvcc-in-tikv/) \ No newline at end of file diff --git a/dev/reference/transactions/transaction-optimistic.md b/dev/reference/transactions/transaction-optimistic.md deleted file mode 100644 index 19c146e5ec0d..000000000000 --- a/dev/reference/transactions/transaction-optimistic.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: TiDB 乐观事务模型 -summary: 了解 TiDB 的乐观事务模型。 -category: reference -aliases: ['/docs-cn/dev/reference/transactions/transaction-model/'] ---- - -# TiDB 乐观事务模型 - -本文介绍 TiDB 乐观事务的原理，以及相关特性。本文假定你对 [TiDB 的整体架构](/dev/architecture.md#tidb-整体架构)、[Percolator](https://www.usenix.org/legacy/event/osdi10/tech/full_papers/Peng.pdf) 事务模型以及事务的 [ACID 特性](/dev/glossary.md#acid)都有一定了解。 - -TiDB 默认使用乐观事务模型，不会出现读写冲突，所有的读操作都不会被写操作阻塞。对于写写冲突，只有在客户端执行 `COMMIT` 时，才会触发两阶段提交并检测是否存在写写冲突。 - -> **注意：** -> -> 自 v3.0.8 开始，TiDB 默认使用[悲观事务模型](/dev/reference/transactions/transaction-pessimistic.md)。但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 - -## 乐观事务原理 - -TiDB 中事务使用两阶段提交，流程如下： - -![TiDB 中的两阶段提交](/media/2pc-in-tidb.png) - -1. 客户端开始一个事务。 - - TiDB 从 PD 获取一个全局唯一递增的版本号作为当前事务的开始版本号，这里定义为该事务的 `start_ts` 版本。 - -2. 客户端发起读请求。 - - 1. TiDB 从 PD 获取数据路由信息，即数据具体存在哪个 TiKV 节点上。 - 2. TiDB 从 TiKV 获取 `start_ts` 版本下对应的数据信息。 - -3. 客户端发起写请求。 - - TiDB 校验写入数据是否符合一致性约束（如数据类型是否正确、是否符合唯一索引约束等）。**校验通过的数据将存放在内存里。** - -4. 客户端发起 commit。 - -5. TiDB 开始两阶段提交，保证分布式事务的原子性，让数据真正落盘。 - - 1. TiDB 从当前要写入的数据中选择一个 Key 作为当前事务的 Primary Key。 - 2. TiDB 从 PD 获取所有数据的写入路由信息，并将所有的 Key 按照所有的路由进行分类。 - 3. TiDB 并发地向所有涉及的 TiKV 发起 prewrite 请求。TiKV 收到 prewrite 数据后，检查数据版本信息是否存在冲突或已过期。符合条件的数据会被加锁。 - 4. TiDB 收到所有 prewrite 响应且所有 prewrite 都成功。 - 5. TiDB 向 PD 获取第二个全局唯一递增版本号，定义为本次事务的 `commit_ts`。 - 6. TiDB 向 Primary Key 所在 TiKV 发起第二阶段提交。TiKV 收到 commit 操作后，检查数据合法性，清理 prewrite 阶段留下的锁。 - 7. TiDB 收到两阶段提交成功的信息。 - -6. TiDB 向客户端返回事务提交成功的信息。 - -7. TiDB 异步清理本次事务遗留的锁信息。 - -## 优缺点分析 - -通过分析 TiDB 中事务的处理流程，可以发现 TiDB 事务有如下优点： - -* 实现原理简单，易于理解。 -* 基于单实例事务实现了跨节点事务。 -* 锁管理实现了去中心化。 - -但 TiDB 事务也存在以下缺点： - -* 两阶段提交使网络交互增多。 -* 需要一个中心化的版本管理服务。 -* 事务数据量过大时易导致内存暴涨。 - -实际应用中，你可以[根据事务的大小进行针对性处理](/dev/reference/transactions/overview.md#事务大小)，以提高事务的执行效率。 - -## 事务的重试 - -使用乐观事务模型时，在高冲突率的场景中，事务很容易提交失败。而 MySQL 内部使用的是悲观事务模型，在执行 SQL 语句的过程中进行冲突检测，所以提交时很难出现异常。为了兼容 MySQL 的悲观事务行为，TiDB 提供了重试机制。 - -### 重试机制 - -当事务提交后，如果发现冲突，TiDB 内部重新执行包含写操作的 SQL 语句。你可以通过设置 `tidb_disable_txn_auto_retry = off` 开启自动重试，并通过 `tidb_retry_limit` 设置重试次数： - -```sql -# 设置是否禁用自动重试，默认为 “on”，即不重试。 -tidb_disable_txn_auto_retry = off -# 控制重试次数，默认为 “10”。只有自动重试启用时该参数才会生效。 -# 当 “tidb_retry_limit= 0” 时，也会禁用自动重试。 -tidb_retry_limit = 10 -``` - -你也可以修改当前 Session 或 Global 的值： - -- Session 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@tidb_retry_limit = 10; - ``` - -- Global 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_retry_limit = 10; - ``` - -> **注意：** -> -> `tidb_retry_limit` 变量决定了事务重试的最大次数。当它被设置为 0 时，所有事务都不会自动重试，包括自动提交的单语句隐式事务。这是彻底禁用 TiDB 中自动重试机制的方法。禁用自动重试后，所有冲突的事务都会以最快的方式上报失败信息 (`try again later`) 给应用层。 - -### 重试的局限性 - -TiDB 默认不进行事务重试，因为重试事务可能会导致更新丢失，从而破坏[可重复读的隔离级别](/dev/reference/transactions/transaction-isolation.md)。 - -事务重试的局限性与其原理有关。事务重试可概括为以下三个步骤： - -1. 重新获取 `start_ts`。 -2. 重新执行包含写操作的 SQL 语句。 -3. 再次进行两阶段提交。 - -第二步中，重试时仅重新执行包含写操作的 SQL 语句，并不涉及读操作的 SQL 语句。但是当前事务中读到数据的时间与事务真正开始的时间发生了变化，写入的版本变成了重试时获取的 `start_ts` 而非事务一开始时获取的 `start_ts`。因此，当事务中存在依赖查询结果来更新的语句时，重试将无法保证事务原本可重复读的隔离级别，最终可能导致结果与预期出现不一致。 - -如果业务可以容忍事务重试导致的异常，或并不关注事务是否以可重复读的隔离级别来执行，则可以开启自动重试。 - -## 冲突检测 - -乐观事务下，检测底层数据是否存在写写冲突是一个很重要的操作。具体而言，TiKV 在 prewrite 阶段就需要读取数据进行检测。为了优化这一块性能，TiDB 集群会在内存里面进行一次冲突预检测。 - -作为一个分布式系统，TiDB 在内存中的冲突检测主要在两个模块进行： - -- TiDB 层。如果发现 TiDB 实例本身就存在写写冲突，那么第一个写入发出后，后面的写入已经清楚地知道自己冲突了，无需再往下层 TiKV 发送请求去检测冲突。 -- TiKV 层。主要发生在 prewrite 阶段。因为 TiDB 集群是一个分布式系统，TiDB 实例本身无状态，实例之间无法感知到彼此的存在，也就无法确认自己的写入与别的 TiDB 实例是否存在冲突，所以会在 TiKV 这一层检测具体的数据是否有冲突。 - -其中 TiDB 层的冲突检测可以根据场景需要选择打开或关闭，具体配置项如下： - -```toml -# 事务内存锁相关配置，当本地事务冲突比较多时建议开启。 -[txn-local-latches] -# 是否开启内存锁，默认为 false，即不开启。 -enabled = false -# Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。 -# 每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据）， -# 设置过小会导致变慢，性能下降。（默认为 2048000） -capacity = 2048000 -``` - -配置项 `capacity` 主要影响到冲突判断的正确性。在实现冲突检测时，不可能把所有的 Key 都存到内存里，所以真正存下来的是每个 Key 的 Hash 值。有 Hash 算法就有碰撞也就是误判的概率，这里可以通过配置 `capacity` 来控制 Hash 取模的值： - -* `capacity` 值越小，占用内存小，误判概率越大。 -* `capacity` 值越大，占用内存大，误判概率越小。 - -实际应用时，如果业务场景能够预判断写入不存在冲突（如导入数据操作），建议关闭冲突检测。 - -相应地，在 TiKV 层检测内存中是否存在冲突也有类似的机制。不同的是，TiKV 层的检测会更严格且不允许关闭，仅支持对 Hash 取模值进行配置： - -```toml -# scheduler 内置一个内存锁机制，防止同时对一个 Key 进行操作。 -# 每个 Key hash 到不同的 slot。（默认为 2048000） -scheduler-concurrency = 2048000 -``` - -此外，TiKV 支持监控等待 latch 的时间： - -![Scheduler latch wait duration](/media/optimistic-transaction-metric.png) - -当 `Scheduler latch wait duration` 的值特别高时，说明大量时间消耗在等待锁的请求上。如果不存在底层写入慢的问题，基本上可以判断该段时间内冲突比较多。 - -## 更多阅读 - -- [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/) \ No newline at end of file diff --git a/dev/releases/21rc5.md b/dev/releases/21rc5.md deleted file mode 100644 index a886038bd8bc..000000000000 --- a/dev/releases/21rc5.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: TiDB 2.1 RC5 Release Notes -category: Releases ---- - - - -# TiDB 2.1 RC5 Release Notes - -2018 年 11 月 12 日，TiDB 发布 2.1 RC5 版。相比 2.1 RC4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复 `IndexReader` 在某些情况下读取的 handle 不正确的问题 [#8132](https://github.com/pingcap/tidb/pull/8132) - - 修复 `IndexScan Prepared` 语句在使用 `Plan Cache` 的时候的问题 [#8055](https://github.com/pingcap/tidb/pull/8055) - - 修复 `Union` 语句结果不稳定的问题 [#8165](https://github.com/pingcap/tidb/pull/8165) -+ 执行器 - - 提升 TiDB 插入和更新宽表的性能 [#8024](https://github.com/pingcap/tidb/pull/8024) - - 内建函数 `Truncate` 支持 unsigned `int` 参数 [#8068](https://github.com/pingcap/tidb/pull/8068) - - 修复转换 JSON 数据到 decimal 类型出错的问题 [#8109](https://github.com/pingcap/tidb/pull/8109) - - 修复 float 类型在 `Update` 时出错的问题 [#8170](https://github.com/pingcap/tidb/pull/8170) -+ 统计信息 - - 修复点查在某些情况下，统计信息出现错误的问题 [#8035](https://github.com/pingcap/tidb/pull/8035) - - 修复统计信息某些情况下在 primary key 的选择率的问题 [#8149](https://github.com/pingcap/tidb/pull/8149) - - 修复被删除的表的统计信息长时间没有清理的问题 [#8182](https://github.com/pingcap/tidb/pull/8182) -+ Server - + 提升日志的可读性，完善日志信息 - - [#8063](https://github.com/pingcap/tidb/pull/8063) - - [#8053](https://github.com/pingcap/tidb/pull/8053) - - [#8224](https://github.com/pingcap/tidb/pull/8224) - - 修复获取 `infoschema.profiling` 表数据出错的问题 [#8096](https://github.com/pingcap/tidb/pull/8096) - - 替换 unix socket，使用 pumps client 来写 binlog [#8098](https://github.com/pingcap/tidb/pull/8098) - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 [#8094](https://github.com/pingcap/tidb/pull/8094) - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 [#8200](https://github.com/pingcap/tidb/pull/8200) - - 增加环境变量 `tidb_opt_write_row_id` 来控制是否允许写入 `_tidb_rowid` [#8218](https://github.com/pingcap/tidb/pull/8218) - - ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8081](https://github.com/pingcap/tidb/pull/8081)，[#8247](https://github.com/pingcap/tidb/pull/8247) -+ DDL - - 修复在事务中某些情况下执行 DDL 语句出错的问题 [#8056](https://github.com/pingcap/tidb/pull/8056) - - 修复 partition 分区表执行 `truncate table` 没有生效的问题 [#8103](https://github.com/pingcap/tidb/pull/8103) - - 修复某些情况下 DDL 操作在被 cancel 之后没有正确回滚的问题 [#8057](https://github.com/pingcap/tidb/pull/8057) - - 增加命令 `admin show next_row_id`，返回下一个可用的行 ID [#8268](https://github.com/pingcap/tidb/pull/8268) - -## PD - -+ 修复 `pd-ctl` 读取 Region key 的相关问题 - - [#1298](https://github.com/pingcap/pd/pull/1298) - - [#1299](https://github.com/pingcap/pd/pull/1299) - - [#1308](https://github.com/pingcap/pd/pull/1308) - -- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -- 修复 PD join 失败后无法重新 join 的问题 [#1279](https://github.com/pingcap/pd/pull/1279) -- 修复某些情况下 watch leader 会丢失事件的问题 [#1317](https://github.com/pingcap/pd/pull/1317) - -## TiKV - -- 优化 `WriteConflict` 报错信息 [#3750](https://github.com/tikv/tikv/pull/3750) -- 增加 panic 标记文件 [#3746](https://github.com/tikv/tikv/pull/3746) -- 降级 grpcio，避免新版本 gRPC 导致的 segment fault 问题 [#3650](https://github.com/tikv/tikv/pull/3650) -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) - -## Tools - -- TiDB 支持 TiDB Binlog cluster，不兼容旧版本 TiDB Binlog [#8093](https://github.com/pingcap/tidb/pull/8093)，[使用文档](/dev/reference/tidb-binlog/overview.md) diff --git a/dev/releases/3.0.8.md b/dev/releases/3.0.8.md deleted file mode 100644 index 25706239c46d..000000000000 --- a/dev/releases/3.0.8.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: TiDB 3.0.8 Release Notes -category: Releases ---- - -# TiDB 3.0.8 Release Notes - -发版日期：2019 年 12 月 31 日 - -TiDB 版本：3.0.8 - -TiDB Ansible 版本：3.0.8 - -## TiDB - -+ SQL 优化器 - - 修复 SQL Binding 因为 cache 更新不及时，导致绑定计划错误的问题 [#13891](https://github.com/pingcap/tidb/pull/13891) - - 修复当 SQL 包含符号列表（类似于 "?, ?, ?" 这样的占位符）时，SQL Binding 可能失效的问题 [#14004](https://github.com/pingcap/tidb/pull/14004) - - 修复 SQL Binding 由于原 SQL 以 `;` 结尾而不能创建/删除的问题 [#14113](https://github.com/pingcap/tidb/pull/14113) - - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14133](https://github.com/pingcap/tidb/pull/14133) - - 移除 `minAutoAnalyzeRatio` 约束使自动 analyze 更及时 [#14015](https://github.com/pingcap/tidb/pull/14015) -+ SQL 执行引擎 - - 修复 `INSERT/REPLACE/UPDATE ... SET ... = DEFAULT` 语法会报错的问题，修复 `DEFAULT` 表达式与虚拟生成列配合使用会报错的问题 [#13682](https://github.com/pingcap/tidb/pull/13682) - - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14011](https://github.com/pingcap/tidb/pull/14011) - - 修复 `HashAgg` Executor 并发值未被正确初始化，导致聚合操作执行在一些情况下效率低的问题 [#13811](https://github.com/pingcap/tidb/pull/13811) - - 修复 group by item 被括号包含时执行报错的问题 [#13658](https://github.com/pingcap/tidb/pull/13658) - - 修复 TiDB 没有正确计算 group by item，导致某些情况下 OUTER JOIN 执行会报错的问题 [#14014](https://github.com/pingcap/tidb/pull/14014) - - 修复向 Range 分区表写入超过 Range 外的数据时，报错信息不准确的问题 [#14107](https://github.com/pingcap/tidb/pull/14107) - - 鉴于 MySQL 8 即将废弃 `PadCharToFullLength`，revert PR [#10124](https://github.com/pingcap/tidb/pull/10124) 并撤销 `PadCharToFullLength` 的效果，以避免一些特殊情况下查询结果不符合预期 [#14157](https://github.com/pingcap/tidb/pull/14157) - - 修复 `ExplainExec` 中没有保证 `close()` 的调用而导致 `EXPLAIN ANALYZE` 时造成 goroutine 泄露的问题 [#14226](https://github.com/pingcap/tidb/pull/14226) -+ DDL - - 优化 "change column"/"modify column" 的输出的报错信息，让人更容易理解 [#13796](https://github.com/pingcap/tidb/pull/13796) - - 新增 `SPLIT PARTITION TABLE` 语法，支持分区表切分 Region 功能 [#13929](https://github.com/pingcap/tidb/pull/13929) - - 修复创建索引时，没有正确检查长度，导致索引长度超过 3072 字节没有报错的问题 [#13779](https://github.com/pingcap/tidb/pull/13779) - - 修复由于分区表添加索引时若花费时间过长，可能导致输出 `GC life time is shorter than transaction duration` 报错信息的问题 [#14132](https://github.com/pingcap/tidb/pull/14132) - - 修复在 `DROP COLUMN`/`MODIFY COLUMN`/`CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14105](https://github.com/pingcap/tidb/pull/14105) -+ Server - - Statement Summary 功能改进： - - 新增大量的 SQL 指标字段，便于对 SQL 进行更详细的统计分析 [#14151](https://github.com/pingcap/tidb/pull/14151)，[#14168](https://github.com/pingcap/tidb/pull/14168) - - 新增 `stmt-summary.refresh-interval` 参数用于控制定期将 `events_statements_summary_by_digest` 表中过期的数据移到 `events_statements_summary_by_digest_history` 表，默认间隔时间：30min [#14161](https://github.com/pingcap/tidb/pull/14161) - - 新增 `events_statements_summary_by_digest_history` 表，保存从 `events_statements_summary_by_digest` 中过期的数据 [#14166](https://github.com/pingcap/tidb/pull/14166) - - 修复执行 RBAC 相关的内部 SQL 时，错误输出 binlog 的问题 [#13890](https://github.com/pingcap/tidb/pull/13890) - - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13906](https://github.com/pingcap/tidb/pull/13906) - - 新增通过 HTTP 接口恢复 TiDB binlog 写入功能 [#13892](https://github.com/pingcap/tidb/pull/13892) - - 将 `GRANT roles TO user` 所需要的权限由 `GrantPriv` 修改为 `ROLE_ADMIN` 或 `SUPER`，以与 MySQL 保持一致 [#13932](https://github.com/pingcap/tidb/pull/13932) - - 当 `GRANT` 语句未指定 database 名时，TiDB 行为由使用当前 database 改为报错 `No database selected`，与 MySQL 保持兼容 [#13784](https://github.com/pingcap/tidb/pull/13784) - - 修改 `REVOKE` 语句执行权限从 `SuperPriv` 改成用户只需要有对应 Schema 的权限，就可以执行 `REVOKE` 语句，与 MySQL 保持一致 [#13306](https://github.com/pingcap/tidb/pull/13306) - - 修复 `GRANT ALL` 语法在没有 `WITH GRANT OPTION` 时，错误地将 `GrantPriv` 授权给目标用户的问题 [#13943](https://github.com/pingcap/tidb/pull/13943) - - 修复 `LoadDataInfo` 中调用 `addRecord` 报错时，报错信息不包含导致 `LOAD DATA` 语句行为不正确信息的问题 [#13980](https://github.com/pingcap/tidb/pull/13980) - - 修复因查询中多个 SQL 语句共用同一个 `StartTime` 导致输出错误的慢查询信息的问题 [#13898](https://github.com/pingcap/tidb/pull/13898) - - 修复 `batchClient` 处理大事务时可能造成内存泄露的问题 [#14032](https://github.com/pingcap/tidb/pull/14032) - - 修复 `system_time_zone` 固定显示为 `CST` 的问题，现在 TiDB 的 `system_time_zone` 会从 `mysql.tidb` 表中的 `systemTZ` 获取 [#14086](https://github.com/pingcap/tidb/pull/14086) - - 修复 `GRANT ALL` 语法授予权限不完整（例如 `Lock_tables_priv`）的问题 [#14092](https://github.com/pingcap/tidb/pull/14092) - - 修复 `Priv_create_user` 权限不能 `CREATE ROLE` 和 `DROP ROLE`的问题 [#14088](https://github.com/pingcap/tidb/pull/14088) - - 将 `ErrInvalidFieldSize` 的错误码从 `1105(Unknow Error)` 改成 `3013` [#13737](https://github.com/pingcap/tidb/pull/13737) - - 新增 `SHUTDOWN` 命令用于停止 TiDB Server，并新增 `ShutdownPriv` 权限 [#14104](https://github.com/pingcap/tidb/pull/14104) - - 修复 `DROP ROLE` 语句的原子性问题，避免语句执行失败时，一些 ROLE 仍然被非预期地删除 [#14130](https://github.com/pingcap/tidb/pull/14130) - - 修复 3.0 以下版本升级到 3.0 时，`tidb_enable_window_function` 在 `SHOW VARIABLE` 语句的查询结果错误输出 1 的问题，修复后输出 0 [#14131](https://github.com/pingcap/tidb/pull/14131) - - 修复 TiKV 节点下线时，由于 `gcworker` 持续重试导致可能出现 goroutine 泄露的问题 [#14106](https://github.com/pingcap/tidb/pull/14106) - - 在慢日志中记录 Binlog 的 `Prewrite` 的时间，提升问题追查的易用性 [#14138](https://github.com/pingcap/tidb/pull/14138) - - `tidb_enable_table_partition` 变量支持 GLOBAL SCOPE 作用域 [#14091](https://github.com/pingcap/tidb/pull/14091) - - 修复新增权限时未正确将新增的权限赋予对应的用户导致用户权限可能缺失或者被误添加的问题 [#14178](https://github.com/pingcap/tidb/pull/14178) - - 修复当 TiKV 链接断开时，由于 `rpcClient` 不会关闭而导致 `CheckStreamTimeoutLoop` goroutine 会泄露的问题 [#14227](https://github.com/pingcap/tidb/pull/14227) - - 支持基于证书的身份验证（[使用文档](/dev/reference/security/cert-based-authentication.md)）[#13955](https://github.com/pingcap/tidb/pull/13955) -+ Transaction - - 创建新集群时，`tidb_txn_mode` 变量的默认值由 `""` 改为 `"pessimistic"` [#14171](https://github.com/pingcap/tidb/pull/14171) - - 修复悲观事务模式，事务重试时单条语句的等锁时间没有被重置导致等锁时间过长的问题 [#13990](https://github.com/pingcap/tidb/pull/13990) - - 修复悲观事务模式，因对没有修改的数据未加锁导致可能读到不正确数据的问题 [#14050](https://github.com/pingcap/tidb/pull/14050) - - 修复 mocktikv 中 prewrite 时，没有区分事务类型，导致重复的 insert value 约束检查 [#14175](https://github.com/pingcap/tidb/pull/14175) - - 修复 `session.TxnState` 状态为 `Invalid` 时，事务没有被正确处理导致 panic 的问题 [#13988](https://github.com/pingcap/tidb/pull/13988) - - 修复 mocktikv 中 `ErrConfclit` 结构未包含 `ConflictCommitTS` 的问题 [#14080](https://github.com/pingcap/tidb/pull/14080) - - 修复 TiDB 在 Resolve Lock 之后，没有正确处理锁超时检查导致事务卡住的问题 [#14083](https://github.com/pingcap/tidb/pull/14083) -+ Monitor - - `LockKeys` 新增 `pessimistic_lock_keys_duration` 监控 [#14194](https://github.com/pingcap/tidb/pull/14194) - -## TiKV - -+ Coprocessor - - 修改 Coprocessor 遇到错误时输出日志的级别从 `error` 改成 `warn` [#6051](https://github.com/tikv/tikv/pull/6051) - - 修改统计信息采样数据的更新行为从直接更行改成先删除再插入，更新行为与 tidb-server 保持一致 [#6069](https://github.com/tikv/tikv/pull/6096) -+ Raftstore - - 修复因重复向 `peerfsm` 发送 destory 消息，`peerfsm` 被多次销毁导致 panic 的问题 [#6297](https://github.com/tikv/tikv/pull/6297) - - `split-region-on-table` 默认值由 `true` 改成 `false`，默认关闭按 table 切分 Region 的功能 [#6253](https://github.com/tikv/tikv/pull/6253) -+ Engine - - 修复极端条件下因 RocksDB 迭代器错误未正确处理导致可能返回空数据的问题 [#6326](https://github.com/tikv/tikv/pull/6326) -+ 事务 - - 修复悲观锁因锁未被正确清理导致 Key 无法写入数据，且出现 GC 卡住的问题 [#6354](https://github.com/tikv/tikv/pull/6354) - - 优化悲观锁等锁机制，提升锁冲突严重场景的性能 [#6296](https://github.com/tikv/tikv/pull/6296) -+ 将内存分配库的默认值由 `tikv_alloc/default` 改成 `jemalloc` [#6206](https://github.com/tikv/tikv/pull/6206) - -## PD - -- Client - - 新增通过 `context` 创建新 client，创建新 client 时可设置超时时间 [#1994](https://github.com/pingcap/pd/pull/1994) - - 新增创建 `KeepAlive` 连接功能 [#2035](https://github.com/pingcap/pd/pull/2035) -- 优化`/api/v1/regions` API 的性能 [#1986](https://github.com/pingcap/pd/pull/1986) -- 修复删除 `tombstone` 状态的 Store 可能会导致 panic 的隐患 [#2038](https://github.com/pingcap/pd/pull/2038) -- 修复从磁盘加载 Region 信息时错误的将范围有重叠的 Region 删除的问题 [#2011](https://github.com/pingcap/pd/issues/2011)，[#2040](https://github.com/pingcap/pd/pull/2040) -- 将 etcd 版本从 3.4.0 升级到 3.4.3 稳定版本，注意升级后只能通过 pd-recover 工具降级 [#2058](https://github.com/pingcap/pd/pull/2058) - -## Tools - -+ TiDB Binlog - - 修复 Pump 由于没有收到 DDL 的 commit binlog 导致 binlog 被忽略的问题 [#853](https://github.com/pingcap/tidb-binlog/pull/853) - -## TiDB Ansible - -- 回滚被精简的配置项 [#1053](https://github.com/pingcap/tidb-ansible/pull/1053) -- 优化滚动升级时 TiDB 版本检查的逻辑 [#1056](https://github.com/pingcap/tidb-ansible/pull/1056) -- TiSpark 版本升级到 2.1.8 [#1061](https://github.com/pingcap/tidb-ansible/pull/1061) -- 修复 Grafana 监控上 PD 页面 Role 监控项显示不正确的问题 [#1065](https://github.com/pingcap/tidb-ansible/pull/1065) -- 优化 Grafana 监控上 TiKV Detail 页面上 `Thread Voluntary Context Switches` 和 `Thread Nonvoluntary Context Switches` 监控项 [#1071](https://github.com/pingcap/tidb-ansible/pull/1071) diff --git a/dev/releases/rn.md b/dev/releases/rn.md deleted file mode 100644 index ee1b47cc1ca7..000000000000 --- a/dev/releases/rn.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: TiDB 版本发布历史 -category: release ---- - -# TiDB 版本发布历史 - -TiDB 历史版本发布声明如下： - -## 4.0 - -- [4.0.0-beta](/dev/releases/4.0.0-beta.md) - -## 3.1 - -- [3.1.0-beta.1](/dev/releases/3.1.0-beta.1.md) -- [3.1.0-beta](/dev/releases/3.1.0-beta.md) - -## 3.0 - -- [3.0.10](/dev/releases/3.0.10.md) -- [3.0.9](/dev/releases/3.0.9.md) -- [3.0.8](/dev/releases/3.0.8.md) -- [3.0.7](/dev/releases/3.0.7.md) -- [3.0.6](/dev/releases/3.0.6.md) -- [3.0.5](/dev/releases/3.0.5.md) -- [3.0.4](/dev/releases/3.0.4.md) -- [3.0.3](/dev/releases/3.0.3.md) -- [3.0.2](/dev/releases/3.0.2.md) -- [3.0.1](/dev/releases/3.0.1.md) -- [3.0 GA](/dev/releases/3.0-ga.md) -- [3.0.0-rc.3](/dev/releases/3.0.0-rc.3.md) -- [3.0.0-rc.2](/dev/releases/3.0.0-rc.2.md) -- [3.0.0-rc.1](/dev/releases/3.0.0-rc.1.md) -- [3.0.0-beta.1](/dev/releases/3.0.0-beta.1.md) -- [3.0.0-beta](/dev/releases/3.0beta.md) - -## 2.1 - -- [2.1.19](/dev/releases/2.1.19.md) -- [2.1.18](/dev/releases/2.1.18.md) -- [2.1.17](/dev/releases/2.1.17.md) -- [2.1.16](/dev/releases/2.1.16.md) -- [2.1.15](/dev/releases/2.1.15.md) -- [2.1.14](/dev/releases/2.1.14.md) -- [2.1.13](/dev/releases/2.1.13.md) -- [2.1.12](/dev/releases/2.1.12.md) -- [2.1.11](/dev/releases/2.1.11.md) -- [2.1.10](/dev/releases/2.1.10.md) -- [2.1.9](/dev/releases/2.1.9.md) -- [2.1.8](/dev/releases/2.1.8.md) -- [2.1.7](/dev/releases/2.1.7.md) -- [2.1.6](/dev/releases/2.1.6.md) -- [2.1.5](/dev/releases/2.1.5.md) -- [2.1.4](/dev/releases/2.1.4.md) -- [2.1.3](/dev/releases/2.1.3.md) -- [2.1.2](/dev/releases/2.1.2.md) -- [2.1.1](/dev/releases/2.1.1.md) -- [2.1 GA](/dev/releases/2.1ga.md) -- [2.1 RC5](/dev/releases/21rc5.md) -- [2.1 RC4](/dev/releases/21rc4.md) -- [2.1 RC3](/dev/releases/21rc3.md) -- [2.1 RC2](/dev/releases/21rc2.md) -- [2.1 RC1](/dev/releases/21rc1.md) -- [2.1 Beta](/dev/releases/21beta.md) - -## 2.0 - -- [2.0.11](/dev/releases/2.0.11.md) -- [2.0.10](/dev/releases/2.0.10.md) -- [2.0.9](/dev/releases/209.md) -- [2.0.8](/dev/releases/208.md) -- [2.0.7](/dev/releases/207.md) -- [2.0.6](/dev/releases/206.md) -- [2.0.5](/dev/releases/205.md) -- [2.0.4](/dev/releases/204.md) -- [2.0.3](/dev/releases/203.md) -- [2.0.2](/dev/releases/202.md) -- [2.0.1](/dev/releases/201.md) -- [2.0](/dev/releases/2.0ga.md) -- [2.0 RC5](/dev/releases/2rc5.md) -- [2.0 RC4](/dev/releases/2rc4.md) -- [2.0 RC3](/dev/releases/2rc3.md) -- [2.0 RC1](/dev/releases/2rc1.md) -- [1.1 Beta](/dev/releases/11beta.md) -- [1.1 Alpha](/dev/releases/11alpha.md) - -## 1.0 - -- [1.0](/dev/releases/ga.md) -- [Pre-GA](/dev/releases/prega.md) -- [RC4](/dev/releases/rc4.md) -- [RC3](/dev/releases/rc3.md) -- [RC2](/dev/releases/rc2.md) -- [RC1](/dev/releases/rc1.md) diff --git a/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md b/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md deleted file mode 100644 index 6767daa25ddd..000000000000 --- a/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: 在阿里云上部署 TiDB 集群 -category: how-to ---- - -# 在阿里云上部署 TiDB 集群 - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在阿里云上部署 TiDB 集群。 - -## 环境需求 - -- [aliyun-cli](https://github.com/aliyun/aliyun-cli) >= 3.0.15 并且[配置 aliyun-cli](https://www.alibabacloud.com/help/doc-detail/90766.htm?spm=a2c63.l28256.a3.4.7b52a893EFVglq) - - > **注意：** - > - > Access Key 需要具有操作相应资源的权限。 - -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.12 -- [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.1 且 <= 2.11.0 -- [jq](https://stedolan.github.io/jq/download/) >= 1.6 -- [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) 0.12.* - -你可以使用阿里云的[云命令行](https://shell.aliyun.com)服务来进行操作，云命令行中已经预装并配置好了所有工具。 - -### 权限 - -完整部署集群需要具备以下权限： - -- AliyunECSFullAccess -- AliyunESSFullAccess -- AliyunVPCFullAccess -- AliyunSLBFullAccess -- AliyunCSFullAccess -- AliyunEIPFullAccess -- AliyunECIFullAccess -- AliyunVPNGatewayFullAccess -- AliyunNATGatewayFullAccess - -## 概览 - -默认配置下，会创建： - -- 一个新的 VPC -- 一台 ECS 实例作为堡垒机 -- 一个托管版 ACK（阿里云 Kubernetes）集群以及一系列 worker 节点： - - 属于一个伸缩组的 2 台 ECS 实例（2 核 2 GB）托管版 Kubernetes 的默认伸缩组中必须至少有两台实例，用于承载整个的系统服务，例如 CoreDNS - - 属于一个伸缩组的 3 台 `ecs.g5.large` 实例，用于部署 PD - - 属于一个伸缩组的 3 台 `ecs.i2.2xlarge` 实例，用于部署 TiKV - - 属于一个伸缩组的 2 台 `ecs.c5.4xlarge` 实例用于部署 TiDB - - 属于一个伸缩组的 1 台 `ecs.c5.xlarge` 实例用于部署监控组件 - - 一块 100 GB 的云盘用作监控数据存储 - -除了默认伸缩组之外的其它所有实例都是跨可用区部署的。而伸缩组 (Auto-scaling Group) 能够保证集群的健康实例数等于期望数值。因此，当发生节点故障甚至可用区故障时，伸缩组能够自动为我们创建新实例来确保服务可用性。 - -## 安装部署 - -1. 设置目标 Region 和阿里云密钥（也可以在运行 `terraform` 命令时根据命令提示输入）： - - {{< copyable "shell-regular" >}} - - ```shell - export TF_VAR_ALICLOUD_REGION= && \ - export TF_VAR_ALICLOUD_ACCESS_KEY= && \ - export TF_VAR_ALICLOUD_SECRET_KEY= - ``` - - 用于部署集群的各变量的默认值存储在 `variables.tf` 文件中，如需定制可以修改此文件或在安装时通过 `-var` 参数覆盖。 - -2. 使用 Terraform 进行安装： - - {{< copyable "shell-regular" >}} - - ```shell - git clone --depth=1 https://github.com/pingcap/tidb-operator && \ - cd tidb-operator/deploy/aliyun - ``` - - {{< copyable "shell-regular" >}} - - ```shell - terraform init - ``` - - `apply` 过程中需要输入 `yes` 来确认执行： - - {{< copyable "shell-regular" >}} - - ```shell - terraform apply - ``` - - 假如在运行 `terraform apply` 时出现报错，可根据报错信息（例如缺少权限）进行修复后再次运行 `terraform apply`。 - - 整个安装过程大约需要 5 至 10 分钟，安装完成后会输出集群的关键信息（想要重新查看这些信息，可以运行 `terraform output`）： - - ``` - Apply complete! Resources: 3 added, 0 changed, 1 destroyed. - - Outputs: - - bastion_ip = 47.96.174.214 - cluster_id = c2d9b20854a194f158ef2bc8ea946f20e - kubeconfig_file = /tidb-operator/deploy/aliyun/credentials/kubeconfig - monitor_endpoint = 121.199.195.236:3000 - region = cn-hangzhou - ssh_key_file = /tidb-operator/deploy/aliyun/credentials/my-cluster-keyZ.pem - tidb_endpoint = 172.21.5.171:4000 - tidb_version = v3.0.0 - vpc_id = vpc-bp1v8i5rwsc7yh8dwyep5 - ``` - -3. 用 `kubectl` 或 `helm` 对集群进行操作： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG=$PWD/credentials/kubeconfig - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl version - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm ls - ``` - -## 连接数据库 - -通过堡垒机可连接 TiDB 集群进行测试，相关信息在安装完成后的输出中均可找到： - -{{< copyable "shell-regular" >}} - -```shell -ssh -i credentials/-key.pem root@ -``` - -{{< copyable "shell-regular" >}} - -```shell -mysql -h -P 4000 -u root -``` - -## 监控 - -访问 `` 就可以查看相关的 Grafana 监控面板。相关信息可在安装完成后的输出中找到。默认帐号密码为： - -- 用户名：admin -- 密码：admin - -> **警告：** -> -> 出于安全考虑，假如你已经或将要配置 VPN 用于访问 VPC，强烈建议将 `deploy/modules/aliyun/tidb-cluster/values/default.yaml` 文件里 `monitor.grafana.service.annotations` 中的 `service.beta.kubernetes.io/alicloud-loadbalancer-address-type` 设置为 `intranet` 以禁止监控服务的公网访问。 - -## 升级 TiDB 集群 - -设置 `variables.tf` 中的 `tidb_version` 参数，并再次运行 `terraform apply` 即可完成升级。 - -升级操作可能会执行较长时间，可以通过以下命令来持续观察进度： - -{{< copyable "shell-regular" >}} - -``` -kubectl get pods --namespace -o wide --watch -``` - -## TiDB 集群水平伸缩 - -按需修改 `variables.tf` 中的 `tikv_count` 和 `tidb_count` 数值，再次运行 `terraform apply` 即可完成 TiDB 集群的水平伸缩。 - -## 销毁集群 - -{{< copyable "shell-regular" >}} - -```shell -terraform destroy -``` - -假如 Kubernetes 集群没有创建成功，那么在 destroy 时会出现报错，无法进行正常清理。此时需要手动将 Kubernetes 资源从本地状态中移除： - -{{< copyable "shell-regular" >}} - -```shell -terraform state list -``` - -{{< copyable "shell-regular" >}} - -```shell -terraform state rm module.ack.alicloud_cs_managed_kubernetes.k8s -``` - -销毁集群操作需要执行较长时间。 - -> **注意：** -> -> 监控组件挂载的云盘需要在阿里云管理控制台中手动删除。 - -## 配置 - -### 配置 TiDB Operator - -通过调整 `variables.tf` 内的值来配置 TiDB Operator，大多数配置项均能按照 `variable` 的注释理解语义后进行修改。需要注意的是，`operator_helm_values` 配置项允许为 TiDB Operator 提供一个自定义的 `values.yaml` 配置文件，示例如下： - -- 在 `terraform.tfvars` 中设置 `operator_helm_values`： - - ```hcl - operator_helm_values = "./my-operator-values.yaml" - ``` - -- 在 `main.tf` 中设置 `operator_helm_values`： - - ```hcl - operator_helm_values = file("./my-operator-values.yaml") - ``` - -同时，在默认配置下 Terraform 脚本会创建一个新的 VPC，假如要使用现有的 VPC，可以在 `variable.tf` 中设置 `vpc_id`。注意，当使用现有 VPC 时，没有设置 vswitch 的可用区将不会部署 Kubernetes 节点。 - -### 配置 TiDB 集群 - -TiDB 集群会使用 `./my-cluster.yaml` 作为集群的 `values.yaml` 配置文件，修改该文件即可配置 TiDB 集群。支持的配置项可参考 [Kubernetes 上的 TiDB 集群配置](/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 - -## 管理多个 TiDB 集群 - -需要在一个 Kubernetes 集群下管理多个 TiDB 集群时，需要编辑 `./main.tf`，按实际需要新增 `tidb-cluster` 声明，示例如下： - -```hcl -module "tidb-cluster-dev" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "dev-cluster" - ack = module.tidb-operator - - pd_count = 1 - tikv_count = 1 - tidb_count = 1 - override_values = file("dev-cluster.yaml") -} - -module "tidb-cluster-staging" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "staging-cluster" - ack = module.tidb-operator - - pd_count = 3 - tikv_count = 3 - tidb_count = 2 - override_values = file("staging-cluster.yaml") -} -``` - -注意，多个 TiDB 集群之间 `cluster_name` 必须保持唯一。下面是 `tidb-cluster` 模块的所有可配置参数： - -| 参数名 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `ack` | 封装目标 Kubernetes 集群信息的结构体，必填 | `nil` | -| `cluster_name` | TiDB 集群名，必填且必须唯一 | `nil` | -| `tidb_version` | TiDB 集群版本 | `v3.0.1` | -| `tidb_cluster_chart_version` | `tidb-cluster` helm chart 的版本 | `v1.0.1` | -| `pd_count` | PD 节点数 | 3 | -| `pd_instance_type` | PD 实例类型 | `ecs.g5.large` | -| `tikv_count` | TiKV 节点数 | 3 | -| `tikv_instance_type` | TiKV 实例类型 | `ecs.i2.2xlarge` | -| `tidb_count` | TiDB 节点数 | 2 | -| `tidb_instance_type` | TiDB 实例类型 | `ecs.c5.4xlarge` | -| `monitor_instance_type` | 监控组件的实例类型 | `ecs.c5.xlarge` | -| `override_values` | TiDB 集群的 `values.yaml` 配置文件，通常通过 `file()` 函数从文件中读取 | `nil` | -| `local_exec_interpreter` | 执行命令行指令的解释器 | `["/bin/sh", "-c"]` | - -## 管理多个 Kubernetes 集群 - -推荐针对每个 Kubernetes 集群都使用单独的 Terraform 模块进行管理（一个 Terraform Module 即一个包含 `.tf` 脚本的目录）。 - -`deploy/aliyun` 实际上是将 `deploy/modules` 中的数个可复用的 Terraform 脚本组合在了一起。当管理多个集群时（下面的操作在 `tidb-operator` 项目根目录下进行）： - -1. 首先针对每个集群创建一个目录，如： - - {{< copyable "shell-regular" >}} - - ```shell - mkdir -p deploy/aliyun-staging - ``` - -2. 参考 `deploy/aliyun` 的 `main.tf`，编写自己的脚本，下面是一个简单的例子： - - ```hcl - provider "alicloud" { - region = - access_key = - secret_key = - } - - module "tidb-operator" { - source = "../modules/aliyun/tidb-operator" - - region = - access_key = - secret_key = - cluster_name = "example-cluster" - key_file = "ssh-key.pem" - kubeconfig_file = "kubeconfig" - } - - provider "helm" { - alias = "default" - insecure = true - install_tiller = false - kubernetes { - config_path = module.tidb-operator.kubeconfig_filename - } - } - - module "tidb-cluster" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "example-cluster" - ack = module.tidb-operator - } - - module "bastion" { - source = "../modules/aliyun/bastion" - - bastion_name = "example-bastion" - key_name = module.tidb-operator.key_name - vpc_id = module.tidb-operator.vpc_id - vswitch_id = module.tidb-operator.vswitch_ids[0] - enable_ssh_to_worker = true - worker_security_group_id = module.tidb-operator.security_group_id - } - ``` - -上面的脚本可以自由定制，比如，假如不需要堡垒机则可以移除 `module "bastion"` 相关声明。 - -你也可以直接拷贝 `deploy/aliyun` 目录，但要注意不能拷贝已经运行了 `terraform apply` 的目录，建议重新 clone 仓库再进行拷贝。 - -## 使用限制 - -目前，`pod cidr`，`service cidr` 和节点型号等配置在集群创建后均无法修改。 diff --git a/dev/tidb-in-kubernetes/deploy/aws-eks.md b/dev/tidb-in-kubernetes/deploy/aws-eks.md deleted file mode 100644 index 60d0f6a75ef3..000000000000 --- a/dev/tidb-in-kubernetes/deploy/aws-eks.md +++ /dev/null @@ -1,531 +0,0 @@ ---- -title: 在 AWS EKS 上部署 TiDB 集群 -category: how-to ---- - -# 在 AWS EKS 上部署 TiDB 集群 - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在 AWS EKS (Elastic Kubernetes Service) 上部署 TiDB 集群。 - -## 环境配置准备 - -部署前，请确认已安装以下软件并完成配置： - -* [awscli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) >= 1.16.73，控制 AWS 资源 - - 要与 AWS 交互，必须[配置 `awscli`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。最快的方式是使用 `aws configure` 命令: - - {{< copyable "shell-regular" >}} - - ``` shell - aws configure - ``` - - 替换下面的 AWS Access Key ID 和 AWS Secret Access Key： - - ``` - AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE - AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - Default region name [None]: us-west-2 - Default output format [None]: json - ``` - - > **注意：** - > - > Access key 必须至少具有以下权限：创建 VPC、创建 EBS、创建 EC2 和创建 Role。 - -* [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) >= 0.12 -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.11 -* [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.0 且 < 3.0.0 -* [jq](https://stedolan.github.io/jq/download/) -* [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html)，AWS 权限鉴定工具，确保安装在 `PATH` 路径下。 - - 最简单的安装方法是下载编译好的二进制文件 `aws-iam-authenticator`，如下所示。 - - Linux 用户下载二进制文件： - - {{< copyable "shell-regular" >}} - - ``` shell - curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/linux/amd64/aws-iam-authenticator - ``` - - macOS 用户下载二进制文件： - - {{< copyable "shell-regular" >}} - - ``` shell - curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/darwin/amd64/aws-iam-authenticator - ``` - - 二进制文件下载完成后，执行以下操作： - - {{< copyable "shell-regular" >}} - - ``` shell - chmod +x ./aws-iam-authenticator && \ - sudo mv ./aws-iam-authenticator /usr/local/bin/aws-iam-authenticator - ``` - -## 部署集群 - -默认部署会创建一个新的 VPC、一个 t2.micro 实例作为堡垒机，并包含以下 ec2 实例作为工作节点的 EKS 集群： - -* 3 台 m5.xlarge 实例，部署 PD -* 3 台 c5d.4xlarge 实例，部署 TiKV -* 2 台 c5.4xlarge 实例，部署 TiDB -* 1 台 c5.2xlarge 实例，部署监控组件 - -使用如下命令部署集群。 - -从 Github 克隆代码并进入指定路径： - -{{< copyable "shell-regular" >}} - -``` shell -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator/deploy/aws -``` - -使用 `terraform` 命令初始化并部署集群： - -{{< copyable "shell-regular" >}} - -``` shell -terraform init -``` - -{{< copyable "shell-regular" >}} - -``` shell -terraform apply -``` - -> **注意：** -> -> `terraform apply` 过程中必须输入 "yes" 才能继续。 - -整个过程可能至少需要 10 分钟。`terraform apply` 执行成功后，控制台会输出类似如下的信息： - -``` -Apply complete! Resources: 67 added，0 changed，0 destroyed. - -Outputs: - -bastion_ip = [ - "34.219.204.217", -] -default-cluster_monitor-dns = a82db513ba84511e9af170283460e413-1838961480.us-west-2.elb.amazonaws.com -default-cluster_tidb-dns = a82df6d13a84511e9af170283460e413-d3ce3b9335901d8c.elb.us-west-2.amazonaws.com -eks_endpoint = https://9A9A5ABB8303DDD35C0C2835A1801723.yl4.us-west-2.eks.amazonaws.com -eks_version = 1.12 -kubeconfig_filename = credentials/kubeconfig_my-cluster -region = us-west-21 -``` - -你可以通过 `terraform output` 命令再次获取上面的输出信息。 - -> **注意：** -> -> 1.14 版本以前的 EKS 不支持自动开启 NLB 跨可用区负载均衡，因此默认配置下 会出现各台 TiDB 实例压力不均衡额状况。生产环境下，强烈建议参考 [AWS 官方文档](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-disable-crosszone-lb.html#enable-cross-zone)手动开启 NLB 的跨可用区负载均衡。 - -## 访问数据库 - -`terraform apply` 完成后，可先通过 `ssh` 远程连接到堡垒机，再通过 MySQL client 来访问 TiDB 集群。 - -所需命令如下（用上面的输出信息替换 `<>` 部分内容)： - -{{< copyable "shell-regular" >}} - -```shell -ssh -i credentials/.pem centos@ -``` - -{{< copyable "shell-regular" >}} - -```shell -mysql -h -P 4000 -u root -``` - -`eks_name` 默认为 `my-cluster`。如果 DNS 名字无法解析，请耐心等待几分钟。 - -你还可以通过 `kubectl` 和 `helm` 命令使用 kubeconfig 文件 `credentials/kubeconfig_` 和 EKS 集群交互，主要有两种方式，如下所示。 - -- 指定 --kubeconfig 参数： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl --kubeconfig credentials/kubeconfig_ get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm --kubeconfig credentials/kubeconfig_ ls - ``` - -- 或者，设置 KUBECONFIG 环境变量： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG=$PWD/credentials/kubeconfig_ - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm ls - ``` - -## Grafana 监控 - -你可以通过浏览器访问 `:3000` 地址查看 Grafana 监控指标。 - -Grafana 默认登录信息： - -- 用户名：admin -- 密码：admin - -## 升级 TiDB 集群 - -要升级 TiDB 集群，可编辑 `variables.tf` 文件，修改 `default_cluster_version` 变量到更高版本，然后运行 `terraform apply`。 - -例如，要升级 TiDB 集群到 3.0.1，则修改 `default_cluster_version` 为 `v3.0.1`： - -```hcl -variable "default_cluster_version" { - default = "v3.0.1" -} -``` - -> **注意：** -> -> 升级过程会持续一段时间，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察升级进度。 - -## 扩容 TiDB 集群 - -若要扩容 TiDB 集群，可按需修改 `variables.tf` 文件中的 `default_cluster_tikv_count` 或者 `default_cluster_tidb_count` 变量，然后运行 `terraform apply`。 - -例如，可以将 `default_cluster_tidb_count` 从 2 改为 4 以扩容 TiDB： - -```hcl - variable "default_cluster_tidb_count" { - default = 4 - } -``` - -> **注意：** -> -> - 由于缩容过程中无法确定会缩掉哪个节点，目前还不支持 TiDB 集群的缩容。 -> - 扩容过程会持续几分钟，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察进度。 - -## 自定义 - -你可以按需修改 `variables.tf` 文件中的默认值，例如集群名称和镜像版本等。 - -### 自定义 AWS 相关的资源 - -默认情况下 terraform 脚本会新建 VPC。你也可以通过设置 `create_vpc` 为 `false`，并指定 `vpc_id`、`private_subnet_ids` 和 `public_subnet_ids` 变量为已有的 VPC id、subnet ids 来使用现有的网络。 - -> **注意：** -> -> - 由于 AWS 和 Terraform 的限制，还不支持复用已有 EKS 集群的 VPC 和 subnets，所以请确保只在你手动创建 VPC 的情况下修改该参数； -> - EKS Node 上的 CNI 插件会为每个节点预留一部分 IP 资源，因此 IP 消耗较大，在手动创建 VPC 时，建议将每个 subnet 的掩码长度设置在 18~20 以确保 IP 资源充足，或参考 [EKS CNI 插件文档](https://github.com/aws/amazon-vpc-cni-k8s#cni-configuration-variables)将节点预留的 IP 资源数调低。 - -由于 TiDB 服务通过 [Internal Elastic Load Balancer](https://aws.amazon.com/blogs/aws/internal-elastic-load-balancers/) 暴露，默认情况下，会创建一个 Amazon EC2 实例作为堡垒机，访问创建的 TiDB 集群。堡垒机上预装了 MySQL 和 Sysbench，所以你可以通过 SSH 方式登陆到堡垒机后通过 ELB 访问 TiDB。如果你的 VPC 中已经有了类似的 EC2 实例，你可以通过设置 `create_bastion` 为 `false` 禁掉堡垒机的创建。 - -TiDB 版本和组件数量也可以在 `variables.tf` 中修改，你可以按照自己的需求配置。 - -目前，由于 PD 和 TiKV 依赖 [NVMe SSD 实例存储卷](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html)，TiDB 集群组件的实例类型不能修改。 - -### 自定义 TiDB 参数配置 - -Terraform 脚本中为运行在 EKS 上的 TiDB 集群提供了合理的默认配置。有自定义需求时，你可以在 `clusters.tf` 中通过 `override_values` 参数为每个 TiDB 集群指定一个 `values.yaml` 文件来自定义集群参数配置。 - -作为例子，默认集群使用了 `./default-cluster.yaml` 作为 `values.yaml` 配置文件，并在配置中打开了"配置文件滚动更新"特性。 - -值得注意的是，在 EKS 上部分配置项无法在 `values.yaml` 中进行修改，包括集群版本、副本数、`NodeSelector` 以及 `Tolerations`。`NodeSelector` 和 `Tolerations` 由 Terraform 直接管理以确保基础设施与 TiDB 集群之间的一致性。集群版本和副本数可以通过 `cluster.tf` 文件中的 `tidb-cluster` module 参数来修改。 - -> **注意：** -> -> 自定义 `values.yaml` 配置文件中，不建议包含如下配置（`tidb-cluster` module 默认固定配置）： - -``` -pd: - storageClassName: ebs-gp2 -tikv: - stroageClassName: local-storage -tidb: - service: - type: LoadBalancer - annotations: - service.beta.kubernetes.io/aws-load-balancer-internal: '0.0.0.0/0' - service.beta.kubernetes.io/aws-load-balancer-type: nlb - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: >'true' - separateSlowLog: true -monitor: - storage: 100Gi - storageClassName: ebs-gp2 - persistent: true - grafana: - config: - GF_AUTH_ANONYMOUS_ENABLED: "true" - service: - type: LoadBalancer -``` - -### 自定义 TiDB Operator - -你可以通过 `variables.tf` 中的 `operator_values` 参数传入自定义的 `values.yaml` 内容来配置 TiDB Operator。示例如下： - -```hcl -variable "operator_values" { - description = "The helm values file for TiDB Operator, path is relative to current working dir" - default = "./operator_values.yaml" -} -``` - -## 管理多个 TiDB 集群 - -一个 `tidb-cluster` 模块的实例对应一个 TiDB 集群，你可以通过编辑 `clusters.tf` 添加新的 `tidb-cluster` 模块实例来新增 TiDB 集群，示例如下： - -```hcl -module example-cluster { - source = "../modules/aws/tidb-cluster" - - # The target EKS, required - eks = local.eks - # The subnets of node pools of this TiDB cluster, required - subnets = local.subnets - # TiDB cluster name, required - cluster_name = "example-cluster" - - # Helm values file - override_values = file("example-cluster.yaml") - # TiDB cluster version - cluster_version = "v3.0.0" - # SSH key of cluster nodes - ssh_key_name = module.key-pair.key_name - # PD replica number - pd_count = 3 - # TiKV instance type - pd_instance_type = "t2.xlarge" - # TiKV replica number - tikv_count = 3 - # TiKV instance type - tikv_instance_type = "t2.xlarge" - # The storage class used by TiKV, if the TiKV instance type do not have local SSD, you should change it to storage class - # TiDB replica number - tidb_count = 2 - # TiDB instance type - tidb_instance_type = "t2.xlarge" - # Monitor instance type - monitor_instance_type = "t2.xlarge" - # The version of tidb-cluster helm chart - tidb_cluster_chart_version = "v1.0.0" - # Decides whether or not to create the tidb-cluster helm release. - # If this variable is set to false, you have to - # install the helm release manually - create_tidb_cluster_release = true -} -``` - -> **注意：** -> -> `cluster_name` 必须是唯一的。 - -你可以通过 `kubectl` 获取新集群的监控系统地址与 TiDB 地址。假如你希望让 Terraform 脚本输出这些地址，可以通过在 `outputs.tf` 中增加相关的输出项实现： - -```hcl -output "example-cluster_tidb-hostname" { - value = module.example-cluster.tidb_hostname -} - -output "example-cluster_monitor-hostname" { - value = module.example-cluster.monitor_hostname -} -``` - -修改完成后，执行 `terraform init` 和 `terraform apply` 创建集群。 - -最后，只要移除 `tidb-cluster` 模块调用，对应的 TiDB 集群就会被销毁，EC2 资源也会随之释放。 - -## 仅管理基础设施 - -通过调整配置，你可以控制 Terraform 脚本只创建 Kubernetes 集群和 TiDB Operator。操作步骤如下： - -* 修改 `clusters.tf` 中 TiDB 集群的 `create_tidb_cluster_release` 配置项： - - ```hcl - module "default-cluster" { - ... - create_tidb_cluster_release = false - } - ``` - - 如上所示，当 `create_tidb_cluster_release` 设置为 `false` 时，Terraform 脚本不会创建和修改 TiDB 集群，但仍会创建 TiDB 集群所需的计算和存储资源。此时，你可以使用 Helm 等工具来独立管理集群。 - -> **注意：** -> -> 在已经部署的集群上将 `create_tidb_cluster_release` 调整为 `false` 会导致已安装的 TiDB 集群被删除，对应的 TiDB 集群对象也会随之被删除。 - -## 销毁集群 - -可以通过如下命令销毁集群： - -{{< copyable "shell-regular" >}} - -```shell -terraform destroy -``` - -> **注意：** -> -> * 该操作会销毁 EKS 集群以及部署在该 EKS 集群上的所有 TiDB 集群。 -> * 如果你不再需要存储卷中的数据，在执行 `terraform destroy` 后，你需要在 AWS 控制台手动删除 EBS 卷。 - -## 管理多个 Kubernetes 集群 - -本节详细介绍了如何管理多个 Kubernetes 集群（EKS），并在每个集群上部署一个或更多 TiDB 集群。 - -上述文档中介绍的 Terraform 脚本组合了多个 Terraform 模块： - -- `tidb-operator` 模块，用于创建 EKS 集群并在 EKS 集群上安装配置 [TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md)。 -- `tidb-cluster` 模块，用于创建 TiDB 集群所需的资源池并部署 TiDB 集群。 -- EKS 上的 TiDB 集群专用的 `vpc` 模块、`key-pair`模块和`bastion` 模块 - -管理多个 Kubernetes 集群的最佳实践是为每个 Kubernetes 集群创建一个单独的目录，并在新目录中自行组合上述 Terraform 模块。这种方式能够保证多个集群间的 Terraform 状态不会互相影响，也便于自由定制和扩展。下面是一个例子： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p deploy/aws-staging -vim deploy/aws-staging/main.tf -``` - -`deploy/aws-staging/main.tf` 的内容可以是： - -```hcl -provider "aws" { - region = "us-west-1" -} - -# 创建一个 ssh key，用于登录堡垒机和 Kubernetes 节点 -module "key-pair" { - source = "../modules/aws/key-pair" - - name = "another-eks-cluster" - path = "${path.cwd}/credentials/" -} - -# 创建一个新的 VPC -module "vpc" { - source = "../modules/aws/vpc" - - vpc_name = "another-eks-cluster" -} - -# 在上面的 VPC 中创建一个 EKS 并部署 tidb-operator -module "tidb-operator" { - source = "../modules/aws/tidb-operator" - - eks_name = "another-eks-cluster" - config_output_path = "credentials/" - subnets = module.vpc.private_subnets - vpc_id = module.vpc.vpc_id - ssh_key_name = module.key-pair.key_name -} - -# 特殊处理，确保 helm 操作在 EKS 创建完毕后进行 -resource "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.eks] - sensitive_content = module.tidb-operator.eks.kubeconfig - filename = module.tidb-operator.eks.kubeconfig_filename -} -provider "helm" { - alias = "eks" - insecure = true - install_tiller = false - kubernetes { - config_path = local_file.kubeconfig.filename - } -} - -# 在上面的 EKS 集群上创建一个 TiDB 集群 -module "tidb-cluster-a" { - source = "../modules/aws/tidb-cluster" - providers = { - helm = "helm.eks" - } - - cluster_name = "tidb-cluster-a" - eks = module.tidb-operator.eks - ssh_key_name = module.key-pair.key_name - subnets = module.vpc.private_subnets -} - -# 在上面的 EKS 集群上创建另一个 TiDB 集群 -module "tidb-cluster-b" { - source = "../modules/aws/tidb-cluster" - providers = { - helm = "helm.eks" - } - - cluster_name = "tidb-cluster-b" - eks = module.tidb-operator.eks - ssh_key_name = module.key-pair.key_name - subnets = module.vpc.private_subnets -} - -# 创建一台堡垒机 -module "bastion" { - source = "../modules/aws/bastion" - - bastion_name = "another-eks-cluster-bastion" - key_name = module.key-pair.key_name - public_subnets = module.vpc.public_subnets - vpc_id = module.vpc.vpc_id - target_security_group_id = module.tidb-operator.eks.worker_security_group_id - enable_ssh_to_workers = true -} - -# 输出 tidb-cluster-a 的 TiDB 服务地址 -output "cluster-a_tidb-dns" { - description = "tidb service endpoints" - value = module.tidb-cluster-a.tidb_hostname -} - -# 输出 tidb-cluster-b 的监控地址 -output "cluster-b_monitor-dns" { - description = "tidb service endpoint" - value = module.tidb-cluster-b.monitor_hostname -} - -# 输出堡垒机 IP -output "bastion_ip" { - description = "Bastion IP address" - value = module.bastion.bastion_ip -} -``` - -上面的例子很容易进行定制，比如，假如你不需要堡垒机，便可以删去对 `bastion` 模块的调用。同时，项目中提供的 Terraform 模块均设置了合理的默认值，因此在调用这些 Terraform 模块时，你可以略去大部分的参数。 - -你可以参考默认的 Terraform 脚本来定制每个模块的参数，也可以参考每个模块的 `variables.tf` 文件来了解所有可配置的参数。 - -另外，这些 Terraform 模块可以很容易地集成到你自己的 Terraform 工作流中。假如你对 Terraform 非常熟悉，这也是我们推荐的一种使用方式。 - -> **注意：** -> -> * 由于 Terraform 本身的限制（[hashicorp/terraform#2430](https://github.com/hashicorp/terraform/issues/2430#issuecomment-370685911)），在你自己的 Terraform 脚本中，也需要保留上述例子中对 `helm provider` 的特殊处理。 -> * 创建新目录时，需要注意与 Terraform 模块之间的相对路径，这会影响调用模块时的 `source` 参数。 -> * 假如你想在 tidb-operator 项目之外使用这些模块，你需要确保 `modules` 目录中的所有模块的相对路径保持不变。 - -假如你不想自己写 Terraform 代码，也可以直接拷贝 `deploy/aws` 目录来创建新的 Kubernetes 集群。但要注意不能拷贝已经运行过 `terraform apply` 的目录（已经有 Terraform 的本地状态）。这种情况下，推荐在拷贝前克隆一个新的仓库。 diff --git a/dev/tidb-in-kubernetes/deploy/general-kubernetes.md b/dev/tidb-in-kubernetes/deploy/general-kubernetes.md deleted file mode 100644 index 073286286a0c..000000000000 --- a/dev/tidb-in-kubernetes/deploy/general-kubernetes.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 在标准 Kubernetes 上部署 TiDB 集群 -category: how-to ---- - -# 在标准 Kubernetes 上部署 TiDB 集群 - -本文主要描述了如何在标准的 Kubernetes 集群上通过 TiDB Operator 部署 TiDB 集群。 - -## 前置条件 - -* 参考 [TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md) 完成集群中的 TiDB Operator 部署； -* 参考 [使用 Helm](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 - -## 配置 TiDB 集群 - -通过下面命令获取待安装的 tidb-cluster chart 的 `values.yaml` 配置文件： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p /home/tidb/ && \ -helm inspect values pingcap/tidb-cluster --version= > /home/tidb//values-.yaml -``` - -> **注意：** -> -> - `/home/tidb` 可以替换为你想用的目录。 -> - `release-name` 将会作为 Kubernetes 相关资源（例如 Pod，Service 等）的前缀名，可以起一个方便记忆的名字，要求全局唯一，通过 `helm ls -q` 可以查看集群中已经有的 `release-name`。 -> - `chart-version` 是 tidb-cluster chart 发布的版本，可以通过 `helm search -l tidb-cluster` 查看当前支持的版本。 -> - 下文会用 `values.yaml` 指代 `/home/tidb//values-.yaml`。 - -### 存储类型 - -集群默认使用 `local-storage` 存储类型。 - -- 生产环境：推荐使用本地存储，但实际 Kubernetes 集群中本地存储可能按磁盘类型进行了分类，例如 `nvme-disks`，`sas-disks`。 -- 演示环境或功能性验证：可以使用网络存储，例如 `ebs`，`nfs` 等。 - -另外 TiDB 集群不同组件对磁盘的要求不一样，所以部署集群前要根据当前 Kubernetes 集群支持的存储类型以及使用场景为 TiDB 集群各组件选择合适的存储类型，通过修改 `values.yaml` 中各组件的 `storageClassName` 字段设置存储类型。关于 Kubernetes 集群支持哪些[存储类型](/dev/tidb-in-kubernetes/reference/configuration/storage-class.md)，请联系系统管理员确定。 - -> **注意：** -> -> 如果创建集群时设置了集群中不存在的存储类型，则会导致集群创建处于 Pending 状态，需要[将集群彻底销毁掉](/dev/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md)。 - -### 集群拓扑 - -默认部署的集群拓扑是：3 个 PD Pod，3 个 TiKV Pod，2 个 TiDB Pod 和 1 个监控 Pod。在该部署拓扑下根据数据高可用原则，TiDB Operator 扩展调度器要求 Kubernetes 集群中至少有 3 个节点。如果 Kubernetes 集群节点个数少于 3 个，将会导致有一个 PD Pod 处于 Pending 状态，而 TiKV 和 TiDB Pod 也都不会被创建。 - -Kubernetes 集群节点个数少于 3 个时，为了使 TiDB 集群能启动起来，可以将默认部署的 PD 和 TiKV Pod 个数都减小到 1 个，或者将 `values.yaml` 中 `schedulerName` 改为 Kubernetes 内置调度器 `default-scheduler`。 - -> **警告：** -> -> `default-scheduler` 仅适用于演示环境，改为 `default-scheduler` 后，TiDB 集群的调度将无法保证数据高可用，另外一些其它特性也无法支持，例如 [TiDB Pod StableScheduling](https://github.com/pingcap/tidb-operator/blob/master/docs/design-proposals/tidb-stable-scheduling.md) 等。 - -其它更多配置参数请参考 [TiDB 集群部署配置文档](/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 - -## 部署 TiDB 集群 - -TiDB Operator 部署并配置完成后，可以通过下面命令部署 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster --name= --namespace= --version= -f /home/tidb//values-.yaml -``` - -> **注意：** -> -> `namespace` 是[命名空间](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)，你可以起一个方便记忆的名字，比如和 `release-name` 相同的名称。 - -通过下面命令可以查看 Pod 状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get po -n -l app.kubernetes.io/instance= -``` - -单个 Kubernetes 集群中可以利用 TiDB Operator 部署管理多套 TiDB 集群，重复以上命令并将 `release-name` 替换成不同名字即可。不同集群既可以在相同 `namespace` 中，也可以在不同 `namespace` 中，可根据实际需求进行选择。 diff --git a/dev/tidb-in-kubernetes/deploy/prerequisites.md b/dev/tidb-in-kubernetes/deploy/prerequisites.md deleted file mode 100644 index d531442e2ac1..000000000000 --- a/dev/tidb-in-kubernetes/deploy/prerequisites.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群环境需求 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群环境需求 - -本文介绍在 Kubernetes 上部署 TiDB 集群的软硬件环境需求。 - -## 软件版本要求 - -| 软件名称 | 版本 | -| :--- | :--- | -| Docker | Docker CE 18.09.6 | -| Kubernetes | v1.12.5+ | -| CentOS | CentOS 7.6，内核要求为 3.10.0-957 或之后版本 | - -## 内核参数设置 - -| 配置项 | 设置值 | -| :--- | :--- | -| net.core.somaxconn | 32768 | -| vm.swappiness | 0 | -| net.ipv4.tcp_syncookies | 0 | -| net.ipv4.ip_forward | 1 | -| fs.file-max | 1000000 | -| fs.inotify.max_user_watches | 1048576 | -| fs.inotify.max_user_instances | 1024 | -| net.ipv4.conf.all.rp_filter | 1 | -| net.ipv4.neigh.default.gc_thresh1 | 80000 | -| net.ipv4.neigh.default.gc_thresh2 | 90000 | -| net.ipv4.neigh.default.gc_thresh3 | 100000 | -| net.bridge.bridge-nf-call-iptables | 1 | -| net.bridge.bridge-nf-call-arptables | 1 | -| net.bridge.bridge-nf-call-ip6tables | 1 | - -在设置 `net.bridge.bridge-nf-call-*` 这几项参数时，如果选项报错，则可通过如下命令检查是否已经加载该模块： - -{{< copyable "shell-regular" >}} - -```shell -lsmod|grep br_netfilter -``` - -如果没有加载，则执行如下命令加载： - -{{< copyable "shell-regular" >}} - -```shell -modprobe br_netfilter -``` - -同时还需要关闭每个部署 Kubernetes 节点的 swap，执行如下命令： - -{{< copyable "shell-regular" >}} - -```shell -swapoff -a -``` - -执行如下命令检查 swap 是否已经关闭： - -{{< copyable "shell-regular" >}} - -```shell -free -m -``` - -如果执行命令后输出显示 swap 一列全是 0，则表明 swap 已经关闭。 - -此外，为了永久性地关闭 swap，还需要将 `/etc/fstab` 中 swap 相关的条目全部删除。 - -在上述内容都设置完成后，还需要检查是否给机器配置了 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt)，也就是将各个设备对应的中断号分别绑定到不同的 CPU 上，以防止所有中断请求都落在同一个 CPU 上而引发性能瓶颈。对于 TiDB 集群来说，网卡处理包的速度对集群的吞吐率影响很大。因此下文主要描述如何将网卡中断号绑定到特定的 CPU 上，充分利用多核的优势来提高集群的吞吐率。首先可以通过以下命令来查看网卡对应的中断号： - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/interrupts|grep |awk '{print $1,$NF}' -``` - -以上命令输出的第一列是中断号，第二列是设备名称。如果是多队列网卡，上面的命令会显示多行信息，网卡的每个队列对应一个中断号。通过以下命令可以查看该中断号被绑定到哪个 CPU 上： - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/irq//smp_affinity -``` - -上面命令输出 CPU 序号对应的十六进制值。输出结果欠直观。具体计算方法可参见 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt) 文档。 - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/irq//smp_affinity_list -``` - -上面命令输出 CPU 序号对应的十进制值，输出结果较为直观。 - -如果多队列网卡对应的所有中断号都已被绑定到不同的 CPU 上，那么该机器的 SMP IRQ Affinity 配置是正确的。如果中断号都落在同一个 CPU 上，则需要进行调整。调整的方式有以下两种： - -+ 方法一：开启 [irqbalance](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-tool_reference-irqbalance) 服务。在 centos7 系统上的开启命令如下: - - {{< copyable "shell-regular" >}} - - ```shell - systemctl start irqbalance - ``` - -+ 方法二：禁用 irqbalance，自定义中断号和 CPU 的绑定关系。详情参见脚本 [set_irq_affinity.sh](https://gist.githubusercontent.com/SaveTheRbtz/8875474/raw/0c6e500e81e161505d9111ac77115a2367180d12/set_irq_affinity.sh)。 - -上文所描述的是处理多队列网卡和多核心的场景。单队列网卡和多核的场景则有不同的处理方式。在这种场景下，可以使用 [RPS/RFS](https://www.kernel.org/doc/Documentation/networking/scaling.txt) 在软件层面模拟实现硬件的网卡多队列功能 (RSS)。此时不能使用方法一所述的 irqbalance 服务，而是通过使用方法二提供的脚本来设置 RPS。RFS 的配置可以参考[这里](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-networking-configuration_tools#sect-Red_Hat_Enterprise_Linux-Performance_Tuning_Guide-Configuration_tools-Configuring_Receive_Flow_Steering_RFS)。 - -## 硬件和部署要求 - -与使用 binary 方式部署 TiDB 集群一致，要求选用 Intel x86-64 架构的 64 位通用硬件服务器，使用万兆网卡。关于 TiDB 集群在物理机上的具体部署需求，参考 [TiDB 软件和硬件环境建议配置](/dev/how-to/deploy/hardware-recommendations.md)。 - -对于服务器 disk、memory、CPU 的选择要根据对集群的容量规划以及部署拓扑来定。线上 Kubernetes 集群部署为了保证高可用，一般需要部署三个 master 节点、三个 etcd 节点以及若干个 worker 节点。同时，为了充分利用机器资源，master 节点一般也充当 worker 节点（也就是 master 节点上也可以调度负载）。通过 kubelet 设置[预留资源](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/)来保证机器上的系统进程以及 Kubernetes 的核心进程在工作负载很高的情况下仍然有足够的资源来运行，从而保证整个系统的稳定。 - -下面按 3 Kubernetes master + 3 etcd + 若干 worker 节点部署方案进行分析。Kubernetes 的多 master 节点高可用部署可参考[官方文档](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/)。 - -## Kubernetes 系统资源要求 - -- 每台机器需要一块比较大的 SAS 盘（至少 1T），这块盘用来存 Docker 和 kubelet 的数据目录。Docker 的数据主要包括镜像和容器日志数据，kubelet 主要占盘的数据是 [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) 所使用的数据。 - -- 如果需要部署 Kubernetes 集群的监控系统, 且监控数据需要落盘，则也需要考虑为 Prometheus 准备一块 SAS 盘，后面日志监控系统也需要大的 SAS 盘，同时考虑到机器采购最好是同构的这一因素，因此每台机器最好有两块大的 SAS 盘。 - - > **注意：** - > - > 生产环境建议给这两种类型的盘做 RAID5，至于使用多少块来做 RAID5 可自己决定。 - -- etcd 的分布建议是和 Kubernetes master 节点保持一致，即有多少个 master 节点就部署多少个 etcd 节点。etcd 数据建议使用 SSD 盘存放。 - -## TiDB 集群资源需求 - -TiDB 集群由 PD、TiKV、TiDB 三个组件组成，在做容量规划的时候一般按照可以支持多少套 TiDB 集群来算。这里按照标准的 TiDB 集群（3 个 PD + 3 个 TiKV + 2 个 TiDB）来算，下面是对每个组件规划的一种建议： - -- PD 组件：PD 占用资源较少，这种集群规模下分配 2C 4GB 即可，占用少量本地盘。 - - 为了便于管理，可以将所有集群的 PD 都放在 master 节点，比如需要支持 5 套 TiDB 集群，则可以规划 3 个 master 节点，每个节点支持部署 5 个 PD 实例，5 个 PD 实例使用同一块 SSD 盘即可（两三百 GB 的盘即可）。通过 bind mount 的方式在这块 SSD 上创建 5 个目录作为挂载点，操作方式见 [Sharing a disk filesystem by multiple filesystem PVs](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)。 - - 如果后续要添加更多机器支持更多的 TiDB 集群，可以在 master 上用这种方式继续增加 PD 实例。如果 master 上资源耗尽，可以找其它的 worker 节点机器用同样的方式添加 PD 实例。这种方式的好处就是方便规划和管理 PD 实例，坏处就是由于 PD 实例过于集中，这些机器中如果有两台宕机会导致所有的 TiDB 集群不可用。 - - 因此建议从所有集群里面的机器都拿出一块 SSD 盘像 master 节点一样提供 PD 实例。比如总共 7 台机器，要支持 7 套 TiDB 标准集群的情况下，则需要每台机器上都能支持部署 3 个 PD 实例，如果后续有集群需要通过扩容机器增加容量，也只需要在新的机器上创建 PD 实例。 - -- TiKV 组件：因为 TiKV 组件的性能很依赖磁盘 I/O 且数据量一般较大，因此建议每个 TiKV 实例独占一块 NVMe 的盘，资源配置为 8C 32GB。如果想要在一个机器上支持部署多个 TiKV 实例，则建议参考这些参数去选择合适的机器，同时在规划容量的时候应当预留出足够的 buffer。 - -- TiDB 组件：TiDB 组件因为不占用磁盘，因此在规划的时候只需要考虑其占用的 CPU 和内存资源即可，这里也按 8C 32 GB 的容量来计算。 - -## TiDB 集群规划示例 - -通过上面的分析，这里给出一个支持部署 5 套规模为 3 个 PD + 3 个 TiKV + 2 个 TiDB 集群的例子，其中 PD 配置为 2C 4GB，TiDB 配置为 8C 32GB，TiKV 配置为 8C 32GB。Kubernetes 节点有 7 个，其中有 3 个节点既是 master 又是 worker 节点，另外 4 个是纯 worker 节点。各组件分布情况如下： - -+ 单个 master 节点： - - - 1 etcd (2C 4GB) + 2 PD (2 \* 2C 2 \* 4GB) + 3 TiKV (3 \* 8C 3 \* 32GB) + 1 TiDB (8C 32GB)，总共是 38C 140GB - - 两块 SSD 盘，一块给 etcd，另外一块给 2 个 PD 实例 - - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 - - 三块 NVMe 盘给 TiKV 实例 - -+ 单个 worker 节点： - - - 3 PD (3 \* 2C 3 \* 4GB) + 2 TiKV (2 \* 8C 2 \* 32GB) + 2 TiDB (2 \* 8C 2 \* 32GB)，总共是 38C 140GB - - 一块 SSD 盘给三个 PD 实例 - - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 - - 两块 NVMe 盘给 TiKV 实例 - -从上面的分析来看，要支持 5 套 TiDB 集群容量共需要 7 台物理机，其中 3 台为 master 兼 worker 节点，其余 4 台为 worker 节点，机器配置需求如下： - -- master 兼 worker 节点：48C 192GB；2 块 SSD 盘，一块做了 RAID5 的 SAS 盘，三块 NVMe 盘 -- worker 节点：48C 192GB；1 块 SSD 盘，一块做了 RAID5 的 SAS 盘，两块 NVMe 盘 - -使用上面的机器配置，除去各个组件占用的资源外，还有比较多的预留资源。如果要考虑加监控和日志组件，则可以用同样的方法去规划需要采购的机器类型以及配置。 - -另外，在生产环境的使用上尽量不要在 master 节点部署 TiDB 实例，或者尽可能少地部署 TiDB 实例。这里的主要考虑点是网卡带宽，因为 master 节点网卡满负荷工作会影响到 worker 节点和 master 节点之间的心跳信息汇报，导致比较严重的问题。 diff --git a/dev/tidb-in-kubernetes/deploy/tidb-operator.md b/dev/tidb-in-kubernetes/deploy/tidb-operator.md deleted file mode 100644 index 1f1b7fd2bfea..000000000000 --- a/dev/tidb-in-kubernetes/deploy/tidb-operator.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: 在 Kubernetes 上部署 TiDB Operator -summary: 了解如何在 Kubernetes 上部署 TiDB Operator -category: how-to ---- - -# 在 Kubernetes 上部署 TiDB Operator - -本文介绍如何在 Kubernetes 上部署 TiDB Operator。 - -## 准备环境 - -TiDB Operator 部署前，请确认以下软件需求： - -* Kubernetes v1.12 或者更高版本 -* [DNS 插件](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/) -* [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) -* [RBAC](https://kubernetes.io/docs/admin/authorization/rbac) 启用（可选） -* [Helm](https://helm.sh) 版本 >= v2.8.2 && < v3.0.0 - -> **注意：** -> -> - 尽管 TiDB Operator 可以使用网络卷持久化 TiDB 数据，TiDB 数据自身会存多副本，再走额外的网络卷性能会受到很大影响。强烈建议搭建[本地卷](https://kubernetes.io/docs/concepts/storage/volumes/#local)以提高性能。 -> - 跨多可用区的网络卷需要 Kubernetes v1.12 或者更高版本。在 `tidb-backup` chart 配置中，建议使用网络卷存储备份数据。 - -## 部署 Kubernetes 集群 - -TiDB Operator 运行在 Kubernetes 集群，你可以使用 [Getting started 页面](https://kubernetes.io/docs/setup/)列出的任何一种方法搭建一套 Kubernetes 集群。只要保证 Kubernetes 版本大于等于 v1.12。如果你使用 AWS、GKE 或者本机，下面是快速上手教程： - -* [kind 教程](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) -* [Google GKE 教程](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) -* [AWS EKS 教程](/dev/tidb-in-kubernetes/deploy/aws-eks.md) - -如果你要使用不同环境，必须在 Kubernetes 集群中安装 DNS 插件。可以根据[官方文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/)搭建 DNS 插件。 - -TiDB Operator 使用[持久化卷](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)持久化存储 TiDB 集群数据（包括数据库，监控和备份数据），所以 Kubernetes 集群必须提供至少一种持久化卷。为提高性能，建议使用本地 SSD 盘作为持久化卷。可以根据[这一步](#配置本地持久化卷)自动配置本地持久化卷。 - -Kubernetes 集群建议启用 [RBAC](https://kubernetes.io/docs/admin/authorization/rbac)。否则，需要在 `tidb-operator` 和 `tidb-cluster` chart 的 `values.yaml` 中设置 `rbac.create` 为 `false`。 - -TiDB 默认会使用很多文件描述符，工作节点和上面的 Docker 进程的 `ulimit` 必须设置大于等于 `1048576`： - -* 设置工作节点的 `ulimit` 值，详情可以参考[如何设置 ulimit](https://access.redhat.com/solutions/61334) - - {{< copyable "shell-regular" >}} - - ```shell - sudo vim /etc/security/limits.conf - ``` - - 设置 root 账号的 `soft` 和 `hard` 的 `nofile` 大于等于 `1048576` - -* 设置 Docker 服务的 `ulimit` - - {{< copyable "shell-regular" >}} - - ```shell - sudo vim /etc/systemd/system/docker.service - ``` - - 设置 `LimitNOFILE` 大于等于 `1048576`。 - -> **注意：** -> -> `LimitNOFILE` 需要显式设置为 `1048576` 或者更大，而不是默认的 `infinity`，由于 `systemd` 的 [bug](https://github.com/systemd/systemd/commit/6385cb31ef443be3e0d6da5ea62a267a49174688#diff-108b33cf1bd0765d116dd401376ca356L1186)，`infinity` 在 `systemd` 某些版本中指的是 `65536`。 - -## 安装 Helm - -参考 [使用 Helm](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 - -## 配置本地持久化卷 - -### 准备本地卷 - -参考[本地 PV 配置](/dev/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)在你的 Kubernetes 集群中配置本地持久化卷。 - -## 安装 TiDB Operator - -TiDB Operator 使用 [CRD (Custom Resource Definition)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) 扩展 Kubernetes，所以要使用 TiDB Operator，必须先创建 `TidbCluster` 自定义资源类型。只需要在你的 Kubernetes 集群上创建一次即可： - -{{< copyable "shell-regular" >}} - -```shell -kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/crd.yaml && \ -kubectl get crd tidbclusters.pingcap.com -``` - -创建 `TidbCluster` 自定义资源类型后，接下来在 Kubernetes 集群上安装 TiDB Operator。 - -1. 获取你要安装的 `tidb-operator` chart 中的 `values.yaml` 文件： - - {{< copyable "shell-regular" >}} - - ```shell - mkdir -p /home/tidb/tidb-operator && \ - helm inspect values pingcap/tidb-operator --version= > /home/tidb/tidb-operator/values-tidb-operator.yaml - ``` - - > **注意：** - > - > `` 在后续文档中代表 chart 版本，例如 `v1.0.0`，可以通过 `helm search -l tidb-operator` 查看当前支持的版本。 - -2. 配置 TiDB Operator - - TiDB Operator 里面会用到 `k8s.gcr.io/kube-scheduler` 镜像，如果下载不了该镜像，可以修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 文件中的 `scheduler.kubeSchedulerImageName` 为 `registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler`。 - -3. 安装 TiDB Operator - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-operator --name=tidb-operator --namespace=tidb-admin --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml && \ - kubectl get po -n tidb-admin -l app.kubernetes.io/name=tidb-operator - ``` - -## 自定义 TiDB Operator - -通过修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 中的配置自定义 TiDB Operator。后续文档使用 `values.yaml` 指代 `/home/tidb/tidb-operator/values-tidb-operator.yaml`。 - -TiDB Operator 有两个组件： - -* tidb-controller-manager -* tidb-scheduler - -这两个组件是无状态的，通过 `Deployment` 部署。你可以在 `values.yaml` 中自定义资源 `limit`、`request` 和 `replicas`。 - -修改为 `values.yaml` 后，执行下面命令使配置生效： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade tidb-operator pingcap/tidb-operator --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml -``` diff --git a/dev/tidb-in-kubernetes/faq.md b/dev/tidb-in-kubernetes/faq.md deleted file mode 100644 index f6b2d225f155..000000000000 --- a/dev/tidb-in-kubernetes/faq.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群常见问题 -category: FAQ ---- - -# Kubernetes 上的 TiDB 集群常见问题 - -本文介绍 Kubernetes 上的 TiDB 集群常见问题以及解决方案。 - -## 如何修改时区设置？ - -默认情况下，在 Kubernetes 集群上部署的 TiDB 集群各组件容器中的时区为 UTC，如果要修改时区配置，有下面两种情况： - -* 第一次部署集群 - - 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后部署 TiDB 集群。 - -* 集群已经在运行 - - 如果 TiDB 集群已经在运行，需要做如下修改： - - * 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后升级 TiDB 集群。 - * 参考[时区支持](/dev/how-to/configure/time-zone.md)，修改 TiDB 服务时区配置。 - -## TiDB 相关组件可以配置 HPA 或 VPA 么？ - -TiDB 集群目前还不支持 HPA（Horizontal Pod Autoscaling，自动水平扩缩容）和 VPA（Vertical Pod Autoscaling，自动垂直扩缩容），因为对于数据库这种有状态应用而言，实现自动扩缩容难度较大，无法仅通过 CPU 和 memory 监控数据来简单地实现。 - -## 使用 TiDB Operator 编排 TiDB 集群时，有什么场景需要人工介入操作吗？ - -如果不考虑 Kubernetes 集群本身的运维，TiDB Operator 存在以下可能需要人工介入的场景： - -* TiKV 自动故障转移之后的集群调整，参考[自动故障转移](/dev/tidb-in-kubernetes/maintain/auto-failover.md)； -* 维护或下线指定的 Kubernetes 节点，参考[维护节点](/dev/tidb-in-kubernetes/maintain/kubernetes-node.md)。 - -## 在公有云上使用 TiDB Operator 编排 TiDB 集群时，推荐的部署拓扑是怎样的？ - -首先，为了实现高可用和数据安全，我们在推荐生产环境下的 TiDB 集群中至少部署在三个可用区 (Available Zone)。 - -当考虑 TiDB 集群与业务服务的部署拓扑关系时，TiDB Operator 支持下面几种部署形态。它们有各自的优势与劣势，具体选型需要根据实际业务需求进行权衡： - -* 将 TiDB 集群与业务服务部署在同一个 VPC 中的同一个 Kubernetes 集群上； -* 将 TiDB 集群与业务服务部署在同一个 VPC 中的不同 Kubernetes 集群上； -* 将 TiDB 集群与业务服务部署在不同 VPC 中的不同 Kubernetes 集群上。 - -## TiDB Operator 支持 TiSpark 吗？ - -TiDB Operator 尚不支持自动编排 TiSpark。 - -假如要为 TiDB in Kubernetes 添加 TiSpark 组件，你需要在**同一个** Kubernetes 集群中自行维护 Spark，确保 Spark 能够访问到 PD 和 TiKV 实例的 IP 与端口，并为 Spark 安装 TiSpark 插件，TiSpark 插件的安装方式可以参考 [TiSpark](/dev/reference/tispark.md#已有-Spark-集群的部署方式)。 - -在 Kubernetes 上维护 Spark 可以参考 Spark 的官方文档：[Spark on Kubernetes](http://spark.apache.org/docs/latest/running-on-kubernetes.html)。 - -## 如何查看 TiDB 集群配置？ - -如果需要查看当前集群的 PD、TiKV、TiDB 组件的配置信息，可以执行下列命令: - -* 查看 PD 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -n -- cat /etc/pd/pd.toml - ``` - -* 查看 TiKV 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -n -- cat /etc/tikv/tikv.toml - ``` - -* 查看 TiDB 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -c tidb -n -- cat /etc/tidb/tidb.toml - ``` - -## 部署 TiDB 集群时调度失败是什么原因？ - -TiDB Operator 调度 Pod 失败的原因可能有三种情况： - -* 资源不足，导致 Pod 一直阻塞在 `Pending` 状态。详细说明参见[集群故障诊断](/dev/tidb-in-kubernetes/troubleshoot.md)。 - -* 部分 Node 被打了 `taint`，导致 Pod 无法调度到对应的 Node 上。详请参考 [taint & toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)。 - -* 调度错误，导致 Pod 一直阻塞在 `ContainerCreating` 状态。这种情况发生时请检查 Kubernetes 集群中是否部署过多个 TiDB Operator。重复的 TiDB Operator 自定义调度器的存在，会导致同一个 Pod 的调度周期不同阶段会分别被不同的调度器处理，从而产生冲突。 - - 执行以下命令，如果有两条及以上记录，就说明 Kubernetes 集群中存在重复的 TiDB Operator，请根据实际情况删除多余的 TiDB Operator。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get deployment --all-namespaces |grep tidb-scheduler - ``` diff --git a/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md b/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md deleted file mode 100644 index 68af60c3dfd3..000000000000 --- a/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -title: 在 GCP 上通过 Kubernetes 部署 TiDB 集群 -summary: 在 GCP 上通过 Kubernetes 部署 TiDB 集群教程 -category: how-to ---- - -# 在 GCP 上通过 Kubernetes 部署 TiDB 集群 - -本文介绍如何使用 [TiDB Operator](https://github.com/pingcap/tidb-operator) 在 GCP 上部署 TiDB 集群。本教程需要在 [Google Cloud Shell](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/pingcap/tidb-operator&tutorial=docs/google-kubernetes-tutorial.md) 上运行。 - -所包含的步骤如下： - -- 启动一个包含 3 个节点的 Kubernetes 集群（可选） -- 安装 Kubernetes 包管理工具 Helm -- 部署 TiDB Operator -- 部署 TiDB 集群 -- 访问 TiDB 集群 -- 扩容 TiDB 集群 -- 删除 Kubernetes 集群（可选） - -> **警告：** -> -> 对于生产环境，不要使用此方式进行部署。 - -## 选择一个项目 - -本教程会启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。价格信息可以参考 [All pricing](https://cloud.google.com/compute/pricing)。 - -继续之前请选择一个项目： - - - - -## 启用 API - -本教程需要使用计算和容器 API。继续之前请启用： - - - - -## 配置 gcloud - -这一步配置 glcoud 默认访问你要用的项目和[可用区](https://cloud.google.com/compute/docs/regions-zones/)，可以简化后面用到的命令： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud config set project {{project-id}} && \ -gcloud config set compute/zone us-west1-a -``` - -## 启动 3 个节点的 Kubernetes 集群 - -下面命令启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。 - -命令执行需要几分钟时间： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud container clusters create tidb -``` - -集群启动完成后，将其设置为默认集群： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud config set container/cluster tidb -``` - -最后验证 `kubectl` 可以访问集群并且 3 个节点正常运行： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get nodes -``` - -如果所有节点状态为 `Ready`，恭喜你，你已经成功搭建你的第一个 Kubernetes 集群。 - -## 安装 Helm - -Helm 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 - -安装 `helm`： - -{{< copyable "shell-regular" >}} - -``` shell -curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash -``` - -复制 `helm` 到你的 `$HOME` 目录下，这样即使 Google Cloud Shell 超时断开连接，再次登录后仍然可以访问 Helm： - -{{< copyable "shell-regular" >}} - -``` shell -mkdir -p ~/bin && \ -cp /usr/local/bin/helm ~/bin && \ -echo 'PATH="$PATH:$HOME/bin"' >> ~/.bashrc -``` - -Helm 正常工作需要一定的权限： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl apply -f ./manifests/tiller-rbac.yaml && \ -helm init --service-account tiller --upgrade -``` - -`tiller` 是 Helm 的服务端组件，初始化完成需要几分钟时间： - -{{< copyable "shell-regular" >}} - -``` shell -watch "kubectl get pods --namespace kube-system | grep tiller" -``` - -当 Pod 状态为 `Running`，Ctrl+C 停止并继续下一步。 - -## 添加 Helm 仓库 - -PingCAP Helm 仓库中存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。使用下面命令添加仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo add pingcap https://charts.pingcap.org/ && \ -helm repo list -``` - -然后你可以查看可用的 chart： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo update && \ -helm search tidb-cluster -l && \ -helm search tidb-operator -l -``` - -## 部署 TiDB 集群 - -> **注意：** -> -> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 - -第一个要安装的 TiDB 组件是 TiDB Operator，TiDB Operator 是管理组件，结合 Kubernetes 启动 TiDB 集群并保证集群正常运行。执行下面命令之前请确保在 `tidb-operator` 目录下： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl apply -f ./manifests/crd.yaml && \ -kubectl apply -f ./manifests/gke/persistent-disk.yaml && \ -helm install pingcap/tidb-operator -n tidb-admin --namespace=tidb-admin --version= -``` - -可以通过下面命令观察 Operator 启动情况： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb-admin -o wide --watch -``` - -如果 tidb-scheduler 和 tidb-controller-manager 状态都为 `Running`，Ctrl+C 停止并继续下一步部署一个 TiDB 集群！ - -## 部署你的第一个 TiDB 集群 - -我们可以一键部署一个 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster -n demo --namespace=tidb --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd --version= -``` - -集群启动需要几分钟时间，可以通过下面命令观察状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb -o wide --watch -``` - -TiDB 集群包含 2 个 TiDB pod，3 个 TiKV pod 和 3 个 PD pod。如果所有 pod 状态都为 `Running`，Ctrl+C 停止并继续！ - -## 访问 TiDB 集群 - -从 pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get svc -n tidb --watch -``` - -如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 - -要访问 Kubernetes 集群中的 TiDB 服务，可以在 TiDB 服务和 Google Cloud Shell 之间建立一条隧道。建议这种方式只用于调试，因为如果 Google Cloud Shell 重启，隧道不会自动重新建立。要建立隧道： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n tidb port-forward svc/demo-tidb 4000:4000 &>/tmp/port-forward.log & -``` - -在 Cloud Shell 上运行： - -{{< copyable "shell-regular" >}} - -``` shell -sudo apt-get install -y mysql-client && \ -mysql -h 127.0.0.1 -u root -P 4000 -``` - -在 MySQL 终端中输入一条 MySQL 命令： - -{{< copyable "sql" >}} - -``` sql -select tidb_version(); -``` - -如果用 Helm 安装的过程中没有指定密码，现在可以设置： - -{{< copyable "sql" >}} - -``` sql -SET PASSWORD FOR 'root'@'%' = ''; -``` - -> **注意：** -> -> 这条命令中包含一些特殊字符，Google Cloud Shell 无法自动填充，你需要手动复制、粘贴到控制台中。 - -恭喜，你已经启动并运行一个兼容 MySQL 的分布式 TiDB 数据库！ - -## 扩容 TiDB 集群 - -我们可以一键扩容 TiDB 集群。如下命令可以扩容 TiKV： - -{{< copyable "shell-regular" >}} - -``` shell -helm upgrade demo pingcap/tidb-cluster --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd,tikv.replicas=5 --version= -``` - -TiKV 的 Pod 数量从 3 增加到了 5。可以通过下面命令查看： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get po -n tidb -``` - -## 访问 Grafana 面板 - -要访问 Grafana 面板，可以在 Grafana 服务和 shell 之间建立一条隧道，可以使用如下命令： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n tidb port-forward svc/demo-grafana 3000:3000 &>/dev/null & -``` - -在 Cloud Shell 中，点击 Web Preview 按钮并输入端口 3000，将打开一个新的浏览器标签页访问 Grafana 面板。或者也可以在新浏览器标签或者窗口中直接访问 URL：。 - -如果没有使用 Cloud Shell，可以在浏览器中访问 `localhost:3000`。 - -## 销毁 TiDB 集群 - -如果不再需要这个 TiDB 集群，可以使用下面命令删除集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm delete demo --purge -``` - -上面的命令只会删除运行的 Pod，但是数据还会保留。如果你不再需要那些数据，可以执行下面的命令清除数据和动态创建的持久化磁盘： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl delete pvc -n tidb -l app.kubernetes.io/instance=demo,app.kubernetes.io/managed-by=tidb-operator && \ -kubectl get pv -l app.kubernetes.io/namespace=tidb,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` - -## 删除 Kubernetes 集群 - -实验结束后，可以使用如下命令删除 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud container clusters delete tidb -``` - -## 更多信息 - -我们还提供简单的[基于 Terraform 的部署方案](/dev/tidb-in-kubernetes/deploy/gcp-gke.md)。 diff --git a/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md b/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md deleted file mode 100644 index e2be4a971843..000000000000 --- a/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: 使用 kind 在 Kubernetes 上部署 TiDB 集群 -summary: 使用 kind 在 Kubernetes 上部署 TiDB 集群。 -category: how-to -aliases: ['/docs-cn/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-dind/'] ---- - -# 使用 kind 在 Kubernetes 上部署 TiDB 集群 - -本文介绍了如何在个人电脑（Linux 或 MacOS）上采用 [kind](https://kind.sigs.k8s.io/) 方式在 Kubernetes 上部署 [TiDB Operator](https://github.com/pingcap/tidb-operator) 和 TiDB 集群。 - -kind 通过使用 Docker 容器作为集群节点模拟出一个本地的 Kubernetes 集群。kind 的设计初衷是为了在本地进行 Kubernetes 集群的一致性测试。Kubernetes 集群版本取决于 kind 使用的镜像，你可以指定任一镜像版本用于集群节点，并在 [Docker hub](https://hub.docker.com/r/kindest/node/tags) 中找到想要部署的 Kubernetes 版本。 - -> **警告：** -> -> 对于生产环境，不要使用此方式进行部署。 - -## 环境准备 - -部署前，请确认软件、资源等满足如下需求： - -- 资源需求：CPU 2 核+、内存 4G+ - - > **注意：** - > - > 对于 macOS 系统，需要给 Docker 分配 2 核+ CPU 和 4G+ 内存。详情请参考 [Mac 上配置 Docker](https://docs.docker.com/docker-for-mac/#advanced)。 - -- [Docker](https://docs.docker.com/install/)：版本 >= 17.03 -- [Helm Client](https://helm.sh/docs/intro/install/)：版本 >= 2.9.0 并且 < 3.0.0 -- [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)：版本 >= 1.10，建议 1.13 或更高版本 - - > **注意：** - > - > 不同 kubectl 版本，输出可能略有不同。 - -- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/)：版本 >= 0.4.0 -- [net.ipv4.ip_forward](https://linuxconfig.org/how-to-turn-on-off-ip-forwarding-in-linux) 需要被设置为 `1` - -## 第 1 步：通过 kind 部署 Kubernetes 集群 - -首先确认 Docker 进程正常运行，然后你可以通过脚本命令快速启动一个本地的 Kubernetes 集群。 - -1. Clone 官方提供的代码： - - {{< copyable "shell-regular" >}} - - ``` shell - git clone --depth=1 https://github.com/pingcap/tidb-operator && \ - cd tidb-operator - ``` - -2. 运行脚本，在本地创建一个 Kubernetes 集群： - - {{< copyable "shell-regular" >}} - - ``` shell - hack/kind-cluster-build.sh - ``` - - > **注意：** - > - > 通过该脚本启动的 Kubernetes 集群默认有 6 个节点，Kubernetes 版本默认为 v1.12.8，每个节点默认挂载数为 9。你可以通过启动参数去修改这些参数： - > - > {{< copyable "shell-regular" >}} - > - > ```shell - > hack/kind-cluster-build.sh --nodeNum 2 --k8sVersion v1.14.6 --volumeNum 3 - > ``` - -3. 集群创建完毕后，执行下列命令将 kubectl 的默认配置文件切换到 `kube-config`，从而连接到该本地 Kubernetes 集群： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG="$(kind get kubeconfig-path)" - ``` - -4. 查看该 kubernetes 集群信息： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl cluster-info - ``` - - 输出如下类似信息： - - ``` shell - Kubernetes master is running at https://127.0.0.1:50295 - KubeDNS is running at https://127.0.0.1:50295/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy - ``` - -5. 查看该 Kubernetes 集群的 `storageClass`： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl get storageClass - ``` - - 输出如下类似信息： - - ``` shell - NAME PROVISIONER AGE - local-storage kubernetes.io/no-provisioner 7m50s - standard (default) kubernetes.io/host-path 8m29s - ``` - -## 第 2 步：在 Kubernetes 集群上部署 TiDB Operator - -1. 安装 Helm 并配置 PingCAP 官方 chart 仓库，参考 [使用 Helm](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 小节中的操作。 - -2. 部署 TiDB Operator，参考 [安装 TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md#安装-tidb-operator) 小节中的操作。 - -## 第 3 步：在 Kubernetes 集群中部署 TiDB 集群 - -参考[在标准 Kubernetes 上部署 TiDB 集群](/dev/tidb-in-kubernetes/deploy/general-kubernetes.md#部署-tidb-集群)中的操作。 - -## 访问数据库和监控面板 - -通过 `kubectl port-forward` 暴露服务到主机，可以访问 TiDB 集群。命令中的端口格式为：`<主机端口>:`。 - -- 通过 MySQL 客户端访问 TiDB - - 在访问 TiDB 集群之前，请确保已安装 MySQL client。 - - 1. 使用 kubectl 暴露 TiDB 服务端口： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/-tidb 4000:4000 --namespace= - ``` - - > **注意：** - > - > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:4000 -> 4000`。测试完成后按 `Ctrl + C` 停止代理并退出。 - - 2. 然后，通过 MySQL 客户端访问 TiDB，打开一个**新**终端标签或窗口，执行下面的命令： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -- 查看监控面板 - - 1. 使用 kubectl 暴露 Grafana 服务端口： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/-grafana 3000:3000 --namespace= - ``` - - > **注意：** - > - > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:3000 -> 3000`。测试完成后按 `Ctrl + C` 停止代理并退出。 - - 2. 然后，在浏览器中打开 访问 Grafana 监控面板： - - - 默认用户名：admin - - 默认密码：admin - - > **注意：** - > - > 如果你不是在本地 PC 而是在远程主机上部署的 kind 环境，可能无法通过 localhost 访问远程主机的服务。 - > - > 如果使用 kubectl 1.13 或者更高版本，可以在执行 `kubectl port-forward` 命令时添加 `--address 0.0.0.0` 选项，在 `0.0.0.0` 暴露端口而不是默认的 `127.0.0.1`： - > - > {{< copyable "shell-regular" >}} - > - > ``` - > kubectl port-forward --address 0.0.0.0 -n tidb svc/-grafana 3000:3000 - > ``` - > - > 然后，在浏览器中打开 `http://<远程主机 IP>:3000` 访问 Grafana 监控面板。 - -## 删除 TiDB 集群 与 Kubernetes 集群 - -删除本地 TiDB 集群可参考[销毁 TiDB 集群](/dev/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md#销毁-kubernetes-上的-tidb-集群)。 - -通过下面命令删除该 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -kind delete cluster -``` diff --git a/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md b/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md deleted file mode 100644 index 7139d4ec13c9..000000000000 --- a/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -title: 在 Minikube 集群上部署 TiDB 集群 -summary: 在 Minikube 集群上部署 TiDB 集群 -category: how-to ---- - -# 在 Minikube 集群上部署 TiDB 集群 - -[Minikube](https://kubernetes.io/docs/setup/minikube/) 可以让你在个人电脑上的虚拟机中创建一个 Kubernetes 集群，支持 macOS、Linux 和 Windows 系统。本文介绍如何在 Minikube 集群上部署 TiDB 集群。 - -> **警告：** -> -> - 对于生产环境，不要使用此方式进行部署。 -> -> - 尽管 Minikube 支持通过 `--vm-driver=none` 选项使用主机 Docker 而不使用虚拟机，但是目前尚没有针对 TiDB Operator 做过全面的测试，可能会无法正常工作。如果你想在不支持虚拟化的系统（例如，VPS）上试用 TiDB Operator，可以考虑使用 [kind](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)。 - -## 安装 Minikube 并启动 Kubernetes 集群 - -参考[安装 Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/)，在你的机器上安装 Minikube 1.0.0+。 - -安装完 Minikube 后，可以执行下面命令启动一个 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -minikube start -``` - -对于中国大陆用户，可以使用国内 gcr.io mirror 仓库，例如 `registry.cn-hangzhou.aliyuncs.com/google_containers`。 - -{{< copyable "shell-regular" >}} - -``` shell -minikube start --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers -``` - -或者给 Docker 配置 HTTP/HTTPS 代理。 - -将下面命令中的 `127.0.0.1:1086` 替换为你自己的 HTTP/HTTPS 代理地址： - -{{< copyable "shell-regular" >}} - -``` shell -minikube start --docker-env https_proxy=http://127.0.0.1:1086 \ - --docker-env http_proxy=http://127.0.0.1:1086 -``` - -> **注意：** -> -> 由于 Minikube 通过虚拟机（默认）运行，`127.0.0.1` 是虚拟机本身，有些情况下你可能想要使用你的主机的实际 IP。 - -参考 [Minikube setup](https://kubernetes.io/docs/setup/minikube/) 查看配置虚拟机和 Kubernetes 集群的更多选项。 - -## 安装 kubectl 并访问集群 - -Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/user-guide/kubectl/)，可以让你执行命令访问 Kubernetes 集群。 - -参考 [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) 安装和配置 kubectl。 - -kubectl 安装完成后，测试 Minikube Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl cluster-info -``` - -## 安装 TiDB Operator 并运行 TiDB 集群 - -### 安装 Helm - -[Helm](https://helm.sh/) 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 - -{{< copyable "shell-regular" >}} - -``` shell -curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash -``` - -安装 helm tiller： - -{{< copyable "shell-regular" >}} - -``` shell -helm init -``` - -如果无法访问 gcr.io，你可以尝试 mirror 仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm init --upgrade --tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:$(helm version --client --short | grep -Eo 'v[0-9]\.[0-9]+\.[0-9]+') -``` - -安装完成后，执行 `helm version` 会同时显示客户端和服务端组件版本： - -{{< copyable "shell-regular" >}} - -``` shell -helm version -``` - -输出类似如下内容： - -``` -Client: &version.Version{SemVer:"v2.13.1", -GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} -Server: &version.Version{SemVer:"v2.13.1", -GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} -``` - -如果只显示客户端版本，表示 `helm` 无法连接到服务端。通过 `kubectl` 查看 tiller pod 是否在运行： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n kube-system get pods -l app=helm -``` - -### 添加 Helm 仓库 - -Helm 仓库 (`https://charts.pingcap.org/`) 存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。可使用以下命令添加仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo add pingcap https://charts.pingcap.org/ && \ -helm repo list -``` - -然后可以查看可用的 chart： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo update && \ -helm search tidb-cluster -l && \ -helm search tidb-operator -l -``` - -### 在 Kubernetes 集群上安装 TiDB Operator - -> **注意：** -> -> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 - -克隆 tidb-operator 代码库并安装 TiDB Operator： - -{{< copyable "shell-regular" >}} - -``` shell -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator && \ -kubectl apply -f ./manifests/crd.yaml && \ -helm install pingcap/tidb-operator --name tidb-operator --namespace tidb-admin --version= -``` - -然后，可以通过如下命令查看 TiDB Operator 的启动情况： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb-admin -o wide --watch -``` - -如果无法访问 gcr.io（Pod 由于 ErrImagePull 无法启动），可以尝试从 mirror 仓库中拉取 kube-scheduler 镜像。可以通过以下命令升级 tidb-operator： - -{{< copyable "shell-regular" >}} - -``` shell -helm upgrade tidb-operator pingcap/tidb-operator --namespace tidb-admin --set \ - scheduler.kubeSchedulerImageName=registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler --version= -``` - -如果 tidb-scheduler 和 tidb-controller-manager 都进入 running 状态，你可以继续下一步启动一个 TiDB 集群。 - -### 启动 TiDB 集群 - -通过下面命令启动 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster --name demo --set \ - schedulerName=default-scheduler,pd.storageClassName=standard,tikv.storageClassName=standard,pd.replicas=1,tikv.replicas=1,tidb.replicas=1 --version= -``` - -可以通过下面命令观察集群的状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace default -l app.kubernetes.io/instance=demo -o wide --watch -``` - -通过 Ctrl+C 停止观察。 - -## 测试 TiDB 集群 - -测试 TiDB 集群之前，请确保已经安装 MySQL 客户端。从 Pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get svc --watch -``` - -如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 - -按照以下步骤访问 TiDB 集群： - -1. 转发本地端口到 TiDB 端口。 - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/demo-tidb 4000:4000 - ``` - -2. 在另一个终端窗口中，通过 MySQL 客户端访问 TiDB： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -uroot - ``` - - 或者可以直接执行 SQL 命令： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -uroot -e 'select tidb_version();' - ``` - -## 监控 TiDB 集群 - -按照以下步骤监控 TiDB 集群状态： - -1. 转发本地端口到 Grafana 端口。 - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/demo-grafana 3000:3000 - ``` - -2. 打开浏览器，通过 `http://localhost:3000` 访问 Grafana。 - - 或者，Minikube 提供了 `minikube service` 的方式暴露 Grafana 服务，可以更方便的接入。 - - {{< copyable "shell-regular" >}} - - ``` shell - minikube service demo-grafana - ``` - - 上述命令会自动搭建代理并在浏览器中打开 Grafana。 - -### 删除 TiDB 集群 - -通过下面命令删除 demo 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm delete --purge demo -``` - -更新 demo 集群使用的 PV 的 reclaim 策略为 Delete： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pv -l app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` - -删除 PVC： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl delete pvc -l app.kubernetes.io/managed-by=tidb-operator -``` - -## FAQ - -### Minikube 上的 TiDB 集群不响应或者响应非常慢 - -Minikube 虚拟机默认配置为 2048 MB 内存和 2 个 CPU。可以在 `minikube start` 时通过`--memory` 和 `--cpus` 选项为其分配更多资源。注意，为了使配置修改生效，你需要重新创建 Minikube 虚拟机。 - -{{< copyable "shell-regular" >}} - -``` shell -minikube delete && \ -minikube start --cpus 4 --memory 4096 ... -``` diff --git a/dev/tidb-in-kubernetes/maintain/backup-and-restore.md b/dev/tidb-in-kubernetes/maintain/backup-and-restore.md deleted file mode 100644 index 82e54d153532..000000000000 --- a/dev/tidb-in-kubernetes/maintain/backup-and-restore.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群备份恢复 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群备份与恢复 - -这篇文档详细描述了如何对 Kubernetes 上的 TiDB 集群进行数据备份和数据恢复。 - -Kubernetes 上的 TiDB 集群支持两种备份策略： - -* [全量备份](#全量备份)（定时执行或 Ad-hoc）：使用 [`mydumper`](/dev/reference/tools/mydumper.md) 获取集群的逻辑备份； -* [增量备份](#增量备份)：使用 [`TiDB Binlog`](/dev/reference/tidb-binlog/overview.md) 将 TiDB 集群的数据实时复制到其它数据库中或实时获得增量数据备份； - -目前，Kubernetes 上的 TiDB 集群只对 `mydumper` 获取的全量备份数据提供自动化的数据恢复操作。恢复 `TiDB-Binlog` 获取的增量数据需要手动进行。 - -## 全量备份 - -全量备份使用 `mydumper` 来获取 TiDB 集群的逻辑备份数据。全量备份任务会创建一个 PVC ([PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)) 来存储数据。 - -默认配置下，备份任务使用 PV ([Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes)) 来存储备份数据。你也可以通过修改配置将备份数据存储到 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，在这种情况下，数据在上传到对象存储前，会临时存储在 PV 中。参考 [Kubernetes 上的 TiDB 集群备份配置](/dev/tidb-in-kubernetes/reference/configuration/backup.md) 了解所有的配置选项。 - -你可以配置一个定时执行的全量备份任务，也可以临时执行一个全量备份任务。 - -### 定时全量备份 - -定时全量备份是一个与 TiDB 集群一同创建的定时任务，它会像 `crontab` 任务那样周期性地运行。 - -你可以修改 TiDB 集群的 `values.yaml` 文件来配置定时全量备份： - -1. 将 `scheduledBackup.create` 设置为 `true`； -2. 将 `scheduledBackup.storageClassName` 设置为用于存储数据的 PV 的 `storageClass`； - - > **注意：** - > - > 你必须将定时全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 - -3. 按照 [Cron](https://en.wikipedia.org/wiki/Cron) 格式设置 `scheduledBackup.schedule` 来定义任务的执行周期与时间； -4. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) 该用户必须拥有数据备份所需的数据库相关权限，同时，将 `scheduledBackup.secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -5. 通过 `helm install` 创建一个配置了定时全量备份的 TiDB 集群，针对现有集群，则使用 `helm upgrade` 为集群打开定时全量备份： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -### Ad-hoc 全量备份 - -Ad-hoc 全量备份封装在 `pingcap/tidb-backup` 这个 Helm chart 中。根据 `values.yaml` 文件中的 `mode` 配置，该 chart 可以执行全量备份或数据恢复。我们会在[数据恢复](#数据恢复)一节中描述如何执行数据恢复。 - -你可以通过下面的步骤执行一次 Ad-hoc 全量备份： - -1. 修改 `values.yaml`： - * 将 `clusterName` 设置为目标 TiDB 集群名字； - * 将 `mode` 设置为 `backup`； - * 将 `storage.className` 设置为用于存储数据的 PV 的 `storageClass`； - * 根据数据量调整 `storage.size`； - - > **注意：** - > - > 你必须将 Ad-hoc 全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 - -2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -3. 使用下面的命令执行一次 Ad-hoc 全量备份： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-backup --name= --namespace= -f values.yaml --version= - ``` - -### 查看备份 - -对于存储在 PV 中的备份，你可以使用下面的命令进行查看： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pvc -n -l app.kubernetes.io/component=backup,pingcap.com/backup-cluster-name= -``` - -假如你将数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你可以用这些存储系统自带的图形界面或命令行工具查看全量备份。 - -## 数据恢复 - - 使用 `pingcap/tidb-backup` 这个 Helm chart 进行数据恢复，步骤如下： - -1. 修改 `values.yaml`： - * 将 `clusterName` 设置为目标 TiDB 集群名； - * 将 `mode` 设置为 `restore`； - * 将 `name` 设置为用于恢复的备份名字（你可以参考[查看备份](#查看备份)来寻找可用的备份数据）。假如备份数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你必须保证这些存储的相关配置与执行[全量备份](#全量备份)时一致。 -2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`，假如你在[全量备份](#全量备份)时已经创建了该 Secret，则可以跳过这步）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -3. 恢复数据： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-backup --namespace= --name= -f values.yaml --version= - ``` - -## 增量备份 - -增量备份使用 [TiDB Binlog](/dev/reference/tidb-binlog/overview.md) 工具从 TiDB 集群收集 Binlog，并提供实时备份和向其它数据库的实时同步能力。 - -有关 Kubernetes 上运维 TiDB Binlog 的详细指南，可参阅 [TiDB Binlog](/dev/tidb-in-kubernetes/maintain/tidb-binlog.md)。 - -### Pump 缩容 - -缩容 Pump 需要先将单个 Pump 节点从集群中下线，然后运行 `helm upgrade` 命令将对应的 Pump Pod 删除，并对每个节点重复上述步骤。 - -1. 下线 Pump 节点： - - 假设现在有 3 个 Pump 节点，我们需要下线第 3 个 Pump 节点，将 `` 替换成 `2`，操作方式如下（`` 为当前 TiDB 的版本）。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl run offline-pump- --image=pingcap/tidb-binlog: --namespace= --restart=OnFailure -- /binlogctl -pd-urls=http://-pd:2379 -cmd offline-pump -node-id -pump-:8250 - ``` - - 然后查看 Pump 的日志输出，输出 `pump offline, please delete my pod` 后即可确认该节点已经成功下线。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl logs -f -n -pump- - ``` - -2. 删除对应的 Pump Pod： - - 修改 `values.yaml` 文件中 `binlog.pump.replicas` 为 `2`，然后执行如下命令来删除 Pump Pod： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` diff --git a/dev/tidb-in-kubernetes/maintain/kubernetes-node.md b/dev/tidb-in-kubernetes/maintain/kubernetes-node.md deleted file mode 100644 index ee97abac54f2..000000000000 --- a/dev/tidb-in-kubernetes/maintain/kubernetes-node.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: 维护 TiDB 集群所在的 Kubernetes 节点 -category: how-to ---- - -# 维护 TiDB 集群所在的 Kubernetes 节点 - -TiDB 是高可用数据库，可以在部分数据库节点下线的情况下正常运行，因此，我们可以安全地对底层 Kubernetes 节点进行停机维护。在具体操作时，针对 PD、TiKV 和 TiDB 实例的不同特性，我们需要采取不同的操作策略。 - -本文档将详细介绍如何对 Kubernetes 节点进行临时或长期的维护操作。 - -环境准备： - -- [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [`tkctl`](/dev/tidb-in-kubernetes/reference/tools/tkctl.md) -- [`jq`](https://stedolan.github.io/jq/download/) - -> **注意：** -> -> 长期维护节点前，需要保证 Kubernetes 集群的剩余资源足够运行 TiDB 集群。 - -## 维护 PD 和 TiDB 实例所在节点 - -PD 和 TiDB 实例的迁移较快，可以采取主动驱逐实例到其它节点上的策略进行节点维护： - -1. 检查待维护节点上是否有 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pod --all-namespaces -o wide | grep - ``` - - 假如存在 TiKV 实例，请参考[维护 TiKV 实例所在节点](#维护-tikv-实例所在节点)。 - -2. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl cordon - ``` - -3. 使用 `kubectl drain` 命令将待维护节点上的数据库实例迁移到其它节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl drain --ignore-daemonsets --delete-local-data - ``` - - 运行后，该节点上的 TiDB 实例会自动迁移到其它可用节点上，PD 实例则会在 5 分钟后触发自动故障转移补齐节点。 - -4. 此时，假如希望下线该 Kubernetes 节点，则可以将该节点删除： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete node - ``` - - 假如希望恢复 Kubernetes 节点，则需要在恢复节点后确认其健康状态： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl get node - ``` - - 观察到节点进入 `Ready` 状态后，继续操作。 - -5. 使用 `kubectl uncordon` 命令解除节点的调度限制： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl uncordon - ``` - -6. 观察 Pod 是否全部恢复正常运行： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl get -n $namespace pod -o wide - ``` - - 或者： - - {{< copyable "shell-regular" >}} - - ```sql - watch tkctl get all - ``` - - Pod 恢复正常运行后，操作结束。 - -## 维护 TiKV 实例所在节点 - -TiKV 实例迁移较慢，并且会对集群造成一定的数据迁移负载，因此在维护 TiKV 实例所在节点前，需要根据维护需求选择操作策略： - -- 假如是维护短期内可恢复的节点，则不需要迁移 TiKV 节点，在维护结束后原地恢复节点； -- 假如是维护短期内不可恢复的节点，则需要规划 TiKV 的迁移工作。 - -### 维护短期内可恢复的节点 - -针对短期维护，我们可以通过调整 PD 集群的 `max-store-down-time` 配置来增大集群所允许的 TiKV 实例下线时间，在此时间内维护完毕并恢复 Kubernetes 节点后，所有该节点上的 TiKV 实例会自动恢复。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward svc/-pd 2379:2379 -``` - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -d config set max-store-down-time 10m -``` - -调整 `max-store-down-time` 到合理的值后，后续的操作方式与[维护 PD 和 TiDB 实例所在节点](#维护-pd-和-tidb-实例所在节点)相同。 - -### 维护短期内不可恢复的节点 - -针对短期内不可恢复的节点维护，如节点长期下线等情形，需要使用 `pd-ctl` 主动通知 TiDB 集群下线对应的 TiKV 实例，再手动解除 TiKV 实例与该节点的绑定。 - -1. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl cordon - ``` - -2. 查看待维护节点上的 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - tkctl get -A tikv | grep - ``` - -3. 使用 `pd-ctl` 主动下线 TiKV 实例。 - - > **注意：** - > - > 下线 TiKV 实例前，需要保证集群中剩余的 TiKV 实例数不少于 PD 配置中的 TiKV 数据副本数（配置项：`max-replicas`）。假如不符合该条件，需要先操作扩容 TiKV。 - - 查看 TiKV 实例的 `store-id`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get tc -ojson | jq '.status.tikv.stores | .[] | select ( .podName == "" ) | .id' - ``` - - 下线实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward svc/-pd 2379:2379 - ``` - - {{< copyable "shell-regular" >}} - - ```shell - pd-ctl -d store delete - ``` - -4. 等待 store 状态（`state_name`）转移为 `Tombstone`： - - {{< copyable "shell-regular" >}} - - ```shell - watch pd-ctl -d store - ``` - -5. 解除 TiKV 实例与节点本地盘的绑定。 - - 查询 Pod 使用的 `PesistentVolumeClaim`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n pod -ojson | jq '.spec.volumes | .[] | select (.name == "tikv") | .persistentVolumeClaim.claimName' - ``` - - 删除该 `PesistentVolumeClaim`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pvc - ``` - -6. 删除 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pod - ``` - -7. 观察该 TiKV 实例是否正常调度到其它节点上： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 假如待维护节点上还有其它 TiKV 实例，则重复同样的操作步骤直到所有的 TiKV 实例都迁移到其它节点上。 - -8. 确认节点不再有 TiKV 实例后，再逐出节点上的其它实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl drain --ignore-daemonsets --delete-local-data - ``` - -9. 再次确认节点不再有任何 TiKV、TiDB 和 PD 实例运行： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pod --all-namespaces | grep - ``` - -10. 最后（可选），假如是长期下线节点，建议将节点从 Kubernetes 集群中删除： - - {{< copyable "shell-regular" >}} - - ```shell - kuebctl delete node - ``` - -至此，操作完成。 diff --git a/dev/tidb-in-kubernetes/maintain/lightning.md b/dev/tidb-in-kubernetes/maintain/lightning.md deleted file mode 100644 index 52c543d28c27..000000000000 --- a/dev/tidb-in-kubernetes/maintain/lightning.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 恢复 Kubernetes 上的 TiDB 集群数据 -summary: 使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据。 -category: how-to ---- - -# 恢复 Kubernetes 上的 TiDB 集群数据 - -本文介绍了如何使用 [TiDB Lightning](https://github.com/pingcap/tidb-lightning) 快速恢复 Kubernetes 上的 TiDB 集群数据。 - -TiDB Lightning 包含两个组件：tidb-lightning 和 tikv-importer。在 Kubernetes 上，tikv-importer 位于 TiDB 集群的 Helm chart 内，被部署为一个副本数为 1 (`replicas=1`) 的 `StatefulSet`；tidb-lightning 位于单独的 Helm chart 内，被部署为一个 `Job`。 - -为了使用 TiDB Lightning 恢复数据，tikv-importer 和 tidb-lightning 都必须分别部署。 - -## 部署 tikv-importer - -tikv-importer 可以在一个现有的 TiDB 集群上启用，或者在新建 TiDB 集群时启用。 - -* 在新建一个 TiDB 集群时启用 tikv-importer： - - 1. 在 `tidb-cluster` 的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 - - 2. 部署该集群。 - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster --name= --namespace= -f values.yaml --version= - ``` - -* 配置一个现有的 TiDB 集群以启用 tikv-importer： - - 1. 在该 TiDB 集群的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 - - 2. 升级该 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -## 部署 tidb-lightning - -1. 配置 TiDB Lightning - - 使用如下命令获得 TiDB Lightning 的默认配置。 - - {{< copyable "shell-regular" >}} - - ```shell - helm inspect values pingcap/tidb-lightning --version= > tidb-lightning-values.yaml - ``` - - tidb-lightning Helm chart 支持恢复本地或远程的备份数据。 - - * 本地模式 - - 本地模式要求 Mydumper 备份数据位于其中一个 Kubernetes 节点上。要启用该模式，你需要将 `dataSource.local.nodeName` 设置为该节点名称，将 `dataSource.local.hostPath` 设置为 Mydumper 备份数据目录路径，该路径中需要包含名为 `metadata` 的文件。 - - * 远程模式 - - 与本地模式不同，远程模式需要使用 [rclone](https://rclone.org) 将 Mydumper 备份 tarball 文件从网络存储中下载到 PV 中。远程模式能在 rclone 支持的任何云存储下工作，目前已经有以下存储进行了相关测试：[Google Cloud Storage (GCS)](https://cloud.google.com/storage/)、[AWS S3](https://aws.amazon.com/s3/) 和 [Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/)。 - - 1. 确保 `values.yaml` 中的 `dataSource.local.nodeName` 和 `dataSource.local.hostPath` 被注释掉。 - - 2. 新建一个包含 rclone 配置的 `Secret`。rclone 配置示例如下。一般只需要配置一种云存储。有关其他的云存储，请参考 [rclone 官方文档](https://rclone.org/)。 - - {{< copyable "" >}} - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: cloud-storage-secret - type: Opaque - stringData: - rclone.conf: | - [s3] - type = s3 - provider = AWS - env_auth = false - access_key_id = - secret_access_key = - region = us-east-1 - [ceph] - type = s3 - provider = Ceph - env_auth = false - access_key_id = - secret_access_key = - endpoint = - region = :default-placement - [gcs] - type = google cloud storage - # 该服务账号必须被授予 Storage Object Viewer 角色。 - # 该内容可以通过 `cat | jq -c .` 命令获取。 - service_account_credentials = - ``` - - 使用你的实际配置替换上述配置中的占位符，并将该文件存储为 `secret.yaml`。然后通过 `kubectl apply -f secret.yaml -n ` 命令创建该 `Secret`。 - - 3. 将 `dataSource.remote.storageClassName` 设置为 Kubernetes 集群中现有的一个存储类型。 - -2. 部署 TiDB Lightning - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-lightning --name= --namespace= --set failFast=true -f tidb-lightning-values.yaml --version= - ``` - -当 TiDB Lightning 未能成功恢复数据时，不能简单地直接重启进程，必须进行**手动干预**，否则将很容易出现错误。因此，tidb-lightning 的 `Job` 重启策略被设置为 `Never`。 - -> **注意：** -> -> 目前，即使数据被成功恢复，TiDB Lightning 也会[报出非零错误码并退出](https://github.com/pingcap/tidb-lightning/pull/230)，这会导致 `Job` 失败。因此，数据恢复成功与否需要通过查看 tidb-lightning pod 的日志进行确认。 - -如果 TiDB Lightning 未能成功恢复数据，需要采用以下步骤进行手动干预： - -1. 运行 `kubectl delete job -n -tidb-lightning`，删除 lightning `Job`。 - -2. 运行 `helm template pingcap/tidb-lightning --name --set failFast=false -f tidb-lightning-values.yaml | kubectl apply -n -f -`，重新创建禁用 `failFast` 的 lightning `Job`。 - -3. 当 lightning pod 重新运行时，在 lightning 容器中执行 `kubectl exec -it -n sh` 命令。 - -4. 运行 `cat /proc/1/cmdline`，获得启动脚本。 - -5. 参考[故障排除指南](/dev/how-to/troubleshoot/tidb-lightning.md#tidb-lightning-troubleshooting)，对 lightning 进行诊断。 - -## 销毁 TiDB Lightning - -目前，TiDB Lightning 只能在线下恢复数据。当恢复过程结束、TiDB 集群需要向外部应用提供服务时，可以销毁 TiDB Lightning 以节省开支。 - -删除 tikv-importer 的步骤： - -1. 在 TiDB 集群 chart 的 `values.yaml` 文件中将 `importer.create` 设置为 `false`。 - -2. 然后运行 `helm upgrade pingcap/tidb-cluster -f values.yaml`。 - -删除 tidb-lightning 的方法： - -* 运行 `helm delete --purge`。 diff --git a/dev/tidb-in-kubernetes/maintain/tidb-binlog.md b/dev/tidb-in-kubernetes/maintain/tidb-binlog.md deleted file mode 100644 index 47f19fe6cc9b..000000000000 --- a/dev/tidb-in-kubernetes/maintain/tidb-binlog.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB Binlog 运维 -summary: 了解如何在 Kubernetes 上运维 TiDB 集群的 TiDB Binlog。 -category: how-to ---- - -# TiDB Binlog 运维 - -本文档介绍如何在 Kubernetes 上运维 TiDB 集群的 [TiDB Binlog](/dev/reference/tidb-binlog/overview.md)。 - -## 运维准备 - -- [部署 TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md)； -- [安装 Helm](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 并配置 PingCAP 官方 chart 仓库。 - -## 启用 TiDB 集群的 TiDB Binlog - -默认情况下，TiDB Binlog 在 TiDB 集群中处于禁用状态。若要创建一个启用 TiDB Binlog 的 TiDB 集群，或在现有 TiDB 集群中启用 TiDB Binlog，可根据以下步骤进行操作： - -1. 按照以下说明修改 `values.yaml` 文件： - - * 将 `binlog.pump.create` 的值设为 `true`。 - * 将 `binlog.drainer.create` 的值设为 `true`。 - * 将 `binlog.pump.storageClassName` 和 `binlog.drainer.storageClassName` 设为所在 Kubernetes 集群上可用的 `storageClass`。 - * 将 `binlog.drainer.destDBType` 设为所需的下游存储类型。 - - TiDB Binlog 支持三种下游存储类型： - - * PersistenceVolume：默认的下游存储类型。可通过修改 `binlog.drainer.storage` 来为 `drainer` 配置大 PV。 - - * 与 MySQL 兼容的数据库：通过将 `binlog.drainer.destDBType` 设置为 `mysql` 来启用。同时，必须在 `binlog.drainer.mysql` 中配置目标数据库的地址和凭据。 - - * Apache Kafka：通过将 `binlog.drainer.destDBType` 设置为 `kafka` 来启用。同时，必须在 `binlog.drainer.kafka` 中配置目标集群的 zookeeper 地址和 Kafka 地址。 - -2. 为 TiDB 与 Pump 组件设置亲和性和反亲和性： - - > **注意：** - > - > 如果在生产环境中开启 TiDB Binlog，建议为 TiDB 与 Pump 组件设置亲和性和反亲和性。如果在内网测试环境中尝试使用开启 TiDB Binlog，可以跳过此步。 - - 默认情况下，TiDB 的 affinity 亲和性设置为 `{}`。由于目前 Pump 组件与 TiDB 组件默认并非一一对应，当启用 TiDB Binlog 时，如果 Pump 与 TiDB 组件分开部署并出现网络隔离，而且 TiDB 组件还开启了 `ignore-error`，则会导致 TiDB 丢失 Binlog。推荐通过亲和性特性将 TiDB 组件与 Pump 部署在同一台 Node 上，同时通过反亲和性特性将 Pump 分散在不同的 Node 上，每台 Node 上至多仅需一个 Pump 实例。 - - > **注意：** - > - > `` 需要替换为目标 `tidb-cluster` 的 Helm release name。 - - * 将 `tidb.affinity` 按照如下设置： - - ```yaml - tidb: - affinity: - podAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "pump" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - ``` - - * 将 `binlog.pump.affinity` 按照如下设置： - - ```yaml - binlog: - pump: - affinity: - podAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "tidb" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "pump" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - ``` - -3. 创建一个新的 TiDB 集群或更新现有的集群： - - * 创建一个启用 TiDB Binlog 的 TiDB 新集群： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster --name= --namespace= --version= -f - ``` - - * 更新现有的 TiDB 集群以启用 TiDB Binlog： - - > **注意：** - > - > 如果设置了 TiDB 组件的亲和性，那么更新现有的 TiDB 集群将引起 TiDB 集群中的 TiDB 组件滚动更新。 - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster --version= -f - ``` - -## 部署多个 drainer - -默认情况下，仅创建一个下游 drainer。可安装 `tidb-drainer` Helm chart 来为 TiDB 集群部署多个 drainer，示例如下： - -1. 确保 PingCAP Helm 库是最新的： - - {{< copyable "shell-regular" >}} - - ```shell - helm repo update - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm search tidb-drainer -l - ``` - -2. 获取默认的 `values.yaml` 文件以方便自定义： - - {{< copyable "shell-regular" >}} - - ```shell - helm inspect values pingcap/tidb-drainer --version= > values.yaml - ``` - -3. 修改 `values.yaml` 文件以指定源 TiDB 集群和 drainer 的下游数据库。示例如下： - - ```yaml - clusterName: example-tidb - clusterVersion: v3.0.0 - storageClassName: local-storage - storage: 10Gi - config: | - detect-interval = 10 - [syncer] - worker-count = 16 - txn-batch = 20 - disable-dispatch = false - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - safe-mode = false - db-type = "tidb" - [syncer.to] - host = "slave-tidb" - user = "root" - password = "" - port = 4000 - ``` - - `clusterName` 和 `clusterVersion` 必须匹配所需的源 TiDB 集群。 - - 有关完整的配置详细信息，请参阅 [Kubernetes 上的 TiDB Binlog Drainer 配置](/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md)。 - -4. 部署 drainer： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-drainer --name= --namespace= --version= -f values.yaml - ``` - - > **注意：** - > - > 该 chart 必须与源 TiDB 集群安装在相同的命名空间中。 diff --git a/dev/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md b/dev/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md deleted file mode 100644 index 19a59509b19f..000000000000 --- a/dev/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群监控 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群监控 - -基于 Kubernetes 环境部署的 TiDB 集群监控可以大体分为两个部分：对 TiDB 集群本身的监控、对 Kubernetes 集群及 TiDB Operator 的监控。本文将对两者进行简要说明。 - -## TiDB 集群的监控 - -TiDB 通过 Prometheus 和 Grafana 监控 TiDB 集群。在通过 TiDB Operator 创建新的 TiDB 集群时，对于每个 TiDB 集群，会同时创建、配置一套独立的监控系统，与 TiDB 集群运行在同一 Namespace，包括 Prometheus 和 Grafana 两个组件。 - -监控数据默认没有持久化，如果由于某些原因监控容器重启，已有的监控数据会丢失。可以在 `values.yaml` 中设置 `monitor.persistent` 为 `true` 来持久化监控数据。开启此选项时应将 `storageClass` 设置为一个当前集群中已有的存储，并且此存储应当支持将数据持久化，否则仍然会存在数据丢失的风险。 - -在 [TiDB 集群监控](/dev/how-to/monitor/monitor-a-cluster.md)中有一些监控系统配置的细节可供参考。 - -### 查看监控面板 - -可以通过 `kubectl port-forward` 查看监控面板： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-grafana 3000:3000 &>/tmp/portforward-grafana.log & -``` - -然后在浏览器中打开 [http://localhost:3000](http://localhost:3000)，默认用户名和密码都为 `admin`。 - -Grafana 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.grafana.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问面板。 - -如果不需要使用 Grafana，可以在部署时在 `values.yaml` 中将 `monitor.grafana.create` 设置为 `false` 来节省资源。这一情况下需要使用其他已有或新部署的数据可视化工具直接访问监控数据来完成可视化。 - -### 访问监控数据 - -对于需要直接访问监控数据的情况，可以通过 `kubectl port-forward` 来访问 Prometheus： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-prometheus 9090:9090 &>/tmp/portforward-prometheus.log & -``` - -然后在浏览器中打开 [http://localhost:9090](http://localhost:9090)，或通过客户端工具访问此地址即可。 - -Prometheus 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.prometheus.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问监控数据。 - -## Kubernetes 的监控 - -随集群部署的 TiDB 监控只关注 TiDB 本身各组件的运行情况，并不包括对容器资源、宿主机、Kubernetes 组件和 TiDB Operator 等的监控。对于这些组件或资源的监控，需要在整个 Kubernetes 集群维度部署监控系统来实现。 - -### 宿主机监控 - -对宿主机及其资源的监控与传统的服务器物理资源监控相同。 - -如果在你的现有基础设施中已经有针对物理服务器的监控系统，只需要通过常规方法将 Kubernetes 所在的宿主机添加到现有监控系统中即可；如果没有可用的监控系统，或者希望部署一套独立的监控系统用于监控 Kubernetes 所在的宿主机，也可以使用你熟悉的任意监控系统。 - -新部署的监控系统可以运行于独立的服务器、直接运行于 Kubernetes 所在的宿主机，或运行于 Kubernetes 集群内，不同部署方式除在安装配置与资源利用上存在少许差异，在使用上并没有重大区别。 - -常见的可用于监控服务器资源的开源监控系统有： - -- [CollectD](https://collectd.org/) -- [Nagios](https://www.nagios.org/) -- [Prometheus](http://prometheus.io/) & [node_exporter](https://github.com/prometheus/node_exporter) -- [Zabbix](https://www.zabbix.com/) - -一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的监控解决方案可以选择。 - -我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 在 Kubernetes 集群内部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于 Kubernetes 自身组件的监控。 - -### Kubernetes 组件监控 - -对 Kubernetes 组件的监控可以参考[官方文档](https://kubernetes.io/docs/tasks/debug-application-cluster/resource-usage-monitoring/)提供的方案，也可以使用其他兼容 Kubernetes 的监控系统来进行。 - -一些云服务商可能提供了自己的 Kubernetes 组件监控方案，一些专门的性能监控服务商也有各自的 Kubernetes 集成方案可以选择。 - -由于 TiDB Operator 实际上是运行于 Kubernetes 中的容器，选择任一可以覆盖对 Kubernetes 容器状态及资源进行监控的监控系统即可覆盖对 TiDB Operator 的监控，无需再额外部署监控组件。 - -我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于对宿主机资源的监控。 - -## 报警配置 - -### TiDB 集群报警 - -在随 TiDB 集群部署 Prometheus 时，会自动导入一些默认的报警规则，可以通过浏览器访问 Prometheus 的 Alerts 页面查看当前系统中的所有报警规则和状态。 - -我们目前暂不支持报警规则的自定义配置，如果确实需要修改报警规则，可以手动下载 charts 进行修改。 - -默认的 Prometheus 和报警配置不能发送报警消息，如需发送报警消息，可以使用任意支持 Prometheus 报警的工具与其集成。推荐通过 [AlertManager](https://prometheus.io/docs/alerting/alertmanager/) 管理与发送报警消息。 - -如果在你的现有基础设施中已经有可用的 AlertManager 服务，可以在 `values.yaml` 文件中修改 `monitor.prometheus.alertmanagerURL` 配置其地址供 Prometheus 使用；如果没有可用的 AlertManager 服务，或者希望部署一套独立的服务，可以参考官方的[说明](https://github.com/prometheus/alertmanager)部署。 - -### Kubernetes 报警 - -如果使用 Prometheus Operator 部署针对 Kubernetes 宿主机和服务的监控，会默认配置一些告警规则，并且会部署一个 AlertManager 服务，具体的设置方法请参阅 [kube-prometheus](https://github.com/coreos/kube-prometheus) 的说明。 - -如果使用其他的工具或服务对 Kubernetes 宿主机和服务进行监控，请查阅该工具或服务提供商的对应资料。 diff --git a/dev/tidb-in-kubernetes/reference/configuration/backup.md b/dev/tidb-in-kubernetes/reference/configuration/backup.md deleted file mode 100644 index 0f1017721aef..000000000000 --- a/dev/tidb-in-kubernetes/reference/configuration/backup.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群备份配置 -category: reference ---- - -# Kubernetes 上的 TiDB 集群备份配置 - -`tidb-backup` 是一个用于 Kubernetes 上 TiDB 集群备份和恢复的 Helm Chart。本文详细介绍了 `tidb-backup` 的可配置参数。 - -## `mode` - -+ 运行模式 -+ 默认："backup" -+ 可选值为 `backup`（备份集群数据）和 `restore`（恢复集群数据） - -## `clusterName` - -+ 目标集群名字 -+ 默认："demo" -+ 指定要从哪个集群进行备份或将数据恢复到哪个集群中 - -## `name` - -+ 备份名 -+ 默认值："fullbackup-"，`` 是备份的开始时间，精确到分钟 -+ 备份名用于区分不同的备份数据 - -## `secretName` - -+ 访问目标集群时使用的凭据 -+ 默认："backup-secret" -+ 该 Kubernetes Secret 中需要存储目标集群的登录用户名和密码，你可以通过以下命令来创建这个 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user=root --from-literal=password= - ``` - -## `storage.className` - -+ Kubernetes StorageClass -+ 默认："local-storage" -+ 备份任务需要绑定一个持久卷 (Persistent Volume, PV) 来永久或临时存储备份数据，`StorageClass` 用于声明持久卷使用的存储类型，需要确保该 `StorageClass` 在 Kubernetes 集群中存在。 - -## `storage.size` - -+ 持久卷的空间大小 -+ 默认："100Gi" - -## `backupOptions` - -+ 备份参数 -+ 默认："--chunk-filesize=100" -+ 为备份数据时使用的 [Mydumper](https://github.com/maxbube/mydumper/blob/master/docs/mydumper_usage.rst#options) 指定额外的运行参数 - -## `restoreOptions` - -+ 恢复参数 -+ 默认："-t 16" -+ 为恢复数据时使用的 [Loader](/dev/reference/tools/loader.md) 指定额外的运行参数 - -## `gcp.bucket` - -+ Google Cloud Storage 的 bucket 名字 -+ 默认："" -+ 用于存储备份数据到 Google Cloud Storage 上 - -> **注意：** -> -> 一旦设置了 `gcp` 下的任何参数，备份和恢复就会使用 Google Cloud Storage 进行数据存储。也就是说，假如要设置 `gcp` 下的参数，就需要保证所有 `gcp` 相关参数都得到正确配置，否则会造成备份恢复失败。 - -## `gcp.secretName` - -+ 访问 GCP 时使用的凭据 -+ 默认："" -+ 该 Kubernetes Secret 中需要存储 GCP 的 Service Account 凭据，你可以参考 [Google Cloud Documentation](https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually) 来下载凭据文件，然后通过下面的命令创建 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic gcp-backup-secret -n --from-file=./credentials.json - ``` - -## `ceph.endpoint` - -+ Ceph 对象存储的 Endpoint -+ 默认："" -+ 用于访问 Ceph 对象存储 - -> **注意：** -> -> 一旦设置了 `ceph` 下的任何参数，备份和恢复就会使用 Ceph 对象存储进行数据存储。也就是说，假如要设置 `ceph` 下的参数，就需要保证所有 `ceph` 相关参数都得到正确配置，否则会造成备份恢复失败。 - -## `ceph.bucket` - -+ Ceph 对象存储的 bucket 名字 -+ 默认："" -+ 用于存储数据到 Ceph 对象存储上 - -## `ceph.secretName` - -+ 访问 Ceph 对象存储时使用的凭据 -+ 默认："" -+ 该 Kubernetes Secret 中需要存储访问 Ceph 时使用的 `access_key` 和 `secret_key`。可使用如下命令来创建这个 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic ceph-backup-secret -n --from-literal=access_key= --from-literal=secret_key= - ``` diff --git a/dev/tidb-in-kubernetes/reference/configuration/storage-class.md b/dev/tidb-in-kubernetes/reference/configuration/storage-class.md deleted file mode 100644 index e10497d57b61..000000000000 --- a/dev/tidb-in-kubernetes/reference/configuration/storage-class.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: Kubernetes 上的持久化存储类型配置 -category: reference -aliases: ['/docs-cn/dev/tidb-in-kubernetes/reference/configuration/local-pv/'] ---- - -# Kubernetes 上的持久化存储类型配置 - -TiDB 集群中 PD、TiKV、监控等组件以及 TiDB Binlog 和备份等工具都需要使用将数据持久化的存储。Kubernetes 上的数据持久化需要使用 [PersistentVolume (PV)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)。Kubernetes 提供多种[存储类型](https://kubernetes.io/docs/concepts/storage/volumes/)，主要分为两大类： - -* 网络存储 - - 存储介质不在当前节点，而是通过网络方式挂载到当前节点。一般有多副本冗余提供高可用保证，在节点出现故障时，对应网络存储可以再挂载到其它节点继续使用。 - -* 本地存储 - - 存储介质在当前节点，通常能提供比网络存储更低的延迟，但没有多副本冗余，一旦节点出故障，数据就有可能丢失。如果是 IDC 服务器，节点故障可以一定程度上对数据进行恢复，但公有云上使用本地盘的虚拟机在节点故障后，数据是**无法找回**的。 - -PV 一般由系统管理员或 volume provisioner 自动创建，PV 与 Pod 是通过 [PersistentVolumeClaim (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) 进行关联的。普通用户在使用 PV 时并不需要直接创建 PV，而是通过 PVC 来申请使用 PV，对应的 volume provisioner 根据 PVC 创建符合要求的 PV，并将 PVC 与该 PV 进行绑定。 - -> **警告：** -> -> 为了数据安全，任何情况下都不要直接删除 PV，除非对 volume provisioner 原理非常清楚。 - -## TiDB 集群推荐存储类型 - -TiKV 自身借助 Raft 实现了数据复制，出现节点故障后，PD 会自动进行数据调度补齐缺失的数据副本，同时 TiKV 要求存储有较低的读写延迟，所以生产环境强烈推荐使用本地 SSD 存储。 - -PD 同样借助 Raft 实现了数据复制，但作为存储集群元信息的数据库，并不是 IO 密集型应用，所以一般本地普通 SAS 盘或网络 SSD 存储（例如 AWS 上 gp2 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）就可以满足要求。 - -监控组件以及 TiDB Binlog、备份等工具，由于自身没有做多副本冗余，所以为保证可用性，推荐用网络存储。其中 TiDB Binlog 的 pump 和 drainer 组件属于 IO 密集型应用，需要较低的读写延迟，所以推荐用高性能的网络存储（例如 AWS 上的 io1 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）。 - -在利用 TiDB Operator 部署 TiDB 集群或者备份工具的时候，需要持久化存储的组件都可以通过 values.yaml 配置文件中对应的 `storageClassName` 设置存储类型。不设置时默认都使用 `local-storage`。 - -## 网络 PV 配置 - -Kubernetes 1.11 及以上的版本支持[网络 PV 的动态扩容](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/)，但用户需要为相应的 `StorageClass` 开启动态扩容支持。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl patch storageclass -p '{"allowVolumeExpansion": true}' -``` - -开启动态扩容后，通过下面方式对 PV 进行扩容： - -1. 修改 PVC 大小 - - 假设之前 PVC 大小是 10 Gi，现在需要扩容到 100 Gi - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pvc -n -p '{"spec": {"resources": {"requests": {"storage": "100Gi"}}}' - ``` - -2. 查看 PV 扩容成功 - - 扩容成功后，通过 `kubectl get pvc -n ` 显示的大小仍然是初始大小，但查看 PV 大小会显示已经扩容到预期的大小。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pv | grep - ``` - -## 本地 PV 配置 - -Kubernetes 当前支持静态分配的本地存储。可使用 [local-static-provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner) 项目中的 `local-volume-provisioner` 程序创建本地存储对象。创建流程如下： - -1. 参考 Kubernetes 提供的[操作文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md)，在集群节点中预分配本地存储。 - -2. 部署 `local-volume-provisioner` 程序。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml - ``` - - 通过下面命令查看 Pod 和 PV 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l app=local-volume-provisioner && \ - kubectl get pv | grep local-storage - ``` - - `local-volume-provisioner` 会为发现目录 (discovery directory) 下的每一个挂载点创建一个 PV。注意，在 GKE 上，默认只能创建大小为 375 GiB 的本地卷。 - -更多信息，可参阅 [Kubernetes 本地存储](https://kubernetes.io/docs/concepts/storage/volumes/#local)和 [local-static-provisioner 文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner#overview)。 - -### 最佳实践 - -- Local PV 的路径是本地存储卷的唯一标示符。为了保证唯一性并避免冲突，推荐使用设备的 UUID 来生成唯一的路径 -- 如果想要 IO 隔离，建议每个存储卷使用一块物理盘会比较恰当，在硬件层隔离 -- 如果想要容量隔离，建议每个存储卷一个分区或者每个存储卷使用一块物理盘来实现 - -更多信息，可参阅 local-static-provisioner 的[最佳实践文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/best-practices.md)。 - -### 示例 - -如果监控、TiDB Binlog、备份等组件都使用本地盘存储数据，可以挂载普通 SAS 盘，并分别创建不同的 `StorageClass` 供这些组件使用，具体操作如下： - -- 给监控数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/disks` 目录，后续创建 `local-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量。1 个目录会对应创建 1 个 PV。每个 TiDB 集群的监控数据会使用 1 个 PV。 - -- 给 TiDB Binlog 和备份数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/backup` 目录，后续创建 `backup-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量、每个集群内的 Pump 数量及备份方式。1 个目录会对应创建 1 个 PV。每个 Pump 会使用 1 个 PV，每个 drainer 会使用 1 个 PV，每次 [Ad-hoc 全量备份](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md#ad-hoc-全量备份)会使用 1 个 PV，所有[定时全量备份](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md#定时全量备份)会共用 1 个 PV。 - -- 给 PD 数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/sharedssd` 目录，后续创建 `shared-ssd-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量及每个集群内的 PD 数量。1 个目录会对应创建 1 个 PV。每个 PD 会使用一个 PV。 - -- 给 TiKV 数据使用的盘，可通过[普通挂载](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#use-a-whole-disk-as-a-filesystem-pv)方式将盘挂载到 `/mnt/ssd` 目录，后续创建 `ssd-storage` `StorageClass`。 - -盘挂载完成后，需要根据上述磁盘挂载情况修改 [`local-volume-provisioner` yaml 文件](https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml)，配置发现目录并创建必要的 `StorageClass`。以下是根据上述挂载修改的 yaml 文件示例： - -``` -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "local-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "ssd-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "shared-ssd-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "backup-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: local-provisioner-config - namespace: kube-system -data: - nodeLabelsForPV: | - - kubernetes.io/hostname - storageClassMap: | - shared-ssd-storage: - hostDir: /mnt/sharedssd - mountDir: /mnt/sharedssd - ssd-storage: - hostDir: /mnt/ssd - mountDir: /mnt/ssd - local-storage: - hostDir: /mnt/disks - mountDir: /mnt/disks - backup-storage: - hostDir: /mnt/backup - mountDir: /mnt/backup ---- - -...... - - volumeMounts: - - ...... - - - mountPath: /mnt/ssd - name: local-ssd - mountPropagation: "HostToContainer" - - mountPath: /mnt/sharedssd - name: local-sharedssd - mountPropagation: "HostToContainer" - - mountPath: /mnt/disks - name: local-disks - mountPropagation: "HostToContainer" - - mountPath: /mnt/backup - name: local-backup - mountPropagation: "HostToContainer" - volumes: - - ...... - - - name: local-ssd - hostPath: - path: /mnt/ssd - - name: local-sharedssd - hostPath: - path: /mnt/sharedssd - - name: local-disks - hostPath: - path: /mnt/disks - - name: local-backup - hostPath: - path: /mnt/backup -...... - -``` - -最后通过 `kubectl apply` 命令部署 `local-volume-provisioner` 程序。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml -``` - -后续创建 TiDB 集群或备份等组件的时候，再配置相应的 `StorageClass` 供其使用。 - -## 数据安全 - -一般情况下 PVC 在使用完删除后，与其绑定的 PV 会被 provisioner 清理回收再放入资源池中被调度使用。为避免数据意外丢失，可在全局配置 `StorageClass` 的回收策略 (reclaim policy) 为 `Retain` 或者只将某个 PV 的回收策略修改为 `Retain`。`Retain` 模式下，PV 不会自动被回收。 - -* 全局配置 - - `StorageClass` 的回收策略一旦创建就不能再修改，所以只能在创建时进行设置。如果创建时没有设置，可以再创建相同 provisioner 的 `StorageClass`，例如 GKE 上默认的 pd 类型的 `StorageClass` 默认保留策略是 `Delete`，可以再创建一个名为 `pd-standard` 的保留策略是 `Retain` 的存储类型，并在创建 TiDB 集群时将相应组件的 `storageClassName` 修改为 `pd-standard`。 - - {{< copyable "" >}} - - ```yaml - apiVersion: storage.k8s.io/v1 - kind: StorageClass - metadata: - name: pd-standard - parameters: - type: pd-standard - provisioner: kubernetes.io/gce-pd - reclaimPolicy: Retain - volumeBindingMode: Immediate - ``` - -* 配置单个 PV - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' - ``` - -> **注意：** -> -> TiDB Operator 默认会自动将 PD 和 TiKV 的 PV 保留策略修改为 `Retain` 以确保数据安全。 - -PV 保留策略是 `Retain` 时，如果确认某个 PV 的数据可以被删除，需要通过下面的操作来删除 PV 以及对应的数据： - -1. 删除 PV 对应的 PVC 对象： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete pvc --namespace= - ``` - -2. 设置 PV 的保留策略为 `Delete`，PV 会被自动删除并回收： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - ``` - -要了解更多关于 PV 的保留策略可参考[修改 PV 保留策略](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/)。 diff --git a/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md b/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md deleted file mode 100644 index 1ef12d1999eb..000000000000 --- a/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群配置 -category: reference ---- - -# Kubernetes 上的 TiDB 集群配置 - -本文介绍 Kubernetes 上 TiDB 集群的配置参数、资源配置，以及容灾配置。 - -## 配置参数 - -TiDB Operator 使用 Helm 部署和管理 TiDB 集群。通过 Helm 获取的配置文件默认提供了基本的配置，通过这个基本配置，可以快速启动一个 TiDB 集群。但是如果用户需要特殊配置或是用于生产环境，则需要根据以下配置参数列表手动配置对应的配置项。 - -> **注意：** -> -> 下文用 `values.yaml` 指代要修改的 TiDB 集群配置文件。 - -| 参数名 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `rbac.create` | 是否启用 Kubernetes 的 RBAC | `true` | -| `clusterName` | TiDB 集群名，默认不设置该变量，`tidb-cluster` 会直接用执行安装时的 `ReleaseName` 代替 | `nil` | -| `extraLabels` | 添加额外的 labels 到 `TidbCluster` 对象 (CRD) 上，参考：[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) | `{}` | -| `schedulerName` | TiDB 集群使用的调度器 | `tidb-scheduler` | -| `timezone` | TiDB 集群默认时区 | `UTC` | -| `pvReclaimPolicy` | TiDB 集群使用的 PV (Persistent Volume)的 reclaim policy | `Retain` | -| `services[0].name` | TiDB 集群对外暴露服务的名字 | `nil` | -| `services[0].type` | TiDB 集群对外暴露服务的类型，(从 `ClusterIP`、`NodePort`、`LoadBalancer` 中选择) | `nil` | -| `discovery.image` | TiDB 集群 PD 服务发现组件的镜像，该组件用于在 PD 集群第一次启动时，为各个 PD 实例提供服务发现功能以协调启动顺序 | `pingcap/tidb-operator:v1.0.0-beta.3` | -| `discovery.imagePullPolicy` | PD 服务发现组件镜像的拉取策略 | `IfNotPresent` | -| `discovery.resources.limits.cpu` | PD 服务发现组件的 CPU 资源限额 | `250m` | -| `discovery.resources.limits.memory` | PD 服务发现组件的内存资源限额 | `150Mi` | -| `discovery.resources.requests.cpu` | PD 服务发现组件的 CPU 资源请求 | `80m` | -| `discovery.resources.requests.memory` | PD 服务发现组件的内存资源请求 | `50Mi` | -| `enableConfigMapRollout` | 是否开启 TiDB 集群自动滚动更新。如果启用，则 TiDB 集群的 ConfigMap 变更时，TiDB 集群自动更新对应组件。该配置只在 tidb-operator v1.0 及以上版本才支持 | `false` | -| `pd.config` | 配置文件格式的 PD 的配置，请参考 [`pd/conf/config.toml`](https://github.com/pingcap/pd/blob/master/conf/config.toml) 查看默认 PD 配置文件（选择对应 PD 版本的 tag），可以参考 [PD 配置文件描述](/dev/reference/configuration/pd-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置** | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
`[replication]`
`location-labels = ["region", "zone", "rack", "host"]`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"`
    `[replication]`
    `location-labels = ["region", "zone", "rack", "host"]` | -| `pd.replicas` | PD 的 Pod 数 | `3` | -| `pd.image` | PD 镜像 | `pingcap/pd:v3.0.0-rc.1` | -| `pd.imagePullPolicy` | PD 镜像的拉取策略 | `IfNotPresent` | -| `pd.logLevel` | PD 日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[log]`
`level = "info"` | `info` | -| `pd.storageClassName` | PD 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `pd.maxStoreDownTime` | `pd.maxStoreDownTime` 指一个 store 节点断开连接多长时间后状态会被标记为 `down`，当状态变为 `down` 后，store 节点开始迁移数据到其它 store 节点
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[schedule]`
`max-store-down-time = "30m"` | `30m` | -| `pd.maxReplicas` | `pd.maxReplicas` 是 TiDB 集群的数据的副本数
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[replication]`
`max-replicas = 3` | `3` | -| `pd.resources.limits.cpu` | 每个 PD Pod 的 CPU 资源限额 | `nil` | -| `pd.resources.limits.memory` | 每个 PD Pod 的内存资源限额 | `nil` | -| `pd.resources.limits.storage` | 每个 PD Pod 的存储容量限额 | `nil` | -| `pd.resources.requests.cpu` | 每个 PD Pod 的 CPU 资源请求 | `nil` | -| `pd.resources.requests.memory` | 每个 PD Pod 的内存资源请求 | `nil` | -| `pd.resources.requests.storage` | 每个 PD Pod 的存储容量请求 | `1Gi` | -| `pd.affinity` | `pd.affinity` 定义 PD 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `pd.nodeSelector` | `pd.nodeSelector` 确保 PD Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `pd.tolerations` | `pd.tolerations` 应用于 PD Pods，允许 PD Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `pd.annotations` | 为 PD Pods 添加特定的 `annotations` | `{}` | -| `tikv.config` | 配置文件格式的 TiKV 的配置，请参考 [`tikv/etc/config-template.toml`](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 查看默认 TiKV 配置文件（选择对应 TiKV 版本的 tag），可以参考 [TiKV 配置文件描述](https://pingcap.com/docs-cn/v3.0/reference/configuration/tikv-server/configuration-file/)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置**

以下两个配置项需要显式配置：

`[storage.block-cache]`
  `shared = true`
  `capacity = "1GB"`
推荐设置：`capacity` 设置为 `tikv.resources.limits.memory` 的 50%

`[readpool.coprocessor]`
  `high-concurrency = 8`
  `normal-concurrency = 8`
  `low-concurrency = 8`
推荐设置：设置为 `tikv.resources.limits.cpu` 的 80%| TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`log-level = "info"`
配置示例：
  `config:` \|
    `log-level = "info"` | -| `tikv.replicas` | TiKV 的 Pod 数 | `3` | -| `tikv.image` | TiKV 的镜像 | `pingcap/tikv:v3.0.0-rc.1` | -| `tikv.imagePullPolicy` | TiKV 镜像的拉取策略 | `IfNotPresent` | -| `tikv.logLevel` | TiKV 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`log-level = "info"` | `info` | -| `tikv.storageClassName` | TiKV 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `tikv.syncLog` | syncLog 指是否启用 raft 日志同步功能，启用该功能能保证在断电时数据不丢失
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[raftstore]`
`sync-log = true` | `true` | -| `tikv.grpcConcurrency` | 配置 gRPC server 线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[server]`
`grpc-concurrency = 4` | `4` | -| `tikv.resources.limits.cpu` | 每个 TiKV Pod 的 CPU 资源限额 | `nil` | -| `tikv.resources.limits.memory` | 每个 TiKV Pod 的内存资源限额 | `nil` | -| `tikv.resources.limits.storage` | 每个 TiKV Pod 的存储容量限额 | `nil` | -| `tikv.resources.requests.cpu` | 每个 TiKV Pod 的 CPU 资源请求 | `nil` | -| `tikv.resources.requests.memory` | 每个 TiKV Pod 的内存资源请求 | `nil` | -| `tikv.resources.requests.storage` | 每个 TiKV Pod 的存储容量请求 | `10Gi` | -| `tikv.affinity` | `tikv.affinity` 定义 TiKV 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `tikv.nodeSelector` | `tikv.nodeSelector`确保 TiKV Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tikv.tolerations` | `tikv.tolerations` 应用于 TiKV Pods，允许 TiKV Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `tikv.annotations` | 为 TiKV Pods 添加特定的 `annotations` | `{}` | -| `tikv.defaultcfBlockCacheSize` | 指定 block 缓存大小，block 缓存用于缓存未压缩的 block，较大的 block 缓存设置可以加快读取速度。一般推荐设置为 `tikv.resources.limits.memory` 的 30%-50%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.defaultcf]`
`block-cache-size = "1GB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `1GB` | -| `tikv.writecfBlockCacheSize` | 指定 writecf 的 block 缓存大小，一般推荐设置为 `tikv.resources.limits.memory` 的 10%-30%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.writecf]`
`block-cache-size = "256MB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `256MB` | -| `tikv.readpoolStorageConcurrency` | TiKV 存储的高优先级/普通优先级/低优先级操作的线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.storage]`
`high-concurrency = 4`
`normal-concurrency = 4`
`low-concurrency = 4` | `4` | -| `tikv.readpoolCoprocessorConcurrency` | 一般如果 `tikv.resources.limits.cpu` > 8，则 `tikv.readpoolCoprocessorConcurrency` 设置为`tikv.resources.limits.cpu` * 0.8
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.coprocessor]`
`high-concurrency = 8`
`normal-concurrency = 8`
`low-concurrency = 8` | `8` | -| `tikv.storageSchedulerWorkerPoolSize` | TiKV 调度程序的工作池大小，应在重写情况下增加，同时应小于总 CPU 核心
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[storage]`
`scheduler-worker-pool-size = 4` | `4` | -| `tidb.config` | 配置文件格式的 TiDB 的配置，请参考[配置文件](https://github.com/pingcap/tidb/blob/master/config/config.toml.example)查看默认 TiDB 配置文件（选择对应 TiDB 版本的 tag），可以参考 [TiDB 配置文件描述](/dev/reference/configuration/tidb-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本）。这里只需要**按照配置文件中的格式修改配置**。

以下配置项需要显式配置：

`[performance]`
  `max-procs = 0`
推荐设置：`max-procs` 设置为 `tidb.resources.limits.cpu` 对应的核心数 | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"` | -| `tidb.replicas` | TiDB 的 Pod 数 | `2` | -| `tidb.image` | TiDB 的镜像 | `pingcap/tidb:v3.0.0-rc.1` | -| `tidb.imagePullPolicy` | TiDB 镜像的拉取策略 | `IfNotPresent` | -| `tidb.logLevel` | TiDB 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[log]`
`level = "info"` | `info` | -| `tidb.resources.limits.cpu` | 每个 TiDB Pod 的 CPU 资源限额 | `nil` | -| `tidb.resources.limits.memory` | 每个 TiDB Pod 的内存资源限额 | `nil` | -| `tidb.resources.requests.cpu` | 每个 TiDB Pod 的 CPU 资源请求 | `nil` | -| `tidb.resources.requests.memory` | 每个 TiDB Pod 的内存资源请求 | `nil` | -| `tidb.passwordSecretName`| 存放 TiDB 用户名及密码的 Secret 的名字，该 Secret 可以使用以下命令创建机密：`kubectl create secret generic tidb secret--from literal=root=--namespace=`，如果没有设置，则 TiDB 根密码为空 | `nil` | -| `tidb.initSql`| 在 TiDB 集群启动成功后，会执行的初始化脚本 | `nil` | -| `tidb.affinity` | `tidb.affinity` 定义 TiDB 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `tidb.nodeSelector` | `tidb.nodeSelector`确保 TiDB Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tidb.tolerations` | `tidb.tolerations` 应用于 TiDB Pods，允许 TiDB Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `tidb.annotations` | 为 TiDB Pods 添加特定的 `annotations` | `{}` | -| `tidb.maxFailoverCount` | TiDB 最大的故障转移数量，假设为 3 即最多支持同时 3 个 TiDB 实例故障转移 | `3` | -| `tidb.service.type` | TiDB 服务对外暴露类型 | `NodePort` | -| `tidb.service.externalTrafficPolicy` | 表示此服务是否希望将外部流量路由到节点本地或集群范围的端点。有两个可用选项：`Cluster`（默认）和 `Local`。`Cluster` 隐藏了客户端源 IP，可能导致流量需要二次跳转到另一个节点，但具有良好的整体负载分布。`Local` 保留客户端源 IP 并避免 LoadBalancer 和 NodePort 类型服务流量的第二次跳转，但存在潜在的不均衡流量传播风险。详细参考：[外部负载均衡器](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) | `nil` | -| `tidb.service.loadBalancerIP` | 指定 tidb 负载均衡 IP，某些云提供程序允许您指定loadBalancerIP。在这些情况下，将使用用户指定的loadBalancerIP创建负载平衡器。如果未指定loadBalancerIP字段，则将使用临时IP地址设置loadBalancer。如果指定loadBalancerIP但云提供程序不支持该功能，则将忽略您设置的loadbalancerIP字段 | `nil` | -| `tidb.service.mysqlNodePort` | TiDB 服务暴露的 mysql NodePort 端口 | | -| `tidb.service.exposeStatus` | TiDB 服务是否暴露状态端口 | `true` | -| `tidb.service.statusNodePort` | 指定 TiDB 服务的状态端口暴露的 `NodePort` | | -| `tidb.separateSlowLog` | 是否以 sidecar 方式运行独立容器输出 TiDB 的 SlowLog | 如果 TiDB Operator 版本 <= v1.0.0-beta.3，默认值为 `false`
如果 TiDB Operator 版本 > v1.0.0-beta.3，默认值为 `true` | -| `tidb.slowLogTailer.image` | TiDB 的 slowLogTailer 的镜像，slowLogTailer 是一个 sidecar 类型的容器，用于输出 TiDB 的 SlowLog，该配置仅在 `tidb.separateSlowLog`=`true` 时生效 | `busybox:1.26.2` | -| `tidb.slowLogTailer.resources.limits.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源限额 | `100m` | -| `tidb.slowLogTailer.resources.limits.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源限额 | `50Mi` | -| `tidb.slowLogTailer.resources.requests.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源请求 | `20m` | -| `tidb.slowLogTailer.resources.requests.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源请求 | `5Mi` | -| `tidb.plugin.enable` | 是否启用 TiDB 插件功能 | `false` | -| `tidb.plugin.directory` | 指定 TiDB 插件所在的目录 | `/plugins` | -| `tidb.plugin.list` | 指定 TiDB 加载的插件列表，plugin ID 命名规则：插件名-版本，例如：'conn_limit-1' | `[]` | -| `tidb.preparedPlanCacheEnabled` | 是否启用 TiDB 的 prepared plan 缓存
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`enabled = false` | `false` | -| `tidb.preparedPlanCacheCapacity` | TiDB 的 prepared plan 缓存数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`capacity = 100` | `100` | -| `tidb.txnLocalLatchesEnabled` | 是否启用事务内存锁，当本地事务冲突比较多时建议开启
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`enabled = false` | `false` | -| `tidb.txnLocalLatchesCapacity` | 事务内存锁的容量，Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`capacity = 10240000` | `10240000` | -| `tidb.tokenLimit` | TiDB 并发执行会话的限制
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`token-limit = 1000` | `1000` | -| `tidb.memQuotaQuery` | TiDB 查询的内存限额，默认 32GB
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`mem-quota-query = 34359738368` | `34359738368` | -| `tidb.checkMb4ValueInUtf8` | 用于控制当字符集为 utf8 时是否检查 mb4 字符
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`check-mb4-value-in-utf8 = true` | `true` | -| `tidb.treatOldVersionUtf8AsUtf8mb4` | 用于升级兼容性。设置为 `true` 将把旧版本的表/列的 `utf8` 字符集视为 `utf8mb4` 字符集
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`treat-old-version-utf8-as-utf8mb4 = true` | `true` | -| `tidb.lease` | `tidb.lease`是 TiDB Schema lease 的期限，对其更改是非常危险的，除非你明确知道可能产生的结果，否则不建议更改。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`lease = "45s"` | `45s` | -| `tidb.maxProcs` | 最大可使用的 CPU 核数，0 代表机器/Pod 上的 CPU 数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[performance]`
`max-procs = 0` | `0` | - -## 资源配置说明 - -部署前需要根据实际情况和需求，为 TiDB 集群各个组件配置资源，其中 PD、TiKV、TiDB 是 TiDB 集群的核心服务组件，在生产环境下它们的资源配置还需要按组件要求指定，具体参考：[资源配置推荐](/dev/how-to/deploy/hardware-recommendations.md)。 - -为了保证 TiDB 集群的组件在 Kubernetes 中合理的调度和稳定的运行，建议为其设置 Guaranteed 级别的 QoS，通过在配置资源时让 limits 等于 requests 来实现, 具体参考：[配置 QoS](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/)。 - -如果使用 NUMA 架构的 CPU，为了获得更好的性能，需要在节点上开启 `Static` 的 CPU 管理策略。为了 TiDB 集群组件能独占相应的 CPU 资源，除了为其设置上述 Guaranteed 级别的 QoS 外，还需要保证 CPU 的配额必须是大于或等于 1 的整数。具体参考: [CPU 管理策略](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies)。 - -## 容灾配置说明 - -TiDB 是分布式数据库，它的容灾需要做到在任一个物理拓扑节点发生故障时，不仅服务不受影响，还要保证数据也是完整和可用。下面分别具体说明这两种容灾的配置。 - -### TiDB 服务的容灾 - -TiDB 服务容灾本质上基于 Kubernetes 的调度功能来实现的，为了优化调度，TiDB Operator 提供了自定义的调度器，该调度器通过指定的调度算法能在 host 层面，保证 TiDB 服务的容灾，而且目前 TiDB Cluster 使用该调度器作为默认调度器，设置项是上述列表中的 `schedulerName` 配置项。 - -其它层面的容灾（例如 rack，zone，region）是通过 Affinity 的 `PodAntiAffinity` 来保证，通过 `PodAntiAffinity` 能尽量避免同一组件的不同实例部署到同一个物理拓扑节点上，从而达到容灾的目的，Affinity 的使用参考：[Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity)。 - -下面是一个典型的容灾设置例子： - -{{< copyable "shell-regular" >}} - -```shell -affinity: - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - # this term works when the nodes have the label named region - - weight: 10 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "region" - namespaces: - - - # this term works when the nodes have the label named zone - - weight: 20 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "zone" - namespaces: - - - # this term works when the nodes have the label named rack - - weight: 40 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "rack" - namespaces: - - - # this term works when the nodes have the label named kubernetes.io/hostname - - weight: 80 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "kubernetes.io/hostname" - namespaces: - - -``` - -### 数据的容灾 - -在开始数据容灾配置前，首先请阅读[集群拓扑信息配置](/dev/how-to/deploy/geographic-redundancy/location-awareness.md)。该文档描述了 TiDB 集群数据容灾的实现原理。 - -在 Kubernetes 上支持数据容灾的功能，需要如下操作： - -* 为 PD 设置拓扑位置 Label 集合 - - > **注意：** - > - > 除 `kubernetes.io/hostname` 外，目前 PD 暂不支持名字中带 `/` 的 Label。 - - 用 Kubernetes 集群 Node 节点上描述拓扑位置的 Label 集合替换 `pd.config` 配置项中里的 `location-labels` 信息。 - -* 为 TiKV 节点设置所在的 Node 节点的拓扑信息 - - TiDB Operator 会自动为 TiKV 获取其所在 Node 节点的拓扑信息，并调用 PD 接口将这些信息设置为 TiKV 的 store labels 信息，这样 TiDB 集群就能基于这些信息来调度数据副本。 - - 如果当前 Kubernetes 集群的 Node 节点没有表示拓扑位置的 Label，或者已有的拓扑 Label 名字中带有 `/`，可以通过下面的命令手动给 Node 增加标签： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl label node region= zone= rack= kubernetes.io/hostname= - ``` - - 其中 `region`、`zone`、`rack`、`kubernetes.io/hostname` 只是举例，要添加的 Label 名字和数量可以任意定义，只要符合规范且和 `pd.config` 里的 `location-labels` 设置的 Labels 保持一致即可。 diff --git a/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md b/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md deleted file mode 100644 index 98544ee5a7b5..000000000000 --- a/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Kubernetes 上的 TiDB Binlog Drainer 配置 -summary: 了解 Kubernetes 上的 TiDB Binlog Drainer 配置 -category: reference ---- - -# Kubernetes 上的 TiDB Binlog Drainer 配置 - -本文档介绍 Kubernetes 上 TiDB Binlog drainer 的配置参数。 - -## 配置参数 - -下表包含所有用于 `tidb-drainer` chart 的配置参数。关于如何配置这些参数，可参阅[使用 Helm](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm)。 - -| 参数 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `clusterName` | 源 TiDB 集群的名称 | `demo` | -| `clusterVersion` | 源 TiDB 集群的版本 | `v3.0.1` | -| `baseImage` | TiDB Binlog 的基础镜像 | `pingcap/tidb-binlog` | -| `imagePullPolicy` | 镜像的拉取策略 | `IfNotPresent` | -| `logLevel` | drainer 进程的日志级别 | `info` | -| `storageClassName` | drainer 所使用的 `storageClass`。`storageClassName` 是 Kubernetes 集群提供的一种存储，可以映射到服务质量级别、备份策略或集群管理员确定的任何策略。详情可参阅 [storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `storage` | drainer Pod 的存储限制。请注意，如果 `db-type` 设为 `pd`，则应将本参数值设得大一些 | `10Gi` | -| `disableDetect` | 决定是否禁用事故检测 | `false` | -| `initialCommitTs` | 如果 drainer 没有断点，则用于初始化断点 | `0` | -| `config` | 传递到 drainer 的配置文件。详情可参阅 [drainer.toml](https://github.com/pingcap/tidb-binlog/blob/master/cmd/drainer/drainer.toml) |（见下文）| -| `resources` | drainer Pod 的资源限制和请求 | `{}` | -| `nodeSelector` | 确保 drainer Pod 仅被调度到具有特定键值对作为标签的节点上。详情可参阅 [nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tolerations` | 适用于 drainer Pod，允许将 Pod 调度到有指定 taint 的节点上。详情可参阅 [taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `affinity` | 定义 drainer Pod 的调度策略和首选项。详情可参阅 [affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | - -`config` 的默认值为： - -```toml -detect-interval = 10 -compressor = "" -[syncer] -worker-count = 16 -disable-dispatch = false -ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" -safe-mode = false -txn-batch = 20 -db-type = "file" -[syncer.to] -dir = "/data/pb" -``` diff --git a/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md b/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md deleted file mode 100644 index edbdc343098d..000000000000 --- a/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 工具指南 -category: reference ---- - -# Kubernetes 上的 TiDB 工具指南 - -Kubernetes 上的 TiDB 运维管理需要使用一些开源工具。同时，在 Kubernetes 上使用 TiDB 生态工具时，也有特殊的操作要求。本文档详细描述 Kubernetes 上的 TiDB 相关的工具及其使用方法。 - -## 在 Kubernetes 上使用 PD Control - -[PD Control](/dev/reference/tools/pd-control.md) 是 PD 的命令行工具，在使用 PD Control 操作 Kubernetes 上的 TiDB 集群时，需要先使用 `kubectl port-forward` 打开本地到 PD 服务的连接： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & -``` - -执行上述命令后，就可以通过 `127.0.0.1:2379` 访问到 PD 服务，从而直接使用 `pd-ctl` 命令的默认参数执行操作，如： - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -d config show -``` - -假如你本地的 2379 被占据，则需要选择其它端口： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & -``` - -此时，需要为 `pd-ctl` 命令显式指定 PD 端口： - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -u 127.0.0.1: -d config show -``` - -## 在 Kubernetes 上使用 TiKV Control - -[TiKV Control](/dev/reference/tools/tikv-control.md) 是 TiKV 的命令行工具。在使用 TiKV Control 操作 Kubernetes 上的 TiDB 集群时，针对 TiKV Control 的不同操作模式，有不同的操作步骤。 - -* **远程模式**：此模式下 `tikv-ctl` 命令需要通过网络访问 TiKV 服务或 PD 服务，因此需要先使用 `kubectl port-forward` 打开本地到 PD 服务以及目标 TiKV 节点的连接： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n 20160:20160 &>/tmp/portforward-tikv.log & - ``` - - 打开连接后，即可通过本地的对应端口访问 PD 服务和 TiKV 节点： - - {{< copyable "shell-regular" >}} - - ```shell - $ tikv-ctl --host 127.0.0.1:20160 - ``` - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --pd 127.0.0.1:2379 compact-cluster - ``` - -* **本地模式**：本地模式需要访问 TiKV 的数据文件，并且需要停止正在运行的 TiKV 实例。需要先使用[诊断模式](/dev/tidb-in-kubernetes/troubleshoot.md#诊断模式)关闭 TiKV 实例自动重启，关闭 TiKV 进程，再使用 `tkctl debug` 命令在目标 TiKV Pod 中启动一个包含 `tikv-ctl` 可执行文件的新容器来执行操作，步骤如下： - - 1. 进入诊断模式： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl annotate pod -n runmode=debug - ``` - - 2. 关闭 TiKV 进程： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -n -c tikv -- kill -s TERM 1 - ``` - - 3. 启动 debug 容器： - - {{< copyable "shell-regular" >}} - - ```shell - tkctl debug -c tikv - ``` - - 4. 开始使用 `tikv-ctl` 的本地模式，需要注意的是 `tikv` 容器的根文件系统在 `/proc/1/root` 下，因此执行命令时也需要调整数据目录的路径： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --db /path/to/tikv/db size -r 2 - ``` - - Kubernetes 上 TiKV 实例在 debug 容器中的的默认 db 路径是 `/proc/1/root/var/lib/tikv/db size -r 2` - -## 在 Kubernetes 上使用 TiDB Control - -[TiDB Control](/dev/reference/tools/tidb-control.md) 是 TiDB 的命令行工具，使用 TiDB Control 时，需要从本地访问 TiDB 节点和 PD 服务，因此建议使用 `kubectl port-forward` 打开到集群中 TiDB 节点和 PD 服务的连接： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & -``` - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n 10080:10080 &>/tmp/portforward-tidb.log & -``` - -接下来便可开始使用 `tidb-ctl` 命令： - -{{< copyable "shell-regular" >}} - -```shell -tidb-ctl schema in mysql -``` - -## 使用 Helm - -[Helm](https://helm.sh/) 是一个 Kubernetes 的包管理工具，你可以参考 [Helm 官方文档](https://github.com/helm/helm#install) 安装 Helm，步骤如下： - -1. 安装 Helm 客户端 - - {{< copyable "shell-regular" >}} - - ```shell - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果使用 macOS，可以通过 homebrew 安装 Helm：`brew install kubernetes-helm`。 - -2. 安装 Helm 服务端 - - {{< copyable "shell-regular" >}} - - 在集群中应用 helm 服务端组件 `tiller` 所需的 `RBAC` 规则并安装 `tiller`： - - ```shell - kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/tiller-rbac.yaml && \ - helm init --service-account=tiller --upgrade - ``` - - 通过下面命令确认 `tiller` Pod 进入 running 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l name=tiller - ``` - - 如果 Kubernetes 集群没有启用 `RBAC`，那么可以直接使用下列命令安装 `tiller`： - - {{< copyable "shell-regular" >}} - - ```shell - helm init --upgrade - ``` - -Kubernetes 应用在 helm 中被打包为 chart。PingCAP 针对 Kubernetes 上的 TiDB 部署运维提供了三个 Helm chart： - -* `tidb-operator`：用于部署 TiDB Operator； -* `tidb-cluster`：用于部署 TiDB 集群； -* `tidb-backup`：用于 TiDB 集群备份恢复； - -这些 chart 都托管在 PingCAP 维护的 helm chart 仓库 `https://charts.pingcap.org/` 中，你可以通过下面的命令添加该仓库： - -{{< copyable "shell-regular" >}} - -```shell -helm repo add pingcap https://charts.pingcap.org/ -``` - -添加完成后，可以使用 `helm search` 搜索 PingCAP 提供的 chart： - -{{< copyable "shell-regular" >}} - -```shell -helm search pingcap -l -``` - -``` -NAME CHART VERSION APP VERSION DESCRIPTION -pingcap/tidb-backup v1.0.0 A Helm chart for TiDB Backup or Restore -pingcap/tidb-cluster v1.0.0 A Helm chart for TiDB Cluster -pingcap/tidb-operator v1.0.0 tidb-operator Helm chart for Kubernetes -``` - -当新版本的 chart 发布后，你可以使用 `helm repo update` 命令更新本地对于仓库的缓存： - -{{< copyable "shell-regular" >}} - -``` -helm repo update -``` - -Helm 的常用操作有部署（`helm install`）、升级（`helm upgrade`)、销毁（`helm del`)、查询（`helm ls`）。Helm chart 往往都有很多可配置参数，通过命令行进行配置比较繁琐，因此推荐使用 YAML 文件的形式来编写这些配置项，基于 Helm 社区约定俗称的命名方式，我们在文档中将用于配置 chart 的 YAML 文件称为 `values.yaml` 文件。 - -执行部署、升级、销毁等操作前，可以使用 `helm ls` 查看集群中已部署的应用： - -{{< copyable "shell-regular" >}} - -```shell -helm ls -``` - -在执行部署和升级操作时，必须指定使用的 chart 名字（`chart-name`）和部署后的应用名（`release-name`），还可以指定一个或多个 `values.yaml` 文件来配置 chart。此外，假如对 chart 有特定的版本需求，则需要通过 `--version` 参数指定 `chart-version` (默认为最新的 GA 版本）。命令形式如下： - -* 执行安装： - - {{< copyable "shell-regular" >}} - - ```shell - helm install --name= --namespace= --version= -f - ``` - -* 执行升级（升级可以是修改 `chart-version` 升级到新版本的 chart，也可以是修改 `values.yaml` 文件更新应用配置）： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade --version= -f - ``` - -最后，假如要删除 helm 部署的应用，可以执行： - -{{< copyable "shell-regular" >}} - -```shell -helm del --purge -``` - -更多 helm 的相关文档，请参考 [Helm 官方文档](https://helm.sh/docs/)。 - -## 使用 Terraform - -[Terraform](https://www.terraform.io/) 是一个基础设施即代码（Infrastructure as Code）管理工具。它允许用户使用声明式的风格描述自己的基础设施，并针对描述生成执行计划来创建或调整真实世界的计算资源。Kubernetes 上的 TiDB 使用 Terraform 来在公有云上创建和管理 TiDB 集群。 - -你可以参考 [Terraform 官方文档](https://www.terraform.io/downloads.html) 来安装 Terraform。 diff --git a/dev/tidb-in-kubernetes/scale-in-kubernetes.md b/dev/tidb-in-kubernetes/scale-in-kubernetes.md deleted file mode 100644 index 162d0a6f9db3..000000000000 --- a/dev/tidb-in-kubernetes/scale-in-kubernetes.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群扩缩容 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群扩缩容 - -本文介绍 TiDB 在 Kubernetes 中如何进行水平扩缩容和垂直扩缩容。 - -## 水平扩缩容 - -TiDB 水平扩缩容操作指的是通过增加或减少节点的数量，来达到集群扩缩容的目的。扩缩容 TiDB 集群时，会按照填入的 replicas 值，对 PD、TiKV、TiDB 进行顺序扩缩容操作。扩容操作按照节点编号由小到大增加节点，缩容操作按照节点编号由大到小删除节点。 - -### 水平扩缩容操作 - -1. 修改集群的 `value.yaml` 文件中的 `pd.replicas`、`tidb.replicas`、`tikv.replicas` 至期望值。 - -2. 执行 `helm upgrade` 命令进行扩缩容： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看集群水平扩缩容状态： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有组件的 Pod 数量都达到了预设值，并且都进入 `Running` 状态后，水平扩缩容完成。 - -> **注意：** -> -> - PD、TiKV 组件在滚动升级的过程中不会触发扩缩容操作。 -> - TiKV 组件在缩容过程中会调用 PD 接口将对应 TiKV 标记为下线，然后将其上数据迁移到其它 TiKV 节点，在数据迁移期间 TiKV Pod 依然是 `Running` 状态，数据迁移完成后对应 Pod 才会被删除，缩容时间与待缩容的 TiKV 上的数据量有关，可以通过 `kubectl get tidbcluster -n -o json | jq '.status.tikv.stores'` 查看 TiKV 是否处于下线 `Offline` 状态。 -> - PD、TiKV 组件在缩容过程中被删除的节点的 PVC 会保留，并且由于 PV 的 `Reclaim Policy` 设置为 `Retain`，即使 PVC 被删除，数据依然可以找回。 -> - TiKV 组件不支持在缩容过程中进行扩容操作，强制执行此操作可能导致集群状态异常。假如异常已经发生，可以参考 [TiKV Store 异常进入 Tombstone 状态](/dev/tidb-in-kubernetes/troubleshoot.md#tikv-store-异常进入-tombstone-状态) 进行解决。 - -## 垂直扩缩容 - -垂直扩缩容操作指的是通过增加或减少节点的资源限制，来达到集群扩缩容的目的。垂直扩缩容本质上是节点滚动升级的过程。 - -### 垂直扩缩容操作 - -1. 修改 `values.yaml` 文件中的 `tidb.resources`、`tikv.resources`、`pd.resources` 至期望值。 - -2. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，垂直扩缩容完成。 - -> **注意：** -> -> - 如果在垂直扩容时修改了资源的 `requests` 字段，由于 PD、TiKV 使用了 `Local PV`，升级后还需要调度回原节点，如果原节点资源不够，则会导致 Pod 一直处于 `Pending` 状态而影响服务。 -> - TiDB 作为一个可水平扩展的数据库，推荐通过增加节点个数发挥 TiDB 集群可水平扩展的优势，而不是类似传统数据库升级节点硬件配置来实现垂直扩容。 diff --git a/dev/tidb-in-kubernetes/tidb-operator-overview.md b/dev/tidb-in-kubernetes/tidb-operator-overview.md deleted file mode 100644 index f07bb49ee840..000000000000 --- a/dev/tidb-in-kubernetes/tidb-operator-overview.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: TiDB Operator 简介 -category: reference ---- - -# TiDB Operator 简介 - -TiDB Operator 是 Kubernetes 上的 TiDB 集群自动运维系统，提供包括部署、升级、扩缩容、备份恢复、配置变更的 TiDB 全生命周期管理。借助 TiDB Operator，TiDB 可以无缝运行在公有云或私有部署的 Kubernetes 集群上。 - -> **注意：** -> -> 每个 Kubernetes 集群中只能部署一个 TiDB Operator。 - -## TiDB Operator 整体架构 - -![TiDB Operator Overview](/media/tidb-operator-overview.png) - -其中，`TidbCluster` 是由 CRD（`CustomResourceDefinition`）定义的自定义资源，用于描述用户期望的 TiDB 集群状态。TiDB 集群的编排和调度逻辑则由下列组件负责： - -* `tidb-controller-manager` 是一组 Kubernetes 上的自定义控制器。这些控制器会不断对比 `TidbCluster` 对象中记录的期望状态与 TiDB 集群的实际状态，并调整 Kubernetes 中的资源以驱动 TiDB 集群满足期望状态； -* `tidb-scheduler` 是一个 Kubernetes 调度器扩展，它为 Kubernetes 调度器注入 TiDB 集群特有的调度逻辑。 - -此外，TiDB Operator 还提供了命令行接口 `tkctl` 用于运维集群和诊断集群问题。 - -![TiDB Operator Control Flow](/media/tidb-operator-control-flow.png) - -上图是 TiDB Operator 的控制流程解析。由于 TiDB 集群还需要监控、初始化、定时备份、Binlog 等组件，TiDB Operator 中使用 Helm Chart 封装了 TiDB 集群定义。整体的控制流程如下： - -1. 用户通过 Helm 创建 `TidbCluster` 对象和相应的一系列 Kubernetes 原生对象，比如执行定时备份的 `CronJob`； -2. TiDB Operator 会 watch `TidbCluster` 以及其它相关对象，基于集群的实际状态不断调整 PD、TiKV、TiDB 的 `StatefulSet` 和 `Service` 对象； -3. Kubernetes 的原生控制器根据 `StatefulSet`、`Deployment`、`CronJob` 等对象创建更新或删除对应的 `Pod`； -4. PD、TiKV、TiDB 的 `Pod` 声明中会指定使用 `tidb-scheduler` 调度器，`tidb-scheduler` 会在调度对应 `Pod` 时应用 TiDB 的特定调度逻辑。 - -基于上述的声明式控制流程，TiDB Operator 能够自动进行集群节点健康检查和故障恢复。部署、升级、扩缩容等操作也可以通过修改 `TidbCluster` 对象声明“一键”完成。 - -## 使用 TiDB Operator 管理 TiDB 集群 - -TiDB Operator 提供了多种方式来部署 Kubernetes 上的 TiDB 集群： - -+ 测试环境： - - [kind](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：采用 [kind](https://kind.sigs.k8s.io/) 方式在本地 Kubernetes 集群上部署 TiDB 集群； - - [Minikube](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：使用 TiDB Operator 在本地 Minikube 环境部署 TiDB 集群； - - [GKE](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md)：使用 TiDB Operator 在 GKE 上部署 TiDB 集群。 - -+ 生产环境： - - - 公有云：参考 [AWS 部署文档](/dev/tidb-in-kubernetes/deploy/aws-eks.md)，[GKE 部署文档 (beta)](/dev/tidb-in-kubernetes/deploy/gcp-gke.md)，或[阿里云部署文档](/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md)在对应的公有云上一键部署生产可用的 TiDB 集群并进行后续的运维管理； - - - 现有 Kubernetes 集群：首先按照[部署 TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md)在集群中安装 TiDB Operator，再根据[在标准 Kubernetes 集群上部署 TiDB 集群](/dev/tidb-in-kubernetes/deploy/general-kubernetes.md)来部署你的 TiDB 集群。对于生产级 TiDB 集群，你还需要参考 [TiDB 集群环境要求](/dev/tidb-in-kubernetes/deploy/prerequisites.md)调整 Kubernetes 集群配置并根据[本地 PV 配置](/dev/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)为你的 Kubernetes 集群配置本地 PV，以满足 TiKV 的低延迟本地存储需求。 - -在任何环境上部署前，都可以参考 [TiDB 集群配置](/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)来自定义 TiDB 配置。 - -部署完成后，你可以参考下面的文档进行 Kubernetes 上 TiDB 集群的使用和运维： - -+ [部署 TiDB 集群](/dev/tidb-in-kubernetes/deploy/general-kubernetes.md) -+ [访问 TiDB 集群](/dev/tidb-in-kubernetes/deploy/access-tidb.md) -+ [TiDB 集群扩缩容](/dev/tidb-in-kubernetes/scale-in-kubernetes.md) -+ [TiDB 集群升级](/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md#升级-tidb-版本) -+ [TiDB 集群配置变更](/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md#更新-tidb-集群配置) -+ [TiDB 集群备份恢复](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md) -+ [配置 TiDB 集群故障自动转移](/dev/tidb-in-kubernetes/maintain/auto-failover.md) -+ [监控 TiDB 集群](/dev/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) -+ [TiDB 集群日志收集](/dev/tidb-in-kubernetes/maintain/log-collecting.md) -+ [维护 TiDB 所在的 Kubernetes 节点](/dev/tidb-in-kubernetes/maintain/kubernetes-node.md) - -当集群出现问题需要进行诊断时，你可以： - -+ 查阅 [Kubernetes 上的 TiDB FAQ](/dev/tidb-in-kubernetes/faq.md) 寻找是否存在现成的解决办法； -+ 参考 [Kubernetes 上的 TiDB 故障诊断](/dev/tidb-in-kubernetes/troubleshoot.md)解决故障。 - -Kubernetes 上的 TiDB 提供了专用的命令行工具 `tkctl` 用于集群管理和辅助诊断，同时，在 Kubernetes 上，TiDB 的部分生态工具的使用方法也有所不同，你可以： - -+ 参考 [`tkctl` 使用指南](/dev/tidb-in-kubernetes/reference/tools/tkctl.md) 来使用 `tkctl`； -+ 参考 [Kubernetes 上的 TiDB 相关工具使用指南](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md)来了解 TiDB 生态工具在 Kubernetes 上的使用方法。 - -最后，当 TiDB Operator 发布新版本时，你可以参考[升级 TiDB Operator](/dev/tidb-in-kubernetes/upgrade/tidb-operator.md) 进行版本更新。 diff --git a/dev/tidb-in-kubernetes/troubleshoot.md b/dev/tidb-in-kubernetes/troubleshoot.md deleted file mode 100644 index f25508ae6252..000000000000 --- a/dev/tidb-in-kubernetes/troubleshoot.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群故障诊断 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群故障诊断 - -本文介绍了 Kubernetes 上 TiDB 集群的一些常见故障以及诊断解决方案。 - -## 诊断模式 - -当 Pod 处于 `CrashLoopBackoff` 状态时，Pod 内会容器不断退出，导致无法正常使用 `kubectl exec` 或 `tkctl debug`，给诊断带来不便。为了解决这个问题，TiDB in Kubernetes 提供了 PD/TiKV/TiDB Pod 诊断模式。在诊断模式下，Pod 内的容器启动后会直接挂起，不会再进入重复 Crash 的状态，此时，便可以通过 `kubectl exec` 或 `tkctl debug` 连接 Pod 内的容器进行诊断。 - -操作方式： - -首先，为待诊断的 Pod 添加 Annotation： - -{{< copyable "shell-regular" >}} - -```shell -kubectl annotate pod -n runmode=debug -``` - -在 Pod 内的容器下次重启时，会检测到该 Annotation，进入诊断模式。等待 Pod 进入 Running 状态即可开始诊断： - -{{< copyable "shell-regular" >}} - -```shell -watch kubectl get pod -n -``` - -下面是使用 `kubectl exec` 进入容器进行诊断工作的例子： - -{{< copyable "shell-regular" >}} - -```shell -kubectl exec -it -n -- /bin/sh -``` - -诊断完毕，修复问题后，删除 Pod： - -```shell -kubectl delete pod -n -``` - -Pod 重建后会自动回到正常运行模式。 - -## 集群意外删除后恢复 - -TiDB Operator 使用 PV (Persistent Volume)、PVC (Persistent Volume Claim) 来存储持久化的数据，如果不小心使用 `helm delete` 意外删除了集群，PV/PVC 对象以及数据都会保留下来，以最大程度保证数据安全。 - -此时集群恢复的办法就是使用 `helm install` 命令来创建一个同名的集群，之前保留下来未被删除的 PV/PVC 以及数据会被复用： - -{{< copyable "shell-regular" >}} - -```shell -helm install pingcap/tidb-cluster -n --namespace= --version= -f values.yaml -``` - -## Pod 未正常创建 - -通过 `helm install` 创建集群后，如果 Pod 没有创建，则可以通过以下方式进行诊断： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get tidbclusters -n -kubectl get statefulsets -n -kubectl describe statefulsets -n -pd -``` - -## Pod 之间网络不通 - -针对 TiDB 集群而言，绝大部分 Pod 间的访问均通过 Pod 的域名（使用 Headless Service 分配）进行，例外的情况是 TiDB Operator 在收集集群信息或下发控制指令时，会通过 PD Service 的 `service-name` 访问 PD 集群。 - -当通过日志或监控确认 Pod 间存在网络连通性问题，或根据故障情况推断出 Pod 间网络连接可能不正常时，可以按照下面的流程进行诊断，逐步缩小问题范围： - -1. 确认 Service 和 Headless Service 的 Endpoints 是否正常： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl -n get endpoints -pd - kubectl -n get endpoints -tidb - kubectl -n get endpoints -pd-peer - kubectl -n get endpoints -tikv-peer - kubectl -n get endpoints -tidb-peer - ``` - - 以上命令展示的 `ENDPOINTS` 字段中，应当是由逗号分隔的 `cluster_ip:port` 列表。假如字段为空或不正确，请检查 Pod 的健康状态以及 `kube-controller-manager` 是否正常工作。 - -2. 进入 Pod 的 Network Namespace 诊断网络问题： - - {{< copyable "shell-regular" >}} - - ``` - tkctl debug -n - ``` - - 远端 shell 启动后，使用 `dig` 命令诊断 DNS 解析，假如 DNS 解析异常，请参照[诊断 Kubernetes DNS 解析](https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/)进行故障排除： - - {{< copyable "shell-regular" >}} - - ```shell - dig - ``` - - 使用 `ping` 命令诊断到目的 IP 的三层网络是否连通（目的 IP 为使用 `dig` 解析出的 ClusterIP）: - - {{< copyable "shell-regular" >}} - - ```shell - ping - ``` - - 假如 ping 检查失败，请参照[诊断 Kubernetes 网络](https://www.praqma.com/stories/debugging-kubernetes-networking/)进行故障排除。 - - 假如 ping 检查正常，继续使用 `telnet` 检查目标端口是否打开： - - {{< copyable "shell-regular" >}} - - ```shell - telnet - ``` - - 假如 `telnet` 检查失败，则需要验证 Pod 的对应端口是否正确暴露以及应用的端口是否配置正确： - - {{< copyable "shell-regular" >}} - - ```shell - # 检查端口是否一致 - kubectl -n get po -ojson | jq '.spec.containers[].ports[].containerPort' - - # 检查应用是否被正确配置服务于指定端口上 - # PD, 未配置时默认为 2379 端口 - kubectl -n -it exec -- cat /etc/pd/pd.toml | grep client-urls - # TiKV, 未配置时默认为 20160 端口 - kubectl -n -it exec -- cat /etc/tikv/tikv.toml | grep addr - # TiDB, 未配置时默认为 4000 端口 - kubectl -n -it exec -- cat /etc/tidb/tidb.toml | grep port - ``` - -## Pod 处于 Pending 状态 - -Pod 处于 Pending 状态，通常都是资源不满足导致的，比如： - -* 使用持久化存储的 PD、TiKV、Monitor Pod 使用的 PVC 的 StorageClass 不存在或 PV 不足 -* Kubernetes 集群中没有节点能满足 Pod 申请的 CPU 或内存 -* PD 或者 TiKV Replicas 数量和集群内节点数量不满足 tidb-scheduler 高可用调度策略 - -此时，可以通过 `kubectl describe pod` 命令查看 Pending 的具体原因： - -{{< copyable "shell-regular" >}} - -``` -kubectl describe po -n -``` - -如果是 CPU 或内存资源不足，可以通过降低对应组件的 CPU 或内存资源申请使其能够得到调度，或是增加新的 Kubernetes 节点。 - -如果是 PVC 的 StorageClass 找不到，需要在 `values.yaml` 里面将 `storageClassName` 修改为集群中可用的 StorageClass 名字，执行 `helm upgrade`，然后将 Statefulset 删除，并且将对应的 PVC 也都删除，可以通过以下命令获取集群中可用的 StorageClass： - -{{< copyable "shell-regular" >}} - -``` -kubectl get storageclass -``` - -如果集群中有 StorageClass，但可用的 PV 不足，则需要添加对应的 PV 资源。对于 Local PV，可以参考[本地 PV 配置](/dev/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)进行扩充。 - -tidb-scheduler 针对 PD 和 TiKV 定制了高可用调度策略。对于同一个 TiDB 集群，假设 PD 或者 TiKV 的 Replicas 数量为 N，那么可以调度到每个节点的 PD Pod 数量最多为 `M=(N-1)/2`（如果 N<3，M=1），可以调度到每个节点的 TiKV Pod 数量最多为 `M=ceil(N/3)`（ceil 表示向上取整，如果 N<3，M=1）。如果 Pod 因为不满足高可用调度策略而导致状态为 Pending，需要往集群内添加节点。 - -## Pod 处于 CrashLoopBackOff 状态 - -Pod 处于 CrashLoopBackOff 状态意味着 Pod 内的容器重复地异常退出（异常退出后，容器被 Kubelet 重启，重启后又异常退出，如此往复）。可能导致 CrashLoopBackOff 的原因有很多，此时，最有效的定位办法是查看 Pod 内容器的日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n logs -f -``` - -假如本次日志没有能够帮助诊断的有效信息，可以添加 `-p` 参数输出容器上次启动时的日志信息： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n logs -p -``` - -确认日志中的错误信息后，可以根据 [tidb-server 启动报错](/dev/how-to/troubleshoot/cluster-setup.md#tidb-server-启动报错)，[tikv-server 启动报错](/dev/how-to/troubleshoot/cluster-setup.md#tikv-server-启动报错)，[pd-server 启动报错](/dev/how-to/troubleshoot/cluster-setup.md#pd-server-启动报错)中的指引信息进行进一步排查解决。 - -若是 TiKV Pod 日志中出现 "cluster id mismatch" 信息，则 TiKV Pod 使用的数据可能是其他或之前的 TiKV Pod 的旧数据。在集群配置本地存储时未清除机器上本地磁盘上的数据，或者强制删除了 PV 导致数据并没有被 local volume provisioner 程序回收，可能导致 PV 遗留旧数据，导致错误。 - -在确认该 TiKV 应作为新节点加入集群、且 PV 上的数据应该删除后，可以删除该 TiKV Pod 和关联 PVC。TiKV Pod 将自动重建并绑定新的 PV 来使用。集群本地存储配置中，应对机器上的本地存储删除，避免 Kubernetes 使用机器上遗留的数据。集群运维中，不可强制删除 PV ，应由 local volume provisioner 程序管理。用户通过创建、删除 PVC 以及设置 PV 的 reclaimPolicy 来管理 PV 的生命周期。 - -另外，TiKV 在 ulimit 不足时也会发生启动失败的状况，对于这种情况，可以修改 Kubernetes 节点的 `/etc/security/limits.conf` 调大 ulimit： - -``` -root soft nofile 1000000 -root hard nofile 1000000 -root soft core unlimited -root soft stack 10240 -``` - -假如通过日志无法确认失败原因，ulimit 也设置正常，那么可以通过[诊断模式](#诊断模式)进行进一步排查。 - -## 无法访问 TiDB 服务 - -TiDB 服务访问不了时，首先确认 TiDB 服务是否部署成功，确认方法如下： - -查看该集群的所有组件是否全部都启动了，状态是否为 Running。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl get po -n -``` - -检查 TiDB 组件的日志，看日志是否有报错。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -f -n -c tidb -``` - -如果确定集群部署成功，则进行网络检查： - -1. 如果你是通过 `NodePort` 方式访问不了 TiDB 服务，请在 node 上尝试使用 service domain 或 clusterIP 访问 TiDB 服务，假如 serviceName 或 clusterIP 的方式能访问，基本判断 Kubernetes 集群内的网络是正常的，问题可能出在下面两个方面： - - * 客户端到 node 节点的网络不通。 - * 查看 TiDB service 的 `externalTrafficPolicy` 属性是否为 Local。如果是 Local 则客户端必须通过 TiDB Pod 所在 node 的 IP 来访问。 - -2. 如果 service domain 或 clusterIP 方式也访问不了 TiDB 服务，尝试用 TiDB服务后端的 `:4000` 连接看是否可以访问，如果通过 PodIP 可以访问 TiDB 服务，可以确认问题出在 service domain 或 clusterIP 到 PodIP 之间的连接上，排查项如下： - - * 检查 DNS 服务是否正常： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l k8s-app=kube-dns - dig - ``` - - * 检查各个 node 上的 kube-proxy 是否正常运行： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l k8s-app=kube-proxy - ``` - - * 检查 node 上的 iptables 规则中 TiDB 服务的规则是否正确 - - {{< copyable "shell-regular" >}} - - ```shell - iptables-save -t nat |grep - ``` - - * 检查对应的 endpoint 是否正确 - -3. 如果通过 PodIP 访问不了 TiDB 服务，问题出在 Pod 层面的网络上，排查项如下： - - * 检查 node 上的相关 route 规则是否正确 - * 检查网络插件服务是否正常 - * 参考上面的 [Pod 之间网络不通](#pod-之间网络不通)章节 - -## TiKV Store 异常进入 Tombstone 状态 - -正常情况下，当 TiKV Pod 处于健康状态时（Pod 状态为 `Running`），对应的 TiKV Store 状态也是健康的（Store 状态为 `UP`）。但并发进行 TiKV 组件的扩容和缩容可能会导致部分 TiKV Store 异常并进入 Tombstone 状态。此时，可以按照以下步骤进行修复： - -1. 查看 TiKV Store 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n tidbcluster -ojson | jq '.status.tikv.stores' - ``` - -2. 查看 TiKV Pod 运行状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n po -l app.kubernetes.io/component=tikv - ``` - -3. 对比 Store 状态与 Pod 运行状态。假如某个 TiKV Pod 所对应的 Store 处于 `Offline` 状态，则表明该 Pod 的 Store 正在异常下线中。此时，可以通过下面的命令取消下线进程，进行恢复： - - 1. 打开到 PD 服务的连接： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & - ``` - - 2. 上线对应 Store： - - {{< copyable "shell-regular" >}} - - ```shell - curl -X POST http://127.0.0.1:2379/pd/api/v1/store//state?state=Up - ``` - -4. 假如某个 TiKV Pod 所对应的 `lastHeartbeatTime` 最新的 Store 处于 `Tombstone` 状态 ，则表明异常下线已经完成。此时，需要重建 Pod 并绑定新的 PV 进行恢复： - - 1. 将该 Store 对应 PV 的 `reclaimPolicy` 调整为 `Delete`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch $(kubectl get pv -l app.kubernetes.io/instance=,tidb.pingcap.com/store-id= -o name) -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}} - ``` - - 2. 删除 Pod 使用的 PVC： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pvc tikv- --wait=false - ``` - - 3. 删除 Pod，等待 Pod 重建： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pod - ``` - - Pod 重建后，会以在集群中注册一个新的 Store，恢复完成。 - -## TiDB 长连接被异常中断 - -许多负载均衡器 (Load Balancer) 会设置连接空闲超时时间。当连接上没有数据传输的时间超过设定值，负载均衡器会主动将连接中断。若发现 TiDB 使用过程中，长查询会被异常中断，可检查客户端与 TiDB 服务端之间的中间件程序。若其连接空闲超时时间较短，可尝试增大该超时时间。若不可修改，可打开 TiDB `tcp-keep-alive` 选项，启用 TCP keepalive 特性。 - -默认情况下，Linux 发送 keepalive 探测包的等待时间为 7200 秒。若需减少该时间，可通过 `podSecurityContext` 字段配置 `sysctls`。 - -- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 允许配置 `--allowed-unsafe-sysctls=net.*`，请为 `kubelet` 配置该参数，并按如下方式配置 TiDB： - - {{< copyable "" >}} - - ```yaml - tidb: - ... - podSecurityContext: - sysctls: - - name: net.ipv4.tcp_keepalive_time - value: "300" - ``` - -- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 不允许配置 `--allowed-unsafe-sysctls=net.*`，请按如下方式配置 TiDB： - - {{< copyable "" >}} - - ```yaml - tidb: - annotations: - tidb.pingcap.com/sysctl-init: "true" - podSecurityContext: - sysctls: - - name: net.ipv4.tcp_keepalive_time - value: "300" - ... - ``` - -> **注意：** -> -> 进行以上配置要求 TiDB Operator 1.1 及以上版本。 diff --git a/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md b/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md deleted file mode 100644 index 1df4d10d22b4..000000000000 --- a/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: 滚动升级 Kubernetes 上的 TiDB 集群 -category: how-to ---- - -# 滚动升级 Kubernetes 上的 TiDB 集群 - -滚动更新 TiDB 集群时，会按 PD、TiKV、TiDB 的顺序，串行删除 Pod，并创建新版本的 Pod，当新版本的 Pod 正常运行后，再处理下一个 Pod。 - -滚动升级过程会自动处理 PD、TiKV 的 Leader 迁移与 TiDB 的 DDL Owner 迁移。因此，在多节点的部署拓扑下（最小环境：PD \* 3、TiKV \* 3、TiDB \* 2），滚动更新 TiKV、PD 不会影响业务正常运行。 - -对于有连接重试功能的客户端，滚动更新 TiDB 同样不会影响业务。对于无法进行重试的客户端，滚动更新 TiDB 则会导致连接到被关闭节点的数据库连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能或在低峰期进行 TiDB 的滚动升级操作。 - -滚动更新可以用于升级 TiDB 版本，也可以用于更新集群配置。 - -## 升级 TiDB 版本 - -1. 修改集群的 `values.yaml` 文件中的 `tidb.image`、`tikv.image`、`pd.image` 的值为新版本镜像； -2. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 - -## 更新 TiDB 集群配置 - -默认条件下，修改配置文件不会自动应用到 TiDB 集群中，只有在实例重启时，才会重新加载新的配置文件。 - -您可以开启配置文件自动更新特性，在每次配置文件更新时，自动执行滚动更新，将修改后的配置应用到集群中。操作步骤如下： - -1. 修改集群的 `values.yaml` 文件，将 `enableConfigMapRollout` 的值设为 `true`； -2. 根据需求修改 `values.yaml` 中需要调整的集群配置项； -3. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -4. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 - -> **注意：** -> -> - 将 `enableConfigMapRollout` 特性从关闭状态打开时，即使没有配置变更，也会触发一次 PD、TiKV、TiDB 的滚动更新。 - -## 强制升级 TiDB 集群 - -如果 PD 集群因为 PD 配置错误、PD 镜像 tag 错误、NodeAffinity 等原因不可用，[TiDB 集群扩缩容](/dev/tidb-in-kubernetes/scale-in-kubernetes.md)、[升级 TiDB 版本](#升级-tidb-版本)和[更新 TiDB 集群配置](#更新-tidb-集群配置)这三种操作都无法成功执行。 - -这种情况下，可使用 `force-upgrade`（TiDB Operator 版本 > v1.0.0-beta.3 ）强制升级集群以恢复集群功能。 -首先为集群设置 `annotation`： - -{{< copyable "shell-regular" >}} - -```shell -kubectl annotate --overwrite tc -n tidb.pingcap.com/force-upgrade=true -``` - -然后执行对应操作中的 `helm upgrade` 命令： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade pingcap/tidb-cluster -f values.yaml --version= -``` - -> **警告：** -> -> PD 集群恢复后，**必须**执行下面命令禁用强制升级功能，否则下次升级过程可能会出现异常： -> -> {{< copyable "shell-regular" >}} -> -> ```shell -> kubectl annotate tc -n tidb.pingcap.com/force-upgrade- -> ``` diff --git a/faq/tidb-lightning.md b/faq/tidb-lightning.md new file mode 100644 index 000000000000..864038c99cfc --- /dev/null +++ b/faq/tidb-lightning.md @@ -0,0 +1,190 @@ +--- +title: TiDB Lightning 常见问题 +category: FAQ +--- + +# TiDB Lightning 常见问题 + +本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。 + +>**注意：** +> +> 使用 TiDB Lightning 的过程中如遇错误，参考 [TiDB Lightning 故障诊断](/how-to/troubleshoot/tidb-lightning.md)进行排查。 + +## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ + +TiDB Lightning 的版本应与集群相同。最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。 + +## TiDB Lightning 支持导入多个库吗？ + +支持。 + +## TiDB Lightning 对下游数据库的账号权限要求是怎样的？ + +TiDB Lightning 需要以下权限： + +* SELECT +* UPDATE +* ALTER +* CREATE +* DROP + +如果选择 [TiDB-backend](/reference/tools/tidb-lightning/tidb-backend.md) 模式，或目标数据库用于存储断点，则 TiBD Lightning 额外需要以下权限： + +* INSERT +* DELETE + ++Importer-backend 无需以上两个权限，因为数据直接被 Ingest 到 TiKV 中，所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问，就可以保证安全。 + +如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 + +## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？ + +如果只是个别表报错，不会影响整体。报错的那个表会停止处理，继续处理其他的表。 + +## 如何正确重启 TiDB Lightning？ + +根据 `tikv-importer` 的状态，重启 TiDB Lightning 的基本顺序如下： + +如果 `tikv-importer` 仍在运行： + +1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 +2. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 +3. 如果上面的修改操作更改了任何表，你还需要[清除对应的断点](/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-remove)。 +4. 重启 `tidb-lightning`。 + +如果 `tikv-importer` 需要重启： + +1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 +2. [结束 `tikv-importer` 进程](#如何正确结束-tikv-importer-进程)。 +3. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 +4. 重启 `tikv-importer`。 +5. 重启 `tidb-lightning` 并等待，**直到程序因校验和错误（如果有的话）而失败**。 + * 重启 `tikv-importer` 将清除所有仍在写入的引擎文件，但是 `tidb-lightning` 并不会感知到该操作。从 v3.0 开始，最简单的方法是让 `tidb-lightning` 继续，然后再重试。 +6. [清除失败的表及断点](/how-to/troubleshoot/tidb-lightning.md#checkpoint-for--has-invalid-status错误码)。 +7. 再次重启 `tidb-lightning`。 + +## 如何校验导入的数据的正确性？ + +TiDB Lightning 默认会对导入数据计算校验和 (checksum)，如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。 + +TiDB 也支持从 MySQL 命令行运行 `ADMIN CHECKSUM TABLE` 指令来计算校验和。 + +{{< copyable "sql" >}} + +```sql +ADMIN CHECKSUM TABLE `schema`.`table`; +``` + +``` ++---------+------------+---------------------+-----------+-------------+ +| Db_name | Table_name | Checksum_crc64_xor | Total_kvs | Total_bytes | ++---------+------------+---------------------+-----------+-------------+ +| schema | table | 5505282386844578743 | 3 | 96 | ++---------+------------+---------------------+-----------+-------------+ +1 row in set (0.01 sec) +``` + +## TiDB Lightning 支持哪些格式的数据源？ + +TiDB Lightning 只支持两种格式的数据源： + +1. [Mydumper](/reference/tools/mydumper.md) 生成的 SQL dump +2. 储存在本地文件系统的 [CSV](/reference/tools/tidb-lightning/csv.md) 文件 + +## 我已经在下游创建好库和表了，TiDB Lightning 可以忽略建库建表操作吗？ + +可以。在配置文档中的 `[mydumper]` 部分将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。 + +## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入？ + +可以。Lightning 默认的 [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) 为 `"STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"`。 + +这个设置不允许一些非法的数值，例如 `1970-00-00` 这样的日期。可以修改配置文件 `[tidb]` 下的 `sql-mode` 值。 + +```toml +... +[tidb] +sql-mode = "" +... +``` + +## 可以启用一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？ + +只要每个 Lightning 操作的表互不相同就可以。 + +## 如何正确结束 `tikv-importer` 进程？ + +根据部署方式，选择相应操作结束进程 + +- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh`。 + +- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程 ID，然后通过 `kill «pid»` 结束进程。 + +## 如何正确结束 `tidb-lightning` 进程？ + +根据部署方式，选择相应操作结束进程 + +- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh`。 + +- 手动部署：如果 `tidb-lightning` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tidb-lightning` 获取进程 ID，然后通过 `kill -2 «pid»` 结束进程。 + +## `tidb-lightning` 在服务器上运行，进程莫名其妙地退出了，是怎么回事呢？ + +这种情况可能是启动方式不正确，导致收到 SIGHUP 信号而退出。此时 `tidb-lightning.log` 通常有如下日志： + +``` +[2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup] +``` + +不推荐在命令行中直接使用 `nohup` 启动进程，推荐[使用脚本启动 `tidb-lightning`](/reference/tools/tidb-lightning/deployment.md)。 + +## 为什么用过 TiDB Lightning 之后，TiDB 集群变得又慢又耗 CPU？ + +如果 `tidb-lightning` 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)： + +{{< copyable "shell-regular" >}} + +```sh +tidb-lightning-ctl --switch-mode=normal +``` + +## TiDB Lightning 可以使用千兆网卡吗？ + +使用 TiDB Lightning 建议配置万兆网卡。**不推荐**使用千兆网卡，尤其是在部署 `tikv-importer` 的机器上。 + +千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。为了避免这种情况，你可以在 [`tikv-importer` 的配置文件](/reference/tools/tidb-lightning/config.md#tikv-importer-配置参数)中**限制上传速度**。 + +```toml +[import] +# Importer 上传至 TiKV 的最大速度（字节/秒）。 +# 建议将该速度设为 100 MB/s 或更小。 +upload-speed-limit = "100MB" +``` + +## 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间？ + +当使用默认的 3 副本设置时，TiDB Lightning 需要 TiKV 集群预留数据源大小 6 倍的空间。多出来的 2 倍是算上下列没储存在数据源的因素的保守估计： + +- 索引会占据额外的空间 +- RocksDB 的空间放大效应 + +## TiDB Lightning 使用过程中是否可以重启 TiKV Importer？ + +不能，Importer 会在内存中存储一些引擎文件，Importer 重启后，`tidb-lightning` 会因连接失败而停止。此时，你需要[清除失败的断点](/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-error-destroy)，因为这些 Importer 特有的信息丢失了。你可以在之后[重启 Lightning](#如何正确重启-tidb-lightning)。 + +## 如何清除所有与 TiDB Lightning 相关的中间数据？ + +1. 删除断点文件。 + + {{< copyable "shell-regular" >}} + + ```sh + tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all + ``` + + 如果出于某些原因而无法运行该命令，你可以尝试手动删除 `/tmp/tidb_lightning_checkpoint.pb` 文件。 + +2. 删除 `tikv-importer` 所在机器上的整个 “import” 文件目录。 + +3. 如果需要的话，删除 TiDB 集群上创建的所有表和库。 diff --git a/faq/tidb.md b/faq/tidb.md new file mode 100755 index 000000000000..890c4c397c6c --- /dev/null +++ b/faq/tidb.md @@ -0,0 +1,1082 @@ +--- +title: TiDB FAQ +category: FAQ +--- + +# FAQ + +## 一、 TiDB 介绍、架构、原理 + +### 1.1 TiDB 介绍及整体架构 + +#### 1.1.1 TiDB 整体架构 + +[TiDB 简介](/overview.md#tidb-简介) + +#### 1.1.2 TiDB 是什么？ + +TiDB 是一个分布式 NewSQL 数据库。它支持水平弹性扩展、ACID 事务、标准 SQL、MySQL 语法和 MySQL 协议，具有数据强一致的高可用特性，是一个不仅适合 OLTP 场景还适合 OLAP 场景的混合数据库。 + +#### 1.1.3 TiDB 是基于 MySQL 开发的吗？ + +不是，虽然 TiDB 支持 MySQL 语法和协议，但是 TiDB 是由 PingCAP 团队完全自主开发的产品。 + +#### 1.1.4 TiDB、TiKV、Placement Driver (PD) 主要作用？ + +- TiDB 是 Server 计算层，主要负责 SQL 的解析、制定查询计划、生成执行器。 +- TiKV 是分布式 Key-Value 存储引擎，用来存储真正的数据，简而言之，TiKV 是 TiDB 的存储引擎。 +- PD 是 TiDB 集群的管理组件，负责存储 TiKV 的元数据，同时也负责分配时间戳以及对 TiKV 做负载均衡调度。 + +#### 1.1.5 TiDB 易用性如何？ + +TiDB 使用起来很简单，可以将 TiDB 集群当成 MySQL 来用，你可以将 TiDB 用在任何以 MySQL 作为后台存储服务的应用中，并且基本上不需要修改应用代码，同时你可以用大部分流行的 MySQL 管理工具来管理 TiDB。 + +#### 1.1.6 TiDB 和 MySQL 兼容性如何？ + +TiDB 目前还不支持触发器、存储过程、自定义函数、外键，除此之外，TiDB 支持绝大部分 MySQL 5.7 的语法。 + +详情参见[与 MySQL 兼容性对比](/reference/mysql-compatibility.md)。 + +#### 1.1.7 TiDB 具备高可用的特性吗？ + +TiDB 天然具备高可用特性，TiDB、TiKV、PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。具体见 [TiDB 高可用性](/key-features.md#高可用)。 + +#### 1.1.8 TiDB 数据是强一致的吗？ + +TiDB 实现了快照隔离 (Snapshot Isolation) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。 + +在底层，TiKV 使用复制日志 + 状态机 (State Machine) 的模型来复制数据。对于写入请求，数据被写入 Leader，然后 Leader 以日志的形式将命令复制到它的 Follower 中。当集群中的大多数节点收到此日志时，日志会被提交，状态机会相应作出变更。 + +#### 1.1.9 TiDB 支持分布式事务吗？ + +支持。无论是一个地方的几个节点，还是[跨多个数据中心的多个节点](/how-to/deploy/geographic-redundancy/overview.md)，TiDB 均支持 ACID 分布式事务。 + +TiDB 事务模型灵感源自 Google Percolator 模型，主体是一个两阶段提交协议，并进行了一些实用的优化。该模型依赖于一个时间戳分配器，为每个事务分配单调递增的时间戳，这样就检测到事务冲突。在 TiDB 集群中，[PD](/architecture.md#pd-server) 承担时间戳分配器的角色。 + +#### 1.1.10 TiDB 支持哪些编程语言？ + +只要支持 MySQL Client/Driver 的编程语言，都可以直接使用 TiDB。 + +#### 1.1.11 TiDB 是否支持其他存储引擎？ + +是的，除了 TiKV 之外，TiDB 还支持一些流行的单机存储引擎，比如 GolevelDB、RocksDB、BoltDB 等。如果一个存储引擎是支持事务的 KV 引擎，并且能提供一个满足 TiDB 接口要求的 Client，即可接入 TiDB。 + +#### 1.1.12 官方有没有三中心跨机房多活部署的推荐方案？ + +从 TiDB 架构来讲，支持真正意义上的跨中心异地多活，从操作层面讲，依赖数据中心之间的网络延迟和稳定性，一般建议延迟在 5ms 以下，目前我们已经有相似客户方案，具体请咨询官方 [info@pingcap.com](mailto:info@pingcap.com)。 + +#### 1.1.13 除了官方文档，有没有其他 TiDB 知识获取途径？ + +目前[官方文档](/overview.md#tidb-简介)是获取 TiDB 相关知识最主要、最及时的发布途径。除此之外，我们也有一些技术沟通群，如有需求可发邮件至 [info@pingcap.com](mailto:info@pingcap.com) 获取。 + +#### 1.1.14 TiDB 对哪些 MySQL variables 兼容？ + +详细可参考[系统变量](/reference/configuration/tidb-server/mysql-variables.md)。 + +#### 1.1.15 TiDB 是否支持 select for update？ + +支持，但语义上和 MySQL 有区别，TiDB 是分布式数据库，采用的乐观锁机制，也就说 select for update 不在事务开启就锁住数据，而是其他事务在提交的时候进行冲突检查，如有冲突，会进行回滚。 + +#### 1.1.16 TiDB 的 codec 能保证 UTF8 的字符串是 memcomparable 的吗？我们的 key 需要支持 UTF8，有什么编码建议吗？ + +TiDB 字符集默认就是 UTF8 而且目前只支持 UTF8，字符串就是 memcomparable 格式的。 + +#### 1.1.17 TiDB 用户名长度限制？ + +在 TiDB 中用户名最长为 32 字符。 + +#### 1.1.18 一个事务中的语句数量最大是多少？ + +一个事务中的语句数量，默认限制最大为 5000 条。 + +#### 1.1.19 TiDB 是否支持 XA？ + +虽然 TiDB 的 JDBC 驱动用的就是 MySQL JDBC（Connector / J），但是当使用 Atomikos 的时候，数据源要配置成类似这样的配置：`type="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"`。MySQL JDBC XADataSource 连接 TiDB 的模式目前是不支持的。MySQL JDBC 中配置好的 XADataSource 模式，只对 MySQL 数据库起作用（DML 去修改 redo 等）。 + +Atomikos 配好两个数据源后，JDBC 驱动都要设置成 XA 模式，然后 Atomikos 在操作 TM 和 RM（DB）的时候，会通过数据源的配置，发起带有 XA 指令到 JDBC 层，JDBC 层 XA 模式启用的情况下，会对 InnoDB（如果是 MySQL 的话）下发操作一连串 XA 逻辑的动作，包括 DML 去变更 redo log 等，就是两阶段递交的那些操作。TiDB 目前的引擎版本中，没有对上层应用层 JTA / XA 的支持，不解析这些 Atomikos 发过来的 XA 类型的操作。 + +MySQL 是单机数据库，只能通过 XA 来满足跨数据库事务，而 TiDB 本身就通过 Google 的 Percolator 事务模型支持分布式事务，性能稳定性比 XA 要高出很多，所以不会也不需要支持 XA。 + +#### 1.1.20 show processlist 是否显示系统进程号？ + +TiDB 的 `show processlist` 与 MySQL 的 `show processlist` 显示内容基本一样，不会显示系统进程号，而 ID 表示当前的 session ID。其中 TiDB 的 `show processlist` 和 MySQL 的 `show processlist` 区别如下： + +1）由于 TiDB 是分布式数据库，tidb-server 实例是无状态的 SQL 解析和执行引擎（详情可参考 [TiDB 整体架构](/overview.md#tidb-整体架构)），用户使用 MySQL 客户端登录的是哪个 tidb-server，`show processlist` 就会显示当前连接的这个 tidb-server 中执行的 session 列表，不是整个集群中运行的全部 session 列表；而 MySQL 是单机数据库，`show processlist` 列出的是当前整个 MySQL 数据库的全部执行 SQL 列表。 + +2）TiDB 的 `show processlist` 显示内容比起 MySQL 来讲，多了一个当前 session 使用内存的估算值（单位 Byte）。 + +#### 1.1.21 如何修改用户名密码和权限？ + +TiDB 作为分布式数据库，在 TiDB 中修改用户密码建议使用 `set password for 'root'@'%' = '0101001';` 或 `alter` 方法，不推荐使用 `update mysql.user` 的方法进行，这种方法可能会造成其它节点刷新不及时的情况。修改权限也一样，都建议采用官方的标准语法。详情可参考 [TiDB 用户账户管理](/reference/security/user-account-management.md)。 + +#### 1.1.22 TiDB 中，为什么出现后插入数据的自增 ID 反而小？ + +TiDB 的自增 ID (`AUTO_INCREMENT`) 只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。当多个线程并发往不同的 tidb-server 插入数据的时候，有可能会出现后插入的数据自增 ID 小的情况。此外，TiDB允许给整型类型的字段指定 AUTO_INCREMENT，且一个表只允许一个属性为 `AUTO_INCREMENT` 的字段。详情可参考[CREATE TABLE 语法](/reference/mysql-compatibility.md#自增-id)。 + +#### 1.1.23 sql_mode 默认除了通过命令 set 修改，配置文件怎么修改？ + +TiDB 的 sql_mode 与 MySQL 的 sql_mode 设置方法有一些差别，TiDB 不支持配置文件配置设置数据库的 sql\_mode，而只能使用 set 命令去设置，具体方法为：`set @@global.sql_mode = 'STRICT_TRANS_TABLES';`。 + +#### 1.1.24 TiDB 支持哪些认证协议，过程是怎样的？ + +这一层跟 MySQL 一样，走的 SASL 认证协议，用于用户登录认证，对密码的处理流程。 + +客户端连接 TiDB 的时候，走的是 challenge-response（挑战-应答）的认证模式，过程如下： + +第一步：客户端连接服务器； + +第二步：服务器发送随机字符串 challenge 给客户端； + +第三步：客户端发送 username + response 给服务器； + +第四步：服务器验证 response。 + +### 1.2 TiDB 原理 + +#### 1.2.1 存储 TiKV + +##### 1.2.1.1 TiKV 详细解读 + +[三篇文章了解 TiDB 技术内幕 - 说存储](http://t.cn/RTKRRWv) + +#### 1.2.2 计算 TiDB + +##### 1.2.2.1 TiDB 详细解读 + +[三篇文章了解 TiDB 技术内幕 - 说计算](http://t.cn/RTKRkBh) + +#### 1.2.3 调度 PD + +##### 1.2.3.1 PD 详细解读 + +[三篇文章了解 TiDB 技术内幕 - 谈调度](http://t.cn/RTKEZ0U) + +## 二、安装部署升级 + +### 2.1 环境准备 + +#### 2.1.1 操作系统版本要求 + +| **Linux 操作系统平台** | **版本** | +| --- | --- | +| Red Hat Enterprise Linux | 7.3 及以上 | +| CentOS | 7.3 及以上 | +| Oracle Enterprise Linux | 7.3 及以上 | + +##### 2.1.1.1 为什么要在 CentOS 7 上部署 TiDB 集群？ + +TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络，作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境，具体可以参考 TiDB 的[官方部署要求](/how-to/deploy/hardware-recommendations.md)。其中 TiDB 在 CentOS 7.3 的环境下进行大量的测试，同时也有很多这个操作系统的部署最佳实践，因此，我们推荐客户在部署 TiDB 的时候使用 CentOS 7.3+ 以上的Linux 操作系统。 + +#### 2.1.2 硬件要求 + +TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： + +##### 2.1.2.1 开发及测试环境 + +| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | +| --- | --- | --- | --- | --- | --- | +| TiDB | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 PD 同机器） | +| PD | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | +| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | +| | | | | 服务器总计 | 4 | + +##### 2.1.2.2 线上环境 + +| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | +| --- | --- | --- | --- | --- | --- | +| TiDB | 16核+ | 48 GB+ | SAS | 万兆网卡（2块最佳） | 2 | +| PD | 8核+ | 16 GB+ | SSD | 万兆网卡（2块最佳） | 3 | +| TiKV | 16核+ | 48 GB+ | SSD | 万兆网卡（2块最佳） | 3 | +| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | +| | | | | 服务器总计 | 9 | + +##### 2.1.2.3 2 块网卡的目的是？万兆的目的是？ + +作为一个分布式集群，TiDB 对时间的要求还是比较高的，尤其是 PD 需要分发唯一的时间戳，如果 PD 时间不统一，如果有 PD 切换，将会等待更长的时间。2 块网卡可以做 bond，保证数据传输的稳定，万兆可以保证数据传输的速度，千兆网卡容易出现瓶颈，我们强烈建议使用万兆网卡。 + +##### 2.1.2.4 SSD 不做 RAID 是否可行？ + +资源可接受的话，我们建议做 RAID 10，如果资源有限，也可以不做 RAID。 + +##### 2.1.2.5 TiDB 集群各个组件的配置推荐？ + +- TiDB 需要 CPU 和内存比较好的机器，参考官网配置要求，如果后期需要开启 Binlog，根据业务量的评估和 GC 时间的要求，也需要本地磁盘大一点，不要求 SSD 磁盘； +- PD 里面存了集群元信息，会有频繁的读写请求，对磁盘 I/O 要求相对比较高，磁盘太差会影响整个集群性能，推荐 SSD 磁盘，空间不用太大。另外集群 Region 数量越多对 CPU、内存的要求越高； +- TiKV 对 CPU、内存、磁盘要求都比较高，一定要用 SSD 磁盘。 + +详情可参考 [TiDB 软硬件环境需求](/how-to/deploy/hardware-recommendations.md)。 + +### 2.2 安装部署 + +#### 2.2.1 Ansible 部署方式（强烈推荐） + +详细可参考[使用 TiDB Ansible 部署 TiDB 集群](/how-to/deploy/orchestrated/ansible.md)。 + +##### 2.2.1.1 为什么修改了 TiKV/PD 的 toml 配置文件，却没有生效？ + +这种情况一般是因为没有使用 `--config` 参数来指定配置文件（目前只会出现在 binary 部署的场景），TiKV/PD 会按默认值来设置。如果要使用配置文件，请设置 TiKV/PD 的 `--config` 参数。对于 TiKV 组件，修改配置后重启服务即可；对于 PD 组件，只会在第一次启动时读取配置文件，之后可以使用 pd-ctl 的方式来修改配置，详情可参考 [PD 配置参数](/reference/configuration/pd-server/configuration.md)。 + +##### 2.2.1.2 TiDB 监控框架 Prometheus + Grafana 监控机器建议单独还是多台部署？ + +监控机建议单独部署。建议 CPU 8 core，内存 16 GB 以上，硬盘 500 GB 以上。 + +##### 2.2.1.3 有一部分监控信息显示不出来？ + +查看访问监控的机器时间跟集群内机器的时间差，如果比较大，更正时间后即可显示正常。 + +##### 2.2.1.4 supervise/svc/svstat 服务具体起什么作用？ + +- supervise 守护进程 +- svc 启停服务 +- svstat 查看进程状态 + +##### 2.2.1.5 inventory.ini 变量参数解读 + +| **变量** | **含义** | +| --- | --- | +| cluster_name | 集群名称，可调整 | +| tidb_version | TiDB 版本，TiDB Ansible 各分支默认已配置 | +| deployment_method | 部署方式，默认为 binary，可选 docker | +| process_supervision | 进程监管方式，默认为 systemd，可选 supervise | +| timezone | 修改部署目标机器时区，默认为 Asia/Shanghai, 可调整，与set_timezone 变量结合使用 | +| set_timezone | 默认为 True，即修改部署目标机器时区，关闭可修改为 False | +| enable_elk | 目前不支持，请忽略 | +| enable_firewalld | 开启防火墙，默认不开启 | +| enable_ntpd | 检测部署目标机器 NTP 服务，默认为 True，请勿关闭 | +| machine_benchmark | 检测部署目标机器磁盘 IOPS，默认为 True，请勿关闭 | +| set_hostname | 根据 IP 修改部署目标机器主机名，默认为 False | +| enable_binlog | 是否部署 pump 并开启 binlog，默认为 False，依赖 Kafka 集群，参见 zookeeper_addrs 变量 | +| zookeeper_addrs | binlog Kafka 集群的 zookeeper 地址 | +| enable_slow_query_log | TiDB 慢查询日志记录到单独文件({{ deploy_dir }}/log/tidb_slow_query.log)，默认为 False，记录到 tidb 日志 | +| deploy_without_tidb | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 inventory.ini 文件中 tidb_servers 主机组 IP 设置为空。 | + +#### 2.2.2 TiDB 离线 Ansible 部署方案 + +首先这不是我们建议的方式，如果中控机没有外网，也可以通过离线 Ansible 部署方式，详情可参考[离线 TiDB Ansible 部署方案](/how-to/deploy/orchestrated/offline-ansible.md)。 + +#### 2.2.3 Docker Compose 快速构建集群（单机部署） + +使用 docker-compose 在本地一键拉起一个集群，包括集群监控，还可以根据需求自定义各个组件的软件版本和实例个数，以及自定义配置文件，这种只限于开发环境，详细可参考[官方文档](/how-to/get-started/deploy-tidb-from-docker-compose.md)。 + +#### 2.2.4 如何单独记录 TiDB 中的慢查询日志，如何定位慢查询 SQL？ + +1）TiDB 中，对慢查询的定义在 tidb-ansible 的 `conf/tidb.yml` 配置文件中，`slow-threshold: 300`，这个参数是配置慢查询记录阈值的，单位是 ms。 + +慢查询日志默认记录到 tidb.log 中，如果希望生成单独的慢查询日志文件，修改 inventory.ini 配置文件的参数 `enable_slow_query_log` 为 True。 + +如上配置修改之后，需要执行 `ansible-playbook rolling_update.yml --tags=tidb`，对 tidb-server 实例进行滚动升级，升级完成后，tidb-server 将在 `tidb_slow_query.log` +文件中记录慢查询日志。 + +2）如果出现了慢查询，可以从 Grafana 监控定位到出现慢查询的 tidb-server 以及时间点，然后在对应节点查找日志中记录的 SQL 信息。 + +3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md#admin-show-slow-命令)。 + +#### 2.2.5 首次部署 TiDB 集群时，没有配置 tikv 的 Label 信息，在后续如何添加配置 Label？ + +TiDB 的 Label 设置是与集群的部署架构相关的，是集群部署中的重要内容，是 PD 进行全局管理和调度的依据。如果集群在初期部署过程中没有设置 Label，需要在后期对部署结构进行调整，就需要手动通过 PD 的管理工具 pd-ctl 来添加 location-labels 信息，例如：`config set location-labels "zone,rack,host"`（根据实际的 label 层级名字配置）。 + +pd-ctl 的使用参考 [PD Control 使用说明](/reference/tools/pd-control.md)。 + +#### 2.2.6 为什么测试磁盘的 dd 命令用 oflag=direct 这个选项？ + +Direct 模式就是把写入请求直接封装成 I/O 指令发到磁盘，这样是为了绕开文件系统的缓存，可以直接测试磁盘的真实的 I/O 读写能力。 + +#### 2.2.7 如何用 fio 命令测试 TiKV 实例的磁盘性能？ + +- 随机读测试： + + {{< copyable "shell-regular" >}} + + ```bash + ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randread -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json + ``` + +- 顺序写和随机读混合测试： + + {{< copyable "shell-regular" >}} + + ```bash + ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randrw -percentage_random=100,0 -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json + ``` + +#### 2.2.8 使用 TiDB Ansible 部署 TiDB 集群的时候，遇到 `UNREACHABLE! "msg": "Failed to connect to the host via ssh: "` 报错是什么原因？ + +有两种可能性： + +- ssh 互信的准备工作未做好，建议严格参照我们的[官方文档步骤](/how-to/deploy/orchestrated/ansible.md)配置互信，并使用命令 `ansible -i inventory.ini all -m shell -a 'whoami' -b` 来验证互信配置是否成功。 + +- 如果涉及到单服务器分配了多角色的场景，例如多组件混合部署或单台服务器部署了多个 TiKV 实例，可能是由于 ssh 复用的机制引起这个报错，可以使用 `ansible … -f 1` 的选项来规避这个报错。 + +### 2.3 升级 + +#### 2.3.1 如何使用 Ansible 滚动升级？ + +滚动升级 TiKV 节点( 只升级单独服务 ) + +`ansible-playbook rolling_update.yml --tags=tikv` + +滚动升级所有服务 + +`ansible-playbook rolling_update.yml` + +#### 2.3.2 滚动升级有那些影响? + +滚动升级 TiDB 服务，滚动升级期间不影响业务运行，需要配置最小集群拓扑（TiDB \* 2、PD \* 3、TiKV \* 3），如果集群环境中有 Pump/Drainer 服务，建议先停止 Drainer 后滚动升级（升级 TiDB 时会升级 Pump）。 + +#### 2.3.3 Binary 如何升级？ + +Binary 不是我们建议的安装方式，对升级支持也不友好，建议换成 Ansible 部署。 + +#### 2.3.4 一般升级选择升级 TiKV 还是所有组件都升级？ + +常规需要一起升，因为整个版本都是一起测试的，单独升级只限当发生一个紧急故障时，需要单独对一个有问题的角色做升级。 + +#### 2.3.5 启动集群或者升级集群过程中出现 “Timeout when waiting for search string 200 OK” 是什么原因？如何处理？ + +可能有以下几种原因：进程没有正常启动；端口被占用；进程没有正常停掉；停掉集群的情况下使用 rolling_update.yml 来升级集群（操作错误）。 + +处理方式：登录到相应节点查看进程或者端口的状态；纠正错误的操作步骤。 + +## 三、集群管理 + +### 3.1 集群日常管理 + +#### 3.1.1 Ansible 常见运维操作有那些？ + +| **任务** | **Playbook** | +| --- | --- | +| 启动集群 | ansible-playbook start.yml | +| 停止集群 | ansible-playbook stop.yml | +| 销毁集群 | ansible-playbook unsafe\_cleanup.yml (若部署目录为挂载点，会报错，可忽略） | +| 清除数据(测试用) | ansible-playbook cleanup\_data.yml | +| 滚动升级 | ansible-playbook rolling\_update.yml | +| 滚动升级 TiKV | ansible-playbook rolling\_update.yml --tags=tikv | +| 滚动升级除 PD 外模块 | ansible-playbook rolling\_update.yml --skip-tags=pd | +| 滚动升级监控组件 | ansible-playbook rolling\_update\_monitor.yml | + +#### 3.1.2 TiDB 如何登录？ + +和 MySQL 登录方式一样，可以按照下面例子进行登录。 + +`mysql -h 127.0.0.1 -uroot -P4000` + +#### 3.1.3 TiDB 如何修改数据库系统变量？ + +和 MySQL 一样，TiDB 也分为静态参数和固态参数，静态参数可以直接通过`set global xxx = n`的方式进行修改，不过新参数值只限于该实例生命周期有效。 + +#### 3.1.4 TiDB (TiKV) 有哪些数据目录？ + +默认在 [`--data-dir`](/reference/configuration/tikv-server/configuration.md#--data-dir) 目录下，其中包括 backup、db、raft、snap 四个目录，分别存储备份、数据、raft 数据及镜像数据。 + +#### 3.1.5 TiDB 有哪些系统表？ + +和 MySQL 类似，TiDB 中也有系统表，用于存放数据库运行时所需信息，具体信息参考 [TiDB 系统数据库](/reference/system-databases/mysql.md)文档。 + +#### 3.1.6 TiDB 各节点服务器下是否有日志文件，如何管理？ + +默认情况下各节点服务器会在日志中输出标准错误，如果启动的时候通过 `--log-file` 参数指定了日志文件，那么日志会输出到指定的文件中，并且按天做 rotation。 + +#### 3.1.7 如何规范停止 TiDB？ + +如果是用 Ansible 部署的，可以使用 `ansible-playbook stop.yml` 命令停止 TiDB 集群。如果不是 Ansible 部署的，可以直接 kill 掉所有服务。如果使用 kill 命令，TiDB 的组件会做 graceful 的 shutdown。 + +#### 3.1.8 TiDB 里面可以执行 kill 命令吗？ + +- 可以 kill DML 语句，首先使用 `show processlist`，找到对应 session 的 id，然后执行 `kill tidb [session id]`。 +- 可以 kill DDL 语句，首先使用 `admin show ddl jobs`，查找需要 kill 的 DDL job ID，然后执行 `admin cancel ddl jobs 'job_id' [, 'job_id'] ...`。具体可以参考 [admin 操作](/reference/sql/statements/admin.md)。 + +#### 3.1.9 TiDB 是否支持会话超时？ + +TiDB 暂不支持数据库层面的会话超时，目前想要实现超时，在没 LB（Load Balancing）的时候，需要应用侧记录发起的 Session 的 ID，通过应用自定义超时，超时以后需要到发起 Query 的节点上用 `kill tidb [session id]` 来杀掉 SQL。目前建议使用应用程序来实现会话超时，当达到超时时间，应用层就会抛出异常继续执行后续的程序段。 + +#### 3.1.10 TiDB 生产环境的版本管理策略是怎么样的？如何尽可能避免频繁升级？ + +TiDB 版本目前逐步标准化，每次 Release 都包含详细的 Change log，版本功能[变化详情](https://github.com/pingcap/TiDB/releases)，生产环境是否有必要升级取决于业务系统，建议升级之前详细了解前后版本的功能差异。 + +版本号说明参考：Release Version: `v1.0.3-1-ga80e796` + +- `v1.0.3` 表示 GA 标准版 +- `1` 表示该版本 commit 1 次 +- `ga80e796` 代表版本的 `git-hash` + +#### 3.1.11 分不清 TiDB master 版本之间的区别，经常用错 TiDB Ansible 版本? + +TiDB 目前社区非常活跃，在 1.0 GA 版本发布后，还在不断的优化和修改 BUG，因此 TiDB 的版本更新周期比较快，会不定期有新版本发布，请关注我们的[新版本发布官方网站](https://pingcap.com/weekly/)。此外 TiDB 安装推荐使用 TiDB Ansible 进行安装，TiDB Ansible 的版本也会随着 TiDB 的版本发布进行更新，因此建议用户在安装升级新版本的时候使用最新的 TiDB Ansible 安装包版本进行安装。此外，在 TiDB 1.0 GA 版本后，对 TiDB 的版本号进行了统一管理，TiDB 的版本可以通过以下两种方式进行查看： + +- 通过 `select tidb_version()` 进行查看 +- 通过执行 `tidb-server -V` 进行查看 + +#### 3.1.12 有没有图形化部署 TiDB 的工具？ + +暂时没有。 + +#### 3.1.13 TiDB 如何进行水平扩展？ + +当您的业务不断增长时，数据库可能会面临三方面瓶颈，第一是存储空间，第二是计算资源，第三是读写容量，这时可以对 TiDB 集群做水平扩展。 + +- 如果是存储资源不够，可以通过添加 TiKV Server 节点来解决，新节点启动后，PD 会自动将其他节点的部分数据迁移过去，无需人工介入。 +- 如果是计算资源不够，可以查看 TiDB Server 和 TiKV Server 节点的 CPU 消耗情况，再考虑添加 TiDB Server 节点或者是 TiKV Server 节点来解决，如添加 TiDB Server 节点，将其添加到前端 Load Balancer 配置之中即可。 +- 如果是容量跟不上，一般可以考虑同时增加 TiDB Server 和 TiKV Server 节点。 + +#### 3.1.14 Percolator 用了分布式锁，crash 的客户端会保持锁，会造成锁没有 release？ + +详细可参考 [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/)。 + +#### 3.1.15 TiDB 为什么选用 gRPC 而不选用 Thrift，是因为 Google 在用吗？ + +不只是因为 Google 在用，有一些比较好的特性我们需要，比如流控、加密还有 Streaming。 + +#### 3.1.16 like(bindo.customers.name, jason%, 92) 这个92代表什么？ + +那个是转义字符，默认是 (ASCII 92)。 + +#### 3.1.17 为什么 `information_schema.tables.data_length` 记录的大小和 TiKV 监控面板上的 store size 不一样？ + +这是因为两者计算的角度不一样。`information_schema.tables.data_length` 是通过统计信息（平均每行的大小）得到的估算值。TiKV 监控面板上的 store size 是单个 TiKV 实例的数据文件（RocksDB 的 SST 文件）的大小总和。由于多版本和 TiKV 会压缩数据，所以两者显示的大小不一样。 + +### 3.2 PD 管理 + +#### 3.2.1 访问 PD 报错：TiKV cluster is not bootstrapped + +PD 的大部分 API 需要在初始化 TiKV 集群以后才能使用，如果在部署新集群的时候只启动了 PD，还没有启动 TiKV，这时候访问 PD 就会报这个错误。遇到这个错误应该先把要部署的 TiKV 启动起来，TiKV 会自动完成初始化工作，然后就可以正常访问 PD。 + +#### 3.2.2 PD 启动报错：etcd cluster ID mismatch + +PD 启动参数中的 `--initial-cluster` 包含了某个不属于该集群的成员。遇到这个错误时请检查各个成员的所属集群，剔除错误的成员后即可正常启动。 + +#### 3.2.3 PD 能容忍的时间同步误差是多少？ + +理论上，时间同步误差越小越好。PD 可容忍任意时长的误差，但是，时间同步误差越大意味着 PD 分配的时间戳与真实的物理时间相差越大，这个差距会影响读历史版本等功能。 + +#### 3.2.4 Client 连接是如何寻找 PD 的？ + +Client 连接只能通过 TiDB 访问集群，TiDB 负责连接 PD 与 TiKV，PD 与 TiKV 对 Client 透明。当 TiDB 连接任意一台 PD 的时候，PD 会告知 TiDB 当前的 leader 是谁，如果此台 PD 不是 leader，TiDB 将会重新连接至 leader PD。 + +#### 3.2.5 PD 参数中 leader-schedule-limit 和 region-schedule-limit 调度有什么区别？ + +- leader-schedule-limit 调度是用来均衡不同 TiKV 的 leader 数，影响处理查询的负载。 +- region-schedule-limit 调度是均衡不同 TiKV 的副本数，影响不同节点的数据量。 + +#### 3.2.6 每个 region 的 replica 数量可配置吗？调整的方法是？ + +可以，目前只能调整全局的 replica 数量。首次启动时 PD 会读配置文件（conf/pd.yml），使用其中的 max-replicas 配置，之后修改需要使用 pd-ctl 配置命令 `config set max-replicas $num`，配置后可通过 `config show all` 来查看已生效的配置。调整的时候，不会影响业务，会在后台添加，注意总 TiKV 实例数总是要大于等于设置的副本数，例如 3 副本需要至少 3 个 TiKV。增加副本数量之前需要预估额外的存储需求。pd-ctl 的详细用法可参考 [PD Control 使用说明](/reference/tools/pd-control.md)。 + +#### 3.2.7 缺少命令行集群管理工具，整个集群的健康度当前是否正常，不好确认？ + +可以通过 pd-ctl 等工具来判断集群大概的状态，详细的集群状态还是需要通过监控来确认。 + +#### 3.2.8 集群下线节点后，怎么删除老集群节点监控信息？ + +下线节点一般指 TiKV 节点通过 pd-ctl 或者监控判断节点是否下线完成。节点下线完成后，手动停止下线节点上相关的服务。从 Prometheus 配置文件中删除对应节点的 node_exporter 信息。从 Ansible inventory.ini 中删除对应节点的信息。 + +#### 3.2.9 使用 PD Control 连接 PD Server 时，为什么只能通过本机 IP 连接，不能通过 127.0.0.1 连接？ + +因为使用 TiDB Ansible 部署的集群，PD 对外服务端口不会绑定到 127.0.0.1，所以 PD Control 不会识别 127.0.0.1。 + +### 3.3 TiDB server 管理 + +#### 3.3.1 TiDB 的 lease 参数应该如何设置？ + +启动 TiDB Server 时，需要通过命令行参数设置 lease 参数（--lease=60），其值会影响 DDL 的速度（只会影响当前执行 DDL 的 session，其他的 session 不会受影响）。在测试阶段，lease 的值可以设为 1s，加快测试进度；在生产环境下，我们推荐这个值设为分钟级（一般可以设为 60），这样可以保证 DDL 操作的安全。 + +#### 3.3.2 DDL 在正常情况下的耗时是多少？ + +一般情况下处理一个 DDL 操作（之前没有其他 DDL 操作在处理）的耗时基本可以分如下为三种： + +- add index 操作，且此操作对应表数据行数比较少，耗时约为 3s。 +- add index 操作，且此操作对应表数据行数比较多，耗时具体由表中数据行数和当时 QPS 情况定（add index 操作优先级比一般 SQL 低）。 +- 其他 DDL 操作耗时约为 1s。 + +此外，如果接收 DDL 请求的 TiDB 和 DDL owner 所处的 TiDB 是一台，那么上面列举的第一和第三种可能的耗时应该在几十到几百毫秒。 + +#### 3.3.3 为什么有的时候执行 DDL 会很慢？ + +可能原因如下： + +- 多个 DDL 语句一起执行的时候，后面的几个 DDL 语句会比较慢。原因是当前 TiDB 集群中 DDL 操作是串行执行的。 +- 在正常集群启动后，第一个 DDL 操作的执行时间可能会比较久，一般在 30s 左右，这个原因是刚启动时 TiDB 在竞选处理 DDL 的 leader。 +- 由于停 TiDB 时不能与 PD 正常通信（包括停电情况）或者用 `kill -9` 指令停 TiDB 导致 TiDB 没有及时从 PD 清理注册数据，那么会影响 TiDB 启动后 10min 内的 DDL 语句处理时间。这段时间内运行 DDL 语句时，每个 DDL 状态变化都需要等待 2 * lease（默认 lease = 45s）。 +- 当集群中某个 TiDB 与 PD 之间发生通信问题，即 TiDB 不能从 PD 及时获取或更新版本信息，那么这时候 DDL 操作的每个状态处理需要等待 2 * lease。 + +#### 3.3.4 TiDB 可以使用 S3 作为后端存储吗？ + +不可以，目前 TiDB 只支持分布式存储引擎和 GolevelDB/RocksDB/BoltDB 引擎。 + +#### 3.3.5 Information_schema 能否支持更多真实信息？ + +Information_schema 库里面的表主要是为了兼容 MySQL 而存在，有些第三方软件会查询里面的信息。在目前 TiDB 的实现中，里面大部分只是一些空表。后续随着 TiDB 的升级，会提供更多的参数信息。当前 TiDB 支持的 Information\_schema 请参考 [TiDB 系统数据库说明文档](/reference/system-databases/information-schema.md)。 + +#### 3.3.6 TiDB Backoff type 主要原因? + +TiDB-server 与 TiKV-server 随时进行通信，在进行大量数据操作过程中，会出现 `Server is busy` 或者 `backoff.maxsleep 20000ms` 的日志提示信息，这是由于 TiKV-server 在处理过程中系统比较忙而出现的提示信息，通常这时候可以通过系统资源监控到 TiKV 主机系统资源使用率比较高的情况出现。如果这种情况出现，可以根据资源使用情况进行相应的扩容操作。 + +#### 3.3.7 TiDB TiClient type 主要原因？ + +TiClient Region Error 该指标描述的是在 TiDB-server 作为客户端通过 KV 接口访问 TiKV-server 进行数据操作过程中，TiDB-server 操作 TiKV-server 中的 Region 数据出现的错误类型与 metric 指标，错误类型包括 not_leader、stale_epoch。出现这些错误的情况是当 TiDB-server 根据自己的缓存信息去操作 Region leader 数据的时候，Region leader 发生了迁移或者 TiKV 当前的 Region 信息与 TiDB 缓存的路由信息不一致而出现的错误提示。一般这种情况下，TiDB-server 都会自动重新从 PD 获取最新的路由数据，重做之前的操作。 + +#### 3.3.8 TiDB 同时支持的最大并发连接数？ + +当前版本 TiDB 没有最大连接数的限制，如果并发过大导致响应时间增加，可以通过增加 TiDB 节点进行扩容。 + +#### 3.3.9 如何查看某张表创建的时间？ + +information_schema 库中的 tables 表里的 create_time 即为表的真实创建时间。 + +#### 3.3.9 TiDB 的日志中 EXPENSIVE_QUERY 是什么意思？ + +TiDB 在执行 SQL 时，预估出来每个 operator 处理了超过 10000 条数据就认为这条 query 是 expensive query。可以通过修改 tidb-server 配置参数来对这个门限值进行调整，调整后需要重新启动 tidb-server。 + +#### 3.3.10 在 TiDB 中如何控制或改变 SQL 提交的执行优先级？ + +TiDB 支持改变 [per-session](/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_force_priority)、[全局](/reference/configuration/tidb-server/configuration-file.md#force-priority)或单个语句的优先级。优先级包括： + +- HIGH_PRIORITY：该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句 +- LOW_PRIORITY：该语句为低优先级语句，TiDB 在执行阶段会降低这条语句的优先级 + +以上两种参数可以结合 TiDB 的 DML 语言进行使用，使用方法举例如下： + +1. 通过在数据库中写 SQL 的方式来调整优先级： + + {{< copyable "sql" >}} + + ```sql + select HIGH_PRIORITY | LOW_PRIORITY count(*) from table_name; + insert HIGH_PRIORITY | LOW_PRIORITY into table_name insert_values; + delete HIGH_PRIORITY | LOW_PRIORITY from table_name; + update HIGH_PRIORITY | LOW_PRIORITY table_reference set assignment_list where where_condition; + replace HIGH_PRIORITY | LOW_PRIORITY into table_name; + ``` + +2. 全表扫会自动调整为低优先级，analyze 也是默认低优先级。 + +#### 3.3.11 在 TiDB 中 auto analyze 的触发策略是怎样的？ + +触发策略：新表达到 1000 条，并且在 1 分钟内没有写入，会自动触发。 + +当表的（修改数/当前总行数）大于 `tidb_auto_analyze_ratio` 的时候，会自动触发 `analyze` 语句。`tidb_auto_analyze_ratio` 的默认值为 0.5，即默认开启此功能。为了保险起见，在开启此功能的时候，保证了其最小值为 0.3。但是不能大于等于 `pseudo-estimate-ratio`（默认值为 0.8），否则会有一段时间使用 pseudo 统计信息，建议设置值为 0.5。 + +#### 3.3.12 SQL 中如何通过 hint 使用一个具体的 index？ + +同 MySQL 的用法一致，例如： +`select column_name from table_name use index（index_name）where where_condition;` + +#### 3.3.13 触发 Information schema is changed 错误的原因？ + +TiDB 在执行 SQL 语句时，会使用当时的 `schema` 来处理该 SQL 语句，而且 TiDB 支持在线异步变更 DDL。那么，在执行 DML 的时候可能有 DDL 语句也在执行，而你需要确保每个 SQL 语句在同一个 `schema` 上执行。所以当执行 DML 时，遇到正在执行中的 DDL 操作就可能会报 `Information schema is changed` 的错误。为了避免太多的 DML 语句报错，已做了一些优化。 + +现在会报此错的可能原因如下（后两个报错原因与表无关）： + +- 执行的 DML 语句中涉及的表和集群中正在执行的 DDL 的表有相同的，那么这个 DML 语句就会报此错。 +- 这个 DML 执行时间很久，而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 1024 （此为默认值，可以通过 `tidb_max_delta_schema_count` 变量修改）。 +- 接受 DML 请求的 TiDB 长时间不能加载到 `schema information`（TiDB 与 PD 或 TiKV 之间的网络连接故障等会导致此问题），而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 100。 + +> **注意：** +> +> + 目前 TiDB 未缓存所有的 `schema` 版本信息。 +> + 对于每个 DDL 操作，`schema` 版本变更的数量与对应 `schema state` 变更的次数一致。 +> + 不同的 DDL 操作版本变更次数不一样。例如，`create table` 操作会有 1 次 `schema` 版本变更；`add column` 操作有 4 次 `schema` 版本变更。 + +#### 3.3.14 触发 Information schema is out of date 错误的原因？ + +当执行 DML 时，TiDB 超过一个 DDL lease 时间（默认 45s）没能加载到最新的 schema 就可能会报 `Information schema is out of date` 的错误。遇到此错的可能原因如下： + +- 执行此 DML 的 TiDB 被 kill 后准备退出，且此 DML 对应的事务执行时间超过一个 DDL lease，在事务提交时会报这个错误。 +- TiDB 在执行此 DML 时，有一段时间内连不上 PD 或者 TiKV，导致 TiDB 超过一个 DDL lease 时间没有 load schema，或者导致 TiDB 断开与 PD 之间带 keep alive 设置的连接。 + +#### 3.3.15 高并发情况下执行 DDL 时报错的原因？ + +高并发情况下执行 DDL（比如批量建表）时，极少部分 DDL 可能会由于并发执行时 key 冲突而执行失败。 + +并发执行 DDL 时，建议将 DDL 数量保持在 20 以下，否则你需要在应用端重试失败的 DDL 语句。 + +### 3.4 TiKV 管理 + +#### 3.4.1 TiKV 集群副本建议配置数量是多少，是不是最小高可用配置（3个）最好？ + +如果是测试环境 3 副本足够；在生产环境中，不可让集群副本数低于 3，需根据架构特点、业务系统及恢复能力的需求，适当增加副本数。值得注意的是，副本升高，性能会有下降，但是安全性更高。 + +#### 3.4.2 TiKV 启动报错：cluster ID mismatch + +TiKV 本地存储的 cluster ID 和指定的 PD 的 cluster ID 不一致。在部署新的 PD 集群的时候，PD 会随机生成一个 cluster ID，TiKV 第一次初始化的时候会从 PD 获取 cluster ID 存储在本地，下次启动的时候会检查本地的 cluster ID 与 PD 的 cluster ID 是否一致，如果不一致则会报错并退出。出现这个错误一个常见的原因是，用户原先部署了一个集群，后来把 PD 的数据删除了并且重新部署了新的 PD，但是 TiKV 还是使用旧的数据重启连到新的 PD 上，就会报这个错误。 + +#### 3.4.3 TiKV 启动报错：duplicated store address + +启动参数中的地址已经被其他的 TiKV 注册在 PD 集群中了。造成该错误的常见情况：TiKV `--data-dir` 指定的路径下没有数据文件夹（删除或移动后没有更新 --data-dir），用之前参数重新启动该 TiKV。请尝试用 pd-ctl 的 [store delete](https://github.com/pingcap/pd/tree/55db505e8f35e8ab4e00efd202beb27a8ecc40fb/tools/pd-ctl#store-delete--label--weight-store_id----jqquery-string) 功能，删除之前的 store，然后重新启动 TiKV 即可。 + +#### 3.4.4 TiKV master 和 slave 用的是一样的压缩算法，为什么效果不一样? + +目前来看 master 有些文件的压缩率会高一些，这个取决于底层数据的分布和 RocksDB 的实现，数据大小偶尔有些波动是正常的，底层存储引擎会根据需要调整数据。 + +#### 3.4.5 TiKV block cache 有哪些特性？ + +TiKV 使用了 RocksDB 的 Column Family (CF) 特性，KV 数据最终存储在默认 RocksDB 内部的 default、write、lock 3 个 CF 内。 + +- default CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中。 +- write CF 存储的是数据的版本信息（MVCC）、索引、小表相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中。 +- lock CF 存储的是锁信息，系统使用默认参数。 +- Raft RocksDB 实例存储 Raft log。default CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 +- 所有 CF 共享一个 Block-cache，用于缓存数据块，加速 RocksDB 的读取速度，Block-cache 的大小通过参数 `block-cache-size` 控制，`block-cache-size` 越大，能够缓存的热点数据越多，对读取操作越有利，同时占用的系统内存也会越多。 +- 每个 CF 有各自的 Write-buffer，大小通过 `write-buffer-size` 控制。 + +#### 3.4.6 TiKV channel full 是什么原因？ + +- Raftstore 线程太忙，或者因 I/O 而卡住。可以看一下 Raftstore 的 CPU 使用情况。 +- TiKV 过忙（CPU、磁盘 I/O 等），请求处理不过来。 + +#### 3.4.7 TiKV 频繁切换 Region leader 是什么原因？ + +- 网络问题导致节点间通信卡了，查看 Report failures 监控。 +- 原主 Leader 的节点卡了，导致没有及时给 Follower 发送消息。 +- Raftstore 线程卡了。 + +#### 3.4.8 如果一个节点挂了会影响服务吗？影响会持续多久？ + +TiDB 使用 Raft 在多个副本之间做数据同步（默认为每个 Region 3 个副本）。当一份备份出现问题时，其他的副本能保证数据的安全。根据 Raft 协议，当某个节点挂掉导致该节点里的 Leader 失效时，在最大 2 * lease time（leasetime 是 10 秒）时间后，通过 Raft 协议会很快将一个另外一个节点里的 Follower 选为新的 Region Leader 来提供服务。 + +#### 3.4.9 TiKV 在分别在那些场景下占用大量 IO、内存、CPU（超过参数配置的多倍）？ + +在大量写入、读取的场景中会占用大量的磁盘 IO、内存、CPU。在执行很复杂的查询，比如会产生很大中间结果集的情况下，会消耗很多的内存和 CPU 资源。 + +#### 3.4.10 TiKV 是否可以使用 SAS/SATA 盘或者进行 SSD/SAS 混合部署？ + +不可以使用，TiDB 在进行 OLTP 场景中，数据访问和操作需要高 IO 磁盘的支持，TiDB 作为强一致的分布式数据库，存在一定的写放大，如副本复制、存储底层 Compaction，因此，TiDB 部署的最佳实践中推荐用户使用 NVMe SSD 磁盘作为数据存储磁盘。另外，TiKV 与 PD 不能混合部署。 + +#### 3.4.11 数据表 Key 的 Range 范围划分是在数据接入之前就已经划分好了吗？ + +不是的，这个和 MySQL 分表规则不一样，需要提前设置好，TiKV 是根据 Region 的大小动态分裂的。 + +#### 3.4.12 Region 是如何进行分裂的？ + +Region 不是前期划分好的，但确实有 Region 分裂机制。当 Region 的大小超过参数 `region-max-size` 或 `region-max-keys` 的值时，就会触发分裂，分裂后的信息会汇报给 PD。 + +#### 3.4.13 TiKV 是否有类似 MySQL 的 `innodb_flush_log_trx_commit` 参数，来保证提交数据不丢失？ + +是的，TiKV 单机的存储引擎目前使用两个 RocksDB 实例，其中一个存储 raft-log，TiKV 有个 sync-log 参数，在 ture 的情况下，每次提交都会强制刷盘到 raft-log，如果发生 crash 后，通过 raft-log 进行 KV 数据的恢复。 + +#### 3.4.14 对 WAL 存储有什么推荐的硬件配置，例如 SSD，RAID 级别，RAID 卡 cache 策略，NUMA 设置，文件系统选择，操作系统的 IO 调度策略等？ + +WAL 属于顺序写，目前我们并没有单独对他进行配置，建议 SSD，RAID 如果允许的话，最好是 RAID 10，RAID 卡 cache、操作系统 I/O 调度目前没有针对性的最佳实践，Linux 7 以上默认配置即可，NUMA 没有特别建议，NUMA 内存分配策略可以尝试使用 `interleave = all`，文件系统建议 ext4。 + +#### 3.4.15 在最严格的 `sync-log = true` 数据可用模式下，写入性能如何？ + +一般来说，开启 `sync-log` 会让性能损耗 30% 左右。关闭 `sync-log` 时的性能表现，请参见 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 + +#### 3.4.16 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠，单机存储引擎是否需要最严格模式？ + +通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。但理论上两个节点也可能同时发生故障，所以除非是对性能要求高于数据安全的场景，一般都强烈推荐开启 `sync-log`。 + +另外，还有一种 `sync-log` 的替代方案，即在 Raft group 中用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 + +对于单机存储引擎也同样推荐打开 `sync-log` 模式。否则如果节点宕机可能会丢失最后一次写入数据。 + +#### 3.4.17 使用 Raft 协议，数据写入会有多次网络的 roundtrip，实际写入延迟如何？ + +理论上，和单机数据库相比，数据写入会多四个网络延迟。 + +#### 3.4.18 有没有类似 MySQL 的 InnoDB Memcached plugin，可以直接使用 KV 接口，可以不需要独立的 Cache？ + +TiKV 支持单独进行接口调用，理论上也可以起个实例做为 Cache，但 TiDB 最大的价值是分布式关系型数据库，我们原则上不对 TiKV 单独进行支持。 + +#### 3.4.19 Coprocessor 组件的主要作用？ + +- 减少 TiDB 与 TiKV 之间的数据传输。 +- 计算下推，充分利用 TiKV 的分布式计算资源。 + +#### 3.4.20 IO error: No space left on device While appending to file + +这是磁盘空间不足导致的，需要加节点或者扩大磁盘空间。 + +#### 3.4.21 为什么 TiKV 容易出现 OOM？ + +TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总内存的 40%。当 TiKV 容易出现 OOM 时，检查 `block-cache-size` 配置是否过高。还需要注意，当单机部署了多个 TiKV 实例时，需要显式地配置该参数，以防止多个实例占用过多系统内存导致 OOM。 + +#### 3.4.22 TiDB 数据和 RawKV 数据可存储于同一个 TiKV 集群里吗？ + +不可以。TiDB 数据（或使用其他事务 API 生成的数据）依赖于一种特殊的键值格式，和 RawKV API 数据（或其他基于 RawKV 的服务生成的数据）并不兼容。 + +### 3.5 TiDB 测试 + +#### 3.5.1 TiDB Sysbench 基准测试结果如何？ + +很多用户在接触 TiDB 都习惯做一个基准测试或者 TiDB 与 MySQL 的对比测试，官方也做了一个类似测试，汇总很多测试结果后，我们发现虽然测试的数据有一定的偏差，但结论或者方向基本一致，由于 TiDB 与 MySQL 由于架构上的差别非常大，很多方面是很难找到一个基准点，所以官方的建议两点： + +- 大家不要用过多精力纠结这类基准测试上，应该更多关注 TiDB 的场景上的区别。 +- 大家可以直接参考 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 + +#### 3.5.2 TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？ + +- 在 10 节点内，TiDB 写入能力（Insert TPS）和节点数量基本成 40% 线性递增，MySQL 由于是单节点写入，所以不具备写入扩展能力。 +- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://t.cn/RTD18qV)。 +- TiDB 不管是读流量、还是写流量都可以通过添加节点快速方便的进行扩展。 + +#### 3.5.3 我们的 DBA 测试过 MySQL 性能，单台 TiDB 的性能没有 MySQL 性能那么好？ + +TiDB 设计的目标就是针对 MySQL 单台容量限制而被迫做的分库分表的场景，或者需要强一致性和完整分布式事务的场景。它的优势是通过尽量下推到存储节点进行并行计算。对于小表（比如千万级以下），不适合 TiDB，因为数据量少，Region 有限，发挥不了并行的优势，最极端的就是计数器表，几行记录高频更新，这几行在 TiDB 里，会变成存储引擎上的几个 KV，然后只落在一个 Region 里，而这个 Region 只落在一个节点上。加上后台强一致性复制的开销，TiDB 引擎到 TiKV 引擎的开销，最后表现出来的就是没有单个 MySQL 好。 + +### 3.6 TiDB 备份恢复 + +#### 3.6.1 TiDB 主要备份方式？ + +目前，推荐的备份方式是使用 [PingCAP fork 的 Mydumper](/reference/tools/mydumper.md)。尽管 TiDB 也支持使用 MySQL 官方工具 `mysqldump` 进行数据备份、恢复，但其性能低于 [`mydumper`](/reference/tools/mydumper.md)/[`loader`](/reference/tools/loader.md)，并且该工具备份、恢复大量数量时，要耗费更多时间。 + +使用 Mydumper 导出来的数据文件尽可能的小, 最好不要超过 64M, 可以设置参数 -F 64； + +loader 的 -t 参数可以根据 TiKV 的实例个数以及负载进行评估调整，例如 3 个 TiKV 的场景， 此值可以设为 3 * (1 ～ n)，当 TiKV 负载过高，loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 可以适当调小该值，当 TiKV 负载不是太高的时候，可以适当调大该值。 + +## 四、数据、流量迁移 + +### 4.1 全量数据导出导入 + +#### 4.1.1 Mydumper + +参见 [Mydumper 使用文档](/reference/tools/mydumper.md)。 + +#### 4.1.2 Loader + +参见 [Loader 使用文档](/reference/tools/loader.md)。 + +#### 4.1.3 如何将一个运行在 MySQL 上的应用迁移到 TiDB 上？ + +TiDB 支持绝大多数 MySQL 语法，一般不需要修改代码。 + +#### 4.1.4 不小心把 MySQL 的 user 表导入到 TiDB 了，或者忘记密码，无法登录，如何处理？ + +重启 TiDB 服务，配置文件中增加 `-skip-grant-table=true` 参数，无密码登录集群后，可以根据情况重建用户，或者重建 mysql.user 表，具体表结构搜索官网。 + +#### 4.1.5 在 Loader 运行的过程中，TiDB 可以对外提供服务吗？ + +该操作进行逻辑插入，TiDB 仍可对外提供服务，但不要执行相关 DDL 操作。 + +#### 4.1.6 如何导出 TiDB 数据？ + +TiDB 目前暂时不支持 `select into outfile`，可以通过以下方式导出 TiDB 数据：参考 [MySQL 使用 mysqldump 导出某个表的部分数据](https://blog.csdn.net/xin_yu_xin/article/details/7574662)，使用 mysqldump 加 where 条件导出，使用 MySQL client 将 select 的结果输出到一个文件。 + +#### 4.1.7 如何从 DB2、Oracle 数据库迁移到 TiDB？ + +DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： + +- 使用 Oracle 官方迁移工具，如 OGG、Gateway（透明网关）、CDC（Change Data Capture）。 +- 自研数据导出导入程序实现。 +- 导出（Spool）成文本文件，然后通过 Load infile 进行导入。 +- 使用第三方数据迁移工具。 + +目前看来 OGG 最为合适。 + +#### 4.1.8 用 Sqoop 批量写入 TiDB 数据，虽然配置了 `--batch` 选项，但还是会遇到 `java.sql.BatchUpdateExecption:statement count 5001 exceeds the transaction limitation` 的错误，该如何解决？ + +- 在 Sqoop 中，`--batch` 是指每个批次提交 100 条 statement，但是默认每个 statement 包含 100 条 SQL 语句，所以此时 100 * 100 = 10000 条 SQL 语句，超出了 TiDB 的事务限制 5000 条，可以增加选项 `-Dsqoop.export.records.per.statement=10` 来解决这个问题，完整的用法如下： + + {{< copyable "shell-regular" >}} + + ```bash + sqoop export \ + -Dsqoop.export.records.per.statement=10 \ + --connect jdbc:mysql://mysql.example.com/sqoop \ + --username sqoop ${user} \ + --password ${passwd} \ + --table ${tab_name} \ + --export-dir ${dir} \ + --batch + ``` + +- 也可以选择增大 tidb 的单个事物语句数量限制，不过这个会导致内存上涨。 + +#### 4.1.9 TiDB 有像 Oracle 那样的 Flashback Query 功能么，DDL 支持么？ + +有，也支持 DDL。详细参考 [TiDB 历史数据回溯](/how-to/get-started/read-historical-data.md)。 + +### 4.2 在线数据同步 + +#### 4.2.1 Syncer 架构 + +详细参考 [解析 TiDB 在线数据同步工具 Syncer](https://pingcap.com/blog-cn/tidb-syncer/)。 + +##### 4.2.1.1 Syncer 使用文档 + +详细参考 [Syncer 使用文档](/reference/tools/syncer.md)。 + +##### 4.2.1.2 如何配置监控 Syncer 运行情况？ + +下载 [Syncer Json](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json) 导入到 Grafana，修改 Prometheus 配置文件，添加以下内容： + +- job_name: 'syncer_ops' // 任务名字 + static_configs: +- targets: ['10.10.1.1:10096'] //Syncer 监听地址与端口，通知 prometheus 拉取 Syncer 的数据。 + +重启 Prometheus 即可。 + +##### 4.2.1.3 有没有现成的同步方案，可以将数据同步到 Hbase、Elasticsearh 等其他存储？ + +没有，目前依赖程序自行实现。 + +##### 4.2.1.4 利用 Syncer 做数据同步的时候是否支持只同步部分表？ + +支持，具体参考 Syncer 使用手册 [Syncer 使用文档](/reference/tools/syncer.md) + +##### 4.2.1.5 频繁的执行 DDL 会影响 Syncer 同步速度吗？ + +频繁执行 DDL 对同步速度会有影响。对于 Sycner 来说，DDL 是串行执行的，当同步遇到了 DDL，就会以串行的方式执行，所以这种场景就会导致同步速度下降。 + +##### 4.2.1.6 使用 Syncer gtid 的方式同步时，同步过程中会不断更新 syncer.meta 文件，如果 Syncer 所在的机器坏了，导致 syncer.meta 文件所在的目录丢失，该如何处理？ + +当前 Syncer 版本的没有进行高可用设计，Syncer 目前的配置信息 syncer.meta 直接存储在硬盘上，其存储方式类似于其他 MySQL 生态工具，比如 Mydumper。因此，要解决这个问题当前可以有两个方法： + +1）把 syncer.meta 数据放到比较安全的磁盘上，例如磁盘做好 raid1； + +2）可以根据 Syncer 定期上报到 Prometheus 的监控信息来还原出历史同步的位置信息，该方法的位置信息在大量同步数据时由于延迟会可能不准确。 + +##### 4.2.1.7 Syncer 下游 TiDB 数据和 MySQL 数据不一致，DML 会退出么？ + +- 上游 MySQL 中存在数据，下游 TiDB 中该数据不存在，上游 MySQL 执行 `UPDATE` 或 `DELETE`（更新/删除）该条数据的操作时，Syncer 同步过程即不会报错退出也没有该条数据。 +- 下游有主键索引或是唯一索引冲突时，执行 `UPDATE` 会退出，执行 `INSERT` 不会退出。 + +### 4.3 业务流量迁入 + +#### 4.3.1 如何快速迁移业务流量？ + +我们建议通过 Syncer 工具搭建成多源 MySQL -> TiDB 实时同步环境，读写流量可以按照需求分阶段通过修改网络配置进行流量迁移，建议 DB 上层部署一个稳定的网络 LB（HAproxy、LVS、F5、DNS 等），这样直接修改网络配置就能实现无缝流量迁移。 + +#### 4.3.2 TiDB 总读写流量有限制吗？ + +TiDB 读流量可以通过增加 TiDB server 进行扩展，总读容量无限制，写流量可以通过增加 TiKV 节点进行扩容，基本上写容量也没有限制。 + +#### 4.3.3 Transaction too large 是什么原因，怎么解决？ + +由于分布式事务要做两阶段提交，并且底层还需要做 Raft 复制，如果一个事务非常大，会使得提交过程非常慢，并且会卡住下面的 Raft 复制流程。为了避免系统出现被卡住的情况，我们对事务的大小做了限制： + +- 单个事务包含的 SQL 语句不超过 5000 条（默认） +- 单条 KV entry 不超过 6MB +- KV entry 的总大小不超过 100MB + +在 Google 的 Cloud Spanner 上面，也有类似的[限制](https://cloud.google.com/spanner/docs/limits)。 + +#### 4.3.4 如何批量导入？ + +导入数据的时候，可以分批插入，每批最好不要超过 1w 行。 + +#### 4.3.5 TiDB 中删除数据后会立即释放空间吗？ + +DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DROP 操作，在达到 TiDB 的 GC (garbage collection) 时间后（默认 10 分钟），TiDB 的 GC 机制会删除数据并释放空间。对于 DELETE 操作 TiDB 的 GC 机制会删除数据，但不会释放空间，而是当后续数据写入 RocksDB 且进行 compact 时对空间重新利用。 + +#### 4.3.6 Load 数据时可以对目标表执行 DDL 操作吗？ + +不可以，加载数据期间不能对目标表执行任何 DDL 操作，这会导致数据加载失败。 + +#### 4.3.7 TiDB 是否支持 replace into 语法？ + +支持，但是 load data 不支持 replace into 语法。 + +#### 4.3.8 数据删除后查询速度为何会变慢？ + +大量删除数据后，会有很多无用的 key 存在，影响查询效率。目前正在开发 Region Merge 功能，完善之后可以解决这个问题，具体看参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 + +#### 4.3.9 数据删除最高效最快的方式？ + +在删除大量数据的时候，建议使用 `Delete * from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)。 + +#### 4.3.10 TiDB 如何提高数据加载速度？ + +主要有两个方面： + +- 目前已开发分布式导入工具 [Lightning](/reference/tools/tidb-lightning/overview.md)，需要注意的是数据导入过程中为了性能考虑，不会执行完整的事务流程，所以没办法保证导入过程中正在导入的数据的 ACID 约束，只能保证整个导入过程结束以后导入数据的 ACID 约束。因此适用场景主要为新数据的导入（比如新的表或者新的索引），或者是全量的备份恢复（先 Truncate 原表再导入）。 +- TiDB 的数据加载与磁盘以及整体集群状态相关，加载数据时应关注该主机的磁盘利用率，TiClient Error/Backoff/Thread CPU 等相关 metric，可以分析相应瓶颈。 + +#### 4.3.11 对数据做删除操作之后，空间回收比较慢，如何处理？ + +可以设置并行 GC，加快对空间的回收速度。默认并发为 1，最大可调整为 tikv 实例数量的 50%。可使用 `update mysql.tidb set VARIABLE_VALUE="3" where VARIABLE_NAME="tikv_gc_concurrency";` 命令来调整。 + +## 五、SQL 优化 + +### 5.1 TiDB 执行计划解读 + +详细解读 [理解 TiDB 执行计划](/reference/performance/understanding-the-query-execution-plan.md)。 + +#### 5.1.1 统计信息收集 + +详细解读 [统计信息](/reference/performance/statistics.md)。 + +#### 5.1.2 Count 如何加速？ + +Count 就是暴力扫表，提高并发度能显著的提升速度，修改并发度可以参考 `tidb_distsql_scan_concurrency` 变量，但是也要看 CPU 和 I/O 资源。TiDB 每次查询都要访问 TiKV，在数据量小的情况下，MySQL 都在内存里，TiDB 还需要进行一次网络访问。 + +提升建议： + +- 建议提升硬件配置，可以参考[部署建议](/how-to/deploy/hardware-recommendations.md)。 +- 提升并发度，默认是 10，可以提升到 50 试试，但是一般提升在 2-4 倍之间。 +- 测试大数据量的 count。 +- 调优 TiKV 配置，可以参考[性能调优](/reference/performance/tune-tikv.md)。 + +#### 5.1.3 查看当前 DDL 的进度？ + +通过 `admin show ddl` 查看当前 job 进度。操作如下： + +{{< copyable "sql" >}} + +```sql +admin show ddl; +``` + +``` +*************************** 1. row *************************** + SCHEMA_VER: 140 + OWNER: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc +RUNNING_JOBS: ID:121, Type:add index, State:running, SchemaState:write reorganization, SchemaID:1, TableID:118, RowCount:77312, ArgLen:0, start time: 2018-12-05 16:26:10.652 +0800 CST, Err:, ErrCount:0, SnapshotVersion:404749908941733890 + SELF_ID: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc +``` + +从上面操作结果可知，当前正在处理的是 `add index` 操作。且从 `RUNNING_JOBS` 列的 `RowCount` 字段可以知道当前 `add index` 操作已经添加了 77312 行索引。 + +#### 5.1.4 如何查看 DDL job？ + +可以使用 `admin show ddl` 语句查看正在运行的 DDL 作业。 + +- `admin show ddl jobs`：用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 +- `admin show ddl job queries 'job_id' [, 'job_id'] ...`：用于显示 `job_id` 对应的 DDL 任务的原始 SQL 语句。此 `job_id` 只搜索正在执行中的任务以及 DDL 历史作业队列中的最近十条结果。 + +#### 5.1.5 TiDB 是否支持基于 COST 的优化（CBO），如果支持，实现到什么程度？ + +是的，TiDB 使用的基于成本的优化器（CBO），我们有一个小组单独会对代价模型、统计信息持续优化，除此之外，我们支持 hash join、soft merge 等关联算法。 + +#### 5.1.6 如何确定某张表是否需要做 analyze ？ + +可以通过 `show stats_healthy` 来查看 Healthy 字段，一般小于等于 60 的表需要做 analyze。 + +#### 5.1.7 SQL 的执行计划展开成了树，ID 的序号有什么规律吗？这棵树的执行顺序会是怎么样的？ + +ID 没什么规律，只要是唯一就行，不过生成的时候，是有一个计数器，生成一个 plan 就加一，执行的顺序和序号无关，整个执行计划是一颗树，执行时从根节点开始，不断地向上返回数据。执行计划的理解，请参考[理解 TiDB 执行计划](/reference/performance/understanding-the-query-execution-plan.md)。 + +#### 5.1.8 TiDB 执行计划中，task cop 在一个 root 下，这个是并行的么？ + +目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指被下推到 KV 端分布式执行的计算任务，root task 是指在 TiDB 端单点执行的计算任务。一般来讲 root task 的输入数据是来自于 cop task 的；但是 root task 在处理数据的时候，TiKV 上的 cop task 也可以同时处理数据，等待 TiDB 的 root task 拉取，所以从这个观点上来看，他们是并行的；但是存在数据上下游关系；在执行的过程中，某些时间段其实也是并行的，第一个 cop task 在处理 [100, 200] 的数据，第二个 cop task 在处理 [1, 100] 的数据。执行计划的理解，请参考[理解 TiDB 执行计划](/reference/performance/understanding-the-query-execution-plan.md)。 + +## 六、数据库优化 + +### 6.1 TiDB + +#### 6.1.1 TiDB 参数及调整 + +详情参考 [TiDB 配置参数](/reference/configuration/tidb-server/configuration.md)。 + +#### 6.1.2 如何打散热点 + +TiDB 中以 Region 分片来管理数据库，通常来讲，TiDB 的热点指的是 Region 的读写访问热点。而 TiDB 中对于 PK 非整数或没有 PK 的表，可以通过设置 `SHARD_ROW_ID_BITS` 来适度分解 Region 分片，以达到打散 Region 热点的效果。详情可参考官网 [TiDB 专用系统变量和语法](/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)中 `SHARD_ROW_ID_BITS` 的介绍。 + +### 6.2 TiKV + +#### 6.2.1 TiKV 性能参数调优 + +详情参考 [TiKV 性能参数调优](/reference/performance/tune-tikv.md)。 + +## 七、监控 + +### 7.1 Prometheus 监控框架 + +详细参考 [TiDB 监控框架概述](/how-to/monitor/overview.md)。 + +### 7.2 监控指标解读 + +详细参考 [重要监控指标详解](/reference/key-monitoring-metrics/overview-dashboard.md)。 + +#### 7.2.1 目前的监控使用方式及主要监控指标，有没有更好看的监控？ + +TiDB 使用 Prometheus + Grafana 组成 TiDB 数据库系统的监控系统，用户在 Grafana 上通过 dashboard 可以监控到 TiDB 的各类运行指标，包括系统资源的监控指标，包括客户端连接与 SQL 运行的指标，包括内部通信和 Region 调度的指标，通过这些指标，可以让数据库管理员更好的了解到系统的运行状态，运行瓶颈等内容。在监控指标的过程中，我们按照 TiDB 不同的模块，分别列出了各个模块重要的指标项，一般用户只需要关注这些常见的指标项。具体指标请参见[官方文档](/reference/key-monitoring-metrics/overview-dashboard.md)。 + +#### 7.2.2 Prometheus 监控数据默认 15 天自动清除一次，可以自己设定成 2 个月或者手动删除吗？ + +可以的，在 Prometheus 启动的机器上，找到启动脚本，然后修改启动参数，然后重启 Prometheus 生效。 + +```config +--storage.tsdb.retention="60d" +``` + +#### 7.2.3 Region Health 监控项 + +TiDB-2.0 版本中，PD metric 监控页面中，对 Region 健康度进行了监控，其中 Region Health 监控项是对所有 Region 副本状况的一些统计。其中 miss 是缺副本，extra 是多副本。同时也增加了按 Label 统计的隔离级别，level-1 表示这些 Region 的副本在第一级 Label 下是物理隔离的，没有配置 location label 时所有 Region 都在 level-0。 + +#### 7.2.4 Statement Count 监控项中的 selectsimplefull 是什么意思？ + +代表全表扫，但是可能是很小的系统表。 + +#### 7.2.5 监控上的 QPS 和 Statement OPS 有什么区别？ + +QPS 会统计执行的所有 SQL 命令，包括 use database、load data、begin、commit、set、show、insert、select 等。 + +Statement OPS 只统计 select、update、insert 等业务相关的，所以 Statement OPS 的统计和业务比较相符。 + +## 八、Cloud TiDB + +### 8.1 腾讯云 + +#### 8.1.1 目前 Cloud TiDB 都有那些云厂商？ + +Cloud TiDB 目前已经在腾讯云、UCloud 上线，都是数据库一级入口，欢迎大家使用。 + +## 九、故障排除 + +### 9.1 TiDB 自定义报错汇总 + +#### 9.1.1 ERROR 8005 (HY000) : Write Conflict, txnStartTS is stale + +可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 + +#### 9.1.2 ERROR 9001 (HY000) : PD Server Timeout + +请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络。 + +#### 9.1.3 ERROR 9002 (HY000) : TiKV Server Timeout + +请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络。 + +#### 9.1.4 ERROR 9003 (HY000) : TiKV Server is Busy + +TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志。 + +#### 9.1.5 ERROR 9004 (HY000) : Resolve Lock Timeout + +清理锁超时，当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码是否有锁争用。 + +#### 9.1.6 ERROR 9005 (HY000) : Region is unavailable + +访问的 Region 不可用，某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志。 + +#### 9.1.7 ERROR 9006 (HY000) : GC life time is shorter than transaction duration + +`GC Life Time` 间隔时间过短，长事务本应读到的数据可能被清理了，可使用如下命令增加 `GC Life Time`： + +{{< copyable "sql" >}} + +```sql +update mysql.tidb set variable_value='30m' where variable_name='tikv_gc_life_time'; +``` + +其中 30m 代表仅清理 30 分钟前的数据，这可能会额外占用一定的存储空间。 + +#### 9.1.8 ERROR 9007 (HY000) : Write Conflict + +可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 + +### 9.2 MySQL 原生报错汇总 + +#### 9.2.1 ERROR 2013 (HY000): Lost connection to MySQL server during query 问题的排查方法？ + +- log 中是否有 panic +- dmesg 中是否有 oom，命令：`dmesg -T | grep -i oom` +- 长时间没有访问，也会收到这个报错，一般是 tcp 超时导致的，tcp 长时间不用, 会被操作系统 kill。 + +#### 9.2.2 ERROR 1105 (HY000): other error: unknown error Wire Error(InvalidEnumValue(4004)) 是什么意思？ + +这类问题一般是 TiDB 和 TiKV 版本不匹配，在升级过程尽量一起升级，避免版本 mismatch。 + +#### 9.2.3 ERROR 1148 (42000): the used command is not allowed with this TiDB version 问题的处理方法？ + +这个问题是因为在执行 `LOAD DATA LOCAL` 语句的时候，MySQL 客户端不允许执行此语句（即 `local_infile` 选项为 0）。解决方法是在启动 MySQL 客户端时，用 `--local-infile=1` 选项。具体启动指令类似：`mysql --local-infile=1 -u root -h 127.0.0.1 -P 4000`。有些 MySQL 客户端需要设置而有些不需要设置，原因是不同版本的 MySQL 客户端对 `local-infile` 的默认值不同。 + +#### 9.2.4 ERROR 9001 (HY000): PD server timeout start timestamp may fall behind safe point + +这个报错一般是 TiDB 访问 PD 出了问题，TiDB 后台有个 worker 会不断地从 PD 查询 safepoint，如果超过 100s 查不成功就会报这个错。一般是因为 PD 磁盘操作过忙、反应过慢，或者 TiDB 和 PD 之间的网络有问题。TiDB 常见错误码请参考[错误码与故障诊断](/reference/error-codes.md)。 + +### 9.3 TiDB 日志中的报错信息 + +#### 9.3.1 EOF + +当客户端或者 proxy 断开连接时，TiDB 不会立刻察觉连接已断开，而是等到开始往连接返回数据时，才发现连接已断开，此时日志会打印 EOF 错误。 diff --git a/dev/faq/upgrade.md b/faq/upgrade.md similarity index 100% rename from dev/faq/upgrade.md rename to faq/upgrade.md diff --git a/dev/glossary.md b/glossary.md similarity index 100% rename from dev/glossary.md rename to glossary.md diff --git a/dev/how-to/configure/memory-control.md b/how-to/configure/memory-control.md similarity index 100% rename from dev/how-to/configure/memory-control.md rename to how-to/configure/memory-control.md diff --git a/dev/how-to/configure/time-zone.md b/how-to/configure/time-zone.md similarity index 100% rename from dev/how-to/configure/time-zone.md rename to how-to/configure/time-zone.md diff --git a/how-to/deploy/data-migration-with-ansible.md b/how-to/deploy/data-migration-with-ansible.md new file mode 100644 index 000000000000..5ca68e4fbe2d --- /dev/null +++ b/how-to/deploy/data-migration-with-ansible.md @@ -0,0 +1,570 @@ +--- +title: 使用 DM-Ansible 部署 DM 集群 +category: how-to +--- + +# 使用 DM-Ansible 部署 DM 集群 + +DM-Ansible 是 PingCAP 基于 [Ansible](https://docs.ansible.com/ansible/latest/index.html) 的 [Playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html#about-playbooks) 研发的 DM (Data Migration) 集群部署工具。本文将介绍如何使用 DM-Ansible 快速部署 DM 集群。 + +## 准备工作 + +在开始之前，先确保您准备好了以下配置的机器： + +1. 部署目标机器若干，配置如下： + + - CentOS 7.3 (64-bit) 或更高版本，x86_64 架构（AMD64） + - 机器之间内网互通 + - 关闭防火墙，或开放服务端口 + +2. 一台中控机，配置如下： + + - 包含 Python 2.7 的 CentOS 7.3（64-bit）或更高版本 + - Ansible 2.5 或更高版本 + - 互联网访问 + +## 第 1 步：在中控机上安装依赖包 + +> **注意：** +> +> 请确保使用 `root` 账户登录中控机。 + +根据中控机的操作系统版本，运行相应命令如下： + +- CentOS 7： + + {{< copyable "shell-root" >}} + + ```bash + yum -y install epel-release git curl sshpass && + yum -y install python-pip + ``` + +- Ubuntu： + + {{< copyable "shell-root" >}} + + ```bash + apt-get -y install git curl sshpass python-pip + ``` + +## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH 密钥 + +> **注意：** +> +> 请确保使用 `root` 账户登录中控机。 + +1. 创建 `tidb` 用户。 + + {{< copyable "shell-root" >}} + + ```bash + useradd -m -d /home/tidb tidb + ``` + +2. 为 `tidb` 用户设置密码。 + + {{< copyable "shell-root" >}} + + ```bash + passwd tidb + ``` + +3. 在 sudo 文件尾部加上 `tidb ALL=(ALL) NOPASSWD: ALL`，为 `tidb` 用户设置免密使用 sudo。 + + {{< copyable "shell-root" >}} + + ```bash + visudo + ``` + + ``` + tidb ALL=(ALL) NOPASSWD: ALL + ``` + +4. 生成 SSH 密钥。 + + 执行以下 `su` 命令，将登录用户从 `root` 切换至 `tidb`。 + + {{< copyable "shell-root" >}} + + ```bash + su - tidb + ``` + + 为 `tidb` 用户创建 SSH 密钥。当提示 `Enter passphrase` 时，按 Enter 键。命令成功执行后，生成的 SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为`/home/tidb/.ssh/id_rsa.pub`。 + + {{< copyable "shell-regular" >}} + + ```bash + ssh-keygen -t rsa + ``` + + ``` + Generating public/private rsa key pair. + Enter file in which to save the key (/home/tidb/.ssh/id_rsa): + Created directory '/home/tidb/.ssh'. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /home/tidb/.ssh/id_rsa. + Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. + The key fingerprint is: + SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 + The key's randomart image is: + +---[RSA 2048]----+ + |=+o+.o. | + |o=o+o.oo | + | .O.=.= | + | . B.B + | + |o B * B S | + | * + * + | + | o + . | + | o E+ . | + |o ..+o. | + +----[SHA256]-----+ + ``` + +## 第 3 步：下载 DM-Ansible 至中控机 + +> **注意：** +> +> 请确保使用 `tidb` 账户登录中控机。 + +1. 打开 `/home/tidb` 目录。 +2. 执行以下命令下载 DM-Ansible。 + + {{< copyable "shell-regular" >}} + + ```bash + wget https://download.pingcap.org/dm-ansible-{version}.tar.gz + ``` + + `{version}` 为期望下载的 DM 版本，如 `v1.0.1`、`v1.0.2` 等， + 可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 + +## 第 4 步：安装 DM-Ansible 及其依赖至中控机 + +> **注意：** +> +> - 请确保使用 `tidb` 账户登录中控机。 +> - 您需要使用 `pip` 方式下载安装 Ansible 及其依赖，否则可能会遇到兼容性问题。 DM-Ansible 当前与 Ansible 2.5 或更高版本兼容。 + +1. 在中控机上安装 DM-Ansible 及其依赖包： + + {{< copyable "shell-regular" >}} + + ```bash + tar -xzvf dm-ansible-{version}.tar.gz && + mv dm-ansible-{version} dm-ansible && + cd /home/tidb/dm-ansible && + sudo pip install -r ./requirements.txt + ``` + + Ansible 和相关依赖包含于 `dm-ansible/requirements.txt` 文件中。 + +2. 查看 Ansible 版本： + + {{< copyable "shell-regular" >}} + + ```bash + ansible --version + ``` + + ``` + ansible 2.5.0 + ``` + +## 第 5 步：在中控机上配置 SSH 互信和 sudo 规则 + +> **注意：** +> +> 请确保使用 `tidb` 账户登录至中控机。 + +1. 将您部署的目标机器的 IP 地址加至 `hosts.ini` 文件中的 `[servers]` 部分。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/dm-ansible && + vi hosts.ini + ``` + + ``` + [servers] + 172.16.10.71 + 172.16.10.72 + 172.16.10.73 + + [all:vars] + username = tidb + ``` + +2. 运行如下命令，然后输入部署目标机器的 `root` 用户密码。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook -i hosts.ini create_users.yml -u root -k + ``` + + 该步骤将在部署目标机器上创建 `tidb` 用户，创建 sudo 规则，并为中控机和部署目标机器之间配置 SSH 互信。 + +## 第 6 步：下载 DM 及监控组件安装包至中控机 + +> **注意：** +> +> 请确保中控机接入互联网。 + +在中控机上，运行如下命令： + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook local_prepare.yml +``` + +## 第 7 步：编辑 `inventory.ini` 配置文件 + +> **注意：** +> +> 请确保使用 `tidb` 账户登录中控机。 + +打开并编辑 `/home/tidb/dm-ansible/inventory.ini` 文件如下，以管控 DM 集群。 + +```ini +dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 +``` + +根据场景需要，您可以在以下两种集群拓扑中任选一种： + +- [单节点上单个 DM-worker 实例的集群拓扑](#选项-1使用单节点上单个-dm-worker-实例的集群拓扑) +- [单节点上多个 DM-worker 实例的集群拓扑](#选项-2使用单节点上多个-dm-worker-实例的集群拓扑) + +通常情况下，我们推荐每个节点上部署单个 DM-Worker 实例。但如果您的机器拥有性能远超 [TiDB 软件和硬件环境要求](/how-to/deploy/hardware-recommendations.md)中推荐配置的 CPU 和内存，并且每个节点配置 2 块以上的硬盘或大于 2T 的 SSD，您可以在单个节点上部署不超过 2 个 DM-Worker 实例。 + +### 选项 1：使用单节点上单个 DM-Worker 实例的集群拓扑 + +| 节点 | 主机 IP | 服务 | +| ---- | ------- | -------- | +| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | +| node2 | 172.16.10.72 | DM-worker1 | +| node3 | 172.16.10.73 | DM-worker2 | +| mysql-replica-01| 172.16.10.81 | MySQL | +| mysql-replica-02| 172.16.10.82 | MySQL | + +```ini +# DM 模块 +[dm_master_servers] +dm_master ansible_host=172.16.10.71 + +[dm_worker_servers] +dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + +dm_worker2 ansible_host=172.16.10.73 server_id=102 source_id="mysql-replica-02" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + +[dm_portal_servers] +dm_portal ansible_host=172.16.10.71 + +# 监控模块 +[prometheus_servers] +prometheus ansible_host=172.16.10.71 + +[grafana_servers] +grafana ansible_host=172.16.10.71 + +[alertmanager_servers] +alertmanager ansible_host=172.16.10.71 + +# 全局变量 +[all:vars] +cluster_name = test-cluster + +ansible_user = tidb + +dm_version = {version} + +deploy_dir = /data1/dm + +grafana_admin_user = "admin" +grafana_admin_password = "admin" +``` + +`{version}` 为当前 DM-Ansible 对应的版本号。关于 DM-worker 参数的更多信息，请参考 [DM-worker 配置及参数描述](#dm-worker-配置及参数描述)。 + +### 选项 2：使用单节点上多个 DM-worker 实例的集群拓扑 + +| 节点 | 主机 IP | 服务 | +| ---- | ------- | -------- | +| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | +| node2 | 172.16.10.72 | DM-worker1-1, DM-worker1-2 | +| node3 | 172.16.10.73 | DM-worker2-1, DM-worker2-2 | + +编辑 `inventory.ini` 文件时，请注意区分这些变量：`server_id`，`deploy_dir`，和 `dm_worker_port`。 + +```ini +# DM 模块 +[dm_master_servers] +dm_master ansible_host=172.16.10.71 + +[dm_worker_servers] +dm_worker1_1 ansible_host=172.16.10.72 server_id=101 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 +dm_worker1_2 ansible_host=172.16.10.72 server_id=102 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + +dm_worker2_1 ansible_host=172.16.10.73 server_id=103 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 +dm_worker2_2 ansible_host=172.16.10.73 server_id=104 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.84 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + +[dm_portal_servers] +dm_portal ansible_host=172.16.10.71 + +# 监控模块 +[prometheus_servers] +prometheus ansible_host=172.16.10.71 + +[grafana_servers] +grafana ansible_host=172.16.10.71 + +[alertmanager_servers] +alertmanager ansible_host=172.16.10.71 + +# 全局变量 +[all:vars] +cluster_name = test-cluster + +ansible_user = tidb + +dm_version = {version} + +deploy_dir = /data1/dm + +grafana_admin_user = "admin" +grafana_admin_password = "admin" +``` + +`{version}` 为当前 DM-Ansible 对应的版本号。 + +### DM-worker 配置及参数描述 + +| 变量名称 | 描述 | +| ------------- | ------- +| source_id | DM-worker 绑定到的一个数据库实例或是具有主从架构的复制组。当发生主从切换的时候，只需要更新 `mysql_host` 或 `mysql_port` 而不用更改该 ID 标识。 | +| server_id | DM-worker 伪装成一个 MySQL slave，该变量即为这个 slave 的 server ID，在 MySQL 集群中需保持全局唯一。取值范围 0 ~ 4294967295。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置。 | +| mysql_host | 上游 MySQL 主机。 | +| mysql_user | 上游 MySQL 用户名，默认值为 “root”。| +| mysql_password | 上游 MySQL 用户密码，需使用 `dmctl` 工具加密。请参考[使用 dmctl 加密上游 MySQL 用户密码](#使用-dmctl-加密上游-mysql-用户密码)。 | +| mysql_port | 上游 MySQL 端口， 默认 3306。 | +| enable_gtid | DM-worker 是否使用全局事务标识符（GTID）拉取 binlog。使用前提是在上游 MySQL 已开启 GTID 模式。 | +| relay_binlog_name | DM-worker 是否从指定 binlog 文件位置开始拉取 binlog。仅适用于本地无有效 relay log 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。| +| relay_binlog_gtid | DM-worker 是否从指定 GTID 位置开始拉取 binlog。仅适用于本地无有效 relay log，且 `enable_gtid` 设置为 true 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | +| flavor | 代表 MySQL 的版本发布类型。 如果是官方版本，Percona 版，或 Cloud MySQL 版，其值为 “mysql”。 如果是 MariaDB，其值为 "mariadb"。默认值是 "mysql"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置。 | + +关于 `deploy_dir` 配置的更多信息，请参考[配置部署目录](#配置部署目录)。 + +### 使用 dmctl 加密上游 MySQL 用户密码 + +假定上游 MySQL 的用户密码为 `123456`，运行以下命令，并将生成的字符串添加至 DM-worker 的 `mysql_password` 变量。 + +{{< copyable "shell-regular" >}} + +```bash +cd /home/tidb/dm-ansible/resources/bin && +./dmctl -encrypt 123456 +``` + +``` +VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= +``` + +## 第 8 步：编辑 `inventory.ini` 文件中的变量 + +此步介绍如何编辑部署目录中的变量，如何配置 relay log 同步位置以及 relay log GTID 的同步模式。此外，还会描述 `inventory.ini` 中的全局变量。 + +### 配置部署目录 + +编辑 `deploy_dir` 变量以配置部署目录。 + +- 全局变量默认设为 `/home/tidb/deploy`，适用于所有服务。如果数据盘挂载于 `/data1` 目录，您可以通过以下修改将其变更至 `/data1/dm`。 + + ```ini + ## Global variables. + [all:vars] + deploy_dir = /data1/dm + ``` + +- 如果需要为某个服务创建单独的部署目录，您可以在 `inventory.ini` 中配置服务主机列表的同时设置 host 变量。此操作需要您添加第一列别名，以避免在混合服务部署场景下产生混淆。 + + ```ini + dm-master ansible_host=172.16.10.71 deploy_dir=/data1/deploy + ``` + +### 配置 relay log 同步位置 + +首次启动 DM-worker 时，您需要配置 `relay_binlog_name` 变量以指定 DM-worker 拉取上游 MySQL 或 MariaDB binlog 的起始位置。 + +```yaml +[dm_worker_servers] +dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 relay_binlog_name="binlog.000011" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + +dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name="binlog.000002" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 +``` + +> **注意：** +> +> 如未设定 `relay_binlog_name`，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 + +### 开启 relay log GTID 同步模式 + +在 DM 集群中，DM-worker 的 relay log 处理单元负责与上游 MySQL 或 MariaDB 通信，从而将 binlog 拉取至本地文件系统。 + +DM 目前支持 MySQL GTID 和 MariaDB GTID。您可以通过配置以下项目开启 relay log GTID 同步模式： + +- `enable_gtid`：打开 relay log GTID 同步模式以处理 master 和 slave 易位的场景 + +- `relay_binlog_gtid`：指定 DM-worker 开始拉取对应上游 MySQL 或 MariaDB binlog 的起始位置 + +示例配置如下： + +```yaml +[dm_worker_servers] +dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 enable_gtid=true relay_binlog_gtid="aae3683d-f77b-11e7-9e3b-02a495f8993c:1-282967971,cc97fa93-f5cf-11e7-ae19-02915c68ee2e:1-284361339" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + +dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name=binlog.000002 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 +``` + +### 全局变量 + +| 变量名称 | 描述 | +| --------------- | ---------------------------------------------------------- | +| cluster_name | 集群名称，可调整 | +| dm_version | DM 版本，默认已配置 | +| grafana_admin_user | Grafana 管理员用户名称，默认值 `admin` | +| grafana_admin_password | Grafana 管理员账户的密码，用于通过 Ansible 导入 Dashboard。默认值为 `admin`。如果您在 Grafana 网页端修改了密码，请更新此变量。 | + +## 第 9 步：部署 DM 集群 + +使用 `ansible-playbook` 运行 Playbook，默认并发数量是 5。如果部署目标机器较多，您可以使用 `-f` 参数增加并发数量，例如，`ansible-playbook deploy.yml -f 10`。 + +以下部署操作示例使用中运行服务的用户为 `tidb`： + +1. 编辑 `dm-ansible/inventory.ini` 文件，确保 `ansible_user = tidb`。 + + ```ini + ansible_user = tidb + ``` + + > **注意：** + > + > 请勿将 `ansible_user` 设为 `root`，因为 `tidb-ansible` 限制服务需以普通用户运行。 + + 运行以下命令。如果所有服务都返回 `tidb`，则 SSH 互信配置成功。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible -i inventory.ini all -m shell -a 'whoami' + ``` + + 运行以下命令。如果所有服务都返回 `root`，则 `tidb` 用户免密 sudo 操作配置成功。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible -i inventory.ini all -m shell -a 'whoami' -b + ``` + +2. 修改内核参数，并部署 DM 集群组件和监控组件。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml + ``` + +3. 启动 DM 集群。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml + ``` + + 此操作会按顺序启动 DM 集群的所有组件，包括 DM-master，DM-worker，以及监控组件。当一个 DM 集群被关闭后，您可以使用该命令将其开启。 + +## 第 10 步：关闭 DM 集群 + +如果您需要关闭一个 DM 集群，运行以下命令： + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook stop.yml +``` + +该操作会按顺序关闭整个 DM 集群中的所有组件，包括 DM-master，DM-worker，以及监控组件。 + +## 常见部署问题 + +### 默认服务端口 + +| 组件 | 端口变量 | 默认端口 | 描述 | +| :-- | :-- | :-- | :-- | +| DM-master | `dm_master_port` | 8261 | DM-master 服务交流端口 | +| DM-worker | `dm_worker_port` | 8262 | DM-worker 服务交流端口 | +| Prometheus | `prometheus_port` | 9090 | Prometheus 服务交流端口 | +| Grafana | `grafana_port` | 3000 | 外部 Web 监控服务及客户端（浏览器）访问端口 | +| Alertmanager | `alertmanager_port` | 9093 | Alertmanager 服务交流端口 | + +### 自定义端口 + +编辑 `inventory.ini` 文件，将服务端口的相关主机变量添加在对应服务 IP 地址后： + +```ini +dm_master ansible_host=172.16.10.71 dm_master_port=18261 +``` + +### 更新 DM-Ansible + +1. 使用 `tidb` 账户登录至中控机，进入 `/home/tidb` 目录，然后备份`dm-ansible` 文件夹。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb && \ + mv dm-ansible dm-ansible-bak + ``` + +2. 下载指定版本 DM-Ansible，解压。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb && \ + wget https://download.pingcap.org/dm-ansible-{version}.tar.gz && \ + tar -xzvf dm-ansible-{version}.tar.gz && \ + mv dm-ansible-{version} dm-ansible + ``` + +3. 迁移 `inventory.ini` 配置文件。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb && \ + cp dm-ansible-bak/inventory.ini dm-ansible/inventory.ini + ``` + +4. 迁移 `dmctl` 配置。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/dm-ansible-bak/dmctl && \ + cp * /home/tidb/dm-ansible/dmctl/ + ``` + +5. 用 Playbook 下载最新的 DM 二进制文件。此文件会自动替换 `/home/tidb/dm-ansible/resource/bin/` 目录下的二进制文件。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook local_prepare.yml + ``` diff --git a/how-to/deploy/data-migration-with-binary.md b/how-to/deploy/data-migration-with-binary.md new file mode 100644 index 000000000000..d01ad5dacefd --- /dev/null +++ b/how-to/deploy/data-migration-with-binary.md @@ -0,0 +1,306 @@ +--- +title: 使用 DM binary 部署 DM 集群 +category: how-to +--- + +# 使用 DM binary 部署 DM 集群 + +本文将介绍如何使用 DM binary 快速部署 DM 集群。 + +## 准备工作 + +下载官方 binary，链接地址：[DM 下载](/reference/tools/download.md#tidb-dm-data-migration)。 + +下载的文件中包括子目录 bin 和 conf。bin 目录下包含 dm-master、dm-worker、dmctl 以及 Mydumper 的二进制文件。conf 目录下有相关的示例配置文件。 + +## 使用样例 + +假设在两台服务器上部署 MySQL，在一台服务器上部署 TiDB（mocktikv 模式），另外在三台服务器上部署两个 DM-worker 实例和一个 DM-master 实例。各个节点的信息如下： + +| 实例 | 服务器地址 | +| :---------- | :----------- | +| MySQL1 | 192.168.0.1 | +| MySQL2 | 192.168.0.2 | +| TiDB | 192.168.0.3 | +| DM-master | 192.168.0.4 | +| DM-worker1 | 192.168.0.5 | +| DM-worker2 | 192.168.0.6 | + +MySQL1 和 MySQL2 中需要开启 binlog。DM-worker1 负责同步 MySQL1 的数据，DM-worker2 负责同步 MySQL2 的数据。下面以此为例，说明如何部署 DM。 + +### DM-worker 的部署 + +DM-worker 需要连接上游 MySQL，且为了安全，强制用户配置加密后的密码。首先使用 dmctl 对 MySQL 的密码进行加密，以密码为 "123456" 为例： + +{{< copyable "shell-regular" >}} + +```bash +./bin/dmctl --encrypt "123456" +``` + +``` +fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg= +``` + +记录该加密后的值，用于下面部署 DM-worker 时的配置。 + +DM-worker 提供命令行参数和配置文件两种配置方式。 + +**配置方式 1：命令行参数** + +查看 DM-worker 的命令行参数说明： + +{{< copyable "shell-regular" >}} + +```bash +./bin/dm-worker --help +``` + +``` +Usage of worker: + -L string + 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值："info"） + -V 输出版本信息 + -checker-backoff-max duration + 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔（默认值："5m0s"，一般情况下不需要修改。如果对该参数的作用没有深入的了解，不建议修改该参数） + -checker-backoff-rollback duration + 任务检查模块中，调整自动恢复等待时间的间隔（默认值："5m0s"，一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改该参数） + -checker-check-enable + 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务（默认值：true） + -config string + 配置文件的路径 + -log-file string + 日志文件的路径 + -print-sample-config + 打印示例配置 + -purge-expires int + relay log 的过期时间。DM-worker 会尝试自动删除最后修改时间超过了过期时间的 relay log（单位：小时） + -purge-interval int + 定期检查 relay log 是否过期的间隔时间（默认值：3600）（单位：秒） + -purge-remain-space int + 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log（默认值：15）（单位：GB） + -relay-dir string + 存储 relay log 的路径（默认值："./relay_log"） + -worker-addr string + DM-worker 的地址 +``` + +> **注意：** +> +> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 + +**配置方式 2：配置文件** + +推荐使用配置文件来配置 DM-worker，把以下配置文件内容写入到 `conf/dm-worker1.toml` 中。 + +DM-worker 的配置文件： + +```toml +# Worker Configuration. + +# 日志配置 +log-level = "info" +log-file = "dm-worker.log" + +# DM-worker 的地址 +worker-addr = ":8262" + +# 作为 MySQL slave 的 server ID，用于获取 MySQL 的 binlog +# 在一个 replication group 中，每个实例（master 和 slave）都应该有唯一的 server ID +# v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置 +server-id = 101 + +# 用于标识一个 replication group 或者 MySQL/MariaDB 实例 +source-id = "mysql-replica-01" + +# 上游实例类型，值可为 "mysql" 或者 "mariadb" +# v1.0.2 及以上版本的 DM 会自动识别上游实例类型，不需要手动配置 +flavor = "mysql" + +# MySQL 的连接地址 +[from] +host = "192.168.0.1" +user = "root" +password = "fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg=" +port = 3306 +``` + +在终端中使用下面的命令运行 DM-worker： + +{{< copyable "shell-regular" >}} + +```bash +bin/dm-worker -config conf/dm-worker1.toml +``` + +对于 DM-worker2，修改配置文件中的 `source-id` 为 `mysql-replica-02`，并将 `from` 配置部分修改为 MySQL2 的地址即可。如果因为没有多余的机器，将 DM-worker2 与 DM-worker1 部署在一台机器上，需要把两个 DM-worker 实例部署在不同的路径下，否则保存元信息和 relay log 的默认路径会冲突。 + +### DM-master 的部署 + +DM-master 提供命令行参数和配置文件两种配置方式。 + +**配置方式 1：命令行参数** + +DM-master 的命令行参数说明： + +```bash +./bin/dm-master --help +``` + +``` +Usage of dm-master: + -L string + 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值为 "info"） + -V 输出版本信息 + -config string + 配置文件的路径 + -log-file string + 日志文件的路径 + -master-addr string + DM-master 的地址 + -print-sample-config + 打印出 DM-master 的示例配置 +``` + +> **注意：** +> +> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 + +**配置方式 2：配置文件** + +推荐使用配置文件，把以下配置文件内容写入到 `conf/dm-master.toml` 中。 + +DM-master 的配置文件： + +```toml +# Master Configuration. + +# 日志配置 +log-level = "info" +log-file = "dm-master.log" + +# DM-master 监听地址 +master-addr = ":8261" + +# DM-Worker 的配置 +[[deploy]] +# 对应 DM-worker1 配置文件中的 source-id +source-id = "mysql-replica-01" +# DM-worker1 的服务地址 +dm-worker = "192.168.0.5:8262" + +[[deploy]] +# 对应 DM-worker2 配置文件中的 source-id +source-id = "mysql-replica-02" +# DM-worker2 的服务地址 +dm-worker = "192.168.0.6:8262" +``` + +在终端中使用下面的命令运行 DM-master： + +{{< copyable "shell-regular" >}} + +```bash +bin/dm-master -config conf/dm-master.toml +``` + +这样，DM 集群就部署成功了。下面创建简单的数据同步任务来使用 DM 集群。 + +### 创建数据同步任务 + +假设在 MySQL1 和 MySQL2 实例中有若干个分表，这些分表的结构相同，所在库的名称都以 "sharding" 开头，表名称都以 "t" 开头，并且主键或唯一键不存在冲突（即每张分表的主键或唯一键各不相同）。现在需要把这些分表同步到 TiDB 中的 `db_target.t_target` 表中。 + +首先创建任务的配置文件： + +{{< copyable "" >}} + +```yaml +--- +name: test +task-mode: all +is-sharding: true + +target-database: + host: "192.168.0.3" + port: 4000 + user: "root" + password: "" # 如果密码不为空，也需要配置 dmctl 加密后的密码 + +mysql-instances: + - source-id: "mysql-replica-01" + black-white-list: "instance" + route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] + mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 + loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 + syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 + + - source-id: "mysql-replica-02" + black-white-list: "instance" + route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] + mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 + loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 + syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 + +black-white-list: + instance: + do-dbs: ["~^sharding[\\d]+"] + do-tables: + - db-name: "~^sharding[\\d]+" + tbl-name: "~^t[\\d]+" + +routes: + sharding-route-rules-table: + schema-pattern: sharding* + table-pattern: t* + target-schema: db_target + target-table: t_target + + sharding-route-rules-schema: + schema-pattern: sharding* + target-schema: db_target +``` + +将以上配置内容写入到 `conf/task.yaml` 文件中，使用 dmctl 创建任务： + +{{< copyable "shell-regular" >}} + +```bash +bin/dmctl -master-addr 192.168.0.4:8261 +``` + +``` +Welcome to dmctl +Release Version: v1.0.0-69-g5134ad1 +Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 +Git Branch: master +UTC Build Time: 2019-04-29 09:36:42 +Go Version: go version go1.12 linux/amd64 +» +``` + +{{< copyable "" >}} + +```bash +» start-task conf/task.yaml +``` + +``` +{ + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "192.168.0.5:8262", + "msg": "" + }, + { + "result": true, + "worker": "192.168.0.6:8262", + "msg": "" + } + ] +} +``` + +这样就成功创建了一个将 MySQL1 和 MySQL2 实例中的分表数据同步到 TiDB 的任务。 diff --git a/how-to/deploy/geographic-redundancy/location-awareness.md b/how-to/deploy/geographic-redundancy/location-awareness.md new file mode 100644 index 000000000000..27c8980019e7 --- /dev/null +++ b/how-to/deploy/geographic-redundancy/location-awareness.md @@ -0,0 +1,95 @@ +--- +title: 集群拓扑信息配置 +category: how-to +--- + +# 集群拓扑信息配置 + +## 概述 + +PD 能够根据 TiKV 集群的拓扑结构进行调度，使得 TiKV 的容灾能力最大化。 + +阅读本章前，请先确保阅读 [Ansible 部署方案](/how-to/deploy/orchestrated/ansible.md) 和 [Docker 部署方案](/how-to/deploy/orchestrated/docker.md)。 + +## TiKV 上报拓扑信息 + +可以通过 TiKV 的启动参数或者配置文件来让 TiKV 上报拓扑信息给 PD。 + +假设拓扑结构分为三级：zone > rack > host，可以通过 labels 来指定这些信息。 + +启动参数： + +``` +tikv-server --labels zone=,rack=,host= +``` + +配置文件： + +{{< copyable "" >}} + +```toml +[server] +labels = "zone=,rack=,host=" +``` + +## PD 理解 TiKV 拓扑结构 + +可以通过 PD 的配置文件让 PD 理解 TiKV 集群的拓扑结构。 + +{{< copyable "" >}} + +```toml +[replication] +max-replicas = 3 +location-labels = ["zone", "rack", "host"] +``` + +其中 `location-labels` 需要与 TiKV 的 `labels` 名字对应，这样 PD 才能知道这些 `labels` 代表了 TiKV 的拓扑结构。 + +> **注意：** +> +> 必须同时配置 PD 的 `location-labels` 和 TiKV 的 `labels` 参数，否则 `labels` 不会生效。 + +## PD 基于 TiKV 拓扑结构进行调度 + +PD 能够根据我们提供的拓扑信息作出最优的调度，我们只需要关心什么样的拓扑结构能够达到我们想要的效果。 + +假设我们使用三副本，并且希望一个数据中心挂掉的情况下，还能继续保持 TiDB 集群的高可用状态，我们至少需要四个数据中心。 + +假设我们有四个数据中心 (zone)，每个数据中心有两个机架 (rack)，每个机架上有两个主机 (host)。 +每个主机上面启动一个 TiKV 实例： + +``` +# zone=z1 +tikv-server --labels zone=z1,rack=r1,host=h1 +tikv-server --labels zone=z1,rack=r1,host=h2 +tikv-server --labels zone=z1,rack=r2,host=h1 +tikv-server --labels zone=z1,rack=r2,host=h2 + +# zone=z2 +tikv-server --labels zone=z2,rack=r1,host=h1 +tikv-server --labels zone=z2,rack=r1,host=h2 +tikv-server --labels zone=z2,rack=r2,host=h1 +tikv-server --labels zone=z2,rack=r2,host=h2 + +# zone=z3 +tikv-server --labels zone=z3,rack=r1,host=h1 +tikv-server --labels zone=z3,rack=r1,host=h2 +tikv-server --labels zone=z3,rack=r2,host=h1 +tikv-server --labels zone=z3,rack=r2,host=h2 + +# zone=z4 +tikv-server --labels zone=z4,rack=r1,host=h1 +tikv-server --labels zone=z4,rack=r1,host=h2 +tikv-server --labels zone=z4,rack=r2,host=h1 +tikv-server --labels zone=z4,rack=r2,host=h2 +``` + +也就是说，我们有 16 个 TiKV 实例，分布在 4 个不同的数据中心，8 个不同的机架，16 个不同的机器。 + +在这种拓扑结构下，PD 会优先把每一份数据的不同副本调度到不同的数据中心。 +这时候如果其中一个数据中心挂了，不会影响 TiDB 集群的高可用状态。 +如果这个数据中心一段时间内恢复不了，PD 会把这个数据中心的副本迁移出去。 + +总的来说，PD 能够根据当前的拓扑结构使得集群容灾能力最大化，所以如果我们希望达到某个级别的容灾能力， +就需要根据拓扑机构在不同的地理位置提供多于备份数 (`max-replicas`) 的机器。 diff --git a/dev/how-to/deploy/geographic-redundancy/overview.md b/how-to/deploy/geographic-redundancy/overview.md similarity index 100% rename from dev/how-to/deploy/geographic-redundancy/overview.md rename to how-to/deploy/geographic-redundancy/overview.md diff --git a/how-to/deploy/hardware-recommendations.md b/how-to/deploy/hardware-recommendations.md new file mode 100644 index 000000000000..773d8931e45f --- /dev/null +++ b/how-to/deploy/hardware-recommendations.md @@ -0,0 +1,83 @@ +--- +title: TiDB 软件和硬件环境建议配置 +category: how-to +--- + +# TiDB 软件和硬件环境建议配置 + +TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 + +## Linux 操作系统版本要求 + +| Linux 操作系统平台 | 版本 | +| :----------------------- | :----------: | +| Red Hat Enterprise Linux | 7.3 及以上 | +| CentOS | 7.3 及以上 | +| Oracle Enterprise Linux | 7.3 及以上 | +| Ubuntu LTS | 16.04 及以上 | + +> **注意：** +> +> - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 +> - TiDB 在 CentOS 7.3 的环境下进行过大量的测试，同时社区也有很多该操作系统部署的最佳实践，因此，建议使用 CentOS 7.3 以上的 Linux 操作系统来部署 TiDB。 +> - 以上 Linux 操作系统可运行在物理服务器以及 VMware、KVM、XEN 主流虚拟化环境上。 + +## 服务器建议配置 + +TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： + +### 开发及测试环境 + +| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | +| --- | --- | --- | --- | --- | --- | +| TiDB | 8核+ | 16 GB+ | 无特殊要求 | 千兆网卡 | 1（可与 PD 同机器） | +| PD | 4核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | +| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | + +> **注意：** +> +> - 验证测试环境中的 TiDB 和 PD 可以部署在同一台服务器上。 +> - 如进行性能相关的测试，避免采用低性能存储和网络硬件配置，防止对测试结果的正确性产生干扰。 +> - TiKV 的 SSD 盘推荐使用 NVME 接口以保证读写更快。 +> - 如果仅验证功能，建议使用 [Docker Compose 部署方案](/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 +> - TiDB 对于磁盘的使用以存放日志为主，因此在测试环境中对于磁盘类型和容量并无特殊要求。 + +### 生产环境 + +| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | +| --- | --- | --- | --- | --- | --- | +| TiDB | 16核+ | 32 GB+ | SAS | 万兆网卡（2块最佳） | 2 | +| PD | 4核+ | 8 GB+ | SSD | 万兆网卡（2块最佳） | 3 | +| TiKV | 16核+ | 32 GB+ | SSD | 万兆网卡（2块最佳） | 3 | +| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | + +> **注意：** +> +> - 生产环境中的 TiDB 和 PD 可以部署和运行在同服务器上，如对性能和可靠性有更高的要求，应尽可能分开部署。 +> - 生产环境强烈推荐使用更高的配置。 +> - TiKV 硬盘大小配置建议 PCI-E SSD 不超过 2 TB，普通 SSD 不超过 1.5 TB。 + +## 网络要求 + +TiDB 作为开源分布式 NewSQL 数据库，其正常运行需要网络环境提供如下的网络端口配置要求，管理员可根据实际环境中 TiDB 组件部署的方案，在网络侧和主机侧开放相关端口： + +| 组件 | 默认端口 | 说明 | +| :-- | :-- | :-- | +| TiDB | 4000 | 应用及 DBA 工具访问通信端口 | +| TiDB | 10080 | TiDB 状态信息上报通信端口 | +| TiKV | 20160 | TiKV 通信端口 | +| PD | 2379 | 提供 TiDB 和 PD 通信端口 | +| PD | 2380 | PD 集群节点间通信端口 | +| Pump | 8250 | Pump 通信端口 | +| Drainer | 8249 | Drainer 通信端口 | +| Prometheus | 9090 | Prometheus 服务通信端口 | +| Pushgateway | 9091 | TiDB，TiKV，PD 监控聚合和上报端口 | +| Node_exporter | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | +| Blackbox_exporter | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | +| Grafana | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | +| Grafana | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | +| Kafka_exporter | 9308 | Kafka_exporter 通信端口，用于监控 binlog kafka 集群 | + +## 客户端 Web 浏览器要求 + +TiDB 提供了基于 [Grafana](https://grafana.com/) 的技术平台，对数据库集群的各项指标进行可视化展现。采用支持 Javascript 的微软 IE、Google Chrome、Mozilla Firefox 的较新版本即可访问监控入口。 diff --git a/how-to/deploy/orchestrated/ansible.md b/how-to/deploy/orchestrated/ansible.md new file mode 100644 index 000000000000..9dd37e927b79 --- /dev/null +++ b/how-to/deploy/orchestrated/ansible.md @@ -0,0 +1,966 @@ +--- +title: 使用 TiDB Ansible 部署 TiDB 集群 +category: how-to +--- + +# 使用 TiDB Ansible 部署 TiDB 集群 + +## 概述 + +Ansible 是一款自动化运维工具，[TiDB Ansible](https://github.com/pingcap/tidb-ansible) 是 PingCAP 基于 Ansible playbook 功能编写的集群部署工具。本文档介绍如何使用 TiDB Ansible 部署一个完整的 TiDB 集群。 + +本部署工具可以通过配置文件设置集群拓扑，完成以下各项运维工作： + +- 初始化操作系统参数 +- 部署 TiDB 集群（包括 PD、TiDB、TiKV 等组件和监控组件） +- [启动集群](/how-to/maintain/ansible-operations.md#启动集群) +- [关闭集群](/how-to/maintain/ansible-operations.md#关闭集群) +- [变更组件配置](/how-to/upgrade/from-previous-version.md#编辑-tidb-集群组件配置文件) +- [集群扩容缩容](/how-to/scale/with-ansible.md) +- [升级组件版本](/how-to/upgrade/from-previous-version.md#滚动升级-tidb-集群组件) +- [集群开启 binlog](/reference/tidb-binlog/overview.md) +- [清除集群数据](/how-to/maintain/ansible-operations.md#清除集群数据) +- [销毁集群](/how-to/maintain/ansible-operations.md#销毁集群) + +> **注意：** +> +> 对于生产环境，须使用 TiDB Ansible 部署 TiDB 集群。如果只是用于测试 TiDB 或体验 TiDB 的特性，建议[使用 Docker Compose 在单机上快速部署 TiDB 集群](/how-to/get-started/deploy-tidb-from-docker-compose.md)。 + +## 准备机器 + +1. 部署目标机器若干 + + - 建议 4 台及以上，TiKV 至少 3 实例，且与 TiDB、PD 模块不位于同一主机，详见[部署建议](/how-to/deploy/hardware-recommendations.md)。 + - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统，x86_64 架构 (amd64)。 + - 机器之间内网互通。 + + > **注意：** + > + > 使用 Ansible 方式部署时，TiKV 及 PD 节点数据目录所在磁盘请使用 SSD 磁盘，否则无法通过检测。** 如果仅验证功能，建议使用 [Docker Compose 部署方案](/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 + +2. 部署中控机一台 + + - 中控机可以是部署目标机器中的某一台。 + - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统（默认包含 Python 2.7）。 + - 该机器需开放外网访问，用于下载 TiDB 及相关软件安装包。 + +## 第 1 步：在中控机上安装系统依赖包 + +以 `root` 用户登录中控机，然后根据操作系统类型执行相应的安装命令。 + +- 如果中控机使用的是 CentOS 7 系统，执行以下命令： + + {{< copyable "shell-root" >}} + + ```bash + yum -y install epel-release git curl sshpass && \ + yum -y install python2-pip + ``` + +- 如果中控机使用的是 Ubuntu 系统，执行以下命令： + + {{< copyable "shell-root" >}} + + ```bash + apt-get -y install git curl sshpass python-pip + ``` + +## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH key + +以 `root` 用户登录中控机，执行以下步骤： + +1. 创建 `tidb` 用户。 + + {{< copyable "shell-root" >}} + + ```bash + useradd -m -d /home/tidb tidb + ``` + +2. 设置 `tidb` 用户密码。 + + {{< copyable "shell-root" >}} + + ```bash + passwd tidb + ``` + +3. 配置 `tidb` 用户 sudo 免密码，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾即可。 + + {{< copyable "shell-root" >}} + + ```bash + visudo + ``` + + ``` + tidb ALL=(ALL) NOPASSWD: ALL + ``` + +4. 生成 SSH key。 + + 执行 `su` 命令，从 `root` 用户切换到 `tidb` 用户下。 + + {{< copyable "shell-root" >}} + + ```bash + su - tidb + ``` + + 创建 `tidb` 用户 SSH key，提示 `Enter passphrase` 时直接回车即可。执行成功后，SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为 `/home/tidb/.ssh/id_rsa.pub`。 + + {{< copyable "shell-regular" >}} + + ```bash + ssh-keygen -t rsa + ``` + + ``` + Generating public/private rsa key pair. + Enter file in which to save the key (/home/tidb/.ssh/id_rsa): + Created directory '/home/tidb/.ssh'. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /home/tidb/.ssh/id_rsa. + Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. + The key fingerprint is: + SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 + The key's randomart image is: + +---[RSA 2048]----+ + |=+o+.o. | + |o=o+o.oo | + | .O.=.= | + | . B.B + | + |o B * B S | + | * + * + | + | o + . | + | o E+ . | + |o ..+o. | + +----[SHA256]-----+ + ``` + +## 第 3 步：在中控机器上下载 TiDB Ansible + +以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录。使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 master 分支的 TiDB Ansible，默认的文件夹名称为 `tidb-ansible`。 + +{{< copyable "shell-regular" >}} + +```bash +git clone https://github.com/pingcap/tidb-ansible.git +``` + +> **注意：** +> +> - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 +> - 请务必按文档操作，将 `tidb-ansible` 下载到 `/home/tidb` 目录下，权限为 `tidb` 用户，不要下载到 `/root` 下，否则会遇到权限问题。 + +## 第 4 步：在中控机器上安装 Ansible 及其依赖 + +以 `tidb` 用户登录中控机，请务必按以下方式通过 `pip` 安装 Ansible 及其相关依赖的指定版本，否则会有兼容问题。目前，TiDB release-2.0、release-2.1、release-3.0、release-3.1 以及最新开发版本兼容 Ansible 2.4 ~ 2.7.11 (2.4 ≤ Ansible ≤ 2.7.11)。 + +1. 在中控机器上安装 Ansible 及其依赖。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/tidb-ansible && \ + sudo pip install -r ./requirements.txt + ``` + + Ansible 及相关依赖的版本信息记录在 `tidb-ansible/requirements.txt` 文件中。 + +2. 查看 Ansible 的版本。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible --version + ``` + + ``` + ansible 2.7.11 + ``` + +## 第 5 步：在中控机上配置部署机器 SSH 互信及 sudo 规则 + +以 `tidb` 用户登录中控机，然后执行以下步骤： + +1. 将你的部署目标机器 IP 添加到 `hosts.ini` 文件的 `[servers]` 区块下。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/tidb-ansible && \ + vi hosts.ini + ``` + + ```ini + [servers] + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + 172.16.10.4 + 172.16.10.5 + 172.16.10.6 + + [all:vars] + username = tidb + ntp_server = pool.ntp.org + ``` + +2. 执行以下命令，按提示输入部署目标机器的 `root` 用户密码。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook -i hosts.ini create_users.yml -u root -k + ``` + + 该步骤将在部署目标机器上创建 `tidb` 用户，并配置 sudo 规则，配置中控机与部署目标机器之间的 SSH 互信。 + +如果要手工配置 SSH 互信及 sudo 免密码，可参考[如何手工配置 ssh 互信及 sudo 免密码](#如何手工配置-ssh-互信及-sudo-免密码)。 + +## 第 6 步：在部署目标机器上安装 NTP 服务 + +> **注意：** +> +> 如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略。可参考[如何检测 NTP 服务是否正常](#如何检测-ntp-服务是否正常)。 + +以 `tidb` 用户登录中控机，执行以下命令： + +{{< copyable "shell-regular" >}} + +```bash +cd /home/tidb/tidb-ansible && \ +ansible-playbook -i hosts.ini deploy_ntp.yml -u tidb -b +``` + +该步骤将在部署目标机器上使用系统自带软件源联网安装并启动 NTP 服务，服务使用安装包默认的 NTP server 列表，见配置文件 `/etc/ntp.conf` 中 server 参数。如果使用默认的 NTP server，你的机器需要连接外网。 + +为了让 NTP 尽快开始同步，启动 NTP 服务前，系统会执行 `ntpdate` 命令，与用户在 `hosts.ini` 文件中指定的 `ntp_server` 同步日期与时间。默认的服务器为 `pool.ntp.org`，也可替换为你的 NTP server。 + +## 第 7 步：在部署目标机器上配置 CPUfreq 调节器模式 + +为了让 CPU 发挥最大性能，请将 CPUfreq 调节器模式设置为 `performance` 模式。如需了解 CPUfreq 的更多信息，可查看[使用 CPUFREQ 调控器](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/power_management_guide/cpufreq_governors#cpufreq_setup)文档。 + +### 查看系统支持的调节器模式 + +执行以下 `cpupower` 命令，可查看系统支持的调节器模式： + +{{< copyable "shell-root" >}} + +```bash +cpupower frequency-info --governors +``` + +``` +analyzing CPU 0: + available cpufreq governors: performance powersave +``` + +> **注意：** +> +> 本例中系统支持设置 `performance` 和 `powersave` 模式。如果返回 `Not Available`，表示当前系统不支持配置 CPUfreq，跳过该步骤即可。 + +{{< copyable "shell-root" >}} + +```bash +cpupower frequency-info --governors +``` + +``` +analyzing CPU 0: + available cpufreq governors: Not Available +``` + +### 查看系统当前的 CPUfreq 调节器模式 + +执行以下 `cpupower` 命令，可查看系统当前的 CPUfreq 调节器模式： + +{{< copyable "shell-root" >}} + +```bash +cpupower frequency-info --policy +``` + +``` +analyzing CPU 0: + current policy: frequency should be within 1.20 GHz and 3.20 GHz. + The governor "powersave" may decide which speed to use + within this range. +``` + +如上述代码所示，本例中的当前配置是 `powersave` 模式。 + +### 修改调节器模式 + +你可以通过以下两种方法来修改调节器模式。本例中，当前调节器模式为 `powersave`，以下命令会将模式变更为 `performance`。 + +- 使用 `cpupower frequency-set --governor` 命令来修改。 + + {{< copyable "shell-root" >}} + + ```bash + cpupower frequency-set --governor performance + ``` + +- 使用以下命令在部署目标机器上批量设置。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible -i hosts.ini all -m shell -a "cpupower frequency-set --governor performance" -u tidb -b + ``` + +## 第 8 步：在部署目标机器上添加数据盘 ext4 文件系统挂载参数 + +使用 `root` 用户登录目标机器，将部署目标机器数据盘格式化成 ext4 文件系统，挂载时添加 `nodelalloc` 和 `noatime` 挂载参数。`nodelalloc` 是必选参数，否则 Ansible 安装时检测无法通过；`noatime` 是可选建议参数。 + +> **注意：** +> +> 如果你的数据盘已经格式化成 ext4 并挂载了磁盘，可先执行 `umount /dev/nvme0n1p1` 命令卸载，从编辑 `/etc/fstab` 文件步骤开始执行，添加挂载参数重新挂载即可。 + +以 `/dev/nvme0n1` 数据盘为例，具体操作步骤如下： + +1. 查看数据盘。 + + {{< copyable "shell-root" >}} + + ```bash + fdisk -l + ``` + + ``` + Disk /dev/nvme0n1: 1000 GB + ``` + +2. 创建分区表。 + + {{< copyable "shell-root" >}} + + ```bash + parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1 + ``` + + > **注意：** + > + > 使用 `lsblk` 命令查看分区的设备号：对于 nvme 磁盘，生成的分区设备号一般为 `nvme0n1p1`；对于普通磁盘（例如 `/dev/sdb`），生成的的分区设备号一般为 `sdb1`。 + +3. 格式化文件系统。 + + {{< copyable "shell-root" >}} + + ```bash + mkfs.ext4 /dev/nvme0n1p1 + ``` + +4. 查看数据盘分区 UUID。 + + 本例中 `nvme0n1p1` 的 UUID 为 `c51eb23b-195c-4061-92a9-3fad812cc12f`。 + + {{< copyable "shell-root" >}} + + ```bash + lsblk -f + ``` + + ``` + NAME FSTYPE LABEL UUID MOUNTPOINT + sda + ├─sda1 ext4 237b634b-a565-477b-8371-6dff0c41f5ab /boot + ├─sda2 swap f414c5c0-f823-4bb1-8fdf-e531173a72ed + └─sda3 ext4 547909c1-398d-4696-94c6-03e43e317b60 / + sr0 + nvme0n1 + └─nvme0n1p1 ext4 c51eb23b-195c-4061-92a9-3fad812cc12f + ``` + +5. 编辑 `/etc/fstab` 文件，添加 `nodelalloc` 挂载参数。 + + {{< copyable "shell-root" >}} + + ```bash + vi /etc/fstab + ``` + + ``` + UUID=c51eb23b-195c-4061-92a9-3fad812cc12f /data1 ext4 defaults,nodelalloc,noatime 0 2 + ``` + +6. 挂载数据盘。 + + {{< copyable "shell-root" >}} + + ```bash + mkdir /data1 && \ + mount -a + ``` + +7. 执行以下命令，如果文件系统为 ext4，并且挂载参数中包含 `nodelalloc`，则表示已生效。 + + {{< copyable "shell-root" >}} + + ```bash + mount -t ext4 + ``` + + ``` + /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered) + ``` + +## 第 9 步：编辑 `inventory.ini` 文件，分配机器资源 + +以 `tidb` 用户登录中控机，编辑 `/home/tidb/tidb-ansible/inventory.ini` 文件为 TiDB 集群分配机器资源。一个标准的 TiDB 集群需要 6 台机器：2 个 TiDB 实例，3 个 PD 实例，3 个 TiKV 实例。 + +- 至少需部署 3 个 TiKV 实例。 +- 不要将 TiKV 实例与 TiDB 或 PD 实例混合部署在同一台机器上。 +- 将第一台 TiDB 机器同时用作监控机。 + +> **注意：** +> +> 请使用内网 IP 来部署集群，如果部署目标机器 SSH 端口非默认的 22 端口，需添加 `ansible_port` 变量，如 `TiDB1 ansible_host=172.16.10.1 ansible_port=5555`。 + +你可以根据实际场景从以下两种集群拓扑中选择一种： + +- [单机单 TiKV 实例集群拓扑](#单机单-tikv-实例集群拓扑) + + 默认情况下，建议在每个 TiKV 节点上仅部署一个 TiKV 实例，以提高性能。但是，如果你的 TiKV 部署机器的 CPU 和内存配置是[部署建议](/how-to/deploy/hardware-recommendations.md)的两倍或以上，并且一个节点拥有两块 SSD 硬盘或者单块 SSD 硬盘的容量大于 2 TB，则可以考虑部署两实例，但不建议部署两个以上实例。 + +- [单机多 TiKV 实例集群拓扑](#单机多-tikv-实例集群拓扑) + +### 单机单 TiKV 实例集群拓扑 + +| Name | Host IP | Services | +| :---- | :------- | :-------- | +| node1 | 172.16.10.1 | PD1, TiDB1 | +| node2 | 172.16.10.2 | PD2, TiDB2 | +| node3 | 172.16.10.3 | PD3 | +| node4 | 172.16.10.4 | TiKV1 | +| node5 | 172.16.10.5 | TiKV2 | +| node6 | 172.16.10.6 | TiKV3 | + +```ini +[tidb_servers] +172.16.10.1 +172.16.10.2 + +[pd_servers] +172.16.10.1 +172.16.10.2 +172.16.10.3 + +[tikv_servers] +172.16.10.4 +172.16.10.5 +172.16.10.6 + +[monitoring_servers] +172.16.10.1 + +[grafana_servers] +172.16.10.1 + +[monitored_servers] +172.16.10.1 +172.16.10.2 +172.16.10.3 +172.16.10.4 +172.16.10.5 +172.16.10.6 +``` + +### 单机多 TiKV 实例集群拓扑 + +以两实例为例： + +| Name | Host IP | Services | +| :---- | :------- | :-------- | +| node1 | 172.16.10.1 | PD1, TiDB1 | +| node2 | 172.16.10.2 | PD2, TiDB2 | +| node3 | 172.16.10.3 | PD3 | +| node4 | 172.16.10.4 | TiKV1-1, TiKV1-2 | +| node5 | 172.16.10.5 | TiKV2-1, TiKV2-2 | +| node6 | 172.16.10.6 | TiKV3-1, TiKV3-2 | + +```ini +[tidb_servers] +172.16.10.1 +172.16.10.2 + +[pd_servers] +172.16.10.1 +172.16.10.2 +172.16.10.3 + +# 注意：要使用 TiKV 的 labels，必须同时配置 PD 的 location_labels 参数，否则 labels 设置不生效。 +[tikv_servers] +TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv1" +TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv1" +TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv2" +TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv2" +TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv3" +TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv3" + +# 部署 3.0 版本的 TiDB 集群时，多实例场景需要额外配置 status 端口，示例如下： +# TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" +# TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" +# TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" +# TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" +# TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" +# TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" + +[monitoring_servers] +172.16.10.1 + +[grafana_servers] +172.16.10.1 + +[monitored_servers] +172.16.10.1 +172.16.10.2 +172.16.10.3 +172.16.10.4 +172.16.10.5 +172.16.10.6 + +# 注意：为使 TiKV 的 labels 设置生效，部署集群时必须设置 PD 的 location_labels 参数。 +[pd_servers:vars] +location_labels = ["host"] +``` + +- 服务配置文件参数调整 + + 1. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `block-cache-size` 下面的 `capacity` 参数： + + ```yaml + storage: + block-cache: + capacity: "1GB" + ``` + + > **注意：** + > + > TiKV 实例数量指每个服务器上 TiKV 的进程数量。 + > + > 推荐设置：`capacity` = MEM_TOTAL * 0.5 / TiKV 实例数量 + + 2. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： + + ```yaml + readpool: + coprocessor: + # Notice: if CPU_NUM > 8, default thread pool size for coprocessors + # will be set to CPU_NUM * 0.8. + # high-concurrency: 8 + # normal-concurrency: 8 + # low-concurrency: 8 + ``` + + > **注意：** + > + > 推荐设置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 + + 3. 如果多个 TiKV 实例部署在同一块物理磁盘上，需要修改 `conf/tikv.yml` 中的 `capacity` 参数： + + ```yaml + raftstore: + capacity: 0 + ``` + + > **注意：** + > + > 推荐配置：`capacity` = 磁盘总容量 / TiKV 实例数量 + > + > 例如：`capacity: "100GB"` + +## 第 10 步：调整 `inventory.ini` 文件中的变量 + +本小节介绍如何编辑部署目录的变量和 `inventory.ini` 文件中的其它变量。 + +### 调整部署目录 + +部署目录通过 `deploy_dir` 变量控制，默认全局变量已设置为 `/home/tidb/deploy`，对所有服务生效。如数据盘挂载目录为 `/data1`，可设置为 `/data1/deploy`，样例如下： + +```ini +## Global variables +[all:vars] +deploy_dir = /data1/deploy +``` + +如为某一服务单独设置部署目录，可在配置服务主机列表时配置主机变量，以 TiKV 节点为例，其他服务类推，请务必添加第一列别名，以免服务混布时混淆。 + +```ini +TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy +``` + +### 调整其它变量（可选） + +> **注意：** +> +> 以下控制变量开启请使用首字母大写 `True`，关闭请使用首字母大写 `False`。 + +| 变量 | 含义 | +| :--------------- | :-------------------------------------------------------- | +| `cluster_name` | 集群名称，可调整 | +| `tidb_version` | TiDB 版本，TiDB Ansible 各分支默认已配置 | +| `process_supervision` | 进程监管方式，默认为 `systemd`，可选 `supervise` | +| `timezone` | 新安装 TiDB 集群第一次启动 bootstrap（初始化）时，将 TiDB 全局默认时区设置为该值。TiDB 使用的时区后续可通过 `time_zone` 全局变量和 session 变量来修改，参考[时区支持](/how-to/configure/time-zone.md)。默认为 `Asia/Shanghai`，可选值参考 [timzone 列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。 | +| `enable_firewalld` | 开启防火墙，默认不开启，如需开启，请将[部署建议-网络要求](/how-to/deploy/hardware-recommendations.md#网络要求) 中的端口加入白名单 | +| `enable_ntpd` | 检测部署目标机器 NTP 服务，默认为 `True`，请勿关闭 | +| `set_hostname` | 根据 IP 修改部署目标机器主机名，默认为 `False` | +| `enable_binlog` | 是否部署 Pump 并开启 binlog，默认为 `False`，依赖 Kafka 集群，参见 `zookeeper_addrs` 变量 | +| `zookeeper_addrs` | binlog Kafka 集群的 zookeeper 地址 | +| `deploy_without_tidb` | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 `inventory.ini` 文件中 `tidb_servers` 主机组 IP 设置为空。| +| `alertmanager_target` | 可选：如果你已单独部署 alertmanager，可配置该变量，格式：`alertmanager_host:alertmanager_port` | +| `grafana_admin_user` | Grafana 管理员帐号用户名，默认为 admin | +| `grafana_admin_password` | Grafana 管理员帐号密码，默认为 admin，用于 Ansible 导入 Dashboard 和创建 API Key，如后期通过 grafana web 修改了密码，请更新此变量 | +| `collect_log_recent_hours` | 采集日志时，采集最近几个小时的日志，默认为 2 小时 | +| `enable_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时，是否限速，默认为 `True`，与 `collect_bandwidth_limit` 变量结合使用 | +| `collect_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时限速多少，单位: Kbit/s，默认 10000，即 10Mb/s，如果是单机多 TiKV 实例部署方式，需除以单机实例个数 | +| `prometheus_storage_retention` | Prometheus 监控数据的保留时间（默认为 30 天）；2.1.7、3.0 以及之后的 tidb-ansible 版本中，`group_vars/monitoring_servers.yml` 文件里新增的配置 | + +## 第 11 步：部署 TiDB 集群 + +`ansible-playbook` 执行 Playbook 时，默认并发为 5。部署目标机器较多时，可添加 `-f` 参数指定并发数，例如 `ansible-playbook deploy.yml -f 10`。以下示例使用 `tidb` 用户作为服务运行用户： + +1. 在 `tidb-ansible/inventory.ini` 文件中，确认 `ansible_user = tidb`。 + + ```ini + ## Connection + # ssh via normal user + ansible_user = tidb + ``` + + > **注意：** + > + > 不要将 `ansible_user` 设置为 `root` 用户，因为 `tidb-ansible` 限制了服务以普通用户运行。 + + 执行以下命令，如果所有 server 均返回 `tidb`，表示 SSH 互信配置成功： + + {{< copyable "shell-regular" >}} + + ```bash + ansible -i inventory.ini all -m shell -a 'whoami' + ``` + + 执行以下命令，如果所有 server 均返回 `root`，表示 `tidb` 用户 sudo 免密码配置成功。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible -i inventory.ini all -m shell -a 'whoami' -b + ``` + +2. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 至中控机。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook local_prepare.yml + ``` + +3. 初始化系统环境，修改内核参数。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook bootstrap.yml + ``` + +4. 部署 TiDB 集群软件。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml + ``` + + > **注意：** + > + > Grafana Dashboard 上的 **Report** 按钮可用来生成 PDF 文件，此功能依赖 `fontconfig` 包和英文字体。如需使用该功能，登录 **grafana_servers** 机器，用以下命令安装： + > + > {{< copyable "shell-regular" >}} + > + > ```bash + > sudo yum install fontconfig open-sans-fonts + > ``` + +5. 启动 TiDB 集群。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml + ``` + +## 测试集群 + +TiDB 兼容 MySQL，因此可使用 MySQL 客户端直接连接 TiDB。推荐配置负载均衡以提供统一的 SQL 接口。 + +1. 使用 MySQL 客户端连接 TiDB 集群。TiDB 服务的默认端口为 `4000`。 + + {{< copyable "sql" >}} + + ```sql + mysql -u root -h 172.16.10.1 -P 4000 + ``` + +2. 通过浏览器访问监控平台。 + + - 地址： + - 默认帐号与密码：`admin`；`admin` + +## 常见部署问题 + +本小节介绍使用 Ansible 部署 TiDB 集群过程中的常见问题与解决方案。 + +### 如何自定义端口 + +修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： + +| 组件 | 端口变量 | 默认端口 | 说明 | +| :-- | :-- | :-- | :-- | +| TiDB | tidb_port | 4000 | 应用及 DBA 工具访问通信端口 | +| TiDB | tidb_status_port | 10080 | TiDB 状态信息上报通信端口 | +| TiKV | tikv_port | 20160 | TiKV 通信端口 | +| TiKV | tikv_status_port | 20180 | 上报 TiKV 状态的通信端口 | +| PD | pd_client_port | 2379 | 提供 TiDB 和 PD 通信端口 | +| PD | pd_peer_port | 2380 | PD 集群节点间通信端口 | +| Pump | pump_port | 8250 | Pump 通信端口 | +| Prometheus | prometheus_port | 9090 | Prometheus 服务通信端口 | +| Pushgateway | pushgateway_port | 9091 | TiDB， TiKV， PD 监控聚合和上报端口 | +| Node_exporter | node_exporter_port | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | +| Blackbox_exporter | blackbox_exporter_port | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | +| Grafana | grafana_port | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | +| Grafana | grafana_collector_port | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | +| Kafka_exporter | kafka_exporter_port | 9308 | Kafka_exporter 通信端口，用于监控 binlog Kafka 集群 | + +### 如何自定义部署目录 + +修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： + +| 组件 | 目录变量 | 默认目录 | 说明 | +| :-- | :-- | :-- | :-- | +| 全局 | deploy_dir | /home/tidb/deploy | 部署目录 | +| TiDB | tidb_log_dir | {{ deploy_dir }}/log | 日志目录 | +| TiKV | tikv_log_dir | {{ deploy_dir }}/log | 日志目录 | +| TiKV | tikv_data_dir | {{ deploy_dir }}/data | 数据目录 | +| TiKV | wal_dir | "" | rocksdb write-ahead 日志目录，为空时与 TiKV 数据目录一致 | +| TiKV | raftdb_path | "" | raftdb 目录，为空时为 tikv_data_dir/raft | +| PD | pd_log_dir | {{ deploy_dir }}/log | 日志目录 | +| PD | pd_data_dir | {{ deploy_dir }}/data.pd | 数据目录 | +| pump | pump_log_dir | {{ deploy_dir }}/log | 日志目录 | +| pump | pump_data_dir | {{ deploy_dir }}/data.pump | 数据目录 | +| prometheus | prometheus_log_dir | {{ deploy_dir }}/log | 日志目录 | +| prometheus | prometheus_data_dir | {{ deploy_dir }}/data.metrics | 数据目录 | +| pushgateway | pushgateway_log_dir | {{ deploy_dir }}/log | 日志目录 | +| node_exporter | node_exporter_log_dir | {{ deploy_dir }}/log | 日志目录 | +| grafana | grafana_log_dir | {{ deploy_dir }}/log | 日志目录 | +| grafana | grafana_data_dir | {{ deploy_dir }}/data.grafana | 数据目录 | + +### 如何检测 NTP 服务是否正常 + +1. 执行以下命令，如果输出 `running` 表示 NTP 服务正在运行： + + {{< copyable "shell-regular" >}} + + ```bash + sudo systemctl status ntpd.service + ``` + + ``` + ntpd.service - Network Time Service + Loaded: loaded (/usr/lib/systemd/system/ntpd.service; disabled; vendor preset: disabled) + Active: active (running) since 一 2017-12-18 13:13:19 CST; 3s ago + ``` + +2. 执行 `ntpstat` 命令，如果输出 `synchronised to NTP server`（正在与 NTP server 同步），表示在正常同步： + + {{< copyable "shell-regular" >}} + + ```bash + ntpstat + ``` + + ``` + synchronised to NTP server (85.199.214.101) at stratum 2 + time correct to within 91 ms + polling server every 1024 s + ``` + +> **注意：** +> +> Ubuntu 系统需安装 `ntpstat` 软件包。 + +- 以下情况表示 NTP 服务未正常同步： + + {{< copyable "shell-regular" >}} + + ```bash + ntpstat + ``` + + ``` + unsynchronised + ``` + +- 以下情况表示 NTP 服务未正常运行： + + {{< copyable "shell-regular" >}} + + ```bash + ntpstat + ``` + + ``` + Unable to talk to NTP daemon. Is it running? + ``` + +- 如果要使 NTP 服务尽快开始同步，执行以下命令。可以将 `pool.ntp.org` 替换为你的 NTP server： + + {{< copyable "shell-regular" >}} + + ```bash + sudo systemctl stop ntpd.service && \ + sudo ntpdate pool.ntp.org && \ + sudo systemctl start ntpd.service + ``` + +- 如果要在 CentOS 7 系统上手动安装 NTP 服务，可执行以下命令： + + {{< copyable "shell-regular" >}} + + ```bash + sudo yum install ntp ntpdate && \ + sudo systemctl start ntpd.service && \ + sudo systemctl enable ntpd.service + ``` + +### 如何调整进程监管方式从 supervise 到 systemd + +{{< copyable "shell-root" >}} + +```shell +process supervision, [systemd, supervise] +``` + +``` +process_supervision = systemd +``` + +TiDB Anisble 在 TiDB v1.0.4 版本之前进程监管方式默认为 `supervise`。之前安装的集群可保持不变，如需更新为 `systemd`，需关闭集群，按以下方式变更： + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook stop.yml && \ +ansible-playbook deploy.yml -D && \ +ansible-playbook start.yml +``` + +### 如何手工配置 SSH 互信及 sudo 免密码 + +1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 + + {{< copyable "shell-root" >}} + + ```bash + useradd tidb && \ + passwd tidb + ``` + +2. 执行以下命令，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾，即配置好 sudo 免密码。 + + {{< copyable "shell-root" >}} + + ```bash + visudo + ``` + + ``` + tidb ALL=(ALL) NOPASSWD: ALL + ``` + +3. 以 `tidb` 用户登录到中控机，执行以下命令。将 `172.16.10.61` 替换成你的部署目标机器 IP，按提示输入部署目标机器 `tidb` 用户密码，执行成功后即创建好 SSH 互信，其他机器同理。 + + {{< copyable "shell-regular" >}} + + ```bash + ssh-copy-id -i ~/.ssh/id_rsa.pub 172.16.10.61 + ``` + +4. 以 `tidb` 用户登录中控机，通过 `ssh` 的方式登录目标机器 IP。如果不需要输入密码并登录成功，即表示 SSH 互信配置成功。 + + {{< copyable "shell-regular" >}} + + ```bash + ssh 172.16.10.61 + ``` + + ``` + [tidb@172.16.10.61 ~]$ + ``` + +5. 以 `tidb` 用户登录到部署目标机器后，执行以下命令，不需要输入密码并切换到 `root` 用户，表示 `tidb` 用户 sudo 免密码配置成功。 + + {{< copyable "shell-regular" >}} + + ```bash + sudo -su root + ``` + + ``` + [root@172.16.10.61 tidb]# + ``` + +### You need to install jmespath prior to running json_query filter 报错 + +1. 请参照[在中控机器上安装 Ansible 及其依赖](#在中控机器上安装-ansible-及其依赖) 在中控机上通过 `pip` 安装 Ansible 及相关依赖的指定版本，默认会安装 `jmespath`。 + +2. 执行以下命令，验证 `jmespath` 是否安装成功： + + {{< copyable "shell-regular" >}} + + ```bash + pip show jmespath + ``` + + ``` + Name: jmespath + Version: 0.9.0 + ``` + +3. 在中控机上 Python 交互窗口里执行 `import jmespath`。 + + - 如果没有报错，表示依赖安装成功。 + - 如果有 `ImportError: No module named jmespath` 报错，表示未成功安装 Python `jmespath` 模块。 + + {{< copyable "shell-regular" >}} + + ```bash + python + ``` + + ``` + Python 2.7.5 (default, Nov 6 2016, 00:28:07) + [GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux2 + Type "help", "copyright", "credits" or "license" for more information. + ``` + + {{< copyable "shell-regular" >}} + + ```shell + import jmespath + ``` + +### 启动 Pump/Drainer 报 `zk: node does not exist` 错误 + +请检查 `inventory.ini` 里的 `zookeeper_addrs` 参数配置与 Kafka 集群内的配置是否相同、是否填写了命名空间。关于命名空间的配置说明如下： + +```ini +# ZooKeeper connection string (see ZooKeeper docs for details). +# ZooKeeper address of Kafka cluster, example: +# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" +# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes. Example: +# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" +``` diff --git a/how-to/deploy/orchestrated/docker.md b/how-to/deploy/orchestrated/docker.md new file mode 100644 index 000000000000..61e9bfc86423 --- /dev/null +++ b/how-to/deploy/orchestrated/docker.md @@ -0,0 +1,260 @@ +--- +title: TiDB Docker 部署方案 +category: how-to +--- + +# TiDB Docker 部署方案 + +本文介绍如何使用 Docker 部署一个多节点的 TiDB 集群。 + +> **警告：** +> +> 对于生产环境，不要使用 Docker 进行部署，而应[使用 Ansible 部署 TiDB 集群](/how-to/deploy/orchestrated/ansible.md)。 + +## 环境准备 + +### 安装 Docker + +Docker 可以方便地在 Linux / Mac OS / Windows 平台安装，安装方法请参考 [Docker 官方文档](https://www.docker.com/products/docker)。 + +### 拉取 TiDB 的 Docker 镜像 + +部署 TiDB 集群主要包括 3 个服务组件: + +- TiDB +- TiKV +- PD + +对应的最新 Docker 镜像可以通过 [Docker 官方镜像仓库](https://hub.docker.com/u/pingcap) 获取： + +{{< copyable "shell-regular" >}} + +```bash +docker pull pingcap/tidb:latest +``` + +{{< copyable "shell-regular" >}} + +```bash +docker pull pingcap/tikv:latest +``` + +{{< copyable "shell-regular" >}} + +```bash +docker pull pingcap/pd:latest +``` + +## 部署一个多节点集群 + +假设我们打算在 6 台主机上部署一个 TiDB 集群: + +| 主机名 | IP | 部署服务 | 数据盘挂载 | +| --------- | ------------- | ---------- | ----- | +| host1 | 192.168.1.101 | PD1 & TiDB | /data | +| host2 | 192.168.1.102 | PD2 | /data | +| host3 | 192.168.1.103 | PD3 | /data | +| host4 | 192.168.1.104 | TiKV1 | /data | +| host5 | 192.168.1.105 | TiKV2 | /data | +| host6 | 192.168.1.106 | TiKV3 | /data | + +### 启动 PD + +登录 **host1** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name pd1 \ + -p 2379:2379 \ + -p 2380:2380 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + pingcap/pd:latest \ + --name="pd1" \ + --data-dir="/data/pd1" \ + --client-urls="http://0.0.0.0:2379" \ + --advertise-client-urls="http://192.168.1.101:2379" \ + --peer-urls="http://0.0.0.0:2380" \ + --advertise-peer-urls="http://192.168.1.101:2380" \ + --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" +``` + +登录 **host2** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name pd2 \ + -p 2379:2379 \ + -p 2380:2380 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + pingcap/pd:latest \ + --name="pd2" \ + --data-dir="/data/pd2" \ + --client-urls="http://0.0.0.0:2379" \ + --advertise-client-urls="http://192.168.1.102:2379" \ + --peer-urls="http://0.0.0.0:2380" \ + --advertise-peer-urls="http://192.168.1.102:2380" \ + --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" +``` + +登录 **host3** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name pd3 \ + -p 2379:2379 \ + -p 2380:2380 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + pingcap/pd:latest \ + --name="pd3" \ + --data-dir="/data/pd3" \ + --client-urls="http://0.0.0.0:2379" \ + --advertise-client-urls="http://192.168.1.103:2379" \ + --peer-urls="http://0.0.0.0:2380" \ + --advertise-peer-urls="http://192.168.1.103:2380" \ + --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" +``` + +### 启动 TiKV + +登录 **host4** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name tikv1 \ + -p 20160:20160 \ + --ulimit nofile=1000000:1000000 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + pingcap/tikv:latest \ + --addr="0.0.0.0:20160" \ + --advertise-addr="192.168.1.104:20160" \ + --data-dir="/data/tikv1" \ + --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" +``` + +登录 **host5** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name tikv2 \ + -p 20160:20160 \ + --ulimit nofile=1000000:1000000 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + pingcap/tikv:latest \ + --addr="0.0.0.0:20160" \ + --advertise-addr="192.168.1.105:20160" \ + --data-dir="/data/tikv2" \ + --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" +``` + +登录 **host6** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name tikv3 \ + -p 20160:20160 \ + --ulimit nofile=1000000:1000000 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + pingcap/tikv:latest \ + --addr="0.0.0.0:20160" \ + --advertise-addr="192.168.1.106:20160" \ + --data-dir="/data/tikv3" \ + --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" +``` + +### 启动 TiDB + +登录 **host1** 执行： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name tidb \ + -p 4000:4000 \ + -p 10080:10080 \ + -v /etc/localtime:/etc/localtime:ro \ + pingcap/tidb:latest \ + --store=tikv \ + --path="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" +``` + +### 使用 MySQL 标准客户端连接 TiDB 测试 + +登录 **host1** 并确保已安装 [MySQL 命令行客户端](http://dev.mysql.com/downloads/mysql/)，执行： + +{{< copyable "shell-regular" >}} + +```bash +mysql -h 127.0.0.1 -P 4000 -u root -D test +``` + +{{< copyable "sql" >}} + +```sql +show databases; +``` + +``` ++--------------------+ +| Database | ++--------------------+ +| INFORMATION_SCHEMA | +| PERFORMANCE_SCHEMA | +| mysql | +| test | ++--------------------+ +4 rows in set (0.00 sec) +``` + +### 如何自定义配置文件 + +TiKV 和 PD 可以通过指定配置文件的方式来加载更加丰富的启动参数，用于性能调优。 + +假定配置文件在宿主机上的存放路径 `/path/to/config/pd.toml` 和 `/path/to/config/tikv.toml`。启动 Docker 时需要调整相应的启动参数，以 tikv1 和 pd1 为例： + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name tikv1 \ + -p 20160:20160 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + -v /path/to/config/tikv.toml:/tikv.toml:ro \ + pingcap/tikv:latest \ + --addr="0.0.0.0:20160" \ + --advertise-addr="192.168.1.104:20160" \ + --data-dir="/data/tikv1" \ + --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" \ + --config="/tikv.toml" +``` + +{{< copyable "shell-regular" >}} + +```bash +docker run -d --name pd1 \ + -p 2379:2379 \ + -p 2380:2380 \ + -v /etc/localtime:/etc/localtime:ro \ + -v /data:/data \ + -v /path/to/config/pd.toml:/pd.toml:ro \ + pingcap/pd:latest \ + --name="pd1" \ + --data-dir="/data/pd1" \ + --client-urls="http://0.0.0.0:2379" \ + --advertise-client-urls="http://192.168.1.101:2379" \ + --peer-urls="http://0.0.0.0:2380" \ + --advertise-peer-urls="http://192.168.1.101:2380" \ + --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" \ + --config="/pd.toml" +``` diff --git a/how-to/deploy/orchestrated/offline-ansible.md b/how-to/deploy/orchestrated/offline-ansible.md new file mode 100644 index 000000000000..68f068555854 --- /dev/null +++ b/how-to/deploy/orchestrated/offline-ansible.md @@ -0,0 +1,159 @@ +--- +title: 离线 TiDB Ansible 部署方案 +category: how-to +--- + +# 离线 TiDB Ansible 部署方案 + +## 准备机器 + +1. 下载机一台 + + - 该机器需开放外网访问，用于下载 TiDB Ansible、TiDB 及相关软件安装包。 + - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统。 + +2. 部署目标机器若干及部署中控机一台 + + - 系统要求及配置参考[准备机器](/how-to/deploy/orchestrated/ansible.md#准备机器)。 + - 可以无法访问外网。 + +## 在中控机上安装系统依赖包 + +1. 在下载机上下载[系统依赖离线安装包](https://download.pingcap.org/ansible-system-rpms.el7.tar.gz)，然后上传至中控机。该离线包仅支持 CentOS 7 系统，包含 `pip` 及 `sshpass`。 + +2. 在中控机上安装系统依赖包： + + {{< copyable "shell-root" >}} + + ```bash + tar -xzvf ansible-system-rpms.el7.tar.gz && + cd ansible-system-rpms.el7 && + chmod u+x install_ansible_system_rpms.sh && + ./install_ansible_system_rpms.sh + ``` + +3. 安装完成后，可通过 `pip -V` 验证 pip 是否安装成功： + + {{< copyable "shell-root" >}} + + ```bash + pip -V + ``` + + ``` + pip 8.1.2 from /usr/lib/python2.7/site-packages (python 2.7) + ``` + +> **注意：** +> +> 如果你的系统已安装 pip，请确认版本 >= 8.1.2，否则离线安装 ansible 及其依赖时，会有兼容问题。 + +## 在中控机上创建 tidb 用户，并生成 ssh key + +参考[在中控机上创建 tidb 用户，并生成 ssh key](/how-to/deploy/orchestrated/ansible.md#第-2-步在中控机上创建-tidb-用户并生成-ssh-key) 即可。 + +## 在中控机器上离线安装 Ansible 及其依赖 + +以下是 CentOS 7 系统 Ansible 离线安装方式： + +建议使用 Ansible 2.4 至 2.7.11 版本，Ansible 及相关依赖版本记录在 `tidb-ansible/requirements.txt` 文件中。下面步骤以安装 Ansible 2.5 为例。 + +1. 在下载机上下载 [Ansible 2.5 离线安装包](https://download.pingcap.org/ansible-2.5.0-pip.tar.gz)，然后上传至中控机。 + +2. 离线安装 Ansible 及相关依赖： + + {{< copyable "shell-root" >}} + + ```bash + tar -xzvf ansible-2.5.0-pip.tar.gz && + cd ansible-2.5.0-pip/ && + chmod u+x install_ansible.sh && + ./install_ansible.sh + ``` + +3. 安装完成后，可通过 `ansible --version` 查看版本： + + {{< copyable "shell-root" >}} + + ```bash + ansible --version + ``` + + ``` + ansible 2.5.0 + ``` + +## 在下载机上下载 TiDB Ansible 及 TiDB 安装包 + +1. 在下载机上安装 Ansible： + + 请按以下方式在 CentOS 7 系统的下载机上在线安装 Ansible。安装完成后，可通过 `ansible --version` 查看版本，请务必确认是 **Ansible 2.5.0** 版本，否则会有兼容问题。 + + {{< copyable "shell-root" >}} + + ```bash + yum install epel-release && + yum install ansible curl && + ansible --version + ``` + + ``` + ansible 2.5.0 + ``` + +2. 下载 tidb-ansible： + + 使用以下命令从 Github [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应版本，默认的文件夹名称为 `tidb-ansible`。 + + {{< copyable "shell-regular" >}} + + ```bash + git clone https://github.com/pingcap/tidb-ansible.git + ``` + + > **注意：** + > + > 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 + +3. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到下载机： + + {{< copyable "shell-regular" >}} + + ```bash + cd tidb-ansible && + ansible-playbook local_prepare.yml + ``` + +4. 将执行完以上命令之后的 `tidb-ansible` 文件夹拷贝到中控机 `/home/tidb` 目录下，文件属主权限需是 `tidb` 用户。 + +## 在中控机上配置部署机器 SSH 互信及 sudo 规则 + +参考[在中控机上配置部署机器 SSH 互信及 sudo 规则](/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)即可。 + +## 在部署目标机器上安装 NTP 服务 + +如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略，可参考[如何检测 NTP 服务是否正常](/how-to/deploy/orchestrated/ansible.md#如何检测-ntp-服务是否正常)。 + +参考[在部署目标机器上安装 NTP 服务](/how-to/deploy/orchestrated/ansible.md#第-6-步在部署目标机器上安装-ntp-服务)即可。 + +## 在部署目标机器上配置 CPUfreq 调节器模式 + +参考[在部署目标机器上配置 CPUfreq 调节器模式](/how-to/deploy/orchestrated/ansible.md#第-7-步在部署目标机器上配置-cpufreq-调节器模式)即可。 + +## 在部署目标机器上添加数据盘 ext4 文件系统挂载参数 + +参考[在部署目标机器上添加数据盘 ext4 文件系统挂载参数](/how-to/deploy/orchestrated/ansible.md#第-8-步在部署目标机器上添加数据盘-ext4-文件系统挂载参数)即可。 + +## 分配机器资源，编辑 inventory.ini 文件 + +参考[分配机器资源，编辑 inventory.ini 文件](/how-to/deploy/orchestrated/ansible.md#第-9-步编辑-inventoryini-文件分配机器资源)即可。 + +## 部署任务 + +1. `ansible-playbook local_prepare.yml` 该 playbook 不需要再执行。 + +2. 参考[部署任务](/how-to/deploy/orchestrated/ansible.md#第-11-步部署-tidb-集群)即可。 + +## 测试集群 + +参考[测试集群](/how-to/deploy/orchestrated/ansible.md#测试集群)即可。 diff --git a/how-to/get-started/data-migration.md b/how-to/get-started/data-migration.md new file mode 100644 index 000000000000..dd8841b03fd5 --- /dev/null +++ b/how-to/get-started/data-migration.md @@ -0,0 +1,523 @@ +--- +title: TiDB Data Migration 教程 +category: how-to +--- + +# TiDB Data Migration 教程 + +TiDB Data Migration (DM) 是一体化的数据同步任务管理平台，支持将大量、复杂的生产环境中的数据从 MySQL 或 MariaDB 迁移到 TiDB。 + +DM 功能如下： + +- 数据迁移 + - 支持导出与导入源数据库的初始全量数据，并在数据迁移过程中读取、应用来自源数据库存储的 binlog，从而保持数据的同步。 + - 通过合并上游的多个 MySQL 或 MariaDB 实例或集群的表，DM 能迁移生产环境中的分库分表。 +- 将 TiDB 作为 MySQL 或 MariaDB 的从库时，DM 能持续提高数据库水平扩展的能力，或在无需 ETL 作业的情况下，在 TiDB 上进行数据实时分析。 + +本教程主要介绍如何使用 DM 迁移上游多个 MySQL 实例的一个分片表。包括两种场景： + +- 合并若干个互不冲突的表或分片，即这些表或分片的表结构并不会造成唯一键的冲突； +- 合并唯一键存在冲突的表。 + +本教程假设目前使用的是一台新的、纯净版 CentOS 7 实例，你能（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为需要运行多个服务，建议内存最好在 1 GB 以上。 + +> **警告：** +> +> 本教程中 TiDB 的部署方法并**不适用**于生产或开发环境。 + +## Data Migration 架构 + +![TiDB Data Migration 架构](/media/dm-architecture.png) + +TiDB Data Migration 平台由 3 部分组成：DM-master、DM-worker 和 dmctl。 + +* DM-master 负责管理和调度数据同步任务的操作。 +* DM-worker 负责执行特定的数据同步任务。 +* dmctl 是一个命令行工具，用于控制 DM 集群。 + +`.yaml` 文件中定义了各个数据同步任务，dmctl 会读取这些文件，并且这些文件会被提交给 DM-master。DM-master 再将关于给定任务的相应职责告知每个 DM-worker 实例。 + +详情参见 [Data Migration 简介](/reference/tools/data-migration/overview.md)。 + +## 安装 + +本部分介绍如何部署 3 个 MySQL Server 实例及 `pd-server`、`tikv-server` 和 `tidb-server` 实例各 1 个，以及如何启动 1 个 DM-master 和 3 个 DM-worker 实例。 + +1. 安装 MySQL 5.7，下载或提取 TiDB v3.0 以及 DM v1.0.2 安装包： + + {{< copyable "shell-regular" >}} + + ```bash + sudo yum install -y http://repo.mysql.com/yum/mysql-5.7-community/el/7/x86_64/mysql57-community-release-el7-10.noarch.rpm && + sudo yum install -y mysql-community-server && + curl https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - && + curl https://download.pingcap.org/dm-v1.0.2-linux-amd64.tar.gz | tar xzf - && + curl -L https://github.com/pingcap/docs/raw/master/dev/how-to/get-started/dm-cnf/dm-cnf.tgz | tar xvzf - + ``` + +2. 创建目录和符号链接： + + {{< copyable "shell-regular" >}} + + ```bash + mkdir -p bin data logs && + ln -sf -t bin/ "$HOME"/*/bin/* && + [[ :$PATH: = *:$HOME/bin:* ]] || echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile && . ~/.bash_profile + ``` + +3. 安装 3 个 MySQL Server 实例的配置： + + {{< copyable "shell-regular" >}} + + ```bash + tee -a "$HOME/.my.cnf" <}} + + ```bash + for i in 1 2 3 + do + echo "mysql$i" + mysqld --defaults-group-suffix="$i" --initialize-insecure + mysqld --defaults-group-suffix="$i" & + done + ``` + +5. 执行 `jobs` 和/或 `pgrep -a mysqld` 以确保 MySQL Server 实例都在运行状态。 + + {{< copyable "shell-regular" >}} + + ```bash + jobs + ``` + + ``` + [1] Running mysqld --defaults-group-suffix="$i" & + [2]- Running mysqld --defaults-group-suffix="$i" & + [3]+ Running mysqld --defaults-group-suffix="$i" & + ``` + + {{< copyable "shell-regular" >}} + + ```bash + pgrep -a mysqld + ``` + + ``` + 17672 mysqld --defaults-group-suffix=1 + 17727 mysqld --defaults-group-suffix=2 + 17782 mysqld --defaults-group-suffix=3 + ``` + +## 同步分片数据 + +本示例场景包含 3 个分片，这些分片表结构相同，但自增主键并不重叠。 + +在 `.my.cnf` 文件中设置 `auto-increment-increment=5` 和 `auto-increment-offset` 可以实现这种情况。将 `auto-increment-increment` 设置为 5，则这些实例的自增 ID 以 5 为单位递增；每个实例的 `auto-increment-offset` 都设置得不同，则这些实例的偏移为 0 到开始计数的值。例如，若一个实例的 `auto-increment-increment` 为 5，`auto-increment-offset` 为 2，则会生成自增 ID 序列 {2,7,12,17,22,…}。 + +1. 对于这 3 个 MySQL Server 实例，每个实例都分别创建数据库和表： + + {{< copyable "shell-regular" >}} + + ```bash + for i in 1 2 3 + do + mysql -h 127.0.0.1 -P "$((3306+i))" -u root <}} + + ```bash + for i in 1 2 3; do + mysql -h 127.0.0.1 -P "$((3306+i))" -u root dmtest1 <}} + + ```bash + for i in 1 2 3; do + mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select * from dmtest1.t1' + done | sort -n + ``` + +注意返回的列表左侧是一列递增的、无重叠的 ID，右侧的端口编号显示这些数据插入到哪些实例以及从哪些实例中查询： + +``` +... +1841 e8dfff4676a47048d6f0c4ef899593dd 3307 +1842 57c0531e13f40b91b3b0f1a30b529a1d 3308 +1843 4888241374e8c62ddd9b4c3cfd091f96 3309 +1846 f45a1078feb35de77d26b3f7a52ef502 3307 +1847 82cadb0649a3af4968404c9f6031b233 3308 +1848 7385db9a3f11415bc0e9e2625fae3734 3309 +1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 +1852 eb1e78328c46506b46a4ac4a1e378b91 3308 +1853 7503cfacd12053d309b6bed5c89de212 3309 +1856 3c947bc2f7ff007b86a9428b74654de5 3307 +1857 a3545bd79d31f9a72d3a78690adf73fc 3308 +1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 +``` + +### 启动 DM-master 和 DM-worker + +本小节介绍如何使用 DM 将来自不同的 MySQL 实例的数据合并到 TiDB 的一张表里。 + +配置文件包 `dm-cnf.tgz` 包含： + +- TiDB 集群组件和 DM 组件的配置 +- 本教程后文介绍的 2 个 DM 任务的配置 + +1. 启动单个 `tidb-server` 实例、每个 MySQL Server 实例 （总共 3 个实例）的 DM-worker 进程和一个 DM-master 进程： + + {{< copyable "shell-regular" >}} + + ```bash + tidb-server --log-file=logs/tidb-server.log & + for i in 1 2 3; do dm-worker --config=dm-cnf/dm-worker$i.toml & done + dm-master --config=dm-cnf/dm-master.toml & + ``` + +2. 执行 `jobs` 和/或 `ps -a`，确保这些进程都正在运行： + + {{< copyable "shell-regular" >}} + + ```bash + jobs + ``` + + ``` + [1] Running mysqld --defaults-group-suffix="$i" & + [2] Running mysqld --defaults-group-suffix="$i" & + [3] Running mysqld --defaults-group-suffix="$i" & + [4] Running tidb-server --log-file=logs/tidb-server.log & + [5] Running dm-worker --config=dm-cnf/dm-worker$i.toml & + [6] Running dm-worker --config=dm-cnf/dm-worker$i.toml & + [7]- Running dm-worker --config=dm-cnf/dm-worker$i.toml & + [8]+ Running dm-master --config=dm-cnf/dm-master.toml & + ``` + + {{< copyable "shell-regular" >}} + + ```bash + ps -a + ``` + + ``` + PID TTY TIME CMD + 17317 pts/0 00:00:00 screen + 17672 pts/1 00:00:04 mysqld + 17727 pts/1 00:00:04 mysqld + 17782 pts/1 00:00:04 mysqld + 18586 pts/1 00:00:02 tidb-server + 18587 pts/1 00:00:00 dm-worker + 18588 pts/1 00:00:00 dm-worker + 18589 pts/1 00:00:00 dm-worker + 18590 pts/1 00:00:00 dm-master + 18892 pts/1 00:00:00 ps + ``` + +每个上游的 MySQL Server 实例对应一个单独的 DM-worker 实例，每个 DM-worker 实例都有各自的配置文件。这些文件内容包括： + +- 连接到上游 MySQL Server 的详细信息 +- relay log（上游服务器的 binlog）的存储路径 +- mydumper 的输出 + +各个 DM-worker 通过不同的端口监听（由 `worker-addr` 定义）。 + +以下为 `dm-worker1.toml` 的示例： + +{{< copyable "" >}} + +```toml +# DM-worker 配置 + +server-id = 1 +source-id = "mysql1" +flavor = "mysql" +worker-addr = ":8262" +log-file = "logs/worker1.log" +relay-dir = "data/relay1" +meta-dir = "data/meta1" +dir = "data/dump1" + +[from] +host = "127.0.0.1" +user = "root" +password = "" +port = 3307 +``` + +- 如果从 MySQL Server、Percona Server、Percona XtraDB Cluster、Amazon Aurora 或 RDS 迁移数据，则 `flavor` 配置项应设为 "mysql"（默认值，支持 5.5 < MySQL 版本 < 8.0）。 +- 如果从 MariaDB Server 或 MariaDB (Galera) Cluster 迁移数据，则设置 `flavor = "mariadb"`（仅支持 10.1.2 以上 MariaDB 版本）。 +- 从 DM 1.0.2 版本开始，`flavor`、`server-id` 项均会由 DM 自动生成，一般情况下不需要手动配置。 +- `from` 中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见[使用 dmctl 加密上游 MySQL 用户密码](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 + +任务在 YAML 文件中定义。以下为一个 `dmtask1.yaml` 文件示例： + +{{< copyable "" >}} + +```yaml +name: dmtask1 +task-mode: all +is-sharding: true +enable-heartbeat: true +ignore-checking-items: ["auto_increment_ID"] + +target-database: + host: "127.0.0.1" + port: 4000 + user: "root" + password: "" + +mysql-instances: + - source-id: "mysql1" + server-id: 1 + black-white-list: "dmtest1" + loader-config-name: "loader1" + - source-id: "mysql2" + server-id: 2 + black-white-list: "dmtest1" + loader-config-name: "loader2" + - source-id: "mysql3" + server-id: 3 + black-white-list: "dmtest1" + loader-config-name: "loader3" + +black-white-list: + dmtest1: + do-dbs: ["dmtest1"] + +loaders: + loader1: + dir: "data/dump1" + loader2: + dir: "data/dump2" + loader3: + dir: "data/dump3" +``` + +以上文件包含一些全局配置项和几组定义各种行为的配置项。 + +* `task-mode: all`：DM 导入上游实例的全量备份，并使用上游 MySQL Server 的 binlog 进行增量同步。 + + * 此外，可将 `task-mode` 设置为 `full` 或 `incremental` 以分别进行全量备份或增量同步。 + +* `is-sharding: true`：多个 DM-worker 实例进行同一个任务，这些实例将上游的若干分片合并到一个下游的表中。 + +* `ignore-checking-items: ["auto_increment_ID"]`：关闭 DM 对上游实例中潜在的自增 ID 冲突的检测。DM 能检测出上游表结构相同、并包含自增列的分片间潜在的列值冲突。通过配置 `auto-increment-increment` 和 `auto-increment-offset` 可使每个 MySQL Server 的 ID 都不重叠，从而避免不同表之间冲突的产生。因此，可以让 DM 关闭对自增 ID 冲突的检测。 + +* `black-white-list`：将一个任务限制在数据库 `dmtest` 中。 + +* `loaders`：定义由各个 DM-worker 实例执行的每个 mydumper 实例的输出地址。 + +* `target-database`：定义目标数据库的链接信息，其中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见 [使用 dmctl 加密上游 MySQL 用户密码](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 + +`dmctl` 是控制 DM 集群的命令行工具，用于启动任务、查询任务状态。执行 `dmctl -master-addr :8261` 获取如下交互提示，从而启动该工具： + +{{< copyable "shell-regular" >}} + +```bash +dmctl -master-addr :8261 +``` + +``` +Welcome to dmctl +Release Version: v1.0.0-alpha-69-g5134ad1 +Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 +Git Branch: master +UTC Build Time: 2019-04-29 09:36:42 +Go Version: go version go1.12 linux/amd64 + +» +``` + +执行 `start-task dm-cnf/dmtask1.yaml` 启动 `dmtask1`： + +{{< copyable "shell-regular" >}} + +```bash +start-task dm-cnf/dmtask1.yaml +``` + +``` +{ + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "127.0.0.1:8262", + "msg": "" + }, + { + "result": true, + "worker": "127.0.0.1:8263", + "msg": "" + }, + { + "result": true, + "worker": "127.0.0.1:8264", + "msg": "" + } + ] +} +``` + +启动该任务意味着启动任务配置文件中定义的行为，包括执行 mydumper 和 loader 实例，加载初次 dump 的数据后，将 DM-worker 作为同步任务的 slave 连接到上游的 MySQL Server。 + +所有的行数据都被迁移到 TiDB Server： + +{{< copyable "shell-regular" >}} + +```bash +mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail +``` + +输出结果： + +``` +... +1843 4888241374e8c62ddd9b4c3cfd091f96 3309 +1846 f45a1078feb35de77d26b3f7a52ef502 3307 +1847 82cadb0649a3af4968404c9f6031b233 3308 +1848 7385db9a3f11415bc0e9e2625fae3734 3309 +1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 +1852 eb1e78328c46506b46a4ac4a1e378b91 3308 +1853 7503cfacd12053d309b6bed5c89de212 3309 +1856 3c947bc2f7ff007b86a9428b74654de5 3307 +1857 a3545bd79d31f9a72d3a78690adf73fc 3308 +1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 +``` + +现在 DM 正作为每个 MySQL Server 的 slave，读取 MySQL Server 的 binlog，将更新的数据实时同步到下游的 TiDB Server： + +{{< copyable "shell-regular" >}} + +```bash +for i in 1 2 3 +do + mysql -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select host, command, state from information_schema.processlist where command="Binlog Dump"' +done +``` + +输出结果： + +``` ++-----------------+-------------+---------------------------------------------------------------+ +| host | command | state | ++-----------------+-------------+---------------------------------------------------------------+ +| localhost:42168 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | ++-----------------+-------------+---------------------------------------------------------------+ ++-----------------+-------------+---------------------------------------------------------------+ +| host | command | state | ++-----------------+-------------+---------------------------------------------------------------+ +| localhost:42922 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | ++-----------------+-------------+---------------------------------------------------------------+ ++-----------------+-------------+---------------------------------------------------------------+ +| host | command | state | ++-----------------+-------------+---------------------------------------------------------------+ +| localhost:56798 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | ++-----------------+-------------+---------------------------------------------------------------+ +``` + +向上游 MySQL Server 插入几行数据，更新 MySQL 中的这些行，并再次查询这些行： + +{{< copyable "shell-regular" >}} + +```bash +for i in 1 2 3; do + mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'insert into t1 (id) select null from t1' dmtest1 +done +mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail +``` + +输出结果： + +``` +6313 NULL NULL +6316 NULL NULL +6317 NULL NULL +6318 NULL NULL +6321 NULL NULL +6322 NULL NULL +6323 NULL NULL +6326 NULL NULL +6327 NULL NULL +6328 NULL NULL +``` + +更新这些行，则可见更新的数据已同步到 TiDB 中： + +{{< copyable "shell-regular" >}} + +```bash +for i in 1 2 3; do + mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'update t1 set c=md5(id), port=@@port' dmtest1 +done | sort -n +mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail +``` + +输出结果： + +``` +6313 2118d8a1b7004ed5baf5347a4f99f502 3309 +6316 6107d91fc9a0b04bc044aa7d8c1443bd 3307 +6317 0e9b734aa25ca8096cb7b56dc0dd8929 3308 +6318 b0eb9a95e8b085e4025eae2f0d76a6a6 3309 +6321 7cb36e23529e4de4c41460940cc85e6e 3307 +6322 fe1f9c70bdf347497e1a01b6c486bdb9 3308 +6323 14eac0d254a6ccaf9b67584c7830a5c0 3309 +6326 17b65afe58c49edc1bdd812c554ee3bb 3307 +6327 c54bc2ded4480856dc9f39bdcf35a3e7 3308 +6328 b294504229c668e750dfcc4ea9617f0a 3309 +``` + +只要 DM-master 和 DM-worker 运行 `dmtest1` 任务，下游的 TiDB Server 将持续和上游的 MySQL Server 实例保持同步的状态。 + +## 结论 + +本教程完成了上游 3 个 MySQL Server 实例的分片迁移，介绍了分片迁移中，DM 如何在集群中导入初始数据，以及如何读取 MySQL 的 binlog 来同步增量数据，从而使下游 TiDB 集群与上游实例保持同步。 + +关于 DM 的更多详情，请参考 [Data Migration 简介](/reference/tools/data-migration/overview.md)，或加入 [TiDB Community Slack](https://pingcap.com/tidbslack/) channel 参与讨论。 diff --git a/how-to/get-started/deploy-tidb-from-docker-compose.md b/how-to/get-started/deploy-tidb-from-docker-compose.md new file mode 100644 index 000000000000..f0fde2d9bf93 --- /dev/null +++ b/how-to/get-started/deploy-tidb-from-docker-compose.md @@ -0,0 +1,205 @@ +--- +title: 使用 Docker Compose 快速构建 TiDB 集群 +category: how-to +--- + +# 使用 Docker Compose 快速构建 TiDB 集群 + +本文档介绍如何在单机上通过 Docker Compose 快速一键部署一套 TiDB 测试集群。[Docker Compose](https://docs.docker.com/compose/overview) 可以通过一个 YAML 文件定义多个容器的应用服务，然后一键启动或停止。 + +> **警告：** +> +> 对于生产环境，不要使用 Docker Compose 进行部署，而应[使用 Ansible 部署 TiDB 集群](/how-to/deploy/orchestrated/ansible.md)。 + +## 准备环境 + +确保你的机器上已安装： + +- Docker（17.06.0 及以上版本） +- Docker Compose +- Git + +## 快速部署 + +1. 下载 `tidb-docker-compose` + + {{< copyable "shell-regular" >}} + + ```bash + git clone https://github.com/pingcap/tidb-docker-compose.git + ``` + +2. 创建并启动集群 + + 获取最新 Docker 镜像： + + {{< copyable "shell-regular" >}} + + ```bash + cd tidb-docker-compose && docker-compose pull && docker-compose up -d + ``` + +3. 访问集群 + + {{< copyable "shell-regular" >}} + + ```bash + mysql -h 127.0.0.1 -P 4000 -u root + ``` + + 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 + + [集群数据可视化](https://github.com/pingcap/tidb-vision)： + +## 自定义集群 + +在完成快速部署后，以下组件已默认部署：3 个 PD，3 个 TiKV，1 个 TiDB 和监控组件 Prometheus，Pushgateway，Grafana 以及 tidb-vision。 + +如果想自定义集群，可以直接修改 `docker-compose.yml`，但是手动修改比较繁琐而且容易出错，强烈建议使用 [Helm](https://helm.sh) 模板引擎生成 `docker-compose.yml` 文件。 + +1. 安装 Helm + + [Helm](https://helm.sh) 可以用作模板渲染引擎，只需要下载其 binary 文件即可以使用。 + + {{< copyable "shell-regular" >}} + + ```bash + curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash + ``` + + 如果是 Mac 系统，也可以通过 Homebrew 安装： + + {{< copyable "shell-regular" >}} + + ```bash + brew install kubernetes-helm + ``` + +2. 下载 `tidb-docker-compose` + + {{< copyable "shell-regular" >}} + + ```bash + git clone https://github.com/pingcap/tidb-docker-compose.git + ``` + +3. 自定义集群 + + {{< copyable "shell-regular" >}} + + ```bash + cd tidb-docker-compose && + cp compose/values.yaml values.yaml && + vim values.yaml + ``` + + 修改 `values.yaml` 里面的配置，例如集群规模，TiDB 镜像版本等。 + + [tidb-vision](https://github.com/pingcap/tidb-vision) 是 TiDB 集群可视化页面，可以可视化地显示 PD 对 TiKV 数据的调度。如果不想部署该组件，可以将 `tidbVision` 项留空。 + + PD，TiKV，TiDB 和 tidb-vision 支持从 GitHub 源码或本地文件构建 Docker 镜像，供开发测试使用。 + + - 如果希望从本地已编译好的 binary 文件构建 PD，TiKV 或 TiDB 镜像，需要将其 `image` 字段留空，并将已编译好的 binary 拷贝到对应的 `pd/bin/pd-server`，`tikv/bin/tikv-server`，`tidb/bin/tidb-server`。 + + - 如果希望从本地构建 tidb-vision 镜像，需要将其 `image` 字段留空，并将 tidb-vision 项目拷贝到 `tidb-vision/tidb-vision`。 + +4. 生成 `docker-compose.yml` 文件 + + {{< copyable "shell-regular" >}} + + ```bash + helm template -f values.yaml compose > generated-docker-compose.yml + ``` + +5. 使用生成的 `docker-compose.yml` 创建并启动集群 + + 获取最新 Docker 镜像： + + {{< copyable "shell-regular" >}} + + ```bash + docker-compose -f generated-docker-compose.yml pull + ``` + + {{< copyable "shell-regular" >}} + + ```bash + docker-compose -f generated-docker-compose.yml up -d + ``` + +6. 访问集群 + + {{< copyable "shell-regular" >}} + + ```bash + mysql -h 127.0.0.1 -P 4000 -u root + ``` + + 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 + + 如果启用了 tidb-vision，可以通过 查看。 + +## 访问 Spark shell 并加载 TiSpark + +向 TiDB 集群中插入一些样本数据： + +{{< copyable "shell-regular" >}} + +```bash +docker-compose exec tispark-master bash && +cd /opt/spark/data/tispark-sample-data && +mysql -h tidb -P 4000 -u root < dss.ddl +``` + +当样本数据加载到 TiDB 集群之后，可以使用 `docker-compose exec tispark-master /opt/spark/bin/spark-shell` 来访问 Spark shell。 + +{{< copyable "shell-regular" >}} + +```bash +docker-compose exec tispark-master /opt/spark/bin/spark-shell +``` + +``` +... +Spark context available as 'sc' (master = local[*], app id = local-1527045927617). +Spark session available as 'spark'. +Welcome to + ____ __ + / __/__ ___ _____/ /__ + _\ \/ _ \/ _ `/ __/ '_/ + /___/ .__/\_,_/_/ /_/\_\ version 2.1.1 + /_/ + +Using Scala version 2.11.8 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_172) +Type in expressions to have them evaluated. +Type :help for more information. +``` + +```shell +scala> import org.apache.spark.sql.TiContext +... +scala> val ti = new TiContext(spark) +... +scala> ti.tidbMapDatabase("TPCH_001") +... +scala> spark.sql("select count(*) from lineitem").show +``` + +``` ++--------+ +|count(1)| ++--------+ +| 60175| ++--------+ +``` + +你也可以通过 Python 或 R 来访问 Spark： + +{{< copyable "shell-regular" >}} + +```bash +docker-compose exec tispark-master /opt/spark/bin/pyspark && +docker-compose exec tispark-master /opt/spark/bin/sparkR +``` + +更多关于 TiSpark 的信息，参见 [TiSpark 的详细文档](/how-to/get-started/tispark.md)。 diff --git a/how-to/get-started/explore-sql.md b/how-to/get-started/explore-sql.md new file mode 100644 index 000000000000..32599b670888 --- /dev/null +++ b/how-to/get-started/explore-sql.md @@ -0,0 +1,274 @@ +--- +title: TiDB 中的基本 SQL 操作 +category: how-to +--- + +# TiDB 中的基本 SQL 操作 + +成功部署 TiDB 集群之后，便可以在 TiDB 中执行 SQL 语句了。因为 TiDB 兼容 MySQL，你可以使用 MySQL 客户端连接 TiDB，并且[大多数情况下](/reference/mysql-compatibility.md)可以直接执行 MySQL 语句。 + +本文介绍 CRUD 操作等基本的 SQL 语句。完整的 SQL 语句列表，参见 [TiDB SQL 语法详解](https://pingcap.github.io/sqlgram/)。 + +## 创建、查看和删除数据库 + +使用 `CREATE DATABASE` 语句创建数据库。语法如下： + +{{< copyable "sql" >}} + +```sql +CREATE DATABASE db_name [options]; +``` + +例如，要创建一个名为 `samp_db` 的数据库，可使用以下语句： + +{{< copyable "sql" >}} + +```sql +CREATE DATABASE IF NOT EXISTS samp_db; +``` + +使用 `SHOW DATABASES` 语句查看数据库： + +{{< copyable "sql" >}} + +```sql +SHOW DATABASES; +``` + +使用 `DROP DATABASE` 语句删除数据库，例如： + +{{< copyable "sql" >}} + +```sql +DROP DATABASE samp_db; +``` + +## 创建、查看和删除表 + +使用 `CREATE TABLE` 语句创建表。语法如下： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE table_name column_name data_type constraint; +``` + +例如： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE person ( + number INT(11), + name VARCHAR(255), + birthday DATE + ); +``` + +如果表已存在，添加 `IF NOT EXISTS` 可防止发生错误： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE IF NOT EXISTS person ( + number INT(11), + name VARCHAR(255), + birthday DATE +); +``` + +使用 `SHOW CREATE` 语句查看建表语句。例如： + +{{< copyable "sql" >}} + +```sql +SHOW CREATE table person; +``` + +使用 `SHOW FULL COLUMNS` 语句查看表的列。 例如： + +{{< copyable "sql" >}} + +```sql +SHOW FULL COLUMNS FROM person; +``` + +使用 `DROP TABLE` 语句删除表。例如： + +{{< copyable "sql" >}} + +```sql +DROP TABLE person; +``` + +或者 + +{{< copyable "sql" >}} + +```sql +DROP TABLE IF EXISTS person; +``` + +使用 `SHOW TABLES` 语句查看数据库中的所有表。例如： + +{{< copyable "sql" >}} + +```sql +SHOW TABLES FROM samp_db; +``` + +## 创建、查看和删除索引 + +对于值不唯一的列，可使用 `CREATE INDEX` 或 `ALTER TABLE` 语句。例如： + +{{< copyable "sql" >}} + +```sql +CREATE INDEX person_num ON person (number); +``` + +或者 + +{{< copyable "sql" >}} + +```sql +ALTER TABLE person ADD INDEX person_num (number); +``` + +对于值唯一的列，可以创建唯一索引。例如： + +{{< copyable "sql" >}} + +```sql +CREATE UNIQUE INDEX person_num ON person (number); +``` + +或者 + +{{< copyable "sql" >}} + +```sql +ALTER TABLE person ADD UNIQUE person_num (number); +``` + +使用 `SHOW INDEX` 语句查看表内所有索引： + +{{< copyable "sql" >}} + +```sql +SHOW INDEX from person; +``` + +使用 `ALTER TABLE` 或 `DROP INDEX` 语句来删除索引。与 `CREATE INDEX` 语句类似，`DROP INDEX` 也可以嵌入 `ALTER TABLE` 语句。例如： + +{{< copyable "sql" >}} + +```sql +DROP INDEX person_num ON person; +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE person DROP INDEX person_num; +``` + +## 增删改查数据 + +使用 `INSERT` 语句向表内插入数据。例如： + +{{< copyable "sql" >}} + +```sql +INSERT INTO person VALUES("1","tom","20170912"); +``` + +使用 `SELECT` 语句检索表内数据。例如： + +{{< copyable "sql" >}} + +```sql +SELECT * FROM person; +``` + +``` ++--------+------+------------+ +| number | name | birthday | ++--------+------+------------+ +| 1 | tom | 2017-09-12 | ++--------+------+------------+ +``` + +使用 `UPDATE` 语句修改表内数据。例如： + +{{< copyable "sql" >}} + +```sql +UPDATE person SET birthday='20171010' WHERE name='tom'; +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM person; +``` + +``` ++--------+------+------------+ +| number | name | birthday | ++--------+------+------------+ +| 1 | tom | 2017-10-10 | ++--------+------+------------+ +``` + +使用 `DELETE` 语句删除表内数据： + +{{< copyable "sql" >}} + +```sql +DELETE FROM person WHERE number=1; +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM person; +``` + +``` +Empty set (0.00 sec) +``` + +## 创建、授权和删除用户 + +使用 `CREATE USER` 语句创建一个用户 `tiuser`，密码为 `123456`： + +{{< copyable "sql" >}} + +```sql +CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456'; +``` + +授权用户 `tiuser` 可检索数据库 `samp_db` 内的表： + +{{< copyable "sql" >}} + +```sql +GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost'; +``` + +查询用户 `tiuser` 的权限： + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS for tiuser@localhost; +``` + +删除用户 `tiuser`： + +{{< copyable "sql" >}} + +```sql +DROP USER 'tiuser'@'localhost'; +``` diff --git a/how-to/get-started/read-historical-data.md b/how-to/get-started/read-historical-data.md new file mode 100644 index 000000000000..f98ef21783fe --- /dev/null +++ b/how-to/get-started/read-historical-data.md @@ -0,0 +1,194 @@ +--- +title: 读取历史数据 +category: how-to +--- + +# 读取历史数据 + +本文档介绍 TiDB 如何读取历史版本数据，包括具体的操作流程以及历史数据的保存策略。 + +## 功能说明 + +TiDB 实现了通过标准 SQL 接口读取历史数据功能，无需特殊的 client 或者 driver。当数据被更新、删除后，依然可以通过 SQL 接口将更新/删除前的数据读取出来。 + +另外即使在更新数据之后，表结构发生了变化，TiDB 依旧能用旧的表结构将数据读取出来。 + +## 操作流程 + +为支持读取历史版本数据， 引入了一个新的 system variable: tidb_snapshot ，这个变量是 Session 范围有效，可以通过标准的 Set 语句修改其值。其值为文本，能够存储 TSO 和日期时间。TSO 即是全局授时的时间戳，是从 PD 端获取的; 日期时间的格式可以为： +“2016-10-08 16:45:26.999”，一般来说可以只写到秒，比如”2016-10-08 16:45:26”。 +当这个变量被设置时，TiDB 会用这个时间戳建立 Snapshot（没有开销，只是创建数据结构），随后所有的 Select 操作都会在这个 Snapshot 上读取数据。 + +> **注意：** +> +> TiDB 的事务是通过 PD 进行全局授时，所以存储的数据版本也是以 PD 所授时间戳作为版本号。在生成 Snapshot 时，是以 tidb_snapshot 变量的值作为版本号，如果 TiDB Server 所在机器和 PD Server 所在机器的本地时间相差较大，需要以 PD 的时间为准。 + +当读取历史版本操作结束后，可以结束当前 Session 或者是通过 Set 语句将 tidb_snapshot 变量的值设为 ""，即可读取最新版本的数据。 + +## 历史数据保留策略 + +TiDB 使用 MVCC 管理版本，当更新/删除数据时，不会做真正的数据删除，只会添加一个新版本数据，所以可以保留历史数据。历史数据不会全部保留，超过一定时间的历史数据会被彻底删除，以减小空间占用以及避免历史版本过多引入的性能开销。 + +TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理，关于 GC 的详细介绍参见 [TiDB 垃圾回收 (GC)](/reference/garbage-collection/overview.md)。 + +这里需要重点关注的是 `tikv_gc_life_time` 和 `tikv_gc_safe_point` 这条。`tikv_gc_life_time` 用于配置历史版本保留时间，可以手动修改；`tikv_gc_safe_point` 记录了当前的 safePoint，用户可以安全地使用大于 safePoint 的时间戳创建 snapshot 读取历史版本。safePoint 在每次 GC 开始运行时自动更新。 + +## 示例 + +1. 初始化阶段，创建一个表，并插入几行数据： + + {{< copyable "sql" >}} + + ```sql + create table t (c int); + ``` + + ``` + Query OK, 0 rows affected (0.01 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + insert into t values (1), (2), (3); + ``` + + ``` + Query OK, 3 rows affected (0.00 sec) + ``` + +2. 查看表中的数据： + + {{< copyable "sql" >}} + + ```sql + select * from t; + ``` + + ``` + +------+ + | c | + +------+ + | 1 | + | 2 | + | 3 | + +------+ + 3 rows in set (0.00 sec) + ``` + +3. 查看当前时间： + + {{< copyable "sql" >}} + + ```sql + select now(); + ``` + + ``` + +---------------------+ + | now() | + +---------------------+ + | 2016-10-08 16:45:26 | + +---------------------+ + 1 row in set (0.00 sec) + ``` + +4. 更新某一行数据： + + {{< copyable "sql" >}} + + ```sql + update t set c=22 where c=2; + ``` + + ``` + Query OK, 1 row affected (0.00 sec) + ``` + +5. 确认数据已经被更新： + + {{< copyable "sql" >}} + + ```sql + select * from t; + ``` + + ``` + +------+ + | c | + +------+ + | 1 | + | 22 | + | 3 | + +------+ + 3 rows in set (0.00 sec) + ``` + +6. 设置一个特殊的环境变量，这个是一个 session scope 的变量，其意义为读取这个时间之前的最新的一个版本。 + + {{< copyable "sql" >}} + + ```sql + set @@tidb_snapshot="2016-10-08 16:45:26"; + ``` + + ``` + Query OK, 0 rows affected (0.00 sec) + ``` + + > **注意：** + > + > - 这里的时间设置的是 update 语句之前的那个时间。 + > - 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 + + 这里读取到的内容即为 update 之前的内容，也就是历史版本： + + {{< copyable "sql" >}} + + ```sql + select * from t; + ``` + + ``` + +------+ + | c | + +------+ + | 1 | + | 2 | + | 3 | + +------+ + 3 rows in set (0.00 sec) + ``` + +7. 清空这个变量后，即可读取最新版本数据： + + {{< copyable "sql" >}} + + ```sql + set @@tidb_snapshot=""; + ``` + + ``` + Query OK, 0 rows affected (0.00 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + select * from t; + ``` + + ``` + +------+ + | c | + +------+ + | 1 | + | 22 | + | 3 | + +------+ + 3 rows in set (0.00 sec) + ``` + + > **注意：** + > + > 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 diff --git a/how-to/get-started/tidb-binlog.md b/how-to/get-started/tidb-binlog.md new file mode 100644 index 000000000000..4635d34c290b --- /dev/null +++ b/how-to/get-started/tidb-binlog.md @@ -0,0 +1,521 @@ +--- +title: TiDB Binlog 教程 +category: how-to +--- + +# TiDB Binlog 教程 + +本文档主要介绍如何使用 TiDB Binlog 将数据从 TiDB 推送到 MariaDB 实例。文中的 TiDB Binlog 集群包含 Pump 和 Drainer 的单个节点，TiDB 集群包含 TiDB、TiKV 和 Placement Driver (PD) 各组件的单个节点。 + +希望上手实践 TiDB Binlog 工具的用户需要对 [TiDB 架构](/architecture.md)有一定的了解，最好有创建过 TiDB 集群的经验。该文档也有助于简单快速了解 TiDB Binlog 架构以及相关概念。 + +> **警告：** +> +> 该文档中部署 TiDB 的操作指导**不适用于**在生产或研发环境中部署 TiDB 的情况。 + +该文档假设用户使用的是现代 Linux 发行版本中的 x86-64。示例中使用的是 VMware 中运行的 CentOS 7 最小化安装。建议在一开始就进行清洁安装，以避免受现有环境中未知情况的影响。如果不想使用本地虚拟环境，也可以使用云服务启动 CentOS 7 VM。 + +## TiDB Binlog 简介 + +TiDB Binlog 用于收集 TiDB 中二进制日志数据、提供实时数据备份和同步以及将 TiDB 集群的数据增量同步到下游。 + +TiDB Binlog 支持以下功能场景： + +- 增量备份，将 TiDB 集群中的数据增量同步到另一个集群，或通过 Kafka 增量同步到选择的下游。 +- 当使用 TiDB DM (Data Migration) 将数据从上游 MySQL 或者 MariaDB 迁移到 TiDB 集群时，可使用 TiDB Binlog 保持 TiDB 集群与其一个独立下游 MySQL 或 MariaDB 实例或集群同步。当 TiDB 集群上游数据迁移过程中出现问题，下游数据同步过程中可使用 TiDB Binlog 恢复数据到原先的状态。 + +更多信息参考 [TiDB Binlog Cluster 版本用户文档](/reference/tidb-binlog/overview.md)。 + +## 架构 + +TiDB Binlog 集群由 **Pump** 和 **Drainer** 两个组件组成。一个 Pump 集群中有若干个 Pump 节点。TiDB 实例连接到各个 Pump 节点并发送 binlog 数据到 Pump 节点。Pump 集群连接到 Drainer 节点，Drainer 将接收到的更新数据转换到某个特定下游（例如 Kafka、另一个 TiDB 集群或 MySQL 或 MariaDB Server）指定的正确格式。 + +![TiDB Binlog architecture](/media/tidb_binlog_cluster_architecture.png) + +Pump 的集群架构能确保 TiDB 或 Pump 集群中有新的实例加入或退出时更新数据不会丢失。 + +## 安装 + +由于 RHEL/CentOS 7 的默认包装库中包括 MariaDB Server，本示例选择的是 MariaDB Server。后续除了安装服务器，也需要安装客户端。安装指令如下： + +{{< copyable "shell-regular" >}} + +```bash +sudo yum install -y mariadb-server +``` + +{{< copyable "shell-regular" >}} + +```bash +curl -LO https://download.pingcap.org/tidb-latest-linux-amd64.tar.gz | tar xzf - && +cd tidb-latest-linux-amd64 +``` + +预期输出： + +``` + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 368M 100 368M 0 0 8394k 0 0:00:44 0:00:44 --:--:-- 11.1M +``` + +## 配置 + +通过执行以下步骤配置一个 TiDB 集群，该集群包括 `pd-server`、`tikv-server` 和 `tidb-server` 各组件的单个实例。 + +1. 填充配置文件： + + {{< copyable "shell-regular" >}} + + ```bash + printf > pd.toml %s\\n 'log-file="pd.log"' 'data-dir="pd.data"' && + printf > tikv.toml %s\\n 'log-file="tikv.log"' '[storage]' 'data-dir="tikv.data"' '[pd]' 'endpoints=["127.0.0.1:2379"]' '[rocksdb]' max-open-files=1024 '[raftdb]' max-open-files=1024 && + printf > pump.toml %s\\n 'log-file="pump.log"' 'data-dir="pump.data"' 'addr="127.0.0.1:8250"' 'advertise-addr="127.0.0.1:8250"' 'pd-urls="http://127.0.0.1:2379"' && + printf > tidb.toml %s\\n 'store="tikv"' 'path="127.0.0.1:2379"' '[log.file]' 'filename="tidb.log"' '[binlog]' 'enable=true' && + printf > drainer.toml %s\\n 'log-file="drainer.log"' '[syncer]' 'db-type="mysql"' '[syncer.to]' 'host="127.0.0.1"' 'user="root"' 'password=""' 'port=3306' + ``` + +2. 查看配置细节： + + {{< copyable "shell-regular" >}} + + ```bash + for f in *.toml; do echo "$f:"; cat "$f"; echo; done + ``` + + 预期输出： + + ``` + drainer.toml: + log-file="drainer.log" + [syncer] + db-type="mysql" + [syncer.to] + host="127.0.0.1" + user="root" + password="" + port=3306 + + pd.toml: + log-file="pd.log" + data-dir="pd.data" + + pump.toml: + log-file="pump.log" + data-dir="pump.data" + addr="127.0.0.1:8250" + advertise-addr="127.0.0.1:8250" + pd-urls="http://127.0.0.1:2379" + + tidb.toml: + store="tikv" + path="127.0.0.1:2379" + [log.file] + filename="tidb.log" + [binlog] + enable=true + + tikv.toml: + log-file="tikv.log" + [storage] + data-dir="tikv.data" + [pd] + endpoints=["127.0.0.1:2379"] + [rocksdb] + max-open-files=1024 + [raftdb] + max-open-files=1024 + ``` + +## 启动程序 + +现在可启动各个组件。推荐启动顺序依次为 Placement Driver (PD)、TiKV、Pump（TiDB 发送 binlog 日志必须连接 Pump 服务）、TiDB。 + +1. 启动所有服务： + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/pd-server --config=pd.toml &>pd.out & + ``` + + ``` + [1] 20935 + ``` + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/tikv-server --config=tikv.toml &>tikv.out & + ``` + + ``` + [2] 20944 + ``` + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/pump --config=pump.toml &>pump.out & + ``` + + ``` + [3] 21050 + ``` + + {{< copyable "shell-regular" >}} + + ```bash + sleep 3 && + ./bin/tidb-server --config=tidb.toml &>tidb.out & + ``` + + ``` + [4] 21058 + ``` + +2. 如果执行 `jobs`，可以看到后台正在运行的程序，列表如下： + + {{< copyable "shell-regular" >}} + + ```bash + jobs + ``` + + ``` + [1] Running ./bin/pd-server --config=pd.toml &>pd.out & + [2] Running ./bin/tikv-server --config=tikv.toml &>tikv.out & + [3]- Running ./bin/pump --config=pump.toml &>pump.out & + [4]+ Running ./bin/tidb-server --config=tidb.toml &>tidb.out & + ``` + + 如果有服务启动失败（例如出现 “`Exit 1`” 而不是 “`Running`”），尝试重启单个组件。 + +## 连接 + +按以上步骤操作后，TiDB 的 4 个组件开始运行。接下来可以使用以下 MariaDB 或 MySQL 命令行客户端，通过 4000 端口连接到 TiDB 服务： + +{{< copyable "shell-regular" >}} + +```bash +mysql -h 127.0.0.1 -P 4000 -u root -e 'select tidb_version();' +``` + +预期输出： + +``` +*************************** 1. row *************************** +tidb_version(): Release Version: v3.0.0-beta.1-154-gd5afff70c +Git Commit Hash: d5afff70cdd825d5fab125c8e52e686cc5fb9a6e +Git Branch: master +UTC Build Time: 2019-04-24 03:10:00 +GoVersion: go version go1.12 linux/amd64 +Race Enabled: false +TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e +Check Table Before Drop: false +``` + +连接后TiDB 集群已开始运行，`pump` 读取集群中的 binlog 数据，并在其数据目录中将 binlog 数据存储为 relay log。下一步是启动一个可供 `drainer` 写入的 MariaDB Server。 + +1. 启动 `drainer`： + + {{< copyable "shell-regular" >}} + + ```bash + sudo systemctl start mariadb && + ./bin/drainer --config=drainer.toml &>drainer.out & + ``` + + 如果你的操作系统更易于安装 MySQL，只需保证监听 3306 端口。另外，可使用密码为空的 "root" 用户连接到 MySQL，或调整 `drainer.toml` 连接到 MySQL。 + + {{< copyable "shell-regular" >}} + + ```bash + mysql -h 127.0.0.1 -P 3306 -u root + ``` + + 预期输出： + + ``` + Welcome to the MariaDB monitor. Commands end with ; or \g. + Your MariaDB connection id is 20 + Server version: 5.5.60-MariaDB MariaDB Server + + Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. + + Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + + MariaDB [(none)]> + ``` + + {{< copyable "sql" >}} + + ```sql + show databases; + ``` + + 预期输出： + + ``` + +--------------------+ + | Database | + +--------------------+ + | information_schema | + | mysql | + | performance_schema | + | test | + | tidb_binlog | + +--------------------+ + 5 rows in set (0.01 sec) + ``` + + 如下表格是包含 `checkpoint` 表格的 `tidb_binlog` 数据库。`drainer` 使用 `checkpoint` 表格，记录 TiDB 集群中的 binlog 已经更新到了哪个位置。 + + {{< copyable "sql" >}} + + ```sql + use tidb_binlog; + ``` + + ``` + Database changed + ``` + + {{< copyable "sql" >}} + + ```sql + select * from checkpoint; + ``` + + ``` + +---------------------+---------------------------------------------+ + | clusterID | checkPoint | + +---------------------+---------------------------------------------+ + | 6678715361817107733 | {"commitTS":407637466476445697,"ts-map":{}} | + +---------------------+---------------------------------------------+ + 1 row in set (0.00 sec) + ``` + + 打开另一个连接到 TiDB 的客户端，创建一个表格并插入几行数据。建议在 GNU Screen 软件中操作，从而同时打开多个客户端。 + + {{< copyable "shell-regular" >}} + + ```bash + mysql -h 127.0.0.1 -P 4000 --prompt='TiDB [\d]> ' -u root + ``` + + {{< copyable "sql" >}} + + ```sql + create database tidbtest; + ``` + + ``` + Query OK, 0 rows affected (0.12 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + use tidbtest; + ``` + + ``` + Database changed + ``` + + {{< copyable "sql" >}} + + ```sql + create table t1 (id int unsigned not null AUTO_INCREMENT primary key); + ``` + + ``` + Query OK, 0 rows affected (0.11 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + insert into t1 () values (),(),(),(),(); + ``` + + ``` + Query OK, 5 rows affected (0.01 sec) + Records: 5 Duplicates: 0 Warnings: 0 + ``` + + {{< copyable "sql" >}} + + ```sql + select * from t1; + ``` + + ``` + +----+ + | id | + +----+ + | 1 | + | 2 | + | 3 | + | 4 | + | 5 | + +----+ + 5 rows in set (0.00 sec) + ``` + + 切换回 MariaDB 客户端可看到新的数据库、新的表格和最近插入的行数据。 + + {{< copyable "sql" >}} + + ```sql + use tidbtest; + ``` + + ``` + Reading table information for completion of table and column names + You can turn off this feature to get a quicker startup with -A + + Database changed + ``` + + {{< copyable "sql" >}} + + ```sql + show tables; + ``` + + ``` + +--------------------+ + | Tables_in_tidbtest | + +--------------------+ + | t1 | + +--------------------+ + 1 row in set (0.00 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + select * from t1; + ``` + + ``` + +----+ + | id | + +----+ + | 1 | + | 2 | + | 3 | + | 4 | + | 5 | + +----+ + 5 rows in set (0.00 sec) + ``` + + 可看到查询 MariaDB 时插入到 TiDB 相同的行数据，表明 TiDB Binlog 安装成功。 + +## binlogctl + +加入到集群的 Pump 和 Drainer 的数据存储在 Placement Driver (PD) 中。binlogctl 可用于查询和修改状态信息。更多信息请参考 [binlogctl guide](/reference/tidb-binlog/maintain.md#binlogctl-工具)。 + +使用 `binlogctl` 查看集群中 Pump 和 Drainer 的当前状态： + +{{< copyable "shell-regular" >}} + +```bash +./bin/binlogctl -cmd drainers +``` + +``` +[2019/04/11 17:44:10.861 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: online, MaxCommitTS: 407638907719778305, UpdateTime: 2019-04-11 17:44:10 -0400 EDT}"] +``` + +{{< copyable "shell-regular" >}} + +```bash +./bin/binlogctl -cmd pumps +``` + +``` +[2019/04/11 17:44:13.904 -04:00] [INFO] [nodes.go:47] ["query node"] [type=pump] [node="{NodeID: localhost.localdomain:8250, Addr: 192.168.236.128:8250, State: online, MaxCommitTS: 407638914024079361, UpdateTime: 2019-04-11 17:44:13 -0400 EDT}"] +``` + +如果结束 Drainer 进程，集群会改进程设置“已暂停（即集群等待 Drainer 重新加入）”的状态。 + +{{< copyable "shell-regular" >}} + +```bash +pkill drainer && +./bin/binlogctl -cmd drainers +``` + +预期输出： + +``` +[2019/04/11 17:44:22.640 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: paused, MaxCommitTS: 407638915597467649, UpdateTime: 2019-04-11 17:44:18 -0400 EDT}"] +``` + +使用 binlogctl 的 "NodeIDs" 可控制单个对应节点。在该情况下，Drainer 的节点 ID 是 "localhost.localdomain:8249"，Pump 的节点 ID 是 "localhost.localdomain:8250"。 + +本文档中的 binlogctl 主要用于集群重启。如果在 TiDB 集群中终止并尝试重启所有的进程，由于 Pump 无法连接 Drainer 且认为 Drainer 依旧“在线”，Pump 会拒绝启动。这里的进程并不包括下游的 MySQL 或 MariaDB 或 Drainer。 + +以下有三个方案可解决上述问题： + +- 使用 binlogctl 停止 Drainer，而不是结束进程： + + ```bash + ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=drainers && + ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=pause-drainer --node-id=localhost.localdomain:8249 + ``` + +- 在启动 Pump **之前**先启动 Drainer。 + +- 在启动 PD 之后但在启动 Drainer 和 Pump 之前，使用 binlogctl 更新已暂定 Drainer 的状态。 + + ```bash + ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=update-drainer --node-id=localhost.localdomain:8249 --state=paused + ``` + +## 清理 + +在 shell 终端里可启动创建集群的所有进程（`pd-server` 、`tikv-server`、`pump`、`tidb-server`、`drainer`）。可通过在 shell 终端中执行 `pkill -P $$` 停止 TiDB 集群服务和 TiDB Binlog 进程。按一定的顺序停止这些进程有利于留出足够的时间彻底关闭每个组件。 + +{{< copyable "shell-regular" >}} + +```bash +for p in tidb-server drainer pump tikv-server pd-server; do pkill "$p"; sleep 1; done +``` + +预期输出： + +``` +[4]- Done ./bin/tidb-server --config=tidb.toml &>tidb.out +[5]+ Done ./bin/drainer --config=drainer.toml &>drainer.out +[3]+ Done ./bin/pump --config=pump.toml &>pump.out +[2]+ Done ./bin/tikv-server --config=tikv.toml &>tikv.out +[1]+ Done ./bin/pd-server --config=pd.toml &>pd.out +``` + +如果需要所有服务退出后重启集群，可以使用一开始启动服务的命令。如以上 [`binlogctl`](#binlogctl) 部分所述，需要先启动 Drainer 再启动 Pump，最后启动 `tidb-server`。 + +{{< copyable "shell-regular" >}} + +```bash +./bin/pd-server --config=pd.toml &>pd.out & +./bin/tikv-server --config=tikv.toml &>tikv.out & +./bin/drainer --config=drainer.toml &>drainer.out & +sleep 3 +./bin/pump --config=pump.toml &>pump.out & +sleep 3 +./bin/tidb-server --config=tidb.toml &>tidb.out & +``` + +如果有组件启动失败，请尝试单独重启该组件。 + +## 总结 + +本文档介绍了如何通过设置 TiDB Binlog，使用单个 Pump 和 Drainer 组成的集群同步 TiDB 集群数据到下游的 MariaDB。可以发现，TiDB Binlog 是用于获取处理 TiDB 集群中更新数据的综合性平台工具。 + +在更稳健的开发、测试或生产部署环境中，可以使用多个 TiDB 服务以实现高可用性和扩展性。使用多个 Pump 实例可以避免 Pump 集群中的问题影响发送到 TiDB 实例的应用流量。或者可以使用增加的 Drainer 实例同步数据到不同的下游或实现数据增量备份。 +binlog \ No newline at end of file diff --git a/how-to/get-started/tidb-lightning.md b/how-to/get-started/tidb-lightning.md new file mode 100644 index 000000000000..8836041f54a6 --- /dev/null +++ b/how-to/get-started/tidb-lightning.md @@ -0,0 +1,120 @@ +--- +title: TiDB Lightning 教程 +category: how-to +--- + +# TiDB Lightning 教程 + +TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： + +- **迅速**导入**大量新**数据。 +- 备份恢复所有数据。 + +TiDB Lightning 主要包含两个部分: + +- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键/值对 (KV 对) 发送到 `tikv-importer`、检查数据完整性等。 +- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，把 `tidb-lightning` 写入的 KV 对缓存、排序、切分并导入到 TiKV 集群。 + +![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) + +本教程假设使用的是若干新的、纯净版 CentOS 7 实例，你可以（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为 TiDB Lightning 对计算机资源消耗较高，建议分配 4 GB 以上的内存。 + +> **警告：** +> +> 本教程中的部署方法只适用于测试及功能体验，并不适用于生产或开发环境。 + +## 准备全量备份数据 + +我们使用 [`mydumper`](/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： + +{{< copyable "shell-regular" >}} + +```sh +./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ +``` + +其中： + +- `-B test`：从 `test` 数据库导出。 +- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 +- `-t 16`：使用 16 个线程导出数据。 +- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 +- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 + +这样全量备份数据就导出到了 `/data/my_database` 目录中。 + +## 部署 TiDB Lightning + +### 第 1 步：部署 TiDB 集群 + +在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群（版本要求 2.0.9 以上），本教程使用 TiDB 3.0.4 版本。部署方法可参考 [TiDB 快速入门指南](/overview.md#部署方式)。 + +### 第 2 步：下载 TiDB Lightning 安装包 + +通过以下链接获取 TiDB Lightning 安装包（选择与 TiDB 集群相同的版本）： + +- **v3.0.4**: [tidb-toolkit-v3.0.4-linux-amd64.tar.gz](https://download.pingcap.org/tidb-toolkit-v3.0.0-linux-amd64.tar.gz) + +### 第 3 步：启动 `tikv-importer` + +1. 将安装包里的 `bin/tikv-importer` 上传至部署 TiDB Lightning 的服务器。 + +2. 配置 `tikv-importer.toml`。 + + ```toml + # TiKV Importer 配置文件模版 + + # 日志文件。 + log-file = "tikv-importer.log" + # 日志等级：trace、debug、info、warn、error、off。 + log-level = "info" + + [server] + # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 + addr = "192.168.20.10:8287" + + [import] + # 存储引擎文档 (engine file) 的文件夹路径。 + import-dir = "/mnt/ssd/data.import/" + ``` + +3. 运行 `tikv-importer`。 + + {{< copyable "shell-regular" >}} + + ```sh + nohup ./tikv-importer -C tikv-importer.toml > nohup.out & + ``` + +### 第 4 步：启动 `tidb-lightning` + +1. 将安装包里的 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。 + +2. 将数据源也上传到同样的服务器。 + +3. 配置合适的参数运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： + + {{< copyable "shell-regular" >}} + + ```sh + #!/bin/bash + nohup ./tidb-lightning \ + --importer 172.16.31.10:8287 \ + -d /data/my_database/ \ + --tidb-server 172.16.31.2 \ + --tidb-user root \ + --log-file tidb-lightning.log \ + > nohup.out & + ``` + +### 第 5 步：检查数据 + +导入完毕后，TiDB Lightning 会自动退出。若导入成功，日志的最后一行会显示 `tidb lightning exit`。 + +如果出错，请参见 [TiDB Lightning 错误排解](/how-to/troubleshoot/tidb-lightning.md)。 + +## 总结 + +本教程对 TiDB Lightning 进行了简单的介绍，并快速部署了一套简单的 TiDB Lightning 集群，将全量备份数据导入到 TiDB 集群中。 + +关于 TiDB Lightning 的详细功能和使用，参见 [TiDB Lightning 简介](/reference/tools/tidb-lightning/overview.md)。 diff --git a/how-to/get-started/tispark.md b/how-to/get-started/tispark.md new file mode 100644 index 000000000000..64c9ee984d74 --- /dev/null +++ b/how-to/get-started/tispark.md @@ -0,0 +1,212 @@ +--- +title: TiSpark 快速入门指南 +category: how-to +--- + +# TiSpark 快速入门指南 + +为了让大家快速体验 [TiSpark](/reference/tispark.md)，通过 TiDB Ansible 安装的 TiDB 集群中默认已集成 Spark、TiSpark jar 包及 TiSpark sample data。 + +## 部署信息 + +- Spark 默认部署在 TiDB 实例部署目录下 spark 目录中 +- TiSpark jar 包默认部署在 Spark 部署目录 jars 文件夹下：`spark/jars/tispark-${name_with_version}.jar` +- TiSpark sample data 及导入脚本默认部署在 TiDB Ansible 目录下：`tidb-ansible/resources/bin/tispark-sample-data` + +## 环境准备 + +### 在 TiDB 实例上安装 JDK + +在 [Oracle JDK 官方下载页面](http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html) 下载 JDK 1.8 当前最新版，本示例中下载的版本为 `jdk-8u141-linux-x64.tar.gz`。 + +解压并根据您的 JDK 部署目录设置环境变量，编辑 `~/.bashrc` 文件，比如： + +{{< copyable "shell-regular" >}} + +```bash +export JAVA_HOME=/home/pingcap/jdk1.8.0_144 && +export PATH=$JAVA_HOME/bin:$PATH +``` + +验证 JDK 有效性： + +```bash +java -version +``` + +``` +java version "1.8.0_144" +Java(TM) SE Runtime Environment (build 1.8.0_144-b01) +Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode) +``` + +### 导入样例数据 + +假设 TiDB 集群已启动，其中一台 TiDB 实例服务 IP 为 192.168.0.2，端口为 4000，用户名为 root, 密码为空。 + +{{< copyable "shell-regular" >}} + +```bash +cd tidb-ansible/resources/bin/tispark-sample-data +``` + +修改 `sample_data.sh` 中 TiDB 登录信息，比如： + +{{< copyable "shell-regular" >}} + +```bash +mysql --local-infile=1 -h 192.168.0.2 -P 4000 -u root < dss.ddl +``` + +执行脚本 + +{{< copyable "shell-regular" >}} + +```bash +./sample_data.sh +``` + +> **注意：** +> +> 执行脚本的机器上需要安装 MySQL client，CentOS 用户可通过 `yum -y install mysql`来安装。 + +登录 TiDB 并验证数据包含 `TPCH_001` 库及以下表： + +{{< copyable "shell-regular" >}} + +```bash +mysql -uroot -P4000 -h192.168.0.2 +``` + +{{< copyable "sql" >}} + +```sql +show databases; +``` + +``` ++--------------------+ +| Database | ++--------------------+ +| INFORMATION_SCHEMA | +| PERFORMANCE_SCHEMA | +| TPCH_001 | +| mysql | +| test | ++--------------------+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +use TPCH_001; +``` + +``` +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Database changed +``` + +{{< copyable "sql" >}} + +```sql +show tables; +``` + +``` ++--------------------+ +| Tables_in_TPCH_001 | ++--------------------+ +| CUSTOMER | +| LINEITEM | +| NATION | +| ORDERS | +| PART | +| PARTSUPP | +| REGION | +| SUPPLIER | ++--------------------+ +8 rows in set (0.00 sec) +``` + +## 使用范例 + +进入 spark 部署目录启动 spark-shell: + +{{< copyable "shell-regular" >}} + +```bash +cd spark && +bin/spark-shell +``` + +然后像使用原生 Spark 一样查询 TiDB 表： + +```shell +scala> spark.sql("select count(*) from lineitem").show +``` + +结果为 + +``` ++--------+ +|count(1)| ++--------+ +| 60175| ++--------+ +``` + +下面执行另一个复杂一点的 Spark SQL: + +```shell +scala> spark.sql( + """select + | l_returnflag, + | l_linestatus, + | sum(l_quantity) as sum_qty, + | sum(l_extendedprice) as sum_base_price, + | sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, + | sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, + | avg(l_quantity) as avg_qty, + | avg(l_extendedprice) as avg_price, + | avg(l_discount) as avg_disc, + | count(*) as count_order + |from + | lineitem + |where + | l_shipdate <= date '1998-12-01' - interval '90' day + |group by + | l_returnflag, + | l_linestatus + |order by + | l_returnflag, + | l_linestatus + """.stripMargin).show +``` + +结果为： + +``` ++------------+------------+---------+--------------+--------------+ +|l_returnflag|l_linestatus| sum_qty|sum_base_price|sum_disc_price| ++------------+------------+---------+--------------+--------------+ +| A| F|380456.00| 532348211.65|505822441.4861| +| N| F| 8971.00| 12384801.37| 11798257.2080| +| N| O|742802.00| 1041502841.45|989737518.6346| +| R| F|381449.00| 534594445.35|507996454.4067| ++------------+------------+---------+--------------+--------------+ +(续) +-----------------+---------+------------+--------+-----------+ + sum_charge| avg_qty| avg_price|avg_disc|count_order| +-----------------+---------+------------+--------+-----------+ + 526165934.000839|25.575155|35785.709307|0.050081| 14876| + 12282485.056933|25.778736|35588.509684|0.047759| 348| +1029418531.523350|25.454988|35691.129209|0.049931| 29181| + 528524219.358903|25.597168|35874.006533|0.049828| 14902| +-----------------+---------+------------+--------+-----------+ +``` + +更多样例请参考 [`pingcap/tispark-test`](https://github.com/pingcap/tispark-test/tree/master/tpch/sparksql) diff --git a/dev/how-to/maintain/ansible-operations.md b/how-to/maintain/ansible-operations.md similarity index 100% rename from dev/how-to/maintain/ansible-operations.md rename to how-to/maintain/ansible-operations.md diff --git a/how-to/maintain/backup-and-restore/mydumper-lightning.md b/how-to/maintain/backup-and-restore/mydumper-lightning.md new file mode 100644 index 000000000000..936641513ec7 --- /dev/null +++ b/how-to/maintain/backup-and-restore/mydumper-lightning.md @@ -0,0 +1,95 @@ +--- +title: 使用 Mydumper/TiDB Lightning 进行备份与恢复 +category: how-to +aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/'] +--- + +# 使用 Mydumper/TiDB Lightning 进行备份与恢复 + +本文档将详细介绍如何使用 Mydumper/TiDB Lightning 对 TiDB 进行全量备份与恢复。增量备份与恢复可使用 [TiDB Binlog](/reference/tidb-binlog/overview.md)。 + +这里假定 TiDB 服务信息如下： + +|Name|Address|Port|User|Password| +|----|-------|----|----|--------| +|TiDB|127.0.0.1|4000|root|*| + +在这个备份恢复过程中，会用到下面的工具： + +- [Mydumper](/reference/tools/mydumper.md) 从 TiDB 导出数据 +- [TiDB Lightning](/reference/tools/tidb-lightning/overview.md) 导入数据到 TiDB + +## 使用 Mydumper/TiDB Lightning 全量备份恢复数据 + +`mydumper` 是一个强大的数据备份工具，具体可以参考 [`maxbube/mydumper`](https://github.com/maxbube/mydumper)。 + +可使用 [Mydumper](/reference/tools/mydumper.md) 从 TiDB 导出数据进行备份，然后用 [TiDB Lightning](/reference/tools/tidb-lightning/overview.md) 将其导入到 TiDB 里面进行恢复。 + +> **注意：** +> +> PingCAP 研发团队对 `mydumper` 进行了针对 TiDB 的适配性改造，建议使用 PingCAP 官方提供的 [Mydumper](/reference/tools/mydumper.md)。由于使用 `mysqldump` 进行数据备份和恢复都要耗费许多时间，这里也并不推荐。 + +### Mydumper/TiDB Lightning 全量备份恢复最佳实践 + +为了快速地备份恢复数据 (特别是数据量巨大的库)，可以参考以下建议： + +* 导出来的数据文件应当尽可能的小，可以通过设置参数 `-F` 来控制导出来的文件大小。如果后续使用 TiDB Lightning 对备份文件进行恢复，建议把 `mydumper` -F 参数的值设置为 `256`（单位 MB）；如果使用 `loader` 恢复，则建议设置为 `64`（单位 MB）。 + +## 从 TiDB 备份数据 + +我们使用 `mydumper` 从 TiDB 备份数据，如下: + +{{< copyable "shell-regular" >}} + +```bash +./bin/mydumper -h 127.0.0.1 -P 4000 -u root -t 32 -F 256 -B test -T t1,t2 --skip-tz-utc -o ./var/test +``` + +上面，我们使用 `-B test` 表明是对 `test` 这个 database 操作，然后用 `-T t1,t2` 表明只导出 `t1`，`t2` 两张表。 + +`-t 32` 表明使用 32 个线程去导出数据。`-F 256` 是将实际的表切分成一定大小的 chunk，这里的 chunk 大小为 256MB。 + +添加 `--skip-tz-utc` 参数后，会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 + +如果 `mydumper` 出现以下报错： + +``` +** (mydumper:27528): CRITICAL **: 13:25:09.081: Could not read data from testSchema.testTable: GC life time is shorter than transaction duration, transaction starts at 2019-08-05 21:10:01.451 +0800 CST, GC safe point is 2019-08-05 21:14:53.801 +0800 CST +``` + +就再执行两步命令： + +1. 执行 `mydumper` 命令前，查询 TiDB 集群的 [GC](/reference/garbage-collection/overview.md) 值并使用 MySQL 客户端将其调整为合适的值： + + {{< copyable "sql" >}} + + ```sql + SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + + ``` + +-----------------------+------------------------------------------------------------------------------------------------+ + | VARIABLE_NAME | VARIABLE_VALUE | + +-----------------------+------------------------------------------------------------------------------------------------+ + | tikv_gc_life_time | 10m0s | + +-----------------------+------------------------------------------------------------------------------------------------+ + 1 rows in set (0.02 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + +2. 执行 `mydumper` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值： + + {{< copyable "sql" >}} + + ```sql + update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + +## 向 TiDB 恢复数据 + +使用 TiDB Lightning 将之前导出的数据导入到 TiDB，完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/reference/tools/tidb-lightning/tidb-backend.md) diff --git a/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md b/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md new file mode 100644 index 000000000000..df80893d6aaf --- /dev/null +++ b/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md @@ -0,0 +1,52 @@ +--- +title: 定位消耗系统资源多的查询 +category: how-to +--- + +# 定位消耗系统资源多的查询 + +TiDB 会将执行时间超过 [tidb_expensive_query_time_threshold](/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_expensive_query_time_threshold)（默认值为 60s），或使用内存超过 [mem-quota-query](/reference/configuration/tidb-server/configuration-file.md#mem-quota-query)（默认值为 32 GB）的语句输出到 [tidb-server 日志文件](/reference/configuration/tidb-server/configuration-file.md#logfile)（默认文件为：“tidb.log”）中，用于在语句执行结束前定位消耗系统资源多的查询语句（以下简称为 expensive query），帮助用户分析和解决语句执行的性能问题。 + +注意，expensive query 日志和[慢查询日志](/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)的区别是，慢查询日志是在语句执行完后才打印，expensive query 日志可以将正在执行的语句的相关信息打印出来。当一条语句在执行过程中达到资源使用阈值时（执行时间/使用内存量），TiDB 会即时将这条语句的相关信息写入日志。 + +## Expensive query 日志示例 + +```sql +[2020/02/05 15:32:25.096 +08:00] [WARN] [expensivequery.go:167] [expensive_query] [cost_time=60.008338935s] [wait_time=0s] [request_count=1] [total_keys=70] [process_keys=65] [num_cop_tasks=1] [process_avg_time=0s] [process_p90_time=0s] [process_max_time=0s] [process_max_addr=10.0.1.9:20160] [wait_avg_time=0.002s] [wait_p90_time=0.002s] [wait_max_time=0.002s] [wait_max_addr=10.0.1.9:20160] [stats=t:pseudo] [conn_id=60026] [user=root] [database=test] [table_ids="[122]"] [txn_start_ts=414420273735139329] [mem_max="1035 Bytes (1.0107421875 KB)"] [sql="insert into t select sleep(1) from t"] +``` + +## 字段含义说明 + +基本字段： + +* `cost_time`：日志打印时语句已经花费的执行时间。 +* `stats`：语句涉及到的表或索引使用的统计信息版本。值为 pesudo 时表示无可用统计信息，需要对表或索引进行 analyze。 +* `table_ids`：语句涉及到的表的 ID。 +* `txn_start_ts`：事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 +* `sql`：SQL 语句。 + +和内存使用相关的字段： + +* `mem_max`：日志打印时语句已经使用的内存空间。该项使用两种单位标识内存使用量，分别为 Bytes 以及易于阅读的自适应单位（比如 MB、GB 等）。 + +和 SQL 执行的用户相关的字段： + +* `user`：执行语句的用户名。 +* `conn_id`：用户的连接 ID，可以用类似 `con:60026` 的关键字在 TiDB 日志中查找该连接相关的其他日志。 +* `database`：执行语句时使用的 database。 + +和 TiKV Coprocessor Task 相关的字段： + +* `wait_time`：该语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 +* `request_count`：该语句发送的 Coprocessor 请求的数量。 +* `total_keys`：Coprocessor 扫过的 key 的数量。 +* `processed_keys`：Coprocessor 处理的 key 的数量。与 total_keys 相比，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 +* `num_cop_tasks`：该语句发送的 Coprocessor 请求的数量。 +* `process_avg_time`：Coprocessor 执行 task 的平均执行时间。 +* `process_p90_time`：Coprocessor 执行 task 的 P90 分位执行时间。 +* `process_max_time`：Coprocessor 执行 task 的最长执行时间。 +* `process_max_addr`：task 执行时间最长的 Coprocessor 所在地址。 +* `wait_avg_time`：Coprocessor 上 task 的等待时间。 +* `wait_p90_time`：Coprocessor 上 task 的 P90 分位等待时间。 +* `wait_max_time`：Coprocessor 上 task 的最长等待时间。 +* `wait_max_addr`：task 等待时间最长的 Coprocessor 所在地址。 diff --git a/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md b/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md new file mode 100644 index 000000000000..7aba53fdfd7c --- /dev/null +++ b/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md @@ -0,0 +1,332 @@ +--- +title: 慢查询日志 +category: how-to +aliases: ['/docs-cn/sql/slow-query/','/docs-cn/dev/how-to/maintain/identify-slow-queries/'] +--- + +# 慢查询日志 + +TiDB 会将执行时间超过 [slow-threshold](/reference/configuration/tidb-server/configuration-file.md#slow-threshold)（默认值为 300 毫秒）的语句输出到 [slow-query-file](/reference/configuration/tidb-server/configuration-file.md#slow-query-file)（默认值："tidb-slow.log"）日志文件中，用于帮助用户定位慢查询语句，分析和解决 SQL 执行的性能问题。 + +## 日志示例 + +```sql +# Time: 2019-08-14T09:26:59.487776265+08:00 +# Txn_start_ts: 410450924122144769 +# User: root@127.0.0.1 +# Conn_ID: 3086 +# Query_time: 1.527627037 +# Parse_time: 0.000054933 +# Compile_time: 0.000129729 +# Process_time: 0.07 Request_count: 1 Total_keys: 131073 Process_keys: 131072 Prewrite_time: 0.335415029 Commit_time: 0.032175429 Get_commit_ts_time: 0.000177098 Local_latch_wait_time: 0.106869448 Write_keys: 131072 Write_size: 3538944 Prewrite_region: 1 +# DB: test +# Is_internal: false +# Digest: 50a2e32d2abbd6c1764b1b7f2058d428ef2712b029282b776beb9506a365c0f1 +# Stats: t:pseudo +# Num_cop_tasks: 1 +# Cop_proc_avg: 0.07 Cop_proc_p90: 0.07 Cop_proc_max: 0.07 Cop_proc_addr: 172.16.5.87:20171 +# Cop_wait_avg: 0 Cop_wait_p90: 0 Cop_wait_max: 0 Cop_wait_addr: 172.16.5.87:20171 +# Mem_max: 525211 +# Succ: true +# Plan: tidb_decode_plan('ZJAwCTMyXzcJMAkyMAlkYXRhOlRhYmxlU2Nhbl82CjEJMTBfNgkxAR0AdAEY1Dp0LCByYW5nZTpbLWluZiwraW5mXSwga2VlcCBvcmRlcjpmYWxzZSwgc3RhdHM6cHNldWRvCg==') +insert into t select * from t; +``` + +## 字段含义说明 + +> **注意：** +> +> 慢查询日志中所有时间相关字段的单位都是 **“秒”** + +Slow Query 基础信息： + +* `Time`：表示日志打印时间。 +* `Query_time`：表示执行这个语句花费的时间。 +* `Parse_time`：表示这个语句在语法解析阶段花费的时间。 +* `Compile_time`：表示这个语句在查询优化阶段花费的时间。 +* `Query`：表示 SQL 语句。慢日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 +* `Digest`：表示 SQL 语句的指纹。 +* `Txn_start_ts`：表示事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 +* `Is_internal`：表示是否为 TiDB 内部的 SQL 语句。`true` 表示 TiDB 系统内部执行的 SQL 语句，`false` 表示用户执行的 SQL 语句。 +* `Index_ids`：表示语句涉及到的索引的 ID。 +* `Succ`：表示语句是否执行成功。 +* `Backoff_time`：表示语句遇到需要重试的错误时在重试前等待的时间，常见的需要重试的错误有以下几种：遇到了 lock、Region 分裂、`tikv server is busy`。 +* `Plan`：表示语句的执行计划，用 `select tidb_decode_plan('xxx...')` SQL 语句可以解析出具体的执行计划。 + +和事务执行相关的字段： + +* `Prewrite_time`：表示事务两阶段提交中第一阶段（prewrite 阶段）的耗时。 +* `Commit_time`：表示事务两阶段提交中第二阶段（commit 阶段）的耗时。 +* `Get_commit_ts_time`：表示事务两阶段提交中第二阶段（commit 阶段）获取 commit 时间戳的耗时。 +* `Local_latch_wait_time`：表示事务两阶段提交中第二阶段（commit 阶段）发起前在 TiDB 侧等锁的耗时。 +* `Write_keys`：表示该事务向 TiKV 的 Write CF 写入 Key 的数量。 +* `Write_size`：表示事务提交时写 key 或 value 的总大小。 +* `Prewrite_region`：表示事务两阶段提交中第一阶段（prewrite 阶段）涉及的 TiKV Region 数量。每个 Region 会触发一次远程过程调用。 + +和内存使用相关的字段： + +* `Memory_max`：表示执行期间 TiDB 使用的最大内存空间，单位为 byte。 + +和 SQL 执行的用户相关的字段： + +* `User`：表示执行语句的用户名。 +* `Conn_ID`：表示用户的链接 ID，可以用类似 `con:3` 的关键字在 TiDB 日志中查找该链接相关的其他日志。 +* `DB`：表示执行语句时使用的 database。 + +和 TiKV Coprocessor Task 相关的字段： + +* `Request_count`：表示这个语句发送的 Coprocessor 请求的数量。 +* `Total_keys`：表示 Coprocessor 扫过的 key 的数量。 +* `Process_time`：执行 SQL 在 TiKV 的处理时间之和，因为数据会并行的发到 TiKV 执行，这个值可能会超过 `Query_time`。 +* `Wait_time`：表示这个语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 +* `Process_keys`：表示 Coprocessor 处理的 key 的数量。相比 total_keys，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 +* `Cop_proc_avg`：cop-task 的平均执行时间。 +* `Cop_proc_p90`：cop-task 的 P90 分位执行时间。 +* `Cop_proc_max`：cop-task 的最大执行时间。 +* `Cop_proc_addr`：执行时间最长的 cop-task 所在地址。 +* `Cop_wait_avg`：cop-task 的平均等待时间。 +* `Cop_wait_p90`：cop-task 的 P90 分位等待时间。 +* `Cop_wait_max`：cop-task 的最大等待时间。 +* `Cop_wait_addr`：等待时间最长的 cop-task 所在地址。 + +## 慢日志内存映射表 + +用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢日志中字段名一一对应，表结构可查看 [Information Schema](/reference/system-databases/information-schema.md#information-schema) 中关于 `SLOW_QUERY` 表的介绍。 + +> **注意：** +> +> 每次查询 `SLOW_QUERY` 表时，TiDB 都会去读取和解析一次当前的慢查询日志。 + +## 查询 `SLOW_QUERY` 示例 + +### 搜索 Top N 的慢查询 + +查询 Top 2 的用户慢查询。`is_internal=false` 表示排除 TiDB 内部的慢查询，只看用户的慢查询： + +{{< copyable "sql" >}} + +```sql +select query_time, query +from information_schema.slow_query +where is_internal = false -- 排除 TiDB 内部的慢查询 SQL +order by query_time desc +limit 2; +``` + +输出样例： + +``` ++--------------+------------------------------------------------------------------+ +| query_time | query | ++--------------+------------------------------------------------------------------+ +| 12.77583857 | select * from t_slim, t_wide where t_slim.c0=t_wide.c0; | +| 0.734982725 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c0; | ++--------------+------------------------------------------------------------------+ +``` + +### 搜索某个用户的 Top N 慢查询 + +下面例子中搜索 test 用户执行的慢查询 SQL，且按执行消耗时间逆序排序显式前 2 条： + +{{< copyable "sql" >}} + +```sql +select query_time, query, user +from information_schema.slow_query +where is_internal = false -- 排除 TiDB 内部的慢查询 SQL + and user = "test" -- 查找的用户名 +order by query_time desc +limit 2; +``` + +输出样例： + +``` ++-------------+------------------------------------------------------------------+----------------+ +| Query_time | query | user | ++-------------+------------------------------------------------------------------+----------------+ +| 0.676408014 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c1; | test | ++-------------+------------------------------------------------------------------+----------------+ +``` + +### 根据 SQL 指纹搜索同类慢查询 + +在得到 Top N 的慢查询 SQL 后，可通过 SQL 指纹继续搜索同类慢查询 SQL。 + +先获取 Top N 的慢查询和对应的 SQL 指纹： + +{{< copyable "sql" >}} + +```sql +select query_time, query, digest +from information_schema.slow_query +where is_internal = false +order by query_time desc +limit 1; +``` + +输出样例： + +``` ++-------------+-----------------------------+------------------------------------------------------------------+ +| query_time | query | digest | ++-------------+-----------------------------+------------------------------------------------------------------+ +| 0.302558006 | select * from t1 where a=1; | 4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa | ++-------------+-----------------------------+------------------------------------------------------------------+ +``` + +再根据 SQL 指纹搜索同类慢查询： + +{{< copyable "sql" >}} + +```sql +select query, query_time +from information_schema.slow_query +where digest = "4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa"; +``` + +输出样例： + +``` ++-----------------------------+-------------+ +| query | query_time | ++-----------------------------+-------------+ +| select * from t1 where a=1; | 0.302558006 | +| select * from t1 where a=2; | 0.401313532 | ++-----------------------------+-------------+ +``` + +### 搜索统计信息为 pseudo 的慢查询 SQL 语句 + +{{< copyable "sql" >}} + +```sql +select query, query_time, stats +from information_schema.slow_query +where is_internal = false + and stats like '%pseudo%'; +``` + +输出样例： + +``` ++-----------------------------+-------------+---------------------------------+ +| query | query_time | stats | ++-----------------------------+-------------+---------------------------------+ +| select * from t1 where a=1; | 0.302558006 | t1:pseudo | +| select * from t1 where a=2; | 0.401313532 | t1:pseudo | +| select * from t1 where a>2; | 0.602011247 | t1:pseudo | +| select * from t1 where a>3; | 0.50077719 | t1:pseudo | +| select * from t1 join t2; | 0.931260518 | t1:407872303825682445,t2:pseudo | ++-----------------------------+-------------+---------------------------------+ +``` + +## 解析其他的 TiDB 慢日志文件 + +TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHEMA.SLOW_QUERY` 时要读取和解析的文件，可通过修改改 session 变量的值来查询其他慢查询日志文件的内容： + +{{< copyable "sql" >}} + +```sql +set tidb_slow_query_file = "/path-to-log/tidb-slow.log" +``` + +## 用 `pt-query-digest` 工具分析 TiDB 慢日志 + +可以用 `pt-query-digest` 工具分析 TiDB 慢日志。 + +> **注意：** +> +> 建议使用 pt-query-digest 3.0.13 及以上版本。 + +示例如下： + +{{< copyable "shell" >}} + +```shell +pt-query-digest --report tidb-slow.log +``` + +输出样例： + +``` +# 320ms user time, 20ms system time, 27.00M rss, 221.32M vsz +# Current date: Mon Mar 18 13:18:51 2019 +# Hostname: localhost.localdomain +# Files: tidb-slow.log +# Overall: 1.02k total, 21 unique, 0 QPS, 0x concurrency _________________ +# Time range: 2019-03-18-12:22:16 to 2019-03-18-13:08:52 +# Attribute total min max avg 95% stddev median +# ============ ======= ======= ======= ======= ======= ======= ======= +# Exec time 218s 10ms 13s 213ms 30ms 1s 19ms +# Query size 175.37k 9 2.01k 175.89 158.58 122.36 158.58 +# Commit time 46ms 2ms 7ms 3ms 7ms 1ms 3ms +# Conn ID 71 1 16 8.88 15.25 4.06 9.83 +# Process keys 581.87k 2 103.15k 596.43 400.73 3.91k 400.73 +# Process time 31s 1ms 10s 32ms 19ms 334ms 16ms +# Request coun 1.97k 1 10 2.02 1.96 0.33 1.96 +# Total keys 636.43k 2 103.16k 652.35 793.42 3.97k 400.73 +# Txn start ts 374.38E 0 16.00E 375.48P 1.25P 89.05T 1.25P +# Wait time 943ms 1ms 19ms 1ms 2ms 1ms 972us +. +. +. +``` + +### 定位问题语句的方法 + +并不是所有 SLOW_QUERY 的语句都是有问题的。会造成集群整体压力增大的，是那些 process_time 很大的语句。wait_time 很大，但 process_time 很小的语句通常不是问题语句，是因为被问题语句阻塞，在执行队列等待造成的响应时间过长。 + +## `admin show slow` 命令 + +除了获取 TiDB 日志，还有一种定位慢查询的方式是通过 `admin show slow` SQL 命令： + +{{< copyable "sql" >}} + +```sql +admin show slow recent N; +``` + +{{< copyable "sql" >}} + +```sql +admin show slow top [internal | all] N; +``` + +`recent N` 会显示最近的 N 条慢查询记录，例如： + +{{< copyable "sql" >}} + +```sql +admin show slow recent 10; +``` + +`top N` 则显示最近一段时间（大约几天）内，最慢的查询记录。如果指定 `internal` 选项，则返回查询系统内部 SQL 的慢查询记录；如果指定 `all` 选项，返回系统内部和用户 SQL 汇总以后的慢查询记录；默认只返回用户 SQL 中的慢查询记录。 + +{{< copyable "sql" >}} + +```sql +admin show slow top 3; +admin show slow top internal 3; +admin show slow top all 5; +``` + +由于内存限制，保留的慢查询记录的条数是有限的。当命令查询的 `N` 大于记录条数时，返回的结果记录条数会小于 `N`。 + +输出内容详细说明，如下： + +| 列名 | 描述 | +|:------|:---- | +| start | SQL 语句执行开始时间 | +| duration | SQL 语句执行持续时间 | +| details | 执行语句的详细信息 | +| succ | SQL 语句执行是否成功，1: 成功，0: 失败 | +| conn_id | session 连接 ID | +| transcation_ts | 事务提交的 commit ts | +| user | 执行该语句的用户名 | +| db | 执行该 SQL 涉及到 database | +| table_ids | 执行该 SQL 涉及到表的 ID | +| index_ids | 执行该 SQL 涉及到索引 ID | +| internal | 表示为 TiDB 内部的 SQL 语句 | +| digest | 表示 SQL 语句的指纹 | +| sql | 执行的 SQL 语句 | diff --git a/how-to/migrate/from-mysql-aurora.md b/how-to/migrate/from-mysql-aurora.md new file mode 100644 index 000000000000..b0719cb2b4a6 --- /dev/null +++ b/how-to/migrate/from-mysql-aurora.md @@ -0,0 +1,208 @@ +--- +title: 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 +summary: 使用 DM 从 MySQL/Amazon Aurora MySQL 迁移数据。 +category: how-to +aliases: ['/docs-cn/dev/how-to/migrate/from-aurora/'] +--- + +# 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 + +本文以 [Amazon Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 为例介绍如何使用 DM 从 MySQL 协议数据库迁移数据到 TiDB。 + +## 第 1 步：在 Aurora 集群中启用 binlog + +假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 + +| 集群 | 终端节点 | 端口 | 角色 | +|:-------- |:--- | :--- | :--- | +| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | +| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | +| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | + +DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/reference/tools/data-migration/precheck.md#检查内容)。 + +> **注意：** +> +> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 + +如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 + +> **注意：** +> +> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 + +### 为 Aurora 集群修改 binlog 相关参数 + +在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 + +如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 + +> **注意：** +> +> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 + +## 第 2 步：部署 DM 集群 + +目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/how-to/deploy/data-migration-with-ansible.md)。 + +> **注意：** +> +> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 +> - 上下游数据库用户必须拥有相应的读写权限。 + +## 第 3 步：检查集群信息 + +使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： + +- DM 集群相关组件配置信息 + + | 组件 | 主机 | 端口 | + |:------|:---- |:---- | + | dm_worker1 | 172.16.10.72 | 8262 | + | dm_worker2 | 172.16.10.73 | 8262 | + | dm_master | 172.16.10.71 | 8261 | + +- 上下游数据库实例相关信息 + + | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | + |:-------- |:--- | :--- | :--- | :--- | + | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | + | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | + | 下游 TiDB | 172.16.10.83 | 4000 | root | | + +- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 + + ```toml + # Master 配置。 + + [[deploy]] + source-id = "mysql-replica-01" + dm-worker = "172.16.10.72:8262" + + [[deploy]] + source-id = "mysql-replica-02" + dm-worker = "172.16.10.73:8262" + ``` + +## 第 4 步：配置任务 + +假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 + +复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： + +```yaml +# 任务名，多个同时运行的任务不能重名。 +name: "test" +# 全量+增量 (all) 同步模式。 +task-mode: "all" +# 下游 TiDB 配置信息。 +target-database: + host: "172.16.10.83" + port: 4000 + user: "root" + password: "" + +# 当前数据同步任务需要的全部上游 MySQL 实例配置。 +mysql-instances: +- + # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 + source-id: "mysql-replica-01" + # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 + black-white-list: "global" + # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 + mydumper-config-name: "global" + +- + source-id: "mysql-replica-02" + black-white-list: "global" + mydumper-config-name: "global" + +# 黑白名单全局配置，各实例通过配置项名引用。 +black-white-list: + global: + do-tables: # 需要同步的上游表的白名单。 + - db-name: "test_db" # 需要同步的表的库名。 + tbl-name: "test_table" # 需要同步的表的名称。 + +# Mydumper 全局配置，各实例通过配置项名引用。 +mydumpers: + global: + extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 +``` + +## 第 5 步：启动任务 + +1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` + +2. 执行以下命令启动 dmctl + + {{< copyable "shell-regular" >}} + + ```bash + ./dmctl --master-addr 172.16.10.71:8261 + ``` + +3. 执行以下命令启动数据同步任务（`task.yaml` 是之前编辑的配置文件） + + {{< copyable "shell-regular" >}} + + ```bash + start-task ./task.yaml + ``` + + - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 + - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 + + ```json + { + "id": 4, + "name": "source db dump privilege chcker", + "desc": "check dump privileges of source DB", + "state": "fail", + "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", + "instruction": "", + "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" + }, + { + "id": 5, + "name": "source db replication privilege chcker", + "desc": "check replication privileges of source DB", + "state": "fail", + "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", + "instruction": "", + "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" + } + ``` + + 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： + + 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 + 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 + + ```yaml + ignore-checking-items: ["dump_privilege", "replication_privilege"] + ``` + +## 第 6 步：查询任务 + +如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： + +{{< copyable "shell-regular" >}} + +```bash +query-status +``` + +> **注意：** +> +> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： +> +> ``` +> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) +> ``` +> +> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： +> +> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 +> 2. 将原 `task.yaml` 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` +> 3. 使用 `start-task` 重新启动任务 diff --git a/dev/how-to/monitor/monitor-a-cluster.md b/how-to/monitor/monitor-a-cluster.md similarity index 100% rename from dev/how-to/monitor/monitor-a-cluster.md rename to how-to/monitor/monitor-a-cluster.md diff --git a/dev/how-to/monitor/overview.md b/how-to/monitor/overview.md similarity index 100% rename from dev/how-to/monitor/overview.md rename to how-to/monitor/overview.md diff --git a/how-to/scale/horizontally.md b/how-to/scale/horizontally.md new file mode 100644 index 000000000000..028715b888a2 --- /dev/null +++ b/how-to/scale/horizontally.md @@ -0,0 +1,132 @@ +--- +title: TiDB 集群扩容缩容方案 +category: how-to +--- + +# TiDB 集群扩容缩容方案 + +TiDB 集群可以在不影响线上服务的情况下动态进行扩容和缩容。 + +> **注意：** +> +> 如果使用 Ansible 部署 TiDB 集群，请参考[使用 Ansible 扩容缩容](/how-to/scale/with-ansible.md)。 + +下面分别介绍如何增加或者删除 PD，TiKV 以及 TiDB 的节点。 + +下面用到的 pd-ctl 文档可以参考 [pd-control](/reference/tools/pd-control.md)。 + +## PD + +假设现在我们有三个 PD 服务，详细信息如下： + +|Name|ClientUrls|PeerUrls| +|----|----------|--------| +|pd1|`http://host1:2379`|`http://host1:2380`| +|pd2|`http://host2:2379`|`http://host2:2380`| +|pd3|`http://host3:2379`|`http://host3:2380`| + +我们可以通过 pd-ctl 来查看当前所有 PD 节点的信息： + +{{< copyable "shell-regular" >}} + +```bash +./pd-ctl -u http://host1:2379 -i +>> member +``` + +### 动态添加节点 + +我们可以使用 `join` 参数，将一个新的 PD 服务加入到现有的 PD 集群里面。 +如果我们需要添加 `pd4`，只需要在 `--join` 参数里面填入当前 PD 集群任意一个 PD 服务的 client url，比如： + +{{< copyable "shell-regular" >}} + +```bash +./bin/pd-server --name=pd4 \ + --client-urls="http://host4:2379" \ + --peer-urls="http://host4:2380" \ + --join="http://host1:2379" +``` + +### 动态删除节点 + +如果我们需要删除 `pd4`，可以通过 pd-ctl 来完成： + +{{< copyable "shell-regular" >}} + +```bash +./pd-ctl -u http://host1:2379 +>> member delete name pd4 +``` + +### 动态迁移节点 + +如果想把现有的 PD 节点迁移到新的机器上，我们可以先在新的机器上添加节点，然后把旧的机器上的节点删除掉。迁移过程中应该一个节点一个节点逐个迁移，每完成一个步骤可以先查看一下当前的所有节点信息来进行确认。 + +## TiKV + +我们可以通过 pd-ctl 来查看当前所有 TiKV 节点的信息： + +{{< copyable "shell-regular" >}} + +```bash +./pd-ctl -u http://host1:2379 +>> store +``` + +### 动态添加节点 + +动态添加一个新的 TiKV 服务非常容易，只需要在新的机器上启动一个 TiKV 服务，不需要其他特殊操作。 +新启动的 TiKV 服务会自动注册到现有集群的 PD 中，PD 会自动做负载均衡，逐步地把一部分数据迁移到新的TiKV 服务中，从而降低现有 TiKV 服务的压力。 + +### 动态删除节点 + +安全地删除（下线）一个 TiKV 服务需要先告诉 PD，这样 PD 可以先把这个 TiKV 服务上面的数据迁移到其他 TiKV 服务上，保证数据有足够的副本数。 + +假设我们需要删除 store id 为 1 的 TiKV 服务，可以通过 pd-ctl 来完成： + +{{< copyable "shell-regular" >}} + +```bash +./pd-ctl -u http://host1:2379 +>> store delete 1 +``` + +然后可以查看这个 TiKV 服务的状态： + +{{< copyable "shell-regular" >}} + +```bash +./pd-ctl -u http://host1:2379 +>> store 1 +``` + +``` +{ + "store": { + "id": 1, + "address": "127.0.0.1:21060", + "state": 1, + "state_name": "Offline" + }, + "status": { + ... + } +} +``` + +我们可以通过这个 store 的 state_name 来确定这个 store 的状态： + +- Up：这个 store 正常服务 +- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 +- Down：超过一小时（可通过 `max-down-time` 配置）没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 +- Offline：这个 store 正在将其中的 Region 转移到其他节点，此时这个 store 仍在服务中 +- Tombstone：这个 store 已经完成下线，此时 store 上已经没有数据，可以关闭实例 + +### 动态迁移节点 + +迁移 TiKV 服务也是通过先在新的机器上添加节点，然后把旧的机器上的节点下线来完成。迁移过程中可以先把新集群的机器全部添加到已有的集群中，然后再把旧的节点一个一个地下线。可以通过查看正在下线的节点的状态信息来确定这个节点是否已经完成下线，确认完成以后再下线下一个节点。 + +## TiDB + +TiDB 是一个无状态的服务，这也就意味着我们能直接添加和删除 TiDB。需要注意的是，如果我们在 TiDB 的服务的前面搭建了一个 proxy（譬如 HAProxy），则需要更新 proxy 的配置并重新载入。 diff --git a/how-to/scale/with-ansible.md b/how-to/scale/with-ansible.md new file mode 100644 index 000000000000..dcdb68b7ea13 --- /dev/null +++ b/how-to/scale/with-ansible.md @@ -0,0 +1,527 @@ +--- +title: 使用 TiDB Ansible 扩容缩容 TiDB 集群 +category: how-to +--- + +# 使用 TiDB Ansible 扩容缩容 TiDB 集群 + +TiDB 集群可以在不影响线上服务的情况下进行扩容和缩容。 + +> **注意：** +> +> 以下缩容示例中，被移除的节点没有混合部署其他服务；如果混合部署了其他服务，不能按如下操作。 + +假设拓扑结构如下所示： + +| Name | Host IP | Services | +| ---- | ------- | -------- | +| node1 | 172.16.10.1 | PD1 | +| node2 | 172.16.10.2 | PD2 | +| node3 | 172.16.10.3 | PD3, Monitor | +| node4 | 172.16.10.4 | TiDB1 | +| node5 | 172.16.10.5 | TiDB2 | +| node6 | 172.16.10.6 | TiKV1 | +| node7 | 172.16.10.7 | TiKV2 | +| node8 | 172.16.10.8 | TiKV3 | +| node9 | 172.16.10.9 | TiKV4 | + +## 扩容 TiDB/TiKV 节点 + +例如，如果要添加两个 TiDB 节点（node101、node102），IP 地址为 172.16.10.101、172.16.10.102，可以进行如下操作： + +1. 编辑 `inventory.ini` 文件，添加节点信息： + + ```ini + [tidb_servers] + 172.16.10.4 + 172.16.10.5 + 172.16.10.101 + 172.16.10.102 + + [pd_servers] + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + + [tikv_servers] + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitored_servers] + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + 172.16.10.4 + 172.16.10.5 + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + 172.16.10.101 + 172.16.10.102 + + [monitoring_servers] + 172.16.10.3 + + [grafana_servers] + 172.16.10.3 + ``` + + 现在拓扑结构如下所示： + + | Name | Host IP | Services | + | ---- | ------- | -------- | + | node1 | 172.16.10.1 | PD1 | + | node2 | 172.16.10.2 | PD2 | + | node3 | 172.16.10.3 | PD3, Monitor | + | node4 | 172.16.10.4 | TiDB1 | + | node5 | 172.16.10.5 | TiDB2 | + | **node101** | **172.16.10.101**|**TiDB3** | + | **node102** | **172.16.10.102**|**TiDB4** | + | node6 | 172.16.10.6 | TiKV1 | + | node7 | 172.16.10.7 | TiKV2 | + | node8 | 172.16.10.8 | TiKV3 | + | node9 | 172.16.10.9 | TiKV4 | + +2. 初始化新增节点： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook bootstrap.yml -l 172.16.10.101,172.16.10.102 + ``` + + > **注意：** + > + > 如果 `inventory.ini` 中为节点配置了别名，如 `node101 ansible_host=172.16.10.101`，执行 ansible-playbook 时 -l 请指定别名，以下步骤类似。例如：`ansible-playbook bootstrap.yml -l node101,node102` + +3. 部署新增节点： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml -l 172.16.10.101,172.16.10.102 + ``` + +4. 启动新节点服务： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml -l 172.16.10.101,172.16.10.102 + ``` + +5. 更新 Prometheus 配置并重启： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 + + 可使用同样的步骤添加 TiKV 节点。但如果要添加 PD 节点，则需手动更新一些配置文件。 + +## 扩容 PD 节点 + +例如，如果要添加一个 PD 节点（node103），IP 地址为 172.16.10.103，可以进行如下操作： + +1. 编辑 `inventory.ini` 文件，添加节点信息置于 `[pd_servers]` 主机组最后一行： + + ```ini + [tidb_servers] + 172.16.10.4 + 172.16.10.5 + + [pd_servers] + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + 172.16.10.103 + + [tikv_servers] + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitored_servers] + 172.16.10.4 + 172.16.10.5 + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + 172.16.10.103 + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitoring_servers] + 172.16.10.3 + + [grafana_servers] + 172.16.10.3 + ``` + + 现在拓扑结构如下所示： + + | Name | Host IP | Services | + | ---- | ------- | -------- | + | node1 | 172.16.10.1 | PD1 | + | node2 | 172.16.10.2 | PD2 | + | node3 | 172.16.10.3 | PD3, Monitor | + | **node103** | **172.16.10.103** | **PD4** | + | node4 | 172.16.10.4 | TiDB1 | + | node5 | 172.16.10.5 | TiDB2 | + | node6 | 172.16.10.6 | TiKV1 | + | node7 | 172.16.10.7 | TiKV2 | + | node8 | 172.16.10.8 | TiKV3 | + | node9 | 172.16.10.9 | TiKV4 | + +2. 初始化新增节点： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook bootstrap.yml -l 172.16.10.103 + ``` + +3. 部署新增节点： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml -l 172.16.10.103 + ``` + +4. 登录新增的 PD 节点，编辑启动脚本：`{deploy_dir}/scripts/run_pd.sh` + + 1. 移除 `--initial-cluster="xxxx" \` 配置，注意这里不能在行开头加注释符 #。 + + 2. 添加 `--join="http://172.16.10.1:2379" \`，IP 地址 （172.16.10.1） 可以是集群内现有 PD IP 地址中的任意一个。 + + 3. 在新增 PD 节点中手动启动 PD 服务： + + {{< copyable "shell-regular" >}} + + ```bash + {deploy_dir}/scripts/start_pd.sh + ``` + + > **注意：** + > + > 启动前，需要通过 [PD Control](/reference/tools/pd-control.md) 工具确认当前 PD 节点的 `health` 状态均为 "true"，否则 PD 服务会启动失败，同时日志中报错 `["join meet error"] [error="etcdserver: unhealthy cluster"]`。 + + 4. 使用 `pd-ctl` 检查新节点是否添加成功： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member + ``` + +5. 滚动升级整个集群： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml + ``` + +6. 启动监控服务： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml -l 172.16.10.103 + ``` + +7. 更新 Prometheus 配置并重启： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +8. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 + +## 缩容 TiDB 节点 + +例如，如果要移除一个 TiDB 节点（node5），IP 地址为 172.16.10.5，可以进行如下操作： + +1. 停止 node5 节点上的服务： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml -l 172.16.10.5 + ``` + +2. 编辑 `inventory.ini` 文件，移除节点信息： + + ```ini + [tidb_servers] + 172.16.10.4 + #172.16.10.5 # 注释被移除节点 + + [pd_servers] + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + + [tikv_servers] + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitored_servers] + 172.16.10.4 + #172.16.10.5 # 注释被移除节点 + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitoring_servers] + 172.16.10.3 + + [grafana_servers] + 172.16.10.3 + ``` + + 现在拓扑结构如下所示： + + | Name | Host IP | Services | + | ---- | ------- | -------- | + | node1 | 172.16.10.1 | PD1 | + | node2 | 172.16.10.2 | PD2 | + | node3 | 172.16.10.3 | PD3, Monitor | + | node4 | 172.16.10.4 | TiDB1 | + | **node5** | **172.16.10.5** | **TiDB2 已删除** | + | node6 | 172.16.10.6 | TiKV1 | + | node7 | 172.16.10.7 | TiKV2 | + | node8 | 172.16.10.8 | TiKV3 | + | node9 | 172.16.10.9 | TiKV4 | + +3. 更新 Prometheus 配置并重启： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +4. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 + +## 缩容 TiKV 节点 + +例如，如果要移除一个 TiKV 节点（node9），IP 地址为 172.16.10.9，可以进行如下操作： + +1. 使用 `pd-ctl` 从集群中移除节点： + + 1. 查看 node9 节点的 store id： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store + ``` + + 2. 从集群中移除 node9，假如 store id 为 10： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store delete 10 + ``` + +2. 使用 Grafana 或者 `pd-ctl` 检查节点是否下线成功（下线需要一定时间，下线节点的状态变为 Tombstone 就说明下线成功了）： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store 10 + ``` + +3. 下线成功后，停止 node9 上的服务： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml -l 172.16.10.9 + ``` + +4. 编辑 `inventory.ini` 文件，移除节点信息： + + ```ini + [tidb_servers] + 172.16.10.4 + 172.16.10.5 + + [pd_servers] + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + + [tikv_servers] + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + #172.16.10.9 # 注释被移除节点 + + [monitored_servers] + 172.16.10.4 + 172.16.10.5 + 172.16.10.1 + 172.16.10.2 + 172.16.10.3 + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + #172.16.10.9 # 注释被移除节点 + + [monitoring_servers] + 172.16.10.3 + + [grafana_servers] + 172.16.10.3 + ``` + + 现在拓扑结构如下所示： + + | Name | Host IP | Services | + | ---- | ------- | -------- | + | node1 | 172.16.10.1 | PD1 | + | node2 | 172.16.10.2 | PD2 | + | node3 | 172.16.10.3 | PD3, Monitor | + | node4 | 172.16.10.4 | TiDB1 | + | node5 | 172.16.10.5 | TiDB2 | + | node6 | 172.16.10.6 | TiKV1 | + | node7 | 172.16.10.7 | TiKV2 | + | node8 | 172.16.10.8 | TiKV3 | + | **node9** | **172.16.10.9** | **TiKV4 已删除** | + +5. 更新 Prometheus 配置并重启： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 + +## 缩容 PD 节点 + +例如，如果要移除一个 PD 节点（node2），IP 地址为 172.16.10.2，可以进行如下操作： + +1. 使用 `pd-ctl` 从集群中移除节点： + + 1. 查看 node2 节点的 name： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member + ``` + + 2. 从集群中移除 node2，假如 name 为 pd2： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member delete name pd2 + ``` + +2. 使用 `pd-ctl` 检查节点是否下线成功（PD 下线会很快，结果中没有 node2 节点信息即为下线成功）： + + {{< copyable "shell-regular" >}} + + ```bash + /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member + ``` + +3. 下线成功后，停止 node2 上的服务： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml -l 172.16.10.2 + ``` + +4. 编辑 `inventory.ini` 文件，移除节点信息： + + ```ini + [tidb_servers] + 172.16.10.4 + 172.16.10.5 + + [pd_servers] + 172.16.10.1 + #172.16.10.2 # 注释被移除节点 + 172.16.10.3 + + [tikv_servers] + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitored_servers] + 172.16.10.4 + 172.16.10.5 + 172.16.10.1 + #172.16.10.2 # 注释被移除节点 + 172.16.10.3 + 172.16.10.6 + 172.16.10.7 + 172.16.10.8 + 172.16.10.9 + + [monitoring_servers] + 172.16.10.3 + + [grafana_servers] + 172.16.10.3 + ``` + + 现在拓扑结构如下所示： + + | Name | Host IP | Services | + | ---- | ------- | -------- | + | node1 | 172.16.10.1 | PD1 | + | **node2** | **172.16.10.2** | **PD2 已删除** | + | node3 | 172.16.10.3 | PD3, Monitor | + | node4 | 172.16.10.4 | TiDB1 | + | node5 | 172.16.10.5 | TiDB2 | + | node6 | 172.16.10.6 | TiKV1 | + | node7 | 172.16.10.7 | TiKV2 | + | node8 | 172.16.10.8 | TiKV3 | + | node9 | 172.16.10.9 | TiKV4 | + +5. 滚动升级整个集群： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml + ``` + +6. 更新 Prometheus 配置并重启： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +7. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 diff --git a/how-to/secure/enable-tls-between-components.md b/how-to/secure/enable-tls-between-components.md new file mode 100644 index 000000000000..3ef9688e8f3c --- /dev/null +++ b/how-to/secure/enable-tls-between-components.md @@ -0,0 +1,131 @@ +--- +title: 为 TiDB 组件间开启 TLS 和数据加密存储 +category: how-to +--- + +# 为 TiDB 组件间开启 TLS 和数据加密存储 + +本文档介绍 TiDB 集群如何开启 TLS 验证和数据加密存储。 + +## 开启 TLS 验证 + +本部分介绍 TiDB 集群如何开启 TLS 验证，TLS 验证支持： + +- TiDB 组件之间的双向验证，包括 TiDB、TiKV、PD 相互之间，TiKV Control 与 TiKV、PD Control 与 PD 的双向认证，以及 TiKV peer 之间、PD peer 之间。一旦开启，所有组件之间均使用验证，不支持只开启某一部分的验证。 +- MySQL Client 与 TiDB 之间的客户端对服务器身份的单向验证以及双向验证。 + +MySQL Client 与 TiDB 之间使用一套证书，TiDB 集群组件之间使用另外一套证书。 + +### TiDB 集群组件间开启 TLS（双向认证） + +1. 准备证书。 + + 推荐为 TiDB、TiKV、PD 分别准备一个 server 证书，并保证可以相互验证，而它们的各种客户端共用 client 证书。 + + 有多种工具可以生成自签名证书，如 `openssl`，`easy-rsa`，`cfssl`。 + + 这里提供一个使用 `cfssl` 生成证书的示例：[生成自签名证书](/how-to/secure/generate-self-signed-certificates.md)。 + +2. 配置证书。 + + - TiDB + + 在 `config` 文件或命令行参数中设置： + + ```toml + [security] + # Path of file that contains list of trusted SSL CAs for connection with cluster components. + cluster-ssl-ca = "/path/to/ca.pem" + # Path of file that contains X509 certificate in PEM format for connection with cluster components. + cluster-ssl-cert = "/path/to/tidb-server.pem" + # Path of file that contains X509 key in PEM format for connection with cluster components. + cluster-ssl-key = "/path/to/tidb-server-key.pem" + ``` + + - TiKV + + 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： + + ```toml + [security] + # set the path for certificates. Empty string means disabling secure connectoins. + ca-path = "/path/to/ca.pem" + cert-path = "/path/to/tikv-server.pem" + key-path = "/path/to/tikv-server-key.pem" + ``` + + - PD + + 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： + + ```toml + [security] + # Path of file that contains list of trusted SSL CAs. if set, following four settings shouldn't be empty + cacert-path = "/path/to/ca.pem" + # Path of file that contains X509 certificate in PEM format. + cert-path = "/path/to/pd-server.pem" + # Path of file that contains X509 key in PEM format. + key-path = "/path/to/pd-server-key.pem" + ``` + + 此时 TiDB 集群各个组件间已开启双向验证。 + + > **注意：** + > + > 若 TiDB 集群各个组件间已开启 TLS，在使用 tikv-ctl 或 pd-ctl 工具连接集群时，需要指定 client 证书，示例： + + {{< copyable "shell-regular" >}} + + ```bash + ./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem + ``` + + {{< copyable "shell-regular" >}} + + ```bash + ./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/clinet-key.pem" + ``` + +### MySQL 与 TiDB 间开启 TLS + +请参考 [使用加密连接](/how-to/secure/enable-tls-clients.md)。 + +## 开启数据加密存储 + +在 TiDB 集群中，用户的数据都存储在 TiKV 中，配置了 TiKV 数据加密存储功能，就代表 TiDB 集群已经加密存储了用户的数据。本部分主要介绍如何配置 TiKV 的加密存储功能。 + +### 操作流程 + +1. 生成 token 文件。 + + token 文件存储的是密钥，用于对用户数据进行加密，以及对已加密的数据进行解密。 + + {{< copyable "shell-regular" >}} + + ```bash + ./tikv-ctl random-hex --len 256 > cipher-file-256 + ``` + + > **注意：** + > + > TiKV 只接受 hex 格式的 token 文件，文件的长度必须是 2^n，并且小于等于 1024。 + +2. 配置 TiKV。 + + ```toml + [security] + # Cipher file 的存储路径 + cipher-file = "/path/to/cipher-file-256" + ``` + +> **注意：** +> +> 若使用 [Lightning](/reference/tools/tidb-lightning/overview.md) 向集群导入数据，如果目标集群开启了加密功能，Lightning 生成的 sst 文件也必须是加密的格式。 + +### 使用限制 + +目前 TiKV 数据加密存储存在以下限制： + +- 对之前没有开启加密存储的集群，不支持开启该功能。 +- 已经开启加密功能的集群，不允许关闭加密存储功能。 +- 同一集群内部，不允许部分 TiKV 实例开启该功能，部分 TiKV 实例不开启该功能。对于加密存储功能，所有 TiKV 实例要么都开启该功能，要么都不开启该功能。这是由于 TiKV 实例之间会有数据迁移，如果开启了加密存储功能，迁移过程中数据也是加密的。 diff --git a/how-to/secure/enable-tls-clients.md b/how-to/secure/enable-tls-clients.md new file mode 100644 index 000000000000..bbe0aaa81db9 --- /dev/null +++ b/how-to/secure/enable-tls-clients.md @@ -0,0 +1,158 @@ +--- +title: 使用加密连接 +category: how-to +--- + +# 使用加密连接 + +TiDB 服务端默认采用非加密连接，因而具备监视信道流量能力的第三方可以知悉 TiDB 服务端与客户端之间发送和接受的数据，包括但不限于查询语句内容、查询结果等。若信道是不可信的，例如客户端是通过公网连接到 TiDB 服务端的，则非加密连接容易造成信息泄露，建议使用加密连接确保安全性。 + +TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接，协议与 MySQL 加密连接一致，现有 MySQL 客户端如 MySQL 运维工具和 MySQL 驱动等能直接支持。TLS 的前身是 SSL，因而 TLS 有时也被称为 SSL，但由于 SSL 协议有已知安全漏洞，TiDB 实际上并未支持。TiDB 支持的 TLS/SSL 协议版本为 TLS 1.0、TLS 1.1、TLS 1.2。 + +使用加密连接后，连接将具有以下安全性质： + +- 保密性：流量明文无法被窃听； +- 完整性：流量明文无法被篡改； +- 身份验证（可选）：客户端和服务端能验证双方身份，避免中间人攻击。 + +TiDB 的加密连接支持默认是关闭的，必须在 TiDB 服务端通过配置开启加密连接的支持后，才能在客户端中使用加密连接。另外，与 MySQL 一致，TiDB 加密连接是以单个连接为单位的，并且是可选的，因而对于开启了加密连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。大部分 MySQL 客户端默认不采用加密连接，因此一般还要显式地要求客户端使用加密连接。 + +简单来说，要使用加密连接必须同时满足以下两个条件： + +1. TiDB 服务端配置开启加密连接的支持 +2. 客户端指定使用加密连接 + +## 配置 TiDB 启用加密连接支持 + +在启动 TiDB 时，至少需要在配置文件中同时指定 `ssl-cert` 和 `ssl-key` 参数，才能使 TiDB 服务端接受加密连接。还可以指定 `ssl-ca` 参数进行客户端身份验证（请参见[配置启用身份验证](#配置启用身份验证)章节）。 + +- [`ssl-cert`](/reference/configuration/tidb-server/configuration-file.md#ssl-cert)：指定 SSL 证书文件路径 +- [`ssl-key`](/reference/configuration/tidb-server/configuration-file.md#ssl-key)：指定证书文件对应的私钥 +- [`ssl-ca`](/reference/configuration/tidb-server/configuration-file.md#ssl-ca)：可选，指定受信任的 CA 证书文件路径 + +参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端加密连接到 TiDB 服务端。 + +上述证书及密钥可以使用 OpenSSL 签发和生成，也可以使用 MySQL 自带的工具 `mysql_ssl_rsa_setup` 快捷生成： + +{{< copyable "shell-regular" >}} + +```bash +mysql_ssl_rsa_setup --datadir=./certs +``` + +以上命令将在 `certs` 目录下生成以下文件： + +``` +certs +├── ca-key.pem +├── ca.pem +├── client-cert.pem +├── client-key.pem +├── private_key.pem +├── public_key.pem +├── server-cert.pem +└── server-key.pem +``` + +对应的 TiDB 配置文件参数为： + +```toml +[security] +ssl-cert = "certs/server-cert.pem" +ssl-key = "certs/server-key.pem" +``` + +若证书参数无误，则 TiDB 在启动时将会输出 `Secure connection is enabled`，否则 TiDB 会输出 `Secure connection is NOT ENABLED`。 + +## 配置 MySQL 客户端使用加密连接 + +MySQL 5.7 及以上版本自带的客户端默认尝试使用安全连接，若服务端不支持安全连接则自动退回到使用非安全连接；MySQL 5.7 以下版本自带的客户端默认采用非安全连接。 + +可以通过命令行参数修改客户端的连接行为，包括： + +- 强制使用安全连接，若服务端不支持安全连接则连接失败 (`--ssl-mode=REQUIRED`) +- 尝试使用安全连接，若服务端不支持安全连接则退回使用不安全连接 +- 使用不安全连接 (`--ssl-mode=DISABLED`) + +详细信息请参阅 MySQL 文档中关于[客户端配置安全连接](https://dev.mysql.com/doc/refman/5.7/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration)的部分。 + +## 配置启用身份验证 + +若在 TiDB 服务端或 MySQL 客户端中未指定 `ssl-ca` 参数，则默认不会进行客户端或服务端身份验证，无法抵御中间人攻击，例如客户端可能会“安全地”连接到了一个伪装的服务端。可以在服务端和客户端中配置 `ssl-ca` 参数进行身份验证。一般情况下只需验证服务端身份，但也可以验证客户端身份进一步增强安全性。 + +- 若要使 MySQL 客户端验证 TiDB 服务端身份，TiDB 服务端需至少配置 `ssl-cert` 和 `ssl-key` 参数，客户端需至少指定 `--ssl-ca` 参数，且 `--ssl-mode` 至少为 `VERIFY_CA`。必须确保 TiDB 服务端配置的证书（`ssl-cert`）是由客户端 `--ssl-ca` 参数所指定的 CA 所签发的，否则身份验证失败。 +- 若要使 TiDB 服务端验证 MySQL 客户端身份，TiDB 服务端需配置 `ssl-cert`、`ssl-key`、`ssl-ca` 参数，客户端需至少指定 `--ssl-cert`、`--ssl-key` 参数。必须确保服务端配置的证书和客户端配置的证书都是由服务端配置指定的 `ssl-ca` 签发的。 +- 若要进行双向身份验证，请同时满足上述要求。 + +> **注意：** +> +> 目前 TiDB 尚不支持强制验证客户端身份，即服务端对客户端的身份验证是可选的。若客户端在 TLS 握手时未出示自己的身份证书，也能正常建立 TLS 连接。 + +## 检查当前连接是否是加密连接 + +可以通过 `SHOW STATUS LIKE "%Ssl%";` 了解当前连接的详细情况，包括是否使用了安全连接、安全连接采用的加密协议、TLS 版本号等。 + +以下是一个安全连接中执行该语句的结果。由于客户端支持的 TLS 版本号和加密协议会有所不同，执行结果相应地也会有所变化。 + +{{< copyable "sql" >}} + +```sql +SHOW STATUS LIKE "%Ssl%"; +``` + +``` +...... +| Ssl_verify_mode | 5 | +| Ssl_version | TLSv1.2 | +| Ssl_cipher | ECDHE-RSA-AES128-GCM-SHA256 | +...... +``` + +除此以外，对于 MySQL 自带客户端，还可以使用 `STATUS` 或 `\s` 语句查看连接情况： + +{{< copyable "sql" >}} + +```sql +\s +``` + +``` +... +SSL: Cipher in use is ECDHE-RSA-AES128-GCM-SHA256 +... +``` + +## 支持的 TLS 版本及密钥交换协议和加密算法 + +TiDB 支持的 TLS 版本及密钥交换协议和加密算法由 Golang 官方库决定。 + +### 支持的 TLS 版本 + +- TLS 1.0 +- TLS 1.1 +- TLS 1.2 + +### 支持的密钥交换协议及加密算法 + +- TLS\_RSA\_WITH\_RC4\_128\_SHA +- TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA +- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA +- TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA +- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 +- TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 +- TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 +- TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA +- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA +- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA +- TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA +- TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA +- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA +- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA +- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256 +- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 +- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 +- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 +- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 +- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 +- TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 +- TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 diff --git a/dev/how-to/secure/generate-self-signed-certificates.md b/how-to/secure/generate-self-signed-certificates.md similarity index 100% rename from dev/how-to/secure/generate-self-signed-certificates.md rename to how-to/secure/generate-self-signed-certificates.md diff --git a/how-to/troubleshoot/cluster-setup.md b/how-to/troubleshoot/cluster-setup.md new file mode 100644 index 000000000000..168eadedcdbd --- /dev/null +++ b/how-to/troubleshoot/cluster-setup.md @@ -0,0 +1,149 @@ +--- +title: TiDB 集群故障诊断 +category: how-to +--- + +# TiDB 集群故障诊断 + +当试用 TiDB 遇到问题时，请先参考本篇文档。如果问题未解决，请按文档要求收集必要的信息通过 Github [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 + +## 如何给 TiDB 开发者报告错误 + +当使用 TiDB 遇到问题并且通过后面所列信息无法解决时，请收集以下信息并[创建新 Issue](https://github.com/pingcap/tidb/issues/new/choose): + ++ 具体的出错信息以及正在执行的操作 ++ 当前所有组件的状态 ++ 出问题组件 log 中的 error/fatal/panic 信息 ++ 机器配置以及部署拓扑 ++ dmesg 中 TiDB 组件相关的问题 + +## 数据库连接不上 + +首先请确认集群的各项服务是否已经启动，包括 tidb-server、pd-server、tikv-server。请用 ps 命令查看所有进程是否在。如果某个组件的进程已经不在了，请参考对应的章节排查错误。 + +如果所有的进程都在，请查看 tidb-server 的日志，看是否有报错？常见的错误包括： + ++ InformationSchema is out of date + + 无法连接 tikv-server，请检查 pd-server 以及 tikv-server 的状态和日志。 + ++ panic + + 程序有错误，请将具体的 panic log [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 + + 如果是清空数据并重新部署服务，请确认以下信息： + ++ pd-server、tikv-server 数据都已清空 + + tikv-server 存储具体的数据，pd-server 存储 tikv-server 中数据的的元信息。如果只清空 pd-server 或只清空 tikv-server 的数据，会导致两边数据不匹配。 + ++ 清空 pd-server 和 tikv-server 的数据并重启后，也需要重启 tidb-server + + 集群 ID 是由 pd-server 在集群初始化时随机分配，所以重新部署集群后，集群 ID 会发生变化。tidb-server 业务需要重启以获取新的集群 ID。 + +## tidb-server 启动报错 + +tidb-server 无法启动的常见情况包括： + ++ 启动参数错误 + + 请参考 [TiDB 命令行参数](/reference/configuration/tidb-server/configuration.md)。 + ++ 端口被占用：`lsof -i:port` + + 请确保 tidb-server 启动所需要的端口未被占用。 + ++ 无法连接 pd-server + + 首先检查 pd-server 的进程状态和日志，确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 + + 若 pd-server 正常，则需要检查 tidb-server 机器和 pd-server 对应端口之间的连通性， + 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。 + + 例如，假设 tidb 服务位于 `192.168.1.100`，无法连接的 pd 位于 `192.168.1.101`，且 2379 为其 client port， + 则可以在 tidb 机器上执行 `nc -v -z 192.168.1.101 2379`，测试是否可以访问端口。 + 或使用 `curl -v 192.168.1.101:2379/pd/api/v1/leader` 直接检查 pd 是否正常服务。 + +## tikv-server 启动报错 + ++ 启动参数错误 + + 请参考 [TiKV 启动参数](/reference/configuration/tikv-server/configuration.md)文档。 + ++ 端口被占用：`lsof -i:port` + + 请确保 tikv-server 启动所需要的端口未被占用：`lsof -i:port`。 ++ 无法连接 pd-server + + 首先检查 pd-server 的进程状态和日志。确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 + + 若 pd-server 正常，则需要检查 tikv-server 机器和 pd-server 对应端口之间的连通性， + 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。具体命令参考上一节。 + ++ 文件被占用 + + 不要在一个数据库文件目录上打开两个 tikv。 + +## pd-server 启动报错 + ++ 启动参数错误 + + 请参考 [PD 命令行参数](/reference/configuration/pd-server/configuration.md)文档。 + ++ 端口被占用：`lsof -i:port` + + 请确保 pd-server 启动所需要的端口未被占用：`lsof -i:port`。 + +## TiDB/TiKV/PD 进程异常退出 + ++ 进程是否是启动在前台 + + 当前终端退出给其所有子进程发送 HUP 信号，从而导致进程退出。 + ++ 是否是在命令行用过 `nohup+&` 方式直接运行 + + 这样依然可能导致进程因终端连接突然中断，作为终端 SHELL 的子进程被杀掉。 + + 推荐将启动命令写在脚本中，通过脚本运行（相当于二次 fork 启动）。 + +## TiKV 进程异常重启 + ++ 检查 dmesg 或者 syslog 里面是否有 OOM 信息 + + 如果有 OOM 信息并且杀掉的进程为 TiKV，请减少 TiKV 的 RocksDB 的各个 CF 的 `block-cache-size` 值。 + ++ 检查 TiKV 日志是否有 panic 的 log + + 提交 Issue 并附上 panic 的 log。 + +## TiDB panic + +请提供 panic 的 log。 + +## 连接被拒绝 + ++ 请确保操作系统的网络参数正确，包括但不限于 + - 连接字符串中的端口和 tidb-server 启动的端口需要一致 + - 请保证防火墙的配置正确 + +## Too many open files + +在启动进程之前，请确保 `ulimit -n` 的结果足够大，推荐设为 unlimited 或者是大于 1000000。 + +## 数据库访问超时，系统负载高 + +首先检查 [SLOW-QUERY](/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息： + ++ 部署的拓扑结构 + - tidb-server/pd-server/tikv-server 部署了几个实例 + - 这些实例在机器上是如何分布的 ++ 机器的硬件配置 + - CPU 核数 + - 内存大小 + - 硬盘类型（SSD 还是机械硬盘） + - 是实体机还是虚拟机 ++ 机器上除了 TiDB 集群之外是否还有其他服务 ++ pd-server 和 tikv-server 是否分开部署 ++ 目前正在进行什么操作 ++ 用 `top -H` 命令查看当前占用 CPU 的线程名 ++ 最近一段时间的网络/IO 监控数据是否有异常 diff --git a/how-to/troubleshoot/tidb-lightning.md b/how-to/troubleshoot/tidb-lightning.md new file mode 100644 index 000000000000..27830093d3e0 --- /dev/null +++ b/how-to/troubleshoot/tidb-lightning.md @@ -0,0 +1,134 @@ +--- +title: TiDB Lightning 故障诊断 +category: reference +--- + +# TiDB Lightning 故障诊断 + +当 Lightning 遇到不可恢复的错误时便会异常退出，并在日志中记下错误原因。一般可在日志底部找到，也可以搜索 `[error]` 字符串找出中间发生的错误。本文主要描述一些常见的错误及其解决方法。 + +## 导入速度太慢 + +TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件，如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 `restore chunk … takes` 的记录，或者观察 Grafana 的监控信息。 + +导入速度太慢一般有几个原因： + +**原因 1**：`region-concurrency` 设定太高，线程间争用资源反而减低了效率。 + +1. 从日志的开头搜寻 `region-concurrency` 能知道 Lightning 读到的参数是多少。 +2. 如果 Lightning 与其他服务（如 Importer）共用一台服务器，必需**手动**将 `region-concurrency` 设为该服务器 CPU 数量的 75%。 +3. 如果 CPU 设有限额（例如从 Kubernetes 指定的上限），Lightning 可能无法自动判断出来，此时亦需要**手动**调整 `region-concurrency`。 + +**原因 2**：表结构太复杂。 + +每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 + +**原因 3**：Lightning 版本太旧。 + +试试最新的版本吧！可能会有改善。 + +## checksum failed: checksum mismatched remote vs local + +**原因**：本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因： + +1. 这张表可能本身已有数据，影响最终结果。 +2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。 +3. 如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如： + + * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。 + * 唯一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。 +4. 如果 TiDB Lightning 之前失败停机过，但没有正确重启，可能会因为数据不同步而出现校验和不一致。 + +**解决办法**： + +1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。 + + {{< copyable "shell-regular" >}} + + ```sh + tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all + ``` + +2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。 + +3. 参考[如何正确重启 TiDB Lightning](/faq/tidb-lightning.md#如何正确重启-tidb-lightning)中的解决办法。 + +## Checkpoint for … has invalid status:（错误码） + +**原因**：[断点续传](/reference/tools/tidb-lightning/checkpoints.md)已启用。Lightning 或 Importer 之前发生了异常退出。为了防止数据意外损坏，Lightning 在错误解决以前不会启动。 + +错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。 + +**解决办法**： + +如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。 + +{{< copyable "shell-regular" >}} + +```sh +tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all +``` + +其他解决方法请参考[断点续传的控制](/reference/tools/tidb-lightning/checkpoints.md#断点续传的控制)。 + +## ResourceTemporarilyUnavailable("Too many open engines …: …") + +**原因**：并行打开的引擎文件 (engine files) 超出 `tikv-importer` 里的限制。这可能由配置错误引起。即使配置没问题，如果 `tidb-lightning` 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。 + +**解决办法**： + +1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为： + + 最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number` + +2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。 + +3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录： + + {{< copyable "shell-regular" >}} + + ```sh + tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all + ``` + +## cannot guess encoding for input file, please convert to UTF-8 manually + +**原因**：Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如，因为在不同的环境运行过 `ALTER TABLE`，使表架构同时出现 UTF-8 和 GB-18030 的字符。 + +**解决办法**： + +1. 编辑数据源，保存为纯 UTF-8 或 GB-18030 的文件。 +2. 手动在目标数量库创建所有的表，然后设置 `[mydumper] no-schema = true` 跳过创建表的步骤。 +3. 设置 `[mydumper] character-set = "binary"` 跳过这个检查。但是这样可能使数据库出现乱码。 + +## [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 …}' + +**原因**: 一个 `timestamp` 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。 + +**解决办法**: + +1. 确保 Lightning 与数据源时区一致。 + + * 使用 Ansible 部署的话，修正 [`inventory.ini`] 下的 `timezone` 变量。 + + ```ini + # inventory.ini + [all:vars] + timezone = Asia/Shanghai + ``` + + * 手动部署的话，通过设定 `$TZ` 环境变量强制时区设定。 + + 强制使用 Asia/Shanghai 时区： + + {{< copyable "shell-regular" >}} + + ```sh + TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml + ``` + +2. 导出数据时，必须加上 `--skip-tz-utc` 选项。 + +3. 确保整个集群使用的是同一最新版本的 `tzdata` (2018i 或更高版本)。 + + 如果你使用的是 CentOS 机器，你可以运行 `yum info tzdata` 命令查看 `tzdata` 的版本及是否有更新。然后运行 `yum upgrade tzdata` 命令升级 `tzdata`。 diff --git a/how-to/upgrade/from-previous-version.md b/how-to/upgrade/from-previous-version.md new file mode 100644 index 000000000000..68a84719b3db --- /dev/null +++ b/how-to/upgrade/from-previous-version.md @@ -0,0 +1,220 @@ +--- +title: TiDB 最新开发版升级操作指南 +category: how-to +aliases: ['/docs-cn/dev/how-to/upgrade/to-tidb-3.0/','/docs-cn/dev/how-to/upgrade/rolling-updates-with-ansible/'] +--- + +# TiDB 最新开发版升级操作指南 + +本文档适用于从 TiDB 2.0、2.1、3.0、3.1 版本升级至 TiDB 最新开发版 (latest) 以及从开发版的较低版本升级至最新版本。目前，TiDB 最新开发版兼容 [TiDB Binlog Cluster 版本](/reference/tidb-binlog/overview.md)。 + +> **警告：** +> +> TiDB 最新开发版为非稳定版本，不建议用于生产环境。 + +## 升级兼容性说明 + +- 不支持在升级后回退至 2.1.x 或更旧版本 +- 从 2.0.6 之前的版本升级到 latest 之前，需要确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 `Add Index` 操作，等 DDL 操作完成后再执行升级操作 +- 2.1 及之后版本启用了并行 DDL，早于 2.0.1 版本的集群，无法滚动升级到 latest 版本，可以选择下面两种方案： + - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 latest 版本 + - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 latest 版本 + +> **注意：** +> +> 在升级的过程中不要执行 DDL 请求，否则可能会出现行为未定义的问题。 + +## 在中控机器上安装 Ansible 及其依赖 + +> **注意：** +> +> 如果已经安装了 Ansible 及其依赖，可跳过该步骤。 + +TiDB Ansible 最新开发版依赖 2.4.2 及以上但不高于 2.7.11 的 Ansible 版本（`2.4.2 ≦ ansible ≦ 2.7.11`，建议 2.7.11 版本），另依赖 Python 模块：`jinja2 ≧ 2.9.6` 和 `jmespath ≧ 0.9.0`。为方便管理依赖，建议使用 `pip` 安装 Ansible 及其依赖，可参照[在中控机器上安装 Ansible 及其依赖](/how-to/deploy/orchestrated/ansible.md#在中控机器上安装-ansible-及其依赖) 进行安装。离线环境参照[在中控机器上离线安装 Ansible 及其依赖](/how-to/deploy/orchestrated/offline-ansible.md#在中控机器上离线安装-ansible-及其依赖)。 + +安装完成后，可通过以下命令查看版本： + +{{< copyable "shell-regular" >}} + +```bash +ansible --version +``` + +``` +ansible 2.7.11 +``` + +{{< copyable "shell-regular" >}} + +```bash +pip show jinja2 +``` + +``` +Name: Jinja2 +Version: 2.10 +``` + +{{< copyable "shell-regular" >}} + +```bash +pip show jmespath +``` + +``` +Name: jmespath +Version: 0.9.0 +``` + +> **注意：** +> +> 请务必按以上文档安装 Ansible 及其依赖。确认 Jinja2 版本是否正确，否则启动 Grafana 时会报错。确认 jmespath 版本是否正确，否则滚动升级 TiKV 时会报错。 + +## 在中控机器上下载 TiDB Ansible + +以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录，备份 TiDB 2.0、2.1、3.0 或其他低版本的 tidb-ansible 文件夹： + +{{< copyable "shell-regular" >}} + +```bash +mv tidb-ansible tidb-ansible-bak +``` + +下载 TiDB latest 版本对应的 tidb-ansible [**下载 TiDB Ansible**](/how-to/deploy/orchestrated/ansible.md#在中控机器上下载-tidb-ansible)，默认的文件夹名称为 `tidb-ansible`。 + +{{< copyable "shell-regular" >}} + +```bash +git clone https://github.com/pingcap/tidb-ansible.git +``` + +## 编辑 inventory.ini 文件和配置文件 + +以 `tidb` 用户登录中控机并进入 `/home/tidb/tidb-ansible` 目录。 + +### 编辑 `inventory.ini` 文件 + +编辑 `inventory.ini` 文件，IP 信息参照备份文件 `/home/tidb/tidb-ansible-bak/inventory.ini`。 + +以下变量配置，需要重点确认，变量含义可参考 [inventory.ini 变量调整](/how-to/deploy/orchestrated/ansible.md#调整其它变量可选)。 + +1. 请确认 `ansible_user` 配置的是普通用户。为统一权限管理，不再支持使用 root 用户远程安装。默认配置中使用 `tidb` 用户作为 SSH 远程用户及程序运行用户。 + + ``` + ## Connection + # ssh via normal user + ansible_user = tidb + ``` + + 可参考[如何配置 SSH 互信及 sudo 规则](/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)自动配置主机间互信。 + +2. `process_supervision` 变量请与之前版本保持一致，默认推荐使用 `systemd`。 + + ``` + # process supervision, [systemd, supervise] + process_supervision = systemd + ``` + + 如需变更，可参考[如何调整进程监管方式从 supervise 到 systemd](/how-to/deploy/orchestrated/ansible.md#如何调整进程监管方式从-supervise-到-systemd)，先使用备份 `/home/tidb/tidb-ansible-bak/` 分支变更进程监管方式再升级。 + +### 编辑 TiDB 集群组件配置文件 + +如之前自定义过 TiDB 集群组件配置文件，请参照备份文件修改 `/home/tidb/tidb-ansible/conf` 下对应配置文件。 + +**注意以下参数变更：** + +- TiKV 配置中 `end-point-concurrency` 变更为 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： + + ``` + readpool: + coprocessor: + # Notice: if CPU_NUM > 8, default thread pool size for coprocessors + # will be set to CPU_NUM * 0.8. + # high-concurrency: 8 + # normal-concurrency: 8 + # low-concurrency: 8 + ``` + + > **注意：** + > + > 2.0 版本升级且单机多 TiKV 实例（进程）情况下，需要修改这三个参数。 + > + > 推荐设置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 + +- TiKV 配置中不同 CF 中的 `block-cache-size` 参数变更为 `block-cache`： + + ``` + storage: + block-cache: + capacity: "1GB" + ``` + + > **注意：** + > + > 单机多 TiKV 实例（进程）情况下，需要修改 `capacity` 参数。 + > + > 推荐设置：`capacity` = (MEM_TOTAL * 0.5 / TiKV 实例数量) + +- TiKV 配置中单机多实例场景需要额外配置 `tikv_status_port` 端口： + + ``` + [tikv_servers] + TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" + TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" + TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" + TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" + TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" + TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" + ``` + + > **注意：** + > + > 最新开发版单机多 TiKV 实例（进程）情况下，需要添加 `tikv_status_port` 参数。 + > + > 配置前，注意检查端口是否有冲突。 + +## 下载 TiDB latest binary 到中控机 + +确认 `tidb-ansible/inventory.ini` 文件中 `tidb_version = latest`，然后执行以下命令下载 TiDB latest binary 到中控机。 + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook local_prepare.yml +``` + +## 滚动升级 TiDB 集群组件 + +- 如果 `process_supervision` 变量使用默认的 `systemd` 参数： + + - 当前集群版本 < 3.0，则通过 `excessive_rolling_update.yml` 滚动升级 TiDB 集群。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook excessive_rolling_update.yml + ``` + + - 当前集群版本 ≥ 3.0.0，滚动升级及日常滚动重启 TiDB 集群，使用 `rolling_update.yml`。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml + ``` + +- 如果 `process_supervision` 变量使用的是 `supervise` 参数，无论当前集群为哪个版本，均通过 `rolling_update.yml` 来滚动升级 TiDB 集群。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml + ``` + +## 滚动升级 TiDB 监控组件 + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook rolling_update_monitor.yml +``` diff --git a/dev/key-features.md b/key-features.md similarity index 100% rename from dev/key-features.md rename to key-features.md diff --git a/overview.md b/overview.md new file mode 100644 index 000000000000..cd60e6d66875 --- /dev/null +++ b/overview.md @@ -0,0 +1,66 @@ +--- +title: TiDB 简介 +category: introduction +--- + +# TiDB 简介 + +TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 + +TiDB 具备如下特性： + +- 高度兼容 MySQL + + [大多数情况下](/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 + +- 水平弹性扩展 + + 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 + +- 分布式事务 + + TiDB 100% 支持标准的 ACID 事务。 + +- 真正金融级高可用 + + 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 + +- 一站式 HTAP 解决方案 + + TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 + +- 云原生 SQL 数据库 + + TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，配合 [TiDB Operator 项目](/tidb-in-kubernetes/tidb-operator-overview.md) 可实现自动化运维，使部署、配置和维护变得十分简单。 + +TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/reference/tispark.md)来完成。 + +TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 + +三篇文章了解 TiDB 技术内幕： + +- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) +- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) +- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) + +## 部署方式 + +TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： + +- [使用 Ansible 部署](/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，推荐使用 Ansible 部署 TiDB 集群。 +- [使用 Ansible 离线部署](/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 +- [使用 TiDB Operator 部署](/tidb-in-kubernetes/deploy/tidb-operator.md)：使用 TiDB Operator 在 Kubernetes 集群上部署生产就绪的 TiDB 集群，支持[部署到 AWS EKS](/tidb-in-kubernetes/deploy/aws-eks.md)、[部署到谷歌云 GKE (beta)](/tidb-in-kubernetes/deploy/gcp-gke.md)、[部署到阿里云 ACK](/tidb-in-kubernetes/deploy/alibaba-cloud.md) 等。 +- [使用 Docker Compose 部署](/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 +- [使用 Docker 部署](/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 +- [使用 TiDB Operator 部署到 Minikube](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：你可以使用 TiDB Opeartor 将 TiDB 集群部署到本地 Minikube 启动的 Kubernetes 集群中。该部署方式不适用于生产环境。 +- [使用 TiDB Operator 部署到 kind](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：你可以使用 TiDB Operator 将 TiDB 集群部署到以 kind 方式启动的 Kubernetes 本地集群中。该部署方式不适用于生产环境。 + +## 项目源码 + +TiDB 集群所有组件的源码均可从 GitHub 上直接访问： + +- [TiDB](https://github.com/pingcap/tidb) +- [TiKV](https://github.com/tikv/tikv) +- [PD](https://github.com/pingcap/pd) +- [TiSpark](https://github.com/pingcap/tispark) +- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/reference/alert-rules.md b/reference/alert-rules.md new file mode 100644 index 000000000000..f0bc8fa505fe --- /dev/null +++ b/reference/alert-rules.md @@ -0,0 +1,1161 @@ +--- +title: TiDB 集群报警规则 +summary: TiDB 集群中各组件的报警规则详解。 +category: reference +--- + +# TiDB 集群报警规则 + +本文介绍了 TiDB 集群中各组件的报警规则，包括 TiDB、TiKV、PD、TiDB Binlog、Node_exporter 和 Blackbox_exporter 的各报警项的规则描述及处理方法。 + +## TiDB 报警规则 + +本节介绍了 TiDB 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 + +### 紧急级别报警项 + +紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 + +#### `TiDB_schema_error` + +* 报警规则： + + `increase(tidb_session_schema_lease_error_total{type="outdated"}[15m]) > 0` + +* 规则描述： + + TiDB 在一个 Lease 时间内没有重载到最新的 Schema 信息。如果 TiDB 无法继续对外提供服务，则报警。 + +* 处理方法： + + 该问题通常由于 TiKV Region 不可用或超时导致，需要看 TiKV 的监控指标定位问题。 + +#### `TiDB_tikvclient_region_err_total` + +* 报警规则： + + `increase(tidb_tikvclient_region_err_total[10m]) > 6000` + +* 规则描述： + + TiDB 访问 TiKV 时发生了 Region 错误。如果在 10 分钟之内该错误多于 6000 次，则报警。 + +* 处理方法： + + 查看 TiKV 的监控状态。 + +#### `TiDB_domain_load_schema_total` + +* 报警规则： + + `increase(tidb_domain_load_schema_total{type="failed"}[10m]) > 10` + +* 规则描述： + + TiDB 重载最新的 Schema 信息失败的总次数。如果在 10 分钟之内重载失败次数超过 10 次，则报警。 + +* 处理方法： + + 参考 [`TiDB_schema_error`](#tidb_schema_error) 的处理方法。 + +#### `TiDB_monitor_keep_alive` + +* 报警规则： + + `increase(tidb_monitor_keep_alive_total[10m]) < 100` + +* 规则描述： + + 表示 TiDB 的进程是否仍然存在。如果在 10 分钟之内 `tidb_monitor_keep_alive_total` 增加次数少于 100，则 TiDB 的进程可能已经退出，此时会报警。 + +* 处理方法： + + * 检查 TiDB 进程是否 OOM。 + * 检查机器是否发生了重启。 + +### 重要级别报警项 + +对于重要级别的报警，需要密切关注异常指标。 + +#### `TiDB_server_panic_total` + +* 报警规则： + + `increase(tidb_server_panic_total[10m]) > 0` + +* 规则描述： + + 发生崩溃的 TiDB 线程的数量。当出现崩溃的时候会报警。该线程通常会被恢复，否则 TiDB 会频繁重启。 + +* 处理方法： + + 收集 panic 日志，定位原因。 + +### 警告级别报警项 + +警告级别的报警是对某一问题或错误的提醒。 + +#### `TiDB_memory_abnormal` + +* 报警规则： + + `go_memstats_heap_inuse_bytes{job="tidb"} > 1e+10` + +* 规则描述： + + 对 TiDB 内存使用量的监控。如果内存使用大于 10 G，则报警。 + +* 处理方法： + + 通过 HTTP API 来排查 goroutine 泄露的问题。 + +#### `TiDB_query_duration` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tidb_server_handle_query_duration_seconds_bucket[1m])) BY (le, instance)) > 1` + +* 规则描述： + + TiDB 处理请求的延时。如果 .99 的延迟大于 1 秒，则报警。 + +* 处理方法： + + 查看 TiDB 的日志，搜索 SLOW_QUERY 和 TIME_COP_PROCESS 关键字，查找慢 SQL。 + +#### `TiDB_server_event_error` + +* 报警规则： + + `increase(tidb_server_event_total{type=~"server_start|server_hang"}[15m]) > 0` + +* 规则描述： + + TiDB 服务中发生的事件数量。当出现以下事件的时候会报警： + + 1. start：TiDB 服务启动。 + 2. hang：当发生了 Critical 级别的事件时（目前只有 Binlog 写不进去一种情况），TiDB 进入 `hang` 模式，并等待人工 Kill。 + +* 处理方法： + + * 重启 TiDB 以恢复服务。 + * 检查 TiDB Binlog 服务是否正常。 + +#### `TiDB_tikvclient_backoff_total` + +* 报警规则： + + `increase(tidb_tikvclient_backoff_total[10m]) > 10` + +* 规则描述： + + TiDB 访问 TiKV 发生错误时发起重试的次数。如果在 10 分钟之内重试次数多于 10 次，则报警。 + +* 处理方法： + + 查看 TiKV 的监控状态。 + +#### `TiDB_monitor_time_jump_back_error` + +* 报警规则： + + `increase(tidb_monitor_time_jump_back_total[10m]) > 0` + +* 规则描述： + + 如果 TiDB 所在机器的时间发生了回退，则报警。 + +* 处理方法： + + 排查 NTP 配置。 + +#### `TiDB_ddl_waiting_jobs` + +* 报警规则： + + `sum(tidb_ddl_waiting_jobs) > 5` + +* 规则描述： + + 如果 TiDB 中等待执行的 DDL 任务的数量大于 5，则报警。 + +* 处理方法： + + 通过 `admin show ddl` 语句检查是否有耗时的 add index 操作正在执行。 + +## PD 报警规则 + +本节介绍了 PD 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 + +### 紧急级别报警项 + +紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 + +#### `PD_cluster_offline_tikv_nums` + +* 报警规则： + + `sum(pd_cluster_status{type="store_down_count"}) > 0` + +* 规则描述： + + PD 长时间（默认配置是 30 分钟）没有收到 TiKV 心跳。 + +* 处理方法： + + * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 + * 如果确定 TiKV 无法恢复，可做下线处理。 + +### 重要级别报警项 + +对于重要级别的报警，需要密切关注异常指标。 + +#### `PD_etcd_write_disk_latency` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[1m])) by (instance,job,le)) > 1` + +* 规则描述： + + etcd 写盘慢，这很容易引起 PD leader 超时或者 TSO 无法及时存盘等问题，从而导致整个集群停止服务。 + +* 处理方法： + + * 排查写入慢的原因。可能是由于其他服务导致系统负载过高。可以检查 PD 本身是否占用了大量 CPU 或 IO 资源。 + * 可尝试重启 PD 或手动 transfer leader 至其他的 PD 来恢复服务。 + * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 + +#### `PD_miss_peer_region_count` + +* 报警规则： + + `sum(pd_regions_status{type="miss_peer_region_count"}) > 100` + +* 规则描述： + + Region 的副本数小于 `max-replicas` 配置的值。这通常是由于 TiKV 宕机等问题导致一段时间内一些 Region 缺副本，下线 TiKV 节点也会导致少量 Region 缺副本（对于有 pending peer 的 Region 会走先减后加的流程）。 + +* 处理方法： + + * 查看是否有 TiKV 宕机或在做下线操作，尝试定位问题产生的原因。 + * 观察 region health 面板，查看 `miss_peer_region_count` 是否在不断减少。 + +### 警告级别报警项 + +警告级别的报警是对某一问题或错误的提醒。 + +#### `PD_cluster_lost_connect_tikv_nums` + +* 报警规则： + + `sum(pd_cluster_status{type="store_disconnected_count"}) > 0` + +* 规则描述： + + PD 在 20 秒之内未收到 TiKV 上报心跳。正常情况下是每 10 秒收到 1 次心跳。 + +* 处理方法： + + * 排查是否在重启 TiKV。 + * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 + * 如果确定 TiKV 无法恢复，可做下线处理。 + * 如果确定 TiKV 可以恢复，但在短时间内还无法恢复，可以考虑延长 `max-down-time` 配置，防止超时后 TiKV 被判定为无法恢复并开始搬移数据。 + +#### `PD_cluster_low_space` + +* 报警规则： + + `sum(pd_cluster_status{type="store_low_space_count"}) > 0` + +* 规则描述： + + 表示 TiKV 节点空间不足。 + +* 处理方法： + + * 检查集群中的空间是否普遍不足。如果是，则需要扩容。 + * 检查 Region balance 调度是否有问题。如果有问题，会导致数据分布不均衡。 + * 检查是否有文件占用了大量磁盘空间，比如日志、快照、core dump 等文件。 + * 降低该节点的 Region weight 来减少数据量。 + * 无法释放空间时，可以考虑主动下线该节点，防止由于磁盘空间不足而宕机。 + +#### `PD_etcd_network_peer_latency` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(etcd_network_peer_round_trip_time_seconds_bucket[1m])) by (To,instance,job,le)) > 1` + +* 规则描述： + + PD 节点之间网络延迟高，严重情况下会导致 leader 超时和 TSO 存盘超时，从而影响集群服务。 + +* 处理方法： + + * 检查网络状况和系统负载情况。 + * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 + +#### `PD_tidb_handle_requests_duration` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(pd_client_request_handle_requests_duration_seconds_bucket{type="tso"}[1m])) by (instance,job,le)) > 0.1` + +* 规则描述： + + PD 处理 TSO 请求耗时过长，一般是由于负载过高。 + +* 处理方法： + + * 检查服务器负载状况。 + * 使用 pprof 抓取 PD 的 CPU profile 进行分析。 + * 手动切换 PD leader。 + * 如果是环境问题，则将有问题的 PD 下线替换。 + +#### `PD_down_peer_region_nums` + +* 报警规则： + + `sum(pd_regions_status{type="down_peer_region_count"}) > 0` + +* 规则描述： + + Raft leader 上报有不响应 peer 的 Region 数量。 + +* 处理方法： + + * 检查是否有 TiKV 宕机，或刚发生重启，或者繁忙。 + * 观察 region health 面板，检查 `down_peer_region_count` 是否在不断减少。 + * 检查是否有 TiKV 之间网络不通。 + +#### `PD_pending_peer_region_count` + +* 报警规则： + + `sum(pd_regions_status{type="pending_peer_region_count"}) > 100` + +* 规则描述： + + Raft log 落后的 Region 过多。由于调度产生少量的 pending peer 是正常的，但是如果持续很高，就可能有问题。 + +* 处理方法： + + * 观察 region health 面板，检查 `pending_peer_region_count` 是否在不断减少。 + * 检查 TiKV 之间的网络状况，特别是带宽是否足够。 + +#### `PD_leader_change` + +* 报警规则： + + `count(changes(pd_server_tso{type="save"}[10m]) > 0) >= 2` + +* 规则描述： + + 近期发生了 PD leader 切换。 + +* 处理方法： + + * 排除人为因素，比如重启 PD、手动 transfer leader 或调整 leader 优先级等。 + * 检查网络状况和系统负载情况。 + * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 + +#### `TiKV_space_used_more_than_80%` + +* 报警规则： + + `sum(pd_cluster_status{type="storage_size"}) / sum(pd_cluster_status{type="storage_capacity"}) * 100 > 80` + +* 规则描述： + + 集群空间占用超过 80%。 + +* 处理方法： + + * 确认是否需要扩容。 + * 排查是否有文件占用了大量磁盘空间，比如日志、快照或 core dump等文件。 + +#### `PD_system_time_slow` + +* 报警规则： + + `changes(pd_server_tso{type="system_time_slow"}[10m]) >= 1` + +* 规则描述： + + 系统时间可能发生回退。 + +* 处理方法： + + 检查系统时间设置是否正确。 + +#### `PD_no_store_for_making_replica` + +* 报警规则： + + `increase(pd_checker_event_count{type="replica_checker", name="no_target_store"}[1m]) > 0` + +* 规则描述： + + 没有合适的 store 用来补副本。 + +* 处理方法： + + * 检查 store 是否空间不足。 + * 根据 label 配置（如果有这个配置的话）来检查是否有可以补副本的 store。 + +## TiKV 报警规则 + +本节介绍了 TiKV 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 + +### 紧急级别报警项 + +紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 + +#### `TiKV_memory_used_too_fast` + +* 报警规则： + + `process_resident_memory_bytes{job=~"tikv",instance=~".*"} - (process_resident_memory_bytes{job=~"tikv",instance=~".*"} offset 5m) > 5*1024*1024*1024` + +* 规则描述： + + 目前没有和内存相关的 TiKV 的监控，你可以通过 Node_exporter 监控集群内机器的内存使用情况。如上规则表示，如果在 5 分钟之内内存使用超过 5GB（TiKV 内存占用的太快），则报警。 + +* 处理方法： + + 调整 `rockdb.defaultcf` 和 `rocksdb.writecf` 的 `block-cache-size` 的大小。 + +#### `TiKV_GC_can_not_work` + +* 报警规则： + + `sum(increase(tidb_tikvclient_gc_action_result{type="success"}[6h])) < 1` + + > **注意：** + > + > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 + +* 规则描述： + + 在 6 小时内 Region 上没有成功执行 GC，说明 GC 不能正常工作了。短期内 GC 不运行不会造成太大的影响，但如果 GC 一直不运行，版本会越来越多，从而导致查询变慢。 + +* 处理方法： + + 1. 执行 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME="tikv_gc_leader_desc"` 来找到 gc leader 对应的 `tidb-server`； + 2. 查看该 `tidb-server` 的日志，grep gc_worker tidb.log； + 3. 如果发现这段时间一直在 resolve locks（最后一条日志是 `start resolve locks`）或者 delete ranges（最后一条日志是 `start delete {number} ranges`），说明 GC 进程是正常的。否则需要报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 + +### 重要级别报警项 + +对于重要级别的报警，需要密切关注异常指标。 + +#### `TiKV_server_report_failure_msg_total` + +* 报警规则： + + `sum(rate(tikv_server_report_failure_msg_total{type="unreachable"}[10m])) BY (store_id) > 10` + +* 规则描述： + + 表明无法连接远端的 TiKV。 + +* 处理方法： + + 1. 检查网络是否通畅。 + 2. 检查远端 TiKV 是否挂掉。 + 3. 如果远端 TiKV 没有挂掉，检查压力是否太大，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 处理方法。 + +#### `TiKV_channel_full_total` + +* 报警规则： + + `sum(rate(tikv_channel_full_total[10m])) BY (type, instance) > 0` + +* 规则描述： + + 该错误通常是因为 Raftstore 线程卡死，TiKV 的压力已经非常大了。 + +* 处理方法： + + 1. 观察 Raft Propose 监控，看这个报警的 TiKV 节点是否明显有比其他 TiKV 高很多。如果是，表明这个 TiKV 上有热点，需要检查热点调度是否能正常工作。 + 2. 观察 Raft IO 监控，看延迟是否升高。如果延迟很高，表明磁盘可能有瓶颈。一个能缓解但不怎么安全的办法是将 `sync-log` 改成 `false`。 + 3. 观察 Raft Process 监控，看 tick duration 是否很高。如果是，需要在 `[raftstore]` 配置下加上 `raft-base-tick-interval = “2s”`。 + +#### `TiKV_write_stall` + +* 报警规则： + + `delta(tikv_engine_write_stall[10m]) > 0` + +* 规则描述： + + RocksDB 写入压力太大，出现了 stall。 + +* 处理方法： + + 1. 观察磁盘监控，排除磁盘问题。 + 2. 看 TiKV 是否有写入热点。 + 3. 在 `[rocksdb]` 和 `[raftdb]` 配置下调大 `max-sub-compactions` 的值。 + +#### `TiKV_raft_log_lag` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_raftstore_log_lag_bucket[1m])) by (le, instance)) > 5000` + +* 规则描述： + + 这个值偏大，表明 Follower 已经远远落后于 Leader，Raft 没法正常同步了。可能的原因是 Follower 所在的 TiKV 卡住或者挂掉了。 + +#### `TiKV_async_request_snapshot_duration_seconds` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="snapshot"}[1m])) by (le, instance, type)) > 1` + +* 规则描述： + + 这个值偏大，表明 Raftstore 负载压力很大，可能已经卡住。 + +* 处理方法： + + 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 + +#### `TiKV_async_request_write_duration_seconds` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="write"}[1m])) by (le, instance, type)) > 1` + +* 规则描述： + + 这个值偏大，表明 Raft write 耗时很长。 + +* 处理方法： + + 1. 检查 Raftstore 上的压力，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 + 2. 检查 apply worker 线程的压力。 + +#### `TiKV_coprocessor_request_wait_seconds` + +* 报警规则： + + `histogram_quantile(0.9999, sum(rate(tikv_coprocessor_request_wait_seconds_bucket[1m])) by (le, instance, req)) > 10` + +* 规则描述： + + 这个值偏大，表明 Coprocessor worker 压力很大。可能有比较慢的任务卡住了 Coprocessor 线程。 + +* 处理方法： + + 1. 从 TiDB 日志中查看慢查询日志，看查询是否用到了索引或全表扫，或者看是否需要做 analyze。 + 2. 排查是否有热点。 + 3. 查看 Coprocessor 监控，看 `coporcessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 + +#### `TiKV_raftstore_thread_cpu_seconds_total` + +* 报警规则： + + `sum(rate(tikv_thread_cpu_seconds_total{name=~"raftstore_.*"}[1m])) by (instance, name) > 1.6` + +* 规则描述： + + Raftstore 线程压力太大。 + +* 处理方法： + + 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 + +#### `TiKV_raft_append_log_duration_secs` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_raftstore_append_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` + +* 规则描述： + + 表示 append Raft log 的耗时，如果高，通常是因为 IO 太忙了。 + +#### `TiKV_raft_apply_log_duration_secs` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_raftstore_apply_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` + +* 规则描述： + + 表示 apply Raft log 耗时，如果高，通常是因为 IO 太忙了。 + +#### `TiKV_scheduler_latch_wait_duration_seconds` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_scheduler_latch_wait_duration_seconds_bucket[1m])) by (le, instance, type)) > 1` + +* 规则描述： + + Scheduler 中写操作获取内存锁时的等待时间。如果这个值高，表明写操作冲突较多，也可能是某些引起冲突的操作耗时较长，阻塞了其它等待相同锁的操作。 + +* 处理方法： + + 1. 查看 Scheduler-All 监控中的 scheduler command duration，看哪一个命令耗时最大。 + 2. 查看 Scheduler-All 监控中的 scheduler scan details，看 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描，另外观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 + 3. 查看 Storage 监控中的 storage async snapshot/write duration，看是否 Raft 操作不及时。 + +#### `TiKV_thread_apply_worker_cpu_seconds` + +* 报警规则： + + `sum(rate(tikv_thread_cpu_seconds_total{name="apply_worker"}[1m])) by (instance) > 1.8` + +* 规则描述： + + Apply Raft log 线程压力太大，通常是因为写入太猛了。 + +#### `TiDB_tikvclient_gc_action_fail`（基本不发生，只在特殊配置下才会发生） + +* 报警规则： + + `sum(increase(tidb_tikvclient_gc_action_result{type="fail”}[1m])) > 10` + + > **注意：** + > + > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 + +* 规则描述： + + GC 失败的 Region 较多。 + +* 处理方法： + + 1. 一般是因为并行 GC 开的太高了，可以适当降低 GC 并行度。你需要先确认 GC 失败是由于服务器繁忙导致的。 + 2. 通过执行 `update set VARIABLE_VALUE=”{number}” where VARIABLE_NAME=”tikv_gc_concurrency”` 适当降低并行度。 + +### 警告级别报警项 + +警告级别的报警是对某一问题或错误的提醒。 + +#### `TiKV_leader_drops` + +* 报警规则： + + `delta(tikv_pd_heartbeat_tick_total{type="leader"}[30s]) < -10` + +* 规则描述： + + 该问题通常是因为 Raftstore 线程卡住了。 + +* 处理方法： + + 1. 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 + 2. 如果 TiKV 压力很小，考虑 PD 的调度是否太频繁。可以查看 PD 页面的 Operator Create 面板，排查 PD 产生调度的类型和数量。 + +#### `TiKV_raft_process_ready_duration_secs` + +* 报警规则： + + `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type='ready'}[1m])) by (le, instance, type)) > 2` + +* 规则描述： + + 表示处理 Raft ready 的耗时。这个值大，通常是因为 append log 任务卡住了。 + +#### `TiKV_raft_process_tick_duration_secs` + +* 报警规则： + + `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type=’tick’}[1m])) by (le, instance, type)) > 2` + +* 规则描述： + + 表示处理 Raft tick 的耗时，这个值大，通常是因为 Region 太多导致的。 + +* 处理方法： + + 1. 考虑使用更高等级的日志，比如 `warn` 或者 `error`。 + 2. 在 `[raftstore]` 配置下添加 `raft-base-tick-interval = “2s”`。 + +#### `TiKV_scheduler_context_total` + +* 报警规则： + + `abs(delta( tikv_scheduler_context_total[5m])) > 1000` + +* 规则描述： + + Scheduler 正在执行的写命令数量。这个值高，表示任务完成得不及时。 + +* 处理方法： + + 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 + +#### `TiKV_scheduler_command_duration_seconds` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_scheduler_command_duration_seconds_bucket[1m])) by (le, instance, type) / 1000) > 1` + +* 规则描述： + + 表明 Scheduler 执行命令的耗时。 + +* 处理方法： + + 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 + +#### `TiKV_coprocessor_outdated_request_wait_seconds` + +* 报警规则： + + `delta(tikv_coprocessor_outdated_request_wait_seconds_count[10m]) > 0` + +* 规则描述： + + Coprocessor 已经过期的请求等待的时间。这个值高，表示 Coprocessor 压力已经非常大了。 + +* 处理方法： + + 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 + +#### `TiKV_coprocessor_request_error` + +* 报警规则： + + `increase(tikv_coprocessor_request_error{reason!="lock"}[10m]) > 100` + +* 规则描述： + + Coprocessor 的请求错误。 + +* 处理方法： + + Coprocessor 错误的主要原因分为“lock”、“outdated”和“full”等。“outdated”表示请求超时，很可能是由于排队时间过久，或者单个请求的耗时比较长。“full”表示 Coprocessor 的请求队列已经满了，可能是正在执行的请求比较耗时，导致新来的请求都在排队。耗时比较长的查询需要查看下对应的执行计划是否正确。 + +#### `TiKV_coprocessor_request_lock_error` + +* 报警规则： + + `increase(tikv_coprocessor_request_error{reason="lock"}[10m]) > 10000` + +* 规则描述： + + Coprocessor 请求锁的错误。 + +* 处理方法： + + Coprocessor 错误的主要原因分为“lock”、“outdated”、“full”等。“lock”表示读到的数据正在写入，需要等待一会再读（TiDB 内部会自动重试）。少量这种错误不用关注，如果有大量这种错误，需要查看写入和查询是否有冲突。 + +#### `TiKV_coprocessor_pending_request` + +* 报警规则： + + `delta(tikv_coprocessor_pending_request[10m]) > 5000` + +* 规则描述： + + Coprocessor 排队的请求。 + +* 处理方法： + + 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 + +#### `TiKV_batch_request_snapshot_nums` + +* 报警规则： + + `sum(rate(tikv_thread_cpu_seconds_total{name=~"cop_.*"}[1m])) by (instance) / (count(tikv_thread_cpu_seconds_total{name=~"cop_.*"}) * 0.9) / count(count(tikv_thread_cpu_seconds_total) by (instance)) > 0` + +* 规则描述： + + 某个 TiKV 的 Coprocessor CPU 使用率超过了 90%。 + +#### `TiKV_pending_task` + +* 报警规则： + + `sum(tikv_worker_pending_task_total) BY (instance,name) > 1000` + +* 规则描述： + + TiKV 等待的任务数量。 + +* 处理方法： + + 查看是哪一类任务的值偏高，通常 Coprocessor、apply worker 这类任务都可以在其他指标里找到解决办法。 + +#### `TiKV_low_space_and_add_region` + +* 报警规则： + + `count((sum(tikv_store_size_bytes{type="available"}) by (instance) / sum(tikv_store_size_bytes{type="capacity"}) by (instance) < 0.2) and (sum(tikv_raftstore_snapshot_traffic_total{type="applying"}) by (instance) > 0)) > 0` + +#### `TiKV_approximate_region_size` + +* 报警规则： + + `histogram_quantile(0.99, sum(rate(tikv_raftstore_region_size_bucket[1m])) by (le)) > 1073741824` + +* 规则描述： + + TiKV split checker 扫描到的最大的 Region approximate size 在 1 分钟内持续大于 1 GB。 + +* 处理方法： + + Region 分裂的速度不及写入的速度。为缓解这种情况，建议更新到支持 batch-split 的版本 (>= 2.1.0-rc1)。如暂时无法更新，可以使用 `pd-ctl operator add split-region --policy=approximate` 手动分裂 Region。 + +## TiDB Binlog 报警规则 + +关于 TiDB Binlog 报警规则的详细描述，参见 [TiDB Binlog 集群监控报警文档](/reference/tidb-binlog/monitor.md#监控报警规则)。 + +## Node_exporter 主机报警规则 + +本节介绍了 Node_exporter 主机的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 + +### 紧急级别报警项 + +紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 + +#### `NODE_disk_used_more_than_80%` + +* 报警规则： + + `node_filesystem_avail{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} / node_filesystem_size{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} * 100 <= 20` + +* 规则描述： + + 机器磁盘空间使用率超过 80%。 + +* 处理方法： + + 登录机器，执行 `df -h` 命令，查看磁盘空间使用率，做好扩容计划。 + +#### `NODE_disk_inode_more_than_80%` + +* 报警规则： + + `node_filesystem_files_free{fstype=~"(ext.|xfs)"} / node_filesystem_files{fstype=~"(ext.|xfs)"} * 100 < 20` + +* 规则描述： + + 机器磁盘挂载目录文件系统 inode 使用率超过 80%。 + +* 处理方法： + + 登录机器，执行 `df -i` 命令，查看磁盘挂载目录文件系统 inode 使用率，做好扩容计划。 + +#### `NODE_disk_readonly` + +* 报警规则： + + `node_filesystem_readonly{fstype=~"(ext.|xfs)"} == 1` + +* 规则描述： + + 磁盘挂载目录文件系统只读，无法写入数据，一般是因为磁盘故障或文件系统损坏。 + +* 处理方法： + + * 登录机器创建文件测试是否正常。 + * 检查该服务器硬盘指示灯是否正常，如异常，需更换磁盘并修复该机器文件系统。 + +### 重要级别报警项 + +对于重要级别的报警，需要密切关注异常指标。 + +#### `NODE_memory_used_more_than_80%` + +* 报警规则： + + `(((node_memory_MemTotal-node_memory_MemFree-node_memory_Cached)/(node_memory_MemTotal)*100)) >= 80` + +* 规则描述： + + 机器内存使用率超过 80%。 + +* 处理方法： + + * 在 Grafana Node Exporter 页面查看该主机的 Memory 面板，检查 `Used` 是否过高，`Available` 内存是否过低。 + * 登录机器，执行 `free -m` 命令查看内存使用情况，执行 `top` 看是否有异常进程的内存使用率过高。 + +### 警告级别报警项 + +警告级别的报警是对某一问题或错误的提醒。 + +#### `NODE_node_overload` + +* 报警规则： + + `(node_load5 / count without (cpu, mode) (node_cpu{mode="system"})) > 1` + +* 规则描述： + + 机器 CPU 负载较高。 + +* 处理方法： + + * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 + * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 + +#### `NODE_cpu_used_more_than_80%` + +* 报警规则： + + `avg(irate(node_cpu{mode="idle"}[5m])) by(instance) * 100 <= 20` + +* 规则描述： + + 机器 CPU 使用率超过 80%。 + +* 处理方法： + + * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 + * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 + +#### `NODE_tcp_estab_num_more_than_50000` + +* 报警规则： + + `node_netstat_Tcp_CurrEstab > 50000` + +* 规则描述： + + 机器 `establish` 状态的 TCP 链接超过 50,000。 + +* 处理方法： + + 登录机器执行 `ss -s` 可查看当前系统 `estab` 状态的 TCP 链接数，执行 `netstat` 查看是否有异常链接。 + +#### `NODE_disk_read_latency_more_than_32ms` + +* 报警规则： + + `((rate(node_disk_read_time_ms{device=~".+"}[5m]) / rate(node_disk_reads_completed{device=~".+"}[5m])) or (irate(node_disk_read_time_ms{device=~".+"}[5m]) / irate(node_disk_reads_completed{device=~".+"}[5m]))) > 32` + +* 规则描述： + + 磁盘读延迟超过 32 毫秒。 + +* 处理方法： + + * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 + * 查看 Disk Latency 面板观察磁盘的读延迟。 + * 查看 Disk IO Utilization 面板观察 IO 使用率。 + +#### `NODE_disk_write_latency_more_than_16ms` + +* 报警规则： + + `((rate(node_disk_write_time_ms{device=~".+"}[5m]) / rate(node_disk_writes_completed{device=~".+"}[5m])) or (irate(node_disk_write_time_ms{device=~".+"}[5m]) / irate(node_disk_writes_completed{device=~".+"}[5m])))> 16` + +* 规则描述： + + 机器磁盘写延迟超过 16 毫秒。 + +* 处理方法： + + * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 + * 查看 Disk Latency 面板可查看磁盘的写延迟。 + * 查看 Disk IO Utilization 面板可查看 IO 使用率。 + +## Blackbox_exporter TCP、ICMP 和 HTTP 报警规则 + +本节介绍了 Blackbox_exporter TCP、ICMP 和 HTTP 的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 + +### 紧急级别报警项 + +紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 + +#### `TiDB_server_is_down` + +* 报警规则： + + `probe_success{group="tidb"} == 0` + +* 规则描述： + + TiDB 服务端口探测失败。 + +* 处理方法： + + * 检查 TiDB 服务所在机器是否宕机。 + * 检查 TiDB 进程是否存在。 + * 检查监控机与 TiDB 服务所在机器之间网络是否正常。 + +#### `Pump_server_is_down` + +* 报警规则： + + `probe_success{group="pump"} == 0` + +* 规则描述： + + Pump 服务端口探测失败。 + +* 处理方法： + + * 检查 Pump 服务所在机器是否宕机。 + * 检查 Pump 进程是否存在。 + * 检查监控机与 Pump 服务所在机器之间网络是否正常。 + +#### `Drainer_server_is_down` + +* 报警规则： + + `probe_success{group="drainer"} == 0` + +* 规则描述： + + Drainer 服务端口探测失败。 + +* 处理方法： + + * 检查 Drainer 服务所在机器是否宕机。 + * 检查 Drainer 进程是否存在。 + * 检查监控机与 Drainer 服务所在机器之间网络是否正常。 + +#### `TiKV_server_is_down` + +* 报警规则： + + `probe_success{group="tikv"} == 0` + +* 规则描述： + + TiKV 服务端口探测失败。 + +* 处理方法： + + * 检查 TiKV 服务所在机器是否宕机。 + * 检查 TiKV 进程是否存在。 + * 检查监控机与 TiKV 服务所在机器之间网络是否正常。 + +#### `PD_server_is_down` + +* 报警规则： + + `probe_success{group="pd"} == 0` + +* 规则描述： + + PD 服务端口探测失败。 + +* 处理方法： + + * 检查 PD 服务所在机器是否宕机。 + * 检查 PD 进程是否存在。 + * 检查监控机与 PD 服务所在机器之间网络是否正常。 + +#### `Node_exporter_server_is_down` + +* 报警规则： + + `probe_success{group="node_exporter"} == 0` + +* 规则描述： + + Node_exporter 服务端口探测失败。 + +* 处理方法： + + * 检查 Node_exporter 服务所在机器是否宕机。 + * 检查 Node_exporter 进程是否存在。 + * 检查监控机与 Node_exporter 服务所在机器之间网络是否正常。 + +#### `Blackbox_exporter_server_is_down` + +* 报警规则： + + `probe_success{group="blackbox_exporter"} == 0` + +* 规则描述： + + Blackbox_exporter 服务端口探测失败。 + +* 处理方法： + + * 检查 Blackbox_exporter 服务所在机器是否宕机。 + * 检查 Blackbox_exporter 进程是否存在。 + * 检查监控机与 Blackbox_exporter 服务所在机器之间网络是否正常。 + +#### `Grafana_server_is_down` + +* 报警规则： + + `probe_success{group="grafana"} == 0` + +* 规则描述： + + Grafana 服务端口探测失败。 + +* 处理方法： + + * 检查 Grafana 服务所在机器是否宕机。 + * 检查 Grafana 进程是否存在。 + * 检查监控机与 Grafana 服务所在机器之间网络是否正常。 + +#### `Pushgateway_server_is_down` + +* 报警规则： + + `probe_success{group="pushgateway"} == 0` + +* 规则描述： + + Pushgateway 服务端口探测失败。 + +* 处理方法： + + * 检查 Pushgateway 服务所在机器是否宕机。 + * 检查 Pushgateway 进程是否存在。 + * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 + +#### `Kafka_exporter_is_down` + +* 报警规则： + + `probe_success{group="kafka_exporter"} == 0` + +* 规则描述： + + Kafka_exporter 服务端口探测失败。 + +* 处理方法： + + * 检查 Kafka_exporter 服务所在机器是否宕机。 + * 检查 Kafka_exporter 进程是否存在。 + * 检查监控机与 Kafka_exporter 服务所在机器之间网络是否正常。 + +#### `Pushgateway_metrics_interface` + +* 报警规则： + + `probe_success{job="blackbox_exporter_http"} == 0` + +* 规则描述： + + Pushgateway 服务 http 接口探测失败。 + +* 处理方法： + + * 检查 Pushgateway 服务所在机器是否宕机。 + * 检查 Pushgateway 进程是否存在。 + * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 + +### 警告级别报警项 + +警告级别的报警是对某一问题或错误的提醒。 + +#### `BLACKER_ping_latency_more_than_1s` + +* 报警规则： + + `max_over_time(probe_duration_seconds{job=~"blackbox_exporter.*_icmp"}[1m]) > 1` + +* 规则描述： + + Ping 延迟超过 1 秒。 + +* 处理方法： + + * 在 Grafana Blackbox Exporter dashboard 上检查两个节点间的 ping 延迟是否太高。 + * 在 Grafana Blackbox Exporter dashboard 的 tcp 面板上检查是否有丢包。 diff --git a/reference/best-practices/grafana-monitor.md b/reference/best-practices/grafana-monitor.md new file mode 100644 index 000000000000..6e3f2df68efa --- /dev/null +++ b/reference/best-practices/grafana-monitor.md @@ -0,0 +1,206 @@ +--- +title: 使用 Grafana 监控 TiDB 的最佳实践 +summary: 了解高效利用 Grafana 监控 TiDB 的七个技巧。 +category: reference +--- + +# 使用 Grafana 监控 TiDB 的最佳实践 + +[使用 TiDB Ansible 部署 TiDB 集群](/how-to/deploy/orchestrated/ansible.md)时，会同时部署一套 [Grafana + Prometheus 的监控平台](/how-to/monitor/overview.md)，用于收集和展示 TiDB 集群各个组件和机器的 metric 信息。本文主要介绍使用 TiDB 监控的最佳实践，旨在帮助 TiDB 用户高效利用丰富的 metric 信息来分析 TiDB 的集群状态或进行故障诊断。 + +## 监控架构 + +Prometheus 是一个拥有多维度数据模型和灵活查询语句的时序数据库。Grafana 是一个开源的 metric 分析及可视化系统。 + +![TiDB 监控整体架构](/media/prometheus-in-tidb.png) + +从 TiDB 2.1.3 版本开始，监控采用 pull 的方式，而之前版本采用的是 push 的方式，这是一个非常好的调整，它有以下几个优点： + +- 如果 Prometheus 需要迁移，无需重启整个 TiDB 集群。调整前，因为组件要调整 push 的目标地址，迁移 Prometheus 需要重启整个集群。 +- 支持部署 2 套独立的 Grafana + Prometheus 的监控平台（非 HA），防止监控的单点。方法是使用 ansible 用不同的 ip 各执行一次部署命令。 +- 去掉了 Pushgateway 这个单点组件。 + +## 监控数据的来源与展示 + +TiDB 的 3 个核心组件（TiDB server、TiKV server 和 PD server）可以通过 HTTP 接口来获取 metric 数据。这些 metric 均是从程序代码中上传的，默认端口如下： + +| 组件 | 端口 | +|:------------|:-------| +| TiDB server | 10080 | +| TiKV server | 20181 | +| PD server | 2379 | + +下面以 TiDB server 为例，展示如何通过 HTTP 接口查看一个语句的 QPS 数据： + +{{< copyable "shell-regular" >}} + +```bash +curl http://__tidb_ip__:10080/metrics |grep tidb_executor_statement_total +``` + +``` +# 可以看到实时 QPS 数据，并根据不同 type 对 SQL 语句进行了区分，value 是 counter 类型的累计值（科学计数法）。 +tidb_executor_statement_total{type="Delete"} 520197 +tidb_executor_statement_total{type="Explain"} 1 +tidb_executor_statement_total{type="Insert"} 7.20799402e+08 +tidb_executor_statement_total{type="Select"} 2.64983586e+08 +tidb_executor_statement_total{type="Set"} 2.399075e+06 +tidb_executor_statement_total{type="Show"} 500531 +tidb_executor_statement_total{type="Use"} 466016 +``` + +这些数据会存储在 Prometheus 中，然后在 Grafana 上进行展示。在面板上点击鼠标右键会出现 **Edit** 按钮（或直接按 E 键），如下图所示： + +![Metrics 面板的编辑入口](/media/best-practices/metric-board-edit-entry.png) + +点击 **Edit** 按钮之后，在 Metrics 面板上可以看到利用该 metric 的 query 表达式。面板上一些细节的含义如下： + +- `rate[1m]`：表示 1 分钟的增长速率，只能用于 counter 类型的数据。 +- `sum`：表示 value 求和。 +- `by type`：表示将求和后的数据按 metric 原始值中的 type 进行分组。 +- `Legend format`：表示指标名称的格式。 +- `Resolution`：默认打点步长是 15s，Resolution 表示是否将多个样本数据合并成一个点。 + +Metrics 面板中的表达式如下： + +![Metric 面板中的表达式](/media/best-practices/metric-board-expression.jpeg) + +Prometheus 支持很多表达式与函数，更多表达式请参考 [Prometheus 官网页面](https://prometheus.io/docs/prometheus/latest/querying)。 + +## Grafana 使用技巧 + +本小节介绍高效利用 Grafana 监控分析 TiDB 指标的七个技巧。 + +### 技巧 1：查看所有维度并编辑表达式 + +在[监控数据的来源与展示](#监控数据的来源与展示)一节的示例中，数据是按照 type 进行分组的。如果你想知道是否还能按其它维度分组，并快速查看还有哪些维度，可采用以下技巧：**在 query 的表达式上只保留指标名称，不做任何计算，`Legend format` 也留空**。这样就能显示出原始的 metric 数据。比如，下图能看到有 3 个维度（`instance`、`job` 和 `type`）： + +![编辑表达式并查看所有维度](/media/best-practices/edit-expression-check-dimensions.jpg) + +然后调整表达式，在原有的 `type` 后面加上 `instance` 这个维度，在 `Legend format` 处增加 `{{instance}}`，就可以看到每个 TiDB server 上执行的不同类型 SQL 语句的 QPS 了。如下图所示： + +![给表达式增加一个 instance 维度](/media/best-practices/add-instance-dimension.jpeg) + +### 技巧 2：调整 Y 轴标尺的计算方式 + +以 Query Duration 指标为例，默认的比例尺采用 2 的对数计算，显示上会将差距缩小。为了观察到明显的变化，可以将比例尺改为线性，从下面两张图中可以看到显示上的区别，明显发现那个时刻有个 SQL 语句运行较慢。 + +当然也不是所有场景都适合用线性，比如观察 1 个月的性能趋势，用线性可能就会有很多噪点，不好观察。 + +标尺默认的比例尺为 2 的对数： + +![标尺默认的比例尺为 2 的对数](/media/best-practices/default-axes-scale.jpg) + +将标尺的比例尺调整为线性： + +![调整标尺的比例尺为线性](/media/best-practices/axes-scale-linear.jpg) + +> **建议：** +> +> 结合技巧 1，会发现这里还有一个 `sql_type` 的维度，可以立刻分析出是 `SELECT` 慢还是 `UPDATE` 慢；并且可以分析出是哪个 instance 上的语句慢。 + +### 技巧 3：调整 Y 轴基线，放大变化 + +有时已经用了线性比例尺，却还是看不出变化趋势。比如下图中，在扩容后想观察 `Store size` 的实时变化效果，但由于基数较大，观察不到微弱的变化。这时可以将 Y 轴最小值从 `0` 改为 `auto`，将上部放大。观察下面两张图的区别，可以看出数据已开始迁移了。 + +基线默认为 `0`： + +![基线默认为 0](/media/best-practices/default-y-min.jpeg) + +将基线调整为 `auto`： + +![调整基线为 auto](/media/best-practices/y-min-auto.jpg) + +### 技巧 4：标尺联动 + +在 **Settings** 面板中，有一个 **Graph Tooltip** 设置项，默认使用 **Default**。 + +![图形展示工具](/media/best-practices/graph-tooltip.jpeg) + +下面将图形展示工具分别调整为 **Shared crosshair** 和 **Shared Tooltip** 看看效果。可以看到标尺能联动展示了，方便排查问题时确认 2 个指标的关联性。 + +将图形展示工具调整为 **Shared crosshair**： + +![调整图形展示工具为 Shared crosshair](/media/best-practices/graph-tooltip-shared-crosshair.jpeg) + +将图形展示工具调整为 **Shared Tooltip**： + +![调整图形展示工具为 Shared Tooltip](/media/best-practices/graph-tooltip-shared-tooltip.jpg) + +### 技巧 5：手动输入 `ip:端口号` 查看历史信息 + +PD 的 dashboard 只展示当前 leader 的 metric 信息，而有时想看历史上 PD leader 当时的状况，但是 `instance` 下拉列表中已不存在这个成员了。此时，可以手动输入 `ip:2379` 来查看当时的数据。 + +![查看历史 metric 信息](/media/best-practices/manually-input-check-metric.jpeg) + +### 技巧 6：巧用 `Avg` 函数 + +通常默认图例中只有 `Max` 和 `Current` 函数。当指标波动较大时，可以增加 `Avg` 等其它汇总函数的图例，来看一段时间的整体趋势。 + +增加 `Avg` 等汇总函数： + +![增加 Avg 等汇总函数](/media/best-practices/add-avg-function.jpeg) + +然后查看整体趋势： + +![增加 Avg 函数查看整体趋势](/media/best-practices/add-avg-function-check-trend.jpg) + +### 技巧 7：使用 Prometheus 的 API 接口获得表达式的结果 + +Grafana 通过 Prometheus 的接口获取数据，你也可以用该接口来获取数据，这个用法还可以衍生出许多功能： + +- 自动获取集群规模、状态等信息。 +- 对表达式稍加改动给报表提供数据，如统计每天的 QPS 总量、每天的 QPS 峰值和每天的响应时间。 +- 将重要的指标进行定期健康巡检。 + +Prometheus 的 API 接口如下： + +![Prometheus 的 API 接口](/media/best-practices/prometheus-api-interface.jpg) + +{{< copyable "shell-regular" >}} + +```bash +curl -u user:pass 'http://__grafana_ip__:3000/api/datasources/proxy/1/api/v1/query_range?query=sum(tikv_engine_size_bytes%7Binstancexxxxxxxxx20181%22%7D)%20by%20(instance)&start=1565879269&end=1565882869&step=30' |python -m json.tool +``` + +``` +{ + "data": { + "result": [ + { + "metric": { + "instance": "xxxxxxxxxx:20181" + }, + "values": [ + [ + 1565879269, + "1006046235280" + ], + [ + 1565879299, + "1006057877794" + ], + [ + 1565879329, + "1006021550039" + ], + [ + 1565879359, + "1006021550039" + ], + [ + 1565882869, + "1006132630123" + ] + ] + } + ], + "resultType": "matrix" + }, + "status": "success" +} +``` + +## 总结 + +Grafana + Prometheus 监控平台是一套非常强大的组合工具，用好这套工具可以为分析节省很多时间，提高效率，更重要的是，我们可以更容易发现问题。在运维 TiDB 集群，尤其是数据量大的情况下，这套工具能派上大用场。 diff --git a/dev/reference/best-practices/haproxy.md b/reference/best-practices/haproxy.md similarity index 100% rename from dev/reference/best-practices/haproxy.md rename to reference/best-practices/haproxy.md diff --git a/reference/best-practices/high-concurrency.md b/reference/best-practices/high-concurrency.md new file mode 100644 index 000000000000..243664c1d4e8 --- /dev/null +++ b/reference/best-practices/high-concurrency.md @@ -0,0 +1,203 @@ +--- +title: TiDB 高并发写入场景最佳实践 +summary: 了解 TiDB 在高并发写入场景下的最佳实践。 +category: reference +--- + +# TiDB 高并发写入场景最佳实践 + +在 TiDB 的使用过程中，一个典型场景是高并发批量写入数据到 TiDB。本文阐述了该场景中的常见问题，旨在给出一个业务的最佳实践，帮助读者避免因使用 TiDB 不当而影响业务开发。 + +## 目标读者 + +本文假设你已对 TiDB 有一定的了解，推荐先阅读 TiDB 原理相关的三篇文章（[讲存储](https://pingcap.com/blog-cn/tidb-internal-1/)，[说计算](https://pingcap.com/blog-cn/tidb-internal-2/)，[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)），以及 [TiDB Best Practice](https://pingcap.com/blog-cn/tidb-best-practice/)。 + +## 高并发批量插入场景 + +高并发批量插入的场景通常出现在业务系统的批量任务中，例如清算以及结算等业务。此类场景存在以下特点： + +- 数据量大 +- 需要短时间内将历史数据入库 +- 需要短时间内读取大量数据 + +这就对 TiDB 提出了以下挑战： + +- 写入/读取能力是否可以线性水平扩展 +- 随着数据持续大并发写入，数据库性能是否稳定不衰减 + +对于分布式数据库来说，除了本身的基础性能外，最重要的就是充分利用所有节点能力，避免让单个节点成为瓶颈。 + +## TiDB 数据分布原理 + +如果要解决以上挑战，需要从 TiDB 数据切分以及调度的原理开始讲起。这里只作简单说明，详情可参阅[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)。 + +TiDB 以 Region 为单位对数据进行切分，每个 Region 有大小限制（默认 96M）。Region 的切分方式是范围切分。每个 Region 会有多副本，每一组副本，称为一个 Raft Group。每个 Raft Group 中由 Leader 负责执行这块数据的读 & 写（TiDB 即将支持 [Follower-Read](https://zhuanlan.zhihu.com/p/78164196)）。Leader 会自动地被 PD 组件均匀调度在不同的物理节点上，用以均分读写压力。 + +![TiDB 数据概览](/media/best-practices/tidb-data-overview.png) + +只要业务的写入没有 `AUTO_INCREMENT` 的主键，或没有单调递增的索引（即没有业务上的写入热点，更多细节可参阅 [TiDB 正确使用方式](https://zhuanlan.zhihu.com/p/25574778)），从原理上来说，TiDB 依靠这个架构可具备线性扩展的读写能力，并且可以充分利用分布式资源。从这一点看，TiDB 尤其适合高并发批量写入场景的业务。 + +但理论场景和实际情况往往存在不同。以下实例说明了热点是如何产生的。 + +## 热点产生的实例 + +以下为一张示例表： + +```sql +CREATE TABLE IF NOT EXISTS TEST_HOTSPOT( + id BIGINT PRIMARY KEY, + age INT, + user_name VARCHAR(32), + email VARCHAR(128) +) +``` + +这个表的结构非常简单，除了 `id` 为主键以外，没有额外的二级索引。将数据写入该表的语句如下，`id` 通过随机数离散生成： + +{{< copyable "sql" >}} + +```sql +INSERT INTO TEST_HOTSPOT(id, age, user_name, email) values(%v, %v, '%v', '%v'); +``` + +负载是短时间内密集地执行以上写入语句。 + +以上操作看似符合理论场景中的 TiDB 最佳实践，业务上没有热点产生。只要有足够的机器，就可以充分利用 TiDB 的分布式能力。要验证是否真的符合最佳实践，可以在实验环境中进行测试。 + +部署拓扑 2 个 TiDB 节点，3 个 PD 节点，6 个 TiKV 节点。请忽略 QPS，因为测试只是为了阐述原理，并非 benchmark。 + +![QPS1](/media/best-practices/QPS1.png) + +客户端在短时间内发起了“密集”的写入，TiDB 收到的请求是 3K QPS。理论上，压力应该均摊给 6 个 TiKV 节点。但是从 TiKV 节点的 CPU 使用情况上看，存在明显的写入倾斜（tikv - 3 节点是写入热点）： + +![QPS2](/media/best-practices/QPS2.png) + +![QPS3](/media/best-practices/QPS3.png) + +[Raft store CPU](/reference/key-monitoring-metrics/tikv-dashboard.md) 为 `raftstore` 线程的 CPU 使用率，通常代表写入的负载。在这个场景下 tikv-3 为 Raft Leader，tikv-0 和 tikv-1 是 Raft 的 Follower，其他的 TiKV 节点的负载几乎为空。 + +从 PD 的监控中也可以证明热点的产生： + +![QPS4](/media/best-practices/QPS4.png) + +## 热点问题产生的原因 + +以上测试并未达到理论场景中最佳实践，因为刚创建表的时候，这个表在 TiKV 中只会对应为一个 Region，范围是： + +``` +[CommonPrefix + TableID, CommonPrefix + TableID + 1) +``` + +短时间内大量数据会持续写入到同一个 Region 上。 + +![TiKV Region 分裂流程](/media/best-practices/tikv-Region-split.png) + +上图简单描述了这个过程，随着数据持续写入，TiKV 会将一个 Region 切分为多个。但因为首先发起选举的是原 Leader 所在的 Store，所以新切分好的两个 Region 的 Leader 很可能还会在原 Store 上。新切分好的 Region 2，3 上，也会重复之前发生在 Region 1 上的过程。也就是压力会密集地集中在 TiKV-Node 1 上。 + +在持续写入的过程中，PD 发现 Node 1 中产生了热点，会将 Leader 均分到其他的 Node 上。如果 TiKV 的节点数多于副本数的话，TiKV 会尽可能将 Region 迁移到空闲的节点上。这两个操作在数据插入的过程中，也能在 PD 监控中得到印证： + +![QPS5](/media/best-practices/QPS5.png) + +在持续写入一段时间后，整个集群会被 PD 自动地调度成一个压力均匀的状态，到那个时候整个集群的能力才会真正被利用起来。在大多数情况下，以上热点产生的过程是没有问题的，这个阶段属于表 Region 的预热阶段。 + +但是对于高并发批量密集写入场景来说，应该避免这个阶段。 + +## 热点问题的规避方法 + +为了达到场景理论中的最佳性能，可跳过这个预热阶段，直接将 Region 切分为预期的数量，提前调度到集群的各个节点中。 + +TiDB 在 v3.0.x 以及 v2.1.13 后支持一个叫 [Split Region](/reference/sql/statements/split-region.md) 的新特性。这个特性提供了新的语法： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num +``` + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] +``` + +但是 TiDB 并不会自动提前完成这个切分操作。原因如下： + +![Table Region Range](/media/best-practices/table-Region-range.png) + +从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 + +如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 + +作为一款通用数据库，TiDB 并不对数据的分布作假设，所以开始只用一个 Region 来对应一个表。等到真实数据插入进来以后，TiDB 自动根据数据的分布来作切分。这种方式是较通用的。 + +所以 TiDB 提供了 `Split Region` 语法，专门针对短时批量写入场景作优化。基于以上案例，下面尝试用 `Split Region` 语法提前切散 Region，再观察负载情况。 + +由于测试的写入数据在正数范围内完全离散，所以用以下语句，在 Int64 空间内提前将表切分为 128 个 Region： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; +``` + +切分完成以后，可以通过 `SHOW TABLE test_hotspot REGIONS;` 语句查看打散的情况。如果 `SCATTERING` 列值全部为 `0`，代表调度成功。 + +也可以通过 [table-regions.py](https://github.com/pingcap/tidb-ansible/blob/dabf60baba5e740a4bee9faf95e77563d8084be1/scripts/table-regions.py) 脚本，查看 Region 的分布。目前分布已经比较均匀了： + +``` +[root@172.16.4.4 scripts]# python table-regions.py --host 172.16.4.3 --port 31453 test test_hotspot +[RECORD - test.test_hotspot] - Leaders Distribution: + total leader count: 127 + store: 1, num_leaders: 21, percentage: 16.54% + store: 4, num_leaders: 20, percentage: 15.75% + store: 6, num_leaders: 21, percentage: 16.54% + store: 46, num_leaders: 21, percentage: 16.54% + store: 82, num_leaders: 23, percentage: 18.11% + store: 62, num_leaders: 21, percentage: 16.54% +``` + +再重新运行写入负载： + +![QPS6](/media/best-practices/QPS6.png) + +![QPS7](/media/best-practices/QPS7.png) + +![QPS8](/media/best-practices/QPS8.png) + +可以看到已经消除了明显的热点问题了。 + +本示例仅为一个简单的表，还有索引热点的问题需要考虑。读者可参阅 [Split Region](/reference/sql/statements/split-region.md) 文档来了解如何预先切散索引相关的 Region。 + +### 更复杂的热点问题 + +如果表没有主键或者主键不是 Int 类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 + +要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/reference/sql/statements/split-region.md#pre_split_regions)）。 + +`SHARD_ROW_ID_BITS` 用于将 `_tidb_rowid` 列生成的行 ID 随机打散。`pre_split_regions` 用于在建完表后预先进行 Split region。 + +> **注意：** +> +> `pre_split_regions` 必须小于或等于 `shard_row_id_bits`。 + +示例： + +{{< copyable "sql" >}} + +```sql +create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; +``` + +- `SHARD_ROW_ID_BITS = 4` 表示 tidb_rowid 的值会随机分布成 16 （16=2^4） 个范围区间。 +- `pre_split_regions=3` 表示建完表后提前切分出 8 (2^3) 个 Region。 + +开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 + +## 参数配置 + +TiDB 2.1 版本中在 SQL 层引入了 [latch 机制](/reference/configuration/tidb-server/configuration-file.md#txn-local-latches)，用于在写入冲突比较频繁的场景中提前发现事务冲突，减少 TiDB 和 TiKV 事务提交时写写冲突导致的重试。通常，跑批场景使用的是存量数据，所以并不存在事务的写入冲突。可以把 TiDB 的 latch 功能关闭，以减少为细小对象分配内存： + +``` +[txn-local-latches] +enabled = false +``` diff --git a/dev/reference/best-practices/java-app.md b/reference/best-practices/java-app.md similarity index 100% rename from dev/reference/best-practices/java-app.md rename to reference/best-practices/java-app.md diff --git a/reference/best-practices/massive-regions.md b/reference/best-practices/massive-regions.md new file mode 100644 index 000000000000..2dd6c904779f --- /dev/null +++ b/reference/best-practices/massive-regions.md @@ -0,0 +1,143 @@ +--- +title: 海量 Region 集群调优最佳实践 +summary: 了解海量 Region 导致性能问题的原因和优化方法。 +category: reference +--- + +# 海量 Region 集群调优最佳实践 + +在 TiDB 的架构中，所有数据以一定 key range 被切分成若干 Region 分布在多个 TiKV 实例上。随着数据的写入，一个集群中会产生上百万个甚至千万个 Region。单个 TiKV 实例上产生过多的 Region 会给集群带来较大的负担，影响整个集群的性能表现。 + +本文将介绍 TiKV 核心模块 Raftstore 的工作流程，海量 Region 导致性能问题的原因，以及优化性能的方法。 + +## Raftstore 的工作流程 + +一个 TiKV 实例上有多个 Region。Region 消息是通过 Raftstore 模块驱动 Raft 状态机来处理的。这些消息包括 Region 上读写请求的处理、Raft log 的持久化和复制、Raft 的心跳处理等。但是，Region 数量增多会影响整个集群的性能。为了解释这一点，需要先了解 TiKV 的核心模块 Raftstore 的工作流程。 + +![图 1 Raftstore 处理流程示意图](/media/best-practices/raft-process.png) + +> **注意：** +> +> 该图仅为示意，不代表代码层面的实际结构。 + +上图是 Raftstore 处理流程的示意图。如图所示，从 TiDB 发来的请求会通过 gRPC 和 storage 模块变成最终的 KV 读写消息，并被发往相应的 Region，而这些消息并不会被立即处理而是被暂存下来。Raftstore 会轮询检查每个 Region 是否有需要处理的消息。如果 Region 有需要处理的消息，那么 Raftstore 会驱动 Raft 状态机去处理这些消息，并根据这些消息所产生的状态变更去进行后续操作。例如，在有写请求时，Raft 状态机需要将日志落盘并且将日志发送给其他 Region 副本；在达到心跳间隔时，Raft 状态机需要将心跳信息发送给其他 Region 副本。 + +## 性能问题 + +从 Raftstore 处理流程示意图可以看出，需要依次处理各个 Region 的消息。那么在 Region 数量较多的情况下，Raftstore 需要花费一些时间去处理大量 Region 的心跳，从而带来一些延迟，导致某些读写请求得不到及时处理。如果读写压力较大，Raftstore 线程的 CPU 使用率容易达到瓶颈，导致延迟进一步增加，进而影响性能表现。 + +通常在有负载的情况下，如果 Raftstore 的 CPU 使用率达到了 85% 以上，即可视为达到繁忙状态且成为了瓶颈，同时 `propose wait duration` 可能会高达百毫秒级别。 + +> **注意：** +> +> + Raftstore 的 CPU 使用率是指单线程的情况。如果是多线程 Raftstore，可等比例放大使用率。 +> + 由于 Raftstore 线程中有 I/O 操作，所以 CPU 使用率不可能达到 100%。 + +### 性能监控 + +可在 Grafana 的 TiKV 面板下查看相关的监控 metrics： + ++ Thread-CPU 下的 `Raft store CPU` + + 参考值：低于 `raftstore.store-pool-size * 85%`。在 v2.1 版本中无此配置项，因此在 v2.1 中可视为 `raftstore.store-pool-size = 1`。 + + ![图 2 查看 Raftstore CPU](/media/best-practices/raft-store-cpu.png) + ++ Raft Propose 下的 `Propose wait duration` + + `Propose wait duration` 是从发送请求给 Raftstore，到 Raftstore 真正开始处理请求之间的延迟时间。如果该延迟时间较长，说明 Raftstore 比较繁忙或者处理 append log 比较耗时导致 Raftstore 不能及时处理请求。 + + 参考值：低于 50-100ms。 + + ![图 3 查看 Propose wait duration](/media/best-practices/propose-wait-duration.png) + +## 性能优化方法 + +找到性能问题的根源后，可从以下两个方向来解决性能问题： + ++ 减少单个 TiKV 实例的 Region 数 ++ 减少单个 Region 的消息数 + +### 方法一：增加 TiKV 实例 + +如果 I/O 资源和 CPU 资源都比较充足，可在单台机器上部署多个 TiKV 实例，以减少单个 TiKV 实例上的 Region 个数；或者增加 TiKV 集群的机器数。 + +### 方法二：调整 `raft-base-tick-interval` + +除了减少 Region 个数外，还可以通过减少 Region 单位时间内的消息数量来减小 Raftstore 的压力。例如，在 TiKV 配置中适当调大 `raft-base-tick-interval`： + +{{< copyable "" >}} + +``` +[raftstore] +raft-base-tick-interval = "2s" +``` + +`raft-base-tick-interval` 是 Raftstore 驱动每个 Region 的 Raft 状态机的时间间隔，也就是每隔该时长就需要向 Raft 状态机发送一个 tick 消息。增加该时间间隔，可以有效减少 Raftstore 的消息数量。 + +需要注意的是，该 tick 消息的间隔也决定了 `election timeout` 和 `heartbeat` 的间隔。示例如下： + +{{< copyable "" >}} + +``` +raft-election-timeout = raft-base-tick-interval * raft-election-timeout-ticks +raft-heartbeat-interval = raft-base-tick-interval * raft-heartbeat-ticks +``` + +如果 Region Follower 在 `raft-election-timeout` 间隔内未收到来自 Leader 的心跳，就会判断 Leader 出现故障而发起新的选举。`raft-heartbeat-interval` 是 Leader 向 Follower 发送心跳的间隔，因此调大 `raft-base-tick-interval` 可以减少单位时间内 Raft 发送的网络消息，但也会让 Raft 检测到 Leader 故障的时间更长。 + +### 方法三：提高 Raftstore 并发数 + +v3.0 版本中的 Raftstore 已经扩展为多线程，极大降低了 Raftstore 线程成为瓶颈的可能性。 + +TiKV 默认将 `raftstore.store-pool-size` 配置为 `2`。如果 Raftstore 出现瓶颈，可以根据实际情况适当调高该参数值，但不建议设置过高以免引入不必要的线程切换开销。 + +### 方法四：开启 Hibernate Region 功能 + +在实际情况中，读写请求并不会均匀分布到每个 Region 上，而是集中在少数的 Region 上。那么可以尽量减少暂时空闲的 Region 的消息数量，这也就是 Hibernate Region 的功能。无必要时可不进行 `raft-base-tick`，即不驱动空闲 Region 的 Raft 状态机，那么就不会触发这些 Region 的 Raft 产生心跳信息，极大地减小了 Raftstore 的工作负担。 + +截至 TiDB v3.0.5，Hibernate Region 仍是一个实验功能，在 [TiKV master](https://github.com/tikv/tikv/tree/master) 分支上已经默认开启。可根据实际情况和需求来开启该功能。Hibernate Region 的配置说明请参考[配置 Hibernate Region](https://github.com/tikv/tikv/blob/master/docs/reference/configuration/raftstore-config.md#hibernate-region)。 + +### 方法五：开启 `Region Merge` + +> **注意：** +> +> `Region Merge` 已在 TiDB v3.0 中默认开启。 + +开启 `Region Merge` 也能减少 Region 的个数。与 `Region Split` 相反，`Region Merge` 是通过调度把相邻的小 Region 合并的过程。在集群中删除数据或者执行 `Drop Table`/`Truncate Table` 语句后，可以将小 Region 甚至空 Region 进行合并以减少资源的消耗。 + +通过 pd-ctl 设置以下参数即可开启 `Region Merge`： + +{{< copyable "" >}} + +``` +>> pd-ctl config set max-merge-region-size 20 +>> pd-ctl config set max-merge-region-keys 200000 +>> pd-ctl config set merge-schedule-limit 8 +``` + +详情请参考[如何配置 Region Merge](https://github.com/tikv/tikv/blob/master/docs/how-to/configure/region-merge.md) 和 [PD 配置文件描述](/reference/configuration/pd-server/configuration-file.md#schedule)。 + +同时，默认配置的 `Region Merge` 的参数设置较为保守，可以根据需求参考 [PD 调度策略最佳实践](/reference/best-practices/pd-scheduling.md#region-merge-速度慢) 中提供的方法加快 `Region Merge` 过程的速度。 + +## 其他问题和解决方案 + +### 切换 PD Leader 的速度慢 + +PD 需要将 Region Meta 信息持久化在 etcd 上，以保证切换 PD Leader 节点后 PD 能快速继续提供 Region 路由服务。随着 Region 数量的增加，etcd 出现性能问题，使得 PD 在切换 Leader 时从 etcd 获取 Region Meta 信息的速度较慢。在百万 Region 量级时，从 etcd 获取信息的时间可能需要十几秒甚至几十秒。 + +因此在 v3.0 版本中，PD 默认开启配置项 `use-region-storage`，将 Region Meta 信息存在本地的 LevelDB 中，并通过其他机制同步 PD 节点间的信息。 + +### PD 路由信息更新不及时 + +在 TiKV 中，pd-worker 模块将 Region Meta 信息定期上报给 PD，在 TiKV 重启或者切换 Region Leader 时需要通过统计信息重新计算 Region 的 `approximate size/keys`。因此在 Region 数量较多的情况下，pd-worker 单线程可能成为瓶颈，造成任务得不到及时处理而堆积起来。因此 PD 不能及时获取某些 Region Meta 信息以致路由信息更新不及时。该问题不会影响实际的读写，但可能导致 PD 调度不准确以及 TiDB 更新 Region cache 时需要多几次 round-trip。 + +可在 TiKV Grafana 面板中查看 Task 下的 Worker pending tasks 来确定 pd-worker 是否有任务堆积。通常来说，pending tasks 应该维持在一个比较低的值。 + +![图 4 查看 pd-worker](/media/best-practices/pd-worker-metrics.png) + +目前已经在 [TiKV master](https://github.com/tikv/tikv/tree/master) 上对 pd-worker 进行了[效率优化](https://github.com/tikv/tikv/pull/5620)。[TiDB v3.0.5](https://pingcap.com/docs-cn/stable/releases/3.0.5/) 中已带上该优化。如果碰到类似问题，建议升级至 v3.0.5。 + +### Prometheus 查询 metrics 的速度慢 + +在大规模集群中，随着 TiKV 实例数的增加，Prometheus 查询 metrics 时的计算压力较大，导致 Grafana 查看 metrics 的速度较慢。v3.0 版本中设置了一些 metrics 的预计算，让这个问题有所缓解。 diff --git a/reference/best-practices/pd-scheduling.md b/reference/best-practices/pd-scheduling.md new file mode 100644 index 000000000000..e88978c8ce53 --- /dev/null +++ b/reference/best-practices/pd-scheduling.md @@ -0,0 +1,271 @@ +--- +title: PD 调度策略最佳实践 +summary: 了解 PD 调度策略的最佳实践和调优方式 +category: reference +--- + +# PD 调度策略最佳实践 + +本文将详细介绍 PD 调度系统的原理，并通过几个典型场景的分析和处理方式，分享调度策略的最佳实践和调优方式，帮助大家在使用过程中快速定位问题。本文假定你对 TiDB，TiKV 以及 PD 已经有一定的了解，相关核心概念如下： + +- [Leader/Follower/Learner](/glossary.md#leaderfollowerlearner) +- [Operator](/glossary.md#operator) +- [Operator Step](/glossary.md#operator-step) +- [Pending/Down](/glossary.md#pendingdown) +- [Region/Peer/Raft Group](/glossary.md#regionpeerraft-group) +- [Region Split](/glossary.md#region-split) +- [Scheduler](/glossary.md#scheduler) +- [Store](/glossary.md#store) + +> **注意：** +> +> 本文内容基于 TiDB 3.0 版本，更早的版本（2.x）缺少部分功能的支持，但是基本原理类似，也可以以本文作为参考。 + +## PD 调度原理 + +该部分介绍调度系统涉及到的相关原理和流程。 + +### 调度流程 + +宏观上来看，调度流程大体可划分为 3 个部分： + +1. 信息收集 + + TiKV 节点周期性地向 PD 上报 `StoreHeartbeat` 和 `RegionHeartbeat` 两种心跳消息： + + * `StoreHeartbeat` 包含 Store 的基本信息、容量、剩余空间和读写流量等数据。 + * `RegionHeartbeat` 包含 Region 的范围、副本分布、副本状态、数据量和读写流量等数据。 + + PD 梳理并转存这些信息供调度进行决策。 + +2. 生成调度 + + 不同的调度器从自身的逻辑和需求出发，考虑各种限制和约束后生成待执行的 Operator。这里所说的限制和约束包括但不限于： + + - 不往断连中、下线中、繁忙、空间不足、在大量收发 snapshot 等各种异常状态的 Store 添加副本 + - Balance 时不选择状态异常的 Region + - 不尝试把 Leader 转移给 Pending Peer + - 不尝试直接移除 Leader + - 不破坏 Region 各种副本的物理隔离 + - 不破坏 Label property 等约束 + +3. 执行调度 + + 调度执行的步骤为： + + a. Operator 先进入一个由 `OperatorController` 管理的等待队列。 + + b. `OperatorController` 会根据配置以一定的并发量从等待队列中取出 Operator 并执行。执行的过程就是依次把每个 Operator Step 下发给对应 Region 的 Leader。 + + c. 标记 Operator 为 “finish” 或 “timeout” 状态，然后从执行列表中移除。 + +### 负载均衡 + +Region 负载均衡调度主要依赖 `balance-leader` 和 `balance-region` 两个调度器。二者的调度目标是将 Region 均匀地分散在集群中的所有 Store 上，但它们各有侧重：`balance-leader` 关注 Region 的 Leader，目的是分散处理客户端请求的压力；`balance-region` 关注 Region 的各个 Peer，目的是分散存储的压力，同时避免出现爆盘等状况。 + +`balance-leader` 与 `balance-region` 有着相似的调度流程： + +1. 根据不同 Store 的对应资源量的情况分别打分。 +2. 不断从得分较高的 Store 选择 Leader 或 Peer 迁移到得分较低的 Store 上。 + +两者的分数计算上也有一定差异：`balance-leader` 比较简单，使用 Store 上所有 Leader 所对应的 Region Size 加和作为得分。因为不同节点存储容量可能不一致，计算 `balance-region` 得分会分以下三种情况： + +- 当空间富余时使用数据量计算得分（使不同节点数据量基本上均衡） +- 当空间不足时由使用剩余空间计算得分（使不同节点剩余空间基本均衡） +- 处于中间态时则同时考虑两个因素做加权和当作得分 + +此外，为了应对不同节点可能在性能等方面存在差异的问题，还可为 Store 设置负载均衡的权重。`leader-weight` 和 `region-weight` 分别用于控制 Leader 权重以及 Region 权重（默认值都为 “1”）。假如把某个 Store 的 `leader-weight` 设为 “2”，调度稳定后，则该节点的 Leader 数量约为普通节点的 2 倍；假如把某个 Store 的 `region-weight` 设为 “0.5”，那么调度稳定后该节点的 Region 数量约为其他节点的一半。 + +### 热点调度 + +热点调度对应的调度器是 `hot-region-scheduler`。在 3.0 版本中，统计热点 Region 的方式为： + +1. 根据 Store 上报的信息，统计出持续一段时间读或写流量超过一定阈值的 Region。 +2. 用与负载均衡类似的方式把这些 Region 分散开来。 + +对于写热点，热点调度会同时尝试打散热点 Region 的 Peer 和 Leader；对于读热点，由于只有 Leader 承载读压力，热点调度会尝试将热点 Region 的 Leader 打散。 + +### 集群拓扑感知 + +让 PD 感知不同节点分布的拓扑是为了通过调度使不同 Region 的各个副本尽可能分散，保证高可用和容灾。PD 会在后台不断扫描所有 Region，当发现 Region 的分布不是当前的最优化状态时，会生成调度以替换 Peer，将 Region 调整至最佳状态。 + +负责这个检查的组件叫 `replicaChecker`（跟 Scheduler 类似，但是不可关闭）。它依赖于 `location-labels` 配置项来进行调度。比如配置 `[zone,rack,host]` 定义了三层的拓扑结构：集群分为多个 zone（可用区），每个 zone 下有多个 rack（机架），每个 rack 下有多个 host（主机）。PD 在调度时首先会尝试将 Region 的 Peer 放置在不同的 zone，假如无法满足（比如配置 3 副本但总共只有 2 个 zone）则保证放置在不同的 rack；假如 rack 的数量也不足以保证隔离，那么再尝试 host 级别的隔离，以此类推。 + +### 缩容及故障恢复 + +缩容是指预备将某个 Store 下线，通过命令将该 Store 标记为 “Offline“ 状态，此时 PD 通过调度将待下线节点上的 Region 迁移至其他节点。 + +故障恢复是指当有 Store 发生故障且无法恢复时，有 Peer 分布在对应 Store 上的 Region 会产生缺少副本的状况，此时 PD 需要在其他节点上为这些 Region 补副本。 + +这两种情况的处理过程基本上是一样的。`replicaChecker` 检查到 Region 存在异常状态的 Peer后，生成调度在健康的 Store 上创建新副本替换异常的副本。 + +### Region merge + +Region merge 指的是为了避免删除数据后大量小甚至空的 Region 消耗系统资源，通过调度把相邻的小 Region 合并的过程。Region merge 由 `mergeChecker` 负责，其过程与 `replicaChecker` 类似：PD 在后台遍历，发现连续的小 Region 后发起调度。 + +## 查询调度状态 + +你可以通过观察 PD 相关的 Metrics 或使用 pd-ctl 工具等方式查看调度系统状态。更具体的信息可以参考 [PD 监控](/reference/key-monitoring-metrics/pd-dashboard.md)和 [PD Control](/reference/tools/pd-control.md)。 + +### Operator 状态 + +**Grafana PD/Operator** 页面展示了 Operator 的相关统计信息。其中比较重要的有： + +- Schedule Operator Create：Operator 的创建情况 +- Operator finish duration：Operator 执行耗时的情况 +- Operator Step duration：不同 Operator Step 执行耗时的情况 + +查询 Operator 的 pd-ctl 命令有： + +- `operator show`：查询当前调度生成的所有 Operator +- `operator show [admin | leader | region]`：按照类型查询 Operator + +### Balance 状态 + +**Grafana PD/Statistics - Balance** 页面展示了负载均衡的相关统计信息，其中比较重要的有： + +- Store Leader/Region score：每个 Store 的得分 +- Store Leader/Region count：每个 Store 的 Leader/Region 数量 +- Store available：每个 Store 的剩余空间 + +使用 pd-ctl 的 `store` 命令可以查询 Store 的得分、数量、剩余空间和 weight 等信息。 + +### 热点调度状态 + +**Grafana PD/Statistics - hotspot** 页面展示了热点 Region 的相关统计信息，其中比较重要的有： + +- Hot write Region’s leader/peer distribution：写热点 Region 的 Leader/Peer 分布情况 +- Hot read Region’s leader distribution：读热点 Region 的 Leader 分布情况 + +使用 pd-ctl 同样可以查询上述信息，可以使用的命令有： + +- `hot read`：查询读热点 Region 信息 +- `hot write`：查询写热点 Region 信息 +- `hot store`：按 Store 统计热点分布情况 +- `region topread [limit]`：查询当前读流量最大的 Region +- `region topwrite [limit]`：查询当前写流量最大的 Region + +### Region 健康度 + +**Grafana PD/Cluster/Region health** 面板展示了异常 Region 的相关统计信息，包括 Pending Peer、Down Peer、Offline Peer，以及副本数过多或过少的 Region。 + +通过 pd-ctl 的 `region check` 命令可以查看具体异常的 Region 列表： + +- `region check miss-peer`：缺副本的 Region +- `region check extra-peer`：多副本的 Region +- `region check down-peer`：有副本状态为 Down 的 Region +- `region check pending-peer`：有副本状态为 Pending 的 Region + +## 调度策略控制 + +使用 pd-ctl 可以从以下三个方面来调整 PD 的调度策略。更具体的信息可以参考 [PD Control](/reference/tools/pd-control.md)。 + +### 启停调度器 + +pd-ctl 支持动态创建和删除 Scheduler，你可以通过这些操作来控制 PD 的调度行为，如： + +- `scheduler show`：显示当前系统中的 Scheduler +- `scheduler remove balance-leader-scheduler`：删除（停用）balance region 调度器 +- `scheduler add evict-leader-scheduler-1`：添加移除 Store 1 的所有 Leader 的调度器 + +### 手动添加 Operator + +PD 支持直接通过 pd-ctl 来创建或删除 Operator，如： + +- `operator add add-peer 2 5`：在 Store 5 上为 Region 2 添加 Peer +- `operator add transfer-leader 2 5`：将 Region 2 的 Leader 迁移至 Store 5 +- `operator add split-region 2`：将 Region 2 拆分为 2 个大小相当的 Region +- `operator remove 2`：取消 Region 2 当前待执行的 Operator + +### 调度参数调整 + +使用 pd-ctl 执行 `config show` 命令可以查看所有的调度参数，执行 `config set {key} {value}` 可以调整对应参数的值。常见调整如下： + +- `leader-schedule-limit`：控制 Transfer Leader 调度的并发数 +- `region-schedule-limit`：控制增删 Peer 调度的并发数 +- `disable-replace-offline-replica`：停止处理节点下线的调度 +- `disable-location-replacement`：停止处理调整 Region 隔离级别相关的调度 +- `max-snapshot-count`：每个 Store 允许的最大收发 Snapshot 的并发数 + +## 典型场景分析与处理 + +该部分通过几个典型场景及其应对方式说明 PD 调度策略的最佳实践。 + +### Leader/Region 分布不均衡 + +PD 的打分机制决定了一般情况下，不同 Store 的 Leader Count 和 Region Count 不能完全说明负载均衡状态，所以需要从 TiKV 的实际负载或者存储空间占用来判断是否有负载不均衡的状况。 + +确认 Leader/Region 分布不均衡后，首先观察不同 Store 的打分情况。 + +如果不同 Store 的打分是接近的，说明 PD 认为此时已经是均衡状态了，可能的原因有： + +- 存在热点导致负载不均衡。可以参考[热点分布不均匀](#热点分布不均匀)中的解决办法进行分析处理。 +- 存在大量空 Region 或小 Region，因此不同 Store 的 Leader 数量差别特别大，导致 Raftstore 负担过重。此时需要开启 [Region Merge](#region-merge) 并尽可能加速合并。 +- 不同 Store 的软硬件环境存在差异。可以酌情调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 +- 其他不明原因。仍可以通过调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 + +如果不同 Store 的分数差异较大，需要进一步检查 Operator 的相关 Metrics，特别关注 Operator 的生成和执行情况，这时大体上又分两种情况： + +- 生成的调度是正常的，但是调度的速度很慢。可能的原因有： + + - 调度速度受限于 limit 配置。PD 默认配置的 limit 比较保守，在不对正常业务造成显著影响的前提下，可以酌情将 `leader-schedule-limit` 或 `region-schedule-limit` 调大一些。此外， `max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 + - 系统中同时运行有其他的调度任务产生竞争，导致 balance 速度上不去。这种情况下如果 balance 调度的优先级更高，可以先停掉其他的调度或者限制其他调度的速度。例如 Region 没均衡的情况下做下线节点操作，下线的调度与 Region Balance 会抢占 `region-schedule-limit` 配额，此时你可以调小 `replica-schedule-limit` 以限制下线调度的速度，或者设置 `disable-replace-offline-replica = true` 来暂时关闭下线流程。 + - 调度执行得太慢。可以通过 **Operator step duration** 进行判断。通常不涉及到收发 Snapshot 的 Step（比如 `TransferLeader`，`RemovePeer`，`PromoteLearner` 等）的完成时间应该在毫秒级，涉及到 Snapshot 的 Step（如 `AddLearner`，`AddPeer` 等）的完成时间为数十秒。如果耗时明显过高，可能是 TiKV 压力过大或者网络等方面的瓶颈导致的，需要具体情况具体分析。 + +- 没能生成对应的 balance 调度。可能的原因有： + + - 调度器未被启用。比如对应的 Scheduler 被删除了，或者 limit 被设置为 “0”。 + - 由于其他约束无法进行调度。比如系统中有 `evict-leader-scheduler`，此时无法把 Leader 迁移至对应的 Store。再比如设置了 Label property，也会导致部分 Store 不接受 Leader。 + - 集群拓扑的限制导致无法均衡。比如 3 副本 3 数据中心的集群，由于副本隔离的限制，每个 Region 的 3 个副本都分别分布在不同的数据中心，假如这 3 个数据中心的 Store 数不一样，最后调度就会收敛在每个数据中心均衡，但是全局不均衡的状态。 + +### 节点下线速度慢 + +这个场景需要从 Operator 相关的 Metrics 入手，分析 Operator 的生成执行情况。 + +如果调度在正常生成，只是速度很慢，可能的原因有： + +- 调度速度受限于 limit 配置。可以适当调大 `replica-schedule-limit`，`max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 +- 系统中同时运行有其他的调度任务产生竞争。处理方法参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡)。 +- 下线单个节点时，由于待操作的 Region 有很大一部分（3 副本配置下约 1/3）的 Leader 都集中在下线的节点上，下线速度会受限于这个单点生成 Snapshot 的速度。你可以通过手动给该节点添加一个 `evict-leader-scheduler` 调度器迁走 Leader 来加速。 + +如果没有对应的 Operator 调度生成，可能的原因有： + +- 下线调度被关闭，或者 `replica-schedule-limit` 被设为 “0”。 +- 找不到节点来转移 Region。例如相同 Label 的替代节点可用容量都不足 20%，PD 为了避免爆盘的风险会停止调度。这种情况需要添加更多节点，或者删除一些数据释放空间。 + +### 节点上线速度慢 + +目前 PD 没有对节点上线特殊处理。节点上线实际上是依靠 balance region 机制来调度的，所以参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡) 中的排查步骤即可。 + +### 热点分布不均匀 + +热点调度的问题大体上可以分为以下几种情况： + +- 从 PD 的 Metrics 能看出来有不少 hot Region，但是调度速度跟不上，不能及时地把热点 Region 分散开来。 + + **解决方法**：调大 `hot-region-schedule-limit` 并减少其他调度器的 limit 配额，从而加快热点调度的速度。还可调小 `hot-region-cache-hits-threshold` 使 PD 对更快响应流量的变化。 + +- 单一 Region 形成热点，比如大量请求频繁 scan 一个小表，这个可以从业务角度或者 Metrics 统计的热点信息看出来。由于单 Region 热点现阶段无法使用打散的手段来消除，需要确认热点 Region 后手动添加 `split-region` 调度将这样的 Region 拆开。 + +- 从 PD 的统计来看没有热点，但是从 TiKV 的相关 Metrics 可以看出部分节点负载明显高于其他节点，成为整个系统的瓶颈。这是因为目前 PD 统计热点 Region 的维度比较单一，仅针对流量进行分析，在某些场景下无法准确定位热点。例如部分 Region 有大量的点查请求，从流量上来看并不显著，但是过高的 QPS 导致关键模块达到瓶颈。 + + **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) 文档。 + +### Region Merge 速度慢 + +Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-schedule-limit` 及 `region-schedule-limit`），或者是与其他调度器产生了竞争。具体来说，可有如下处理方式： + +- 假如已经从相关 Metrics 得知系统中有大量的空 Region，这时可以通过把 `max-merge-region-size` 和 `max-merge-region-keys` 调整为较小值来加快 Merge 速度。这是因为 Merge 的过程涉及到副本迁移，所以 Merge 的 Region 越小，速度就越快。如果生成 Merge Operator 的速度很快，想进一步加快 Region Merge 过程，还可以把 `patrol-region-interval` 调整为 "10ms" ，这个能加快巡检 Region 的速度，但是会消耗更多的 CPU 资源。 + +- 创建过大量 Table 后（包括执行 `Truncate Table` 操作）又清空了。此时如果开启了 split table 特性，这些空 Region 是无法合并的，此时需要调整以下参数关闭这个特性： + + - TiKV: `split-region-on-table` 设为 false + - PD: `namespace-classifier` 设为 “” + +- 对于 3.0.4 和 2.1.16 以前的版本，Region 中 Key 的个数（`approximate_keys`）在特定情况下（大部分发生在删表之后）统计不准确，造成 keys 的统计值很大，无法满足 `max-merge-region-keys` 的约束。你可以通过调大 `max-merge-region-keys` 来避免这个问题。 + +### TiKV 节点故障处理策略 + +没有人工介入时，PD 处理 TiKV 节点故障的默认行为是，等待半小时之后（可通过 `max-store-down-time` 配置调整），将此节点设置为 Down 状态，并开始为涉及到的 Region 补充副本。 + +实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 diff --git a/reference/configuration/pd-server/configuration-file.md b/reference/configuration/pd-server/configuration-file.md new file mode 100644 index 000000000000..f48fc52158b8 --- /dev/null +++ b/reference/configuration/pd-server/configuration-file.md @@ -0,0 +1,265 @@ +--- +title: PD 配置文件描述 +category: reference +--- + +# PD 配置文件描述 + + + +PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/config.toml](https://github.com/pingcap/pd/blob/master/conf/config.toml) 找到默认的配置文件。 + +本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [PD 配置参数](/reference/configuration/pd-server/configuration.md)。 + +### `lease` + ++ PD Leader Key 租约超时时间，超时系统重新选举 Leader。 ++ 默认：3 ++ 单位：秒 + +### `tso-save-interval` + ++ TSO 分配的时间窗口,实时持久存储。 ++ 默认：3s + +### `initial-cluster-state` + ++ 集群初始状态 ++ 默认：new + +### `enable-prevote` + ++ 开启 raft prevote 的开关。 ++ 默认：true + +### `quota-backend-bytes` + ++ 元信息数据库存储空间的大小，默认 2GB。 ++ 默认：2147483648 + +### `auto-compaction-mod` + ++ 元信息数据库自动压缩的模式，可选项为 periodic（按周期），revision（按版本数）。 ++ 默认：periodic + +### `auto-compaction-retention` + ++ compaction-mode 为 periodic 时为元信息数据库自动压缩的间隔时间；compaction-mode 设置为 revision 时为自动压缩的版本数。 ++ 默认：1h + +### `force-new-cluster` + ++ 强制让该 PD 以一个新集群启动，且修改 raft 成员数为 1。 ++ 默认：false + +### `tick-interval` + ++ etcd raft 的 tick 周期。 ++ 默认：100ms + +### `election-interval` + ++ etcd leader 选举的超时时间。 ++ 默认：3s + +### `use-region-storage` + ++ 开启独立的 region 存储。 ++ 默认：false + +## security + +安全相关配置项。 + +### `cacert-path` + ++ CA 文件路径 ++ 默认："" + +### `cert-path` + ++ 包含 X509 证书的 PEM 文件路径 ++ 默认："" + +### `key-path` + ++ 包含 X509 key 的 PEM 文件路径 ++ 默认："" + +## log + +日志相关的配置项。 + +### `format` + ++ 日志格式，可指定为"text"，"json"， "console"。 ++ 默认：text + +### `disable-timestamp` + ++ 是否禁用日志中自动生成的时间戳。 ++ 默认：false + +## log.file + +日志文件相关的配置项。 + +### `max-size` + ++ 单个日志文件最大大小，超过该值系统自动切分成多个文件。 ++ 默认：300 ++ 单位：MiB ++ 最小值为 1 + +### `max-days` + ++ 日志保留的最长天数。 ++ 默认: 28 ++ 最小值为 1 + +### `max-backups` + ++ 日志文件保留的最大个数。 ++ 默认: 7 ++ 最小值为 1 + +## metric + +监控相关的配置项。 + +### `interval` + ++ 向 promethus 推送监控指标数据的间隔时间。 ++ 默认: 15s + +## schedule + +调度相关的配置项。 + +### `max-merge-region-size` + ++ 控制 Region Merge 的 size 上限，当 Region Size 大于指定值时 PD 不会将其与相邻的 Region 合并。 ++ 默认: 20 + +### `max-merge-region-keys` + ++ 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 ++ 默认: 200000 + +### `patrol-region-interval` + ++ 控制 replicaChecker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整 ++ 默认: 100ms + +### `split-merge-interval` + ++ 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。 ++ 默认: 1h + +### `max-snapshot-count` + ++ 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。 ++ 默认: 3 + +### `max-pending-peer-count` + ++ 控制单个 store 的 pending peer 上限，调度受制于这个配置来防止在部分节点产生大量日志落后的 Region。 ++ 默认：16 + +### `max-store-down-time` + ++ PD 认为失联 store 无法恢复的时间，当超过指定的时间没有收到 store 的心跳后，PD 会在其他节点补充副本。 ++ 默认：30m + +### `leader-schedule-limit` + ++ 同时进行 leader 调度的任务个数。 ++ 默认：4 + +### `region-schedule-limit` + ++ 同时进行 Region 调度的任务个数 ++ 默认：4 + +### `replica-schedule-limit` + ++ 同时进行 replica 调度的任务个数。 ++ 默认：8 + +### `merge-schedule-limit` + ++ 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 ++ 默认：8 + +### `high-space-ratio` + ++ 设置 store 空间充裕的阈值。 ++ 默认：0.6 ++ 最小值：大于 0 ++ 最大值：小于 1 + +### `low-space-ratio` + ++ 设置 store 空间不足的阈值。 ++ 默认：0.8 ++ 最小值：大于 0 ++ 最大值：小于 1 + +### `tolerant-size-ratio` + ++ 控制 balance 缓冲区大小。 ++ 默认：5 ++ 最小值：0 + +### `disable-remove-down-replica` + ++ 关闭自动删除 DownReplica 的特性的开关，当设置为 true 时，PD 不会自动清理宕机状态的副本。 ++ 默认：false + +### `disable-replace-offline-replica` + ++ 关闭迁移 OfflineReplica 的特性的开关，当设置为 true 时，PD 不会迁移下线状态的副本。 ++ 默认：false + +### `disable-make-up-replica` + ++ 关闭补充副本的特性的开关，当设置为 true 时，PD 不会为副本数不足的 Region 补充副本。 ++ 默认：false + +### `disable-remove-extra-replica` + ++ 关闭删除多余副本的特性开关，当设置为 true 时，PD 不会为副本数过多的 Region 删除多余副本。 ++ 默认：false + +### `disable-location-replacement` + ++ 关闭隔离级别检查的开关，当设置为 true 时，PD 不会通过调度来提升 Region 副本的隔离级别。 ++ 默认：false + +## replication + +副本相关的配置项。 + +### `max-replicas` + ++ 副本数量。 ++ 默认：3 + +### `location-labels` + ++ TiKV 集群的拓扑信息。 ++ 默认：[] + +## label-property + +标签相关的配置项。 + +### `key` + ++ 拒绝 leader 的 store 带有的 label key。 ++ 默认："" + +### `value` + ++ 拒绝 leader 的 store 带有的 label value。 ++ 默认："" diff --git a/dev/reference/configuration/pd-server/configuration.md b/reference/configuration/pd-server/configuration.md similarity index 100% rename from dev/reference/configuration/pd-server/configuration.md rename to reference/configuration/pd-server/configuration.md diff --git a/reference/configuration/tidb-server/configuration-file.md b/reference/configuration/tidb-server/configuration-file.md new file mode 100644 index 000000000000..8538f68a9a41 --- /dev/null +++ b/reference/configuration/tidb-server/configuration-file.md @@ -0,0 +1,444 @@ +--- +title: TiDB 配置文件描述 +category: reference +--- + + + +# TiDB 配置文件描述 + +TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/config.toml.example](https://github.com/pingcap/tidb/blob/master/config/config.toml.example) 找到默认值的配置文件，重命名为 `config.toml` 即可。本文档只介绍未包含在[命令行参数](https://pingcap.com/docs-cn/dev/reference/configuration/tidb-server/configuration)中的参数。 + +### `split-table` + ++ 为每个 table 建立单独的 Region。 ++ 默认值：true ++ 如果需要创建大量的表，我们建议把这个参数设置为 false。 + +### `oom-action` + ++ 指定 TiDB 发生 out-of-memory 错误时的操作。 ++ 默认值："log" ++ 现在合法的选项是 ["log", "cancel"]，如果为 "log"，仅仅是打印日志，不作实质处理。如果为 "cancel"，我们会取消执行这个操作，并且输出日志。 + +### `mem-quota-query` + ++ 单条 SQL 语句可以占用的最大内存阈值。 ++ 默认值：34359738368 ++ 超过该值的请求会被 `oom-action` 定义的行为所处理。 + +### `enable-streaming` + ++ 开启 coprocessor 的 streaming 获取数据模式。 ++ 默认值：false + +### `lower-case-table-names` + ++ 这个选项可以设置 TiDB 的系统变量 `lower_case_table_names` 的值。 ++ 默认值：2 ++ 具体可以查看 MySQL 关于这个变量的[描述](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_lower_case_table_names) + +> **注意：** +> +> 目前 TiDB 只支持将该选项的值设为 2，即按照大小写来保存表名，按照小写来比较（不区分大小写）。 + +### `lease` + ++ DDL 租约超时时间。 ++ 默认值：45s ++ 单位：秒 + +### `compatible-kill-query` + ++ 设置 `KILL` 语句的兼容性。 ++ 默认值：false ++ TiDB 中 `KILL xxx` 的行为和 MySQL 中的行为不相同。为杀死一条查询，在 TiDB 里需要加上 `TIDB` 关键词，即 `KILL TIDB xxx`。但如果把 `compatible-kill-query` 设置为 true，则不需要加上 `TIDB` 关键词。 ++ 这种区别很重要，因为当用户按下 Ctrl+C 时，MySQL 命令行客户端的默认行为是：创建与后台的新连接，并在该新连接中执行 `KILL` 语句。如果负载均衡器或代理已将该新连接发送到与原始会话不同的 TiDB 服务器实例，则该错误会话可能被终止，从而导致使用 TiDB 集群的业务中断。只有当您确定在 `KILL` 语句中引用的连接正好位于 `KILL` 语句发送到的服务器上时，才可以启用 `compatible-kill-query`。 + +### `check-mb4-value-in-utf8` + ++ 开启检查 utf8mb4 字符的开关，如果开启此功能，字符集是 utf8，且在 utf8 插入 mb4 字符，系统将会报错。 ++ 默认值：true + +### `treat-old-version-utf8-as-utf8mb4` + ++ 将旧表中的 utf8 字符集当成 utf8mb4的开关。 ++ 默认值：true + +### `alter-primary-key` + ++ 用于控制添加或者删除主键功能。 ++ 默认值：false ++ 默认情况下，不支持增删主键。将此变量被设置为 true 后，支持增删主键功能。不过对在此开关开启前已经存在的表，且主键是整型类型时，即使之后开启此开关也不支持对此列表删除主键。 + +### `repair-mode` + ++ 用于开启非可信修复模式，启动该模式后，可以过滤 `repair-table-list` 名单中坏表的加载。 ++ 默认值：false ++ 默认情况下，不支持修复语法，默认启动时会加载所有表信息。 + +### `repair-table-list` + ++ 配合 `repair-mode` 为 true 时使用，用于列出实例中需要修复的坏表的名单，该名单的写法为 ["db.table1","db.table2"...]。 ++ 默认值：[] ++ 默认情况下，该 list 名单为空，表示没有所需修复的坏表信息。 + +## log + +日志相关的配置项。 + +### `format` + ++ 指定日志输出的格式，可选项为 [json, text, console]。 ++ 默认值："text" + +### `enable-timestamp` + ++ 是否在日志中输出时间戳。 ++ 默认值：true ++ 如果设置为 false，那么日志里面将不会输出时间戳。 + +> **注意：** +> +> 考虑后向兼容性，原来的配置项 `disable-timestamp` 仍然有效，但如果和 `enable-timestamp` 配置的值在语义上冲突（例如在配置中把 `enable-timestamp` 和 `disable-timestamp` 同时设置为 `true`），则 TiDB 会忽略 `disable-timestamp` 的值。在未来的版本中，`disable-timestamp` 配置项将被彻底移除，请废弃 `disable-timestamp` 的用法，使用语义上更易于理解的 `enable-timestamp`。 + +### `slow-query-file` + ++ 慢查询日志的文件名。 ++ 默认值："tidb-slow.log"，注：由于 TiDB V2.1.8 更新了慢日志格式，所以将慢日志单独输出到了慢日志文件。V2.1.8 之前的版本，该变量的默认值是 ""。 ++ 设置后，慢查询日志会单独输出到该文件。 + +### `slow-threshold` + ++ 输出慢日志的耗时阈值。 ++ 默认值：300ms ++ 当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。 + +### `expensive-threshold` + ++ 输出 `expensive` 操作的行数阈值。 ++ 默认值：10000 ++ 当查询的行数（包括中间结果，基于统计信息）大于这个值，我们就会当成是一个 `expensive` 的操作，输出一个前缀带有 `[EXPENSIVE_QUERY]` 的日志。 + +### `query-log-max-len` + ++ 最长的 SQL 输出长度。 ++ 默认值：2048 ++ 当语句的长度大于 `query-log-max-len`，将会被截断输出。 + +### `max-server-connections` + ++ TiDB 中同时允许的最大客户端连接数，用于资源控制。 ++ 默认值：4096 ++ 当客户端连接数到达 `max-server-connections` 时，TiDB 服务端将会拒绝新的客户端连接。 + +## log.file + +日志文件相关的配置项。 + +#### `filename` + ++ 一般日志文件名字。 ++ 默认值："" ++ 如果设置，会输出一般日志到这个文件。 + +#### `max-size` + ++ 日志文件的大小限制。 ++ 默认值：300MB ++ 最大设置上限为 4GB。 + +#### `max-days` + ++ 日志最大保留的天数。 ++ 默认值：0 ++ 默认不清理；如果设置了参数值，在 `max-days` 之后 TiDB 会清理过期的日志文件。 + +#### `max-backups` + ++ 保留的日志的最大数量。 ++ 默认值：0 ++ 默认全部保存；如果设置为 7，会最多保留 7 个老的日志文件。 + +#### `log-rotate` + ++ 是否每日创建一个新的日志文件。 ++ 默认值：true ++ 如果设置为 true，每天会新建新的日志文件，如果设置为 false，那么只会输出到一个日志文件。 + +## security + +安全相关配置。 + +### `ssl-ca` + ++ PEM 格式的受信任 CA 的证书文件路径。 ++ 默认值："" ++ 当同时设置了该选项和 `--ssl-cert`、`--ssl-key` 选项时，TiDB 将在客户端出示证书的情况下根据该选项指定的受信任的 CA 列表验证客户端证书。若验证失败，则连接会被终止。 ++ 即使设置了该选项，若客户端没有出示证书，则安全连接仍然继续，不会进行客户端证书验证。 + +### `ssl-cert` + ++ PEM 格式的 SSL 证书文件路径。 ++ 默认值："" ++ 当同时设置了该选项和 `--ssl-key` 选项时，TiDB 将接受（但不强制）客户端使用 TLS 安全地连接到 TiDB。 ++ 若指定的证书或私钥无效，则 TiDB 会照常启动，但无法接受安全连接。 + +### `ssl-key` + ++ PEM 格式的 SSL 证书密钥文件路径，即 `--ssl-cert` 所指定的证书的私钥。 ++ 默认值："" ++ 目前 TiDB 不支持加载由密码保护的私钥。 + +### `cluster-ssl-ca` + ++ CA 根证书，用于用 tls 连接 TiKV/PD ++ 默认值："" + +### `cluster-ssl-cert` + ++ ssl 证书文件路径，用于用 tls 连接 TiKV/PD ++ 默认值："" + +### `cluster-ssl-key` + ++ ssl 私钥文件路径，用于用 tls 连接 TiKV/PD ++ 默认值："" + +### `skip-grant-table` + ++ 是否跳过权限检查 ++ 默认值：false + +## performance + +性能相关配置。 + +### `max-procs` + ++ TiDB 的 CPU 使用数量。 ++ 默认值：0 ++ 默认值为 0 表示使用机器上所有的 CPU；如果设置成 n，那么 TiDB 会使用 n 个 CPU 数量。 + +### `max-memory` + ++ Prepare cache LRU 使用的最大内存限制，超过 performance.max-memory * (1 - prepared-plan-cache.memory-guard-ratio)会 剔除 LRU 中的元素。 ++ 默认值：0 ++ 这个配置只有在 prepared-plan-cache.enabled 为 true 的情况才会生效。在 LRU 的 size 大于 prepared-plan-cache.capacity 的情况下，也会剔除 LRU 中的元素。 + +### `stmt-count-limit` + ++ TiDB 一个事务允许的最大语句条数限制。 ++ 默认值：5000 ++ 在一个事务中，超过 `stmt-count-limit` 条语句后还没有 rollback 或者 commit，TiDB 将会返回 `statement count 5001 exceeds the transaction limitation, autocommit = false` 错误。 + +### `tcp-keep-alive` + ++ TiDB 在 TCP 层开启 keepalive。 ++ 默认值：false + +### `cross-join` + ++ 默认值：true ++ 默认可以执行在做 join 时两边表没有任何条件（where 字段）的语句；如果设置为 false，则有这样的 join 语句出现时，server 会拒绝执行 + +### `stats-lease` + ++ TiDB 重载统计信息，更新表行数，检查是否需要自动 analyze，利用 feedback 更新统计信息以及加载列的统计信息的时间间隔。 ++ 默认值：3s + - 每隔 `stats-lease` 时间，TiDB 会检查统计信息是否有更新，如果有会将其更新到内存中 + - 每隔 `20 * stats-lease` 时间，TiDB 会将 DML 产生的总行数以及修改的行数变化更新到系统表中 + - 每隔 `stats-lease` 时间，TiDB 会检查是否有表或者索引需要自动 analyze + - 每隔 `stats-lease` 时间，TiDB 会检查是否有列的统计信息需要被加载到内存中 + - 每隔 `200 * stats-lease` 时间，TiDB 会将内存中缓存的 feedback 写入系统表中 + - 每隔 `5 * stats-lease` 时间，TiDB 会读取系统表中的 feedback，更新内存中缓存的统计信息 ++ 当 `stats-lease` 为 0 时，TiDB 会以 3s 的时间间隔周期性的读取系统表中的统计信息并更新内存中缓存的统计信息。但不会自动修改统计信息相关系统表，具体来说，TiDB 不再自动修改这些表： + - `mysql.stats_meta`：TiDB 不再自动记录事务中对某张表的修改行数，也不会更新到这个系统表中 + - `mysql.stats_histograms`/`mysql.stats_buckets` 和 `mysql.stats_top_n`：TiDB 不再自动 analyze 和主动更新统计信息 + - `mysql.stats_feedback`：TiDB 不再根据被查询的数据反馈的部分统计信息更新表和索引的统计信息 + +### `run-auto-analyze` + ++ TiDB 是否做自动的 Analyze。 ++ 默认值：true + +### `feedback-probability` + ++ TiDB 对查询收集统计信息反馈的概率。 ++ 默认值：0.05 ++ 对于每一个查询，TiDB 会以 `feedback-probability` 的概率收集查询的反馈，用于更新统计信息。 + +### `query-feedback-limit` + ++ 在内存中缓存的最大 Query Feedback 数量，超过这个数量的 Feedback 会被丢弃。 ++ 默认值：1024 + +### `pseudo-estimate-ratio` + ++ 修改过的行数/表的总行数的比值，超过该值时系统会认为统计信息已经过期，会采用 pseudo 的统计信息。 ++ 默认值：0.8 ++ 最小值为 0；最大值为 1。 + +### `force-priority` + ++ 把所有的语句优先级设置为 force-priority 的值。 ++ 默认值：NO_PRIORITY ++ 可选值：NO_PRIORITY, LOW_PRIORITY, HIGH_PRIORITY, DELAYED。 + +## prepared-plan-cache + +prepare 语句的 Plan cache 设置。 + +### `enabled` + ++ 开启 prepare 语句的 plan cache。 ++ 默认值：false + +### `capacity` + ++ 缓存语句的数量。 ++ 默认值：100 + +### `memory-guard-ratio` + ++ 用于防止超过 performance.max-memory, 超过 max-proc * (1 - prepared-plan-cache.memory-guard-ratio)会剔除 LRU 中的元素。 ++ 默认值：0.1 ++ 最小值为 0；最大值为 1。 + +## tikv-client + +### `grpc-connection-count` + ++ 跟每个 TiKV 之间建立的最大连接数。 ++ 默认值：16 + +### `grpc-keepalive-time` + ++ TiDB 与 TiKV 节点之间 rpc 连接 keepalive 时间间隔，如果超过该值没有网络包，grpc client 会 ping 一下 TiKV 查看是否存活。 ++ 默认值：10 ++ 单位：秒 + +### `grpc-keepalive-timeout` + ++ TiDB 与 TiKV 节点 rpc keepalive 检查的超时时间 ++ 默认值：3 ++ 单位：秒 + +### `commit-timeout` + ++ 执行事务提交时，最大的超时时间。 ++ 默认值：41s ++ 这个值必须是大于两倍 Raft 选举的超时时间。 + +### `max-txn-time-use` + ++ 单个事务允许的最大执行时间。 ++ 默认值：590 ++ 单位：秒 + +### `max-batch-size` + ++ 批量发送 rpc 封包的最大数量，如果不为 0，将使用 BatchCommands api 发送请求到 TiKV，可以在并发度高的情况降低 rpc 的延迟，推荐不修改该值。 ++ 默认值：128 + +### `max-batch-wait-time` + ++ 等待 `max-batch-wait-time` 纳秒批量将此期间的数据包封装成一个大包发送给 TiKV 节点，仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 ++ 默认值：0 ++ 单位：纳秒 + +### `batch-wait-size` + ++ 批量向 TiKV 发送的封包最大数量，不推荐修改该值。 ++ 默认值：8 ++ 若此值为 0 表示关闭此功能。 + +### `overload-threshold` + ++ TiKV 的负载阈值，如果超过此阈值，会收集更多的 batch 封包，来减轻 TiKV 的压力。仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 ++ 默认值：200 + +## txn-local-latches + +事务内存锁相关配置，当本地事务冲突比较多时建议开启。 + +### `enable` + ++ 开启或关闭事务内存锁 ++ 默认值：false + +### `capacity` + ++ Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。 ++ 默认值：2048000 + +## binlog + +TiDB Binlog 相关配置。 + +### `enable` + ++ binlog 开关。 ++ 默认值：false + +### `write-timeout` + ++ 写 binlog 的超时时间，推荐不修改该值。 ++ 默认值：15s ++ 单位：秒 + +### `ignore-error` + ++ 忽略写 binlog 发生的错误时处理开关，推荐不修改该值。 ++ 默认值：false ++ 如果设置为 `true`，发生错误时，TiDB 会停止写入 binlog，并且在监控项 `tidb_server_critical_error_total` 上计数加 1；如果设置为 `false`，写入 binlog 失败，会停止整个 TiDB 的服务。 + +### `binlog-socket` + ++ binlog 输出网络地址。 ++ 默认值："" + +### `strategy` + ++ binlog 输出时选择 pump 的策略，仅支持 hash，range 方法。 ++ 默认值："range" + +## status + +TiDB 服务状态相关配置。 + +### `report-status` + ++ 开启 HTTP API 服务的开关。 ++ 默认值：true + +### `record-db-qps` + ++ 输与 database 相关的 QPS metrics 到 Prometheus 的开关。 ++ 默认值：false + +## stmt-summary 从 v3.0.4 版本开始引入 + +系统表 `events_statement_summary_by_digest` 的相关配置。 + +### max-stmt-count + ++ `events_statement_summary_by_digest` 表中保存的 SQL 种类的最大数量。 ++ 默认值：100 + +### max-sql-length + ++ `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 ++ 默认值：4096 + +## pessimistic-txn + +### enable + ++ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/reference/transactions/transaction-pessimistic.md)。 ++ 默认值：true + +### max-retry-count + ++ 悲观事务中每个语句最大重试次数，超出该限制将会报错。 ++ 默认值：256 diff --git a/reference/configuration/tidb-server/configuration.md b/reference/configuration/tidb-server/configuration.md new file mode 100644 index 000000000000..53d12b0337a0 --- /dev/null +++ b/reference/configuration/tidb-server/configuration.md @@ -0,0 +1,145 @@ +--- +title: TiDB 配置参数 +category: reference +--- + +# TiDB 配置参数 + +在启动 TiDB 时，你可以使用命令行参数或环境变量来配置 TiDB。本文将详细介绍 TiDB 的命令行启动参数。TiDB 的默认端口为 4000（客户端请求）与 10080（状态报告）。 + +## `--advertise-address` + ++ 登录 TiDB 的 IP 地址 ++ 默认："" ++ 必须确保用户和集群中的其他机器都能够访问到该 IP 地址 + +## `--binlog-socket` + ++ TiDB 服务使用 unix socket file 方式接受内部连接，如 Pump 服务 ++ 默认："" ++ 例如，可以使用 "/tmp/pump.sock" 来接受 Pump unix socket file 通信 + +## `--config` + ++ 配置文件 ++ 默认："" ++ 如果你指定了配置文件，TiDB 会首先读取配置文件的配置。如果对应的配置在命令行参数里面也存在，TiDB 就会使用命令行参数的配置来覆盖配置文件中的配置。详细的配置项请参阅 [TiDB 配置文件描述](/reference/configuration/tidb-server/configuration-file.md)。 + +## `--cors` + ++ 用于设置 TiDB HTTP 状态服务的 Access-Control-Allow-Origin ++ 默认："" + +## `--host` + ++ TiDB 服务监听的 host ++ 默认："0.0.0.0" ++ 0.0.0.0 默认会监听所有的网卡地址。如果有多块网卡，可以指定对外提供服务的网卡，如 192.168.100.113 + +## `-L` + ++ Log 级别 ++ 默认："info" ++ 可选项为：debug、info、warn、error、fatal + +## `--log-file` + ++ Log 文件 ++ 默认："" ++ 如果未设置该参数，log 会默认输出到 "stderr"；如果设置了该参数，log 会输出到对应的文件中。每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 + +## `--log-slow-query` + ++ 慢查询日志文件路径 ++ 默认："" ++ 如果未设置该参数，log 会默认输出到 `--log-file` 指定的文件中 + +## `--metrics-addr` + ++ Prometheus Pushgateway 地址 ++ 默认："" ++ 如果该参数为空，TiDB 不会将统计信息推送给 Pushgateway。参数格式示例：`--metrics-addr=192.168.100.115:9091` + +## `--metrics-interval` + ++ 推送统计信息到 Prometheus Pushgateway 的时间间隔 ++ 默认：15s ++ 设置为 0 表示不推送统计信息给 Pushgateway。示例：`--metrics-interval=2` 指每两秒推送到 Pushgateway + +## `-P` + ++ TiDB 服务监听端口 ++ 默认："4000" ++ TiDB 服务会使用该端口接受 MySQL 客户端发来的请求 + +## `--path` + ++ 对于本地存储引擎 "mocktikv" 来说，path 指定的是实际的数据存放路径 ++ 当 `--store = tikv` 时，必须指定 path；当 `--store = mocktikv` 时，如果不指定 path，会使用默认值。 ++ 对于 "TiKV" 存储引擎来说，path 指定的是实际的 PD 地址。假如在 192.168.100.113:2379、192.168.100.114:2379 和 192.168.100.115:2379 上面部署了 PD，那么 path 为 "192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379" ++ 默认："/tmp/tidb" ++ 可以通过 `tidb-server --store=mocktikv --path=""` 来启动一个纯内存引擎的 TiDB + +## `--proxy-protocol-networks` + ++ PROXY Protocol 允许的代理服务器地址列表。如需配置多个地址，用 `,` 分隔。 ++ 默认："" ++ 如果该参数为空，TiDB 会禁用 PROXY Protocol 功能。地址可以使用 IP 地址 (192.168.1.50) 或者 CIDR (192.168.1.0/24)，`*` 代表所有地址。 + +## `--proxy-protocol-header-timeout` + ++ PROXY Protocol 请求头读取超时时间 ++ 默认：5 ++ 单位：秒 + +> **注意：** +> +> 不要将该参数配置为 `0`。除非特殊情况，一般使用默认值即可。 + +## `--report-status` + ++ 用于打开或者关闭服务状态监听端口 ++ 默认：true ++ 将参数值设置为 `true` 表明开启状态监听端口；设置为 `false` 表明关闭状态监听端口 + +## `--run-ddl` + ++ tidb-server 是否运行 DDL 语句，集群内至少需要有一台 tidb-server 设置该参数 ++ 默认：true ++ 值可以为 `true` 或者 `false`。设置为 `true` 表明自身会运行 DDL；设置为 `false` 表明自身不会运行 DDL + +## `--socket string` + ++ TiDB 服务使用 unix socket file 方式接受外部连接 ++ 默认："" ++ 例如可以使用 "/tmp/tidb.sock" 来打开 unix socket file + +## `--status` + ++ TiDB 服务状态监听端口 ++ 默认："10080" ++ 该端口用于展示 TiDB 内部数据，包括 [prometheus 统计](https://prometheus.io/) 和 [pprof](https://golang.org/pkg/net/http/pprof/) ++ Prometheus 统计可以通过 `http://host:status_port/metrics` 访问 ++ pprof 数据可以通过 `http://host:status_port/debug/pprof` 访问 + +## `--status-host` + ++ TiDB 服务状态监听 host ++ 默认："0.0.0.0" + +## `--store` + ++ 用来指定 TiDB 底层使用的存储引擎 ++ 默认："mocktikv" ++ 可以选择 "mocktikv"（本地存储引擎）或者 "tikv"（分布式存储引擎） + +## `--token-limit` + ++ TiDB 中同时允许运行的 Session 数量，用于流量控制 ++ 默认：1000 ++ 如果当前运行的连接多于该 token-limit，那么请求会阻塞，等待已经完成的操作释放 Token + +## `-V` + ++ 输出 TiDB 的版本 ++ 默认："" diff --git a/reference/configuration/tidb-server/mysql-variables.md b/reference/configuration/tidb-server/mysql-variables.md new file mode 100644 index 000000000000..03c49014069c --- /dev/null +++ b/reference/configuration/tidb-server/mysql-variables.md @@ -0,0 +1,200 @@ +--- +title: 系统变量 +category: reference +--- + +# 系统变量 + +MySQL 系统变量 (System Variables) 是一些系统参数，用于调整数据库运行时的行为，根据变量的作用范围分为全局范围有效（Global Scope）以及会话级别有效（Session Scope）。TiDB 支持 MySQL5.7 的所有系统变量，大部分变量仅仅是为了兼容性而支持，不会影响运行时行为。 + +## 设置系统变量 + +通过 [`SET` 语句](/reference/sql/statements/admin.md#set-语句)可以修改系统变量的值。进行修改时，还要考虑变量可修改的范围，不是所有的变量都能在全局/会话范围内进行修改。具体的可修改范围参考 [MySQL 动态变量文档](https://dev.mysql.com/doc/refman/5.7/en/dynamic-system-variables.html)。 + +### 全局范围值 + +* 在变量名前加 `GLOBAL` 关键词或者是使用 `@@global.` 作为修饰符: + + {{< copyable "sql" >}} + + ```sql + SET GLOBAL autocommit = 1; + ``` + + {{< copyable "sql" >}} + + ```sql + SET @@global.autocommit = 1; + ``` + +> **注意：** +> +> 在分布式 TiDB 中，`GLOBAL` 变量的设置会持久化到存储层中，单个 TiDB 实例每 2 秒会主动进行一次全变量的获取并形成 `gvc` (global variables cache) 缓存，该缓存有效时间最多可持续 2 秒。在设置 `GLOBAL` 变量之后，为了保证新会话的有效性，请确保两个操作之间的间隔大于 2 秒。相关细节可以查看 [Issue #14531](https://github.com/pingcap/tidb/issues/14531)。 + +### 会话范围值 + +* 在变量名前加 `SESSION` 关键词或者是使用 `@@session.` 作为修饰符，或者是不加任何修饰符: + + {{< copyable "sql" >}} + + ```sql + SET SESSION autocommit = 1; + ``` + + {{< copyable "sql" >}} + + ```sql + SET @@session.autocommit = 1; + ``` + + {{< copyable "sql" >}} + + ```sql + SET @@autocommit = 1; + ``` + +* `LOCAL` 以及 `@@local.` 是 `SESSION` 以及 `@@session.` 的同义词 + +### 系统变量的作用机制 + +* 会话范围的系统变量仅仅会在创建会话时才会根据全局范围系统变量初始化自己的值。更改全局范围的系统变量不会改变已经创建的会话正在使用的系统变量的值。 + + {{< copyable "sql" >}} + + ```sql + SELECT @@GLOBAL.autocommit; + ``` + + ``` + +---------------------+ + | @@GLOBAL.autocommit | + +---------------------+ + | ON | + +---------------------+ + 1 row in set (0.00 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + SELECT @@SESSION.autocommit; + ``` + + ``` + +----------------------+ + | @@SESSION.autocommit | + +----------------------+ + | ON | + +----------------------+ + 1 row in set (0.00 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + SET GLOBAL autocommit = OFF; + ``` + + ``` + Query OK, 0 rows affected (0.01 sec) + ``` + + 会话范围的系统变量不会改变，会话中执行的事务依旧是以自动提交的形式来进行： + + {{< copyable "sql" >}} + + ```sql + SELECT @@SESSION.autocommit; + ``` + + ``` + +----------------------+ + | @@SESSION.autocommit | + +----------------------+ + | ON | + +----------------------+ + 1 row in set (0.00 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + SELECT @@GLOBAL.autocommit; + ``` + + ``` + +---------------------+ + | @@GLOBAL.autocommit | + +---------------------+ + | OFF | + +---------------------+ + 1 row in set (0.00 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + exit + ``` + + ``` + Bye + ``` + + {{< copyable "shell-regular" >}} + + ```shell + mysql -h 127.0.0.1 -P 4000 -u root -D test + ``` + + ``` + Welcome to the MySQL monitor. Commands end with ; or \g. + Your MySQL connection id is 3 + Server version: 5.7.25-TiDB-None MySQL Community Server (Apache License 2.0) + + Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + + Oracle is a registered trademark of Oracle Corporation and/or its + affiliates. Other names may be trademarks of their respective + owners. + + Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + + mysql> + ``` + + 新建的会话会使用新的全局变量： + + ```sql + SELECT @@SESSION.autocommit; + ``` + + ``` + +----------------------+ + | @@SESSION.autocommit | + +----------------------+ + | OFF | + +----------------------+ + 1 row in set (0.00 sec) + ``` + +## TiDB 支持的 MySQL 系统变量 + +下列系统变量是 TiDB 真正支持并且行为和 MySQL 一致： + +| 变量名 | 作用域 | 说明 | +| ---------------- | -------- | -------------------------------------------------- | +| autocommit | GLOBAL \| SESSION | 是否自动 Commit 事务 | +| sql_mode | GLOBAL \| SESSION | 支持部分 MySQL SQL mode，| +| time_zone | GLOBAL \| SESSION | 数据库所使用的时区 | +| tx_isolation | GLOBAL \| SESSION | 事务隔离级别 | +| max\_execution\_time | GLOBAL \| SESSION | 语句超时时间，单位为毫秒 | +| innodb\_lock\_wait\_timeout | GLOBAL \| SESSION | 悲观事务语句等锁时间，单位为秒 | + +> **注意：** +> +> `max_execution_time` 目前对所有类型的 `statement` 生效，并非只对 `SELECT` 语句生效。实际精度在 100ms 级别，而非更准确的毫秒级别。 + +## TiDB 特有的系统变量 + +参见 [TiDB 专用系统变量](/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/reference/configuration/tidb-server/tidb-specific-variables.md b/reference/configuration/tidb-server/tidb-specific-variables.md new file mode 100644 index 000000000000..12025adbac62 --- /dev/null +++ b/reference/configuration/tidb-server/tidb-specific-variables.md @@ -0,0 +1,668 @@ +--- +title: TiDB 专用系统变量和语法 +category: reference +--- + +# TiDB 专用系统变量和语法 + +TiDB 在 MySQL 的基础上，定义了一些专用的系统变量和语法用来优化性能。 + +## 系统变量 + +变量可以通过 SET 语句设置，例如 + +{{< copyable "sql" >}} + +```sql +set @@tidb_distsql_scan_concurrency = 10; +``` + +如果需要设置全局变量，执行 + +{{< copyable "sql" >}} + +```sql +set @@global.tidb_distsql_scan_concurrency = 10; +``` + +### tidb_snapshot + +作用域：SESSION + +默认值：空字符串 + +这个变量用来设置当前会话期待读取的历史数据所处时刻。比如当设置为 "2017-11-11 20:20:20" 时或者一个 TSO 数字 "400036290571534337"，当前会话将能读取到该时刻的数据。 + +### tidb_import_data + +作用域：SESSION + +默认值：0 + +这个变量用来表示当前状态是否为从 dump 文件中导入数据。 +当这个变量被设置为 1 时，唯一索引约束不被检查以加速导入速度。 +这个变量不对外用，只是给 lightning 使用，请用户不要自行修改。 + +### tidb_opt_agg_push_down + +作用域：SESSION + +默认值：0 + +这个变量用来设置优化器是否执行聚合函数下推到 Join 之前的优化操作。 +当查询中聚合操作执行很慢时，可以尝试设置该变量为 1。 + +### tidb_auto_analyze_ratio + +作用域：GLOBAL + +默认值：0.5 + +这个变量用来设置自动 ANALYZE 更新的阈值。当某个表 `tbl` 的修改行数与总行数的比值大于 tidb_auto_analyze_ratio，并且当前时间在 tidb_auto_analyze_start_time 和 tidb_auto_analyze_end_time 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句以自动更新该表的统计信息。注意：只有在 TiDB 的启动配置文件中开启了 run-auto-analyze 选项，该 TiDB 才会触发 auto_analyze。 + +### tidb_auto_analyze_start_time + +作用域：GLOBAL + +默认值：00:00 +0000 + +这个变量用来设置一天中允许自动 ANALYZE 更新的开始时间。 + +### tidb_auto_analyze_end_time + +作用域：GLOBAL + +默认值：23:59 +0000 + +这个变量用来设置一天中允许自动 ANALYZE 更新的结束时间。 + +### tidb_build_stats_concurrency + +作用域：SESSION + +默认值：4 + +这个变量用来设置 ANALYZE 语句执行时并发度。 +当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 + +### tidb_checksum_table_concurrency + +作用域：SESSION + +默认值：4 + +这个变量用来设置 ADMIN CHECKSUM TABLE 语句执行时扫描索引的并发度。 +当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 + +### tidb_current_ts + +作用域：SESSION + +默认值：0 + +这个变量是一个只读变量，用来获取当前事务的时间戳。 + +### tidb_config + +作用域：SESSION + +默认值：空字符串 + +这个变量是一个只读变量，用来获取当前 TiDB Server 的配置信息。 + +### tidb_distsql_scan_concurrency + +作用域：SESSION | GLOBAL + +默认值：15 + +这个变量用来设置 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 +对于 AP 类应用，最大值建议不要超过所有 TiKV 节点的 CPU 核数。 + +### tidb_index_lookup_size + +作用域：SESSION | GLOBAL + +默认值：20000 + +这个变量用来设置 index lookup 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 + +### tidb_index_lookup_concurrency + +作用域：SESSION | GLOBAL + +默认值：4 + +这个变量用来设置 index lookup 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 + +### tidb_index_lookup_join_concurrency + +作用域：SESSION | GLOBAL + +默认值：4 + +这个变量用来设置 index lookup join 算法的并发度。 + +### tidb_hash_join_concurrency + +作用域：SESSION | GLOBAL + +默认值：5 + +这个变量用来设置 hash join 算法的并发度。 + +### tidb_index_serial_scan_concurrency + +作用域：SESSION | GLOBAL + +默认值：1 + +这个变量用来设置顺序 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 + +### tidb_projection_concurrency + +作用域：SESSION | GLOBAL + +默认值：4 + +这个变量用来设置 Projection 算子的并发度。 + +### tidb_hashagg_partial_concurrency + +作用域：SESSION | GLOBAL + +默认值：4 + +这个变量用来设置并行 hash aggregation 算法 partial 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 + +### tidb_hashagg_final_concurrency + +作用域：SESSION | GLOBAL + +默认值：4 + +这个变量用来设置并行 hash aggregation 算法 final 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 + +### tidb_index_join_batch_size + +作用域：SESSION | GLOBAL + +默认值：25000 + +这个变量用来设置 index lookup join 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 + +### tidb_skip_utf8_check + +作用域：SESSION | GLOBAL + +默认值：0 + +这个变量用来设置是否跳过 UTF-8 字符的验证。 +验证 UTF-8 字符需要消耗一定的性能，当可以确认输入的字符串为有效的 UTF-8 字符时，可以将其设置为 1。 + +### tidb_init_chunk_size + +作用域：SESSION | GLOBAL + +默认值：32 + +这个变量用来设置执行过程中初始 chunk 的行数。默认值是 32。 + +### tidb_max_chunk_size + +作用域：SESSION | GLOBAL + +默认值：1024 + +这个变量用来设置执行过程中一个 chunk 最大的行数。 + +### tidb_mem_quota_query + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置一条查询语句的内存使用阈值。 +如果一条查询语句执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_hashjoin + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 HashJoin 算子的内存使用阈值。 +如果 HashJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_mergejoin + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 MergeJoin 算子的内存使用阈值。 +如果 MergeJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_sort + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 Sort 算子的内存使用阈值。 +如果 Sort 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_topn + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 TopN 算子的内存使用阈值。 +如果 TopN 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_indexlookupreader + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 IndexLookupReader 算子的内存使用阈值。 + +如果 IndexLookupReader 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_indexlookupjoin + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 IndexLookupJoin 算子的内存使用阈值。 +如果 IndexLookupJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_mem_quota_nestedloopapply + +作用域：SESSION + +默认值：32 GB + +这个变量用来设置 NestedLoopApply 算子的内存使用阈值。 +如果 NestedLoopApply 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 + +### tidb_general_log + +作用域：SERVER + +默认值：0 + +这个变量用来设置是否在日志里记录所有的 SQL 语句。 + +### tidb_enable_streaming + +作用域：SESSION + +默认值：0 + +这个变量用来设置是否启用 Streaming。 + +### tidb_retry_limit + +作用域：SESSION | GLOBAL + +默认值：10 + +这个变量用来设置最大重试次数。一个事务执行中遇到可重试的错误（例如事务冲突、事务提交过慢或表结构变更）时，会根据该变量的设置进行重试。注意当 `tidb_retry_limit = 0` 时，也会禁用自动重试。 + +### tidb_disable_txn_auto_retry + +作用域：SESSION | GLOBAL + +默认值：on + +这个变量用来设置是否禁用显式事务自动重试，设置为 `on` 时，不会自动重试，如果遇到事务冲突需要在应用层重试。 + +如果将该变量的值设为 `off`，TiDB 将会自动重试事务，这样在事务提交时遇到的错误更少。需要注意的是，这样可能会导致数据更新丢失。 + +这个变量不会影响自动提交的隐式事务和 TiDB 内部执行的事务，它们依旧会根据 `tidb_retry_limit` 的值来决定最大重试次数。 + +是否需要禁用自动重试，请参考[重试的局限性](/reference/transactions/transaction-optimistic.md#重试的局限性)。 + +### tidb_backoff_weight + +作用域：SESSION | GLOBAL + +默认值：2 + +这个变量用来给 TiDB 的 `backoff` 最大时间增加权重，即内部遇到网络或其他组件（TiKV、PD）故障等时，发送重试请求的最大重试时间。可以通过这个变量来调整最大重试时间，最小值为 1。 + +例如，TiDB 向 PD 取 TSO 的基础超时时间是 15 秒，当 `tidb_backoff_weight = 2` 时，取 TSO 的最大超时时间为：基础时间 * 2 等于 30 秒。 + +在网络环境较差的情况下，适当增大该变量值可以有效缓解因为超时而向应用端报错的情况；而如果应用端希望更快地接到报错信息，则应该尽量减小该变量的值。 + +### tidb_enable_table_partition + +作用域：SESSION + +默认值："auto" + +这个变量用来设置是否开启 TABLE PARTITION 特性。默认值 `auto` 表示开启 range partition 和 hash partion。`off` 表示关闭 TABLE PARTITION 的特性，此时语法还是会依旧兼容，只是建立的 partition table 实际上并不是真正的 partition table，而是和普通的 table 一样。`on` 表示开启，目前的作用和 `auto` 一样。 + +注意，目前 TiDB 只支持 range partition 和 hash partition。 + +### tidb_backoff_lock_fast + +作用域：SESSION | GLOBAL + +默认值：100 + +这个变量用来设置读请求遇到锁的 backoff 时间。 + +### tidb_ddl_reorg_worker_cnt + +作用域：GLOBAL + +默认值：16 + +这个变量用来设置 DDL 操作 re-organize 阶段的并发度。 + +### tidb_ddl_reorg_batch_size + +作用域：GLOBAL + +默认值：1024 + +这个变量用来设置 DDL 操作 re-organize 阶段的 batch size。比如 Add Index 操作，需要回填索引数据，通过并发 tidb_ddl_reorg_worker_cnt 个 worker 一起回填数据，每个 worker 以 batch 为单位进行回填。如果 Add Index 时有较多 Update 操作或者 Replace 等更新操作，batch size 越大，事务冲突的概率也会越大，此时建议调小 batch size 的值，最小值是 32。在没有事务冲突的情况下，batch size 可设为较大值，最大值是 10240，这样回填数据的速度更快，但是 TiKV 的写入压力也会变大。 + +### tidb_ddl_reorg_priority + +作用域：SESSION | GLOBAL + +默认值：PRIORITY_LOW + +这个变量用来设置 `ADD INDEX` 操作 re-organize 阶段的执行优先级，可设置为 PRIORITY_LOW/PRIORITY_NORMAL/PRIORITY_HIGH。 + +### tidb_ddl_error_count_limit + +作用域：GLOBAL + +默认值：512 + +这个变量用来控制 DDL 操作失败重试的次数。失败重试次数超过该参数的值后，会取消出错的 DDL 操作。 + +### tidb_max_delta_schema_count + +作用域：GLOBAL + +默认值：1024 + +这个变量用来设置缓存 schema 版本信息（对应版本修改的相关 table IDs）的个数限制，可设置的范围 100 - 16384。此变量在 2.1.18 及之后版本支持。 + +### tidb_force_priority + +作用域：SESSION + +默认值：`NO_PRIORITY` + +这个变量用于改变 TiDB server 上执行的语句的默认优先级。例如，你可以通过设置该变量来确保正在执行 OLAP 查询的用户优先级低于正在执行 OLTP 查询的用户。 + +可设置为 `NO_PRIORITY`、`LOW_PRIORITY`、`DELAYED` 或 `HIGH_PRIORITY`。 + +### tidb_opt_write_row_id + +作用域：SESSION + +默认值：0 + +这个变量用来设置是否允许 insert、replace 和 update 操作 `_tidb_rowid` 列，默认是不允许操作。该选项仅用于 TiDB 工具导数据时使用。 + +### SHARD_ROW_ID_BITS + +对于 PK 非整数或没有 PK 的表，TiDB 会使用一个隐式的自增 rowid，大量 `INSERT` 时会把数据集中写入单个 Region，造成写入热点。 + +通过设置 `SHARD_ROW_ID_BITS`，可以把 rowid 打散写入多个不同的 Region，缓解写入热点问题。但是设置的过大会造成 RPC 请求数放大，增加 CPU 和网络开销。 + +- `SHARD_ROW_ID_BITS = 4` 表示 16 个分片 +- `SHARD_ROW_ID_BITS = 6` 表示 64 个分片 +- `SHARD_ROW_ID_BITS = 0` 表示默认值 1 个分片 + +语句示例： + +- `CREATE TABLE`：`CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` +- `ALTER TABLE`：`ALTER TABLE t SHARD_ROW_ID_BITS = 4;` + +### tidb_slow_log_threshold + +作用域：SESSION + +默认值：300 + +输出慢日志的耗时阈值。当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。默认为 300ms。 + +示例： + +{{< copyable "sql" >}} + +```sql +set tidb_slow_log_threshold = 200; +``` + +### tidb_query_log_max_len + +作用域：SESSION + +默认值：2048 (bytes) + +最长的 SQL 输出长度。当语句的长度大于 query-log-max-len，将会被截断输出。 + +示例： + +{{< copyable "sql" >}} + +```sql +set tidb_query_log_max_len = 20; +``` + +### tidb_txn_mode + +作用域：SESSION | GLOBAL + +默认值："pessimistic" + +这个变量用于设置事务模式。TiDB v3.0 支持了悲观事务，自 v3.0.8 开始，默认使用[悲观事务模式](/reference/transactions/transaction-pessimistic.md)。 + +但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 + +将该变量设置为 "optimistic" 或 "" 时，将会使用[乐观事务模式](/reference/transactions/transaction-optimistic.md)。 + +### tidb_constraint_check_in_place + +作用域：SESSION | GLOBAL + +默认值：0 + +TiDB 支持乐观事务模型，即在执行写入时，假设不存在冲突。冲突检查是在最后 commit 提交时才去检查。这里的检查指 unique key 检查。 + +这个变量用来控制是否每次写入一行时就执行一次唯一性检查。注意，开启该变量后，在大批量写入场景下，对性能会有影响。 + +示例： + +默认关闭 tidb_constraint_check_in_place 时的行为： + +{{< copyable "sql" >}} + +```sql +create table t (i int key); +insert into t values (1); +begin; +insert into t values (1); +``` + +``` +Query OK, 1 row affected +``` + +commit 时才去做检查： + +{{< copyable "sql" >}} + +```sql +commit; +``` + +``` +ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' +``` + +打开 tidb_constraint_check_in_place 后： + +{{< copyable "sql" >}} + +```sql +set @@tidb_constraint_check_in_place=1; +begin; +insert into t values (1); +``` + +``` +ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' +``` + +### tidb_check_mb4_value_in_utf8 + +作用域：SERVER + +默认值：1 + +这个变量用来设置是否开启对字符集为 UTF8 类型的数据做合法性检查，默认值 `1` 表示开启检查。这个默认行为和 MySQL 是兼容的。 + +注意，如果是旧版本升级时，可能需要关闭该选项，否则由于旧版本（v2.1.1 以及之前）没有对数据做合法性检查，所以旧版本写入非法字符串是可以写入成功的，但是新版本加入合法性检查后会报写入失败。具体可以参考[升级后常见问题](/faq/upgrade.md)。 + +### tidb_opt_insubq_to_join_and_agg + +作用域：SESSION | GLOBAL + +默认值：1 + +这个用来设置是否开启优化规则：将子查询转成 join 和 aggregation。 + +示例： + +打开这个优化规则后，会将下面子查询做如下变化： + +{{< copyable "sql" >}} + +```sql +select * from t where t.a in (select aa from t1); +``` + +将子查询转成 join 如下： + +{{< copyable "sql" >}} + +```sql +select * from t, (select aa from t1 group by aa) tmp_t where t.a = tmp_t.aa; +``` + +如果 t1 在列 aa 上有 unique 且 not null 的限制，可以直接改写为如下，不需要添加 aggregation。 + +{{< copyable "sql" >}} + +```sql +select * from t, t1 where t.a=t1.a; +``` + +### tidb_opt_correlation_threshold + +作用域：SESSION | GLOBAL + +默认值：0.9 + +这个变量用来设置优化器启用交叉估算 row count 方法的阈值。如果列和 handle 列之间的顺序相关性超过这个阈值，就会启用交叉估算方法。 + +交叉估算方法可以简单理解为，利用这个列的直方图来估算 handle 列需要扫的行数。 + +### tidb_opt_correlation_exp_factor + +作用域：SESSION | GLOBAL + +默认值：1 + +当交叉估算方法不可用时，会采用启发式估算方法。这个变量用来控制启发式方法的行为。当值为 0 时不用启发式估算方法，大于 0 时，该变量值越大，启发式估算方法越倾向 index scan，越小越倾向 table scan。 + +### tidb_enable_window_function + +作用域：SESSION | GLOBAL + +默认值：1 + +这个变量用来控制是否开启窗口函数的支持。默认值 1 代表开启窗口函数的功能。 + +由于窗口函数会使用一些保留关键字，可能导致原先可以正常执行的 SQL 语句在升级 TiDB 后无法被解析语法，此时可以将 `tidb_enable_window_function` 设置为 `0`。 + +### tidb_slow_query_file + +作用域：SESSION + +默认值："" + +查询 `INFORMATION_SCHEMA.SLOW_QUERY` 只会解析配置文件中 `slow-query-file` 设置的慢日志文件名，默认是 "tidb-slow.log"。但如果想要解析其他的日志文件，可以通过设置 session 变量 `tidb_slow_query_file` 为具体的文件路径，然后查询 `INFORMATION_SCHEMA.SLOW_QUERY` 就会按照设置的路径去解析慢日志文件。更多详情可以参考 [SLOW_QUERY 文档](/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 + +### tidb_enable_fast_analyze + +作用域：SESSION | GLOBAL + +默认值：0 + +这个变量用来控制是否启用统计信息快速分析功能。默认值 0 表示不开启。 + +快速分析功能开启后，TiDB 会随机采样约 10000 行的数据来构建统计信息。因此在数据分布不均匀或者数据量比较少的情况下，统计信息的准确度会比较低。这可能导致执行计划不优，比如选错索引。如果可以接受普通 `ANALYZE` 语句的执行时间，则推荐关闭快速分析功能。 + +### tidb_expensive_query_time_threshold + +作用域：SERVER + +默认值：60 + +这个变量用来控制打印 expensive query 日志的阈值时间，单位是秒，默认值是 60 秒。expensive query 日志和慢日志的差别是，慢日志是在语句执行完后才打印，expensive query 日志可以把正在执行中的语句且执行时间超过阈值的语句及其相关信息打印出来。 + +### tidb_wait_split_region_finish + +作用域：SESSION + +默认值：1 + +由于打散 region 的时间可能比较长，主要由 PD 调度以及 TiKV 的负载情况所决定。这个变量用来设置在执行 `SPLIT REGION` 语句时，是否同步等待所有 region 都打散完成后再返回结果给客户端。默认 1 代表等待打散完成后再返回结果。0 代表不等待 Region 打散完成就返回。 + +需要注意的是，在 region 打散期间，对正在打散 region 上的写入和读取的性能会有一定影响，对于批量写入，导数据等场景，还是建议等待 region 打散完成后再开始导数据。 + +### tidb_wait_split_region_timeout + +作用域：SESSION + +默认值：300 + +这个变量用来设置 `SPLIT REGION` 语句的执行超时时间，单位是秒，默认值是 300 秒，如果超时还未完成，就返回一个超时错误。 + +### tidb_scatter_region + +作用域：GLOBAL + +默认值：0 + +TiDB 默认会在建表时为新表分裂 Region。开启该变量后，会在建表语句执行时，同步打散刚分裂出的 Region。适用于批量建表后紧接着批量写入数据，能让刚分裂出的 Region 先在 TiKV 分散而不用等待 PD 进行调度。为了保证后续批量写入数据的稳定性，建表语句会等待打散 Region 完成后再返回建表成功，建表语句执行时间会是关闭该变量的数倍。 + +### tidb_allow_remove_auto_inc 从 v2.1.18 和 v3.0.4 版本开始引入 + +作用域：SESSION + +默认值：0 + +这个变量用来控制是否允许通过 `ALTER TABLE MODIFY` 或 `ALTER TABLE CHANGE` 来移除某个列的 `AUTO_INCREMENT` 属性。默认为不允许。 + +### tidb_enable_stmt_summary 从 v3.0.4 版本开始引入 + +作用域：SESSION | GLOBAL + +默认值：0 + +这个变量用来控制是否开启 statement summary 功能。如果开启，SQL 的耗时等执行信息将被记录到系统表 `performance_schema.events_statements_summary_by_digest` 中，用于定位和排查 SQL 性能问题。 diff --git a/reference/configuration/tikv-server/configuration-file.md b/reference/configuration/tikv-server/configuration-file.md new file mode 100644 index 000000000000..a9415f62dfe1 --- /dev/null +++ b/reference/configuration/tikv-server/configuration-file.md @@ -0,0 +1,1092 @@ +--- +title: TiKV 配置文件描述 +category: reference +--- + +# TiKV 配置文件描述 + +TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/config-template.toml](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 找到默认值的配置文件，重命名为 config.toml 即可。 + +本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [TiKV 配置参数](/reference/configuration/tikv-server/configuration.md)。 + + +### `status-thread-pool-size` + ++ Http API 服务的工作线程数量。 ++ 默认值：1 ++ 最小值：1 + +### `grpc-compression-type` + ++ gRPC 消息的压缩算法，取值：none， deflate， gzip。 ++ 默认值：none + +### `grpc-concurrency` + ++ gRPC 工作线程的数量。 ++ 默认值：4 ++ 最小值：1 + +### `grpc-concurrent-stream` + ++ 一个 gRPC 链接中最多允许的并发请求数量。 ++ 默认值：1024 ++ 最小值：1 + +### `server.grpc-raft-conn-num` + ++ tikv 节点之间用于 raft 通讯的链接最大数量。 ++ 默认值：10 ++ 最小值：1 + +### `server.grpc-stream-initial-window-size` + ++ gRPC stream 的 window 大小。 ++ 默认值：2MB ++ 单位：KB|MB|GB ++ 最小值：1KB + +### `server.grpc-keepalive-time` + ++ gRPC 发送 keep alive ping 消息的间隔时长。 ++ 默认值：10s ++ 最小值：1s + +### `server.grpc-keepalive-timeout` + ++ 关闭 gRPC 链接的超时时长。 ++ 默认值：3s ++ 最小值：1s + +### `server.concurrent-send-snap-limit` + ++ 同时发送 snapshot 的最大个数，默认值：32 ++ 默认值：32 ++ 最小值：1 + +### `server.concurrent-recv-snap-limit` + ++ 同时接受 snapshot 的最大个数，默认值：32 ++ 默认值：32 ++ 最小值：1 + +### `server.end-point-recursion-limit` + ++ endpoint 下推查询请求解码消息时，最多允许的递归层数。 ++ 默认值：1000 ++ 最小值：1 + +### `server.end-point-request-max-handle-duration` + ++ endpoint 下推查询请求处理任务最长允许的时长。 ++ 默认值：60s ++ 最小值：1s + +### `server.snap-max-write-bytes-per-sec` + ++ 处理 snapshot 时最大允许使用的磁盘带宽 ++ 默认值：1000MB ++ 单位：KB|MB|GB ++ 最小值：1KB + +## readpool.storage + +存储线程池相关的配置项。 + +### `high-concurrency` + ++ 处理高优先级读请求的线程池线程数量。 ++ 默认值：4 ++ 最小值：1 + +### `normal-concurrency` + ++ 处理普通优先级读请求的线程池线程数量。 ++ 默认值：4 ++ 最小值：1 + +### `low-concurrency` + ++ 处理低优先级读请求的线程池线程数量。 ++ 默认值：4 ++ 最小值：1 + +### `max-tasks-per-worker-high` + ++ 高优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 ++ 默认值：2000 ++ 最小值：2 + +### `max-tasks-per-worker-normal` + ++ 普通优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 ++ 默认值：2000 ++ 最小值：2 + +### `max-tasks-per-worker-low` + ++ 低优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 ++ 默认值：2000 ++ 最小值：2 + +### `stack-size` + ++ Storage 读线程池中线程的栈大小。 ++ 默认值：10MB ++ 单位：KB|MB|GB ++ 最小值：2MB + +## readpool.coprocessor + +协处理器线程池相关的配置项。 + +### `high-concurrency` + ++ 处理高优先级 Coprocessor 请求（如点查）的线程池线程数量。 ++ 默认值：CPU * 0.8 ++ 最小值：1 + +### `normal-concurrency` + ++ 处理普通优先级 Coprocessor 请求的线程池线程数量。 ++ 默认值：CPU * 0.8 ++ 最小值：1 + +### `low-concurrency` + ++ 处理低优先级 Coprocessor 请求（如扫表）的线程池线程数量。 ++ 默认值：CPU * 0.8 ++ 最小值：1 + +### `max-tasks-per-worker-high` + ++ 高优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 ++ 默认值：2000 ++ 最小值：2 + +### `max-tasks-per-worker-normal` + ++ 普通优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 ++ 默认值：2000 ++ 最小值：2 + +### `max-tasks-per-worker-low` + ++ 低优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 ++ 默认值：2000 ++ 最小值：2 + +### `stack-size` + +Coprocessor 线程池中线程的栈大小，默认值：10，单位：KiB|MiB|GiB。 + ++ 默认值：10MB ++ 单位：KB|MB|GB ++ 最小值：2MB + +## storage + +存储相关的配置项。 + +### `scheduler-notify-capacity` + ++ scheduler 一次获取最大消息个数 ++ 默认值：10240 ++ 最小值：1 + +### `scheduler-concurrency` + ++ scheduler 内置一个内存锁机制，防止同时对一个 key 进行操作。每个 key hash 到不同的槽。 ++ 默认值：2048000 ++ 最小值：1 + +### `scheduler-worker-pool-size` + ++ scheduler 线程个数，主要负责写入之前的事务一致性检查工作。 ++ 默认值：4 ++ 最小值：1 + +### `scheduler-pending-write-threshold` + ++ 写入数据队列的最大值，超过该值之后对于新的写入 TiKV 会返回 Server Is Busy 错误。 ++ 默认值：100MB ++ 单位: MB|GB + +## raftstore + +raftstore 相关的配置项。 + +### `sync-log` + ++ 数据、log 落盘是否 sync，注意：设置成 false 可能会丢数据。 ++ 默认值：true + +### `prevote` + ++ 开启 Prevote 的开关，开启有助于减少隔离恢复后对系统造成的抖动。 ++ 默认值：true + +### `raftdb-path` + ++ raft 库的路径，默认存储在 storage.data-dir/raft 下。 ++ 默认值："" + +### `raft-base-tick-interval` + ++ 状态机 tick 一次的间隔时间。 ++ 默认值：1s ++ 最小值：大于 0 + +### `raft-heartbeat-ticks` + ++ 发送心跳时经过的 tick 个数，即每隔 raft-base-tick-interval * raft-heartbeat-ticks 时间发送一次心跳。 ++ 默认值：2 ++ 最小值：大于 0 + +### `raft-election-timeout-ticks` + ++ 发起选举时经过的 tick 个数，即如果处于无主状态，大约经过 raft-base-tick-interval * raft-election-timeout-ticks 时间以后发起选举。 ++ 默认值：10 ++ 最小值：raft-heartbeat-ticks + +### `raft-min-election-timeout-ticks` + ++ 发起选举时至少经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks，不能比 raft-election-timeout-ticks 小。 ++ 默认值：0 ++ 最小值：0 + +### `raft-max-election-timeout-ticks` + ++ 发起选举时最多经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks * 2。 ++ 默认值：0 ++ 最小值：0 + +### `raft-max-size-per-message` + ++ 产生的单个消息包的大小限制，软限制。 ++ 默认值：1MB ++ 最小值：0 ++ 单位：MB + +### `raft-max-inflight-msgs` + ++ 待确认日志个数的数量，如果超过这个数量将会减缓发送日志的个数。 ++ 默认值：256 ++ 最小值：大于0 + +### `raft-entry-max-size` + ++ 单个日志最大大小，硬限制。 ++ 默认值：8MB ++ 最小值：0 ++ 单位：MB|GB + +### `raft-log-gc-tick-interval` + ++ 删除 raft 日志的轮询任务调度间隔时间，0 表示不启用。 ++ 默认值：10s ++ 最小值：0 + +### `raft-log-gc-threshold` + ++ 允许残余的 raft 日志个数，这是一个软限制。 ++ 默认值：50 ++ 最小值：1 + +### `raft-log-gc-count-limit` + ++ 允许残余的 raft 日志个数，这是一个硬限制。默认值为按照每个日志 1MB 而计算出来的 3/4 region 大小所能容纳的日志个数。 ++ 最小值：0 + +### `raft-log-gc-size-limit` + ++ 允许残余的 raft 日志大小，这是一个硬限制，默认为 region 大小的 3/4。 ++ 最小值：大于 0 + +### `raft-entry-cache-life-time` + ++ 内存中日志 cache 允许的最长残留时间。 ++ 默认值：30s ++ 最小值：0 + +### `raft-reject-transfer-leader-duration` + ++ 新节点保护时间，控制迁移 leader 到新加节点的最小时间，设置过小容易导致迁移 leader 失败。 ++ 默认值：3s ++ 最小值：0 + +### `raftstore.hibernate-regions` (**实验特性**) + ++ 打开或关闭静默 Region。打开后，如果 Region 长时间处于非活跃状态，即被自动设置为静默状态。静默状态的 Region 可以降低 Leader 和 Follower 之间心跳信息的系统开销。可以通过 `raftstore.peer-stale-state-check-interval` 调整 Leader 和 Follower 之间的心跳间隔。 ++ 默认值：true + +### `raftstore.peer-stale-state-check-interval` + ++ 修改对 Region 的状态检查间隔时间。 ++ 默认值：5 min + +### `split-region-check-tick-interval` + ++ 检查 region 是否需要分裂的时间间隔，0 表示不启用。 ++ 默认值：10s ++ 最小值：0 + +### `region-split-check-diff` + ++ 允许 region 数据超过指定大小的最大值，默认为 region 大小的 1/16。 ++ 最小值：0 + +### `region-compact-check-interval` + ++ 检查是否需要人工触发 rocksdb compaction 的时间间隔，0 表示不启用。 ++ 默认值：5m ++ 最小值：0 + +### `clean-stale-peer-delay` + ++ 延迟删除过期副本数据的时间。 ++ 默认值：10m ++ 最小值：0 + +### `region-compact-check-step` + ++ 每轮校验人工 compaction 时，一次性检查的 region 个数。 ++ 默认值：100 ++ 最小值：0 + +### `region-compact-min-tombstones` + ++ 触发 rocksdb compaction 需要的 tombstone 个数。 ++ 默认值：10000 ++ 最小值：0 + +### `region-compact-tombstones-percent` + ++ 触发 rocksdb compaction 需要的 tombstone 所占比例。 ++ 默认值：30 ++ 最小值：1 ++ 最大值：100 + +### `pd-heartbeat-tick-interval` + ++ 触发 region 对 PD 心跳的时间间隔，0 表示不启用。 ++ 默认值：1m ++ 最小值：0 + +### `pd-store-heartbeat-tick-interval` + ++ 触发 store 对 PD 心跳的时间间隔，0 表示不启用。 ++ 默认值：10s ++ 最小值：0 + +### `snap-mgr-gc-tick-interval` + ++ 触发回收过期 snapshot 文件的时间间隔，0 表示不启用。 ++ 默认值：5s ++ 最小值：0 + +### `snap-gc-timeout` + ++ snapshot 文件的最长保存时间。 ++ 默认值：4h ++ 最小值：0 + +### `lock-cf-compact-interval` + ++ 触发对 lock CF compact 检查的时间间隔。 ++ 默认值：10m ++ 最小值：0 + +### `lock-cf-compact-bytes-threshold` + ++ 触发对 lock CF 进行 compact 的大小。 ++ 默认值：256MB ++ 最小值：0 ++ 单位：MB + +### `notify-capacity` + ++ region 消息队列的最长长度。 ++ 默认值：40960 ++ 最小值：0 + +### `messages-per-tick` + ++ 每轮处理的消息最大个数。 ++ 默认值：4096 ++ 最小值：0 + +### `max-peer-down-duration` + ++ 副本允许的最长未响应时间，超过将被标记为 down，后续 PD 会尝试将其删掉。 ++ 默认值：5m ++ 最小值：0 + +### `max-leader-missing-duration` + ++ 允许副本处于无主状态的最长时间，超过将会向 PD 校验自己是否已经被删除。 ++ 默认值：2h ++ 最小值：> abnormal-leader-missing-duration + +### `abnormal-leader-missing-duration` + ++ 允许副本处于无主状态的时间，超过将视为异常，标记在 metrics 和日志中。 ++ 默认值：10m ++ 最小值：> peer-stale-state-check-interval + +### `peer-stale-state-check-interval` + ++ 触发检验副本是否处于无主状态的时间间隔。 ++ 默认值：5m ++ 最小值：> 2 * election-timeout + +### `leader-transfer-max-log-lag` + ++ 尝试转移领导权时被转移者允许的最大日志缺失个数。 ++ 默认值：10 ++ 最小值：10 + +### `snap-apply-batch-size` + ++ 当导入 snapshot 文件需要写数据时，内存写缓存的大小 ++ 默认值：10MB ++ 最小值：0 ++ 单位：MB + +### `consistency-check-interval` + ++ 触发一致性检查的时间间隔, 0 表示不启用。 ++ 默认值：0s ++ 最小值：0 + +### `raft-store-max-leader-lease` + ++ region 主可信任期的最长时间。 ++ 默认值：9s ++ 最小值：0 + +### `right-derive-when-split` + ++ 为 true 时，以最大分裂 key 为起点的 region 复用原 region 的 key；否则以原 region 起点 key 作为起点的 region 复用原 region 的 key。 ++ 默认值：true + +### `allow-remove-leader` + ++ 允许删除主开关。 ++ 默认值：false + +### `merge-max-log-gap` + ++ 进行 merge 时，允许的最大日志缺失个数。 ++ 默认值：10 ++ 最小值：> raft-log-gc-count-limit + +### `merge-check-tick-interval` + ++ 触发 merge 完成检查的时间间隔。 ++ 默认值：10s ++ 最小值：大于 0 + +### `use-delete-range` + ++ 开启 rocksdb delete_range 接口删除数据的开关。 ++ 默认值：false + +### `cleanup-import-sst-interval` + ++ 触发检查过期 SST 文件的时间间隔，0 表示不启用。 ++ 默认值：10m ++ 最小值：0 + +### `local-read-batch-size` + ++ 一轮处理读请求的最大个数。 ++ 默认值：1024 ++ 最小值：大于 0 + +### `apply-max-batch-size` + ++ 一轮处理数据落盘的最大请求个数。 ++ 默认值：1024 ++ 最小值：大于 0 + +### `apply-pool-size` + ++ 处理数据落盘的线程池线程数。 ++ 默认值：2 ++ 最小值：大于 0 + +### `store-max-batch-size` + ++ 一轮处理的最大请求个数。 ++ 默认值：1024 ++ 最小值：大于 0 + +### `store-pool-size` + ++ 处理 raft 的线程池线程数。 ++ 默认值：2 ++ 最小值：大于 0 + +### `future-poll-size` + ++ 驱动 future 的线程池线程数。 ++ 默认值：1 ++ 最小值：大于 0 + +## coprocessor + +协处理器相关的配置项。 + +### `split-region-on-table` + ++ 开启按 table 分裂 Region的开关，建议仅在 TiDB 模式下使用。 ++ 默认值：true + +### `batch-split-limit` + ++ 批量分裂 Region 的阈值，调大该值可加速分裂 Region。 ++ 默认值：10 ++ 最小值：1 + +### `region-max-size` + ++ Region 容量空间最大值，超过时系统分裂成多个 Region。 ++ 默认值：144MB ++ 单位：KB|MB|GB + +### `region-split-size` + ++ 分裂后新 Region 的大小，此值属于估算值。 ++ 默认值：96MB ++ 单位：KB|MB|GB + +### `region-max-keys` + ++ Region 最多允许的 key 的个数，超过时系统分裂成多个 Region。 ++ 默认值：1440000 + +### `region-split-keys` + ++ 分裂后新 Region 的 key 的个数，此值属于估算值。 ++ 默认值：960000 + +## rocksdb + +rocksdb 相关的配置项。 + +### `max-background-jobs` + ++ RocksDB 后台线程个数。 ++ 默认值：8 ++ 最小值：1 + +### `max-sub-compactions` + ++ RocksDB 进行 subcompaction 的并发个数。 ++ 默认值：1 ++ 最小值：1 + +### `max-open-files` + ++ RocksDB 可以打开的文件总数。 ++ 默认值：40960 ++ 最小值：-1 + +### `max-manifest-file-size` + ++ RocksDB Manifest 文件最大大小。 ++ 默认值：128MB ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `create-if-missing` + ++ 自动创建 DB 开关。 ++ 默认值：true + +### `wal-recovery-mode` + ++ WAL 恢复模式，取值：0（TolerateCorruptedTailRecords），1（AbsoluteConsistency），2（PointInTimeRecovery），3（SkipAnyCorruptedRecords）。 ++ 默认值：2 ++ 最小值：0 ++ 最大值：3 + +### `wal-dir` + ++ WAL 存储目录，默认：“tmp/tikv/store”。 ++ 默认值：/tmp/tikv/store + +### `wal-ttl-seconds` + ++ 归档 WAL 生存周期，超过该值时，系统会删除相关 WAL。 ++ 默认值：0 ++ 最小值：0 ++ 单位：秒 + +### `wal-size-limit` + ++ 归档 WAL 大小限制，超过该值时，系统会删除相关 WAL。 ++ 默认值：0 ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `enable-statistics` + ++ 开启自动优化 Rate LImiter 的配置的开关。 ++ 默认值：false + +### `stats-dump-period` + ++ 开启 Pipelined Write 的开关。 ++ 默认值：true + +### `compaction-readahead-size` + ++ 异步 Sync 限速速率。 ++ 默认值：0 ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `writable-file-max-buffer-size` + ++ WritableFileWrite 所使用的最大的 buffer 大小。 ++ 默认值：1MB ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `use-direct-io-for-flush-and-compaction` + ++ flush 或者 compaction 开启 DirectIO 的开关。 ++ 默认值：false + +### `rate-bytes-per-sec` + ++ Rate Limiter 限制速率。 ++ 默认值：0 ++ 最小值：0 ++ 单位：Bytes + +### `rate-limiter-mode` + ++ Rate LImiter 模式，取值：1（ReadOnly），2（WriteOnly），3（AllIo）。 ++ 默认值：2 ++ 最小值：1 ++ 最大值：3 + +### `auto-tuned` + ++ 开启自动优化 Rate LImiter 的配置的开关。 ++ 默认值：false + +### `enable-pipelined-write` + ++ 开启 Pipelined Write 的开关。 ++ 默认值：true + +### `bytes-per-sync` + ++ 异步 Sync 限速速率。 ++ 默认值：1MB ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `wal-bytes-per-sync` + ++ WAL Sync 限速速率，默认：512KB。 ++ 默认值：512KB ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `info-log-max-size` + ++ Info 日志的最大大小。 ++ 默认值：1GB ++ 最小值：0 ++ 单位：B|KB|MB|GB + +### `info-log-roll-time` + ++ 日志截断间隔时间，如果为0则不截断。 ++ 默认值：0 + +### `info-log-keep-log-file-num` + ++ 保留日志文件最大个数。 ++ 默认值：10 ++ 最小值：0 + +### `info-log-dir` + ++ 日志存储目录。 ++ 默认值："" + +## rocksdb.titan + +Titan 相关的配置项。 + +### `enabled` + ++ 开启 Titan 开关。 ++ 默认值：false + +### `dirname` + ++ Titan Blob 文件存储目录。 ++ 默认值：titandb + +### `disable-gc` + ++ 关闭 Titan 对 Blob 文件的 GC 的开关。 ++ 默认值：false + +### `max-background-gc` + ++ Titan 后台 GC 的线程个数。 ++ 默认值：1 ++ 最小值：1 + +## rocksdb.defaultcf + +rocksdb defaultcf 相关的配置项。 + +### `block-size` + ++ rocksdb block size。 ++ 默认值：64KB ++ 最小值：1KB ++ 单位：KB|MB|GB + +### `block-cache-size` + ++ rocksdb block cache size。 ++ 默认值：机器总内存 / 4 ++ 最小值：0 ++ 单位：KB|MB|GB + +### `disable-block-cache` + ++ 开启 block cache 开关。 ++ 默认值：false + +### `cache-index-and-filter-blocks` + ++ 开启 缓存 index 和 filter 的开关。 ++ 默认值：true + +### `pin-l0-filter-and-index-blocks` + ++ 是否 pin 住 L0 的 index 和 filter。 ++ 默认值：true + +### `use-bloom-filter` + ++ 开启 bloom filter 的开关。 ++ 默认值：true + +### `optimize-filters-for-hits` + ++ 开启优化 filter 的命中率的开关。 ++ 默认值：true + +### `whole_key_filtering` + ++ 开启将整个 key 放到 bloom filter 中的开关。 ++ 默认值：true + +### `bloom-filter-bits-per-key` + +bloom filter 为每个 key 预留的长度。 + ++ 默认值：10 ++ 单位：字节 + +### `block-based-bloom-filter` + ++ 开启每个 block 建立 bloom filter 的开关。 ++ 默认值：false + +### `read-amp-bytes-per-bit` + ++ 开启读放大统计的开关，0：不开启，> 0 开启。 ++ 默认值：0 ++ 最小值：0 + +### `compression-per-level` + ++ 每一层默认压缩算法，默认：前两层为 No，后面 5 层为 lz4。 ++ 默认值：["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] + +### `write-buffer-size` + ++ memtable 大小。 ++ 默认值：128MB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `max-write-buffer-number` + ++ 最大 memtable 个数。 ++ 默认值：5 ++ 最小值：0 + +### `min-write-buffer-number-to-merge` + ++ 触发 flush 的最小 memtable 个数。 ++ 默认值：1 ++ 最小值：0 + +### `max-bytes-for-level-base` + ++ base level (L1) 最大字节数，一般设置为 memtable 大小 4 倍。 ++ 默认值：512MB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `target-file-size-base` + ++ base level 的目标文件大小。 ++ 默认值：8MB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `level0-file-num-compaction-trigger` + ++ 触发 compaction 的 L0 文件最大个数。 ++ 默认值：4 ++ 最小值：0 + +### `level0-slowdown-writes-trigger` + ++ 触发 write stall 的 L0 文件最大个数。 ++ 默认值：20 ++ 最小值：0 + +### `level0-stop-writes-trigger` + ++ 完全阻停写入的 L0 文件最大个数。 ++ 默认值：36 ++ 最小值：0 + +### `max-compaction-bytes` + ++ 一次 compaction 最大写入字节数，默认 2GB。 ++ 默认值：2GB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `compaction-pri` + +Compaction 优先类型，默认：3（MinOverlappingRatio），0（ByCompensatedSize）， +1（OldestLargestSeqFirst），2（OldestSmallestSeqFirst）。 + ++ 默认值：3 + +### `dynamic-level-bytes` + ++ 开启 dynamic level bytes 优化的开关。 ++ 默认值：true + +### `num-levels` + ++ RocksDB 文件最大层数。 ++ 默认值：7 + +### `max-bytes-for-level-multiplier` + ++ 每一层的默认放大倍数。 ++ 默认值：10 + +### `rocksdb.defaultcf.compaction-style` + ++ Compaction 方法，可选值为 level，universal。 ++ 默认值：level + +### `disable-auto-compactions` + ++ 开启自动 compaction 的开关。 ++ 默认值：false + +### `soft-pending-compaction-bytes-limit` + ++ pending compaction bytes 的软限制。 ++ 默认值：64GB ++ 单位：KB|MB|GB + +### `hard-pending-compaction-bytes-limit` + ++ pending compaction bytes 的硬限制。 ++ 默认值：256GB ++ 单位：KB|MB|GB + +## rocksdb.defaultcf.titan + +rocksdb defaultcf titan 相关的配置项。 + +### `min-blob-size` + ++ 最小存储在 Blob 文件中 value 大小，低于该值的 value 还是存在 LSM-Tree 中。 ++ 默认值：1KB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `blob-file-compression` + ++ Blob 文件所使用的压缩算法，可选值：no, snappy, zlib, bzip2, lz4, lz4hc, zstd。 ++ 默认值：lz4 + +### `blob-cache-size` + ++ Blob 文件的 cache 大小，默认：0GB。 ++ 默认值：0GB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `min-gc-batch-size` + ++ 做一次 GC 所要求的最低 Blob 文件大小总和。 ++ 默认值：16MB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `max-gc-batch-size` + ++ 做一次 GC 所要求的最高 Blob 文件大小总和。 ++ 默认值：64MB ++ 最小值：0 ++ 单位：KB|MB|GB + +### `discardable-ratio` + ++ Blob 文件 GC 的触发比例，如果某 Blob 文件中的失效 value 的比例高于该值才可能被 GC 选中。 ++ 默认值：0.5 ++ 最小值：0 ++ 最大值：1 + +### `sample-ratio` + ++ 进行 GC 时，对 Blob 文件进行采样时读取数据占整个文件的比例。 ++ 默认值：0.1 ++ 最小值：0 ++ 最大值：1 + +### `merge-small-file-threshold` + ++ Blob 文件的大小小于该值时，无视 discardable-ratio 仍可能被 GC 选中。 ++ 默认值：8MB ++ 最小值：0 ++ 单位：KB|MB|GB + +## rocksdb.writecf + +rocksdb writecf 相关的配置项。 + +### `block-cache-size` + ++ block cache size。 ++ 默认值：机器总内存 * 15% ++ 单位：MB|GB + +### `optimize-filters-for-hits` + ++ 开启优化 filter 的命中率的开关。 ++ 默认值：false + +### `whole-key-filtering` + ++ 开启将整个 key 放到 bloom filter 中的开关。 ++ 默认值：false + +## rocksdb.lockcf + +rocksdb lockcf 相关配置项。 + +### `block-cache-size` + ++ block cache size。 ++ 默认值：机器总内存 * 2% ++ 单位：MB|GB + +### `optimize-filters-for-hits` + ++ 开启优化 filter 的命中率的开关。 ++ 默认值：false + +### `level0-file-num-compaction-trigger` + ++ 触发 compaction 的 L0 文件个数。 ++ 默认值：1 + +## raftdb + +raftdb 相关配置项。 + +### `max-background-jobs` + ++ RocksDB 后台线程个数。 ++ 默认值：2 ++ 最小值：1 + +### `max-sub-compactions` + ++ RocksDB 进行 subcompaction 的并发数。 ++ 默认值：1 ++ 最小值：1 + +### `wal-dir` + ++ WAL 存储目录。 ++ 默认值：/tmp/tikv/store + +## security + +安全相关配置项。 + +### `ca-path` + ++ CA 文件路径 ++ 默认值："" + +### `cert-path` + ++ 包含 X509 证书的 PEM 文件路径 ++ 默认值："" + +### `key-path` + ++ 包含 X509 key 的 PEM 文件路径 ++ 默认值："" + +## import + +import 相关的配置项。 + +### `num-threads` + ++ 处理 RPC 请求线程数。 ++ 默认值：8 ++ 最小值：1 + +### `num-import-jobs` + ++ 并发导入工作任务数。 ++ 默认值：8 ++ 最小值：1 + +## pessimistic-txn + +### `enabled` + ++ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/reference/transactions/transaction-pessimistic.md)。 ++ 默认值：true + +### `wait-for-lock-timeout` + ++ 悲观事务在 TiKV 中等待其他事务释放锁的最长时间，单位为毫秒。若超时则会返回错误给 TiDB 并由 TiDB 重试加锁，语句最长等锁时间由 `innodb_lock_wait_timeout` 控制。 ++ 默认值：1000 ++ 最小值：1 + +### `wait-up-delay-duration` + ++ 悲观事务释放锁时，只会唤醒等锁事务中 start ts 最小的事务，其他事务将会延迟 `wake-up-delay-duration` 毫秒之后被唤醒。 ++ 默认值：20 diff --git a/dev/reference/configuration/tikv-server/configuration.md b/reference/configuration/tikv-server/configuration.md similarity index 100% rename from dev/reference/configuration/tikv-server/configuration.md rename to reference/configuration/tikv-server/configuration.md diff --git a/reference/error-codes.md b/reference/error-codes.md new file mode 100644 index 000000000000..dc03defa4197 --- /dev/null +++ b/reference/error-codes.md @@ -0,0 +1,120 @@ +--- +title: 错误码与故障诊断 +category: reference +--- + +# 错误码与故障诊断 + +本篇文档描述在使用 TiDB 过程中会遇到的问题以及解决方法。 + +## 错误码 + +TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样的错误码。另外还有一些特有的错误码： + +| 错误码 | 说明 | +| --------------------- | -------------------------------------------------- | +| 8001 | 请求使用的内存超过 TiDB 内存使用的阈值限制 | +| 8002 | 带有 `SELECT FOR UPDATE` 语句的事务，在遇到写入冲突时，为保证一致性无法进行重试，事务将进行回滚并返回该错误 | +| 8003 | `ADMIN CHECK TABLE` 命令在遇到行数据跟索引不一致的时候返回该错误 | +| 8004 | 单个事务过大，原因及解决方法请参考[这里](/faq/tidb.md#433-transaction-too-large-是什么原因怎么解决) | +| 8005 | 事务在 TiDB 中遇到了写入冲突，原因及解决方法请参考[这里](/faq/tidb.md#九故障排除) | +| 8018 | 插件无法重新载入，原因是没有载入过 | +| 8019 | 重新载入的插件版本与之前不同，无法重新载入 | +| 8020 | 表被锁 | +| 8021 | key 不存在 | +| 8022 | 事务提交失败，但可以进行重试 | +| 8023 | 不能设置空值 | +| 8024 | 非法的事务 | +| 8025 | 写入的单条键值对过大 | +| 8026 | 没有实现的接口 | +| 8027 | 表结构版本过期 | +| 8028 | 表结构发生了变化 | +| 8029 | 错误值 | +| 8030 | 转变为带符号正整数时发生了越界，显示为负数 | +| 8031 | 负数转变为无符号数时，被转变为正数 | +| 8032 | 非法的 year 格式 | +| 8033 | 非法的 year 值 | +| 8034 | 不正确的 datetime 值 | +| 8036 | 非法的 time 格式 | +| 8037 | 非法的 week 格式 | +| 8038 | 字段无法获取到默认值 | +| 8039 | 索引的偏移量超出范围 | +| 8042 | 表结构的状态为不存在 | +| 8043 | 列信息的状态为不存在 | +| 8044 | 索引的状态为不存在 | +| 8045 | 非法的表数据 | +| 8046 | 列信息的状态为不可见 | +| 8047 | 设置了不支持的系统变量值，通常在用户设置了数据库不支持的变量值后的告警信息里出现 | +| 8048 | 设置了不支持的数据库隔离级别 | +| 8049 | 载入权限相关表失败 | +| 8050 | 设置了不支持的权限类型 | +| 8051 | 未知的字段类型 | +| 8052 | 来自客户端的数据包的序列号错误 | +| 8053 | 获取到了非法的自增列值 | +| 8055 | 当前快照过旧，数据可能已经被 GC | +| 8056 | 非法的表 ID | +| 8057 | 非法的字段类型 | +| 8058 | 申请了不存在的自动变量类型 | +| 8059 | 获取自动随机量失败 | +| 8060 | 非法的自增列偏移量 | +| 8061 | 不支持的 SQL Hint | +| 8062 | SQL Hint 中使用了非法的 token，与 Hint 的保留字冲突 | +| 8063 | SQL Hint 中限制内存使用量超过系统设置的上限，设置被忽略 | +| 8064 | 解析 SQL Hint 失败 | +| 8065 | SQL Hint 中使用了非法的整数 | +| 8066 | JSON_OBJECTAGG 函数的第二个参数是非法参数 | +| 8101 | 插件 ID 格式错误，正确的格式是 `[name]-[version]` 并且 name 和 version 中不能带有 '-' | +| 8102 | 无法读取插件定义信息 | +| 8103 | 插件名称错误 | +| 8104 | 插件版本不匹配 | +| 8105 | 插件被重复载入 | +| 8106 | 插件定义的系统变量名称没有以插件名作为开头 | +| 8107 | 载入的插件未指定版本或指定的版本过低 | +| 8108 | 不支持的执行计划类型 | +| 8109 | analyze 索引时找不到指定的索引 | +| 8110 | 不能进行笛卡尔积运算，需要将配置文件里的 `cross-join` 设置为 `true` | +| 8111 | execute 语句执行时找不到对应的 prepare 语句 | +| 8112 | execute 语句的参数个数与 prepare 语句不符合 | +| 8113 | execute 语句涉及的表结构在 prepare 语句执行后发生了变化 | +| 8114 | 未知的执行计划类型 | +| 8115 | 不支持 prepare 多行语句 | +| 8116 | 不支持 prepare DDL 语句 | +| 8118 | 构建执行器失败 | +| 8120 | 获取不到事务的 start tso | +| 8121 | 权限检查失败 | +| 8122 | 指定了通配符，但是找不到对应的表名 | +| 8123 | 带聚合函数的 SQL 中返回非聚合的列，违反了 only_full_group_by 模式 | +| 8200 | 尚不支持的 DDL 语法 | +| 8201 | 当前 TiDB 不是 DDL owner | +| 8202 | 不能对该索引解码 | +| 8203 | 非法的 DDL worker | +| 8204 | 非法的 DDL job | +| 8205 | 非法的 DDL job 标志 | +| 8206 | DDL 的 Reorg 阶段执行超时 | +| 8207 | 非法的存储节点 | +| 8210 | 非法的 DDL 状态 | +| 8211 | DDL 的 Reorg 阶段发生了 panic | +| 8212 | 非法的 region 切分范围 | +| 8213 | 非法的 DDL job 版本 | +| 8214 | DDL 操作被终止 | +| 8215 | Admin Repair 表失败 | +| 8216 | 非法的自动随机列 | +| 8221 | Key 编码错误 | +| 8222 | 索引 Key 编码错误 | +| 8223 | 检测出数据与索引不一致的错误 | +| 8224 | 找不到 DDL job | +| 8225 | DDL 已经完成，无法被取消 | +| 8226 | DDL 几乎要完成了，无法被取消 | +| 8227 | 创建 Sequence 时使用了不支持的选项 | +| 9001 | 请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络 | +| 9002 | 请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络 | +| 9003 | TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志 | +| 9004 | 当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码 | +| 9005 | 某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志 | +| 9006 | GC Life Time 间隔时间过短，长事务本应读到的数据可能被清理了，应增加 GC Life Time | +| 9007 | 事务在 TiKV 中遇到了写入冲突，原因及解决方法请参考[这里](/faq/tidb.md#九故障排除) | +| 9008 | 同时向 TiKV 发送的请求过多，超过了限制 | + +## 故障诊断 + +参见[故障诊断文档](/how-to/troubleshoot/cluster-setup.md)以及 [FAQ](/faq/tidb.md)。 diff --git a/reference/garbage-collection/configuration.md b/reference/garbage-collection/configuration.md new file mode 100644 index 000000000000..f23ed92b865a --- /dev/null +++ b/reference/garbage-collection/configuration.md @@ -0,0 +1,125 @@ +--- +title: GC 配置 +category: reference +--- + +# GC 配置 + +TiDB 的 GC 相关的配置存储于 `mysql.tidb` 系统表中，可以通过 SQL 语句对这些参数进行查询和更改： + +{{< copyable "sql" >}} + +```sql +select VARIABLE_NAME, VARIABLE_VALUE from mysql.tidb; +``` + +``` ++--------------------------+----------------------------------------------------------------------------------------------------+ +| VARIABLE_NAME | VARIABLE_VALUE | ++--------------------------+----------------------------------------------------------------------------------------------------+ +| bootstrapped | True | +| tidb_server_version | 33 | +| system_tz | UTC | +| tikv_gc_leader_uuid | 5afd54a0ea40005 | +| tikv_gc_leader_desc | host:tidb-cluster-tidb-0, pid:215, start at 2019-07-15 11:09:14.029668932 +0000 UTC m=+0.463731223 | +| tikv_gc_leader_lease | 20190715-12:12:14 +0000 | +| tikv_gc_enable | true | +| tikv_gc_run_interval | 10m0s | +| tikv_gc_life_time | 10m0s | +| tikv_gc_last_run_time | 20190715-12:09:14 +0000 | +| tikv_gc_safe_point | 20190715-11:59:14 +0000 | +| tikv_gc_auto_concurrency | true | +| tikv_gc_mode | distributed | ++--------------------------+----------------------------------------------------------------------------------------------------+ +13 rows in set (0.00 sec) +``` + +例如，如果需要将 GC 调整为保留最近一天以内的数据，只需执行下列语句即可： + +{{< copyable "sql" >}} + +```sql +update mysql.tidb set VARIABLE_VALUE="24h" where VARIABLE_NAME="tikv_gc_life_time"; +``` + +> **注意：** +> +> `mysql.tidb` 系统表中除了下文将要列出的 GC 的配置以外，还包含一些 TiDB 用于储存部分集群状态（包括 GC 状态）的记录。请勿手动更改这些记录。其中，与 GC 有关的记录如下： +> +> - `tikv_gc_leader_uuid`，`tikv_gc_leader_desc` 和 `tikv_gc_leader_lease` 用于记录 GC leader 的状态 +> - `tikv_gc_last_run_time`：上次 GC 运行时间 +> - `tikv_gc_safe_point`：当前 GC 的 safe point + +## `tikv_gc_enable` + +- 控制是否启用 GC。 +- 默认值：`true` + +## `tikv_gc_run_interval` + +- 指定 GC 运行时间间隔。Duration 类型，使用 Go 的 Duration 字符串格式，如 `"1h30m"`，`"15m"` 等。 +- 默认值：`"10m0s"` + +## `tikv_gc_life_time` + +- 每次 GC 时，保留数据的时限。Duration 类型。每次 GC 时将以当前时间减去该配置的值作为 safe point。 +- 默认值：`"10m0s"` + +> **注意：** +> +> - `tikv_gc_life_time` 的值必须大于 TiDB 的配置文件中的 [`max-txn-time-use`](/reference/configuration/tidb-server/configuration-file.md#max-txn-time-use) 的值至少 10 秒，且不低于 10 分钟。 +> +> - 在数据更新频繁的场景下，如果将 `tikv_gc_life_time` 设置得比较大（如数天甚至数月），可能会有一些潜在的问题，如： +> - 磁盘空间占用较多。 +> - 大量的历史版本会在一定程度上影响性能，尤其是范围查询（如 `select count(*) from t`）。 + +## `tikv_gc_mode` + +指定 GC 模式。可选值如下： + +- `"distributed"`（默认）：分布式 GC 模式。在此模式下，[Do GC](/reference/garbage-collection/overview.md#do-gc) 阶段由 TiDB 上的 GC leader 向 PD 发送 safe point，每个 TiKV 节点各自获取该 safe point 并对所有当前节点上作为 leader 的 Region 进行 GC。此模式于 TiDB 3.0 引入。 + +- `"central"`：集中 GC 模式。在此模式下，[Do GC](/reference/garbage-collection/overview.md#do-gc) 阶段由 GC leader 向所有的 Region 发送 GC 请求。TiDB 2.1 及更早版本采用此 GC 模式。 + +## `tikv_gc_auto_concurrency` + +控制是否由 TiDB 自动决定 GC concurrency，即同时进行 GC 的线程数。 + +当 `tikv_gc_mode` 设为 `"distributed"`，GC concurrency 将应用于 [Resolve Locks](/reference/garbage-collection/overview.md#resolve-locks) 阶段。当 [`tikv_gc_mode`](#tikv_gc_mode) 设为 `"central"` 时，GC concurrency 将应用于 Resolve Locks 以及 [Do GC](/reference/garbage-collection/overview.md#do-gc) 两个阶段。 + +- `true`（默认）：自动以 TiKV 节点的个数作为 GC concurrency +- `false`：使用 [`tikv_gc_concurrency`](#tikv_gc_concurrency) 的值作为 GC 并发数 + +## `tikv_gc_concurrency` + +- 手动设置 GC concurrency。要使用该参数，必须将 [`tikv_gc_auto_concurrency`](#tikv_gc_auto_concurrency) 设为 `false` 。 +- 默认值：2 + +## 关于 GC 流程的说明 + +从 TiDB 3.0 版本起，由于对分布式 GC 模式和并行 Resolve Locks 的支持，部分配置选项的作用发生了变化。可根据下表理解不同版本中这些配置的区别： + +| 版本/配置 | Resolve Locks | Do GC | +|-------------------|---------------|----------------| +| 2.x | 串行 | 并行 | +| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = false` | 并行 | 并行 | +| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = true` | 自动并行 | 自动并行 | +| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = false` | 并行 | 分布式 | +| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = true`
（默认配置） | 自动并行 | 分布式 | + +表格内容说明： + +- 串行：由 TiDB 逐个向 Region 发送请求。 +- 并行：使用 `tikv_gc_concurrency` 选项所指定的线程数，并行地向每个 Region 发送请求。 +- 自动并行：使用 TiKV 节点的个数作为线程数，并行地向每个 Region 发送请求。 +- 分布式：无需 TiDB 通过对 TiKV 发送请求的方式来驱动，而是每台 TiKV 自行工作。 + +## 流控 + +TiKV 在 3.0.6 版本开始支持 GC 流控，可通过配置 `gc.max-write-bytes-per-sec` 限制 GC worker 每秒数据写入量，降低对正常请求的影响，`0` 为关闭该功能。该配置可通过 tikv-ctl 动态修改： + +{{< copyable "shell-regular" >}} + +```bash +tikv-ctl --host=ip:port modify-tikv-config -m server -n gc.max_write_bytes_per_sec -v 10MB +``` diff --git a/reference/garbage-collection/overview.md b/reference/garbage-collection/overview.md new file mode 100644 index 000000000000..4053b03e3fb7 --- /dev/null +++ b/reference/garbage-collection/overview.md @@ -0,0 +1,40 @@ +--- +title: GC 机制简介 +category: reference +--- + +# GC 机制简介 + +TiDB 的事务的实现采用了 MVCC（多版本并发控制）机制，当新写入的数据覆盖旧的数据时，旧的数据不会被替换掉，而是与新写入的数据同时保留，并以时间戳来区分版本。GC 的任务便是清理不再需要的旧数据。 + +## 整体流程 + +一个 TiDB 集群中会有一个 TiDB 实例被选举为 GC leader，GC 的运行由 GC leader 来控制。 + +GC 会被定期触发，默认情况下每 10 分钟一次。每次 GC 时，首先，TiDB 会计算一个称为 safe point 的时间戳（默认为当前时间减去 10 分钟），接下来 TiDB 会在保证 safe point 之后的快照全部拥有正确数据的前提下，删除更早的过期数据。具体而言，分为以下三个步骤： + +1. Resolve Locks +2. Delete Ranges +3. Do GC + +### Resolve Locks + +TiDB 的事务是基于 [Google Percolator](https://ai.google/research/pubs/pub36726) 模型实现的，事务的提交是一个两阶段提交的过程。第一阶段完成时，所有涉及的 key 会加上一个锁，其中一个锁会被设定为 Primary，其余的锁（Secondary）则会指向 Primary；第二阶段会将 Primary 锁所在的 key 加上一个 Write 记录，并去除锁。这里的 Write 记录就是历史上对该 key 进行写入或删除，或者该 key 上发生事务回滚的记录。Primary 锁被替换为何种 Write 记录标志着该事务提交成功与否。接下来，所有 Secondary 锁也会被依次替换。如果替换这些 Secondary 锁的线程死掉了，锁就残留了下来。 + +Resolve Locks 这一步的任务即对 safe point 之前的锁进行回滚或提交，取决于其 Primary 是否被提交。如果一个 Primary 锁也残留了下来，那么该事务应当视为超时并进行回滚。这一步是必不可少的，因为如果其 Primary 的 Write 记录由于太老而被 GC 清除掉了，那么就再也无法知道该事务是否成功。如果该事务存在残留的 Secondary 锁，那么也无法知道它应当被回滚还是提交，也就无法保证一致性。 + +Resolve Locks 的执行方式是由 GC leader 对所有的 Region 发送请求进行处理。从 3.0 起，这个过程默认会并行地执行，并发数量默认与 TiKV 节点个数相同。 + +### Delete Ranges + +在执行 `DROP TABLE/INDEX` 等操作时，会有大量连续的数据被删除。如果对每个 key 都进行删除操作、再对每个 key 进行 GC 的话，那么执行效率和空间回收速度都可能非常的低下。事实上，这种时候 TiDB 并不会对每个 key 进行删除操作，而是将这些待删除的区间及删除操作的时间戳记录下来。Delete Ranges 会将这些时间戳在 safe point 之前的区间进行快速的物理删除。 + +### Do GC + +这一步即删除所有 key 的过期版本。为了保证 safe point 之后的任何时间戳都具有一致的快照，这一步删除 safe point 之前提交的数据，但是会保留 safe point 前的最后一次写入（除非最后一次写入是删除）。 + +TiDB 2.1 及更早版本使用的 GC 方式是由 GC leader 向所有 Region 发送 GC 请求。从 3.0 起，GC leader 只需将 safe point 上传至 PD。每个 TiKV 节点都会各自从 PD 获取 safe point。当 TiKV 发现 safe point 发生更新时，便会对当前节点上所有作为 leader 的 Region 进行 GC。与此同时，GC leader 可以继续触发下一轮 GC。 + +> **注意：** +> +> 通过修改配置可以继续使用旧的 GC 方式，详情请参考 [GC 配置](/reference/garbage-collection/configuration.md)。 diff --git a/reference/key-monitoring-metrics/overview-dashboard.md b/reference/key-monitoring-metrics/overview-dashboard.md new file mode 100644 index 000000000000..2833f338d023 --- /dev/null +++ b/reference/key-monitoring-metrics/overview-dashboard.md @@ -0,0 +1,87 @@ +--- +title: Overview 面板重要监控指标详解 +category: reference +--- + +# Overview 面板重要监控指标详解 + +使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/how-to/monitor/overview.md)。 + +目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 + +对于日常运维，我们单独挑选出重要的 Metrics 放在 Overview 页面，方便日常运维人员观察集群组件 (PD, TiDB, TiKV) 使用状态以及集群使用状态。 + +以下为 Overview Dashboard 监控说明： + +## Services Port Status + +- Services Online：各服务在线节点数量 +- Services Offline：各服务 Down 掉节点数量 + +## PD + +- Storage Capacity：TiDB 集群总可用数据库空间大小 +- Current Storage Size：TiDB 集群目前已用数据库空间大小 +- Number of Regions：当前集群的 Region 总量 +- Leader Balance Ratio：Leader 数量最多和最少节点相差的百分比，一般小于 5%，节点重启时会有比较大的波动 +- Region Balance Ratio：Region 数量最多和最少节点相差的百分比，一般小于 5%，新增/下线节点时相差比较大 +- Store Status：集群 TiKV 节点的状态 + - Up Stores：正常运行的 TiKV 节点数量 + - Disconnect Stores：短时间内通信异常的 TiKV 节点数量 + - LowSpace Stores：剩余可用空间小于 20% 的 TiKV 节点数量 + - Down Stores：停止工作的 TiKV 节点数量，如果大于 0，说明有节点不正常 + - Offline Stores：正在下线的 TiKV 节点数量（正在下线的 TiKV 节点还在提供服务） + - Tombstone Stores：下线成功的 TiKV 节点数量 +- 99% completed\_cmds\_duration\_seconds：单位时间内，99% 的 pd-server 请求执行时间小于监控曲线的值，一般 <= 5ms +- handle\_requests\_duration\_seconds：PD 发送请求的网络耗时 + +## TiDB + +- Statement OPS：SQL 执行数量统计（包含 select、insert、update 等） +- Duration：SQL 执行的时间 +- QPS By Instance：每个 TiDB 上的 QPS +- Failed Query OPM：失败 SQL 的统计，例如语法错误、主键冲突等 +- Connection count：每个 TiDB 的连接数 +- Heap Memory Usage：每个 TiDB 使用的堆内存大小 +- Transaction OPS：事务执行数量统计 +- Transaction Duration：事务执行的时间 +- KV Cmd OPS：KV 命令执行数量统计 +- KV Cmd Duration 99：KV 命令执行的时间 +- PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 +- PD TSO Wait Duration：TiDB 从 PD 获取 TS 的时间 +- TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 +- Lock Resolve OPS：事务冲突相关的数量 +- Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 +- KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） + +## TiKV + +- leader：各个 TiKV 节点上 Leader 的数量分布 +- region：各个 TiKV 节点上 Region 的数量分布 +- CPU：各个 TiKV 节点的 CPU 使用率 +- Memory：各个 TiKV 节点的内存使用量 +- store size：各个 TiKV 节点存储的数据量 +- cf size：集群不同 CF 存储的数据量 +- channel full：正常情况显示 No data，如果有了监控值，说明对应 TiKV 节点的消息处理不过来了 +- server report failures：正常情况显示 No data，如果出现了 Unreachable，说明 TiKV 之间通信有问题 +- scheduler pending commands：写入堆积的数量，偶尔出现峰值属于正常现象 +- coprocessor pending requests：正常情况监控为 0 或者数量很少 +- coprocessor executor count：不同类型的查询操作数量 +- coprocessor request duration：TiKV 中查询消耗的时间 +- raft store CPU：raftstore 线程的 CPU 使用率，线程数量默认为 2 (通过 `raftstore.store-pool-size` 配置)。如果单个线程使用率超过 80%，说明使用率很高 +- Coprocessor CPU：TiKV 查询线程的 CPU 使用率，和业务相关，复杂查询会使用大量的 CPU 资源 + +## System Info + +- Vcores：CPU 核心数量 +- Memory：内存总大小 +- CPU Usage：CPU 使用率，最大为 100% +- Load [1m]：1 分钟的负载情况 +- Memory Available：剩余内存大小 +- Network Traffic：网卡流量统计 +- TCP Retrans：网络监控，TCP 相关信息统计 +- IO Util：磁盘使用率，最高为 100%，一般到 80% - 90% 就需要考虑加节点 + +## 图例 + +![overview](/media/overview.png) diff --git a/reference/key-monitoring-metrics/pd-dashboard.md b/reference/key-monitoring-metrics/pd-dashboard.md new file mode 100644 index 000000000000..93a7bf9ff2ac --- /dev/null +++ b/reference/key-monitoring-metrics/pd-dashboard.md @@ -0,0 +1,139 @@ +--- +title: PD 重要监控指标详解 +category: reference +--- + +# PD 重要监控指标详解 + +使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/how-to/monitor/overview.md)。 + +目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 + +对于日常运维，我们通过观察 PD 面板上的 Metrics，可以了解 PD 当前的状态。 + +以下为 PD Dashboard 监控说明： + +## Cluster + +- PD role：当前 PD 的角色 +- Storage capacity：TiDB 集群总可用数据库空间大小 +- Current storage size：TiDB 集群目前已用数据库空间大小 +- Current storage usage：TiDB 集群存储空间的使用率 +- Normal stores：处于正常状态的节点数目 +- Number of Regions：当前集群的 Region 总量 +- PD scheduler config：PD 调度配置列表 +- Region label isolation level：不同 label 所在的 level 的 Region 数量 +- Label distribution：集群中 TiKV 节点的 label 分布情况 +- Abnormal stores：处于异常状态的节点数目，正常情况应当为 0 +- pd_cluster_metadata：记录集群 ID，时间戳和生成的 ID +- Current peer count：当前集群 peer 的总量 +- Region health：每个 Region 的状态，通常情况下，pending 的 peer 应该少于 100，miss 的 peer 不能一直大于 0 + +![PD Dashboard - Cluster metrics](/media/pd-dashboard-cluster-v2.png) + +## Operator + +- Schedule operator create：新创建的不同 operator 的数量 +- Schedule operator check：已检查的 operator 的数量，主要检查是否当前步骤已经执行完成，如果是，则执行下一个步骤 +- Schedule operator finish：已完成调度的 operator 的数量 +- Schedule operator timeout：已超时的 operator 的数量 +- Schedule operator replaced or canceled：已取消或者被替换的 operator 的数量 +- Schedule operators count by state：不同状态的 operator 的数量 +- 99% Operator finish duration：99% 已完成 operator 所花费的最长时间 +- 50% Operator finish duration：50% 已完成 operator 所花费的最长时间 +- 99% Operator step duration：99% 已完成的 operator 步骤所花费的最长时间 +- 50% Operator step duration：50% 已完成的 operator 步骤所花费的最长时间 + +![PD Dashboard - Operator metrics](/media/pd-dashboard-operator-v2.png) + +## Statistics - Balance + +- Store capacity：每个 TiKV 实例的总的空间大小 +- Store available：每个 TiKV 实例的可用空间大小 +- Store used：每个 TiKV 实例的已使用空间大小 +- Size amplification：每个 TiKV 实例的空间放大比率 +- Size available ratio：每个 TiKV 实例的可用空间比率 +- Store leader score：每个 TiKV 实例的 leader 分数 +- Store Region score：每个 TiKV 实例的 Region 分数 +- Store leader size：每个 TiKV 实例上所有 leader 的大小 +- Store Region size：每个 TiKV 实例上所有 Region 的大小 +- Store leader count：每个 TiKV 实例上所有 leader 的数量 +- Store Region count：每个 TiKV 实例上所有 Region 的数量 + +![PD Dashboard - Balance metrics](/media/pd-dashboard-balance-v2.png) + +## Statistics - hotspot + +- Hot write Region's leader distribution：每个 TiKV 实例上是写入热点的 leader 的数量 +- Hot write Region's peer distribution：每个 TiKV 实例上是写入热点的 peer 的数量 +- Hot write Region's leader written bytes：每个 TiKV 实例上热点的 leader 的写入大小 +- Hot write Region's peer written bytes：每个 TiKV 实例上热点的 peer 的写入大小 +- Hot read Region's leader distribution：每个 TiKV 实例上是读取热点的 leader 的数量 +- Hot read Region's peer distribution：每个 TiKV 实例上是读取热点的 peer 的数量 +- Hot read Region's leader read bytes：每个 TiKV 实例上热点的 leader 的读取大小 +- Hot read Region's peer read bytes：每个 TiKV 实例上热点的 peer 的读取字节数 + +![PD Dashboard - Hotspot metrics](/media/pd-dashboard-hotspot.png) + +## Scheduler + +- Scheduler is running：所有正在运行的 scheduler +- Balance leader movement：leader 移动的详细情况 +- Balance Region movement：Region 移动的详细情况 +- Balance leader event：balance leader 的事件数量 +- Balance Region event：balance Region 的事件数量 +- Balance leader scheduler：balance-leader scheduler 的状态 +- Balance Region scheduler：balance-region scheduler 的状态 +- Namespace checker：namespace checker 的状态 +- Replica checker：replica checker 的状态 +- Region merge checker：merge checker 的状态 +- Filter target：尝试选择 Store 作为调度 taget 时没有通过 Filter 的计数 +- Filter source：尝试选择 Store 作为调度 source 时没有通过 Filter 的计数 +- Balance Direction：Store 被选作调度 target 或 source 的次数 +- Store Limit：Store 的调度限流状态 + +![PD Dashboard - Scheduler metrics](/media/pd-dashboard-scheduler-v2.png) + +## gRPC + +- Completed commands rate：gRPC 命令的完成速率 +- 99% Completed commands duration：99% 命令的最长消耗时间 + +![PD Dashboard - gRPC metrics](/media/pd-dashboard-grpc-v2.png) + +## etcd + +- Handle transactions count：etcd 的事务个数 +- 99% Handle transactions duration：99% 的情况下，处理 etcd 事务所需花费的时间 +- 99% WAL fsync duration：99% 的情况下，持久化 WAL 所需花费的时间，这个值通常应该小于 1s +- 99% Peer round trip time seconds：99% 的情况下，etcd 的网络延时，这个值通常应该小于 1s +- etcd disk WAL fsync rate：etcd 持久化 WAL 的速率 +- Raft term：当前 Raft 的 term +- Raft committed index：最后一次 commit 的 Raft index +- Raft applied index：最后一次 apply 的 Raft index + +![PD Dashboard - etcd metrics](/media/pd-dashboard-etcd-v2.png) + +## TiDB + +- Handle requests count：TiDB 的请求数量 +- Handle requests duration：每个请求所花费的时间，99% 的情况下，应该小于 100ms + +![PD Dashboard - TiDB metrics](/media/pd-dashboard-tidb-v2.png) + +## Heartbeat + +- Region heartbeat report：TiKV 向 PD 发送的心跳个数 +- Region heartbeat report error：TiKV 向 PD 发送的异常的心跳个数 +- Region heartbeat report active：TiKV 向 PD 发送的正常的心跳个数 +- Region schedule push：PD 向 TiKV 发送的调度命令的个数 +- 99% Region heartbeat latency：99% 的情况下，心跳的延迟 + +![PD Dashboard - Heartbeat metrics](/media/pd-dashboard-heartbeat-v2.png) + +## Region storage + +- Syncer Index：Leader 记录 Region 变更历史的最大 index +- history last index：Follower 成功同步的 Region 变更历史的 index + +![PD Dashboard - Region storage](/media/pd-dashboard-region-storage.png) diff --git a/reference/key-monitoring-metrics/tidb-dashboard.md b/reference/key-monitoring-metrics/tidb-dashboard.md new file mode 100644 index 000000000000..6b086936093d --- /dev/null +++ b/reference/key-monitoring-metrics/tidb-dashboard.md @@ -0,0 +1,139 @@ +--- +title: TiDB 重要监控指标详解 +category: reference +--- + +# TiDB 重要监控指标详解 + +使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/how-to/monitor/overview.md)。 + +目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等，TiDB 分为 TiDB 和 TiDB Summary 面板（其中 TiDB 面板包含 TiDB Summary 面板的内容）。 + +以下为 TiDB Dashboard 部分监控说明： + +## 说明 + +- Query Summary + - Duration：SQL 执行的时间 + - QPS：每个 TiDB 上的 SQL 执行结果按照 OK/Error 统计 + - Statement OPS：SQL 执行数量统计（包含 `SELECT`、`INSERT`、`UPDATE` 等） + - QPS By Instance：每个 TiDB 上的 QPS + - Failed Query OPM：每个 TiDB 实例上，执行 SQL 语句发生错误按照错误类型的统计（例如语法错误、主键冲突等） + - Slow query：慢查询处理时间统计（整个慢查询耗时、Coprocessor 耗时、Coprocessor 调度等待时间） + - 999/99/95/80 Duration：不同类型的 SQL 语句执行耗时统计（不同百分位） + +- Query Detail + - Duration 80/95/99/999 By Instance：每个 TiDB 实例执行 SQL 语句的耗时统计（不同百分位） + - Failed Query OPM Detail：整个集群执行 SQL 语句发生的错误按照错误类型统计（例如语法错误、主键冲突等） + - Internal SQL OPS：TiDB 内部 SQL 语句执行数量统计 + +- Server + - Uptime：TiDB 运行时间 + - Memory Usage：不同 TiDB 实例的内存使用统计 + - CPU Usage：不同 TiDB 实例的 CPU 使用统计 + - Connection Count：每个 TiDB 的连接数 + - Open FD Count：不同 TiDB 实例的打开的文件描述符统计 + - Goroutine Count：不同 TiDB 实例的 Goroutine 数量 + - Go GC Duration：不同 TiDB 实例的 GC 耗时统计 + - Go Threads：不同 TiDB 实例的线程数量 + - Go GC Count：不同 TiDB 实例的 GC 执行次数统计 + - Go GC CPU Usage：不同 TiDB 实例的 GC CPU 统计 + - Events OPM：统计关键事件，例如 start，close，graceful-shutdown，kill，hang 等 + - Keep Alive OPM：不同 TiDB 实例每分钟刷新监控的次数 + - Prepare Statement Count：不同 TiDB 实例执行 Prepare 语句数以及总数统计 + - Time Jump Back OPS：不同 TiDB 实例上每秒钟时间回跳的次数 + - Heap Memory Usage：每个 TiDB 使用的堆内存大小 + - Uncommon Error OPM：TiDB 非正常错误的统计，包括 panic，binlog 写失败等 + - Handshake Error OPS：不同 TiDB 实例每秒握手错误的次数统计 + - Get Token Duration：建立连接后获取 Token 耗时 + +- Transaction + - Transaction OPS：事务执行数量统计 + - Duration：事务执行的时间 + - Transaction Retry Num：事务重试次数 + - Transaction Statement Num：一个事务中的 SQL 语句数量 + - Session Retry Error OPS：事务重试时遇到的错误数量 + - Local Latch Wait Duration：本地事务等待时间 + +- Executor + - Parse Duration：SQL 语句解析耗时统计 + - Compile Duration：将 SQL AST 编译成执行计划耗时统计 + - Execution Duration：SQL 语句执行耗时统计 + - Expensive Executor OPS：消耗系统资源比较多的算子统计，包括 Merge Join，Hash Join，Index Look Up Join，Hash Agg，Stream Agg，Sort，TopN 等 + - Queries Using Plan Cache OPS：使用 Plan Cache 的查询数量统计 + +- Distsql + - Distsql Duration：Distsql 处理的时长 + - Distsql QPS：Distsql 的数量统计 + - Distsql Partial QPS：每秒 Partial Results 的数量 + - Scan Keys Num：每个 Query 扫描的 Key 的数量 + - Scan Keys Partial Num：每一个 Partial Result 扫描的 Key 的数量 + - Partial Num：每个 SQL 语句 Partial Results 的数量 + +- KV Errors + - KV Retry Duration：KV 重试请求的时间 + - TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 + - KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） + - Lock Resolve OPS：事务冲突相关的数量 + - Other Errors OPS：其他类型的错误数量，包括清锁和更新 SafePoint + +- KV Duration + - KV Request Duration 999 by store：KV Request 执行时间，根据 TiKV 显示 + - KV Request Duration 999 by type：KV Request 执行时间，根据请求类型显示 + - KV Cmd Duration 99/999：KV 命令执行的时间 + +- KV Count + - KV Cmd OPS：KV 命令执行数量统计 + - KV Txn OPS：启动事务的数量统计 + - Txn Regions Num 90：事务使用的 Region 数量统计 + - Txn Write Size Bytes 100：事务写入的字节数统计 + - Txn Write KV Num 100：事务写入的 KV 数量统计 + - Load SafePoint OPS：更新 SafePoint 的数量统计 + +- PD Client + - PD Client CMD OPS：PD Client 执行命令数量统计 + - PD Client CMD Duration: PD Client 执行命令耗时 + - PD Client CMD Fail OPS：PD Client 执行命令失败统计 + - PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 + - PD TSO Wait Duration：TiDB 从 PD 获取 TSO 的时间 + - PD TSO RPC Duration：TiDB 从调用 PD 获取 TSO gRPC 接口花费的时间 + +- Schema Load + - Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 + - Load Schema OPS：TiDB 从 TiKV 获取 Schema 的数量统计 + - Schema Lease Error OPM：Schema Lease 出错，包括 change 和 outdate 两种，出现 outdate 错误时会报警 + +- DDL + - DDL Duration 95：DDL 语句处理时间统计 + - Batch Add Index Duration 100：创建索引时每个 Batch 所花费的时间统计 + - DDL Waiting Jobs Count：等待的 DDL 任务数量 + - DDL META OPM：DDL 每分钟获取 META 的次数 + - Deploy Syncer Duration：Schema Version Syncer 初始化，重启，清空等操作耗时 + - Owner Handle Syncer Duration：DDL Owner 在执行更新，获取以及检查 Schema Version 的耗时 + - Update Self Version Duration：Schema Version Syncer 更新版本信息耗时 + +- Statistics + - Auto Analyze Duration 95：自动 ANALYZE 耗时统计 + - Auto Analyze QPS：自动 ANALYZE 数量统计 + - Stats Inaccuracy Rate：统计信息不准确度统计 + - Pseudo Estimation OPS：使用假的统计信息优化 SQL 的数量统计 + - Dump Feedback OPS：存储统计信息 Feedback 的数量统计 + - Update Stats OPS：利用 Feedback 更新统计信息的数量统计 + - Significant Feedback：重要的 Feedback 更新统计信息的数量统计 + +- Meta + - AutoID QPS：AutoID 相关操作的数量统计，包括全局 ID 分配、单个 Table AutoID 分配、单个 Table AutoID Rebase 三种操作 + - AutoID Duration：AutoID 相关操作的耗时 + - Meta Operations Duration 99：Meta 操作延迟 + +- GC + - Worker Action OPM：GC 相关操作的数量统计，包括 run\_job，resolve\_lock，delete\_range 等操作 + - Duration 99：GC 相关操作的耗时统计 + - GC Failure OPM：GC 相关操作失败数量统计 + - Action Result OPM：GC 相关操作结果数量统计 + - Too Many Locks Error OPM：GC 清锁过多错误的数量统计 + +- Batch Client + - Pending Request Count by TiKV：等待处理的 Batch 消息数量统计 + - Wait Duration 95：等待处理的 Batch 消息延迟统计 + - Batch Client Unavailable Duration 95：Batch 客户端不可用的时间统计 diff --git a/reference/key-monitoring-metrics/tikv-dashboard.md b/reference/key-monitoring-metrics/tikv-dashboard.md new file mode 100644 index 000000000000..e4623d2d2f6f --- /dev/null +++ b/reference/key-monitoring-metrics/tikv-dashboard.md @@ -0,0 +1,429 @@ +--- +title: TiKV 重要监控指标详解 +category: reference +--- + +# TiKV 重要监控指标详解 + +使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/how-to/monitor/overview.md)。 + +目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 + +对于日常运维，我们通过观察 TiKV 面板上的 Metrics，可以了解 TiKV 当前的状态。 + +以下为 TiKV Dashboard 监控说明： + +## Cluster + +- Store size：每个 TiKV 实例的使用的存储空间的大小 +- Available size：每个 TiKV 实例的可用的存储空间的大小 +- Capacity size：每个 TiKV 实例的存储容量的大小 +- CPU：每个 TiKV 实例 CPU 的使用率 +- Memory：每个 TiKV 实例内存的使用情况 +- IO utilization：每个 TiKV 实例 IO 的使用率 +- MBps：每个 TiKV 实例写入和读取的数据量大小 +- QPS：每个 TiKV 实例上各种命令的 QPS +- Errps：每个 TiKV 实例上 gRPC 消息失败的个数 +- leader：每个 TiKV 实例 leader 的个数 +- Region：每个 TiKV 实例 Region 的个数 + +![TiKV Dashboard - Cluster metrics](/media/tikv-dashboard-cluster.png) + +## Errors + +- Server is busy：各种会导致 server 繁忙的事件个数，如 write stall，channel full 等，正常情况下应当为 0 +- Server report failures：server 报错的消息个数，正常情况下应当为 0 +- Raftstore error：每个 TiKV 实例上 raftstore 发生错误的个数 +- Scheduler error：每个 TiKV 实例上 scheduler 发生错误的个数 +- Coprocessor error：每个 TiKV 实例上 coprocessor 发生错误的个数 +- gRPC message error：每个 TiKV 实例上 gRPC 消息发生错误的个数 +- Leader drop：每个 TiKV 实例上 drop leader 的个数 +- Leader missing：每个 TiKV 实例上 missing leader 的个数 + +![TiKV Dashboard - Errors metrics](/media/tikv-dashboard-errors.png) + +## Server + +- Leader：每个 TiKV 实例 leader 的个数 +- Region：每个 TiKV 实例 Region 的个数 +- CF size：每个 CF 的大小 +- Store size：每个 TiKV 实例的使用的存储空间的大小 +- Channel full：每个 TiKV 实例上 channel full 错误的数量，正常情况下应当为 0 +- Server report failures：server 报错的消息个数，正常情况下应当为 0 +- Region average written keys：每个 TiKV 实例上所有 Region 的平均 key 写入个数 +- Region average written bytes：每个 TiKV 实例上所有 Region 的平均写入大小 +- Active written leaders：每个 TiKV 实例上有效的 leader 个数 +- Approximate Region size：每个 Region 近似的大小 + +![TiKV Dashboard - Server metrics](/media/tikv-dashboard-server.png) + +## Raft IO + +- Apply log duration：Raft apply 日志所花费的时间 +- Apply log duration per server：每个 TiKV 实例上 Raft apply 日志所花费的时间 +- Append log duration：Raft append 日志所花费的时间 +- Append log duration per server：每个 TiKV 实例上 Raft append 日志所花费的时间 + +![TiKV Dashboard - Raft IO metrics](/media/tikv-dashboard-raftio.png) + +## Raft process + +- Ready handled：Raft 中不同 ready 类型的个数 +- Process ready duration per server：每个 TiKV 实例处理 ready 所花费的时间，99.99% 的情况下，应该小于 2s +- Process tick duration per server：每个 TiKV 实例处理 tick 所花费的时间 +- 0.99 Duration of Raft store events：99% 的 raftstore 事件所花费的时间 + +![TiKV Dashboard - Raft process metrics](/media/tikv-dashboard-raft-process.png) + +## Raft message + +- Sent messages per server：每个 TiKV 实例发送 Raft 消息的个数 +- Flush messages per server：每个 TiKV 实例持久化 Raft 消息的个数 +- Receive messages per server：每个 TiKV 实例接受 Raft 消息的个数 +- Messages：发送不同类型的 Raft 消息的个数 +- Vote：Raft 投票消息发送的个数 +- Raft dropped messages：丢弃不同类型的 Raft 消息的个数 + +![TiKV Dashboard - Raft message metrics](/media/tikv-dashboard-raft-message.png) + +## Raft propose + +- Raft proposals per ready：在一个 mio tick 内，所有 Region proposal 的个数 +- Raft read/write proposals：不同类型的 proposal 的个数 +- Raft read proposals per server：每个 TiKV 实例发起读 proposal 的个数 +- Raft write proposals per server：每个 TiKV 实例发起写 proposal 的个数 +- Propose wait duration：每个 proposal 的等待时间 +- Propose wait duration per server：每个 TiKV 实例上每个 proposal 的等待时间 +- Raft log speed：peer propose 日志的速度 + +![TiKV Dashboard - Raft propose metrics](/media/tikv-dashboard-raft-propose.png) + +## Raft admin + +- Admin proposals：admin proposal 的个数 +- Admin apply：apply 命令的个数 +- Check split：split check 命令的个数 +- 99.99% Check split duration：99.99% 的情况下，split check 所需花费的时间 + +![TiKV Dashboard - Raft admin metrics](/media/tikv-dashboard-raft-admin.png) + +## Local reader + +- Local reader requests：所有请求的总数以及 local read 线程拒绝的请求数量 +- Local read requests duration：local read 请求的等待时间 +- Local read requests batch size：local read 请求的批量大小 + +![TiKV Dashboard - Local reader metrics](/media/tikv-dashboard-local-reader.png) + +## Storage + +- Storage command total：收到不同命令的个数 +- Storage async request error：异步请求出错的个数 +- Storage async snapshot duration：异步处理 snapshot 所花费的时间，99% 的情况下，应该小于 1s +- Storage async write duration：异步写所花费的时间，99% 的情况下，应该小于 1s + +![TiKV Dashboard - Storage metrics](/media/tikv-dashboard-storage.png) + +## Scheduler + +- Scheduler stage total：每种命令不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler priority commands：不同优先级命令的个数 +- Scheduler pending commands：每个 TiKV 实例上 pending 命令的个数 + +![TiKV Dashboard - Scheduler metrics](/media/tikv-dashboard-scheduler.png) + +## Scheduler - batch_get + +- Scheduler stage total：batch_get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 batch_get 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：batch_get 命令读取 key 的个数 +- Scheduler keys written：batch_get 命令写入 key 的个数 +- Scheduler scan details：执行 batch_get 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details：执行 batch_get 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 batch_get 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 batch_get 命令时，扫描每个 default CF 中 key 的详细情况 + +![TiKV Dashboard - Scheduler - batch_get metrics](/media/tikv-dashboard-scheduler-batch-get.png) + +## Scheduler - cleanup + +- Scheduler stage total：cleanup 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 cleanup 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：cleanup 命令读取 key 的个数 +- Scheduler keys written：cleanup 命令写入 key 的个数 +- Scheduler scan details：执行 cleanup 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 cleanup 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 cleanup 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 cleanup 命令时，扫描每个 default CF 中 key 的详细情况 + +![TiKV Dashboard - Scheduler - cleanup metrics](/media/tikv-dashboard-scheduler-cleanup.png) + +## Scheduler - commit + +- Scheduler stage total：commit 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 commit 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：commit 命令读取 key 的个数 +- Scheduler keys written：commit 命令写入 key 的个数 +- Scheduler scan details：执行 commit 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 commit 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 commit 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 commit 命令时，扫描每个 default CF 中 key 的详细情况 + +![TiKV Dashboard - Scheduler commit metrics](/media/tikv-dashboard-scheduler-commit.png) + +## Scheduler - gc + +- Scheduler stage total：gc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 gc 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：gc 命令读取 key 的个数 +- Scheduler keys written：gc 命令写入 key 的个数 +- Scheduler scan details：执行 gc 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 gc 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 gc 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 gc 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - get + +- Scheduler stage total：get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 get 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：get 命令读取 key 的个数 +- Scheduler keys written：get 命令写入 key 的个数 +- Scheduler scan details：执行 get 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 get 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 get 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 get 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - key_mvcc + +- Scheduler stage total：key_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 key_mvcc 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：key_mvcc 命令读取 key 的个数 +- Scheduler keys written：key_mvcc 命令写入 key 的个数 +- Scheduler scan details：执行 key_mvcc 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 key_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 key_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 key_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - prewrite + +- Scheduler stage total：prewrite 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 prewrite 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：prewrite 命令读取 key 的个数 +- Scheduler keys written：prewrite 命令写入 key 的个数 +- Scheduler scan details：执行 prewrite 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 prewrite 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 prewrite 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 prewrite 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - resolve_lock + +- Scheduler stage total：resolve_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 resolve_lock 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：resolve_lock 命令读取 key 的个数 +- Scheduler keys written：resolve_lock 命令写入 key 的个数 +- Scheduler scan details：执行 resolve_lock 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 resolve_lock 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 resolve_lock 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 resolve_lock 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - scan + +- Scheduler stage total：scan 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 scan 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：scan 命令读取 key 的个数 +- Scheduler keys written：scan 命令写入 key 的个数 +- Scheduler scan details：执行 scan 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 scan 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 scan 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 scan 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - scan_lock + +- Scheduler stage total：scan_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 scan_lock 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：scan_lock 命令读取 key 的个数 +- Scheduler keys written：scan_lock 命令写入 key 的个数 +- Scheduler scan details：执行 scan_lock 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 scan_lock 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 scan_lock 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 scan_lock 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - start_ts_mvcc + +- Scheduler stage total：start_ts_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 start_ts_mvcc 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：start_ts_mvcc 命令读取 key 的个数 +- Scheduler keys written：start_ts_mvcc 命令写入 key 的个数 +- Scheduler scan details：执行 start_ts_mvcc 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 start_ts_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 start_ts_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 start_ts_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 + +## Scheduler - unsafe_destroy_range + +- Scheduler stage total：unsafe_destroy_range 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 +- Scheduler command duration：执行 unsafe_destroy_range 命令所需花费的时间，正常情况下，应该小于 1s +- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s +- Scheduler keys read：unsafe_destroy_range 命令读取 key 的个数 +- Scheduler keys written：unsafe_destroy_range 命令写入 key 的个数 +- Scheduler scan details：执行 unsafe_destroy_range 命令时，扫描每个 CF 中 key 的详细情况 +- Scheduler scan details [lock]：执行 unsafe_destroy_range 命令时，扫描每个 lock CF 中 key 的详细情况 +- Scheduler scan details [write]：执行 unsafe_destroy_range 命令时，扫描每个 write CF 中 key 的详细情况 +- Scheduler scan details [default]：执行 unsafe_destroy_range 命令时，扫描每个 default CF 中 key 的详细情况 + +## Coprocessor + +- Request duration：处理 coprocessor 读请求所花费的时间 +- Wait duration：coprocessor 请求的等待时间，99.99% 的情况下，应该小于 10s +- Handle duration：处理 coprocessor 请求所花费的时间 +- 95% Request duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 读请求所花费的时间 +- 95% Wait duration by store：95% 的情况下，每个 TiKV 实例上 coprocessor 请求的等待时间 +- 95% Handle duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 请求所花费的时间 +- Request errors：下推的请求发生错误的个数，正常情况下，短时间内不应该有大量的错误 +- DAG executors：DAG executor 的个数 +- Scan keys：每个请求 scan key 的个数 +- Scan details：scan 每个 CF 的详细情况 +- Table Scan - Details by CF：table scan 针对每个 CF 的详细情况 +- Index Scan - Details by CF：index scan 针对每个 CF 的详细情况 +- Table Scan - Perf Statistics：执行 table sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 +- Index Scan - Perf Statistics：执行 index sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 + +## GC + +- MVCC versions：每个 key 的版本个数 +- MVCC delete versions：GC 删除掉的每个 key 的版本个数 +- GC tasks：由 gc_worker 处理的 GC 任务的个数 +- GC tasks Duration：执行 GC 任务时所花费的时间 +- GC keys (write CF)：在 GC 过程中，write CF 中 受影响的 key 的个数 +- TiDB GC actions result：TiDB Region 层面的 GC 结果 +- TiDB GC worker actions：TiDB GC worker 的不同 action 的个数 +- TiDB GC seconds：TiDB 执行 GC 花费的时间 +- TiDB GC failure：TiDB GC job 失败的个数 +- GC lifetime：TiDB 设置的 GC lifetime +- GC interval：TiDB 设置的 GC 间隔 + +## Snapshot + +- Rate snapshot message：发送 Raft snapshot 消息的速率 +- 99% Handle snapshot duration：99% 的情况下，处理 snapshot 所需花费的时间 +- Snapshot state count：不同状态的 snapshot 的个数 +- 99.99% Snapshot size：99.99% 的 snapshot 的大小 +- 99.99% Snapshot KV count：99.99% 的 snapshot 包含的 key 的个数 + +## Task + +- Worker handled tasks：worker 处理的任务个数 +- Worker pending tasks：当前 worker 中，pending 和 running 的任务个数，正常情况下，应该小于 1000 +- FuturePool handled tasks：future pool 处理的任务个数 +- FuturePool pending tasks：当前 future pool 中，pending 和 running 的任务个数 + +## Thread CPU + +- Raft store CPU：raftstore 线程的 CPU 使用率，通常应低于 80% +- Async apply CPU：async apply 线程的 CPU 使用率，通常应低于 90% +- Scheduler CPU：scheduler 线程的 CPU 使用率，通常应低于 80% +- Scheduler worker CPU：scheduler worker 线程的 CPU 使用率 +- Storage ReadPool CPU：Readpool 线程的 CPU 使用率 +- Coprocessor CPU：coprocessor 线程的 CPU 使用率 +- Snapshot worker CPU：snapshot worker 线程的 CPU 使用率 +- Split check CPU：split check 线程的 CPU 使用率 +- RocksDB CPU：RocksDB 线程的 CPU 使用率 +- gRPC poll CPU：gRPC 线程的 CPU 使用率，通常应低于 80% + +## RocksDB - kv + +- Get operations：get 操作的个数 +- Get duration：get 操作的耗时 +- Seek operations：seek 操作的个数 +- Seek duration：seek 操作的耗时 +- Write operations：write 操作的个数 +- Write duration：write 操作的耗时 +- WAL sync operations：sync WAL 操作的个数 +- WAL sync duration：sync WAL 操作的耗时 +- Compaction operations：compaction 和 flush 操作的个数 +- Compaction duration：compaction 和 flush 操作的耗时 +- SST read duration：读取 SST 所需的时间 +- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 +- Memtable size：每个 CF 的 memtable 的大小 +- Memtable hit：memtable 的命中率 +- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 +- Block cache hit：block cache 的命中率 +- Block cache flow：不同 block cache 操作的流量 +- Block cache operations 不同 block cache 操作的个数 +- Keys flow：不同操作造成的 key 的流量 +- Total keys：每个 CF 中 key 的个数 +- Read flow：不同读操作的流量 +- Bytes / Read：每次读的大小 +- Write flow：不同写操作的流量 +- Bytes / Write：每次写的大小 +- Compaction flow：compaction 相关的流量 +- Compaction pending bytes：等待 compaction 的大小 +- Read amplification：每个 TiKV 实例的读放大 +- Compression ratio：每一层的压缩比 +- Number of snapshots：每个 TiKV 的 snapshot 的数量 +- Oldest snapshots duration：最旧的 snapshot 保留的时间 +- Number files at each level：每一层的文件个数 +- Ingest SST duration seconds：ingest SST 所花费的时间 +- Stall conditions changed of each CF：每个 CF stall 的原因 + +## RocksDB - raft + +- Get operations：get 操作的个数 +- Get duration：get 操作的耗时 +- Seek operations：seek 操作的个数 +- Seek duration：seek 操作的耗时 +- Write operations：write 操作的个数 +- Write duration：write 操作的耗时 +- WAL sync operations：sync WAL 操作的个数 +- WAL sync duration：sync WAL 操作的耗时 +- Compaction operations：compaction 和 flush 操作的个数 +- Compaction duration：compaction 和 flush 操作的耗时 +- SST read duration：读取 SST 所需的时间 +- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 +- Memtable size：每个 CF 的 memtable 的大小 +- Memtable hit：memtable 的命中率 +- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 +- Block cache hit：block cache 的命中率 +- Block cache flow：不同 block cache 操作的流量 +- Block cache operations 不同 block cache 操作的个数 +- Keys flow：不同操作造成的 key 的流量 +- Total keys：每个 CF 中 key 的个数 +- Read flow：不同读操作的流量 +- Bytes / Read：每次读的大小 +- Write flow：不同写操作的流量 +- Bytes / Write：每次写的大小 +- Compaction flow：compaction 相关的流量 +- Compaction pending bytes：等待 compaction 的大小 +- Read amplification：每个 TiKV 实例的读放大 +- Compression ratio：每一层的压缩比 +- Number of snapshots：每个 TiKV 的 snapshot 的数量 +- Oldest snapshots duration：最旧的 snapshot 保留的时间 +- Number files at each level：每一层的文件个数 +- Ingest SST duration seconds：ingest SST 所花费的时间 +- Stall conditions changed of each CF：每个 CF stall 的原因 + +## gRPC + +- gRPC message count：每种 gRPC 消息的个数 +- gRPC message failed：失败的 gRPC 消息的个数 +- 99% gRPC message duration：在 99% gRPC 消息的执行时间 +- gRPC GC message count：gRPC GC 消息的个数 +- 99% gRPC KV GC message duration：在 99% 情况下，gRPC GC 消息的执行时间 + +## PD + +- PD requests：TiKV 发送给 PD 的请求个数 +- PD request duration (average)：TiKV 发送给 PD 的请求所需的平均时间 +- PD heartbeats：发送给 PD 的心跳个数 +- PD validate peers：通过 PD 验证 TiKV 的 peer 有效的个数 diff --git a/reference/mysql-compatibility.md b/reference/mysql-compatibility.md new file mode 100644 index 000000000000..3f619cfe2eca --- /dev/null +++ b/reference/mysql-compatibility.md @@ -0,0 +1,226 @@ +--- +title: 与 MySQL 兼容性对比 +category: reference +--- + +# 与 MySQL 兼容性对比 + +TiDB 支持 MySQL 传输协议及其绝大多数的语法。这意味着您现有的 MySQL 连接器和客户端都可以继续使用。大多数情况下您现有的应用都可以迁移至 TiDB，无需任何代码修改。 + +当前 TiDB 服务器官方支持的版本为 MySQL 5.7。大部分 MySQL 运维工具（如 PHPMyAdmin, Navicat, MySQL Workbench 等），以及备份恢复工具（如 mysqldump, Mydumper/myloader）等都可以直接使用。 + +不过一些特性由于在分布式环境下没法很好的实现，目前暂时不支持或者是表现与 MySQL 有差异。一些 MySQL 语法在 TiDB 中可以解析通过，但是不会做任何后续的处理，例如 `Create Table` 语句中 `Engine`，是解析并忽略。 + +> **注意：** +> +> 本页内容仅涉及 MySQL 与 TiDB 的总体差异。关于[安全特性](/reference/security/compatibility.md)、[悲观事务模型](/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)的兼容信息请查看各自具体页面。 + +## 不支持的特性 + +* 存储过程与函数 +* 触发器 +* 事件 +* 自定义函数 +* 外键约束 +* 全文/空间函数与索引 +* 非 `ascii`/`latin1`/`binary`/`utf8`/`utf8mb4` 的字符集 +* `BINARY` 之外的排序规则 +* 增加/删除主键 +* SYS schema +* MySQL 追踪优化器 +* XML 函数 +* X Protocol +* Savepoints +* 列级权限 +* `XA` 语法（TiDB 内部使用两阶段提交，但并没有通过 SQL 接口公开） +* `CREATE TABLE tblName AS SELECT stmt` 语法 +* `CREATE TEMPORARY TABLE` 语法 +* `CHECK TABLE` 语法 +* `CHECKSUM TABLE` 语法 +* `SELECT INTO FILE` 语法 + +## 与 MySQL 有差异的特性 + +### 自增 ID + +TiDB 中，自增列只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配 ID 的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。 + +在集群中有多个 tidb-server 实例时，如果表结构中有自增 ID，建议不要混用缺省值和自定义值，否则在如下情况下会遇到问题。 + +假设有这样一个带有自增 ID 的表： + +{{< copyable "sql" >}} + +```sql +create table t(id int unique key AUTO_INCREMENT, c int); +``` + +TiDB 实现自增 ID 的原理是每个 tidb-server 实例缓存一段 ID 值用于分配（目前会缓存 30000 个 ID），用完这段值再去取下一段。 + +假设集群中有两个 tidb-server 实例 A 和 B（A 缓存 [1,30000] 的自增 ID，B 缓存 [30001,60000] 的自增 ID），依次执行如下操作： + +1. 客户端向 B 插入一条将 `id` 设置为 1 的语句 `insert into t values (1, 1)`，并执行成功。 +2. 客户端向 A 发送 Insert 语句 `insert into t (c) (1)`，这条语句中没有指定 `id` 的值，所以会由 A 分配，当前 A 缓存了 [1, 30000] 这段 ID，所以会分配 1 为自增 ID 的值，并把本地计数器加 1。而此时数据库中已经存在 `id` 为 1 的数据，最终返回 `Duplicated Error` 错误。 + +另外，从 TiDB 2.1.18 和 3.0.4 版本开始，TiDB 将通过系统变量 `@@tidb_allow_remove_auto_inc` 控制是否允许通过 `alter table modify` 或 `alter table change` 来移除列的 `AUTO_INCREMENT` 属性，默认是不允许移除。 + +### Performance schema + +Performance schema 表在 TiDB 中返回结果为空。TiDB 使用 [Prometheus 和 Grafana](/how-to/monitor/monitor-a-cluster.md) 来监测性能指标。 + +从 TiDB 3.0.4 版本开始，TiDB 支持 `events_statements_summary_by_digest`，参见 [Statement Summary Table](/reference/performance/statement-summary.md)。 + +### 查询计划 + +TiDB 的查询计划（`EXPLAIN`/`EXPLAIN FOR`）输出格式与 MySQL 差别较大，同时 `EXPLAIN FOR` 的输出内容与权限设置与 MySQL 不一致，参见[理解 TiDB 执行计划](/reference/performance/understanding-the-query-execution-plan.md)。 + +### 内建函数 + +TiDB 支持常用的 MySQL 内建函数，但是不是所有的函数都已经支持，具体请参考[语法文档](https://pingcap.github.io/sqlgram/#functioncallkeyword)。 + +### DDL + +在 TiDB 中，运行的 DDL 操作不会影响对表的读取或写入。但是，目前 DDL 变更有如下一些限制： + ++ Add Index + - 不支持同时创建多个索引 + - 不支持 `VISIBLE/INVISIBLE` 的索引 + - 不支持通过 `ALTER TABLE` 在所生成的列上添加索引 + - 其他类型的 Index Type (HASH/BTREE/RTREE) 只有语法支持，功能不支持 ++ Add Column + - 不支持同时创建多个列 + - 不支持将新创建的列设为主键或唯一索引，也不支持将此列设成 AUTO_INCREMENT 属性 ++ Drop Column: 不支持删除主键列或索引列 ++ Change/Modify Column + - 不支持有损变更，比如从 `BIGINT` 变为 `INTEGER`，或者从 `VARCHAR(255)` 变为 `VARCHAR(10)` + - 不支持修改 `DECIMAL` 类型的精度 + - 不支持更改 `UNSIGNED` 属性 + - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` ++ Alter Database + - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` ++ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}`: TiDB 支持的语法，但是在 TiDB 中不会生效。所有支持的 DDL 变更都不会锁表。 ++ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}`: TiDB 完全支持 `ALGORITHM=INSTANT` 和 `ALGORITHM=INPLACE` 语法，但运行过程与 MySQL 有所不同，因为 MySQL 中的一些 `INPLACE` 操作实际上是 TiDB 中的 `INSTANT` 操作。`ALGORITHM=COPY` 语法在 TiDB 中不会生效，会返回警告信息。 ++ Table Option 不支持以下语法 + - `WITH/WITHOUT VALIDATION` + - `SECONDARY_LOAD/SECONDARY_UNLOAD` + - `CHECK/DROP CHECK` + - `STATS_AUTO_RECALC/STATS_SAMPLE_PAGES` + - `SECONDARY_ENGINE` + - `ENCRYPTION` ++ Table Partition 不支持以下语法 + - `PARTITION BY LIST` + - `PARTITION BY KEY` + - `SUBPARTITION` + - `{CHECK|EXCHANGE|TRUNCATE|OPTIMIZE|REPAIR|IMPORT|DISCARD|REBUILD|REORGANIZE} PARTITION` + +### `ANALYZE TABLE` + +- [`ANALYZE TABLE`](/reference/performance/statistics.md#手动收集) 语句在 TiDB 和 MySQL 中表现不同。在 MySQL/InnoDB 中，它是一个轻量级语句，执行过程较短；而在 TiDB 中，它会完全重构表的统计数据，语句执行过程较长。 + +### 视图 + +目前 TiDB 不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 + +### 存储引擎 + +出于兼容性原因，TiDB 支持使用备用存储引擎创建表的语法。元数据命令将表描述为 InnoDB 存储引擎： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT) ENGINE=MyISAM; +``` + +``` +Query OK, 0 rows affected (0.14 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +``` +*************************** 1. row *************************** + Table: t1 +Create Table: CREATE TABLE `t1` ( + `a` int(11) DEFAULT NULL +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +1 row in set (0.00 sec) +``` + +从架构上讲，TiDB 确实支持类似 MySQL 的存储引擎抽象，在启动 TiDB（通常是 `tikv`）时 [`--store`](/reference/configuration/tidb-server/configuration.md#store) 选项指定的引擎中创建用户表。 + +### SQL 模式 + +TiDB 支持 MySQL 5.7 中 **绝大多数的 SQL 模式**，以下几种模式除外： + +- TiDB 不支持兼容模式（例如 `ORACLE` 和 `POSTGRESQL`）。MySQL 5.7 已弃用兼容模式，MySQL 8.0 已移除兼容模式。 +- TiDB 中的 `ONLY_FULL_GROUP_BY` 与 MySQL 5.7 相比有细微的[语义差别](/reference/sql/functions-and-operators/aggregate-group-by-functions.md#与-mysql-的区别)，此问题日后将予以解决。 +- `NO_DIR_IN_CREATE` 和 `NO_ENGINE_SUBSTITUTION` 这两种 SQL 模式用于解决兼容问题，但并不适用于 TiDB。 + +### 默认设置的区别 + ++ 默认字符集与 MySQL 不同： + + TiDB 中为 `utf8mb4` + + MySQL 5.7 中为 `latin1`，MySQL 8.0 中修改为 `utf8mb4` ++ 默认排序规则不同： + + TiDB 中，`utf8mb4` 的默认排序规则为 `utf8mb4_bin` + + MySQL 5.7 中，`utf8mb4` 的默认排序规则为 `utf8mb4_general_ci`，MySQL 8.0 中修改为 `utf8mb4_0900_ai_ci` + + 请使用 [`SHOW CHARACTER SET`](/reference/sql/statements/show-character-set.md) 语句查看所有字符集的默认排序规则 ++ `foreign_key_checks` 的默认值不同： + + TiDB 中该值默认为 `OFF`，并且目前 TiDB 只支持设置该值为 `OFF`。 + + MySQL 5.7 中该值默认为 `ON`。 ++ 默认 SQL mode 与 MySQL 5.7 相同，与 MySQL 8.0 不同： + + TiDB 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` + + MySQL 中默认设置： + + MySQL 5.7 的默认 SQL mode 与 TiDB 相同 + + MySQL 8.0 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION` ++ `lower_case_table_names` 的默认值不同： + + TiDB 中该值默认为 2，并且目前 TiDB 只支持设置该值为 2 + + MySQL 中默认设置： + + Linux 系统中该值为 0 + + Windows 系统中该值为 1 + + macOS 系统中该值为 2 ++ `explicit_defaults_for_timestamp` 的默认值不同： + + TiDB 中该值默认为 `ON`，并且目前 TiDB 只支持设置该值为 `ON` + + MySQL 中默认设置： + + MySQL 5.7：`OFF` + + MySQL 8.0：`ON` + +### 日期时间处理的区别 + +#### 时区 + +MySQL 默认使用本地时区，依赖于系统内置的当前的时区规则（例如什么时候开始夏令时等）进行计算；且在未[导入时区表数据](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation)的情况下不能通过时区名称来指定时区。 + +TiDB 不需要导入时区表数据也能使用所有时区名称，采用系统当前安装的所有时区规则进行计算（一般为 `tzdata` 包），且无法通过导入时区表数据的形式修改计算规则。 + +> **注意：** +> +> 能下推到 TiKV 的时间相关表达式会由 TiKV 进行计算。TiKV 总是采用 TiKV 内置时区规则计算，而不依赖于系统所安装的时区规则。若系统安装的时区规则与 TiKV 内置的时区规则版本不匹配，则在少数情况下可能发生能插入的时间数据无法再读出来的问题。例如，若系统上安装了 tzdata 2018a 时区规则，则在时区设置为 Asia/Shanghai 或时区设置为本地时区且本地时区为 Asia/Shanghai 的情况下，时间 `1988-04-17 02:00:00` 可以被正常插入 TiDB 3.0 RC.1，但该记录对于特定类型 SQL 则无法再读出来，原因是 TiKV 3.0 RC.1 依据的 tzdata 2018i 规则中该时间在 Asia/Shanghai 时区中不存在（夏令时时间后移一小时）。 +> +> TiKV 各个版本内置的时区规则如下： +> +> - 3.0.0 RC.1 及以后：[tzdata 2018i](https://github.com/eggert/tz/tree/2018i) +> - 2.1.0 RC.1 及以后：[tzdata 2018e](https://github.com/eggert/tz/tree/2018e) + +#### 零月和零日 + +目前 TiDB 尚不能完整支持月为 `0` 或日为 `0`（但年不为 `0`）的日期。在非严格模式下，此类日期时间能被正常插入。但对于特定类型的 SQL 语句，可能出现无法读出来的情况。 + +#### 字符串类型行末空格的处理 + +目前 TiDB 在进行数据插入时，对于 `VARCHAR` 类型会保留行末空格，对于 `CHAR` 类型会插入截断空格后的数据。在没有索引的情况下，TiDB 和 MySQL 行为保持一致。如果 `VARCHAR` 类型上有 `UNIQUE` 索引，MySQL 在判断是否重复的时候，和处理 `CHAR` 类型一样，先截断 `VARCHAR` 数据末行空格再作判断；TiDB 则是按照保留空格的情况处理。 + +在做比较时，MySQL 会先截去常量和 Column 的末尾空格再作比较，而 TiDB 则是保留常量和 Column 的末尾空格来做精确比较。 + +### 类型系统的区别 + +以下的列类型 MySQL 支持，但 TiDB 不支持： + ++ FLOAT4/FLOAT8 ++ FIXED (alias for DECIMAL) ++ SERIAL (alias for BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE) ++ SQL_TSI_* （包括 SQL_TSI_YEAR、SQL_TSI_MONTH、SQL_TSI_WEEK、SQL_TSI_DAY、SQL_TSI_HOUR、SQL_TSI_MINUTE 和 SQL_TSI_SECOND） diff --git a/reference/performance/check-cluster-status-using-sql-statements.md b/reference/performance/check-cluster-status-using-sql-statements.md new file mode 100644 index 000000000000..6a6b5184a78f --- /dev/null +++ b/reference/performance/check-cluster-status-using-sql-statements.md @@ -0,0 +1,27 @@ +--- +title: 使用 SQL 语句检查 TiDB 集群状态 +category: reference +--- + +# 使用 SQL 语句检查 TiDB 集群状态 + +为了方便排查问题，TiDB 提供了一些 SQL 语句和系统表以查询一些有用的信息。 + +`INFORMATION_SCHEMA` 中提供了如下几个系统表，用于查询集群状态，诊断常见的集群问题。 + +- [`TABLES`](/reference/system-databases/information-schema.md#tables-表) +- [`TIDB_INDEXES`](/reference/system-databases/information-schema.md#tidb_indexes-表) +- [`ANALYZE_STATUS`](/reference/system-databases/information-schema.md#analyze_status-表) +- [`TIDB_HOT_REGIONS`](/reference/system-databases/information-schema.md#tidb_hot_regions-表) +- [`TIKV_STORE_STATUS`](/reference/system-databases/information-schema.md#tikv_store_status-表) +- [`TIKV_REGION_STATUS`](/reference/system-databases/information-schema.md#tikv_region_status-表) +- [`TIKV_REGION_PEERS`](/reference/system-databases/information-schema.md#tikv_region_peers-表) + +除此之外，执行下列语句也可获得对排查问题或查询集群状态有用的信息： + +- `ADMIN SHOW DDL` 可以获得是 `DDL owner` 角色的 TiDB 的 ID 及 `IP:PORT` 等具体信息。 +- `SHOW ANALYZE STATUS` 和 [`ANALYZE_STATUS`](/reference/system-databases/information-schema.md#analyze_status-表) 表的功能相同。 +- 特殊的 `EXPLAIN` 语句： + - `EXPLAIN ANALYZE` 语句可以获得一个 SQL 语句执行中的一些具体信息。 + - `EXPLAIN FOR CONNECTION` 可以获得一个连接中最后执行的查询的执行计划。可以配合 `SHOW PROCESSLIST` 使用。 + - 关于 `EXPLAIN` 相关的更具体的信息，参考文档[理解 TiDB 执行计划](/reference/performance/understanding-the-query-execution-plan.md)。 diff --git a/reference/performance/execution-plan-bind.md b/reference/performance/execution-plan-bind.md new file mode 100644 index 000000000000..af9016be95a3 --- /dev/null +++ b/reference/performance/execution-plan-bind.md @@ -0,0 +1,103 @@ +--- +title: 执行计划绑定 +category: reference +--- + +# 执行计划绑定 + +在[优化器 Hints](/reference/performance/optimizer-hints.md) 中介绍了可以通过 Hint 的方式选择指定的执行计划，但有的时候需要在不修改 SQL 语句的情况下干预执行计划的选择。执行计划绑定提供了一系列功能使得可以在不修改 SQL 语句的情况下选择指定的执行计划。 + +## 语法 + +### 创建绑定 + +{{< copyable "sql" >}} + +```sql +CREATE [GLOBAL | SESSION] BINDING FOR SelectStmt USING SelectStmt; +``` + +该语句可以在 GLOBAL 或者 SESSION 作用域内为 SQL 绑定执行计划。在不指定作用域时，隐式作用域为 SESSION。被绑定的 SQL 会被参数化后存储到系统表中。在处理 SQL 查询时，只要参数化后的 SQL 和系统表中某个被绑定的 SQL 语句一致，并且系统变量 `tidb_use_plan_baselines` 的值为 `on`（其默认值为 `on`），即可使用相应的优化器 Hint。如果存在多个可匹配的执行计划，优化器会从中选择代价最小的一个进行绑定。 + +`参数化`：把 SQL 中的常量变成变量参数，并对 SQL 中的空格和换行符等做标准化处理。例如： + +```sql +select * from t where a > 1 +-- 参数化后： +select * from t where a > ？ +``` + +需要注意的是原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本必须相同，否则创建会失败，例如： + +{{< copyable "sql" >}} + +```sql +CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE a > 2; +``` + +可以创建成功，因为原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本都是 `select * from t where a > ?`，而 + +{{< copyable "sql" >}} + +```sql +CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE b > 2; +``` + +则不可以创建成功，因为原始 SQL 在经过处理后是 `select * from t where a > ?`，而绑定 SQL 在经过处理后是 `select * from t where b > ?`。 + +### 删除绑定 + +{{< copyable "sql" >}} + +```sql +DROP [GLOBAL | SESSION] BINDING FOR SelectStmt; +``` + +该语句可以在 GLOBAL 或者 SESSION 作用域内删除指定的执行计划绑定，在不指定作用域时默认作用域为 SESSION。 + +### 查看绑定 + +{{< copyable "sql" >}} + +```sql +SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere]; +``` + +该语句会输出 GLOBAL 或者 SESSION 作用域内的执行计划绑定，在不指定作用域时默认作用域为 SESSION。目前 `SHOW BINDINGS` 会输出 8 列，具体如下： + +| 列名 | 说明 | +| -------- | ------------- | +| original_sql | 参数化后的原始 SQL | +| bind_sql | 带 Hint 的绑定 SQL | +| default_db | 默认数据库名 | +| status | 状态，包括 using（正在使用）、deleted（已删除）和 invalid（无效） | +| create_time | 创建时间 | +| update_time | 更新时间 | +| charset | 字符集 | +| collation | 排序规则 | + +### 自动创建绑定 + +通过将 `tidb_capture_plan_baselines` 的值设置为 `on`（其默认值为 `off`）可以打开自动创建绑定功能。 + +> **注意：** +> +> 自动绑定功能依赖于 [Statement Summary](/reference/performance/statement-summary.md)，因此在使用自动绑定之前需打开 Statement Summary 开关。 + +开启自动绑定功能后，每隔 `bind-info-lease`（默认值为 `3s`）会遍历一次 Statement Summary 中的历史 SQL 语句，并为至少出现两次的 SQL 语句自动创建绑定。 + +### 自动演进绑定 + +随着数据的变更，有可能原先绑定的执行计划已经不是最优的了，自动演进绑定功能可以自动优化已经绑定的执行计划。 + +{{< copyable "sql" >}} + +```sql +set global tidb_evolve_plan_baselines = on; +``` + +`tidb_evolve_plan_baselines` 的默认值为 `off`。 + +在打开自动演进功能后，如果优化器选出的最优执行计划不在之前绑定的执行计划之中，会将其记录为待验证的执行计划。每隔 `bind-info-lease`（默认值为 `3s`），会选出一个待验证的执行计划，将其和已经绑定的执行计划中代价最小的比较实际运行时间。如果待验证的运行时间更优的话，会将其标记为可使用的绑定。 + +为了减少自动演进对集群的影响，可以通过 `tidb_evolve_plan_task_max_time` 来限制每个执行计划运行的最长时间，其默认值为 `600s`；通过 `tidb_evolve_plan_task_start_time` 和 `tidb_evolve_plan_task_end_time` 可以限制运行演进任务的时间窗口，默认值分别为 `00:00 +0000` 和 `23:59 +0000`。 diff --git a/dev/reference/performance/follower-read.md b/reference/performance/follower-read.md similarity index 100% rename from dev/reference/performance/follower-read.md rename to reference/performance/follower-read.md diff --git a/dev/reference/performance/index-merge.md b/reference/performance/index-merge.md similarity index 97% rename from dev/reference/performance/index-merge.md rename to reference/performance/index-merge.md index 667f9f839b0f..1d7c067a3564 100644 --- a/dev/reference/performance/index-merge.md +++ b/reference/performance/index-merge.md @@ -92,7 +92,7 @@ explain select * from t where a = 1 or b = 1; 默认设置下，`IndexMerge` 是关闭的，开启的方法有两种： - 设置系统变量 `tidb_enable_index_merge` 为 1； -- 在查询中使用 SQL Hint [`USE_INDEX_MERGE`](/dev/reference/performance/optimizer-hints.md#use_index_merget1_name-idx1_name--idx2_name-)； +- 在查询中使用 SQL Hint [`USE_INDEX_MERGE`](/reference/performance/optimizer-hints.md#use_index_merget1_name-idx1_name--idx2_name-)； > **注意：** > diff --git a/dev/reference/performance/optimizer-hints.md b/reference/performance/optimizer-hints.md similarity index 100% rename from dev/reference/performance/optimizer-hints.md rename to reference/performance/optimizer-hints.md diff --git a/dev/reference/performance/sql-optimizer-overview.md b/reference/performance/sql-optimizer-overview.md similarity index 100% rename from dev/reference/performance/sql-optimizer-overview.md rename to reference/performance/sql-optimizer-overview.md diff --git a/dev/reference/performance/statement-summary.md b/reference/performance/statement-summary.md similarity index 100% rename from dev/reference/performance/statement-summary.md rename to reference/performance/statement-summary.md diff --git a/dev/reference/performance/statistics.md b/reference/performance/statistics.md similarity index 100% rename from dev/reference/performance/statistics.md rename to reference/performance/statistics.md diff --git a/dev/reference/performance/tune-tikv.md b/reference/performance/tune-tikv.md similarity index 100% rename from dev/reference/performance/tune-tikv.md rename to reference/performance/tune-tikv.md diff --git a/dev/reference/performance/understanding-the-query-execution-plan.md b/reference/performance/understanding-the-query-execution-plan.md similarity index 100% rename from dev/reference/performance/understanding-the-query-execution-plan.md rename to reference/performance/understanding-the-query-execution-plan.md diff --git a/dev/reference/security/cert-based-authentication.md b/reference/security/cert-based-authentication.md similarity index 100% rename from dev/reference/security/cert-based-authentication.md rename to reference/security/cert-based-authentication.md diff --git a/dev/reference/security/compatibility.md b/reference/security/compatibility.md similarity index 100% rename from dev/reference/security/compatibility.md rename to reference/security/compatibility.md diff --git a/dev/reference/security/privilege-system.md b/reference/security/privilege-system.md similarity index 100% rename from dev/reference/security/privilege-system.md rename to reference/security/privilege-system.md diff --git a/reference/security/role-based-access-control.md b/reference/security/role-based-access-control.md new file mode 100644 index 000000000000..f947656741c1 --- /dev/null +++ b/reference/security/role-based-access-control.md @@ -0,0 +1,386 @@ +--- +title: 基于角色的访问控制 +category: reference +--- + +# 基于角色的访问控制 + +TiDB 的基于角色的访问控制 (RBAC) 系统的实现类似于 MySQL 8.0 的 RBAC 系统。TiDB 兼容大部分 MySQL RBAC 系统的语法。 + +本文档主要介绍 TiDB 基于角色的访问控制相关操作及实现。 + +## 角色访问控制相关操作 + +角色是一系列权限的集合。用户可以创建角色、删除角色、将权限赋予角色；也可以将角色授予给其他用户，被授予的用户在启用角色后，可以得到角色所包含的权限。 + +### 创建角色 + +创建角色 r_1 和 r_2： + +{{< copyable "sql" >}} + +```sql +CREATE ROLE `r_1`@`%`, `r_2`@`%`; +``` + +角色名的格式和规范可以参考 [TiDB 用户账户管理](/reference/security/user-account-management.md)。 + +角色会被保存在 `mysql.user` 表中，如果表中有同名角色或用户，角色会创建失败并报错。 +创建角色的用户需要拥有 `CREATE ROLE` 或 `CREATE USER` 权限。 + +### 删除角色 + +删除角色 r_1 和 r_2： + +{{< copyable "sql" >}} + +```sql +DROP ROLE `r_1`@`%`, `r_2`@`%`; +``` + +这个操作会清除角色在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录，解除和其相关的授权关系。 +执行删除角色的用户需要拥有 `DROP ROLE` 或 `DROP USER` 权限。 + +### 授予角色权限 + +为角色授予权限和为用户授予权限操作相同，可参考 [TiDB 权限管理](/reference/security/privilege-system.md)。 + +为 `analyst` 角色授予数据库 `test` 的读权限： + +{{< copyable "sql" >}} + +```sql +GRANT SELECT ON test.* TO 'analyst'@'%'; +``` + +为 `analyst` 角色授予所有数据库的全部权限： + +{{< copyable "sql" >}} + +```sql +GRANT ALL PRIVILEGES ON *.* TO 'analyst'@'%'; +``` + +### 收回权限 + +`REVOKE` 语句与 `GRANT` 对应： + +{{< copyable "sql" >}} + +```sql +REVOKE ALL PRIVILEGES ON `test`.* FROM 'analyst'@'%'; +``` + +具体可参考 [TiDB 权限管理](/reference/security/privilege-system.md)。 + +### 将角色授予给用户 + +将角色 role1 和 role2 同时授予给用户 `user1@localhost` 和 `user2@localhost`。 + +{{< copyable "sql" >}} + +```sql +GRANT 'role1', 'role2' TO 'user1'@'localhost', 'user2'@'localhost'; +``` + +用户执行将角色授予给其他用户或者收回角色的命令，需要用户拥有 `SUPER` 权限。 +将角色授予给用户时并不会启用该角色，启用角色需要额外的操作。 + +以下操作可能会形成一个“关系环”： + +```sql +CREATE USER 'u1', 'u2'; +CREATE ROLE 'r1', 'r2'; + +GRANT 'u1' TO 'u1'; +GRANT 'r1' TO 'r1'; + +GRANT 'r2' TO 'u2'; +GRANT 'u2' TO 'r2'; +``` + +TiDB 允许这种多层授权关系存在，可以使用多层授权关系实现权限继承。 + +### 收回角色 + +解除角色 role1、role2 与用户 `user1@localhost`、`user2@localhost` 的授权关系。 + +{{< copyable "sql" >}} + +```sql +REVOKE 'role1', 'role2' FROM 'user1'@'localhost', 'user2'@'localhost'; +``` + +解除角色授权具有原子性，如果在撤销授权操作中失败会回滚。 + +### 设置默认启用角色 + +角色在授予给用户之后，并不会生效；只有在用户启用了某些角色之后，才可以使用角色拥有的权限。 + +可以对用户设置默认启用的角色；用户在登陆时，默认启用的角色会被自动启用。 + +{{< copyable "sql" >}} + +```sql +SET DEFAULT ROLE + {NONE | ALL | role [, role ] ...} + TO user [, user ] +``` + +比如将 administrator 和 developer 设置为 `test@localhost` 的默认启用角色： + +{{< copyable "sql" >}} + +```sql +SET DEFAULT ROLE administrator, developer TO 'test'@'localhost'; +``` + +将 `test@localhost` 的所有角色，设为其默认启用角色： + +{{< copyable "sql" >}} + +```sql +SET DEFAULT ROLE ALL TO 'test'@'localhost'; +``` + +关闭 `test@localhost` 的所有默认启用角色： + +{{< copyable "sql" >}} + +```sql +SET DEFAULT ROLE NONE TO 'test'@'localhost'; +``` + +需要注意的是，设置为默认启用角色的角色必须已经授予给那个用户。 + +### 在当前 session 启用角色 + +除了使用 `SET DEFAULT ROLE` 启用角色外，TiDB 还提供让用户在当前 session 启用某些角色的功能。 + +```sql +SET ROLE { + DEFAULT + | NONE + | ALL + | ALL EXCEPT role [, role ] ... + | role [, role ] ... +} +``` + +例如，为当前用户启用角色 role1 和 role2 ，仅在当前 session 有效： + +{{< copyable "sql" >}} + +```sql +SET ROLE 'role1', 'role2'; +``` + +启用当前用户的默认角色： + +{{< copyable "sql" >}} + +```sql +SET ROLE DEFAULT +``` + +启用授予给当前用户的所有角色： + +{{< copyable "sql" >}} + +```sql +SET ROLE ALL +``` + +不启用任何角色： + +{{< copyable "sql" >}} + +```sql +SET ROLE NONE +``` + +启用除 role1 和 role2 外的角色： + +{{< copyable "sql" >}} + +```sql +SET ROLE ALL EXCEPT 'role1', 'role2' +``` + +> **注意：** +> +> 使用 `SET ROLE` 启用的角色只有在当前 session 才会有效。 + +### 查看当前启用角色 + +当前用户可以通过 `CURRENT_ROLE()` 函数查看当前用户启用了哪些角色。 + +例如，先对 `u1'@'localhost` 授予角色： + +{{< copyable "sql" >}} + +```sql +GRANT 'r1', 'r2' TO 'u1'@'localhost'; +``` + +{{< copyable "sql" >}} + +```sql +SET DEFAULT ROLE ALL TO 'u1'@'localhost'; +``` + +在 u1 登陆后： + +{{< copyable "sql" >}} + +```sql +SELECT CURRENT_ROLE(); +``` + +``` ++-------------------+ +| CURRENT_ROLE() | ++-------------------+ +| `r1`@`%`,`r2`@`%` | ++-------------------+ +``` + +{{< copyable "sql" >}} + +```sql +SET ROLE 'r1'; SELECT CURRENT_ROLE(); +``` + +``` ++----------------+ +| CURRENT_ROLE() | ++----------------+ +| `r1`@`%` | ++----------------+ +``` + +### 查看角色拥有的权限 + +可以通过 `SHOW GRANTS` 语句查看用户被授予了哪些角色。 +当用户查看其他用户权限相关信息时，需要对 `mysql` 数据库拥有 `SELECT` 权限。 + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'u1'@'localhost'; +``` + +``` ++---------------------------------------------+ +| Grants for u1@localhost | ++---------------------------------------------+ +| GRANT USAGE ON *.* TO `u1`@`localhost` | +| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | ++---------------------------------------------+ +``` + +可以通过使用 `SHOW GRANTS` 的 `USING` 选项来查看角色对应的权限。 + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'u1'@'localhost' USING 'r1'; +``` + +``` ++---------------------------------------------+ +| Grants for u1@localhost | ++---------------------------------------------+ +| GRANT USAGE ON *.* TO `u1`@`localhost` | +| GRANT Select ON `db1`.* TO `u1`@`localhost` | +| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | ++---------------------------------------------+ +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'u1'@'localhost' USING 'r2'; +``` + +``` ++-------------------------------------------------------------+ +| Grants for u1@localhost | ++-------------------------------------------------------------+ +| GRANT USAGE ON *.* TO `u1`@`localhost` | +| GRANT Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | +| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | ++-------------------------------------------------------------+ +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'u1'@'localhost' USING 'r1', 'r2'; +``` + +``` ++---------------------------------------------------------------------+ +| Grants for u1@localhost | ++---------------------------------------------------------------------+ +| GRANT USAGE ON *.* TO `u1`@`localhost` | +| GRANT Select, Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | +| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | ++---------------------------------------------------------------------+ +``` + +可以使用 `SHOW GRANTS` 或 `SHOW GRANTS FOR CURRENT_USER()` 查看当前用户的权限。 +这两个语句有细微的差异，`SHOW GRANTS` 会显示当前用户的启用角色的权限，而 `SHOW GRANTS FOR CURRENT_USER()` 则不会显示启用角色的权限。 + +### 授权表 + +在原有的四张[系统权限表](/reference/security/privilege-system.md#授权表)的基础上，角色访问控制引入了两张新的系统表： + +- `mysql.role_edges`：记录角色与用户的授权关系 +- `mysql.default_roles`：记录每个用户默认启用的角色 + +以下是 `mysql.role_edges` 所包含的数据。 + +{{< copyable "sql" >}} + +```sql +select * from mysql.role_edges; +``` + +``` ++-----------+-----------+---------+---------+-------------------+ +| FROM_HOST | FROM_USER | TO_HOST | TO_USER | WITH_ADMIN_OPTION | ++-----------+-----------+---------+---------+-------------------+ +| % | r_1 | % | u_1 | N | ++-----------+-----------+---------+---------+-------------------+ +1 row in set (0.00 sec) +``` + +其中 `FROM_HOST` 和 `FROM_USER` 分别表示角色的主机名和用户名，`TO_HOST` 和 `TO_USER` 分别表示被授予角色的用户的主机名和用户名。 + +`mysql.default_roles` 中包含了每个用户默认启用了哪些角色。 + +{{< copyable "sql" >}} + +```sql +select * from mysql.default_roles; +``` + +``` ++------+------+-------------------+-------------------+ +| HOST | USER | DEFAULT_ROLE_HOST | DEFAULT_ROLE_USER | ++------+------+-------------------+-------------------+ +| % | u_1 | % | r_1 | +| % | u_1 | % | r_2 | ++------+------+-------------------+-------------------+ +2 rows in set (0.00 sec) +``` + +`HOST` 和 `USER` 分别表示用户的主机名和用户名，`DEFAULT_ROLE_HOST` 和 `DEFAULT_ROLE_USER` 分别表示默认启用的角色的主机名和用户名。 + +### 其他 + +由于基于角色的访问控制模块和用户管理以及权限管理结合十分紧密，因此需要参考一些操作的细节： + +- [TiDB 权限管理](/reference/security/privilege-system.md) +- [TiDB 用户账户管理](/reference/security/user-account-management.md) diff --git a/reference/security/user-account-management.md b/reference/security/user-account-management.md new file mode 100644 index 000000000000..fda0c6fce7af --- /dev/null +++ b/reference/security/user-account-management.md @@ -0,0 +1,232 @@ +--- +title: TiDB 用户账户管理 +category: reference +--- + +# TiDB 用户账户管理 + +本文档主要介绍如何管理 TiDB 用户账户。 + +## 用户名和密码 + +TiDB 将用户账户存储在 `mysql.user` 系统表里面。每个账户由用户名和 host 作为标识。每个账户可以设置一个密码。 + +通过 MySQL 客户端连接到 TiDB 服务器，通过指定的账户和密码登录： + +{{< copyable "shell-regular" >}} + +``` +mysql --port 4000 --user xxx --password +``` + +使用缩写的命令行参数则是： + +{{< copyable "shell-regular" >}} + +``` +mysql -P 4000 -u xxx -p +``` + +## 添加用户 + +添加用户有两种方式： + +* 通过标准的用户管理的 SQL 语句创建用户以及授予权限，比如 `CREATE USER` 和 `GRANT`。 +* 直接通过 `INSERT`、`UPDATE` 和 `DELETE` 操作授权表。 + +推荐使用第一种方式。第二种方式修改容易导致一些不完整的修改，因此不推荐。还有另一种可选方式是使用第三方工具的图形化界面工具。 + +{{< copyable "sql" >}} + +```sql +CREATE USER [IF NOT EXISTS] + user [auth_spec] [, user [auth_spec]] ... +``` + +{{< copyable "sql" >}} + +```sql +auth_spec: { + IDENTIFIED BY 'auth_string' + | IDENTIFIED BY PASSWORD 'hash_string' +} +``` + +* `IDENTIFIED BY 'auth_string'`：设置登录密码时，`auth_string` 会被 TiDB 经过加密存储在 `mysql.user` 表中。 +* `IDENTIFIED BY PASSWORD 'hash_string'`：设置登录密码，`hash_string` 是一个类似于 `*EBE2869D7542FCE37D1C9BBC724B97BDE54428F1` 的 41 位字符串，会被 TiDB 直接存储在 `mysql.user` 表中，该字符串可以通过 `SELECT password('auth_string')` 加密得到。 + +{{< copyable "sql" >}} + +```sql +CREATE USER 'test'@'127.0.0.1' IDENTIFIED BY 'xxx'; +``` + +TiDB 的用户账户名由一个用户名和一个主机名组成。账户名的语法为 `'user_name'@'host_name'`。 + +- `user_name` 大小写敏感。 +- `host_name` 可以是一个主机名或 IP 地址。主机名或 IP 地址中允许使用通配符 `%` 和 `_`。例如，名为 `'%'` 的主机名可以匹配所有主机，`'192.168.1.%'` 可以匹配子网中的所有主机。 + +host 支持模糊匹配，比如： + +{{< copyable "sql" >}} + +```sql +CREATE USER 'test'@'192.168.10.%'; +``` + +允许 `test` 用户从 `192.168.10` 子网的任何一个主机登录。 + +如果没有指定 host，则默认是所有 IP 均可登录。如果没有指定密码，默认为空： + +{{< copyable "sql" >}} + +```sql +CREATE USER 'test'; +``` + +等价于： + +{{< copyable "sql" >}} + +```sql +CREATE USER 'test'@'%' IDENTIFIED BY ''; +``` + +下面的例子用 `CREATE USER` 和 `GRANT` 语句创建了四个账户： + +{{< copyable "sql" >}} + +```sql +CREATE USER 'finley'@'localhost' IDENTIFIED BY 'some_pass'; +``` + +{{< copyable "sql" >}} + +```sql +GRANT ALL PRIVILEGES ON *.* TO 'finley'@'localhost' WITH GRANT OPTION; +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER 'finley'@'%' IDENTIFIED BY 'some_pass'; +``` + +{{< copyable "sql" >}} + +```sql +GRANT ALL PRIVILEGES ON *.* TO 'finley'@'%' WITH GRANT OPTION; +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass'; +``` + +{{< copyable "sql" >}} + +```sql +GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER 'dummy'@'localhost'; +``` + +使用 `SHOW GRANTS` 可以看到为一个用户授予的权限： + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'admin'@'localhost'; +``` + +``` ++-----------------------------------------------------+ +| Grants for admin@localhost | ++-----------------------------------------------------+ +| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' | ++-----------------------------------------------------+ +``` + +## 删除用户 + +使用 `DROP USER` 语句可以删除用户，例如： + +{{< copyable "sql" >}} + +```sql +DROP USER 'test'@'localhost'; +``` + +这个操作会清除用户在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录。 + +## 保留用户账户 + +TiDB 在数据库初始化时会生成一个 `'root'@'%'` 的默认账户。 + +## 设置资源限制 + +暂不支持。 + +## 设置密码 + +TiDB 将密码存在 `mysql.user` 系统数据库里面。只有拥有 `CREATE USER` 权限，或者拥有 `mysql` 数据库权限（`INSERT` 权限用于创建，`UPDATE` 权限用于更新）的用户才能够设置或修改密码。 + +- 在 `CREATE USER` 创建用户时可以通过 `IDENTIFIED BY` 指定密码： + + {{< copyable "sql" >}} + + ```sql + CREATE USER 'test'@'localhost' IDENTIFIED BY 'mypass'; + ``` + +- 为一个已存在的账户修改密码，可以通过 `SET PASSWORD FOR` 或者 `ALTER USER` 语句完成： + + {{< copyable "sql" >}} + + ```sql + SET PASSWORD FOR 'root'@'%' = 'xxx'; + ``` + + 或者： + + {{< copyable "sql" >}} + + ```sql + ALTER USER 'test'@'localhost' IDENTIFIED BY 'mypass'; + ``` + +## 忘记 `root` 密码 + +1. 修改配置文件，在 `security` 部分添加 `skip-grant-table`： + + {{< copyable "" >}} + + ``` + [security] + skip-grant-table = true + ``` + +2. 然后使用 `root` 登录后修改密码： + + {{< copyable "shell-regular" >}} + + ```bash + mysql -h 127.0.0.1 -P 4000 -u root + ``` + +## `FLUSH PRIVILEGES` + +如果授权表已被直接修改，运行如下命令可使改动立即生效： + +{{< copyable "sql" >}} + +```sql +FLUSH PRIVILEGES; +``` + +详情参见[权限管理](/reference/security/privilege-system.md)。 diff --git a/dev/reference/sql/character-set.md b/reference/sql/character-set.md similarity index 100% rename from dev/reference/sql/character-set.md rename to reference/sql/character-set.md diff --git a/reference/sql/constraints.md b/reference/sql/constraints.md new file mode 100644 index 000000000000..40ff7f55dc3e --- /dev/null +++ b/reference/sql/constraints.md @@ -0,0 +1,273 @@ +--- +title: 约束 +category: reference +--- + +# 约束 + +TiDB 支持的基本约束与 MySQL 的基本相同，但有以下区别： + +- 默认对唯一约束进行[惰性检查](/reference/transactions/overview.md#事务的惰性检查)。通过在事务提交时再进行批量检查，TiDB 能够减少网络开销、提升性能。您可通过设置 `tidb_constraint_check_in_place` 为 `TRUE` 改变此行为。 + +- TiDB 支持创建外键约束，但不会在 DML 语句中对外键进行约束（即外键约束不生效）。 + +## 外键约束 + +目前，TiDB 支持创建外键。例如： + +```sql +CREATE TABLE users ( + id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, + doc JSON +); +CREATE TABLE orders ( + id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, + user_id INT NOT NULL, + doc JSON, + FOREIGN KEY fk_user_id (user_id) REFERENCES users(id) +); +``` + +{{< copyable "sql" >}} + +```sql +SELECT table_name, column_name, constraint_name, referenced_table_name, referenced_column_name +FROM information_schema.key_column_usage WHERE table_name IN ('users', 'orders'); +``` + +``` ++------------+-------------+-----------------+-----------------------+------------------------+ +| table_name | column_name | constraint_name | referenced_table_name | referenced_column_name | ++------------+-------------+-----------------+-----------------------+------------------------+ +| users | id | PRIMARY | NULL | NULL | +| orders | id | PRIMARY | NULL | NULL | +| orders | user_id | fk_user_id | users | id | ++------------+-------------+-----------------+-----------------------+------------------------+ +3 rows in set (0.00 sec) +``` + +TiDB 也支持使用 `ALTER TABLE` 命令来删除外键（`DROP FOREIGN KEY`）和添加外键（`ADD FOREIGN KEY`）： + +{{< copyable "sql" >}} + +```sql +ALTER TABLE orders DROP FOREIGN KEY fk_user_id; +ALTER TABLE orders ADD FOREIGN KEY fk_user_id (user_id) REFERENCES users(id); +``` + +### 注意 + +* TiDB 支持外键是为了在将其他数据库迁移到 TiDB 时，不会因为此语法报错。但是，TiDB 不会在 DML 语句中对外键进行约束。例如，即使 `users` 表中不存在 `id=123` 的记录，下列事务也能提交成功： + + ``` + START TRANSACTION; + INSERT INTO orders (user_id, doc) VALUES (123, NULL); + COMMIT; + ``` + +* TiDB 在执行 `SHOW CREATE TABLE` 语句的结果中不显示外键信息。 + +## 非空约束 + +TiDB 支持的非空约束规则与 MySQL 支持的一致。例如： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE users ( + id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, + age INT NOT NULL, + last_login TIMESTAMP +); +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO users (id,age,last_login) VALUES (NULL,123,NOW()); +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO users (id,age,last_login) VALUES (NULL,NULL,NOW()); +``` + +``` +ERROR 1048 (23000): Column 'age' cannot be null +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO users (id,age,last_login) VALUES (NULL,123,NULL); +``` + +``` +Query OK, 1 row affected (0.03 sec) +``` + +* 第一条 `INSERT` 语句成功，因为对于定义为 `AUTO_INCREMENT` 的列，允许 `NULL` 作为其特殊值。TiDB 将为其分配下一个自动值。 + +* 第二条 `INSERT` 语句失败，因为 `age` 列被定义为 `NOT NULL`。 + +* 第三条 `INSERT` 语句成功，因为 `last_login` 列没有被明确地指定为 `NOT NULL`。默认允许 `NULL` 值。 + +## 主键约束 + +TiDB 支持的主键约束规则与 MySQL 支持的相似。例如： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t2 (a INT NULL PRIMARY KEY); +``` + +``` +ERROR 1171 (42000): All parts of a PRIMARY KEY must be NOT NULL; if you need NULL in a key, use UNIQUE instead +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t3 (a INT NOT NULL PRIMARY KEY, b INT NOT NULL PRIMARY KEY); +``` + +``` +ERROR 1068 (42000): Multiple primary key defined +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t4 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b)); +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +* 表 `t2` 创建失败，因为定义为主键的列 `a` 不能允许 `NULL` 值。 +* 表 `t3` 创建失败，因为一张表只能有一个主键。 +* 表 `t4` 创建成功，因为虽然只能有一个主键，但 TiDB 支持定义一个多列组合作为复合主键。 + +除上述规则外，TiDB 还强加了另一个限制，即一旦一张表创建成功，其主键就不能再改变。 + +## 唯一约束 + +在 TiDB 中，默认会对唯一约束进行惰性检查。通过直到事务提交时才进行批量检查，TiDB 能够减少网络通信开销。例如： + +{{< copyable "sql" >}} + +```sql +DROP TABLE IF EXISTS users; +CREATE TABLE users ( + id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, + username VARCHAR(60) NOT NULL, + UNIQUE KEY (username) +); +INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); +``` + +{{< copyable "sql" >}} + +```sql +START TRANSACTION; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); +``` + +``` +Query OK, 3 rows affected (0.00 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO users (username) VALUES ('steve'),('elizabeth'); +``` + +``` +Query OK, 2 rows affected (0.00 sec) +Records: 2 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +COMMIT; +``` + +``` +ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' +``` + +* 第一条 `INSERT` 语句不会导致重复键错误，这同 MySQL 的规则一致。该检查将推迟到事务提交时才会进行。 + +如果将 `tidb_constraint_check_in_place` 更改为 `TRUE`，则会在执行语句时就对唯一约束进行检查。例如： + +```sql +DROP TABLE IF EXISTS users; +CREATE TABLE users ( + id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, + username VARCHAR(60) NOT NULL, + UNIQUE KEY (username) +); +INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); +``` + +{{< copyable "sql" >}} + +```sql +SET tidb_constraint_check_in_place = TRUE; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +START TRANSACTION; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); +``` + +``` +ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' +.. +``` + +* 第一条 `INSERT` 语句导致了重复键错误。这会造成额外的网络通信开销，并可能降低插入操作的吞吐量。 diff --git a/dev/reference/sql/data-types/date-and-time.md b/reference/sql/data-types/date-and-time.md similarity index 100% rename from dev/reference/sql/data-types/date-and-time.md rename to reference/sql/data-types/date-and-time.md diff --git a/dev/reference/sql/data-types/default-values.md b/reference/sql/data-types/default-values.md similarity index 100% rename from dev/reference/sql/data-types/default-values.md rename to reference/sql/data-types/default-values.md diff --git a/dev/reference/sql/data-types/json.md b/reference/sql/data-types/json.md similarity index 100% rename from dev/reference/sql/data-types/json.md rename to reference/sql/data-types/json.md diff --git a/dev/reference/sql/data-types/numeric.md b/reference/sql/data-types/numeric.md similarity index 100% rename from dev/reference/sql/data-types/numeric.md rename to reference/sql/data-types/numeric.md diff --git a/reference/sql/data-types/overview.md b/reference/sql/data-types/overview.md new file mode 100644 index 000000000000..43ed6515d101 --- /dev/null +++ b/reference/sql/data-types/overview.md @@ -0,0 +1,15 @@ +--- +title: 数据类型概述 +category: reference +--- + +# 数据类型概述 + +TiDB 支持除空间类型 (`SPATIAL`) 之外的所有 MySQL 数据类型，包括[数值型类型](/reference/sql/data-types/numeric.md)、[字符串类型](/reference/sql/data-types/string.md)、[时间和日期类型](/reference/sql/data-types/date-and-time.md)、[JSON 类型](/reference/sql/data-types/json.md)。 + +数据类型定义一般为 `T(M[, D])`，其中： + +* `T` 表示具体的类型。 +* `M` 在整数类型中表示最大显示长度；在浮点数或者定点数中表示精度；在字符类型中表示最大长度。`M` 的最大值取决于具体的类型。 +* `D` 表示浮点数、定点数的小数位长度。 +* `fsp` 在时间和日期类型里的 `TIME`、`DATETIME` 以及 `TIMESTAMP` 中表示秒的精度，其取值范围是 0 到 6。值为 0 表示没有小数部分。如果省略，则默认精度为 0。 diff --git a/dev/reference/sql/data-types/string.md b/reference/sql/data-types/string.md similarity index 100% rename from dev/reference/sql/data-types/string.md rename to reference/sql/data-types/string.md diff --git a/reference/sql/functions-and-operators/aggregate-group-by-functions.md b/reference/sql/functions-and-operators/aggregate-group-by-functions.md new file mode 100644 index 000000000000..0586410900ab --- /dev/null +++ b/reference/sql/functions-and-operators/aggregate-group-by-functions.md @@ -0,0 +1,157 @@ +--- +title: GROUP BY 聚合函数 +category: reference +--- + +# GROUP BY 聚合函数 + +本文将详细介绍 TiDB 支持的聚合函数。 + +## TiDB 支持的聚合函数 + +TiDB 支持的 MySQL GROUP BY 聚合函数如下所示： + +| 函数名 | 功能描述 | +|:---------|:--------------------| +| [`COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count) | 返回检索到的行的数目| +| [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count-distinct) | 返回不同值的数目 | +| [`SUM()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_sum) | 返回和 | +| [`AVG()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_avg) | 返回平均值 | +| [`MAX()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_max) | 返回最大值 | +| [`MIN()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_min) | 返回最小值 | +| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_group-concat) | 返回连接的字符串 | + +> **注意：** +> +> - 除非另有说明，否则聚合函数默认忽略 `NULL` 值。 +> - 如果在不包含 `GROUP BY` 子句的语句中使用聚合函数，则相当于对所有行进行分组。 + +## GROUP BY 修饰符 + +TiDB 目前不支持 `GROUP BY` 修饰符，例如 `WITH ROLLUP`，将来会提供支持。详情参阅 [#4250](https://github.com/pingcap/tidb/issues/4250)。 + +## 对 SQL 模式的支持 + +TiDB 支持 SQL 模式 `ONLY_FULL_GROUP_BY`，当启用该模式时，TiDB 拒绝不明确的非聚合列的查询。例如，以下查询在启用 `ONLY_FULL_GROUP_BY` 时是不合规的，因为 `SELECT` 列表中的非聚合列 "b" 在 `GROUP BY` 语句中不显示： + +{{< copyable "sql" >}} + +```sql +drop table if exists t; +create table t(a bigint, b bigint, c bigint); +insert into t values(1, 2, 3), (2, 2, 3), (3, 2, 3); +``` + +{{< copyable "sql" >}} + +```sql +select a, b, sum(c) from t group by a; +``` + +``` ++------+------+--------+ +| a | b | sum(c) | ++------+------+--------+ +| 1 | 2 | 3 | +| 2 | 2 | 3 | +| 3 | 2 | 3 | ++------+------+--------+ +3 rows in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +set sql_mode = 'ONLY_FULL_GROUP_BY'; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +select a, b, sum(c) from t group by a; +``` + +``` +ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP BY clause and contains nonaggregated column 'b' which is not functionally dependent on columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by +``` + +目前，TiDB 默认开启 SQL 模式 [`ONLY_FULL_GROUP_BY`](/reference/mysql-compatibility.md#默认设置的区别)。 + +### 与 MySQL 的区别 + +TiDB 目前实现的 `ONLY_FULL_GROUP_BY` 没有 MySQL 5.7 严格。例如，假设我们执行以下查询，希望结果按 "c" 排序： + +{{< copyable "sql" >}} + +```sql +drop table if exists t; +create table t(a bigint, b bigint, c bigint); +insert into t values(1, 2, 1), (1, 2, 2), (1, 3, 1), (1, 3, 2); +select distinct a, b from t order by c; +``` + +要对结果进行排序，必须先清除重复。但选择保留哪一行会影响 `c` 的保留值，也会影响排序，并使其具有任意性。 + +在 MySQL 中，`ORDER BY` 表达式需至少满足以下条件之一，否则 `DISTINCT` 和 `ORDER BY` 查询将因不合规而被拒绝： + +- 表达式等同于 `SELECT` 列表中的一个。 +- 表达式引用并属于查询选择表的所有列都是 `SELECT` 列表的元素。 + +但是在 TiDB 中，上述查询是合规的，详情参阅 [#4254](https://github.com/pingcap/tidb/issues/4254)。 + +TiDB 中另一个标准 SQL 的扩展允许 `HAVING` 子句中的引用使用 `SELECT` 列表中的别名表达式。例如：以下查询返回在 `orders` 中只出现一次的 `name` 值： + +{{< copyable "sql" >}} + +```sql +select name, count(name) from orders +group by name +having count(name) = 1; +``` + +这个 TiDB 扩展允许在聚合列的 `HAVING` 子句中使用别名： + +{{< copyable "sql" >}} + +```sql +select name, count(name) as c from orders +group by name +having c = 1; +``` + +标准 SQL 只支持 `GROUP BY` 子句中的列表达式，以下语句不合规，因为 `FLOOR(value/100)` 是一个非列表达式： + +{{< copyable "sql" >}} + +```sql +select id, floor(value/100) +from tbl_name +group by id, floor(value/100); +``` + +TiDB 对标准 SQL 的扩展支持 `GROUP BY` 子句中非列表达式，认为上述语句合规。 + +标准 SQL 也不支持 `GROUP BY` 子句中使用别名。TiDB 对标准 SQL 的扩展支持使用别名，查询的另一种写法如下： + +{{< copyable "sql" >}} + +```sql +select id, floor(value/100) as val +from tbl_name +group by id, val; +``` + +## TiDB 不支持的聚合函数 + +TiDB 目前不支持的聚合函数如下所示，相关进展参阅 [TiDB #7623](https://github.com/pingcap/tidb/issues/7623)。 + +- `STD`, `STDDEV`, `STDDEV_POP` +- `STDDEV_SAMP` +- `VARIANCE`, `VAR_POP` +- `VAR_SAMP` +- `JSON_ARRAYAGG` +- `JSON_OBJECTAGG` diff --git a/dev/reference/sql/functions-and-operators/bit-functions-and-operators.md b/reference/sql/functions-and-operators/bit-functions-and-operators.md similarity index 100% rename from dev/reference/sql/functions-and-operators/bit-functions-and-operators.md rename to reference/sql/functions-and-operators/bit-functions-and-operators.md diff --git a/dev/reference/sql/functions-and-operators/cast-functions-and-operators.md b/reference/sql/functions-and-operators/cast-functions-and-operators.md similarity index 100% rename from dev/reference/sql/functions-and-operators/cast-functions-and-operators.md rename to reference/sql/functions-and-operators/cast-functions-and-operators.md diff --git a/dev/reference/sql/functions-and-operators/control-flow-functions.md b/reference/sql/functions-and-operators/control-flow-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/control-flow-functions.md rename to reference/sql/functions-and-operators/control-flow-functions.md diff --git a/dev/reference/sql/functions-and-operators/date-and-time-functions.md b/reference/sql/functions-and-operators/date-and-time-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/date-and-time-functions.md rename to reference/sql/functions-and-operators/date-and-time-functions.md diff --git a/dev/reference/sql/functions-and-operators/encryption-and-compression-functions.md b/reference/sql/functions-and-operators/encryption-and-compression-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/encryption-and-compression-functions.md rename to reference/sql/functions-and-operators/encryption-and-compression-functions.md diff --git a/reference/sql/functions-and-operators/expressions-pushed-down.md b/reference/sql/functions-and-operators/expressions-pushed-down.md new file mode 100644 index 000000000000..32d7b1ad0531 --- /dev/null +++ b/reference/sql/functions-and-operators/expressions-pushed-down.md @@ -0,0 +1,145 @@ +--- +title: 下推到 TiKV 的表达式列表 +summary: TiDB 中下推到 TiKV 的表达式列表及相关设置。 +category: reference +--- + +# 下推到 TiKV 的表达式列表 + +当 TiDB 从 TiKV 中读取数据的时候，TiDB 会尽量下推一些表达式运算到 TiKV 中，从而减少数据传输量以及 TiDB 单一节点的计算压力。本文将介绍 TiDB 已支持下推的表达式，以及如何禁止下推特定表达式。 + +## 已支持下推的表达式列表 + +| 表达式分类 | 具体操作 | +| :-------------- | :------------------------------------- | +| [逻辑运算](/reference/sql/functions-and-operators/operators.md#逻辑操作符) | AND (&&), OR (||), NOT (!) | +| [比较运算](/reference/sql/functions-and-operators/operators.md#比较方法和操作符) | <, <=, =, != (<>), >, >=, [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to), [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in), IS NULL, LIKE, IS TRUE, IS FALSE, [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | +| [数值运算](/reference/sql/functions-and-operators/numeric-functions-and-operators.md) | +, -, *, /, [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs), [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil), [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling), [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | +| [控制流运算](/reference/sql/functions-and-operators/control-flow-functions.md) | [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case), [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if), [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | +| [JSON运算](/reference/sql/functions-and-operators/json-functions.md) | [JSON_TYPE(json_val)][json_type],
[JSON_EXTRACT(json_doc, path[, path] ...)][json_extract],
[JSON_UNQUOTE(json_val)][json_unquote],
[JSON_OBJECT(key, val[, key, val] ...)][json_object],
[JSON_ARRAY([val[, val] ...])][json_array],
[JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge],
[JSON_SET(json_doc, path, val[, path, val] ...)][json_set],
[JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert],
[JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace],
[JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | +| [日期运算](/reference/sql/functions-and-operators/date-and-time-functions.md) | [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | + +## 禁止特定表达式下推 + +当函数的计算过程由于下推而出现异常时，可通过黑名单功能禁止其下推来快速恢复业务。具体而言，你可以将上述支持的函数或运算符名加入黑名单 `mysql.expr_pushdown_blacklist` 中，以禁止特定表达式下推。 + +### 加入黑名单 + +执行以下步骤，可将一个或多个函数或运算符加入黑名单： + +1. 向 `mysql.expr_pushdown_blacklist` 插入对应的函数名或运算符名。 +2. 执行 `admin reload expr_pushdown_blacklist;`。 + +### 移出黑名单 + +执行以下步骤，可将一个或多个函数及运算符移出黑名单： + +1. 从 `mysql.expr_pushdown_blacklist` 表中删除对应的函数名或运算符名。 +2. 执行 `admin reload expr_pushdown_blacklist;`。 + +### 黑名单用法示例 + +以下示例首先将运算符 `<` 及 `>` 加入黑名单，然后将运算符 `>` 从黑名单中移出。 + +黑名单是否生效可以从 `explain` 结果中进行观察（参见[如何理解 `explain` 结果](/reference/performance/understanding-the-query-execution-plan.md)）。 + +```sql +tidb> create table t(a int); +Query OK, 0 rows affected (0.01 sec) + +tidb> explain select * from t where a < 2 and a > 2; ++---------------------+----------+------+------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+------------------------------------------------------------+ +| TableReader_7 | 0.00 | root | data:Selection_6 | +| └─Selection_6 | 0.00 | cop | gt(test.t.a, 2), lt(test.t.a, 2) | +| └─TableScan_5 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+------------------------------------------------------------+ +3 rows in set (0.00 sec) + +tidb> insert into mysql.expr_pushdown_blacklist values('<'), ('>'); +Query OK, 2 rows affected (0.00 sec) +Records: 2 Duplicates: 0 Warnings: 0 + +tidb> admin reload expr_pushdown_blacklist; +Query OK, 0 rows affected (0.00 sec) + +tidb> explain select * from t where a < 2 and a > 2; ++---------------------+----------+------+------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+------------------------------------------------------------+ +| Selection_5 | 8000.00 | root | gt(test.t.a, 2), lt(test.t.a, 2) | +| └─TableReader_7 | 10000.00 | root | data:TableScan_6 | +| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+------------------------------------------------------------+ +3 rows in set (0.00 sec) + +tidb> delete from mysql.expr_pushdown_blacklist where name = '>'; +Query OK, 1 row affected (0.00 sec) + +tidb> admin reload expr_pushdown_blacklist; +Query OK, 0 rows affected (0.00 sec) + +tidb> explain select * from t where a < 2 and a > 2; ++-----------------------+----------+------+------------------------------------------------------------+ +| id | count | task | operator info | ++-----------------------+----------+------+------------------------------------------------------------+ +| Selection_5 | 2666.67 | root | lt(test.t.a, 2) | +| └─TableReader_8 | 3333.33 | root | data:Selection_7 | +| └─Selection_7 | 3333.33 | cop | gt(test.t.a, 2) | +| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | ++-----------------------+----------+------+------------------------------------------------------------+ +4 rows in set (0.00 sec) +``` + +> **注意：** +> +> - `admin reload expr_pushdown_blacklist` 只对执行该 SQL 语句的 TiDB server 生效。若需要集群中所有 TiDB server 生效，需要在每台 TiDB server 上执行该 SQL 语句。 +> - 表达式黑名单功能在 v3.0.0 及以上版本中支持。 +> - 在 v3.0.3 及以下版本中，不支持将某些运算符的原始名称文本（如 ">"、"+" 和 "is null"）加入黑名单中，部分运算符在黑名单中需使用别名。已支持下推的表达式中，别名与原始名不同的运算符见下表（区分大小写）。 + +| 运算符原始名称 | 运算符别名 | +| :-------- | :---------- | +| < | lt | +| > | gt | +| <= | le | +| >= | ge | +| = | eq | +| != | ne | +| <> | ne | +| <=> | nulleq | +| | | bitor | +| && | bitand| +| || | or | +| ! | not | +| in | in | +| + | plus| +| - | minus | +| * | mul | +| / | div | +| DIV | intdiv| +| IS NULL | isnull | +| IS TRUE | istrue | +| IS FALSE | isfalse | + +[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract +[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path +[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path +[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote +[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type +[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set +[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert +[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace +[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove +[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge +[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve +[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object +[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array +[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys +[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length +[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid +[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote +[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains +[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path +[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg +[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/dev/reference/sql/functions-and-operators/information-functions.md b/reference/sql/functions-and-operators/information-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/information-functions.md rename to reference/sql/functions-and-operators/information-functions.md diff --git a/dev/reference/sql/functions-and-operators/json-functions.md b/reference/sql/functions-and-operators/json-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/json-functions.md rename to reference/sql/functions-and-operators/json-functions.md diff --git a/dev/reference/sql/functions-and-operators/miscellaneous-functions.md b/reference/sql/functions-and-operators/miscellaneous-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/miscellaneous-functions.md rename to reference/sql/functions-and-operators/miscellaneous-functions.md diff --git a/dev/reference/sql/functions-and-operators/numeric-functions-and-operators.md b/reference/sql/functions-and-operators/numeric-functions-and-operators.md similarity index 100% rename from dev/reference/sql/functions-and-operators/numeric-functions-and-operators.md rename to reference/sql/functions-and-operators/numeric-functions-and-operators.md diff --git a/dev/reference/sql/functions-and-operators/operators.md b/reference/sql/functions-and-operators/operators.md similarity index 100% rename from dev/reference/sql/functions-and-operators/operators.md rename to reference/sql/functions-and-operators/operators.md diff --git a/dev/reference/sql/functions-and-operators/precision-math.md b/reference/sql/functions-and-operators/precision-math.md similarity index 100% rename from dev/reference/sql/functions-and-operators/precision-math.md rename to reference/sql/functions-and-operators/precision-math.md diff --git a/reference/sql/functions-and-operators/reference.md b/reference/sql/functions-and-operators/reference.md new file mode 100644 index 000000000000..ed06e78a0800 --- /dev/null +++ b/reference/sql/functions-and-operators/reference.md @@ -0,0 +1,12 @@ +--- +title: 函数和操作符概述 +category: reference +--- + +# 函数和操作符概述 + +TiDB 中函数和操作符使用方法与 MySQL 基本一致，详情参见: [Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/functions.html)。 + +在 SQL 语句中，表达式可用于诸如 `SELECT` 语句的 `ORDER BY` 或 `HAVING` 子句，`SELECT`/`DELETE`/`UPDATE` 语句的 `WHERE` 子句，或 `SET` 语句之类的地方。 + +可使用字面值，列名，NULL，内置函数，操作符等来书写表达式。其中有些表达式下推到 TiKV 上执行，详见[下推到 TiKV 的表达式列表](/reference/sql/functions-and-operators/expressions-pushed-down.md)。 diff --git a/dev/reference/sql/functions-and-operators/string-functions.md b/reference/sql/functions-and-operators/string-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/string-functions.md rename to reference/sql/functions-and-operators/string-functions.md diff --git a/dev/reference/sql/functions-and-operators/type-conversion.md b/reference/sql/functions-and-operators/type-conversion.md similarity index 100% rename from dev/reference/sql/functions-and-operators/type-conversion.md rename to reference/sql/functions-and-operators/type-conversion.md diff --git a/dev/reference/sql/functions-and-operators/window-functions.md b/reference/sql/functions-and-operators/window-functions.md similarity index 100% rename from dev/reference/sql/functions-and-operators/window-functions.md rename to reference/sql/functions-and-operators/window-functions.md diff --git a/reference/sql/generated-columns.md b/reference/sql/generated-columns.md new file mode 100644 index 000000000000..6f32b4350476 --- /dev/null +++ b/reference/sql/generated-columns.md @@ -0,0 +1,99 @@ +--- +title: 生成列 +category: reference +--- + +# 生成列 + +为了在功能上兼容 MySQL 5.7，TiDB 支持生成列 (generated column)。生成列的主要的作用之一：从 JSON 数据类型中解出数据，并为该数据建立索引。 + +## 使用 generated column 对 JSON 建索引 + +MySQL 5.7 及 TiDB 都不能直接为 JSON 类型的列添加索引，即**不支持**如下表结构： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE person ( + id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(255) NOT NULL, + address_info JSON, + KEY (address_info) +); +``` + +为 JSON 列添加索引之前，首先必须抽取该列为 generated column。 + +以 `city` generated stored column 为例，你可以添加索引： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE person ( + id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(255) NOT NULL, + address_info JSON, + city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED, + KEY (city) +); +``` + +该表中，`city` 列是一个 **generated stored column**。顾名思义，此列由该表的其他列生成，对此列进行插入或更新操作时，并不能对之赋值。此列按其定义的表达式生成，并存储在数据库中，这样在读取此列时，就可以直接读取，不用再读取其依赖的 `address_info` 列后再计算得到。`city` 列的索引**存储在数据库中**，并使用和 `varchar(64)` 类的其他索引相同的结构。 + +可使用 generated stored column 的索引，以提高如下语句的执行速度： + +{{< copyable "sql" >}} + +```sql +SELECT name, id FROM person WHERE city = 'Beijing'; +``` + +如果 `$.city` 路径中无数据，则 `JSON_EXTRACT` 返回 `NULL`。如果想增加约束，`city` 列必须是 `NOT NULL`，则可按照以下方式定义 virtual column： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE person ( + id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(255) NOT NULL, + address_info JSON, + city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED NOT NULL, + KEY (city) +); +``` + +`INSERT` 和 `UPDATE` 语句都会检查 virtual column 的定义。未通过有效性检测的行会返回错误： + +{{< copyable "sql" >}} + +```sql +INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada')); +``` + +``` +ERROR 1048 (23000): Column 'city' cannot be null +``` + +## 使用 generated virtual column + +TiDB 也支持 generated virtual column，和 generated store column 不同的是，此列按需生成，并不存储在数据库中，也不占用内存空间，因而是**虚拟的**。 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE person ( + id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(255) NOT NULL, + address_info JSON, + city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) VIRTUAL +); +``` + +## 局限性 + +目前 JSON and generated column 有以下局限性： + +- 不能通过 `ALTER TABLE` 增加 `STORED` 存储方式的 generated column； +- 不能通过 `ALTER TABLE` 将 generated stored column 转换为普通列，也不能将普通列转换成 generated stored column； +- 不能通过 `ALTER TABLE` 修改 generated stored column 的**生成列表达式**； +- 并未支持所有的 [JSON 函数](/reference/sql/functions-and-operators/json-functions.md)。 \ No newline at end of file diff --git a/reference/sql/language-structure/comment-syntax.md b/reference/sql/language-structure/comment-syntax.md new file mode 100644 index 000000000000..05a8010fcb68 --- /dev/null +++ b/reference/sql/language-structure/comment-syntax.md @@ -0,0 +1,124 @@ +--- +title: 注释语法 +category: reference +--- + +# 注释语法 + +TiDB 支持三种注释风格： + +* 用 `#` 注释一行 +* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。 +* 用 `/* */` 注释一块，可以注释多行。 + +例： + +{{< copyable "sql" >}} + +```sql +SELECT 1+1; # 注释文字 +``` + +``` ++------+ +| 1+1 | ++------+ +| 2 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT 1+1; -- 注释文字 +``` + +``` ++------+ +| 1+1 | ++------+ +| 2 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT 1 /* 这是行内注释文字 */ + 1; +``` + +``` ++--------+ +| 1 + 1 | ++--------+ +| 2 | ++--------+ +1 row in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT 1+ + -> /* + /*> 这是一条 + /*> 多行注释 + /*> */ + -> 1; +``` + +``` ++-------+ +| 1+ + +1 | ++-------+ +| 2 | ++-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT 1+1--1; +``` + +``` ++--------+ +| 1+1--1 | ++--------+ +| 3 | ++--------+ +1 row in set (0.01 sec) +``` + +TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： + +``` +/*! Specific code */ +``` + +在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 + +例如：`SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...` + +在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` + +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。 + +还有一种注释会被当做是优化器 Hint 特殊对待： + +{{< copyable "sql" >}} + +```sql +SELECT /*+ hint */ FROM ...; +``` + +由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments + +TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/reference/performance/optimizer-hints.md)。 + +更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 diff --git a/dev/reference/sql/language-structure/expression-syntax.md b/reference/sql/language-structure/expression-syntax.md similarity index 100% rename from dev/reference/sql/language-structure/expression-syntax.md rename to reference/sql/language-structure/expression-syntax.md diff --git a/reference/sql/language-structure/keywords-and-reserved-words.md b/reference/sql/language-structure/keywords-and-reserved-words.md new file mode 100644 index 000000000000..f1a5b2362004 --- /dev/null +++ b/reference/sql/language-structure/keywords-and-reserved-words.md @@ -0,0 +1,483 @@ +--- +title: 关键字和保留字 +category: reference +--- + +# 关键字和保留字 + +关键字在 SQL 中有特殊的意义， 例如 `SELECT`，`UPDATE`，`DELETE`，在作为表名跟函数名的时候，需要特殊对待，例如作为表名，保留字需要被反引号包住： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE select (a INT); +``` + +``` +ERROR 1105 (HY000): line 0 column 19 near " (a INT)" (total length 27) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE `select` (a INT); +``` + +``` +Query OK, 0 rows affected (0.09 sec) +``` + +`BEGIN` 和 `END` 是关键字， 但不是保留字，所以不需要反引号： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE `select` (BEGIN int, END int); +``` + +``` +Query OK, 0 rows affected (0.09 sec) +``` + +有一种特殊情况， 如果使用了限定符 `.`，那么也不需要用反引号： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE test.select (BEGIN int, END int); +``` + +``` +Query OK, 0 rows affected (0.08 sec) +``` + +下表列出了 TiDB 中的关键字和保留字。保留字用 `(R)` 来标识。[窗口函数](/reference/sql/functions-and-operators/window-functions.md)的保留字用 `(R-Window)` 来标识： + +{{< tabs-panel "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z" >}} + +A + +- ACTION +- ADD (R) +- ADDDATE +- ADMIN +- AFTER +- ALL (R) +- ALTER (R) +- ALWAYS +- ANALYZE(R) +- AND (R) +- ANY +- AS (R) +- ASC (R) +- ASCII +- AUTO_INCREMENT +- AVG +- AVG_ROW_LENGTH + +B + +- BEGIN +- BETWEEN (R) +- BIGINT (R) +- BINARY (R) +- BINLOG +- BIT +- BIT_XOR +- BLOB (R) +- BOOL +- BOOLEAN +- BOTH (R) +- BTREE +- BY (R) +- BYTE + +C + +- CASCADE (R) +- CASE (R) +- CAST +- CHANGE (R) +- CHAR (R) +- CHARACTER (R) +- CHARSET +- CHECK (R) +- CHECKSUM +- COALESCE +- COLLATE (R) +- COLLATION +- COLUMN (R) +- COLUMNS +- COMMENT +- COMMIT +- COMMITTED +- COMPACT +- COMPRESSED +- COMPRESSION +- CONNECTION +- CONSISTENT +- CONSTRAINT (R) +- CONVERT (R) +- COUNT +- CREATE (R) +- CROSS (R) +- CUME_DIST (R-Window) +- CURRENT_DATE (R) +- CURRENT_TIME (R) +- CURRENT_TIMESTAMP (R) +- CURRENT_USER (R) +- CURTIME + +D + +- DATA +- DATABASE (R) +- DATABASES (R) +- DATE +- DATE_ADD +- DATE_SUB +- DATETIME +- DAY +- DAY_HOUR (R) +- DAY_MICROSECOND (R) +- DAY_MINUTE (R) +- DAY_SECOND (R) +- DDL +- DEALLOCATE +- DEC +- DECIMAL (R) +- DEFAULT (R) +- DELAY_KEY_WRITE +- DELAYED (R) +- DELETE (R) +- DENSE_RANK (R-Window) +- DESC (R) +- DESCRIBE (R) +- DISABLE +- DISTINCT (R) +- DISTINCTROW (R) +- DIV (R) +- DO +- DOUBLE (R) +- DROP (R) +- DUAL (R) +- DUPLICATE +- DYNAMIC + +E + +- ELSE (R) +- ENABLE +- ENCLOSED +- END +- ENGINE +- ENGINES +- ENUM +- ESCAPE +- ESCAPED +- EVENTS +- EXCLUSIVE +- EXECUTE +- EXISTS +- EXPLAIN (R) +- EXTRACT + +F + +- FALSE (R) +- FIELDS +- FIRST +- FIRST_VALUE (R-Window) +- FIXED +- FLOAT (R) +- FLUSH +- FOR (R) +- FORCE (R) +- FOREIGN (R) +- FORMAT +- FROM (R) +- FULL +- FULLTEXT (R) +- FUNCTION + +G + +- GENERATED (R) +- GET_FORMAT +- GLOBAL +- GRANT (R) +- GRANTS +- GROUP (R) +- GROUP_CONCAT +- GROUPS (R-Window) + +H + +- HASH +- HAVING (R) +- HIGH_PRIORITY (R) +- HOUR +- HOUR_MICROSECOND (R) +- HOUR_MINUTE (R) +- HOUR_SECOND (R) + +I + +- IDENTIFIED +- IF (R) +- IGNORE (R) +- IN (R) +- INDEX (R) +- INDEXES +- INFILE (R) +- INNER (R) +- INSERT (R) +- INT (R) +- INTEGER (R) +- INTERVAL (R) +- INTO (R) +- IS (R) +- ISOLATION + +J + +- JOBS +- JOIN (R) +- JSON + +K + +- KEY (R) +- KEY_BLOCK_SIZE +- KEYS (R) +- KILL (R) + +L + +- LAG (R-Window) +- LAST_VALUE (R-Window) +- LEAD (R-Window) +- LEADING (R) +- LEFT (R) +- LESS +- LEVEL +- LIKE (R) +- LIMIT (R) +- LINES (R) +- LOAD (R) +- LOCAL +- LOCALTIME (R) +- LOCALTIMESTAMP (R) +- LOCK (R) +- LONGBLOB (R) +- LONGTEXT (R) +- LOW_PRIORITY (R) + +M + +- MAX +- MAX_ROWS +- MAXVALUE (R) +- MEDIUMBLOB (R) +- MEDIUMINT (R) +- MEDIUMTEXT (R) +- MICROSECOND +- MIN +- MIN_ROWS +- MINUTE +- MINUTE_MICROSECOND (R) +- MINUTE_SECOND (R) +- MIN +- MIN_ROWS +- MINUTE +- MINUTE_MICROSECOND +- MINUTE_SECOND +- MOD (R) +- MODE +- MODIRY +- MONTH + +N + +- NAMES +- NATIONAL +- NATURAL (R) +- NO +- NO_WRITE_TO_BINLOG (R) +- NONE +- NOT (R) +- NOW +- NTH_VALUE (R-Window) +- NTILE (R-Window) +- NULL (R) +- NUMERIC (R) +- NVARCHAR (R) + +O + +- OFFSET +- ON (R) +- ONLY +- OPTION (R) +- OR (R) +- ORDER (R) +- OUTER (R) +- OVER (R-Window) + +P + +- PARTITION (R) +- PARTITIONS +- PASSWORD +- PERCENT_RANK (R-Window) +- PLUGINS +- POSITION +- PRECISION (R) +- PREPARE +- PRIMARY (R) +- PRIVILEGES +- PROCEDURE (R) +- PROCESS +- PROCESSLIST + +Q + +- QUARTER +- QUERY +- QUICK + +R + +- RANGE (R) +- RANK (R-Window) +- READ (R) +- REAL (R) +- REDUNDANT +- REFERENCES (R) +- REGEXP (R) +- RENAME (R) +- REPEAT (R) +- REPEATABLE +- REPLACE (R) +- RESTRICT (R) +- REVERSE +- REVOKE (R) +- RIGHT (R) +- RLIKE (R) +- ROLLBACK +- ROW +- ROW_COUNT +- ROW_FORMAT +- ROW_NUMBER (R-Window) +- ROWS (R-Window) + +S + +- SCHEMA +- SCHEMAS +- SECOND +- SECOND_MICROSECOND (R) +- SELECT (R) +- SERIALIZABLE +- SESSION +- SET (R) +- SHARE +- SHARED +- SHOW (R) +- SIGNED +- SMALLINT (R) +- SNAPSHOT +- SOME +- SQL_CACHE +- SQL_CALC_FOUND_ROWS (R) +- SQL_NO_CACHE +- START +- STARTING (R) +- STATS +- STATS_BUCKETS +- STATS_HISTOGRAMS +- STATS_META +- STATS_PERSISTENT +- STATUS +- STORED (R) +- SUBDATE +- SUBSTR +- SUBSTRING +- SUM +- SUPER + +T + +- TABLE (R) +- TABLES +- TERMINATED (R) +- TEXT +- THAN +- THEN (R) +- TIDB +- TIDB_INLJ +- TIDB_SMJ +- TIME +- TIMESTAMP +- TIMESTAMPADD +- TIMESTAMPDIFF +- TINYBLOB (R) +- TINYINT (R) +- TINYTEXT (R) +- TO (R) +- TRAILING (R) +- TRANSACTION +- TRIGGER (R) +- TRIGGERS +- TRIM +- TRUE (R) +- TRUNCATE + +U + +- UNCOMMITTED +- UNION (R) +- UNIQUE (R) +- UNKNOWN +- UNLOCK (R) +- UNSIGNED (R) +- UPDATE (R) +- USE (R) +- USER +- USING (R) +- UTC_DATE (R) +- UTC_TIME (R) +- UTC_TIMESTAMP (R) + +V + +- VALUE +- VALUES (R) +- VARBINARY (R) +- VARCHAR (R) +- VARIABLES +- VIEW +- VIRTUAL (R) + +W + +- WARNINGS +- WEEK +- WHEN (R) +- WHERE (R) +- WINDOW (R-Window) +- WITH (R) +- WRITE (R) + +X + +- XOR (R) + +Y + +- YEAR +- YEAR_MONTH (R) + +Z + +- ZEROFILL (R) diff --git a/dev/reference/sql/language-structure/literal-values.md b/reference/sql/language-structure/literal-values.md similarity index 100% rename from dev/reference/sql/language-structure/literal-values.md rename to reference/sql/language-structure/literal-values.md diff --git a/dev/reference/sql/language-structure/schema-object-names.md b/reference/sql/language-structure/schema-object-names.md similarity index 100% rename from dev/reference/sql/language-structure/schema-object-names.md rename to reference/sql/language-structure/schema-object-names.md diff --git a/dev/reference/sql/language-structure/user-defined-variables.md b/reference/sql/language-structure/user-defined-variables.md similarity index 100% rename from dev/reference/sql/language-structure/user-defined-variables.md rename to reference/sql/language-structure/user-defined-variables.md diff --git a/dev/reference/sql/partitioning.md b/reference/sql/partitioning.md similarity index 100% rename from dev/reference/sql/partitioning.md rename to reference/sql/partitioning.md diff --git a/dev/reference/sql/sql-mode.md b/reference/sql/sql-mode.md similarity index 100% rename from dev/reference/sql/sql-mode.md rename to reference/sql/sql-mode.md diff --git a/reference/sql/statements/add-column.md b/reference/sql/statements/add-column.md new file mode 100644 index 000000000000..2a00e4f97c4e --- /dev/null +++ b/reference/sql/statements/add-column.md @@ -0,0 +1,129 @@ +--- +title: ADD COLUMN +summary: TiDB 数据库中 ADD COLUMN 的使用概况。 +category: reference +--- + +# ADD COLUMN + +`ALTER TABLE.. ADD COLUMN` 语句用于在已有表中添加列。在 TiDB 中，`ADD COLUMN` 为在线操作，不会阻塞表中的数据读写。 + +## 语法图 + +**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) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (NULL); +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+ +| id | ++----+ +| 1 | ++----+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 ADD COLUMN c1 INT NOT NULL; +``` + +``` +Query OK, 0 rows affected (0.28 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 0 | ++----+----+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 ADD c2 INT NOT NULL AFTER c1; +``` + +``` +Query OK, 0 rows affected (0.28 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+----+ +| id | c1 | c2 | ++----+----+----+ +| 1 | 0 | 0 | ++----+----+----+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +* 不支持同时添加多列。 +* 不支持将新添加的列设为 `PRIMARY KEY`。 +* 不支持将新添加的列设为 `AUTO_INCREMENT`。 + +## 另请参阅 + +* [ADD INDEX](/reference/sql/statements/add-index.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) diff --git a/reference/sql/statements/add-index.md b/reference/sql/statements/add-index.md new file mode 100644 index 000000000000..94d971b1aa93 --- /dev/null +++ b/reference/sql/statements/add-index.md @@ -0,0 +1,113 @@ +--- +title: ADD INDEX +summary: TiDB 数据库中 ADD INDEX 的使用概况。 +category: reference +--- + +# ADD INDEX + +`ALTER TABLE.. ADD INDEX` 语句用于在已有表中添加一个索引。在 TiDB 中，`ADD INDEX` 为在线操作，不会阻塞表中的数据读写。 + +## 语法图 + +**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) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++---------------------+----------+------+-------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+-------------------------------------------------------------+ +| TableReader_7 | 10.00 | root | data:Selection_6 | +| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | +| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+-------------------------------------------------------------+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 ADD INDEX (c1); +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++-------------------+-------+------+-----------------------------------------------------------------+ +| id | count | task | operator info | ++-------------------+-------+------+-----------------------------------------------------------------+ +| IndexReader_6 | 10.00 | root | index:IndexScan_5 | +| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | ++-------------------+-------+------+-----------------------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 +* 不支持降序索引（类似于 MySQL 5.7）。 +* 目前尚不支持同时添加多个索引。 +* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 + +## 另请参阅 + +* [CREATE INDEX](/reference/sql/statements/create-index.md) +* [DROP INDEX](/reference/sql/statements/drop-index.md) +* [RENAME INDEX](/reference/sql/statements/rename-index.md) +* [ADD COLUMN](/reference/sql/statements/add-column.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [EXPLAIN](/reference/sql/statements/explain.md) diff --git a/reference/sql/statements/admin.md b/reference/sql/statements/admin.md new file mode 100644 index 000000000000..a97159da8257 --- /dev/null +++ b/reference/sql/statements/admin.md @@ -0,0 +1,163 @@ +--- +title: ADMIN +category: reference +--- + +# ADMIN + +`ADMIN` 语句是 TiDB 扩展语法，用于查看 TiDB 自身的状态，并对 TiDB 中的表数据进行校验。示例如下。 + +{{< copyable "sql" >}} + +```sql +ADMIN SHOW DDL; +``` + +`ADMIN SHOW DDL` 用于查看当前正在执行的 DDL 作业。 + +{{< copyable "sql" >}} + +```sql +ADMIN SHOW DDL JOBS [NUM] [WHERE where_condition]; +``` + +* `NUM`：查看已经执行完成的 DDL 作业队列中最近 `NUM` 条结果，未指定时，默认值为 10。 +* `WHERE`：`WHERE` 子句，可以添加过滤条件。 + +`ADMIN SHOW DDL JOBS` 用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 + +{{< copyable "sql" >}} + +```sql +ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...; +``` + +{{< copyable "sql" >}} + +```sql +ADMIN CANCEL DDL JOBS job_id [, job_id] ...; +``` + +{{< copyable "sql" >}} + +```sql +ADMIN CHECK TABLE tbl_name [, tbl_name] ...; +``` + +{{< copyable "sql" >}} + +```sql +ADMIN REPAIR TABLE tbl_name CREATE TABLE STATEMENT; +``` + +## 语句概览 + +**AdminStmt**： + +![AdminStmt](/media/sqlgram/AdminStmt.png) + +## 使用示例 + +执行以下命令，可查看正在执行的 DDL 任务中最近 10 条已经完成的 DDL 任务。未指定 `NUM` 时，默认只显示最近 10 条已经执行完的 DDL 任务。 + +{{< copyable "sql" >}} + +```sql +admin show ddl jobs; +``` + +``` ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | END_TIME | STATE | ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | | running | +| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | 2019-01-10 12:36:55.852 +0800 CST | rollback done | +| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | 2019-01-10 12:35:14.925 +0800 CST | synced | +| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | 2019-01-10 12:34:36.958 +0800 CST | synced | +| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | 2019-01-10 12:33:24.625 +0800 CST | synced | +| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | 2019-01-10 12:33:09.78 +0800 CST | synced | +| 39 | test | t1 | add column | public | 32 | 37 | 0 | 2019-01-10 12:32:55.42 +0800 CST | 2019-01-10 12:32:56.24 +0800 CST | synced | +| 38 | test | t1 | create table | public | 32 | 37 | 0 | 2019-01-10 12:32:41.956 +0800 CST | 2019-01-10 12:32:43.956 +0800 CST | synced | +| 36 | test | | drop table | none | 32 | 34 | 0 | 2019-01-10 11:29:59.982 +0800 CST | 2019-01-10 11:30:00.45 +0800 CST | synced | +| 35 | test | | create table | public | 32 | 34 | 0 | 2019-01-10 11:29:40.741 +0800 CST | 2019-01-10 11:29:41.682 +0800 CST | synced | +| 33 | test | | create schema | public | 32 | 0 | 0 | 2019-01-10 11:29:22.813 +0800 CST | 2019-01-10 11:29:23.954 +0800 CST | synced | ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +``` + +执行以下命令，可查看正在执行的 DDL 任务中最近 5 条已经执行完的 DDL 任务： + +{{< copyable "sql" >}} + +```sql +admin show ddl jobs 5; +``` + +``` ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | END_TIME | STATE | ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | | running | +| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | 2019-01-10 12:36:55.852 +0800 CST | rollback done | +| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | 2019-01-10 12:35:14.925 +0800 CST | synced | +| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | 2019-01-10 12:34:36.958 +0800 CST | synced | +| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | 2019-01-10 12:33:24.625 +0800 CST | synced | +| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | 2019-01-10 12:33:09.78 +0800 CST | synced | ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +``` + +执行以下命令，可查看 test 数据库中未执行完成的 DDL 任务，包括正在执行中以及最近 5 条已经执行完但是执行失败的 DDL 任务。 + +{{< copyable "sql" >}} + +```sql +admin show ddl jobs 5 where state!='synced' and db_name='test'; +``` + +``` ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | END_TIME | STATE | ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | | running | +| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | 2019-01-10 12:36:55.852 +0800 CST | rollback done | ++--------+---------+------------+---------------------+----------------+-----------+----------+-----------+-----------------------------------+-----------------------------------+---------------+ +``` + +* `JOB_ID`：每个 DDL 操作对应一个 DDL 作业，`JOB_ID` 全局唯一。 +* `DB_NAME`：执行 DDL 操作的数据库的名称。 +* `TABLE_NAME`：执行 DDL 操作的表的名称。 +* `JOB_TYPE`：DDL 操作的类型。 +* `SCHEMA_STATE`：schema 的当前状态。如果 `JOB_TYPE` 是 `add index`，则为 index 的状态；如果是 `add column`，则为 column 的状态，如果是 `create table`，则为 table 的状态。常见的状态有以下几种： + * `none`：表示不存在。一般 `drop` 操作或者 `create` 操作失败回滚后，会变为 `none` 状态。 + * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在[Online, Asynchronous Schema Change in F1](http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。 + * `public`：表示存在且可用。一般 `create table` 和 `add index/column` 等操作完成后，会变为 `public` 状态，表示新建的 table/column/index 可以正常读写了。 +* `SCHEMA_ID`：执行 DDL 操作的数据库的 ID。 +* `TABLE_ID`：执行 DDL 操作的表的 ID。 +* `ROW_COUNT`：执行 `add index` 操作时，当前已经添加完成的数据行数。 +* `START_TIME`：DDL 操作的开始时间。 +* `END_TIME`：DDL 操作的结束时间。 +* `STATE`：DDL 操作的状态。常见的状态有以下几种： + * `none`：表示该操作任务已经进入 DDL 作业队列中，但尚未执行，因为还在排队等待前面的 DDL 作业完成。另一种原因可能是执行 `drop` 操作后，会变为 `none` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。 + * `running`：表示该操作正在执行。 + * `synced`：表示该操作已经执行成功，且所有 TiDB 实例都已经同步该状态。 + * `rollback done`：表示该操作执行失败，回滚完成。 + * `rollingback`：表示该操作执行失败，正在回滚。 + * `cancelling`：表示正在取消该操作。这个状态只有在用 `ADMIN CANCEL DDL JOBS` 命令取消 DDL 作业时才会出现。 + +- `ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...`：用于查看 `job_id` 对应的 DDL 任务的原始 SQL 语句。这个 `job_id` 只会搜索正在运行中的 DDL 作业以及 DDL 历史作业队列中最近的十条结果。 +- `ADMIN CANCEL DDL JOBS job_id [, job_id] ...`：用于取消当前正在运行的 DDL 作业，并返回对应作业是否取消成功。如果取消失败，会显示失败的具体原因。 + + > **注意：** + > + > 只有该操作可以取消 DDL 作业，其他所有的操作和环境变更（例如机器重启、集群重启）都不会取消 DDL 作业。 + > + > 该操作可以同时取消多个 DDL 作业。可以通过 `ADMIN SHOW DDL JOBS` 语句来获取 DDL 作业的 ID。 + > + > 如果希望取消的作业已经完成，则取消操作将会失败。 + +- `ADMIN CHECK TABLE tbl_name [, tbl_name] ...`：用于对给定表中的所有数据和对应索引进行一致性校验，若通过校验，则返回空的查询结果；否则返回数据不一致的错误信息。 + +- `ADMIN REPAIR TABLE tbl_name CREATE TABLE STATEMENT`：在极端情况下，用于对存储层中的表的元信息进行非可信的覆盖，“非可信”是指需要人为保证原表的元信息可以完全由 `CREATE TABLE STATEMENT` 提供。该语句需要打开配置文件项中的 [`repair-mode`](/reference/configuration/tidb-server/configuration-file.md#repair-mode) 开关，并且需要确保所修复的表名在 [`repair-table-list`](/reference/configuration/tidb-server/configuration-file.md#repair-table-list) 名单中。 + +## MySQL 兼容性 + +ADMIN 语句是 TiDB 对于 MySQL 语法的扩展。 diff --git a/reference/sql/statements/alter-database.md b/reference/sql/statements/alter-database.md new file mode 100644 index 000000000000..8f1839f5aa66 --- /dev/null +++ b/reference/sql/statements/alter-database.md @@ -0,0 +1,28 @@ +--- +title: ALTER DATABASE +summary: TiDB 数据库中 ALTER DATABASE 的使用概况。 +category: reference +--- + +# ALTER DATABASE + +`ALTER DATABASE` 用于修改指定或当前数据库的默认字符集和排序规则。`ALTER SCHEMA` 跟 `ALTER DATABASE` 操作效果一样。 + +## 示例 + +{{< copyable "sql" >}} + +```sql +ALTER {DATABASE | SCHEMA} [db_name] + alter_specification ... +alter_specification: + [DEFAULT] CHARACTER SET [=] charset_name + | [DEFAULT] COLLATE [=] collation_name +``` + +`alter_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/reference/sql/character-set.md)。 + +## 另请参阅 + +* [CREATE DATABASE](/reference/sql/statements/create-database.md) +* [SHOW DATABASES](/reference/sql/statements/show-databases.md) diff --git a/reference/sql/statements/alter-table.md b/reference/sql/statements/alter-table.md new file mode 100644 index 000000000000..d438f7d2bf68 --- /dev/null +++ b/reference/sql/statements/alter-table.md @@ -0,0 +1,108 @@ +--- +title: ALTER TABLE +summary: TiDB 数据库中 ALTER TABLE 的使用概况。 +category: reference +--- + +# ALTER TABLE + +`ALTER TABLE` 语句用于对已有表进行修改，以符合新表结构。`ALTER TABLE` 语句可用于： + +* [`ADD`](/reference/sql/statements/add-index.md)，[`DROP`](/reference/sql/statements/drop-index.md)，或 [`RENAME`](/reference/sql/statements/rename-index.md) 索引 +* [`ADD`](/reference/sql/statements/add-column.md)，[`DROP`](/reference/sql/statements/drop-column.md)，[`MODIFY`](/reference/sql/statements/modify-column.md) 或 [`CHANGE`](/reference/sql/statements/change-column.md) 列 + +## 语法图 + +**AlterTableStmt:** + +![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +**AlterTableSpec:** + +![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++---------------------+----------+------+-------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+-------------------------------------------------------------+ +| TableReader_7 | 10.00 | root | data:Selection_6 | +| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | +| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+-------------------------------------------------------------+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 ADD INDEX (c1); +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++-------------------+-------+------+-----------------------------------------------------------------+ +| id | count | task | operator info | ++-------------------+-------+------+-----------------------------------------------------------------+ +| IndexReader_6 | 10.00 | root | index:IndexScan_5 | +| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | ++-------------------+-------+------+-----------------------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +* 支持除空间类型外的所有数据类型。 +* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 + +## 另请参阅 + +* [ADD COLUMN](/reference/sql/statements/add-column.md) +* [DROP COLUMN](/reference/sql/statements/drop-column.md) +* [ADD INDEX](/reference/sql/statements/add-index.md) +* [DROP INDEX](/reference/sql/statements/drop-index.md) +* [RENAME INDEX](/reference/sql/statements/rename-index.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/alter-user.md b/reference/sql/statements/alter-user.md new file mode 100644 index 000000000000..8b6f508b4643 --- /dev/null +++ b/reference/sql/statements/alter-user.md @@ -0,0 +1,84 @@ +--- +title: ALTER USER +summary: TiDB 数据库中 ALTER USER 的使用概况。 +category: reference +--- + +# ALTER USER + +`ALTER USER` 语句用于更改 TiDB 权限系统内的已有用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 + +## 语法图 + +**AlterUserStmt:** + +![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) + +**UserSpecList:** + +![UserSpecList](/media/sqlgram/UserSpecList.png) + +**UserSpec:** + +![UserSpec](/media/sqlgram/UserSpec.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; +``` + +``` +Query OK, 1 row affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE USER 'newuser'; +``` + +```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER for newuser@% | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*5806E04BBEE79E1899964C6A04D68BCA69B1A879' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER USER 'newuser' IDENTIFIED BY 'newnewpassword'; +``` + +``` +Query OK, 0 rows affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE USER 'newuser'; +``` + +```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER for newuser@% | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*FB8A1EA1353E8775CA836233E367FBDFCB37BE73' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +* 在 MySQL 中，`ALTER` 语句用于更改属性，例如使密码失效。但 TiDB 尚不支持此功能。 + +## 另请参阅 + +* [Security Compatibility with MySQL](/reference/security/compatibility.md) +* [CREATE USER](/reference/sql/statements/create-user.md) +* [DROP USER](/reference/sql/statements/drop-user.md) +* [SHOW CREATE USER](/reference/sql/statements/show-create-user.md) diff --git a/reference/sql/statements/analyze-table.md b/reference/sql/statements/analyze-table.md new file mode 100644 index 000000000000..e44827a42477 --- /dev/null +++ b/reference/sql/statements/analyze-table.md @@ -0,0 +1,109 @@ +--- +title: ANALYZE TABLE +summary: TiDB 数据库中 ANALYZE TABLE 的使用概况。 +category: reference +--- + +# ANALYZE TABLE + +`ANALYZE TABLE` 语句用于更新 TiDB 在表和索引上留下的统计信息。执行大批量更新或导入记录后，或查询执行计划不是最佳时，建议运行 `ANALYZE TABLE`。 + +当 TiDB 逐渐发现这些统计数据与预估不一致时，也会自动更新其统计数据。 + +## 语法图 + +**AnalyzeTableStmt:** + +![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) + +**TableNameList:** + +![TableNameList](/media/sqlgram/TableNameList.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 ADD INDEX (c1); +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++-------------------+-------+------+-----------------------------------------------------------------+ +| id | count | task | operator info | ++-------------------+-------+------+-----------------------------------------------------------------+ +| IndexReader_6 | 10.00 | root | index:IndexScan_5 | +| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | ++-------------------+-------+------+-----------------------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +analyze table t1; +``` + +``` +Query OK, 0 rows affected (0.13 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++-------------------+-------+------+---------------------------------------------------+ +| id | count | task | operator info | ++-------------------+-------+------+---------------------------------------------------+ +| IndexReader_6 | 1.00 | root | index:IndexScan_5 | +| └─IndexScan_5 | 1.00 | cop | table:t1, index:c1, range:[3,3], keep order:false | ++-------------------+-------+------+---------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`ANALYZE TABLE` 在语法上与 MySQL 类似。但 `ANALYZE TABLE` 在 TiDB 上执行所需时间可能长得多，因为它的内部运行方式不同。 + +## 另请参阅 + +* [EXPLAIN](/reference/sql/statements/explain.md) +* [EXPLAIN ANALYZE](/reference/sql/statements/explain-analyze.md) diff --git a/reference/sql/statements/begin.md b/reference/sql/statements/begin.md new file mode 100644 index 000000000000..cd8e1ecce868 --- /dev/null +++ b/reference/sql/statements/begin.md @@ -0,0 +1,69 @@ +--- +title: BEGIN +summary: TiDB 数据库中 BEGIN 的使用概况。 +category: reference +--- + +# BEGIN + +`BEGIN` 语句用于在 TiDB 内启动一个新事务，类似于 `START TRANSACTION` 和 `SET autocommit=0` 语句。 + +在没有 `BEGIN` 语句的情况下，每个语句默认在各自的事务中自动提交，从而确保 MySQL 兼容性。 + +## 语法图 + +**BeginTransactionStmt:** + +![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +BEGIN; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1); +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +COMMIT; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +## MySQL 兼容性 + +`BEGIN` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上[提交 issue](/report-issue.md)。 + +## 另请参阅 + +* [COMMIT](/reference/sql/statements/commit.md) +* [ROLLBACK](/reference/sql/statements/rollback.md) +* [START TRANSACTION](/reference/sql/statements/start-transaction.md) diff --git a/reference/sql/statements/change-column.md b/reference/sql/statements/change-column.md new file mode 100644 index 000000000000..19afc8e166a9 --- /dev/null +++ b/reference/sql/statements/change-column.md @@ -0,0 +1,121 @@ +--- +title: CHANGE COLUMN +summary: TiDB 数据库中 CHANGE COLUMN 的使用概况。 +category: reference +--- + +# CHANGE COLUMN + +`ALTER TABLE.. CHANGE COLUMN` 语句用于在已有表上更改列，包括对列进行重命名，和将数据改为兼容类型。 + +## 语法图 + +**AlterTableStmt:** + +![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) + +**AlterTableSpec:** + +![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) + +**ColumnKeywordOpt:** + +![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) + +**ColumnName:** + +![ColumnName](/media/sqlgram/ColumnName.png) + +**ColumnDef:** + +![ColumnDef](/media/sqlgram/ColumnDef.png) + +**ColumnPosition:** + +![ColumnPosition](/media/sqlgram/ColumnPosition.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 CHANGE col1 col2 INT; +``` + +``` +Query OK, 0 rows affected (0.09 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 CHANGE col2 col3 BIGINT, ALGORITHM=INSTANT; +``` + +``` +Query OK, 0 rows affected (0.08 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 CHANGE col3 col3 INT; +``` + +``` +ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 CHANGE col3 col3 BLOB; +``` + +``` +ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 CHANGE col3 col4 BIGINT, CHANGE id id2 INT NOT NULL; +``` + +``` +ERROR 1105 (HY000): can't run multi schema change +``` + +## MySQL 兼容性 + +* 目前尚不支持在单个 `ALTER TABLE` 语句中进行多个更改。 +* 仅支持特定的数据类型更改。例如，支持将 `INTEGER` 更改为 `BIGINT`，但不支持将 `BIGINT` 更改为 `INTEGER`。不支持从整数更改为字符串格式或 BLOB 类型。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [ADD COLUMN](/reference/sql/statements/add-column.md) +* [DROP COLUMN](/reference/sql/statements/drop-column.md) +* [MODIFY COLUMN](/reference/sql/statements/modify-column.md) diff --git a/reference/sql/statements/commit.md b/reference/sql/statements/commit.md new file mode 100644 index 000000000000..e44590443b57 --- /dev/null +++ b/reference/sql/statements/commit.md @@ -0,0 +1,71 @@ +--- +title: COMMIT +summary: TiDB 数据库中 COMMIT 的使用概况。 +category: reference +--- + +# COMMIT + +`COMMIT` 语句用于在 TiDB 服务器内部提交事务。 + +在不使用 `BEGIN` 或 `START TRANSACTION` 语句的情况下，TiDB 中每一个查询语句本身也会默认作为事务处理，自动提交，确保了与 MySQL 的兼容。 + +## 语法图 + +**CommitStmt:** + +![CommitStmt](/media/sqlgram/CommitStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +START TRANSACTION; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1); +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +COMMIT; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +## MySQL 兼容性 + +* 在 MySQL 中，除了有多个 primary 的群组复制以外，`COMMIT` 语句通常不会导致错误。相比之下，TiDB 使用乐观并发控制，冲突可能导致 `COMMIT` 返回错误。 +* 默认情况下，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。 + +## 另请参阅 + +* [START TRANSACTION](/reference/sql/statements/start-transaction.md) +* [ROLLBACK](/reference/sql/statements/rollback.md) +* [BEGIN](/reference/sql/statements/begin.md) +* [事务的惰性检查](/reference/transactions/overview.md#事务的惰性检查) diff --git a/reference/sql/statements/create-database.md b/reference/sql/statements/create-database.md new file mode 100644 index 000000000000..406cf63bcd9d --- /dev/null +++ b/reference/sql/statements/create-database.md @@ -0,0 +1,108 @@ +--- +title: CREATE DATABASE +summary: TiDB 数据库中 CREATE DATABASE 的使用概况。 +category: reference +--- + +# CREATE DATABASE + +`CREATE DATABASE` 语句用于在 TiDB 上创建新数据库。按照 SQL 标准，“数据库” 一词在 MySQL 术语中最接近 “schema”。 + +## 语法图 + +**CreateDatabaseStmt:** + +![CreateDatabaseStmt](/media/sqlgram/CreateDatabaseStmt.png) + +**DatabaseSym:** + +![DatabaseSym](/media/sqlgram/DatabaseSym.png) + +**IfNotExists:** + +![IfNotExists](/media/sqlgram/IfNotExists.png) + +**DBName:** + +![DBName](/media/sqlgram/DBName.png) + +**DatabaseOptionListOpt:** + +![DatabaseOptionListOpt](/media/sqlgram/DatabaseOptionListOpt.png) + +## 语法说明 + +`CREATE DATABASE` 用于创建数据库，并可以指定数据库的默认属性（如数据库默认字符集、排序规则）。`CREATE SCHEMA` 跟 `CREATE DATABASE` 操作效果一样。 + +{{< copyable "sql" >}} + +```sql +CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name + [create_specification] ... + +create_specification: + [DEFAULT] CHARACTER SET [=] charset_name + | [DEFAULT] COLLATE [=] collation_name +``` + +当创建已存在的数据库且不指定使用 `IF NOT EXISTS` 时会报错。 + +`create_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/reference/sql/character-set.md)。 + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE DATABASE mynewdatabase; +``` + +``` +Query OK, 0 rows affected (0.09 sec) +``` + +{{< copyable "sql" >}} + +```sql +USE mynewdatabase; +``` + +``` +Database changed +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES; +``` + +``` ++-------------------------+ +| Tables_in_mynewdatabase | ++-------------------------+ +| t1 | ++-------------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`CREATE DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [USE](/reference/sql/statements/use.md) +* [ALTER DATABASE](/reference/sql/statements/alter-database.md) +* [DROP DATABASE](/reference/sql/statements/drop-database.md) +* [SHOW DATABASES](/reference/sql/statements/show-databases.md) diff --git a/reference/sql/statements/create-index.md b/reference/sql/statements/create-index.md new file mode 100644 index 000000000000..fc2b24a1b2ed --- /dev/null +++ b/reference/sql/statements/create-index.md @@ -0,0 +1,148 @@ +--- +title: CREATE INDEX +summary: CREATE INDEX 在 TiDB 中的使用概况 +category: reference +--- + +# CREATE INDEX + +`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 `ALTER TABLE .. ADD INDEX`。包含该语句提供了 MySQL 兼容性。 + +## 语法图 + +**CreateIndexStmt:** + +![CreateIndexStmt](/media/sqlgram/CreateIndexStmt.png) + +**CreateIndexStmtUnique:** + +![CreateIndexStmtUnique](/media/sqlgram/CreateIndexStmtUnique.png) + +**Identifier:** + +![Identifier](/media/sqlgram/Identifier.png) + +**IndexTypeOpt:** + +![IndexTypeOpt](/media/sqlgram/IndexTypeOpt.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +**IndexColNameList:** + +![IndexColNameList](/media/sqlgram/IndexColNameList.png) + +**IndexOptionList:** + +![IndexOptionList](/media/sqlgram/IndexOptionList.png) + +**IndexOption:** + +![IndexOption](/media/sqlgram/IndexOption.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++---------------------+----------+------+-------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+-------------------------------------------------------------+ +| TableReader_7 | 10.00 | root | data:Selection_6 | +| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | +| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+-------------------------------------------------------------+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE INDEX c1 ON t1 (c1); +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++-------------------+-------+------+-----------------------------------------------------------------+ +| id | count | task | operator info | ++-------------------+-------+------+-----------------------------------------------------------------+ +| IndexReader_6 | 10.00 | root | index:IndexScan_5 | +| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | ++-------------------+-------+------+-----------------------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 DROP INDEX c1; +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE UNIQUE INDEX c1 ON t1 (c1); +``` + +``` +Query OK, 0 rows affected (0.31 sec) +``` + +## 相关 session 变量 + +和 `CREATE INDEX` 语句相关的全局变量有 `tidb_ddl_reorg_worker_cnt`，`tidb_ddl_reorg_batch_size` 和 `tidb_ddl_reorg_priority`，具体可以参考 [TiDB 特定系统变量](/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_ddl_reorg_worker_cnt)。 + +## MySQL 兼容性 + +* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 +* 不支持降序索引 （类似于 MySQL 5.7）。 +* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 + +## 另请参阅 + +* [ADD INDEX](/reference/sql/statements/add-index.md) +* [DROP INDEX](/reference/sql/statements/drop-index.md) +* [RENAME INDEX](/reference/sql/statements/rename-index.md) +* [ADD COLUMN](/reference/sql/statements/add-column.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [EXPLAIN](/reference/sql/statements/explain.md) diff --git a/reference/sql/statements/create-table-like.md b/reference/sql/statements/create-table-like.md new file mode 100644 index 000000000000..0adaa2eab4a8 --- /dev/null +++ b/reference/sql/statements/create-table-like.md @@ -0,0 +1,94 @@ +--- +title: CREATE TABLE LIKE +summary: TiDB 数据库中 CREATE TABLE LIKE 的使用概况。 +category: reference +--- + +# CREATE TABLE LIKE + +`CREATE TABLE LIKE` 语句用于复制已有表的定义，但不复制任何数据。 + +## 语法图 + +**CreateTableStmt:** + +![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) + +**LikeTableWithOrWithoutParen:** + +![LikeTableWithOrWithoutParen](/media/sqlgram/LikeTableWithOrWithoutParen.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.13 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++---+ +| a | ++---+ +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | ++---+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t2 LIKE t1; +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t2; +``` + +``` +Empty set (0.00 sec) +``` + +## MySQL 兼容性 + +`CREATE TABLE LIKE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/create-table.md b/reference/sql/statements/create-table.md new file mode 100644 index 000000000000..2ead05fe3523 --- /dev/null +++ b/reference/sql/statements/create-table.md @@ -0,0 +1,303 @@ +--- +title: CREATE TABLE +summary: TiDB 数据库中 CREATE TABLE 的使用概况 +category: reference +--- + +# CREATE TABLE + +`CREATE TABLE` 语句用于在当前所选数据库中创建新表。另可参阅单独的 `CREATE TABLE LIKE` 文档。 + +## 语法图 + +**CreateTableStmt:** + +![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) + +**IfNotExists:** + +![IfNotExists](/media/sqlgram/IfNotExists.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +**TableElementListOpt:** + +![TableElementListOpt](/media/sqlgram/TableElementListOpt.png) + +**TableElement:** + +![TableElement](/media/sqlgram/TableElement.png) + +**PartitionOpt:** + +![PartitionOpt](/media/sqlgram/PartitionOpt.png) + +**ColumnDef:** + +![ColumnDef](/media/sqlgram/ColumnDef.png) + +**ColumnName:** + +![ColumnName](/media/sqlgram/ColumnName.png) + +**Type:** + +![Type](/media/sqlgram/Type.png) + +**ColumnOptionListOpt:** + +![ColumnOptionListOpt](/media/sqlgram/ColumnOptionListOpt.png) + +**TableOptionListOpt:** + +![TableOptionListOpt](/media/sqlgram/TableOptionListOpt.png) + +## 语法说明 + +`CREATE TABLE` 用于创建一个表。目前不支持临时表，不支持 `CHECK` 约束，不支持创建表的同时从其它表导入数据功能。在语法上也支持一些 `Partition_options`，但是并不完全，就不做列举了。 + +以下是 `CREATE TABLE` 相关的语法说明： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE [IF NOT EXISTS] tbl_name + (create_definition,...) + [table_options] +``` + +使用 `IF NOT EXIST` 时，即使创建的表已经存在，也不会报错，如果不指定时，则报错。 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE [IF NOT EXISTS] tbl_name + { LIKE old_tbl_name | (LIKE old_tbl_name) } +``` + +使用 `LIKE` 基于一个表的定义创建一个空表，包括这个表中的列属性和索引属性。 + +```sql +create_definition: + col_name column_definition + | [CONSTRAINT [symbol]] PRIMARY KEY [index_type] (index_col_name,...) + [index_option] ... + | {INDEX|KEY} [index_name] [index_type] (index_col_name,...) + [index_option] ... + | [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY] + [index_name] [index_type] (index_col_name,...) + [index_option] ... + | {FULLTEXT} [INDEX|KEY] [index_name] (index_col_name,...) + [index_option] ... + | [CONSTRAINT [symbol]] FOREIGN KEY + [index_name] (index_col_name,...) reference_definition +``` + +`create_definition` 中 `FULLTEXT` 和 `FOREIGN KEY` 目前只是语法上支持。 + +```sql +column_definition: + data_type [NOT NULL | NULL] [DEFAULT default_value] + [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] + [COMMENT 'string'] + [reference_definition] + | data_type [GENERATED ALWAYS] AS (expression) + [VIRTUAL | STORED] [UNIQUE [KEY]] [COMMENT comment] + [NOT NULL | NULL] [[PRIMARY] KEY] + +data_type: + BIT[(length)] + | TINYINT[(length)] [UNSIGNED] [ZEROFILL] + | SMALLINT[(length)] [UNSIGNED] [ZEROFILL] + | MEDIUMINT[(length)] [UNSIGNED] [ZEROFILL] + | INT[(length)] [UNSIGNED] [ZEROFILL] + | INTEGER[(length)] [UNSIGNED] [ZEROFILL] + | BIGINT[(length)] [UNSIGNED] [ZEROFILL] + | REAL[(length,decimals)] [UNSIGNED] [ZEROFILL] + | DOUBLE[(length,decimals)] [UNSIGNED] [ZEROFILL] + | FLOAT[(length,decimals)] [UNSIGNED] [ZEROFILL] + | DECIMAL[(length[,decimals])] [UNSIGNED] [ZEROFILL] + | NUMERIC[(length[,decimals])] [UNSIGNED] [ZEROFILL] + | DATE + | TIME[(fsp)] + | TIMESTAMP[(fsp)] + | DATETIME[(fsp)] + | YEAR + | CHAR[(length)] [BINARY] + [CHARACTER SET charset_name] [COLLATE collation_name] + | VARCHAR(length) [BINARY] + [CHARACTER SET charset_name] [COLLATE collation_name] + | BINARY[(length)] + | VARBINARY(length) + | TINYBLOB + | BLOB + | MEDIUMBLOB + | LONGBLOB + | TINYTEXT [BINARY] + [CHARACTER SET charset_name] [COLLATE collation_name] + | TEXT [BINARY] + [CHARACTER SET charset_name] [COLLATE collation_name] + | MEDIUMTEXT [BINARY] + [CHARACTER SET charset_name] [COLLATE collation_name] + | LONGTEXT [BINARY] + [CHARACTER SET charset_name] [COLLATE collation_name] + | ENUM(value1,value2,value3,...) + [CHARACTER SET charset_name] [COLLATE collation_name] + | SET(value1,value2,value3,...) + [CHARACTER SET charset_name] [COLLATE collation_name] + | JSON +``` + +`data_type` 请参考[数据类型](/reference/sql/data-types/overview.md)章节。 + +```sql +index_col_name: + col_name [(length)] [ASC | DESC] +``` + +`index_col_name` 中 `[ASC | DESC]` 目前只是语法上支持。 + +```sql +index_type: + USING {BTREE | HASH} +``` + +`index_type` 目前只是语法上支持。 + +```sql +index_option: + KEY_BLOCK_SIZE [=] value + | index_type + | COMMENT 'string' +``` + +`index_option` 中 `KEY_BLOCK_SIZE` 目前只是语法上支持。 + +```sql +reference_definition: + REFERENCES tbl_name (index_col_name,...) + [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] + [ON DELETE reference_option] + [ON UPDATE reference_option] + +reference_option: + RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT +``` + +```sql +table_options: + table_option [[,] table_option] ... + +table_option: + AUTO_INCREMENT [=] value + | AVG_ROW_LENGTH [=] value + | SHARD_ROW_ID_BITS [=] value + | PRE_SPLIT_REGIONS [=] value + | [DEFAULT] CHARACTER SET [=] charset_name + | CHECKSUM [=] {0 | 1} + | [DEFAULT] COLLATE [=] collation_name + | COMMENT [=] 'string' + | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'} + | CONNECTION [=] 'connect_string' + | DELAY_KEY_WRITE [=] {0 | 1} + | ENGINE [=] engine_name + | KEY_BLOCK_SIZE [=] value + | MAX_ROWS [=] value + | MIN_ROWS [=] value + | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT} + | STATS_PERSISTENT [=] {DEFAULT|0|1} +``` + +`table_option` 目前支持的只有 `AUTO_INCREMENT`、`SHARD_ROW_ID_BITS`（详情介绍请参考 [TiDB 专用系统变量和语法](/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）、`PRE_SPLIT_REGIONS`、`CHARACTER SET`、`COLLATE` 和 `COMMENT`，其它只是语法上支持。具体内容参考下表，各个子句之间用逗号隔开。 + +| 参数 |含义 |举例 | +|----------------|--------------------------------------|----------------------------| +|`AUTO_INCREMENT`|自增字段初始值 |`AUTO_INCREMENT` = 5| +|`SHARD_ROW_ID_BITS`|用来设置隐式 _tidb_rowid 的分片数量的 bit 位数 |`SHARD_ROW_ID_BITS` = 4| +|`PRE_SPLIT_REGIONS`|用来在建表时预先均匀切分 `2^(PRE_SPLIT_REGIONS)` 个 Region |`PRE_SPLIT_REGIONS` = 4| +|`CHARACTER SET` |指定该表所使用的字符集 | `CHARACTER SET` = 'utf8mb4'| +|`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| +|`COMMENT` |注释信息 | `COMMENT` = 'comment info'| + +`split-table` 配置项默认情况下会开启，在此配置项开启时，建表操作会为每个表建立单独的 Region。 + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t2 LIKE t1; +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +DESC t1; +``` + +``` ++-------+---------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+---------+------+------+---------+-------+ +| a | int(11) | YES | | NULL | | ++-------+---------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1); +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++------+ +| a | ++------+ +| 1 | ++------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +* TiDB 不支持 `CREATE TEMPORARY TABLE` 语法。 +* 支持除空间类型以外的所有数据类型。 +* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 +* `KEY_BLOCK_SIZE` 和 `ENGINE` 属性可被解析，但会被忽略。 +* `index_col_name` 属性支持 length 选项，最大长度限制为 3072 字节。此长度限制不会更改，具体取决于存储引擎和建表时使用的字符集。 +* `index_col_name` 属性支持 `ASC` 和 `DESC` 的索引排序选项。 +* `COMMENT` 属性最多支持 1024 个字符，不支持 `WITH PARSER` 选项。 +* TiDB 在单个表中最多支持 512 列。InnoDB 中相应的数量限制为 1017，MySQL 中的硬限制为 4096。 + +## 另请参阅 + +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [CREATE TABLE LIKE](/reference/sql/statements/create-table-like.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/create-user.md b/reference/sql/statements/create-user.md new file mode 100644 index 000000000000..78bad4644e6b --- /dev/null +++ b/reference/sql/statements/create-user.md @@ -0,0 +1,69 @@ +--- +title: CREATE USER +summary: TiDB 数据库中 CREATE USER 的使用概况。 +category: reference +--- + +# CREATE USER + +`CREATE USER` 语句用于创建带有指定密码的新用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 + +## 语法图 + +**CreateUserStmt:** + +![CreateUserStmt](/media/sqlgram/CreateUserStmt.png) + +**IfNotExists:** + +![IfNotExists](/media/sqlgram/IfNotExists.png) + +**UserSpecList:** + +![UserSpecList](/media/sqlgram/UserSpecList.png) + +**UserSpec:** + +![UserSpec](/media/sqlgram/UserSpec.png) + +**AuthOption:** + +![AuthOption](/media/sqlgram/AuthOption.png) + +**StringName:** + +![StringName](/media/sqlgram/StringName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; +``` + +``` +Query OK, 1 row affected (0.04 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER 'newuser2'@'192.168.1.1' IDENTIFIED BY 'newuserpassword'; +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +## MySQL 兼容性 + +* TiDB 尚不支持若干 `CREATE` 选项。这些选项可被解析，但会被忽略。 + +## 另请参阅 + +* [Security Compatibility with MySQL](/reference/security/compatibility.md) +* [DROP USER](/reference/sql/statements/drop-user.md) +* [SHOW CREATE USER](/reference/sql/statements/show-create-user.md) +* [ALTER USER](/reference/sql/statements/alter-user.md) +* [Privilege Management](/reference/security/privilege-system.md) diff --git a/reference/sql/statements/create-view.md b/reference/sql/statements/create-view.md new file mode 100644 index 000000000000..7f4bd23923ed --- /dev/null +++ b/reference/sql/statements/create-view.md @@ -0,0 +1,160 @@ +--- +title: CREATE VIEW +summary: TiDB 数据库中 CREATE VIEW 的使用概况。 +category: reference +--- + +# CREATE VIEW + +使用 `CREATE VIEW` 语句将 `SELECT` 语句保存为类似于表的可查询对象。TiDB 中的视图是非物化的，这意味着在查询视图时，TiDB 将在内部重写查询，以将视图定义与 SQL 查询结合起来。 + +## 语法图 + +**CreateViewStmt:** + +![CreateViewStmt](/media/sqlgram/CreateViewStmt.png) + +**OrReplace:** + +![OrReplace](/media/sqlgram/OrReplace.png) + +**ViewAlgorithm:** + +![ViewAlgorithm](/media/sqlgram/ViewAlgorithm.png) + +**ViewDefiner:** + +![ViewDefiner](/media/sqlgram/ViewDefiner.png) + +**ViewSQLSecurity:** + +![ViewSQLSecurity](/media/sqlgram/ViewSQLSecurity.png) + +**ViewName:** + +![ViewName](/media/sqlgram/ViewName.png) + +**ViewFieldList:** + +![ViewFieldList](/media/sqlgram/ViewFieldList.png) + +**ViewCheckOption:** + +![ViewCheckOption](/media/sqlgram/ViewCheckOption.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM v1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (6); +``` + +``` +Query OK, 1 row affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM v1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | +| 6 | 6 | ++----+----+ +4 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO v1 (c1) VALUES (7); +``` + +``` +ERROR 1105 (HY000): insert into view v1 is not supported now. +``` + +## MySQL 兼容性 + +* 目前 TiDB 中的视图不可插入且不可更新。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [DROP TABLE](/reference/sql/statements/drop-table.md) diff --git a/reference/sql/statements/deallocate.md b/reference/sql/statements/deallocate.md new file mode 100644 index 000000000000..41475d5f610a --- /dev/null +++ b/reference/sql/statements/deallocate.md @@ -0,0 +1,79 @@ +--- +title: DEALLOCATE +summary: TiDB 数据库中 DEALLOCATE 的使用概况。 +category: reference +--- + +# DEALLOCATE + +`DEALLOCATE` 语句用于为服务器端预处理语句提供 SQL 接口。 + +## 语法图 + +**DeallocateStmt:** + +![DeallocateStmt](/media/sqlgram/DeallocateStmt.png) + +**DeallocateSym:** + +![DeallocateSym](/media/sqlgram/DeallocateSym.png) + +**Identifier:** + +![Identifier](/media/sqlgram/Identifier.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET @number = 5; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXECUTE mystmt USING @number; +``` + +``` ++------+ +| num | ++------+ +| 5 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DEALLOCATE PREPARE mystmt; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +## MySQL 兼容性 + +`DEALLOCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [PREPARE](/reference/sql/statements/prepare.md) +* [EXECUTE](/reference/sql/statements/execute.md) diff --git a/reference/sql/statements/delete.md b/reference/sql/statements/delete.md new file mode 100644 index 000000000000..a9e855c9909e --- /dev/null +++ b/reference/sql/statements/delete.md @@ -0,0 +1,96 @@ +--- +title: DELETE +summary: TiDB 数据库中 DELETE 的使用概况。 +category: reference +--- + +# DELETE + +`DELETE` 语句用于从指定的表中删除行。 + +## 语法图 + +**DeleteFromStmt:** + +![DeleteFromStmt](/media/sqlgram/DeleteFromStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DELETE FROM t1 WHERE id = 4; +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 5 | 5 | ++----+----+ +4 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`DELETE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [INSERT](/reference/sql/statements/insert.md) +* [SELECT](/reference/sql/statements/select.md) +* [UPDATE](/reference/sql/statements/update.md) +* [REPLACE](/reference/sql/statements/replace.md) diff --git a/reference/sql/statements/desc.md b/reference/sql/statements/desc.md new file mode 100644 index 000000000000..eb1b5f291111 --- /dev/null +++ b/reference/sql/statements/desc.md @@ -0,0 +1,9 @@ +--- +title: DESC +summary: TiDB 数据库中 DESC 的使用概况。 +category: reference +--- + +# DESC + +`DESC` 语句是 [`EXPLAIN`](/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/reference/sql/statements/describe.md b/reference/sql/statements/describe.md new file mode 100644 index 000000000000..bb4d85c6868d --- /dev/null +++ b/reference/sql/statements/describe.md @@ -0,0 +1,9 @@ +--- +title: DESCRIBE +summary: TiDB 数据库中 DESCRIBE 的使用概况。 +category: reference +--- + +# DESCRIBE + +`DESCRIBE` 语句为 [`EXPLAIN`](/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/reference/sql/statements/do.md b/reference/sql/statements/do.md new file mode 100644 index 000000000000..bc6b8b9d6d74 --- /dev/null +++ b/reference/sql/statements/do.md @@ -0,0 +1,68 @@ +--- +title: DO | TiDB SQL Statement Reference +summary: TiDB 数据库中 DO 的使用概况。 +category: reference +--- + +# DO + +`DO` 语句用于执行表达式，而不返回结果。在 MySQL 中，`DO` 的一个常见用例是执行存储的程序，而无需处理结果。但是 TiDB 不提供存储例程，因此该功能的使用较为受限。 + +## 语法图 + +**DoStmt:** + +![DoStmt](/media/sqlgram/DoStmt.png) + +**ExpressionList:** + +![ExpressionList](/media/sqlgram/ExpressionList.png) + +**Expression:** + +![Expression](/media/sqlgram/Expression.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SELECT SLEEP(5); +``` + +``` ++----------+ +| SLEEP(5) | ++----------+ +| 0 | ++----------+ +1 row in set (5.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DO SLEEP(5); +``` + +``` +Query OK, 0 rows affected (5.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DO SLEEP(1), SLEEP(1.5); +``` + +``` +Query OK, 0 rows affected (2.50 sec) +``` + +## MySQL 兼容性 + +`DO` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SELECT](/reference/sql/statements/select.md) diff --git a/reference/sql/statements/drop-column.md b/reference/sql/statements/drop-column.md new file mode 100644 index 000000000000..a004bfb2287f --- /dev/null +++ b/reference/sql/statements/drop-column.md @@ -0,0 +1,137 @@ +--- +title: DROP COLUMN +summary: TiDB 数据库中 DROP COLUMN 的使用概况。 +category: reference +--- + +# DROP COLUMN + +`DROP COLUMN` 语句用于从指定的表中删除列。在 TiDB 中，`COLUMN` 为在线操作，不会阻塞表中的数据读写。 + +## 语法图 + +**AlterTableStmt:** + +![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) + +**AlterTableSpec:** + +![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) + +**ColumnKeywordOpt:** + +![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) + +**ColumnName:** + +![ColumnName](/media/sqlgram/ColumnName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, col1 INT NOT NULL, col2 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (col1,col2) VALUES (1,1),(2,2),(3,3),(4,4),(5,5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+------+------+ +| id | col1 | col2 | ++----+------+------+ +| 1 | 1 | 1 | +| 2 | 2 | 2 | +| 3 | 3 | 3 | +| 4 | 4 | 4 | +| 5 | 5 | 5 | ++----+------+------+ +5 rows in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 DROP COLUMN col1, DROP COLUMN col2; +``` + +``` +ERROR 1105 (HY000): can't run multi schema change +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+------+------+ +| id | col1 | col2 | ++----+------+------+ +| 1 | 1 | 1 | +| 2 | 2 | 2 | +| 3 | 3 | 3 | +| 4 | 4 | 4 | +| 5 | 5 | 5 | ++----+------+------+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 DROP COLUMN col1; +``` + +``` +Query OK, 0 rows affected (0.27 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+------+ +| id | col2 | ++----+------+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+------+ +5 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +* 不支持使用相同语句删除多个列。 + +## 另请参阅 + +* [ADD COLUMN](/reference/sql/statements/add-column.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) diff --git a/reference/sql/statements/drop-database.md b/reference/sql/statements/drop-database.md new file mode 100644 index 000000000000..64e1bb2e1dbd --- /dev/null +++ b/reference/sql/statements/drop-database.md @@ -0,0 +1,83 @@ +--- +title: DROP DATABASE +summary: TiDB 数据库中 DROP DATABASE 的使用概况。 +category: reference +--- + +# DROP DATABASE + +`DROP DATABASE` 语句用于永久删除指定的数据库 schema，以及删除所有在 schema 中创建的表和视图。与被删数据库相关联的用户权限不受影响。 + +## 语法图 + +**DropDatabaseStmt:** + +![DropDatabaseStmt](/media/sqlgram/DropDatabaseStmt.png) + +**DatabaseSym:** + +![DatabaseSym](/media/sqlgram/DatabaseSym.png) + +**IfExists:** + +![IfExists](/media/sqlgram/IfExists.png) + +**DBName:** + +![DBName](/media/sqlgram/DBName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW DATABASES; +``` + +``` ++--------------------+ +| Database | ++--------------------+ +| INFORMATION_SCHEMA | +| PERFORMANCE_SCHEMA | +| mysql | +| test | ++--------------------+ +4 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP DATABASE test; +``` + +``` +Query OK, 0 rows affected (0.25 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW DATABASES; +``` + +``` ++--------------------+ +| Database | ++--------------------+ +| INFORMATION_SCHEMA | +| PERFORMANCE_SCHEMA | +| mysql | ++--------------------+ +3 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`DROP DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE DATABASE](/reference/sql/statements/create-database.md) +* [ALTER DATABASE](/reference/sql/statements/alter-database.md) diff --git a/reference/sql/statements/drop-index.md b/reference/sql/statements/drop-index.md new file mode 100644 index 000000000000..1b4b35ce2151 --- /dev/null +++ b/reference/sql/statements/drop-index.md @@ -0,0 +1,114 @@ +--- +title: DROP INDEX +summary: TiDB 数据库中 DROP INDEX 的使用概况。 +category: reference +--- + +# DROP INDEX + +`DROP INDEX` 语句用于从指定的表中删除索引，并在 TiKV 中将空间标记为释放。 + +## 语法图 + +**AlterTableStmt:** + +![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) + +**AlterTableSpec:** + +![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) + +**KeyOrIndex:** + +![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) + +**Identifier:** + +![Identifier](/media/sqlgram/Identifier.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++---------------------+----------+------+-------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+-------------------------------------------------------------+ +| TableReader_7 | 10.00 | root | data:Selection_6 | +| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | +| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+-------------------------------------------------------------+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE INDEX c1 ON t1 (c1); +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE c1 = 3; +``` + +``` ++-------------------+-------+------+-----------------------------------------------------------------+ +| id | count | task | operator info | ++-------------------+-------+------+-----------------------------------------------------------------+ +| IndexReader_6 | 10.00 | root | index:IndexScan_5 | +| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | ++-------------------+-------+------+-----------------------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 DROP INDEX c1; +``` + +``` +Query OK, 0 rows affected (0.30 sec) +``` + +## MySQL 兼容性 + +* 默认不支持删除 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 + +## 另请参阅 + +* [SHOW INDEX](/reference/sql/statements/show-index.md) +* [CREATE INDEX](/reference/sql/statements/create-index.md) +* [ADD INDEX](/reference/sql/statements/add-index.md) +* [RENAME INDEX](/reference/sql/statements/rename-index.md) diff --git a/reference/sql/statements/drop-table.md b/reference/sql/statements/drop-table.md new file mode 100644 index 000000000000..e7378f5d1c22 --- /dev/null +++ b/reference/sql/statements/drop-table.md @@ -0,0 +1,98 @@ +--- +title: DROP TABLE +summary: TiDB 数据库中 DROP TABLE 的使用概况。 +category: reference +--- + +# DROP TABLE + +`DROP TABLE` 语句用于从当前所选的数据库中删除表。如果表不存在则会报错，除非使用 `IF EXISTS` 修饰符。 + +按照设计，`DROP TABLE` 也会删除视图，因为视图与表共享相同的命名空间。 + +## 语法图 + +**DropTableStmt:** + +![DropTableStmt](/media/sqlgram/DropTableStmt.png) + +**TableOrTables:** + +![TableOrTables](/media/sqlgram/TableOrTables.png) + +**TableNameList:** + +![TableNameList](/media/sqlgram/TableNameList.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP TABLE t1; +``` + +``` +Query OK, 0 rows affected (0.22 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP TABLE table_not_exists; +``` + +``` +ERROR 1051 (42S02): Unknown table 'test.table_not_exists' +``` + +{{< copyable "sql" >}} + +```sql +DROP TABLE IF EXISTS table_not_exists; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE VIEW v1 AS SELECT 1; +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP TABLE v1; +``` + +``` +Query OK, 0 rows affected (0.23 sec) +``` + +## MySQL 兼容性 + +* 在尝试删除不存在的表时，使用 `IF EXISTS` 删除表不会返回警告。[Issue #7867](https://github.com/pingcap/tidb/issues/7867) + +## 另请参阅 + +* [DROP VIEW](/reference/sql/statements/drop-view.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [SHOW TABLES](/reference/sql/statements/show-tables.md) diff --git a/reference/sql/statements/drop-user.md b/reference/sql/statements/drop-user.md new file mode 100644 index 000000000000..074e47e5138c --- /dev/null +++ b/reference/sql/statements/drop-user.md @@ -0,0 +1,133 @@ +--- +title: DROP USER +summary: TiDB 数据库中 DROP USER 的使用概况。 +category: reference +--- + +# DROP USER + +`DROP USER` 语句用于从 TiDB 系统数据库中删除用户。如果用户不存在，使用关键词 `IF EXISTS` 可避免出现警告。 + +## 语法图 + +**DropUserStmt:** + +![DropUserStmt](/media/sqlgram/DropUserStmt.png) + +**Username:** + +![Username](/media/sqlgram/Username.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +DROP USER idontexist; +``` + +``` +ERROR 1396 (HY000): Operation DROP USER failed for idontexist@% +``` + +{{< copyable "sql" >}} + +```sql +DROP USER IF EXISTS idontexist; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER newuser IDENTIFIED BY 'mypassword'; +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +GRANT ALL ON test.* TO 'newuser'; +``` + +``` +Query OK, 0 rows affected (0.03 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'newuser'; +``` + +``` ++-------------------------------------------------+ +| Grants for newuser@% | ++-------------------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | +| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | ++-------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +REVOKE ALL ON test.* FROM 'newuser'; +``` + +``` +Query OK, 0 rows affected (0.03 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'newuser'; +``` + +``` ++-------------------------------------+ +| Grants for newuser@% | ++-------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | ++-------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP USER newuser; +``` + +``` +Query OK, 0 rows affected (0.14 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR newuser; +``` + +``` +ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' +``` + +## MySQL 兼容性 + +* 在 TiDB 中删除不存在的用户时，使用 `IF EXISTS` 可避免出现警告。[Issue #10196](https://github.com/pingcap/tidb/issues/10196)。 + +## 另请参阅 + +* [CREATE USER](/reference/sql/statements/create-user.md) +* [ALTER USER](/reference/sql/statements/alter-user.md) +* [SHOW CREATE USER](/reference/sql/statements/show-create-user.md) +* [Privilege Management](/reference/security/privilege-system.md) diff --git a/reference/sql/statements/drop-view.md b/reference/sql/statements/drop-view.md new file mode 100644 index 000000000000..2d4a3da6a2db --- /dev/null +++ b/reference/sql/statements/drop-view.md @@ -0,0 +1,130 @@ +--- +title: DROP VIEW +summary: TiDB 数据库中 DROP VIEW 的使用概况。 +category: reference +--- + +# DROP VIEW + +`DROP VIEW` 语句用于从当前所选定的数据库中删除视图对象。视图所引用的基表不受影响。 + +## 语法图 + +**DropViewStmt:** + +![DropViewStmt](/media/sqlgram/DropViewStmt.png) + +**TableNameList:** + +![TableNameList](/media/sqlgram/TableNameList.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM v1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP VIEW v1; +``` + +``` +Query OK, 0 rows affected (0.23 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +5 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`DROP VIEW` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## See also + +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [CREATE VIEW](/reference/sql/statements/create-view.md) diff --git a/reference/sql/statements/execute.md b/reference/sql/statements/execute.md new file mode 100644 index 000000000000..40f57d00a350 --- /dev/null +++ b/reference/sql/statements/execute.md @@ -0,0 +1,75 @@ +--- +title: EXECUTE +summary: TiDB 数据库中 EXECUTE 的使用概况。 +category: reference +--- + +# EXECUTE + +`EXECUTE` 语句为服务器端预处理语句提供 SQL 接口。 + +## 语法图 + +**ExecuteStmt:** + +![ExecuteStmt](/media/sqlgram/ExecuteStmt.png) + +**Identifier:** + +![Identifier](/media/sqlgram/Identifier.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET @number = 5; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXECUTE mystmt USING @number; +``` + +``` ++------+ +| num | ++------+ +| 5 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DEALLOCATE PREPARE mystmt; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +## MySQL 兼容性 + +`EXECUTE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [PREPARE](/reference/sql/statements/prepare.md) +* [DEALLOCATE](/reference/sql/statements/deallocate.md) diff --git a/reference/sql/statements/explain-analyze.md b/reference/sql/statements/explain-analyze.md new file mode 100644 index 000000000000..c4c84280fb35 --- /dev/null +++ b/reference/sql/statements/explain-analyze.md @@ -0,0 +1,88 @@ +--- +title: EXPLAIN ANALYZE +summary: TiDB 数据库中 EXPLAIN ANALYZE 的使用概况。 +category: reference +--- + +# EXPLAIN ANALYZE + +`EXPLAIN ANALYZE` 语句的工作方式类似于 `EXPLAIN`，主要区别在于前者实际上会执行语句。这样可以将查询计划中的估计值与执行时所遇到的实际值进行比较。如果估计值与实际值显著不同，那么应考虑在受影响的表上运行 `ANALYZE TABLE`。 + +## 语法图 + +**ExplainSym:** + +![ExplainSym](/media/sqlgram/ExplainSym.png) + +**ExplainStmt:** + +![ExplainStmt](/media/sqlgram/ExplainStmt.png) + +**ExplainableStmt:** + +![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1), (2), (3); +``` + +``` +Query OK, 3 rows affected (0.02 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN ANALYZE SELECT * FROM t1 WHERE id = 1; +``` + +``` ++-------------+-------+------+--------------------+---------------------------+ +| id | count | task | operator info | execution info | ++-------------+-------+------+--------------------+---------------------------+ +| Point_Get_1 | 1.00 | root | table:t1, handle:1 | time:0ns, loops:0, rows:0 | ++-------------+-------+------+--------------------+---------------------------+ +1 row in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN ANALYZE SELECT * FROM t1; +``` + +``` ++-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ +| id | count | task | operator info | execution info | ++-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ +| TableReader_5 | 10000.00 | root | data:TableScan_4 | time:931.759µs, loops:2, rows:3 | +| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | time:0s, loops:0, rows:3 | ++-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +该语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +* [Understanding the Query Execution Plan](/reference/performance/understanding-the-query-execution-plan.md) +* [EXPLAIN](/reference/sql/statements/explain.md) +* [ANALYZE TABLE](/reference/sql/statements/analyze-table.md) +* [TRACE](/reference/sql/statements/trace.md) diff --git a/reference/sql/statements/explain.md b/reference/sql/statements/explain.md new file mode 100644 index 000000000000..e5926e18e218 --- /dev/null +++ b/reference/sql/statements/explain.md @@ -0,0 +1,223 @@ +--- +title: EXPLAIN +summary: TiDB 数据库中 EXPLAIN 的使用概况。 +category: reference +--- + +# EXPLAIN + +`EXPLAIN` 语句仅用于显示查询的执行计划，而不执行查询。`EXPLAIN ANALYZE` 可执行查询，补充 `EXPLAIN` 语句。如果 `EXPLAIN` 的输出与预期结果不匹配，可考虑在查询的每个表上执行 `ANALYZE TABLE`。 + +语句 `DESC` 和 `DESCRIBE` 是 `EXPLAIN` 的别名。`EXPLAIN ` 的替代用法记录在 [`SHOW [FULL] COLUMNS FROM`](/reference/sql/statements/show-columns-from.md) 下。 + +## 语法图 + +**ExplainSym:** + +![ExplainSym](/media/sqlgram/ExplainSym.png) + +**ExplainStmt:** + +![ExplainStmt](/media/sqlgram/ExplainStmt.png) + +**ExplainableStmt:** + +![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT 1; +``` + +``` ++-------------------+-------+------+---------------+ +| id | count | task | operator info | ++-------------------+-------+------+---------------+ +| Projection_3 | 1.00 | root | 1 | +| └─TableDual_4 | 1.00 | root | rows:1 | ++-------------------+-------+------+---------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1), (2), (3); +``` + +``` +Query OK, 3 rows affected (0.02 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT * FROM t1 WHERE id = 1; +``` + +``` ++-------------+-------+------+--------------------+ +| id | count | task | operator info | ++-------------+-------+------+--------------------+ +| Point_Get_1 | 1.00 | root | table:t1, handle:1 | ++-------------+-------+------+--------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DESC SELECT * FROM t1 WHERE id = 1; +``` + +``` ++-------------+-------+------+--------------------+ +| id | count | task | operator info | ++-------------+-------+------+--------------------+ +| Point_Get_1 | 1.00 | root | table:t1, handle:1 | ++-------------+-------+------+--------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DESCRIBE SELECT * FROM t1 WHERE id = 1; +``` + +``` ++-------------+-------+------+--------------------+ +| id | count | task | operator info | ++-------------+-------+------+--------------------+ +| Point_Get_1 | 1.00 | root | table:t1, handle:1 | ++-------------+-------+------+--------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN INSERT INTO t1 (c1) VALUES (4); +``` + +``` +ERROR 1105 (HY000): Unsupported type *core.Insert +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN UPDATE t1 SET c1=5 WHERE c1=3; +``` + +``` ++---------------------+----------+------+-------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+-------------------------------------------------------------+ +| TableReader_6 | 10.00 | root | data:Selection_5 | +| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | +| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+-------------------------------------------------------------+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXPLAIN DELETE FROM t1 WHERE c1=3; +``` + +``` ++---------------------+----------+------+-------------------------------------------------------------+ +| id | count | task | operator info | ++---------------------+----------+------+-------------------------------------------------------------+ +| TableReader_6 | 10.00 | root | data:Selection_5 | +| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | +| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | ++---------------------+----------+------+-------------------------------------------------------------+ +3 rows in set (0.00 sec) +``` + +如果未指定 `FORMAT`，或未指定 `FORMAT ="row"`，那么 `EXPLAIN` 语句将以表格格式输出结果。更多信息，可参阅 [Understand the Query Execution Plan](https://pingcap.com/docs/dev/reference/performance/understanding-the-query-execution-plan/)。 + +除 MySQL 标准结果格式外，TiDB 还支持 DotGraph。需按照下列所示指定 `FORMAT ="dot"`： + +{{< copyable "sql" >}} + +```sql +create table t(a bigint, b bigint); +desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10; +``` + +```+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| dot contents | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| +digraph HashRightJoin_7 { +subgraph cluster7{ +node [style=filled, color=lightgrey] +color=black +label = "root" +"HashRightJoin_7" -> "TableReader_10" +"HashRightJoin_7" -> "TableReader_12" +} +subgraph cluster9{ +node [style=filled, color=lightgrey] +color=black +label = "cop" +"Selection_9" -> "TableScan_8" +} +subgraph cluster11{ +node [style=filled, color=lightgrey] +color=black +label = "cop" +"TableScan_11" +} +"TableReader_10" -> "Selection_9" +"TableReader_12" -> "TableScan_11" +} + | ++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +如果你的计算机上安装了 `dot` 程序（在 `graphviz` 包中），可使用以下方法生成 PNG 文件： + +{{< copyable "shell-regular" >}} + +```bash +dot xx.dot -T png -O +``` + +The `xx.dot` is the result returned by the above statement. + +如果你的计算机上未安装 `dot` 程序，可将结果复制到 [本网站](http://www.webgraphviz.com/) 以获取树形图： + +![Explain Dot](/media/explain_dot.png) + +## MySQL 兼容性 + +* `EXPLAIN` 的格式和 TiDB 中潜在的执行计划都与 MySQL 有很大不同。 +* TiDB 不像 MySQL 那样支持 `EXPLAIN FORMAT = JSON`。 +* TiDB 目前不支持插入语句的 `EXPLAIN`。 + +## 另请参阅 + +* [Understanding the Query Execution Plan](/reference/performance/understanding-the-query-execution-plan.md) +* [EXPLAIN ANALYZE](/reference/sql/statements/explain-analyze.md) +* [ANALYZE TABLE](/reference/sql/statements/analyze-table.md) +* [TRACE](/reference/sql/statements/trace.md) diff --git a/reference/sql/statements/flush-privileges.md b/reference/sql/statements/flush-privileges.md new file mode 100644 index 000000000000..4a8d369f5aef --- /dev/null +++ b/reference/sql/statements/flush-privileges.md @@ -0,0 +1,45 @@ +--- +title: FLUSH PRIVILEGES +summary: TiDB 数据库中 FLUSH PRIVILEGES 的使用概况。 +category: reference +--- + +# FLUSH PRIVILEGES + +`FLUSH PRIVILEGES` 语句可触发 TiDB 从权限表中重新加载权限的内存副本。在对如 `mysql.user` 一类的表进行手动编辑后，应当执行 `FLUSH PRIVILEGES`。使用如 `GRANT` 或 `REVOKE` 一类的权限语句后，不需要执行 `FLUSH PRIVILEGES` 语句。 + +## 语法图 + +**FlushStmt:** + +![FlushStmt](/media/sqlgram/FlushStmt.png) + +**NoWriteToBinLogAliasOpt:** + +![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) + +**FlushOption:** + +![FlushOption](/media/sqlgram/FlushOption.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +FLUSH PRIVILEGES; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +## MySQL 兼容性 + +`FLUSH PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [GRANT](/reference/sql/statements/grant-privileges.md) +* [REVOKE ](/reference/sql/statements/revoke-privileges.md) +* [Privilege Management](/reference/security/privilege-system.md) diff --git a/reference/sql/statements/flush-status.md b/reference/sql/statements/flush-status.md new file mode 100644 index 000000000000..1ae3472a1a70 --- /dev/null +++ b/reference/sql/statements/flush-status.md @@ -0,0 +1,103 @@ +--- +title: FLUSH STATUS +summary: TiDB 数据库中 FLUSH STATUS 的使用概况。 +category: reference +--- + +# FLUSH STATUS + +`FLUSH STATUS` 语句用于提供 MySQL 兼容性，但在 TiDB 上并无作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 + +## 语法图 + +**FlushStmt:** + +![FlushStmt](/media/sqlgram/FlushStmt.png) + +**NoWriteToBinLogAliasOpt:** + +![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) + +**FlushOption:** + +![FlushOption](/media/sqlgram/FlushOption.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +show status; +``` + +``` ++--------------------+--------------------------------------+ +| Variable_name | Value | ++--------------------+--------------------------------------+ +| Ssl_cipher_list | | +| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | +| ddl_schema_version | 141 | +| Ssl_verify_mode | 0 | +| Ssl_version | | +| Ssl_cipher | | ++--------------------+--------------------------------------+ +6 rows in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +show global status; +``` + +``` ++--------------------+--------------------------------------+ +| Variable_name | Value | ++--------------------+--------------------------------------+ +| Ssl_cipher | | +| Ssl_cipher_list | | +| Ssl_verify_mode | 0 | +| Ssl_version | | +| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | +| ddl_schema_version | 141 | ++--------------------+--------------------------------------+ +6 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +flush status; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +show status; +``` + +``` ++--------------------+--------------------------------------+ +| Variable_name | Value | ++--------------------+--------------------------------------+ +| Ssl_cipher | | +| Ssl_cipher_list | | +| Ssl_verify_mode | 0 | +| Ssl_version | | +| ddl_schema_version | 141 | +| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | ++--------------------+--------------------------------------+ +6 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +* `FLUSH STATUS` 语句仅用于提供 MySQL 兼容性。 + +## 另请参阅 + +* [SHOW \[GLOBAL|SESSION\] STATUS](/reference/sql/statements/show-status.md) diff --git a/reference/sql/statements/flush-tables.md b/reference/sql/statements/flush-tables.md new file mode 100644 index 000000000000..2e413879c544 --- /dev/null +++ b/reference/sql/statements/flush-tables.md @@ -0,0 +1,66 @@ +--- +title: FLUSH TABLES +summary: TiDB 数据库中 FLUSH TABLES 的使用概况。 +category: reference +--- + +# FLUSH TABLES + +`FLUSH TABLES` 语句用于提供 MySQL 兼容性，但在 TiDB 中并无有效用途。 + +## 语法图 + +**FlushStmt:** + +![FlushStmt](/media/sqlgram/FlushStmt.png) + +**NoWriteToBinLogAliasOpt:** + +![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) + +**FlushOption:** + +![FlushOption](/media/sqlgram/FlushOption.png) + +**TableOrTables:** + +![TableOrTables](/media/sqlgram/TableOrTables.png) + +**TableNameListOpt:** + +![TableNameListOpt](/media/sqlgram/TableNameListOpt.png) + +**WithReadLockOpt:** + +![WithReadLockOpt](/media/sqlgram/WithReadLockOpt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +FLUSH TABLES; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +FLUSH TABLES WITH READ LOCK; +``` + +``` +ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported. Please use @@tidb_snapshot +``` + +## MySQL 兼容性 + +* TiDB 没有 MySQL 中的表缓存这一概念。所以，`FLUSH TABLES` 因 MySQL 兼容性会在 TiDB 中解析出但会被忽略掉。 +* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads] 来实现锁表。 + +## 另请参阅 + +* [Read historical data](/how-to/get-started/read-historical-data.md) diff --git a/reference/sql/statements/grant-privileges.md b/reference/sql/statements/grant-privileges.md new file mode 100644 index 000000000000..df9e988ed4cf --- /dev/null +++ b/reference/sql/statements/grant-privileges.md @@ -0,0 +1,89 @@ +--- +title: GRANT +summary: TiDB 数据库中 GRANT 的使用概况。 +category: reference +--- + +# GRANT + +`GRANT ` 语句用于为 TiDB 中已存在的用户分配权限。TiDB 中的权限系统同 MySQL 一样，都基于数据库/表模式来分配凭据。 + +## 语法图 + +**GrantStmt:** + +![GrantStmt](/media/sqlgram/GrantStmt.png) + +**PrivElemList:** + +![PrivElemList](/media/sqlgram/PrivElemList.png) + +**PrivElem:** + +![PrivElem](/media/sqlgram/PrivElem.png) + +**PrivType:** + +![PrivType](/media/sqlgram/PrivType.png) + +**ObjectType:** + +![ObjectType](/media/sqlgram/ObjectType.png) + +**PrivLevel:** + +![PrivLevel](/media/sqlgram/PrivLevel.png) + +**UserSpecList:** + +![UserSpecList](/media/sqlgram/UserSpecList.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE USER newuser IDENTIFIED BY 'mypassword'; +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +GRANT ALL ON test.* TO 'newuser'; +``` + +``` +Query OK, 0 rows affected (0.03 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'newuser'; +``` + +``` ++-------------------------------------------------+ +| Grants for newuser@% | ++-------------------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | +| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | ++-------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +* 与 MySQL 类似，`USAGE` 权限表示登录 TiDB 服务器的能力。 +* 目前不支持列级权限。 +* 与 MySQL 类似，不存在 `NO_AUTO_CREATE_USER` sql 模式时，`GRANT` 语句将在用户不存在时自动创建一个空密码的新用户。删除此 sql-mode（默认情况下已启用）会带来安全风险。 + +## 另请参阅 + +* [REVOKE ](/reference/sql/statements/revoke-privileges.md) +* [SHOW GRANTS](/reference/sql/statements/show-grants.md) +* [Privilege Management](/reference/security/privilege-system.md) diff --git a/reference/sql/statements/insert.md b/reference/sql/statements/insert.md new file mode 100644 index 000000000000..8ec326e1ebef --- /dev/null +++ b/reference/sql/statements/insert.md @@ -0,0 +1,161 @@ +--- +title: INSERT +summary: TiDB 数据库中 INSERT 的使用概况。 +category: reference +--- + +# INSERT + +使用 `INSERT` 语句在表中插入新行。 + +## 语法图 + +**InsertIntoStmt:** + +![InsertIntoStmt](/media/sqlgram/InsertIntoStmt.png) + +**PriorityOpt:** + +![PriorityOpt](/media/sqlgram/PriorityOpt.png) + +**IgnoreOptional:** + +![IgnoreOptional](/media/sqlgram/IgnoreOptional.png) + +**IntoOpt:** + +![IntoOpt](/media/sqlgram/IntoOpt.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +**InsertValues:** + +![InsertValues](/media/sqlgram/InsertValues.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t2 LIKE t1; +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1); +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (a) VALUES (1); +``` + +``` +Query OK, 1 row affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t2 SELECT * FROM t1; +``` + +``` +Query OK, 2 rows affected (0.01 sec) +Records: 2 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++------+ +| a | ++------+ +| 1 | +| 1 | ++------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t2; +``` + +``` ++------+ +| a | ++------+ +| 1 | +| 1 | ++------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t2 VALUES (2),(3),(4); +``` + +``` +Query OK, 3 rows affected (0.02 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t2; +``` + +``` ++------+ +| a | ++------+ +| 1 | +| 1 | +| 2 | +| 3 | +| 4 | ++------+ +5 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`INSERT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [DELETE](/reference/sql/statements/delete.md) +* [SELECT](/reference/sql/statements/select.md) +* [UPDATE](/reference/sql/statements/update.md) +* [REPLACE](/reference/sql/statements/replace.md) diff --git a/reference/sql/statements/kill.md b/reference/sql/statements/kill.md new file mode 100644 index 000000000000..2abe5bdba7d8 --- /dev/null +++ b/reference/sql/statements/kill.md @@ -0,0 +1,53 @@ +--- +title: KILL [TIDB] +summary: TiDB 数据库中 KILL [TIDB] 的使用概况。 +category: reference +--- + +# KILL [TIDB] + +`KILL TIDB` 语句用于终止 TiDB 中的连接。 + +按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。 + +## 语法图 + +**KillStmt:** + +![KillStmt](/media/sqlgram/KillStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW PROCESSLIST; +``` + +``` ++------+------+-----------+------+---------+------+-------+------------------+ +| Id | User | Host | db | Command | Time | State | Info | ++------+------+-----------+------+---------+------+-------+------------------+ +| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | +| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | ++------+------+-----------+------+---------+------+-------+------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +KILL TIDB 2; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +## MySQL 兼容性 + +* `KILL TIDB` 语句是 TiDB 的扩展语法。如果正尝试终止的会话位于同一个 TiDB 服务器上，可在配置文件里设置 [`compatible-kill-query = true`](/reference/configuration/tidb-server/configuration-file.md#compatible-kill-query)。 + +## 另请参阅 + +* [SHOW \[FULL\] PROCESSLIST](/reference/sql/statements/show-processlist.md) diff --git a/reference/sql/statements/load-data.md b/reference/sql/statements/load-data.md new file mode 100644 index 000000000000..85d4517a3339 --- /dev/null +++ b/reference/sql/statements/load-data.md @@ -0,0 +1,72 @@ +--- +title: LOAD DATA +summary: TiDB 数据库中 LOAD DATA 的使用概况。 +category: reference +--- + +# LOAD DATA + +`LOAD DATA` 语句用于将数据批量加载到 TiDB 表中。 + +## 语法图 + +**LoadDataStmt:** + +![LoadDataStmt](/media/sqlgram/LoadDataStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE trips ( + -> trip_id bigint NOT NULL PRIMARY KEY AUTO_INCREMENT, + -> duration integer not null, + -> start_date datetime, + -> end_date datetime, + -> start_station_number integer, + -> start_station varchar(255), + -> end_station_number integer, + -> end_station varchar(255), + -> bike_number varchar(255), + -> member_type varchar(255) + -> ); +``` + +``` +Query OK, 0 rows affected (0.14 sec) +``` + +{{< copyable "sql" >}} + +```sql +LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); +``` + +``` +Query OK, 815264 rows affected (39.63 sec) +Records: 815264 Deleted: 0 Skipped: 0 Warnings: 0 +``` + +`LOAD DATA` 也支持使用十六进制 ASCII 字符表达式或二进制 ASCII 字符表达式作为 `FIELDS ENCLOSED BY` 和 `FIELDS TERMINATED BY` 的参数。示例如下： + +{{< copyable "sql" >}} + +```sql +LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY x'2c' ENCLOSED BY b'100010' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); +``` + +以上示例中 `x'2c'` 是字符 `,` 的十六进制表示，`b'100010'` 是字符 `"` 的二进制表示。 + +## MySQL 兼容性 + +* 默认情况下，TiDB 每 20,000 行会进行一次提交。这类似于 MySQL NDB Cluster，但并非 InnoDB 存储引擎的默认配置。 + +> **注意：** +> +> 这种拆分事务提交的方式是以打破事务的原子性和隔离性为代价的，使用该特性时，使用者需要保证没有其他对正在处理的表的**任何**操作，并且在出现报错时，需要及时**人工介入，检查数据的一致性和完整性**。因此，不建议在生产环境中使用。 + +## 另请参阅 + +* [INSERT](/reference/sql/statements/insert.md) +* [乐观事务模型](/reference/transactions/transaction-optimistic.md) diff --git a/reference/sql/statements/modify-column.md b/reference/sql/statements/modify-column.md new file mode 100644 index 000000000000..085ba43f89bf --- /dev/null +++ b/reference/sql/statements/modify-column.md @@ -0,0 +1,125 @@ +--- +title: MODIFY COLUMN +summary: TiDB 数据库中 MODIFY COLUMN 的使用概况。 +category: reference +--- + +# MODIFY COLUMN + +`ALTER TABLE .. MODIFY COLUMN` 语句用于修改已有表上的列，包括列的数据类型和属性。若要同时重命名，可改用 [`CHANGE COLUMN`](/reference/sql/statements/change-column.md) 语句。 + +## 语法图 + +**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) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 MODIFY col1 BIGINT; +``` + +``` +Query OK, 0 rows affected (0.09 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +``` +*************************** 1. row *************************** + Table: t1 +Create Table: CREATE TABLE `t1` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `col1` bigint(20) DEFAULT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=30001 +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 MODIFY col1 INT; +``` + +``` +ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 MODIFY col1 BLOB; +``` + +``` +ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 MODIFY col1 BIGINT, MODIFY id BIGINT NOT NULL; +``` + +``` +ERROR 1105 (HY000): can't run multi schema change +``` + +## MySQL 兼容性 + +* 目前不支持使用单个 `ALTER TABLE` 语句进行多个修改。 +* 仅支持特定类型的数据类型更改。例如，支持将 `INTEGER` 改为 `BIGINT`，但不支持将 `BIGINT` 改为 `INTEGER`。不支持将整数改为字符串格式或 BLOB 格式。 +* 不支持修改 decimal 类型的精度。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [ADD COLUMN](/reference/sql/statements/add-column.md) +* [DROP COLUMN](/reference/sql/statements/drop-column.md) +* [CHANGE COLUMN](/reference/sql/statements/change-column.md) diff --git a/reference/sql/statements/prepare.md b/reference/sql/statements/prepare.md new file mode 100644 index 000000000000..7dd48d99b0a4 --- /dev/null +++ b/reference/sql/statements/prepare.md @@ -0,0 +1,71 @@ +--- +title: PREPARE +summary: TiDB 数据库中 PREPARE 的使用概况。 +category: reference +--- + +# PREPARE + +`PREPARE` 语句为服务器端预处理语句提供 SQL 接口。 + +## 语法图 + +**PreparedStmt:** + +![PreparedStmt](/media/sqlgram/PreparedStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET @number = 5; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +EXECUTE mystmt USING @number; +``` + +``` ++------+ +| num | ++------+ +| 5 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DEALLOCATE PREPARE mystmt; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +## MySQL 兼容性 + +`PREPARE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [EXECUTE](/reference/sql/statements/execute.md) +* [DEALLOCATE](/reference/sql/statements/deallocate.md) diff --git a/reference/sql/statements/recover-table.md b/reference/sql/statements/recover-table.md new file mode 100644 index 000000000000..af2b60e5326d --- /dev/null +++ b/reference/sql/statements/recover-table.md @@ -0,0 +1,109 @@ +--- +title: RECOVER TABLE +category: reference +--- + +# RECOVER TABLE + +`RECOVER TABLE` 的功能是恢复被删除的表及其数据。在 `DROP TABLE` 后，在 GC life time 时间内，可以用 `RECOVER TABLE` 语句恢复被删除的表以及其数据。 + +## 语法 + +{{< copyable "sql" >}} + +```sql +RECOVER TABLE table_name +``` + +{{< copyable "sql" >}} + +```sql +RECOVER TABLE BY JOB ddl_job_id +``` + +## 注意事项 + +如果删除表后并过了 GC lifetime，就不能再用 `RECOVER TABLE` 来恢复被删除的表了，执行 `RECOVER TABLE` 语句会返回类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 + +对于 3.0.0 及之后的 TiDB 版本，不推荐在使用 TiDB Binlog 的情况下使用 `RECOVER TABLE` 功能。 + +TiDB Binlog 在 3.0.1 支持 `RECOVER TABLE` 后，可在下面的情况下使用 `RECOVER TABLE`： + +* 3.0.1+ 版本的 TiDB Binlog +* 主从集群都使用 TiDB 3.0 +* 从集群 GC lifetime 一定要长于主集群（不过由于上下游同步的延迟，可能也会造成下游 recover 失败） + +### TiDB Binlog 同步错误处理 + +当使用 TiDB Binlog 同步工具时，上游 TiDB 使用 `RECOVER TABLE` 后，TiDB Binlog 可能会因为下面几个原因造成同步中断： + +* 下游数据库不支持 `RECOVER TABLE` 语句。类似错误：`check the manual that corresponds to your MySQL server version for the right syntax to use near 'RECOVER TABLE table_name'`。 + +* 上下游数据库的 GC lifetime 不一样。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 + +* 上下游数据库的同步延迟。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 + +只能通过重新[全量导入被删除的表](/reference/tools/user-guide.md#tidb-集群数据的全量备份及恢复-1)来恢复 TiDB Binlog 的数据同步。 + +## 示例 + +- 根据表名恢复被删除的表。 + + {{< copyable "sql" >}} + + ```sql + DROP TABLE t; + ``` + + {{< copyable "sql" >}} + + ```sql + RECOVER TABLE t; + ``` + + 根据表名恢复被删除的表需满足以下条件： + + - 最近 DDL JOB 历史中找到的第一个 `DROP TABLE` 操作，且 + - `DROP TABLE` 所删除的表的名称与 `RECOVER TABLE` 语句指定表名相同 + +- 根据删除表时的 DDL JOB ID 恢复被删除的表。 + + 如果第一次删除表 t 后，又新建了一个表 t，然后又把新建的表 t 删除了，此时如果想恢复最开始删除的表 t, 就需要用到指定 DDL JOB ID 的语法了。 + + {{< copyable "sql" >}} + + ```sql + DROP TABLE t; + ``` + + {{< copyable "sql" >}} + + ```sql + ADMIN SHOW DDL JOBS 1; + ``` + + 上面这个语句用来查找删除表 t 时的 DDL JOB ID，这里是 53： + + ``` + +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ + | JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | + +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ + | 53 | test | | drop table | none | 1 | 41 | 0 | 2019-07-10 13:23:18.277 +0800 CST | synced | + +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ + ``` + + {{< copyable "sql" >}} + + ```sql + RECOVER TABLE BY JOB 53; + ``` + + 根据删除表时的 DDL JOB ID 恢复被删除的表，会直接用 DDL JOB ID 找到被删除表进行恢复。如果指定的 DDL JOB ID 的 DDL JOB 不是 `DROP TABLE` 类型，会报错。 + +## 原理 + +TiDB 在删除表时，实际上只删除了表的元信息，并将需要删除的表数据（行数据和索引数据）写一条数据到 `mysql.gc_delete_range` 表。TiDB 后台的 GC Worker 会定期从 `mysql.gc_delete_range` 表中取出超过 GC lifetime 相关范围的 key 进行删除。 + +所以，RECOVER TABLE 只需要在 GC Worker 还没删除表数据前，恢复表的元信息并删除 `mysql.gc_delete_range` 表中相应的行记录就可以了。恢复表的元信息可以用 TiDB 的快照读实现。具体的快照读内容可以参考[读取历史数据](/how-to/get-started/read-historical-data.md)文档。 + +TiDB 中表的恢复是通过快照读获取表的元信息后，再走一次类似于 `CREATE TABLE` 的建表流程，所以 `RECOVER TABLE` 实际上也是一种 DDL。 diff --git a/reference/sql/statements/rename-index.md b/reference/sql/statements/rename-index.md new file mode 100644 index 000000000000..da02d789ef11 --- /dev/null +++ b/reference/sql/statements/rename-index.md @@ -0,0 +1,88 @@ +--- +title: RENAME INDEX +summary: TiDB 数据库中 RENAME INDEX 的使用概况。 +category: reference +--- + +# RENAME INDEX + +`ALTER TABLE .. RENAME INDEX` 语句用于对已有索引进行重命名。这在 TiDB 中是即时操作的，仅需更改元数据。 + +## 语法图 + +**AlterTableStmt:** + +![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) + +**KeyOrIndex:** + +![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL, INDEX col1 (c1)); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +``` +*************************** 1. row *************************** + Table: t1 +Create Table: CREATE TABLE `t1` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `c1` int(11) NOT NULL, + PRIMARY KEY (`id`), + KEY `col1` (`c1`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 RENAME INDEX col1 TO c1; +``` + +``` +Query OK, 0 rows affected (0.09 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +``` +*************************** 1. row *************************** + Table: t1 +Create Table: CREATE TABLE `t1` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `c1` int(11) NOT NULL, + PRIMARY KEY (`id`), + KEY `c1` (`c1`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`RENAME INDEX` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [CREATE INDEX](/reference/sql/statements/create-index.md) +* [DROP INDEX](/reference/sql/statements/drop-index.md) +* [SHOW INDEX](/reference/sql/statements/show-index.md) diff --git a/reference/sql/statements/rename-table.md b/reference/sql/statements/rename-table.md new file mode 100644 index 000000000000..551cabd058da --- /dev/null +++ b/reference/sql/statements/rename-table.md @@ -0,0 +1,81 @@ +--- +title: RENAME TABLE +summary: TiDB 数据库中 RENAME TABLE 的使用概况。 +category: reference +--- + +# RENAME TABLE + +`RENAME TABLE` 语句用于对已有表进行重命名。 + +## 语法图 + +**RenameTableStmt:** + +![RenameTableStmt](/media/sqlgram/RenameTableStmt.png) + +**TableToTable:** + +![TableToTable](/media/sqlgram/TableToTable.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES; +``` + +``` ++----------------+ +| Tables_in_test | ++----------------+ +| t1 | ++----------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +RENAME TABLE t1 TO t2; +``` + +``` +Query OK, 0 rows affected (0.08 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES; +``` + +``` ++----------------+ +| Tables_in_test | ++----------------+ +| t2 | ++----------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`RENAME TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW TABLES](/reference/sql/statements/show-tables.md) +* [ALTER TABLE](/reference/sql/statements/alter-table.md) diff --git a/reference/sql/statements/replace.md b/reference/sql/statements/replace.md new file mode 100644 index 000000000000..2d707eb581f5 --- /dev/null +++ b/reference/sql/statements/replace.md @@ -0,0 +1,109 @@ +--- +title: REPLACE +summary: TiDB 数据库中 REPLACE 的使用概况。 +category: reference +--- + +# REPLACE + +从语义上看，`REPLACE` 语句是 `DELETE` 语句和 `INSERT` 语句的结合，可用于简化应用程序代码。 + +## 语法图 + +**ReplaceIntoStmt:** + +![ReplaceIntoStmt](/media/sqlgram/ReplaceIntoStmt.png) + +**PriorityOpt:** + +![PriorityOpt](/media/sqlgram/PriorityOpt.png) + +**IntoOpt:** + +![IntoOpt](/media/sqlgram/IntoOpt.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +**InsertValues:** + +![InsertValues](/media/sqlgram/InsertValues.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1), (2), (3); +``` + +``` +Query OK, 3 rows affected (0.02 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | ++----+----+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +REPLACE INTO t1 (id, c1) VALUES(3, 99); +``` + +``` +Query OK, 2 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 99 | ++----+----+ +3 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`REPLACE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [DELETE](/reference/sql/statements/delete.md) +* [INSERT](/reference/sql/statements/insert.md) +* [SELECT](/reference/sql/statements/select.md) +* [UPDATE](/reference/sql/statements/update.md) diff --git a/reference/sql/statements/revoke-privileges.md b/reference/sql/statements/revoke-privileges.md new file mode 100644 index 000000000000..b7e54cb4ca15 --- /dev/null +++ b/reference/sql/statements/revoke-privileges.md @@ -0,0 +1,132 @@ +--- +title: REVOKE +summary: TiDB 数据库中 REVOKE 的使用概况。 +category: reference +--- + +# REVOKE + +`REVOKE ` 语句用于删除已有用户的权限。 + +## 语法图 + +**GrantStmt:** + +![GrantStmt](/media/sqlgram/GrantStmt.png) + +**PrivElemList:** + +![PrivElemList](/media/sqlgram/PrivElemList.png) + +**PrivElem:** + +![PrivElem](/media/sqlgram/PrivElem.png) + +**PrivType:** + +![PrivType](/media/sqlgram/PrivType.png) + +**ObjectType:** + +![ObjectType](/media/sqlgram/ObjectType.png) + +**PrivLevel:** + +![PrivLevel](/media/sqlgram/PrivLevel.png) + +**UserSpecList:** + +![UserSpecList](/media/sqlgram/UserSpecList.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE USER newuser IDENTIFIED BY 'mypassword'; +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +GRANT ALL ON test.* TO 'newuser'; +``` + +``` +Query OK, 0 rows affected (0.03 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'newuser'; +``` + +``` ++-------------------------------------------------+ +| Grants for newuser@% | ++-------------------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | +| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | ++-------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +REVOKE ALL ON test.* FROM 'newuser'; +``` + +``` +Query OK, 0 rows affected (0.03 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'newuser'; +``` + +``` ++-------------------------------------+ +| Grants for newuser@% | ++-------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | ++-------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +DROP USER newuser; +``` + +``` +Query OK, 0 rows affected (0.14 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR newuser; +``` + +``` +ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' +``` + +## MySQL 兼容性 + +`REVOKE ` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [GRANT ](/reference/sql/statements/grant-privileges.md) +* [SHOW GRANTS](/reference/sql/statements/show-grants.md) +* [Privilege Management](/reference/security/privilege-system.md) diff --git a/reference/sql/statements/rollback.md b/reference/sql/statements/rollback.md new file mode 100644 index 000000000000..15bdad87872f --- /dev/null +++ b/reference/sql/statements/rollback.md @@ -0,0 +1,77 @@ +--- +title: ROLLBACK +summary: TiDB 数据库中 ROLLBACK 的使用概况。 +category: reference +--- + +# ROLLBACK + +`ROLLBACK` 语句用于还原 TiDB 内当前事务中的所有更改，作用与 `COMMIT` 语句相反。 + +## 语法图 + +**Statement:** + +![Statement](/media/sqlgram/Statement.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +BEGIN; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1); +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +ROLLBACK; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` +Empty set (0.01 sec) +``` + +## MySQL 兼容性 + +`ROLLBACK` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [COMMIT](/reference/sql/statements/commit.md) +* [BEGIN](/reference/sql/statements/begin.md) +* [START TRANSACTION](/reference/sql/statements/start-transaction.md) diff --git a/reference/sql/statements/select.md b/reference/sql/statements/select.md new file mode 100644 index 000000000000..918208df023b --- /dev/null +++ b/reference/sql/statements/select.md @@ -0,0 +1,131 @@ +--- +title: SELECT +summary: TiDB 数据库中 SELECT 的使用概况。 +category: reference +--- + +# SELECT + +`SELECT` 语句用于从 TiDB 读取数据。 + +## 语法图 + +**SelectStmt:** + +![SelectStmt](/media/sqlgram/SelectStmt.png) + +**FromDual:** + +![FromDual](/media/sqlgram/FromDual.png) + +**WhereClauseOptional:** + +![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) + +**SelectStmtOpts:** + +![SelectStmtOpts](/media/sqlgram/SelectStmtOpts.png) + +**SelectStmtFieldList:** + +![SelectStmtFieldList](/media/sqlgram/SelectStmtFieldList.png) + +**TableRefsClause:** + +![TableRefsClause](/media/sqlgram/TableRefsClause.png) + +**WhereClauseOptional:** + +![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) + +**SelectStmtGroup:** + +![SelectStmtGroup](/media/sqlgram/SelectStmtGroup.png) + +**HavingClause:** + +![HavingClause](/media/sqlgram/HavingClause.png) + +**OrderByOptional:** + +![OrderByOptional](/media/sqlgram/OrderByOptional.png) + +**SelectStmtLimit:** + +![SelectStmtLimit](/media/sqlgram/SelectStmtLimit.png) + +**SelectLockOpt:** + +![SelectLockOpt](/media/sqlgram/SelectLockOpt.png) + +## 语法元素说明 + +|语法元素 | 说明 | +| --------------------- | -------------------------------------------------- | +|`ALL`、`DISTINCT`、`DISTINCTROW` | 查询结果集中可能会包含重复值。指定 DISTINCT/DISTINCTROW 则在查询结果中过滤掉重复的行；指定 ALL 则列出所有的行。默认为 ALL。| +|`HIGH_PRIORITY` | 该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句| +|`SQL_CALC_FOUND_ROWS` | TiDB 出于兼容性解析这个语法，但是不做任何处理| +|`SQL_CACHE`、`SQL_NO_CACHE` | 是否把请求结果缓存到 TiKV (RocksDB) 的 `BlockCache` 中。对于一次性的大数据量的查询，比如 `count(*)` 查询，为了避免冲掉 `BlockCache` 中用户的热点数据，建议填上 `SQL_NO_CACHE` | +|`STRAIGHT_JOIN`|`STRAIGHT_JOIN` 会强制优化器按照 `FROM` 子句中所使用的表的顺序做联合查询。当优化器选择的 Join 顺序并不优秀时，你可以使用这个语法来加速查询的执行| +|`select_expr` | 投影操作列表，一般包括列名、表达式，或者是用 '\*' 表示全部列| +|`FROM table_references` | 表示数据来源，数据来源可以是一个表（`select * from t;`）或者是多个表 (`select * from t1 join t2;`) 或者是0个表 (`select 1+1 from dual;`, 等价于 `select 1+1;`)| +|`WHERE where_condition` | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据| +|`GROUP BY` | GroupBy 子句用于对查询结果集进行分组| +|`HAVING where_condition` | Having 子句与 Where 子句作用类似，Having 子句可以让过滤 GroupBy 后的各种数据，Where 子句用于在聚合前过滤记录。| +|`ORDER BY` | OrderBy 子句用于指定结果排序顺序，可以按照列、表达式或者是 `select_expr` 列表中某个位置的字段进行排序。| +|`LIMIT` | Limit 子句用于限制结果条数。Limit 接受一个或两个数字参数，如果只有一个参数，那么表示返回数据的最大行数；如果是两个参数，那么第一个参数表示返回数据的第一行的偏移量（第一行数据的偏移量是 0），第二个参数指定返回数据的最大条目数。| +|`FOR UPDATE` | 对查询结果集所有行上锁（对于在查询条件内，但是不在结果集的行，将不会加锁，如事务启动后由其他事务写入的行），以监测其他事务对这些的并发修改。使用[乐观事务模型](/reference/transactions/transaction-optimistic.md)时，语句执行期间不会检测锁，因此，不会像 PostgreSQL 之类的数据库一样，在当前事务结束前阻止其他事务执行 `UPDATE`、`DELETE` 和 `SELECT FOR UPDATE`。在事务的提交阶段 `SELECT FOR UPDATE` 读到的行，也会进行两阶段提交，因此，它们也可以参与事务冲突检测。如发生写入冲突，那么包含 `SELECT FOR UPDATE` 语句的事务会提交失败。如果没有冲突，事务将成功提交，当提交结束时，这些被加锁的行，会产生一个新版本，可以让其他尚未提交的事务，在将来提交时发现写入冲突。若使用悲观事务，则行为与其他数据库基本相同，不一致之处参考[和 MySQL InnoDB 的差异](/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)。 | +|`LOCK IN SHARE MODE` | TiDB 出于兼容性解析这个语法，但是不做任何处理| + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.03 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+----+ +5 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SELECT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [INSERT](/reference/sql/statements/insert.md) +* [DELETE](/reference/sql/statements/delete.md) +* [UPDATE](/reference/sql/statements/update.md) +* [REPLACE](/reference/sql/statements/replace.md) diff --git a/reference/sql/statements/set-names.md b/reference/sql/statements/set-names.md new file mode 100644 index 000000000000..227f25d22990 --- /dev/null +++ b/reference/sql/statements/set-names.md @@ -0,0 +1,113 @@ +--- +title: SET [NAMES|CHARACTER SET] +summary: TiDB 数据库中 SET [NAMES|CHARACTER SET] 的使用概况。 +category: reference +--- + +# SET [NAMES|CHARACTER SET] + +`SET NAMES`，`SET CHARACTER SET` 和 `SET CHARSET` 语句用于修改当前连接的变量 `character_set_client`，`character_set_results` 和 `character_set_connection`。 + +## 语法图 + +**SetStmt:** + +![SetStmt](/media/sqlgram/SetStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW VARIABLES LIKE 'character_set%'; +``` + +``` ++--------------------------+--------------------------------------------------------+ +| Variable_name | Value | ++--------------------------+--------------------------------------------------------+ +| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | +| character_set_connection | utf8mb4 | +| character_set_system | utf8 | +| character_set_results | utf8mb4 | +| character_set_client | utf8mb4 | +| character_set_database | utf8mb4 | +| character_set_filesystem | binary | +| character_set_server | utf8mb4 | ++--------------------------+--------------------------------------------------------+ +8 rows in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET NAMES utf8; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW VARIABLES LIKE 'character_set%'; +``` + +``` ++--------------------------+--------------------------------------------------------+ +| Variable_name | Value | ++--------------------------+--------------------------------------------------------+ +| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | +| character_set_connection | utf8 | +| character_set_system | utf8 | +| character_set_results | utf8 | +| character_set_client | utf8 | +| character_set_server | utf8mb4 | +| character_set_database | utf8mb4 | +| character_set_filesystem | binary | ++--------------------------+--------------------------------------------------------+ +8 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET CHARACTER SET utf8mb4; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW VARIABLES LIKE 'character_set%'; +``` + +``` ++--------------------------+--------------------------------------------------------+ +| Variable_name | Value | ++--------------------------+--------------------------------------------------------+ +| character_set_connection | utf8mb4 | +| character_set_system | utf8 | +| character_set_results | utf8mb4 | +| character_set_client | utf8mb4 | +| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | +| character_set_database | utf8mb4 | +| character_set_filesystem | binary | +| character_set_server | utf8mb4 | ++--------------------------+--------------------------------------------------------+ +8 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SET [NAMES|CHARACTER SET]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW \[GLOBAL|SESSION\] VARIABLES](/reference/sql/statements/show-variables.md) +* [SET ](/reference/sql/statements/set-variable.md) +* [Character Set Support](/reference/sql/character-set.md) diff --git a/reference/sql/statements/set-password.md b/reference/sql/statements/set-password.md new file mode 100644 index 000000000000..2cddc02f96a5 --- /dev/null +++ b/reference/sql/statements/set-password.md @@ -0,0 +1,110 @@ +--- +title: SET PASSWORD +summary: TiDB 数据库中 SET PASSWORD 的使用概况。 +category: reference +--- + +# SET PASSWORD + +`SET PASSWORD` 语句用于更改 TiDB 系统数据库中的用户密码。 + +## 语法图 + +**SetStmt:** + +![SetStmt](/media/sqlgram/SetStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SET PASSWORD='test'; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER 'newuser' IDENTIFIED BY 'test'; +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE USER newuser; +``` + +```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER for newuser@% | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET PASSWORD FOR newuser = 'test'; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE USER newuser; +``` + +```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER for newuser@% | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET PASSWORD FOR newuser = PASSWORD('test'); +``` + +上述语法是早期 MySQL 版本的过时语法。 + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE USER newuser; +``` + +```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER for newuser@% | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SET PASSWORD` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE USER](/reference/sql/statements/create-user.md) +* [Privilege Management](/reference/security/privilege-system.md) diff --git a/reference/sql/statements/set-transaction.md b/reference/sql/statements/set-transaction.md new file mode 100644 index 000000000000..8e701697a12c --- /dev/null +++ b/reference/sql/statements/set-transaction.md @@ -0,0 +1,101 @@ +--- +title: SET TRANSACTION +summary: TiDB 数据库中 SET TRANSACTION 的使用概况。 +category: reference +--- + +# SET TRANSACTION + +`SET TRANSACTION` 语句用于在 `GLOBAL` 或 `SESSION` 的基础上更改当前的隔离级别，是 `SET transaction_isolation ='new-value'` 的替代语句，提供 MySQL 和 SQL 标准的兼容性。 + +## 语法图 + +**SetStmt:** + +![SetStmt](/media/sqlgram/SetStmt.png) + +**TransactionChar:** + +![TransactionChar](/media/sqlgram/TransactionChar.png) + +**IsolationLevel:** + +![IsolationLevel](/media/sqlgram/IsolationLevel.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW SESSION VARIABLES like 'transaction_isolation'; +``` + +``` ++-----------------------+-----------------+ +| Variable_name | Value | ++-----------------------+-----------------+ +| transaction_isolation | REPEATABLE-READ | ++-----------------------+-----------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW SESSION VARIABLES like 'transaction_isolation'; +``` + +``` ++-----------------------+----------------+ +| Variable_name | Value | ++-----------------------+----------------+ +| transaction_isolation | READ-COMMITTED | ++-----------------------+----------------+ +1 row in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET SESSION transaction_isolation = 'REPEATABLE-READ'; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW SESSION VARIABLES like 'transaction_isolation'; +``` + +``` ++-----------------------+-----------------+ +| Variable_name | Value | ++-----------------------+-----------------+ +| transaction_isolation | REPEATABLE-READ | ++-----------------------+-----------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +* TiDB 支持仅在语法中将事务设置为只读的功能。 +* 不支持隔离级别 `READ-UNCOMMITTED` 和 `SERIALIZABLE`。 +* 隔离级别 `REPEATABLE-READ` 在技术上属于快照隔离（Snapshot Isolation）。在 TiDB 中称为 `REPEATABLE-READ` 是为了和 MySQL 保持一致。 + +## 另请参阅 + +* [SET \[GLOBAL|SESSION\] ](/reference/sql/statements/set-variable.md) +* [Isolation Levels](/reference/transactions/transaction-isolation.md) diff --git a/reference/sql/statements/set-variable.md b/reference/sql/statements/set-variable.md new file mode 100644 index 000000000000..159ed2ced2ac --- /dev/null +++ b/reference/sql/statements/set-variable.md @@ -0,0 +1,120 @@ +--- +title: SET [GLOBAL|SESSION] +summary: TiDB 数据库中 SET [GLOBAL|SESSION] 的使用概况。 +category: reference +--- + +# SET [GLOBAL|SESSION] + +`SET [GLOBAL|SESSION]` 语句用于在 `SESSION` 或 `GLOBAL` 的范围内，对某个 TiDB 的内置变量进行更改。需注意，对 `GLOBAL` 变量的更改不适用于已有连接或本地连接，这与 MySQL 类似。只有新会话才会反映值的变化。 + +## 语法图 + +**SetStmt:** + +![SetStmt](/media/sqlgram/SetStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW GLOBAL VARIABLES LIKE 'sql_mode'; +``` + +``` ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Variable_name | Value | ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW SESSION VARIABLES LIKE 'sql_mode'; +``` + +``` ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Variable_name | Value | ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; +``` + +``` +Query OK, 0 rows affected (0.03 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GLOBAL VARIABLES LIKE 'sql_mode'; +``` + +``` ++---------------+-----------------------------------------+ +| Variable_name | Value | ++---------------+-----------------------------------------+ +| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | ++---------------+-----------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW SESSION VARIABLES LIKE 'sql_mode'; +``` + +``` ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Variable_name | Value | ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | ++---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW SESSION VARIABLES LIKE 'sql_mode'; +``` + +``` ++---------------+-----------------------------------------+ +| Variable_name | Value | ++---------------+-----------------------------------------+ +| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | ++---------------+-----------------------------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SET [GLOBAL|SESSION]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW \[GLOBAL|SESSION\] VARIABLES](/reference/sql/statements/show-variables.md) diff --git a/reference/sql/statements/show-character-set.md b/reference/sql/statements/show-character-set.md new file mode 100644 index 000000000000..d9eb74acc69f --- /dev/null +++ b/reference/sql/statements/show-character-set.md @@ -0,0 +1,52 @@ +--- +title: SHOW CHARACTER SET +summary: TiDB 数据库中 SHOW CHARACTER SET 的使用概况。 +category: reference +--- + +# SHOW CHARACTER SET + +`SHOW CHARACTER SET` 语句提供 TiDB 中可用字符集的静态列表。此列表不反映当前连接或用户的任何属性。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**CharsetKw:** + +![CharsetKw](/media/sqlgram/CharsetKw.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW CHARACTER SET; +``` + +``` ++---------+---------------+-------------------+--------+ +| Charset | Description | Default collation | Maxlen | ++---------+---------------+-------------------+--------+ +| utf8 | UTF-8 Unicode | utf8_bin | 3 | +| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | +| ascii | US ASCII | ascii_bin | 1 | +| latin1 | Latin1 | latin1_bin | 1 | +| binary | binary | binary | 1 | ++---------+---------------+-------------------+--------+ +5 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW CHARACTER SET` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW COLLATION](/reference/sql/statements/show-collation.md) diff --git a/reference/sql/statements/show-collation.md b/reference/sql/statements/show-collation.md new file mode 100644 index 000000000000..59c93f2ab0e2 --- /dev/null +++ b/reference/sql/statements/show-collation.md @@ -0,0 +1,264 @@ +--- +title: SHOW COLLATION +summary: TiDB 数据库中 SHOW COLLATION 的使用概况。 +category: reference +--- + +# SHOW COLLATION + +`SHOW COLLATION` 语句用于提供一个静态的排序规则列表，确保与 MySQL 客户端库的兼容性。 + +> **注意:** TiDB 目前仅支持二进制排序规则。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW COLLATION; +``` + +``` ++--------------------------+----------+------+---------+----------+---------+ +| Collation | Charset | Id | Default | Compiled | Sortlen | ++--------------------------+----------+------+---------+----------+---------+ +| big5_chinese_ci | big5 | 1 | Yes | Yes | 1 | +| latin2_czech_cs | latin2 | 2 | | Yes | 1 | +| dec8_swedish_ci | dec8 | 3 | Yes | Yes | 1 | +| cp850_general_ci | cp850 | 4 | Yes | Yes | 1 | +| latin1_german1_ci | latin1 | 5 | | Yes | 1 | +| hp8_english_ci | hp8 | 6 | Yes | Yes | 1 | +| koi8r_general_ci | koi8r | 7 | Yes | Yes | 1 | +| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | +| latin2_general_ci | latin2 | 9 | Yes | Yes | 1 | +| swe7_swedish_ci | swe7 | 10 | Yes | Yes | 1 | +| ascii_general_ci | ascii | 11 | Yes | Yes | 1 | +| ujis_japanese_ci | ujis | 12 | Yes | Yes | 1 | +| sjis_japanese_ci | sjis | 13 | Yes | Yes | 1 | +| cp1251_bulgarian_ci | cp1251 | 14 | | Yes | 1 | +| latin1_danish_ci | latin1 | 15 | | Yes | 1 | +| hebrew_general_ci | hebrew | 16 | Yes | Yes | 1 | +| tis620_thai_ci | tis620 | 18 | Yes | Yes | 1 | +| euckr_korean_ci | euckr | 19 | Yes | Yes | 1 | +| latin7_estonian_cs | latin7 | 20 | | Yes | 1 | +| latin2_hungarian_ci | latin2 | 21 | | Yes | 1 | +| koi8u_general_ci | koi8u | 22 | Yes | Yes | 1 | +| cp1251_ukrainian_ci | cp1251 | 23 | | Yes | 1 | +| gb2312_chinese_ci | gb2312 | 24 | Yes | Yes | 1 | +| greek_general_ci | greek | 25 | Yes | Yes | 1 | +| cp1250_general_ci | cp1250 | 26 | Yes | Yes | 1 | +| latin2_croatian_ci | latin2 | 27 | | Yes | 1 | +| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | +| cp1257_lithuanian_ci | cp1257 | 29 | | Yes | 1 | +| latin5_turkish_ci | latin5 | 30 | Yes | Yes | 1 | +| latin1_german2_ci | latin1 | 31 | | Yes | 1 | +| armscii8_general_ci | armscii8 | 32 | Yes | Yes | 1 | +| utf8_general_ci | utf8 | 33 | Yes | Yes | 1 | +| cp1250_czech_cs | cp1250 | 34 | | Yes | 1 | +| ucs2_general_ci | ucs2 | 35 | Yes | Yes | 1 | +| cp866_general_ci | cp866 | 36 | Yes | Yes | 1 | +| keybcs2_general_ci | keybcs2 | 37 | Yes | Yes | 1 | +| macce_general_ci | macce | 38 | Yes | Yes | 1 | +| macroman_general_ci | macroman | 39 | Yes | Yes | 1 | +| cp852_general_ci | cp852 | 40 | Yes | Yes | 1 | +| latin7_general_ci | latin7 | 41 | Yes | Yes | 1 | +| latin7_general_cs | latin7 | 42 | | Yes | 1 | +| macce_bin | macce | 43 | | Yes | 1 | +| cp1250_croatian_ci | cp1250 | 44 | | Yes | 1 | +| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | +| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | +| latin1_bin | latin1 | 47 | | Yes | 1 | +| latin1_general_ci | latin1 | 48 | | Yes | 1 | +| latin1_general_cs | latin1 | 49 | | Yes | 1 | +| cp1251_bin | cp1251 | 50 | | Yes | 1 | +| cp1251_general_ci | cp1251 | 51 | Yes | Yes | 1 | +| cp1251_general_cs | cp1251 | 52 | | Yes | 1 | +| macroman_bin | macroman | 53 | | Yes | 1 | +| utf16_general_ci | utf16 | 54 | Yes | Yes | 1 | +| utf16_bin | utf16 | 55 | | Yes | 1 | +| utf16le_general_ci | utf16le | 56 | Yes | Yes | 1 | +| cp1256_general_ci | cp1256 | 57 | Yes | Yes | 1 | +| cp1257_bin | cp1257 | 58 | | Yes | 1 | +| cp1257_general_ci | cp1257 | 59 | Yes | Yes | 1 | +| utf32_general_ci | utf32 | 60 | Yes | Yes | 1 | +| utf32_bin | utf32 | 61 | | Yes | 1 | +| utf16le_bin | utf16le | 62 | | Yes | 1 | +| binary | binary | 63 | Yes | Yes | 1 | +| armscii8_bin | armscii8 | 64 | | Yes | 1 | +| ascii_bin | ascii | 65 | | Yes | 1 | +| cp1250_bin | cp1250 | 66 | | Yes | 1 | +| cp1256_bin | cp1256 | 67 | | Yes | 1 | +| cp866_bin | cp866 | 68 | | Yes | 1 | +| dec8_bin | dec8 | 69 | | Yes | 1 | +| greek_bin | greek | 70 | | Yes | 1 | +| hebrew_bin | hebrew | 71 | | Yes | 1 | +| hp8_bin | hp8 | 72 | | Yes | 1 | +| keybcs2_bin | keybcs2 | 73 | | Yes | 1 | +| koi8r_bin | koi8r | 74 | | Yes | 1 | +| koi8u_bin | koi8u | 75 | | Yes | 1 | +| latin2_bin | latin2 | 77 | | Yes | 1 | +| latin5_bin | latin5 | 78 | | Yes | 1 | +| latin7_bin | latin7 | 79 | | Yes | 1 | +| cp850_bin | cp850 | 80 | | Yes | 1 | +| cp852_bin | cp852 | 81 | | Yes | 1 | +| swe7_bin | swe7 | 82 | | Yes | 1 | +| utf8_bin | utf8 | 83 | | Yes | 1 | +| big5_bin | big5 | 84 | | Yes | 1 | +| euckr_bin | euckr | 85 | | Yes | 1 | +| gb2312_bin | gb2312 | 86 | | Yes | 1 | +| gbk_bin | gbk | 87 | | Yes | 1 | +| sjis_bin | sjis | 88 | | Yes | 1 | +| tis620_bin | tis620 | 89 | | Yes | 1 | +| ucs2_bin | ucs2 | 90 | | Yes | 1 | +| ujis_bin | ujis | 91 | | Yes | 1 | +| geostd8_general_ci | geostd8 | 92 | Yes | Yes | 1 | +| geostd8_bin | geostd8 | 93 | | Yes | 1 | +| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | +| cp932_japanese_ci | cp932 | 95 | Yes | Yes | 1 | +| cp932_bin | cp932 | 96 | | Yes | 1 | +| eucjpms_japanese_ci | eucjpms | 97 | Yes | Yes | 1 | +| eucjpms_bin | eucjpms | 98 | | Yes | 1 | +| cp1250_polish_ci | cp1250 | 99 | | Yes | 1 | +| utf16_unicode_ci | utf16 | 101 | | Yes | 1 | +| utf16_icelandic_ci | utf16 | 102 | | Yes | 1 | +| utf16_latvian_ci | utf16 | 103 | | Yes | 1 | +| utf16_romanian_ci | utf16 | 104 | | Yes | 1 | +| utf16_slovenian_ci | utf16 | 105 | | Yes | 1 | +| utf16_polish_ci | utf16 | 106 | | Yes | 1 | +| utf16_estonian_ci | utf16 | 107 | | Yes | 1 | +| utf16_spanish_ci | utf16 | 108 | | Yes | 1 | +| utf16_swedish_ci | utf16 | 109 | | Yes | 1 | +| utf16_turkish_ci | utf16 | 110 | | Yes | 1 | +| utf16_czech_ci | utf16 | 111 | | Yes | 1 | +| utf16_danish_ci | utf16 | 112 | | Yes | 1 | +| utf16_lithuanian_ci | utf16 | 113 | | Yes | 1 | +| utf16_slovak_ci | utf16 | 114 | | Yes | 1 | +| utf16_spanish2_ci | utf16 | 115 | | Yes | 1 | +| utf16_roman_ci | utf16 | 116 | | Yes | 1 | +| utf16_persian_ci | utf16 | 117 | | Yes | 1 | +| utf16_esperanto_ci | utf16 | 118 | | Yes | 1 | +| utf16_hungarian_ci | utf16 | 119 | | Yes | 1 | +| utf16_sinhala_ci | utf16 | 120 | | Yes | 1 | +| utf16_german2_ci | utf16 | 121 | | Yes | 1 | +| utf16_croatian_ci | utf16 | 122 | | Yes | 1 | +| utf16_unicode_520_ci | utf16 | 123 | | Yes | 1 | +| utf16_vietnamese_ci | utf16 | 124 | | Yes | 1 | +| ucs2_unicode_ci | ucs2 | 128 | | Yes | 1 | +| ucs2_icelandic_ci | ucs2 | 129 | | Yes | 1 | +| ucs2_latvian_ci | ucs2 | 130 | | Yes | 1 | +| ucs2_romanian_ci | ucs2 | 131 | | Yes | 1 | +| ucs2_slovenian_ci | ucs2 | 132 | | Yes | 1 | +| ucs2_polish_ci | ucs2 | 133 | | Yes | 1 | +| ucs2_estonian_ci | ucs2 | 134 | | Yes | 1 | +| ucs2_spanish_ci | ucs2 | 135 | | Yes | 1 | +| ucs2_swedish_ci | ucs2 | 136 | | Yes | 1 | +| ucs2_turkish_ci | ucs2 | 137 | | Yes | 1 | +| ucs2_czech_ci | ucs2 | 138 | | Yes | 1 | +| ucs2_danish_ci | ucs2 | 139 | | Yes | 1 | +| ucs2_lithuanian_ci | ucs2 | 140 | | Yes | 1 | +| ucs2_slovak_ci | ucs2 | 141 | | Yes | 1 | +| ucs2_spanish2_ci | ucs2 | 142 | | Yes | 1 | +| ucs2_roman_ci | ucs2 | 143 | | Yes | 1 | +| ucs2_persian_ci | ucs2 | 144 | | Yes | 1 | +| ucs2_esperanto_ci | ucs2 | 145 | | Yes | 1 | +| ucs2_hungarian_ci | ucs2 | 146 | | Yes | 1 | +| ucs2_sinhala_ci | ucs2 | 147 | | Yes | 1 | +| ucs2_german2_ci | ucs2 | 148 | | Yes | 1 | +| ucs2_croatian_ci | ucs2 | 149 | | Yes | 1 | +| ucs2_unicode_520_ci | ucs2 | 150 | | Yes | 1 | +| ucs2_vietnamese_ci | ucs2 | 151 | | Yes | 1 | +| ucs2_general_mysql500_ci | ucs2 | 159 | | Yes | 1 | +| utf32_unicode_ci | utf32 | 160 | | Yes | 1 | +| utf32_icelandic_ci | utf32 | 161 | | Yes | 1 | +| utf32_latvian_ci | utf32 | 162 | | Yes | 1 | +| utf32_romanian_ci | utf32 | 163 | | Yes | 1 | +| utf32_slovenian_ci | utf32 | 164 | | Yes | 1 | +| utf32_polish_ci | utf32 | 165 | | Yes | 1 | +| utf32_estonian_ci | utf32 | 166 | | Yes | 1 | +| utf32_spanish_ci | utf32 | 167 | | Yes | 1 | +| utf32_swedish_ci | utf32 | 168 | | Yes | 1 | +| utf32_turkish_ci | utf32 | 169 | | Yes | 1 | +| utf32_czech_ci | utf32 | 170 | | Yes | 1 | +| utf32_danish_ci | utf32 | 171 | | Yes | 1 | +| utf32_lithuanian_ci | utf32 | 172 | | Yes | 1 | +| utf32_slovak_ci | utf32 | 173 | | Yes | 1 | +| utf32_spanish2_ci | utf32 | 174 | | Yes | 1 | +| utf32_roman_ci | utf32 | 175 | | Yes | 1 | +| utf32_persian_ci | utf32 | 176 | | Yes | 1 | +| utf32_esperanto_ci | utf32 | 177 | | Yes | 1 | +| utf32_hungarian_ci | utf32 | 178 | | Yes | 1 | +| utf32_sinhala_ci | utf32 | 179 | | Yes | 1 | +| utf32_german2_ci | utf32 | 180 | | Yes | 1 | +| utf32_croatian_ci | utf32 | 181 | | Yes | 1 | +| utf32_unicode_520_ci | utf32 | 182 | | Yes | 1 | +| utf32_vietnamese_ci | utf32 | 183 | | Yes | 1 | +| utf8_unicode_ci | utf8 | 192 | | Yes | 1 | +| utf8_icelandic_ci | utf8 | 193 | | Yes | 1 | +| utf8_latvian_ci | utf8 | 194 | | Yes | 1 | +| utf8_romanian_ci | utf8 | 195 | | Yes | 1 | +| utf8_slovenian_ci | utf8 | 196 | | Yes | 1 | +| utf8_polish_ci | utf8 | 197 | | Yes | 1 | +| utf8_estonian_ci | utf8 | 198 | | Yes | 1 | +| utf8_spanish_ci | utf8 | 199 | | Yes | 1 | +| utf8_swedish_ci | utf8 | 200 | | Yes | 1 | +| utf8_turkish_ci | utf8 | 201 | | Yes | 1 | +| utf8_czech_ci | utf8 | 202 | | Yes | 1 | +| utf8_danish_ci | utf8 | 203 | | Yes | 1 | +| utf8_lithuanian_ci | utf8 | 204 | | Yes | 1 | +| utf8_slovak_ci | utf8 | 205 | | Yes | 1 | +| utf8_spanish2_ci | utf8 | 206 | | Yes | 1 | +| utf8_roman_ci | utf8 | 207 | | Yes | 1 | +| utf8_persian_ci | utf8 | 208 | | Yes | 1 | +| utf8_esperanto_ci | utf8 | 209 | | Yes | 1 | +| utf8_hungarian_ci | utf8 | 210 | | Yes | 1 | +| utf8_sinhala_ci | utf8 | 211 | | Yes | 1 | +| utf8_german2_ci | utf8 | 212 | | Yes | 1 | +| utf8_croatian_ci | utf8 | 213 | | Yes | 1 | +| utf8_unicode_520_ci | utf8 | 214 | | Yes | 1 | +| utf8_vietnamese_ci | utf8 | 215 | | Yes | 1 | +| utf8_general_mysql500_ci | utf8 | 223 | | Yes | 1 | +| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | +| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | +| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | +| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | +| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | +| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | +| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | +| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | +| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | +| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | +| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | +| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | +| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | +| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | +| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | +| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | +| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | +| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | +| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | +| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | +| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | +| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | +| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | +| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | ++--------------------------+----------+------+---------+----------+---------+ +219 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +TiDB 不支持二进制以外的排序规则。`SHOW COLLATION` 语句仅用于确保与 MySQL 的兼容性。 + +## 另请参阅 + +* [SHOW CHARACTER SET](/reference/sql/statements/show-character-set.md) diff --git a/reference/sql/statements/show-columns-from.md b/reference/sql/statements/show-columns-from.md new file mode 100644 index 000000000000..861bd266ed27 --- /dev/null +++ b/reference/sql/statements/show-columns-from.md @@ -0,0 +1,178 @@ +--- +title: SHOW [FULL] COLUMNS FROM +summary: TiDB 数据库中 SHOW [FULL] COLUMNS FROM 的使用概况。 +category: reference +--- + +# SHOW [FULL] COLUMNS FROM + +`SHOW [FULL] COLUMNS FROM` 语句用于以表格格式描述表或视图中的列。可选关键字 `FULL` 用于显示当前用户对该列的权限，以及表定义中的 `comment`。 + +`SHOW [FULL] FIELDS FROM`，`DESC `，`DESCRIBE
` 和 `EXPLAIN
` 语句都是 `SHOW [FULL] COLUMNS FROM` 的别名。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**OptFull:** + +![OptFull](/media/sqlgram/OptFull.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +create view v1 as select 1; +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +show columns from v1; +``` + +``` ++-------+-----------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+-----------+------+------+---------+-------+ +| 1 | bigint(1) | YES | | NULL | | ++-------+-----------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +desc v1; +``` + +``` ++-------+-----------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+-----------+------+------+---------+-------+ +| 1 | bigint(1) | YES | | NULL | | ++-------+-----------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +describe v1; +``` + +``` ++-------+-----------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+-----------+------+------+---------+-------+ +| 1 | bigint(1) | YES | | NULL | | ++-------+-----------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +explain v1; +``` + +``` ++-------+-----------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+-----------+------+------+---------+-------+ +| 1 | bigint(1) | YES | | NULL | | ++-------+-----------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +show fields from v1; +``` + +``` ++-------+-----------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+-----------+------+------+---------+-------+ +| 1 | bigint(1) | YES | | NULL | | ++-------+-----------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +show full columns from v1; +``` + +``` ++-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ +| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | ++-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ +| 1 | bigint(1) | NULL | YES | | NULL | | select,insert,update,references | | ++-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +show full columns from mysql.user; +``` + +``` ++-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ +| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | ++-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ +| Host | char(64) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | +| User | char(32) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | +| Password | char(41) | utf8mb4_bin | YES | | NULL | | select,insert,update,references | | +| Select_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Insert_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Update_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Delete_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Create_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Drop_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Process_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Grant_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| References_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Alter_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Show_db_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Super_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Create_tmp_table_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Lock_tables_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Execute_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Create_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Show_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Create_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Alter_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Index_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Create_user_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Event_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Trigger_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Create_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Drop_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | +| Account_locked | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | ++-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ +29 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW [FULL] COLUMNS FROM` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/show-create-table.md b/reference/sql/statements/show-create-table.md new file mode 100644 index 000000000000..88c92ca79aea --- /dev/null +++ b/reference/sql/statements/show-create-table.md @@ -0,0 +1,59 @@ +--- +title: SHOW CREATE TABLE +summary: TiDB 数据库中 SHOW CREATE TABLE 的使用概况。 +category: reference +--- + +# SHOW CREATE TABLE + +`SHOW CREATE TABLE` 语句用于显示用 SQL 重新创建已有表的确切语句。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +``` ++-------+------------------------------------------------------------------------------------------------------------+ +| Table | Create Table | ++-------+------------------------------------------------------------------------------------------------------------+ +| t1 | CREATE TABLE `t1` ( + `a` int(11) DEFAULT NULL +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | ++-------+------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW CREATE TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [SHOW TABLES](/reference/sql/statements/show-tables.md) +* [SHOW COLUMNS FROM](/reference/sql/statements/show-columns-from.md) diff --git a/reference/sql/statements/show-create-user.md b/reference/sql/statements/show-create-user.md new file mode 100644 index 000000000000..373b70c3ce79 --- /dev/null +++ b/reference/sql/statements/show-create-user.md @@ -0,0 +1,53 @@ +--- +title: SHOW CREATE USER +summary: TiDB 数据库中 SHOW CREATE USER 的使用概况。 +category: reference +--- + +# SHOW CREATE USER + +`SHOW CREATE USER` 语句用于显示如何使用 `CREATE USER` 语法来重新创建用户。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**Username:** + +![Username](/media/sqlgram/Username.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW CREATE USER 'root'; +``` + +```+--------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER for root@% | ++--------------------------------------------------------------------------------------------------------------------------+ +| CREATE USER 'root'@'%' IDENTIFIED WITH 'mysql_native_password' AS '' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | ++--------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) + +mysql> SHOW GRANTS FOR 'root'; ++-------------------------------------------+ +| Grants for root@% | ++-------------------------------------------+ +| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | ++-------------------------------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +* `SHOW CREATE USER` 的输出结果旨在匹配 MySQL，但 TiDB 尚不支持若干 `CREATE` 选项。尚未支持的选项在语句执行过程中会被解析但会被跳过执行。详情可参阅 [security compatibility]。 + +## 另请参阅 + +* [CREATE USER](/reference/sql/statements/create-user.md) +* [SHOW GRANTS](/reference/sql/statements/show-grants.md) +* [DROP USER](/reference/sql/statements/drop-user.md) diff --git a/reference/sql/statements/show-databases.md b/reference/sql/statements/show-databases.md new file mode 100644 index 000000000000..5c807ccea82b --- /dev/null +++ b/reference/sql/statements/show-databases.md @@ -0,0 +1,80 @@ +--- +title: SHOW DATABASES +summary: TiDB 数据库中 SHOW DATABASES 的使用概况。 +category: reference +--- + +# SHOW DATABASES + +`SHOW DATABASES` 语句用于显示当前用户有权访问的数据库列表。当前用户无权访问的数据库将从列表中隐藏。`information_schema` 数据库始终出现在列表的最前面。 + +`SHOW SCHEMAS` 是 `SHOW DATABASES` 语句的别名。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW DATABASES; +``` + +``` ++--------------------+ +| Database | ++--------------------+ +| INFORMATION_SCHEMA | +| PERFORMANCE_SCHEMA | +| mysql | +| test | ++--------------------+ +4 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE DATABASE mynewdb; +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW DATABASES; +``` + +``` ++--------------------+ +| Database | ++--------------------+ +| INFORMATION_SCHEMA | +| PERFORMANCE_SCHEMA | +| mynewdb | +| mysql | +| test | ++--------------------+ +5 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW DATABASES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW SCHEMAS](/reference/sql/statements/show-schemas.md) +* [DROP DATABASE](/reference/sql/statements/drop-database.md) +* [CREATE DATABASE](/reference/sql/statements/create-database.md) diff --git a/dev/reference/sql/statements/show-engines.md b/reference/sql/statements/show-engines.md similarity index 100% rename from dev/reference/sql/statements/show-engines.md rename to reference/sql/statements/show-engines.md diff --git a/reference/sql/statements/show-errors.md b/reference/sql/statements/show-errors.md new file mode 100644 index 000000000000..929f36cff50a --- /dev/null +++ b/reference/sql/statements/show-errors.md @@ -0,0 +1,102 @@ +--- +title: SHOW ERRORS +summary: TiDB 数据库中 SHOW ERRORS 的使用概况。 +category: reference +--- + +# SHOW ERRORS + +`SHOW ERRORS` 语句用于显示已执行语句中的错误。一旦先前的语句成功执行，就会清除错误缓冲区，这时 `SHOW ERRORS` 会返回一个空集。 + +当前的 `sql_mode` 很大程度决定了哪些语句会产生错误与警告。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +select invalid; +``` + +``` +ERROR 1054 (42S22): Unknown column 'invalid' in 'field list' +``` + +{{< copyable "sql" >}} + +```sql +create invalid; +``` + +``` +ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" +``` + +{{< copyable "sql" >}} + +```sql +SHOW ERRORS; +``` + +``` ++-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Level | Code | Message | ++-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Error | 1054 | Unknown column 'invalid' in 'field list' | +| Error | 1064 | You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" | ++-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE invalid2; +``` + +``` +ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 15 near "invalid2" +``` + +{{< copyable "sql" >}} + +```sql +SELECT 1; +``` + +``` ++------+ +| 1 | ++------+ +| 1 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW ERRORS; +``` + +``` +Empty set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW ERRORS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW WARNINGS](/reference/sql/statements/show-warnings.md) diff --git a/reference/sql/statements/show-fields-from.md b/reference/sql/statements/show-fields-from.md new file mode 100644 index 000000000000..5454119e9283 --- /dev/null +++ b/reference/sql/statements/show-fields-from.md @@ -0,0 +1,9 @@ +--- +title: SHOW [FULL] FIELDS FROM +summary: TiDB 数据库中 SHOW [FULL] FIELDS FROM 的使用概况。 +category: reference +--- + +# SHOW [FULL] FIELDS FROM + +`SHOW [FULL] FIELDS FROM` 是 [`SHOW [FULL] COLUMNS FROM`](/reference/sql/statements/show-columns-from.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/reference/sql/statements/show-grants.md b/reference/sql/statements/show-grants.md new file mode 100644 index 000000000000..c40c9d8b46f8 --- /dev/null +++ b/reference/sql/statements/show-grants.md @@ -0,0 +1,91 @@ +--- +title: SHOW GRANTS +summary: TiDB 数据库中 SHOW GRANTS 的使用概况。 +category: reference +--- + +# SHOW GRANTS + +`SHOW GRANTS` 语句用于显示与用户关联的权限列表。与在 MySQL 中一样，`USAGE` 权限表示登录 TiDB 的能力。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**Username:** + +![Username](/media/sqlgram/Username.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS; +``` + +``` ++-------------------------------------------+ +| Grants for User | ++-------------------------------------------+ +| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | ++-------------------------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR 'u1'; +``` + +``` +ERROR 1141 (42000): There is no such grant defined for user 'u1' on host '%' +``` + +{{< copyable "sql" >}} + +```sql +CREATE USER u1; +``` + +``` +Query OK, 1 row affected (0.04 sec) +``` + +{{< copyable "sql" >}} + +```sql +GRANT SELECT ON test.* TO u1; +``` + +``` +Query OK, 0 rows affected (0.04 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GRANTS FOR u1; +``` + +``` ++------------------------------------+ +| Grants for u1@% | ++------------------------------------+ +| GRANT USAGE ON *.* TO 'u1'@'%' | +| GRANT Select ON test.* TO 'u1'@'%' | ++------------------------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW GRANTS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW CREATE USER](/reference/sql/statements/show-create-user.md) +* [GRANT](/reference/sql/statements/grant-privileges.md) diff --git a/reference/sql/statements/show-index.md b/reference/sql/statements/show-index.md new file mode 100644 index 000000000000..6686230cf28f --- /dev/null +++ b/reference/sql/statements/show-index.md @@ -0,0 +1,9 @@ +--- +title: SHOW INDEX [FROM|IN] +summary: TiDB 数据库中 SHOW INDEX [FROM|IN] 的使用概况。 +category: reference +--- + +# SHOW INDEX [FROM|IN] + +`SHOW INDEX [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/reference/sql/statements/show-indexes.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/reference/sql/statements/show-indexes.md b/reference/sql/statements/show-indexes.md new file mode 100644 index 000000000000..12eadf96dfe0 --- /dev/null +++ b/reference/sql/statements/show-indexes.md @@ -0,0 +1,101 @@ +--- +title: SHOW INDEXES [FROM|IN] +summary: TiDB 数据库中 SHOW INDEXES [FROM|IN] 的使用概况。 +category: reference +--- + +# SHOW INDEXES [FROM|IN] + +`SHOW INDEXES [FROM|IN]` 语句用于列出指定表上的索引。`SHOW INDEX [FROM | IN]` 和 `SHOW KEYS [FROM | IN]` 是该语句的别名。包含该语句提供了 MySQL 兼容性。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**ShowIndexKwd:** + +![ShowIndexKwd](/media/sqlgram/ShowIndexKwd.png) + +**FromOrIn:** + +![FromOrIn](/media/sqlgram/FromOrIn.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT, INDEX(col1)); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW INDEXES FROM t1; +``` + +``` ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | +| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW INDEX FROM t1; +``` + +``` ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | +| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +2 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW KEYS FROM t1; +``` + +``` ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | +| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | ++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW INDEXES [FROM|IN]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) +* [DROP INDEX](/reference/sql/statements/drop-index.md) +* [CREATE INDEX](/reference/sql/statements/create-index.md) diff --git a/reference/sql/statements/show-keys.md b/reference/sql/statements/show-keys.md new file mode 100644 index 000000000000..7a2366413436 --- /dev/null +++ b/reference/sql/statements/show-keys.md @@ -0,0 +1,9 @@ +--- +title: SHOW KEYS [FROM|IN] +summary: TiDB 数据库中 SHOW KEYS [FROM|IN] 的使用概况。 +category: reference +--- + +# SHOW KEYS [FROM|IN] + +`SHOW KEYS [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/reference/sql/statements/show-indexes.md) 语句的别名。包含该语句提供了 MySQL 兼容性。。 diff --git a/reference/sql/statements/show-privileges.md b/reference/sql/statements/show-privileges.md new file mode 100644 index 000000000000..d5bb3ec16709 --- /dev/null +++ b/reference/sql/statements/show-privileges.md @@ -0,0 +1,72 @@ +--- +title: SHOW PRIVILEGES +summary: TiDB 数据库中 SHOW PRIVILEGES 的使用概况。 +category: reference +--- + +# SHOW PRIVILEGES + +`SHOW PRIVILEGES` 语句用于显示 TiDB 中可分配权限的列表。此列表为静态列表，不反映当前用户的权限。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +show privileges; +``` + +``` ++-------------------------+---------------------------------------+-------------------------------------------------------+ +| Privilege | Context | Comment | ++-------------------------+---------------------------------------+-------------------------------------------------------+ +| Alter | Tables | To alter the table | +| Alter | Tables | To alter the table | +| Alter routine | Functions,Procedures | To alter or drop stored functions/procedures | +| Create | Databases,Tables,Indexes | To create new databases and tables | +| Create routine | Databases | To use CREATE FUNCTION/PROCEDURE | +| Create temporary tables | Databases | To use CREATE TEMPORARY TABLE | +| Create view | Tables | To create new views | +| Create user | Server Admin | To create new users | +| Delete | Tables | To delete existing rows | +| Drop | Databases,Tables | To drop databases, tables, and views | +| Event | Server Admin | To create, alter, drop and execute events | +| Execute | Functions,Procedures | To execute stored routines | +| File | File access on server | To read and write files on the server | +| Grant option | Databases,Tables,Functions,Procedures | To give to other users those privileges you possess | +| Index | Tables | To create or drop indexes | +| Insert | Tables | To insert data into tables | +| Lock tables | Databases | To use LOCK TABLES (together with SELECT privilege) | +| Process | Server Admin | To view the plain text of currently executing queries | +| Proxy | Server Admin | To make proxy user possible | +| References | Databases,Tables | To have references on tables | +| Reload | Server Admin | To reload or refresh tables, logs and privileges | +| Replication client | Server Admin | To ask where the slave or master servers are | +| Replication slave | Server Admin | To read binary log events from the master | +| Select | Tables | To retrieve rows from table | +| Show databases | Server Admin | To see all databases with SHOW DATABASES | +| Show view | Tables | To see views with SHOW CREATE VIEW | +| Shutdown | Server Admin | To shut down the server | +| Super | Server Admin | To use KILL thread, SET GLOBAL, CHANGE MASTER, etc. | +| Trigger | Tables | To use triggers | +| Create tablespace | Server Admin | To create/alter/drop tablespaces | +| Update | Tables | To update existing rows | +| Usage | Server Admin | No privileges - allow connect only | ++-------------------------+---------------------------------------+-------------------------------------------------------+ +32 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW GRANTS](/reference/sql/statements/show-grants.md) +* [GRANT ](/reference/sql/statements/grant-privileges.md) diff --git a/reference/sql/statements/show-processlist.md b/reference/sql/statements/show-processlist.md new file mode 100644 index 000000000000..4d89c2f15825 --- /dev/null +++ b/reference/sql/statements/show-processlist.md @@ -0,0 +1,45 @@ +--- +title: SHOW [FULL] PROCESSLIST +summary: TiDB 数据库中 SHOW [FULL] PROCESSLIST 的使用概况。 +category: reference +--- + +# SHOW [FULL] PROCESSLIST + +`SHOW [FULL] PROCESSLIST` 语句列出连接到相同 TiDB 服务器的当前会话。`Info` 列包含查询文本，除非指定可选关键字 `FULL`，否则文本会被截断。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**OptFull:** + +![OptFull](/media/sqlgram/OptFull.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW PROCESSLIST; +``` + +``` ++------+------+-----------+------+---------+------+-------+------------------+ +| Id | User | Host | db | Command | Time | State | Info | ++------+------+-----------+------+---------+------+-------+------------------+ +| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | +| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | ++------+------+-----------+------+---------+------+-------+------------------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +* TiDB 中的 `State` 列是非描述性的。在 TiDB 中，将状态表示为单个值更复杂，因为查询是并行执行的，而且每个 GO 线程在任一时刻都有不同的状态。 + +## 另请参阅 + +* [KILL \[TIDB\]](/reference/sql/statements/kill.md) diff --git a/reference/sql/statements/show-schemas.md b/reference/sql/statements/show-schemas.md new file mode 100644 index 000000000000..3c47fac808e1 --- /dev/null +++ b/reference/sql/statements/show-schemas.md @@ -0,0 +1,9 @@ +--- +title: SHOW SCHEMAS +summary: TiDB 数据库中 SHOW SCHEMAS 的使用概况。 +category: reference +--- + +# SHOW SCHEMAS + +`SHOW SCHEMAS` 语句是 [`SHOW DATABASES`](/reference/sql/statements/show-databases.md) 的别名。包含该语句提供了 MySQL 兼容性。。 diff --git a/reference/sql/statements/show-status.md b/reference/sql/statements/show-status.md new file mode 100644 index 000000000000..ffb683c0a67c --- /dev/null +++ b/reference/sql/statements/show-status.md @@ -0,0 +1,73 @@ +--- +title: SHOW [GLOBAL|SESSION] STATUS +summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] STATUS 的使用概况。 +category: reference +--- + +# SHOW [GLOBAL|SESSION] STATUS + +`SHOW [GLOBAL|SESSION] STATUS` 语句用于提供 MySQL 兼容性，对 TiDB 没有作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**GlobalScope:** + +![GlobalScope](/media/sqlgram/GlobalScope.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +show status; +``` + +``` ++--------------------+--------------------------------------+ +| Variable_name | Value | ++--------------------+--------------------------------------+ +| Ssl_cipher_list | | +| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | +| ddl_schema_version | 141 | +| Ssl_verify_mode | 0 | +| Ssl_version | | +| Ssl_cipher | | ++--------------------+--------------------------------------+ +6 rows in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +show global status; +``` + +``` ++--------------------+--------------------------------------+ +| Variable_name | Value | ++--------------------+--------------------------------------+ +| Ssl_cipher | | +| Ssl_cipher_list | | +| Ssl_verify_mode | 0 | +| Ssl_version | | +| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | +| ddl_schema_version | 141 | ++--------------------+--------------------------------------+ +6 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW [GLOBAL|SESSION] STATUS` 语句仅用于提供 MySQL 兼容性。 + +## 另请参阅 + +* [FLUSH STATUS](/reference/sql/statements/flush-status.md) diff --git a/reference/sql/statements/show-table-regions.md b/reference/sql/statements/show-table-regions.md new file mode 100644 index 000000000000..ac829b76e470 --- /dev/null +++ b/reference/sql/statements/show-table-regions.md @@ -0,0 +1,179 @@ +--- +title: SHOW TABLE REGIONS +summary: 了解如何使用 TiDB 数据库中的 SHOW TABLE REGIONS。 +category: reference +--- + +# SHOW TABLE REGIONS + +`SHOW TABLE REGIONS` 语句用于显示 TiDB 中某个表的 Region 信息。 + +## 语法图 + +```sql +SHOW TABLE [table_name] REGIONS [WhereClauseOptional]; + +SHOW TABLE [table_name] INDEX [index_name] REGIONS [WhereClauseOptional]; +``` + +`SHOW TABLE REGIONS` 会返回如下列： + +* `REGION_ID`：Region 的 ID。 +* `START_KEY`：Region 的 Start key。 +* `END_KEY`：Region 的 End key。 +* `LEADER_ID`：Region 的 Leader ID。 +* `LEADER_STORE_ID`：Region leader 所在的 store (TiKV) ID。 +* `PEERS`：Region 所有副本的 ID。 +* `SCATTERING`：Region 是否正在调度中。1 表示正在调度。 +* `WRITTEN_BYTES`：估算的 Region 在 1 个心跳周期内的写入数据量大小，单位是 byte。 +* `READ_BYTES`：估算的 Region 在 1 个心跳周期内的读数据量大小，单位是 byte。 +* `APPROXIMATE_SIZE(MB)`：估算的 Region 的数据量大小，单位是 MB。 +* `APPROXIMATE_KEYS`：估算的 Region 内 Key 的个数。 + +> **注意：** +> +> `WRITTEN_BYTES`，`READ_BYTES`，`APPROXIMATE_SIZE(MB)`，`APPROXIMATE_KEYS` 的值是 PD 根据 Region 的心跳汇报信息统计，估算出来的数据，所以不是精确的数据。 + +## 示例 + +{{< copyable "sql" >}} + +```sql +create table t (id int key,name varchar(50), index (name)); +``` + +``` +Query OK, 0 rows affected +``` + +默认新建表后会单独 split 出一个 Region 来存放该表的数据，开始时行数据和索引数据都会写到这个 Region。 + +{{< copyable "sql" >}} + +```sql +show table t regions; +``` + +``` ++-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ +| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | ++-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ +| 3 | t_43_ | | 73 | 9 | 5, 73, 93 | 0 | 35 | 0 | 1 | 0 | ++-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ +1 row in set +``` + +解释： + +- 上面 START_KEY 列的值 t_43_ 中，t 是表数据的前缀，43 是表 t 的 table ID。 +- END_KEY 列的值为空（""）表示无穷大。 + +用 `SPLIT TABLE REGION` 语法切分行数据的 Region，下面语法把表 t 的行数据切分成 5 个 Region。 + +{{< copyable "sql" >}} + +```sql +split table t between (0) and (100000) regions 5; +``` + +``` ++--------------------+----------------------+ +| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | ++--------------------+----------------------+ +| 5 | 1.0 | ++--------------------+----------------------+ +1 row in set +``` + +解释： + +- TOTAL_SPLIT_REGION 表示新切的 region 数量，这是新切了 5 个 region. +- SCATTER_FINISH_RATIO 表示新切的 region 的打散成功率，1.0 表示都已经打散了。 + +表 t 现在一共有 6 个 Region，其中 102、106、110、114、3 用来存行数据，Region 98 用来存索引数据。 + +{{< copyable "sql" >}} + +```sql +show table t regions; +``` + +``` ++-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ +| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | ++-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ +| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | +| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 107, 108, 120 | 0 | 23 | 0 | 1 | 0 | +| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | +| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | +| 3 | t_43_r_80000 | | 93 | 8 | 5, 73, 93 | 0 | 0 | 0 | 1 | 0 | +| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | ++-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ +6 rows in set +``` + +解释： + +- Region 102 的 START_KEY 和 END_KEY 中，t_43 是表数据前缀和 table ID，_r 是表 t record 数据的前缀，索引数据的前缀是 _i，所以 Region 102 的 START_KEY 和 END_KEY 表示用来存储 [-inf, 20000) 之前的 record 数据。其他 Region (103, 109, 113, 2) 的存储范围依次类推。 +- Region 98 用来存储索引数据存储。表 t 索引数据的起始 key 是 t_43_i，处于 Region 98 的存储范围内。 + +查看表 t 在 store 1 上的 region，用 where 条件过滤。 + +{{< copyable "sql" >}} + +```sql +show table t regions where leader_store_id =1; +``` + +``` ++-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ +| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | ++-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ +| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | ++-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ +``` + +用 `SPLIT TABLE REGION` 语法切分索引数据的 Region，下面语法把表 t 的索引 name 数据在 [a,z] 范围内切分成 2 个 Region。 + +{{< copyable "sql" >}} + +```sql +split table t index name between ("a") and ("z") regions 2; +``` + +``` ++--------------------+----------------------+ +| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | ++--------------------+----------------------+ +| 2 | 1.0 | ++--------------------+----------------------+ +1 row in set +``` + +现在表 t 一共有 7 个 Region，其中 5 个 Region (102, 106, 110, 114, 3) 用来存表 t 的 record 数据，另外 2 个 Region (135, 98) 用来存 name 索引的数据。 + +{{< copyable "sql" >}} + +```sql +show table t regions; +``` + +``` ++-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ +| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | ++-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ +| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | +| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 108, 120, 126 | 0 | 0 | 0 | 1 | 0 | +| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | +| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | +| 3 | t_43_r_80000 | | 93 | 8 | 73, 93, 128 | 0 | 0 | 0 | 1 | 0 | +| 135 | t_43_i_1_ | t_43_i_1_016d80000000000000 | 139 | 2 | 138, 139, 140 | 0 | 35 | 0 | 1 | 0 | +| 98 | t_43_i_1_016d80000000000000 | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | ++-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ +7 rows in set +``` + +## 另请参阅 + +* [SPLIT REGION](/reference/sql/statements/split-region.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) diff --git a/reference/sql/statements/show-table-status.md b/reference/sql/statements/show-table-status.md new file mode 100644 index 000000000000..45f07a5228ce --- /dev/null +++ b/reference/sql/statements/show-table-status.md @@ -0,0 +1,125 @@ +--- +title: SHOW TABLE STATUS +summary: TiDB 数据库中 SHOW TABLE STATUS 的使用概况。 +category: reference +--- + +# SHOW TABLE STATUS + +`SHOW TABLE STATUS` 语句用于显示 TiDB 中表的各种统计信息。如果显示统计信息过期，建议运行 [`ANALYZE TABLE`](/reference/sql/statements/analyze-table.md)。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**ShowDatabaseNameOpt:** + +![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLE STATUS LIKE 't1'; +``` + +``` +*************************** 1. row *************************** + Name: t1 + Engine: InnoDB + Version: 10 + Row_format: Compact + Rows: 0 + Avg_row_length: 0 + Data_length: 0 +Max_data_length: 0 + Index_length: 0 + Data_free: 0 + Auto_increment: 30001 + Create_time: 2019-04-19 08:32:06 + Update_time: NULL + Check_time: NULL + Collation: utf8mb4_bin + Checksum: + Create_options: + Comment: +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +analyze table t1; +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLE STATUS LIKE 't1'; +``` + +``` +*************************** 1. row *************************** + Name: t1 + Engine: InnoDB + Version: 10 + Row_format: Compact + Rows: 5 + Avg_row_length: 16 + Data_length: 80 +Max_data_length: 0 + Index_length: 0 + Data_free: 0 + Auto_increment: 30001 + Create_time: 2019-04-19 08:32:06 + Update_time: NULL + Check_time: NULL + Collation: utf8mb4_bin + Checksum: + Create_options: + Comment: +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW TABLE STATUS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW TABLES](/reference/sql/statements/show-tables.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/show-tables.md b/reference/sql/statements/show-tables.md new file mode 100644 index 000000000000..c3ab706b782c --- /dev/null +++ b/reference/sql/statements/show-tables.md @@ -0,0 +1,86 @@ +--- +title: SHOW [FULL] TABLES +summary: TiDB 数据库中 SHOW [FULL] TABLES 的使用概况。 +category: reference +--- + +# SHOW [FULL] TABLES + +`SHOW [FULL] TABLES` 语句用于显示当前所选数据库中表和视图的列表。可选关键字 `FULL` 说明表的类型是 `BASE TABLE` 还是 `VIEW`。 + +若要在不同的数据库中显示表，可使用 `SHOW TABLES IN DatabaseName` 语句。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**ShowDatabaseNameOpt:** + +![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) + +## 示例 + +```sql +mysql> CREATE TABLE t1 (a int); +Query OK, 0 rows affected (0.12 sec) + +mysql> CREATE VIEW v1 AS SELECT 1; +Query OK, 0 rows affected (0.10 sec) + +mysql> SHOW TABLES; ++----------------+ +| Tables_in_test | ++----------------+ +| t1 | +| v1 | ++----------------+ +2 rows in set (0.00 sec) + +mysql> SHOW FULL TABLES; ++----------------+------------+ +| Tables_in_test | Table_type | ++----------------+------------+ +| t1 | BASE TABLE | +| v1 | VIEW | ++----------------+------------+ +2 rows in set (0.00 sec) + +mysql> SHOW TABLES IN mysql; ++----------------------+ +| Tables_in_mysql | ++----------------------+ +| GLOBAL_VARIABLES | +| bind_info | +| columns_priv | +| db | +| default_roles | +| gc_delete_range | +| gc_delete_range_done | +| help_topic | +| role_edges | +| stats_buckets | +| stats_feedback | +| stats_histograms | +| stats_meta | +| tables_priv | +| tidb | +| user | ++----------------------+ +16 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW [FULL] TABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/show-variables.md b/reference/sql/statements/show-variables.md new file mode 100644 index 000000000000..46c549d06b73 --- /dev/null +++ b/reference/sql/statements/show-variables.md @@ -0,0 +1,134 @@ +--- +title: SHOW [GLOBAL|SESSION] VARIABLES +summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] VARIABLES 的使用概况。 +category: reference +--- + +# SHOW [GLOBAL|SESSION] VARIABLES + +`SHOW [GLOBAL|SESSION] VARIABLES` 语句用于显示 `GLOBAL` 或 `SESSION` 范围的变量列表。如果未指定范围，则应用默认范围 `SESSION`。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +**GlobalScope:** + +![GlobalScope](/media/sqlgram/GlobalScope.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +SHOW GLOBAL VARIABLES LIKE 'tidb%'; +``` + +``` ++-------------------------------------+---------------+ +| Variable_name | Value | ++-------------------------------------+---------------+ +| tidb_ddl_error_count_limit | 512 | +| tidb_dml_batch_size | 20000 | +| tidb_force_priority | NO_PRIORITY | +| tidb_batch_insert | 0 | +| tidb_skip_utf8_check | 0 | +| tidb_backoff_lock_fast | 100 | +| tidb_opt_join_reorder_threshold | 0 | +| tidb_auto_analyze_end_time | 23:59 +0000 | +| tidb_slow_log_threshold | 300 | +| tidb_opt_correlation_exp_factor | 1 | +| tidb_mem_quota_sort | 34359738368 | +| tidb_current_ts | 0 | +| tidb_ddl_reorg_batch_size | 256 | +| tidb_checksum_table_concurrency | 4 | +| tidb_check_mb4_value_in_utf8 | 1 | +| tidb_distsql_scan_concurrency | 15 | +| tidb_optimizer_selectivity_level | 0 | +| tidb_opt_agg_push_down | 0 | +| tidb_max_chunk_size | 1024 | +| tidb_low_resolution_tso | 0 | +| tidb_index_lookup_size | 20000 | +| tidb_skip_isolation_level_check | 0 | +| tidb_opt_write_row_id | 0 | +| tidb_wait_split_region_finish | 1 | +| tidb_index_lookup_join_concurrency | 4 | +| tidb_mem_quota_indexlookupjoin | 34359738368 | +| tidb_replica_read | leader | +| tidb_ddl_reorg_priority | PRIORITY_LOW | +| tidb_batch_commit | 0 | +| tidb_mem_quota_mergejoin | 34359738368 | +| tidb_mem_quota_query | 34359738368 | +| tidb_batch_delete | 0 | +| tidb_build_stats_concurrency | 4 | +| tidb_enable_index_merge | 0 | +| tidb_enable_radix_join | 0 | +| tidb_retry_limit | 10 | +| tidb_query_log_max_len | 2048 | +| tidb_config | | +| tidb_ddl_reorg_worker_cnt | 4 | +| tidb_opt_insubq_to_join_and_agg | 1 | +| tidb_enable_vectorized_expression | 1 | +| tidb_mem_quota_hashjoin | 34359738368 | +| tidb_disable_txn_auto_retry | 1 | +| tidb_enable_window_function | 1 | +| tidb_init_chunk_size | 32 | +| tidb_constraint_check_in_place | 0 | +| tidb_wait_split_region_timeout | 300 | +| tidb_hash_join_concurrency | 5 | +| tidb_enable_fast_analyze | 0 | +| tidb_enable_cascades_planner | 0 | +| tidb_txn_mode | | +| tidb_index_serial_scan_concurrency | 1 | +| tidb_projection_concurrency | 4 | +| tidb_enable_noop_functions | 0 | +| tidb_index_lookup_concurrency | 4 | +| tidb_hashagg_partial_concurrency | 4 | +| tidb_general_log | 0 | +| tidb_enable_streaming | 0 | +| tidb_backoff_weight | 2 | +| tidb_mem_quota_topn | 34359738368 | +| tidb_scatter_region | 0 | +| tidb_index_join_batch_size | 25000 | +| tidb_snapshot | | +| tidb_expensive_query_time_threshold | 60 | +| tidb_slow_query_file | tidb-slow.log | +| tidb_auto_analyze_ratio | 0.5 | +| tidb_enable_table_partition | auto | +| tidb_auto_analyze_start_time | 00:00 +0000 | +| tidb_mem_quota_nestedloopapply | 34359738368 | +| tidb_mem_quota_indexlookupreader | 34359738368 | +| tidb_hashagg_final_concurrency | 4 | +| tidb_opt_correlation_threshold | 0.9 | ++-------------------------------------+---------------+ +68 rows in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW GLOBAL VARIABLES LIKE 'time_zone%'; +``` + +``` ++---------------+--------+ +| Variable_name | Value | ++---------------+--------+ +| time_zone | SYSTEM | ++---------------+--------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW [GLOBAL|SESSION] VARIABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SET](/reference/sql/statements/set-variable.md) diff --git a/reference/sql/statements/show-warnings.md b/reference/sql/statements/show-warnings.md new file mode 100644 index 000000000000..bb3b37cd622e --- /dev/null +++ b/reference/sql/statements/show-warnings.md @@ -0,0 +1,155 @@ +--- +title: SHOW WARNINGS +summary: TiDB 数据库中 SHOW WARNINGS 的使用概况。 +category: reference +--- + +# SHOW WARNINGS + +`SHOW WARNINGS` 语句用于显示当前客户端连接中已执行语句的报错列表。与在 MySQL 中一样，`sql_mode` 极大地影响哪些语句会导致错误与警告。 + +## 语法图 + +**ShowStmt:** + +![ShowStmt](/media/sqlgram/ShowStmt.png) + +**ShowTargetFilterable:** + +![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT UNSIGNED); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (0); +``` + +``` +Query OK, 1 row affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT 1/a FROM t1; +``` + +``` ++------+ +| 1/a | ++------+ +| NULL | ++------+ +1 row in set, 1 warning (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW WARNINGS; +``` + +``` ++---------+------+---------------+ +| Level | Code | Message | ++---------+------+---------------+ +| Warning | 1365 | Division by 0 | ++---------+------+---------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (-1); +``` + +``` +ERROR 1264 (22003): Out of range value for column 'a' at row 1 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++------+ +| a | ++------+ +| 0 | ++------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SET sql_mode=''; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (-1); +``` + +``` +Query OK, 1 row affected, 1 warning (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW WARNINGS; +``` + +``` ++---------+------+---------------------------+ +| Level | Code | Message | ++---------+------+---------------------------+ +| Warning | 1690 | constant -1 overflows int | ++---------+------+---------------------------+ +1 row in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++------+ +| a | ++------+ +| 0 | +| 0 | ++------+ +2 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`SHOW WARNINGS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [SHOW ERRORS](/reference/sql/statements/show-errors.md) diff --git a/reference/sql/statements/split-region.md b/reference/sql/statements/split-region.md new file mode 100644 index 000000000000..bbef170898b3 --- /dev/null +++ b/reference/sql/statements/split-region.md @@ -0,0 +1,200 @@ +--- +title: Split Region 使用文档 +category: reference +--- + +# Split Region 使用文档 + +在 TiDB 中新建一个表后，默认会单独切分出 1 个 Region 来存储这个表的数据，这个默认行为由配置文件中的 `split-table` 控制。当这个 Region 中的数据超过默认 Region 大小限制后，这个 Region 会开始分裂成 2 个 Region。 + +上述情况中，如果在新建的表上发生大批量写入，则会造成热点，因为开始只有一个 Region，所有的写请求都发生在该 Region 所在的那台 TiKV 上。 + +为解决上述场景中的热点问题，TiDB 引入了预切分 Region 的功能，即可以根据指定的参数，预先为某个表切分出多个 Region，并打散到各个 TiKV 上去。 + +## Split Region 的使用 + +Split Region 有 2 种不同的语法，具体如下： + +```sql +SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num +``` + +`BETWEEN lower_value AND upper_value REGIONS region_num` 语法是通过指定上、下边界和 Region 数量，然后在上、下边界之间均匀切分出 `region_num` 个 Region。 + +```sql +SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ... +``` + +`BY value_list…` 语法将手动指定一系列的点，然后根据这些指定的点切分 Region，适用于数据不均匀分布的场景。 + +### Split Table Region + +表中行数据的 key 由 `table_id` 和 `row_id` 编码组成，格式如下： + +```go +t[table_id]_r[row_id] +``` + +例如，当 `table_id` 是 22，`row_id` 是 11 时： + +```go +t22_r11 +``` + +同一表中行数据的 `table_id` 是一样的，但 `row_id` 肯定不一样，所以可以根据 `row_id` 来切分 Region。 + +#### 均匀切分 + +由于 `row_id` 是整数，所以根据指定的 `lower_value`、`upper_value` 以及 `region_num`，可以推算出需要切分的 key。TiDB 先计算 step（`step = (upper_value - lower_value)/num`），然后在 `lower_value` 和 `upper_value` 之间每隔 step 区间切一次，最终切出 `num` 个 Region。 + +例如，对于表 t，如果想要从 `minInt64`~`maxInt64` 之间均匀切割出 16 个 Region，可以用以下语句： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; +``` + +该语句会把表 t 从 minInt64 到 maxInt64 之间均匀切割出 16 个 Region。如果已知主键的范围没有这么大，比如只会在 0~1000000000 之间，那可以用 0 和 1000000000 分别代替上面的 minInt64 和 maxInt64 来切分 Region。 + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t BETWEEN (0) AND (1000000000) REGIONS 16; +``` + +#### 不均匀切分 + +如果已知数据不是均匀分布的，比如想要 -inf ~ 10000 切一个 Region，10000 ~ 90000 切一个 Region，90000 ~ +inf 切一个 Region，可以通过手动指定点来切分 Region，示例如下： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t BY (10000), (90000); +``` + +### Split Index Region + +表中索引数据的 key 由 `table_id`、`index_id` 以及索引列的值编码组成，格式如下： + +```go +t[table_id]_i[index_id][index_value] +``` + +例如，当 `table_id` 是 22，`index_id` 是 5，`index_value` 是 abc 时： + +```go +t22_i5abc +``` + +同一表中同一索引数据的 `table_id` 和 `index_id` 是一样的，所以要根据 `index_value` 切分索引 Region。 + +#### 均匀切分 + +索引均匀切分与行数据均匀切分的原理一样，只是计算 step 的值较为复杂，因为 `index_value` 可能不是整数。 + +`upper` 和 `lower` 的值会先编码成 byte 数组，去掉 `lower` 和 `upper` byte 数组的最长公共前缀后，从 `lower` 和 `upper` 各取前 8 字节转成 uint64，再计算 `step = (upper - lower)/num`。计算出 step 后再将 step 编码成 byte 数组，添加到之前 `upper`和 `lower`的最长公共前缀后面组成一个 key 后去做切分。示例如下： + +如果索引 idx 的列也是整数类型，可以用如下 SQL 语句切分索引数据： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t INDEX idx BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; +``` + +该语句会把表 t 中 idx 索引数据 Region 从 `minInt64` 到 `maxInt64` 之间均匀切割出 16 个 Region。 + +如果索引 idx1 的列是 varchar 类型，希望根据前缀字母来切分索引数据： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t INDEX idx1 BETWEEN ("a") AND ("z") REGIONS 26; +``` + +该语句会把表 t 中 idx1 索引数据的 Region 从 a~z 切成 26 个 Region，region1 的范围是 [minIndexValue, b)，region2 的范围是 [b, c)，……，region26 的范围是 [z, maxIndexValue)。对于 idx 索引以 a 为前缀的数据都会写到 region1，以 b 为前缀的索引数据都会写到 region2，以此类推。 + +如果索引 idx2 的列是 timestamp/datetime 等时间类型，希望根据时间区间来切分索引数据： + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t INDEX idx2 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; +``` + +该语句会把表 t 中 idx2 的索引数据 Region 从 `2010-01-01 00:00:00` 到 `2020-01-01 00:00:00` 切成 10 个 Region。region1 的范围是从 `[minIndexValue, 2011-01-01 00:00:00)`，region2 的范围是 `[2011-01-01 00:00:00, 2012-01-01 00:00:00)`…… + +其他索引列类型的切分方法也是类似的。 + +对于联合索引的数据 Region 切分，唯一不同的是可以指定多个 column 的值。 + +比如索引 `idx3 (a, b)` 包含 2 列，a 是 timestamp，b 是 int。如果只想根据 a 列做时间范围的切分，可以用切分单列时间索引的 SQL 语句来切分，`lower_value` 和 `upper_velue` 中不指定 b 列的值即可。 + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; +``` + +如果想在时间相同的情况下，根据 b 列再做一次切分，在切分时指定 b 列的值即可。 + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00", "a") AND ("2010-01-01 00:00:00", "z") REGIONS 10; +``` + +该语句在 a 列时间前缀相同的情况下，根据 b 列的值从 a~z 切了 10 个 Region。如果指定的 a 列的值不相同，那么可能不会用到 b 列的值。 + +#### 不均匀切分 + +索引数据也可以根据用户指定的索引值来做切分。 + +假如有 idx4 (a,b)，其中 a 列是 varchar 类型， b 列是 timestamp 类型。 + +{{< copyable "sql" >}} + +```sql +SPLIT TABLE t1 INDEX idx4 BY ("a", "2000-01-01 00:00:01"), ("b", "2019-04-17 14:26:19"), ("c", ""); +``` + +该语句指定了 3 个值，会切分出 4 个 Region，每个 Region 的范围如下。 + +``` +region1 [ minIndexValue , ("a", "2000-01-01 00:00:01")) +region2 [("a", "2000-01-01 00:00:01") , ("b", "2019-04-17 14:26:19")) +region3 [("b", "2019-04-17 14:26:19") , ("c", "") ) +region4 [("c", "") , maxIndexValue ) +``` + +## pre_split_regions + +使用带有 `shard_row_id_bits` 的表时，如果希望建表时就均匀切分 Region，可以考虑配合 `pre_split_regions` 一起使用，用来在建表成功后就开始预均匀切分 `2^(pre_split_regions)` 个 Region。 + +> **注意：** +> +> `pre_split_regions` 必须小于等于 `shard_row_id_bits`。 + +### 示例 + +{{< copyable "sql" >}} + +```sql +create table t (a int, b int,index idx1(a)) shard_row_id_bits = 4 pre_split_regions=2; +``` + +该语句在建表后，会对这个表 t 预切分出 4 + 1 个 Region。4 (2^2) 个 Region 是用来存 table 的行数据的，1 个 Region 是用来存 idx1 索引的数据。 + +4 个 table Region 的范围区间如下： + +``` +region1: [ -inf , 1<<61 ) +region2: [ 1<<61 , 2<<61 ) +region3: [ 2<<61 , 3<<61 ) +region4: [ 3<<61 , +inf ) +``` + +## 相关 session 变量 + +和 `SPLIT REGION` 语句相关的 session 变量有 `tidb_scatter_region`，`tidb_wait_split_region_finish` 和 `tidb_wait_split_region_timeout`，具体可参考 [TiDB 专用系统变量和语法](/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/reference/sql/statements/start-transaction.md b/reference/sql/statements/start-transaction.md new file mode 100644 index 000000000000..09d7792367ba --- /dev/null +++ b/reference/sql/statements/start-transaction.md @@ -0,0 +1,69 @@ +--- +title: START TRANSACTION +summary: TiDB 数据库中 START TRANSACTION 的使用概况。 +category: reference +--- + +# START TRANSACTION + +`START TRANSACTION` 语句用于在 TiDB 内部启动新事务。它类似于语句 `BEGIN` 和 `SET autocommit = 0`。 + +在没有 `START TRANSACTION` 语句的情况下，每个语句都会在各自的事务中自动提交，这样可确保 MySQL 兼容性。 + +## 语法图 + +**BeginTransactionStmt:** + +![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.12 sec) +``` + +{{< copyable "sql" >}} + +```sql +START TRANSACTION; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1); +``` + +``` +Query OK, 1 row affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +COMMIT; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +## MySQL 兼容性 + +`START TRANSACTION` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [COMMIT](/reference/sql/statements/commit.md) +* [ROLLBACK](/reference/sql/statements/rollback.md) +* [BEGIN](/reference/sql/statements/begin.md) diff --git a/reference/sql/statements/trace.md b/reference/sql/statements/trace.md new file mode 100644 index 000000000000..5854c77a6f68 --- /dev/null +++ b/reference/sql/statements/trace.md @@ -0,0 +1,169 @@ +--- +title: TRACE +summary: TiDB 数据库中 TRACE 的使用概况。 +category: reference +--- + +# TRACE + +`TRACE` 语句用于提供查询执行的详细信息，可通过 TiDB 服务器状态端口所公开的图形界面进行查看。 + +## 语法图 + +**TraceStmt:** + +![TraceStmt](/media/sqlgram/TraceStmt.png) + +**TraceableStmt:** + +![TraceableStmt](/media/sqlgram/TraceableStmt.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +trace format='row' select * from mysql.user; +``` + +``` ++---------------------------+-----------------+------------+ +| operation | startTS | duration | ++---------------------------+-----------------+------------+ +| session.getTxnFuture | 10:33:34.647148 | 3.847µs | +| ├─session.Execute | 10:33:34.647146 | 536.233µs | +| ├─session.ParseSQL | 10:33:34.647182 | 19.868µs | +| ├─executor.Compile | 10:33:34.647219 | 295.688µs | +| ├─session.runStmt | 10:33:34.647533 | 116.229µs | +| ├─session.CommitTxn | 10:33:34.647631 | 5.44µs | +| ├─recordSet.Next | 10:33:34.647707 | 833.103µs | +| ├─tableReader.Next | 10:33:34.647709 | 806.783µs | +| ├─recordSet.Next | 10:33:34.648572 | 19.367µs | +| └─tableReader.Next | 10:33:34.648575 | 1.783µs | ++---------------------------+-----------------+------------+ +10 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +TRACE FORMAT='json' SELECT * FROM t1 WHERE id = 2; +``` + +``` +operation: [ + {"ID":{"Trace":"60d20d005593de87","Span":"44e5b309242ffe2f","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"c2Vzc2lvbi5nZXRUeG5GdXR1cmU="}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTQ3ODYtMDY6MDA="}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MjA0MDYtMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":[ + {"ID":{"Trace":"60d20d005593de87","Span":"4dbf8f2ca373b4b0","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"c2Vzc2lvbi5QYXJzZVNRTA=="}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2NjE1MTQtMDY6MDA="}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MDYxNjgtMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null}, + {"ID":{"Trace":"60d20d005593de87","Span":"6b6d6916df809604","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"ZXhlY3V0b3IuQ29tcGlsZQ=="}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NTcyODUtMDY6MDA="}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MzE0MjYtMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null}, + {"ID":{"Trace":"60d20d005593de87","Span":"3f1bcdd402a72911","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"c2Vzc2lvbi5Db21taXRUeG4="}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3OTgyNjItMDY6MDA="}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MDU1NzYtMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null}, + {"ID":{"Trace":"60d20d005593de87","Span":"58c1f7d66dc5afbc","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"c2Vzc2lvbi5ydW5TdG10"}, + {"Key":"_schema:name","Value":null}, + {"Key":"Msg","Value":"eyJzcWwiOiJTRUxFQ1QgKiBGUk9NIHQxIFdIRVJFIGlkID0gMiJ9"}, + {"Key":"Time","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3ODA1NjgtMDY6MDA="}, + {"Key":"_schema:log","Value":null}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MTk5MzMtMDY6MDA="}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NzcyNDItMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null}, + {"ID":{"Trace":"60d20d005593de87","Span":"6bd8cc440fb31ed7","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"c2Vzc2lvbi5FeGVjdXRl"}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTEwODktMDY6MDA="}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NTU0My0wNjowMA=="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null}, + {"ID":{"Trace":"60d20d005593de87","Span":"61d0b809f6cc018b","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NzQ1NTYtMDY6MDA="}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIyOTg4NjYtMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null}, + {"ID":{"Trace":"60d20d005593de87","Span":"2bd2c3d47ccb1133","Parent":"79d146dac9a29a7e"}, + "Annotations":[ + {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, + {"Key":"_schema:name","Value":null}, + {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjY0ODgtMDY6MDA="}, + {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjkwMDMtMDY6MDA="}, + {"Key":"_schema:Timespan","Value":null} + ], + "Sub":null} + ] + } +] +1 row in set (0.00 sec) +``` + +可将 JSON 格式的跟踪文件粘贴到跟踪查看器中。查看器可通过 TiDB 状态端口访问： + +![TiDB Trace Viewer-1](/media/trace-paste.png) + +![TiDB Trace Viewer-2](/media/trace-view.png) + +## MySQL 兼容性 + +`TRACE` 语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +* [EXPLAIN ANALYZE](/reference/sql/statements/explain-analyze.md) diff --git a/reference/sql/statements/truncate.md b/reference/sql/statements/truncate.md new file mode 100644 index 000000000000..d0f3544a2567 --- /dev/null +++ b/reference/sql/statements/truncate.md @@ -0,0 +1,119 @@ +--- +title: TRUNCATE +summary: TiDB 数据库中 TRUNCATE 的使用概况。 +category: reference +--- + +# TRUNCATE + +`TRUNCATE` 语句以非事务方式从表中删除所有数据。可认为 `TRUNCATE` 语句同 `DROP TABLE` + `CREATE TABLE` 组合在语义上相同，定义与 `DROP TABLE` 语句相同。 + +`TRUNCATE TABLE tableName` 和 `TRUNCATE tableName` 均为有效语法。 + +## 语法图 + +**TruncateTableStmt:** + +![TruncateTableStmt](/media/sqlgram/TruncateTableStmt.png) + +**OptTable:** + +![OptTable](/media/sqlgram/OptTable.png) + +**TableName:** + +![TableName](/media/sqlgram/TableName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.01 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++---+ +| a | ++---+ +| 1 | +| 2 | +| 3 | +| 4 | +| 5 | ++---+ +5 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +TRUNCATE t1; +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` +Empty set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sqlS +INSERT INTO t1 VALUES (1),(2),(3),(4),(5); +``` + +``` +Query OK, 5 rows affected (0.01 sec) +Records: 5 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +TRUNCATE TABLE t1; +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +## MySQL 兼容性 + +`TRUNCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [DROP TABLE](/reference/sql/statements/drop-table.md) +* [DELETE](/reference/sql/statements/delete.md) +* [CREATE TABLE](/reference/sql/statements/create-table.md) +* [SHOW CREATE TABLE](/reference/sql/statements/show-create-table.md) diff --git a/reference/sql/statements/update.md b/reference/sql/statements/update.md new file mode 100644 index 000000000000..2bbe9db1cb83 --- /dev/null +++ b/reference/sql/statements/update.md @@ -0,0 +1,110 @@ +--- +title: UPDATE +summary: TiDB 数据库中 UPDATE 的使用概况。 +category: reference +--- + +# UPDATE + +`UPDATE` 语句用于修改指定表中的数据。 + +## 语法图 + +**UpdateStmt:** + +![UpdateStmt](/media/sqlgram/UpdateStmt.png) + +**TableRef:** + +![TableRef](/media/sqlgram/TableRef.png) + +**TableRefs:** + +![TableRefs](/media/sqlgram/TableRefs.png) + +**AssignmentList:** + +![AssignmentList](/media/sqlgram/AssignmentList.png) + +**WhereClauseOptional:** + +![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); +``` + +``` +Query OK, 0 rows affected (0.11 sec) +``` + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 (c1) VALUES (1), (2), (3); +``` + +``` +Query OK, 3 rows affected (0.02 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | ++----+----+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +UPDATE t1 SET c1=5 WHERE c1=3; +``` + +``` +Query OK, 1 row affected (0.01 sec) +Rows matched: 1 Changed: 1 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1; +``` + +``` ++----+----+ +| id | c1 | ++----+----+ +| 1 | 1 | +| 2 | 2 | +| 3 | 5 | ++----+----+ +3 rows in set (0.00 sec) +``` + +## MySQL 兼容性 + +`UPDATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [INSERT](/reference/sql/statements/insert.md) +* [SELECT](/reference/sql/statements/select.md) +* [DELETE](/reference/sql/statements/delete.md) +* [REPLACE](/reference/sql/statements/replace.md) diff --git a/reference/sql/statements/use.md b/reference/sql/statements/use.md new file mode 100644 index 000000000000..50a3fa060e26 --- /dev/null +++ b/reference/sql/statements/use.md @@ -0,0 +1,128 @@ +--- +title: USE +summary: TiDB 数据库中 USE 的使用概况。 +category: reference +--- + +# USE + +`USE` 语句可为用户会话选择当前数据库。 + +## 语法图 + +**UseStmt:** + +![UseStmt](/media/sqlgram/UseStmt.png) + +**DBName:** + +![DBName](/media/sqlgram/DBName.png) + +## 示例 + +{{< copyable "sql" >}} + +```sql +USE mysql; +``` + +``` +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Database changed +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES; +``` + +``` ++----------------------+ +| Tables_in_mysql | ++----------------------+ +| GLOBAL_VARIABLES | +| bind_info | +| columns_priv | +| db | +| default_roles | +| gc_delete_range | +| gc_delete_range_done | +| help_topic | +| role_edges | +| stats_buckets | +| stats_feedback | +| stats_histograms | +| stats_meta | +| tables_priv | +| tidb | +| user | ++----------------------+ +16 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE DATABASE newtest; +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +USE newtest; +``` + +``` +Database changed +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES; +``` + +``` +Empty set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a int); +``` + +``` +Query OK, 0 rows affected (0.10 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES; +``` + +``` ++-------------------+ +| Tables_in_newtest | ++-------------------+ +| t1 | ++-------------------+ +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +`USE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/report-issue.md)。 + +## 另请参阅 + +* [CREATE DATABASE](/reference/sql/statements/create-database.md) +* [SHOW TABLES](/reference/sql/statements/show-tables.md) diff --git a/reference/sql/view.md b/reference/sql/view.md new file mode 100644 index 000000000000..309dbf6d2222 --- /dev/null +++ b/reference/sql/view.md @@ -0,0 +1,108 @@ +--- +title: 视图 +category: reference +--- + +# 视图 + +TiDB 支持视图，视图是一张虚拟表，该虚拟表的结构由创建视图时的 `SELECT` 语句定义。使用视图一方面可以对用户只暴露安全的字段及数据，进而保证底层表的敏感字段及数据的安全。另一方面，将频繁出现的复杂查询定义为视图，可以使复杂查询更加简单便捷。 + +## 查询视图 + +查询一个视图和查询一张普通表类似。但是 TiDB 在真正执行查询视图时，会将视图展开成创建视图时定义的 `SELECT` 语句，进而执行展开后的查询语句。 + +## 样例 + +以下例子将创建一个视图，并在该视图上进行查询，最后删除该视图。 + +{{< copyable "sql" >}} + +```sql +create table t(a int, b int); +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +insert into t values(1, 1),(2,2),(3,3); +``` + +``` +Query OK, 3 rows affected (0.00 sec) +Records: 3 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +create table s(a int); +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +insert into s values(2),(3); +``` + +``` +Query OK, 2 rows affected (0.01 sec) +Records: 2 Duplicates: 0 Warnings: 0 +``` + +{{< copyable "sql" >}} + +```sql +create view v as select s.a from t left join s on t.a = s.a; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +select * from v; +``` + +``` ++------+ +| a | ++------+ +| NULL | +| 2 | +| 3 | ++------+ +3 rows in set (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +drop view v; +``` + +``` +Query OK, 0 rows affected (0.02 sec) +``` + +## 局限性 + +目前 TiDB 中的视图有以下局限性： + +- 不支持物化视图。 +- TiDB 中视图为只读视图，不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 +- 对已创建的视图仅支持 `DROP` 的 DDL 操作，即 `DROP [VIEW | TABLE]`。 + +## 扩展阅读 + +- [创建视图](/reference/sql/statements/create-view.md) +- [删除视图](/reference/sql/statements/drop-view.md) diff --git a/dev/reference/supported-clients.md b/reference/supported-clients.md similarity index 100% rename from dev/reference/supported-clients.md rename to reference/supported-clients.md diff --git a/reference/system-databases/information-schema.md b/reference/system-databases/information-schema.md new file mode 100644 index 000000000000..2b8b875774c3 --- /dev/null +++ b/reference/system-databases/information-schema.md @@ -0,0 +1,767 @@ +--- +title: Information Schema +category: reference +--- + +# Information Schema + +为了和 MySQL 保持兼容，TiDB 支持很多 `INFORMATION_SCHEMA` 表，其中有不少表都支持相应的 `SHOW` 命令。查询 `INFORMATION_SCHEMA` 表也为表的连接操作提供了可能。 + +## ANALYZE_STATUS 表 + +`ANALYZE_STATUS` 表提供正在执行的收集统计信息的任务以及有限条历史任务记录。 + +{{< copyable "sql" >}} + +```sql +select * from `ANALYZE_STATUS`; +``` + +``` ++--------------+------------+----------------+-------------------+----------------+---------------------+----------+ +| TABLE_SCHEMA | TABLE_NAME | PARTITION_NAME | JOB_INFO | PROCESSED_ROWS | START_TIME | STATE | ++--------------+------------+----------------+-------------------+----------------+---------------------+----------+ +| test | t | | analyze index idx | 2 | 2019-06-21 19:51:14 | finished | +| test | t | | analyze columns | 2 | 2019-06-21 19:51:14 | finished | +| test | t1 | p0 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | +| test | t1 | p3 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | +| test | t1 | p1 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | +| test | t1 | p2 | analyze columns | 1 | 2019-06-21 19:51:15 | finished | ++--------------+------------+----------------+-------------------+----------------+---------------------+----------+ +6 rows in set +``` + +## CHARACTER_SETS 表 + +`CHARACTER_SETS` 表提供[字符集](/reference/sql/character-set.md)相关的信息。TiDB 目前仅支持部分字符集。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM character_sets; +``` + +``` ++--------------------+----------------------+---------------+--------+ +| CHARACTER_SET_NAME | DEFAULT_COLLATE_NAME | DESCRIPTION | MAXLEN | ++--------------------+----------------------+---------------+--------+ +| utf8 | utf8_bin | UTF-8 Unicode | 3 | +| utf8mb4 | utf8mb4_bin | UTF-8 Unicode | 4 | +| ascii | ascii_bin | US ASCII | 1 | +| latin1 | latin1_bin | Latin1 | 1 | +| binary | binary | binary | 1 | ++--------------------+----------------------+---------------+--------+ +5 rows in set (0.00 sec) +``` + +## COLLATIONS 表 + +`COLLATIONS` 表提供了 `CHARACTER_SETS` 表中字符集对应的排序规则列表。TiDB 当前仅支持二进制排序规则，包含该表仅为兼容 MySQL。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM collations WHERE character_set_name='utf8mb4'; +``` + +``` ++------------------------+--------------------+------+------------+-------------+---------+ +| COLLATION_NAME | CHARACTER_SET_NAME | ID | IS_DEFAULT | IS_COMPILED | SORTLEN | ++------------------------+--------------------+------+------------+-------------+---------+ +| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | +| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | +| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | +| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | +| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | +| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | +| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | +| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | +| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | +| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | +| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | +| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | +| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | +| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | +| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | +| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | +| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | +| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | +| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | +| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | +| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | +| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | +| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | +| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | +| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | +| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | ++------------------------+--------------------+------+------------+-------------+---------+ +26 rows in set (0.00 sec) +``` + +## COLLATION_CHARACTER_SET_APPLICABILITY 表 + +`COLLATION_CHARACTER_SET_APPLICABILITY` 表将排序规则映射至适用的字符集名称。和 `COLLATIONS` 表一样，包含此表也是为了兼容 MySQL。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM collation_character_set_applicability WHERE character_set_name='utf8mb4'; +``` + +``` ++------------------------+--------------------+ +| COLLATION_NAME | CHARACTER_SET_NAME | ++------------------------+--------------------+ +| utf8mb4_general_ci | utf8mb4 | +| utf8mb4_bin | utf8mb4 | +| utf8mb4_unicode_ci | utf8mb4 | +| utf8mb4_icelandic_ci | utf8mb4 | +| utf8mb4_latvian_ci | utf8mb4 | +| utf8mb4_romanian_ci | utf8mb4 | +| utf8mb4_slovenian_ci | utf8mb4 | +| utf8mb4_polish_ci | utf8mb4 | +| utf8mb4_estonian_ci | utf8mb4 | +| utf8mb4_spanish_ci | utf8mb4 | +| utf8mb4_swedish_ci | utf8mb4 | +| utf8mb4_turkish_ci | utf8mb4 | +| utf8mb4_czech_ci | utf8mb4 | +| utf8mb4_danish_ci | utf8mb4 | +| utf8mb4_lithuanian_ci | utf8mb4 | +| utf8mb4_slovak_ci | utf8mb4 | +| utf8mb4_spanish2_ci | utf8mb4 | +| utf8mb4_roman_ci | utf8mb4 | +| utf8mb4_persian_ci | utf8mb4 | +| utf8mb4_esperanto_ci | utf8mb4 | +| utf8mb4_hungarian_ci | utf8mb4 | +| utf8mb4_sinhala_ci | utf8mb4 | +| utf8mb4_german2_ci | utf8mb4 | +| utf8mb4_croatian_ci | utf8mb4 | +| utf8mb4_unicode_520_ci | utf8mb4 | +| utf8mb4_vietnamese_ci | utf8mb4 | ++------------------------+--------------------+ +26 rows in set (0.00 sec) +``` + +## COLUMNS 表 + +`COLUMNS` 表提供了表的所有列的信息。 + +{{< copyable "sql" >}} + +```sql +CREATE TABLE test.t1 (a int); +``` + +``` +1 row in set (0.01 sec) +``` + +{{< copyable "sql" >}} + +```sql +SELECT * FROM information_schema.columns WHERE table_schema='test' AND TABLE_NAME='t1'; +``` + +``` +*************************** 1. row *************************** + TABLE_CATALOG: def + TABLE_SCHEMA: test + TABLE_NAME: t1 + COLUMN_NAME: a + ORDINAL_POSITION: 1 + COLUMN_DEFAULT: NULL + IS_NULLABLE: YES + DATA_TYPE: int +CHARACTER_MAXIMUM_LENGTH: NULL + CHARACTER_OCTET_LENGTH: NULL + NUMERIC_PRECISION: 11 + NUMERIC_SCALE: 0 + DATETIME_PRECISION: NULL + CHARACTER_SET_NAME: NULL + COLLATION_NAME: NULL + COLUMN_TYPE: int(11) + COLUMN_KEY: + EXTRA: + PRIVILEGES: select,insert,update,references + COLUMN_COMMENT: + GENERATION_EXPRESSION: +1 row in set (0.01 sec) +``` + +对应的 `SHOW` 语句如下： + +{{< copyable "sql" >}} + +```sql +SHOW COLUMNS FROM t1 FROM test; +``` + +``` ++-------+---------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------+---------+------+------+---------+-------+ +| a | int(11) | YES | | NULL | | ++-------+---------+------+------+---------+-------+ +1 row in set (0.00 sec) +``` + +## ENGINES 表 + +`ENGINES` 表提供了关于存储引擎的信息。从和 MySQL 兼容性上考虑，TiDB 会一直将 InnoDB 描述为唯一支持的引擎。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM engines; +``` + +``` +*************************** 1. row *************************** + ENGINE: InnoDB + SUPPORT: DEFAULT + COMMENT: Supports transactions, row-level locking, and foreign keys +TRANSACTIONS: YES + XA: YES + SAVEPOINTS: YES +1 row in set (0.00 sec) +``` + +## KEY_COLUMN_USAGE 表 + +`KEY_COLUMN_USAGE` 表描述了列的键约束，比如主键约束。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM key_column_usage WHERE table_schema='mysql' and table_name='user'; +``` + +``` +*************************** 1. row *************************** + CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: PRIMARY + TABLE_CATALOG: def + TABLE_SCHEMA: mysql + TABLE_NAME: user + COLUMN_NAME: Host + ORDINAL_POSITION: 1 +POSITION_IN_UNIQUE_CONSTRAINT: NULL + REFERENCED_TABLE_SCHEMA: NULL + REFERENCED_TABLE_NAME: NULL + REFERENCED_COLUMN_NAME: NULL +*************************** 2. row *************************** + CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: PRIMARY + TABLE_CATALOG: def + TABLE_SCHEMA: mysql + TABLE_NAME: user + COLUMN_NAME: User + ORDINAL_POSITION: 2 +POSITION_IN_UNIQUE_CONSTRAINT: NULL + REFERENCED_TABLE_SCHEMA: NULL + REFERENCED_TABLE_NAME: NULL + REFERENCED_COLUMN_NAME: NULL +2 rows in set (0.00 sec) +``` + +## PROCESSLIST 表 + +`PROCESSLIST` 和 `show processlist` 的功能一样，都是查看当前正在处理的请求。 + +`PROCESSLIST` 表会比 `show processlist` 多一个 `MEM` 列，`MEM` 是指正在处理的请求已使用的内存，单位是 byte。 + +```sql ++----+------+------+--------------------+---------+------+-------+---------------------------+-----+ +| ID | USER | HOST | DB | COMMAND | TIME | STATE | INFO | MEM | ++----+------+------+--------------------+---------+------+-------+---------------------------+-----+ +| 1 | root | ::1 | INFORMATION_SCHEMA | Query | 0 | 2 | select * from PROCESSLIST | 0 | ++----+------+------+--------------------+---------+------+-------+---------------------------+-----+ +``` + +## SCHEMATA 表 + +`SCHEMATA` 表提供了关于数据库的信息。表中的数据与 `SHOW DATABASES` 语句的执行结果等价。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM schemata; +``` + +``` ++--------------+--------------------+----------------------------+------------------------+----------+ +| CATALOG_NAME | SCHEMA_NAME | DEFAULT_CHARACTER_SET_NAME | DEFAULT_COLLATION_NAME | SQL_PATH | ++--------------+--------------------+----------------------------+------------------------+----------+ +| def | INFORMATION_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | +| def | mynewdb | utf8mb4 | utf8mb4_bin | NULL | +| def | mysql | utf8mb4 | utf8mb4_bin | NULL | +| def | PERFORMANCE_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | +| def | test | utf8mb4 | utf8mb4_bin | NULL | ++--------------+--------------------+----------------------------+------------------------+----------+ +5 rows in set (0.00 sec) +``` + +## SESSION_VARIABLES 表 + +`SESSION_VARIABLES` 表提供了关于 session 变量的信息。表中的数据跟 `SHOW SESSION VARIABLES` 语句执行结果类似。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM session_variables LIMIT 10; +``` + +``` ++----------------------------------+----------------------+ +| VARIABLE_NAME | VARIABLE_VALUE | ++----------------------------------+----------------------+ +| max_write_lock_count | 18446744073709551615 | +| server_id_bits | 32 | +| net_read_timeout | 30 | +| innodb_online_alter_log_max_size | 134217728 | +| innodb_optimize_fulltext_only | OFF | +| max_join_size | 18446744073709551615 | +| innodb_read_io_threads | 4 | +| session_track_gtids | OFF | +| have_ssl | DISABLED | +| max_binlog_cache_size | 18446744073709547520 | ++----------------------------------+----------------------+ +10 rows in set (0.00 sec) +``` + +## SLOW_QUERY 表 + +`SLOW_QUERY` 表中提供了慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，列名和慢日志中的字段名是一一对应。关于如何使用该表调查和改善慢查询请参考[慢查询日志文档](/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 + +```sql +mysql> desc information_schema.slow_query; ++---------------+---------------------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++---------------+---------------------+------+------+---------+-------+ +| Time | timestamp unsigned | YES | | NULL | | +| Txn_start_ts | bigint(20) unsigned | YES | | NULL | | +| User | varchar(64) | YES | | NULL | | +| Host | varchar(64) | YES | | NULL | | +| Conn_ID | bigint(20) unsigned | YES | | NULL | | +| Query_time | double unsigned | YES | | NULL | | +| Process_time | double unsigned | YES | | NULL | | +| Wait_time | double unsigned | YES | | NULL | | +| Backoff_time | double unsigned | YES | | NULL | | +| Request_count | bigint(20) unsigned | YES | | NULL | | +| Total_keys | bigint(20) unsigned | YES | | NULL | | +| Process_keys | bigint(20) unsigned | YES | | NULL | | +| DB | varchar(64) | YES | | NULL | | +| Index_ids | varchar(100) | YES | | NULL | | +| Is_internal | tinyint(1) unsigned | YES | | NULL | | +| Digest | varchar(64) | YES | | NULL | | +| Stats | varchar(512) | YES | | NULL | | +| Cop_proc_avg | double unsigned | YES | | NULL | | +| Cop_proc_p90 | double unsigned | YES | | NULL | | +| Cop_proc_max | double unsigned | YES | | NULL | | +| Cop_proc_addr | varchar(64) | YES | | NULL | | +| Cop_wait_avg | double unsigned | YES | | NULL | | +| Cop_wait_p90 | double unsigned | YES | | NULL | | +| Cop_wait_max | double unsigned | YES | | NULL | | +| Cop_wait_addr | varchar(64) | YES | | NULL | | +| Mem_max | bigint(20) unsigned | YES | | NULL | | +| Succ | tinyint(1) unsigned | YES | | NULL | | +| Query | longblob unsigned | YES | | NULL | | ++---------------+---------------------+------+------+---------+-------+ +``` + +## STATISTICS 表 + +`STATISTICS` 表提供了关于表索引的信息。 + +{{< copyable "sql" >}} + +```sql +desc statistics; +``` + +``` ++---------------|---------------------|------|------|---------|-------+ +| Field | Type | Null | Key | Default | Extra | ++---------------|---------------------|------|------|---------|-------+ +| TABLE_CATALOG | varchar(512) | YES | | NULL | | +| TABLE_SCHEMA | varchar(64) | YES | | NULL | | +| TABLE_NAME | varchar(64) | YES | | NULL | | +| NON_UNIQUE | varchar(1) | YES | | NULL | | +| INDEX_SCHEMA | varchar(64) | YES | | NULL | | +| INDEX_NAME | varchar(64) | YES | | NULL | | +| SEQ_IN_INDEX | bigint(2) UNSIGNED | YES | | NULL | | +| COLUMN_NAME | varchar(21) | YES | | NULL | | +| COLLATION | varchar(1) | YES | | NULL | | +| CARDINALITY | bigint(21) UNSIGNED | YES | | NULL | | +| SUB_PART | bigint(3) UNSIGNED | YES | | NULL | | +| PACKED | varchar(10) | YES | | NULL | | +| NULLABLE | varchar(3) | YES | | NULL | | +| INDEX_TYPE | varchar(16) | YES | | NULL | | +| COMMENT | varchar(16) | YES | | NULL | | +| INDEX_COMMENT | varchar(1024) | YES | | NULL | | ++---------------|---------------------|------|------|---------|-------+ +``` + +下列语句是等价的： + +{{< copyable "sql" >}} + +```sql +SELECT * FROM INFORMATION_SCHEMA.STATISTICS + WHERE table_name = 'tbl_name' + AND table_schema = 'db_name' +``` + +{{< copyable "sql" >}} + +```sql +SHOW INDEX + FROM tbl_name + FROM db_name +``` + +## TABLES 表 + +`TABLES` 表提供了数据库里面关于表的信息。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'; +``` + +``` +*************************** 1. row *************************** + TABLE_CATALOG: def + TABLE_SCHEMA: mysql + TABLE_NAME: user + TABLE_TYPE: BASE TABLE + ENGINE: InnoDB + VERSION: 10 + ROW_FORMAT: Compact + TABLE_ROWS: 0 + AVG_ROW_LENGTH: 0 + DATA_LENGTH: 0 + MAX_DATA_LENGTH: 0 + INDEX_LENGTH: 0 + DATA_FREE: 0 + AUTO_INCREMENT: 0 + CREATE_TIME: 2019-03-29 09:17:27 + UPDATE_TIME: NULL + CHECK_TIME: NULL + TABLE_COLLATION: utf8mb4_bin + CHECKSUM: NULL + CREATE_OPTIONS: + TABLE_COMMENT: + TIDB_TABLE_ID: 5 +TIDB_ROW_ID_SHARDING_INFO: NULL +1 row in set (0.00 sec) +``` + +以下操作是等价的： + +{{< copyable "sql" >}} + +```sql +SELECT table_name FROM INFORMATION_SCHEMA.TABLES + WHERE table_schema = 'db_name' + [AND table_name LIKE 'wild'] +``` + +{{< copyable "sql" >}} + +```sql +SHOW TABLES + FROM db_name + [LIKE 'wild'] +``` + +表中的信息大部分定义自 MySQL，此外有两列是 TiDB 新增的： + +* `TIDB_TABLE_ID`：标识表的内部 ID，该 ID 在一个 TiDB 集群内部唯一。 +* `TIDB_ROW_ID_SHARDING_INFO`：标识表的 Sharding 类型，可能的值为： + - `"NOT_SHARDED"`：表未被 Shard。 + - `"NOT_SHARDED(PK_IS_HANDLE)"`：一个定义了整型主键的表未被 Shard。 + - `"PK_AUTO_RANDOM_BITS={bit_number}"`：一个定义了整型主键的表由于定义了 `AUTO_RANDOM` 而被 Shard。 + - `"SHARD_BITS={bit_number}"`：表使用 `SHARD_ROW_ID_BITS={bit_number}` 进行了 Shard。 + - NULL：表属于系统表或 View，无法被 Shard。 + +## TABLE_CONSTRAINTS 表 + +`TABLE_CONSTRAINTS` 表记录了表的约束信息。 + +{{< copyable "sql" >}} + +```sql +SELECT * FROM table_constraints WHERE constraint_type='UNIQUE'; +``` + +``` +*************************** 1. row *************************** +CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: name + TABLE_SCHEMA: mysql + TABLE_NAME: help_topic + CONSTRAINT_TYPE: UNIQUE +*************************** 2. row *************************** +CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: tbl + TABLE_SCHEMA: mysql + TABLE_NAME: stats_meta + CONSTRAINT_TYPE: UNIQUE +*************************** 3. row *************************** +CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: tbl + TABLE_SCHEMA: mysql + TABLE_NAME: stats_histograms + CONSTRAINT_TYPE: UNIQUE +*************************** 4. row *************************** +CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: tbl + TABLE_SCHEMA: mysql + TABLE_NAME: stats_buckets + CONSTRAINT_TYPE: UNIQUE +*************************** 5. row *************************** +CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: delete_range_index + TABLE_SCHEMA: mysql + TABLE_NAME: gc_delete_range + CONSTRAINT_TYPE: UNIQUE +*************************** 6. row *************************** +CONSTRAINT_CATALOG: def + CONSTRAINT_SCHEMA: mysql + CONSTRAINT_NAME: delete_range_done_index + TABLE_SCHEMA: mysql + TABLE_NAME: gc_delete_range_done + CONSTRAINT_TYPE: UNIQUE +6 rows in set (0.00 sec) +``` + +其中： + +* `CONSTRAINT_TYPE` 的取值可以是 `UNIQUE`，`PRIMARY KEY`，或者 `FOREIGN KEY`。 +* `UNIQUE` 和 `PRIMARY KEY` 信息与 `SHOW INDEX` 语句的执行结果类似。 + +## TIDB_HOT_REGIONS 表 + +`TIDB_HOT_REGIONS` 表提供了关于热点 REGION 的相关信息。 + +{{< copyable "sql" >}} + +```sql +desc TIDB_HOT_REGIONS; +``` + +``` ++----------------+---------------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++----------------+---------------------+------+-----+---------+-------+ +| TABLE_ID | bigint(21) unsigned | YES | | | | +| INDEX_ID | bigint(21) unsigned | YES | | | | +| DB_NAME | varchar(64) | YES | | | | +| TABLE_NAME | varchar(64) | YES | | | | +| INDEX_NAME | varchar(64) | YES | | | | +| TYPE | varchar(64) | YES | | | | +| MAX_HOT_DEGREE | bigint(21) unsigned | YES | | | | +| REGION_COUNT | bigint(21) unsigned | YES | | | | +| FLOW_BYTES | bigint(21) unsigned | YES | | | | ++----------------+---------------------+------+-----+---------+-------+ +``` + +## TIDB_INDEXES 表 + +`TIDB_INDEXES` 记录了所有表中的 INDEX 信息。 + +{{< copyable "sql" >}} + +```sql +desc TIDB_INDEXES; +``` + +``` ++---------------+---------------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++---------------+---------------------+------+-----+---------+-------+ +| TABLE_SCHEMA | varchar(64) | YES | | | | +| TABLE_NAME | varchar(64) | YES | | | | +| NON_UNIQUE | bigint(21) unsigned | YES | | | | +| KEY_NAME | varchar(64) | YES | | | | +| SEQ_IN_INDEX | bigint(21) unsigned | YES | | | | +| COLUMN_NAME | varchar(64) | YES | | | | +| SUB_PART | bigint(21) unsigned | YES | | | | +| INDEX_COMMENT | varchar(2048) | YES | | | | +| INDEX_ID | bigint(21) unsigned | YES | | | | ++---------------+---------------------+------+-----+---------+-------+ +``` + +## TIKV_REGION_PEERS 表 + +`TIKV_REGION_PEERS` 表提供了所有 REGION 的 peer 信息。 + +{{< copyable "sql" >}} + +```sql +desc TIKV_REGION_PEERS; +``` + +``` ++--------------+---------------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++--------------+---------------------+------+-----+---------+-------+ +| REGION_ID | bigint(21) unsigned | YES | | | | +| PEER_ID | bigint(21) unsigned | YES | | | | +| STORE_ID | bigint(21) unsigned | YES | | | | +| IS_LEARNER | tinyint(1) unsigned | YES | | | | +| IS_LEADER | tinyint(1) unsigned | YES | | | | +| STATUS | varchar(10) | YES | | | | +| DOWN_SECONDS | bigint(21) unsigned | YES | | | | ++--------------+---------------------+------+-----+---------+-------+ +``` + +## TIKV_REGION_STATUS 表 + +`TIKV_REGION_STATUS` 表提供了所有 REGION 的状态信息。 + +{{< copyable "sql" >}} + +```sql +desc TIKV_REGION_STATUS; +``` + +``` ++------------------+---------------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++------------------+---------------------+------+-----+---------+-------+ +| REGION_ID | bigint(21) unsigned | YES | | | | +| START_KEY | text | YES | | | | +| END_KEY | text | YES | | | | +| EPOCH_CONF_VER | bigint(21) unsigned | YES | | | | +| EPOCH_VERSION | bigint(21) unsigned | YES | | | | +| WRITTEN_BYTES | bigint(21) unsigned | YES | | | | +| READ_BYTES | bigint(21) unsigned | YES | | | | +| APPROXIMATE_SIZE | bigint(21) unsigned | YES | | | | +| APPROXIMATE_KEYS | bigint(21) unsigned | YES | | | | ++------------------+---------------------+------+-----+---------+-------+ +``` + +## TIKV_STORE_STATUS 表 + +`TIKV_STORE_STATUS` 表提供了所有 TiKV Store 的状态信息。 + +{{< copyable "sql" >}} + +```sql +desc TIKV_STORE_STATUS; +``` + +``` ++-------------------+---------------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------------+---------------------+------+-----+---------+-------+ +| STORE_ID | bigint(21) unsigned | YES | | | | +| ADDRESS | varchar(64) | YES | | | | +| STORE_STATE | bigint(21) unsigned | YES | | | | +| STORE_STATE_NAME | varchar(64) | YES | | | | +| LABEL | json unsigned | YES | | | | +| VERSION | varchar(64) | YES | | | | +| CAPACITY | varchar(64) | YES | | | | +| AVAILABLE | varchar(64) | YES | | | | +| LEADER_COUNT | bigint(21) unsigned | YES | | | | +| LEADER_WEIGHT | bigint(21) unsigned | YES | | | | +| LEADER_SCORE | bigint(21) unsigned | YES | | | | +| LEADER_SIZE | bigint(21) unsigned | YES | | | | +| REGION_COUNT | bigint(21) unsigned | YES | | | | +| REGION_WEIGHT | bigint(21) unsigned | YES | | | | +| REGION_SCORE | bigint(21) unsigned | YES | | | | +| REGION_SIZE | bigint(21) unsigned | YES | | | | +| START_TS | datetime unsigned | YES | | | | +| LAST_HEARTBEAT_TS | datetime unsigned | YES | | | | +| UPTIME | varchar(64) | YES | | | | ++-------------------+---------------------+------+-----+---------+-------+ +``` + +## USER_PRIVILEGES 表 + +`USER_PRIVILEGES` 表提供了关于全局权限的信息。该表的数据根据 `mysql.user` 系统表生成。 + +{{< copyable "sql" >}} + +```sql +desc USER_PRIVILEGES; +``` + +``` ++----------------|--------------|------|------|---------|-------+ +| Field | Type | Null | Key | Default | Extra | ++----------------|--------------|------|------|---------|-------+ +| GRANTEE | varchar(81) | YES | | NULL | | +| TABLE_CATALOG | varchar(512) | YES | | NULL | | +| PRIVILEGE_TYPE | varchar(64) | YES | | NULL | | +| IS_GRANTABLE | varchar(3) | YES | | NULL | | ++----------------|--------------|------|------|---------|-------+ +4 rows in set (0.00 sec) +``` + +## VIEWS 表 + +`VIEWS` 表提供了关于 SQL 视图的信息。 + +{{< copyable "sql" >}} + +```sql +create view test.v1 as select 1; +``` + +``` +Query OK, 0 rows affected (0.00 sec) +``` + +{{< copyable "sql" >}} + +```sql +select * from views; +``` + +``` +*************************** 1. row *************************** + TABLE_CATALOG: def + TABLE_SCHEMA: test + TABLE_NAME: v1 + VIEW_DEFINITION: select 1 + CHECK_OPTION: CASCADED + IS_UPDATABLE: NO + DEFINER: root@127.0.0.1 + SECURITY_TYPE: DEFINER +CHARACTER_SET_CLIENT: utf8 +COLLATION_CONNECTION: utf8_general_ci +1 row in set (0.00 sec) +``` + +## 不支持的 Information Schema 表 + +TiDB 包含以下 `INFORMATION_SCHEMA` 表，但仅会返回空行： + +* `COLUMN_PRIVILEGES` +* `EVENTS` +* `FILES` +* `GLOBAL_STATUS` +* `GLOBAL_VARIABLES` +* `OPTIMIZER_TRACE` +* `PARAMETERS` +* `PARTITIONS` +* `PLUGINS` +* `PROFILING` +* `REFERENTIAL_CONSTRAINTS` +* `ROUTINES` +* `SCHEMA_PRIVILEGES` +* `SESSION_STATUS` +* `TABLESPACES` +* `TABLE_PRIVILEGES` +* `TRIGGERS` diff --git a/dev/reference/system-databases/mysql.md b/reference/system-databases/mysql.md similarity index 100% rename from dev/reference/system-databases/mysql.md rename to reference/system-databases/mysql.md diff --git a/dev/reference/tidb-binlog/binlog-slave-client.md b/reference/tidb-binlog/binlog-slave-client.md similarity index 100% rename from dev/reference/tidb-binlog/binlog-slave-client.md rename to reference/tidb-binlog/binlog-slave-client.md diff --git a/reference/tidb-binlog/deploy.md b/reference/tidb-binlog/deploy.md new file mode 100644 index 000000000000..1e749150aeed --- /dev/null +++ b/reference/tidb-binlog/deploy.md @@ -0,0 +1,629 @@ +--- +title: TiDB Binlog 集群部署 +category: reference +aliases: ['/docs-cn/dev/how-to/deploy/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/deploy/'] +--- + +# TiDB Binlog 集群部署 + +## 服务器要求 + +Pump 和 Drainer 均可部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台上。在开发、测试和生产环境下，对服务器硬件配置的要求和建议如下： + +| 服务 | 部署数量 | CPU | 磁盘 | 内存 | +| :-------- | :-------- | :--------| :--------------- | :------ | +| Pump | 3 | 8核+ | SSD, 200 GB+ | 16G | +| Drainer | 1 | 8核+ | SAS, 100 GB+ （如果输出 binlog 为本地文件，磁盘大小视保留数据天数而定） | 16G | + +## 使用 TiDB Ansible 部署 TiDB Binlog + +### 第 1 步：下载 TiDB Ansible + +1. 以 TiDB 用户登录中控机并进入 `/home/tidb` 目录。以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 + + | TiDB Ansible 分支 | TiDB 版本 | 备注 | + | ---------------- | --------- | --- | + | master | master 版本 | 包含最新特性，每日更新。 | + +2. 使用以下命令从 GitHub [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应分支，默认的文件夹名称为 `tidb-ansible`。 + + - 下载 master 版本： + + {{< copyable "shell-regular" >}} + + ```bash + git clone https://github.com/pingcap/tidb-ansible.git + ``` + +### 第 2 步：部署 Pump + +1. 修改 tidb-ansible/inventory.ini 文件 + + 1. 设置 `enable_binlog = True`，表示 TiDB 集群开启 binlog。 + + ```ini + ## binlog trigger + enable_binlog = True + ``` + + 2. 为 `pump_servers` 主机组添加部署机器 IP。 + + ```ini + ## Binlog Part + [pump_servers] + 172.16.10.72 + 172.16.10.73 + 172.16.10.74 + ``` + + 默认 Pump 保留 7 天数据，如需修改可修改 `tidb-ansible/conf/pump.yml`（TiDB 3.0.0~3.0.2 版本中为 `tidb-ansible/conf/pump-cluster.yml`）文件中 `gc` 变量值，并取消注释。 + + {{< copyable "" >}} + + ```yaml + global: + # an integer value to control the expiry date of the binlog data, which indicates for how long (in days) the binlog data would be stored + # must be bigger than 0 + # gc: 7 + ``` + + 请确保部署目录有足够空间存储 binlog，详见[调整部署目录](/how-to/deploy/orchestrated/ansible.md#调整部署目录)，也可为 Pump 设置单独的部署目录。 + + ```ini + ## Binlog Part + [pump_servers] + pump1 ansible_host=172.16.10.72 deploy_dir=/data1/pump + pump2 ansible_host=172.16.10.73 deploy_dir=/data2/pump + pump3 ansible_host=172.16.10.74 deploy_dir=/data3/pump + ``` + +2. 部署并启动含 Pump 组件的 TiDB 集群 + + 参照上文配置完 `inventory.ini` 文件后，从以下两种方式中选择一种进行部署。 + + **方式一**：在已有的 TiDB 集群上增加 Pump 组件，需按以下步骤逐步进行。 + + 1. 部署 pump_servers 和 node_exporters + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml --tags=pump -l ${pump1_ip},${pump2_ip},[${alias1_name},${alias2_name}] + ``` + + > **注意：** + > + > 以上命令中，逗号后不要加空格，否则会报错。 + + 2. 启动 pump_servers + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml --tags=pump + ``` + + 3. 更新并重启 tidb_servers + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=tidb + ``` + + 4. 更新监控信息 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + + **方式二**：从零开始部署含 Pump 组件的 TiDB 集群 + + 使用 Ansible 部署 TiDB 集群，方法参考 [使用 TiDB Ansible 部署 TiDB 集群](/how-to/deploy/orchestrated/ansible.md)。 + +3. 查看 Pump 服务状态 + + 使用 binlogctl 查看 Pump 服务状态，pd-urls 参数请替换为集群 PD 地址，结果 State 为 online 表示 Pump 启动成功。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/tidb-ansible && + resources/bin/binlogctl -pd-urls=http://172.16.10.72:2379 -cmd pumps + ``` + + ``` + INFO[0000] pump: {NodeID: ip-172-16-10-72:8250, Addr: 172.16.10.72:8250, State: online, MaxCommitTS: 403051525690884099, UpdateTime: 2018-12-25 14:23:37 +0800 CST} + INFO[0000] pump: {NodeID: ip-172-16-10-73:8250, Addr: 172.16.10.73:8250, State: online, MaxCommitTS: 403051525703991299, UpdateTime: 2018-12-25 14:23:36 +0800 CST} + INFO[0000] pump: {NodeID: ip-172-16-10-74:8250, Addr: 172.16.10.74:8250, State: online, MaxCommitTS: 403051525717360643, UpdateTime: 2018-12-25 14:23:35 +0800 CST} + ``` + +### 第 3 步：部署 Drainer + +1. 获取 initial_commit_ts 的值 + + Drainer 初次启动时需要获取 initial_commit_ts 这个时间戳信息。 + + - 如果从最近的时间点开始同步，initial_commit_ts 使用 `-1` 即可。 + + - 如果下游为 MySQL 或 TiDB，为了保证数据的完整性，需要进行全量数据的备份与恢复。此时 initial_commit_ts 的值必须是全量备份的时间戳。 + + 如果使用 mydumper 进行全量备份，可以在导出目录中找到 metadata 文件，其中的 `Pos` 字段值即全量备份的时间戳。metadata 文件示例如下： + + ``` + Started dump at: 2019-12-30 13:25:41 + SHOW MASTER STATUS: + Log: tidb-binlog + Pos: 413580274257362947 + GTID: + + Finished dump at: 2019-12-30 13:25:41 + ``` + +2. 修改 `tidb-ansible/inventory.ini` 文件 + + 为 `drainer_servers` 主机组添加部署机器 IP，initial_commit_ts 请设置为获取的 initial_commit_ts，仅用于 Drainer 第一次启动。 + + - 以下游为 MySQL 为例，别名为 `drainer_mysql`。 + + ```ini + [drainer_servers] + drainer_mysql ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" + ``` + + - 以下游为 file 为例，别名为 `drainer_file`。 + + ```ini + [drainer_servers] + drainer_file ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" + ``` + +3. 修改配置文件 + + - 以下游为 MySQL 为例 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/tidb-ansible/conf && + cp drainer.toml drainer_mysql_drainer.toml && + vi drainer_mysql_drainer.toml + ``` + + > **注意：** + > + > 配置文件名命名规则为 `别名_drainer.toml`，否则部署时无法找到自定义配置文件。 + + db-type 设置为 "mysql"， 配置下游 MySQL 信息。 + + {{< copyable "" >}} + + ```toml + [syncer] + # downstream storage, equal to --dest-db-type + # Valid values are "mysql", "file", "tidb", "kafka". + db-type = "mysql" + + # the downstream MySQL protocol database + [syncer.to] + host = "172.16.10.72" + user = "root" + password = "123456" + port = 3306 + ``` + + - 以下游为增量备份文件为例 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/tidb-ansible/conf && + cp drainer.toml drainer_file_drainer.toml && + vi drainer_file_drainer.toml + ``` + + db-type 设置为 "file"。 + + {{< copyable "" >}} + + ```toml + [syncer] + # downstream storage, equal to --dest-db-type + # Valid values are "mysql", "file", "tidb", "kafka". + db-type = "file" + + # Uncomment this if you want to use "file" as "db-type". + [syncer.to] + # default data directory: "{{ deploy_dir }}/data.drainer" + dir = "data.drainer" + ``` + +4. 部署 Drainer + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy_drainer.yml + ``` + +5. 启动 Drainer + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start_drainer.yml + ``` + +## 使用 Binary 部署 TiDB Binlog + +### 下载官方 Binary + +{{< copyable "shell-regular" >}} + +```bash +wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && +wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 +``` + +检查文件完整性，返回 ok 则正确： + +{{< copyable "shell-regular" >}} + +```bash +sha256sum -c tidb-{version}-linux-amd64.sha256 +``` + +对于 v2.1.0 GA 及以上版本，Pump 和 Drainer 已经包含在 TiDB 的下载包中，其他版本需要单独下载 Pump 和 Drainer: + +{{< copyable "shell-regular" >}} + +```bash +wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.tar.gz && +wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.sha256 +``` + +检查文件完整性，返回 ok 则正确： + +{{< copyable "shell-regular" >}} + +```bash +sha256sum -c tidb-binlog-latest-linux-amd64.sha256 +``` + +### 使用样例 + +假设有三个 PD，一个 TiDB，另外有两台机器用于部署 Pump，一台机器用于部署 Drainer。各个节点信息如下： + +``` +TiDB="192.168.0.10" +PD1="192.168.0.16" +PD2="192.168.0.15" +PD3="192.168.0.14" +Pump="192.168.0.11" +Pump="192.168.0.12" +Drainer="192.168.0.13" +``` + +下面以此为例，说明 Pump/Drainer 的使用。 + +1. 使用 binary 部署 Pump + + - Pump 命令行参数说明（以在 “192.168.0.11” 上部署为例） + + ```bash + Usage of Pump: + -L string + 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") + -V + 打印版本信息 + -addr string + Pump 提供服务的 RPC 地址(-addr="192.168.0.11:8250") + -advertise-addr string + Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.11:8250") + -config string + 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置; + 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里的配置。 + -data-dir string + Pump 数据存储位置路径 + -gc int + Pump 只保留多少天以内的数据 (默认 7) + -heartbeat-interval int + Pump 向 PD 发送心跳间隔 (单位 秒) + -log-file string + log 文件路径 + -log-rotate string + log 文件切换频率，hour/day + -metrics-addr string + Prometheus Pushgateway 地址，不设置则禁止上报监控信息 + -metrics-interval int + 监控信息上报频率 (默认 15，单位 秒) + -node-id string + Pump 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 + -pd-urls string + PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") + -fake-binlog-interval int + Pump 节点生成 fake binlog 的频率 (默认 3，单位 秒) + ``` + + - Pump 配置文件（以在 “192.168.0.11” 上部署为例） + + ```toml + # Pump Configuration + + # Pump 绑定的地址 + addr = "192.168.0.11:8250" + + # Pump 对外提供服务的地址 + advertise-addr = "192.168.0.11:8250" + + # Pump 只保留多少天以内的数据 (默认 7) + gc = 7 + + # Pump 数据存储位置路径 + data-dir = "data.pump" + + # Pump 向 PD 发送心跳的间隔 (单位 秒) + heartbeat-interval = 2 + + # PD 集群节点的地址 (英文逗号分割，中间不加空格) + pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" + + # [security] + # 如无特殊安全设置需要，该部分一般都注解掉 + # 包含与集群连接的受信任 SSL CA 列表的文件路径 + # ssl-ca = "/path/to/ca.pem" + # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 + # ssl-cert = "/path/to/drainer.pem" + # 包含与集群链接的 PEM 形式的 X509 key 的路径 + # ssl-key = "/path/to/drainer-key.pem" + + # [storage] + # 设置为 true（默认值）来保证可靠性，确保 binlog 数据刷新到磁盘 + # sync-log = true + + # 当可用磁盘容量小于该设置值时，Pump 将停止写入数据 + # 42 MB -> 42000000, 42 mib -> 44040192 + # default: 10 gib + # stop-write-at-available-space = "10 gib" + + # Pump 内嵌的 LSM DB 设置，除非对该部分很了解，否则一般注解掉 + # [storage.kv] + # block-cache-capacity = 8388608 + # block-restart-interval = 16 + # block-size = 4096 + # compaction-L0-trigger = 8 + # compaction-table-size = 67108864 + # compaction-total-size = 536870912 + # compaction-total-size-multiplier = 8.0 + # write-buffer = 67108864 + # write-L0-pause-trigger = 24 + # write-L0-slowdown-trigger = 17 + ``` + + - 启动示例 + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/pump -config pump.toml + ``` + + 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 + +2. 使用 binary 部署 Drainer + + - Drainer 命令行参数说明（以在 “192.168.0.13” 上部署为例） + + ```bash + Usage of Drainer + -L string + 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") + -V + 打印版本信息 + -addr string + Drainer 提供服务的地址(-addr="192.168.0.13:8249") + -c int + 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) + -cache-binlog-count int + 缓存中的 binlog 数目限制（默认 8） + 如果上游的单个 binlog 较大导致 Drainer 出现 OOM 时，可尝试调小该值减少内存使用 + -config string + 配置文件路径，Drainer 会首先读取配置文件的配置； + 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的配置 + -data-dir string + Drainer 数据存储位置路径 (默认 "data.drainer") + -dest-db-type string + Drainer 下游服务类型 (默认为 mysql，支持 tidb、kafka、file) + -detect-interval int + 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) + -disable-detect + 是否禁用冲突监测 + -disable-dispatch + 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则每个 binlog + 按顺序依次还原成单个事务进行同步（下游服务类型为 MySQL，该项设置为 False） + -ignore-schemas string + db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， + 不支持对 ignore schemas 的 table 进行 rename DDL 操作 + -initial-commit-ts（默认为 `-1`） + 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 + 该参数值为 `-1` 时，Drainer 会自动从 PD 获取一个最新的时间戳 + -log-file string + log 文件路径 + -log-rotate string + log 文件切换频率，hour/day + -metrics-addr string + Prometheus Pushgateway 地址，不设置则禁止上报监控信息 + -metrics-interval int + 监控信息上报频率（默认 15，单位：秒） + -node-id string + drainer 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 + -pd-urls string + PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") + -safe-mode + 是否开启安全模式使得下游 MySQL/TiDB 可被重复写入 + 即将 insert 语句换为 replace 语句，将 update 语句拆分为 delete + replace 语句 + -txn-batch int + 输出到下游数据库一个事务的 SQL 数量（默认 1） + ``` + + - Drainer 配置文件（以在 “192.168.0.13” 上部署为例） + + ```toml + # Drainer Configuration. + + # Drainer 提供服务的地址("192.168.0.13:8249") + addr = "192.168.0.13:8249" + + # Drainer 对外提供服务的地址 + advertise-addr = "192.168.0.13:8249" + + # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) + detect-interval = 10 + + # Drainer 数据存储位置路径 (默认 "data.drainer") + data-dir = "data.drainer" + + # PD 集群节点的地址 (英文逗号分割，中间不加空格) + pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" + + # log 文件路径 + log-file = "drainer.log" + + # Drainer 从 Pump 获取 binlog 时对数据进行压缩，值可以为 "gzip"，如果不配置则不进行压缩 + # compressor = "gzip" + + # [security] + # 如无特殊安全设置需要，该部分一般都注解掉 + # 包含与集群连接的受信任 SSL CA 列表的文件路径 + # ssl-ca = "/path/to/ca.pem" + # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 + # ssl-cert = "/path/to/pump.pem" + # 包含与集群链接的 PEM 形式的 X509 key 的路径 + # ssl-key = "/path/to/pump-key.pem" + + # Syncer Configuration + [syncer] + # 如果设置了该项，会使用该 sql-mode 解析 DDL 语句，此时如果下游是 MySQL 或 TiDB 则 + # 下游的 sql-mode 也会被设置为该值 + # sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" + + # 输出到下游数据库一个事务的 SQL 语句数量 (默认 20) + txn-batch = 20 + + # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (默认 16) + worker-count = 16 + + # 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则按照每个 binlog + # 顺序依次还原成单个事务进行同步（下游服务类型为 MySQL, 该项设置为 False） + disable-dispatch = false + + # safe mode 会使写下游 MySQL/TiDB 可被重复写入 + # 会用 replace 替换 insert 语句，用 delete + replace 替换 update 语句 + safe-mode = false + + # Drainer 下游服务类型（默认为 mysql） + # 参数有效值为 "mysql"，"tidb"，"file"，"kafka" + db-type = "mysql" + + # 事务的 commit ts 若在该列表中，则该事务将被过滤，不会同步至下游 + ignore-txn-commit-ts = [] + + # db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， + # 不支持对 ignore schemas 的 table 进行 rename DDL 操作 + ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" + + # replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。 + # 以 '~' 开始声明使用正则表达式 + + # replicate-do-db = ["~^b.*","s1"] + + # [syncer.relay] + # 保存 relay log 的目录，空值表示不开启。 + # 只有下游是 TiDB 或 MySQL 时该配置才生效。 + # log-dir = "" + # 每个文件的大小上限 + # max-file-size = 10485760 + + # [[syncer.replicate-do-table]] + # db-name ="test" + # tbl-name = "log" + + # [[syncer.replicate-do-table]] + # db-name ="test" + # tbl-name = "~^a.*" + + # 忽略同步某些表 + # [[syncer.ignore-table]] + # db-name = "test" + # tbl-name = "log" + + # db-type 设置为 mysql 时，下游数据库服务器参数 + [syncer.to] + host = "192.168.0.13" + user = "root" + password = "" + # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 + # encrypted_password 非空时 password 会被忽略 + encrypted_password = "" + port = 3306 + + [syncer.to.checkpoint] + # 当 checkpoint type 是 mysql 或 tidb 时可以开启该选项，以改变保存 checkpoint 的数据库 + # schema = "tidb_binlog" + # 目前只支持 mysql 或者 tidb 类型。可以去掉注释来控制 checkpoint 保存的位置。 + # db-type 默认的 checkpoint 保存方式是: + # mysql/tidb -> 对应的下游 mysql/tidb + # file/kafka -> file in `data-dir` + # type = "mysql" + # host = "127.0.0.1" + # user = "root" + # password = "" + # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 + # encrypted_password 非空时 password 会被忽略 + # encrypted_password = "" + # port = 3306 + + + # db-type 设置为 file 时，存放 binlog 文件的目录 + # [syncer.to] + # dir = "data.drainer" + + # db-type 设置为 kafka 时，Kafka 相关配置 + # [syncer.to] + # kafka-addrs 和 zookeeper-addrs 只需要一个，两者都有时程序会优先用 zookeeper 中的 kafka 地址 + # zookeeper-addrs = "127.0.0.1:2181" + # kafka-addrs = "127.0.0.1:9092" + # kafka-version = "0.8.2.0" + # kafka-max-messages = 1024 + + # 保存 binlog 数据的 Kafka 集群的 topic 名称，默认值为 _obinlog + # 如果运行多个 Drainer 同步数据到同一个 Kafka 集群，每个 Drainer 的 topic-name 需要设置不同的名称 + # topic-name = "" + ``` + + - 启动示例 + + > **注意：** + > + > 如果下游为 MySQL/TiDB，为了保证数据的完整性，在 Drainer 初次启动前需要获取 `initial-commit-ts` 的值，并进行全量数据的备份与恢复。详细信息参见[部署 Drainer](#第-3-步部署-drainer)。 + + 初次启动时使用参数 `initial-commit-ts`， 命令如下： + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/drainer -config drainer.toml -initial-commit-ts {initial-commit-ts} + ``` + + 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 + +> **注意：** +> +> - 在运行 TiDB 时，需要保证至少一个 Pump 正常运行。 +> - 通过给 TiDB 增加启动参数 `enable-binlog` 来开启 binlog 服务。尽量保证同一集群的所有 TiDB 都开启了 binlog 服务，否则在同步数据时可能会导致上下游数据不一致。如果要临时运行一个不开启 binlog 服务的 TiDB 实例，需要在 TiDB 的配置文件中设置 `run_ddl= false`。 +> - Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 +> - 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取**快照时间戳**，然后导入全量备份，最后启动 Drainer 从对应的快照时间戳开始同步增量数据。 +> - 下游使用 MySQL 或 TiDB 时应当保证上下游数据库的 sql_mode 具有一致性，即下游数据库同步每条 SQL 语句时的 sql_mode 应当与上游数据库执行该条 SQL 语句时的 sql_mode 保持一致。可以在上下游分别执行 `select @@sql_mode;` 进行查询和比对。 +> - 如果存在上游 TiDB 能运行但下游 MySQL 不支持的 DDL 语句时（例如下游 MySQL 使用 InnoDB 引擎时同步语句 `CREATE TABLE t1(a INT) ROW_FORMAT=FIXED;`），Drainer 也会同步失败，此时可以在 Drainer 配置中跳过该事务，同时在下游手动执行兼容的语句，详见[跳过事务](/reference/tidb-binlog/faq.md#同步时出现上游数据库支持但是下游数据库执行会出错的-ddl应该怎么办)。 diff --git a/reference/tidb-binlog/faq.md b/reference/tidb-binlog/faq.md new file mode 100644 index 000000000000..543a7ef1ff25 --- /dev/null +++ b/reference/tidb-binlog/faq.md @@ -0,0 +1,210 @@ +--- +title: TiDB Binlog 常见问题 +category: FAQ +aliases: ['/docs-cn/dev/faq/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/faq/'] +--- + +# TiDB Binlog 常见问题 + +本文介绍 TiDB Binlog 使用过程中的常见问题及解决方案。 + +## 开启 binog 对 TiDB 的性能有何影响？ + +- 对于查询无影响。 + +- 对于有写入或更新数据的事务有一点性能影响。延迟上，在 Prewrite 阶段要并发写一条 p-binlog 成功后才可以提交事务，一般写 binlog 比 KV Prewrite 快，所以不会增加延迟。可以在 Pump 的监控面板看到写 binlog 的响应时间。 + +## Drainer 同步下游 TiDB/MySQL 的帐号需要哪些权限？ + +Drainer 同步帐号需要有如下权限： + +* Insert +* Update +* Delete +* Create +* Drop +* Alter +* Execute +* Index +* Select + +## Pump 磁盘快满了怎么办？ + +确认 GC 正常： + +- 确认 pump 监控面板 **gc_tso** 时间是否与配置一致。 + +如 gc 正常以下调整可以降低单个 pump 需要的空间大小： + +- 调整 pump **GC** 参数减少保留数据天数。 +- 添加 pump 结点。 + +## Drainer 同步中断怎么办？ + +使用以下 binlogctl 命令查看 Pump 状态是否正常，以及是否全部非 `offline` 状态的 Pump 都在正常运行。 + +{{< copyable "shell-regular" >}} + +```bash +binlogctl -cmd pumps +``` + +查看 Drainer 监控与日志是否有对应报错，根据具体问题进行处理。 + +## Drainer 同步下游 TiDB/MySQL 慢怎么办？ + +特别关注以下监控项： + +- 通过 Drainer 监控 **drainer event**，可以看到 Drainer 当前每秒同步 Insert/Update/Delete 事件到下游的速度。 +- 通过 Drainer 监控 **sql query time**，可以看到 Drainer 在下游执行 SQL 的响应时间。 + +同步慢的可能原因与解决方案： + +- 同步的数据库包含没有主键或者唯一索引的表，需要给表加上主键。 +- Drainer 与下游之间延迟大，可以调大 Drainer `worker-count` 参数（跨机房同步建议将 Drainer 部署在下游）。 +- 下游负载不高，可以尝试调大 Drainer `worker-count` 参数。 + +## 假如有一个 Pump crash 了会怎样？ + +Drainer 会因为获取不到这个 Pump 的数据没法同步数据到下游。如果这个 Pump 能恢复，Drainer 就能恢复同步。 + +如果 Pump 没法恢复，可采用以下方式进行处理： + +1. 使用 [binlogctl 将该 Pump 状态修改为 `offline`](/reference/tidb-binlog/maintain.md)（丢失这个 Pump 的数据） +2. Drainer 获取到的数据会丢失这个 Pump 上的数据，下游跟上游数据会不一致，需要重新做全量 + 增量同步。具体步骤如下： + 1. 停止当前 Drainer。 + 2. 上游做全量备份。 + 3. 清理掉下游数据，包括 checkpoint 表 `tidb_binlog.checkpoint`。 + 4. 使用上游的全量备份恢复下游数据。 + 5. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 + +## 什么是 checkpoint？ + +Checkpoint 记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 +Drainer 日志 `["write save point"] [ts=411222863322546177]` 表示保存对应时间戳的 checkpoint。 + +下游类型不同，checkpoint 的保存方式也不同： + +- 下游 MySQL/TiDB 保存在 `tidb_binlog.checkpoint` 表。 +- 下游 kafka/file 保存在对应配置目录里的文件。 + +因为 kafka/file 的数据内容包含了 commit-ts，所以如果 checkpoint 丢失，可以消费下游最新的一条数据看写到下游数据的最新 commit-ts。 + +Drainer 启动的时候会去读取 checkpoint，如果读取不到，就会使用配置的 `initial-commit-ts` 做为初次启动开始的同步时间点。 + +## Drainer 机器发生故障，下游数据还在，如何在新机器上重新部署 Drainer？ + +如果下游数据还在，只要保证能从对应 checkpoint 接着同步即可。 + +假如 checkpoint 还在，可采用以下方式进行处理： + +1. 部署新的 Drainer 并启动即可（参考 checkpoint 介绍，Drainer 可以读取 checkpoint 接着同步）。 +2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/reference/tidb-binlog/maintain.md)。 + +假如 checkpoint 不在，可以如下处理： + +1. 获取之前 Drainer 的 checkpoint `commit-ts`，做为新部署 Drainer 的 `initial-commit-ts` 配置来部署新的 Drainer。 +2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/reference/tidb-binlog/maintain.md)。 + +## 如何用全量 + binlog 备份文件来恢复一个集群？ + +1. 清理集群数据并使用全部备份恢复数据。 +2. 使用 reparo 设置 `start-tso` = {全量备份文件快照时间戳+1}，`end-ts` = 0（或者指定时间点），恢复到备份文件最新的数据。 + +## 主从同步开启 `ignore-error` 触发 critical error 后如何重新部署？ + +TiDB 配置开启 `ignore-error` 写 binlog 失败后触发 critical error 告警，后续都不会再写 binlog，所以会有 binlog 数据丢失。如果要恢复同步，需要如下处理： + +1. 停止当前 Drainer。 +2. 重启触发 critical error 的 `tidb-server` 实例重新开始写 binlog（触发 critical error 后不会再写 binlog 到 pump）。 +3. 上游做全量备份。 +4. 清理掉下游数据包括 checkpoint 表 `tidb_binlog.checkpoint`。 +5. 使用上游的全量备份恢复下游。 +6. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 + +## 同步时出现上游数据库支持但是下游数据库执行会出错的 DDL，应该怎么办？ + +1. 查看 drainer.log 日志，查找 `exec failed` 找到 Drainer 退出前最后一条执行失败的 DDL。 +2. 将 DDL 改为下游兼容支持的版本，在下游数据库中手动执行。 +3. 查看 drainer.log 日志，查找执行失败的 DDL 语句，可以查询到该 DDL 的 commit-ts。 +4. 编辑 `drainer.toml` 配置文件，在 `ignore-txn-commit-ts` 项中添加该 commit-ts，重启 Drainer。 + +在绝大部分情况下，TiDB 和 MySQL 的语句都是兼容的。用户需要注意的是上下游的 `sql_mode` 应当保持一致。 + +## 在什么情况下暂停和下线 Pump/Drainer？ + +首先需要通过以下内容来了解 Pump/Drainer 的状态定义和启动、退出的流程。 + +暂停主要针对临时需要停止服务的场景，例如： + +- 版本升级：停止进程后使用新的 binary 启动服务。 +- 服务器维护：需要对服务器进行停机维护。退出进程，等维护完成后重启服务。 + +下线主要针对永久（或长时间）不再使用该服务的场景，例如： + +- Pump 缩容：不再需要那么多 Pump 服务了，所以下线部分服务。 +- 同步任务取消：不再需要将数据同步到某个下游，所以下线对应的 Drainer。 +- 服务器迁移：需要将服务迁移到其他服务器。下线服务，在新的服务器上重新部署。 + +## 可以通过哪些方式暂停 Pump/Drainer？ + +- 直接 kill 进程。 + + >**注意：** + > + > 不能使用 `kill -9` 命令，否则 Pump/Drainer 无法对信号进行处理。 + +- 如果 Pump/Drainer 运行在前台，则可以通过按下 Ctrl+C 来暂停。 +- 使用 binlogctl 的 `pause-pump` 或 `pause-drainer` 命令。 + +## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来下线 Pump/Drainer 服务吗？ + +不可以。使用 `update-pump`/`update-drainer` 命令会直接修改 PD 中保存的状态信息，并且不会通知 Pump/Drainer 做相应的操作。使用不当时，可能会干扰数据同步，某些情况下还可能会造成**数据不一致**的严重后果。例如： + +- 当 Pump 正常运行或者处于暂停状态时，如果使用 `update-pump` 将该 Pump 设置为 `offline`，那么 Drainer 会放弃获取处于 `offline` 状态的 Pump 的 binlog 数据，导致该 Pump 最新的 binlog 数据没有同步到 Drainer，造成上下游数据不一致。 +- 当 Drainer 正常运行时，使用 `update-drainer` 命令将该 Drainer 设置为 `offline`。如果这时启动一个 Pump 节点，Pump 只会通知 `online` 状态的 Drainer，导致该 Drainer 没有及时获取到该 Pump 的 binlog 数据，造成上下游数据不一致。 + +## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来暂停 Pump/Drainer 服务吗？ + +不可以。`update-pump`/`update-drainer` 命令直接修改 PD 中保存的状态信息。执行这个命令并不会通知 Pump/Drainer 做相应的操作，**而且使用不当会使数据同步中断，甚至造成数据丢失。** + +## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `paused`？ + +在某些异常情况下，Pump 没有正确维护自己的状态，实际上状态应该为 `paused`。这时可以使用 `update-pump` 对状态进行修正，例如： + +- Pump 异常退出（可能由 panic 或者误操作执行 `kill -9` 命令直接 kill 掉进程导致），Pump 保存在 PD 中的状态仍然为 `online`。如果暂时不需要重启 Pump 恢复服务，可以使用 `update-pump` 把该 Pump 状态设置为 `paused`，避免对 TiDB 写 binlog 和 Drainer 获取 binlog 造成干扰。 + +## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `paused`？ + +在某些异常情况下，Drainer 没有正确维护自己的状态，，对数据同步造成了影响，实际上状态应该为 `paused`。这时可以使用 `update-drainer` 对状态进行修正，例如： + +- Drainer 异常退出（出现 panic 直接退出进程，或者误操作执行 `kill -9` 命令直接 kill 掉进程），Drainer 保存在 PD 中的状态仍然为 `online`。当 Pump 启动时无法正常通知该 Drainer（报错 `notify drainer ...`），导致 Pump 无法正常运行。这个时候可以使用 `update-drainer` 将 Drainer 状态更新为 `paused`，再启动 Pump。 + +## 可以通过哪些方式下线 Pump/Drainer？ + +目前只可以使用 binlogctl 的 `offline-pump` 和 `offline-drainer` 命令来下线 Pump 和 Drainer。 + +## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `offline`? + +> **警告：** +> +> 仅在可以容忍 binlog **数据丢失、上下游数据不一致**或者确认不再需要使用该 Pump 存储的 binlog 数据的情况下，才能使用 `update-pump` 修改 Pump 状态为 `offline`。 + +可以使用 `update-pump` 修改 Pump 状态为 `offline` 的情况有： + +- 在某些情况下，Pump 异常退出进程，且无法恢复服务，同步就会中断。如果希望恢复同步且可以容忍部分 binlog 数据丢失，可以使用 `update-pump` 命令将该 Pump 状态设置为 `offline`，则 Drainer 会放弃拉取该 Pump 的 binlog 然后继续同步数据。 +- 有从历史任务遗留下来且不再使用的 Pump 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-pump` 将该 Pump 设置为 `offline`。 + +在其他情况下一定要使用 `offline-pump` 命令让 Pump 走正常的下线处理流程。 + +## Pump 进程已经退出，且状态为 `paused`，现在不想使用这个 Pump 节点了，能否用 binlogctl 的 `update-pump` 命令设置节点状态为 `offline`？ + +Pump 以 `paused` 状态退出进程时，不保证所有 binlog 数据被下游 Drainer 消费。所以这样做会有上下游数据不一致的风险。正确的做法是重新启动 Pump，然后使用 `offline-pump` 下线该 Pump。 + +## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `offline`？ + +- 有从历史任务遗留下来且不再使用的 Drainer 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-drainer` 将该 Drainer 设置为 `offline`。 + +## 可以使用 `change pump`、`change drainer` 等 SQL 操作来暂停或者下线 Pump/Drainer 服务吗？ + +目前还不支持。这种 SQL 操作会直接修改 PD 中保存的状态，在功能上等同于使用 binlogctl 的 `update-pump`、`update-drainer` 命令。如果需要暂停或者下线，仍然要使用 binlogctl。 diff --git a/dev/reference/tidb-binlog/glossary.md b/reference/tidb-binlog/glossary.md similarity index 100% rename from dev/reference/tidb-binlog/glossary.md rename to reference/tidb-binlog/glossary.md diff --git a/dev/reference/tidb-binlog/maintain.md b/reference/tidb-binlog/maintain.md similarity index 100% rename from dev/reference/tidb-binlog/maintain.md rename to reference/tidb-binlog/maintain.md diff --git a/dev/reference/tidb-binlog/monitor.md b/reference/tidb-binlog/monitor.md similarity index 100% rename from dev/reference/tidb-binlog/monitor.md rename to reference/tidb-binlog/monitor.md diff --git a/reference/tidb-binlog/overview.md b/reference/tidb-binlog/overview.md new file mode 100644 index 000000000000..e978f4d15bea --- /dev/null +++ b/reference/tidb-binlog/overview.md @@ -0,0 +1,60 @@ +--- +title: TiDB Binlog 简介 +category: reference +aliases: ['/docs-cn/dev/reference/tidb-binlog-overview/','/docs-cn/dev/reference/tools/tidb-binlog/overview/'] +--- + +# TiDB Binlog 简介 + +TiDB Binlog 是一个用于收集 TiDB 的 binlog，并提供准实时备份和同步功能的商业工具。 + +TiDB Binlog 支持以下功能场景： + +- **数据同步**：同步 TiDB 集群数据到其他数据库 +- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 + +## TiDB Binlog 整体架构 + +![TiDB Binlog 架构](/media/tidb_binlog_cluster_architecture.png) + +TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl 工具： + +### Pump + +[Pump](https://github.com/pingcap/tidb-binlog/blob/master/pump) 用于实时记录 TiDB 产生的 Binlog，并将 Binlog 按照事务的提交时间进行排序，再提供给 Drainer 进行消费。 + +### Drainer + +[Drainer](https://github.com/pingcap/tidb-binlog/tree/master/drainer) 从各个 Pump 中收集 Binlog 进行归并，再将 Binlog 转化成 SQL 或者指定格式的数据，最终同步到下游。 + +### binlogctl 工具 + +[`binlogctl`](https://github.com/pingcap/tidb-binlog/tree/master/binlogctl) 是一个 TiDB Binlog 配套的运维工具，具有如下功能： + +* 获取 TiDB 集群当前的 TSO +* 查看 Pump/Drainer 状态 +* 修改 Pump/Drainer 状态 +* 暂停/下线 Pump/Drainer + +## 主要特性 + +* 多个 Pump 形成一个集群，可以水平扩容。 +* TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。 +* Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。 +* Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。 +* Drainer 支持 [relay log](/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。 + +## 注意事项 + +* 需要使用 TiDB v2.0.8-binlog、v2.1.0-rc.5 及以上版本，否则不兼容该版本的 TiDB Binlog。 + +* Drainer 支持将 Binlog 同步到 MySQL、TiDB、Kafka 或者本地文件。如果需要将 Binlog 同步到其他 Drainer 不支持的类型的系统中，可以设置 Drainer 将 Binlog 同步到 Kafka，然后根据 binlog slave protocol 进行定制处理，参考 [binlog slave client 用户文档](/reference/tidb-binlog/binlog-slave-client.md)。 + +* 如果 TiDB Binlog 用于增量恢复，可以设置配置项 `db-type="file"`，Drainer 会将 binlog 转化为指定的 [proto buffer 格式](https://github.com/pingcap/tidb-binlog/blob/master/proto/binlog.proto)的数据，再写入到本地文件中。这样就可以使用 [Reparo](/reference/tidb-binlog/reparo.md) 恢复增量数据。 + + 关于 `db-type` 的取值，应注意： + + - 如果 TiDB 版本 < 2.1.9，则 `db-type="pb"`。 + - 如果 TiDB 版本 > = 2.1.9，则 `db-type="file"` 或 `db-type="pb"`。 + +* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。 diff --git a/dev/reference/tidb-binlog/relay-log.md b/reference/tidb-binlog/relay-log.md similarity index 100% rename from dev/reference/tidb-binlog/relay-log.md rename to reference/tidb-binlog/relay-log.md diff --git a/dev/reference/tidb-binlog/reparo.md b/reference/tidb-binlog/reparo.md similarity index 100% rename from dev/reference/tidb-binlog/reparo.md rename to reference/tidb-binlog/reparo.md diff --git a/dev/reference/tidb-binlog/tidb-binlog-kafka.md b/reference/tidb-binlog/tidb-binlog-kafka.md similarity index 100% rename from dev/reference/tidb-binlog/tidb-binlog-kafka.md rename to reference/tidb-binlog/tidb-binlog-kafka.md diff --git a/reference/tidb-binlog/tidb-binlog-local.md b/reference/tidb-binlog/tidb-binlog-local.md new file mode 100644 index 000000000000..780b54c177b4 --- /dev/null +++ b/reference/tidb-binlog/tidb-binlog-local.md @@ -0,0 +1,287 @@ +--- +title: TiDB Binlog Local 部署方案 +category: reference +aliases: ['/docs-cn/dev/reference/tools/tidb-binlog/tidb-binlog-local/'] +--- + +# TiDB Binlog Local 部署方案 + +## TiDB Binlog Local 简介 + +TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 + +TiDB Binlog 支持以下功能场景: + +* **数据同步**：同步 TiDB 集群数据到其他数据库。 +* **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复。 + +## TiDB Binlog Local 架构 + +下图为 TiDB Binlog Local的整体架构。 + +![TiDB Binlog 架构](/media/architecture.jpeg) + +TiDB Binlog Local 主要分为两个组件： + +- **Pump** 是一个守护进程，在每个 TiDB 的主机上后台运行。他的主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入磁盘文件 + +- **Drainer** 从各个 Pump 节点收集 Binlog，并按照在 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件 + +## TiDB Binlog Local 安装 + +### TiDB Binlog Local 下载 + +TiDB Binlog 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/reference/tools/download.md)。 + +### TiDB Binlog Local 部署 + +#### 注意 + +* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 方式的输出 binlog。 +* 手动部署时， 启动顺序为： Pump > TiDB，停止顺序为 TiDB > Pump + + 我们设置 TiDB 启动参数 binlog-socket 为对应的 Pump 的参数 socket 所指定的 unix socket 文件路径，最终部署结构如下图所示： + + ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) + +* drainer 不支持对 ignore schemas（在过滤列表中的 schemas） 的 table 进行 rename DDL 操作 + +* 在已有的 TiDB 集群中启动 drainer，一般需要全量备份 并且获取 savepoint，然后导入全量备份，最后启动 drainer 从 savepoint 开始同步。 + + 为了保证数据的完整性，在 pump 运行 10 分钟左右后按顺序进行下面的操作 + + * 以 gen-savepoint model 运行 drainer 生成 drainer savepint 文件，`bin/drainer -gen-savepoint --data-dir= ${drainer_savepoint_dir} --pd-urls=${pd_urls}` + * 全量备份，例如 Mydumper 备份 tidb + * 全量导入备份到目标系统 + * 设置 savepoint 文件路径，然后启动 drainer，`bin/drainer --config=conf/drainer.toml --data-dir=${drainer_savepoint_dir}` + +* drainer 输出的 pb, 需要在配置文件设置下面的参数 + + ```toml + [syncer] + db-type = "pb" + disable-dispatch = true + + [syncer.to] + dir = "/path/pb-dir" + ``` + +#### 使用 TiDB Ansible 部署 Pump (推荐) + +* 搭建全新的 TiDB Cluster，启动顺序 pd-server -> tikv-server -> pump -> tidb-server -> drainer + * 修改 tidb-ansible inventory.ini 文件 + * enable_binlog = True + * 执行 ansible-playbook deploy.yml + * 执行 ansible-playbook start.yml + * drainer 目前需要手动部署 + +* 对已有的 TiDB Cluster 部署 binlog + * 修改 tidb-ansible inventory.ini 文件 + * enable_binlog = True + * 执行 ansible-playbook rolling_update.yml --tags=tidb + * drainer 目前需要手动部署 + +#### 使用 Binary 部署 Pump + +1. PUMP 命令行参数说明 + + ``` + Usage of pump: + -L string + 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") + -V + 打印版本信息 + -addr string + pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") + -advertise-addr string + pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") + -config string + 配置文件路径,如果你指定了配置文件，pump 会首先读取配置文件的配置 + 如果对应的配置在命令行参数里面也存在，pump 就会使用命令行参数的配置来覆盖配置文件里面的 + -data-dir string + pump 数据存储位置路径 + -gc int + 日志最大保留天数 (默认 7)， 设置为 0 可永久保存 + -heartbeat-interval uint + pump 向 pd 发送心跳间隔 (单位 秒) + -log-file string + log 文件路径 + -log-rotate string + log 文件切换频率, hour/day + -metrics-addr string + prometheus Pushgateway 地址，不设置则禁止上报监控信息 + -metrics-interval int + 监控信息上报频率 (默认 15，单位 秒) + -pd-urls string + pd 集群节点的地址 (默认 "http://127.0.0.1:2379") + -socket string + unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) + ``` + + 2. PUMP 配置文件 + + ```toml + # pump Configuration. + # pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") + addr = "127.0.0.1:8250" + # pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") + advertise-addr = "" + # binlog 最大保留天数 (默认 7)， 设置为 0 可永久保存 + gc = 7 + # pump 数据存储位置路径 + data-dir = "data.pump" + # pump 向 pd 发送心跳间隔 (单位 秒) + heartbeat-interval = 3 + # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") + pd-urls = "http://127.0.0.1:2379" + # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) + socket = "unix:///tmp/pump.sock" + ``` + +3. 启动示例 + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/pump -config pump.toml + ``` + +#### 使用 Binary 部署 Drainer + +1. Drainer 命令行参数说明 + + ``` + Usage of drainer: + -L string + 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") + -V + 打印版本信息 + -addr string + drainer 提供服务的地址(默认 "127.0.0.1:8249") + -c int + 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) + -config string + 配置文件路径, drainer 会首先读取配置文件的配置 + 如果对应的配置在命令行参数里面也存在，drainer 就会使用命令行参数的配置来覆盖配置文件里面的 + -data-dir string + drainer 数据存储位置路径 (默认 "data.drainer") + -dest-db-type string + drainer 下游服务类型 (默认为 mysql) + -detect-interval int + 向 pd 查询在线 Pump 的时间间隔 (默认 10，单位 秒) + -disable-dispatch + 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog + 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) + -gen-savepoint + 如果设置为 true, 则只生成 drainer 的 savepoint meta 文件, 可以配合 Mydumper 使用 + -ignore-schemas string + db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), + 不支持对 ignore schemas 的 table 进行 rename DDL 操作 + -log-file string + log 文件路径 + -log-rotate string + log 文件切换频率, hour/day + -metrics-addr string + Prometheus Pushgateway 地址，不设置则禁止上报监控信息 + -metrics-interval int + 监控信息上报频率 (默认 15，单位 秒) + -pd-urls string + pd 集群节点的地址 (默认 "http://127.0.0.1:2379") + -txn-batch int + 输出到下游数据库一个事务的 sql 数量 (default 1) + ``` + +2. Drainer 配置文件 + + ```toml + # drainer Configuration. + + # drainer 提供服务的地址(默认 "127.0.0.1:8249") + addr = "127.0.0.1:8249" + + # 向 pd 查询在线 pump 的时间间隔 (默认 10，单位 秒) + detect-interval = 10 + + # drainer 数据存储位置路径 (默认 "data.drainer") + data-dir = "data.drainer" + + # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") + pd-urls = "http://127.0.0.1:2379" + + # log 文件路径 + log-file = "drainer.log" + + # Syncer Configuration. + [syncer] + + ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), + ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 + ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" + + # 输出到下游数据库一个事务的 sql 数量 (default 1) + txn-batch = 1 + + # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) + worker-count = 1 + + # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog + # 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) + disable-dispatch = false + + # drainer 下游服务类型 (默认为 mysql) + # 参数有效值为 "mysql", "pb" + db-type = "mysql" + + # replicate-do-db priority over replicate-do-table if have same db name + # and we support regex expression , + # 以 '~' 开始声明使用正则表达式 + + #replicate-do-db = ["~^b.*","s1"] + + #[[syncer.replicate-do-table]] + #db-name ="test" + #tbl-name = "log" + + #[[syncer.replicate-do-table]] + #db-name ="test" + #tbl-name = "~^a.*" + + # db-type 设置为 mysql 时，下游数据库服务器参数 + [syncer.to] + host = "127.0.0.1" + user = "root" + password = "" + port = 3306 + + # db-type 设置为 pb 时,存放 binlog 文件的目录 + # [syncer.to] + # dir = "data.drainer" + ``` + +3. 启动示例 + + {{< copyable "shell-regular" >}} + + ```bash + ./bin/drainer -config drainer.toml + ``` + +## TiDB Binlog Local 监控 + +这部分主要对 TiDB Binlog 的状态、性能做监控，通过 Prometheus + Grafana 展现 metrics 数据， + +### pump/drainer 配置 + +使用 ansible 部署的 pump 服务，已经在启动参数设置 metrics 。 + +drainer 启动时可以设置 `--metrics-addr` 和 `--metrics-interval` 两个参数，其中 metrics-addr 设为 Push Gateway 的地址，metrics-interval 为 push 的频率，单位为秒，默认值为15 + +### Grafana 配置 + ++ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号: admin 密码: admin） + + 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 ( 注: Type 选 Prometheus，Url 为 Prometheus 地址，根据实际情况 添加/填写 ） + ++ 导入 dashboard 配置文件 + + 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/binlog.json)上传 -> 选择对应的 data source diff --git a/reference/tidb-binlog/troubleshoot/binlog.md b/reference/tidb-binlog/troubleshoot/binlog.md new file mode 100644 index 000000000000..3494e0c83ad3 --- /dev/null +++ b/reference/tidb-binlog/troubleshoot/binlog.md @@ -0,0 +1,19 @@ +--- +title: TiDB Binlog 故障诊断 +category: reference +aliases: ['/docs-cn/dev/how-to/troubleshoot/tidb-binlog/'] +--- + +# TiDB Binlog 故障诊断 + +本文总结了在 TiDB Binlog 的使用过程中遇到问题的诊断流程，并指引用户通过监控、状态、日志等信息查找相应的解决方案。 + +如果你在使用 TiDB Binlog 时出现了异常，请尝试以下方式排查问题： + +1. 查看各个监控指标是否异常，参见[TiDB Binlog 集群监控](/reference/tidb-binlog/monitor.md)。 + +2. 使用 [binlogctl 工具](/reference/tidb-binlog/maintain.md#binlogctl-工具)查看各个 Pump、Drainer 的状态是否有异常。 + +3. 查看 Pump、Drainer 日志中是否有 `ERROR`、`WARN`，并根据详细的日志信息初步判断问题原因。 + +通过以上方式定位到问题后，在 [FAQ](/reference/tidb-binlog/faq.md) 以及 [常见错误及修复](/reference/tidb-binlog/troubleshoot/error-handling.md) 中查找解决方案，如果没有查找到解决方案或者提供的解决方案无法解决问题，请提交 [issue](https://github.com/pingcap/tidb-binlog/issues) 或者联系相关技术支持人员。 diff --git a/reference/tidb-binlog/troubleshoot/error-handling.md b/reference/tidb-binlog/troubleshoot/error-handling.md new file mode 100644 index 000000000000..68c42af4ee2d --- /dev/null +++ b/reference/tidb-binlog/troubleshoot/error-handling.md @@ -0,0 +1,32 @@ +--- +title: TiDB Binlog 常见错误修复 +category: reference +--- + +# TiDB Binlog 常见错误修复 + +本文档介绍 TiDB Binlog 中常见的错误以及修复方法。 + +## Drainer 同步数据到 Kafka 时报错 "kafka server: Message was too large, server rejected it to avoid allocation error" + +报错原因：如果在 TiDB 中执行了大事务，则生成的 binlog 数据会比较大，可能超过了 Kafka 的消息大小限制。 + +解决方法：需要调整 Kafka 的配置参数，如下所示。 + +``` +message.max.bytes=1073741824 +replica.fetch.max.bytes=1073741824 +fetch.message.max.bytes=1073741824 +``` + +## Pump 报错 "no space left on device" + +报错原因：本地磁盘空间不足，Pump 无法正常写 binlog 数据。 + +解决方法：需要清理磁盘空间，然后重启 Pump。 + +## Pump 启动时报错 "fail to notify all living drainer" + +报错原因：Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。 + +解决方法：可以使用 [binlogctl 工具](/reference/tidb-binlog/maintain.md#binlogctl-工具)查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。 diff --git a/reference/tidb-binlog/upgrade.md b/reference/tidb-binlog/upgrade.md new file mode 100644 index 000000000000..39e28f2a80b6 --- /dev/null +++ b/reference/tidb-binlog/upgrade.md @@ -0,0 +1,83 @@ +--- +title: TiDB Binlog 版本升级方法 +category: reference +aliases: ['/docs-cn/dev/how-to/upgrade/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/upgrade/'] +--- + +# TiDB Binlog 版本升级方法 + +如未特别指明，文中出现的 TiDB Binlog 均指最新的 [Cluster](/reference/tidb-binlog/overview.md) 版本。 + +本文会分 Ansible 部署和手动部署两种情况介绍 TiDB Binlog 版本升级的方法，另外有一小节介绍如何从更早的不兼容版本（Kafka/Local 版本）升级到最新版本。 + +## Ansible 部署 + +本节适用于使用 [TiDB Ansible Playbook](https://github.com/pingcap/tidb-ansible) 部署的情况。 + +### 升级 Pump + +1. 将新版本的二进制文件 `pump` 复制到 `{{ resources_dir }}/bin` 目录中 +2. 执行 `ansible-playbook rolling_update.yml --tags=pump` 命令来滚动升级 Pump + +### 升级 Drainer + +1. 将新版本的二进制文件 `drainer` 复制到 `{{ resources_dir }}/bin` 目录中 +2. 执行 `ansible-playbook stop_drainer.yml --tags=drainer` 命令 +3. 执行 `ansible-playbook start_drainer.yml --tags=drainer` 命令 + +## 手动部署 + +### 升级 Pump + +对集群里的每个 Pump 逐一升级，确保集群中总有 Pump 可以接收 TiDB 发来的 Binlog。 + +1. 用新版本的 `pump` 替换原来的文件 +2. 重启 Pump 进程 + +### 升级 Drainer + +1. 用新版本的 `drainer` 替换原来的文件 +2. 重启 Drainer 进程 + +## 从 Kafka/Local 版本升级到 Cluster 版本 + +新版本的 TiDB（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）不兼容 [Kafka 版本](/reference/tidb-binlog/tidb-binlog-kafka.md)以及 [Local 版本](/reference/tidb-binlog/tidb-binlog-local.md)的 TiDB Binlog，集群升级到新版本后只能使用 Cluster 版本的 TiDB Binlog。如果在升级前已经使用了 Kafka／Local 版本的 TiDB Binlog，必须将其升级到 Cluster 版本。 + +TiDB Binlog 版本与 TiDB 版本的对应关系如下： + +| TiDB Binlog 版本 | TiDB 版本 | 说明 | +|---|---|---| +| Local | TiDB 1.0 及更低版本 || +| Kafka | TiDB 1.0 ~ TiDB 2.1 RC5 | TiDB 1.0 支持 local 版本和 Kafka 版本的 TiDB Binlog。 | +| Cluster | TiDB v2.0.8-binlog，TiDB 2.1 RC5 及更高版本 | TiDB v2.0.8-binlog 是一个支持 Cluster 版本 TiDB Binlog 的 2.0 特殊版本。 | + +### 升级流程 + +> **注意：** +> +> 如果能接受重新导全量数据，则可以直接废弃老版本，按 [TiDB Binlog 集群部署](/reference/tidb-binlog/deploy.md)中的步骤重新部署。 + +如果想从原来的 checkpoint 继续同步，使用以下升级流程： + +1. 部署新版本 Pump。 +2. 暂停 TiDB 集群业务。 +3. 更新 TiDB 以及配置，写 Binlog 到新的 Pump Cluster。 +4. TiDB 集群重新接入业务。 +5. 确认老版本的 Drainer 已经将老版本的 Pump 的数据完全同步到下游。 + + 查询 Drainer 的 `status` 接口，示例命令如下： + + {{< copyable "shell-regular" >}} + + ```bash + curl 'http://172.16.10.49:8249/status' + ``` + + ``` + {"PumpPos":{"172.16.10.49:8250":{"offset":32686}},"Synced": true ,"DepositWindow":{"Upper":398907800202772481,"Lower":398907799455662081}} + ``` + + 如果返回的 `Synced` 为 true，则可以认为 Binlog 数据已经全部同步到了下游。 + +6. 启动新版本 Drainer； +7. 下线老版本的 Pump、Drainer 以及依赖的 Kafka 和 ZookeSeper。 diff --git a/reference/tispark.md b/reference/tispark.md new file mode 100644 index 000000000000..ee4810233068 --- /dev/null +++ b/reference/tispark.md @@ -0,0 +1,333 @@ +--- +title: TiSpark 用户指南 +category: reference +--- + +# TiSpark 用户指南 + +TiSpark 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。TiSpark 依赖于 TiKV 集群和 Placement Driver (PD)，也需要你搭建一个 Spark 集群。 + +本文简单介绍如何部署和使用 TiSpark。本文假设你对 Spark 有基本认知。你可以参阅 [Apache Spark 官网](https://spark.apache.org/docs/latest/index.html) 了解 Spark 的相关信息。 + +## 概述 + +TiSpark 是将 Spark SQL 直接运行在分布式存储引擎 TiKV 上的 OLAP 解决方案。其架构图如下： + +![TiSpark Architecture](/media/tispark-architecture.png) + ++ TiSpark 深度整合了 Spark Catalyst 引擎, 可以对计算提供精确的控制，使 Spark 能够高效的读取 TiKV 中的数据，提供索引支持以实现高速的点查。 ++ 通过多种计算下推减少 Spark SQL 需要处理的数据大小，以加速查询；利用 TiDB 的内建的统计信息选择更优的查询计划。 ++ 从数据集群的角度看，TiSpark + TiDB 可以让用户无需进行脆弱和难以维护的 ETL，直接在同一个平台进行事务和分析两种工作，简化了系统架构和运维。 ++ 除此之外，用户借助 TiSpark 项目可以在 TiDB 上使用 Spark 生态圈提供的多种工具进行数据处理。例如，使用 TiSpark 进行数据分析和 ETL；使用 TiKV 作为机器学习的数据源；借助调度系统产生定时报表等等。 + +## 环境准备 + +现有 TiSpark 2.x 版本支持 Spark 2.3.x 和 Spark 2.4.x。如果你希望使用 Spark 2.1.x 版本，需使用 TiSpark 1.x。 + +TiSpark 需要 JDK 1.8+ 以及 Scala 2.11（Spark2.0+ 默认 Scala 版本）。 + +TiSpark 可以在 YARN，Mesos，Standalone 等任意 Spark 模式下运行。 + +## 推荐配置 + +本部分描述了 TiKV 与 TiSpark 集群分开部署、Spark 与 TiSpark 集群独立部署，以及TiSpark 与 TiKV 集群混合部署的建议配置。 + +### TiKV 与 TiSpark 集群分开部署的配置 + +对于 TiKV 与 TiSpark 分开部署的场景，可以参考如下建议配置： + ++ 硬件配置建议 + + 普通场景可以参考 [TiDB 和 TiKV 硬件配置建议](/how-to/deploy/hardware-recommendations.md)，但是如果是偏重分析的场景，可以将 TiKV 节点增加到至少 64G 内存。 + +### Spark 与 TiSpark 集群独立部署的配置 + +关于 Spark 的详细硬件推荐配置请参考[官网](https://spark.apache.org/docs/latest/hardware-provisioning.html)，如下是 TiSpark 所需环境的简单描述： + +Spark 推荐 32G 内存以上的配额。请在配置中预留 25% 的内存给操作系统。 + +Spark 推荐每台计算节点配备 CPU 累计 8 到 16 核以上。你可以初始设定分配所有 CPU 核给 Spark。 + +Spark 的具体配置方式也请参考[官方说明](https://spark.apache.org/docs/latest/spark-standalone.html)。以下为根据 `spark-env.sh` 配置的范例： + +{{< copyable "" >}} + +``` +SPARK_EXECUTOR_CORES: 5 +SPARK_EXECUTOR_MEMORY: 10g +SPARK_WORKER_CORES: 5 +SPARK_WORKER_MEMORY: 10g +``` + +在 `spark-defaults.conf` 中，增加如下配置： + +{{< copyable "" >}} + +``` +spark.tispark.pd.addresses $your_pd_servers +spark.sql.extensions org.apache.spark.sql.TiExtensions +``` + +`your_pd_servers` 是用逗号分隔的 PD 地址，每个地址使用 `地址:端口` 的格式。 + +例如你有一组 PD 在`10.16.20.1`，`10.16.20.2`，`10.16.20.3`，那么 PD 配置格式是`10.16.20.1:2379,10.16.20.2:2379,10.16.20.3:2379`。 + +### TiSpark 与 TiKV 集群混合部署的配置 + +对于 TiKV 与 TiSpark 混合部署的场景，需在原有 TiKV 预留资源之外累加 Spark 所需部分，并分配 25% 的内存作为系统本身占用。 + +## 部署 TiSpark + +TiSpark 的 jar 包可以在 [TiSpark Releases 页面](https://github.com/pingcap/tispark/releases)下载对应版本的 jar 包并拷贝到合适的目录。 + +### 已有 Spark 集群的部署方式 + +如果在已有 Spark 集群上运行 TiSpark，无需重启集群。可以使用 Spark 的 `--jars` 参数将 TiSpark 作为依赖引入： + +{{< copyable "shell-regular" >}} + +```shell +spark-shell --jars $TISPARK_FOLDER/tispark-${name_with_version}.jar +``` + +### 没有 Spark 集群的部署方式 + +如果没有使用中的 Spark 集群，推荐使用 Saprk Standalone 方式部署。这里简单介绍下 Standalone 部署方式。如果遇到问题，可以去官网寻求[帮助](https://spark.apache.org/docs/latest/spark-standalone.html)；也欢迎在我们的 GitHub 上提 [issue](https://github.com/pingcap/tispark/issues/new)。 + +#### 下载安装包并安装 + +你可以在 [Download Apache Spark™ 页面](https://spark.apache.org/downloads.html)下载 Apache Spark。 + +对于 Standalone 模式且无需 Hadoop 支持，则选择 Spark 2.3.x 或者 Spark 2.4.x 且带有 Hadoop 依赖的 Pre-build with Apache Hadoop 2.x 任意版本。如有需要配合使用的 Hadoop 集群，则选择对应的 Hadoop 版本号。你也可以选择从源代码[自行构建](https://spark.apache.org/docs/latest/building-spark.html)以配合官方 Hadoop 2.x 之前的版本。 + +如果你已经有了 Spark 二进制文件，并且当前 PATH 为 SPARKPATH，需将 TiSpark jar 包拷贝到 `${SPARKPATH}/jars` 目录下。 + +#### 启动 Master + +在选中的 Spark Master 节点执行如下命令： + +{{< copyable "shell-regular" >}} + +```bash +cd $SPARKPATH +``` + +{{< copyable "shell-regular" >}} + +```bash +./sbin/start-master.sh +``` + +在这步完成以后，屏幕上会打印出一个 log 文件。检查 log 文件确认 Spark-Master 是否启动成功。你可以打开 查看集群信息（如果你没有改动 Spark-Master 默认 Port Numebr）。在启动 Spark-Slave 的时候，也可以通过这个面板来确认 Slave 是否已经加入集群。 + +#### 启动 Slave + +类似地，可以用如下命令启动 Spark-Slave 节点： + +{{< copyable "shell-regular" >}} + +```bash +./sbin/start-slave.sh spark://spark-master-hostname:7077 +``` + +命令返回以后，即可通过刚才的面板查看这个 Slave 是否已经正确地加入了 Spark 集群。在所有 Slave 节点重复刚才的命令。确认所有的 Slave 都可以正确连接 Master，这样你就拥有了一个 Standalone 模式的 Spark 集群。 + +#### Spark SQL shell 和 JDBC 服务器 + +当前版本的 TiSpark 可以直接使用 `spark-sql` 和 Spark 的 ThriftServer JDBC 服务器。 + +## 一个使用范例 + +假设你已经按照上述步骤成功启动了 TiSpark 集群，下面简单介绍如何使用 Spark SQL 来做 OLAP 分析。这里我们用名为 tpch 数据库中的 lineitem 表作为范例。 + +假设你的 PD 节点位于 192.168.1.100，端口为 2379，在 `$SPARK_HOME/conf/spark-defaults.conf` 加入： + +{{< copyable "" >}} + +``` +spark.tispark.pd.addresses 192.168.1.100:2379 +``` + +{{< copyable "" >}} + +``` +spark.sql.extensions org.apache.spark.sql.TiExtensions +``` + +然后在 Spark-Shell 里像原生 Spark 一样输入下面的命令： + +{{< copyable "" >}} + +```scala +spark.sql("use tpch") +``` + +{{< copyable "" >}} + +```scala +spark.sql("select count(*) from lineitem").show +``` + +结果为： + +``` ++-------------+ +| Count (1) | ++-------------+ +| 600000000 | ++-------------+ +``` + +Spark SQL 交互 Shell 和原生 Spark 一致： + +{{< copyable "" >}} + +```shell +spark-sql> use tpch; +``` + +``` +Time taken: 0.015 seconds +``` + +{{< copyable "" >}} + +```shell +spark-sql> select count(*) from lineitem; +``` + +``` +2000 +Time taken: 0.673 seconds, Fetched 1 row(s) +``` + +SQuirreLSQL 和 hive-beeline 可以使用 JDBC 连接 Thrift 服务器。 +例如，使用 beeline 连接： + +{{< copyable "shell-regular" >}} + +```shell +./beeline +``` + +``` +Beeline version 1.2.2 by Apache Hive +``` + +{{< copyable "" >}} + +```shell +beeline> !connect jdbc:hive2://localhost:10000 +``` + +{{< copyable "" >}} + +```shell +1: jdbc:hive2://localhost:10000> use testdb; +``` + +``` ++---------+--+ +| Result | ++---------+--+ ++---------+--+ +No rows selected (0.013 seconds) +``` + +{{< copyable "sql" >}} + +```sql +select count(*) from account; +``` + +``` ++-----------+--+ +| count(1) | ++-----------+--+ +| 1000000 | ++-----------+--+ +1 row selected (1.97 seconds) +``` + +## 和 Hive 一起使用 TiSpark + +TiSpark 可以和 Hive 混合使用。 +在启动 Spark 之前，需要添加 HADOOP_CONF_DIR 环境变量指向 Hadoop 配置目录并且将 `hive-site.xml` 拷贝到 `$SPARK_HOME/conf` 目录下。 + +``` +val tisparkDF = spark.sql("select * from tispark_table").toDF +tisparkDF.write.saveAsTable("hive_table") // save table to hive +spark.sql("select * from hive_table a, tispark_table b where a.col1 = b.col1").show // join table across Hive and Tispark +``` + +## 通过 JDBC 将 DataFrame 写入 TiDB + +暂时 TiSpark 不支持直接将数据写入 TiDB 集群，但可以使用 Spark 原生的 JDBC 支持进行写入： + +```scala +import org.apache.spark.sql.execution.datasources.jdbc.JDBCOptions + +val customer = spark.sql("select * from customer limit 100000") +// you might repartition source to make it balance across nodes +// and increase concurrency +val df = customer.repartition(32) +df.write +.mode(saveMode = "append") +.format("jdbc") +.option("driver", "com.mysql.jdbc.Driver") + // replace host and port as your and be sure to use rewrite batch +.option("url", "jdbc:mysql://127.0.0.1:4000/test?rewriteBatchedStatements=true") +.option("useSSL", "false") +// As tested, 150 is good practice +.option(JDBCOptions.JDBC_BATCH_INSERT_SIZE, 150) +.option("dbtable", s"cust_test_select") // database name and table name here +.option("isolationLevel", "NONE") // recommended to set isolationLevel to NONE if you have a large DF to load. +.option("user", "root") // TiDB user here +.save() +``` + +推荐将 `isolationLevel` 设置为 `NONE`，否则单一大事务有可能造成 TiDB 服务器内存溢出。 + +## 统计信息 + +TiSpark 可以使用 TiDB 的统计信息： + +1. 选择代价最低的索引或扫表访问 +2. 估算数据大小以决定是否进行广播优化 + +如果希望使用统计信息支持，需要确保所涉及的表已经被分析。请阅读[这份文档](https://pingcap.com/docs-cn/dev/reference/performance/statistics/)了解如何进行表分析。 + +从 TiSpark 2.0 开始，统计信息将会默认被读取。 + +统计信息将在 Spark Driver 进行缓存，请确定 Driver 内存足够缓存统计信息。 +可以在`spark-defaults.conf`中开启或关闭统计信息读取： + +| Property Name | Default | Description +| -------- | -----: | :----: | +| spark.tispark.statistics.auto_load | true | 是否默认进行统计信息读取 | + +## TiSpark FAQ + +- Q. 是独立部署还是和现有 Spark／Hadoop 集群共用资源？ + + A. 可以利用现有 Spark 集群无需单独部署，但是如果现有集群繁忙，TiSpark 将无法达到理想速度。 + +- Q. 是否可以和 TiKV 混合部署？ + + A. 如果 TiDB 以及 TiKV 负载较高且运行关键的线上任务，请考虑单独部署 TiSpark；并且考虑使用不同的网卡保证 OLTP 的网络资源不被侵占而影响线上业务。如果线上业务要求不高或者机器负载不大，可以考虑与 TiKV 混合部署。 + +- Q. Spark 执行中报 warning：WARN ObjectStore:568 - Failed to get database + + A. Warning 忽略即可，原因是 Spark 找不到对应的 hive 库，因为这个库是在 TIKV 中，而不是在 hive 中。可以考虑调整 [log4j 日志](https://github.com/pingcap/tidb-docker-compose/blob/master/tispark/conf/log4j.properties#L43)，将该参数添加到 spark 下 conf 里 log4j 文件(如果后缀是 template 那先 mv 成后缀 properties)。 + +- Q. Spark 执行中报 java.sql.BatchUpdateException: Data Truncated + + A. 写入的数据长度超过了数据库定义的数据类型的长度，可以确认 target table 的字段长度，进行调整。 + +- Q. TiSpark 任务是否默认读取 Hive 的元数据？ + + A. TiSpark 通过读取 hive-site 里的 meta 来搜寻 hive 的库。如果搜寻不到，就通过读取 tidb meta 搜寻 tidb 库。如果不需要该行为，可不在 hive site 中配置 hive 的 meta。 + +- Q. TiSpark 执行 Spark 任务时报：Error：java.io.InvalidClassException: com.pingcap.tikv.region.TiRegion; local class incompatible: stream classdesc serialVersionUID ... + + A. 该报错日志中显示 serialVersionUID 冲突，说明存在不同版本的 class 和 TiRegion。因为 TiRegion 是 TiSpark 独有的，所以可能存在多个版本的 TiSpark 包。要解决该报错，请确保集群中各节点的 TiSpark 依赖包版本一致。 diff --git a/reference/tools/br/br.md b/reference/tools/br/br.md new file mode 100644 index 000000000000..685f1942e0d3 --- /dev/null +++ b/reference/tools/br/br.md @@ -0,0 +1,400 @@ +--- +title: 使用 BR 进行备份与恢复 +summary: 了解如何使用 BR 工具进行集群数据备份和恢复。 +category: how-to +aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/br/'] +--- + +# 使用 BR 进行备份与恢复 + +Backup & Restore（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`mydumper`/`loader`](/how-to/maintain/backup-and-restore/mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。 + +## 使用限制 + +- BR 只支持 TiDB v3.1 及以上版本。 +- 目前只支持在全新的集群上执行恢复操作。 +- BR 备份最好串行执行，否则不同备份任务之间会相互影响。 + +## 推荐部署配置 + +- 推荐 BR 部署在 PD 节点上。 +- 推荐使用一块高性能 SSD 网盘，挂载到 BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。 + +## 下载 Binary + +详见[下载链接](/reference/tools/download.md#快速备份和恢复br)。 + +## 工作原理 + +BR 是分布式备份恢复的工具，它将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。 + +### 备份原理 + +BR 执行备份操作时，会先从 PD 获取到以下信息： + +- 当前的 TS 作为备份快照的时间点 +- 当前集群的 TiKV 节点信息 + +然后 BR 根据这些信息，在内部启动一个 TiDB 实例，获取对应 TS 的数据库或表信息，同时过滤掉系统库 (`information_schema`，`performance_schema`，`mysql`)。 + +此时根据备份子命令，会有两种备份逻辑： + +- 全量备份：BR 遍历全部库表，并且根据每一张表构建需要备份的 KV Range +- 单表备份：BR 根据该表构建需要备份的 KV Range + +最后，BR 将需要备份的 KV Range 收集后，构造完整的备份请求分发给集群内的 TiKV 节点。 + +该请求的主要结构如下： + +``` +BackupRequest{ + ClusterId, // 集群 ID + StartKey, // 备份起始点，startKey 会被备份 + EndKey, // 备份结束点，endKey 不会被备份 + EndVersion, // 备份快照时间点 + StorageBackend, // 备份文件存储地址 + RateLimit, // 备份速度 (MB/s) + Concurrency, // 执行备份操作的线程数（默认为 4） +} +``` + +TiKV 节点收到备份请求后，会遍历节点上所有的 Region Leader，找到和请求中 KV Range 有重叠范围的 Region，将该范围下的部分或者全部数据进行备份，在备份路径下生成对应的 SST 文件。 + +TiKV 节点在备份完对应 Region Leader 的数据后将元信息返回给 BR。BR 将这些元信息收集并存储进 `backupmeta` 文件中，等待恢复时使用。 + +如果执行命令时开启了 checksum，那么 BR 在最后会对备份的每一张表计算 checksum 用于校验。 + +#### 备份文件类型 + +备份路径下会生成以下两种类型文件： + +- SST 文件：存储 TiKV 备份下来的数据信息 +- `backupmeta` 文件：存储本次备份的元信息，包括备份文件数、备份文件的 Key 区间、备份文件大小和备份文件 Hash (sha256) 值 + +#### SST 文件命名格式 + +SST 文件以 `storeID_regionID_regionEpoch_keyHash_cf` 的格式命名。格式名的解释如下： + +- storeID：TiKV 节点编号 +- regionID：Region 编号 +- regionEpoch：Region 版本号 +- keyHash：Range startKey 的 Hash (sha256) 值，确保唯一性 +- cf：RocksDB 的 ColumnFamily（默认为 `default` 或 `write`） + +### 恢复原理 + +BR 执行恢复操作时，会按顺序执行以下任务： + +1. 解析备份路径下的 backupMeta 文件，根据解析出来的库表信息，在内部启动一个 TiDB 实例在新集群创建对应的库表。 + +2. 把解析出来的 SST 文件，根据表进行聚合。 + +3. 根据 SST 文件的 Key Range 进行预切分 Region，使得每个 Region 至少对应一个 SST 文件。 + +4. 遍历要恢复的每一张表，以及这个表对应的 SST 文件。 + +5. 找到该文件对应的 Region，发送下载文件的请求到对应的 TiKV 节点，并在下载成功后，发送加载请求。 + +TiKV 收到加载 SST 文件的请求后，利用 Raft 机制保证加载 SST 数据的强一致性。在加载成功后，下载下来的 SST 文件会被异步删除。 + +在执行完恢复操作后，BR 会对恢复后的数据进行 checksum 计算，用于和备份下来的数据进行对比。 + +![br-arch](/media/br-arch.png) + +## BR 命令行描述 + +一条 `br` 命令是由子命令、选项和参数组成的。子命令即不带 `-` 或者 `--` 的字符。选项即以 `-` 或者 `--` 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。 + +以下是一条完整的 `br` 命令行： + +`br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"` + +命令行各部分的解释如下： + +* `backup`：`br` 的子命令 +* `full`：`backup` 的子命令 +* `-s` 或 `--storage`：备份保存的路径 +* `"local:///tmp/backup"`：`-s` 的参数，保存的路径为本地磁盘的 `/tmp/backup` +* `--pd`：PD 服务地址 +* `"${PDIP}:2379"`：`--pd` 的参数 + +### 命令和子命令 + +BR 由多层命令组成。目前，BR 包含 `backup`、`restore` 和 `version` 三个子命令: + +* `br backup` 用于备份 TiDB 集群 +* `br restore` 用于恢复 TiDB 集群 +* `br version` 用于查看 BR 工具版本信息 + +以上三个子命令可能还包含这些子命令： + +* `full`：可用于备份或恢复全部数据。 +* `db`：可用于备份或恢复集群中的指定数据库。 +* `table`：可用于备份或恢复集群指定数据库中的单张表。 + +### 常用选项 + +* `--pd`：用于连接的选项，表示 PD 服务地址，例如 `"${PDIP}:2379"`。 +* `-h`/`--help`：获取所有命令和子命令的使用帮助。例如 `br backup --help`。 +* `--ca`：指定 PEM 格式的受信任 CA 的证书文件路径。 +* `--cert`：指定 PEM 格式的 SSL 证书文件路径。 +* `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。 +* `--status-addr`：BR 向 Prometheus 提供统计数据的监听地址。 + +## 备份集群数据 + +使用 `br backup` 命令来备份集群数据。可选择添加 `full` 或 `table` 子命令来指定备份的范围：全部集群数据或单张表的数据。 + +如果备份时间可能超过设定的 [`tikv_gc_life_time`](/reference/garbage-collection/configuration.md#tikv_gc_life_time)（默认 `10m0s`），则需要将该参数调大。 + +例如，将 `tikv_gc_life_time` 调整为 `720h`： + +{{< copyable "sql" >}} + +```sql +mysql -h${TiDBIP} -P4000 -u${TIDB_USER} ${password_str} -Nse \ + "update mysql.tidb set variable_value='720h' where variable_name='tikv_gc_life_time'"; +``` + +### 备份全部集群数据 + +要备份全部集群数据，可使用 `br backup full` 命令。该命令的使用帮助可以通过 `br backup full -h` 或 `br backup full --help` 来获取。 + +用例：将所有集群数据备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 + +{{< copyable "shell-regular" >}} + +```shell +br backup full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --concurrency 4 \ + --log-file backupfull.log +``` + +以上命令中，`--ratelimit` 和 `--concurrency` 选项限制了**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）和并发数上限。`--log-file` 选项指定把 BR 的 log 写到 `backupfull.log` 文件中。 + +备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。进度条效果如下： + +```shell +br backup full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --concurrency 4 \ + --log-file backupfull.log +Full Backup <---------/................................................> 17.12%. +``` + +### 备份单个数据库的数据 + +要备份集群中指定单个数据库的数据，可使用 `br backup db` 命令。同样可通过 `br backup db -h` 或 `br backup db --help` 来获取子命令 `db` 的使用帮助。 + +用例：将数据库 `test` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 + +{{< copyable "shell-regular" >}} + +```shell +br backup db \ + --pd "${PDIP}:2379" \ + --db test \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --concurrency 4 \ + --log-file backuptable.log +``` + +`db` 子命令的选项为 `--db`，用来指定数据库名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 + +备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 + +### 备份单张表的数据 + +要备份集群中指定单张表的数据，可使用 `br backup table` 命令。同样可通过 `br backup table -h` 或 `br backup table --help` 来获取子命令 `table` 的使用帮助。 + +用例：将表 `test.usertable` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 + +{{< copyable "shell-regular" >}} + +```shell +br backup table \ + --pd "${PDIP}:2379" \ + --db test \ + --table usertable \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --concurrency 4 \ + --log-file backuptable.log +``` + +`table` 子命令有 `--db` 和 `--table` 两个选项，分别用来指定数据库名和表名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 + +备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 + +## 恢复集群数据 + +使用 `br restore` 命令来恢复备份数据。可选择添加 `full`、`db` 或 `table` 子命令来指定恢复操作的范围：全部集群数据、某个数据库或某张数据表。 + +> **注意：** +> +> 如果备份的集群没有网络存储，在恢复前需要将所有备份的 SST 文件拷贝到各个 TiKV 节点上 `--storage` 指定的目录下。 + +### 恢复全部备份数据 + +要将全部备份数据恢复到集群中来，可使用 `br restore full` 命令。该命令的使用帮助可以通过 `br restore full -h` 或 `br restore full --help` 来获取。 + +用例：将 `/tmp/backup` 路径中的全部备份数据恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --concurrency 128 \ + --log-file restorefull.log +``` + +`--concurrency` 指定了该恢复任务内部的子任务的并发数。`--log-file` 选项指定把 BR 的 log 写到 `restorefull.log` 文件中。 + +恢复期间还有进度条会在终端中显示，当进度条前进到 100% 时，说明恢复已完成。在完成恢复后，BR 为了确保数据安全性，还会校验恢复数据。进度条效果如下： + +```shell +br restore full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +Full Restore <---------/...............................................> 17.12%. +``` + +### 恢复单个数据库的数据 + +要将备份数据中的某个数据库恢复到集群中，可以使用 `br restore db` 命令。该命令的使用帮助可以通过 `br restore db -h` 或 `br restore db --help` 来获取。 + +用例：将 `/tmp/backup` 路径中备份数据中的某个数据库恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore db \ + --pd "${PDIP}:2379" \ + --db "test" \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +``` + +以上命令中 `--db` 选项指定了需要恢复的数据库名字。其余选项的含义与[恢复全部备份数据](#恢复全部备份数据)相同。 + +### 恢复单张表的数据 + +要将备份数据中的某张数据表恢复到集群中，可以使用 `br restore table` 命令。该命令的使用帮助可通过 `br restore table -h` 或 `br restore table --help` 来获取。 + +用例：将 `/tmp/backup` 路径下的备份数据中的某个数据表恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore table \ + --pd "${PDIP}:2379" \ + --db "test" \ + --table "usertable" \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +``` + +以上命令中 `--table` 选项指定了需要恢复的表名。其余选项的含义与[恢复某个数据库](#恢复某个数据库)相同。 + +## 最佳实践 + +- 推荐在 `-s` 指定的备份路径上挂载一个共享存储，例如 NFS。这样能方便收集和管理备份文件。 +- 在使用共享存储时，推荐使用高吞吐的存储硬件，因为存储的吞吐会限制备份或恢复的速度。 +- 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。 + +更多最佳实践内容，参见 [BR 备份与恢复场景示例](/reference/tools/br/use-cases.md)。 + +## 备份和恢复示例 + +本示例展示如何对已有的集群数据进行备份和恢复操作。可以根据机器性能、配置、数据规模来预估一下备份和恢复的性能。 + +### 数据规模和机器配置 + +假设对 TiKV 集群中的 10 张表进行备份和恢复。每张表有 500 万行数据，数据总量为 35 GB。 + +```sql +MySQL [sbtest]> show tables; ++------------------+ +| Tables_in_sbtest | ++------------------+ +| sbtest1 | +| sbtest10 | +| sbtest2 | +| sbtest3 | +| sbtest4 | +| sbtest5 | +| sbtest6 | +| sbtest7 | +| sbtest8 | +| sbtest9 | ++------------------+ + +MySQL [sbtest]> select count(*) from sbtest1; ++----------+ +| count(*) | ++----------+ +| 5000000 | ++----------+ +1 row in set (1.04 sec) +``` + +表结构如下： + +```sql +CREATE TABLE `sbtest1` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `k` int(11) NOT NULL DEFAULT '0', + `c` char(120) NOT NULL DEFAULT '', + `pad` char(60) NOT NULL DEFAULT '', + PRIMARY KEY (`id`), + KEY `k_1` (`k`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=5138499 +``` + +示例假设有 4 个 TiKV 节点，每个节点配置如下： + +| CPU | 内存 | 磁盘 | 副本数 | +| :--- | :--- | :--- | :--- | +| 16 核 | 32 GB | SSD | 3 | + +### 备份示例 + +- 备份前需确认已将 GC 时间调长，确保备份期间不会因为数据丢失导致中断 +- 备份前需确认 TiDB 集群没有执行 DDL 操作 + +执行以下命令对集群中的全部数据进行备份： + +{{< copyable "shell-regular" >}} + +``` +bin/br backup full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file backup.log +``` + +``` +[INFO] [collector.go:165] ["Full backup summary: total backup ranges: 2, total success: 2, total failed: 0, total take(s): 0.00, total kv: 4, total size(Byte): 133, avg speed(Byte/s): 27293.78"] ["backup total regions"=2] ["backup checksum"=1.640969ms] ["backup fast checksum"=227.885µs] +``` + +### 恢复示例 + +恢复操作前，需确认待恢复的 TiKV 集群是全新的集群。 + +执行以下命令对全部数据进行恢复： + +{{< copyable "shell-regular" >}} + +``` +bin/br restore full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file restore.log +``` + +``` +[INFO] [collector.go:165] ["Full Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 0.26, total kv: 20000, total size(MB): 10.98, avg speed(MB/s): 41.95"] ["restore files"=3] ["restore ranges"=2] ["split region"=0.562369381s] ["restore checksum"=36.072769ms] +``` diff --git a/reference/tools/br/use-cases.md b/reference/tools/br/use-cases.md new file mode 100644 index 000000000000..4e2c0eb41aee --- /dev/null +++ b/reference/tools/br/use-cases.md @@ -0,0 +1,415 @@ +--- +title: BR 备份与恢复场景示例 +category: reference +aliases: ['/docs-cn/dev/how-to/maintain/backup-and-restore/br-best-practices/','/docs-cn/dev/reference/tools/br/br-best-practices/'] +--- + +# BR 备份与恢复场景示例 + +[Backup & Restore](/reference/tools/br/br.md)（下文简称 BR）一款分布式的快速备份和恢复工具。本文展示了[四种备份和恢复场景](#使用场景)下的 BR 操作过程，以帮助读者达到以下目标： + +* 正确使用网络盘或本地盘进行备份或恢复 +* 通过相关监控指标了解备份或恢复的状态 +* 了解在备份或恢复时如何调优性能 +* 处理备份时可能发生的异常 + +> **注意：** +> +> 使用 BR 时应注意[使用限制](/reference/tools/br/br.md#使用限制)。 + +## 目标读者 + +读者需要对 TiDB 和 TiKV 有一定的了解。在阅读本文前，推荐先阅读[使用 BR 进行备份与恢复](/reference/tools/br/br.md)。 + +## 环境准备 + +本部分介绍推荐的 TiDB 的部署方式、示例中的集群版本、TiKV 集群硬件信息和集群配置。读者可根据自己的硬件和配置来预估备份恢复的性能。 + +### 部署方式 + +推荐使用 [TiDB Ansible](/how-to/deploy/orchestrated/ansible.md) 部署 TiDB 集群，再下载 [TiDB Toolkit](/reference/tools/download.md#快速备份和恢复br) 获取 BR 应用。 + +### 集群版本 + +* TiKV: v3.1.0-beta.1 +* PD: v3.1.0-beta.1 +* br: v3.1.0-beta.1 + +### TiKV 集群硬件信息 + +* 操作系统：CentOS Linux release 7.6.1810 (Core) +* CPU：16-Core Common KVM processor +* RAM：32GB +* 硬盘：500G SSD * 2 +* 网卡：10000MB/s + +### 配置 + +BR 可以直接将命令下发到 TiKV 集群来执行备份和恢复，不依赖 TiDB server 组件，因此无需对 TiDB server 进行配置。 + +* TiKV: 默认配置 +* PD : 默认配置 + +## 使用场景 + +本文描述以下四种使用场景： + +* [将单表数据备份到网络盘（推荐）](#将单表数据备份到网络盘推荐) +* [从网络磁盘恢复备份数据（推荐）](#从网络磁盘恢复备份数据推荐) +* [将单表数据备份到本地磁盘](#将单表数据备份到本地磁盘) +* [从本地磁盘恢复备份数据](#从本地磁盘恢复备份数据) + +推荐使用网络盘来进行备份和恢复操作，这样可以省去收集备份数据文件的繁琐步骤。尤其在 TiKV 集群规模较大的情况下，使用网络盘可以大幅提升操作效率。 + +> **注意：** +> +> 在进行备份或恢复操作前，需要先进行备份或恢复的准备工作。 + +### 备份前的准备工作 + +`br backup` 命令的详细使用方法请参考 [BR 命令行描述](/reference/tools/br/br.md#br-命令行描述)。 + +1. 运行 `br backup` 命令前，查询 TiDB 集群的 [`tikv_gc_life_time`](/reference/garbage-collection/configuration.md#tikv_gc_life_time) 配置项的值，并使用 MySQL 客户端将该项调整至合适的值，确保备份期间不会发生 [Garbage Collection](/reference/garbage-collection/overview.md) (GC)。 + + {{< copyable "sql" >}} + + ```sql + SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; + UPDATE mysql.tidb SET VARIABLE_VALUE = '720h' WHERE VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + +2. 在备份完成后，将该参数调回原来的值。 + + {{< copyable "sql" >}} + + ```sql + update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + +### 恢复前的准备工作 + +`br restore` 命令的详细使用方法请参考 [BR 命令行描述](/reference/tools/br/br.md#br-命令行描述)。 + +> **注意：** +> +> 运行 `br restore` 前检查新集群确保没有同名的表。 + +### 将单表数据备份到网络盘（推荐） + +使用 `br backup` 命令，将单表数据 `--db batchmark --table order_line` 备份到指定的网络盘路径 `local:///br_data` 下。 + +#### 前置要求 + +* 配置一台高性能 SSD 硬盘主机为 NFS server 存储数据。其他所有 BR 节点和 TiKV 节点为 NFS client，挂载相同的路径（例如 `/br_data`）到 NFS server 上以访问 NFS server。 +* NFS server 和 NFS client 间的数据传输速率至少要达到备份集群的 `TiKV 实例数 * 150MB/s`。否则网络 I/O 有可能成为性能瓶颈。 + +#### 部署拓扑 + +部署拓扑如下图所示： + +![img](/media/br/backup-nfs-deploy.png) + +#### 运行备份 + +备份操作前，在 TiDB 中使用 `admin checksum table order_line` 命令获得备份目标表 `--db batchmark --table order_line` 的统计信息。统计信息示例如下： + +![img](/media/br/total-data.png) + +运行 BR 备份命令： + +{{< copyable "shell-regular" >}} + +```shell +bin/br backup table --db batchmark --table order_line -s local:///br_data --pd 172.16.5.198:2379 --log-file backup-nfs.log +``` + +#### 备份过程中的运行指标 + +在 BR 备份过程中，需关注以下监控面版中的运行指标来了解备份的状态。 + +**Backup CPU Utilization**：参与备份的 TiKV 节点（例如 backup-worker 和 backup-endpoint）的 CPU 使用率。 + +![img](/media/br/backup-cpu.png) + +**IO Utilization**：参与备份的 TiKV 节点的 I/O 使用率。 + +![img](/media/br/backup-io.png) + +**BackupSST Generation Throughput**：参与备份的 TiKV 节点生成 backupSST 文件的吞吐。正常时单个 TiKV 节点的吞吐在 150MB/s 左右。 + +![img](/media/br/backup-throughput.png) + +**One Backup Range Duration**：备份一个 range 的操作耗时，包括扫描耗时 (scan KV) 和保存耗时（保存为 backupSST 文件）。 + +![img](/media/br/backup-range-duration.png) + +**One Backup Subtask Duration**： 一次备份任务会被拆分成多个子任务。该监控项显示子任务的耗时。 + +> **注意：** +> +> * 虽然本次任务是备份单表，但因为表中有 3 个索引，所以正常会拆分成 4 个子任务。 +> * 下图中有 13 个点，说明有 9 次 (13-4) 重试。备份过程中可能发生 Region 调度行为，少量重试是正常的。 + +![img](/media/br/backup-subtask-duration.png) + +**Backup Errors**：备份过程中的错误。正常时无错误。即使出现少量错误，备份操作也有重试机制，可能会导致备份时间增加，但不会影响备份的正确性。 + +![img](/media/br/backup-errors.png) + +**Checksum Request Duration**：对备份集群执行 admin checksum 的耗时统计。 + +![img](/media/br/checksum-duration.png) + +#### 结果解读 + +使用 BR 前已设置日志的存放路径。从路径下存放的日志中可以获取此次备份的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： + +``` +["Table backup summary: total backup ranges: 4, total success: 4, total failed: 0, total take(s): 986.43, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 358.09"] ["backup total regions"=7196] ["backup checksum"=6m28.291772955s] ["backup fast checksum"=24.950298ms] +``` + +以上日志信息中包含以下内容： + +* 备份耗时：`total take(s): 986.43` +* 数据大小：`total size(MB): 353227.18` +* 备份吞吐：`avg speed(MB/s): 358.09` +* 校验耗时：`take=6m28.29s` + +通过以上数据可以计算得到单个 TiKV 实例的吞吐为：`avg speed(MB/s)`/`tikv_count` = `89`。 + +#### 性能调优 + +如果 TiKV 的资源使用没有出现明显的瓶颈（例如[备份过程中的运行指标](#备份过程中的运行指标)中的 **Backup CPU Utilization** 最高为 `1500%` 左右，**IO Utilization** 普遍低于 `30%`），可以尝试调大 `--concurrency` 参数以进行性能调优。该方法不适用于存在许多小表的场景。 + +示例如下： + +{{< copyable "shell-regular" >}} + +```shell +bin/br backup table --db batchmark --table order_line -s local:///br_data/ --pd 172.16.5.198:2379 --log-file backup-nfs.log --concurrency 16 +``` + +![img](/media/br/backup-diff.png) + +![img](/media/br/backup-diff2.png) + +性能调优后的结果如下所示（保持数据大小不变）： + +* 备份耗时：`total take(s)` 从 `986.43` 减少到 `535.53` +* 数据大小：`total size(MB): 353227.18` +* 备份吞吐：`avg speed(MB/s)` 从 `358.09` 提升到 `659.59` +* 单个 TiKV 实例的吞吐：`avg speed(MB/s)/tikv_count` 从 `89` 提升到 `164.89` + +### 从网络磁盘恢复备份数据（推荐） + +使用 `br restore` 命令，将一份完整的备份数据恢复到一个离线集群。暂不支持恢复到在线集群。 + +#### 前置要求 + +无 + +#### 部署拓扑 + +部署拓扑如下图所示： + +![img](/media/br/restore-nfs-deploy.png) + +#### 运行恢复 + +运行 `br restore` 命令： + +{{< copyable "shell-regular" >}} + +```shell +bin/br restore table --db batchmark --table order_line -s local:///br_data --pd 172.16.5.198:2379 --log-file restore-nfs.log +``` + +#### 恢复过程中的运行指标 + +在 BR 恢复过程中，需关注以下监控面版中的运行指标来了解恢复的状态。 + +**CPU Utilization**：参与恢复的 TiKV 节点 CPU 使用率。 + +![img](/media/br/restore-cpu.png) + +**IO Utilization**：参与恢复的 TiKV 节点的 I/O 使用率。 + +![img](/media/br/restore-io.png) + +**Region** 分布：Region 分布越均匀，说明恢复资源利用越充分。 + +![img](/media/br/restore-region.png) + +**Process SST Duration**：处理 SST 文件的延迟。恢复一张表时时，如果 `tableID` 发生了变化，需要对 `tableID` 进行 `rewrite`，否则会进行 `rename`。通常 `rewrite` 延迟要高于 `rename` 的延迟。 + +![img](/media/br/restore-process-sst.png) + +**DownLoad SST Throughput**：从 External Storage 下载 SST 文件的吞吐。 + +![img](/media/br/restore-download-sst.png) + +**Restore Errors**：恢复过程中的错误。 + +![img](/media/br/restore-errors.png) + +**Checksum Request duration**：对恢复集群执行 admin checksum 的耗时统计，会比备份时的 checksum 延迟高。 + +![img](/media/br/restore-checksum.png) + +#### 结果解读 + +使用 BR 前已设置日志的存放路径。从路径下存放的日志中可以获取此次恢复的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： + +``` +["Table Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 961.37, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 367.42"] ["restore files"=9263] ["restore ranges"=6888] ["split region"=49.049182743s] ["restore checksum"=6m34.879439498s] +``` + +以上日志信息中包含以下内容： + +* 恢复耗时：`total take(s):961.37` +* 数据大小：`total size(MB): 353227.18` +* 恢复吞吐：`avg speed(MB/s): 367.42` +* `Region Split` 耗时：`take=49.049182743s` +* 校验耗时：`take=6m34.879439498s` + +根据上表数据可以计算得到： + +* 单个 TiKV 吞吐：`avg speed(MB/s)`/`tikv_count` = `91.8` +* 单个 TiKV 平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` = `87.4` + +#### 性能调优 + +如果 TiKV 资源使用没有明显的瓶颈，可以尝试调大 `--concurrency` 参数（默认为 `128`），示例如下： + +{{< copyable "shell-regular" >}} + +```shell +bin/br restore table --db batchmark --table order_line -s local:///br_data/ --pd 172.16.5.198:2379 --log-file restore-concurrency.log --concurrency 1024 +``` + +性能调优后的结果如下表所示（保持数据大小不变）： + +* 恢复耗时：`total take(s)` 从 `961.37` 减少到 `443.49` +* 恢复吞吐：`avg speed(MB/s)` 从 `367.42` 提升到 `796.47` +* 单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` 从 `91.8` 提升到 `199.1` +* 单个 TiKV 实例的平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` 从 `87.4` 提升到 `162.3` + +### 将单表数据备份到本地磁盘 + +使用 `br backup 命令`，将单表数据 `--db batchmark --table order_line` 备份到指定的本地磁盘路径 `local:///home/tidb/backup_local` 下。 + +#### 前置要求 + +* 各个 TiKV 节点有单独的磁盘用来存放 backupSST 数据。 +* `backup_endpoint` 节点有单独的磁盘用来存放备份的 `backupmeta` 文件。 +* TiKV 和 `backup_endpoint` 节点需要有相同的备份目录，例如 `/home/tidb/backup_local`。 + +#### 部署拓扑 + +![img](/media/br/backup-local-deploy.png) + +#### 运行备份 + +备份前在 TiDB 里通过 `admin checksum table order_line` 获得备份的目标表 `--db batchmark --table order_line` 的统计信息。统计信息示例如下： + +![img](/media/br/total-data.png) + +运行 `br backup` 命令： + +{{< copyable "shell-regular" >}} + +```shell +bin/br backup table --db batchmark --table order_line -s local:///home/tidb/backup_local/ --pd 172.16.5.198:2379 --log-file backup_local.log +``` + +运行备份时，参考[备份过程中的运行指标](#备份过程中的运行指标)对相关指标进行监控，以了解备份状态。 + +#### 结果解读 + +使用 BR 前已设置日志的存放路径。从该路径下存放的日志获取此次备份的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： + +``` +["Table backup summary: total backup ranges: 4, total success: 4, total failed: 0, total take(s): 551.31, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 640.71"] ["backup total regions"=6795] ["backup checksum"=6m33.962719217s] ["backup fast checksum"=22.995552ms] +``` + +以上日志信息中包含以下内容： + +* 备份耗时：`total take(s): 551.31` +* 数据大小：`total size(MB): 353227.18` +* 备份吞吐：`avg speed(MB/s): 640.71` +* 校验耗时：`take=6m33.962719217s` + +根据上表数据可以计算得到单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` = `160`。 + +### 从本地磁盘恢复备份数据 + +使用 `br restore` 命令，将一份完整的备份数据恢复到一个离线集群。暂不支持恢复到在线集群。 + +#### 前置要求 + +* 集群中没有与备份数据相同的库表。目前 BR 不支持 table route。 +* 集群中各个 TiKV 节点有单独的磁盘用来存放要恢复的 backupSST 数据。 +* `restore_endpoint` 节点有单独的磁盘用来存放要恢复的 `backupmeta` 文件。 +* 集群中 TiKV 和 `restore_endpoint` 节点需要有相同的备份目录，例如 `/home/tidb/backup_local/`。 + +如果备份数据存放在本地磁盘，那么需要执行以下的步骤： + +1. 汇总所有 backupSST 文件到一个统一的目录下。 +2. 将汇总后的 backupSST 文件到复制到集群的所有 TiKV 节点下。 +3. 将 `backupmeta` 文件复制到到 `restore endpoint` 节点下。 + +#### 部署拓扑 + +![img](/media/br/restore-local-deploy.png) + +#### 运行恢复 + +运行 `br restore` 命令： + +{{< copyable "shell-regular" >}} + +```shell +bin/br restore table --db batchmark --table order_line -s local:///home/tidb/backup_local/ --pd 172.16.5.198:2379 --log-file restore_local.log +``` + +运行恢复时，参考[恢复过程中的运行指标](#恢复过程中的运行指标)对相关指标进行监控，以了解恢复状态。 + +#### 结果解读 + +使用 BR 前已设置日志的存放路径。从该日志中可以获取此次恢复的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： + +``` +["Table Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 908.42, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 388.84"] ["restore files"=9263] ["restore ranges"=6888] ["split region"=58.7885518s] ["restore checksum"=6m19.349067937s] +``` + +以上日志信息中包含以下内容： + +* 恢复耗时：`total take(s): 908.42` +* 数据大小：`total size(MB): 353227.18` +* 恢复吞吐：`avg speed(MB/s): 388.84` +* `Region Split` 耗时：`take=58.7885518s` +* 校验耗时：`take=6m19.349067937s` + +根据上表数据可以计算得到： + +* 单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` = `97.2` +* 单个 TiKV 实例的平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` = `92.4` + +### 异常处理 + +本部分介绍如何处理备份过程中出现的常见错误。 + +#### 备份日志中出现 `key locked Error` + +日志中的错误消息：`log - ["backup occur kv error"][error="{\"KvError\":{\"locked\":` + +如果在备份过程中遇到 key 被锁住，目前 BR 会尝试清锁。少量报错不会影响备份的正确性。 + +#### 备份失败 + +日志中的错误消息：`log - Error: msg:"Io(Custom { kind: AlreadyExists, error: \"[5_5359_42_123_default.sst] is already exists in /dir/backup_local/\" })"` + +若备份失败并出现以上错误消息，采取以下其中一种操作后再重新备份： + +* 更换备份数据目录。例如将 `/dir/backup-2020-01-01/` 改为 `/dir/backup_local/`。 +* 删除所有 TiKV 和 BR 节点的备份目录。 diff --git a/reference/tools/data-migration/cluster-operations.md b/reference/tools/data-migration/cluster-operations.md new file mode 100644 index 000000000000..7be1204e1b4a --- /dev/null +++ b/reference/tools/data-migration/cluster-operations.md @@ -0,0 +1,489 @@ +--- +title: DM 集群操作 +category: reference +--- + +# DM 集群操作 + +本文介绍 DM 集群操作以及使用 DM-Ansible 管理 DM 集群时需要注意的事项。 + +## 启动集群 + +运行以下命令以启动整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook start.yml +``` + +## 下线集群 + +运行以下命令以下线整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： + +{{< copyable "shell-regular" >}} + +```bash +ansible-playbook stop.yml +``` + +## 重启集群组件 + +在以下情况下，需要更新 DM 集群组件： + +- 您想要[更新组件版本](#更新组件版本)。 +- 发生了严重的错误，您需要重启组件完成临时恢复。 +- DM 集群所在的机器由于某种原因重启。 + +### 重启注意事项 + +该部分描述重启 DM 各组件时需要了解的事项。 + +#### DM-worker 重启事项 + +**全量数据导入过程中：** + +对于全量数据导入时的 SQL 文件，DM 使用下游数据库记录断点信息，DM-worker 会在本地 meta 文件记录子任务信息。DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 + +**增量数据同步过程中：** + +对于增量数据导入过程中的 binlog，DM 使用下游数据库记录断点信息，并会在同步任务开始或恢复后的第一个五分钟之内开启安全模式。 + ++ 未启用 sharding DDL 同步 + + 如果 DM-worker 上运行的任务未启用 sharding DDL 同步功能，DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 + ++ 已启用 sharding DDL 同步 + + - DM 同步 sharding DDL 语句时，如果 DM-worker 成功执行（或跳过）sharding DDL 的 binlog event，与 DM-worker 中的 sharding DDL 语句相关的所有表的断点信息都会被更新至 DDL 语句对应的 binlog event 之后的位置。 + + - 当 DM-worker 重启发生在 sharding DDL 语句同步开始前或完成后，DM-worker 会根据断点信息和本地记录的子任务信息自动恢复数据同步。 + + - 当 DM-worker 重启发生在 sharding DDL 语句同步过程中，可能会出现作为 DDL lock owner 的 DM-worker 实例已执行了 DDL 语句并成功变更了下游数据库表结构，但其他 DM-worker 实例重启而无法跳过 DDL 语句也无法更新断点的情况。 + + 此时 DM 会再次尝试同步这些未跳过执行的 DDL 语句。然而，由于未重启的 DM-worker 实例已经执行到了此 DDL 对应的 binlog event 之后，重启的 DM-worker 实例会被阻滞在重启前 DDL binlog event 对应的位置。 + + 要解决这个问题，请按照[手动处理 Sharding DDL Lock](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#场景二unlock-过程中部分-dm-worker-重启) 中描述的步骤操作。 + +**总结**：尽量避免在 sharding DDL 同步过程中重启 DM-worker。 + +#### DM-master 重启事项 + +由 DM-master 维护的信息包括以下两种。重启 DM-master 不会持久化保存这些信息的相关数据。 + +- 任务信息 +- Sharding DDL lock 信息 + +DM-master 重启时会自动向每个 DM-worker 实例请求任务信息，重建任务与 DM-worker 之间的对应关系，并从每个 DM-worker 实例获取 sharding DDL 信息。这样，就可以准确重建相应的 DDL lock，也可以自动解除 sharding DDL lock。 + +### 重启 DM-worker + +> **注意：** +> +> 尽量避免在 sharding DDL 同步过程中重启 DM-worker。 + +使用以下两种方法中任一种重启 DM-worker 组件： + +- 对 DM-worker 执行滚动升级。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-worker + ``` + +- 先停止 DM-worker，然后重启。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml --tags=dm-worker && + ansible-playbook start.yml --tags=dm-worker + ``` + +### 重启 DM-master + +在以下两种方法中任选一种，重启 DM-master 组件： + +- 对 DM-master 执行滚动升级。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-master + ``` + +- 停止 DM-master，然后重启。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml --tags=dm-master && + ansible-playbook start.yml --tags=dm-master + ``` + +## 更新组件版本 + +1. 下载 DM 二进制文件。 + + 1. 从 `downloads` 目录删除已有文件。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/dm-ansible && + rm -rf downloads + ``` + + 2. 用 Playbook 下载 inventory.ini 文件中指定版本的最新 DM 二进制文件。这会自动替换 `/home/tidb/dm-ansible/resource/bin/` 中已有文件。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook local_prepare.yml + ``` + +2. 使用 Ansible 执行滚动升级。 + + 1. 对 DM-worker 实例执行滚动升级： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-worker + ``` + + 2. 对 DM-master 实例执行滚动升级： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-master + ``` + + 3. 升级 dmctl： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dmctl + ``` + + 4. 对 DM-worker， DM-master， 以及 dmctl 整体执行滚动升级： + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml + ``` + +## 创建 DM-worker 实例 + +假设您想要在机器 `172.16.10.74` 上创建一个名为 `dm_worker3` 的 DM-worker 实例，按以下步骤操作： + +1. 为中控机设置 SSH 互信以及 sudo 规则。 + + 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 用户登录至中控机，并将 `172.16.10.74` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/dm-ansible && + vi hosts.ini + ``` + + ``` + [servers] + 172.16.10.74 + + [all:vars] + username = tidb + ``` + + 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.74`。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook -i hosts.ini create_users.yml -u root -k + ``` + + 该步在 `172.16.10.74` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 + +2. 修改 `inventory.ini` 文件，创建新 DM-worker 实例 `dm_worker3`。 + + ```ini + [dm_worker_servers] + dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + + dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + + dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + ``` + +3. 部署新 DM-worker 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml --tags=dm-worker -l dm_worker3 + ``` + +4. 启用新 DM-worker 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml --tags=dm-worker -l dm_worker3 + ``` + +5. 配置并重启 DM-master 服务。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-master + ``` + +6. 配置并重启 Prometheus 服务。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +## 下线 DM-worker 实例 + +假设您想要下线的 DM-worker 实例为 `dm_worker3`。按以下步骤操作： + +1. 关闭您想要下线的 DM-worker 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml --tags=dm-worker -l dm_worker3 + ``` + +2. 修改 `inventory.ini` 文件，注释或删除 `dm_worker3` 实例所在行。 + + ```ini + [dm_worker_servers] + dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + + dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + + # dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 # Comment or delete this line + ``` + +3. 配置并重启 DM-master 服务。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-master + ``` + +4. 配置并重启 Prometheus 服务。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +## 替换/迁移 DM-master 实例 + +假设机器 `172.16.10.71` 需要进行维护或者已崩溃，需要将 DM-master 实例从 `172.16.10.71` 迁移至 `172.16.10.80`。按以下步骤操作： + +1. 为中控机设置 SSH 互信以及 sudo 规则。 + + 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.80` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/dm-ansible && + vi hosts.ini + ``` + + ``` + [servers] + 172.16.10.80 + + [all:vars] + username = tidb + ``` + + 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.80`。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook -i hosts.ini create_users.yml -u root -k + ``` + + 该步在 `172.16.10.80` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 + +2. 关闭待替换的 DM-master 实例。 + + > **注意：** + > + > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml --tags=dm-master + ``` + +3. 修改 `inventory.ini` 文件。注释或删除待替换实例所在行，同时为新 DM-master 实例添加相关信息。 + + ```ini + [dm_master_servers] + # dm_master ansible_host=172.16.10.71 + dm_master ansible_host=172.16.10.80 + ``` + +4. 部署新 DM-master 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml --tags=dm-master + ``` + +5. 启用新 DM-master 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml --tags=dm-master + ``` + +6. 更新 dmctl 配置文件。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dmctl + ``` + +## 替换/迁移 DM-worker 实例 + +假设机器 `172.16.10.72` 需要进行维护或者已崩溃，您需要将 `dm_worker1` 实例从 `172.16.10.72` 迁移至 `172.16.10.75`。按以下步骤操作： + +1. 为中控机设置 SSH 互信以及 sudo 规则。 + + 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.75` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 + + {{< copyable "shell-regular" >}} + + ```bash + cd /home/tidb/dm-ansible && + vi hosts.ini + ``` + + ``` + [servers] + 172.16.10.75 + + [all:vars] + username = tidb + ``` + + 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.85`。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook -i hosts.ini create_users.yml -u root -k + ``` + + 该步在 `172.16.10.75` 上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 + +2. 下线待替换 DM-worker 实例。 + + > **注意：** + > + > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook stop.yml --tags=dm-worker -l dm_worker1 + ``` + +3. 修改 `inventory.ini` 文件，为新 DM-worker 实例添加相关信息。 + + 修改 `inventory.ini` 文件。注释或删除旧 `dm_worker1` 实例所在行；同时为新 `dm_worker1` 实例添加相关信息。 + + 如果希望从不同的 binlog position 或 GTID Sets 拉取 relay log，则也需要更新对应的 `{relay_binlog_name}` 或 `{relay_binlog_gtid}`。 + + ```ini + [dm_worker_servers] + dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.75 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + # dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + + dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 + ``` + +4. 部署新 DM-worker 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook deploy.yml --tags=dm-worker -l dm_worker1 + ``` + +5. 迁移 relay log 数据。 + + - 如果待替换 DM-worker 实例所在机器仍能访问，则可直接将该实例的 `{dm_worker_relay_dir}` 目录下的所有数据复制到新 DM-worker 实例的对应目录。 + + - 如果待替换 DM-worker 实例所在机器已无法访问，可能需在第 9 步中手动恢复 relay log 目录等信息。 + +6. 启动新 DM-worker 实例。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook start.yml --tags=dm-worker -l dm_worker1 + ``` + +7. 配置并重启 DM-master 服务。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update.yml --tags=dm-master + ``` + +8. 配置并重启 Prometheus 服务。 + + {{< copyable "shell-regular" >}} + + ```bash + ansible-playbook rolling_update_monitor.yml --tags=prometheus + ``` + +9. 启动并验证数据迁移任务。 + + 使用 `start-task` 命令启动数据迁移任务，如果任务运行正常，则表示 DM-worker 迁移顺利完成；如果报类似如下错误，则需要对 relay log 目录进行手动修复。 + + ```log + fail to initial unit Sync of subtask test-task : UUID suffix 000002 with UUIDs [1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001] not found + ``` + + 如果待替换 DM-worker 所连接的上游 MySQL 已发生过切换，则会产生如上错误。此时可通过如下步骤手动修复： + + 1. 使用 `stop-task` 命令停止数据迁移任务。 + + 2. 通过 `$ ansible-playbook stop.yml --tags=dm-worker -l dm_worker1` 停止 DM-worker 实例。 + + 3. 更新 relay log 子目录的后缀，例如将 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 重命名为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 + + 4. 更新 relay log 子目录索引文件 `server-uuid.index`，例如将其中的内容由 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 变更为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 + + 5. 通过 `$ ansible-playbook start.yml --tags=dm-worker -l dm_worker1` 启动 DM-worker 实例。 + + 6. 再次启动并验证数据迁移任务。 diff --git a/dev/reference/tools/data-migration/configure/dm-master-configuration-file.md b/reference/tools/data-migration/configure/dm-master-configuration-file.md similarity index 100% rename from dev/reference/tools/data-migration/configure/dm-master-configuration-file.md rename to reference/tools/data-migration/configure/dm-master-configuration-file.md diff --git a/dev/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md b/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md similarity index 100% rename from dev/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md rename to reference/tools/data-migration/configure/dm-worker-configuration-file-full.md diff --git a/reference/tools/data-migration/configure/dm-worker-configuration-file.md b/reference/tools/data-migration/configure/dm-worker-configuration-file.md new file mode 100644 index 000000000000..6c94b3e253f6 --- /dev/null +++ b/reference/tools/data-migration/configure/dm-worker-configuration-file.md @@ -0,0 +1,67 @@ +--- +title: DM-worker 配置文件介绍 +category: reference +--- + +# DM-worker 配置文件介绍 + +本文档主要介绍 DM-worker 的基础配置文件。在一般场景中，用户只需要使用基础配置即可完成 DM-worker 的部署。 + +完整配置项参考 [DM-worker 完整配置说明](/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 + +## 配置文件示例 + +```toml +# Worker Configuration. + +# Log configuration. +log-file = "dm-worker.log" + +# DM-worker listen address. +worker-addr = ":8262" + +# Represents a MySQL/MariaDB instance or a replication group. +source-id = "mysql-replica-01" + +# Server id of slave for binlog replication. +# Each instance (master and slave) in replication group should have different server id. +server-id = 101 + +# flavor: mysql/mariadb +flavor = "mysql" + +# The directory that used to store relay log. +relay-dir = "./relay_log" + +[from] +host = "127.0.0.1" +user = "root" +password = "Up8156jArvIPymkVC+5LxkAT6rek" +port = 3306 +``` + +## 配置项说明 + +### Global 配置 + +| 配置项 | 说明 | +| :------------ | :--------------------------------------- | +| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | +| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。| +| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | +| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | +| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | +| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | + +### 数据库链接配置（from 配置项） + +| 配置项 | 说明 | +| :------------ | :--------------------------------------- | +| `host` | 上游数据库的 host。| +| `port` | 上游数据库的端口。 | +| `user` | 连接数据库使用的用户名。 | +| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | + +> **注意：** +> +> 以上配置为部署 DM-worker 的基础配置，一般情况下使用基础配置即可，更多配置项参考 [DM-worker 完整配置说明](/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 diff --git a/reference/tools/data-migration/configure/overview.md b/reference/tools/data-migration/configure/overview.md new file mode 100644 index 000000000000..f30768c31a83 --- /dev/null +++ b/reference/tools/data-migration/configure/overview.md @@ -0,0 +1,37 @@ +--- +title: DM 配置简介 +category: reference +--- + +# DM 配置简介 + +本文档简要介绍 DM (Data Migration) 的配置文件和数据同步任务的配置。 + +## 配置文件 + +- `inventory.ini`：使用 DM-Ansible 部署 DM 集群的配置文件。需要根据所选用的集群拓扑来进行编辑。详见[编辑 `inventory.ini` 配置文件](/how-to/deploy/data-migration-with-ansible.md#第-7-步编辑-inventoryini-配置文件)。 +- `dm-master.toml`：DM-master 进程的配置文件，包括 DM 集群的拓扑信息、MySQL 实例与 DM-worker 之间的关系（必须为一对一的关系）。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-master.toml` 文件，各项配置说明详见 [DM-master 配置文件介绍](/reference/tools/data-migration/configure/dm-master-configuration-file.md) +- `dm-worker.toml`：DM-worker 进程的配置文件，包括上游 MySQL 实例的配置和 relay log 的配置。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-worker.toml` 文件，各项配置说明详见 [DM-worker 配置文件介绍](/reference/tools/data-migration/configure/dm-worker-configuration-file.md) + +## 同步任务配置 + +### 任务配置文件 + +使用 DM-Ansible 部署 DM 集群时，`/conf` 中提供了任务配置文件模板：`task.yaml.exmaple` 文件。该文件是 DM 同步任务配置的标准文件，每一个具体的任务对应一个 `task.yaml` 文件。关于该配置文件的详细介绍，参见 [任务配置文件](/reference/tools/data-migration/configure/task-configuration-file.md)。 + +### 创建数据同步任务 + +你可以基于 `task.yaml.example` 文件来创建数据同步任务，具体步骤如下： + +1. 复制 `task.yaml.example` 为 `your_task.yaml`。 +2. 参考[任务配置文件](/reference/tools/data-migration/configure/task-configuration-file.md)来修改 `your_task.yaml` 文件。 +3. [使用 dmctl 创建数据同步任务](/reference/tools/data-migration/manage-tasks.md#创建数据同步任务)。 + +### 关键概念 + +DM 配置的关键概念如下： + +| 概念 | 解释 | 配置文件 | +| :------------ | :------------ | :------------------ | +| source-id | 唯一确定一个 MySQL 或 MariaDB 实例，或者一个具有主从结构的复制组，字符串长度不大于 32 | `inventory.ini` 的 `source_id`；
`dm-master.toml` 的 `source-id`；
`task.yaml` 的 `source-id` | +| DM-worker ID | 唯一确定一个 DM-worker（取值于 `dm-worker.toml` 的 `worker-addr` 参数） | `dm-worker.toml` 的 `worker-addr`；
dmctl 命令行的 `-worker` / `-w` flag | diff --git a/reference/tools/data-migration/configure/task-configuration-file-full.md b/reference/tools/data-migration/configure/task-configuration-file-full.md new file mode 100644 index 000000000000..0a7d922d8397 --- /dev/null +++ b/reference/tools/data-migration/configure/task-configuration-file-full.md @@ -0,0 +1,165 @@ +--- +title: DM 任务完整配置文件介绍 +category: reference +--- + +# DM 任务完整配置文件介绍 + +本文档主要介绍 Data Migration (DM) 的任务完整的配置文件 [`task_advanced.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_advanced.yaml)，包含[全局配置](#全局配置) 和[实例配置](#实例配置) 两部分。 + +关于各配置项的功能和配置，请参阅[数据同步功能](/reference/tools/data-migration/features/overview.md#同步功能介绍)。 + +## 关键概念 + +关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/reference/tools/data-migration/configure/overview.md#关键概念)。 + +## 完整配置文件示例 + +下面是一个完整的配置文件示例，通过该示例可以完成复杂的数据同步功能。 + +```yaml +--- + +# ----------- 全局配置 ----------- +## ********* 基本信息配置 ********* +name: test # 任务名称，需要全局唯一 +task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" +is-sharding: true # 是否为分库分表合并任务 +meta-schema: "dm_meta" # 下游储存 `meta` 信息的数据库 +remove-meta: false # 是否在任务同步开始前移除该任务名对应的 `meta`（`checkpoint` 和 `onlineddl` 等）。 +enable-heartbeat: false # 是否开启 `heartbeat` 功能 + +target-database: # 下游数据库实例配置 + host: "192.168.0.1" + port: 4000 + user: "root" + password: "" # 如果不为空则需经过 dmctl 加密 + + +## ******** 功能配置集 ********** + +routes: # 上游和下游表之间的路由 table routing 规则集 + route-rule-1: # 配置名称 + schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" + table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" + target-schema: "test" # 目标库名称 + target-table: "t" # 目标表名称 + route-rule-2: + schema-pattern: "test_*" + target-schema: "test" + +filters: # 上游数据库实例匹配的表的 binlog event filter 规则集 + filter-rule-1: # 配置名称 + schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" + table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" + events: ["truncate table", "drop table"] # 匹配哪些 event 类型 + action: Ignore # 对与符合匹配规则的 binlog 同步（Do）还是忽略(Ignore) + filter-rule-2: + schema-pattern: "test_*" + events: ["all dml"] + action: Do + +black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 + bw-rule-1: # 配置名称 + do-dbs: ["~^test.*", "user"] # 同步哪些库 + ignore-dbs: ["mysql", "account"] # 忽略哪些库 + do-tables: # 同步哪些表 + - db-name: "~^test.*" + tbl-name: "~^t.*" + - db-name: "user" + tbl-name: "information" + ignore-tables: # 忽略哪些表 + - db-name: "user" + tbl-name: "log" + +mydumpers: # mydumper 处理单元运行配置参数 + global: # 配置名称 + mydumper-path: "./bin/mydumper" # mydumper binary 文件地址，默认值为 "./bin/mydumper" + threads: 4 # mydumper 从上游数据库实例导出数据的线程数量，默认值为 4 + chunk-filesize: 64 # mydumper 生成的数据文件大小，默认值为 64，单位为 MB + skip-tz-utc: true # 忽略对时间类型数据进行时区转化，默认值为 true + extra-args: "--no-locks" # mydumper 的其他参数，在 v1.0.2 版本中 DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置 + +loaders: # loader 处理单元运行配置参数 + global: # 配置名称 + pool-size: 16 # loader 并发执行 mydumper 的 SQL 文件的线程数量，默认值为 16 + dir: "./dumped_data" # loader 读取 mydumper 输出文件的地址，同实例对应的不同任务必须不同（mydumper 会根据这个地址输出 SQL 文件），默认值为 "./dumped_data" + +syncers: # syncer 处理单元运行配置参数 + global: # 配置名称 + worker-count: 16 # syncer 并发同步 binlog event 的线程数量，默认值为 16 + batch: 100 # syncer 同步到下游数据库的一个事务批次 SQL 语句数，默认值为 100 + +# ----------- 实例配置 ----------- +mysql-instances: + - + source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 + meta: # `task-mode` 为 `incremental` 且下游数据库的 `checkpoint` 不存在时 binlog 同步开始的位置; 如果 checkpoint 存在，则以 `checkpoint` 为准 + binlog-name: binlog.000001 + binlog-pos: 4 + + route-rules: ["route-rule-1", "route-rule-2"] # 该上游数据库实例匹配的表到下游数据库的 table routing 规则名称 + filter-rules: ["filter-rule-1"] # 该上游数据库实例匹配的表的 binlog event filter 规则名称 + black-white-list: "bw-rule-1" # 该上游数据库实例匹配的表的 black & white list 过滤规则名称 + + mydumper-config-name: "global" # mydumper 配置名称 + loader-config-name: "global" # loader 配置名称 + syncer-config-name: "global" # Syncer 配置名称 + + - + source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 + mydumper-thread: 4 # mydumper 用于导出数据的线程数量，等同于 mydumper 处理单元配置中的 `threads`，在 v1.0.2 版本引入 + loader-thread: 16 # loader 用于导入数据的线程数量，等同于 loader 处理单元配置中的 `pool-size`, 在 v1.0.2 版本引入 + syncer-thread: 16 # syncer 用于同步增量数据的线程数量，等同于 syncer 处理单元配置中的 `worker-count`，在 v1.0.2 版本引入 +``` + +## 配置顺序 + +通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基本信息配置`和`实例配置`，配置顺序如下： + +1. 编辑[全局配置](#全局配置)。 +2. 根据全局配置编辑[实例配置](#实例配置)。 + +## 全局配置 + +### 任务基本信息配置 + +配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。其中 `task-mode` 需要特殊说明： + +`task-mode` + +- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 +- 值为字符串（`full`，`incremental` 或 `all`）。 + - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 + - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 + - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 + +### 功能配置集 + +全局配置主要包含下列功能配置集： + +| 配置项 | 说明 | +| :------------ | :--------------------------------------- | +| `routes` | 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/reference/tools/data-migration/features/overview.md#table-routing) | +| `filters` | 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/reference/tools/data-migration/features/overview.md#binlog-event-filter) | +| `black-white-list` | 该上游数据库实例匹配的表的 black & white list 过滤规则集。建议通过该项指定需要同步的库和表，否则会同步所有的库和表。使用场景及示例配置参见 [Black & White Lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists) | +| `mydumpers` | mydumper 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 | +| `loaders` | loader 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 | +| `syncers` | syncer 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 | + +各个功能配置集的参数及解释参见[完整配置文件示例](#完整配置文件示例)中的注释说明。 + +## 实例配置 + +本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 + +在该项配置中设置数据同步子任务中各个功能对应的配置集中的配置名称，关于这些配置项的更多配置细节，参见[功能配置集](#功能配置集)的相关配置项，对应关系如下： + +| 配置项 | 相关配置项 | +| :------ | :------------------ | +| `route-rules` | `routes` | +| `filter-rules` | `filters` | +| `black-white-list` | `black-white-list` | +| `mydumper-config-name` | `mydumpers` | +| `loader-config-name` | `loaders` | +| `syncer-config-name` | `syncers` | diff --git a/reference/tools/data-migration/configure/task-configuration-file.md b/reference/tools/data-migration/configure/task-configuration-file.md new file mode 100644 index 000000000000..9e5faf08369c --- /dev/null +++ b/reference/tools/data-migration/configure/task-configuration-file.md @@ -0,0 +1,82 @@ +--- +title: DM 任务配置文件介绍 +category: reference +--- + +# DM 任务配置文件介绍 + +本文档主要介绍 Data Migration (DM) 的任务基础配置文件 [`task_basic.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_basic.yaml)，包含[全局配置](#全局配置)和[实例配置](#实例配置)两部分。 + +完整的任务配置参见 [DM 任务完整配置文件介绍](/reference/tools/data-migration/configure/task-configuration-file-full.md) + +关于各配置项的功能和配置，请参阅[数据同步功能](/reference/tools/data-migration/features/overview.md)。 + +## 关键概念 + +关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/reference/tools/data-migration/configure/overview.md#关键概念)。 + +## 基础配置文件示例 + +下面是一个基础的配置文件示例，通过该示例可以完成简单的数据同步功能。 + +```yaml +--- + +# ----------- 全局配置 ----------- +## ********* 基本信息配置 ********* +name: test # 任务名称，需要全局唯一 +task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" + +target-database: # 下游数据库实例配置 + host: "127.0.0.1" + port: 4000 + user: "root" + password: "" # 如果不为空则需经过 dmctl 加密 + +## ******** 功能配置集 ********** +black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 + bw-rule-1: # 黑白名单配置的名称 + do-dbs: ["all_mode"] # 同步哪些库 + +# ----------- 实例配置 ----------- +mysql-instances: + - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 + black-white-list: "bw-rule-1" # 黑白名单配置名称 + mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 + loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 + syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 + + - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 + black-white-list: "bw-rule-1" # 黑白名单配置名称 + mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 + loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 + syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 +``` + +## 配置顺序 + +通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基础信息配置`和`功能配置集`，配置顺序如下： + +1. 编辑[全局配置](#全局配置)。 +2. 根据全局配置编辑[实例配置](#实例配置)。 + +## 全局配置 + +### 任务基本信息配置 + +配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。关于 `task-mode` 的特殊说明如下： + +- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 +- 值为字符串（`full`，`incremental` 或 `all`）。 + - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 + - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 + - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 + +### 功能配置集 + +对于一般的业务场景，只需要配置黑白名单过滤规则集，配置说明参见以上示例配置文件中 `black-white-list` 的注释以及 [Black & white table lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists) + +## 实例配置 + +本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 +配置项说明参见以上示例配置文件中 `mysql-instances` 的注释。 diff --git a/reference/tools/data-migration/deploy.md b/reference/tools/data-migration/deploy.md new file mode 100644 index 000000000000..13a8a12546e7 --- /dev/null +++ b/reference/tools/data-migration/deploy.md @@ -0,0 +1,186 @@ +--- +title: 使用 DM 同步数据 +category: reference +--- + +# 使用 DM 同步数据 + +本文介绍如何使用 DM (Data Migration) 同步数据。 + +## 第 1 步：部署 DM 集群 + +目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照 [使用 DM-Ansible 部署 DM 集群](/how-to/deploy/data-migration-with-ansible.md)；也可以使用 binary 部署 DM 集群用于体验或者测试，具体部署方法参照[使用 DM binary 部署 DM 集群](/how-to/deploy/data-migration-with-binary.md)。 + +> **注意：** +> +> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 +> - 上下游数据库用户必须拥有相应的读写权限。 + +## 第 2 步：检查集群信息 + +使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： + +- DM 集群相关组件配置信息 + + | 组件 | 主机 | 端口 | + |:------|:---- |:---- | + | dm_worker1 | 172.16.10.72 | 8262 | + | dm_worker2 | 172.16.10.73 | 8262 | + | dm_master | 172.16.10.71 | 8261 | + +- 上下游数据库实例相关信息 + + | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | + |:-------- |:--- | :--- | :--- | :--- | + | 上游 MySQL-1 | 172.16.10.81 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | + | 上游 MySQL-2 | 172.16.10.82 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | + | 下游 TiDB | 172.16.10.83 | 4000 | root | | + +- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 + + ```toml + # Master 配置 + + [[deploy]] + source-id = "mysql-replica-01" + dm-worker = "172.16.10.72:8262" + + [[deploy]] + source-id = "mysql-replica-02" + dm-worker = "172.16.10.73:8262" + ``` + + > **注意：** + > + > `{ansible deploy}/conf/dm-master.toml` 中的 `{ansible deploy}` 表示使用 DM-Ansible 部署 DM 时通过 `deploy_dir` 参数指定的目录。 + +## 第 3 步：配置任务 + +假设需要将 MySQL-1 和 MySQL-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 + +复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： + +```yaml +# 任务名，多个同时运行的任务不能重名。 +name: "test" +# 全量+增量 (all) 同步模式。 +task-mode: "all" +# 下游 TiDB 配置信息。 +target-database: + host: "172.16.10.83" + port: 4000 + user: "root" + password: "" + +# 当前数据同步任务需要的全部上游 MySQL 实例配置。 +mysql-instances: +- + # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 + source-id: "mysql-replica-01" + # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 + black-white-list: "global" + # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 + mydumper-config-name: "global" + +- + source-id: "mysql-replica-02" + black-white-list: "global" + mydumper-config-name: "global" + +# 黑白名单全局配置，各实例通过配置项名引用。 +black-white-list: + global: + do-tables: # 需要同步的上游表的白名单。 + - db-name: "test_db" # 需要同步的表的库名。 + tbl-name: "test_table" # 需要同步的表的名称。 + +# Mydumper 全局配置，各实例通过配置项名引用。 +mydumpers: + global: + mydumper-path: "./bin/mydumper" # Mydumper 二进制文件的路径。 + extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 +``` + +## 第 4 步：启动任务 + +为了提前发现数据同步任务的一些配置错误，DM 中增加了[前置检查](/reference/tools/data-migration/precheck.md)功能： + +- 启动数据同步任务时，DM 自动检查相应的权限和配置。 +- 也可使用 `check-task` 命令手动前置检查上游的 MySQL 实例配置是否符合 DM 的配置要求。 + +> **注意：** +> +> 第一次启动数据同步任务时，必须确保上游数据库已配置。否则，启动任务时会报错。 + +1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/`。 + +2. 执行以下命令启动 dmctl。 + + {{< copyable "shell-regular" >}} + + ```bash + ./dmctl --master-addr 172.16.10.71:8261 + ``` + +3. 执行以下命令启动数据同步任务。其中，`task.yaml` 是之前编辑的配置文件。 + + {{< copyable "" >}} + + ```bash + » start-task ./task.yaml + ``` + + - 如果执行该命令后返回的结果如下，则表明任务已成功启动。 + + ```json + { + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "172.16.10.72:8262", + "msg": "" + }, + { + "result": true, + "worker": "172.16.10.73:8262", + "msg": "" + } + ] + } + ``` + + - 如果任务启动失败，可根据返回结果的提示进行配置变更后执行 `start-task task.yaml` 命令重新启动任务。 + +## 第 5 步：查询任务 + +如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： + +{{< copyable "" >}} + +```bash +» query-status +``` + +## 第 6 步：停止任务 + +如果不再需要进行数据同步，可以在 dmctl 内使用以下命令停止同步任务： + +{{< copyable "" >}} + +```bash +» stop-task test +``` + +其中的 `test` 是 `task.yaml` 配置文件中 `name` 配置项设置的任务名。 + +## 第 7 步：监控任务与查看日志 + +如果使用 DM-Ansible 部署 DM 集群时，正确部署了 Prometheus 与 Grafana，且 Grafana 的地址为 `172.16.10.71`，可在浏览器中打开 进入 Grafana，选择 DM 的 dashboard 即可查看 DM 相关监控项。 + +DM 在运行过程中，DM-worker, DM-master 及 dmctl 都会通过日志输出相关信息。各组件的日志目录如下： + +- DM-master 日志目录：通过 DM-master 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-master 节点的 `{ansible deploy}/log/dm-master.log`。 +- DM-worker 日志目录：通过 DM-worker 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-worker 节点的 `{ansible deploy}/log/dm-worker.log`。 +- dmctl 日志目录：与其二进制文件目录相同。 diff --git a/reference/tools/data-migration/dm-portal.md b/reference/tools/data-migration/dm-portal.md new file mode 100644 index 000000000000..6591842694ce --- /dev/null +++ b/reference/tools/data-migration/dm-portal.md @@ -0,0 +1,220 @@ +--- +title: DM Portal 简介 +category: reference +--- + +# DM Portal 简介 + +当前版本的 DM 提供了丰富多样的功能特性，包括 [Table routing](/reference/tools/data-migration/features/overview.md#table-routing)，[Black & white table lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists)，[Binlog event filter](/reference/tools/data-migration/features/overview.md#binlog-event-filter) 等。但这些功能特性同时也增加了用户使用 DM 的复杂度，尤其在编写 [DM 任务配置](/reference/tools/data-migration/configure/task-configuration-file.md)的时候。 + +针对这个问题，DM 提供了一个精简的网页程序 DM Portal，能够帮助用户以可视化的方式去配置需要的同步任务，并且生成可以直接让 DM 直接执行的 `task.yaml` 文件。 + +## 功能描述 + +### 同步模式配置 + +支持 DM 的三种同步模式： + +- 全量同步 +- 增量同步 +- All（全量+增量） + +### 实例信息配置 + +支持配置库表同步路由方式，能够支持 DM 中分库分表合并的配置方式。 + +### binlog 过滤配置 + +支持对数据库、数据表配置 binlog event 过滤。 + +### 配置文件生成 + +支持配置文件创建，能够将配置文件下载到本地并且同时会在 dm-portal 服务器的 `/tmp/` 目录下自动创建。 + +### 使用限制 + +当前的 DM 配置可视化生成页面能够覆盖绝大部分的 DM 配置场景，但也有一定的使用限制： + +- 不支持 [Binlog event filter](/reference/tools/data-migration/features/overview.md#binlog-event-filter) 的 SQL pattern 方式 +- 编辑功能不支持解析用户之前写的 `task.yaml` 文件，页面只能编辑由页面生成的 `task.yaml` 文件 +- 编辑功能不支持修改实例配置信息，如果用户需要调整实例配置，需要重新生成 `task.yaml` 文件 +- 页面的上游实例配置仅用于获取上游库表结构，DM-worker 里依旧需要配置对应的上游实例信息 +- 生成的 `task.yaml` 中，默认 mydumper-path 为 `./bin/mydumper`，如果实际使用其他路径，需要在生成的配置文件中进行手动修改。 + +## 部署使用 + +### Binary 部署 + +DM Portal 可以在 [dm-portal-latest-linux-amd64.tar.gz](https://download.pingcap.org/dm-portal-latest-linux-amd64.tar.gz) 下载，通过 `./dm-portal` 的命令即可直接启动。 + +* 如果在本地启动，浏览器访问 `127.0.0.1:8280` 即可使用。 +* 如果在服务器上启动，需要为服务器上配置访问代理。 + +### DM Ansible 部署 + +可以使用 DM Ansible 部署 DM Portal，具体部署方法参照[使用 DM Ansible 部署 DM 集群](/how-to/deploy/data-migration-with-ansible.md)。 + +## 使用说明 + +### 新建规则 + +#### 功能描述 + +用于新建一个 `task.yaml` 文件，需要选择同步模式、配置上下游实例、配置库表路由，配置 binlog 过滤。 + +#### 操作步骤 + +登录 dm-portal 页面，点击**新建任务规则**。 + +### 基础信息配置 + +#### 功能描述 + +用于填写任务名称，以及选择任务类型。 + +#### 前置条件 + +已选择**新建同步规则**。 + +#### 操作步骤 + +1. 填写任务名称。 +2. 选择任务类型。 + +![DM Portal BasicConfig](/media/dm-portal-basicconfig.png) + +### 实例信息配置 + +#### 功能描述 + +用于配置上下游实例信息，包括 Host、Port、Username、Password。 + +#### 前置条件 + +已填写任务名称和选择任务类型。 + +#### 注意事项 + +如果任务类型选择**增量**或者 **All**，在配置上游实例信息时候，还需要配置 binlog-file 和 binlog-pos。 + +#### 操作步骤 + +1. 填写上游实例信息。 +2. 填写下游实例信息。 +3. 点击**下一步**。 + +![DM Portal InstanceConfig](/media/dm-portal-instanceconfig.png) + +### binlog 过滤配置 + +#### 功能描述 + +用于配置上游的 binlog 过滤，可以选择需要过滤的 DDL/DML，并且在数据库上配置的 filter 后会自动给其下的数据表继承。 + +#### 前置条件 + +已经配置好上下游实例信息并且连接验证没问题。 + +#### 注意事项 + +* binlog 过滤配置只能在上游实例处进行修改编辑，一旦数据库或者数据表被移动到下游实例后，就不可以进行修改编辑。 +* 在数据库上配置的 binlog 过滤会自动被其下的数据表继承。 + +#### 操作步骤 + +1. 点击需要配置的数据库或者数据表。 +2. 点击编辑按钮，选择需要过滤的 binlog 类型。 + +![DM Portal InstanceShow](/media/dm-portal-instanceshow.png) + +![DM Portal BinlogFilter 1](/media/dm-portal-binlogfilter-1.png) + +![DM Portal BinlogFilter 2](/media/dm-portal-binlogfilter-2.png) + +### 库表路由配置 + +#### 功能描述 + +可以选择需要同步的数据库和数据表，并且进行修改名称、合并库、合并表等操作。可以对上一步操作进行撤销，可以对库表路由配置进行全部重置。在完成任务配置后，DM Portal 会帮忙生成对应的 `task.yaml` 文件。 + +#### 前置条件 + +* 已经配置好需要的 binlog 过滤规则。 + +#### 注意事项 + +* 在合并库表操作的时候，不允许批量操作，只能逐一拖动。 +* 在合表库表操作的时候，只能对数据表进行拖动操作，不能对数据库进行数据库进行拖动操作。 + +#### 操作步骤 + +1. 在**上游实例**处，选择需要同步的数据库和数据表。 +2. 点击移动按钮，将需要同步的库表移动至**下游实例**处。 +3. 点击右键按钮，可以对库表进行改名操作。 +4. 选中需要操作的数据表，可以拖动至别的数据表图标上创建出合并表；可以拖动到数据库图标上移动至该库下；可以拖动到 target-instance 图标上移动到一个新的数据库下。 +5. 点击**完成**，自动下载 `task.yaml` 到本地，并且在 DM Portal 服务器上的 `/tmp/` 目录下自动创建一份 `task.yaml` 配置文件。 + +##### 移动同步库表 + +![DM Portal TableRoute 1](/media/dm-portal-tableroute-1.png) + +![DM Portal TableRoute 2](/media/dm-portal-tableroute-2.png) + +##### 右键修改库表名称 + +![DM Portal ChangeTableName](/media/dm-portal-changetablename.png) + +##### 合并数据表操作 + +![DM Portal MergeTable 1](/media/dm-portal-mergetable-1.png) + +![DM Portal MergeTable 2](/media/dm-portal-mergetable-2.png) + +##### 移动数据表至其他数据库 + +![DM Portal MoveToDB 1](/media/dm-portal-movetodb-1.png) + +![DM Portal MoveToDB 2](/media/dm-portal-movetodb-2.png) + +##### 移动数据表至新建默认数据库 + +![DM Portal MoveToNewDB 1](/media/dm-portal-movetonewdb-1.png) + +![DM Portal MoveToNewDB 2](/media/dm-portal-movetonewdb-2.png) + +##### 撤销本次操作 + +![DM Portal Revert](/media/dm-portal-revert.png) + +##### 清空下游实例 + +![DM Portal Reset](/media/dm-portal-reset.png) + +##### 完成并下载 + +![DM Portal GenerateConfig](/media/dm-portal-generateconfig.png) + +### 编辑规则 + +#### 功能描述 + +可以将之前创建的 `task.yaml` 上传后，解析出来之前的填写的配置信息，对部分配置进行修改。 + +#### 前置条件 + +* 已经创建出 `task.yaml` 文件。 +* 非 DM Portal 创建出来的 `task.yaml` 文件不可使用。 + +#### 注意事项 + +* 不允许修改实例配置信息 + +#### 操作步骤 + +1. 在首页，点击**编辑同步规则**。 +2. 选择上传 `task.yaml` 文件。 +3. 解析成功后，页面会自动跳转。 + +![DM Portal EditConfig](/media/dm-portal-editconfig.png) + +![DM Portal UploadConfig](/media/dm-portal-uploadconfig.png) diff --git a/reference/tools/data-migration/dm-upgrade.md b/reference/tools/data-migration/dm-upgrade.md new file mode 100644 index 000000000000..16bd62e22fee --- /dev/null +++ b/reference/tools/data-migration/dm-upgrade.md @@ -0,0 +1,161 @@ +--- +title: DM 版本升级 +category: reference +--- + +# DM 版本升级 + +本文档主要介绍各 DM (Data Migration) 版本间的升级操作步骤。 + +> **注意：** +> +> - 若无特殊说明，各版本的升级操作均为从前一个有升级指引的版本向当前版本升级。 +> - 若无特殊说明，各升级操作示例均假定已经下载了对应版本的 DM 和 DM-Ansible 且 DM binary 存在于 DM-Ansible 的相应目录中（下载 DM binary 可以参考[更新组件版本](/reference/tools/data-migration/cluster-operations.md#更新组件版本)）。 +> - 若无特殊说明，各升级操作示例均假定升级前已停止所有同步任务，升级完成后手动重新启动所有同步任务。 +> - 以下版本升级指引逆序展示。 + +## 升级到 v1.0.3 + +### 版本信息 + +```bash +Release Version: v1.0.3 +Git Commit Hash: 41426af6cffcff9a325697a3bdebeadc9baa8aa6 +Git Branch: release-1.0 +UTC Build Time: 2019-12-13 07:04:53 +Go Version: go version go1.13 linux/amd64 +``` + +### 主要变更 + +- dmctl 支持命令式使用 +- 支持同步 `ALTER DATABASE` DDL 语句 +- 优化 DM 错误提示信息 +- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 +- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 + +### 升级操作示例 + +1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.3` +2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 +3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 +4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 + +> **注意：** +> +> 更新至 DM 1.0.3 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 + +## 升级到 v1.0.2 + +### 版本信息 + +```bash +Release Version: v1.0.2 +Git Commit Hash: affc6546c0d9810b0630e85502d60ed5c800bf25 +Git Branch: release-1.0 +UTC Build Time: 2019-10-30 05:08:50 +Go Version: go version go1.12 linux/amd64 +``` + +### 主要变更 + +- 支持自动为 DM-worker 生成部分配置项，减少人工配置成本 +- 支持自动生成 mydumper 库表参数，减少人工配置成本 +- 优化 `query-status` 默认输出，突出重点信息 +- 直接管理到下游的 DB 连接而不是使用内置连接池，优化 SQL 错误处理与重试 +- 修复 DM-worker 进程启动时、执行 DML 失败时可能 panic 的 bug +- 修复执行 sharding DDL（如 `ADD INDEX`）超时后可能造成后续 sharding DDL 无法正确协调的 bug +- 修复了有部分 DM-worker 不可访问时无法 `start-task` 的 bug +- 完善了对 1105 错误的自动重试策略 + +### 升级操作示例 + +1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.2` +2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 +3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 +4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 + +> **注意：** +> +> 更新至 DM 1.0.2 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 + +## 升级到 v1.0.1 + +### 版本信息 + +```bash +Release Version: v1.0.1 +Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 +Git Branch: release-1.0 +UTC Build Time: 2019-09-10 06:15:05 +Go Version: go version go1.12 linux/amd64 +``` + +### 主要变更 + +- 修复某些情况下 DM 会频繁重建数据库连接的问题 +- 修复使用 `query-status` 时潜在的 panic 问题 + +### 升级操作示例 + +1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.1` +2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 +3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 +4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 + +> **注意：** +> +> 更新至 DM 1.0.1 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 + +## 升级到 v1.0.0-10-geb2889c9 (1.0 GA) + +### 版本信息 + +```bash +Release Version: v1.0.0-10-geb2889c9 +Git Commit Hash: eb2889c9dcfbff6653be9c8720a32998b4627db9 +Git Branch: release-1.0 +UTC Build Time: 2019-09-06 03:18:48 +Go Version: go version go1.12 linux/amd64 +``` + +### 主要变更 + +- 常见的异常场景支持自动尝试恢复同步任务 +- 提升 DDL 语法兼容性 +- 修复上游数据库连接异常时可能丢失数据的 bug + +### 升级操作示例 + +1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.0` +2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 +3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 +4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 + +> **注意：** +> +> 更新至 DM 1.0 GA 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 + +## 升级到 v1.0.0-rc.1-12-gaa39ff9 + +### 版本信息 + +```bash +Release Version: v1.0.0-rc.1-12-gaa39ff9 +Git Commit Hash: aa39ff981dfb3e8c0fa4180127246b253604cc34 +Git Branch: dm-master +UTC Build Time: 2019-07-24 02:26:08 +Go Version: go version go1.11.2 linux/amd64 +``` + +### 主要变更 + +从此版本开始，将对所有的配置进行严格检查，遇到无法识别的配置会报错，以确保用户始终准确地了解自己的配置。 + +### 升级操作示例 + +启动 DM-master 或 DM-worker 前，必须确保已经删除废弃的配置信息，且没有多余的配置项，否则会启动失败。可根据失败信息删除多余的配置。 +可能遗留的废弃配置： + +- `dm-worker.toml` 中的 `meta-file` +- `task.yaml` 中的 `mysql-instances` 中的 `server-id` diff --git a/dev/reference/tools/data-migration/dm-worker-intro.md b/reference/tools/data-migration/dm-worker-intro.md similarity index 100% rename from dev/reference/tools/data-migration/dm-worker-intro.md rename to reference/tools/data-migration/dm-worker-intro.md diff --git a/reference/tools/data-migration/faq.md b/reference/tools/data-migration/faq.md new file mode 100644 index 000000000000..c6ac428d6611 --- /dev/null +++ b/reference/tools/data-migration/faq.md @@ -0,0 +1,52 @@ +--- +title: Data Migration 常见问题 +category: reference +aliases: ['/docs-cn/dev/faq/data-migration/'] +--- + +# Data Migration 常见问题 + +## DM 是否支持同步阿里 RDS 以及其他云数据库的数据？ + +DM 仅支持解析标准版本的 MySQL/MariaDB 的 binlog，对于阿里云 RDS 以及其他云数据库没有进行过测试，如果确认其 binlog 为标准格式，则可以支持。 + +## task 配置中的黑白名单的正则表达式是否支持`非获取匹配`（?!）？ + +目前不支持，DM 仅支持 golang 标准库的正则，可以通过 [re2-syntax](https://github.com/google/re2/wiki/Syntax) 了解 golang 支持的正则表达式。 + +## 如果在上游执行的一个 statement 包含多个 DDL 操作，DM 是否支持同步？ + +DM 会尝试将包含多个 DDL 变更操作的单条语句拆分成只包含一个 DDL 操作的多条语句，但是可能没有覆盖所有的场景。建议在上游执行的一条 statement 中只包含一个 DDL 操作，或者在测试环境中验证一下，如果不支持，可以给 DM 提 [issue](https://github.com/pingcap/dm/issues)。 + +## 如何处理不兼容的 DDL 语句？ + +你需要使用 dmctl 手动处理 TiDB 不兼容的 DDL 语句（包括手动跳过该 DDL 语句或使用用户指定的 DDL 语句替换原 DDL 语句，详见[跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句](/reference/tools/data-migration/skip-replace-sqls.md)）。 + +> **注意：** +> +> TiDB 目前并不兼容 MySQL 支持的所有 DDL 语句。 + +## 如何重置数据同步任务？ + +在以下情况中，你需要重置整个数据同步任务： + +- 上游数据库中人为执行了 `RESET MASTER`，造成 relay log 同步出错 + +- relay log 或上游 binlog event 损坏或者丢失 + +此时，relay 处理单元通常会发生错误而退出，且无法优雅地自动恢复，因此需要通过手动方式恢复数据同步： + +1. 使用 `stop-task` 命令停止当前正在运行的所有同步任务。 + +2. 使用 Ansible [停止整个 DM 集群](/how-to/deploy/data-migration-with-ansible.md#第-10-步关闭-dm-集群)。 + +3. 手动清理掉与 binlog event 被重置的 MySQL master 相对应的 DM-worker 的 relay log 目录。 + + - 如果是使用 Ansible 部署，relay log 目录即 `/relay_log` 目录。 + - 如果是使用二进制文件手动部署，relay log 目录即 relay-dir 参数设置的目录。 + +4. 清理掉下游已同步的数据。 + +5. 使用 Ansible [启动整个 DM 集群](/how-to/deploy/data-migration-with-ansible.md#第-9-步部署-dm-集群)。 + +6. 以新的任务名重启数据同步任务，或设置 `remove-meta` 为 `true` 且 `task-mode` 为 `all`。 diff --git a/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md b/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md new file mode 100644 index 000000000000..76ebc115e378 --- /dev/null +++ b/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md @@ -0,0 +1,540 @@ +--- +title: 手动处理 Sharding DDL Lock +category: reference +--- + +# 手动处理 Sharding DDL Lock + +DM (Data Migration) 使用 sharding DDL lock 来确保分库分表的 DDL 操作可以正确执行。绝大多数情况下，该锁定机制可自动完成；但在部分异常情况发生时，需要使用 `unlock-ddl-lock`/`break-ddl-lock` 手动处理异常的 DDL lock。 + +> **注意：** +> +> - 不要轻易使用 `unlock-ddl-lock`/`break-ddl-lock` 命令，除非完全明确当前场景下使用这些命令可能会造成的影响，并能接受这些影响。 +> - 在手动处理异常的 DDL lock 前，请确保已经了解 DM 的[分库分表合并同步原理](/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)。 + +## 命令介绍 + +### `show-ddl-locks` + +该命令用于查询当前 DM-master 上存在的 DDL lock 信息。 + +#### 命令示例 + +{{< copyable "shell-regular" >}} + +```bash +show-ddl-locks [--worker=127.0.0.1:8262] [task-name] +``` + +#### 参数解释 + ++ `worker`： + - flag 参数，string，`--worker`，可选 + - 不指定时，查询所有 DM-worker 相关的 lock 信息；指定时，仅查询与这组 DM-worker 相关的 lock 信息，可重复多次指定 + ++ `task-name`： + - 非 flag 参数，string，可选 + - 不指定时，查询与所有任务相关的 lock 信息；指定时，仅查询特定任务相关的 lock 信息 + +#### 返回结果示例 + +{{< copyable "shell-regular" >}} + +```bash +show-ddl-locks test +``` + +``` +{ + "result": true, # 查询 lock 操作本身是否成功 + "msg": "", # 查询 lock 操作失败时的原因或其它描述信息（如不存在任务 lock） + "locks": [ # DM-master 上存在的 lock 信息列表 + { + "ID": "test-`shard_db`.`shard_table`", # lock 的 ID 标识，当前由任务名与 DDL 对应的 schema/table 信息组成 + "task": "test", # lock 所属的任务名 + "owner": "127.0.0.1:8262", # lock 的 owner（第一个遇到该 DDL 的 DM-worker） + "DDLs": [ # lock 对应的 DDL 列表 + "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;" + ], + "synced": [ # 已经收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 + "127.0.0.1:8262" + ], + "unsynced": [ # 尚未收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 + "127.0.0.1:8263" + ] + } + ] +} +``` + +### `unlock-ddl-lock` + +该命令用于主动请求 DM-master 解除指定的 DDL lock，包括的操作：请求 owner 执行 DDL 操作，请求其他非 owner 的 DM-worker 跳过 DDL 操作，移除 DM-master 上的 lock 信息。 + +#### 命令示例 + +{{< copyable "shell-regular" >}} + +```bash +unlock-ddl-lock [--worker=127.0.0.1:8262] [--owner] [--force-remove] +``` + +#### 参数解释 + ++ `worker`： + - flag 参数，string，`--worker`，可选 + - 不指定时，对所有已经在等待该 lock 的 DM-worker 发起跳过 DDL 操作请求；指定时，仅对这组 DM-worker 发起跳过 DDL 操作请求，可重复多次指定 + ++ `owner`： + - flag 参数，string，`--owner`，可选 + - 不指定时，请求默认的 owner（`show-ddl-locks` 返回结果中的 `owner`）执行 DDL 操作；指定时，请求该 DM-worker（替代默认的 owner）执行 DDL 操作 + ++ `force-remove`： + - flag 参数，boolean，`--force-remove`，可选 + - 不指定时，仅在 owner 执行 DDL 成功时移除 lock 信息；指定时，即使 owner 执行 DDL 失败也强制移除 lock 信息（此后将无法再次查询或操作该 lock） + ++ `lock-ID`： + - 非 flag 参数，string，必选 + - 指定需要执行 unlock 操作的 DDL lock ID（即 `show-ddl-locks` 返回结果中的 `ID`） + +#### 返回结果示例 + +{{< copyable "shell-regular" >}} + +```bash +unlock-ddl-lock test-`shard_db`.`shard_table` +``` + +``` +{ + "result": true, # unlock lock 操作是否成功 + "msg": "", # unlock lock 操作失败时的原因 + "workers": [ # 各 DM-worker 执行/跳过 DDL 操作结果信息列表 + { + "result": true, # 该 DM-worker 执行/跳过 DDL 操作是否成功 + "worker": "127.0.0.1:8262", # DM-worker 地址 (DM-worker ID) + "msg": "" # DM-worker 执行/跳过 DDL 失败时的原因 + } + ] +} +``` + +### break-ddl-lock + +该命令用于主动请求 DM-worker 强制打破当前正在等待 unlock 的 DDL lock，包括请求 DM-worker 执行或跳过 DDL 操作、移除该 DM-worker 上的 DDL lock 信息。 + +#### 命令示例 + +{{< copyable "shell-regular" >}} + +```bash +break-ddl-lock <--worker=127.0.0.1:8262> [--remove-id] [--exec] [--skip] +``` + +#### 参数解释 + ++ `worker`： + - flag 参数，string，`--worker`，必选 + - 指定需要执行 break 操作的 DM-worker + ++ `remove-id`：已废弃 + ++ `exec`： + - flag 参数，boolean，`--exec`，可选 + - 不可与 `--skip` 参数同时指定 + - 指定时，请求该 DM-worker 执行（execute）当前 lock 对应的 DDL + ++ `skip`： + - flag 参数，boolean，`--skip`，可选 + - 不可与 `--exec` 参数同时指定 + - 指定时，请求该 DM-worker 跳过（skip）当前 lock 对应的 DDL + ++ `task-name`： + - 非 flag 参数，string，必选 + - 指定要执行 break 操作的 lock 所在的 task 名称（要查看各 task 上是否存在 lock，可通过 [query-status](/reference/tools/data-migration/query-status.md) 获得） + +#### 返回结果示例 + +{{< copyable "shell-regular" >}} + +```bash +break-ddl-lock -w 127.0.0.1:8262 --exec test +``` + +``` +{ + "result": true, # break lock 操作是否成功 + "msg": "", # break lock 操作失败时的原因 + "workers": [ # 执行 break lock 操作的 DM-worker 列表（当前单次操作仅支持对一个 DM-worker 执行 break lock） + { + "result": false, # 该 DM-worker break lock 操作是否成功 + "worker": "127.0.0.1:8262", # 该 DM-worker 地址 (DM-worker ID) + "msg": "" # DM-worker break lock 失败时的原因 + } + ] +} +``` + +## 支持场景 + +目前，使用 `unlock-ddl-lock`/`break-ddl-lock` 命令仅支持处理以下三种 sharding DDL lock 异常情况。 + +### 场景一：部分 DM-worker 下线 + +#### Lock 异常原因 + +在 DM-master 尝试自动 unlock sharding DDL lock 之前，需要等待所有 DM-worker 的 sharding DDL events 全部到达（详见[分库分表合并同步原理](/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)）。如果 sharding DDL 已经在同步过程中，且有部分 DM-worker 下线，并且不再计划重启它们（按业务需求移除了这部分 DM-worker），则会由于永远无法等齐所有的 DDL 而造成 lock 无法自动 unlock。 + +#### 手动处理示例 + +假设上游有 MySQL-1 和 MySQL-2 两个实例，其中 MySQL-1 中有 `shard_db_1`.`shard_table_1` 和 `shard_db_1`.`shard_table_2` 两个表，MySQL-2 中有 `shard_db_2`.`shard_table_1` 和 `shard_db_2`.`shard_table_2` 两个表。现在需要将这 4 个表合并后同步到下游 TiDB 的 `shard_db`.`shard_table` 表中。 + +初始表结构如下： + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE shard_db_1.shard_table_1; +``` + +``` ++---------------+------------------------------------------+ +| Table | Create Table | ++---------------+------------------------------------------+ +| shard_table_1 | CREATE TABLE `shard_table_1` ( + `c1` int(11) NOT NULL, + PRIMARY KEY (`c1`) +) ENGINE=InnoDB DEFAULT CHARSET=latin1 | ++---------------+------------------------------------------+ +``` + +上游分表将执行以下 DDL 语句变更表结构： + +{{< copyable "sql" >}} + +```sql +ALTER TABLE shard_db_*.shard_table_* ADD COLUMN c2 INT; +``` + +MySQL 及 DM 操作与处理流程如下： + +1. MySQL-1 对应的 DM-worker-1 的两个分表执行了对应的 DDL 操作进行表结构变更。 + + {{< copyable "sql" >}} + + ```sql + ALTER TABLE shard_db_1.shard_table_1 ADD COLUMN c2 INT; + ``` + + {{< copyable "sql" >}} + + ```sql + ALTER TABLE shard_db_1.shard_table_2 ADD COLUMN c2 INT; + ``` + +2. DM-worker-1 接受到两个分表的 DDL 之后，将对应 MySQL-1 相关的 DDL 信息发送给 DM-master，DM-master 创建相应的 DDL lock。 +3. 使用 `show-ddl-lock` 查看当前的 DDL lock 信息。 + + {{< copyable "shell-regular" >}} + + ```bash + show-ddl-locks test + ``` + + ``` + { + "result": true, + "msg": "", + "locks": [ + { + "ID": "test-`shard_db`.`shard_table`", + "task": "test", + "owner": "127.0.0.1:8262", + "DDLs": [ + "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" + ], + "synced": [ + "127.0.0.1:8262" + ], + "unsynced": [ + "127.0.0.1:8263" + ] + } + ] + } + ``` + +4. 由于业务需要，DM-worker-2 对应的 MySQL-2 的数据不再需要同步到下游 TiDB，对 DM-worker-2 执行了下线处理。 +5. DM-master 上 ID 为 ```test-`shard_db`.`shard_table` ``` 的 lock 无法等到 DM-worker-2 的 DDL 操作信息。 + + `show-ddl-locks` 返回的 `unsynced` 中一直包含 DM-worker-2 的信息（`127.0.0.1:8263`）。 + +6. 使用 `unlock-dll-lock` 来请求 DM-master 主动 unlock 该 DDL lock。 + + - 如果 DDL lock 的 owner 也已经下线，可以使用 `--owner` 参数指定其他 DM-worker 作为新 owner 来执行 DDL。 + - 当存在任意 DM-worker 报错时，`result` 将为 `false`，此时请仔细检查各 DM-worker 的错误是否是预期可接受的。 + - 已下线的 DM-worker 会返回 `rpc error: code = Unavailable` 错误属于预期行为，可以忽略。 + - 如果其它未下线的 DM-worker 返回错误，则需要根据情况额外处理。 + + {{< copyable "shell-regular" >}} + + ```bash + unlock-ddl-lock test-`shard_db`.`shard_table` + ``` + + ``` + { + "result": false, + "msg": "github.com/pingcap/tidb-enterprise-tools/dm/master/server.go:1472: DDL lock test-`shard_db`.`shard_table` owner ExecuteDDL successfully, so DDL lock removed. but some dm-workers ExecuteDDL fail, you should to handle dm-worker directly", + "workers": [ + { + "result": true, + "worker": "127.0.0.1:8262", + "msg": "" + }, + { + "result": false, + "worker": "127.0.0.1:8263", + "msg": "rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = \"transport: Error while dialing dial tcp 127.0.0.1:8263: connect: connection refused\"" + } + ] + } + ``` + +7. 使用 `show-dd-locks` 确认 DDL lock 是否被成功 unlock。 + + ```bash + show-ddl-locks test + ``` + + ``` + { + "result": true, + "msg": "no DDL lock exists", + "locks": [ + ] + } + ``` + +8. 查看下游 TiDB 中的表结构是否变更成功。 + + {{< copyable "sql" >}} + + ```sql + SHOW CREATE TABLE shard_db.shard_table; + ``` + + ``` + +-------------+--------------------------------------------------+ + | Table | Create Table | + +-------------+--------------------------------------------------+ + | shard_table | CREATE TABLE `shard_table` ( + `c1` int(11) NOT NULL, + `c2` int(11) DEFAULT NULL, + PRIMARY KEY (`c1`) + ) ENGINE=InnoDB DEFAULT CHARSET=latin1 COLLATE=latin1_bin | + +-------------+--------------------------------------------------+ + ``` + +9. 使用 `query-status` 确认同步任务是否正常。 + +#### 手动处理后的影响 + +使用 `unlock-ddl-lock` 手动执行 unlock 操作后，由于该任务的配置信息中仍然包含了已下线的 DM-worker，如果不进行处理，则当下次 sharding DDL 到达时，仍会出现 lock 无法自动完成同步的情况。 + +因此，在手动解锁 DDL lock 后，需要再执行以下操作： + +1. 使用 `stop-task` 停止运行中的任务。 +2. 更新任务配置文件，将已下线 DM-worker 对应的信息从配置文件中移除。 +3. 使用 `start-task` 及新任务配置文件重新启动任务。 + +> **注意：** +> +> 在 `unlock-ddl-lock` 之后，如果已下线的 DM-worker 重新上线并尝试对其中的分表进行数据同步，则会由于数据与下游的表结构不匹配而发生错误。 + +### 场景二：unlock 过程中部分 DM-worker 重启 + +#### Lock 异常原因 + +在 DM-master 收到所有 DM-worker 的 DDL 信息后，执行自动 unlock DDL lock 的操作主要包括以下步骤： + +1. 请求 lock owner 执行 DDL 操作，并更新对应分表的 checkpoint。 +2. 在 owner 执行 DDL 操作成功后，移除 DM-master 上保存的 DDL lock 信息。 +3. 在 owner 执行 DDL 操作成功后，请求其他所有 DM-worker 跳过 DDL 操作并更新对应分表的 checkpoint。 + +上述 unlock DDL lock 的操作不是原子的，当 owner 执行 DDL 操作成功后，请求其他 DM-worker 跳过 DDL 操作时，如果该 DM-worker 发生了重启，则会造成该 DM-worker 跳过 DDL 操作失败。 + +此时 DM-master 上的 lock 信息被移除，但该 DM-worker 重启后将尝试继续重新同步该 DDL 操作。但是，由于其他 DM-worker（包括原 owner）已经同步完该 DDL 操作，并已经在继续后续的同步，该 DM-worker 将永远无法等待该 DDL 操作对应 lock 的自动 unlock。 + +#### 手动处理示例 + +仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 + +当在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息；但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于 DM-worker-2 发生了重启而跳过 DDL 操作失败。 + +DM-worker-2 重启后，将尝试重新同步重启前已经在等待的 DDL lock。此时将在 DM-master 上创建一个新的 lock，并且该 DM-worker 将成为 lock 的 owner（其他 DM-worker 此时已经执行或跳过 DDL 操作并在进行后续同步）。 + +处理流程如下： + +1. 使用 `show-ddl-locks` 确认 DM-master 上存在该 DDL 操作对应的 lock。 + + 应该仅有该重启的 DM-worker（`127.0.0.1:8263`）处于 `syned` 状态： + + {{< copyable "shell-regular" >}} + + ```bash + show-ddl-locks + ``` + + ``` + { + "result": true, + "msg": "", + "locks": [ + { + "ID": "test-`shard_db`.`shard_table`", + "task": "test", + "owner": "127.0.0.1:8263", + "DDLs": [ + "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" + ], + "synced": [ + "127.0.0.1:8263" + ], + "unsynced": [ + "127.0.0.1:8262" + ] + } + ] + } + ``` + +2. 使用 `unlock-ddl-lock` 请求 DM-master unlock 该 lock。 + + - 使用 `--worker` 参数限定操作仅针对该重启的 DM-worker（`127.0.0.1:8263`）。 + - Lock 过程中该 DM-worker 会尝试再次向下游执行该 DDL 操作（重启前的原 owner 已向下游执行过该 DDL 操作），需要确保该 DDL 操作可被多次执行。 + + {{< copyable "shell-regular" >}} + + ```bash + unlock-ddl-lock --worker=127.0.0.1:8263 test-`shard_db`.`shard_table` + ``` + + ``` + { + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "127.0.0.1:8263", + "msg": "" + } + ] + } + ``` + +3. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 +4. 使用 `query-status` 确认同步任务是否正常。 + +#### 手动处理后的影响 + +手动 unlock sharding DDL lock 后，后续的 sharding DDL 将可以自动正常同步。 + +### 场景三：unlock 过程中部分 DM-worker 临时不可达 + +#### Lock 异常原因 + +与 [unlock 过程中部分 DM-worker 重启](#场景二unlock-过程中部分-dm-worker-重启) 造成 lock 异常的原因类似。当请求 DM-worker 跳过 DDL 操作时，如果该 DM-worker 临时不可达，则会造成该 DM-worker 跳过 DDL 操作失败。此时 DM-master 上的 lock 信息被移除，但该 DM-worker 将处于等待一个不再存在的 DDL lock 的状态。 + +场景三与[场景二](#场景二unlock-过程中部分-dm-worker-重启)的区别在于，场景三中 DM-master 没有 lock，而场景二中 DM-master 有一个新的 lock。 + +#### 手动处理示例 + +仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 + +在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息，但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于网络原因等临时不可达而跳过 DDL 操作失败。 + +处理流程如下： + +1. 使用 `show-ddl-locks` 确认 DM-master 上不再存在该 DDL 操作对应的 lock。 +2. 使用 `query-status` 确认 DM-worker 仍在等待 lock 同步。 + + {{< copyable "shell-regular" >}} + + ```bash + query-status test + ``` + + ``` + { + "result": true, + "msg": "", + "workers": [ + ... + { + ... + "worker": "127.0.0.1:8263", + "subTaskStatus": [ + { + ... + "unresolvedDDLLockID": "test-`shard_db`.`shard_table`", + "sync": { + ... + "blockingDDLs": [ + "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" + ], + "unresolvedGroups": [ + { + "target": "`shard_db`.`shard_table`", + "DDLs": [ + "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" + ], + "firstPos": "(mysql-bin|000001.000003, 1752)", + "synced": [ + "`shard_db_2`.`shard_table_1`", + "`shard_db_2`.`shard_table_2`" + ], + "unsynced": [ + ] + } + ], + "synced": false + } + } + ] + ... + } + ] + } + ``` + +3. 使用 `break-ddl-lock` 请求强制 break 该 DM-worker 当前正在等待的 DDL lock。 + + 由于 owner 已经向下游执行了 DDL 操作，因此在 break 时使用 `--skip` 参数。 + + {{< copyable "shell-regular" >}} + + ```bash + break-ddl-lock --worker=127.0.0.1:8263 --skip test + ``` + + ``` + { + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "127.0.0.1:8263", + "msg": "" + } + ] + } + ``` + +4. 使用 `query-status` 确认同步任务是否正常且不再处于等待 lock 的状态。 + +#### 手动处理后的影响 + +手动强制 break lock 后，后续 sharding DDL 将可以自动正常同步。 diff --git a/reference/tools/data-migration/features/overview.md b/reference/tools/data-migration/features/overview.md new file mode 100644 index 000000000000..6912cb24c400 --- /dev/null +++ b/reference/tools/data-migration/features/overview.md @@ -0,0 +1,529 @@ +--- +title: 数据同步功能 +summary: DM 提供的功能及其配置介绍 +category: reference +--- + +# 数据同步功能 + +本文将详细介绍 DM 提供的数据同步功能，以及相关的配置选项。 + +## Table routing + +Table routing 提供将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的功能。 + +> **注意：** +> +> - 不支持对同一个表设置多个不同的路由规则。 +> - Schema 的匹配规则需要单独设置，用来同步 `create/drop schema xx`，例如下面[参数配置](#参数配置)中的 rule-2。 + +### 参数配置 + +{{< copyable "" >}} + +```yaml +routes: + rule-1: + schema-pattern: "test_*" + table-pattern: "t_*" + target-schema: "test" + target-table: "t" + rule-2: + schema-pattern: "test_*" + target-schema: "test" +``` + +### 参数解释 + +将根据 [`schema-pattern`/`table-pattern`](/reference/tools/data-migration/table-selector.md) 匹配上该规则的上游 MySQL/MariaDB 实例的表同步到下游的 `target-schema`/`target-table`。 + +### 使用示例 + +下面展示了三个不同场景下的配置示例。 + +#### 分库分表合并 + +假设存在分库分表场景，需要将上游两个 MySQL 实例的表 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的一张表 `test`.`t`。 + +为了同步到下游实例的表 `test`.`t` 需要创建两个 table routing 规则： + +- `rule-1` 用来同步匹配上 `schema-pattern: "test_*"` 和 `table-pattern: "t_*"` 的表的 DML/DDL 语句到下游的 `test`.`t`。 +- `rule-2` 用来同步匹配上 `schema-pattern: "test_*"` 的库的 DDL 语句，例如 `create/drop schema xx`。 + +> **注意：** +> +> - 如果下游 TiDB `schema: test` 已经存在， 并且不会被删除，则可以省略 `rule-2`。 +> - 如果下游 TiDB `schema: test` 不存在，只设置了 `rule_1`，则同步会报错 `schema test doesn't exist`。 + +{{< copyable "" >}} + +```yaml + rule-1: + schema-pattern: "test_*" + table-pattern: "t_*" + target-schema: "test" + target-table: "t" + rule-2: + schema-pattern: "test_*" + target-schema: "test" +``` + +#### 分库合并 + +假设存在分库场景，将上游两个 MySQL 实例 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t_{1,2,3...}`，创建一条路由规则即可： + +{{< copyable "" >}} + +```yaml + rule-1: + schema-pattern: "test_*" + target-schema: "test" +``` + +#### 错误的 table routing + +假设存在下面两个路由规则，`test_1_bak`.`t_1_bak` 可以匹配上 `rule-1` 和 `rule-2`，违反 table 路由的限制而报错。 + +{{< copyable "" >}} + +```yaml + rule-0: + schema-pattern: "test_*" + target-schema: "test" + rule-1: + schema-pattern: "test_*" + table-pattern: "t_*" + target-schema: "test" + target-table: "t" + rule-2: + schema-pattern: "test_1_bak" + table-pattern: "t_1_bak" + target-schema: "test" + target-table: "t_bak" +``` + +## Black & white table lists + +上游数据库实例表的黑白名单过滤规则，可以用来过滤或者只同步某些 `database/table` 的所有操作。 + +### 参数配置 + +{{< copyable "" >}} + +```yaml +black-white-list: + rule-1: + do-dbs: ["~^test.*"] # 以 ~ 字符开头，表示规则是正则表达式 +​ ignore-dbs: ["mysql"] + do-tables: + - db-name: "~^test.*" + tbl-name: "~^t.*" + - db-name: "test" + tbl-name: "t" + ignore-tables: + - db-name: "test" + tbl-name: "log" +``` + +### 参数解释 + +- `do-dbs`：要同步的库的白名单，类似于 MySQL 中的 [`replicate-do-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-db)。 +- `ignore-dbs`：要同步的库的黑名单，类似于 MySQL 中的 [`replicate-ignore-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-db)。 +- `do-tables`：要同步的表的白名单，类似于 MySQL 中的 [`replicate-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-table)。 +- `ignore-tables`：要同步的表的黑名单，类似于 MySQL 中的 [`replicate-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-table)。 + +以上参数值以 `~` 开头时均支持使用[正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)来匹配库名、表名。 + +### 过滤规则 + +`do-dbs` 与 `ignore-dbs` 对应的过滤规则与 MySQL 中的 [Evaluation of Database-Level Replication and Binary Logging Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-db-options.html) 类似，`do-tables` 与 `ignore-tables` 对应的过滤规则与 MySQL 中的 [Evaluation of Table-Level Replication Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-table-options.html) 类似。 + +> **注意：** +> +> DM 中黑白名单过滤规则与 MySQL 中相应规则存在以下区别： +> +> - MySQL 中存在 [`replicate-wild-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-do-table) 与 [`replicate-wild-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-ignore-table) 用于支持通配符，DM 中各配置参数直接支持以 `~` 字符开头的正则表达式。 +> - DM 当前只支持 `ROW` 格式的 binlog，不支持 `STATEMENT`/`MIXED` 格式的 binlog，因此应与 MySQL 中 `ROW` 格式下的规则对应。 +> - 对于 DDL，MySQL 仅依据默认的 database 名称（`USE` 语句显式指定的 database）进行判断，而 DM 优先依据 DDL 中的 database 名称部分进行判断，并当 DDL 中不包含 database 名称时再依据 `USE` 部分进行判断。假设需要判断的 SQL 为 `USE test_db_2; CREATE TABLE test_db_1.test_table (c1 INT PRIMARY KEY)`，且 MySQL 配置了 `replicate-do-db=test_db_1`、DM 配置了 `do-dbs: ["test_db_1"]`，则对于 MySQL 该规则不会生效，而对于 DM 该规则会生效。 + +判断 table `test`.`t` 是否应该被过滤的过滤流程如下： + +1. 首先 **schema 过滤判断** + + - 如果 `do-dbs` 不为空，判断 `do-dbs` 中是否存在一个匹配的 schema。 + + - 如果存在，则进入 **table 过滤判断**。 + - 如果不存在，则过滤 `test`.`t`。 + + - 如果 `do-dbs` 为空并且 `ignore-dbs` 不为空，判断 `ignore-dbs` 中是否存在一个匹配的 schema。 + + - 如果存在，则过滤 `test`.`t`。 + - 如果不存在，则进入 **table 过滤判断**。 + + - 如果 `do-dbs` 和 `ignore-dbs` 都为空，则进入 **table 过滤判断**。 + +2. 进行 **table 过滤判断** + + 1. 如果 `do-tables` 不为空，判断 `do-tables` 中是否存在一个匹配的 table。 + + - 如果存在，则同步 `test`.`t`。 + - 如果不存在，则过滤 `test`.`t`。 + + 2. 如果 `ignore-tables` 不为空，判断 `ignore-tables` 中是否存在一个匹配的 table。 + + - 如果存在，则过滤 `test`.`t`. + - 如果不存在，则同步 `test`.`t`。 + + 3. 如果 `do-tables` 和 `ignore-tables` 都为空，则同步 `test`.`t`。 + +> **注意：** +> +> 判断 schema `test` 是否被过滤，只进行 **schema 过滤判断** + +### 使用示例 + +假设上游 MySQL 实例包含以下表： + +``` +`logs`.`messages_2016` +`logs`.`messages_2017` +`logs`.`messages_2018` +`forum`.`users` +`forum`.`messages` +`forum_backup_2016`.`messages` +`forum_backup_2017`.`messages` +`forum_backup_2018`.`messages` +``` + +配置如下： + +{{< copyable "" >}} + +```yaml +black-white-list: + bw-rule: + do-dbs: ["forum_backup_2018", "forum"] + ignore-dbs: ["~^forum_backup_"] + do-tables: + - db-name: "logs" + tbl-name: "~_2018$" + - db-name: "~^forum.*" +​ tbl-name: "messages" + ignore-tables: + - db-name: "~.*" +​ tbl-name: "^messages.*" +``` + +应用 `bw-rule` 规则后： + +| table | 是否过滤| 过滤的原因 | +|:----|:----|:--------------| +| `logs`.`messages_2016` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | +| `logs`.`messages_2017` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | +| `logs`.`messages_2018` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | +| `forum_backup_2016`.`messages` | 是 | schema `forum_backup_2016` 没有匹配到 `do-dbs` 任意一项 | +| `forum_backup_2017`.`messages` | 是 | schema `forum_backup_2017` 没有匹配到 `do-dbs` 任意一项 | +| `forum`.`users` | 是 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 没有匹配到 `do-tables` 和 `ignore-tables` 中任意一项，并且 `do-tables` 不为空，因此过滤 | +| `forum`.`messages` | 否 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | +| `forum_backup_2018`.`messages` | 否 | 1. schema `forum_backup_2018` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | + +## Binlog event filter + +Binlog event filter 是比同步表黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema / table` 的指定类型 binlog，比如 `INSERT`，`TRUNCATE TABLE`。 + +> **注意：** +> +> 同一个表匹配上多个规则，将会顺序应用这些规则，并且黑名单的优先级高于白名单，即如果同时存在规则 `Ignore` 和 `Do` 应用在某个 table 上，那么 `Ignore` 生效。 + +### 参数配置 + +{{< copyable "" >}} + +```yaml +filters: + rule-1: + schema-pattern: "test_*" + ​table-pattern: "t_*" + ​events: ["truncate table", "drop table"] + sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] + ​action: Ignore +``` + +### 参数解释 + +- [`schema-pattern`/`table-pattern`](/reference/tools/data-migration/table-selector.md)：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句进行以下规则过滤。 + +- `events`：binlog events 数组。 + + | Event | 分类 | 解释 | + | --------------- | ---- | ----------------------------- | + | all | | 代表包含下面所有的 events | + | all dml | | 代表包含下面所有 DML events | + | all ddl | | 代表包含下面所有 DDL events | + | none | | 代表不包含下面所有 events | + | none ddl | | 代表不包含下面所有 DDL events | + | none dml | | 代表不包含下面所有 DML events | + | insert | DML | insert DML event | + | update | DML | update DML event | + | delete | DML | delete DML event | + | create database | DDL | create database event | + | drop database | DDL | drop database event | + | create table | DDL | create table event | + | create index | DDL | create index event | + | drop table | DDL | drop table event | + | truncate table | DDL | truncate table event | + | rename table | DDL | rename table event | + | drop index | DDL | drop index event | + | alter table | DDL | alter table event | + +- `sql-pattern`：用于过滤指定的 DDL SQL 语句，支持正则表达式匹配，例如上面示例 `"^DROP\\s+PROCEDURE"`。 + +- `action`：string(`Do` / `Ignore`)；进行下面规则判断，满足其中之一则过滤，否则不过滤。 + + - `Do`：白名单。binlog event 如果满足下面两个条件之一就会被过滤掉： + - 不在该 rule 的 `events` 中。 + - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 没有匹配上 `sql-pattern` 中任意一项。 + - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉： + - 在该 rule 的 `events` 中。 + - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 可以匹配上 `sql-pattern` 中任意一项。 + +### 使用示例 + +#### 过滤分库分表的所有删除操作 + +需要设置下面两个 `Binlog event filter rule` 来过滤掉所有的删除操作： + +- `filter-table-rule` 过滤掉所有匹配到 pattern `test_*`.`t_*` 的 table 的 `turncate table`、`drop table`、`delete statement` 操作。 +- `filter-schema-rule` 过滤掉所有匹配到 pattern `test_*` 的 schema 的 `drop database` 操作。 + +{{< copyable "" >}} + +```yaml +filters: + filter-table-rule: + schema-pattern: "test_*" + table-pattern: "t_*" + events: ["truncate table", "drop table", "delete"] + action: Ignore + filter-schema-rule: + schema-pattern: "test_*" + events: ["drop database"] + action: Ignore +``` + +#### 只同步分库分表的 DML 操作 + +需要设置下面两个 `Binlog event filter rule` 只同步 DML 操作： + +- `do-table-rule` 只同步所有匹配到 pattern `test_*`.`t_*` 的 table 的 `create table`、`insert`、`update`、`delete` 操作。 +- `do-schema-rule` 只同步所有匹配到 pattern `test_*` 的 schema 的 `create database` 操作。 + +> **注意：** +> +> 同步 `create database/table` 的原因是创建库和表后才能同步 `DML`。 + +{{< copyable "" >}} + +```yaml +filters: + do-table-rule: + schema-pattern: "test_*" + table-pattern: "t_*" + events: ["create table", "all dml"] + action: Do + do-schema-rule: + schema-pattern: "test_*" + events: ["create database"] + action: Do +``` + +#### 过滤 TiDB 不支持的 SQL 语句 + +可设置如下规则过滤 TiDB 不支持的 `PROCEDURE` 语句： + +{{< copyable "" >}} + +```yaml +filters: + filter-procedure-rule: + schema-pattern: "test_*" + table-pattern: "t_*" + sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] + action: Ignore +``` + +#### 过滤 TiDB parser 不支持的 SQL 语句 + +对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 `schema`/`table` 信息，因此需要使用全局过滤规则：`schema-pattern: "*"`。 + +> **注意：** +> +> 全局过滤规则的设置必须尽可能严格，以避免预期之外地过滤掉需要同步的数据。 + +可设置如下规则过滤 TiDB parser 不支持的 `PARTITION` 语句： + +{{< copyable "" >}} + +```yaml +filters: + filter-partition-rule: + schema-pattern: "*" + sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"] + action: Ignore +``` + +## Column mapping + +> **注意：** +> +> 由于 Column mapping 的使用限制较多，我们不推荐使用 Column mapping 功能作为首选方案。我们优先推荐的方案请参考 [自增主键冲突处理](/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)。 + +Column mapping 提供对表的列值进行修改的功能。可以根据不同的表达式对表的指定列做不同的修改操作，目前只支持 DM 提供的内置表达式。 + +> **注意：** +> +> - 不支持修改 column 的类型和表结构。 +> - 不支持对同一个表设置多个不同的列值转换规则。 + +### 参数配置 + +{{< copyable "" >}} + +```yaml +column-mappings: + rule-1: +​ schema-pattern: "test_*" +​ table-pattern: "t_*" +​ expression: "partition id" +​ source-column: "id" +​ target-column: "id" +​ arguments: ["1", "test", "t", "_"] + rule-2: +​ schema-pattern: "test_*" +​ table-pattern: "t_*" +​ expression: "partition id" +​ source-column: "id" +​ target-column: "id" +​ arguments: ["2", "test", "t", "_"] +``` + +### 参数解释 + +- [`schema-pattern`/`table-pattern`](/reference/tools/data-migration/table-selector.md)：对匹配上该规则的上游 MySQL/MariaDB 实例的表按照指定 `expression` 进行列值修改操作。 +- `source-column`，`target-column`：对 `source-column` 列的值按照指定 `expression` 进行修改，将修改后的值赋值给 `target-column`。 +- `expression`：对数据进行转换的表达式，目前只支持下面的内置计算表达式。 + +#### `partition id` 表达式 + +`partition id` 目的是为了解决分库分表合并同步的自增主键的冲突。 + +**`partition id` 限制** + +注意下面的限制： + +- 只支持类型为 bigint 的列，通常为自增主键，联合主键或者联合唯一索引的其中一列 +- 如果 `schema 前缀` 不为空，则库名的组成必须为 `schema 前缀` 或者 `schema 前缀 + 分隔符 + 数字（即 schema ID）`，例如：支持 `s` 和 `s_1`，不支持 `s_a` +- 如果 `table 前缀` 不为空，则表名的组成必须为 `table 前缀` 或者 `table 前缀 + 分隔符 + 数字（即 table ID）` +- 如果库名/表名不包含 `… + 分隔符 + 数字` 部分，则对应的 ID 默认为 0 +- 对分库分表的规模支持限制如下 + - 支持最多 16 个 MySQL/MariaDB 实例，且需要满足 0 <= instance ID <= 15。 + - 每个实例支持最多 128 个 schema，且需要满足 0 <= schema ID <= 127。 + - 每个实例的每个 schema 支持最多 256 个 table，且需要满足 0 <= table ID <= 255。 + - 进行 Column mapping 的列的范围需要满足 0 <= ID <= 17592186044415。 + - `{instance ID, schema ID, table ID}` 组合需要保持唯一。 +- 目前该功能是定制功能，如果需要调整请联系相关开发人员进行调整 + +**`partition id` 参数配置** + +用户需要在 arguments 里面按顺序设置以下三个或四个参数： + +- `instance_id`：客户指定的上游分库分表的 MySQL/MariaDB instance ID（0 <= instance ID <= 15） +- `schema 前缀`：用来解析库名并获取 `schema ID` +- `table 前缀`：用来解释表名并获取 `table ID` +- 分隔符：用来分隔前缀与 ID，可省略，省略时分隔符默认为空字符串 + +`instance_id`、`schema 前缀` 和 `table 前缀` 这三个参数均可被设置为空字符串（`""`），表示对应的部分不会被编码进 `partition id`。 + +**`partition id` 表达式规则** + +`partition id` 会用 arguments 里面的数字来填充自增主键 ID 的首个比特位，计算出来一个 int64（即 MySQL bigint）类型的值，具体规则如下： + +| instance_id | schema 前缀 | table 前缀 | 编码 | +|:------------|:--------------|:-------------|---------:| +| ☑ 已定义 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 44 比特位] | +| ☐ 空 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 48 比特位] | +| ☑ 已定义 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`T`: 8 比特位] [`P`: 51 比特位] | +| ☑ 已定义 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`P`: 52 比特位] | +| ☐ 空 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`T`: 8 比特位] [`P`: 55 比特位] | +| ☐ 空 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`D`: 7 比特位] [`P`: 56 比特位] | +| ☑ 已定义 | ☐ 空 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`P`: 59 比特位] | + +- `S`：符号位，保留 +- `I`：instance ID，默认 4 比特位 +- `D`：schema ID，默认 7 比特位 +- `T`：table ID，默认 8 比特位 +- `P`：自增主键 ID，占据剩下的比特位（≥44 比特位） + +### 使用示例 + +假设存在分库分表场景：将上游两个 MySQL 实例的 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t`，并且这些表都有自增主键。 + +需要设置下面两个规则： + +{{< copyable "" >}} + +```yaml +column-mappings: + rule-1: +​ schema-pattern: "test_*" +​ table-pattern: "t_*" +​ expression: "partition id" +​ source-column: "id" +​ target-column: "id" +​ arguments: ["1", "test", "t", "_"] + rule-2: +​ schema-pattern: "test_*" +​ table-pattern: "t_*" +​ expression: "partition id" +​ source-column: "id" +​ target-column: "id" +​ arguments: ["2", "test", "t", "_"] +``` + +- MySQL instance 1 的表 `test_1`.`t_1` 的 `ID = 1` 的行经过转换后 ID = 1 变为 `1 << (64-1-4) | 1 << (64-1-4-7) | 1 << 44 | 1 = 580981944116838401` +- MySQL instance 2 的表 `test_1`.`t_2` 的 `ID = 1` 的行经过转换后 ID = 2 变为 `2 << (64-1-4) | 1 << (64-1-4-7) | 2 << 44 | 2 = 1157460288606306306` + +## 同步延迟监控 + +DM 支持通过 heartbeat 真实同步数据来计算每个同步任务与 MySQL/MariaDB 的实时同步延迟。 + +> **注意：** +> +> - 同步延迟的估算的精度在秒级别。 +> - heartbeat 相关的 binlog 不会同步到下游，在计算延迟后会被丢弃。 + +### 系统权限 + +如果开启 heartbeat 功能，需要上游 MySQL/MariaDB 实例提供下面的权限： + +- SELECT +- INSERT +- CREATE (databases, tables) + +### 参数配置 + +在 task 的配置文件中设置： + +``` +enable-heartbeat: true +``` + +### 原理介绍 + +- DM-worker 在对应的上游 MySQL/MariaDB 创建库 `dm_heartbeat`（当前不可配置） +- DM-worker 在对应的上游 MySQL/MariaDB 创建表 `heartbeat`（当前不可配置） +- DM-worker 每秒钟（当前不可配置）在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 表中，利用 `replace statement` 更新当前时间戳 `TS_master` +- DM-worker 每个任务拿到 `dm_heartbeat`.`heartbeat` 的 binlog 后，更新自己的同步时间 `TS_slave_task` +- DM-worker 每 10 秒在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 查询当前的 `TS_master`，并且对每个任务计算 `task_lag` = `TS_master` - `TS_slave_task` + +可以在 metrics 的 [binlog replication](/reference/tools/data-migration/monitor.md#binlog-replication) 处理单元找到 replicate lag 监控项。 diff --git a/reference/tools/data-migration/features/shard-merge.md b/reference/tools/data-migration/features/shard-merge.md new file mode 100644 index 000000000000..136d7f29c9b1 --- /dev/null +++ b/reference/tools/data-migration/features/shard-merge.md @@ -0,0 +1,177 @@ +--- +title: 分库分表合并同步 +category: reference +--- + +# 分库分表合并同步 + +本文介绍了 DM 提供的分库分表合并同步功能。此功能用于将上游 MySQL/MariaDB 实例中结构相同的表同步到下游 TiDB 的同一个表中。DM 不仅支持同步上游的 DML 数据，也支持协调同步多个上游分表的 DDL 表结构变更。 + +> **注意：** +> +> 要执行分库分表合并同步任务，必须在任务配置文件中设置 `is-sharding: true`。 + +## 使用限制 + +DM 进行分表 DDL 的同步有以下几点使用限制： + +- 在一个逻辑 sharding group（需要合并同步到下游同一个表的所有分表组成的 group）内，所有上游分表必须以相同的顺序执行相同的 DDL 语句（库名和表名可以不同），并且只有在所有分表执行完当前一条 DDL 语句后，下一条 DDL 语句才能执行。 + + - 比如，如果在 table_1 表中先增加列 a 后再增加列 b，则在 table_2 表中就不能先增加列 b 后再增加列 a，因为 DM 不支持以不同的顺序来执行相同的 DDL 语句。 + +- 对于每个逻辑 sharding group，推荐使用一个独立的任务进行同步。 + + - 如果一个任务内存在多个 sharding group，则必须等待一个 sharding group 的 DDL 语句同步完成后，才能开始对其他 sharding group 执行 DDL 语句。 + +- 在一个逻辑 sharding group 内，所有上游分表都应该执行对应的 DDL 语句。 + + - 比如，若 DM-worker-2 对应的一个或多个上游分表未执行 DDL 语句，则其他已执行 DDL 语句的 DM-worker 都会暂停同步任务，直到等到 DM-worker-2 收到上游对应的 DDL 语句。 + +- sharding group 数据同步任务不支持 `DROP DATABASE/TABLE` 语句。 + + - DM-worker 中的 binlog 同步单元（sync）会自动忽略掉上游分表的 `DROP DATABASE` 和 `DROP TABLE` 语句。 + +- sharding group 数据同步任务支持 `RENAME TABLE` 语句，但有如下限制（online DDL 中的 `RENAME` 有特殊方案进行支持）： + + - 只支持 `RENAME TABLE` 到一个不存在的表。 + - 一条 `RENAME TABLE` 语句只能包含一个 `RENAME` 操作。 + +- 增量同步任务需要确认开始同步的 binlog position 上各分表的表结构必须一致，才能确保来自不同分表的 DML 语句能够同步到表结构确定的下游，并且后续各分表的 DDL 语句能够正确匹配与同步。 + +- 如果需要变更 [table routing 规则](/reference/tools/data-migration/features/overview.md#table-routing)，必须先等所有 sharding DDL 语句同步完成。 + + - 在 sharding DDL 语句同步过程中，使用 dmctl 尝试变更 router-rules 会报错。 + +- 如果需要创建新表加入到一个正在执行 DDL 语句的 sharding group 中，则必须保持新表结构和最新更改的表结构一致。 + + - 比如，原 table_1, table_2 表初始时有 (a, b) 两列，sharding DDL 语句执行后有 (a, b, c) 三列，则同步完成后新创建的表也应当有 (a, b, c) 三列。 + +- 由于已经收到 DDL 语句的 DM-worker 会暂停任务以等待其他 DM-worker 收到对应的 DDL 语句，因此数据同步延迟会增加。 + +## 背景 + +目前，DM 使用 ROW 格式的 binlog 进行数据同步，且 binlog 中不包含表结构信息。在 ROW 格式的 binlog 同步过程中，如果不需要将多个上游表合并同步到下游的同一个表，则只存在一个上游表的 DDL 语句会更新对应下游表结构。ROW 格式的 binlog 可以认为是具有 self-description 属性。 + +分库分表合并同步过程中，可以根据 column values 及下游的表结构构造出相应的 DML 语句，但此时若上游的分表执行 DDL 语句进行了表结构变更，则必须对该 DDL 语句进行额外同步处理，以避免因为表结构和 binlog 数据不一致而造成同步出错的问题。 + +以下是一个简化后的例子： + +![shard-ddl-example-1](/media/shard-ddl-example-1.png) + +在上图的例子中，分表的合库合表过程简化成了上游只有两个 MySQL 实例，每个实例内只有一个表。假设在数据同步开始时，将两个分表的表结构版本记为 schema V1，将 DDL 语句执行完后的表结构版本记为 schema V2。 + +现在，假设数据同步过程中，DM-worker 内的 binlog 同步单元（sync）从两个上游分表收到的 binlog 数据有如下时序： + +1. 开始同步时，sync 从两个分表收到的都是 schema V1 版本的 DML 语句。 + +2. 在 t1 时刻，sync 收到实例 1 上分表的 DDL 语句。 + +3. 从 t2 时刻开始，sync 从实例 1 收到的是 schema V2 版本的 DML 语句；但从实例 2 收到的仍是 schema V1 版本的 DML 语句。 + +4. 在 t3 时刻，sync 收到实例 2 上分表的 DDL 语句。 + +5. 从 t4 时刻开始，sync 从实例 2 收到的也是 schema V2 版本的 DML 语句。 + +假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当实例 1 的 DDL 语句同步到下游后，下游的表结构会变更成为 schema V2 版本。但在 t2 到 t3 这段时间内，sync 从实例 2 上收到的仍是 schema V1 版本的 DML 语句。当尝试把这些 schema V1 版本的 DML 语句同步到下游时，就会由于 DML 语句与表结构的不一致而发生错误，从而无法正确同步数据。 + +## 实现原理 + +基于上述例子，本部分介绍了 DM 在合库合表过程中进行 DDL 同步的实现原理。 + +![shard-ddl-flow](/media/shard-ddl-flow.png) + +在这个例子中，DM-worker-1 负责同步来自 MySQL 实例 1 的数据，DM-worker-2 负责同步来自 MySQL 实例 2 的数据，DM-master 负责协调多个 DM-worker 间的 DDL 同步。 + +从 DM-worker-1 收到 DDL 语句开始，简化后的 DDL 同步流程为： + +1. 在 t1 时刻，DM-worker-1 收到来自 MySQL 实例 1 的 DDL 语句，自身暂停该 DDL 语句对应任务的 DDL 及 DML 数据同步，并将 DDL 相关信息发送给 DM-master。 + +2. DM-master 根据收到的 DDL 信息判断得知需要协调该 DDL 语句的同步，于是为该 DDL 语句创建一个锁，并将 DDL 锁信息发回给 DM-worker-1，同时将 DM-worker-1 标记为这个锁的 owner。 + +3. DM-worker-2 继续进行 DML 语句的同步，直到在 t3 时刻收到来自 MySQL 实例 2 的 DDL 语句，自身暂停该 DDL 语句对应任务的数据同步，并将 DDL 相关信息发送给 DM-master。 + +4. DM-master 根据收到的 DDL 信息判断得知该 DDL 语句对应的锁信息已经存在，于是直接将对应锁信息发回给 DM-worker-2。 + +5. 根据任务启动时的配置信息、上游 MySQL 实例分表信息、部署拓扑信息等，DM-master 判断得知自身已经收到了来自待合表的所有上游分表的 DDL 语句，于是请求 DDL 锁的 owner（DM-worker-1）向下游同步执行该 DDL。 + +6. DM-worker-1 根据第二步收到的 DDL 锁信息验证 DDL 语句执行请求；向下游执行 DDL，并将执行结果反馈给 DM-master；若 DDL 语句执行成功，则自身开始继续同步后续的（从 t2 时刻对应的 binlog 开始的）DML 语句。 + +7. DM-master 收到来自 owner 执行 DDL 语句成功的响应，于是请求在等待该 DDL 锁的所有其他 DM-worker（DM-worker-2）忽略该 DDL 语句，直接继续同步后续的（从 t4 时刻对应的 binlog 开始的）DML 语句。 + +根据上面的流程，可以归纳出 DM 协调多个 DM-worker 间 sharding DDL 同步的特点： + +- 根据任务配置与 DM 集群部署拓扑信息，DM-master 内部也会建立一个逻辑 sharding group 来协调 DDL 同步，group 中的成员为负责处理该同步任务拆解后的各子任务的 DM-worker。 + +- 各 DM-worker 从 binlog event 中收到 DDL 语句后，会将 DDL 信息发送给 DM-master。 + +- DM-master 根据来自 DM-worker 的 DDL 信息及 sharding group 信息创建或更新 DDL 锁。 + +- 如果 sharding group 的所有成员都收到了某一条相同的 DDL 语句，则表明上游分表在该 DDL 执行前的 DML 语句都已经同步完成，此时可以执行该 DDL 语句，并继续后续的 DML 同步。 + +- 上游所有分表的 DDL 在经过 [table router](/reference/tools/data-migration/features/overview.md#table-routing) 转换后需要保持一致，因此仅需 DDL 锁的 owner 执行一次该 DDL 语句即可，其他 DM-worker 可直接忽略对应的 DDL 语句。 + +在上面的示例中，每个 DM-worker 对应的上游 MySQL 实例中只有一个待合并的分表。但在实际场景下，一个 MySQL 实例可能有多个分库内的多个分表需要进行合并，这种情况下，sharding DDL 的协调同步过程将更加复杂。 + +假设同一个 MySQL 实例中有 table_1 和 table_2 两个分表需要进行合并： + +![shard-ddl-example-2](/media/shard-ddl-example-2.png) + +在这个例子中，由于数据来自同一个 MySQL 实例，因此所有数据都是从同一个 binlog 流中获得，时序如下： + +1. 开始同步时，DM-worker 内的 sync 从两个分表收到的数据都是 schema V1 版本的 DML 语句。 + +2. 在 t1 时刻，sync 收到 table_1 分表的 DDL 语句。 + +3. 从 t2 到 t3 时刻，sync 收到的数据同时包含 table_1 的 DML 语句（schema V2 版本）及 table_2 的 DML 语句（schema V1 版本）。 + +4. 在 t3 时刻，sync 收到 table_2 分表的 DDL 语句。 + +5. 从 t4 时刻开始，sync 从两个分表收到的数据都是 schema V2 版本的 DML 语句。 + +假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当 table_1 的 DDL 语句同步到下游从而变更下游表结构后，table_2 的 DML 语句（schema V1 版本）将无法正常同步。因此，在单个 DM-worker 内部，我们也构造了与 DM-master 内类似的逻辑 sharding group，但 group 的成员是同一个上游 MySQL 实例的不同分表。 + +DM-worker 内协调处理 sharding group 的同步与 DM-master 处理 DM-worker 之间的同步不完全一致，主要原因包括： + +- 当 DM-worker 收到 table_1 分表的 DDL 语句时，同步不能暂停，需要继续解析 binlog 才能获得后续 table_2 分表的 DDL 语句，即需要从 t2 时刻继续解析直到 t3 时刻。 + +- 在继续解析 t2 到 t3 时刻的 binlog 的过程中，table_1 分表的 DML 语句（schema V2 版本）不能向下游同步；但当 sharding DDL 同步并执行成功后，这些 DML 语句则需要同步到下游。 + +DM-worker 内部 sharding DDL 同步的简化流程为： + +1. 在 t1 时刻，DM-worker 收到 table_1 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 + +2. DM-worker 继续向前解析 t2 到 t3 时刻的 binlog。 + +3. 对于 table_1 的 DML 语句（schema V2 版本），忽略；对于 table_2 的 DML 语句（schema V1 版本），正常同步到下游。 + +4. 在 t3 时刻，DM-worker 收到 table_2 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 + +5. 根据同步任务配置信息、上游库表信息等，DM-worker 判断得知该 MySQL 实例上所有分表的 DDL 语句都已收到；于是将该 DDL 语句同步到下游执行并变更下游表结构。 + +6. DM-worker 设置 binlog 流的新解析起始位置点为第一步时保存的位置点。 + +7. DM-worker 重新开始解析从 t2 到 t3 时刻的 binlog。 + +8. 对于 table_1 的 DML 语句（schema V2 版本），正常同步到下游；对于 table_2 的 DML 语句（schema V1 版本），忽略。 + +9. 解析到达第四步时保存的 binlog 位置点，可得知在第三步时被忽略的所有 DML 语句都已经重新同步到下游。 + +10. DM-worker 继续从 t4 时刻对应的 binlog 位置点开始正常同步。 + +综上可知，DM 在处理 sharding DDL 同步时，主要通过两级 sharding group 来进行协调控制，简化的流程为： + +1. 各 DM-worker 独立地协调对应上游 MySQL 实例内多个分表组成的 sharding group 的 DDL 同步。 + +2. 当 DM-worker 收到所有分表的 DDL 语句时，向 DM-master 发送 DDL 相关信息。 + +3. DM-master 根据 DM-worker 发来的 DDL 信息，协调由各 DM-worker 组成的 sharing group 的 DDL 同步。 + +4. 当 DM-master 收到所有 DM-worker 的 DDL 信息时，请求 DDL 锁的 owner（某个 DM-worker） 执行该 DDL 语句。 + +5. DDL 锁的 owner 执行 DDL 语句，并将结果反馈给 DM-master；自身开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 + +6. 当 DM-master 收到 owner 执行 DDL 成功的消息后，请求其他所有 DM-worker 继续开始同步。 + +7. 其他所有 DM-worker 各自开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 + +8. 在完成被忽略的 DML 语句的重新同步后，所有 DM-worker 继续正常同步。 diff --git a/reference/tools/data-migration/from-aurora.md b/reference/tools/data-migration/from-aurora.md new file mode 100644 index 000000000000..303baed0ebf9 --- /dev/null +++ b/reference/tools/data-migration/from-aurora.md @@ -0,0 +1,206 @@ +--- +title: 从 AWS Aurora MySQL 迁移数据 +summary: 使用 DM 从 AWS Aurora MySQL 迁移数据。 +category: reference +--- + +# 从 AWS Aurora MySQL 迁移数据 + +本文介绍如何使用 DM 从 [AWS Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 迁移数据到 TiDB。 + +## 第 1 步：在 Aurora 集群中启用 binlog + +假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 + +| 集群 | 终端节点 | 端口 | 角色 | +|:-------- |:--- | :--- | :--- | +| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | +| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | +| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | + +DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/reference/tools/data-migration/precheck.md#检查内容)。 + +> **注意：** +> +> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 + +如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 + +> **注意：** +> +> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 + +### 为 Aurora 集群修改 binlog 相关参数 + +在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 + +如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 + +> **注意：** +> +> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 + +## 第 2 步：部署 DM 集群 + +目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/how-to/deploy/data-migration-with-ansible.md)。 + +> **注意：** +> +> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 +> - 上下游数据库用户必须拥有相应的读写权限。 + +## 第 3 步：检查集群信息 + +使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： + +- DM 集群相关组件配置信息 + + | 组件 | 主机 | 端口 | + |:------|:---- |:---- | + | dm_worker1 | 172.16.10.72 | 8262 | + | dm_worker2 | 172.16.10.73 | 8262 | + | dm_master | 172.16.10.71 | 8261 | + +- 上下游数据库实例相关信息 + + | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | + |:-------- |:--- | :--- | :--- | :--- | + | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | + | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | + | 下游 TiDB | 172.16.10.83 | 4000 | root | | + +- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 + + ```toml + # Master 配置。 + + [[deploy]] + source-id = "mysql-replica-01" + dm-worker = "172.16.10.72:8262" + + [[deploy]] + source-id = "mysql-replica-02" + dm-worker = "172.16.10.73:8262" + ``` + +## 第 4 步：配置任务 + +假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 + +复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： + +```yaml +# 任务名，多个同时运行的任务不能重名。 +name: "test" +# 全量+增量 (all) 同步模式。 +task-mode: "all" +# 下游 TiDB 配置信息。 +target-database: + host: "172.16.10.83" + port: 4000 + user: "root" + password: "" + +# 当前数据同步任务需要的全部上游 MySQL 实例配置。 +mysql-instances: +- + # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 + source-id: "mysql-replica-01" + # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 + black-white-list: "global" + # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 + mydumper-config-name: "global" + +- + source-id: "mysql-replica-02" + black-white-list: "global" + mydumper-config-name: "global" + +# 黑白名单全局配置，各实例通过配置项名引用。 +black-white-list: + global: + do-tables: # 需要同步的上游表的白名单。 + - db-name: "test_db" # 需要同步的表的库名。 + tbl-name: "test_table" # 需要同步的表的名称。 + +# Mydumper 全局配置，各实例通过配置项名引用。 +mydumpers: + global: + extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 +``` + +## 第 5 步：启动任务 + +1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` + +2. 执行以下命令启动 dmctl + + {{< copyable "shell-regular" >}} + + ```bash + ./dmctl --master-addr 172.16.10.71:8261 + ``` + +3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 + + {{< copyable "" >}} + + ```bash + » start-task ./task.yaml + ``` + + - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 + - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 + + ```json + { + "id": 4, + "name": "source db dump privilege chcker", + "desc": "check dump privileges of source DB", + "state": "fail", + "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", + "instruction": "", + "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" + }, + { + "id": 5, + "name": "source db replication privilege chcker", + "desc": "check replication privileges of source DB", + "state": "fail", + "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", + "instruction": "", + "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" + } + ``` + + 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： + 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 + 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 + + ```yaml + ignore-checking-items: ["dump_privilege", "replication_privilege"] + ``` + +## 第 6 步：查询任务 + +如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： + +{{< copyable "" >}} + +```bash +» query-status +``` + +> **注意：** +> +> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： +> +> ```bash +> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) +> ``` +> +> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： +> +> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 +> 2. 将原 task.yaml 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` +> 3. 使用 `start-task` 重新启动任务 diff --git a/reference/tools/data-migration/glossary.md b/reference/tools/data-migration/glossary.md new file mode 100644 index 000000000000..29fe53ad7acb --- /dev/null +++ b/reference/tools/data-migration/glossary.md @@ -0,0 +1,124 @@ +--- +title: TiDB Data Migration 术语表 +summary: 学习 TiDB Data Migration 相关术语 +category: glossary +--- + +# TiDB Data Migration 术语表 + +本文档介绍 TiDB Data Migration (TiDB DM) 相关术语。 + +## B + +### Binlog + +在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/internals/en/binary-log.html) 与 [MariaDB Binary Log](https://mariadb.com/kb/en/library/binary-log/)。 + +### Binlog event + +MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/internals/en/binlog-event.html) 与 [MariaDB Binlog Event](https://mariadb.com/kb/en/library/1-binlog-events/)。 + +### Binlog event filter + +比 Black & white table list 更加细粒度的过滤功能，具体可参考 [Binlog event filter](/reference/tools/data-migration/overview.md#binlog-event-filter)。 + +### Binlog position + +特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/kb/en/library/show-binlog-events/)。 + +### Binlog replication 处理单元 + +DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游的处理单元，每个 Subtask 对应一个 Binlog replication 处理单元。在当前文档中，有时也称作 Sync 处理单元。 + +### Black & white table list + +针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Black & white table lists](/reference/tools/data-migration/overview.md#black--white-table-lists)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。 + +## C + +### Checkpoint + +TiDB DM 在全量导入与增量复制过程中的断点信息，用于在重新启动或恢复任务时从之前已经处理过的位置继续执行。 + +- 对于全量导入，Checkpoint 信息对应于每个数据文件已经被成功导入的数据对应的文件内偏移量等信息，其在每个导入数据的事务中同步更新； +- 对于增量复制，Checkpoint 信息对应于已经成功解析并导入到下游的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 等信息，其在 DDL 导入成功后或距上次更新时间超过 30 秒等条件下更新。 + +另外，[Relay 处理单元](#relay-处理单元) 对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#GTID) 信息。 + +## D + +### Dump 处理单元 + +DM-worker 内部用于从上游导出全量数据的处理单元，每个 Subtask 对应一个 Dump 处理单元。 + +## G + +### GTID + +MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/kb/en/library/gtid/)。 + +## H + +### Heartbeat + +在增量数据迁移过程中，用于估算数据从在上游写入后到达 Binlog replication 处理单元延迟时间的机制，具体可参考[同步延迟监控](/reference/tools/data-migration/features/overview.md#同步延迟监控)。 + +## L + +### Load 处理单元 + +DM-worker 内部用于将全量导出数据导入到下游的处理单元，每个 Subtask 对应一个 Load 处理单元。在当前文档中，有时也称作 Import 处理单元。 + +## R + +### Relay log + +DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/kb/en/library/relay-log/) 相近。 + +有关 TiDB DM 内 Relay log 的目录结构、初始同步规则、数据清理等内容，可参考 [TiDB DM Relay Log](https://pingcap.com/docs-cn/stable/reference/tools/data-migration/relay-log/)。 + +### Relay 处理单元 + +DM-worker 内部用于从上游拉取 Binlog 并写入数据到 Relay log 的处理单元，每个 DM-worker 实例内部仅存在一个该处理单元。 + +## S + +### Safe mode + +指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 + +该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在启动或恢复增量迁移任务的前 5 分钟 TiDB DM 会自动启动 Safe mode，另外也可以在任务配置文件中通过 `safe-mode` 参数手动开启。 + +### Shard DDL + +指合库合表迁移过程中，在上游各分表 (shard) 上执行的需要 TiDB DM 进行协调迁移的 DDL。在当前文档中，有时也称作 Sharding DDL。 + +### Shard DDL lock + +用于协调 Shard DDL 迁移的锁机制，具体原理可查看[分库分表合并同步实现原理](/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding DDL lock。 + +### Shard group + +指合库合表迁移过程中，需要合并迁移到下游同一张表的所有上游分表 (shard)，TiDB DM 内部具体实现时使用了两级抽象的 Shard group，具体可查看[分库分表合并同步实现原理](/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding group。 + +### Subtask + +数据迁移子任务，即数据迁移任务运行在单个 DM-worker 实例上的部分。根据任务配置的不同，单个数据迁移任务可能只有一个子任务，也可能有多个子任务。 + +### Subtask status + +数据迁移子任务所处的状态，目前包括 `New`、`Running`、`Paused`、`Stopped` 及 `Finished` 5 种状态。有关数据迁移任务、子任务状态的更多信息可参考[任务状态](/reference/tools/data-migration/query-status.md#任务状态)。 + +## T + +### Table routing + +用于支持将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步，具体可参考 [Table routing](/reference/tools/data-migration/features/overview.md#table-routing)。 + +### Task + +数据迁移任务，执行 `start-task` 命令成功后即启动一个数据迁移任务。根据任务配置的不同，单个数据迁移任务既可能只在单个 DM-worker 实例上运行，也可能同时在多个 DM-worker 实例上运行。 + +### Task status + +数据迁移子任务所处的状态，由 [Subtask status](#subtask-status) 整合而来，具体信息可查看[任务状态](/reference/tools/data-migration/query-status.md#任务状态)。 diff --git a/reference/tools/data-migration/manage-tasks.md b/reference/tools/data-migration/manage-tasks.md new file mode 100644 index 000000000000..04447c4d488d --- /dev/null +++ b/reference/tools/data-migration/manage-tasks.md @@ -0,0 +1,956 @@ +--- +title: 管理数据同步任务 +category: reference +--- + +# 管理数据同步任务 + +本文介绍了如何使用 [dmctl](/reference/tools/data-migration/overview.md#dmctl) 组件来进行数据同步任务的管理和维护。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 `dm-ansible/dmctl`。 + +dmctl 支持交互模式用于人工操作，同时也支持命令模式用于脚本。 + +## dmctl 交互模式 + +本部分描述了在交互模式下一些 dmctl 命令的基本用法。 + +### dmctl 使用帮助 + +{{< copyable "shell-regular" >}} + +```bash +./dmctl --help +``` + +``` +Usage of dmctl: + -V prints version and exit + -config string + path to config file + # 按照 DM 提供的加密方法加密数据库密码，用于 DM 的配置文件 + -encrypt string + encrypt plaintext to ciphertext + # DM-master 访问地址，dmctl 与 DM-master 交互以完成任务管理操作 + -master-addr string + master API server addr + -rpc-timeout string + rpc timeout, default is 10m (default "10m") +``` + +### 加密数据库密码 + +在 DM 相关配置文件中，要求必须使用经 dmctl 加密后的密码，否则会报错。对于同一个原始密码，每次加密后密码不同。 + +{{< copyable "shell-regular" >}} + +```bash +./dmctl -encrypt 123456 +``` + +``` +VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= +``` + +### 任务管理概览 + +进入交互模式，与 DM-master 进行交互： + +{{< copyable "shell-regular" >}} + +```bash +./dmctl -master-addr 172.16.30.14:8261 +``` + +``` +Welcome to dmctl +Release Version: v1.0.1 +Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 +Git Branch: release-1.0 +UTC Build Time: 2019-09-10 06:15:05 +Go Version: go version go1.12 linux/amd64 + +» help +DM control + +Usage: + dmctl [command] + +Available Commands: + break-ddl-lock forcefully break DM-worker's DDL lock + check-task check the config file of the task + help help about any command + migrate-relay migrate DM-worker's relay unit + pause-relay pause DM-worker's relay unit + pause-task pause a specified running task + purge-relay purge relay log files of the DM-worker according to the specified filename + query-error query task error + query-status query task status + refresh-worker-tasks refresh worker -> tasks mapper + resume-relay resume DM-worker's relay unit + resume-task resume a specified paused task + show-ddl-locks show un-resolved DDL locks + sql-inject inject (limited) SQLs into binlog replication unit as binlog events + sql-replace replace SQLs matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern); each SQL must end with a semicolon + sql-skip skip the binlog event matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern) + start-task start a task as defined in the config file + stop-task stop a specified task + switch-relay-master switch the master server of the DM-worker's relay unit + unlock-ddl-lock forcefully unlock DDL lock + update-master-config update the config of the DM-master + update-relay update the relay unit config of the DM-worker + update-task update a task's config for routes, filters, or black-white-list + +Flags: + -h, --help help for dmctl + -w, --worker strings DM-worker ID + +# 使用 `dmctl [command] --help` 来获取某个命令的更多信息 +``` + +## 管理数据同步任务 + +本部分描述了如何使用不同的任务管理命令来执行相应操作。 + +### 创建数据同步任务 + +`start-task` 命令用于创建数据同步任务。 当数据同步任务启动时，DM 将[自动对相应权限和配置进行前置检查](/reference/tools/data-migration/precheck.md)。 + +{{< copyable "" >}} + +```bash +help start-task +``` + +``` +start a task as defined in the config file + +Usage: + dmctl start-task [-w worker ...] [flags] + +Flags: + -h, --help help for start-task + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +start-task [ -w "172.16.30.15:8262"] ./task.yaml +``` + +#### 参数解释 + ++ `-w`： + - 可选 + - 指定在特定的一组 DM-workers 上执行 `task.yaml` + - 如果设置，则只启动指定任务在该组 DM-workers 上的子任务 ++ `config-file`： + - 必选 + - 指定 `task.yaml` 的文件路径 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +start-task task.yaml +``` + +``` +{ + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + }, + { + "result": true, + "worker": "172.16.30.16:8262", + "msg": "" + } + ] +} +``` + +### 查询数据同步任务状态 + +`query-status` 命令用于查询数据同步任务状态。有关查询结果及子任务状态，详见[查询状态](/reference/tools/data-migration/query-status.md)。 + +{{< copyable "" >}} + +```bash +help query-status +``` + +``` +query task status + +Usage: + dmctl query-status [-w worker ...] [task-name] [flags] + +Flags: + -h, --help help for query-status + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +query-status +``` + +#### 参数解释 + +- `-w`： + - 可选 + - 查询在指定的一组 DM-workers 上运行的数据同步任务的子任务 +- `task-name`： + - 可选 + - 指定任务名称 + - 如果未设置，则返回全部数据同步任务的查询结果 + +#### 返回结果示例 + +有关查询结果中各参数的意义，详见[查询状态结果](/reference/tools/data-migration/query-status.md#查询结果)。 + +### 查询运行错误 + +`query-error` 可用于查询数据同步任务与 relay 处理单元的错误信息。相比于 `query-status`，`query-error` 一般不用于获取除错误信息之外的其他信息。 + +`query-error` 常用于获取 `sql-skip`/`sql-replace` 所需的 binlog position 信息，有关 `query-error` 的参数与结果解释，请参考 [跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 文档中的 query-error](/reference/tools/data-migration/skip-replace-sqls.md#query-error)。 + +### 暂停数据同步任务 + +`pause-task` 命令用于暂停数据同步任务。 + +> **注意：** +> +> 有关 `pause-task` 与 `stop-task` 的区别如下： +> +> - 使用 `pause-task` 仅暂停同步任务的执行，但仍然会在内存中保留任务的状态信息等，且可通过 `query-status` 进行查询；使用 `stop-task` 会停止同步任务的执行，并移除内存中与该任务相关的信息，且不可再通过 `query-status` 进行查询，但不会移除已经写入到下游数据库中的数据以及其中的 checkpoint 等 `dm_meta` 信息。 +> - 使用 `pause-task` 暂停同步任务期间，由于任务本身仍然存在，因此不能再启动同名的新任务，且会阻止对该任务所需 relay log 的清理；使用 `stop-task` 停止任务后，由于任务不再存在，因此可以再启动同名的新任务，且不会阻止对 relay log 的清理。 +> - `pause-task` 一般用于临时暂停同步任务以排查问题等；`stop-task` 一般用于永久删除同步任务或通过与 `start-task` 配合以更新配置信息。 + +{{< copyable "" >}} + +```bash +help pause-task +``` + +``` +pause a specified running task + +Usage: + dmctl pause-task [-w worker ...] [flags] + +Flags: + -h, --help help for pause-task + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +pause-task [-w "127.0.0.1:8262"] task-name +``` + +#### 参数解释 + +- `-w`： + - 可选 + - 指定在特定的一组 DM-workers 上暂停数据同步任务的子任务 + - 如果设置，则只暂停该任务在指定 DM-workers 上的子任务 +- `task-name`： + - 必选 + - 指定任务名称 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +pause-task test +``` + +``` +{ + "op": "Pause", + "result": true, + "msg": "", + "workers": [ + { + "meta": { + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + }, + "op": "Pause", + "logID": "2" + }, + { + "meta": { + "result": true, + "worker": "172.16.30.16:8262", + "msg": "" + }, + "op": "Pause", + "logID": "2" + } + ] +} +``` + +### 恢复数据同步任务 + +`resume-task` 命令用于恢复处于 `Paused` 状态的数据同步任务，通常用于在人为处理完造成同步任务暂停的故障后手动恢复同步任务。 + +{{< copyable "" >}} + +```bash +help resume-task +``` + +``` +resume a specified paused task + +Usage: + dmctl resume-task [-w worker ...] [flags] + +Flags: + -h, --help help for resume-task + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +resume-task [-w "127.0.0.1:8262"] task-name +``` + +#### 参数解释 + +- `-w`： + - 可选 + - 指定在特定的一组 DM-workers 上恢复数据同步任务的子任务 + - 如果设置，则只恢复该任务在指定 DM-workers 上的子任务 +- `task-name`： + - 必选 + - 指定任务名称 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +resume-task test +``` + +``` +{ + "op": "Resume", + "result": true, + "msg": "", + "workers": [ + { + "meta": { + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + }, + "op": "Resume", + "logID": "3" + }, + { + "meta": { + "result": true, + "worker": "172.16.30.16:8262", + "msg": "" + }, + "op": "Resume", + "logID": "3" + } + ] +} +``` + +### 停止数据同步任务 + +`stop-task` 命令用于停止数据同步任务。有关 `stop-task` 与 `pause-task` 的区别，请参考[暂停数据同步任务](#暂停数据同步任务)中的相关说明。 + +{{< copyable "" >}} + +```bash +help stop-task +``` + +``` +stop a specified task + +Usage: + dmctl stop-task [-w worker ...] [flags] + +Flags: + -h, --help help for stop-task + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +stop-task [-w "127.0.0.1:8262"] task-name +``` + +#### 参数解释 + +- `-w`： + - 可选 + - 指定在特定的一组 DM-workers 上停止数据同步任务的子任务 + - 如果设置，则只停止该任务在指定 DM-workers 上的子任务 +- `task-name`： + - 必选 + - 指定任务名称 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +stop-task test +``` + +``` +{ + "op": "Stop", + "result": true, + "msg": "", + "workers": [ + { + "meta": { + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + }, + "op": "Stop", + "logID": "4" + }, + { + "meta": { + "result": true, + "worker": "172.16.30.16:8262", + "msg": "" + }, + "op": "Stop", + "logID": "4" + } + ] +} +``` + +### 更新数据同步任务 + +`update-task` 命令用于更新数据同步任务。 + +支持的更新项包括： + +- Table routing 规则 +- Black & white table lists 规则 +- Binlog event filter 规则 + +其余项均不支持更新。 + +> **注意：** +> +> 如果能确保同步任务所需的 relay log 在任务停止期间不会被清理，则推荐使用[不支持更新项的更新步骤](#不支持更新项的更新步骤)来以统一的方式更新任务配置信息。 + +#### 支持更新项的更新步骤 + +1. 使用 `query-status ` 查询对应数据同步任务的状态。 + + - 若 `stage` 不为 `Paused`，则先使用 `pause-task ` 暂停任务。 + +2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 + +3. 使用 `update-task task.yaml` 更新任务配置。 + +4. 使用 `resume-task ` 恢复任务。 + +#### 不支持更新项的更新步骤 + +1. 使用 `query-status ` 查询对应数据同步任务的状态。 + + - 若任务存在，则通过 `stop-task ` 停止任务。 + +2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 + +3. 使用 `start-task ` 重启恢复任务。 + +{{< copyable "" >}} + +```bash +help update-task +``` + +``` +update a task's config for routes, filters, or black-white-list + +Usage: + dmctl update-task [-w worker ...] [flags] + +Flags: + -h, --help help for update-task + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +update-task [-w "127.0.0.1:8262"] ./task.yaml +``` + +#### 参数解释 + +- `-w`： + - 可选 + - 指定在特定的一组 DM-workers 上更新数据同步任务的子任务 + - 如果设置，则只更新指定 DM-workers 上的子任务配置 +- `config-file`： + - 必选 + - 指定 `task.yaml` 的文件路径 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +update-task task_all_black.yaml +``` + +``` +{ + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + }, + { + "result": true, + "worker": "172.16.30.16:8262", + "msg": "" + } + ] +} +``` + +## 管理 DDL lock + +目前与 DDL lock 相关的命令主要包括 `show-ddl-locks`、`unlock-ddl-lock`、`break-ddl-lock` 等。有关它们的功能、用法以及适用场景等，请参考[手动处理 sharding DDL lock](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 + +## 其他任务与集群管理命令 + +除上述常用的任务管理命令外，DM 还提供了其他一些命令用于管理数据同步任务或 DM 集群本身。 + +### 检查任务配置文件 + +`check-task` 命令用于检查指定的数据同步任务配置文件（`task.yaml`）是否合法以及上下游数据库的配置、权限、表结构等是否满足同步需要。具体可参考[上游 MySQL 实例配置前置检查](/reference/tools/data-migration/precheck.md)。 + +在使用 `start-task` 启动同步任务时，DM 也会执行 `check-task` 所做的全部检查。 + +{{< copyable "" >}} + +```bash +help check-task +``` + +``` +check the config file of the task + +Usage: + dmctl check-task [flags] + +Flags: + -h, --help help for check-task + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +check-task task.yaml +``` + +#### 参数解释 + ++ `config-file`： + - 必选 + - 指定 `task.yaml` 的文件路径 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +check-task task-test.yaml +``` + +``` +{ + "result": true, + "msg": "check pass!!!" +} +``` + +### 暂停 relay 处理单元 + +relay 处理单元在 DM-worker 进程启动后即开始自动运行。通过使用 `pause-relay` 命令，我们可以暂停 relay 处理单元的运行。 + +当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `pause-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 + +{{< copyable "" >}} + +```bash +help pause-relay +``` + +``` +pause DM-worker's relay unit + +Usage: + dmctl pause-relay <-w worker ...> [flags] + +Flags: + -h, --help help for pause-relay + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +pause-relay -w "127.0.0.1:8262" +``` + +#### 参数解释 + +- `-w`： + - 必选 + - 指定需要暂停 relay 处理单元的 DM-worker + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +pause-relay -w "172.16.30.15:8262" +``` + +``` +{ + "op": "InvalidRelayOp", + "result": true, + "msg": "", + "workers": [ + { + "op": "PauseRelay", + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + } + ] +} +``` + +### 恢复 relay 处理单元 + +`resume-relay` 用于恢复处于 `Paused` 状态的 relay 处理单元。 + +当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `resume-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 + +{{< copyable "" >}} + +```bash +help resume-relay +``` + +``` +resume DM-worker's relay unit + +Usage: + dmctl resume-relay <-w worker ...> [flags] + +Flags: + -h, --help help for resume-relay + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +resume-relay -w "127.0.0.1:8262" +``` + +#### 参数解释 + +- `-w`： + - 必选 + - 指定需要恢复 relay 处理单元的 DM-worker + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +resume-relay -w "172.16.30.15:8262" +``` + +``` +{ + "op": "InvalidRelayOp", + "result": true, + "msg": "", + "workers": [ + { + "op": "ResumeRelay", + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + } + ] +} +``` + +### 切换 relay log 到新的子目录 + +relay 处理单元通过使用不同的子目录来存储来自上游不同 MySQL 实例的 binlog 数据。通过使用 `switch-relay-master` 命令，我们可以变更 relay 处理单元以开始使用一个新的子目录。 + +当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `switch-relay-master` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 + +{{< copyable "" >}} + +```bash +help switch-relay-master +``` + +``` +switch the master server of the DM-worker's relay unit + +Usage: + dmctl switch-relay-master <-w worker ...> [flags] + +Flags: + -h, --help help for switch-relay-master + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +switch-relay-master -w "127.0.0.1:8262" +``` + +#### 参数解释 + +- `-w`： + - 必选 + - 指定需要切换 relay 处理单元使用子目录的 DM-worker + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +switch-relay-master -w "172.16.30.15:8262" +``` + +``` +{ + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "172.16.30.15:8262", + "msg": "" + } + ] +} +``` + +### 手动清理 relay log + +DM 支持[自动清理 relay log](/reference/tools/data-migration/relay-log.md#自动数据清理)，但同时 DM 也支持使用 `purge-relay` 命令[手动清理 relay log](/reference/tools/data-migration/relay-log.md#手动数据清理)。 + +{{< copyable "" >}} + +```bash +help purge-relay +``` + +``` +purge relay log files of the DM-worker according to the specified filename + +Usage: + dmctl purge-relay <-w worker> [--filename] [--sub-dir] [flags] + +Flags: + -f, --filename string name of the terminal file before which to purge relay log files. Sample format: "mysql-bin.000006" + -h, --help help for purge-relay + -s, --sub-dir string specify relay sub directory for --filename. If not specified, the latest one will be used. Sample format: "2ae76434-f79f-11e8-bde2-0242ac130008.000001" + +Global Flags: + -w, --worker strings DM-worker ID +``` + +#### 命令用法示例 + +{{< copyable "" >}} + +```bash +purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" +``` + +#### 参数解释 + +- `-w`： + - 必选 + - 指定需要执行 relay log 清理操作的 DM-worker +- `--filename`： + - 必选 + - 指定标识 relay log 将要停止清理的文件名。如指定为 `mysql-bin.000100`，则只尝试清理到 `mysql-bin.000099` +- `--sub-dir`： + - 可选 + - 指定 `--filename` 对应的 relay log 子目录，如果不指定则会使用当前最新的子目录 + +#### 返回结果示例 + +{{< copyable "" >}} + +```bash +purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" +``` + +``` +[warn] no --sub-dir specified for --filename; the latest one will be used +{ + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "127.0.0.1:8262", + "msg": "" + } + ] +} +``` + +### 预设跳过 DDL 操作 + +`sql-skip` 命令用于预设一个跳过操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。相关参数与结果解释，请参考[`sql-skip`](/reference/tools/data-migration/skip-replace-sqls.md#sql-skip)。 + +### 预设替换 DDL 操作 + +`sql-replace` 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替换执行操作。相关参数与结果解释，请参考[`sql-replace`](/reference/tools/data-migration/skip-replace-sqls.md#sql-replace)。 + +### 强制刷新 `task => DM-workers` 映射关系 + +`refresh-worker-tasks` 命令用于强制刷新 DM-master 内存中维护的 `task => DM-workers` 映射关系。 + +> **注意：** +> +> 一般不需要使用此命令。仅当已确定 `task => DM-workers` 映射关系存在，但执行其它命令时仍提示必须刷新它时，你才需要使用此命令。 + +## dmctl 命令模式 + +命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。 + +> **注意：** +> +> + 一条 dmctl 命令只能跟一个任务操作 +> + 任务操作只能放在 dmctl 命令的最后 + +{{< copyable "shell-regular" >}} + +```bash +./dmctl -master-addr 172.16.30.14:8261 start-task task.yaml +./dmctl -master-addr 172.16.30.14:8261 stop-task task +./dmctl -master-addr 172.16.30.14:8261 query-status +``` + +``` +Available Commands: + break-ddl-lock break-ddl-lock <-w worker ...> [--remove-id] [--exec] [--skip] + check-task check-task + migrate-relay migrate-relay + pause-relay pause-relay <-w worker ...> + pause-task pause-task [-w worker ...] + purge-relay purge-relay <-w worker> [--filename] [--sub-dir] + query-error query-error [-w worker ...] [task-name] + query-status query-status [-w worker ...] [task-name] + refresh-worker-tasks refresh-worker-tasks + resume-relay resume-relay <-w worker ...> + resume-task resume-task [-w worker ...] + show-ddl-locks show-ddl-locks [-w worker ...] [task-name] + sql-inject sql-inject <-w worker> + sql-replace sql-replace <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] + sql-skip sql-skip <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] + start-task start-task [-w worker ...] + stop-task stop-task [-w worker ...] + switch-relay-master switch-relay-master <-w worker ...> + unlock-ddl-lock unlock-ddl-lock [-w worker ...] + update-master-config update-master-config + update-relay update-relay [-w worker ...] + update-task update-task [-w worker ...] +``` + +## 废弃或不推荐使用的命令 + +以下命令已经被废弃或仅用于 debug，在接下来的版本中可能会被移除或修改其语义，**强烈不推荐使用**。 + +- `migrate-relay` +- `sql-inject` +- `update-master-config` +- `update-relay` diff --git a/reference/tools/data-migration/monitor.md b/reference/tools/data-migration/monitor.md new file mode 100644 index 000000000000..2941024f839a --- /dev/null +++ b/reference/tools/data-migration/monitor.md @@ -0,0 +1,119 @@ +--- +title: DM 监控指标 +summary: 介绍 DM 的监控指标 +category: reference +--- + +# DM 监控指标 + +使用 DM-Ansible 部署 DM 集群的时候，会默认部署一套[监控系统](/reference/tools/data-migration/deploy.md#第-7-步监控任务与查看日志)。 + +> **注意：** +> +> 目前只有 DM-worker 提供了 metrics，DM-master 暂未提供。 + +## Task + +在 Grafana dashboard 中，DM 默认名称为 `DM-task`。 + +### overview + +overview 下包含运行当前选定 task 的所有 DM-worker instance 的部分监控指标。当前默认告警规则只针对于单个 DM-worker instance。 + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| task state | 同步子任务的状态 | N/A | N/A | +| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | +| storage remain | relay log 占有的磁盘的剩余可用容量 | N/A | N/A | +| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | N/A | N/A | +| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | +| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | +| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | + +### task 状态 + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时| critical | + +### Relay log + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | +| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | +| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | +| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | +| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | +| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | +| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | +| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | +| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | +| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | +| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒| N/A | N/A | +| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | + +### Dump/Load unit + +下面 metrics 仅在 `task-mode` 为 `full` 或者 `all` 模式下会有值。 + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | +| data file size | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的总大小 | N/A | N/A | +| dump process exits with error | dump unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | +| load process exits with error | load unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | +| table count | load unit 导入的全量数据中 table 的数量总和 | N/A | N/A | +| data file count | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的数量总和| N/A | N/A | +| latency of execute transaction | load unit 在执行事务的时延，单位：秒 | N/A | N/A | +| latency of query | load unit 执行 query 的耗时，单位：秒 | N/A | N/A | + +### Binlog replication + +下面 metrics 仅在 `task-mode` 为 `incremental` 或者 `all` 模式下会有值。 + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| remaining time to sync | 预计 Syncer 还需要多少分钟可以和 master 完全同步，单位：分钟 | N/A | N/A | +| replicate lag | master 到 Syncer 的 binlog 复制延迟时间，单位：秒 | N/A | N/A | +| process exist with error | binlog replication 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | +| binlog file gap between master and syncer | 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | +| binlog file gap between relay and syncer | 与 relay 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | +| binlog event qps | 单位时间内接收到的 binlog event 数量 (不包含需要跳过的 event) | N/A | N/A | +| skipped binlog event qps | 单位时间内接收到的需要跳过的 binlog event 数量 | N/A | N/A | +| cost of binlog event transform | Syncer 解析并且转换 binlog 成 SQLs 的耗时，单位：秒 | N/A | N/A | +| total sqls jobs | 单位时间内新增的 job 数量 | N/A | N/A | +| finished sqls jobs | 单位时间内完成的 job 数量 | N/A | N/A | +| execution latency | Syncer 执行 transaction 到下游的耗时，单位：秒 | N/A | N/A | +| unsynced tables | 当前子任务内还未收到 shard DDL 的分表数量 | N/A | N/A | +| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | + +## Instance + +在 Grafana dashboard 中，instance 的默认名称为 `DM-instance`。 + +### Relay log + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | +| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | +| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | +| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | +| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | +| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | +| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | +| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | +| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | +| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | +| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒 | N/A | N/A | +| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | + +### task + +| metric 名称 | 说明 | 告警说明 | 告警级别 | +|:----|:------------|:----|:----| +| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时 | critical | +| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | +| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | +| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | diff --git a/reference/tools/data-migration/overview.md b/reference/tools/data-migration/overview.md new file mode 100644 index 000000000000..8f6c3c6efe60 --- /dev/null +++ b/reference/tools/data-migration/overview.md @@ -0,0 +1,99 @@ +--- +title: Data Migration 简介 +category: reference +--- + +# Data Migration 简介 + +[DM](https://github.com/pingcap/dm) (Data Migration) 是一体化的数据同步任务管理平台，支持从 MySQL 或 MariaDB 到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化错误处理流程，降低运维成本。 + +## DM 架构 + +DM 主要包括三个组件：DM-master，DM-worker 和 dmctl。 + +![Data Migration architecture](/media/dm-architecture.png) + +### DM-master + +DM-master 负责管理和调度数据同步任务的各项操作。 + +- 保存 DM 集群的拓扑信息 +- 监控 DM-worker 进程的运行状态 +- 监控数据同步任务的运行状态 +- 提供数据同步任务管理的统一入口 +- 协调分库分表场景下各个实例分表的 DDL 同步 + +### DM-worker + +DM-worker 负责执行具体的数据同步任务。 + +- 将 binlog 数据持久化保存在本地 +- 保存数据同步子任务的配置信息 +- 编排数据同步子任务的运行 +- 监控数据同步子任务的运行状态 + +DM-worker 启动后，会自动同步上游 binlog 至本地配置目录（如果使用 DM-Ansible 部署 DM 集群，默认的同步目录为 `/relay_log`）。关于 DM-worker，详见 [DM-worker 简介](/reference/tools/data-migration/dm-worker-intro.md)。关于 relay log，详见 [DM Relay Log](/reference/tools/data-migration/relay-log.md)。 + +### dmctl + +dmctl 是用来控制 DM 集群的命令行工具。 + +- 创建、更新或删除数据同步任务 +- 查看数据同步任务状态 +- 处理数据同步任务错误 +- 校验数据同步任务配置的正确性 + +## 同步功能介绍 + +下面简单介绍 DM 数据同步功能的核心特性。 + +### Table routing + +[Table routing](/reference/tools/data-migration/features/overview.md#table-routing) 是指将上游 MySQL 或 MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步。 + +### Black & white table lists + +[Black & white table lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists) 是指上游数据库实例表的黑白名单过滤规则。其过滤规则类似于 MySQL `replication-rules-db`/`replication-rules-table`，可以用来过滤或只同步某些数据库或某些表的所有操作。 + +### Binlog event filter + +[Binlog event filter](/reference/tools/data-migration/features/overview.md#binlog-event-filter) 是比库表同步黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema`/`table` 的指定类型的 binlog events，比如 `INSERT`，`TRUNCATE TABLE`。 + +### Shard support + +DM 支持对原分库分表进行合库合表操作，但需要满足一些[使用限制](/reference/tools/data-migration/features/shard-merge.md#使用限制)。 + +## 使用限制 + +在使用 DM 工具之前，需了解以下限制： + ++ 数据库版本 + + - 5.5 < MySQL 版本 < 8.0 + - MariaDB 版本 >= 10.1.2 + + > **注意：** + > + > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则需要 5.7.1 < MySQL 版本 < 8.0 或者 MariaDB 版本 >= 10.1.3。 + + 在使用 dmctl 启动任务时，DM 会自动对任务上下游数据库的配置、权限等进行[前置检查](/reference/tools/data-migration/precheck.md)。 + ++ DDL 语法 + + - 目前，TiDB 部分兼容 MySQL 支持的 DDL 语句。因为 DM 使用 TiDB parser 来解析处理 DDL 语句，所以目前仅支持 TiDB parser 支持的 DDL 语法。详见 [TiDB DDL 语法支持](/reference/mysql-compatibility.md#ddl)。 + + - DM 遇到不兼容的 DDL 语句时会报错。要解决此报错，需要使用 dmctl 手动处理，要么跳过该 DDL 语句，要么用指定的 DDL 语句来替换它。详见[如何处理不兼容的 DDL 语句](/reference/tools/data-migration/faq.md#如何处理不兼容的-ddl-语句)。 + ++ 分库分表 + + - 如果业务分库分表之间存在数据冲突，可以参考[自增主键冲突处理](/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决；否则不推荐使用 DM 进行同步，如果进行同步则有冲突的数据会相互覆盖造成数据丢失。 + - 关于分库分表合并场景的其它限制，参见[使用限制](/reference/tools/data-migration/features/shard-merge.md#使用限制)。 + ++ 操作限制 + + - DM-worker 重启后不能自动恢复数据同步任务，需要使用 dmctl 手动执行 `start-task`。详见[管理数据同步任务](/reference/tools/data-migration/manage-tasks.md)。 + - 在一些情况下，DM-worker 重启后不能自动恢复 DDL lock 同步，需要手动处理。详见[手动处理 Sharding DDL Lock](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 + ++ DM-worker 切换 MySQL + + - 当 DM-worker 通过虚拟 IP（VIP）连接到 MySQL 且要切换 VIP 指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。如需切换 VIP 指向的 MySQL 实例，请参考[虚拟 IP 环境下的上游主从切换](/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-ip-环境下切换-dm-worker-与-mysql-实例的连接)对 DM 手动执行变更。 diff --git a/reference/tools/data-migration/precheck.md b/reference/tools/data-migration/precheck.md new file mode 100644 index 000000000000..418325617af2 --- /dev/null +++ b/reference/tools/data-migration/precheck.md @@ -0,0 +1,63 @@ +--- +title: 上游 MySQL 实例配置前置检查 +category: reference +--- + +# 上游 MySQL 实例配置前置检查 + +本文介绍了 DM 提供的前置检查功能，此功能用于在数据同步任务启动时提前检测出上游 MySQL 实例配置中可能存在的一些错误。 + +## 使用命令 + +`check-task` 命令用于对上游 MySQL 实例配置是否满足 DM 要求进行前置检查。 + +## 检查内容 + +上下游数据库用户必须具备相应读写权限。当数据同步任务启动时，DM 会自动检查下列权限和配置： + ++ 数据库版本 + + - 5.5 < MySQL 版本 < 8.0 + - MariaDB 版本 >= 10.1.2 + ++ MySQL binlog 配置 + + - binlog 是否开启（DM 要求 binlog 必须开启） + - 是否有 `binlog_format=ROW`（DM 只支持 ROW 格式的 binlog 同步） + - 是否有 `binlog_row_image=FULL`（DM 只支持 `binlog_row_image=FULL`） + ++ 上游 MySQL 实例用户的权限 + + DM 配置中的 MySQL 用户至少需要具备以下权限： + + - REPLICATION SLAVE + - REPLICATION CLIENT + - RELOAD + - SELECT + ++ 上游 MySQL 表结构的兼容性 + + TiDB 和 MySQL 的兼容性存在以下一些区别： + + - TiDB 不支持外键 + - 字符集的兼容性不同，详见 [TiDB 支持的字符集](/reference/sql/character-set.md) + ++ 上游 MySQL 多实例分库分表的一致性 + + + 所有分表的表结构是否一致，检查内容包括： + + - Column 数量 + - Column 名称 + - Column 位置 + - Column 类型 + - 主键 + - 唯一索引 + + + 分表中自增主键冲突检查 + + - 在两种情况下会造成检查失败： + + - 分表存在自增主键，且自增主键 column 类型不为 bigint + - 分表存在自增主键，自增主键 column 类型为 bigint，但没有为其配置列值转换 + + - 其他情况下检查将成功 diff --git a/reference/tools/data-migration/query-status.md b/reference/tools/data-migration/query-status.md new file mode 100644 index 000000000000..82ab81f8b353 --- /dev/null +++ b/reference/tools/data-migration/query-status.md @@ -0,0 +1,262 @@ +--- +title: DM 查询状态 +category: reference +--- + +# DM 查询状态 + +本文介绍 DM（Data Migration）`query-status` 命令的查询结果、任务状态与子任务状态。 + +## 查询结果 + +{{< copyable "" >}} + +```bash +» query-status +``` + +``` +{ + "result": true, # 查询是否成功。 + "msg": "", # 查询失败原因描述。 + "tasks": [ # 迁移 task 列表 + { + "taskName": "test-1", # 任务名称 + "taskStatus": "Running", # 任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped”，“Finished” 以及 “Error”。 + "workers": [ # 该任务所使用的 DM-workers 列表 + "127.0.0.1:8262" + ] + }, + { + "taskName": "test-2", + "taskStatus": "Error - Some error occurred in subtask", # 该任务的子任务存在运行错误并暂停的现象 + "workers": [ + "127.0.0.1:8262", + "127.0.0.1:8263" + ] + }, + { + "taskName": "test-3", + "taskStatus": "Error - Relay status is Error", # 该任务的某个处于 Sync 阶段的子任务对应的 Relay 处理单元出错 + "workers": [ + "127.0.0.1:8263", + "127.0.0.1:8264" + ] + } + ] +} +``` + +关于 tasks 下的 taskStatus 状态的详细定义，请参阅[任务状态](#任务状态)。 + +推荐的 `query-status` 使用方法是： + +1. 首先使用 query-status 查看各个 task 的运行状态是否正常。 +2. 如果发现其中某一 task 状态有问题，通过 `query-status <出错任务的 taskName>` 来得到更详细的错误信息。 + +## 任务状态 + +DM 的迁移任务状态取决于其分配到 DM-worker 上的[子任务状态](#子任务状态)，定义见下表： + +| 任务对应的所有子任务的状态 | 任务状态 | +| :--- | :--- | +| 任一子任务处于 “Paused” 状态且返回结果有错误信息 | Error - Some error occurred in subtask | +| 任一处于 Sync 阶段的子任务处于 “Running” 状态但其 Relay 处理单元未运行（处于 Error/Paused/Stopped 状态） | Error - Relay status is Error/Paused/Stopped | +| 任一子任务处于 “Paused” 状态且返回结果没有错误信息 | Paused | +| 所有子任务处于 “New” 状态 | New | +| 所有子任务处于 “Finished” 状态 | Finished | +| 所有子任务处于 “Stopped” 状态 | Stopped | +| 其他情况 | Running | + +## 详情查询结果 + +{{< copyable "" >}} + +```bash +» query-status test +``` + +``` +{ + "result": true, # 查询是否成功。 + "msg": "", # 查询失败原因描述。 + "workers": [ # DM-worker 列表。 + { + "result": true, + "worker": "172.17.0.2:8262", # DM-worker ID。 + "msg": "", + "subTaskStatus": [ # DM-worker 所有子任务的信息。 + { + "name": "test", # 子任务名称。 + "stage": "Running", # 子任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped” 以及 “Finished”。 + "unit": "Sync", # DM 的处理单元，包括 “Check”，“Dump“，“Load” 以及 “Sync”。 + "result": null, # 子任务失败时显示错误信息。 + "unresolvedDDLLockID": "test-`test`.`t_target`", # sharding DDL lock ID，可用于异常情况下手动处理 sharding DDL lock。 + "sync": { # 当前 `Sync` 处理单元的同步信息。 + "totalEvents": "12", # 该子任务中同步的 binlog event 总数。 + "totalTps": "1", # 该子任务中每秒同步的 binlog event 数量。 + "recentTps": "1", # 该子任务中最后一秒同步的 binlog event 数量。 + "masterBinlog": "(bin.000001, 3234)", # 上游数据库当前的 binlog position。 + "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库当前的 GTID 信息。 + "syncerBinlog": "(bin.000001, 2525)", # 已被 `Sync` 处理单元同步的 binlog position。 + "syncerBinlogGtid": "", # 当前版本总是为空（因为 `Sync` 处理单元暂不使用 GTID 同步数据）。 + "blockingDDLs": [ # 当前被阻塞的 DDL 列表。该项仅在当前 DM-worker 所有上游表都处于 “synced“ 状态时才有数值，此时该列表包含的是待执行或待跳过的 sharding DDL 语句. + "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" + ], + "unresolvedGroups": [ # 没有被解决的 sharding group 信息。 + { + "target": "`test`.`t_target`", # 待同步的下游表。 + "DDLs": [ + "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" + ], + "firstPos": "(bin|000001.000001, 3130)", # sharding DDL 语句起始 binlog position。 + "synced": [ # `Sync` 处理单元已经读到该 sharding DDL 的上游分表。 + "`test`.`t2`" + "`test`.`t3`" + "`test`.`t1`" + ], + "unsynced": [ # `Sync` 处理单元未读到该 sharding DDL 的上游分表。如有上游分表未完成同步，`blockingDDLs` 为空。 + ] + } + ], + "synced": false # 增量同步是否已追上上游。由于后台 `Sync` 单元并不会实时刷新保存点，当前值为 “false“ 并不一定代表发生了同步延迟。 + } + } + ], + "relayStatus": { # relay 单元的同步状态. + "masterBinlog": "(bin.000001, 3234)", # 上游数据库的 binlog position。 + "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库的 binlog GTID 信息。 + "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", # 当前使用的 relay log 子目录。 + "relayBinlog": "(bin.000001, 3234)", # 已被拉取至本地存储的 binlog position。 + "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 已被拉取至本地存储的 binlog GTID 信息。 + "relayCatchUpMaster": true, # 本地 relay log 同步进度是否与上游一致。 + "stage": "Running", # relay 处理单元状态 + "result": null + }, + "sourceID": "172.17.0.2:3306" # 上游实例或者复制组 ID + }, + { + "result": true, + "worker": "172.17.0.3:8262", + "msg": "", + "subTaskStatus": [ + { + "name": "test", + "stage": "Running", + "unit": "Load", + "result": null, + "unresolvedDDLLockID": "", + "load": { # `Load` 处理单元的同步信息。 + "finishedBytes": "115", # 已全量导入字节数。 + "totalBytes": "452", # 总计需要导入的字节数。 + "progress": "25.44 %" # 全量导入进度。 + } + } + ], + "relayStatus": { + "masterBinlog": "(bin.000001, 28507)", + "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", + "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", + "relayBinlog": "(bin.000001, 28507)", + "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", + "relayCatchUpMaster": true, + "stage": "Running", + "result": null + }, + "sourceID": "172.17.0.3:3306" + }, + { + "result": true, + "worker": "172.17.0.6:8262", + "msg": "", + "subTaskStatus": [ + { + "name": "test", + "stage": "Paused", + "unit": "Load", + "result": { # 错误示例 + "isCanceled": false, + "errors": [ + { + "Type": "ExecSQL", + "msg": "Error 1062: Duplicate entry '1155173304420532225' for key 'PRIMARY'\n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:160: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:105: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/loader.go:138: file test.t1.sql" + } + ], + "detail": null + }, + "unresolvedDDLLockID": "", + "load": { + "finishedBytes": "0", + "totalBytes": "156", + "progress": "0.00 %" + } + } + ], + "relayStatus": { + "masterBinlog": "(bin.000001, 1691)", + "masterBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", + "relaySubDir": "97b5142f-e19c-11e8-808c-0242ac110005.000001", + "relayBinlog": "(bin.000001, 1691)", + "relayBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", + "relayCatchUpMaster": true, + "stage": "Running", + "result": null + }, + "sourceID": "172.17.0.6:3306" + } + ] +} +``` + +关于 `workers` 下 `subTaskStatus` 中 `stage` 状态和状态转换关系的详细信息，请参阅[子任务状态](#子任务状态)。 + +关于 `workers` 下 `subTaskStatus` 中 `unresolvedDDLLockID`的操作细节，请参阅[手动处理 Sharding DDL Lock](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 + +## 子任务状态 + +### 状态描述 + +- `New`： + + - 初始状态。 + - 如果子任务没有发生错误，状态切换为 `Running`，其他情况则切换为 `Paused`。 + +- `Running`：正常运行状态。 + +- `Paused`： + + - 暂停状态。 + - 子任务发生错误，状态切换为 `Paused`。 + - 如在子任务为 `Running` 状态下执行 `pause-task` 命令，任务状态会切换为 `Paused`。 + - 如子任务处于该状态，可以使用 `resume-task` 命令恢复任务。 + +- `Stopped`： + + - 停止状态。 + - 如在子任务为 `Running` 或 `Paused` 状态下执行 `stop-task` 命令，任务状态会切换为 `Stopped`。 + - 如子任务处于该状态，不可使用 `resume-task` 命令恢复任务。 + +- `Finished`： + + - 任务完成状态。 + - 只有 `task-mode` 为 `full` 的任务正常完成后，任务才会切换为该状态。 + +### 状态转换图 + +``` + error occurs + New --------------------------------| + | | + | resume-task | + | |----------------------------| | + | | | | + | | | | + v v error occurs | v + Finished <-------------- Running -----------------------> Paused + ^ | or pause-task | + | | | + start task | | stop task | + | | | + | v stop task | + Stopped <-------------------------| +``` diff --git a/dev/reference/tools/data-migration/relay-log.md b/reference/tools/data-migration/relay-log.md similarity index 100% rename from dev/reference/tools/data-migration/relay-log.md rename to reference/tools/data-migration/relay-log.md diff --git a/dev/reference/tools/data-migration/releases/1.0.2.md b/reference/tools/data-migration/releases/1.0.2.md similarity index 100% rename from dev/reference/tools/data-migration/releases/1.0.2.md rename to reference/tools/data-migration/releases/1.0.2.md diff --git a/dev/reference/tools/data-migration/releases/1.0.3.md b/reference/tools/data-migration/releases/1.0.3.md similarity index 100% rename from dev/reference/tools/data-migration/releases/1.0.3.md rename to reference/tools/data-migration/releases/1.0.3.md diff --git a/reference/tools/data-migration/skip-replace-sqls.md b/reference/tools/data-migration/skip-replace-sqls.md new file mode 100644 index 000000000000..4ecee753a90c --- /dev/null +++ b/reference/tools/data-migration/skip-replace-sqls.md @@ -0,0 +1,663 @@ +--- +title: 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 +category: reference +--- + +# 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 + +本文介绍了如何使用 DM 来处理异常的 SQL 语句。 + +目前，TiDB 并不完全兼容所有的 MySQL 语法（详见 [TiDB 已支持的 DDL 语句](/reference/mysql-compatibility.md#ddl)）。当使用 DM 从 MySQL 同步数据到 TiDB 时，如果 TiDB 不支持对应的 SQL 语句，可能会造成错误并中断同步任务。在这种情况下，DM 提供以下两种方式来恢复同步： + +- 使用 dmctl 来手动跳过该 SQL 语句对应的 binlog event。 + +- 使用 dmctl 来手动指定其他 SQL 语句来替代该 SQL 语句对应的 binlog event，并向下游执行。 + +如果提前预知将要同步 TiDB 不支持的 SQL 语句，也可以使用 dmctl 来手动预设跳过/替代执行操作。当 DM 尝试将该 SQL 语句对应的 binlog event 同步到下游时，该预设的操作将自动执行，从而避免同步过程被中断。 + + + +#### 使用限制 + +- 跳过/替代执行操作只适合用于一次性跳过/替代执行**下游 TiDB 不支持执行的 SQL 语句**，其它同步错误请不要使用此方式进行处理。 + + - 其它同步错误可尝试使用 [black & white table lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists) 或 [binlog event filter](/reference/tools/data-migration/features/overview.md#binlog-event-filter)。 + +- 如果业务不能接受下游 TiDB 跳过异常的 DDL 语句，也不接受使用其他 DDL 语句作为替代，则不适合使用此方式进行处理。 + + - 比如：`DROP PRIMARY KEY` + - 这种情况下，只能在下游重建一个（DDL 执行完后的）新表结构对应的表，并将原表的全部数据重新导入该新表。 + +- 单次跳过/替代执行操作都是针对单个 binlog event 的。 + +- `--sharding` 仅用于对 sharding group 预设一些操作，并且必须在 DDL 语句执行之前预设，不能在 DDL 语句已经执行后预设。 + + - `--sharding` 模式下只支持预设，并只能使用 `--sql-pattern` 来匹配 binlog event。 + - 有关使用 DM 处理 sharding DDL 同步的原理，请参阅[分库分表合并同步原理](/reference/tools/data-migration/features/shard-merge.md#实现原理)。 + +#### 匹配 binlog event + +当同步任务由于执行 SQL 语句出错而中断时，可以使用 `query-error` 命令获取对应 binlog event 的 position 信息。在执行 `sql-skip` / `sql-replace` 时，通过指定该 position 信息，即可与对应的 binlog event 进行匹配。 + +然而，在同步中断前主动处理不被支持的 SQL 语句的情况下，由于无法提前预知 binlog event 的 position 信息，则需要使用其他方式来确保与后续将到达的 binlog event 进行匹配。 + +在 DM 中，支持如下两种 binlog event 匹配模式（两种模式只能选择其中一种）： + +1. binlog position：binlog event 的 position 信息 + + - binlog position 在命令中使用 `--binlog-pos` 参数传入，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 + - DM 中 binlog filename 的格式与上游 MySQL 中 binlog filename 的格式不完全一致。 + - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 + +2. DDL pattern：（仅限于 DDL 语句的）正则表达式匹配模式 + + - DDL pattern 在命令中使用 `--sql-pattern` 参数传入，如要匹配 ```ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` ```，则对应的正则表达式为 ```~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` ```。 + - 正则表达式必须以 `~` 为前缀，且不包含任何原始空格（正则表达式字符串中的空格均以 `\s` 或 `\s+` 表示）。 + +对于合库合表场景，如果需要由 DM 自动选择 DDL lock owner 来执行跳过/替代执行操作，则由于不同 DM-worker 上 DDL 语句对应的 binlog position 无逻辑关联且难以确定，因此只能使用 DDL pattern 匹配模式。 + +> **注意：** +> +> - 一个 binlog event 只能注册一个使用 `--binlog-pos` 指定的 operator，后注册的 operator 会覆盖之前已经注册的 operator。 +> - 不要尝试为一个 binlog event 同时使用 `--binlog-pos` 和 `--sql-pattern` 指定 operator。 +> - operator 在与 binlog event 匹配成功后（而非执行成功后）即会被删除，后续如果需要再进行（`--sql-pattern`）匹配则必须重新注册。 + +### 支持场景 + +- 场景一：同步过程中，上游执行了 TiDB 不支持的 DDL 语句并同步到了 DM，造成同步任务中断。 + + - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 跳过对该 DDL 语句的同步以恢复同步任务。 + - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 替代该 DDL 的同步以恢复同步任务。 + +- 场景二：同步过程中，预先知道了上游将执行 TiDB 不支持的 DDL 语句，则需要提前处理以避免同步任务中断。 + + - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 预设一个跳过该 DDL 语句的操作，当执行到该 DDL 语句时即自动跳过。 + - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 预设一个替代该 DDL 语句的操作，当执行到该 DDL 语句时即自动替代。 + +### 实现原理 + +DM 在进行增量数据同步时，简化后的流程大致为： + +1. relay 处理单元从上游拉取 binlog 存储在本地作为 relay log。 + +2. binlog 同步单元（sync）读取本地 relay log，获取其中的 binlog event。 + +3. binlog 同步单元解析该 binlog event 并构造 DDL/DML 语句，然后将这些语句向下游 TiDB 执行。 + +在 binlog 同步单元解析完 binlog event 并向下游 TiDB 执行时，可能会由于 TiDB 不支持对应的 SQL 语句而报错并造成同步中断。 + +在 DM 中，可以为 binlog event 注册一些跳过/替代执行操作（operator）。在向下游 TiDB 执行 SQL 语句前，将当前的 binlog event 信息（position、DDL 语句）与注册的 operator 进行比较。如果 position 或 DDL 语句与注册的某个 operator 匹配，则执行该 operator 对应的操作并将该 operator 移除。 + +**同步中断后使用 `sql-skip` 或 `sql-replace` 恢复同步的流程** + +1. 使用 `sql-skip` 或 `sql-replace` 为指定的 binlog position 或 DDL pattern 注册 operator。 + +2. 使用 `resume-task` 恢复之前由于同步出错导致中断的任务。 + +3. 重新解析获得之前造成同步出错的 binlog event。 + +4. 该 binlog event 与第一步注册的 operator 匹配成功。 + +5. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 + +**同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** + +1. 使用 `sql-skip` 或 `sql-replace` 为指定的 DDL pattern 注册 operator。 + +2. 从 relay log 中解析获得 binlog event。 + +3. （包含 TiDB 不支持 SQL 语句的）binlog event 与第一步注册的 operator 匹配成功。 + +4. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务，任务不发生中断。 + +**合库合表同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** + +1. 使用 `sql-skip` 或 `sql-replace`（在 DM-master 上）为指定的 DDL pattern 注册 operator。 + +2. 各 DM-worker 从 relay log 中解析获得 binlog event。 + +3. DM-master 协调各个 DM-worker 进行 DDL lock 同步。 + +4. DM-master 判断得知 DDL lock 同步成功后，将第一步注册的 operator 发送给 DDL lock owner。 + +5. DM-master 请求 DDL lock owner 执行 DDL 语句。 + +6. DDL lock owner 将要执行的 DDL 语句与第四步收到的 operator 匹配成功。 + +7. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 + +### 命令介绍 + +使用 dmctl 手动处理 TiDB 不支持的 SQL 语句时，主要使用的命令包括 `query-status`、`query-error`、`sql-skip` 和 `sql-replace`。 + +#### query-status + +`query-status` 命令用于查询当前 DM-worker 内子任务及 relay 单元等的状态，详见[查询状态](/reference/tools/data-migration/query-status.md)。 + +#### query-error + +`query-error` 命令用于查询 DM-worker 内子任务及 relay 单元当前在运行中存在的错误。 + +##### 命令用法 + +```bash +query-error [--worker=127.0.0.1:8262] [task-name] +``` + +##### 参数解释 + ++ `worker`： + - flag 参数，string，`--worker`，可选； + - 不指定时查询所有 DM-worker 上的错误，指定时仅查询特定一组 DM-worker 上的错误。 + ++ `task-name`： + - 非 flag 参数，string，可选； + - 不指定时查询所有任务内的错误，指定时仅查询特定任务内的错误。 + +##### 结果示例 + +{{< copyable "" >}} + +```bash +» query-error test +``` + +``` +{ + "result": true, # query-error 操作本身是否成功 + "msg": "", # query-error 操作失败的说明信息 + "workers": [ # DM-worker 信息列表 + { + "result": true, # 该 DM-worker 上 query-error 操作是否成功 + "worker": "127.0.0.1:8262", # 该 DM-worker 的 IP:port（worker-id） + "msg": "", # 该 DM-worker 上 query-error 操作失败的说明信息 + "subTaskError": [ # 该 DM-worker 上运行子任务的错误信息 + { + "name": "test", # 任务名 + "stage": "Paused", # 当前任务的状态 + "unit": "Sync", # 当前正在处理任务的处理单元 + "sync": { # binlog 同步单元（sync）的错误信息 + "errors": [ # 当前处理单元的错误信息列表 + { + // 错误信息描述 + "msg": "exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, err:Error 1105: unsupported modify column length 10 is less than origin 11", + // 发生错误的 binlog event 的 position + "failedBinlogPosition": "mysql-bin|000001.000003:34642", + // 发生错误的 SQL 语句 + "errorSQL": "[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]" + } + ] + } + } + ], + "RelayError": { # 该 DM-worker 上 relay 处理单元的错误信息 + "msg": "" # 错误信息描述 + } + } + ] +} +``` + +#### sql-skip + +`sql-skip` 命令用于预设一个跳过操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。 + +##### 命令用法 + +```bash +sql-skip <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] +``` + +##### 参数解释 + ++ `worker`： + - flag 参数，string，`--worker`； + - 未指定 `--sharding` 时必选，指定 `--sharding` 时禁止使用； + - `worker` 指定预设操作将生效的 DM-worker。 + ++ `binlog-pos`： + - flag 参数，string，`--binlog-pos`； + - `binlog-pos` 与 `--sql-pattern` 必须指定其中一个，且只能指定其中一个。 + - 在指定时表示操作将在 `binlog-pos` 与 binlog event 的 position 匹配时生效，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 + - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 + ++ `sql-pattern`： + - flag 参数，string，`--sql-pattern`； + - `--sql-pattern` 与 `binlog-pos` 必须指定其中一个，且只能指定其中一个。 + - 在指定时表示操作将在 `sql-pattern` 与 binlog event 对应的（经过可选的 router-rule 转换后的）DDL 语句匹配时生效。格式为以 `~` 为前缀的正则表达式，如 ```~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT```。 + - 暂时不支持正则表达式中包含原始空格，需要使用 `\s` 或 `\s+` 替代空格。 + - 正则表达式必须以 `~` 为前缀，详见[正则表达式语法](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。 + - 正则表达式中的库名和表名必须是经过可选的 router-rule 转换后的名字，即对应下游的目标库名和表名。如上游为 ``` `shard_db_1`.`shard_tbl_1` ```，下游为 ``` `shard_db`.`shard_tbl` ```，则应该尝试匹配 ``` `shard_db`.`shard_tbl` ```。 + - 正则表达式中的库名、表名及列名需要使用 ``` ` ``` 标记，如 ``` `db1`.`tbl1` ```。 + ++ `sharding`： + - flag 参数，boolean，`--sharding`； + - 未指定 `--worker` 时必选，指定 `--worker` 时禁止使用； + - 在指定时表示预设的操作将在 sharding DDL 同步过程中的 DDL lock owner 内生效。 + ++ `task-name`： + - 非 flag 参数，string，必选； + - 指定预设的操作将生效的任务。 + +#### sql-replace + +`sql-replace` 命令用于预设一个替代执行操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替代执行操作。 + +##### 命令用法 + +```bash +sql-replace <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] +``` + +##### 参数解释 + ++ `worker`： + - 与 `sql-skip` 命令的 `--worker` 参数解释一致。 + ++ `binlog-pos`： + - 与 `sql-skip` 命令的 `--binlog-pos` 参数解释一致。 + ++ `sql-pattern`： + - 与 `sql-skip` 命令的 `--sql-pattern` 参数解释一致。 + ++ `sharding`： + - 与 `sql-skip` 命令的 `--sharding` 参数解释一致。 + ++ `task-name`： + - 与 `sql-skip` 命令的 `task-name` 参数解释一致。 + ++ `SQLs`： + - 非 flag 参数，string，必选； + - `SQLs` 指定将用于替代原 binlog event 的新的 SQL 语句。多条 SQL 语句间以 `;` 分隔，如 ```ALTER TABLE shard_db.shard_table drop index idx_c2;ALTER TABLE shard_db.shard_table DROP COLUMN c2;```。 + +### 使用示例 + +#### 同步中断后被动执行跳过操作 + +##### 应用场景 + +假设现在需要将上游的 `db1.tbl1` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE db1.tbl1; +``` + +``` ++-------+--------------------------------------------------+ +| Table | Create Table | ++-------+--------------------------------------------------+ +| tbl1 | CREATE TABLE `tbl1` ( + `c1` int(11) NOT NULL, + `c2` decimal(11,3) DEFAULT NULL, + PRIMARY KEY (`c1`) +) ENGINE=InnoDB DEFAULT CHARSET=latin1 | ++-------+--------------------------------------------------+ +``` + +此时，上游执行以下 DDL 操作修改表结构（将列的 DECIMAL(11, 3) 修改为 DECIMAL(10, 3)）： + +{{< copyable "sql" >}} + +```sql +ALTER TABLE db1.tbl1 CHANGE c2 c2 DECIMAL (10, 3); +``` + +则会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： + +``` +exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, +err:Error 1105: unsupported modify column length 10 is less than origin 11 +``` + +此时使用 `query-status` 查询任务状态，可看到 `stage` 转为了 `Paused`，且 `errors` 中有相关的错误描述信息。 + +使用 `query-error` 可以获取该错误的详细信息。比如，执行 `query-error test` 可获得出错的 binlog event 的 position（`failedBinlogPosition`）为 `mysql-bin|000001.000003:34642`。 + +##### 被动跳过 SQL 语句 + +假设业务上可以接受下游 TiDB 不执行此 DDL 语句（即继续保持原有的表结构），则可以通过使用 `sql-skip` 命令跳过该 DDL 语句以恢复同步任务。操作步骤如下： + +1. 使用 `query-error` 获取同步出错的 binlog event 的 position 信息。 + - position 信息可直接由 `query-error` 返回的 `failedBinlogPosition` 获得。 + - 本示例中的 position 为 `mysql-bin|000001.000003:34642`。 + +2. 使用 `sql-skip` 预设一个 binlog event 跳过操作，该操作将在使用 `resume-task` 后同步该 binlog event 到下游时生效。 + + {{< copyable "" >}} + + ```bash + » sql-skip --worker=127.0.0.1:8262 --binlog-pos=mysql-bin|000001.000003:34642 test + ``` + + ``` + { + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "", + "msg": "" + } + ] + } + ``` + + 对应 DM-worker 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 11:17:51 operator.go:121: [info] [sql-operator] set a new operator + uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: + on replication unit + ``` + +3. 使用 `resume-task` 恢复之前出错中断的同步任务。 + + {{< copyable "" >}} + + ```bash + » resume-task --worker=127.0.0.1:8262 test + ``` + + ``` + { + "op": "Resume", + "result": true, + "msg": "", + "workers": [ + { + "op": "Resume", + "result": true, + "worker": "127.0.0.1:8262", + "msg": "" + } + ] + } + ``` + + 对应 DM-worker 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 11:27:46 operator.go:158: [info] [sql-operator] binlog-pos (mysql-bin|000001.000003, 34642) matched, + applying operator uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: + ``` + +4. 使用 `query-status` 确认该任务的 `stage` 已经转为 `Running`。 + +5. 使用 `query-error` 确认原错误信息已不再存在。 + +#### 同步中断前主动执行替代执行操作 + +##### 应用场景 + +假设现在需要将上游的 `db2.tbl2` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE db2.tbl2; +``` + +``` ++-------+--------------------------------------------------+ +| Table | Create Table | ++-------+--------------------------------------------------+ +| tbl2 | CREATE TABLE `tbl2` ( + `c1` int(11) NOT NULL, + `c2` int(11) DEFAULT NULL, + PRIMARY KEY (`c1`), + KEY `idx_c2` (`c2`) +) ENGINE=InnoDB DEFAULT CHARSET=latin1 | ++-------+--------------------------------------------------+ +``` + +此时，上游执行以下 DDL 操作修改表结构（即 DROP 列 c2）： + +{{< copyable "sql" >}} + +```sql +ALTER TABLE db2.tbl2 DROP COLUMN c2; +``` + +当同步该 DDL 语句对应的 binlog event 到下游时，会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： + +``` +exec sqls[[USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;]] failed, +err:Error 1105: can't drop column c2 with index covered now +``` + +**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 为该 DDL 语句预设一个跳过（skip）或替代执行（replace）操作。 + +对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP 列 c2。 + +##### 主动替代执行该 SQL 语句 + +1. 为将要在上游执行的 DDL 语句（经过可选的 router-rule 转换后的 DDL 语句）设计一个能匹配上的正则表达式。 + - 上游将执行的 DDL 语句为 `ALTER TABLE db2.tbl2 DROP COLUMN c2;`。 + - 由于该 DDL 语句不存在 router-rule 转换，可设计如下正则表达式： + + ``` + ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` + ``` + +2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： + + {{< copyable "sql" >}} + + ```sql + ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`; + ``` + +3. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 + + {{< copyable "" >}} + + ```bash + » sql-replace --worker=127.0.0.1:8262 --sql-pattern=~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` + ``` + + ``` + { + "result": true, + "msg": "", + "workers": [ + { + "result": true, + "worker": "", + "msg": "" + } + ] + } + ``` + + 对应 DM-worker 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 15:33:13 operator.go:121: [info] [sql-operator] set a new operator + uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, + op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` + on replication unit + ``` + +4. 在上游 MySQL 执行该 DDL 语句。 + +5. 观察下游表结构是否变更成功，对应 DM-worker 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 15:33:45 operator.go:158: [info] [sql-operator] + sql-pattern ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` matched SQL + USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;, + applying operator uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, + pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, + op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` + ``` + +6. 使用 `query-status` 确认该任务的 `stage` 持续为 `Running`。 + +7. 使用 `query-error` 确认不存在 DDL 执行错误。 + +#### 合库合表场景下同步中断后被动执行跳过操作 + +##### 应用场景 + +假设现在通过多个 DM-worker 将上游多个 MySQL 实例内的多个表进行合库合表同步到下游 TiDB 的同一个表，并且上游各分表执行了 TiDB 不支持的 DDL 语句。 + +DM-master 通过 DDL lock 协调 DDL 同步、并请求 DDL lock owner 向下游 TiDB 执行该 DDL 语句后，由于 TiDB 不支持该 DDL 语句，同步任务会报错并中断。 + +##### 被动跳过 SQL 语句 + +合库合表场景下，被动跳过 TiDB 不支持的 DDL 语句的处理方式与非合库合表场景下的[同步中断后被动执行跳过操作](#同步中断后被动执行跳过操作)基本一致。 + +但在合库合表场景下，只需要 DDL lock owner 向下游同步该 DDL 语句，因此在两种场景下的处理过程主要存在以下区别： + +1. 合库合表场景下，仅需要对 DDL lock owner 执行 `sql-skip`（`--worker={DDL-lock-owner}`）。 + +2. 合库合表场景下，仅需要对 DDL lock owner 执行 `resume-task`（`--worker={DDL-lock-owner}`）。 + +#### 合库合表场景下同步中断前主动执行替代执行操作 + +##### 应用场景 + +假设现在存在如下四个上游表需要合并同步到下游的同一个表 ``` `shard_db`.`shard_table` ```： + +- MySQL 实例 1 内有 `shard_db_1` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 +- MySQL 实例 2 内有 `shard_db_2` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 + +初始时表结构为： + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE shard_db_1.shard_table_1; +``` + +``` ++---------------+------------------------------------------+ +| Table | Create Table | ++---------------+------------------------------------------+ +| shard_table_1 | CREATE TABLE `shard_table_1` ( + `c1` int(11) NOT NULL, + `c2` int(11) DEFAULT NULL, + PRIMARY KEY (`c1`), + KEY `idx_c2` (`c2`) +) ENGINE=InnoDB DEFAULT CHARSET=latin1 | ++---------------+------------------------------------------+ +``` + +此时，在上游所有分表上都执行以下 DDL 操作修改表结构（即 DROP 列 c2）： + +{{< copyable "sql" >}} + +```sql +ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2; +``` + +则当 DM 通过 sharding DDL lock 协调两个 DM-worker 同步该 DDL 语句、并请求 DDL lock owner 向下游执行该 DDL 语句时，会由于 TiDB 不支持该 DDL 语句而导致同步任务中断且报如下错误： + +``` +exec sqls[[USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;]] failed, +err:Error 1105: can't drop column c2 with index covered now +``` + +**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 命令为该 DDL 语句预设一个跳过/替代执行操作。 + +对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP c2 列。 + +##### 主动替代执行该 SQL 语句 + +1. 为将要在上游执行的（经过可选的 router-rule 转换后的）DDL 语句设计一个能匹配上的正则表达式。 + - 上游将执行的 DDL 语句为 `ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2`。 + - 由于存在 router-rule 会将表名转换为 ``` `shard_db`.`shard_table` ```，可设计如下正则表达式： + + ``` + ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` + ``` + +2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： + + {{< copyable "sql" >}} + + ```sql + ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; + ``` + +3. 由于这是合库合表场景，因此使用 `--sharding` 参数来由 DM 自动确定替代执行操作只发生在 DDL lock owner 上。 + +4. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 + + {{< copyable "" >}} + + ```bash + » sql-replace --sharding --sql-pattern=~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` + ``` + + ``` + { + "result": true, + "msg": "request with --sharding saved and will be sent to DDL lock's owner when resolving DDL lock", + "workers": [ + ] + } + ``` + + **DM-master** 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 16:53:33 operator.go:105: [info] [sql-operator] set a new operator + uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" + op:REPLACE args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" + args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" + sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" + sharding:true + ``` + +5. 在上游 MySQL 实例的分表上执行 DDL 语句。 + +6. 观察下游表结构是否变更成功，对应的 DDL lock **owner** 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 16:54:35 operator.go:121: [info] [sql-operator] set a new operator + uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, + pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, + op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` + on replication unit + ``` + + ``` + 2018/12/28 16:54:35 operator.go:158: [info] [sql-operator] + sql-pattern ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL + USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;, + applying operator uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, + pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, + op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` + ``` + + 另外，**DM-master** 节点中也可以看到类似如下日志： + + ``` + 2018/12/28 16:54:35 operator.go:122: [info] [sql-operator] get an operator + uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE + args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" + args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" + sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" + sharding:true + with key ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL + USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; + ``` + + ``` + 2018/12/28 16:54:36 operator.go:145: [info] [sql-operator] remove an operator + uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE + args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" + args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" + sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" + sharding:true + ``` + +7. 使用 `query-status` 确认任务的 `stage` 持续为 `Running`，且不存在正阻塞同步的 DDL 语句（`blockingDDLs`）与待解决的 sharding group（`unresolvedGroups`）。 + +8. 使用 `query-error` 确认不存在 DDL 执行错误。 + +9. 使用 `show-ddl-locks` 确认不存在待解决的 DDL lock。 diff --git a/dev/reference/tools/data-migration/table-selector.md b/reference/tools/data-migration/table-selector.md similarity index 100% rename from dev/reference/tools/data-migration/table-selector.md rename to reference/tools/data-migration/table-selector.md diff --git a/reference/tools/data-migration/troubleshoot/dm.md b/reference/tools/data-migration/troubleshoot/dm.md new file mode 100644 index 000000000000..183392222e0d --- /dev/null +++ b/reference/tools/data-migration/troubleshoot/dm.md @@ -0,0 +1,27 @@ +--- +title: Data Migration 故障诊断 +category: reference +aliases: ['/docs-cn/dev/how-to/troubleshoot/data-migration/'] +--- + +# Data Migration 故障诊断 + +本文总结了在 DM 工具使用过程中遇到问题的诊断流程，并指引用户通过错误信息查找相应的解决方案。 + +如果你在运行 DM 工具时出现了错误，请尝试以下解决方案： + +1. 执行 `query-status` 命令查看任务运行状态以及相关错误输出。 + +2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [Data Migration 错误含义](/reference/tools/data-migration/troubleshoot/error-system.md) 获取错误的关键信息，然后查看 [Data Migration 常见错误及修复](/reference/tools/data-migration/troubleshoot/error-handling.md)以寻找相应的解决方案。 + +3. 如果该错误还没有相应的解决方案，并且你无法通过查询日志或监控指标自行解决此问题，你可以联系相关销售人员进行支持。 + +4. 一般情况下，错误处理完成后，只需使用 dmctl 重启任务即可。 + + {{< copyable "shell-regular" >}} + + ```bash + resume-task ${task name} + ``` + +但在某些情况下，你还需要重置数据同步任务。有关何时需要重置以及如何重置，详见[重置数据同步任务](/reference/tools/data-migration/faq.md#重置数据同步任务)。 diff --git a/reference/tools/data-migration/troubleshoot/error-handling.md b/reference/tools/data-migration/troubleshoot/error-handling.md new file mode 100644 index 000000000000..cbfefe9305da --- /dev/null +++ b/reference/tools/data-migration/troubleshoot/error-handling.md @@ -0,0 +1,71 @@ +--- +title: Data Migration 常见错误修复 +category: reference +--- + +# Data Migration 常见错误修复 + +本文档介绍 DM 中常见的错误以及修复方法。 + +## 常见错误说明和处理方法 + +| 错误码 | 错误说明 | 解决方法 | +| :----------- | :------------------------------------------------------------ | :----------------------------------------------------------- | +| `code=10001` | 数据库操作异常 | 进一步分析错误信息和错误堆栈 | +| `code=10002` | 数据库底层的 `bad connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 | DM 提供针对此类错误的自动恢复。如果长时间未恢复，需要用户检查网络或 TiDB 状态。 | +| `code=10003` | 数据库底层 `invalid connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 | DM 提供针对此类错误的自动恢复。如果未能正常恢复，需要用户进一步检查错误信息并根据具体场景进行分析。 | +| `code=10005` | 数据库查询类语句出错 | | +| `code=10006` | 数据库 `EXECUTE` 类型语句出错，包括 DDL 和 `INSERT`/`UPDATE`/`DELETE` 类型的 DML。更详细的错误信息可通过错误 message 获取。错误 message 中通常包含操作数据库所返回的错误码和错误信息。 | | +| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/reference/tools/data-migration/faq.md#处理不兼容的-ddl-语句) 提供的解决方案 | +| `code=20010` | 处理任务配置时，解密数据库的密码出错 | 检查任务配置中提供的下游数据库密码是否有[使用 dmctl 正确加密](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码) | +| `code=26002` | 任务检查创建数据库连接失败。更详细的错误信息可通过错误 message 获取。错误 message 中包含操作数据库所返回的错误码和错误信息。 | 检查 DM-master 所在的机器是否有权限访问上游 | +| `code=32001` | dump 处理单元异常 | 如果报错 `msg` 包含 `mydumper: argument list too long.`，则需要用户根据 black-white list，在 `task.yaml` 的 mydumper `extra-args` 参数中手动加上 `--regex` 正则表达式设置要导出的库表。例如，如果要导出所有库中表名字为 `hello` 的表，可加上 `--regex '.*\\.hello$'`，如果要导出所有表，可加上 `--regex '.*'`。 | +| `code=38008` | DM 组件间的 gRPC 通信出错 | 检查 `class`， 定位错误发生在哪些组件的交互环节，根据错误 message 判断是哪类通信错误。如果是 gRPC 建立连接出错，可检查通信服务端是否运行正常。 | + +## 同步任务中断并包含 `invalid connection` 错误 + +发生 `invalid connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 + +由于 DM 中存在同步任务并发向下游复制数据的特性，因此在任务中断时可能同时包含多个错误（可通过 `query-status` 或 `query-error` 查询当前错误）。 + +- 如果错误中仅包含 `invalid connection` 类型的错误且当前处于增量复制阶段，则 DM 会自动进行重试。 +- 如果 DM 由于版本问题等未自动进行重试或自动重试未能成功，则可尝试先使用 `stop-task` 停止任务，然后再使用 `start-task` 重启任务。 + +## 同步任务中断并包含 `driver: bad connection` 错误 + +发生 `driver: bad connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 + +当前版本 DM 发生该类型错误时，需要先使用 `stop-task` 停止任务后再使用 `start-task` 重启任务。后续 DM 会完善对此错误类型的自动重试机制。 + +## relay 处理单元报错 `event from * in * diff from passed-in event *` 或同步任务中断并包含 `get binlog error ERROR 1236 (HY000)`、`binlog checksum mismatch, data may be corrupted` 等 binlog 获取或解析失败错误 + +在 DM 进行 relay log 拉取与增量同步过程中，如果遇到了上游超过 4GB 的 binlog 文件，就可能出现这两个错误。 + +原因是 DM 在写 relay log 时需要依据 binlog position 及文件大小对 event 进行验证，且需要保存同步的 binlog position 信息作为 checkpoint。但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，进而出现上面的错误。 + +对于 relay 处理单元，可通过以下步骤手动恢复： + +1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 +2. 停止 DM-worker。 +3. 将上游对应的 binlog 文件复制到 relay log 目录作为 relay log 文件。 +4. 更新 relay log 目录内对应的 `relay.meta` 文件以从下一个 binlog 开始拉取。 + + 例如：报错时有 `binlog-name = "mysql-bin.004451"` 与`binlog-pos = 2453`，则将其分别更新为 `binlog-name = "mysql-bin.004452"` 与`binlog-pos = 4`。 +5. 重启 DM-worker。 + +对于 binlog replication 处理单元，可通过以下步骤手动恢复： + +1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 +2. 通过 `stop-task` 停止同步任务。 +3. 将下游 `dm_meta` 数据库中 global checkpoint 与每个 table 的 checkpoint 中的 `binlog_name` 更新为出错的 binlog 文件，将 `binlog_pos` 更新为已同步过的一个合法的 position 值，比如 4。 + + 例如：出错任务名为 `dm_test`，对应的 `source-id` 为 `replica-1`，出错时对应的 binlog 文件为 `mysql-bin|000001.004451`，则执行 `UPDATE dm_test_syncer_checkpoint SET binlog_name='mysql-bin|000001.004451', binlog_pos = 4 WHERE id='replica-1';`。 +4. 在同步任务配置中为 `syncers` 部分设置 `safe-mode: true` 以保证可重入执行。 +5. 通过 `start-task` 启动同步任务。 +6. 通过 `query-status` 观察同步任务状态，当原造成出错的 relay log 文件同步完成后，即可还原 `safe-mode` 为原始值并重启同步任务。 + +## 执行 `query-status` 或查看日志时出现 `Access denied for user 'root'@'172.31.43.27' (using password: YES)` + +在所有 DM 配置文件中，数据库相关的密码都必须使用经 dmctl 加密后的密文（若数据库密码为空，则无需加密）。有关如何使用 dmctl 加密明文密码，参见[使用 dmctl 加密上游 MySQL 用户密码](/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 + +此外，在 DM 运行过程中，上下游数据库的用户必须具备相应的读写权限。在启动同步任务过程中，DM 会自动进行相应权限的前置检查，详见[上游 MySQL 实例配置前置检查](/reference/tools/data-migration/precheck.md)。 diff --git a/dev/reference/tools/data-migration/troubleshoot/error-system.md b/reference/tools/data-migration/troubleshoot/error-system.md similarity index 100% rename from dev/reference/tools/data-migration/troubleshoot/error-system.md rename to reference/tools/data-migration/troubleshoot/error-system.md diff --git a/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md b/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md new file mode 100644 index 000000000000..ece8f4785260 --- /dev/null +++ b/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md @@ -0,0 +1,131 @@ +--- +title: 分表合并数据迁移最佳实践 +summary: 使用 DM 对分库分表进行合并迁移时的最佳实践。 +category: reference +--- +# 分表合并数据迁移最佳实践 + +本文阐述了使用 TiDB Data Migration（以下简称 DM）对分库分表进行合并迁移的场景中，DM 相关功能的支持和限制，旨在给出一个业务的最佳实践。 + +## 独立的数据迁移任务 + +在[分库分表合并同步的实现原理部分](/reference/tools/data-migration/features/shard-merge.md#实现原理)，我们介绍了 sharding group 的概念，简单来说可以理解为需要合并到下游同一个表的所有上游表即组成一个 sharding group。 + +当前的 sharding DDL 算法为了能协调在不同分表执行 DDL 对 schema 变更的影响，加入了一些[使用限制](/reference/tools/data-migration/features/shard-merge.md#使用限制)。而当这些使用限制由于某些异常原因被打破时，我们需要[手动处理 Sharding DDL Lock](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) 甚至是完整重做整个数据迁移任务。 + +因此，为了减小异常发生时对数据迁移的影响，我们推荐将每一个 sharding group 拆分成一个独立的数据迁移任务。**这样当异常发生时，可能只有少部分迁移任务需要进行手动处理，其他数据迁移任务可以不受影响。** + +## 手动处理 sharding DDL lock + +从[分库分表合并同步的实现原理部分](/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，DM 中的 sharding DDL lock 是用于协调不同上游分表向下游执行 DDL 的一种机制，本身并不是异常。 + +因此，当通过 `show-ddl-locks` 查看到 DM-master 上存在 sharding DDL lock 时，或通过 `query-status` 查看到某些 DM-worker 有 `unresolvedGroups` 或 `blockingDDLs` 时，并不要急于使用 `unlock-ddl-lock` 或 `break-ddl-lock` 尝试去手动解除 sharding DDL lock。 + +只有在确认当前未能自动解除 sharding DDL lock 是文档中所列的[支持场景](/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#支持场景)之一时，才能参照对应支持场景中的手动处理示例进行处理。对于其他未被支持的场景，我们建议完整重做整个数据迁移任务，即清空下游数据库中的数据以及该数据迁移任务相关的 `dm_meta` 信息后，重新执行全量数据及增量数据的迁移。 + +## 自增主键冲突处理 + +在 DM 中，我们提供了 [Column mapping](/reference/tools/data-migration/features/overview.md#column-mapping) 用于处理 bigint 类型的自增主键在合并时可能出现冲突的问题，但我们**强烈不推荐**使用该功能。如果业务上允许，我们推荐使用以下两种处理方式。 + +### 去掉自增主键的主键属性 + +假设上游分表的表结构如下： + +```sql +CREATE TABLE `tbl_no_pk` ( + `auto_pk_c1` bigint(20) NOT NULL, + `uk_c2` bigint(20) NOT NULL, + `content_c3` text, + PRIMARY KEY (`auto_pk_c1`), + UNIQUE KEY `uk_c2` (`uk_c2`) +) ENGINE=InnoDB DEFAULT CHARSET=latin1 +``` + +如果满足下列条件： + +- `auto_pk_c1` 列对业务无意义，且不依赖该列的 `PRIMARY KEY` 属性。 +- `uk_c2` 列有 `UNIQUE KEY` 属性，且能保证在所有上游分表间全局唯一。 + +则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： + +1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但将 `auto_pk_c1` 的 `PRIMARY KEY` 属性修改为普通索引。 + + ```sql + CREATE TABLE `tbl_no_pk_2` ( + `auto_pk_c1` bigint(20) NOT NULL, + `uk_c2` bigint(20) NOT NULL, + `content_c3` text, + INDEX (`auto_pk_c1`), + UNIQUE KEY `uk_c2` (`uk_c2`) + ) ENGINE=InnoDB DEFAULT CHARSET=latin1 + ``` + +2. 启动数据迁移任务，执行全量与增量数据迁移。 +3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 + +### 使用联合主键 + +假设上游分表的表结构如下： + +```sql +CREATE TABLE `tbl_multi_pk` ( + `auto_pk_c1` bigint(20) NOT NULL, + `uuid_c2` bigint(20) NOT NULL, + `content_c3` text, + PRIMARY KEY (`auto_pk_c1`) +) ENGINE=InnoDB DEFAULT CHARSET=latin1 +``` + +如果满足下列条件： + +* 业务不依赖 `auto_pk_c1` 的 `PRIMARY KEY` 属性。 +* `auto_pk_c1` 与 `uuid_c2` 的组合能确保全局唯一。 +* 业务能接受将 `auto_pk_c1` 与 `uuid_c2` 组成联合 `PRIMARY KEY`。 + +则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： + +1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但不为 `auto_pk_c1` 指定 `PRIMARY KEY` 属性，而是将 `auto_pk_c1` 与 `uuid_c2` 一起组成 `PRIMARY KEY`。 + + ```sql + CREATE TABLE `tbl_multi_pk_c2` ( + `auto_pk_c1` bigint(20) NOT NULL, + `uuid_c2` bigint(20) NOT NULL, + `content_c3` text, + PRIMARY KEY (`auto_pk_c1`,`uuid_c2`) + ) ENGINE=InnoDB DEFAULT CHARSET=latin1 + ``` + +2. 启动数据迁移任务，执行全量与增量数据迁移。 + +3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 + +## 合表迁移过程中在上游增/删表 + +从[分库分表合并同步的实现原理部分](/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，sharding DDL lock 的协调依赖于是否已收到上游已有各分表对应的 DDL，且当前 DM 在合表迁移过程中暂时**不支持**在上游动态增加或删除分表。如果需要在合表迁移过程中，对上游执行增、删分表操作，推荐按以下方式进行处理。 + +### 在上游增加分表 + +如果需要在上游增加新的分表，推荐按以下顺序执行操作： + +1. 等待在上游分表上执行过的所有 sharding DDL 协调同步完成。 +2. 通过 `stop-task` 停止任务。 +3. 在上游添加新的分表。 +4. 确保 `task.yaml` 配置能使新添加的分表与其他已有的分表能合并到同一个下游表。 +5. 通过 `start-task` 启动任务。 +6. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 + +### 在上游删除分表 + +如果需要在上游删除原有的分表，推荐按以下顺序执行操作： + +1. 在上游删除原有的分表，并通过 [`SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/5.7/en/show-binlog-events.html) 获取该 `DROP TABLE` 语句在 binlog 中对应的 `End_log_pos`，记为 _Pos-M_。 +2. 通过 `query-status` 获取当前 DM 已经处理完成的 binlog event 对应的 position（`syncerBinlog`），记为 _Pos-S_。 +3. 当 _Pos-S_ 比 _Pos-M_ 更大后，则说明 DM 已经处理完 `DROP TABLE` 语句，且该表在被删除前的数据都已经同步到下游，可以进行后续操作；否则，继续等待 DM 进行数据同步。 +4. 通过 `stop-task` 停止任务。 +5. 确保 `task.yaml` 配置能忽略上游已删除的分表。 +6. 通过 `start-task` 启动任务。 +7. 通过 `query-status` 验证数据迁移任务是否正常。 + +## 数据迁移限速/流控 + +当将多个上游 MySQL/MariaDB 实例的数据合并迁移到下游同一个 TiDB 集群时，由于每个与上游 MySQL/MariaDB 对应的 DM-worker 都会并发地进行全量与增量数据迁移，默认的并发度（全量阶段的 `pool-size` 与增量阶段的 `worker-count`）通过多个 DM-worker 累加后，可能会给下游造成过大的压力，此时应根据 TiDB 监控及 DM 监控进行初步的性能分析后，适当地调整各并发度参数的大小。后续 DM 也将考虑支持部分自动的流控策略。 diff --git a/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md b/reference/tools/data-migration/usage-scenarios/master-slave-switch.md similarity index 100% rename from dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md rename to reference/tools/data-migration/usage-scenarios/master-slave-switch.md diff --git a/reference/tools/data-migration/usage-scenarios/shard-merge.md b/reference/tools/data-migration/usage-scenarios/shard-merge.md new file mode 100644 index 000000000000..883c25956950 --- /dev/null +++ b/reference/tools/data-migration/usage-scenarios/shard-merge.md @@ -0,0 +1,242 @@ +--- +title: DM 分库分表合并场景 +category: reference +--- + +# DM 分库分表合并场景 + +本文介绍如何在分库分表合并场景中使用 Data Migration (DM)。使用场景中，三个上游 MySQL 实例的分库和分表数据需要同步至下游 TiDB 集群。 + +## 上游实例 + +假设上游库结构如下： + +- 实例 1 + + | Schema | Tables | + |:------|:------| + | user | information, log_north, log_bak | + | store_01 | sale_01, sale_02 | + | store_02 | sale_01, sale_02 | + +- 实例 2 + + | Schema | Tables | + |:------|:------| + | user | information, log_east, log_bak | + | store_01 | sale_01, sale_02 | + | store_02 | sale_01, sale_02 | + +- 实例 3 + + | Schema | Tables | + |:------|:------| + | user | information, log_south, log_bak | + | store_01 | sale_01, sale_02 | + | store_02 | sale_01, sale_02 | + +## 同步需求 + +1. 合并三个实例中的 `user`.`information` 表至下游 TiDB 中的 `user`.`information` 表。 +2. 合并三个实例中的 `user`.`log_{north|south|east}` 表至下游TiDB中的 `user`.`log_{north|south|east}` 表。 +3. 合并三个实例中的 `store_{01|02}`.`sale_{01|02}` 表至下游TiDB中的 `store`.`sale` 表。 +4. 过滤掉三个实例的 `user`.`log_{north|south|east}` 表的所有删除操作。 +5. 过滤掉三个实例的 `user`.`information` 表的所有删除操作。 +6. 过滤掉三个实例的 `store_{01|02}`.`sale_{01|02}` 表的所有删除操作。 +7. 过滤掉三个实例的 `user`.`log_bak` 表。 +8. 因为 `store_{01|02}`.`sale_{01|02}` 表带有 bigint 型的自增主键，将其合并至 TiDB 时会引发冲突。你需要有相应的方案来避免冲突。 + +## 下游实例 + +假设同步后下游库结构如下： + +| Schema | Tables | +|:------|:------| +| user | information, log_north, log_east, log_south| +| store | sale | + +## 同步方案 + +- 要满足同步需求 #1 和 #2，配置 [Table routing 规则](/reference/tools/data-migration/features/overview.md#table-routing) 如下： + + {{< copyable "" >}} + + ```yaml + routes: + ... + user-route-rule: + schema-pattern: "user" + target-schema: "user" + ``` + +- 要满足同步需求 #3，配置 [table routing 规则](/reference/tools/data-migration/features/overview.md#table-routing) 如下： + + {{< copyable "" >}} + + ```yaml + routes: + ... + store-route-rule: + schema-pattern: "store_*" + target-schema: "store" + sale-route-rule: + schema-pattern: "store_*" + table-pattern: "sale_*" + target-schema: "store" + target-table: "sale" + ``` + +- 要满足同步需求 #4 和 #5，配置 [Binlog event filter 规则](/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： + + {{< copyable "" >}} + + ```yaml + filters: + ... + user-filter-rule: + schema-pattern: "user" + events: ["truncate table", "drop table", "delete", "drop database"] + action: Ignore + ``` + + > **注意：** + > + > 同步需求 #4、#5 和 #7 的操作意味着过滤掉所有对 `user` 库的删除操作，所以此处配置了库级别的过滤规则。但是 `user` 库以后加入表的删除操作也都会被过滤。 + +- 要满足同步需求 #6，配置 [Binlog event filter 规则](/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： + + {{< copyable "" >}} + + ```yaml + filters: + ... + sale-filter-rule: + schema-pattern: "store_*" + table-pattern: "sale_*" + events: ["truncate table", "drop table", "delete"] + action: Ignore + store-filter-rule: + schema-pattern: "store_*" + events: ["drop database"] + action: Ignore + ``` + +- 要满足同步需求 #7，配置 [Black & white table lists](/reference/tools/data-migration/features/overview.md#black--white-table-lists) 如下： + + {{< copyable "" >}} + + ```yaml + black-white-list: + log-bak-ignored: + ignore-tables: + - db-name: "user" + tbl-name: "log_bak" + ``` + +- 要满足同步需求 #8，首先参考[自增主键冲突处理](/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决冲突，保证在同步到下游时不会因为分表中有相同的主键值而使同步出现异常；然后需要配置 `ignore-checking-items` 来跳过自增主键冲突的检查： + + {{< copyable "" >}} + + ```yaml + ignore-checking-items: ["auto_increment_ID"] + ``` + +## 同步任务配置 + +同步任务的完整配置如下。详情请参阅 [Data Migration 任务配置文件](/reference/tools/data-migration/configure/task-configuration-file.md)。 + +{{< copyable "" >}} + +```yaml +name: "shard_merge" +task-mode: all +meta-schema: "dm_meta" +remove-meta: false +ignore-checking-items: ["auto_increment_ID"] + +target-database: + host: "192.168.0.1" + port: 4000 + user: "root" + password: "" + +mysql-instances: + - + source-id: "instance-1" + route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] + filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] + black-white-list: "log-bak-ignored" + mydumper-config-name: "global" + loader-config-name: "global" + syncer-config-name: "global" + + - + source-id: "instance-2" + route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] + filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] + black-white-list: "log-bak-ignored" + mydumper-config-name: "global" + loader-config-name: "global" + syncer-config-name: "global" + - + source-id: "instance-3" + route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] + filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] + black-white-list: "log-bak-ignored" + mydumper-config-name: "global" + loader-config-name: "global" + syncer-config-name: "global" + +# 所有实例共享的其他通用配置 + +routes: + user-route-rule: + schema-pattern: "user" + target-schema: "user" + store-route-rule: + schema-pattern: "store_*" + target-schema: "store" + sale-route-rule: + schema-pattern: "store_*" + table-pattern: "sale_*" + target-schema: "store" + target-table: "sale" + +filters: + user-filter-rule: + schema-pattern: "user" + events: ["truncate table", "drop table", "delete", "drop database"] + action: Ignore + sale-filter-rule: + schema-pattern: "store_*" + table-pattern: "sale_*" + events: ["truncate table", "drop table", "delete"] + action: Ignore + store-filter-rule: + schema-pattern: "store_*" + events: ["drop database"] + action: Ignore + +black-white-list: + log-bak-ignored: + ignore-tables: + - db-name: "user" + tbl-name: "log_bak" + +mydumpers: + global: + threads: 4 + chunk-filesize: 64 + skip-tz-utc: true + +loaders: + global: + pool-size: 16 + dir: "./dumped_data" + +syncers: + global: + worker-count: 16 + batch: 100 + max-retry: 100 +``` diff --git a/reference/tools/data-migration/usage-scenarios/simple-synchronization.md b/reference/tools/data-migration/usage-scenarios/simple-synchronization.md new file mode 100644 index 000000000000..a939703c8149 --- /dev/null +++ b/reference/tools/data-migration/usage-scenarios/simple-synchronization.md @@ -0,0 +1,255 @@ +--- +title: Data Migration 简单使用场景 +category: reference +--- + +# Data Migration 简单使用场景 + +本文介绍了 DM 工具的一个简单使用场景（非分库分表合并场景）：将三个上游 MySQL 实例的数据同步到一个下游 TiDB 集群中。 + +## 上游实例 + +假设上游结构为： + +- 实例 1 + + | Schema | Tables | + |:------|:------| + | user | information, log | + | store | store_bj, store_tj | + | log | messages | + +- 实例 2 + + | Schema | Tables | + |:------|:------| + | user | information, log | + | store | store_sh, store_sz | + | log | messages | + +- 实例 3 + + | Schema | Tables | + |:------|:------| + | user | information, log | + | store | store_gz, store_sz | + | log | messages | + +## 同步要求 + +1. 不合并 `user` 库。 + + 1. 将实例 1 中的 `user` 库同步到下游 TiDB 的 `user_north` 库中。 + + 2. 将实例 2 中的 `user` 库同步到下游 TiDB 的 `user_east` 库中。 + + 3. 将实例 3 中的 `user` 库同步到下游 TiDB 的 `user_south` 库中。 + + 4. 任何情况下都不删除 `log` 表的任何数据。 + +2. 将上游 `store` 库同步到下游 `store` 库中，且同步过程中不合并表。 + + 1. 实例 2 和实例 3 中都存在 `store_sz` 表，且这两个 `store_sz` 表分别被同步到下游的 `store_suzhou` 表和 `store_shenzhen` 表中。 + + 2. 任何情况下都不删除 `store` 库的任何数据。 + +3. `log` 库需要被过滤掉。 + +## 下游实例 + +假设下游结构为： + +| Schema | Tables | +|:------|:------| +| user_north | information, log | +| user_east | information, log | +| user_south | information, log | +| store | store_bj, store_tj, store_sh, store_suzhou, store_gz, store_shenzhen | + +## 同步方案 + +- 为了满足[同步要求](#同步要求)中第一点的前三条要求，需要配置以下 [table routing 规则](/reference/tools/data-migration/features/overview.md#table-routing)： + + {{< copyable "" >}} + + ```yaml + routes: + ... + instance-1-user-rule: + schema-pattern: "user" + target-schema: "user_north" + instance-2-user-rule: + schema-pattern: "user" + target-schema: "user_east" + instance-3-user-rule: + schema-pattern: "user" + target-schema: "user_south" + ``` + +- 为了满足[同步要求](#同步要求)中第二点的第一条要求，需要配置以下 [table routing 规则](/reference/tools/data-migration/features/overview.md#table-routing)： + + {{< copyable "" >}} + + ```yaml + routes: + ... + instance-2-store-rule: + schema-pattern: "store" + table-pattern: "store_sz" + target-schema: "store" + target-table: "store_suzhou" + instance-3-store-rule: + schema-pattern: "store" + table-pattern: "store_sz" + target-schema: "store" + target-table: "store_shenzhen" + ``` + +- 为了满足[同步要求](#同步要求)中第一点的第四条要求，需要配置以下 [binlog event filter 规则](/reference/tools/data-migration/features/overview.md#binlog-event-filter)： + + {{< copyable "" >}} + + ```yaml + filters: + ... + log-filter-rule: + schema-pattern: "user" + table-pattern: "log" + events: ["truncate table", "drop table", "delete"] + action: Ignore + user-filter-rule: + schema-pattern: "user" + events: ["drop database"] + action: Ignore + ``` + +- 为了满足[同步要求](#同步要求)中第二点的第二条要求，需要配置以下 [binlog event filter 规则](/reference/tools/data-migration/features/overview.md#binlog-event-filter)： + + {{< copyable "" >}} + + ```yaml + filters: + ... + store-filter-rule: + schema-pattern: "store" + events: ["drop database", "truncate table", "drop table", "delete"] + action: Ignore + ``` + + > **注意：** + > + > `store-filter-rule` 不同于 `log-filter-rule` 和 `user-filter-rule`。`store-filter-rule` 是针对整个 `store` 库的规则，而 `log-filter-rule` 和 `user-filter-rule` 是针对 `user` 库中 `log` 表的规则。 + +- 为了满足[同步要求](#同步要求)中的第三点要求，需要配置以下 [black & white table lists 规则](/reference/tools/data-migration/features/overview.md#black--white-table-lists)： + + {{< copyable "" >}} + + ```yaml + black-white-list: + log-ignored: + ignore-dbs: ["log"] + ``` + +## 同步任务配置 + +以下是完整的同步任务配置，详见[配置介绍](/reference/tools/data-migration/configure/task-configuration-file.md)。 + +{{< copyable "" >}} + +```yaml +name: "one-tidb-slave" +task-mode: all +meta-schema: "dm_meta" +remove-meta: false + +target-database: + host: "192.168.0.1" + port: 4000 + user: "root" + password: "" + +mysql-instances: + - + source-id: "instance-1" + route-rules: ["instance-1-user-rule"] + filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] + black-white-list: "log-ignored" + mydumper-config-name: "global" + loader-config-name: "global" + syncer-config-name: "global" + - + source-id: "instance-2" + route-rules: ["instance-2-user-rule", instance-2-store-rule] + filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] + black-white-list: "log-ignored" + mydumper-config-name: "global" + loader-config-name: "global" + syncer-config-name: "global" + - + source-id: "instance-3" + route-rules: ["instance-3-user-rule", instance-3-store-rule] + filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] + black-white-list: "log-ignored" + mydumper-config-name: "global" + loader-config-name: "global" + syncer-config-name: "global" + +# 所有实例的共有配置 + +routes: + instance-1-user-rule: + schema-pattern: "user" + target-schema: "user_north" + instance-2-user-rule: + schema-pattern: "user" + target-schema: "user_east" + instance-3-user-rule: + schema-pattern: "user" + target-schema: "user_south" + instance-2-store-rule: + schema-pattern: "store" + table-pattern: "store_sz" + target-schema: "store" + target-table: "store_suzhou" + instance-3-store-rule: + schema-pattern: "store" + table-pattern: "store_sz" + target-schema: "store" + target-table: "store_shenzhen" + +filters: + log-filter-rule: + schema-pattern: "user" + table-pattern: "log" + events: ["truncate table", "drop table", "delete"] + action: Ignore + user-filter-rule: + schema-pattern: "user" + events: ["drop database"] + action: Ignore + store-filter-rule: + schema-pattern: "store" + events: ["drop database", "truncate table", "drop table", "delete"] + action: Ignore + +black-white-list: + log-ignored: + ignore-dbs: ["log"] + +mydumpers: + global: + threads: 4 + chunk-filesize: 64 + skip-tz-utc: true + +loaders: + global: + pool-size: 16 + dir: "./dumped_data" + +syncers: + global: + worker-count: 16 + batch: 100 + max-retry: 100 +``` diff --git a/reference/tools/download.md b/reference/tools/download.md new file mode 100644 index 000000000000..aa6c5993fab7 --- /dev/null +++ b/reference/tools/download.md @@ -0,0 +1,75 @@ +--- +title: TiDB 工具下载 +category: reference +--- + +# TiDB 工具下载 + +本页面汇总了 TiDB 周边工具官方维护版本的下载链接。 + +## TiDB Binlog + +如需下载最新版本的 [TiDB Binlog](/reference/tidb-binlog/overview.md)，直接下载 TiDB 安装包即可，因为 TiDB Binlog 包含在 TiDB 安装包中。 + +以下表格中也提供了 Kafka 版本的 TiDB Binlog 下载链接。 + +| 安装包 | 操作系统 | 架构 | SHA256 校验和 | +|:---|:---|:---|:---| +| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (TiDB Binlog) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | +| `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz`（Kafka 版本的 TiDB Binlog）| Linux | amd64 | `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256` | + +> **注意：** +> +> 下载链接中的 `{version}` 为 TiDB 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 + +## TiDB Lightning + +使用下表中的链接下载 [TiDB Lightning](/reference/tools/tidb-lightning/overview.md)： + +| 安装包 | 操作系统 | 架构 | SHA256 校验和 | +|:---|:---|:---|:---| +| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | + +> **注意：** +> +> 下载链接中的 `{version}` 为 TiDB Lightning 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 + +## 快速备份和恢复（BR） + +使用下表中的链接下载 [快速备份和恢复（BR）](/reference/tools/br/br.md)： + +| 安装包 | 操作系统 | 架构 | SHA256 校验和 | +|:---|:---|:---|:---| +| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | + +> **注意：** +> +> 下载链接中的 `{version}` 为 BR 的版本号。例如，`v3.1.0-beta` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.1.0-beta-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 + +## TiDB DM (Data Migration) + +使用下表中的链接下载 [DM](/reference/tools/data-migration/overview.md)： + +| 安装包 | 操作系统 | 架构 | SHA256 校验和 | +|:---|:---|:---|:---| +| `https://download.pingcap.org/dm-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/dm-{version}-linux-amd64.sha256` | + +> **注意：** +> +> 下载链接中的 `{version}` 为 DM 的版本号。例如，`v1.0.1` 版本的下载链接为 `https://download.pingcap.org/dm-v1.0.1-linux-amd64.tar.gz`。可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 + +## Syncer，Loader 和 Mydumper + +如需下载最新版本的 [Syncer](/reference/tools/syncer.md)，[Loader](/reference/tools/loader.md) 或 [Mydumper](/reference/tools/mydumper.md)，直接下载 tidb-enterprise-tools 安装包即可，因为这些工具均包含在此安装包中。 + +| 安装包 | 操作系统 | 架构 | SHA256 校验和 | +|:---|:---|:---|:---| +| [tidb-enterprise-tools-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) | Linux | amd64 | [tidb-enterprise-tools-latest-linux-amd64.sha256](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256) | + +tidb-enterprise-tools 安装包包含以下工具： + +- Syncer +- Loader +- Mydumper +- ddl_checker +- [sync-diff-inspector](/reference/tools/sync-diff-inspector/overview.md) diff --git a/reference/tools/error-case-handling/lightning-misuse-handling.md b/reference/tools/error-case-handling/lightning-misuse-handling.md new file mode 100644 index 000000000000..d9dfd46345d4 --- /dev/null +++ b/reference/tools/error-case-handling/lightning-misuse-handling.md @@ -0,0 +1,35 @@ +--- +title: TiDB Lightning 常见的错误用法 +category: reference +--- + +# TiDB Lightning 常见的错误用法 + +本文介绍了 [TiDB Lightning](/reference/tools/tidb-lightning/overview.md) 使用过程中常见的出错场景以及相应的处理方式。 + +## 报错：`checksum mismatched remote vs local` + +在数据导入过程中遇到下面的报错 + +```log +Error: checksum mismatched remote vs local => (checksum: 3828723015727756136 vs 7895534721177712659) (total_kvs: 1221416844 vs 1501500000) (total_bytes:237660308510 vs 292158203078) +``` + +### 原因 + +* 先前使用过 TiDB Lightning 进行数据导入，但是对应的 [checkpoint](/reference/tools/tidb-lightning/checkpoints.md) 的数据没有被清理，存在残留的数据。可以通过查看 TiDB Lightning 第一次启动 log 来确认： + * `[checkpoint] driver = file`，如果对应 TiDB Lightning 导入时间点的 log 存在 `open checkpoint file failed, going to create a new one`，那么 `checkpoint` 已经被正确清理，否则存在残留数据可能导致导入数据缺失； + * `[checkpoint] driver = mysql`，可以通过使用 TiDB API `curl http://{TiDBIP}:10080/schema/{checkpoint.schema}/{checkpoint.table}` 来查询对应 `checkpoint table` 的创建时间，从而判断是否正确清理了 `checkpoint`。 + +* TiDB Lightning 导入的数据源存在冲突的数据 + * 不同行的数据具有相同的主键或唯一键 + +### 解决方案 + +* 删除出现 `checksum mismatch` 错误的表的数据 + + ``` + tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all + ``` + +* 需要寻找办法检测数据源是否存在冲突数据，TiDB Lightning 一般需要处理大量的数据，所以目前还未提供有效的冲突检测和处理措施。 diff --git a/reference/tools/error-case-handling/load-misuse-handling.md b/reference/tools/error-case-handling/load-misuse-handling.md new file mode 100644 index 000000000000..6655120d92b4 --- /dev/null +++ b/reference/tools/error-case-handling/load-misuse-handling.md @@ -0,0 +1,41 @@ +--- +title: 全量数据导入过程常见报错处理 +category: reference +--- + +# 全量数据导入过程常见报错处理 + +本文介绍了使用 [Loader](/reference/tools/loader.md) 或者 [TiDB Data Migration](/reference/tools/data-migration/overview.md)（以下简称为 DM）进行全量数据导入过程中常见的因为使用造成的出错场景，以及这些错误发生的原因和处理方式。 + +## 报错：```Try adjusting the `max_allowed_packet` variable``` + +在全量数据导入过程中遇到下面的报错 + +``` +packet for query is too large. Try adjusting the 'max_allowed_packet' variable +``` + +### 原因 + +* MySQL client 和 MySQL/TiDB Server 都有 `max_allowed_packet` 配额的限制，如果在使用过程中违反其中任何一个 `max_allowed_packet` 配额，客户端程序就会收到对应的报错。目前最新版本的 Syncer、Loader、DM 和 TiDB Server 的默认 `max_allowed_packet` 配额都为 `64M`。 + * 请使用最新版本，或者最新稳定版本的工具。[下载页面](/reference/tools/download.md)。 +* Loader 或 DM 的全量数据导入处理模块不支持对 dump sqls 文件进行切分，原因是 Mydumper 采用了最简单的编码实现，正如 Mydumper 代码注释 `/* Poor man's data dump code */` 所言。如果在 Loader 或 DM 实现文件切分，那么需要在 `TiDB parser` 基础上实现一个完备的解析器才能正确的处理数据切分，但是随之会带来以下的问题： + * 工作量大 + * 复杂度高，不容易保证正确性 + * 性能的极大降低 + +### 解决方案 + +* 依据上面的原因，在代码层面不能简单的解决这个困扰，我们推荐的方式是：利用 Mydumper 提供的控制 `Insert Statement` 大小的功能 `-s, --statement-size`: `Attempted size of INSERT statement in bytes, default 1000000`。 + + 依据默认的 `--statement-size` 设置，Mydumper 默认生成的 `Insert Statement` 大小会尽量接近在 `1M` 左右，使用默认值就可以确保绝大部分情况不会出现该问题。 + + 有时候在 dump 过程中会出现下面的 `WARN` log，但是这个报错不影响 dump 的过程，只是表达了 dump 的表可能是宽表。 + + ``` + Row bigger than statement_size for xxx + ``` + +* 如果宽表的单行超过了 `64M`，那么需要修改以下两个配置，并且使之生效。 + * 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728` （`134217728 = 128M`） + * 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M`，然后重启进程或者任务 diff --git a/reference/tools/loader.md b/reference/tools/loader.md new file mode 100644 index 000000000000..b2466b06a11f --- /dev/null +++ b/reference/tools/loader.md @@ -0,0 +1,154 @@ +--- +title: Loader 使用文档 +category: reference +--- + +# Loader 使用文档 + +## Loader 简介 + +Loader 是由 PingCAP 开发的数据导入工具，用于向 TiDB 中导入数据。 + +Loader 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/reference/tools/download.md)。 + +## 为什么我们要做这个工具 + +当数据量比较大的时候，如果用 mysqldump 这样的工具迁移数据会比较慢。我们尝试了 [Mydumper/myloader 套件](https://github.com/maxbube/mydumper)，能够多线程导出和导入数据。在使用过程中，Mydumper 问题不大，但是 myloader 由于缺乏出错重试、断点续传这样的功能，使用起来很不方便。所以我们开发了 loader，能够读取 Mydumper 的输出数据文件，通过 MySQL protocol 向 TiDB/MySQL 中导入数据。 + +## Loader 有哪些优点 + +* 多线程导入 +* 支持表级别的并发导入，分散写入热点 +* 支持对单个大表并发导入，分散写入热点 +* 支持 Mydumper 数据格式 +* 出错重试 +* 断点续导 +* 通过 system variable 优化 TiDB 导入数据速度 + +## 使用方法 + +### 注意事项 + +请勿使用 loader 导入 MySQL 实例中 `mysql` 系统数据库到下游 TiDB。 + +如果 Mydumper 使用 -m 参数，会导出不带表结构的数据，这时 loader 无法导入数据。 + +如果使用默认的 `checkpoint-schema` 参数，在导完一个 database 数据库后，请 `drop database tidb_loader` 后再开始导入下一个 database。 + +推荐数据库开始导入的时候，明确指定 `checkpoint-schema = "tidb_loader"` 参数。 + +### 参数说明 + +``` + -L string + log 级别设置，可以设置为 debug, info, warn, error, fatal (默认为 "info") + -P int + TiDB/MySQL 的端口 (默认为 4000) + -V + 打印 loader 版本 + -c string + 指定配置文件启动 loader + -checkpoint-schema string + checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后，会通过这个库获取上次运行的进度 (默认为 "tidb_loader") + -d string + 需要导入的数据存放路径 (default "./") + -h string + TiDB 服务 host IP (default "127.0.0.1") + -p string + TiDB 账户密码 + -status-addr string + Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 + -t int + 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 + -u string + TiDB 的用户名 (默认为 "root") +``` + +### 配置文件 + +除了使用命令行参数外，还可以使用配置文件来配置，配置文件的格式如下： + +```toml +# 日志输出等级；可以设置为 debug, info, warn, error, fatal (默认为 "info") +log-level = "info" + +# 指定 loader 日志目录 +log-file = "loader.log" + +# 需要导入的数据存放路径 (default "./") +dir = "./" + +## Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 +status-addr = ":8272" + +# checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后， +# 会通过这个库获取上次运行的进度 (默认为 "tidb_loader") +checkpoint-schema = "tidb_loader" + +# 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 +pool-size = 16 + +# 目标数据库信息 +[db] +host = "127.0.0.1" +user = "root" +password = "" +port = 4000 + +# 导入数据时数据库连接所使用的 session 级别的 `sql_mode`。如果 `sql-mode` 的值没有提供或者设置为 "@DownstreamDefault"，会使用下游 global 级别的 `sql_mode`。 +# sql-mode = "" +# `max-allowed-packet` 设置数据库连接允许的最大数据包大小，对应于系统参数中的 `max_allowed_packet`。 如果设置为 0，会使用下游数据库 global 级别的 `max_allowed_packet`。 +max-allowed-packet = 67108864 + +# sharding 同步规则，采用 wildcharacter +# 1\. 星号字符 (*) 可以匹配零个或者多个字符, +# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; +# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 +# 2\. 问号字符 (?) 匹配任一一个字符 + +# [[route-rules]] +# pattern-schema = "shard_db_*" +# pattern-table = "shard_table_*" +# target-schema = "shard_db" +# target-table = "shard_table" +``` + +### 使用示例 + +通过命令行参数： + +{{< copyable "shell-regular" >}} + +```bash +./bin/loader -d ./test -h 127.0.0.1 -u root -P 4000 +``` + +或者使用配置文件 "config.toml": + +{{< copyable "shell-regular" >}} + +```bash +./bin/loader -c=config.toml +``` + +## FAQ + +### 合库合表场景案例说明 + +根据配置文件的 route-rules 可以支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则： + ++ 是否可以利用 route-rules 的语义规则表示 ++ 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 + +Loader 需要配置文件中开启 route-rules 参数以提供合库合表功能 + ++ 如果使用该功能，必须填写 `pattern-schema` 与 `target-schema` ++ 如果 `pattern-table` 与 `target-table` 为空，将不进行表名称合并或转换 + +```toml +[[route-rules]] +pattern-schema = "example_db" +pattern-table = "table_*" +target-schema = "example_db" +target-table = "table" +``` diff --git a/reference/tools/mydumper.md b/reference/tools/mydumper.md new file mode 100644 index 000000000000..de5ec89cfb95 --- /dev/null +++ b/reference/tools/mydumper.md @@ -0,0 +1,190 @@ +--- +title: Mydumper 使用文档 +summary: 使用 Mydumper 从 TiDB 导出数据。 +category: reference +--- + +# Mydumper 使用文档 + +## Mydumper 简介 + +[Mydumper](https://github.com/pingcap/mydumper) 是一个 fork 项目，针对 TiDB 的特性进行了优化，推荐使用此工具对 TiDB 进行逻辑备份。 + +Mydumper 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/reference/tools/download.md)。 + +### 相比于普通的 Mydumper，此工具有哪些改进之处？ + ++ 对于 TiDB 可以设置 [tidb_snapshot](/how-to/get-started/read-historical-data.md#操作流程) 的值指定备份数据的时间点，从而保证备份的一致性，而不是通过 `FLUSH TABLES WITH READ LOCK` 来保证备份一致性。 + ++ 使用 TiDB 的隐藏列 `_tidb_rowid` 优化了单表内数据的并发导出性能。 + +## 基本用法 + +### 新添参数 + +- `-z` 或 `--tidb-snapshot`：设置 `tidb_snapshot` 用于备份。默认值为当前 TSO（`SHOW MASTER STATUS` 输出的 `Position` 字段）。此参数可设为 TSO 或有效的 `datetime` 时间，例如：`-z "2016-10-08 16:45:26"`。 + +### 需要的权限 + +- SELECT +- RELOAD +- LOCK TABLES +- REPLICATION CLIENT + +### 使用举例 + +执行如下命令从 TiDB 备份数据，需要根据实际情况添加命令行参数： + +{{< copyable "shell-regular" >}} + +```bash +./bin/mydumper -h 127.0.0.1 -u root -P 4000 +``` + +## 表内并发 Dump + +### 原理 + +Mydumper 首先计算 `min(_tidb_rowid)` 和 `max(_tidb_rowid)`，然后按照 `-r` 设定的值对表划分 chunks，将 chunks 分配到不同线程并发导出。 + +### 并发 Dump 相关参数 + +- `-t` 或 `--threads`：并发线程数，默认值为 `4`。 +- `-r` 或 `--rows`：每个 chunks 包含的最大行数。设置该值后，Mydumper 将会忽略 `--chunk-filesize` 值。 + +### 示例 + +以下是一条完整的 Mydumper 命令： + +{{< copyable "shell-regular" >}} + +```bash +./bin/mydumper -h 127.0.0.1 -u root -P 4000 -r 10000 -t 4 +``` + +### 支持 `_tidb_rowid` 索引的 TiDB 版本 + +由于表内并发使用 TiDB 的隐藏列 `_tidb_rowid`，数据库需要支持 `_tidb_rowid` 索引才能发挥并发导出的优势。 + +以下 TiDB 版本支持 `_tidb_rowid` 索引： + +- v2.1.3 及以上 +- v3.0 及以上，包括 v3.1 及未来版本 + +### 性能评估 + +在 Dump 操作前需要进行性能评估。由于并发 Scan 操作对 TiDB、TiKV 集群都会产生一定压力，所以需要评估与测试 Dump 操作对数据库集群和业务的影响。 + +## FAQ + +### 如何判断使用的 Mydumper 是否为 PingCAP 优化的版本？ + +执行如下命令： + +{{< copyable "shell-regular" >}} + +```bash +./bin/mydumper -V +``` + +如果输出结果中包含 `githash`（如下列示例输出中的 `d3e6fec8b069daee772d0dbaa47579f67a5947e7`），则使用的 Mydumper 为 PingCAP 优化的版本。 + +``` +mydumper 0.9.5 (d3e6fec8b069daee772d0dbaa47579f67a5947e7), built against MySQL 5.7.24 +``` + +### 使用 Loader 恢复 Mydumper 备份出来的数据时报错 "invalid mydumper files for there are no `-schema-create.sql` files found"，应该如何解决？ + +检查使用 Mydumper 备份数据时是否使用了 `-T` 或者 `--tables-list` 配置，如果使用了这些配置，Mydumper 就不会生成包含建库 SQL 的文件。 + +**解决方法**：在 Mydumper 备份数据目录下创建文件 `{schema-name}-schema-create.sql`，在文件中写入 "CREATE DATABASE `{schema-name}`"，再运行 Loader 即可。 + +### 为什么使用 Mydumper 导出来的 TIMESTAMP 类型的数据和数据库中的数据不一致？ + +检查一下运行 Mydumper 的服务器的时区与数据库的时区是否一致，Mydumper 会根据运行所在服务器的时区对 TIMESTAMP 类型的数据进行转化，可以给 Mydumper 加上 `--skip-tz-utc` 参数禁止这种转化。 + +### 如何配置 Mydumper 的参数 `-F, --chunk-filesize`？ + +Mydumper 在备份时会根据这个参数的值把每个表的数据划分成多个 chunk，每个 chunk 保存到一个文件中，大小约为 `chunk-filesize`。根据这个参数把数据切分到多个文件中，这样就可以利用 Loader/TiDB Lightning 的并行处理逻辑提高导入速度。如果后续使用 Loader 对备份文件进行恢复，建议把该参数的值设置为 `64`（单位 MB）；如果使用 TiDB Lightning 恢复，则建议设置为 `256`（单位 MB）。 + +### 如何配置 Mydumper 的参数 `-s --statement-size`？ + +Mydumper 使用该参数控制 `Insert Statement` 的大小，默认值为 `10000000`（约 1 MB）。使用该参数来尽量避免在恢复数据时报以下错误： + +```log +packet for query is too large. Try adjusting the 'max_allowed_packet' variable +``` + +默认值在绝大部分情况下都可以满足需求，但是**如果表为宽表，单行数据的大小可能超过 statement-size 的限制，Mydumper 会报如下的 Warning**： + +```log +Row bigger than statement_size for xxx +``` + +此时恢复数据时仍然会报 `packet for query is too large` 的错误日志，这个时候需要修改以下两个配置（以设置为 `128M` 为例）： + +* 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728`（`134217728` = `128M`）。 +* 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M` 的语句，然后重启进程或者任务。 + +### 如何设置 Mydumper 的参数 `-l, --long-query-guard`？ + +把该参数设置为预估备份需要消耗的时间，如果 Mydumper 运行时间超过该参数的值，就会报错退出。推荐初次备份设置为 `7200`（单位：秒），之后可根据具体备份时间进行调整。 + +### 如何设置 Mydumper 的参数 `--tidb-force-priority`？ + +仅当备份 TiDB 的数据时才可以设置该参数，值可以为 `LOW_PRIORITY`，`DELAYED` 或者 `HIGH_PRIORITY`。如果不希望数据备份对线上业务造成影响，推荐将该参数设置为 `LOW_PRIORITY`；如果备份的优先级更高，则可以设置为 `HIGH_PRIORITY`。 + +### Mydumper 备份 TiDB 数据报错 "GC life time is shorter than transaction duration" 应该怎么解决？ + +Mydumper 备份 TiDB 数据时为了保证数据的一致性使用了 TiDB 的 snapshot 特性，如果备份过程中 snapshot 对应的历史数据被 TiDB GC 处理了，则会报该错误。解决步骤如下： + +1. 在备份前，使用 MySQL 客户端查询 TiDB 集群的 `tikv_gc_life_time` 的值，并将其调整为一个合适的值： + + {{< copyable "sql" >}} + + ```sql + SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + + ``` + +-----------------------+------------------------------------------------------------------------------------------------+ + | VARIABLE_NAME | VARIABLE_VALUE | + +-----------------------+------------------------------------------------------------------------------------------------+ + | tikv_gc_life_time | 10m0s | + +-----------------------+------------------------------------------------------------------------------------------------+ + 1 rows in set (0.02 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + +2. 备份完成后，将 `tikv_gc_life_time` 调整为原来的值： + + {{< copyable "sql" >}} + + ```sql + update mysql.tidb set VARIABLE_VALUE = '10m0s' where VARIABLE_NAME = 'tikv_gc_life_time'; + ``` + +### Mydumper 的参数 `--tidb-rowid` 是否需要配置？ + +如果设置该参数为 true，则导出的数据中会包含 TiDB 的隐藏列的数据。将数据恢复到 TiDB 的时候使用隐藏列会有数据不一致的风险，目前不推荐使用该参数。 + +### Mydumper 报错 "Segmentation fault" 怎么解决？ + +该 bug 已修复。如果仍然报错，可尝试升级到最新版本。 + +### Mydumper 报错 "Error dumping table ({schema}.{table}) data: line ...... (total length ...)" 怎么解决？ + +Mydumper 解析 SQL 时报错，可尝试使用最新版本。如果仍然报错，可以提 issue 到 [mydumper/issues](https://github.com/pingcap/mydumper/issues)。 + +### Mydumper 报错 "Failed to set tidb_snapshot: parsing time \"20190901-10:15:00 +0800\" as \"20190901-10:15:00 +0700 MST\": cannot parse \"\" as \"MST\"" 如何解决？ + +检查 TiDB 的版本是否低于 v2.1.11。如果是的话，需要升级 TiDB 到 v2.1.11 或以上版本。 + +### 未来是否计划让 PingCAP 对 Mydumper 的改动合并到上游？ + +是的，PingCAP 团队计划将对 Mydumper 的改动合并到上游。参见 [PR #155](https://github.com/maxbube/mydumper/pull/155)。 diff --git a/dev/reference/tools/pd-control.md b/reference/tools/pd-control.md similarity index 100% rename from dev/reference/tools/pd-control.md rename to reference/tools/pd-control.md diff --git a/dev/reference/tools/pd-recover.md b/reference/tools/pd-recover.md similarity index 100% rename from dev/reference/tools/pd-recover.md rename to reference/tools/pd-recover.md diff --git a/reference/tools/sync-diff-inspector/overview.md b/reference/tools/sync-diff-inspector/overview.md new file mode 100644 index 000000000000..9247fa9a4f6b --- /dev/null +++ b/reference/tools/sync-diff-inspector/overview.md @@ -0,0 +1,220 @@ +--- +title: sync-diff-inspector 用户文档 +category: tools +--- + +# sync-diff-inspector 用户文档 + +sync-diff-inspector 是一个用于校验 MySQL／TiDB 中两份数据是否一致的工具。该工具提供了修复数据的功能（适用于修复少量不一致的数据）。 + +主要功能： + +* 对比表结构和数据 +* 如果数据不一致，则生成用于修复数据的 SQL 语句 +* 支持[不同库名或表名的数据校验](/reference/tools/sync-diff-inspector/route-diff.md) +* 支持[分库分表场景下的数据校验](/reference/tools/sync-diff-inspector/shard-diff.md) +* 支持 [TiDB 主从集群的数据校验](/reference/tools/sync-diff-inspector/tidb-diff.md) + +GitHub 地址：[sync-diff-inspector](https://github.com/pingcap/tidb-tools/tree/master/sync_diff_inspector) + +下载地址：[tidb-enterprise-tools-latest-linux-amd64](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) + +## sync-diff-inspector 的使用 + +### 使用限制 + +* 目前不支持在线校验，需要保证上下游校验的表中没有数据写入，或者保证某个范围内的数据不再变更，通过配置 `range` 来校验这个范围内的数据。 + +* 不支持 JSON、BIT、BINARY、BLOB 等类型的数据，在校验时需要设置 `ignore-columns` 忽略检查这些类型的数据。 + +* FLOAT、DOUBLE 等浮点数类型在 TiDB 和 MySQL 中的实现方式不同，在计算 checksum 时可能存在差异，如果发现因为这些类型的数据导致的数据校验不一致，需要设置 `ignore-columns` 忽略这些列的检查。 + +### 数据库权限 + +sync-diff-inspector 需要获取表结构信息、查询数据、建 checkpoint 库保存断点信息，需要的数据库权限如下： + +- 上游数据库 + + - SELECT（查数据进行对比） + + - SHOW_DATABASES (查看库名) + + - RELOAD (查看表结构) + +- 下游数据库 + + - SELECT （查数据进行对比） + + - CREATE （创建 checkpoint 库和表） + + - DELETE （删除 checkpoint 表中的信息） + + - INSERT （写入 checkpoint 表） + + - UPDATE（修改 checkpoint 表） + + - SHOW_DATABASES (查看库名) + + - RELOAD (查看表结构) + +### 配置文件说明 + +sync-diff-inspector 的配置总共分为三个部分： + +- Global config: 通用配置，包括日志级别、划分 chunk 的大小、校验的线程数量等。 +- Tables config: 配置校验哪些表，如果有的表在上下游有一定的映射关系或者有一些特殊要求，则需要对指定的表进行配置。 +- Databases config: 配置上下游数据库实例。 + +下面是一个完整配置文件的说明： + +```toml +# Diff Configuration. + +######################### Global config ######################### + +# 日志级别，可以设置为 info、debug +log-level = "info" + +# sync-diff-inspector 根据主键／唯一键／索引将数据划分为多个 chunk， +# 对每一个 chunk 的数据进行对比。使用 chunk-size 设置 chunk 的大小 +chunk-size = 1000 + +# 检查数据的线程数量 +check-thread-count = 4 + +# 抽样检查的比例，如果设置为 100 则检查全部数据 +sample-percent = 100 + +# 通过计算 chunk 的 checksum 来对比数据，如果不开启则逐行对比数据 +use-checksum = true + +# 如果设置为 true 则只会通过计算 checksum 来校验数据，如果上下游的 checksum 不一致也不会查出数据再进行校验 +only-use-checksum = false + +# 是否使用上次校验的 checkpoint，如果开启，则只校验上次未校验以及校验失败的 chunk +use-checkpoint = true + +# 不对比数据 +ignore-data-check = false + +# 不对比表结构 +ignore-struct-check = false + +# 保存用于修复数据的 sql 的文件名称 +fix-sql-file = "fix.sql" + +######################### Tables config ######################### + +# 如果需要对比大量的不同库名或者表名的表的数据，可以通过 table-rule 来设置映射关系。可以只配置 schema 或者 table 的映射关系，也可以都配置 +#[[table-rules]] + # schema-pattern 和 table-pattern 支持通配符 *? + #schema-pattern = "test_*" + #table-pattern = "t_*" + #target-schema = "test" + #target-table = "t" + +# 配置需要对比的*目标数据库*中的表 +[[check-tables]] + # 目标库中数据库的名称 + schema = "test" + + # 需要检查的表 + tables = ["test1", "test2", "test3"] + + # 支持使用正则表达式配置检查的表，需要以‘~’开始， + # 下面的配置会检查所有表名以‘test’为前缀的表 + # tables = ["~^test.*"] + # 下面的配置会检查配置库中所有的表 + # tables = ["~^"] + +# 对部分表进行特殊的配置，配置的表必须包含在 check-tables 中 +[[table-config]] + # 目标库中数据库的名称 + schema = "test" + + # 表名 + table = "test3" + + # 指定用于划分 chunk 的列，如果不配置该项，sync-diff-inspector 会选取一个合适的列（主键／唯一键／索引） + index-field = "id" + + # 指定检查的数据的范围，需要符合 sql 中 where 条件的语法 + range = "age > 10 AND age < 20" + + # 如果是对比多个分表与总表的数据，则设置为 true + is-sharding = false + + # 在某些情况下字符类型的数据的排序会不一致，通过指定 collation 来保证排序的一致， + # 需要与数据库中 charset 的设置相对应 + # collation = "latin1_bin" + + # 忽略某些列的检查，例如 sync-diff-inspector 目前还不支持的一些类型（json，bit，blob 等）， + # 或者是浮点类型数据在 TiDB 和 MySQL 中的表现可能存在差异，可以使用 ignore-columns 忽略检查这些列 + # ignore-columns = ["name"] + +# 下面是一个对比不同库名和表名的两个表的配置示例 +[[table-config]] + # 目标库名 + schema = "test" + + # 目标表名 + table = "test2" + + # 非分库分表场景，设置为 false + is-sharding = false + + # 源数据的配置 + [[table-config.source-tables]] + # 源库的实例 id + instance-id = "source-1" + # 源数据库的名称 + schema = "test" + # 源表的名称 + table = "test1" + +######################### Databases config ######################### + +# 源数据库实例的配置 +[[source-db]] + host = "127.0.0.1" + port = 3306 + user = "root" + password = "123456" + # 源数据库实例的 id，唯一标识一个数据库实例 + instance-id = "source-1" + # 使用 TiDB 的 snapshot 功能，如果开启的话会使用历史数据进行对比 + # snapshot = "2016-10-08 16:45:26" + # 设置数据库的 sql-mode，用于解析表结构 + # sql-mode = "" + +# 目标数据库实例的配置 +[target-db] + host = "127.0.0.1" + port = 4000 + user = "root" + password = "123456" + # 使用 TiDB 的 snapshot 功能，如果开启的话会使用历史数据进行对比 + # snapshot = "2016-10-08 16:45:26" + # 设置数据库的 sql-mode，用于解析表结构 + # sql-mode = "" +``` + +### 运行 sync-diff-inspector + +执行如下命令： + +{{< copyable "shell-regular" >}} + +```bash +./bin/sync_diff_inspector --config=./config.toml +``` + +该命令最终会在日志中输出一个检查报告，说明每个表的检查情况。如果数据存在不一致的情况，sync-diff-inspector 会生成 SQL 修复不一致的数据，并将这些 SQL 语句保存到 `fix.sql` 文件中。 + +### 注意事项 + +* sync-diff-inspector 在校验数据时会消耗一定的服务器资源，需要避免在业务高峰期间校验。 +* TiDB 使用的 collation 为 `utf8_bin`。如果对 MySQL 和 TiDB 的数据进行对比，需要注意 MySQL 中表的 collation 设置。如果表的主键／唯一键为 varchar 类型，且 MySQL 中 collation 设置与 TiDB 不同，可能会因为排序问题导致最终校验结果不正确，需要在 sync-diff-inspector 的配置文件中增加 collation 设置。 +* sync-diff-inspector 会优先使用 TiDB 的统计信息来划分 chunk，需要尽量保证统计信息精确，可以在**业务空闲期**手动执行 `analyze table {table_name}`。 +* table-rule 的规则需要特殊注意，例如设置了 `schema-pattern="test1"`，`target-schema="test2"`，会对比 source 中的 `test1` 库和 target 中的 `test2` 库；如果 source 中有 `test2` 库，该库也会和 target 中的 `test2` 库进行对比。 +* 生成的 `fix.sql` 仅作为修复数据的参考，需要确认后再执行这些 SQL 修复数据。 diff --git a/dev/reference/tools/sync-diff-inspector/route-diff.md b/reference/tools/sync-diff-inspector/route-diff.md similarity index 100% rename from dev/reference/tools/sync-diff-inspector/route-diff.md rename to reference/tools/sync-diff-inspector/route-diff.md diff --git a/dev/reference/tools/sync-diff-inspector/shard-diff.md b/reference/tools/sync-diff-inspector/shard-diff.md similarity index 100% rename from dev/reference/tools/sync-diff-inspector/shard-diff.md rename to reference/tools/sync-diff-inspector/shard-diff.md diff --git a/dev/reference/tools/sync-diff-inspector/tidb-diff.md b/reference/tools/sync-diff-inspector/tidb-diff.md similarity index 100% rename from dev/reference/tools/sync-diff-inspector/tidb-diff.md rename to reference/tools/sync-diff-inspector/tidb-diff.md diff --git a/reference/tools/syncer.md b/reference/tools/syncer.md new file mode 100644 index 000000000000..f15e71b12820 --- /dev/null +++ b/reference/tools/syncer.md @@ -0,0 +1,604 @@ +--- +title: Syncer 使用文档 +category: reference +--- + +# Syncer 使用文档 + +## Syncer 简介 + +Syncer 是一个数据导入工具，能方便地将 MySQL 的数据增量导入到 TiDB。 + +Syncer 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/reference/tools/download.md)。 + +## Syncer 架构 + +![Syncer 架构](/media/syncer-architecture.png) + +## Syncer 部署位置 + +Syncer 可以部署在任一台可以连通对应的 MySQL 和 TiDB 集群的机器上，推荐部署在 TiDB 集群。 + +## Syncer 增量导入数据示例 + +使用前请详细阅读 [Syncer 同步前预检查](#syncer-同步前检查)。 + +### 设置同步开始的 position + +设置 Syncer 的 meta 文件, 这里假设 meta 文件是 `syncer.meta`: + +{{< copyable "shell-regular" >}} + +```bash +cat syncer.meta +``` + +``` +binlog-name = "mysql-bin.000003" +binlog-pos = 930143241 +binlog-gtid = "2bfabd22-fff7-11e6-97f7-f02fa73bcb01:1-23,61ccbb5d-c82d-11e6-ac2e-487b6bd31bf7:1-4" +``` + +> **注意：** +> +> - `syncer.meta` 只需要第一次使用的时候配置，后续 Syncer 同步新的 binlog 之后会自动将其更新到最新的 position。 +> - 如果使用 binlog position 同步则只需要配置 `binlog-name` 和 `binlog-pos`；如果使用 `binlog-gtid` 同步则需要设置 `binlog-gtid`，且启动 Syncer 时带有 `--enable-gtid`。 + +### 启动 Syncer + +Syncer 的命令行参数说明： + +``` +Usage of Syncer: + -L string + 日志等级: debug, info, warn, error, fatal (默认为 "info") + -V + 输出 Syncer 版本；默认 false + -auto-fix-gtid + 当 mysql master/slave 切换时，自动修复 gtid 信息；默认 false + -b int + batch 事务大小 (默认 100) + -c int + Syncer 处理 batch 线程数 (默认 16) + -config string + 指定相应配置文件启动 Sycner 服务；如 `--config config.toml` + -enable-ansi-quotes + 使用 ANSI_QUOTES sql_mode 来解析 SQL 语句 + -enable-gtid + 使用 gtid 模式启动 Syncer；默认 false，开启前需要上游 MySQL 开启 GTID 功能 + -flavor string + 上游数据库实例类型，目前支持 "mysql" 和 "mariadb" + -log-file string + 指定日志文件目录；如 `--log-file ./syncer.log` + -log-rotate string + 指定日志切割周期, hour/day (默认 "day") + -max-retry int + SQL 请求由于网络异常等原因出错时的最大重试次数（默认值为 100） + -meta string + 指定 Syncer 上游 meta 信息文件 (默认与配置文件相同目录下 "syncer.meta") + -persistent-dir string + 指定同步过程中历史 schema 结构的保存文件地址，如果设置为空，则不保存历史 schema 结构；如果不为空，则根据 binlog 里面包含的数据的 column 长度选择 schema 来还原 DML 语句 + -safe-mode + 指定是否开启 safe mode，让 Syncer 在任何情况下可重入 + -server-id int + 指定 MySQL slave sever-id (默认 101) + -status-addr string + 指定 Syncer metric 信息; 如 `--status-addr 127:0.0.1:10088` + -timezone string + 目标数据库使用的时区，请使用 IANA 时区标识符，如 `Asia/Shanghai` +``` + +Syncer 的配置文件 `config.toml`： + +```toml +log-level = "info" +log-file = "syncer.log" +log-rotate = "day" + +server-id = 101 + +## meta 文件地址 +meta = "./syncer.meta" +worker-count = 16 +batch = 100 +flavor = "mysql" + +## Prometheus 可以通过该地址拉取 Syncer metrics，也是 Syncer 的 pprof 调试地址 +status-addr = ":8271" + +## 如果设置为 true，Syncer 遇到 DDL 语句时就会停止退出 +stop-on-ddl = false + +## SQL 请求由于网络异常等原因出错时的最大重试次数 +max-retry = 100 + +## 指定目标数据库使用的时区，binlog 中所有 timestamp 字段会按照该时区进行转换，默认使用 Syncer 本地时区 +# timezone = "Asia/Shanghai" + +## 跳过 DDL 语句，格式为 **前缀完全匹配**，如：`DROP TABLE ABC` 至少需要填入 `DROP TABLE` +# skip-ddls = ["ALTER USER", "CREATE USER"] + +## 在使用 route-rules 功能后， +## replicate-do-db & replicate-ignore-db 匹配合表之后 (target-schema & target-table) 数值 +## 优先级关系: replicate-do-db --> replicate-do-table --> replicate-ignore-db --> replicate-ignore-table +## 指定要同步数据库名；支持正则匹配，表达式语句必须以 `~` 开始 +#replicate-do-db = ["~^b.*","s1"] + +## 指定 **忽略** 同步数据库；支持正则匹配，表达式语句必须以 `~` 开始 +#replicate-ignore-db = ["~^b.*","s1"] + +# skip-dmls 支持跳过 DML binlog events，type 字段的值可为：'insert'，'update' 和 'delete' +# 跳过 foo.bar 表的所有 delete 语句 +# [[skip-dmls]] +# db-name = "foo" +# tbl-name = "bar" +# type = "delete" +# +# 跳过所有表的 delete 语句 +# [[skip-dmls]] +# type = "delete" +# +# 跳过 foo.* 表的 delete 语句 +# [[skip-dmls]] +# db-name = "foo" +# type = "delete" + +## 指定要同步的 db.table 表 +## db-name 与 tbl-name 不支持 `db-name ="dbname，dbname2"` 格式 +#[[replicate-do-table]] +#db-name ="dbname" +#tbl-name = "table-name" + +#[[replicate-do-table]] +#db-name ="dbname1" +#tbl-name = "table-name1" + +## 指定要同步的 db.table 表；支持正则匹配，表达式语句必须以 `~` 开始 +#[[replicate-do-table]] +#db-name ="test" +#tbl-name = "~^a.*" + +## 指定 **忽略** 同步数据库 +## db-name & tbl-name 不支持 `db-name ="dbname，dbname2"` 语句格式 +#[[replicate-ignore-table]] +#db-name = "your_db" +#tbl-name = "your_table" + +## 指定要 **忽略** 同步数据库名；支持正则匹配，表达式语句必须以 `~` 开始 +#[[replicate-ignore-table]] +#db-name ="test" +#tbl-name = "~^a.*" + +# sharding 同步规则，采用 wildcharacter +# 1. 星号字符 (*) 可以匹配零个或者多个字符, +# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; +# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 +# 2. 问号字符 (?) 匹配任一一个字符 + +#[[route-rules]] +#pattern-schema = "route_*" +#pattern-table = "abc_*" +#target-schema = "route" +#target-table = "abc" + +#[[route-rules]] +#pattern-schema = "route_*" +#pattern-table = "xyz_*" +#target-schema = "route" +#target-table = "xyz" + +[from] +host = "127.0.0.1" +user = "root" +password = "" +port = 3306 + +[to] +host = "127.0.0.1" +user = "root" +password = "" +port = 4000 +``` + +启动 Syncer： + +{{< copyable "shell-regular" >}} + +```bash +./bin/syncer -config config.toml +``` + +``` +2016/10/27 15:22:01 binlogsyncer.go:226: [info] begin to sync binlog from position (mysql-bin.000003, 1280) +2016/10/27 15:22:01 binlogsyncer.go:130: [info] register slave for master server 127.0.0.1:3306 +2016/10/27 15:22:01 binlogsyncer.go:552: [info] rotate to (mysql-bin.000003, 1280) +2016/10/27 15:22:01 syncer.go:549: [info] rotate binlog to (mysql-bin.000003, 1280) +``` + +### 在 MySQL 中插入新的数据 + +{{< copyable "sql" >}} + +```sql +INSERT INTO t1 VALUES (4, 4), (5, 5); +``` + +登录到 TiDB 查看： + +{{< copyable "shell-regular" >}} + +```bash +mysql -h127.0.0.1 -P4000 -uroot -p +``` + +{{< copyable "sql" >}} + +```sql +select * from t1; +``` + +``` ++----+------+ +| id | age | ++----+------+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | +| 5 | 5 | ++----+------+ +``` + +Syncer 每隔 30s 会输出当前的同步统计，如下所示： + +``` +2017/06/08 01:18:51 syncer.go:934: [info] [syncer]total events = 15, total tps = 130, recent tps = 4, +master-binlog = (ON.000001, 11992), master-binlog-gtid=53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-74, +syncer-binlog = (ON.000001, 2504), syncer-binlog-gtid = 53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-17 +2017/06/08 01:19:21 syncer.go:934: [info] [syncer]total events = 15, total tps = 191, recent tps = 2, +master-binlog = (ON.000001, 11992), master-binlog-gtid=53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-74, +syncer-binlog = (ON.000001, 2504), syncer-binlog-gtid = 53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-35 +``` + +由上述示例可见，使用 Syncer 可以自动将 MySQL 的更新同步到 TiDB。 + +## Syncer 配置说明 + +### 指定数据库同步 + +本部分将通过实际案例描述 Syncer 同步数据库参数的优先级关系。 + +- 如果使用 route-rules 规则，参考 [Sharding 同步支持](#sharding-同步支持) +- 优先级：replicate-do-db --> replicate-do-table --> replicate-ignore-db --> replicate-ignore-table + +```toml +# 指定同步 ops 数据库 +# 指定同步以 ti 开头的数据库 +replicate-do-db = ["ops","~^ti.*"] + +# china 数据库下有 guangzhou / shanghai / beijing 等多张表，只同步 shanghai 与 beijing 表。 +# 指定同步 china 数据库下 shanghai 表 +[[replicate-do-table]] +db-name ="china" +tbl-name = "shanghai" + +# 指定同步 china 数据库下 beijing 表 +[[replicate-do-table]] +db-name ="china" +tbl-name = "beijing" + +# ops 数据库下有 ops_user / ops_admin / weekly 等数据表，只需要同步 ops_user 表。 +# 因 replicate-do-db 优先级比 replicate-do-table 高，所以此处设置只同步 ops_user 表无效，实际工作会同步 ops 整个数据库 +[[replicate-do-table]] +db-name ="ops" +tbl-name = "ops_user" + +# history 数据下有 2017_01 2017_02 ... 2017_12 / 2016_01 2016_02 ... 2016_12 等多张表，只需要同步 2017 年的数据表 +[[replicate-do-table]] +db-name ="history" +tbl-name = "~^2017_.*" + +# 忽略同步 ops 与 fault 数据库 +# 忽略同步以 www 开头的数据库 +## 因 replicate-do-db 优先级比 replicate-ignore-db 高，所以此处忽略同步 ops 不生效。 +replicate-ignore-db = ["ops","fault","~^www"] + +# fault 数据库下有 faults / user_feedback / ticket 等数据表 +# 忽略同步 user_feedback 数据表 +# 因 replicate-ignore-db 优先级比 replicate-ignore-table 高，所以此处设置只忽略同步 user_feedback 表无效，实际工作会忽略同步 fault 整个数据库 +[[replicate-ignore-table]] +db-name = "fault" +tbl-name = "user_feedback" + +# order 数据下有 2017_01 2017_02 ... 2017_12 / 2016_01 2016_02 ... 2016_12 等多张表，忽略 2016 年的数据表 +[[replicate-ignore-table]] +db-name ="order" +tbl-name = "~^2016_.*" +``` + +### Sharding 同步支持 + +根据配置文件的 route-rules，支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则，如下： + +- 是否可以利用 route-rules 的语义规则表示 +- 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 + +暂时对 DDL 支持不完善。 + +![sharding](/media/syncer-sharding.png) + +#### 分库分表同步示例 + +1. 只需在所有 MySQL 实例下面，启动 Syncer, 并设置 route-rules。 +2. `replicate-do-db` & `replicate-ignore-db` 与 route-rules 同时使用场景下，`replicate-do-db` & `replicate-ignore-db` 需要指定 route-rules 中 `target-schema` & `target-table` 的内容。 + +```toml +# 场景如下: +# 数据库A 下有 order_2016 / history_2016 等多个数据库 +# 数据库B 下有 order_2017 / history_2017 等多个数据库 +# 指定同步数据库A order_2016 数据库，数据表如下 2016_01 2016_02 ... 2016_12 +# 指定同步数据库B order_2017 数据库，数据表如下 2017_01 2017_02 ... 2017_12 +# 表内使用 order_id 作为主键，数据之间主键不冲突 +# 忽略同步 history_2016 与 history_2017 数据库 +# 目标库需要为 order ，目标数据表为 order_2017 / order_2016 + +# Syncer 获取到上游数据后，发现 route-rules 规则启用，先做合库合表操作，再进行 do-db & do-table 判定 +## 此处需要设置 target-schema & target-table 判定需要同步的数据库 +[[replicate-do-table]] +db-name ="order" +tbl-name = "order_2016" + +[[replicate-do-table]] +db-name ="order" +tbl-name = "order_2017" + +[[route-rules]] +pattern-schema = "order_2016" +pattern-table = "2016_??" +target-schema = "order" +target-table = "order_2016" + +[[route-rules]] +pattern-schema = "order_2017" +pattern-table = "2017_??" +target-schema = "order" +target-table = "order_2017" +``` + +### Syncer 同步前检查 + +1. 检查数据库版本。 + + 使用 `select @@version;` 命令检查数据库版本。目前，Syncer 只支持以下版本： + + - 5.5 < MySQL 版本 < 8.0 + - MariaDB 版本 >= 10.1.2（更早版本的 binlog 部分字段类型格式与 MySQL 不一致） + + > **注意：** + > + > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则 + > + > - 5.7.1 < MySQL 版本 < 8.0 + > - MariaDB 版本 >= 10.1.3 + +2. 检查源库 `server-id`。 + + 可通过以下命令查看 `server-id`： + + {{< copyable "sql" >}} + + ```sql + show global variables like 'server_id'; + ``` + + ``` + +---------------+-------+ + | Variable_name | Value | + +---------------+-------+ + | server_id | 1 | + +---------------+-------+ + 1 row in set (0.01 sec) + ``` + + - 结果为空或者为 0，Syncer 无法同步数据。 + - Syncer `server-id` 与 MySQL `server-id` 不能相同，且必须在 MySQL cluster 中唯一。 + +3. 检查 Binlog 相关参数。 + + 1. 检查 MySQL 是否开启了 binlog。 + + 使用如下命令确认是否开启了 binlog： + + {{< copyable "sql" >}} + + ```sql + show global variables like 'log_bin'; + ``` + + ``` + +--------------------+---------+ + | Variable_name | Value | + +--------------------+---------+ + | log_bin | ON | + +--------------------+---------+ + 1 row in set (0.00 sec) + ``` + + 如果结果是 `log_bin` = `OFF`，则需要开启 binlog，开启方式请参考[官方文档](https://dev.mysql.com/doc/refman/5.7/en/replication-howto-masterbaseconfig.html)。 + + 2. binlog 格式必须为 `ROW`，且参数 `binlog_row_image` 必须设置为 `FULL`，可使用如下命令查看参数设置： + + {{< copyable "shell-regular" >}} + + ```sql + select variable_name, variable_value from information_schema.global_variables where variable_name in ('binlog_format','binlog_row_image'); + ``` + + ``` + +------------------+----------------+ + | variable_name | variable_value | + +------------------+----------------+ + | BINLOG_FORMAT | ROW | + | BINLOG_ROW_IMAGE | FULL | + +------------------+----------------+ + 2 rows in set (0.001 sec) + ``` + + - 如果以上设置出现错误，则需要修改磁盘上的配置文件，然后重启 MySQL。 + - 将配置的更改持久化存储在磁盘上很重要，这样在 MySQL 重启之后才能显示相应更改。 + - 由于现有的连接会保留全局变量原先的值，所以**不可以**使用 `SET` 语句动态修改这些设置。 + +4. 检查用户权限。 + + 1. 全量导出的 Mydumper 需要的用户权限。 + + - Mydumper 导出数据至少拥有以下权限：`select, reload`。 + - Mydumper 操作对象为 RDS 时，可以添加 `--no-locks` 参数，避免申请 `reload` 权限。 + + 2. 增量同步 Syncer 需要的上游 MySQL/MariaDB 用户权限。 + + 需要上游 MySQL 同步账号至少赋予以下权限： + + ``` + select, replication slave, replication client + ``` + + 3. 下游 TiDB 需要的权限 + + | 权限 | 作用域 | + |----:|:------| + | SELECT | Tables | + | INSERT | Tables | + | UPDATE | Tables | + | DELETE | Tables | + | CREATE | Databases,tables | + | DROP | Databases, tables | + | ALTER | Tables | + | INDEX | Tables | + + 为所同步的数据库或者表，执行下面的 GRANT 语句： + + {{< copyable "sql" >}} + + ```sql + GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,INDEX ON db.table TO 'your_user'@'your_wildcard_of_host'; + ``` + +5. 检查 SQL mode。 + + 必须确认上下游的 SQL mode 一致；如果不一致，则会出现数据同步的错误。 + + {{< copyable "sql" >}} + + ```sql + show variables like '%sql_mode%'; + ``` + + ``` + +---------------+-----------------------------------------------------------------------------------+ + | Variable_name | Value | + +---------------+-----------------------------------------------------------------------------------+ + | sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | + +---------------+-----------------------------------------------------------------------------------+ + 1 row in set (0.01 sec) + ``` + +6. 检查字符集。 + + TiDB 和 MySQL 的字符集的兼容性不同，详见 [TiDB 支持的字符集](/reference/sql/character-set.md)。 + +7. 检查同步的表是否都有主键或者唯一索引。 + + 如果表没有主键或唯一索引，就没法实现幂等，并且此时在下游更新每条数据时都是扫全表，可能导致同步速度变慢，所以建议同步的表都加上主键。 + +## 监控方案 + +Syncer 使用开源时序数据库 Prometheus 作为监控和性能指标信息存储方案，使用 Grafana 作为可视化组件进行展示，配合 AlertManager 来实现报警。其方案如下图所示： + +![monitor_scheme](/media/syncer-monitor-scheme.png) + +### 配置 Syncer 监控与告警 + +Syncer 对外提供 metric 接口，需要 Prometheus 主动获取数据。配置 Syncer 监控与告警的操作步骤如下： + +1. 在 Prometheus 中添加 Syncer job 信息，将以下内容刷新到 Prometheus 配置文件，重启 Prometheus 后生效。 + + ```yaml + - job_name: 'syncer_ops' // 任务名字，区分数据上报 + static_configs: + - targets: ['10.1.1.4:10086'] // Syncer 监听地址与端口，通知 Prometheus 获取 Syncer 的监控数据。 + ``` + +2. 配置 Prometheus [告警](https://prometheus.io/docs/alerting/alertmanager/)，将以下内容刷新到 `alert.rule` 配置文件，重启 Prometheus 后生效。 + + ``` + # syncer + ALERT syncer_status + IF syncer_binlog_file{node='master'} - ON(instance, job) syncer_binlog_file{node='syncer'} > 1 + FOR 1m + LABELS {channels="alerts", env="test-cluster"} + ANNOTATIONS { + summary = "syncer status error", + description="alert: syncer_binlog_file{node='master'} - ON(instance, job) syncer_binlog_file{node='syncer'} > 1 instance: {{ $labels.instance }} values: {{ $value }}", + } + ``` + +#### Grafana 配置 + ++ 进入 Grafana Web 界面（默认地址: `http://localhost:3000` ，默认账号: admin 密码: admin） + ++ 导入 dashboard 配置文件 + + 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 Dashboard [配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json)上传 -> 选择对应的 data source + +### Grafana Syncer metrics 说明 + +#### title: binlog events + +- metrics: `rate(syncer_binlog_event_count[1m])` +- info: 统计 Syncer 每秒已经收到的 binlog 个数 + +#### title: binlog event transform + +- metrics: `histogram_quantile(0.8, sum(rate(syncer_binlog_event_bucket[1m])) by (le))` +- info: Syncer 把 binlog 转换为 SQL 语句的耗时 + +#### title: transaction latency + +- metrics: `histogram_quantile(0.95, sum(rate(syncer_txn_cost_in_second_bucket[1m])) by (le))` +- info: Syncer 在下游 TiDB 执行 transaction 的耗时 + +#### title: transaction tps + +- metrics: `rate(syncer_txn_cost_in_second_count[1m])` +- info: Syncer 在下游 TiDB 每秒执行的 transaction 个数 + +#### title: binlog file gap + +- metrics: `syncer_binlog_file{node="master"} - ON(instance, job) syncer_binlog_file{node="syncer"}` +- info: Syncer 已经同步到的 binlog position 的文件编号距离上游 MySQL 当前 binlog position 的文件编号的值；注意 MySQL 当前 binlog position 是定期查询，在一些情况下该 metrics 会出现负数的情况 + +#### title: binlog skipped events + +- metrics: `rate(syncer_binlog_skipped_events_total[1m])` +- info: Syncer 跳过的 binlog 的个数，你可以在配置文件中配置 `skip-ddls` 和 `skip-dmls` 来跳过指定的 binlog + +#### title: position of binlog position + +- metrics: `syncer_binlog_pos{node="syncer"}` and `syncer_binlog_pos{node="master"}` +- info: 需配合 `file number of binlog position` 一起看。`syncer_binlog_pos{node="master"}` 表示上游 MySQL 当前 binlog position 的 position 值，`syncer_binlog_pos{node="syncer"}` 表示上游 Syncer 已经同步到的 binlog position 的 position 值 + +#### title: file number of binlog position + +- metrics: `syncer_binlog_file{node="syncer"}` and `syncer_binlog_file{node="master"}` +- info: 需要配置 `position of binlog position` 一起看。`syncer_binlog_file{node="master"}` 表示上游 MySQL 当前 binlog position 的文件编号，`syncer_binlog_file{node="syncer"}` 表示上游 Syncer 已经同步到的 binlog 位置的文件编号 + +#### title: execution jobs + +- metrics: `sum(rate(syncer_add_jobs_total[1m])) by (queueNo)` +- info: Syncer 把 binlog 转换成 SQL 语句后，将 SQL 语句以 jobs 的方式加到执行队列中，这个 metrics 表示已经加入执行队列的 jobs 总数 + +#### title: pending jobs + +- metrics: `sum(rate(syncer_add_jobs_total[1m]) - rate(syncer_finished_jobs_total[1m])) by (queueNo)` +- info: 已经加入执行队列但是还没有执行的 jobs 数量 diff --git a/dev/reference/tools/tidb-control.md b/reference/tools/tidb-control.md similarity index 100% rename from dev/reference/tools/tidb-control.md rename to reference/tools/tidb-control.md diff --git a/dev/reference/tools/tidb-lightning/checkpoints.md b/reference/tools/tidb-lightning/checkpoints.md similarity index 100% rename from dev/reference/tools/tidb-lightning/checkpoints.md rename to reference/tools/tidb-lightning/checkpoints.md diff --git a/reference/tools/tidb-lightning/config.md b/reference/tools/tidb-lightning/config.md new file mode 100644 index 000000000000..457b0fce7a72 --- /dev/null +++ b/reference/tools/tidb-lightning/config.md @@ -0,0 +1,326 @@ +--- +title: TiDB Lightning 配置参数 +summary: 使用配置文件或命令行配置 TiDB Lightning。 +category: reference +--- + +# TiDB Lightning 配置参数 + +你可以使用配置文件或命令行配置 TiDB Lightning。本文主要介绍 TiDB Lightning 的全局配置、任务配置和 TiKV Importer 的配置，以及如何使用命令行进行参数配置。 + +## 配置文件 + +TiDB Lightning 的配置文件分为“全局”和“任务”两种类别，二者在结构上兼容。只有当[服务器模式](/reference/tools/tidb-lightning/web.md)开启时，全局配置和任务配置才会有区别；默认情况下，服务器模式为禁用状态，此时 TiDB Lightning 只会执行一个任务，且全局和任务配置使用同一配置文件。 + +### TiDB Lightning 全局配置 + +```toml +### tidb-lightning 全局配置 + +[lightning] +# 用于拉取 web 界面和 Prometheus 监控项的 HTTP 端口。设置为 0 时为禁用状态。 +status-addr = ':8289' + +# 切换为服务器模式并使用 web 界面 +# 详情参见“TiDB Lightning web 界面”文档 +server-mode = false + +# 日志 +level = "info" +file = "tidb-lightning.log" +max-size = 128 # MB +max-days = 28 +max-backups = 14 +``` + +### TiDB Lightning 任务配置 + +```toml +### tidb-lightning 任务配置 + +[lightning] +# 启动之前检查集群是否满足最低需求。 +# check-requirements = true + +# 引擎文件的最大并行数。 +# 每张表被切分成一个用于存储索引的“索引引擎”和若干存储行数据的“数据引擎”。 +# 这两项设置控制两种引擎文件的最大并发数。 +# 这两项设置的值会影响 tikv-importer 的内存和磁盘用量。 +# 两项数值之和不能超过 tikv-importer 的 max-open-engines 的设定。 +index-concurrency = 2 +table-concurrency = 6 + +# 数据的并发数。默认与逻辑 CPU 的数量相同。 +# 混合部署的情况下可以将其大小配置为逻辑 CPU 数的 75%，以限制 CPU 的使用。 +# region-concurrency = + +# I/O 最大并发数。I/O 并发量太高时，会因硬盘内部缓存频繁被刷新 +# 而增加 I/O 等待时间，导致缓存未命中和读取速度降低。 +# 对于不同的存储介质，此参数可能需要调整以达到最佳效率。 +io-concurrency = 5 + +[checkpoint] +# 是否启用断点续传。 +# 导入数据时，TiDB Lightning 会记录当前表导入的进度。 +# 所以即使 Lightning 或其他组件异常退出，在重启时也可以避免重复再导入已完成的数据。 +enable = true +# 存储断点的数据库名称。 +schema = "tidb_lightning_checkpoint" +# 存储断点的方式。 +# - file：存放在本地文件系统。 +# - mysql：存放在兼容 MySQL 的数据库服务器。 +driver = "file" + +# dsn 是数据源名称 (data source name)，表示断点的存放位置。 +# 若 driver = "file"，则 dsn 为断点信息存放的文件路径。 +#若不设置该路径，则默认存储路径为“/tmp/CHECKPOINT_SCHEMA.pb”。 +# 若 driver = "mysql"，则 dsn 为“用户:密码@tcp(地址:端口)/”格式的 URL。 +# 若不设置该 URL，则默认会使用 [tidb] 部分指定的 TiDB 服务器来存储断点。 +# 为减少目标 TiDB 集群的压力，建议指定另一台兼容 MySQL 的数据库服务器来存储断点。 +# dsn = "/tmp/tidb_lightning_checkpoint.pb" + +# 所有数据导入成功后是否保留断点。设置为 false 时为删除断点。 +# 保留断点有利于进行调试，但会泄漏关于数据源的元数据。 +# keep-after-success = false + +[tikv-importer] +# 选择后端：“importer” 或 “tidb“ +# backend = "importer" +# 当后端是 “importer” 时，tikv-importer 的监听地址（需改为实际地址）。 +addr = "172.16.31.10:8287" +# 当后端是 “tidb” 时，插入重复数据时执行的操作。 +# - replace：新数据替代已有数据 +# - ignore：保留已有数据，忽略新数据 +# - error：中止导入并报错 +# on-duplicate = "replace" + +[mydumper] +# 设置文件读取的区块大小，确保该值比数据源的最长字符串长。 +read-block-size = 65536 # Byte (默认为 64 KB) + +# （源数据文件）单个导入区块大小的最小值。 +# Lightning 根据该值将一张大表分割为多个数据引擎文件。 +batch-size = 107_374_182_400 # Byte (默认为 100 GB) + +# 引擎文件需按顺序导入。由于并行处理，多个数据引擎几乎在同时被导入， +# 这样形成的处理队列会造成资源浪费。因此，为了合理分配资源，Lightning +# 稍微增大了前几个区块的大小。该参数也决定了比例系数，即在完全并发下 +# “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GB 大小的 +# 单张表的（导入时长/写入时长）得到。在日志文件中可以看到精确的时间。 +# 如果“导入”更快，区块大小的差异就会更小；比值为 0 时则说明区块大小一致。 +# 取值范围为（0 <= batch-import-ratio < 1）。 +batch-import-ratio = 0.75 + +# mydumper 本地源数据目录。 +data-source-dir = "/data/my_database" +# 如果 no-shcema = false，那么 TiDB Lightning 假设目标 TiDB 集群上 +# 已有表结构，并且不会执行 `CREATE TABLE` 语句。 +no-schema = false +# 指定包含 `CREATE TABLE` 语句的表结构文件的字符集。只支持下列选项： +# - utf8mb4：表结构文件必须使用 UTF-8 编码，否则 Lightning 会报错。 +# - gb18030：表结构文件必须使用 GB-18030 编码，否则 Lightning 会报错。 +# - auto：自动判断文件编码是 UTF-8 还是 GB-18030，两者皆非则会报错（默认）。 +# - binary：不尝试转换编码。 +# 注意：**数据** 文件始终解析为 binary 文件。 +character-set = "auto" + +# 配置 CSV 文件的解析方式。 +[mydumper.csv] +# 字段分隔符，应为单个 ASCII 字符。 +separator = ',' +# 引用定界符，可为单个 ASCII 字符或空字符串。 +delimiter = '"' +# CSV 文件是否包含表头。 +# 如果 header = true，将跳过首行。 +# CSV 文件是否包含 NULL。 +# 如果 not-null = true，CSV 所有列都不能解析为 NULL。 +not-null = false +# 如果 not-null = false（即 CSV 可以包含 NULL）， +# 为以下值的字段将会被解析为 NULL。 +null = '\N' +# 是否对字段内“\“进行转义 +backslash-escape = true +# 如果有行以分隔符结尾，删除尾部分隔符。 +trim-last-separator = false + +[tidb] +# 目标集群的信息。tidb-server 的地址，填一个即可。 +host = "172.16.31.1" +port = 4000 +user = "root" +password = "" +# 表结构信息从 TiDB 的“status-port”获取。 +status-port = 10080 +# pd-server 的地址，填一个即可。 +pd-addr = "172.16.31.4:2379" +# tidb-lightning 引用了 TiDB 库，并生成产生一些日志。 +# 设置 TiDB 库的日志等级。 +log-level = "error" + +# 设置 TiDB 会话变量，提升 Checksum 和 Analyze 的速度。 +# 各参数定义可参阅”控制 Analyze 并发度“文档 +build-stats-concurrency = 20 +distsql-scan-concurrency = 100 +index-serial-scan-concurrency = 20 +checksum-table-concurrency = 16 + +# 解析和执行 SQL 语句的默认 SQL 模式。 +sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" +# `max-allowed-packet` 设置数据库连接允许的最大数据包大小， +# 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0， +# 会使用下游数据库 global 级别的 `max_allowed_packet`。 +max-allowed-packet = 67_108_864 + +# 数据导入完成后，tidb-lightning 可以自动执行 Checksum、Compact 和 Analyze 操作。 +# 在生产环境中，建议这将些参数都设为 true。 +# 执行的顺序为：Checksum -> Compact -> Analyze。 +[post-restore] +# 如果设置为 true，会对所有表逐个执行 `ADMIN CHECKSUM TABLE
` 操作 +# 来验证数据的完整性。 +checksum = true +# 如果设置为 true，会在导入每张表后执行一次 level-1 Compact。 +# 默认值为 false。 +level-1-compact = false +# 如果设置为 true，会在导入过程结束时对整个 TiKV 集群执行一次 full Compact。 +# 默认值为 false。 +compact = false +# 如果设置为 true，会对所有表逐个执行 `ANALYZE TABLE
` 操作。 +analyze = true + +# 设置周期性后台操作。 +# 支持的单位：h（时）、m（分）、s（秒）。 +[cron] +# Lightning 自动刷新导入模式状态的持续时间，该值应小于 TiKV 对应的设定值。 +switch-mode = "5m" +# 在日志中打印导入进度的持续时间。 +log-progress = "5m" + +# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 +# [black-white-list] +# ... +``` + +### TiKV Importer 配置参数 + +```toml +# TiKV Importer 配置文件模版 + +# 日志文件 +log-file = "tikv-importer.log" +# 日志等级：trace, debug, info, warn, error 和 off +log-level = "info" + +[server] +# tikv-importer 的监听地址，tidb-lightning 需要连到这个地址进行数据写入。 +addr = "192.168.20.10:8287" +# gRPC 服务器的线程池大小。 +grpc-concurrency = 16 + +[metric] +# 给 Prometheus 客户端推送的 job 名称。 +job = "tikv-importer" +# 给 Prometheus 客户端推送的间隔。 +interval = "15s" +# Prometheus Pushgateway 的地址。 +address = "" + +[rocksdb] +# background job 的最大并发数。 +max-background-jobs = 32 + +[rocksdb.defaultcf] +# 数据在刷新到硬盘前能存于内存的容量上限。 +write-buffer-size = "1GB" +# 内存中写缓冲器的最大数量。 +max-write-buffer-number = 8 + +# 各个压缩层级使用的算法。 +# 第 0 层的算法用于压缩 KV 数据。 +# 第 6 层的算法用于压缩 SST 文件。 +# 第 1 至 5 层的算法目前尚未使用。 +compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] + +[rocksdb.writecf] +# 同上 +compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] + +[import] +# 存储引擎文件的文件夹路径 +import-dir = "/mnt/ssd/data.import/" +# 处理 RPC 请求的线程数 +num-threads = 16 +# 导入 job 的并发数。 +num-import-jobs = 24 +# 预处理 Region 最长时间。 +# max-prepare-duration = "5m" +# 把要导入的数据切分为这个大小的 Region。 +#region-split-size = "512MB" +# 设置 stream-channel-window 的大小。 +# channel 满了之后 stream 会处于阻塞状态。 +# stream-channel-window = 128 +# 同时打开引擎文档的最大数量。 +max-open-engines = 8 +# Importer 上传至 TiKV 的最大速度（字节/秒）。 +# upload-speed-limit = "512MB" +# 目标存储可用空间比率（store_available_space/store_capacity）的最小值。 +# 如果目标存储空间的可用比率低于该值，Importer 将会暂停上传 SST +# 来为 PD 提供足够时间进行 Regions 负载均衡。 +min-available-ratio = 0.05 +``` + +## 命令行参数 + +### `tidb-lightning` + +使用 `tidb-lightning` 可以对下列参数进行配置： + +| 参数 | 描述 | 对应配置项 | +|:----|:----|:----| +| --config *file* | 从 *file* 读取全局设置。如果没有指定则使用默认设置。 | | +| -V | 输出程序的版本 | | +| -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | +| -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | +| --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | +| --log-file *file* | 日志文件路径 | `lightning.log-file` | +| --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | +| --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | +| --pd-urls *host:port* | PD endpoint 的地址 | `tidb.pd-addr` | +| --tidb-host *host* | TiDB Server 的 host | `tidb.host` | +| --tidb-port *port* | TiDB Server 的端口（默认为 4000） | `tidb.port` | +| --tidb-status *port* | TiDB Server 的状态端口的（默认为 10080） | `tidb.status-port` | +| --tidb-user *user* | 连接到 TiDB 的用户名 | `tidb.user` | +| --tidb-password *password* | 连接到 TiDB 的密码 | `tidb.password` | + +如果同时对命令行参数和配置文件中的对应参数进行更改，命令行参数将优先生效。例如，在 `cfg.toml` 文件中，不管对日志等级做出什么修改，运行 `./tidb-lightning -L debug --config cfg.toml` 命令总是将日志级别设置为 “debug”。 + +### `tidb-lightning-ctl` + +使用 `tidb-lightning-ctl` 可以对下列参数进行配置： + +| 参数 | 描述 | +|:----|:----------| +| --compact | 执行 full compact | +| --switch-mode *mode* | 将每个 TiKV Store 切换到指定模式（normal 或 import） | +| --import-engine *uuid* | 将 TiKV Importer 上关闭的引擎文件导入到 TiKV 集群 | +| --cleanup-engine *uuid* | 删除 TiKV Importer 上的引擎文件 | +| --checkpoint-dump *folder* | 将当前的断点以 CSV 格式存储到文件夹中 | +| --checkpoint-error-destroy *tablename* | 删除断点，如果报错则删除该表 | +| --checkpoint-error-ignore *tablename* | 忽略指定表中断点的报错 | +| --checkpoint-remove *tablename* | 无条件删除表的断点 | + +*tablename* 必须是`` `db`.`tbl` `` 中的限定表名（包括反引号），或关键词 `all`。 + +此外，上表中所有 `tidb-lightning` 的参数也适用于 `tidb-lightning-ctl`。 + +### `tikv-importer` + +使用 `tikv-importer` 可以对下列参数进行配置： + +| 参数 | 描述 | 对应配置项 | +|:----|:----|:-------| +| -C, --config *file* | 从 *file* 读取配置。如果没有指定，则使用默认设置| | +| -V, --version | 输出程序的版本 | | +| -A, --addr *ip:port* | TiKV Importer 服务器的监听地址 | `server.addr` | +| --import-dir *dir* | 引擎文件的存储目录 | `import.import-dir` | +| --log-level *level* | 日志的等级： trace、debug、info、warn、error 或 off | `log-level` | +| --log-file *file* | 日志文件路径 | `log-file` | diff --git a/dev/reference/tools/tidb-lightning/csv.md b/reference/tools/tidb-lightning/csv.md similarity index 100% rename from dev/reference/tools/tidb-lightning/csv.md rename to reference/tools/tidb-lightning/csv.md diff --git a/reference/tools/tidb-lightning/deployment.md b/reference/tools/tidb-lightning/deployment.md new file mode 100644 index 000000000000..65c8fe4ec2a8 --- /dev/null +++ b/reference/tools/tidb-lightning/deployment.md @@ -0,0 +1,279 @@ +--- +title: TiDB Lightning 部署与执行 +category: reference +--- + +# TiDB Lightning 部署与执行 + +本文主要介绍 TiDB Lightning 使用 Importer-backend（默认）进行数据导入的硬件需求，以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 + +如果你想改用 TiDB-backend 进行数据导入，参考 [TiDB Lightning TiDB-backend](/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 + +## 注意事项 + +在使用 TiDB Lightning 前，需注意以下事项： + +- TiDB Lightning 运行后，TiDB 集群将无法正常对外提供服务。 +- 若 `tidb-lightning` 崩溃，集群会留在“导入模式”。若忘记转回“普通模式”，集群会产生大量未压缩的文件，继而消耗 CPU 并导致延迟。此时，需要使用 `tidb-lightning-ctl` 手动将集群转回“普通模式”： + + {{< copyable "shell-regular" >}} + + ```sh + bin/tidb-lightning-ctl -switch-mode=normal + ``` + +- TiDB Lightning 需要下游 TiDB 有如下权限： + + | 权限 | 作用域 | + |:----|:------| + | SELECT | Tables | + | INSERT | Tables | + | UPDATE | Tables | + | DELETE | Tables | + | CREATE | Databases, tables | + | DROP | Databases, tables | + | ALTER | Tables | + + 如果配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 + +## 硬件需求 + +`tidb-lightning` 和 `tikv-importer` 这两个组件皆为资源密集程序，建议各自单独部署。 + +为了优化效能，建议硬件配置如下： + +- `tidb-lightning` + + - 32+ 逻辑核 CPU + - 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 + - 使用万兆网卡，带宽需 300 MB/s 以上 + - 运行过程默认会占满 CPU，建议单独部署。条件不允许的情况下可以和其他组件（比如 `tidb-server`）部署在同一台机器上，然后通过配置 `region-concurrency` 限制 `tidb-lightning` 使用 CPU 资源。 + +- `tikv-importer` + + - 32+ 逻辑核 CPU + - 40 GB+ 内存 + - 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000） + * 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。 + - 使用万兆网卡，带宽需 300 MB/s 以上 + - 运行过程中 CPU、I/O 和网络带宽都可能占满，建议单独部署。 + +如果机器充裕的话，可以部署多套 `tidb-lightning` + `tikv-importer`，然后将源数据以表为粒度进行切分，并发导入。 + +> **注意：** +> +> - `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 资源分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 “24”。 +> +> - `tikv-importer` 将中间数据存储缓存到内存上以加速导入过程。占用内存大小可以通过 **(`max-open-engines` × `write-buffer-size` × 2) + (`num-import-jobs` × `region-split-size` × 2)** 计算得来。如果磁盘写入速度慢，缓存可能会带来更大的内存占用。 + +此外，目标 TiKV 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](/how-to/deploy/hardware-recommendations.md)以外，目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](/faq/tidb.md#326-每个-region-的-replica-数量可配置吗调整的方法是) × 2**。例如集群默认使用 3 副本，那么总存储空间需为数据源大小的 6 倍以上。 + +## 导出数据 + +使用 [`mydumper`](/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： + +{{< copyable "shell-regular" >}} + +```sh +./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ +``` + +其中： + +- `-B test`：从 `test` 数据库导出。 +- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 +- `-t 16`：使用 16 个线程导出数据。 +- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 +- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 + +如果数据源是 CSV 文件，请参考 [CSV 支持](/reference/tools/tidb-lightning/csv.md)获取配置信息。 + +## 部署 TiDB Lightning + +本节介绍 TiDB Lightning 的两种部署方式：[使用 Ansible 部署](#使用-ansible-部署-tidb-lightning)和[手动部署](#手动部署-tidb-lightning)。 + +### 使用 Ansible 部署 TiDB Lightning + +TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/how-to/deploy/orchestrated/ansible.md)。 + +1. 编辑 `inventory.ini`，分别配置一个 IP 来部署 `tidb-lightning` 和 `tikv-importer`。 + + ```ini + ... + + [importer_server] + 192.168.20.9 + + [lightning_server] + 192.168.20.10 + + ... + ``` + +2. 修改 `group_vars/*.yml` 的变量配置这两个工具。 + + - `group_vars/all.yml` + + ```yaml + ... + # tikv-importer 的监听端口。需对 tidb-lightning 服务器开放。 + tikv_importer_port: 8287 + ... + ``` + + - `group_vars/lightning_server.yml` + + ```yaml + --- + dummy: + + # 提供监控告警的端口。需对监控服务器 (monitoring_server) 开放。 + tidb_lightning_pprof_port: 8289 + + # 获取数据源（Mydumper SQL dump 或 CSV）的路径。 + data_source_dir: "{{ deploy_dir }}/mydumper" + ``` + + - `group_vars/importer_server.yml` + + ```yaml + --- + dummy: + + # 储存引擎文件的路径。需存放在空间足够大的分区。 + import_dir: "{{ deploy_dir }}/data.import" + ``` + +3. 开始部署。 + + {{< copyable "shell-regular" >}} + + ```sh + ansible-playbook bootstrap.yml && + ansible-playbook deploy.yml + ``` + +4. 将数据源写入 `data_source_dir` 指定的路径。 + +5. 登录 `tikv-importer` 的服务器，并执行以下命令来启动 Importer。 + + {{< copyable "shell-regular" >}} + + ```sh + scripts/start_importer.sh + ``` + +6. 登录 `tidb-lightning` 的服务器，并执行以下命令来启动 Lightning，开始导入过程。 + + {{< copyable "shell-regular" >}} + + ```sh + scripts/start_lightning.sh + ``` + +7. 完成后，在 `tikv-importer` 的服务器执行 `scripts/stop_importer.sh` 来关闭 Importer。 + +### 手动部署 TiDB Lightning + +#### 第 1 步：部署 TiDB 集群 + +在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群 (版本要求 2.0.9 以上)，建议使用最新版。部署方法可参考 [TiDB 快速入门指南](/overview.md#部署方式)。 + +#### 第 2 步：下载 TiDB Lightning 安装包 + +在[工具下载](/reference/tools/download.md#tidb-lightning)页面下载 TiDB Lightning 安装包（需选择与 TiDB 集群相同的版本）。 + +#### 第 3 步：启动 `tikv-importer` + +1. 从安装包上传 `bin/tikv-importer`。 + +2. 配置 `tikv-importer.toml`。 + + ```toml + # TiKV Importer 配置文件模版 + + # 日志文件。 + log-file = "tikv-importer.log" + # 日志等级：trace、debug、info、warn、error、off。 + log-level = "info" + + [server] + # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 + addr = "192.168.20.10:8287" + + [metric] + # 给 Prometheus 客户端的推送任务名称。 + job = "tikv-importer" + # 给 Prometheus 客户端的推送间隔。 + interval = "15s" + # Prometheus Pushgateway 地址。 + address = "" + + [import] + # 存储引擎文档 (engine file) 的文件夹路径。 + import-dir = "/mnt/ssd/data.import/" + ``` + + 上面仅列出了 `tikv-importer` 的基本配置。完整配置请参考[`tikv-importer` 配置说明](/reference/tools/tidb-lightning/config.md#tikv-importer)。 + +3. 运行 `tikv-importer`。 + + {{< copyable "shell-regular" >}} + + ```sh + nohup ./tikv-importer -C tikv-importer.toml > nohup.out & + ``` + +#### 第 4 步：启动 `tidb-lightning` + +1. 从安装包上传 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl`。 + +2. 将数据源写入到同样的机器。 + +3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置，TiDB Lightning 给出配置错误的提醒并退出。 + + ```toml + [lightning] + + # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。 + # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。 + # region-concurrency = + + # 日志 + level = "info" + file = "tidb-lightning.log" + + [tikv-importer] + # tikv-importer 的监听地址，需改成 tikv-importer 服务器的实际地址。 + addr = "172.16.31.10:8287" + + [mydumper] + # Mydumper 源数据目录。 + data-source-dir = "/data/my_database" + + [tidb] + # 目标集群的信息。tidb-server 的监听地址，填一个即可。 + host = "172.16.31.1" + port = 4000 + user = "root" + password = "" + # 表架构信息在从 TiDB 的“状态端口”获取。 + status-port = 10080 + ``` + + 上面仅列出了 `tidb-lightning` 的基本配置信息。完整配置信息请参考[`tidb-lightning` 配置说明](/reference/tools/tidb-lightning/config.md#tidb-lightning-全局配置)。 + +4. 运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： + + {{< copyable "shell-regular" >}} + + ```sh + #!/bin/bash + nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & + ``` + +## 升级 TiDB Lightning + +你可以通过替换二进制文件升级 TiDB Lightning，无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 + +如果当前有运行的导入任务，推荐任务完成后再升级 TiDB Lightning。否则，你可能需要从头重新导入，因为无法保证断点可以跨版本工作。 diff --git a/reference/tools/tidb-lightning/glossary.md b/reference/tools/tidb-lightning/glossary.md new file mode 100644 index 000000000000..83d7b6d942d3 --- /dev/null +++ b/reference/tools/tidb-lightning/glossary.md @@ -0,0 +1,193 @@ +--- +title: TiDB Lightning 术语表 +summary: 了解 TiDB Lightning 相关的术语及定义。 +category: glossary +--- + +# TiDB Lightning 术语表 + +本术语表提供了 TiDB Lightning 相关的术语和定义，这些术语会出现在 TiDB Lightning 的日志、监控指标、配置和文档中。 + + + +## A + +### Analyze + +统计信息分析。指重建 TiDB 表中的统计信息，即运行 [`ANALYZE TABLE`](/reference/sql/statements/analyze-table.md) 语句。 + +因为 TiDB Lightning 不通过 TiDB 导入数据，统计信息不会自动更新，所以 TiDB Lightning 在导入后显式地分析每个表。如果不需要该操作，可以将 `post-restore.analyze` 设置为 `false`。 + +### `AUTO_INCREMENT_ID` + +用于为自增列分配默认值的自增 ID 计数器。每张表都有一个相关联的 `AUTO_INCREMENT_ID` 计数器。在 TiDB 中，该计数器还用于分配行 ID。 + +因为 TiDB Lightning 不通过 TiDB 导入数据，`AUTO_INCREMENT_ID` 计数器不会自动更新，所以 TiDB Lightning 显式地将 `AUTO_INCREMENT_ID` 改为一个有效值。即使表中没有自增列，这步仍是会执行。 + + + +## B + +### Backend + +也称作 Back end（后端），用于接受 TiDB Lightning 解析结果。 + +详情参阅 [TiDB Lightning TiDB-backend](/reference/tools/tidb-lightning/tidb-backend.md)。 + +### Black-white list + +黑白名单配置列表。用于指定要导入、忽略哪些表和库。 + +详情参阅 [TiDB Lightning 表库过滤](/reference/tools/tidb-lightning/table-filter.md)。 + + + +## C + +### Checkpoint + +断点。用于保证 TiDB Lightning 在导入数据时不断地将进度保存到本地文件或远程数据库中。这样即使进程崩溃，TiDB Lightning 也能从中间状态恢复。 + +详情参见 [TiDB Lightning 断点续传](/reference/tools/tidb-lightning/checkpoints.md)。 + +### Checksum + +校验和。一种用于[验证导入数据正确性](/faq/tidb-lightning.md#如何校验导入的数据的正确性)的方法。 + +在 TiDB Lightning 中，表的校验和是由 3 个数字组成的集合，由该表中每个键值对的内容计算得出。这些数字分别是： + +* 键值对的数量 +* 所有键值对的总长度 +* 每个键值对 [CRC-64-ECMA](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) 按位异或的结果 + +TiDB Lightning 通过比较每个表的[本地校验和](#local-checksum)和[远程校验和](#remote-checksum)来验证导入数据的正确性。如果有任一对校验和不匹配，导入进程就会停止。如果你需要跳过校验和检查，可以将 `post-restore.checksum` 设置为 `false` 。 + +遇到校验和不匹配的问题时，参考[故障排查](/how-to/troubleshoot/tidb-lightning.md#checksum-failed-checksum-mismatched-remote-vs-local)进行处理。 + +### Chunk + +指数据源中的单个文件。 + +### Compaction + +压缩。指将多个小 SST 文件合并为一个大 SST 文件并清理已删除的条目。TiDB Lightning 导入数据时，TiKV 在后台会自动压缩数据。 + +> **注意：** +> +> 出于遗留原因，你仍然可以将 TiDB Lightning 配置为在每次导入表时进行显式压缩，但是官方不推荐采用该操作，且该操作的相关设置默认是禁用的。 +> +> 技术细节参阅 [RocksDB 关于压缩的说明](https://github.com/facebook/rocksdb/wiki/Compaction)。 + + + +## D + +### Data engine + +数据引擎。用于对实际的行数据进行排序的[引擎](#engine)。 + +当一个表数据很多的时候，表的数据会被放置在多个数据引擎中以改善任务流水线并节省 TiKV Importer 的空间。默认条件下，每 100 GB 的 SQL 数据会打开一个新的数据引擎（可通过 `mydumper.batch-size` 配置项进行更改）。 + +TiDB Lightning 同时处理多个数据引擎（可通过 `lightning.table-concurrency` 配置项进行更改）。 + + + +## E + +### Engine + +引擎。在 TiKV Importer 中，一个引擎就是一个用于排序键值对的 RocksDB 实例。 + +TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先打开一个引擎，向其发送未排序的键值对，然后关闭引擎。随后，引擎会对收到的键值对进行排序操作。这些关闭的引擎可以进一步上传至 TiKV store 中为 [Ingest](#ingest) 做准备。 + +引擎使用 TiKV Importer 的 `import-dir` 作为临时存储，有时也会被称为引擎文件 (engine files)。 + +另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 + + + +## I + +### Import mode + +导入模式。指通过降低读取速度和减少空间使用，来优化 TiKV 写入的配置模式。 + +导入过程中，TiDB Lightning 自动在导入模式和[普通模式](#normal-mode)中来回切换。如果 TiKV 卡在导入模式，你可以使用 `tidb-lightning-ctl` [强制切换回普通模式](/faq/tidb-lightning.md#为什么用过-tidb-lightning-之后tidb-集群变得又慢又耗-cpu)。 + +### Index engine + +索引引擎。用于对索引进行排序的[引擎](#engine)。 + +不管表中有多少索引，每张表都只对应**一个**索引引擎。 + +TiDB Lightning 可同时处理多个索引引擎（可通过 `lightning.index-concurrency` 配置项进行更改）。由于每张表正好对应一个索引引擎，`lightning.index-concurrency` 配置项也限定了可同时处理的表的最大数量。 + +### Ingest + +指将 [SST 文件](#sst-file)的全部内容插入到 RocksDB（TiKV）store 中的操作。 + +与逐个插入键值对相比，Ingest 的效率非常高。因此，该操作直接决定了 TiDB Lightning 的性能。 + +技术细节参阅 [RocksDB 关于创建、Ingest SST 文件的 wiki 页面](https://github.com/facebook/rocksdb/wiki/Creating-and-Ingesting-SST-files)。 + + + +## K + +### KV pair + +即 key-value pair（键值对）。 + +### KV encoder + +用于将 SQL 或 CSV 行解析为键值对的例程。多个 KV encoder 会并行运行以加快处理速度。 + + + +## L + +### Local checksum + +本地校验和。在将键值对发送到 TiKV Importer 前，由 TiDB Lightning 计算的表的校验和。 + + + +## N + +### Normal mode + +普通模式。未启用[导入模式](#import-mode)时的模式。 + + + +## P + +### Post-processing + +指整个数据源被解析发送到 TiKV Importer 之后的一段时间。此时 TiDB Lightning 正在等待 TiKV Importer 上传、[Ingest](#ingest) [SST 文件](#sst-file)。 + + + +## R + +### Remote checksum + +远程校验和。指导入 TiDB 后所计算的表的[校验和](#checksum)。 + + + +## S + +### Scattering + +指随机再分配 [Region](/glossary.md#regionpeerraft-group) 中 leader 和 peer 的操作。Scattering 确保导入的数据在 TiKV store 中均匀分布，这样可以降低 PD 调度的压力。 + +### Splitting + +指 TiKV Importer 在上传之前会将单个引擎文件拆分为若干小 [SST 文件](#sst-file)的操作。这是因为引擎文件通常很大（约为 100 GB），在 TiKV 中不适合视为单一的 [Region](/glossary.md#regionpeerraft-group)。拆分的文件大小可通过 `import.region-split-size` 配置项更改。 + +### SST file + +Sorted string table file（排序字符串表文件）。SST 文件是一种在 RocksDB 中（因而也是 TiKV 中）键值对集合在本地的存储形式。 + +TiKV Importer 从关闭的[引擎](#engine)中生成 SST 文件。这些 SST 文件接着被上传、[ingest](#ingest) 到 TiKV store 中。 diff --git a/dev/reference/tools/tidb-lightning/monitor.md b/reference/tools/tidb-lightning/monitor.md similarity index 100% rename from dev/reference/tools/tidb-lightning/monitor.md rename to reference/tools/tidb-lightning/monitor.md diff --git a/reference/tools/tidb-lightning/overview.md b/reference/tools/tidb-lightning/overview.md new file mode 100644 index 000000000000..c5629a9aaceb --- /dev/null +++ b/reference/tools/tidb-lightning/overview.md @@ -0,0 +1,42 @@ +--- +title: TiDB Lightning 简介 +category: reference +--- + +# TiDB Lightning 简介 + +TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量数据的备份恢复。目前，支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： + +- **迅速**导入**大量新**数据。 +- 备份恢复所有数据。 + +## TiDB Lightning 整体架构 + +TiDB Lightning 主要包含两个部分： + +- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键值对（KV 对）发送到 `tikv-importer`、检查数据完整性等。 +- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，对 `tidb-lightning` 写入的键值对进行缓存、排序、切分操作并导入到 TiKV 集群。 + +![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) + +TiDB Lightning 整体工作原理如下： + +1. 在导数据之前，`tidb-lightning` 会自动将 TiKV 集群切换为“导入模式” (import mode)，优化写入效率并停止自动压缩。 + +2. `tidb-lightning` 会在目标数据库建立架构和表，并获取其元数据。 + +3. 每张表都会被分割为多个连续的**区块**，这样来自大表 (200 GB+) 的数据就可以用增量方式导入。 + +4. `tidb-lightning` 会通过 gRPC 让 `tikv-importer` 为每一个区块准备一个“引擎文件 (engine file)”来处理键值对。`tidb-lightning` 会并发读取 SQL dump，将数据源转换成与 TiDB 相同编码的键值对，然后发送到 `tikv-importer` 里对应的引擎文件。 + +5. 当一个引擎文件数据写入完毕时，`tikv-importer` 便开始对目标 TiKV 集群数据进行分裂和调度，然后导入数据到 TiKV 集群。 + + 引擎文件包含两种：**数据引擎**与**索引引擎**，各自又对应两种键值对：行数据和次级索引。通常行数据在数据源里是完全有序的，而次级索引是无序的。因此，数据引擎文件在对应区块写入完成后会被立即上传，而所有的索引引擎文件只有在整张表所有区块编码完成后才会执行导入。 + +6. 整张表相关联的所有引擎文件完成导入后，`tidb-lightning` 会对比本地数据源及下游集群的校验和 (checksum)，确保导入的数据无损，然后让 TiDB 分析 (`ANALYZE`) 这些新增的数据，以优化日后的操作。同时，`tidb-lightning` 调整 `AUTO_INCREMENT` 值防止之后新增数据时发生冲突。 + + 表的自增 ID 是通过行数的**上界**估计值得到的，与表的数据文件总大小成正比。因此，最后的自增 ID 通常比实际行数大得多。这属于正常现象，因为在 TiDB 中自增 ID [不一定是连续分配的](/reference/mysql-compatibility.md#auto-increment-id)。 + +7. 在所有步骤完毕后，`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode)，此后 TiDB 集群可以正常对外提供服务。 + +TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似，使用 TiDB-backend 时，`tidb-lightning` 将数据转换为 `INSERT` 语句，然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/reference/tools/tidb-lightning/tidb-backend.md)。 diff --git a/dev/reference/tools/tidb-lightning/table-filter.md b/reference/tools/tidb-lightning/table-filter.md similarity index 100% rename from dev/reference/tools/tidb-lightning/table-filter.md rename to reference/tools/tidb-lightning/table-filter.md diff --git a/reference/tools/tidb-lightning/tidb-backend.md b/reference/tools/tidb-lightning/tidb-backend.md new file mode 100644 index 000000000000..ce576b37bc2f --- /dev/null +++ b/reference/tools/tidb-lightning/tidb-backend.md @@ -0,0 +1,208 @@ +--- +title: TiDB Lightning TiDB-Backend +summary: 了解 TiDB Lightning TiDB-backend。 +category: reference +--- + +# TiDB Lightning TiDB-Backend + +TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前，TiDB Lightning 支持 Importer-backend（默认）和 TiDB-backend 两种后端，两者导入数据的区别如下： + +* **Importer-backend**：`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对，由 `tikv-importer` 对写入的键值对进行排序，然后把这些键值对 Ingest 到 TiKV 节点中。 + +* **TiDB-backend**：`tidb-lightning` 先将数据编码成 `INSERT` 语句，然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 + +| 后端 | Importer-backend | TiDB-backend | +|:---|:---|:---| +| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | +| 资源使用率 | 高 | 低 | +| 导入时是否满足 ACID | 否 | 是 | +| 目标表 | 必须为空 | 可以不为空 | + +## 部署 TiDB-backend + +使用 TiDB-backend 时，你无需部署 `tikv-importer`。与[标准部署过程](/reference/tools/tidb-lightning/deployment.md)相比，部署 TiDB-backend 时有如下不同： + +* 可以跳过所有涉及 `tikv-importer` 的步骤。 +* 必须更改相应配置申明使用的是 TiDB-backend。 + +### 硬件需求 + +使用 TiDB-backend 时， TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此，即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下： + +* 16 逻辑核 CPU +* 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 +* 千兆网卡 + +### 使用 Ansible 部署 + +1. `inventory.ini` 文件中，`[importer_server]` 部分可以留空。 + + ```ini + ... + + [importer_server] + # keep empty + + [lightning_server] + 192.168.20.10 + + ... + ``` + +2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置，`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 + + ```yaml + ... + tikv_importer: + backend: "tidb" # <-- 改成 “tidb” + ... + ``` + +3. 启动、部署集群。 + +4. 为 TiDB Lightning 挂载数据源。 + +5. 启动 `tidb-lightning`。 + +### 手动部署 + +手动部署时，你无需下载和配置 `tikv-importer`。 + +在运行 `tidb-lightning` 之前，在配置文件中加上如下几行： + +```toml +[tikv-importer] +backend = "tidb" +``` + +或者在用命令行启动 `tidb-lightning` 时，传入参数 `--backend tidb`。 + +## 冲突解决 + +TiDB-backend 支持导入到已填充的表（非空表）。但是，新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为： + +```toml +[tikv-importer] +backend = "tidb" +on-duplicate = "replace" # 或者 “error”、“ignore” +``` + +| 设置 | 冲突时默认行为 | 对应 SQL 语句 | +|:---|:---|:---| +| replace | 新数据替代旧数据 | `REPLACE INTO ...` | +| ignore | 保留旧数据，忽略新数据 | `INSERT IGNORE INTO ...` | +| error | 中止导入 | `INSERT INTO ...` | + +## 从 Loader 迁移到 TiDB Lightning TiDB-backend + +TiDB Lightning TiDB-backend 可以完全取代 [Loader](/reference/tools/loader.md)。下表说明了如何将 [Loader](/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/reference/tools/tidb-lightning/config.md)中： + +
+ + + + + + + + + +
LoaderTiDB Lightning
+ +```toml +# 日志 +log-level = "info" +log-file = "loader.log" +# Prometheus +status-addr = ":8272" +# 线程数 +pool-size = 16 +``` + + + +```toml +[lightning] +# 日志 +level = "info" +file = "tidb-lightning.log" +# Prometheus +pprof-port = 8289 +# 并发度 (最好使用默认设置) +#region-concurrency = 16 +``` + +
+ +```toml +# 断点数据库名 +checkpoint-schema = "tidb_loader" +``` + + + +```toml +[checkpoint] +# 断点存储 +enable = true +schema = "tidb_lightning_checkpoint" +# 断点默认存储在本地的文件系统，这样更高效。但你也可以 +# 选择将断点存储在目标数据库中，设置如下： +# driver = "mysql" +``` + +
+ +```toml +``` + + + +```toml +[tikv-importer] +# 使用 TiDB-backend +backend = "tidb" +``` + +
+ +```toml +# 数据源目录 +dir = "/data/export/" +``` + + + +```toml +[mydumper] +# 数据源目录 +data-source-dir = "/data/export" +``` + +
+ +```toml +[db] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +user = "root" +password = "" +#sql-mode = "" +``` + + + +```toml +[tidb] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +status-port = 10080 # <- 必须有的参数 +user = "root" +password = "" +#sql-mode = "" +``` + +
diff --git a/reference/tools/tidb-lightning/web.md b/reference/tools/tidb-lightning/web.md new file mode 100644 index 000000000000..6fca77f1a1d2 --- /dev/null +++ b/reference/tools/tidb-lightning/web.md @@ -0,0 +1,82 @@ +--- +title: TiDB Lightning Web 界面 +summary: 了解 TiDB Lightning 的服务器模式——通过 Web 界面来控制 TiDB Lightning。 +category: reference +--- + +# TiDB Lightning Web 界面 + +TiDB Lightning 支持在网页上查看导入进度或执行一些简单任务管理，这就是 TiDB Lightning 的**服务器模式**。本文将介绍服务器模式下的 Web 界面和一些常见操作。 + +启用服务器模式的方式有如下几种： + +1. 在启动 `tidb-lightning` 时加上命令行参数 `--server-mode`。 + + ```sh + ./tidb-lightning --server-mode --status-addr :8289 + ``` + +2. 在配置文件中设置 `lightning.server-mode`。 + + ```toml + [lightning] + server-mode = true + status-addr = ':8289' + ``` + +TiDB Lightning 启动后，可以访问 `http://127.0.0.1:8289` 来管理程序（实际的 URL 取决于你的 `status-addr` 设置）。 + +服务器模式下，TiDB Lightning 不会立即开始运行，而是通过用户在 web 页面提交（多个）**任务**来导入数据。 + +## TiDB Lightning Web 首页 + +![TiDB Lightning Web 首页](/media/lightning-web-frontpage.png) + +标题栏上图标所对应的功能，从左到右依次为： + +| 图标 | 功能 | +|:----|:----| +| "TiDB Lightning" | 点击即返回首页 | +| ⚠ | 显示**前一个**任务的所有错误信息 | +| ⓘ | 列出当前及队列中的任务，可能会出现一个标记提示队列中任务的数量 | +| + | 提交单个任务 | +| ⏸/▶ | 暂停/继续当前操作 | +| ⟳ | 设置网页自动刷新 | + +标题栏下方的三个面板显示了不同状态下的所有表： + +* Active：当前正在导入这些表 +* Completed：这些表导入成功或失败 +* Pending：这些表还没有被处理 + +每个面板都包含用于描述表状态的卡片。 + +## 提交任务 + +点击标题栏的 **+** 图标提交任务。 + +![提交任务对话框](/media/lightning-web-submit.png) + +任务 (task) 为 TOML 格式的文件，具体参考 [TiDB Lightning 任务配置](/reference/tools/tidb-lightning/config.md#tidb-lightning-任务配置参数)。你也可以点击 **UPLOAD** 上传一个本地的 TOML 文件。 + +点击 **SUBMIT** 运行任务。如果当前有任务正在运行，新增任务会加入队列并在当前任务结束后执行。 + +## 查看导入进度 + +点击首页表格卡片上的 **>** 图标，查看表格导入的详细进度。 + +![表格导入进度](/media/lightning-web-table.png) + +该页显示每张表的引擎文件的导入过程。 + +点击标题栏上的 **TiDB Lightning** 返回首页。 + +## 管理任务 + +单击标题栏上的 **ⓘ** 图标来管理当前及队列中的任务。 + +![任务管理页面](/media/lightning-web-queue.png) + +每个任务都是依据提交时间来标记。点击该任务将显示 JSON 格式的配置文件。 + +点击任务上的 **⋮** 可以对该任务进行管理。你可以立即停止任务，或重新排序队列中的任务。 diff --git a/dev/reference/tools/tikv-control.md b/reference/tools/tikv-control.md similarity index 100% rename from dev/reference/tools/tikv-control.md rename to reference/tools/tikv-control.md diff --git a/reference/tools/user-guide.md b/reference/tools/user-guide.md new file mode 100644 index 000000000000..d7627ffb5afe --- /dev/null +++ b/reference/tools/user-guide.md @@ -0,0 +1,185 @@ +--- +title: TiDB 生态工具使用指南 +category: reference +aliases: ['/docs-cn/dev/how-to/migrate/from-mysql/', '/docs-cn/dev/how-to/migrate/incrementally-from-mysql/', '/docs-cn/dev/how-to/migrate/overview/', '/docs-cn/dev/reference/tools/use-guide/'] +--- + +# TiDB 生态工具使用指南 + +目前 TiDB 生态工具较多，有些工具之间有功能重叠，也有些属于版本迭代关系。本文档将对各个工具进行介绍，说明各个工具之间的关系，并且说明各个版本、场景下应该使用哪些工具。 + +## TiDB 生态工具概览 + +TiDB 生态工具可以分为几种： + +- 数据导入类，包括全量导入工具、备份和恢复工具、增量导入工具等 +- 数据导出类，包括全量导出工具、增量导出工具等 + +下面将分别介绍这两类工具。 + +### 数据导入类 + +#### 全量导入工具 Loader（停止维护，不推荐使用） + +[Loader](/reference/tools/loader.md) 是一款轻量级的全量数据导入工具，数据以 SQL 的形式导入到 TiDB 中。目前这个工具正在逐步被 [TiDB Lightning](#全量导入工具-tidb-lightning) 替换掉，参见 [TiDB Lightning TiDB-backend 文档](/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。 + +以下是 Loader 的一些基本信息： + +- Loader 的输入：Mydumper 输出的文件 +- Loader 的输出：以 SQL 形式写入 TiDB +- 适用 TiDB 版本：所有版本 +- Kubernetes 支持：[备份与恢复](/tidb-in-kubernetes/maintain/backup-and-restore.md) + +#### 全量导入工具 TiDB Lightning + +[TiDB Lightning](/reference/tools/tidb-lightning/overview.md) 是将全量数据快速导入到一个新的 TiDB 集群的工具。 + +注意用 TiDB Lightning 导入数据到 TiDB 的时候，有两种模式： + +- 默认模式：`tikv-importer` 为后端，这种模式下导入数据过程中集群无法提供正常的服务，用于导入大量的数据（TB 级别）。 +- 第二种模式：`TiDB` 为后端（相当于 Loader 的功能），相对默认模式导入速度较慢，但是可以在线导入。 + +以下是 TiDB Lightning 的一些基本信息： + +- Lightning 的输入 + - Mydumper 输出文件 + - CSV 格式文件 +- 适用 TiDB 版本：v2.1 及以上 +- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](/tidb-in-kubernetes/maintain/lightning.md) + +#### 备份和恢复工具 BR + +[BR](/reference/tools/br/br.md) 是 TiDB 进行分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 Mydumper 和 Loader，BR 更适合大数据量的场景，有更高效的备份和恢复效率。 + +以下是 BR 的一些基本信息： + +- [备份输出和恢复输入的文件类型](/reference/tools/br/br.md#备份文件类型)：SST + `backupmeta` 文件 +- 适用 TiDB 版本：v3.1 及 v4.0 +- Kubernetes 支持：已支持，文档撰写中 + +#### 增量导入工具 Syncer（已停止维护，不推荐使用） + +[Syncer](/reference/tools/syncer.md) 是将 MySQL/MariaDB 增量 binlog 数据实时复制导入到 TiDB 的工具。目前推荐使用 [TiDB Data Migration](#增量导入工具-tidb-data-migration) 替换该工具。 + +以下是 Syncer 的一些基本信息： + +- Syncer 的输入：MySQL/MariaDB 的 binlog +- Syncer 的输出：以 SQL 形式写入 TiDB +- 适用 TiDB 版本：所有版本 +- Kubernetes 支持：不支持 + +#### 增量导入工具 TiDB Data Migration + +[TiDB Data Migration (DM)](/reference/tools/data-migration/overview.md) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的同步。 + +以下是 DM 的一些基本信息： + +- DM 的输入：MySQL/MariaDB 的全量数据以及 binlog +- DM 的输出：以 SQL 形式写入 TiDB +- 适用 TiDB 版本：所有版本 +- Kubernetes 支持：开发中 + +### 数据导出类 + +#### 全量导出工具 Mydumper + +[Mydumper](/reference/tools/mydumper.md) 用于对 MySQL/TiDB 进行全量逻辑备份。 + +以下是 Mydumper 的一些基本信息： + +- Mydumper 的输入：MySQL/TiDB 集群 +- Mydumper 的输出：SQL 文件 +- 适用 TiDB 版本：所有版本 +- Kubernetes 支持：[备份与恢复](/tidb-in-kubernetes/maintain/backup-and-restore.md) + +#### 增量导出工具 TiDB Binlog + +[TiDB Binlog](/reference/tidb-binlog/overview.md) 是收集 TiDB 的 binlog，并提供准实时同步和备份的工具。 + +以下是 TiDB Binlog 的一些基本信息： + +- TiDB Binlog 的输入：TiDB 集群 +- TiDB Binlog 的输出：MySQL、TiDB、Kafka 或者增量备份文件 +- 适用 TiDB 版本：v2.1 及以上 +- Kubernetes 支持：[TiDB Binlog 运维文档](/tidb-in-kubernetes/maintain/tidb-binlog.md)，[Kubernetes 上的 TiDB Binlog Drainer 配置](/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) + +## 工具演进路线 + +下面简单的介绍一下 TiDB 生态工具集的演进，方便大家了解工具之间的关系。 + +### TiDB 备份与恢复 + +Mydumper、Loader -> BR： + +Mydumper 和 Loader 都是在逻辑层面进行备份和恢复，效率较低；BR 使用 TiDB 的特性进行备份和恢复，适合数据量比较大的场景，备份效率大大提升。 + +### TiDB 全量恢复 + +Loader -> TiDB Lightning： + +Loader 使用 SQL 的方式进行全量数据恢复，效率较低。TiDB Lightning 将数据直接导入 TiKV，大大提升了全量数据恢复的效率，适合将大量数据（TB 级别以上数据）快速导入到一个全新的 TiDB 集群中；且 TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，支持在线导入数据。 + +### MySQL 数据迁移 + +- Mydumper、Loader、Syncer -> DM： + + 使用 Mydumper、Loader、Syncer 将 MySQL 数据迁移到 TiDB，迁移过程比较繁琐。DM 提供了一体化的数据迁移方案，提高了易用性，而且 DM 还支持分库分表的合并。 + +- Loader -> TiDB Lightning： + + TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，由 TiDB Lightning 统一提供全量数据恢复功能。 + +## 数据迁移解决方案 + +针对 TiDB 的 2.1，3.0 以及 3.1 版本，下面给出典型业务场景下的数据迁移方案。 + +### TiDB 3.0 全链路数据迁移方案 + +#### MySQL 数据迁移到 TiDB + +如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： + +1. 使用 Mydumper 导出 MySQL 全量数据 +2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 +3. 使用 DM 同步 MySQL 增量数据到 TiDB + +如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 + +#### TiDB 集群数据的同步 + +使用 TiDB Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 + +#### TiDB 集群数据的全量备份及恢复 + +推荐步骤： + +1. 使用 Mydumper 进行全量数据的备份 +2. 使用 TiDB Lightning 将全量数据恢复到 TiDB/MySQL + +### TiDB 3.1 全链路数据迁移方案 + +#### MySQL 数据迁移到 TiDB + +如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： + +1. 使用 Mydumper 导出 MySQL 全量数据 +2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 +3. 使用 DM 同步 MySQL 增量数据到 TiDB + +如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 + +#### TiDB 集群数据的同步 + +使用 TiDB-Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 + +#### TiDB 集群数据的全量备份及恢复 + +- 恢复到 TiDB + + - 使用 BR 进行全量数据的备份 + - 使用 BR 进行全量数据的恢复 + +- 恢复到 MySQL + + - 使用 Mydumper 进行全量数据的备份 + - 使用 TiDB Lightning 进行全量数据的恢复 diff --git a/reference/transactions/overview.md b/reference/transactions/overview.md new file mode 100644 index 000000000000..22a06a39aa0f --- /dev/null +++ b/reference/transactions/overview.md @@ -0,0 +1,214 @@ +--- +title: TiDB 事务概览 +summary: 了解 TiDB 中的事务。 +category: reference +--- + +# TiDB 事务概览 + +TiDB 支持完整的分布式事务，提供[乐观事务](/reference/transactions/transaction-optimistic.md)与[悲观事务](/reference/transactions/transaction-pessimistic.md)（TiDB 3.0 中引入）两种事务模型。本文主要介绍涉及到事务的语句、显式/隐式事务、事务的隔离级别和惰性检查，以及事务大小的限制。 + +常用的变量包括 [`autocommit`](#自动提交)、[`tidb_disable_txn_auto_retry`](/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_disable_txn_auto_retry) 以及 [`tidb_retry_limit`](/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_retry_limit)。 + +## 常用事务语句 + +### `BEGIN` 和 `START TRANSACTION` + +语法： + +{{< copyable "sql" >}} + +```sql +BEGIN; +``` + +{{< copyable "sql" >}} + +```sql +START TRANSACTION; +``` + +{{< copyable "sql" >}} + +```sql +START TRANSACTION WITH CONSISTENT SNAPSHOT; +``` + +以上三条语句都用于开启事务，效果相同。执行开启事务语句可以显式地开启一个新的事务。如果执行以上语句时，当前 Session 正处于一个事务的中间过程，那么系统会先自动提交当前事务，再开启一个新的事务。 + +### `COMMIT` + +语法： + +{{< copyable "sql" >}} + +```sql +COMMIT; +``` + +该语句用于提交当前的事务，包括从 `[BEGIN|START TRANSACTION]` 到 `COMMIT` 之间的所有修改。 + +### `ROLLBACK` + +语法： + +{{< copyable "sql" >}} + +```sql +ROLLBACK; +``` + +该语句用于回滚当前事务，撤销从 `[BEGIN|START TRANSACTION]` 到 `ROLLBACK` 之间的所有修改。 + +## 自动提交 + +语法： + +{{< copyable "sql" >}} + +```sql +SET autocommit = {0 | 1} +``` + +当 `autocommit = 1` 时（默认），当前的 Session 为自动提交状态，即每条语句运行后，TiDB 会自动将修改提交到数据库中。设置 `autocommit = 0` 时更改当前 Session 更改为非自动提交状态，通过执行 `COMMIT` 语句来手动提交事务。 + +> **注意：** +> +> 某些语句执行后会导致隐式提交。例如，执行 `[BEGIN|START TRANCATION]` 语句时，TiDB 会试图提交上一个事务，并开启一个新的事务。详情参见 [implicit commit](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html)。 + +另外，`autocommit` 也是一个系统变量，你可以通过变量赋值语句修改当前 Session 或 Global 的值。 + +{{< copyable "sql" >}} + +```sql +SET @@SESSION.autocommit = {0 | 1}; +``` + +{{< copyable "sql" >}} + +```sql +SET @@GLOBAL.autocommit = {0 | 1}; +``` + +## 显式事务和隐式事务 + +TiDB 可以显式地使用事务（通过 `[BEGIN|START TRANSACTION]`/`COMMIT` 语句定义事务的开始和结束) 或者隐式地使用事务 (`SET autocommit = 1`)。 + +在自动提交状态下，使用 `[BEGIN|START TRANSACTION]` 语句会显式地开启一个事务，同时也会禁用自动提交，使隐式事务变成显式事务。直到执行 `COMMIT` 或 `ROLLBACK` 语句时才会恢复到此前默认的自动提交状态。 + +对于 DDL 语句，会自动提交并且不能回滚。如果运行 DDL 的时候，正在一个事务的中间过程中，会先自动提交当前事务，再执行 DDL。 + +## 事务隔离级别 + +TiDB **只支持** `SNAPSHOT ISOLATION`，可以通过下面的语句将当前 Session 的隔离级别设置为 `READ COMMITTED`，这只是语法上的兼容，事务依旧是以 `SNAPSHOT ISOLATION` 来执行。 + +{{< copyable "sql" >}} + +```sql +SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; +``` + +## 惰性检查 + +TiDB 中，对于普通的 `INSERT` 语句写入的值，会进行惰性检查。惰性检查的含义是，不在 `INSERT` 语句执行时进行唯一约束的检查，而在事务提交时进行唯一约束的检查。 + +举例： + +{{< copyable "sql" >}} + +```sql +CREATE TABLE T (I INT KEY); +INSERT INTO T VALUES (1); +BEGIN; +INSERT INTO T VALUES (1); -- MySQL 返回错误；TiDB 返回成功 +INSERT INTO T VALUES (2); +COMMIT; -- MySQL 提交成功；TiDB 返回错误，事务回滚 +SELECT * FROM T; -- MySQL 返回 1 2；TiDB 返回 1 +``` + +惰性检查的意义在于，如果对事务中每个 `INSERT` 语句都立刻进行唯一性约束检查，将造成很高的网络开销。而在提交时进行一次批量检查，将会大幅提升性能。 + +> **注意：** +> +> 本优化仅对普通的 `INSERT` 语句生效，对 `INSERT IGNORE` 和 `INSERT ON DUPLICATE KEY UPDATE` 不会生效。 + +## 语句回滚 + +TiDB 支持语句执行的原子性回滚。在事务内部执行一个语句，遇到错误时，该语句整体不会生效。 + +{{< copyable "sql" >}} + +```sql +begin; +insert into test values (1); +insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 +insert into test values (3); +commit; +``` + +上面的例子里面，第二条语句执行失败，但第一和第三条语句仍然能正常提交。 + +{{< copyable "sql" >}} + +```sql +begin; +insert into test values (1); +insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 +insert into test values (3); +rollback; +``` + +以上例子中，第二条语句执行失败。由于调用了 `ROLLBACK`，因此事务不会将任何数据写入数据库。 + +## 事务大小 + +对于 TiDB 事务而言，事务太大或太小，都会影响事务的执行效率。 + +### 小事务 + +以如下 query 为例，当 `autocommit = 1` 时，下面三条语句各为一个事务： + +{{< copyable "sql" >}} + +```sql +UPDATE my_table SET a ='new_value' WHERE id = 1; +UPDATE my_table SET a ='newer_value' WHERE id = 2; +UPDATE my_table SET a ='newest_value' WHERE id = 3; +``` + +此时每一条语句都需要经过两阶段提交，频繁的网络交互致使延迟率高。为提升事务执行效率，可以选择使用显式事务，即在一个事务内执行三条语句。 + +优化后版本： + +{{< copyable "sql" >}} + +```sql +START TRANSACTION; +UPDATE my_table SET a ='new_value' WHERE id = 1; +UPDATE my_table SET a ='newer_value' WHERE id = 2; +UPDATE my_table SET a ='newest_value' WHERE id = 3; +COMMIT; +``` + +同理，执行 `INSERT` 语句时，建议使用显式事务。 + +> **注意：** +> +> 由于 TiDB 中的资源是分布式的，TiDB 中单线程 workload 可能不会很好地利用分布式资源，因此性能相比于单实例部署的 MySQL 较低。这与 TiDB 中的事务延迟较高的情況类似。 + +### 大事务 + +由于 TiDB 两阶段提交的要求，修改数据的单个事务过大时会存在以下问题： + +* 客户端在提交之前，数据都写在内存中，而数据量过多时易导致 OOM (Out of Memory) 错误。 +* 在第一阶段写入数据耗时增加，与其他事务出现写冲突的概率会指数级增长。 +* 最终导致事务完成提交的耗时增加。 + +因此，TiDB 对事务做了一些限制： + +* 单个事务包含的 SQL 语句不超过 5000 条（默认） +* 每个键值对不超过 6 MB + +为了使性能达到最优，建议每 100～500 行写入一个事务。 + +TiDB 设置了键值对的总大小不超过 100 MB 默认限制，可以通过配置文件中的配置项 `txn-total-size-limit` 进行修改，最大支持到 10GB。实际的单个事务大小限制还取决于用户的内存，执行大事务时 TiDB 进程的内存消耗大约是事务大小 6 倍以上。 \ No newline at end of file diff --git a/reference/transactions/transaction-isolation.md b/reference/transactions/transaction-isolation.md new file mode 100644 index 000000000000..f697fb7c8853 --- /dev/null +++ b/reference/transactions/transaction-isolation.md @@ -0,0 +1,65 @@ +--- +title: TiDB 事务隔离级别 +summary: 了解 TiDB 事务的隔离级别。 +category: reference +--- + +# TiDB 事务隔离级别 + +事务隔离级别是数据库事务处理的基础，[ACID](/glossary.md#acid) 中的 “I”，即 Isolation，指的就是事务的隔离性。 + +SQL-92 标准定义了 4 种隔离级别：读未提交 (READ UNCOMMITTED)、读已提交 (READ COMMITTED)、可重复读 (REPEATABLE READ)、串行化 (SERIALIZABLE)。详见下表： + +| Isolation Level | Dirty Write | Dirty Read | Fuzzy Read | Phantom | +| ---------------- | ------------ | ------------ | ------------ | ------------ | +| READ UNCOMMITTED | Not Possible | Possible | Possible | Possible | +| READ COMMITTED | Not Possible | Not possible | Possible | Possible | +| REPEATABLE READ | Not Possible | Not possible | Not possible | Possible | +| SERIALIZABLE | Not Possible | Not possible | Not possible | Not possible | + +TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](#与-ansi-可重复读隔离级别的区别)和 [MySQL 可重复读隔离级别](#与-mysql-可重复读隔离级别的区别)。 + +> **注意：** +> +> 在 TiDB v3.0 中，事务的自动重试功能默认为禁用状态。关于该项功能对隔离级别的影响以及如何开启该项功能，请参考[事务重试](/reference/transactions/transaction-optimistic.md#重试机制)。 + +## 可重复读隔离级别 (Repeatable Read) + +当事务隔离级别为可重复读时，只能读到该事务启动时已经提交的其他事务修改的数据，未提交的数据或在事务启动后其他事务提交的数据是不可见的。对于本事务而言，事务语句可以看到之前的语句做出的修改。 + +对于运行于不同节点的事务而言，不同事务启动和提交的顺序取决于从 PD 获取时间戳的顺序。 + +处于可重复读隔离级别的事务不能并发的更新同一行，当时事务提交时发现该行在该事务启动后，已经被另一个已提交的事务更新过，那么该事务会回滚并启动自动重试。示例如下： + +```sql +create table t1(id int); +insert into t1 values(0); + +start transaction; | start transaction; +select * from t1; | select * from t1; +update t1 set id=id+1; | update t1 set id=id+1; +commit; | + | commit; -- 事务提交失败，回滚 +``` + +### 与 ANSI 可重复读隔离级别的区别 + +尽管名称是可重复读隔离级别，但是 TiDB 中可重复读隔离级别和 ANSI 可重复隔离级别是不同的。按照 [A Critique of ANSI SQL Isolation Levels](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf) 论文中的标准，TiDB 实现的是论文中的快照隔离级别。该隔离级别不会出现狭义上的幻读 (A3)，但不会阻止广义上的幻读 (P3)，同时，SI 还会出现写偏斜，而 ANSI 可重复读隔离级别不会出现写偏斜，会出现幻读。 + +### 与 MySQL 可重复读隔离级别的区别 + +MySQL 可重复读隔离级别在更新时并不检验当前版本是否可见，也就是说，即使该行在事务启动后被更新过，同样可以继续更新。这种情况在 TiDB 会导致事务回滚，导致事务最终失败，而 MySQL 是可以更新成功的。MySQL 的可重复读隔离级别并非 Snapshot 隔离级别，MySQL 可重复读隔离级别的一致性要弱于 Snapshot 隔离级别，也弱于 TiDB 的可重复读隔离级别。 + +## 读已提交隔离级别 (Read Committed) + +TiDB 仅在[悲观事务模式](/reference/transactions/transaction-pessimistic.md)下支持读已提交隔离级别。在乐观事务模式下设置事务隔离级别为读已提交将不会生效，事务将仍旧使用可重复读隔离级别。 + +由于历史原因，当前主流数据库的读已提交隔离级别本质上都是 Oracle 定义的一致性读隔离级别。TiDB 为了适应这一历史原因，悲观事务中的读已提交隔离级别的实质行为也是一致性读。 + +### 与 MySQL 读已提交隔离级别的区别 + +MySQL 的读已提交隔离级别大部分符合一致性读特性，但其中存在某些特例，如半一致性读 ([semi-consistent read](https://dev.mysql.com/doc/refman/8.0/en/innodb-transaction-isolation-levels.html))，TiDB 没有兼容这个特殊行为。 + +## 更多阅读 + +- [TiKV 的 MVCC (Multi-Version Concurrency Control) 机制](https://pingcap.com/blog-cn/mvcc-in-tikv/) \ No newline at end of file diff --git a/reference/transactions/transaction-optimistic.md b/reference/transactions/transaction-optimistic.md new file mode 100644 index 000000000000..115f2789ea4e --- /dev/null +++ b/reference/transactions/transaction-optimistic.md @@ -0,0 +1,178 @@ +--- +title: TiDB 乐观事务模型 +summary: 了解 TiDB 的乐观事务模型。 +category: reference +aliases: ['/docs-cn/dev/reference/transactions/transaction-model/'] +--- + +# TiDB 乐观事务模型 + +本文介绍 TiDB 乐观事务的原理，以及相关特性。本文假定你对 [TiDB 的整体架构](/architecture.md#tidb-整体架构)、[Percolator](https://www.usenix.org/legacy/event/osdi10/tech/full_papers/Peng.pdf) 事务模型以及事务的 [ACID 特性](/glossary.md#acid)都有一定了解。 + +TiDB 默认使用乐观事务模型，不会出现读写冲突，所有的读操作都不会被写操作阻塞。对于写写冲突，只有在客户端执行 `COMMIT` 时，才会触发两阶段提交并检测是否存在写写冲突。 + +> **注意：** +> +> 自 v3.0.8 开始，TiDB 默认使用[悲观事务模型](/reference/transactions/transaction-pessimistic.md)。但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 + +## 乐观事务原理 + +TiDB 中事务使用两阶段提交，流程如下： + +![TiDB 中的两阶段提交](/media/2pc-in-tidb.png) + +1. 客户端开始一个事务。 + + TiDB 从 PD 获取一个全局唯一递增的版本号作为当前事务的开始版本号，这里定义为该事务的 `start_ts` 版本。 + +2. 客户端发起读请求。 + + 1. TiDB 从 PD 获取数据路由信息，即数据具体存在哪个 TiKV 节点上。 + 2. TiDB 从 TiKV 获取 `start_ts` 版本下对应的数据信息。 + +3. 客户端发起写请求。 + + TiDB 校验写入数据是否符合一致性约束（如数据类型是否正确、是否符合唯一索引约束等）。**校验通过的数据将存放在内存里。** + +4. 客户端发起 commit。 + +5. TiDB 开始两阶段提交，保证分布式事务的原子性，让数据真正落盘。 + + 1. TiDB 从当前要写入的数据中选择一个 Key 作为当前事务的 Primary Key。 + 2. TiDB 从 PD 获取所有数据的写入路由信息，并将所有的 Key 按照所有的路由进行分类。 + 3. TiDB 并发地向所有涉及的 TiKV 发起 prewrite 请求。TiKV 收到 prewrite 数据后，检查数据版本信息是否存在冲突或已过期。符合条件的数据会被加锁。 + 4. TiDB 收到所有 prewrite 响应且所有 prewrite 都成功。 + 5. TiDB 向 PD 获取第二个全局唯一递增版本号，定义为本次事务的 `commit_ts`。 + 6. TiDB 向 Primary Key 所在 TiKV 发起第二阶段提交。TiKV 收到 commit 操作后，检查数据合法性，清理 prewrite 阶段留下的锁。 + 7. TiDB 收到两阶段提交成功的信息。 + +6. TiDB 向客户端返回事务提交成功的信息。 + +7. TiDB 异步清理本次事务遗留的锁信息。 + +## 优缺点分析 + +通过分析 TiDB 中事务的处理流程，可以发现 TiDB 事务有如下优点： + +* 实现原理简单，易于理解。 +* 基于单实例事务实现了跨节点事务。 +* 锁管理实现了去中心化。 + +但 TiDB 事务也存在以下缺点： + +* 两阶段提交使网络交互增多。 +* 需要一个中心化的版本管理服务。 +* 事务数据量过大时易导致内存暴涨。 + +实际应用中，你可以[根据事务的大小进行针对性处理](/reference/transactions/overview.md#事务大小)，以提高事务的执行效率。 + +## 事务的重试 + +使用乐观事务模型时，在高冲突率的场景中，事务很容易提交失败。而 MySQL 内部使用的是悲观事务模型，在执行 SQL 语句的过程中进行冲突检测，所以提交时很难出现异常。为了兼容 MySQL 的悲观事务行为，TiDB 提供了重试机制。 + +### 重试机制 + +当事务提交后，如果发现冲突，TiDB 内部重新执行包含写操作的 SQL 语句。你可以通过设置 `tidb_disable_txn_auto_retry = off` 开启自动重试，并通过 `tidb_retry_limit` 设置重试次数： + +```sql +# 设置是否禁用自动重试，默认为 “on”，即不重试。 +tidb_disable_txn_auto_retry = off +# 控制重试次数，默认为 “10”。只有自动重试启用时该参数才会生效。 +# 当 “tidb_retry_limit= 0” 时，也会禁用自动重试。 +tidb_retry_limit = 10 +``` + +你也可以修改当前 Session 或 Global 的值： + +- Session 级别设置： + + {{< copyable "sql" >}} + + ```sql + set @@tidb_disable_txn_auto_retry = off; + ``` + + {{< copyable "sql" >}} + + ```sql + set @@tidb_retry_limit = 10; + ``` + +- Global 级别设置： + + {{< copyable "sql" >}} + + ```sql + set @@global.tidb_disable_txn_auto_retry = off; + ``` + + {{< copyable "sql" >}} + + ```sql + set @@global.tidb_retry_limit = 10; + ``` + +> **注意：** +> +> `tidb_retry_limit` 变量决定了事务重试的最大次数。当它被设置为 0 时，所有事务都不会自动重试，包括自动提交的单语句隐式事务。这是彻底禁用 TiDB 中自动重试机制的方法。禁用自动重试后，所有冲突的事务都会以最快的方式上报失败信息 (`try again later`) 给应用层。 + +### 重试的局限性 + +TiDB 默认不进行事务重试，因为重试事务可能会导致更新丢失，从而破坏[可重复读的隔离级别](/reference/transactions/transaction-isolation.md)。 + +事务重试的局限性与其原理有关。事务重试可概括为以下三个步骤： + +1. 重新获取 `start_ts`。 +2. 重新执行包含写操作的 SQL 语句。 +3. 再次进行两阶段提交。 + +第二步中，重试时仅重新执行包含写操作的 SQL 语句，并不涉及读操作的 SQL 语句。但是当前事务中读到数据的时间与事务真正开始的时间发生了变化，写入的版本变成了重试时获取的 `start_ts` 而非事务一开始时获取的 `start_ts`。因此，当事务中存在依赖查询结果来更新的语句时，重试将无法保证事务原本可重复读的隔离级别，最终可能导致结果与预期出现不一致。 + +如果业务可以容忍事务重试导致的异常，或并不关注事务是否以可重复读的隔离级别来执行，则可以开启自动重试。 + +## 冲突检测 + +乐观事务下，检测底层数据是否存在写写冲突是一个很重要的操作。具体而言，TiKV 在 prewrite 阶段就需要读取数据进行检测。为了优化这一块性能，TiDB 集群会在内存里面进行一次冲突预检测。 + +作为一个分布式系统，TiDB 在内存中的冲突检测主要在两个模块进行： + +- TiDB 层。如果发现 TiDB 实例本身就存在写写冲突，那么第一个写入发出后，后面的写入已经清楚地知道自己冲突了，无需再往下层 TiKV 发送请求去检测冲突。 +- TiKV 层。主要发生在 prewrite 阶段。因为 TiDB 集群是一个分布式系统，TiDB 实例本身无状态，实例之间无法感知到彼此的存在，也就无法确认自己的写入与别的 TiDB 实例是否存在冲突，所以会在 TiKV 这一层检测具体的数据是否有冲突。 + +其中 TiDB 层的冲突检测可以根据场景需要选择打开或关闭，具体配置项如下： + +```toml +# 事务内存锁相关配置，当本地事务冲突比较多时建议开启。 +[txn-local-latches] +# 是否开启内存锁，默认为 false，即不开启。 +enabled = false +# Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。 +# 每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据）， +# 设置过小会导致变慢，性能下降。（默认为 2048000） +capacity = 2048000 +``` + +配置项 `capacity` 主要影响到冲突判断的正确性。在实现冲突检测时，不可能把所有的 Key 都存到内存里，所以真正存下来的是每个 Key 的 Hash 值。有 Hash 算法就有碰撞也就是误判的概率，这里可以通过配置 `capacity` 来控制 Hash 取模的值： + +* `capacity` 值越小，占用内存小，误判概率越大。 +* `capacity` 值越大，占用内存大，误判概率越小。 + +实际应用时，如果业务场景能够预判断写入不存在冲突（如导入数据操作），建议关闭冲突检测。 + +相应地，在 TiKV 层检测内存中是否存在冲突也有类似的机制。不同的是，TiKV 层的检测会更严格且不允许关闭，仅支持对 Hash 取模值进行配置： + +```toml +# scheduler 内置一个内存锁机制，防止同时对一个 Key 进行操作。 +# 每个 Key hash 到不同的 slot。（默认为 2048000） +scheduler-concurrency = 2048000 +``` + +此外，TiKV 支持监控等待 latch 的时间： + +![Scheduler latch wait duration](/media/optimistic-transaction-metric.png) + +当 `Scheduler latch wait duration` 的值特别高时，说明大量时间消耗在等待锁的请求上。如果不存在底层写入慢的问题，基本上可以判断该段时间内冲突比较多。 + +## 更多阅读 + +- [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/) \ No newline at end of file diff --git a/dev/reference/transactions/transaction-pessimistic.md b/reference/transactions/transaction-pessimistic.md similarity index 100% rename from dev/reference/transactions/transaction-pessimistic.md rename to reference/transactions/transaction-pessimistic.md diff --git a/dev/releases/11alpha.md b/releases/11alpha.md similarity index 100% rename from dev/releases/11alpha.md rename to releases/11alpha.md diff --git a/dev/releases/11beta.md b/releases/11beta.md similarity index 100% rename from dev/releases/11beta.md rename to releases/11beta.md diff --git a/dev/releases/2.0.10.md b/releases/2.0.10.md similarity index 100% rename from dev/releases/2.0.10.md rename to releases/2.0.10.md diff --git a/dev/releases/2.0.11.md b/releases/2.0.11.md similarity index 100% rename from dev/releases/2.0.11.md rename to releases/2.0.11.md diff --git a/dev/releases/2.0ga.md b/releases/2.0ga.md similarity index 100% rename from dev/releases/2.0ga.md rename to releases/2.0ga.md diff --git a/dev/releases/2.1.1.md b/releases/2.1.1.md similarity index 100% rename from dev/releases/2.1.1.md rename to releases/2.1.1.md diff --git a/dev/releases/2.1.10.md b/releases/2.1.10.md similarity index 100% rename from dev/releases/2.1.10.md rename to releases/2.1.10.md diff --git a/dev/releases/2.1.11.md b/releases/2.1.11.md similarity index 100% rename from dev/releases/2.1.11.md rename to releases/2.1.11.md diff --git a/dev/releases/2.1.12.md b/releases/2.1.12.md similarity index 100% rename from dev/releases/2.1.12.md rename to releases/2.1.12.md diff --git a/dev/releases/2.1.13.md b/releases/2.1.13.md similarity index 100% rename from dev/releases/2.1.13.md rename to releases/2.1.13.md diff --git a/dev/releases/2.1.14.md b/releases/2.1.14.md similarity index 100% rename from dev/releases/2.1.14.md rename to releases/2.1.14.md diff --git a/dev/releases/2.1.15.md b/releases/2.1.15.md similarity index 100% rename from dev/releases/2.1.15.md rename to releases/2.1.15.md diff --git a/dev/releases/2.1.16.md b/releases/2.1.16.md similarity index 100% rename from dev/releases/2.1.16.md rename to releases/2.1.16.md diff --git a/dev/releases/2.1.17.md b/releases/2.1.17.md similarity index 100% rename from dev/releases/2.1.17.md rename to releases/2.1.17.md diff --git a/dev/releases/2.1.18.md b/releases/2.1.18.md similarity index 100% rename from dev/releases/2.1.18.md rename to releases/2.1.18.md diff --git a/dev/releases/2.1.19.md b/releases/2.1.19.md similarity index 100% rename from dev/releases/2.1.19.md rename to releases/2.1.19.md diff --git a/dev/releases/2.1.2.md b/releases/2.1.2.md similarity index 100% rename from dev/releases/2.1.2.md rename to releases/2.1.2.md diff --git a/dev/releases/2.1.3.md b/releases/2.1.3.md similarity index 100% rename from dev/releases/2.1.3.md rename to releases/2.1.3.md diff --git a/dev/releases/2.1.4.md b/releases/2.1.4.md similarity index 100% rename from dev/releases/2.1.4.md rename to releases/2.1.4.md diff --git a/dev/releases/2.1.5.md b/releases/2.1.5.md similarity index 100% rename from dev/releases/2.1.5.md rename to releases/2.1.5.md diff --git a/dev/releases/2.1.6.md b/releases/2.1.6.md similarity index 100% rename from dev/releases/2.1.6.md rename to releases/2.1.6.md diff --git a/dev/releases/2.1.7.md b/releases/2.1.7.md similarity index 100% rename from dev/releases/2.1.7.md rename to releases/2.1.7.md diff --git a/dev/releases/2.1.8.md b/releases/2.1.8.md similarity index 100% rename from dev/releases/2.1.8.md rename to releases/2.1.8.md diff --git a/dev/releases/2.1.9.md b/releases/2.1.9.md similarity index 100% rename from dev/releases/2.1.9.md rename to releases/2.1.9.md diff --git a/dev/releases/2.1ga.md b/releases/2.1ga.md similarity index 100% rename from dev/releases/2.1ga.md rename to releases/2.1ga.md diff --git a/dev/releases/201.md b/releases/201.md similarity index 100% rename from dev/releases/201.md rename to releases/201.md diff --git a/dev/releases/202.md b/releases/202.md similarity index 100% rename from dev/releases/202.md rename to releases/202.md diff --git a/dev/releases/203.md b/releases/203.md similarity index 100% rename from dev/releases/203.md rename to releases/203.md diff --git a/dev/releases/204.md b/releases/204.md similarity index 100% rename from dev/releases/204.md rename to releases/204.md diff --git a/dev/releases/205.md b/releases/205.md similarity index 100% rename from dev/releases/205.md rename to releases/205.md diff --git a/dev/releases/206.md b/releases/206.md similarity index 100% rename from dev/releases/206.md rename to releases/206.md diff --git a/dev/releases/207.md b/releases/207.md similarity index 100% rename from dev/releases/207.md rename to releases/207.md diff --git a/dev/releases/208.md b/releases/208.md similarity index 100% rename from dev/releases/208.md rename to releases/208.md diff --git a/dev/releases/209.md b/releases/209.md similarity index 100% rename from dev/releases/209.md rename to releases/209.md diff --git a/dev/releases/21beta.md b/releases/21beta.md similarity index 100% rename from dev/releases/21beta.md rename to releases/21beta.md diff --git a/dev/releases/21rc1.md b/releases/21rc1.md similarity index 100% rename from dev/releases/21rc1.md rename to releases/21rc1.md diff --git a/dev/releases/21rc2.md b/releases/21rc2.md similarity index 100% rename from dev/releases/21rc2.md rename to releases/21rc2.md diff --git a/dev/releases/21rc3.md b/releases/21rc3.md similarity index 100% rename from dev/releases/21rc3.md rename to releases/21rc3.md diff --git a/dev/releases/21rc4.md b/releases/21rc4.md similarity index 100% rename from dev/releases/21rc4.md rename to releases/21rc4.md diff --git a/releases/21rc5.md b/releases/21rc5.md new file mode 100644 index 000000000000..801e823b1a85 --- /dev/null +++ b/releases/21rc5.md @@ -0,0 +1,64 @@ +--- +title: TiDB 2.1 RC5 Release Notes +category: Releases +--- + + + +# TiDB 2.1 RC5 Release Notes + +2018 年 11 月 12 日，TiDB 发布 2.1 RC5 版。相比 2.1 RC4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 + +## TiDB + ++ SQL 优化器 + - 修复 `IndexReader` 在某些情况下读取的 handle 不正确的问题 [#8132](https://github.com/pingcap/tidb/pull/8132) + - 修复 `IndexScan Prepared` 语句在使用 `Plan Cache` 的时候的问题 [#8055](https://github.com/pingcap/tidb/pull/8055) + - 修复 `Union` 语句结果不稳定的问题 [#8165](https://github.com/pingcap/tidb/pull/8165) ++ 执行器 + - 提升 TiDB 插入和更新宽表的性能 [#8024](https://github.com/pingcap/tidb/pull/8024) + - 内建函数 `Truncate` 支持 unsigned `int` 参数 [#8068](https://github.com/pingcap/tidb/pull/8068) + - 修复转换 JSON 数据到 decimal 类型出错的问题 [#8109](https://github.com/pingcap/tidb/pull/8109) + - 修复 float 类型在 `Update` 时出错的问题 [#8170](https://github.com/pingcap/tidb/pull/8170) ++ 统计信息 + - 修复点查在某些情况下，统计信息出现错误的问题 [#8035](https://github.com/pingcap/tidb/pull/8035) + - 修复统计信息某些情况下在 primary key 的选择率的问题 [#8149](https://github.com/pingcap/tidb/pull/8149) + - 修复被删除的表的统计信息长时间没有清理的问题 [#8182](https://github.com/pingcap/tidb/pull/8182) ++ Server + + 提升日志的可读性，完善日志信息 + - [#8063](https://github.com/pingcap/tidb/pull/8063) + - [#8053](https://github.com/pingcap/tidb/pull/8053) + - [#8224](https://github.com/pingcap/tidb/pull/8224) + - 修复获取 `infoschema.profiling` 表数据出错的问题 [#8096](https://github.com/pingcap/tidb/pull/8096) + - 替换 unix socket，使用 pumps client 来写 binlog [#8098](https://github.com/pingcap/tidb/pull/8098) + - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 [#8094](https://github.com/pingcap/tidb/pull/8094) + - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 [#8200](https://github.com/pingcap/tidb/pull/8200) + - 增加环境变量 `tidb_opt_write_row_id` 来控制是否允许写入 `_tidb_rowid` [#8218](https://github.com/pingcap/tidb/pull/8218) + - ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8081](https://github.com/pingcap/tidb/pull/8081)，[#8247](https://github.com/pingcap/tidb/pull/8247) ++ DDL + - 修复在事务中某些情况下执行 DDL 语句出错的问题 [#8056](https://github.com/pingcap/tidb/pull/8056) + - 修复 partition 分区表执行 `truncate table` 没有生效的问题 [#8103](https://github.com/pingcap/tidb/pull/8103) + - 修复某些情况下 DDL 操作在被 cancel 之后没有正确回滚的问题 [#8057](https://github.com/pingcap/tidb/pull/8057) + - 增加命令 `admin show next_row_id`，返回下一个可用的行 ID [#8268](https://github.com/pingcap/tidb/pull/8268) + +## PD + ++ 修复 `pd-ctl` 读取 Region key 的相关问题 + - [#1298](https://github.com/pingcap/pd/pull/1298) + - [#1299](https://github.com/pingcap/pd/pull/1299) + - [#1308](https://github.com/pingcap/pd/pull/1308) + +- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) +- 修复 PD join 失败后无法重新 join 的问题 [#1279](https://github.com/pingcap/pd/pull/1279) +- 修复某些情况下 watch leader 会丢失事件的问题 [#1317](https://github.com/pingcap/pd/pull/1317) + +## TiKV + +- 优化 `WriteConflict` 报错信息 [#3750](https://github.com/tikv/tikv/pull/3750) +- 增加 panic 标记文件 [#3746](https://github.com/tikv/tikv/pull/3746) +- 降级 grpcio，避免新版本 gRPC 导致的 segment fault 问题 [#3650](https://github.com/tikv/tikv/pull/3650) +- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) + +## Tools + +- TiDB 支持 TiDB Binlog cluster，不兼容旧版本 TiDB Binlog [#8093](https://github.com/pingcap/tidb/pull/8093)，[使用文档](/reference/tidb-binlog/overview.md) diff --git a/dev/releases/2rc1.md b/releases/2rc1.md similarity index 100% rename from dev/releases/2rc1.md rename to releases/2rc1.md diff --git a/dev/releases/2rc3.md b/releases/2rc3.md similarity index 100% rename from dev/releases/2rc3.md rename to releases/2rc3.md diff --git a/dev/releases/2rc4.md b/releases/2rc4.md similarity index 100% rename from dev/releases/2rc4.md rename to releases/2rc4.md diff --git a/dev/releases/2rc5.md b/releases/2rc5.md similarity index 100% rename from dev/releases/2rc5.md rename to releases/2rc5.md diff --git a/dev/releases/3.0-ga.md b/releases/3.0-ga.md similarity index 100% rename from dev/releases/3.0-ga.md rename to releases/3.0-ga.md diff --git a/dev/releases/3.0.0-beta.1.md b/releases/3.0.0-beta.1.md similarity index 100% rename from dev/releases/3.0.0-beta.1.md rename to releases/3.0.0-beta.1.md diff --git a/dev/releases/3.0.0-rc.1.md b/releases/3.0.0-rc.1.md similarity index 100% rename from dev/releases/3.0.0-rc.1.md rename to releases/3.0.0-rc.1.md diff --git a/dev/releases/3.0.0-rc.2.md b/releases/3.0.0-rc.2.md similarity index 100% rename from dev/releases/3.0.0-rc.2.md rename to releases/3.0.0-rc.2.md diff --git a/dev/releases/3.0.0-rc.3.md b/releases/3.0.0-rc.3.md similarity index 100% rename from dev/releases/3.0.0-rc.3.md rename to releases/3.0.0-rc.3.md diff --git a/dev/releases/3.0.1.md b/releases/3.0.1.md similarity index 100% rename from dev/releases/3.0.1.md rename to releases/3.0.1.md diff --git a/dev/releases/3.0.10.md b/releases/3.0.10.md similarity index 100% rename from dev/releases/3.0.10.md rename to releases/3.0.10.md diff --git a/dev/releases/3.0.2.md b/releases/3.0.2.md similarity index 100% rename from dev/releases/3.0.2.md rename to releases/3.0.2.md diff --git a/dev/releases/3.0.3.md b/releases/3.0.3.md similarity index 100% rename from dev/releases/3.0.3.md rename to releases/3.0.3.md diff --git a/dev/releases/3.0.4.md b/releases/3.0.4.md similarity index 100% rename from dev/releases/3.0.4.md rename to releases/3.0.4.md diff --git a/dev/releases/3.0.5.md b/releases/3.0.5.md similarity index 100% rename from dev/releases/3.0.5.md rename to releases/3.0.5.md diff --git a/dev/releases/3.0.6.md b/releases/3.0.6.md similarity index 100% rename from dev/releases/3.0.6.md rename to releases/3.0.6.md diff --git a/dev/releases/3.0.7.md b/releases/3.0.7.md similarity index 100% rename from dev/releases/3.0.7.md rename to releases/3.0.7.md diff --git a/releases/3.0.8.md b/releases/3.0.8.md new file mode 100644 index 000000000000..e7aced918195 --- /dev/null +++ b/releases/3.0.8.md @@ -0,0 +1,112 @@ +--- +title: TiDB 3.0.8 Release Notes +category: Releases +--- + +# TiDB 3.0.8 Release Notes + +发版日期：2019 年 12 月 31 日 + +TiDB 版本：3.0.8 + +TiDB Ansible 版本：3.0.8 + +## TiDB + ++ SQL 优化器 + - 修复 SQL Binding 因为 cache 更新不及时，导致绑定计划错误的问题 [#13891](https://github.com/pingcap/tidb/pull/13891) + - 修复当 SQL 包含符号列表（类似于 "?, ?, ?" 这样的占位符）时，SQL Binding 可能失效的问题 [#14004](https://github.com/pingcap/tidb/pull/14004) + - 修复 SQL Binding 由于原 SQL 以 `;` 结尾而不能创建/删除的问题 [#14113](https://github.com/pingcap/tidb/pull/14113) + - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14133](https://github.com/pingcap/tidb/pull/14133) + - 移除 `minAutoAnalyzeRatio` 约束使自动 analyze 更及时 [#14015](https://github.com/pingcap/tidb/pull/14015) ++ SQL 执行引擎 + - 修复 `INSERT/REPLACE/UPDATE ... SET ... = DEFAULT` 语法会报错的问题，修复 `DEFAULT` 表达式与虚拟生成列配合使用会报错的问题 [#13682](https://github.com/pingcap/tidb/pull/13682) + - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14011](https://github.com/pingcap/tidb/pull/14011) + - 修复 `HashAgg` Executor 并发值未被正确初始化，导致聚合操作执行在一些情况下效率低的问题 [#13811](https://github.com/pingcap/tidb/pull/13811) + - 修复 group by item 被括号包含时执行报错的问题 [#13658](https://github.com/pingcap/tidb/pull/13658) + - 修复 TiDB 没有正确计算 group by item，导致某些情况下 OUTER JOIN 执行会报错的问题 [#14014](https://github.com/pingcap/tidb/pull/14014) + - 修复向 Range 分区表写入超过 Range 外的数据时，报错信息不准确的问题 [#14107](https://github.com/pingcap/tidb/pull/14107) + - 鉴于 MySQL 8 即将废弃 `PadCharToFullLength`，revert PR [#10124](https://github.com/pingcap/tidb/pull/10124) 并撤销 `PadCharToFullLength` 的效果，以避免一些特殊情况下查询结果不符合预期 [#14157](https://github.com/pingcap/tidb/pull/14157) + - 修复 `ExplainExec` 中没有保证 `close()` 的调用而导致 `EXPLAIN ANALYZE` 时造成 goroutine 泄露的问题 [#14226](https://github.com/pingcap/tidb/pull/14226) ++ DDL + - 优化 "change column"/"modify column" 的输出的报错信息，让人更容易理解 [#13796](https://github.com/pingcap/tidb/pull/13796) + - 新增 `SPLIT PARTITION TABLE` 语法，支持分区表切分 Region 功能 [#13929](https://github.com/pingcap/tidb/pull/13929) + - 修复创建索引时，没有正确检查长度，导致索引长度超过 3072 字节没有报错的问题 [#13779](https://github.com/pingcap/tidb/pull/13779) + - 修复由于分区表添加索引时若花费时间过长，可能导致输出 `GC life time is shorter than transaction duration` 报错信息的问题 [#14132](https://github.com/pingcap/tidb/pull/14132) + - 修复在 `DROP COLUMN`/`MODIFY COLUMN`/`CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14105](https://github.com/pingcap/tidb/pull/14105) ++ Server + - Statement Summary 功能改进： + - 新增大量的 SQL 指标字段，便于对 SQL 进行更详细的统计分析 [#14151](https://github.com/pingcap/tidb/pull/14151)，[#14168](https://github.com/pingcap/tidb/pull/14168) + - 新增 `stmt-summary.refresh-interval` 参数用于控制定期将 `events_statements_summary_by_digest` 表中过期的数据移到 `events_statements_summary_by_digest_history` 表，默认间隔时间：30min [#14161](https://github.com/pingcap/tidb/pull/14161) + - 新增 `events_statements_summary_by_digest_history` 表，保存从 `events_statements_summary_by_digest` 中过期的数据 [#14166](https://github.com/pingcap/tidb/pull/14166) + - 修复执行 RBAC 相关的内部 SQL 时，错误输出 binlog 的问题 [#13890](https://github.com/pingcap/tidb/pull/13890) + - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13906](https://github.com/pingcap/tidb/pull/13906) + - 新增通过 HTTP 接口恢复 TiDB binlog 写入功能 [#13892](https://github.com/pingcap/tidb/pull/13892) + - 将 `GRANT roles TO user` 所需要的权限由 `GrantPriv` 修改为 `ROLE_ADMIN` 或 `SUPER`，以与 MySQL 保持一致 [#13932](https://github.com/pingcap/tidb/pull/13932) + - 当 `GRANT` 语句未指定 database 名时，TiDB 行为由使用当前 database 改为报错 `No database selected`，与 MySQL 保持兼容 [#13784](https://github.com/pingcap/tidb/pull/13784) + - 修改 `REVOKE` 语句执行权限从 `SuperPriv` 改成用户只需要有对应 Schema 的权限，就可以执行 `REVOKE` 语句，与 MySQL 保持一致 [#13306](https://github.com/pingcap/tidb/pull/13306) + - 修复 `GRANT ALL` 语法在没有 `WITH GRANT OPTION` 时，错误地将 `GrantPriv` 授权给目标用户的问题 [#13943](https://github.com/pingcap/tidb/pull/13943) + - 修复 `LoadDataInfo` 中调用 `addRecord` 报错时，报错信息不包含导致 `LOAD DATA` 语句行为不正确信息的问题 [#13980](https://github.com/pingcap/tidb/pull/13980) + - 修复因查询中多个 SQL 语句共用同一个 `StartTime` 导致输出错误的慢查询信息的问题 [#13898](https://github.com/pingcap/tidb/pull/13898) + - 修复 `batchClient` 处理大事务时可能造成内存泄露的问题 [#14032](https://github.com/pingcap/tidb/pull/14032) + - 修复 `system_time_zone` 固定显示为 `CST` 的问题，现在 TiDB 的 `system_time_zone` 会从 `mysql.tidb` 表中的 `systemTZ` 获取 [#14086](https://github.com/pingcap/tidb/pull/14086) + - 修复 `GRANT ALL` 语法授予权限不完整（例如 `Lock_tables_priv`）的问题 [#14092](https://github.com/pingcap/tidb/pull/14092) + - 修复 `Priv_create_user` 权限不能 `CREATE ROLE` 和 `DROP ROLE`的问题 [#14088](https://github.com/pingcap/tidb/pull/14088) + - 将 `ErrInvalidFieldSize` 的错误码从 `1105(Unknow Error)` 改成 `3013` [#13737](https://github.com/pingcap/tidb/pull/13737) + - 新增 `SHUTDOWN` 命令用于停止 TiDB Server，并新增 `ShutdownPriv` 权限 [#14104](https://github.com/pingcap/tidb/pull/14104) + - 修复 `DROP ROLE` 语句的原子性问题，避免语句执行失败时，一些 ROLE 仍然被非预期地删除 [#14130](https://github.com/pingcap/tidb/pull/14130) + - 修复 3.0 以下版本升级到 3.0 时，`tidb_enable_window_function` 在 `SHOW VARIABLE` 语句的查询结果错误输出 1 的问题，修复后输出 0 [#14131](https://github.com/pingcap/tidb/pull/14131) + - 修复 TiKV 节点下线时，由于 `gcworker` 持续重试导致可能出现 goroutine 泄露的问题 [#14106](https://github.com/pingcap/tidb/pull/14106) + - 在慢日志中记录 Binlog 的 `Prewrite` 的时间，提升问题追查的易用性 [#14138](https://github.com/pingcap/tidb/pull/14138) + - `tidb_enable_table_partition` 变量支持 GLOBAL SCOPE 作用域 [#14091](https://github.com/pingcap/tidb/pull/14091) + - 修复新增权限时未正确将新增的权限赋予对应的用户导致用户权限可能缺失或者被误添加的问题 [#14178](https://github.com/pingcap/tidb/pull/14178) + - 修复当 TiKV 链接断开时，由于 `rpcClient` 不会关闭而导致 `CheckStreamTimeoutLoop` goroutine 会泄露的问题 [#14227](https://github.com/pingcap/tidb/pull/14227) + - 支持基于证书的身份验证（[使用文档](/reference/security/cert-based-authentication.md)）[#13955](https://github.com/pingcap/tidb/pull/13955) ++ Transaction + - 创建新集群时，`tidb_txn_mode` 变量的默认值由 `""` 改为 `"pessimistic"` [#14171](https://github.com/pingcap/tidb/pull/14171) + - 修复悲观事务模式，事务重试时单条语句的等锁时间没有被重置导致等锁时间过长的问题 [#13990](https://github.com/pingcap/tidb/pull/13990) + - 修复悲观事务模式，因对没有修改的数据未加锁导致可能读到不正确数据的问题 [#14050](https://github.com/pingcap/tidb/pull/14050) + - 修复 mocktikv 中 prewrite 时，没有区分事务类型，导致重复的 insert value 约束检查 [#14175](https://github.com/pingcap/tidb/pull/14175) + - 修复 `session.TxnState` 状态为 `Invalid` 时，事务没有被正确处理导致 panic 的问题 [#13988](https://github.com/pingcap/tidb/pull/13988) + - 修复 mocktikv 中 `ErrConfclit` 结构未包含 `ConflictCommitTS` 的问题 [#14080](https://github.com/pingcap/tidb/pull/14080) + - 修复 TiDB 在 Resolve Lock 之后，没有正确处理锁超时检查导致事务卡住的问题 [#14083](https://github.com/pingcap/tidb/pull/14083) ++ Monitor + - `LockKeys` 新增 `pessimistic_lock_keys_duration` 监控 [#14194](https://github.com/pingcap/tidb/pull/14194) + +## TiKV + ++ Coprocessor + - 修改 Coprocessor 遇到错误时输出日志的级别从 `error` 改成 `warn` [#6051](https://github.com/tikv/tikv/pull/6051) + - 修改统计信息采样数据的更新行为从直接更行改成先删除再插入，更新行为与 tidb-server 保持一致 [#6069](https://github.com/tikv/tikv/pull/6096) ++ Raftstore + - 修复因重复向 `peerfsm` 发送 destory 消息，`peerfsm` 被多次销毁导致 panic 的问题 [#6297](https://github.com/tikv/tikv/pull/6297) + - `split-region-on-table` 默认值由 `true` 改成 `false`，默认关闭按 table 切分 Region 的功能 [#6253](https://github.com/tikv/tikv/pull/6253) ++ Engine + - 修复极端条件下因 RocksDB 迭代器错误未正确处理导致可能返回空数据的问题 [#6326](https://github.com/tikv/tikv/pull/6326) ++ 事务 + - 修复悲观锁因锁未被正确清理导致 Key 无法写入数据，且出现 GC 卡住的问题 [#6354](https://github.com/tikv/tikv/pull/6354) + - 优化悲观锁等锁机制，提升锁冲突严重场景的性能 [#6296](https://github.com/tikv/tikv/pull/6296) ++ 将内存分配库的默认值由 `tikv_alloc/default` 改成 `jemalloc` [#6206](https://github.com/tikv/tikv/pull/6206) + +## PD + +- Client + - 新增通过 `context` 创建新 client，创建新 client 时可设置超时时间 [#1994](https://github.com/pingcap/pd/pull/1994) + - 新增创建 `KeepAlive` 连接功能 [#2035](https://github.com/pingcap/pd/pull/2035) +- 优化`/api/v1/regions` API 的性能 [#1986](https://github.com/pingcap/pd/pull/1986) +- 修复删除 `tombstone` 状态的 Store 可能会导致 panic 的隐患 [#2038](https://github.com/pingcap/pd/pull/2038) +- 修复从磁盘加载 Region 信息时错误的将范围有重叠的 Region 删除的问题 [#2011](https://github.com/pingcap/pd/issues/2011)，[#2040](https://github.com/pingcap/pd/pull/2040) +- 将 etcd 版本从 3.4.0 升级到 3.4.3 稳定版本，注意升级后只能通过 pd-recover 工具降级 [#2058](https://github.com/pingcap/pd/pull/2058) + +## Tools + ++ TiDB Binlog + - 修复 Pump 由于没有收到 DDL 的 commit binlog 导致 binlog 被忽略的问题 [#853](https://github.com/pingcap/tidb-binlog/pull/853) + +## TiDB Ansible + +- 回滚被精简的配置项 [#1053](https://github.com/pingcap/tidb-ansible/pull/1053) +- 优化滚动升级时 TiDB 版本检查的逻辑 [#1056](https://github.com/pingcap/tidb-ansible/pull/1056) +- TiSpark 版本升级到 2.1.8 [#1061](https://github.com/pingcap/tidb-ansible/pull/1061) +- 修复 Grafana 监控上 PD 页面 Role 监控项显示不正确的问题 [#1065](https://github.com/pingcap/tidb-ansible/pull/1065) +- 优化 Grafana 监控上 TiKV Detail 页面上 `Thread Voluntary Context Switches` 和 `Thread Nonvoluntary Context Switches` 监控项 [#1071](https://github.com/pingcap/tidb-ansible/pull/1071) diff --git a/dev/releases/3.0.9.md b/releases/3.0.9.md similarity index 100% rename from dev/releases/3.0.9.md rename to releases/3.0.9.md diff --git a/dev/releases/3.0beta.md b/releases/3.0beta.md similarity index 100% rename from dev/releases/3.0beta.md rename to releases/3.0beta.md diff --git a/dev/releases/3.1.0-beta.1.md b/releases/3.1.0-beta.1.md similarity index 100% rename from dev/releases/3.1.0-beta.1.md rename to releases/3.1.0-beta.1.md diff --git a/dev/releases/3.1.0-beta.md b/releases/3.1.0-beta.md similarity index 100% rename from dev/releases/3.1.0-beta.md rename to releases/3.1.0-beta.md diff --git a/dev/releases/4.0.0-beta.md b/releases/4.0.0-beta.md similarity index 100% rename from dev/releases/4.0.0-beta.md rename to releases/4.0.0-beta.md diff --git a/dev/releases/ga.md b/releases/ga.md similarity index 100% rename from dev/releases/ga.md rename to releases/ga.md diff --git a/dev/releases/prega.md b/releases/prega.md similarity index 100% rename from dev/releases/prega.md rename to releases/prega.md diff --git a/dev/releases/rc1.md b/releases/rc1.md similarity index 100% rename from dev/releases/rc1.md rename to releases/rc1.md diff --git a/dev/releases/rc2.md b/releases/rc2.md similarity index 100% rename from dev/releases/rc2.md rename to releases/rc2.md diff --git a/dev/releases/rc3.md b/releases/rc3.md similarity index 100% rename from dev/releases/rc3.md rename to releases/rc3.md diff --git a/dev/releases/rc4.md b/releases/rc4.md similarity index 100% rename from dev/releases/rc4.md rename to releases/rc4.md diff --git a/releases/rn.md b/releases/rn.md new file mode 100644 index 000000000000..f858276d84a1 --- /dev/null +++ b/releases/rn.md @@ -0,0 +1,95 @@ +--- +title: TiDB 版本发布历史 +category: release +--- + +# TiDB 版本发布历史 + +TiDB 历史版本发布声明如下： + +## 4.0 + +- [4.0.0-beta](/releases/4.0.0-beta.md) + +## 3.1 + +- [3.1.0-beta.1](/releases/3.1.0-beta.1.md) +- [3.1.0-beta](/releases/3.1.0-beta.md) + +## 3.0 + +- [3.0.10](/releases/3.0.10.md) +- [3.0.9](/releases/3.0.9.md) +- [3.0.8](/releases/3.0.8.md) +- [3.0.7](/releases/3.0.7.md) +- [3.0.6](/releases/3.0.6.md) +- [3.0.5](/releases/3.0.5.md) +- [3.0.4](/releases/3.0.4.md) +- [3.0.3](/releases/3.0.3.md) +- [3.0.2](/releases/3.0.2.md) +- [3.0.1](/releases/3.0.1.md) +- [3.0 GA](/releases/3.0-ga.md) +- [3.0.0-rc.3](/releases/3.0.0-rc.3.md) +- [3.0.0-rc.2](/releases/3.0.0-rc.2.md) +- [3.0.0-rc.1](/releases/3.0.0-rc.1.md) +- [3.0.0-beta.1](/releases/3.0.0-beta.1.md) +- [3.0.0-beta](/releases/3.0beta.md) + +## 2.1 + +- [2.1.19](/releases/2.1.19.md) +- [2.1.18](/releases/2.1.18.md) +- [2.1.17](/releases/2.1.17.md) +- [2.1.16](/releases/2.1.16.md) +- [2.1.15](/releases/2.1.15.md) +- [2.1.14](/releases/2.1.14.md) +- [2.1.13](/releases/2.1.13.md) +- [2.1.12](/releases/2.1.12.md) +- [2.1.11](/releases/2.1.11.md) +- [2.1.10](/releases/2.1.10.md) +- [2.1.9](/releases/2.1.9.md) +- [2.1.8](/releases/2.1.8.md) +- [2.1.7](/releases/2.1.7.md) +- [2.1.6](/releases/2.1.6.md) +- [2.1.5](/releases/2.1.5.md) +- [2.1.4](/releases/2.1.4.md) +- [2.1.3](/releases/2.1.3.md) +- [2.1.2](/releases/2.1.2.md) +- [2.1.1](/releases/2.1.1.md) +- [2.1 GA](/releases/2.1ga.md) +- [2.1 RC5](/releases/21rc5.md) +- [2.1 RC4](/releases/21rc4.md) +- [2.1 RC3](/releases/21rc3.md) +- [2.1 RC2](/releases/21rc2.md) +- [2.1 RC1](/releases/21rc1.md) +- [2.1 Beta](/releases/21beta.md) + +## 2.0 + +- [2.0.11](/releases/2.0.11.md) +- [2.0.10](/releases/2.0.10.md) +- [2.0.9](/releases/209.md) +- [2.0.8](/releases/208.md) +- [2.0.7](/releases/207.md) +- [2.0.6](/releases/206.md) +- [2.0.5](/releases/205.md) +- [2.0.4](/releases/204.md) +- [2.0.3](/releases/203.md) +- [2.0.2](/releases/202.md) +- [2.0.1](/releases/201.md) +- [2.0](/releases/2.0ga.md) +- [2.0 RC5](/releases/2rc5.md) +- [2.0 RC4](/releases/2rc4.md) +- [2.0 RC3](/releases/2rc3.md) +- [2.0 RC1](/releases/2rc1.md) +- [1.1 Beta](/releases/11beta.md) +- [1.1 Alpha](/releases/11alpha.md) + +## 1.0 + +- [1.0](/releases/ga.md) +- [Pre-GA](/releases/prega.md) +- [RC4](/releases/rc4.md) +- [RC3](/releases/rc3.md) +- [RC2](/releases/rc2.md) +- [RC1](/releases/rc1.md) diff --git a/dev/report-issue.md b/report-issue.md similarity index 100% rename from dev/report-issue.md rename to report-issue.md diff --git a/dev/roadmap.md b/roadmap.md similarity index 100% rename from dev/roadmap.md rename to roadmap.md diff --git a/dev/support-resources.md b/support-resources.md similarity index 100% rename from dev/support-resources.md rename to support-resources.md diff --git a/dev/tidb-in-kubernetes/deploy/access-tidb.md b/tidb-in-kubernetes/deploy/access-tidb.md similarity index 100% rename from dev/tidb-in-kubernetes/deploy/access-tidb.md rename to tidb-in-kubernetes/deploy/access-tidb.md diff --git a/tidb-in-kubernetes/deploy/alibaba-cloud.md b/tidb-in-kubernetes/deploy/alibaba-cloud.md new file mode 100644 index 000000000000..bbfec07787c4 --- /dev/null +++ b/tidb-in-kubernetes/deploy/alibaba-cloud.md @@ -0,0 +1,352 @@ +--- +title: 在阿里云上部署 TiDB 集群 +category: how-to +--- + +# 在阿里云上部署 TiDB 集群 + +本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在阿里云上部署 TiDB 集群。 + +## 环境需求 + +- [aliyun-cli](https://github.com/aliyun/aliyun-cli) >= 3.0.15 并且[配置 aliyun-cli](https://www.alibabacloud.com/help/doc-detail/90766.htm?spm=a2c63.l28256.a3.4.7b52a893EFVglq) + + > **注意：** + > + > Access Key 需要具有操作相应资源的权限。 + +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.12 +- [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.1 且 <= 2.11.0 +- [jq](https://stedolan.github.io/jq/download/) >= 1.6 +- [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) 0.12.* + +你可以使用阿里云的[云命令行](https://shell.aliyun.com)服务来进行操作，云命令行中已经预装并配置好了所有工具。 + +### 权限 + +完整部署集群需要具备以下权限： + +- AliyunECSFullAccess +- AliyunESSFullAccess +- AliyunVPCFullAccess +- AliyunSLBFullAccess +- AliyunCSFullAccess +- AliyunEIPFullAccess +- AliyunECIFullAccess +- AliyunVPNGatewayFullAccess +- AliyunNATGatewayFullAccess + +## 概览 + +默认配置下，会创建： + +- 一个新的 VPC +- 一台 ECS 实例作为堡垒机 +- 一个托管版 ACK（阿里云 Kubernetes）集群以及一系列 worker 节点： + - 属于一个伸缩组的 2 台 ECS 实例（2 核 2 GB）托管版 Kubernetes 的默认伸缩组中必须至少有两台实例，用于承载整个的系统服务，例如 CoreDNS + - 属于一个伸缩组的 3 台 `ecs.g5.large` 实例，用于部署 PD + - 属于一个伸缩组的 3 台 `ecs.i2.2xlarge` 实例，用于部署 TiKV + - 属于一个伸缩组的 2 台 `ecs.c5.4xlarge` 实例用于部署 TiDB + - 属于一个伸缩组的 1 台 `ecs.c5.xlarge` 实例用于部署监控组件 + - 一块 100 GB 的云盘用作监控数据存储 + +除了默认伸缩组之外的其它所有实例都是跨可用区部署的。而伸缩组 (Auto-scaling Group) 能够保证集群的健康实例数等于期望数值。因此，当发生节点故障甚至可用区故障时，伸缩组能够自动为我们创建新实例来确保服务可用性。 + +## 安装部署 + +1. 设置目标 Region 和阿里云密钥（也可以在运行 `terraform` 命令时根据命令提示输入）： + + {{< copyable "shell-regular" >}} + + ```shell + export TF_VAR_ALICLOUD_REGION= && \ + export TF_VAR_ALICLOUD_ACCESS_KEY= && \ + export TF_VAR_ALICLOUD_SECRET_KEY= + ``` + + 用于部署集群的各变量的默认值存储在 `variables.tf` 文件中，如需定制可以修改此文件或在安装时通过 `-var` 参数覆盖。 + +2. 使用 Terraform 进行安装： + + {{< copyable "shell-regular" >}} + + ```shell + git clone --depth=1 https://github.com/pingcap/tidb-operator && \ + cd tidb-operator/deploy/aliyun + ``` + + {{< copyable "shell-regular" >}} + + ```shell + terraform init + ``` + + `apply` 过程中需要输入 `yes` 来确认执行： + + {{< copyable "shell-regular" >}} + + ```shell + terraform apply + ``` + + 假如在运行 `terraform apply` 时出现报错，可根据报错信息（例如缺少权限）进行修复后再次运行 `terraform apply`。 + + 整个安装过程大约需要 5 至 10 分钟，安装完成后会输出集群的关键信息（想要重新查看这些信息，可以运行 `terraform output`）： + + ``` + Apply complete! Resources: 3 added, 0 changed, 1 destroyed. + + Outputs: + + bastion_ip = 47.96.174.214 + cluster_id = c2d9b20854a194f158ef2bc8ea946f20e + kubeconfig_file = /tidb-operator/deploy/aliyun/credentials/kubeconfig + monitor_endpoint = 121.199.195.236:3000 + region = cn-hangzhou + ssh_key_file = /tidb-operator/deploy/aliyun/credentials/my-cluster-keyZ.pem + tidb_endpoint = 172.21.5.171:4000 + tidb_version = v3.0.0 + vpc_id = vpc-bp1v8i5rwsc7yh8dwyep5 + ``` + +3. 用 `kubectl` 或 `helm` 对集群进行操作： + + {{< copyable "shell-regular" >}} + + ```shell + export KUBECONFIG=$PWD/credentials/kubeconfig + ``` + + {{< copyable "shell-regular" >}} + + ```shell + kubectl version + ``` + + {{< copyable "shell-regular" >}} + + ```shell + helm ls + ``` + +## 连接数据库 + +通过堡垒机可连接 TiDB 集群进行测试，相关信息在安装完成后的输出中均可找到： + +{{< copyable "shell-regular" >}} + +```shell +ssh -i credentials/-key.pem root@ +``` + +{{< copyable "shell-regular" >}} + +```shell +mysql -h -P 4000 -u root +``` + +## 监控 + +访问 `` 就可以查看相关的 Grafana 监控面板。相关信息可在安装完成后的输出中找到。默认帐号密码为： + +- 用户名：admin +- 密码：admin + +> **警告：** +> +> 出于安全考虑，假如你已经或将要配置 VPN 用于访问 VPC，强烈建议将 `deploy/modules/aliyun/tidb-cluster/values/default.yaml` 文件里 `monitor.grafana.service.annotations` 中的 `service.beta.kubernetes.io/alicloud-loadbalancer-address-type` 设置为 `intranet` 以禁止监控服务的公网访问。 + +## 升级 TiDB 集群 + +设置 `variables.tf` 中的 `tidb_version` 参数，并再次运行 `terraform apply` 即可完成升级。 + +升级操作可能会执行较长时间，可以通过以下命令来持续观察进度： + +{{< copyable "shell-regular" >}} + +``` +kubectl get pods --namespace -o wide --watch +``` + +## TiDB 集群水平伸缩 + +按需修改 `variables.tf` 中的 `tikv_count` 和 `tidb_count` 数值，再次运行 `terraform apply` 即可完成 TiDB 集群的水平伸缩。 + +## 销毁集群 + +{{< copyable "shell-regular" >}} + +```shell +terraform destroy +``` + +假如 Kubernetes 集群没有创建成功，那么在 destroy 时会出现报错，无法进行正常清理。此时需要手动将 Kubernetes 资源从本地状态中移除： + +{{< copyable "shell-regular" >}} + +```shell +terraform state list +``` + +{{< copyable "shell-regular" >}} + +```shell +terraform state rm module.ack.alicloud_cs_managed_kubernetes.k8s +``` + +销毁集群操作需要执行较长时间。 + +> **注意：** +> +> 监控组件挂载的云盘需要在阿里云管理控制台中手动删除。 + +## 配置 + +### 配置 TiDB Operator + +通过调整 `variables.tf` 内的值来配置 TiDB Operator，大多数配置项均能按照 `variable` 的注释理解语义后进行修改。需要注意的是，`operator_helm_values` 配置项允许为 TiDB Operator 提供一个自定义的 `values.yaml` 配置文件，示例如下： + +- 在 `terraform.tfvars` 中设置 `operator_helm_values`： + + ```hcl + operator_helm_values = "./my-operator-values.yaml" + ``` + +- 在 `main.tf` 中设置 `operator_helm_values`： + + ```hcl + operator_helm_values = file("./my-operator-values.yaml") + ``` + +同时，在默认配置下 Terraform 脚本会创建一个新的 VPC，假如要使用现有的 VPC，可以在 `variable.tf` 中设置 `vpc_id`。注意，当使用现有 VPC 时，没有设置 vswitch 的可用区将不会部署 Kubernetes 节点。 + +### 配置 TiDB 集群 + +TiDB 集群会使用 `./my-cluster.yaml` 作为集群的 `values.yaml` 配置文件，修改该文件即可配置 TiDB 集群。支持的配置项可参考 [Kubernetes 上的 TiDB 集群配置](/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 + +## 管理多个 TiDB 集群 + +需要在一个 Kubernetes 集群下管理多个 TiDB 集群时，需要编辑 `./main.tf`，按实际需要新增 `tidb-cluster` 声明，示例如下： + +```hcl +module "tidb-cluster-dev" { + source = "../modules/aliyun/tidb-cluster" + providers = { + helm = helm.default + } + + cluster_name = "dev-cluster" + ack = module.tidb-operator + + pd_count = 1 + tikv_count = 1 + tidb_count = 1 + override_values = file("dev-cluster.yaml") +} + +module "tidb-cluster-staging" { + source = "../modules/aliyun/tidb-cluster" + providers = { + helm = helm.default + } + + cluster_name = "staging-cluster" + ack = module.tidb-operator + + pd_count = 3 + tikv_count = 3 + tidb_count = 2 + override_values = file("staging-cluster.yaml") +} +``` + +注意，多个 TiDB 集群之间 `cluster_name` 必须保持唯一。下面是 `tidb-cluster` 模块的所有可配置参数： + +| 参数名 | 说明 | 默认值 | +| :----- | :---- | :----- | +| `ack` | 封装目标 Kubernetes 集群信息的结构体，必填 | `nil` | +| `cluster_name` | TiDB 集群名，必填且必须唯一 | `nil` | +| `tidb_version` | TiDB 集群版本 | `v3.0.1` | +| `tidb_cluster_chart_version` | `tidb-cluster` helm chart 的版本 | `v1.0.1` | +| `pd_count` | PD 节点数 | 3 | +| `pd_instance_type` | PD 实例类型 | `ecs.g5.large` | +| `tikv_count` | TiKV 节点数 | 3 | +| `tikv_instance_type` | TiKV 实例类型 | `ecs.i2.2xlarge` | +| `tidb_count` | TiDB 节点数 | 2 | +| `tidb_instance_type` | TiDB 实例类型 | `ecs.c5.4xlarge` | +| `monitor_instance_type` | 监控组件的实例类型 | `ecs.c5.xlarge` | +| `override_values` | TiDB 集群的 `values.yaml` 配置文件，通常通过 `file()` 函数从文件中读取 | `nil` | +| `local_exec_interpreter` | 执行命令行指令的解释器 | `["/bin/sh", "-c"]` | + +## 管理多个 Kubernetes 集群 + +推荐针对每个 Kubernetes 集群都使用单独的 Terraform 模块进行管理（一个 Terraform Module 即一个包含 `.tf` 脚本的目录）。 + +`deploy/aliyun` 实际上是将 `deploy/modules` 中的数个可复用的 Terraform 脚本组合在了一起。当管理多个集群时（下面的操作在 `tidb-operator` 项目根目录下进行）： + +1. 首先针对每个集群创建一个目录，如： + + {{< copyable "shell-regular" >}} + + ```shell + mkdir -p deploy/aliyun-staging + ``` + +2. 参考 `deploy/aliyun` 的 `main.tf`，编写自己的脚本，下面是一个简单的例子： + + ```hcl + provider "alicloud" { + region = + access_key = + secret_key = + } + + module "tidb-operator" { + source = "../modules/aliyun/tidb-operator" + + region = + access_key = + secret_key = + cluster_name = "example-cluster" + key_file = "ssh-key.pem" + kubeconfig_file = "kubeconfig" + } + + provider "helm" { + alias = "default" + insecure = true + install_tiller = false + kubernetes { + config_path = module.tidb-operator.kubeconfig_filename + } + } + + module "tidb-cluster" { + source = "../modules/aliyun/tidb-cluster" + providers = { + helm = helm.default + } + + cluster_name = "example-cluster" + ack = module.tidb-operator + } + + module "bastion" { + source = "../modules/aliyun/bastion" + + bastion_name = "example-bastion" + key_name = module.tidb-operator.key_name + vpc_id = module.tidb-operator.vpc_id + vswitch_id = module.tidb-operator.vswitch_ids[0] + enable_ssh_to_worker = true + worker_security_group_id = module.tidb-operator.security_group_id + } + ``` + +上面的脚本可以自由定制，比如，假如不需要堡垒机则可以移除 `module "bastion"` 相关声明。 + +你也可以直接拷贝 `deploy/aliyun` 目录，但要注意不能拷贝已经运行了 `terraform apply` 的目录，建议重新 clone 仓库再进行拷贝。 + +## 使用限制 + +目前，`pod cidr`，`service cidr` 和节点型号等配置在集群创建后均无法修改。 diff --git a/tidb-in-kubernetes/deploy/aws-eks.md b/tidb-in-kubernetes/deploy/aws-eks.md new file mode 100644 index 000000000000..fd4496a0282e --- /dev/null +++ b/tidb-in-kubernetes/deploy/aws-eks.md @@ -0,0 +1,531 @@ +--- +title: 在 AWS EKS 上部署 TiDB 集群 +category: how-to +--- + +# 在 AWS EKS 上部署 TiDB 集群 + +本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在 AWS EKS (Elastic Kubernetes Service) 上部署 TiDB 集群。 + +## 环境配置准备 + +部署前，请确认已安装以下软件并完成配置： + +* [awscli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) >= 1.16.73，控制 AWS 资源 + + 要与 AWS 交互，必须[配置 `awscli`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。最快的方式是使用 `aws configure` 命令: + + {{< copyable "shell-regular" >}} + + ``` shell + aws configure + ``` + + 替换下面的 AWS Access Key ID 和 AWS Secret Access Key： + + ``` + AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE + AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + Default region name [None]: us-west-2 + Default output format [None]: json + ``` + + > **注意：** + > + > Access key 必须至少具有以下权限：创建 VPC、创建 EBS、创建 EC2 和创建 Role。 + +* [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) >= 0.12 +* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.11 +* [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.0 且 < 3.0.0 +* [jq](https://stedolan.github.io/jq/download/) +* [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html)，AWS 权限鉴定工具，确保安装在 `PATH` 路径下。 + + 最简单的安装方法是下载编译好的二进制文件 `aws-iam-authenticator`，如下所示。 + + Linux 用户下载二进制文件： + + {{< copyable "shell-regular" >}} + + ``` shell + curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/linux/amd64/aws-iam-authenticator + ``` + + macOS 用户下载二进制文件： + + {{< copyable "shell-regular" >}} + + ``` shell + curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/darwin/amd64/aws-iam-authenticator + ``` + + 二进制文件下载完成后，执行以下操作： + + {{< copyable "shell-regular" >}} + + ``` shell + chmod +x ./aws-iam-authenticator && \ + sudo mv ./aws-iam-authenticator /usr/local/bin/aws-iam-authenticator + ``` + +## 部署集群 + +默认部署会创建一个新的 VPC、一个 t2.micro 实例作为堡垒机，并包含以下 ec2 实例作为工作节点的 EKS 集群： + +* 3 台 m5.xlarge 实例，部署 PD +* 3 台 c5d.4xlarge 实例，部署 TiKV +* 2 台 c5.4xlarge 实例，部署 TiDB +* 1 台 c5.2xlarge 实例，部署监控组件 + +使用如下命令部署集群。 + +从 Github 克隆代码并进入指定路径： + +{{< copyable "shell-regular" >}} + +``` shell +git clone --depth=1 https://github.com/pingcap/tidb-operator && \ +cd tidb-operator/deploy/aws +``` + +使用 `terraform` 命令初始化并部署集群： + +{{< copyable "shell-regular" >}} + +``` shell +terraform init +``` + +{{< copyable "shell-regular" >}} + +``` shell +terraform apply +``` + +> **注意：** +> +> `terraform apply` 过程中必须输入 "yes" 才能继续。 + +整个过程可能至少需要 10 分钟。`terraform apply` 执行成功后，控制台会输出类似如下的信息： + +``` +Apply complete! Resources: 67 added，0 changed，0 destroyed. + +Outputs: + +bastion_ip = [ + "34.219.204.217", +] +default-cluster_monitor-dns = a82db513ba84511e9af170283460e413-1838961480.us-west-2.elb.amazonaws.com +default-cluster_tidb-dns = a82df6d13a84511e9af170283460e413-d3ce3b9335901d8c.elb.us-west-2.amazonaws.com +eks_endpoint = https://9A9A5ABB8303DDD35C0C2835A1801723.yl4.us-west-2.eks.amazonaws.com +eks_version = 1.12 +kubeconfig_filename = credentials/kubeconfig_my-cluster +region = us-west-21 +``` + +你可以通过 `terraform output` 命令再次获取上面的输出信息。 + +> **注意：** +> +> 1.14 版本以前的 EKS 不支持自动开启 NLB 跨可用区负载均衡，因此默认配置下 会出现各台 TiDB 实例压力不均衡额状况。生产环境下，强烈建议参考 [AWS 官方文档](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-disable-crosszone-lb.html#enable-cross-zone)手动开启 NLB 的跨可用区负载均衡。 + +## 访问数据库 + +`terraform apply` 完成后，可先通过 `ssh` 远程连接到堡垒机，再通过 MySQL client 来访问 TiDB 集群。 + +所需命令如下（用上面的输出信息替换 `<>` 部分内容)： + +{{< copyable "shell-regular" >}} + +```shell +ssh -i credentials/.pem centos@ +``` + +{{< copyable "shell-regular" >}} + +```shell +mysql -h -P 4000 -u root +``` + +`eks_name` 默认为 `my-cluster`。如果 DNS 名字无法解析，请耐心等待几分钟。 + +你还可以通过 `kubectl` 和 `helm` 命令使用 kubeconfig 文件 `credentials/kubeconfig_` 和 EKS 集群交互，主要有两种方式，如下所示。 + +- 指定 --kubeconfig 参数： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl --kubeconfig credentials/kubeconfig_ get po -n + ``` + + {{< copyable "shell-regular" >}} + + ```shell + helm --kubeconfig credentials/kubeconfig_ ls + ``` + +- 或者，设置 KUBECONFIG 环境变量： + + {{< copyable "shell-regular" >}} + + ```shell + export KUBECONFIG=$PWD/credentials/kubeconfig_ + ``` + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get po -n + ``` + + {{< copyable "shell-regular" >}} + + ```shell + helm ls + ``` + +## Grafana 监控 + +你可以通过浏览器访问 `:3000` 地址查看 Grafana 监控指标。 + +Grafana 默认登录信息： + +- 用户名：admin +- 密码：admin + +## 升级 TiDB 集群 + +要升级 TiDB 集群，可编辑 `variables.tf` 文件，修改 `default_cluster_version` 变量到更高版本，然后运行 `terraform apply`。 + +例如，要升级 TiDB 集群到 3.0.1，则修改 `default_cluster_version` 为 `v3.0.1`： + +```hcl +variable "default_cluster_version" { + default = "v3.0.1" +} +``` + +> **注意：** +> +> 升级过程会持续一段时间，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察升级进度。 + +## 扩容 TiDB 集群 + +若要扩容 TiDB 集群，可按需修改 `variables.tf` 文件中的 `default_cluster_tikv_count` 或者 `default_cluster_tidb_count` 变量，然后运行 `terraform apply`。 + +例如，可以将 `default_cluster_tidb_count` 从 2 改为 4 以扩容 TiDB： + +```hcl + variable "default_cluster_tidb_count" { + default = 4 + } +``` + +> **注意：** +> +> - 由于缩容过程中无法确定会缩掉哪个节点，目前还不支持 TiDB 集群的缩容。 +> - 扩容过程会持续几分钟，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察进度。 + +## 自定义 + +你可以按需修改 `variables.tf` 文件中的默认值，例如集群名称和镜像版本等。 + +### 自定义 AWS 相关的资源 + +默认情况下 terraform 脚本会新建 VPC。你也可以通过设置 `create_vpc` 为 `false`，并指定 `vpc_id`、`private_subnet_ids` 和 `public_subnet_ids` 变量为已有的 VPC id、subnet ids 来使用现有的网络。 + +> **注意：** +> +> - 由于 AWS 和 Terraform 的限制，还不支持复用已有 EKS 集群的 VPC 和 subnets，所以请确保只在你手动创建 VPC 的情况下修改该参数； +> - EKS Node 上的 CNI 插件会为每个节点预留一部分 IP 资源，因此 IP 消耗较大，在手动创建 VPC 时，建议将每个 subnet 的掩码长度设置在 18~20 以确保 IP 资源充足，或参考 [EKS CNI 插件文档](https://github.com/aws/amazon-vpc-cni-k8s#cni-configuration-variables)将节点预留的 IP 资源数调低。 + +由于 TiDB 服务通过 [Internal Elastic Load Balancer](https://aws.amazon.com/blogs/aws/internal-elastic-load-balancers/) 暴露，默认情况下，会创建一个 Amazon EC2 实例作为堡垒机，访问创建的 TiDB 集群。堡垒机上预装了 MySQL 和 Sysbench，所以你可以通过 SSH 方式登陆到堡垒机后通过 ELB 访问 TiDB。如果你的 VPC 中已经有了类似的 EC2 实例，你可以通过设置 `create_bastion` 为 `false` 禁掉堡垒机的创建。 + +TiDB 版本和组件数量也可以在 `variables.tf` 中修改，你可以按照自己的需求配置。 + +目前，由于 PD 和 TiKV 依赖 [NVMe SSD 实例存储卷](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html)，TiDB 集群组件的实例类型不能修改。 + +### 自定义 TiDB 参数配置 + +Terraform 脚本中为运行在 EKS 上的 TiDB 集群提供了合理的默认配置。有自定义需求时，你可以在 `clusters.tf` 中通过 `override_values` 参数为每个 TiDB 集群指定一个 `values.yaml` 文件来自定义集群参数配置。 + +作为例子，默认集群使用了 `./default-cluster.yaml` 作为 `values.yaml` 配置文件，并在配置中打开了"配置文件滚动更新"特性。 + +值得注意的是，在 EKS 上部分配置项无法在 `values.yaml` 中进行修改，包括集群版本、副本数、`NodeSelector` 以及 `Tolerations`。`NodeSelector` 和 `Tolerations` 由 Terraform 直接管理以确保基础设施与 TiDB 集群之间的一致性。集群版本和副本数可以通过 `cluster.tf` 文件中的 `tidb-cluster` module 参数来修改。 + +> **注意：** +> +> 自定义 `values.yaml` 配置文件中，不建议包含如下配置（`tidb-cluster` module 默认固定配置）： + +``` +pd: + storageClassName: ebs-gp2 +tikv: + stroageClassName: local-storage +tidb: + service: + type: LoadBalancer + annotations: + service.beta.kubernetes.io/aws-load-balancer-internal: '0.0.0.0/0' + service.beta.kubernetes.io/aws-load-balancer-type: nlb + service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: >'true' + separateSlowLog: true +monitor: + storage: 100Gi + storageClassName: ebs-gp2 + persistent: true + grafana: + config: + GF_AUTH_ANONYMOUS_ENABLED: "true" + service: + type: LoadBalancer +``` + +### 自定义 TiDB Operator + +你可以通过 `variables.tf` 中的 `operator_values` 参数传入自定义的 `values.yaml` 内容来配置 TiDB Operator。示例如下： + +```hcl +variable "operator_values" { + description = "The helm values file for TiDB Operator, path is relative to current working dir" + default = "./operator_values.yaml" +} +``` + +## 管理多个 TiDB 集群 + +一个 `tidb-cluster` 模块的实例对应一个 TiDB 集群，你可以通过编辑 `clusters.tf` 添加新的 `tidb-cluster` 模块实例来新增 TiDB 集群，示例如下： + +```hcl +module example-cluster { + source = "../modules/aws/tidb-cluster" + + # The target EKS, required + eks = local.eks + # The subnets of node pools of this TiDB cluster, required + subnets = local.subnets + # TiDB cluster name, required + cluster_name = "example-cluster" + + # Helm values file + override_values = file("example-cluster.yaml") + # TiDB cluster version + cluster_version = "v3.0.0" + # SSH key of cluster nodes + ssh_key_name = module.key-pair.key_name + # PD replica number + pd_count = 3 + # TiKV instance type + pd_instance_type = "t2.xlarge" + # TiKV replica number + tikv_count = 3 + # TiKV instance type + tikv_instance_type = "t2.xlarge" + # The storage class used by TiKV, if the TiKV instance type do not have local SSD, you should change it to storage class + # TiDB replica number + tidb_count = 2 + # TiDB instance type + tidb_instance_type = "t2.xlarge" + # Monitor instance type + monitor_instance_type = "t2.xlarge" + # The version of tidb-cluster helm chart + tidb_cluster_chart_version = "v1.0.0" + # Decides whether or not to create the tidb-cluster helm release. + # If this variable is set to false, you have to + # install the helm release manually + create_tidb_cluster_release = true +} +``` + +> **注意：** +> +> `cluster_name` 必须是唯一的。 + +你可以通过 `kubectl` 获取新集群的监控系统地址与 TiDB 地址。假如你希望让 Terraform 脚本输出这些地址，可以通过在 `outputs.tf` 中增加相关的输出项实现： + +```hcl +output "example-cluster_tidb-hostname" { + value = module.example-cluster.tidb_hostname +} + +output "example-cluster_monitor-hostname" { + value = module.example-cluster.monitor_hostname +} +``` + +修改完成后，执行 `terraform init` 和 `terraform apply` 创建集群。 + +最后，只要移除 `tidb-cluster` 模块调用，对应的 TiDB 集群就会被销毁，EC2 资源也会随之释放。 + +## 仅管理基础设施 + +通过调整配置，你可以控制 Terraform 脚本只创建 Kubernetes 集群和 TiDB Operator。操作步骤如下： + +* 修改 `clusters.tf` 中 TiDB 集群的 `create_tidb_cluster_release` 配置项： + + ```hcl + module "default-cluster" { + ... + create_tidb_cluster_release = false + } + ``` + + 如上所示，当 `create_tidb_cluster_release` 设置为 `false` 时，Terraform 脚本不会创建和修改 TiDB 集群，但仍会创建 TiDB 集群所需的计算和存储资源。此时，你可以使用 Helm 等工具来独立管理集群。 + +> **注意：** +> +> 在已经部署的集群上将 `create_tidb_cluster_release` 调整为 `false` 会导致已安装的 TiDB 集群被删除，对应的 TiDB 集群对象也会随之被删除。 + +## 销毁集群 + +可以通过如下命令销毁集群： + +{{< copyable "shell-regular" >}} + +```shell +terraform destroy +``` + +> **注意：** +> +> * 该操作会销毁 EKS 集群以及部署在该 EKS 集群上的所有 TiDB 集群。 +> * 如果你不再需要存储卷中的数据，在执行 `terraform destroy` 后，你需要在 AWS 控制台手动删除 EBS 卷。 + +## 管理多个 Kubernetes 集群 + +本节详细介绍了如何管理多个 Kubernetes 集群（EKS），并在每个集群上部署一个或更多 TiDB 集群。 + +上述文档中介绍的 Terraform 脚本组合了多个 Terraform 模块： + +- `tidb-operator` 模块，用于创建 EKS 集群并在 EKS 集群上安装配置 [TiDB Operator](/tidb-in-kubernetes/deploy/tidb-operator.md)。 +- `tidb-cluster` 模块，用于创建 TiDB 集群所需的资源池并部署 TiDB 集群。 +- EKS 上的 TiDB 集群专用的 `vpc` 模块、`key-pair`模块和`bastion` 模块 + +管理多个 Kubernetes 集群的最佳实践是为每个 Kubernetes 集群创建一个单独的目录，并在新目录中自行组合上述 Terraform 模块。这种方式能够保证多个集群间的 Terraform 状态不会互相影响，也便于自由定制和扩展。下面是一个例子： + +{{< copyable "shell-regular" >}} + +```shell +mkdir -p deploy/aws-staging +vim deploy/aws-staging/main.tf +``` + +`deploy/aws-staging/main.tf` 的内容可以是： + +```hcl +provider "aws" { + region = "us-west-1" +} + +# 创建一个 ssh key，用于登录堡垒机和 Kubernetes 节点 +module "key-pair" { + source = "../modules/aws/key-pair" + + name = "another-eks-cluster" + path = "${path.cwd}/credentials/" +} + +# 创建一个新的 VPC +module "vpc" { + source = "../modules/aws/vpc" + + vpc_name = "another-eks-cluster" +} + +# 在上面的 VPC 中创建一个 EKS 并部署 tidb-operator +module "tidb-operator" { + source = "../modules/aws/tidb-operator" + + eks_name = "another-eks-cluster" + config_output_path = "credentials/" + subnets = module.vpc.private_subnets + vpc_id = module.vpc.vpc_id + ssh_key_name = module.key-pair.key_name +} + +# 特殊处理，确保 helm 操作在 EKS 创建完毕后进行 +resource "local_file" "kubeconfig" { + depends_on = [module.tidb-operator.eks] + sensitive_content = module.tidb-operator.eks.kubeconfig + filename = module.tidb-operator.eks.kubeconfig_filename +} +provider "helm" { + alias = "eks" + insecure = true + install_tiller = false + kubernetes { + config_path = local_file.kubeconfig.filename + } +} + +# 在上面的 EKS 集群上创建一个 TiDB 集群 +module "tidb-cluster-a" { + source = "../modules/aws/tidb-cluster" + providers = { + helm = "helm.eks" + } + + cluster_name = "tidb-cluster-a" + eks = module.tidb-operator.eks + ssh_key_name = module.key-pair.key_name + subnets = module.vpc.private_subnets +} + +# 在上面的 EKS 集群上创建另一个 TiDB 集群 +module "tidb-cluster-b" { + source = "../modules/aws/tidb-cluster" + providers = { + helm = "helm.eks" + } + + cluster_name = "tidb-cluster-b" + eks = module.tidb-operator.eks + ssh_key_name = module.key-pair.key_name + subnets = module.vpc.private_subnets +} + +# 创建一台堡垒机 +module "bastion" { + source = "../modules/aws/bastion" + + bastion_name = "another-eks-cluster-bastion" + key_name = module.key-pair.key_name + public_subnets = module.vpc.public_subnets + vpc_id = module.vpc.vpc_id + target_security_group_id = module.tidb-operator.eks.worker_security_group_id + enable_ssh_to_workers = true +} + +# 输出 tidb-cluster-a 的 TiDB 服务地址 +output "cluster-a_tidb-dns" { + description = "tidb service endpoints" + value = module.tidb-cluster-a.tidb_hostname +} + +# 输出 tidb-cluster-b 的监控地址 +output "cluster-b_monitor-dns" { + description = "tidb service endpoint" + value = module.tidb-cluster-b.monitor_hostname +} + +# 输出堡垒机 IP +output "bastion_ip" { + description = "Bastion IP address" + value = module.bastion.bastion_ip +} +``` + +上面的例子很容易进行定制，比如，假如你不需要堡垒机，便可以删去对 `bastion` 模块的调用。同时，项目中提供的 Terraform 模块均设置了合理的默认值，因此在调用这些 Terraform 模块时，你可以略去大部分的参数。 + +你可以参考默认的 Terraform 脚本来定制每个模块的参数，也可以参考每个模块的 `variables.tf` 文件来了解所有可配置的参数。 + +另外，这些 Terraform 模块可以很容易地集成到你自己的 Terraform 工作流中。假如你对 Terraform 非常熟悉，这也是我们推荐的一种使用方式。 + +> **注意：** +> +> * 由于 Terraform 本身的限制（[hashicorp/terraform#2430](https://github.com/hashicorp/terraform/issues/2430#issuecomment-370685911)），在你自己的 Terraform 脚本中，也需要保留上述例子中对 `helm provider` 的特殊处理。 +> * 创建新目录时，需要注意与 Terraform 模块之间的相对路径，这会影响调用模块时的 `source` 参数。 +> * 假如你想在 tidb-operator 项目之外使用这些模块，你需要确保 `modules` 目录中的所有模块的相对路径保持不变。 + +假如你不想自己写 Terraform 代码，也可以直接拷贝 `deploy/aws` 目录来创建新的 Kubernetes 集群。但要注意不能拷贝已经运行过 `terraform apply` 的目录（已经有 Terraform 的本地状态）。这种情况下，推荐在拷贝前克隆一个新的仓库。 diff --git a/dev/tidb-in-kubernetes/deploy/gcp-gke.md b/tidb-in-kubernetes/deploy/gcp-gke.md similarity index 100% rename from dev/tidb-in-kubernetes/deploy/gcp-gke.md rename to tidb-in-kubernetes/deploy/gcp-gke.md diff --git a/tidb-in-kubernetes/deploy/general-kubernetes.md b/tidb-in-kubernetes/deploy/general-kubernetes.md new file mode 100644 index 000000000000..0d99b144724a --- /dev/null +++ b/tidb-in-kubernetes/deploy/general-kubernetes.md @@ -0,0 +1,80 @@ +--- +title: 在标准 Kubernetes 上部署 TiDB 集群 +category: how-to +--- + +# 在标准 Kubernetes 上部署 TiDB 集群 + +本文主要描述了如何在标准的 Kubernetes 集群上通过 TiDB Operator 部署 TiDB 集群。 + +## 前置条件 + +* 参考 [TiDB Operator](/tidb-in-kubernetes/deploy/tidb-operator.md) 完成集群中的 TiDB Operator 部署； +* 参考 [使用 Helm](/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 + +## 配置 TiDB 集群 + +通过下面命令获取待安装的 tidb-cluster chart 的 `values.yaml` 配置文件： + +{{< copyable "shell-regular" >}} + +```shell +mkdir -p /home/tidb/ && \ +helm inspect values pingcap/tidb-cluster --version= > /home/tidb//values-.yaml +``` + +> **注意：** +> +> - `/home/tidb` 可以替换为你想用的目录。 +> - `release-name` 将会作为 Kubernetes 相关资源（例如 Pod，Service 等）的前缀名，可以起一个方便记忆的名字，要求全局唯一，通过 `helm ls -q` 可以查看集群中已经有的 `release-name`。 +> - `chart-version` 是 tidb-cluster chart 发布的版本，可以通过 `helm search -l tidb-cluster` 查看当前支持的版本。 +> - 下文会用 `values.yaml` 指代 `/home/tidb//values-.yaml`。 + +### 存储类型 + +集群默认使用 `local-storage` 存储类型。 + +- 生产环境：推荐使用本地存储，但实际 Kubernetes 集群中本地存储可能按磁盘类型进行了分类，例如 `nvme-disks`，`sas-disks`。 +- 演示环境或功能性验证：可以使用网络存储，例如 `ebs`，`nfs` 等。 + +另外 TiDB 集群不同组件对磁盘的要求不一样，所以部署集群前要根据当前 Kubernetes 集群支持的存储类型以及使用场景为 TiDB 集群各组件选择合适的存储类型，通过修改 `values.yaml` 中各组件的 `storageClassName` 字段设置存储类型。关于 Kubernetes 集群支持哪些[存储类型](/tidb-in-kubernetes/reference/configuration/storage-class.md)，请联系系统管理员确定。 + +> **注意：** +> +> 如果创建集群时设置了集群中不存在的存储类型，则会导致集群创建处于 Pending 状态，需要[将集群彻底销毁掉](/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md)。 + +### 集群拓扑 + +默认部署的集群拓扑是：3 个 PD Pod，3 个 TiKV Pod，2 个 TiDB Pod 和 1 个监控 Pod。在该部署拓扑下根据数据高可用原则，TiDB Operator 扩展调度器要求 Kubernetes 集群中至少有 3 个节点。如果 Kubernetes 集群节点个数少于 3 个，将会导致有一个 PD Pod 处于 Pending 状态，而 TiKV 和 TiDB Pod 也都不会被创建。 + +Kubernetes 集群节点个数少于 3 个时，为了使 TiDB 集群能启动起来，可以将默认部署的 PD 和 TiKV Pod 个数都减小到 1 个，或者将 `values.yaml` 中 `schedulerName` 改为 Kubernetes 内置调度器 `default-scheduler`。 + +> **警告：** +> +> `default-scheduler` 仅适用于演示环境，改为 `default-scheduler` 后，TiDB 集群的调度将无法保证数据高可用，另外一些其它特性也无法支持，例如 [TiDB Pod StableScheduling](https://github.com/pingcap/tidb-operator/blob/master/docs/design-proposals/tidb-stable-scheduling.md) 等。 + +其它更多配置参数请参考 [TiDB 集群部署配置文档](/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 + +## 部署 TiDB 集群 + +TiDB Operator 部署并配置完成后，可以通过下面命令部署 TiDB 集群： + +{{< copyable "shell-regular" >}} + +``` shell +helm install pingcap/tidb-cluster --name= --namespace= --version= -f /home/tidb//values-.yaml +``` + +> **注意：** +> +> `namespace` 是[命名空间](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)，你可以起一个方便记忆的名字，比如和 `release-name` 相同的名称。 + +通过下面命令可以查看 Pod 状态： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get po -n -l app.kubernetes.io/instance= +``` + +单个 Kubernetes 集群中可以利用 TiDB Operator 部署管理多套 TiDB 集群，重复以上命令并将 `release-name` 替换成不同名字即可。不同集群既可以在相同 `namespace` 中，也可以在不同 `namespace` 中，可根据实际需求进行选择。 diff --git a/tidb-in-kubernetes/deploy/prerequisites.md b/tidb-in-kubernetes/deploy/prerequisites.md new file mode 100644 index 000000000000..2488efcda96a --- /dev/null +++ b/tidb-in-kubernetes/deploy/prerequisites.md @@ -0,0 +1,174 @@ +--- +title: Kubernetes 上的 TiDB 集群环境需求 +category: how-to +--- + +# Kubernetes 上的 TiDB 集群环境需求 + +本文介绍在 Kubernetes 上部署 TiDB 集群的软硬件环境需求。 + +## 软件版本要求 + +| 软件名称 | 版本 | +| :--- | :--- | +| Docker | Docker CE 18.09.6 | +| Kubernetes | v1.12.5+ | +| CentOS | CentOS 7.6，内核要求为 3.10.0-957 或之后版本 | + +## 内核参数设置 + +| 配置项 | 设置值 | +| :--- | :--- | +| net.core.somaxconn | 32768 | +| vm.swappiness | 0 | +| net.ipv4.tcp_syncookies | 0 | +| net.ipv4.ip_forward | 1 | +| fs.file-max | 1000000 | +| fs.inotify.max_user_watches | 1048576 | +| fs.inotify.max_user_instances | 1024 | +| net.ipv4.conf.all.rp_filter | 1 | +| net.ipv4.neigh.default.gc_thresh1 | 80000 | +| net.ipv4.neigh.default.gc_thresh2 | 90000 | +| net.ipv4.neigh.default.gc_thresh3 | 100000 | +| net.bridge.bridge-nf-call-iptables | 1 | +| net.bridge.bridge-nf-call-arptables | 1 | +| net.bridge.bridge-nf-call-ip6tables | 1 | + +在设置 `net.bridge.bridge-nf-call-*` 这几项参数时，如果选项报错，则可通过如下命令检查是否已经加载该模块： + +{{< copyable "shell-regular" >}} + +```shell +lsmod|grep br_netfilter +``` + +如果没有加载，则执行如下命令加载： + +{{< copyable "shell-regular" >}} + +```shell +modprobe br_netfilter +``` + +同时还需要关闭每个部署 Kubernetes 节点的 swap，执行如下命令： + +{{< copyable "shell-regular" >}} + +```shell +swapoff -a +``` + +执行如下命令检查 swap 是否已经关闭： + +{{< copyable "shell-regular" >}} + +```shell +free -m +``` + +如果执行命令后输出显示 swap 一列全是 0，则表明 swap 已经关闭。 + +此外，为了永久性地关闭 swap，还需要将 `/etc/fstab` 中 swap 相关的条目全部删除。 + +在上述内容都设置完成后，还需要检查是否给机器配置了 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt)，也就是将各个设备对应的中断号分别绑定到不同的 CPU 上，以防止所有中断请求都落在同一个 CPU 上而引发性能瓶颈。对于 TiDB 集群来说，网卡处理包的速度对集群的吞吐率影响很大。因此下文主要描述如何将网卡中断号绑定到特定的 CPU 上，充分利用多核的优势来提高集群的吞吐率。首先可以通过以下命令来查看网卡对应的中断号： + +{{< copyable "shell-regular" >}} + +```shell +cat /proc/interrupts|grep |awk '{print $1,$NF}' +``` + +以上命令输出的第一列是中断号，第二列是设备名称。如果是多队列网卡，上面的命令会显示多行信息，网卡的每个队列对应一个中断号。通过以下命令可以查看该中断号被绑定到哪个 CPU 上： + +{{< copyable "shell-regular" >}} + +```shell +cat /proc/irq//smp_affinity +``` + +上面命令输出 CPU 序号对应的十六进制值。输出结果欠直观。具体计算方法可参见 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt) 文档。 + +{{< copyable "shell-regular" >}} + +```shell +cat /proc/irq//smp_affinity_list +``` + +上面命令输出 CPU 序号对应的十进制值，输出结果较为直观。 + +如果多队列网卡对应的所有中断号都已被绑定到不同的 CPU 上，那么该机器的 SMP IRQ Affinity 配置是正确的。如果中断号都落在同一个 CPU 上，则需要进行调整。调整的方式有以下两种： + ++ 方法一：开启 [irqbalance](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-tool_reference-irqbalance) 服务。在 centos7 系统上的开启命令如下: + + {{< copyable "shell-regular" >}} + + ```shell + systemctl start irqbalance + ``` + ++ 方法二：禁用 irqbalance，自定义中断号和 CPU 的绑定关系。详情参见脚本 [set_irq_affinity.sh](https://gist.githubusercontent.com/SaveTheRbtz/8875474/raw/0c6e500e81e161505d9111ac77115a2367180d12/set_irq_affinity.sh)。 + +上文所描述的是处理多队列网卡和多核心的场景。单队列网卡和多核的场景则有不同的处理方式。在这种场景下，可以使用 [RPS/RFS](https://www.kernel.org/doc/Documentation/networking/scaling.txt) 在软件层面模拟实现硬件的网卡多队列功能 (RSS)。此时不能使用方法一所述的 irqbalance 服务，而是通过使用方法二提供的脚本来设置 RPS。RFS 的配置可以参考[这里](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-networking-configuration_tools#sect-Red_Hat_Enterprise_Linux-Performance_Tuning_Guide-Configuration_tools-Configuring_Receive_Flow_Steering_RFS)。 + +## 硬件和部署要求 + +与使用 binary 方式部署 TiDB 集群一致，要求选用 Intel x86-64 架构的 64 位通用硬件服务器，使用万兆网卡。关于 TiDB 集群在物理机上的具体部署需求，参考 [TiDB 软件和硬件环境建议配置](/how-to/deploy/hardware-recommendations.md)。 + +对于服务器 disk、memory、CPU 的选择要根据对集群的容量规划以及部署拓扑来定。线上 Kubernetes 集群部署为了保证高可用，一般需要部署三个 master 节点、三个 etcd 节点以及若干个 worker 节点。同时，为了充分利用机器资源，master 节点一般也充当 worker 节点（也就是 master 节点上也可以调度负载）。通过 kubelet 设置[预留资源](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/)来保证机器上的系统进程以及 Kubernetes 的核心进程在工作负载很高的情况下仍然有足够的资源来运行，从而保证整个系统的稳定。 + +下面按 3 Kubernetes master + 3 etcd + 若干 worker 节点部署方案进行分析。Kubernetes 的多 master 节点高可用部署可参考[官方文档](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/)。 + +## Kubernetes 系统资源要求 + +- 每台机器需要一块比较大的 SAS 盘（至少 1T），这块盘用来存 Docker 和 kubelet 的数据目录。Docker 的数据主要包括镜像和容器日志数据，kubelet 主要占盘的数据是 [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) 所使用的数据。 + +- 如果需要部署 Kubernetes 集群的监控系统, 且监控数据需要落盘，则也需要考虑为 Prometheus 准备一块 SAS 盘，后面日志监控系统也需要大的 SAS 盘，同时考虑到机器采购最好是同构的这一因素，因此每台机器最好有两块大的 SAS 盘。 + + > **注意：** + > + > 生产环境建议给这两种类型的盘做 RAID5，至于使用多少块来做 RAID5 可自己决定。 + +- etcd 的分布建议是和 Kubernetes master 节点保持一致，即有多少个 master 节点就部署多少个 etcd 节点。etcd 数据建议使用 SSD 盘存放。 + +## TiDB 集群资源需求 + +TiDB 集群由 PD、TiKV、TiDB 三个组件组成，在做容量规划的时候一般按照可以支持多少套 TiDB 集群来算。这里按照标准的 TiDB 集群（3 个 PD + 3 个 TiKV + 2 个 TiDB）来算，下面是对每个组件规划的一种建议： + +- PD 组件：PD 占用资源较少，这种集群规模下分配 2C 4GB 即可，占用少量本地盘。 + + 为了便于管理，可以将所有集群的 PD 都放在 master 节点，比如需要支持 5 套 TiDB 集群，则可以规划 3 个 master 节点，每个节点支持部署 5 个 PD 实例，5 个 PD 实例使用同一块 SSD 盘即可（两三百 GB 的盘即可）。通过 bind mount 的方式在这块 SSD 上创建 5 个目录作为挂载点，操作方式见 [Sharing a disk filesystem by multiple filesystem PVs](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)。 + + 如果后续要添加更多机器支持更多的 TiDB 集群，可以在 master 上用这种方式继续增加 PD 实例。如果 master 上资源耗尽，可以找其它的 worker 节点机器用同样的方式添加 PD 实例。这种方式的好处就是方便规划和管理 PD 实例，坏处就是由于 PD 实例过于集中，这些机器中如果有两台宕机会导致所有的 TiDB 集群不可用。 + + 因此建议从所有集群里面的机器都拿出一块 SSD 盘像 master 节点一样提供 PD 实例。比如总共 7 台机器，要支持 7 套 TiDB 标准集群的情况下，则需要每台机器上都能支持部署 3 个 PD 实例，如果后续有集群需要通过扩容机器增加容量，也只需要在新的机器上创建 PD 实例。 + +- TiKV 组件：因为 TiKV 组件的性能很依赖磁盘 I/O 且数据量一般较大，因此建议每个 TiKV 实例独占一块 NVMe 的盘，资源配置为 8C 32GB。如果想要在一个机器上支持部署多个 TiKV 实例，则建议参考这些参数去选择合适的机器，同时在规划容量的时候应当预留出足够的 buffer。 + +- TiDB 组件：TiDB 组件因为不占用磁盘，因此在规划的时候只需要考虑其占用的 CPU 和内存资源即可，这里也按 8C 32 GB 的容量来计算。 + +## TiDB 集群规划示例 + +通过上面的分析，这里给出一个支持部署 5 套规模为 3 个 PD + 3 个 TiKV + 2 个 TiDB 集群的例子，其中 PD 配置为 2C 4GB，TiDB 配置为 8C 32GB，TiKV 配置为 8C 32GB。Kubernetes 节点有 7 个，其中有 3 个节点既是 master 又是 worker 节点，另外 4 个是纯 worker 节点。各组件分布情况如下： + ++ 单个 master 节点： + + - 1 etcd (2C 4GB) + 2 PD (2 \* 2C 2 \* 4GB) + 3 TiKV (3 \* 8C 3 \* 32GB) + 1 TiDB (8C 32GB)，总共是 38C 140GB + - 两块 SSD 盘，一块给 etcd，另外一块给 2 个 PD 实例 + - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 + - 三块 NVMe 盘给 TiKV 实例 + ++ 单个 worker 节点： + + - 3 PD (3 \* 2C 3 \* 4GB) + 2 TiKV (2 \* 8C 2 \* 32GB) + 2 TiDB (2 \* 8C 2 \* 32GB)，总共是 38C 140GB + - 一块 SSD 盘给三个 PD 实例 + - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 + - 两块 NVMe 盘给 TiKV 实例 + +从上面的分析来看，要支持 5 套 TiDB 集群容量共需要 7 台物理机，其中 3 台为 master 兼 worker 节点，其余 4 台为 worker 节点，机器配置需求如下： + +- master 兼 worker 节点：48C 192GB；2 块 SSD 盘，一块做了 RAID5 的 SAS 盘，三块 NVMe 盘 +- worker 节点：48C 192GB；1 块 SSD 盘，一块做了 RAID5 的 SAS 盘，两块 NVMe 盘 + +使用上面的机器配置，除去各个组件占用的资源外，还有比较多的预留资源。如果要考虑加监控和日志组件，则可以用同样的方法去规划需要采购的机器类型以及配置。 + +另外，在生产环境的使用上尽量不要在 master 节点部署 TiDB 实例，或者尽可能少地部署 TiDB 实例。这里的主要考虑点是网卡带宽，因为 master 节点网卡满负荷工作会影响到 worker 节点和 master 节点之间的心跳信息汇报，导致比较严重的问题。 diff --git a/tidb-in-kubernetes/deploy/tidb-operator.md b/tidb-in-kubernetes/deploy/tidb-operator.md new file mode 100644 index 000000000000..29f09ff21fab --- /dev/null +++ b/tidb-in-kubernetes/deploy/tidb-operator.md @@ -0,0 +1,132 @@ +--- +title: 在 Kubernetes 上部署 TiDB Operator +summary: 了解如何在 Kubernetes 上部署 TiDB Operator +category: how-to +--- + +# 在 Kubernetes 上部署 TiDB Operator + +本文介绍如何在 Kubernetes 上部署 TiDB Operator。 + +## 准备环境 + +TiDB Operator 部署前，请确认以下软件需求： + +* Kubernetes v1.12 或者更高版本 +* [DNS 插件](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/) +* [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) +* [RBAC](https://kubernetes.io/docs/admin/authorization/rbac) 启用（可选） +* [Helm](https://helm.sh) 版本 >= v2.8.2 && < v3.0.0 + +> **注意：** +> +> - 尽管 TiDB Operator 可以使用网络卷持久化 TiDB 数据，TiDB 数据自身会存多副本，再走额外的网络卷性能会受到很大影响。强烈建议搭建[本地卷](https://kubernetes.io/docs/concepts/storage/volumes/#local)以提高性能。 +> - 跨多可用区的网络卷需要 Kubernetes v1.12 或者更高版本。在 `tidb-backup` chart 配置中，建议使用网络卷存储备份数据。 + +## 部署 Kubernetes 集群 + +TiDB Operator 运行在 Kubernetes 集群，你可以使用 [Getting started 页面](https://kubernetes.io/docs/setup/)列出的任何一种方法搭建一套 Kubernetes 集群。只要保证 Kubernetes 版本大于等于 v1.12。如果你使用 AWS、GKE 或者本机，下面是快速上手教程： + +* [kind 教程](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) +* [Google GKE 教程](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) +* [AWS EKS 教程](/tidb-in-kubernetes/deploy/aws-eks.md) + +如果你要使用不同环境，必须在 Kubernetes 集群中安装 DNS 插件。可以根据[官方文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/)搭建 DNS 插件。 + +TiDB Operator 使用[持久化卷](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)持久化存储 TiDB 集群数据（包括数据库，监控和备份数据），所以 Kubernetes 集群必须提供至少一种持久化卷。为提高性能，建议使用本地 SSD 盘作为持久化卷。可以根据[这一步](#配置本地持久化卷)自动配置本地持久化卷。 + +Kubernetes 集群建议启用 [RBAC](https://kubernetes.io/docs/admin/authorization/rbac)。否则，需要在 `tidb-operator` 和 `tidb-cluster` chart 的 `values.yaml` 中设置 `rbac.create` 为 `false`。 + +TiDB 默认会使用很多文件描述符，工作节点和上面的 Docker 进程的 `ulimit` 必须设置大于等于 `1048576`： + +* 设置工作节点的 `ulimit` 值，详情可以参考[如何设置 ulimit](https://access.redhat.com/solutions/61334) + + {{< copyable "shell-regular" >}} + + ```shell + sudo vim /etc/security/limits.conf + ``` + + 设置 root 账号的 `soft` 和 `hard` 的 `nofile` 大于等于 `1048576` + +* 设置 Docker 服务的 `ulimit` + + {{< copyable "shell-regular" >}} + + ```shell + sudo vim /etc/systemd/system/docker.service + ``` + + 设置 `LimitNOFILE` 大于等于 `1048576`。 + +> **注意：** +> +> `LimitNOFILE` 需要显式设置为 `1048576` 或者更大，而不是默认的 `infinity`，由于 `systemd` 的 [bug](https://github.com/systemd/systemd/commit/6385cb31ef443be3e0d6da5ea62a267a49174688#diff-108b33cf1bd0765d116dd401376ca356L1186)，`infinity` 在 `systemd` 某些版本中指的是 `65536`。 + +## 安装 Helm + +参考 [使用 Helm](/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 + +## 配置本地持久化卷 + +### 准备本地卷 + +参考[本地 PV 配置](/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)在你的 Kubernetes 集群中配置本地持久化卷。 + +## 安装 TiDB Operator + +TiDB Operator 使用 [CRD (Custom Resource Definition)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) 扩展 Kubernetes，所以要使用 TiDB Operator，必须先创建 `TidbCluster` 自定义资源类型。只需要在你的 Kubernetes 集群上创建一次即可： + +{{< copyable "shell-regular" >}} + +```shell +kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/crd.yaml && \ +kubectl get crd tidbclusters.pingcap.com +``` + +创建 `TidbCluster` 自定义资源类型后，接下来在 Kubernetes 集群上安装 TiDB Operator。 + +1. 获取你要安装的 `tidb-operator` chart 中的 `values.yaml` 文件： + + {{< copyable "shell-regular" >}} + + ```shell + mkdir -p /home/tidb/tidb-operator && \ + helm inspect values pingcap/tidb-operator --version= > /home/tidb/tidb-operator/values-tidb-operator.yaml + ``` + + > **注意：** + > + > `` 在后续文档中代表 chart 版本，例如 `v1.0.0`，可以通过 `helm search -l tidb-operator` 查看当前支持的版本。 + +2. 配置 TiDB Operator + + TiDB Operator 里面会用到 `k8s.gcr.io/kube-scheduler` 镜像，如果下载不了该镜像，可以修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 文件中的 `scheduler.kubeSchedulerImageName` 为 `registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler`。 + +3. 安装 TiDB Operator + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-operator --name=tidb-operator --namespace=tidb-admin --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml && \ + kubectl get po -n tidb-admin -l app.kubernetes.io/name=tidb-operator + ``` + +## 自定义 TiDB Operator + +通过修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 中的配置自定义 TiDB Operator。后续文档使用 `values.yaml` 指代 `/home/tidb/tidb-operator/values-tidb-operator.yaml`。 + +TiDB Operator 有两个组件： + +* tidb-controller-manager +* tidb-scheduler + +这两个组件是无状态的，通过 `Deployment` 部署。你可以在 `values.yaml` 中自定义资源 `limit`、`request` 和 `replicas`。 + +修改为 `values.yaml` 后，执行下面命令使配置生效： + +{{< copyable "shell-regular" >}} + +```shell +helm upgrade tidb-operator pingcap/tidb-operator --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml +``` diff --git a/tidb-in-kubernetes/faq.md b/tidb-in-kubernetes/faq.md new file mode 100644 index 000000000000..1f50166292c1 --- /dev/null +++ b/tidb-in-kubernetes/faq.md @@ -0,0 +1,98 @@ +--- +title: Kubernetes 上的 TiDB 集群常见问题 +category: FAQ +--- + +# Kubernetes 上的 TiDB 集群常见问题 + +本文介绍 Kubernetes 上的 TiDB 集群常见问题以及解决方案。 + +## 如何修改时区设置？ + +默认情况下，在 Kubernetes 集群上部署的 TiDB 集群各组件容器中的时区为 UTC，如果要修改时区配置，有下面两种情况： + +* 第一次部署集群 + + 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后部署 TiDB 集群。 + +* 集群已经在运行 + + 如果 TiDB 集群已经在运行，需要做如下修改： + + * 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后升级 TiDB 集群。 + * 参考[时区支持](/how-to/configure/time-zone.md)，修改 TiDB 服务时区配置。 + +## TiDB 相关组件可以配置 HPA 或 VPA 么？ + +TiDB 集群目前还不支持 HPA（Horizontal Pod Autoscaling，自动水平扩缩容）和 VPA（Vertical Pod Autoscaling，自动垂直扩缩容），因为对于数据库这种有状态应用而言，实现自动扩缩容难度较大，无法仅通过 CPU 和 memory 监控数据来简单地实现。 + +## 使用 TiDB Operator 编排 TiDB 集群时，有什么场景需要人工介入操作吗？ + +如果不考虑 Kubernetes 集群本身的运维，TiDB Operator 存在以下可能需要人工介入的场景： + +* TiKV 自动故障转移之后的集群调整，参考[自动故障转移](/tidb-in-kubernetes/maintain/auto-failover.md)； +* 维护或下线指定的 Kubernetes 节点，参考[维护节点](/tidb-in-kubernetes/maintain/kubernetes-node.md)。 + +## 在公有云上使用 TiDB Operator 编排 TiDB 集群时，推荐的部署拓扑是怎样的？ + +首先，为了实现高可用和数据安全，我们在推荐生产环境下的 TiDB 集群中至少部署在三个可用区 (Available Zone)。 + +当考虑 TiDB 集群与业务服务的部署拓扑关系时，TiDB Operator 支持下面几种部署形态。它们有各自的优势与劣势，具体选型需要根据实际业务需求进行权衡： + +* 将 TiDB 集群与业务服务部署在同一个 VPC 中的同一个 Kubernetes 集群上； +* 将 TiDB 集群与业务服务部署在同一个 VPC 中的不同 Kubernetes 集群上； +* 将 TiDB 集群与业务服务部署在不同 VPC 中的不同 Kubernetes 集群上。 + +## TiDB Operator 支持 TiSpark 吗？ + +TiDB Operator 尚不支持自动编排 TiSpark。 + +假如要为 TiDB in Kubernetes 添加 TiSpark 组件，你需要在**同一个** Kubernetes 集群中自行维护 Spark，确保 Spark 能够访问到 PD 和 TiKV 实例的 IP 与端口，并为 Spark 安装 TiSpark 插件，TiSpark 插件的安装方式可以参考 [TiSpark](/reference/tispark.md#已有-Spark-集群的部署方式)。 + +在 Kubernetes 上维护 Spark 可以参考 Spark 的官方文档：[Spark on Kubernetes](http://spark.apache.org/docs/latest/running-on-kubernetes.html)。 + +## 如何查看 TiDB 集群配置？ + +如果需要查看当前集群的 PD、TiKV、TiDB 组件的配置信息，可以执行下列命令: + +* 查看 PD 配置文件 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl exec -it -n -- cat /etc/pd/pd.toml + ``` + +* 查看 TiKV 配置文件 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl exec -it -n -- cat /etc/tikv/tikv.toml + ``` + +* 查看 TiDB 配置文件 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl exec -it -c tidb -n -- cat /etc/tidb/tidb.toml + ``` + +## 部署 TiDB 集群时调度失败是什么原因？ + +TiDB Operator 调度 Pod 失败的原因可能有三种情况： + +* 资源不足，导致 Pod 一直阻塞在 `Pending` 状态。详细说明参见[集群故障诊断](/tidb-in-kubernetes/troubleshoot.md)。 + +* 部分 Node 被打了 `taint`，导致 Pod 无法调度到对应的 Node 上。详请参考 [taint & toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)。 + +* 调度错误，导致 Pod 一直阻塞在 `ContainerCreating` 状态。这种情况发生时请检查 Kubernetes 集群中是否部署过多个 TiDB Operator。重复的 TiDB Operator 自定义调度器的存在，会导致同一个 Pod 的调度周期不同阶段会分别被不同的调度器处理，从而产生冲突。 + + 执行以下命令，如果有两条及以上记录，就说明 Kubernetes 集群中存在重复的 TiDB Operator，请根据实际情况删除多余的 TiDB Operator。 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get deployment --all-namespaces |grep tidb-scheduler + ``` diff --git a/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md b/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md new file mode 100644 index 000000000000..0a9ae9df0e8e --- /dev/null +++ b/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md @@ -0,0 +1,304 @@ +--- +title: 在 GCP 上通过 Kubernetes 部署 TiDB 集群 +summary: 在 GCP 上通过 Kubernetes 部署 TiDB 集群教程 +category: how-to +--- + +# 在 GCP 上通过 Kubernetes 部署 TiDB 集群 + +本文介绍如何使用 [TiDB Operator](https://github.com/pingcap/tidb-operator) 在 GCP 上部署 TiDB 集群。本教程需要在 [Google Cloud Shell](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/pingcap/tidb-operator&tutorial=docs/google-kubernetes-tutorial.md) 上运行。 + +所包含的步骤如下： + +- 启动一个包含 3 个节点的 Kubernetes 集群（可选） +- 安装 Kubernetes 包管理工具 Helm +- 部署 TiDB Operator +- 部署 TiDB 集群 +- 访问 TiDB 集群 +- 扩容 TiDB 集群 +- 删除 Kubernetes 集群（可选） + +> **警告：** +> +> 对于生产环境，不要使用此方式进行部署。 + +## 选择一个项目 + +本教程会启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。价格信息可以参考 [All pricing](https://cloud.google.com/compute/pricing)。 + +继续之前请选择一个项目： + + + + +## 启用 API + +本教程需要使用计算和容器 API。继续之前请启用： + + + + +## 配置 gcloud + +这一步配置 glcoud 默认访问你要用的项目和[可用区](https://cloud.google.com/compute/docs/regions-zones/)，可以简化后面用到的命令： + +{{< copyable "shell-regular" >}} + +``` shell +gcloud config set project {{project-id}} && \ +gcloud config set compute/zone us-west1-a +``` + +## 启动 3 个节点的 Kubernetes 集群 + +下面命令启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。 + +命令执行需要几分钟时间： + +{{< copyable "shell-regular" >}} + +``` shell +gcloud container clusters create tidb +``` + +集群启动完成后，将其设置为默认集群： + +{{< copyable "shell-regular" >}} + +``` shell +gcloud config set container/cluster tidb +``` + +最后验证 `kubectl` 可以访问集群并且 3 个节点正常运行： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get nodes +``` + +如果所有节点状态为 `Ready`，恭喜你，你已经成功搭建你的第一个 Kubernetes 集群。 + +## 安装 Helm + +Helm 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 + +安装 `helm`： + +{{< copyable "shell-regular" >}} + +``` shell +curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash +``` + +复制 `helm` 到你的 `$HOME` 目录下，这样即使 Google Cloud Shell 超时断开连接，再次登录后仍然可以访问 Helm： + +{{< copyable "shell-regular" >}} + +``` shell +mkdir -p ~/bin && \ +cp /usr/local/bin/helm ~/bin && \ +echo 'PATH="$PATH:$HOME/bin"' >> ~/.bashrc +``` + +Helm 正常工作需要一定的权限： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl apply -f ./manifests/tiller-rbac.yaml && \ +helm init --service-account tiller --upgrade +``` + +`tiller` 是 Helm 的服务端组件，初始化完成需要几分钟时间： + +{{< copyable "shell-regular" >}} + +``` shell +watch "kubectl get pods --namespace kube-system | grep tiller" +``` + +当 Pod 状态为 `Running`，Ctrl+C 停止并继续下一步。 + +## 添加 Helm 仓库 + +PingCAP Helm 仓库中存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。使用下面命令添加仓库： + +{{< copyable "shell-regular" >}} + +``` shell +helm repo add pingcap https://charts.pingcap.org/ && \ +helm repo list +``` + +然后你可以查看可用的 chart： + +{{< copyable "shell-regular" >}} + +``` shell +helm repo update && \ +helm search tidb-cluster -l && \ +helm search tidb-operator -l +``` + +## 部署 TiDB 集群 + +> **注意：** +> +> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 + +第一个要安装的 TiDB 组件是 TiDB Operator，TiDB Operator 是管理组件，结合 Kubernetes 启动 TiDB 集群并保证集群正常运行。执行下面命令之前请确保在 `tidb-operator` 目录下： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl apply -f ./manifests/crd.yaml && \ +kubectl apply -f ./manifests/gke/persistent-disk.yaml && \ +helm install pingcap/tidb-operator -n tidb-admin --namespace=tidb-admin --version= +``` + +可以通过下面命令观察 Operator 启动情况： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get pods --namespace tidb-admin -o wide --watch +``` + +如果 tidb-scheduler 和 tidb-controller-manager 状态都为 `Running`，Ctrl+C 停止并继续下一步部署一个 TiDB 集群！ + +## 部署你的第一个 TiDB 集群 + +我们可以一键部署一个 TiDB 集群： + +{{< copyable "shell-regular" >}} + +``` shell +helm install pingcap/tidb-cluster -n demo --namespace=tidb --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd --version= +``` + +集群启动需要几分钟时间，可以通过下面命令观察状态： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get pods --namespace tidb -o wide --watch +``` + +TiDB 集群包含 2 个 TiDB pod，3 个 TiKV pod 和 3 个 PD pod。如果所有 pod 状态都为 `Running`，Ctrl+C 停止并继续！ + +## 访问 TiDB 集群 + +从 pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get svc -n tidb --watch +``` + +如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 + +要访问 Kubernetes 集群中的 TiDB 服务，可以在 TiDB 服务和 Google Cloud Shell 之间建立一条隧道。建议这种方式只用于调试，因为如果 Google Cloud Shell 重启，隧道不会自动重新建立。要建立隧道： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl -n tidb port-forward svc/demo-tidb 4000:4000 &>/tmp/port-forward.log & +``` + +在 Cloud Shell 上运行： + +{{< copyable "shell-regular" >}} + +``` shell +sudo apt-get install -y mysql-client && \ +mysql -h 127.0.0.1 -u root -P 4000 +``` + +在 MySQL 终端中输入一条 MySQL 命令： + +{{< copyable "sql" >}} + +``` sql +select tidb_version(); +``` + +如果用 Helm 安装的过程中没有指定密码，现在可以设置： + +{{< copyable "sql" >}} + +``` sql +SET PASSWORD FOR 'root'@'%' = ''; +``` + +> **注意：** +> +> 这条命令中包含一些特殊字符，Google Cloud Shell 无法自动填充，你需要手动复制、粘贴到控制台中。 + +恭喜，你已经启动并运行一个兼容 MySQL 的分布式 TiDB 数据库！ + +## 扩容 TiDB 集群 + +我们可以一键扩容 TiDB 集群。如下命令可以扩容 TiKV： + +{{< copyable "shell-regular" >}} + +``` shell +helm upgrade demo pingcap/tidb-cluster --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd,tikv.replicas=5 --version= +``` + +TiKV 的 Pod 数量从 3 增加到了 5。可以通过下面命令查看： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get po -n tidb +``` + +## 访问 Grafana 面板 + +要访问 Grafana 面板，可以在 Grafana 服务和 shell 之间建立一条隧道，可以使用如下命令： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl -n tidb port-forward svc/demo-grafana 3000:3000 &>/dev/null & +``` + +在 Cloud Shell 中，点击 Web Preview 按钮并输入端口 3000，将打开一个新的浏览器标签页访问 Grafana 面板。或者也可以在新浏览器标签或者窗口中直接访问 URL：。 + +如果没有使用 Cloud Shell，可以在浏览器中访问 `localhost:3000`。 + +## 销毁 TiDB 集群 + +如果不再需要这个 TiDB 集群，可以使用下面命令删除集群： + +{{< copyable "shell-regular" >}} + +``` shell +helm delete demo --purge +``` + +上面的命令只会删除运行的 Pod，但是数据还会保留。如果你不再需要那些数据，可以执行下面的命令清除数据和动态创建的持久化磁盘： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl delete pvc -n tidb -l app.kubernetes.io/instance=demo,app.kubernetes.io/managed-by=tidb-operator && \ +kubectl get pv -l app.kubernetes.io/namespace=tidb,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' +``` + +## 删除 Kubernetes 集群 + +实验结束后，可以使用如下命令删除 Kubernetes 集群： + +{{< copyable "shell-regular" >}} + +``` shell +gcloud container clusters delete tidb +``` + +## 更多信息 + +我们还提供简单的[基于 Terraform 的部署方案](/tidb-in-kubernetes/deploy/gcp-gke.md)。 diff --git a/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md b/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md new file mode 100644 index 000000000000..15bf500d9458 --- /dev/null +++ b/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md @@ -0,0 +1,190 @@ +--- +title: 使用 kind 在 Kubernetes 上部署 TiDB 集群 +summary: 使用 kind 在 Kubernetes 上部署 TiDB 集群。 +category: how-to +aliases: ['/docs-cn/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-dind/'] +--- + +# 使用 kind 在 Kubernetes 上部署 TiDB 集群 + +本文介绍了如何在个人电脑（Linux 或 MacOS）上采用 [kind](https://kind.sigs.k8s.io/) 方式在 Kubernetes 上部署 [TiDB Operator](https://github.com/pingcap/tidb-operator) 和 TiDB 集群。 + +kind 通过使用 Docker 容器作为集群节点模拟出一个本地的 Kubernetes 集群。kind 的设计初衷是为了在本地进行 Kubernetes 集群的一致性测试。Kubernetes 集群版本取决于 kind 使用的镜像，你可以指定任一镜像版本用于集群节点，并在 [Docker hub](https://hub.docker.com/r/kindest/node/tags) 中找到想要部署的 Kubernetes 版本。 + +> **警告：** +> +> 对于生产环境，不要使用此方式进行部署。 + +## 环境准备 + +部署前，请确认软件、资源等满足如下需求： + +- 资源需求：CPU 2 核+、内存 4G+ + + > **注意：** + > + > 对于 macOS 系统，需要给 Docker 分配 2 核+ CPU 和 4G+ 内存。详情请参考 [Mac 上配置 Docker](https://docs.docker.com/docker-for-mac/#advanced)。 + +- [Docker](https://docs.docker.com/install/)：版本 >= 17.03 +- [Helm Client](https://helm.sh/docs/intro/install/)：版本 >= 2.9.0 并且 < 3.0.0 +- [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)：版本 >= 1.10，建议 1.13 或更高版本 + + > **注意：** + > + > 不同 kubectl 版本，输出可能略有不同。 + +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/)：版本 >= 0.4.0 +- [net.ipv4.ip_forward](https://linuxconfig.org/how-to-turn-on-off-ip-forwarding-in-linux) 需要被设置为 `1` + +## 第 1 步：通过 kind 部署 Kubernetes 集群 + +首先确认 Docker 进程正常运行，然后你可以通过脚本命令快速启动一个本地的 Kubernetes 集群。 + +1. Clone 官方提供的代码： + + {{< copyable "shell-regular" >}} + + ``` shell + git clone --depth=1 https://github.com/pingcap/tidb-operator && \ + cd tidb-operator + ``` + +2. 运行脚本，在本地创建一个 Kubernetes 集群： + + {{< copyable "shell-regular" >}} + + ``` shell + hack/kind-cluster-build.sh + ``` + + > **注意：** + > + > 通过该脚本启动的 Kubernetes 集群默认有 6 个节点，Kubernetes 版本默认为 v1.12.8，每个节点默认挂载数为 9。你可以通过启动参数去修改这些参数： + > + > {{< copyable "shell-regular" >}} + > + > ```shell + > hack/kind-cluster-build.sh --nodeNum 2 --k8sVersion v1.14.6 --volumeNum 3 + > ``` + +3. 集群创建完毕后，执行下列命令将 kubectl 的默认配置文件切换到 `kube-config`，从而连接到该本地 Kubernetes 集群： + + {{< copyable "shell-regular" >}} + + ```shell + export KUBECONFIG="$(kind get kubeconfig-path)" + ``` + +4. 查看该 kubernetes 集群信息： + + {{< copyable "shell-regular" >}} + + ``` shell + kubectl cluster-info + ``` + + 输出如下类似信息： + + ``` shell + Kubernetes master is running at https://127.0.0.1:50295 + KubeDNS is running at https://127.0.0.1:50295/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy + ``` + +5. 查看该 Kubernetes 集群的 `storageClass`： + + {{< copyable "shell-regular" >}} + + ``` shell + kubectl get storageClass + ``` + + 输出如下类似信息： + + ``` shell + NAME PROVISIONER AGE + local-storage kubernetes.io/no-provisioner 7m50s + standard (default) kubernetes.io/host-path 8m29s + ``` + +## 第 2 步：在 Kubernetes 集群上部署 TiDB Operator + +1. 安装 Helm 并配置 PingCAP 官方 chart 仓库，参考 [使用 Helm](/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 小节中的操作。 + +2. 部署 TiDB Operator，参考 [安装 TiDB Operator](/tidb-in-kubernetes/deploy/tidb-operator.md#安装-tidb-operator) 小节中的操作。 + +## 第 3 步：在 Kubernetes 集群中部署 TiDB 集群 + +参考[在标准 Kubernetes 上部署 TiDB 集群](/tidb-in-kubernetes/deploy/general-kubernetes.md#部署-tidb-集群)中的操作。 + +## 访问数据库和监控面板 + +通过 `kubectl port-forward` 暴露服务到主机，可以访问 TiDB 集群。命令中的端口格式为：`<主机端口>:`。 + +- 通过 MySQL 客户端访问 TiDB + + 在访问 TiDB 集群之前，请确保已安装 MySQL client。 + + 1. 使用 kubectl 暴露 TiDB 服务端口： + + {{< copyable "shell-regular" >}} + + ``` shell + kubectl port-forward svc/-tidb 4000:4000 --namespace= + ``` + + > **注意：** + > + > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:4000 -> 4000`。测试完成后按 `Ctrl + C` 停止代理并退出。 + + 2. 然后，通过 MySQL 客户端访问 TiDB，打开一个**新**终端标签或窗口，执行下面的命令： + + {{< copyable "shell-regular" >}} + + ``` shell + mysql -h 127.0.0.1 -P 4000 -u root + ``` + +- 查看监控面板 + + 1. 使用 kubectl 暴露 Grafana 服务端口： + + {{< copyable "shell-regular" >}} + + ``` shell + kubectl port-forward svc/-grafana 3000:3000 --namespace= + ``` + + > **注意：** + > + > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:3000 -> 3000`。测试完成后按 `Ctrl + C` 停止代理并退出。 + + 2. 然后，在浏览器中打开 访问 Grafana 监控面板： + + - 默认用户名：admin + - 默认密码：admin + + > **注意：** + > + > 如果你不是在本地 PC 而是在远程主机上部署的 kind 环境，可能无法通过 localhost 访问远程主机的服务。 + > + > 如果使用 kubectl 1.13 或者更高版本，可以在执行 `kubectl port-forward` 命令时添加 `--address 0.0.0.0` 选项，在 `0.0.0.0` 暴露端口而不是默认的 `127.0.0.1`： + > + > {{< copyable "shell-regular" >}} + > + > ``` + > kubectl port-forward --address 0.0.0.0 -n tidb svc/-grafana 3000:3000 + > ``` + > + > 然后，在浏览器中打开 `http://<远程主机 IP>:3000` 访问 Grafana 监控面板。 + +## 删除 TiDB 集群 与 Kubernetes 集群 + +删除本地 TiDB 集群可参考[销毁 TiDB 集群](/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md#销毁-kubernetes-上的-tidb-集群)。 + +通过下面命令删除该 Kubernetes 集群： + +{{< copyable "shell-regular" >}} + +``` shell +kind delete cluster +``` diff --git a/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md b/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md new file mode 100644 index 000000000000..8bf325336a53 --- /dev/null +++ b/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md @@ -0,0 +1,298 @@ +--- +title: 在 Minikube 集群上部署 TiDB 集群 +summary: 在 Minikube 集群上部署 TiDB 集群 +category: how-to +--- + +# 在 Minikube 集群上部署 TiDB 集群 + +[Minikube](https://kubernetes.io/docs/setup/minikube/) 可以让你在个人电脑上的虚拟机中创建一个 Kubernetes 集群，支持 macOS、Linux 和 Windows 系统。本文介绍如何在 Minikube 集群上部署 TiDB 集群。 + +> **警告：** +> +> - 对于生产环境，不要使用此方式进行部署。 +> +> - 尽管 Minikube 支持通过 `--vm-driver=none` 选项使用主机 Docker 而不使用虚拟机，但是目前尚没有针对 TiDB Operator 做过全面的测试，可能会无法正常工作。如果你想在不支持虚拟化的系统（例如，VPS）上试用 TiDB Operator，可以考虑使用 [kind](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)。 + +## 安装 Minikube 并启动 Kubernetes 集群 + +参考[安装 Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/)，在你的机器上安装 Minikube 1.0.0+。 + +安装完 Minikube 后，可以执行下面命令启动一个 Kubernetes 集群： + +{{< copyable "shell-regular" >}} + +``` shell +minikube start +``` + +对于中国大陆用户，可以使用国内 gcr.io mirror 仓库，例如 `registry.cn-hangzhou.aliyuncs.com/google_containers`。 + +{{< copyable "shell-regular" >}} + +``` shell +minikube start --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers +``` + +或者给 Docker 配置 HTTP/HTTPS 代理。 + +将下面命令中的 `127.0.0.1:1086` 替换为你自己的 HTTP/HTTPS 代理地址： + +{{< copyable "shell-regular" >}} + +``` shell +minikube start --docker-env https_proxy=http://127.0.0.1:1086 \ + --docker-env http_proxy=http://127.0.0.1:1086 +``` + +> **注意：** +> +> 由于 Minikube 通过虚拟机（默认）运行，`127.0.0.1` 是虚拟机本身，有些情况下你可能想要使用你的主机的实际 IP。 + +参考 [Minikube setup](https://kubernetes.io/docs/setup/minikube/) 查看配置虚拟机和 Kubernetes 集群的更多选项。 + +## 安装 kubectl 并访问集群 + +Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/user-guide/kubectl/)，可以让你执行命令访问 Kubernetes 集群。 + +参考 [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) 安装和配置 kubectl。 + +kubectl 安装完成后，测试 Minikube Kubernetes 集群： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl cluster-info +``` + +## 安装 TiDB Operator 并运行 TiDB 集群 + +### 安装 Helm + +[Helm](https://helm.sh/) 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 + +{{< copyable "shell-regular" >}} + +``` shell +curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash +``` + +安装 helm tiller： + +{{< copyable "shell-regular" >}} + +``` shell +helm init +``` + +如果无法访问 gcr.io，你可以尝试 mirror 仓库： + +{{< copyable "shell-regular" >}} + +``` shell +helm init --upgrade --tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:$(helm version --client --short | grep -Eo 'v[0-9]\.[0-9]+\.[0-9]+') +``` + +安装完成后，执行 `helm version` 会同时显示客户端和服务端组件版本： + +{{< copyable "shell-regular" >}} + +``` shell +helm version +``` + +输出类似如下内容： + +``` +Client: &version.Version{SemVer:"v2.13.1", +GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} +Server: &version.Version{SemVer:"v2.13.1", +GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} +``` + +如果只显示客户端版本，表示 `helm` 无法连接到服务端。通过 `kubectl` 查看 tiller pod 是否在运行： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl -n kube-system get pods -l app=helm +``` + +### 添加 Helm 仓库 + +Helm 仓库 (`https://charts.pingcap.org/`) 存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。可使用以下命令添加仓库： + +{{< copyable "shell-regular" >}} + +``` shell +helm repo add pingcap https://charts.pingcap.org/ && \ +helm repo list +``` + +然后可以查看可用的 chart： + +{{< copyable "shell-regular" >}} + +``` shell +helm repo update && \ +helm search tidb-cluster -l && \ +helm search tidb-operator -l +``` + +### 在 Kubernetes 集群上安装 TiDB Operator + +> **注意：** +> +> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 + +克隆 tidb-operator 代码库并安装 TiDB Operator： + +{{< copyable "shell-regular" >}} + +``` shell +git clone --depth=1 https://github.com/pingcap/tidb-operator && \ +cd tidb-operator && \ +kubectl apply -f ./manifests/crd.yaml && \ +helm install pingcap/tidb-operator --name tidb-operator --namespace tidb-admin --version= +``` + +然后，可以通过如下命令查看 TiDB Operator 的启动情况： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get pods --namespace tidb-admin -o wide --watch +``` + +如果无法访问 gcr.io（Pod 由于 ErrImagePull 无法启动），可以尝试从 mirror 仓库中拉取 kube-scheduler 镜像。可以通过以下命令升级 tidb-operator： + +{{< copyable "shell-regular" >}} + +``` shell +helm upgrade tidb-operator pingcap/tidb-operator --namespace tidb-admin --set \ + scheduler.kubeSchedulerImageName=registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler --version= +``` + +如果 tidb-scheduler 和 tidb-controller-manager 都进入 running 状态，你可以继续下一步启动一个 TiDB 集群。 + +### 启动 TiDB 集群 + +通过下面命令启动 TiDB 集群： + +{{< copyable "shell-regular" >}} + +``` shell +helm install pingcap/tidb-cluster --name demo --set \ + schedulerName=default-scheduler,pd.storageClassName=standard,tikv.storageClassName=standard,pd.replicas=1,tikv.replicas=1,tidb.replicas=1 --version= +``` + +可以通过下面命令观察集群的状态： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get pods --namespace default -l app.kubernetes.io/instance=demo -o wide --watch +``` + +通过 Ctrl+C 停止观察。 + +## 测试 TiDB 集群 + +测试 TiDB 集群之前，请确保已经安装 MySQL 客户端。从 Pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get svc --watch +``` + +如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 + +按照以下步骤访问 TiDB 集群： + +1. 转发本地端口到 TiDB 端口。 + + {{< copyable "shell-regular" >}} + + ``` shell + kubectl port-forward svc/demo-tidb 4000:4000 + ``` + +2. 在另一个终端窗口中，通过 MySQL 客户端访问 TiDB： + + {{< copyable "shell-regular" >}} + + ``` shell + mysql -h 127.0.0.1 -P 4000 -uroot + ``` + + 或者可以直接执行 SQL 命令： + + {{< copyable "shell-regular" >}} + + ``` shell + mysql -h 127.0.0.1 -P 4000 -uroot -e 'select tidb_version();' + ``` + +## 监控 TiDB 集群 + +按照以下步骤监控 TiDB 集群状态： + +1. 转发本地端口到 Grafana 端口。 + + {{< copyable "shell-regular" >}} + + ``` shell + kubectl port-forward svc/demo-grafana 3000:3000 + ``` + +2. 打开浏览器，通过 `http://localhost:3000` 访问 Grafana。 + + 或者，Minikube 提供了 `minikube service` 的方式暴露 Grafana 服务，可以更方便的接入。 + + {{< copyable "shell-regular" >}} + + ``` shell + minikube service demo-grafana + ``` + + 上述命令会自动搭建代理并在浏览器中打开 Grafana。 + +### 删除 TiDB 集群 + +通过下面命令删除 demo 集群： + +{{< copyable "shell-regular" >}} + +``` shell +helm delete --purge demo +``` + +更新 demo 集群使用的 PV 的 reclaim 策略为 Delete： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl get pv -l app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' +``` + +删除 PVC： + +{{< copyable "shell-regular" >}} + +``` shell +kubectl delete pvc -l app.kubernetes.io/managed-by=tidb-operator +``` + +## FAQ + +### Minikube 上的 TiDB 集群不响应或者响应非常慢 + +Minikube 虚拟机默认配置为 2048 MB 内存和 2 个 CPU。可以在 `minikube start` 时通过`--memory` 和 `--cpus` 选项为其分配更多资源。注意，为了使配置修改生效，你需要重新创建 Minikube 虚拟机。 + +{{< copyable "shell-regular" >}} + +``` shell +minikube delete && \ +minikube start --cpus 4 --memory 4096 ... +``` diff --git a/dev/tidb-in-kubernetes/initialize-cluster.md b/tidb-in-kubernetes/initialize-cluster.md similarity index 100% rename from dev/tidb-in-kubernetes/initialize-cluster.md rename to tidb-in-kubernetes/initialize-cluster.md diff --git a/dev/tidb-in-kubernetes/maintain/auto-failover.md b/tidb-in-kubernetes/maintain/auto-failover.md similarity index 100% rename from dev/tidb-in-kubernetes/maintain/auto-failover.md rename to tidb-in-kubernetes/maintain/auto-failover.md diff --git a/tidb-in-kubernetes/maintain/backup-and-restore.md b/tidb-in-kubernetes/maintain/backup-and-restore.md new file mode 100644 index 000000000000..15b797efac0c --- /dev/null +++ b/tidb-in-kubernetes/maintain/backup-and-restore.md @@ -0,0 +1,159 @@ +--- +title: Kubernetes 上的 TiDB 集群备份恢复 +category: how-to +--- + +# Kubernetes 上的 TiDB 集群备份与恢复 + +这篇文档详细描述了如何对 Kubernetes 上的 TiDB 集群进行数据备份和数据恢复。 + +Kubernetes 上的 TiDB 集群支持两种备份策略： + +* [全量备份](#全量备份)（定时执行或 Ad-hoc）：使用 [`mydumper`](/reference/tools/mydumper.md) 获取集群的逻辑备份； +* [增量备份](#增量备份)：使用 [`TiDB Binlog`](/reference/tidb-binlog/overview.md) 将 TiDB 集群的数据实时复制到其它数据库中或实时获得增量数据备份； + +目前，Kubernetes 上的 TiDB 集群只对 `mydumper` 获取的全量备份数据提供自动化的数据恢复操作。恢复 `TiDB-Binlog` 获取的增量数据需要手动进行。 + +## 全量备份 + +全量备份使用 `mydumper` 来获取 TiDB 集群的逻辑备份数据。全量备份任务会创建一个 PVC ([PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)) 来存储数据。 + +默认配置下，备份任务使用 PV ([Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes)) 来存储备份数据。你也可以通过修改配置将备份数据存储到 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，在这种情况下，数据在上传到对象存储前，会临时存储在 PV 中。参考 [Kubernetes 上的 TiDB 集群备份配置](/tidb-in-kubernetes/reference/configuration/backup.md) 了解所有的配置选项。 + +你可以配置一个定时执行的全量备份任务，也可以临时执行一个全量备份任务。 + +### 定时全量备份 + +定时全量备份是一个与 TiDB 集群一同创建的定时任务，它会像 `crontab` 任务那样周期性地运行。 + +你可以修改 TiDB 集群的 `values.yaml` 文件来配置定时全量备份： + +1. 将 `scheduledBackup.create` 设置为 `true`； +2. 将 `scheduledBackup.storageClassName` 设置为用于存储数据的 PV 的 `storageClass`； + + > **注意：** + > + > 你必须将定时全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 + +3. 按照 [Cron](https://en.wikipedia.org/wiki/Cron) 格式设置 `scheduledBackup.schedule` 来定义任务的执行周期与时间； +4. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) 该用户必须拥有数据备份所需的数据库相关权限，同时，将 `scheduledBackup.secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= + ``` + +5. 通过 `helm install` 创建一个配置了定时全量备份的 TiDB 集群，针对现有集群，则使用 `helm upgrade` 为集群打开定时全量备份： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` + +### Ad-hoc 全量备份 + +Ad-hoc 全量备份封装在 `pingcap/tidb-backup` 这个 Helm chart 中。根据 `values.yaml` 文件中的 `mode` 配置，该 chart 可以执行全量备份或数据恢复。我们会在[数据恢复](#数据恢复)一节中描述如何执行数据恢复。 + +你可以通过下面的步骤执行一次 Ad-hoc 全量备份： + +1. 修改 `values.yaml`： + * 将 `clusterName` 设置为目标 TiDB 集群名字； + * 将 `mode` 设置为 `backup`； + * 将 `storage.className` 设置为用于存储数据的 PV 的 `storageClass`； + * 根据数据量调整 `storage.size`； + + > **注意：** + > + > 你必须将 Ad-hoc 全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 + +2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= + ``` + +3. 使用下面的命令执行一次 Ad-hoc 全量备份： + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-backup --name= --namespace= -f values.yaml --version= + ``` + +### 查看备份 + +对于存储在 PV 中的备份，你可以使用下面的命令进行查看： + +{{< copyable "shell-regular" >}} + +```shell +kubectl get pvc -n -l app.kubernetes.io/component=backup,pingcap.com/backup-cluster-name= +``` + +假如你将数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你可以用这些存储系统自带的图形界面或命令行工具查看全量备份。 + +## 数据恢复 + + 使用 `pingcap/tidb-backup` 这个 Helm chart 进行数据恢复，步骤如下： + +1. 修改 `values.yaml`： + * 将 `clusterName` 设置为目标 TiDB 集群名； + * 将 `mode` 设置为 `restore`； + * 将 `name` 设置为用于恢复的备份名字（你可以参考[查看备份](#查看备份)来寻找可用的备份数据）。假如备份数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你必须保证这些存储的相关配置与执行[全量备份](#全量备份)时一致。 +2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`，假如你在[全量备份](#全量备份)时已经创建了该 Secret，则可以跳过这步）： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= + ``` + +3. 恢复数据： + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-backup --namespace= --name= -f values.yaml --version= + ``` + +## 增量备份 + +增量备份使用 [TiDB Binlog](/reference/tidb-binlog/overview.md) 工具从 TiDB 集群收集 Binlog，并提供实时备份和向其它数据库的实时同步能力。 + +有关 Kubernetes 上运维 TiDB Binlog 的详细指南，可参阅 [TiDB Binlog](/tidb-in-kubernetes/maintain/tidb-binlog.md)。 + +### Pump 缩容 + +缩容 Pump 需要先将单个 Pump 节点从集群中下线，然后运行 `helm upgrade` 命令将对应的 Pump Pod 删除，并对每个节点重复上述步骤。 + +1. 下线 Pump 节点： + + 假设现在有 3 个 Pump 节点，我们需要下线第 3 个 Pump 节点，将 `` 替换成 `2`，操作方式如下（`` 为当前 TiDB 的版本）。 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl run offline-pump- --image=pingcap/tidb-binlog: --namespace= --restart=OnFailure -- /binlogctl -pd-urls=http://-pd:2379 -cmd offline-pump -node-id -pump-:8250 + ``` + + 然后查看 Pump 的日志输出，输出 `pump offline, please delete my pod` 后即可确认该节点已经成功下线。 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl logs -f -n -pump- + ``` + +2. 删除对应的 Pump Pod： + + 修改 `values.yaml` 文件中 `binlog.pump.replicas` 为 `2`，然后执行如下命令来删除 Pump Pod： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` diff --git a/dev/tidb-in-kubernetes/maintain/backup-and-restore/backup-gcs.md b/tidb-in-kubernetes/maintain/backup-and-restore/backup-gcs.md similarity index 98% rename from dev/tidb-in-kubernetes/maintain/backup-and-restore/backup-gcs.md rename to tidb-in-kubernetes/maintain/backup-and-restore/backup-gcs.md index f0133698e6fb..c8d2a85636aa 100644 --- a/dev/tidb-in-kubernetes/maintain/backup-and-restore/backup-gcs.md +++ b/tidb-in-kubernetes/maintain/backup-and-restore/backup-gcs.md @@ -5,7 +5,7 @@ category: how-to # 在 Kubernetes 上备份 TiDB 集群到 GCS -本文档详细描述了如何将 Kubernetes 上 TiDB 集群的数据备份到 [Google Cloud Storage (GCS)](https://cloud.google.com/storage/docs/) 上。本文档中的“备份”，均是指全量备份（Ad-hoc 全量备份和定时全量备份），底层通过使用 [`mydumper`](/dev/reference/tools/mydumper.md) 获取集群的逻辑备份，然后再将备份数据上传到远端 GCS。 +本文档详细描述了如何将 Kubernetes 上 TiDB 集群的数据备份到 [Google Cloud Storage (GCS)](https://cloud.google.com/storage/docs/) 上。本文档中的“备份”，均是指全量备份（Ad-hoc 全量备份和定时全量备份），底层通过使用 [`mydumper`](/reference/tools/mydumper.md) 获取集群的逻辑备份，然后再将备份数据上传到远端 GCS。 ## Ad-hoc 全量备份 diff --git a/dev/tidb-in-kubernetes/maintain/backup-and-restore/backup-s3.md b/tidb-in-kubernetes/maintain/backup-and-restore/backup-s3.md similarity index 98% rename from dev/tidb-in-kubernetes/maintain/backup-and-restore/backup-s3.md rename to tidb-in-kubernetes/maintain/backup-and-restore/backup-s3.md index 790a19c89138..d91f3c49a37a 100644 --- a/dev/tidb-in-kubernetes/maintain/backup-and-restore/backup-s3.md +++ b/tidb-in-kubernetes/maintain/backup-and-restore/backup-s3.md @@ -5,7 +5,7 @@ category: how-to # 在 Kubernetes 上备份 TiDB 集群到兼容 S3 的存储 -这篇文档详细描述了如何将 Kubernetes 上的 TiDB 集群数据备份到兼容 S3 的存储上。本文档中的“备份”，均是指全量备份（Ad-hoc 全量备份和定时全量备份）。底层通过使用 [`mydumper`](/dev/reference/tools/mydumper.md) 获取集群的逻辑备份，然后在将备份数据上传到兼容 S3 的存储上。 +这篇文档详细描述了如何将 Kubernetes 上的 TiDB 集群数据备份到兼容 S3 的存储上。本文档中的“备份”，均是指全量备份（Ad-hoc 全量备份和定时全量备份）。底层通过使用 [`mydumper`](/reference/tools/mydumper.md) 获取集群的逻辑备份，然后在将备份数据上传到兼容 S3 的存储上。 ## Ad-hoc 全量备份 diff --git a/dev/tidb-in-kubernetes/maintain/backup-and-restore/restore.md b/tidb-in-kubernetes/maintain/backup-and-restore/restore.md similarity index 97% rename from dev/tidb-in-kubernetes/maintain/backup-and-restore/restore.md rename to tidb-in-kubernetes/maintain/backup-and-restore/restore.md index 9401c73e3de7..33e8934ccae4 100644 --- a/dev/tidb-in-kubernetes/maintain/backup-and-restore/restore.md +++ b/tidb-in-kubernetes/maintain/backup-and-restore/restore.md @@ -5,7 +5,7 @@ category: how-to # 恢复备份数据到 Kubernetes 上的 TiDB 集群 -本文档详细描述了如何将 Kubernetes 上通过 TiDB Operator 备份的 TiDB 集群数据恢复的具体操作过程。底层通过使用 [`loader`](/dev/reference/tools/loader.md) 来进行集群恢复。 +本文档详细描述了如何将 Kubernetes 上通过 TiDB Operator 备份的 TiDB 集群数据恢复的具体操作过程。底层通过使用 [`loader`](/reference/tools/loader.md) 来进行集群恢复。 为了更好地说明如何进行恢复，本文档提供了以下示例。示例假设备份数据来源于 Kubernetes `test1` 这个 namespace 中的 TiDB 集群 `demo1`，并将其中的一个备份数据恢复到 Kubernetes `test2` 这个 namespace 中的 TiDB 集群 `demo2`。下面是具体的操作过程： diff --git a/dev/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md b/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md similarity index 100% rename from dev/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md rename to tidb-in-kubernetes/maintain/destroy-tidb-cluster.md diff --git a/tidb-in-kubernetes/maintain/kubernetes-node.md b/tidb-in-kubernetes/maintain/kubernetes-node.md new file mode 100644 index 000000000000..b231d5195c6d --- /dev/null +++ b/tidb-in-kubernetes/maintain/kubernetes-node.md @@ -0,0 +1,239 @@ +--- +title: 维护 TiDB 集群所在的 Kubernetes 节点 +category: how-to +--- + +# 维护 TiDB 集群所在的 Kubernetes 节点 + +TiDB 是高可用数据库，可以在部分数据库节点下线的情况下正常运行，因此，我们可以安全地对底层 Kubernetes 节点进行停机维护。在具体操作时，针对 PD、TiKV 和 TiDB 实例的不同特性，我们需要采取不同的操作策略。 + +本文档将详细介绍如何对 Kubernetes 节点进行临时或长期的维护操作。 + +环境准备： + +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [`tkctl`](/tidb-in-kubernetes/reference/tools/tkctl.md) +- [`jq`](https://stedolan.github.io/jq/download/) + +> **注意：** +> +> 长期维护节点前，需要保证 Kubernetes 集群的剩余资源足够运行 TiDB 集群。 + +## 维护 PD 和 TiDB 实例所在节点 + +PD 和 TiDB 实例的迁移较快，可以采取主动驱逐实例到其它节点上的策略进行节点维护： + +1. 检查待维护节点上是否有 TiKV 实例： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get pod --all-namespaces -o wide | grep + ``` + + 假如存在 TiKV 实例，请参考[维护 TiKV 实例所在节点](#维护-tikv-实例所在节点)。 + +2. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl cordon + ``` + +3. 使用 `kubectl drain` 命令将待维护节点上的数据库实例迁移到其它节点上： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl drain --ignore-daemonsets --delete-local-data + ``` + + 运行后，该节点上的 TiDB 实例会自动迁移到其它可用节点上，PD 实例则会在 5 分钟后触发自动故障转移补齐节点。 + +4. 此时，假如希望下线该 Kubernetes 节点，则可以将该节点删除： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl delete node + ``` + + 假如希望恢复 Kubernetes 节点，则需要在恢复节点后确认其健康状态： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl get node + ``` + + 观察到节点进入 `Ready` 状态后，继续操作。 + +5. 使用 `kubectl uncordon` 命令解除节点的调度限制： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl uncordon + ``` + +6. 观察 Pod 是否全部恢复正常运行： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl get -n $namespace pod -o wide + ``` + + 或者： + + {{< copyable "shell-regular" >}} + + ```sql + watch tkctl get all + ``` + + Pod 恢复正常运行后，操作结束。 + +## 维护 TiKV 实例所在节点 + +TiKV 实例迁移较慢，并且会对集群造成一定的数据迁移负载，因此在维护 TiKV 实例所在节点前，需要根据维护需求选择操作策略： + +- 假如是维护短期内可恢复的节点，则不需要迁移 TiKV 节点，在维护结束后原地恢复节点； +- 假如是维护短期内不可恢复的节点，则需要规划 TiKV 的迁移工作。 + +### 维护短期内可恢复的节点 + +针对短期维护，我们可以通过调整 PD 集群的 `max-store-down-time` 配置来增大集群所允许的 TiKV 实例下线时间，在此时间内维护完毕并恢复 Kubernetes 节点后，所有该节点上的 TiKV 实例会自动恢复。 + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward svc/-pd 2379:2379 +``` + +{{< copyable "shell-regular" >}} + +```shell +pd-ctl -d config set max-store-down-time 10m +``` + +调整 `max-store-down-time` 到合理的值后，后续的操作方式与[维护 PD 和 TiDB 实例所在节点](#维护-pd-和-tidb-实例所在节点)相同。 + +### 维护短期内不可恢复的节点 + +针对短期内不可恢复的节点维护，如节点长期下线等情形，需要使用 `pd-ctl` 主动通知 TiDB 集群下线对应的 TiKV 实例，再手动解除 TiKV 实例与该节点的绑定。 + +1. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl cordon + ``` + +2. 查看待维护节点上的 TiKV 实例： + + {{< copyable "shell-regular" >}} + + ```shell + tkctl get -A tikv | grep + ``` + +3. 使用 `pd-ctl` 主动下线 TiKV 实例。 + + > **注意：** + > + > 下线 TiKV 实例前，需要保证集群中剩余的 TiKV 实例数不少于 PD 配置中的 TiKV 数据副本数（配置项：`max-replicas`）。假如不符合该条件，需要先操作扩容 TiKV。 + + 查看 TiKV 实例的 `store-id`： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get tc -ojson | jq '.status.tikv.stores | .[] | select ( .podName == "" ) | .id' + ``` + + 下线实例： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl port-forward svc/-pd 2379:2379 + ``` + + {{< copyable "shell-regular" >}} + + ```shell + pd-ctl -d store delete + ``` + +4. 等待 store 状态（`state_name`）转移为 `Tombstone`： + + {{< copyable "shell-regular" >}} + + ```shell + watch pd-ctl -d store + ``` + +5. 解除 TiKV 实例与节点本地盘的绑定。 + + 查询 Pod 使用的 `PesistentVolumeClaim`： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get -n pod -ojson | jq '.spec.volumes | .[] | select (.name == "tikv") | .persistentVolumeClaim.claimName' + ``` + + 删除该 `PesistentVolumeClaim`： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl delete -n pvc + ``` + +6. 删除 TiKV 实例： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl delete -n pod + ``` + +7. 观察该 TiKV 实例是否正常调度到其它节点上： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl -n get pod -o wide + ``` + + 假如待维护节点上还有其它 TiKV 实例，则重复同样的操作步骤直到所有的 TiKV 实例都迁移到其它节点上。 + +8. 确认节点不再有 TiKV 实例后，再逐出节点上的其它实例： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl drain --ignore-daemonsets --delete-local-data + ``` + +9. 再次确认节点不再有任何 TiKV、TiDB 和 PD 实例运行： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get pod --all-namespaces | grep + ``` + +10. 最后（可选），假如是长期下线节点，建议将节点从 Kubernetes 集群中删除： + + {{< copyable "shell-regular" >}} + + ```shell + kuebctl delete node + ``` + +至此，操作完成。 diff --git a/tidb-in-kubernetes/maintain/lightning.md b/tidb-in-kubernetes/maintain/lightning.md new file mode 100644 index 000000000000..b66bca4014bb --- /dev/null +++ b/tidb-in-kubernetes/maintain/lightning.md @@ -0,0 +1,143 @@ +--- +title: 恢复 Kubernetes 上的 TiDB 集群数据 +summary: 使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据。 +category: how-to +--- + +# 恢复 Kubernetes 上的 TiDB 集群数据 + +本文介绍了如何使用 [TiDB Lightning](https://github.com/pingcap/tidb-lightning) 快速恢复 Kubernetes 上的 TiDB 集群数据。 + +TiDB Lightning 包含两个组件：tidb-lightning 和 tikv-importer。在 Kubernetes 上，tikv-importer 位于 TiDB 集群的 Helm chart 内，被部署为一个副本数为 1 (`replicas=1`) 的 `StatefulSet`；tidb-lightning 位于单独的 Helm chart 内，被部署为一个 `Job`。 + +为了使用 TiDB Lightning 恢复数据，tikv-importer 和 tidb-lightning 都必须分别部署。 + +## 部署 tikv-importer + +tikv-importer 可以在一个现有的 TiDB 集群上启用，或者在新建 TiDB 集群时启用。 + +* 在新建一个 TiDB 集群时启用 tikv-importer： + + 1. 在 `tidb-cluster` 的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 + + 2. 部署该集群。 + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-cluster --name= --namespace= -f values.yaml --version= + ``` + +* 配置一个现有的 TiDB 集群以启用 tikv-importer： + + 1. 在该 TiDB 集群的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 + + 2. 升级该 TiDB 集群。 + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` + +## 部署 tidb-lightning + +1. 配置 TiDB Lightning + + 使用如下命令获得 TiDB Lightning 的默认配置。 + + {{< copyable "shell-regular" >}} + + ```shell + helm inspect values pingcap/tidb-lightning --version= > tidb-lightning-values.yaml + ``` + + tidb-lightning Helm chart 支持恢复本地或远程的备份数据。 + + * 本地模式 + + 本地模式要求 Mydumper 备份数据位于其中一个 Kubernetes 节点上。要启用该模式，你需要将 `dataSource.local.nodeName` 设置为该节点名称，将 `dataSource.local.hostPath` 设置为 Mydumper 备份数据目录路径，该路径中需要包含名为 `metadata` 的文件。 + + * 远程模式 + + 与本地模式不同，远程模式需要使用 [rclone](https://rclone.org) 将 Mydumper 备份 tarball 文件从网络存储中下载到 PV 中。远程模式能在 rclone 支持的任何云存储下工作，目前已经有以下存储进行了相关测试：[Google Cloud Storage (GCS)](https://cloud.google.com/storage/)、[AWS S3](https://aws.amazon.com/s3/) 和 [Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/)。 + + 1. 确保 `values.yaml` 中的 `dataSource.local.nodeName` 和 `dataSource.local.hostPath` 被注释掉。 + + 2. 新建一个包含 rclone 配置的 `Secret`。rclone 配置示例如下。一般只需要配置一种云存储。有关其他的云存储，请参考 [rclone 官方文档](https://rclone.org/)。 + + {{< copyable "" >}} + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: cloud-storage-secret + type: Opaque + stringData: + rclone.conf: | + [s3] + type = s3 + provider = AWS + env_auth = false + access_key_id = + secret_access_key = + region = us-east-1 + [ceph] + type = s3 + provider = Ceph + env_auth = false + access_key_id = + secret_access_key = + endpoint = + region = :default-placement + [gcs] + type = google cloud storage + # 该服务账号必须被授予 Storage Object Viewer 角色。 + # 该内容可以通过 `cat | jq -c .` 命令获取。 + service_account_credentials = + ``` + + 使用你的实际配置替换上述配置中的占位符，并将该文件存储为 `secret.yaml`。然后通过 `kubectl apply -f secret.yaml -n ` 命令创建该 `Secret`。 + + 3. 将 `dataSource.remote.storageClassName` 设置为 Kubernetes 集群中现有的一个存储类型。 + +2. 部署 TiDB Lightning + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-lightning --name= --namespace= --set failFast=true -f tidb-lightning-values.yaml --version= + ``` + +当 TiDB Lightning 未能成功恢复数据时，不能简单地直接重启进程，必须进行**手动干预**，否则将很容易出现错误。因此，tidb-lightning 的 `Job` 重启策略被设置为 `Never`。 + +> **注意：** +> +> 目前，即使数据被成功恢复，TiDB Lightning 也会[报出非零错误码并退出](https://github.com/pingcap/tidb-lightning/pull/230)，这会导致 `Job` 失败。因此，数据恢复成功与否需要通过查看 tidb-lightning pod 的日志进行确认。 + +如果 TiDB Lightning 未能成功恢复数据，需要采用以下步骤进行手动干预： + +1. 运行 `kubectl delete job -n -tidb-lightning`，删除 lightning `Job`。 + +2. 运行 `helm template pingcap/tidb-lightning --name --set failFast=false -f tidb-lightning-values.yaml | kubectl apply -n -f -`，重新创建禁用 `failFast` 的 lightning `Job`。 + +3. 当 lightning pod 重新运行时，在 lightning 容器中执行 `kubectl exec -it -n sh` 命令。 + +4. 运行 `cat /proc/1/cmdline`，获得启动脚本。 + +5. 参考[故障排除指南](/how-to/troubleshoot/tidb-lightning.md#tidb-lightning-troubleshooting)，对 lightning 进行诊断。 + +## 销毁 TiDB Lightning + +目前，TiDB Lightning 只能在线下恢复数据。当恢复过程结束、TiDB 集群需要向外部应用提供服务时，可以销毁 TiDB Lightning 以节省开支。 + +删除 tikv-importer 的步骤： + +1. 在 TiDB 集群 chart 的 `values.yaml` 文件中将 `importer.create` 设置为 `false`。 + +2. 然后运行 `helm upgrade pingcap/tidb-cluster -f values.yaml`。 + +删除 tidb-lightning 的方法： + +* 运行 `helm delete --purge`。 diff --git a/dev/tidb-in-kubernetes/maintain/log-collecting.md b/tidb-in-kubernetes/maintain/log-collecting.md similarity index 100% rename from dev/tidb-in-kubernetes/maintain/log-collecting.md rename to tidb-in-kubernetes/maintain/log-collecting.md diff --git a/dev/tidb-in-kubernetes/maintain/restart.md b/tidb-in-kubernetes/maintain/restart.md similarity index 100% rename from dev/tidb-in-kubernetes/maintain/restart.md rename to tidb-in-kubernetes/maintain/restart.md diff --git a/tidb-in-kubernetes/maintain/tidb-binlog.md b/tidb-in-kubernetes/maintain/tidb-binlog.md new file mode 100644 index 000000000000..b54ea5526a72 --- /dev/null +++ b/tidb-in-kubernetes/maintain/tidb-binlog.md @@ -0,0 +1,214 @@ +--- +title: TiDB Binlog 运维 +summary: 了解如何在 Kubernetes 上运维 TiDB 集群的 TiDB Binlog。 +category: how-to +--- + +# TiDB Binlog 运维 + +本文档介绍如何在 Kubernetes 上运维 TiDB 集群的 [TiDB Binlog](/reference/tidb-binlog/overview.md)。 + +## 运维准备 + +- [部署 TiDB Operator](/tidb-in-kubernetes/deploy/tidb-operator.md)； +- [安装 Helm](/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 并配置 PingCAP 官方 chart 仓库。 + +## 启用 TiDB 集群的 TiDB Binlog + +默认情况下，TiDB Binlog 在 TiDB 集群中处于禁用状态。若要创建一个启用 TiDB Binlog 的 TiDB 集群，或在现有 TiDB 集群中启用 TiDB Binlog，可根据以下步骤进行操作： + +1. 按照以下说明修改 `values.yaml` 文件： + + * 将 `binlog.pump.create` 的值设为 `true`。 + * 将 `binlog.drainer.create` 的值设为 `true`。 + * 将 `binlog.pump.storageClassName` 和 `binlog.drainer.storageClassName` 设为所在 Kubernetes 集群上可用的 `storageClass`。 + * 将 `binlog.drainer.destDBType` 设为所需的下游存储类型。 + + TiDB Binlog 支持三种下游存储类型： + + * PersistenceVolume：默认的下游存储类型。可通过修改 `binlog.drainer.storage` 来为 `drainer` 配置大 PV。 + + * 与 MySQL 兼容的数据库：通过将 `binlog.drainer.destDBType` 设置为 `mysql` 来启用。同时，必须在 `binlog.drainer.mysql` 中配置目标数据库的地址和凭据。 + + * Apache Kafka：通过将 `binlog.drainer.destDBType` 设置为 `kafka` 来启用。同时，必须在 `binlog.drainer.kafka` 中配置目标集群的 zookeeper 地址和 Kafka 地址。 + +2. 为 TiDB 与 Pump 组件设置亲和性和反亲和性： + + > **注意：** + > + > 如果在生产环境中开启 TiDB Binlog，建议为 TiDB 与 Pump 组件设置亲和性和反亲和性。如果在内网测试环境中尝试使用开启 TiDB Binlog，可以跳过此步。 + + 默认情况下，TiDB 的 affinity 亲和性设置为 `{}`。由于目前 Pump 组件与 TiDB 组件默认并非一一对应，当启用 TiDB Binlog 时，如果 Pump 与 TiDB 组件分开部署并出现网络隔离，而且 TiDB 组件还开启了 `ignore-error`，则会导致 TiDB 丢失 Binlog。推荐通过亲和性特性将 TiDB 组件与 Pump 部署在同一台 Node 上，同时通过反亲和性特性将 Pump 分散在不同的 Node 上，每台 Node 上至多仅需一个 Pump 实例。 + + > **注意：** + > + > `` 需要替换为目标 `tidb-cluster` 的 Helm release name。 + + * 将 `tidb.affinity` 按照如下设置： + + ```yaml + tidb: + affinity: + podAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchExpressions: + - key: "app.kubernetes.io/component" + operator: In + values: + - "pump" + - key: "app.kubernetes.io/managed-by" + operator: In + values: + - "tidb-operator" + - key: "app.kubernetes.io/name" + operator: In + values: + - "tidb-cluster" + - key: "app.kubernetes.io/instance" + operator: In + values: + - + topologyKey: kubernetes.io/hostname + ``` + + * 将 `binlog.pump.affinity` 按照如下设置： + + ```yaml + binlog: + pump: + affinity: + podAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: "app.kubernetes.io/component" + operator: In + values: + - "tidb" + - key: "app.kubernetes.io/managed-by" + operator: In + values: + - "tidb-operator" + - key: "app.kubernetes.io/name" + operator: In + values: + - "tidb-cluster" + - key: "app.kubernetes.io/instance" + operator: In + values: + - + topologyKey: kubernetes.io/hostname + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: "app.kubernetes.io/component" + operator: In + values: + - "pump" + - key: "app.kubernetes.io/managed-by" + operator: In + values: + - "tidb-operator" + - key: "app.kubernetes.io/name" + operator: In + values: + - "tidb-cluster" + - key: "app.kubernetes.io/instance" + operator: In + values: + - + topologyKey: kubernetes.io/hostname + ``` + +3. 创建一个新的 TiDB 集群或更新现有的集群： + + * 创建一个启用 TiDB Binlog 的 TiDB 新集群： + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-cluster --name= --namespace= --version= -f + ``` + + * 更新现有的 TiDB 集群以启用 TiDB Binlog： + + > **注意：** + > + > 如果设置了 TiDB 组件的亲和性，那么更新现有的 TiDB 集群将引起 TiDB 集群中的 TiDB 组件滚动更新。 + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster --version= -f + ``` + +## 部署多个 drainer + +默认情况下，仅创建一个下游 drainer。可安装 `tidb-drainer` Helm chart 来为 TiDB 集群部署多个 drainer，示例如下： + +1. 确保 PingCAP Helm 库是最新的： + + {{< copyable "shell-regular" >}} + + ```shell + helm repo update + ``` + + {{< copyable "shell-regular" >}} + + ```shell + helm search tidb-drainer -l + ``` + +2. 获取默认的 `values.yaml` 文件以方便自定义： + + {{< copyable "shell-regular" >}} + + ```shell + helm inspect values pingcap/tidb-drainer --version= > values.yaml + ``` + +3. 修改 `values.yaml` 文件以指定源 TiDB 集群和 drainer 的下游数据库。示例如下： + + ```yaml + clusterName: example-tidb + clusterVersion: v3.0.0 + storageClassName: local-storage + storage: 10Gi + config: | + detect-interval = 10 + [syncer] + worker-count = 16 + txn-batch = 20 + disable-dispatch = false + ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" + safe-mode = false + db-type = "tidb" + [syncer.to] + host = "slave-tidb" + user = "root" + password = "" + port = 4000 + ``` + + `clusterName` 和 `clusterVersion` 必须匹配所需的源 TiDB 集群。 + + 有关完整的配置详细信息，请参阅 [Kubernetes 上的 TiDB Binlog Drainer 配置](/tidb-in-kubernetes/reference/configuration/tidb-drainer.md)。 + +4. 部署 drainer： + + {{< copyable "shell-regular" >}} + + ```shell + helm install pingcap/tidb-drainer --name= --namespace= --version= -f values.yaml + ``` + + > **注意：** + > + > 该 chart 必须与源 TiDB 集群安装在相同的命名空间中。 diff --git a/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md b/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md new file mode 100644 index 000000000000..c87a4ed0effe --- /dev/null +++ b/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md @@ -0,0 +1,97 @@ +--- +title: Kubernetes 上的 TiDB 集群监控 +category: how-to +--- + +# Kubernetes 上的 TiDB 集群监控 + +基于 Kubernetes 环境部署的 TiDB 集群监控可以大体分为两个部分：对 TiDB 集群本身的监控、对 Kubernetes 集群及 TiDB Operator 的监控。本文将对两者进行简要说明。 + +## TiDB 集群的监控 + +TiDB 通过 Prometheus 和 Grafana 监控 TiDB 集群。在通过 TiDB Operator 创建新的 TiDB 集群时，对于每个 TiDB 集群，会同时创建、配置一套独立的监控系统，与 TiDB 集群运行在同一 Namespace，包括 Prometheus 和 Grafana 两个组件。 + +监控数据默认没有持久化，如果由于某些原因监控容器重启，已有的监控数据会丢失。可以在 `values.yaml` 中设置 `monitor.persistent` 为 `true` 来持久化监控数据。开启此选项时应将 `storageClass` 设置为一个当前集群中已有的存储，并且此存储应当支持将数据持久化，否则仍然会存在数据丢失的风险。 + +在 [TiDB 集群监控](/how-to/monitor/monitor-a-cluster.md)中有一些监控系统配置的细节可供参考。 + +### 查看监控面板 + +可以通过 `kubectl port-forward` 查看监控面板： + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward -n svc/-grafana 3000:3000 &>/tmp/portforward-grafana.log & +``` + +然后在浏览器中打开 [http://localhost:3000](http://localhost:3000)，默认用户名和密码都为 `admin`。 + +Grafana 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.grafana.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问面板。 + +如果不需要使用 Grafana，可以在部署时在 `values.yaml` 中将 `monitor.grafana.create` 设置为 `false` 来节省资源。这一情况下需要使用其他已有或新部署的数据可视化工具直接访问监控数据来完成可视化。 + +### 访问监控数据 + +对于需要直接访问监控数据的情况，可以通过 `kubectl port-forward` 来访问 Prometheus： + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward -n svc/-prometheus 9090:9090 &>/tmp/portforward-prometheus.log & +``` + +然后在浏览器中打开 [http://localhost:9090](http://localhost:9090)，或通过客户端工具访问此地址即可。 + +Prometheus 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.prometheus.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问监控数据。 + +## Kubernetes 的监控 + +随集群部署的 TiDB 监控只关注 TiDB 本身各组件的运行情况，并不包括对容器资源、宿主机、Kubernetes 组件和 TiDB Operator 等的监控。对于这些组件或资源的监控，需要在整个 Kubernetes 集群维度部署监控系统来实现。 + +### 宿主机监控 + +对宿主机及其资源的监控与传统的服务器物理资源监控相同。 + +如果在你的现有基础设施中已经有针对物理服务器的监控系统，只需要通过常规方法将 Kubernetes 所在的宿主机添加到现有监控系统中即可；如果没有可用的监控系统，或者希望部署一套独立的监控系统用于监控 Kubernetes 所在的宿主机，也可以使用你熟悉的任意监控系统。 + +新部署的监控系统可以运行于独立的服务器、直接运行于 Kubernetes 所在的宿主机，或运行于 Kubernetes 集群内，不同部署方式除在安装配置与资源利用上存在少许差异，在使用上并没有重大区别。 + +常见的可用于监控服务器资源的开源监控系统有： + +- [CollectD](https://collectd.org/) +- [Nagios](https://www.nagios.org/) +- [Prometheus](http://prometheus.io/) & [node_exporter](https://github.com/prometheus/node_exporter) +- [Zabbix](https://www.zabbix.com/) + +一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的监控解决方案可以选择。 + +我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 在 Kubernetes 集群内部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于 Kubernetes 自身组件的监控。 + +### Kubernetes 组件监控 + +对 Kubernetes 组件的监控可以参考[官方文档](https://kubernetes.io/docs/tasks/debug-application-cluster/resource-usage-monitoring/)提供的方案，也可以使用其他兼容 Kubernetes 的监控系统来进行。 + +一些云服务商可能提供了自己的 Kubernetes 组件监控方案，一些专门的性能监控服务商也有各自的 Kubernetes 集成方案可以选择。 + +由于 TiDB Operator 实际上是运行于 Kubernetes 中的容器，选择任一可以覆盖对 Kubernetes 容器状态及资源进行监控的监控系统即可覆盖对 TiDB Operator 的监控，无需再额外部署监控组件。 + +我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于对宿主机资源的监控。 + +## 报警配置 + +### TiDB 集群报警 + +在随 TiDB 集群部署 Prometheus 时，会自动导入一些默认的报警规则，可以通过浏览器访问 Prometheus 的 Alerts 页面查看当前系统中的所有报警规则和状态。 + +我们目前暂不支持报警规则的自定义配置，如果确实需要修改报警规则，可以手动下载 charts 进行修改。 + +默认的 Prometheus 和报警配置不能发送报警消息，如需发送报警消息，可以使用任意支持 Prometheus 报警的工具与其集成。推荐通过 [AlertManager](https://prometheus.io/docs/alerting/alertmanager/) 管理与发送报警消息。 + +如果在你的现有基础设施中已经有可用的 AlertManager 服务，可以在 `values.yaml` 文件中修改 `monitor.prometheus.alertmanagerURL` 配置其地址供 Prometheus 使用；如果没有可用的 AlertManager 服务，或者希望部署一套独立的服务，可以参考官方的[说明](https://github.com/prometheus/alertmanager)部署。 + +### Kubernetes 报警 + +如果使用 Prometheus Operator 部署针对 Kubernetes 宿主机和服务的监控，会默认配置一些告警规则，并且会部署一个 AlertManager 服务，具体的设置方法请参阅 [kube-prometheus](https://github.com/coreos/kube-prometheus) 的说明。 + +如果使用其他的工具或服务对 Kubernetes 宿主机和服务进行监控，请查阅该工具或服务提供商的对应资料。 diff --git a/tidb-in-kubernetes/reference/configuration/backup.md b/tidb-in-kubernetes/reference/configuration/backup.md new file mode 100644 index 000000000000..de40f1267d04 --- /dev/null +++ b/tidb-in-kubernetes/reference/configuration/backup.md @@ -0,0 +1,111 @@ +--- +title: Kubernetes 上的 TiDB 集群备份配置 +category: reference +--- + +# Kubernetes 上的 TiDB 集群备份配置 + +`tidb-backup` 是一个用于 Kubernetes 上 TiDB 集群备份和恢复的 Helm Chart。本文详细介绍了 `tidb-backup` 的可配置参数。 + +## `mode` + ++ 运行模式 ++ 默认："backup" ++ 可选值为 `backup`（备份集群数据）和 `restore`（恢复集群数据） + +## `clusterName` + ++ 目标集群名字 ++ 默认："demo" ++ 指定要从哪个集群进行备份或将数据恢复到哪个集群中 + +## `name` + ++ 备份名 ++ 默认值："fullbackup-"，`` 是备份的开始时间，精确到分钟 ++ 备份名用于区分不同的备份数据 + +## `secretName` + ++ 访问目标集群时使用的凭据 ++ 默认："backup-secret" ++ 该 Kubernetes Secret 中需要存储目标集群的登录用户名和密码，你可以通过以下命令来创建这个 Secret： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl create secret generic backup-secret -n --from-literal=user=root --from-literal=password= + ``` + +## `storage.className` + ++ Kubernetes StorageClass ++ 默认："local-storage" ++ 备份任务需要绑定一个持久卷 (Persistent Volume, PV) 来永久或临时存储备份数据，`StorageClass` 用于声明持久卷使用的存储类型，需要确保该 `StorageClass` 在 Kubernetes 集群中存在。 + +## `storage.size` + ++ 持久卷的空间大小 ++ 默认："100Gi" + +## `backupOptions` + ++ 备份参数 ++ 默认："--chunk-filesize=100" ++ 为备份数据时使用的 [Mydumper](https://github.com/maxbube/mydumper/blob/master/docs/mydumper_usage.rst#options) 指定额外的运行参数 + +## `restoreOptions` + ++ 恢复参数 ++ 默认："-t 16" ++ 为恢复数据时使用的 [Loader](/reference/tools/loader.md) 指定额外的运行参数 + +## `gcp.bucket` + ++ Google Cloud Storage 的 bucket 名字 ++ 默认："" ++ 用于存储备份数据到 Google Cloud Storage 上 + +> **注意：** +> +> 一旦设置了 `gcp` 下的任何参数，备份和恢复就会使用 Google Cloud Storage 进行数据存储。也就是说，假如要设置 `gcp` 下的参数，就需要保证所有 `gcp` 相关参数都得到正确配置，否则会造成备份恢复失败。 + +## `gcp.secretName` + ++ 访问 GCP 时使用的凭据 ++ 默认："" ++ 该 Kubernetes Secret 中需要存储 GCP 的 Service Account 凭据，你可以参考 [Google Cloud Documentation](https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually) 来下载凭据文件，然后通过下面的命令创建 Secret： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl create secret generic gcp-backup-secret -n --from-file=./credentials.json + ``` + +## `ceph.endpoint` + ++ Ceph 对象存储的 Endpoint ++ 默认："" ++ 用于访问 Ceph 对象存储 + +> **注意：** +> +> 一旦设置了 `ceph` 下的任何参数，备份和恢复就会使用 Ceph 对象存储进行数据存储。也就是说，假如要设置 `ceph` 下的参数，就需要保证所有 `ceph` 相关参数都得到正确配置，否则会造成备份恢复失败。 + +## `ceph.bucket` + ++ Ceph 对象存储的 bucket 名字 ++ 默认："" ++ 用于存储数据到 Ceph 对象存储上 + +## `ceph.secretName` + ++ 访问 Ceph 对象存储时使用的凭据 ++ 默认："" ++ 该 Kubernetes Secret 中需要存储访问 Ceph 时使用的 `access_key` 和 `secret_key`。可使用如下命令来创建这个 Secret： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl create secret generic ceph-backup-secret -n --from-literal=access_key= --from-literal=secret_key= + ``` diff --git a/tidb-in-kubernetes/reference/configuration/storage-class.md b/tidb-in-kubernetes/reference/configuration/storage-class.md new file mode 100644 index 000000000000..3f4f8d8cd845 --- /dev/null +++ b/tidb-in-kubernetes/reference/configuration/storage-class.md @@ -0,0 +1,280 @@ +--- +title: Kubernetes 上的持久化存储类型配置 +category: reference +aliases: ['/docs-cn/dev/tidb-in-kubernetes/reference/configuration/local-pv/'] +--- + +# Kubernetes 上的持久化存储类型配置 + +TiDB 集群中 PD、TiKV、监控等组件以及 TiDB Binlog 和备份等工具都需要使用将数据持久化的存储。Kubernetes 上的数据持久化需要使用 [PersistentVolume (PV)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)。Kubernetes 提供多种[存储类型](https://kubernetes.io/docs/concepts/storage/volumes/)，主要分为两大类： + +* 网络存储 + + 存储介质不在当前节点，而是通过网络方式挂载到当前节点。一般有多副本冗余提供高可用保证，在节点出现故障时，对应网络存储可以再挂载到其它节点继续使用。 + +* 本地存储 + + 存储介质在当前节点，通常能提供比网络存储更低的延迟，但没有多副本冗余，一旦节点出故障，数据就有可能丢失。如果是 IDC 服务器，节点故障可以一定程度上对数据进行恢复，但公有云上使用本地盘的虚拟机在节点故障后，数据是**无法找回**的。 + +PV 一般由系统管理员或 volume provisioner 自动创建，PV 与 Pod 是通过 [PersistentVolumeClaim (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) 进行关联的。普通用户在使用 PV 时并不需要直接创建 PV，而是通过 PVC 来申请使用 PV，对应的 volume provisioner 根据 PVC 创建符合要求的 PV，并将 PVC 与该 PV 进行绑定。 + +> **警告：** +> +> 为了数据安全，任何情况下都不要直接删除 PV，除非对 volume provisioner 原理非常清楚。 + +## TiDB 集群推荐存储类型 + +TiKV 自身借助 Raft 实现了数据复制，出现节点故障后，PD 会自动进行数据调度补齐缺失的数据副本，同时 TiKV 要求存储有较低的读写延迟，所以生产环境强烈推荐使用本地 SSD 存储。 + +PD 同样借助 Raft 实现了数据复制，但作为存储集群元信息的数据库，并不是 IO 密集型应用，所以一般本地普通 SAS 盘或网络 SSD 存储（例如 AWS 上 gp2 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）就可以满足要求。 + +监控组件以及 TiDB Binlog、备份等工具，由于自身没有做多副本冗余，所以为保证可用性，推荐用网络存储。其中 TiDB Binlog 的 pump 和 drainer 组件属于 IO 密集型应用，需要较低的读写延迟，所以推荐用高性能的网络存储（例如 AWS 上的 io1 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）。 + +在利用 TiDB Operator 部署 TiDB 集群或者备份工具的时候，需要持久化存储的组件都可以通过 values.yaml 配置文件中对应的 `storageClassName` 设置存储类型。不设置时默认都使用 `local-storage`。 + +## 网络 PV 配置 + +Kubernetes 1.11 及以上的版本支持[网络 PV 的动态扩容](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/)，但用户需要为相应的 `StorageClass` 开启动态扩容支持。 + +{{< copyable "shell-regular" >}} + +```shell +kubectl patch storageclass -p '{"allowVolumeExpansion": true}' +``` + +开启动态扩容后，通过下面方式对 PV 进行扩容： + +1. 修改 PVC 大小 + + 假设之前 PVC 大小是 10 Gi，现在需要扩容到 100 Gi + + {{< copyable "shell-regular" >}} + + ```shell + kubectl patch pvc -n -p '{"spec": {"resources": {"requests": {"storage": "100Gi"}}}' + ``` + +2. 查看 PV 扩容成功 + + 扩容成功后，通过 `kubectl get pvc -n ` 显示的大小仍然是初始大小，但查看 PV 大小会显示已经扩容到预期的大小。 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get pv | grep + ``` + +## 本地 PV 配置 + +Kubernetes 当前支持静态分配的本地存储。可使用 [local-static-provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner) 项目中的 `local-volume-provisioner` 程序创建本地存储对象。创建流程如下： + +1. 参考 Kubernetes 提供的[操作文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md)，在集群节点中预分配本地存储。 + +2. 部署 `local-volume-provisioner` 程序。 + + {{< copyable "shell-regular" >}} + + ```shell + kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml + ``` + + 通过下面命令查看 Pod 和 PV 状态： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get po -n kube-system -l app=local-volume-provisioner && \ + kubectl get pv | grep local-storage + ``` + + `local-volume-provisioner` 会为发现目录 (discovery directory) 下的每一个挂载点创建一个 PV。注意，在 GKE 上，默认只能创建大小为 375 GiB 的本地卷。 + +更多信息，可参阅 [Kubernetes 本地存储](https://kubernetes.io/docs/concepts/storage/volumes/#local)和 [local-static-provisioner 文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner#overview)。 + +### 最佳实践 + +- Local PV 的路径是本地存储卷的唯一标示符。为了保证唯一性并避免冲突，推荐使用设备的 UUID 来生成唯一的路径 +- 如果想要 IO 隔离，建议每个存储卷使用一块物理盘会比较恰当，在硬件层隔离 +- 如果想要容量隔离，建议每个存储卷一个分区或者每个存储卷使用一块物理盘来实现 + +更多信息，可参阅 local-static-provisioner 的[最佳实践文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/best-practices.md)。 + +### 示例 + +如果监控、TiDB Binlog、备份等组件都使用本地盘存储数据，可以挂载普通 SAS 盘，并分别创建不同的 `StorageClass` 供这些组件使用，具体操作如下： + +- 给监控数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/disks` 目录，后续创建 `local-storage` `StorageClass`。 + + > **注意：** + > + > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量。1 个目录会对应创建 1 个 PV。每个 TiDB 集群的监控数据会使用 1 个 PV。 + +- 给 TiDB Binlog 和备份数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/backup` 目录，后续创建 `backup-storage` `StorageClass`。 + + > **注意：** + > + > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量、每个集群内的 Pump 数量及备份方式。1 个目录会对应创建 1 个 PV。每个 Pump 会使用 1 个 PV，每个 drainer 会使用 1 个 PV，每次 [Ad-hoc 全量备份](/tidb-in-kubernetes/maintain/backup-and-restore.md#ad-hoc-全量备份)会使用 1 个 PV，所有[定时全量备份](/tidb-in-kubernetes/maintain/backup-and-restore.md#定时全量备份)会共用 1 个 PV。 + +- 给 PD 数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/sharedssd` 目录，后续创建 `shared-ssd-storage` `StorageClass`。 + + > **注意：** + > + > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量及每个集群内的 PD 数量。1 个目录会对应创建 1 个 PV。每个 PD 会使用一个 PV。 + +- 给 TiKV 数据使用的盘，可通过[普通挂载](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#use-a-whole-disk-as-a-filesystem-pv)方式将盘挂载到 `/mnt/ssd` 目录，后续创建 `ssd-storage` `StorageClass`。 + +盘挂载完成后，需要根据上述磁盘挂载情况修改 [`local-volume-provisioner` yaml 文件](https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml)，配置发现目录并创建必要的 `StorageClass`。以下是根据上述挂载修改的 yaml 文件示例： + +``` +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: "local-storage" +provisioner: "kubernetes.io/no-provisioner" +volumeBindingMode: "WaitForFirstConsumer" +--- +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: "ssd-storage" +provisioner: "kubernetes.io/no-provisioner" +volumeBindingMode: "WaitForFirstConsumer" +--- +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: "shared-ssd-storage" +provisioner: "kubernetes.io/no-provisioner" +volumeBindingMode: "WaitForFirstConsumer" +--- +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: "backup-storage" +provisioner: "kubernetes.io/no-provisioner" +volumeBindingMode: "WaitForFirstConsumer" +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: local-provisioner-config + namespace: kube-system +data: + nodeLabelsForPV: | + - kubernetes.io/hostname + storageClassMap: | + shared-ssd-storage: + hostDir: /mnt/sharedssd + mountDir: /mnt/sharedssd + ssd-storage: + hostDir: /mnt/ssd + mountDir: /mnt/ssd + local-storage: + hostDir: /mnt/disks + mountDir: /mnt/disks + backup-storage: + hostDir: /mnt/backup + mountDir: /mnt/backup +--- + +...... + + volumeMounts: + + ...... + + - mountPath: /mnt/ssd + name: local-ssd + mountPropagation: "HostToContainer" + - mountPath: /mnt/sharedssd + name: local-sharedssd + mountPropagation: "HostToContainer" + - mountPath: /mnt/disks + name: local-disks + mountPropagation: "HostToContainer" + - mountPath: /mnt/backup + name: local-backup + mountPropagation: "HostToContainer" + volumes: + + ...... + + - name: local-ssd + hostPath: + path: /mnt/ssd + - name: local-sharedssd + hostPath: + path: /mnt/sharedssd + - name: local-disks + hostPath: + path: /mnt/disks + - name: local-backup + hostPath: + path: /mnt/backup +...... + +``` + +最后通过 `kubectl apply` 命令部署 `local-volume-provisioner` 程序。 + +{{< copyable "shell-regular" >}} + +```shell +kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml +``` + +后续创建 TiDB 集群或备份等组件的时候，再配置相应的 `StorageClass` 供其使用。 + +## 数据安全 + +一般情况下 PVC 在使用完删除后，与其绑定的 PV 会被 provisioner 清理回收再放入资源池中被调度使用。为避免数据意外丢失，可在全局配置 `StorageClass` 的回收策略 (reclaim policy) 为 `Retain` 或者只将某个 PV 的回收策略修改为 `Retain`。`Retain` 模式下，PV 不会自动被回收。 + +* 全局配置 + + `StorageClass` 的回收策略一旦创建就不能再修改，所以只能在创建时进行设置。如果创建时没有设置，可以再创建相同 provisioner 的 `StorageClass`，例如 GKE 上默认的 pd 类型的 `StorageClass` 默认保留策略是 `Delete`，可以再创建一个名为 `pd-standard` 的保留策略是 `Retain` 的存储类型，并在创建 TiDB 集群时将相应组件的 `storageClassName` 修改为 `pd-standard`。 + + {{< copyable "" >}} + + ```yaml + apiVersion: storage.k8s.io/v1 + kind: StorageClass + metadata: + name: pd-standard + parameters: + type: pd-standard + provisioner: kubernetes.io/gce-pd + reclaimPolicy: Retain + volumeBindingMode: Immediate + ``` + +* 配置单个 PV + + {{< copyable "shell-regular" >}} + + ```shell + kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' + ``` + +> **注意：** +> +> TiDB Operator 默认会自动将 PD 和 TiKV 的 PV 保留策略修改为 `Retain` 以确保数据安全。 + +PV 保留策略是 `Retain` 时，如果确认某个 PV 的数据可以被删除，需要通过下面的操作来删除 PV 以及对应的数据： + +1. 删除 PV 对应的 PVC 对象： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl delete pvc --namespace= + ``` + +2. 设置 PV 的保留策略为 `Delete`，PV 会被自动删除并回收： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' + ``` + +要了解更多关于 PV 的保留策略可参考[修改 PV 保留策略](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/)。 diff --git a/tidb-in-kubernetes/reference/configuration/tidb-cluster.md b/tidb-in-kubernetes/reference/configuration/tidb-cluster.md new file mode 100644 index 000000000000..c454d0ea2df3 --- /dev/null +++ b/tidb-in-kubernetes/reference/configuration/tidb-cluster.md @@ -0,0 +1,212 @@ +--- +title: Kubernetes 上的 TiDB 集群配置 +category: reference +--- + +# Kubernetes 上的 TiDB 集群配置 + +本文介绍 Kubernetes 上 TiDB 集群的配置参数、资源配置，以及容灾配置。 + +## 配置参数 + +TiDB Operator 使用 Helm 部署和管理 TiDB 集群。通过 Helm 获取的配置文件默认提供了基本的配置，通过这个基本配置，可以快速启动一个 TiDB 集群。但是如果用户需要特殊配置或是用于生产环境，则需要根据以下配置参数列表手动配置对应的配置项。 + +> **注意：** +> +> 下文用 `values.yaml` 指代要修改的 TiDB 集群配置文件。 + +| 参数名 | 说明 | 默认值 | +| :----- | :---- | :----- | +| `rbac.create` | 是否启用 Kubernetes 的 RBAC | `true` | +| `clusterName` | TiDB 集群名，默认不设置该变量，`tidb-cluster` 会直接用执行安装时的 `ReleaseName` 代替 | `nil` | +| `extraLabels` | 添加额外的 labels 到 `TidbCluster` 对象 (CRD) 上，参考：[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) | `{}` | +| `schedulerName` | TiDB 集群使用的调度器 | `tidb-scheduler` | +| `timezone` | TiDB 集群默认时区 | `UTC` | +| `pvReclaimPolicy` | TiDB 集群使用的 PV (Persistent Volume)的 reclaim policy | `Retain` | +| `services[0].name` | TiDB 集群对外暴露服务的名字 | `nil` | +| `services[0].type` | TiDB 集群对外暴露服务的类型，(从 `ClusterIP`、`NodePort`、`LoadBalancer` 中选择) | `nil` | +| `discovery.image` | TiDB 集群 PD 服务发现组件的镜像，该组件用于在 PD 集群第一次启动时，为各个 PD 实例提供服务发现功能以协调启动顺序 | `pingcap/tidb-operator:v1.0.0-beta.3` | +| `discovery.imagePullPolicy` | PD 服务发现组件镜像的拉取策略 | `IfNotPresent` | +| `discovery.resources.limits.cpu` | PD 服务发现组件的 CPU 资源限额 | `250m` | +| `discovery.resources.limits.memory` | PD 服务发现组件的内存资源限额 | `150Mi` | +| `discovery.resources.requests.cpu` | PD 服务发现组件的 CPU 资源请求 | `80m` | +| `discovery.resources.requests.memory` | PD 服务发现组件的内存资源请求 | `50Mi` | +| `enableConfigMapRollout` | 是否开启 TiDB 集群自动滚动更新。如果启用，则 TiDB 集群的 ConfigMap 变更时，TiDB 集群自动更新对应组件。该配置只在 tidb-operator v1.0 及以上版本才支持 | `false` | +| `pd.config` | 配置文件格式的 PD 的配置，请参考 [`pd/conf/config.toml`](https://github.com/pingcap/pd/blob/master/conf/config.toml) 查看默认 PD 配置文件（选择对应 PD 版本的 tag），可以参考 [PD 配置文件描述](/reference/configuration/pd-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置** | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
`[replication]`
`location-labels = ["region", "zone", "rack", "host"]`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"`
    `[replication]`
    `location-labels = ["region", "zone", "rack", "host"]` | +| `pd.replicas` | PD 的 Pod 数 | `3` | +| `pd.image` | PD 镜像 | `pingcap/pd:v3.0.0-rc.1` | +| `pd.imagePullPolicy` | PD 镜像的拉取策略 | `IfNotPresent` | +| `pd.logLevel` | PD 日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[log]`
`level = "info"` | `info` | +| `pd.storageClassName` | PD 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | +| `pd.maxStoreDownTime` | `pd.maxStoreDownTime` 指一个 store 节点断开连接多长时间后状态会被标记为 `down`，当状态变为 `down` 后，store 节点开始迁移数据到其它 store 节点
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[schedule]`
`max-store-down-time = "30m"` | `30m` | +| `pd.maxReplicas` | `pd.maxReplicas` 是 TiDB 集群的数据的副本数
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[replication]`
`max-replicas = 3` | `3` | +| `pd.resources.limits.cpu` | 每个 PD Pod 的 CPU 资源限额 | `nil` | +| `pd.resources.limits.memory` | 每个 PD Pod 的内存资源限额 | `nil` | +| `pd.resources.limits.storage` | 每个 PD Pod 的存储容量限额 | `nil` | +| `pd.resources.requests.cpu` | 每个 PD Pod 的 CPU 资源请求 | `nil` | +| `pd.resources.requests.memory` | 每个 PD Pod 的内存资源请求 | `nil` | +| `pd.resources.requests.storage` | 每个 PD Pod 的存储容量请求 | `1Gi` | +| `pd.affinity` | `pd.affinity` 定义 PD 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | +| `pd.nodeSelector` | `pd.nodeSelector` 确保 PD Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | +| `pd.tolerations` | `pd.tolerations` 应用于 PD Pods，允许 PD Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | +| `pd.annotations` | 为 PD Pods 添加特定的 `annotations` | `{}` | +| `tikv.config` | 配置文件格式的 TiKV 的配置，请参考 [`tikv/etc/config-template.toml`](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 查看默认 TiKV 配置文件（选择对应 TiKV 版本的 tag），可以参考 [TiKV 配置文件描述](https://pingcap.com/docs-cn/v3.0/reference/configuration/tikv-server/configuration-file/)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置**

以下两个配置项需要显式配置：

`[storage.block-cache]`
  `shared = true`
  `capacity = "1GB"`
推荐设置：`capacity` 设置为 `tikv.resources.limits.memory` 的 50%

`[readpool.coprocessor]`
  `high-concurrency = 8`
  `normal-concurrency = 8`
  `low-concurrency = 8`
推荐设置：设置为 `tikv.resources.limits.cpu` 的 80%| TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`log-level = "info"`
配置示例：
  `config:` \|
    `log-level = "info"` | +| `tikv.replicas` | TiKV 的 Pod 数 | `3` | +| `tikv.image` | TiKV 的镜像 | `pingcap/tikv:v3.0.0-rc.1` | +| `tikv.imagePullPolicy` | TiKV 镜像的拉取策略 | `IfNotPresent` | +| `tikv.logLevel` | TiKV 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`log-level = "info"` | `info` | +| `tikv.storageClassName` | TiKV 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | +| `tikv.syncLog` | syncLog 指是否启用 raft 日志同步功能，启用该功能能保证在断电时数据不丢失
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[raftstore]`
`sync-log = true` | `true` | +| `tikv.grpcConcurrency` | 配置 gRPC server 线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[server]`
`grpc-concurrency = 4` | `4` | +| `tikv.resources.limits.cpu` | 每个 TiKV Pod 的 CPU 资源限额 | `nil` | +| `tikv.resources.limits.memory` | 每个 TiKV Pod 的内存资源限额 | `nil` | +| `tikv.resources.limits.storage` | 每个 TiKV Pod 的存储容量限额 | `nil` | +| `tikv.resources.requests.cpu` | 每个 TiKV Pod 的 CPU 资源请求 | `nil` | +| `tikv.resources.requests.memory` | 每个 TiKV Pod 的内存资源请求 | `nil` | +| `tikv.resources.requests.storage` | 每个 TiKV Pod 的存储容量请求 | `10Gi` | +| `tikv.affinity` | `tikv.affinity` 定义 TiKV 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | +| `tikv.nodeSelector` | `tikv.nodeSelector`确保 TiKV Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | +| `tikv.tolerations` | `tikv.tolerations` 应用于 TiKV Pods，允许 TiKV Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | +| `tikv.annotations` | 为 TiKV Pods 添加特定的 `annotations` | `{}` | +| `tikv.defaultcfBlockCacheSize` | 指定 block 缓存大小，block 缓存用于缓存未压缩的 block，较大的 block 缓存设置可以加快读取速度。一般推荐设置为 `tikv.resources.limits.memory` 的 30%-50%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.defaultcf]`
`block-cache-size = "1GB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `1GB` | +| `tikv.writecfBlockCacheSize` | 指定 writecf 的 block 缓存大小，一般推荐设置为 `tikv.resources.limits.memory` 的 10%-30%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.writecf]`
`block-cache-size = "256MB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `256MB` | +| `tikv.readpoolStorageConcurrency` | TiKV 存储的高优先级/普通优先级/低优先级操作的线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.storage]`
`high-concurrency = 4`
`normal-concurrency = 4`
`low-concurrency = 4` | `4` | +| `tikv.readpoolCoprocessorConcurrency` | 一般如果 `tikv.resources.limits.cpu` > 8，则 `tikv.readpoolCoprocessorConcurrency` 设置为`tikv.resources.limits.cpu` * 0.8
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.coprocessor]`
`high-concurrency = 8`
`normal-concurrency = 8`
`low-concurrency = 8` | `8` | +| `tikv.storageSchedulerWorkerPoolSize` | TiKV 调度程序的工作池大小，应在重写情况下增加，同时应小于总 CPU 核心
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[storage]`
`scheduler-worker-pool-size = 4` | `4` | +| `tidb.config` | 配置文件格式的 TiDB 的配置，请参考[配置文件](https://github.com/pingcap/tidb/blob/master/config/config.toml.example)查看默认 TiDB 配置文件（选择对应 TiDB 版本的 tag），可以参考 [TiDB 配置文件描述](/reference/configuration/tidb-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本）。这里只需要**按照配置文件中的格式修改配置**。

以下配置项需要显式配置：

`[performance]`
  `max-procs = 0`
推荐设置：`max-procs` 设置为 `tidb.resources.limits.cpu` 对应的核心数 | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"` | +| `tidb.replicas` | TiDB 的 Pod 数 | `2` | +| `tidb.image` | TiDB 的镜像 | `pingcap/tidb:v3.0.0-rc.1` | +| `tidb.imagePullPolicy` | TiDB 镜像的拉取策略 | `IfNotPresent` | +| `tidb.logLevel` | TiDB 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[log]`
`level = "info"` | `info` | +| `tidb.resources.limits.cpu` | 每个 TiDB Pod 的 CPU 资源限额 | `nil` | +| `tidb.resources.limits.memory` | 每个 TiDB Pod 的内存资源限额 | `nil` | +| `tidb.resources.requests.cpu` | 每个 TiDB Pod 的 CPU 资源请求 | `nil` | +| `tidb.resources.requests.memory` | 每个 TiDB Pod 的内存资源请求 | `nil` | +| `tidb.passwordSecretName`| 存放 TiDB 用户名及密码的 Secret 的名字，该 Secret 可以使用以下命令创建机密：`kubectl create secret generic tidb secret--from literal=root=--namespace=`，如果没有设置，则 TiDB 根密码为空 | `nil` | +| `tidb.initSql`| 在 TiDB 集群启动成功后，会执行的初始化脚本 | `nil` | +| `tidb.affinity` | `tidb.affinity` 定义 TiDB 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | +| `tidb.nodeSelector` | `tidb.nodeSelector`确保 TiDB Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | +| `tidb.tolerations` | `tidb.tolerations` 应用于 TiDB Pods，允许 TiDB Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | +| `tidb.annotations` | 为 TiDB Pods 添加特定的 `annotations` | `{}` | +| `tidb.maxFailoverCount` | TiDB 最大的故障转移数量，假设为 3 即最多支持同时 3 个 TiDB 实例故障转移 | `3` | +| `tidb.service.type` | TiDB 服务对外暴露类型 | `NodePort` | +| `tidb.service.externalTrafficPolicy` | 表示此服务是否希望将外部流量路由到节点本地或集群范围的端点。有两个可用选项：`Cluster`（默认）和 `Local`。`Cluster` 隐藏了客户端源 IP，可能导致流量需要二次跳转到另一个节点，但具有良好的整体负载分布。`Local` 保留客户端源 IP 并避免 LoadBalancer 和 NodePort 类型服务流量的第二次跳转，但存在潜在的不均衡流量传播风险。详细参考：[外部负载均衡器](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) | `nil` | +| `tidb.service.loadBalancerIP` | 指定 tidb 负载均衡 IP，某些云提供程序允许您指定loadBalancerIP。在这些情况下，将使用用户指定的loadBalancerIP创建负载平衡器。如果未指定loadBalancerIP字段，则将使用临时IP地址设置loadBalancer。如果指定loadBalancerIP但云提供程序不支持该功能，则将忽略您设置的loadbalancerIP字段 | `nil` | +| `tidb.service.mysqlNodePort` | TiDB 服务暴露的 mysql NodePort 端口 | | +| `tidb.service.exposeStatus` | TiDB 服务是否暴露状态端口 | `true` | +| `tidb.service.statusNodePort` | 指定 TiDB 服务的状态端口暴露的 `NodePort` | | +| `tidb.separateSlowLog` | 是否以 sidecar 方式运行独立容器输出 TiDB 的 SlowLog | 如果 TiDB Operator 版本 <= v1.0.0-beta.3，默认值为 `false`
如果 TiDB Operator 版本 > v1.0.0-beta.3，默认值为 `true` | +| `tidb.slowLogTailer.image` | TiDB 的 slowLogTailer 的镜像，slowLogTailer 是一个 sidecar 类型的容器，用于输出 TiDB 的 SlowLog，该配置仅在 `tidb.separateSlowLog`=`true` 时生效 | `busybox:1.26.2` | +| `tidb.slowLogTailer.resources.limits.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源限额 | `100m` | +| `tidb.slowLogTailer.resources.limits.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源限额 | `50Mi` | +| `tidb.slowLogTailer.resources.requests.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源请求 | `20m` | +| `tidb.slowLogTailer.resources.requests.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源请求 | `5Mi` | +| `tidb.plugin.enable` | 是否启用 TiDB 插件功能 | `false` | +| `tidb.plugin.directory` | 指定 TiDB 插件所在的目录 | `/plugins` | +| `tidb.plugin.list` | 指定 TiDB 加载的插件列表，plugin ID 命名规则：插件名-版本，例如：'conn_limit-1' | `[]` | +| `tidb.preparedPlanCacheEnabled` | 是否启用 TiDB 的 prepared plan 缓存
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`enabled = false` | `false` | +| `tidb.preparedPlanCacheCapacity` | TiDB 的 prepared plan 缓存数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`capacity = 100` | `100` | +| `tidb.txnLocalLatchesEnabled` | 是否启用事务内存锁，当本地事务冲突比较多时建议开启
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`enabled = false` | `false` | +| `tidb.txnLocalLatchesCapacity` | 事务内存锁的容量，Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`capacity = 10240000` | `10240000` | +| `tidb.tokenLimit` | TiDB 并发执行会话的限制
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`token-limit = 1000` | `1000` | +| `tidb.memQuotaQuery` | TiDB 查询的内存限额，默认 32GB
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`mem-quota-query = 34359738368` | `34359738368` | +| `tidb.checkMb4ValueInUtf8` | 用于控制当字符集为 utf8 时是否检查 mb4 字符
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`check-mb4-value-in-utf8 = true` | `true` | +| `tidb.treatOldVersionUtf8AsUtf8mb4` | 用于升级兼容性。设置为 `true` 将把旧版本的表/列的 `utf8` 字符集视为 `utf8mb4` 字符集
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`treat-old-version-utf8-as-utf8mb4 = true` | `true` | +| `tidb.lease` | `tidb.lease`是 TiDB Schema lease 的期限，对其更改是非常危险的，除非你明确知道可能产生的结果，否则不建议更改。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`lease = "45s"` | `45s` | +| `tidb.maxProcs` | 最大可使用的 CPU 核数，0 代表机器/Pod 上的 CPU 数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[performance]`
`max-procs = 0` | `0` | + +## 资源配置说明 + +部署前需要根据实际情况和需求，为 TiDB 集群各个组件配置资源，其中 PD、TiKV、TiDB 是 TiDB 集群的核心服务组件，在生产环境下它们的资源配置还需要按组件要求指定，具体参考：[资源配置推荐](/how-to/deploy/hardware-recommendations.md)。 + +为了保证 TiDB 集群的组件在 Kubernetes 中合理的调度和稳定的运行，建议为其设置 Guaranteed 级别的 QoS，通过在配置资源时让 limits 等于 requests 来实现, 具体参考：[配置 QoS](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/)。 + +如果使用 NUMA 架构的 CPU，为了获得更好的性能，需要在节点上开启 `Static` 的 CPU 管理策略。为了 TiDB 集群组件能独占相应的 CPU 资源，除了为其设置上述 Guaranteed 级别的 QoS 外，还需要保证 CPU 的配额必须是大于或等于 1 的整数。具体参考: [CPU 管理策略](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies)。 + +## 容灾配置说明 + +TiDB 是分布式数据库，它的容灾需要做到在任一个物理拓扑节点发生故障时，不仅服务不受影响，还要保证数据也是完整和可用。下面分别具体说明这两种容灾的配置。 + +### TiDB 服务的容灾 + +TiDB 服务容灾本质上基于 Kubernetes 的调度功能来实现的，为了优化调度，TiDB Operator 提供了自定义的调度器，该调度器通过指定的调度算法能在 host 层面，保证 TiDB 服务的容灾，而且目前 TiDB Cluster 使用该调度器作为默认调度器，设置项是上述列表中的 `schedulerName` 配置项。 + +其它层面的容灾（例如 rack，zone，region）是通过 Affinity 的 `PodAntiAffinity` 来保证，通过 `PodAntiAffinity` 能尽量避免同一组件的不同实例部署到同一个物理拓扑节点上，从而达到容灾的目的，Affinity 的使用参考：[Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity)。 + +下面是一个典型的容灾设置例子： + +{{< copyable "shell-regular" >}} + +```shell +affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + # this term works when the nodes have the label named region + - weight: 10 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/instance: + app.kubernetes.io/component: "pd" + topologyKey: "region" + namespaces: + - + # this term works when the nodes have the label named zone + - weight: 20 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/instance: + app.kubernetes.io/component: "pd" + topologyKey: "zone" + namespaces: + - + # this term works when the nodes have the label named rack + - weight: 40 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/instance: + app.kubernetes.io/component: "pd" + topologyKey: "rack" + namespaces: + - + # this term works when the nodes have the label named kubernetes.io/hostname + - weight: 80 + podAffinityTerm: + labelSelector: + matchLabels: + app.kubernetes.io/instance: + app.kubernetes.io/component: "pd" + topologyKey: "kubernetes.io/hostname" + namespaces: + - +``` + +### 数据的容灾 + +在开始数据容灾配置前，首先请阅读[集群拓扑信息配置](/how-to/deploy/geographic-redundancy/location-awareness.md)。该文档描述了 TiDB 集群数据容灾的实现原理。 + +在 Kubernetes 上支持数据容灾的功能，需要如下操作： + +* 为 PD 设置拓扑位置 Label 集合 + + > **注意：** + > + > 除 `kubernetes.io/hostname` 外，目前 PD 暂不支持名字中带 `/` 的 Label。 + + 用 Kubernetes 集群 Node 节点上描述拓扑位置的 Label 集合替换 `pd.config` 配置项中里的 `location-labels` 信息。 + +* 为 TiKV 节点设置所在的 Node 节点的拓扑信息 + + TiDB Operator 会自动为 TiKV 获取其所在 Node 节点的拓扑信息，并调用 PD 接口将这些信息设置为 TiKV 的 store labels 信息，这样 TiDB 集群就能基于这些信息来调度数据副本。 + + 如果当前 Kubernetes 集群的 Node 节点没有表示拓扑位置的 Label，或者已有的拓扑 Label 名字中带有 `/`，可以通过下面的命令手动给 Node 增加标签： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl label node region= zone= rack= kubernetes.io/hostname= + ``` + + 其中 `region`、`zone`、`rack`、`kubernetes.io/hostname` 只是举例，要添加的 Label 名字和数量可以任意定义，只要符合规范且和 `pd.config` 里的 `location-labels` 设置的 Labels 保持一致即可。 diff --git a/tidb-in-kubernetes/reference/configuration/tidb-drainer.md b/tidb-in-kubernetes/reference/configuration/tidb-drainer.md new file mode 100644 index 000000000000..05527f080efd --- /dev/null +++ b/tidb-in-kubernetes/reference/configuration/tidb-drainer.md @@ -0,0 +1,46 @@ +--- +title: Kubernetes 上的 TiDB Binlog Drainer 配置 +summary: 了解 Kubernetes 上的 TiDB Binlog Drainer 配置 +category: reference +--- + +# Kubernetes 上的 TiDB Binlog Drainer 配置 + +本文档介绍 Kubernetes 上 TiDB Binlog drainer 的配置参数。 + +## 配置参数 + +下表包含所有用于 `tidb-drainer` chart 的配置参数。关于如何配置这些参数，可参阅[使用 Helm](/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm)。 + +| 参数 | 说明 | 默认值 | +| :----- | :---- | :----- | +| `clusterName` | 源 TiDB 集群的名称 | `demo` | +| `clusterVersion` | 源 TiDB 集群的版本 | `v3.0.1` | +| `baseImage` | TiDB Binlog 的基础镜像 | `pingcap/tidb-binlog` | +| `imagePullPolicy` | 镜像的拉取策略 | `IfNotPresent` | +| `logLevel` | drainer 进程的日志级别 | `info` | +| `storageClassName` | drainer 所使用的 `storageClass`。`storageClassName` 是 Kubernetes 集群提供的一种存储，可以映射到服务质量级别、备份策略或集群管理员确定的任何策略。详情可参阅 [storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | +| `storage` | drainer Pod 的存储限制。请注意，如果 `db-type` 设为 `pd`，则应将本参数值设得大一些 | `10Gi` | +| `disableDetect` | 决定是否禁用事故检测 | `false` | +| `initialCommitTs` | 如果 drainer 没有断点，则用于初始化断点 | `0` | +| `config` | 传递到 drainer 的配置文件。详情可参阅 [drainer.toml](https://github.com/pingcap/tidb-binlog/blob/master/cmd/drainer/drainer.toml) |（见下文）| +| `resources` | drainer Pod 的资源限制和请求 | `{}` | +| `nodeSelector` | 确保 drainer Pod 仅被调度到具有特定键值对作为标签的节点上。详情可参阅 [nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | +| `tolerations` | 适用于 drainer Pod，允许将 Pod 调度到有指定 taint 的节点上。详情可参阅 [taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | +| `affinity` | 定义 drainer Pod 的调度策略和首选项。详情可参阅 [affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | + +`config` 的默认值为： + +```toml +detect-interval = 10 +compressor = "" +[syncer] +worker-count = 16 +disable-dispatch = false +ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" +safe-mode = false +txn-batch = 20 +db-type = "file" +[syncer.to] +dir = "/data/pb" +``` diff --git a/tidb-in-kubernetes/reference/tools/in-kubernetes.md b/tidb-in-kubernetes/reference/tools/in-kubernetes.md new file mode 100644 index 000000000000..81f818872c2e --- /dev/null +++ b/tidb-in-kubernetes/reference/tools/in-kubernetes.md @@ -0,0 +1,256 @@ +--- +title: Kubernetes 上的 TiDB 工具指南 +category: reference +--- + +# Kubernetes 上的 TiDB 工具指南 + +Kubernetes 上的 TiDB 运维管理需要使用一些开源工具。同时，在 Kubernetes 上使用 TiDB 生态工具时，也有特殊的操作要求。本文档详细描述 Kubernetes 上的 TiDB 相关的工具及其使用方法。 + +## 在 Kubernetes 上使用 PD Control + +[PD Control](/reference/tools/pd-control.md) 是 PD 的命令行工具，在使用 PD Control 操作 Kubernetes 上的 TiDB 集群时，需要先使用 `kubectl port-forward` 打开本地到 PD 服务的连接： + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & +``` + +执行上述命令后，就可以通过 `127.0.0.1:2379` 访问到 PD 服务，从而直接使用 `pd-ctl` 命令的默认参数执行操作，如： + +{{< copyable "shell-regular" >}} + +```shell +pd-ctl -d config show +``` + +假如你本地的 2379 被占据，则需要选择其它端口： + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & +``` + +此时，需要为 `pd-ctl` 命令显式指定 PD 端口： + +{{< copyable "shell-regular" >}} + +```shell +pd-ctl -u 127.0.0.1: -d config show +``` + +## 在 Kubernetes 上使用 TiKV Control + +[TiKV Control](/reference/tools/tikv-control.md) 是 TiKV 的命令行工具。在使用 TiKV Control 操作 Kubernetes 上的 TiDB 集群时，针对 TiKV Control 的不同操作模式，有不同的操作步骤。 + +* **远程模式**：此模式下 `tikv-ctl` 命令需要通过网络访问 TiKV 服务或 PD 服务，因此需要先使用 `kubectl port-forward` 打开本地到 PD 服务以及目标 TiKV 节点的连接： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & + ``` + + {{< copyable "shell-regular" >}} + + ```shell + kubectl port-forward -n 20160:20160 &>/tmp/portforward-tikv.log & + ``` + + 打开连接后，即可通过本地的对应端口访问 PD 服务和 TiKV 节点： + + {{< copyable "shell-regular" >}} + + ```shell + $ tikv-ctl --host 127.0.0.1:20160 + ``` + + {{< copyable "shell-regular" >}} + + ```shell + tikv-ctl --pd 127.0.0.1:2379 compact-cluster + ``` + +* **本地模式**：本地模式需要访问 TiKV 的数据文件，并且需要停止正在运行的 TiKV 实例。需要先使用[诊断模式](/tidb-in-kubernetes/troubleshoot.md#诊断模式)关闭 TiKV 实例自动重启，关闭 TiKV 进程，再使用 `tkctl debug` 命令在目标 TiKV Pod 中启动一个包含 `tikv-ctl` 可执行文件的新容器来执行操作，步骤如下： + + 1. 进入诊断模式： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl annotate pod -n runmode=debug + ``` + + 2. 关闭 TiKV 进程： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl exec -n -c tikv -- kill -s TERM 1 + ``` + + 3. 启动 debug 容器： + + {{< copyable "shell-regular" >}} + + ```shell + tkctl debug -c tikv + ``` + + 4. 开始使用 `tikv-ctl` 的本地模式，需要注意的是 `tikv` 容器的根文件系统在 `/proc/1/root` 下，因此执行命令时也需要调整数据目录的路径： + + {{< copyable "shell-regular" >}} + + ```shell + tikv-ctl --db /path/to/tikv/db size -r 2 + ``` + + Kubernetes 上 TiKV 实例在 debug 容器中的的默认 db 路径是 `/proc/1/root/var/lib/tikv/db size -r 2` + +## 在 Kubernetes 上使用 TiDB Control + +[TiDB Control](/reference/tools/tidb-control.md) 是 TiDB 的命令行工具，使用 TiDB Control 时，需要从本地访问 TiDB 节点和 PD 服务，因此建议使用 `kubectl port-forward` 打开到集群中 TiDB 节点和 PD 服务的连接： + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & +``` + +{{< copyable "shell-regular" >}} + +```shell +kubectl port-forward -n 10080:10080 &>/tmp/portforward-tidb.log & +``` + +接下来便可开始使用 `tidb-ctl` 命令： + +{{< copyable "shell-regular" >}} + +```shell +tidb-ctl schema in mysql +``` + +## 使用 Helm + +[Helm](https://helm.sh/) 是一个 Kubernetes 的包管理工具，你可以参考 [Helm 官方文档](https://github.com/helm/helm#install) 安装 Helm，步骤如下： + +1. 安装 Helm 客户端 + + {{< copyable "shell-regular" >}} + + ```shell + curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash + ``` + + 如果使用 macOS，可以通过 homebrew 安装 Helm：`brew install kubernetes-helm`。 + +2. 安装 Helm 服务端 + + {{< copyable "shell-regular" >}} + + 在集群中应用 helm 服务端组件 `tiller` 所需的 `RBAC` 规则并安装 `tiller`： + + ```shell + kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/tiller-rbac.yaml && \ + helm init --service-account=tiller --upgrade + ``` + + 通过下面命令确认 `tiller` Pod 进入 running 状态： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get po -n kube-system -l name=tiller + ``` + + 如果 Kubernetes 集群没有启用 `RBAC`，那么可以直接使用下列命令安装 `tiller`： + + {{< copyable "shell-regular" >}} + + ```shell + helm init --upgrade + ``` + +Kubernetes 应用在 helm 中被打包为 chart。PingCAP 针对 Kubernetes 上的 TiDB 部署运维提供了三个 Helm chart： + +* `tidb-operator`：用于部署 TiDB Operator； +* `tidb-cluster`：用于部署 TiDB 集群； +* `tidb-backup`：用于 TiDB 集群备份恢复； + +这些 chart 都托管在 PingCAP 维护的 helm chart 仓库 `https://charts.pingcap.org/` 中，你可以通过下面的命令添加该仓库： + +{{< copyable "shell-regular" >}} + +```shell +helm repo add pingcap https://charts.pingcap.org/ +``` + +添加完成后，可以使用 `helm search` 搜索 PingCAP 提供的 chart： + +{{< copyable "shell-regular" >}} + +```shell +helm search pingcap -l +``` + +``` +NAME CHART VERSION APP VERSION DESCRIPTION +pingcap/tidb-backup v1.0.0 A Helm chart for TiDB Backup or Restore +pingcap/tidb-cluster v1.0.0 A Helm chart for TiDB Cluster +pingcap/tidb-operator v1.0.0 tidb-operator Helm chart for Kubernetes +``` + +当新版本的 chart 发布后，你可以使用 `helm repo update` 命令更新本地对于仓库的缓存： + +{{< copyable "shell-regular" >}} + +``` +helm repo update +``` + +Helm 的常用操作有部署（`helm install`）、升级（`helm upgrade`)、销毁（`helm del`)、查询（`helm ls`）。Helm chart 往往都有很多可配置参数，通过命令行进行配置比较繁琐，因此推荐使用 YAML 文件的形式来编写这些配置项，基于 Helm 社区约定俗称的命名方式，我们在文档中将用于配置 chart 的 YAML 文件称为 `values.yaml` 文件。 + +执行部署、升级、销毁等操作前，可以使用 `helm ls` 查看集群中已部署的应用： + +{{< copyable "shell-regular" >}} + +```shell +helm ls +``` + +在执行部署和升级操作时，必须指定使用的 chart 名字（`chart-name`）和部署后的应用名（`release-name`），还可以指定一个或多个 `values.yaml` 文件来配置 chart。此外，假如对 chart 有特定的版本需求，则需要通过 `--version` 参数指定 `chart-version` (默认为最新的 GA 版本）。命令形式如下： + +* 执行安装： + + {{< copyable "shell-regular" >}} + + ```shell + helm install --name= --namespace= --version= -f + ``` + +* 执行升级（升级可以是修改 `chart-version` 升级到新版本的 chart，也可以是修改 `values.yaml` 文件更新应用配置）： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade --version= -f + ``` + +最后，假如要删除 helm 部署的应用，可以执行： + +{{< copyable "shell-regular" >}} + +```shell +helm del --purge +``` + +更多 helm 的相关文档，请参考 [Helm 官方文档](https://helm.sh/docs/)。 + +## 使用 Terraform + +[Terraform](https://www.terraform.io/) 是一个基础设施即代码（Infrastructure as Code）管理工具。它允许用户使用声明式的风格描述自己的基础设施，并针对描述生成执行计划来创建或调整真实世界的计算资源。Kubernetes 上的 TiDB 使用 Terraform 来在公有云上创建和管理 TiDB 集群。 + +你可以参考 [Terraform 官方文档](https://www.terraform.io/downloads.html) 来安装 Terraform。 diff --git a/dev/tidb-in-kubernetes/reference/tools/tkctl.md b/tidb-in-kubernetes/reference/tools/tkctl.md similarity index 100% rename from dev/tidb-in-kubernetes/reference/tools/tkctl.md rename to tidb-in-kubernetes/reference/tools/tkctl.md diff --git a/tidb-in-kubernetes/scale-in-kubernetes.md b/tidb-in-kubernetes/scale-in-kubernetes.md new file mode 100644 index 000000000000..ecdd3bc6fd6c --- /dev/null +++ b/tidb-in-kubernetes/scale-in-kubernetes.md @@ -0,0 +1,72 @@ +--- +title: Kubernetes 上的 TiDB 集群扩缩容 +category: how-to +--- + +# Kubernetes 上的 TiDB 集群扩缩容 + +本文介绍 TiDB 在 Kubernetes 中如何进行水平扩缩容和垂直扩缩容。 + +## 水平扩缩容 + +TiDB 水平扩缩容操作指的是通过增加或减少节点的数量，来达到集群扩缩容的目的。扩缩容 TiDB 集群时，会按照填入的 replicas 值，对 PD、TiKV、TiDB 进行顺序扩缩容操作。扩容操作按照节点编号由小到大增加节点，缩容操作按照节点编号由大到小删除节点。 + +### 水平扩缩容操作 + +1. 修改集群的 `value.yaml` 文件中的 `pd.replicas`、`tidb.replicas`、`tikv.replicas` 至期望值。 + +2. 执行 `helm upgrade` 命令进行扩缩容： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` + +3. 查看集群水平扩缩容状态： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl -n get pod -o wide + ``` + + 当所有组件的 Pod 数量都达到了预设值，并且都进入 `Running` 状态后，水平扩缩容完成。 + +> **注意：** +> +> - PD、TiKV 组件在滚动升级的过程中不会触发扩缩容操作。 +> - TiKV 组件在缩容过程中会调用 PD 接口将对应 TiKV 标记为下线，然后将其上数据迁移到其它 TiKV 节点，在数据迁移期间 TiKV Pod 依然是 `Running` 状态，数据迁移完成后对应 Pod 才会被删除，缩容时间与待缩容的 TiKV 上的数据量有关，可以通过 `kubectl get tidbcluster -n -o json | jq '.status.tikv.stores'` 查看 TiKV 是否处于下线 `Offline` 状态。 +> - PD、TiKV 组件在缩容过程中被删除的节点的 PVC 会保留，并且由于 PV 的 `Reclaim Policy` 设置为 `Retain`，即使 PVC 被删除，数据依然可以找回。 +> - TiKV 组件不支持在缩容过程中进行扩容操作，强制执行此操作可能导致集群状态异常。假如异常已经发生，可以参考 [TiKV Store 异常进入 Tombstone 状态](/tidb-in-kubernetes/troubleshoot.md#tikv-store-异常进入-tombstone-状态) 进行解决。 + +## 垂直扩缩容 + +垂直扩缩容操作指的是通过增加或减少节点的资源限制，来达到集群扩缩容的目的。垂直扩缩容本质上是节点滚动升级的过程。 + +### 垂直扩缩容操作 + +1. 修改 `values.yaml` 文件中的 `tidb.resources`、`tikv.resources`、`pd.resources` 至期望值。 + +2. 执行 `helm upgrade` 命令进行升级： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` + +3. 查看升级进度： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl -n get pod -o wide + ``` + + 当所有 Pod 都重建完毕进入 `Running` 状态后，垂直扩缩容完成。 + +> **注意：** +> +> - 如果在垂直扩容时修改了资源的 `requests` 字段，由于 PD、TiKV 使用了 `Local PV`，升级后还需要调度回原节点，如果原节点资源不够，则会导致 Pod 一直处于 `Pending` 状态而影响服务。 +> - TiDB 作为一个可水平扩展的数据库，推荐通过增加节点个数发挥 TiDB 集群可水平扩展的优势，而不是类似传统数据库升级节点硬件配置来实现垂直扩容。 diff --git a/tidb-in-kubernetes/tidb-operator-overview.md b/tidb-in-kubernetes/tidb-operator-overview.md new file mode 100644 index 000000000000..56e94a4f8061 --- /dev/null +++ b/tidb-in-kubernetes/tidb-operator-overview.md @@ -0,0 +1,76 @@ +--- +title: TiDB Operator 简介 +category: reference +--- + +# TiDB Operator 简介 + +TiDB Operator 是 Kubernetes 上的 TiDB 集群自动运维系统，提供包括部署、升级、扩缩容、备份恢复、配置变更的 TiDB 全生命周期管理。借助 TiDB Operator，TiDB 可以无缝运行在公有云或私有部署的 Kubernetes 集群上。 + +> **注意：** +> +> 每个 Kubernetes 集群中只能部署一个 TiDB Operator。 + +## TiDB Operator 整体架构 + +![TiDB Operator Overview](/media/tidb-operator-overview.png) + +其中，`TidbCluster` 是由 CRD（`CustomResourceDefinition`）定义的自定义资源，用于描述用户期望的 TiDB 集群状态。TiDB 集群的编排和调度逻辑则由下列组件负责： + +* `tidb-controller-manager` 是一组 Kubernetes 上的自定义控制器。这些控制器会不断对比 `TidbCluster` 对象中记录的期望状态与 TiDB 集群的实际状态，并调整 Kubernetes 中的资源以驱动 TiDB 集群满足期望状态； +* `tidb-scheduler` 是一个 Kubernetes 调度器扩展，它为 Kubernetes 调度器注入 TiDB 集群特有的调度逻辑。 + +此外，TiDB Operator 还提供了命令行接口 `tkctl` 用于运维集群和诊断集群问题。 + +![TiDB Operator Control Flow](/media/tidb-operator-control-flow.png) + +上图是 TiDB Operator 的控制流程解析。由于 TiDB 集群还需要监控、初始化、定时备份、Binlog 等组件，TiDB Operator 中使用 Helm Chart 封装了 TiDB 集群定义。整体的控制流程如下： + +1. 用户通过 Helm 创建 `TidbCluster` 对象和相应的一系列 Kubernetes 原生对象，比如执行定时备份的 `CronJob`； +2. TiDB Operator 会 watch `TidbCluster` 以及其它相关对象，基于集群的实际状态不断调整 PD、TiKV、TiDB 的 `StatefulSet` 和 `Service` 对象； +3. Kubernetes 的原生控制器根据 `StatefulSet`、`Deployment`、`CronJob` 等对象创建更新或删除对应的 `Pod`； +4. PD、TiKV、TiDB 的 `Pod` 声明中会指定使用 `tidb-scheduler` 调度器，`tidb-scheduler` 会在调度对应 `Pod` 时应用 TiDB 的特定调度逻辑。 + +基于上述的声明式控制流程，TiDB Operator 能够自动进行集群节点健康检查和故障恢复。部署、升级、扩缩容等操作也可以通过修改 `TidbCluster` 对象声明“一键”完成。 + +## 使用 TiDB Operator 管理 TiDB 集群 + +TiDB Operator 提供了多种方式来部署 Kubernetes 上的 TiDB 集群： + ++ 测试环境： + - [kind](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：采用 [kind](https://kind.sigs.k8s.io/) 方式在本地 Kubernetes 集群上部署 TiDB 集群； + - [Minikube](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：使用 TiDB Operator 在本地 Minikube 环境部署 TiDB 集群； + - [GKE](/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md)：使用 TiDB Operator 在 GKE 上部署 TiDB 集群。 + ++ 生产环境： + + - 公有云：参考 [AWS 部署文档](/tidb-in-kubernetes/deploy/aws-eks.md)，[GKE 部署文档 (beta)](/tidb-in-kubernetes/deploy/gcp-gke.md)，或[阿里云部署文档](/tidb-in-kubernetes/deploy/alibaba-cloud.md)在对应的公有云上一键部署生产可用的 TiDB 集群并进行后续的运维管理； + + - 现有 Kubernetes 集群：首先按照[部署 TiDB Operator](/tidb-in-kubernetes/deploy/tidb-operator.md)在集群中安装 TiDB Operator，再根据[在标准 Kubernetes 集群上部署 TiDB 集群](/tidb-in-kubernetes/deploy/general-kubernetes.md)来部署你的 TiDB 集群。对于生产级 TiDB 集群，你还需要参考 [TiDB 集群环境要求](/tidb-in-kubernetes/deploy/prerequisites.md)调整 Kubernetes 集群配置并根据[本地 PV 配置](/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)为你的 Kubernetes 集群配置本地 PV，以满足 TiKV 的低延迟本地存储需求。 + +在任何环境上部署前，都可以参考 [TiDB 集群配置](/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)来自定义 TiDB 配置。 + +部署完成后，你可以参考下面的文档进行 Kubernetes 上 TiDB 集群的使用和运维： + ++ [部署 TiDB 集群](/tidb-in-kubernetes/deploy/general-kubernetes.md) ++ [访问 TiDB 集群](/tidb-in-kubernetes/deploy/access-tidb.md) ++ [TiDB 集群扩缩容](/tidb-in-kubernetes/scale-in-kubernetes.md) ++ [TiDB 集群升级](/tidb-in-kubernetes/upgrade/tidb-cluster.md#升级-tidb-版本) ++ [TiDB 集群配置变更](/tidb-in-kubernetes/upgrade/tidb-cluster.md#更新-tidb-集群配置) ++ [TiDB 集群备份恢复](/tidb-in-kubernetes/maintain/backup-and-restore.md) ++ [配置 TiDB 集群故障自动转移](/tidb-in-kubernetes/maintain/auto-failover.md) ++ [监控 TiDB 集群](/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) ++ [TiDB 集群日志收集](/tidb-in-kubernetes/maintain/log-collecting.md) ++ [维护 TiDB 所在的 Kubernetes 节点](/tidb-in-kubernetes/maintain/kubernetes-node.md) + +当集群出现问题需要进行诊断时，你可以： + ++ 查阅 [Kubernetes 上的 TiDB FAQ](/tidb-in-kubernetes/faq.md) 寻找是否存在现成的解决办法； ++ 参考 [Kubernetes 上的 TiDB 故障诊断](/tidb-in-kubernetes/troubleshoot.md)解决故障。 + +Kubernetes 上的 TiDB 提供了专用的命令行工具 `tkctl` 用于集群管理和辅助诊断，同时，在 Kubernetes 上，TiDB 的部分生态工具的使用方法也有所不同，你可以： + ++ 参考 [`tkctl` 使用指南](/tidb-in-kubernetes/reference/tools/tkctl.md) 来使用 `tkctl`； ++ 参考 [Kubernetes 上的 TiDB 相关工具使用指南](/tidb-in-kubernetes/reference/tools/in-kubernetes.md)来了解 TiDB 生态工具在 Kubernetes 上的使用方法。 + +最后，当 TiDB Operator 发布新版本时，你可以参考[升级 TiDB Operator](/tidb-in-kubernetes/upgrade/tidb-operator.md) 进行版本更新。 diff --git a/tidb-in-kubernetes/troubleshoot.md b/tidb-in-kubernetes/troubleshoot.md new file mode 100644 index 000000000000..46a4626bd774 --- /dev/null +++ b/tidb-in-kubernetes/troubleshoot.md @@ -0,0 +1,372 @@ +--- +title: Kubernetes 上的 TiDB 集群故障诊断 +category: how-to +--- + +# Kubernetes 上的 TiDB 集群故障诊断 + +本文介绍了 Kubernetes 上 TiDB 集群的一些常见故障以及诊断解决方案。 + +## 诊断模式 + +当 Pod 处于 `CrashLoopBackoff` 状态时，Pod 内会容器不断退出，导致无法正常使用 `kubectl exec` 或 `tkctl debug`，给诊断带来不便。为了解决这个问题，TiDB in Kubernetes 提供了 PD/TiKV/TiDB Pod 诊断模式。在诊断模式下，Pod 内的容器启动后会直接挂起，不会再进入重复 Crash 的状态，此时，便可以通过 `kubectl exec` 或 `tkctl debug` 连接 Pod 内的容器进行诊断。 + +操作方式： + +首先，为待诊断的 Pod 添加 Annotation： + +{{< copyable "shell-regular" >}} + +```shell +kubectl annotate pod -n runmode=debug +``` + +在 Pod 内的容器下次重启时，会检测到该 Annotation，进入诊断模式。等待 Pod 进入 Running 状态即可开始诊断： + +{{< copyable "shell-regular" >}} + +```shell +watch kubectl get pod -n +``` + +下面是使用 `kubectl exec` 进入容器进行诊断工作的例子： + +{{< copyable "shell-regular" >}} + +```shell +kubectl exec -it -n -- /bin/sh +``` + +诊断完毕，修复问题后，删除 Pod： + +```shell +kubectl delete pod -n +``` + +Pod 重建后会自动回到正常运行模式。 + +## 集群意外删除后恢复 + +TiDB Operator 使用 PV (Persistent Volume)、PVC (Persistent Volume Claim) 来存储持久化的数据，如果不小心使用 `helm delete` 意外删除了集群，PV/PVC 对象以及数据都会保留下来，以最大程度保证数据安全。 + +此时集群恢复的办法就是使用 `helm install` 命令来创建一个同名的集群，之前保留下来未被删除的 PV/PVC 以及数据会被复用： + +{{< copyable "shell-regular" >}} + +```shell +helm install pingcap/tidb-cluster -n --namespace= --version= -f values.yaml +``` + +## Pod 未正常创建 + +通过 `helm install` 创建集群后，如果 Pod 没有创建，则可以通过以下方式进行诊断： + +{{< copyable "shell-regular" >}} + +```shell +kubectl get tidbclusters -n +kubectl get statefulsets -n +kubectl describe statefulsets -n -pd +``` + +## Pod 之间网络不通 + +针对 TiDB 集群而言，绝大部分 Pod 间的访问均通过 Pod 的域名（使用 Headless Service 分配）进行，例外的情况是 TiDB Operator 在收集集群信息或下发控制指令时，会通过 PD Service 的 `service-name` 访问 PD 集群。 + +当通过日志或监控确认 Pod 间存在网络连通性问题，或根据故障情况推断出 Pod 间网络连接可能不正常时，可以按照下面的流程进行诊断，逐步缩小问题范围： + +1. 确认 Service 和 Headless Service 的 Endpoints 是否正常： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl -n get endpoints -pd + kubectl -n get endpoints -tidb + kubectl -n get endpoints -pd-peer + kubectl -n get endpoints -tikv-peer + kubectl -n get endpoints -tidb-peer + ``` + + 以上命令展示的 `ENDPOINTS` 字段中，应当是由逗号分隔的 `cluster_ip:port` 列表。假如字段为空或不正确，请检查 Pod 的健康状态以及 `kube-controller-manager` 是否正常工作。 + +2. 进入 Pod 的 Network Namespace 诊断网络问题： + + {{< copyable "shell-regular" >}} + + ``` + tkctl debug -n + ``` + + 远端 shell 启动后，使用 `dig` 命令诊断 DNS 解析，假如 DNS 解析异常，请参照[诊断 Kubernetes DNS 解析](https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/)进行故障排除： + + {{< copyable "shell-regular" >}} + + ```shell + dig + ``` + + 使用 `ping` 命令诊断到目的 IP 的三层网络是否连通（目的 IP 为使用 `dig` 解析出的 ClusterIP）: + + {{< copyable "shell-regular" >}} + + ```shell + ping + ``` + + 假如 ping 检查失败，请参照[诊断 Kubernetes 网络](https://www.praqma.com/stories/debugging-kubernetes-networking/)进行故障排除。 + + 假如 ping 检查正常，继续使用 `telnet` 检查目标端口是否打开： + + {{< copyable "shell-regular" >}} + + ```shell + telnet + ``` + + 假如 `telnet` 检查失败，则需要验证 Pod 的对应端口是否正确暴露以及应用的端口是否配置正确： + + {{< copyable "shell-regular" >}} + + ```shell + # 检查端口是否一致 + kubectl -n get po -ojson | jq '.spec.containers[].ports[].containerPort' + + # 检查应用是否被正确配置服务于指定端口上 + # PD, 未配置时默认为 2379 端口 + kubectl -n -it exec -- cat /etc/pd/pd.toml | grep client-urls + # TiKV, 未配置时默认为 20160 端口 + kubectl -n -it exec -- cat /etc/tikv/tikv.toml | grep addr + # TiDB, 未配置时默认为 4000 端口 + kubectl -n -it exec -- cat /etc/tidb/tidb.toml | grep port + ``` + +## Pod 处于 Pending 状态 + +Pod 处于 Pending 状态，通常都是资源不满足导致的，比如： + +* 使用持久化存储的 PD、TiKV、Monitor Pod 使用的 PVC 的 StorageClass 不存在或 PV 不足 +* Kubernetes 集群中没有节点能满足 Pod 申请的 CPU 或内存 +* PD 或者 TiKV Replicas 数量和集群内节点数量不满足 tidb-scheduler 高可用调度策略 + +此时，可以通过 `kubectl describe pod` 命令查看 Pending 的具体原因： + +{{< copyable "shell-regular" >}} + +``` +kubectl describe po -n +``` + +如果是 CPU 或内存资源不足，可以通过降低对应组件的 CPU 或内存资源申请使其能够得到调度，或是增加新的 Kubernetes 节点。 + +如果是 PVC 的 StorageClass 找不到，需要在 `values.yaml` 里面将 `storageClassName` 修改为集群中可用的 StorageClass 名字，执行 `helm upgrade`，然后将 Statefulset 删除，并且将对应的 PVC 也都删除，可以通过以下命令获取集群中可用的 StorageClass： + +{{< copyable "shell-regular" >}} + +``` +kubectl get storageclass +``` + +如果集群中有 StorageClass，但可用的 PV 不足，则需要添加对应的 PV 资源。对于 Local PV，可以参考[本地 PV 配置](/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)进行扩充。 + +tidb-scheduler 针对 PD 和 TiKV 定制了高可用调度策略。对于同一个 TiDB 集群，假设 PD 或者 TiKV 的 Replicas 数量为 N，那么可以调度到每个节点的 PD Pod 数量最多为 `M=(N-1)/2`（如果 N<3，M=1），可以调度到每个节点的 TiKV Pod 数量最多为 `M=ceil(N/3)`（ceil 表示向上取整，如果 N<3，M=1）。如果 Pod 因为不满足高可用调度策略而导致状态为 Pending，需要往集群内添加节点。 + +## Pod 处于 CrashLoopBackOff 状态 + +Pod 处于 CrashLoopBackOff 状态意味着 Pod 内的容器重复地异常退出（异常退出后，容器被 Kubelet 重启，重启后又异常退出，如此往复）。可能导致 CrashLoopBackOff 的原因有很多，此时，最有效的定位办法是查看 Pod 内容器的日志： + +{{< copyable "shell-regular" >}} + +```shell +kubectl -n logs -f +``` + +假如本次日志没有能够帮助诊断的有效信息，可以添加 `-p` 参数输出容器上次启动时的日志信息： + +{{< copyable "shell-regular" >}} + +```shell +kubectl -n logs -p +``` + +确认日志中的错误信息后，可以根据 [tidb-server 启动报错](/how-to/troubleshoot/cluster-setup.md#tidb-server-启动报错)，[tikv-server 启动报错](/how-to/troubleshoot/cluster-setup.md#tikv-server-启动报错)，[pd-server 启动报错](/how-to/troubleshoot/cluster-setup.md#pd-server-启动报错)中的指引信息进行进一步排查解决。 + +若是 TiKV Pod 日志中出现 "cluster id mismatch" 信息，则 TiKV Pod 使用的数据可能是其他或之前的 TiKV Pod 的旧数据。在集群配置本地存储时未清除机器上本地磁盘上的数据，或者强制删除了 PV 导致数据并没有被 local volume provisioner 程序回收，可能导致 PV 遗留旧数据，导致错误。 + +在确认该 TiKV 应作为新节点加入集群、且 PV 上的数据应该删除后，可以删除该 TiKV Pod 和关联 PVC。TiKV Pod 将自动重建并绑定新的 PV 来使用。集群本地存储配置中，应对机器上的本地存储删除，避免 Kubernetes 使用机器上遗留的数据。集群运维中，不可强制删除 PV ，应由 local volume provisioner 程序管理。用户通过创建、删除 PVC 以及设置 PV 的 reclaimPolicy 来管理 PV 的生命周期。 + +另外，TiKV 在 ulimit 不足时也会发生启动失败的状况，对于这种情况，可以修改 Kubernetes 节点的 `/etc/security/limits.conf` 调大 ulimit： + +``` +root soft nofile 1000000 +root hard nofile 1000000 +root soft core unlimited +root soft stack 10240 +``` + +假如通过日志无法确认失败原因，ulimit 也设置正常，那么可以通过[诊断模式](#诊断模式)进行进一步排查。 + +## 无法访问 TiDB 服务 + +TiDB 服务访问不了时，首先确认 TiDB 服务是否部署成功，确认方法如下： + +查看该集群的所有组件是否全部都启动了，状态是否为 Running。 + +{{< copyable "shell-regular" >}} + +```shell +kubectl get po -n +``` + +检查 TiDB 组件的日志，看日志是否有报错。 + +{{< copyable "shell-regular" >}} + +```shell +kubectl logs -f -n -c tidb +``` + +如果确定集群部署成功，则进行网络检查： + +1. 如果你是通过 `NodePort` 方式访问不了 TiDB 服务，请在 node 上尝试使用 service domain 或 clusterIP 访问 TiDB 服务，假如 serviceName 或 clusterIP 的方式能访问，基本判断 Kubernetes 集群内的网络是正常的，问题可能出在下面两个方面： + + * 客户端到 node 节点的网络不通。 + * 查看 TiDB service 的 `externalTrafficPolicy` 属性是否为 Local。如果是 Local 则客户端必须通过 TiDB Pod 所在 node 的 IP 来访问。 + +2. 如果 service domain 或 clusterIP 方式也访问不了 TiDB 服务，尝试用 TiDB服务后端的 `:4000` 连接看是否可以访问，如果通过 PodIP 可以访问 TiDB 服务，可以确认问题出在 service domain 或 clusterIP 到 PodIP 之间的连接上，排查项如下： + + * 检查 DNS 服务是否正常： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get po -n kube-system -l k8s-app=kube-dns + dig + ``` + + * 检查各个 node 上的 kube-proxy 是否正常运行： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get po -n kube-system -l k8s-app=kube-proxy + ``` + + * 检查 node 上的 iptables 规则中 TiDB 服务的规则是否正确 + + {{< copyable "shell-regular" >}} + + ```shell + iptables-save -t nat |grep + ``` + + * 检查对应的 endpoint 是否正确 + +3. 如果通过 PodIP 访问不了 TiDB 服务，问题出在 Pod 层面的网络上，排查项如下： + + * 检查 node 上的相关 route 规则是否正确 + * 检查网络插件服务是否正常 + * 参考上面的 [Pod 之间网络不通](#pod-之间网络不通)章节 + +## TiKV Store 异常进入 Tombstone 状态 + +正常情况下，当 TiKV Pod 处于健康状态时（Pod 状态为 `Running`），对应的 TiKV Store 状态也是健康的（Store 状态为 `UP`）。但并发进行 TiKV 组件的扩容和缩容可能会导致部分 TiKV Store 异常并进入 Tombstone 状态。此时，可以按照以下步骤进行修复： + +1. 查看 TiKV Store 状态： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get -n tidbcluster -ojson | jq '.status.tikv.stores' + ``` + +2. 查看 TiKV Pod 运行状态： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl get -n po -l app.kubernetes.io/component=tikv + ``` + +3. 对比 Store 状态与 Pod 运行状态。假如某个 TiKV Pod 所对应的 Store 处于 `Offline` 状态，则表明该 Pod 的 Store 正在异常下线中。此时，可以通过下面的命令取消下线进程，进行恢复： + + 1. 打开到 PD 服务的连接： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & + ``` + + 2. 上线对应 Store： + + {{< copyable "shell-regular" >}} + + ```shell + curl -X POST http://127.0.0.1:2379/pd/api/v1/store//state?state=Up + ``` + +4. 假如某个 TiKV Pod 所对应的 `lastHeartbeatTime` 最新的 Store 处于 `Tombstone` 状态 ，则表明异常下线已经完成。此时，需要重建 Pod 并绑定新的 PV 进行恢复： + + 1. 将该 Store 对应 PV 的 `reclaimPolicy` 调整为 `Delete`： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl patch $(kubectl get pv -l app.kubernetes.io/instance=,tidb.pingcap.com/store-id= -o name) -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}} + ``` + + 2. 删除 Pod 使用的 PVC： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl delete -n pvc tikv- --wait=false + ``` + + 3. 删除 Pod，等待 Pod 重建： + + {{< copyable "shell-regular" >}} + + ```shell + kubectl delete -n pod + ``` + + Pod 重建后，会以在集群中注册一个新的 Store，恢复完成。 + +## TiDB 长连接被异常中断 + +许多负载均衡器 (Load Balancer) 会设置连接空闲超时时间。当连接上没有数据传输的时间超过设定值，负载均衡器会主动将连接中断。若发现 TiDB 使用过程中，长查询会被异常中断，可检查客户端与 TiDB 服务端之间的中间件程序。若其连接空闲超时时间较短，可尝试增大该超时时间。若不可修改，可打开 TiDB `tcp-keep-alive` 选项，启用 TCP keepalive 特性。 + +默认情况下，Linux 发送 keepalive 探测包的等待时间为 7200 秒。若需减少该时间，可通过 `podSecurityContext` 字段配置 `sysctls`。 + +- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 允许配置 `--allowed-unsafe-sysctls=net.*`，请为 `kubelet` 配置该参数，并按如下方式配置 TiDB： + + {{< copyable "" >}} + + ```yaml + tidb: + ... + podSecurityContext: + sysctls: + - name: net.ipv4.tcp_keepalive_time + value: "300" + ``` + +- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 不允许配置 `--allowed-unsafe-sysctls=net.*`，请按如下方式配置 TiDB： + + {{< copyable "" >}} + + ```yaml + tidb: + annotations: + tidb.pingcap.com/sysctl-init: "true" + podSecurityContext: + sysctls: + - name: net.ipv4.tcp_keepalive_time + value: "300" + ... + ``` + +> **注意：** +> +> 进行以上配置要求 TiDB Operator 1.1 及以上版本。 diff --git a/tidb-in-kubernetes/upgrade/tidb-cluster.md b/tidb-in-kubernetes/upgrade/tidb-cluster.md new file mode 100644 index 000000000000..b99f393b4aaf --- /dev/null +++ b/tidb-in-kubernetes/upgrade/tidb-cluster.md @@ -0,0 +1,96 @@ +--- +title: 滚动升级 Kubernetes 上的 TiDB 集群 +category: how-to +--- + +# 滚动升级 Kubernetes 上的 TiDB 集群 + +滚动更新 TiDB 集群时，会按 PD、TiKV、TiDB 的顺序，串行删除 Pod，并创建新版本的 Pod，当新版本的 Pod 正常运行后，再处理下一个 Pod。 + +滚动升级过程会自动处理 PD、TiKV 的 Leader 迁移与 TiDB 的 DDL Owner 迁移。因此，在多节点的部署拓扑下（最小环境：PD \* 3、TiKV \* 3、TiDB \* 2），滚动更新 TiKV、PD 不会影响业务正常运行。 + +对于有连接重试功能的客户端，滚动更新 TiDB 同样不会影响业务。对于无法进行重试的客户端，滚动更新 TiDB 则会导致连接到被关闭节点的数据库连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能或在低峰期进行 TiDB 的滚动升级操作。 + +滚动更新可以用于升级 TiDB 版本，也可以用于更新集群配置。 + +## 升级 TiDB 版本 + +1. 修改集群的 `values.yaml` 文件中的 `tidb.image`、`tikv.image`、`pd.image` 的值为新版本镜像； +2. 执行 `helm upgrade` 命令进行升级： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` + +3. 查看升级进度： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl -n get pod -o wide + ``` + + 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 + +## 更新 TiDB 集群配置 + +默认条件下，修改配置文件不会自动应用到 TiDB 集群中，只有在实例重启时，才会重新加载新的配置文件。 + +您可以开启配置文件自动更新特性，在每次配置文件更新时，自动执行滚动更新，将修改后的配置应用到集群中。操作步骤如下： + +1. 修改集群的 `values.yaml` 文件，将 `enableConfigMapRollout` 的值设为 `true`； +2. 根据需求修改 `values.yaml` 中需要调整的集群配置项； +3. 执行 `helm upgrade` 命令进行升级： + + {{< copyable "shell-regular" >}} + + ```shell + helm upgrade pingcap/tidb-cluster -f values.yaml --version= + ``` + +4. 查看升级进度： + + {{< copyable "shell-regular" >}} + + ```shell + watch kubectl -n get pod -o wide + ``` + + 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 + +> **注意：** +> +> - 将 `enableConfigMapRollout` 特性从关闭状态打开时，即使没有配置变更，也会触发一次 PD、TiKV、TiDB 的滚动更新。 + +## 强制升级 TiDB 集群 + +如果 PD 集群因为 PD 配置错误、PD 镜像 tag 错误、NodeAffinity 等原因不可用，[TiDB 集群扩缩容](/tidb-in-kubernetes/scale-in-kubernetes.md)、[升级 TiDB 版本](#升级-tidb-版本)和[更新 TiDB 集群配置](#更新-tidb-集群配置)这三种操作都无法成功执行。 + +这种情况下，可使用 `force-upgrade`（TiDB Operator 版本 > v1.0.0-beta.3 ）强制升级集群以恢复集群功能。 +首先为集群设置 `annotation`： + +{{< copyable "shell-regular" >}} + +```shell +kubectl annotate --overwrite tc -n tidb.pingcap.com/force-upgrade=true +``` + +然后执行对应操作中的 `helm upgrade` 命令： + +{{< copyable "shell-regular" >}} + +```shell +helm upgrade pingcap/tidb-cluster -f values.yaml --version= +``` + +> **警告：** +> +> PD 集群恢复后，**必须**执行下面命令禁用强制升级功能，否则下次升级过程可能会出现异常： +> +> {{< copyable "shell-regular" >}} +> +> ```shell +> kubectl annotate tc -n tidb.pingcap.com/force-upgrade- +> ``` diff --git a/dev/tidb-in-kubernetes/upgrade/tidb-operator.md b/tidb-in-kubernetes/upgrade/tidb-operator.md similarity index 100% rename from dev/tidb-in-kubernetes/upgrade/tidb-operator.md rename to tidb-in-kubernetes/upgrade/tidb-operator.md diff --git a/v2.1/TOC.md b/v2.1/TOC.md deleted file mode 100644 index d3dbd2a7fa79..000000000000 --- a/v2.1/TOC.md +++ /dev/null @@ -1,397 +0,0 @@ -# TiDB 中文用户文档 - - - - -## 目录 - -+ 关于 TiDB - - [TiDB 简介](/v2.1/overview.md) - + Benchmark 测试 - - [如何用 Sysbench 测试 TiDB](/v2.1/benchmark/how-to-run-sysbench.md) - - [Sysbench 性能对比 - v2.1 对比 v2.0](/v2.1/benchmark/sysbench-v3.md) - - [TPC-H 50G 性能对比 - v2.1 对比 v2.0](/v2.1/benchmark/tpch-v2.md) -+ 主要概念 - - [整体架构](/v2.1/architecture.md) - + 核心特性 - - [水平扩展](/v2.1/key-features.md#水平扩展) - - [高可用](/v2.1/key-features.md#高可用) -+ 操作指南 - + 快速上手 - + 创建集群 - - [使用 Docker Compose](https://pingcap.com/docs-cn/dev/how-to/get-started/deploy-tidb-from-docker-compose/) - - [SQL 基本操作](/v2.1/how-to/get-started/explore-sql.md) - - [读取历史数据](/v2.1/how-to/get-started/read-historical-data.md) - - [TiDB Binlog 教程](/v2.1/how-to/get-started/tidb-binlog.md) - - [TiDB Data Migration 教程](/v2.1/how-to/get-started/data-migration.md) - - [TiDB Lightning 教程](/v2.1/how-to/get-started/tidb-lightning.md) - - [TiSpark 教程](/v2.1/how-to/get-started/tispark.md) - + 部署 - - [软硬件环境需求](/v2.1/how-to/deploy/hardware-recommendations.md) - + 集群部署方式 - - [使用 Ansible 部署（推荐）](/v2.1/how-to/deploy/orchestrated/ansible.md) - - [使用 Ansible 离线部署](/v2.1/how-to/deploy/orchestrated/offline-ansible.md) - - [使用 Docker 部署](/v2.1/how-to/deploy/orchestrated/docker.md) - + 跨地域冗余 - - [跨数据中心部署方案](/v2.1/how-to/deploy/geographic-redundancy/overview.md) - - [配置集群拓扑](/v2.1/how-to/deploy/geographic-redundancy/location-awareness.md) - - [使用 Ansible 部署 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md) - + 配置 - - [时区](/v2.1/how-to/configure/time-zone.md) - - [内存控制](/v2.1/how-to/configure/memory-control.md) - + 安全 - + 安全传输层协议 (TLS) - - [为 MySQL 客户端开启 TLS](/v2.1/how-to/secure/enable-tls-clients.md) - - [为 TiDB 组件间开启 TLS](/v2.1/how-to/secure/enable-tls-between-components.md) - - [生成自签名证书](/v2.1/how-to/secure/generate-self-signed-certificates.md) - + 监控 - - [概述](/v2.1/how-to/monitor/overview.md) - - [监控 TiDB 集群](/v2.1/how-to/monitor/monitor-a-cluster.md) - + 迁移 - - [概述](/v2.1/how-to/migrate/overview.md) - + 从 MySQL 迁移 - - [全量迁移](/v2.1/how-to/migrate/from-mysql.md) - - [增量复制](/v2.1/how-to/migrate/incrementally-from-mysql.md) - - [从 MySQL/Amazon Aurora MySQL 迁移数据](/v2.1/how-to/migrate/from-aurora.md) - - [从 CSV 迁移](/v2.1/reference/tools/tidb-lightning/csv.md) - + 运维 - - [Ansible 常见运维操作](/v2.1/how-to/maintain/ansible-operations.md) - + [备份与恢复](/v2.1/how-to/maintain/backup-and-restore.md) - - [定位慢查询](/v2.1/how-to/maintain/identify-slow-queries.md) - + 扩容缩容 - - [使用 Ansible 扩容缩容](/v2.1/how-to/scale/with-ansible.md) - + 升级 - - [升级至 TiDB 2.1](/v2.1/how-to/upgrade/from-previous-version.md) - + 故障诊断 - - [集群配置诊断](/v2.1/how-to/troubleshoot/cluster-setup.md) - - [TiDB Lightning 故障诊断](/v2.1/how-to/troubleshoot/tidb-lightning.md) -+ 参考手册 - + SQL - - [与 MySQL 兼容性对比](/v2.1/reference/mysql-compatibility.md) - + SQL 语言结构 - - [字面值](/v2.1/reference/sql/language-structure/literal-values.md) - - [Schema 对象名](/v2.1/reference/sql/language-structure/schema-object-names.md) - - [关键字和保留字](/v2.1/reference/sql/language-structure/keywords-and-reserved-words.md) - - [用户自定义变量](/v2.1/reference/sql/language-structure/user-defined-variables.md) - - [表达式语法](/v2.1/reference/sql/language-structure/expression-syntax.md) - - [注释语法](/v2.1/reference/sql/language-structure/comment-syntax.md) - + 数据类型 - - [概述](/v2.1/reference/sql/data-types/overview.md) - - [默认值](/v2.1/reference/sql/data-types/default-values.md) - + 数值类型 - - [`BIT`](/v2.1/reference/sql/data-types/numeric.md#bit-类型) - - [`BOOL|BOOLEAN`](/v2.1/reference/sql/data-types/numeric.md#boolean-类型) - - [`TINYINT`](/v2.1/reference/sql/data-types/numeric.md#tinyint-类型) - - [`SMALLINT`](/v2.1/reference/sql/data-types/numeric.md#smallint-类型) - - [`MEDIUMINT`](/v2.1/reference/sql/data-types/numeric.md#mediumint-类型) - - [`INT|INTEGER`](/v2.1/reference/sql/data-types/numeric.md#integer-类型) - - [`BIGINT`](/v2.1/reference/sql/data-types/numeric.md#bigint-类型) - - [`DECIMAL`](/v2.1/reference/sql/data-types/numeric.md#decimal-类型) - - [`FLOAT`](/v2.1/reference/sql/data-types/numeric.md#float-类型) - - [`DOUBLE`](/v2.1/reference/sql/data-types/numeric.md#double-类型) - + 日期和时间类型 - - [`DATE`](/v2.1/reference/sql/data-types/date-and-time.md#date-类型) - - [`DATETIME`](/v2.1/reference/sql/data-types/date-and-time.md#datetime-类型) - - [`TIMESTAMP`](/v2.1/reference/sql/data-types/date-and-time.md#timestamp-类型) - - [`TIME`](/v2.1/reference/sql/data-types/date-and-time.md#time-类型) - - [`YEAR`](/v2.1/reference/sql/data-types/date-and-time.md#year-类型) - + 字符串类型 - - [`CHAR`](/v2.1/reference/sql/data-types/string.md#char-类型) - - [`VARCHAR`](/v2.1/reference/sql/data-types/string.md#varchar-类型) - - [`TEXT`](/v2.1/reference/sql/data-types/string.md#text-类型) - - [`LONGTEXT`](/v2.1/reference/sql/data-types/string.md#longtext-类型) - - [`BINARY`](/v2.1/reference/sql/data-types/string.md#binary-类型) - - [`VARBINARY`](/v2.1/reference/sql/data-types/string.md#varbinary-类型) - - [`TINYBLOB`](/v2.1/reference/sql/data-types/string.md#tinyblob-类型) - - [`BLOB`](/v2.1/reference/sql/data-types/string.md#blob-类型) - - [`MEDIUMBLOB`](/v2.1/reference/sql/data-types/string.md#mediumblob-类型) - - [`LONGBLOB`](/v2.1/reference/sql/data-types/string.md#longblob-类型) - - [`ENUM`](/v2.1/reference/sql/data-types/string.md#enum-类型) - - [`SET`](/v2.1/reference/sql/data-types/string.md#set-类型) - - [JSON Type](/v2.1/reference/sql/data-types/json.md) - + 函数与操作符 - - [函数与操作符概述](/v2.1/reference/sql/functions-and-operators/reference.md) - - [表达式求值的类型转换](/v2.1/reference/sql/functions-and-operators/type-conversion.md) - - [操作符](/v2.1/reference/sql/functions-and-operators/operators.md) - - [控制流程函数](/v2.1/reference/sql/functions-and-operators/control-flow-functions.md) - - [字符串函数](/v2.1/reference/sql/functions-and-operators/string-functions.md) - - [数值函数与操作符](/v2.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md) - - [日期和时间函数](/v2.1/reference/sql/functions-and-operators/date-and-time-functions.md) - - [位函数和操作符](/v2.1/reference/sql/functions-and-operators/bit-functions-and-operators.md) - - [Cast 函数和操作符](/v2.1/reference/sql/functions-and-operators/cast-functions-and-operators.md) - - [加密和压缩函数](/v2.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md) - - [信息函数](/v2.1/reference/sql/functions-and-operators/information-functions.md) - - [JSON 函数](/v2.1/reference/sql/functions-and-operators/json-functions.md) - - [GROUP BY 聚合函数](/v2.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md) - - [其它函数](/v2.1/reference/sql/functions-and-operators/miscellaneous-functions.md) - - [精度数学](/v2.1/reference/sql/functions-and-operators/precision-math.md) - + SQL 语句 - - [`ADD COLUMN`](/v2.1/reference/sql/statements/add-column.md) - - [`ADD INDEX`](/v2.1/reference/sql/statements/add-index.md) - - [`ADMIN`](/v2.1/reference/sql/statements/admin.md) - - [`ALTER DATABASE`](/v2.1/reference/sql/statements/alter-database.md) - - [`ALTER TABLE`](/v2.1/reference/sql/statements/alter-table.md) - - [`ALTER USER`](/v2.1/reference/sql/statements/alter-user.md) - - [`ANALYZE TABLE`](/v2.1/reference/sql/statements/analyze-table.md) - - [`BEGIN`](/v2.1/reference/sql/statements/begin.md) - - [`COMMIT`](/v2.1/reference/sql/statements/commit.md) - - [`CREATE DATABASE`](/v2.1/reference/sql/statements/create-database.md) - - [`CREATE INDEX`](/v2.1/reference/sql/statements/create-index.md) - - [`CREATE TABLE LIKE`](/v2.1/reference/sql/statements/create-table-like.md) - - [`CREATE TABLE`](/v2.1/reference/sql/statements/create-table.md) - - [`CREATE USER`](/v2.1/reference/sql/statements/create-user.md) - - [`DEALLOCATE`](/v2.1/reference/sql/statements/deallocate.md) - - [`DELETE`](/v2.1/reference/sql/statements/delete.md) - - [`DESC`](/v2.1/reference/sql/statements/desc.md) - - [`DESCRIBE`](/v2.1/reference/sql/statements/describe.md) - - [`DO`](/v2.1/reference/sql/statements/do.md) - - [`DROP COLUMN`](/v2.1/reference/sql/statements/drop-column.md) - - [`DROP DATABASE`](/v2.1/reference/sql/statements/drop-database.md) - - [`DROP INDEX`](/v2.1/reference/sql/statements/drop-index.md) - - [`DROP TABLE`](/v2.1/reference/sql/statements/drop-table.md) - - [`DROP USER`](/v2.1/reference/sql/statements/drop-user.md) - - [`EXECUTE`](/v2.1/reference/sql/statements/execute.md) - - [`EXPLAIN ANALYZE`](/v2.1/reference/sql/statements/explain-analyze.md) - - [`EXPLAIN`](/v2.1/reference/sql/statements/explain.md) - - [`FLUSH PRIVILEGES`](/v2.1/reference/sql/statements/flush-privileges.md) - - [`FLUSH STATUS`](/v2.1/reference/sql/statements/flush-status.md) - - [`FLUSH TABLES`](/v2.1/reference/sql/statements/flush-tables.md) - - [`GRANT `](/v2.1/reference/sql/statements/grant-privileges.md) - - [`INSERT`](/v2.1/reference/sql/statements/insert.md) - - [`KILL [TIDB]`](/v2.1/reference/sql/statements/kill.md) - - [`LOAD DATA`](/v2.1/reference/sql/statements/load-data.md) - - [`MODIFY COLUMN`](/v2.1/reference/sql/statements/modify-column.md) - - [`PREPARE`](/v2.1/reference/sql/statements/prepare.md) - - [`RENAME INDEX`](/v2.1/reference/sql/statements/rename-index.md) - - [`RENAME TABLE`](/v2.1/reference/sql/statements/rename-table.md) - - [`REPLACE`](/v2.1/reference/sql/statements/replace.md) - - [`REVOKE `](/v2.1/reference/sql/statements/revoke-privileges.md) - - [`ROLLBACK`](/v2.1/reference/sql/statements/rollback.md) - - [`SELECT`](/v2.1/reference/sql/statements/select.md) - - [`SET [NAMES|CHARACTER SET]`](/v2.1/reference/sql/statements/set-names.md) - - [`SET PASSWORD`](/v2.1/reference/sql/statements/set-password.md) - - [`SET TRANSACTION`](/v2.1/reference/sql/statements/set-transaction.md) - - [`SET [GLOBAL|SESSION] `](/v2.1/reference/sql/statements/set-variable.md) - - [`SHOW CHARACTER SET`](/v2.1/reference/sql/statements/show-character-set.md) - - [`SHOW COLLATION`](/v2.1/reference/sql/statements/show-collation.md) - - [`SHOW [FULL] COLUMNS FROM`](/v2.1/reference/sql/statements/show-columns-from.md) - - [`SHOW CREATE TABLE`](/v2.1/reference/sql/statements/show-create-table.md) - - [`SHOW DATABASES`](/v2.1/reference/sql/statements/show-databases.md) - - [`SHOW ENGINES`](/v2.1/reference/sql/statements/show-engines.md) - - [`SHOW ERRORS`](/v2.1/reference/sql/statements/show-errors.md) - - [`SHOW [FULL] FIELDS FROM`](/v2.1/reference/sql/statements/show-fields-from.md) - - [`SHOW GRANTS`](/v2.1/reference/sql/statements/show-grants.md) - - [`SHOW INDEXES [FROM|IN]`](/v2.1/reference/sql/statements/show-indexes.md) - - [`SHOW INDEX [FROM|IN]`](/v2.1/reference/sql/statements/show-index.md) - - [`SHOW KEYS [FROM|IN]`](/v2.1/reference/sql/statements/show-keys.md) - - [`SHOW PRIVILEGES`](/v2.1/reference/sql/statements/show-privileges.md) - - [`SHOW [FULL] PROCESSSLIST`](/v2.1/reference/sql/statements/show-processlist.md) - - [`SHOW SCHEMAS`](/v2.1/reference/sql/statements/show-schemas.md) - - [`SHOW [FULL] TABLES`](/v2.1/reference/sql/statements/show-tables.md) - - [`SHOW TABLE REGIONS`](/v2.1/reference/sql/statements/show-table-regions.md) - - [`SHOW TABLE STATUS`](/v2.1/reference/sql/statements/show-table-status.md) - - [`SHOW [GLOBAL|SESSION] VARIABLES`](/v2.1/reference/sql/statements/show-variables.md) - - [`SHOW WARNINGS`](/v2.1/reference/sql/statements/show-warnings.md) - - [`SPLIT REGION`](/v2.1/reference/sql/statements/split-region.md) - - [`START TRANSACTION`](/v2.1/reference/sql/statements/start-transaction.md) - - [`TRACE`](/v2.1/reference/sql/statements/trace.md) - - [`TRUNCATE`](/v2.1/reference/sql/statements/truncate.md) - - [`UPDATE`](/v2.1/reference/sql/statements/update.md) - - [`USE`](/v2.1/reference/sql/statements/use.md) - - [约束](/v2.1/reference/sql/constraints.md) - - [生成列](/v2.1/reference/sql/generated-columns.md) - - [字符集](/v2.1/reference/sql/character-set.md) - + 配置 - + tidb-server - - [MySQL 系统变量](/v2.1/reference/configuration/tidb-server/mysql-variables.md) - - [TiDB 特定系统变量](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md) - - [配置参数](/v2.1/reference/configuration/tidb-server/configuration.md) - - [配置文件描述](/v2.1/reference/configuration/tidb-server/configuration-file.md) - + pd-server - - [配置参数](/v2.1/reference/configuration/pd-server/configuration.md) - + tikv-server - - [配置参数](/v2.1/reference/configuration/tikv-server/configuration.md) - + 安全 - - [与 MySQL 的安全特性差异](/v2.1/reference/security/compatibility.md) - - [TiDB 数据库权限管理](/v2.1/reference/security/privilege-system.md) - - [TiDB 用户账户管理](/v2.1/reference/security/user-account-management.md) - + 事务 - - [事务概览](/v2.1/reference/transactions/overview.md) - - [隔离级别](/v2.1/reference/transactions/transaction-isolation.md) - - [乐观事务](/v2.1/reference/transactions/transaction-optimistic.md) - + 系统数据库 - - [`mysql`](/v2.1/reference/system-databases/mysql.md) - - [`information_schema`](/v2.1/reference/system-databases/information-schema.md) - - [错误码](/v2.1/reference/error-codes.md) - - [支持的连接器和 API](/v2.1/reference/supported-clients.md) - - [垃圾回收 (GC)](/v2.1/reference/garbage-collection.md) - + 性能调优 - - [SQL 优化流程](/v2.1/reference/performance/sql-optimizer-overview.md) - - [理解 TiDB 执行计划](/v2.1/reference/performance/understanding-the-query-execution-plan.md) - - [统计信息概述](/v2.1/reference/performance/statistics.md) - - [Optimizer Hints](/v2.1/reference/performance/optimizer-hints.md) - - [TiKV 调优](/v2.1/reference/performance/tune-tikv.md) - - [TiDB 最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/) - + 监控指标 - - [Overview 面板](/v2.1/reference/key-monitoring-metrics/overview-dashboard.md) - - [TiDB 面板](/v2.1/reference/key-monitoring-metrics/tidb-dashboard.md) - - [PD 面板](/v2.1/reference/key-monitoring-metrics/pd-dashboard.md) - - [TiKV 面板](/v2.1/reference/key-monitoring-metrics/tikv-dashboard.md) - - [报警规则](/v2.1/reference/alert-rules.md) - + 最佳实践 - - [HAProxy 最佳实践](/v2.1/reference/best-practices/haproxy.md) - - [Java 应用开发最佳实践](/v2.1/reference/best-practices/java-app.md) - - [Grafana 监控最佳实践](/v2.1/reference/best-practices/grafana-monitor.md) - - [PD 调度策略最佳实践](/v2.1/reference/best-practices/pd-scheduling.md) - - [海量 Region 集群调优最佳实践](/v2.1/reference/best-practices/massive-regions.md) - + [TiSpark 使用指南](/v2.1/reference/tispark.md) - + TiDB Binlog - - [概述](/v2.1/reference/tidb-binlog/overview.md) - - [部署使用](/v2.1/reference/tidb-binlog/deploy.md) - - [运维管理](/v2.1/reference/tidb-binlog/maintain.md) - - [版本升级](/v2.1/reference/tidb-binlog/upgrade.md) - - [监控告警](/v2.1/reference/tidb-binlog/monitor.md) - - [增量恢复](/v2.1/reference/tidb-binlog/reparo.md) - - [Kafka 自定义开发](/v2.1/reference/tidb-binlog/binlog-slave-client.md) - - [术语表](/v2.1/reference/tidb-binlog/glossary.md) - + 故障诊断 - - [故障诊断](/v2.1/reference/tidb-binlog/troubleshoot/binlog.md) - - [常见错误修复](/v2.1/reference/tidb-binlog/troubleshoot/error-handling.md) - - [FAQ](/v2.1/reference/tidb-binlog/faq.md) - + 周边工具 - - [Mydumper](/v2.1/reference/tools/mydumper.md) - - [Loader](/v2.1/reference/tools/loader.md) - - [Syncer](/v2.1/reference/tools/syncer.md) - + Data Migration - + 概述 - - [DM 架构](/v2.1/reference/tools/data-migration/overview.md#dm-架构) - - [同步功能介绍](/v2.1/reference/tools/data-migration/overview.md#同步功能介绍) - - [使用限制](/v2.1/reference/tools/data-migration/overview.md#使用限制) - - [DM-worker 简介](/v2.1/reference/tools/data-migration/dm-worker-intro.md) - - [DM Relay Log](/v2.1/reference/tools/data-migration/relay-log.md) - + 核心特性 - - [Table Routing](/v2.1/reference/tools/data-migration/features/overview.md#table-routing) - - [Black & White Lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) - - [Binlog Event Filter](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) - - [同步延迟监控](/v2.1/reference/tools/data-migration/features/overview.md#同步延迟监控) - + Shard Support - - [简介](/v2.1/reference/tools/data-migration/features/shard-merge.md) - - [使用限制](/v2.1/reference/tools/data-migration/features/shard-merge.md#使用限制) - - [手动处理 Sharding DDL Lock](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) - + 使用场景 - - [简单的从库同步场景](/v2.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md) - - [分库分表合并场景](/v2.1/reference/tools/data-migration/usage-scenarios/shard-merge.md) - - [分表合并数据迁移最佳实践](/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md) - - [DM-worker 在上游 MySQL 主从间切换](/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md) - + [部署使用](/v2.1/reference/tools/data-migration/deploy.md) - + 配置 - - [概述](/v2.1/reference/tools/data-migration/configure/overview.md) - - [DM-master 配置](/v2.1/reference/tools/data-migration/configure/dm-master-configuration-file.md) - - [DM-worker 配置](/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - - [任务配置](/v2.1/reference/tools/data-migration/configure/task-configuration-file.md) - + DM 集群管理 - - [集群操作](/v2.1/reference/tools/data-migration/cluster-operations.md) - - [集群升级](/v2.1/reference/tools/data-migration/dm-upgrade.md) - + DM 同步任务管理 - - [管理数据同步任务](/v2.1/reference/tools/data-migration/manage-tasks.md) - - [任务前置检查](/v2.1/reference/tools/data-migration/precheck.md) - - [任务状态查询](/v2.1/reference/tools/data-migration/query-status.md) - - [跳过或替代执行异常的 SQL 语句](/v2.1/reference/tools/data-migration/skip-replace-sqls.md) - - [监控 DM 集群](/v2.1/reference/tools/data-migration/monitor.md) - + 从与 MySQL 兼容的数据库迁移数据 - - [从 MySQL/Amazon Aurora MySQL 迁移数据](/v2.1/how-to/migrate/from-aurora.md) - - [DM Portal](/v2.1/reference/tools/data-migration/dm-portal.md) - + DM 故障诊断 - - [故障诊断](/v2.1/reference/tools/data-migration/troubleshoot/dm.md) - - [错误含义](/v2.1/reference/tools/data-migration/troubleshoot/error-system.md) - - [常见错误修复](/v2.1/reference/tools/data-migration/troubleshoot/error-handling.md) - - [DM FAQ](/v2.1/reference/tools/data-migration/faq.md) - + 版本发布历史 - + v1.0 - - [1.0.2](/v2.1/reference/tools/data-migration/releases/1.0.2.md) - - [1.0.3](/v2.1/reference/tools/data-migration/releases/1.0.3.md) - - [TiDB DM 术语表](/v2.1/reference/tools/data-migration/glossary.md) - + TiDB Lightning - - [概述](/v2.1/reference/tools/tidb-lightning/overview.md) - - [部署执行](/v2.1/reference/tools/tidb-lightning/deployment.md) - - [参数说明](/v2.1/reference/tools/tidb-lightning/config.md) - - [断点续传](/v2.1/reference/tools/tidb-lightning/checkpoints.md) - - [表库过滤](/v2.1/reference/tools/tidb-lightning/table-filter.md) - - [CSV 支持](/v2.1/reference/tools/tidb-lightning/csv.md) - - [Web 界面](/v2.1/reference/tools/tidb-lightning/web.md) - - [监控告警](/v2.1/reference/tools/tidb-lightning/monitor.md) - - [故障诊断](/v2.1/how-to/troubleshoot/tidb-lightning.md) - - [FAQ](/v2.1/faq/tidb-lightning.md) - - [术语表](/v2.1/reference/tools/tidb-lightning/glossary.md) - - [sync-diff-inspector](/v2.1/reference/tools/sync-diff-inspector/overview.md) - - [PD Control](/v2.1/reference/tools/pd-control.md) - - [PD Recover](/v2.1/reference/tools/pd-recover.md) - - [TiKV Control](/v2.1/reference/tools/tikv-control.md) - - [TiDB Controller](/v2.1/reference/tools/tidb-control.md) - - [工具下载](/v2.1/reference/tools/download.md) -+ 常见问题 (FAQ) - - [TiDB FAQ](/v2.1/faq/tidb.md) - - [TiDB Lightning FAQ](/v2.1/faq/tidb-lightning.md) - - [升级 FAQ](/v2.1/faq/upgrade.md) -+ 技术支持 - - [支持渠道](/v2.1/support-resources.md) - - [反馈问题](/v2.1/report-issue.md) -+ [贡献](/v2.1/contribute.md) - - [贡献代码](/v2.1/contribute.md#成为-tidb-的贡献者) - - [改进文档](/v2.1/contribute.md#改进文档) -- [TiDB 路线图](/v2.1/roadmap.md) -+ [版本发布历史](/v2.1/releases/rn.md) - + v2.1 - - [2.1.19](/v2.1/releases/2.1.19.md) - - [2.1.18](/v2.1/releases/2.1.18.md) - - [2.1.17](/v2.1/releases/2.1.17.md) - - [2.1.16](/v2.1/releases/2.1.16.md) - - [2.1.15](/v2.1/releases/2.1.15.md) - - [2.1.14](/v2.1/releases/2.1.14.md) - - [2.1.13](/v2.1/releases/2.1.13.md) - - [2.1.12](/v2.1/releases/2.1.12.md) - - [2.1.11](/v2.1/releases/2.1.11.md) - - [2.1.10](/v2.1/releases/2.1.10.md) - - [2.1.9](/v2.1/releases/2.1.9.md) - - [2.1.8](/v2.1/releases/2.1.8.md) - - [2.1.7](/v2.1/releases/2.1.7.md) - - [2.1.6](/v2.1/releases/2.1.6.md) - - [2.1.5](/v2.1/releases/2.1.5.md) - - [2.1.4](/v2.1/releases/2.1.4.md) - - [2.1.3](/v2.1/releases/2.1.3.md) - - [2.1.2](/v2.1/releases/2.1.2.md) - - [2.1.1](/v2.1/releases/2.1.1.md) - - [2.1 GA](/v2.1/releases/2.1ga.md) - - [2.1 RC5](/v2.1/releases/21rc5.md) - - [2.1 RC4](/v2.1/releases/21rc4.md) - - [2.1 RC3](/v2.1/releases/21rc3.md) - - [2.1 RC2](/v2.1/releases/21rc2.md) - - [2.1 RC1](/v2.1/releases/21rc1.md) - - [2.1 Beta](/v2.1/releases/21beta.md) - + v2.0 - - [2.0.11](/v2.1/releases/2.0.11.md) - - [2.0.10](/v2.1/releases/2.0.10.md) - - [2.0.9](/v2.1/releases/209.md) - - [2.0.8](/v2.1/releases/208.md) - - [2.0.7](/v2.1/releases/207.md) - - [2.0.6](/v2.1/releases/206.md) - - [2.0.5](/v2.1/releases/205.md) - - [2.0.4](/v2.1/releases/204.md) - - [2.0.3](/v2.1/releases/203.md) - - [2.0.2](/v2.1/releases/202.md) - - [2.0.1](/v2.1/releases/201.md) - - [2.0](/v2.1/releases/2.0ga.md) - - [2.0 RC5](/v2.1/releases/2rc5.md) - - [2.0 RC4](/v2.1/releases/2rc4.md) - - [2.0 RC3](/v2.1/releases/2rc3.md) - - [2.0 RC1](/v2.1/releases/2rc1.md) - - [1.1 Beta](/v2.1/releases/11beta.md) - - [1.1 Alpha](/v2.1/releases/11alpha.md) - + v1.0 - - [1.0](/v2.1/releases/ga.md) - - [Pre-GA](/v2.1/releases/prega.md) - - [RC4](/v2.1/releases/rc4.md) - - [RC3](/v2.1/releases/rc3.md) - - [RC2](/v2.1/releases/rc2.md) - - [RC1](/v2.1/releases/rc1.md) -+ [术语表](/v2.1/glossary.md) diff --git a/v2.1/_index.md b/v2.1/_index.md deleted file mode 100755 index 2bbdefc937c0..000000000000 --- a/v2.1/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/v2.1/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v2.1/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/v2.1/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v2.1/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 Docker Compose 部署](/v2.1/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v2.1/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/v2.1/architecture.md b/v2.1/architecture.md deleted file mode 100644 index 7e599ad13d5f..000000000000 --- a/v2.1/architecture.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: TiDB 整体架构 -category: introduction ---- - -# TiDB 整体架构 - -要深入了解 TiDB 的水平扩展和高可用特点，首先需要了解 TiDB 的整体架构。TiDB 集群主要包括三个核心组件：TiDB Server，PD Server 和 TiKV Server。此外，还有用于解决用户复杂 OLAP 需求的 [TiSpark](https://github.com/pingcap/tispark/) 组件。 - -![TiDB Architecture](/media/tidb-architecture.png) - -## TiDB Server - -TiDB Server 负责接收 SQL 请求，处理 SQL 相关的逻辑，并通过 PD 找到存储计算所需数据的 TiKV 地址，与 TiKV 交互获取数据，最终返回结果。TiDB Server 是无状态的，其本身并不存储数据，只负责计算，可以无限水平扩展，可以通过负载均衡组件（如LVS、HAProxy 或 F5）对外提供统一的接入地址。 - -## PD Server - -Placement Driver (简称 PD) 是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。 - -PD 通过 Raft 协议保证数据的安全性。Raft 的 leader server 负责处理所有操作，其余的 PD server 仅用于保证高可用。建议部署奇数个 PD 节点。 - -## TiKV Server - -TiKV Server 负责存储数据，从外部看 TiKV 是一个分布式的提供事务的 Key-Value 存储引擎。存储数据的基本单位是 Region，每个 Region 负责存储一个 Key Range（从 StartKey 到 EndKey 的左闭右开区间）的数据，每个 TiKV 节点会负责多个 Region。TiKV 使用 Raft 协议做复制，保持数据的一致性和容灾。副本以 Region 为单位进行管理，不同节点上的多个 Region 构成一个 Raft Group，互为副本。数据在多个 TiKV 之间的负载均衡由 PD 调度，这里也是以 Region 为单位进行调度。 - -## TiSpark - -TiSpark 作为 TiDB 中解决用户复杂 OLAP 需求的主要组件，将 Spark SQL 直接运行在 TiDB 存储层上，同时融合 TiKV 分布式集群的优势，并融入大数据社区生态。至此，TiDB 可以通过一套系统，同时支持 OLTP 与 OLAP，免除用户数据同步的烦恼。 diff --git a/v2.1/benchmark/how-to-run-sysbench.md b/v2.1/benchmark/how-to-run-sysbench.md deleted file mode 100644 index a00054b779f7..000000000000 --- a/v2.1/benchmark/how-to-run-sysbench.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: 如何用 Sysbench 测试 TiDB -category: benchmark ---- - -# 如何用 Sysbench 测试 TiDB - -本次测试使用的是 TiDB 3.0 Beta 和 Sysbench 1.0.14。建议使用 Sysbench 1.0 或之后的更新版本，可在 [Sysbench Release 1.0.14 页面](https://github.com/akopytov/sysbench/releases/tag/1.0.14)下载。 - -## 测试环境 - -- [硬件要求](/v2.1/how-to/deploy/hardware-recommendations.md) - -- 参考 [TiDB 部署文档](/v2.1/how-to/deploy/orchestrated/ansible.md)部署 TiDB 集群。在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD，和 1 个 TiKV 实例。关于磁盘，以 32 张表、每张表 10M 行数据为例，建议 TiKV 的数据目录所在的磁盘空间大于 512 GB。 - 对于单个 TiDB 的并发连接数，建议控制在 500 以内，如需增加整个系统的并发压力，可以增加 TiDB 实例，具体增加的 TiDB 个数视测试压力而定。 - -IDC 机器： - -| 类别 | 名称 | -|:---- |:---- | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel® Xeon® CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Intel Optane SSD P4800X 375G * 1 | -| NIC | 10Gb Ethernet | - -## 测试方案 - -### TiDB 版本信息 - -| 组件 | GitHash | -|:---- |:---- | -| TiDB | 7a240818d19ae96e4165af9ea35df92466f59ce6 | -| TiKV | e26ceadcdfe94fb6ff83b5abb614ea3115394bcd | -| PD | 5e81548c3c1a1adab056d977e7767307a39ecb70 | - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|:---- |:---- | -| 172.16.30.31 | 3*sysbench | -| 172.16.30.33 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.34 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.35 | 1\*tidb 1\*pd 1\*tikv | - -### TiDB 配置 - -升高日志级别，可以减少打印日志数量，对 TiDB 的性能有积极影响。开启 TiDB 配置中的 `prepared plan cache`，以减少优化执行计划的开销。具体在 TiDB 配置文件中加入： - -```toml -[log] -level = "error" -[prepared-plan-cache] -enabled = true -``` - -### TiKV 配置 - -升高 TiKV 的日志级别同样有利于提高性能表现。 - -由于 TiKV 是以集群形式部署的，在 Raft 算法的作用下，能保证大多数节点已经写入数据。因此，除了对数据安全极端敏感的场景之外，raftstore 中的 `sync-log` 选项可以关闭。 - -TiKV 集群存在两个 Column Family（Default CF 和 Write CF），主要用于存储不同类型的数据。对于 Sysbench 测试，导入数据的 Column Family 在 TiDB 集群中的比例是固定的。这个比例是： - -Default CF : Write CF = 4 : 1 - -在 TiKV 中需要根据机器内存大小配置 RocksDB 的 block cache，以充分利用内存。以 40 GB 内存的虚拟机部署一个 TiKV 为例，其 block cache 建议配置如下: - -```toml -log-level = "error" -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "24GB" -[rocksdb.writecf] -block-cache-size = "6GB" -``` - -更详细的 TiKV 参数调优请参考 [TiKV 性能参数调优](/v2.1/reference/performance/tune-tikv.md)。 - -## 测试过程 - -> **注意：** -> -> 此次测试并没有使用如 HAproxy 等负载均衡工具。在 TiDB 单一节点上进行 Sysbench 测试，并把结果相加。负载均衡工具和不同版本参数也会影响性能表现。 - -### Sysbench 配置 - -以下为 Sysbench 配置文件样例： - -```txt -mysql-host={TIDB_HOST} -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads={8, 16, 32, 64, 128, 256} -report-interval=10 -db-driver=mysql -``` - -可根据实际需求调整其参数，其中 `TIDB_HOST` 为 TiDB server 的 IP 地址（配置文件中不能写多个地址），`threads` 为测试中的并发连接数，可在 “8, 16, 32, 64, 128, 256” 中调整，导入数据时，建议设置 threads = 8 或者 16。调整后，将该文件保存为名为 **config** 的文件。 - -**配置文件**参考示例如下： - -```txt -mysql-host=172.16.30.33 -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads=16 -report-interval=10 -db-driver=mysql -``` - -### 数据导入 - -在数据导入前，需要对 TiDB 进行简单设置。在 MySQL 客户端中执行如下命令： - -```sql -set global tidb_disable_txn_auto_retry = off; -``` - -然后退出客户端。TiDB 使用乐观事务模型，当发现并发冲突时，会回滚事务。将 `tidb_disable_txn_auto_retry` 设置为 `off` 会开启事务冲突后的自动重试机制，可以尽可能避免事务冲突报错导致 Sysbench 程序退出的问题。 - -重新启动 MySQL 客户端执行以下 SQL 语句，创建数据库 `sbtest`： - -```sql -create database sbtest; -``` - -调整 Sysbench 脚本创建索引的顺序。Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。该方式对于 TiDB 需要花费更多的导入时间。用户可以通过调整顺序来加速数据的导入。 - -假设用户使用的 [Sysbench](https://github.com/akopytov/sysbench/tree/1.0.14) 版本。我们可以通过以下两种方式来修改。 - -1. 直接下载为 TiDB 修改好的 [oltp_common.lua](https://raw.githubusercontent.com/pingcap/tidb-bench/master/sysbench/sysbench-patch/oltp_common.lua) 文件，覆盖 `/usr/share/sysbench/oltp_common.lua` 文件。 -2. 将 `/usr/share/sysbench/oltp_common.lua` 的第 [235](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L235) 行到第 [240](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L240) 行移动到第 198 行以后。 - -> **注意：** -> -> 此操作为可选操作，仅节约了数据导入时间。 - -命令行输入以下命令，开始导入数据，config 文件为上一步中配置的文件： - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 prepare -``` - -### 数据预热与统计信息收集 - -数据预热可将磁盘中的数据载入内存的 block cache 中，预热后的数据对系统整体的性能有较大的改善，建议在每次重启集群后进行一次数据预热。 - -Sysbench 1.0.14 没有提供数据预热的功能，因此需要手动进行数据预热。如果使用更新的 Sysbench 版本，可以使用自带的预热功能。 - -以 Sysbench 中某张表 sbtest7 为例，执行如下 SQL 语句 进行数据预热： - -```sql -SELECT COUNT(pad) FROM sbtest7 USE INDEX (k_7); -``` - -统计信息收集有助于优化器选择更为准确的执行计划，可以通过 `analyze` 命令来收集表 sbtest 的统计信息，每个表都需要统计。 - -```sql -ANALYZE TABLE sbtest7; -``` - -### Point select 测试命令 - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 run -``` - -### Update index 测试命令 - -```bash -sysbench --config-file=config oltp_update_index --tables=32 --table-size=10000000 run -``` - -### Read-only 测试命令 - -```bash -sysbench --config-file=config oltp_read_only --tables=32 --table-size=10000000 run -``` - -## 测试结果 - -测试了数据 32 表，每表有 10M 数据。 - -对每个 tidb-server 进行了 Sysbench 测试，将结果相加，得出最终结果： - -### oltp_point_select - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| point_select | 3\*8 | 67502.55 | 67502.55 | 0.36 | 0.42 | 141.92 | -| point_select | 3\*16 | 120141.84 | 120141.84 | 0.40 | 0.52 | 20.99 | -| point_select | 3\*32 | 170142.92 | 170142.92 | 0.58 | 0.99 | 28.08 | -| point_select | 3\*64 | 195218.54 | 195218.54 | 0.98 | 2.14 | 21.82 | -| point_select | 3\*128 | 208189.53 | 208189.53 | 1.84 | 4.33 | 31.02 | - -![oltp_point_select](/media/oltp_point_select.png) - -### oltp_update_index - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_update_index | 3\*8 | 9668.98 | 9668.98 | 2.51 | 3.19 | 103.88| -| oltp_update_index | 3\*16 | 12834.99 | 12834.99 | 3.79 | 5.47 | 176.90 | -| oltp_update_index | 3\*32 | 15955.77 | 15955.77 | 6.07 | 9.39 | 4787.14 | -| oltp_update_index | 3\*64 | 18697.17 | 18697.17 | 10.34 | 17.63 | 4539.04 | -| oltp_update_index | 3\*128 | 20446.81 | 20446.81 | 18.98 | 40.37 | 5394.75 | -| oltp_update_index | 3\*256 | 23563.03 | 23563.03 | 32.86 | 78.60 | 5530.69 | - -![oltp_update_index](/media/oltp_update_index.png) - -### oltp_read_only - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_read_only | 3\*8 | 2411.00 | 38575.96 | 9.92 | 20.00 | 92.23 | -| oltp_read_only | 3\*16 | 3873.53 | 61976.50 | 12.25 | 16.12 | 56.94 | -| oltp_read_only | 3\*32 | 5066.88 | 81070.16 | 19.42 | 26.20 | 123.41 | -| oltp_read_only | 3\*64 | 5466.36 | 87461.81 | 34.65 | 63.20 | 231.19 | -| oltp_read_only | 3\*128 | 6684.16 | 106946.59 | 57.29 | 97.55 | 180.85 | - -![oltp_read_only](/media/oltp_read_only.png) - -## 常见问题 - -### 在高并发压力下，TiDB、TiKV 的配置都合理，为什么整体性能还是偏低？ - -这种情况可能与使用了 proxy 有关。可以尝试直接对单个 TiDB 加压，将求和后的结果与使用 proxy 的情况进行对比。 - -以 HAproxy 为例。`nbproc` 参数可以增加其最大启动的进程数，较新版本的 HAproxy 还支持 `nbthread` 和 `cpu-map` 等。这些都可以减少对其性能的不利影响。 - -### 在高并发压力下，为什么 TiKV 的 CPU 利用率依然很低？ - -TiKV 虽然整体 CPU 偏低，但部分模块的 CPU 可能已经达到了很高的利用率。 - -TiKV 的其他模块，如 storage readpool、coprocessor 和 gRPC 的最大并发度限制是可以通过 TiKV 的配置文件进行调整的。 - -通过 Grafana 的 TiKV Thread CPU 监控面板可以观察到其实际使用率。如出现多线程模块瓶颈，可以通过增加该模块并发度进行调整。 - -### 在高并发压力下，TiKV 也未达到 CPU 使用瓶颈，为什么 TiDB 的 CPU 利用率依然很低？ - -在某些高端设备上，使用的是 NUMA 架构的 CPU，跨 CPU 访问远端内存将极大降低性能。TiDB 默认将使用服务器所有 CPU，goroutine 的调度不可避免地会出现跨 CPU 内存访问。 - -因此，建议在 NUMA 架构服务器上，部署 *n* 个 TiDB（*n* = NUMA CPU 的个数），同时将 TiDB 的 `max-procs` 变量的值设置为与 NUMA CPU 的核数相同。 diff --git a/v2.1/benchmark/sysbench-v2.md b/v2.1/benchmark/sysbench-v2.md deleted file mode 100644 index bce70f8a8400..000000000000 --- a/v2.1/benchmark/sysbench-v2.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 -category: benchmark ---- - -# TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 - -## 测试目的 - -对比 TiDB 2.0 版本和 1.0 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v1.0.8 Vs v2.0.0-rc6 - -时间：2018 年 4 月 - -地点：北京 - -## 测试环境 - -IDC 机器 - -| 类别 | 名称 | -| :--------: | :---------: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD * 1 | - -## 测试方案 - -### TiDB 版本信息 - -### v1.0.8 - -| 组件 | GitHash | -| :--------: | :---------: | -| TiDB | 571f0bbd28a0b8155a5ee831992c986b90d21ab7 | -| TiKV | 4ef5889947019e3cb55cc744f487aa63b42540e7 | -| PD | 776bcd940b71d295a2c7ed762582bc3aff7d3c0e | - -### v2.0.0-rc6 - -| 组件 | GitHash | -| :--------: | :---------: | -| TiDB | 82d35f1b7f9047c478f4e1e82aa0002abc8107e7 | -| TiKV | 7ed4f6a91f92cad5cd5323aaebe7d9f04b77cc79 | -| PD | 2c8e7d7e33b38e457169ce5dfb2f461fced82d65 | - -### TiKV 参数配置 - -* v1.0.8 - - ``` - sync-log = false - grpc-concurrency = 8 - grpc-raft-conn-num = 24 - ``` - -* v2.0.0-rc6 - - ``` - sync-log = false - grpc-concurrency = 8 - grpc-raft-conn-num = 24 - use-delete-range: false - ``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|--------------|------------| -| 172.16.21.1 | 1*tidb 1*pd 1*sysbench | -| 172.16.21.2 | 1*tidb 1*pd 1*sysbench | -| 172.16.21.3 | 1*tidb 1*pd 1*sysbench | -| 172.16.11.4 | 1*tikv | -| 172.16.11.5 | 1*tikv | -| 172.16.11.6 | 1*tikv | -| 172.16.11.7 | 1*tikv | -| 172.16.11.8 | 1*tikv | -| 172.16.11.9 | 1*tikv | - -## 测试结果 - -### 标准 Select 测试 - -| 版本 | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 201936 | 1.9033 ms / 5.67667 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 208130 | 3.69333 ms / 8.90333 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 211788 | 7.23333 ms / 15.59 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 212868 | 14.5933 ms / 43.2133 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 188686 | 2.03667 ms / 5.99 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 195090 |3.94 ms / 9.12 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 203012 | 7.57333 ms / 15.3733 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 205932 | 14.9267 ms / 40.7633 ms | - -GA2.0 比 GA1.0 在 Select 查询性能上，最高提升了 10% 左右。 - -### 标准 OLTP 测试 - -| 版本 | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---:| -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 5404.22 | 108084.4 | 87.2033 ms / 110 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 5578.165 | 111563.3 | 167.673 ms / 275.623 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 5874.045 | 117480.9 | 315.083 ms / 674.017 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 6290.7 | 125814 | 529.183 ms / 857.007 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 5523.91 | 110478 | 69.53 ms / 88.6333 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 5969.43 | 119389 |128.63 ms / 162.58 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 6308.93 | 126179 | 243.543 ms / 310.913 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 6444.25 | 128885 | 476.787ms / 635.143 ms | - -GA2.0 比 GA1.0 在 OLTP 性能上，性能基本一致。 - -### 标准 Insert 测试 - -| 版本 | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 31707.5 | 12.11 ms / 21.1167 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 38741.2 | 19.8233 ms / 39.65 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 45136.8 | 34.0267 ms / 66.84 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 48667 | 63.1167 ms / 121.08 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 31125.7 | 12.3367 ms / 19.89 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 36800 | 20.8667 ms / 35.3767 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 44123 | 34.8067 ms / 63.32 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 48496 | 63.3333 ms / 118.92 ms | - -GA2.0 比 GA1.0 在 Insert 性能上略有提升。 diff --git a/v2.1/benchmark/sysbench-v3.md b/v2.1/benchmark/sysbench-v3.md deleted file mode 100644 index 35270f2451c3..000000000000 --- a/v2.1/benchmark/sysbench-v3.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 -category: benchmark ---- - -# TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 - -## 测试目的 - -对比 TiDB 2.1 版本和 2.0 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v2.1.0-rc.2 vs. v2.0.6 - -时间：2018 年 9 月 - -地点：北京 - -## 测试环境 - -IDC 机器： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD \* 1 | - -Sysbench 版本：1.1.0 - -## 测试方案 - -使用 Sysbench 向集群导入 **16 张表，每张数据 1000 万**。通过 HAProxy 代理，分别以递增并发数向集群发送请求，单次并发测试时间 5 分钟。 - -### TiDB 版本信息 - -### v2.1.0-rc.2 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 08e56cd3bae166b2af3c2f52354fbc9818717f62 | -| TiKV | 57e684016dafb17dc8a6837d30224be66cbc7246 | -| PD | 6a7832d2d6e5b2923c79683183e63d030f954563 | - -### v2.0.6 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | b13bc08462a584a085f377625a7bab0cc0351570 | -| TiKV | 57c83dc4ebc93d38d77dc8f7d66db224760766cc | -| PD | b64716707b7279a4ae822be767085ff17b5f3fea | - -### TiDB 参数配置 - -两版本 TiDB 均使用**默认配置**。 - -### TiKV 参数配置 - -两版本 TiKV 均使用如下配置： - -```txt -[readpool.storage] -normal-concurrency = 8 -[server] -grpc-concurrency = 8 -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "60GB" -[rocksdb.writecf] -block-cache-size = "20GB" -``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-: | :-: | -| 172.16.30.31 | 1\*Sysbench 1\*HAProxy | -| 172.16.30.32 | 1\*TiDB 1\*pd 1\*TiKV | -| 172.16.30.33 | 1\*TiDB 1\*TiKV | -| 172.16.30.34 | 1\*TiDB 1\*TiKV | - -## 测试结果 - -### Point Select 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 111481.09 | 1.16 | -| v2.1 | 128 | 145102.62 | 2.52 | -| v2.1 | 256 | 161311.9 | 4.57 | -| v2.1 | 512 | 184991.19 | 7.56 | -| v2.1 | 1024 | 230282.74 | 10.84 | -| v2.0 | 64 | 75285.87 | 1.93 | -| v2.0 | 128 | 92141.79 | 3.68 | -| v2.0 | 256 | 107464.93 | 6.67 | -| v2.0 | 512 | 121350.61 | 11.65 | -| v2.0 | 1024 | 150036.31 | 17.32 | - -![point select](/media/sysbench_v3_point_select.png) - -v2.1 比 v2.0 在 Point Select 查询性能上，**提升了 50%**。 - -### Update Non-Index 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 18946.09 | 5.77 | -| v2.1 | 128 | 22022.82 | 12.08 | -| v2.1 | 256 | 24679.68 | 25.74 | -| v2.1 | 512 | 25107.1 | 51.94 | -| v2.1 | 1024 | 27144.92 | 106.75 | -| v2.0 | 64 | 16316.85 | 6.91 | -| v2.0 | 128 | 20944.6 | 11.45 | -| v2.0 | 256 | 24017.42 | 23.1 | -| v2.0 | 512 | 25994.33 | 46.63 | -| v2.0 | 1024 | 27917.52 | 92.42 | - -![update non-index](/media/sysbench_v3_update_non_index.png) - -v2.1 与 v2.0 在 Update Non-Index 写入性能上基本一致。 - -### Update Index 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 9934.49 | 12.08 | -| v2.1 | 128 | 10505.95 | 25.28 | -| v2.1 | 256 | 11007.7 | 55.82 | -| v2.1 | 512 | 11198.81 | 106.75 | -| v2.1 | 1024 | 11591.89 | 200.47 | -| v2.0 | 64 | 9754.68 | 11.65 | -| v2.0 | 128 | 10603.31 | 24.38 | -| v2.0 | 256 | 11011.71 | 50.11 | -| v2.0 | 512 | 11162.63 | 104.84 | -| v2.0 | 1024 | 12067.63 | 179.94 | - -![update index](/media/sysbench_v3_update_index.png) - -v2.1 与 v2.0 在 Update Index 写入性能上基本一致。 diff --git a/v2.1/benchmark/sysbench.md b/v2.1/benchmark/sysbench.md deleted file mode 100644 index 41c6f79e10e0..000000000000 --- a/v2.1/benchmark/sysbench.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: TiDB Sysbench 性能测试报告 - v1.0.0 -category: benchmark -draft: true ---- - -# TiDB Sysbench 性能测试报告 - v1.0.0 - -## 测试目的 - -测试 TiDB 在 OLTP 场景下的性能以及水平扩展能力。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试版本、时间、地点 - -TiDB 版本：v1.0.0 -时间：2017 年 10 月 20 日 -地点：北京 - -## 测试环境 - -IDC 机器 - -| 类别 | 名称 | -| :--------: | :---------: | -| OS | linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | 1.5T SSD \* 2 + Optane SSD \* 1 | - -Sysbench 版本: 1.0.6 - -测试脚本: - -## 测试方案 - -### 场景一：sysbench 标准性能测试 - -测试表结构 - -``` -CREATE TABLE `sbtest` ( - `id` int(10) unsigned NOT NULL AUTO_INCREMENT, - `k` int(10) unsigned NOT NULL DEFAULT '0', - `c` char(120) NOT NULL DEFAULT '', - `pad` char(60) NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB -``` - -部署方案以及配置参数 - -``` -// TiDB 部署方案 -172.16.20.4 4*tikv 1*tidb 1*sysbench -172.16.20.6 4*tikv 1*tidb 1*sysbench -172.16.20.7 4*tikv 1*tidb 1*sysbench -172.16.10.8 1*tidb 1*pd 1*sysbench - -// 每个物理节点有三块盘： -data3: 2 tikv (Optane SSD) -data2: 1 tikv -data1: 1 tikv - -// TiKV 参数配置 -sync-log = false -grpc-concurrency = 8 -grpc-raft-conn-num = 24 -[defaultcf] -block-cache-size = "12GB" -[writecf] -block-cache-size = "5GB" -[raftdb.defaultcf] -block-cache-size = "2GB" - -// Mysql 部署方案 -// 分别使用半同步复制和异步复制，部署两副本 -172.16.20.4 master -172.16.20.6 slave -172.16.20.7 slave -172.16.10.8 1*sysbench -Mysql version: 5.6.37 - -// Mysql 参数配置 -thread_cache_size = 64 -innodb_buffer_pool_size = 64G -innodb_file_per_table = 1 -innodb_flush_log_at_trx_commit = 0 -datadir = /data3/mysql -max_connections = 2000 -``` - -* 标准 oltp 测试 - -| - | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 3834 | 76692 | 67.04 ms / 110.88 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 4172 | 83459 | 124.00 ms / 194.21 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 4577 | 91547 | 228.36 ms / 334.02 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 4032 | 80657 | 256.62 ms / 443.88 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 3811 | 76233 | 269.46 ms / 505.20 ms | -| Mysql | 32 | 100 万 | 64 | 2392 | 47845 | 26.75 ms / 73.13 ms | -| Mysql | 32 | 100 万 | 128 | 2493 | 49874 | 51.32 ms / 173.58 ms | -| Mysql | 32 | 100 万 | 256 | 2561 | 51221 | 99.95 ms / 287.38 ms | -| Mysql | 32 | 500 万 | 256 | 1902 | 38045 | 134.56 ms / 363.18 ms | -| Mysql | 32 | 1000 万 | 256 | 1770 | 35416 | 144.55 ms / 383.33 ms | - -![sysbench-01](/media/sysbench-01.png) - -![sysbench-02](/media/sysbench-02.png) - -* 标准 select 测试 - -| - | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 160299 | 1.61ms / 50.06 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 183347 | 2.85 ms / 8.66 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 196515 | 5.42 ms / 14.43 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 187628 | 5.66 ms / 15.04 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 187440 | 5.65 ms / 15.37 ms | -| Mysql | 32 | 100 万 | 64 | 359572 | 0.18 ms / 0.45 ms | -| Mysql | 32 | 100 万 | 128 | 410426 |0.31 ms / 0.74 ms | -| Mysql | 32 | 100 万 | 256 | 396867 | 0.64 ms / 1.58 ms | -| Mysql | 32 | 500 万 | 256 | 386866 | 0.66 ms / 1.64 ms | -| Mysql | 32 | 1000 万 | 256 | 388273 | 0.66 ms / 1.64 ms | - -![sysbench-03](/media/sysbench-03.png) - -![sysbench-04](/media/sysbench-04.png) - -* 标准 insert 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 25308 | 10.12 ms / 25.40 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 28773 | 17.80 ms / 44.58 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 32641 | 31.38 ms / 73.47 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 30430 | 33.65 ms / 79.32 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 28925 | 35.41 ms / 78.96 ms | -| Mysql | 32 | 100 万 | 64 | 14806 | 4.32 ms / 9.39 ms | -| Mysql | 32 | 100 万 | 128 | 14884 | 8.58 ms / 21.11 ms | -| Mysql | 32 | 100 万 | 256 | 14508 | 17.64 ms / 44.98 ms | -| Mysql | 32 | 500 万 | 256 | 10593 | 24.16 ms / 82.96 ms | -| Mysql | 32 | 1000 万 | 256 | 9813 | 26.08 ms / 94.10 ms | - -![sysbench-05](/media/sysbench-05.png) - -![sysbench-06](/media/sysbench-06.png) - -### 场景二：TiDB 水平扩展能力测试 - -部署方案以及配置参数 - -``` -// TiDB 部署方案 -172.16.20.3 4*tikv -172.16.10.2 1*tidb 1*pd 1*sysbench - -每个物理节点有三块盘： -data3: 2 tikv (Optane SSD) -data2: 1 tikv -data1: 1 tikv - -// TiKV 参数配置 -sync-log = false -grpc-concurrency = 8 -grpc-raft-conn-num = 24 -[defaultcf] -block-cache-size = "12GB" -[writecf] -block-cache-size = "5GB" -[raftdb.defaultcf] -block-cache-size = "2GB" -``` - -* 标准 oltp 测试 - -| - | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| 1 物理节点 TiDB | 32 | 100 万 | 256 * 1 | 2495 | 49902 | 102.42 ms / 125.52 ms | -| 2 物理节点 TiDB | 32 | 100 万 | 256 * 2 | 5007 | 100153 | 102.23 ms / 125.52 ms | -| 4 物理节点 TiDB | 32 | 100 万 | 256 * 4 | 8984 | 179692 | 114.96 ms / 176.73 ms | -| 6 物理节点 TiDB | 32 | 500 万 | 256 * 6 | 12953 | 259072 | 117.80 ms / 200.47 ms | - -![sysbench-07](/media/sysbench-07.png) - -* 标准 select 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| 1 物理节点 TiDB | 32 | 100 万 | 256 * 1 | 71841 | 3.56 ms / 8.74 ms | -| 2 物理节点 TiDB | 32 | 100 万 | 256 * 2 | 146615 | 3.49 ms / 8.74 ms | -| 4 物理节点 TiDB | 32 | 100 万 | 256 * 4 | 289933 | 3.53 ms / 8.74 ms | -| 6 物理节点 TiDB | 32 | 500 万 | 256 * 6 | 435313 | 3.55 ms / 9.17 ms | - -![sysbench-08](/media/sysbench-08.png) - -* 标准 insert 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| 3 物理节点 TiKV | 32 | 100 万 |256 * 3 | 40547 | 18.93 ms / 38.25 ms | -| 5 物理节点 TiKV | 32 | 100 万 | 256 * 3 | 60689 | 37.96 ms / 29.9 ms | -| 7 物理节点 TiKV | 32 | 100 万 | 256 * 3 | 80087 | 9.62 ms / 21.37 ms | - -![sysbench-09](/media/sysbench-09.png) diff --git a/v2.1/benchmark/tpch-v2.md b/v2.1/benchmark/tpch-v2.md deleted file mode 100644 index 3989420e74e0..000000000000 --- a/v2.1/benchmark/tpch-v2.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: TiDB TPC-H 50G 性能测试报告 -category: benchmark ---- - -# TiDB TPC-H 50G 性能测试报告 - -## 测试目的 - -测试 TiDB 在 OLAP 场景下 2.0 和 2.1 版本的性能对比。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试环境 - -### 测试机器信息 - -1. 系统信息 - -| 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | -|--------------|------------------------|------------------------------|--------------| -| 10.0.1.4 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.5 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.6 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.7 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.8 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.9 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - -2. 硬件信息 - -| 类别 | 10.0.1.4 | 10.0.1.5, 10.0.1.6, 10.0.1.7, 10.0.1.8, 10.0.1.9 | -|------------|------------------------------------------------------|------------------------------------------------------| -| CPU | 16 vCPUs, Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz | 8 vCPUs, Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz | -| 内存 | 110G | 55G | -| 磁盘 | 221G SSD | 111G SSD | -| 网卡 | 万兆网卡, 10000Mb/s | 万兆网卡, 10000Mb/s | - -### TPC-H - -[tidb-bench/tpch](https://github.com/pingcap/tidb-bench/tree/master/tpch) - -### 集群拓扑 - -| 机器 IP | 部署的实例 | -|----------|------------| -| 10.0.1.5 | TiKV \* 1 | -| 10.0.1.6 | TiKV \* 1 | -| 10.0.1.7 | TiKV \* 1 | -| 10.0.1.8 | TiKV \* 1 | -| 10.0.1.9 | TiKV \* 1 | -| 10.0.1.4 | PD \* 1 | -| 10.0.1.4 | TiDB \* 1 | - -### TiDB 版本信息 - -TiDB 2.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.0.7 | 29ec059cb3b7d14b6f52c2f219f94a89570162bc | -| TiKV | v2.0.7 | d0b8cd7c7f62f06e7ef456837bd32a47da1ca4cd | -| PD | v2.0.5 | b64716707b7279a4ae822be767085ff17b5f3fea | - -TiDB 2.1： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.1.0-rc.2 | 16864f95b47f859ed6104555ccff0387abdc2429 | -| TiKV | v2.1.0-rc.2 | 8458ce53ebbd434c48baac6373fe0f0a43a54005 | -| PD | v2.1.0-rc.2 | 55db505e8f35e8ab4e00efd202beb27a8ecc40fb | - -## 测试结果 - -| Query ID | TiDB 2.0 | TiDB 2.1 | -|-----------|----------------|----------------| -| 1 | 121.550595999s | 91.4755480289s | -| 2 | 53.0638680458s | 23.1186130047s | -| 3 | 75.7236940861s | 61.790802002s | -| 4 | 30.2647120953s | 26.3483440876s | -| 6 | 51.4850790501s | 34.6432199478s | -| 7 | 216.787364006s | 94.9856910706s | -| 8 | 188.717588902s | 181.852752209s | -| 9 | 546.438174009s | 414.462754965s | -| 10 | 109.978317022s | 37.0369961262s | -| 11 | 42.9398438931s | 37.6951580048s | -| 12 | 60.455039978s | 40.2236878872s | -| 13 | 230.278712988s | 70.2887151241s | -| 14 | 61.2673521042s | 35.8372960091s | -| 16 | 30.2539310455s | 18.5897550583s | -| 17 | 3200.70173788s | 263.095014811s | -| 18 | 1035.59847498s | 296.360667944s | -| 19 | 54.3732938766s | 40.4523630142s | -| 20 | 105.094577074s | 53.2429068089s | -| 21 | 389.883709908s | 361.034544945s | -| 22 | 64.0494630337s | 65.7153418064s | - -![TPC-H Query Result](/media/tpch-query-result-v2.png) - -说明： -- 图中橙色为 Release 2.1，蓝色为 Release 2.0，纵坐标是 Query 的处理时间，越低越好 -- Query 15 因为 2.1 和 2.0 都还未支持视图，所以未列出结果 -- Query 5 因为 Join Order 问题长时间未跑出结果来，所以未列出结果 diff --git a/v2.1/benchmark/tpch.md b/v2.1/benchmark/tpch.md deleted file mode 100644 index a008d6c637a0..000000000000 --- a/v2.1/benchmark/tpch.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: TiDB TPC-H 50G 性能测试报告 -category: benchmark ---- - -# TiDB TPC-H 50G 性能测试报告 - -## 测试目的 - -测试 TiDB 在 OLAP 场景下 1.0 和 2.0 版本的性能对比。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试环境 - -### 测试机器信息 - -1. 系统信息 - -| 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | -|--------------|------------------------|------------------------------|--------------| -| 172.16.31.2 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | -| 172.16.31.3 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | -| 172.16.31.4 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | -| 172.16.31.6 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | -| 172.16.31.8 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | -| 172.16.31.10 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | - -2. 硬件信息 - -| 类别 | 名称 | -|------------|------------------------------------------------------| -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| 内存 | 128GB, 8条16GB RDIMM, 2400MT/s, 双列, x8 带宽 | -| 磁盘 | 2 块 Intel P4500 系列 4T SSD 硬盘 | -| 网卡 | 万兆网卡 | - -### TPC-H - -[tidb-bench/tpch](https://github.com/pingcap/tidb-bench/tree/master/tpch) - -### 集群拓扑 - -| 机器 IP | 部署的实例 | -|--------------|------------| -| 172.16.31.2 | TiKV \* 2 | -| 172.16.31.3 | TiKV \* 2 | -| 172.16.31.6 | TiKV \* 2 | -| 172.16.31.8 | TiKV \* 2 | -| 172.16.31.10 | TiKV \* 2 | -| 172.16.31.10 | PD \* 1 | -| 172.16.31.4 | TiDB \* 1 | - -### TiDB 版本信息 - -TiDB 1.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v1.0.9 | 4c7ee3580cd0a69319b2c0c08abdc59900df7344 | -| TiKV | v1.0.8 | 2bb923a4cd23dbf68f0d16169fd526dc5c1a9f4a | -| PD | v1.0.8 | 137fa734472a76c509fbfd9cb9bc6d0dc804a3b7 | - -TiDB 2.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.0.0-rc.6 | 82d35f1b7f9047c478f4e1e82aa0002abc8107e7 | -| TiKV | v2.0.0-rc.6 | 8bd5c54966c6ef42578a27519bce4915c5b0c81f | -| PD | v2.0.0-rc.6 | 9b824d288126173a61ce7d51a71fc4cb12360201 | - -## 测试结果 - -| Query ID | TiDB 2.0 | TiDB 1.0 | -|-----------|--------------------|------------------| -| 1 | 33.915s | 215.305s | -| 2 | 25.575s | NaN | -| 3 | 59.631s | 196.003s | -| 4 | 30.234s | 249.919s | -| 5 | 31.666s | OOM | -| 6 | 13.111s | 118.709s | -| 7 | 31.710s | OOM | -| 8 | 31.734s | 800.546s | -| 9 | 34.211s | 630.639s | -| 10 | 30.774s | 133.547s | -| 11 | 27.692s | 78.026s | -| 12 | 27.962s | 124.641s | -| 13 | 27.676s | 174.695s | -| 14 | 19.676s | 110.602s | -| 15 | View Required | View Required | -| 16 | 24.890s | 40.529s | -| 17 | 245.796s | NaN | -| 18 | 91.256s | OOM | -| 19 | 37.615s | NaN | -| 20 | 44.167s | 212.201s | -| 21 | 31.466s | OOM | -| 22 | 31.539s | 125.471s | - -![TPC-H Query Result](/media/tpch-query-result.png) - -说明： -- 图中橙色为 Release 1.0，蓝色为 Release 2.0，纵坐标是 Query 的处理时间，越低越好 -- Query 15 因为 1.0 和 2.0 都还未支持视图，所以结果标记为 "View Required" -- Query 2, 17, 19 因为 TiDB 1.0 长时间未跑出结果，所以结果标记为 "Nan" -- Query 5, 7, 18, 21 因为 TiDB 1.0 在跑的过程中内存占用过多被 oom-killer 杀死，所以结果标记为 "OOM" diff --git a/v2.1/contribute.md b/v2.1/contribute.md deleted file mode 100644 index 33a8555c20e8..000000000000 --- a/v2.1/contribute.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 成为贡献者 -category: contribute ---- - -# 成为贡献者 - -## 成为 TiDB 的贡献者 - -我们推荐您先尝试解决带 [help-wanted](https://github.com/pingcap/tidb/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) 标签的现有 Issue，这些问题非常适合新的贡献者。 - -一旦您提交给 [TiDB/TiKV/TiSpark/PD/Docs/Docs-cn](https://github.com/pingcap) 项目的 PR (Pull Request) 被批准且合并，您即成为 TiDB 的贡献者。 - -在提交 PR 之前，请先签署 [CLA](https://cla-assistant.io/pingcap/tidb?pullRequest=5567)。 - -如果您想实践一个影响范围相对较小的新想法，请遵循以下步骤： - -1. 提交新 Issue，描述您对相关仓库的更改建议。 -2. 相关仓库的负责人将及时回复您的 Issue。 -3. 如果您的更改建议被接受，您需要先签署 [CLA](https://cla-assistant.io/pingcap/tidb?pullRequest=5567)，便可以在您的克隆仓库 (fork) 里开始工作了。 -4. 在测试过所做的更改后，您便可以提交[包含更改的 PR](https://github.com/pingcap/tidb/pull/3113) 了。 - -我们欢迎并非常感谢您的贡献。有关提交补丁和贡献流程的详细信息，请参阅[贡献者指南](https://github.com/pingcap/tidb/blob/master/CONTRIBUTING.md)。 - -## 改进文档 - -我们欢迎更多贡献者来帮助改进文档！ - -TiDB 文档使用 Markdown 语言，并参考了 [Google 开发者文档风格指南](https://developers.google.com/style/)进行编写。如果这些概念对您来说比较陌生，请不要担心，我们很乐意为您提供指导。 - -如要对文档仓库进行贡献，请先 fork [docs-cn 仓库](https://github.com/pingcap/docs-cn)，再提交您的 PR。 diff --git a/v2.1/faq/tidb-lightning.md b/v2.1/faq/tidb-lightning.md deleted file mode 100644 index 4f3bebed93f4..000000000000 --- a/v2.1/faq/tidb-lightning.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: TiDB Lightning 常见问题 -category: FAQ ---- - -# TiDB Lightning 常见问题 - -## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ - -最低版本要求是 2.0.9。 - -## TiDB Lightning 支持导入多个库吗？ - -支持。 - -## TiDB Lightning 对下游数据库的账号权限要求是怎样的？ - -TiDB Lightning 需要以下权限： - -* SELECT -* UPDATE -* ALTER -* CREATE -* DROP - -存储断点的数据库额外需要以下权限： - -* INSERT -* DELETE - -如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？ - -如果只是个别表报错，不会影响整体。报错的那个表会停止处理，继续处理其他的表。 - -## 如何校验导入的数据的正确性？ - -TiDB Lightning 默认会对导入数据计算校验和 (checksum)，如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。 - -TiDB 也支持从 MySQL 命令行运行 `ADMIN CHECKSUM TABLE` 指令来计算校验和。 - -```text -mysql> ADMIN CHECKSUM TABLE `schema`.`table`; -+---------+------------+---------------------+-----------+-------------+ -| Db_name | Table_name | Checksum_crc64_xor | Total_kvs | Total_bytes | -+---------+------------+---------------------+-----------+-------------+ -| schema | table | 5505282386844578743 | 3 | 96 | -+---------+------------+---------------------+-----------+-------------+ -1 row in set (0.01 sec) -``` - -## TiDB Lightning 支持哪些格式的数据源？ - -到 v2.1.6 版本为止，只支持本地文档形式的数据源，支持 [Mydumper](/v2.1/reference/tools/mydumper.md) 或 [CSV](/v2.1/reference/tools/tidb-lightning/csv.md) 格式。 - -## 我已经在下游创建好库和表了，Lightning 可以忽略建库建表操作吗？ - -可以。在配置文档中的 `[mydumper]` 将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。 - -## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL MOde) 来导入？ - -可以。Lightning 默认的 [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) 为 `"STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"`。 - -这个设置不允许一些非法的数值，例如 `1970-00-00` 这样的日期。可以修改配置文件 `[tidb]` 下的 `sql-mode` 值。 - -```toml -... -[tidb] -sql-mode = "" -... -``` - -## 可以起一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？ - -只要每个 Lightning 操作的表互不相同就可以。 - -## 如何正确关闭 `tikv-importer` 进程？ - -根据您的部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh` 。 - -- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程ID，然后通过 `kill «pid»` 结束进程。 - -## 如何正确关闭 `tidb-lightning` 进程？ - -根据您的部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh` 。 - -- 手动部署：如果 `tidb-lightning` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tidb-lightning` 获取进程 ID，然后通过 `kill -2 «pid»` 结束进程。 - -## `tidb-lightning` 在服务器上运行，进程莫名其妙地退出了，是怎么回事呢？ - -这种情况可能是启动方式不正确，导致收到 SIGHUP 信号而退出。此时 `tidb-lightning.log` 通常有如下日志： - -``` -2018/08/10 07:29:08.310 main.go:47: [info] Got signal hangup to exit. -``` - -不推荐在命令行中直接使用 `nohup` 启动进程，推荐按照 [启动 tidb-lightning](/v2.1/reference/tools/tidb-lightning/deployment.md) 使用脚本启动。 - -## 为什么用过 TiDB Lightning 之后，TiDB 集群变得又慢又耗 CPU？ - -如果 `tidb-lightning` 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)： - -```sh -tidb-lightning-ctl --switch-mode=normal -``` - -## TiDB Lightning 可以使用千兆网卡吗？ - -使用 TiDB Lightning 必须配置万兆网卡。**不能使用**千兆网卡，尤其是在部署 `tikv-importer` 的机器上。千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。 - -## 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间？ - -当使用默认的 3 副本设置时，TiDB Lightning 需要 TiKV 集群预留数据源大小 6 倍的空间。多出来的 2 倍是算上下列没储存在数据源的因素的保守估计： - -- 索引会占据额外的空间 -- RocksDB 的空间放大效应 - -## TiDB Lightning 使用过程中是否可以重启 TiKV Importer？ - -不能，Importer 会保存一些 Engine 的信息在内存中，Importer 重启后，Lightning 必须重启。 diff --git a/v2.1/faq/tidb.md b/v2.1/faq/tidb.md deleted file mode 100755 index dbb01adde760..000000000000 --- a/v2.1/faq/tidb.md +++ /dev/null @@ -1,1068 +0,0 @@ ---- -title: TiDB FAQ -category: FAQ ---- - -# FAQ - -## 一、 TiDB 介绍、架构、原理 - -### 1.1 TiDB 介绍及整体架构 - -#### 1.1.1 TiDB 整体架构 - -[TiDB 简介](/v2.1/overview.md#tidb-简介) - -#### 1.1.2 TiDB 是什么？ - -TiDB 是一个分布式 NewSQL 数据库。它支持水平弹性扩展、ACID 事务、标准 SQL、MySQL 语法和 MySQL 协议，具有数据强一致的高可用特性，是一个不仅适合 OLTP 场景还适合 OLAP 场景的混合数据库。 - -#### 1.1.3 TiDB 是基于 MySQL 开发的吗？ - -不是，虽然 TiDB 支持 MySQL 语法和协议，但是 TiDB 是由 PingCAP 团队完全自主开发的产品。 - -#### 1.1.4 TiDB、TiKV、Placement Driver (PD) 主要作用？ - -- TiDB 是 Server 计算层，主要负责 SQL 的解析、制定查询计划、生成执行器。 -- TiKV 是分布式 Key-Value 存储引擎，用来存储真正的数据，简而言之，TiKV 是 TiDB 的存储引擎。 -- PD 是 TiDB 集群的管理组件，负责存储 TiKV 的元数据，同时也负责分配时间戳以及对 TiKV 做负载均衡调度。 - -#### 1.1.5 TiDB 易用性如何？ - -TiDB 使用起来很简单，可以将 TiDB 集群当成 MySQL 来用，你可以将 TiDB 用在任何以 MySQL 作为后台存储服务的应用中，并且基本上不需要修改应用代码，同时你可以用大部分流行的 MySQL 管理工具来管理 TiDB。 - -#### 1.1.6 TiDB 和 MySQL 兼容性如何？ - -TiDB 目前还不支持触发器、存储过程、自定义函数、外键，除此之外，TiDB 支持绝大部分 MySQL 5.7 的语法。 - -详情参见[与 MySQL 兼容性对比](/v2.1/reference/mysql-compatibility.md)。 - -#### 1.1.7 TiDB 具备高可用的特性吗？ - -TiDB 天然具备高可用特性，TiDB、TiKV、PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。具体见 [TiDB 高可用性](/v2.1/key-features.md#高可用)。 - -#### 1.1.8 TiDB 数据是强一致的吗？ - -TiDB 实现了快照隔离 (Snapshot Isolation) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。 - -在底层，TiKV 使用复制日志 + 状态机 (State Machine) 的模型来复制数据。对于写入请求，数据被写入 Leader，然后 Leader 以日志的形式将命令复制到它的 Follower 中。当集群中的大多数节点收到此日志时，日志会被提交，状态机会相应作出变更。 - -#### 1.1.9 TiDB 支持分布式事务吗？ - -支持。无论是一个地方的几个节点，还是[跨多个数据中心的多个节点](/v2.1/how-to/deploy/geographic-redundancy/overview.md)，TiDB 均支持 ACID 分布式事务。 - -TiDB 事务模型灵感源自 Google Percolator 模型，主体是一个两阶段提交协议，并进行了一些实用的优化。该模型依赖于一个时间戳分配器，为每个事务分配单调递增的时间戳，这样就检测到事务冲突。在 TiDB 集群中，[PD](/v2.1/architecture.md#pd-server) 承担时间戳分配器的角色。 - -#### 1.1.10 TiDB 支持哪些编程语言？ - -只要支持 MySQL Client/Driver 的编程语言，都可以直接使用 TiDB。 - -#### 1.1.11 TiDB 是否支持其他存储引擎？ - -是的，除了 TiKV 之外，TiDB 还支持一些流行的单机存储引擎，比如 GolevelDB、RocksDB、BoltDB 等。如果一个存储引擎是支持事务的 KV 引擎，并且能提供一个满足 TiDB 接口要求的 Client，即可接入 TiDB。 - -#### 1.1.12 官方有没有三中心跨机房多活部署的推荐方案？ - -从 TiDB 架构来讲，支持真正意义上的跨中心异地多活，从操作层面讲，依赖数据中心之间的网络延迟和稳定性，一般建议延迟在 5ms 以下，目前我们已经有相似客户方案，具体请咨询官方 [info@pingcap.com](mailto:info@pingcap.com)。 - -#### 1.1.13 除了官方文档，有没有其他 TiDB 知识获取途径？ - -目前[官方文档](/v2.1/overview.md#tidb-简介)是获取 TiDB 相关知识最主要、最及时的发布途径。除此之外，我们也有一些技术沟通群，如有需求可发邮件至 [info@pingcap.com](mailto:info@pingcap.com) 获取。 - -#### 1.1.14 TiDB 对哪些 MySQL variables 兼容？ - -详细可参考[系统变量](/v2.1/reference/configuration/tidb-server/mysql-variables.md)。 - -#### 1.1.15 TiDB 是否支持 select for update？ - -支持，但语义上和 MySQL 有区别，TiDB 是分布式数据库，采用的乐观锁机制，也就说 select for update 不在事务开启就锁住数据，而是其他事务在提交的时候进行冲突检查，如有冲突，会进行回滚。 - -#### 1.1.16 TiDB 的 codec 能保证 UTF8 的字符串是 memcomparable 的吗？我们的 key 需要支持 UTF8，有什么编码建议吗？ - -TiDB 字符集默认就是 UTF8 而且目前只支持 UTF8，字符串就是 memcomparable 格式的。 - -#### 1.1.17 TiDB 用户名长度限制？ - -在 TiDB 中用户名最长为 32 字符。 - -#### 1.1.18 一个事务中的语句数量最大是多少？ - -一个事务中的语句数量，默认限制最大为 5000 条。 - -#### 1.1.19 TiDB 是否支持 XA？ - -虽然 TiDB 的 JDBC 驱动用的就是 MySQL JDBC（Connector / J），但是当使用 Atomikos 的时候，数据源要配置成类似这样的配置：`type="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"`。MySQL JDBC XADataSource 连接 TiDB 的模式目前是不支持的。MySQL JDBC 中配置好的 XADataSource 模式，只对 MySQL 数据库起作用（DML 去修改 redo 等）。 - -Atomikos 配好两个数据源后，JDBC 驱动都要设置成 XA 模式，然后 Atomikos 在操作 TM 和 RM（DB）的时候，会通过数据源的配置，发起带有 XA 指令到 JDBC 层，JDBC 层 XA 模式启用的情况下，会对 InnoDB（如果是 MySQL 的话）下发操作一连串 XA 逻辑的动作，包括 DML 去变更 redo log 等，就是两阶段递交的那些操作。TiDB 目前的引擎版本中，没有对上层应用层 JTA / XA 的支持，不解析这些 Atomikos 发过来的 XA 类型的操作。 - -MySQL 是单机数据库，只能通过 XA 来满足跨数据库事务，而 TiDB 本身就通过 Google 的 Percolator 事务模型支持分布式事务，性能稳定性比 XA 要高出很多，所以不会也不需要支持 XA。 - -#### 1.1.20 show processlist 是否显示系统进程号？ - -TiDB 的 `show processlist` 与 MySQL 的 `show processlist` 显示内容基本一样，不会显示系统进程号，而 ID 表示当前的 session ID。其中 TiDB 的 `show processlist` 和 MySQL 的 `show processlist` 区别如下： - -1）由于 TiDB 是分布式数据库，tidb-server 实例是无状态的 SQL 解析和执行引擎（详情可参考 [TiDB 整体架构](/v2.1/overview.md#tidb-整体架构)），用户使用 MySQL 客户端登录的是哪个 tidb-server，`show processlist` 就会显示当前连接的这个 tidb-server 中执行的 session 列表，不是整个集群中运行的全部 session 列表；而 MySQL 是单机数据库，`show processlist` 列出的是当前整个 MySQL 数据库的全部执行 SQL 列表。 - -2）TiDB 的 `show processlist` 显示内容比起 MySQL 来讲，多了一个当前 session 使用内存的估算值（单位 Byte）。 - -#### 1.1.21 如何修改用户名密码和权限？ - -TiDB 作为分布式数据库，在 TiDB 中修改用户密码建议使用 `set password for 'root'@'%' = '0101001';` 或 `alter` 方法，不推荐使用 `update mysql.user` 的方法进行，这种方法可能会造成其它节点刷新不及时的情况。修改权限也一样，都建议采用官方的标准语法。详情可参考 [TiDB 用户账户管理](/v2.1/reference/security/user-account-management.md)。 - -#### 1.1.22 TiDB 中，为什么出现后插入数据的自增 ID 反而小？ - -TiDB 的自增 ID (`AUTO_INCREMENT`) 只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。当多个线程并发往不同的 tidb-server 插入数据的时候，有可能会出现后插入的数据自增 ID 小的情况。此外，TiDB允许给整型类型的字段指定 AUTO_INCREMENT，且一个表只允许一个属性为 `AUTO_INCREMENT` 的字段。详情可参考[CREATE TABLE 语法](/v2.1/reference/mysql-compatibility.md#自增-id)。 - -#### 1.1.23 sql_mode 默认除了通过命令 set 修改，配置文件怎么修改？ - -TiDB 的 sql_mode 与 MySQL 的 sql_mode 设置方法有一些差别，TiDB 不支持配置文件配置设置数据库的 sql\_mode，而只能使用 set 命令去设置，具体方法为：`set @@global.sql_mode = 'STRICT_TRANS_TABLES';`。 - -#### 1.1.24 TiDB 支持哪些认证协议，过程是怎样的？ - -这一层跟 MySQL 一样，走的 SASL 认证协议，用于用户登录认证，对密码的处理流程。 - -客户端连接 TiDB 的时候，走的是 challenge-response（挑战-应答）的认证模式，过程如下： - -第一步：客户端连接服务器； - -第二步：服务器发送随机字符串 challenge 给客户端； - -第三步：客户端发送 username + response 给服务器； - -第四步：服务器验证 response。 - -### 1.2 TiDB 原理 - -#### 1.2.1 存储 TiKV - -##### 1.2.1.1 TiKV 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说存储](http://t.cn/RTKRRWv) - -#### 1.2.2 计算 TiDB - -##### 1.2.2.1 TiDB 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说计算](http://t.cn/RTKRkBh) - -#### 1.2.3 调度 PD - -##### 1.2.3.1 PD 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 谈调度](http://t.cn/RTKEZ0U) - -## 二、安装部署升级 - -### 2.1 环境准备 - -#### 2.1.1 操作系统版本要求 - -| **Linux 操作系统平台** | **版本** | -| --- | --- | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | - -##### 2.1.1.1 为什么要在 CentOS 7 上部署 TiDB 集群？ - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络，作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境，具体可以参考 TiDB 的[官方部署要求](/v2.1/how-to/deploy/hardware-recommendations.md)。其中 TiDB 在 CentOS 7.3 的环境下进行大量的测试，同时也有很多这个操作系统的部署最佳实践，因此，我们推荐客户在部署 TiDB 的时候使用 CentOS 7.3+ 以上的Linux 操作系统。 - -#### 2.1.2 硬件要求 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -##### 2.1.2.1 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | -| | | | | 服务器总计 | 4 | - -##### 2.1.2.2 线上环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 48 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 8核+ | 16 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 48 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | -| | | | | 服务器总计 | 9 | - -##### 2.1.2.3 2 块网卡的目的是？万兆的目的是？ - -作为一个分布式集群，TiDB 对时间的要求还是比较高的，尤其是 PD 需要分发唯一的时间戳，如果 PD 时间不统一，如果有 PD 切换，将会等待更长的时间。2 块网卡可以做 bond，保证数据传输的稳定，万兆可以保证数据传输的速度，千兆网卡容易出现瓶颈，我们强烈建议使用万兆网卡。 - -##### 2.1.2.4 SSD 不做 RAID 是否可行？ - -资源可接受的话，我们建议做 RAID 10，如果资源有限，也可以不做 RAID。 - -##### 2.1.2.5 TiDB 集群各个组件的配置推荐？ - -- TiDB 需要 CPU 和内存比较好的机器，参考官网配置要求，如果后期需要开启 Binlog，根据业务量的评估和 GC 时间的要求，也需要本地磁盘大一点，不要求 SSD 磁盘； -- PD 里面存了集群元信息，会有频繁的读写请求，对磁盘 I/O 要求相对比较高，磁盘太差会影响整个集群性能，推荐 SSD 磁盘，空间不用太大。另外集群 Region 数量越多对 CPU、内存的要求越高； -- TiKV 对 CPU、内存、磁盘要求都比较高，一定要用 SSD 磁盘。 - -详情可参考 [TiDB 软硬件环境需求](/v2.1/how-to/deploy/hardware-recommendations.md)。 - -### 2.2 安装部署 - -#### 2.2.1 Ansible 部署方式（强烈推荐） - -详细可参考[使用 TiDB Ansible 部署 TiDB 集群](/v2.1/how-to/deploy/orchestrated/ansible.md)。 - -##### 2.2.1.1 为什么修改了 TiKV/PD 的 toml 配置文件，却没有生效？ - -这种情况一般是因为没有使用 `--config` 参数来指定配置文件（目前只会出现在 binary 部署的场景），TiKV/PD 会按默认值来设置。如果要使用配置文件，请设置 TiKV/PD 的 `--config` 参数。对于 TiKV 组件，修改配置后重启服务即可；对于 PD 组件，只会在第一次启动时读取配置文件，之后可以使用 pd-ctl 的方式来修改配置，详情可参考 [PD 配置参数](/v2.1/reference/configuration/pd-server/configuration.md)。 - -##### 2.2.1.2 TiDB 监控框架 Prometheus + Grafana 监控机器建议单独还是多台部署？ - -监控机建议单独部署。建议 CPU 8 core，内存 16 GB 以上，硬盘 500 GB 以上。 - -##### 2.2.1.3 有一部分监控信息显示不出来？ - -查看访问监控的机器时间跟集群内机器的时间差，如果比较大，更正时间后即可显示正常。 - -##### 2.2.1.4 supervise/svc/svstat 服务具体起什么作用？ - -- supervise 守护进程 -- svc 启停服务 -- svstat 查看进程状态 - -##### 2.2.1.5 inventory.ini 变量参数解读 - -| **变量** | **含义** | -| --- | --- | -| cluster_name | 集群名称，可调整 | -| tidb_version | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| deployment_method | 部署方式，默认为 binary，可选 docker | -| process_supervision | 进程监管方式，默认为 systemd，可选 supervise | -| timezone | 修改部署目标机器时区，默认为 Asia/Shanghai, 可调整，与set_timezone 变量结合使用 | -| set_timezone | 默认为 True，即修改部署目标机器时区，关闭可修改为 False | -| enable_elk | 目前不支持，请忽略 | -| enable_firewalld | 开启防火墙，默认不开启 | -| enable_ntpd | 检测部署目标机器 NTP 服务，默认为 True，请勿关闭 | -| machine_benchmark | 检测部署目标机器磁盘 IOPS，默认为 True，请勿关闭 | -| set_hostname | 根据 IP 修改部署目标机器主机名，默认为 False | -| enable_binlog | 是否部署 pump 并开启 binlog，默认为 False，依赖 Kafka 集群，参见 zookeeper_addrs 变量 | -| zookeeper_addrs | binlog Kafka 集群的 zookeeper 地址 | -| enable_slow_query_log | TiDB 慢查询日志记录到单独文件({{ deploy_dir }}/log/tidb_slow_query.log)，默认为 False，记录到 tidb 日志 | -| deploy_without_tidb | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 inventory.ini 文件中 tidb_servers 主机组 IP 设置为空。 | - -#### 2.2.2 TiDB 离线 Ansible 部署方案 - -首先这不是我们建议的方式，如果中控机没有外网，也可以通过离线 Ansible 部署方式，详情可参考[离线 TiDB Ansible 部署方案](/v2.1/how-to/deploy/orchestrated/offline-ansible.md)。 - -#### 2.2.3 Docker Compose 快速构建集群（单机部署） - -使用 docker-compose 在本地一键拉起一个集群，包括集群监控，还可以根据需求自定义各个组件的软件版本和实例个数，以及自定义配置文件，这种只限于开发环境，详细可参考[官方文档](https://pingcap.com/docs-cn/dev/how-to/get-started/deploy-tidb-from-docker-compose/)。 - -#### 2.2.4 如何单独记录 TiDB 中的慢查询日志，如何定位慢查询 SQL？ - -1）TiDB 中，对慢查询的定义在 tidb-ansible 的 `conf/tidb.yml` 配置文件中，`slow-threshold: 300`，这个参数是配置慢查询记录阈值的，单位是 ms。 - -慢查询日志默认记录到 tidb.log 中，如果希望生成单独的慢查询日志文件，修改 inventory.ini 配置文件的参数 `enable_slow_query_log` 为 True。 - -如上配置修改之后，需要执行 `ansible-playbook rolling_update.yml --tags=tidb`，对 tidb-server 实例进行滚动升级，升级完成后，tidb-server 将在 `tidb_slow_query.log` -文件中记录慢查询日志。 - -2）如果出现了慢查询，可以从 Grafana 监控定位到出现慢查询的 tidb-server 以及时间点，然后在对应节点查找日志中记录的 SQL 信息。 - -3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/v2.1/how-to/maintain/identify-slow-queries.md#admin-show-slow-命令)。 - -#### 2.2.5 首次部署 TiDB 集群时，没有配置 tikv 的 Label 信息，在后续如何添加配置 Label？ - -TiDB 的 Label 设置是与集群的部署架构相关的，是集群部署中的重要内容，是 PD 进行全局管理和调度的依据。如果集群在初期部署过程中没有设置 Label，需要在后期对部署结构进行调整，就需要手动通过 PD 的管理工具 pd-ctl 来添加 location-labels 信息，例如：`config set location-labels "zone,rack,host"`（根据实际的 label 层级名字配置）。 - -pd-ctl 的使用参考 [PD Control 使用说明](/v2.1/reference/tools/pd-control.md)。 - -#### 2.2.6 为什么测试磁盘的 dd 命令用 oflag=direct 这个选项？ - -Direct 模式就是把写入请求直接封装成 I/O 指令发到磁盘，这样是为了绕开文件系统的缓存，可以直接测试磁盘的真实的 I/O 读写能力。 - -#### 2.2.7 如何用 fio 命令测试 TiKV 实例的磁盘性能？ - -- 随机读测试： - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randread -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json - ``` - -- 顺序写和随机读混合测试： - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randrw -percentage_random=100,0 -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json - ``` - -#### 2.2.8 使用 TiDB Ansible 部署 TiDB 集群的时候，遇到 `UNREACHABLE! "msg": "Failed to connect to the host via ssh: "` 报错是什么原因？ - -有两种可能性： - -- ssh 互信的准备工作未做好，建议严格参照我们的[官方文档步骤](/v2.1/how-to/deploy/orchestrated/ansible.md)配置互信，并使用命令 `ansible -i inventory.ini all -m shell -a 'whoami' -b` 来验证互信配置是否成功。 - -- 如果涉及到单服务器分配了多角色的场景，例如多组件混合部署或单台服务器部署了多个 TiKV 实例，可能是由于 ssh 复用的机制引起这个报错，可以使用 `ansible … -f 1` 的选项来规避这个报错。 - -### 2.3 升级 - -#### 2.3.1 如何使用 Ansible 滚动升级？ - -滚动升级 TiKV 节点( 只升级单独服务 ) - -`ansible-playbook rolling_update.yml --tags=tikv` - -滚动升级所有服务 - -`ansible-playbook rolling_update.yml` - -#### 2.3.2 滚动升级有那些影响? - -滚动升级 TiDB 服务，滚动升级期间不影响业务运行，需要配置最小集群拓扑（TiDB \* 2、PD \* 3、TiKV \* 3），如果集群环境中有 Pump/Drainer 服务，建议先停止 Drainer 后滚动升级（升级 TiDB 时会升级 Pump）。 - -#### 2.3.3 Binary 如何升级？ - -Binary 不是我们建议的安装方式，对升级支持也不友好，建议换成 Ansible 部署。 - -#### 2.3.4 一般升级选择升级 TiKV 还是所有组件都升级？ - -常规需要一起升，因为整个版本都是一起测试的，单独升级只限当发生一个紧急故障时，需要单独对一个有问题的角色做升级。 - -#### 2.3.5 启动集群或者升级集群过程中出现 “Timeout when waiting for search string 200 OK” 是什么原因？如何处理？ - -可能有以下几种原因：进程没有正常启动；端口被占用；进程没有正常停掉；停掉集群的情况下使用 rolling_update.yml 来升级集群（操作错误）。 - -处理方式：登录到相应节点查看进程或者端口的状态；纠正错误的操作步骤。 - -## 三、集群管理 - -### 3.1 集群日常管理 - -#### 3.1.1 Ansible 常见运维操作有那些？ - -| **任务** | **Playbook** | -| --- | --- | -| 启动集群 | ansible-playbook start.yml | -| 停止集群 | ansible-playbook stop.yml | -| 销毁集群 | ansible-playbook unsafe\_cleanup.yml (若部署目录为挂载点，会报错，可忽略） | -| 清除数据(测试用) | ansible-playbook cleanup\_data.yml | -| 滚动升级 | ansible-playbook rolling\_update.yml | -| 滚动升级 TiKV | ansible-playbook rolling\_update.yml --tags=tikv | -| 滚动升级除 PD 外模块 | ansible-playbook rolling\_update.yml --skip-tags=pd | -| 滚动升级监控组件 | ansible-playbook rolling\_update\_monitor.yml | - -#### 3.1.2 TiDB 如何登录？ - -和 MySQL 登录方式一样，可以按照下面例子进行登录。 - -`mysql -h 127.0.0.1 -uroot -P4000` - -#### 3.1.3 TiDB 如何修改数据库系统变量？ - -和 MySQL 一样，TiDB 也分为静态参数和固态参数，静态参数可以直接通过`set global xxx = n`的方式进行修改，不过新参数值只限于该实例生命周期有效。 - -#### 3.1.4 TiDB (TiKV) 有哪些数据目录？ - -默认在 [`--data-dir`](/v2.1/reference/configuration/tikv-server/configuration.md#--data-dir) 目录下，其中包括 backup、db、raft、snap 四个目录，分别存储备份、数据、raft 数据及镜像数据。 - -#### 3.1.5 TiDB 有哪些系统表？ - -和 MySQL 类似，TiDB 中也有系统表，用于存放数据库运行时所需信息，具体信息参考 [TiDB 系统数据库](/v2.1/reference/system-databases/mysql.md)文档。 - -#### 3.1.6 TiDB 各节点服务器下是否有日志文件，如何管理？ - -默认情况下各节点服务器会在日志中输出标准错误，如果启动的时候通过 `--log-file` 参数指定了日志文件，那么日志会输出到指定的文件中，并且按天做 rotation。 - -#### 3.1.7 如何规范停止 TiDB？ - -如果是用 Ansible 部署的，可以使用 `ansible-playbook stop.yml` 命令停止 TiDB 集群。如果不是 Ansible 部署的，可以直接 kill 掉所有服务。如果使用 kill 命令，TiDB 的组件会做 graceful 的 shutdown。 - -#### 3.1.8 TiDB 里面可以执行 kill 命令吗？ - -- 可以 kill DML 语句，首先使用 `show processlist`，找到对应 session 的 id，然后执行 `kill tidb [session id]`。 -- 可以 kill DDL 语句，首先使用 `admin show ddl jobs`，查找需要 kill 的 DDL job ID，然后执行 `admin cancel ddl jobs 'job_id' [, 'job_id'] ...`。具体可以参考 [admin 操作](/v2.1/reference/sql/statements/admin.md)。 - -#### 3.1.9 TiDB 是否支持会话超时？ - -TiDB 暂不支持数据库层面的会话超时，目前想要实现超时，在没 LB（Load Balancing）的时候，需要应用侧记录发起的 Session 的 ID，通过应用自定义超时，超时以后需要到发起 Query 的节点上用 `kill tidb [session id]` 来杀掉 SQL。目前建议使用应用程序来实现会话超时，当达到超时时间，应用层就会抛出异常继续执行后续的程序段。 - -#### 3.1.10 TiDB 生产环境的版本管理策略是怎么样的？如何尽可能避免频繁升级？ - -TiDB 版本目前逐步标准化，每次 Release 都包含详细的 Change log，版本功能[变化详情](https://github.com/pingcap/TiDB/releases)，生产环境是否有必要升级取决于业务系统，建议升级之前详细了解前后版本的功能差异。 - -版本号说明参考：Release Version: `v1.0.3-1-ga80e796` - -- `v1.0.3` 表示 GA 标准版 -- `1` 表示该版本 commit 1 次 -- `ga80e796` 代表版本的 `git-hash` - -#### 3.1.11 分不清 TiDB master 版本之间的区别，经常用错 TiDB Ansible 版本? - -TiDB 目前社区非常活跃，在 1.0 GA 版本发布后，还在不断的优化和修改 BUG，因此 TiDB 的版本更新周期比较快，会不定期有新版本发布，请关注我们的[新版本发布官方网站](https://pingcap.com/weekly/)。此外 TiDB 安装推荐使用 TiDB Ansible 进行安装，TiDB Ansible 的版本也会随着 TiDB 的版本发布进行更新，因此建议用户在安装升级新版本的时候使用最新的 TiDB Ansible 安装包版本进行安装。此外，在 TiDB 1.0 GA 版本后，对 TiDB 的版本号进行了统一管理，TiDB 的版本可以通过以下两种方式进行查看： - -- 通过 `select tidb_version()` 进行查看 -- 通过执行 `tidb-server -V` 进行查看 - -#### 3.1.12 有没有图形化部署 TiDB 的工具？ - -暂时没有。 - -#### 3.1.13 TiDB 如何进行水平扩展？ - -当您的业务不断增长时，数据库可能会面临三方面瓶颈，第一是存储空间，第二是计算资源，第三是读写容量，这时可以对 TiDB 集群做水平扩展。 - -- 如果是存储资源不够，可以通过添加 TiKV Server 节点来解决，新节点启动后，PD 会自动将其他节点的部分数据迁移过去，无需人工介入。 -- 如果是计算资源不够，可以查看 TiDB Server 和 TiKV Server 节点的 CPU 消耗情况，再考虑添加 TiDB Server 节点或者是 TiKV Server 节点来解决，如添加 TiDB Server 节点，将其添加到前端 Load Balancer 配置之中即可。 -- 如果是容量跟不上，一般可以考虑同时增加 TiDB Server 和 TiKV Server 节点。 - -#### 3.1.14 Percolator 用了分布式锁，crash 的客户端会保持锁，会造成锁没有 release？ - -详细可参考 [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/)。 - -#### 3.1.15 TiDB 为什么选用 gRPC 而不选用 Thrift，是因为 Google 在用吗？ - -不只是因为 Google 在用，有一些比较好的特性我们需要，比如流控、加密还有 Streaming。 - -#### 3.1.16 like(bindo.customers.name, jason%, 92) 这个92代表什么？ - -那个是转义字符，默认是 (ASCII 92)。 - -#### 3.1.17 为什么 `information_schema.tables.data_length` 记录的大小和 TiKV 监控面板上的 store size 不一样？ - -这是因为两者计算的角度不一样。`information_schema.tables.data_length` 是通过统计信息（平均每行的大小）得到的估算值。TiKV 监控面板上的 store size 是单个 TiKV 实例的数据文件（RocksDB 的 SST 文件）的大小总和。由于多版本和 TiKV 会压缩数据，所以两者显示的大小不一样。 - -### 3.2 PD 管理 - -#### 3.2.1 访问 PD 报错：TiKV cluster is not bootstrapped - -PD 的大部分 API 需要在初始化 TiKV 集群以后才能使用，如果在部署新集群的时候只启动了 PD，还没有启动 TiKV，这时候访问 PD 就会报这个错误。遇到这个错误应该先把要部署的 TiKV 启动起来，TiKV 会自动完成初始化工作，然后就可以正常访问 PD。 - -#### 3.2.2 PD 启动报错：etcd cluster ID mismatch - -PD 启动参数中的 `--initial-cluster` 包含了某个不属于该集群的成员。遇到这个错误时请检查各个成员的所属集群，剔除错误的成员后即可正常启动。 - -#### 3.2.3 PD 能容忍的时间同步误差是多少？ - -理论上，时间同步误差越小越好。PD 可容忍任意时长的误差，但是，时间同步误差越大意味着 PD 分配的时间戳与真实的物理时间相差越大，这个差距会影响读历史版本等功能。 - -#### 3.2.4 Client 连接是如何寻找 PD 的？ - -Client 连接只能通过 TiDB 访问集群，TiDB 负责连接 PD 与 TiKV，PD 与 TiKV 对 Client 透明。当 TiDB 连接任意一台 PD 的时候，PD 会告知 TiDB 当前的 leader 是谁，如果此台 PD 不是 leader，TiDB 将会重新连接至 leader PD。 - -#### 3.2.5 PD 参数中 leader-schedule-limit 和 region-schedule-limit 调度有什么区别？ - -- leader-schedule-limit 调度是用来均衡不同 TiKV 的 leader 数，影响处理查询的负载。 -- region-schedule-limit 调度是均衡不同 TiKV 的副本数，影响不同节点的数据量。 - -#### 3.2.6 每个 region 的 replica 数量可配置吗？调整的方法是？ - -可以，目前只能调整全局的 replica 数量。首次启动时 PD 会读配置文件（conf/pd.yml），使用其中的 max-replicas 配置，之后修改需要使用 pd-ctl 配置命令 `config set max-replicas $num`，配置后可通过 `config show all` 来查看已生效的配置。调整的时候，不会影响业务，会在后台添加，注意总 TiKV 实例数总是要大于等于设置的副本数，例如 3 副本需要至少 3 个 TiKV。增加副本数量之前需要预估额外的存储需求。pd-ctl 的详细用法可参考 [PD Control 使用说明](/v2.1/reference/tools/pd-control.md)。 - -#### 3.2.7 缺少命令行集群管理工具，整个集群的健康度当前是否正常，不好确认？ - -可以通过 pd-ctl 等工具来判断集群大概的状态，详细的集群状态还是需要通过监控来确认。 - -#### 3.2.8 集群下线节点后，怎么删除老集群节点监控信息？ - -下线节点一般指 TiKV 节点通过 pd-ctl 或者监控判断节点是否下线完成。节点下线完成后，手动停止下线节点上相关的服务。从 Prometheus 配置文件中删除对应节点的 node_exporter 信息。从 Ansible inventory.ini 中删除对应节点的信息。 - -#### 3.2.9 使用 PD Control 连接 PD Server 时，为什么只能通过本机 IP 连接，不能通过 127.0.0.1 连接？ - -因为使用 TiDB Ansible 部署的集群，PD 对外服务端口不会绑定到 127.0.0.1，所以 PD Control 不会识别 127.0.0.1。 - -### 3.3 TiDB server 管理 - -#### 3.3.1 TiDB 的 lease 参数应该如何设置？ - -启动 TiDB Server 时，需要通过命令行参数设置 lease 参数（--lease=60），其值会影响 DDL 的速度（只会影响当前执行 DDL 的 session，其他的 session 不会受影响）。在测试阶段，lease 的值可以设为 1s，加快测试进度；在生产环境下，我们推荐这个值设为分钟级（一般可以设为 60），这样可以保证 DDL 操作的安全。 - -#### 3.3.2 DDL 在正常情况下的耗时是多少？ - -一般情况下处理一个 DDL 操作（之前没有其他 DDL 操作在处理）的耗时基本可以分如下为三种： - -- add index 操作，且此操作对应表数据行数比较少，耗时约为 3s。 -- add index 操作，且此操作对应表数据行数比较多，耗时具体由表中数据行数和当时 QPS 情况定（add index 操作优先级比一般 SQL 低）。 -- 其他 DDL 操作耗时约为 1s。 - -此外，如果接收 DDL 请求的 TiDB 和 DDL owner 所处的 TiDB 是一台，那么上面列举的第一和第三种可能的耗时应该在几十到几百毫秒。 - -#### 3.3.3 为什么有的时候执行 DDL 会很慢？ - -可能原因如下： - -- 多个 DDL 语句一起执行的时候，后面的几个 DDL 语句会比较慢。原因是当前 TiDB 集群中 DDL 操作是串行执行的。 -- 在正常集群启动后，第一个 DDL 操作的执行时间可能会比较久，一般在 30s 左右，这个原因是刚启动时 TiDB 在竞选处理 DDL 的 leader。 -- 由于停 TiDB 时不能与 PD 正常通信（包括停电情况）或者用 `kill -9` 指令停 TiDB 导致 TiDB 没有及时从 PD 清理注册数据，那么会影响 TiDB 启动后 10min 内的 DDL 语句处理时间。这段时间内运行 DDL 语句时，每个 DDL 状态变化都需要等待 2 * lease（默认 lease = 45s）。 -- 当集群中某个 TiDB 与 PD 之间发生通信问题，即 TiDB 不能从 PD 及时获取或更新版本信息，那么这时候 DDL 操作的每个状态处理需要等待 2 * lease。 - -#### 3.3.4 TiDB 可以使用 S3 作为后端存储吗？ - -不可以，目前 TiDB 只支持分布式存储引擎和 GolevelDB/RocksDB/BoltDB 引擎。 - -#### 3.3.5 Information_schema 能否支持更多真实信息？ - -Information_schema 库里面的表主要是为了兼容 MySQL 而存在，有些第三方软件会查询里面的信息。在目前 TiDB 的实现中，里面大部分只是一些空表。后续随着 TiDB 的升级，会提供更多的参数信息。当前 TiDB 支持的 Information\_schema 请参考 [TiDB 系统数据库说明文档](/v2.1/reference/system-databases/information-schema.md)。 - -#### 3.3.6 TiDB Backoff type 主要原因? - -TiDB-server 与 TiKV-server 随时进行通信，在进行大量数据操作过程中，会出现 `Server is busy` 或者 `backoff.maxsleep 20000ms` 的日志提示信息，这是由于 TiKV-server 在处理过程中系统比较忙而出现的提示信息，通常这时候可以通过系统资源监控到 TiKV 主机系统资源使用率比较高的情况出现。如果这种情况出现，可以根据资源使用情况进行相应的扩容操作。 - -#### 3.3.7 TiDB TiClient type 主要原因？ - -TiClient Region Error 该指标描述的是在 TiDB-server 作为客户端通过 KV 接口访问 TiKV-server 进行数据操作过程中，TiDB-server 操作 TiKV-server 中的 Region 数据出现的错误类型与 metric 指标，错误类型包括 not_leader、stale_epoch。出现这些错误的情况是当 TiDB-server 根据自己的缓存信息去操作 Region leader 数据的时候，Region leader 发生了迁移或者 TiKV 当前的 Region 信息与 TiDB 缓存的路由信息不一致而出现的错误提示。一般这种情况下，TiDB-server 都会自动重新从 PD 获取最新的路由数据，重做之前的操作。 - -#### 3.3.8 TiDB 同时支持的最大并发连接数？ - -当前版本 TiDB 没有最大连接数的限制，如果并发过大导致响应时间增加，可以通过增加 TiDB 节点进行扩容。 - -#### 3.3.9 如何查看某张表创建的时间？ - -information_schema 库中的 tables 表里的 create_time 即为表的真实创建时间。 - -#### 3.3.9 TiDB 的日志中 EXPENSIVE_QUERY 是什么意思？ - -TiDB 在执行 SQL 时，预估出来每个 operator 处理了超过 10000 条数据就认为这条 query 是 expensive query。可以通过修改 tidb-server 配置参数来对这个门限值进行调整，调整后需要重新启动 tidb-server。 - -#### 3.3.10 在 TiDB 中如何控制或改变 SQL 提交的执行优先级？ - -TiDB 支持改变 [per-session](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_force_priority)、[全局](/v2.1/reference/configuration/tidb-server/configuration-file.md#force-priority)或单个语句的优先级。优先级包括： - -- HIGH_PRIORITY：该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句 -- LOW_PRIORITY：该语句为低优先级语句，TiDB 在执行阶段会降低这条语句的优先级 - -以上两种参数可以结合 TiDB 的 DML 语言进行使用，使用方法举例如下： - -1. 通过在数据库中写 SQL 的方式来调整优先级： - - ```sql - select HIGH_PRIORITY | LOW_PRIORITY count(*) from table_name; - insert HIGH_PRIORITY | LOW_PRIORITY into table_name insert_values; - delete HIGH_PRIORITY | LOW_PRIORITY from table_name; - update HIGH_PRIORITY | LOW_PRIORITY table_reference set assignment_list where where_condition; - replace HIGH_PRIORITY | LOW_PRIORITY into table_name; - ``` - -2. 全表扫会自动调整为低优先级，analyze 也是默认低优先级。 - -#### 3.3.11 在 TiDB 中 auto analyze 的触发策略是怎样的？ - -触发策略：新表达到 1000 条，并且在 1 分钟内没有写入，会自动触发。 - -当表的（修改数/当前总行数）大于 `tidb_auto_analyze_ratio` 的时候，会自动触发 `analyze` 语句。`tidb_auto_analyze_ratio` 的默认值为 0.5，即默认开启此功能。为了保险起见，在开启此功能的时候，保证了其最小值为 0.3。但是不能大于等于 `pseudo-estimate-ratio`（默认值为 0.8），否则会有一段时间使用 pseudo 统计信息，建议设置值为 0.5。 - -#### 3.3.12 SQL 中如何通过 hint 使用一个具体的 index？ - -同 MySQL 的用法一致，例如： -`select column_name from table_name use index（index_name）where where_condition;` - -#### 3.3.13 触发 Information schema is changed 错误的原因？ - -TiDB 在执行 SQL 语句时，会使用当时的 `schema` 来处理该 SQL 语句，而且 TiDB 支持在线异步变更 DDL。那么，在执行 DML 的时候可能有 DDL 语句也在执行，而你需要确保每个 SQL 语句在同一个 `schema` 上执行。所以当执行 DML 时，遇到正在执行中的 DDL 操作就可能会报 `Information schema is changed` 的错误。为了避免太多的 DML 语句报错，已做了一些优化。 - -现在会报此错的可能原因如下（后两个报错原因与表无关）： - -- 执行的 DML 语句中涉及的表和集群中正在执行的 DDL 的表有相同的，那么这个 DML 语句就会报此错。 -- 这个 DML 执行时间很久，而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 1024（v2.1.18 版本之前此值为定值 100。v2.1.18 及之后版本默认值为 1024，可以通过 `tidb_max_delta_schema_count` 变量修改）。 -- 接受 DML 请求的 TiDB 长时间不能加载到 `schema information`（TiDB 与 PD 或 TiKV 之间的网络连接故障等会导致此问题），而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 100。 - -> **注意：** -> -> + 目前 TiDB 未缓存所有的 `schema` 版本信息。 -> + 对于每个 DDL 操作，`schema` 版本变更的数量与对应 `schema state` 变更的次数一致。 -> + 不同的 DDL 操作版本变更次数不一样。例如，`create table` 操作会有 1 次 `schema` 版本变更；`add column` 操作有 4 次 `schema` 版本变更。 - -#### 3.3.14 触发 Information schema is out of date 错误的原因？ - -当执行 DML 时，TiDB 超过一个 DDL lease 时间（默认 45s）没能加载到最新的 schema 就可能会报 `Information schema is out of date` 的错误。遇到此错的可能原因如下： - -- 执行此 DML 的 TiDB 被 kill 后准备退出，且此 DML 对应的事务执行时间超过一个 DDL lease，在事务提交时会报这个错误。 -- TiDB 在执行此 DML 时，有一段时间内连不上 PD 或者 TiKV，导致 TiDB 超过一个 DDL lease 时间没有 load schema，或者导致 TiDB 断开与 PD 之间带 keep alive 设置的连接。 - -#### 3.3.15 高并发情况下执行 DDL 时报错的原因？ - -高并发情况下执行 DDL（比如批量建表）时，极少部分 DDL 可能会由于并发执行时 key 冲突而执行失败。 - -并发执行 DDL 时，建议将 DDL 数量保持在 20 以下，否则你需要在应用端重试失败的 DDL 语句。 - -### 3.4 TiKV 管理 - -#### 3.4.1 TiKV 集群副本建议配置数量是多少，是不是最小高可用配置（3个）最好？ - -如果是测试环境 3 副本足够；在生产环境中，不可让集群副本数低于 3，需根据架构特点、业务系统及恢复能力的需求，适当增加副本数。值得注意的是，副本升高，性能会有下降，但是安全性更高。 - -#### 3.4.2 TiKV 启动报错：cluster ID mismatch - -TiKV 本地存储的 cluster ID 和指定的 PD 的 cluster ID 不一致。在部署新的 PD 集群的时候，PD 会随机生成一个 cluster ID，TiKV 第一次初始化的时候会从 PD 获取 cluster ID 存储在本地，下次启动的时候会检查本地的 cluster ID 与 PD 的 cluster ID 是否一致，如果不一致则会报错并退出。出现这个错误一个常见的原因是，用户原先部署了一个集群，后来把 PD 的数据删除了并且重新部署了新的 PD，但是 TiKV 还是使用旧的数据重启连到新的 PD 上，就会报这个错误。 - -#### 3.4.3 TiKV 启动报错：duplicated store address - -启动参数中的地址已经被其他的 TiKV 注册在 PD 集群中了。造成该错误的常见情况：TiKV `--data-dir` 指定的路径下没有数据文件夹（删除或移动后没有更新 --data-dir），用之前参数重新启动该 TiKV。请尝试用 pd-ctl 的 [store delete](https://github.com/pingcap/pd/tree/55db505e8f35e8ab4e00efd202beb27a8ecc40fb/tools/pd-ctl#store-delete--label--weight-store_id----jqquery-string) 功能，删除之前的 store，然后重新启动 TiKV 即可。 - -#### 3.4.4 TiKV master 和 slave 用的是一样的压缩算法，为什么效果不一样? - -目前来看 master 有些文件的压缩率会高一些，这个取决于底层数据的分布和 RocksDB 的实现，数据大小偶尔有些波动是正常的，底层存储引擎会根据需要调整数据。 - -#### 3.4.5 TiKV block cache 有哪些特性？ - -TiKV 使用了 RocksDB 的 Column Family (CF) 特性，KV 数据最终存储在默认 RocksDB 内部的 default、write、lock 3 个 CF 内。 - -- default CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中。 -- write CF 存储的是数据的版本信息（MVCC）、索引、小表相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中。 -- lock CF 存储的是锁信息，系统使用默认参数。 -- Raft RocksDB 实例存储 Raft log。default CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 -- 每个 CF 都有单独的 Block-cache，用于缓存数据块，加速 RocksDB 的读取速度，Block-cache 的大小通过参数 `block-cache-size` 控制，`block-cache-size` 越大，能够缓存的热点数据越多，对读取操作越有利，同时占用的系统内存也会越多。 -- 每个 CF 有各自的 Write-buffer，大小通过 `write-buffer-size` 控制。 - -#### 3.4.6 TiKV channel full 是什么原因？ - -- Raftstore 线程太忙，或者因 I/O 而卡住。可以看一下 Raftstore 的 CPU 使用情况。 -- TiKV 过忙（CPU、磁盘 I/O 等），请求处理不过来。 - -#### 3.4.7 TiKV 频繁切换 Region leader 是什么原因？ - -- 网络问题导致节点间通信卡了，查看 Report failures 监控。 -- 原主 Leader 的节点卡了，导致没有及时给 Follower 发送消息。 -- Raftstore 线程卡了。 - -#### 3.4.8 如果一个节点挂了会影响服务吗？影响会持续多久？ - -TiDB 使用 Raft 在多个副本之间做数据同步（默认为每个 Region 3 个副本）。当一份备份出现问题时，其他的副本能保证数据的安全。根据 Raft 协议，当某个节点挂掉导致该节点里的 Leader 失效时，在最大 2 * lease time（leasetime 是 10 秒）时间后，通过 Raft 协议会很快将一个另外一个节点里的 Follower 选为新的 Region Leader 来提供服务。 - -#### 3.4.9 TiKV 在分别在那些场景下占用大量 IO、内存、CPU（超过参数配置的多倍）？ - -在大量写入、读取的场景中会占用大量的磁盘 IO、内存、CPU。在执行很复杂的查询，比如会产生很大中间结果集的情况下，会消耗很多的内存和 CPU 资源。 - -#### 3.4.10 TiKV 是否可以使用 SAS/SATA 盘或者进行 SSD/SAS 混合部署？ - -不可以使用，TiDB 在进行 OLTP 场景中，数据访问和操作需要高 IO 磁盘的支持，TiDB 作为强一致的分布式数据库，存在一定的写放大，如副本复制、存储底层 Compaction，因此，TiDB 部署的最佳实践中推荐用户使用 NVMe SSD 磁盘作为数据存储磁盘。另外，TiKV 与 PD 不能混合部署。 - -#### 3.4.11 数据表 Key 的 Range 范围划分是在数据接入之前就已经划分好了吗？ - -不是的，这个和 MySQL 分表规则不一样，需要提前设置好，TiKV 是根据 Region 的大小动态分裂的。 - -#### 3.4.12 Region 是如何进行分裂的？ - -Region 不是前期划分好的，但确实有 Region 分裂机制。当 Region 的大小超过参数 `region-max-size` 或 `region-max-keys` 的值时，就会触发分裂，分裂后的信息会汇报给 PD。 - -#### 3.4.13 TiKV 是否有类似 MySQL 的 `innodb_flush_log_trx_commit` 参数，来保证提交数据不丢失？ - -是的，TiKV 单机的存储引擎目前使用两个 RocksDB 实例，其中一个存储 raft-log，TiKV 有个 sync-log 参数，在 ture 的情况下，每次提交都会强制刷盘到 raft-log，如果发生 crash 后，通过 raft-log 进行 KV 数据的恢复。 - -#### 3.4.14 对 WAL 存储有什么推荐的硬件配置，例如 SSD，RAID 级别，RAID 卡 cache 策略，NUMA 设置，文件系统选择，操作系统的 IO 调度策略等？ - -WAL 属于顺序写，目前我们并没有单独对他进行配置，建议 SSD，RAID 如果允许的话，最好是 RAID 10，RAID 卡 cache、操作系统 I/O 调度目前没有针对性的最佳实践，Linux 7 以上默认配置即可，NUMA 没有特别建议，NUMA 内存分配策略可以尝试使用 `interleave = all`，文件系统建议 ext4。 - -#### 3.4.15 在最严格的 `sync-log = true` 数据可用模式下，写入性能如何？ - -一般来说，开启 `sync-log` 会让性能损耗 30% 左右。关闭 `sync-log` 时的性能表现，请参见 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/v2.1/benchmark/sysbench-v3.md)。 - -#### 3.4.16 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠，单机存储引擎是否需要最严格模式？ - -通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。但理论上两个节点也可能同时发生故障，所以除非是对性能要求高于数据安全的场景，一般都强烈推荐开启 `sync-log`。 - -另外，还有一种 `sync-log` 的替代方案，即在 Raft group 中用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 - -对于单机存储引擎也同样推荐打开 `sync-log` 模式。否则如果节点宕机可能会丢失最后一次写入数据。 - -#### 3.4.17 使用 Raft 协议，数据写入会有多次网络的 roundtrip，实际写入延迟如何？ - -理论上，和单机数据库相比，数据写入会多四个网络延迟。 - -#### 3.4.18 有没有类似 MySQL 的 InnoDB Memcached plugin，可以直接使用 KV 接口，可以不需要独立的 Cache？ - -TiKV 支持单独进行接口调用，理论上也可以起个实例做为 Cache，但 TiDB 最大的价值是分布式关系型数据库，我们原则上不对 TiKV 单独进行支持。 - -#### 3.4.19 Coprocessor 组件的主要作用？ - -- 减少 TiDB 与 TiKV 之间的数据传输。 -- 计算下推，充分利用 TiKV 的分布式计算资源。 - -#### 3.4.20 IO error: No space left on device While appending to file - -这是磁盘空间不足导致的，需要加节点或者扩大磁盘空间。 - -#### 3.4.21 为什么 TiKV 容易出现 OOM？ - -TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总内存的 40%。当 TiKV 容易出现 OOM 时，检查 `block-cache-size` 配置是否过高。还需要注意，当单机部署了多个 TiKV 实例时，需要显式地配置该参数，以防止多个实例占用过多系统内存导致 OOM。 - -#### 3.4.22 TiDB 数据和 RawKV 数据可存储于同一个 TiKV 集群里吗？ - -不可以。TiDB 数据（或使用其他事务 API 生成的数据）依赖于一种特殊的键值格式，和 RawKV API 数据（或其他基于 RawKV 的服务生成的数据）并不兼容。 - -### 3.5 TiDB 测试 - -#### 3.5.1 TiDB Sysbench 基准测试结果如何？ - -很多用户在接触 TiDB 都习惯做一个基准测试或者 TiDB 与 MySQL 的对比测试，官方也做了一个类似测试，汇总很多测试结果后，我们发现虽然测试的数据有一定的偏差，但结论或者方向基本一致，由于 TiDB 与 MySQL 由于架构上的差别非常大，很多方面是很难找到一个基准点，所以官方的建议两点： - -- 大家不要用过多精力纠结这类基准测试上，应该更多关注 TiDB 的场景上的区别。 -- 大家可以直接参考 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/v2.1/benchmark/sysbench-v3.md)。 - -#### 3.5.2 TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？ - -- 在 10 节点内，TiDB 写入能力（Insert TPS）和节点数量基本成 40% 线性递增，MySQL 由于是单节点写入，所以不具备写入扩展能力。 -- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://t.cn/RTD18qV)。 -- TiDB 不管是读流量、还是写流量都可以通过添加节点快速方便的进行扩展。 - -#### 3.5.3 我们的 DBA 测试过 MySQL 性能，单台 TiDB 的性能没有 MySQL 性能那么好？ - -TiDB 设计的目标就是针对 MySQL 单台容量限制而被迫做的分库分表的场景，或者需要强一致性和完整分布式事务的场景。它的优势是通过尽量下推到存储节点进行并行计算。对于小表（比如千万级以下），不适合 TiDB，因为数据量少，Region 有限，发挥不了并行的优势，最极端的就是计数器表，几行记录高频更新，这几行在 TiDB 里，会变成存储引擎上的几个 KV，然后只落在一个 Region 里，而这个 Region 只落在一个节点上。加上后台强一致性复制的开销，TiDB 引擎到 TiKV 引擎的开销，最后表现出来的就是没有单个 MySQL 好。 - -### 3.6 TiDB 备份恢复 - -#### 3.6.1 TiDB 主要备份方式？ - -目前，推荐的备份方式是使用 [PingCAP fork 的 Mydumper](/v2.1/reference/tools/mydumper.md)。尽管 TiDB 也支持使用 MySQL 官方工具 `mysqldump` 进行数据备份、恢复，但其性能低于 [`mydumper`](/v2.1/reference/tools/mydumper.md)/[`loader`](/v2.1/reference/tools/loader.md)，并且该工具备份、恢复大量数量时，要耗费更多时间。 - -使用 Mydumper 导出来的数据文件尽可能的小, 最好不要超过 64M, 可以设置参数 -F 64； - -loader 的 -t 参数可以根据 TiKV 的实例个数以及负载进行评估调整，例如 3 个 TiKV 的场景， 此值可以设为 3 * (1 ～ n)，当 TiKV 负载过高，loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 可以适当调小该值，当 TiKV 负载不是太高的时候，可以适当调大该值。 - -## 四、数据、流量迁移 - -### 4.1 全量数据导出导入 - -#### 4.1.1 Mydumper - -参见 [Mydumper 使用文档](/v2.1/reference/tools/mydumper.md)。 - -#### 4.1.2 Loader - -参见 [Loader 使用文档](/v2.1/reference/tools/loader.md)。 - -#### 4.1.3 如何将一个运行在 MySQL 上的应用迁移到 TiDB 上？ - -TiDB 支持绝大多数 MySQL 语法，一般不需要修改代码。 - -#### 4.1.4 不小心把 MySQL 的 user 表导入到 TiDB 了，或者忘记密码，无法登录，如何处理？ - -重启 TiDB 服务，配置文件中增加 `-skip-grant-table=true` 参数，无密码登录集群后，可以根据情况重建用户，或者重建 mysql.user 表，具体表结构搜索官网。 - -#### 4.1.5 在 Loader 运行的过程中，TiDB 可以对外提供服务吗？ - -该操作进行逻辑插入，TiDB 仍可对外提供服务，但不要执行相关 DDL 操作。 - -#### 4.1.6 如何导出 TiDB 数据？ - -TiDB 目前暂时不支持 `select into outfile`，可以通过以下方式导出 TiDB 数据：参考 [MySQL 使用 mysqldump 导出某个表的部分数据](https://blog.csdn.net/xin_yu_xin/article/details/7574662)，使用 mysqldump 加 where 条件导出，使用 MySQL client 将 select 的结果输出到一个文件。 - -#### 4.1.7 如何从 DB2、Oracle 数据库迁移到 TiDB？ - -DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： - -- 使用 Oracle 官方迁移工具，如 OGG、Gateway（透明网关）、CDC（Change Data Capture）。 -- 自研数据导出导入程序实现。 -- 导出（Spool）成文本文件，然后通过 Load infile 进行导入。 -- 使用第三方数据迁移工具。 - -目前看来 OGG 最为合适。 - -#### 4.1.8 用 Sqoop 批量写入 TiDB 数据，虽然配置了 `--batch` 选项，但还是会遇到 `java.sql.BatchUpdateExecption:statement count 5001 exceeds the transaction limitation` 的错误，该如何解决？ - -- 在 Sqoop 中，`--batch` 是指每个批次提交 100 条 statement，但是默认每个 statement 包含 100 条 SQL 语句，所以此时 100 * 100 = 10000 条 SQL 语句，超出了 TiDB 的事务限制 5000 条，可以增加选项 `-Dsqoop.export.records.per.statement=10` 来解决这个问题，完整的用法如下： - -```bash -sqoop export \ - -Dsqoop.export.records.per.statement=10 \ - --connect jdbc:mysql://mysql.example.com/sqoop \ - --username sqoop ${user} \ - --password ${passwd} \ - --table ${tab_name} \ - --export-dir ${dir} \ - --batch -``` - -- 也可以选择增大 tidb 的单个事物语句数量限制，不过这个会导致内存上涨。 - -#### 4.1.9 TiDB 有像 Oracle 那样的 Flashback Query 功能么，DDL 支持么？ - -有，也支持 DDL。详细参考 [TiDB 历史数据回溯](/v2.1/how-to/get-started/read-historical-data.md)。 - -### 4.2 在线数据同步 - -#### 4.2.1 Syncer 架构 - -详细参考 [解析 TiDB 在线数据同步工具 Syncer](https://pingcap.com/blog-cn/tidb-syncer/)。 - -##### 4.2.1.1 Syncer 使用文档 - -详细参考 [Syncer 使用文档](/v2.1/reference/tools/syncer.md)。 - -##### 4.2.1.2 如何配置监控 Syncer 运行情况？ - -下载 [Syncer Json](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json) 导入到 Grafana，修改 Prometheus 配置文件，添加以下内容： - -- job_name: 'syncer_ops' // 任务名字 - static_configs: -- targets: ['10.10.1.1:10096'] // Syncer 监听地址与端口，通知 prometheus 拉取 Syncer 的数据。 - -重启 Prometheus 即可。 - -##### 4.2.1.3 有没有现成的同步方案，可以将数据同步到 Hbase、Elasticsearh 等其他存储？ - -没有，目前依赖程序自行实现。 - -##### 4.2.1.4 利用 Syncer 做数据同步的时候是否支持只同步部分表？ - -支持，具体参考 Syncer 使用手册 [Syncer 使用文档](/v2.1/reference/tools/syncer.md) - -##### 4.2.1.5 频繁的执行 DDL 会影响 Syncer 同步速度吗？ - -频繁执行 DDL 对同步速度会有影响。对于 Sycner 来说，DDL 是串行执行的，当同步遇到了 DDL，就会以串行的方式执行，所以这种场景就会导致同步速度下降。 - -##### 4.2.1.6 使用 Syncer gtid 的方式同步时，同步过程中会不断更新 syncer.meta 文件，如果 Syncer 所在的机器坏了，导致 syncer.meta 文件所在的目录丢失，该如何处理？ - -当前 Syncer 版本的没有进行高可用设计，Syncer 目前的配置信息 syncer.meta 直接存储在硬盘上，其存储方式类似于其他 MySQL 生态工具，比如 Mydumper。因此，要解决这个问题当前可以有两个方法： - -1）把 syncer.meta 数据放到比较安全的磁盘上，例如磁盘做好 raid1； - -2）可以根据 Syncer 定期上报到 Prometheus 的监控信息来还原出历史同步的位置信息，该方法的位置信息在大量同步数据时由于延迟会可能不准确。 - -##### 4.2.1.7 Syncer 下游 TiDB 数据和 MySQL 数据不一致，DML 会退出么？ - -- 上游 MySQL 中存在数据，下游 TiDB 中该数据不存在，上游 MySQL 执行 `UPDATE` 或 `DELETE`（更新/删除）该条数据的操作时，Syncer 同步过程即不会报错退出也没有该条数据。 -- 下游有主键索引或是唯一索引冲突时，执行 `UPDATE` 会退出，执行 `INSERT` 不会退出。 - -### 4.3 业务流量迁入 - -#### 4.3.1 如何快速迁移业务流量？ - -我们建议通过 Syncer 工具搭建成多源 MySQL -> TiDB 实时同步环境，读写流量可以按照需求分阶段通过修改网络配置进行流量迁移，建议 DB 上层部署一个稳定的网络 LB（HAproxy、LVS、F5、DNS 等），这样直接修改网络配置就能实现无缝流量迁移。 - -#### 4.3.2 TiDB 总读写流量有限制吗？ - -TiDB 读流量可以通过增加 TiDB server 进行扩展，总读容量无限制，写流量可以通过增加 TiKV 节点进行扩容，基本上写容量也没有限制。 - -#### 4.3.3 Transaction too large 是什么原因，怎么解决？ - -由于分布式事务要做两阶段提交，并且底层还需要做 Raft 复制，如果一个事务非常大，会使得提交过程非常慢，并且会卡住下面的 Raft 复制流程。为了避免系统出现被卡住的情况，我们对事务的大小做了限制： - -- 单个事务包含的 SQL 语句不超过 5000 条（默认） -- 单条 KV entry 不超过 6MB -- KV entry 的总条数不超过 30w -- KV entry 的总大小不超过 100MB - -在 Google 的 Cloud Spanner 上面，也有类似的[限制](https://cloud.google.com/spanner/docs/limits)。 - -#### 4.3.4 如何批量导入？ - -导入数据的时候，可以分批插入，每批最好不要超过 1w 行。 - -#### 4.3.5 TiDB 中删除数据后会立即释放空间吗？ - -DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DROP 操作，在达到 TiDB 的 GC (garbage collection) 时间后（默认 10 分钟），TiDB 的 GC 机制会删除数据并释放空间。对于 DELETE 操作 TiDB 的 GC 机制会删除数据，但不会释放空间，而是当后续数据写入 RocksDB 且进行 compact 时对空间重新利用。 - -#### 4.3.6 Load 数据时可以对目标表执行 DDL 操作吗？ - -不可以，加载数据期间不能对目标表执行任何 DDL 操作，这会导致数据加载失败。 - -#### 4.3.7 TiDB 是否支持 replace into 语法？ - -支持，但是 load data 不支持 replace into 语法。 - -#### 4.3.8 数据删除后查询速度为何会变慢？ - -大量删除数据后，会有很多无用的 key 存在，影响查询效率。目前正在开发 Region Merge 功能，完善之后可以解决这个问题，具体看参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 - -#### 4.3.9 数据删除最高效最快的方式？ - -在删除大量数据的时候，建议使用 `Delete * from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -#### 4.3.10 TiDB 如何提高数据加载速度？ - -主要有两个方面： - -- 目前已开发分布式导入工具 [Lightning](/v2.1/reference/tools/tidb-lightning/overview.md)，需要注意的是数据导入过程中为了性能考虑，不会执行完整的事务流程，所以没办法保证导入过程中正在导入的数据的 ACID 约束，只能保证整个导入过程结束以后导入数据的 ACID 约束。因此适用场景主要为新数据的导入（比如新的表或者新的索引），或者是全量的备份恢复（先 Truncate 原表再导入）。 -- TiDB 的数据加载与磁盘以及整体集群状态相关，加载数据时应关注该主机的磁盘利用率，TiClient Error/Backoff/Thread CPU 等相关 metric，可以分析相应瓶颈。 - -#### 4.3.11 对数据做删除操作之后，空间回收比较慢，如何处理？ - -可以设置并行 GC，加快对空间的回收速度。默认并发为 1，最大可调整为 tikv 实例数量的 50%。可使用 `update mysql.tidb set VARIABLE_VALUE="3" where VARIABLE_NAME="tikv_gc_concurrency";` 命令来调整。 - -## 五、SQL 优化 - -### 5.1 TiDB 执行计划解读 - -详细解读 [理解 TiDB 执行计划](/v2.1/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.1 统计信息收集 - -详细解读 [统计信息](/v2.1/reference/performance/statistics.md)。 - -#### 5.1.2 Count 如何加速？ - -Count 就是暴力扫表，提高并发度能显著的提升速度，修改并发度可以参考 `tidb_distsql_scan_concurrency` 变量，但是也要看 CPU 和 I/O 资源。TiDB 每次查询都要访问 TiKV，在数据量小的情况下，MySQL 都在内存里，TiDB 还需要进行一次网络访问。 - -提升建议： - -- 建议提升硬件配置，可以参考[部署建议](/v2.1/how-to/deploy/hardware-recommendations.md)。 -- 提升并发度，默认是 10，可以提升到 50 试试，但是一般提升在 2-4 倍之间。 -- 测试大数据量的 count。 -- 调优 TiKV 配置，可以参考[性能调优](/v2.1/reference/performance/tune-tikv.md)。 - -#### 5.1.3 查看当前 DDL 的进度？ - -通过 `admin show ddl` 查看当前 job 进度。操作如下： - -```sql -tidb> admin show ddl\G; -*************************** 1. row *************************** - SCHEMA_VER: 140 - OWNER: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -RUNNING_JOBS: ID:121, Type:add index, State:running, SchemaState:write reorganization, SchemaID:1, TableID:118, RowCount:77312, ArgLen:0, start time: 2018-12-05 16:26:10.652 +0800 CST, Err:, ErrCount:0, SnapshotVersion:404749908941733890 - SELF_ID: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -``` - -从上面操作结果可知，当前正在处理的是 `add index` 操作。且从 `RUNNING_JOBS` 列的 `RowCount` 字段可以知道当前 `add index` 操作已经添加了 77312 行索引。 - -#### 5.1.4 如何查看 DDL job？ - -可以使用 `admin show ddl` 语句查看正在运行的 DDL 作业。 - -- `admin show ddl jobs`：用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 -- `admin show ddl job queries 'job_id' [, 'job_id'] ...`：用于显示 `job_id` 对应的 DDL 任务的原始 SQL 语句。此 `job_id` 只搜索正在执行中的任务以及 DDL 历史作业队列中的最近十条结果。 - -#### 5.1.5 TiDB 是否支持基于 COST 的优化（CBO），如果支持，实现到什么程度？ - -是的，TiDB 使用的基于成本的优化器（CBO），我们有一个小组单独会对代价模型、统计信息持续优化，除此之外，我们支持 hash join、soft merge 等关联算法。 - -#### 5.1.6 如何确定某张表是否需要做 analyze ？ - -可以通过 `show stats_healthy` 来查看 Healthy 字段，一般小于等于 60 的表需要做 analyze。 - -#### 5.1.7 SQL 的执行计划展开成了树，ID 的序号有什么规律吗？这棵树的执行顺序会是怎么样的？ - -ID 没什么规律，只要是唯一就行，不过生成的时候，是有一个计数器，生成一个 plan 就加一，执行的顺序和序号无关，整个执行计划是一颗树，执行时从根节点开始，不断地向上返回数据。执行计划的理解，请参考[理解 TiDB 执行计划](/v2.1/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.8 TiDB 执行计划中，task cop 在一个 root 下，这个是并行的么？ - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指被下推到 KV 端分布式执行的计算任务，root task 是指在 TiDB 端单点执行的计算任务。一般来讲 root task 的输入数据是来自于 cop task 的；但是 root task 在处理数据的时候，TiKV 上的 cop task 也可以同时处理数据，等待 TiDB 的 root task 拉取，所以从这个观点上来看，他们是并行的；但是存在数据上下游关系；在执行的过程中，某些时间段其实也是并行的，第一个 cop task 在处理 [100, 200] 的数据，第二个 cop task 在处理 [1, 100] 的数据。执行计划的理解，请参考[理解 TiDB 执行计划](/v2.1/reference/performance/understanding-the-query-execution-plan.md)。 - -## 六、数据库优化 - -### 6.1 TiDB - -#### 6.1.1 TiDB 参数及调整 - -详情参考 [TiDB 配置参数](/v2.1/reference/configuration/tidb-server/configuration.md)。 - -#### 6.1.2 如何打散热点 - -TiDB 中以 Region 分片来管理数据库，通常来讲，TiDB 的热点指的是 Region 的读写访问热点。而 TiDB 中对于 PK 非整数或没有 PK 的表，可以通过设置 `SHARD_ROW_ID_BITS` 来适度分解 Region 分片，以达到打散 Region 热点的效果。详情可参考官网 [TiDB 专用系统变量和语法](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)中 `SHARD_ROW_ID_BITS` 的介绍。 - -### 6.2 TiKV - -#### 6.2.1 TiKV 性能参数调优 - -详情参考 [TiKV 性能参数调优](/v2.1/reference/performance/tune-tikv.md)。 - -## 七、监控 - -### 7.1 Prometheus 监控框架 - -详细参考 [TiDB 监控框架概述](/v2.1/how-to/monitor/overview.md)。 - -### 7.2 监控指标解读 - -详细参考 [重要监控指标详解](/v2.1/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.1 目前的监控使用方式及主要监控指标，有没有更好看的监控？ - -TiDB 使用 Prometheus + Grafana 组成 TiDB 数据库系统的监控系统，用户在 Grafana 上通过 dashboard 可以监控到 TiDB 的各类运行指标，包括系统资源的监控指标，包括客户端连接与 SQL 运行的指标，包括内部通信和 Region 调度的指标，通过这些指标，可以让数据库管理员更好的了解到系统的运行状态，运行瓶颈等内容。在监控指标的过程中，我们按照 TiDB 不同的模块，分别列出了各个模块重要的指标项，一般用户只需要关注这些常见的指标项。具体指标请参见[官方文档](/v2.1/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.2 Prometheus 监控数据默认 15 天自动清除一次，可以自己设定成 2 个月或者手动删除吗？ - -可以的，在 Prometheus 启动的机器上，找到启动脚本，然后修改启动参数，然后重启 Prometheus 生效。 - -```config ---storage.tsdb.retention="60d" -``` - -#### 7.2.3 Region Health 监控项 - -TiDB-2.0 版本中，PD metric 监控页面中，对 Region 健康度进行了监控，其中 Region Health 监控项是对所有 Region 副本状况的一些统计。其中 miss 是缺副本，extra 是多副本。同时也增加了按 Label 统计的隔离级别，level-1 表示这些 Region 的副本在第一级 Label 下是物理隔离的，没有配置 location label 时所有 Region 都在 level-0。 - -#### 7.2.4 Statement Count 监控项中的 selectsimplefull 是什么意思？ - -代表全表扫，但是可能是很小的系统表。 - -#### 7.2.5 监控上的 QPS 和 Statement OPS 有什么区别？ - -QPS 会统计执行的所有 SQL 命令，包括 use database、load data、begin、commit、set、show、insert、select 等。 - -Statement OPS 只统计 select、update、insert 等业务相关的，所以 Statement OPS 的统计和业务比较相符。 - -## 八、Cloud TiDB - -### 8.1 腾讯云 - -#### 8.1.1 目前 Cloud TiDB 都有那些云厂商？ - -Cloud TiDB 目前已经在腾讯云、UCloud 上线，都是数据库一级入口，欢迎大家使用。 - -## 九、故障排除 - -### 9.1 TiDB 自定义报错汇总 - -#### 9.1.1 ERROR 8005 (HY000) : Write Conflict, txnStartTS is stale - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -#### 9.1.2 ERROR 9001 (HY000) : PD Server Timeout - -请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络。 - -#### 9.1.3 ERROR 9002 (HY000) : TiKV Server Timeout - -请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络。 - -#### 9.1.4 ERROR 9003 (HY000) : TiKV Server is Busy - -TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.5 ERROR 9004 (HY000) : Resolve Lock Timeout - -清理锁超时，当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码是否有锁争用。 - -#### 9.1.6 ERROR 9005 (HY000) : Region is unavailable - -访问的 Region 不可用，某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.7 ERROR 9006 (HY000) : GC life time is shorter than transaction duration - -`GC Life Time` 间隔时间过短，长事务本应读到的数据可能被清理了，可使用如下命令增加 `GC Life Time`： - -```sql -update mysql.tidb set variable_value='30m' where variable_name='tikv_gc_life_time'; -``` - -其中 30m 代表仅清理 30 分钟前的数据，这可能会额外占用一定的存储空间。 - -#### 9.1.8 ERROR 9007 (HY000) : Write Conflict - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -### 9.2 MySQL 原生报错汇总 - -#### 9.2.1 ERROR 2013 (HY000): Lost connection to MySQL server during query 问题的排查方法？ - -- log 中是否有 panic -- dmesg 中是否有 oom，命令：`dmesg -T | grep -i oom` -- 长时间没有访问，也会收到这个报错，一般是 tcp 超时导致的，tcp 长时间不用, 会被操作系统 kill。 - -#### 9.2.2 ERROR 1105 (HY000): other error: unknown error Wire Error(InvalidEnumValue(4004)) 是什么意思？ - -这类问题一般是 TiDB 和 TiKV 版本不匹配，在升级过程尽量一起升级，避免版本 mismatch。 - -#### 9.2.3 ERROR 1148 (42000): the used command is not allowed with this TiDB version 问题的处理方法？ - -这个问题是因为在执行 `LOAD DATA LOCAL` 语句的时候，MySQL 客户端不允许执行此语句（即 `local_infile` 选项为 0）。解决方法是在启动 MySQL 客户端时，用 `--local-infile=1` 选项。具体启动指令类似：`mysql --local-infile=1 -u root -h 127.0.0.1 -P 4000`。有些 MySQL 客户端需要设置而有些不需要设置，原因是不同版本的 MySQL 客户端对 `local-infile` 的默认值不同。 - -#### 9.2.4 ERROR 9001 (HY000): PD server timeout start timestamp may fall behind safe point - -这个报错一般是 TiDB 访问 PD 出了问题，TiDB 后台有个 worker 会不断地从 PD 查询 safepoint，如果超过 100s 查不成功就会报这个错。一般是因为 PD 磁盘操作过忙、反应过慢，或者 TiDB 和 PD 之间的网络有问题。TiDB 常见错误码请参考[错误码与故障诊断](/v2.1/reference/error-codes.md)。 - -### 9.3 TiDB 日志中的报错信息 - -#### 9.3.1 EOF - -当客户端或者 proxy 断开连接时，TiDB 不会立刻察觉连接已断开，而是等到开始往连接返回数据时，才发现连接已断开，此时日志会打印 EOF 错误。 diff --git a/v2.1/faq/upgrade.md b/v2.1/faq/upgrade.md deleted file mode 100644 index d74c9c5e3783..000000000000 --- a/v2.1/faq/upgrade.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: 升级后常见问题 -category: FAQ ---- - -# 升级后常见问题 - -本文列出了一些升级后可能会遇到的问题与解决办法。 - -## 执行 DDL 操作时遇到的字符集 (charset) 问题 - -TiDB 在 v2.1.0 以及之前版本（包括 v2.0 所有版本）中，默认字符集是 UTF8。从 v2.1.1 开始，默认字符集变更为 UTF8MB4。如果在 v2.1.0 及之前版本中，建表时显式指定了 table 的 charset 为 UTF8，那么升级到 v2.1.1 之后，执行 DDL 操作可能会失败。 - -要避免该问题，需注意以下两个要点： - -1. 在 v2.1.3 之前，TiDB 不支持修改 column 的 charset。所以，执行 DDL 操作时，新 column 的 charset 需要和旧 column 的 charset 保持一致。 - -2. 在 v2.1.3 之前，即使 column 的 charset 和 table 的 charset 不一样，`show create table` 也不会显示 column 的 charset，但可以通过 HTTP API 获取 table 的元信息来查看 column 的 charset，下文提供了示例。 - -### 问题 1：`unsupported modify column charset utf8mb4 not match origin utf8` - -- 升级前：v2.1.0 及之前版本 - - ```sql - tidb > create table t(a varchar(10)) charset=utf8; - Query OK, 0 rows affected - Time: 0.106s - tidb > show create table t - +-------+-------------------------------------------------------+ - | Table | Create Table | - +-------+-------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+-------------------------------------------------------+ - 1 row in set - Time: 0.006s - ``` - -- 升级后：v2.1.1、v2.1.2 会出现下面的问题，v2.1.3 以及之后版本不会出现下面的问题。 - - ```sql - tidb > alter table t change column a a varchar(20); - ERROR 1105 (HY000): unsupported modify column charset utf8mb4 not match origin utf8 - ``` - -解决方案：显式指定 column charset，保持和原来的 charset 一致即可。 - -```sql -alter table t change column a a varchar(22) character set utf8; -``` - -- 根据要点 1，此处如果不指定 column 的 charset，会用默认的 UTF8MB4，所以需要指定 column charset 保持和原来一致。 - -- 根据要点 2，用 HTTP API 获取 table 元信息，然后根据 column 名字和 Charset 关键字搜索即可找到 column 的 charset。 - - ```sh - ▶ curl "http://$IP:10080/schema/test/t" | python -m json.tool # 这里用了 python 的格式化 json的工具，也可以不加，此处只是为了方便注释。 - { - "ShardRowIDBits": 0, - "auto_inc_id": 0, - "charset": "utf8", # table 的 charset - "collate": "", - "cols": [ # 从这里开始列举 column 的相关信息 - { - ... - "id": 1, - "name": { - "L": "a", - "O": "a" # column 的名字 - }, - "offset": 0, - "origin_default": null, - "state": 5, - "type": { - "Charset": "utf8", # column a 的 charset - "Collate": "utf8_bin", - "Decimal": 0, - "Elems": null, - "Flag": 0, - "Flen": 10, - "Tp": 15 - } - } - ], - ... - } - ``` - -### 问题 2：`unsupported modify charset from utf8mb4 to utf8` - -- 升级前：v2.1.1，v2.1.2 - - ```sql - tidb > create table t(a varchar(10)) charset=utf8; - Query OK, 0 rows affected - Time: 0.109s - tidb > show create table t - +-------+-------------------------------------------------------+ - | Table | Create Table | - +-------+-------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+-------------------------------------------------------+ - ``` - - 上面 `show create table` 只显示出了 table 的 charset，但其实 column 的 charset 是 UTF8MB4，这可以通过 HTTP API 获取 schema 来确认。这是一个 bug，即此处建表时 column 的 charset 应该要和 table 保持一致为 UTF8，该问题在 v2.1.3 中已经修复。 - -- 升级后：v2.1.3 及之后版本 - - ```sql - tidb > show create table t - +-------+--------------------------------------------------------------------+ - | Table | Create Table | - +-------+--------------------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) CHARSET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+--------------------------------------------------------------------+ - 1 row in set - Time: 0.007s - tidb > alter table t change column a a varchar(20); - ERROR 1105 (HY000): unsupported modify charset from utf8mb4 to utf8 - ``` - -解决方案： - -- 因为在 v2.1.3 之后，TiDB 支持修改 column 和 table 的 charset，所以这里推荐修改 table 的 charset 为 UTF8MB4。 - - ```sql - alter table t convert to character set utf8mb4; - ``` - -- 也可以像问题 1 一样指定 column 的 charset，保持和 column 原来的 charset (UTF8MB4) 一致即可。 - - ```sql - alter table t change column a a varchar(20) character set utf8mb4; - ``` - -### 问题 3：`ERROR 1366 (HY000): incorrect utf8 value f09f8c80(🌀) for column a` - -TiDB 在 v2.1.1 及之前版本中，如果 charset 是 UTF8，没有对 4-byte 的插入数据进行 UTF8 Unicode encoding 检查。在v2.1.2 及之后版本中，添加了该检查。 - -- 升级前：v2.1.1 及之前版本 - - ```sql - tidb> create table t(a varchar(100) charset utf8); - Query OK, 0 rows affected - tidb> insert t values (unhex('f09f8c80')); - Query OK, 1 row affected - ``` - -- 升级后：v2.1.2 及之后版本 - - ```sql - tidb> insert t values (unhex('f09f8c80')); - ERROR 1366 (HY000): incorrect utf8 value f09f8c80(🌀) for column a - ``` - -解决方案： - -- v2.1.2 版本：该版本不支持修改 column charset，所以只能跳过 UTF8 的检查。 - - ```sql - tidb > set @@session.tidb_skip_utf8_check=1; - Query OK, 0 rows affected - tidb > insert t values (unhex('f09f8c80')); - Query OK, 1 row affected - ``` - -- v2.1.3 及之后版本：建议修改 column 的 charset 为 UTF8MB4。或者也可以设置 `tidb_skip_utf8_check` 变量跳过 UTF8 的检查。如果跳过 UTF8 的检查，在需要将数据从 TiDB 同步回 MySQL 的时候，可能会失败，因为 MySQL 会执行该检查。 - - ```sql - tidb > alter table t change column a a varchar(100) character set utf8mb4; - Query OK, 0 rows affected - tidb > insert t values (unhex('f09f8c80')); - Query OK, 1 row affected - ``` - - 关于 `tidb_skip_utf8_check` 变量，具体来说是指跳过 UTF8 和 UTF8MB4 类型对数据的合法性检查。如果跳过这个检查，在需要将数据从 TiDB 同步回 MySQL 的时候，可能会失败，因为 MySQL 执行该检查。如果只想跳过 UTF8 类型的检查，可以设置 `tidb_check_mb4_value_in_utf8` 变量。 - - `tidb_check_mb4_value_in_utf8` 在 v2.1.3 版本加入 `config.toml` 文件，可以修改配置文件里面的 `check-mb4-value-in-utf8` 后重启集群生效。 - - `tidb_check_mb4_value_in_utf8` 在 v2.1.5 版本开始可以用 HTTP API 来设置，也可以用 session 变量来设置。 - - * HTTP API（HTTP API 只在单台服务器上生效） - - * 执行下列命令启用 HTTP API： - - {{< copyable "shell-regular" >}} - - ```sh - curl -X POST -d "check_mb4_value_in_utf8=1" http://{TiDBIP}:10080/settings - ``` - - * 执行下列命令禁用 HTTP API： - - {{< copyable "shell-regular" >}} - - ```sh - curl -X POST -d "check_mb4_value_in_utf8=0" http://{TiDBIP}:10080/settings - ``` - - * Session 变量 - - * 执行下列命令启用 Session 变量： - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_check_mb4_value_in_utf8 = 1; - ``` - - * 执行下列命令禁用 Session 变量： - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_check_mb4_value_in_utf8 = 0; - ``` - -- v2.1.7 及之后版本，如果对表和 column 的字符集没有严格要求为 UTF8，也不想修改客户端代码去跳过 UTF8 检查或者手动修改 column 的 charset，可以在配置文件中把 `treat-old-version-utf8-as-utf8mb4` 打开。该配置的作用是自动把 v2.1.7 版本之前创建的旧版本的表和 column 的 UTF8 字符集转成 UTF8MB4。这个转换是在 TiDB load schema 时在内存中将 UTF8 转成 UTF8MB4，不会对实际存储的数据做任何修改。在配置文件中关闭 `treat-old-version-utf8-as-utf8mb4` 并重启 TiDB 后，以前字符集为 UTF8 的表和 column 的字符集仍然还是 UTF8。 - - > **注意：** - > - > `treat-old-version-utf8-as-utf8mb4` 参数默认打开，如果客户端强制需要用 UTF8 而不用 UTF8MB4，需要在配置文件中关闭。 diff --git a/v2.1/glossary.md b/v2.1/glossary.md deleted file mode 100644 index 3b31e69e5d20..000000000000 --- a/v2.1/glossary.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: 术语表 -summary: 了解 TiDB 相关术语。 -category: glossary ---- - -# 术语表 - -## A - -### ACID - -ACID 是指数据库管理系统在写入或更新资料的过程中，为保证[事务](#事务)是正确可靠的，所必须具备的四个特性：原子性 (atomicity)、一致性 (consistency)、隔离性（isolation）以及持久性（durability）。 - -* 原子性 (atomicity) 指一个事务中的所有操作，或者全部完成，或者全部不完成，不会结束在中间某个环节。TiDB 通过 Primary Key 所在 [Region](#regionpeerraft-group) 的原子性来保证分布式事务的原子性。 -* 一致性 (consistency) 指在事务开始之前和结束以后，数据库的完整性没有被破坏。TiDB 在写入数据之前，会校验数据的一致性，校验通过才会写入内存并返回成功。 -* 隔离性 (isolation) 指数据库允许多个并发事务同时对其数据进行读写和修改的能力。隔离性可以防止多个事务并发执行时由于交叉执行而导致数据的不一致，主要用于处理并发场景。TiDB 目前只支持一种隔离级别，即可重复读。 -* 持久性 (durability) 指事务处理结束后，对数据的修改就是永久的，即便系统故障也不会丢失。在 TiDB 中，事务一旦提交成功，数据全部持久化存储到 TiKV，此时即使 TiDB 服务器宕机也不会出现数据丢失。 - -## L - -### Leader/Follower/Learner - -它们分别对应 [Peer](#regionpeerraft-group) 的三种角色。其中 Leader 负责响应客户端的读写请求；Follower 被动地从 Leader 同步数据，当 Leader 失效时会进行选举产生新的 Leader；Learner 是一种特殊的角色，它只参与同步 raft log 而不参与投票，在目前的实现中只短暂存在于添加副本的中间步骤。 - -## O - -### Operator - -Operator 是应用于一个 Region 的，服务于某个调度目的的一系列操作的集合。例如“将 Region 2 的 Leader 迁移至 Store 5”，“将 Region 2 的副本迁移到 Store 1, 4, 5”等。 - -Operator 可以是由 Scheduler 通过计算生成的，也可以是由外部 API 创建的。 - -### Operator Step - -Operator Step 是 Operator 执行过程的一个步骤，一个 Operator 常常会包含多个 Operator Step。 - -目前 PD 可生成的 Step 包括： - -- `TransferLeader`：将 Region Leader 迁移至指定 Peer -- `AddPeer`：在指定 Store 添加 Follower -- `RemovePeer`：删除一个 Region Peer -- `AddLearner`：在指定 Store 添加 Region Learner -- `PromoteLearner`：将指定 Learner 提升为 Follower -- `SplitRegion`：将指定 Region 一分为二 - -## P - -### Pending/Down - -Pending 和 Down 是 Peer 可能出现的两种特殊状态。其中 Pending 表示 Follower 或 Learner 的 raft log 与 Leader 有较大差距，Pending 状态的 Follower 无法被选举成 Leader。Down 是指 Leader 长时间没有收到对应 Peer 的消息，通常意味着对应节点发生了宕机或者网络隔离。 - -## R - -### Region/Peer/Raft Group - -每个 Region 负责维护集群的一段连续数据（默认配置下平均约 96 MiB），每份数据会在不同的 Store 存储多个副本（默认配置是 3 副本），每个副本称为 Peer。同一个 Region 的多个 Peer 通过 raft 协议进行数据同步，所以 Peer 也用来指代 raft 实例中的成员。TiKV 使用 multi-raft 模式来管理数据，即每个 Region 都对应一个独立运行的 raft 实例，我们也把这样的一个 raft 实例叫做一个 Raft Group。 - -### Region Split - -TiKV 集群中的 Region 不是一开始就划分好的，而是随着数据写入逐渐分裂生成的，分裂的过程被称为 Region Split。 - -其机制是集群初始化时构建一个初始 Region 覆盖整个 key space，随后在运行过程中每当 Region 数据达到一定量之后就通过 Split 产生新的 Region。 - -## S - -### Scheduler - -Scheduler（调度器）是 PD 中生成调度的组件。PD 中每个调度器是独立运行的，分别服务于不同的调度目的。常用的调度器及其调用目标有： - -- `balance-leader-scheduler`：保持不同节点的 Leader 均衡。 -- `balance-region-scheduler`：保持不同节点的 Peer 均衡。 -- `hot-region-scheduler`：保持不同节点的读写热点 Region 均衡。 -- `evict-leader-{store-id}`：驱逐某个节点的所有 Leader。（常用于滚动升级） - -### Store - -PD 中的 Store 指的是集群中的存储节点，也就是 tikv-server 实例。Store 与 TiKV 实例是严格一一对应的，即使在同一主机甚至同一块磁盘部署多个 TiKV 实例，这些实例也对会对应不同的 Store。 diff --git a/v2.1/how-to/configure/memory-control.md b/v2.1/how-to/configure/memory-control.md deleted file mode 100644 index 68d9c4d07b53..000000000000 --- a/v2.1/how-to/configure/memory-control.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB 内存控制文档 -category: how-to ---- - -# TiDB 内存控制文档 - -目前 TiDB 已经能够做到追踪单条 SQL 查询过程中的内存使用情况，当内存使用超过一定阈值后也能采取一些操作来预防 OOM 或者排查 OOM 原因。在 TiDB 的配置文件中，我们可以使用如下配置来控制内存使用超阈值时 TiDB 的行为： - -``` -# Valid options: ["log", "cancel"] -oom-action = "log" -``` - -- 如果上面的配置项使用的是 "log"，那么当一条 SQL 的内存使用超过一定阈值（由 session 变量 `tidb_mem_quota_query` 来控制）后，TiDB 会在 log 文件中打印一条 LOG，然后这条 SQL 继续执行，之后如果发生了 OOM 可以在 LOG 中找到对应的 SQL。 -- 如果上面的配置项使用的是 "cancel"，那么当一条 SQL 的内存使用超过一定阈值后，TiDB 会立即中断这条 SQL 的执行并给客户端返回一个 error，error 信息中会详细写明这条 SQL 执行过程中各个占用内存比较多的物理执行算子的内存使用情况。 - -## 如何配置一条 SQL 执行过程中的内存使用阈值 - -可以在配置文件中设置每个 Query 默认的 Memory Quota，例如将其设置为 32GB： -``` -mem-quota-query = 34359738368 -``` - -此外还可通过如下几个 session 变量来控制一条 Query 中的内存使用，大多数用户只需要设置 `tidb_mem_quota_query` 即可，其他变量是高级配置，大多数用户不需要关心： - -| 变量名 | 作用 | 单位 | 默认值 | -|-----------------------------------|---------------------------------------------------|-------|-----------| -| tidb_mem_quota_query | 配置整条 SQL 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_hashjoin | 配置 Hash Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_mergejoin | 配置 Merge Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_sort | 配置 Sort 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_topn | 配置 TopN 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_indexlookupreader | 配置 Index Lookup Reader 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_indexlookupjoin | 配置 Index Lookup Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_nestedloopapply | 配置 Nested Loop Apply 的内存使用阈值 | Byte | 32 << 30 | - -几个使用例子： - -```sql --- 配置整条 SQL 的内存使用阈值为 8GB： -set @@tidb_mem_quota_query = 8 << 30; - --- 配置整条 SQL 的内存使用阈值为 8MB： -set @@tidb_mem_quota_query = 8 << 20; - --- 配置整条 SQL 的内存使用阈值为 8KB： -set @@tidb_mem_quota_query = 8 << 10; -``` diff --git a/v2.1/how-to/configure/time-zone.md b/v2.1/how-to/configure/time-zone.md deleted file mode 100644 index 45c1538cfafe..000000000000 --- a/v2.1/how-to/configure/time-zone.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: 时区支持 -category: how-to ---- - -# 时区支持 - -TiDB 使用的时区由 `time_zone` 全局变量和 session 变量决定。`time_zone` 的默认值是 `System`，`System` 对应的实际时区在 `TiDB` 集群 bootstrap 初始化时设置。具体逻辑如下: - -* 优先使用 `TZ` 环境变量 -* 如果失败，则从 `/etc/localtime` 的实际软链地址提取。 -* 如果上面两种都失败则使用 `UTC` 作为系统时区。 - -在运行过程中可以修改全局时区： - -```sql -mysql> SET GLOBAL time_zone = timezone; -``` - -TiDB 还可以通过设置 session 变量 `time_zone` 为每个连接维护各自的时区。默认条件下，这个值取的是全局变量 `time_zone` 的值。修改 session 使用的时区： - -```sql -mysql> SET time_zone = timezone; -``` - -查看当前使用的时区的值： - -```sql -mysql> SELECT @@global.time_zone, @@session.time_zone; -``` - -设置 `time_zone` 的值的格式： - -* 'SYSTEM' 表明使用系统时间 -* 相对于 UTC 时间的偏移，比如 '+10:00' 或者 '-6:00' -* 某个时区的名字，比如 'Europe/Helsinki'， 'US/Eastern' 或 'MET' - -`NOW()` 和 `CURTIME()` 的返回值都受到时区设置的影响。 - -> **注意：** -> -> 只有 Timestamp 数据类型的值是受时区影响的。可以理解为， Timestamp 数据类型的实际表示使用的是 (字面值 + 时区信息)。其它时间和日期类型，比如 Datetime/Date/Time 是不包含时区信息的，所以也不受到时区变化的影响。 - -```sql -mysql> create table t (ts timestamp, dt datetime); -Query OK, 0 rows affected (0.02 sec) - -mysql> set @@time_zone = 'UTC'; -Query OK, 0 rows affected (0.00 sec) - -mysql> insert into t values ('2017-09-30 11:11:11', '2017-09-30 11:11:11'); -Query OK, 1 row affected (0.00 sec) - -mysql> set @@time_zone = '+8:00'; -Query OK, 0 rows affected (0.00 sec) - -mysql> select * from t; -+---------------------|---------------------+ -| ts | dt | -+---------------------|---------------------+ -| 2017-09-30 19:11:11 | 2017-09-30 11:11:11 | -+---------------------|---------------------+ -1 row in set (0.00 sec) -``` - -上面的例子中，无论怎么调整时区的值， Datetime 类型字段的值是不受影响的，而 Timestamp 则随着时区改变，显示的值会发生变化。其实 Timestamp 持久化到存储的值始终没有变化过，只是根据时区的不同显示值不同。 - -Timestamp 类型和 Datetime 等类型的值，两者相互转换的过程中，会涉及到时区。这种情况一律基于 session 的当前 `time_zone` 时区处理。 - -另外，用户在导数据的过程中，也要需注意主库和从库之间的时区设定是否一致。 diff --git a/v2.1/how-to/deploy/data-migration-with-ansible.md b/v2.1/how-to/deploy/data-migration-with-ansible.md deleted file mode 100644 index 01e01ba4b235..000000000000 --- a/v2.1/how-to/deploy/data-migration-with-ansible.md +++ /dev/null @@ -1,527 +0,0 @@ ---- -title: 使用 DM-Ansible 部署 DM 集群 -category: how-to ---- - -# 使用 DM-Ansible 部署 DM 集群 - -DM-Ansible 是 PingCAP 基于 [Ansible](https://docs.ansible.com/ansible/latest/index.html) 的 [Playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html#about-playbooks) 研发的 DM (Data Migration) 集群部署工具。本文将介绍如何使用 DM-Ansible 快速部署 DM 集群。 - -## 准备工作 - -在开始之前，先确保您准备好了以下配置的机器： - -1. 部署目标机器若干，配置如下： - - - CentOS 7.3 (64-bit) 或更高版本，x86_64 架构（AMD64） - - 机器之间内网互通 - - 关闭防火墙，或开放服务端口 - -2. 一台中控机，配置如下： - - - 包含 Python 2.7 的 CentOS 7.3（64-bit）或更高版本 - - Ansible 2.5 或更高版本 - - 互联网访问 - -## 第 1 步：在中控机上安装依赖包 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -根据中控机的操作系统版本，运行相应命令如下： - -- CentOS 7： - - ``` - # yum -y install epel-release git curl sshpass - # yum -y install python-pip - ``` - -- Ubuntu： - - ``` - # apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH 密钥 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -1. 创建 `tidb` 用户。 - - ``` - # useradd -m -d /home/tidb tidb - ``` - -2. 为 `tidb` 用户设置密码。 - - ``` - # passwd tidb - ``` - -3. 在 sudo 文件尾部加上 `tidb ALL=(ALL) NOPASSWD: ALL`，为 `tidb` 用户设置免密使用 sudo。 - - ``` - # visudo - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH 密钥。 - - 执行以下 `su` 命令，将登录用户从 `root` 切换至 `tidb`。 - - ``` - # su - tidb - ``` - - 为 `tidb` 用户创建 SSH 密钥。当提示 `Enter passphrase` 时，按 Enter 键。命令成功执行后，生成的 SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为`/home/tidb/.ssh/id_rsa.pub`。 - - ``` - $ ssh-keygen -t rsa - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：下载 DM-Ansible 至中控机 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -1. 打开 `/home/tidb` 目录。 -2. 执行以下命令下载 DM-Ansible。 - - ```bash - $ wget https://download.pingcap.org/dm-ansible-{version}.tar.gz - ``` - - `{version}` 为期望下载的 DM 版本，如 `v1.0.1`、`v1.0.2` 等， - 可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 第 4 步：安装 DM-Ansible 及其依赖至中控机 - -> **注意：** -> -> - 请确保使用 `tidb` 账户登录中控机。 -> - 您需要使用 `pip` 方式下载安装 Ansible 及其依赖，否则可能会遇到兼容性问题。 DM-Ansible 当前与 Ansible 2.5 或更高版本兼容。 - -1. 在中控机上安装 DM-Ansible 及其依赖包： - - ```bash - $ tar -xzvf dm-ansible-{version}.tar.gz - $ mv dm-ansible-{version} dm-ansible - $ cd /home/tidb/dm-ansible - $ sudo pip install -r ./requirements.txt - ``` - - Ansible 和相关依赖包含于 `dm-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 版本： - - ```bash - $ ansible --version - ansible 2.5.0 - ``` - -## 第 5 步：在中控机上配置 SSH 互信和 sudo 规则 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录至中控机。 - -1. 将您部署的目标机器的 IP 地址加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - ``` - $ cd /home/tidb/dm-ansible - $ vi hosts.ini - [servers] - 172.16.10.71 - 172.16.10.72 - 172.16.10.73 - - [all:vars] - username = tidb - ``` - -2. 运行如下命令，然后输入部署目标机器的 `root` 用户密码。 - - ```bash - $ ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，创建 sudo 规则，并为中控机和部署目标机器之间配置 SSH 互信。 - -## 第 6 步：下载 DM 及监控组件安装包至中控机 - -> **注意：** -> -> 请确保中控机接入互联网。 - -在中控机上，运行如下命令： - -```bash -ansible-playbook local_prepare.yml -``` - -## 第 7 步：编辑 `inventory.ini` 配置文件 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -打开并编辑 `/home/tidb/dm-ansible/inventory.ini` 文件如下，以管控 DM 集群。 - -```ini -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -根据场景需要，您可以在以下两种集群拓扑中任选一种： - -- [单节点上单个 DM-worker 实例的集群拓扑](#选项-1使用单节点上单个-dm-worker-实例的集群拓扑) -- [单节点上多个 DM-worker 实例的集群拓扑](#选项-2使用单节点上多个-dm-worker-实例的集群拓扑) - -通常情况下，我们推荐每个节点上部署单个 DM-Worker 实例。但如果您的机器拥有性能远超 [TiDB 软件和硬件环境要求](/v2.1/how-to/deploy/hardware-recommendations.md)中推荐配置的 CPU 和内存，并且每个节点配置 2 块以上的硬盘或大于 2T 的 SSD，您可以在单个节点上部署不超过 2 个 DM-Worker 实例。 - -### 选项 1：使用单节点上单个 DM-Worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1 | -| node3 | 172.16.10.73 | DM-worker2 | -| mysql-replica-01| 172.16.10.81 | MySQL | -| mysql-replica-02| 172.16.10.82 | MySQL | - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2 ansible_host=172.16.10.73 server_id=102 source_id="mysql-replica-02" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。关于 DM-worker 参数的更多信息，请参考 [DM-worker 配置及参数描述](#dm-worker-配置及参数描述)。 - -### 选项 2：使用单节点上多个 DM-worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1-1, DM-worker1-2 | -| node3 | 172.16.10.73 | DM-worker2-1, DM-worker2-2 | - -编辑 `inventory.ini` 文件时，请注意区分这些变量：`server_id`，`deploy_dir`，和 `dm_worker_port`。 - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1_1 ansible_host=172.16.10.72 server_id=101 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker1_2 ansible_host=172.16.10.72 server_id=102 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2_1 ansible_host=172.16.10.73 server_id=103 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker2_2 ansible_host=172.16.10.73 server_id=104 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.84 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。 - -### DM-worker 配置及参数描述 - -| 变量名称 | 描述 | -| ------------- | ------- -| source_id | DM-worker 绑定到的一个数据库实例或是具有主从架构的复制组。当发生主从切换的时候，只需要更新 `mysql_host` 或 `mysql_port` 而不用更改该 ID 标识。 | -| server_id | DM-worker 伪装成一个 MySQL slave，该变量即为这个 slave 的 server ID，在 MySQL 集群中需保持全局唯一。取值范围 0 ~ 4294967295。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置。 | -| mysql_host | 上游 MySQL 主机。 | -| mysql_user | 上游 MySQL 用户名，默认值为 “root”。| -| mysql_password | 上游 MySQL 用户密码，需使用 `dmctl` 工具加密。请参考[使用 dmctl 加密上游 MySQL 用户密码](#使用-dmctl-加密上游-mysql-用户密码)。 | -| mysql_port | 上游 MySQL 端口， 默认 3306。 | -| enable_gtid | DM-worker 是否使用全局事务标识符（GTID）拉取 binlog。使用前提是在上游 MySQL 已开启 GTID 模式。 | -| relay_binlog_name | DM-worker 是否从指定 binlog 文件位置开始拉取 binlog。仅适用于本地无有效 relay log 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| relay_binlog_gtid | DM-worker 是否从指定 GTID 位置开始拉取 binlog。仅适用于本地无有效 relay log，且 `enable_gtid` 设置为 true 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| flavor | 代表 MySQL 的版本发布类型。 如果是官方版本，Percona 版，或 Cloud MySQL 版，其值为 “mysql”。 如果是 MariaDB，其值为 "mariadb"。默认值是 "mysql"。 | - -关于 `deploy_dir` 配置的更多信息，请参考[配置部署目录](#配置部署目录)。 - -### 使用 dmctl 加密上游 MySQL 用户密码 - -假定上游 MySQL 的用户密码为 `123456`，运行以下命令，并将生成的字符串添加至 DM-worker 的 `mysql_password` 变量。 - -```bash -$ cd /home/tidb/dm-ansible/resources/bin -$ ./dmctl -encrypt 123456 -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -## 第 8 步：编辑 `inventory.ini` 文件中的变量 - -此步介绍如何编辑部署目录中的变量，如何配置 relay log 同步位置以及 relay log GTID 的同步模式。此外，还会描述 `inventory.ini` 中的全局变量。 - -### 配置部署目录 - -编辑 `deploy_dir` 变量以配置部署目录。 - -- 全局变量默认设为 `/home/tidb/deploy`，适用于所有服务。如果数据盘挂载于 `/data1` 目录，您可以通过以下修改将其变更至 `/data1/dm`。 - - ```ini - ## Global variables. - [all:vars] - deploy_dir = /data1/dm - ``` - -- 如果需要为某个服务创建单独的部署目录，您可以在 `inventory.ini` 中配置服务主机列表的同时设置 host 变量。此操作需要您添加第一列别名，以避免在混合服务部署场景下产生混淆。 - - ```ini - dm-master ansible_host=172.16.10.71 deploy_dir=/data1/deploy - ``` - -### 配置 relay log 同步位置 - -首次启动 DM-worker 时，您需要配置 `relay_binlog_name` 变量以指定 DM-worker 拉取上游 MySQL 或 MariaDB binlog 的起始位置。 - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 relay_binlog_name="binlog.000011" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name="binlog.000002" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -> **注意：** -> -> 如未设定 `relay_binlog_name`，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置 - -### 开启 relay log GTID 同步模式 - -在 DM 集群中，DM-worker 的 relay log 处理单元负责与上游 MySQL 或 MariaDB 通信，从而将 binlog 拉取至本地文件系统。 - -DM 目前支持 MySQL GTID 和 MariaDB GTID。您可以通过配置以下项目开启 relay log GTID 同步模式： - -- `enable_gtid`：打开 relay log GTID 同步模式以处理 master 和 slave 易位的场景 - -- `relay_binlog_gtid`：指定 DM-worker 开始拉取对应上游 MySQL 或 MariaDB binlog 的起始位置 - -示例配置如下： - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 enable_gtid=true relay_binlog_gtid="aae3683d-f77b-11e7-9e3b-02a495f8993c:1-282967971,cc97fa93-f5cf-11e7-ae19-02915c68ee2e:1-284361339" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name=binlog.000002 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -### 全局变量 - -| 变量名称 | 描述 | -| --------------- | ---------------------------------------------------------- | -| cluster_name | 集群名称，可调整 | -| dm_version | DM 版本，默认已配置 | -| grafana_admin_user | Grafana 管理员用户名称，默认值 `admin` | -| grafana_admin_password | Grafana 管理员账户的密码，用于通过 Ansible 导入 Dashboard。默认值为 `admin`。如果您在 Grafana 网页端修改了密码，请更新此变量。 | - -## 第 9 步：部署 DM 集群 - -使用 `ansible-playbook` 运行 Playbook，默认并发数量是 5。如果部署目标机器较多，您可以使用 `-f` 参数增加并发数量，例如，`ansible-playbook deploy.yml -f 10`。 - -以下部署操作示例使用中运行服务的用户为 `tidb`： - -1. 编辑 `dm-ansible/inventory.ini` 文件，确保 `ansible_user = tidb`。 - - ```ini - ansible_user = tidb - ``` - - > **注意：** - > - > 请勿将 `ansible_user` 设为 `root`，因为 `tidb-ansible` 限制服务需以普通用户运行。 - - 运行以下命令。如果所有服务都返回 `tidb`，则 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 运行以下命令。如果所有服务都返回 `root`，则 `tidb` 用户免密 sudo 操作配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 修改内核参数，并部署 DM 集群组件和监控组件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - -3. 启动 DM 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - - 此操作会按顺序启动 DM 集群的所有组件，包括 DM-master，DM-worker，以及监控组件。当一个 DM 集群被关闭后，您可以使用该命令将其开启。 - -## 第 10 步：关闭 DM 集群 - -如果您需要关闭一个 DM 集群，运行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -该操作会按顺序关闭整个 DM 集群中的所有组件，包括 DM-master，DM-worker，以及监控组件。 - -## 常见部署问题 - -### 默认服务端口 - -| 组件 | 端口变量 | 默认端口 | 描述 | -| :-- | :-- | :-- | :-- | -| DM-master | `dm_master_port` | 8261 | DM-master 服务交流端口 | -| DM-worker | `dm_worker_port` | 8262 | DM-worker 服务交流端口 | -| Prometheus | `prometheus_port` | 9090 | Prometheus 服务交流端口 | -| Grafana | `grafana_port` | 3000 | 外部 Web 监控服务及客户端（浏览器）访问端口 | -| Alertmanager | `alertmanager_port` | 9093 | Alertmanager 服务交流端口 | - -### 自定义端口 - -编辑 `inventory.ini` 文件，将服务端口的相关主机变量添加在对应服务 IP 地址后： - -```ini -dm_master ansible_host=172.16.10.71 dm_master_port=18261 -``` - -### 更新 DM-Ansible - -1. 使用 `tidb` 账户登录至中控机，进入 `/home/tidb` 目录，然后备份`dm-ansible` 文件夹。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - mv dm-ansible dm-ansible-bak - ``` - -2. 下载指定版本 DM-Ansible，解压。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz && \ - tar -xzvf dm-ansible-{version}.tar.gz && \ - mv dm-ansible-{version} dm-ansible - ``` - -3. 迁移 `inventory.ini` 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - cp dm-ansible-bak/inventory.ini dm-ansible/inventory.ini - ``` - -4. 迁移 `dmctl` 配置。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible-bak/dmctl && \ - cp * /home/tidb/dm-ansible/dmctl/ - ``` - -5. 用 Playbook 下载最新的 DM 二进制文件。此文件会自动替换 `/home/tidb/dm-ansible/resource/bin/` 目录下的二进制文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` diff --git a/v2.1/how-to/deploy/data-migration-with-binary.md b/v2.1/how-to/deploy/data-migration-with-binary.md deleted file mode 100644 index 9552cc2f6162..000000000000 --- a/v2.1/how-to/deploy/data-migration-with-binary.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: 使用 DM binary 部署 DM 集群 -category: how-to ---- - -# 使用 DM binary 部署 DM 集群 - -本文将介绍如何使用 DM binary 快速部署 DM 集群。 - -## 准备工作 - -下载官方 binary，链接地址：[DM 下载](/v2.1/reference/tools/download.md#tidb-dm-data-migration)。 - -下载的文件中包括子目录 bin 和 conf。bin 目录下包含 dm-master、dm-worker、dmctl 以及 Mydumper 的二进制文件。conf 目录下有相关的示例配置文件。 - -## 使用样例 - -假设在两台服务器上部署 MySQL，在一台服务器上部署 TiDB（mocktikv 模式），另外在三台服务器上部署两个 DM-worker 实例和一个 DM-master 实例。各个节点的信息如下： - -| 实例 | 服务器地址 | -| :---------- | :----------- | -| MySQL1 | 192.168.0.1 | -| MySQL2 | 192.168.0.2 | -| TiDB | 192.168.0.3 | -| DM-master | 192.168.0.4 | -| DM-worker1 | 192.168.0.5 | -| DM-worker2 | 192.168.0.6 | - -MySQL1 和 MySQL2 中需要开启 binlog。DM-worker1 负责同步 MySQL1 的数据，DM-worker2 负责同步 MySQL2 的数据。下面以此为例，说明如何部署 DM。 - -### DM-worker 的部署 - -DM-worker 需要连接上游 MySQL，且为了安全，强制用户配置加密后的密码。首先使用 dmctl 对 MySQL 的密码进行加密，以密码为 "123456" 为例： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dmctl --encrypt "123456" -``` - -``` -fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg= -``` - -记录该加密后的值，用于下面部署 DM-worker 时的配置。 - -DM-worker 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -查看 DM-worker 的命令行参数说明： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dm-worker --help -``` - -``` -Usage of worker: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值："info"） - -V 输出版本信息 - -checker-backoff-max duration - 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔（默认值："5m0s"，一般情况下不需要修改。如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-backoff-rollback duration - 任务检查模块中，调整自动恢复等待时间的间隔（默认值："5m0s"，一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-check-enable - 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务（默认值：true） - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -print-sample-config - 打印示例配置 - -purge-expires int - relay log 的过期时间。DM-worker 会尝试自动删除最后修改时间超过了过期时间的 relay log（单位：小时） - -purge-interval int - 定期检查 relay log 是否过期的间隔时间（默认值：3600）（单位：秒） - -purge-remain-space int - 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log（默认值：15）（单位：GB） - -relay-dir string - 存储 relay log 的路径（默认值："./relay_log"） - -worker-addr string - DM-worker 的地址 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件来配置 DM-worker，把以下配置文件内容写入到 `conf/dm-worker1.toml` 中。 - -DM-worker 的配置文件： - -```toml -# Worker Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker 的地址 -worker-addr = ":8262" - -# 作为 MySQL slave 的 server ID，用于获取 MySQL 的 binlog -# 在一个 replication group 中，每个实例（master 和 slave）都应该有唯一的 server ID -# v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置 -server-id = 101 - -# 用于标识一个 replication group 或者 MySQL/MariaDB 实例 -source-id = "mysql-replica-01" - -# 上游实例类型，值可为 "mysql" 或者 "mariadb" -# v1.0.2 及以上版本的 DM 会自动识别上游实例类型，不需要手动配置 -flavor = "mysql" - -# MySQL 的连接地址 -[from] -host = "192.168.0.1" -user = "root" -password = "fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg=" -port = 3306 -``` - -在终端中使用下面的命令运行 DM-worker： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-worker -config conf/dm-worker1.toml -``` - -对于 DM-worker2，修改配置文件中的 `source-id` 为 `mysql-replica-02`，并将 `from` 配置部分修改为 MySQL2 的地址即可。如果因为没有多余的机器，将 DM-worker2 与 DM-worker1 部署在一台机器上，需要把两个 DM-worker 实例部署在不同的路径下，否则保存元信息和 relay log 的默认路径会冲突。 - -### DM-master 的部署 - -DM-master 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -DM-master 的命令行参数说明： - -```bash -./bin/dm-master --help -``` - -``` -Usage of dm-master: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值为 "info"） - -V 输出版本信息 - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -master-addr string - DM-master 的地址 - -print-sample-config - 打印出 DM-master 的示例配置 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件，把以下配置文件内容写入到 `conf/dm-master.toml` 中。 - -DM-master 的配置文件： - -```toml -# Master Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-master.log" - -# DM-master 监听地址 -master-addr = ":8261" - -# DM-Worker 的配置 -[[deploy]] -# 对应 DM-worker1 配置文件中的 source-id -source-id = "mysql-replica-01" -# DM-worker1 的服务地址 -dm-worker = "192.168.0.5:8262" - -[[deploy]] -# 对应 DM-worker2 配置文件中的 source-id -source-id = "mysql-replica-02" -# DM-worker2 的服务地址 -dm-worker = "192.168.0.6:8262" -``` - -在终端中使用下面的命令运行 DM-master： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-master -config conf/dm-master.toml -``` - -这样，DM 集群就部署成功了。下面创建简单的数据同步任务来使用 DM 集群。 - -### 创建数据同步任务 - -假设在 MySQL1 和 MySQL2 实例中有若干个分表，这些分表的结构相同，所在库的名称都以 "sharding" 开头，表名称都以 "t" 开头，并且主键或唯一键不存在冲突（即每张分表的主键或唯一键各不相同）。现在需要把这些分表同步到 TiDB 中的 `db_target.t_target` 表中。 - -首先创建任务的配置文件： - -{{< copyable "" >}} - -```yaml ---- -name: test -task-mode: all -is-sharding: true - -target-database: - host: "192.168.0.3" - port: 4000 - user: "root" - password: "" # 如果密码不为空，也需要配置 dmctl 加密后的密码 - -mysql-instances: - - source-id: "mysql-replica-01" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - -black-white-list: - instance: - do-dbs: ["~^sharding[\\d]+"] - do-tables: - - db-name: "~^sharding[\\d]+" - tbl-name: "~^t[\\d]+" - -routes: - sharding-route-rules-table: - schema-pattern: sharding* - table-pattern: t* - target-schema: db_target - target-table: t_target - - sharding-route-rules-schema: - schema-pattern: sharding* - target-schema: db_target -``` - -将以上配置内容写入到 `conf/task.yaml` 文件中，使用 dmctl 创建任务： - -{{< copyable "shell-regular" >}} - -```bash -bin/dmctl -master-addr 192.168.0.4:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 -» -``` - -{{< copyable "" >}} - -```bash -» start-task conf/task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "192.168.0.5:8262", - "msg": "" - }, - { - "result": true, - "worker": "192.168.0.6:8262", - "msg": "" - } - ] -} -``` - -这样就成功创建了一个将 MySQL1 和 MySQL2 实例中的分表数据同步到 TiDB 的任务。 diff --git a/v2.1/how-to/deploy/geographic-redundancy/location-awareness.md b/v2.1/how-to/deploy/geographic-redundancy/location-awareness.md deleted file mode 100644 index 8a9444774662..000000000000 --- a/v2.1/how-to/deploy/geographic-redundancy/location-awareness.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: 集群拓扑信息配置 -category: how-to ---- - -# 集群拓扑信息配置 - -## 概述 - -PD 能够根据 TiKV 集群的拓扑结构进行调度，使得 TiKV 的容灾能力最大化。 - -阅读本章前，请先确保阅读 [Ansible 部署方案](/v2.1/how-to/deploy/orchestrated/ansible.md) 和 [Docker 部署方案](/v2.1/how-to/deploy/orchestrated/docker.md)。 - -## TiKV 上报拓扑信息 - -可以通过 TiKV 的启动参数或者配置文件来让 TiKV 上报拓扑信息给 PD。 - -假设拓扑结构分为三级：zone > rack > host，可以通过 labels 来指定这些信息。 - -启动参数： - -``` -tikv-server --labels zone=,rack=,host= -``` - -配置文件： - -```toml -[server] -labels = "zone=,rack=,host=" -``` - -## PD 理解 TiKV 拓扑结构 - -可以通过 PD 的配置文件让 PD 理解 TiKV 集群的拓扑结构。 - -```toml -[replication] -max-replicas = 3 -location-labels = ["zone", "rack", "host"] -``` - -其中 `location-labels` 需要与 TiKV 的 `labels` 名字对应，这样 PD 才能知道这些 `labels` 代表了 TiKV 的拓扑结构。 - -> **注意：** -> -> 必须同时配置 PD 的 `location-labels` 和 TiKV 的 `labels` 参数，否则 `labels` 不会生效。 - -## PD 基于 TiKV 拓扑结构进行调度 - -PD 能够根据我们提供的拓扑信息作出最优的调度，我们只需要关心什么样的拓扑结构能够达到我们想要的效果。 - -假设我们使用三副本，并且希望一个数据中心挂掉的情况下，还能继续保持 TiDB 集群的高可用状态，我们至少需要四个数据中心。 - -假设我们有四个数据中心 (zone)，每个数据中心有两个机架 (rack)，每个机架上有两个主机 (host)。 -每个主机上面启动一个 TiKV 实例： - -``` -# zone=z1 -tikv-server --labels zone=z1,rack=r1,host=h1 -tikv-server --labels zone=z1,rack=r1,host=h2 -tikv-server --labels zone=z1,rack=r2,host=h1 -tikv-server --labels zone=z1,rack=r2,host=h2 - -# zone=z2 -tikv-server --labels zone=z2,rack=r1,host=h1 -tikv-server --labels zone=z2,rack=r1,host=h2 -tikv-server --labels zone=z2,rack=r2,host=h1 -tikv-server --labels zone=z2,rack=r2,host=h2 - -# zone=z3 -tikv-server --labels zone=z3,rack=r1,host=h1 -tikv-server --labels zone=z3,rack=r1,host=h2 -tikv-server --labels zone=z3,rack=r2,host=h1 -tikv-server --labels zone=z3,rack=r2,host=h2 - -# zone=z4 -tikv-server --labels zone=z4,rack=r1,host=h1 -tikv-server --labels zone=z4,rack=r1,host=h2 -tikv-server --labels zone=z4,rack=r2,host=h1 -tikv-server --labels zone=z4,rack=r2,host=h2 -``` - -也就是说，我们有 16 个 TiKV 实例，分布在 4 个不同的数据中心，8 个不同的机架，16 个不同的机器。 - -在这种拓扑结构下，PD 会优先把每一份数据的不同副本调度到不同的数据中心。 -这时候如果其中一个数据中心挂了，不会影响 TiDB 集群的高可用状态。 -如果这个数据中心一段时间内恢复不了，PD 会把这个数据中心的副本迁移出去。 - -总的来说，PD 能够根据当前的拓扑结构使得集群容灾能力最大化，所以如果我们希望达到某个级别的容灾能力， -就需要根据拓扑机构在不同的地理位置提供多于备份数 (`max-replicas`) 的机器。 diff --git a/v2.1/how-to/deploy/geographic-redundancy/overview.md b/v2.1/how-to/deploy/geographic-redundancy/overview.md deleted file mode 100644 index 80daae48a75e..000000000000 --- a/v2.1/how-to/deploy/geographic-redundancy/overview.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: 跨数据中心部署方案 -category: how-to ---- - -# 跨数据中心部署方案 - -作为 NewSQL 数据库，TiDB 兼顾了传统关系型数据库的优秀特性以及 NoSQL 数据库可扩展性，以及跨数据中心（下文简称“中心”）场景下的高可用。本文档旨在介绍跨数据中心部署的不同解决方案。 - -## 三中心部署方案 - -TiDB, TiKV, PD 分别分布在 3 个不同的中心，这是最常规，可用性最高的方案。 - -![三中心部署](/media/deploy-3dc.png) - -### 优点 - -所有数据的副本分布在三个数据中心，任何一个数据中心失效后，另外两个数据中心会自动发起 leader election，并在合理长的时间内（通常情况 20s 以内）恢复服务，并且不会产生数据丢失。 - -![三中心部署容灾](/media/deploy-3dc-dr.png) - -### 缺点 - -性能受网络延迟影响。 - -- 对于写入的场景，所有写入的数据需要同步复制到至少 2 个数据中心，由于 TiDB 写入过程使用两阶段提交，故写入延迟至少需要 2 倍数据中心间的延迟。 -- 对于读请求来说，如果数据 leader 与发起读取的 TiDB 节点不在同一个数据中心，也会受网络延迟影响。 -- TiDB 中的每个事务都需要向 PD leader 获取 TSO，当 TiDB 与 PD leader 不在同一个数据中心时，它上面运行的事务也会因此受网络延迟影响，每个有写入的事务会获取两次 TSO。 - -### 读性能优化 - -如果不需要每个数据中心同时对外提供服务，可以将业务流量全部派发到一个数据中心，并通过调度策略把 Region leader 和 PD leader 都迁移到同一个数据中心（我们在上文所述的测试中也做了这个优化）。这样一来，不管是从 PD 获取 TSO 还是读取 Region 都不受数据中心间网络的影响。当该数据中心失效后，PD leader 和 Region leader 会自动在其它数据中心选出，只需要把业务流量转移至其他存活的数据中心即可。 - -![三中心部署读性能优化](/media/deploy-3dc-optimize.png) - -## 两地三中心部署方案 - -两地三中心的方案与三数据中心类似，算是三机房方案根据业务特点进行的优化，区别是其中有两个数据中心距离很近（通常在同一个城市），网络延迟相对很小。这种场景下，我们可以把业务流量同时派发到同城的两个数据中心，同时控制 Region leader 和 PD leader 也分布在同城的两个数据中心。 - -![两地三中心部署方案](/media/deploy-2city3dc.png) - -与三数据中心方案相比，两地三中心有以下优势： - -- 写入速度更优 -- 两中心同时提供服务资源利用率更高 -- 依然能保证任何一个数据中心失效后保持可用并且不发生数据丢失 - -但是，缺陷是如果同城的两个数据中心同时失效（理论上讲要高于异地三数据中心损失 2 个的概率），将会导致不可用以及部分数据丢失。 - -## 两数据中心 + binlog 同步方案 - -两数据中心 + binlog 同步类似于传统的 MySQL 中 master/slave 方案。两个数据中心分别部署一套完整的 TiDB 集群，我们称之为主集群和从集群。正常情况下所有的请求都在主集群，写入的数据通过 binlog 异步同步至从集群并写入。 - -![binlog 同步部署方案](/media/deploy-binlog.png) - -当主集群整个数据中心失效后，业务可以切换至从集群，与 MySQL 类似，这种情况下会有一些数据缺失。对比 MySQL，这个方案的优势是数据中心内的 HA -- 少部分节点故障时，通过重新选举 leader 自动恢复服务，不需要人工干预。 - -![两中心 binlog 相互备份方案](/media/deploy-backup.png) - -另外部分用户采用这种方式做双数据中心多活，两个数据中心各有一个集群，将业务分为两个库，每个库服务一部分数据，每个数据中心的业务只会访问一个库，两个集群之间通过 binlog 将本数据中心业务所涉及的库中的数据变更同步到对端机房，形成环状备份。 - -> **注意：** -> -> 在两数据中心 + binlog 同步部署方案中，数据中心之间只有 binlog 异步复制。在数据中心间的延迟较高的情况下，从集群落后主集群的数据量会增大。当主集群故障后（DR），会造成数据丢失，丢失的数据量受网络延迟等因素影响。 - -## 高可用和容灾分析 - -对于三数据中心方案和两地三中心方案，我们能得到的保障是任意一个数据中心故障时，集群能自动恢复服务，不需要人工介入，并能保证数据一致性。注意各种调度策略都是用于帮助性能优化的，当发生故障时调度机制总是第一优先考虑可用性而不是性能。 - -对于两数据中心 + binlog 同步的方案，主集群内少量节点故障时也能自动恢复服务，不需要人工介入，并能保证数据一致性。当整个主集群故障时，需要人工切换至从集群，并可能发生一些数据丢失，数据丢失的数量取决于同步延迟，和网络条件有关。 diff --git a/v2.1/how-to/deploy/hardware-recommendations.md b/v2.1/how-to/deploy/hardware-recommendations.md deleted file mode 100644 index 6db10992bcb1..000000000000 --- a/v2.1/how-to/deploy/hardware-recommendations.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: TiDB 软件和硬件环境建议配置 -category: how-to ---- - -# TiDB 软件和硬件环境建议配置 - -## 概述 - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 - -## Linux 操作系统版本要求 - -| Linux 操作系统平台 | 版本 | -| :----------------------- | :----------: | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | -| Ubuntu LTS | 16.04 及以上 | - -> **注意：** -> -> - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 -> - TiDB 在 CentOS 7.3 的环境下进行过大量的测试，同时社区也有很多该操作系统部署的最佳实践，因此，建议使用 CentOS 7.3 以上的 Linux 操作系统来部署 TiDB。 -> - 以上 Linux 操作系统可运行在物理服务器以及 VMware、KVM、XEN 主流虚拟化环境上。 - -## 服务器建议配置 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -### 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | 无特殊要求 | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 4核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | - -> **注意：** -> -> - 验证测试环境中的 TiDB 和 PD 可以部署在同一台服务器上。 -> - 如进行性能相关的测试，避免采用低性能存储和网络硬件配置，防止对测试结果的正确性产生干扰。 -> - TiKV 的 SSD 盘推荐使用 NVME 接口以保证读写更快。 -> - 如果仅验证功能，建议使用 [Docker Compose 部署方案](/v2.1/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 -> - TiDB 对于磁盘的使用以存放日志为主，因此在测试环境中对于磁盘类型和容量并无特殊要求。 - -### 生产环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 32 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 4核+ | 8 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 32 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | - -> **注意：** -> -> - 生产环境中的 TiDB 和 PD 可以部署和运行在同服务器上，如对性能和可靠性有更高的要求，应尽可能分开部署。 -> - 生产环境强烈推荐使用更高的配置。 -> - TiKV 硬盘大小配置建议 PCI-E SSD 不超过 2 TB，普通 SSD 不超过 1.5 TB。 - -## 网络要求 - -TiDB 作为开源分布式 NewSQL 数据库，其正常运行需要网络环境提供如下的网络端口配置要求，管理员可根据实际环境中 TiDB 组件部署的方案，在网络侧和主机侧开放相关端口： - -| 组件 | 默认端口 | 说明 | -| :-- | :-- | :-- | -| TiDB | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | 20160 | TiKV 通信端口 | -| PD | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | 2380 | PD 集群节点间通信端口 | -| Pump | 8250 | Pump 通信端口 | -| Drainer | 8249 | Drainer 通信端口 | -| Prometheus | 9090 | Prometheus 服务通信端口 | -| Pushgateway | 9091 | TiDB，TiKV，PD 监控聚合和上报端口 | -| Node_exporter | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | 9308 | Kafka_exporter 通信端口，用于监控 binlog kafka 集群 | - -## 客户端 Web 浏览器要求 - -TiDB 提供了基于 [Grafana](https://grafana.com/) 的技术平台，对数据库集群的各项指标进行可视化展现。采用支持 Javascript 的微软 IE、Google Chrome、Mozilla Firefox 的较新版本即可访问监控入口。 diff --git a/v2.1/how-to/deploy/orchestrated/ansible.md b/v2.1/how-to/deploy/orchestrated/ansible.md deleted file mode 100644 index a2e4df343f7b..000000000000 --- a/v2.1/how-to/deploy/orchestrated/ansible.md +++ /dev/null @@ -1,963 +0,0 @@ ---- -title: 使用 TiDB Ansible 部署 TiDB 集群 -category: how-to ---- - -# 使用 TiDB Ansible 部署 TiDB 集群 - -## 概述 - -Ansible 是一款自动化运维工具，[TiDB Ansible](https://github.com/pingcap/tidb-ansible) 是 PingCAP 基于 Ansible playbook 功能编写的集群部署工具。本文档介绍如何使用 TiDB Ansible 部署一个完整的 TiDB 集群。 - -本部署工具可以通过配置文件设置集群拓扑，完成以下各项运维工作： - -- 初始化操作系统参数 -- 部署 TiDB 集群（包括 PD、TiDB、TiKV 等组件和监控组件） -- [启动集群](/v2.1/how-to/maintain/ansible-operations.md#启动集群) -- [关闭集群](/v2.1/how-to/maintain/ansible-operations.md#关闭集群) -- [变更组件配置](/v2.1/how-to/upgrade/from-previous-version.md#编辑-tidb-集群组件配置文件) -- [集群扩容缩容](/v2.1/how-to/scale/with-ansible.md) -- [升级组件版本](/v2.1/how-to/upgrade/from-previous-version.md#滚动升级-tidb-集群组件) -- [集群开启 binlog](/v2.1/reference/tidb-binlog/overview.md) -- [清除集群数据](/v2.1/how-to/maintain/ansible-operations.md#清除集群数据) -- [销毁集群](/v2.1/how-to/maintain/ansible-operations.md#销毁集群) - -> **注意：** -> -> 对于生产环境，须使用 TiDB Ansible 部署 TiDB 集群。如果只是用于测试 TiDB 或体验 TiDB 的特性，建议[使用 Docker Compose 在单机上快速部署 TiDB 集群](/v2.1/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -## 准备机器 - -1. 部署目标机器若干 - - - 建议 4 台及以上，TiKV 至少 3 实例，且与 TiDB、PD 模块不位于同一主机，详见[部署建议](/v2.1/how-to/deploy/hardware-recommendations.md)。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统，x86_64 架构 (amd64)。 - - 机器之间内网互通。 - - > **注意：** - > - > 使用 Ansible 方式部署时，TiKV 及 PD 节点数据目录所在磁盘请使用 SSD 磁盘，否则无法通过检测。** 如果仅验证功能，建议使用 [Docker Compose 部署方案](/v2.1/how-to//get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 - -2. 部署中控机一台 - - - 中控机可以是部署目标机器中的某一台。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统（默认包含 Python 2.7）。 - - 该机器需开放外网访问，用于下载 TiDB 及相关软件安装包。 - -## 第 1 步：在中控机上安装系统依赖包 - -以 `root` 用户登录中控机，然后根据操作系统类型执行相应的安装命令。 - -- 如果中控机使用的是 CentOS 7 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && \ - yum -y install python2-pip - ``` - -- 如果中控机使用的是 Ubuntu 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH key - -以 `root` 用户登录中控机，执行以下步骤： - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 设置 `tidb` 用户密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 配置 `tidb` 用户 sudo 免密码，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾即可。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH key。 - - 执行 `su` 命令，从 `root` 用户切换到 `tidb` 用户下。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 创建 `tidb` 用户 SSH key，提示 `Enter passphrase` 时直接回车即可。执行成功后，SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为 `/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录。以下为 tidb-ansible 与 TiDB 的版本对应关系，版本选择可以咨询官方。 - -| TiDB 版本 | tidb-ansible tag | 说明 | -| :-------- | :---------------- | :--- | -| 2.0 版本 | v2.0.10、v2.0.11 | 2.0 稳定版本，新用户不建议用于生产环境 | -| 2.1 版本 | v2.1.1 ~ v2.1.13 等 | 2.1 稳定版本，可用于生产环境 | - -使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 2.0 或者 2.1 [相应 TAG 版本](https://github.com/pingcap/tidb-ansible/tags)，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone -b $tag https://github.com/pingcap/tidb-ansible.git -``` - -> **注意：** -> -> - `$tag` 替换为选定的 TAG 版本的值，例如 `v2.1.15`。 -> - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 -> - 请务必按文档操作，将 `tidb-ansible` 下载到 `/home/tidb` 目录下，权限为 `tidb` 用户，不要下载到 `/root` 下，否则会遇到权限问题。 - -## 第 4 步：在中控机器上安装 Ansible 及其依赖 - -以 `tidb` 用户登录中控机，请务必按以下方式通过 `pip` 安装 Ansible 及其相关依赖的指定版本，否则会有兼容问题。目前，release-2.0、release-2.1 及最新开发版本兼容 Ansible 2.4 ~ 2.7.11 (2.4 ≤ Ansible ≤ 2.7.11)。 - -1. 在中控机器上安装 Ansible 及其依赖。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - sudo pip install -r ./requirements.txt - ``` - - Ansible 及相关依赖的版本信息记录在 `tidb-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 的版本。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ansible 2.5.0 - ``` - -## 第 5 步：在中控机上配置部署机器 SSH 互信及 sudo 规则 - -以 `tidb` 用户登录中控机，然后执行以下步骤： - -1. 将你的部署目标机器 IP 添加到 `hosts.ini` 文件的 `[servers]` 区块下。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - vi hosts.ini - ``` - - ```ini - [servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - - [all:vars] - username = tidb - ntp_server = pool.ntp.org - ``` - -2. 执行以下命令，按提示输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ``` - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，并配置 sudo 规则，配置中控机与部署目标机器之间的 SSH 互信。 - -如果要手工配置 SSH 互信及 sudo 免密码，可参考[如何手工配置 ssh 互信及 sudo 免密码](#如何手工配置-ssh-互信及-sudo-免密码)。 - -## 第 6 步：在部署目标机器上安装 NTP 服务 - -> **注意：** -> -> 如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略。可参考[如何检测 NTP 服务是否正常](#如何检测-ntp-服务是否正常)。 - -以 `tidb` 用户登录中控机，执行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/tidb-ansible && \ -ansible-playbook -i hosts.ini deploy_ntp.yml -u tidb -b -``` - -该步骤将在部署目标机器上使用系统自带软件源联网安装并启动 NTP 服务，服务使用安装包默认的 NTP server 列表，见配置文件 `/etc/ntp.conf` 中 server 参数。如果使用默认的 NTP server，你的机器需要连接外网。 - -为了让 NTP 尽快开始同步，启动 NTP 服务前，系统会执行 `ntpdate` 命令，与用户在 `hosts.ini` 文件中指定的 `ntp_server` 同步日期与时间。默认的服务器为 `pool.ntp.org`，也可替换为你的 NTP server。 - -## 第 7 步：在部署目标机器上配置 CPUfreq 调节器模式 - -为了让 CPU 发挥最大性能，请将 CPUfreq 调节器模式设置为 `performance` 模式。如需了解 CPUfreq 的更多信息，可查看[使用 CPUFREQ 调控器](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/power_management_guide/cpufreq_governors#cpufreq_setup)文档。 - -### 查看系统支持的调节器模式 - -执行以下 `cpupower` 命令，可查看系统支持的调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: performance powersave -``` - -> **注意：** -> -> 本例中系统支持设置 `performance` 和 `powersave` 模式。如果返回 `Not Available`，表示当前系统不支持配置 CPUfreq，跳过该步骤即可。 - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: Not Available -``` - -### 查看系统当前的 CPUfreq 调节器模式 - -执行以下 `cpupower` 命令，可查看系统当前的 CPUfreq 调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --policy -``` - -``` -analyzing CPU 0: - current policy: frequency should be within 1.20 GHz and 3.20 GHz. - The governor "powersave" may decide which speed to use - within this range. -``` - -如上述代码所示，本例中的当前配置是 `powersave` 模式。 - -### 修改调节器模式 - -你可以通过以下两种方法来修改调节器模式。本例中，当前调节器模式为 `powersave`，以下命令会将模式变更为 `performance`。 - -- 使用 `cpupower frequency-set --governor` 命令来修改。 - - {{< copyable "shell-root" >}} - - ```bash - cpupower frequency-set --governor performance - ``` - -- 使用以下命令在部署目标机器上批量设置。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i hosts.ini all -m shell -a "cpupower frequency-set --governor performance" -u tidb -b - ``` - -## 第 8 步：在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -使用 `root` 用户登录目标机器，将部署目标机器数据盘格式化成 ext4 文件系统，挂载时添加 `nodelalloc` 和 `noatime` 挂载参数。`nodelalloc` 是必选参数，否则 Ansible 安装时检测无法通过；`noatime` 是可选建议参数。 - -> **注意：** -> -> 如果你的数据盘已经格式化成 ext4 并挂载了磁盘，可先执行 `umount /dev/nvme0n1p1` 命令卸载，从编辑 `/etc/fstab` 文件步骤开始执行，添加挂载参数重新挂载即可。 - -以 `/dev/nvme0n1` 数据盘为例，具体操作步骤如下： - -1. 查看数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - fdisk -l - ``` - - ``` - Disk /dev/nvme0n1: 1000 GB - ``` - -2. 创建分区表。 - - {{< copyable "shell-root" >}} - - ```bash - parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1 - ``` - - > **注意：** - > - > 使用 `lsblk` 命令查看分区的设备号：对于 nvme 磁盘，生成的分区设备号一般为 `nvme0n1p1`；对于普通磁盘（例如 `/dev/sdb`），生成的的分区设备号一般为 `sdb1`。 - -3. 格式化文件系统。 - - {{< copyable "shell-root" >}} - - ```bash - mkfs.ext4 /dev/nvme0n1p1 - ``` - -4. 查看数据盘分区 UUID。 - - 本例中 `nvme0n1p1` 的 UUID 为 `c51eb23b-195c-4061-92a9-3fad812cc12f`。 - - {{< copyable "shell-root" >}} - - ```bash - lsblk -f - ``` - - ``` - NAME FSTYPE LABEL UUID MOUNTPOINT - sda - ├─sda1 ext4 237b634b-a565-477b-8371-6dff0c41f5ab /boot - ├─sda2 swap f414c5c0-f823-4bb1-8fdf-e531173a72ed - └─sda3 ext4 547909c1-398d-4696-94c6-03e43e317b60 / - sr0 - nvme0n1 - └─nvme0n1p1 ext4 c51eb23b-195c-4061-92a9-3fad812cc12f - ``` - -5. 编辑 `/etc/fstab` 文件，添加 `nodelalloc` 挂载参数。 - - {{< copyable "shell-root" >}} - - ```bash - vi /etc/fstab - ``` - - ``` - UUID=c51eb23b-195c-4061-92a9-3fad812cc12f /data1 ext4 defaults,nodelalloc,noatime 0 2 - ``` - -6. 挂载数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - mkdir /data1 && \ - mount -a - ``` - -7. 执行以下命令，如果文件系统为 ext4，并且挂载参数中包含 `nodelalloc`，则表示已生效。 - - {{< copyable "shell-root" >}} - - ```bash - mount -t ext4 - ``` - - ``` - /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered) - ``` - -## 第 9 步：编辑 `inventory.ini` 文件，分配机器资源 - -以 `tidb` 用户登录中控机，编辑 `/home/tidb/tidb-ansible/inventory.ini` 文件为 TiDB 集群分配机器资源。一个标准的 TiDB 集群需要 6 台机器：2 个 TiDB 实例，3 个 PD 实例，3 个 TiKV 实例。 - -- 至少需部署 3 个 TiKV 实例。 -- 不要将 TiKV 实例与 TiDB 或 PD 实例混合部署在同一台机器上。 -- 将第一台 TiDB 机器同时用作监控机。 - -> **注意：** -> -> 请使用内网 IP 来部署集群，如果部署目标机器 SSH 端口非默认的 22 端口，需添加 `ansible_port` 变量，如 `TiDB1 ansible_host=172.16.10.1 ansible_port=5555`。 - -你可以根据实际场景从以下两种集群拓扑中选择一种： - -- [单机单 TiKV 实例集群拓扑](#单机单-tikv-实例集群拓扑) - - 默认情况下，建议在每个 TiKV 节点上仅部署一个 TiKV 实例，以提高性能。但是，如果你的 TiKV 部署机器的 CPU 和内存配置是[部署建议](/v2.1/how-to/deploy/hardware-recommendations.md)的两倍或以上，并且一个节点拥有两块 SSD 硬盘或者单块 SSD 硬盘的容量大于 2 TB，则可以考虑部署两实例，但不建议部署两个以上实例。 - -- [单机多 TiKV 实例集群拓扑](#单机多-tikv-实例集群拓扑) - -### 单机单 TiKV 实例集群拓扑 - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -[tikv_servers] -172.16.10.4 -172.16.10.5 -172.16.10.6 - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 -``` - -### 单机多 TiKV 实例集群拓扑 - -以两实例为例： - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1-1, TiKV1-2 | -| node5 | 172.16.10.5 | TiKV2-1, TiKV2-2 | -| node6 | 172.16.10.6 | TiKV3-1, TiKV3-2 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -# 注意：要使用 TiKV 的 labels，必须同时配置 PD 的 location_labels 参数，否则 labels 设置不生效。 -[tikv_servers] -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv1" -TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv1" -TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv2" -TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv2" -TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv3" -TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv3" - -# 部署 3.0 版本的 TiDB 集群时，多实例场景需要额外配置 status 端口，示例如下： -# TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" -# TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" -# TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" -# TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" -# TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" -# TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 - -# 注意：为使 TiKV 的 labels 设置生效，部署集群时必须设置 PD 的 location_labels 参数。 -[pd_servers:vars] -location_labels = ["host"] -``` - -- 服务配置文件参数调整 - - 1. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中的 `block-cache-size` 参数： - - - `rocksdb defaultcf block-cache-size(GB)` = MEM \* 80% / TiKV 实例数量 \* 30% - - `rocksdb writecf block-cache-size(GB)` = MEM \* 80% / TiKV 实例数量 \* 45% - - `rocksdb lockcf block-cache-size(GB)` = MEM \* 80% / TiKV 实例数量 \* 2.5% (最小 128 MB) - - `raftdb defaultcf block-cache-size(GB)` = MEM \* 80% / TiKV 实例数量 \* 2.5% (最小 128 MB) - - 2. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ```yaml - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 推荐配置：实例数 \* 参数值 = CPU 核数 * 0.8。 - - 3. 如果多个 TiKV 实例部署在同一块物理磁盘上，需要修改 `conf/tikv.yml` 中的 `capacity` 参数： - - ```yaml - raftstore: - capacity: 0 - ``` - - > **注意：** - > - > 推荐配置：`capacity` = 磁盘总容量 / TiKV 实例数量，例如：`capacity: "100GB"`。 - -### 第 10 步：调整 `inventory.ini` 文件中的变量 - -本小节介绍如何编辑部署目录的变量和 `inventory.ini` 文件中的其它变量。 - -### 调整部署目录 - -部署目录通过 `deploy_dir` 变量控制，默认全局变量已设置为 `/home/tidb/deploy`，对所有服务生效。如数据盘挂载目录为 `/data1`，可设置为 `/data1/deploy`，样例如下： - -```ini -## Global variables -[all:vars] -deploy_dir = /data1/deploy -``` - -如为某一服务单独设置部署目录，可在配置服务主机列表时配置主机变量，以 TiKV 节点为例，其他服务类推，请务必添加第一列别名，以免服务混布时混淆。 - -```ini -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy -``` - -### 调整其它变量（可选） - -> **注意：** -> -> 以下控制变量开启请使用首字母大写 `True`，关闭请使用首字母大写 `False`。 - -| 变量 | 含义 | -| :--------------- | :---------------------------------------------------------- | -| `cluster_name` | 集群名称，可调整 | -| `tidb_version` | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| `process_supervision` | 进程监管方式，默认为 `systemd`，可选 `supervise` | -| `timezone` | 新安装 TiDB 集群第一次启动 bootstrap（初始化）时，将 TiDB 全局默认时区设置为该值。TiDB 使用的时区后续可通过 `time_zone` 全局变量和 session 变量来修改，参考[时区支持](/v2.1/how-to/configure/time-zone.md)。默认为 `Asia/Shanghai`，可选值参考 [timzone 列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。 | -| `enable_firewalld` | 开启防火墙，默认不开启，如需开启，请将[部署建议-网络要求](/v2.1/how-to/deploy/hardware-recommendations.md#网络要求) 中的端口加入白名单 | -| `enable_ntpd` | 检测部署目标机器 NTP 服务，默认为 `True`，请勿关闭 | -| `set_hostname` | 根据 IP 修改部署目标机器主机名，默认为 `False` | -| `enable_binlog` | 是否部署 Pump 并开启 binlog，默认为 `False`，依赖 Kafka 集群，参见 `zookeeper_addrs` 变量 | -| `zookeeper_addrs` | binlog Kafka 集群的 zookeeper 地址 | -| `enable_slow_query_log` | TiDB 慢查询日志记录到单独文件 `{{ deploy_dir }}/log/tidb_slow_query.log`，默认为 `False`，记录到 TiDB 日志 | -| `deploy_without_tidb` | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 `inventory.ini` 文件中 `tidb_servers` 主机组 IP 设置为空。| -| `alertmanager_target` | 可选：如果你已单独部署 alertmanager，可配置该变量，格式：`alertmanager_host:alertmanager_port` | -| `grafana_admin_user` | Grafana 管理员帐号用户名，默认为 admin | -| `grafana_admin_password` | Grafana 管理员帐号密码，默认为 admin，用于 Ansible 导入 Dashboard 和创建 API Key，如后期通过 grafana web 修改了密码，请更新此变量 | -| `collect_log_recent_hours` | 采集日志时，采集最近几个小时的日志，默认为 2 小时 | -| `enable_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时，是否限速，默认为 `True`，与 `collect_bandwidth_limit` 变量结合使用 | -| `collect_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时限速多少，单位: Kbit/s，默认 10000，即 10Mb/s，如果是单机多 TiKV 实例部署方式，需除以单机实例个数 | -| `prometheus_storage_retention` | Prometheus 监控数据的保留时间（默认为 30 天）；2.1.7、3.0 以及之后的 tidb-ansible 版本中，`group_vars/monitoring_servers.yml` 文件里新增的配置 | - -## 第 11 步：部署 TiDB 集群 - -`ansible-playbook` 执行 Playbook 时，默认并发为 5。部署目标机器较多时，可添加 `-f` 参数指定并发数，例如 `ansible-playbook deploy.yml -f 10`。以下示例使用 `tidb` 用户作为服务运行用户： - -1. 在 `tidb-ansible/inventory.ini` 文件中，确认 `ansible_user = tidb`。 - - ```ini - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - > **注意：** - > - > 不要将 `ansible_user` 设置为 `root` 用户，因为 `tidb-ansible` 限制了服务以普通用户运行。 - - 执行以下命令，如果所有 server 均返回 `tidb`，表示 SSH 互信配置成功： - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 执行以下命令，如果所有 server 均返回 `root`，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到中控机。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -3. 初始化系统环境，修改内核参数。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml - ``` - -4. 部署 TiDB 集群软件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - - > **注意：** - > - > Grafana Dashboard 上的 **Report** 按钮可用来生成 PDF 文件，此功能依赖 `fontconfig` 包和英文字体。如需使用该功能，登录 **grafana_servers** 机器，用以下命令安装： - > - > {{< copyable "shell-regular" >}} - > - > ```bash - > sudo yum install fontconfig open-sans-fonts - > ``` - -5. 启动 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - -## 测试集群 - -TiDB 兼容 MySQL，因此可使用 MySQL 客户端直接连接 TiDB。推荐配置负载均衡以提供统一的 SQL 接口。 - -1. 使用 MySQL 客户端连接 TiDB 集群。TiDB 服务的默认端口为 `4000`。 - - {{< copyable "sql" >}} - - ```sql - mysql -u root -h 172.16.10.1 -P 4000 - ``` - -2. 通过浏览器访问监控平台。 - - - 地址： - - 默认帐号与密码：`admin`；`admin` - -## 常见部署问题 - -本小节介绍使用 Ansible 部署 TiDB 集群过程中的常见问题与解决方案。 - -### 如何自定义端口 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 端口变量 | 默认端口 | 说明 | -| :-- | :-- | :-- | :-- | -| TiDB | tidb_port | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | tidb_status_port | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | tikv_port | 20160 | TiKV 通信端口 | -| TiKV | tikv_status_port | 20180 | 上报 TiKV 状态的通信端口 | -| PD | pd_client_port | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | pd_peer_port | 2380 | PD 集群节点间通信端口 | -| Pump | pump_port | 8250 | Pump 通信端口 | -| Prometheus | prometheus_port | 9090 | Prometheus 服务通信端口 | -| Pushgateway | pushgateway_port | 9091 | TiDB， TiKV， PD 监控聚合和上报端口 | -| Node_exporter | node_exporter_port | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | blackbox_exporter_port | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | grafana_port | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | grafana_collector_port | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | kafka_exporter_port | 9308 | Kafka_exporter 通信端口，用于监控 binlog Kafka 集群 | - -### 如何自定义部署目录 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 目录变量 | 默认目录 | 说明 | -| :-- | :-- | :-- | :-- | -| 全局 | deploy_dir | /home/tidb/deploy | 部署目录 | -| TiDB | tidb_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_data_dir | {{ deploy_dir }}/data | 数据目录 | -| TiKV | wal_dir | "" | rocksdb write-ahead 日志目录，为空时与 TiKV 数据目录一致 | -| TiKV | raftdb_path | "" | raftdb 目录，为空时为 tikv_data_dir/raft | -| PD | pd_log_dir | {{ deploy_dir }}/log | 日志目录 | -| PD | pd_data_dir | {{ deploy_dir }}/data.pd | 数据目录 | -| pump | pump_log_dir | {{ deploy_dir }}/log | 日志目录 | -| pump | pump_data_dir | {{ deploy_dir }}/data.pump | 数据目录 | -| prometheus | prometheus_log_dir | {{ deploy_dir }}/log | 日志目录 | -| prometheus | prometheus_data_dir | {{ deploy_dir }}/data.metrics | 数据目录 | -| pushgateway | pushgateway_log_dir | {{ deploy_dir }}/log | 日志目录 | -| node_exporter | node_exporter_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_data_dir | {{ deploy_dir }}/data.grafana | 数据目录 | - -### 如何检测 NTP 服务是否正常 - -1. 执行以下命令，如果输出 `running` 表示 NTP 服务正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl status ntpd.service - ``` - - ``` - ntpd.service - Network Time Service - Loaded: loaded (/usr/lib/systemd/system/ntpd.service; disabled; vendor preset: disabled) - Active: active (running) since 一 2017-12-18 13:13:19 CST; 3s ago - ``` - -2. 执行 `ntpstat` 命令，如果输出 `synchronised to NTP server`（正在与 NTP server 同步），表示在正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - synchronised to NTP server (85.199.214.101) at stratum 2 - time correct to within 91 ms - polling server every 1024 s - ``` - -> **注意：** -> -> Ubuntu 系统需安装 `ntpstat` 软件包。 - -- 以下情况表示 NTP 服务未正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - unsynchronised - ``` - -- 以下情况表示 NTP 服务未正常运行： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - Unable to talk to NTP daemon. Is it running? - ``` - -- 如果要使 NTP 服务尽快开始同步，执行以下命令。可以将 `pool.ntp.org` 替换为你的 NTP server： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl stop ntpd.service && \ - sudo ntpdate pool.ntp.org && \ - sudo systemctl start ntpd.service - ``` - -- 如果要在 CentOS 7 系统上手动安装 NTP 服务，可执行以下命令： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install ntp ntpdate && \ - sudo systemctl start ntpd.service && \ - sudo systemctl enable ntpd.service - ``` - -### 如何调整进程监管方式从 supervise 到 systemd - -{{< copyable "shell-root" >}} - -```shell -process supervision, [systemd, supervise] -``` - -``` -process_supervision = systemd -``` - -TiDB Anisble 在 TiDB v1.0.4 版本之前进程监管方式默认为 `supervise`。之前安装的集群可保持不变，如需更新为 `systemd`，需关闭集群，按以下方式变更： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml && \ -ansible-playbook deploy.yml -D && \ -ansible-playbook start.yml -``` - -### 如何手工配置 SSH 互信及 sudo 免密码 - -1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 - - {{< copyable "shell-root" >}} - - ```bash - useradd tidb && \ - passwd tidb - ``` - -2. 执行以下命令，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾，即配置好 sudo 免密码。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -3. 以 `tidb` 用户登录到中控机，执行以下命令。将 `172.16.10.61` 替换成你的部署目标机器 IP，按提示输入部署目标机器 `tidb` 用户密码，执行成功后即创建好 SSH 互信，其他机器同理。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-copy-id -i ~/.ssh/id_rsa.pub 172.16.10.61 - ``` - -4. 以 `tidb` 用户登录到中控机，通过 `ssh` 的方式登录目标机器 IP。如果不需要输入密码并登录成功，即表示 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh 172.16.10.61 - ``` - - ``` - [tidb@172.16.10.61 ~]$ - ``` - -5. 以 `tidb` 用户登录到部署目标机器后，执行以下命令，不需要输入密码并切换到 `root` 用户，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - sudo -su root - ``` - - ``` - [root@172.16.10.61 tidb]# - ``` - -### You need to install jmespath prior to running json_query filter 报错 - -1. 请参照[在中控机器上安装 Ansible 及其依赖](#在中控机器上安装-ansible-及其依赖) 在中控机上通过 `pip` 安装 Ansible 及相关依赖的指定版本，默认会安装 `jmespath`。 - -2. 执行以下命令，验证 `jmespath` 是否安装成功： - - {{< copyable "shell-regular" >}} - - ```bash - pip show jmespath - ``` - - ``` - Name: jmespath - Version: 0.9.0 - ``` - -3. 在中控机上 Python 交互窗口里 `import jmespath`。 - - - 如果没有报错，表示依赖安装成功。 - - 如果有 `ImportError: No module named jmespath` 报错，表示未成功安装 Python `jmespath` 模块。 - - {{< copyable "shell-regular" >}} - - ```bash - python - ``` - - ``` - Python 2.7.5 (default, Nov 6 2016, 00:28:07) - [GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - ``` - - {{< copyable "shell-regular" >}} - - ```shell - import jmespath - ``` - -### 启动 Pump/Drainer 报 `zk: node does not exist` 错误 - -请检查 `inventory.ini` 里的 `zookeeper_addrs` 参数配置与 Kafka 集群内的配置是否相同、是否填写了命名空间。关于命名空间的配置说明如下： - -```ini -# ZooKeeper connection string (see ZooKeeper docs for details). -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes. Example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -``` diff --git a/v2.1/how-to/deploy/orchestrated/docker.md b/v2.1/how-to/deploy/orchestrated/docker.md deleted file mode 100644 index aecc2a1f5993..000000000000 --- a/v2.1/how-to/deploy/orchestrated/docker.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: TiDB Docker 部署方案 -category: how-to ---- - -# TiDB Docker 部署方案 - -本文介绍如何使用 Docker 部署一个多节点的 TiDB 集群。 - -> **注意：** -> -> 对于生产环境，不要使用 Docker 进行部署，而应[使用 Ansible 部署 TiDB 集群](/v2.1/how-to/deploy/orchestrated/ansible.md)。 - -## 环境准备 - -### 安装 Docker - -Docker 可以方便地在 Linux / Mac OS / Windows 平台安装，安装方法请参考 [Docker 官方文档](https://www.docker.com/products/docker)。 - -### 拉取 TiDB 的 Docker 镜像 - -部署 TiDB 集群主要包括 3 个服务组件: - -- TiDB -- TiKV -- PD - -对应的最新 Docker 镜像可以通过 [Docker 官方镜像仓库](https://hub.docker.com/u/pingcap) 获取： - -```bash -docker pull pingcap/tidb:latest -docker pull pingcap/tikv:latest -docker pull pingcap/pd:latest -``` - -## 部署一个多节点集群 - -假设我们打算在 6 台主机上部署一个 TiDB 集群: - -| 主机名 | IP | 部署服务 | 数据盘挂载 | -| --------- | ------------- | ---------- | ----- | -| host1 | 192.168.1.101 | PD1 & TiDB | /data | -| host2 | 192.168.1.102 | PD2 | /data | -| host3 | 192.168.1.103 | PD3 | /data | -| host4 | 192.168.1.104 | TiKV1 | /data | -| host5 | 192.168.1.105 | TiKV2 | /data | -| host6 | 192.168.1.106 | TiKV3 | /data | - -### 启动 PD - -登录 **host1** 执行： - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host2** 执行： - -```bash -docker run -d --name pd2 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd2" \ - --data-dir="/data/pd2" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.102:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.102:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host3** 执行： - -```bash -docker run -d --name pd3 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd3" \ - --data-dir="/data/pd3" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.103:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.103:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -### 启动 TiKV - -登录 **host4** 执行： - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host5** 执行： - -```bash -docker run -d --name tikv2 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.105:20160" \ - --data-dir="/data/tikv2" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host6** 执行： - -```bash -docker run -d --name tikv3 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.106:20160" \ - --data-dir="/data/tikv3" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 启动 TiDB - -登录 **host1** 执行： - -```bash -docker run -d --name tidb \ - -p 4000:4000 \ - -p 10080:10080 \ - -v /etc/localtime:/etc/localtime:ro \ - pingcap/tidb:latest \ - --store=tikv \ - --path="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 使用 MySQL 标准客户端连接 TiDB 测试 - -登录 **host1** 并确保已安装 [MySQL 命令行客户端](http://dev.mysql.com/downloads/mysql/)，执行： - -```bash -$ mysql -h 127.0.0.1 -P 4000 -u root -D test -mysql> show databases; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -### 如何自定义配置文件 - -TiKV 和 PD 可以通过指定配置文件的方式来加载更加丰富的启动参数，用于性能调优。 - -假定配置文件在宿主机上的存放路径 `/path/to/config/pd.toml` 和 `/path/to/config/tikv.toml`。启动 Docker 时需要调整相应的启动参数，以 tikv1 和 pd1 为例： - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/tikv.toml:/tikv.toml:ro \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" \ - --config="/tikv.toml" -``` - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/pd.toml:/pd.toml:ro \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" \ - --config="/pd.toml" -``` diff --git a/v2.1/how-to/deploy/orchestrated/offline-ansible.md b/v2.1/how-to/deploy/orchestrated/offline-ansible.md deleted file mode 100644 index b6f1d7ed381e..000000000000 --- a/v2.1/how-to/deploy/orchestrated/offline-ansible.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: 离线 TiDB Ansible 部署方案 -category: how-to ---- - -# 离线 TiDB Ansible 部署方案 - -## 准备机器 - -1. 下载机一台 - - - 该机器需开放外网访问，用于下载 TiDB Ansible、TiDB 及相关软件安装包。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统。 - -2. 部署目标机器若干及部署中控机一台 - - - 系统要求及配置参考[准备机器](/v2.1/how-to/deploy/orchestrated/ansible.md#准备机器)。 - - 可以无法访问外网。 - -## 在中控机上安装系统依赖包 - -1. 在下载机上下载[系统依赖离线安装包](https://download.pingcap.org/ansible-system-rpms.el7.tar.gz)，然后上传至中控机。该离线包仅支持 CentOS 7 系统，包含 `pip` 及 `sshpass`。 - -2. 在中控机上安装系统依赖包： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-system-rpms.el7.tar.gz && - cd ansible-system-rpms.el7 && - chmod u+x install_ansible_system_rpms.sh && - ./install_ansible_system_rpms.sh - ``` - -3. 安装完成后，可通过 `pip -V` 验证 pip 是否安装成功： - - {{< copyable "shell-root" >}} - - ```bash - pip -V - ``` - - ``` - pip 8.1.2 from /usr/lib/python2.7/site-packages (python 2.7) - ``` - -> **注意：** -> -> 如果你的系统已安装 pip，请确认版本 >= 8.1.2，否则离线安装 ansible 及其依赖时，会有兼容问题。 - -## 在中控机上创建 tidb 用户，并生成 ssh key - -参考[在中控机上创建 tidb 用户，并生成 ssh key](/v2.1/how-to/deploy/orchestrated/ansible.md#第-2-步在中控机上创建-tidb-用户并生成-ssh-key) 即可。 - -## 在中控机器上离线安装 Ansible 及其依赖 - -以下是 CentOS 7 系统 Ansible 离线安装方式： - -建议使用 Ansible 2.4 至 2.7.11 版本，Ansible 及相关依赖版本记录在 `tidb-ansible/requirements.txt` 文件中。下面步骤以安装 Ansible 2.5 为例。 - -1. 在下载机上下载 [Ansible 2.5 离线安装包](https://download.pingcap.org/ansible-2.5.0-pip.tar.gz)，然后上传至中控机。 - -2. 离线安装 Ansible 及相关依赖： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-2.5.0-pip.tar.gz && - cd ansible-2.5.0-pip/ && - chmod u+x install_ansible.sh && - ./install_ansible.sh - ``` - -3. 安装完成后，可通过 `ansible --version` 查看版本： - - {{< copyable "shell-root" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 在下载机上下载 TiDB Ansible 及 TiDB 安装包 - -以下为 tidb-ansible 与 TiDB 的版本对应关系，版本选择可以咨询官方。 - -| TiDB 版本 | tidb-ansible tag | 备注 | -| -------- | ---------------- | --- | -| 2.0 版本 | v2.0.10、v2.0.11 | 2.0 稳定版本，新用户不建议用于生产环境 | -| 2.1 版本 | v2.1.x | 2.1 稳定版本，可用于生产环境 | - -1. 在下载机上安装 Ansible： - - 请按以下方式在 CentOS 7 系统的下载机上在线安装 Ansible。安装完成后，可通过 `ansible --version` 查看版本，请务必确认是 **Ansible 2.5.0** 版本，否则会有兼容问题。 - - {{< copyable "shell-root" >}} - - ```bash - yum install epel-release && - yum install ansible curl && - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -2. 下载 tidb-ansible： - - 使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 2.0 或者 2.1 [相应 TAG 版本](https://github.com/pingcap/tidb-ansible/tags)，默认的文件夹名称为 `tidb-ansible`。 - - {{< copyable "shell-regular" >}} - - ```bash - git clone -b $tag https://github.com/pingcap/tidb-ansible.git - ``` - - > **注意：** - > - > - 将 `$tag` 替换为选定的 TAG 版本的值，例如 `v2.1.15`。 - > - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 - -3. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到下载机： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-ansible && - ansible-playbook local_prepare.yml - ``` - -4. 将执行完以上命令之后的 `tidb-ansible` 文件夹拷贝到中控机 `/home/tidb` 目录下，文件属主权限需是 `tidb` 用户。 - -## 在中控机上配置部署机器 ssh 互信及 sudo 规则 - -参考[在中控机上配置部署机器 ssh 互信及 sudo 规则](/v2.1/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)即可。 - -## 在部署目标机器上安装 NTP 服务 - -如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略，可参考[如何检测 NTP 服务是否正常](/v2.1/how-to/deploy/orchestrated/ansible.md#如何检测-ntp-服务是否正常)。 - -参考[在部署目标机器上安装 NTP 服务](/v2.1/how-to/deploy/orchestrated/ansible.md#第-6-步在部署目标机器上安装-ntp-服务)即可。 - -## 在部署目标机器上配置 CPUfreq 调节器模式 - -参考[在部署目标机器上配置 CPUfreq 调节器模式](/v2.1/how-to/deploy/orchestrated/ansible.md#第-7-步在部署目标机器上配置-cpufreq-调节器模式)即可。 - -## 在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -参考[在部署目标机器上添加数据盘 ext4 文件系统挂载参数](/v2.1/how-to/deploy/orchestrated/ansible.md#第-8-步在部署目标机器上添加数据盘-ext4-文件系统挂载参数)即可。 - -## 分配机器资源，编辑 inventory.ini 文件 - -参考[分配机器资源，编辑 inventory.ini 文件](/v2.1/how-to/deploy/orchestrated/ansible.md#第-9-步编辑-inventoryini-文件分配机器资源)即可。 - -## 部署任务 - -1. `ansible-playbook local_prepare.yml` 该 playbook 不需要再执行。 - -2. Grafana Dashboard 上的 Report 按钮可用来生成 PDF 文件，此功能依赖 `fontconfig` 包及英文字体，如需使用该功能，请下载 [font 离线安装包](https://download.pingcap.org/grafana-font-rpms.el7.tar.gz)上传至 **grafana_servers** 机器上安装。该离线包仅支持 CentOS 7 系统，包含 `fontconfig` 及 `open-sans-fonts`。 - - {{< copyable "shell-regular" >}} - - ```bash - tar -xzvf grafana-font-rpms.el7.tar.gz && - cd grafana-font-rpms.el7 && - chmod u+x install_grafana_font_rpms.sh && - ./install_grafana_font_rpms.sh - ``` - -3. 参考[部署任务](/v2.1/how-to/deploy/orchestrated/ansible.md#第-11-步部署-tidb-集群)即可。 - -## 测试集群 - -参考[测试集群](/v2.1/how-to/deploy/orchestrated/ansible.md#测试集群)即可。 diff --git a/v2.1/how-to/get-started/data-migration.md b/v2.1/how-to/get-started/data-migration.md deleted file mode 100644 index 959a4ae04037..000000000000 --- a/v2.1/how-to/get-started/data-migration.md +++ /dev/null @@ -1,459 +0,0 @@ ---- -title: TiDB Data Migration 教程 -category: how-to ---- - -# TiDB Data Migration 教程 - -TiDB Data Migration (DM) 是一体化的数据同步任务管理平台，支持将大量、复杂的生产环境中的数据从 MySQL 或 MariaDB 迁移到 TiDB。 - -DM 功能如下： - -- 数据迁移 - - 支持导出与导入源数据库的初始全量数据，并在数据迁移过程中读取、应用来自源数据库存储的 binlog，从而保持数据的同步。 - - 通过合并上游的多个 MySQL 或 MariaDB 实例或集群的表，DM 能迁移生产环境中的分库分表。 -- 将 TiDB 作为 MySQL 或 MariaDB 的从库时，DM 能持续提高数据库水平扩展的能力，或在无需 ETL 作业的情况下，在 TiDB 上进行数据实时分析。 - -本教程主要介绍如何使用 DM 迁移上游多个 MySQL 实例的一个分片表。包括两种场景： - -- 合并若干个互不冲突的表或分片，即这些表或分片的表结构并不会造成唯一键的冲突； -- 合并唯一键存在冲突的表。 - -本教程假设目前使用的是一台新的、纯净版 CentOS 7 实例，你能（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为需要运行多个服务，建议内存最好在 1 GB 以上。 - -> **警告：** -> -> 本教程中 TiDB 的部署方法并**不适用**于生产或开发环境。 - -## Data Migration 架构 - -![TiDB Data Migration 架构](/media/dm-architecture.png) - -TiDB Data Migration 平台由 3 部分组成：DM-master、DM-worker 和 dmctl。 - -* DM-master 负责管理和调度数据同步任务的操作。 -* DM-worker 负责执行特定的数据同步任务。 -* dmctl 是一个命令行工具，用于控制 DM 集群。 - -`.yaml` 文件中定义了各个数据同步任务，dmctl 会读取这些文件，并且这些文件会被提交给 DM-master。DM-master 再将关于给定任务的相应职责告知每个 DM-worker 实例。 - -详情参见 [Data Migration 简介](/v2.1/reference/tools/data-migration/overview.md)。 - -## 安装 - -本部分介绍如何部署 3 个 MySQL Server 实例及 `pd-server`、`tikv-server` 和 `tidb-server` 实例各 1 个，以及如何启动 1 个 DM-master 和 3 个 DM-worker 实例。 - -1. 安装 MySQL 5.7，下载或提取 TiDB v3.0 以及 DM v1.0.2 安装包： - - ```bash - sudo yum install -y http://repo.mysql.com/yum/mysql-5.7-community/el/7/x86_64/mysql57-community-release-el7-10.noarch.rpm - sudo yum install -y mysql-community-server - curl https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - - curl https://download.pingcap.org/dm-v1.0.2-linux-amd64.tar.gz | tar xzf - - curl -L https://github.com/pingcap/docs/raw/master/dev/how-to/get-started/dm-cnf/dm-cnf.tgz | tar xvzf - - ``` - -2. 创建目录和符号链接： - - ```bash - mkdir -p bin data logs - ln -sf -t bin/ "$HOME"/*/bin/* - [[ :$PATH: = *:$HOME/bin:* ]] || echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile && . ~/.bash_profile - ``` - -3. 安装 3 个 MySQL Server 实例的配置： - - ```bash - tee -a "$HOME/.my.cnf" < **注意：** -> -> 对于生产环境，不要使用 Docker Compose 进行部署，而应[使用 Ansible 部署 TiDB 集群](/v2.1/how-to/deploy/orchestrated/ansible.md)。 - -## 准备环境 - -确保你的机器上已安装： - -- Docker（17.06.0 及以上版本） -- Docker Compose -- Git - -## 快速部署 - -1. 下载 `tidb-docker-compose` - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -2. 创建并启动集群 - - ```bash - cd tidb-docker-compose && docker-compose pull # Get the latest Docker images - docker-compose up -d - ``` - -3. 访问集群 - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - [集群数据可视化](https://github.com/pingcap/tidb-vision)： - -## 自定义集群 - -在完成快速部署后，以下组件已默认部署：3 个 PD，3 个 TiKV，1 个 TiDB 和监控组件 Prometheus，Pushgateway，Grafana 以及 tidb-vision。 - -如果想自定义集群，可以直接修改 `docker-compose.yml`，但是手动修改比较繁琐而且容易出错，强烈建议使用 [Helm](https://helm.sh) 模板引擎生成 `docker-compose.yml` 文件。 - -1. 安装 Helm - - [Helm](https://helm.sh) 可以用作模板渲染引擎，只需要下载其 binary 文件即可以使用。 - - ```bash - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果是 Mac 系统，也可以通过 Homebrew 安装： - - ``` - brew install kubernetes-helm - ``` - -2. 下载 `tidb-docker-compose` - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -3. 自定义集群 - - ```bash - cd tidb-docker-compose - cp compose/values.yaml values.yaml - vim values.yaml - ``` - - 修改 `values.yaml` 里面的配置，例如集群规模，TiDB 镜像版本等。 - - [tidb-vision](https://github.com/pingcap/tidb-vision) 是 TiDB 集群可视化页面，可以可视化地显示 PD 对 TiKV 数据的调度。如果不想部署该组件，可以将 `tidbVision` 项留空。 - - PD，TiKV，TiDB 和 tidb-vision 支持从 GitHub 源码或本地文件构建 Docker 镜像，供开发测试使用。 - - - 如果希望从本地已编译好的 binary 文件构建 PD，TiKV 或 TiDB 镜像，需要将其 `image` 字段留空，并将已编译好的 binary 拷贝到对应的 `pd/bin/pd-server`，`tikv/bin/tikv-server`，`tidb/bin/tidb-server`。 - - - 如果希望从本地构建 tidb-vision 镜像，需要将其 `image` 字段留空，并将 tidb-vision 项目拷贝到 `tidb-vision/tidb-vision`。 - -4. 生成 `docker-compose.yml` 文件 - - ```bash - helm template -f values.yaml compose > generated-docker-compose.yml - ``` - -5. 使用生成的 `docker-compose.yml` 创建并启动集群 - - ```bash - docker-compose -f generated-docker-compose.yml pull # Get the latest Docker images - docker-compose -f generated-docker-compose.yml up -d - ``` - -6. 访问集群 - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - 如果启用了 tidb-vision，可以通过 查看。 - -## 访问 Spark shell 并加载 TiSpark - -向 TiDB 集群中插入一些样本数据： - -```bash -$ docker-compose exec tispark-master bash -$ cd /opt/spark/data/tispark-sample-data -$ mysql -h tidb -P 4000 -u root < dss.ddl -``` - -当样本数据加载到 TiDB 集群之后，可以使用 `docker-compose exec tispark-master /opt/spark/bin/spark-shell` 来访问 Spark shell。 - -```bash -$ docker-compose exec tispark-master /opt/spark/bin/spark-shell -... -Spark context available as 'sc' (master = local[*], app id = local-1527045927617). -Spark session available as 'spark'. -Welcome to - ____ __ - / __/__ ___ _____/ /__ - _\ \/ _ \/ _ `/ __/ '_/ - /___/ .__/\_,_/_/ /_/\_\ version 2.1.1 - /_/ - -Using Scala version 2.11.8 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_172) -Type in expressions to have them evaluated. -Type :help for more information. - -scala> import org.apache.spark.sql.TiContext -... -scala> val ti = new TiContext(spark) -... -scala> ti.tidbMapDatabase("TPCH_001") -... -scala> spark.sql("select count(*) from lineitem").show -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -你也可以通过 Python 或 R 来访问 Spark： - -```bash -docker-compose exec tispark-master /opt/spark/bin/pyspark -docker-compose exec tispark-master /opt/spark/bin/sparkR -``` - -更多关于 TiSpark 的信息，参见 [TiSpark 的详细文档](/v2.1/how-to/get-started/tispark.md)。 diff --git a/v2.1/how-to/get-started/explore-sql.md b/v2.1/how-to/get-started/explore-sql.md deleted file mode 100644 index 9292531bedf6..000000000000 --- a/v2.1/how-to/get-started/explore-sql.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: TiDB 中的基本 SQL 操作 -category: how-to ---- - -# TiDB 中的基本 SQL 操作 - -成功部署 TiDB 集群之后，便可以在 TiDB 中执行 SQL 语句了。因为 TiDB 兼容 MySQL，你可以使用 MySQL 客户端连接 TiDB，并且[大多数情况下](/v2.1/reference/mysql-compatibility.md)可以直接执行 MySQL 语句。 - -本文介绍 CRUD 操作等基本的 SQL 语句。完整的 SQL 语句列表，参见 [TiDB SQL 语法详解](https://pingcap.github.io/sqlgram/)。 - -## 创建、查看和删除数据库 - -使用 `CREATE DATABASE` 语句创建数据库。语法如下： - -```sql -CREATE DATABASE db_name [options]; -``` - -例如，要创建一个名为 `samp_db` 的数据库，可使用以下语句： - -```sql -CREATE DATABASE IF NOT EXISTS samp_db; -``` - -使用 `SHOW DATABASES` 语句查看数据库： - -```sql -SHOW DATABASES; -``` - -使用 `DROP DATABASE` 语句删除数据库，例如： - -```sql -DROP DATABASE samp_db; -``` - -## 创建、查看和删除表 - -使用 `CREATE TABLE` 语句创建表。语法如下： - -```sql -CREATE TABLE table_name column_name data_type constraint; -``` - -例如： - -```sql -CREATE TABLE person ( - number INT(11), - name VARCHAR(255), - birthday DATE - ); -``` - -如果表已存在，添加 `IF NOT EXISTS` 可防止发生错误： - -```sql -CREATE TABLE IF NOT EXISTS person ( - number INT(11), - name VARCHAR(255), - birthday DATE -); -``` - -使用 `SHOW CREATE` 语句查看建表语句。例如： - -```sql -SHOW CREATE table person; -``` - -使用 `SHOW FULL COLUMNS` 语句查看表的列。 例如： - -```sql -SHOW FULL COLUMNS FROM person; -``` - -使用 `DROP TABLE` 语句删除表。例如： - -```sql -DROP TABLE person; -``` - -或者 - -```sql -DROP TABLE IF EXISTS person; -``` - -使用 `SHOW TABLES` 语句查看数据库中的所有表。例如： - -```sql -SHOW TABLES FROM samp_db; -``` - -## 创建、查看和删除索引 - -对于值不唯一的列，可使用 `CREATE INDEX` 或 `ALTER TABLE` 语句。例如： - -```sql -CREATE INDEX person_num ON person (number); -``` - -或者 - -```sql -ALTER TABLE person ADD INDEX person_num (number); -``` - -对于值唯一的列，可以创建唯一索引。例如： - -```sql -CREATE UNIQUE INDEX person_num ON person (number); -``` - -或者 - -```sql -ALTER TABLE person ADD UNIQUE person_num (number); -``` - -使用 `SHOW INDEX` 语句查看表内所有索引： - -```sql -SHOW INDEX from person; -``` - -使用 `ALTER TABLE` 或 `DROP INDEX` 语句来删除索引。与 `CREATE INDEX` 语句类似，`DROP INDEX` 也可以嵌入 `ALTER TABLE` 语句。例如： - -```sql -DROP INDEX person_num ON person; -ALTER TABLE person DROP INDEX person_num; -``` - -## 增删改查数据 - -使用 `INSERT` 语句向表内插入数据。例如： - -```sql -INSERT INTO person VALUES("1","tom","20170912"); -``` - -使用 `SELECT` 语句检索表内数据。例如： - -```sql -SELECT * FROM person; -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-09-12 | -+--------+------+------------+ -``` - -使用 `UPDATE` 语句修改表内数据。例如： - -```sql -UPDATE person SET birthday='20171010' WHERE name='tom'; - -SELECT * FROM person; -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-10-10 | -+--------+------+------------+ -``` - -使用 `DELETE` 语句删除表内数据： - -```sql -DELETE FROM person WHERE number=1; -SELECT * FROM person; -Empty set (0.00 sec) -``` - -## 创建、授权和删除用户 - -使用 `CREATE USER` 语句创建一个用户 `tiuser`，密码为 `123456`： - -```sql -CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456'; -``` - -授权用户 `tiuser` 可检索数据库 `samp_db` 内的表： - -```sql -GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost'; -``` - -查询用户 `tiuser` 的权限： - -```sql -SHOW GRANTS for tiuser@localhost; -``` - -删除用户 `tiuser`： - -```sql -DROP USER 'tiuser'@'localhost'; -``` diff --git a/v2.1/how-to/get-started/read-historical-data.md b/v2.1/how-to/get-started/read-historical-data.md deleted file mode 100644 index 760a71498d7d..000000000000 --- a/v2.1/how-to/get-started/read-historical-data.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: 读取历史数据 -category: how-to ---- - -# 读取历史数据 - -本文档介绍 TiDB 如何读取历史版本数据，包括具体的操作流程以及历史数据的保存策略。 - -## 功能说明 - -TiDB 实现了通过标准 SQL 接口读取历史数据功能，无需特殊的 client 或者 driver。当数据被更新、删除后，依然可以通过 SQL 接口将更新/删除前的数据读取出来。 - -另外即使在更新数据之后，表结构发生了变化，TiDB 依旧能用旧的表结构将数据读取出来。 - -## 操作流程 - -为支持读取历史版本数据， 引入了一个新的 system variable: tidb_snapshot ，这个变量是 Session 范围有效，可以通过标准的 Set 语句修改其值。其值为文本，能够存储 TSO 和日期时间。TSO 即是全局授时的时间戳，是从 PD 端获取的; 日期时间的格式可以为： -“2016-10-08 16:45:26.999”，一般来说可以只写到秒，比如”2016-10-08 16:45:26”。 -当这个变量被设置时，TiDB 会用这个时间戳建立 Snapshot（没有开销，只是创建数据结构），随后所有的 Select 操作都会在这个 Snapshot 上读取数据。 - -> **注意：** -> -> TiDB 的事务是通过 PD 进行全局授时，所以存储的数据版本也是以 PD 所授时间戳作为版本号。在生成 Snapshot 时，是以 tidb_snapshot 变量的值作为版本号，如果 TiDB Server 所在机器和 PD Server 所在机器的本地时间相差较大，需要以 PD 的时间为准。 - -当读取历史版本操作结束后，可以结束当前 Session 或者是通过 Set 语句将 tidb_snapshot 变量的值设为 ""，即可读取最新版本的数据。 - -## 历史数据保留策略 - -TiDB 使用 MVCC 管理版本，当更新/删除数据时，不会做真正的数据删除，只会添加一个新版本数据，所以可以保留历史数据。历史数据不会全部保留，超过一定时间的历史数据会被彻底删除，以减小空间占用以及避免历史版本过多引入的性能开销。 - -TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理，关于 GC 的详细介绍参见 [TiDB 垃圾回收 (GC)](/v2.1/reference/garbage-collection.md)。 - -这里需要重点关注的是 `tikv_gc_life_time` 和 `tikv_gc_safe_point` 这条。`tikv_gc_life_time` 用于配置历史版本保留时间，可以手动修改；`tikv_gc_safe_point` 记录了当前的 safePoint，用户可以安全地使用大于 safePoint 的时间戳创建 snapshot 读取历史版本。safePoint 在每次 GC 开始运行时自动更新。 - -## 示例 - -1. 初始化阶段，创建一个表，并插入几行数据： - - ```sql - mysql> create table t (c int); - Query OK, 0 rows affected (0.01 sec) - - mysql> insert into t values (1), (2), (3); - Query OK, 3 rows affected (0.00 sec) - ``` - -2. 查看表中的数据： - - ```sql - mysql> select * from t; - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -3. 查看当前时间： - - ```sql - mysql> select now(); - +---------------------+ - | now() | - +---------------------+ - | 2016-10-08 16:45:26 | - +---------------------+ - 1 row in set (0.00 sec) - ``` - -4. 更新某一行数据： - - ```sql - mysql> update t set c=22 where c=2; - Query OK, 1 row affected (0.00 sec) - ``` - -5. 确认数据已经被更新： - - ```sql - mysql> select * from t; - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -6. 设置一个特殊的环境变量，这个是一个 session scope 的变量，其意义为读取这个时间之前的最新的一个版本。 - - ```sql - mysql> set @@tidb_snapshot="2016-10-08 16:45:26"; - Query OK, 0 rows affected (0.00 sec) - ``` - - > **注意：** - > - > - 这里的时间设置的是 update 语句之前的那个时间。 - > - 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 - - 这里读取到的内容即为 update 之前的内容，也就是历史版本： - - ```sql - mysql> select * from t; - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -7. 清空这个变量后，即可读取最新版本数据： - - ```sql - mysql> set @@tidb_snapshot=""; - Query OK, 0 rows affected (0.00 sec) - ``` - - ```sql - mysql> select * from t; - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - - > **注意：** - > - > 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 \ No newline at end of file diff --git a/v2.1/how-to/get-started/tidb-binlog.md b/v2.1/how-to/get-started/tidb-binlog.md deleted file mode 100644 index 7b54fc3025b1..000000000000 --- a/v2.1/how-to/get-started/tidb-binlog.md +++ /dev/null @@ -1,416 +0,0 @@ ---- -title: TiDB Binlog 教程 -category: how-to ---- - -# TiDB Binlog 教程 - -本文档主要介绍如何使用 TiDB Binlog 将数据从 TiDB 推送到 MariaDB 实例。文中的 TiDB Binlog 集群包含 Pump 和 Drainer 的单个节点，TiDB 集群包含 TiDB、TiKV 和 Placement Driver (PD) 各组件的单个节点。 - -希望上手实践 TiDB Binlog 工具的用户需要对 [TiDB 架构](/v2.1/architecture.md)有一定的了解，最好有创建过 TiDB 集群的经验。该文档也有助于简单快速了解 TiDB Binlog 架构以及相关概念。 - -> **警告：** -> -> 该文档中部署 TiDB 的操作指导**不适用于**在生产或研发环境中部署 TiDB 的情况。 - -该文档假设用户使用的是现代 Linux 发行版本中的 x86-64。示例中使用的是 VMware 中运行的 CentOS 7 最小化安装。建议在一开始就进行清洁安装，以避免受现有环境中未知情况的影响。如果不想使用本地虚拟环境，也可以使用云服务启动 CentOS 7 VM。 - -## TiDB Binlog 简介 - -TiDB Binlog 用于收集 TiDB 中二进制日志数据、提供实时数据备份和同步以及将 TiDB 集群的数据增量同步到下游。 - -TiDB Binlog 支持以下功能场景： - -- 增量备份，将 TiDB 集群中的数据增量同步到另一个集群，或通过 Kafka 增量同步到选择的下游。 -- 当使用 TiDB DM (Data Migration) 将数据从上游 MySQL 或者 MariaDB 迁移到 TiDB 集群时，可使用 TiDB Binlog 保持 TiDB 集群与其一个独立下游 MySQL 或 MariaDB 实例或集群同步。当 TiDB 集群上游数据迁移过程中出现问题，下游数据同步过程中可使用 TiDB Binlog 恢复数据到原先的状态。 - -更多信息参考 [TiDB Binlog Cluster 版本用户文档](/v2.1/reference/tidb-binlog/overview.md)。 - -## 架构 - -TiDB Binlog 集群由 **Pump** 和 **Drainer** 两个组件组成。一个 Pump 集群中有若干个 Pump 节点。TiDB 实例连接到各个 Pump 节点并发送 binlog 数据到 Pump 节点。Pump 集群连接到 Drainer 节点，Drainer 将接收到的更新数据转换到某个特定下游（例如 Kafka、另一个 TiDB 集群或 MySQL 或 MariaDB Server）指定的正确格式。 - -![TiDB Binlog architecture](/media/tidb_binlog_cluster_architecture.png) - -Pump 的集群架构能确保 TiDB 或 Pump 集群中有新的实例加入或退出时更新数据不会丢失。 - -## 安装 - -由于 RHEL/CentOS 7 的默认包装库中包括 MariaDB Server，本示例选择的是 MariaDB Server。后续除了安装服务器，也需要安装客户端。安装指令如下： - -```bash -sudo yum install -y mariadb-server -``` - -预期输出： - -``` -[kolbe@localhost ~]$ curl -LO https://download.pingcap.org/tidb-latest-linux-amd64.tar.gz | tar xzf - - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 368M 100 368M 0 0 8394k 0 0:00:44 0:00:44 --:--:-- 11.1M -[kolbe@localhost ~]$ cd tidb-latest-linux-amd64 -[kolbe@localhost tidb-latest-linux-amd64]$ -``` - -## 配置 - -通过执行以下步骤配置一个 TiDB 集群，该集群包括 `pd-server`、`tikv-server` 和 `tidb-server` 各组件的单个实例。 - -1. 填充配置文件： - - ```bash - printf > pd.toml %s\\n 'log-file="pd.log"' 'data-dir="pd.data"' - printf > tikv.toml %s\\n 'log-file="tikv.log"' '[storage]' 'data-dir="tikv.data"' '[pd]' 'endpoints=["127.0.0.1:2379"]' '[rocksdb]' max-open-files=1024 '[raftdb]' max-open-files=1024 - printf > pump.toml %s\\n 'log-file="pump.log"' 'data-dir="pump.data"' 'addr="127.0.0.1:8250"' 'advertise-addr="127.0.0.1:8250"' 'pd-urls="http://127.0.0.1:2379"' - printf > tidb.toml %s\\n 'store="tikv"' 'path="127.0.0.1:2379"' '[log.file]' 'filename="tidb.log"' '[binlog]' 'enable=true' - printf > drainer.toml %s\\n 'log-file="drainer.log"' '[syncer]' 'db-type="mysql"' '[syncer.to]' 'host="127.0.0.1"' 'user="root"' 'password=""' 'port=3306' - ``` - -2. 查看配置细节： - - ```bash - for f in *.toml; do echo "$f:"; cat "$f"; echo; done - ``` - - 预期输出： - - ``` - drainer.toml: - log-file="drainer.log" - [syncer] - db-type="mysql" - [syncer.to] - host="127.0.0.1" - user="root" - password="" - port=3306 - - pd.toml: - log-file="pd.log" - data-dir="pd.data" - - pump.toml: - log-file="pump.log" - data-dir="pump.data" - addr="127.0.0.1:8250" - advertise-addr="127.0.0.1:8250" - pd-urls="http://127.0.0.1:2379" - - tidb.toml: - store="tikv" - path="127.0.0.1:2379" - [log.file] - filename="tidb.log" - [binlog] - enable=true - - tikv.toml: - log-file="tikv.log" - [storage] - data-dir="tikv.data" - [pd] - endpoints=["127.0.0.1:2379"] - [rocksdb] - max-open-files=1024 - [raftdb] - max-open-files=1024 - ``` - -## 启动程序 - -现在可启动各个组件。推荐启动顺序依次为 Placement Driver (PD)、TiKV、Pump（TiDB 发送 binlog 日志必须连接 Pump 服务）、TiDB。 - -1. 启动所有服务： - - ```bash - ./bin/pd-server --config=pd.toml &>pd.out & - ./bin/tikv-server --config=tikv.toml &>tikv.out & - ./bin/pump --config=pump.toml &>pump.out & - sleep 3 - ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - 预期输出： - - ``` - [kolbe@localhost tidb-latest-linux-amd64]$ ./bin/pd-server --config=pd.toml &>pd.out & - [1] 20935 - [kolbe@localhost tidb-latest-linux-amd64]$ ./bin/tikv-server --config=tikv.toml &>tikv.out & - [2] 20944 - [kolbe@localhost tidb-latest-linux-amd64]$ ./bin/pump --config=pump.toml &>pump.out & - [3] 21050 - [kolbe@localhost tidb-latest-linux-amd64]$ sleep 3 - [kolbe@localhost tidb-latest-linux-amd64]$ ./bin/tidb-server --config=tidb.toml &>tidb.out & - [4] 21058 - ``` - -2. 如果执行 `jobs`，可以看到后台正在运行的程序，列表如下： - - ``` - [kolbe@localhost tidb-latest-linux-amd64]$ jobs - [1] Running ./bin/pd-server --config=pd.toml &>pd.out & - [2] Running ./bin/tikv-server --config=tikv.toml &>tikv.out & - [3]- Running ./bin/pump --config=pump.toml &>pump.out & - [4]+ Running ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - 如果有服务启动失败（例如出现 “`Exit 1`” 而不是 “`Running`”），尝试重启单个组件。 - -## 连接 - -按以上步骤操作后，TiDB 的 4 个组件开始运行。接下来可以使用以下 MariaDB 或 MySQL 命令行客户端，通过 4000 端口连接到 TiDB 服务： - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select tidb_version()\G' -``` - -预期输出： - -``` -[kolbe@localhost tidb-latest-linux-amd64]$ mysql -h 127.0.0.1 -P 4000 -u root -e 'select tidb_version()\G' -*************************** 1. row *************************** -tidb_version(): Release Version: v3.0.0-beta.1-154-gd5afff70c -Git Commit Hash: d5afff70cdd825d5fab125c8e52e686cc5fb9a6e -Git Branch: master -UTC Build Time: 2019-04-24 03:10:00 -GoVersion: go version go1.12 linux/amd64 -Race Enabled: false -TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e -Check Table Before Drop: false -``` - -连接后TiDB 集群已开始运行，`pump` 读取集群中的 binlog 数据，并在其数据目录中将 binlog 数据存储为 relay log。下一步是启动一个可供 `drainer` 写入的 MariaDB Server。 - -1. 启动 `drainer`： - - ```bash - sudo systemctl start mariadb - ./bin/drainer --config=drainer.toml &>drainer.out & - ``` - - 如果你的操作系统更易于安装 MySQL，只需保证监听 3306 端口。另外，可使用密码为空的 "root" 用户连接到 MySQL，或调整 `drainer.toml` 连接到 MySQL。 - - ```bash - mysql -h 127.0.0.1 -P 3306 -u root - ``` - - ```sql - show databases; - ``` - - 预期输出： - - ``` - [kolbe@localhost ~]$ mysql -h 127.0.0.1 -P 3306 -u root - Welcome to the MariaDB monitor. Commands end with ; or \g. - Your MariaDB connection id is 20 - Server version: 5.5.60-MariaDB MariaDB Server - - Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - MariaDB [(none)]> show databases; - +--------------------+ - | Database | - +--------------------+ - | information_schema | - | mysql | - | performance_schema | - | test | - | tidb_binlog | - +--------------------+ - 5 rows in set (0.01 sec) - ``` - - 如下表格是包含 `checkpoint` 表格的 `tidb_binlog` 数据库。`drainer` 使用 `checkpoint` 表格，记录 TiDB 集群中的 binlog 已经更新到了哪个位置。 - - ```sql - MariaDB [tidb_binlog]> use tidb_binlog; - Database changed - MariaDB [tidb_binlog]> select * from checkpoint; - +---------------------+---------------------------------------------+ - | clusterID | checkPoint | - +---------------------+---------------------------------------------+ - | 6678715361817107733 | {"commitTS":407637466476445697,"ts-map":{}} | - +---------------------+---------------------------------------------+ - 1 row in set (0.00 sec) - ``` - - 打开另一个连接到 TiDB 的客户端，创建一个表格并插入几行数据。建议在 GNU Screen 软件中操作，从而同时打开多个客户端。 - - ```bash - mysql -h 127.0.0.1 -P 4000 --prompt='TiDB [\d]> ' -u root - ``` - - ```sql - create database tidbtest; - use tidbtest; - create table t1 (id int unsigned not null AUTO_INCREMENT primary key); - insert into t1 () values (),(),(),(),(); - select * from t1; - ``` - - 预期输出： - - ``` - TiDB [(none)]> create database tidbtest; - Query OK, 0 rows affected (0.12 sec) - - TiDB [(none)]> use tidbtest; - Database changed - TiDB [tidbtest]> create table t1 (id int unsigned not null AUTO_INCREMENT primary key); - Query OK, 0 rows affected (0.11 sec) - - TiDB [tidbtest]> insert into t1 () values (),(),(),(),(); - Query OK, 5 rows affected (0.01 sec) - Records: 5 Duplicates: 0 Warnings: 0 - - TiDB [tidbtest]> select * from t1; - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 切换回 MariaDB 客户端可看到新的数据库、新的表格和最近插入的行数据。 - - ```sql - use tidbtest; - show tables; - select * from t1; - ``` - - 预期输出： - - ``` - MariaDB [(none)]> use tidbtest; - Reading table information for completion of table and column names - You can turn off this feature to get a quicker startup with -A - - Database changed - MariaDB [tidbtest]> show tables; - +--------------------+ - | Tables_in_tidbtest | - +--------------------+ - | t1 | - +--------------------+ - 1 row in set (0.00 sec) - - MariaDB [tidbtest]> select * from t1; - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 可看到查询 MariaDB 时插入到 TiDB 相同的行数据，表明 TiDB Binlog 安装成功。 - -## binlogctl - -加入到集群的 Pump 和 Drainer 的数据存储在 Placement Driver (PD) 中。binlogctl 可用于查询和修改状态信息。更多信息请参考 [binlogctl guide](/v2.1/reference/tidb-binlog/maintain.md#binlogctl-工具)。 - -使用 `binlogctl` 查看集群中 Pump 和 Drainer 的当前状态： - -```bash -./bin/binlogctl -cmd drainers -./bin/binlogctl -cmd pumps -``` - -预期输出： - -``` -[kolbe@localhost tidb-latest-linux-amd64]$ ./bin/binlogctl -cmd drainers -[2019/04/11 17:44:10.861 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: online, MaxCommitTS: 407638907719778305, UpdateTime: 2019-04-11 17:44:10 -0400 EDT}"] - -[kolbe@localhost tidb-latest-linux-amd64]$ ./bin/binlogctl -cmd pumps -[2019/04/11 17:44:13.904 -04:00] [INFO] [nodes.go:47] ["query node"] [type=pump] [node="{NodeID: localhost.localdomain:8250, Addr: 192.168.236.128:8250, State: online, MaxCommitTS: 407638914024079361, UpdateTime: 2019-04-11 17:44:13 -0400 EDT}"] -``` - -如果结束 Drainer 进程，集群会改进程设置“已暂停（即集群等待 Drainer 重新加入）”的状态。 - -```bash -pkill drainer -./bin/binlogctl -cmd drainers -``` - -预期输出： - -``` -[kolbe@localhost tidb-latest-linux-amd64]$ pkill drainer -[kolbe@localhost tidb-latest-linux-amd64]$ ./bin/binlogctl -cmd drainers -[2019/04/11 17:44:22.640 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: paused, MaxCommitTS: 407638915597467649, UpdateTime: 2019-04-11 17:44:18 -0400 EDT}"] -``` - -使用 binlogctl 的 "NodeIDs" 可控制单个对应节点。在该情况下，Drainer 的节点 ID 是 "localhost.localdomain:8249"，Pump 的节点 ID 是 "localhost.localdomain:8250"。 - -本文档中的 binlogctl 主要用于集群重启。如果在 TiDB 集群中终止并尝试重启所有的进程，由于 Pump 无法连接 Drainer 且认为 Drainer 依旧“在线”，Pump 会拒绝启动。这里的进程并不包括下游的 MySQL 或 MariaDB 或 Drainer。 - -以下有三个方案可解决上述问题： - -- 使用 binlogctl 停止 Drainer，而不是结束进程： - - ``` - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=drainers - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=pause-drainer --node-id=localhost.localdomain:8249 - ``` - -- 在启动 Pump **之前**先启动 Drainer。 - -- 在启动 PD 之后但在启动 Drainer 和 Pump 之前，使用 binlogctl 更新已暂定 Drainer 的状态。 - - ``` - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=update-drainer --node-id=localhost.localdomain:8249 --state=paused - ``` - -## 清理 - -在 shell 终端里可启动创建集群的所有进程（`pd-server` 、`tikv-server`、`pump`、`tidb-server`、`drainer`）。可通过在 shell 终端中执行 `pkill -P $$` 停止 TiDB 集群服务和 TiDB Binlog 进程。按一定的顺序停止这些进程有利于留出足够的时间彻底关闭每个组件。 - -```bash -for p in tidb-server drainer pump tikv-server pd-server; do pkill "$p"; sleep 1; done -``` - -预期输出： - -``` -kolbe@localhost tidb-latest-linux-amd64]$ for p in tidb-server drainer pump tikv-server pd-server; do pkill "$p"; sleep 1; done -[4]- Done ./bin/tidb-server --config=tidb.toml &>tidb.out -[5]+ Done ./bin/drainer --config=drainer.toml &>drainer.out -[3]+ Done ./bin/pump --config=pump.toml &>pump.out -[2]+ Done ./bin/tikv-server --config=tikv.toml &>tikv.out -[1]+ Done ./bin/pd-server --config=pd.toml &>pd.out -``` - -如果需要所有服务退出后重启集群，可以使用一开始启动服务的命令。如以上 [`binlogctl`](#binlogctl) 部分所述，需要先启动 Drainer 再启动 Pump，最后启动 `tidb-server`。 - -```bash -./bin/pd-server --config=pd.toml &>pd.out & -./bin/tikv-server --config=tikv.toml &>tikv.out & -./bin/drainer --config=drainer.toml &>drainer.out & -sleep 3 -./bin/pump --config=pump.toml &>pump.out & -sleep 3 -./bin/tidb-server --config=tidb.toml &>tidb.out & -``` - -如果有组件启动失败，请尝试单独重启该组件。 - -## 总结 - -本文档介绍了如何通过设置 TiDB Binlog，使用单个 Pump 和 Drainer 组成的集群同步 TiDB 集群数据到下游的 MariaDB。可以发现，TiDB Binlog 是用于获取处理 TiDB 集群中更新数据的综合性平台工具。 - -在更稳健的开发、测试或生产部署环境中，可以使用多个 TiDB 服务以实现高可用性和扩展性。使用多个 Pump 实例可以避免 Pump 集群中的问题影响发送到 TiDB 实例的应用流量。或者可以使用增加的 Drainer 实例同步数据到不同的下游或实现数据增量备份。 diff --git a/v2.1/how-to/get-started/tidb-lightning.md b/v2.1/how-to/get-started/tidb-lightning.md deleted file mode 100644 index 045de86b2de1..000000000000 --- a/v2.1/how-to/get-started/tidb-lightning.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: TiDB Lightning 教程 -category: how-to ---- - -# TiDB Lightning 教程 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -TiDB Lightning 主要包含两个部分: - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键/值对 (KV 对) 发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，把 `tidb-lightning` 写入的 KV 对缓存、排序、切分并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -本教程假设使用的是若干新的、纯净版 CentOS 7 实例，你可以（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为 TiDB Lightning 对计算机资源消耗较高，建议分配 4 GB 以上的内存。 - -> **警告：** -> -> 本教程中的部署方法只适用于测试及功能体验，并不适用于生产或开发环境。 - -## 准备全量备份数据 - -我们使用 [`mydumper`](/v2.1/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -这样全量备份数据就导出到了 `/data/my_database` 目录中。 - -## 部署 TiDB Lightning - -### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群（版本要求 2.0.9 以上），本教程使用 TiDB 3.0.4 版本。部署方法可参考 [TiDB 快速入门指南](/v2.1/overview.md#部署方式)。 - -### 第 2 步：下载 TiDB Lightning 安装包 - -通过以下链接获取 TiDB Lightning 安装包（选择与 TiDB 集群相同的版本）： - -- **v3.0.4**: [tidb-toolkit-v3.0.4-linux-amd64.tar.gz](https://download.pingcap.org/tidb-toolkit-v3.0.0-linux-amd64.tar.gz) - -### 第 3 步：启动 `tikv-importer` - -1. 将安装包里的 `bin/tikv-importer` 上传至部署 TiDB Lightning 的服务器。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -### 第 4 步：启动 `tidb-lightning` - -1. 将安装包里的 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。 - -2. 将数据源也上传到同样的服务器。 - -3. 配置合适的参数运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning \ - --importer 172.16.31.10:8287 \ - -d /data/my_database/ \ - --tidb-server 172.16.31.2 \ - --tidb-user root \ - --log-file tidb-lightning.log \ - > nohup.out & - ``` - -### 第 5 步：检查数据 - -导入完毕后，TiDB Lightning 会自动退出。若导入成功，日志的最后一行会显示 `tidb lightning exit`。 - -如果出错，请参见 [TiDB Lightning 错误排解](/v2.1/how-to/troubleshoot/tidb-lightning.md)。 - -## 总结 - -本教程对 TiDB Lightning 进行了简单的介绍，并快速部署了一套简单的 TiDB Lightning 集群，将全量备份数据导入到 TiDB 集群中。 - -关于 TiDB Lightning 的详细功能和使用，参见 [TiDB Lightning 简介](/v2.1/reference/tools/tidb-lightning/overview.md)。 diff --git a/v2.1/how-to/get-started/tispark.md b/v2.1/how-to/get-started/tispark.md deleted file mode 100644 index 4fe9ddcd9ba2..000000000000 --- a/v2.1/how-to/get-started/tispark.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: TiSpark 快速入门指南 -category: how-to ---- - -# TiSpark 快速入门指南 - -为了让大家快速体验 [TiSpark](/v2.1/reference/tispark.md)，通过 TiDB Ansible 安装的 TiDB 集群中默认已集成 Spark、TiSpark jar 包及 TiSpark sample data。 - -## 部署信息 - -- Spark 默认部署在 TiDB 实例部署目录下 spark 目录中 -- TiSpark jar 包默认部署在 Spark 部署目录 jars 文件夹下：`spark/jars/tispark-SNAPSHOT-jar-with-dependencies.jar` -- TiSpark sample data 及导入脚本默认部署在 TiDB Ansible 目录下：`tidb-ansible/resources/bin/tispark-sample-data` - -## 环境准备 - -### 在 TiDB 实例上安装 JDK - -在 [Oracle JDK 官方下载页面](http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html) 下载 JDK 1.8 当前最新版，本示例中下载的版本为 `jdk-8u141-linux-x64.tar.gz`。 - -解压并根据您的 JDK 部署目录设置环境变量， -编辑 `~/.bashrc` 文件，比如： - -```bashrc -export JAVA_HOME=/home/pingcap/jdk1.8.0_144 -export PATH=$JAVA_HOME/bin:$PATH -``` - -验证 JDK 有效性： - -``` -$ java -version -java version "1.8.0_144" -Java(TM) SE Runtime Environment (build 1.8.0_144-b01) -Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode) -``` - -### 导入样例数据 - -假设 TiDB 集群已启动，其中一台 TiDB 实例服务 IP 为 192.168.0.2，端口为 4000，用户名为 root, 密码为空。 - -``` -cd tidb-ansible/resources/bin/tispark-sample-data -``` - -修改 `sample_data.sh` 中 TiDB 登录信息，比如： - -``` -mysql --local-infile=1 -h 192.168.0.2 -P 4000 -u root < dss.ddl -``` - -执行脚本 - -``` -./sample_data.sh -``` - -> 执行脚本的机器上需要安装 MySQL client，CentOS 用户可通过 `yum -y install mysql`来安装。 - -登录 TiDB 并验证数据包含 `TPCH_001` 库及以下表： - -``` -$ mysql -uroot -P4000 -h192.168.0.2 -MySQL [(none)]> show databases; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| TPCH_001 | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) - -MySQL [(none)]> use TPCH_001 -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -MySQL [TPCH_001]> show tables; -+--------------------+ -| Tables_in_TPCH_001 | -+--------------------+ -| CUSTOMER | -| LINEITEM | -| NATION | -| ORDERS | -| PART | -| PARTSUPP | -| REGION | -| SUPPLIER | -+--------------------+ -8 rows in set (0.00 sec) -``` - -## 使用范例 - -进入 spark 部署目录启动 spark-shell: - -``` -$ cd spark -$ bin/spark-shell -``` - -然后像使用原生 Spark 一样查询 TiDB 表： - -```scala -scala> spark.sql("select count(*) from lineitem").show -``` - -结果为 - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -下面执行另一个复杂一点的 Spark SQL: - -```scala -scala> spark.sql( - """select - | l_returnflag, - | l_linestatus, - | sum(l_quantity) as sum_qty, - | sum(l_extendedprice) as sum_base_price, - | sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, - | sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, - | avg(l_quantity) as avg_qty, - | avg(l_extendedprice) as avg_price, - | avg(l_discount) as avg_disc, - | count(*) as count_order - |from - | lineitem - |where - | l_shipdate <= date '1998-12-01' - interval '90' day - |group by - | l_returnflag, - | l_linestatus - |order by - | l_returnflag, - | l_linestatus - """.stripMargin).show -``` - -结果为： - -``` -+------------+------------+---------+--------------+--------------+ -|l_returnflag|l_linestatus| sum_qty|sum_base_price|sum_disc_price| -+------------+------------+---------+--------------+--------------+ -| A| F|380456.00| 532348211.65|505822441.4861| -| N| F| 8971.00| 12384801.37| 11798257.2080| -| N| O|742802.00| 1041502841.45|989737518.6346| -| R| F|381449.00| 534594445.35|507996454.4067| -+------------+------------+---------+--------------+--------------+ -(续) ------------------+---------+------------+--------+-----------+ - sum_charge| avg_qty| avg_price|avg_disc|count_order| ------------------+---------+------------+--------+-----------+ - 526165934.000839|25.575155|35785.709307|0.050081| 14876| - 12282485.056933|25.778736|35588.509684|0.047759| 348| -1029418531.523350|25.454988|35691.129209|0.049931| 29181| - 528524219.358903|25.597168|35874.006533|0.049828| 14902| ------------------+---------+------------+--------+-----------+ -``` - -更多样例请参考 diff --git a/v2.1/how-to/maintain/ansible-operations.md b/v2.1/how-to/maintain/ansible-operations.md deleted file mode 100644 index 4ea898e127b8..000000000000 --- a/v2.1/how-to/maintain/ansible-operations.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB Ansible 常见运维操作 -category: how-to ---- - -# TiDB Ansible 常见运维操作 - -## 启动集群 - -此操作会按顺序启动整个 TiDB 集群所有组件（包括 PD、TiDB、TiKV 等组件和监控组件）。 - -``` -$ ansible-playbook start.yml -``` - -## 关闭集群 - -此操作会按顺序关闭整个 TiDB 集群所有组件（包括 PD、TiDB、TiKV 等组件和监控组件）。 - -``` -$ ansible-playbook stop.yml -``` - -## 清除集群数据 - -此操作会关闭 TiDB、Pump、TiKV、PD 服务，并清空 Pump、TiKV、PD 数据目录。 - -``` -$ ansible-playbook unsafe_cleanup_data.yml -``` - -## 销毁集群 - -此操作会关闭集群，并清空部署目录，若部署目录为挂载点，会报错，可忽略。 - -``` -$ ansible-playbook unsafe_cleanup.yml -``` diff --git a/v2.1/how-to/maintain/backup-and-restore.md b/v2.1/how-to/maintain/backup-and-restore.md deleted file mode 100644 index dfdf1808828d..000000000000 --- a/v2.1/how-to/maintain/backup-and-restore.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: 备份与恢复 -category: how-to ---- - -# 备份与恢复 - -本文档将详细介绍如何对 TiDB 进行全量备份与恢复。增量备份与恢复可使用 [TiDB Binlog](/v2.1/reference/tidb-binlog/overview.md)。 - -这里我们假定 TiDB 服务信息如下： - -|Name|Address|Port|User|Password| -|----|-------|----|----|--------| -|TiDB|127.0.0.1|4000|root|*| - -在这个备份恢复过程中，我们会用到下面的工具： - -- Mydumper 从 TiDB 导出数据 -- Loader 导入数据到 TiDB - -## 下载 TiDB 工具集 (Linux) - -下载 tool 压缩包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -解开压缩包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf tidb-enterprise-tools-latest-linux-amd64.tar.gz && \ -cd tidb-enterprise-tools-latest-linux-amd64 -``` - -## 使用 `mydumper`/`loader` 全量备份恢复数据 - -`mydumper` 是一个强大的数据备份工具，具体可以参考 [`maxbube/mydumper`](https://github.com/maxbube/mydumper)。 - -可使用 [`mydumper`](/v2.1/reference/tools/mydumper.md) 从 TiDB 导出数据进行备份，然后用 [`loader`](/v2.1/reference/tools/loader.md) 将其导入到 TiDB 里面进行恢复。 - -> **注意：** -> -> 必须使用企业版工具集包的 `mydumper`，不要使用你的操作系统的包管理工具提供的 `mydumper`。`mydumper` 的上游版本并不能对 TiDB 进行正确处理 ([#155](https://github.com/maxbube/mydumper/pull/155))。由于使用 `mysqldump` 进行数据备份和恢复都要耗费许多时间，这里也并不推荐。 - -### `mydumper`/`loader` 全量备份恢复最佳实践 - -为了快速地备份恢复数据 (特别是数据量巨大的库)，可以参考以下建议： - -* 使用 Mydumper 导出来的数据文件尽可能的小，最好不要超过 64M，可以将参数 `-F` 设置为 64。 -* Loader的 `-t` 参数可以根据 TiKV 的实例个数以及负载进行评估调整，推荐设置为 32。当 TiKV 负载过高，Loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 时，可以适当调小该值；当 TiKV 负载不是太高的时候，可以适当调大该值。 - -## 从 TiDB 备份数据 - -我们使用 `mydumper` 从 TiDB 备份数据，如下: - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -P 4000 -u root -t 32 -F 64 -B test -T t1,t2 --skip-tz-utc -o ./var/test -``` - -上面，我们使用 `-B test` 表明是对 `test` 这个 database 操作，然后用 `-T t1,t2` 表明只导出 `t1`，`t2` 两张表。 - -`-t 32` 表明使用 32 个线程去导出数据。`-F 64` 是将实际的 table 切分成多大的 chunk，这里就是 64MB 一个 chunk。 - -`--skip-tz-utc` 添加这个参数忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果 `mydumper` 出现以下报错： - -``` -** (mydumper:27528): CRITICAL **: 13:25:09.081: Could not read data from testSchema.testTable: GC life time is shorter than transaction duration, transaction starts at 2019-08-05 21:10:01.451 +0800 CST, GC safe point is 2019-08-05 21:14:53.801 +0800 CST -``` - -就再执行两步命令： - -1. 执行 `mydumper` 命令前，查询 TiDB 集群的 GC 值并使用 MySQL 客户端将其调整为合适的值。 - - ```sql - mysql> SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - - mysql> update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 执行 `mydumper` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值。 - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -## 向 TiDB 恢复数据 - -我们使用 `loader` 将之前导出的数据导入到 TiDB，完成恢复操作。Loader 的下载和具体的使用方法见 [Loader 使用文档](/v2.1/reference/tools/loader.md) - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -h 127.0.0.1 -u root -P 4000 -t 32 -d ./var/test -``` - -导入成功之后，我们可以用 MySQL 官方客户端进入 TiDB，查看： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h127.0.0.1 -P4000 -uroot -``` - -{{< copyable "sql" >}} - -```sql -show tables; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -| t2 | -+----------------+ -``` - -{{< copyable "sql" >}} - -```sql -select * from t1; -``` - -``` -+----+------+ -| id | age | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+------+ -``` - -{{< copyable "sql" >}} - -```sql -select * from t2; -``` - -``` -+----+------+ -| id | name | -+----+------+ -| 1 | a | -| 2 | b | -| 3 | c | -+----+------+ -``` diff --git a/v2.1/how-to/maintain/identify-slow-queries.md b/v2.1/how-to/maintain/identify-slow-queries.md deleted file mode 100644 index 3a14b1f886f3..000000000000 --- a/v2.1/how-to/maintain/identify-slow-queries.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: 慢查询日志 -category: how-to -aliases: ['/docs-cn/sql/slow-query/'] ---- - -# 慢查询日志 - -TiDB 会将执行时间超过 [slow-threshold](/v2.1/reference/configuration/tidb-server/configuration-file.md#slow-threshold)（默认值为 300 毫秒）的语句输出到 [slow-query-file](/v2.1/reference/configuration/tidb-server/configuration-file.md#slow-query-file)（默认值："tidb-slow.log"）日志文件中，用于帮助用户定位慢查询语句，分析和解决 SQL 执行的性能问题。 - -## 日志示例 - -```sql -# Time: 2019-08-14T09:26:59.487776265+08:00 -# Txn_start_ts: 410450924122144769 -# User: root@127.0.0.1 -# Conn_ID: 3086 -# Query_time: 1.527627037 -# Process_time: 0.07 Request_count: 1 Total_keys: 131073 Process_keys: 131072 Prewrite_time: 0.335415029 Commit_time: 0.032175429 Get_commit_ts_time: 0.000177098 Local_latch_wait_time: 0.106869448 Write_keys: 131072 Write_size: 3538944 Prewrite_region: 1 -# DB: test -# Is_internal: false -# Digest: 50a2e32d2abbd6c1764b1b7f2058d428ef2712b029282b776beb9506a365c0f1 -# Stats: t:pseudo -# Num_cop_tasks: 1 -# Cop_proc_avg: 0.07 Cop_proc_p90: 0.07 Cop_proc_max: 0.07 Cop_proc_addr: 172.16.5.87:20171 -# Cop_wait_avg: 0 Cop_wait_p90: 0 Cop_wait_max: 0 Cop_wait_addr: 172.16.5.87:20171 -# Mem_max: 525211 -# Succ: false -insert into t select * from t; -``` - -## 字段含义说明 - -> **注意：** -> -> 慢查询日志中所有时间相关字段的单位都是 **“秒”** - -Slow Query 基础信息： - -* `Time`：表示日志打印时间。 -* `Query_time`：表示执行这个语句花费的时间。 -* `Query`：表示 SQL 语句。慢日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 -* `Digest`：表示 SQL 语句的指纹。 -* `Txn_start_ts`：表示事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `Is_internal`：表示是否为 TiDB 内部的 SQL 语句。`true` 表示 TiDB 系统内部执行的 SQL 语句，`false` 表示用户执行的 SQL 语句。 -* `Index_ids`：表示语句涉及到的索引的 ID。 -* `Succ`：表示语句是否执行成功。 -* `Backoff_time`：表示语句遇到需要重试的错误时在重试前等待的时间，常见的需要重试的错误有以下几种：遇到了 lock、Region 分裂、`tikv server is busy`。 - -和内存使用相关的字段： - -* `Memory_max`：表示执行期间 TiDB 使用的最大内存空间，单位为 byte。 - -和 SQL 执行的用户相关的字段： - -* `User`：表示执行语句的用户名。 -* `Conn_ID`：表示用户的链接 ID，可以用类似 `con:3` 的关键字在 TiDB 日志中查找该链接相关的其他日志。 -* `DB`：表示执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `Request_count`：表示这个语句发送的 Coprocessor 请求的数量。 -* `Total_keys`：表示 Coprocessor 扫过的 key 的数量。 -* `Process_time`：执行 SQL 在 TiKV 的处理时间之和，因为数据会并行的发到 TiKV 执行，这个值可能会超过 `Query_time`。 -* `Wait_time`：表示这个语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `Process_keys`：表示 Coprocessor 处理的 key 的数量。相比 total_keys，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `Cop_proc_avg`：cop-task 的平均执行时间。 -* `Cop_proc_p90`：cop-task 的 P90 分位执行时间。 -* `Cop_proc_max`：cop-task 的最大执行时间。 -* `Cop_proc_addr`：执行时间最长的 cop-task 所在地址。 -* `Cop_wait_avg`：cop-task 的平均等待时间。 -* `Cop_wait_p90`：cop-task 的 P90 分位等待时间。 -* `Cop_wait_max`：cop-task 的最大等待时间。 -* `Cop_wait_addr`：等待时间最长的 cop-task 所在地址。 - -## 慢日志内存映射表 - -用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢日志中字段名一一对应，表结构可查看 [Information Schema](/v2.1/reference/system-databases/information-schema.md#information-schema) 中关于 `SLOW_QUERY` 表的介绍。 - -> **注意：** -> -> 每次查询 `SLOW_QUERY` 表时，TiDB 都会去读取和解析一次当前的慢查询日志。 - -## 查询 `SLOW_QUERY` 示例 - -### 搜索 Top N 的慢查询 - -查询 Top 2 的用户慢查询。`is_internal=false` 表示排除 TiDB 内部的慢查询，只看用户的慢查询： - -{{< copyable "sql" >}} - -```sql -select query_time, query -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+--------------+------------------------------------------------------------------+ -| query_time | query | -+--------------+------------------------------------------------------------------+ -| 12.77583857 | select * from t_slim, t_wide where t_slim.c0=t_wide.c0; | -| 0.734982725 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c0; | -+--------------+------------------------------------------------------------------+ -``` - -### 搜索某个用户的 Top N 慢查询 - -下面例子中搜索 test 用户执行的慢查询 SQL，且按执行消耗时间逆序排序显式前 2 条： - -{{< copyable "sql" >}} - -```sql -select query_time, query, user -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL - and user = "test" -- 查找的用户名 -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+-------------+------------------------------------------------------------------+----------------+ -| Query_time | query | user | -+-------------+------------------------------------------------------------------+----------------+ -| 0.676408014 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c1; | test | -+-------------+------------------------------------------------------------------+----------------+ -``` - -### 根据 SQL 指纹搜索同类慢查询 - -在得到 Top N 的慢查询 SQL 后，可通过 SQL 指纹继续搜索同类慢查询 SQL。 - -先获取 Top N 的慢查询和对应的 SQL 指纹： - -{{< copyable "sql" >}} - -```sql -select query_time, query, digest -from information_schema.slow_query -where is_internal = false -order by query_time desc -limit 1; -``` - -输出样例： - -``` -+-------------+-----------------------------+------------------------------------------------------------------+ -| query_time | query | digest | -+-------------+-----------------------------+------------------------------------------------------------------+ -| 0.302558006 | select * from t1 where a=1; | 4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa | -+-------------+-----------------------------+------------------------------------------------------------------+ -``` - -再根据 SQL 指纹搜索同类慢查询： - -{{< copyable "sql" >}} - -```sql -select query, query_time -from information_schema.slow_query -where digest = "4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa"; -``` - -输出样例： - -``` -+-----------------------------+-------------+ -| query | query_time | -+-----------------------------+-------------+ -| select * from t1 where a=1; | 0.302558006 | -| select * from t1 where a=2; | 0.401313532 | -+-----------------------------+-------------+ -``` - -### 搜索统计信息为 pseudo 的慢查询 SQL 语句 - -{{< copyable "sql" >}} - -```sql -select query, query_time, stats -from information_schema.slow_query -where is_internal = false - and stats like '%pseudo%'; -``` - -输出样例： - -``` -+-----------------------------+-------------+---------------------------------+ -| query | query_time | stats | -+-----------------------------+-------------+---------------------------------+ -| select * from t1 where a=1; | 0.302558006 | t1:pseudo | -| select * from t1 where a=2; | 0.401313532 | t1:pseudo | -| select * from t1 where a>2; | 0.602011247 | t1:pseudo | -| select * from t1 where a>3; | 0.50077719 | t1:pseudo | -| select * from t1 join t2; | 0.931260518 | t1:407872303825682445,t2:pseudo | -+-----------------------------+-------------+---------------------------------+ -``` - -## 解析其他的 TiDB 慢日志文件 - -TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHEMA.SLOW_QUERY` 时要读取和解析的文件，可通过修改改 session 变量的值来查询其他慢查询日志文件的内容： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_query_file = "/path-to-log/tidb-slow.log" -``` - -## 用 `pt-query-digest` 工具分析 TiDB 慢日志 - -可以用 `pt-query-digest` 工具分析 TiDB 慢日志。 - -> **注意：** -> -> 建议使用 pt-query-digest 3.0.13 及以上版本。 - -示例如下： - -{{< copyable "shell" >}} - -```shell -pt-query-digest --report tidb-slow.log -``` - -输出样例： - -``` -# 320ms user time, 20ms system time, 27.00M rss, 221.32M vsz -# Current date: Mon Mar 18 13:18:51 2019 -# Hostname: localhost.localdomain -# Files: tidb-slow.log -# Overall: 1.02k total, 21 unique, 0 QPS, 0x concurrency _________________ -# Time range: 2019-03-18-12:22:16 to 2019-03-18-13:08:52 -# Attribute total min max avg 95% stddev median -# ============ ======= ======= ======= ======= ======= ======= ======= -# Exec time 218s 10ms 13s 213ms 30ms 1s 19ms -# Query size 175.37k 9 2.01k 175.89 158.58 122.36 158.58 -# Commit time 46ms 2ms 7ms 3ms 7ms 1ms 3ms -# Conn ID 71 1 16 8.88 15.25 4.06 9.83 -# Process keys 581.87k 2 103.15k 596.43 400.73 3.91k 400.73 -# Process time 31s 1ms 10s 32ms 19ms 334ms 16ms -# Request coun 1.97k 1 10 2.02 1.96 0.33 1.96 -# Total keys 636.43k 2 103.16k 652.35 793.42 3.97k 400.73 -# Txn start ts 374.38E 0 16.00E 375.48P 1.25P 89.05T 1.25P -# Wait time 943ms 1ms 19ms 1ms 2ms 1ms 972us -. -. -. -``` - -### 定位问题语句的方法 - -并不是所有 SLOW_QUERY 的语句都是有问题的。会造成集群整体压力增大的，是那些 process_time 很大的语句。wait_time 很大，但 process_time 很小的语句通常不是问题语句，是因为被问题语句阻塞，在执行队列等待造成的响应时间过长。 - -## `admin show slow` 命令 - -除了获取 TiDB 日志，还有一种定位慢查询的方式是通过 `admin show slow` SQL 命令： - -```sql -admin show slow recent N -admin show slow top [internal | all] N -``` - -`recent N` 会显示最近的 N 条慢查询记录，例如： - -```sql -admin show slow recent 10 -``` - -`top N` 则显示最近一段时间（大约几天）内，最慢的查询记录。如果指定 `internal` 选项，则返回查询系统内部 SQL 的慢查询记录；如果指定 `all` 选项，返回系统内部和用户 SQL 汇总以后的慢查询记录；默认只返回用户 SQL 中的慢查询记录。 - -```sql -admin show slow top 3 -admin show slow top internal 3 -admin show slow top all 5 -``` - -由于内存限制，保留的慢查询记录的条数是有限的。当命令查询的 `N` 大于记录条数时，返回的结果记录条数会小于 `N`。 - -输出内容详细说明，如下： - -| 列名 | 描述 | -|:------|:---- | -| start | SQL 语句执行开始时间 | -| duration | SQL 语句执行持续时间 | -| details | 执行语句的详细信息 | -| succ | SQL 语句执行是否成功，1: 成功，0: 失败 | -| conn_id | session 连接 ID | -| transcation_ts | 事务提交的 commit ts | -| user | 执行该语句的用户名 | -| db | 执行该 SQL 涉及到 database | -| table_ids | 执行该 SQL 涉及到表的 ID | -| index_ids | 执行该 SQL 涉及到索引 ID | -| internal | 表示为 TiDB 内部的 SQL 语句 | -| digest | 表示 SQL 语句的指纹 | -| sql | 执行的 SQL 语句 | diff --git a/v2.1/how-to/migrate/from-aurora.md b/v2.1/how-to/migrate/from-aurora.md deleted file mode 100644 index 2c434178cd6d..000000000000 --- a/v2.1/how-to/migrate/from-aurora.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 -summary: 使用 DM 从 MySQL/Amazon Aurora MySQL 迁移数据。 -category: how-to ---- - -# 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 - -本文介绍如何使用 DM 从 [Amazon Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/v2.1/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v2.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 - - {{< copyable "" >}} - - ```bash - start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -```bash -query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ```bash -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 `task.yaml` 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/v2.1/how-to/migrate/from-mysql.md b/v2.1/how-to/migrate/from-mysql.md deleted file mode 100644 index 1c0cd82e3e9b..000000000000 --- a/v2.1/how-to/migrate/from-mysql.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: 全量数据迁移 -category: how-to ---- - -# 全量数据迁移 - -`mydumper` 是一个强大的数据迁移工具，具体可以参考 [`maxbube/mydumper`](https://github.com/maxbube/mydumper)。你可以使用 `mydumper` 从 MySQL 导出数据，然后用 `loader` 将其导入到 TiDB。 - -> **注意：** -> -> 虽然 TiDB 也支持使用 MySQL 官方的 `mysqldump` 工具来进行数据的迁移工作，但相比于 `mydumper`/`loader`，性能会慢很多，大量数据的迁移会花费很多时间，这里我们并不推荐。 - -## `mydumper`/`loader` 全量导入数据最佳实践 - -为了快速的迁移数据 (特别是数据量巨大的库)，可以参考以下建议： - -* Mydumper 导出数据至少要拥有 `SELECT`，`RELOAD`，`LOCK TABLES` 权限 -* 使用 Mydumper 导出来的数据文件尽可能的小，最好不要超过 64M，可以设置参数 -F 64 -* loader的 `-t` 参数可以根据 TiKV 的实例个数以及负载进行评估调整，例如 3个 TiKV 的场景，此值可以设为 `3 *（1 ～ n)`；当 TiKV 负载过高，loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 可以适当调小该值，当 TiKV 负载不是太高的时候，可以适当调大该值。 - -导入示例及相关配置： - -- Mydumper 导出后总数据量 214G，单表 8 列，20 亿行数据 -- 集群拓扑 - - TiKV * 12 - - TiDB * 4 - - PD * 3 -- Mydumper `-F` 设置为 16，Loader `-t` 参数设置为 64 - -结果：导入时间 11 小时左右，19.4 G/小时 - -## 从 MySQL 导出数据 - -我们使用 `mydumper` 从 MySQL 导出数据，如下: - -```bash -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 64 -B test -T t1,t2 --skip-tz-utc -o ./var/test -``` - -上面，我们使用 `-B test` 表明是对 `test` 这个 database 操作，然后用 `-T t1,t2` 表明只导出 `t1`，`t2` 两张表。 - -`-t 16` 表明使用 16 个线程去导出数据。`-F 64` 是将实际的 table 切分成多大的 chunk，这里就是 64MB 一个 chunk。 - -`--skip-tz-utc` 添加这个参数忽略掉 MySQL 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -> **注意：** -> -> 在阿里云等一些需要 `super privilege` 的云上面，`mydumper` 需要加上 `--no-locks` 参数，否则会提示没有权限操作。 - -## 向 TiDB 导入数据 - -> **注意：** -> -> 目前 TiDB 支持 UTF8mb4 [字符编码](/v2.1/reference/sql/character-set.md)，假设 Mydumper 导出数据为 latin1 字符编码，请使用 `iconv -f latin1 -t utf-8 $file -o /data/imdbload/$basename` 命令转换，$file 为已有文件，$basename 为转换后文件。 - -> **注意：** -> -> 如果 Mydumper 使用 -m 参数，会导出不带表结构的数据，这时 loader 无法导入数据。 - -我们使用 `loader` 将之前导出的数据导入到 TiDB。Loader 的下载和具体的使用方法见 [Loader 使用文档](/v2.1/reference/tools/loader.md) - -```bash -./bin/loader -h 127.0.0.1 -u root -P 4000 -t 32 -d ./var/test -``` - -导入成功之后，我们可以用 MySQL 官方客户端进入 TiDB，查看: - -```sql -mysql -h127.0.0.1 -P4000 -uroot - -mysql> show tables; -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -| t2 | -+----------------+ - -mysql> select * from t1; -+----+------+ -| id | age | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+------+ - -mysql> select * from t2; -+----+------+ -| id | name | -+----+------+ -| 1 | a | -| 2 | b | -| 3 | c | -+----+------+ -``` diff --git a/v2.1/how-to/migrate/incrementally-from-mysql.md b/v2.1/how-to/migrate/incrementally-from-mysql.md deleted file mode 100644 index c71597019d67..000000000000 --- a/v2.1/how-to/migrate/incrementally-from-mysql.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: 增量数据复制 -category: how-to ---- - -# 增量数据复制 - -[全量迁移](/v2.1/how-to/migrate/from-mysql.md)文档中介绍了如何使用 `mydumper`/`loader` 将 MySQL 的数据全量导入到 TiDB，但如果后续 MySQL 的数据有更新，仍然希望快速导入，就不适合使用全量的方式。因此，TiDB 提供了 `syncer` 工具，可以方便地将 MySQL 的数据增量的导入到 TiDB 里面。 - -`syncer` 属于 TiDB 企业版工具集，如何获取可以参考 [下载 TiDB 企业版工具集](#下载-tidb-企业版工具集-linux)。 - -## 下载 TiDB 企业版工具集 (Linux) - -```bash -# 下载 tool 压缩包 -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256 - -# 检查文件完整性，返回 ok 则正确 -sha256sum -c tidb-enterprise-tools-latest-linux-amd64.sha256 -# 解开压缩包 -tar -xzf tidb-enterprise-tools-latest-linux-amd64.tar.gz -cd tidb-enterprise-tools-latest-linux-amd64 -``` - -假设我们之前已经使用 `mydumper`/`loader` 导入了 `t1` 和 `t2` 两张表的一些数据，现在我们希望这两张表的任何更新，都是实时的同步到 TiDB 上面。 - -## 获取同步 position - -如上文所提，Mydumper 导出的数据目录里面有一个 `metadata` 文件，里面就包含了我们所需的 position 信息。 - -medadata 文件信息内容举例： - -``` -Started dump at: 2017-04-28 10:48:10 -SHOW MASTER STATUS: - Log: mysql-bin.000003 - Pos: 930143241 - GTID: - -Finished dump at: 2017-04-28 10:48:11 -``` - -我们将 position 相关的信息保存到一个 `syncer.meta` 文件里面，用于 `syncer` 的同步: - -```bash -# cat syncer.meta -binlog-name = "mysql-bin.000003" -binlog-pos = 930143241 -binlog-gtid = "2bfabd22-fff7-11e6-97f7-f02fa73bcb01:1-23,61ccbb5d-c82d-11e6-ac2e-487b6bd31bf7:1-4" -``` - -> **注意：** -> -> - `syncer.meta` 只需要第一次使用的时候配置，后续 `syncer` 同步新的 binlog 之后会自动将其更新到最新的 position。 -> - 如果使用 binlog position 同步则只需要配置 binlog-name binlog-pos; 使用 gtid 同步则需要设置 gtid，且启动 Syncer 时带有 `--enable-gtid`。 - -## 启动 `syncer` - -启动 Syncer 服务之前请详细阅读 [Syncer 增量导入](/v2.1/reference/tools/syncer.md ) - -`syncer` 的配置文件 `config.toml`: - -```toml -log-level = "info" -log-file = "syncer.log" -log-rotate = "day" - -server-id = 101 - -## meta 文件地址 -meta = "./syncer.meta" -worker-count = 16 -batch = 1000 -flavor = "mysql" - -## pprof 调试地址，Prometheus 也可以通过该地址拉取 Syncer metrics -status-addr = ":8271" - -## 如果设置为 true，Syncer 遇到 DDL 语句时就会停止退出 -stop-on-ddl = false - -## 跳过 DDL 语句，格式为 **前缀完全匹配**，如：`DROP TABLE ABC` 至少需要填入 `DROP TABLE` -# skip-ddls = ["ALTER USER", "CREATE USER"] - -## 在使用 route-rules 功能后， -## replicate-do-db & replicate-ignore-db 匹配合表之后 (target-schema & target-table) 数值 -## 优先级关系: replicate-do-db --> replicate-do-table --> replicate-ignore-db --> replicate-ignore-table -## 指定要同步数据库名；支持正则匹配，表达式语句必须以 `~` 开始 -#replicate-do-db = ["~^b.*","s1"] - -## 指定 **忽略** 同步数据库；支持正则匹配，表达式语句必须以 `~` 开始 -#replicate-ignore-db = ["~^b.*","s1"] - -# skip-dmls 支持跳过 DML binlog events，type 字段的值可为：'insert'，'update' 和 'delete' -# 跳过 foo.bar 表的所有 delete 语句 -# [[skip-dmls]] -# db-name = "foo" -# tbl-name = "bar" -# type = "delete" -# -# 跳过所有表的 delete 语句 -# [[skip-dmls]] -# type = "delete" -# -# 跳过 foo.* 表的 delete 语句 -# [[skip-dmls]] -# db-name = "foo" -# type = "delete" - -## 指定要同步的 db.table 表 -## db-name 与 tbl-name 不支持 `db-name ="dbname，dbname2"` 格式 -#[[replicate-do-table]] -#db-name ="dbname" -#tbl-name = "table-name" - -#[[replicate-do-table]] -#db-name ="dbname1" -#tbl-name = "table-name1" - -## 指定要同步的 db.table 表；支持正则匹配，表达式语句必须以 `~` 开始 -#[[replicate-do-table]] -#db-name ="test" -#tbl-name = "~^a.*" - -## 指定 **忽略** 同步数据库 -## db-name & tbl-name 不支持 `db-name ="dbname，dbname2"` 语句格式 -#[[replicate-ignore-table]] -#db-name = "your_db" -#tbl-name = "your_table" - -## 指定要 **忽略** 同步数据库名；支持正则匹配，表达式语句必须以 `~` 开始 -#[[replicate-ignore-table]] -#db-name ="test" -#tbl-name = "~^a.*" - -# sharding 同步规则，采用 wildcharacter -# 1. 星号字符 (*) 可以匹配零个或者多个字符, -# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; -# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 -# 2. 问号字符 (?) 匹配任一一个字符 - -#[[route-rules]] -#pattern-schema = "route_*" -#pattern-table = "abc_*" -#target-schema = "route" -#target-table = "abc" - -#[[route-rules]] -#pattern-schema = "route_*" -#pattern-table = "xyz_*" -#target-schema = "route" -#target-table = "xyz" - -[from] -host = "127.0.0.1" -user = "root" -password = "" -port = 3306 - -[to] -host = "127.0.0.1" -user = "root" -password = "" -port = 4000 - -``` - -启动 `syncer`: - -```bash -./bin/syncer -config config.toml - -2016/10/27 15:22:01 binlogsyncer.go:226: [info] begin to sync binlog from position (mysql-bin.000003, 1280) -2016/10/27 15:22:01 binlogsyncer.go:130: [info] register slave for master server 127.0.0.1:3306 -2016/10/27 15:22:01 binlogsyncer.go:552: [info] rotate to (mysql-bin.000003, 1280) -2016/10/27 15:22:01 syncer.go:549: [info] rotate binlog to (mysql-bin.000003, 1280) -``` - -## 在 MySQL 插入新的数据 - -```sql -INSERT INTO t1 VALUES (4, 4), (5, 5); -``` - -登录到 TiDB 查看： - -```sql -mysql -h127.0.0.1 -P4000 -uroot -p -mysql> select * from t1; -+----+------+ -| id | age | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+------+ -``` - -`syncer` 每隔 30s 会输出当前的同步统计，如下 - -```bash -2017/06/08 01:18:51 syncer.go:934: [info] [syncer]total events = 15, total tps = 130, recent tps = 4, -master-binlog = (ON.000001, 11992), master-binlog-gtid=53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-74, -syncer-binlog = (ON.000001, 2504), syncer-binlog-gtid = 53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-17 -2017/06/08 01:19:21 syncer.go:934: [info] [syncer]total events = 15, total tps = 191, recent tps = 2, -master-binlog = (ON.000001, 11992), master-binlog-gtid=53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-74, -syncer-binlog = (ON.000001, 2504), syncer-binlog-gtid = 53ea0ed1-9bf8-11e6-8bea-64006a897c73:1-35 -``` - -可以看到，使用 `syncer`，我们就能自动的将 MySQL 的更新同步到 TiDB。 diff --git a/v2.1/how-to/migrate/overview.md b/v2.1/how-to/migrate/overview.md deleted file mode 100644 index a71a6d7d9cfc..000000000000 --- a/v2.1/how-to/migrate/overview.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 数据迁移概述 -category: how-to ---- - -# 数据迁移概述 - -本文档介绍了 TiDB 提供的数据迁移工具，以及不同迁移场景下如何选择迁移工具，从而将数据从 MySQL 或 CSV 数据源迁移到 TiDB。 - -## 迁移工具 - -在上述数据迁移过程中会用到如下工具： - -- [Mydumper](/v2.1/reference/tools/mydumper.md)：用于从 MySQL 导出数据。建议使用 Mydumper，而非 mysqldump。 -- [Loader](/v2.1/reference/tools/loader.md)：用于将 Mydumper 导出格式的数据导入到 TiDB。 -- [Syncer](/v2.1/reference/tools/syncer.md)：用于将数据从 MySQL 增量同步到 TiDB。 -- [DM (Data Migration)](/v2.1/reference/tools/data-migration/overview.md)：集成了 Mydumper、Loader、Syncer 的功能，支持 MySQL 数据的全量导出和到 TiDB 的全量导入，还支持 MySQL binlog 数据到 TiDB 的增量同步。 -- [TiDB Lightning](/v2.1/reference/tools/tidb-lightning/overview.md)：用于将全量数据高速导入到 TiDB 集群。例如，如果要导入超过 1TiB 的数据，使用 Loader 往往需花费几十个小时，而使用 TiDB-Lightning 的导入速度至少是 Loader 的三倍。 - -## 迁移场景 - -本小节将通过几个示例场景来说明如何选择和使用 TiDB 的迁移工具。 - -### MySQL 数据的全量迁移 - -要将数据从 MySQL 全量迁移至 TiDB，可以采用以下三种方案中一种： - -- **Mydumper + Loader**：先使用 Mydumper 将数据从 MySQL 导出，然后使用 Loader 将数据导入至 TiDB。 -- **Mydumper + TiDB Lightning**：先使用 Mydumper 将数据从 MySQL 导出，然后使用 TiDB Lightning 将数据导入至 TiDB。 -- **DM**：直接使用 DM 将数据从 MySQL 导出，然后将数据导入至 TiDB。 - -详细操作参见 [MySQL 数据到 TiDB 的全量迁移](/v2.1/how-to/migrate/from-mysql.md)。 - -### MySQL 数据的全量迁移和增量同步 - -- **Mydumper + Loader + Syncer**：先使用 Mydumper 将数据从 MySQL 导出，然后使用 Loader 将数据导入至 TiDB，再使用 Syncer 将 MySQL binlog 数据增量同步至 TiDB。 -- **Mydumper + TiDB Lightning + Syncer**：先使用 Mydumper 将数据从 MySQL 导出，然后使用 TiDB Lightning 将数据导入至 TiDB，再使用 Syncer 将 MySQL binlog 数据增量同步至 TiDB。 -- **DM**：先使用 DM 将数据从 MySQL 全量迁移至 TiDB，然后使用 DM 将 MySQL binlog 数据增量同步至 TiDB。 - -详细操作参见 [MySQL 数据到 TiDB 的增量同步](/v2.1/how-to/migrate/incrementally-from-mysql.md)。 - -> **注意：** -> -> 在将 MySQL binlog 数据增量同步至 TiDB 前，需要[在 MySQL 中开启 binlog 功能](http://dev.mysql.com/doc/refman/5.7/en/replication-howto-masterbaseconfig.html)，并且 binlog 必须[使用 `ROW` 格式](https://dev.mysql.com/doc/refman/5.7/en/binary-log-formats.html)。 - -### 非 MySQL 数据源的数据迁移 - -如果源数据库不是 MySQL，建议采用以下步骤进行数据迁移： - -1. 将数据导出为 CSV 格式。 -2. 使用 TiDB Lightning 将 CSV 格式的数据导入 TiDB。 - -详细操作参见[使用 TiDB Lightning 迁移 CSV 数据](/v2.1/reference/tools/tidb-lightning/csv.md)。 diff --git a/v2.1/how-to/monitor/monitor-a-cluster.md b/v2.1/how-to/monitor/monitor-a-cluster.md deleted file mode 100644 index 889142c75d1a..000000000000 --- a/v2.1/how-to/monitor/monitor-a-cluster.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: TiDB 集群监控 -category: how-to ---- - -# TiDB 集群监控 - -TiDB 集群状态监控目前有两种接口，第一种是通过 HTTP 接口对外汇报组件的信息，我们称之为组件的状态接口；第二种是使用 prometheus 记录组件中各种操作的详细信息，我们称之为 metrics 接口。 - -## 组件状态接口 - -这类接口可以获取组件的一些基本信息，并且可以作为 keepalive 监测接口。另外 PD 的接口可以看到整个 TiKV 集群的详细信息。 - -### TiDB Server - -TiDB API 地址：`http://${host}:${port}`。 - -其中 port 默认为 10080，各类 `api_name` 详细信息参见 [TiDB API Doc](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md)。 - -下面示例中，通过访问 `http://${host}:${port}/status` 获取当前 TiDB Server 的状态，以及判断是否存活。返回结果为 **Json** 格式： - -```bash -curl http://127.0.0.1:10080/status -{ - connections: 0, - version: "5.5.31-TiDB-1.0", - git_hash: "b99521846ff6f71f06e2d49a3f98fa1c1d93d91b" -} -``` - -+ `connections`：当前 TiDB Server 上的客户端连接数 - + `version`：TiDB 版本号 - + `git_hash`：TiDB 当前代码的 Git Hash - -### PD Server - -PD API 地址：`http://${host}:${port}/pd/api/v1/${api_name}`。 - -其中 port 默认为 2379，各类 api_name 详细信息参见 [PD API Doc](https://download.pingcap.com/pd-api-v1.html)。 - -通过这个接口可以获取当前所有 TiKV 的状态以及负载均衡信息。其中最重要也是最常用的接口获取 TiKV 集群所有节点状态的接口，下面以一个单个 TiKV 构成的集群为例，说明一些用户需要了解的信息： - -```bash -curl http://127.0.0.1:2379/pd/api/v1/stores -{ - "count": 1, TiKV 节点数量 - "stores": [ // TiKV 节点的列表 - // 下面列出的是这个集群中单个 TiKV 节点的信息 - { - "store": { - "id": 1, - "address": "127.0.0.1:22161", - "state": 0 - }, - "status": { - "store_id": 1, // 节点的 ID - "capacity": 1968874332160, // 存储总容量 - "available": 1264847716352, // 存储剩余容量 - "region_count": 1, // 该节点上存放的 Region 数量 - "sending_snap_count": 0, - "receiving_snap_count": 0, - "start_ts": "2016-10-24T19:54:00.110728339+08:00", // 启动时间 - "last_heartbeat_ts": "2016-10-25T10:52:54.973669928+08:00", // 最后一次心跳时间 - "total_region_count": 1, // 总 Region 数量 - "leader_region_count": 1, // Leader Region 数量 - "uptime": "14h58m54.862941589s" - }, - "scores": [ - 100, - 35 - ] - } - ] -} -``` - -## Metrics 监控 - -这部分主要对整个集群的状态、性能做监控，通过 Prometheus + Grafana 展现 metrics 数据，在下面一节会介绍如何搭建监控系统。 - -### TiDB Server - -+ query 处理时间，可以看到延迟和吞吐 -+ ddl 过程监控 -+ TiKV client 相关的监控 -+ PD client 相关的监控 - -### PD Server - -+ 命令执行的总次数 -+ 某个命令执行失败的总次数 -+ 某个命令执行成功的耗时统计 -+ 某个命令执行失败的耗时统计 -+ 某个命令执行完成并返回结果的耗时统计 - -### TiKV Server - -+ GC 监控 -+ 执行 KV 命令的总次数 -+ Scheduler 执行命令的耗时统计 -+ Raft propose 命令的总次数 -+ Raft 执行命令的耗时统计 -+ Raft 执行命令失败的总次数 -+ Raft 处理 ready 状态的总次数 - -## 使用 Prometheus + Grafana - -### 部署架构 - -整个架构如下图所示，在 TiDB/PD/TiKV 三个组件的启动参数中添加 Prometheus Pushgateway 地址: - -![Deployment Architecture](/media/monitor-architecture.png) - -### 搭建监控系统 - -- Prometheus Push Gateway 参考： -- Prometheus Server 参考： -- Grafana 参考： - -### 配置 - -#### TiDB/PD/TiKV 配置 - -+ TiDB - - 设置 \-\-metrics-addr 和 \-\-metrics-interval 两个参数，其中 metrics-addr 设为 Push Gateway 的地址，metrics-interval 为 push 的频率，单位为秒，默认值为 15 - -+ PD - - 修改 toml 配置文件，填写 Push Gateway 的地址和推送频率 - - ```toml - [metric] - # prometheus client push interval, set "0s" to disable prometheus. - interval = "15s" - # prometheus pushgateway address, leaves it empty will disable prometheus. - address = "host:port" - ``` - -+ TiKV - - 修改 toml 配置文件，填写 Push Gateway 的地址和推送频率，job 字段一般设为“tikv”。 - - ```toml - [metric] - # the Prometheus client push interval. Setting the value to 0s stops Prometheus client from pushing. - interval = "15s" - # the Prometheus pushgateway address. Leaving it empty stops Prometheus client from pushing. - address = "host:port" - # the Prometheus client push job name. Note: A node id will automatically append, e.g., "tikv_1". - job = "tikv" - ``` - -#### PushServer 配置 - -一般无需特殊配置，使用默认端口 9091 即可 - -#### Prometheus 配置 - -在 yaml 配置文件中添加 Push Gateway 地址： - -```yaml - scrape_configs: -# The job name is added as a label `job=` to any timeseries scraped from this config. -- job_name: 'TiDB' - - # Override the global default and scrape targets from this job every 5 seconds. - scrape_interval: 5s - - honor_labels: true - - static_configs: - - targets: ['host:port'] # use the Push Gateway address -labels: - group: 'production' -``` - -#### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址：，默认账号: admin 密码: admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息（注: Type 选 Prometheus，Url 为 Prometheus 地址，其他根据实际情况填写） - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 Dashboard [配置文件](https://grafana.com/tidb)上传 -> 选择对应的 data source diff --git a/v2.1/how-to/monitor/overview.md b/v2.1/how-to/monitor/overview.md deleted file mode 100644 index 326adbfd28e5..000000000000 --- a/v2.1/how-to/monitor/overview.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: TiDB 监控框架概述 -category: monitoring ---- - -# TiDB 监控框架概述 - -TiDB 使用开源时序数据库 Prometheus 作为监控和性能指标信息存储方案，使用 Grafana 作为可视化组件进行展示。 - -Prometheus 是一个拥有多维度数据模型，灵活的查询语句的时序数据库。Prometheus 作为热门的开源项目，拥有活跃的社区及众多的成功案例。 - -Prometheus 提供了多个组件供用户使用。目前，我们使用 Prometheus Server，来收集和存储时间序列数据。Client 代码库，在程序中定制需要的 Metric 。Push GateWay 来接收 Client Push 上来的数据，统一供 Prometheus 主服务器抓取。以及 AlertManager 来实现报警机制。其结构如下图： - -![Prometheus in TiDB](/media/prometheus-in-tidb-v2.1.png) - -Grafana 是一个开源的 metric 分析及可视化系统。我们使用 Grafana 来展示 TiDB 的各项性能指标。如下图所示: - -![Grafana Screeshot](/media/grafana-screenshot-v2.1.png) diff --git a/v2.1/how-to/scale/horizontally.md b/v2.1/how-to/scale/horizontally.md deleted file mode 100644 index 44a8157aca7c..000000000000 --- a/v2.1/how-to/scale/horizontally.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: TiDB 集群扩容缩容方案 -category: how-to ---- - -# TiDB 集群扩容缩容方案 - -TiDB 集群可以在不影响线上服务的情况下动态进行扩容和缩容。 - -> **注意：** -> -> 如果使用 Ansible 部署 TiDB 集群，请参考[使用 Ansible 扩容缩容](/v2.1/how-to/scale/with-ansible.md)。 - -下面分别介绍如何增加或者删除 PD，TiKV 以及 TiDB 的节点。 - -下面用到的 pd-ctl 文档可以参考 [pd-control](/v2.1/reference/tools/pd-control.md)。 - -## PD - -假设现在我们有三个 PD 服务，详细信息如下： - -|Name|ClientUrls|PeerUrls| -|----|----------|--------| -|pd1|`http://host1:2379`|`http://host1:2380`| -|pd2|`http://host2:2379`|`http://host2:2380`| -|pd3|`http://host3:2379`|`http://host3:2380`| - -我们可以通过 pd-ctl 来查看当前所有 PD 节点的信息： - -```bash -./pd-ctl -u http://host1:2379 -i ->> member -``` - -### 动态添加节点 - -我们可以使用 `join` 参数，将一个新的 PD 服务加入到现有的 PD 集群里面。 -如果我们需要添加 `pd4`，只需要在 `--join` 参数里面填入当前 PD 集群任意一个 PD 服务的 client url，比如： - -```bash -./bin/pd-server --name=pd4 \ - --client-urls="http://host4:2379" \ - --peer-urls="http://host4:2380" \ - --join="http://host1:2379" -``` - -### 动态删除节点 - -如果我们需要删除 `pd4`，可以通过 pd-ctl 来完成： - -```bash -./pd-ctl -u http://host1:2379 ->> member delete name pd4 -``` - -### 动态迁移节点 - -如果想把现有的 PD 节点迁移到新的机器上，我们可以先在新的机器上添加节点，然后把旧的机器上的节点删除掉。迁移过程中应该一个节点一个节点逐个迁移，每完成一个步骤可以先查看一下当前的所有节点信息来进行确认。 - -## TiKV - -我们可以通过 pd-ctl 来查看当前所有 TiKV 节点的信息： - -```bash -./pd-ctl -u http://host1:2379 ->> store -``` - -### 动态添加节点 - -动态添加一个新的 TiKV 服务非常容易，只需要在新的机器上启动一个 TiKV 服务，不需要其他特殊操作。 -新启动的 TiKV 服务会自动注册到现有集群的 PD 中，PD 会自动做负载均衡，逐步地把一部分数据迁移到新的TiKV 服务中，从而降低现有 TiKV 服务的压力。 - -### 动态删除节点 - -安全地删除（下线）一个 TiKV 服务需要先告诉 PD，这样 PD 可以先把这个 TiKV 服务上面的数据迁移到其他 TiKV 服务上，保证数据有足够的副本数。 - -假设我们需要删除 store id 为 1 的 TiKV 服务，可以通过 pd-ctl 来完成： - -```bash -./pd-ctl -u http://host1:2379 ->> store delete 1 -``` - -然后可以查看这个 TiKV 服务的状态： - -```bash -./pd-ctl -u http://host1:2379 ->> store 1 -{ - "store": { - "id": 1, - "address": "127.0.0.1:21060", - "state": 1, - "state_name": "Offline" - }, - "status": { - ... - } -} -``` - -我们可以通过这个 store 的 state_name 来确定这个 store 的状态： - -- Up：这个 store 正常服务 -- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 -- Down：超过一小时（可通过 `max-down-time` 配置）没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 -- Offline：这个 store 正在将其中的 Region 转移到其他节点，此时这个 store 仍在服务中 -- Tombstone：这个 store 已经完成下线，此时 store 上已经没有数据，可以关闭实例 - -### 动态迁移节点 - -迁移 TiKV 服务也是通过先在新的机器上添加节点，然后把旧的机器上的节点下线来完成。迁移过程中可以先把新集群的机器全部添加到已有的集群中，然后再把旧的节点一个一个地下线。可以通过查看正在下线的节点的状态信息来确定这个节点是否已经完成下线，确认完成以后再下线下一个节点。 - -## TiDB - -TiDB 是一个无状态的服务，这也就意味着我们能直接添加和删除 TiDB。需要注意的是，如果我们在 TiDB 的服务的前面搭建了一个 proxy（譬如 HAProxy），则需要更新 proxy 的配置并重新载入。 diff --git a/v2.1/how-to/scale/with-ansible.md b/v2.1/how-to/scale/with-ansible.md deleted file mode 100644 index 30246150d321..000000000000 --- a/v2.1/how-to/scale/with-ansible.md +++ /dev/null @@ -1,475 +0,0 @@ ---- -title: 使用 TiDB Ansible 扩容缩容 TiDB 集群 -category: how-to ---- - -# 使用 TiDB Ansible 扩容缩容 TiDB 集群 - -TiDB 集群可以在不影响线上服务的情况下进行扩容和缩容。 - -> **注意：** -> -> 以下缩容示例中，被移除的节点没有混合部署其他服务；如果混合部署了其他服务，不能按如下操作。 - -假设拓扑结构如下所示： - -| Name | Host IP | Services | -| ---- | ------- | -------- | -| node1 | 172.16.10.1 | PD1 | -| node2 | 172.16.10.2 | PD2 | -| node3 | 172.16.10.3 | PD3, Monitor | -| node4 | 172.16.10.4 | TiDB1 | -| node5 | 172.16.10.5 | TiDB2 | -| node6 | 172.16.10.6 | TiKV1 | -| node7 | 172.16.10.7 | TiKV2 | -| node8 | 172.16.10.8 | TiKV3 | -| node9 | 172.16.10.9 | TiKV4 | - -## 扩容 TiDB/TiKV 节点 - -例如，如果要添加两个 TiDB 节点（node101、node102），IP 地址为 172.16.10.101、172.16.10.102，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.101 - 172.16.10.102 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - 172.16.10.101 - 172.16.10.102 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | **node101** | **172.16.10.101**|**TiDB3** | - | **node102** | **172.16.10.102**|**TiDB4** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - ``` - ansible-playbook bootstrap.yml -l 172.16.10.101,172.16.10.102 - ``` - - > **注意：** - > - > 如果 `inventory.ini` 中为节点配置了别名，如 `node101 ansible_host=172.16.10.101`，执行 ansible-playbook 时 -l 请指定别名，以下步骤类似。例如：`ansible-playbook bootstrap.yml -l node101,node102` - -3. 部署新增节点： - - ``` - ansible-playbook deploy.yml -l 172.16.10.101,172.16.10.102 - ``` - -4. 启动新节点服务： - - ``` - ansible-playbook start.yml -l 172.16.10.101,172.16.10.102 - ``` - -5. 更新 Prometheus 配置并重启： - - ``` - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - - 可使用同样的步骤添加 TiKV 节点。但如果要添加 PD 节点，则需手动更新一些配置文件。 - -## 扩容 PD 节点 - -例如，如果要添加一个 PD 节点（node103），IP 地址为 172.16.10.103，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息置于 `[pd_servers]` 主机组最后一行： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | **node103** | **172.16.10.103** | **PD4** | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - ``` - ansible-playbook bootstrap.yml -l 172.16.10.103 - ``` - -3. 部署新增节点： - - ``` - ansible-playbook deploy.yml -l 172.16.10.103 - ``` - -4. 登录新增的 PD 节点，编辑启动脚本：`{deploy_dir}/scripts/run_pd.sh` - - 1. 移除 `--initial-cluster="xxxx" \` 配置，注意这里不能在行开头加注释符 #。 - - 2. 添加 `--join="http://172.16.10.1:2379" \`，IP 地址 （172.16.10.1） 可以是集群内现有 PD IP 地址中的任意一个。 - - 3. 在新增 PD 节点中手动启动 PD 服务： - - ``` - {deploy_dir}/scripts/start_pd.sh - ``` - - 4. 使用 `pd-ctl` 检查新节点是否添加成功： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -5. 滚动升级整个集群： - - ``` - ansible-playbook rolling_update.yml - ``` - -6. 启动监控服务： - - ``` - ansible-playbook start.yml -l 172.16.10.103 - ``` - -7. 更新 Prometheus 配置并重启： - - ``` - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -8. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - -## 缩容 TiDB 节点 - -例如，如果要移除一个 TiDB 节点（node5），IP 地址为 172.16.10.5，可以进行如下操作： - -1. 停止 node5 节点上的服务： - - ``` - ansible-playbook stop.yml -l 172.16.10.5 - ``` - -2. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | **node5** | **172.16.10.5** | **TiDB2 已删除** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -3. 更新 Prometheus 配置并重启： - - ``` - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -4. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 TiKV 节点 - -例如，如果要移除一个 TiKV 节点（node9），IP 地址为 172.16.10.9，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node9 节点的 store id： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store - ``` - - 2. 从集群中移除 node9，假如 store id 为 10： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store delete 10 - ``` - -2. 使用 Grafana 或者 `pd-ctl` 检查节点是否下线成功（下线需要一定时间，下线节点的状态变为 Tombstone 就说明下线成功了）： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store 10 - ``` - -3. 下线成功后，停止 node9 上的服务： - - ``` - ansible-playbook stop.yml -l 172.16.10.9 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | **node9** | **172.16.10.9** | **TiKV4 已删除** | - -5. 更新 Prometheus 配置并重启： - - ``` - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 PD 节点 - -例如，如果要移除一个 PD 节点（node2），IP 地址为 172.16.10.2，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node2 节点的 name： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - - 2. 从集群中移除 node2，假如 name 为 pd2： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member delete name pd2 - ``` - -2. 使用 `pd-ctl` 检查节点是否下线成功（PD 下线会很快，结果中没有 node2 节点信息即为下线成功）： - - ``` - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -3. 下线成功后，停止 node2 上的服务： - - ``` - ansible-playbook stop.yml -l 172.16.10.2 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | **node2** | **172.16.10.2** | **PD2 已删除** | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -5. 滚动升级整个集群： - - ``` - ansible-playbook rolling_update.yml - ``` - -6. 更新 Prometheus 配置并重启： - - ``` - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -7. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 diff --git a/v2.1/how-to/secure/enable-tls-between-components.md b/v2.1/how-to/secure/enable-tls-between-components.md deleted file mode 100644 index 42ed0b94d17a..000000000000 --- a/v2.1/how-to/secure/enable-tls-between-components.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: 为 TiDB 组件间开启 TLS 和数据加密存储 -category: how-to ---- - -# 为 TiDB 组件间开启 TLS 和数据加密存储 - -本文档介绍 TiDB 集群如何开启 TLS 验证和数据加密存储。 - -## 开启 TLS 验证 - -本部分介绍 TiDB 集群如何开启 TLS 验证，TLS 验证支持： - -- TiDB 组件之间的双向验证，包括 TiDB、TiKV、PD 相互之间，TiKV Control 与 TiKV、PD Control 与 PD 的双向认证，以及 TiKV peer 之间、PD peer 之间。一旦开启，所有组件之间均使用验证，不支持只开启某一部分的验证。 -- MySQL Client 与 TiDB 之间的客户端对服务器身份的单向验证以及双向验证。 - -MySQL Client 与 TiDB 之间使用一套证书，TiDB 集群组件之间使用另外一套证书。 - -### TiDB 集群组件间开启 TLS（双向认证） - -1. 准备证书。 - - 推荐为 TiDB、TiKV、PD 分别准备一个 server 证书，并保证可以相互验证，而它们的各种客户端共用 client 证书。 - - 有多种工具可以生成自签名证书，如 `openssl`，`easy-rsa`，`cfssl`。 - - 这里提供一个使用 `cfssl` 生成证书的示例：[生成自签名证书](/v2.1/how-to/secure/generate-self-signed-certificates.md)。 - -2. 配置证书。 - - - TiDB - - 在 `config` 文件或命令行参数中设置： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs for connection with cluster components. - cluster-ssl-ca = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format for connection with cluster components. - cluster-ssl-cert = "/path/to/tidb-server.pem" - # Path of file that contains X509 key in PEM format for connection with cluster components. - cluster-ssl-key = "/path/to/tidb-server-key.pem" - ``` - - - TiKV - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # set the path for certificates. Empty string means disabling secure connectoins. - ca-path = "/path/to/ca.pem" - cert-path = "/path/to/tikv-server.pem" - key-path = "/path/to/tikv-server-key.pem" - ``` - - - PD - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs. if set, following four settings shouldn't be empty - cacert-path = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format. - cert-path = "/path/to/pd-server.pem" - # Path of file that contains X509 key in PEM format. - key-path = "/path/to/pd-server-key.pem" - ``` - - 此时 TiDB 集群各个组件间已开启双向验证。 - -> **注意：** -> -> 若 TiDB 集群各个组件间已开启 TLS，在使用 tikv-ctl 或 pd-ctl 工具连接集群时，需要指定 client 证书，示例： - -```bash -./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem - -./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/clinet-key.pem" -``` - -### MySQL 与 TiDB 间开启 TLS - -请参考 [使用加密连接](/v2.1/how-to/secure/enable-tls-clients.md)。 - -## 开启数据加密存储 - -在 TiDB 集群中，用户的数据都存储在 TiKV 中，配置了 TiKV 数据加密存储功能，就代表 TiDB 集群已经加密存储了用户的数据。本部分主要介绍如何配置 TiKV 的加密存储功能。 - -### 操作流程 - -1. 生成 token 文件。 - - token 文件存储的是密钥，用于对用户数据进行加密，以及对已加密的数据进行解密。 - - ```bash - ./tikv-ctl random-hex --len 256 > cipher-file-256 - ``` - - > **注意：** - > - > TiKV 只接受 hex 格式的 token 文件，文件的长度必须是 2^n，并且小于等于 1024。 - -2. 配置 TiKV。 - - ```toml - [security] - # Cipher file 的存储路径 - cipher-file = "/path/to/cipher-file-256" - ``` - -> **注意：** -> -> 若使用 [Lightning](/v2.1/reference/tools/tidb-lightning/overview.md) 向集群导入数据，如果目标集群开启了加密功能，Lightning 生成的 sst 文件也必须是加密的格式。 - -### 使用限制 - -目前 TiKV 数据加密存储存在以下限制： - -- 对之前没有开启加密存储的集群，不支持开启该功能。 -- 已经开启加密功能的集群，不允许关闭加密存储功能。 -- 同一集群内部，不允许部分 TiKV 实例开启该功能，部分 TiKV 实例不开启该功能。对于加密存储功能，所有 TiKV 实例要么都开启该功能，要么都不开启该功能。这是由于 TiKV 实例之间会有数据迁移，如果开启了加密存储功能，迁移过程中数据也是加密的。 diff --git a/v2.1/how-to/secure/enable-tls-clients.md b/v2.1/how-to/secure/enable-tls-clients.md deleted file mode 100644 index 8ee2d8418198..000000000000 --- a/v2.1/how-to/secure/enable-tls-clients.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: 使用加密连接 -category: how-to ---- - -# 使用加密连接 - -TiDB 服务端默认采用非加密连接，因而具备监视信道流量能力的第三方可以知悉 TiDB 服务端与客户端之间发送和接受的数据，包括但不限于查询语句内容、查询结果等。若信道是不可信的，例如客户端是通过公网连接到 TiDB 服务端的，则非加密连接容易造成信息泄露，建议使用加密连接确保安全性。 - -TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接，协议与 MySQL 加密连接一致，现有 MySQL 客户端如 MySQL 运维工具和 MySQL 驱动等能直接支持。TLS 的前身是 SSL，因而 TLS 有时也被称为 SSL，但由于 SSL 协议有已知安全漏洞，TiDB 实际上并未支持。TiDB 支持的 TLS/SSL 协议版本为 TLS 1.0、TLS 1.1、TLS 1.2。 - -使用加密连接后，连接将具有以下安全性质： - -- 保密性：流量明文无法被窃听； -- 完整性：流量明文无法被篡改； -- 身份验证（可选）：客户端和服务端能验证双方身份，避免中间人攻击。 - -TiDB 的加密连接支持默认是关闭的，必须在 TiDB 服务端通过配置开启加密连接的支持后，才能在客户端中使用加密连接。另外，与 MySQL 一致，TiDB 加密连接是以单个连接为单位的，并且是可选的，因而对于开启了加密连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。大部分 MySQL 客户端默认不采用加密连接，因此一般还要显式地要求客户端使用加密连接。 - -简单来说，要使用加密连接必须同时满足以下两个条件： - -1. TiDB 服务端配置开启加密连接的支持 -2. 客户端指定使用加密连接 - -## 配置 TiDB 启用加密连接支持 - -在启动 TiDB 时，至少需要在配置文件中同时指定 `ssl-cert` 和 `ssl-key` 参数，才能使 TiDB 服务端接受加密连接。还可以指定 `ssl-ca` 参数进行客户端身份验证（请参见[配置启用身份验证](#配置启用身份验证)章节）。 - -- [`ssl-cert`](/v2.1/reference/configuration/tidb-server/configuration-file.md#ssl-cert)：指定 SSL 证书文件路径 -- [`ssl-key`](/v2.1/reference/configuration/tidb-server/configuration-file.md#ssl-key)：指定证书文件对应的私钥 -- [`ssl-ca`](/v2.1/reference/configuration/tidb-server/configuration-file.md#ssl-ca)：可选，指定受信任的 CA 证书文件路径 - -参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端加密连接到 TiDB 服务端。 - -上述证书及密钥可以使用 OpenSSL 签发和生成，也可以使用 MySQL 自带的工具 `mysql_ssl_rsa_setup` 快捷生成： - -```bash -mysql_ssl_rsa_setup --datadir=./certs -``` - -以上命令将在 `certs` 目录下生成以下文件： - -``` -certs -├── ca-key.pem -├── ca.pem -├── client-cert.pem -├── client-key.pem -├── private_key.pem -├── public_key.pem -├── server-cert.pem -└── server-key.pem -``` - -对应的 TiDB 配置文件参数为： - -```toml -[security] -ssl-cert = "certs/server-cert.pem" -ssl-key = "certs/server-key.pem" -``` - -若证书参数无误，则 TiDB 在启动时将会输出 `Secure connection is enabled`，否则 TiDB 会输出 `Secure connection is NOT ENABLED`。 - -## 配置 MySQL 客户端使用加密连接 - -MySQL 5.7 及以上版本自带的客户端默认尝试使用安全连接，若服务端不支持安全连接则自动退回到使用非安全连接；MySQL 5.7 以下版本自带的客户端默认采用非安全连接。 - -可以通过命令行参数修改客户端的连接行为，包括： - -- 强制使用安全连接，若服务端不支持安全连接则连接失败 (`--ssl-mode=REQUIRED`) -- 尝试使用安全连接，若服务端不支持安全连接则退回使用不安全连接 -- 使用不安全连接 (`--ssl-mode=DISABLED`) - -详细信息请参阅 MySQL 文档中关于[客户端配置安全连接](https://dev.mysql.com/doc/refman/5.7/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration)的部分。 - -## 配置启用身份验证 - -若在 TiDB 服务端或 MySQL 客户端中未指定 `ssl-ca` 参数，则默认不会进行客户端或服务端身份验证，无法抵御中间人攻击，例如客户端可能会“安全地”连接到了一个伪装的服务端。可以在服务端和客户端中配置 `ssl-ca` 参数进行身份验证。一般情况下只需验证服务端身份，但也可以验证客户端身份进一步增强安全性。 - -- 若要使 MySQL 客户端验证 TiDB 服务端身份，TiDB 服务端需至少配置 `ssl-cert` 和 `ssl-key` 参数，客户端需至少指定 `--ssl-ca` 参数，且 `--ssl-mode` 至少为 `VERIFY_CA`。必须确保 TiDB 服务端配置的证书（`ssl-cert`）是由客户端 `--ssl-ca` 参数所指定的 CA 所签发的，否则身份验证失败。 -- 若要使 TiDB 服务端验证 MySQL 客户端身份，TiDB 服务端需配置 `ssl-cert`、`ssl-key`、`ssl-ca` 参数，客户端需至少指定 `--ssl-cert`、`--ssl-key` 参数。必须确保服务端配置的证书和客户端配置的证书都是由服务端配置指定的 `ssl-ca` 签发的。 -- 若要进行双向身份验证，请同时满足上述要求。 - -> **注意：** -> -> 目前 TiDB 尚不支持强制验证客户端身份，即服务端对客户端的身份验证是可选的。若客户端在 TLS 握手时未出示自己的身份证书，也能正常建立 TLS 连接。 - -## 检查当前连接是否是加密连接 - -可以通过 `SHOW STATUS LIKE "%Ssl%";` 了解当前连接的详细情况，包括是否使用了安全连接、安全连接采用的加密协议、TLS 版本号等。 - -以下是一个安全连接中执行该语句的结果。由于客户端支持的 TLS 版本号和加密协议会有所不同，执行结果相应地也会有所变化。 - -```sql -mysql> SHOW STATUS LIKE "%Ssl%"; -...... -| Ssl_verify_mode | 5 | -| Ssl_version | TLSv1.2 | -| Ssl_cipher | ECDHE-RSA-AES128-GCM-SHA256 | -...... -``` - -除此以外，对于 MySQL 自带客户端，还可以使用 `STATUS` 或 `\s` 语句查看连接情况： - -```sql -mysql> \s -... -SSL: Cipher in use is ECDHE-RSA-AES128-GCM-SHA256 -... -``` - -## 支持的 TLS 版本及密钥交换协议和加密算法 - -TiDB 支持的 TLS 版本及密钥交换协议和加密算法由 Golang 官方库决定。 - -### 支持的 TLS 版本 - -- TLS 1.0 -- TLS 1.1 -- TLS 1.2 - -### 支持的密钥交换协议及加密算法 - -- TLS\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 -- TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 diff --git a/v2.1/how-to/secure/generate-self-signed-certificates.md b/v2.1/how-to/secure/generate-self-signed-certificates.md deleted file mode 100644 index 13a6fca62e5c..000000000000 --- a/v2.1/how-to/secure/generate-self-signed-certificates.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: 生成自签名证书 -category: how-to ---- - -# 生成自签名证书 - -## 概述 - -本文档提供使用 `cfssl` 生成自签名证书的示例。 - -假设实例集群拓扑如下： - -| Name | Host IP | Services | -| ----- | ----------- | ---------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -## 下载 cfssl - -假设使用 x86_64 Linux 主机： - -```bash -mkdir ~/bin -curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64 -curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64 -chmod +x ~/bin/{cfssl,cfssljson} -export PATH=$PATH:~/bin -``` - -## 初始化证书颁发机构 - -生成 cfssl 的默认配置，以便于之后修改： - -```bash -mkdir ~/cfssl -cd ~/cfssl -cfssl print-defaults config > ca-config.json -cfssl print-defaults csr > ca-csr.json -``` - -## 生成证书 - -### 证书介绍 - -- tidb-server certificate 由 TiDB 使用，为其他组件和客户端验证 TiDB 身份。 -- tikv-server certificate 由 TiKV 使用，为其他组件和客户端验证 TiKV 身份。 -- pd-server certificate 由 PD 使用，为其他组件和客户端验证 PD 身份。 -- client certificate 用于通过 PD、TiKV、TiDB 验证客户端。例如 `pd-ctl`，`tikv-ctl`，`pd-recover`。 - -### 配置 CA 选项 - -根据实际需求修改 `ca-config.json`： - -```json -{ - "signing": { - "default": { - "expiry": "43800h" - }, - "profiles": { - "server": { - "expiry": "43800h", - "usages": [ - "signing", - "key encipherment", - "server auth", - "client auth" - ] - }, - "client": { - "expiry": "43800h", - "usages": [ - "signing", - "key encipherment", - "client auth" - ] - } - } - } -} -``` - -根据实际需求修改 `ca-csr.json` ： - -```json -{ - "CN": "My own CA", - "key": { - "algo": "rsa", - "size": 2048 - }, - "names": [ - { - "C": "CN", - "L": "Beijing", - "O": "PingCAP", - "ST": "Beijing" - } - ] -} -``` - -### 生成 CA 证书 - -```bash -cfssl gencert -initca ca-csr.json | cfssljson -bare ca - -``` - -将会生成以下几个文件： - -```bash -ca-key.pem -ca.csr -ca.pem -``` - -### 生成服务器端证书 - -`hostname` 中为各组件的 IP 地址，以及 `127.0.0.1` - -```bash -echo '{"CN":"tidb-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,127.0.0.1" - | cfssljson -bare tidb-server - -echo '{"CN":"tikv-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.4,172.16.10.5,172.16.10.6,127.0.0.1" - | cfssljson -bare tikv-server - -echo '{"CN":"pd-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,172.16.10.3,127.0.0.1" - | cfssljson -bare pd-server -``` - -将会生成以下几个文件： - -```Bash -tidb-server-key.pem tikv-server-key.pem pd-server-key.pem -tidb-server.csr tikv-server.csr pd-server.csr -tidb-server.pem tikv-server.pem pd-server.pem -``` - -#### 生成客户端证书 - -```bash -echo '{"CN":"client","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client -hostname="" - | cfssljson -bare client -``` - -将会生成以下几个文件： - -```bash -client-key.pem -client.csr -client.pem -``` diff --git a/v2.1/how-to/troubleshoot/cluster-setup.md b/v2.1/how-to/troubleshoot/cluster-setup.md deleted file mode 100644 index 1a2b8af09158..000000000000 --- a/v2.1/how-to/troubleshoot/cluster-setup.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: TiDB 集群故障诊断 -category: how-to ---- - -# TiDB 集群故障诊断 - -当试用 TiDB 遇到问题时，请先参考本篇文档。如果问题未解决，请按文档要求收集必要的信息通过 Github [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - -## 如何给 TiDB 开发者报告错误 - -当使用 TiDB 遇到问题并且通过后面所列信息无法解决时，请收集以下信息并[创建新 Issue](https://github.com/pingcap/tidb/issues/new/choose): - -+ 具体的出错信息以及正在执行的操作 -+ 当前所有组件的状态 -+ 出问题组件 log 中的 error/fatal/panic 信息 -+ 机器配置以及部署拓扑 -+ dmesg 中 TiDB 组件相关的问题 - -## 数据库连接不上 - -首先请确认集群的各项服务是否已经启动，包括 tidb-server、pd-server、tikv-server。请用 ps 命令查看所有进程是否在。如果某个组件的进程已经不在了，请参考对应的章节排查错误。 - -如果所有的进程都在，请查看 tidb-server 的日志，看是否有报错？常见的错误包括： - -+ InformationSchema is out of date - - 无法连接 tikv-server，请检查 pd-server 以及 tikv-server 的状态和日志。 - -+ panic - - 程序有错误，请将具体的 panic log [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - - 如果是清空数据并重新部署服务，请确认以下信息： - -+ pd-server、tikv-server 数据都已清空 - - tikv-server 存储具体的数据，pd-server 存储 tikv-server 中数据的的元信息。如果只清空 pd-server 或只清空 tikv-server 的数据，会导致两边数据不匹配。 - -+ 清空 pd-server 和 tikv-server 的数据并重启后，也需要重启 tidb-server - - 集群 ID 是由 pd-server 在集群初始化时随机分配，所以重新部署集群后，集群 ID 会发生变化。tidb-server 业务需要重启以获取新的集群 ID。 - -## tidb-server 启动报错 - -tidb-server 无法启动的常见情况包括： - -+ 启动参数错误 - - 请参考[TiDB 命令行参数](/v2.1/reference/configuration/tidb-server/configuration.md) - -+ 端口被占用：`lsof -i:port` - - 请确保 tidb-server 启动所需要的端口未被占用。 - -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志，确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tidb-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。 - - 例如，假设 tidb 服务位于 `192.168.1.100`，无法连接的 pd 位于 `192.168.1.101`，且 2379 为其 client port， - 则可以在 tidb 机器上执行 `nc -v -z 192.168.1.101 2379`，测试是否可以访问端口。 - 或使用 `curl -v 192.168.1.101:2379/pd/api/v1/leader` 直接检查 pd 是否正常服务。 - -## tikv-server 启动报错 - -+ 启动参数错误 - - 请参考[TiKV 启动参数](/v2.1/reference/configuration/tikv-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 tikv-server 启动所需要的端口未被占用： `lsof -i:port`。 -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志。确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tikv-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。具体命令参考上一节。 - -+ 文件被占用 - - 不要在一个数据库文件目录上打开两个 tikv。 - -## pd-server 启动报错 - -+ 启动参数错误 - - 请参考[PD 命令行参数](/v2.1/reference/configuration/pd-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 pd-server 启动所需要的端口未被占用： `lsof -i:port`。 - -## TiDB/TiKV/PD 进程异常退出 - -+ 进程是否是启动在前台 - - 当前终端退出给其所有子进程发送 HUP 信号，从而导致进程退出。 -+ 是否是在命令行用过 `nohup+&` 方式直接运行 - - 这样依然可能导致进程因终端连接突然中断，作为终端 SHELL 的子进程被杀掉。 - 推荐将启动命令写在脚本中，通过脚本运行（相当于二次 fork 启动）。 - -## TiKV 进程异常重启 - -+ 检查 dmesg 或者 syslog 里面是否有 OOM 信息 - - 如果有 OOM 信息并且杀掉的进程为 TiKV，请减少 TiKV 的 RocksDB 的各个 CF 的 `block-cache-size` 值。 - -+ 检查 TiKV 日志是否有 panic 的 log - - 提交 Issue 并附上 panic 的 log。 - -## TiDB panic - -请提供 panic 的 log - -## 连接被拒绝 - -+ 请确保操作系统的网络参数正确，包括但不限于 - - 连接字符串中的端口和 tidb-server 启动的端口需要一致 - - 请保证防火墙的配置正确 - -## Too many open files - -在启动进程之前，请确保 `ulimit -n` 的结果足够大，推荐设为 unlimited 或者是大于 1000000。 - -## 数据库访问超时，系统负载高 - -首先检查 [SLOW-QUERY](/v2.1/how-to/maintain/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息： - -+ 部署的拓扑结构 - - tidb-server/pd-server/tikv-server 部署了几个实例 - - 这些实例在机器上是如何分布的 -+ 机器的硬件配置 - - CPU 核数 - - 内存大小 - - 硬盘类型（SSD 还是机械硬盘） - - 是实体机还是虚拟机 -+ 机器上除了 TiDB 集群之外是否还有其他服务 -+ pd-server 和 tikv-server 是否分开部署 -+ 目前正在进行什么操作 -+ 用 `top -H` 命令查看当前占用 CPU 的线程名 -+ 最近一段时间的网络/IO 监控数据是否有异常 diff --git a/v2.1/how-to/troubleshoot/tidb-lightning.md b/v2.1/how-to/troubleshoot/tidb-lightning.md deleted file mode 100644 index fa9fb95aef71..000000000000 --- a/v2.1/how-to/troubleshoot/tidb-lightning.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: TiDB Lightning 错误排解 -category: reference ---- - -# TiDB Lightning 错误排解 - -当 Lightning 遇到不可恢复的错误时便会异常退出，并在日志中记下错误原因。一般可在日志底部找到，也可以搜索 `[error]` 字符串找出中间发生的错误。本文主要描述一些常见的错误及其解决方法。 - -## 导入速度太慢 - -TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件，如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 `restore chunk … takes` 的记录，或者观察 Grafana 的监控信息。 - -导入速度太慢一般有几个原因： - -**原因 1**：`region-concurrency` 设定太高，线程间争用资源反而减低了效率。 - -1. 从日志的开头搜寻 `region-concurrency` 能知道 Lightning 读到的参数是多少。 -2. 如果 Lightning 与其他服务（如 Importer）共用一台服务器，必需**手动**将 `region-concurrency` 设为该服务器 CPU 数量的 75%。 -3. 如果 CPU 设有限额（例如从 K8s 指定的上限），Lightning 可能无法自动判断出来，此时亦需要**手动**调整 `region-concurrency`。 - -**原因 2**：表结构太复杂。 - -每条索引都会额外增加 KV 对。如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 - -**原因 3**：Lightning 版本太旧。 - -试试最新的版本吧！可能会有改善。 - -## checksum failed: checksum mismatched remote vs local - -**原因**：本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因： - -1. 这张表可能本身已有数据，影响最终结果。 -2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。 -3. 如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如： - - * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。 - * 单一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。 - -**解决办法**： - -1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。 - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。 - -## Checkpoint for … has invalid status:（错误码） - -**原因**：[断点续传](/v2.1/reference/tools/tidb-lightning/checkpoints.md)已启用。Lightning 或 Importer 之前发生了异常退出。为了防止数据意外损坏，Lightning 在错误解决以前不会启动。 - -错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。 - -**解决办法**： - -如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。 - -```sh -tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all -``` - -其他解决方法请参考[断点续传的控制](/v2.1/reference/tools/tidb-lightning/checkpoints.md#断点续传的控制)。 - -## ResourceTemporarilyUnavailable("Too many open engines …: 8") - -**原因**：并行打开的引擎文件 (engine files) 超出 `tikv-importer` 里的限制。这可能由配置错误引起。即使配置没问题，如果 `tidb-lightning` 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。 - -**解决办法**： - -1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为： - - 最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number` - -2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。 - -3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录： - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -## cannot guess encoding for input file, please convert to UTF-8 manually - -**原因**：Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如，因为在不同的环境运行过 `ALTER TABLE`，使表架构同时出现 UTF-8 和 GB-18030 的字符。 - -**解决办法**： - -1. 编辑数据源，保存为纯 UTF-8 或 GB-18030 的文件。 -2. 手动在目标数量库创建所有的表，然后设置 `[mydumper] no-schema = true` 跳过创建表的步骤。 -3. 设置 `[mydumper] character-set = "binary"` 跳过这个检查。但是这样可能使数据库出现乱码。 - -## [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 0 45 0 0}' - -**原因**: 一个 `timestamp` 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。 - -**解决办法**: - -1. 确保 Lightning 与数据源时区一致。 - - * 使用 Ansible 部署的话，修正 [`inventory.ini`] 下的 `timezone` 变量。 - - ```ini - # inventory.ini - [all:vars] - timezone = Asia/Shanghai - ``` - - * 手动部署的话，通过设定 `$TZ` 环境变量强制时区设定。 - - ```sh - # 强制使用 Asia/Shanghai 时区 - TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml - ``` - -2. 导出数据时，必须加上 `--skip-tz-utc` 选项。 diff --git a/v2.1/how-to/upgrade/from-previous-version.md b/v2.1/how-to/upgrade/from-previous-version.md deleted file mode 100644 index 64da77773d60..000000000000 --- a/v2.1/how-to/upgrade/from-previous-version.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: TiDB 2.1 升级操作指南 -category: how-to -aliases: ['/docs-cn/op-guide/tidb-v2.1-upgrade-guide/','/docs-cn/v2.1/how-to/upgrade/to-tidb-2.1/','/docs-cn/dev/how-to/upgrade/to-tidb-2.1/','/docs-cn/v3.0/how-to/upgrade/to-tidb-2.1/',/docs-cn/v3.1/how-to/upgrade/to-tidb-2.1/,'/docs-cn/v2.1/how-to/upgrade/rolling-updates-with-ansible/'] ---- - -# TiDB 2.1 升级操作指南 - -本文档适用于从 TiDB 2.0 版本升级至 TiDB 2.1 版本以及 TiDB 2.1 低版本升级至 TiDB 2.1 高版本。TiDB 2.1 版本不兼容 Kafka 版本的 TiDB Binlog，如果当前集群已经使用 [Kafka 版本的 TiDB Binlog](/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md)，须参考 [TiDB Binlog Cluster 版本升级方法](/v2.1/reference/tidb-binlog/upgrade.md) 升级到 Cluster 版本。 - -## 升级兼容性说明 - -- 新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 -- 从 2.0.6 之前的版本升级到 2.1 之前，需要确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 `Add Index` 操作，等 DDL 操作完成后再执行升级操作 -- 2.1 版本启用了并行 DDL，早于 2.0.1 版本的集群，无法滚动升级到 2.1，可以选择下面两种方案： - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 2.1 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 2.1 版本 - -## 注意事项 - -在升级的过程中不要执行 DDL 请求，否则可能会出现行为未定义的问题。 - -## 在中控机器上安装 Ansible 及其依赖 - -TiDB Ansible release-2.1 版本依赖 2.4.2 及以上但不高于 2.7.11 的 Ansible 版本（`2.4.2 ≦ ansible < 2.7.11`），另依赖 Python 模块：`jinja2 ≧ 2.9.6` 和 `jmespath ≧ 0.9.0`。为方便管理依赖，新版本使用 `pip` 安装 Ansible 及其依赖，可参照[在中控机器上安装 Ansible 及其依赖](/v2.1/how-to/deploy/orchestrated/ansible.md#在中控机器上安装-ansible-及其依赖) 进行安装。离线环境参照[在中控机器上离线安装 Ansible 及其依赖](/v2.1/how-to/deploy/orchestrated/offline-ansible.md#在中控机器上离线安装-ansible-及其依赖)。 - -安装完成后，可通过以下命令查看版本： - -{{< copyable "shell-regular" >}} - -```bash -ansible --version -``` - -``` -ansible 2.6.8 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jinja2 -``` - -``` -Name: Jinja2 -Version: 2.10 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jmespath -``` - -``` -Name: jmespath -Version: 0.9.3 -``` - -> **注意：** -> -> 请务必按以上文档安装 Ansible 及其依赖。确认 Jinja2 版本是否正确，否则启动 Grafana 时会报错。确认 jmespath 版本是否正确，否则滚动升级 TiKV 时会报错。 - -## 在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录，备份 TiDB 2.0 版本或 TiDB 2.1 rc 版本的 tidb-ansible 文件夹： - -{{< copyable "shell-regular" >}} - -```bash -mv tidb-ansible tidb-ansible-bak -``` - -下载最新 tidb-ansible release-2.1 分支，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone -b release-2.1 https://github.com/pingcap/tidb-ansible.git -``` - -## 编辑 inventory.ini 文件和配置文件 - -以 `tidb` 用户登录中控机并进入 `/home/tidb/tidb-ansible` 目录。 - -### 编辑 `inventory.ini` 文件 - -编辑 `inventory.ini` 文件，IP 信息参照备份文件 `/home/tidb/tidb-ansible-bak/inventory.ini`。 - -以下变量配置，需要重点确认，变量含义可参考 [inventory.ini 变量调整](/v2.1/how-to/deploy/orchestrated/ansible.md#调整其它变量可选)。 - -1. 请确认 `ansible_user` 配置的是普通用户。为统一权限管理，不再支持使用 root 用户远程安装。默认配置中使用 `tidb` 用户作为 SSH 远程用户及程序运行用户。 - - ``` - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - 可参考[如何配置 SSH 互信及 sudo 规则](/v2.1/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)自动配置主机间互信。 - -2. `process_supervision` 变量请与之前版本保持一致，默认推荐使用 `systemd`。 - - ``` - # process supervision, [systemd, supervise] - process_supervision = systemd - ``` - - 如需变更，可参考 [如何调整进程监管方式从 supervise 到 systemd](/v2.1/how-to/deploy/orchestrated/ansible.md#如何调整进程监管方式从-supervise-到-systemd)，先使用备份 `/home/tidb/tidb-ansible-bak/` 分支变更进程监管方式再升级。 - -### 编辑 TiDB 集群组件配置文件 - -如之前自定义过 TiDB 集群组件配置文件，请参照备份文件修改 `/home/tidb/tidb-ansible/conf` 下对应配置文件。 - -TiKV 配置中 `end-point-concurrency` 变更为 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - -``` -readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 -``` - -2.0 版本升级且单机多 TiKV 实例情况下，需要修改这三个参数。推荐设置：`实例数 * 参数值 = CPU 核数 * 0.8`。 - -## 下载 TiDB 2.1 binary 到中控机 - -确认 `tidb-ansible/inventory.ini` 文件中 `tidb_version = v2.1.x`，然后执行以下命令下载 TiDB 2.1 binary 到中控机。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 滚动升级 TiDB 集群组件 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook rolling_update.yml -``` - -## 滚动升级 TiDB 监控组件 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook rolling_update_monitor.yml -``` diff --git a/v2.1/key-features.md b/v2.1/key-features.md deleted file mode 100644 index 4d739c036396..000000000000 --- a/v2.1/key-features.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: TiDB 核心特性 -category: introduction ---- - -# TiDB 核心特性 - -本文详细介绍 TiDB 的两大核心特性：水平扩展与高可用。 - -## 水平扩展 - -无限水平扩展是 TiDB 的一大特点，这里说的水平扩展包括两方面：计算能力和存储能力。TiDB Server 负责处理 SQL 请求，随着业务的增长，可以简单的添加 TiDB Server 节点，提高整体的处理能力，提供更高的吞吐。TiKV 负责存储数据，随着数据量的增长，可以部署更多的 TiKV Server 节点解决数据 Scale 的问题。PD 会在 TiKV 节点之间以 Region 为单位做调度，将部分数据迁移到新加的节点上。所以在业务的早期，可以只部署少量的服务实例（推荐至少部署 3 个 TiKV， 3 个 PD，2 个 TiDB），随着业务量的增长，按照需求添加 TiKV 或者 TiDB 实例。 - -## 高可用 - -高可用是 TiDB 的另一大特点，TiDB/TiKV/PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。下面分别说明这三个组件的可用性、单个实例失效后的后果以及如何恢复。 - -- TiDB - - TiDB 是无状态的，推荐至少部署两个实例，前端通过负载均衡组件对外提供服务。当单个实例失效时，会影响正在这个实例上进行的 Session，从应用的角度看，会出现单次请求失败的情况，重新连接后即可继续获得服务。单个实例失效后，可以重启这个实例或者部署一个新的实例。 - -- PD - - PD 是一个集群，通过 Raft 协议保持数据的一致性，单个实例失效时，如果这个实例不是 Raft 的 leader，那么服务完全不受影响；如果这个实例是 Raft 的 leader，会重新选出新的 Raft leader，自动恢复服务。PD 在选举的过程中无法对外提供服务，这个时间大约是3秒钟。推荐至少部署三个 PD 实例，单个实例失效后，重启这个实例或者添加新的实例。 - -- TiKV - - TiKV 是一个集群，通过 Raft 协议保持数据的一致性（副本数量可配置，默认保存三副本），并通过 PD 做负载均衡调度。单个节点失效时，会影响这个节点上存储的所有 Region。对于 Region 中的 Leader 节点，会中断服务，等待重新选举；对于 Region 中的 Follower 节点，不会影响服务。当某个 TiKV 节点失效，并且在一段时间内（默认 30 分钟）无法恢复，PD 会将其上的数据迁移到其他的 TiKV 节点上。 diff --git a/v2.1/overview.md b/v2.1/overview.md deleted file mode 100644 index 2bbdefc937c0..000000000000 --- a/v2.1/overview.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/v2.1/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v2.1/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/v2.1/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v2.1/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 Docker Compose 部署](/v2.1/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v2.1/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/v2.1/reference/alert-rules.md b/v2.1/reference/alert-rules.md deleted file mode 100644 index fec730db4d6a..000000000000 --- a/v2.1/reference/alert-rules.md +++ /dev/null @@ -1,1168 +0,0 @@ ---- -title: TiDB 集群报警规则 -summary: TiDB 集群中各组件的报警规则详解。 -category: reference ---- - -# TiDB 集群报警规则 - -本文介绍了 TiDB 集群中各组件的报警规则，包括 TiDB、TiKV、PD、TiDB Binlog、Node_exporter 和 Blackbox_exporter 的各报警项的规则描述及处理方法。 - -## TiDB 报警项 - -本节介绍了 TiDB 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_schema_error` - -* 报警规则： - - `increase(tidb_session_schema_lease_error_total{type="outdated"}[15m]) > 0` - -* 规则描述： - - TiDB 在一个 Lease 时间内没有重载到最新的 Schema 信息。如果 TiDB 无法继续对外提供服务，则报警。 - -* 处理方法： - - 该问题通常由于 TiKV Region 不可用或超时导致，需要看 TiKV 的监控指标定位问题。 - -#### `TiDB_tikvclient_region_err_total` - -* 报警规则： - - `increase(tidb_tikvclient_region_err_total[10m]) > 6000` - -* 规则描述： - - TiDB 访问 TiKV 时发生了 Region 错误。如果在 10 分钟之内该错误多于 6000 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_domain_load_schema_total` - -* 报警规则： - - `increase(tidb_domain_load_schema_total{type="failed"}[10m]) > 10` - -* 规则描述： - - TiDB 重载最新的 Schema 信息失败的总次数。如果在 10 分钟之内重载失败次数超过 10 次，则报警。 - -* 处理方法： - - 参考 [`TiDB_schema_error`](#tidb_schema_error) 的处理方法。 - -#### `TiDB_monitor_keep_alive` - -* 报警规则： - - `increase(tidb_monitor_keep_alive_total[10m]) < 100` - -* 规则描述： - - 表示 TiDB 的进程是否仍然存在。如果在 10 分钟之内 `tidb_monitor_keep_alive_total` 增加次数少于 100，则 TiDB 的进程可能已经退出，此时会报警。 - -* 处理方法： - - * 检查 TiDB 进程是否 OOM。 - * 检查机器是否发生了重启。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiDB_server_panic_total` - -* 报警规则： - - `increase(tidb_server_panic_total[10m]) > 0` - -* 规则描述： - - 发生崩溃的 TiDB 线程的数量。当出现崩溃的时候会报警。该线程通常会被恢复，否则 TiDB 会频繁重启。 - -* 处理方法： - - 收集 panic 日志，定位原因。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiDB_memory_abnormal` - -* 报警规则： - - `go_memstats_heap_inuse_bytes{job="tidb"} > 1e+10` - -* 规则描述： - - 对 TiDB 内存使用量的监控。如果内存使用大于 10 G，则报警。 - -* 处理方法： - - 通过 HTTP API 来排查 goroutine 泄露的问题。 - -#### `TiDB_query_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tidb_server_handle_query_duration_seconds_bucket[1m])) BY (le, instance)) > 1` - -* 规则描述： - - TiDB 处理请求的延时。如果 .99 的延迟大于 1 秒，则报警。 - -* 处理方法： - - 查看 TiDB 的日志，搜索 SLOW_QUERY 和 TIME_COP_PROCESS 关键字，查找慢 SQL。 - -#### `TiDB_server_event_error` - -* 报警规则： - - `increase(tidb_server_event_total{type=~"server_start|server_hang"}[15m]) > 0` - -* 规则描述： - - TiDB 服务中发生的事件数量。当出现以下事件的时候会报警： - - 1. start：TiDB 服务启动。 - 2. hang：当发生了 Critical 级别的事件时（目前只有 Binlog 写不进去一种情况），TiDB 进入 `hang` 模式，并等待人工 Kill。 - -* 处理方法： - - * 重启 TiDB 以恢复服务。 - * 检查 TiDB Binlog 服务是否正常。 - -#### `TiDB_tikvclient_backoff_total` - -* 报警规则： - - `increase(tidb_tikvclient_backoff_total[10m]) > 10` - -* 规则描述： - - TiDB 访问 TiKV 发生错误时发起重试的次数。如果在 10 分钟之内重试次数多于 10 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_monitor_time_jump_back_error` - -* 报警规则： - - `increase(tidb_monitor_time_jump_back_total[10m]) > 0` - -* 规则描述： - - 如果 TiDB 所在机器的时间发生了回退，则报警。 - -* 处理方法： - - 排查 NTP 配置。 - -#### `TiDB_ddl_waiting_jobs` - -* 报警规则： - - `sum(tidb_ddl_waiting_jobs) > 5` - -* 规则描述： - - 如果 TiDB 中等待执行的 DDL 任务的数量大于 5，则报警。 - -* 处理方法： - - 通过 `admin show ddl` 语句检查是否有耗时的 add index 操作正在执行。 - -## PD 报警规则 - -本节介绍了 PD 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `PD_cluster_offline_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_down_count"}) > 0` - -* 规则描述： - - PD 长时间（默认配置是 30 分钟）没有收到 TiKV 心跳。 - -* 处理方法： - - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `PD_etcd_write_disk_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[1m])) by (instance,job,le)) > 1` - -* 规则描述： - - etcd 写盘慢，这很容易引起 PD leader 超时或者 TSO 无法及时存盘等问题，从而导致整个集群停止服务。 - -* 处理方法： - - * 排查写入慢的原因。可能是由于其他服务导致系统负载过高。可以检查 PD 本身是否占用了大量 CPU 或 IO 资源。 - * 可尝试重启 PD 或手动 transfer leader 至其他的 PD 来恢复服务。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_miss_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="miss_peer_region_count"}) > 100` - -* 规则描述： - - Region 的副本数小于 `max-replicas` 配置的值。这通常是由于 TiKV 宕机等问题导致一段时间内一些 Region 缺副本，下线 TiKV 节点也会导致少量 Region 缺副本（对于有 pending peer 的 Region 会走先减后加的流程）。 - -* 处理方法： - - * 查看是否有 TiKV 宕机或在做下线操作，尝试定位问题产生的原因。 - * 观察 region health 面板，查看 `miss_peer_region_count` 是否在不断减少。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `PD_cluster_lost_connect_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_disconnected_count"}) > 0` - -* 规则描述： - - PD 在 20 秒之内未收到 TiKV 上报心跳。正常情况下是每 10 秒收到 1 次心跳。 - -* 处理方法： - - * 排查是否在重启 TiKV。 - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - * 如果确定 TiKV 可以恢复，但在短时间内还无法恢复，可以考虑延长 `max-down-time` 配置，防止超时后 TiKV 被判定为无法恢复并开始搬移数据。 - -#### `PD_cluster_low_space` - -* 报警规则： - - `sum(pd_cluster_status{type="store_low_space_count"}) > 0` - -* 规则描述： - - 表示 TiKV 节点空间不足。 - -* 处理方法： - - * 检查集群中的空间是否普遍不足。如果是，则需要扩容。 - * 检查 Region balance 调度是否有问题。如果有问题，会导致数据分布不均衡。 - * 检查是否有文件占用了大量磁盘空间，比如日志、快照、core dump 等文件。 - * 降低该节点的 Region weight 来减少数据量。 - * 无法释放空间时，可以考虑主动下线该节点，防止由于磁盘空间不足而宕机。 - -#### `PD_etcd_network_peer_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_network_peer_round_trip_time_seconds_bucket[1m])) by (To,instance,job,le)) > 1` - -* 规则描述： - - PD 节点之间网络延迟高，严重情况下会导致 leader 超时和 TSO 存盘超时，从而影响集群服务。 - -* 处理方法： - - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_tidb_handle_requests_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(pd_client_request_handle_requests_duration_seconds_bucket{type="tso"}[1m])) by (instance,job,le)) > 0.1` - -* 规则描述： - - PD 处理 TSO 请求耗时过长，一般是由于负载过高。 - -* 处理方法： - - * 检查服务器负载状况。 - * 使用 pprof 抓取 PD 的 CPU profile 进行分析。 - * 手动切换 PD leader。 - * 如果是环境问题，则将有问题的 PD 下线替换。 - -#### `PD_down_peer_region_nums` - -* 报警规则： - - `sum(pd_regions_status{type="down_peer_region_count"}) > 0` - -* 规则描述： - - Raft leader 上报有不响应 peer 的 Region 数量。 - -* 处理方法： - - * 检查是否有 TiKV 宕机，或刚发生重启，或者繁忙。 - * 观察 region health 面板，检查 `down_peer_region_count` 是否在不断减少。 - * 检查是否有 TiKV 之间网络不通。 - -#### `PD_pending_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="pending_peer_region_count"}) > 100` - -* 规则描述： - - Raft log 落后的 Region 过多。由于调度产生少量的 pending peer 是正常的，但是如果持续很高，就可能有问题。 - -* 处理方法： - - * 观察 region health 面板，检查 `pending_peer_region_count` 是否在不断减少。 - * 检查 TiKV 之间的网络状况，特别是带宽是否足够。 - -#### `PD_leader_change` - -* 报警规则： - - `count(changes(pd_server_tso{type="save"}[10m]) > 0) >= 2` - -* 规则描述： - - 近期发生了 PD leader 切换。 - -* 处理方法： - - * 排除人为因素，比如重启 PD、手动 transfer leader 或调整 leader 优先级等。 - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `TiKV_space_used_more_than_80%` - -* 报警规则： - - `sum(pd_cluster_status{type="storage_size"}) / sum(pd_cluster_status{type="storage_capacity"}) * 100 > 80` - -* 规则描述： - - 集群空间占用超过 80%。 - -* 处理方法： - - * 确认是否需要扩容。 - * 排查是否有文件占用了大量磁盘空间，比如日志、快照或 core dump等文件。 - -#### `PD_system_time_slow` - -* 报警规则： - - `changes(pd_server_tso{type="system_time_slow"}[10m]) >= 1` - -* 规则描述： - - 系统时间可能发生回退。 - -* 处理方法： - - 检查系统时间设置是否正确。 - -#### `PD_no_store_for_making_replica` - -* 报警规则： - - `increase(pd_checker_event_count{type="replica_checker", name="no_target_store"}[1m]) > 0` - -* 规则描述： - - 没有合适的 store 用来补副本。 - -* 处理方法： - - * 检查 store 是否空间不足。 - * 根据 label 配置（如果有这个配置的话）来检查是否有可以补副本的 store。 - -## TiKV 报警规则 - -本节介绍了 TiKV 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiKV_memory_used_too_fast` - -* 报警规则： - - `process_resident_memory_bytes{job=~"tikv",instance=~".*"} - (process_resident_memory_bytes{job=~"tikv",instance=~".*"} offset 5m) > 5*1024*1024*1024` - -* 规则描述： - - 目前没有和内存相关的 TiKV 的监控，你可以通过 Node_exporter 监控集群内机器的内存使用情况。如上规则表示，如果在 5 分钟之内内存使用超过 5GB（TiKV 内存占用的太快），则报警。 - -* 处理方法： - - 调整 `rockdb.defaultcf` 和 `rocksdb.writecf` 的 `block-cache-size` 的大小。 - -#### `TiKV_GC_can_not_work` - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="success"}[6h])) < 1` - -* 规则描述： - - 在 6 小时内 Region 上没有成功执行 GC，说明 GC 不能正常工作了。短期内 GC 不运行不会造成太大的影响，但如果 GC 一直不运行，版本会越来越多，从而导致查询变慢。 - -* 处理方法： - - 1. 执行 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME="tikv_gc_leader_desc"` 来找到 gc leader 对应的 `tidb-server`； - 2. 查看该 `tidb-server` 的日志，grep gc_worker tidb.log； - 3. 如果发现这段时间一直在 resolve locks（最后一条日志是 `start resolve locks`）或者 delete ranges（最后一条日志是 `start delete {number} ranges`），说明 GC 进程是正常的。否则需要报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiKV_server_report_failure_msg_total` - -* 报警规则： - - `sum(rate(tikv_server_report_failure_msg_total{type="unreachable"}[10m])) BY (store_id) > 10` - -* 规则描述： - - 表明无法连接远端的 TiKV。 - -* 处理方法： - - 1. 检查网络是否通畅。 - 2. 检查远端 TiKV 是否挂掉。 - 3. 如果远端 TiKV 没有挂掉，检查压力是否太大，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 处理方法。 - -#### `TiKV_channel_full_total` - -* 报警规则： - - `sum(rate(tikv_channel_full_total[10m])) BY (type, instance) > 0` - -* 规则描述： - - 该错误通常是因为 Raftstore 线程卡死，TiKV 的压力已经非常大了。 - -* 处理方法： - - 1. 观察 Raft Propose 监控，看这个报警的 TiKV 节点是否明显有比其他 TiKV 高很多。如果是，表明这个 TiKV 上有热点，需要检查热点调度是否能正常工作。 - 2. 观察 Raft IO 监控，看延迟是否升高。如果延迟很高，表明磁盘可能有瓶颈。一个能缓解但不怎么安全的办法是将 `sync-log` 改成 `false`。 - 3. 观察 Raft Process 监控，看 tick duration 是否很高。如果是，需要在 `[raftstore]` 配置下加上 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_write_stall` - -* 报警规则： - - `delta(tikv_engine_write_stall[10m]) > 0` - -* 规则描述： - - RocksDB 写入压力太大，出现了 stall。 - -* 处理方法： - - 1. 观察磁盘监控，排除磁盘问题。 - 2. 看 TiKV 是否有写入热点。 - 3. 在 `[rocksdb]` 和 `[raftdb]` 配置下调大 `max-sub-compactions` 的值。 - -#### `TiKV_raft_log_lag` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_log_lag_bucket[1m])) by (le, instance)) > 5000` - -* 规则描述： - - 这个值偏大，表明 Follower 已经远远落后于 Leader，Raft 没法正常同步了。可能的原因是 Follower 所在的 TiKV 卡住或者挂掉了。 - -#### `TiKV_async_request_snapshot_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="snapshot"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raftstore 负载压力很大，可能已经卡住。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_async_request_write_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="write"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raft write 耗时很长。 - -* 处理方法： - - 1. 检查 Raftstore 上的压力，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 检查 apply worker 线程的压力。 - -#### `TiKV_coprocessor_request_wait_seconds` - -* 报警规则： - - `histogram_quantile(0.9999, sum(rate(tikv_coprocessor_request_wait_seconds_bucket[1m])) by (le, instance, req)) > 10` - -* 规则描述： - - 这个值偏大，表明 Coprocessor worker 压力很大。可能有比较慢的任务卡住了 Coprocessor 线程。 - -* 处理方法： - - 1. 从 TiDB 日志中查看慢查询日志，看查询是否用到了索引或全表扫，或者看是否需要做 analyze。 - 2. 排查是否有热点。 - 3. 查看 Coprocessor 监控，看 `coporcessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 - -#### `TiKV_raftstore_thread_cpu_seconds_total` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"raftstore_.*"}[1m])) by (instance, name) > 0.8` - -* 规则描述： - - Raftstore 线程压力太大。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_raft_append_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_append_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 append Raft log 的耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_raft_apply_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_apply_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 apply Raft log 耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_scheduler_latch_wait_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_latch_wait_duration_seconds_bucket[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - Scheduler 中写操作获取内存锁时的等待时间。如果这个值高，表明写操作冲突较多，也可能是某些引起冲突的操作耗时较长，阻塞了其它等待相同锁的操作。 - -* 处理方法： - - 1. 查看 Scheduler-All 监控中的 scheduler command duration，看哪一个命令耗时最大。 - 2. 查看 Scheduler-All 监控中的 scheduler scan details，看 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描，另外观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 - 3. 查看 Storage 监控中的 storage async snapshot/write duration，看是否 Raft 操作不及时。 - -#### `TiKV_thread_apply_worker_cpu_seconds` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name="apply_worker"}[1m])) by (instance) > 0.9` - -* 规则描述： - - Apply Raft log 线程压力太大，通常是因为写入太猛了。 - -#### `TiDB_tikvclient_gc_action_fail` - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="fail”}[1m])) > 10` - -* 规则描述： - - GC 失败的 Region 较多。 - -* 处理方法： - - 1. 一般是因为并行 GC 开的太高了，可以适当降低 GC 并行度。你需要先确认 GC 失败是由于服务器繁忙导致的。 - 2. 通过执行 `update set VARIABLE_VALUE=”{number}” where VARIABLE_NAME=”tikv_gc_concurrency”` 适当降低并行度。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiKV_leader_drops` - -* 报警规则： - - `delta(tikv_pd_heartbeat_tick_total{type="leader"}[30s]) < -10` - -* 规则描述： - - 该问题通常是因为 Raftstore 线程卡住了。 - -* 处理方法： - - 1. 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 如果 TiKV 压力很小，考虑 PD 的调度是否太频繁。可以查看 PD 页面的 Operator Create 面板，排查 PD 产生调度的类型和数量。 - -#### `TiKV_raft_process_ready_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type='ready'}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft ready 的耗时。这个值大，通常是因为 append log 任务卡住了。 - -#### `TiKV_raft_process_tick_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type=’tick’}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft tick 的耗时，这个值大，通常是因为 Region 太多导致的。 - -* 处理方法： - - 1. 考虑使用更高等级的日志，比如 `warn` 或者 `error`。 - 2. 在 `[raftstore]` 配置下添加 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_scheduler_context_total` - -* 报警规则： - - `abs(delta( tikv_scheduler_context_total[5m])) > 1000` - -* 规则描述： - - Scheduler 正在执行的写命令数量。这个值高，表示任务完成得不及时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_scheduler_command_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_command_duration_seconds_bucket[1m])) by (le, instance, type) / 1000) > 1` - -* 规则描述： - - 表明 Scheduler 执行命令的耗时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_thread_storage_scheduler_cpu_seconds` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"storage_schedul.*"}[1m])) by (instance) > 0.8` - -* 规则描述： - - scheduler 单线程的 CPU 使用超过了 80%，一般是由于写入太多引起。 - -* 处理方法： - - * 查看是否存在写入热点问题。 - * 如果所有 TiKV 都出现了这种情况，说明写入压力太大，需要扩容。 - -#### `TiKV_coprocessor_outdated_request_wait_seconds` - -* 报警规则： - - `delta(tikv_coprocessor_outdated_request_wait_seconds_count[10m]) > 0` - -* 规则描述： - - Coprocessor 已经过期的请求等待的时间。这个值高，表示 Coprocessor 压力已经非常大了。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_coprocessor_request_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason!="lock"}[10m]) > 100` - -* 规则描述： - - Coprocessor 的请求错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”和“full”等。“outdated”表示请求超时，很可能是由于排队时间过久，或者单个请求的耗时比较长。“full”表示 Coprocessor 的请求队列已经满了，可能是正在执行的请求比较耗时，导致新来的请求都在排队。耗时比较长的查询需要查看下对应的执行计划是否正确。 - -#### `TiKV_coprocessor_request_lock_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason="lock"}[10m]) > 10000` - -* 规则描述： - - Coprocessor 请求锁的错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”、“full”等。“lock”表示读到的数据正在写入，需要等待一会再读（TiDB 内部会自动重试）。少量这种错误不用关注，如果有大量这种错误，需要查看写入和查询是否有冲突。 - -#### `TiKV_coprocessor_pending_request` - -* 报警规则： - - `delta(tikv_coprocessor_pending_request[10m]) > 5000` - -* 规则描述： - - Coprocessor 排队的请求。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_batch_request_snapshot_nums` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"cop_.*"}[1m])) by (instance) / (count(tikv_thread_cpu_seconds_total{name=~"cop_.*"}) * 0.9) / count(count(tikv_thread_cpu_seconds_total) by (instance)) > 0` - -* 规则描述： - - 某个 TiKV 的 Coprocessor CPU 使用率超过了 90%。 - -#### `TiKV_pending_task` - -* 报警规则： - - `sum(tikv_worker_pending_task_total) BY (instance,name) > 1000` - -* 规则描述： - - TiKV 等待的任务数量。 - -* 处理方法： - - 查看是哪一类任务的值偏高，通常 Coprocessor、apply worker 这类任务都可以在其他指标里找到解决办法。 - -#### `TiKV_low_space_and_add_region` - -* 报警规则： - - `count((sum(tikv_store_size_bytes{type="available"}) by (instance) / sum(tikv_store_size_bytes{type="capacity"}) by (instance) < 0.2) and (sum(tikv_raftstore_snapshot_traffic_total{type="applying"}) by (instance) > 0)) > 0` - -#### `TiKV_approximate_region_size` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_region_size_bucket[1m])) by (le)) > 1073741824` - -* 规则描述： - - TiKV split checker 扫描到的最大的 Region approximate size 在 1 分钟内持续大于 1 GB。 - -* 处理方法： - - Region 分裂的速度不及写入的速度。为缓解这种情况，建议更新到支持 batch-split 的版本 (>= 2.1.0-rc1)。如暂时无法更新，可以使用 `pd-ctl operator add split-region --policy=approximate` 手动分裂 Region。 - -## TiDB Binlog 报警规则 - -关于 TiDB Binlog 报警规则的详细描述，参见 [TiDB Binlog 集群监控报警文档](/v2.1/reference/tidb-binlog/monitor.md#监控报警规则)。 - -## Node_exporter 主机报警规则 - -本节介绍了 Node_exporter 主机的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `NODE_disk_used_more_than_80%` - -* 报警规则： - - `node_filesystem_avail{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} / node_filesystem_size{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} * 100 <= 20` - -* 规则描述： - - 机器磁盘空间使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -h` 命令，查看磁盘空间使用率，做好扩容计划。 - -#### `NODE_disk_inode_more_than_80%` - -* 报警规则： - - `node_filesystem_files_free{fstype=~"(ext.|xfs)"} / node_filesystem_files{fstype=~"(ext.|xfs)"} * 100 < 20` - -* 规则描述： - - 机器磁盘挂载目录文件系统 inode 使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -i` 命令，查看磁盘挂载目录文件系统 inode 使用率，做好扩容计划。 - -#### `NODE_disk_readonly` - -* 报警规则： - - `node_filesystem_readonly{fstype=~"(ext.|xfs)"} == 1` - -* 规则描述： - - 磁盘挂载目录文件系统只读，无法写入数据，一般是因为磁盘故障或文件系统损坏。 - -* 处理方法： - - * 登录机器创建文件测试是否正常。 - * 检查该服务器硬盘指示灯是否正常，如异常，需更换磁盘并修复该机器文件系统。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `NODE_memory_used_more_than_80%` - -* 报警规则： - - `(((node_memory_MemTotal-node_memory_MemFree-node_memory_Cached)/(node_memory_MemTotal)*100)) >= 80` - -* 规则描述： - - 机器内存使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node Exporter 页面查看该主机的 Memory 面板，检查 `Used` 是否过高，`Available` 内存是否过低。 - * 登录机器，执行 `free -m` 命令查看内存使用情况，执行 `top` 看是否有异常进程的内存使用率过高。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `NODE_node_overload` - -* 报警规则： - - `(node_load5 / count without (cpu, mode) (node_cpu{mode="system"})) > 1` - -* 规则描述： - - 机器 CPU 负载较高。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_cpu_used_more_than_80%` - -* 报警规则： - - `avg(irate(node_cpu{mode="idle"}[5m])) by(instance) * 100 <= 20` - -* 规则描述： - - 机器 CPU 使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_tcp_estab_num_more_than_50000` - -* 报警规则： - - `node_netstat_Tcp_CurrEstab > 50000` - -* 规则描述： - - 机器 `establish` 状态的 TCP 链接超过 50,000。 - -* 处理方法： - - 登录机器执行 `ss -s` 可查看当前系统 `estab` 状态的 TCP 链接数，执行 `netstat` 查看是否有异常链接。 - -#### `NODE_disk_read_latency_more_than_32ms` - -* 报警规则： - - `((rate(node_disk_read_time_ms{device=~".+"}[5m]) / rate(node_disk_reads_completed{device=~".+"}[5m])) or (irate(node_disk_read_time_ms{device=~".+"}[5m]) / irate(node_disk_reads_completed{device=~".+"}[5m]))) > 32` - -* 规则描述： - - 磁盘读延迟超过 32 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板观察磁盘的读延迟。 - * 查看 Disk IO Utilization 面板观察 IO 使用率。 - -#### `NODE_disk_write_latency_more_than_16ms` - -* 报警规则： - - `((rate(node_disk_write_time_ms{device=~".+"}[5m]) / rate(node_disk_writes_completed{device=~".+"}[5m])) or (irate(node_disk_write_time_ms{device=~".+"}[5m]) / irate(node_disk_writes_completed{device=~".+"}[5m])))> 16` - -* 规则描述： - - 机器磁盘写延迟超过 16 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板可查看磁盘的写延迟。 - * 查看 Disk IO Utilization 面板可查看 IO 使用率。 - -## Blackbox_exporter TCP、ICMP 和 HTTP 报警规则 - -本节介绍了 Blackbox_exporter TCP、ICMP 和 HTTP 的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_server_is_down` - -* 报警规则： - - `probe_success{group="tidb"} == 0` - -* 规则描述： - - TiDB 服务端口探测失败。 - -* 处理方法： - - * 检查 TiDB 服务所在机器是否宕机。 - * 检查 TiDB 进程是否存在。 - * 检查监控机与 TiDB 服务所在机器之间网络是否正常。 - -#### `Pump_server_is_down` - -* 报警规则： - - `probe_success{group="pump"} == 0` - -* 规则描述： - - Pump 服务端口探测失败。 - -* 处理方法： - - * 检查 Pump 服务所在机器是否宕机。 - * 检查 Pump 进程是否存在。 - * 检查监控机与 Pump 服务所在机器之间网络是否正常。 - -#### `Drainer_server_is_down` - -* 报警规则： - - `probe_success{group="drainer"} == 0` - -* 规则描述： - - Drainer 服务端口探测失败。 - -* 处理方法： - - * 检查 Drainer 服务所在机器是否宕机。 - * 检查 Drainer 进程是否存在。 - * 检查监控机与 Drainer 服务所在机器之间网络是否正常。 - -#### `TiKV_server_is_down` - -* 报警规则： - - `probe_success{group="tikv"} == 0` - -* 规则描述： - - TiKV 服务端口探测失败。 - -* 处理方法： - - * 检查 TiKV 服务所在机器是否宕机。 - * 检查 TiKV 进程是否存在。 - * 检查监控机与 TiKV 服务所在机器之间网络是否正常。 - -#### `PD_server_is_down` - -* 报警规则： - - `probe_success{group="pd"} == 0` - -* 规则描述： - - PD 服务端口探测失败。 - -* 处理方法： - - * 检查 PD 服务所在机器是否宕机。 - * 检查 PD 进程是否存在。 - * 检查监控机与 PD 服务所在机器之间网络是否正常。 - -#### `Node_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="node_exporter"} == 0` - -* 规则描述： - - Node_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Node_exporter 服务所在机器是否宕机。 - * 检查 Node_exporter 进程是否存在。 - * 检查监控机与 Node_exporter 服务所在机器之间网络是否正常。 - -#### `Blackbox_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="blackbox_exporter"} == 0` - -* 规则描述： - - Blackbox_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Blackbox_exporter 服务所在机器是否宕机。 - * 检查 Blackbox_exporter 进程是否存在。 - * 检查监控机与 Blackbox_exporter 服务所在机器之间网络是否正常。 - -#### `Grafana_server_is_down` - -* 报警规则： - - `probe_success{group="grafana"} == 0` - -* 规则描述： - - Grafana 服务端口探测失败。 - -* 处理方法： - - * 检查 Grafana 服务所在机器是否宕机。 - * 检查 Grafana 进程是否存在。 - * 检查监控机与 Grafana 服务所在机器之间网络是否正常。 - -#### `Pushgateway_server_is_down` - -* 报警规则： - - `probe_success{group="pushgateway"} == 0` - -* 规则描述： - - Pushgateway 服务端口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -#### `Kafka_exporter_is_down` - -* 报警规则： - - `probe_success{group="kafka_exporter"} == 0` - -* 规则描述： - - Kafka_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Kafka_exporter 服务所在机器是否宕机。 - * 检查 Kafka_exporter 进程是否存在。 - * 检查监控机与 Kafka_exporter 服务所在机器之间网络是否正常。 - -#### `Pushgateway_metrics_interface` - -* 报警规则： - - `probe_success{job="blackbox_exporter_http"} == 0` - -* 规则描述： - - Pushgateway 服务 http 接口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `BLACKER_ping_latency_more_than_1s` - -* 报警规则： - - `max_over_time(probe_duration_seconds{job=~"blackbox_exporter.*_icmp"}[1m]) > 1` - -* 规则描述： - - Ping 延迟超过 1 秒。 - -* 处理方法： - - * 在 Grafana Blackbox Exporter dashboard 上检查两个节点间的 ping 延迟是否太高。 - * 在 Grafana Blackbox Exporter dashboard 的 tcp 面板上检查是否有丢包。 diff --git a/v2.1/reference/best-practices/grafana-monitor.md b/v2.1/reference/best-practices/grafana-monitor.md deleted file mode 100644 index 90f84febc0d2..000000000000 --- a/v2.1/reference/best-practices/grafana-monitor.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 使用 Grafana 监控 TiDB 的最佳实践 -summary: 了解高效利用 Grafana 监控 TiDB 的七个技巧。 -category: reference ---- - -# 使用 Grafana 监控 TiDB 的最佳实践 - -[使用 TiDB Ansible 部署 TiDB 集群](/v2.1/how-to/deploy/orchestrated/ansible.md)时，会同时部署一套 [Grafana + Prometheus 的监控平台](/v2.1/how-to/monitor/overview.md)，用于收集和展示 TiDB 集群各个组件和机器的 metric 信息。本文主要介绍使用 TiDB 监控的最佳实践，旨在帮助 TiDB 用户高效利用丰富的 metric 信息来分析 TiDB 的集群状态或进行故障诊断。 - -## 监控架构 - -Prometheus 是一个拥有多维度数据模型和灵活查询语句的时序数据库。Grafana 是一个开源的 metric 分析及可视化系统。 - -![TiDB 监控整体架构](/media/prometheus-in-tidb.png) - -从 TiDB 2.1.3 版本开始，监控采用 pull 的方式，而之前版本采用的是 push 的方式，这是一个非常好的调整，它有以下几个优点： - -- 如果 Prometheus 需要迁移，无需重启整个 TiDB 集群。调整前，因为组件要调整 push 的目标地址，迁移 Prometheus 需要重启整个集群。 -- 支持部署 2 套独立的 Grafana + Prometheus 的监控平台（非 HA），防止监控的单点。方法是使用 ansible 用不同的 ip 各执行一次部署命令。 -- 去掉了 Pushgateway 这个单点组件。 - -## 监控数据的来源与展示 - -TiDB 的 3 个核心组件（TiDB server、TiKV server 和 PD server）可以通过 HTTP 接口来获取 metric 数据。这些 metric 均是从程序代码中上传的，默认端口如下： - -| 组件 | 端口 | -|:------------|:-------| -| TiDB server | 10080 | -| TiKV server | 20181 | -| PD server | 2379 | - -下面以 TiDB server 为例，展示如何通过 HTTP 接口查看一个语句的 QPS 数据： - -{{< copyable "shell-regular" >}} - -```bash -curl http://__tidb_ip__:10080/metrics |grep tidb_executor_statement_total -``` - -``` -# 可以看到实时 QPS 数据，并根据不同 type 对 SQL 语句进行了区分，value 是 counter 类型的累计值（科学计数法）。 -tidb_executor_statement_total{type="Delete"} 520197 -tidb_executor_statement_total{type="Explain"} 1 -tidb_executor_statement_total{type="Insert"} 7.20799402e+08 -tidb_executor_statement_total{type="Select"} 2.64983586e+08 -tidb_executor_statement_total{type="Set"} 2.399075e+06 -tidb_executor_statement_total{type="Show"} 500531 -tidb_executor_statement_total{type="Use"} 466016 -``` - -这些数据会存储在 Prometheus 中，然后在 Grafana 上进行展示。在面板上点击鼠标右键会出现 **Edit** 按钮（或直接按 E 键），如下图所示： - -![Metrics 面板的编辑入口](/media/best-practices/metric-board-edit-entry.png) - -点击 **Edit** 按钮之后，在 Metrics 面板上可以看到利用该 metric 的 query 表达式。面板上一些细节的含义如下： - -- `rate[1m]`：表示 1 分钟的增长速率，只能用于 counter 类型的数据。 -- `sum`：表示 value 求和。 -- `by type`：表示将求和后的数据按 metric 原始值中的 type 进行分组。 -- `Legend format`：表示指标名称的格式。 -- `Resolution`：默认打点步长是 15s，Resolution 表示是否将多个样本数据合并成一个点。 - -Metrics 面板中的表达式如下： - -![Metric 面板中的表达式](/media/best-practices/metric-board-expression.jpeg) - -Prometheus 支持很多表达式与函数，更多表达式请参考 [Prometheus 官网页面](https://prometheus.io/docs/prometheus/latest/querying)。 - -## Grafana 使用技巧 - -本小节介绍高效利用 Grafana 监控分析 TiDB 指标的七个技巧。 - -### 技巧 1：查看所有维度并编辑表达式 - -在[监控数据的来源与展示](#监控数据的来源与展示)一节的示例中，数据是按照 type 进行分组的。如果你想知道是否还能按其它维度分组，并快速查看还有哪些维度，可采用以下技巧：**在 query 的表达式上只保留指标名称，不做任何计算，`Legend format` 也留空**。这样就能显示出原始的 metric 数据。比如，下图能看到有 3 个维度（`instance`、`job` 和 `type`）： - -![编辑表达式并查看所有维度](/media/best-practices/edit-expression-check-dimensions.jpg) - -然后调整表达式，在原有的 `type` 后面加上 `instance` 这个维度，在 `Legend format` 处增加 `{{instance}}`，就可以看到每个 TiDB server 上执行的不同类型 SQL 语句的 QPS 了。如下图所示： - -![给表达式增加一个 instance 维度](/media/best-practices/add-instance-dimension.jpeg) - -### 技巧 2：调整 Y 轴标尺的计算方式 - -以 Query Duration 指标为例，默认的比例尺采用 2 的对数计算，显示上会将差距缩小。为了观察到明显的变化，可以将比例尺改为线性，从下面两张图中可以看到显示上的区别，明显发现那个时刻有个 SQL 语句运行较慢。 - -当然也不是所有场景都适合用线性，比如观察 1 个月的性能趋势，用线性可能就会有很多噪点，不好观察。 - -标尺默认的比例尺为 2 的对数： - -![标尺默认的比例尺为 2 的对数](/media/best-practices/default-axes-scale.jpg) - -将标尺的比例尺调整为线性： - -![调整标尺的比例尺为线性](/media/best-practices/axes-scale-linear.jpg) - -> **建议：** -> -> 结合技巧 1，会发现这里还有一个 `sql_type` 的维度，可以立刻分析出是 `SELECT` 慢还是 `UPDATE` 慢；并且可以分析出是哪个 instance 上的语句慢。 - -### 技巧 3：调整 Y 轴基线，放大变化 - -有时已经用了线性比例尺，却还是看不出变化趋势。比如下图中，在扩容后想观察 `Store size` 的实时变化效果，但由于基数较大，观察不到微弱的变化。这时可以将 Y 轴最小值从 `0` 改为 `auto`，将上部放大。观察下面两张图的区别，可以看出数据已开始迁移了。 - -基线默认为 `0`： - -![基线默认为 0](/media/best-practices/default-y-min.jpeg) - -将基线调整为 `auto`： - -![调整基线为 auto](/media/best-practices/y-min-auto.jpg) - -### 技巧 4：标尺联动 - -在 **Settings** 面板中，有一个 **Graph Tooltip** 设置项，默认使用 **Default**。 - -![图形展示工具](/media/best-practices/graph-tooltip.jpeg) - -下面将图形展示工具分别调整为 **Shared crosshair** 和 **Shared Tooltip** 看看效果。可以看到标尺能联动展示了，方便排查问题时确认 2 个指标的关联性。 - -将图形展示工具调整为 **Shared crosshair**： - -![调整图形展示工具为 Shared crosshair](/media/best-practices/graph-tooltip-shared-crosshair.jpeg) - -将图形展示工具调整为 **Shared Tooltip**： - -![调整图形展示工具为 Shared Tooltip](/media/best-practices/graph-tooltip-shared-tooltip.jpg) - -### 技巧 5：手动输入 `ip:端口号` 查看历史信息 - -PD 的 dashboard 只展示当前 leader 的 metric 信息，而有时想看历史上 PD leader 当时的状况，但是 `instance` 下拉列表中已不存在这个成员了。此时，可以手动输入 `ip:2379` 来查看当时的数据。 - -![查看历史 metric 信息](/media/best-practices/manually-input-check-metric.jpeg) - -### 技巧 6：巧用 `Avg` 函数 - -通常默认图例中只有 `Max` 和 `Current` 函数。当指标波动较大时，可以增加 `Avg` 等其它汇总函数的图例，来看一段时间的整体趋势。 - -增加 `Avg` 等汇总函数： - -![增加 Avg 等汇总函数](/media/best-practices/add-avg-function.jpeg) - -然后查看整体趋势： - -![增加 Avg 函数查看整体趋势](/media/best-practices/add-avg-function-check-trend.jpg) - -### 技巧 7：使用 Prometheus 的 API 接口获得表达式的结果 - -Grafana 通过 Prometheus 的接口获取数据，你也可以用该接口来获取数据，这个用法还可以衍生出许多功能： - -- 自动获取集群规模、状态等信息。 -- 对表达式稍加改动给报表提供数据，如统计每天的 QPS 总量、每天的 QPS 峰值和每天的响应时间。 -- 将重要的指标进行定期健康巡检。 - -Prometheus 的 API 接口如下： - -![Prometheus 的 API 接口](/media/best-practices/prometheus-api-interface.jpg) - -{{< copyable "shell-regular" >}} - -```bash -curl -u user:pass 'http://__grafana_ip__:3000/api/datasources/proxy/1/api/v1/query_range?query=sum(tikv_engine_size_bytes%7Binstancexxxxxxxxx20181%22%7D)%20by%20(instance)&start=1565879269&end=1565882869&step=30' |python -m json.tool -``` - -``` -{ - "data": { - "result": [ - { - "metric": { - "instance": "xxxxxxxxxx:20181" - }, - "values": [ - [ - 1565879269, - "1006046235280" - ], - [ - 1565879299, - "1006057877794" - ], - [ - 1565879329, - "1006021550039" - ], - [ - 1565879359, - "1006021550039" - ], - [ - 1565882869, - "1006132630123" - ] - ] - } - ], - "resultType": "matrix" - }, - "status": "success" -} -``` - -## 总结 - -Grafana + Prometheus 监控平台是一套非常强大的组合工具，用好这套工具可以为分析节省很多时间，提高效率，更重要的是，我们可以更容易发现问题。在运维 TiDB 集群，尤其是数据量大的情况下，这套工具能派上大用场。 diff --git a/v2.1/reference/best-practices/haproxy.md b/v2.1/reference/best-practices/haproxy.md deleted file mode 100644 index bac220f0a4c8..000000000000 --- a/v2.1/reference/best-practices/haproxy.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: HAProxy 在 TiDB 中的最佳实践 -category: reference ---- - -# HAProxy 在 TiDB 中的最佳实践 - -本文介绍 [HAProxy](https://github.com/haproxy/haproxy) 在 TiDB 中的最佳配置和使用方法。HAProxy 提供 TCP 协议下的负载均衡能力，TiDB 客户端通过连接 HAProxy 提供的浮动 IP 即可对数据进行操作，实现 TiDB Server 层的负载均衡。 - -![HAProxy 在 TiDB 中的最佳实践](/media/haproxy.jpg) - -## HAProxy 简介 - -HAProxy 是由 C 语言编写的自由开放源码的软件，为基于 TCP 和 HTTP 协议的应用程序提供高可用性、负载均衡和代理服务。因为 HAProxy 能够快速、高效使用 CPU 和内存，所以目前使用非常广泛，许多知名网站诸如 GitHub、Bitbucket、Stack Overflow、Reddit、Tumblr、Twitter 和 Tuenti 以及亚马逊网络服务系统都在使用 HAProxy。 - -HAProxy 由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。最新的稳定版本 2.0.0 于 2019 年 8 月 16 日发布，带来更多[优秀的特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 - -## HAProxy 部分核心功能介绍 - -- [高可用性](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.4)：HAProxy 提供优雅关闭服务和无缝切换的高可用功能； -- [负载均衡](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#4.2-balance)：L4 (TCP) 和 L7 (HTTP) 两种负载均衡模式，至少 9 类均衡算法，比如 roundrobin，leastconn，random 等； -- [健康检查](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#5.2-check)：对 HAProxy 配置的 HTTP 或者 TCP 模式状态进行检查； -- [会话保持](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.6)：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能； -- [SSL](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.2)：支持 HTTPS 通信和解析； -- [监控与统计](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.3)：通过 web 页面可以实时监控服务状态以及具体的流量信息。 - -## 准备环境 - -在部署 HAProxy 之前，需准备好以下环境。 - -### 硬件要求 - -根据官方文档，对 HAProxy 的服务器硬件配置有以下建议，也可以根据负载均衡环境进行推算，在此基础上提高服务器配置。 - -|硬件资源|最低配置| -|:---|:---| -|CPU|2 核，3.5 GHz| -|内存|16 GB| -|存储容量|50 GB（SATA 盘）| -|网卡|万兆网卡| - -### 依赖软件 - -根据官方文档，对操作系统和依赖包有以下建议，如果通过 yum 源部署安装 HAProxy 软件，依赖包无需单独安装。 - -#### 操作系统 - -| 操作系统版本 | 架构 | -|:-------------------------|:------------------------------------------| -| Linux 2.4 | x86、x86_64、Alpha、SPARC、MIPS 和 PA-RISC | -| Linux 2.6 或 3.x | x86、x86_64、ARM、SPARC 和 PPC64 | -| Solaris 8 或 9 | UltraSPARC II 和 UltraSPARC III | -| Solaris 10 | Opteron 和 UltraSPARC | -| FreeBSD 4.10 ~ 10 | x86 | -| OpenBSD 3.1 及以上版本 | i386、AMD64、macppc、Alpha 和 SPARC64 | -| AIX 5.1 ~ 5.3 | Power™ | - -#### 依赖包 - -- epel-release -- gcc -- systemd-devel - -执行如下命令安装依赖包： - -{{< copyable "shell-regular" >}} - -```bash -yum -y install epel-release gcc systemd-devel -``` - -## 部署 HAProxy - -HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具有普遍性，不具有特殊性，建议根据实际场景，个性化配置相关的[配置文件](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html)。 - -### 安装 HAProxy - -1. 使用 yum 安装 HAProxy： - - {{< copyable "shell-regular" >}} - - ```bash - yum -y install haproxy - ``` - -2. 验证 HAProxy 安装是否成功： - - {{< copyable "shell-regular" >}} - - ```bash - which haproxy - ``` - - ``` - /usr/sbin/haproxy - ``` - -#### HAProxy 命令介绍 - -执行如下命令查看命令行参数及基本用法： - -{{< copyable "shell-regular" >}} - -```bash -haproxy --help -``` - -| 参数 | 说明 | -| :------- | :--------- | -| `-v` | 显示简略的版本信息。 | -| `-vv` | 显示详细的版本信息。 | -| `-d` | 开启 debug 模式。 | -| `-db` | 禁用后台模式和多进程模式。 | -| `-dM []` | 执行分配内存。| -| `-V` | 启动过程显示配置和轮询信息。 | -| `-D` | 开启守护进程模式。 | -| `-C ` | 在加载配置文件之前更改目录位置至 \。 | -| `-W` | 主从模式。 | -| `-q` | 静默模式，不输出信息。 | -| `-c` | 只检查配置文件并在尝试绑定之前退出。 | -| `-n ` | 设置每个进程的最大总连接数为 \。 | -| `-m ` | 设置所有进程的最大可用内存为 \（单位：MB）。 | -| `-N ` | 设置单点最大连接数为 \，默认为 2000。 | -| `-L ` | 将本地实例对等名称改为 \，默认为本地主机名。 | -| `-p ` | 将 HAProxy 所有子进程的 PID 信息写入 \。 | -| `-de` | 禁止使用 epoll(7)，epoll(7) 仅在 Linux 2.6 和某些定制的 Linux 2.4 系统上可用。 | -| `-dp` | 禁止使用 epoll(2)，可改用 select(2)。 | -| `-dS` | 禁止使用 splice(2)，splice(2) 在一些旧版 Linux 内核上不可用。 | -| `-dR` | 禁止使用 SO_REUSEPORT。 | -| `-dr` | 忽略服务器地址解析失败。 | -| `-dV` | 禁止在服务器端使用 SSL。 | -| `-sf ` | 启动后，向 pidlist 中的 PID 发送 `finish` 信号，收到此信号的进程在退出之前将等待所有会话完成，即优雅停止服务。此选项必须最后指定，后跟任意数量的 PID。从技术上讲，SIGTTOU 和 SIGUSR1 都被发送。 | -| `-st ` | 启动后，向 pidlist 中的 PID 发送 `terminate` 信号，收到此信号的进程将立即终止，关闭所有活动会话。此选项必须最后指定，后跟任意数量的 PID。从技术上讲，SIGTTOU 和 SIGTERM 都被发送。 | -| `-x ` | 连接指定的 socket 并从旧进程中获取所有 listening socket，然后，使用这些 socket 而不是绑定新的。 | -| `-S [,...]` | 主从模式下，创建绑定到主进程的 socket，此 socket 可访问每个子进程的 socket。 | - -更多有关 HAProxy 命令参数的信息，可参阅 [Management Guide of HAProxy](http://cbonte.github.io/haproxy-dconv/1.9/management.html) 和 [General Commands Manual of HAProxy](https://manpages.debian.org/buster-backports/haproxy/haproxy.1.en.html)。 - -### 配置 HAProxy - -yum 安装过程中会生成配置模版，你也可以根据实际场景自定义配置如下配置项。 - -```yaml -global # 全局配置。 - log 127.0.0.1 local2 # 定义全局的 syslog 服务器，最多可以定义两个。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 40 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - stats socket /var/lib/haproxy/stats # 统计信息保存位置。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen admin_stats # frontend 和 backend 的组合体，此监控组的名称可按需进行自定义。 - bind 0.0.0.0:8080 # 监听端口。 - mode http # 监控运行的模式，此处为 `http` 模式。 - option httplog # 开始启用记录 HTTP 请求的日志功能。 - maxconn 10 # 最大并发连接数。 - stats refresh 30s # 每隔 30 秒自动刷新监控页面。 - stats uri /haproxy # 监控页面的 URL。 - stats realm HAProxy # 监控页面的提示信息。 - stats auth admin:pingcap123 # 监控页面的用户和密码，可设置多个用户名。 - stats hide-version # 隐藏监控页面上的 HAProxy 版本信息。 - stats admin if TRUE # 手工启用或禁用后端服务器（HAProxy 1.4.9 及之后版本开始支持）。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 - server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 -``` - -### 启动 HAProxy - -- 方法一：执行 `haproxy`，默认读取 `/etc/haproxy/haproxy.cfg`（推荐）。 - - {{< copyable "shell-regular" >}} - - ```bash - haproxy -f /etc/haproxy/haproxy.cfg - ``` - -- 方法二：使用 `systemd` 启动 HAProxy。 - - {{< copyable "shell-regular" >}} - - ```bash - systemctl start haproxy.service - ``` - -### 停止 HAProxy - -- 方法一：使用 `kill -9`。 - - 1. 执行如下命令： - - {{< copyable "shell-regular" >}} - - ```bash - ps -ef | grep haproxy - ``` - - 2. 终止 HAProxy 相关的 PID 进程： - - {{< copyable "shell-regular" >}} - - ```bash - kill -9 ${haproxy.pid} - ``` - -- 方法二：使用 `systemd`。 - - {{< copyable "shell-regular" >}} - - ```bash - systemctl stop haproxy.service - ``` diff --git a/v2.1/reference/best-practices/java-app.md b/v2.1/reference/best-practices/java-app.md deleted file mode 100644 index 41fcd066b104..000000000000 --- a/v2.1/reference/best-practices/java-app.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: 开发 Java 应用使用 TiDB 的最佳实践 -category: reference -aliases: ['/docs-cn/v2.1/reference/best-practices/using-tidb-in-java/'] ---- - -# 开发 Java 应用使用 TiDB 的最佳实践 - -本文主要介绍如何开发 Java 应用程序以更好地使用 TiDB，包括开发中的常见问题与最佳实践。 - -## Java 应用中的数据库相关组件 - -通常 Java 应用中和数据库相关的常用组件有： - -- 网络协议：客户端通过标准 [MySQL 协议](https://dev.mysql.com/doc/internals/en/client-server-protocol.html)和 TiDB 进行网络交互。 -- JDBC API 及实现：Java 应用通常使用 [JDBC (Java Database Connectivity)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) 来访问数据库。JDBC 定义了访问数据库 API，而 JDBC 实现完成标准 API 到 MySQL 协议的转换，常见的 JDBC 实现是 [MySQL Connector/J](https://github.com/mysql/mysql-connector-j)，此外有些用户可能使用 [MariaDB Connector/J](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#about-mariadb-connectorj)。 -- 数据库连接池：为了避免每次创建连接，通常应用会选择使用数据库连接池来复用连接，JDBC [DataSource](https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html) 定义了连接池 API，开发者可根据实际需求选择使用某种开源连接池实现。 -- 数据访问框架：应用通常选择通过数据访问框架 ([MyBatis](http://www.mybatis.org/mybatis-3/zh/index.html), [Hibernate](https://hibernate.org/)) 的封装来进一步简化和管理数据库访问操作。 -- 业务实现：业务逻辑控制着何时发送和发送什么指令到数据库，其中有些业务会使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 切面来控制管理事务的开始和提交逻辑。 - -![Java Component](/media/java-practice-1.png) - -如上图所示，应用可能使用 Spring Transaction 来管理控制事务非手工启停，通过类似 MyBatis 的数据访问框架管理生成和执行 SQL，通过连接池获取已池化的长连接，最后通过 JDBC 接口调用实现通过 MySQL 协议和 TiDB 完成交互。 - -接下来将分别介绍使用各个组件时可能需要关注的问题。 - -## JDBC - -Java 应用尽管可以选择在不同的框架中封装，但在最底层一般会通过调用 JDBC 来与数据库服务器进行交互。对于 JDBC，需要关注的主要有：API 的使用选择和 API Implementer 的参数配置。 - -### JDBC API - -对于基本的 JDBC API 使用可以参考 [JDBC 官方教程](https://docs.oracle.com/javase/tutorial/jdbc/)，本文主要强调几个比较重要的 API 选择。 - -#### 使用 Prepare API - -对于 OLTP 场景，程序发送给数据库的 SQL 语句在去除参数变化后都是可穷举的某几类，因此建议使用[预处理语句 (Prepared Statements)](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html) 代替普通的[文本执行](https://docs.oracle.com/javase/tutorial/jdbc/basics/processingsqlstatements.html#executing_queries)，并复用预处理语句来直接执行，从而避免 TiDB 重复解析和生成 SQL 执行计划的开销。 - -目前多数上层框架都会调用 Prepare API 进行 SQL 执行，如果直接使用 JDBC API 进行开发，注意选择使用 Prepare API。 - -另外需要注意 MySQL Connector/J 实现中默认只会做客户端的语句预处理，会将 `?` 在客户端替换后以文本形式发送到服务端，所以除了要使用 Prepare API，还需要在 JDBC 连接参数中配置 `useServerPrepStmts = true`，才能在 TiDB 服务器端进行语句预处理（下面参数配置章节有详细介绍）。 - -#### 使用 Batch 批量插入更新 - -对于批量插入更新，如果插入记录较多，可以选择使用 [addBatch/executeBatch API](https://www.tutorialspoint.com/jdbc/jdbc-batch-processing)。通过 addBatch 的方式将多条 SQL 的插入更新记录先缓存在客户端，然后在 executeBatch 时一起发送到数据库服务器。 - -> **注意：** -> -> 对于 MySQL Connector/J 实现，默认 Batch 只是将多次 addBatch 的 SQL 发送时机延迟到调用 executeBatch 的时候，但实际网络发送还是会一条条的发送，通常不会降低与数据库服务器的网络交互次数。 -> -> 如果希望 Batch 网络发送，需要在 JDBC 连接参数中配置 `rewriteBatchedStatements = true`（下面参数配置章节有详细介绍）。 - -#### 使用 StreamingResult 流式获取执行结果 - -一般情况下，为提升执行效率，JDBC 会默认提前获取查询结果并将其保存在客户端内存中。但在查询返回超大结果集的场景中，客户端会希望数据库服务器减少向客户端一次返回的记录数，等客户端在有限内存处理完一部分后再去向服务器要下一批。 - -在 JDBC 中通常有以下两种处理方式： - -- 设置 [`FetchSize` 为 `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-implementation-notes.html#ResultSet) 让客户端不缓存，客户端通过 StreamingResult 的方式从网络连接上流式读取执行结果。 -- 使用 Cursor Fetch，首先需[设置 `FetchSize`](http://makejavafaster.blogspot.com/2015/06/jdbc-fetch-size-performance.html) 为正整数，且在 JDBC URL 中配置 `useCursorFetch = true`。 - -TiDB 中同时支持两种方式，但更推荐使用第一种将 `FetchSize` 设置为 `Integer.MIN_VALUE` 的方式，比第二种功能实现更简单且执行效率更高。 - -### MySQL JDBC 参数 - -JDBC 实现通常通过 JDBC URL 参数的形式来提供实现相关的配置。这里以 MySQL 官方的 Connector/J 来介绍[参数配置](https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-configuration-properties.html)（如果使用的是 MariaDB，可以参考 [MariaDB 的类似配置](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)）。因为配置项较多，这里主要关注几个可能影响到性能的参数。 - -#### Prepare 相关参数 - -##### `useServerPrepStmts` - -默认情况下，`useServerPrepStmts` 的值为 `false`，即尽管使用了 Prepare API，也只会在客户端做 “prepare”。因此为了避免服务器重复解析的开销，如果同一条 SQL 语句需要多次使用 Prepare API，则建议设置该选项为 `true`。 - -在 TiDB 监控中可以通过 **Query Summary** > **QPS By Instance** 查看请求命令类型，如果请求中 `COM_QUERY` 被 `COM_STMT_EXECUTE` 或 `COM_STMT_PREPARE` 代替即生效。 - -##### `cachePrepStmts` - -虽然 `useServerPrepStmts = true` 能让服务端执行预处理语句，但默认情况下客户端每次执行完后会 close 预处理语句，并不会复用，这样预处理的效率甚至不如文本执行。所以建议开启 `useServerPrepStmts = true` 后同时配置 `cachePrepStmts = true`，这会让客户端缓存预处理语句。 - -在 TiDB 监控中可以通过 **Query Summary** > **QPS By Instance** 查看请求命令类型，如果类似下图，请求中 `COM_STMT_EXECUTE` 数目远远多于 `COM_STMT_PREPARE` 即生效。 - -![QPS By Instance](/media/java-practice-2.png) - -另外，通过 `useConfigs = maxPerformance` 配置会同时配置多个参数，其中也包括 `cachePrepStmts = true`。 - -##### `prepStmtCacheSqlLimit` - -在配置 `cachePrepStmts` 后还需要注意 `prepStmtCacheSqlLimit` 配置（默认为 `256`），该配置控制客户端缓存预处理语句的最大长度，超过该长度将不会被缓存。 - -在一些场景 SQL 的长度可能超过该配置，导致预处理 SQL 不能复用，建议根据应用 SQL 长度情况决定是否需要调大该值。 - -在 TiDB 监控中通过 **Query Summary** > **QPS by Instance** 查看请求命令类型，如果已经配置了 `cachePrepStmts = true`，但 `COM_STMT_PREPARE` 还是和 `COM_STMT_EXECUTE` 基本相等且有 `COM_STMT_CLOSE`，需要检查这个配置项是否设置得太小。 - -##### `prepStmtCacheSize` - -`prepStmtCacheSize` 控制缓存的预处理语句数目（默认为 `25`），如果应用需要预处理的 SQL 种类很多且希望复用预处理语句，可以调大该值。 - -和上一条类似，在监控中通过 **Query Summary** > **QPS by Instance** 查看请求中 `COM_STMT_EXECUTE` 数目是否远远多于 `COM_STMT_PREPARE` 来确认是否正常。 - -#### Batch 相关参数 - -在进行 batch 写入处理时推荐配置 `rewriteBatchedStatements = true`，在已经使用 `addBatch` 或 `executeBatch` 后默认 JDBC 还是会一条条 SQL 发送，例如： - -```java -pstmt = prepare(“insert into t (a) values(?)”); -pstmt.setInt(1, 10); -pstmt.addBatch(); -pstmt.setInt(1, 11); -pstmt.addBatch(); -pstmt.setInt(1, 12); -pstmt.executeBatch(); -``` - -虽然使用了 batch 但发送到 TiDB 语句还是单独的多条 insert： - -{{< copyable "sql" >}} - -```sql -insert into t(a) values(10); -insert into t(a) values(11); -insert into t(a) values(12); -``` - -如果设置 `rewriteBatchedStatements = true`，发送到 TiDB 的 SQL 将是： - -{{< copyable "sql" >}} - -```sql -insert into t(a) values(10),(11),(12); -``` - -需要注意的是，insert 语句的改写，只能将多个 values 后的值拼接成一整条 SQL，insert 语句如果有其他差异将无法被改写。 -例如： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10) on duplicate key update a = 10; -insert into t (a) values (11) on duplicate key update a = 11; -insert into t (a) values (12) on duplicate key update a = 12; -``` - -上述 insert 语句将无法被改写成一条语句。该例子中，如果将 SQL 改写成如下形式： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10) on duplicate key update a = values(a); -insert into t (a) values (11) on duplicate key update a = values(a); -insert into t (a) values (12) on duplicate key update a = values(a); -``` - -即可满足改写条件，最终被改写成： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10), (11), (12) on duplicate key update a = values(a); -``` - -批量更新时如果有 3 处或 3 处以上更新，则 SQL 语句会改写为 multiple-queries 的形式并发送，这样可以有效减少客户端到服务器的请求开销，但副作用是会产生较大的 SQL 语句，例如这样： - -{{< copyable "sql" >}} - -```sql -update t set a = 10 where id = 1; update t set a = 11 where id = 2; update t set a = 12 where id = 3; -``` - -另外，因为一个[客户端 bug](https://bugs.mysql.com/bug.php?id=96623)，批量更新时如果要配置 `rewriteBatchedStatements = true` 和 `useServerPrepStmts = true`，推荐同时配置 `allowMultiQueries = true` 参数来避免这个 bug。 - -#### 执行前检查参数 - -通过监控可能会发现，虽然业务只向集群进行 insert 操作，却看到有很多多余的 select 语句。通常这是因为 JDBC 发送了一些查询设置类的 SQL 语句（例如 `select @@session.transaction_read_only`）。这些 SQL 对 TiDB 无用，推荐配置 `useConfigs = maxPerformance` 来避免额外开销。 - -`useConfigs = maxPerformance` 会包含一组配置： - -```ini -cacheServerConfiguration = true -useLocalSessionState = true -elideSetAutoCommits = true -alwaysSendSetIsolation = false -enableQueryTimeouts = false -``` - -配置后查看监控，可以看到多余语句减少。 - -## 连接池 - -TiDB (MySQL) 连接建立是比较昂贵的操作（至少对于 OLTP），除了建立 TCP 连接外还需要进行连接鉴权操作，所以客户端通常会把 TiDB (MySQL) 连接保存到连接池中进行复用。 - -Java 的连接池实现很多 ([HikariCP](https://github.com/brettwooldridge/HikariCP), [tomcat-jdbc](https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html), [durid](https://github.com/alibaba/druid), [c3p0](https://www.mchange.com/projects/c3p0/), [dbcp](https://commons.apache.org/proper/commons-dbcp/))，TiDB 不会限定使用的连接池，应用可以根据业务特点自行选择连接池实现。 - -### 连接数配置 - -比较常见的是应用需要根据自身情况配置合适的连接池大小，以 HikariCP 为例： - -- `maximumPoolSize`：连接池最大连接数，配置过大会导致 TiDB 消耗资源维护无用连接，配置过小则会导致应用获取连接变慢，所以需根据应用自身特点配置合适的值，可参考[这篇文章](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)。 -- `minimumIdle`：连接池最小空闲连接数，主要用于在应用空闲时存留一些连接以应对突发请求，同样是需要根据业务情况进行配置。 - -应用在使用连接池时，需要注意连接使用完成后归还连接，推荐应用使用对应的连接池相关监控（如 `metricRegistry`），通过监控能及时定位连接池问题。 - -### 探活配置 - -连接池维护到 TiDB 的长连接，TiDB 默认不会主动关闭客户端连接（除非报错），但一般客户端到 TiDB 之间还会有 LVS 或 HAProxy 之类的网络代理，它们通常会在连接空闲一定时间后主动清理连接。除了注意代理的 idle 配置外，连接池还需要进行保活或探测连接。 - -如果常在 Java 应用中看到以下错误： - -``` -The last packet sent successfully to the server was 3600000 milliseconds ago. The driver has not received any packets from the server. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure -``` - -如果 `n milliseconds ago` 中的 `n` 如果是 0 或很小的值，则通常是执行的 SQL 导致 TiDB 异常退出引起的报错，推荐查看 TiDB stderr 日志；如果 n 是一个非常大的值（比如这里的 3600000），很可能是因为这个连接空闲太久然后被中间 proxy 关闭了，通常解决方式除了调大 proxy 的 idle 配置，还可以让连接池执行以下操作： - -- 每次使用连接前检查连接是否可用。 -- 使用单独线程定期检查连接是否可用。 -- 定期发送 test query 保活连接。 - -不同的连接池实现可能会支持其中一种或多种方式，可以查看所使用的连接池文档来寻找对应配置。 - -## 数据访问框架 - -业务应用通常会使用某种数据访问框架来简化数据库的访问。 - -### MyBatis - -[MyBatis](http://www.mybatis.org/mybatis-3/) 是目前比较流行的 Java 数据访问框架，主要用于管理 SQL 并完成结果集和 Java 对象的来回映射工作。MyBatis 和 TiDB 兼容性很好，从历史 issue 可以看出 MyBatis 很少出现问题。这里主要关注如下几个配置。 - -#### Mapper 参数 - -MyBatis 的 Mapper 中支持两种参数： - -- `select 1 from t where id = #{param1}` 会作为预处理语句，被转换为 `select 1 from t where id = ?` 进行预处理，并使用实际参数来复用执行，通过配合前面的 Prepare 连接参数能获得最佳性能。 -- `select 1 from t where id = ${param2}` 会做文本替换为 `select 1 from t where id = 1` 执行，如果这条语句被预处理为不同参数，可能会导致 TiDB 缓存大量的预处理语句，并且以这种方式执行 SQL 有注入安全风险。 - -#### 动态 SQL Batch - -[动态 SQL - foreach](http://www.mybatis.org/mybatis-3/dynamic-sql.html#foreach) - -要支持将多条 insert 语句自动重写为 `insert ... values(...), (...), ...` 的形式，除了前面所说的在 JDBC 配置 `rewriteBatchedStatements = true` 外，MyBatis 还可以使用动态 SQL 来半自动生成 batch insert。比如下面的 mapper: - -```xml - - insert into test - (id, v1, v2) - values - - ( - #{item.id}, #{item.v1}, #{item.v2} - ) - - on duplicate key update v2 = v1 + values(v1) - -``` - -会生成一个 `insert on duplicate key update` 语句，values 后面的 `(?, ?, ?)` 数目是根据传入的 list 个数决定，最终效果和使用 `rewriteBatchStatements = true` 类似，可以有效减少客户端和 TiDB 的网络交互次数，同样需要注意预处理后超过 `prepStmtCacheSqlLimit` 限制导致不缓存预处理语句的问题。 - -#### Streaming 结果 - -前面介绍了在 JDBC 中如何使用流式读取结果，除了 JDBC 相应的配置外，在 MyBatis 中如果希望读取超大结果集合也需要注意： - -- 可以通过在 mapper 配置中对单独一条 SQL 设置 `fetchSize`（见上一段代码段），效果等同于调用 JDBC `setFetchSize` -- 可以使用带 `ResultHandler` 的查询接口来避免一次获取整个结果集 -- 可以使用 `Cursor` 类来进行流式读取 - -对于使用 xml 配置映射，可以通过在映射 ` - select * from post; - -``` - -而使用代码配置映射，则可以使用 `@Options(fetchSize = Integer.MIN_VALUE)` 并返回 `Cursor` 从而让 SQL 结果能被流式读取。 - -```java -@Select("select * from post") -@Options(fetchSize = Integer.MIN_VALUE) -Cursor queryAllPost(); -``` - -### `ExecutorType` - -在 `openSession` 的时候可以选择 `ExecutorType`，MyBatis 支持三种 executor： - -- Simple：每次执行都会向 JDBC 进行预处理语句的调用（如果 JDBC 配置有开启 `cachePrepStmts`，重复的预处理语句会复用）。 -- Reuse：在 `executor` 中缓存预处理语句，这样不用 JDBC 的 `cachePrepStmts` 也能减少重复预处理语句的调用。 -- Batch：每次更新只有在 `addBatch` 到 query 或 commit 时才会调用 `executeBatch` 执行，如果 JDBC 层开启了 `rewriteBatchStatements`，则会尝试改写，没有开启则会一条条发送。 - -通常默认值是 `Simple`，需要在调用 `openSession` 时改变 `ExecutorType`。如果是 Batch 执行，会遇到事务中前面的 update 或 insert 都非常快，而在读数据或 commit 事务时比较慢的情况，这实际上是正常的，在排查慢 SQL 时需要注意。 - -## Spring Transaction - -在应用代码中业务可能会通过使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 和 AOP 切面的方式来启停事务。 - -通过在方法定义上添加 `@Transactional` 注解标记方法，AOP 将会在方法前开启事务，方法返回结果前 commit 事务。如果遇到类似业务，可以通过查找代码 `@Transactional` 来确定事务的开启和关闭时机。需要特别注意有内嵌的情况，如果发生内嵌，Spring 会根据 [Propagation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/annotation/Propagation.html) 配置使用不同的行为，因为 TiDB 未支持 savepoint，所以不支持嵌套事务。 - -## 其他 - -### 排查工具 - -在 Java 应用发生问题并且不知道业务逻辑情况下，使用 JVM 强大的排查工具会比较有用。这里简单介绍几个常用工具： - -#### jstack - -[jstack](https://docs.oracle.com/javase/7/docs/technotes/tools/share/jstack.html) 对应于 Go 中的 pprof/goroutine，可以比较方便地排查进程卡死的问题。 - -通过执行 `jstack pid`，即可输出目标进程中所有线程的线程 id 和堆栈信息。输出中默认只有 Java 堆栈，如果希望同时输出 JVM 中的 C++ 堆栈，需要加 `-m` 选项。 - -通过多次 jstack 可以方便地发现卡死问题（比如：都通过 Mybatis BatchExecutor flush 调用 update）或死锁问题（比如：测试程序都在抢占应用中某把锁导致没发送 SQL） - -另外，`top -p $PID -H` 或者 Java swiss knife 都是常用的查看线程 ID 的方法。通过 `printf "%x\n" pid` 把线程 ID 转换成 16 进制，然后去 jstack 输出结果中找对应线程的栈信息，可以定位”某个线程占用 CPU 比较高，不知道它在执行什么”的问题。 - -#### jmap & mat - -和 Go 中的 pprof/heap 不同，[jmap](https://docs.oracle.com/javase/7/docs/technotes/tools/share/jmap.html) 会将整个进程的内存快照 dump 下来（go 是分配器的采样），然后可以通过另一个工具 [mat](https://www.eclipse.org/mat/) 做分析。 - -通过 mat 可以看到进程中所有对象的关联信息和属性，还可以观察线程运行的状态。比如：我们可以通过 mat 找到当前应用中有多少 MySQL 连接对象，每个连接对象的地址和状态信息是什么。 - -需要注意 mat 默认只会处理 reachable objects，如果要排查 young gc 问题可以在 mat 配置中设置查看 unreachable objects。另外对于调查 young gc 问题（或者大量生命周期较短的对象）的内存分配，用 Java Flight Recorder 比较方便。 - -#### trace - -线上应用通常无法修改代码，又希望在 Java 中做动态插桩来定位问题，推荐使用 btrace 或 arthas trace。它们可以在不重启进程的情况下动态插入 trace 代码。 - -#### 火焰图 - -Java 应用中获取火焰图较繁琐，可参阅 [Java Flame Graphs Introduction: Fire For Everyone!](http://psy-lob-saw.blogspot.com/2017/02/flamegraphs-intro-fire-for-everyone.html) 来手动获取。 - -## 总结 - -本文从常用的和数据库交互的 Java 组件的角度，阐述了开发 Java 应用程序使用 TiDB 的常见问题与解决办法。TiDB 是高度兼容 MySQL 协议的数据库，基于 MySQL 开发的 Java 应用的最佳实践也多适用于 TiDB。 - -欢迎大家在 [ASK TUG](https://asktug.com/) 踊跃发言，和我们一起分享讨论 Java 应用使用 TiDB 的实践技巧或遇到的问题。 \ No newline at end of file diff --git a/v2.1/reference/best-practices/massive-regions.md b/v2.1/reference/best-practices/massive-regions.md deleted file mode 100644 index 234c30f8b1ab..000000000000 --- a/v2.1/reference/best-practices/massive-regions.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: 海量 Region 集群调优最佳实践 -summary: 了解海量 Region 导致性能问题的原因和优化方法。 -category: reference ---- - -# 海量 Region 集群调优最佳实践 - -在 TiDB 的架构中，所有数据以一定 key range 被切分成若干 Region 分布在多个 TiKV 实例上。随着数据的写入，一个集群中会产生上百万个甚至千万个 Region。单个 TiKV 实例上产生过多的 Region 会给集群带来较大的负担，影响整个集群的性能表现。 - -本文将介绍 TiKV 核心模块 Raftstore 的工作流程，海量 Region 导致性能问题的原因，以及优化性能的方法。 - -## Raftstore 的工作流程 - -一个 TiKV 实例上有多个 Region。Region 消息是通过 Raftstore 模块驱动 Raft 状态机来处理的。这些消息包括 Region 上读写请求的处理、Raft log 的持久化和复制、Raft 的心跳处理等。但是，Region 数量增多会影响整个集群的性能。为了解释这一点，需要先了解 TiKV 的核心模块 Raftstore 的工作流程。 - -![图 1 Raftstore 处理流程示意图](/media/best-practices/raft-process.png) - -> **注意：** -> -> 该图仅为示意，不代表代码层面的实际结构。 - -上图是 Raftstore 处理流程的示意图。如图所示，从 TiDB 发来的请求会通过 gRPC 和 storage 模块变成最终的 KV 读写消息，并被发往相应的 Region，而这些消息并不会被立即处理而是被暂存下来。Raftstore 会轮询检查每个 Region 是否有需要处理的消息。如果 Region 有需要处理的消息，那么 Raftstore 会驱动 Raft 状态机去处理这些消息，并根据这些消息所产生的状态变更去进行后续操作。例如，在有写请求时，Raft 状态机需要将日志落盘并且将日志发送给其他 Region 副本；在达到心跳间隔时，Raft 状态机需要将心跳信息发送给其他 Region 副本。 - -## 性能问题 - -从 Raftstore 处理流程示意图可以看出，需要依次处理各个 Region 的消息。那么在 Region 数量较多的情况下，Raftstore 需要花费一些时间去处理大量 Region 的心跳，从而带来一些延迟，导致某些读写请求得不到及时处理。如果读写压力较大，Raftstore 线程的 CPU 使用率容易达到瓶颈，导致延迟进一步增加，进而影响性能表现。 - -通常在有负载的情况下，如果 Raftstore 的 CPU 使用率达到了 85% 以上，即可视为达到繁忙状态且成为了瓶颈，同时 `propose wait duration` 可能会高达百毫秒级别。 - -> **注意：** -> -> + Raftstore 的 CPU 使用率是指单线程的情况。如果是多线程 Raftstore，可等比例放大使用率。 -> + 由于 Raftstore 线程中有 I/O 操作，所以 CPU 使用率不可能达到 100%。 - -### 性能监控 - -可在 Grafana 的 TiKV 面板下查看相关的监控 metrics： - -+ Thread-CPU 下的 `Raft store CPU` - - 参考值：低于 `raftstore.store-pool-size * 85%`。在 v2.1 版本中无此配置项，因此在 v2.1 中可视为 `raftstore.store-pool-size = 1`。 - - ![图 2 查看 Raftstore CPU](/media/best-practices/raft-store-cpu.png) - -+ Raft Propose 下的 `Propose wait duration` - - `Propose wait duration` 是从发送请求给 Raftstore，到 Raftstore 真正开始处理请求之间的延迟时间。如果该延迟时间较长，说明 Raftstore 比较繁忙或者处理 append log 比较耗时导致 Raftstore 不能及时处理请求。 - - 参考值：低于 50-100ms。 - - ![图 3 查看 Propose wait duration](/media/best-practices/propose-wait-duration.png) - -## 性能优化方法 - -找到性能问题的根源后，可从以下两个方向来解决性能问题： - -+ 减少单个 TiKV 实例的 Region 数 -+ 减少单个 Region 的消息数 - -v2.1 版本中的 Raftstore 为单线程。因此 Region 数超过 10 万后，Raftstore 线程的 CPU 使用率会逐渐成为瓶颈。 - -### 方法一：增加 TiKV 实例 - -如果 I/O 资源和 CPU 资源都比较充足，可在单台机器上部署多个 TiKV 实例，以减少单个 TiKV 实例上的 Region 个数；或者增加 TiKV 集群的机器数。 - -### 方法二：开启 `Region Merge` - -开启 `Region Merge` 也能减少 Region 的个数。与 `Region Split` 相反，`Region Merge` 是通过调度把相邻的小 Region 合并的过程。在集群中删除数据或者执行 `Drop Table`/`Truncate Table` 语句后，可以将小 Region 甚至空 Region 进行合并以减少资源的消耗。 - -通过 pd-ctl 设置以下参数即可开启 `Region Merge`： - -{{< copyable "" >}} - -``` ->> pd-ctl config set max-merge-region-size 20 ->> pd-ctl config set max-merge-region-keys 200000 ->> pd-ctl config set merge-schedule-limit 8 -``` - -> **注意：** -> -> `Region Merge` 已在 TiDB v3.0 中默认开启。 - -详情请参考[如何配置 Region Merge](https://github.com/tikv/tikv/blob/master/docs/how-to/configure/region-merge.md)。 - -同时，默认配置的 `Region Merge` 的参数设置较为保守，可以根据需求参考 [PD 调度策略最佳实践](/v2.1/reference/best-practices/pd-scheduling.md#region-merge-速度慢) 中提供的方法加快 `Region Merge` 过程的速度。 - -#### 方法三：调整 `raft-base-tick-interval` - -除了减少 Region 个数外，还可以通过减少 Region 单位时间内的消息数量来减小 Raftstore 的压力。例如，在 TiKV 配置中适当调大 `raft-base-tick-interval`： - -{{< copyable "" >}} - -``` -[raftstore] -raft-base-tick-interval = "2s" -``` - -`raft-base-tick-interval` 是 Raftstore 驱动每个 Region 的 Raft 状态机的时间间隔，也就是每隔该时长就需要向 Raft 状态机发送一个 tick 消息。增加该时间间隔，可以有效减少 Raftstore 的消息数量。 - -需要注意的是，该 tick 消息的间隔也决定了 `election timeout` 和 `heartbeat` 的间隔。示例如下： - -{{< copyable "" >}} - -``` -raft-election-timeout = raft-base-tick-interval * raft-election-timeout-ticks -raft-heartbeat-interval = raft-base-tick-interval * raft-heartbeat-ticks -``` - -如果 Region Follower 在 `raft-election-timeout` 间隔内未收到来自 Leader 的心跳，就会判断 Leader 出现故障而发起新的选举。`raft-heartbeat-interval` 是 Leader 向 Follower 发送心跳的间隔，因此调大 `raft-base-tick-interval` 可以减少单位时间内 Raft 发送的网络消息，但也会让 Raft 检测到 Leader 故障的时间更长。 - -## 其他问题和解决方案 - -### 切换 PD Leader 的速度慢 - -PD 需要将 Region Meta 信息持久化在 etcd 上，以保证切换 PD Leader 节点后 PD 能快速继续提供 Region 路由服务。随着 Region 数量的增加，etcd 出现性能问题，使得 PD 在切换 Leader 时从 etcd 获取 Region Meta 信息的速度较慢。在百万 Region 量级时，从 etcd 获取信息的时间可能需要十几秒甚至几十秒。 - -因此在 v3.0 版本中，PD 默认开启配置项 `use-region-storage`，将 Region Meta 信息存在本地的 LevelDB 中，并通过其他机制同步 PD 节点间的信息。如果在 v2.1 版本中碰到类似问题，建议升级到 v3.0。 - -### PD 路由信息更新不及时 - -在 TiKV 中，pd-worker 模块将 Region Meta 信息定期上报给 PD，在 TiKV 重启或者切换 Region Leader 时需要通过统计信息重新计算 Region 的 `approximate size/keys`。因此在 Region 数量较多的情况下，pd-worker 单线程可能成为瓶颈，造成任务得不到及时处理而堆积起来。因此 PD 不能及时获取某些 Region Meta 信息以致路由信息更新不及时。该问题不会影响实际的读写，但可能导致 PD 调度不准确以及 TiDB 更新 Region cache 时需要多几次 round-trip。 - -可在 TiKV Grafana 面板中查看 Task 下的 Worker pending tasks 来确定 pd-worker 是否有任务堆积。通常来说，pending tasks 应该维持在一个比较低的值。 - -![图 4 查看 pd-worker](/media/best-practices/pd-worker-metrics.png) - -目前已经在 [TiKV master](https://github.com/tikv/tikv/tree/master) 上对 pd-worker 进行了[效率优化](https://github.com/tikv/tikv/pull/5620)。[TiDB v3.0.5](https://pingcap.com/docs-cn/stable/releases/3.0.5/) 中已带上该优化。如果碰到类似问题，建议升级至 v3.0.5。 - -### Prometheus 查询 metrics 的速度慢 - -在大规模集群中，随着 TiKV 实例数的增加，Prometheus 查询 metrics 时的计算压力较大，导致 Grafana 查看 metrics 的速度较慢。v3.0 版本中设置了一些 metrics 的预计算，让这个问题有所缓解。 diff --git a/v2.1/reference/best-practices/pd-scheduling.md b/v2.1/reference/best-practices/pd-scheduling.md deleted file mode 100644 index 22ef21d010c4..000000000000 --- a/v2.1/reference/best-practices/pd-scheduling.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: PD 调度策略最佳实践 -summary: 了解 PD 调度策略的最佳实践和调优方式 -category: reference ---- - -# PD 调度策略最佳实践 - -本文将详细介绍 PD 调度系统的原理，并通过几个典型场景的分析和处理方式，分享调度策略的最佳实践和调优方式，帮助大家在使用过程中快速定位问题。本文假定你对 TiDB，TiKV 以及 PD 已经有一定的了解，相关核心概念如下： - -- [Leader/Follower/Learner](/v2.1/glossary.md#leaderfollowerlearner) -- [Operator](/v2.1/glossary.md#operator) -- [Operator Step](/v2.1/glossary.md#operator-step) -- [Pending/Down](/v2.1/glossary.md#pendingdown) -- [Region/Peer/Raft Group](/v2.1/glossary.md#regionpeerraft-group) -- [Region Split](/v2.1/glossary.md#region-split) -- [Scheduler](/v2.1/glossary.md#scheduler) -- [Store](/v2.1/glossary.md#store) - -> **注意：** -> -> 本文内容基于 TiDB 3.0 版本，更早的版本（2.x）缺少部分功能的支持，但是基本原理类似，也可以以本文作为参考。 - -## PD 调度原理 - -该部分介绍调度系统涉及到的相关原理和流程。 - -### 调度流程 - -宏观上来看，调度流程大体可划分为 3 个部分： - -1. 信息收集 - - TiKV 节点周期性地向 PD 上报 `StoreHeartbeat` 和 `RegionHeartbeat` 两种心跳消息： - - * `StoreHeartbeat` 包含 Store 的基本信息、容量、剩余空间和读写流量等数据。 - * `RegionHeartbeat` 包含 Region 的范围、副本分布、副本状态、数据量和读写流量等数据。 - - PD 梳理并转存这些信息供调度进行决策。 - -2. 生成调度 - - 不同的调度器从自身的逻辑和需求出发，考虑各种限制和约束后生成待执行的 Operator。这里所说的限制和约束包括但不限于： - - - 不往断连中、下线中、繁忙、空间不足、在大量收发 snapshot 等各种异常状态的 Store 添加副本 - - Balance 时不选择状态异常的 Region - - 不尝试把 Leader 转移给 Pending Peer - - 不尝试直接移除 Leader - - 不破坏 Region 各种副本的物理隔离 - - 不破坏 Label property 等约束 - -3. 执行调度 - - 调度执行的步骤为： - - a. Operator 先进入一个由 `OperatorController` 管理的等待队列。 - - b. `OperatorController` 会根据配置以一定的并发量从等待队列中取出 Operator 并执行。执行的过程就是依次把每个 Operator Step 下发给对应 Region 的 Leader。 - - c. 标记 Operator 为 “finish” 或 “timeout” 状态，然后从执行列表中移除。 - -### 负载均衡 - -Region 负载均衡调度主要依赖 `balance-leader` 和 `balance-region` 两个调度器。二者的调度目标是将 Region 均匀地分散在集群中的所有 Store 上，但它们各有侧重：`balance-leader` 关注 Region 的 Leader，目的是分散处理客户端请求的压力；`balance-region` 关注 Region 的各个 Peer，目的是分散存储的压力，同时避免出现爆盘等状况。 - -`balance-leader` 与 `balance-region` 有着相似的调度流程： - -1. 根据不同 Store 的对应资源量的情况分别打分。 -2. 不断从得分较高的 Store 选择 Leader 或 Peer 迁移到得分较低的 Store 上。 - -两者的分数计算上也有一定差异：`balance-leader` 比较简单，使用 Store 上所有 Leader 所对应的 Region Size 加和作为得分。因为不同节点存储容量可能不一致，计算 `balance-region` 得分会分以下三种情况： - -- 当空间富余时使用数据量计算得分（使不同节点数据量基本上均衡） -- 当空间不足时由使用剩余空间计算得分（使不同节点剩余空间基本均衡） -- 处于中间态时则同时考虑两个因素做加权和当作得分 - -此外，为了应对不同节点可能在性能等方面存在差异的问题，还可为 Store 设置负载均衡的权重。`leader-weight` 和 `region-weight` 分别用于控制 Leader 权重以及 Region 权重（默认值都为 “1”）。假如把某个 Store 的 `leader-weight` 设为 “2”，调度稳定后，则该节点的 Leader 数量约为普通节点的 2 倍；假如把某个 Store 的 `region-weight` 设为 “0.5”，那么调度稳定后该节点的 Region 数量约为其他节点的一半。 - -### 热点调度 - -热点调度对应的调度器是 `hot-region-scheduler`。在 3.0 版本中，统计热点 Region 的方式为： - -1. 根据 Store 上报的信息，统计出持续一段时间读或写流量超过一定阈值的 Region。 -2. 用与负载均衡类似的方式把这些 Region 分散开来。 - -对于写热点，热点调度会同时尝试打散热点 Region 的 Peer 和 Leader；对于读热点，由于只有 Leader 承载读压力，热点调度会尝试将热点 Region 的 Leader 打散。 - -### 集群拓扑感知 - -让 PD 感知不同节点分布的拓扑是为了通过调度使不同 Region 的各个副本尽可能分散，保证高可用和容灾。PD 会在后台不断扫描所有 Region，当发现 Region 的分布不是当前的最优化状态时，会生成调度以替换 Peer，将 Region 调整至最佳状态。 - -负责这个检查的组件叫 `replicaChecker`（跟 Scheduler 类似，但是不可关闭）。它依赖于 `location-labels` 配置项来进行调度。比如配置 `[zone,rack,host]` 定义了三层的拓扑结构：集群分为多个 zone（可用区），每个 zone 下有多个 rack（机架），每个 rack 下有多个 host（主机）。PD 在调度时首先会尝试将 Region 的 Peer 放置在不同的 zone，假如无法满足（比如配置 3 副本但总共只有 2 个 zone）则保证放置在不同的 rack；假如 rack 的数量也不足以保证隔离，那么再尝试 host 级别的隔离，以此类推。 - -### 缩容及故障恢复 - -缩容是指预备将某个 Store 下线，通过命令将该 Store 标记为 “Offline“ 状态，此时 PD 通过调度将待下线节点上的 Region 迁移至其他节点。 - -故障恢复是指当有 Store 发生故障且无法恢复时，有 Peer 分布在对应 Store 上的 Region 会产生缺少副本的状况，此时 PD 需要在其他节点上为这些 Region 补副本。 - -这两种情况的处理过程基本上是一样的。`replicaChecker` 检查到 Region 存在异常状态的 Peer后，生成调度在健康的 Store 上创建新副本替换异常的副本。 - -### Region merge - -Region merge 指的是为了避免删除数据后大量小甚至空的 Region 消耗系统资源，通过调度把相邻的小 Region 合并的过程。Region merge 由 `mergeChecker` 负责，其过程与 `replicaChecker` 类似：PD 在后台遍历，发现连续的小 Region 后发起调度。 - -## 查询调度状态 - -你可以通过观察 PD 相关的 Metrics 或使用 pd-ctl 工具等方式查看调度系统状态。更具体的信息可以参考 [PD 监控](/v2.1/reference/key-monitoring-metrics/pd-dashboard.md)和 [PD Control](/v2.1/reference/tools/pd-control.md)。 - -### Operator 状态 - -**Grafana PD/Operator** 页面展示了 Operator 的相关统计信息。其中比较重要的有： - -- Schedule Operator Create：Operator 的创建情况 -- Operator finish duration：Operator 执行耗时的情况 -- Operator Step duration：不同 Operator Step 执行耗时的情况 - -查询 Operator 的 pd-ctl 命令有： - -- `operator show`：查询当前调度生成的所有 Operator -- `operator show [admin | leader | region]`：按照类型查询 Operator - -### Balance 状态 - -**Grafana PD/Statistics - Balance** 页面展示了负载均衡的相关统计信息，其中比较重要的有： - -- Store Leader/Region score：每个 Store 的得分 -- Store Leader/Region count：每个 Store 的 Leader/Region 数量 -- Store available：每个 Store 的剩余空间 - -使用 pd-ctl 的 `store` 命令可以查询 Store 的得分、数量、剩余空间和 weight 等信息。 - -### 热点调度状态 - -**Grafana PD/Statistics - hotspot** 页面展示了热点 Region 的相关统计信息，其中比较重要的有： - -- Hot write Region’s leader/peer distribution：写热点 Region 的 Leader/Peer 分布情况 -- Hot read Region’s leader distribution：读热点 Region 的 Leader 分布情况 - -使用 pd-ctl 同样可以查询上述信息，可以使用的命令有： - -- `hot read`：查询读热点 Region 信息 -- `hot write`：查询写热点 Region 信息 -- `hot store`：按 Store 统计热点分布情况 -- `region topread [limit]`：查询当前读流量最大的 Region -- `region topwrite [limit]`：查询当前写流量最大的 Region - -### Region 健康度 - -**Grafana PD/Cluster/Region health** 面板展示了异常 Region 的相关统计信息，包括 Pending Peer、Down Peer、Offline Peer，以及副本数过多或过少的 Region。 - -通过 pd-ctl 的 `region check` 命令可以查看具体异常的 Region 列表： - -- `region check miss-peer`：缺副本的 Region -- `region check extra-peer`：多副本的 Region -- `region check down-peer`：有副本状态为 Down 的 Region -- `region check pending-peer`：有副本状态为 Pending 的 Region - -## 调度策略控制 - -使用 pd-ctl 可以从以下三个方面来调整 PD 的调度策略。更具体的信息可以参考 [PD Control](/v2.1/reference/tools/pd-control.md)。 - -### 启停调度器 - -pd-ctl 支持动态创建和删除 Scheduler，你可以通过这些操作来控制 PD 的调度行为，如： - -- `scheduler show`：显示当前系统中的 Scheduler -- `scheduler remove balance-leader-scheduler`：删除（停用）balance region 调度器 -- `scheduler add evict-leader-scheduler-1`：添加移除 Store 1 的所有 Leader 的调度器 - -### 手动添加 Operator - -PD 支持直接通过 pd-ctl 来创建或删除 Operator，如： - -- `operator add add-peer 2 5`：在 Store 5 上为 Region 2 添加 Peer -- `operator add transfer-leader 2 5`：将 Region 2 的 Leader 迁移至 Store 5 -- `operator add split-region 2`：将 Region 2 拆分为 2 个大小相当的 Region -- `operator remove 2`：取消 Region 2 当前待执行的 Operator - -### 调度参数调整 - -使用 pd-ctl 执行 `config show` 命令可以查看所有的调度参数，执行 `config set {key} {value}` 可以调整对应参数的值。常见调整如下： - -- `leader-schedule-limit`：控制 Transfer Leader 调度的并发数 -- `region-schedule-limit`：控制增删 Peer 调度的并发数 -- `disable-replace-offline-replica`：停止处理节点下线的调度 -- `disable-location-replacement`：停止处理调整 Region 隔离级别相关的调度 -- `max-snapshot-count`：每个 Store 允许的最大收发 Snapshot 的并发数 - -## 典型场景分析与处理 - -该部分通过几个典型场景及其应对方式说明 PD 调度策略的最佳实践。 - -### Leader/Region 分布不均衡 - -PD 的打分机制决定了一般情况下，不同 Store 的 Leader Count 和 Region Count 不能完全说明负载均衡状态，所以需要从 TiKV 的实际负载或者存储空间占用来判断是否有负载不均衡的状况。 - -确认 Leader/Region 分布不均衡后，首先观察不同 Store 的打分情况。 - -如果不同 Store 的打分是接近的，说明 PD 认为此时已经是均衡状态了，可能的原因有： - -- 存在热点导致负载不均衡。可以参考[热点分布不均匀](#热点分布不均匀)中的解决办法进行分析处理。 -- 存在大量空 Region 或小 Region，因此不同 Store 的 Leader 数量差别特别大，导致 Raftstore 负担过重。此时需要开启 [Region Merge](#region-merge) 并尽可能加速合并。 -- 不同 Store 的软硬件环境存在差异。可以酌情调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 -- 其他不明原因。仍可以通过调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 - -如果不同 Store 的分数差异较大，需要进一步检查 Operator 的相关 Metrics，特别关注 Operator 的生成和执行情况，这时大体上又分两种情况： - -- 生成的调度是正常的，但是调度的速度很慢。可能的原因有： - - - 调度速度受限于 limit 配置。PD 默认配置的 limit 比较保守，在不对正常业务造成显著影响的前提下，可以酌情将 `leader-schedule-limit` 或 `region-schedule-limit` 调大一些。此外， `max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 - - 系统中同时运行有其他的调度任务产生竞争，导致 balance 速度上不去。这种情况下如果 balance 调度的优先级更高，可以先停掉其他的调度或者限制其他调度的速度。例如 Region 没均衡的情况下做下线节点操作，下线的调度与 Region Balance 会抢占 `region-schedule-limit` 配额，此时你可以调小 `replica-schedule-limit` 以限制下线调度的速度，或者设置 `disable-replace-offline-replica = true` 来暂时关闭下线流程。 - - 调度执行得太慢。可以通过 **Operator step duration** 进行判断。通常不涉及到收发 Snapshot 的 Step（比如 `TransferLeader`，`RemovePeer`，`PromoteLearner` 等）的完成时间应该在毫秒级，涉及到 Snapshot 的 Step（如 `AddLearner`，`AddPeer` 等）的完成时间为数十秒。如果耗时明显过高，可能是 TiKV 压力过大或者网络等方面的瓶颈导致的，需要具体情况具体分析。 - -- 没能生成对应的 balance 调度。可能的原因有： - - - 调度器未被启用。比如对应的 Scheduler 被删除了，或者 limit 被设置为 “0”。 - - 由于其他约束无法进行调度。比如系统中有 `evict-leader-scheduler`，此时无法把 Leader 迁移至对应的 Store。再比如设置了 Label property，也会导致部分 Store 不接受 Leader。 - - 集群拓扑的限制导致无法均衡。比如 3 副本 3 数据中心的集群，由于副本隔离的限制，每个 Region 的 3 个副本都分别分布在不同的数据中心，假如这 3 个数据中心的 Store 数不一样，最后调度就会收敛在每个数据中心均衡，但是全局不均衡的状态。 - -### 节点下线速度慢 - -这个场景需要从 Operator 相关的 Metrics 入手，分析 Operator 的生成执行情况。 - -如果调度在正常生成，只是速度很慢，可能的原因有： - -- 调度速度受限于 limit 配置。可以适当调大 `replica-schedule-limit`，`max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 -- 系统中同时运行有其他的调度任务产生竞争。处理方法参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡)。 -- 下线单个节点时，由于待操作的 Region 有很大一部分（3 副本配置下约 1/3）的 Leader 都集中在下线的节点上，下线速度会受限于这个单点生成 Snapshot 的速度。你可以通过手动给该节点添加一个 `evict-leader-scheduler` 调度器迁走 Leader 来加速。 - -如果没有对应的 Operator 调度生成，可能的原因有： - -- 下线调度被关闭，或者 `replica-schedule-limit` 被设为 “0”。 -- 找不到节点来转移 Region。例如相同 Label 的替代节点可用容量都不足 20%，PD 为了避免爆盘的风险会停止调度。这种情况需要添加更多节点，或者删除一些数据释放空间。 - -### 节点上线速度慢 - -目前 PD 没有对节点上线特殊处理。节点上线实际上是依靠 balance region 机制来调度的，所以参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡) 中的排查步骤即可。 - -### 热点分布不均匀 - -热点调度的问题大体上可以分为以下几种情况： - -- 从 PD 的 Metrics 能看出来有不少 hot Region，但是调度速度跟不上，不能及时地把热点 Region 分散开来。 - - **解决方法**：调大 `hot-region-schedule-limit` 并减少其他调度器的 limit 配额，从而加快热点调度的速度。还可调小 `hot-region-cache-hits-threshold` 使 PD 对更快响应流量的变化。 - -- 单一 Region 形成热点，比如大量请求频繁 scan 一个小表，这个可以从业务角度或者 Metrics 统计的热点信息看出来。由于单 Region 热点现阶段无法使用打散的手段来消除，需要确认热点 Region 后手动添加 `split-region` 调度将这样的 Region 拆开。 - -- 从 PD 的统计来看没有热点，但是从 TiKV 的相关 Metrics 可以看出部分节点负载明显高于其他节点，成为整个系统的瓶颈。这是因为目前 PD 统计热点 Region 的维度比较单一，仅针对流量进行分析，在某些场景下无法准确定位热点。例如部分 Region 有大量的点查请求，从流量上来看并不显著，但是过高的 QPS 导致关键模块达到瓶颈。 - - **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) 文档。 - -### Region Merge 速度慢 - -Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-schedule-limit` 及 `region-schedule-limit`），或者是与其他调度器产生了竞争。具体来说，可有如下处理方式： - -- 假如已经从相关 Metrics 得知系统中有大量的空 Region，这时可以通过把 `max-merge-region-size` 和 `max-merge-region-keys` 调整为较小值来加快 Merge 速度。这是因为 Merge 的过程涉及到副本迁移，所以 Merge 的 Region 越小，速度就越快。如果生成 Merge Operator 的速度很快，想进一步加快 Region Merge 过程，还可以把 `patrol-region-interval` 调整为 "10ms" ，这个能加快巡检 Region 的速度，但是会消耗更多的 CPU 资源。 - -- 创建过大量 Table 后（包括执行 `Truncate Table` 操作）又清空了。此时如果开启了 split table 特性，这些空 Region 是无法合并的，此时需要调整以下参数关闭这个特性： - - - TiKV: `split-region-on-table` 设为 false - - PD: `namespace-classifier` 设为 “” - -- 对于 3.0.4 和 2.1.16 以前的版本，Region 中 Key 的个数（`approximate_keys`）在特定情况下（大部分发生在删表之后）统计不准确，造成 keys 的统计值很大，无法满足 `max-merge-region-keys` 的约束。你可以通过调大 `max-merge-region-keys` 来避免这个问题。 - -### TiKV 节点故障处理策略 - -没有人工介入时，PD 处理 TiKV 节点故障的默认行为是，等待半小时之后（可通过 `max-store-down-time` 配置调整），将此节点设置为 Down 状态，并开始为涉及到的 Region 补充副本。 - -实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 diff --git a/v2.1/reference/configuration/pd-server/configuration.md b/v2.1/reference/configuration/pd-server/configuration.md deleted file mode 100644 index c8905db9d160..000000000000 --- a/v2.1/reference/configuration/pd-server/configuration.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: PD 配置参数 -category: reference ---- - -# PD 配置参数 - -PD 可以通过命令行参数或环境变量配置。 - -## `--advertise-client-urls` - -+ 对外客户端访问 URL 列表。 -+ 默认：`${client-urls}` -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，客户端并不能通过 PD 自己监听的 client URLs 来访问到 PD，这时候，你就可以设置 advertise urls 来让客户端访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 `-p 2379:2379`，那么可以设置为 `--advertise-client-urls="http://192.168.100.113:2379"`，客户端可以通过 `http://192.168.100.113:2379` 来找到这个服务。 - -## `--advertise-peer-urls` - -+ 对外其他 PD 节点访问 URL 列表。 -+ 默认：`${peer-urls}` -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，其他节点并不能通过 PD 自己监听的 peer URLs 来访问到 PD，这时候，你就可以设置 advertise urls 来让其他节点访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 `-p 2380:2380`，那么可以设置为 `--advertise-peer-urls="http://192.168.100.113:2380"`，其他 PD 节点可以通过 `http://192.168.100.113:2380` 来找到这个服务。 - -## `--client-urls` - -+ 处理客户端请求监听 URL 列表。 -+ 默认：`http://127.0.0.1:2379` -+ 如果部署一个集群，\-\-client-urls 必须指定当前主机的 IP 地址，例如 `http://192.168.100.113:2379"`，如果是运行在 docker 则需要指定为 `http://0.0.0.0:2379`。 - -## `--peer-urls` - -+ 处理其他 PD 节点请求监听 URL 列表。 -+ default: `http://127.0.0.1:2380` -+ 如果部署一个集群，\-\-peer-urls 必须指定当前主机的 IP 地址，例如 `http://192.168.100.113:2380`，如果是运行在 docker 则需要指定为 `http://0.0.0.0:2380`。 - -## `--config` - -+ 配置文件。 -+ 默认："" -+ 如果你指定了配置文件，PD 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，PD 就会使用命令行参数的配置来覆盖配置文件里面的。 - -## `--data-dir` - -+ PD 存储数据路径。 -+ 默认：`default.${name}` - -## `--initial-cluster` - -+ 初始化 PD 集群配置。 -+ 默认：`{name}=http://{advertise-peer-url}` -+ 例如，如果 name 是 "pd", 并且 `advertise-peer-urls` 是 `http://192.168.100.113:2380`, 那么 `initial-cluster` 就是 `pd=http://192.168.100.113:2380`。 -+ 如果你需要启动三台 PD，那么 `initial-cluster` 可能就是 - `pd1=http://192.168.100.113:2380, pd2=http://192.168.100.114:2380, pd3=192.168.100.115:2380`。 - -## `--join` - -+ 动态加入 PD 集群。 -+ 默认："" -+ 如果你想动态将一台 PD 加入集群，你可以使用 `--join="${advertise-client-urls}"`， `advertise-client-url` 是当前集群里面任意 PD 的 `advertise-client-url`，你也可以使用多个 PD 的，需要用逗号分隔。 - -## `-L` - -+ Log 级别。 -+ 默认："info" -+ 我们能选择 debug, info, warn, error 或者 fatal。 - -## `--log-file` - -+ Log 文件。 -+ 默认："" -+ 如果没设置这个参数，log 会默认输出到 "stderr"，如果设置了，log 就会输出到对应的文件里面，在每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份。 - -## `--log-rotate` - -+ 是否开启日志切割。 -+ 默认：true -+ 当值为 true 时,按照 PD 配置文件中 `[log.file]` 信息执行。 - -## `--name` - -+ 当前 PD 的名字。 -+ 默认："pd" -+ 如果你需要启动多个 PD，一定要给 PD 使用不同的名字 - -## `--cacert` - -+ CA 文件路径，用于开启 TLS。 -+ 默认："" - -## `--cert` - -+ 包含 X509 证书的 PEM 文件路径，用户开启 TLS。 -+ 默认："" - -## `--key` - -+ 包含 X509 key 的 PEM 文件路径，用于开启 TLS。 -+ 默认："" - -## `--namespace-classifier` - -+ 指定 PD 使用的 namespace 分类器。 -+ 默认："table" -+ 如果 TiKV 不与 TiDB 集群配合运行，建议配置为 'default'。 diff --git a/v2.1/reference/configuration/tidb-server/configuration-file.md b/v2.1/reference/configuration/tidb-server/configuration-file.md deleted file mode 100644 index 27ca5fb60109..000000000000 --- a/v2.1/reference/configuration/tidb-server/configuration-file.md +++ /dev/null @@ -1,334 +0,0 @@ ---- -title: TiDB 配置文件描述 -category: reference ---- - - - -# TiDB 配置文件描述 - -TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/config.toml.example](https://github.com/pingcap/tidb/blob/release-2.1/config/config.toml.example) 找到默认值的配置文件，重命名为 `config.toml` 即可。本文档只介绍未包含在[命令行参数](https://pingcap.com/docs-cn/v2.1/reference/configuration/tidb-server/configuration)中的参数。 - -### `split-table` - -+ 为每个 table 建立单独的 Region。 -+ 默认值：true -+ 如果需要创建大量的表，我们建议把这个参数设置为 false。 - -### `oom-action` - -+ 指定 TiDB 发生 out-of-memory 错误时的操作。 -+ 默认值："log" -+ 现在合法的选项是 ["log", "cancel"]，如果为 "log"，仅仅是打印日志，不作实质处理。如果为 "cancel"，我们会取消执行这个操作，并且输出日志。 - -### `mem-quota-query` - -+ 单条 SQL 语句可以占用的最大内存阈值。 -+ 默认值：34359738368 -+ 超过该值的请求会被 `oom-action` 定义的行为所处理。 - -### `enable-streaming` - -+ 开启 coprocessor 的 streaming 获取数据模式。 -+ 默认值：false - -### `lower-case-table-names` - -+ 这个选项可以设置 TiDB 的系统变量 `lower_case_table_names` 的值。 -+ 默认值：2 -+ 具体可以查看 MySQL 关于这个变量的[描述](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_lower_case_table_names) - -> **注意：** -> -> 目前 TiDB 只支持将该选项的值设为 2，即按照大小写来保存表名，按照小写来比较（不区分大小写）。 - -### `lease` - -+ DDL 租约超时时间。 -+ 默认值：45s -+ 单位：秒 - -### `compatible-kill-query` - -+ 设置 `KILL` 语句的兼容性。 -+ 默认值：false -+ TiDB 中 `KILL xxx` 的行为和 MySQL 中的行为不相同。为杀死一条查询，在 TiDB 里需要加上 `TIDB` 关键词，即 `KILL TIDB xxx`。但如果把 `compatible-kill-query` 设置为 true，则不需要加上 `TIDB` 关键词。 -+ 这种区别很重要，因为当用户按下 Ctrl+C 时，MySQL 命令行客户端的默认行为是：创建与后台的新连接，并在该新连接中执行 `KILL` 语句。如果负载均衡器或代理已将该新连接发送到与原始会话不同的 TiDB 服务器实例，则该错误会话可能被终止，从而导致使用 TiDB 集群的业务中断。只有当您确定在 `KILL` 语句中引用的连接正好位于 `KILL` 语句发送到的服务器上时，才可以启用 `compatible-kill-query`。 - -### `check-mb4-value-in-utf8` - -+ 开启检查 utf8mb4 字符的开关，如果开启此功能，字符集是 utf8，且在 utf8 插入 mb4 字符，系统将会报错。 -+ 默认值：true - -### `treat-old-version-utf8-as-utf8mb4` - -+ 将旧表中的 utf8 字符集当成 utf8mb4的开关。 -+ 默认值：true - -## log - -日志相关的配置项。 - -### `format` - -+ 指定日志输出的格式，可选项为 [json, text, console]。 -+ 默认值："text" - -### `disable-timestamp` - -+ 是否禁止在日志中输出时间戳。 -+ 默认值：false -+ 如果设置为 true，那么日志里面将不会输出时间戳。 - -### `slow-query-file` - -+ 慢查询日志的文件名。 -+ 默认值："tidb-slow.log"，注：由于 TiDB V2.1.8 更新了慢日志格式，所以将慢日志单独输出到了慢日志文件。V2.1.8 之前的版本，该变量的默认值是 ""。 -+ 设置后，慢查询日志会单独输出到该文件。 - -### `slow-threshold` - -+ 输出慢日志的耗时阈值。 -+ 默认值：300ms -+ 当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。 - -### `expensive-threshold` - -+ 输出 `expensive` 操作的行数阈值。 -+ 默认值：10000 -+ 当查询的行数（包括中间结果，基于统计信息）大于这个值，我们就会当成是一个 `expensive` 的操作，输出一个前缀带有 `[EXPENSIVE_QUERY]` 的日志。 - -### `query-log-max-len` - -+ 最长的 SQL 输出长度。 -+ 默认值：2048 -+ 当语句的长度大于 `query-log-max-len`，将会被截断输出。 - -## log.file - -日志文件相关的配置项。 - -#### `filename` - -+ 一般日志文件名字。 -+ 默认值："" -+ 如果设置，会输出一般日志到这个文件。 - -#### `max-size` - -+ 日志文件的大小限制。 -+ 默认值：300MB -+ 最大设置上限为 4GB。 - -#### `max-days` - -+ 日志最大保留的天数。 -+ 默认值：0 -+ 默认不清理；如果设置了参数值，在 `max-days` 之后 TiDB 会清理过期的日志文件。 - -#### `max-backups` - -+ 保留的日志的最大数量。 -+ 默认值：0 -+ 默认全部保存；如果设置为 7，会最多保留 7 个老的日志文件。 - -#### `log-rotate` - -+ 是否每日创建一个新的日志文件。 -+ 默认值：true -+ 如果设置为 true，每天会新建新的日志文件，如果设置为 false，那么只会输出到一个日志文件。 - -## security - -安全相关配置。 - -### `ssl-ca` - -+ PEM 格式的受信任 CA 的证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-cert`、`--ssl-key` 选项时，TiDB 将在客户端出示证书的情况下根据该选项指定的受信任的 CA 列表验证客户端证书。若验证失败，则连接会被终止。 -+ 即使设置了该选项，若客户端没有出示证书，则安全连接仍然继续，不会进行客户端证书验证。 - -### `ssl-cert` - -+ PEM 格式的 SSL 证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-key` 选项时，TiDB 将接受（但不强制）客户端使用 TLS 安全地连接到 TiDB。 -+ 若指定的证书或私钥无效，则 TiDB 会照常启动，但无法接受安全连接。 - -### `ssl-key` - -+ PEM 格式的 SSL 证书密钥文件路径，即 `--ssl-cert` 所指定的证书的私钥。 -+ 默认值："" -+ 目前 TiDB 不支持加载由密码保护的私钥。 - -### `cluster-ssl-ca` - -+ CA 根证书，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-cert` - -+ ssl 证书文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-key` - -+ ssl 私钥文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `skip-grant-table` - -+ 是否跳过权限检查 -+ 默认值：false - -## performance - -性能相关配置。 - -### `max-procs` - -+ TiDB 的 CPU 使用数量。 -+ 默认值：0 -+ 默认值为 0 表示使用机器上所有的 CPU；如果设置成 n，那么 TiDB 会使用 n 个 CPU 数量。 - -### `stmt-count-limit` - -+ TiDB 一个事务允许的最大语句条数限制。 -+ 默认值：5000 -+ 在一个事务中，超过 `stmt-count-limit` 条语句后还没有 rollback 或者 commit，TiDB 将会返回 `statement count 5001 exceeds the transaction limitation, autocommit = false` 错误。 - -### `tcp-keep-alive` - -+ TiDB 在 TCP 层开启 keepalive。 -+ 默认值：false - -### `cross-join` - -+ 默认值：true -+ 默认可以执行在做 join 时两边表没有任何条件（where 字段）的语句；如果设置为 false，则有这样的 join 语句出现时，server 会拒绝执行 - -### `stats-lease` - -+ TiDB 重载统计信息，更新表行数，检查是否需要自动 analyze，利用 feedback 更新统计信息以及加载列的统计信息的时间间隔。 -+ 默认：3s - - 每隔 `stats-lease` 时间，TiDB 会检查统计信息是否有更新，如果有会将其更新到内存中 - - 每隔 `20 * stats-lease` 时间，TiDB 会将 DML 产生的总行数以及修改的行数变化持久化下来 - - 每隔 `stats-lease` 时间，TiDB 会检查是否有表或者索引需要自动 analyze - - 每隔 `stats-lease` 时间，TiDB 会检查是否有列的统计信息需要被加载到内存中 - - 每隔 `200 * stats-lease` 时间，TiDB 会将内存中缓存的 feedback 写入系统表中 - - 每隔 `5 * stats-lease` 时间，TiDB 会读取系统表中的 feedback，更新统计信息 -+ 当 `stats-lease` 为 0 时， 上述所有操作都不会再进行。 - -### `run-auto-analyze` - -+ TiDB 是否做自动的 Analyze。 -+ 默认值：true - -### `feedback-probability` - -+ TiDB 对查询收集统计信息反馈的概率。 -+ 默认值：0.05 -+ 对于每一个查询，TiDB 会以 `feedback-probability` 的概率收集查询的反馈，用于更新统计信息。 - -### `query-feedback-limit` - -+ 在内存中缓存的最大 Query Feedback 数量，超过这个数量的 Feedback 会被丢弃。 -+ 默认值：1024 - -### `pseudo-estimate-ratio` - -+ 修改过的行数/表的总行数的比值，超过该值时系统会认为统计信息已经过期，会采用 pseudo 的统计信息。 -+ 默认值：0.8 -+ 最小值为 0；最大值为 1。 - -### `force-priority` - -+ 把所有的语句优先级设置为 force-priority 的值。 -+ 默认值：NO_PRIORITY -+ 可选值：NO_PRIORITY, LOW_PRIORITY, HIGH_PRIORITY, DELAYED。 - -## prepared-plan-cache - -prepare 语句的 Plan cache 设置。 - -### `enabled` - -+ 开启 prepare 语句的 plan cache。 -+ 默认值：false - -### `capacity` - -+ 缓存语句的数量。 -+ 默认值：100 - -## tikv-client - -### `grpc-connection-count` - -+ 跟每个 TiKV 之间建立的最大连接数。 -+ 默认值：16 - -### `grpc-keepalive-time` - -+ TiDB 与 TiKV 节点之间 rpc 连接 keepalive 时间间隔，如果超过该值没有网络包，grpc client 会 ping 一下 TiKV 查看是否存活。 -+ 默认值：10 -+ 单位：秒 - -### `grpc-keepalive-timeout` - -+ TiDB 与 TiKV 节点 rpc keepalive 检查的超时时间 -+ 默认值：3 -+ 单位：秒 - -### `commit-timeout` - -+ 执行事务提交时，最大的超时时间。 -+ 默认值：41s -+ 这个值必须是大于两倍 Raft 选举的超时时间。 - -### `max-txn-time-use` - -+ 单个事务允许的最大执行时间。 -+ 默认值：590 -+ 单位：秒 - -## txn-local-latches - -事务内存锁相关配置，当本地事务冲突比较多时建议开启。 - -### `enable` - -+ 开启 -+ 默认值：false - -### `capacity` - -+ Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。 -+ 默认值：1024000 - -## binlog - -TiDB Binlog 相关配置。 - -### `enable` - -+ 开启 binlog 开关。 -+ 默认值：false - -### `write-timeout` - -+ 写 binlog 的超时时间，推荐不修改该值。 -+ 默认值：15s -+ 单位：秒 - -### `ignore-error` - -+ 忽略写 binlog 发生的错误时处理开关，推荐不修改该值。 -+ 默认值：false -+ 如果设置为 `true`，发生错误时，TiDB 会停止写入 binlog，并且在监控项 `tidb_server_critical_error_total` 上计数加 1；如果设置为 `false`，写入 binlog 失败，会停止整个 TiDB 的服务。 - -### `binlog-socket` - -+ binlog 输出网络地址。 -+ 默认值："" diff --git a/v2.1/reference/configuration/tidb-server/configuration.md b/v2.1/reference/configuration/tidb-server/configuration.md deleted file mode 100644 index fa9e81adb9df..000000000000 --- a/v2.1/reference/configuration/tidb-server/configuration.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: TiDB 配置参数 -category: reference ---- - -# TiDB 配置参数 - -TiDB 通过命令行参数或环境变量配置。默认的 TiDB 端口为 4000（客户端请求）与 10080（状态报告）。 - -## `--advertise-address` - -+ 登录 TiDB 的 IP 地址 -+ 默认："" -+ 必须确保用户和集群中的其他机器都能够访问到该 IP 地址 - -## `--binlog-socket` - -+ TiDB 服务使用 unix socket file 方式接受内部连接，如 Pump 服务 -+ 默认："" -+ 例如，可以使用 "/tmp/pump.sock" 来接受 Pump unix socket file 通信 - -## `--config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiDB 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，TiDB 就会使用命令行参数的配置来覆盖配置文件里面的。详细的配置项请参阅 [TiDB 配置文件描述](/v2.1/reference/configuration/tidb-server/configuration-file.md)。 - -## `--host` - -+ TiDB 服务监听 host -+ 默认："0.0.0.0" -+ TiDB 服务会监听这个 host -+ 0.0.0.0 默认会监听所有的网卡地址。如果有多块网卡，可以指定对外提供服务的网卡，如 192.168.100.113 - -## `-L` - -+ Log 级别 -+ 默认："info" -+ 我们能选择 debug, info, warn, error 或者 fatal - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 "stderr"；如果设置了该参数，log 会输出到对应的文件里面。每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--log-slow-query` - -+ 慢查询日志文件路径 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 `--log-file` 指定的文件中 - -## `--metrics-addr` - -+ Prometheus Pushgateway 地址 -+ 默认："" -+ 如果该参数为空，TiDB 不会将统计信息推送给 Pushgateway。参数格式示例：`--metrics-addr=192.168.100.115:9091` - -## `--metrics-interval` - -+ 推送统计信息到 Prometheus Pushgateway 的时间间隔 -+ 默认：15s -+ 设置为 0 表明不推送统计信息给 Pushgateway。示例：`--metrics-interval=2` 是每两秒推送到 Pushgateway - -## `-P` - -+ TiDB 服务监听端口 -+ 默认："4000" -+ TiDB 服务将会使用这个端口接受 MySQL 客户端发过来的请求 - -## `--path` - -+ 对于本地存储引擎 "mocktikv" 来说，path 指定的是实际的数据存放路径 -+ 对于 `--store = tikv` 时必须指定path，`--store = mocktikv` 时，如果不指定 path，会使用默认值。 -+ 对于 "TiKV" 存储引擎来说，path 指定的是实际的 PD 地址。假如在 192.168.100.113:2379, 192.168.100.114:2379 和 192.168.100.115:2379 上面部署了 PD，那么 path 为 "192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379" -+ 默认："/tmp/tidb" -+ 可以通过 `tidb-server --store=mocktikv --path=""` 来启动一个纯内存引擎的 TiDB。 - -## `--proxy-protocol-networks` - -+ PROXY Protocol 允许的代理服务器地址列表，如果需要配置多个地址用`,`分隔。 -+ 默认："" -+ 如果该参数为空，TiDB 会禁用 PROXY Protocol 功能。地址可以使用 IP 地址 (192.168.1.50) 或者 CIDR (192.168.1.0/24)，`*` 代表所有地址。 - -## `--proxy-protocol-header-timeout` - -+ PROXY Protocol 请求头读取超时时间 -+ 默认：5 -+ 单位：秒 - -> **注意：** -> -> 不要将该参数配置为 `0`。除非特殊情况，一般使用默认值即可。 - -## `--report-status` - -+ 用于打开或者关闭服务状态监听端口 -+ 默认：true -+ 将参数值设置为 `true` 表明开启状态监听端口；设置为 `false` 表明关闭状态监听端口 - -## `--run-ddl` - -+ tidb-server 是否运行 DDL 语句，集群内至少需要有一台 tidb-server 设置该参数 -+ 默认：true -+ 值可以为 `true` 或者 `false`。设置为 `true` 表明自身会运行 DDL；设置为 `false` 表明自身不会运行 DDL - -## `--socket string` - -+ TiDB 服务使用 unix socket file 方式接受外部连接 -+ 默认："" -+ 例如可以使用 "/tmp/tidb.sock" 来打开 unix socket file - -## `--status` - -+ TiDB 服务状态监听端口 -+ 默认："10080" -+ 这个端口是为了展示 TiDB 内部数据用的。包括 [prometheus 统计](https://prometheus.io/) 以及 [pprof](https://golang.org/pkg/net/http/pprof/) -+ Prometheus 统计可以通过 `http://host:status_port/metrics` 访问 -+ pprof 数据可以通过 `http://host:status_port/debug/pprof` 访问 - -## `--store` - -+ 用来指定 TiDB 底层使用的存储引擎 -+ 默认："mocktikv" -+ 可以选择 "mocktikv"（本地存储引擎）或者 "tikv"（分布式存储引擎） - -## `--token-limit` - -+ TiDB 中同时允许运行的 Session 数量，用于流量控制。 -+ 默认：1000 -+ 如果当前运行的连接多余这个 token-limit，那么请求会阻塞等待已经完成的操作释放 Token。 - -## `-V` - -+ 输出 TiDB 的版本 -+ 默认："" diff --git a/v2.1/reference/configuration/tidb-server/mysql-variables.md b/v2.1/reference/configuration/tidb-server/mysql-variables.md deleted file mode 100644 index c2ed5dcbed82..000000000000 --- a/v2.1/reference/configuration/tidb-server/mysql-variables.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: 系统变量 -category: reference ---- - -# 系统变量 - -MySQL 系统变量 (System Variables) 是一些系统参数，用于调整数据库运行时的行为，根据变量的作用范围分为全局范围有效（Global Scope）以及会话级别有效（Session Scope）。TiDB 支持 MySQL5.7 的所有系统变量，大部分变量仅仅是为了兼容性而支持，不会影响运行时行为。 - -## 设置系统变量 - -通过 [`SET` 语句](/v2.1/reference/sql/statements/set-variable.md) 可以修改系统变量的值。进行修改时，还要考虑变量可修改的范围，不是所有的变量都能在全局/会话范围内进行修改。具体的可修改范围参考 [MySQL 动态变量文档](https://dev.mysql.com/doc/refman/5.7/en/dynamic-system-variables.html)。 - -### 全局范围值 - -* 在变量名前加 `GLOBAL` 关键词或者是使用 `@@global.` 作为修饰符: - - ```sql - SET GLOBAL autocommit = 1; - SET @@global.autocommit = 1; - ``` - -> **注意：** -> -> 在分布式 TiDB 中，`GLOBAL` 变量的设置会持久化到存储层中，单个 TiDB 实例每 2 秒会主动进行一次全变量的获取并形成 `gvc` (global variables cache) 缓存，该缓存有效时间最多可持续 2 秒。在设置 `GLOBAL` 变量之后，为了保证新会话的有效性，请确保两个操作之间的间隔大于 2 秒。相关细节可以查看 [Issue #14531](https://github.com/pingcap/tidb/issues/14531)。 - -### 会话范围值 - -* 在变量名前加 `SESSION` 关键词或者是使用 `@@session.` 作为修饰符，或者是不加任何修饰符: - - ```sql - SET SESSION autocommit = 1; - SET @@session.autocommit = 1; - SET @@autocommit = 1; - ``` - -* `LOCAL` 以及 `@@local.` 是 `SESSION` 以及 `@@session.` 的同义词 - -### 系统变量的作用机制 - -* 会话范围的系统变量仅仅会在创建会话时才会根据全局范围系统变量初始化自己的值。更改全局范围的系统变量不会改变已经创建的会话正在使用的系统变量的值。 - - ```sql - mysql> SELECT @@GLOBAL.autocommit; - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | ON | - +---------------------+ - 1 row in set (0.00 sec) - - mysql> SELECT @@SESSION.autocommit; - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - - mysql> SET GLOBAL autocommit = OFF; - Query OK, 0 rows affected (0.01 sec) - - mysql> SELECT @@SESSION.autocommit; -- 会话范围的系统变量不会改变，会话中执行的事务依旧是以自动提交的形式来进行。 - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - - mysql> SELECT @@GLOBAL.autocommit; - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | OFF | - +---------------------+ - 1 row in set (0.00 sec) - - mysql> exit - Bye - $ mysql -h127.0.0.1 -P4000 -uroot -D test - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 3 - Server version: 5.7.25-TiDB-None MySQL Community Server (Apache License 2.0) - - Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. - - Oracle is a registered trademark of Oracle Corporation and/or its - affiliates. Other names may be trademarks of their respective - owners. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - mysql> SELECT @@SESSION.autocommit; -- 新建的会话会使用新的全局变量。 - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | OFF | - +----------------------+ - 1 row in set (0.00 sec) - ``` - -## TiDB 支持的 MySQL 系统变量 - -下列系统变量是 TiDB 真正支持并且行为和 MySQL 一致： - -| 变量名 | 作用域 | 说明 | -| ---------------- | -------- | -------------------------------------------------- | -| autocommit | GLOBAL \| SESSION | 是否自动 Commit 事务 | -| sql_mode | GLOBAL \| SESSION | 支持部分 MySQL SQL mode，| -| time_zone | GLOBAL \| SESSION | 数据库所使用的时区 | -| tx_isolation | GLOBAL \| SESSION | 事务隔离级别 | -| max\_execution\_time | GLOBAL \| SESSION | 语句超时时间，单位为毫秒 | - -> **注意：** -> -> `max_execution_time` 目前对所有类型的 `statement` 生效，并非只对 `SELECT` 语句生效。实际精度在 100ms 级别，而非更准确的毫秒级别。 - -## TiDB 特有的系统变量 - -参见 [TiDB 专用系统变量](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md b/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md deleted file mode 100644 index cdbaf3c5643c..000000000000 --- a/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md +++ /dev/null @@ -1,429 +0,0 @@ ---- -title: TiDB 专用系统变量和语法 -category: reference ---- - -# TiDB 专用系统变量和语法 - -TiDB 在 MySQL 的基础上，定义了一些专用的系统变量和语法用来优化性能。 - -## 系统变量 - -变量可以通过 SET 语句设置，例如 - -``` -set @@tidb_distsql_scan_concurrency = 10 -``` - -如果需要设值全局变量，执行 - -``` -set @@global.tidb_distsql_scan_concurrency = 10 -``` - -### tidb_snapshot - -作用域：SESSION - -默认值：空字符串 - -这个变量用来设置当前会话期待读取的历史数据所处时刻。比如当设置为 "2017-11-11 20:20:20" 时或者一个 TSO 数字 "400036290571534337"，当前会话将能读取到该时刻的数据。 - -### tidb_import_data - -作用域：SESSION - -默认值：0 - -这个变量用来表示当前状态是否为从 dump 文件中导入数据。 -当这个变量被设置为 1 时，唯一索引约束不被检查以加速导入速度。 -这个变量不对外用，只是给 lightning 使用，请用户不要自行修改。 - -### tidb_opt_agg_push_down - -作用域：SESSION - -默认值：0 - -这个变量用来设置优化器是否执行聚合函数下推到 Join 之前的优化操作。 -当查询中聚合操作执行很慢时，可以尝试设置该变量为 1。 - -### tidb_opt_insubquery_unfold - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来设置优化器是否执行 `in-` 子查询展开的优化操作。 - -### tidb_build_stats_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ANALYZE 语句执行时并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_checksum_table_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ADMIN CHECKSUM TABLE 语句执行时扫描索引的并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_current_ts - -作用域：SESSION - -默认值：0 - -这个变量是一个只读变量，用来获取当前事务的时间戳。 - -### tidb_config - -作用域：SESSION - -默认值：空字符串 - -这个变量是一个只读变量，用来获取当前 TiDB Server 的配置信息。 - -### tidb_distsql_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：15 - -这个变量用来设置 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 -对于 AP 类应用，最大值建议不要超过所有 TiKV 节点的 CPU 核数。 - -### tidb_index_lookup_size - -作用域：SESSION | GLOBAL - -默认值：20000 - -这个变量用来设置 index lookup 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup join 算法的并发度。 - -### tidb_hash_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：5 - -这个变量用来设置 hash join 算法的并发度。 - -### tidb_index_serial_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来设置顺序 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_projection_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 Projection 算子的并发度。 - -### tidb_hashagg_partial_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 partial 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_hashagg_final_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 final 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_index_join_batch_size - -作用域：SESSION | GLOBAL - -默认值：25000 - -这个变量用来设置 index lookup join 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_skip_utf8_check - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来设置是否跳过 UTF-8 字符的验证。 -验证 UTF-8 字符需要消耗一定的性能，当可以确认输入的字符串为有效的 UTF-8 字符时，可以将其设置为 1。 - -### tidb_max_chunk_size - -作用域：SESSION | GLOBAL - -默认值：1024 - -这个变量用来设置执行过程中一个 chunk 最大的行数。 - -### tidb_mem_quota_query - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置一条查询语句的内存使用阈值。 -如果一条查询语句执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_hashjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 HashJoin 算子的内存使用阈值。 -如果 HashJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_mergejoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 MergeJoin 算子的内存使用阈值。 -如果 MergeJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_sort - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 Sort 算子的内存使用阈值。 -如果 Sort 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_topn - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 TopN 算子的内存使用阈值。 -如果 TopN 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupreader - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupReader 算子的内存使用阈值。 - -如果 IndexLookupReader 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupJoin 算子的内存使用阈值。 -如果 IndexLookupJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_nestedloopapply - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 NestedLoopApply 算子的内存使用阈值。 -如果 NestedLoopApply 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_general_log - -作用域：SERVER - -默认值：0 - -这个变量用来设置是否在日志里记录所有的 SQL 语句。 - -### tidb_enable_streaming - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否启用 Streaming。 - -### tidb_retry_limit - -作用域：SESSION | GLOBAL - -默认值：10 - -这个变量用来设置最大重试次数。一个事务执行中遇到可重试的错误（例如事务冲突、事务提交过慢或表结构变更）时，会根据该变量的设置进行重试。注意当 `tidb_retry_limit = 0` 时，也会禁用自动重试。 - -### tidb_disable_txn_auto_retry - -作用域：SESSION | GLOBAL - -默认值：off - -这个变量用来设置是否禁用显式事务自动重试，设置为 `on` 时，不会自动重试，如果遇到事务冲突需要在应用层重试。TiDB v2.1 默认开启自动重试。 - -如果将该变量的值设为 `off`，TiDB 将会自动重试事务，这样在事务提交时遇到的错误更少。需要注意的是，这样可能会导致数据更新丢失。 - -这个变量不会影响自动提交的隐式事务和 TiDB 内部执行的事务，它们依旧会根据 `tidb_retry_limit` 的值来决定最大重试次数。 - -是否需要禁用自动重试，请参考[重试的局限性](/v2.1/reference/transactions/transaction-optimistic.md#重试的局限性)。 - -### tidb_backoff_weight - -作用域：SESSION | GLOBAL - -默认值：2 - -这个变量用来给 TiDB 的 `backoff` 最大时间增加权重，即内部遇到网络或其他组件（TiKV、PD）故障等时，发送重试请求的最大重试时间。可以通过这个变量来调整最大重试时间，最小值为 1。 - -例如，TiDB 向 PD 取 TSO 的基础超时时间是 15 秒，当 `tidb_backoff_weight = 2` 时，取 TSO 的最大超时时间为：基础时间 * 2 等于 30 秒。 - -在网络环境较差的情况下，适当增大该变量值可以有效缓解因为超时而向应用端报错的情况；而如果应用端希望更快地接到报错信息，则应该尽量减小该变量的值。 - -### tidb_enable_table_partition - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否开启 TABLE PARTITION 特性。 - -### tidb_backoff_lock_fast - -作用域：SESSION | GLOBAL - -默认值：100 - -这个变量用来设置读请求遇到锁的 backoff 时间。 - -### tidb_ddl_reorg_worker_cnt - -作用域：GLOBAL - -默认值：16 - -这个变量用来设置 DDL 操作 re-organize 阶段的并发度。 - -### tidb_ddl_reorg_batch_size - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置 DDL 操作 re-organize 阶段的 batch size。比如 Add Index 操作，需要回填索引数据，通过并发 tidb_ddl_reorg_worker_cnt 个 worker 一起回填数据，每个 worker 以 batch 为单位进行回填。如果 Add Index 时有较多 Update 操作或者 Replace 等更新操作，batch size 越大，事务冲突的概率也会越大，此时建议调小 batch size 的值，最小值是 32。在没有事务冲突的情况下，batch size 可设为较大值，最大值是 10240，这样回填数据的速度更快，但是 TiKV 的写入压力也会变大。 - -### tidb_ddl_reorg_priority - -作用域：SESSION | GLOBAL - -默认值：PRIORITY_LOW - -这个变量用来设置 `ADD INDEX` 操作 re-organize 阶段的执行优先级，可设置为 PRIORITY_LOW/PRIORITY_NORMAL/PRIORITY_HIGH。 - -### tidb_max_delta_schema_count - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置缓存 schema 版本信息（对应版本修改的相关 table IDs）的个数限制，可设置的范围 100 - 16384。此变量在 2.1.18 及之后版本支持。 - -### tidb_force_priority - -作用域：SESSION - -默认值：`NO_PRIORITY` - -这个变量用于改变 TiDB server 上执行的语句的默认优先级。例如，你可以通过设置该变量来确保正在执行 OLAP 查询的用户优先级低于正在执行 OLTP 查询的用户。 - -可设置为 `NO_PRIORITY`、`LOW_PRIORITY`、`DELAYED` 或 `HIGH_PRIORITY`。 - -### SHARD_ROW_ID_BITS - -对于 PK 非整数或没有 PK 的表，TiDB 会使用一个隐式的自增 rowid，大量 `INSERT` 时会把数据集中写入单个 Region，造成写入热点。 - -通过设置 `SHARD_ROW_ID_BITS`，可以把 rowid 打散写入多个不同的 Region，缓解写入热点问题。但是设置的过大会造成 RPC 请求数放大，增加 CPU 和网络开销。 - -- `SHARD_ROW_ID_BITS = 4` 表示 16 个分片 -- `SHARD_ROW_ID_BITS = 6` 表示 64 个分片 -- `SHARD_ROW_ID_BITS = 0` 表示默认值 1 个分片 - -语句示例： - -- `CREATE TABLE`：`CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` -- `ALTER TABLE`：`ALTER TABLE t SHARD_ROW_ID_BITS = 4;` - -### tidb_slow_log_threshold - -作用域：SESSION - -默认值：300 - -输出慢日志的耗时阈值。当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。默认为 300ms。 - -示例： - -```sql -set tidb_slow_log_threshold = 200 -``` - -### tidb_query_log_max_len - -作用域：SESSION - -默认值：2048 (bytes) - -最长的 SQL 输出长度。当语句的长度大于 query-log-max-len，将会被截断输出。 - -示例： - -```sql -set tidb_query_log_max_len = 20 -``` - -### tidb_scatter_region - -作用域：GLOBAL - -默认值：0 - -TiDB 默认会在建表时为新表分裂 Region。开启该变量后，会在建表语句执行时，同步打散刚分裂出的 Region。适用于批量建表后紧接着批量写入数据，能让刚分裂出的 Region 先在 TiKV 分散而不用等待 PD 进行调度。为了保证后续批量写入数据的稳定性，建表语句会等待打散 Region 完成后再返回建表成功，建表语句执行时间会是关闭该变量的数倍。 - -### tidb_allow_remove_auto_inc 从 v2.1.18 版本开始引入 - -作用域：SESSION - -默认值：0 - -这个变量用来控制是否允许通过 `ALTER TABLE MODIFY` 或 `ALTER TABLE CHANGE` 来移除某个列的 `AUTO_INCREMENT` 属性。默认为不允许。 diff --git a/v2.1/reference/configuration/tikv-server/configuration.md b/v2.1/reference/configuration/tikv-server/configuration.md deleted file mode 100644 index df545c42883e..000000000000 --- a/v2.1/reference/configuration/tikv-server/configuration.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiKV 配置参数 -category: reference ---- - -# TiKV 配置参数 - -TiKV 的命令行参数支持一些可读性好的单位转换。 - -+ 文件大小（以 bytes 为单位）：KB, MB, GB, TB, PB（也可以全小写） -+ 时间（以毫秒为单位）：ms, s, m, h - -## `-A, --addr` - -+ TiKV 监听地址 -+ 默认："127.0.0.1:20160" -+ 如果部署一个集群，\-\-addr 必须指定当前主机的 IP 地址，例如 "192.168.100.113:20160"，如果是运行在 docker 则需要指定为 "0.0.0.0:20160" - -## `--advertise-addr` - -+ TiKV 对外访问地址。 -+ 默认：${addr} -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，客户端并不能通过 TiKV 自己监听的地址来访问到 TiKV，这时候，你就可以设置 advertise addr 来让 客户端访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 -p 20160:20160，那么可以设置为 \-\-advertise-addr="192.168.100.113:20160"，客户端可以通过 192.168.100.113:20160 来找到这个服务 - -## `-C, --config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiKV 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，TiKV 就会使用命令行参数的配置来覆盖配置文件里面的 - -## `--capacity` - -+ TiKV 存储数据的容量 -+ 默认：0 (无限) -+ PD 需要使用这个值来对整个集群做 balance 操作。（提示：你可以使用 10GB 来替代 10737418240，从而简化参数的传递） - -## `--data-dir` - -+ TiKV 数据存储路径 -+ 默认："/tmp/tikv/store" - -## `-L, --log` - -+ Log 级别 -+ 默认："info" -+ 我们能选择 trace, debug, info, warn, error, 或者 off - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果没设置这个参数，log 会默认输出到 "stderr"，如果设置了，log 就会输出到对应的文件里面，在每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--pd` - -+ PD 地址列表。 -+ 默认："" -+ TiKV 必须使用这个值连接 PD，才能正常工作。使用逗号来分隔多个 PD 地址，例如： - 192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379 diff --git a/v2.1/reference/error-codes.md b/v2.1/reference/error-codes.md deleted file mode 100644 index 1305775e7e6b..000000000000 --- a/v2.1/reference/error-codes.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 错误码与故障诊断 -category: reference ---- - -# 错误码与故障诊断 - -本篇文档描述在使用 TiDB 过程中会遇到的问题以及解决方法。 - -## 错误码 - -TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样的错误码。另外还有一些特有的错误码： - -| 错误码 | 说明 | -| --------------------- | -------------------------------------------------- | -| 8001 | 请求使用的内存超过 TiDB 内存使用的阈值限制 | -| 8002 | 带有 `SELECT FOR UPDATE` 语句的事务，在遇到写入冲突时，为保证一致性无法进行重试，事务将进行回滚并返回该错误 | -| 8003 | `ADMIN CHECK TABLE` 命令在遇到行数据跟索引不一致的时候返回该错误 | -| 8004 | 单个事务过大，原因及解决方法请参考[这里](/v2.1/faq/tidb.md#433-transaction-too-large-是什么原因怎么解决) | -| 8005 | 事务在 TiDB 中遇到了写入冲突，原因及解决方法请参考[这里](/v2.1/faq/tidb.md#九故障排除) | -| 9001 | 请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络 | -| 9002 | 请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络 | -| 9003 | TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志 | -| 9004 | 当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码 | -| 9005 | 某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志 | -| 9006 | GC Life Time 间隔时间过短，长事务本应读到的数据可能被清理了，应增加 GC Life Time | -| 9007 | 事务在 TiKV 中遇到了写入冲突，原因及解决方法请参考[这里](/v2.1/faq/tidb.md#九故障排除) | - -## 故障诊断 - -参见[故障诊断文档](/v2.1/how-to/troubleshoot/cluster-setup.md)以及 [FAQ](/v2.1/faq/tidb.md)。 diff --git a/v2.1/reference/garbage-collection.md b/v2.1/reference/garbage-collection.md deleted file mode 100644 index db569a839d26..000000000000 --- a/v2.1/reference/garbage-collection.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: TiDB 垃圾回收 (GC) -category: reference ---- - -# TiDB 垃圾回收 (GC) - -TiDB 采用 MVCC 的方式来进行并发控制。当对数据进行更新或者删除时，原有的数据不会被立刻删除，而是会被保留一段时间，并且在这段时间内这些旧数据仍然可以被读取。这使得写入操作和读取操作不必互斥，并使读取历史数据成为可能。 - -存在超过一定时间并且不再使用的版本会被清理，否则它们将始终占用硬盘空间，并对性能产生负面影响。TiDB 使用一个垃圾回收 (GC) 机制来清理这些旧数据。 - -## 工作方式 - -TiDB 会周期性地进行 GC。每个 TiDB Server 启动后都会在后台运行一个 gc_worker，每个集群中会有其中一个 gc_worker 被选为 leader，leader 负责维护 GC 的状态并向所有的 TiKV Region leader 发送 GC 命令。 - -## 配置与监测方法 - -GC 相关的配置和运行状态记录在 `mysql.tidb` 这张系统表中，可以通过 SQL 语句进行检测和配置： - -```sql -mysql> select VARIABLE_NAME, VARIABLE_VALUE from mysql.tidb; -+-----------------------+------------------------------------------------------------------------------------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+-----------------------+------------------------------------------------------------------------------------------------+ -| bootstrapped | True | -| tidb_server_version | 18 | -| tikv_gc_leader_uuid | 58accebfa7c0004 | -| tikv_gc_leader_desc | host:ip-172-16-30-5, pid:95472, start at 2018-04-11 13:43:30.73076656 +0800 CST m=+0.068873865 | -| tikv_gc_leader_lease | 20180418-11:02:30 +0800 CST | -| tikv_gc_run_interval | 10m0s | -| tikv_gc_life_time | 10m0s | -| tikv_gc_last_run_time | 20180418-10:59:30 +0800 CST | -| tikv_gc_safe_point | 20180418-10:58:30 +0800 CST | -| tikv_gc_concurrency | 1 | -+-----------------------+------------------------------------------------------------------------------------------------+ -10 rows in set (0.02 sec) -``` - -其中，`tikv_gc_run_interval`，`tikv_gc_life_time`，`tikv_gc_concurrency` 这三条记录可以手动配置。其余带有 `tikv_gc` 前缀的记录为当前运行状态的记录， TiDB 会自动更新这些记录，请勿手动修改。 - -`tikv_gc_run_interval` 是 GC 运行时间间隔。`tikv_gc_life_time` 是历史版本的保留时间，每次进行 GC 时，会清理超过该时间的历史数据。这两项配置不应低于 10 分钟，默认值均为 10 分钟。可以直接用 SQL 修改其数值来进行配置。比如，如果想保留一天以内的历史数据，就可以执行： - -```sql -update mysql.tidb set VARIABLE_VALUE = '24h' where VARIABLE_NAME = 'tikv_gc_life_time'; -``` - -时长字符串的形式是数字后接时间单位的序列，如 `24h`、`2h30m`、`2.5h`。可以使用的时间单位包括 "h"、"m"、"s"。 - -> **注意：** -> -> 在数据更新频繁的场景下如果将 `tikv_gc_life_time` 设置得比较大（如数天甚至数月），可能会有一些潜在的问题： -> -> * 随着版本的不断增多，数据占用的磁盘空间会随之增加。 -> * 大量的历史版本会在一定程度上导致查询变慢，主要影响范围查询（如 `select count(*) from t`）。 -> * 如果在运行中突然将 `tikv_gc_life_time` 配置调小，可能会导致短时间内大量历史数据被删除，造成 I/O 负担。 - -`tikv_gc_concurrency` 是运行 GC 的并发数。默认该选项为 1，即单线程运行，逐个向每个涉及的 Region 发起请求并等待响应。可以增加该数值以改善性能，最大不能超过 128。 - -`tikv_gc_leader_uuid`，`tikv_gc_leader_desc`，`tikv_gc_leader_lease` 是当前的 GC leader 的信息。`tikv_gc_last_run_time` 是上一次执行 GC 的时间。 - -`tikv_gc_safe_point` 的含义是，在该时间点以前的版本已经被 GC 清理，并保证该时间点以后的读取可以正确进行。 - -## 实现细节 - -GC 的实施过程实际上比较复杂。我们要在保证一致性不被破坏的前提下，清除不再使用的数据。具体来说，每次执行 GC，要顺序执行三个步骤： - -### 1. Resolve Locks - -TiDB 的事务是基于 Google Percolator 模型实现的，事务的提交是一个两阶段提交的过程。第一阶段完成时，所有涉及的 key 会加上一个锁，其中一个锁会被设定为 Primary，其余的锁（Secondary）则会指向 Primary；第二阶段会将 Primary 锁所在的 key 加上一个 Write 记录，并去除锁。这里的 Write 记录就是历史上对该 key 进行写入或删除，或者该 key 上发生事务回滚的记录。Primary 锁被替换为何种 Write 记录标志着该事务提交成功与否。接下来，所有 Secondary 锁也会被依次替换。如果替换这些 Secondary 锁的线程死掉了，锁就残留了下来。在 GC 过程中如果遇到了时间戳在 safe point 之前的这样的锁，就会根据该事务提交与否，将该锁也替换成 Write 记录。 - -这一步是必须的，因为如果其 Primary 的 Write 记录被 GC 清除掉了，就再也无法知道该事务是否成功，也就难以保证一致性。 - -### 2. Delete Ranges - -DeleteRanges 通常在 drop table 这样的操作之后需要进行，用于删除可能很大的一个区间。如果 TiKV 的 `use_delete_range` 选项没有打开，那么 TiKV 会把范围中的 key 逐个删除。 - -### 3. Do GC - -这一步把每一个 key 的 safe point 之前的数据和 Write 记录清除掉。有一个特例是，如果在 safe point 之前的所有 `Put` 类型和 `Delete` 类型的 Write 记录中，最后一个记录是 `Put`（即写入），那么该记录（及其对应的数据）不能被直接删除。否则，时间戳在 safe point 之后、该 key 的下一个版本之前的读取操作将无法读取到该数据。 diff --git a/v2.1/reference/key-monitoring-metrics/overview-dashboard.md b/v2.1/reference/key-monitoring-metrics/overview-dashboard.md deleted file mode 100644 index f3deac53279d..000000000000 --- a/v2.1/reference/key-monitoring-metrics/overview-dashboard.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Overview 面板重要监控指标详解 -category: reference ---- - -# Overview 面板重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v2.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们单独挑选出重要的 Metrics 放在 Overview 页面，方便日常运维人员观察集群组件 (PD, TiDB, TiKV) 使用状态以及集群使用状态。 - -以下为 Overview Dashboard 监控说明： - -## Services Port Status - -- Services Online：各服务在线节点数量 -- Services Offline：各服务 Down 掉节点数量 - -## PD - -- Storage Capacity：TiDB 集群总可用数据库空间大小 -- Current Storage Size：TiDB 集群目前已用数据库空间大小 -- Number of Regions：当前集群的 Region 总量 -- Leader Balance Ratio：Leader 数量最多和最少节点相差的百分比，一般小于 5%，节点重启时会有比较大的波动 -- Region Balance Ratio：Region 数量最多和最少节点相差的百分比，一般小于 5%，新增/下线节点时相差比较大 -- Store Status：集群 TiKV 节点的状态 - - Up Stores：正常运行的 TiKV 节点数量 - - Disconnect Stores：短时间内通信异常的 TiKV 节点数量 - - LowSpace Stores：剩余可用空间小于 20% 的 TiKV 节点数量 - - Down Stores：停止工作的 TiKV 节点数量，如果大于 0，说明有节点不正常 - - Offline Stores：正在下线的 TiKV 节点数量（正在下线的 TiKV 节点还在提供服务） - - Tombstone Stores：下线成功的 TiKV 节点数量 -- 99% completed\_cmds\_duration\_seconds：单位时间内，99% 的 pd-server 请求执行时间小于监控曲线的值，一般 <= 5ms -- handle\_requests\_duration\_seconds：PD 发送请求的网络耗时 - -## TiDB - -- Statement OPS：SQL 执行数量统计（包含 select、insert、update 等） -- Duration：SQL 执行的时间 -- QPS By Instance：每个 TiDB 上的 QPS -- Failed Query OPM：失败 SQL 的统计，例如语法错误、主键冲突等 -- Connection count：每个 TiDB 的连接数 -- Heap Memory Usage：每个 TiDB 使用的堆内存大小 -- Transaction OPS：事务执行数量统计 -- Transaction Duration：事务执行的时间 -- KV Cmd OPS：KV 命令执行数量统计 -- KV Cmd Duration 99：KV 命令执行的时间 -- PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 -- PD TSO Wait Duration：TiDB 从 PD 获取 TS 的时间 -- TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 -- Lock Resolve OPS：事务冲突相关的数量 -- Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 -- KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - -## TiKV - -- leader：各个 TiKV 节点上 Leader 的数量分布 -- region：各个 TiKV 节点上 Region 的数量分布 -- CPU：各个 TiKV 节点的 CPU 使用率 -- Memory：各个 TiKV 节点的内存使用量 -- store size：各个 TiKV 节点存储的数据量 -- cf size：集群不同 CF 存储的数据量 -- channel full：正常情况显示 No data，如果有了监控值，说明对应 TiKV 节点的消息处理不过来了 -- server report failures：正常情况显示 No data，如果出现了 Unreachable，说明 TiKV 之间通信有问题 -- scheduler pending commands：写入堆积的数量，偶尔出现峰值属于正常现象 -- coprocessor pending requests：正常情况监控为 0 或者数量很少 -- coprocessor executor count：不同类型的查询操作数量 -- coprocessor request duration：TiKV 中查询消耗的时间 -- raft store CPU：raftstore 线程的 CPU 使用率，目前为单线程，超过 80% 说明使用率很高 -- Coprocessor CPU：TiKV 查询线程的 CPU 使用率，和业务相关，复杂查询会使用大量的 CPU 资源 - -## System Info - -- Vcores：CPU 核心数量 -- Memory：内存总大小 -- CPU Usage：CPU 使用率，最大为 100% -- Load [1m]：1 分钟的负载情况 -- Memory Available：剩余内存大小 -- Network Traffic：网卡流量统计 -- TCP Retrans：网络监控，TCP 相关信息统计 -- IO Util：磁盘使用率，最高为 100%，一般到 80% - 90% 就需要考虑加节点 - -## 图例 - -![overview](/media/overview.png) diff --git a/v2.1/reference/key-monitoring-metrics/pd-dashboard.md b/v2.1/reference/key-monitoring-metrics/pd-dashboard.md deleted file mode 100644 index b4ad9981a51f..000000000000 --- a/v2.1/reference/key-monitoring-metrics/pd-dashboard.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: PD 重要监控指标详解 -category: reference ---- - -# PD 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v2.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 PD 面板上的 Metrics，可以了解 PD 当前的状态。 - -以下为 PD Dashboard 监控说明： - -## Cluster - -- PD role：当前 PD 的角色 -- Storage capacity：TiDB 集群总可用数据库空间大小 -- Current storage size：TiDB 集群目前已用数据库空间大小 -- Number of Regions：当前集群的 Region 总量 -- Leader balance ratio：Leader 数量最多和最少节点相差的百分比，一般小于 5%，节点重启时会有比较大的波动 -- Region balance ratio：Region 数量最多和最少节点相差的百分比，一般小于 5%，新增/下线节点时相差比较大 -- Normal stores：处于正常状态的节点数目 -- Abnormal stores：处于异常状态的节点数目，正常情况应当为 0 -- Current storage usage：TiDB 集群存储空间的使用率 -- Current peer count：当前集群 peer 的总量 -- Metadata information：记录集群 ID，时间戳和生成的 ID -- Region label isolation level：不同 label 所在的 level 的 Region 数量 -- Region health：每个 Region 的状态，通常情况下，pending 的 peer 应该少于 100，miss 的 peer 不能一直大于 0 - -![PD Dashboard - Cluster metrics](/media/pd-dashboard-cluster.png) - -## Balance - -- Store capacity：每个 TiKV 实例的总的空间大小 -- Store available：每个 TiKV 实例的可用空间大小 -- Store used：每个 TiKV 实例的已使用空间大小 -- Size amplification：每个 TiKV 实例的空间放大比率 -- Size available ratio：每个 TiKV 实例的可用空间比率 -- Store leader score：每个 TiKV 实例的 leader 分数 -- Store Region score：每个 TiKV 实例的 Region 分数 -- Store leader size：每个 TiKV 实例上所有 leader 的大小 -- Store Region size：每个 TiKV 实例上所有 Region 的大小 -- Store leader count：每个 TiKV 实例上所有 leader 的数量 -- Store Region count：每个 TiKV 实例上所有 Region 的数量 - -![PD Dashboard - Balance metrics](/media/pd-dashboard-balance.png) - -## HotRegion - -- Hot write Region's leader distribution：每个 TiKV 实例上是写入热点的 leader 的数量 -- Hot write Region's peer distribution：每个 TiKV 实例上是写入热点的 peer 的数量 -- Hot write Region's leader written bytes：每个 TiKV 实例上热点的 leader 的写入大小 -- Hot write Region's peer written bytes：每个 TiKV 实例上热点的 peer 的写入大小 -- Hot read Region's leader distribution：每个 TiKV 实例上是读取热点的 leader 的数量 -- Hot read Region's peer distribution：每个 TiKV 实例上是读取热点的 peer 的数量 -- Hot read Region's leader read bytes：每个 TiKV 实例上热点的 leader 的读取大小 -- Hot read Region's peer read bytes：每个 TiKV 实例上热点的 peer 的读取大小 - -![PD Dashboard - HotRegion metrics](/media/pd-dashboard-hot-region.png) - -## Scheduler - -- Scheduler is running：所有正在运行的 scheduler -- Balance leader movement：leader 移动的详细情况 -- Balance Region movement：Region 移动的详细情况 -- Balance leader event：balance leader 的事件数量 -- Balance Region event：balance Region 的事件数量 -- Balance leader scheduler：balance-leader scheduler 的状态 -- Balance Region scheduler：balance-region scheduler 的状态 -- Namespace checker：namespace checker 的状态 -- Replica checker：replica checker 的状态 -- Region merge checker：merge checker 的状态 - -![PD Dashboard - Scheduler metrics](/media/pd-dashboard-scheduler.png) - -## Operator - -- Schedule operator create：新创建的不同 operator 的数量 -- Schedule operator check：已检查的 operator 的数量，主要检查是否当前步骤已经执行完成，如果是，则执行下一个步骤 -- Schedule operator finish：已完成的 operator 的数量 -- Schedule operator timeout：已超时的 operator 的数量 -- Schedule operator replaced or canceled：已取消或者被替换的 operator 的数量 -- Schedule operators count by state：不同状态的 operator 的数量 -- 99% Operator finish duration：已完成的 operator 中，99% 所需花费的时间 -- 50% Operator finish duration：已完成的 operator 中，50% 所需花费的时间 -- 99% Operator step duration：已完成的 operator 的步骤中，99% 所需花费的时间 -- 50% Operator step duration：已完成的 operator 的步骤中，50% 所需花费的时间 - -![PD Dashboard - Operator metrics](/media/pd-dashboard-operator.png) - -## gRPC - -- Completed commands rate：gRPC 命令的完成速率 -- 99% Completed commands duration：99% 的情况下，命令的完成时间 - -![PD Dashboard - gRPC metrics](/media/pd-dashboard-grpc.png) - -## etcd - -- Handle transactions count：etcd 的事务个数 -- 99% Handle transactions duration：99% 的情况下，处理 etcd 事务所需花费的时间 -- 99% WAL fsync duration：99% 的情况下，持久化 WAL 所需花费的时间，这个值通常应该小于 1s -- 99% Peer round trip time seconds：99% 的情况下，etcd 的网络延时，这个值通常应该小于 1s -- etcd disk WAL fsync rate：etcd 持久化 WAL 的速率 -- Raft term：当前 Raft 的 term -- Raft committed index：最后一次 commit 的 Raft index -- Raft applied index：最后一次 apply 的 Raft index - -![PD Dashboard - etcd metrics](/media/pd-dashboard-etcd.png) - -## TiDB - -- Handle requests count：TiDB 的请求数量 -- Handle requests duration：每个请求所花费的时间，99% 的情况下，应该小于 100ms - -![PD Dashboard - TiDB metrics](/media/pd-dashboard-tidb.png) - -## Heartbeat - -- Region heartbeat report：TiKV 向 PD 发送的心跳个数 -- Region heartbeat report error：TiKV 向 PD 发送的异常的心跳个数 -- Region heartbeat report active：TiKV 向 PD 发送的正常的心跳个数 -- Region schedule push：PD 向 TiKV 发送的调度命令的个数 -- 99% Region heartbeat latency：99% 的情况下，心跳的延迟 - -![PD Dashboard - Heartbeat metrics](/media/pd-dashboard-heartbeat.png) \ No newline at end of file diff --git a/v2.1/reference/key-monitoring-metrics/tidb-dashboard.md b/v2.1/reference/key-monitoring-metrics/tidb-dashboard.md deleted file mode 100644 index 6f5695ea2822..000000000000 --- a/v2.1/reference/key-monitoring-metrics/tidb-dashboard.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: TiDB 重要监控指标详解 -category: reference ---- - -# TiDB 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v2.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -以下为 TiDB Dashboard 部分监控说明： - -## 说明 - -- Query Summary - - Duration：SQL 执行的时间 - - Statement OPS：SQL 执行数量统计（包含 `SELECT`、`INSERT`、`UPDATE` 等） - - QPS By Instance：每个 TiDB 上的 QPS - -- Query Detail - - Internal SQL OPS：TiDB 内部 SQL 语句执行数量统计 - -- Server - - Connection count：每个 TiDB 的连接数 - - Failed Query OPM：失败 SQL 的统计，例如语法错误、主键冲突等 - - Heap Memory Usage：每个 TiDB 使用的堆内存大小 - - Events OPM：统计关键事件，例如 start，close，graceful-shutdown，kill，hang 等 - - Uncommon Error OPM：TiDB 非正常错误的统计，包括 panic，binlog 写失败等 - -- Transaction - - Transaction OPS：事务执行数量统计 - - Transaction Duration：事务执行的时间 - - Session Retry Error OPS：事务重试时遇到的错误数量 - -- Executor - - Expensive Executor OPS：消耗系统资源比较多的算子统计，包括 Merge Join，Hash Join，Index Look Up Join，Hash Agg，Stream Agg，Sort，TopN 等 - - Queries Using Plan Cache OPS：使用 Plan Cache 的查询数量统计 - -- Distsql - - Distsql Duration：Distsql 处理的时长 - - Distsql QPS：Distsql 的数量统计 - -- KV Errors - - KV Retry Duration：KV 重试请求的时间 - - TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 - - KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - - Lock Resolve OPS：事务冲突相关的数量 - - Other Errors OPS：其他类型的错误数量，包括清锁和更新 SafePoint - -- KV Duration - - KV Cmd Duration 99：KV 命令执行的时间 - -- KV Count - - KV Cmd OPS：KV 命令执行数量统计 - - Txn OPS：启动事务的数量统计 - - Load SafePoint OPS：更新 SafePoint 的数量统计 - -- PD Client - - PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 - - PD TSO Wait Duration：TiDB 从 PD 获取 TSO 的时间 - - PD Client CMD OPS：PD Client 执行命令数量统计 - - PD Client CMD Duration: PD Client 执行命令耗时 - - PD Client CMD Fail OPS：PD Client 执行命令失败统计 - -- Schema Load - - Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 - - Load Schema OPS：TiDB 从 TiKV 获取 Schema 的数量统计 - - Schema Lease Error OPM：Schema Lease 出错，包括 change 和 outdate 两种，出现 outdate 错误时会报警 - -- DDL - - DDL Duration 95：DDL 语句处理时间统计 - - DDL Batch Add Index Duration 100：创建索引时每个 Batch 所花费的时间统计 - - DDL Deploy Syncer Duration：Schema Version Syncer 初始化，重启，清空等操作耗时 - - Owner Handle Syncer Duration：DDL Owner 在执行更新，获取以及检查 Schema Version 的耗时 - - Update Self Version Duration：Schema Version Syncer 更新版本信息耗时 - -- Statistics - - Auto Analyze Duration 95：自动 ANALYZE 耗时统计 - - Auto Analyze QPS：自动 ANALYZE 数量统计 - - Stats Inaccuracy Rate：统计信息不准确度统计 - - Pseudo Estimation OPS：使用假的统计信息优化 SQL 的数量统计 - - Dump Feedback OPS：存储统计信息 Feedback 的数量统计 - - Update Stats OPS：利用 Feedback 更新统计信息的数量统计 - -- Meta - - AutoID QPS：AutoID 相关操作的数量统计，包括全局 ID 分配、单个 Table AutoID 分配、单个 Table AutoID Rebase 三种操作 - - AutoID Duration：AutoID 相关操作的耗时 - -- GC - - Worker Action OPM：GC 相关操作的数量统计，包括 run\_job，resolve\_lock，delete\_range 等操作 - - Duration 99：GC 相关操作的耗时统计 - - GC Failure OPM：GC 相关操作失败数量统计 - - Too Many Locks Error OPM：GC 清锁过多错误的数量统计 diff --git a/v2.1/reference/key-monitoring-metrics/tikv-dashboard.md b/v2.1/reference/key-monitoring-metrics/tikv-dashboard.md deleted file mode 100644 index 184206685824..000000000000 --- a/v2.1/reference/key-monitoring-metrics/tikv-dashboard.md +++ /dev/null @@ -1,429 +0,0 @@ ---- -title: TiKV 重要监控指标详解 -category: reference ---- - -# TiKV 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v2.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 TiKV 面板上的 Metrics，可以了解 TiKV 当前的状态。 - -以下为 TiKV Dashboard 监控说明： - -## Cluster - -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Available size：每个 TiKV 实例的可用的存储空间的大小 -- Capacity size：每个 TiKV 实例的存储容量的大小 -- CPU：每个 TiKV 实例 CPU 的使用率 -- Memory：每个 TiKV 实例内存的使用情况 -- IO utilization：每个 TiKV 实例 IO 的使用率 -- MBps：每个 TiKV 实例写入和读取的数据量大小 -- QPS：每个 TiKV 实例上各种命令的 QPS -- Errps：每个 TiKV 实例上 gRPC 消息失败的个数 -- leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 - -![TiKV Dashboard - Cluster metrics](/media/tikv-dashboard-cluster.png) - -## Errors - -- Server is busy：各种会导致 server 繁忙的事件个数，如 write stall，channel full 等，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Raftstore error：每个 TiKV 实例上 raftstore 发生错误的个数 -- Scheduler error：每个 TiKV 实例上 scheduler 发生错误的个数 -- Coprocessor error：每个 TiKV 实例上 coprocessor 发生错误的个数 -- gRPC message error：每个 TiKV 实例上 gRPC 消息发生错误的个数 -- Leader drop：每个 TiKV 实例上 drop leader 的个数 -- Leader missing：每个 TiKV 实例上 missing leader 的个数 - -![TiKV Dashboard - Errors metrics](/media/tikv-dashboard-errors.png) - -## Server - -- Leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 -- CF size：每个 CF 的大小 -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Channel full：每个 TiKV 实例上 channel full 错误的数量，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Region average written keys：每个 TiKV 实例上所有 Region 的平均 key 写入个数 -- Region average written bytes：每个 TiKV 实例上所有 Region 的平均写入大小 -- Active written leaders：每个 TiKV 实例上有效的 leader 个数 -- Approximate Region size：每个 Region 近似的大小 - -![TiKV Dashboard - Server metrics](/media/tikv-dashboard-server.png) - -## Raft IO - -- Apply log duration：Raft apply 日志所花费的时间 -- Apply log duration per server：每个 TiKV 实例上 Raft apply 日志所花费的时间 -- Append log duration：Raft append 日志所花费的时间 -- Append log duration per server：每个 TiKV 实例上 Raft append 日志所花费的时间 - -![TiKV Dashboard - Raft IO metrics](/media/tikv-dashboard-raftio.png) - -## Raft process - -- Ready handled：Raft 中不同 ready 类型的个数 -- Process ready duration per server：每个 TiKV 实例处理 ready 所花费的时间，99.99% 的情况下，应该小于 2s -- Process tick duration per server：每个 TiKV 实例处理 tick 所花费的时间 -- 0.99 Duration of Raft store events：99% 的 raftstore 事件所花费的时间 - -![TiKV Dashboard - Raft process metrics](/media/tikv-dashboard-raft-process.png) - -## Raft message - -- Sent messages per server：每个 TiKV 实例发送 Raft 消息的个数 -- Flush messages per server：每个 TiKV 实例持久化 Raft 消息的个数 -- Receive messages per server：每个 TiKV 实例接受 Raft 消息的个数 -- Messages：发送不同类型的 Raft 消息的个数 -- Vote：Raft 投票消息发送的个数 -- Raft dropped messages：丢弃不同类型的 Raft 消息的个数 - -![TiKV Dashboard - Raft message metrics](/media/tikv-dashboard-raft-message.png) - -## Raft propose - -- Raft proposals per ready：在一个 mio tick 内，所有 Region proposal 的个数 -- Raft read/write proposals：不同类型的 proposal 的个数 -- Raft read proposals per server：每个 TiKV 实例发起读 proposal 的个数 -- Raft write proposals per server：每个 TiKV 实例发起写 proposal 的个数 -- Propose wait duration：每个 proposal 的等待时间 -- Propose wait duration per server：每个 TiKV 实例上每个 proposal 的等待时间 -- Raft log speed：peer propose 日志的速度 - -![TiKV Dashboard - Raft propose metrics](/media/tikv-dashboard-raft-propose.png) - -## Raft admin - -- Admin proposals：admin proposal 的个数 -- Admin apply：apply 命令的个数 -- Check split：split check 命令的个数 -- 99.99% Check split duration：99.99% 的情况下，split check 所需花费的时间 - -![TiKV Dashboard - Raft admin metrics](/media/tikv-dashboard-raft-admin.png) - -## Local reader - -- Local reader requests：所有请求的总数以及 local read 线程拒绝的请求数量 -- Local read requests duration：local read 请求的等待时间 -- Local read requests batch size：local read 请求的批量大小 - -![TiKV Dashboard - Local reader metrics](/media/tikv-dashboard-local-reader.png) - -## Storage - -- Storage command total：收到不同命令的个数 -- Storage async request error：异步请求出错的个数 -- Storage async snapshot duration：异步处理 snapshot 所花费的时间，99% 的情况下，应该小于 1s -- Storage async write duration：异步写所花费的时间，99% 的情况下，应该小于 1s - -![TiKV Dashboard - Storage metrics](/media/tikv-dashboard-storage.png) - -## Scheduler - -- Scheduler stage total：每种命令不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler priority commands：不同优先级命令的个数 -- Scheduler pending commands：每个 TiKV 实例上 pending 命令的个数 - -![TiKV Dashboard - Scheduler metrics](/media/tikv-dashboard-scheduler.png) - -## Scheduler - batch_get - -- Scheduler stage total：batch_get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 batch_get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：batch_get 命令读取 key 的个数 -- Scheduler keys written：batch_get 命令写入 key 的个数 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 batch_get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 batch_get 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - batch_get metrics](/media/tikv-dashboard-scheduler-batch-get.png) - -## Scheduler - cleanup - -- Scheduler stage total：cleanup 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 cleanup 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：cleanup 命令读取 key 的个数 -- Scheduler keys written：cleanup 命令写入 key 的个数 -- Scheduler scan details：执行 cleanup 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 cleanup 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 cleanup 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 cleanup 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - cleanup metrics](/media/tikv-dashboard-scheduler-cleanup.png) - -## Scheduler - commit - -- Scheduler stage total：commit 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 commit 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：commit 命令读取 key 的个数 -- Scheduler keys written：commit 命令写入 key 的个数 -- Scheduler scan details：执行 commit 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 commit 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 commit 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 commit 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler commit metrics](/media/tikv-dashboard-scheduler-commit.png) - -## Scheduler - gc - -- Scheduler stage total：gc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 gc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：gc 命令读取 key 的个数 -- Scheduler keys written：gc 命令写入 key 的个数 -- Scheduler scan details：执行 gc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 gc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 gc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 gc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - get - -- Scheduler stage total：get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：get 命令读取 key 的个数 -- Scheduler keys written：get 命令写入 key 的个数 -- Scheduler scan details：执行 get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 get 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - key_mvcc - -- Scheduler stage total：key_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 key_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：key_mvcc 命令读取 key 的个数 -- Scheduler keys written：key_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 key_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 key_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 key_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 key_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - prewrite - -- Scheduler stage total：prewrite 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 prewrite 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：prewrite 命令读取 key 的个数 -- Scheduler keys written：prewrite 命令写入 key 的个数 -- Scheduler scan details：执行 prewrite 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 prewrite 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 prewrite 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 prewrite 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - resolve_lock - -- Scheduler stage total：resolve_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 resolve_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：resolve_lock 命令读取 key 的个数 -- Scheduler keys written：resolve_lock 命令写入 key 的个数 -- Scheduler scan details：执行 resolve_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 resolve_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 resolve_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 resolve_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan - -- Scheduler stage total：scan 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan 命令读取 key 的个数 -- Scheduler keys written：scan 命令写入 key 的个数 -- Scheduler scan details：执行 scan 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan_lock - -- Scheduler stage total：scan_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan_lock 命令读取 key 的个数 -- Scheduler keys written：scan_lock 命令写入 key 的个数 -- Scheduler scan details：执行 scan_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - start_ts_mvcc - -- Scheduler stage total：start_ts_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 start_ts_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：start_ts_mvcc 命令读取 key 的个数 -- Scheduler keys written：start_ts_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 start_ts_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 start_ts_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 start_ts_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 start_ts_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - unsafe_destroy_range - -- Scheduler stage total：unsafe_destroy_range 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 unsafe_destroy_range 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：unsafe_destroy_range 命令读取 key 的个数 -- Scheduler keys written：unsafe_destroy_range 命令写入 key 的个数 -- Scheduler scan details：执行 unsafe_destroy_range 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 unsafe_destroy_range 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 unsafe_destroy_range 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 unsafe_destroy_range 命令时，扫描每个 default CF 中 key 的详细情况 - -## Coprocessor - -- Request duration：处理 coprocessor 读请求所花费的时间 -- Wait duration：coprocessor 请求的等待时间，99.99% 的情况下，应该小于 10s -- Handle duration：处理 coprocessor 请求所花费的时间 -- 95% Request duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 读请求所花费的时间 -- 95% Wait duration by store：95% 的情况下，每个 TiKV 实例上 coprocessor 请求的等待时间 -- 95% Handle duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 请求所花费的时间 -- Request errors：下推的请求发生错误的个数，正常情况下，短时间内不应该有大量的错误 -- DAG executors：DAG executor 的个数 -- Scan keys：每个请求 scan key 的个数 -- Scan details：scan 每个 CF 的详细情况 -- Table Scan - Details by CF：table scan 针对每个 CF 的详细情况 -- Index Scan - Details by CF：index scan 针对每个 CF 的详细情况 -- Table Scan - Perf Statistics：执行 table sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 -- Index Scan - Perf Statistics：执行 index sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 - -## GC - -- MVCC versions：每个 key 的版本个数 -- MVCC delete versions：GC 删除掉的每个 key 的版本个数 -- GC tasks：由 gc_worker 处理的 GC 任务的个数 -- GC tasks Duration：执行 GC 任务时所花费的时间 -- GC keys (write CF)：在 GC 过程中，write CF 中 受影响的 key 的个数 -- TiDB GC actions result：TiDB Region 层面的 GC 结果 -- TiDB GC worker actions：TiDB GC worker 的不同 action 的个数 -- TiDB GC seconds：TiDB 执行 GC 花费的时间 -- TiDB GC failure：TiDB GC job 失败的个数 -- GC lifetime：TiDB 设置的 GC lifetime -- GC interval：TiDB 设置的 GC 间隔 - -## Snapshot - -- Rate snapshot message：发送 Raft snapshot 消息的速率 -- 99% Handle snapshot duration：99% 的情况下，处理 snapshot 所需花费的时间 -- Snapshot state count：不同状态的 snapshot 的个数 -- 99.99% Snapshot size：99.99% 的 snapshot 的大小 -- 99.99% Snapshot KV count：99.99% 的 snapshot 包含的 key 的个数 - -## Task - -- Worker handled tasks：worker 处理的任务个数 -- Worker pending tasks：当前 worker 中，pending 和 running 的任务个数，正常情况下，应该小于 1000 -- FuturePool handled tasks：future pool 处理的任务个数 -- FuturePool pending tasks：当前 future pool 中，pending 和 running 的任务个数 - -## Thread CPU - -- Raft store CPU：raftstore 线程的 CPU 使用率，通常应低于 80% -- Async apply CPU：async apply 线程的 CPU 使用率，通常应低于 90% -- Scheduler CPU：scheduler 线程的 CPU 使用率，通常应低于 80% -- Scheduler worker CPU：scheduler worker 线程的 CPU 使用率 -- Storage ReadPool CPU：Readpool 线程的 CPU 使用率 -- Coprocessor CPU：coprocessor 线程的 CPU 使用率 -- Snapshot worker CPU：snapshot worker 线程的 CPU 使用率 -- Split check CPU：split check 线程的 CPU 使用率 -- RocksDB CPU：RocksDB 线程的 CPU 使用率 -- gRPC poll CPU：gRPC 线程的 CPU 使用率，通常应低于 80% - -## RocksDB - kv - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## RocksDB - raft - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## gRPC - -- gRPC message count：每种 gRPC 消息的个数 -- gRPC message failed：失败的 gRPC 消息的个数 -- 99% gRPC message duration：在 99% gRPC 消息的执行时间 -- gRPC GC message count：gRPC GC 消息的个数 -- 99% gRPC KV GC message duration：在 99% 情况下，gRPC GC 消息的执行时间 - -## PD - -- PD requests：TiKV 发送给 PD 的请求个数 -- PD request duration (average)：TiKV 发送给 PD 的请求所需的平均时间 -- PD heartbeats：发送给 PD 的心跳个数 -- PD validate peers：通过 PD 验证 TiKV 的 peer 有效的个数 diff --git a/v2.1/reference/mysql-compatibility.md b/v2.1/reference/mysql-compatibility.md deleted file mode 100644 index 1c3167efbe86..000000000000 --- a/v2.1/reference/mysql-compatibility.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: 与 MySQL 兼容性对比 -category: reference ---- - -# 与 MySQL 兼容性对比 - -TiDB 支持 MySQL 传输协议及其绝大多数的语法。这意味着您现有的 MySQL 连接器和客户端都可以继续使用。大多数情况下您现有的应用都可以迁移至 TiDB，无需任何代码修改。 - -当前 TiDB 服务器官方支持的版本为 MySQL 5.7。大部分 MySQL 运维工具（如 PHPMyAdmin, Navicat, MySQL Workbench 等），以及备份恢复工具（如 mysqldump，Mydumper/myloader）等都可以直接使用。 - -不过一些特性由于在分布式环境下没法很好的实现，目前暂时不支持或者是表现与 MySQL 有差异。一些 MySQL 语法在 TiDB 中可以解析通过，但是不会做任何后续的处理，例如 `Create Table` 语句中 `Engine` 以及 `Partition` 选项，都是解析并忽略。 - -> **注意：** -> -> 本页内容仅涉及 MySQL 与 TiDB 的总体差异。关于[安全特性](/v2.1/reference/security/compatibility.md)的兼容信息请查看各自具体页面。 - -## 不支持的特性 - -* 存储过程与函数 -* 视图 -* 触发器 -* 事件 -* 自定义函数 -* 外键约束 -* 全文函数与索引 -* 空间函数与索引 -* 非 `ascii`/`latin1`/`binary`/`utf8`/`utf8mb4` 的字符集 -* `BINARY` 之外的排序规则 -* 增加主键 -* 删除主键 -* SYS schema -* MySQL 追踪优化器 -* XML 函数 -* X Protocol -* Savepoints -* 列级权限 -* `CREATE TABLE tblName AS SELECT stmt` 语法 -* `CREATE TEMPORARY TABLE` 语法 -* `XA` 语法（TiDB 内部使用两阶段提交，但并没有通过 SQL 接口公开） -* `LOCK TABLE` 语法（TiDB 使用 `tidb_snapshot` 来[生成备份](/v2.1/reference/tools/mydumper.md) -* `CHECK TABLE` 语法 -* `CHECKSUM TABLE` 语法 - -## 与 MySQL 有差异的特性 - -### 自增 ID - -TiDB 中，自增列只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配 ID 的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。 - -在集群中有多个 tidb-server 实例时，如果表结构中有自增 ID，建议不要混用缺省值和自定义值，否则在如下情况下会遇到问题。 - -假设有这样一个带有自增 ID 的表： - -{{< copyable "sql" >}} - -```sql -create table t(id int unique key AUTO_INCREMENT, c int); -``` - -TiDB 实现自增 ID 的原理是每个 tidb-server 实例缓存一段 ID 值用于分配（目前会缓存 30000 个 ID），用完这段值再去取下一段。 - -假设集群中有两个 tidb-server 实例 A 和 B（A 缓存 [1,30000] 的自增 ID，B 缓存 [30001,60000] 的自增 ID），依次执行如下操作： - -1. 客户端向 B 插入一条将 `id` 设置为 1 的语句 `insert into t values (1, 1)`，并执行成功。 -2. 客户端向 A 发送 Insert 语句 `insert into t (c) (1)`，这条语句中没有指定 `id` 的值，所以会由 A 分配，当前 A 缓存了 [1, 30000] 这段 ID，所以会分配 1 为自增 ID 的值，并把本地计数器加 1。而此时数据库中已经存在 `id` 为 1 的数据，最终返回 `Duplicated Error` 错误。 - -另外，从 TiDB 2.1.18 开始，TiDB 将通过系统变量 `@@tidb_allow_remove_auto_inc` 控制是否允许通过 `alter table modify` 或 `alter table change` 来移除列的 `AUTO_INCREMENT` 属性，默认是不允许移除。 - -### Performance schema - -Performance schema 表在 TiDB 中返回结果为空。TiDB 使用 [Prometheus 和 Grafana](/v2.1/how-to/monitor/monitor-a-cluster.md) 来监测性能指标。 - -### 查询计划 - -TiDB 的查询计划（`EXPLAIN`/`EXPLAIN FOR`）输出格式与 MySQL 差别较大，同时 `EXPLAIN FOR` 的输出内容与权限设置与 MySQL 不一致，参见[理解 TiDB 执行计划](/v2.1/reference/performance/understanding-the-query-execution-plan.md)。 - -### 内建函数 - -TiDB 支持常用的 MySQL 内建函数，但是不是所有的函数都已经支持，具体请参考[语法文档](https://pingcap.github.io/sqlgram/#functioncallkeyword)。 - -### DDL - -在 TiDB 中，运行的 DDL 操作不会影响对表的读取或写入。但是，目前 DDL 变更有如下一些限制： - -+ Add Index - - 不支持同时创建多个索引 - - 不支持通过 `ALTER TABLE` 在所生成的列上添加索引 -+ Add Column - - 不支持同时创建多个列 - - 不支持将新创建的列设为主键或唯一索引，也不支持将此列设成 AUTO_INCREMENT 属性 -+ Drop Column: 不支持删除主键列或索引列 -+ Change/Modify Column - - 不支持有损变更，比如从 `BIGINT` 变为 `INTEGER`，或者从 `VARCHAR(255)` 变为 `VARCHAR(10)` - - 不支持修改 `DECIMAL` 类型的精度（从 TiDB 2.1.10 开始，不支持修改 `DECIMAL` 类型的精度，TiDB 2.1.9 支持修改） - - 不支持更改 `UNSIGNED` 属性 - - 不支持从 `NULL` 到 `NOT NULL` 的修改 - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ Alter Database - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}`: TiDB 支持的语法，但是在 TiDB 中不会生效。所有支持的 DDL 变更都不会锁表。 -+ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}`: TiDB 完全支持 `ALGORITHM=INSTANT` 和 `ALGORITHM=INPLACE` 语法，但运行过程与 MySQL 有所不同，因为 MySQL 中的一些 `INPLACE` 操作实际上是 TiDB 中的 `INSTANT` 操作。`ALGORITHM=COPY` 语法在 TiDB 中不会生效，会返回警告信息。 - -### `ANALYZE TABLE` - -- [`ANALYZE TABLE`](/v2.1/reference/performance/statistics.md#手动收集) 语句在 TiDB 和 MySQL 中表现不同。在 MySQL/InnoDB 中，它是一个轻量级语句，执行过程较短；而在 TiDB 中，它会完全重构表的统计数据，语句执行过程较长。 - -### 存储引擎 - -出于兼容性原因，TiDB 支持使用备用存储引擎创建表的语法。元数据命令将表描述为 InnoDB 存储引擎： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT) ENGINE=MyISAM; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin -1 row in set (0.00 sec) -``` - -从架构上讲，TiDB 确实支持类似 MySQL 的存储引擎抽象，在启动 TiDB（通常是 `tikv`）时 [`--store`](/v2.1/reference/configuration/tidb-server/configuration.md#store) 选项指定的引擎中创建用户表。 - -### SQL 模式 - -TiDB 支持 MySQL 5.7 中 **绝大多数的 SQL 模式**，以下几种模式除外： - -- TiDB 不支持兼容模式（例如 `ORACLE` 和 `POSTGRESQL`）。MySQL 5.7 已弃用兼容模式，MySQL 8.0 已移除兼容模式。 -- TiDB 中的 `ONLY_FULL_GROUP_BY` 与 MySQL 5.7 相比有细微的[语义差别](/v2.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md#与-mysql-的区别)，此问题日后将予以解决。 -- `NO_DIR_IN_CREATE` 和 `NO_ENGINE_SUBSTITUTION` 这两种 SQL 模式用于解决兼容问题，但并不适用于 TiDB。 - -### 默认设置的区别 - -+ 默认字符集与 MySQL 不同： - + TiDB 中为 `utf8mb4` - + MySQL 5.7 中为 `latin1`，MySQL 8.0 中修改为 `utf8mb4` -+ 默认排序规则不同： - + TiDB 中，`utf8mb4` 的默认排序规则为 `utf8mb4_bin` - + MySQL 5.7 中，`utf8mb4` 的默认排序规则为 `utf8mb4_general_ci`，MySQL 8.0 中修改为 `utf8mb4_0900_ai_ci` - + 请使用 [`SHOW CHARACTER SET`](/v2.1/reference/sql/statements/show-character-set.md) 语句查看所有字符集的默认排序规则 -+ 默认 SQL mode 与 MySQL 5.7 相同，与 MySQL 8.0 不同： - + TiDB 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` - + MySQL 中默认设置： - + MySQL 5.7 的默认 SQL mode 与 TiDB 相同 - + MySQL 8.0 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION` -+ `lower_case_table_names` 的默认值不同： - + TiDB 中该值默认为 2，并且目前 TiDB 只支持设置该值为 2 - + MySQL 中默认设置： - + Linux 系统中该值为 0 - + Windows 系统中该值为 1 - + macOS 系统中该值为 2 -+ `explicit_defaults_for_timestamp` 的默认值不同： - + TiDB 中该值默认为 `ON`，并且目前 TiDB 只支持设置该值为 `ON` - + MySQL 中默认设置： - + MySQL 5.7：`OFF` - + MySQL 8.0：`ON` - -### 日期时间处理的区别 - -#### 时区 - -MySQL 默认使用本地时区，依赖于系统内置的当前的时区规则（例如什么时候开始夏令时等）进行计算；且在未[导入时区表数据](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation)的情况下不能通过时区名称来指定时区。 - -TiDB 不需要导入时区表数据也能使用所有时区名称，采用系统当前安装的所有时区规则进行计算（一般为 `tzdata` 包），且无法通过导入时区表数据的形式修改计算规则。 - -> **注意：** -> -> 能下推到 TiKV 的时间相关表达式会由 TiKV 进行计算。TiKV 总是采用 TiKV 内置时区规则计算，而不依赖于系统所安装的时区规则。若系统安装的时区规则与 TiKV 内置的时区规则版本不匹配，则在少数情况下可能发生能插入的时间数据无法再读出来的问题。例如，若系统上安装了 tzdata 2018a 时区规则，则在时区设置为 Asia/Shanghai 或时区设置为本地时区且本地时区为 Asia/Shanghai 的情况下，时间 `1988-04-17 02:00:00` 可以被正常插入 TiDB 3.0 RC.1，但该记录对于特定类型 SQL 则无法再读出来，原因是 TiKV 3.0 RC.1 依据的 tzdata 2018i 规则中该时间在 Asia/Shanghai 时区中不存在（夏令时时间后移一小时）。 -> -> TiKV 各个版本内置的时区规则如下： -> -> - 3.0.0 RC.1 及以后：[tzdata 2018i](https://github.com/eggert/tz/tree/2018i) -> - 2.1.0 RC.1 及以后：[tzdata 2018e](https://github.com/eggert/tz/tree/2018e) - -#### 零月和零日 - -目前 TiDB 尚不能完整支持月为 0 或日为 0（但年不为 0）的日期。在非严格模式下，此类日期时间能被正常插入，但对于特定类型 SQL 可能出现无法读出来的情况。 diff --git a/v2.1/reference/performance/optimizer-hints.md b/v2.1/reference/performance/optimizer-hints.md deleted file mode 100644 index e85e182507a8..000000000000 --- a/v2.1/reference/performance/optimizer-hints.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Optimizer Hints -category: reference ---- - -# Optimizer Hints - -TiDB 支持 Optimizer Hints 语法，它基于 MySQL 5.7 中介绍的类似 comment 的语法，例如 `/*+ TIDB_XX(t1, t2) */`。当 TiDB 优化器选择的不是最优查询计划时，建议使用 Optimizer Hints。 - -> **注意：** -> -> MySQL 命令行客户端在 5.7.7 版本之前默认清除了 Optimizer Hints。如果需要在这些早期版本的客户端中使用 `Hint` 语法，需要在启动客户端时加上 `--comments` 选项，例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。 - -## 语法 - -### TIDB_SMJ(t1, t2) - -```sql -SELECT /*+ TIDB_SMJ(t1, t2) */ * from t1，t2 where t1.id = t2.id -``` - -提示优化器使用 Sort Merge Join 算法，这个算法通常会占用更少的内存，但执行时间会更久。 -当数据量太大，或系统内存不足时，建议尝试使用。 - -### TIDB_INLJ(t1, t2) - -```sql -SELECT /*+ TIDB_INLJ(t1, t2) */ * from t1，t2 where t1.id = t2.id -``` - -提示优化器使用 Index Nested Loop Join 算法，这个算法可能会在某些场景更快，消耗更少系统资源，有的场景会更慢，消耗更多系统资源。对于外表经过 WHERE 条件过滤后结果集较小（小于 1 万行）的场景，可以尝试使用。`TIDB_INLJ()` 中的参数是建立查询计划时，内表的候选表。即 `TIDB_INLJ(t1)` 只会考虑使用 t1 作为内表构建查询计划。 - -### TIDB_HJ(t1, t2) - -```sql -SELECT /*+ TIDB_HJ(t1, t2) */ * from t1，t2 where t1.id = t2.id -``` - -提示优化器使用 Hash Join 算法，这个算法多线程并发执行，执行速度较快，但会消耗较多内存。 - -### MAX\_EXECUTION\_TIME(N) - - 在 `SELECT` 语句中可以使用 `MAX_EXECUTION_TIME(N)`，它会限制语句的执行时间不能超过 `N` 毫秒，否则服务器会终止这条语句的执行。 - -例如，下面例子设置了 1 秒超时： - -```sql -SELECT /*+ MAX_EXECUTION_TIME(1000) */ * FROM t1 INNER JOIN t2 WHERE ... -``` - - 除了 hint 之外，环境变量 `max_execution_time` 也会对语句执行时间进行限制。 diff --git a/v2.1/reference/performance/sql-optimizer-overview.md b/v2.1/reference/performance/sql-optimizer-overview.md deleted file mode 100644 index 5d922ce54720..000000000000 --- a/v2.1/reference/performance/sql-optimizer-overview.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: SQL 优化流程简介 -category: reference ---- - -# SQL 优化流程简介 - -在 TiDB 中，SQL 优化过程分为逻辑优化和物理优化两个阶段。 - -## 逻辑优化简介 - -逻辑优化是基于规则的优化，对输入的逻辑执行计划按顺序应用一些优化规则，从而使整个逻辑执行计划变得更好。这些优化规则包括： - -- 列裁剪 -- 投影消除 -- 关联子查询去关联 -- Max/Min 消除 -- 谓词下推 -- 分区裁剪 -- TopN 和 Limit 下推 - -## 物理优化简介 - -物理优化是基于代价的优化，为上一阶段产生的逻辑执行计划制定物理执行计划。这一阶段中，优化器会为逻辑执行计划中的每个算子选择具体的物理实现。逻辑算子的不同物理实现有着不同的时间复杂度、资源消耗和物理属性等。在这个过程中，优化器会根据数据的统计信息来确定不同物理实现的代价，并选择整体代价最小的物理执行计划。 - -逻辑执行计划是一个树形结构，每个节点对应 SQL 中的一个逻辑算子。同样的，物理执行计划也是一个树形结构，每个节点对应 SQL 中的一个物理算子。逻辑算子只描述这个算子的功能，而物理算子则描述了完成这个功能的具体算法。对于同一个逻辑算子，可能有多个物理算子实现，比如 `LogicalAggregate`，它的实现可以是采用哈希算法的 `HashAggregate`，也可以是流式的 `StreamAggregate`。不同的物理算子具有不同的物理属性，也对其子节点有着不同的物理属性的要求。物理属性包括数据的顺序和分布等。TiDB 中现在只考虑了数据的顺序。 diff --git a/v2.1/reference/performance/statistics.md b/v2.1/reference/performance/statistics.md deleted file mode 100644 index e42db5a3e679..000000000000 --- a/v2.1/reference/performance/statistics.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: 统计信息简介 -category: reference ---- - -# 统计信息简介 - -TiDB 优化器会根据统计信息来选择最优的执行计划。统计信息收集了表级别和列级别的信息，表的统计信息包括总行数和修改的行数。列的统计信息包括不同值的数量、NULL 的数量、直方图，以及该列的 Count-Min Sketch 信息。 - -## 统计信息的收集 - -### 手动收集 - -可以通过执行 `ANALYZE` 语句来收集统计信息。 - -> **注意：** -> -> 在 TiDB 中执行 `ANALYZE TABLE` 语句比在 MySQL 或 InnoDB 中耗时更长。InnoDB 采样的只是少量页面，但 TiDB 会完全重构一系列统计信息。适用于 MySQL 的脚本会误以为执行 `ANALYZE TABLE` 耗时较短。 - -语法： - -```sql -ANALYZE TABLE TableNameList [WITH NUM BUCKETS] -> 该语句会收集 TableNameList 中所有表的统计信息。 -> WITH NUM BUCKETS 可以用来指定生成直方图的桶数量上限。 - -ANALYZE TABLE TableName INDEX [IndexNameList] [WITH NUM BUCKETS] -> 该语句会收集 TableName 中所有的 IndexNameList 中的索引列的统计信息。 -> IndexNameList 为空时会收集所有索引列的统计信息。 - -ANALYZE TABLE TableName PARTITION PartitionNameList [WITH NUM BUCKETS] -> 该语句会收集 TableName 中所有的 PartitionNameList 中分区的统计信息。 - -ANALYZE TABLE TableName PARTITION PartitionNameList [IndexNameList] [WITH NUM BUCKETS] -> 该语句会收集 TableName 中所有的 PartitionNameList 中分区的索引列统计信息。 -``` - -### 自动更新 - -在发生增加，删除以及修改语句时，TiDB 会自动更新表的总行数以及修改的行数。这些信息会定期持久化下来， -更新的周期是 20 * `stats-lease`，`stats-lease` 的默认值是 3s，如果将其指定为 0，那么将不会自动更新。 - -和统计信息自动更新相关的三个系统变量如下： - -| 系统变量名 | 默认值 | 功能 | -|:---|:---|:---| -| `tidb_auto_analyze_ratio`| 0.5 | 自动更新阈值 | -| `tidb_auto_analyze_start_time` | `00:00 +0000` | 一天中能够进行自动更新的开始时间 | -| `tidb_auto_analyze_end_time` | `23:59 +0000` | 一天中能够进行自动更新的结束时间 | - -当某个表 `tbl` 的修改行数与总行数的比值大于 `tidb_auto_analyze_ratio`，并且当前时间在 `tidb_auto_analyze_start_time` 和 `tidb_auto_analyze_end_time` 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句自动更新这个表的统计信息。 - -在查询语句执行时，TiDB 会以 `feedback-probability` 的概率收集反馈信息，并将其用于更新直方图和 Count-Min Sketch。`feedback-probability` 可通过配置文件修改，其默认值是 `0.0`。 - -### 控制 ANALYZE 并发度 - -执行 ANALYZE 语句的时候，你可以通过一些参数来调整并发度，以控制对系统的影响。 - -#### tidb_build_stats_concurrency - -目前 ANALYZE 执行的时候会被切分成一个个小的任务，每个任务只负责某一个列或者索引。`tidb_build_stats_concurrency` 可以控制同时执行的任务的数量，其默认值是 4。 - -#### tidb_distsql_scan_concurrency - -在执行分析普通列任务的时候，`tidb_distsql_scan_concurrency` 可以用于控制一次读取的 Region 数量，其默认值是 15。 - -#### tidb_index_serial_scan_concurrency - -在执行分析索引列任务的时候，`tidb_index_serial_scan_concurrency` 可以用于控制一次读取的 Region 数量，其默认值是 1。 - -## 统计信息的查看 - -你可以通过一些语句来查看统计信息的状态。 - -### 表的元信息 - -你可以通过 `SHOW STATS_META` 来查看表的总行数以及修改的行数等信息。 - -语法： - -```sql -SHOW STATS_META [ShowLikeOrWhere] -> 该语句会输出所有表的总行数以及修改行数等信息，你可以通过使用 ShowLikeOrWhere 来筛选需要的信息。 -``` - -目前 `SHOW STATS_META` 会输出 6 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| update_time | 更新时间 | -| modify_count | 修改的行数 | -| row_count | 总行数 | - -> **注意：** -> -> 在 TiDB 根据 DML 语句自动更新总行数以及修改的行数时，`update_time` 也会被更新，因此并不能认为 `update_time` 是最近一次发生 Analyze 的时间。 - -### 表的健康度信息 - -通过 `SHOW STATS_HEALTHY` 可以查看表的统计信息健康度，并粗略估计表上统计信息的准确度。当 `modify_count` >= `row_count` 时，健康度为 0；当 `modify_count` < `row_count` 时，健康度为 (1 - `modify_count`/`row_count`) * 100。 - -通过以下命令来查看表的统计信息健康度，你可以通过 `ShowLikeOrWhere` 来筛选需要的信息： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_HEALTHY [ShowLikeOrWhere]; -``` - -目前，`SHOW STATS_HEALTHY` 会输出 3 列，具体如下： - -| 语法元素 | 说明 | -| :-------- | :------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| healthy | 健康度 | - -### 列的元信息 - -你可以通过 `SHOW STATS_HISTOGRAMS` 来查看列的不同值数量以及 NULL 数量等信息。 - -语法： - -```sql -SHOW STATS_HISTOGRAMS [ShowLikeOrWhere] -> 该语句会输出所有列的不同值数量以及 NULL 数量等信息，你可以通过使用 ShowLikeOrWhere 来筛选需要的信息。 -``` - -目前 `SHOW STATS_HISTOGRAMS` 会输出 8 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name | 分区名 | -| column_name | 根据 is_index 来变化：is_index 为 0 时是列名，为 1 时是索引名 | -| is_index | 是否是索引列 | -| update_time | 更新时间 | -| distinct_count | 不同值数量 | -| null_count | NULL 的数量 | -| avg_col_size | 列平均长度 | - -### 直方图桶的信息 - -你可以通过 `SHOW STATS_BUCKETS` 来查看直方图每个桶的信息。 - -语法： - -```sql -SHOW STATS_BUCKETS [ShowLikeOrWhere] -> 该语句会输出所有桶的信息，你可以通过使用 ShowLikeOrWhere 来筛选需要的信息。 -``` - -目前 `SHOW STATS_BUCKETS` 会输出 10 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name | 分区名 | -| column_name | 根据 is_index 来变化：is_index 为 0 时是列名，为 1 时是索引名 | -| is_index | 是否是索引列 | -| bucket_id | 桶的编号 | -| count | 所有落在这个桶及之前桶中值的数量 | -| repeats | 最大值出现的次数 | -| lower_bound | 最小值 | -| upper_bound | 最大值 | - -## 删除统计信息 - -可以通过执行 `DROP STATS` 语句来删除统计信息。 - -语法： - -```sql -DROP STATS TableName -> 该语句会删除 TableName 中所有的统计信息。 -``` - -## 统计信息的导入导出 - -### 导出统计信息 - -统计信息的导出接口为： - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name} -> 通过该接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 的 json 格式的统计信息。 -``` - -### 导入统计信息 - -导入的统计信息一般是通过统计信息导出接口得到的 json 文件。 - -语法： - -```sql -LOAD STATS 'file_name' -> `file_name` 为要导入的统计信息的文件名。 -``` diff --git a/v2.1/reference/performance/tune-tikv.md b/v2.1/reference/performance/tune-tikv.md deleted file mode 100644 index 2afee35ab618..000000000000 --- a/v2.1/reference/performance/tune-tikv.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: TiKV 性能参数调优 -category: reference ---- - -# TiKV 性能参数调优 - -本文档用于描述如何根据机器配置情况来调整 TiKV 的参数，使 TiKV 的性能达到最优。 - -TiKV 最底层使用的是 RocksDB 做为持久化存储，所以 TiKV 的很多性能相关的参数都是与 RocksDB 相关的。TiKV 使用了两个 RocksDB 实例，默认 RocksDB 实例存储 KV 数据，Raft RocksDB 实例（简称 RaftDB）存储 Raft 数据。 - -TiKV 使用了 RocksDB 的 `Column Families` (CF) 特性。 - -- 默认 RocksDB 实例将 KV 数据存储在内部的 `default`、`write` 和 `lock` 3 个 CF 内。 - - - `default` CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中； - - `write` CF 存储的是数据的版本信息 (MVCC) 以及索引相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中； - - `lock` CF 存储的是锁信息，系统使用默认参数。 - -- Raft RocksDB 实例存储 Raft log。 - - - `default` CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 - -每个 CF 都有单独的 `block-cache`，用于缓存数据块，加速 RocksDB 的读取速度，block-cache 的大小通过参数 `block-cache-size` 控制，`block-cache-size` 越大，能够缓存的热点数据越多，对读取操作越有利，同时占用的系统内存也会越多。 - -每个 CF 有各自的 `write-buffer`，大小通过 `write-buffer-size` 控制。 - -## 参数说明 - -```toml -# 日志级别，可选值为：trace，debug，info，warn，error，off -log-level = "info" - -[server] -# 监听地址 -# addr = "127.0.0.1:20160" - -# gRPC 线程池大小 -# grpc-concurrency = 4 -# TiKV 每个实例之间的 gRPC 连接数 -# grpc-raft-conn-num = 10 - -# TiDB 过来的大部分读请求都会发送到 TiKV 的 Coprocessor 进行处理，该参数用于设置 -# coprocessor 线程的个数，如果业务是读请求比较多，增加 coprocessor 的线程数，但应比系统的 -# CPU 核数小。例如：TiKV 所在的机器有 32 core，在重读的场景下甚至可以将该参数设置为 30。在没有 -# 设置该参数的情况下，TiKV 会自动将该值设置为 CPU 总核数乘以 0.8。 -# end-point-concurrency = 8 - -# 可以给 TiKV 实例打标签，用于副本的调度 -# labels = {zone = "cn-east-1", host = "118", disk = "ssd"} - -[storage] -# 数据目录 -# data-dir = "/tmp/tikv/store" - -# 通常情况下使用默认值就可以了。在导数据的情况下建议将该参数设置为 1024000。 -# scheduler-concurrency = 102400 -# 该参数控制写入线程的个数，当写入操作比较频繁的时候，需要把该参数调大。使用 top -H -p tikv-pid -# 发现名称为 sched-worker-pool 的线程都特别忙，这个时候就需要将 scheduler-worker-pool-size -# 参数调大，增加写线程的个数。 -# scheduler-worker-pool-size = 4 - -[pd] -# pd 的地址 -# endpoints = ["127.0.0.1:2379","127.0.0.2:2379","127.0.0.3:2379"] - -[metric] -# 将 metrics 推送给 Prometheus pushgateway 的时间间隔 -interval = "15s" -# Prometheus Pushgateway 的地址 -address = "" -job = "tikv" - -[raftstore] -# 默认为 true，表示强制将数据刷到磁盘上。如果是非金融安全级别的业务场景，建议设置成 false， -# 以便获得更高的性能。 -sync-log = true - -# Raft RocksDB 目录。默认值是 [storage.data-dir] 的 raft 子目录。 -# 如果机器上有多块磁盘，可以将 Raft RocksDB 的数据放在不同的盘上，提高 TiKV 的性能。 -# raftdb-dir = "/tmp/tikv/store/raft" - -region-max-size = "384MB" -# Region 分裂阈值 -region-split-size = "256MB" -# 当 Region 写入的数据量超过该阈值的时候，TiKV 会检查该 Region 是否需要分裂。为了减少检查过程 -# 中扫描数据的成本，数据过程中可以将该值设置为32MB，正常运行状态下使用默认值即可。 -region-split-check-diff = "32MB" - -[rocksdb] -# RocksDB 进行后台任务的最大线程数，后台任务包括 compaction 和 flush。具体 RocksDB 为什么需要进行 compaction， -# 请参考 RocksDB 的相关资料。在写流量比较大的时候（例如导数据），建议开启更多的线程， -# 但应小于 CPU 的核数。例如在导数据的时候，32 核 CPU 的机器，可以设置成 28。 -# max-background-jobs = 8 - -# RocksDB 能够打开的最大文件句柄数。 -# max-open-files = 40960 - -# RocksDB MANIFEST 文件的大小限制.
# 更详细的信息请参考：https://github.com/facebook/rocksdb/wiki/MANIFEST -max-manifest-file-size = "20MB" - -# RocksDB write-ahead logs 目录。如果机器上有两块盘，可以将 RocksDB 的数据和 WAL 日志放在 -# 不同的盘上，提高 TiKV 的性能。 -# wal-dir = "/tmp/tikv/store" - -# 下面两个参数用于怎样处理 RocksDB 归档 WAL。 -# 更多详细信息请参考：https://github.com/facebook/rocksdb/wiki/How-to-persist-in-memory-RocksDB-database%3F -# wal-ttl-seconds = 0 -# wal-size-limit = 0 - -# RocksDB WAL 日志的最大总大小，通常情况下使用默认值就可以了。 -# max-total-wal-size = "4GB" - -# 可以通过该参数打开或者关闭 RocksDB 的统计信息。 -# enable-statistics = true - -# 开启 RocksDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。 -# compaction-readahead-size = "2MB" - -[rocksdb.defaultcf] -# 数据块大小。RocksDB 是按照 block 为单元对数据进行压缩的，同时 block 也是缓存在 block-cache -# 中的最小单元（类似其他数据库的 page 概念）。 -block-size = "64KB" - -# RocksDB 每一层数据的压缩方式，可选的值为：no,snappy,zlib,bzip2,lz4,lz4hc,zstd。 -# no:no:lz4:lz4:lz4:zstd:zstd 表示 level0 和 level1 不压缩，level2 到 level4 采用 lz4 压缩算法, -# level5 和 level6 采用 zstd 压缩算法,。 -# no 表示没有压缩，lz4 是速度和压缩比较为中庸的压缩算法，zlib 的压缩比很高，对存储空间比较友 -# 好，但是压缩速度比较慢，压缩的时候需要占用较多的 CPU 资源。不同的机器需要根据 CPU 以及 I/O 资 -# 源情况来配置怎样的压缩方式。例如：如果采用的压缩方式为"no:no:lz4:lz4:lz4:zstd:zstd"，在大量 -# 写入数据的情况下（导数据），发现系统的 I/O 压力很大（使用 iostat 发现 %util 持续 100% 或者使 -# 用 top 命令发现 iowait 特别多），而 CPU 的资源还比较充裕，这个时候可以考虑将 level0 和 -# level1 开启压缩，用 CPU 资源换取 I/O 资源。如果采用的压缩方式 -# 为"no:no:lz4:lz4:lz4:zstd:zstd"，在大量写入数据的情况下，发现系统的 I/O 压力不大，但是 CPU -# 资源已经吃光了，top -H 发现有大量的 bg 开头的线程（RocksDB 的 compaction 线程）在运行，这 -# 个时候可以考虑用 I/O 资源换取 CPU 资源，将压缩方式改成"no:no:no:lz4:lz4:zstd:zstd"。总之，目 -# 的是为了最大限度地利用系统的现有资源，使 TiKV 的性能在现有的资源情况下充分发挥。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# RocksDB memtable 的大小。 -write-buffer-size = "128MB" - -# 最多允许几个 memtable 存在。写入到 RocksDB 的数据首先会记录到 WAL 日志里面，然后会插入到 -# memtable 里面，当 memtable 的大小到达了 write-buffer-size 限定的大小的时候，当前的 -# memtable 会变成只读的，然后生成一个新的 memtable 接收新的写入。只读的 memtable 会被 -# RocksDB 的 flush 线程（max-background-flushes 参数能够控制 flush 线程的最大个数） -# flush 到磁盘，成为 level0 的一个 sst 文件。当 flush 线程忙不过来，导致等待 flush 到磁盘的 -# memtable 的数量到达 max-write-buffer-number 限定的个数的时候，RocksDB 会将新的写入 -# stall 住，stall 是 RocksDB 的一种流控机制。在导数据的时候可以将 max-write-buffer-number -# 的值设置的更大一点，例如 10。 -max-write-buffer-number = 5 - -# 当 level0 的 sst 文件个数到达 level0-slowdown-writes-trigger 指定的限度的时候， -# RocksDB 会尝试减慢写入的速度。因为 level0 的 sst 太多会导致 RocksDB 的读放大上升。 -# level0-slowdown-writes-trigger 和 level0-stop-writes-trigger 是 RocksDB 进行流控的 -# 另一个表现。当 level0 的 sst 的文件个数到达 4（默认值），level0 的 sst 文件会和 level1 中 -# 有 overlap 的 sst 文件进行 compaction，缓解读放大的问题。 -level0-slowdown-writes-trigger = 20 - -# 当 level0 的 sst 文件个数到达 level0-stop-writes-trigger 指定的限度的时候，RocksDB 会 -# stall 住新的写入。 -level0-stop-writes-trigger = 36 - -# 当 level1 的数据量大小达到 max-bytes-for-level-base 限定的值的时候，会触发 level1 的 -# sst 和 level2 种有 overlap 的 sst 进行 compaction。 -# 黄金定律：max-bytes-for-level-base 的设置的第一参考原则就是保证和 level0 的数据量大致相 -# 等，这样能够减少不必要的 compaction。例如压缩方式为"no:no:lz4:lz4:lz4:lz4:lz4"，那么 -# max-bytes-for-level-base 的值应该是 write-buffer-size 的大小乘以 4，因为 level0 和 -# level1 都没有压缩，而且 level0 触发 compaction 的条件是 sst 的个数到达 4（默认值）。在 -# level0 和 level1 都采取了压缩的情况下，就需要分析下 RocksDB 的日志，看一个 memtable 的压 -# 缩成一个 sst 文件的大小大概是多少，例如 32MB，那么 max-bytes-for-level-base 的建议值就应 -# 该是 32MB * 4 = 128MB。 -max-bytes-for-level-base = "512MB" - -# sst 文件的大小。level0 的 sst 文件的大小受 write-buffer-size 和 level0 采用的压缩算法的 -# 影响，target-file-size-base 参数用于控制 level1-level6 单个 sst 文件的大小。 -target-file-size-base = "32MB" - -# 在不配置该参数的情况下，TiKV 会将该值设置为系统总内存量的 40%。如果需要在单个物理机上部署多个 -# TiKV 节点，需要显式配置该参数，否则 TiKV 容易出现 OOM 的问题。 -# block-cache-size = "1GB"。 - -[rocksdb.writecf] -# 保持和 rocksdb.defaultcf.compression-per-level 一致。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# 保持和 rocksdb.defaultcf.write-buffer-size 一致。 -write-buffer-size = "128MB" -max-write-buffer-number = 5 -min-write-buffer-number-to-merge = 1 - -# 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。 -max-bytes-for-level-base = "512MB" -target-file-size-base = "32MB" - -# 在不配置该参数的情况下，TiKV 会将该值设置为系统总内存量的 15%。如果需要在单个物理机上部署多个 -# TiKV 节点，需要显式配置该参数。版本信息 (MVCC) 相关的数据以及索引相关的数据都记录在 write 这 -# 个 CF 里面，如果业务的场景下单表索引较多，可以将该参数设置的更大一点。 -# block-cache-size = "256MB" - -[raftdb] -# RaftDB 能够打开的最大文件句柄数。 -# max-open-files = 40960 - -# 可以通过该参数打开或者关闭 RaftDB 的统计信息。 -# enable-statistics = true - -# 开启 RaftDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。 -# compaction-readahead-size = "2MB" - -[raftdb.defaultcf] -# 保持和 rocksdb.defaultcf.compression-per-level 一致。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# 保持和 rocksdb.defaultcf.write-buffer-size 一致。 -write-buffer-size = "128MB" -max-write-buffer-number = 5 -min-write-buffer-number-to-merge = 1 - -# 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。 -max-bytes-for-level-base = "512MB" -target-file-size-base = "32MB" - -# 通常配置在 256MB 到 2GB 之间，通常情况下使用默认值就可以了，但如果系统资源比较充足可以适当调大点。 -block-cache-size = "256MB" -``` - -## TiKV 内存使用情况 - -除了以上列出的 `block-cache` 以及 `write-buffer` 会占用系统内存外： - -1. 需预留一些内存作为系统的 page cache -2. TiKV 在处理大的查询的时候（例如 `select * from ...`）会读取数据然后在内存中生成对应的数据结构返回给 TiDB，这个过程中 TiKV 会占用一部分内存 - -## TiKV 机器配置推荐 - -1. 生产环境中，不建议将 TiKV 部署在 CPU 核数小于 8 或内存低于 32GB 的机器上 -2. 如果对写入吞吐要求比较高，建议使用吞吐能力比较好的磁盘 -3. 如果对读写的延迟要求非常高，建议使用 IOPS 比较高的 SSD 盘 diff --git a/v2.1/reference/performance/understanding-the-query-execution-plan.md b/v2.1/reference/performance/understanding-the-query-execution-plan.md deleted file mode 100644 index 11369728ab87..000000000000 --- a/v2.1/reference/performance/understanding-the-query-execution-plan.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: 理解 TiDB 执行计划 -category: reference ---- - -# 理解 TiDB 执行计划 - -TiDB 优化器会根据当前数据表的实际情况来选择最优的执行计划，执行计划由一系列的算子构成。本文将详细解释 TiDB 中 `EXPLAIN` 语句返回的执行计划信息。 - -## 使用 `EXPLAIN` 来优化 SQL 语句 - -`EXPLAIN` 语句的返回结果提供了 TiDB 执行 SQL 查询的详细信息： - -- `EXPLAIN` 可以和 `SELECT`，`DELETE` 语句一起使用； -- 执行 `EXPLAIN`，TiDB 会返回被 `EXPLAIN` 的 SQL 语句经过优化器后的最终物理执行计划。也就是说，`EXPLAIN` 展示了 TiDB 执行该 SQL 语句的完整信息，比如以什么样的顺序，什么方式 JOIN 两个表，表达式树长什么样等等。详见 [`EXPLAIN` 输出格式](#explain-输出格式)； -- TiDB 支持 `EXPLAIN [options] FOR CONNECTION connection_id`，但与 MySQL 的 `EXPLAIN FOR` 有一些区别，请参见 [`EXPLAIN FOR CONNECTION`](#explain-for-connection)。 - -通过观察 `EXPLAIN` 的结果，你可以知道如何给数据表添加索引使得执行计划使用索引从而加速 SQL 语句的执行速度；你也可以使用 `EXPLAIN` 来检查优化器是否选择了最优的顺序来 JOIN 数据表。 - -## `EXPLAIN` 输出格式 - -目前 TiDB 的 `EXPLAIN` 会输出 4 列，分别是：id，count，task，operator info。执行计划中每个算子都由这 4 列属性来描述，`EXPLAIN` 结果中每一行描述一个算子。每个属性的具体含义如下： - -| 属性名 | 含义 | -|:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------| -| id | 算子的 ID，在整个执行计划中唯一的标识一个算子。在 TiDB 2.1 中，id 会格式化显示算子的树状结构。数据从 child 流向 parent，每个 算子的 parent 有且仅有一个。 | -| count | 预计当前算子将会输出的数据条数，基于统计信息以及算子的执行逻辑估算而来。 | -| task | 当前这个算子属于什么 task。目前的执行计划分成为两种 task，一种叫 **root** task，在 tidb-server 上执行，一种叫 **cop** task，并行的在 TiKV 上执行。当前的执行计划在 task 级别的拓扑关系是一个 root task 后面可以跟许多 cop task，root task 使用 cop task 的输出结果作为输入。cop task 中执行的也即是 TiDB 下推到 TiKV 上的任务，每个 cop task 分散在 TiKV 集群中，由多个进程共同执行。 | -| operator info | 每个算子的详细信息。各个算子的 operator info 各有不同，详见 [Operator Info](#operator-info)。 | - -## `EXPLAIN ANALYZE` 输出格式 - -作为 `EXPLAIN` 语句的扩展，`EXPLAIN ANALYZE` 语句执行查询并在 `execution info` 列中提供额外的执行统计信息。具体如下： - -* `time` 显示从进入算子到离开算子的全部 wall time，包括所有子算子操作的全部执行时间。如果该算子被父算子多次调用 (`loops`)，这个时间就是累积的时间。 -* `loops` 是当前算子被父算子调用的次数。 -* `rows` 是当前算子返回的行的总数。例如，可以将 `count` 列的精度和 `execution_info` 列中的 `rows`/`loops` 值进行对比，据此评定查询优化器估算的精确度。 - -### 用例 - -使用 [bikeshare example database](https://github.com/pingcap/docs/blob/master/dev/how-to/get-started/import-example-database.md): - -``` -mysql> EXPLAIN SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'; -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -| id | count | task | operator info | -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -| StreamAgg_20 | 1.00 | root | funcs:count(col_0) | -| └─TableReader_21 | 1.00 | root | data:StreamAgg_9 | -| └─StreamAgg_9 | 1.00 | cop | funcs:count(1) | -| └─Selection_19 | 8166.73 | cop | ge(bikeshare.trips.start_date, 2017-07-01 00:00:00.000000), le(bikeshare.trips.start_date, 2017-07-01 23:59:59.000000) | -| └─TableScan_18 | 19117643.00 | cop | table:trips, range:[-inf,+inf], keep order:false | -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -5 rows in set (0.00 sec) -``` - -在上面的例子中，coprocessor 上读取 `trips` 表上的数据（`TableScan_18`），寻找满足 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 条件的数据（`Selection_19`），然后计算满足条件的数据行数（`StreamAgg_9`），最后把结果返回给 TiDB。TiDB 汇总各个 coprocessor 返回的结果（`TableReader_21`），并进一步计算所有数据的行数（`StreamAgg_20`），最终把结果返回给客户端。在上面这个查询中，TiDB 根据 `trips` 表的统计信息估算出 `TableScan_18` 的输出结果行数为 19117643.00，满足条件 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 的有 `8166.73` 条，经过聚合运算后，只有 1 条结果。 - -上述查询中，虽然大部分计算逻辑都下推到了 TiKV 的 coprocessor 上，但是其执行效率还是不够高，可以添加适当的索引来消除 `TableScan_18` 对 `trips` 的全表扫，进一步加速查询的执行： - -```sql -mysql> ALTER TABLE trips ADD INDEX (start_date); -.. -mysql> EXPLAIN SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'; -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -| id | count | task | operator info | -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -| StreamAgg_25 | 1.00 | root | funcs:count(col_0) | -| └─IndexReader_26 | 1.00 | root | index:StreamAgg_9 | -| └─StreamAgg_9 | 1.00 | cop | funcs:count(1) | -| └─IndexScan_24 | 8166.73 | cop | table:trips, index:start_date, range:[2017-07-01 00:00:00,2017-07-01 23:59:59], keep order:false | -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -4 rows in set (0.01 sec) -``` - -在添加完索引后的新执行计划中，使用 `IndexScan_24` 直接读取满足条件 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 的数据，可以看到，估算的要扫描的数据行数从之前的 `19117643.00` 降到了现在的 `8166.73`。在测试环境中显示，这个查询的执行时间从 50.41 秒降到了 0.01 秒！ - -## `EXPLAIN FOR CONNECTION` - -`EXPLAIN FOR CONNECTION` 用于获得一个连接中最后执行的查询的执行计划，其输出格式与 `EXPLAIN` 完全一致。但 TiDB 中的实现与 MySQL 不同，除了输出格式之外，还有以下区别： - -- MySQL 返回的是**正在执行**的查询计划，而 TiDB 返回的是**最后执行**的查询计划。 -- MySQL 的文档中指出，MySQL 要求登录用户与被查询的连接相同，或者拥有 `PROCESS` 权限，而 TiDB 则要求登录用户与被查询的连接相同，或者拥有 `SUPER` 权限。 - -## 概述 - -### Task 简介 - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指使用 TiKV 中的 coprocessor 执行的计算任务，root task 是指在 TiDB 中执行的计算任务。 - -SQL 优化的目标之一是将计算尽可能地下推到 TiKV 中执行。TiKV 中的 coprocessor 能支持大部分 SQL 内建函数（包括聚合函数和标量函数）、SQL `LIMIT` 操作、索引扫描和表扫描。但是，所有的 Join 操作都只能作为 root task 在 TiDB 上执行。 - -### 表数据和索引数据 - -TiDB 的表数据是指一张表的原始数据，存放在 TiKV 中。对于每行表数据，它的 key 是一个 64 位整数，称为 Handle ID。如果一张表存在 int 类型的主键，TiDB 会把主键的值当作表数据的 Handle ID，否则由系统自动生成 Handle ID。表数据的 value 由这一行的所有数据编码而成。在读取表数据的时候，可以按照 Handle ID 递增的顺序返回。 - -TiDB 的索引数据和表数据一样，也存放在 TiKV 中。它的 key 是由索引列编码的有序 bytes，value 是这一行索引数据对应的 Handle ID，通过 Handle ID 可以读取这一行的非索引列。在读取索引数据的时候，TiKV 会按照索引列递增的顺序返回，如果有多个索引列，首先保证第 1 列递增，并且在第 i 列相等的情况下，保证第 i + 1 列递增。 - -### 范围查询 - -在 WHERE/HAVING/ON 条件中，TiDB 优化器会分析主键或索引键的查询返回。如数字、日期类型的比较符，如大于、小于、等于以及大于等于、小于等于，字符类型的 LIKE 符号等。 - -值得注意的是，TiDB 目前只支持比较符一端是列，另一端是常量，或可以计算成某一常量的情况，类似 `year(birth_day) < 1992` 的查询条件是不能利用索引的。还要注意应尽可能使用同一类型进行比较，以避免引入额外的 cast 操作而导致不能利用索引，如 `user_id = 123456`，如果 `user_id` 是字符串，需要将 `123456` 也写成字符串常量的形式。 - -针对同一列的范围查询条件使用 `AND` 和 `OR` 组合后，等于对范围求交集或者并集。对于多维组合索引，可以写多个列的条件。例如对组合索引`(a, b, c)`，当 a 为等值查询时，可以继续求 b 的查询范围，当 b 也为等值查询时，可以继续求 c 的查询范围，反之如果 a 为非等值查询，则只能求 a 的范围。 - -## Operator Info - -### TableReader 和 TableScan - -TableScan 表示在 KV 端对表数据进行扫描，TableReader 表示在 TiDB 端从 TiKV 端读取，属于同一功能的两个算子。table 表示 SQL 语句中的表名，如果表名被重命名，则显示重命名。range 表示扫描的数据范围，如果在查询中不指定 WHERE/HAVING/ON 条件，则会选择全表扫描，如果在 int 类型的主键上有范围查询条件，会选择范围查询。keep order 表示 table scan 是否按顺序返回。 - -### IndexReader 和 IndexLookUp - -Index 在 TiDB 端的读取方式有两种：IndexReader 表示直接从索引中读取索引列，适用于 SQL 语句中仅引用了该索引相关的列或主键；IndexLookUp 表示从索引中过滤部分数据，仅返回这些数据的 Handle ID，通过 Handle ID 再次查找表数据，这种方式需要两次从 TiKV 获取数据。Index 的读取方式是由优化器自动选择的。 - -IndexScan 是 KV 端读取索引数据的算子，和 TableScan 功能类似。table 表示 SQL 语句中的表名，如果表名被重命名，则显示重命名。index 表示索引名。range 表示扫描的数据范围。out of order 表示 index scan 是否按照顺序返回。注意在 TiDB 中，多列或者非 int 列构成的主键是当作唯一索引处理的。 - -### Selection - -Selection 表示 SQL 语句中的选择条件，通常出现在 WHERE/HAVING/ON 子句中。 - -### Projection - -Projection 对应 SQL 语句中的 SELECT 列表，功能是将每一条输入数据映射成新的输出数据。 - -### Aggregation - -Aggregation 对应 SQL 语句中的 Group By 语句或者没有 Group By 语句但是存在聚合函数，例如 count 或 sum 函数等。TiDB 支持两种聚合算法：Hash Aggregation 以及 Stream Aggregation（待补充）。Hash Aggregation 是基于哈希的聚合算法，如果 Hash Aggregation 紧邻 Table 或者 Index 的读取算子，则聚合算子会在 TiKV 端进行预聚合，以提高计算的并行度和减少网络开销。 - -### Join - -TiDB 支持 Inner Join 以及 Left/Right Outer Join，并会自动将可以化简的外连接转换为 Inner Join。 - -TiDB 支持三种 Join 算法：Hash Join，Sort Merge Join 和 Index Look up Join。Hash Join 的原理是将参与连接的小表预先装载到内存中，读取大表的所有数据进行连接。Sort Merge Join 会利用输入数据的有序信息，同时读取两张表的数据并依次进行比较。Index Look Up Join 会读取外表的数据，并对内表进行主键或索引键查询。 - -### Apply - -Apply 是 TiDB 用来描述子查询的一种算子，行为类似于 Nested Loop，即每次从外表中取一条数据，带入到内表的关联列中，并执行，最后根据 Apply 内联的 Join 算法进行连接计算。 - -值得注意的是，Apply 一般会被查询优化器自动转换为 Join 操作。用户在编写 SQL 的过程中应尽量避免 Apply 算子的出现。 diff --git a/v2.1/reference/security/compatibility.md b/v2.1/reference/security/compatibility.md deleted file mode 100644 index 77227fdfb3e8..000000000000 --- a/v2.1/reference/security/compatibility.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 与 MySQL 安全特性差异 -category: reference ---- - -# 与 MySQL 安全特性差异 - -除以下功能外，TiDB 支持与 MySQL 5.7 类似的安全特性。 - -- 仅支持 `mysql_native_password` 身份验证方案。 -- 不支持外部身份验证方式（如 LDAP）。 -- 不支持列级别权限设置。 -- 不支持使用证书验证身份。[#9708](https://github.com/pingcap/tidb/issues/9708) -- 不支持密码过期，最后一次密码变更记录以及密码生存期。[#9709](https://github.com/pingcap/tidb/issues/9709) -- 不支持权限属性 `max_questions`，`max_updated`，`max_connections` 以及 `max_user_connections`。 -- 不支持密码验证。[#9741](https://github.com/pingcap/tidb/issues/9741) -- 不支持透明数据加密（TDE）。 diff --git a/v2.1/reference/security/privilege-system.md b/v2.1/reference/security/privilege-system.md deleted file mode 100644 index bbfa9b76ee36..000000000000 --- a/v2.1/reference/security/privilege-system.md +++ /dev/null @@ -1,481 +0,0 @@ ---- -title: 权限管理 -category: reference ---- - -# 权限管理 - -TiDB 的权限管理系统按照 MySQL 的权限管理进行实现，TiDB 支持大部分的 MySQL 的语法和权限类型。 - -本文档主要介绍 TiDB 权限相关操作、各项操作需要的权限以及权限系统的实现。 - -## 权限相关操作 - -### 授予权限 - -授予 `xxx` 用户对数据库 `test` 的读权限： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO 'xxx'@'%'; -``` - -为 `xxx` 用户授予所有数据库，全部权限： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'xxx'@'%'; -``` - -`GRANT` 为一个不存在的用户授予权限时，默认并不会自动创建用户。该行为受 SQL Mode 中的 `NO_AUTO_CREATE_USER` 控制。 -如果从 SQL Mode 中去掉 `NO_AUTO_CREATE_USER`，当 `GRANT` 的目标用户不存在时，TiDB 会自动创建用户。 - -{{< copyable "sql" >}} - -```sql -mysql> select @@sql_mode; -``` - -```+-------------------------------------------------------------------------------------------------------------------------------------------+ -| @@sql_mode | -+-------------------------------------------------------------------------------------------------------------------------------------------+ -| ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@sql_mode='ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM mysql.user WHERE user='xxxx'; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON test.* TO 'xxxx'@'%' IDENTIFIED BY 'yyyyy'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT user,host FROM mysql.user WHERE user='xxxx'; -``` - -``` -+------|------+ -| user | host | -+------|------+ -| xxxx | % | -+------|------+ -1 row in set (0.00 sec) -``` - -上述示例中，`xxxx@%` 即自动添加的用户。 - -`GRANT` 对于数据库或者表的授权，不检查数据库或表是否存在。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM test.xxxx; -``` - -``` -ERROR 1146 (42S02): Table 'test.xxxx' doesn't exist -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON test.xxxx TO xxxx; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -mysql> SELECT user,host FROM mysql.tables_priv WHERE user='xxxx'; -``` - -``` -+------|------+ -| user | host | -+------|------+ -| xxxx | % | -+------|------+ -1 row in set (0.00 sec) -``` - -`GRANT` 可以模糊匹配地授予数据库和表： - -{{< copyable "sql" >}} - -```sql -mysql> GRANT ALL PRIVILEGES ON `te%`.* TO genius; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT user,host,db FROM mysql.db WHERE user='genius'; -``` - -``` -+--------|------|-----+ -| user | host | db | -+--------|------|-----+ -| genius | % | te% | -+--------|------|-----+ -1 row in set (0.00 sec) -``` - -这个例子中通过 `%` 模糊匹配，所有 `te` 开头的数据库，都被授予了权限。 - -### 收回权限 - -`REVOKE` 语句与 `GRANT` 对应： - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `test`.* FROM 'genius'@'localhost'; -``` - -> **注意：** -> -> `REVOKE` 收回权限时只做精确匹配，若找不到记录则报错。而 `GRANT` 授予权限时可以使用模糊匹配。 - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `te%`.* FROM 'genius'@'%'; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'genius' on host '%' -``` - -关于模糊匹配和转义，字符串和 identifier： - -{{< copyable "sql" >}} - -```sql -mysql> GRANT ALL PRIVILEGES ON `te\%`.* TO 'genius'@'localhost'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -上述例子是精确匹配名为 `te%` 的数据库，注意使用 `\` 转义字符。 - -以单引号包含的部分，是一个字符串。以反引号包含的部分，是一个 identifier。注意下面的区别： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON 'test'.* TO 'genius'@'localhost'; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the -manual that corresponds to your MySQL server version for the right -syntax to use near ''test'.* to 'genius'@'localhost'' at line 1 -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON `test`.* TO 'genius'@'localhost'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -如果想将一些特殊的关键字做为表名，可以用反引号包含起来。比如： - -{{< copyable "sql" >}} - -```sql -mysql> CREATE TABLE `select` (id int); -``` - -``` -Query OK, 0 rows affected (0.27 sec) -``` - -### 查看为用户分配的权限 - -`SHOW GRANTS` 语句可以查看为用户分配了哪些权限。例如： - -查看当前用户的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS; -``` - -查看某个特定用户的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS for 'root'@'%'; -``` - -更精确的方式，可以通过直接查看授权表的数据实现。比如想知道，名为 `test@%` 的用户是否拥有对 `db1.t` 的 `Insert` 权限： - -1. 先查看该用户是否拥有全局 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT Insert_priv FROM mysql.user WHERE user='test' AND host='%'; - ``` - -2. 如果没有，再查看该用户是否拥有 `db1` 数据库级别的 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT Insert_priv FROM mysql.db WHERE user='test' AND host='%'; - ``` - -3. 如果仍然没有，则继续判断是否拥有 `db1.t` 这张表的 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT table_priv FROM mysql.tables_priv WHERE user='test' AND host='%' AND db='db1'; - ``` - -## TiDB 各操作需要的权限 - -TiDB 用户目前拥有的权限可以在 `INFORMATION_SCHEMA.USER_PRIVILEGES` 表中查找到。 - -| 权限类型 | 权限变量名 | 权限简述 | -| :------------ | :------------ | :---------------------- | -| ALL | AllPriv | 所有权限 | -| Drop | DropPriv | 删除 schema/table | -| Index | IndexPriv | 创建/删除 index | -| Alter | AlterPriv | 执行 `ALTER` 语句 | -| Super | SuperPriv | 所有权限 | -| Grant | GrantPriv | 授予其他用户权限 | -| Create | CreatePriv | 创建 schema/table | -| Select | SelectPriv | 读取表内容 | -| Insert | InsertPriv | 插入数据到表 | -| Update | UpdatePriv | 更新表中数据 | -| Delete | DeletePriv | 删除表中数据 | -| Trigger | TriggerPriv | 尚未使用 | -| Process | ProcessPriv | 显示正在运行的任务 | -| Execute | ExecutePriv | 执行 execute 语句 | -| Drop Role | DropRolePriv | 执行 drop role | -| Show View | ShowViewPriv | 执行 show create view | -| References | ReferencesPriv | 尚未使用 | -| Create View | CreateViewPriv | 创建视图 | -| Create User | CreateUserPriv | 创建用户 | -| Create Role | CreateRolePriv | 执行 create role | -| Show Databases | ShowDBPriv | 显示 database 内的表情况 | - -### ALTER - -- 对于所有的 `ALTER` 语句，均需要用户对所操作的表拥有 `ALTER` 权限。 -- 除 `ALTER...DROP` 和 `ALTER...RENAME TO` 外，均需要对所操作表拥有 `INSERT` 和 `CREATE` 权限。 -- 对于 `ALTER...DROP` 语句，需要对表拥有 `DROP` 权限。 -- 对于 `ALTER...RENAME TO` 语句，需要对重命名前的表拥有 `DROP` 权限，对重命名后的表拥有 `CREATE` 和 `INSERT` 权限。 - -> **注意：** -> -> 根据 MySQL 5.7 文档中的说明，对表进行 `ALTER` 操作需要 `INSERT` 和 `CREATE` 权限，但在 MySQL 5.7.25 版本实际情况中，该操作仅需要 `ALTER` 权限。目前，TiDB 中的 `ALTER` 权限与 MySQL 实际行为保持一致。 - -### CREATE DATABASE - -需要对数据库拥有 `CREATE` 权限。 - -### CREATE INDEX - -需要对所操作的表拥有 `INDEX` 权限。 - -### CREATE TABLE - -需要对所操作的表拥有 `CREATE` 权限；若使用 `CREATE TABLE...LIKE...` 需要对相关的表拥有 `SELECT` 权限。 - -### CREATE VIEW - -需要拥有 `CREATE VIEW` 权限。 - -> **注意：** -> -> 如果当前登录用户与创建视图的用户不同，除需要 `CREATE VIEW` 权限外，还需要 `SUPER` 权限。 - -### DROP DATABASE - -需要对数据库拥有 `DROP` 权限。 - -### DROP INDEX - -需要对所操作的表拥有 `INDEX` 权限。 - -### DROP TABLES - -需要对所操作的表拥有 `DROP` 权限。 - -### TRUNCATE TABLE - -需要对所操作的表拥有 `DROP` 权限。 - -### RENAME TABLE - -需要对重命名前的表拥有 `ALTER` 和 `DROP` 权限，对重命名后的表拥有 `CREATE` 和 `INSERT` 权限。 - -### ANALYZE TABLE - -需要对所操作的表拥有 `INSERT` 和 `SELECT` 权限。 - -### SHOW - -`SHOW CREATE TABLE` 需要任意一种权限。 - -`SHOW CREATE VIEW` 需要 `SHOW VIEW` 权限。 - -### CREATE ROLE/USER - -`CREATE ROLE` 需要 `CREATE ROLE` 权限。 - -`CREATE USER` 需要 `CREATE USER` 权限 - -### DROP ROLE/USER - -`DROP ROLE` 需要 `DROPROLE` 权限。 - -`DROP USER` 需要 `CREATEUSER` 权限 - -### ALTER USER - -`ALTER USER` 需要 `CREATEUSER` 权限。 - -### GRANT - -`GRANT` 需要 `GRANT` 权限并且拥有 `GRANT` 所赋予的权限。 - -### REVOKE - -`REVOKE` 需要 `SUPER` 权限。 - -## 权限系统的实现 - -### 授权表 - -以下几张系统表是非常特殊的表，权限相关的数据全部存储在这几张表内。 - -- `mysql.user`：用户账户，全局权限 -- `mysql.db`：数据库级别的权限 -- `mysql.tables_priv`：表级别的权限 -- `mysql.columns_priv`：列级别的权限，当前暂不支持 - -这几张表包含了数据的生效范围和权限信息。例如，`mysql.user` 表的部分数据： - -{{< copyable "sql" >}} - -```sql -SELECT User,Host,Select_priv,Insert_priv FROM mysql.user LIMIT 1; -``` - -``` -+------|------|-------------|-------------+ -| User | Host | Select_priv | Insert_priv | -+------|------|-------------|-------------+ -| root | % | Y | Y | -+------|------|-------------|-------------+ -1 row in set (0.00 sec) -``` - -这条记录中，`Host` 和 `User` 决定了 root 用户从任意主机 (%) 发送过来的连接请求可以被接受，而 `Select_priv` 和 `Insert_priv` 表示用户拥有全局的 `Select` 和 `Insert` 权限。`mysql.user` 这张表里面的生效范围是全局的。 - -`mysql.db` 表里面包含的 `Host` 和 `User` 决定了用户可以访问哪些数据库，权限列的生效范围是数据库。 - -理论上，所有权限管理相关的操作，都可以通过直接对授权表的 CRUD 操作完成。 - -实现层面其实也只是包装了一层语法糖。例如删除用户会执行： - -{{< copyable "sql" >}} - -```sql -DELETE FROM mysql.user WHERE user='test'; -``` - -但是，不推荐手动修改授权表，建议使用 `DROP USER` 语句： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'; -``` - -### 连接验证 - -当客户端发送连接请求时，TiDB 服务器会对登录操作进行验证。验证过程先检查 `mysql.user` 表，当某条记录的 `User` 和 `Host` 和连接请求匹配上了，再去验证 Password。用户身份基于两部分信息，发起连接的客户端的 `Host`，以及用户名 `User`。如果 `User` 不为空，则用户名必须精确匹配。 - -User+Host 可能会匹配 `user` 表里面多行，为了处理这种情况，`user` 表的行是排序过的，客户端连接时会依次去匹配，并使用首次匹配到的那一行做权限验证。排序是按 `Host` 在前，`User` 在后。 - -### 请求验证 - -连接成功之后，请求验证会检测执行操作是否拥有足够的权限。 - -对于数据库相关请求 (`INSERT`，`UPDATE`)，先检查 `mysql.user` 表里面的用户全局权限，如果权限够，则直接可以访问。如果全局权限不足，则再检查 `mysql.db` 表。 - -`user` 表的权限是全局的，并且不管默认数据库是哪一个。比如 `user` 里面有 `DELETE` 权限，任何一行，任何的表，任何的数据库。 - -`db`表里面，User 为空是匹配匿名用户，User 里面不能有通配符。Host 和 Db 列里面可以有 `%` 和 `_`，可以模式匹配。 - -`user` 和 `db` 读到内存也是排序的。 - -`tables_priv` 和 `columns_priv` 中使用 `%` 是类似的，但是在`Db`, `Table_name`, `Column_name` 这些列不能包含 `%`。加载进来时排序也是类似的。 - -### 生效时机 - -TiDB 启动时，将一些权限检查的表加载到内存，之后使用缓存的数据来验证权限。系统会周期性的将授权表从数据库同步到缓存，生效则是由同步的周期决定，目前这个值设定的是 5 分钟。 - -修改了授权表，如果需要立即生效，可以手动调用： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -### 限制和约束 - -一些使用频率偏低的权限当前版本的实现中还未做检查，比如 `FILE`/`USAGE`/`SHUTDOWN`/`EXECUTE`/`PROCESS`/`INDEX` 等等，未来会陆续完善。 - -现阶段对权限的支持还没有做到 column 级别。 diff --git a/v2.1/reference/security/user-account-management.md b/v2.1/reference/security/user-account-management.md deleted file mode 100644 index 045488e649af..000000000000 --- a/v2.1/reference/security/user-account-management.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: TiDB 用户账户管理 -category: reference ---- - -# TiDB 用户账户管理 - -本文档主要介绍如何管理 TiDB 用户账户。 - -## 用户名和密码 - -TiDB 将用户账户存储在 `mysql.user` 系统表里面。每个账户由用户名和 host 作为标识。每个账户可以设置一个密码。 - -通过 MySQL 客户端连接到 TiDB 服务器，通过指定的账户和密码登录： - -{{< copyable "shell-regular" >}} - -``` -mysql --port 4000 --user xxx --password -``` - -使用缩写的命令行参数则是： - -{{< copyable "shell-regular" >}} - -``` -mysql -P 4000 -u xxx -p -``` - -## 添加用户 - -添加用户有两种方式： - -* 通过标准的用户管理的 SQL 语句创建用户以及授予权限，比如 `CREATE USER` 和 `GRANT`。 -* 直接通过 `INSERT`、`UPDATE` 和 `DELETE` 操作授权表。 - -推荐使用第一种方式。第二种方式修改容易导致一些不完整的修改，因此不推荐。还有另一种可选方式是使用第三方工具的图形化界面工具。 - -{{< copyable "sql" >}} - -```sql -CREATE USER [IF NOT EXISTS] - user [auth_spec] [, user [auth_spec]] ... -``` - -{{< copyable "sql" >}} - -```sql -auth_spec: { - IDENTIFIED BY 'auth_string' - | IDENTIFIED BY PASSWORD 'hash_string' -} -``` - -* `IDENTIFIED BY 'auth_string'`：设置登录密码时，`auth_string` 会被 TiDB 经过加密存储在 `mysql.user` 表中。 -* `IDENTIFIED BY PASSWORD 'hash_string'`：设置登录密码，`hash_string` 是一个类似于 `*EBE2869D7542FCE37D1C9BBC724B97BDE54428F1` 的 41 位字符串，会被 TiDB 直接存储在 `mysql.user` 表中，该字符串可以通过 `SELECT password('auth_string')` 加密得到。 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'127.0.0.1' IDENTIFIED BY 'xxx'; -``` - -TiDB 的用户账户名由一个用户名和一个主机名组成。账户名的语法为 `'user_name'@'host_name'`。 - -- `user_name` 大小写敏感。 -- `host_name` 可以是一个主机名或 IP 地址。主机名或 IP 地址中允许使用通配符 `%` 和 `_`。例如，名为 `'%'` 的主机名可以匹配所有主机，`'192.168.1.%'` 可以匹配子网中的所有主机。 - -host 支持模糊匹配，比如： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'192.168.10.%'; -``` - -允许 `test` 用户从 `192.168.10` 子网的任何一个主机登录。 - -如果没有指定 host，则默认是所有 IP 均可登录。如果没有指定密码，默认为空： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'; -``` - -等价于： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'%' IDENTIFIED BY ''; -``` - -下面的例子用 `CREATE USER` 和 `GRANT` 语句创建了四个账户： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'localhost' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'localhost' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'%' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'%' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'dummy'@'localhost'; -``` - -使用 `SHOW GRANTS` 可以看到为一个用户授予的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'admin'@'localhost'; -``` - -``` -+-----------------------------------------------------+ -| Grants for admin@localhost | -+-----------------------------------------------------+ -| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' | -+-----------------------------------------------------+ -``` - -## 删除用户 - -使用 `DROP USER` 语句可以删除用户，例如： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'@'localhost'; -``` - -这个操作会清除用户在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录。 - -## 保留用户账户 - -TiDB 在数据库初始化时会生成一个 `'root'@'%'` 的默认账户。 - -## 设置资源限制 - -暂不支持。 - -## 设置密码 - -TiDB 将密码存在 `mysql.user` 系统数据库里面。只有拥有 `CREATE USER` 权限，或者拥有 `mysql` 数据库权限（`INSERT` 权限用于创建，`UPDATE` 权限用于更新）的用户才能够设置或修改密码。 - -- 在 `CREATE USER` 创建用户时可以通过 `IDENTIFIED BY` 指定密码： - - {{< copyable "sql" >}} - - ```sql - CREATE USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -- 为一个已存在的账户修改密码，可以通过 `SET PASSWORD FOR` 或者 `ALTER USER` 语句完成： - - {{< copyable "sql" >}} - - ```sql - SET PASSWORD FOR 'root'@'%' = 'xxx'; - ``` - - 或者： - - {{< copyable "sql" >}} - - ```sql - ALTER USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -## 忘记 `root` 密码 - -1. 修改配置文件，在 `security` 部分添加 `skip-grant-table`： - - {{< copyable "" >}} - - ``` - [security] - skip-grant-table = true - ``` - -2. 然后使用 `root` 登录后修改密码： - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -## `FLUSH PRIVILEGES` - -如果授权表已被直接修改，运行如下命令可使改动立即生效： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -详情参见[权限管理](/v2.1/reference/security/privilege-system.md)。 diff --git a/v2.1/reference/sql/character-set.md b/v2.1/reference/sql/character-set.md deleted file mode 100644 index 7d41470911fb..000000000000 --- a/v2.1/reference/sql/character-set.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: 字符集支持 -category: reference ---- - -# 字符集支持 - -名词解释，下面的阐述中会交错使用中文或者英文，请互相对照： - -* Character Set：字符集 -* Collation：排序规则 - -目前 `TiDB` 支持以下字符集： - -```sql -mysql> SHOW CHARACTER SET; -+---------|---------------|-------------------|--------+ -| Charset | Description | Default collation | Maxlen | -+---------|---------------|-------------------|--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------|---------------|-------------------|--------+ -5 rows in set (0.00 sec) -``` - -对于字符集来说，至少会有一个 Collation（排序规则）与之对应。而大部分字符集实际上会有多个 Collation。利用以下的语句可以查看： - -```sql -mysql> SHOW COLLATION WHERE Charset = 'latin1'; -+-------------------|---------|------|---------|----------|---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+-------------------|---------|------|---------|----------|---------+ -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -+-------------------|---------|------|---------|----------|---------+ -8 rows in set (0.00 sec) -``` - -`latin1` Collation（排序规则）分别有以下含义： - -| Collation | 含义 | -|:------------------|:----------------------------------| -| latin1_bin | latin1 编码的二进制表示 | -| latin1_danish_ci | 丹麦语/挪威语，不区分大小写 | -| latin1_general_ci | 多种语言的 (西欧)，不区分大小写 | -| latin1_general_cs | 多种语言的 (ISO 西欧)，区分大小写 | -| latin1_german1_ci | 德国 DIN-1 (字典序)，不区分大小写 | -| latin1_german2_ci | 德国 DIN-2，不区分大小写 | -| latin1_spanish_ci | 现代西班牙语，不区分大小写 | -| latin1_swedish_ci | 瑞典语/芬兰语，不区分大小写 | - -每一个字符集，都有一个默认的 Collation，例如 `utf8` 的默认 Collation 就为 `utf8_bin`。 - -> **注意：** -> -> `TiDB` 目前的 Collation 都是区分大小写的。 - -## Collation 命名规则 - -`TiDB` 的 Collation 遵循着如下的命名规则： - -* Collation 的前缀是它相应的字符集，通常之后会跟着一个或者更多的后缀来表名其他的排序规则， 例如：utf8_general_ci 和 lation1_swedish_ci 是 utf8 - 和 latin1 字符集的 Collation。但是 binary 字符集只有一个 Collation，就是 binary。 -* 一个语言对应的 Collation 会包含语言的名字，例如 utf8_turkish_ci 和 utf8_hungarian_ci 是依据 Turkish(土耳其语) 和 Hungarian(匈牙利语) 的排序规则来排序。 -* Collation 的后缀表示了 Collation 是否区分大小写和是否区分口音。下面的表展示了这些特性： - -| 后缀 | 含义 | -|:-----|:---------------------------------| -| \_ai | 口音不敏感（Accent insensitive） | -| \_as | 口音敏感 （Accent sensitive） | -| \_ci | 大小写不敏感 | -| \_cs | 大小写敏感 | - -> **注意：** -> -> 目前为止 TiDB 只支持部分以上提到的 Collation。 - -## 数据库 Character Set 和 Collation - -每个数据库都有相应的 Character Set 和 Collation，数据库的 Character Set 和 Collation 可以通过以下语句来设置： - -```sql -CREATE DATABASE db_name - [[DEFAULT] CHARACTER SET charset_name] - [[DEFAULT] COLLATE collation_name] - -ALTER DATABASE db_name - [[DEFAULT] CHARACTER SET charset_name] - [[DEFAULT] COLLATE collation_name] -``` - -在这里 `DATABASE` 可以跟 `SCHEMA` 互换使用。 - -不同的数据库之间可以使用不一样的字符集和排序规则。 - -通过系统变量 `character_set_database` 和 `collation_database` 可以查看到当前数据库的字符集以及排序规则： - -```sql -mysql> create schema test1 character set utf8 COLLATE uft8_general_ci; -Query OK, 0 rows affected (0.09 sec) - -mysql> use test1; -Database changed -mysql> SELECT @@character_set_database, @@collation_database; -+--------------------------|----------------------+ -| @@character_set_database | @@collation_database | -+--------------------------|----------------------+ -| utf8 | uft8_general_ci | -+--------------------------|----------------------+ -1 row in set (0.00 sec) - -mysql> create schema test2 character set latin1 COLLATE latin1_general_ci; -Query OK, 0 rows affected (0.09 sec) - -mysql> use test2; -Database changed -mysql> SELECT @@character_set_database, @@collation_database; -+--------------------------|----------------------+ -| @@character_set_database | @@collation_database | -+--------------------------|----------------------+ -| latin1 | latin1_general_ci | -+--------------------------|----------------------+ -1 row in set (0.00 sec) -``` - -在 INFORMATION_SCHEMA 中也可以查看到这两个值： - -```sql -SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME -FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = 'db_name'; -``` - -## 表的 Character Set 和 Collation - -表的 Character Set 和 Collation 可以通过以下语句来设置： - -```sql -CREATE TABLE tbl_name (column_list) - [[DEFAULT] CHARACTER SET charset_name] - [COLLATE collation_name]] - -ALTER TABLE tbl_name - [[DEFAULT] CHARACTER SET charset_name] - [COLLATE collation_name] -``` - -例如： - -```sql -mysql> CREATE TABLE t1(a int) CHARACTER SET utf8 COLLATE utf8_general_ci; -Query OK, 0 rows affected (0.08 sec) -``` - -如果表的字符集和排序规则没有设置，那么数据库的字符集和排序规则就作为其默认值。 - -## 列的 Character Set 和 Collation - -列的 Character Set 和 Collation 的语法如下： - -```sql -col_name {CHAR | VARCHAR | TEXT} (col_length) - [CHARACTER SET charset_name] - [COLLATE collation_name] - -col_name {ENUM | SET} (val_list) - [CHARACTER SET charset_name] - [COLLATE collation_name] -``` - -如果列的字符集和排序规则没有设置，那么表的字符集和排序规则就作为其默认值。 - -## 客户端连接的 Character Sets 和 Collations - -* 服务器的字符集和排序规则可以通过系统变量 `character_set_server` 和 `collation_server` 获取。 -* 数据库的字符集和排序规则可以通过环境变量 `character_set_database` 和 `collation_database` 获取。 - -对于每一个客户端的连接，也有相应的变量表示字符集和排序规则：`character_set_connection` 和 `collation_connection`。 - -`character_set_client` 代表客户端的字符集。在返回结果前，服务端会把结果根据 `character_set_results` 转换成对应的字符集。包括结果的元信息等。 - -可以用以下的语句来影响这些跟客户端相关的字符集变量： - -* `SET NAMES 'charset_name' [COLLATE 'collation_name']` - -`SET NAMES` 用来设定客户端会在之后的请求中使用的字符集。`SET NAMES utf8` 表示客户端会在接下来的请求中，都使用 utf8 字符集。服务端也会在之后返回结果的时候使用 utf8 字符集。 -`SET NAMES 'charset_name'` 语句其实等于下面语句的组合： - -``` -SET character_set_client = charset_name; -SET character_set_results = charset_name; -SET character_set_connection = charset_name; - -``` - -`COLLATE` 是可选的，如果没有提供，将会用 charset_name 默认的 Collation。 - -* `SET CHARACTER SET 'charset_name'` - -跟 `SET NAMES` 类似，等价于下面语句的组合： - -``` -SET character_set_client = charset_name; -SET character_set_results = charset_name; -SET collation_connection = @@collation_database; - -``` - -## 字符合法性检查 - -当指定的字符集为 utf8 或 utf8mb4 时，TiDB 仅支持合法的 utf8 字符。对于不合法的字符，会报错：`incorrect utf8 value`。该字符合法性检查与 MySQL 8.0 兼容，与 MySQL 5.7 及以下版本不兼容。 - -如果不希望报错，可以通过 `set @@tidb_skip_utf8_check=1;` 跳过字符检查。 - -更多细节，参考 [Connection Character Sets and Collations](https://dev.mysql.com/doc/refman/5.7/en/charset-connection.html)。 diff --git a/v2.1/reference/sql/constraints.md b/v2.1/reference/sql/constraints.md deleted file mode 100644 index 9d2050ae2054..000000000000 --- a/v2.1/reference/sql/constraints.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: 约束 -category: reference ---- - -# 约束 - -TiDB 支持的基本约束与 MySQL 的基本相同，但有以下区别： - -- 默认对唯一约束进行[惰性检查](/v2.1/reference/transactions/overview.md#事务的惰性检查)。通过在事务提交时再进行批量检查，TiDB 能够减少网络开销、提升性能。您可通过设置 `tidb_constraint_check_in_place` 为 `TRUE` 改变此行为。 - -- TiDB 支持创建外键约束，但不会在 DML 语句中对外键进行约束（即外键约束不生效）。 - -## 外键约束 - -目前，TiDB 支持创建外键。例如： - -``` -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - doc JSON -); -CREATE TABLE orders ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - user_id INT NOT NULL, - doc JSON, - FOREIGN KEY fk_user_id (user_id) REFERENCES users(id) -); -mysql> SELECT table_name, column_name, constraint_name, referenced_table_name, referenced_column_name -FROM information_schema.key_column_usage WHERE table_name IN ('users', 'orders'); -+------------+-------------+-----------------+-----------------------+------------------------+ -| table_name | column_name | constraint_name | referenced_table_name | referenced_column_name | -+------------+-------------+-----------------+-----------------------+------------------------+ -| users | id | PRIMARY | NULL | NULL | -| orders | id | PRIMARY | NULL | NULL | -| orders | user_id | fk_user_id | users | id | -+------------+-------------+-----------------+-----------------------+------------------------+ -3 rows in set (0.00 sec) -``` - -TiDB 也支持使用 `ALTER TABLE` 命令来删除外键（`DROP FOREIGN KEY`）和添加外键（`ADD FOREIGN KEY`）： - -``` -ALTER TABLE orders DROP FOREIGN KEY fk_user_id; -ALTER TABLE orders ADD FOREIGN KEY fk_user_id (user_id) REFERENCES users(id); -``` - -### 注意 - -* TiDB 支持外键是为了在将其他数据库迁移到 TiDB 时，不会因为此语法报错。但是，TiDB 不会在 DML 语句中对外键进行约束。例如，即使 `users` 表中不存在 `id=123` 的记录，下列事务也能提交成功： - - ``` - START TRANSACTION; - INSERT INTO orders (user_id, doc) VALUES (123, NULL); - COMMIT; - ``` - -* TiDB 在执行 `SHOW CREATE TABLE` 语句的结果中不显示外键信息。 - -## 非空约束 - -TiDB 支持的非空约束规则与 MySQL 支持的一致。例如： - -``` -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - age INT NOT NULL, - last_login TIMESTAMP -); -mysql> INSERT INTO users (id,age,last_login) VALUES (NULL,123,NOW()); -Query OK, 1 row affected (0.02 sec) -mysql> INSERT INTO users (id,age,last_login) VALUES (NULL,NULL,NOW()); -ERROR 1048 (23000): Column 'age' cannot be null -mysql> INSERT INTO users (id,age,last_login) VALUES (NULL,123,NULL); -Query OK, 1 row affected (0.03 sec) -``` - -* 第一条 `INSERT` 语句成功，因为对于定义为 `AUTO_INCREMENT` 的列，允许 `NULL` 作为其特殊值。TiDB 将为其分配下一个自动值。 - -* 第二条 `INSERT` 语句失败，因为 `age` 列被定义为 `NOT NULL`。 - -* 第三条 `INSERT` 语句成功，因为 `last_login` 列没有被明确地指定为 `NOT NULL`。默认允许 `NULL` 值。 - -## 主键约束 - -TiDB 支持的主键约束规则与 MySQL 支持的相似。例如： - -``` -mysql> CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -Query OK, 0 rows affected (0.12 sec) -mysql> CREATE TABLE t2 (a INT NULL PRIMARY KEY); -ERROR 1171 (42000): All parts of a PRIMARY KEY must be NOT NULL; if you need NULL in a key, use UNIQUE instead -mysql> CREATE TABLE t3 (a INT NOT NULL PRIMARY KEY, b INT NOT NULL PRIMARY KEY); -ERROR 1068 (42000): Multiple primary key defined -mysql> CREATE TABLE t4 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b)); -Query OK, 0 rows affected (0.10 sec) -``` - -* 表 `t2` 创建失败，因为定义为主键的列 `a` 不能允许 `NULL` 值。 -* 表 `t3` 创建失败，因为一张表只能有一个主键。 -* 表 `t4` 创建成功，因为虽然只能有一个主键，但 TiDB 支持定义一个多列组合作为复合主键。 - -除上述规则外，TiDB 还强加了另一个限制，即一旦一张表创建成功，其主键就不能再改变。 - -## 唯一约束 - -在 TiDB 中，默认会对唯一约束进行惰性检查。通过直到事务提交时才进行批量检查，TiDB 能够减少网络通信开销。例如： - -``` -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -mysql> START TRANSACTION; -Query OK, 0 rows affected (0.00 sec) -mysql> INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -mysql> INSERT INTO users (username) VALUES ('steve'),('elizabeth'); -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 -mysql> COMMIT; -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -``` - -* 第一条 `INSERT` 语句不会导致重复键错误，这同 MySQL 的规则一致。该检查将推迟到事务提交时才会进行。 - -如果将 `tidb_constraint_check_in_place` 更改为 `TRUE`，则会在执行语句时就对唯一约束进行检查。例如： - -``` -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -mysql> SET tidb_constraint_check_in_place = TRUE; -Query OK, 0 rows affected (0.00 sec) -mysql> START TRANSACTION; -Query OK, 0 rows affected (0.00 sec) -mysql> INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -.. -``` - -* 第一条 `INSERT` 语句导致了重复键错误。这会造成额外的网络通信开销，并可能降低插入操作的吞吐量。 diff --git a/v2.1/reference/sql/data-types/date-and-time.md b/v2.1/reference/sql/data-types/date-and-time.md deleted file mode 100644 index 6645d949bd38..000000000000 --- a/v2.1/reference/sql/data-types/date-and-time.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 日期和时间类型 -category: reference ---- - -# 日期和时间类型 - -TiDB 支持 MySQL 所有的日期和时间类型，包括 DATE、DATETIME、TIMESTAMP、TIME 以及 YEAR，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-types.html)文档。 - -## 类型定义 - -### `DATE` 类型 - -`DATE` 类型的格式为 `YYYY-MM-DD`，支持的范围是 `1000-01-01` 到 `9999-12-31`。 - -{{< copyable "sql" >}} - -```sql -DATE -``` - -### `TIME` 类型 - -`TIME` 类型的格式为 `HH:MM:SS[.fraction]`，支持的范围是 `-838:59:59.000000` 到 `838:59:59.000000`。`TIME` 不仅可用于指示一天内的时间，还可用于指两个事件之间的时间间隔。`fsp` 参数表示秒精度，取值范围为：0 ~ 6，默认值为 0。 - -{{< copyable "sql" >}} - -```sql -TIME[(fsp)] -``` - -> **注意：** -> -> 注意 `TIME` 的缩写形式。例如，'11:12' 表示 '11:12:00' 而不是 '00:11:12'。但是，'1112' 表示 '00:11:12'。这些差异取决于 `:` 字符的存在与否。 - -### `DATETIME` 类型 - -`DATETIME` 类型是日期和时间的组合，格式为 `YYYY-MM-DD HH:MM:SS[.fraction]`。支持的范围是 `1000-01-01 00:00:00.000000` 到 `9999-12-31 23:59:59.000000`。`fsp` 参数表示秒精度，取值范围为 0~6，默认值为 0。 - -{{< copyable "sql" >}} - -```sql -DATETIME[(fsp)] -``` - -### `TIMESTAMP` 类型 - -`TIMESTAMP` 类型包含日期和时间，支持的范围是 `1970-01-01 00:00:01.000000` 到 `2038-01-19 03:14:07.999999`。`fsp` 参数表示秒精度，取值范围为 0~6，默认值为 0。在 `TIMESTAMP` 中，不允许零出现在月份部分或日期部分，唯一的例外是零值本身 '0000-00-00 00:00:00'。 - -{{< copyable "sql" >}} - -```sql -TIMESTAMP[(fsp)] -``` - -### `YEAR` 类型 - -`YEAR` 类型的格式为 'YYYY'，支持的值范围是 1901 到 2155，或零值 0000。 - -{{< copyable "sql" >}} - -```sql -YEAR[(4)] -``` diff --git a/v2.1/reference/sql/data-types/default-values.md b/v2.1/reference/sql/data-types/default-values.md deleted file mode 100644 index cfe82fb74cb7..000000000000 --- a/v2.1/reference/sql/data-types/default-values.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 数据类型的默认值 -category: reference ---- - -# 数据类型的默认值 - -在一个数据类型描述中的 `DEFAULT value` 段描述了一个列的默认值。这个默认值必须是常量，不可以是一个函数或者是表达式。但是对于时间类型，可以例外的使用 `NOW`、`CURRENT_TIMESTAMP`、`LOCALTIME`、`LOCALTIMESTAMP` 等函数作为 `DATETIME` 或者 `TIMESTAMP` 的默认值。 - -`BLOB`、`TEXT` 以及 `JSON` 不可以设置默认值。 - -如果一个列的定义中没有 `DEFAULT` 的设置。TiDB 按照如下的规则决定: - -* 如果该类型可以使用 `NULL` 作为值，那么这个列会在定义时添加隐式的默认值设置 `DEFAULT NULL`。 -* 如果该类型无法使用 `NULL` 作为值，那么这个列在定义时不会添加隐式的默认值设置。 - -对于一个设置了 `NOT NULL` 但是没有显式设置 `DEFAULT` 的列，当 `INSERT`、`REPLACE` 没有涉及到该列的值时，TiDB 根据当时的 `SQL_MODE` 进行不同的行为： - -* 如果此时是 `strict sql mode`，在事务中的语句会导致事务失败并回滚，非事务中的语句会直接报错。 -* 如果此时不是 `strict sql mode`，TiDB 会为这列赋值为列数据类型的隐式默认值。 - -此时隐式默认值的设置按照如下规则： - -* 对于数值类型，它们的默认值是 0。当有 `AUTO_INCREMENT` 参数时，默认值会按照增量情况赋予正确的值。 -* 对于除了时间戳外的日期时间类型，默认值会是该类型的“零值”。时间戳类型的默认值会是当前的时间。 -* 对于除枚举以外的字符串类型，默认值会是空字符串。对于枚举类型，默认值是枚举中的第一个值。 diff --git a/v2.1/reference/sql/data-types/json.md b/v2.1/reference/sql/data-types/json.md deleted file mode 100644 index 5bfc89554dc4..000000000000 --- a/v2.1/reference/sql/data-types/json.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: JSON 类型 -category: reference ---- - -# JSON 类型 - -JSON 类型可以存储 JSON 这种半结构化的数据，相比于直接将 JSON 存储为字符串，它的好处在于： - -1. 使用 Binary 格式进行序列化，对 JSON 的内部字段的查询、解析加快； -2. 多了 JSON 合法性验证的步骤，只有合法的 JSON 文档才可以放入这个字段中； - -JSON 字段本身上，并不能创建索引。相反，可以对 JSON 文档中的某个子字段创建索引。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE city ( - id INT PRIMARY KEY, - detail JSON, - population INT AS (JSON_EXTRACT(detail, '$.population')) -); -INSERT INTO city (id,detail) VALUES (1, '{"name": "Beijing", "population": 100}'); -SELECT id FROM city WHERE population >= 100; -``` diff --git a/v2.1/reference/sql/data-types/numeric.md b/v2.1/reference/sql/data-types/numeric.md deleted file mode 100644 index 08cd36538837..000000000000 --- a/v2.1/reference/sql/data-types/numeric.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 数值类型 -category: reference ---- - -# 数值类型 - -TiDB 支持 MySQL 所有的数值类型，按照精度可以分为: - -+ [整数类型（精确值)](#整数类型) -+ [浮点类型（近似值)](#浮点类型) -+ [定点类型（精确值)](#定点类型) - -## 整数类型 - -TiDB 支持 MySQL 所有的整数类型，包括 `INTEGER`/`INT`、`TINYINT`、`SMALLINT`、`MEDIUMINT` 以及 `BIGINT`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/numeric-type-overview.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| ---- | --------| -| M | 类型显示宽度，可选 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识，但是没有做补零的操作 | - -### 类型定义 - -#### `BIT` 类型 - -比特值类型。M 表示比特位的长度，取值范围从1到64，其默认值是1。 - -{{< copyable "sql" >}} - -```sql -BIT[(M)] -``` - -#### `BOOLEAN` 类型 - -布尔类型，别名为 `BOOL`，和 `TINYINT(1)` 等价。零值被认为是 `False`，非零值认为是 `True`。在 TiDB 内部，`True` 存储为 `1`，`False` 存储为 `0`。 - -{{< copyable "sql" >}} - -```sql -BOOLEAN -``` - -#### `TINYINT` 类型 - -`TINYINT` 类型。有符号数的范围是 `[-128, 127]`。无符号数的范围是 `[0, 255]`。 - -{{< copyable "sql" >}} - -```sql -TINYINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -#### `SMALLINT` 类型 - -`SMALLINT` 类型。有符号数的范围是 `[-32768, 32767]`。无符号数的范围是 `[0, 65535]`。 - -{{< copyable "sql" >}} - -```sql -SMALLINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -#### `MEDIUMINT` 类型 - -`MEDIUMINT` 类型。有符号数的范围是 `[-8388608, 8388607]`。无符号数的范围是 `[0, 16777215]`。 - -{{< copyable "sql" >}} - -```sql -MEDIUMINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -### `INTEGER` 类型 - -`INTEGER` 类型，别名 `INT`。有符号数的范围是 `[-2147483648, 2147483647]`。无符号数的范围是 `[0, 4294967295]`。 - -{{< copyable "sql" >}} - -```sql -INT[(M)] [UNSIGNED] [ZEROFILL] -``` - -或者： - -{{< copyable "sql" >}} - -```sql -INTEGER[(M)] [UNSIGNED] [ZEROFILL] -``` - -### `BIGINT` 类型 - -`BIGINT` 类型。有符号数的范围是 `[-9223372036854775808, 9223372036854775807]`。无符号数的范围是 `[0, 18446744073709551615]`。 - -{{< copyable "sql" >}} - -```sql -BIGINT[(M)] [UNSIGNED] [ZEROFILL] -> -``` - -### 存储空间以及取值范围 - -每种类型对存储空间的需求以及最大/最小值如下表所示: - -| 类型 | 存储空间 | 最小值(有符号/无符号) | 最大值(有符号/无符号) | -| ----------- |----------|-----------------------| --------------------- | -| `TINYINT` | 1 | -128 / 0 | 127 / 255 | -| `SMALLINT` | 2 | -32768 / 0 | 32767 / 65535 | -| `MEDIUMINT` | 3 | -8388608 / 0 | 8388607 / 16777215 | -| `INT` | 4 | -2147483648 / 0 | 2147483647 / 4294967295 | -| `BIGINT` | 8 | -9223372036854775808 / 0 | 9223372036854775807 / 18446744073709551615 | - -## 浮点类型 - -TiDB 支持 MySQL 所有的浮点类型，包括 `FLOAT`、`DOUBLE`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| -------- | ------------------------------- | -| M | 小数总位数 | -| D | 小数点后位数 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识 | - -### 类型定义 - -#### `FLOAT` 类型 - -单精度浮点数。允许的值范围为 -2^128 ~ +2^128，也即 -3.402823466E+38 到 -1.175494351E-38、0 和 1.175494351E-38 到 3.402823466E+38。这些是基于 IEEE 标准的理论限制。实际的范围根据硬件或操作系统的不同可能稍微小些。 - -`FLOAT(p)` 类型中，`p` 表示精度（以位数表示）。只使用该值来确定是否结果列的数据类型为 `FLOAT` 或 `DOUBLE`。如果 `p` 为从 0 到 24，数据类型变为没有 M 或 D 值的 `FLOAT`。如果 `p` 为从 25 到 53，数据类型变为没有 M 或 D 值的 `DOUBLE`。结果列范围与本节前面描述的单精度 `FLOAT` 或双精度 `DOUBLE` 数据类型相同。 - -{{< copyable "sql" >}} - -```sql -FLOAT[(M,D)] [UNSIGNED] [ZEROFILL] -FLOAT(p) [UNSIGNED] [ZEROFILL] -``` - -> **警告：** -> -> 与在 MySQL 中一样，`FLOAT` 数据类型存储近似值。对于货币之类的精确值，建议使用 `DECIMAL` 类型。 - -#### `DOUBLE` 类型 - -双精度浮点数，别名为 `DOUBLE PRECISION`。允许的值范围为：-2^1024 ~ +2^1024，也即是 -1.7976931348623157E+308 到 -2.2250738585072014E-308、0 和 2.2250738585072014E-308 到 1.7976931348623157E+308。这些是基于 IEEE 标准的理论限制。实际的范围根据硬件或操作系统的不同可能稍微小些。 - -{{< copyable "sql" >}} - -```sql -DOUBLE[(M,D)] [UNSIGNED] [ZEROFILL] -DOUBLE PRECISION [(M,D)] [UNSIGNED] [ZEROFILL], REAL[(M,D)] [UNSIGNED] [ZEROFILL] -``` - -> **警告：** -> -> 与在 MySQL 中一样，`DOUBLE` 数据类型存储近似值。对于货币之类的精确值，建议使用 `DECIMAL` 类型。 - -### 存储空间 - -每种类型对存储空间的需求如下表所示: - -| 类型 | 存储空间 | -| ----------- |----------| -| `FLOAT` | 4 | -| `FLOAT(p)` | 如果 0 <= p <= 24 为 4 个字节, 如果 25 <= p <= 53 为 8 个字节| -| `DOUBLE` | 8 | - -## 定点类型 - -TiDB 支持 MySQL 所有的定点类型，包括 `DECIMAL`、`NUMERIC`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/fixed-point-types.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| -------- | ------------------------------- | -| M | 小数总位数 | -| D | 小数点后位数 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识 | - -### 类型定义 - -#### `DECIMAL` 类型 - -定点数，别名为 `NUMERIC`。M 是小数位数（精度）的总数，D 是小数点（标度）后面的位数。小数点和 `-`（负数）符号不包括在 M 中。如果 D 是 0，则值没有小数点或分数部分。如果 D 被省略，默认是 0。如果 M 被省略，默认是 10。 - -{{< copyable "sql" >}} - -```sql -DECIMAL[(M[,D])] [UNSIGNED] [ZEROFILL] -NUMERIC[(M[,D])] [UNSIGNED] [ZEROFILL] -``` diff --git a/v2.1/reference/sql/data-types/overview.md b/v2.1/reference/sql/data-types/overview.md deleted file mode 100644 index 00024f1669f7..000000000000 --- a/v2.1/reference/sql/data-types/overview.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 数据类型概述 -category: reference ---- - -# 数据类型概述 - -TiDB 支持除空间类型 (`SPATIAL`) 之外的所有 MySQL 数据类型，包括[数值型类型](/v2.1/reference/sql/data-types/numeric.md)、[字符串类型](/v2.1/reference/sql/data-types/string.md)、[时间和日期类型](/v2.1/reference/sql/data-types/date-and-time.md)、[JSON 类型](/v2.1/reference/sql/data-types/json.md)。 - -数据类型定义一般为 `T(M[, D])`，其中： - -* `T` 表示具体的类型。 -* `M` 在整数类型中表示最大显示长度；在浮点数或者定点数中表示精度；在字符类型中表示最大长度。`M` 的最大值取决于具体的类型。 -* `D` 表示浮点数、定点数的小数位长度。 -* `fsp` 在时间和日期类型里的 `TIME`、`DATETIME` 以及 `TIMESTAMP` 中表示秒的精度，其取值范围是 0 到 6。值为 0 表示没有小数部分。如果省略，则默认精度为 0。 diff --git a/v2.1/reference/sql/data-types/string.md b/v2.1/reference/sql/data-types/string.md deleted file mode 100644 index 801998dc71b6..000000000000 --- a/v2.1/reference/sql/data-types/string.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 字符串类型 -category: reference ---- - -# 字符串类型 - -TiDB 支持 MySQL 所有的字符串类型，包括 `CHAR`、`VARCHAR`、`BINARY`、`VARBINARY`、`BLOB`、`TEXT`、`ENUM` 以及 `SET`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/string-types.html)文档。 - -## 类型定义 - -### `CHAR` 类型 - -定长字符串。`CHAR` 列的长度固定为创建表时声明的长度。长度可以为从 0 到 255 的任何值。当保存 CHAR 值时，在它们的右边填充空格以达到指定的长度。 - -{{< copyable "sql" >}} - -```sql -[NATIONAL] CHAR[(M)] [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `VARCHAR` 类型 - -变长字符串。M 表示最大列长度，范围是 0 到 65535。VARCHAR 的最大实际长度由最长的行的大小和使用的字符集确定。 - -{{< copyable "sql" >}} - -```sql -[NATIONAL] VARCHAR(M) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `TEXT` 类型 - -文本串。M 表示最大列长度，范围是 0 到 65535。TEXT 的最大实际长度由最长的行的大小和使用的字符集确定。 - -{{< copyable "sql" >}} - -```sql -TEXT[(M)] [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `TINYTEXT` 类型 - -类似于 `TEXT`，区别在于最大列长度为 255。 - -{{< copyable "sql" >}} - -```sql -TINYTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `MEDIUMTEXT` 类型 - -类似于 TEXT，区别在于最大列长度为 16,777,215。 - -{{< copyable "sql" >}} - -```sql -MEDIUMTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `LONGTEXT` 类型 - -类似于 `TEXT`，区别在于最大列长度为 4,294,967,295。 - -{{< copyable "sql" >}} - -```sql -LONGTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `BINARY` 类型 - -类似于 `CHAR`，区别在于 BINARY 存储的是二进制字符串。 - -{{< copyable "sql" >}} - -```sql -BINARY(M) -``` - -### `VARBINARY` 类型 - -类似于 `VARCHAR`，区别在于 VARBINARY 存储的是二进制字符串。 - -{{< copyable "sql" >}} - -```sql -VARBINARY(M) -``` - -### `TINYBLOB` 类型 - -类似于 BLOB，区别在于最大列长度为 255。 - -{{< copyable "sql" >}} - -```sql -TINYBLOB -``` - -### `BLOB` 类型 - -二进制大文件。M 表示最大列长度，范围是 0 到 65535。 - -{{< copyable "sql" >}} - -```sql -BLOB[(M)] -``` - -### `MEDIUMBLOB` 类型 - -类似于 `BLOB`，区别在于最大列长度为 16,777,215。 - -{{< copyable "sql" >}} - -```sql -MEDIUMBLOB -``` - -### `LONGBLOB` 类型 - -类似于 `BLOB`，区别在于最大列长度为 4,294,967,295。 - -{{< copyable "sql" >}} - -```sql -LONGBLOB -``` - -### `ENUM` 类型 - -枚举类型是一个字符串，它只能有一个值的字符串对象。其值必须是从一个固定集合中选取，这个固定集合在创建表的时候定义，语法是： - -{{< copyable "sql" >}} - -```sql -ENUM('value1','value2',...) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -ENUM('apple', 'orange', 'pear') -``` - -枚举类型的值在 TiDB 内部使用数值来存储，每个值会按照定义的顺序转换为一个数字，比如上面的例子中，每个字符串值都会映射为一个数字： - -| 值 | 数字 | -| ---- | ---- | -| NULL | NULL | -| '' | 0 | -| 'apple' | 1 | -| 'orange' | 2 | -| 'pear' | 3 | - -更多信息参考 [MySQL 枚举文档](https://dev.mysql.com/doc/refman/5.7/en/enum.html)。 - -### `SET` 类型 - -集合类型是一个包含零个或多个值的字符串，其中每个值必须是从一个固定集合中选取，这个固定集合在创建表的时候定义，语法是： - -{{< copyable "sql" >}} - -```sql -SET('value1','value2',...) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -SET('1', '2') NOT NULL -``` - -上面的例子中，这列的有效值可以是： - -``` -'' -'1' -'2' -'1,2' -``` - -集合类型的值在 TiDB 内部会转换为一个 Int64 数值，每个元素是否存在用一个二进制位的 0/1 值来表示，比如这个例子 `SET('a','b','c','d')`，每一个元素都被映射为一个数字，且每个数字的二进制表示只会有一位是 1： - -| 成员 | 十进制表示 | 二进制表示 | -| ---- | ---- | ------ | -| 'a' | 1 | 0001 | -| 'b' | 2 | 0010 | -| 'c' | 4 | 0100 | -| 'd' | 8 | 1000 | - -这样对于值为 `('a', 'c')` 的元素，其二进制表示即为 0101。 - -更多信息参考 [MySQL 集合文档](https://dev.mysql.com/doc/refman/5.7/en/set.html)。 diff --git a/v2.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md b/v2.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md deleted file mode 100644 index 4a335f640ef4..000000000000 --- a/v2.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: GROUP BY 聚合函数 -category: reference ---- - -# GROUP BY 聚合函数 - -本文将详细介绍 TiDB 支持的聚合函数。 - -## TiDB 支持的聚合函数 - -TiDB 支持的 MySQL GROUP BY 聚合函数如下所示： - -| 函数名 | 功能描述 | -|:---------|:--------------------| -| [`COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count) | 返回检索到的行的数目| -| [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count-distinct) | 返回不同值的数目 | -| [`SUM()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_sum) | 返回和 | -| [`AVG()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_avg) | 返回平均值 | -| [`MAX()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_max) | 返回最大值 | -| [`MIN()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_min) | 返回最小值 | -| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_group-concat) | 返回连接的字符串 | - -> **注意：** -> -> - 除非另有说明，否则聚合函数默认忽略 `NULL` 值。 -> - 如果在不包含 `GROUP BY` 子句的语句中使用聚合函数，则相当于对所有行进行分组。 - -## GROUP BY 修饰符 - -TiDB 目前不支持 `GROUP BY` 修饰符，例如 `WITH ROLLUP`，将来会提供支持。详情参阅 [#4250](https://github.com/pingcap/tidb/issues/4250)。 - -## 对 SQL 模式的支持 - -TiDB 支持 SQL 模式 `ONLY_FULL_GROUP_BY`，当启用该模式时，TiDB 拒绝不明确的非聚合列的查询。例如，以下查询在启用 `ONLY_FULL_GROUP_BY` 时是不合规的，因为 `SELECT` 列表中的非聚合列 "b" 在 `GROUP BY` 语句中不显示： - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 3), (2, 2, 3), (3, 2, 3); - -mysql> select a, b, sum(c) from t group by a; -+------+------+--------+ -| a | b | sum(c) | -+------+------+--------+ -| 1 | 2 | 3 | -| 2 | 2 | 3 | -| 3 | 2 | 3 | -+------+------+--------+ -3 rows in set (0.01 sec) - -mysql> set sql_mode = 'ONLY_FULL_GROUP_BY'; -Query OK, 0 rows affected (0.00 sec) - -mysql> select a, b, sum(c) from t group by a; -ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP BY clause and contains nonaggregated column 'b' which is not functionally dependent on columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by -``` - -目前，TiDB 默认开启 SQL 模式 [`ONLY_FULL_GROUP_BY`](/v2.1/reference/mysql-compatibility.md#默认设置的区别)。 - -### 与 MySQL 的区别 - -TiDB 目前实现的 `ONLY_FULL_GROUP_BY` 没有 MySQL 5.7 严格。例如，假设我们执行以下查询，希望结果按 "c" 排序： - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 1), (1, 2, 2), (1, 3, 1), (1, 3, 2); -select distinct a, b from t order by c; -``` - -要对结果进行排序，必须先清除重复。但选择保留哪一行会影响 `c` 的保留值，也会影响排序，并使其具有任意性。 - -在 MySQL 中，`ORDER BY` 表达式需至少满足以下条件之一，否则 `DISTINCT` 和 `ORDER BY` 查询将因不合规而被拒绝： - -- 表达式等同于 `SELECT` 列表中的一个。 -- 表达式引用并属于查询选择表的所有列都是 `SELECT` 列表的元素。 - -但是在 TiDB 中，上述查询是合规的，详情参阅 [#4254](https://github.com/pingcap/tidb/issues/4254)。 - -TiDB 中另一个标准 SQL 的扩展允许 `HAVING` 子句中的引用使用 `SELECT` 列表中的别名表达式。例如：以下查询返回在 `orders` 中只出现一次的 `name` 值： - -```sql -select name, count(name) from orders -group by name -having count(name) = 1; -``` - -这个 TiDB 扩展允许在聚合列的 `HAVING` 子句中使用别名： - -```sql -select name, count(name) as c from orders -group by name -having c = 1; -``` - -标准 SQL 只支持 `GROUP BY` 子句中的列表达式，以下语句不合规，因为 `FLOOR(value/100)` 是一个非列表达式： - -```sql -select id, floor(value/100) -from tbl_name -group by id, floor(value/100); -``` - -TiDB 对标准 SQL 的扩展支持 `GROUP BY` 子句中非列表达式，认为上述语句合规。 - -标准 SQL 也不支持 `GROUP BY` 子句中使用别名。TiDB 对标准 SQL 的扩展支持使用别名，查询的另一种写法如下： - -```sql -select id, floor(value/100) as val -from tbl_name -group by id, val; -``` - -## TiDB 不支持的聚合函数 - -TiDB 目前不支持的聚合函数如下所示，相关进展参阅 [TiDB #7623](https://github.com/pingcap/tidb/issues/7623)。 - -- `STD`, `STDDEV`, `STDDEV_POP` -- `STDDEV_SAMP` -- `VARIANCE`, `VAR_POP` -- `VAR_SAMP` -- `JSON_ARRAYAGG` -- `JSON_OBJECTAGG` diff --git a/v2.1/reference/sql/functions-and-operators/bit-functions-and-operators.md b/v2.1/reference/sql/functions-and-operators/bit-functions-and-operators.md deleted file mode 100644 index 2aec09c475ab..000000000000 --- a/v2.1/reference/sql/functions-and-operators/bit-functions-and-operators.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: 位函数和操作符 -category: reference ---- - -# 位函数和操作符 - -TiDB 中位函数和操作符的使用方法与 MySQL 基本一致，详情参见: [Bit Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html)。 - -**位函数和操作符表** - -| 函数和操作符名 | 功能描述 | -| -------------- | ------------------------------------- | -| [`BIT_COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#function_bit-count) | 返回参数二进制表示中为 1 的个数 | -| [&](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-and) | 位与 | -| [~](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-invert) | 按位取反 | -| [\|](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-or) | 位或 | -| [^](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-xor) | 位亦或 | -| [<<](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_left-shift) | 左移 | -| [>>](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_right-shift) | 右移 | diff --git a/v2.1/reference/sql/functions-and-operators/cast-functions-and-operators.md b/v2.1/reference/sql/functions-and-operators/cast-functions-and-operators.md deleted file mode 100644 index b08a98dc0ae2..000000000000 --- a/v2.1/reference/sql/functions-and-operators/cast-functions-and-operators.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Cast 函数和操作符 -category: reference ---- - -# Cast 函数和操作符 - -Cast 函数和操作符用于将某种数据类型的值转换为另一种数据类型。TiDB 中该函数和操作符的使用方法与 MySQL基本一致，详情参见: [Cast Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html). - -## Cast 函数和操作符表 - -| 函数和操作符名 | 功能描述 | -| --------------- | ----------------------------------- | -| [`BINARY`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#operator_binary) | 将一个字符串转换成一个二进制字符串 | -| [`CAST()`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_cast) | 将一个值转换成一个确定类型 | -| [`CONVERT()`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_convert) | 将一个值转换成一个确定类型 | - diff --git a/v2.1/reference/sql/functions-and-operators/control-flow-functions.md b/v2.1/reference/sql/functions-and-operators/control-flow-functions.md deleted file mode 100644 index 6297065acf9c..000000000000 --- a/v2.1/reference/sql/functions-and-operators/control-flow-functions.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 控制流程函数 -category: reference ---- - -# 控制流程函数 - -| 函数名 | 功能描述 | -|:--------------------------------------------------------------------------------------------------|:----------------------------------| -| [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case) | Case 操作符 | -| [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if) | 构建 if/else | -| [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | 构建 Null if/else | -| [`NULLIF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_nullif) | 如果 expr1 = expr2，返回 `NULL` | diff --git a/v2.1/reference/sql/functions-and-operators/date-and-time-functions.md b/v2.1/reference/sql/functions-and-operators/date-and-time-functions.md deleted file mode 100644 index 1de572c6abad..000000000000 --- a/v2.1/reference/sql/functions-and-operators/date-and-time-functions.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: 日期和时间函数 -category: reference ---- - -# 日期和时间函数 - -TiDB 中日期和时间函数的使用方法与 MySQL 基本一致，详情参见: [Date and Time Functions](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html). - -## 日期时间函数表 - -| 函数名 | 功能描述 | -| ------ | ---------------------------------------- | -| [`ADDDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_adddate) | 将时间间隔添加到日期上 | -| [`ADDTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_addtime) | 时间数值相加 | -| [`CONVERT_TZ()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_convert-tz) | 转换时区 | -| [`CURDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_curdate) | 返回当前日期 | -| [`CURRENT_DATE()`, `CURRENT_DATE`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-date) | 与 CURDATE() 同义 | -| [`CURRENT_TIME()`, `CURRENT_TIME`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-time) | 与 CURTIME() 同义 | -| [`CURRENT_TIMESTAMP()`, `CURRENT_TIMESTAMP`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-timestamp) | 与 NOW() 同义 | -| [`CURTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_curtime) | 返回当前时间 | -| [`DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date) | 从日期或日期/时间表达式中提取日期部分| -| [`DATE_ADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-add) | 将时间间隔添加到日期上| -| [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | 返回满足指定格式的日期/时间 | -| [`DATE_SUB()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-sub) | 从日期减去指定的时间间隔 | -| [`DATEDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_datediff) | 返回两个日期间隔的天数| -| [`DAY()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_day) | 与 DAYOFMONTH() 同义| -| [`DAYNAME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayname) | 返回星期名称 | -| [`DAYOFMONTH()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofmonth) | 返回参数对应的天数部分(1-31)| -| [`DAYOFWEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofweek) | 返回参数对应的星期下标| -| [`DAYOFYEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofyear) | 返回参数代表一年的哪一天 (1-366) | -| [`EXTRACT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_extract) | 提取日期/时间中的单独部分| -| [`FROM_DAYS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_from-days) | 将天数转化为日期 | -| [`FROM_UNIXTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_from-unixtime) | 将 Unix 时间戳格式化为日期 | -| [`GET_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_get-format) | 返回满足日期格式的字符串 | -| [`HOUR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_hour) | 提取日期/时间表达式中的小时部分 | -| [`LAST_DAY`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_last-day) | 返回参数中月份的最后一天 | -| [`LOCALTIME()`, `LOCALTIME`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_localtime) | 与 NOW() 同义 | -| [`LOCALTIMESTAMP`, `LOCALTIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_localtimestamp) | 与 NOW() 同义 | -| [`MAKEDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_makedate) | 根据给定的年份和一年中的天数生成一个日期 | -| [`MAKETIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_maketime) | 根据给定的时、分、秒生成一个时间 | -| [`MICROSECOND()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_microsecond) | 返回参数的微秒部分| -| [`MINUTE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_minute) | 返回参数的分钟部分| -| [`MONTH()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_month) | 返回参数的月份部分| -| [`MONTHNAME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_monthname) | 返回参数的月份名称| -| [`NOW()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_now) | 返回当前日期和时间| -| [`PERIOD_ADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_period-add) | 在年-月表达式上添加一段时间(数个月)| -| [`PERIOD_DIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_period-diff) | 返回间隔的月数| -| [`QUARTER()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_quarter) | 返回参数对应的季度(1-4) | -| [`SEC_TO_TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_sec-to-time) | 将秒数转化为 'HH:MM:SS' 的格式| -| [`SECOND()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_second) | 返回秒数(0-59) | -| [`STR_TO_DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_str-to-date) | 将字符串转化为日期| -| [`SUBDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_subdate) | 当传入三个参数时作为 DATE_SUB() 的同义| -| [`SUBTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_subtime) | 从一个时间中减去一段时间 | -| [`SYSDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_sysdate) | 返回该方法执行时的时间| -| [`TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time) | 返回参数的时间表达式部分 | -| [`TIME_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time-format) | 格式化时间| -| [`TIME_TO_SEC()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time-to-sec) | 返回参数对应的秒数| -| [`TIMEDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timediff) | 返回时间间隔 | -| [`TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestamp) | 传入一个参数时候,该方法返回日期或日期/时间表达式, 传入两个参数时候, 返回参数的和 | -| [`TIMESTAMPADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestampadd) | 在日期/时间表达式上增加一段时间间隔 | -| [`TIMESTAMPDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestampdiff) | 从日期/时间表达式中减去一段时间间隔 | -| [`TO_DAYS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_to-days) | 将参数转化对应的天数(从第 0 年开始) | -| [`TO_SECONDS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_to-seconds) | 将日期或日期/时间参数转化为秒数(从第 0 年开始) | -| [`UNIX_TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_unix-timestamp) | 返回一个 Unix 时间戳| -| [`UTC_DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-date) | 返回当前的 UTC 日期 | -| [`UTC_TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-time) | 返回当前的 UTC 时间 | -| [`UTC_TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-timestamp) | 返回当前的 UTC 日期和时间| -| [`WEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_week) | 返回参数所在的一年中的星期数 | -| [`WEEKDAY()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_weekday) | 返回星期下标 | -| [`WEEKOFYEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_weekofyear) | 返回参数在日历中对应的一年中的星期数 | -| [`YEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_year) | 返回参数对应的年数| -| [`YEARWEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_yearweek) | 返回年数和星期数 | diff --git a/v2.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md b/v2.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md deleted file mode 100644 index 0db5cde147b2..000000000000 --- a/v2.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: 加密和压缩函数 -category: reference ---- - -# 加密和压缩函数 - -| 函数名 | 功能描述 | -|:-----------|:----------------------------| -| [`MD5()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_md5)                                                             | 计算字符串的 MD5 校验和       | -| [`PASSWORD()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_password) | 计算并返回密码字符串 | -| [`RANDOM_BYTES()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_random-bytes) | 返回随机字节向量 | -| [`SHA1()`, `SHA()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_sha1)                                                   | 计算 SHA-1 160 位校验和               | -| [`SHA2()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_sha2)                                                           | 计算 SHA-2 校验和                       | -| [`AES_DECRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_aes-decrypt) | 使用 AES 解密 | -| [`AES_ENCRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_aes-encrypt) | 使用 AES 加密 | -| [`COMPRESS()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_compress) | 返回经过压缩的二进制字符串 | -| [`UNCOMPRESS()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_uncompress) | 解压缩字符串 | -| [`UNCOMPRESSED_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_uncompressed-length)                             | 返回字符串解压后的长度 | -| [`CREATE_ASYMMETRIC_PRIV_KEY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-asymmetric-priv-key) | 创建私钥 | -| [`CREATE_ASYMMETRIC_PUB_KEY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-asymmetric-pub-key) | 创建公钥 | -| [`CREATE_DH_PARAMETERS()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-dh-parameters) | 创建 DH 共享密钥 | -| [`CREATE_DIGEST()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-digest) | 从字符串创建摘要 | -| [`ASYMMETRIC_DECRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-decrypt) | 使用公钥或私钥解密密文 | -| [`ASYMMETRIC_DERIVE()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-derive) | 从非对称密钥导出对称密钥 | -| [`ASYMMETRIC_ENCRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-encrypt) | 使用公钥或私钥加密明文 | -| [`ASYMMETRIC_SIGN()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-sign) | 从摘要创建签名 | -| [`ASYMMETRIC_VERIFY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-verify) | 验证签名字符串是否匹配摘要字符串 | diff --git a/v2.1/reference/sql/functions-and-operators/information-functions.md b/v2.1/reference/sql/functions-and-operators/information-functions.md deleted file mode 100644 index c190910a094f..000000000000 --- a/v2.1/reference/sql/functions-and-operators/information-functions.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 信息函数 -category: reference ---- - -# 信息函数 - -TiDB 中信息函数的使用方法与 MySQL 基本一致，详情参见：[Information Functions](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html)。 - -## 信息函数表 - -| 函数名 | 功能描述 | -| ------ | ---------------------------------------- | -| [`CONNECTION_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_connection-id) | 返回当前连接的连接 ID (线程 ID) | -| [`CURRENT_USER()`, `CURRENT_USER`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_current-user) | 返回当前用户的用户名和主机名 | -| [`DATABASE()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_database) | 返回默认(当前)的数据库名 | -| [`FOUND_ROWS()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_found-rows) | 该函数返回对于一个包含 LIMIT 的 SELECT 查询语句，在不包含 LIMIT 的情况下回返回的记录数 | -| [`LAST_INSERT_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_last-insert-id) | 返回最后一条 INSERT 语句中自增列的值 | -| [`SCHEMA()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_schema) | 与 DATABASE() 同义 | -| [`SESSION_USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_session-user) | 与 USER() 同义 | -| [`SYSTEM_USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_system-user) | 与 USER() 同义 | -| [`USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_user) | 返回客户端提供的用户名和主机名 | -| [`VERSION()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_version) | 返回当前 MySQL 服务器的版本信息 | -| `TIDB_VERSION()` | 返回当前 TiDB 服务器的版本信息 | diff --git a/v2.1/reference/sql/functions-and-operators/json-functions.md b/v2.1/reference/sql/functions-and-operators/json-functions.md deleted file mode 100644 index d23f5e6f2b82..000000000000 --- a/v2.1/reference/sql/functions-and-operators/json-functions.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: JSON 函数及语法糖 -category: reference ---- - -# JSON 函数及语法糖 - -TiDB 支持 MySQL 5.7 GA 版本发布的大多数 JSON 函数。MySQL 5.7 发布后，又增加了更多 JSON 函数，TiDB 并未支持所有这些函数（参见[未支持的函数](#未支持的函数)）。 - -## 创建 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| ------------------------------------------------------------------ | ---------------------------------------------------------- | -| [JSON_ARRAY([val[, val] ...])][json_array] | 根据一系列元素创建一个 JSON 文档 | -| [JSON_OBJECT(key, val[, key, val] ...)][json_object] | 根据一系列 K/V 对创建一个 JSON 文档 | -| [JSON_QUOTE(string)][json_quote] | 返回一个字符串，该字符串为带引号的 JSON 值 | - -## 搜索 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| ------------------------------------------------------------------ | ---------------------------------------------------------- | -| [JSON_CONTAINS(target, candidate[, path])][json_contains] | 通过返回 1 或 0 来表示目标 JSON 文档中是否包含给定的 candidate JSON 文档 | -| [JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)][json_contains_path] | 通过返回 0 或 1 来表示一个 JSON 文档在给定路径是否包含数据 | -| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract] | 从 JSON 文档中解出某一路径对应的子文档 | -| [->][json_short_extract] | 返回执行路径后面的 JSON 列的值；`JSON_EXTRACT(doc, path_literal)` 的语法糖 | -| [->>][json_short_extract_unquote] | 返回执行路径后面的 JSON 列的值和转义后的结果； `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` 的语法糖 | -| [JSON_KEYS(json_doc[, path])][json_keys] | 返回从 JSON 对象的顶级值作为 JSON array 的键，如果给定了路径参数，则从选定路径中获取顶级键 | - -## 修改 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| --------------------------------- | ----------- | -| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | 在 JSON 文档中在某一路径下插入子文档 | -| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge] | 已废弃的 `JSON_MERGE_PRESERVE` 别名 | -| [JSON_MERGE_PRESERVE(json_doc, json_doc[, json_doc] ...)][json_merge_preserve] | 将两个或多个 JSON 文档合并成一个文档，并返回合并结果 | -| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | 移除 JSON 文档中某一路径下的子文档 | -| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | 替换 JSON 文档中的某一路径下的子文档 | -| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set] | 在 JSON 文档中为某一路径设置子文档 | -| [JSON_UNQUOTE(json_val)][json_unquote] | 去掉 JSON 值外面的引号，返回结果为字符串 | - -## 返回 JSON 值属性的函数 - -| 函数及语法糖 | 功能描述 | -| --------------------------------- | ----------- | -| [JSON_DEPTH(json_doc)][json_depth] | 返回 JSON 文档的最大深度 | -| [JSON_LENGTH(json_doc[, path])][json_length] | 返回 JSON 文档的长度；如果路径参数已定，则返回该路径下值的长度 | -| [JSON_TYPE(json_val)][json_type] | 检查某 JSON 文档内部内容的类型 | - -## 未支持的函数 - -TiDB 暂未支持以下 JSON 函数。相关进展参见 [TiDB #7546](https://github.com/pingcap/tidb/issues/7546): - -* `JSON_APPEND` 及其别名 `JSON_ARRAY_APPEND` -* `JSON_ARRAY_INSERT` -* `JSON_DEPTH` -* `JSON_MERGE_PATCH` -* `JSON_PRETTY` -* `JSON_SEARCH` -* `JSON_STORAGE_SIZE` -* `JSON_VALID` -* `JSON_ARRAYAGG` -* `JSON_OBJECTAGG` - -[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract -[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path -[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path -[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote -[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type -[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set -[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert -[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace -[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove -[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge -[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve -[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object -[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array -[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys -[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length -[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid -[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote -[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains -[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path -[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg -[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/v2.1/reference/sql/functions-and-operators/miscellaneous-functions.md b/v2.1/reference/sql/functions-and-operators/miscellaneous-functions.md deleted file mode 100644 index b0fe6dcb5b07..000000000000 --- a/v2.1/reference/sql/functions-and-operators/miscellaneous-functions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 其他函数 -category: reference ---- - -# 其他函数 - -| 函数名 | 功能描述 | -|:------|:-----------| -| [`ANY_VALUE()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_any-value) | 在 `ONLY_FULL_GROUP_BY` 模式下，防止带有 `GROUP BY` 的语句报错 | -| [`SLEEP()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_sleep) | 休眠指定秒数 | -| [`UUID()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_uuid) | 返回通用唯一识别码 (UUID) | -| [`VALUES()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_values) | 定义 `INSERT` 过程中要用到的值 | -| [`INET_ATON()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet-aton) | 将 IP 地址转换为数值 | -| [`INET_NTOA()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet-ntoa) | 将数值转换为 IP 地址 | -| [`INET6_ATON()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet6-aton) | 将 IPv6 地址转换为数值 | -| [`INET6_NTOA()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet6-ntoa) | 将数值转换为 IPv6 地址 | -| [`IS_IPV4()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4) | 判断参数是否为 IPv4 地址 | -| [`IS_IPV4_COMPAT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4-compat) | 判断参数是否为兼容 IPv4 的地址 | -| [`IS_IPV4_MAPPED()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4-mapped) | 判断参数是否为 IPv4 映射的地址 | -| [`IS_IPV6()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv6) | 判断参数是否为 IPv6 地址 | -| [`GET_LOCK()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock) | 获取命名锁，TiDB 出于兼容性支持这个函数，实际上不会做任何操作，这点和 MySQL 有区别 | -| [`RELEASE_LOCK()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_release-lock) | 释放命名锁 | diff --git a/v2.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md b/v2.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md deleted file mode 100644 index 8e43902d5410..000000000000 --- a/v2.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 数值函数与操作符 -category: reference ---- - -# 数值函数与操作符 - -## 算术操作符 - -| 操作符名 | 功能描述 | -|:-------------|:--------------------------------| -| [`+`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_plus) | 加号 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_minus) | 减号 | -| [`*`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_times) | 乘号 | -| [`/`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_divide) | 除号 | -| [`DIV`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_div) | 整数除法 | -| [`%`, `MOD`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod) | 模运算，取余 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_unary-minus) | 更改参数符号 | - -## 数学函数 - -| 函数名 | 功能描述 | -|:----------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| -| [`POW()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_pow) | 返回参数的指定乘方的结果值 | -| [`POWER()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_power) | 返回参数的指定乘方的结果值 | -| [`EXP()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_exp) | 返回 e（自然对数的底）的指定乘方后的值 | -| [`SQRT()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sqrt) | 返回非负数的二次方根 | -| [`LN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ln) | 返回参数的自然对数 | -| [`LOG()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log) | 返回第一个参数的自然对数 | -| [`LOG2()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log2) | 返回参数以 2 为底的对数 | -| [`LOG10()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log10) | 返回参数以 10 为底的对数 | -| [`PI()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_pi) | 返回 pi 的值 | -| [`TAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_tan) | 返回参数的正切值 | -| [`COT()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_cot) | 返回参数的余切值 | -| [`SIN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sin) | 返回参数的正弦值 | -| [`COS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_cos) | 返回参数的余弦值 | -| [`ATAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_atan) | 返回参数的反正切值 | -| [`ATAN2(), ATAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_atan2) | 返回两个参数的反正切值 | -| [`ASIN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_asin) | 返回参数的反正弦值 | -| [`ACOS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_acos) | 返回参数的反余弦值 | -| [`RADIANS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_radians) | 返回由度转化为弧度的参数 | -| [`DEGREES()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_degrees) | 返回由弧度转化为度的参数 | -| [`MOD()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_mod) | 返回余数 | -| [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs) | 返回参数的绝对值 | -| [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil) | 返回不小于参数的最小整数值 | -| [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling) | 返回不小于参数的最小整数值 | -| [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | 返回不大于参数的最大整数值 | -| [`ROUND()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_round) | 返回参数最近似的整数或指定小数位数的数值 | -| [`RAND()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_rand) | 返回一个随机浮点值 | -| [`SIGN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sign) | 返回参数的符号 | -| [`CONV()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_conv) | 不同数基间转换数字，返回数字的字符串表示 | -| [`TRUNCATE()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_truncate) | 返回被舍位至指定小数位数的数字 | -| [`CRC32()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_crc32)           | 计算循环冗余码校验值并返回一个 32 位无符号值                     | diff --git a/v2.1/reference/sql/functions-and-operators/operators.md b/v2.1/reference/sql/functions-and-operators/operators.md deleted file mode 100644 index 04df31d1a871..000000000000 --- a/v2.1/reference/sql/functions-and-operators/operators.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: 操作符 -category: reference ---- - -# 操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`AND`, &&](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_and) | 逻辑与 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-equal) | 赋值 (可用于 [`SET`](https://dev.mysql.com/doc/refman/5.7/en/set-variable.html) 语句中, 或用于 [`UPDATE`](https://dev.mysql.com/doc/refman/5.7/en/update.html) 语句的 `SET` 中 ) | -| [`:=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-value) | 赋值 | -| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_between) | 判断值满足范围 | -| [`BINARY`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#operator_binary) | 将一个字符串转换为一个二进制字符串 | -| [&](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-and) | 位与 | -| [~](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-invert) | 位非 | -| [`\|`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-or) | 位或 | -| [`^`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-xor) | 按位异或 | -| [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case) | case 操作符 | -| [`DIV`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_div) | 整数除 | -| [`/`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_divide) | 除法 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal) | 相等比较 | -| [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to) | 空值安全型相等比较 | -| [`>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than) | 大于 | -| [`>=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than-or-equal) | 大于或等于 | -| [`IS`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is) | 判断一个值是否等于一个布尔值 | -| [`IS NOT`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not) | 判断一个值是否不等于一个布尔值 | -| [`IS NOT NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not-null) | 非空判断 | -| [`IS NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-null) | 空值判断 | -| [`<<`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_left-shift) | 左移 | -| [`<`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than) | 小于 | -| [`<=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than-or-equal) | 小于或等于 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 简单模式匹配 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_minus) | 减 | -| [`%`, `MOD`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod) | 求余 | -| [`NOT`, `!`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_not) | 取反 | -| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-between) | 判断值是否不在范围内 | -| [`!=`, `<>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-equal) | 不等于 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 不符合简单模式匹配 | -| [`NOT REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_not-regexp) | 不符合正则表达式模式匹配 | -| [`\|\|`, `OR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_or) | 逻辑或 | -| [`+`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_plus) | 加 | -| [`REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 使用正则表达式进行模式匹配 | -| [`>>`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_right-shift) | 右移 | -| [`RLIKE`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | REGEXP 同义词 | -| [`*`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_times) | 乘 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_unary-minus) | 取反符号 | -| [`XOR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_xor) | 逻辑亦或 | - -## 操作符优先级 - -操作符优先级显示在以下列表中，从最高优先级到最低优先级。同一行显示的操作符具有相同的优先级。 - -```sql -INTERVAL -BINARY -! -- (unary minus), ~ (unary bit inversion) -^ -*, /, DIV, %, MOD --, + -<<, >> -& -| -= (comparison), <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN -BETWEEN, CASE, WHEN, THEN, ELSE -NOT -AND, && -XOR -OR, || -= (assignment), := -``` - -详情参见 [Operator Precedence](https://dev.mysql.com/doc/refman/5.7/en/operator-precedence.html)。 - -## 比较方法和操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_between) | 判断值是否在范围内 | -| [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | 返回第一个非空值 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal) | 相等比较 | -| [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to) | 空值安全型相等比较 | -| [`>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than) | 大于 | -| [`>=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than-or-equal) | 大于或等于 | -| [`GREATEST()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_greatest) | 返回最大值 | -| [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in) | 判断值是否在一个值的集合内 | -| [`INTERVAL()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_interval) | 返回一个小于第一个参数的参数的下标 | -| [`IS`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is) | 判断是否等于一个布尔值 | -| [`IS NOT`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not) | 判断是否不等于一个布尔值 | -| [`IS NOT NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not-null) | 非空判断 | -| [`IS NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-null) | 空值判断 | -| [`ISNULL()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_isnull) | 判断参数是否为空 | -| [`LEAST()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_least) | 返回最小值 | -| [`<`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than) | 小于 | -| [`<=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than-or-equal) | 小于或等于 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 简单模式匹配 | -| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-between) | 判断值是否不在范围内 | -| [`!=`, `<>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-equal) | 不等于 | -| [`NOT IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_not-in) | 判断值是否不在一个值的集合内 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 不满足简单模式匹配 | -| [`STRCMP()`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#function_strcmp) | 比较两个字符串 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html). - -## 逻辑操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`AND`, &&](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_and) | 逻辑与 | -| [`NOT`, `!`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_not) | 逻辑非 | -| [`\|\|`, `OR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_or) | 逻辑或 | -| [`XOR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_xor) | 逻辑亦或 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/group-by-handling.html). - -## 赋值操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-equal) | 赋值 (可用于 [`SET`](https://dev.mysql.com/doc/refman/5.7/en/set-variable.html) 语句中, 或用于 [`UPDATE`](https://dev.mysql.com/doc/refman/5.7/en/update.html) 语句的 `SET` 中 ) | -| [`:=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-value) | 赋值 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/group-by-functional-dependence.html). diff --git a/v2.1/reference/sql/functions-and-operators/precision-math.md b/v2.1/reference/sql/functions-and-operators/precision-math.md deleted file mode 100644 index 7a17c06082eb..000000000000 --- a/v2.1/reference/sql/functions-and-operators/precision-math.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: 精度数学 -category: reference ---- - -# 精度数学 - -TiDB 中精度数学计算与 MySQL 中基本一致, 详情请参见: [Precision Math](https://dev.mysql.com/doc/refman/5.7/en/precision-math.html). - -- 数值类型 -- DECIMAL 数据类型的特性 - -## 数值类型 - -精确数值运算的范围包括精确值数据类型(整型和 DECIMAL 类型), 以及精确值数字字面量. 近似值数据类型和近似值数字字面量被作为浮点数来处理. - -精确值数字字面量包含整数部分或小数部分, 或二者都包含. 精确值数字字面量可以包含符号位. 例如: 1, .2, 3.4, -5, -6.78, +9.10. - -近似值数字字面量以一个包含尾数和指数的科学计数法表示(基数为 10). 其中尾数和指数可以分别或同时带有符号位. 例如: 1.2E3, 1.2E-3, -1.2E3, -1.2E-3. - -两个看起来相似的数字可能会被以不同的方式进行处理. 例如, 2.34 是精确值(定点数), 而 2.3E0 是近似值(浮点数). - -DECIMAL 数据类型是定点数类型, 其运算是精确计算. FLOAT 和 DOUBLE 数据类型是浮点类型, 其运算是近似计算. - -## DECIMAL 数据类型的特性 - -本节讨论 DECIMAL 数据类型的特性, 主要涉及以下几点: - -1. 最大位数 -2. 存储格式 -3. 存储要求 - -DECIMAL 列的声明语法为 DECIMAL(M, D). 其中参数值意义及其范围如下: - -- M 表示最大的数字位数 (精度). 1<= M <= 65. -- D 表示小数点右边数字的位数 (标度). 1 <= D <= 30 且 不大于 M. - -M 的最大值 65 表示 DECIMAL 值的计算精确到 65 位数字. 该精度同样适用于其精确值字面量. - -DECIMAL 列的值采用二进制进行存储, 其将每 9 位十进制数字包装成 4 个字节. 其中整数和小数部分分别确定所需的存储空间. 如果数字位数为 9 的倍数, 则每 9 位十进制数字各采用 4 个字节进行存储, 对于剩余不足 9 位的数字, 所需的存储空间如下表所示. - -| 剩余数字位数 | 存储所需字节数 | -| --- | --- | -| 0 | 0 | -| 1–2 | 1 | -| 3–4 | 2 | -| 5–6 | 3 | -| 7–9 | 4 | - -例如, 定义类型为 DECIMAL(18, 9) 的列, 其小数点两侧均各包含 9 位十进制数字, 因此, 分别需要 4 个字节的存储空间. 定义类型为 DECIMAL(20, 6) 的列, 其小数部分包含 6 位十进制数字, 整数部分包含 14 位十进制数字. 整数部分中 9 位数字需要 4 个字节进行存储, 其余 5 位数字需要 3 个字节进行存储. 小数部分 6 位数字需要 3 个字节进行存储. - -DECIMAL 列不存储前导的字符 `+` 或字符 `-` 或数字 `0`. 如果将 +0003.1 插入到 DECIMAL(5, 1) 列中, 则将其存储为3.1. 对于负数, 不存储字符 `-` 的字面值. - -DECIMAL 列不允许插入大于列定义的隐含范围的值. 例如, DECIMAL(3, 0) 列范围为 -999 到 999. DECIMAL(M, D) 列小数点左边部分最多支持 M-D 位数字. - -有关 DECIMAL 值的内部格式完整说明, 请参阅 TiDB 源码文件 [types/mydecimal.go](https://github.com/pingcap/tidb/blob/master/types/mydecimal.go). - -## 表达式计算 - -在涉及精度数学计算的表达式中，TiDB 会尽可能不做任何修改的使用每个输入的数值。比如：在计算比较函数时，参与运算的数字将不做任何改变。在严格 SQL 模式下，向一个数据列插入一个值时，如果该值处于这一列的值域范围内，这个值将直接不做任何修改的直接插入进去，提取这个值的时候，取得的值和插入的值将会是同一个值。当处于非严格 SQL 模式时，TiDB 会允许数据插入过程中发生的数据截断。 - -处理数值类型表达式取决于这个表达式参数的具体值： - -* 当表达式参数中包含近似值时，这个表达式的结果也是近似值，TiDB 会使用浮点数对应的计算逻辑返回一个浮点数的结果 -* 当表达式参数中不包含任何近似值时（也就是说表达式的参数全部是精确值），如果某个精确值包含小数部分，TIDB 会对这个表达式使用 `DECIMAL` 对应的计算逻辑，返回一个 `DECIMAL` 的结果，精确到 65 位数字 -* 其他情况下，表达式只会包含整数参数，这个表达式的结果也是精确的，TiDB 会使用整数对应的计算逻辑返回一个整数结果，精度和 `BIGINT` 保持一致（64位） - -如果数值类型表达式中包含字符串参数，这些字符串参数将被转换成双精度浮点数，这个表达式的计算结果将是个近似值。 - -向一个数值类型列插入数据的具体行为会受到 SQL 模式的影响。接下来的讨论将围绕严格模式以及 `ERROR_FOR_DIVISION_BY_ZERO` 模式展开，如果要打开所有的限制，可以简单的使用 `TRADITIONAL` 模式，这个模式将同时使用严格模式以及 `ERROR_FOR_DIVISION_BY_ZERO` 模式： - -```sql -SET sql_mode = 'TRADITIONAL'; -``` - -向一个具有精确值类型（`DECIMAL` 或者整数类型）的列插入数据时，如果插入的数据位于该列的值域范围内将使用该数据的精确值。如果该数据的小数部分太长，将会发生数值修约，这时会有 warning 产生，具体内容可以看"数值修约"。 - -如果该数据整数部分太长： - -* 如果没有开启严格模式，这个值会被截断并产生一个 warning -* 如果开启了严格模式，将会产生一个数据溢出的 error - -如果向一个数值类型列插入字符串，如果该字符串中包含非数值部分，TiDB 将这样做类型转换： - -* 在严格模式下，没有以数字开头的字符串（即使是一个空字符串）不能被被用作数字值并会返回一个 error 或者是 warning； -* 以数字开头的字符串可以被转换，不过末尾的非数字部分会被截断。如果被截断的部分包含的不全是空格，在严格模式下这回产生一个 error 或者 warning - -默认情况下，如果计算的过程中发生了除数是 0 的现象将会得到一个 `NULL` 结果，并且不会有 warning 产生。通过设置适当的 SQL 模式，除以 0 的操作可以被限制：当设置 `ERROR_FOR_DIVISION_BY_ZERO` SQL 模式时，TiDB 的行为是： - -* 如果设置了严格 SQL 模式，`INSERT` 和 `UPDATE` 的过程中如果发生了除以 0 的操作，正在进行的 `INSERT` 或者 `UPDATE` 操作会被禁止，并且会返回一个 error -* 如果没有设置严格 SQL 模式，除以 0 的操作仅会返回一个 warning - -假设我们有如下的 SQL 语句： - -```sql -INSERT INTO t SET i = 1/0; -``` - -不同的 SQL 模式将会导致不同的结果如下： - -| `sql_mode` 的值 | 结果 | -| :--- | :--- | -| '' | 没有 warning，没有 error，i 被设为 NULL | -| strict | 没有 warning，没有 error，i 被设为 NULL | -| `ERROR_FOR_DIVISION_BY_ZERO` | 有 warning，没有 error，i 被设为 NULL | -| strict, `ERROR_FOR_DIVISION_BY_ZERO` | 有 error，插入失败 | - -## 数值修约 - -`round()` 函数的结果取决于他的参数是否是精确值： - -* 如果参数是精确值，`round()` 函数将使用四舍五入的规则 -* 如果参数是一个近似值，`round()` 表达式的结果可能和 MySQL 不太一样 - -```sql -TiDB > SELECT ROUND(2.5), ROUND(25E-1); -+------------+--------------+ -| ROUND(2.5) | ROUND(25E-1) | -+------------+--------------+ -| 3 | 3 | -+------------+--------------+ -1 row in set (0.00 sec) -``` - -向一个 `DECIMAL` 或者整数类型列插入数据时，round 的规则将采用 [round half away from zero](https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero) 的方式： - -```sql -TiDB > CREATE TABLE t (d DECIMAL(10,0)); -Query OK, 0 rows affected (0.01 sec) - -TiDB > INSERT INTO t VALUES(2.5),(2.5E0); -Query OK, 2 rows affected, 2 warnings (0.00 sec) - -TiDB > SELECT d FROM t; -+------+ -| d | -+------+ -| 3 | -| 3 | -+------+ -2 rows in set (0.00 sec) -``` diff --git a/v2.1/reference/sql/functions-and-operators/reference.md b/v2.1/reference/sql/functions-and-operators/reference.md deleted file mode 100644 index dfad15c2b002..000000000000 --- a/v2.1/reference/sql/functions-and-operators/reference.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: 函数和操作符概述 -category: reference ---- - -# 函数和操作符概述 - -TiDB 中函数和操作符使用方法与 MySQL 基本一致，详情参见: [Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/functions.html)。 - -在 SQL 语句中，表达式可用于诸如 `SELECT` 语句的 `ORDER BY` 或 `HAVING` 子句，`SELECT`/`DELETE`/`UPDATE` 语句的 `WHERE` 子句，或 `SET` 语句之类的地方。 - -可使用字面值，列名，NULL，内置函数，操作符等来书写表达式。 diff --git a/v2.1/reference/sql/functions-and-operators/string-functions.md b/v2.1/reference/sql/functions-and-operators/string-functions.md deleted file mode 100644 index 6197b751978c..000000000000 --- a/v2.1/reference/sql/functions-and-operators/string-functions.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: 字符串函数 -category: reference ---- - -# 字符串函数 - -| 函数名 | 功能描述 | -|:----------|:-----------------------| -| [`ASCII()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ascii) | 返回最左字符的数值 | -| [`CHAR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_char)    | 返回由整数的代码值所给出的字符组成的字符串   | -| [`BIN()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_bin) | 返回一个数的二进制值的字符串表示 | -| [`HEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_hex) | 返回十进制值或字符串值的十六进制表示 | -| [`OCT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_oct) | 返回一个数的八进制值的字符串表示 | -| [`UNHEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_unhex) | 返回 HEX 表示的数字所代表的字符串 | -| [`TO_BASE64()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_to-base64) | 返回转换为 BASE64 的字符串参数 | -| [`FROM_BASE64()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_from-base64) | 解码为 BASE64 的字符串并返回结果 | -| [`LOWER()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lower) | 返回小写字母的字符 | -| [`LCASE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lcase) | 与 `LOWER()` 功能相同 | -| [`UPPER()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_upper) | 返回大写字母的字符 | -| [`UCASE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ucase) | 与 `UPPER()` 功能相同 | -| [`LPAD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lpad)                           | 返回左边由指定字符串填充的字符串参数                                                                         | -| [`RPAD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_rpad)                           | 返回右边由指定字符串填充的字符串参数                                                                                               | -| [`TRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_trim) | 删除字符串的前缀和后缀 | -| [`LTRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ltrim)                         | 删除前面的空格字符                                                                                                             | -| [`RTRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_rtrim) | 删除结尾的空格字符 | -| [`BIT_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_bit-length)               | 返回字符串的位长度                                                                                                       | -| [`CHAR_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_char-length)             | 返回字符串的字符长度                                                                                                   | -| [`CHARACTER_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_character-length) | 与 `CHAR_LENGTH()` 功能相同 | -| [`LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_length)                       | 返回字符串的字节长度                                                                                                   | -| [`OCTET_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_octet-length) | 与 `LENGTH()` 功能相同 | -| [`INSERT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_insert) | 在指定位置插入一个子字符串，直到指定的字符数 | -| [`REPLACE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_replace) | 替换指定的字符串 | -| [`SUBSTR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substr) | 返回指定的子字符串 | -| [`SUBSTRING()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substring) | 返回指定的子字符串 | -| [`SUBSTRING_INDEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substring-index) | 返回最终定界符左边或右边的子字符串 | -| [`MID()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_mid) | 返回从指定位置开始的子字符串 | -| [`LEFT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_left) | 返回指定的最左字符 | -| [`RIGHT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_right) | 返回指定的最右字符 | -| [`INSTR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_instr) | 返回子字符串的第一个出现位置 | -| [`LOCATE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_locate) | 返回子字符串的第一个出现位置，与 `INSTR()` 的参数位置相反 | -| [`POSITION()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_position) | 与 `LOCATE()` 功能相同 | -| [`REPEAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_repeat) | 返回重复指定次数的字符串 | -| [`CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_concat) | 返回连接的字符串 | -| [`CONCAT_WS()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_concat-ws) | 返回由分隔符连接的字符串 | -| [`REVERSE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_reverse) | 返回和字符顺序相反的字符串 | -| [`SPACE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_space) | 返回指定数目的空格组成的字符串 | -| [`FIELD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_field) | 返回参数在后续参数中出现的第一个位置 | -| [`ELT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_elt) | 返回指定位置的字符串 | -| [`EXPORT_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_export-set)               | 返回一个字符串，其中值位中设置的每个位，可以得到一个 on 字符串，而每个未设置的位，可以得到一个 off 字符串       | -| [`MAKE_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_make-set)                   | 返回一组逗号分隔的字符串，由位集合中具有相应位的字符串组成                                                   | -| [`FIND_IN_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_find-in-set) | 返回第一个参数在第二个参数中出现的位置 | -| [`FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_format) | 返回指定小数位数格式的数字 | -| [`ORD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ord) | 返回参数中最左字符的字符代码 | -| [`QUOTE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_quote)                         | 引用一个字符串，返回一个在 SQL 语句中可用作正确转义的数据值的结果                                                                                           | - -## 字符串比较函数 - -| 函数名 | 功能描述 | -|:------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------| -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 进行简单模式匹配 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 否定简单模式匹配 | -| [`STRCMP()`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#function_strcmp) | 比较两个字符串 | - -## 正则表达式 - -| 表达式名 | 功能描述 | -|:------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------| -| [`REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 使用正则表达式进行模式匹配 | -| [`RLIKE`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 与 `REGEXP` 功能相同 | -| [`NOT REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_not-regexp) | 否定 `REGEXP` | diff --git a/v2.1/reference/sql/functions-and-operators/type-conversion.md b/v2.1/reference/sql/functions-and-operators/type-conversion.md deleted file mode 100644 index 1a88da5de4da..000000000000 --- a/v2.1/reference/sql/functions-and-operators/type-conversion.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: 表达式求值的类型转换 -category: reference ---- - -# 表达式求值的类型转换 - -TiDB 中表达式求值的类型转换与 MySQL 基本一致，详情参见 [MySQL 表达式求值的类型转换](https://dev.mysql.com/doc/refman/5.7/en/type-conversion.html)。 diff --git a/v2.1/reference/sql/generated-columns.md b/v2.1/reference/sql/generated-columns.md deleted file mode 100644 index 2c2b8f0b3483..000000000000 --- a/v2.1/reference/sql/generated-columns.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: 生成列 -category: reference ---- - -# 生成列 - -为了在功能上兼容 MySQL 5.7，TiDB 支持生成列 (generated column)。生成列的主要的作用之一：从 JSON 数据类型中解出数据，并为该数据建立索引。 - -## 使用 generated stored column 对 JSON 建索引 - -MySQL 5.7 及 TiDB 都不能直接为 JSON 类型的列添加索引，即**不支持**如下表结构： - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - KEY (address_info) -); -``` - -为 JSON 列添加索引之前，首先必须抽取该列为 generated stored column。 - -> **注意：** -> -> 必须是 generated stored column 上建立的索引才能被优化器使用到，如果在 generated virtual column 上建立索引，优化器目前将无法使用这个索引，会在后续版本中改进（ISSUE [#5189](https://github.com/pingcap/tidb/issues/5189)）。 - -以 `city` generated stored column 为例，你可以添加索引： - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED, - KEY (city) -); -``` - -该表中，`city` 列是一个 **generated stored column**。顾名思义，此列由该表的其他列生成，对此列进行插入或更新操作时，并不能对之赋值。此列按其定义的表达式生成，并存储在数据库中，这样在读取此列时，就可以直接读取，不用再读取其依赖的 `address_info` 列后再计算得到。`city` 列的索引**存储在数据库中**，并使用和 `varchar(64)` 类的其他索引相同的结构。 - -可使用 generated stored column 的索引，以提高如下语句的执行速度： - -```sql -SELECT name, id FROM person WHERE city = 'Beijing'; -``` - -如果 `$.city` 路径中无数据，则 `JSON_EXTRACT` 返回 `NULL`。如果想增加约束，`city` 列必须是 `NOT NULL`，则可按照以下方式定义 virtual column： - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED NOT NULL, - KEY (city) -); -``` - -`INSERT` 和 `UPDATE` 语句都会检查 virtual column 的定义。未通过有效性检测的行会返回错误： - -```sql -mysql> INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada')); -ERROR 1048 (23000): Column 'city' cannot be null -``` - -## 使用 generated virtual column - -TiDB 也支持 generated virtual column，和 generated store column 不同的是，此列按需生成，并不存储在数据库中，也不占用内存空间，因而是**虚拟的**。TiDB 虽然支持在 generated virtual column 上建立索引，优化器目前将无法使用这个索引，所以这个索引将没有意义，会在后续版本中改进（ISSUE [#5189](https://github.com/pingcap/tidb/issues/5189)）。 - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) VIRTUAL -); -``` - -## 局限性 - -目前 JSON and generated column 有以下局限性： - -- 不能通过 `ALTER TABLE` 增加 `STORED` 存储方式的 generated column； -- 不能通过 `ALTER TABLE` 在 generated column 上增加索引； -- 不能通过 `ALTER TABLE` 将 generated stored column 转换为普通列，也不能将普通列转换成 generated stored column； -- 不能通过 `ALTER TABLE` 修改 generated stored column 的**生成列表达式**； -- 不支持在 DML 语句中将生成列赋值为 `DEFAULT`； -- 并未支持所有的 [JSON 函数](/v2.1/reference/sql/functions-and-operators/json-functions.md)。 diff --git a/v2.1/reference/sql/language-structure/comment-syntax.md b/v2.1/reference/sql/language-structure/comment-syntax.md deleted file mode 100644 index 7f03f8766c23..000000000000 --- a/v2.1/reference/sql/language-structure/comment-syntax.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: 注释语法 -category: reference ---- - -# 注释语法 - -TiDB 支持三种注释风格： - -* 用 `#` 注释一行 -* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。 -* 用 `/* */` 注释一块，可以注释多行。 - -例： - -``` -mysql> SELECT 1+1; # This comment continues to the end of line -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT 1+1; -- This comment continues to the end of line -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT 1 /* this is an in-line comment */ + 1; -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) - -mysql> SELECT 1+ - -> /* - /*> this is a - /*> multiple-line comment - /*> */ - -> 1; -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) - -mysql> SELECT 1+1--1; -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) -``` - -TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： - -``` -/*! Specific code */ -``` - -在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 - -例如： `SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...` - -在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` - -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。 - -还有一种注释会被当做是优化器 Hint 特殊对待： - -``` -SELECT /*+ hint */ FROM ...; -``` - -由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments - -TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/v2.1/reference/performance/optimizer-hints.md)。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 diff --git a/v2.1/reference/sql/language-structure/expression-syntax.md b/v2.1/reference/sql/language-structure/expression-syntax.md deleted file mode 100644 index d11a4ad8cf16..000000000000 --- a/v2.1/reference/sql/language-structure/expression-syntax.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: 表达式语法 -category: reference ---- - -# 表达式语法 (Expression Syntax) - -在 TiDB 中，以下规则是表达式的语法，你可以在 `parser/parser.y` 中找到定义。TiDB 的语法解析是基于 yacc 的。 - -``` -Expression: - singleAtIdentifier assignmentEq Expression - | Expression logOr Expression - | Expression "XOR" Expression - | Expression logAnd Expression - | "NOT" Expression - | Factor IsOrNotOp trueKwd - | Factor IsOrNotOp falseKwd - | Factor IsOrNotOp "UNKNOWN" - | Factor - -Factor: - Factor IsOrNotOp "NULL" - | Factor CompareOp PredicateExpr - | Factor CompareOp singleAtIdentifier assignmentEq PredicateExpr - | Factor CompareOp AnyOrAll SubSelect - | PredicateExpr - -PredicateExpr: - PrimaryFactor InOrNotOp '(' ExpressionList ')' - | PrimaryFactor InOrNotOp SubSelect - | PrimaryFactor BetweenOrNotOp PrimaryFactor "AND" PredicateExpr - | PrimaryFactor LikeOrNotOp PrimaryExpression LikeEscapeOpt - | PrimaryFactor RegexpOrNotOp PrimaryExpression - | PrimaryFactor - -PrimaryFactor: - PrimaryFactor '|' PrimaryFactor - | PrimaryFactor '&' PrimaryFactor - | PrimaryFactor "<<" PrimaryFactor - | PrimaryFactor ">>" PrimaryFactor - | PrimaryFactor '+' PrimaryFactor - | PrimaryFactor '-' PrimaryFactor - | PrimaryFactor '*' PrimaryFactor - | PrimaryFactor '/' PrimaryFactor - | PrimaryFactor '%' PrimaryFactor - | PrimaryFactor "DIV" PrimaryFactor - | PrimaryFactor "MOD" PrimaryFactor - | PrimaryFactor '^' PrimaryFactor - | PrimaryExpression - -PrimaryExpression: - Operand - | FunctionCallKeyword - | FunctionCallNonKeyword - | FunctionCallAgg - | FunctionCallGeneric - | Identifier jss stringLit - | Identifier juss stringLit - | SubSelect - | '!' PrimaryExpression - | '~' PrimaryExpression - | '-' PrimaryExpression - | '+' PrimaryExpression - | "BINARY" PrimaryExpression - | PrimaryExpression "COLLATE" StringName -``` diff --git a/v2.1/reference/sql/language-structure/keywords-and-reserved-words.md b/v2.1/reference/sql/language-structure/keywords-and-reserved-words.md deleted file mode 100644 index 9c1c1dd22c7e..000000000000 --- a/v2.1/reference/sql/language-structure/keywords-and-reserved-words.md +++ /dev/null @@ -1,445 +0,0 @@ ---- -title: 关键字和保留字 -category: reference ---- - -# 关键字和保留字 - -关键字在 SQL 中有特殊的意义， 例如 `SELECT`，`UPDATE`，`DELETE`，在作为表名跟函数名的时候，需要特殊对待，例如作为表名，保留字需要被反引号包住： - -```sql -mysql> CREATE TABLE select (a INT); -ERROR 1105 (HY000): line 0 column 19 near " (a INT)" (total length 27) -mysql> CREATE TABLE `select` (a INT); -Query OK, 0 rows affected (0.09 sec) -``` - -`BEGIN` 和 `END` 是关键字， 但不是保留字，所以不需要反引号： - -```sql -mysql> CREATE TABLE `select` (BEGIN int, END int); -Query OK, 0 rows affected (0.09 sec) -``` - -有一种特殊情况， 如果使用了限定符 `.`，那么也不需要用反引号： - -```sql -mysql> CREATE TABLE test.select (BEGIN int, END int); -Query OK, 0 rows affected (0.08 sec) -``` - -下表列出了在 TiDB 中的关键字跟保留字，保留字用 (R) 来标识： - -{{< tabs-panel "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z" >}} - -A - -- ACTION -- ADD (R) -- ADDDATE -- ADMIN -- AFTER -- ALL (R) -- ALTER (R) -- ALWAYS -- ANALYZE(R) -- AND (R) -- ANY -- AS (R) -- ASC (R) -- ASCII -- AUTO_INCREMENT -- AVG -- AVG_ROW_LENGTH - -B - -- BEGIN -- BETWEEN (R) -- BIGINT (R) -- BINARY (R) -- BINLOG -- BIT -- BIT_XOR -- BLOB (R) -- BOOL -- BOOLEAN -- BOTH (R) -- BTREE -- BY (R) -- BYTE - -C - -- CASCADE (R) -- CASE (R) -- CAST -- CHANGE (R) -- CHAR (R) -- CHARACTER (R) -- CHARSET -- CHECK (R) -- CHECKSUM -- COALESCE -- COLLATE (R) -- COLLATION -- COLUMN (R) -- COLUMNS -- COMMENT -- COMMIT -- COMMITTED -- COMPACT -- COMPRESSED -- COMPRESSION -- CONNECTION -- CONSISTENT -- CONSTRAINT (R) -- CONVERT (R) -- COUNT -- CREATE (R) -- CROSS (R) -- CURRENT_DATE (R) -- CURRENT_TIME (R) -- CURRENT_TIMESTAMP (R) -- CURRENT_USER (R) -- CURTIME - -D - -- DATA -- DATABASE (R) -- DATABASES (R) -- DATE -- DATE_ADD -- DATE_SUB -- DATETIME -- DAY -- DAY_HOUR (R) -- DAY_MICROSECOND (R) -- DAY_MINUTE (R) -- DAY_SECOND (R) -- DDL -- DEALLOCATE -- DEC -- DECIMAL (R) -- DEFAULT (R) -- DELAY_KEY_WRITE -- DELAYED (R) -- DELETE (R) -- DESC (R) -- DESCRIBE (R) -- DISABLE -- DISTINCT (R) -- DISTINCTROW (R) -- DIV (R) -- DO -- DOUBLE (R) -- DROP (R) -- DUAL (R) -- DUPLICATE -- DYNAMIC - -E - -- ELSE (R) -- ENABLE -- ENCLOSED -- END -- ENGINE -- ENGINES -- ENUM -- ESCAPE -- ESCAPED -- EVENTS -- EXCLUSIVE -- EXECUTE -- EXISTS -- EXPLAIN (R) -- EXTRACT - -F - -- FALSE (R) -- FIELDS -- FIRST -- FIXED -- FLOAT (R) -- FLUSH -- FOR (R) -- FORCE (R) -- FOREIGN (R) -- FORMAT -- FROM (R) -- FULL -- FULLTEXT (R) -- FUNCTION - -G - -- GENERATED (R) -- GET_FORMAT -- GLOBAL -- GRANT (R) -- GRANTS -- GROUP (R) -- GROUP_CONCAT - -H - -- HASH -- HAVING (R) -- HIGH_PRIORITY (R) -- HOUR -- HOUR_MICROSECOND (R) -- HOUR_MINUTE (R) -- HOUR_SECOND (R) - -I - -- IDENTIFIED -- IF (R) -- IGNORE (R) -- IN (R) -- INDEX (R) -- INDEXES -- INFILE (R) -- INNER (R) -- INSERT (R) -- INT (R) -- INTEGER (R) -- INTERVAL (R) -- INTO (R) -- IS (R) -- ISOLATION - -J - -- JOBS -- JOIN (R) -- JSON - -K - -- KEY (R) -- KEY_BLOCK_SIZE -- KEYS (R) -- KILL (R) - -L - -- LEADING (R) -- LEFT (R) -- LESS -- LEVEL -- LIKE (R) -- LIMIT (R) -- LINES (R) -- LOAD (R) -- LOCAL -- LOCALTIME (R) -- LOCALTIMESTAMP (R) -- LOCK (R) -- LONGBLOB (R) -- LONGTEXT (R) -- LOW_PRIORITY (R) - -M - -- MAX -- MAX_ROWS -- MAXVALUE (R) -- MEDIUMBLOB (R) -- MEDIUMINT (R) -- MEDIUMTEXT (R) -- MICROSECOND -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND (R) -- MINUTE_SECOND (R) -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND -- MINUTE_SECOND -- MOD (R) -- MODE -- MODIRY -- MONTH - -N - -- NAMES -- NATIONAL -- NATURAL (R) -- NO -- NO_WRITE_TO_BINLOG (R) -- NONE -- NOT (R) -- NOW -- NULL (R) -- NUMERIC (R) -- NVARCHAR (R) - -O - -- OFFSET -- ON (R) -- ONLY -- OPTION (R) -- OR (R) -- ORDER (R) -- OUTER (R) - -P - -- PARTITION (R) -- PARTITIONS -- PASSWORD -- PLUGINS -- POSITION -- PRECISION (R) -- PREPARE -- PRIMARY (R) -- PRIVILEGES -- PROCEDURE (R) -- PROCESS -- PROCESSLIST - -Q - -- QUARTER -- QUERY -- QUICK - -R - -- RANGE (R) -- READ (R) -- REAL (R) -- REDUNDANT -- REFERENCES (R) -- REGEXP (R) -- RENAME (R) -- REPEAT (R) -- REPEATABLE -- REPLACE (R) -- RESTRICT (R) -- REVERSE -- REVOKE (R) -- RIGHT (R) -- RLIKE (R) -- ROLLBACK -- ROW -- ROW_COUNT -- ROW_FORMAT - -S - -- SCHEMA -- SCHEMAS -- SECOND -- SECOND_MICROSECOND (R) -- SELECT (R) -- SERIALIZABLE -- SESSION -- SET (R) -- SHARE -- SHARED -- SHOW (R) -- SIGNED -- SMALLINT (R) -- SNAPSHOT -- SOME -- SQL_CACHE -- SQL_CALC_FOUND_ROWS (R) -- SQL_NO_CACHE -- START -- STARTING (R) -- STATS -- STATS_BUCKETS -- STATS_HISTOGRAMS -- STATS_META -- STATS_PERSISTENT -- STATUS -- STORED (R) -- SUBDATE -- SUBSTR -- SUBSTRING -- SUM -- SUPER - -T - -- TABLE (R) -- TABLES -- TERMINATED (R) -- TEXT -- THAN -- THEN (R) -- TIDB -- TIDB_INLJ -- TIDB_SMJ -- TIME -- TIMESTAMP -- TIMESTAMPADD -- TIMESTAMPDIFF -- TINYBLOB (R) -- TINYINT (R) -- TINYTEXT (R) -- TO (R) -- TRAILING (R) -- TRANSACTION -- TRIGGER (R) -- TRIGGERS -- TRIM -- TRUE (R) -- TRUNCATE - -U - -- UNCOMMITTED -- UNION (R) -- UNIQUE (R) -- UNKNOWN -- UNLOCK (R) -- UNSIGNED (R) -- UPDATE (R) -- USE (R) -- USER -- USING (R) -- UTC_DATE (R) -- UTC_TIME (R) -- UTC_TIMESTAMP (R) - -V - -- VALUE -- VALUES (R) -- VARBINARY (R) -- VARCHAR (R) -- VARIABLES -- VIEW -- VIRTUAL (R) - -W - -- WARNINGS -- WEEK -- WHEN (R) -- WHERE (R) -- WITH (R) -- WRITE (R) - -X - -- XOR (R) - -Y - -- YEAR -- YEAR_MONTH (R) - -Z - -- ZEROFILL (R) diff --git a/v2.1/reference/sql/language-structure/literal-values.md b/v2.1/reference/sql/language-structure/literal-values.md deleted file mode 100644 index b3815ad9c088..000000000000 --- a/v2.1/reference/sql/language-structure/literal-values.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: 字面值 -category: reference ---- - -# 字面值 - -## String Literals - -String Literals 是一个 bytes 或者 characters 的序列，两端被单引号 `'` 或者双引号 `"` 包围，例如： - -``` -'example string' -"example string" -``` - -如果字符串是连续的，会被合并为一个独立的 string。以下表示是一样的： - -``` -'a string' -'a' ' ' 'string' -"a" ' ' "string" -``` - -如果 `ANSI_QUOTES` SQL MODE 开启了，那么只有单引号内的会被认为是 String Literals，对于双引号内的字符串，会被认为是一个 identifier。 - -binary string 是一串 bytes 组成的字符串，每一个 binary string 有一个叫做 `binary` 的 character set 和 collation。一个非二进制的字符串是一个由字符组成的字符串，它有除 `binary` 外的 character set和与之兼容的 collation。 - -对于两种字符串类型，比较都是基于每个字符的数值。对于 binary string 而言，比较单元就是字节，对于非二进制的字符串，那么单元就是字符，而有的字符集支持多字节字符。 - -一个 String Literal 可以拥有一个可选的 `character set introducer` 和 `COLLATE clause`，可以用来指派特定的字符集跟 collation（TiDB 对此只是做了语法上的兼容，并不实质做处理)。 - -``` -[_charset_name]'string' [COLLATE collation_name] -``` - -例如： - -``` -SELECT _latin1'string'; -SELECT _binary'string'; -SELECT _utf8'string' COLLATE utf8_bin; -``` - -你可以使用 N'literal' 或者 n'literal' 来创建使用 national character set 的字符串，下列语句是一样的： - -``` -SELECT N'some text'; -SELECT n'some text'; -SELECT _utf8'some text'; -``` - -转义字符： - -- \\0: ASCII NUL (X'00') 字符 -- \\': 单引号 -- \\": 双引号 -- \\b: 退格符号 -- \\n: 换行符 -- \\r: 回车符 -- \\t: tab 符（制表符） -- \\z: ASCII 26 (Ctrl + Z) -- \\\\: 反斜杠 \\ -- \\%: \% -- \\_: \_ - -如果要在 string literal 中使用 `'` 或者 `"`，有以下几种办法： - -* 在 `'` 引用的字符串中，可以用 `''` 来表示单引号。 -* 在 `"` 引用的字符串中，可以用 `""` 来表示双引号。 -* 前面接转义符`\`。 -* 在 `'` 中表示 `"` 或者在 `"` 中表示 `'` 都不需要特别的处理。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/string-literals.html)。 - -## Numeric Literals - -数值字面值包括 integer 跟 Decimal 类型跟浮点数字面值。 - -integer 可以包括 `.` 作为小数点分隔，数字前可以有 `-` 或者 `+` 来表示正数或者负数。 - -精确数值字面值可以表示为如下格式：`1, .2, 3.4, -5, -6.78, +9.10`. - -科学记数法也是被允许的，表示为如下格式：`1.2E3, 1.2E-3, -1.2E3, -1.2E-3`。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/number-literals.html)。 - -## NULL Values - -`NULL` 代表数据为空，它是大小写不敏感的，与 `\N`(大小写敏感) 同义。 - -> **注意：** -> -> `NULL` 跟 `0` 并不一样，跟空字符串 `''` 也不一样。 - -## Hexadecimal Literals - -十六进制字面值是有 `X` 和 `0x` 前缀的字符串，后接表示十六进制的数字。注意 `0x` 是大小写敏感的，不能表示为 `0X`。 - -例: - -``` -X'ac12' -X'12AC' -x'ac12' -x'12AC' -0xac12 -0x12AC -``` - -以下是不合法的十六进制字面值： - -``` -X'1z' (z 不是合法的十六进制值) -0X12AC (0X 必须用小写的 0x) -``` - -对于使用 `X'val'` 格式的十六进制字面值，`val` 必须要有一个数字，可以在前面补一个 0 来避免语法错误。 - -```sql -mysql> select X'aff'; -ERROR 1105 (HY000): line 0 column 13 near ""hex literal: invalid hexadecimal format, must even numbers, but 3 (total length 13) -mysql> select X'0aff'; -+---------+ -| X'0aff' | -+---------+ -| - | -+---------+ -1 row in set (0.00 sec) -``` - -默认情况，十六进制字面值是一个二进制字符串。 - -如果需要将一个字符串或者数字转换为十六进制字面值，可以使用内建函数 `HEX()`： - -```sql -mysql> SELECT HEX('TiDB'); -+-------------+ -| HEX('TiDB') | -+-------------+ -| 54694442 | -+-------------+ -1 row in set (0.01 sec) - -mysql> SELECT X'54694442'; -+-------------+ -| X'54694442' | -+-------------+ -| TiDB | -+-------------+ -1 row in set (0.00 sec) -``` - -## Date and Time Literals - -Date 跟 Time 字面值有几种格式，例如用字符串表示，或者直接用数字表示。在 TiDB 里面，当 TiDB 期望一个 Date 的时候，它会把 `'2017-08-24'`， `'20170824'`，`20170824` 当做是 Date。 - -TiDB 的 Date 值有以下几种格式： - -* `'YYYY-MM-DD'` 或者 `'YY-MM-DD'`，这里的 `-` 分隔符并不是严格的，可以是任意的标点符号。比如 `'2017-08-24'`，`'2017&08&24'`， `'2012@12^31'` 都是一样的。唯一需要特别对待的是 '.' 号，它被当做是小数点，用于分隔整数和小数部分。 - Date 和 Time 部分可以被 'T' 分隔，它的作用跟空格符是一样的，例如 `2017-8-24 10:42:00` 跟 `2017-8-24T10:42:00` 是一样的。 -* `'YYYYMMDDHHMMSS'` 或者 `'YYMMDDHHMMSS'`，例如 `'20170824104520'` 和 `'170824104520'` 被当做是 `'2017-08-24 10:45:20'`，但是如果你提供了一个超过范围的值，例如`'170824304520'`，那这就不是一个有效的 Date 字面值。 -* `YYYYMMDDHHMMSS` 或者 `YYMMDDHHMMSS` 注意这里没有单引号或者双引号，是一个数字。例如 `20170824104520`表示为 `'2017-08-24 10:45:20'`。 - -DATETIME 或者 TIMESTAMP 值可以接一个小数部分，用来表示微秒（精度最多到小数点后 6 位），用小数点 `.` 分隔。 - -Dates 如果 year 部分只有两个数字，这是有歧义的（推荐使用四个数字的格式），TiDB 会尝试用以下的规则来解释： - -* year 值如果在 `70-99` 范围，那么被转换成 `1970-1999`。 -* year 值如果在 `00-69` 范围，那么被转换成 `2000-2069`。 - -对于小于 10 的 month 或者 day 值，`'2017-8-4'` 跟 `'2017-08-04'` 是一样的。对于 Time 也是一样，比如 `'2017-08-24 1:2:3'` 跟 `'2017-08-24 01:02:03'`是一样的。 - -在需要 Date 或者 Time 的语境下, 对于数值，TiDB 会根据数值的长度来选定指定的格式： - -* 6 个数字，会被解释为 `YYMMDD`。 -* 12 个数字，会被解释为 `YYMMDDHHMMSS`。 -* 8 个数字，会解释为 `YYYYMMDD`。 -* 14 个数字，会被解释为 `YYYYMMDDHHMMSS`。 - -对于 Time 类型，TiDB 用以下格式来表示： - -* `'D HH:MM:SS'`，或者 `'HH:MM:SS'`，`'HH:MM'`，`'D HH:MM'`，`'D HH'`，`'SS'`，这里的 D 表示 days，合法的范围是 `0-34`。 -* 数值 `HHMMSS`，例如 `231010` 被解释为`'23:10:10'`。 -* 数值 `SS`，`MMSS`，`HHMMSS` 都是可以被当做 Time。 - -Time 类型的小数点也是 `.`，精度最多小数点后 6 位。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-literals.html)。 - -## Boolean Literals - -常量 `TRUE` 和 `FALSE` 等于 1 和 0，它是大小写不敏感的。 - -```sql -mysql> SELECT TRUE, true, tRuE, FALSE, FaLsE, false; -+------+------+------+-------+-------+-------+ -| TRUE | true | tRuE | FALSE | FaLsE | false | -+------+------+------+-------+-------+-------+ -| 1 | 1 | 1 | 0 | 0 | 0 | -+------+------+------+-------+-------+-------+ -1 row in set (0.00 sec) -``` - -## Bit-Value Literals - -位值字面值用 `b` 或者 `0b` 做前缀，后接以 0 跟 1 组成的二进制数字。其中 `0b` 是区分大小写的，`0B` 是会报错的。 - -合法的 Bit-value： - -* b'01' -* B'01' -* 0b01 - -非法的 Bit-value： - -* b'2' (2 不是二进制数值, 必须为 0 或 1) -* 0B01 (0B 必须是小写 0b) - -默认情况，位值字面值是一个二进制字符串。 - -Bit-value 是作为二进制返回的，所以输出到 MySQL Client 可能会显示不出来，如果要转换为可打印的字符，可以使用内建函数 `BIN()` 或者 `HEX()`： - -```sql -CREATE TABLE t (b BIT(8)); -INSERT INTO t SET b = b'00010011'; -INSERT INTO t SET b = b'1110'; -INSERT INTO t SET b = b'100101'; - -mysql> SELECT b+0, BIN(b), HEX(b) FROM t; -+------+--------+--------+ -| b+0 | BIN(b) | HEX(b) | -+------+--------+--------+ -| 19 | 10011 | 13 | -| 14 | 1110 | E | -| 37 | 100101 | 25 | -+------+--------+--------+ -3 rows in set (0.00 sec) -``` diff --git a/v2.1/reference/sql/language-structure/schema-object-names.md b/v2.1/reference/sql/language-structure/schema-object-names.md deleted file mode 100644 index 8bbfc292072a..000000000000 --- a/v2.1/reference/sql/language-structure/schema-object-names.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Schema Object Names -category: reference ---- - -# Schema Object Names - -在 TiDB 中，包括 database，table，index，column，alias 等等都被认为是 identifier (标识符，之后阐述用英文). - -在 TiDB 中，identifier可以被反引号 (\`) 包裹，为了阐述方便，我们叫这种情况为 `被引用`。identifier 也可以不被 \` 包裹。但是如果一个 identifier 存在一个特殊符号或者是一个保留关键字，那么你必须要 `引用` 它。 - -```sql -mysql> SELECT * FROM `table` WHERE `table`.id = 20; -``` - -如果`ANSI_QUOTES` sql mode 被设置了，那么我们认为被双引号 `"` 包裹的字符串为 identifier。 - -```sql -mysql> CREATE TABLE "test" (a varchar(10)); -ERROR 1105 (HY000): line 0 column 19 near " (a varchar(10))" (total length 35) - -mysql> SET SESSION sql_mode='ANSI_QUOTES'; -Query OK, 0 rows affected (0.00 sec) - -mysql> CREATE TABLE "test" (a varchar(10)); -Query OK, 0 rows affected (0.09 sec) -``` - -如果你需要在被引用的 identifier 中使用反引号这个字符，那你需要重复两次，例如你需要创建一个表为 a`b： - -```sql -mysql> CREATE TABLE `a``b` (a int); -``` - -在 select 语句中，alias 语句可以用 identifier 或者字符串： - -```sql -mysql> SELECT 1 AS `identifier`, 2 AS 'string'; -+------------+--------+ -| identifier | string | -+------------+--------+ -| 1 | 2 | -+------------+--------+ -1 row in set (0.00 sec) -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/identifiers.html) - -## Identifier Qualifiers - -Object Names (对象名字) 可以被限定也可以不用。例如你可以在创建表的时候不指定 database names： - -```sql -CREATE TABLE t (i int); -``` - -但是如果你之前没有设定过默认的数据库，会报 `ERROR 1046 (3D000): No database selected` 错误。当然你也可以指定数据库限定名： - -```sql -CREATE TABLE test.t (i int); -``` - -对于 `.` 左右两端可以出现空格，`table_name.col_name` 等于 `table_name . col_name`。 - -如果你要引用这个 identifier，那么请使用： - -``` -`table_name`.`col_name` -``` - -而不是： - -``` -`table_name.col_name` -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/identifier-qualifiers.html) diff --git a/v2.1/reference/sql/language-structure/user-defined-variables.md b/v2.1/reference/sql/language-structure/user-defined-variables.md deleted file mode 100644 index 069bfcc71b34..000000000000 --- a/v2.1/reference/sql/language-structure/user-defined-variables.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: 用户自定义变量 -category: reference ---- - -# 用户自定义变量 - -用户自定义变量格式为 `@var_name`。`var_name` 目前只支持字母，数字，`_$`组成。用户自定义变量是大小写不敏感的。 - -用户自定义变量是跟 session 绑定的，也就是说只有当前连接可以看见设置的用户变量，其他客户端连接无法查看到。 - -用 `SET` 语句可以设置用户自定义变量： - -```sql -SET @var_name = expr [, @var_name = expr] ... -或 -SET @var_name := expr -``` - -对于 `SET` 语句，赋值操作符可以是 `=` 也可以是 `:=` - -例： - -```sql -mysql> SET @a1=1, @a2=2, @a3:=4; -mysql> SELECT @a1, @a2, @t3, @a4 := @a1+@a2+@a3; -+------+------+------+--------------------+ -| @a1 | @a2 | @a3 | @a4 := @a1+@a2+@a3 | -+------+------+------+--------------------+ -| 1 | 2 | 4 | 7 | -+------+------+------+--------------------+ -``` - -如果设置用户变量用了 `HEX` 或者 `BIT` 值，TiDB会把它当成二进制字符串。如果你要将其设置成数字，那么需要手动加上 `CAST转换`: `CAST(.. AS UNSIGNED)`： - -```sql -mysql> SELECT @v1, @v2, @v3; -+------+------+------+ -| @v1 | @v2 | @v3 | -+------+------+------+ -| A | 65 | 65 | -+------+------+------+ -1 row in set (0.00 sec) - -mysql> SET @v1 = b'1000001'; -Query OK, 0 rows affected (0.00 sec) - -mysql> SET @v2 = b'1000001'+0; -Query OK, 0 rows affected (0.00 sec) - -mysql> SET @v3 = CAST(b'1000001' AS UNSIGNED); -Query OK, 0 rows affected (0.00 sec) - -mysql> SELECT @v1, @v2, @v3; -+------+------+------+ -| @v1 | @v2 | @v3 | -+------+------+------+ -| A | 65 | 65 | -+------+------+------+ -1 row in set (0.00 sec) -``` - -如果获取一个没有设置过的变量，会返回一个 NULL： - -```sql -mysql> select @not_exist; -+------------+ -| @not_exist | -+------------+ -| NULL | -+------------+ -1 row in set (0.00 sec) -``` - -用户自定义变量不能直接在 SQL 语句中被当成 identifier，例： - -```sql -mysql> select * from t; -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) - -mysql> SET @col = "a"; -Query OK, 0 rows affected (0.00 sec) - -mysql> SELECT @col FROM t; -+------+ -| @col | -+------+ -| a | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT `@col` FROM t; -ERROR 1054 (42S22): Unknown column '@col' in 'field list' - -mysql> SET @col = "`a`"; -Query OK, 0 rows affected (0.00 sec) - -mysql> SELECT @col FROM t; -+------+ -| @col | -+------+ -| `a` | -+------+ -1 row in set (0.01 sec) -``` - -但是有一个例外是如果你在 PREPARE 语句中使用它，是可以的： - -```sql -mysql> PREPARE stmt FROM "SELECT @c FROM t"; -Query OK, 0 rows affected (0.00 sec) - -mysql> EXECUTE stmt; -+------+ -| @c | -+------+ -| a | -+------+ -1 row in set (0.01 sec) - -mysql> DEALLOCATE PREPARE stmt; -Query OK, 0 rows affected (0.00 sec) -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/user-variables.html)。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/add-column.md b/v2.1/reference/sql/statements/add-column.md deleted file mode 100644 index 2121b3715d8e..000000000000 --- a/v2.1/reference/sql/statements/add-column.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: ADD COLUMN -summary: TiDB 数据库中 ADD COLUMN 的使用概况。 -category: reference ---- - -# ADD COLUMN - -`ALTER TABLE.. ADD COLUMN` 语句用于在已有表中添加列。在 TiDB 中，`ADD COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 VALUES (NULL); -Query OK, 1 row affected (0.02 sec) - -mysql> SELECT * FROM t1; -+----+ -| id | -+----+ -| 1 | -+----+ -1 row in set (0.00 sec) - -mysql> ALTER TABLE t1 ADD COLUMN c1 INT NOT NULL; -Query OK, 0 rows affected (0.28 sec) - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 0 | -+----+----+ -1 row in set (0.00 sec) - -mysql> ALTER TABLE t1 ADD c2 INT NOT NULL AFTER c1; -Query OK, 0 rows affected (0.28 sec) - -mysql> SELECT * FROM t1; -+----+----+----+ -| id | c1 | c2 | -+----+----+----+ -| 1 | 0 | 0 | -+----+----+----+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持同时添加多列。 -* 不支持将新添加的列设为 `PRIMARY KEY`。 -* 不支持将新添加的列设为 `AUTO_INCREMENT`。 - -## 另请参阅 - -* [ADD INDEX](/v2.1/reference/sql/statements/add-index.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) diff --git a/v2.1/reference/sql/statements/add-index.md b/v2.1/reference/sql/statements/add-index.md deleted file mode 100644 index ebe38ef80492..000000000000 --- a/v2.1/reference/sql/statements/add-index.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: ADD INDEX -summary: TiDB 数据库中 ADD INDEX 的使用概况。 -category: reference ---- - -# ADD INDEX - -`ALTER TABLE.. ADD INDEX` 语句用于在已有表中添加一个索引。在 TiDB 中，`ADD INDEX` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> ALTER TABLE t1 ADD INDEX (c1); -Query OK, 0 rows affected (0.30 sec) - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引（类似于 MySQL 5.7）。 -* 目前尚不支持同时添加多个索引。 -* 无法向表中添加 `PRIMARY KEY`。 - -## 另请参阅 - -* [CREATE INDEX](/v2.1/reference/sql/statements/create-index.md) -* [DROP INDEX](/v2.1/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v2.1/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/v2.1/reference/sql/statements/add-column.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [EXPLAIN](/v2.1/reference/sql/statements/explain.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/admin.md b/v2.1/reference/sql/statements/admin.md deleted file mode 100644 index 119e80a12504..000000000000 --- a/v2.1/reference/sql/statements/admin.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: ADMIN 语句 -category: reference ---- - -# `ADMIN` 语句 - -`ADMIN` 语句是 TiDB 扩展语法，用于查看 TiDB 自身的状态，并对 TiDB 中的表数据进行校验。示例如下。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL -``` - -`ADMIN SHOW DDL` 用于查看当前正在执行的 DDL 作业。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOBS -``` - -`ADMIN SHOW DDL JOBS` 用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ... -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CANCEL DDL JOBS job_id [, job_id] ... -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CHECK TABLE tbl_name [, tbl_name] ... -``` - -## 语句概览 - -**AdminStmt**： - -![AdminStmt](/media/sqlgram/AdminStmt.png) - -## 使用示例 - -{{< copyable "sql" >}} - -```sql -admin show ddl jobs; -``` - -``` -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | running | -| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | rollback done | -| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | synced | -| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | synced | -| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | synced | -| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | synced | -| 39 | test | t1 | add column | public | 32 | 37 | 0 | 2019-01-10 12:32:55.42 +0800 CST | synced | -| 38 | test | t1 | create table | public | 32 | 37 | 0 | 2019-01-10 12:32:41.956 +0800 CST | synced | -| 36 | test | | drop table | none | 32 | 34 | 0 | 2019-01-10 11:29:59.982 +0800 CST | synced | -| 35 | test | | create table | public | 32 | 34 | 0 | 2019-01-10 11:29:40.741 +0800 CST | synced | -| 33 | test | | create schema | public | 32 | 0 | 0 | 2019-01-10 11:29:22.813 +0800 CST | synced | -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -``` - -* `JOB_ID`：每个 DDL 操作对应一个 DDL 作业，`JOB_ID` 全局唯一。 -* `DB_NAME`：执行 DDL 操作的数据库的名称。 -* `TABLE_NAME`：执行 DDL 操作的表的名称。 -* `JOB_TYPE`：DDL 操作的类型。 -* `SCHEMA_STATE`：schema 的当前状态。如果 `JOB_TYPE` 是 `add index`，则为 index 的状态；如果是 `add column`，则为 column 的状态，如果是 `create table`，则为 table 的状态。常见的状态有以下几种： - * `none`：表示不存在。一般 `drop` 操作或者 `create` 操作失败回滚后，会变为 `none` 状态。 - * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在 [Online, Asynchronous Schema Change in F1](http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。 - * `public`：表示存在且可用。一般 `create table` 和 `add index/column` 等操作完成后，会变为 `public` 状态，表示新建的 table/column/index 可以正常读写了。 -* `SCHEMA_ID`：执行 DDL 操作的数据库的 ID。 -* `TABLE_ID`：执行 DDL 操作的表的 ID。 -* `ROW_COUNT`：执行 `add index` 操作时，当前已经添加完成的数据行数。 -* `START_TIME`：DDL 操作的开始时间。 -* `STATE`：DDL 操作的状态。常见的状态有以下几种： - * `none`：表示该操作任务已经进入 DDL 作业队列中，但尚未执行，因为还在排队等待前面的 DDL 作业完成。另一种原因可能是执行 `drop` 操作后，会变为 `none` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。 - * `running`：表示该操作正在执行。 - * `synced`：表示该操作已经执行成功，且所有 TiDB 实例都已经同步该状态。 - * `rollback done`：表示该操作执行失败，回滚完成。 - * `rollingback`：表示该操作执行失败，正在回滚。 - * `cancelling`：表示正在取消该操作。这个状态只有在用 `ADMIN CANCEL DDL JOBS` 命令取消 DDL 作业时才会出现。 - -- `ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...`：用于查看 `job_id` 对应的 DDL 任务的原始 SQL 语句。这个 `job_id` 只会搜索正在运行中的 DDL 作业以及 DDL 历史作业队列中最近的十条结果。 -- `ADMIN CANCEL DDL JOBS job_id [, job_id] ...`：用于取消当前正在运行的 DDL 作业，并返回对应作业是否取消成功。如果取消失败，会显示失败的具体原因。 - - > **注意：** - > - > - 只有该操作可以取消 DDL 作业，其他所有的操作和环境变更（例如机器重启、集群重启）都不会取消 DDL 作业。 - > - 该操作可以同时取消多个 DDL 作业。可以通过 `ADMIN SHOW DDL JOBS` 语句来获取 DDL 作业的 ID。 - > - 如果希望取消的作业已经完成，则取消操作将会失败。 - -- `ADMIN CHECK TABLE tbl_name [, tbl_name] ...`：用于对给定表中的所有数据和对应索引进行一致性校验，若通过校验，则返回空的查询结果；否则返回数据不一致的错误信息。 - -## MySQL 兼容性 - -ADMIN 语句是 TiDB 对于 MySQL 语法的扩展。 diff --git a/v2.1/reference/sql/statements/alter-database.md b/v2.1/reference/sql/statements/alter-database.md deleted file mode 100644 index c3222e975b29..000000000000 --- a/v2.1/reference/sql/statements/alter-database.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: ALTER DATABASE -summary: TiDB 数据库中 ALTER DATABASE 的使用概况。 -category: reference ---- - -# ALTER DATABASE - -`ALTER DATABASE` 用于修改指定或当前数据库的默认字符集和排序规则。`ALTER SCHEMA` 跟 `ALTER DATABASE` 操作效果一样。 - -## 示例 - -```sql -ALTER {DATABASE | SCHEMA} [db_name] - alter_specification ... -alter_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -`alter_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/v2.1/reference/sql/character-set.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v2.1/reference/sql/statements/create-database.md) -* [SHOW DATABASES](/v2.1/reference/sql/statements/show-databases.md) diff --git a/v2.1/reference/sql/statements/alter-table.md b/v2.1/reference/sql/statements/alter-table.md deleted file mode 100644 index ce29e5c920f9..000000000000 --- a/v2.1/reference/sql/statements/alter-table.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: ALTER TABLE -summary: TiDB 数据库中 ALTER TABLE 的使用概况。 -category: reference ---- - -# ALTER TABLE - -`ALTER TABLE` 语句用于对已有表进行修改，以符合新表结构。`ALTER TABLE` 语句可用于： - -* [`ADD`](/v2.1/reference/sql/statements/add-index.md)，[`DROP`](/v2.1/reference/sql/statements/drop-index.md)，或 [`RENAME`](/v2.1/reference/sql/statements/rename-index.md) 索引 -* [`ADD`](/v2.1/reference/sql/statements/add-column.md)，[`DROP`](/v2.1/reference/sql/statements/drop-column.md)，[`MODIFY`](/v2.1/reference/sql/statements/modify-column.md) 或 [`CHANGE`](/v2.1/reference/sql/statements/change-column.md) 列 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> ALTER TABLE t1 ADD INDEX (c1); -Query OK, 0 rows affected (0.30 sec) - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 支持除空间类型外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 - -## 另请参阅 - -* [ADD COLUMN](/v2.1/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v2.1/reference/sql/statements/drop-column.md) -* [ADD INDEX](/v2.1/reference/sql/statements/add-index.md) -* [DROP INDEX](/v2.1/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v2.1/reference/sql/statements/rename-index.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v2.1/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) diff --git a/v2.1/reference/sql/statements/alter-user.md b/v2.1/reference/sql/statements/alter-user.md deleted file mode 100644 index 99bbba744a2d..000000000000 --- a/v2.1/reference/sql/statements/alter-user.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: ALTER USER -summary: TiDB 数据库中 ALTER USER 的使用概况。 -category: reference ---- - -# ALTER USER - -`ALTER USER` 语句用于更改 TiDB 权限系统内的已有用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**AlterUserStmt:** - -![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -## 示例 - -```sql -mysql> CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -Query OK, 1 row affected (0.01 sec) - -mysql> SELECT USER, HOST, PASSWORD FROM mysql.`user` WHERE USER = 'newuser'; -+---------+------+-------------------------------------------+ -| USER | HOST | PASSWORD | -+---------+------+-------------------------------------------+ -| newuser | % | *5806E04BBEE79E1899964C6A04D68BCA69B1A879 | -+---------+------+-------------------------------------------+ -1 row in set (0.00 sec) - -mysql> ALTER USER 'newuser' IDENTIFIED BY 'newnewpassword'; -Query OK, 0 rows affected (0.02 sec) - -mysql> SELECT USER, HOST, PASSWORD FROM mysql.`user` WHERE USER = 'newuser'; -+---------+------+-------------------------------------------+ -| USER | HOST | PASSWORD | -+---------+------+-------------------------------------------+ -| newuser | % | *FB8A1EA1353E8775CA836233E367FBDFCB37BE73 | -+---------+------+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，`ALTER` 语句用于更改属性，例如使密码失效。但 TiDB 尚未支持此功能。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/v2.1/reference/security/compatibility.md) -* [CREATE USER](/v2.1/reference/sql/statements/create-user.md) -* [DROP USER](/v2.1/reference/sql/statements/drop-user.md) diff --git a/v2.1/reference/sql/statements/analyze-table.md b/v2.1/reference/sql/statements/analyze-table.md deleted file mode 100644 index 5a6c82beb2e7..000000000000 --- a/v2.1/reference/sql/statements/analyze-table.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: ANALYZE TABLE -summary: TiDB 数据库中 ANALYZE TABLE 的使用概况。 -category: reference ---- - -# ANALYZE TABLE - -`ANALYZE TABLE` 语句用于更新 TiDB 在表和索引上留下的统计信息。执行大批量更新或导入记录后，或查询执行计划不是最佳时，建议运行 `ANALYZE TABLE`。 - -当 TiDB 逐渐发现这些统计数据与预估不一致时，也会自动更新其统计数据。 - -## 语法图 - -**AnalyzeTableStmt:** - -![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> ALTER TABLE t1 ADD INDEX (c1); -Query OK, 0 rows affected (0.30 sec) - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) - -mysql> analyze table t1; -Query OK, 0 rows affected (0.13 sec) - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+-------------------+-------+------+---------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------------------------------------------+ -| IndexReader_6 | 1.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 1.00 | cop | table:t1, index:c1, range:[3,3], keep order:false | -+-------------------+-------+------+---------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`ANALYZE TABLE` 在语法上与 MySQL 类似。但 `ANALYZE TABLE` 在 TiDB 上执行所需时间可能长得多，因为它的内部运行方式不同。 - -## 另请参阅 - -* [EXPLAIN](/v2.1/reference/sql/statements/explain.md) -* [EXPLAIN ANALYZE](/v2.1/reference/sql/statements/explain-analyze.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/begin.md b/v2.1/reference/sql/statements/begin.md deleted file mode 100644 index 0ee02f8d5524..000000000000 --- a/v2.1/reference/sql/statements/begin.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: BEGIN -summary: TiDB 数据库中 BEGIN 的使用概况。 -category: reference ---- - -# BEGIN - -`BEGIN` 语句用于在 TiDB 内启动一个新事务，类似于 `START TRANSACTION` 和 `SET autocommit=0` 语句。 - -在没有 `BEGIN` 语句的情况下，每个语句默认在各自的事务中自动提交，从而确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -Query OK, 0 rows affected (0.12 sec) - -mysql> BEGIN; -Query OK, 0 rows affected (0.00 sec) - -mysql> INSERT INTO t1 VALUES (1); -Query OK, 1 row affected (0.00 sec) - -mysql> COMMIT; -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`BEGIN` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上[提交 issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v2.1/reference/sql/statements/commit.md) -* [ROLLBACK](/v2.1/reference/sql/statements/rollback.md) -* [START TRANSACTION](/v2.1/reference/sql/statements/start-transaction.md) diff --git a/v2.1/reference/sql/statements/change-column.md b/v2.1/reference/sql/statements/change-column.md deleted file mode 100644 index b0e8fcd12169..000000000000 --- a/v2.1/reference/sql/statements/change-column.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: CHANGE COLUMN -summary: TiDB 数据库中 CHANGE COLUMN 的使用概况。 -category: reference ---- - -# CHANGE COLUMN - -`ALTER TABLE.. CHANGE COLUMN` 语句用于在已有表上更改列，包括对列进行重命名，和将数据改为兼容类型。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> -mysql> ALTER TABLE t1 CHANGE col1 col2 INT; -Query OK, 0 rows affected (0.09 sec) - -mysql> ALTER TABLE t1 CHANGE col2 col3 BIGINT, ALGORITHM=INSTANT; -Query OK, 0 rows affected (0.08 sec) - -mysql> -mysql> ALTER TABLE t1 CHANGE col3 col3 INT; -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -mysql> ALTER TABLE t1 CHANGE col3 col3 BLOB; -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -mysql> ALTER TABLE t1 CHANGE col3 col4 BIGINT, CHANGE id id2 INT NOT NULL; -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前尚不支持在单个 `ALTER TABLE` 语句中进行多个更改。 -* 仅支持特定的数据类型更改。例如，支持将 `INTEGER` 更改为 `BIGINT`，但不支持将 `BIGINT` 更改为 `INTEGER`。不支持从整数更改为字符串格式或 BLOB 类型。 - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/v2.1/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v2.1/reference/sql/statements/drop-column.md) -* [MODIFY COLUMN](/v2.1/reference/sql/statements/modify-column.md) diff --git a/v2.1/reference/sql/statements/commit.md b/v2.1/reference/sql/statements/commit.md deleted file mode 100644 index 0ed51a03bba7..000000000000 --- a/v2.1/reference/sql/statements/commit.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: COMMIT -summary: TiDB 数据库中 COMMIT 的使用概况。 -category: reference ---- - -# COMMIT - -`COMMIT` 语句用于在 TiDB 服务器内部提交事务。 - -在不使用 `BEGIN` 或 `START TRANSACTION` 语句的情况下，TiDB 中每一个查询语句本身也会默认作为事务处理，自动提交，确保了与 MySQL 的兼容。 - -## 语法图 - -**CommitStmt:** - -![CommitStmt](/media/sqlgram/CommitStmt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -Query OK, 0 rows affected (0.12 sec) - -mysql> START TRANSACTION; -Query OK, 0 rows affected (0.00 sec) - -mysql> INSERT INTO t1 VALUES (1); -Query OK, 1 row affected (0.00 sec) - -mysql> COMMIT; -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，除了有多个 primary 的群组复制以外，`COMMIT` 语句通常不会导致错误。相比之下，TiDB 使用乐观并发控制，冲突可能导致 `COMMIT` 返回错误。 -* 默认情况下，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。 - -## 另请参阅 - -* [START TRANSACTION](/v2.1/reference/sql/statements/start-transaction.md) -* [ROLLBACK](/v2.1/reference/sql/statements/rollback.md) -* [BEGIN](/v2.1/reference/sql/statements/begin.md) -* [事务的惰性检查](/v2.1/reference/transactions/overview.md#事务的惰性检查) diff --git a/v2.1/reference/sql/statements/create-database.md b/v2.1/reference/sql/statements/create-database.md deleted file mode 100644 index f04a744ba483..000000000000 --- a/v2.1/reference/sql/statements/create-database.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: CREATE DATABASE -summary: TiDB 数据库中 CREATE DATABASE 的使用概况。 -category: reference ---- - -# CREATE DATABASE - -`CREATE DATABASE` 语句用于在 TiDB 上创建新数据库。按照 SQL 标准，“数据库” 一词在 MySQL 术语中最接近 “schema”。 - -## 语法图 - -**CreateDatabaseStmt:** - -![CreateDatabaseStmt](/media/sqlgram/CreateDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -**DatabaseOptionListOpt:** - -![DatabaseOptionListOpt](/media/sqlgram/DatabaseOptionListOpt.png) - -## 语法说明 - -`CREATE DATABASE` 用于创建数据库，并可以指定数据库的默认属性（如数据库默认字符集、校验规则。`CREATE SCHEMA` 跟 `CREATE DATABASE` 操作效果一样。 - -```sql -CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name - [create_specification] ... - -create_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -当创建已存在的数据库且不指定使用 `IF NOT EXISTS` 时会报错。 - -`create_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前这个选项只是语法支持。 - -## 示例 - -```sql -mysql> CREATE DATABASE mynewdatabase; -Query OK, 0 rows affected (0.09 sec) - -mysql> USE mynewdatabase; -Database changed -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.11 sec) - -mysql> SHOW TABLES; -+-------------------------+ -| Tables_in_mynewdatabase | -+-------------------------+ -| t1 | -+-------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [USE](/v2.1/reference/sql/statements/use.md) -* [ALTER DATABASE](/v2.1/reference/sql/statements/alter-database.md) -* [DROP DATABASE](/v2.1/reference/sql/statements/drop-database.md) -* [SHOW DATABASES](/v2.1/reference/sql/statements/show-databases.md) diff --git a/v2.1/reference/sql/statements/create-index.md b/v2.1/reference/sql/statements/create-index.md deleted file mode 100644 index a3c3ba225110..000000000000 --- a/v2.1/reference/sql/statements/create-index.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: CREATE INDEX -summary: CREATE INDEX 在 TiDB 中的使用概况 -category: reference ---- - -# CREATE INDEX - -`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 `ALTER TABLE .. ADD INDEX`。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**CreateIndexStmt:** - -![CreateIndexStmt](/media/sqlgram/CreateIndexStmt.png) - -**CreateIndexStmtUnique:** - -![CreateIndexStmtUnique](/media/sqlgram/CreateIndexStmtUnique.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -**IndexTypeOpt:** - -![IndexTypeOpt](/media/sqlgram/IndexTypeOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**IndexColNameList:** - -![IndexColNameList](/media/sqlgram/IndexColNameList.png) - -**IndexOptionList:** - -![IndexOptionList](/media/sqlgram/IndexOptionList.png) - -**IndexOption:** - -![IndexOption](/media/sqlgram/IndexOption.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.10 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> CREATE INDEX c1 ON t1 (c1); -Query OK, 0 rows affected (0.30 sec) - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) - -mysql> ALTER TABLE t1 DROP INDEX c1; -Query OK, 0 rows affected (0.30 sec) - -mysql> CREATE UNIQUE INDEX c1 ON t1 (c1); -Query OK, 0 rows affected (0.31 sec) -``` - -## 相关 session 变量 - -和 `CREATE INDEX` 语句相关的全局变量有 `tidb_ddl_reorg_worker_cnt`，`tidb_ddl_reorg_batch_size` 和 `tidb_ddl_reorg_priority`，具体可以参考 [TiDB 特定系统变量](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_ddl_reorg_worker_cnt)。 - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引 （类似于 MySQL 5.7）。 -* 无法向表中添加 `PRIMARY KEY`。 - -## 另请参阅 - -* [ADD INDEX](/v2.1/reference/sql/statements/add-index.md) -* [DROP INDEX](/v2.1/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v2.1/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/v2.1/reference/sql/statements/add-column.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [EXPLAIN](/v2.1/reference/sql/statements/explain.md) diff --git a/v2.1/reference/sql/statements/create-table-like.md b/v2.1/reference/sql/statements/create-table-like.md deleted file mode 100644 index c23444241484..000000000000 --- a/v2.1/reference/sql/statements/create-table-like.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: CREATE TABLE LIKE -summary: TiDB 数据库中 CREATE TABLE LIKE 的使用概况。 -category: reference ---- - -# CREATE TABLE LIKE - -`CREATE TABLE LIKE` 语句用于复制已有表的定义，但不复制任何数据。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**LikeTableWithOrWithoutParen:** - -![LikeTableWithOrWithoutParen](/media/sqlgram/LikeTableWithOrWithoutParen.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a INT NOT NULL); -Query OK, 0 rows affected (0.13 sec) - -mysql> INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) - -mysql> CREATE TABLE t2 LIKE t1; -Query OK, 0 rows affected (0.10 sec) - -mysql> SELECT * FROM t2; -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE TABLE LIKE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) diff --git a/v2.1/reference/sql/statements/create-table.md b/v2.1/reference/sql/statements/create-table.md deleted file mode 100644 index 98a69691d25f..000000000000 --- a/v2.1/reference/sql/statements/create-table.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: CREATE TABLE -summary: TiDB 数据库中 CREATE TABLE 的使用概况 -category: reference ---- - -# CREATE TABLE - -`CREATE TABLE` 语句用于在当前所选数据库中创建新表。另可参阅单独的 `CREATE TABLE LIKE` 文档。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**TableElementListOpt:** - -![TableElementListOpt](/media/sqlgram/TableElementListOpt.png) - -**TableElement:** - -![TableElement](/media/sqlgram/TableElement.png) - -**PartitionOpt:** - -![PartitionOpt](/media/sqlgram/PartitionOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**Type:** - -![Type](/media/sqlgram/Type.png) - -**ColumnOptionListOpt:** - -![ColumnOptionListOpt](/media/sqlgram/ColumnOptionListOpt.png) - -**TableOptionListOpt:** - -![TableOptionListOpt](/media/sqlgram/TableOptionListOpt.png) - -## 语法说明 - -`CREATE TABLE` 用于创建一个表。目前不支持临时表，不支持 `CHECK` 约束，不支持创建表的同时从其它表导入数据功能。在语法上也支持一些 `Partition_options`，但是并不完全，就不做列举了。 - -以下是 `CREATE TABLE` 相关的语法说明： - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - (create_definition,...) - [table_options] -``` - -使用 `IF NOT EXIST` 时，即使创建的表已经存在，也不会报错，如果不指定时，则报错。 - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - { LIKE old_tbl_name | (LIKE old_tbl_name) } -``` - -使用 `LIKE` 基于一个表的定义创建一个空表，包括这个表中的列属性和索引属性。 - -```sql -create_definition: - col_name column_definition - | [CONSTRAINT [symbol]] PRIMARY KEY [index_type] (index_col_name,...) - [index_option] ... - | {INDEX|KEY} [index_name] [index_type] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY] - [index_name] [index_type] (index_col_name,...) - [index_option] ... - | {FULLTEXT} [INDEX|KEY] [index_name] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] FOREIGN KEY - [index_name] (index_col_name,...) reference_definition -``` - -`create_definition` 中 `FULLTEXT` 和 `FOREIGN KEY` 目前只是语法上支持。 - -```sql -column_definition: - data_type [NOT NULL | NULL] [DEFAULT default_value] - [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] - [COMMENT 'string'] - [reference_definition] - | data_type [GENERATED ALWAYS] AS (expression) - [VIRTUAL | STORED] [UNIQUE [KEY]] [COMMENT comment] - [NOT NULL | NULL] [[PRIMARY] KEY] - -data_type: - BIT[(length)] - | TINYINT[(length)] [UNSIGNED] [ZEROFILL] - | SMALLINT[(length)] [UNSIGNED] [ZEROFILL] - | MEDIUMINT[(length)] [UNSIGNED] [ZEROFILL] - | INT[(length)] [UNSIGNED] [ZEROFILL] - | INTEGER[(length)] [UNSIGNED] [ZEROFILL] - | BIGINT[(length)] [UNSIGNED] [ZEROFILL] - | REAL[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DOUBLE[(length,decimals)] [UNSIGNED] [ZEROFILL] - | FLOAT[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DECIMAL[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | NUMERIC[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | DATE - | TIME[(fsp)] - | TIMESTAMP[(fsp)] - | DATETIME[(fsp)] - | YEAR - | CHAR[(length)] [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | VARCHAR(length) [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | BINARY[(length)] - | VARBINARY(length) - | TINYBLOB - | BLOB - | MEDIUMBLOB - | LONGBLOB - | TINYTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | TEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | MEDIUMTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | LONGTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | ENUM(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | SET(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | JSON -``` - -`data_type` 请参考[数据类型](/v2.1/reference/sql/data-types/overview.md)章节。 - -```sql -index_col_name: - col_name [(length)] [ASC | DESC] -``` - -`index_col_name` 中 `[ASC | DESC]` 目前只是语法上支持。 - -```sql -index_type: - USING {BTREE | HASH} -``` - -`index_type` 目前只是语法上支持。 - -```sql -index_option: - KEY_BLOCK_SIZE [=] value - | index_type - | COMMENT 'string' -``` - -`index_option` 中 `KEY_BLOCK_SIZE` 目前只是语法上支持。 - -```sql -reference_definition: - REFERENCES tbl_name (index_col_name,...) - [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] - [ON DELETE reference_option] - [ON UPDATE reference_option] - -reference_option: - RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT -``` - -```sql -table_options: - table_option [[,] table_option] ... - -table_option: - AUTO_INCREMENT [=] value - | AVG_ROW_LENGTH [=] value - | [DEFAULT] CHARACTER SET [=] charset_name - | CHECKSUM [=] {0 | 1} - | [DEFAULT] COLLATE [=] collation_name - | COMMENT [=] 'string' - | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'} - | CONNECTION [=] 'connect_string' - | DELAY_KEY_WRITE [=] {0 | 1} - | ENGINE [=] engine_name - | KEY_BLOCK_SIZE [=] value - | MAX_ROWS [=] value - | MIN_ROWS [=] value - | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT} - | STATS_PERSISTENT [=] {DEFAULT|0|1} -``` - -`table_option` 目前支持的只有 `AUTO_INCREMENT`、`SHARD_ROW_ID_BITS`（详情介绍请参考 [TiDB 专用系统变量和语法](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）、`PRE_SPLIT_REGIONS`、`CHARACTER SET`、`COLLATE` 和 `COMMENT`，其它只是语法上支持。具体内容参考下表，各个子句之间用逗号隔开。 - -| 参数 |含义 |举例 | -|----------------|--------------------------------------|----------------------------| -|`AUTO_INCREMENT`|自增字段初始值 |`AUTO_INCREMENT` = 5| -|`SHARD_ROW_ID_BITS`|用来设置隐式 _tidb_rowid 的分片数量的 bit 位数 |`SHARD_ROW_ID_BITS` = 4| -|`PRE_SPLIT_REGIONS`|用来在建表时预先均匀切分 `2^(PRE_SPLIT_REGIONS)` 个 Region |`PRE_SPLIT_REGIONS` = 4| -|`CHARACTER SET` |指定该表的字符串编码。目前支持 UTF8MB4| `CHARACTER SET` = 'utf8mb4'| -|`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| -|`COMMENT` |注释信息 | `COMMENT` = 'comment info'| - -> **注意：** -> -> 在 TiDB 2.1 版本中，`SHARD_ROW_ID_BITS`、`PRE_SPLIT_REGIONS` 和 `COLLATE` 这三个功能都是从 2.1.13 版本（包括 2.1.13）开始支持的。 - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.11 sec) - -mysql> CREATE TABLE t2 LIKE t1; -Query OK, 0 rows affected (0.10 sec) - -mysql> DESC t1; -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) - -mysql> INSERT INTO t1 VALUES (1); -Query OK, 1 row affected (0.02 sec) - -mysql> SELECT * FROM t1; -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 不支持 `CREATE TEMPORARY TABLE` 语法。 -* 支持除空间类型以外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* `KEY_BLOCK_SIZE` 和 `ENGINE` 属性可被解析，但会被忽略。 -* `index_col_name` 属性支持 length 选项，最大长度限制为 3072 字节。此长度限制不会更改，具体取决于存储引擎和建表时使用的字符集。 -* `index_col_name` 属性支持 `ASC` 和 `DESC` 的索引排序选项。 -* `COMMENT` 属性最多支持 1024 个字符，不支持 `WITH PARSER` 选项。 -* TiDB 在单个表中最多支持 512 列。InnoDB 中相应的数量限制为 1017，MySQL 中的硬限制为 4096。 - -## 另请参阅 - -* [DROP TABLE](/v2.1/reference/sql/statements/drop-table.md) -* [CREATE TABLE LIKE](/v2.1/reference/sql/statements/create-table-like.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) diff --git a/v2.1/reference/sql/statements/create-user.md b/v2.1/reference/sql/statements/create-user.md deleted file mode 100644 index 787b41409074..000000000000 --- a/v2.1/reference/sql/statements/create-user.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: CREATE USER -summary: TiDB 数据库中 CREATE USER 的使用概况。 -category: reference ---- - -# CREATE USER - -`CREATE USER` 语句用于创建带有指定密码的新用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**CreateUserStmt:** - -![CreateUserStmt](/media/sqlgram/CreateUserStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -**AuthOption:** - -![AuthOption](/media/sqlgram/AuthOption.png) - -**StringName:** - -![StringName](/media/sqlgram/StringName.png) - -## 示例 - -```sql -mysql> CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -Query OK, 1 row affected (0.04 sec) - -mysql> CREATE USER 'newuser2'@'192.168.1.1' IDENTIFIED BY 'newuserpassword'; -Query OK, 1 row affected (0.02 sec) -``` - -## MySQL 兼容性 - -* TiDB 尚不支持若干 `CREATE` 选项。这些选项可被解析，但会被忽略。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/v2.1/reference/security/compatibility.md) -* [DROP USER](/v2.1/reference/sql/statements/drop-user.md) -* [ALTER USER](/v2.1/reference/sql/statements/alter-user.md) -* [Privilege Management](/v2.1/reference/security/privilege-system.md) diff --git a/v2.1/reference/sql/statements/deallocate.md b/v2.1/reference/sql/statements/deallocate.md deleted file mode 100644 index dd4bcba8adbd..000000000000 --- a/v2.1/reference/sql/statements/deallocate.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: DEALLOCATE -summary: TiDB 数据库中 DEALLOCATE 的使用概况。 -category: reference ---- - -# DEALLOCATE - -`DEALLOCATE` 语句用于为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**DeallocateStmt:** - -![DeallocateStmt](/media/sqlgram/DeallocateStmt.png) - -**DeallocateSym:** - -![DeallocateSym](/media/sqlgram/DeallocateSym.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -```sql -mysql> PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -Query OK, 0 rows affected (0.00 sec) - -mysql> SET @number = 5; -Query OK, 0 rows affected (0.00 sec) - -mysql> EXECUTE mystmt USING @number; -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) - -mysql> DEALLOCATE PREPARE mystmt; -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`DEALLOCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/v2.1/reference/sql/statements/prepare.md) -* [EXECUTE](/v2.1/reference/sql/statements/execute.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/delete.md b/v2.1/reference/sql/statements/delete.md deleted file mode 100644 index b6d99740faef..000000000000 --- a/v2.1/reference/sql/statements/delete.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: DELETE -summary: TiDB 数据库中 DELETE 的使用概况。 -category: reference ---- - -# DELETE - -`DELETE` 语句用于从指定的表中删除行。 - -## 语法图 - -**DeleteFromStmt:** - -![DeleteFromStmt](/media/sqlgram/DeleteFromStmt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) - -mysql> DELETE FROM t1 WHERE id = 4; -Query OK, 1 row affected (0.02 sec) - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 5 | 5 | -+----+----+ -4 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DELETE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v2.1/reference/sql/statements/insert.md) -* [SELECT](/v2.1/reference/sql/statements/select.md) -* [UPDATE](/v2.1/reference/sql/statements/update.md) -* [REPLACE](/v2.1/reference/sql/statements/replace.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/desc.md b/v2.1/reference/sql/statements/desc.md deleted file mode 100644 index 747083126331..000000000000 --- a/v2.1/reference/sql/statements/desc.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESC -summary: TiDB 数据库中 DESC 的使用概况。 -category: reference ---- - -# DESC - -`DESC` 语句是 [`EXPLAIN`](/v2.1/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/describe.md b/v2.1/reference/sql/statements/describe.md deleted file mode 100644 index f74f7d08aeb8..000000000000 --- a/v2.1/reference/sql/statements/describe.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESCRIBE -summary: TiDB 数据库中 DESCRIBE 的使用概况。 -category: reference ---- - -# DESCRIBE - -`DESCRIBE` 语句为 [`EXPLAIN`](/v2.1/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/do.md b/v2.1/reference/sql/statements/do.md deleted file mode 100644 index 0fac9c579ff7..000000000000 --- a/v2.1/reference/sql/statements/do.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: DO | TiDB SQL Statement Reference -summary: TiDB 数据库中 DO 的使用概况。 -category: reference ---- - -# DO - -`DO` 语句用于执行表达式，而不返回结果。在 MySQL 中，`DO` 的一个常见用例是执行存储的程序，而无需处理结果。但是 TiDB 不提供存储例程，因此该功能的使用较为受限。 - -## 语法图 - -**DoStmt:** - -![DoStmt](/media/sqlgram/DoStmt.png) - -**ExpressionList:** - -![ExpressionList](/media/sqlgram/ExpressionList.png) - -**Expression:** - -![Expression](/media/sqlgram/Expression.png) - -## 示例 - -```sql -mysql> SELECT SLEEP(5); -+----------+ -| SLEEP(5) | -+----------+ -| 0 | -+----------+ -1 row in set (5.00 sec) - -mysql> DO SLEEP(5); -Query OK, 0 rows affected (5.00 sec) - -mysql> DO SLEEP(1), SLEEP(1.5); -Query OK, 0 rows affected (2.50 sec) -``` - -## MySQL 兼容性 - -`DO` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SELECT](/v2.1/reference/sql/statements/select.md) diff --git a/v2.1/reference/sql/statements/drop-column.md b/v2.1/reference/sql/statements/drop-column.md deleted file mode 100644 index 5009e770fcb1..000000000000 --- a/v2.1/reference/sql/statements/drop-column.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: DROP COLUMN -summary: TiDB 数据库中 DROP COLUMN 的使用概况。 -category: reference ---- - -# DROP COLUMN - -`DROP COLUMN` 语句用于从指定的表中删除列。在 TiDB 中，`COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, col1 INT NOT NULL, col2 INT NOT NULL); -Query OK, 0 rows affected (0.12 sec) - -mysql> INSERT INTO t1 (col1,col2) VALUES (1,1),(2,2),(3,3),(4,4),(5,5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.01 sec) - -mysql> ALTER TABLE t1 DROP COLUMN col1, DROP COLUMN col2; -ERROR 1105 (HY000): can't run multi schema change -mysql> SELECT * FROM t1; -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.00 sec) - -mysql> ALTER TABLE t1 DROP COLUMN col1; -Query OK, 0 rows affected (0.27 sec) - -mysql> SELECT * FROM t1; -+----+------+ -| id | col2 | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持使用相同语句删除多个列。 - -## 另请参阅 - -* [ADD COLUMN](/v2.1/reference/sql/statements/add-column.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) diff --git a/v2.1/reference/sql/statements/drop-database.md b/v2.1/reference/sql/statements/drop-database.md deleted file mode 100644 index 05385e96073b..000000000000 --- a/v2.1/reference/sql/statements/drop-database.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: DROP DATABASE -summary: TiDB 数据库中 DROP DATABASE 的使用概况。 -category: reference ---- - -# DROP DATABASE - -`DROP DATABASE` 语句用于永久删除指定的数据库 schema，以及删除所有在 schema 中创建的表和视图。与被删数据库相关联的用户权限不受影响。 - -## 语法图 - -**DropDatabaseStmt:** - -![DropDatabaseStmt](/media/sqlgram/DropDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfExists:** - -![IfExists](/media/sqlgram/IfExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -```sql -mysql> SHOW DATABASES; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) - -mysql> DROP DATABASE test; -Query OK, 0 rows affected (0.25 sec) - -mysql> SHOW DATABASES; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -+--------------------+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v2.1/reference/sql/statements/create-database.md) -* [ALTER DATABASE](/v2.1/reference/sql/statements/alter-database.md) diff --git a/v2.1/reference/sql/statements/drop-index.md b/v2.1/reference/sql/statements/drop-index.md deleted file mode 100644 index b8d23f0a03bc..000000000000 --- a/v2.1/reference/sql/statements/drop-index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: DROP INDEX -summary: TiDB 数据库中 DROP INDEX 的使用概况。 -category: reference ---- - -# DROP INDEX - -`DROP INDEX` 语句用于从指定的表中删除索引，并在 TiKV 中将空间标记为释放。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.10 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> CREATE INDEX c1 ON t1 (c1); -Query OK, 0 rows affected (0.30 sec) - -mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) - -mysql> ALTER TABLE t1 DROP INDEX c1; -Query OK, 0 rows affected (0.30 sec) -``` - -## MySQL 兼容性 - -* 不支持删除 `PRIMARY KEY`。 - -## 另请参阅 - -* [SHOW INDEX](/v2.1/reference/sql/statements/show-index.md) -* [CREATE INDEX](/v2.1/reference/sql/statements/create-index.md) -* [ADD INDEX](/v2.1/reference/sql/statements/add-index.md) -* [RENAME INDEX](/v2.1/reference/sql/statements/rename-index.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/drop-table.md b/v2.1/reference/sql/statements/drop-table.md deleted file mode 100644 index 256cee8c59f0..000000000000 --- a/v2.1/reference/sql/statements/drop-table.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: DROP TABLE -summary: TiDB 数据库中 DROP TABLE 的使用概况。 -category: reference ---- - -# DROP TABLE - -`DROP TABLE` 语句用于从当前所选的数据库中删除表。如果表不存在则会报错，除非使用 `IF EXISTS` 修饰符。 - -按照设计，`DROP TABLE` 也会删除视图，因为视图与表共享相同的命名空间。 - -## 语法图 - -**DropTableStmt:** - -![DropTableStmt](/media/sqlgram/DropTableStmt.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a INT); -Query OK, 0 rows affected (0.11 sec) - -mysql> DROP TABLE t1; -Query OK, 0 rows affected (0.22 sec) - -mysql> DROP TABLE table_not_exists; -ERROR 1051 (42S02): Unknown table 'test.table_not_exists' -mysql> DROP TABLE IF EXISTS table_not_exists; -Query OK, 0 rows affected (0.01 sec) - -mysql> CREATE VIEW v1 AS SELECT 1; -Query OK, 0 rows affected (0.10 sec) - -mysql> DROP TABLE v1; -Query OK, 0 rows affected (0.23 sec) -``` - -## MySQL 兼容性 - -* 在尝试删除不存在的表时，使用 `IF EXISTS` 删除表不会返回警告。[Issue #7867](https://github.com/pingcap/tidb/issues/7867) - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) -* [SHOW TABLES](/v2.1/reference/sql/statements/show-tables.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/drop-user.md b/v2.1/reference/sql/statements/drop-user.md deleted file mode 100644 index 3ab2daf8fc5a..000000000000 --- a/v2.1/reference/sql/statements/drop-user.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: DROP USER -summary: TiDB 数据库中 DROP USER 的使用概况。 -category: reference ---- - -# DROP USER - -`DROP USER` 语句用于从 TiDB 系统数据库中删除用户。如果用户不存在，使用关键词 `IF EXISTS` 可避免出现警告。 - -## 语法图 - -**DropUserStmt:** - -![DropUserStmt](/media/sqlgram/DropUserStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -```sql -mysql> DROP USER idontexist; -ERROR 1396 (HY000): Operation DROP USER failed for idontexist@% - -mysql> DROP USER IF EXISTS idontexist; -Query OK, 0 rows affected (0.01 sec) - -mysql> CREATE USER newuser IDENTIFIED BY 'mypassword'; -Query OK, 1 row affected (0.02 sec) - -mysql> GRANT ALL ON test.* TO 'newuser'; -Query OK, 0 rows affected (0.03 sec) - -mysql> SHOW GRANTS FOR 'newuser'; -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) - -mysql> REVOKE ALL ON test.* FROM 'newuser'; -Query OK, 0 rows affected (0.03 sec) - -mysql> SHOW GRANTS FOR 'newuser'; -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) - -mysql> DROP USER newuser; -Query OK, 0 rows affected (0.14 sec) - -mysql> SHOW GRANTS FOR newuser; -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -* 在 TiDB 中删除不存在的用户时，使用 `IF EXISTS` 可避免出现警告。[Issue #10196](https://github.com/pingcap/tidb/issues/10196)。 - -## 另请参阅 - -* [CREATE USER](/v2.1/reference/sql/statements/create-user.md) -* [ALTER USER](/v2.1/reference/sql/statements/alter-user.md) -* [Privilege Management](/v2.1/reference/security/privilege-system.md) diff --git a/v2.1/reference/sql/statements/execute.md b/v2.1/reference/sql/statements/execute.md deleted file mode 100644 index e123113c5859..000000000000 --- a/v2.1/reference/sql/statements/execute.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: EXECUTE -summary: TiDB 数据库中 EXECUTE 的使用概况。 -category: reference ---- - -# EXECUTE - -`EXECUTE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**ExecuteStmt:** - -![ExecuteStmt](/media/sqlgram/ExecuteStmt.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -```sql -mysql> PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -Query OK, 0 rows affected (0.00 sec) - -mysql> SET @number = 5; -Query OK, 0 rows affected (0.00 sec) - -mysql> EXECUTE mystmt USING @number; -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) - -mysql> DEALLOCATE PREPARE mystmt; -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`EXECUTE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/v2.1/reference/sql/statements/prepare.md) -* [DEALLOCATE](/v2.1/reference/sql/statements/deallocate.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/explain-analyze.md b/v2.1/reference/sql/statements/explain-analyze.md deleted file mode 100644 index 837ce9bbf549..000000000000 --- a/v2.1/reference/sql/statements/explain-analyze.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: EXPLAIN ANALYZE -summary: TiDB 数据库中 EXPLAIN ANALYZE 的使用概况。 -category: reference ---- - -# EXPLAIN ANALYZE - -`EXPLAIN ANALYZE` 语句的工作方式类似于 `EXPLAIN`，主要区别在于前者实际上会执行语句。这样可以将查询计划中的估计值与执行时所遇到的实际值进行比较。如果估计值与实际值显著不同，那么应考虑在受影响的表上运行 `ANALYZE TABLE`。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.12 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1), (2), (3); -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 - -mysql> EXPLAIN ANALYZE SELECT * FROM t1 WHERE id = 1; -+-------------+-------+------+--------------------+---------------------------+ -| id | count | task | operator info | execution info | -+-------------+-------+------+--------------------+---------------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | time:0ns, loops:0, rows:0 | -+-------------+-------+------+--------------------+---------------------------+ -1 row in set (0.01 sec) - -mysql> EXPLAIN ANALYZE SELECT * FROM t1; -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| id | count | task | operator info | execution info | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| TableReader_5 | 10000.00 | root | data:TableScan_4 | time:931.759µs, loops:2, rows:3 | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | time:0s, loops:0, rows:3 | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -该语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/v2.1/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN](/v2.1/reference/sql/statements/explain.md) -* [ANALYZE TABLE](/v2.1/reference/sql/statements/analyze-table.md) -* [TRACE](/v2.1/reference/sql/statements/trace.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/explain.md b/v2.1/reference/sql/statements/explain.md deleted file mode 100644 index 1a8aa3d53a23..000000000000 --- a/v2.1/reference/sql/statements/explain.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: EXPLAIN -summary: TiDB 数据库中 EXPLAIN 的使用概况。 -category: reference ---- - -# EXPLAIN - -`EXPLAIN` 语句仅用于显示查询的执行计划，而不执行查询。`EXPLAIN ANALYZE` 可执行查询，补充 `EXPLAIN` 语句。如果 `EXPLAIN` 的输出与预期结果不匹配，可考虑在查询的每个表上执行 `ANALYZE TABLE`。 - -语句 `DESC` 和 `DESCRIBE` 是 `EXPLAIN` 的别名。`EXPLAIN ` 的替代用法记录在 [`SHOW [FULL] COLUMNS FROM`](/v2.1/reference/sql/statements/show-columns-from.md) 下。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -```sql -mysql> EXPLAIN SELECT 1; -+-------------------+-------+------+---------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------+ -| Projection_3 | 1.00 | root | 1 | -| └─TableDual_4 | 1.00 | root | rows:1 | -+-------------------+-------+------+---------------+ -2 rows in set (0.00 sec) - -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.10 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1), (2), (3); -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 - -mysql> EXPLAIN SELECT * FROM t1 WHERE id = 1; -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) - -mysql> DESC SELECT * FROM t1 WHERE id = 1; -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) - -mysql> DESCRIBE SELECT * FROM t1 WHERE id = 1; -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) - -mysql> EXPLAIN INSERT INTO t1 (c1) VALUES (4); -ERROR 1105 (HY000): Unsupported type *core.Insert - -mysql> EXPLAIN UPDATE t1 SET c1=5 WHERE c1=3; -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) - -mysql> EXPLAIN DELETE FROM t1 WHERE c1=3; -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -如果未指定 `FORMAT`，或未指定 `FORMAT ="row"`，那么 `EXPLAIN` 语句将以表格格式输出结果。更多信息，可参阅 [Understand the Query Execution Plan](https://pingcap.com/docs/dev/reference/performance/understanding-the-query-execution-plan/)。 - -除 MySQL 标准结果格式外，TiDB 还支持 DotGraph。需按照下列所示指定 `FORMAT ="dot"`： - -```sql -create table t(a bigint, b bigint); -desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10; - -TiDB > desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10;desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10; -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dot contents | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| -digraph HashRightJoin_7 { -subgraph cluster7{ -node [style=filled, color=lightgrey] -color=black -label = "root" -"HashRightJoin_7" -> "TableReader_10" -"HashRightJoin_7" -> "TableReader_12" -} -subgraph cluster9{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"Selection_9" -> "TableScan_8" -} -subgraph cluster11{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"TableScan_11" -} -"TableReader_10" -> "Selection_9" -"TableReader_12" -> "TableScan_11" -} - | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -如果你的计算机上安装了 `dot` 程序（在 `graphviz` 包中），可使用以下方法生成 PNG 文件： - -```bash -dot xx.dot -T png -O - -The xx.dot is the result returned by the above statement. -``` - -如果你的计算机上未安装 `dot` 程序，可将结果复制到 [本网站](http://www.webgraphviz.com/) 以获取树形图： - -![Explain Dot](/media/explain_dot.png) - -## MySQL 兼容性 - -* `EXPLAIN` 的格式和 TiDB 中潜在的执行计划都与 MySQL 有很大不同。 -* TiDB 不像 MySQL 那样支持 `EXPLAIN FORMAT = JSON`。 -* TiDB 目前不支持插入语句的 `EXPLAIN`。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/v2.1/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN ANALYZE](/v2.1/reference/sql/statements/explain-analyze.md) -* [ANALYZE TABLE](/v2.1/reference/sql/statements/analyze-table.md) -* [TRACE](/v2.1/reference/sql/statements/trace.md) diff --git a/v2.1/reference/sql/statements/flush-privileges.md b/v2.1/reference/sql/statements/flush-privileges.md deleted file mode 100644 index 6d62aa19dad8..000000000000 --- a/v2.1/reference/sql/statements/flush-privileges.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: FLUSH PRIVILEGES -summary: TiDB 数据库中 FLUSH PRIVILEGES 的使用概况。 -category: reference ---- - -# FLUSH PRIVILEGES - -`FLUSH PRIVILEGES` 语句可触发 TiDB 从权限表中重新加载权限的内存副本。在对如 `mysql.user` 一类的表进行手动编辑后，应当执行 `FLUSH PRIVILEGES`。使用如 `GRANT` 或 `REVOKE` 一类的权限语句后，不需要执行 `FLUSH PRIVILEGES` 语句。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -```sql -mysql> FLUSH PRIVILEGES; -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`FLUSH PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [GRANT](/v2.1/reference/sql/statements/grant-privileges.md) -* [REVOKE ](/v2.1/reference/sql/statements/revoke-privileges.md) -* [Privilege Management](/v2.1/reference/security/privilege-system.md) diff --git a/v2.1/reference/sql/statements/flush-status.md b/v2.1/reference/sql/statements/flush-status.md deleted file mode 100644 index 11d3ea57494b..000000000000 --- a/v2.1/reference/sql/statements/flush-status.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: FLUSH STATUS -summary: TiDB 数据库中 FLUSH STATUS 的使用概况。 -category: reference ---- - -# FLUSH STATUS - -`FLUSH STATUS` 语句用于提供 MySQL 兼容性，但在 TiDB 上并无作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -```sql -mysql> show status; -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) - -mysql> show global status; -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) - -mysql> flush status; -Query OK, 0 rows affected (0.00 sec) - -mysql> show status; -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| ddl_schema_version | 141 | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `FLUSH STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] STATUS](/v2.1/reference/sql/statements/show-status.md) diff --git a/v2.1/reference/sql/statements/flush-tables.md b/v2.1/reference/sql/statements/flush-tables.md deleted file mode 100644 index d0633d5c2e6c..000000000000 --- a/v2.1/reference/sql/statements/flush-tables.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: FLUSH TABLES -summary: TiDB 数据库中 FLUSH TABLES 的使用概况。 -category: reference ---- - -# FLUSH TABLES - -`FLUSH TABLES` 语句用于提供 MySQL 兼容性，但在 TiDB 中并无有效用途。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameListOpt:** - -![TableNameListOpt](/media/sqlgram/TableNameListOpt.png) - -**WithReadLockOpt:** - -![WithReadLockOpt](/media/sqlgram/WithReadLockOpt.png) - -## 示例 - -```sql -mysql> FLUSH TABLES; -Query OK, 0 rows affected (0.00 sec) - -mysql> FLUSH TABLES WITH READ LOCK; -ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported. Please use @@tidb_snapshot -``` - -## MySQL 兼容性 - -* TiDB 没有 MySQL 中的表缓存这一概念。所以，`FLUSH TABLES` 因 MySQL 兼容性会在 TiDB 中解析出但会被忽略掉。 -* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads] 来实现锁表。 - -## 另请参阅 - -* [Read historical data](/v2.1/how-to/get-started/read-historical-data.md) diff --git a/v2.1/reference/sql/statements/grant-privileges.md b/v2.1/reference/sql/statements/grant-privileges.md deleted file mode 100644 index 9f8f77895d4d..000000000000 --- a/v2.1/reference/sql/statements/grant-privileges.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: GRANT -summary: TiDB 数据库中 GRANT 的使用概况。 -category: reference ---- - -# GRANT - -`GRANT ` 语句用于为 TiDB 中已存在的用户分配权限。TiDB 中的权限系统同 MySQL 一样，都基于数据库/表模式来分配凭据。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -```sql -mysql> CREATE USER newuser IDENTIFIED BY 'mypassword'; -Query OK, 1 row affected (0.02 sec) - -mysql> GRANT ALL ON test.* TO 'newuser'; -Query OK, 0 rows affected (0.03 sec) - -mysql> SHOW GRANTS FOR 'newuser'; -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 与 MySQL 类似，`USAGE` 权限表示登录 TiDB 服务器的能力。 -* 目前不支持列级权限。 -* 与 MySQL 类似，不存在 `NO_AUTO_CREATE_USER` sql 模式时，`GRANT` 语句将在用户不存在时自动创建一个空密码的新用户。删除此 sql-mode（默认情况下已启用）会带来安全风险。 - -## 另请参阅 - -* [REVOKE ](/v2.1/reference/sql/statements/revoke-privileges.md) -* [SHOW GRANTS](/v2.1/reference/sql/statements/show-grants.md) -* [Privilege Management](/v2.1/reference/security/privilege-system.md) diff --git a/v2.1/reference/sql/statements/insert.md b/v2.1/reference/sql/statements/insert.md deleted file mode 100644 index 2be737f7a456..000000000000 --- a/v2.1/reference/sql/statements/insert.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: INSERT -summary: TiDB 数据库中 INSERT 的使用概况。 -category: reference ---- - -# INSERT - -使用 `INSERT` 语句在表中插入新行。 - -## 语法图 - -**InsertIntoStmt:** - -![InsertIntoStmt](/media/sqlgram/InsertIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IgnoreOptional:** - -![IgnoreOptional](/media/sqlgram/IgnoreOptional.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.11 sec) - -mysql> CREATE TABLE t2 LIKE t1; -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 VALUES (1); -Query OK, 1 row affected (0.02 sec) - -mysql> INSERT INTO t1 (a) VALUES (1); -Query OK, 1 row affected (0.01 sec) - -mysql> INSERT INTO t2 SELECT * FROM t1; -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) - -mysql> SELECT * FROM t2; -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) - -mysql> INSERT INTO t2 VALUES (2),(3),(4); -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t2; -+------+ -| a | -+------+ -| 1 | -| 1 | -| 2 | -| 3 | -| 4 | -+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`INSERT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/v2.1/reference/sql/statements/delete.md) -* [SELECT](/v2.1/reference/sql/statements/select.md) -* [UPDATE](/v2.1/reference/sql/statements/update.md) -* [REPLACE](/v2.1/reference/sql/statements/replace.md) diff --git a/v2.1/reference/sql/statements/kill.md b/v2.1/reference/sql/statements/kill.md deleted file mode 100644 index 15925c47bef1..000000000000 --- a/v2.1/reference/sql/statements/kill.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: KILL [TIDB] -summary: TiDB 数据库中 KILL [TIDB] 的使用概况。 -category: reference ---- - -# KILL [TIDB] - -`KILL TIDB` 语句用于终止 TiDB 中的连接。 - -按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。 - -## 语法图 - -**KillStmt:** - -![KillStmt](/media/sqlgram/KillStmt.png) - -## 示例 - -```sql -mysql> SHOW PROCESSLIST; -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) - -mysql> KILL TIDB 2; -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -* `KILL TIDB` 语句是 TiDB 的扩展语法。如果正尝试终止的会话位于同一个 TiDB 服务器上，可在配置文件里设置 [`compatible-kill-query = true`](/v2.1/reference/configuration/tidb-server/configuration-file.md#compatible-kill-query)。 - -## 另请参阅 - -* [SHOW \[FULL\] PROCESSLIST](/v2.1/reference/sql/statements/show-processlist.md) diff --git a/v2.1/reference/sql/statements/load-data.md b/v2.1/reference/sql/statements/load-data.md deleted file mode 100644 index 65c848c85537..000000000000 --- a/v2.1/reference/sql/statements/load-data.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: LOAD DATA -summary: TiDB 数据库中 LOAD DATA 的使用概况。 -category: reference ---- - -# LOAD DATA - -`LOAD DATA` 语句用于将数据批量加载到 TiDB 表中。 - -## 语法图 - -**LoadDataStmt:** - -![LoadDataStmt](/media/sqlgram/LoadDataStmt.png) - -## 示例 - -```sql -mysql> CREATE TABLE trips ( - -> trip_id bigint NOT NULL PRIMARY KEY AUTO_INCREMENT, - -> duration integer not null, - -> start_date datetime, - -> end_date datetime, - -> start_station_number integer, - -> start_station varchar(255), - -> end_station_number integer, - -> end_station varchar(255), - -> bike_number varchar(255), - -> member_type varchar(255) - -> ); -Query OK, 0 rows affected (0.14 sec) - -mysql> LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); - -Query OK, 815264 rows affected (39.63 sec) -Records: 815264 Deleted: 0 Skipped: 0 Warnings: 0 -``` - -## MySQL 兼容性 - -* 默认情况下，TiDB 每 20,000 行会进行一次提交。这类似于 MySQL NDB Cluster，但并非 InnoDB 存储引擎的默认配置。 - -> **注意：** -> -> 这种拆分事务提交的方式是以打破事务的原子性和隔离性为代价的，使用该特性时，使用者需要保证没有其他对正在处理的表的**任何**操作，并且在出现报错时，需要及时**人工介入，检查数据的一致性和完整性**。因此，不建议在生产环境中使用。 - -## 另请参阅 - -* [INSERT](/v2.1/reference/sql/statements/insert.md) -* [乐观事务模型](/v2.1/reference/transactions/transaction-optimistic.md) diff --git a/v2.1/reference/sql/statements/modify-column.md b/v2.1/reference/sql/statements/modify-column.md deleted file mode 100644 index ce633607d583..000000000000 --- a/v2.1/reference/sql/statements/modify-column.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: MODIFY COLUMN -summary: TiDB 数据库中 MODIFY COLUMN 的使用概况。 -category: reference ---- - -# MODIFY COLUMN - -`ALTER TABLE .. MODIFY COLUMN` 语句用于修改已有表上的列，包括列的数据类型和属性。若要同时重命名，可改用 [`CHANGE COLUMN`](/v2.1/reference/sql/statements/change-column.md) 语句。 - -## 语法图 - -**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) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> ALTER TABLE t1 MODIFY col1 BIGINT; -Query OK, 0 rows affected (0.09 sec) - -mysql> SHOW CREATE TABLE t1\G -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `col1` bigint(20) DEFAULT NULL, - PRIMARY KEY (`id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=30001 -1 row in set (0.00 sec) - -mysql> ALTER TABLE t1 MODIFY col1 INT; -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -mysql> ALTER TABLE t1 MODIFY col1 BLOB; -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -mysql> ALTER TABLE t1 MODIFY col1 BIGINT, MODIFY id BIGINT NOT NULL; -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前不支持使用单个 `ALTER TABLE` 语句进行多个修改。 -* 仅支持特定类型的数据类型更改。例如，支持将 `INTEGER` 改为 `BIGINT`，但不支持将 `BIGINT` 改为 `INTEGER`。不支持将整数改为字符串格式或 BLOB 格式。 -* 不支持修改 decimal 类型的精度。 - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/v2.1/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v2.1/reference/sql/statements/drop-column.md) -* [CHANGE COLUMN](/v2.1/reference/sql/statements/change-column.md) diff --git a/v2.1/reference/sql/statements/prepare.md b/v2.1/reference/sql/statements/prepare.md deleted file mode 100644 index e4b152167a20..000000000000 --- a/v2.1/reference/sql/statements/prepare.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: PREPARE -summary: TiDB 数据库中 PREPARE 的使用概况。 -category: reference ---- - -# PREPARE - -`PREPARE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**PreparedStmt:** - -![PreparedStmt](/media/sqlgram/PreparedStmt.png) - -## 示例 - -```sql -mysql> PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -Query OK, 0 rows affected (0.00 sec) - -mysql> SET @number = 5; -Query OK, 0 rows affected (0.00 sec) - -mysql> EXECUTE mystmt USING @number; -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) - -mysql> DEALLOCATE PREPARE mystmt; -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`PREPARE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [EXECUTE](/v2.1/reference/sql/statements/execute.md) -* [DEALLOCATE](/v2.1/reference/sql/statements/deallocate.md) diff --git a/v2.1/reference/sql/statements/rename-index.md b/v2.1/reference/sql/statements/rename-index.md deleted file mode 100644 index 5b1021cd220c..000000000000 --- a/v2.1/reference/sql/statements/rename-index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: RENAME INDEX -summary: TiDB 数据库中 RENAME INDEX 的使用概况。 -category: reference ---- - -# RENAME INDEX - -`ALTER TABLE .. RENAME INDEX` 语句用于对已有索引进行重命名。这在 TiDB 中是即时操作的，仅需更改元数据。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL, INDEX col1 (c1)); -Query OK, 0 rows affected (0.11 sec) - -mysql> SHOW CREATE TABLE t1\G -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `col1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) - -mysql> ALTER TABLE t1 RENAME INDEX col1 TO c1; -Query OK, 0 rows affected (0.09 sec) - -mysql> SHOW CREATE TABLE t1\G -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `c1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME INDEX` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) -* [CREATE INDEX](/v2.1/reference/sql/statements/create-index.md) -* [DROP INDEX](/v2.1/reference/sql/statements/drop-index.md) -* [SHOW INDEX](/v2.1/reference/sql/statements/show-index.md) diff --git a/v2.1/reference/sql/statements/rename-table.md b/v2.1/reference/sql/statements/rename-table.md deleted file mode 100644 index 51f2f9f58514..000000000000 --- a/v2.1/reference/sql/statements/rename-table.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: RENAME TABLE -summary: TiDB 数据库中 RENAME TABLE 的使用概况。 -category: reference ---- - -# RENAME TABLE - -`RENAME TABLE` 语句用于对已有表进行重命名。 - -## 语法图 - -**RenameTableStmt:** - -![RenameTableStmt](/media/sqlgram/RenameTableStmt.png) - -**TableToTable:** - -![TableToTable](/media/sqlgram/TableToTable.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.12 sec) - -mysql> SHOW TABLES; -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -+----------------+ -1 row in set (0.00 sec) - -mysql> RENAME TABLE t1 TO t2; -Query OK, 0 rows affected (0.08 sec) - -mysql> SHOW TABLES; -+----------------+ -| Tables_in_test | -+----------------+ -| t2 | -+----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [SHOW TABLES](/v2.1/reference/sql/statements/show-tables.md) -* [ALTER TABLE](/v2.1/reference/sql/statements/alter-table.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/replace.md b/v2.1/reference/sql/statements/replace.md deleted file mode 100644 index b3a3bcc9789e..000000000000 --- a/v2.1/reference/sql/statements/replace.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: REPLACE -summary: TiDB 数据库中 REPLACE 的使用概况。 -category: reference ---- - -# REPLACE - -从语义上看，`REPLACE` 语句是 `DELETE` 语句和 `INSERT` 语句的结合，可用于简化应用程序代码。 - -## 语法图 - -**ReplaceIntoStmt:** - -![ReplaceIntoStmt](/media/sqlgram/ReplaceIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.12 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1), (2), (3); -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) - -mysql> REPLACE INTO t1 (id, c1) VALUES(3, 99); -Query OK, 2 rows affected (0.01 sec) - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 99 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`REPLACE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/v2.1/reference/sql/statements/delete.md) -* [INSERT](/v2.1/reference/sql/statements/insert.md) -* [SELECT](/v2.1/reference/sql/statements/select.md) -* [UPDATE](/v2.1/reference/sql/statements/update.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/revoke-privileges.md b/v2.1/reference/sql/statements/revoke-privileges.md deleted file mode 100644 index c60209a8e352..000000000000 --- a/v2.1/reference/sql/statements/revoke-privileges.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: REVOKE -summary: TiDB 数据库中 REVOKE 的使用概况。 -category: reference ---- - -# REVOKE - -`REVOKE ` 语句用于删除已有用户的权限。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -```sql -mysql> CREATE USER newuser IDENTIFIED BY 'mypassword'; -Query OK, 1 row affected (0.02 sec) - -mysql> GRANT ALL ON test.* TO 'newuser'; -Query OK, 0 rows affected (0.03 sec) - -mysql> SHOW GRANTS FOR 'newuser'; -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) - -mysql> REVOKE ALL ON test.* FROM 'newuser'; -Query OK, 0 rows affected (0.03 sec) - -mysql> SHOW GRANTS FOR 'newuser'; -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) - -mysql> DROP USER newuser; -Query OK, 0 rows affected (0.14 sec) - -mysql> SHOW GRANTS FOR newuser; -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -`REVOKE ` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [GRANT ](/v2.1/reference/sql/statements/grant-privileges.md) -* [SHOW GRANTS](/v2.1/reference/sql/statements/show-grants.md) -* [Privilege Management](/v2.1/reference/security/privilege-system.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/rollback.md b/v2.1/reference/sql/statements/rollback.md deleted file mode 100644 index c4717df3decf..000000000000 --- a/v2.1/reference/sql/statements/rollback.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: ROLLBACK -summary: TiDB 数据库中 ROLLBACK 的使用概况。 -category: reference ---- - -# ROLLBACK - -`ROLLBACK` 语句用于还原 TiDB 内当前事务中的所有更改，作用与 `COMMIT` 语句相反。 - -## 语法图 - -**Statement:** - -![Statement](/media/sqlgram/Statement.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -Query OK, 0 rows affected (0.12 sec) - -mysql> BEGIN; -Query OK, 0 rows affected (0.00 sec) - -mysql> INSERT INTO t1 VALUES (1); -Query OK, 1 row affected (0.00 sec) - -mysql> ROLLBACK; -Query OK, 0 rows affected (0.01 sec) - -mysql> SELECT * FROM t1; -Empty set (0.01 sec) -``` - -## MySQL 兼容性 - -`ROLLBACK` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v2.1/reference/sql/statements/commit.md) -* [BEGIN](/v2.1/reference/sql/statements/begin.md) -* [START TRANSACTION](/v2.1/reference/sql/statements/start-transaction.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/select.md b/v2.1/reference/sql/statements/select.md deleted file mode 100644 index 6ad448008338..000000000000 --- a/v2.1/reference/sql/statements/select.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: SELECT -summary: TiDB 数据库中 SELECT 的使用概况。 -category: reference ---- - -# SELECT - -`SELECT` 语句用于从 TiDB 读取数据。 - -## 语法图 - -**SelectStmt:** - -![SelectStmt](/media/sqlgram/SelectStmt.png) - -**FromDual:** - -![FromDual](/media/sqlgram/FromDual.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtOpts:** - -![SelectStmtOpts](/media/sqlgram/SelectStmtOpts.png) - -**SelectStmtFieldList:** - -![SelectStmtFieldList](/media/sqlgram/SelectStmtFieldList.png) - -**TableRefsClause:** - -![TableRefsClause](/media/sqlgram/TableRefsClause.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtGroup:** - -![SelectStmtGroup](/media/sqlgram/SelectStmtGroup.png) - -**HavingClause:** - -![HavingClause](/media/sqlgram/HavingClause.png) - -**OrderByOptional:** - -![OrderByOptional](/media/sqlgram/OrderByOptional.png) - -**SelectStmtLimit:** - -![SelectStmtLimit](/media/sqlgram/SelectStmtLimit.png) - -**SelectLockOpt:** - -![SelectLockOpt](/media/sqlgram/SelectLockOpt.png) - -## 语法元素说明 - -|语法元素 | 说明 | -| --------------------- | -------------------------------------------------- | -|`ALL`、`DISTINCT`、`DISTINCTROW` | 查询结果集中可能会包含重复值。指定 DISTINCT/DISTINCTROW 则在查询结果中过滤掉重复的行；指定 ALL 则列出所有的行。默认为 ALL。| -|`HIGH_PRIORITY` | 该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句| -|`SQL_CALC_FOUND_ROWS` | TiDB 出于兼容性解析这个语法，但是不做任何处理| -|`SQL_CACHE`、`SQL_NO_CACHE` | 是否把请求结果缓存到 TiKV (RocksDB) 的 `BlockCache` 中。对于一次性的大数据量的查询，比如 `count(*)` 查询，为了避免冲掉 `BlockCache` 中用户的热点数据，建议填上 `SQL_NO_CACHE` | -|`STRAIGHT_JOIN`|`STRAIGHT_JOIN` 会强制优化器按照 `FROM` 子句中所使用的表的顺序做联合查询。当优化器选择的 Join 顺序并不优秀时，你可以使用这个语法来加速查询的执行| -|`select_expr` | 投影操作列表，一般包括列名、表达式，或者是用 '\*' 表示全部列| -|`FROM table_references` | 表示数据来源，数据来源可以是一个表（`select * from t;`）或者是多个表 (`select * from t1 join t2;`) 或者是0个表 (`select 1+1 from dual;`, 等价于 `select 1+1;`)| -|`WHERE where_condition` | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据| -|`GROUP BY` | GroupBy 子句用于对查询结果集进行分组| -|`HAVING where_condition` | Having 子句与 Where 子句作用类似，Having 子句可以让过滤 GroupBy 后的各种数据，Where 子句用于在聚合前过滤记录。| -|`ORDER BY` | OrderBy 子句用于指定结果排序顺序，可以按照列、表达式或者是 `select_expr` 列表中某个位置的字段进行排序。| -|`LIMIT` | Limit 子句用于限制结果条数。Limit 接受一个或两个数字参数，如果只有一个参数，那么表示返回数据的最大行数；如果是两个参数，那么第一个参数表示返回数据的第一行的偏移量（第一行数据的偏移量是 0），第二个参数指定返回数据的最大条目数。| -|`FOR UPDATE` | 对查询结果集所有行上锁（对于在查询条件内，但是不在结果集的行，将不会加锁，如事务启动后由其他事务写入的行），以监测其他事务对这些的并发修改。使用[乐观事务模型](/v2.1/reference/transactions/transaction-optimistic.md)时，语句执行期间不会检测锁，因此，不会像 PostgreSQL 之类的数据库一样，在当前事务结束前阻止其他事务执行 `UPDATE`、`DELETE` 和 `SELECT FOR UPDATE`。在事务的提交阶段 `SELECT FOR UPDATE` 读到的行，也会进行两阶段提交，因此，它们也可以参与事务冲突检测。如发生写入冲突，那么包含 `SELECT FOR UPDATE` 语句的事务会提交失败。如果没有冲突，事务将成功提交，当提交结束时，这些被加锁的行，会产生一个新版本，可以让其他尚未提交的事务，在将来提交时发现写入冲突。 | -|`LOCK IN SHARE MODE` | TiDB 出于兼容性解析这个语法，但是不做任何处理| - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SELECT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v2.1/reference/sql/statements/insert.md) -* [DELETE](/v2.1/reference/sql/statements/delete.md) -* [UPDATE](/v2.1/reference/sql/statements/update.md) -* [REPLACE](/v2.1/reference/sql/statements/replace.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/set-names.md b/v2.1/reference/sql/statements/set-names.md deleted file mode 100644 index 00b11d9c4d6f..000000000000 --- a/v2.1/reference/sql/statements/set-names.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: SET [NAMES|CHARACTER SET] -summary: TiDB 数据库中 SET [NAMES|CHARACTER SET] 的使用概况。 -category: reference ---- - -# SET [NAMES|CHARACTER SET] - -`SET NAMES`，`SET CHARACTER SET` 和 `SET CHARSET` 语句用于修改当前连接的变量 `character_set_client`，`character_set_results` 和 `character_set_connection`。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -```sql -mysql> SHOW VARIABLES LIKE 'character_set%'; -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.01 sec) - -mysql> SET NAMES utf8; -Query OK, 0 rows affected (0.00 sec) - -mysql> SHOW VARIABLES LIKE 'character_set%'; -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8 | -| character_set_system | utf8 | -| character_set_results | utf8 | -| character_set_client | utf8 | -| character_set_server | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) - -mysql> SET CHARACTER SET utf8mb4; -Query OK, 0 rows affected (0.00 sec) - -mysql> SHOW VARIABLES LIKE 'character_set%'; -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [NAMES|CHARACTER SET]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/v2.1/reference/sql/statements/show-variables.md) -* [SET ](/v2.1/reference/sql/statements/set-variable.md) -* [Character Set Support](/v2.1/reference/sql/character-set.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/set-password.md b/v2.1/reference/sql/statements/set-password.md deleted file mode 100644 index e06276afb6c2..000000000000 --- a/v2.1/reference/sql/statements/set-password.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: SET PASSWORD -summary: TiDB 数据库中 SET PASSWORD 的使用概况。 -category: reference ---- - -# SET PASSWORD - -`SET PASSWORD` 语句用于更改 TiDB 系统数据库中的用户密码。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -```sql -mysql> SET PASSWORD='test'; -- change my password -Query OK, 0 rows affected (0.01 sec) - -mysql> CREATE USER 'newuser' IDENTIFIED BY 'test'; -Query OK, 1 row affected (0.00 sec) - -mysql> SELECT USER, HOST, PASSWORD FROM mysql.`user` WHERE USER = 'newuser'; -+---------+------+-------------------------------------------+ -| USER | HOST | PASSWORD | -+---------+------+-------------------------------------------+ -| newuser | % | *94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29 | -+---------+------+-------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SET PASSWORD FOR newuser = 'test'; -Query OK, 0 rows affected (0.01 sec) - -mysql> SELECT USER, HOST, PASSWORD FROM mysql.`user` WHERE USER = 'newuser'; -+---------+------+-------------------------------------------+ -| USER | HOST | PASSWORD | -+---------+------+-------------------------------------------+ -| newuser | % | *94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29 | -+---------+------+-------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SET PASSWORD FOR newuser = PASSWORD('test'); -- deprecated syntax from earlier MySQL releases -Query OK, 0 rows affected (0.00 sec) - -mysql> SELECT USER, HOST, PASSWORD FROM mysql.`user` WHERE USER = 'newuser'; -+---------+------+-------------------------------------------+ -| USER | HOST | PASSWORD | -+---------+------+-------------------------------------------+ -| newuser | % | *94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29 | -+---------+------+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET PASSWORD` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE USER](/v2.1/reference/sql/statements/create-user.md) -* [Privilege Management](/v2.1/reference/security/privilege-system.md) diff --git a/v2.1/reference/sql/statements/set-transaction.md b/v2.1/reference/sql/statements/set-transaction.md deleted file mode 100644 index cf21c2afc699..000000000000 --- a/v2.1/reference/sql/statements/set-transaction.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: SET TRANSACTION -summary: TiDB 数据库中 SET TRANSACTION 的使用概况。 -category: reference ---- - -# SET TRANSACTION - -`SET TRANSACTION` 语句用于在 `GLOBAL` 或 `SESSION` 的基础上更改当前的隔离级别，是 `SET transaction_isolation ='new-value'` 的替代语句，提供 MySQL 和 SQL 标准的兼容性。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -**TransactionChar:** - -![TransactionChar](/media/sqlgram/TransactionChar.png) - -**IsolationLevel:** - -![IsolationLevel](/media/sqlgram/IsolationLevel.png) - -## 示例 - -```sql -mysql> SHOW SESSION VARIABLES like 'transaction_isolation'; -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) - -mysql> SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -Query OK, 0 rows affected (0.00 sec) - -mysql> SHOW SESSION VARIABLES like 'transaction_isolation'; -+-----------------------+----------------+ -| Variable_name | Value | -+-----------------------+----------------+ -| transaction_isolation | READ-COMMITTED | -+-----------------------+----------------+ -1 row in set (0.01 sec) - -mysql> SET SESSION transaction_isolation = 'REPEATABLE-READ'; -Query OK, 0 rows affected (0.00 sec) - -mysql> SHOW SESSION VARIABLES like 'transaction_isolation'; -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 支持仅在语法中将事务设置为只读的功能。 -* 不支持隔离级别 `READ-UNCOMMITTED` 和 `SERIALIZABLE`。 -* 隔离级别 `REPEATABLE-READ` 在技术上属于快照隔离（Snapshot Isolation）。在 TiDB 中称为 `REPEATABLE-READ` 是为了和 MySQL 保持一致。 - -## 另请参阅 - -* [SET \[GLOBAL|SESSION\] ](/v2.1/reference/sql/statements/set-variable.md) -* [Isolation Levels](/v2.1/reference/transactions/transaction-isolation.md) diff --git a/v2.1/reference/sql/statements/set-variable.md b/v2.1/reference/sql/statements/set-variable.md deleted file mode 100644 index 27f17b7843bc..000000000000 --- a/v2.1/reference/sql/statements/set-variable.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: SET [GLOBAL|SESSION] -summary: TiDB 数据库中 SET [GLOBAL|SESSION] 的使用概况。 -category: reference ---- - -# SET [GLOBAL|SESSION] - -`SET [GLOBAL|SESSION]` 语句用于在 `SESSION` 或 `GLOBAL` 的范围内，对某个 TiDB 的内置变量进行更改。需注意，对 `GLOBAL` 变量的更改不适用于已有连接或本地连接，这与 MySQL 类似。只有新会话才会反映值的变化。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -```sql -mysql> SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SHOW SESSION VARIABLES LIKE 'sql_mode'; -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -Query OK, 0 rows affected (0.03 sec) - -mysql> SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) - -mysql> SHOW SESSION VARIABLES LIKE 'sql_mode'; -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -Query OK, 0 rows affected (0.01 sec) - -mysql> SHOW SESSION VARIABLES LIKE 'sql_mode'; -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [GLOBAL|SESSION]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/v2.1/reference/sql/statements/show-variables.md) diff --git a/v2.1/reference/sql/statements/show-character-set.md b/v2.1/reference/sql/statements/show-character-set.md deleted file mode 100644 index acaf6b0d24b4..000000000000 --- a/v2.1/reference/sql/statements/show-character-set.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: SHOW CHARACTER SET -summary: TiDB 数据库中 SHOW CHARACTER SET 的使用概况。 -category: reference ---- - -# SHOW CHARACTER SET - -`SHOW CHARACTER SET` 语句提供 TiDB 中可用字符集的静态列表。此列表不反映当前连接或用户的任何属性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**CharsetKw:** - -![CharsetKw](/media/sqlgram/CharsetKw.png) - -## 示例 - -```sql -mysql> SHOW CHARACTER SET; -+---------+---------------+-------------------+--------+ -| Charset | Description | Default collation | Maxlen | -+---------+---------------+-------------------+--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------+---------------+-------------------+--------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CHARACTER SET` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW COLLATION](/v2.1/reference/sql/statements/show-collation.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-collation.md b/v2.1/reference/sql/statements/show-collation.md deleted file mode 100644 index c8add87dc558..000000000000 --- a/v2.1/reference/sql/statements/show-collation.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: SHOW COLLATION -summary: TiDB 数据库中 SHOW COLLATION 的使用概况。 -category: reference ---- - -# SHOW COLLATION - -`SHOW COLLATION` 语句用于提供一个静态的排序规则列表，确保与 MySQL 客户端库的兼容性。 - -> **注意:** TiDB 目前仅支持二进制排序规则。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -```sql -mysql> SHOW COLLATION; -+--------------------------+----------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+--------------------------+----------+------+---------+----------+---------+ -| big5_chinese_ci | big5 | 1 | Yes | Yes | 1 | -| latin2_czech_cs | latin2 | 2 | | Yes | 1 | -| dec8_swedish_ci | dec8 | 3 | Yes | Yes | 1 | -| cp850_general_ci | cp850 | 4 | Yes | Yes | 1 | -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| hp8_english_ci | hp8 | 6 | Yes | Yes | 1 | -| koi8r_general_ci | koi8r | 7 | Yes | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin2_general_ci | latin2 | 9 | Yes | Yes | 1 | -| swe7_swedish_ci | swe7 | 10 | Yes | Yes | 1 | -| ascii_general_ci | ascii | 11 | Yes | Yes | 1 | -| ujis_japanese_ci | ujis | 12 | Yes | Yes | 1 | -| sjis_japanese_ci | sjis | 13 | Yes | Yes | 1 | -| cp1251_bulgarian_ci | cp1251 | 14 | | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| hebrew_general_ci | hebrew | 16 | Yes | Yes | 1 | -| tis620_thai_ci | tis620 | 18 | Yes | Yes | 1 | -| euckr_korean_ci | euckr | 19 | Yes | Yes | 1 | -| latin7_estonian_cs | latin7 | 20 | | Yes | 1 | -| latin2_hungarian_ci | latin2 | 21 | | Yes | 1 | -| koi8u_general_ci | koi8u | 22 | Yes | Yes | 1 | -| cp1251_ukrainian_ci | cp1251 | 23 | | Yes | 1 | -| gb2312_chinese_ci | gb2312 | 24 | Yes | Yes | 1 | -| greek_general_ci | greek | 25 | Yes | Yes | 1 | -| cp1250_general_ci | cp1250 | 26 | Yes | Yes | 1 | -| latin2_croatian_ci | latin2 | 27 | | Yes | 1 | -| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | -| cp1257_lithuanian_ci | cp1257 | 29 | | Yes | 1 | -| latin5_turkish_ci | latin5 | 30 | Yes | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| armscii8_general_ci | armscii8 | 32 | Yes | Yes | 1 | -| utf8_general_ci | utf8 | 33 | Yes | Yes | 1 | -| cp1250_czech_cs | cp1250 | 34 | | Yes | 1 | -| ucs2_general_ci | ucs2 | 35 | Yes | Yes | 1 | -| cp866_general_ci | cp866 | 36 | Yes | Yes | 1 | -| keybcs2_general_ci | keybcs2 | 37 | Yes | Yes | 1 | -| macce_general_ci | macce | 38 | Yes | Yes | 1 | -| macroman_general_ci | macroman | 39 | Yes | Yes | 1 | -| cp852_general_ci | cp852 | 40 | Yes | Yes | 1 | -| latin7_general_ci | latin7 | 41 | Yes | Yes | 1 | -| latin7_general_cs | latin7 | 42 | | Yes | 1 | -| macce_bin | macce | 43 | | Yes | 1 | -| cp1250_croatian_ci | cp1250 | 44 | | Yes | 1 | -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| cp1251_bin | cp1251 | 50 | | Yes | 1 | -| cp1251_general_ci | cp1251 | 51 | Yes | Yes | 1 | -| cp1251_general_cs | cp1251 | 52 | | Yes | 1 | -| macroman_bin | macroman | 53 | | Yes | 1 | -| utf16_general_ci | utf16 | 54 | Yes | Yes | 1 | -| utf16_bin | utf16 | 55 | | Yes | 1 | -| utf16le_general_ci | utf16le | 56 | Yes | Yes | 1 | -| cp1256_general_ci | cp1256 | 57 | Yes | Yes | 1 | -| cp1257_bin | cp1257 | 58 | | Yes | 1 | -| cp1257_general_ci | cp1257 | 59 | Yes | Yes | 1 | -| utf32_general_ci | utf32 | 60 | Yes | Yes | 1 | -| utf32_bin | utf32 | 61 | | Yes | 1 | -| utf16le_bin | utf16le | 62 | | Yes | 1 | -| binary | binary | 63 | Yes | Yes | 1 | -| armscii8_bin | armscii8 | 64 | | Yes | 1 | -| ascii_bin | ascii | 65 | | Yes | 1 | -| cp1250_bin | cp1250 | 66 | | Yes | 1 | -| cp1256_bin | cp1256 | 67 | | Yes | 1 | -| cp866_bin | cp866 | 68 | | Yes | 1 | -| dec8_bin | dec8 | 69 | | Yes | 1 | -| greek_bin | greek | 70 | | Yes | 1 | -| hebrew_bin | hebrew | 71 | | Yes | 1 | -| hp8_bin | hp8 | 72 | | Yes | 1 | -| keybcs2_bin | keybcs2 | 73 | | Yes | 1 | -| koi8r_bin | koi8r | 74 | | Yes | 1 | -| koi8u_bin | koi8u | 75 | | Yes | 1 | -| latin2_bin | latin2 | 77 | | Yes | 1 | -| latin5_bin | latin5 | 78 | | Yes | 1 | -| latin7_bin | latin7 | 79 | | Yes | 1 | -| cp850_bin | cp850 | 80 | | Yes | 1 | -| cp852_bin | cp852 | 81 | | Yes | 1 | -| swe7_bin | swe7 | 82 | | Yes | 1 | -| utf8_bin | utf8 | 83 | | Yes | 1 | -| big5_bin | big5 | 84 | | Yes | 1 | -| euckr_bin | euckr | 85 | | Yes | 1 | -| gb2312_bin | gb2312 | 86 | | Yes | 1 | -| gbk_bin | gbk | 87 | | Yes | 1 | -| sjis_bin | sjis | 88 | | Yes | 1 | -| tis620_bin | tis620 | 89 | | Yes | 1 | -| ucs2_bin | ucs2 | 90 | | Yes | 1 | -| ujis_bin | ujis | 91 | | Yes | 1 | -| geostd8_general_ci | geostd8 | 92 | Yes | Yes | 1 | -| geostd8_bin | geostd8 | 93 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -| cp932_japanese_ci | cp932 | 95 | Yes | Yes | 1 | -| cp932_bin | cp932 | 96 | | Yes | 1 | -| eucjpms_japanese_ci | eucjpms | 97 | Yes | Yes | 1 | -| eucjpms_bin | eucjpms | 98 | | Yes | 1 | -| cp1250_polish_ci | cp1250 | 99 | | Yes | 1 | -| utf16_unicode_ci | utf16 | 101 | | Yes | 1 | -| utf16_icelandic_ci | utf16 | 102 | | Yes | 1 | -| utf16_latvian_ci | utf16 | 103 | | Yes | 1 | -| utf16_romanian_ci | utf16 | 104 | | Yes | 1 | -| utf16_slovenian_ci | utf16 | 105 | | Yes | 1 | -| utf16_polish_ci | utf16 | 106 | | Yes | 1 | -| utf16_estonian_ci | utf16 | 107 | | Yes | 1 | -| utf16_spanish_ci | utf16 | 108 | | Yes | 1 | -| utf16_swedish_ci | utf16 | 109 | | Yes | 1 | -| utf16_turkish_ci | utf16 | 110 | | Yes | 1 | -| utf16_czech_ci | utf16 | 111 | | Yes | 1 | -| utf16_danish_ci | utf16 | 112 | | Yes | 1 | -| utf16_lithuanian_ci | utf16 | 113 | | Yes | 1 | -| utf16_slovak_ci | utf16 | 114 | | Yes | 1 | -| utf16_spanish2_ci | utf16 | 115 | | Yes | 1 | -| utf16_roman_ci | utf16 | 116 | | Yes | 1 | -| utf16_persian_ci | utf16 | 117 | | Yes | 1 | -| utf16_esperanto_ci | utf16 | 118 | | Yes | 1 | -| utf16_hungarian_ci | utf16 | 119 | | Yes | 1 | -| utf16_sinhala_ci | utf16 | 120 | | Yes | 1 | -| utf16_german2_ci | utf16 | 121 | | Yes | 1 | -| utf16_croatian_ci | utf16 | 122 | | Yes | 1 | -| utf16_unicode_520_ci | utf16 | 123 | | Yes | 1 | -| utf16_vietnamese_ci | utf16 | 124 | | Yes | 1 | -| ucs2_unicode_ci | ucs2 | 128 | | Yes | 1 | -| ucs2_icelandic_ci | ucs2 | 129 | | Yes | 1 | -| ucs2_latvian_ci | ucs2 | 130 | | Yes | 1 | -| ucs2_romanian_ci | ucs2 | 131 | | Yes | 1 | -| ucs2_slovenian_ci | ucs2 | 132 | | Yes | 1 | -| ucs2_polish_ci | ucs2 | 133 | | Yes | 1 | -| ucs2_estonian_ci | ucs2 | 134 | | Yes | 1 | -| ucs2_spanish_ci | ucs2 | 135 | | Yes | 1 | -| ucs2_swedish_ci | ucs2 | 136 | | Yes | 1 | -| ucs2_turkish_ci | ucs2 | 137 | | Yes | 1 | -| ucs2_czech_ci | ucs2 | 138 | | Yes | 1 | -| ucs2_danish_ci | ucs2 | 139 | | Yes | 1 | -| ucs2_lithuanian_ci | ucs2 | 140 | | Yes | 1 | -| ucs2_slovak_ci | ucs2 | 141 | | Yes | 1 | -| ucs2_spanish2_ci | ucs2 | 142 | | Yes | 1 | -| ucs2_roman_ci | ucs2 | 143 | | Yes | 1 | -| ucs2_persian_ci | ucs2 | 144 | | Yes | 1 | -| ucs2_esperanto_ci | ucs2 | 145 | | Yes | 1 | -| ucs2_hungarian_ci | ucs2 | 146 | | Yes | 1 | -| ucs2_sinhala_ci | ucs2 | 147 | | Yes | 1 | -| ucs2_german2_ci | ucs2 | 148 | | Yes | 1 | -| ucs2_croatian_ci | ucs2 | 149 | | Yes | 1 | -| ucs2_unicode_520_ci | ucs2 | 150 | | Yes | 1 | -| ucs2_vietnamese_ci | ucs2 | 151 | | Yes | 1 | -| ucs2_general_mysql500_ci | ucs2 | 159 | | Yes | 1 | -| utf32_unicode_ci | utf32 | 160 | | Yes | 1 | -| utf32_icelandic_ci | utf32 | 161 | | Yes | 1 | -| utf32_latvian_ci | utf32 | 162 | | Yes | 1 | -| utf32_romanian_ci | utf32 | 163 | | Yes | 1 | -| utf32_slovenian_ci | utf32 | 164 | | Yes | 1 | -| utf32_polish_ci | utf32 | 165 | | Yes | 1 | -| utf32_estonian_ci | utf32 | 166 | | Yes | 1 | -| utf32_spanish_ci | utf32 | 167 | | Yes | 1 | -| utf32_swedish_ci | utf32 | 168 | | Yes | 1 | -| utf32_turkish_ci | utf32 | 169 | | Yes | 1 | -| utf32_czech_ci | utf32 | 170 | | Yes | 1 | -| utf32_danish_ci | utf32 | 171 | | Yes | 1 | -| utf32_lithuanian_ci | utf32 | 172 | | Yes | 1 | -| utf32_slovak_ci | utf32 | 173 | | Yes | 1 | -| utf32_spanish2_ci | utf32 | 174 | | Yes | 1 | -| utf32_roman_ci | utf32 | 175 | | Yes | 1 | -| utf32_persian_ci | utf32 | 176 | | Yes | 1 | -| utf32_esperanto_ci | utf32 | 177 | | Yes | 1 | -| utf32_hungarian_ci | utf32 | 178 | | Yes | 1 | -| utf32_sinhala_ci | utf32 | 179 | | Yes | 1 | -| utf32_german2_ci | utf32 | 180 | | Yes | 1 | -| utf32_croatian_ci | utf32 | 181 | | Yes | 1 | -| utf32_unicode_520_ci | utf32 | 182 | | Yes | 1 | -| utf32_vietnamese_ci | utf32 | 183 | | Yes | 1 | -| utf8_unicode_ci | utf8 | 192 | | Yes | 1 | -| utf8_icelandic_ci | utf8 | 193 | | Yes | 1 | -| utf8_latvian_ci | utf8 | 194 | | Yes | 1 | -| utf8_romanian_ci | utf8 | 195 | | Yes | 1 | -| utf8_slovenian_ci | utf8 | 196 | | Yes | 1 | -| utf8_polish_ci | utf8 | 197 | | Yes | 1 | -| utf8_estonian_ci | utf8 | 198 | | Yes | 1 | -| utf8_spanish_ci | utf8 | 199 | | Yes | 1 | -| utf8_swedish_ci | utf8 | 200 | | Yes | 1 | -| utf8_turkish_ci | utf8 | 201 | | Yes | 1 | -| utf8_czech_ci | utf8 | 202 | | Yes | 1 | -| utf8_danish_ci | utf8 | 203 | | Yes | 1 | -| utf8_lithuanian_ci | utf8 | 204 | | Yes | 1 | -| utf8_slovak_ci | utf8 | 205 | | Yes | 1 | -| utf8_spanish2_ci | utf8 | 206 | | Yes | 1 | -| utf8_roman_ci | utf8 | 207 | | Yes | 1 | -| utf8_persian_ci | utf8 | 208 | | Yes | 1 | -| utf8_esperanto_ci | utf8 | 209 | | Yes | 1 | -| utf8_hungarian_ci | utf8 | 210 | | Yes | 1 | -| utf8_sinhala_ci | utf8 | 211 | | Yes | 1 | -| utf8_german2_ci | utf8 | 212 | | Yes | 1 | -| utf8_croatian_ci | utf8 | 213 | | Yes | 1 | -| utf8_unicode_520_ci | utf8 | 214 | | Yes | 1 | -| utf8_vietnamese_ci | utf8 | 215 | | Yes | 1 | -| utf8_general_mysql500_ci | utf8 | 223 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+--------------------------+----------+------+---------+----------+---------+ -219 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -TiDB 不支持二进制以外的排序规则。`SHOW COLLATION` 语句仅用于确保与 MySQL 的兼容性。 - -## 另请参阅 - -* [SHOW CHARACTER SET](/v2.1/reference/sql/statements/show-character-set.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-columns-from.md b/v2.1/reference/sql/statements/show-columns-from.md deleted file mode 100644 index d883b5f6b030..000000000000 --- a/v2.1/reference/sql/statements/show-columns-from.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: SHOW [FULL] COLUMNS FROM -summary: TiDB 数据库中 SHOW [FULL] COLUMNS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] COLUMNS FROM - -`SHOW [FULL] COLUMNS FROM` 语句用于以表格格式描述表或视图中的列。可选关键字 `FULL` 用于显示当前用户对该列的权限，以及表定义中的 `comment`。 - -`SHOW [FULL] FIELDS FROM`，`DESC `，`DESCRIBE
` 和 `EXPLAIN
` 语句都是 `SHOW [FULL] COLUMNS FROM` 的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -```sql -mysql> create view v1 as select 1; -Query OK, 0 rows affected (0.11 sec) - -mysql> show columns from v1; -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) - -mysql> desc v1; -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) - -mysql> describe v1; -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) - -mysql> explain v1; -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) - -mysql> show fields from v1; -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) - -mysql> show full columns from v1; -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| 1 | bigint(1) | NULL | YES | | NULL | | select,insert,update,references | | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -1 row in set (0.00 sec) - -mysql> show full columns from mysql.user; -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Host | char(64) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| User | char(32) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| Password | char(41) | utf8mb4_bin | YES | | NULL | | select,insert,update,references | | -| Select_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Insert_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Update_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Delete_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Process_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Grant_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| References_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_db_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Super_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_tmp_table_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Lock_tables_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Execute_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Index_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_user_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Event_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Trigger_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Account_locked | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -29 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] COLUMNS FROM` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-create-table.md b/v2.1/reference/sql/statements/show-create-table.md deleted file mode 100644 index 96be29efa3b8..000000000000 --- a/v2.1/reference/sql/statements/show-create-table.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: SHOW CREATE TABLE -summary: TiDB 数据库中 SHOW CREATE TABLE 的使用概况。 -category: reference ---- - -# SHOW CREATE TABLE - -`SHOW CREATE TABLE` 语句用于显示用 SQL 重新创建已有表的确切语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a INT); -Query OK, 0 rows affected (0.12 sec) - -mysql> SHOW CREATE TABLE t1; -+-------+------------------------------------------------------------------------------------------------------------+ -| Table | Create Table | -+-------+------------------------------------------------------------------------------------------------------------+ -| t1 | CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | -+-------+------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CREATE TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v2.1/reference/sql/statements/drop-table.md) -* [SHOW TABLES](/v2.1/reference/sql/statements/show-tables.md) -* [SHOW COLUMNS FROM](/v2.1/reference/sql/statements/show-columns-from.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-databases.md b/v2.1/reference/sql/statements/show-databases.md deleted file mode 100644 index 55a9e7d6efaf..000000000000 --- a/v2.1/reference/sql/statements/show-databases.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: SHOW DATABASES -summary: TiDB 数据库中 SHOW DATABASES 的使用概况。 -category: reference ---- - -# SHOW DATABASES - -`SHOW DATABASES` 语句用于显示当前用户有权访问的数据库列表。当前用户无权访问的数据库将从列表中隐藏。`information_schema` 数据库始终出现在列表的最前面。 - -`SHOW SCHEMAS` 是 `SHOW DATABASES` 语句的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -```sql -mysql> SHOW DATABASES; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) - -mysql> CREATE DATABASE mynewdb; -Query OK, 0 rows affected (0.10 sec) - -mysql> SHOW DATABASES; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mynewdb | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW DATABASES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW SCHEMAS](/v2.1/reference/sql/statements/show-schemas.md) -* [DROP DATABASE](/v2.1/reference/sql/statements/drop-database.md) -* [CREATE DATABASE](/v2.1/reference/sql/statements/create-database.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-engines.md b/v2.1/reference/sql/statements/show-engines.md deleted file mode 100644 index 7207505c6c37..000000000000 --- a/v2.1/reference/sql/statements/show-engines.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: SHOW ENGINES -summary: TiDB 数据库中 SHOW ENGINES 的使用概况。 -category: reference ---- - -# SHOW ENGINES - -`SHOW ENGINES` 语句仅提供 MySQL 兼容性。 - -## 语法图 - -```sql -SHOW ENGINES -``` - -## 示例 - -```sql -mysql> SHOW ENGINES; -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -| Engine | Support | Comment | Transactions | XA | Savepoints | -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -| InnoDB | DEFAULT | Supports transactions, row-level locking, and foreign keys | YES | YES | YES | -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `SHOW ENGINES` 语句始终只返回 InnoDB 作为其支持的引擎。但 TiDB 内部通常使用 TiKV 作为存储引擎。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-errors.md b/v2.1/reference/sql/statements/show-errors.md deleted file mode 100644 index ddac3b070729..000000000000 --- a/v2.1/reference/sql/statements/show-errors.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: SHOW ERRORS -summary: TiDB 数据库中 SHOW ERRORS 的使用概况。 -category: reference ---- - -# SHOW ERRORS - -`SHOW ERRORS` 语句用于显示已执行语句中的错误。一旦先前的语句成功执行，就会清除错误缓冲区，这时 `SHOW ERRORS` 会返回一个空集。 - -当前的 `sql_mode` 很大程度决定了哪些语句会产生错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -```sql -mysql> select invalid; -ERROR 1054 (42S22): Unknown column 'invalid' in 'field list' -mysql> create invalid; -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" -mysql> SHOW ERRORS; -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Level | Code | Message | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Error | 1054 | Unknown column 'invalid' in 'field list' | -| Error | 1064 | You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -2 rows in set (0.00 sec) - -mysql> CREATE invalid2; -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 15 near "invalid2" -mysql> SELECT 1; -+------+ -| 1 | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) - -mysql> SHOW ERRORS; -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW ERRORS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW WARNINGS](/v2.1/reference/sql/statements/show-warnings.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-fields-from.md b/v2.1/reference/sql/statements/show-fields-from.md deleted file mode 100644 index e29d40b9d16c..000000000000 --- a/v2.1/reference/sql/statements/show-fields-from.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW [FULL] FIELDS FROM -summary: TiDB 数据库中 SHOW [FULL] FIELDS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] FIELDS FROM - -`SHOW [FULL] FIELDS FROM` 是 [`SHOW [FULL] COLUMNS FROM`](/v2.1/reference/sql/statements/show-columns-from.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-grants.md b/v2.1/reference/sql/statements/show-grants.md deleted file mode 100644 index f5a4abbb41f4..000000000000 --- a/v2.1/reference/sql/statements/show-grants.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: SHOW GRANTS -summary: TiDB 数据库中 SHOW GRANTS 的使用概况。 -category: reference ---- - -# SHOW GRANTS - -`SHOW GRANTS` 语句用于显示与用户关联的权限列表。与在 MySQL 中一样，`USAGE` 权限表示登录 TiDB 的能力。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -```sql -mysql> SHOW GRANTS; -+-------------------------------------------+ -| Grants for User | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SHOW GRANTS FOR 'u1'; -ERROR 1141 (42000): There is no such grant defined for user 'u1' on host '%' -mysql> CREATE USER u1; -Query OK, 1 row affected (0.04 sec) - -mysql> GRANT SELECT ON test.* TO u1; -Query OK, 0 rows affected (0.04 sec) - -mysql> SHOW GRANTS FOR u1; -+------------------------------------+ -| Grants for u1@% | -+------------------------------------+ -| GRANT USAGE ON *.* TO 'u1'@'%' | -| GRANT Select ON test.* TO 'u1'@'%' | -+------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW GRANTS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [GRANT](/v2.1/reference/sql/statements/grant-privileges.md) diff --git a/v2.1/reference/sql/statements/show-index.md b/v2.1/reference/sql/statements/show-index.md deleted file mode 100644 index 8d5d0100b7a4..000000000000 --- a/v2.1/reference/sql/statements/show-index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW INDEX [FROM|IN] -summary: TiDB 数据库中 SHOW INDEX [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEX [FROM|IN] - -`SHOW INDEX [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/v2.1/reference/sql/statements/show-indexes.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-indexes.md b/v2.1/reference/sql/statements/show-indexes.md deleted file mode 100644 index adb12ef4b004..000000000000 --- a/v2.1/reference/sql/statements/show-indexes.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: SHOW INDEXES [FROM|IN] -summary: TiDB 数据库中 SHOW INDEXES [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEXES [FROM|IN] - -`SHOW INDEXES [FROM|IN]` 语句用于列出指定表上的索引。`SHOW INDEX [FROM | IN]` 和 `SHOW KEYS [FROM | IN]` 是该语句的别名。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowIndexKwd:** - -![ShowIndexKwd](/media/sqlgram/ShowIndexKwd.png) - -**FromOrIn:** - -![FromOrIn](/media/sqlgram/FromOrIn.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT, INDEX(col1)); -Query OK, 0 rows affected (0.12 sec) - -mysql> SHOW INDEXES FROM t1; -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) - -mysql> SHOW INDEX FROM t1; -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) - -mysql> SHOW KEYS FROM t1; -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW INDEXES [FROM|IN]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) -* [DROP INDEX](/v2.1/reference/sql/statements/drop-index.md) -* [CREATE INDEX](/v2.1/reference/sql/statements/create-index.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-keys.md b/v2.1/reference/sql/statements/show-keys.md deleted file mode 100644 index 5ae1017f550a..000000000000 --- a/v2.1/reference/sql/statements/show-keys.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW KEYS [FROM|IN] -summary: TiDB 数据库中 SHOW KEYS [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW KEYS [FROM|IN] - -`SHOW KEYS [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/v2.1/reference/sql/statements/show-indexes.md) 语句的别名。包含该语句提供了 MySQL 兼容性。。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-privileges.md b/v2.1/reference/sql/statements/show-privileges.md deleted file mode 100644 index cb96e3b2f9e4..000000000000 --- a/v2.1/reference/sql/statements/show-privileges.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: SHOW PRIVILEGES -summary: TiDB 数据库中 SHOW PRIVILEGES 的使用概况。 -category: reference ---- - -# SHOW PRIVILEGES - -`SHOW PRIVILEGES` 语句用于显示 TiDB 中可分配权限的列表。此列表为静态列表，不反映当前用户的权限。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -## 示例 - -```sql -mysql> show privileges; -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Privilege | Context | Comment | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Alter | Tables | To alter the table | -| Alter | Tables | To alter the table | -| Alter routine | Functions,Procedures | To alter or drop stored functions/procedures | -| Create | Databases,Tables,Indexes | To create new databases and tables | -| Create routine | Databases | To use CREATE FUNCTION/PROCEDURE | -| Create temporary tables | Databases | To use CREATE TEMPORARY TABLE | -| Create view | Tables | To create new views | -| Create user | Server Admin | To create new users | -| Delete | Tables | To delete existing rows | -| Drop | Databases,Tables | To drop databases, tables, and views | -| Event | Server Admin | To create, alter, drop and execute events | -| Execute | Functions,Procedures | To execute stored routines | -| File | File access on server | To read and write files on the server | -| Grant option | Databases,Tables,Functions,Procedures | To give to other users those privileges you possess | -| Index | Tables | To create or drop indexes | -| Insert | Tables | To insert data into tables | -| Lock tables | Databases | To use LOCK TABLES (together with SELECT privilege) | -| Process | Server Admin | To view the plain text of currently executing queries | -| Proxy | Server Admin | To make proxy user possible | -| References | Databases,Tables | To have references on tables | -| Reload | Server Admin | To reload or refresh tables, logs and privileges | -| Replication client | Server Admin | To ask where the slave or master servers are | -| Replication slave | Server Admin | To read binary log events from the master | -| Select | Tables | To retrieve rows from table | -| Show databases | Server Admin | To see all databases with SHOW DATABASES | -| Show view | Tables | To see views with SHOW CREATE VIEW | -| Shutdown | Server Admin | To shut down the server | -| Super | Server Admin | To use KILL thread, SET GLOBAL, CHANGE MASTER, etc. | -| Trigger | Tables | To use triggers | -| Create tablespace | Server Admin | To create/alter/drop tablespaces | -| Update | Tables | To update existing rows | -| Usage | Server Admin | No privileges - allow connect only | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -32 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW GRANTS](/v2.1/reference/sql/statements/show-grants.md) -* [GRANT ](/v2.1/reference/sql/statements/grant-privileges.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-processlist.md b/v2.1/reference/sql/statements/show-processlist.md deleted file mode 100644 index d2acbee586af..000000000000 --- a/v2.1/reference/sql/statements/show-processlist.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: SHOW [FULL] PROCESSLIST -summary: TiDB 数据库中 SHOW [FULL] PROCESSLIST 的使用概况。 -category: reference ---- - -# SHOW [FULL] PROCESSLIST - -`SHOW [FULL] PROCESSLIST` 语句列出连接到相同 TiDB 服务器的当前会话。`Info` 列包含查询文本，除非指定可选关键字 `FULL`，否则文本会被截断。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -```sql -mysql> SHOW PROCESSLIST; -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 中的 `State` 列是非描述性的。在 TiDB 中，将状态表示为单个值更复杂，因为查询是并行执行的，而且每个 GO 线程在任一时刻都有不同的状态。 - -## 另请参阅 - -* [KILL \[TIDB\]](/v2.1/reference/sql/statements/kill.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-schemas.md b/v2.1/reference/sql/statements/show-schemas.md deleted file mode 100644 index 51d491f2f1fb..000000000000 --- a/v2.1/reference/sql/statements/show-schemas.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW SCHEMAS -summary: TiDB 数据库中 SHOW SCHEMAS 的使用概况。 -category: reference ---- - -# SHOW SCHEMAS - -`SHOW SCHEMAS` 语句是 [`SHOW DATABASES`](/v2.1/reference/sql/statements/show-databases.md) 的别名。包含该语句提供了 MySQL 兼容性。。 \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-status.md b/v2.1/reference/sql/statements/show-status.md deleted file mode 100644 index 238dbc7cf0a3..000000000000 --- a/v2.1/reference/sql/statements/show-status.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] STATUS -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] STATUS 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] STATUS - -`SHOW [GLOBAL|SESSION] STATUS` 语句用于提供 MySQL 兼容性，对 TiDB 没有作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -```sql -mysql> show status; -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) - -mysql> show global status; -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [FLUSH STATUS](/v2.1/reference/sql/statements/flush-status.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-table-regions.md b/v2.1/reference/sql/statements/show-table-regions.md deleted file mode 100644 index d6cc796d5e88..000000000000 --- a/v2.1/reference/sql/statements/show-table-regions.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: SHOW TABLE REGIONS -summary: 了解如何使用 TiDB 数据库中的 SHOW TABLE REGIONS。 -category: reference ---- - -# SHOW TABLE REGIONS - -`SHOW TABLE REGIONS` 语句用于显示 TiDB 中某个表的 Region 信息。 - -## 语法图 - -```sql -SHOW TABLE [table_name] REGIONS [WhereClauseOptional]; - -SHOW TABLE [table_name] INDEX [index_name] REGIONS [WhereClauseOptional]; -``` - -`SHOW TABLE REGIONS` 会返回如下列： - -* `REGION_ID`：Region 的 ID。 -* `START_KEY`：Region 的 Start key。 -* `END_KEY`：Region 的 End key。 -* `LEADER_ID`：Region 的 Leader ID。 -* `LEADER_STORE_ID`：Region leader 所在的 store (TiKV) ID。 -* `PEERS`：Region 所有副本的 ID。 -* `SCATTERING`：Region 是否正在调度中。 - -## 示例 - -```sql -test> create table t (id int key,name varchar(50), index (name)); -Query OK, 0 rows affected --- 默认新建表后会单独切分出一个 Region 来存放该表的数据，开始时行数据和索引数据都会写到这个 Region。 -test> show table t regions; -+-----------+-----------+---------+-----------+-----------------+-----------+------------+ -| REGION_ID | START_KEY | END_Key | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+ -| 5 | t_43_ | | 8 | 2 | 8, 14, 93 | 0 | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+ --- 上面 START_KEY 列的值 t_43_ 中，t 是表数据的前缀，43 是表 t 的 table ID。 --- END_KEY 列的值为空（""）表示无穷大。 -1 row in set --- 用 `SPLIT TABLE REGION` 语法切分行数据的 Region，下面语法把表 t 的行数据切分成 5 个 Region。 -test> split table t between (0) and (100000) regions 5; -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 5 | 1.0 | -+--------------------+----------------------+ -1 row in set --- 表 t 现在一共有 6 个 Region，其中 98、103、109、113、2 用来存行数据，Region 68 用来存索引数据。 -test> show table t regions; -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+ -| 98 | t_43_r | t_43_r_20000 | 100 | 4 | 100, 101, 102 | 0 | -| 103 | t_43_r_20000 | t_43_r_40000 | 108 | 5 | 104, 108, 107 | 0 | -| 109 | t_43_r_40000 | t_43_r_60000 | 110 | 1 | 110, 111, 112 | 0 | -| 113 | t_43_r_60000 | t_43_r_80000 | 117 | 6 | 116, 117, 118 | 0 | -| 2 | t_43_r_80000 | | 3 | 1 | 3, 91, 92 | 0 | -| 68 | t_43_ | t_43_r | 90 | 6 | 69, 90, 97 | 0 | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+ -6 rows in set --- Region 98 的 START_KEY 和 END_KEY 中，t_43 是表数据前缀和 table ID，_r 是表 t record 数据的前缀，索引数据的前缀是 _i， --- 所以 Region 98 的 START_KEY 和 END_KEY 表示用来存储 [-inf, 20000) 之前的 record 数据。其他 Region (103, 109, 113, 2) 的存储范围依次类推。 --- Region 68 用来存储索引数据存储。表 t 索引数据的起始 key 是 t_43_i，处于 Region 68 的存储范围内。 - --- 用 `SPLIT TABLE REGION` 语法切分索引数据的 Region，下面语法把表 t 的索引 name 数据在 [a,z] 范围内切分成 2 个 Region。 -test> split table t index name between ("a") and ("z") regions 2; -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 2 | 1.0 | -+--------------------+----------------------+ -1 row in set --- 现在表 t 一共有 7 个 Region，其中 5 个 Region (98, 103, 109, 113, 2) 用来存表 t 的 record 数据，另外 2 个 Region (125, 68) 用来存 name 索引的数据。 -test> show table t regions; -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+ -| 98 | t_43_r | t_43_r_20000 | 100 | 4 | 100, 101, 102 | 0 | -| 103 | t_43_r_20000 | t_43_r_40000 | 108 | 5 | 104, 108, 107 | 0 | -| 109 | t_43_r_40000 | t_43_r_60000 | 110 | 1 | 110, 111, 112 | 0 | -| 113 | t_43_r_60000 | t_43_r_80000 | 117 | 6 | 116, 117, 118 | 0 | -| 2 | t_43_r_80000 | | 3 | 1 | 3, 91, 92 | 0 | -| 125 | t_43_i_1_ | t_43_i_1_016d80000000000000 | 127 | 6 | 127, 128, 129 | 0 | -| 68 | t_43_i_1_016d80000000000000 | t_43_r | 90 | 6 | 69, 90, 97 | 0 | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+ -7 rows in set - --- 查看表 t 在 store 1 上的 region，用 where 条件过滤。 -test> show table t regions where leader_store_id =1; -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+ -| 109 | t_43_r_40000 | t_43_r_60000 | 110 | 1 | 110, 111, 112 | 0 | -| 2 | t_43_r_80000 | | 3 | 1 | 3, 91, 92 | 0 | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+ -2 rows in set -``` - -## 另请参阅 - -* [SPLIT REGION](/v2.1/reference/sql/statements/split-region.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) diff --git a/v2.1/reference/sql/statements/show-table-status.md b/v2.1/reference/sql/statements/show-table-status.md deleted file mode 100644 index e91d65ca2e96..000000000000 --- a/v2.1/reference/sql/statements/show-table-status.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: SHOW TABLE STATUS -summary: TiDB 数据库中 SHOW TABLE STATUS 的使用概况。 -category: reference ---- - -# SHOW TABLE STATUS - -`SHOW TABLE STATUS` 语句用于显示 TiDB 中表的各种统计信息。如果显示统计信息过期，建议运行 [`ANALYZE TABLE`](/v2.1/reference/sql/statements/analyze-table.md)。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> SHOW TABLE STATUS LIKE 't1'\G -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 0 - Avg_row_length: 0 - Data_length: 0 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) - -mysql> analyze table t1; -Query OK, 0 rows affected (0.12 sec) - -mysql> SHOW TABLE STATUS LIKE 't1'\G -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 5 - Avg_row_length: 16 - Data_length: 80 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW TABLE STATUS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW TABLES](/v2.1/reference/sql/statements/show-tables.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v2.1/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-tables.md b/v2.1/reference/sql/statements/show-tables.md deleted file mode 100644 index 6a03c4f6b175..000000000000 --- a/v2.1/reference/sql/statements/show-tables.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: SHOW [FULL] TABLES -summary: TiDB 数据库中 SHOW [FULL] TABLES 的使用概况。 -category: reference ---- - -# SHOW [FULL] TABLES - -`SHOW [FULL] TABLES` 语句用于显示当前所选数据库中表和视图的列表。可选关键字 `FULL` 说明表的类型是 `BASE TABLE` 还是 `VIEW`。 - -若要在不同的数据库中显示表，可使用 `SHOW TABLES IN DatabaseName` 语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.12 sec) - -mysql> CREATE VIEW v1 AS SELECT 1; -Query OK, 0 rows affected (0.10 sec) - -mysql> SHOW TABLES; -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -| v1 | -+----------------+ -2 rows in set (0.00 sec) - -mysql> SHOW FULL TABLES; -+----------------+------------+ -| Tables_in_test | Table_type | -+----------------+------------+ -| t1 | BASE TABLE | -| v1 | VIEW | -+----------------+------------+ -2 rows in set (0.00 sec) - -mysql> SHOW TABLES IN mysql; -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] TABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v2.1/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/show-variables.md b/v2.1/reference/sql/statements/show-variables.md deleted file mode 100644 index 37e55403b756..000000000000 --- a/v2.1/reference/sql/statements/show-variables.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] VARIABLES -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] VARIABLES 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] VARIABLES - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句用于显示 `GLOBAL` 或 `SESSION` 范围的变量列表。如果未指定范围，则应用默认范围 `SESSION`。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -```sql -mysql> SHOW GLOBAL VARIABLES LIKE 'tidb%'; -+------------------------------------+---------------+ -| Variable_name | Value | -+------------------------------------+---------------+ -| tidb_current_ts | 0 | -| tidb_wait_split_region_timeout | 300 | -| tidb_query_log_max_len | 2048 | -| tidb_mem_quota_indexlookupjoin | 34359738368 | -| tidb_index_join_batch_size | 25000 | -| tidb_index_lookup_concurrency | 4 | -| tidb_hash_join_concurrency | 5 | -| tidb_mem_quota_mergejoin | 34359738368 | -| tidb_checksum_table_concurrency | 4 | -| tidb_projection_concurrency | 4 | -| tidb_ddl_reorg_priority | PRIORITY_LOW | -| tidb_batch_delete | 0 | -| tidb_batch_insert | 0 | -| tidb_optimizer_selectivity_level | 0 | -| tidb_backoff_lock_fast | 100 | -| tidb_enable_streaming | 0 | -| tidb_config | | -| tidb_retry_limit | 10 | -| tidb_force_priority | NO_PRIORITY | -| tidb_ddl_reorg_worker_cnt | 16 | -| tidb_index_serial_scan_concurrency | 1 | -| tidb_index_lookup_join_concurrency | 4 | -| tidb_constraint_check_in_place | 0 | -| tidb_scatter_region | 0 | -| tidb_mem_quota_topn | 34359738368 | -| tidb_check_mb4_value_in_utf8 | 1 | -| tidb_hashagg_partial_concurrency | 4 | -| tidb_index_lookup_size | 20000 | -| tidb_max_chunk_size | 1024 | -| tidb_disable_txn_auto_retry | 1 | -| tidb_build_stats_concurrency | 4 | -| tidb_auto_analyze_ratio | 0.5 | -| tidb_general_log | 0 | -| tidb_ddl_reorg_batch_size | 1024 | -| tidb_wait_split_region_finish | 1 | -| tidb_skip_utf8_check | 0 | -| tidb_opt_agg_push_down | 0 | -| tidb_auto_analyze_start_time | 00:00 +0000 | -| tidb_distsql_scan_concurrency | 15 | -| tidb_mem_quota_sort | 34359738368 | -| tidb_opt_write_row_id | 0 | -| tidb_enable_table_partition | 0 | -| tidb_auto_analyze_end_time | 23:59 +0000 | -| tidb_mem_quota_nestedloopapply | 34359738368 | -| tidb_hashagg_final_concurrency | 4 | -| tidb_slow_log_threshold | 300 | -| tidb_mem_quota_query | 34359738368 | -| tidb_snapshot | | -| tidb_dml_batch_size | 20000 | -| tidb_slow_query_file | tidb-slow.log | -| tidb_opt_insubquery_unfold | 0 | -| tidb_mem_quota_indexlookupreader | 34359738368 | -| tidb_mem_quota_hashjoin | 34359738368 | -+------------------------------------+---------------+ -53 rows in set (0.01 sec) - -mysql> SHOW GLOBAL VARIABLES LIKE 'time_zone%'; -+---------------+--------+ -| Variable_name | Value | -+---------------+--------+ -| time_zone | SYSTEM | -+---------------+--------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SET](/v2.1/reference/sql/statements/set-variable.md) diff --git a/v2.1/reference/sql/statements/show-warnings.md b/v2.1/reference/sql/statements/show-warnings.md deleted file mode 100644 index b3dd5698289a..000000000000 --- a/v2.1/reference/sql/statements/show-warnings.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: SHOW WARNINGS -summary: TiDB 数据库中 SHOW WARNINGS 的使用概况。 -category: reference ---- - -# SHOW WARNINGS - -`SHOW WARNINGS` 语句用于显示当前客户端连接中已执行语句的报错列表。与在 MySQL 中一样，`sql_mode` 极大地影响哪些语句会导致错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a INT UNSIGNED); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 VALUES (0); -Query OK, 1 row affected (0.02 sec) - -mysql> SELECT 1/a FROM t1; -+------+ -| 1/a | -+------+ -| NULL | -+------+ -1 row in set, 1 warning (0.00 sec) - -mysql> SHOW WARNINGS; -+---------+------+---------------+ -| Level | Code | Message | -+---------+------+---------------+ -| Warning | 1365 | Division by 0 | -+---------+------+---------------+ -1 row in set (0.00 sec) - -mysql> INSERT INTO t1 VALUES (-1); -ERROR 1264 (22003): Out of range value for column 'a' at row 1 -mysql> SELECT * FROM t1; -+------+ -| a | -+------+ -| 0 | -+------+ -1 row in set (0.00 sec) - -mysql> SET sql_mode=''; -Query OK, 0 rows affected (0.00 sec) - -mysql> INSERT INTO t1 VALUES (-1); -Query OK, 1 row affected, 1 warning (0.01 sec) - -mysql> SHOW WARNINGS; -+---------+------+---------------------------+ -| Level | Code | Message | -+---------+------+---------------------------+ -| Warning | 1690 | constant -1 overflows int | -+---------+------+---------------------------+ -1 row in set (0.00 sec) - -mysql> SELECT * FROM t1; -+------+ -| a | -+------+ -| 0 | -| 0 | -+------+ -2 rows in set (0.00 sec) - -``` - -## MySQL 兼容性 - -`SHOW WARNINGS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW ERRORS](/v2.1/reference/sql/statements/show-errors.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/split-region.md b/v2.1/reference/sql/statements/split-region.md deleted file mode 100644 index d8ea6780370c..000000000000 --- a/v2.1/reference/sql/statements/split-region.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Split Region 使用文档 -category: reference ---- - -# Split Region 使用文档 - -在 TiDB 中新建一个表后，默认会单独切分出 1 个 Region 来存储这个表的数据，这个默认行为由配置文件中的 `split-table` 控制。当这个 Region 中的数据超过默认 Region 大小限制后，这个 Region 会开始分裂成 2 个 Region。 - -上述情况中，如果在新建的表上发生大批量写入，则会造成热点，因为开始只有一个 Region，所有的写请求都发生在该 Region 所在的那台 TiKV 上。 - -为解决上述场景中的热点问题，TiDB 引入了预切分 Region 的功能，即可以根据指定的参数，预先为某个表切分出多个 Region，并打散到各个 TiKV 上去。 - -## Split Region 的使用 - -Split Region 有 2 种不同的语法，具体如下： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -`BETWEEN lower_value AND upper_value REGIONS region_num` 语法是通过指定上、下边界和 Region 数量，然后在上、下边界之间均匀切分出 `region_num` 个 Region。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ... -``` - -`BY value_list…` 语法将手动指定一系列的点，然后根据这些指定的点切分 Region，适用于数据不均匀分布的场景。 - -### Split Table Region - -表中行数据的 key 由 `table_id` 和 `row_id` 编码组成，格式如下： - -```go -t[table_id]_r[row_id] -``` - -例如，当 `table_id` 是 22，`row_id` 是 11 时： - -```go -t22_r11 -``` - -同一表中行数据的 `table_id` 是一样的，但 `row_id` 肯定不一样，所以可以根据 `row_id` 来切分 Region。 - -#### 均匀切分 - -由于 `row_id` 是整数，所以根据指定的 `lower_value`、`upper_value` 以及 `region_num`，可以推算出需要切分的 key。TiDB 先计算 step（`step = (upper_value - lower_value)/num`），然后在 `lower_value` 和 `upper_value` 之间每隔 step 区间切一次，最终切出 `num` 个 Region。 - -例如，对于表 t，如果想要从 `minInt64`~`maxInt64` 之间均匀切割出 16 个 Region，可以用以下语句： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 从 minInt64 到 maxInt64 之间均匀切割出 16 个 Region。如果已知主键的范围没有这么大，比如只会在 0~1000000000 之间，那可以用 0 和 1000000000 分别代替上面的 minInt64 和 maxInt64 来切分 Region。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (0) AND (1000000000) REGIONS 16; -``` - -#### 不均匀切分 - -如果已知数据不是均匀分布的，比如想要 -inf ~ 10000 切一个 Region，10000 ~ 90000 切一个 Region，90000 ~ +inf 切一个 Region，可以通过手动指定点来切分 Region，示例如下： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BY (10000), (90000); -``` - -### Split Index Region - -表中索引数据的 key 由 `table_id`、`index_id` 以及索引列的值编码组成，格式如下： - -```go -t[table_id]_i[index_id][index_value] -``` - -例如，当 `table_id` 是 22，`index_id` 是 5，`index_value` 是 abc 时： - -```go -t22_i5abc -``` - -同一表中同一索引数据的 `table_id` 和 `index_id` 是一样的，所以要根据 `index_value` 切分索引 Region。 - -#### 均匀切分 - -索引均匀切分与行数据均匀切分的原理一样，只是计算 step 的值较为复杂，因为 `index_value` 可能不是整数。 - -`upper` 和 `lower` 的值会先编码成 byte 数组，去掉 `lower` 和 `upper` byte 数组的最长公共前缀后，从 `lower` 和 `upper` 各取前 8 字节转成 uint64，再计算 `step = (upper - lower)/num`。计算出 step 后再将 step 编码成 byte 数组，添加到之前 `upper`和 `lower`的最长公共前缀后面组成一个 key 后去做切分。示例如下： - -如果索引 idx 的列也是整数类型，可以用如下 SQL 语句切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 中 idx 索引数据 Region 从 `minInt64` 到 `maxInt64` 之间均匀切割出 16 个 Region。 - -如果索引 idx1 的列是 varchar 类型，希望根据前缀字母来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx1 BETWEEN ("a") AND ("z") REGIONS 26; -``` - -该语句会把表 t 中 idx1 索引数据的 Region 从 a~z 切成 26 个 Region，region1 的范围是 [minIndexValue, b)，region2 的范围是 [b, c)，……，region26 的范围是 [z, maxIndexValue)。对于 idx 索引以 a 为前缀的数据都会写到 region1，以 b 为前缀的索引数据都会写到 region2，以此类推。 - -如果索引 idx2 的列是 timestamp/datetime 等时间类型，希望根据时间区间来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx2 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -该语句会把表 t 中 idx2 的索引数据 Region 从 `2010-01-01 00:00:00` 到 `2020-01-01 00:00:00` 切成 10 个 Region。region1 的范围是从 `[minIndexValue, 2011-01-01 00:00:00)`，region2 的范围是 `[2011-01-01 00:00:00, 2012-01-01 00:00:00)`…… - -其他索引列类型的切分方法也是类似的。 - -对于联合索引的数据 Region 切分，唯一不同的是可以指定多个 column 的值。 - -比如索引 `idx3 (a, b)` 包含 2 列，a 是 timestamp，b 是 int。如果只想根据 a 列做时间范围的切分，可以用切分单列时间索引的 SQL 语句来切分，`lower_value` 和 `upper_velue` 中不指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -如果想在时间相同的情况下，根据 b 列再做一次切分，在切分时指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00", "a") AND ("2010-01-01 00:00:00", "z") REGIONS 10; -``` - -该语句在 a 列时间前缀相同的情况下，根据 b 列的值从 a~z 切了 10 个 Region。如果指定的 a 列的值不相同，那么可能不会用到 b 列的值。 - -#### 不均匀切分 - -索引数据也可以根据用户指定的索引值来做切分。 - -假如有 idx4 (a,b)，其中 a 列是 varchar 类型， b 列是 timestamp 类型。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t1 INDEX idx4 BY ("a", "2000-01-01 00:00:01"), ("b", "2019-04-17 14:26:19"), ("c", ""); -``` - -该语句指定了 3 个值，会切分出 4 个 Region，每个 Region 的范围如下。 - -``` -region1 [ minIndexValue , ("a", "2000-01-01 00:00:01")) -region2 [("a", "2000-01-01 00:00:01") , ("b", "2019-04-17 14:26:19")) -region3 [("b", "2019-04-17 14:26:19") , ("c", "") ) -region4 [("c", "") , maxIndexValue ) -``` - -## pre_split_regions - -使用带有 `shard_row_id_bits` 的表时，如果希望建表时就均匀切分 Region，可以考虑配合 `pre_split_regions` 一起使用，用来在建表成功后就开始预均匀切分 `2^(pre_split_regions)` 个 Region。 - -> **注意：** -> -> `pre_split_regions` 必须小于等于 `shard_row_id_bits`。 - -### 示例 - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int,index idx1(a)) shard_row_id_bits = 4 pre_split_regions=2; -``` - -该语句在建表后，会对这个表 t 预切分出 4 + 1 个 Region。4 (2^2) 个 Region 是用来存 table 的行数据的，1 个 Region 是用来存 idx1 索引的数据。 - -4 个 table Region 的范围区间如下： - -``` -region1: [ -inf , 1<<61 ) -region2: [ 1<<61 , 2<<61 ) -region3: [ 2<<61 , 3<<61 ) -region4: [ 3<<61 , +inf ) -``` - -## 相关 session 变量 - -和 `SPLIT REGION` 语句相关的 session 变量有 `tidb_wait_split_region_finish` 和 `tidb_wait_split_region_timeout`，具体可参考 [TiDB 专用系统变量和语法](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/v2.1/reference/sql/statements/start-transaction.md b/v2.1/reference/sql/statements/start-transaction.md deleted file mode 100644 index cfb781cf6bdd..000000000000 --- a/v2.1/reference/sql/statements/start-transaction.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: START TRANSACTION -summary: TiDB 数据库中 START TRANSACTION 的使用概况。 -category: reference ---- - -# START TRANSACTION - -`START TRANSACTION` 语句用于在 TiDB 内部启动新事务。它类似于语句 `BEGIN` 和 `SET autocommit = 0`。 - -在没有 `START TRANSACTION` 语句的情况下，每个语句都会在各自的事务中自动提交，这样可确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -Query OK, 0 rows affected (0.12 sec) - -mysql> START TRANSACTION; -Query OK, 0 rows affected (0.00 sec) - -mysql> INSERT INTO t1 VALUES (1); -Query OK, 1 row affected (0.00 sec) - -mysql> COMMIT; -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`START TRANSACTION` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v2.1/reference/sql/statements/commit.md) -* [ROLLBACK](/v2.1/reference/sql/statements/rollback.md) -* [BEGIN](/v2.1/reference/sql/statements/begin.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/trace.md b/v2.1/reference/sql/statements/trace.md deleted file mode 100644 index a8a64a40b7b4..000000000000 --- a/v2.1/reference/sql/statements/trace.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: TRACE -summary: TiDB 数据库中 TRACE 的使用概况。 -category: reference ---- - -# TRACE - -`TRACE` 语句用于提供查询执行的详细信息，可通过 TiDB 服务器状态端口所公开的图形界面进行查看。 - -## 语法图 - -**TraceStmt:** - -![TraceStmt](/media/sqlgram/TraceStmt.png) - -**TraceableStmt:** - -![TraceableStmt](/media/sqlgram/TraceableStmt.png) - -## 示例 - -```sql -mysql> trace format='row' select * from mysql.user; -+---------------------------+-----------------+------------+ -| operation | startTS | duration | -+---------------------------+-----------------+------------+ -| session.getTxnFuture | 10:33:34.647148 | 3.847µs | -| ├─session.Execute | 10:33:34.647146 | 536.233µs | -| ├─session.ParseSQL | 10:33:34.647182 | 19.868µs | -| ├─executor.Compile | 10:33:34.647219 | 295.688µs | -| ├─session.runStmt | 10:33:34.647533 | 116.229µs | -| ├─session.CommitTxn | 10:33:34.647631 | 5.44µs | -| ├─recordSet.Next | 10:33:34.647707 | 833.103µs | -| ├─tableReader.Next | 10:33:34.647709 | 806.783µs | -| ├─recordSet.Next | 10:33:34.648572 | 19.367µs | -| └─tableReader.Next | 10:33:34.648575 | 1.783µs | -+---------------------------+-----------------+------------+ -10 rows in set (0.00 sec) - -mysql> CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> TRACE FORMAT='json' SELECT * FROM t1 WHERE id = 2\G -operation: [ - {"ID":{"Trace":"60d20d005593de87","Span":"44e5b309242ffe2f","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5nZXRUeG5GdXR1cmU="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTQ3ODYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MjA0MDYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":[ - {"ID":{"Trace":"60d20d005593de87","Span":"4dbf8f2ca373b4b0","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5QYXJzZVNRTA=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2NjE1MTQtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MDYxNjgtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6b6d6916df809604","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"ZXhlY3V0b3IuQ29tcGlsZQ=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NTcyODUtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MzE0MjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"3f1bcdd402a72911","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5Db21taXRUeG4="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3OTgyNjItMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MDU1NzYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"58c1f7d66dc5afbc","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5ydW5TdG10"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Msg","Value":"eyJzcWwiOiJTRUxFQ1QgKiBGUk9NIHQxIFdIRVJFIGlkID0gMiJ9"}, - {"Key":"Time","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3ODA1NjgtMDY6MDA="}, - {"Key":"_schema:log","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MTk5MzMtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NzcyNDItMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6bd8cc440fb31ed7","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5FeGVjdXRl"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTEwODktMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NTU0My0wNjowMA=="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"61d0b809f6cc018b","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NzQ1NTYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIyOTg4NjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"2bd2c3d47ccb1133","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjY0ODgtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjkwMDMtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null} - ] - } -] -1 row in set (0.00 sec) -``` - -可将 JSON 格式的跟踪文件粘贴到跟踪查看器中。查看器可通过 TiDB 状态端口访问： - -![TiDB Trace Viewer-1](/media/trace-paste.png) - -![TiDB Trace Viewer-2](/media/trace-view.png) - -## MySQL 兼容性 - -`TRACE` 语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [EXPLAIN ANALYZE](/v2.1/reference/sql/statements/explain-analyze.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/truncate.md b/v2.1/reference/sql/statements/truncate.md deleted file mode 100644 index 94ff77d5eb3f..000000000000 --- a/v2.1/reference/sql/statements/truncate.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: TRUNCATE -summary: TiDB 数据库中 TRUNCATE 的使用概况。 -category: reference ---- - -# TRUNCATE - -`TRUNCATE` 语句以非事务方式从表中删除所有数据。可认为 `TRUNCATE` 语句同 `DROP TABLE` + `CREATE TABLE` 组合在语义上相同，定义与 `DROP TABLE` 语句相同。 - -`TRUNCATE TABLE tableName` 和 `TRUNCATE tableName` 均为有效语法。 - -## 语法图 - -**TruncateTableStmt:** - -![TruncateTableStmt](/media/sqlgram/TruncateTableStmt.png) - -**OptTable:** - -![OptTable](/media/sqlgram/OptTable.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) - -mysql> TRUNCATE t1; -Query OK, 0 rows affected (0.11 sec) - -mysql> SELECT * FROM t1; -Empty set (0.00 sec) - -mysql> INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 - -mysql> TRUNCATE TABLE t1; -Query OK, 0 rows affected (0.11 sec) -``` - -## MySQL 兼容性 - -`TRUNCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [DROP TABLE](/v2.1/reference/sql/statements/drop-table.md) -* [DELETE](/v2.1/reference/sql/statements/delete.md) -* [CREATE TABLE](/v2.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v2.1/reference/sql/statements/show-create-table.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/update.md b/v2.1/reference/sql/statements/update.md deleted file mode 100644 index 20a34caef2d2..000000000000 --- a/v2.1/reference/sql/statements/update.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: UPDATE -summary: TiDB 数据库中 UPDATE 的使用概况。 -category: reference ---- - -# UPDATE - -`UPDATE` 语句用于修改指定表中的数据。 - -## 语法图 - -**UpdateStmt:** - -![UpdateStmt](/media/sqlgram/UpdateStmt.png) - -**TableRef:** - -![TableRef](/media/sqlgram/TableRef.png) - -**TableRefs:** - -![TableRefs](/media/sqlgram/TableRefs.png) - -**AssignmentList:** - -![AssignmentList](/media/sqlgram/AssignmentList.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -Query OK, 0 rows affected (0.11 sec) - -mysql> INSERT INTO t1 (c1) VALUES (1), (2), (3); -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) - -mysql> UPDATE t1 SET c1=5 WHERE c1=3; -Query OK, 1 row affected (0.01 sec) -Rows matched: 1 Changed: 1 Warnings: 0 - -mysql> SELECT * FROM t1; -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`UPDATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v2.1/reference/sql/statements/insert.md) -* [SELECT](/v2.1/reference/sql/statements/select.md) -* [DELETE](/v2.1/reference/sql/statements/delete.md) -* [REPLACE](/v2.1/reference/sql/statements/replace.md) \ No newline at end of file diff --git a/v2.1/reference/sql/statements/use.md b/v2.1/reference/sql/statements/use.md deleted file mode 100644 index 0efabddfedd9..000000000000 --- a/v2.1/reference/sql/statements/use.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: USE -summary: TiDB 数据库中 USE 的使用概况。 -category: reference ---- - -# USE - -`USE` 语句可为用户会话选择当前数据库。 - -## 语法图 - -**UseStmt:** - -![UseStmt](/media/sqlgram/UseStmt.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -```sql -mysql> USE mysql; -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -mysql> SHOW TABLES; -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) - -mysql> CREATE DATABASE newtest; -Query OK, 0 rows affected (0.10 sec) - -mysql> USE newtest; -Database changed -mysql> SHOW TABLES; -Empty set (0.00 sec) - -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.10 sec) - -mysql> SHOW TABLES; -+-------------------+ -| Tables_in_newtest | -+-------------------+ -| t1 | -+-------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`USE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v2.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v2.1/reference/sql/statements/create-database.md) -* [SHOW TABLES](/v2.1/reference/sql/statements/show-tables.md) \ No newline at end of file diff --git a/v2.1/reference/supported-clients.md b/v2.1/reference/supported-clients.md deleted file mode 100644 index f749c8ca066a..000000000000 --- a/v2.1/reference/supported-clients.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: 连接器和 API -category: reference ---- - -# 连接器和 API - -数据库连接器为客户端提供了连接数据库服务端的方式，APIs 提供了使用 MySQL 协议和资源的底层接口。无论是连接器还是 API，都可以用来在不同的语言和环境内连接服务器并执行 sql 语句，包括 odbc、java(jdbc)、Perl、Python、PHP、Ruby 和 C。 - -TiDB 兼容 MySQL(5.6、5.7) 的所有连接器和 API，包括： - -+ [MySQL Connector/C++](https://dev.mysql.com/doc/refman/5.7/en/connector-cpp-info.html) -+ [MySQL Connector/J](https://dev.mysql.com/doc/refman/5.7/en/connector-j-info.html) -+ [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html) -+ [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html) -+ [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html) -+ [MySQL C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html) -+ [MySQL PHP API](https://dev.mysql.com/doc/refman/5.7/en/apis-php-info.html) -+ [MySQL Perl API](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html) -+ [MySQL Python API](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html) -+ [MySQL Ruby APIs](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby.html) -+ [MySQL Tcl API](https://dev.mysql.com/doc/refman/5.7/en/apis-tcl.html) -+ [MySQL Eiffel Wrapper](https://dev.mysql.com/doc/refman/5.7/en/apis-eiffel.html) -+ [Mysql Go API](https://github.com/go-sql-driver/mysql) - -## 使用 MySQL 连接器连接 TiDB - -Oracle 官方提供了以下 API，TiDB 可以兼容所有这些 API。 - -+ [MySQL Connector/C++](https://dev.mysql.com/doc/refman/5.7/en/connector-cpp-info.html)：C++ 语言的客户端库 -+ [MySQL Connector/J](https://dev.mysql.com/doc/refman/5.7/en/connector-j-info.html)：Java 语言的客户端库，基于标准 JDBC 接口 -+ [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html)：.Net 语言的客户端库，[MySQL for Visual Studio](https://dev.mysql.com/doc/visual-studio/en/)使用这个库，支持 Microsoft Visual Studio 2012，2013，2015和2017版本 -+ [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html)：标准的 ODBC 接口，支持 Windows，Unix 和 OS X -+ [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html)：Python 语言的客户端包，和 [Python DB API version 2.0](http://www.python.org/dev/peps/pep-0249/) 一致 - -## 使用 MySQL C API 连接 TiDB - -如果使用 C 语言程序直接连接 TiDB，可以直接链接 libmysqlclient 库，使用 MySQL 的 [C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html)，这是最主要的一种 C 语言连接方式，被各种客户端和 API 广泛使用，包括 Connector/C。 - -## 使用 MySQL 第三方 API 连接 TiDB - -第三方 API 非 Oracle 官方提供，下表列出了常用的第三方 API： - -| Environment | API | Type | Notes | -| -------------- | ---------------------------------------- | -------------------------------- | ---------------------------------------- | -| Ada | GNU Ada MySQL Bindings | `libmysqlclient` | See [MySQL Bindings for GNU Ada](http://gnade.sourceforge.net/) | -| C | C API | `libmysqlclient` | See [Section 27.8, “MySQL C API”](https://dev.mysql.com/doc/refman/5.7/en/c-api.html). | -| C++ | Connector/C++ | `libmysqlclient` | See [MySQL Connector/C++ Developer Guide](https://dev.mysql.com/doc/connector-cpp/en/). | -| | MySQL++ | `libmysqlclient` | See [MySQL++ Web site](http://tangentsoft.net/mysql++/doc/). | -| | MySQL wrapped | `libmysqlclient` | See [MySQL wrapped](http://www.alhem.net/project/mysql/). | -| Go | go-sql-driver | Native Driver | See [Mysql Go API](https://github.com/go-sql-driver/mysql) | -| Cocoa | MySQL-Cocoa | `libmysqlclient` | Compatible with the Objective-C Cocoa environment. See | -| D | MySQL for D | `libmysqlclient` | See [MySQL for D](https://github.com/mysql-d/mysql-native). | -| Eiffel | Eiffel MySQL | `libmysqlclient` | See [Section 27.14, “MySQL Eiffel Wrapper”](https://dev.mysql.com/doc/refman/5.7/en/apis-eiffel.html). | -| Erlang | `erlang-mysql-driver` | `libmysqlclient` | See [`erlang-mysql-driver`.](http://code.google.com/p/erlang-mysql-driver/) | -| Haskell | Haskell MySQL Bindings | Native Driver | See [Brian O'Sullivan's pure Haskell MySQL bindings](http://www.serpentine.com/blog/software/mysql/). | -| | `hsql-mysql` | `libmysqlclient` | See [MySQL driver for Haskell](http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hsql-mysql-1.7). | -| Java/JDBC | Connector/J | Native Driver | See [MySQL Connector/J 5.1 Developer Guide](https://dev.mysql.com/doc/connector-j/5.1/en/). | -| Lua | LuaSQL | `libmysqlclient` | See [LuaSQL](http://keplerproject.github.io/luasql/manual.html). | -| .NET/Mono | Connector/Net | Native Driver | See [MySQL Connector/Net Developer Guide](https://dev.mysql.com/doc/connector-net/en/). | -| Objective Caml | OBjective Caml MySQL Bindings | `libmysqlclient` | See [MySQL Bindings for Objective Caml](http://raevnos.pennmush.org/code/ocaml-mysql/). | -| Octave | Database bindings for GNU Octave | `libmysqlclient` | See [Database bindings for GNU Octave](http://octave.sourceforge.net/database/index.html). | -| ODBC | Connector/ODBC | `libmysqlclient` | See [MySQL Connector/ODBC Developer Guide](https://dev.mysql.com/doc/connector-odbc/en/). | -| Perl | `DBI`/`DBD::mysql` | `libmysqlclient` | See [Section 27.10, “MySQL Perl API”](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html). | -| | `Net::MySQL` | Native Driver | See [`Net::MySQL`](http://search.cpan.org/dist/Net-MySQL/MySQL.pm) at CPAN | -| PHP | `mysql`, `ext/mysql`interface (deprecated) | `libmysqlclient` | See [Original MySQL API](https://dev.mysql.com/doc/apis-php/en/apis-php-mysql.html). | -| | `mysqli`, `ext/mysqli`interface | `libmysqlclient` | See [MySQL Improved Extension](https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.html). | -| | `PDO_MYSQL` | `libmysqlclient` | See [MySQL Functions (PDO_MYSQL)](https://dev.mysql.com/doc/apis-php/en/apis-php-pdo-mysql.html). | -| | PDO mysqlnd | Native Driver | | -| Python | Connector/Python | Native Driver | See [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/). | -| Python | Connector/Python C Extension | `libmysqlclient` | See [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/). | -| | MySQLdb | `libmysqlclient` | See [Section 27.11, “MySQL Python API”](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html). | -| Ruby | MySQL/Ruby | `libmysqlclient` | Uses `libmysqlclient`. See [Section 27.12.1, “The MySQL/Ruby API”](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby-mysqlruby.html). | -| | Ruby/MySQL | Native Driver | See [Section 27.12.2, “The Ruby/MySQL API”](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby-rubymysql.html). | -| Scheme | `Myscsh` | `libmysqlclient` | See [`Myscsh`](https://github.com/aehrisch/myscsh). | -| SPL | `sql_mysql` | `libmysqlclient` | See [`sql_mysql` for SPL](http://www.clifford.at/spl/spldoc/sql_mysql.html). | -| Tcl | MySQLtcl | `libmysqlclient` | See [Section 27.13, “MySQL Tcl API”](https://dev.mysql.com/doc/refman/5.7/en/apis-tcl.html). | - -## TiDB 支持的连接器版本 - -| Connector | Connector version | -| ---------------- | ---------------------------- | -| Connector/C | 6.1.0 GA | -| Connector/C++ | 1.0.5 GA | -| Connector/J | 5.1.8 | -| Connector/Net | 6.9.9 GA | -| Connector/Net | 6.8.8 GA | -| Connector/ODBC | 5.1 | -| Connector/ODBC | 3.51 (Unicode not supported) | -| Connector/Python | 2.0 | -| Connector/Python | 1.2 | diff --git a/v2.1/reference/system-databases/information-schema.md b/v2.1/reference/system-databases/information-schema.md deleted file mode 100644 index 51c49388b8c5..000000000000 --- a/v2.1/reference/system-databases/information-schema.md +++ /dev/null @@ -1,461 +0,0 @@ ---- -title: Information Schema -category: reference ---- - -# Information Schema - -为了和 MySQL 保持兼容，TiDB 支持很多 `INFORMATION_SCHEMA` 表，其中有不少表都支持相应的 `SHOW` 命令。查询 `INFORMATION_SCHEMA` 表也为表的连接操作提供了可能。 - -## CHARACTER\_SETS Table - - `CHARACTER_SETS` 表提供[字符集](/v2.1/reference/sql/character-set.md)相关的信息。TiDB 目前仅支持部分字符集。 - -```sql -mysql> SELECT * FROM character_sets; -+--------------------+----------------------+---------------+--------+ -| CHARACTER_SET_NAME | DEFAULT_COLLATE_NAME | DESCRIPTION | MAXLEN | -+--------------------+----------------------+---------------+--------+ -| utf8 | utf8_bin | UTF-8 Unicode | 3 | -| utf8mb4 | utf8mb4_bin | UTF-8 Unicode | 4 | -| ascii | ascii_bin | US ASCII | 1 | -| latin1 | latin1_bin | Latin1 | 1 | -| binary | binary | binary | 1 | -+--------------------+----------------------+---------------+--------+ -5 rows in set (0.00 sec) -``` - -## COLLATIONS Table - - `COLLATIONS` 表提供了 `CHARACTER_SETS` 表中字符集对应的排序规则列表。TiDB 当前仅支持二进制排序规则，包含该表仅为兼容 MySQL。 - -```sql -mysql> SELECT * FROM collations WHERE character_set_name='utf8mb4'; -+------------------------+--------------------+------+------------+-------------+---------+ -| COLLATION_NAME | CHARACTER_SET_NAME | ID | IS_DEFAULT | IS_COMPILED | SORTLEN | -+------------------------+--------------------+------+------------+-------------+---------+ -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+------------------------+--------------------+------+------------+-------------+---------+ -26 rows in set (0.00 sec) -``` - -## COLLATION\_CHARACTER\_SET\_APPLICABILITY Table - -`COLLATION_CHARACTER_SET_APPLICABILITY` 表将排序规则映射至适用的字符集名称。和 `COLLATIONS` 表一样，包含此表也是为了兼容 MySQL。 - -```sql -mysql> SELECT * FROM collation_character_set_applicability WHERE character_set_name='utf8mb4'; -+------------------------+--------------------+ -| COLLATION_NAME | CHARACTER_SET_NAME | -+------------------------+--------------------+ -| utf8mb4_general_ci | utf8mb4 | -| utf8mb4_bin | utf8mb4 | -| utf8mb4_unicode_ci | utf8mb4 | -| utf8mb4_icelandic_ci | utf8mb4 | -| utf8mb4_latvian_ci | utf8mb4 | -| utf8mb4_romanian_ci | utf8mb4 | -| utf8mb4_slovenian_ci | utf8mb4 | -| utf8mb4_polish_ci | utf8mb4 | -| utf8mb4_estonian_ci | utf8mb4 | -| utf8mb4_spanish_ci | utf8mb4 | -| utf8mb4_swedish_ci | utf8mb4 | -| utf8mb4_turkish_ci | utf8mb4 | -| utf8mb4_czech_ci | utf8mb4 | -| utf8mb4_danish_ci | utf8mb4 | -| utf8mb4_lithuanian_ci | utf8mb4 | -| utf8mb4_slovak_ci | utf8mb4 | -| utf8mb4_spanish2_ci | utf8mb4 | -| utf8mb4_roman_ci | utf8mb4 | -| utf8mb4_persian_ci | utf8mb4 | -| utf8mb4_esperanto_ci | utf8mb4 | -| utf8mb4_hungarian_ci | utf8mb4 | -| utf8mb4_sinhala_ci | utf8mb4 | -| utf8mb4_german2_ci | utf8mb4 | -| utf8mb4_croatian_ci | utf8mb4 | -| utf8mb4_unicode_520_ci | utf8mb4 | -| utf8mb4_vietnamese_ci | utf8mb4 | -+------------------------+--------------------+ -26 rows in set (0.00 sec) -``` - -## COLUMNS Table - -COLUMNS 表提供了表的所有列的信息。 - -```sql -mysql> CREATE TABLE test.t1 (a int); -1 row in set (0.01 sec) -mysql> SELECT * FROM information_schema.columns WHERE table_schema='test' AND TABLE_NAME='t1'\G -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: t1 - COLUMN_NAME: a - ORDINAL_POSITION: 1 - COLUMN_DEFAULT: NULL - IS_NULLABLE: YES - DATA_TYPE: int -CHARACTER_MAXIMUM_LENGTH: NULL - CHARACTER_OCTET_LENGTH: NULL - NUMERIC_PRECISION: 11 - NUMERIC_SCALE: 0 - DATETIME_PRECISION: NULL - CHARACTER_SET_NAME: NULL - COLLATION_NAME: NULL - COLUMN_TYPE: int(11) - COLUMN_KEY: - EXTRA: - PRIVILEGES: select,insert,update,references - COLUMN_COMMENT: - GENERATION_EXPRESSION: -1 row in set (0.01 sec) -``` - -对应的 `SHOW` 语句如下： - -```sql -mysql> SHOW COLUMNS FROM t1 FROM test; -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -## ENGINES Table - -`ENGINES` 表提供了关于存储引擎的信息。从和 MySQL 兼容性上考虑，TiDB 会一直将 InnoDB 描述为唯一支持的引擎。 - -```sql -mysql> SELECT * FROM engines\G -*************************** 1. row *************************** - ENGINE: InnoDB - SUPPORT: DEFAULT - COMMENT: Supports transactions, row-level locking, and foreign keys -TRANSACTIONS: YES - XA: YES - SAVEPOINTS: YES -1 row in set (0.00 sec) -``` - -## KEY\_COLUMN\_USAGE Table - -`KEY_COLUMN_USAGE` 表描述了列的键约束，比如主键约束。 - -```sql -mysql> SELECT * FROM key_column_usage WHERE table_schema='mysql' and table_name='user'\G -*************************** 1. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: Host - ORDINAL_POSITION: 1 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -*************************** 2. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: User - ORDINAL_POSITION: 2 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -2 rows in set (0.00 sec) -``` - -## SCHEMATA Table - -SCHEMATA 表提供了关于数据库的信息。表中的数据与 `SHOW DATABASES` 语句的执行结果等价。 - -```sql -mysql> SELECT * FROM schemata; -+--------------+--------------------+----------------------------+------------------------+----------+ -| CATALOG_NAME | SCHEMA_NAME | DEFAULT_CHARACTER_SET_NAME | DEFAULT_COLLATION_NAME | SQL_PATH | -+--------------+--------------------+----------------------------+------------------------+----------+ -| def | INFORMATION_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | mynewdb | utf8mb4 | utf8mb4_bin | NULL | -| def | mysql | utf8mb4 | utf8mb4_bin | NULL | -| def | PERFORMANCE_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | test | utf8mb4 | utf8mb4_bin | NULL | -+--------------+--------------------+----------------------------+------------------------+----------+ -5 rows in set (0.00 sec) -``` - -## SESSION\_VARIABLES Table - -`SESSION\_VARIABLES` 表提供了关于 session 变量的信息。表中的数据跟 `SHOW SESSION VARIABLES` 语句执行结果类似。 - -```sql -mysql> SELECT * FROM session_variables LIMIT 10; -+----------------------------------+----------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+----------------------------------+----------------------+ -| max_write_lock_count | 18446744073709551615 | -| server_id_bits | 32 | -| net_read_timeout | 30 | -| innodb_online_alter_log_max_size | 134217728 | -| innodb_optimize_fulltext_only | OFF | -| max_join_size | 18446744073709551615 | -| innodb_read_io_threads | 4 | -| session_track_gtids | OFF | -| have_ssl | DISABLED | -| max_binlog_cache_size | 18446744073709547520 | -+----------------------------------+----------------------+ -10 rows in set (0.00 sec) -``` - -## SLOW_QUERY 表 - -`SLOW_QUERY` 表中提供了慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，列名和慢日志中的字段名是一一对应。关于如何使用该表调查和改善慢查询请参考[慢查询日志文档](/v2.1/how-to/maintain/identify-slow-queries.md)。 - -```sql -mysql> desc information_schema.slow_query; -+---------------+---------------------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+------+---------+-------+ -| Time | timestamp unsigned | YES | | NULL | | -| Txn_start_ts | bigint(20) unsigned | YES | | NULL | | -| User | varchar(64) | YES | | NULL | | -| Host | varchar(64) | YES | | NULL | | -| Conn_ID | bigint(20) unsigned | YES | | NULL | | -| Query_time | double unsigned | YES | | NULL | | -| Process_time | double unsigned | YES | | NULL | | -| Wait_time | double unsigned | YES | | NULL | | -| Backoff_time | double unsigned | YES | | NULL | | -| Request_count | bigint(20) unsigned | YES | | NULL | | -| Total_keys | bigint(20) unsigned | YES | | NULL | | -| Process_keys | bigint(20) unsigned | YES | | NULL | | -| DB | varchar(64) | YES | | NULL | | -| Index_ids | varchar(100) | YES | | NULL | | -| Is_internal | tinyint(1) unsigned | YES | | NULL | | -| Digest | varchar(64) | YES | | NULL | | -| Stats | varchar(512) | YES | | NULL | | -| Cop_proc_avg | double unsigned | YES | | NULL | | -| Cop_proc_p90 | double unsigned | YES | | NULL | | -| Cop_proc_max | double unsigned | YES | | NULL | | -| Cop_proc_addr | varchar(64) | YES | | NULL | | -| Cop_wait_avg | double unsigned | YES | | NULL | | -| Cop_wait_p90 | double unsigned | YES | | NULL | | -| Cop_wait_max | double unsigned | YES | | NULL | | -| Cop_wait_addr | varchar(64) | YES | | NULL | | -| Mem_max | bigint(20) unsigned | YES | | NULL | | -| Succ | tinyint(1) unsigned | YES | | NULL | | -| Query | longblob unsigned | YES | | NULL | | -+---------------+---------------------+------+------+---------+-------+ -``` - -## STATISTICS Table - - `STATISTICS` 表提供了关于表索引的信息。 - -```sql -mysql> desc statistics; -+---------------|---------------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------|---------------------|------|------|---------|-------+ -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| TABLE_SCHEMA | varchar(64) | YES | | NULL | | -| TABLE_NAME | varchar(64) | YES | | NULL | | -| NON_UNIQUE | varchar(1) | YES | | NULL | | -| INDEX_SCHEMA | varchar(64) | YES | | NULL | | -| INDEX_NAME | varchar(64) | YES | | NULL | | -| SEQ_IN_INDEX | bigint(2) UNSIGNED | YES | | NULL | | -| COLUMN_NAME | varchar(21) | YES | | NULL | | -| COLLATION | varchar(1) | YES | | NULL | | -| CARDINALITY | bigint(21) UNSIGNED | YES | | NULL | | -| SUB_PART | bigint(3) UNSIGNED | YES | | NULL | | -| PACKED | varchar(10) | YES | | NULL | | -| NULLABLE | varchar(3) | YES | | NULL | | -| INDEX_TYPE | varchar(16) | YES | | NULL | | -| COMMENT | varchar(16) | YES | | NULL | | -| INDEX_COMMENT | varchar(1024) | YES | | NULL | | -+---------------|---------------------|------|------|---------|-------+ -``` - -下列语句是等价的： - -```sql -SELECT * FROM INFORMATION_SCHEMA.STATISTICS - WHERE table_name = 'tbl_name' - AND table_schema = 'db_name' - -SHOW INDEX - FROM tbl_name - FROM db_name -``` - -## TABLES Table - -`TABLES` 表提供了数据库里面关于表的信息。 - -```sql -mysql> SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'\G -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - TABLE_TYPE: BASE TABLE - ENGINE: InnoDB - VERSION: 10 - ROW_FORMAT: Compact - TABLE_ROWS: 0 - AVG_ROW_LENGTH: 0 - DATA_LENGTH: 0 -MAX_DATA_LENGTH: 0 - INDEX_LENGTH: 0 - DATA_FREE: 0 - AUTO_INCREMENT: 0 - CREATE_TIME: 2019-03-29 09:17:27 - UPDATE_TIME: NULL - CHECK_TIME: NULL -TABLE_COLLATION: utf8mb4_bin - CHECKSUM: NULL - CREATE_OPTIONS: - TABLE_COMMENT: - TIDB_TABLE_ID: 5 -1 row in set (0.00 sec) -``` - -以下操作是等价的： - -```sql -SELECT table_name FROM INFORMATION_SCHEMA.TABLES - WHERE table_schema = 'db_name' - [AND table_name LIKE 'wild'] - -SHOW TABLES - FROM db_name - [LIKE 'wild'] -``` - -## TABLE\_CONSTRAINTS Table - -`TABLE\_CONSTRAINTS` 表记录了表的约束信息。 - -```sql -mysql> SELECT * FROM table_constraints WHERE constraint_type='UNIQUE'\G -*************************** 1. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: name - TABLE_SCHEMA: mysql - TABLE_NAME: help_topic - CONSTRAINT_TYPE: UNIQUE -*************************** 2. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_meta - CONSTRAINT_TYPE: UNIQUE -*************************** 3. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_histograms - CONSTRAINT_TYPE: UNIQUE -*************************** 4. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_buckets - CONSTRAINT_TYPE: UNIQUE -*************************** 5. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range - CONSTRAINT_TYPE: UNIQUE -*************************** 6. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_done_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range_done - CONSTRAINT_TYPE: UNIQUE -6 rows in set (0.00 sec) -``` - -其中： - -* `CONSTRAINT_TYPE` 的取值可以是 `UNIQUE`，`PRIMARY KEY`，或者 `FOREIGN KEY`。 -* `UNIQUE` 和 `PRIMARY KEY` 信息与 `SHOW INDEX` 语句的执行结果类似。 - -## USER\_PRIVILEGES Table - -USER\_PRIVILEGES 表提供了关于全局权限的信息。该表的数据根据 `mysql.user` 系统表生成。 - -```sql -mysql> desc USER_PRIVILEGES; -+----------------|--------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------|--------------|------|------|---------|-------+ -| GRANTEE | varchar(81) | YES | | NULL | | -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| PRIVILEGE_TYPE | varchar(64) | YES | | NULL | | -| IS_GRANTABLE | varchar(3) | YES | | NULL | | -+----------------|--------------|------|------|---------|-------+ -4 rows in set (0.00 sec) -``` - -## 不支持的 Information Schema 表 - -TiDB 包含以下 `INFORMATION_SCHEMA` 表，但仅会返回空行： - -* `COLUMN_PRIVILEGES` -* `EVENTS` -* `FILES` -* `GLOBAL_STATUS` -* `GLOBAL_VARIABLES` -* `OPTIMIZER_TRACE` -* `PARAMETERS` -* `PARTITIONS` -* `PLUGINS` -* `PROFILING` -* `REFERENTIAL_CONSTRAINTS` -* `ROUTINES` -* `SCHEMA_PRIVILEGES` -* `SESSION_STATUS` -* `TABLESPACES` -* `TABLE_PRIVILEGES` -* `TRIGGERS` -* `VIEWS` diff --git a/v2.1/reference/system-databases/mysql.md b/v2.1/reference/system-databases/mysql.md deleted file mode 100644 index 57e26eb07952..000000000000 --- a/v2.1/reference/system-databases/mysql.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: TiDB 系统表 -category: reference ---- - -# TiDB 系统表 - -本文档主要介绍 TiDB 支持的系统表。 - -## 权限系统表 - -这些系统表里面包含了用户账户以及相应的授权信息： - -* `user` 用户账户，全局权限，以及其它一些非权限的列 -* `db` 数据库级别的权限 -* `tables_priv` 表级的权限 -* `columns_priv` 列级的权限 - -## 服务端帮助信息系统表 - -* `help_topic` 目前为空 - -## 统计信息相关系统表 - -* `stats_buckets` 统计信息的桶 -* `stats_histograms` 统计信息的直方图 -* `stats_meta` 表的元信息，比如总行数和修改数 - -## GC Worker 相关系统表 - -* `gc_delete_range` - -## 其它系统表 - -* `GLOBAL_VARIABLES` 全局系统变量表 -* `tidb` 用于 TiDB 在 bootstrap 的时候记录相关版本信息 diff --git a/v2.1/reference/tidb-binlog/binlog-slave-client.md b/v2.1/reference/tidb-binlog/binlog-slave-client.md deleted file mode 100644 index 0008abf0f4d5..000000000000 --- a/v2.1/reference/tidb-binlog/binlog-slave-client.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Binlog Slave Client 用户文档 -category: reference -aliases: ['/docs-cn/v2.1/reference/tools/tidb-binlog/binlog-slave-client/'] ---- - -# Binlog Slave Client 用户文档 - -目前 Drainer 提供了多种输出方式，包括 MySQL、TiDB、file 等。但是用户往往有一些自定义的需求，比如输出到 Elasticsearch、Hive 等，这些需求 Drainer 现在还没有实现，因此 Drainer 增加了输出到 Kafka 的功能，将 binlog 数据解析后按一定的格式再输出到 Kafka 中，用户编写代码从 Kafka 中读出数据再进行处理。 - -## 配置 Kafka Drainer - -修改 Drainer 的配置文件，设置输出为 Kafka，相关配置如下： - -``` -[syncer] -db-type = "kafka" - -[syncer.to] -# Kafka 地址 -kafka-addrs = "127.0.0.1:9092" -# Kafka 版本号 -kafka-version = "0.8.2.0" -``` - -## 自定义开发 - -### 数据格式 - -首先需要了解 Drainer 写入到 Kafka 中的数据格式： - -``` -// Column 保存列的数据，针对数据的类型，保存在对应的变量中 -message Column { - // 数据是否为 null - optional bool is_null = 1 [ default = false ]; - // 保存 int 类型的数据 - optional int64 int64_value = 2; - // 保存 uint、enum, set 类型的数据 - optional uint64 uint64_value = 3; - // 保存 float、double 类型的数据 - optional double double_value = 4; - // 保存 bit、blob、binary、json 类型的数据 - optional bytes bytes_value = 5; - // 保存 date、time、decimal、text、char 类型的数据 - optional string string_value = 6; -} - -// ColumnInfo 保存列的信息，包括列名、类型、是否为主键 -message ColumnInfo { - optional string name = 1 [ (gogoproto.nullable) = false ]; - // MySQL 中小写的列字段类型 - // https://dev.mysql.com/doc/refman/8.0/en/data-types.html - // numeric 类型：int bigint smallint tinyint float double decimal bit - // string 类型：text longtext mediumtext char tinytext varchar - // blob longblob mediumblob binary tinyblob varbinary - // enum set - // json 类型：json - optional string mysql_type = 2 [ (gogoproto.nullable) = false ]; - optional bool is_primary_key = 3 [ (gogoproto.nullable) = false ]; -} - -// Row 保存一行的具体数据 -message Row { repeated Column columns = 1; } - -// MutationType 表示 DML 的类型 -enum MutationType { - Insert = 0; - Update = 1; - Delete = 2; -} - -// Table 包含一个表的数据变更 -message Table { - optional string schema_name = 1; - optional string table_name = 2; - repeated ColumnInfo column_info = 3; - repeated TableMutation mutations = 4; -} - -// TableMutation 保存一行数据的变更 -message TableMutation { - required MutationType type = 1; - // 修改后的数据 - required Row row = 2; - // 修改前的数据，只对 Update MutationType 有效 - optional Row change_row = 3; -} - -// DMLData 保存一个事务所有的 DML 造成的数据变更 -message DMLData { - // `tables` 包含事务中所有表的数据变更 - repeated Table tables = 1; -} - -// DDLData 保存 DDL 的信息 -message DDLData { - // 当前使用的数据库 - optional string schema_name = 1; - // 相关表 - optional string table_name = 2; - // `ddl_query` 是原始的 DDL 语句 query - optional bytes ddl_query = 3; -} - -// BinlogType 为 Binlog 的类型，分为 DML 和 DDL -enum BinlogType { - DML = 0; // Has `dml_data` - DDL = 1; // Has `ddl_query` -} - -// Binlog 保存一个事务所有的变更，Kafka 中保存的数据为该结构数据序列化后的结果 -message Binlog { - optional BinlogType type = 1 [ (gogoproto.nullable) = false ]; - optional int64 commit_ts = 2 [ (gogoproto.nullable) = false ]; - optional DMLData dml_data = 3; - optional DDLData ddl_data = 4; -} -``` - -查看数据格式的具体定义，参见 [binlog.proto](https://github.com/pingcap/tidb-tools/blob/master/tidb-binlog/slave_binlog_proto/proto/binlog.proto)。 - -### Driver - -TiDB-Tools 项目提供了用于读取 Kafka 中 binlog 数据的 Driver，具有如下功能： - -* 读取 Kafka 的数据 -* 根据 commit ts 查找 binlog 在 kafka 中的储存位置 - -使用该 Driver 时，用户需要配置如下信息： - -* KafkaAddr：Kafka 集群的地址 -* CommitTS：从哪个 commit ts 开始读取 binlog -* Offset：从 Kafka 哪个 offset 开始读取，如果设置了 CommitTS 就不用配置该参数 -* ClusterID：TiDB 集群的 cluster ID -* Topic: Kafka Topic 名称，如果 Topic 名称为空，将会使用 drainer _obinlog 中的默认名称 - -用户以包的形式引用 Driver 的代码即可使用，可以参考 Driver 中提供的示例代码来学习如何使用 Driver 以及 binlog 数据的解析，目前提供了两个例子： - -* 使用该 Driver 将数据同步到 MySQL，该示例包含将 binlog 转化为 SQL 的具体方法 -* 使用该 Driver 将数据打印出来 - -Driver 项目地址：[Binlog Slave Driver](https://github.com/pingcap/tidb-tools/tree/master/tidb-binlog/driver)。 - -> **注意：** -> -> - 示例代码仅仅用于示范如何使用 Driver，如果需要用于生产环境需要优化代码。 -> - 目前仅提供了 golang 版本的 Driver 以及示例代码。如果需要使用其他语言，用户需要根据 binlog 的 proto 文件生成相应语言的代码文件，并自行开发程序读取 Kafka 中的 binlog 数据、解析数据、输出到下游。也欢迎用户优化 example 代码，以及提交其他语言的示例代码到 [TiDB-Tools](https://github.com/pingcap/tidb-tools)。 diff --git a/v2.1/reference/tidb-binlog/deploy.md b/v2.1/reference/tidb-binlog/deploy.md deleted file mode 100644 index c51b3f2bc07e..000000000000 --- a/v2.1/reference/tidb-binlog/deploy.md +++ /dev/null @@ -1,568 +0,0 @@ ---- -title: TiDB Binlog 集群部署 -category: reference -aliases: ['/docs-cn/v2.1/how-to/deploy/tidb-binlog/','/docs-cn/v2.1/reference/tools/tidb-binlog/deploy/'] ---- - -# TiDB Binlog 集群部署 - -## 服务器要求 - -Pump 和 Drainer 均可部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台上。在开发、测试和生产环境下，对服务器硬件配置的要求和建议如下： - -| 服务 | 部署数量 | CPU | 磁盘 | 内存 | -| :-------- | :-------- | :--------| :--------------- | :------ | -| Pump | 3 | 8核+ | SSD, 200 GB+ | 16G | -| Drainer | 1 | 8核+ | SAS, 100 GB+ （如果输出 binlog 为本地文件，磁盘大小视保留数据天数而定） | 16G | - -## 使用 TiDB Ansible 部署 TiDB Binlog - -### 第 1 步：下载 TiDB Ansible - -1. 以 TiDB 用户登录中控机并进入 `/home/tidb` 目录。以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - - | TiDB Ansible 分支 | TiDB 版本 | 备注 | - | ---------------- | --------- | --- | - | release-2.1 | 2.1 版本 | 最新 2.1 稳定版本，可用于生产环境。 | - -2. 使用以下命令从 GitHub [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应分支，默认的文件夹名称为 `tidb-ansible`。 - - - 下载 2.1 版本： - - ```bash - git clone -b release-2.1 https://github.com/pingcap/tidb-ansible.git - ``` - -### 第 2 步：部署 Pump - -1. 修改 tidb-ansible/inventory.ini 文件 - - 1. 设置 `enable_binlog = True`，表示 TiDB 集群开启 binlog。 - - ```ini - ## binlog trigger - enable_binlog = True - ``` - - 2. 为 `pump_servers` 主机组添加部署机器 IP。 - - ```ini - ## Binlog Part - [pump_servers] - 172.16.10.72 - 172.16.10.73 - 172.16.10.74 - ``` - - 默认 Pump 保留 7 天数据，如需修改可修改 `tidb-ansible/conf/pump.yml` 文件中 `gc` 变量值，并取消注释。 - - ```yaml - global: - # an integer value to control the expiry date of the binlog data, which indicates for how long (in days) the binlog data would be stored - # must be bigger than 0 - # gc: 7 - ``` - - 请确保部署目录有足够空间存储 binlog，详见[调整部署目录](/v2.1/how-to/deploy/orchestrated/ansible.md#调整部署目录)，也可为 Pump 设置单独的部署目录。 - - ```ini - ## Binlog Part - [pump_servers] - pump1 ansible_host=172.16.10.72 deploy_dir=/data1/pump - pump2 ansible_host=172.16.10.73 deploy_dir=/data2/pump - pump3 ansible_host=172.16.10.74 deploy_dir=/data3/pump - ``` - -2. 部署并启动含 Pump 组件的 TiDB 集群 - - 参照上文配置完 `inventory.ini` 文件后，从以下两种方式中选择一种进行部署。 - - **方式一**：在已有的 TiDB 集群上增加 Pump 组件，需按以下步骤逐步进行。 - - 1. 部署 pump_servers 和 node_exporters - - ``` - ansible-playbook deploy.yml --tags=pump -l ${pump1_ip},${pump2_ip},[${alias1_name},${alias2_name}] - ``` - - > **注意：** - > - > 以上命令中，逗号后不要加空格，否则会报错。 - - 2. 启动 pump_servers - - ``` - ansible-playbook start.yml --tags=pump - ``` - - 3. 更新并重启 tidb_servers - - ``` - ansible-playbook rolling_update.yml --tags=tidb - ``` - - 4. 更新监控信息 - - ``` - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - - **方式二**：从零开始部署含 Pump 组件的 TiDB 集群 - - 使用 Ansible 部署 TiDB 集群，方法参考 [使用 TiDB Ansible 部署 TiDB 集群](/v2.1/how-to/deploy/orchestrated/ansible.md)。 - -3. 查看 Pump 服务状态 - - 使用 binlogctl 查看 Pump 服务状态，pd-urls 参数请替换为集群 PD 地址，结果 State 为 online 表示 Pump 启动成功。 - - ```bash - $ cd /home/tidb/tidb-ansible - $ resources/bin/binlogctl -pd-urls=http://172.16.10.72:2379 -cmd pumps - - INFO[0000] pump: {NodeID: ip-172-16-10-72:8250, Addr: 172.16.10.72:8250, State: online, MaxCommitTS: 403051525690884099, UpdateTime: 2018-12-25 14:23:37 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-73:8250, Addr: 172.16.10.73:8250, State: online, MaxCommitTS: 403051525703991299, UpdateTime: 2018-12-25 14:23:36 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-74:8250, Addr: 172.16.10.74:8250, State: online, MaxCommitTS: 403051525717360643, UpdateTime: 2018-12-25 14:23:35 +0800 CST} - ``` - -### 第 3 步：部署 Drainer - -1. 获取 initial_commit_ts 的值 - - Drainer 初次启动时需要获取 initial_commit_ts 这个时间戳信息。 - - - 如果从最近的时间点开始同步，需要使用 binlogctl 工具获取一个最新的时间戳，来作为 initial_commit_ts 的值。获取最新时间戳的方法如下： - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible - resources/bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd generate_meta - ``` - - ``` - INFO[0000] [pd] create pd client with endpoints [http://192.168.199.118:32379] - INFO[0000] [pd] leader switches to: http://192.168.199.118:32379, previous: - INFO[0000] [pd] init cluster id 6569368151110378289 - 2018/06/21 11:24:47 meta.go:117: [info] meta: &{CommitTS:400962745252184065} - ``` - - 该命令会输出 `meta: &{CommitTS:400962745252184065}`，其中 CommitTS 的值即所需的最新的时间戳。 - - - 如果下游为 MySQL 或 TiDB，为了保证数据的完整性，需要进行全量数据的备份与恢复。此时 initial_commit_ts 的值必须是全量备份的时间戳。 - - 如果使用 mydumper 进行全量备份，可以在导出目录中找到 metadata 文件，其中的 `Pos` 字段值即全量备份的时间戳。metadata 文件示例如下： - - ``` - Started dump at: 2019-12-30 13:25:41 - SHOW MASTER STATUS: - Log: tidb-binlog - Pos: 413580274257362947 - GTID: - - Finished dump at: 2019-12-30 13:25:41 - ``` - -2. 修改 `tidb-ansible/inventory.ini` 文件 - - 为 `drainer_servers` 主机组添加部署机器 IP，initial_commit_ts 请设置为获取的 initial_commit_ts，仅用于 Drainer 第一次启动。 - - - 以下游为 MySQL 为例，别名为 `drainer_mysql`。 - - ```ini - [drainer_servers] - drainer_mysql ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - - - 以下游为 file 为例，别名为 `drainer_file`。 - - ```ini - [drainer_servers] - drainer_file ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - -3. 修改配置文件 - - - 以下游为 MySQL 为例 - - ```bash - $ cd /home/tidb/tidb-ansible/conf - $ cp drainer.toml drainer_mysql_drainer.toml - $ vi drainer_mysql_drainer.toml - ``` - - > **注意：** - > - > 配置文件名命名规则为 `别名_drainer.toml`，否则部署时无法找到自定义配置文件。 - - db-type 设置为 "mysql"， 配置下游 MySQL 信息。 - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "mysql" - - # the downstream MySQL protocol database - [syncer.to] - host = "172.16.10.72" - user = "root" - password = "123456" - port = 3306 - ``` - - - 以下游为增量备份文件为例 - - ```bash - $ cd /home/tidb/tidb-ansible/conf - $ cp drainer.toml drainer_file_drainer.toml - $ vi drainer_file_drainer.toml - ``` - - db-type 设置为 "file"。 - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "file" - - # Uncomment this if you want to use "file" as "db-type". - [syncer.to] - # default data directory: "{{ deploy_dir }}/data.drainer" - dir = "data.drainer" - ``` - -4. 部署 Drainer - - ```bash - $ ansible-playbook deploy_drainer.yml - ``` - -5. 启动 Drainer - - ```bash - $ ansible-playbook start_drainer.yml - ``` - -## 使用 Binary 部署 TiDB Binlog - -### 下载官方 Binary - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 - -# 检查文件完整性，返回 ok 则正确 -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，Pump 和 Drainer 已经包含在 TiDB 的下载包中，其他版本需要单独下载 Pump 和 Drainer: - -```bash -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.tar.gz -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.sha256 - -# 检查文件完整性，返回 ok 则正确 -sha256sum -c tidb-binlog-latest-linux-amd64.sha256 -``` - -### 使用样例 - -假设有三个 PD，一个 TiDB，另外有两台机器用于部署 Pump，一台机器用于部署 Drainer。各个节点信息如下： - -``` -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -Pump="192.168.0.11" -Pump="192.168.0.12" -Drainer="192.168.0.13" -``` - -下面以此为例，说明 Pump/Drainer 的使用。 - -1. 使用 binary 部署 Pump - - - Pump 命令行参数说明（以在 “192.168.0.11” 上部署为例） - - ```bash - Usage of Pump: - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.11:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.11:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置; - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里的配置。 - -data-dir string - Pump 数据存储位置路径 - -gc int - Pump 只保留多少天以内的数据 (默认 7) - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -node-id string - Pump 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -fake-binlog-interval int - Pump 节点生成 fake binlog 的频率 (默认 3，单位 秒) - ``` - - - Pump 配置文件（以在 “192.168.0.11” 上部署为例） - - ```toml - # Pump Configuration - - # Pump 绑定的地址 - addr = "192.168.0.11:8250" - - # Pump 对外提供服务的地址 - advertise-addr = "192.168.0.11:8250" - - # Pump 只保留多少天以内的数据 (默认 7) - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 2 - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/drainer.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/drainer-key.pem" - - # [storage] - # 设置为 true（默认值）来保证可靠性，确保 binlog 数据刷新到磁盘 - # sync-log = true - - # 当可用磁盘容量小于该设置值时，Pump 将停止写入数据，v2.1.14 后支持该功能 - # 42 MB -> 42000000, 42 mib -> 44040192 - # default: 10 gib - # stop-write-at-available-space = "10 gib" - - # Pump 内嵌的 LSM DB 设置，除非对该部分很了解，否则一般注解掉 - # [storage.kv] - # block-cache-capacity = 8388608 - # block-restart-interval = 16 - # block-size = 4096 - # compaction-L0-trigger = 8 - # compaction-table-size = 67108864 - # compaction-total-size = 536870912 - # compaction-total-size-multiplier = 8.0 - # write-buffer = 67108864 - # write-L0-pause-trigger = 24 - # write-L0-slowdown-trigger = 17 - ``` - - - 启动示例 - - ```bash - ./bin/pump -config pump.toml - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -2. 使用 binary 部署 Drainer - - - Drainer 命令行参数说明（以在 “192.168.0.13” 上部署为例） - - ```bash - Usage of Drainer - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.13:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -cache-binlog-count int - 缓存中的 binlog 数目限制（默认 8） - 如果上游的单个 binlog 较大导致 Drainer 出现 OOM 时，可尝试调小该值减少内存使用 - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的配置 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql，支持 tidb、kafka、file) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则每个 binlog - 按顺序依次还原成单个事务进行同步（下游服务类型为 MySQL，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts (默认为 0) - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位：秒） - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -safe-mode - 是否开启安全模式使得下游 MySQL/TiDB 可被重复写入 - 即将 insert 语句换为 replace 语句，将 update 语句拆分为 delete + replace 语句 - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - - - Drainer 配置文件（以在 “192.168.0.13” 上部署为例） - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.13:8249") - addr = "192.168.0.13:8249" - - # Drainer 对外提供服务的地址 - advertise-addr = "192.168.0.13:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Drainer 从 Pump 获取 binlog 时对数据进行压缩，值可以为 "gzip"，如果不配置则不进行压缩 - # compressor = "gzip" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/pump.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/pump-key.pem" - - # Syncer Configuration - [syncer] - # 如果设置了该项，会使用该 sql-mode 解析 DDL 语句，此时如果下游是 MySQL 或 TiDB 则 - # 下游的 sql-mode 也会被设置为该值 - # sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" - - # 输出到下游数据库一个事务的 SQL 语句数量 (默认 20) - txn-batch = 20 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (默认 16) - worker-count = 16 - - # 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 MySQL, 该项设置为 False） - disable-dispatch = false - - # safe mode 会使写下游 MySQL/TiDB 可被重复写入 - # 会用 replace 替换 insert 语句，用 delete + replace 替换 update 语句 - safe-mode = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql"，"tidb"，"file"，"kafka" - db-type = "mysql" - - # db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - # 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。 - # 以 '~' 开始声明使用正则表达式 - - # replicate-do-db = ["~^b.*","s1"] - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "log" - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "~^a.*" - - # 忽略同步某些表 - # [[syncer.ignore-table]] - # db-name = "test" - # tbl-name = "log" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.13" - user = "root" - password = "" - port = 3306 - - [syncer.to.checkpoint] - # 当下游是 MySQL 或 TiDB 时可以开启该选项，以改变保存 checkpoint 的数据库 - # schema = "tidb_binlog" - - # db-type 设置为 file 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - - # db-type 设置为 kafka 时，Kafka 相关配置 - # [syncer.to] - # kafka-addrs 和 zookeeper-addrs 只需要一个，两者都有时程序会优先用 zookeeper 中的 kafka 地址 - # zookeeper-addrs = "127.0.0.1:2181" - # kafka-addrs = "127.0.0.1:9092" - # kafka-version = "0.8.2.0" - # kafka-max-messages = 1024 - - # 保存 binlog 数据的 Kafka 集群的 topic 名称，默认值为 _obinlog - # 如果运行多个 Drainer 同步数据到同一个 Kafka 集群，每个 Drainer 的 topic-name 需要设置不同的名称 - # topic-name = "" - ``` - - - 启动示例 - - > **注意：** - > - > 如果下游为 MySQL/TiDB，为了保证数据的完整性，在 Drainer 初次启动前需要获取 `initial-commit-ts` 的值，并进行全量数据的备份与恢复。详细信息参见[部署 Drainer](#第-3-步部署-drainer)。 - - 初次启动时使用参数 `initial-commit-ts`， 命令如下： - - ```bash - ./bin/drainer -config drainer.toml -initial-commit-ts {initial-commit-ts} - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -> **注意：** -> -> - 在运行 TiDB 时，需要保证至少一个 Pump 正常运行。 -> - 通过给 TiDB 增加启动参数 `enable-binlog` 来开启 binlog 服务。尽量保证同一集群的所有 TiDB 都开启了 binlog 服务，否则在同步数据时可能会导致上下游数据不一致。如果要临时运行一个不开启 binlog 服务的 TiDB 实例，需要在 TiDB 的配置文件中设置 `run_ddl= false`。 -> - Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 -> - 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取**快照时间戳**，然后导入全量备份，最后启动 Drainer 从对应的快照时间戳开始同步增量数据。 -> - 下游使用 MySQL 或 TiDB 时应当保证上下游数据库的 sql_mode 具有一致性，即下游数据库同步每条 SQL 语句时的 sql_mode 应当与上游数据库执行该条 SQL 语句时的 sql_mode 保持一致。可以在上下游分别执行 `select @@sql_mode;` 进行查询和比对。 -> - 如果存在上游 TiDB 能运行但下游 MySQL 不支持的 DDL 语句时（例如下游 MySQL 使用 InnoDB 引擎时同步语句 `CREATE TABLE t1(a INT) ROW_FORMAT=FIXED;`），Drainer 也会同步失败，此时可以在 Drainer 配置中跳过该事务，同时在下游手动执行兼容的语句，详见[跳过事务](/v2.1/reference/tidb-binlog/faq.md#同步时出现上游数据库支持但是下游数据库执行会出错的-ddl应该怎么办)。 diff --git a/v2.1/reference/tidb-binlog/faq.md b/v2.1/reference/tidb-binlog/faq.md deleted file mode 100644 index 34d4a91924d6..000000000000 --- a/v2.1/reference/tidb-binlog/faq.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: TiDB Binlog 常见问题 -category: FAQ -aliases: ['/docs-cn/v2.1/faq/tidb-binlog/','/docs-cn/v2.1/reference/tools/tidb-binlog/faq/'] ---- - -# TiDB Binlog 常见问题 - -本文介绍 TiDB Binlog 使用过程中的常见问题及解决方案。 - -## 开启 binog 对 TiDB 的性能有何影响？ - -- 对于查询无影响。 - -- 对于有写入或更新数据的事务有一点性能影响。延迟上，在 Prewrite 阶段要并发写一条 p-binlog 成功后才可以提交事务，一般写 binlog 比 KV Prewrite 快，所以不会增加延迟。可以在 Pump 的监控面板看到写 binlog 的响应时间。 - -## Drainer 同步下游 TiDB/MySQL 的帐号需要哪些权限？ - -Drainer 同步帐号需要有如下权限： - -* Insert -* Update -* Delete -* Create -* Drop -* Alter -* Execute -* Index -* Select - -## Pump 磁盘快满了怎么办？ - -确认 GC 正常： - -- 确认 pump 监控面板 **gc_tso** 时间是否与配置一致，版本 <= v2.1.14 的 pump 会保证非 `offline` 状态 drainer 消费了数据才会 gc，如果有不再使用的 drainer 需要使用 binlogctl 下线。 - -如 gc 正常以下调整可以降低单个 pump 需要的空间大小： - -- 调整 pump **GC** 参数减少保留数据天数。 -- 添加 pump 结点。 - -## Drainer 同步中断怎么办？ - -使用以下 binlogctl 命令查看 Pump 状态是否正常，以及是否全部非 `offline` 状态的 Pump 都在正常运行。 - -{{< copyable "shell-regular" >}} - -```bash -binlogctl -cmd pumps -``` - -查看 Drainer 监控与日志是否有对应报错，根据具体问题进行处理。 - -## Drainer 同步下游 TiDB/MySQL 慢怎么办？ - -特别关注以下监控项： - -- 通过 Drainer 监控 **drainer event**，可以看到 Drainer 当前每秒同步 Insert/Update/Delete 事件到下游的速度。 -- 通过 Drainer 监控 **sql query time**，可以看到 Drainer 在下游执行 SQL 的响应时间。 - -同步慢的可能原因与解决方案： - -- 同步的数据库包含没有主键或者唯一索引的表，需要给表加上主键。 -- Drainer 与下游之间延迟大，可以调大 Drainer `worker-count` 参数（跨机房同步建议将 Drainer 部署在下游）。 -- 下游负载不高，可以尝试调大 Drainer `worker-count` 参数。 - -## 假如有一个 Pump crash 了会怎样？ - -Drainer 会因为获取不到这个 Pump 的数据没法同步数据到下游。如果这个 Pump 能恢复，Drainer 就能恢复同步。 - -如果 Pump 没法恢复，可采用以下方式进行处理： - -1. 使用 [binlogctl 将该 Pump 状态修改为 `offline`](/v2.1/reference/tidb-binlog/maintain.md)（丢失这个 Pump 的数据） -2. Drainer 获取到的数据会丢失这个 Pump 上的数据，下游跟上游数据会不一致，需要重新做全量 + 增量同步。具体步骤如下： - 1. 停止当前 Drainer。 - 2. 上游做全量备份。 - 3. 清理掉下游数据，包括 checkpoint 表 `tidb_binlog.checkpoint`。 - 4. 使用上游的全量备份恢复下游数据。 - 5. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 什么是 checkpoint？ - -Checkpoint 记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 -Drainer 日志 `["write save point"] [ts=411222863322546177]` 表示保存对应时间戳的 checkpoint。 - -下游类型不同，checkpoint 的保存方式也不同： - -- 下游 MySQL/TiDB 保存在 `tidb_binlog.checkpoint` 表。 -- 下游 kafka/file 保存在对应配置目录里的文件。 - -因为 kafka/file 的数据内容包含了 commit-ts，所以如果 checkpoint 丢失，可以消费下游最新的一条数据看写到下游数据的最新 commit-ts。 - -Drainer 启动的时候会去读取 checkpoint，如果读取不到，就会使用配置的 `initial-commit-ts` 做为初次启动开始的同步时间点。 - -## Drainer 机器发生故障，下游数据还在，如何在新机器上重新部署 Drainer？ - -如果下游数据还在，只要保证能从对应 checkpoint 接着同步即可。 - -假如 checkpoint 还在，可采用以下方式进行处理： - -1. 部署新的 Drainer 并启动即可（参考 checkpoint 介绍，Drainer 可以读取 checkpoint 接着同步）。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/v2.1/reference/tidb-binlog/maintain.md)。 - -假如 checkpoint 不在，可以如下处理： - -1. 获取之前 Drainer 的 checkpoint `commit-ts`，做为新部署 Drainer 的 `initial-commit-ts` 配置来部署新的 Drainer。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/v2.1/reference/tidb-binlog/maintain.md)。 - -## 如何用全量 + binlog 备份文件来恢复一个集群？ - -1. 清理集群数据并使用全部备份恢复数据。 -2. 使用 reparo 设置 `start-tso` = {全量备份文件快照时间戳+1}，`end-ts` = 0（或者指定时间点），恢复到备份文件最新的数据。 - -## 主从同步开启 `ignore-error` 触发 critical error 后如何重新部署？ - -TiDB 配置开启 `ignore-error` 写 binlog 失败后触发 critical error 告警，后续都不会再写 binlog，所以会有 binlog 数据丢失。如果要恢复同步，需要如下处理： - -1. 停止当前 Drainer。 -2. 重启触发 critical error 的 `tidb-server` 实例重新开始写 binlog（触发 critical error 后不会再写 binlog 到 pump）。 -3. 上游做全量备份。 -4. 清理掉下游数据包括 checkpoint 表 `tidb_binlog.checkpoint`。 -5. 使用上游的全量备份恢复下游。 -6. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 同步时出现上游数据库支持但是下游数据库执行会出错的 DDL，应该怎么办？ - -1. 查看 drainer.log 日志，查找 `exec failed` 找到 Drainer 退出前最后一条执行失败的 DDL。 -2. 将 DDL 改为下游兼容支持的版本，在下游数据库中手动执行。 -3. 查看 drainer.log 日志，查找执行失败的 DDL 语句，可以查询到该 DDL 的 commit-ts。 -4. 编辑 `drainer.toml` 配置文件，在 `ignore-txn-commit-ts` 项中添加该 commit-ts，重启 Drainer。 - -在绝大部分情况下，TiDB 和 MySQL 的语句都是兼容的。用户需要注意的是上下游的 `sql_mode` 应当保持一致。 - -## 在什么情况下暂停和下线 Pump/Drainer？ - -首先需要通过以下内容来了解 Pump/Drainer 的状态定义和启动、退出的流程。 - -暂停主要针对临时需要停止服务的场景，例如： - -- 版本升级：停止进程后使用新的 binary 启动服务。 -- 服务器维护：需要对服务器进行停机维护。退出进程，等维护完成后重启服务。 - -下线主要针对永久（或长时间）不再使用该服务的场景，例如： - -- Pump 缩容：不再需要那么多 Pump 服务了，所以下线部分服务。 -- 同步任务取消：不再需要将数据同步到某个下游，所以下线对应的 Drainer。 -- 服务器迁移：需要将服务迁移到其他服务器。下线服务，在新的服务器上重新部署。 - -## 可以通过哪些方式暂停 Pump/Drainer？ - -- 直接 kill 进程。 - - >**注意：** - > - > 不能使用 `kill -9` 命令，否则 Pump/Drainer 无法对信号进行处理。 - -- 如果 Pump/Drainer 运行在前台，则可以通过按下 Ctrl+C 来暂停。 -- 使用 binlogctl 的 `pause-pump` 或 `pause-drainer` 命令。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来下线 Pump/Drainer 服务吗？ - -不可以。使用 `update-pump`/`update-drainer` 命令会直接修改 PD 中保存的状态信息，并且不会通知 Pump/Drainer 做相应的操作。使用不当时，可能会干扰数据同步，某些情况下还可能会造成**数据不一致**的严重后果。例如： - -- 当 Pump 正常运行或者处于暂停状态时，如果使用 `update-pump` 将该 Pump 设置为 `offline`，那么 Drainer 会放弃获取处于 `offline` 状态的 Pump 的 binlog 数据，导致该 Pump 最新的 binlog 数据没有同步到 Drainer，造成上下游数据不一致。 -- 当 Drainer 正常运行时，使用 `update-drainer` 命令将该 Drainer 设置为 `offline`。如果这时启动一个 Pump 节点，Pump 只会通知 `online` 状态的 Drainer，导致该 Drainer 没有及时获取到该 Pump 的 binlog 数据，造成上下游数据不一致。## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来暂停 Pump/Drainer 服务吗？ - -不可以。`update-pump`/`update-drainer` 命令直接修改 PD 中保存的状态信息。执行这个命令并不会通知 Pump/Drainer 做相应的操作，**而且使用不当会使数据同步中断，甚至造成数据丢失。** - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来暂停 Pump/Drainer 服务吗？ - -不可以。`update-pump`/`update-drainer` 命令直接修改 PD 中保存的状态信息。执行这个命令并不会通知 Pump/Drainer 做相应的操作，**而且使用不当会使数据同步中断，甚至造成数据丢失。** - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `paused`？ - -在某些异常情况下，Pump 没有正确维护自己的状态，实际上状态应该为 `paused`。这时可以使用 `update-pump` 对状态进行修正，例如： - -- Pump 异常退出（可能由 panic 或者误操作执行 `kill -9` 命令直接 kill 掉进程导致），Pump 保存在 PD 中的状态仍然为 `online`。如果暂时不需要重启 Pump 恢复服务，可以使用 `update-pump` 把该 Pump 状态设置为 `paused`，避免对 TiDB 写 binlog 和 Drainer 获取 binlog 造成干扰。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `paused`？ - -在某些异常情况下，Drainer 没有正确维护自己的状态，，对数据同步造成了影响，实际上状态应该为 `paused`。这时可以使用 `update-drainer` 对状态进行修正，例如： - -- Drainer 异常退出（出现 panic 直接退出进程，或者误操作执行 `kill -9` 命令直接 kill 掉进程），Drainer 保存在 PD 中的状态仍然为 `online`。当 Pump 启动时无法正常通知该 Drainer（报错 `notify drainer ...`），导致 Pump 无法正常运行。这个时候可以使用 `update-drainer` 将 Drainer 状态更新为 `paused`，再启动 Pump。 - -## 可以通过哪些方式下线 Pump/Drainer？ - -目前只可以使用 binlogctl 的 `offline-pump` 和 `offline-drainer` 命令来下线 Pump 和 Drainer。 - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `offline`? - -> **警告：** -> -> 仅在可以容忍 binlog **数据丢失、上下游数据不一致**或者确认不再需要使用该 Pump 存储的 binlog 数据的情况下，才能使用 `update-pump` 修改 Pump 状态为 `offline`。 - -可以使用 `update-pump` 修改 Pump 状态为 `offline` 的情况有： - -- 在某些情况下，Pump 异常退出进程，且无法恢复服务，同步就会中断。如果希望恢复同步且可以容忍部分 binlog 数据丢失，可以使用 `update-pump` 命令将该 Pump 状态设置为 `offline`，则 Drainer 会放弃拉取该 Pump 的 binlog 然后继续同步数据。 -- 有从历史任务遗留下来且不再使用的 Pump 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-pump` 将该 Pump 设置为 `offline`。 - -在其他情况下一定要使用 `offline-pump` 命令让 Pump 走正常的下线处理流程。 - -## Pump 进程已经退出，且状态为 `paused`，现在不想使用这个 Pump 节点了，能否用 binlogctl 的 `update-pump` 命令设置节点状态为 `offline`？ - -Pump 以 `paused` 状态退出进程时，不保证所有 binlog 数据被下游 Drainer 消费。所以这样做会有上下游数据不一致的风险。正确的做法是重新启动 Pump，然后使用 `offline-pump` 下线该 Pump。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `offline`？ - -- 有从历史任务遗留下来且不再使用的 Drainer 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-drainer` 将该 Drainer 设置为 `offline`。 - -## 可以使用 `change pump`、`change drainer` 等 SQL 操作来暂停或者下线 Pump/Drainer 服务吗？ - -目前还不支持。这种 SQL 操作会直接修改 PD 中保存的状态，在功能上等同于使用 binlogctl 的 `update-pump`、`update-drainer` 命令。如果需要暂停或者下线，仍然要使用 binlogctl。 diff --git a/v2.1/reference/tidb-binlog/glossary.md b/v2.1/reference/tidb-binlog/glossary.md deleted file mode 100644 index 473cfa7fece0..000000000000 --- a/v2.1/reference/tidb-binlog/glossary.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB Binlog 术语表 -summary: 学习 TiDB Binlog 相关术语 -category: glossary ---- - -# TiDB Binlog 术语表 - -本文档介绍 TiDB Binlog 相关术语。 - -## Binlog - -在 TiDB Binlog 中，Binlog 通常 TiDB 写的 Binlog 数据，注意 TiDB Binlog 的格式跟 MySQL 不同，也指 Drainer 写到 Kafka 或者文件的 Binlog 数据，但他们的格式不一样。 - -## Binlog event - -TiDB 写的 DML Binlog 有 3 种 event, 分别是 Insert, Update, Delete, Drainer 监控面板 可以看到对应同步数据不同 event 的个数。 - -## Checkpoint - -Checkpoint 指保存的断点信息，记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 - -## Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在 Drainer 启动的前 5 分钟会自动启动 Safe mode，另外也可以配置文件中通过 `safe-mode` 参数手动开启。 - -该配置仅对下游是 MySQL/TiDB 有效。 diff --git a/v2.1/reference/tidb-binlog/maintain.md b/v2.1/reference/tidb-binlog/maintain.md deleted file mode 100644 index 4f4a34d2ca61..000000000000 --- a/v2.1/reference/tidb-binlog/maintain.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: TiDB Binlog 集群运维 -category: reference -aliases: ['/docs-cn/v2.1/how-to/maintain/tidb-binlog/','/docs-cn/v2.1/reference/tools/tidb-binlog/maintain/'] ---- - -# TiDB Binlog 集群运维 - -本文首先介绍 Pump 和 Drainer 的状态及启动、退出的内部处理流程，然后说明如何通过 binlogctl 工具或者直接在 TiDB 执行 SQL 操作来管理 binlog 集群，最后的 FAQ 部分会介绍一些常见问题以及处理方法。 - -## Pump/Drainer 的状态 - -Pump/Drainer 中状态的定义： - -* online：正常运行中 -* pausing：暂停中 -* paused：已暂停 -* closing：下线中 -* offline：已下线 - -这些状态由 Pump/Drainer 服务自身进行维护，并定时将状态信息更新到 PD 中。 - -## Pump/Drainer 的启动、退出流程 - -### Pump - -* 启动：Pump 启动时会通知所有 online 状态的 Drainer，如果通知成功，则 Pump 将状态设置为 online，否则 Pump 将报错，然后将状态设置为 paused 并退出进程。 -* 退出：Pump 进程正常退出前要选择进入暂停或者下线状态；非正常退出（kill -9、进程 panic、宕机）都依然保持 online 状态。 - - * 暂停：使用 kill（非 kill -9）、Ctrl+C 或者使用 binlogctl 的 pause-pump 命令都可以暂停 Pump。接收到暂停指令后，Pump 会变更状态为 pausing，并停止接受 binlog 的写请求，也停止向 Drainer 提供 binlog 数据。安全退出所有线程后，更新状态为 paused 然后退出进程。 - * 下线：仅在使用 binlogctl 的 offline-pump 命令的情况下才会下线 Pump。接收到下线指令后，Pump 会变更状态为 closing，并停止接受 binlog 的写请求。Pump 继续向 Drainer 提供 binlog，等待所有 binlog 数据都被 Drainer 消费后再将状态设置为 offline 并退出进程。 - -### Drainer - -* 启动：Drainer 启动时将状态设置为 online，并尝试从所有非 offline 状态的 Pump 获取 binlog，如果获取 binlog 失败，会不断尝试重新获取。 -* 退出：Drainer 进程正常退出前要选择进入暂停或者下线状态；非正常退出（kill -9 、进程 panic、宕机）都依然保持 online 状态。 - - * 暂停：使用 kill（非 kill -9）、Ctrl+C 或者使用 binlogctl 的 pause-drainer 命令都可以暂停 Drainer。接收到指令后，Drainer 会变更状态为 pausing，并停止从 Pump 获取 binlog。安全退出所有线程后，更新状态为 paused 然后退出进程。 - * 下线：仅在使用 binlogctl 的 offline-drainer 命令的情况下才会下线 Drainer。接收到下线指令后，Drainer 变更状态为 closing，并停止从 Pump 获取 binlog。安全退出所有线程后，更新状态为 offline 然后退出进程。 - -关于 Pump/Drainer 暂停、下线、状态查询、状态修改等具体的操作方法，参考如下 binlogctl 工具的使用方法介绍。 - -## binlogctl 工具 - -支持如下这些功能： - -* 查看 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer -* Pump/Drainer 异常状态处理 - -使用 binlogctl 的场景： - -* 同步出现故障/检查运行情况，需要查看 Pump/Drainer 的状态 -* 维护集群，需要暂停/下线 Pump/Drainer -* Pump/Drainer 异常退出，状态没有更新，或者状态不符合预期，对业务造成影响 - -binlogctl 下载链接： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，binlogctl 已经包含在 TiDB 的下载包中，其他版本需要单独下载 binlogctl: - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -binlogctl 使用说明： - -命令行参数： - -```bash -Usage of binlogctl: --V -输出 binlogctl 的版本信息 --cmd string - 命令模式，包括 "generate_meta"（已废弃）, "pumps", "drainers", "update-pump" ,"update-drainer", "pause-pump", "pause-drainer", "offline-pump", "offline-drainer" --data-dir string - 保存 Drainer 的 checkpoint 的文件的路径 (默认 "binlog_position")（已废弃） --node-id string - Pump/Drainer 的 ID --pd-urls string - PD 的地址，如果有多个，则用"," 连接 (默认 "http://127.0.0.1:2379") --ssl-ca string - SSL CAs 文件的路径 --ssl-cert string - PEM 格式的 X509 认证文件的路径 --ssl-key string - PEM 格式的 X509 key 文件的路径 --time-zone string - 如果设置时区，在 "generate_meta" 模式下会打印出获取到的 tso 对应的时间。例如 "Asia/Shanghai" 为 CST 时区，"Local" 为本地时区 --show-offline-nodes - 在用 `-cmd pumps` 或 `-cmd drainers` 命令时使用，这两个命令默认不显示 offline 的节点，仅当明确指定 `-show-offline-nodes` 时会显示 -``` - -命令示例： - -- 查询所有的 Pump/Drainer 的状态： - - 设置 `cmd` 为 `pumps` 或者 `drainers` 来查看所有 Pump 或者 Drainer 的状态。例如： - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pumps - ``` - - ``` - [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=pump] [node="{NodeID: 1.1.1.1:8250, Addr: pump:8250, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"] - ``` - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd drainers - ``` - - ``` - [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=drainer] [node="{NodeID: 1.1.1.1:8249, Addr: 1.1.1.1:8249, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"] - ``` - -- 暂停/下线 Pump/Drainer - - binlogctl 提供以下命令暂停/下线服务： - - | cmd | 说明 | 示例 | - | --------------- | ------------- | ------------------------------------------------------------------------------------------------| - | pause-pump | 暂停 Pump | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-pump -node-id ip-127-0-0-1:8250` | - | pause-drainer | 暂停 Drainer | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-drainer -node-id ip-127-0-0-1:8249` | - | offline-pump | 下线 Pump | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-pump -node-id ip-127-0-0-1:8250` | - | offline-drainer | 下线 Drainer | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-drainer -node-id ip-127-0-0-1:8249` | - - binlogctl 会发送 HTTP 请求给 Pump/Drainer，Pump/Drainer 收到命令后会主动执行对应的退出流程。 - -- 异常情况下修改 Pump/Drainer 的状态 - - 在服务正常运行以及符合流程的暂停、下线过程中，Pump/Drainer 的状态都是可以正确的。但是在一些异常情况下 Pump/Drainer 无法正确维护自己的状态，可能会影响数据同步任务，在这种情况下需要使用 binlogctl 修复状态信息。 - - 设置 `cmd` 为 `update-pump` 或者 `update-drainer` 来更新 Pump 或者 Drainer 的状态。Pump 和 Drainer 的状态可以为 paused 或者 offline。例如： - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd update-pump -node-id ip-127-0-0-1:8250 -state paused - ``` - - > **注意：** - > - > Pump/Drainer 在正常运行过程中会定期在 PD 中更新自己的状态，而这条命令是直接去修改 Pump/Drainer 保存在 PD 中的状态，所以在 Pump/Drainer 服务正常的情况下使用这些命令是没有意义的。仅在 Pump/Drainer 服务异常的情况下使用，具体哪些场景下使用这条命令可以参考 FAQ。 - -## 使用 TiDB SQL 管理 Pump/Drainer - -要查看和管理 binlog 相关的状态，可在 TiDB 中执行相应的 SQL 语句。 - -- 查看 TiDB 是否开启 binlog - - {{< copyable "sql" >}} - - ```sql - show variables like "log_bin"; - ``` - - ``` - +---------------+-------+ - | Variable_name | Value | - +---------------+-------+ - | log_bin | ON | - +---------------+-------+ - ``` - - 值为 `ON` 时表示 TiDB 开启了 binlog。 - -- 查看 Pump/Drainer 状态 - - {{< copyable "sql" >}} - - ```sql - show pump status; - ``` - - ``` - +--------|----------------|--------|--------------------|---------------------| - | NodeID | Address | State | Max_Commit_Ts | Update_Time | - +--------|----------------|--------|--------------------|---------------------| - | pump1 | 127.0.0.1:8250 | Online | 408553768673342237 | 2019-05-01 00:00:01 | - +--------|----------------|--------|--------------------|---------------------| - | pump2 | 127.0.0.2:8250 | Online | 408553768673342335 | 2019-05-01 00:00:02 | - +--------|----------------|--------|--------------------|---------------------| - ``` - - {{< copyable "sql" >}} - - ```sql - show drainer status; - ``` - - ``` - +----------|----------------|--------|--------------------|---------------------| - | NodeID | Address | State | Max_Commit_Ts | Update_Time | - +----------|----------------|--------|--------------------|---------------------| - | drainer1 | 127.0.0.3:8249 | Online | 408553768673342532 | 2019-05-01 00:00:03 | - +----------|----------------|--------|--------------------|---------------------| - | drainer2 | 127.0.0.4:8249 | Online | 408553768673345531 | 2019-05-01 00:00:04 | - +----------|----------------|--------|--------------------|---------------------| - ``` - -- 异常情况下修改 Pump/Drainer 状态 - - {{< copyable "sql" >}} - - ```sql - change pump to node_state ='paused' for node_id 'pump1'; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - change drainer to node_state ='paused' for node_id 'drainer1'; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - 该 SQL 的功能和 binlogctl 中的 update-pump 和 update-drainer 命令的功能一样，因此也只有在 Pump/Drainer 异常的情况下使用。 - -> **注意：** -> -> 1. 查看 binlog 开启状态以及 Pump/Drainer 状态的功能在 TiDB v2.1.7 及以上版本中支持。 -> 2. 修改 Pump/Drainer 状态的功能在 TiDB v3.0.0-rc.1 及以上版本中支持。该功能只修改 PD 中存储的 Pump/Drainer 状态，如果需要暂停/下线节点，仍然需要使用 `binlogctl`。 diff --git a/v2.1/reference/tidb-binlog/monitor.md b/v2.1/reference/tidb-binlog/monitor.md deleted file mode 100644 index d658bb9735ba..000000000000 --- a/v2.1/reference/tidb-binlog/monitor.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: TiDB Binlog 集群监控 -category: reference -aliases: ['/docs-cn/v2.1/how-to/monitor/tidb-binlog/','/docs-cn/v2.1/reference/tools/tidb-binlog/monitor/'] ---- - -# TiDB Binlog 集群监控 - -使用 Ansible 成功部署 TiDB Binlog 集群后，可以进入 Grafana Web 界面（默认地址: ，默认账号：admin，密码：admin）查看 Pump 和 Drainer 的运行状态。 - -## 监控指标 - -### Pump - -| metric 名称 | 说明 | -|:----|:------------| -| Storage Size | 记录磁盘的总空间大小 (capacity)，以及可用磁盘空间大小 (available) | -| Metadata | 记录每个 Pump 的可删除 binlog 的最大 tso (gc_tso)，以及保存的 binlog 的最大的 commit tso (max_commit_tso)。 | -| Write Binlog QPS by Instance | 每个 Pump 接收到的写 binlog 请求的 QPS | -| Write Binlog Latency | 记录每个 Pump 写 binlog 的延迟时间 | -| Storage Write Binlog Size | Pump 写 binlog 数据的大小 | -| Storage Write Binlog Latency | Pump 中的 storage 模块写 binlog 数据的延迟 | -| Pump Storage Error By Type | Pump 遇到的 error 数量，按照 error 的类型进行统计 | -| Query TiKV | Pump 通过 TiKV 查询事务状态的次数 | - -### Drainer - -| metric 名称 | 说明 | -|:----|:------------| -| Checkpoint TSO | Drainer 已经同步到下游的 binlog 的最大 TSO 对应的时间。可以通过该指标估算同步延迟时间 | -| Pump Handle TSO | 记录 Drainer 从各个 Pump 获取到的 binlog 的最大 TSO 对应的时间 | | Pull Binlog QPS by Pump NodeID | Drainer 从每个 Pump 获取 binlog 的 QPS | -| 95% Binlog Reach Duration By Pump | 记录 binlog 从写入 Pump 到被 Drainer 获取到这个过程的延迟时间 | -| Error By Type | Drainer 遇到的 error 数量，按照 error 的类型进行统计 | -| SQL Query Time| Drainer 在下游执行 SQL 的耗时 | -| Drainer Event | 各种类型 event 的数量，event 包括 ddl、insert、delete、update、flush、savepoint | -| Execute Time | 写入 binlog 到同步下游模块所消耗的时间 | -| 95% Binlog Size | Drainer 从各个 Pump 获取到 binlog 数据的大小 | -| DL Job Count | Drainer 处理的 DDL 的数量| -| Queue Size | Drainer 内部工作队列大小 | - -## 监控报警规则 - -本节介绍了 TiDB Binlog 组件的报警项及相应的报警规则。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别 (Emergency)、重要级别 (Critical)、警告级别 (Warning)。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `binlog_pump_storage_error_count` - -* 报警规则： - - `changes(binlog_pump_storage_error_count[1m]) > 0` - -* 规则描述： - - Pump 写 binlog 到本地存储时失败。 - -* 处理方法： - - 确认 `pump_storage_error` 监控是否存在错误，查看 Pump 日志确认原因。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `binlog_drainer_checkpoint_high_delay` - -* 报警规则： - - `(time() - binlog_drainer_checkpoint_tso / 1000) > 3600` - -* 规则描述： - - Drainer 同步落后延迟超过 1 个小时。 - -* 处理方法： - - * 判断从 Pump 获取数据是否太慢： - - 监控 Pump handle tso 可以看每个 Pump 最近一条消息的时间，是不是有延迟特别大的 Pump，确认对应 Pump 正常运行。 - - * 根据 Drainer event 和 Drainer execute latency 来判断是否下游同步太慢： - - * 如果 Drainer execute time 过大，则检查到目标库网络带宽和延迟，以及目标库状态。 - * 如果 Drainer execute time 不大，Drainer event 过小，则增加 work count 和 batch 进行重试。 - - * 如果上面都不满足或者操作后没有改观，则报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `binlog_pump_write_binlog_rpc_duration_seconds_bucket` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_pump_rpc_duration_seconds_bucket{method="WriteBinlog"}[5m])) > 1` - -* 规则描述： - - Pump 处理 TiDB 写 Binlog 请求耗时过大。 - -* 处理方法： - - * 确认磁盘性能压力，通过 `node exported` 查看 disk performance 监控。 - * 如果 `disk latency` 和 `util` 都很低，那么报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -#### `binlog_pump_storage_write_binlog_duration_time_bucket` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_pump_storage_write_binlog_duration_time_bucket{type="batch"}[5m])) > 1` - -* 规则描述： - - Pump 写本地 binlog 到本地盘的耗时。 - -* 处理方法： - - 确认 Pump 本地盘情况，进行修复。 - -#### `binlog_pump_storage_available_size_less_than_20G` - -* 报警规则： - - `binlog_pump_storage_storage_size_bytes{type="available"} < 20 * 1024 * 1024 * 1024` - -* 规则描述： - - Pump 剩余可用磁盘空间不足 20 G。 - -* 处理方法： - - 监控确认 Pump 的 `gc_tso` 是否正常。如果不正常，调整 Pump 的 GC 时间配置或者下线对应 Pump。 - -#### `binlog_drainer_checkpoint_tso_no_change_for_1m` - -* 报警规则： - - `changes(binlog_drainer_checkpoint_tso[1m]) < 1` - -* 规则描述： - - Drainer 的 `checkpoint` 在 1 分钟内没有更新。 - -* 处理方法： - - 确认所有非下线的 Pump 是否正常运行。 - -#### `binlog_drainer_execute_duration_time_more_than_10s` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_drainer_execute_duration_time_bucket[1m])) > 10` - -* 规则描述： - - Drainer 同步到 TiDB 的事务耗时。如果这个值过大，会影响 Drainer 同步。 - -* 处理方法： - - * 查看 TiDB 集群的状态。 - * 查看 Drainer 日志或监控，如果是 DDL 操作导致了该问题，则忽略。 diff --git a/v2.1/reference/tidb-binlog/overview.md b/v2.1/reference/tidb-binlog/overview.md deleted file mode 100644 index 01cfe11e5f04..000000000000 --- a/v2.1/reference/tidb-binlog/overview.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: TiDB Binlog 简介 -category: reference -aliases: ['/docs-cn/v2.1/reference/tidb-binlog-overview/','/docs-cn/v2.1/reference/tools/tidb-binlog/overview/'] ---- - -# TiDB Binlog 简介 - -TiDB Binlog 是一个用于收集 TiDB 的 binlog，并提供准实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景： - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog 整体架构 - -![TiDB Binlog 架构](/media/tidb_binlog_cluster_architecture.png) - -TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl 工具： - -### Pump - -Pump 用于实时记录 TiDB 产生的 Binlog，并将 Binlog 按照事务的提交时间进行排序，再提供给 Drainer 进行消费。 - -### Drainer - -Drainer 从各个 Pump 中收集 Binlog 进行归并，再将 Binlog 转化成 SQL 或者指定格式的数据，最终同步到下游。 - -### binlogctl 工具 - -binlogctl 是一个 TiDB Binlog 配套的运维工具，具有如下功能： - -* 获取 TiDB 集群当前的 TSO -* 查看 Pump/Drainer 状态 -* 修改 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer - -## 主要特性 - -* 多个 Pump 形成一个集群，可以水平扩容。 -* TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。 -* Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。 -* Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。 - -## 注意事项 - -* 需要使用 TiDB v2.0.8-binlog、v2.1.0-rc.5 及以上版本，否则不兼容该版本的 TiDB Binlog。 - -* Drainer 支持将 Binlog 同步到 MySQL、TiDB、Kafka 或者本地文件。如果需要将 Binlog 同步到其他 Drainer 不支持的类型的系统中，可以设置 Drainer 将 Binlog 同步到 Kafka，然后根据 binlog slave protocol 进行定制处理，参考 [binlog slave client 用户文档](/v2.1/reference/tidb-binlog/binlog-slave-client.md)。 - -* 如果 TiDB Binlog 用于增量恢复，可以设置配置项 `db-type="file"`，Drainer 会将 binlog 转化为指定的 [proto buffer 格式](https://github.com/pingcap/tidb-binlog/blob/master/proto/binlog.proto)的数据，再写入到本地文件中。这样就可以使用 [Reparo](/v2.1/reference/tidb-binlog/reparo.md) 恢复增量数据。 - - 关于 `db-type` 的取值，应注意： - - - 如果 TiDB 版本 < 2.1.9，则 `db-type="pb"`。 - - 如果 TiDB 版本 > = 2.1.9，则 `db-type="file"` 或 `db-type="pb"`。 - -* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/v2.1/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。 diff --git a/v2.1/reference/tidb-binlog/reparo.md b/v2.1/reference/tidb-binlog/reparo.md deleted file mode 100644 index e2791a5d735e..000000000000 --- a/v2.1/reference/tidb-binlog/reparo.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Reparo 使用文档 -category: reference -aliases: ['/docs-cn/v2.1/reference/tools/tidb-binlog/reparo/'] ---- - -# Reparo 使用文档 - -Reparo 是 TiDB Binlog 的一个配套工具，用于增量的恢复。使用 TiDB Binlog 中的 Drainer 将 binlog 按照 protobuf 格式输出到文件，通过这种方式来备份增量数据。当需要恢复增量数据时，使用 Reparo 解析文件中的 binlog，并将其应用到 TiDB／MySQL 中。 - -下载链接：[tidb-binlog-cluster-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-binlog-cluster-latest-linux-amd64.tar.gz) - -## Reparo 使用 - -### 命令行参数说明 - -``` -Usage of Reparo: --L string - 日志输出信息等级设置：debug, info, warn, error, fatal（默认值：info）。 --V 打印版本信息。 --c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好（默认 16）。 --config string - 配置文件路径，如果指定了配置文件，Reparo 会首先读取配置文件的配置；如果对应的配置在命令行参数里面也存在，Reparo 就会使用命令行参数的配置来覆盖配置文件里面的。 --data-dir string - Drainer 输出的 protobuf 格式 binlog 文件的存储路径 (默认值： data.drainer)。 --dest-type string - 下游服务类型。 取值为 print, mysql（默认值：print）。当值为 print 时，只做解析打印到标准输出，不执行 SQL；如果为 mysql，则需要在配置文件内配置 host、port、user、password 等信息。 --log-file string - log 文件路径。 --log-rotate string - log 文件切换频率，取值为 hour、day。 --start-datetime string - 用于指定开始恢复的时间点，格式为 “2006-01-02 15:04:05”。如果不设置该参数则从最早的 binlog 文件开始恢复。 --stop-datetime string - 用于指定结束恢复的时间点，格式同上。如果不设置该参数则恢复到最后一个 binlog 文件。 --safe-mode bool - 指定是否开启安全模式，开启后可支持反复同步。 --txn-batch int - 输出到下游数据库一个事务的 SQL 语句数量（默认 20）。 - -``` - -### 配置文件说明 - -```toml -# Drainer 输出的 protobuf 格式 binlog 文件的存储路径。 -data-dir = "./data.drainer" - -# 使用索引文件来搜索 ts 的位置，当设置了 `start-ts` 时设置该参数，文件的路径为 {data-dir}/{index-name}。 -# index-name = "binlog.index" -# log-file = "" -# log-rotate = "hour" - -# 日志输出信息等级设置：debug, info, warn, error, fatal (默认值：info)。 -log-level = "info" - -# 使用 start-datetime 和 stop-datetime 来选择恢复指定时间范围内的 binlog，格式为 “2006-01-02 15:04:05”。 -# start-datetime = "" -# stop-datetime = "" - -# start-tso、stop-tso 分别对应 start-datetime 和 stop-datetime，也是用于恢复指定时间范围内的 binlog，用 tso 的值来设置。如果已经设置了 start-datetime 和 stop-datetime，就不需要再设置 start-tso 和 stop-tso。 -# start-tso = 0 -# stop-tso = 0 - -# 下游服务类型。 取值为 print, mysql（默认值：print）。当值为 print 时，只做解析打印到标准输出，不执行 SQL；如果为 mysql，则需要在 [dest-db] 中配置 host、port、user、password 等信息。 -dest-type = "mysql" - -# 输出到下游数据库一个事务的 SQL 语句数量（默认 20）。 -txn-batch = 20 - -# 同步下游的并发数，该值设置越高同步的吞吐性能越好（默认 16）。 -worker-count = 16 - -# 安全模式配置。取值为 true 或 false（默认值：false）。当值为 true 时，Reparo 会将 update 语句拆分为 delete + replace 语句。 -safe-mode = false - -# replicate-do-db 和 replicate-do-table 用于指定恢复的库和表，replicate-do-db 的优先级高于 replicate-do-table。支持使用正则表达式来配置，需要以 '~' 开始声明使用正则表达式。 -# 注：replicate-do-db 和 replicate-do-table 使用方式与 Drainer 的使用方式一致。 -# replicate-do-db = ["~^b.*","s1"] -# [[replicate-do-table]] -# db-name ="test" -# tbl-name = "log" -# [[replicate-do-table]] -# db-name ="test" -# tbl-name = "~^a.*" - -# 如果 dest-type 设置为 mysql, 需要配置 dest-db。 -[dest-db] -host = "127.0.0.1" -port = 3309 -user = "root" -password = "" -``` - -### 启动示例 - -``` -./bin/reparo -config reparo.toml -``` - -> **注意：** -> -> - data-dir 用于指定 Drainer 输出的 binlog 文件目录。 -> - start-datatime 和 start-tso 效果一样，只是时间格式上的区别，用于指定开始恢复的时间点；如果不指定，则默认在第一个 binlog 文件开始恢复。 -> - stop-datetime 和 stop-tso 效果一样，只是时间格式上的区别，用于指定结束恢复的时间点；如果不指定，则恢复到最后一个 binlog 文件的结尾。 -> - dest-type 指定目标类型，取值为 `mysql`、`print`。 当值为 `mysql` 时，可以恢复到 MySQL/TiDB 等使用或兼容 MySQL 协议的数据库，需要在配置下面的 [dest-db] 填写数据库信息；当取值为 `print` 的时候，只是打印 binlog 信息，通常用于 debug，以及查看 binlog 的内容，此时不需要填写 `[dest-db]`。 -> - replicate-do-db 用于指定恢复的库，不指定的话，则全部都恢复。 -> - replicate-do-table 用于指定要恢复的表，不指定的话，则全部都恢复。 diff --git a/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md b/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md deleted file mode 100644 index 3d6f056ea3a1..000000000000 --- a/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md +++ /dev/null @@ -1,426 +0,0 @@ ---- -title: TiDB Binlog kafka 部署方案 -category: reference -aliases: ['/docs-cn/v2.1/reference/tools/tidb-binlog/tidb-binlog-kafka/'] ---- - -# TiDB Binlog Kafka 部署方案 - -本文档介绍如何部署 Kafka 版本的 TiDB Binlog。 - -## TiDB Binlog 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog Kafka 架构 - -首先介绍 TiDB Binlog 的整体架构。 - -![TiDB Binlog 架构](/media/tidb_binlog_kafka_architecture.png) - -TiDB Binlog 集群主要分为三个组件： - -### Pump - -Pump 是一个守护进程，在每个 TiDB 主机的后台运行。其主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入 Kafka 中。 - -### Drainer - -Drainer 从 Kafka 中收集 Binlog，并按照 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件。 - -### Kafka & ZooKeeper - -Kafka 集群用来存储由 Pump 写入的 Binlog 数据，并提供给 Drainer 进行读取。 - -> **注意：** -> -> Local 版本将 Binlog 存储在文件中，Kafka 版本则使用 Kafka 存储。 - -## TiDB Binlog 安装 - -以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - -| TiDB Ansible 分支 | TiDB 版本 | 备注 | -|:----|:----|:----| -| release-2.0 | 2.0 版本 | 最新 2.0 稳定版本，可用于生产环境。 | - -### 下载官方 Binary - -CentOS 7+ - -```bash -# 下载压缩包 -wget https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz -wget https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256 - -# 检查文件完整性，返回 ok 则正确 -sha256sum -c tidb-binlog-kafka-linux-amd64.sha256 - -# 解开压缩包 -tar -xzf tidb-binlog-kafka-linux-amd64.tar.gz -cd tidb-binlog-kafka-linux-amd64 -``` - -### TiDB Binlog 部署 - -#### 注意事项 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 的方式输出 Binlog。 - -* 手动部署时，启动顺序为：Pump > TiDB。停止顺序为 TiDB > Pump。 - - 设置 TiDB 启动参数 `binlog-socket` 为对应的 Pump 参数 `socket` 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 - -* 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取 savepoint，然后导入全量备份，最后启动 Drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 Pump 运行 10 分钟左右后按顺序进行如下操作： - - * 使用 [binlogctl](https://github.com/pingcap/tidb-tools/tree/binlog-kafka/tidb_binlog/binlogctl) 工具生成 Drainer 初次启动所需的 position - * 全量备份，例如 Mydumper 备份 TiDB - * 全量导入备份到目标系统 - * Kafka 版本 Drainer 启动的 savepoint 默认保存在下游 database tidb_binlog 下的 checkpoint 表中，如果 checkpoint 表中没有有效的数据，可以通过设置 `initial-commit-ts` 启动 Drainer 从指定位置开始消费 - `bin/drainer --config=conf/drainer.toml --initial-commit-ts=${position}` - -* Drainer 输出为 pb，要在配置文件中设置如下参数： - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -* Drainer 输出为 kafka，要在配置文件中设置如下参数： - - ```toml - [syncer] - db-type = "kafka" - - # when db-type is kafka, you need to use this to config the down stream kafka, or it will be the same kafka addrs where drainer pull binlog from. - [syncer.to] - kafka-addrs = "127.0.0.1:9092" - kafka-version = "0.8.2.0" - ``` - - 输出到 kafka 的数据为按 ts 排好序的 protobuf 定义 binlog 格式，可以参考 [driver](https://github.com/pingcap/tidb-tools/tree/master/tidb-binlog/driver) 获取数据同步到下游。 - -* Kafka 和 ZooKeeper 集群需要在部署 TiDB Binlog 之前部署好。Kafka 需要 0.9 及以上版本。 - -#### Kafka 集群配置推荐 - -|名字|数量|内存|CPU|硬盘| -|:---:|:---:|:---:|:---:|:---:| -|Kafka|3+|16G|8+|2+ 1TB| -|ZooKeeper|3+|8G|4+|2+ 300G| - -#### Kafka 配置参数推荐 - -- `auto.create.topics.enable = true`：如果还没有创建 topic，Kafka 会在 broker 上自动创建 topic -- `broker.id`：用来标识 Kafka 集群的必备参数，不能重复，如 `broker.id = 1` -- `fs.file-max = 1000000`：Kafka 会使用大量文件和网络 socket，建议修改成 1000000，通过 `vi /etc/sysctl.conf` 进行修改 -- 修改以下配置为1G, 否则很容易出现事务修改数据较多导致单个消息过大写 kafka 失败 - - * `message.max.bytes=1073741824` - * `replica.fetch.max.bytes=1073741824` - * `fetch.message.max.bytes=1073741824` - -#### 使用 TiDB Ansible 部署 Pump - -- 如无 Kafka 集群，可使用 [kafka-ansible](https://github.com/pingcap/thirdparty-ops/tree/master/kafka-ansible) 部署 Kafka 集群。 -- 使用 [tidb-ansible](https://github.com/pingcap/tidb-ansible) 部署 TiDB 集群时，修改 `tidb-ansible/inventory.ini` 文件，设置 `enable_binlog = True`，并配置 `zookeeper_addrs` 变量为 Kafka 集群的 ZooKeeper 地址，这样部署 TiDB 集群时会部署 Pump。 - -配置样例: - -```ini -# binlog trigger -enable_binlog = True -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -``` - -#### 使用 Binary 部署 Pump - -使用样例： - -假设我们有三个 PD，三个 ZooKeeper，一个 TiDB，各个节点信息如下： - -```ini -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -ZK1="192.168.0.13" -ZK2="192.168.0.12" -ZK3="192.168.0.11" -``` - -在 ip="192.168.0.10" 的机器上面部署 Drainer/Pump。 - -对应的 PD 集群的 ip="192.168.0.16,192.168.0.15,192.168.0.14"。 - -对应的 Kafka 集群的 ZooKeeper 的 ip="192.168.0.13,192.168.0.12,192.168.0.11"。以此为例，说明 Pump/Drainer 的使用。 - -1. Pump 命令行参数说明 - - ``` - Usage of Pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.10:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.10:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里面的。 - -data-dir string - Pump 数据存储位置路径 - -enable-tolerant - 开启 tolerant 后，如果 binlog 写入失败，Pump 不会报错（默认开启） - -zookeeper-addrs string (-zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181") - ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，需要和 Kafka 中配置相同 - -gc int - 日志最大保留天数 (默认 7)，设置为 0 可永久保存 - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -socket string - unix socket 模式服务监听地址（默认 unix:///tmp/pump.sock） - ``` - -2. Pump 配置文件 - - ```toml - # Pump Configuration. - - # Pump 提供服务的 RPC 地址("192.168.0.10:8250") - addr = "192.168.0.10:8250" - - # Pump 对外提供服务的 RPC 地址("192.168.0.10:8250") - advertise-addr = "" - - # binlog 最大保留天数 (默认 7)，设置为 0 可永久保存 - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，若 Kafka 中配置了命名空间，则此处需同样配置 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" - # 配置了命令空间的 ZooKeeper 地址配置示例 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 3 - - # PD 集群节点的地址 - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of Drainer: - -L string - 日志输出信息等级设置：debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.10:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -zookeeper-addrs string (-zookeeper-addrs="192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181") - ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，需要和 Kafka 中配置相同 - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步（下游服务类型为 mysql，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts (默认为 0) - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位 秒） - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - -2. Drainer 配置文件 - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.10:8249") - addr = "192.168.0.10:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，若 Kafka 中配置了命名空间，则此处需同样配置 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" - # 配置了命令空间的 ZooKeeper 地址配置示例 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" - - # PD 集群节点的地址 - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 SQL 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 mysql, 该项设置为 False） - disable-dispatch = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db prioritizes over replicate-do-table when they have the same db name - # and we support regex expressions, - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.10" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## 下载 PbReader 工具 (Linux) - -PbReader 用于解析 Drainer 生成的 Pb 文件，并翻译成对应的 SQL 语句。 - -CentOS 7+ - -```bash -# 下载 PbReader 压缩包 -wget https://download.pingcap.org/pb_reader-latest-linux-amd64.tar.gz -wget https://download.pingcap.org/pb_reader-latest-linux-amd64.sha256 - -# 检查文件完整性，返回 ok 则正确 -sha256sum -c pb_reader-latest-linux-amd64.sha256 - -# 解开压缩包 -tar -xzf pb_reader-latest-linux-amd64.tar.gz -cd pb_reader-latest-linux-amd64 -``` - -PbReader 使用示例 - -```bash -./bin/pbReader -binlog-file=${path}/binlog-0000000000000000 -``` - -## TiDB Binlog 监控 - -本部分主要介绍如何对 TiDB Binlog 的状态、性能做监控，并通过 Prometheus + Grafana 展现 metrics 数据。 - -### Pump/Drainer 配置 - -使用 Ansible 部署的 Pump 服务已经在启动参数设置 metrics。启动 Drainer 时可以设置以下两个参数： - -- `--metrics-addr`：设为 Push Gateway 的地址 -- `--metrics-interval`：设为 push 的频率，单位为秒，默认值为 15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号：admin，密码：admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 - - > **注意：** - > - > Type 选 Prometheus，URL 为 Prometheus 地址，根据实际情况添加/填写。 - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json)上传 -> 选择对应的 data source diff --git a/v2.1/reference/tidb-binlog/tidb-binlog-local.md b/v2.1/reference/tidb-binlog/tidb-binlog-local.md deleted file mode 100644 index f360804b98fe..000000000000 --- a/v2.1/reference/tidb-binlog/tidb-binlog-local.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: TiDB Binlog Local 部署方案 -category: reference -aliases: ['/docs-cn/v2.1/reference/tools/tidb-binlog/tidb-binlog-local/'] ---- - -# TiDB Binlog Local 部署方案 - -## TiDB Binlog Local 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -* **数据同步**：同步 TiDB 集群数据到其他数据库。 -* **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复。 - -## TiDB Binlog Local 架构 - -下图为 TiDB Binlog Local的整体架构。 - -![TiDB Binlog 架构](/media/architecture.jpeg) - -TiDB Binlog Local 主要分为两个组件： - -- **Pump** 是一个守护进程，在每个 TiDB 的主机上后台运行。他的主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入磁盘文件 - -- **Drainer** 从各个 Pump 节点收集 Binlog，并按照在 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件 - -## TiDB Binlog Local 安装 - -### TiDB Binlog Local 下载 - -TiDB Binlog 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v2.1/reference/tools/download.md)。 - -### TiDB Binlog Local 部署 - -#### 注意 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 方式的输出 binlog。 -* 手动部署时， 启动顺序为： Pump > TiDB，停止顺序为 TiDB > Pump - - 我们设置 TiDB 启动参数 binlog-socket 为对应的 Pump 的参数 socket 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* drainer 不支持对 ignore schemas（在过滤列表中的 schemas） 的 table 进行 rename DDL 操作 - -* 在已有的 TiDB 集群中启动 drainer，一般需要全量备份 并且获取 savepoint，然后导入全量备份，最后启动 drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 pump 运行 10 分钟左右后按顺序进行下面的操作 - - * 以 gen-savepoint model 运行 drainer 生成 drainer savepint 文件，`bin/drainer -gen-savepoint --data-dir= ${drainer_savepoint_dir} --pd-urls=${pd_urls}` - * 全量备份，例如 Mydumper 备份 tidb - * 全量导入备份到目标系统 - * 设置 savepoint 文件路径，然后启动 drainer，`bin/drainer --config=conf/drainer.toml --data-dir=${drainer_savepoint_dir}` - -* drainer 输出的 pb, 需要在配置文件设置下面的参数 - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -#### 使用 TiDB Ansible 部署 Pump (推荐) - -* 搭建全新的 TiDB Cluster，启动顺序 pd-server -> tikv-server -> pump -> tidb-server -> drainer - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook deploy.yml - * 执行 ansible-playbook start.yml - * drainer 目前需要手动部署 - -* 对已有的 TiDB Cluster 部署 binlog - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook rolling_update.yml --tags=tidb - * drainer 目前需要手动部署 - -#### 使用 Binary 部署 Pump - -1. PUMP 命令行参数说明 - - ``` - Usage of pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -advertise-addr string - pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -config string - 配置文件路径,如果你指定了配置文件，pump 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，pump 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - pump 数据存储位置路径 - -gc int - 日志最大保留天数 (默认 7)， 设置为 0 可永久保存 - -heartbeat-interval uint - pump 向 pd 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -socket string - unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - ``` - - 2. PUMP 配置文件 - - ```toml - # pump Configuration. - # pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - addr = "127.0.0.1:8250" - # pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - advertise-addr = "" - # binlog 最大保留天数 (默认 7)， 设置为 0 可永久保存 - gc = 7 - # pump 数据存储位置路径 - data-dir = "data.pump" - # pump 向 pd 发送心跳间隔 (单位 秒) - heartbeat-interval = 3 - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of drainer: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - drainer 提供服务的地址(默认 "127.0.0.1:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径, drainer 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 pd 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - -gen-savepoint - 如果设置为 true, 则只生成 drainer 的 savepoint meta 文件, 可以配合 Mydumper 使用 - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -txn-batch int - 输出到下游数据库一个事务的 sql 数量 (default 1) - ``` - -2. Drainer 配置文件 - - ```toml - # drainer Configuration. - - # drainer 提供服务的地址(默认 "127.0.0.1:8249") - addr = "127.0.0.1:8249" - - # 向 pd 查询在线 pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 sql 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - disable-dispatch = false - - # drainer 下游服务类型 (默认为 mysql) - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db priority over replicate-do-table if have same db name - # and we support regex expression , - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "127.0.0.1" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时,存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## TiDB Binlog Local 监控 - -这部分主要对 TiDB Binlog 的状态、性能做监控，通过 Prometheus + Grafana 展现 metrics 数据， - -### pump/drainer 配置 - -使用 ansible 部署的 pump 服务，已经在启动参数设置 metrics 。 - -drainer 启动时可以设置 `--metrics-addr` 和 `--metrics-interval` 两个参数，其中 metrics-addr 设为 Push Gateway 的地址，metrics-interval 为 push 的频率，单位为秒，默认值为15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号: admin 密码: admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 ( 注: Type 选 Prometheus，Url 为 Prometheus 地址，根据实际情况 添加/填写 ） - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/binlog.json)上传 -> 选择对应的 data source diff --git a/v2.1/reference/tidb-binlog/troubleshoot/binlog.md b/v2.1/reference/tidb-binlog/troubleshoot/binlog.md deleted file mode 100644 index a8d64cc4ae1c..000000000000 --- a/v2.1/reference/tidb-binlog/troubleshoot/binlog.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: TiDB Binlog 故障诊断 -category: reference -aliases: ['/docs-cn/v2.1/how-to/troubleshoot/tidb-binlog/'] ---- - -# TiDB Binlog 故障诊断 - -本文总结了在 TiDB Binlog 的使用过程中遇到问题的诊断流程，并指引用户通过监控、状态、日志等信息查找相应的解决方案。 - -如果你在使用 TiDB Binlog 时出现了异常，请尝试以下方式排查问题： - -1. 查看各个监控指标是否异常，参见[TiDB Binlog 集群监控](/v2.1/reference/tidb-binlog/monitor.md)。 - -2. 使用 [binlogctl 工具](/v2.1/reference/tidb-binlog/maintain.md#binlogctl-工具)查看各个 Pump、Drainer 的状态是否有异常。 - -3. 查看 Pump、Drainer 日志中是否有 `ERROR`、`WARN`，并根据详细的日志信息初步判断问题原因。 - -通过以上方式定位到问题后，在 [FAQ](/v2.1/reference/tidb-binlog/faq.md) 以及 [常见错误及修复](/v2.1/reference/tidb-binlog/troubleshoot/error-handling.md) 中查找解决方案，如果没有查找到解决方案或者提供的解决方案无法解决问题，请提交 [issue](https://github.com/pingcap/tidb-binlog/issues) 或者联系相关技术支持人员。 diff --git a/v2.1/reference/tidb-binlog/troubleshoot/error-handling.md b/v2.1/reference/tidb-binlog/troubleshoot/error-handling.md deleted file mode 100644 index cda558eaa739..000000000000 --- a/v2.1/reference/tidb-binlog/troubleshoot/error-handling.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB Binlog 常见错误修复 -category: reference ---- - -# TiDB Binlog 常见错误修复 - -本文档介绍 TiDB Binlog 中常见的错误以及修复方法。 - -## Drainer 同步数据到 Kafka 时报错 "kafka server: Message was too large, server rejected it to avoid allocation error" - -报错原因：如果在 TiDB 中执行了大事务，则生成的 binlog 数据会比较大，可能超过了 Kafka 的消息大小限制。 - -解决方法：需要调整 Kafka 的配置参数，如下所示。 - -``` -message.max.bytes=1073741824 -replica.fetch.max.bytes=1073741824 -fetch.message.max.bytes=1073741824 -``` - -## Pump 报错 "no space left on device" - -报错原因：本地磁盘空间不足，Pump 无法正常写 binlog 数据。 - -解决方法：需要清理磁盘空间，然后重启 Pump。 - -## Pump 启动时报错 "fail to notify all living drainer" - -报错原因：Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。 - -解决方法：可以使用 [binlogctl 工具](/v2.1/reference/tidb-binlog/maintain.md#binlogctl-工具)查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。 diff --git a/v2.1/reference/tidb-binlog/upgrade.md b/v2.1/reference/tidb-binlog/upgrade.md deleted file mode 100644 index 6d0fad2727eb..000000000000 --- a/v2.1/reference/tidb-binlog/upgrade.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: TiDB Binlog 版本升级方法 -category: reference -aliases: ['/docs-cn/v2.1/how-to/upgrade/tidb-binlog/','/docs-cn/v2.1/reference/tools/tidb-binlog/upgrade/'] ---- - -# TiDB Binlog 版本升级方法 - -如未特别指明，文中出现的 TiDB Binlog 均指最新的 [Cluster](/v2.1/reference/tidb-binlog/overview.md) 版本。 - -本文会分 Ansible 部署和手动部署两种情况介绍 TiDB Binlog 版本升级的方法，另外有一小节介绍如何从更早的不兼容版本（Kafka/Local 版本）升级到最新版本。 - -## Ansible 部署 - -本节适用于使用 [TiDB Ansible Playbook](https://github.com/pingcap/tidb-ansible) 部署的情况。 - -### 升级 Pump - -1. 将新版本的二进制文件 `pump` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook rolling_update.yml --tags=pump` 命令来滚动升级 Pump - -### 升级 Drainer - -1. 将新版本的二进制文件 `drainer` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook stop_drainer.yml --tags=drainer` 命令 -3. 执行 `ansible-playbook start_drainer.yml --tags=drainer` 命令 - -## 手动部署 - -### 升级 Pump - -对集群里的每个 Pump 逐一升级，确保集群中总有 Pump 可以接收 TiDB 发来的 Binlog。 - -1. 用新版本的 `pump` 替换原来的文件 -2. 重启 Pump 进程 - -### 升级 Drainer - -1. 用新版本的 `drainer` 替换原来的文件 -2. 重启 Drainer 进程 - -## 从 Kafka/Local 版本升级到 Cluster 版本 - -新版本的 TiDB（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）不兼容 [Kafka 版本](/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md)以及 [Local 版本](/v2.1/reference/tidb-binlog/tidb-binlog-local.md)的 TiDB Binlog，集群升级到新版本后只能使用 Cluster 版本的 TiDB Binlog。如果在升级前已经使用了 Kafka／Local 版本的 TiDB Binlog，必须将其升级到 Cluster 版本。 - -TiDB Binlog 版本与 TiDB 版本的对应关系如下： - -| TiDB Binlog 版本 | TiDB 版本 | 说明 | -|---|---|---| -| Local | TiDB 1.0 及更低版本 || -| Kafka | TiDB 1.0 ~ TiDB 2.1 RC5 | TiDB 1.0 支持 local 版本和 Kafka 版本的 TiDB Binlog。 | -| Cluster | TiDB v2.0.8-binlog，TiDB 2.1 RC5 及更高版本 | TiDB v2.0.8-binlog 是一个支持 Cluster 版本 TiDB Binlog 的 2.0 特殊版本。 | - -### 升级流程 - -> **注意：** -> -> 如果能接受重新导全量数据，则可以直接废弃老版本，按 [TiDB Binlog 集群部署](/v2.1/reference/tidb-binlog/deploy.md)中的步骤重新部署。 - -如果想从原来的 checkpoint 继续同步，使用以下升级流程： - -1. 部署新版本 Pump。 -2. 暂停 TiDB 集群业务。 -3. 更新 TiDB 以及配置，写 Binlog 到新的 Pump Cluster。 -4. TiDB 集群重新接入业务。 -5. 确认老版本的 Drainer 已经将老版本的 Pump 的数据完全同步到下游。 - - 查询 Drainer 的 `status` 接口，示例命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - curl 'http://172.16.10.49:8249/status' - ``` - - ``` - {"PumpPos":{"172.16.10.49:8250":{"offset":32686}},"Synced": true ,"DepositWindow":{"Upper":398907800202772481,"Lower":398907799455662081}} - ``` - - 如果返回的 `Synced` 为 true，则可以认为 Binlog 数据已经全部同步到了下游。 - -6. 启动新版本 Drainer； -7. 下线老版本的 Pump、Drainer 以及依赖的 Kafka 和 ZookeSeper。 diff --git a/v2.1/reference/tispark.md b/v2.1/reference/tispark.md deleted file mode 100644 index 5dc93118cd32..000000000000 --- a/v2.1/reference/tispark.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: TiSpark 用户指南 -category: reference ---- - -# TiSpark 用户指南 - -TiSpark 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。TiSpark 依赖于 TiKV 集群和 Placement Driver (PD)，也需要你搭建一个 Spark 集群。 - -本文简单介绍如何部署和使用 TiSpark。本文假设你对 Spark 有基本认知。你可以参阅 [Apache Spark 官网](https://spark.apache.org/docs/latest/index.html) 了解 Spark 的相关信息。 - -## 概述 - -TiSpark 是将 Spark SQL 直接运行在分布式存储引擎 TiKV 上的 OLAP 解决方案。其架构图如下： - -![TiSpark Architecture](/media/tispark-architecture.png) - -+ TiSpark 深度整合了 Spark Catalyst 引擎, 可以对计算提供精确的控制，使 Spark 能够高效的读取 TiKV 中的数据，提供索引支持以实现高速的点查。 -+ 通过多种计算下推减少 Spark SQL 需要处理的数据大小，以加速查询；利用 TiDB 的内建的统计信息选择更优的查询计划。 -+ 从数据集群的角度看，TiSpark + TiDB 可以让用户无需进行脆弱和难以维护的 ETL，直接在同一个平台进行事务和分析两种工作，简化了系统架构和运维。 -+ 除此之外，用户借助 TiSpark 项目可以在 TiDB 上使用 Spark 生态圈提供的多种工具进行数据处理。例如，使用 TiSpark 进行数据分析和 ETL；使用 TiKV 作为机器学习的数据源；借助调度系统产生定时报表等等。 - -## 环境准备 - -现有 TiSpark 2.x 版本支持 Spark 2.3.x，但并不支持 Spark 2.3.x 以外的版本。如果你希望使用 Spark 2.1.x 版本，需使用 TiSpark 1.x。 - -TiSpark 2.x 对于 Spark 2.3.x 的不同小版本做了些微的改动。默认的 TiSpark 支持 Spark 2.3.2，若希望使用 Spark 2.3.0 或者 Spark 2.3.1，则需要自行编译相关小版本的支持，以避免出现 API 的冲突。可以参见这个[文档](https://github.com/pingcap/tispark#how-to-build-from-sources)来获知如何从源码编译支持 Spark 2.3.x 的 TiSpark 。 - -TiSpark 需要 JDK 1.8+ 以及 Scala 2.11（Spark2.0+ 默认 Scala 版本）。 - -TiSpark 可以在 YARN，Mesos，Standalone 等任意 Spark 模式下运行。 - -## 推荐配置 - -本部分描述了 TiKV 与 TiSpark 集群分开部署、Spark 与 TiSpark 集群独立部署，以及TiSpark 与 TiKV 集群混合部署的建议配置。 - -### TiKV 与 TiSpark 集群分开部署的配置 - -对于 TiKV 与 TiSpark 分开部署的场景，可以参考如下建议配置： - -+ 硬件配置建议 - - 普通场景可以参考 [TiDB 和 TiKV 硬件配置建议](/v2.1/how-to/deploy/hardware-recommendations.md)，但是如果是偏重分析的场景，可以将 TiKV 节点增加到至少 64G 内存。 - -### Spark 与 TiSpark 集群独立部署的配置 - -关于 Spark 的详细硬件推荐配置请参考[官网](https://spark.apache.org/docs/latest/hardware-provisioning.html)，如下是 TiSpark 所需环境的简单描述： - -Spark 推荐 32G 内存以上的配额。请在配置中预留 25% 的内存给操作系统。 - -Spark 推荐每台计算节点配备 CPU 累计 8 到 16 核以上。你可以初始设定分配所有 CPU 核给 Spark。 - -Spark 的具体配置方式也请参考[官方说明](https://spark.apache.org/docs/latest/spark-standalone.html)。以下为根据 `spark-env.sh` 配置的范例： - -``` -SPARK_EXECUTOR_CORES: 5 -SPARK_EXECUTOR_MEMORY: 10g -SPARK_WORKER_CORES: 5 -SPARK_WORKER_MEMORY: 10g -``` - - 在 `spark-defaults.conf` 中，增加如下配置： - -``` -spark.tispark.pd.addresses $your_pd_servers -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - - `your_pd_servers` 是用逗号分隔的 PD 地址，每个地址使用 `地址:端口` 的格式。 - -例如你有一组 PD 在`10.16.20.1`，`10.16.20.2`，`10.16.20.3`，那么 PD 配置格式是`10.16.20.1:2379,10.16.20.2:2379,10.16.20.3:2379`。 - -### TiSpark 与 TiKV 集群混合部署的配置 - -对于 TiKV 与 TiSpark 混合部署的场景，需在原有 TiKV 预留资源之外累加 Spark 所需部分，并分配 25% 的内存作为系统本身占用。 - -## 部署 TiSpark - -TiSpark 的 jar 包可以在[这里](https://download.pingcap.org/tispark-latest-linux-amd64.tar.gz)下载，解压并拷贝到合适的目录。 - -### 已有 Spark 集群的部署方式 - -如果在已有 Spark 集群上运行 TiSpark，无需重启集群。可以使用 Spark 的 `--jars` 参数将 TiSpark 作为依赖引入： - -``` -spark-shell --jars $TISPARK_FOLDER/tispark-core-${version}-SNAPSHOT-jar-with-dependencies.jar -``` - -### 没有 Spark 集群的部署方式 - -如果没有使用中的 Spark 集群，推荐使用 Saprk Standalone 方式部署。这里简单介绍下 Standalone 部署方式。如果遇到问题，可以去官网寻求[帮助](https://spark.apache.org/docs/latest/spark-standalone.html)；也欢迎在我们的 GitHub 上提 [issue](https://github.com/pingcap/tispark/issues/new)。 - -#### 下载安装包并安装 - -你可以在 [Download Apache Spark™ 页面](https://spark.apache.org/downloads.html)下载 Apache Spark。 - -对于 Standalone 模式且无需 Hadoop 支持，则选择 Spark 2.3.x 且带有 Hadoop 依赖的 Pre-build with Apache Hadoop 2.x 任意版本。如有需要配合使用的 Hadoop 集群，则选择对应的 Hadoop 版本号。你也可以选择从源代码[自行构建](https://spark.apache.org/docs/2.3.0/building-spark.html)以配合官方 Hadoop 2.x 之前的版本。 - -如果你已经有了 Spark 二进制文件，并且当前 PATH 为 SPARKPATH，需将 TiSpark jar 包拷贝到 `${SPARKPATH}/jars` 目录下。 - -#### 启动 Master - -在选中的 Spark Master 节点执行如下命令： - -``` -cd $SPARKPATH -./sbin/start-master.sh -``` - -在这步完成以后，屏幕上会打印出一个 log 文件。检查 log 文件确认 Spark-Master 是否启动成功。你可以打开 查看集群信息（如果你没有改动 Spark-Master 默认 Port Numebr）。在启动 Spark-Slave 的时候，也可以通过这个面板来确认 Slave 是否已经加入集群。 - -#### 启动 Slave - -类似地，可以用如下命令启动 Spark-Slave 节点： - -```bash -./sbin/start-slave.sh spark://spark-master-hostname:7077 -``` - -命令返回以后，即可通过刚才的面板查看这个 Slave 是否已经正确地加入了 Spark 集群。在所有 Slave 节点重复刚才的命令。确认所有的 Slave 都可以正确连接 Master，这样你就拥有了一个 Standalone 模式的 Spark 集群。 - -#### Spark SQL shell 和 JDBC 服务器 - -当前版本的 TiSpark 可以直接使用 `spark-sql`和 Spark 的 ThriftServer JDBC 服务器。 - -## 一个使用范例 - -假设你已经按照上述步骤成功启动了 TiSpark 集群，下面简单介绍如何使用 Spark SQL 来做 OLAP 分析。这里我们用名为 tpch 数据库中的 lineitem 表作为范例。 - -假设你的 PD 节点位于 192.168.1.100，端口为 2379，在`$SPARK_HOME/conf/spark-defaults.conf`加入： - -``` -spark.tispark.pd.addresses 192.168.1.100:2379 -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -然后在 Spark-Shell 里像原生 Spark 一样输入下面的命令： - -```scala -spark.sql("use tpch") -spark.sql("select count(*) from lineitem").show -``` - -结果为： - -``` -+-------------+ -| Count (1) | -+-------------+ -| 600000000 | -+-------------+ -``` - -Spark SQL 交互 Shell 和原生 Spark 一致： - -```sh -spark-sql> use tpch; -Time taken: 0.015 seconds - -spark-sql> select count(*) from lineitem; -2000 -Time taken: 0.673 seconds, Fetched 1 row(s) -``` - -SQuirreLSQL 和 hive-beeline 可以使用 JDBC 连接 Thrift 服务器。 -例如，使用 beeline 连接： - -```sh -./beeline -Beeline version 1.2.2 by Apache Hive -beeline> !connect jdbc:hive2://localhost:10000 - -1: jdbc:hive2://localhost:10000> use testdb; -+---------+--+ -| Result | -+---------+--+ -+---------+--+ -No rows selected (0.013 seconds) - -select count(*) from account; -+-----------+--+ -| count(1) | -+-----------+--+ -| 1000000 | -+-----------+--+ -1 row selected (1.97 seconds) -``` - -## TiSparkR - -TiSparkR 是为兼容 SparkR 而开发的组件。具体使用请参考[这份文档](https://github.com/pingcap/tispark/blob/master/R/README.md)。 - -## TiSpark on PySpark - -TiSpark on PySpark 是为兼容 PySpark 而开发的组件。具体使用请参考[这份文档](https://github.com/pingcap/tispark/blob/master/python/README.md)。 - -## 和 Hive 一起使用 TiSpark - -TiSpark 可以和 Hive 混合使用。 -在启动 Spark 之前，需要添加 HADOOP_CONF_DIR 环境变量指向 Hadoop 配置目录并且将 `hive-site.xml` 拷贝到 `$SPARK_HOME/conf` 目录下。 - -``` -val tisparkDF = spark.sql("select * from tispark_table").toDF -tisparkDF.write.saveAsTable("hive_table") // save table to hive -spark.sql("select * from hive_table a, tispark_table b where a.col1 = b.col1").show // join table across Hive and Tispark -``` - -## 通过 JDBC 将 DataFrame 写入 TiDB - -暂时 TiSpark 不支持直接将数据写入 TiDB 集群，但可以使用 Spark 原生的 JDBC 支持进行写入： - -```scala -import org.apache.spark.sql.execution.datasources.jdbc.JDBCOptions - -val customer = spark.sql("select * from customer limit 100000") -// you might repartition source to make it balance across nodes -// and increase concurrency -val df = customer.repartition(32) -df.write -.mode(saveMode = "append") -.format("jdbc") -.option("driver", "com.mysql.jdbc.Driver") - // replace host and port as your and be sure to use rewrite batch -.option("url", "jdbc:mysql://127.0.0.1:4000/test?rewriteBatchedStatements=true") -.option("useSSL", "false") -// As tested, 150 is good practice -.option(JDBCOptions.JDBC_BATCH_INSERT_SIZE, 150) -.option("dbtable", s"cust_test_select") // database name and table name here -.option("isolationLevel", "NONE") // recommended to set isolationLevel to NONE if you have a large DF to load. -.option("user", "root") // TiDB user here -.save() -``` - -推荐将 `isolationLevel` 设置为 `NONE`，否则单一大事务有可能造成 TiDB 服务器内存溢出。 - -## 统计信息 - -TiSpark 可以使用 TiDB 的统计信息： - -1. 选择代价最低的索引或扫表访问 -2. 估算数据大小以决定是否进行广播优化 - -如果希望使用统计信息支持，需要确保所涉及的表已经被分析。请阅读[这份文档](https://pingcap.com/docs-cn/dev/reference/performance/statistics/)了解如何进行表分析。 - -从 TiSpark 2.0 开始，统计信息将会默认被读取。 - -统计信息将在 Spark Driver 进行缓存，请确定 Driver 内存足够缓存统计信息。 -可以在`spark-defaults.conf`中开启或关闭统计信息读取： - -| Property Name | Default | Description -| -------- | -----: | :----: | -| spark.tispark.statistics.auto_load | true | 是否默认进行统计信息读取 | - -## TiSpark FAQ - -- Q. 是独立部署还是和现有 Spark／Hadoop 集群共用资源？ - - A. 可以利用现有 Spark 集群无需单独部署，但是如果现有集群繁忙，TiSpark 将无法达到理想速度。 - -- Q. 是否可以和 TiKV 混合部署？ - - A. 如果 TiDB 以及 TiKV 负载较高且运行关键的线上任务，请考虑单独部署 TiSpark；并且考虑使用不同的网卡保证 OLTP 的网络资源不被侵占而影响线上业务。如果线上业务要求不高或者机器负载不大，可以考虑与 TiKV 混合部署。 - -- Q. Spark 执行中报 warning：WARN ObjectStore:568 - Failed to get database - - A. Warning 忽略即可，原因是 Spark 找不到对应的 hive 库，因为这个库是在 TIKV 中，而不是在 hive 中。可以考虑调整 [log4j 日志](https://github.com/pingcap/tidb-docker-compose/blob/master/tispark/conf/log4j.properties#L43)，将该参数添加到 spark 下 conf 里 log4j 文件(如果后缀是 template 那先 mv 成后缀 properties)。 - -- Q. Spark 执行中报 java.sql.BatchUpdateException: Data Truncated - - A. 写入的数据长度超过了数据库定义的数据类型的长度，可以确认 target table 的字段长度，进行调整。 - -- Q. TiSpark 任务是否默认读取 Hive 的元数据？ - - A. TiSpark 通过读取 hive-site 里的 meta 来搜寻 hive 的库。如果搜寻不到，就通过读取 tidb meta 搜寻 tidb 库。如果不需要该行为，可不在 hive site 中配置 hive 的 meta。 diff --git a/v2.1/reference/tools/data-migration/cluster-operations.md b/v2.1/reference/tools/data-migration/cluster-operations.md deleted file mode 100644 index 816cc68a150e..000000000000 --- a/v2.1/reference/tools/data-migration/cluster-operations.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -title: DM 集群操作 -category: reference ---- - -# DM 集群操作 - -本文介绍 DM 集群操作以及使用 DM-Ansible 管理 DM 集群时需要注意的事项。 - -## 启动集群 - -运行以下命令以启动整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -``` -$ ansible-playbook start.yml -``` - -## 下线集群 - -运行以下命令以下线整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -``` -$ ansible-playbook stop.yml -``` - -## 重启集群组件 - -在以下情况下，需要更新 DM 集群组件： - -- 您想要[更新组件版本](#更新组件版本)。 -- 发生了严重的错误，您需要重启组件完成临时恢复。 -- DM 集群所在的机器由于某种原因重启。 - -### 重启注意事项 - -该部分描述重启 DM 各组件时需要了解的事项。 - -#### DM-worker 重启事项 - -**全量数据导入过程中：** - -对于全量数据导入时的 SQL 文件，DM 使用下游数据库记录断点信息，DM-worker 会在本地 meta 文件记录子任务信息。DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -**增量数据同步过程中：** - -对于增量数据导入过程中的 binlog，DM 使用下游数据库记录断点信息，并会在同步任务开始或恢复后的第一个五分钟之内开启安全模式。 - -+ 未启用 sharding DDL 同步 - - 如果 DM-worker 上运行的任务未启用 sharding DDL 同步功能，DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -+ 已启用 sharding DDL 同步 - - - DM 同步 sharding DDL 语句时，如果 DM-worker 成功执行（或跳过）sharding DDL 的 binlog event，与 DM-worker 中的 sharding DDL 语句相关的所有表的断点信息都会被更新至 DDL 语句对应的 binlog event 之后的位置。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步开始前或完成后，DM-worker 会根据断点信息和本地记录的子任务信息自动恢复数据同步。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步过程中，可能会出现作为 DDL lock owner 的 DM-worker 实例已执行了 DDL 语句并成功变更了下游数据库表结构，但其他 DM-worker 实例重启而无法跳过 DDL 语句也无法更新断点的情况。 - - 此时 DM 会再次尝试同步这些未跳过执行的 DDL 语句。然而，由于未重启的 DM-worker 实例已经执行到了此 DDL 对应的 binlog event 之后，重启的 DM-worker 实例会被阻滞在重启前 DDL binlog event 对应的位置。 - - 要解决这个问题，请按照[手动处理 Sharding DDL Lock](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#场景二unlock-过程中部分-dm-worker-重启) 中描述的步骤操作。 - -**总结**：尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -#### DM-master 重启事项 - -由 DM-master 维护的信息包括以下两种。重启 DM-master 不会持久化保存这些信息的相关数据。 - -- 任务信息 -- Sharding DDL lock 信息 - -DM-master 重启时会自动向每个 DM-worker 实例请求任务信息，重建任务与 DM-worker 之间的对应关系，并从每个 DM-worker 实例获取 sharding DDL 信息。这样，就可以准确重建相应的 DDL lock，也可以自动解除 sharding DDL lock。 - -### 重启 DM-worker - -> **注意：** -> -> 尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -使用以下两种方法中任一种重启 DM-worker 组件： - -- 对 DM-worker 执行滚动升级。 - - ```bash - $ ansible-playbook rolling_update.yml --tags=dm-worker - ``` - -- 先停止 DM-worker，然后重启。 - - ```bash - $ ansible-playbook stop.yml --tags=dm-worker - $ ansible-playbook start.yml --tags=dm-worker - ``` - -### 重启 DM-master - -在以下两种方法中任选一种，重启 DM-master 组件： - -- 对 DM-master 执行滚动升级。 - - ```bash - $ ansible-playbook rolling_update.yml --tags=dm-master - ``` - -- 停止 DM-master，然后重启。 - - ```bash - $ ansible-playbook stop.yml --tags=dm-master - $ ansible-playbook start.yml --tags=dm-master - ``` - -## 更新组件版本 - -1. 下载 DM 二进制文件。 - - 1. 从 `downloads` 目录删除已有文件。 - - ``` - $ cd /home/tidb/dm-ansible - $ rm -rf downloads - ``` - - 2. 用 Playbook 下载 inventory.ini 文件中指定版本的最新 DM 二进制文件。这会自动替换 `/home/tidb/dm-ansible/resource/bin/` 中已有文件。 - - ``` - $ ansible-playbook local_prepare.yml - ``` - -2. 使用 Ansible 执行滚动升级。 - - 1. 对 DM-worker 实例执行滚动升级： - - ``` - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - - 2. 对 DM-master 实例执行滚动升级： - - ``` - ansible-playbook rolling_update.yml --tags=dm-master - ``` - - 3. 升级 dmctl： - - ``` - ansible-playbook rolling_update.yml --tags=dmctl - ``` - - 4. 对 DM-worker， DM-master， 以及 dmctl 整体执行滚动升级： - - ``` - ansible-playbook rolling_update.yml - ``` - -## 创建 DM-worker 实例 - -假设您想要在机器 `172.16.10.74` 上创建一个名为 `dm_worker3` 的 DM-worker 实例，按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v2.1/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 用户登录至中控机，并将 `172.16.10.74` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - ``` - $ cd /home/tidb/dm-ansible - $ vi hosts.ini - [servers] - 172.16.10.74 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.74`。 - - ``` - $ ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.74` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 修改 `inventory.ini` 文件，创建新 DM-worker 实例 `dm_worker3`。 - - ``` - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -3. 部署新 DM-worker 实例。 - - ``` - $ ansible-playbook deploy.yml --tags=dm-worker -l dm_worker3 - ``` - -4. 启用新 DM-worker 实例。 - - ``` - $ ansible-playbook start.yml --tags=dm-worker -l dm_worker3 - ``` - -5. 配置并重启 DM-master 服务。 - - ``` - $ ansible-playbook rolling_update.yml --tags=dm-master - ``` - -6. 配置并重启 Prometheus 服务。 - - ``` - $ ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 下线 DM-worker 实例 - -假设您想要下线的 DM-worker 实例为 `dm_worker3`。按以下步骤操作： - -1. 关闭您想要下线的 DM-worker 实例。 - - ``` - $ ansible-playbook stop.yml --tags=dm-worker -l dm_worker3 - ``` - -2. 修改 `inventory.ini` 文件，注释或删除 `dm_worker3` 实例所在行。 - - ``` - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - # dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 # Comment or delete this line - ``` - -3. 配置并重启 DM-master 服务。 - - ``` - $ ansible-playbook rolling_update.yml --tags=dm-master - ``` - -4. 配置并重启 Prometheus 服务。 - - ``` - $ ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 替换/迁移 DM-master 实例 - -假设机器 `172.16.10.71` 需要进行维护或者已崩溃，需要将 DM-master 实例从 `172.16.10.71` 迁移至 `172.16.10.80`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v2.1/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.80` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - ``` - $ cd /home/tidb/dm-ansible - $ vi hosts.ini - [servers] - 172.16.10.80 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.80`。 - - ``` - $ ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.80` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 关闭待替换的 DM-master 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - ``` - $ ansible-playbook stop.yml --tags=dm-master - ``` - -3. 修改 `inventory.ini` 文件。注释或删除待替换实例所在行，同时为新 DM-master 实例添加相关信息。 - - ```ini - [dm_master_servers] - # dm_master ansible_host=172.16.10.71 - dm_master ansible_host=172.16.10.80 - ``` - -4. 部署新 DM-master 实例。 - - ``` - $ ansible-playbook deploy.yml --tags=dm-master - ``` - -5. 启用新 DM-master 实例。 - - ``` - $ ansible-playbook start.yml --tags=dm-master - ``` - -6. 更新 dmctl 配置文件。 - - ``` - ansible-playbook rolling_update.yml --tags=dmctl - ``` - -## 替换/迁移 DM-worker 实例 - -假设机器 `172.16.10.72` 需要进行维护或者已崩溃，您需要将 `dm_worker1` 实例从 `172.16.10.72` 迁移至 `172.16.10.75`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v2.1/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.75` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - ``` - $ cd /home/tidb/dm-ansible - $ vi hosts.ini - [servers] - 172.16.10.75 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.85`。 - - ``` - $ ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.75` 上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 下线待替换 DM-worker 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - ``` - $ ansible-playbook stop.yml --tags=dm-worker -l dm_worker1 - ``` - -3. 修改 `inventory.ini` 文件，为新 DM-worker 实例添加相关信息。 - - 修改 `inventory.ini` 文件。注释或删除旧 `dm_worker1` 实例所在行；同时为新 `dm_worker1` 实例添加相关信息。 - - 如果希望从不同的 binlog position 或 GTID Sets 拉取 relay log，则也需要更新对应的 `{relay_binlog_name}` 或 `{relay_binlog_gtid}`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.75 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - # dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -4. 部署新 DM-worker 实例。 - - ``` - $ ansible-playbook deploy.yml --tags=dm-worker -l dm_worker1 - ``` - -5. 迁移 relay log 数据。 - - - 如果待替换 DM-worker 实例所在机器仍能访问，则可直接将该实例的 `{dm_worker_relay_dir}` 目录下的所有数据复制到新 DM-worker 实例的对应目录。 - - - 如果待替换 DM-worker 实例所在机器已无法访问，可能需在第 9 步中手动恢复 relay log 目录等信息。 - -6. 启动新 DM-worker 实例。 - - ```bash - $ ansible-playbook start.yml --tags=dm-worker -l dm_worker1 - ``` - -7. 配置并重启 DM-master 服务。 - - ```bash - $ ansible-playbook rolling_update.yml --tags=dm-master - ``` - -8. 配置并重启 Prometheus 服务。 - - ```bash - $ ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -9. 启动并验证数据迁移任务。 - - 使用 `start-task` 命令启动数据迁移任务，如果任务运行正常，则表示 DM-worker 迁移顺利完成；如果报类似如下错误，则需要对 relay log 目录进行手动修复。 - - ```log - fail to initial unit Sync of subtask test-task : UUID suffix 000002 with UUIDs [1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001] not found - ``` - - 如果待替换 DM-worker 所连接的上游 MySQL 已发生过切换，则会产生如上错误。此时可通过如下步骤手动修复： - - 1. 使用 `stop-task` 命令停止数据迁移任务。 - - 2. 通过 `$ ansible-playbook stop.yml --tags=dm-worker -l dm_worker1` 停止 DM-worker 实例。 - - 3. 更新 relay log 子目录的后缀，例如将 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 重命名为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 4. 更新 relay log 子目录索引文件 `server-uuid.index`，例如将其中的内容由 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 变更为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 5. 通过 `$ ansible-playbook start.yml --tags=dm-worker -l dm_worker1` 启动 DM-worker 实例。 - - 6. 再次启动并验证数据迁移任务。 diff --git a/v2.1/reference/tools/data-migration/configure/dm-master-configuration-file.md b/v2.1/reference/tools/data-migration/configure/dm-master-configuration-file.md deleted file mode 100644 index 6d01371b976b..000000000000 --- a/v2.1/reference/tools/data-migration/configure/dm-master-configuration-file.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: DM-master 配置文件介绍 -category: reference ---- - -# DM-master 配置文件介绍 - -本文介绍 DM-master 的配置文件，包括配置文件示例与配置项说明。 - -## 配置文件示例 - -DM-master 的示例配置文件如下所示： - -```toml -# log configuration -log-file = "dm-master.log" - -# DM-master listening address -master-addr = ":8261" - -# DM-worker deployment. It will be refined when the new deployment function is available. -[[deploy]] -source-id = "mysql-replica-01" -dm-worker = "172.16.10.72:8262" - -[[deploy]] -source-id = "mysql-replica-02" -dm-worker = "172.16.10.73:8262" -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置，日志会输出到标准输出中。 | -| `master-addr` | DM-master 服务的地址，可以省略 IP 信息，例如：":8261"。 | - -### DM-Worker 的配置 - -配置在 `deploy` 中，每一个 DM-worker 都需要设置一个 `deploy`。 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `source-id` | 一个 replication group 或者 MySQL/MariaDB 实例的标识，需要和 DM-worker 中的 `source-id` 一致。 | -| `dm-worker` | DM-worker 的服务地址。 | diff --git a/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md b/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md deleted file mode 100644 index 4b794e2f49f7..000000000000 --- a/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: DM-worker 完整配置说明 -category: reference ---- - -# DM-worker 完整配置说明 - -本文完整地介绍 DM-worker 的配置，包括配置文件示例与配置项说明。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker listening address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in the replication group should have a different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory used to store relay log. -relay-dir = "./relay_log" - -# Enables gtid in the relay log unit -enable-gtid = false - -relay-binlog-name = "" -relay-binlog-gtid = "" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 - -# Relay log purge strategy. -[purge] -interval = 3600 -expires = 24 -remain-space = 15 - -# Task status checker. -[checker] -check-enable = true -backoff-rollback = "5m" -backoff-max = "5m" -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-level` | 日志等级，值可以为 "debug"、"info"、"warn"、"error"、"fatal"，默认值为 "info"。一般情况下不需要手动配置，如果需要排查问题，可以将等级设置为 "debug"。 | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。 | -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中必须是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | -| `enable-gtid` | 是否使用 GTID 方式从上游拉取 binlog，默认值为 false。一般情况下不需要手动配置，如果上游数据库启用了 GTID 支持，且需要做主从切换，则将该配置项设置为 true。 | -| `relay-binlog-name` | 拉取上游 binlog 的起始文件名，例如 "mysql-bin.000002"，该配置在 `enable-gtid` 为 false 的情况下生效。如果不配置该项，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 | -| `relay-binlog-gtid` | 拉取上游 binlog 的起始 GTID，例如 "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"，该配置在 `enable-gtid` 为 true 的情况下生效。如果不配置该项，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog GTID 开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog GTID 开始拉取 binlog，一般情况下不需要手动配置。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。 | -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -### relay log 清理策略配置（purge 配置项） - -一般情况下不需要手动配置，如果 relay log 数据量较大，磁盘空间不足，则可以通过该配置项设置，避免 relay log 写满磁盘。 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `interval` | 定期检查 relay log 是否过期的间隔时间，默认值：3600，单位：秒。 | -| `expires` | relay log 的过期时间，默认值为 0，单位：小时。超过过期时间的 relay log 会被 DM 删除。如果不设置则 DM 不会自动清理过期的 relay log。 | -| `remain-space` | 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log，默认值：15，单位：GB。 | - -> **注意：** -> -> 仅在 `interval` 不为 0 且 `expires` 和 `remain-space` 两个配置项中至少有一个不为 0 的情况下 DM 的自动清理策略才会生效。 - -### 任务检查模块配置（checker 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `check-enable` | 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务，默认值：true。 | -| `backoff-rollback` | 任务检查模块中，定时调整恢复等待时间的间隔，默认值："5m0s"。 | -| `backoff-max` | 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔，默认值："5m0s"。 | - -> **注意：** -> -> 用户只需要通过配置 `check-enable` 开启或者关闭任务状态检查功能。对于 `backoff-rollback` 和 `backoff-max` 一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改这两项参数。 diff --git a/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md b/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md deleted file mode 100644 index c2532218fa5b..000000000000 --- a/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: DM-worker 配置文件介绍 -category: reference ---- - -# DM-worker 配置文件介绍 - -本文档主要介绍 DM-worker 的基础配置文件。在一般场景中，用户只需要使用基础配置即可完成 DM-worker 的部署。 - -完整配置项参考 [DM-worker 完整配置说明](/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-file = "dm-worker.log" - -# DM-worker listen address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in replication group should have different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory that used to store relay log. -relay-dir = "./relay_log" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。| -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。| -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -> **注意：** -> -> 以上配置为部署 DM-worker 的基础配置，一般情况下使用基础配置即可，更多配置项参考 [DM-worker 完整配置说明](/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 diff --git a/v2.1/reference/tools/data-migration/configure/overview.md b/v2.1/reference/tools/data-migration/configure/overview.md deleted file mode 100644 index ac49ee16036f..000000000000 --- a/v2.1/reference/tools/data-migration/configure/overview.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: DM 配置简介 -category: reference ---- - -# DM 配置简介 - -本文档简要介绍 DM (Data Migration) 的配置文件和数据同步任务的配置。 - -## 配置文件 - -- `inventory.ini`：使用 DM-Ansible 部署 DM 集群的配置文件。需要根据所选用的集群拓扑来进行编辑。详见[编辑 `inventory.ini` 配置文件](/v2.1/how-to/deploy/data-migration-with-ansible.md#第-7-步编辑-inventoryini-配置文件)。 -`dm-master.toml`：DM-master 进程的配置文件，包括 DM 集群的拓扑信息、MySQL 实例与 DM-worker 之间的关系（必须为一对一的关系）。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-master.toml` 文件，各项配置说明详见 [DM-master 配置文件介绍](/v2.1/reference/tools/data-migration/configure/dm-master-configuration-file.md) -- `dm-worker.toml`：DM-worker 进程的配置文件，包括上游 MySQL 实例的配置和 relay log 的配置。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-worker.toml` 文件，各项配置说明详见 [DM-worker 配置文件介绍](/v2.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - -## 同步任务配置 - -### 任务配置文件 - -使用 DM-Ansible 部署 DM 集群时，`/conf` 中提供了任务配置文件模板：`task.yaml.exmaple` 文件。该文件是 DM 同步任务配置的标准文件，每一个具体的任务对应一个 `task.yaml` 文件。关于该配置文件的详细介绍，参见 [任务配置文件](/v2.1/reference/tools/data-migration/configure/task-configuration-file.md)。 - -### 创建数据同步任务 - -你可以基于 `task.yaml.example` 文件来创建数据同步任务，具体步骤如下： - -1. 复制 `task.yaml.example` 为 `your_task.yaml`。 -2. 参考[任务配置文件](/v2.1/reference/tools/data-migration/configure/task-configuration-file.md)来修改 `your_task.yaml` 文件。 -3. [使用 dmctl 创建数据同步任务](/v2.1/reference/tools/data-migration/manage-tasks.md#创建数据同步任务)。 - -### 关键概念 - -DM 配置的关键概念如下： - -| 概念 | 解释 | 配置文件 | -| :------------ | :------------ | :------------------ | -| source-id | 唯一确定一个 MySQL 或 MariaDB 实例，或者一个具有主从结构的复制组，字符串长度不大于 32 | `inventory.ini` 的 `source_id`；
`dm-master.toml` 的 `source-id`；
`task.yaml` 的 `source-id` | -| DM-worker ID | 唯一确定一个 DM-worker（取值于 `dm-worker.toml` 的 `worker-addr` 参数） | `dm-worker.toml` 的 `worker-addr`；
dmctl 命令行的 `-worker` / `-w` flag | diff --git a/v2.1/reference/tools/data-migration/configure/task-configuration-file-full.md b/v2.1/reference/tools/data-migration/configure/task-configuration-file-full.md deleted file mode 100644 index 898461fccc71..000000000000 --- a/v2.1/reference/tools/data-migration/configure/task-configuration-file-full.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: DM 任务完整配置文件介绍 -category: reference ---- - -# DM 任务完整配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务完整的配置文件 [`task_advanced.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_advanced.yaml)，包含[全局配置](#全局配置) 和[实例配置](#实例配置) 两部分。 - -关于各配置项的功能和配置，请参阅[数据同步功能](/v2.1/reference/tools/data-migration/features/overview.md#同步功能介绍)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/v2.1/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 完整配置文件示例 - -下面是一个完整的配置文件示例，通过该示例可以完成复杂的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" -is-sharding: true # 是否为分库分表合并任务 -meta-schema: "dm_meta" # 下游储存 `meta` 信息的数据库 -remove-meta: false # 是否在任务同步开始前移除该任务名对应的 `meta`（`checkpoint` 和 `onlineddl` 等）。 -enable-heartbeat: false # 是否开启 `heartbeat` 功能 - -target-database: # 下游数据库实例配置 - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - - -## ******** 功能配置集 ********** - -routes: # 上游和下游表之间的路由 table routing 规则集 - route-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - target-schema: "test" # 目标库名称 - target-table: "t" # 目标表名称 - route-rule-2: - schema-pattern: "test_*" - target-schema: "test" - -filters: # 上游数据库实例匹配的表的 binlog event filter 规则集 - filter-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - events: ["truncate table", "drop table"] # 匹配哪些 event 类型 - action: Ignore # 对与符合匹配规则的 binlog 同步（Do）还是忽略(Ignore) - filter-rule-2: - schema-pattern: "test_*" - events: ["all dml"] - action: Do - -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 配置名称 - do-dbs: ["~^test.*", "user"] # 同步哪些库 - ignore-dbs: ["mysql", "account"] # 忽略哪些库 - do-tables: # 同步哪些表 - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "user" - tbl-name: "information" - ignore-tables: # 忽略哪些表 - - db-name: "user" - tbl-name: "log" - -mydumpers: # mydumper 处理单元运行配置参数 - global: # 配置名称 - mydumper-path: "./bin/mydumper" # mydumper binary 文件地址，默认值为 "./bin/mydumper" - threads: 4 # mydumper 从上游数据库实例导出数据的线程数量，默认值为 4 - chunk-filesize: 64 # mydumper 生成的数据文件大小，默认值为 64，单位为 MB - skip-tz-utc: true # 忽略对时间类型数据进行时区转化，默认值为 true - extra-args: "--no-locks" # mydumper 的其他参数，在 v1.0.2 版本中 DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置 - -loaders: # loader 处理单元运行配置参数 - global: # 配置名称 - pool-size: 16 # loader 并发执行 mydumper 的 SQL 文件的线程数量，默认值为 16 - dir: "./dumped_data" # loader 读取 mydumper 输出文件的地址，同实例对应的不同任务必须不同（mydumper 会根据这个地址输出 SQL 文件），默认值为 "./dumped_data" - -syncers: # syncer 处理单元运行配置参数 - global: # 配置名称 - worker-count: 16 # syncer 并发同步 binlog event 的线程数量，默认值为 16 - batch: 100 # syncer 同步到下游数据库的一个事务批次 SQL 语句数，默认值为 100 - -# ----------- 实例配置 ----------- -mysql-instances: - - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - meta: # `task-mode` 为 `incremental` 且下游数据库的 `checkpoint` 不存在时 binlog 同步开始的位置; 如果 checkpoint 存在，则以 `checkpoint` 为准 - binlog-name: binlog.000001 - binlog-pos: 4 - - route-rules: ["route-rule-1", "route-rule-2"] # 该上游数据库实例匹配的表到下游数据库的 table routing 规则名称 - filter-rules: ["filter-rule-1"] # 该上游数据库实例匹配的表的 binlog event filter 规则名称 - black-white-list: "bw-rule-1" # 该上游数据库实例匹配的表的 black & white list 过滤规则名称 - - mydumper-config-name: "global" # mydumper 配置名称 - loader-config-name: "global" # loader 配置名称 - syncer-config-name: "global" # Syncer 配置名称 - - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，等同于 mydumper 处理单元配置中的 `threads`，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，等同于 loader 处理单元配置中的 `pool-size`, 在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，等同于 syncer 处理单元配置中的 `worker-count`，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基本信息配置`和`实例配置`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。其中 `task-mode` 需要特殊说明： - -`task-mode` - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -全局配置主要包含下列功能配置集： - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `routes` | 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/v2.1/reference/tools/data-migration/features/overview.md#table-routing) | -| `filters` | 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) | -| `black-white-list` | 该上游数据库实例匹配的表的 black & white list 过滤规则集。建议通过该项指定需要同步的库和表，否则会同步所有的库和表。使用场景及示例配置参见 [Black & White Lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) | -| `mydumpers` | mydumper 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 | -| `loaders` | loader 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 | -| `syncers` | syncer 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 | - -各个功能配置集的参数及解释参见[完整配置文件示例](#完整配置文件示例)中的注释说明。 - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 - -在该项配置中设置数据同步子任务中各个功能对应的配置集中的配置名称，关于这些配置项的更多配置细节，参见[功能配置集](#功能配置集)的相关配置项，对应关系如下： - -| 配置项 | 相关配置项 | -| :------ | :------------------ | -| `route-rules` | `routes` | -| `filter-rules` | `filters` | -| `black-white-list` | `black-white-list` | -| `mydumper-config-name` | `mydumpers` | -| `loader-config-name` | `loaders` | -| `syncer-config-name` | `syncers` | diff --git a/v2.1/reference/tools/data-migration/configure/task-configuration-file.md b/v2.1/reference/tools/data-migration/configure/task-configuration-file.md deleted file mode 100644 index 2ac56871d510..000000000000 --- a/v2.1/reference/tools/data-migration/configure/task-configuration-file.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: DM 任务配置文件介绍 -category: reference ---- - -# DM 任务配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务基础配置文件 [`task_basic.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_basic.yaml)，包含[全局配置](#全局配置)和[实例配置](#实例配置)两部分。 - -完整的任务配置参见 [DM 任务完整配置文件介绍](/v2.1/reference/tools/data-migration/configure/task-configuration-file-full.md) - -关于各配置项的功能和配置，请参阅[数据同步功能](/v2.1/reference/tools/data-migration/features/overview.md)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/v2.1/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 基础配置文件示例 - -下面是一个基础的配置文件示例，通过该示例可以完成简单的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" - -target-database: # 下游数据库实例配置 - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - -## ******** 功能配置集 ********** -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 黑白名单配置的名称 - do-dbs: ["all_mode"] # 同步哪些库 - -# ----------- 实例配置 ----------- -mysql-instances: - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基础信息配置`和`功能配置集`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。关于 `task-mode` 的特殊说明如下： - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -对于一般的业务场景，只需要配置黑白名单过滤规则集，配置说明参见以上示例配置文件中 `black-white-list` 的注释以及 [Black & white table lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 -配置项说明参见以上示例配置文件中 `mysql-instances` 的注释。 diff --git a/v2.1/reference/tools/data-migration/deploy.md b/v2.1/reference/tools/data-migration/deploy.md deleted file mode 100644 index cb0625ea5bfb..000000000000 --- a/v2.1/reference/tools/data-migration/deploy.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: 使用 DM 同步数据 -category: reference ---- - -# 使用 DM 同步数据 - -本文介绍如何使用 DM (Data Migration) 同步数据。 - -## 第 1 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照 [使用 DM-Ansible 部署 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md)；也可以使用 binary 部署 DM 集群用于体验或者测试，具体部署方法参照[使用 DM binary 部署 DM 集群](/v2.1/how-to/deploy/data-migration-with-binary.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v2.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 2 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 MySQL-1 | 172.16.10.81 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 MySQL-2 | 172.16.10.82 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - - > **注意：** - > - > `{ansible deploy}/conf/dm-master.toml` 中的 `{ansible deploy}` 表示使用 DM-Ansible 部署 DM 时通过 `deploy_dir` 参数指定的目录。 - -## 第 3 步：配置任务 - -假设需要将 MySQL-1 和 MySQL-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - mydumper-path: "./bin/mydumper" # Mydumper 二进制文件的路径。 - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 4 步：启动任务 - -为了提前发现数据同步任务的一些配置错误，DM 中增加了[前置检查](/v2.1/reference/tools/data-migration/precheck.md)功能： - -- 启动数据同步任务时，DM 自动检查相应的权限和配置。 -- 也可使用 `check-task` 命令手动前置检查上游的 MySQL 实例配置是否符合 DM 的配置要求。 - -> **注意：** -> -> 第一次启动数据同步任务时，必须确保上游数据库已配置。否则，启动任务时会报错。 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/`。 - -2. 执行以下命令启动 dmctl。 - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 - - {{< copyable "" >}} - - ```bash - start-task ./task.yaml - ``` - - - 如果执行该命令后返回的结果如下，则表明任务已成功启动。 - - ```json - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.10.72:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.10.73:8262", - "msg": "" - } - ] - } - ``` - - - 如果任务启动失败，可根据返回结果的提示进行配置变更后执行 `start-task task.yaml` 命令重新启动任务。 - -## 第 5 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -```bash -query-status -``` - -## 第 6 步：停止任务 - -如果不再需要进行数据同步，可以在 dmctl 内使用以下命令停止同步任务： - -```bash -# 其中的 `test` 是 `task.yaml` 配置文件中 `name` 配置项设置的任务名。 -stop-task test -``` - -## 第 7 步：监控任务与查看日志 - -如果使用 DM-Ansible 部署 DM 集群时，正确部署了 Prometheus 与 Grafana，且 Grafana 的地址为 `172.16.10.71`，可在浏览器中打开 进入 Grafana，选择 DM 的 dashboard 即可查看 DM 相关监控项。 - -DM 在运行过程中，DM-worker, DM-master 及 dmctl 都会通过日志输出相关信息。各组件的日志目录如下： - -- DM-master 日志目录：通过 DM-master 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-master 节点的 `{ansible deploy}/log/dm-master.log`。 -- DM-worker 日志目录：通过 DM-worker 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-worker 节点的 `{ansible deploy}/log/dm-worker.log`。 -- dmctl 日志目录：与其二进制文件目录相同。 diff --git a/v2.1/reference/tools/data-migration/dm-portal.md b/v2.1/reference/tools/data-migration/dm-portal.md deleted file mode 100644 index 31dfa0156253..000000000000 --- a/v2.1/reference/tools/data-migration/dm-portal.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: DM Portal 简介 -category: reference ---- - -# DM Portal 简介 - -当前版本的 DM 提供了丰富多样的功能特性，包括 [Table routing](/v2.1/reference/tools/data-migration/features/overview.md#table-routing)，[Black & white table lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists)，[Binlog event filter](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 等。但这些功能特性同时也增加了用户使用 DM 的复杂度，尤其在编写 [DM 任务配置](/v2.1/reference/tools/data-migration/configure/task-configuration-file.md)的时候。 - -针对这个问题，DM 提供了一个精简的网页程序 DM Portal，能够帮助用户以可视化的方式去配置需要的同步任务，并且生成可以直接让 DM 直接执行的 `task.yaml` 文件。 - -## 功能描述 - -### 同步模式配置 - -支持 DM 的三种同步模式： - -- 全量同步 -- 增量同步 -- All（全量+增量） - -### 实例信息配置 - -支持配置库表同步路由方式，能够支持 DM 中分库分表合并的配置方式。 - -### binlog 过滤配置 - -支持对数据库、数据表配置 binlog event 过滤。 - -### 配置文件生成 - -支持配置文件创建，能够将配置文件下载到本地并且同时会在 dm-portal 服务器的 `/tmp/` 目录下自动创建。 - -### 使用限制 - -当前的 DM 配置可视化生成页面能够覆盖绝大部分的 DM 配置场景，但也有一定的使用限制： - -- 不支持 [Binlog event filter](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 的 SQL pattern 方式 -- 编辑功能不支持解析用户之前写的 `task.yaml` 文件，页面只能编辑由页面生成的 `task.yaml` 文件 -- 编辑功能不支持修改实例配置信息，如果用户需要调整实例配置，需要重新生成 `task.yaml` 文件 -- 页面的上游实例配置仅用于获取上游库表结构，DM-worker 里依旧需要配置对应的上游实例信息 -- 生成的 `task.yaml` 中，默认 mydumper-path 为 `./bin/mydumper`，如果实际使用其他路径，需要在生成的配置文件中进行手动修改。 - -## 部署使用 - -### Binary 部署 - -DM Portal 可以在 [dm-portal-latest-linux-amd64.tar.gz](https://download.pingcap.org/dm-portal-latest-linux-amd64.tar.gz) 下载，通过 `./dm-portal` 的命令即可直接启动。 - -* 如果在本地启动，浏览器访问 `127.0.0.1:8280` 即可使用。 -* 如果在服务器上启动，需要为服务器上配置访问代理。 - -### DM Ansible 部署 - -可以使用 DM Ansible 部署 DM Portal，具体部署方法参照[使用 DM Ansible 部署 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md)。 - -## 使用说明 - -### 新建规则 - -#### 功能描述 - -用于新建一个 `task.yaml` 文件，需要选择同步模式、配置上下游实例、配置库表路由，配置 binlog 过滤。 - -#### 操作步骤 - -登录 dm-portal 页面，点击**新建任务规则**。 - -### 基础信息配置 - -#### 功能描述 - -用于填写任务名称，以及选择任务类型。 - -#### 前置条件 - -已选择**新建同步规则**。 - -#### 操作步骤 - -1. 填写任务名称。 -2. 选择任务类型。 - -![DM Portal BasicConfig](/media/dm-portal-basicconfig.png) - -### 实例信息配置 - -#### 功能描述 - -用于配置上下游实例信息，包括 Host、Port、Username、Password。 - -#### 前置条件 - -已填写任务名称和选择任务类型。 - -#### 注意事项 - -如果任务类型选择**增量**或者 **All**，在配置上游实例信息时候，还需要配置 binlog-file 和 binlog-pos。 - -#### 操作步骤 - -1. 填写上游实例信息。 -2. 填写下游实例信息。 -3. 点击**下一步**。 - -![DM Portal InstanceConfig](/media/dm-portal-instanceconfig.png) - -### binlog 过滤配置 - -#### 功能描述 - -用于配置上游的 binlog 过滤，可以选择需要过滤的 DDL/DML，并且在数据库上配置的 filter 后会自动给其下的数据表继承。 - -#### 前置条件 - -已经配置好上下游实例信息并且连接验证没问题。 - -#### 注意事项 - -* binlog 过滤配置只能在上游实例处进行修改编辑，一旦数据库或者数据表被移动到下游实例后，就不可以进行修改编辑。 -* 在数据库上配置的 binlog 过滤会自动被其下的数据表继承。 - -#### 操作步骤 - -1. 点击需要配置的数据库或者数据表。 -2. 点击编辑按钮，选择需要过滤的 binlog 类型。 - -![DM Portal InstanceShow](/media/dm-portal-instanceshow.png) - -![DM Portal BinlogFilter 1](/media/dm-portal-binlogfilter-1.png) - -![DM Portal BinlogFilter 2](/media/dm-portal-binlogfilter-2.png) - -### 库表路由配置 - -#### 功能描述 - -可以选择需要同步的数据库和数据表，并且进行修改名称、合并库、合并表等操作。可以对上一步操作进行撤销，可以对库表路由配置进行全部重置。在完成任务配置后，DM Portal 会帮忙生成对应的 `task.yaml` 文件。 - -#### 前置条件 - -* 已经配置好需要的 binlog 过滤规则。 - -#### 注意事项 - -* 在合并库表操作的时候，不允许批量操作，只能逐一拖动。 -* 在合表库表操作的时候，只能对数据表进行拖动操作，不能对数据库进行数据库进行拖动操作。 - -#### 操作步骤 - -1. 在**上游实例**处，选择需要同步的数据库和数据表。 -2. 点击移动按钮，将需要同步的库表移动至**下游实例**处。 -3. 点击右键按钮，可以对库表进行改名操作。 -4. 选中需要操作的数据表，可以拖动至别的数据表图标上创建出合并表；可以拖动到数据库图标上移动至该库下；可以拖动到 target-instance 图标上移动到一个新的数据库下。 -5. 点击**完成**，自动下载 `task.yaml` 到本地，并且在 DM Portal 服务器上的 `/tmp/` 目录下自动创建一份 `task.yaml` 配置文件。 - -##### 移动同步库表 - -![DM Portal TableRoute 1](/media/dm-portal-tableroute-1.png) - -![DM Portal TableRoute 2](/media/dm-portal-tableroute-2.png) - -##### 右键修改库表名称 - -![DM Portal ChangeTableName](/media/dm-portal-changetablename.png) - -##### 合并数据表操作 - -![DM Portal MergeTable 1](/media/dm-portal-mergetable-1.png) - -![DM Portal MergeTable 2](/media/dm-portal-mergetable-2.png) - -##### 移动数据表至其他数据库 - -![DM Portal MoveToDB 1](/media/dm-portal-movetodb-1.png) - -![DM Portal MoveToDB 2](/media/dm-portal-movetodb-2.png) - -##### 移动数据表至新建默认数据库 - -![DM Portal MoveToNewDB 1](/media/dm-portal-movetonewdb-1.png) - -![DM Portal MoveToNewDB 2](/media/dm-portal-movetonewdb-2.png) - -##### 撤销本次操作 - -![DM Portal Revert](/media/dm-portal-revert.png) - -##### 清空下游实例 - -![DM Portal Reset](/media/dm-portal-reset.png) - -##### 完成并下载 - -![DM Portal GenerateConfig](/media/dm-portal-generateconfig.png) - -### 编辑规则 - -#### 功能描述 - -可以将之前创建的 `task.yaml` 上传后，解析出来之前的填写的配置信息，对部分配置进行修改。 - -#### 前置条件 - -* 已经创建出 `task.yaml` 文件。 -* 非 DM Portal 创建出来的 `task.yaml` 文件不可使用。 - -#### 注意事项 - -* 不允许修改实例配置信息 - -#### 操作步骤 - -1. 在首页，点击**编辑同步规则**。 -2. 选择上传 `task.yaml` 文件。 -3. 解析成功后，页面会自动跳转。 - -![DM Portal EditConfig](/media/dm-portal-editconfig.png) - -![DM Portal UploadConfig](/media/dm-portal-uploadconfig.png) diff --git a/v2.1/reference/tools/data-migration/dm-upgrade.md b/v2.1/reference/tools/data-migration/dm-upgrade.md deleted file mode 100644 index 0c517aa73424..000000000000 --- a/v2.1/reference/tools/data-migration/dm-upgrade.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: DM 版本升级 -category: reference ---- - -# DM 版本升级 - -本文档主要介绍 DM (Data Migration) 版本间的升级操作步骤。 - -> **注意：** -> -> - 若无特殊说明，各版本的升级操作均为从前一个有升级指引的版本向当前版本升级。 -> - 若无特殊说明，各升级操作示例均假定已经下载了对应版本的 DM 和 DM-Ansible 且 DM binary 存在于 DM-Ansible 的相应目录中（下载 DM binary 可以参考[更新组件版本](/v2.1/reference/tools/data-migration/cluster-operations.md#更新组件版本)）。 -> - 若无特殊说明，各升级操作示例均假定升级前已停止所有同步任务，升级完成后手动重新启动所有同步任务。 -> - 以下版本升级指引逆序展示。 - -## 升级到 v1.0.3 - -### 版本信息 - -```bash -Release Version: v1.0.3 -Git Commit Hash: 41426af6cffcff9a325697a3bdebeadc9baa8aa6 -Git Branch: release-1.0 -UTC Build Time: 2019-12-13 07:04:53 -Go Version: go version go1.13 linux/amd64 -``` - -### 主要变更 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.3` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.3 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.2 - -### 版本信息 - -```bash -Release Version: v1.0.2 -Git Commit Hash: affc6546c0d9810b0630e85502d60ed5c800bf25 -Git Branch: release-1.0 -UTC Build Time: 2019-10-30 05:08:50 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 支持自动为 DM-worker 生成部分配置项，减少人工配置成本 -- 支持自动生成 mydumper 库表参数，减少人工配置成本 -- 优化 `query-status` 默认输出，突出重点信息 -- 直接管理到下游的 DB 连接而不是使用内置连接池，优化 SQL 错误处理与重试 -- 修复 DM-worker 进程启动时、执行 DML 失败时可能 panic 的 bug -- 修复执行 sharding DDL（如 ADD INDEX）超时后可能造成后续 sharding DDL 无法正确协调的 bug -- 修复了有部分 DM-worker 不可访问时无法 `start-task` 的 bug -- 完善了对 1105 错误的自动重试策略 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.2` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.2 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.1 - -### 版本信息 - -```bash -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 修复某些情况下 DM 会频繁重建数据库连接的问题 -- 修复使用 `query-status` 时潜在的 panic 问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.1` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.1 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-10-geb2889c9 (1.0 GA) - -### 版本信息 - -```bash -Release Version: v1.0.0-10-geb2889c9 -Git Commit Hash: eb2889c9dcfbff6653be9c8720a32998b4627db9 -Git Branch: release-1.0 -UTC Build Time: 2019-09-06 03:18:48 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 常见的异常场景支持自动尝试恢复同步任务 -- 提升 DDL 语法兼容性 -- 修复上游数据库连接异常时可能丢失数据的 bug - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.0` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0 GA 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-rc.1-12-gaa39ff9 - -### 版本信息 - -```bash -Release Version: v1.0.0-rc.1-12-gaa39ff9 -Git Commit Hash: aa39ff981dfb3e8c0fa4180127246b253604cc34 -Git Branch: dm-master -UTC Build Time: 2019-07-24 02:26:08 -Go Version: go version go1.11.2 linux/amd64 -``` - -### 主要变更 - -从此版本开始，将对所有的配置进行严格检查，遇到无法识别的配置会报错，以确保用户始终准确地了解自己的配置。 - -### 升级操作示例 - -启动 DM-master 或 DM-worker 前，必须确保已经删除废弃的配置信息，且没有多余的配置项，否则会启动失败。可根据失败信息删除多余的配置。 -可能遗留的废弃配置： - -- `dm-worker.toml` 中的 `meta-file` -- `task.yaml` 中的 `mysql-instances` 中的 `server-id` diff --git a/v2.1/reference/tools/data-migration/dm-worker-intro.md b/v2.1/reference/tools/data-migration/dm-worker-intro.md deleted file mode 100644 index 71787b3b8b50..000000000000 --- a/v2.1/reference/tools/data-migration/dm-worker-intro.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: DM-worker 简介 -category: reference ---- - -# DM-worker 简介 - -DM-worker 是 DM (Data Migration) 的一个组件，负责执行具体的数据同步任务。 - -其主要功能如下： - -- 注册为一台 MySQL 或 MariaDB 服务器的 slave。 -- 读取 MySQL 或 MariaDB 的 binlog event，并将这些 event 持久化保存在本地 (relay log)。 -- 单个 DM-worker 支持同步一个 MySQL 或 MariaDB 实例的数据到下游的多个 TiDB 实例。 -- 多个 DM-Worker 支持同步多个 MySQL 或 MariaDB 实例的数据到下游的一个 TiDB 实例。 - -## DM-worker 处理单元 - -DM-worker 任务包含如下多个逻辑处理单元。 - -### Relay log - -Relay log 持久化保存从上游 MySQL 或 MariaDB 读取的 binlog，并对 binlog replication 处理单元提供读取 binlog event 的功能。 - -其原理和功能与 MySQL slave relay log 类似，详见 [Slave Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html)。 - -### Dumper - -Dumper 从上游 MySQL 或 MariaDB 导出全量数据到本地磁盘。 - -### Loader - -Loader 读取 dumper 处理单元的数据文件，然后加载到下游 TiDB。 - -### Binlog replication/Syncer - -Binlog replication/Syncer 读取 relay log 处理单元的 binlog event，将这些 event 转化为 SQL 语句，再将这些 SQL 语句应用到下游 TiDB。 - -## DM-worker 所需权限 - -本小节主要介绍使用 DM-worker 时所需的上下游数据库用户权限以及各处理单元所需的用户权限。 - -### 上游数据库用户权限 - -上游数据库 (MySQL/MariaDB) 用户必须拥有以下权限： - -| 权限 | 作用域 | -|:----|:----| -| `SELECT` | Tables | -| `RELOAD` | Global | -| `REPLICATION SLAVE` | Global | -| `REPLICATION CLIENT` | Global | - -如果要同步 `db1` 的数据到 TiDB，可执行如下的 `GRANT` 语句： - -```sql -GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_wildcard_of_host' -GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; -``` - -如果还要同步其他数据库的数据到 TiDB, 请确保已赋予这些库跟 `db1` 一样的权限。 - -### 下游数据库用户权限 - -下游数据库 (TiDB) 用户必须拥有以下权限： - -| 权限 | 作用域 | -|:----|:----| -| `SELECT` | Tables | -| `INSERT` | Tables | -| `UPDATE`| Tables | -| `DELETE` | Tables | -| `CREATE` | Databases，tables | -| `DROP` | Databases，tables | -| `ALTER` | Tables | -| `INDEX` | Tables | - -对要执行同步操作的数据库或表执行下面的 `GRANT` 语句： - -```sql -GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,INDEX ON db.table TO 'your_user'@'your_wildcard_of_host'; -``` - -### 处理单元所需的最小权限 - -| 处理单元 | 最小上游 (MySQL/MariaDB) 权限 | 最小下游 (TiDB) 权限 | 最小系统权限 | -|:----|:--------------------|:------------|:----| -| Relay log | `REPLICATION SLAVE` (读取 binlog）
`REPLICATION CLIENT` (`show master status`, `show slave status`) | 无 | 本地读/写磁盘 | -| Dumper | `SELECT`
`RELOAD`（获取读锁将表数据刷到磁盘，进行一些操作后，再释放读锁对表进行解锁）| 无 | 本地写磁盘 | -| Loader | 无 | `SELECT`（查询 checkpoint 历史）
`CREATE`（创建数据库或表）
`DELETE`（删除 checkpoint）
`INSERT`（插入 dump 数据）| 读/写本地文件 | -| Binlog replication | `REPLICATION SLAVE`（读 binlog）
`REPLICATION CLIENT` (`show master status`, `show slave status`) | `SELECT`（显示索引和列）
`INSERT` (DML)
`UPDATE` (DML)
`DELETE` (DML)
`CREATE`（创建数据库或表）
`DROP`（删除数据库或表）
`ALTER`（修改表）
`INDEX`（创建或删除索引）| 本地读/写磁盘 | - -> **注意：** -> -> 这些权限并非一成不变。随着需求改变，这些权限也可能会改变。 diff --git a/v2.1/reference/tools/data-migration/faq.md b/v2.1/reference/tools/data-migration/faq.md deleted file mode 100644 index d137abdf606c..000000000000 --- a/v2.1/reference/tools/data-migration/faq.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Data Migration 常见问题 -category: reference -aliases: ['/docs-cn/v2.1/faq/data-migration/'] ---- - -# Data Migration 常见问题 - -## DM 是否支持同步阿里 RDS 以及其他云数据库的数据？ - -DM 仅支持解析标准版本的 MySQL/MariaDB 的 binlog，对于阿里云 RDS 以及其他云数据库没有进行过测试，如果确认其 binlog 为标准格式，则可以支持。 - -## task 配置中的黑白名单的正则表达式是否支持`非获取匹配`（?!）？ - -目前不支持，DM 仅支持 golang 标准库的正则，可以通过 [re2-syntax](https://github.com/google/re2/wiki/Syntax) 了解 golang 支持的正则表达式。 - -## 如果在上游执行的一个 statement 包含多个 DDL 操作，DM 是否支持同步？ - -DM 会尝试将包含多个 DDL 变更操作的单条语句拆分成只包含一个 DDL 操作的多条语句，但是可能没有覆盖所有的场景。建议在上游执行的一条 statement 中只包含一个 DDL 操作，或者在测试环境中验证一下，如果不支持，可以给 DM 提 [issue](https://github.com/pingcap/dm/issues)。 - -## 如何处理不兼容的 DDL 语句？ - -你需要使用 dmctl 手动处理 TiDB 不兼容的 DDL 语句（包括手动跳过该 DDL 语句或使用用户指定的 DDL 语句替换原 DDL 语句，详见[跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句](/v2.1/reference/tools/data-migration/skip-replace-sqls.md)）。 - -> **注意：** -> -> TiDB 目前并不兼容 MySQL 支持的所有 DDL 语句。 - -## 如何重置数据同步任务？ - -在以下情况中，你需要重置整个数据同步任务： - -- 上游数据库中人为执行了 `RESET MASTER`，造成 relay log 同步出错 - -- relay log 或上游 binlog event 损坏或者丢失 - -此时，relay 处理单元通常会发生错误而退出，且无法优雅地自动恢复，因此需要通过手动方式恢复数据同步： - -1. 使用 `stop-task` 命令停止当前正在运行的所有同步任务。 - -2. 使用 Ansible [停止整个 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md#第-10-步关闭-dm-集群)。 - -3. 手动清理掉与 binlog event 被重置的 MySQL master 相对应的 DM-worker 的 relay log 目录。 - - - 如果是使用 Ansible 部署，relay log 目录即 `/relay_log` 目录。 - - 如果是使用二进制文件手动部署，relay log 目录即 relay-dir 参数设置的目录。 - -4. 清理掉下游已同步的数据。 - -5. 使用 Ansible [启动整个 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md#第-9-步部署-dm-集群)。 - -6. 以新的任务名重启数据同步任务，或设置 `remove-meta` 为 `true` 且 `task-mode` 为 `all`。 diff --git a/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md b/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md deleted file mode 100644 index 1ea6e043d757..000000000000 --- a/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md +++ /dev/null @@ -1,470 +0,0 @@ ---- -title: 手动处理 Sharding DDL Lock -category: reference ---- - -# 手动处理 Sharding DDL Lock - -DM (Data Migration) 使用 sharding DDL lock 来确保分库分表的 DDL 操作可以正确执行。绝大多数情况下，该锁定机制可自动完成；但在部分异常情况发生时，需要使用 `unlock-ddl-lock`/`break-ddl-lock` 手动处理异常的 DDL lock。 - -> **注意：** -> -> - 不要轻易使用 `unlock-ddl-lock`/`break-ddl-lock` 命令，除非完全明确当前场景下使用这些命令可能会造成的影响，并能接受这些影响。 -> - 在手动处理异常的 DDL lock 前，请确保已经了解 DM 的[分库分表合并同步原理](/v2.1/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)。 - -## 命令介绍 - -### `show-ddl-locks` - -该命令用于查询当前 DM-master 上存在的 DDL lock 信息。 - -#### 命令示例 - -```bash -show-ddl-locks [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，查询所有 DM-worker 相关的 lock 信息；指定时，仅查询与这组 DM-worker 相关的 lock 信息，可重复多次指定 - -+ `task-name`： - - 非 flag 参数，string，可选 - - 不指定时，查询与所有任务相关的 lock 信息；指定时，仅查询特定任务相关的 lock 信息 - -#### 返回结果示例 - -```bash -» show-ddl-locks test -{ - "result": true, # 查询 lock 操作本身是否成功 - "msg": "", # 查询 lock 操作失败时的原因或其它描述信息（如不存在任务 lock） - "locks": [ # DM-master 上存在的 lock 信息列表 - { - "ID": "test-`shard_db`.`shard_table`", # lock 的 ID 标识，当前由任务名与 DDL 对应的 schema/table 信息组成 - "task": "test", # lock 所属的任务名 - "owner": "127.0.0.1:8262", # lock 的 owner（第一个遇到该 DDL 的 DM-worker） - "DDLs": [ # lock 对应的 DDL 列表 - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;" - ], - "synced": [ # 已经收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8262" - ], - "unsynced": [ # 尚未收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8263" - ] - } - ] -} -``` - -### `unlock-ddl-lock` - -该命令用于主动请求 DM-master 解除指定的 DDL lock，包括的操作：请求 owner 执行 DDL 操作，请求其他非 owner 的 DM-worker 跳过 DDL 操作，移除 DM-master 上的 lock 信息。 - -#### 命令示例 - -```bash -unlock-ddl-lock [--worker=127.0.0.1:8262] [--owner] [--force-remove] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，对所有已经在等待该 lock 的 DM-worker 发起跳过 DDL 操作请求；指定时，仅对这组 DM-worker 发起跳过 DDL 操作请求，可重复多次指定 - -+ `owner`： - - flag 参数，string，`--owner`，可选 - - 不指定时，请求默认的 owner（`show-ddl-locks` 返回结果中的 `owner`）执行 DDL 操作；指定时，请求该 DM-worker（替代默认的 owner）执行 DDL 操作 - -+ `force-remove`： - - flag 参数，boolean，`--force-remove`，可选 - - 不指定时，仅在 owner 执行 DDL 成功时移除 lock 信息；指定时，即使 owner 执行 DDL 失败也强制移除 lock 信息（此后将无法再次查询或操作该 lock） - -+ `lock-ID`： - - 非 flag 参数，string，必选 - - 指定需要执行 unlock 操作的 DDL lock ID（即 `show-ddl-locks` 返回结果中的 `ID`） - -#### 返回结果示例 - -```bash -» unlock-ddl-lock test-`shard_db`.`shard_table` -{ - "result": true, # unlock lock 操作是否成功 - "msg": "", # unlock lock 操作失败时的原因 - "workers": [ # 各 DM-worker 执行/跳过 DDL 操作结果信息列表 - { - "result": true, # 该 DM-worker 执行/跳过 DDL 操作是否成功 - "worker": "127.0.0.1:8262", # DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker 执行/跳过 DDL 失败时的原因 - } - ] -} -``` - -### break-ddl-lock - -该命令用于主动请求 DM-worker 强制打破当前正在等待 unlock 的 DDL lock，包括请求 DM-worker 执行或跳过 DDL 操作、移除该 DM-worker 上的 DDL lock 信息。 - -#### 命令示例 - -```bash -break-ddl-lock <--worker=127.0.0.1:8262> [--remove-id] [--exec] [--skip] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，必选 - - 指定需要执行 break 操作的 DM-worker - -+ `remove-id`：已废弃 - -+ `exec`： - - flag 参数，boolean，`--exec`，可选 - - 不可与 `--skip` 参数同时指定 - - 指定时，请求该 DM-worker 执行（execute）当前 lock 对应的 DDL - -+ `skip`： - - flag 参数，boolean，`--skip`，可选 - - 不可与 `--exec` 参数同时指定 - - 指定时，请求该 DM-worker 跳过（skip）当前 lock 对应的 DDL - -+ `task-name`： - - 非 flag 参数，string，必选 - - 指定要执行 break 操作的 lock 所在的 task 名称（要查看各 task 上是否存在 lock，可通过 [query-status](/v2.1/reference/tools/data-migration/query-status.md) 获得） - -#### 返回结果示例 - -```bash -» break-ddl-lock -w 127.0.0.1:8262 --exec test -{ - "result": true, # break lock 操作是否成功 - "msg": "", # break lock 操作失败时的原因 - "workers": [ # 执行 break lock 操作的 DM-worker 列表（当前单次操作仅支持对一个 DM-worker 执行 break lock） - { - "result": false, # 该 DM-worker break lock 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker break lock 失败时的原因 - } - ] -} -``` - -## 支持场景 - -目前，使用 `unlock-ddl-lock`/`break-ddl-lock` 命令仅支持处理以下三种 sharding DDL lock 异常情况。 - -### 场景一：部分 DM-worker 下线 - -#### Lock 异常原因 - -在 DM-master 尝试自动 unlock sharding DDL lock 之前，需要等待所有 DM-worker 的 sharding DDL events 全部到达（详见[分库分表合并同步原理](/v2.1/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)）。如果 sharding DDL 已经在同步过程中，且有部分 DM-worker 下线，并且不再计划重启它们（按业务需求移除了这部分 DM-worker），则会由于永远无法等齐所有的 DDL 而造成 lock 无法自动 unlock。 - -#### 手动处理示例 - -假设上游有 MySQL-1 和 MySQL-2 两个实例，其中 MySQL-1 中有 `shard_db_1`.`shard_table_1` 和 `shard_db_1`.`shard_table_2` 两个表，MySQL-2 中有 `shard_db_2`.`shard_table_1` 和 `shard_db_2`.`shard_table_2` 两个表。现在需要将这 4 个表合并后同步到下游 TiDB 的 `shard_db`.`shard_table` 表中。 - -初始表结构如下： - -```sql -mysql> SHOW CREATE TABLE shard_db_1.shard_table_1; -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -上游分表将执行以下 DDL 语句变更表结构： - -```sql -ALTER TABLE shard_db_*.shard_table_* ADD COLUMN c2 INT; -``` - -MySQL 及 DM 操作与处理流程如下： - -1. MySQL-1 对应的 DM-worker-1 的两个分表执行了对应的 DDL 操作进行表结构变更。 - - ```sql - ALTER TABLE shard_db_1.shard_table_1 ADD COLUMN c2 INT; - ``` - - ```sql - ALTER TABLE shard_db_1.shard_table_2 ADD COLUMN c2 INT; - ``` - -2. DM-worker-1 接受到两个分表的 DDL 之后，将对应 MySQL-1 相关的 DDL 信息发送给 DM-master，DM-master 创建相应的 DDL lock。 -3. 使用 `show-ddl-lock` 查看当前的 DDL lock 信息。 - - ```bash - » show-ddl-locks test - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8262", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8262" - ], - "unsynced": [ - "127.0.0.1:8263" - ] - } - ] - } - ``` - -4. 由于业务需要，DM-worker-2 对应的 MySQL-2 的数据不再需要同步到下游 TiDB，对 DM-worker-2 执行了下线处理。 -5. DM-master 上 ID 为 ```test-`shard_db`.`shard_table` ``` 的 lock 无法等到 DM-worker-2 的 DDL 操作信息。 - - `show-ddl-locks` 返回的 `unsynced` 中一直包含 DM-worker-2 的信息（`127.0.0.1:8263`）。 - -6. 使用 `unlock-dll-lock` 来请求 DM-master 主动 unlock 该 DDL lock。 - - - 如果 DDL lock 的 owner 也已经下线，可以使用 `--owner` 参数指定其他 DM-worker 作为新 owner 来执行 DDL。 - - 当存在任意 DM-worker 报错时，`result` 将为 `false`，此时请仔细检查各 DM-worker 的错误是否是预期可接受的。 - - 已下线的 DM-worker 会返回 `rpc error: code = Unavailable` 错误属于预期行为，可以忽略。 - - 如果其它未下线的 DM-worker 返回错误，则需要根据情况额外处理。 - - ```bash - » unlock-ddl-lock test-`shard_db`.`shard_table` - { - "result": false, - "msg": "github.com/pingcap/tidb-enterprise-tools/dm/master/server.go:1472: DDL lock test-`shard_db`.`shard_table` owner ExecuteDDL successfully, so DDL lock removed. but some dm-workers ExecuteDDL fail, you should to handle dm-worker directly", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": false, - "worker": "127.0.0.1:8263", - "msg": "rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = \"transport: Error while dialing dial tcp 127.0.0.1:8263: connect: connection refused\"" - } - ] - } - ``` - -7. 使用 `show-dd-locks` 确认 DDL lock 是否被成功 unlock。 - - ```bash - » show-ddl-locks test - { - "result": true, - "msg": "no DDL lock exists", - "locks": [ - ] - } - ``` - -8. 查看下游 TiDB 中的表结构是否变更成功。 - - ```sql - mysql> SHOW CREATE TABLE shard_db.shard_table; - +-------------+--------------------------------------------------+ - | Table | Create Table | - +-------------+--------------------------------------------------+ - | shard_table | CREATE TABLE `shard_table` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 COLLATE=latin1_bin | - +-------------+--------------------------------------------------+ - ``` - -9. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -使用 `unlock-ddl-lock` 手动执行 unlock 操作后，由于该任务的配置信息中仍然包含了已下线的 DM-worker，如果不进行处理，则当下次 sharding DDL 到达时，仍会出现 lock 无法自动完成同步的情况。 - -因此，在手动解锁 DDL lock 后，需要再执行以下操作： - -1. 使用 `stop-task` 停止运行中的任务。 -2. 更新任务配置文件，将已下线 DM-worker 对应的信息从配置文件中移除。 -3. 使用 `start-task` 及新任务配置文件重新启动任务。 - -> **注意：** -> -> 在 `unlock-ddl-lock` 之后，如果已下线的 DM-worker 重新上线并尝试对其中的分表进行数据同步，则会由于数据与下游的表结构不匹配而发生错误。 - -### 场景二：unlock 过程中部分 DM-worker 重启 - -#### Lock 异常原因 - -在 DM-master 收到所有 DM-worker 的 DDL 信息后，执行自动 unlock DDL lock 的操作主要包括以下步骤： - -1. 请求 lock owner 执行 DDL 操作，并更新对应分表的 checkpoint。 -2. 在 owner 执行 DDL 操作成功后，移除 DM-master 上保存的 DDL lock 信息。 -3. 在 owner 执行 DDL 操作成功后，请求其他所有 DM-worker 跳过 DDL 操作并更新对应分表的 checkpoint。 - -上述 unlock DDL lock 的操作不是原子的，当 owner 执行 DDL 操作成功后，请求其他 DM-worker 跳过 DDL 操作时，如果该 DM-worker 发生了重启，则会造成该 DM-worker 跳过 DDL 操作失败。 - -此时 DM-master 上的 lock 信息被移除，但该 DM-worker 重启后将尝试继续重新同步该 DDL 操作。但是，由于其他 DM-worker（包括原 owner）已经同步完该 DDL 操作，并已经在继续后续的同步，该 DM-worker 将永远无法等待该 DDL 操作对应 lock 的自动 unlock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -当在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息；但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于 DM-worker-2 发生了重启而跳过 DDL 操作失败。 - -DM-worker-2 重启后，将尝试重新同步重启前已经在等待的 DDL lock。此时将在 DM-master 上创建一个新的 lock，并且该 DM-worker 将成为 lock 的 owner（其他 DM-worker 此时已经执行或跳过 DDL 操作并在进行后续同步）。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上存在该 DDL 操作对应的 lock。 - - 应该仅有该重启的 DM-worker（`127.0.0.1:8263`）处于 `syned` 状态： - - ```bash - » show-ddl-locks - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8263", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8263" - ], - "unsynced": [ - "127.0.0.1:8262" - ] - } - ] - } - ``` - -2. 使用 `unlock-ddl-lock` 请求 DM-master unlock 该 lock。 - - - 使用 `--worker` 参数限定操作仅针对该重启的 DM-worker（`127.0.0.1:8263`）。 - - Lock 过程中该 DM-worker 会尝试再次向下游执行该 DDL 操作（重启前的原 owner 已向下游执行过该 DDL 操作），需要确保该 DDL 操作可被多次执行。 - - ```bash - » unlock-ddl-lock --worker=127.0.0.1:8263 test-`shard_db`.`shard_table` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -3. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 -4. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -手动 unlock sharding DDL lock 后，后续的 sharding DDL 将可以自动正常同步。 - -### 场景三：unlock 过程中部分 DM-worker 临时不可达 - -#### Lock 异常原因 - -与 [unlock 过程中部分 DM-worker 重启](#场景二unlock-过程中部分-dm-worker-重启) 造成 lock 异常的原因类似。当请求 DM-worker 跳过 DDL 操作时，如果该 DM-worker 临时不可达，则会造成该 DM-worker 跳过 DDL 操作失败。此时 DM-master 上的 lock 信息被移除，但该 DM-worker 将处于等待一个不再存在的 DDL lock 的状态。 - -场景三与[场景二](#场景二unlock-过程中部分-dm-worker-重启)的区别在于，场景三中 DM-master 没有 lock，而场景二中 DM-master 有一个新的 lock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息，但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于网络原因等临时不可达而跳过 DDL 操作失败。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上不再存在该 DDL 操作对应的 lock。 -2. 使用 `query-status` 确认 DM-worker 仍在等待 lock 同步。 - - ```bash - » query-status test - { - "result": true, - "msg": "", - "workers": [ - ... - { - ... - "worker": "127.0.0.1:8263", - "subTaskStatus": [ - { - ... - "unresolvedDDLLockID": "test-`shard_db`.`shard_table`", - "sync": { - ... - "blockingDDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "unresolvedGroups": [ - { - "target": "`shard_db`.`shard_table`", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "firstPos": "(mysql-bin|000001.000003, 1752)", - "synced": [ - "`shard_db_2`.`shard_table_1`", - "`shard_db_2`.`shard_table_2`" - ], - "unsynced": [ - ] - } - ], - "synced": false - } - } - ] - ... - } - ] - } - ``` - -3. 使用 `break-ddl-lock` 请求强制 break 该 DM-worker 当前正在等待的 DDL lock。 - - 由于 owner 已经向下游执行了 DDL 操作，因此在 break 时使用 `--skip` 参数。 - - ```bash - » break-ddl-lock --worker=127.0.0.1:8263 --skip test - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -4. 使用 `query-status` 确认同步任务是否正常且不再处于等待 lock 的状态。 - -#### 手动处理后的影响 - -手动强制 break lock 后，后续 sharding DDL 将可以自动正常同步。 diff --git a/v2.1/reference/tools/data-migration/features/overview.md b/v2.1/reference/tools/data-migration/features/overview.md deleted file mode 100644 index 0cfa06ea40e7..000000000000 --- a/v2.1/reference/tools/data-migration/features/overview.md +++ /dev/null @@ -1,503 +0,0 @@ ---- -title: 数据同步功能 -summary: DM 提供的功能及其配置介绍 -category: reference ---- - -# 数据同步功能 - -本文将详细介绍 DM 提供的数据同步功能，以及相关的配置选项。 - -## Table routing - -Table routing 提供将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的功能。 - -> **注意：** -> -> - 不支持对同一个表设置多个不同的路由规则。 -> - Schema 的匹配规则需要单独设置，用来同步 `create/drop schema xx`，例如下面[参数配置](#参数配置)中的 rule-2。 - -### 参数配置 - -```yaml -routes: - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -### 参数解释 - -将根据 [`schema-pattern`/`table-pattern`](/v2.1/reference/tools/data-migration/table-selector.md) 匹配上该规则的上游 MySQL/MariaDB 实例的表同步到下游的 `target-schema`/`target-table`。 - -### 使用示例 - -下面展示了三个不同场景下的配置示例。 - -#### 分库分表合并 - -假设存在分库分表场景，需要将上游两个 MySQL 实例的表 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的一张表 `test`.`t`。 - -为了同步到下游实例的表 `test`.`t` 需要创建两个 table routing 规则： - -- `rule-1` 用来同步匹配上 `schema-pattern: "test_*"` 和 `table-pattern: "t_*"` 的表的 DML/DDL 语句到下游的 `test`.`t`。 -- `rule-2` 用来同步匹配上 `schema-pattern: "test_*"` 的库的 DDL 语句，例如 `create/drop schema xx`。 - -> **注意：** -> -> - 如果下游 TiDB `schema: test` 已经存在， 并且不会被删除，则可以省略 `rule-2`。 -> - 如果下游 TiDB `schema: test` 不存在，只设置了 `rule_1`，则同步会报错 `schema test doesn't exist`。 - -```yaml - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 分库合并 - -假设存在分库场景，将上游两个 MySQL 实例 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t_{1,2,3...}`，创建一条路由规则即可： - -```yaml - rule-1: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 错误的 table routing - -假设存在下面两个路由规则，`test_1_bak`.`t_1_bak` 可以匹配上 `rule-1` 和 `rule-2`，违反 table 路由的限制而报错。 - -```yaml - rule-0: - schema-pattern: "test_*" - target-schema: "test" - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_1_bak" - table-pattern: "t_1_bak" - target-schema: "test" - target-table: "t_bak" -``` - -## Black & white table lists - -上游数据库实例表的黑白名单过滤规则，可以用来过滤或者只同步某些 `database/table` 的所有操作。 - -### 参数配置 - -```yaml -black-white-list: - rule-1: - do-dbs: ["~^test.*"] # 以 ~ 字符开头，表示规则是正则表达式 -​ ignore-dbs: ["mysql"] - do-tables: - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "test" - tbl-name: "t" - ignore-tables: - - db-name: "test" - tbl-name: "log" -``` - -### 参数解释 - -- `do-dbs`：要同步的库的白名单，类似于 MySQL 中的 [`replicate-do-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-db)。 -- `ignore-dbs`：要同步的库的黑名单，类似于 MySQL 中的 [`replicate-ignore-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-db)。 -- `do-tables`：要同步的表的白名单，类似于 MySQL 中的 [`replicate-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-table)。 -- `ignore-tables`：要同步的表的黑名单，类似于 MySQL 中的 [`replicate-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-table)。 - -以上参数值以 `~` 开头时均支持使用[正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)来匹配库名、表名。 - -### 过滤规则 - -`do-dbs` 与 `ignore-dbs` 对应的过滤规则与 MySQL 中的 [Evaluation of Database-Level Replication and Binary Logging Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-db-options.html) 类似，`do-tables` 与 `ignore-tables` 对应的过滤规则与 MySQL 中的 [Evaluation of Table-Level Replication Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-table-options.html) 类似。 - -> **注意：** -> -> DM 中黑白名单过滤规则与 MySQL 中相应规则存在以下区别： -> -> - MySQL 中存在 [`replicate-wild-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-do-table) 与 [`replicate-wild-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-ignore-table) 用于支持通配符，DM 中各配置参数直接支持以 `~` 字符开头的正则表达式。 -> - DM 当前只支持 `ROW` 格式的 binlog，不支持 `STATEMENT`/`MIXED` 格式的 binlog，因此应与 MySQL 中 `ROW` 格式下的规则对应。 -> - 对于 DDL，MySQL 仅依据默认的 database 名称（`USE` 语句显式指定的 database）进行判断，而 DM 优先依据 DDL 中的 database 名称部分进行判断，并当 DDL 中不包含 database 名称时再依据 `USE` 部分进行判断。假设需要判断的 SQL 为 `USE test_db_2; CREATE TABLE test_db_1.test_table (c1 INT PRIMARY KEY)`，且 MySQL 配置了 `replicate-do-db=test_db_1`、DM 配置了 `do-dbs: ["test_db_1"]`，则对于 MySQL 该规则不会生效，而对于 DM 该规则会生效。 - -判断 table `test`.`t` 是否应该被过滤的过滤流程如下： - -1. 首先 **schema 过滤判断** - - - 如果 `do-dbs` 不为空，判断 `do-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则进入 **table 过滤判断**。 - - 如果不存在，则过滤 `test`.`t`。 - - - 如果 `do-dbs` 为空并且 `ignore-dbs` 不为空，判断 `ignore-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则过滤 `test`.`t`。 - - 如果不存在，则进入 **table 过滤判断**。 - - - 如果 `do-dbs` 和 `ignore-dbs` 都为空，则进入 **table 过滤判断**。 - -2. 进行 **table 过滤判断** - - 1. 如果 `do-tables` 不为空，判断 `do-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则同步 `test`.`t`。 - - 如果不存在，则过滤 `test`.`t`。 - - 2. 如果 `ignore-tables` 不为空，判断 `ignore-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则过滤 `test`.`t`. - - 如果不存在，则同步 `test`.`t`。 - - 3. 如果 `do-tables` 和 `ignore-tables` 都为空，则同步 `test`.`t`。 - -> **注意：** -> -> 判断 schema `test` 是否被过滤，只进行 **schema 过滤判断** - -### 使用示例 - -假设上游 MySQL 实例包含以下表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -``` - -配置如下： - -```yaml -black-white-list: - bw-rule: - do-dbs: ["forum_backup_2018", "forum"] - ignore-dbs: ["~^forum_backup_"] - do-tables: - - db-name: "logs" - tbl-name: "~_2018$" - - db-name: "~^forum.*" -​ tbl-name: "messages" - ignore-tables: - - db-name: "~.*" -​ tbl-name: "^messages.*" -``` - -应用 `bw-rule` 规则后： - -| table | 是否过滤| 过滤的原因 | -|:----|:----|:--------------| -| `logs`.`messages_2016` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2017` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2018` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2016`.`messages` | 是 | schema `forum_backup_2016` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2017`.`messages` | 是 | schema `forum_backup_2017` 没有匹配到 `do-dbs` 任意一项 | -| `forum`.`users` | 是 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 没有匹配到 `do-tables` 和 `ignore-tables` 中任意一项，并且 `do-tables` 不为空，因此过滤 | -| `forum`.`messages` | 否 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | -| `forum_backup_2018`.`messages` | 否 | 1. schema `forum_backup_2018` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | - -## Binlog event filter - -Binlog event filter 是比同步表黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema / table` 的指定类型 binlog，比如 `INSERT`，`TRUNCATE TABLE`。 - -> **注意：** -> -> 同一个表匹配上多个规则，将会顺序应用这些规则，并且黑名单的优先级高于白名单，即如果同时存在规则 `Ignore` 和 `Do` 应用在某个 table 上，那么 `Ignore` 生效。 - -### 参数配置 - -```yaml -filters: - rule-1: - schema-pattern: "test_*" - ​table-pattern: "t_*" - ​events: ["truncate table", "drop table"] - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - ​action: Ignore -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/v2.1/reference/tools/data-migration/table-selector.md)：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句进行以下规则过滤。 - -- `events`：binlog events 数组。 - - | Event | 分类 | 解释 | - | --------------- | ---- | ----------------------------- | - | all | | 代表包含下面所有的 events | - | all dml | | 代表包含下面所有 DML events | - | all ddl | | 代表包含下面所有 DDL events | - | none | | 代表不包含下面所有 events | - | none ddl | | 代表不包含下面所有 DDL events | - | none dml | | 代表不包含下面所有 DML events | - | insert | DML | insert DML event | - | update | DML | update DML event | - | delete | DML | delete DML event | - | create database | DDL | create database event | - | drop database | DDL | drop database event | - | create table | DDL | create table event | - | create index | DDL | create index event | - | drop table | DDL | drop table event | - | truncate table | DDL | truncate table event | - | rename table | DDL | rename table event | - | drop index | DDL | drop index event | - | alter table | DDL | alter table event | - -- `sql-pattern`：用于过滤指定的 DDL SQL 语句，支持正则表达式匹配，例如上面示例 `"^DROP\\s+PROCEDURE"`。 - -- `action`：string(`Do` / `Ignore`)；进行下面规则判断，满足其中之一则过滤，否则不过滤。 - - - `Do`：白名单。binlog event 如果满足下面两个条件之一就会被过滤掉： - - 不在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 没有匹配上 `sql-pattern` 中任意一项。 - - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉： - - 在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 可以匹配上 `sql-pattern` 中任意一项。 - -### 使用示例 - -#### 过滤分库分表的所有删除操作 - -需要设置下面两个 `Binlog event filter rule` 来过滤掉所有的删除操作： - -- `filter-table-rule` 过滤掉所有匹配到 pattern `test_*`.`t_*` 的 table 的 `turncate table`、`drop table`、`delete statement` 操作。 -- `filter-schema-rule` 过滤掉所有匹配到 pattern `test_*` 的 schema 的 `drop database` 操作。 - -```yaml -filters: - filter-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - filter-schema-rule: - schema-pattern: "test_*" - events: ["drop database"] - action: Ignore -``` - -#### 只同步分库分表的 DML 操作 - -需要设置下面两个 `Binlog event filter rule` 只同步 DML 操作： - -- `do-table-rule` 只同步所有匹配到 pattern `test_*`.`t_*` 的 table 的 `create table`、`insert`、`update`、`delete` 操作。 -- `do-schema-rule` 只同步所有匹配到 pattern `test_*` 的 schema 的 `create database` 操作。 - -> **注意：** -> -> 同步 `create database/table` 的原因是创建库和表后才能同步 `DML`。 - -```yaml -filters: - do-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["create table", "all dml"] - action: Do - do-schema-rule: - schema-pattern: "test_*" - events: ["create database"] - action: Do -``` - -#### 过滤 TiDB 不支持的 SQL 语句 - -可设置如下规则过滤 TiDB 不支持的 `PROCEDURE` 语句： - -```yaml -filters: - filter-procedure-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - action: Ignore -``` - -#### 过滤 TiDB parser 不支持的 SQL 语句 - -对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 `schema`/`table` 信息，因此需要使用全局过滤规则：`schema-pattern: "*"`。 - -> **注意：** -> -> 全局过滤规则的设置必须尽可能严格，以避免预期之外地过滤掉需要同步的数据。 - -可设置如下规则过滤 TiDB parser 不支持的 `PARTITION` 语句： - -```yaml -filters: - filter-partition-rule: - schema-pattern: "*" - sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"] - action: Ignore -``` - -## Column mapping - -> **注意：** -> -> 由于 Column mapping 的使用限制较多，我们不推荐使用 Column mapping 功能作为首选方案。我们优先推荐的方案请参考 [自增主键冲突处理](/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)。 - -Column mapping 提供对表的列值进行修改的功能。可以根据不同的表达式对表的指定列做不同的修改操作，目前只支持 DM 提供的内置表达式。 - -> **注意：** -> -> - 不支持修改 column 的类型和表结构。 -> - 不支持对同一个表设置多个不同的列值转换规则。 - -### 参数配置 - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/v2.1/reference/tools/data-migration/table-selector.md)：对匹配上该规则的上游 MySQL/MariaDB 实例的表按照指定 `expression` 进行列值修改操作。 -- `source-column`，`target-column`：对 `source-column` 列的值按照指定 `expression` 进行修改，将修改后的值赋值给 `target-column`。 -- `expression`：对数据进行转换的表达式，目前只支持下面的内置计算表达式。 - -#### `partition id` 表达式 - -`partition id` 目的是为了解决分库分表合并同步的自增主键的冲突。 - -**`partition id` 限制** - -注意下面的限制： - -- 只支持类型为 bigint 的列，通常为自增主键，联合主键或者联合唯一索引的其中一列 -- 如果 `schema 前缀` 不为空，则库名的组成必须为 `schema 前缀` 或者 `schema 前缀 + 分隔符 + 数字（即 schema ID）`，例如：支持 `s` 和 `s_1`，不支持 `s_a` -- 如果 `table 前缀` 不为空，则表名的组成必须为 `table 前缀` 或者 `table 前缀 + 分隔符 + 数字（即 table ID）` -- 如果库名/表名不包含 `… + 分隔符 + 数字` 部分，则对应的 ID 默认为 0 -- 对分库分表的规模支持限制如下 - - 支持最多 16 个 MySQL/MariaDB 实例，且需要满足 0 <= instance ID <= 15。 - - 每个实例支持最多 128 个 schema，且需要满足 0 <= schema ID <= 127。 - - 每个实例的每个 schema 支持最多 256 个 table，且需要满足 0 <= table ID <= 255。 - - 进行 Column mapping 的列的范围需要满足 0 <= ID <= 17592186044415。 - - `{instance ID, schema ID, table ID}` 组合需要保持唯一。 -- 目前该功能是定制功能，如果需要调整请联系相关开发人员进行调整 - -**`partition id` 参数配置** - -用户需要在 arguments 里面按顺序设置以下三个或四个参数： - -- `instance_id`：客户指定的上游分库分表的 MySQL/MariaDB instance ID（0 <= instance ID <= 15） -- `schema 前缀`：用来解析库名并获取 `schema ID` -- `table 前缀`：用来解释表名并获取 `table ID` -- 分隔符：用来分隔前缀与 ID，可省略，省略时分隔符默认为空字符串 - -`instance_id`、`schema 前缀` 和 `table 前缀` 这三个参数均可被设置为空字符串（`""`），表示对应的部分不会被编码进 `partition id`。 - -**`partition id` 表达式规则** - -`partition id` 会用 arguments 里面的数字来填充自增主键 ID 的首个比特位，计算出来一个 int64（即 MySQL bigint）类型的值，具体规则如下： - -| instance_id | schema 前缀 | table 前缀 | 编码 | -|:------------|:--------------|:-------------|---------:| -| ☑ 已定义 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 44 比特位] | -| ☐ 空 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 48 比特位] | -| ☑ 已定义 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`T`: 8 比特位] [`P`: 51 比特位] | -| ☑ 已定义 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`P`: 52 比特位] | -| ☐ 空 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`T`: 8 比特位] [`P`: 55 比特位] | -| ☐ 空 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`D`: 7 比特位] [`P`: 56 比特位] | -| ☑ 已定义 | ☐ 空 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`P`: 59 比特位] | - -- `S`：符号位，保留 -- `I`：instance ID，默认 4 比特位 -- `D`：schema ID，默认 7 比特位 -- `T`：table ID，默认 8 比特位 -- `P`：自增主键 ID，占据剩下的比特位（≥44 比特位） - -### 使用示例 - -假设存在分库分表场景：将上游两个 MySQL 实例的 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t`，并且这些表都有自增主键。 - -需要设置下面两个规则： - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -- MySQL instance 1 的表 `test_1`.`t_1` 的 `ID = 1` 的行经过转换后 ID = 1 变为 `1 << (64-1-4) | 1 << (64-1-4-7) | 1 << 44 | 1 = 580981944116838401` -- MySQL instance 2 的表 `test_1`.`t_2` 的 `ID = 1` 的行经过转换后 ID = 2 变为 `2 << (64-1-4) | 1 << (64-1-4-7) | 2 << 44 | 2 = 1157460288606306306` - -## 同步延迟监控 - -DM 支持通过 heartbeat 真实同步数据来计算每个同步任务与 MySQL/MariaDB 的实时同步延迟。 - -> **注意：** -> -> - 同步延迟的估算的精度在秒级别。 -> - heartbeat 相关的 binlog 不会同步到下游，在计算延迟后会被丢弃。 - -### 系统权限 - -如果开启 heartbeat 功能，需要上游 MySQL/MariaDB 实例提供下面的权限： - -- SELECT -- INSERT -- CREATE (databases, tables) - -### 参数配置 - -在 task 的配置文件中设置： - -``` -enable-heartbeat: true -``` - -### 原理介绍 - -- DM-worker 在对应的上游 MySQL/MariaDB 创建库 `dm_heartbeat`（当前不可配置） -- DM-worker 在对应的上游 MySQL/MariaDB 创建表 `heartbeat`（当前不可配置） -- DM-worker 每秒钟（当前不可配置）在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 表中，利用 `replace statement` 更新当前时间戳 `TS_master` -- DM-worker 每个任务拿到 `dm_heartbeat`.`heartbeat` 的 binlog 后，更新自己的同步时间 `TS_slave_task` -- DM-worker 每 10 秒在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 查询当前的 `TS_master`，并且对每个任务计算 `task_lag` = `TS_master` - `TS_slave_task` - -可以在 metrics 的 [binlog replication](/v2.1/reference/tools/data-migration/monitor.md#binlog-replication) 处理单元找到 replicate lag 监控项。 diff --git a/v2.1/reference/tools/data-migration/features/shard-merge.md b/v2.1/reference/tools/data-migration/features/shard-merge.md deleted file mode 100644 index 34cfa8496a3d..000000000000 --- a/v2.1/reference/tools/data-migration/features/shard-merge.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: 分库分表合并同步 -category: reference ---- - -# 分库分表合并同步 - -本文介绍了 DM 提供的分库分表合并同步功能。此功能用于将上游 MySQL/MariaDB 实例中结构相同的表同步到下游 TiDB 的同一个表中。DM 不仅支持同步上游的 DML 数据，也支持协调同步多个上游分表的 DDL 表结构变更。 - -> **注意：** -> -> 要执行分库分表合并同步任务，必须在任务配置文件中设置 `is-sharding: true`。 - -## 使用限制 - -DM 进行分表 DDL 的同步有以下几点使用限制： - -- 在一个逻辑 sharding group（需要合并同步到下游同一个表的所有分表组成的 group）内，所有上游分表必须以相同的顺序执行相同的 DDL 语句（库名和表名可以不同），并且只有在所有分表执行完当前一条 DDL 语句后，下一条 DDL 语句才能执行。 - - - 比如，如果在 table_1 表中先增加列 a 后再增加列 b，则在 table_2 表中就不能先增加列 b 后再增加列 a，因为 DM 不支持以不同的顺序来执行相同的 DDL 语句。 - -- 对于每个逻辑 sharding group，推荐使用一个独立的任务进行同步。 - - - 如果一个任务内存在多个 sharding group，则必须等待一个 sharding group 的 DDL 语句同步完成后，才能开始对其他 sharding group 执行 DDL 语句。 - -- 在一个逻辑 sharding group 内，所有上游分表都应该执行对应的 DDL 语句。 - - - 比如，若 DM-worker-2 对应的一个或多个上游分表未执行 DDL 语句，则其他已执行 DDL 语句的 DM-worker 都会暂停同步任务，直到等到 DM-worker-2 收到上游对应的 DDL 语句。 - -- sharding group 数据同步任务不支持 `DROP DATABASE/TABLE` 语句。 - - - DM-worker 中的 binlog 同步单元（sync）会自动忽略掉上游分表的 `DROP DATABASE` 和 `DROP TABLE` 语句。 - -- sharding group 数据同步任务支持 `RENAME TABLE` 语句，但有如下限制（online DDL 中的 `RENAME` 有特殊方案进行支持）： - - - 只支持 `RENAME TABLE` 到一个不存在的表。 - - 一条 `RENAME TABLE` 语句只能包含一个 `RENAME` 操作。 - -- 增量同步任务需要确认开始同步的 binlog position 上各分表的表结构必须一致，才能确保来自不同分表的 DML 语句能够同步到表结构确定的下游，并且后续各分表的 DDL 语句能够正确匹配与同步。 - -- 如果需要变更 [table routing 规则](/v2.1/reference/tools/data-migration/features/overview.md#table-routing)，必须先等所有 sharding DDL 语句同步完成。 - - - 在 sharding DDL 语句同步过程中，使用 dmctl 尝试变更 router-rules 会报错。 - -- 如果需要创建新表加入到一个正在执行 DDL 语句的 sharding group 中，则必须保持新表结构和最新更改的表结构一致。 - - - 比如，原 table_1, table_2 表初始时有 (a, b) 两列，sharding DDL 语句执行后有 (a, b, c) 三列，则同步完成后新创建的表也应当有 (a, b, c) 三列。 - -- 由于已经收到 DDL 语句的 DM-worker 会暂停任务以等待其他 DM-worker 收到对应的 DDL 语句，因此数据同步延迟会增加。 - -## 背景 - -目前，DM 使用 ROW 格式的 binlog 进行数据同步，且 binlog 中不包含表结构信息。在 ROW 格式的 binlog 同步过程中，如果不需要将多个上游表合并同步到下游的同一个表，则只存在一个上游表的 DDL 语句会更新对应下游表结构。ROW 格式的 binlog 可以认为是具有 self-description 属性。 - -分库分表合并同步过程中，可以根据 column values 及下游的表结构构造出相应的 DML 语句，但此时若上游的分表执行 DDL 语句进行了表结构变更，则必须对该 DDL 语句进行额外同步处理，以避免因为表结构和 binlog 数据不一致而造成同步出错的问题。 - -以下是一个简化后的例子： - -![shard-ddl-example-1](/media/shard-ddl-example-1.png) - -在上图的例子中，分表的合库合表过程简化成了上游只有两个 MySQL 实例，每个实例内只有一个表。假设在数据同步开始时，将两个分表的表结构版本记为 schema V1，将 DDL 语句执行完后的表结构版本记为 schema V2。 - -现在，假设数据同步过程中，DM-worker 内的 binlog 同步单元（sync）从两个上游分表收到的 binlog 数据有如下时序： - -1. 开始同步时，sync 从两个分表收到的都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到实例 1 上分表的 DDL 语句。 - -3. 从 t2 时刻开始，sync 从实例 1 收到的是 schema V2 版本的 DML 语句；但从实例 2 收到的仍是 schema V1 版本的 DML 语句。 - -4. 在 t3 时刻，sync 收到实例 2 上分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从实例 2 收到的也是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当实例 1 的 DDL 语句同步到下游后，下游的表结构会变更成为 schema V2 版本。但在 t2 到 t3 这段时间内，sync 从实例 2 上收到的仍是 schema V1 版本的 DML 语句。当尝试把这些 schema V1 版本的 DML 语句同步到下游时，就会由于 DML 语句与表结构的不一致而发生错误，从而无法正确同步数据。 - -## 实现原理 - -基于上述例子，本部分介绍了 DM 在合库合表过程中进行 DDL 同步的实现原理。 - -![shard-ddl-flow](/media/shard-ddl-flow.png) - -在这个例子中，DM-worker-1 负责同步来自 MySQL 实例 1 的数据，DM-worker-2 负责同步来自 MySQL 实例 2 的数据，DM-master 负责协调多个 DM-worker 间的 DDL 同步。 - -从 DM-worker-1 收到 DDL 语句开始，简化后的 DDL 同步流程为： - -1. 在 t1 时刻，DM-worker-1 收到来自 MySQL 实例 1 的 DDL 语句，自身暂停该 DDL 语句对应任务的 DDL 及 DML 数据同步，并将 DDL 相关信息发送给 DM-master。 - -2. DM-master 根据收到的 DDL 信息判断得知需要协调该 DDL 语句的同步，于是为该 DDL 语句创建一个锁，并将 DDL 锁信息发回给 DM-worker-1，同时将 DM-worker-1 标记为这个锁的 owner。 - -3. DM-worker-2 继续进行 DML 语句的同步，直到在 t3 时刻收到来自 MySQL 实例 2 的 DDL 语句，自身暂停该 DDL 语句对应任务的数据同步，并将 DDL 相关信息发送给 DM-master。 - -4. DM-master 根据收到的 DDL 信息判断得知该 DDL 语句对应的锁信息已经存在，于是直接将对应锁信息发回给 DM-worker-2。 - -5. 根据任务启动时的配置信息、上游 MySQL 实例分表信息、部署拓扑信息等，DM-master 判断得知自身已经收到了来自待合表的所有上游分表的 DDL 语句，于是请求 DDL 锁的 owner（DM-worker-1）向下游同步执行该 DDL。 - -6. DM-worker-1 根据第二步收到的 DDL 锁信息验证 DDL 语句执行请求；向下游执行 DDL，并将执行结果反馈给 DM-master；若 DDL 语句执行成功，则自身开始继续同步后续的（从 t2 时刻对应的 binlog 开始的）DML 语句。 - -7. DM-master 收到来自 owner 执行 DDL 语句成功的响应，于是请求在等待该 DDL 锁的所有其他 DM-worker（DM-worker-2）忽略该 DDL 语句，直接继续同步后续的（从 t4 时刻对应的 binlog 开始的）DML 语句。 - -根据上面的流程，可以归纳出 DM 协调多个 DM-worker 间 sharding DDL 同步的特点： - -- 根据任务配置与 DM 集群部署拓扑信息，DM-master 内部也会建立一个逻辑 sharding group 来协调 DDL 同步，group 中的成员为负责处理该同步任务拆解后的各子任务的 DM-worker。 - -- 各 DM-worker 从 binlog event 中收到 DDL 语句后，会将 DDL 信息发送给 DM-master。 - -- DM-master 根据来自 DM-worker 的 DDL 信息及 sharding group 信息创建或更新 DDL 锁。 - -- 如果 sharding group 的所有成员都收到了某一条相同的 DDL 语句，则表明上游分表在该 DDL 执行前的 DML 语句都已经同步完成，此时可以执行该 DDL 语句，并继续后续的 DML 同步。 - -- 上游所有分表的 DDL 在经过 [table router](/v2.1/reference/tools/data-migration/features/overview.md#table-routing) 转换后需要保持一致，因此仅需 DDL 锁的 owner 执行一次该 DDL 语句即可，其他 DM-worker 可直接忽略对应的 DDL 语句。 - -在上面的示例中，每个 DM-worker 对应的上游 MySQL 实例中只有一个待合并的分表。但在实际场景下，一个 MySQL 实例可能有多个分库内的多个分表需要进行合并，这种情况下，sharding DDL 的协调同步过程将更加复杂。 - -假设同一个 MySQL 实例中有 table_1 和 table_2 两个分表需要进行合并： - -![shard-ddl-example-2](/media/shard-ddl-example-2.png) - -在这个例子中，由于数据来自同一个 MySQL 实例，因此所有数据都是从同一个 binlog 流中获得，时序如下： - -1. 开始同步时，DM-worker 内的 sync 从两个分表收到的数据都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到 table_1 分表的 DDL 语句。 - -3. 从 t2 到 t3 时刻，sync 收到的数据同时包含 table_1 的 DML 语句（schema V2 版本）及 table_2 的 DML 语句（schema V1 版本）。 - -4. 在 t3 时刻，sync 收到 table_2 分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从两个分表收到的数据都是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当 table_1 的 DDL 语句同步到下游从而变更下游表结构后，table_2 的 DML 语句（schema V1 版本）将无法正常同步。因此，在单个 DM-worker 内部，我们也构造了与 DM-master 内类似的逻辑 sharding group，但 group 的成员是同一个上游 MySQL 实例的不同分表。 - -DM-worker 内协调处理 sharding group 的同步与 DM-master 处理 DM-worker 之间的同步不完全一致，主要原因包括： - -- 当 DM-worker 收到 table_1 分表的 DDL 语句时，同步不能暂停，需要继续解析 binlog 才能获得后续 table_2 分表的 DDL 语句，即需要从 t2 时刻继续解析直到 t3 时刻。 - -- 在继续解析 t2 到 t3 时刻的 binlog 的过程中，table_1 分表的 DML 语句（schema V2 版本）不能向下游同步；但当 sharding DDL 同步并执行成功后，这些 DML 语句则需要同步到下游。 - -DM-worker 内部 sharding DDL 同步的简化流程为： - -1. 在 t1 时刻，DM-worker 收到 table_1 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -2. DM-worker 继续向前解析 t2 到 t3 时刻的 binlog。 - -3. 对于 table_1 的 DML 语句（schema V2 版本），忽略；对于 table_2 的 DML 语句（schema V1 版本），正常同步到下游。 - -4. 在 t3 时刻，DM-worker 收到 table_2 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -5. 根据同步任务配置信息、上游库表信息等，DM-worker 判断得知该 MySQL 实例上所有分表的 DDL 语句都已收到；于是将该 DDL 语句同步到下游执行并变更下游表结构。 - -6. DM-worker 设置 binlog 流的新解析起始位置点为第一步时保存的位置点。 - -7. DM-worker 重新开始解析从 t2 到 t3 时刻的 binlog。 - -8. 对于 table_1 的 DML 语句（schema V2 版本），正常同步到下游；对于 table_2 的 DML 语句（schema V1 版本），忽略。 - -9. 解析到达第四步时保存的 binlog 位置点，可得知在第三步时被忽略的所有 DML 语句都已经重新同步到下游。 - -10. DM-worker 继续从 t4 时刻对应的 binlog 位置点开始正常同步。 - -综上可知，DM 在处理 sharding DDL 同步时，主要通过两级 sharding group 来进行协调控制，简化的流程为： - -1. 各 DM-worker 独立地协调对应上游 MySQL 实例内多个分表组成的 sharding group 的 DDL 同步。 - -2. 当 DM-worker 收到所有分表的 DDL 语句时，向 DM-master 发送 DDL 相关信息。 - -3. DM-master 根据 DM-worker 发来的 DDL 信息，协调由各 DM-worker 组成的 sharing group 的 DDL 同步。 - -4. 当 DM-master 收到所有 DM-worker 的 DDL 信息时，请求 DDL 锁的 owner（某个 DM-worker） 执行该 DDL 语句。 - -5. DDL 锁的 owner 执行 DDL 语句，并将结果反馈给 DM-master；自身开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -6. 当 DM-master 收到 owner 执行 DDL 成功的消息后，请求其他所有 DM-worker 继续开始同步。 - -7. 其他所有 DM-worker 各自开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -8. 在完成被忽略的 DML 语句的重新同步后，所有 DM-worker 继续正常同步。 diff --git a/v2.1/reference/tools/data-migration/from-aurora.md b/v2.1/reference/tools/data-migration/from-aurora.md deleted file mode 100644 index f17041bbfc6f..000000000000 --- a/v2.1/reference/tools/data-migration/from-aurora.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: 从 AWS Aurora MySQL 迁移数据 -summary: 使用 DM 从 AWS Aurora MySQL 迁移数据。 -category: reference ---- - -# 从 AWS Aurora MySQL 迁移数据 - -本文介绍如何使用 DM 从 [AWS Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/v2.1/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/v2.1/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v2.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 - - {{< copyable "" >}} - - ```bash - start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -```bash -query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ```bash -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 task.yaml 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/v2.1/reference/tools/data-migration/glossary.md b/v2.1/reference/tools/data-migration/glossary.md deleted file mode 100644 index b1ed481b7782..000000000000 --- a/v2.1/reference/tools/data-migration/glossary.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: TiDB Data Migration 术语表 -summary: 学习 TiDB Data Migration 相关术语 -category: glossary ---- - -# TiDB Data Migration 术语表 - -本文档介绍 TiDB Data Migration (TiDB DM) 相关术语。 - -## B - -### Binlog - -在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/internals/en/binary-log.html) 与 [MariaDB Binary Log](https://mariadb.com/kb/en/library/binary-log/)。 - -### Binlog event - -MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/internals/en/binlog-event.html) 与 [MariaDB Binlog Event](https://mariadb.com/kb/en/library/1-binlog-events/)。 - -### Binlog event filter - -比 Black & white table list 更加细粒度的过滤功能，具体可参考 [Binlog event filter](/v2.1/reference/tools/data-migration/overview.md#binlog-event-filter)。 - -### Binlog position - -特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/kb/en/library/show-binlog-events/)。 - -### Binlog replication 处理单元 - -DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游的处理单元，每个 Subtask 对应一个 Binlog replication 处理单元。在当前文档中，有时也称作 Sync 处理单元。 - -### Black & white table list - -针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Black & white table lists](/v2.1/reference/tools/data-migration/overview.md#black--white-table-lists)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。 - -## C - -### Checkpoint - -TiDB DM 在全量导入与增量复制过程中的断点信息，用于在重新启动或恢复任务时从之前已经处理过的位置继续执行。 - -- 对于全量导入，Checkpoint 信息对应于每个数据文件已经被成功导入的数据对应的文件内偏移量等信息，其在每个导入数据的事务中同步更新； -- 对于增量复制，Checkpoint 信息对应于已经成功解析并导入到下游的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 等信息，其在 DDL 导入成功后或距上次更新时间超过 30 秒等条件下更新。 - -另外，[Relay 处理单元](#relay-处理单元) 对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#GTID) 信息。 - -## D - -### Dump 处理单元 - -DM-worker 内部用于从上游导出全量数据的处理单元，每个 Subtask 对应一个 Dump 处理单元。 - -## G - -### GTID - -MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/kb/en/library/gtid/)。 - -## H - -### Heartbeat - -在增量数据迁移过程中，用于估算数据从在上游写入后到达 Binlog replication 处理单元延迟时间的机制，具体可参考[同步延迟监控](/v2.1/reference/tools/data-migration/features/overview.md#同步延迟监控)。 - -## L - -### Load 处理单元 - -DM-worker 内部用于将全量导出数据导入到下游的处理单元，每个 Subtask 对应一个 Load 处理单元。在当前文档中，有时也称作 Import 处理单元。 - -## R - -### Relay log - -DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/kb/en/library/relay-log/) 相近。 - -有关 TiDB DM 内 Relay log 的目录结构、初始同步规则、数据清理等内容，可参考 [TiDB DM Relay Log](https://pingcap.com/docs-cn/stable/reference/tools/data-migration/relay-log/)。 - -### Relay 处理单元 - -DM-worker 内部用于从上游拉取 Binlog 并写入数据到 Relay log 的处理单元，每个 DM-worker 实例内部仅存在一个该处理单元。 - -## S - -### Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在启动或恢复增量迁移任务的前 5 分钟 TiDB DM 会自动启动 Safe mode，另外也可以在任务配置文件中通过 `safe-mode` 参数手动开启。 - -### Shard DDL - -指合库合表迁移过程中，在上游各分表 (shard) 上执行的需要 TiDB DM 进行协调迁移的 DDL。在当前文档中，有时也称作 Sharding DDL。 - -### Shard DDL lock - -用于协调 Shard DDL 迁移的锁机制，具体原理可查看[分库分表合并同步实现原理](/v2.1/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding DDL lock。 - -### Shard group - -指合库合表迁移过程中，需要合并迁移到下游同一张表的所有上游分表 (shard)，TiDB DM 内部具体实现时使用了两级抽象的 Shard group，具体可查看[分库分表合并同步实现原理](/v2.1/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding group。 - -### Subtask - -数据迁移子任务，即数据迁移任务运行在单个 DM-worker 实例上的部分。根据任务配置的不同，单个数据迁移任务可能只有一个子任务，也可能有多个子任务。 - -### Subtask status - -数据迁移子任务所处的状态，目前包括 `New`、`Running`、`Paused`、`Stopped` 及 `Finished` 5 种状态。有关数据迁移任务、子任务状态的更多信息可参考[任务状态](/v2.1/reference/tools/data-migration/query-status.md#任务状态)。 - -## T - -### Table routing - -用于支持将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步，具体可参考 [Table routing](/v2.1/reference/tools/data-migration/features/overview.md#table-routing)。 - -### Task - -数据迁移任务，执行 `start-task` 命令成功后即启动一个数据迁移任务。根据任务配置的不同，单个数据迁移任务既可能只在单个 DM-worker 实例上运行，也可能同时在多个 DM-worker 实例上运行。 - -### Task status - -数据迁移子任务所处的状态，由 [Subtask status](#subtask-status) 整合而来，具体信息可查看[任务状态](/v2.1/reference/tools/data-migration/query-status.md#任务状态)。 diff --git a/v2.1/reference/tools/data-migration/manage-tasks.md b/v2.1/reference/tools/data-migration/manage-tasks.md deleted file mode 100644 index 5a621b6d80ac..000000000000 --- a/v2.1/reference/tools/data-migration/manage-tasks.md +++ /dev/null @@ -1,956 +0,0 @@ ---- -title: 管理数据同步任务 -category: reference ---- - -# 管理数据同步任务 - -本文介绍了如何使用 [dmctl](/v2.1/reference/tools/data-migration/overview.md#dmctl) 组件来进行数据同步任务的管理和维护。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 `dm-ansible/dmctl`。 - -dmctl 支持交互模式用于人工操作，同时也支持命令模式用于脚本。 - -## dmctl 交互模式 - -本部分描述了在交互模式下一些 dmctl 命令的基本用法。 - -### dmctl 使用帮助 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl --help -``` - -``` -Usage of dmctl: - -V prints version and exit - -config string - path to config file - # 按照 DM 提供的加密方法加密数据库密码，用于 DM 的配置文件 - -encrypt string - encrypt plaintext to ciphertext - # DM-master 访问地址，dmctl 与 DM-master 交互以完成任务管理操作 - -master-addr string - master API server addr - -rpc-timeout string - rpc timeout, default is 10m (default "10m") -``` - -### 加密数据库密码 - -在 DM 相关配置文件中，要求必须使用经 dmctl 加密后的密码，否则会报错。对于同一个原始密码，每次加密后密码不同。 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -### 任务管理概览 - -进入交互模式，与 DM-master 进行交互： - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 - -» help -DM control - -Usage: - dmctl [command] - -Available Commands: - break-ddl-lock forcefully break DM-worker's DDL lock - check-task check the config file of the task - help help about any command - migrate-relay migrate DM-worker's relay unit - pause-relay pause DM-worker's relay unit - pause-task pause a specified running task - purge-relay purge relay log files of the DM-worker according to the specified filename - query-error query task error - query-status query task status - refresh-worker-tasks refresh worker -> tasks mapper - resume-relay resume DM-worker's relay unit - resume-task resume a specified paused task - show-ddl-locks show un-resolved DDL locks - sql-inject inject (limited) SQLs into binlog replication unit as binlog events - sql-replace replace SQLs matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern); each SQL must end with a semicolon - sql-skip skip the binlog event matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern) - start-task start a task as defined in the config file - stop-task stop a specified task - switch-relay-master switch the master server of the DM-worker's relay unit - unlock-ddl-lock forcefully unlock DDL lock - update-master-config update the config of the DM-master - update-relay update the relay unit config of the DM-worker - update-task update a task's config for routes, filters, or black-white-list - -Flags: - -h, --help help for dmctl - -w, --worker strings DM-worker ID - -# 使用 `dmctl [command] --help` 来获取某个命令的更多信息 -``` - -## 管理数据同步任务 - -本部分描述了如何使用不同的任务管理命令来执行相应操作。 - -### 创建数据同步任务 - -`start-task` 命令用于创建数据同步任务。 当数据同步任务启动时，DM 将[自动对相应权限和配置进行前置检查](/v2.1/reference/tools/data-migration/precheck.md)。 - -{{< copyable "" >}} - -```bash -help start-task -``` - -``` -start a task as defined in the config file - -Usage: - dmctl start-task [-w worker ...] [flags] - -Flags: - -h, --help help for start-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -start-task [ -w "172.16.30.15:8262"] ./task.yaml -``` - -#### 参数解释 - -+ `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上执行 `task.yaml` - - 如果设置，则只启动指定任务在该组 DM-workers 上的子任务 -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -start-task task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -### 查询数据同步任务状态 - -`query-status` 命令用于查询数据同步任务状态。有关查询结果及子任务状态，详见[查询状态](/v2.1/reference/tools/data-migration/query-status.md)。 - -{{< copyable "" >}} - -```bash -help query-status -``` - -``` -query task status - -Usage: - dmctl query-status [-w worker ...] [task-name] [flags] - -Flags: - -h, --help help for query-status - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -query-status -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 查询在指定的一组 DM-workers 上运行的数据同步任务的子任务 -- `task-name`： - - 可选 - - 指定任务名称 - - 如果未设置，则返回全部数据同步任务的查询结果 - -#### 返回结果示例 - -有关查询结果中各参数的意义，详见[查询状态结果](/v2.1/reference/tools/data-migration/query-status.md#查询结果)。 - -### 查询运行错误 - -`query-error` 可用于查询数据同步任务与 relay 处理单元的错误信息。相比于 `query-status`，`query-error` 一般不用于获取除错误信息之外的其他信息。 - -`query-error` 常用于获取 `sql-skip`/`sql-replace` 所需的 binlog position 信息，有关 `query-error` 的参数与结果解释，请参考 [跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 文档中的 query-error](/v2.1/reference/tools/data-migration/skip-replace-sqls.md#query-error)。 - -### 暂停数据同步任务 - -`pause-task` 命令用于暂停数据同步任务。 - -> **注意：** -> -> 有关 `pause-task` 与 `stop-task` 的区别如下： -> -> - 使用 `pause-task` 仅暂停同步任务的执行，但仍然会在内存中保留任务的状态信息等，且可通过 `query-status` 进行查询；使用 `stop-task` 会停止同步任务的执行，并移除内存中与该任务相关的信息，且不可再通过 `query-status` 进行查询，但不会移除已经写入到下游数据库中的数据以及其中的 checkpoint 等 `dm_meta` 信息。 -> - 使用 `pause-task` 暂停同步任务期间，由于任务本身仍然存在，因此不能再启动同名的新任务，且会阻止对该任务所需 relay log 的清理；使用 `stop-task` 停止任务后，由于任务不再存在，因此可以再启动同名的新任务，且不会阻止对 relay log 的清理。 -> - `pause-task` 一般用于临时暂停同步任务以排查问题等；`stop-task` 一般用于永久删除同步任务或通过与 `start-task` 配合以更新配置信息。 - -{{< copyable "" >}} - -```bash -help pause-task -``` - -``` -pause a specified running task - -Usage: - dmctl pause-task [-w worker ...] [flags] - -Flags: - -h, --help help for pause-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上暂停数据同步任务的子任务 - - 如果设置，则只暂停该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-task test -``` - -``` -{ - "op": "Pause", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - } - ] -} -``` - -### 恢复数据同步任务 - -`resume-task` 命令用于恢复处于 `Paused` 状态的数据同步任务，通常用于在人为处理完造成同步任务暂停的故障后手动恢复同步任务。 - -{{< copyable "" >}} - -```bash -help resume-task -``` - -``` -resume a specified paused task - -Usage: - dmctl resume-task [-w worker ...] [flags] - -Flags: - -h, --help help for resume-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上恢复数据同步任务的子任务 - - 如果设置，则只恢复该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-task test -``` - -``` -{ - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - } - ] -} -``` - -### 停止数据同步任务 - -`stop-task` 命令用于停止数据同步任务。有关 `stop-task` 与 `pause-task` 的区别，请参考[暂停数据同步任务](#暂停数据同步任务)中的相关说明。 - -{{< copyable "" >}} - -```bash -help stop-task -``` - -``` -stop a specified task - -Usage: - dmctl stop-task [-w worker ...] [flags] - -Flags: - -h, --help help for stop-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -stop-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上停止数据同步任务的子任务 - - 如果设置，则只停止该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -stop-task test -``` - -``` -{ - "op": "Stop", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - } - ] -} -``` - -### 更新数据同步任务 - -`update-task` 命令用于更新数据同步任务。 - -支持的更新项包括： - -- Table routing 规则 -- Black & white table lists 规则 -- Binlog event filter 规则 - -其余项均不支持更新。 - -> **注意：** -> -> 如果能确保同步任务所需的 relay log 在任务停止期间不会被清理，则推荐使用[不支持更新项的更新步骤](#不支持更新项的更新步骤)来以统一的方式更新任务配置信息。 - -#### 支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若 `stage` 不为 `Paused`，则先使用 `pause-task ` 暂停任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `update-task task.yaml` 更新任务配置。 - -4. 使用 `resume-task ` 恢复任务。 - -#### 不支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若任务存在，则通过 `stop-task ` 停止任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `start-task ` 重启恢复任务。 - -{{< copyable "" >}} - -```bash -help update-task -``` - -``` -update a task's config for routes, filters, or black-white-list - -Usage: - dmctl update-task [-w worker ...] [flags] - -Flags: - -h, --help help for update-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -update-task [-w "127.0.0.1:8262"] ./task.yaml -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上更新数据同步任务的子任务 - - 如果设置，则只更新指定 DM-workers 上的子任务配置 -- `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -update-task task_all_black.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -## 管理 DDL lock - -目前与 DDL lock 相关的命令主要包括 `show-ddl-locks`、`unlock-ddl-lock`、`break-ddl-lock` 等。有关它们的功能、用法以及适用场景等，请参考[手动处理 sharding DDL lock](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 其他任务与集群管理命令 - -除上述常用的任务管理命令外，DM 还提供了其他一些命令用于管理数据同步任务或 DM 集群本身。 - -### 检查任务配置文件 - -`check-task` 命令用于检查指定的数据同步任务配置文件（`task.yaml`）是否合法以及上下游数据库的配置、权限、表结构等是否满足同步需要。具体可参考[上游 MySQL 实例配置前置检查](/v2.1/reference/tools/data-migration/precheck.md)。 - -在使用 `start-task` 启动同步任务时，DM 也会执行 `check-task` 所做的全部检查。 - -{{< copyable "" >}} - -```bash -help check-task -``` - -``` -check the config file of the task - -Usage: - dmctl check-task [flags] - -Flags: - -h, --help help for check-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -check-task task.yaml -``` - -#### 参数解释 - -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -check-task task-test.yaml -``` - -``` -{ - "result": true, - "msg": "check pass!!!" -} -``` - -### 暂停 relay 处理单元 - -relay 处理单元在 DM-worker 进程启动后即开始自动运行。通过使用 `pause-relay` 命令，我们可以暂停 relay 处理单元的运行。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `pause-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help pause-relay -``` - -``` -pause DM-worker's relay unit - -Usage: - dmctl pause-relay <-w worker ...> [flags] - -Flags: - -h, --help help for pause-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要暂停 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "PauseRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 恢复 relay 处理单元 - -`resume-relay` 用于恢复处于 `Paused` 状态的 relay 处理单元。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `resume-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help resume-relay -``` - -``` -resume DM-worker's relay unit - -Usage: - dmctl resume-relay <-w worker ...> [flags] - -Flags: - -h, --help help for resume-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要恢复 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "ResumeRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 切换 relay log 到新的子目录 - -relay 处理单元通过使用不同的子目录来存储来自上游不同 MySQL 实例的 binlog 数据。通过使用 `switch-relay-master` 命令，我们可以变更 relay 处理单元以开始使用一个新的子目录。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `switch-relay-master` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help switch-relay-master -``` - -``` -switch the master server of the DM-worker's relay unit - -Usage: - dmctl switch-relay-master <-w worker ...> [flags] - -Flags: - -h, --help help for switch-relay-master - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要切换 relay 处理单元使用子目录的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "172.16.30.15:8262" -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 手动清理 relay log - -DM 支持[自动清理 relay log](/v2.1/reference/tools/data-migration/relay-log.md#自动数据清理)，但同时 DM 也支持使用 `purge-relay` 命令[手动清理 relay log](/v2.1/reference/tools/data-migration/relay-log.md#手动数据清理)。 - -{{< copyable "" >}} - -```bash -help purge-relay -``` - -``` -purge relay log files of the DM-worker according to the specified filename - -Usage: - dmctl purge-relay <-w worker> [--filename] [--sub-dir] [flags] - -Flags: - -f, --filename string name of the terminal file before which to purge relay log files. Sample format: "mysql-bin.000006" - -h, --help help for purge-relay - -s, --sub-dir string specify relay sub directory for --filename. If not specified, the latest one will be used. Sample format: "2ae76434-f79f-11e8-bde2-0242ac130008.000001" - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要执行 relay log 清理操作的 DM-worker -- `--filename`： - - 必选 - - 指定标识 relay log 将要停止清理的文件名。如指定为 `mysql-bin.000100`，则只尝试清理到 `mysql-bin.000099` -- `--sub-dir`： - - 可选 - - 指定 `--filename` 对应的 relay log 子目录，如果不指定则会使用当前最新的子目录 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -``` -[warn] no --sub-dir specified for --filename; the latest one will be used -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] -} -``` - -### 预设跳过 DDL 操作 - -`sql-skip` 命令用于预设一个跳过操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。相关参数与结果解释，请参考[`sql-skip`](/v2.1/reference/tools/data-migration/skip-replace-sqls.md#sql-skip)。 - -### 预设替换 DDL 操作 - -`sql-replace` 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替换执行操作。相关参数与结果解释，请参考[`sql-replace`](/v2.1/reference/tools/data-migration/skip-replace-sqls.md#sql-replace)。 - -### 强制刷新 `task => DM-workers` 映射关系 - -`refresh-worker-tasks` 命令用于强制刷新 DM-master 内存中维护的 `task => DM-workers` 映射关系。 - -> **注意：** -> -> 一般不需要使用此命令。仅当已确定 `task => DM-workers` 映射关系存在，但执行其它命令时仍提示必须刷新它时，你才需要使用此命令。 - -## dmctl 命令模式 - -命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。 - -> **注意：** -> -> + 一条 dmctl 命令只能跟一个任务操作 -> + 任务操作只能放在 dmctl 命令的最后 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 start-task task.yaml -./dmctl -master-addr 172.16.30.14:8261 stop-task task -./dmctl -master-addr 172.16.30.14:8261 query-status -``` - -``` -Available Commands: - break-ddl-lock break-ddl-lock <-w worker ...> [--remove-id] [--exec] [--skip] - check-task check-task - migrate-relay migrate-relay - pause-relay pause-relay <-w worker ...> - pause-task pause-task [-w worker ...] - purge-relay purge-relay <-w worker> [--filename] [--sub-dir] - query-error query-error [-w worker ...] [task-name] - query-status query-status [-w worker ...] [task-name] - refresh-worker-tasks refresh-worker-tasks - resume-relay resume-relay <-w worker ...> - resume-task resume-task [-w worker ...] - show-ddl-locks show-ddl-locks [-w worker ...] [task-name] - sql-inject sql-inject <-w worker> - sql-replace sql-replace <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - sql-skip sql-skip <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - start-task start-task [-w worker ...] - stop-task stop-task [-w worker ...] - switch-relay-master switch-relay-master <-w worker ...> - unlock-ddl-lock unlock-ddl-lock [-w worker ...] - update-master-config update-master-config - update-relay update-relay [-w worker ...] - update-task update-task [-w worker ...] -``` - -## 废弃或不推荐使用的命令 - -以下命令已经被废弃或仅用于 debug，在接下来的版本中可能会被移除或修改其语义，**强烈不推荐使用**。 - -- `migrate-relay` -- `sql-inject` -- `update-master-config` -- `update-relay` diff --git a/v2.1/reference/tools/data-migration/monitor.md b/v2.1/reference/tools/data-migration/monitor.md deleted file mode 100644 index f0499ba20796..000000000000 --- a/v2.1/reference/tools/data-migration/monitor.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: DM 监控指标 -summary: 介绍 DM 的监控指标 -category: reference ---- - -# DM 监控指标 - -使用 DM-Ansible 部署 DM 集群的时候，会默认部署一套[监控系统](/v2.1/reference/tools/data-migration/deploy.md#第-7-步监控任务与查看日志)。 - -> **注意：** -> -> 目前只有 DM-worker 提供了 metrics，DM-master 暂未提供。 - -## Task - -在 Grafana dashboard 中，DM 默认名称为 `DM-task`。 - -### overview - -overview 下包含运行当前选定 task 的所有 DM-worker instance 的部分监控指标。当前默认告警规则只针对于单个 DM-worker instance。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | N/A | N/A | -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | N/A | N/A | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -### task 状态 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时| critical | - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒| N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### Dump/Load unit - -下面 metrics 仅在 `task-mode` 为 `full` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| data file size | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的总大小 | N/A | N/A | -| dump process exits with error | dump unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| load process exits with error | load unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| table count | load unit 导入的全量数据中 table 的数量总和 | N/A | N/A | -| data file count | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的数量总和| N/A | N/A | -| latency of execute transaction | load unit 在执行事务的时延，单位：秒 | N/A | N/A | -| latency of query | load unit 执行 query 的耗时，单位：秒 | N/A | N/A | - -### Binlog replication - -下面 metrics 仅在 `task-mode` 为 `incremental` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| remaining time to sync | 预计 Syncer 还需要多少分钟可以和 master 完全同步，单位：分钟 | N/A | N/A | -| replicate lag | master 到 Syncer 的 binlog 复制延迟时间，单位：秒 | N/A | N/A | -| process exist with error | binlog replication 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| binlog file gap between master and syncer | 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog file gap between relay and syncer | 与 relay 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog event qps | 单位时间内接收到的 binlog event 数量 (不包含需要跳过的 event) | N/A | N/A | -| skipped binlog event qps | 单位时间内接收到的需要跳过的 binlog event 数量 | N/A | N/A | -| cost of binlog event transform | Syncer 解析并且转换 binlog 成 SQLs 的耗时，单位：秒 | N/A | N/A | -| total sqls jobs | 单位时间内新增的 job 数量 | N/A | N/A | -| finished sqls jobs | 单位时间内完成的 job 数量 | N/A | N/A | -| execution latency | Syncer 执行 transaction 到下游的耗时，单位：秒 | N/A | N/A | -| unsynced tables | 当前子任务内还未收到 shard DDL 的分表数量 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -## Instance - -在 Grafana dashboard 中，instance 的默认名称为 `DM-instance`。 - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒 | N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### task - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时 | critical | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | diff --git a/v2.1/reference/tools/data-migration/overview.md b/v2.1/reference/tools/data-migration/overview.md deleted file mode 100644 index 203e963e0a66..000000000000 --- a/v2.1/reference/tools/data-migration/overview.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Data Migration 简介 -category: reference ---- - -# Data Migration 简介 - -[DM](https://github.com/pingcap/dm) (Data Migration) 是一体化的数据同步任务管理平台，支持从 MySQL 或 MariaDB 到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化错误处理流程，降低运维成本。 - -## DM 架构 - -DM 主要包括三个组件：DM-master，DM-worker 和 dmctl。 - -![Data Migration architecture](/media/dm-architecture.png) - -### DM-master - -DM-master 负责管理和调度数据同步任务的各项操作。 - -- 保存 DM 集群的拓扑信息 -- 监控 DM-worker 进程的运行状态 -- 监控数据同步任务的运行状态 -- 提供数据同步任务管理的统一入口 -- 协调分库分表场景下各个实例分表的 DDL 同步 - -### DM-worker - -DM-worker 负责执行具体的数据同步任务。 - -- 将 binlog 数据持久化保存在本地 -- 保存数据同步子任务的配置信息 -- 编排数据同步子任务的运行 -- 监控数据同步子任务的运行状态 - -DM-worker 启动后，会自动同步上游 binlog 至本地配置目录（如果使用 DM-Ansible 部署 DM 集群，默认的同步目录为 `/relay_log`）。关于 DM-worker，详见 [DM-worker 简介](/v2.1/reference/tools/data-migration/dm-worker-intro.md)。关于 relay log，详见 [DM Relay Log](/v2.1/reference/tools/data-migration/relay-log.md)。 - -### dmctl - -dmctl 是用来控制 DM 集群的命令行工具。 - -- 创建、更新或删除数据同步任务 -- 查看数据同步任务状态 -- 处理数据同步任务错误 -- 校验数据同步任务配置的正确性 - -## 同步功能介绍 - -下面简单介绍 DM 数据同步功能的核心特性。 - -### Table routing - -[Table routing](/v2.1/reference/tools/data-migration/features/overview.md#table-routing) 是指将上游 MySQL 或 MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步。 - -### Black & white table lists - -[Black & white table lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) 是指上游数据库实例表的黑白名单过滤规则。其过滤规则类似于 MySQL `replication-rules-db`/`replication-rules-table`，可以用来过滤或只同步某些数据库或某些表的所有操作。 - -### Binlog event filter - -[Binlog event filter](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 是比库表同步黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema`/`table` 的指定类型的 binlog events，比如 `INSERT`，`TRUNCATE TABLE`。 - -### Shard support - -DM 支持对原分库分表进行合库合表操作，但需要满足一些[使用限制](/v2.1/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -## 使用限制 - -在使用 DM 工具之前，需了解以下限制： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - - > **注意：** - > - > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则 - > - > - 5.7.1 < MySQL 版本 < 8.0 - > - MariaDB 版本 >= 10.1.3 - - 在使用 dmctl 启动任务时，DM 会自动对任务上下游数据库的配置、权限等进行[前置检查](/v2.1/reference/tools/data-migration/precheck.md)。 - -+ DDL 语法 - - - 目前，TiDB 部分兼容 MySQL 支持的 DDL 语句。因为 DM 使用 TiDB parser 来解析处理 DDL 语句，所以目前仅支持 TiDB parser 支持的 DDL 语法。 - - DM 遇到不兼容的 DDL 语句时会报错。要解决此报错，需要使用 dmctl 手动处理，要么跳过该 DDL 语句，要么用指定的 DDL 语句来替换它。详见[如何处理不兼容的 DDL 语句](/v2.1/reference/tools/data-migration/faq.md#如何处理不兼容的-ddl-语句) - -+ 分库分表 - - - 如果业务分库分表之间存在数据冲突，可以参考[自增主键冲突处理](/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决；否则不推荐使用 DM 进行同步，如果进行同步则有冲突的数据会相互覆盖造成数据丢失。 - - 关于分库分表合并场景的其它限制，参见[使用限制](/v2.1/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -+ 操作限制 - - - DM-worker 重启后不能自动恢复数据同步任务，需要使用 dmctl 手动执行 `start-task`。详见[管理数据同步任务](/v2.1/reference/tools/data-migration/manage-tasks.md)。 - - 在一些情况下，DM-worker 重启后不能自动恢复 DDL lock 同步，需要手动处理。详见[手动处理 Sharding DDL Lock](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -+ DM-worker 切换 MySQL - - - 当 DM-worker 通过虚拟 IP（VIP）连接到 MySQL 且要切换 VIP 指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。如需切换 VIP 指向的 MySQL 实例，请参考[虚拟 IP 环境下的上游主从切换](/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-ip-环境下切换-dm-worker-与-mysql-实例的连接)对 DM 手动执行变更。 diff --git a/v2.1/reference/tools/data-migration/precheck.md b/v2.1/reference/tools/data-migration/precheck.md deleted file mode 100644 index d28a92f4c0e7..000000000000 --- a/v2.1/reference/tools/data-migration/precheck.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 上游 MySQL 实例配置前置检查 -category: reference ---- - -# 上游 MySQL 实例配置前置检查 - -本文介绍了 DM 提供的前置检查功能，此功能用于在数据同步任务启动时提前检测出上游 MySQL 实例配置中可能存在的一些错误。 - -## 使用命令 - -`check-task` 命令用于对上游 MySQL 实例配置是否满足 DM 要求进行前置检查。 - -## 检查内容 - -上下游数据库用户必须具备相应读写权限。当数据同步任务启动时，DM 会自动检查下列权限和配置： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - -+ MySQL binlog 配置 - - - binlog 是否开启（DM 要求 binlog 必须开启） - - 是否有 `binlog_format=ROW`（DM 只支持 ROW 格式的 binlog 同步） - - 是否有 `binlog_row_image=FULL`（DM 只支持 `binlog_row_image=FULL`） - -+ 上游 MySQL 实例用户的权限 - - DM 配置中的 MySQL 用户至少需要具备以下权限： - - - REPLICATION SLAVE - - REPLICATION CLIENT - - RELOAD - - SELECT - -+ 上游 MySQL 表结构的兼容性 - - TiDB 和 MySQL 的兼容性存在以下一些区别： - - - TiDB 不支持外键 - - 字符集的兼容性不同，详见 [TiDB 支持的字符集](/v2.1/reference/sql/character-set.md) - -+ 上游 MySQL 多实例分库分表的一致性 - - + 所有分表的表结构是否一致，检查内容包括： - - - Column 数量 - - Column 名称 - - Column 位置 - - Column 类型 - - 主键 - - 唯一索引 - - + 分表中自增主键冲突检查 - - - 在两种情况下会造成检查失败： - - - 分表存在自增主键，且自增主键 column 类型不为 bigint - - 分表存在自增主键，自增主键 column 类型为 bigint，但没有为其配置列值转换 - - - 其他情况下检查将成功 diff --git a/v2.1/reference/tools/data-migration/query-status.md b/v2.1/reference/tools/data-migration/query-status.md deleted file mode 100644 index 1dbe7d1e2f02..000000000000 --- a/v2.1/reference/tools/data-migration/query-status.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: DM 查询状态 -category: reference ---- - -# DM 查询状态 - -本文介绍 DM（Data Migration）`query-status` 命令的查询结果、任务状态与子任务状态。 - -## 查询结果 - -{{< copyable "" >}} - -```bash -» query-status -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "tasks": [ # 迁移 task 列表 - { - "taskName": "test-1", # 任务名称 - "taskStatus": "Running", # 任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped”，“Finished” 以及 “Error”。 - "workers": [ # 该任务所使用的 DM-workers 列表 - "127.0.0.1:8262" - ] - }, - { - "taskName": "test-2", - "taskStatus": "Error - Some error occurred in subtask", # 该任务的子任务存在运行错误并暂停的现象 - "workers": [ - "127.0.0.1:8262", - "127.0.0.1:8263" - ] - }, - { - "taskName": "test-3", - "taskStatus": "Error - Relay status is Error", # 该任务的某个处于 Sync 阶段的子任务对应的 Relay 处理单元出错 - "workers": [ - "127.0.0.1:8263", - "127.0.0.1:8264" - ] - } - ] -} -``` - -关于 tasks 下的 taskStatus 状态的详细定义，请参阅[任务状态](#任务状态)。 - -推荐的 `query-status` 使用方法是： - -1. 首先使用 query-status 查看各个 task 的运行状态是否正常。 -2. 如果发现其中某一 task 状态有问题，通过 `query-status <出错任务的 taskName>` 来得到更详细的错误信息。 - -## 任务状态 - -DM 的迁移任务状态取决于其分配到 DM-worker 上的[子任务状态](#子任务状态)，定义见下表： - -| 任务对应的所有子任务的状态 | 任务状态 | -| :--- | :--- | -| 任一子任务处于 “Paused” 状态且返回结果有错误信息 | Error - Some error occurred in subtask | -| 任一处于 Sync 阶段的子任务处于 “Running” 状态但其 Relay 处理单元未运行（处于 Error/Paused/Stopped 状态） | Error - Relay status is Error/Paused/Stopped | -| 任一子任务处于 “Paused” 状态且返回结果没有错误信息 | Paused | -| 所有子任务处于 “New” 状态 | New | -| 所有子任务处于 “Finished” 状态 | Finished | -| 所有子任务处于 “Stopped” 状态 | Stopped | -| 其他情况 | Running | - -## 详情查询结果 - -{{< copyable "" >}} - -```bash -» query-status test -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "workers": [ # DM-worker 列表。 - { - "result": true, - "worker": "172.17.0.2:8262", # DM-worker ID。 - "msg": "", - "subTaskStatus": [ # DM-worker 所有子任务的信息。 - { - "name": "test", # 子任务名称。 - "stage": "Running", # 子任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped” 以及 “Finished”。 - "unit": "Sync", # DM 的处理单元，包括 “Check”，“Dump“，“Load” 以及 “Sync”。 - "result": null, # 子任务失败时显示错误信息。 - "unresolvedDDLLockID": "test-`test`.`t_target`", # sharding DDL lock ID，可用于异常情况下手动处理 sharding DDL lock。 - "sync": { # 当前 `Sync` 处理单元的同步信息。 - "totalEvents": "12", # 该子任务中同步的 binlog event 总数。 - "totalTps": "1", # 该子任务中每秒同步的 binlog event 数量。 - "recentTps": "1", # 该子任务中最后一秒同步的 binlog event 数量。 - "masterBinlog": "(bin.000001, 3234)", # 上游数据库当前的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库当前的 GTID 信息。 - "syncerBinlog": "(bin.000001, 2525)", # 已被 `Sync` 处理单元同步的 binlog position。 - "syncerBinlogGtid": "", # 当前版本总是为空（因为 `Sync` 处理单元暂不使用 GTID 同步数据）。 - "blockingDDLs": [ # 当前被阻塞的 DDL 列表。该项仅在当前 DM-worker 所有上游表都处于 “synced“ 状态时才有数值，此时该列表包含的是待执行或待跳过的 sharding DDL 语句. - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "unresolvedGroups": [ # 没有被解决的 sharding group 信息。 - { - "target": "`test`.`t_target`", # 待同步的下游表。 - "DDLs": [ - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "firstPos": "(bin|000001.000001, 3130)", # sharding DDL 语句起始 binlog position。 - "synced": [ # `Sync` 处理单元已经读到该 sharding DDL 的上游分表。 - "`test`.`t2`" - "`test`.`t3`" - "`test`.`t1`" - ], - "unsynced": [ # `Sync` 处理单元未读到该 sharding DDL 的上游分表。如有上游分表未完成同步，`blockingDDLs` 为空。 - ] - } - ], - "synced": false # 增量同步是否已追上上游。由于后台 `Sync` 单元并不会实时刷新保存点，当前值为 “false“ 并不一定代表发生了同步延迟。 - } - } - ], - "relayStatus": { # relay 单元的同步状态. - "masterBinlog": "(bin.000001, 3234)", # 上游数据库的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库的 binlog GTID 信息。 - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", # 当前使用的 relay log 子目录。 - "relayBinlog": "(bin.000001, 3234)", # 已被拉取至本地存储的 binlog position。 - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 已被拉取至本地存储的 binlog GTID 信息。 - "relayCatchUpMaster": true, # 本地 relay log 同步进度是否与上游一致。 - "stage": "Running", # relay 处理单元状态 - "result": null - } - }, - { - "result": true, - "worker": "172.17.0.3:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Running", - "unit": "Load", - "result": null, - "unresolvedDDLLockID": "", - "load": { # `Load` 处理单元的同步信息。 - "finishedBytes": "115", # 已全量导入字节数。 - "totalBytes": "452", # 总计需要导入的字节数。 - "progress": "25.44 %" # 全量导入进度。 - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 28507)", - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", - "relayBinlog": "(bin.000001, 28507)", - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - } - }, - { - "result": true, - "worker": "172.17.0.6:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Paused", - "unit": "Load", - "result": { # 错误示例 - "isCanceled": false, - "errors": [ - { - "Type": "ExecSQL", - "msg": "Error 1062: Duplicate entry '1155173304420532225' for key 'PRIMARY'\n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:160: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:105: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/loader.go:138: file test.t1.sql" - } - ], - "detail": null - }, - "unresolvedDDLLockID": "", - "load": { - "finishedBytes": "0", - "totalBytes": "156", - "progress": "0.00 %" - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 1691)", - "masterBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relaySubDir": "97b5142f-e19c-11e8-808c-0242ac110005.000001", - "relayBinlog": "(bin.000001, 1691)", - "relayBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - } - } - ] -} - -``` - -关于 `workers` 下 `subTaskStatus` 中 `stage` 状态和状态转换关系的详细信息，请参阅[子任务状态](#子任务状态)。 - -关于 `workers` 下 `subTaskStatus` 中 `unresolvedDDLLockID`的操作细节，请参阅[手动处理 Sharding DDL Lock](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 子任务状态 - -### 状态描述 - -- `New`： - - - 初始状态。 - - 如果子任务没有发生错误，状态切换为 `Running`，其他情况则切换为 `Paused`。 - -- `Running`：正常运行状态。 - -- `Paused`： - - - 暂停状态。 - - 子任务发生错误，状态切换为 `Paused`。 - - 如在子任务为 `Running` 状态下执行 `pause-task` 命令，任务状态会切换为 `Paused`。 - - 如子任务处于该状态，可以使用 `resume-task` 命令恢复任务。 - -- `Stopped`： - - - 停止状态。 - - 如在子任务为 `Running` 或 `Paused` 状态下执行 `stop-task` 命令，任务状态会切换为 `Stopped`。 - - 如子任务处于该状态，不可使用 `resume-task` 命令恢复任务。 - -- `Finished`： - - - 任务完成状态。 - - 只有 `task-mode` 为 `full` 的任务正常完成后，任务才会切换为该状态。 - -### 状态转换图 - -``` - error occurs - New --------------------------------| - | | - | resume-task | - | |----------------------------| | - | | | | - | | | | - v v error occurs | v - Finished <-------------- Running -----------------------> Paused - ^ | or pause-task | - | | | - start task | | stop task | - | | | - | v stop task | - Stopped <-------------------------| -``` diff --git a/v2.1/reference/tools/data-migration/relay-log.md b/v2.1/reference/tools/data-migration/relay-log.md deleted file mode 100644 index be3bf2b211ef..000000000000 --- a/v2.1/reference/tools/data-migration/relay-log.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: DM Relay Log -summary: 了解目录结构、初始同步规则和 DM relay log 的数据清理。 -category: reference ---- - -# DM Relay Log - -DM (Data Migration) 工具的 relay log 由一组有编号的文件和一个索引文件组成。这些有编号的文件包含了描述数据库更改的事件。索引文件包含所有使用过的 relay log 的文件名。 - -DM-worker 在启动后，会自动将上游 binlog 同步到本地配置目录（若使用 DM-Ansible 部署 DM，则同步目录默认为 ` / relay_log` ）。DM-worker 在运行过程中，会将上游 binlog 实时同步到本地文件。DM-worker 的处理单元 Syncer 会实时读取本地 relay log 的 binlog 事件，将这些事件转换为 SQL 语句，再将 SQL 语句同步到下游数据库。 - -本文档介绍 DM relay log 的目录结构、初始同步规则和数据清理方法。 - -## 目录结构 - -Relay-log 本地存储的目录结构示例如下： - -``` -/relay_log/ -|-- 7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001 -| |-- mysql-bin.000001 -| |-- mysql-bin.000002 -| |-- mysql-bin.000003 -| |-- mysql-bin.000004 -| `-- relay.meta -|-- 842965eb-091c-11e9-9e45-9a3bff03fa39.000002 -| |-- mysql-bin.000001 -| `-- relay.meta -`-- server-uuid.index -``` - -- `subdir`： - - - DM-worker 把从上游数据库同步到的 binlog 存储在同一目录下，每个目录都为一个 `subdir`。 - - `subdir` 的命名格式为 `<上游数据库 UUID>.<本地 subdir 序列号>`。 - - 在上游进行 master 和 slave 实例切换后，DM-worker 会生成一个序号递增的新 `subdir` 目录。 - - - 在以上示例中，对于 `7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001` 这一目录，`7e427cc0-091c-11e9-9e45-72b7c59d52d7` 是上游数据库的 UUID，`000001` 是本地 `subdir` 的序列号。 - -- `server-uuid.index`：记录当前可用的 `subdir` 目录。 - -- `relay.meta`：存储每个 `subdir` 中已同步的 binlog 信息。例如， - - ``` - $ cat c0149e17-dff1-11e8-b6a8-0242ac110004.000001/relay.meta - binlog-name = "mysql-bin.000010" # 当前同步的 binlog 名 - binlog-pos = 63083620 # 当前同步的 binlog 位置 - binlog-gtid = "c0149e17-dff1-11e8-b6a8-0242ac110004:1-3328" # 当前同步的 binlog GTID - - # 可能包含多个 GTID - $ cat 92acbd8a-c844-11e7-94a1-1866daf8accc.000001/relay.meta - binlog-name = "mysql-bin.018393" - binlog-pos = 277987307 - binlog-gtid = "3ccc475b-2343-11e7-be21-6c0b84d59f30:1-14,406a3f61-690d-11e7-87c5-6c92bf46f384:1-94321383,53bfca22-690d-11e7-8a62-18ded7a37b78:1-495,686e1ab6-c47e-11e7-a42c-6c92bf46f384:1-34981190,03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170,10b039fc-c843-11e7-8f6a-1866daf8d810:1-308290454" - ``` - -## 初始同步规则 - -DM-worker 每次启动时（或在 DM-worker 暂停后 relay log 恢复同步），同步的起始位置会出现以下几种情况： - -- 若是有效的本地 relay log（有效是指 relay log 具有有效的 `server-uuid.index`，`subdir` 和 `relay.meta` 文件），DM-worker 从 `relay.meta` 记录的位置恢复同步。 - -- 若不存在有效的本地 relay log，而且 DM 配置文件中未指定 `relay-binlog-name` 或 `relay-binlog-gtid`： - - - 在非 GTID 模式下，DM-worker 从初始的上游 binlog 开始同步，并将所有上游 binlog 文件连续同步至最新。 - - - 在 GTID 模式下，DM-worker 从初始上游 GTID 开始同步。 - - > **注意：** - > - > 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定同步的起始位置。 - -- 若不存在有效的本地 relay log： - - - 在非 GTID 模式下，若指定了 `relay-binlog-name`，则 DM-worker 从指定的 binlog 文件开始同步。 - - 在 GTID 模式下，若指定了 `relay-binlog-gtid`，则 DM-worker 从指定的 GTID 开始同步。 - -## 数据清理 - -因为存在文件读写的检测机制，所以 DM-worker 不会清理正在使用的 relay log，也不会清理当前任务稍后会使用到的 relay log。 - -Relay log 的数据清理包括自动清理和手动清理这两种方法。 - -### 自动数据清理 - -自动数据清理需对 DM-worker 命令行配置中的以下三项进行配置： - -- `purge-interval` - - 后台自动清理的时间间隔，以秒为单位。 - - 默认为 "3600"，表示每 3600 秒执行一次后台清理任务。 - -- `purge-expires` - - 未更新的 relay log 在被后台清理前可保留的小时数。 - - 默认为 "0"，表示不按 relay log 的更新时间执行数据清理。 - -- `purge-remain-space` - - 剩余磁盘空间，单位为 GB。若剩余磁盘空间小于该配置，则指定的 DM-worker 机器会在后台尝试自动清理可被安全清理的 relay-log。若这一数字被设为 "0"，则表示不按剩余磁盘空间来清理数据。 - - 默认为 "15"，表示可用磁盘空间小于 15GB 时，DM-master 会尝试安全地清理 relay log。 - -或者在 DM-woker 的配置文件中加入 purge 配置： - -```toml -# relay log purge strategy -[purge] -interval = 3600 -expires = 24 -remain-space = 15 -``` - -### 手动数据清理 - -手动数据清理是指使用 dmctl 提供的 `purge-relay` 命令，通过指定 `subdir` 和 binlog 文件名，来清理掉**指定 binlog 之前**的所有 relay log。若在命令中不填 `-subdir` 选项，则默认清理**最新 relay log 子目录之前**的所有 relay log。 - -假设当前 relay log 的目录结构如下： - -``` -$ tree . -. -|-- deb76a2b-09cc-11e9-9129-5242cf3bb246.000001 -| |-- mysql-bin.000001 -| |-- mysql-bin.000002 -| |-- mysql-bin.000003 -| `-- relay.meta -|-- deb76a2b-09cc-11e9-9129-5242cf3bb246.000003 -| |-- mysql-bin.000001 -| `-- relay.meta -|-- e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 -| |-- mysql-bin.000001 -| `-- relay.meta -`-- server-uuid.index - -$ cat server-uuid.index -deb76a2b-09cc-11e9-9129-5242cf3bb246.000001 -e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 -deb76a2b-09cc-11e9-9129-5242cf3bb246.000003 -``` - -在 dmctl 中使用 `purge-relay` 命令的示例如下： - -+ 以下命令指定的 relay log 子目录为 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，该子目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001`。所以该命令实际清空了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 子目录，保留 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002` 和 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。 - - {{< copyable "" >}} - - ```bash - » purge-relay -w 10.128.16.223:10081 --filename mysql-bin.000001 --sub-dir e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 - ``` - -+ 以下命令默认 `--sub-dir` 为最新的 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。该目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 和 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，所以该命令实际清空了这两个子目录，保留了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003`。 - - {{< copyable "" >}} - - ```bash - » purge-relay -w 10.128.16.223:10081 --filename mysql-bin.000001 - ``` diff --git a/v2.1/reference/tools/data-migration/releases/1.0.2.md b/v2.1/reference/tools/data-migration/releases/1.0.2.md deleted file mode 100644 index 176073d7f66d..000000000000 --- a/v2.1/reference/tools/data-migration/releases/1.0.2.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: DM 1.0.2 Release Notes -category: Releases ---- - -# DM 1.0.2 Release Notes - -发版日期：2019 年 10 月 30 日 - -DM 版本：1.0.2 - -DM-Ansible 版本：1.0.2 - -## 改进提升 - -- 支持自动为 DM-worker 生成部分配置项 -- 支持自动为数据迁移任务生成部分配置项 -- 简化 `query-status` 在无参数时的默认输出 -- DM 直接管理到下游数据库的连接 - -## 问题修复 - -- 修复在进程启动过程中以及执行 SQL 失败时可能 panic 的问题 -- 修复 DDL 执行超时后可能造成 sharding DDL 协调异常的问题 -- 修复由于前置检查超时或部分 DM-worker 不可访问而不能启动数据迁移任务的问题 -- 修复 SQL 执行失败后可能错误重试的问题 - -## 详细变更及问题修复 - -- 支持自动为 DM-worker 生成随机的 `server-id` 配置项 [#337](https://github.com/pingcap/dm/pull/337) -- 支持自动为 DM-worker 生成 `flavor` 配置项 [#328](https://github.com/pingcap/dm/pull/328) -- 支持自动为 DM-worker 生成 `relay-binlog-name` 与 `relay-binlog-gtid` 配置项 [#318](https://github.com/pingcap/dm/pull/318) -- 支持根据黑白名单生成 mydumper 需要导出的表名配置项 [#326](https://github.com/pingcap/dm/pull/326) -- 为数据迁移任务增加并发度配置项 (`mydumper-thread`、`loader-thread` 与 `syncer-thread`) [#314](https://github.com/pingcap/dm/pull/314) -- 简化 `query-status` 在无参数时的默认输出 [#340](https://github.com/pingcap/dm/pull/340) -- 修复 DDL 执行超时后可能造成 sharding DDL 协调异常的问题 [#338](https://github.com/pingcap/dm/pull/338) -- 修复 DM-worker 从本地 meta 数据恢复数据迁移任务时可能 panic 的问题 [#311](https://github.com/pingcap/dm/pull/311) -- 修复提交事务失败时可能造成 DM-worker panic 的问题 [#313](https://github.com/pingcap/dm/pull/313) -- 修复监听端口被占用时 DM-worker 或 DM-master 启动过程中可能 panic 的问题 [#301](https://github.com/pingcap/dm/pull/301) -- 修复对 1105 错误码的部分重试问题 [#321](https://github.com/pingcap/dm/pull/321), [#332](https://github.com/pingcap/dm/pull/332) -- 修复对 `Duplicate entry` 与 `Data too long for column` 错误的重试问题 [#313](https://github.com/pingcap/dm/pull/313) -- 修复在上游存在大量需要迁移的表时可能造成启动任务前置检查超时中断的问题 [#327](https://github.com/pingcap/dm/pull/327) -- 修复部分 DM-worker 不可访问时无法启动数据迁移任务的问题 [#319](https://github.com/pingcap/dm/pull/319) -- 修复从损坏的 relay log 恢复时可能错误更新 GTID sets 信息的问题 [#339](https://github.com/pingcap/dm/pull/339) -- 修复 sync 处理单元计算 TPS 错误的问题 [#294](https://github.com/pingcap/dm/pull/294) -- DM 直接管理到下游数据库的连接 [#325](https://github.com/pingcap/dm/pull/325) -- 提升组件内错误信息的传递方式 [#320](https://github.com/pingcap/dm/pull/320) diff --git a/v2.1/reference/tools/data-migration/releases/1.0.3.md b/v2.1/reference/tools/data-migration/releases/1.0.3.md deleted file mode 100644 index 8ae6dda78d5e..000000000000 --- a/v2.1/reference/tools/data-migration/releases/1.0.3.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: DM 1.0.3 Release Notes -category: Releases ---- - -# DM 1.0.3 Release Notes - -发版日期：2019 年 12 月 13 日 - -DM 版本：1.0.3 - -DM-Ansible 版本：1.0.3 - -## 改进提升 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 - -## 问题修复 - -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -## 详细变更及问题修复 - -- dmctl 支持命令式使用 [#364](https://github.com/pingcap/dm/pull/364) -- 优化 DM 错误提示信息 [#351](https://github.com/pingcap/dm/pull/351) -- 优化 `query-status` 命令输出内容 [#357](https://github.com/pingcap/dm/pull/357) -- 优化 DM 不同任务类型的权限检查 [#374](https://github.com/pingcap/dm/pull/374) -- 支持对重复引用的路由配置和过滤配置进行检查 [#385](https://github.com/pingcap/dm/pull/385) -- 支持同步 `ALTER DATABASE` DDL 语句 [#389](https://github.com/pingcap/dm/pull/389) -- 优化 DM 异常重试机制 [#391](https://github.com/pingcap/dm/pull/391) -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 [#353](https://github.com/pingcap/dm/pull/353) -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 [#400](https://github.com/pingcap/dm/pull/400) -- 更新 Golang 版本至 1.13 以及其他依赖包版本 [#362](https://github.com/pingcap/dm/pull/362) -- 过滤 SQL 执行时出现的 `context canceled` 错误 [#382](https://github.com/pingcap/dm/pull/382) -- 修复使用 DM-ansible 滚动升级 DM 监控过程中出错导致升级失败的问题 [#408](https://github.com/pingcap/dm/pull/408) diff --git a/v2.1/reference/tools/data-migration/skip-replace-sqls.md b/v2.1/reference/tools/data-migration/skip-replace-sqls.md deleted file mode 100644 index 2a236f8c2800..000000000000 --- a/v2.1/reference/tools/data-migration/skip-replace-sqls.md +++ /dev/null @@ -1,610 +0,0 @@ ---- -title: 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 -category: reference ---- - -# 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 - -本文介绍了如何使用 DM 来处理异常的 SQL 语句。 - -目前，TiDB 并不完全兼容所有的 MySQL 语法。当使用 DM 从 MySQL 同步数据到 TiDB 时，如果 TiDB 不支持对应的 SQL 语句，可能会造成错误并中断同步任务。在这种情况下，DM 提供以下两种方式来恢复同步： - -- 使用 dmctl 来手动跳过该 SQL 语句对应的 binlog event。 -- 使用 dmctl 来手动指定其他 SQL 语句来替代该 SQL 语句对应的 binlog event，并向下游执行。 - -如果提前预知将要同步 TiDB 不支持的 SQL 语句，也可以使用 dmctl 来手动预设跳过/替代执行操作。当 DM 尝试将该 SQL 语句对应的 binlog event 同步到下游时，该预设的操作将自动执行，从而避免同步过程被中断。 - -## 使用限制 - -- 跳过/替代执行操作只适合用于一次性跳过/替代执行**下游 TiDB 不支持执行的 SQL 语句**，其它同步错误请不要使用此方式进行处理。 - - - 其它同步错误可尝试使用 [black & white table lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) 或 [binlog event filter](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter)。 - -- 如果业务不能接受下游 TiDB 跳过异常的 DDL 语句，也不接受使用其他 DDL 语句作为替代，则不适合使用此方式进行处理。 - - - 比如：`DROP PRIMARY KEY` - - 这种情况下，只能在下游重建一个（DDL 执行完后的）新表结构对应的表，并将原表的全部数据重新导入该新表。 - -- 单次跳过/替代执行操作都是针对单个 binlog event 的。 - -- `--sharding` 仅用于对 sharding group 预设一些操作，并且必须在 DDL 语句执行之前预设，不能在 DDL 语句已经执行后预设。 - - - `--sharding` 模式下只支持预设，并只能使用 `--sql-pattern` 来匹配 binlog event。 - - 有关使用 DM 处理 sharding DDL 同步的原理，请参阅[分库分表合并同步原理](/v2.1/reference/tools/data-migration/features/shard-merge.md#实现原理)。 - -## 匹配 binlog event - -当同步任务由于执行 SQL 语句出错而中断时，可以使用 `query-error` 命令获取对应 binlog event 的 position 信息。在执行 `sql-skip` / `sql-replace` 时，通过指定该 position 信息，即可与对应的 binlog event 进行匹配。 - -然而，在同步中断前主动处理不被支持的 SQL 语句的情况下，由于无法提前预知 binlog event 的 position 信息，则需要使用其他方式来确保与后续将到达的 binlog event 进行匹配。 - -在 DM 中，支持如下两种 binlog event 匹配模式（两种模式只能选择其中一种）： - -1. binlog position：binlog event 的 position 信息 - - - binlog position 在命令中使用 `--binlog-pos` 参数传入，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - DM 中 binlog filename 的格式与上游 MySQL 中 binlog filename 的格式不完全一致。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -2. DDL pattern：（仅限于 DDL 语句的）正则表达式匹配模式 - - - DDL pattern 在命令中使用 `--sql-pattern` 参数传入，如要匹配 ```ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` ```，则对应的正则表达式为 ```~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` ```。 - - 正则表达式必须以 `~` 为前缀，且不包含任何原始空格（正则表达式字符串中的空格均以 `\s` 或 `\s+` 表示）。 - -对于合库合表场景，如果需要由 DM 自动选择 DDL lock owner 来执行跳过/替代执行操作，则由于不同 DM-worker 上 DDL 语句对应的 binlog position 无逻辑关联且难以确定，因此只能使用 DDL pattern 匹配模式。 - -> **注意：** -> -> - 一个 binlog event 只能注册一个使用 `--binlog-pos` 指定的 operator，后注册的 operator 会覆盖之前已经注册的 operator。 -> - 不要尝试为一个 binlog event 同时使用 `--binlog-pos` 和 `--sql-pattern` 指定 operator。 -> - operator 在与 binlog event 匹配成功后（而非执行成功后）即会被删除，后续如果需要再进行（`--sql-pattern`）匹配则必须重新注册。 - -## 支持场景 - -- 场景一：同步过程中，上游执行了 TiDB 不支持的 DDL 语句并同步到了 DM，造成同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 跳过对该 DDL 语句的同步以恢复同步任务。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 替代该 DDL 的同步以恢复同步任务。 - -- 场景二：同步过程中，预先知道了上游将执行 TiDB 不支持的 DDL 语句，则需要提前处理以避免同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 预设一个跳过该 DDL 语句的操作，当执行到该 DDL 语句时即自动跳过。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 预设一个替代该 DDL 语句的操作，当执行到该 DDL 语句时即自动替代。 - -## 实现原理 - -DM 在进行增量数据同步时，简化后的流程大致为： - -1. relay 处理单元从上游拉取 binlog 存储在本地作为 relay log。 - -2. binlog 同步单元（sync）读取本地 relay log，获取其中的 binlog event。 - -3. binlog 同步单元解析该 binlog event 并构造 DDL/DML 语句，然后将这些语句向下游 TiDB 执行。 - -在 binlog 同步单元解析完 binlog event 并向下游 TiDB 执行时，可能会由于 TiDB 不支持对应的 SQL 语句而报错并造成同步中断。 - -在 DM 中，可以为 binlog event 注册一些跳过/替代执行操作（operator）。在向下游 TiDB 执行 SQL 语句前，将当前的 binlog event 信息（position、DDL 语句）与注册的 operator 进行比较。如果 position 或 DDL 语句与注册的某个 operator 匹配，则执行该 operator 对应的操作并将该 operator 移除。 - -**同步中断后使用 `sql-skip` 或 `sql-replace` 恢复同步的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 binlog position 或 DDL pattern 注册 operator。 - -2. 使用 `resume-task` 恢复之前由于同步出错导致中断的任务。 - -3. 重新解析获得之前造成同步出错的 binlog event。 - -4. 该 binlog event 与第一步注册的 operator 匹配成功。 - -5. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -**同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 DDL pattern 注册 operator。 - -2. 从 relay log 中解析获得 binlog event。 - -3. （包含 TiDB 不支持 SQL 语句的）binlog event 与第一步注册的 operator 匹配成功。 - -4. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务，任务不发生中断。 - -**合库合表同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace`（在 DM-master 上）为指定的 DDL pattern 注册 operator。 - -2. 各 DM-worker 从 relay log 中解析获得 binlog event。 - -3. DM-master 协调各个 DM-worker 进行 DDL lock 同步。 - -4. DM-master 判断得知 DDL lock 同步成功后，将第一步注册的 operator 发送给 DDL lock owner。 - -5. DM-master 请求 DDL lock owner 执行 DDL 语句。 - -6. DDL lock owner 将要执行的 DDL 语句与第四步收到的 operator 匹配成功。 - -7. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -## 命令介绍 - -使用 dmctl 手动处理 TiDB 不支持的 SQL 语句时，主要使用的命令包括 `query-status`、`query-error`、`sql-skip` 和 `sql-replace`。 - -### query-status - -`query-status` 命令用于查询当前 DM-worker 内子任务及 relay 单元等的状态，详见[查询状态](/v2.1/reference/tools/data-migration/query-status.md)。 - -### query-error - -`query-error` 命令用于查询 DM-worker 内子任务及 relay 单元当前在运行中存在的错误。 - -#### 命令用法 - -```bash -query-error [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选； - - 不指定时查询所有 DM-worker 上的错误，指定时仅查询特定一组 DM-worker 上的错误。 - -+ `task-name`： - - 非 flag 参数，string，可选； - - 不指定时查询所有任务内的错误，指定时仅查询特定任务内的错误。 - -#### 结果示例 - -```bash -» query-error test -{ - "result": true, # query-error 操作本身是否成功 - "msg": "", # query-error 操作失败的说明信息 - "workers": [ # DM-worker 信息列表 - { - "result": true, # 该 DM-worker 上 query-error 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 的 IP:port（worker-id） - "msg": "", # 该 DM-worker 上 query-error 操作失败的说明信息 - "subTaskError": [ # 该 DM-worker 上运行子任务的错误信息 - { - "name": "test", # 任务名 - "stage": "Paused", # 当前任务的状态 - "unit": "Sync", # 当前正在处理任务的处理单元 - "sync": { # binlog 同步单元（sync）的错误信息 - "errors": [ # 当前处理单元的错误信息列表 - { - // 错误信息描述 - "msg": "exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, err:Error 1105: unsupported modify column length 10 is less than origin 11", - // 发生错误的 binlog event 的 position - "failedBinlogPosition": "mysql-bin|000001.000003:34642", - // 发生错误的 SQL 语句 - "errorSQL": "[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]" - } - ] - } - } - ], - "RelayError": { # 该 DM-worker 上 relay 处理单元的错误信息 - "msg": "" # 错误信息描述 - } - } - ] -} -``` - -### sql-skip - -`sql-skip` 命令用于预设一个跳过操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。 - -#### 命令用法 - -```bash -sql-skip <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`； - - 未指定 `--sharding` 时必选，指定 `--sharding` 时禁止使用； - - `worker` 指定预设操作将生效的 DM-worker。 - -+ `binlog-pos`： - - flag 参数，string，`--binlog-pos`； - - `binlog-pos` 与 `--sql-pattern` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `binlog-pos` 与 binlog event 的 position 匹配时生效，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -+ `sql-pattern`： - - flag 参数，string，`--sql-pattern`； - - `--sql-pattern` 与 `binlog-pos` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `sql-pattern` 与 binlog event 对应的（经过可选的 router-rule 转换后的）DDL 语句匹配时生效。格式为以 `~` 为前缀的正则表达式，如 ```~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT```。 - - 暂时不支持正则表达式中包含原始空格，需要使用 `\s` 或 `\s+` 替代空格。 - - 正则表达式必须以 `~` 为前缀，详见[正则表达式语法](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。 - - 正则表达式中的库名和表名必须是经过可选的 router-rule 转换后的名字，即对应下游的目标库名和表名。如上游为 ``` `shard_db_1`.`shard_tbl_1` ```，下游为 ``` `shard_db`.`shard_tbl` ```，则应该尝试匹配 ``` `shard_db`.`shard_tbl` ```。 - - 正则表达式中的库名、表名及列名需要使用 ``` ` ``` 标记，如 ``` `db1`.`tbl1` ```。 - -+ `sharding`： - - flag 参数，boolean，`--sharding`； - - 未指定 `--worker` 时必选，指定 `--worker` 时禁止使用； - - 在指定时表示预设的操作将在 sharding DDL 同步过程中的 DDL lock owner 内生效。 - -+ `task-name`： - - 非 flag 参数，string，必选； - - 指定预设的操作将生效的任务。 - -### sql-replace - -`sql-replace` 命令用于预设一个替代执行操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替代执行操作。 - -#### 命令用法 - -```bash -sql-replace <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -#### 参数解释 - -+ `worker`： - - 与 `sql-skip` 命令的 `--worker` 参数解释一致。 - -+ `binlog-pos`： - - 与 `sql-skip` 命令的 `--binlog-pos` 参数解释一致。 - -+ `sql-pattern`： - - 与 `sql-skip` 命令的 `--sql-pattern` 参数解释一致。 - -+ `sharding`： - - 与 `sql-skip` 命令的 `--sharding` 参数解释一致。 - -+ `task-name`： - - 与 `sql-skip` 命令的 `task-name` 参数解释一致。 - -+ `SQLs`： - - 非 flag 参数，string，必选； - - `SQLs` 指定将用于替代原 binlog event 的新的 SQL 语句。多条 SQL 语句间以 `;` 分隔，如 ```ALTER TABLE shard_db.shard_table drop index idx_c2;ALTER TABLE shard_db.shard_table DROP COLUMN c2;```。 - -## 使用示例 - -### 同步中断后被动执行跳过操作 - -#### 应用场景 - -假设现在需要将上游的 `db1.tbl1` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -```sql -mysql> SHOW CREATE TABLE db1.tbl1; -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl1 | CREATE TABLE `tbl1` ( - `c1` int(11) NOT NULL, - `c2` decimal(11,3) DEFAULT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（将列的 DECIMAL(11, 3) 修改为 DECIMAL(10, 3)）： - -```sql -ALTER TABLE db1.tbl1 CHANGE c2 c2 DECIMAL (10, 3); -``` - -则会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -```bash -exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, -err:Error 1105: unsupported modify column length 10 is less than origin 11 -``` - -此时使用 `query-status` 查询任务状态，可看到 `stage` 转为了 `Paused`，且 `errors` 中有相关的错误描述信息。 - -使用 `query-error` 可以获取该错误的详细信息。比如，执行 `query-error test` 可获得出错的 binlog event 的 position（`failedBinlogPosition`）为 `mysql-bin|000001.000003:34642`。 - -#### 被动跳过 SQL 语句 - -假设业务上可以接受下游 TiDB 不执行此 DDL 语句（即继续保持原有的表结构），则可以通过使用 `sql-skip` 命令跳过该 DDL 语句以恢复同步任务。操作步骤如下： - -1. 使用 `query-error` 获取同步出错的 binlog event 的 position 信息。 - - position 信息可直接由 `query-error` 返回的 `failedBinlogPosition` 获得。 - - 本示例中的 position 为 `mysql-bin|000001.000003:34642`。 - -2. 使用 `sql-skip` 预设一个 binlog event 跳过操作，该操作将在使用 `resume-task` 后同步该 binlog event 到下游时生效。 - - ```bash - » sql-skip --worker=127.0.0.1:8262 --binlog-pos=mysql-bin|000001.000003:34642 test - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 11:17:51 operator.go:121: [info] [sql-operator] set a new operator - uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - on replication unit - ``` - -3. 使用 `resume-task` 恢复之前出错中断的同步任务。 - - ```bash - » resume-task --worker=127.0.0.1:8262 test - { - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "op": "Resume", - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 11:27:46 operator.go:158: [info] [sql-operator] binlog-pos (mysql-bin|000001.000003, 34642) matched, - applying operator uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - ``` - -4. 使用 `query-status` 确认该任务的 `stage` 已经转为 `Running`。 - -5. 使用 `query-error` 确认原错误信息已不再存在。 - -### 同步中断前主动执行替代执行操作 - -#### 应用场景 - -假设现在需要将上游的 `db2.tbl2` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -```sql -mysql> SHOW CREATE TABLE db2.tbl2; -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl2 | CREATE TABLE `tbl2` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -```sql -ALTER TABLE db2.tbl2 DROP COLUMN c2; -``` - -当同步该 DDL 语句对应的 binlog event 到下游时，会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -```bash -exec sqls[[USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 为该 DDL 语句预设一个跳过（skip）或替代执行（replace）操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP 列 c2。 - -#### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的 DDL 语句（经过可选的 router-rule 转换后的 DDL 语句）设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE db2.tbl2 DROP COLUMN c2;`。 - - 由于该 DDL 语句不存在 router-rule 转换，可设计如下正则表达式： - - ```sql - ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - ```sql - ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - -3. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - ```bash - » sql-replace --worker=127.0.0.1:8262 --sql-pattern=~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 15:33:13 operator.go:121: [info] [sql-operator] set a new operator - uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - on replication unit - ``` - -4. 在上游 MySQL 执行该 DDL 语句。 - -5. 观察下游表结构是否变更成功，对应 DM-worker 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 15:33:45 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;, - applying operator uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, - pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - -6. 使用 `query-status` 确认该任务的 `stage` 持续为 `Running`。 - -7. 使用 `query-error` 确认不存在 DDL 执行错误。 - -### 合库合表场景下同步中断后被动执行跳过操作 - -#### 应用场景 - -假设现在通过多个 DM-worker 将上游多个 MySQL 实例内的多个表进行合库合表同步到下游 TiDB 的同一个表，并且上游各分表执行了 TiDB 不支持的 DDL 语句。 - -DM-master 通过 DDL lock 协调 DDL 同步、并请求 DDL lock owner 向下游 TiDB 执行该 DDL 语句后，由于 TiDB 不支持该 DDL 语句，同步任务会报错并中断。 - -#### 被动跳过 SQL 语句 - -合库合表场景下，被动跳过 TiDB 不支持的 DDL 语句的处理方式与非合库合表场景下的[同步中断后被动执行跳过操作](#同步中断后被动执行跳过操作)基本一致。 - -但在合库合表场景下，只需要 DDL lock owner 向下游同步该 DDL 语句，因此在两种场景下的处理过程主要存在以下区别： - -1. 合库合表场景下，仅需要对 DDL lock owner 执行 `sql-skip`（`--worker={DDL-lock-owner}`）。 - -2. 合库合表场景下，仅需要对 DDL lock owner 执行 `resume-task`（`--worker={DDL-lock-owner}`）。 - -### 合库合表场景下同步中断前主动执行替代执行操作 - -#### 应用场景 - -假设现在存在如下四个上游表需要合并同步到下游的同一个表 ``` `shard_db`.`shard_table` ```： - -- MySQL 实例 1 内有 `shard_db_1` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 -- MySQL 实例 2 内有 `shard_db_2` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 - -初始时表结构为： - -```sql -mysql> SHOW CREATE TABLE shard_db_1.shard_table_1; -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -此时，在上游所有分表上都执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -```sql -ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2; -``` - -则当 DM 通过 sharding DDL lock 协调两个 DM-worker 同步该 DDL 语句、并请求 DDL lock owner 向下游执行该 DDL 语句时，会由于 TiDB 不支持该 DDL 语句而导致同步任务中断且报如下错误： - -```bash -exec sqls[[USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 命令为该 DDL 语句预设一个跳过/替代执行操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP c2 列。 - -#### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的（经过可选的 router-rule 转换后的）DDL 语句设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2`。 - - 由于存在 router-rule 会将表名转换为 ``` `shard_db`.`shard_table` ```，可设计如下正则表达式： - - ```sql - ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - ```sql - ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - -3. 由于这是合库合表场景，因此使用 `--sharding` 参数来由 DM 自动确定替代执行操作只发生在 DDL lock owner 上。 - -4. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - ```bash - » sql-replace --sharding --sql-pattern=~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - { - "result": true, - "msg": "request with --sharding saved and will be sent to DDL lock's owner when resolving DDL lock", - "workers": [ - ] - } - ``` - - **DM-master** 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 16:53:33 operator.go:105: [info] [sql-operator] set a new operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" - op:REPLACE args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -5. 在上游 MySQL 实例的分表上执行 DDL 语句。 - -6. 观察下游表结构是否变更成功，对应的 DDL lock **owner** 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 16:54:35 operator.go:121: [info] [sql-operator] set a new operator - uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - on replication unit - ``` - - ```bash - 2018/12/28 16:54:35 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;, - applying operator uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - 另外，**DM-master** 节点中也可以看到类似如下日志： - - ```bash - 2018/12/28 16:54:35 operator.go:122: [info] [sql-operator] get an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - with key ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - - ```bash - 2018/12/28 16:54:36 operator.go:145: [info] [sql-operator] remove an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -7. 使用 `query-status` 确认任务的 `stage` 持续为 `Running`，且不存在正阻塞同步的 DDL 语句（`blockingDDLs`）与待解决的 sharding group（`unresolvedGroups`）。 - -8. 使用 `query-error` 确认不存在 DDL 执行错误。 - -9. 使用 `show-ddl-locks` 确认不存在待解决的 DDL lock。 diff --git a/v2.1/reference/tools/data-migration/table-selector.md b/v2.1/reference/tools/data-migration/table-selector.md deleted file mode 100644 index 104103374f8f..000000000000 --- a/v2.1/reference/tools/data-migration/table-selector.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Table Selector -summary: 介绍 DM 的 Table Selector -category: reference ---- - -# Table Selector - -Table Selector 提供了一种基于[通配符](https://zh.wikipedia.org/wiki/%E9%80%9A%E9%85%8D%E7%AC%A6) 来匹配指定 `schema/table` 的功能。 - -## 通配符 - -table selector 在 `schema-pattern`/`table-pattern` 中可以使用以下两个通配符： - -+ 星号(`*`) - - - 匹配零个或者多个字符。例如， `doc*` 匹配 `doc` 和 `document`，但是不匹配 `dodo`。 - - `*` 只能放在 pattern 的最后一位，例如，支持 `doc*`，但是不支持 `do*c`。 - -+ 问号(`?`) - - - 匹配任意一个空字符除外的字符。 - -## 匹配规则 - -- `schema-pattern` 限制不能为空； -- `table-pattern` 可以设置为空。设置为空时，将只根据 `schema-pattern` 对 `schema` 进行匹配，然后返回匹配结果； -- `table-pattern` 不为空时，分别根据 `schema-pattern` 和 `table-pattern` 进行匹配，两个都匹配则结果为匹配。 - -## 使用示例 - -- 匹配所有库名以 `schema_` 开头的 schema 和 table - - ```yaml - schema-pattern： "schema_*" - table-pattern： "" - ``` - -- 匹配所有库名以 `schema_` 为前缀，并且表名以 `table_` 前缀的表 - - ```yaml - schema-pattern = "schema_*" - table-pattern = "table_*" - ``` diff --git a/v2.1/reference/tools/data-migration/troubleshoot/dm.md b/v2.1/reference/tools/data-migration/troubleshoot/dm.md deleted file mode 100644 index cc3244ab8820..000000000000 --- a/v2.1/reference/tools/data-migration/troubleshoot/dm.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Data Migration 故障诊断 -category: reference -aliases: ['/docs-cn/v2.1/how-to/troubleshoot/data-migration/'] ---- - -# Data Migration 故障诊断 - -本文总结了在 DM 工具使用过程中遇到问题的诊断流程，并指引用户通过错误信息查找相应的解决方案。 - -如果你在运行 DM 工具时出现了错误，请尝试以下解决方案： - -1. 执行 `query-status` 命令查看任务运行状态以及相关错误输出。 - -2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [Data Migration 错误含义](/v2.1/reference/tools/data-migration/troubleshoot/error-system.md) 获取错误的关键信息，然后查看 [Data Migration 常见错误及修复](/v2.1/reference/tools/data-migration/troubleshoot/error-handling.md)以寻找相应的解决方案。 - -3. 如果该错误还没有相应的解决方案，并且你无法通过查询日志或监控指标自行解决此问题，你可以联系相关销售人员进行支持。 - -4. 一般情况下，错误处理完成后，只需使用 dmctl 重启任务即可。 - - {{< copyable "shell-regular" >}} - - ```bash - resume-task ${task name} - ``` - -但在某些情况下，你还需要重置数据同步任务。有关何时需要重置以及如何重置，详见[重置数据同步任务](/v2.1/reference/tools/data-migration/faq.md#重置数据同步任务)。 diff --git a/v2.1/reference/tools/data-migration/troubleshoot/error-handling.md b/v2.1/reference/tools/data-migration/troubleshoot/error-handling.md deleted file mode 100644 index 66b0ca6c0c6f..000000000000 --- a/v2.1/reference/tools/data-migration/troubleshoot/error-handling.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Data Migration 常见错误修复 -category: reference ---- - -# Data Migration 常见错误修复 - -本文档介绍 DM 中常见的错误以及修复方法。 - -## 常见错误说明和处理方法 - -| 错误码 | 错误说明 | 解决方法 | -| :----------- | :------------------------------------------------------------ | :----------------------------------------------------------- | -| `code=10001` | 数据库操作异常 | 进一步分析错误信息和错误堆栈 | -| `code=10002` | 数据库底层的 `bad connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 | DM 提供针对此类错误的自动恢复。如果长时间未恢复，需要用户检查网络或 TiDB 状态。 | -| `code=10003` | 数据库底层 `invalid connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 | DM 提供针对此类错误的自动恢复。如果未能正常恢复，需要用户进一步检查错误信息并根据具体场景进行分析。 | -| `code=10005` | 数据库查询类语句出错 | | -| `code=10006` | 数据库 `EXECUTE` 类型语句出错，包括 DDL 和 `INSERT`/`UPDATE`/`DELETE` 类型的 DML。更详细的错误信息可通过错误 message 获取。错误 message 中通常包含操作数据库所返回的错误码和错误信息。 | | -| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/v2.1/reference/tools/data-migration/faq.md#处理不兼容的-ddl-语句) 提供的解决方案 | -| `code=20010` | 处理任务配置时，解密数据库的密码出错 | 检查任务配置中提供的下游数据库密码是否有[使用 dmctl 正确加密](/v2.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码) | -| `code=26002` | 任务检查创建数据库连接失败。更详细的错误信息可通过错误 message 获取。错误 message 中包含操作数据库所返回的错误码和错误信息。 | 检查 DM-master 所在的机器是否有权限访问上游 | -| `code=32001` | dump 处理单元异常 | 如果报错 `msg` 包含 `mydumper: argument list too long.`，则需要用户根据 black-white list，在 `task.yaml` 的 mydumper `extra-args` 参数中手动加上 `--regex` 正则表达式设置要导出的库表。例如，如果要导出所有库中表名字为 `hello` 的表，可加上 `--regex '.*\\.hello$'`，如果要导出所有表，可加上 `--regex '.*'`。 | -| `code=38008` | DM 组件间的 gRPC 通信出错 | 检查 `class`， 定位错误发生在哪些组件的交互环节，根据错误 message 判断是哪类通信错误。如果是 gRPC 建立连接出错，可检查通信服务端是否运行正常。 | - -## 同步任务中断并包含 `invalid connection` 错误 - -发生 `invalid connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 - -由于 DM 中存在同步任务并发向下游复制数据的特性，因此在任务中断时可能同时包含多个错误（可通过 `query-status` 或 `query-error` 查询当前错误）。 - -- 如果错误中仅包含 `invalid connection` 类型的错误且当前处于增量复制阶段，则 DM 会自动进行重试。 -- 如果 DM 由于版本问题等未自动进行重试或自动重试未能成功，则可尝试先使用 `stop-task` 停止任务，然后再使用 `start-task` 重启任务。 - -## 同步任务中断并包含 `driver: bad connection` 错误 - -发生 `driver: bad connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 - -当前版本 DM 发生该类型错误时，需要先使用 `stop-task` 停止任务后再使用 `start-task` 重启任务。后续 DM 会完善对此错误类型的自动重试机制。 - -## relay 处理单元报错 `event from * in * diff from passed-in event *` 或同步任务中断并包含 `get binlog error ERROR 1236 (HY000)`、`binlog checksum mismatch, data may be corrupted` 等 binlog 获取或解析失败错误 - -在 DM 进行 relay log 拉取与增量同步过程中，如果遇到了上游超过 4GB 的 binlog 文件，就可能出现这两个错误。 - -原因是 DM 在写 relay log 时需要依据 binlog position 及文件大小对 event 进行验证，且需要保存同步的 binlog position 信息作为 checkpoint。但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，进而出现上面的错误。 - -对于 relay 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 停止 DM-worker。 -3. 将上游对应的 binlog 文件复制到 relay log 目录作为 relay log 文件。 -4. 更新 relay log 目录内对应的 `relay.meta` 文件以从下一个 binlog 开始拉取。 - - 例如：报错时有 `binlog-name = "mysql-bin.004451"` 与`binlog-pos = 2453`，则将其分别更新为 `binlog-name = "mysql-bin.004452"` 与`binlog-pos = 4`。 -5. 重启 DM-worker。 - -对于 binlog replication 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 通过 `stop-task` 停止同步任务。 -3. 将下游 `dm_meta` 数据库中 global checkpoint 与每个 table 的 checkpoint 中的 `binlog_name` 更新为出错的 binlog 文件，将 `binlog_pos` 更新为已同步过的一个合法的 position 值，比如 4。 - - 例如：出错任务名为 `dm_test`，对应的 `source-id` 为 `replica-1`，出错时对应的 binlog 文件为 `mysql-bin|000001.004451`，则执行 `UPDATE dm_test_syncer_checkpoint SET binlog_name='mysql-bin|000001.004451', binlog_pos = 4 WHERE id='replica-1';`。 -4. 在同步任务配置中为 `syncers` 部分设置 `safe-mode: true` 以保证可重入执行。 -5. 通过 `start-task` 启动同步任务。 -6. 通过 `query-status` 观察同步任务状态，当原造成出错的 relay log 文件同步完成后，即可还原 `safe-mode` 为原始值并重启同步任务。 - -## 执行 `query-status` 或查看日志时出现 `Access denied for user 'root'@'172.31.43.27' (using password: YES)` - -在所有 DM 配置文件中，数据库相关的密码都必须使用经 dmctl 加密后的密文（若数据库密码为空，则无需加密）。有关如何使用 dmctl 加密明文密码，参见[使用 dmctl 加密上游 MySQL 用户密码](/v2.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -此外，在 DM 运行过程中，上下游数据库的用户必须具备相应的读写权限。在启动同步任务过程中，DM 会自动进行相应权限的前置检查，详见[上游 MySQL 实例配置前置检查](/v2.1/reference/tools/data-migration/precheck.md)。 diff --git a/v2.1/reference/tools/data-migration/troubleshoot/error-system.md b/v2.1/reference/tools/data-migration/troubleshoot/error-system.md deleted file mode 100644 index 3d5f69c5be65..000000000000 --- a/v2.1/reference/tools/data-migration/troubleshoot/error-system.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Data Migration 错误说明 -category: reference ---- - -# Data Migration 错误说明 - -本文介绍了 Data Migration (DM) 的错误系统，以及各种错误信息的详细含义。 - -## DM 错误系统 - -DM 1.0.0-GA 版本中引入了新的错误系统。该系统： - -+ 增加了错误码机制。 -+ 增加了 `class`、`scope`、`level` 等错误信息。 -+ 优化了错误描述内容、错误调用链信息和调用堆栈信息。 - -错误系统的详细设计和实现，可参阅 [RFC 文档: Proposal: Improve Error System](https://github.com/pingcap/dm/blob/master/docs/RFCS/20190722_error_handling.md)。 - -## 错误信息示例 - -以下是 DM 实际输出的一条错误信息。本文根据这条信息，对各个字段作详细说明。 - -``` -[code=38008:class=dm-master:scope=internal:level=high] grpc request error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused" -github.com/pingcap/dm/pkg/terror.(*Error).Delegate - /root/code/gopath/src/github.com/pingcap/dm/pkg/terror/terror.go:267 -github.com/pingcap/dm/dm/master/workerrpc.callRPC - /root/code/gopath/src/github.com/pingcap/dm/dm/master/workerrpc/rawgrpc.go:124 -github.com/pingcap/dm/dm/master/workerrpc.(*GRPCClient).SendRequest - /root/code/gopath/src/github.com/pingcap/dm/dm/master/workerrpc/rawgrpc.go:64 -github.com/pingcap/dm/dm/master.(*Server).getStatusFromWorkers.func2 - /root/code/gopath/src/github.com/pingcap/dm/dm/master/server.go:1125 -github.com/pingcap/dm/dm/master.(*AgentPool).Emit - /root/code/gopath/src/github.com/pingcap/dm/dm/master/agent_pool.go:117 -runtime.goexit - /root/.gvm/gos/go1.12/src/runtime/asm_amd64.s:1337 -``` - -DM 中的错误信息均按以下固定格式输出： - -``` -[错误基本信息] + 错误 message 描述 + 错误堆栈信息（可选） -``` - -### 错误基本信息 - -- `code`：错误码，错误唯一标识。 - - 同一种错误都使用相同的错误码。错误码不随 DM 版本改变。 - - 在 DM 迭代过程中，部分错误可能会被移除，但错误码不会。新增的错误会使用新的错误码，不会复用已有的错误码。 - -- `class`：错误分类。 - - 用于标记出现错误的系统子模块。 - - 下表展示所有的错误类别、错误对应的系统子模块、错误样例： - - | 错误类别 | 错误对应的系统子模块 | 错误样例 | - | :-------------- | :------------------------------ | :------------------------------------------------------------ | - | `database` | 执行数据库操作出现错误 | `[code=10003:class=database:scope=downstream:level=medium] database driver: invalid connection` | - | `functional` | 系统底层的基础函数错误 | `[code=11005:class=functional:scope=internal:level=high] not allowed operation: alter multiple tables in one statement` | - | `config` | 配置错误 | `[code=20005:class=config:scope=internal:level=medium] empty source-id not valid` | - | `binlog-op` | binlog 操作出现错误 | `[code=22001:class=binlog-op:scope=internal:level=high] empty UUIDs not valid` | - | `checkpoint` | checkpoint 相关操作出现错误 | `[code=24002:class=checkpoint:scope=internal:level=high] save point bin.1234 is older than current pos bin.1371` | - | `task-check` | 进行任务检查时出现错误 | `[code=26003:class=task-check:scope=internal:level=medium] new table router error` | - | `relay-event-lib`| 执行 relay 模块基础功能时出现错误 | `[code=28001:class=relay-event-lib:scope=internal:level=high] parse server-uuid.index` | - | `relay-unit` | relay 处理单元内出现错误 | `[code=30015:class=relay-unit:scope=upstream:level=high] TCPReader get event: ERROR 1236 (HY000): Could not open log file` | - | `dump-unit` | dump 处理单元内出现错误 | `[code=32001:class=dump-unit:scope=internal:level=high] mydumper runs with error: CRITICAL **: 15:12:17.559: Error connecting to database: Access denied for user 'root'@'172.17.0.1' (using password: NO)` | - | `load-unit` | load 处理单元内出现错误 | `[code=34002:class=load-unit:scope=internal:level=high] corresponding ending of sql: ')' not found` | - | `sync-unit` | sync 处理单元内出现错误 | `[code=36027:class=sync-unit:scope=internal:level=high] Column count doesn't match value count: 9 (columns) vs 10 (values)` | - | `dm-master` | DM-master 服务内部出现错误 | `[code=38008:class=dm-master:scope=internal:level=high] grpc request error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused"` | - | `dm-worker` | DM-worker 服务内部出现错误 | `[code=40066:class=dm-worker:scope=internal:level=high] ExecuteDDL timeout, try use query-status to query whether the DDL is still blocking` | - | `dm-tracer` | DM-tracer 服务内部出现错误 | `[code=42004:class=dm-tracer:scope=internal:level=medium] trace event test.1 not found` | - -- `scope`：错误作用域。 - - 用于标识错误发生时 DM 作用对象的范围和来源，包括未设置 (not-set)、上游数据库 (upstream)、下游数据库 (downstream)、内部 (internal) 四种类型。 - - 如果错误发生的逻辑直接涉及到上下游数据库请求，作用域会设置为 upstream 或 downstream，其他出错场景目前都设置为 internal。 - -- `level`：错误级别。 - - 错误的严重级别，包括低级别 (low)、中级别 (medium)、高级别 (high) 三种。 - - 低级别通常是用户操作、输入错误，不影响正常同步任务；中级别通常是用户配置等错误，会影响部分新启动服务，不影响已有系统同步状态；高级别通常是用户需要关注的一些错误，可能存在同步任务中断等风险，需要用户进行处理。 - -在上述的错误样例中： - -- `code=38008` 表示 gRPC 通信出错的错误码。 -- `class=dm-master`，表示 DM-master 对外发送 gRPC 请求时出错（请求发送至 DM-worker）。 -- `scope=interal` 表示 DM 内部出现错误。 -- `level=high`，表示这是一个高级别错误，需要用户注意。可根据错误 message 和错误堆栈判断出更多错误信息。 - -### 错误 message 描述 - -错误 message 使用描述性语言来表示错误的详细信息。对于错误调用链上每一层额外增加的错误 message，采用 [errors.Wrap](https://godoc.org/github.com/pkg/errors#hdr-Adding_context_to_an_error) 的模式来叠加和保存错误 message。wrap 最外层的 message 是 DM 内部对该错误的描述，wrap 最内层的 message 是该错误最底层出错位置的错误描述。 - -以上述样例错误的 message 为例： - -- wrap 最外层 message，`grpc request error` 是 DM 对该错误的描述。 -- wrap 最内层 message，`connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused"`，是 gRPC 底层建立连接失败时返回的错误。 - -通过对基本错误信息和错误 message 进行分析，可以诊断出错误是在 DM-master 向 DM-worker 发送 gRPC 请求建立连接失败时出现的。该错误通常是由 DM-worker 未正常运行引起。 - -### 错误堆栈信息 - -DM 根据错误的严重程度和必要性来选择是否输出错误堆栈。错误堆栈记录了错误发生时完整的堆栈调用信息。如果用户通过错误基本信息和错误 message 描述不能完全诊断出错误发生的原因，可以通过错误堆栈进一步跟进出错时代码的运行路径。 - -## 常见错误码描述及处理 - -可在 DM 代码仓库[已发布的错误码](https://github.com/pingcap/dm/blob/master/_utils/terror_gen/errors_release.txt)中查询完整的错误码列表。 diff --git a/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md b/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md deleted file mode 100644 index 0541117759d0..000000000000 --- a/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 分表合并数据迁移最佳实践 -summary: 使用 DM 对分库分表进行合并迁移时的最佳实践。 -category: reference ---- -# 分表合并数据迁移最佳实践 - -本文阐述了使用 TiDB Data Migration（以下简称 DM）对分库分表进行合并迁移的场景中，DM 相关功能的支持和限制，旨在给出一个业务的最佳实践。 - -## 独立的数据迁移任务 - -在[分库分表合并同步的实现原理部分](/v2.1/reference/tools/data-migration/features/shard-merge.md#实现原理)，我们介绍了 sharding group 的概念，简单来说可以理解为需要合并到下游同一个表的所有上游表即组成一个 sharding group。 - -当前的 sharding DDL 算法为了能协调在不同分表执行 DDL 对 schema 变更的影响，加入了一些[使用限制](/v2.1/reference/tools/data-migration/features/shard-merge.md#使用限制)。而当这些使用限制由于某些异常原因被打破时，我们需要[手动处理 Sharding DDL Lock](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) 甚至是完整重做整个数据迁移任务。 - -因此，为了减小异常发生时对数据迁移的影响，我们推荐将每一个 sharding group 拆分成一个独立的数据迁移任务。**这样当异常发生时，可能只有少部分迁移任务需要进行手动处理，其他数据迁移任务可以不受影响。** - -## 手动处理 sharding DDL lock - -从[分库分表合并同步的实现原理部分](/v2.1/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，DM 中的 sharding DDL lock 是用于协调不同上游分表向下游执行 DDL 的一种机制，本身并不是异常。 - -因此，当通过 `show-ddl-locks` 查看到 DM-master 上存在 sharding DDL lock 时，或通过 `query-status` 查看到某些 DM-worker 有 `unresolvedGroups` 或 `blockingDDLs` 时，并不要急于使用 `unlock-ddl-lock` 或 `break-ddl-lock` 尝试去手动解除 sharding DDL lock。 - -只有在确认当前未能自动解除 sharding DDL lock 是文档中所列的[支持场景](/v2.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#支持场景)之一时，才能参照对应支持场景中的手动处理示例进行处理。对于其他未被支持的场景，我们建议完整重做整个数据迁移任务，即清空下游数据库中的数据以及该数据迁移任务相关的 `dm_meta` 信息后，重新执行全量数据及增量数据的迁移。 - -## 自增主键冲突处理 - -在 DM 中，我们提供了 [Column mapping](/v2.1/reference/tools/data-migration/features/overview.md#column-mapping) 用于处理 bigint 类型的自增主键在合并时可能出现冲突的问题，但我们**强烈不推荐**使用该功能。如果业务上允许，我们推荐使用以下两种处理方式。 - -### 去掉自增主键的主键属性 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_no_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -- `auto_pk_c1` 列对业务无意义，且不依赖该列的 `PRIMARY KEY` 属性。 -- `uk_c2` 列有 `UNIQUE KEY` 属性，且能保证在所有上游分表间全局唯一。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但将 `auto_pk_c1` 的 `PRIMARY KEY` 属性修改为普通索引。 - - ```sql - CREATE TABLE `tbl_no_pk_2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - INDEX (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 使用联合主键 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_multi_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -* 业务不依赖 `auto_pk_c1` 的 `PRIMARY KEY` 属性。 -* `auto_pk_c1` 与 `uuid_c2` 的组合能确保全局唯一。 -* 业务能接受将 `auto_pk_c1` 与 `uuid_c2` 组成联合 `PRIMARY KEY`。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但不为 `auto_pk_c1` 指定 `PRIMARY KEY` 属性，而是将 `auto_pk_c1` 与 `uuid_c2` 一起组成 `PRIMARY KEY`。 - - ```sql - CREATE TABLE `tbl_multi_pk_c2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`,`uuid_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 - -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -## 合表迁移过程中在上游增/删表 - -从[分库分表合并同步的实现原理部分](/v2.1/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，sharding DDL lock 的协调依赖于是否已收到上游已有各分表对应的 DDL，且当前 DM 在合表迁移过程中暂时**不支持**在上游动态增加或删除分表。如果需要在合表迁移过程中，对上游执行增、删分表操作，推荐按以下方式进行处理。 - -### 在上游增加分表 - -如果需要在上游增加新的分表，推荐按以下顺序执行操作： - -1. 等待在上游分表上执行过的所有 sharding DDL 协调同步完成。 -2. 通过 `stop-task` 停止任务。 -3. 在上游添加新的分表。 -4. 确保 `task.yaml` 配置能使新添加的分表与其他已有的分表能合并到同一个下游表。 -5. 通过 `start-task` 启动任务。 -6. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 在上游删除分表 - -如果需要在上游删除原有的分表，推荐按以下顺序执行操作： - -1. 在上游删除原有的分表，并通过 [`SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/5.7/en/show-binlog-events.html) 获取该 `DROP TABLE` 语句在 binlog 中对应的 `End_log_pos`，记为 _Pos-M_。 -2. 通过 `query-status` 获取当前 DM 已经处理完成的 binlog event 对应的 position（`syncerBinlog`），记为 _Pos-S_。 -3. 当 _Pos-S_ 比 _Pos-M_ 更大后，则说明 DM 已经处理完 `DROP TABLE` 语句，且该表在被删除前的数据都已经同步到下游，可以进行后续操作；否则，继续等待 DM 进行数据同步。 -4. 通过 `stop-task` 停止任务。 -5. 确保 `task.yaml` 配置能忽略上游已删除的分表。 -6. 通过 `start-task` 启动任务。 -7. 通过 `query-status` 验证数据迁移任务是否正常。 - -## 数据迁移限速/流控 - -当将多个上游 MySQL/MariaDB 实例的数据合并迁移到下游同一个 TiDB 集群时，由于每个与上游 MySQL/MariaDB 对应的 DM-worker 都会并发地进行全量与增量数据迁移，默认的并发度（全量阶段的 `pool-size` 与增量阶段的 `worker-count`）通过多个 DM-worker 累加后，可能会给下游造成过大的压力，此时应根据 TiDB 监控及 DM 监控进行初步的性能分析后，适当地调整各并发度参数的大小。后续 DM 也将考虑支持部分自动的流控策略。 diff --git a/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md b/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md deleted file mode 100644 index 1b9e8cc00d0e..000000000000 --- a/v2.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 切换 DM-worker 与上游 MySQL 实例的连接 -summary: 了解如何切换 DM-worker 与上游 MySQL 实例的连接。 -category: reference ---- - -# 切换 DM-worker 与上游 MySQL 实例的连接 - -当需要对 DM-worker 所连接的上游 MySQL 实例进行停机维护或该实例意外宕机时，需要将 DM-worker 的连接切换到同一个主从复制集群内的另一个 MySQL 实例上。本文介绍如何将 DM-worker 的连接从一个 MySQL 实例切换到另一个 MySQL 实例上。 - -> **注意：** -> -> - 仅支持在同一个主从复制集内的 MySQL 实例间进行切换。 -> - 将要切换到的 MySQL 实例必须拥有 DM-worker 所需的 binlog。 -> - DM-worker 必须以 GTID sets 模式运行，即 DM 通过 DM-Ansible 部署时必须指定 `enable_gtid=true`。 -> - DM 仅支持以下两种切换场景，且必须严格按照各场景的步骤执行操作，否则可能需要根据切换后的 MySQL 实例重新搭建 DM 集群并完整重做数据迁移任务。 - -有关 GTID sets 的概念解释，请参考 [MySQL 文档](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html#replication-gtids-concepts-gtid-sets)。 - -## 虚拟 IP 环境下切换 DM-worker 与 MySQL 实例的连接 - -如果 DM-worker 通过虚拟 IP (VIP) 连接上游的 MySQL 实例，更改 VIP 所指向的 MySQL 实例，即是在 DM-worker 对应上游连接地址不变的情况下切换 DM-worker 实际所连接的 MySQL 实例。 - -> **注意：** -> -> 如果不对 DM 执行必要变更，当切换 VIP 所指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。 - -如果 DM-worker 连接的 VIP 需要指向新的 MySQL 实例，需要按以下步骤进行操作： - -1. 使用 `query-status` 命令获取当前 relay 处理单元已从原 MySQL 实例获取到的 binlog 对应的 GTID sets (`relayBinlogGtid`)，记为 `gtid-W`。 -2. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_purged;` 获取已经被 purged 的 binlog 对应的 GTID sets，记为 `gtid-P`。 -3. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_executed;` 获取所有已经执行成功的事务对应的 GTID sets，记为 `gtid-E`。 -4. 确保满足以下关系，否则不支持将 DM-worker 连接切换到相应的 MySQL 实例： - - `gtid-W` 包含 `gtid-P`（`gtid-P` 可以为空） - - `gtid-E` 包含 `gtid-W` -5. 使用 `pause-relay` 命令暂停 relay 处理。 -6. 使用 `pause-task` 命令暂停所有运行中的数据迁移任务。 -7. 变更 VIP 以指向新的 MySQL 实例。 -8. 使用 `switch-relay-master` 命令通知 relay 处理单元进行主从切换。 -9. 使用 `resume-relay` 命令恢复 relay 处理，使其从新的 MySQL 实例读取 binlog。 -10. 使用 `resume-task` 命令恢复之前的数据迁移任务。 - -## 变更 DM-worker 连接的上游 MySQL 实例地址 - -若要变更 DM-worker 的配置信息来使 DM-worker 连接到新的上游 MySQL 实例，需要按以下步骤进行操作： - -1. 使用 `query-status` 命令获取当前 relay 处理单元已从原 MySQL 实例获取到的 binlog 对应的 GTID sets (`relayBinlogGtid`)，记为 `gtid-W`。 -2. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_purged;` 获取已经被 purged 的 binlog 对应的 GTID sets，记为 `gtid-P`。 -3. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_executed;` 获取所有已经执行成功的事务对应的 GTID sets，记为 `gtid-E`。 -4. 确保满足以下关系，否则不支持将 DM-worker 连接切换到相应的 MySQL 实例： - - `gtid-W` 包含 `gtid-P`（`gtid-P` 可以为空） - - `gtid-E` 包含 `gtid-W` -5. 使用 `stop-task` 命令停止所有运行中的数据迁移任务。 -6. 更新 `inventory.ini` 中的 DM-worker 配置，并使用 DM-Ansible 对 DM-worker 进行滚动升级操作。 -7. 使用 `start-task` 命令重新启动数据迁移任务。 diff --git a/v2.1/reference/tools/data-migration/usage-scenarios/shard-merge.md b/v2.1/reference/tools/data-migration/usage-scenarios/shard-merge.md deleted file mode 100644 index e0f488a9af92..000000000000 --- a/v2.1/reference/tools/data-migration/usage-scenarios/shard-merge.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -title: DM 分库分表合并场景 -category: reference ---- - -# DM 分库分表合并场景 - -本文介绍如何在分库分表合并场景中使用 Data Migration (DM)。使用场景中，三个上游 MySQL 实例的分库和分表数据需要同步至下游 TiDB 集群。 - -## 上游实例 - -假设上游库结构如下： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log_north, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log_east, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log_south, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -## 同步需求 - -1. 合并三个实例中的 `user`.`information` 表至下游 TiDB 中的 `user`.`information` 表。 -2. 合并三个实例中的 `user`.`log_{north|south|east}` 表至下游TiDB中的 `user`.`log_{north|south|east}` 表。 -3. 合并三个实例中的 `store_{01|02}`.`sale_{01|02}` 表至下游TiDB中的 `store`.`sale` 表。 -4. 过滤掉三个实例的 `user`.`log_{north|south|east}` 表的所有删除操作。 -5. 过滤掉三个实例的 `user`.`information` 表的所有删除操作。 -6. 过滤掉三个实例的 `store_{01|02}`.`sale_{01|02}` 表的所有删除操作。 -7. 过滤掉三个实例的 `user`.`log_bak` 表。 -8. 因为 `store_{01|02}`.`sale_{01|02}` 表带有 bigint 型的自增主键，将其合并至 TiDB 时会引发冲突。你需要有相应的方案来避免冲突。 - -## 下游实例 - -假设同步后下游库结构如下： - -| Schema | Tables | -|:------|:------| -| user | information, log_north, log_east, log_south| -| store | sale | - -## 同步方案 - -- 要满足同步需求 #1 和 #2，配置 [Table routing 规则](/v2.1/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - ```yaml - routes: - ... - user-route-rule: - schema-pattern: "user" - target-schema: "user" - ``` - -- 要满足同步需求 #3，配置 [table routing 规则](/v2.1/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - ```yaml - routes: - ... - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - ``` - -- 要满足同步需求 #4 和 #5，配置 [Binlog event filter 规则](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - ```yaml - filters: - ... - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - ``` - - > **注意：** - > - > 同步需求 #4、#5 和 #7 的操作意味着过滤掉所有对 `user` 库的删除操作，所以此处配置了库级别的过滤规则。但是 `user` 库以后加入表的删除操作也都会被过滤。 - -- 要满足同步需求 #6，配置 [Binlog event filter 规则](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - ```yaml - filters: - ... - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - ``` - -- 要满足同步需求 #7，配置 [Black & white table lists](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) 如下： - - ```yaml - black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - ``` - -- 要满足同步需求 #8，首先参考[自增主键冲突处理](/v2.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决冲突，保证在同步到下游时不会因为分表中有相同的主键值而使同步出现异常；然后需要配置 `ignore-checking-items` 来跳过自增主键冲突的检查： - - ```yaml - ignore-checking-items: ["auto_increment_ID"] - ``` - -## 同步任务配置 - -同步任务的完整配置如下。详情请参阅 [Data Migration 任务配置文件](/v2.1/reference/tools/data-migration/configure/task-configuration-file.md)。 - -```yaml -name: "shard_merge" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - - source-id: "instance-2" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例共享的其他通用配置 - -routes: - user-route-rule: - schema-pattern: "user" - target-schema: "user" - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - -filters: - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - -black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/v2.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md b/v2.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md deleted file mode 100644 index eaa40d91e9aa..000000000000 --- a/v2.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: Data Migration 简单使用场景 -category: reference ---- - -# Data Migration 简单使用场景 - -本文介绍了 DM 工具的一个简单使用场景（非分库分表合并场景）：将三个上游 MySQL 实例的数据同步到一个下游 TiDB 集群中。 - -## 上游实例 - -假设上游结构为： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_bj, store_tj | - | log | messages | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_sh, store_sz | - | log | messages | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_gz, store_sz | - | log | messages | - -## 同步要求 - -1. 不合并 `user` 库。 - - 1. 将实例 1 中的 `user` 库同步到下游 TiDB 的 `user_north` 库中。 - - 2. 将实例 2 中的 `user` 库同步到下游 TiDB 的 `user_east` 库中。 - - 3. 将实例 3 中的 `user` 库同步到下游 TiDB 的 `user_south` 库中。 - - 4. 任何情况下都不删除 `log` 表的任何数据。 - -2. 将上游 `store` 库同步到下游 `store` 库中，且同步过程中不合并表。 - - 1. 实例 2 和实例 3 中都存在 `store_sz` 表，且这两个 `store_sz` 表分别被同步到下游的 `store_suzhou` 表和 `store_shenzhen` 表中。 - - 2. 任何情况下都不删除 `store` 库的任何数据。 - -3. `log` 库需要被过滤掉。 - -## 下游实例 - -假设下游结构为： - -| Schema | Tables | -|:------|:------| -| user_north | information, log | -| user_east | information, log | -| user_south | information, log | -| store | store_bj, store_tj, store_sh, store_suzhou, store_gz, store_shenzhen | - -## 同步方案 - -- 为了满足[同步要求](#同步要求)中第一点的前三条要求，需要配置以下 [table routing 规则](/v2.1/reference/tools/data-migration/features/overview.md#table-routing)： - - ```yaml - routes: - ... - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第一条要求，需要配置以下 [table routing 规则](/v2.1/reference/tools/data-migration/features/overview.md#table-routing)： - - ```yaml - routes: - ... - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - ``` - -- 为了满足[同步要求](#同步要求)中第一点的第四条要求，需要配置以下 [binlog event filter 规则](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - ```yaml - filters: - ... - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第二条要求，需要配置以下 [binlog event filter 规则](/v2.1/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - ```yaml - filters: - ... - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - ``` - - > **注意：** - > - > `store-filter-rule` 不同于 `log-filter-rule` 和 `user-filter-rule`。`store-filter-rule` 是针对整个 `store` 库的规则，而 `log-filter-rule` 和 `user-filter-rule` 是针对 `user` 库中 `log` 表的规则。 - -- 为了满足[同步要求](#同步要求)中的第三点要求，需要配置以下 [black & white table lists 规则](/v2.1/reference/tools/data-migration/features/overview.md#black--white-table-lists)： - - ```yaml - black-white-list: - log-ignored: - ignore-dbs: ["log"] - ``` - -## 同步任务配置 - -以下是完整的同步任务配置，详见[配置介绍](/v2.1/reference/tools/data-migration/configure/task-configuration-file.md)。 - -```yaml -name: "one-tidb-slave" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["instance-1-user-rule"] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-2" - route-rules: ["instance-2-user-rule", instance-2-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["instance-3-user-rule", instance-3-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例的共有配置 - -routes: - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - -filters: - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - -black-white-list: - log-ignored: - ignore-dbs: ["log"] - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/v2.1/reference/tools/download.md b/v2.1/reference/tools/download.md deleted file mode 100644 index 90362e82d93b..000000000000 --- a/v2.1/reference/tools/download.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 工具下载 -category: reference ---- - -# TiDB 工具下载 - -本页面汇总了 TiDB 周边工具官方维护版本的下载链接。 - -## TiDB Binlog - -如需下载最新版本的 [TiDB Binlog](/v2.1/reference/tidb-binlog/overview.md)，直接下载 TiDB 安装包即可，因为 TiDB Binlog 包含在 TiDB 安装包中。 - -以下表格中也提供了 Kafka 版本的 TiDB Binlog 下载链接。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (TiDB Binlog) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | -| `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz`（Kafka 版本的 TiDB Binlog）| Linux | amd64 | `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如，`v2.1.15` 版本的下载链接为 `https://download.pingcap.org/tidb-v2.1.15-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB Lightning - -使用下表中的链接下载 [TiDB Lightning](/v2.1/reference/tools/tidb-lightning/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB Lightning 的版本号。例如，`v2.1.15` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v2.1.15-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB DM (Data Migration) - -使用下表中的链接下载 [DM](/v2.1/reference/tools/data-migration/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/dm-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/dm-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 DM 的版本号。例如，`v1.0.1` 版本的下载链接为 `https://download.pingcap.org/dm-v1.0.1-linux-amd64.tar.gz`。可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## Syncer，Loader 和 Mydumper - -如需下载最新版本的 [Syncer](/v2.1/reference/tools/syncer.md)，[Loader](/v2.1/reference/tools/loader.md) 或 [Mydumper](/v2.1/reference/tools/mydumper.md)，直接下载 tidb-enterprise-tools 安装包即可，因为这些工具均包含在此安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| [tidb-enterprise-tools-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) | Linux | amd64 | [tidb-enterprise-tools-latest-linux-amd64.sha256](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256) | - -tidb-enterprise-tools 安装包包含以下工具： - -- Syncer -- Loader -- Mydumper -- ddl_checker -- [sync-diff-inspector](/v2.1/reference/tools/sync-diff-inspector/overview.md) diff --git a/v2.1/reference/tools/loader.md b/v2.1/reference/tools/loader.md deleted file mode 100644 index 803379edf40d..000000000000 --- a/v2.1/reference/tools/loader.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Loader 使用文档 -category: reference ---- - -# Loader 使用文档 - -## Loader 简介 - -Loader 是由 PingCAP 开发的数据导入工具，用于向 TiDB 中导入数据。 - -Loader 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v2.1/reference/tools/download.md)。 - -## 为什么我们要做这个工具 - -当数据量比较大的时候，如果用 mysqldump 这样的工具迁移数据会比较慢。我们尝试了 [Mydumper/myloader 套件](https://github.com/maxbube/mydumper)，能够多线程导出和导入数据。在使用过程中，Mydumper 问题不大，但是 myloader 由于缺乏出错重试、断点续传这样的功能，使用起来很不方便。所以我们开发了 loader，能够读取 Mydumper 的输出数据文件，通过 MySQL protocol 向 TiDB/MySQL 中导入数据。 - -## Loader 有哪些优点 - -* 多线程导入 -* 支持表级别的并发导入，分散写入热点 -* 支持对单个大表并发导入，分散写入热点 -* 支持 Mydumper 数据格式 -* 出错重试 -* 断点续导 -* 通过 system variable 优化 TiDB 导入数据速度 - -## 使用方法 - -### 注意事项 - -请勿使用 loader 导入 MySQL 实例中 `mysql` 系统数据库到下游 TiDB。 - -如果 Mydumper 使用 -m 参数，会导出不带表结构的数据，这时 loader 无法导入数据。 - -如果使用默认的 `checkpoint-schema` 参数，在导完一个 database 数据库后，请 `drop database tidb_loader` 后再开始导入下一个 database。 - -推荐数据库开始导入的时候，明确指定 `checkpoint-schema = "tidb_loader"` 参数。 - -### 参数说明 - -``` - -L string - log 级别设置，可以设置为 debug, info, warn, error, fatal (默认为 "info") - -P int - TiDB/MySQL 的端口 (默认为 4000) - -V - 打印 loader 版本 - -c string - 指定配置文件启动 loader - -checkpoint-schema string - checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后，会通过这个库获取上次运行的进度 (默认为 "tidb_loader") - -d string - 需要导入的数据存放路径 (default "./") - -h string - TiDB 服务 host IP (default "127.0.0.1") - -p string - TiDB 账户密码 - -status-addr string - Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 - -t int - 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 - -u string - TiDB 的用户名 (默认为 "root") -``` - -### 配置文件 - -除了使用命令行参数外，还可以使用配置文件来配置，配置文件的格式如下： - -```toml -# 日志输出等级；可以设置为 debug, info, warn, error, fatal (默认为 "info") -log-level = "info" - -# 指定 loader 日志目录 -log-file = "loader.log" - -# 需要导入的数据存放路径 (default "./") -dir = "./" - -## Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 -status-addr = ":8272" - -# checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后， -# 会通过这个库获取上次运行的进度 (默认为 "tidb_loader") -checkpoint-schema = "tidb_loader" - -# 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 -pool-size = 16 - -# 目标数据库信息 -[db] -host = "127.0.0.1" -user = "root" -password = "" -port = 4000 - -# 导入数据时数据库连接所使用的 session 级别的 `sql_mode`。如果 `sql-mode` 的值没有提供或者设置为 "@DownstreamDefault"，会使用下游 global 级别的 `sql_mode`。 -# sql-mode = "" -# `max-allowed-packet` 设置数据库连接允许的最大数据包大小，对应于系统参数中的 `max_allowed_packet`。 如果设置为 0，会使用下游数据库 global 级别的 `max_allowed_packet`。 -max-allowed-packet = 67108864 - -# sharding 同步规则，采用 wildcharacter -# 1\. 星号字符 (*) 可以匹配零个或者多个字符, -# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; -# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 -# 2\. 问号字符 (?) 匹配任一一个字符 - -# [[route-rules]] -# pattern-schema = "shard_db_*" -# pattern-table = "shard_table_*" -# target-schema = "shard_db" -# target-table = "shard_table" -``` - -### 使用示例 - -通过命令行参数： - -```bash -./bin/loader -d ./test -h 127.0.0.1 -u root -P 4000 -``` - -或者使用配置文件 "config.toml": - -```bash -./bin/loader -c=config.toml -``` - -## FAQ - -### 合库合表场景案例说明 - -根据配置文件的 route-rules 可以支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则： - -+ 是否可以利用 route-rules 的语义规则表示 -+ 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 - -Loader 需要配置文件中开启 route-rules 参数以提供合库合表功能 - -+ 如果使用该功能，必须填写 `pattern-schema` 与 `target-schema` -+ 如果 `pattern-table` 与 `target-table` 为空，将不进行表名称合并或转换 - -```toml -[[route-rules]] -pattern-schema = "example_db" -pattern-table = "table_*" -target-schema = "example_db" -target-table = "table" -``` diff --git a/v2.1/reference/tools/mydumper.md b/v2.1/reference/tools/mydumper.md deleted file mode 100644 index 5c2072ee66da..000000000000 --- a/v2.1/reference/tools/mydumper.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Mydumper 使用文档 -summary: 使用 Mydumper 从 TiDB 导出数据。 -category: reference ---- - -# Mydumper 使用文档 - -## Mydumper 简介 - -[Mydumper](https://github.com/pingcap/mydumper) 是一个 fork 项目，针对 TiDB 的特性进行了优化，推荐使用此工具对 TiDB 进行逻辑备份。 - -Mydumper 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v2.1/reference/tools/download.md)。 - -### 相比于普通的 Mydumper，此工具有哪些改进之处？ - -+ 对于 TiDB 可以设置 [tidb_snapshot](/v2.1/how-to/get-started/read-historical-data.md#操作流程) 的值指定备份数据的时间点，从而保证备份的一致性，而不是通过 `FLUSH TABLES WITH READ LOCK` 来保证备份一致性。 - -+ 使用 TiDB 的隐藏列 `_tidb_rowid` 优化了单表内数据的并发导出性能。 - -## 基本用法 - -### 新添参数 - -- `-z` 或 `--tidb-snapshot`：设置 `tidb_snapshot` 用于备份。默认值为当前 TSO（`SHOW MASTER STATUS` 输出的 `Position` 字段）。此参数可设为 TSO 或有效的 `datetime` 时间，例如：`-z "2016-10-08 16:45:26"`。 - -### 需要的权限 - -- SELECT -- RELOAD -- LOCK TABLES -- REPLICATION CLIENT - -### 使用举例 - -执行如下命令从 TiDB 备份数据，需要根据实际情况添加命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -``` - -## 表内并发 Dump - -### 原理 - -Mydumper 首先计算 `min(_tidb_rowid)` 和 `max(_tidb_rowid)`，然后按照 `-r` 设定的值对表划分 chunks，将 chunks 分配到不同线程并发导出。 - -### 并发 Dump 相关参数 - -- `-t` 或 `--threads`：并发线程数，默认值为 `4`。 -- `-r` 或 `--rows`：每个 chunks 包含的最大行数。设置该值后，Mydumper 将会忽略 `--chunk-filesize` 值。 - -### 示例 - -以下是一条完整的 Mydumper 命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -r 10000 -t 4 -``` - -### 支持 `_tidb_rowid` 索引的 TiDB 版本 - -由于表内并发使用 TiDB 的隐藏列 `_tidb_rowid`，数据库需要支持 `_tidb_rowid` 索引才能发挥并发导出的优势。 - -以下 TiDB 版本支持 `_tidb_rowid` 索引： - -- v2.1.3 及以上 - -### 性能评估 - -在 Dump 操作前需要进行性能评估。由于并发 Scan 操作对 TiDB、TiKV 集群都会产生一定压力，所以需要评估与测试 Dump 操作对数据库集群和业务的影响。 - -## FAQ - -### 如何判断使用的 Mydumper 是否为 PingCAP 优化的版本？ - -执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -V -``` - -如果输出结果中包含 `githash`（如下列示例输出中的 `d3e6fec8b069daee772d0dbaa47579f67a5947e7`），则使用的 Mydumper 为 PingCAP 优化的版本。 - -``` -mydumper 0.9.5 (d3e6fec8b069daee772d0dbaa47579f67a5947e7), built against MySQL 5.7.24 -``` - -### 使用 Loader 恢复 Mydumper 备份出来的数据时报错 "invalid mydumper files for there are no `-schema-create.sql` files found"，应该如何解决？ - -检查使用 Mydumper 备份数据时是否使用了 `-T` 或者 `--tables-list` 配置，如果使用了这些配置，Mydumper 就不会生成包含建库 SQL 的文件。 - -**解决方法**：在 Mydumper 备份数据目录下创建文件 `{schema-name}-schema-create.sql`，在文件中写入 "CREATE DATABASE `{schema-name}`"，再运行 Loader 即可。 - -### 为什么使用 Mydumper 导出来的 TIMESTAMP 类型的数据和数据库中的数据不一致？ - -检查一下运行 Mydumper 的服务器的时区与数据库的时区是否一致，Mydumper 会根据运行所在服务器的时区对 TIMESTAMP 类型的数据进行转化，可以给 Mydumper 加上 `--skip-tz-utc` 参数禁止这种转化。 - -### 如何配置 Mydumper 的参数 `-F, --chunk-filesize`？ - -Mydumper 在备份时会根据这个参数的值把每个表的数据划分成多个 chunk，每个 chunk 保存到一个文件中，大小约为 `chunk-filesize`。根据这个参数把数据切分到多个文件中，这样就可以利用 Loader/TiDB Lightning 的并行处理逻辑提高导入速度。如果后续使用 Loader 对备份文件进行恢复，建议把该参数的值设置为 `64`（单位 MB）；如果使用 TiDB Lightning 恢复，则建议设置为 `256`（单位 MB）。 - -### 如何配置 Mydumper 的参数 `-s --statement-size`？ - -Mydumper 使用该参数控制 `Insert Statement` 的大小，默认值为 `10000000`（约 1 MB）。使用该参数来尽量避免在恢复数据时报以下错误： - -```log -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -默认值在绝大部分情况下都可以满足需求，但是**如果表为宽表，单行数据的大小可能超过 statement-size 的限制，Mydumper 会报如下的 Warning**： - -```log -Row bigger than statement_size for xxx -``` - -此时恢复数据时仍然会报 `packet for query is too large` 的错误日志，这个时候需要修改以下两个配置（以设置为 `128M` 为例）： - -* 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728`（`134217728` = `128M`）。 -* 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M` 的语句，然后重启进程或者任务。 - -### 如何设置 Mydumper 的参数 `-l, --long-query-guard`？ - -把该参数设置为预估备份需要消耗的时间，如果 Mydumper 运行时间超过该参数的值，就会报错退出。推荐初次备份设置为 `7200`（单位：秒），之后可根据具体备份时间进行调整。 - -### 如何设置 Mydumper 的参数 `--tidb-force-priority`？ - -仅当备份 TiDB 的数据时才可以设置该参数，值可以为 `LOW_PRIORITY`，`DELAYED` 或者 `HIGH_PRIORITY`。如果不希望数据备份对线上业务造成影响，推荐将该参数设置为 `LOW_PRIORITY`；如果备份的优先级更高，则可以设置为 `HIGH_PRIORITY`。 - -### Mydumper 备份 TiDB 数据报错 "GC life time is shorter than transaction duration" 应该怎么解决？ - -Mydumper 备份 TiDB 数据时为了保证数据的一致性使用了 TiDB 的 snapshot 特性，如果备份过程中 snapshot 对应的历史数据被 TiDB GC 处理了，则会报该错误。解决步骤如下： - -1. 在备份前，使用 MySQL 客户端查询 TiDB 集群的 `tikv_gc_life_time` 的值，并将其调整为一个合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 备份完成后，将 `tikv_gc_life_time` 调整为原来的值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m0s' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -### Mydumper 的参数 `--tidb-rowid` 是否需要配置？ - -如果设置该参数为 true，则导出的数据中会包含 TiDB 的隐藏列的数据。将数据恢复到 TiDB 的时候使用隐藏列会有数据不一致的风险，目前不推荐使用该参数。 - -### Mydumper 报错 "Segmentation fault" 怎么解决？ - -该 bug 已修复。如果仍然报错，可尝试升级到最新版本。 - -### Mydumper 报错 "Error dumping table ({schema}.{table}) data: line ...... (total length ...)" 怎么解决？ - -Mydumper 解析 SQL 时报错，可尝试使用最新版本。如果仍然报错，可以提 issue 到 [mydumper/issues](https://github.com/pingcap/mydumper/issues)。 - -### Mydumper 报错 "Failed to set tidb_snapshot: parsing time \"20190901-10:15:00 +0800\" as \"20190901-10:15:00 +0700 MST\": cannot parse \"\" as \"MST\"" 如何解决？ - -检查 TiDB 的版本是否低于 v2.1.11。如果是的话，需要升级 TiDB 到 v2.1.11 或以上版本。 - -### 未来是否计划让 PingCAP 对 Mydumper 的改动合并到上游？ - -是的，PingCAP 团队计划将对 Mydumper 的改动合并到上游。参见 [PR #155](https://github.com/maxbube/mydumper/pull/155)。 diff --git a/v2.1/reference/tools/pd-control.md b/v2.1/reference/tools/pd-control.md deleted file mode 100644 index 2128bf4ffb34..000000000000 --- a/v2.1/reference/tools/pd-control.md +++ /dev/null @@ -1,750 +0,0 @@ ---- -title: PD Control 使用说明 -category: reference ---- - -# PD Control 使用说明 - -PD Control 是 PD 的命令行工具，用于获取集群状态信息和调整集群。 - -## 源码编译 - -1. [Go](https://golang.org/) Version 1.9 以上 -2. 在 PD 项目根目录使用 `make` 命令进行编译，生成 bin/pd-ctl - -## 下载安装包 - -如需下载最新版本的 `pd-ctl`，直接下载 TiDB 安装包即可，因为 `pd-ctl` 包含在 TiDB 安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (pd-ctl) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如 `v2.1.17` 版本的下载链接为 `https://download.pingcap.org/tidb-v2.1.17-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 简单例子 - -单命令模式： - -```bash -./pd-ctl store -d -u http://127.0.0.1:2379 -``` - -交互模式： - -```bash -./pd-ctl -u http://127.0.0.1:2379 -``` - -使用环境变量： - -```bash -export PD_ADDR=http://127.0.0.1:2379 -./pd-ctl -``` - -使用TLS加密： - -```bash -./pd-ctl -u https://127.0.0.1:2379 --cacert="path/to/ca" --cert="path/to/cert" --key="path/to/key" -``` - -## 命令行参数(flags) - -### --cacert - -- 指定 PEM 格式的受信任 CA 的证书文件路径 -- 默认值: "" - -### --cert - -- 指定 PEM 格式的 SSL 证书文件路径 -- 默认值: "" - -### \-\-detach,-d - -+ 使用单命令行模式（不进入 readline） -+ 默认值：false - -### --key - -- 指定 PEM 格式的 SSL 证书密钥文件路径，即 `--cert` 所指定的证书的私钥 -- 默认值: "" - -### \-\-pd,-u - -+ 指定 PD 的地址 -+ 默认地址：`http://127.0.0.1:2379` -+ 环境变量：`PD_ADDR` - -### --version,-V - -- 打印版本信息并退出 -- 默认值: false - -## 命令(command) - -### cluster - -用于显示集群基本信息。 - -示例： - -```bash ->> cluster // 显示 cluster 的信息 -{ - "id": 6493707687106161130, - "max_peer_count": 3 -} -``` - -### config [show | set \
` 操作 -# 来验证数据的完整性。 -checksum = true -# 如果设置为 true，会在导入每张表后执行一次 level-1 Compact。 -# 默认值为 false。 -level-1-compact = false -# 如果设置为 true，会在导入过程结束时对整个 TiKV 集群执行一次 full Compact。 -# 默认值为 false。 -compact = false -# 如果设置为 true，会对所有表逐个执行 `ANALYZE TABLE
` 操作。 -analyze = true - -# 设置周期性后台操作。 -# 支持的单位：h（时）、m（分）、s（秒）。 -[cron] -# Lightning 自动刷新导入模式状态的持续时间，该值应小于 TiKV 对应的设定值。 -switch-mode = "5m" -# 在日志中打印导入进度的持续时间。 -log-progress = "5m" - -# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 -# [black-white-list] -# ... -``` - -### TiKV Importer 配置参数 - -```toml -# TiKV Importer 配置文件模版 - -# 日志文件 -log-file = "tikv-importer.log" -# 日志等级：trace, debug, info, warn, error 和 off -log-level = "info" - -[server] -# tikv-importer 的监听地址，tidb-lightning 需要连到这个地址进行数据写入。 -addr = "192.168.20.10:8287" -# gRPC 服务器的线程池大小。 -grpc-concurrency = 16 - -[metric] -# 给 Prometheus 客户端推送的 job 名称。 -job = "tikv-importer" -# 给 Prometheus 客户端推送的间隔。 -interval = "15s" -# Prometheus Pushgateway 的地址。 -address = "" - -[rocksdb] -# background job 的最大并发数。 -max-background-jobs = 32 - -[rocksdb.defaultcf] -# 数据在刷新到硬盘前能存于内存的容量上限。 -write-buffer-size = "1GB" -# 内存中写缓冲器的最大数量。 -max-write-buffer-number = 8 - -# 各个压缩层级使用的算法。 -# 第 0 层的算法用于压缩 KV 数据。 -# 第 6 层的算法用于压缩 SST 文件。 -# 第 1 至 5 层的算法目前尚未使用。 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[rocksdb.writecf] -# 同上 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[import] -# 存储引擎文件的文件夹路径 -import-dir = "/mnt/ssd/data.import/" -# 处理 RPC 请求的线程数 -num-threads = 16 -# 导入 job 的并发数。 -num-import-jobs = 24 -# 预处理 Region 最长时间。 -# max-prepare-duration = "5m" -# 把要导入的数据切分为这个大小的 Region。 -#region-split-size = "512MB" -# 设置 stream-channel-window 的大小。 -# channel 满了之后 stream 会处于阻塞状态。 -# stream-channel-window = 128 -# 同时打开引擎文档的最大数量。 -max-open-engines = 8 -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# upload-speed-limit = "512MB" -# 目标存储可用空间比率（store_available_space/store_capacity）的最小值。 -# 如果目标存储空间的可用比率低于该值，Importer 将会暂停上传 SST -# 来为 PD 提供足够时间进行 Regions 负载均衡。 -min-available-ratio = 0.05 -``` - -## 命令行参数 - -### `tidb-lightning` - -使用 `tidb-lightning` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:----| -| --config *file* | 从 *file* 读取全局设置。如果没有指定则使用默认设置。 | | -| -V | 输出程序的版本 | | -| -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | -| -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | -| --log-file *file* | 日志文件路径 | `lightning.log-file` | -| --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | -| --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | -| --pd-urls *host:port* | PD endpoint 的地址 | `tidb.pd-addr` | -| --tidb-host *host* | TiDB Server 的 host | `tidb.host` | -| --tidb-port *port* | TiDB Server 的端口（默认为 4000） | `tidb.port` | -| --tidb-status *port* | TiDB Server 的状态端口的（默认为 10080） | `tidb.status-port` | -| --tidb-user *user* | 连接到 TiDB 的用户名 | `tidb.user` | -| --tidb-password *password* | 连接到 TiDB 的密码 | `tidb.password` | - -如果同时对命令行参数和配置文件中的对应参数进行更改，命令行参数将优先生效。例如，在 `cfg.toml` 文件中，不管对日志等级做出什么修改，运行 `./tidb-lightning -L debug --config cfg.toml` 命令总是将日志级别设置为 “debug”。 - -### `tidb-lightning-ctl` - -使用 `tidb-lightning-ctl` 可以对下列参数进行配置： - -| 参数 | 描述 | -|:----|:----------| -| --compact | 执行 full compact | -| --switch-mode *mode* | 将每个 TiKV Store 切换到指定模式（normal 或 import） | -| --import-engine *uuid* | 将 TiKV Importer 上关闭的引擎文件导入到 TiKV 集群 | -| --cleanup-engine *uuid* | 删除 TiKV Importer 上的引擎文件 | -| --checkpoint-dump *folder* | 将当前的断点以 CSV 格式存储到文件夹中 | -| --checkpoint-error-destroy *tablename* | 删除断点，如果报错则删除该表 | -| --checkpoint-error-ignore *tablename* | 忽略指定表中断点的报错 | -| --checkpoint-remove *tablename* | 无条件删除表的断点 | - -*tablename* 必须是`` `db`.`tbl` `` 中的限定表名（包括反引号），或关键词 `all`。 - -此外，上表中所有 `tidb-lightning` 的参数也适用于 `tidb-lightning-ctl`。 - -### `tikv-importer` - -使用 `tikv-importer` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:-------| -| -C, --config *file* | 从 *file* 读取配置。如果没有指定，则使用默认设置| | -| -V, --version | 输出程序的版本 | | -| -A, --addr *ip:port* | TiKV Importer 服务器的监听地址 | `server.addr` | -| --import-dir *dir* | 引擎文件的存储目录 | `import.import-dir` | -| --log-level *level* | 日志的等级： trace、debug、info、warn、error 或 off | `log-level` | -| --log-file *file* | 日志文件路径 | `log-file` | diff --git a/v2.1/reference/tools/tidb-lightning/csv.md b/v2.1/reference/tools/tidb-lightning/csv.md deleted file mode 100644 index b0a593fee745..000000000000 --- a/v2.1/reference/tools/tidb-lightning/csv.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: CSV 支持 -category: reference ---- - -# CSV 支持 - -TiDB Lightning 支持读取 CSV（逗号分隔值）的数据源，以及其他定界符格式如 TSV（制表符分隔值）。 - -## 文件名 - -包含整张表的 CSV 文件需命名为 `db_name.table_name.csv`，该文件会被解析为数据库 `db_name` 里名为 `table_name` 的表。 - -如果一个表分布于多个 CSV 文件，这些 CSV 文件命名需加上文件编号的后缀，如 `db_name.table_name.003.csv`。 - -文件扩展名必须为 `*.csv`，即使文件的内容并非逗号分隔。 - -## 表结构 - -CSV 文件是没有表结构的。要导入 TiDB，就必须为其提供表结构。可以通过以下任一方法实现： - -* 创建包含 DDL 语句 `CREATE TABLE` 的文件 `db_name.table_name-schema.sql`。 -* 首先在 TiDB 中直接创建空表，然后在 `tidb-lightning.toml` 中设置 `[mydumper] no-schema = true`。 - -## 配置 - -CSV 格式可在 `tidb-lightning.toml` 文件中 `[mydumper.csv]` 下配置。 -大部分设置项在 MySQL [`LOAD DATA`] 语句中都有对应的项目。 - -```toml -[mydumper.csv] -# 字段分隔符，必须为 ASCII 字符。 -separator = ',' -# 引用定界符，可以为 ASCII 字符或空字符。 -delimiter = '"' -# CSV 文件是否包含表头。 -# 如果为 true，首行将会被跳过。 -header = true -# CSV 是否包含 NULL。 -# 如果为 true，CSV 文件的任何列都不能解析为 NULL。 -not-null = false -# 如果 `not-null` 为 false（即 CSV 可以包含 NULL）， -# 为以下值的字段将会被解析为 NULL。 -null = '\N' -# 是否解析字段内的反斜线转义符。 -backslash-escape = true -# 是否移除以分隔符结束的行。 -trim-last-separator = false -``` - -[`LOAD DATA`]: https://dev.mysql.com/doc/refman/8.0/en/load-data.html - -### `separator` - -- 指定字段分隔符。 -- 必须为单个 ASCII 字符。 -- 常用值： - - * CSV 用 `','` - * TSV 用 `"\t"` - -- 对应 LOAD DATA 语句中的 `FIELDS TERMINATED BY` 项。 - -### `delimiter` - -- 指定引用定界符。 -- 如果 `delimiter` 为空，所有字段都会被取消引用。 -- 常用值： - - * `'"'` 使用双引号引用字段，和 [RFC 4180] 一致。 - * `''` 不引用 - -- 对应 LOAD DATA 语句中的 `FIELDS ENCLOSED BY` 项。 - -[RFC 4180]: https://tools.ietf.org/html/rfc4180 - -### `header` - -- 是否*所有* CSV 文件都包含表头行。 -- 如为 true，第一行会被用作*列名*。如为 false，第一行并无特殊性，按普通的数据行处理。 - -### `not-null` 和 `null` - -- `not-null` 决定是否所有字段不能为空。 -- 如果 `not-null` 为 false，设定了 `null` 的字符串会被转换为 SQL NULL 而非具体数值。 -- 引用不影响字段是否为空。 - - 例如有如下 CSV 文件： - - ```csv - A,B,C - \N,"\N", - ``` - - 在默认设置（`not-null = false; null = '\N'`）下，列 `A` and `B` 导入 TiDB 后都将会转换为 NULL。列 `C` 是空字符串 `''`，但并不会解析为 NULL。 - -### `backslash-escape` - -- 是否解析字段内的反斜线转义符。 -- 如果 `backslash-escape` 为 true，下列转义符会被识别并转换。 - - | 转义符 | 转换为 | - |----------|--------------------------| - | `\0` | 空字符 (U+0000) | - | `\b` | 退格 (U+0008) | - | `\n` | 换行 (U+000A) | - | `\r` | 回车 (U+000D) | - | `\t` | 制表符 (U+0009) | - | `\Z` | Windows EOF (U+001A) | - - 其他情况下（如 `\"`）反斜线会被移除，仅在字段中保留其后面的字符（`"`）。 - -- 引用不会影响反斜线转义符的解析与否。 - -- 对应 LOAD DATA 语句中的 `FIELDS ESCAPED BY '\'` 项。 - -### `trim-last-separator` - -- 将 `separator` 字段当作终止符，并移除尾部所有分隔符。 - - 例如有如下 CSV 文件： - - ```csv - A,,B,, - ``` - -- 当 `trim-last-separator = false`，该文件会被解析为包含 5 个字段的行 `('A', '', 'B', '', '')`。 -- 当 `trim-last-separator = true`，该文件会被解析为包含 3 个字段的行 `('A', '', 'B')`。 - -### 不可配置项 - -TiDB Lightning 并不完全支持 `LOAD DATA` 语句中的所有配置项。例如： - -* 行终止符只能是 CR（`\r`），LF（`\n`）或 CRLF（`\r\n`），也就是说，无法自定义 `LINES TERMINATED BY`。 -* 不可使用行前缀 （`LINES STARTING BY`）。 -* 不可跳过表头（`IGNORE n LINES`）。如有表头，必须是有效的列名。 -* 定界符和分隔符只能为单个 ASCII 字符。 - -## 通用配置 - -### CSV - -默认设置已按照 RFC 4180 调整。 - -```toml -[mydumper.csv] -separator = ',' -delimiter = '"' -header = true -not-null = false -null = '\N' -backslash-escape = true -trim-last-separator = false -``` - -示例内容： - -``` -ID,Region,Count -1,"East",32 -2,"South",\N -3,"West",10 -4,"North",39 -``` - -### TSV - -```toml -[mydumper.csv] -separator = "\t" -delimiter = '' -header = true -not-null = false -null = 'NULL' -backslash-escape = false -trim-last-separator = false -``` - -示例内容： - -``` -ID Region Count -1 East 32 -2 South NULL -3 West 10 -4 North 39 -``` - -### TPC-H DBGEN - -```toml -[mydumper.csv] -separator = '|' -delimiter = '' -header = false -not-null = true -backslash-escape = false -trim-last-separator = true -``` - -示例内容： - -``` -1|East|32| -2|South|0| -3|West|10| -4|North|39| -``` diff --git a/v2.1/reference/tools/tidb-lightning/deployment.md b/v2.1/reference/tools/tidb-lightning/deployment.md deleted file mode 100644 index 010326f7548a..000000000000 --- a/v2.1/reference/tools/tidb-lightning/deployment.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: TiDB Lightning 部署与执行 -category: reference ---- - -# TiDB Lightning 部署与执行 - -本文主要介绍 TiDB Lightning 单独部署与混合部署的硬件需求，以及使用 Ansible 部署与手动部署这两种部署方式。 - -## 注意事项 - -在使用 TiDB Lightning 前，需注意以下事项： - -- TiDB Lightning 运行后，TiDB 集群将无法正常对外提供服务。 -- 若 `tidb-lightning` 崩溃，集群会留在“导入模式”。若忘记转回“普通模式”，集群会产生大量未压缩的文件，继而消耗 CPU 并导致延迟。此时，需要使用 `tidb-lightning-ctl` 手动将集群转回“普通模式”： - - {{< copyable "shell-regular" >}} - - ```sh - bin/tidb-lightning-ctl -switch-mode=normal - ``` - -- TiDB Lightning 需要下游 TiDB 有如下权限： - - | 权限 | 作用域 | - |:----|:------| - | SELECT | Tables | - | INSERT | Tables | - | UPDATE | Tables | - | DELETE | Tables | - | CREATE | Databases, tables | - | DROP | Databases, tables | - | ALTER | Tables | - - 如果配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## 硬件需求 - -`tidb-lightning` 和 `tikv-importer` 这两个组件皆为资源密集程序，建议各自单独部署。 - -为了优化效能，建议硬件配置如下： - -- `tidb-lightning` - - - 32+ 逻辑核 CPU - - 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程默认会占满 CPU，建议单独部署。条件不允许的情况下可以和其他组件（比如 `tidb-server`）部署在同一台机器上，然后通过配置 `region-concurrency` 限制 `tidb-lightning` 使用 CPU 资源。 - -- `tikv-importer` - - - 32+ 逻辑核 CPU - - 40 GB+ 内存 - - 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000） - * 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程中 CPU、I/O 和网络带宽都可能占满，建议单独部署。 - -如果机器充裕的话，可以部署多套 `tidb-lightning` + `tikv-importer`，然后将源数据以表为粒度进行切分，并发导入。 - -> **注意：** -> -> - `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 资源分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 “24”。 -> -> - `tikv-importer` 将中间数据存储缓存到内存上以加速导入过程。占用内存大小可以通过 **(`max-open-engines` × `write-buffer-size` × 2) + (`num-import-jobs` × `region-split-size` × 2)** 计算得来。如果磁盘写入速度慢，缓存可能会带来更大的内存占用。 - -此外，目标 TiKV 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](/v2.1/how-to/deploy/hardware-recommendations.md)以外，目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](/v2.1/faq/tidb.md#326-每个-region-的-replica-数量可配置吗调整的方法是) × 2**。例如集群默认使用 3 副本，那么总存储空间需为数据源大小的 6 倍以上。 - -## 导出数据 - -使用 [`mydumper`](/v2.1/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果数据源是 CSV 文件，请参考 [CSV 支持](/v2.1/reference/tools/tidb-lightning/csv.md)获取配置信息。 - -## 部署 TiDB Lightning - -本节介绍 TiDB Lightning 的两种部署方式：[使用 Ansible 部署](#使用-ansible-部署-tidb-lightning)和[手动部署](#手动部署-tidb-lightning)。 - -### 使用 Ansible 部署 TiDB Lightning - -TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/v2.1/how-to/deploy/orchestrated/ansible.md)。 - -1. 编辑 `inventory.ini`，分别配置一个 IP 来部署 `tidb-lightning` 和 `tikv-importer`。 - - ```ini - ... - - [importer_server] - 192.168.20.9 - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 修改 `group_vars/*.yml` 的变量配置这两个工具。 - - - `group_vars/all.yml` - - ```yaml - ... - # tikv-importer 的监听端口。需对 tidb-lightning 服务器开放。 - tikv_importer_port: 8287 - ... - ``` - - - `group_vars/lightning_server.yml` - - ```yaml - --- - dummy: - - # 提供监控告警的端口。需对监控服务器 (monitoring_server) 开放。 - tidb_lightning_pprof_port: 8289 - - # 获取数据源（Mydumper SQL dump 或 CSV）的路径。 - data_source_dir: "{{ deploy_dir }}/mydumper" - ``` - - - `group_vars/importer_server.yml` - - ```yaml - --- - dummy: - - # 储存引擎文件的路径。需存放在空间足够大的分区。 - import_dir: "{{ deploy_dir }}/data.import" - ``` - -3. 开始部署。 - - {{< copyable "shell-regular" >}} - - ```sh - ansible-playbook bootstrap.yml && - ansible-playbook deploy.yml - ``` - -4. 将数据源写入 `data_source_dir` 指定的路径。 - -5. 登录 `tikv-importer` 的服务器，并执行以下命令来启动 Importer。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_importer.sh - ``` - -6. 登录 `tidb-lightning` 的服务器，并执行以下命令来启动 Lightning，开始导入过程。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_lightning.sh - ``` - -7. 完成后，在 `tikv-importer` 的服务器执行 `scripts/stop_importer.sh` 来关闭 Importer。 - -### 手动部署 TiDB Lightning - -#### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群 (版本要求 2.0.9 以上)，建议使用最新版。部署方法可参考 [TiDB 快速入门指南](/v2.1/overview.md#部署方式)。 - -#### 第 2 步：下载 TiDB Lightning 安装包 - -在[工具下载](/v2.1/reference/tools/download.md#tidb-lightning)页面下载 TiDB Lightning 安装包（需选择与 TiDB 集群相同的版本）。 - -#### 第 3 步：启动 `tikv-importer` - -1. 从安装包上传 `bin/tikv-importer`。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [metric] - # 给 Prometheus 客户端的推送任务名称。 - job = "tikv-importer" - # 给 Prometheus 客户端的推送间隔。 - interval = "15s" - # Prometheus Pushgateway 地址。 - address = "" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - - 上面仅列出了 `tikv-importer` 的基本配置。完整配置请参考[`tikv-importer` 配置说明](/v2.1/reference/tools/tidb-lightning/config.md#tikv-importer)。 - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -#### 第 4 步：启动 `tidb-lightning` - -1. 从安装包上传 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl`。 - -2. 将数据源写入到同样的机器。 - -3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置，TiDB Lightning 给出配置错误的提醒并退出。 - - ```toml - [lightning] - - # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。 - # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。 - # region-concurrency = - - # 日志 - level = "info" - file = "tidb-lightning.log" - - [tikv-importer] - # tikv-importer 的监听地址，需改成 tikv-importer 服务器的实际地址。 - addr = "172.16.31.10:8287" - - [mydumper] - # Mydumper 源数据目录。 - data-source-dir = "/data/my_database" - - [tidb] - # 目标集群的信息。tidb-server 的监听地址，填一个即可。 - host = "172.16.31.1" - port = 4000 - user = "root" - password = "" - # 表架构信息在从 TiDB 的“状态端口”获取。 - status-port = 10080 - ``` - - 上面仅列出了 `tidb-lightning` 的基本配置。完整配置请参考[`tidb-lightning` 配置说明](/v2.1/reference/tools/tidb-lightning/config.md#tidb-lightning-全局配置)。 - -4. 运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & - ``` diff --git a/v2.1/reference/tools/tidb-lightning/glossary.md b/v2.1/reference/tools/tidb-lightning/glossary.md deleted file mode 100644 index bda7810e762b..000000000000 --- a/v2.1/reference/tools/tidb-lightning/glossary.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: TiDB Lightning 术语表 -summary: 了解 TiDB Lightning 相关的术语及定义。 -category: glossary ---- - -# TiDB Lightning 术语表 - -本术语表提供了 TiDB Lightning 相关的术语和定义，这些术语会出现在 TiDB Lightning 的日志、监控指标、配置和文档中。 - - - -## A - -### Analyze - -统计信息分析。指重建 TiDB 表中的统计信息，即运行 [`ANALYZE TABLE`](/v2.1/reference/sql/statements/analyze-table.md) 语句。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，统计信息不会自动更新，所以 TiDB Lightning 在导入后显式地分析每个表。如果不需要该操作，可以将 `post-restore.analyze` 设置为 `false`。 - -### `AUTO_INCREMENT_ID` - -用于为自增列分配默认值的自增 ID 计数器。每张表都有一个相关联的 `AUTO_INCREMENT_ID` 计数器。在 TiDB 中，该计数器还用于分配行 ID。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，`AUTO_INCREMENT_ID` 计数器不会自动更新，所以 TiDB Lightning 显式地将 `AUTO_INCREMENT_ID` 改为一个有效值。即使表中没有自增列，这步仍是会执行。 - - - -## B - -### Black-white list - -黑白名单配置列表。用于指定要导入、忽略哪些表和库。 - -详情参阅 [TiDB Lightning 表库过滤](/v2.1/reference/tools/tidb-lightning/table-filter.md)。 - - - -## C - -### Checkpoint - -断点。用于保证 TiDB Lightning 在导入数据时不断地将进度保存到本地文件或远程数据库中。这样即使进程崩溃，TiDB Lightning 也能从中间状态恢复。 - -详情参见 [TiDB Lightning 断点续传](/v2.1/reference/tools/tidb-lightning/checkpoints.md)。 - -### Checksum - -校验和。一种用于[验证导入数据正确性](/v2.1/faq/tidb-lightning.md#如何校验导入的数据的正确性)的方法。 - -在 TiDB Lightning 中，表的校验和是由 3 个数字组成的集合，由该表中每个键值对的内容计算得出。这些数字分别是： - -* 键值对的数量 -* 所有键值对的总长度 -* 每个键值对 [CRC-64-ECMA](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) 按位异或的结果 - -TiDB Lightning 通过比较每个表的[本地校验和](#local-checksum)和[远程校验和](#remote-checksum)来验证导入数据的正确性。如果有任一对校验和不匹配，导入进程就会停止。如果你需要跳过校验和检查，可以将 `post-restore.checksum` 设置为 `false` 。 - -遇到校验和不匹配的问题时，参考[故障排查](/v2.1/how-to/troubleshoot/tidb-lightning.md#checksum-failed-checksum-mismatched-remote-vs-local)进行处理。 - -### Chunk - -指数据源中的单个文件。 - -### Compaction - -压缩。指将多个小 SST 文件合并为一个大 SST 文件并清理已删除的条目。TiDB Lightning 导入数据时，TiKV 在后台会自动压缩数据。 - -> **注意：** -> -> 出于遗留原因，你仍然可以将 TiDB Lightning 配置为在每次导入表时进行显式压缩，但是官方不推荐采用该操作，且该操作的相关设置默认是禁用的。 -> -> 技术细节参阅 [RocksDB 关于压缩的说明](https://github.com/facebook/rocksdb/wiki/Compaction)。 - - - -## D - -### Data engine - -数据引擎。用于对实际的行数据进行排序的[引擎](#engine)。 - -当一个表数据很多的时候，表的数据会被放置在多个数据引擎中以改善任务流水线并节省 TiKV Importer 的空间。默认条件下，每 100 GB 的 SQL 数据会打开一个新的数据引擎（可通过 `mydumper.batch-size` 配置项进行更改）。 - -TiDB Lightning 同时处理多个数据引擎（可通过 `lightning.table-concurrency` 配置项进行更改）。 - - - -## E - -### Engine - -引擎。在 TiKV Importer 中，一个引擎就是一个用于排序键值对的 RocksDB 实例。 - -TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先打开一个引擎，向其发送未排序的键值对，然后关闭引擎。随后，引擎会对收到的键值对进行排序操作。这些关闭的引擎可以进一步上传至 TiKV store 中为 [Ingest](#ingest) 做准备。 - -引擎使用 TiKV Importer 的 `import-dir` 作为临时存储，有时也会被称为引擎文件 (engine files)。 - -另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 - - - -## I - -### Import mode - -导入模式。指通过降低读取速度和减少空间使用，来优化 TiKV 写入的配置模式。 - -导入过程中，TiDB Lightning 自动在导入模式和[普通模式](#normal-mode)中来回切换。如果 TiKV 卡在导入模式，你可以使用 `tidb-lightning-ctl` [强制切换回普通模式](/v2.1/faq/tidb-lightning.md#为什么用过-tidb-lightning-之后tidb-集群变得又慢又耗-cpu)。 - -### Index engine - -索引引擎。用于对索引进行排序的[引擎](#engine)。 - -不管表中有多少索引，每张表都只对应**一个**索引引擎。 - -TiDB Lightning 可同时处理多个索引引擎（可通过 `lightning.index-concurrency` 配置项进行更改）。由于每张表正好对应一个索引引擎，`lightning.index-concurrency` 配置项也限定了可同时处理的表的最大数量。 - -### Ingest - -指将 [SST 文件](#sst-file)的全部内容插入到 RocksDB（TiKV）store 中的操作。 - -与逐个插入键值对相比，Ingest 的效率非常高。因此，该操作直接决定了 TiDB Lightning 的性能。 - -技术细节参阅 [RocksDB 关于创建、Ingest SST 文件的 wiki 页面](https://github.com/facebook/rocksdb/wiki/Creating-and-Ingesting-SST-files)。 - - - -## K - -### KV pair - -即 key-value pair（键值对）。 - -### KV encoder - -用于将 SQL 或 CSV 行解析为键值对的例程。多个 KV encoder 会并行运行以加快处理速度。 - - - -## L - -### Local checksum - -本地校验和。在将键值对发送到 TiKV Importer 前，由 TiDB Lightning 计算的表的校验和。 - - - -## N - -### Normal mode - -普通模式。未启用[导入模式](#import-mode)时的模式。 - - - -## P - -### Post-processing - -指整个数据源被解析发送到 TiKV Importer 之后的一段时间。此时 TiDB Lightning 正在等待 TiKV Importer 上传、[Ingest](#ingest) [SST 文件](#sst-file)。 - - - -## R - -### Remote checksum - -远程校验和。指导入 TiDB 后所计算的表的[校验和](#checksum)。 - - - -## S - -### Scattering - -指随机再分配 [Region](/v2.1/glossary.md#regionpeerraft-group) 中 leader 和 peer 的操作。Scattering 确保导入的数据在 TiKV store 中均匀分布，这样可以降低 PD 调度的压力。 - -### Splitting - -指 TiKV Importer 在上传之前会将单个引擎文件拆分为若干小 [SST 文件](#sst-file)的操作。这是因为引擎文件通常很大（约为 100 GB），在 TiKV 中不适合视为单一的 [Region](/v2.1/glossary.md#regionpeerraft-group)。拆分的文件大小可通过 `import.region-split-size` 配置项更改。 - -### SST file - -Sorted string table file（排序字符串表文件）。SST 文件是一种在 RocksDB 中（因而也是 TiKV 中）键值对集合在本地的存储形式。 - -TiKV Importer 从关闭的[引擎](#engine)中生成 SST 文件。这些 SST 文件接着被上传、[ingest](#ingest) 到 TiKV store 中。 diff --git a/v2.1/reference/tools/tidb-lightning/monitor.md b/v2.1/reference/tools/tidb-lightning/monitor.md deleted file mode 100644 index 293b004a4ed8..000000000000 --- a/v2.1/reference/tools/tidb-lightning/monitor.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: TiDB Lightning 监控告警 -category: reference ---- - -# TiDB Lightning 监控告警 - -`tidb-lightning` 和 `tikv-importer` 都支持使用 [Prometheus](https://prometheus.io/) 采集监控指标 (metrics)。本文主要介绍 TiDB Lightning 的监控配置与监控指标。 - -## 监控配置 - -- 如果是使用 TiDB Ansible 部署 Lightning，只要将服务器地址加到 `inventory.ini` 文件里的 `[monitored_servers]` 部分即可。 -- 如果是手动部署 Lightning，则参照以下步骤进行配置。 - -### `tikv-importer` - -`tikv-importer` v2.1 使用 [Pushgateway](https://github.com/prometheus/pushgateway) 来推送监控指标。需要配置 `tikv-importer.toml` 来连接 Pushgateway： - -```toml -[metric] - -# 给 Prometheus 客户端的推送任务名称。 -job = "tikv-importer" - -# 给 Prometheus 客户端的推送间隔。 -interval = "15s" - -# Prometheus Pushgateway 地址。 -address = "" -``` - -### `tidb-lightning` - -只要 Prometheus 能发现 `tidb-lightning` 的监控地址，就能收集监控指标。 - -监控的端口可在 `tidb-lightning.toml` 中配置： - -```toml -[lightning] -# 用于调试和 Prometheus 监控的 HTTP 端口。输入 0 关闭。 -pprof-port = 8289 - -... -``` - -要让 Prometheus 发现 Lightning，可以将地址直接写入其配置文件，例如： - -{{< copyable "" >}} - -```yaml -... -scrape_configs: - - job_name: 'tidb-lightning' - static_configs: - - targets: ['192.168.20.10:8289'] -``` - -## Grafana 面板 - -[Grafana](https://grafana.com/) 的可视化面板可以让你在网页上监控 Prometheus 指标。 - -使用 TiDB Ansible 部署 TiDB 集群时，会同时部署一套 Grafana + Prometheus 的监控系统。 - -如果使用其他方式部署 TiDB Lightning，需先导入[面板的 JSON 文件](https://raw.githubusercontent.com/pingcap/tidb-ansible/master/scripts/lightning.json)。 - -### 第一行：速度面板 - -![第一行速度面板](/media/lightning-grafana-row-1.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Import speed | write from lightning | 从 TiDB Lightning 向 TiKV Importer 发送键值对的速度，取决于每个表的复杂性 | -| Import speed | upload to tikv | 从 TiKV Importer 上传 SST 文件到所有 TiKV 副本的总体速度 | -| Chunk process duration | | 完全编码单个数据文件所需的平均时间 | - -有时导入速度会降到 0，这是为了平衡其他部分的速度，属于正常现象。 - -### 第二行：进度面板 - -![第二行进度面板](/media/lightning-grafana-row-2.png) - -| 面板名称 | 描述 | -|:-----|:-----| -| Import progress | 已编码的文件所占百分比 | -| Checksum progress | 已导入的表所占百分比 | -| Failures | 导入失败的表的数量以及故障点，通常为空 | - -### 第三行：资源使用面板 - -![第三行资源使用面板](/media/lightning-grafana-row-3.png) - -| 面板名称 | 描述 | -|:-----|:-----| -| Memory usage | 每个服务占用的内存 | -| Number of Lightning Goroutines | TiDB Lightning 使用的运行中的 goroutines 数量 | -| CPU% | 每个服务使用的逻辑 CPU 数量 | - -### 第四行：配额使用面板 - -![第四行配额使用面板](/media/lightning-grafana-row-4.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Idle workers | io | 未使用的 `io-concurrency` 的数量，通常接近配置值（默认为 5），接近 0 时表示磁盘运行太慢 | -| Idle workers | closed-engine | 已关闭但未清理的引擎数量，通常接近 `index-concurrency` 与`table-concurrency` 的和（默认为 8），接近 0 时表示 TiDB Lightning 比 TiKV Importer 快，导致 TiDB Lightning 延迟 | -| Idle workers | table | 未使用的 `table-concurrency` 的数量，通常为 0，直到进程结束 | -| Idle workers | index | 未使用的 `index-concurrency` 的数量，通常为 0，直到进程结束 | -| Idle workers | region | 未使用的 `region-concurrency` 的数量，通常为 0，直到进程结束 | -| External resources | KV Encoder | 已激活的 KV encoder 的数量，通常与 `region-concurrency` 的数量相同，直到进程结束 | -| External resources | Importer Engines | 打开的引擎文件数量，不应超过 `max-open-engines` 的设置 | - -### 第五行：读取速度面板 - -![第五行读取速度面板](/media/lightning-grafana-row-5.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Chunk parser read block duration | read block | 读取一个字节块来准备解析时所消耗的时间 | -| Chunk parser read block duration | apply worker | 等待 `io-concurrency` 空闲所消耗的时间 | -| SQL process duration | row encode | 解析和编码单行所消耗的时间 | -| SQL process duration | block deliver | 将一组键值对发送到 TiKV Importer 所消耗的时间 | - -如果上述项的持续时间过长，则表示 TiDB Lightning 使用的磁盘运行太慢或 I/O 太忙。 - -### 第六行：存储空间面板 - -![第六行存储空间面板](/media/lightning-grafana-row-6.png) - -| 面板名称 | 序列 |描述 | -|:-----|:-----|:-----| -| SQL process rate | data deliver rate | 向 TiKV Importer 发送数据键值对的速度 | -| SQL process rate | index deliver rate | 向 TiKV Importer 发送索引键值对的速度 | -| SQL process rate | total deliver rate | 发送数据键值对及索引键值对的速度之和 | -| Total bytes | parser read size | TiDB Lightning 正在读取的字节数 | -| Total bytes | data deliver size | 已发送到 TiKV Importer 的数据键值对的字节数 | -| Total bytes | index deliver size | 已发送到 TiKV Importer 的索引键值对的字节数 | -| Total bytes | storage_size/3 | TiKV 集群占用的存储空间大小的 1/3（3 为默认的副本数量）| - -### 第七行：导入速度面板 - -![第七行导入速度面板](/media/lightning-grafana-row-7.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Delivery duration | Range delivery | 将一个 range 的键值对上传到 TiKV 集群所消耗的时间 | -| Delivery duration | SST delivery | 将单个 SST 文件上传到 TiKV 集群所消耗的时间 | -| SST process duration | Split SST | 将键值对流切分成若干 SST 文件所消耗的时间 | -| SST process duration | SST upload | 上传单个 SST 文件所消耗的时间 | -| SST process duration | SST ingest | ingest 单个 SST 文件所消耗的时间 | -| SST process duration | SST size | 单个 SST 文件的大小 | - -## 监控指标 - -本节将详细描述 `tikv-importer` 和 `tidb-lightning` 的监控指标。 - -### `tikv-importer` - -`tikv-importer` 的监控指标皆以 `tikv_import_*` 为前缀。 - -- **`tikv_import_rpc_duration`**（直方图） - - 完成一次 RPC 操作所需时的直方图。标签： - - - **request**：`switch_mode` / `open_engine` / `write_engine` / `close_engine` / `import_engine` / `cleanup_engine` / `compact_cluster` / `upload` / `ingest` / `compact` - - **result**：`ok` / `error` - -- **`tikv_import_write_chunk_bytes`**（直方图） - - 从 Lightning 接收的键值对区块大小（未压缩）的直方图。 - -- **`tikv_import_write_chunk_duration`**（直方图） - - 从 `tidb-lightning` 接收每个键值对区块需时直方图。 - -- **`tikv_import_upload_chunk_bytes`**（直方图） - - 上传到 TiKV 的每个 SST 文件区块大小（压缩）的直方图。 - -- **`tikv_import_range_delivery_duration`**（直方图） - - 将一个 range 的键值对发送至 `dispatch-job` 任务需时的直方图。 - -- **`tikv_import_split_sst_duration`**（直方图） - - 将 range 从引擎文件中分离到单个 SST 文件中需时的直方图。 - -- **`tikv_import_sst_delivery_duration`**（直方图） - - 将 SST 文件从 `dispatch-job` 任务发送到 `ImportSSTJob` 任务需时的直方图 - -- **`tikv_import_sst_recv_duration`**（直方图） - - `ImportSSTJob` 任务接收从 `dispatch-job` 任务发送过来的 SST 文件需时的直方图。 - -- **`tikv_import_sst_upload_duration`**（直方图） - - 从 `ImportSSTJob` 任务上传 SST 文件到 TiKV 节点需时的直方图。 - -- **`tikv_import_sst_chunk_bytes`**（直方图） - - 上传到 TiKV 节点的 SST 文件（压缩）大小的直方图。 - -- **`tikv_import_sst_ingest_duration`**（直方图） - - 将 SST 文件传入至 TiKV 需时的直方图。 - -- **`tikv_import_each_phase`**（测量仪） - - 表示运行阶段。值为 1 时表示在阶段内运行，值为 0 时表示在阶段内运行。标签： - - - **phase**： `prepare` / `import` - -- **`tikv_import_wait_store_available_count`**（计数器） - - 计算出现 TiKV 节点没有充足空间上传 SST 文件现象的次数。标签： - - - **store_id**： TiKV 存储 ID。 - -- **`tikv_import_upload_chunk_duration`**（直方图） - - 上传到 TiKV 的每个区块需时的直方图。 - -### `tidb-lightning` - -`tidb-lightning` 的监控指标皆以 `lightning_*` 为前缀。 - -- **`lightning_importer_engine`**（计数器） - - 计算已开启及关闭的引擎文件数量。标签： - - - **type**：`open` / `closed` - -- **`lightning_idle_workers`**（计量表盘） - - 计算闲置的 worker。数值应低于设置中的 `*-concurrency` 的值，且经常为 0。标签： - - - **name**： `table` / `index` / `region` / `io` / `closed-engine` - -- **`lightning_kv_encoder`**（计数器） - - 计算已开启及关闭的 KV 编码器。KV 编码器是运行于内存的 TiDB 实例，用于将 SQL 的 `INSERT` 语句转换成键值对。此度量的净值（开启减掉关闭）在正常情况下不应持续增长。标签： - - - **type**：`open` / `closed` - -- **`lightning_tables`**（计数器） - - 计算处理过的表及其状态。标签： - - - **state**：`pending` / `written` / `closed` / `imported` / `altered_auto_inc` / `checksum` / `analyzed` / `completed` - - **result**：`success` / `failure` - -- **`lightning_engines`**（计数器） - - 计算处理后引擎文件的数量以及其状态。标签： - - - **state**： `pending` / `written` / `closed` / `imported` / `completed` - - **result**： `success` / `failure` - -- **`lightning_chunks`**（计数器） - - 计算处理过的 Chunks 及其状态。标签： - - - **state**：`estimated` / `pending` / `running` / `finished` / `failed` - -- **`lightning_import_seconds`**（直方图） - - 导入每个表需时的直方图。 - -- **`lightning_row_read_bytes`**（直方图） - - 单行 SQL 数据大小的直方图。 - -- **`lightning_row_encode_seconds`**（直方图） - - 解码单行 SQL 数据到键值对需时的直方图。 - -- **`lightning_row_kv_deliver_seconds`**（直方图） - - 发送一组与单行 SQL 数据对应的键值对需时的直方图。 - -- **`lightning_block_deliver_seconds`**（直方图） - - 每个键值对中的区块传送到 `tikv-importer` 需时的直方图。 - -- **`lightning_block_deliver_bytes`**（直方图） - - 发送到 Importer 的键值对中区块（未压缩）的大小的直方图。 - -- **`lightning_chunk_parser_read_block_seconds`**（直方图） - - 数据文件解析每个 SQL 区块需时的直方图。 - -- **`lightning_checksum_seconds`**（直方图） - - 计算表中 Checksum 需时的直方图。 - -- **`lightning_apply_worker_seconds`**（直方图） - - 获取闲置 worker 等待时间的直方图。标签： - - - **name**： `table` / `index` / `region` / `io` / `closed-engine` diff --git a/v2.1/reference/tools/tidb-lightning/overview.md b/v2.1/reference/tools/tidb-lightning/overview.md deleted file mode 100644 index b57c8858956c..000000000000 --- a/v2.1/reference/tools/tidb-lightning/overview.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB Lightning 简介 -category: reference ---- - -# TiDB Lightning 简介 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量数据的备份恢复。目前，支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -## TiDB Lightning 整体架构 - -TiDB Lightning 主要包含两个部分： - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键值对（KV 对）发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，对 `tidb-lightning` 写入的键值对进行缓存、排序、切分操作并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -TiDB Lightning 整体工作原理如下： - -1. 在导数据之前，`tidb-lightning` 会自动将 TiKV 集群切换为“导入模式” (import mode)，优化写入效率并停止自动压缩。 - -2. `tidb-lightning` 会在目标数据库建立架构和表，并获取其元数据。 - -3. 每张表都会被分割为多个连续的**区块**，这样来自大表 (200 GB+) 的数据就可以用增量方式导入。 - -4. `tidb-lightning` 会通过 gRPC 让 `tikv-importer` 为每一个区块准备一个“引擎文件 (engine file)”来处理键值对。`tidb-lightning` 会并发读取 SQL dump，将数据源转换成与 TiDB 相同编码的键值对，然后发送到 `tikv-importer` 里对应的引擎文件。 - -5. 当一个引擎文件数据写入完毕时，`tikv-importer` 便开始对目标 TiKV 集群数据进行分裂和调度，然后导入数据到 TiKV 集群。 - - 引擎文件包含两种：**数据引擎**与**索引引擎**，各自又对应两种键值对：行数据和次级索引。通常行数据在数据源里是完全有序的，而次级索引是无序的。因此，数据引擎文件在对应区块写入完成后会被立即上传，而所有的索引引擎文件只有在整张表所有区块编码完成后才会执行导入。 - -6. 整张表相关联的所有引擎文件完成导入后，`tidb-lightning` 会对比本地数据源及下游集群的校验和 (checksum)，确保导入的数据无损，然后让 TiDB 分析 (`ANALYZE`) 这些新增的数据，以优化日后的操作。同时，`tidb-lightning` 调整 `AUTO_INCREMENT` 值防止之后新增数据时发生冲突。 - - 表的自增 ID 是通过行数的**上界**估计值得到的，与表的数据文件总大小成正比。因此，最后的自增 ID 通常比实际行数大得多。这属于正常现象，因为在 TiDB 中自增 ID [不一定是连续分配的](/v2.1/reference/mysql-compatibility.md#auto-increment-id)。 - -7. 在所有步骤完毕后，`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode)，此后 TiDB 集群可以正常对外提供服务。 diff --git a/v2.1/reference/tools/tidb-lightning/table-filter.md b/v2.1/reference/tools/tidb-lightning/table-filter.md deleted file mode 100644 index 3f4ff93a6d6b..000000000000 --- a/v2.1/reference/tools/tidb-lightning/table-filter.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: TiDB Lightning 表库过滤 -summary: 使用黑白名单把一些表剔出要导入的范围。 -category: reference ---- - -# TiDB Lightning 表库过滤 - -TiDB Lightning 支持使用黑名单和白名单来过滤掉某些数据库和表。这可以用来跳过一些用作暂存、毋须迁移的表，或用来手动切分数据源，让多机同时导入。 - -这些过滤规则与 MySQL 的 `replication-rules-db`/`replication-rules-table` 类似。 - -## 过滤数据库 - -```toml -[black-white-list] -do-dbs = ["pattern1", "pattern2", "pattern3"] -ignore-dbs = ["pattern4", "pattern5"] -``` - -* 如果 `[black-white-list]` 下的 `do-dbs` 列表不为空， - * 如数据库名称匹配 `do-dbs` 列表中**任何**一项，则数据库会被导入。 - * 否则，数据库会被略过。 -* 否则，如果数据库名称匹配 `ignore-dbs` 列表中**任何**一项，数据库会被略过。 -* 如果数据库名称**同时**匹配 `do-dbs` 和 `ignore-dbs` 列表，数据库会被导入。 - -如果匹配项首字符为 `~`，它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 - -## 过滤表 - -```toml -[[black-white-list.do-tables]] -db-name = "db-pattern-1" -tbl-name = "table-pattern-1" - -[[black-white-list.do-tables]] -db-name = "db-pattern-2" -tbl-name = "table-pattern-2" - -[[black-white-list.do-tables]] -db-name = "db-pattern-3" -tbl-name = "table-pattern-3" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-4" -tbl-name = "table-pattern-4" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-5" -tbl-name = "table-pattern-5" -``` - -* 如果 `do-tables` 列表不为空， - * 如果表的限定名称匹配 `do-tables` 列表中**任何**一对，则表会被导入。 - * 否则，表会被略过。 -* 否则，如果表的限定名称匹配 `ignore-tables` 列表中**任何**一对，表会被略过。 -* 如果表的限定名称**同时**匹配 `do-tables` 和 `ignore-tables` 列表，表会被导入。 - -> **注意：** -> -> Lightning 会先执行数据库过滤规则，之后才执行表的过滤规则。所以，如果一个数据库已被 `ignore-dbs` 略过，即使其下的表匹配 `do-tables` 也不会再被导入。 - -## 例子 - -以下例子演示过滤规则的操作原理。假设数据源包含这些表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -`admin`.`secrets` -``` - -我们使用以下设置： - -```toml -[black-white-list] -do-dbs = [ - "forum_backup_2018", # 规则 A - "~^(logs|forum)$", # 规则 B -] -ignore-dbs = [ - "~^forum_backup_", # 规则 C -] - -[[black-white-list.do-tables]] # 规则 D -db-name = "logs" -tbl-name = "~_2018$" - -[[black-white-list.ignore-tables]] # 规则 E -db-name = "~.*" -tbl-name = "~^messages.*" - -[[black-white-list.do-tables]] # 规则 F -db-name = "~^forum.*" -tbl-name = "messages" -``` - -首先进行数据库过滤： - -| 数据库 | 结果 | -|---------------------------|--------------| -| `` `logs` `` | 导入（规则 B） | -| `` `forum` `` | 导入（规则 B） | -| `` `forum_backup_2016` `` | 略过（规则 C） | -| `` `forum_backup_2017` `` | 略过（规则 C） | -| `` `forum_backup_2018` `` | 导入（规则 A）（不会考虑规则 C） | -| `` `admin` `` | 略过（`do-dbs` 不为空，且没有匹配的项目） | - -然后进行表过滤： - -| 表 | 结果 | -|--------------------------------------|--------------| -| `` `logs`.`messages_2016` `` | 略过（规则 E） | -| `` `logs`.`messages_2017` `` | 略过（规则 E） | -| `` `logs`.`messages_2018` `` | 导入（规则 D）（不会考虑规则 E） | -| `` `forum`.`users` `` | 略过（`do-tables` 不为空，且没有匹配的项目） | -| `` `forum`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `forum_backup_2016`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2017`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2018`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `admin`.`secrets` `` | 略过（数据库已被剔除） | diff --git a/v2.1/reference/tools/tidb-lightning/web.md b/v2.1/reference/tools/tidb-lightning/web.md deleted file mode 100644 index e1e0fd6b3ff4..000000000000 --- a/v2.1/reference/tools/tidb-lightning/web.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: TiDB Lightning Web 界面 -summary: 了解 TiDB Lightning 的服务器模式——通过 Web 界面来控制 TiDB Lightning。 -category: reference ---- - -# TiDB Lightning Web 界面 - -TiDB Lightning 支持在网页上查看导入进度或执行一些简单任务管理，这就是 TiDB Lightning 的**服务器模式**。本文将介绍服务器模式下的 Web 界面和一些常见操作。 - -启用服务器模式的方式有如下几种： - -1. 在启动 `tidb-lightning` 时加上命令行参数 `--server-mode`。 - - ```sh - ./tidb-lightning --server-mode --status-addr :8289 - ``` - -2. 在配置文件中设置 `lightning.server-mode`。 - - ```toml - [lightning] - server-mode = true - status-addr = ':8289' - ``` - -TiDB Lightning 启动后，可以访问 `http://127.0.0.1:8289` 来管理程序（实际的 URL 取决于你的 `status-addr` 设置）。 - -服务器模式下，TiDB Lightning 不会立即开始运行，而是通过用户在 web 页面提交（多个）**任务**来导入数据。 - -## TiDB Lightning Web 首页 - -![TiDB Lightning Web 首页](/media/lightning-web-frontpage.png) - -标题栏上图标所对应的功能，从左到右依次为： - -| 图标 | 功能 | -|:----|:----| -| "TiDB Lightning" | 点击即返回首页 | -| ⚠ | 显示**前一个**任务的所有错误信息 | -| ⓘ | 列出当前及队列中的任务，可能会出现一个标记提示队列中任务的数量 | -| + | 提交单个任务 | -| ⏸/▶ | 暂停/继续当前操作 | -| ⟳ | 设置网页自动刷新 | - -标题栏下方的三个面板显示了不同状态下的所有表： - -* Active：当前正在导入这些表 -* Completed：这些表导入成功或失败 -* Pending：这些表还没有被处理 - -每个面板都包含用于描述表状态的卡片。 - -## 提交任务 - -点击标题栏的 **+** 图标提交任务。 - -![提交任务对话框](/media/lightning-web-submit.png) - -任务 (task) 为 TOML 格式的文件，具体参考 [TiDB Lightning 任务配置](/v2.1/reference/tools/tidb-lightning/config.md#tidb-lightning-任务配置参数)。你也可以点击 **UPLOAD** 上传一个本地的 TOML 文件。 - -点击 **SUBMIT** 运行任务。如果当前有任务正在运行，新增任务会加入队列并在当前任务结束后执行。 - -## 查看导入进度 - -点击首页表格卡片上的 **>** 图标，查看表格导入的详细进度。 - -![表格导入进度](/media/lightning-web-table.png) - -该页显示每张表的引擎文件的导入过程。 - -点击标题栏上的 **TiDB Lightning** 返回首页。 - -## 管理任务 - -单击标题栏上的 **ⓘ** 图标来管理当前及队列中的任务。 - -![任务管理页面](/media/lightning-web-queue.png) - -每个任务都是依据提交时间来标记。点击该任务将显示 JSON 格式的配置文件。 - -点击任务上的 **⋮** 可以对该任务进行管理。你可以立即停止任务，或重新排序队列中的任务。 diff --git a/v2.1/reference/tools/tikv-control.md b/v2.1/reference/tools/tikv-control.md deleted file mode 100644 index abc1c98ae52f..000000000000 --- a/v2.1/reference/tools/tikv-control.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: TiKV Control 使用说明 -category: reference ---- - -# TiKV Control 使用说明 - -TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管理 TiKV 集群。 - -编译 TiKV 的同时也会编译 tikv-ctl 命令。如果通过 Ansible 部署集群，则对应的 `tidb-ansible/resources/bin` 目录下会存在 `tikv-ctl` 二进制文件。如果使用二进制文件部署集群，bin 目录下会包含 `tikv-ctl` 文件及 `tidb-server`、`pd-server`、以及 `tikv-server` 等其他文件。 - -## 通用参数 - -tikv-ctl 提供以下两种运行模式： - -- **远程模式**。通过 `--host` 选项接受 TiKV 的服务地址作为参数。在此模式下，如果 TiKV 启用了 SSL，则 tikv-ctl 也需要指定相关的证书文件，例如： - - ``` - $ tikv-ctl --ca-path ca.pem --cert-path client.pem --key-path client-key.pem --host 127.0.0.1:20160 - ``` - - 某些情况下，tikv-ctl 与 PD 进行通信，而不与 TiKV 通信。此时你需要使用 `--pd` 选项而非 `--host` 选项，例如： - - ``` - $ tikv-ctl --pd 127.0.0.1:2379 compact-cluster - store:"127.0.0.1:20160" compact db:KV cf:default range:([], []) success! - ``` - -- **本地模式**。通过 `--db` 选项来指定本地 TiKV 数据的目录路径。在此模式下，需要停止正在运行的 TiKV 实例。 - -以下如无特殊说明，所有命令都同时支持这两种模式。 - -除此之外，tikv-ctl 还有两个简单的命令 `--to-hex` 和 `--to-escaped`，用于对 key 的形式作简单的变换。一般使用 `escaped` 形式，示例如下： - -```bash -$ tikv-ctl --to-escaped 0xaaff -\252\377 -$ tikv-ctl --to-hex "\252\377" -AAFF -``` - -> **注意：** -> -> 在命令行上指定 `escaped` 形式的 key 时，需要用双引号引起来，否则 bash 会将反斜杠吃掉，导致结果错误。 - -## 各项子命令及部分参数、选项 - -下面逐一对 tikv-ctl 支持的子命令进行举例说明。有的子命令支持很多可选参数，要查看全部细节，可运行 `tikv-ctl --help `。 - -### 查看 Raft 状态机的信息 - -`raft` 子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 **RegionLocalState**、**RaftLocalState** 和 **RegionApplyState** 三个结构体，及某一条 log 对应的 Entries。 - -您可以使用 `region` 和 `log` 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。它们的用法及输出内容如下所示： - -```bash -$ tikv-ctl --host 127.0.0.1:20160 raft region -r 2 -region id: 2 -region state key: \001\003\000\000\000\000\000\000\000\002\001 -region state: Some(region {id: 2 region_epoch {conf_ver: 3 version: 1} peers {id: 3 store_id: 1} peers {id: 5 store_id: 4} peers {id: 7 store_id: 6}}) -raft state key: \001\002\000\000\000\000\000\000\000\002\002 -raft state: Some(hard_state {term: 307 vote: 5 commit: 314617} last_index: 314617) -apply state key: \001\002\000\000\000\000\000\000\000\002\003 -apply state: Some(applied_index: 314617 truncated_state {index: 313474 term: 151}) -``` - -### 查看 Region 的大小 - -`size` 命令可以查看 Region 的大小： - -```bash -$ tikv-ctl --db /path/to/tikv/db size -r 2 -region id: 2 -cf default region size: 799.703 MB -cf write region size: 41.250 MB -cf lock region size: 27616 -``` - -### 扫描查看给定范围的 MVCC - -`scan` 命令的 `--from` 和 `--to` 参数接受两个 escaped 形式的 raw key，并用 `--show-cf` 参数指定只需要查看哪些列族。 - -```bash -$ tikv-ctl --db /path/to/tikv/db scan --from 'zm' --limit 2 --show-cf lock,default,write -key: zmBootstr\377a\377pKey\000\000\377\000\000\373\000\000\000\000\000\377\000\000s\000\000\000\000\000\372 - write cf value: start_ts: 399650102814441473 commit_ts: 399650102814441475 short_value: "20" -key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371 - write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002" - write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001" -``` - -### 查看给定 key 的 MVCC - -与上个命令类似，`mvcc` 命令可以查看给定 key 的 MVCC： - -```bash -$ tikv-ctl --db /path/to/tikv/db mvcc -k "zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371" --show-cf=lock,write,default -key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371 - write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002" - write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001" -``` - -> **注意：** -> -> 该命令中，key 同样需要是 escaped 形式的 raw key。 - -### 打印某个 key 的值 - -打印某个 key 的值需要用到 `print` 命令。示例从略。 - -### 打印 Region 的 properties 信息 - -为了记录 Region 的状态信息，TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 `region-properties` 运行 tikv-ctl 来查看这些 properties 信息。例如： - -```bash -$ tikv-ctl --host localhost:20160 region-properties -r 2 -num_files: 0 -num_entries: 0 -num_deletes: 0 -mvcc.min_ts: 18446744073709551615 -mvcc.max_ts: 0 -mvcc.num_rows: 0 -mvcc.num_puts: 0 -mvcc.num_versions: 0 -mvcc.max_row_versions: 0 -middle_key_by_approximate_size: -``` - -这些 properties 信息可以用于检查某个 Region 是否健康或者修复不健康的 Region。例如，使用 `middle_key_approximate_size` 可以手动分裂 Region。 - -### 手动 compact 单个 TiKV 的数据 - -`compact` 命令可以对单个 TiKV 进行手动 compact。如果指定 `--from` 和 `--to` 选项，那么它们的参数也是 escaped raw key 形式的。`--host` 参数可以指定要 compact 的 TiKV，`-d` 参数可以指定要 compact 的 RocksDB，有 `kv` 和 `raft` 参数值可以选。`--threads` 参数可以指定 compact 的并发数，默认值是 8。一般来说，并发数越大， compact 的速度越快，但是也会对服务造成影响，所以需要根据情况选择合适的并发数。 - -```bash -$ tikv-ctl --host 127.0.0.1:20160 compact -d kv -success! -``` - -### 手动 compact 整个 TiKV 集群的数据 - -`compact-cluster` 命令可以对整个 TiKV 集群进行手动 compact。该命令参数的含义和使用与 `compact` 命令一样。 - -### 设置一个 Region 为 tombstone - -`tombstone` 命令常用于没有开启 sync-log，因为机器掉电导致 Raft 状态机丢失部分写入的情况。它可以在一个 TiKV 实例上将一些 Region 设置为 Tombstone 状态，从而在重启时跳过这些 Region。这些 Region 应该在其他 TiKV 上有足够多的健康的副本以便能够继续通过 Raft 机制进行读写。 - -```bash -pd-ctl>> operator add remove-peer -$ tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r -success! -``` - -> **注意：** -> -> - **该命令只支持本地模式** -> - `-p` 选项的参数指定 PD 的 endpoints，无需 `http` 前缀。指定 PD 的 endpoints 是为了询问 PD 是否可以安全切换至 Tombstone 状态。因此，在将 PD 置为 Tombstone 之前往往还需要在 `pd-ctl` 中把该 Region 在机器上的对应 Peer 拿掉。 - -### 向 TiKV 发出 consistency-check 请求 - -`consistency-check` 命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败，TiKV 自身会 panic。如果 `--host` 指定的 TiKV 不是这个 Region 的 Leader，则会报告错误。 - -```bash -$ tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2 -success! -$ tikv-ctl --host 127.0.0.1:21061 consistency-check -r 2 -DebugClient::check_region_consistency: RpcFailure(RpcStatus { status: Unknown, details: Some("StringError(\"Leader is on store 1\")") }) -``` - -> **注意：** -> -> - **该命令只支持远程模式**。 -> - 即使该命令返回了成功信息，也需要检查是否有 TiKV panic 了。因为该命令只是向 Leader 请求进行一致性检查，但整个检查流程是否成功并不能在客户端知道。 - -### Dump snapshot 元文件 - -这条子命令可以用于解析指定路径下的 Snapshot 元文件并打印结果。 - -### 打印 Raft 状态机出错的 Region - -前面 `tombstone` 命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态，避免 TiKV 启动时对它们进行检查。在运行 `tombstone` 命令之前，可使用 `bad-regions` 命令找到出错的 Region，以便将多个工具组合起来进行自动化的处理。 - -```bash -$ tikv-ctl --db /path/to/tikv/db bad-regions -all regions are healthy -``` - -命令执行成功后会打印以上信息，否则会打印出有错误的 Region 列表。目前可以检出的错误包括 `last index`、`commit index` 和 `apply index` 之间的不匹配，以及 Raft log 的丢失。其他一些情况，比如 Snapshot 文件损坏等仍然需要后续的支持。 - -### 查看 Region 属性 - -本地查看部署在 `/path/to/tikv` 的 tikv 上面 Region 2 的 properties 信息： - -```bash -$ tikv-ctl --db /path/to/tikv/data/db region-properties -r 2 -``` - -在线查看运行在 `127.0.0.1:20160` 的 tikv 上面 Region 2 的 properties 信息： - -```bash -$ tikv-ctl --host 127.0.0.1:20160 region-properties -r 2 -``` - -### 动态修改 TiKV 的 RocksDB 相关配置 - -使用 `modify-tikv-config` 命令可以动态修改配置参数，暂时仅支持对于 RocksDB 相关参数的动态更改。 - -- `-m` 用于指定要修改的 RocksDB，有 `kvdb` 和 `raftdb` 两个值可以选择。 -- `-n` 用于指定配置名。配置名可以参考 [TiKV 配置模版](https://github.com/pingcap/tikv/blob/master/etc/config-template.toml#L213-L500)中 `[rocksdb]` 和 `[raftdb]` 下的参数，分别对应 `kvdb` 和 `raftdb`。同时，还可以通过 `default|write|lock + . + 参数名` 的形式来指定的不同 CF 的配置。对于 `kvdb` 有 `default`、`write` 和 `lock` 可以选择，对于 `raftdb` 仅有 `default` 可以选择。 -- `-v` 用于指定配置值。 - -```bash -$ tikv-ctl modify-tikv-config -m kvdb -n max_background_jobs -v 8 -success! -$ tikv-ctl modify-tikv-config -m kvdb -n write.block-cache-size -v 256MB -success! -$ tikv-ctl modify-tikv-config -m raftdb -n default.disable_auto_compactions -v true -success! -``` - -### 强制 Region 从多副本失败状态恢复服务 - -`unsafe-recover remove-fail-stores` 命令可以将故障机器从指定 Region 的 peer 列表中移除。运行命令之前，需要目标 TiKV 先停掉服务以便释放文件锁。 - -`-s` 选项接受多个以逗号分隔的 `store_id`，并使用 `-r` 参数来指定包含的 Region。如果要对某一个 store 上的全部 Region 都执行这个操作，可简单指定 `--all-regions`。 - -```bash -$ tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 3 -r 1001,1002 -success! - -$ tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 4,5 --all-regions -``` - -之后启动 TiKV，这些 Region 便可以使用剩下的健康副本继续提供服务了。此命令常用于多个 TiKV store 损坏或被删除的情况。 - -> **注意：** -> -> - 该命令只支持本地模式。在运行成功后，会打印 `success!`。 -> - 一般来说，您需要为指定 Region 的 peers 所在的每个 store 运行此命令。 -> - 如果使用 `--all-regions`，通常需要在集群剩余所有健康的 store 上执行此命令。 - -### 恢复损坏的 MVCC 数据 - -`recover-mvcc` 命令用于 MVCC 数据损坏导致 TiKV 无法正常运行的情况。为了从不同种类的不一致情况中恢复，该命令会交叉检查 3 个 CF ("default", "write", "lock")。 - -`-r` 选项可以通过 `region_id` 指定包含的 Region，`-p` 选项可以指定 PD 的 endpoints。 - -```bash -$ tikv-ctl --db /path/to/tikv/db recover-mvcc -r 1001,1002 -p 127.0.0.1:2379 -success! -``` - -> **注意：** -> -> - 该命令只支持本地模式。在运行成功后，会打印 `success!`。 -> - `-p` 选项指定 PD 的 endpoint，不使用 `http` 前缀，用于查询指定的 `region_id` 是否有效。 -> - 对于指定 Region 的 peers 所在的每个 store，均须执行该命令。 - -### Ldb 命令 - -ldb 命令行工具提供多种数据访问以及数据库管理命令。下方列出了一些示例用法。详细信息请在运行 `tikv-ctl ldb` 命令时查看帮助消息或查阅 RocksDB 文档。 - -数据访问序列示例如下。 - -用 HEX 格式 dump 现有 RocksDB 数据: - -```bash -$ tikv-ctl ldb --hex --db=/tmp/db dump -``` - -dump 现有 RocksDB 的声明： - -```bash -$ tikv-ctl ldb --hex manifest_dump --path=/tmp/db/MANIFEST-000001 -``` - -您可以通过 `--column_family=` 指定查询的目标列族。 - -通过 `--try_load_options` 命令加载数据库选项文件以打开数据库。在数据库运行时，建议您保持该命令为开启的状态。如果您使用默认配置打开数据库，LSM-tree 存储组织可能会出现混乱，且无法自动恢复。 diff --git a/v2.1/reference/transactions/overview.md b/v2.1/reference/transactions/overview.md deleted file mode 100644 index 5be9dcddf356..000000000000 --- a/v2.1/reference/transactions/overview.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB 事务概览 -summary: 了解 TiDB 中的事务。 -category: reference ---- - -# TiDB 事务概览 - -TiDB 支持完整的分布式事务，使用[乐观事务模型](/v2.1/reference/transactions/transaction-optimistic.md)。本文主要介绍涉及到事务的语句、显式/隐式事务、事务的隔离级别和惰性检查，以及事务大小的限制。 - -常用的变量包括 [`autocommit`](#自动提交)、[`tidb_disable_txn_auto_retry`](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_disable_txn_auto_retry) 以及 [`tidb_retry_limit`](/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_retry_limit)。 - -## 常用事务语句 - -### `BEGIN` 和 `START TRANSACTION` - -语法： - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION WITH CONSISTENT SNAPSHOT; -``` - -以上三条语句都用于开启事务，效果相同。执行开启事务语句可以显式地开启一个新的事务。如果执行以上语句时，当前 Session 正处于一个事务的中间过程，那么系统会先自动提交当前事务，再开启一个新的事务。 - -### `COMMIT` - -语法： - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -该语句用于提交当前的事务，包括从 `[BEGIN|START TRANSACTION]` 到 `COMMIT` 之间的所有修改。 - -### `ROLLBACK` - -语法： - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -该语句用于回滚当前事务，撤销从 `[BEGIN|START TRANSACTION]` 到 `ROLLBACK` 之间的所有修改。 - -## 自动提交 - -语法： - -{{< copyable "sql" >}} - -```sql -SET autocommit = {0 | 1} -``` - -当 `autocommit = 1` 时（默认），当前的 Session 为自动提交状态，即每条语句运行后，TiDB 会自动将修改提交到数据库中。设置 `autocommit = 0` 时更改当前 Session 更改为非自动提交状态，通过执行 `COMMIT` 语句来手动提交事务。 - -> **注意：** -> -> 某些语句执行后会导致隐式提交。例如，执行 `[BEGIN|START TRANCATION]` 语句时，TiDB 会试图提交上一个事务，并开启一个新的事务。详情参见 [implicit commit](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html)。 - -另外，`autocommit` 也是一个系统变量，你可以通过变量赋值语句修改当前 Session 或 Global 的值。 - -{{< copyable "sql" >}} - -```sql -SET @@SESSION.autocommit = {0 | 1}; -``` - -{{< copyable "sql" >}} - -```sql -SET @@GLOBAL.autocommit = {0 | 1}; -``` - -## 显式事务和隐式事务 - -TiDB 可以显式地使用事务（通过 `[BEGIN|START TRANSACTION]`/`COMMIT` 语句定义事务的开始和结束) 或者隐式地使用事务 (`SET autocommit = 1`)。 - -在自动提交状态下，使用 `[BEGIN|START TRANSACTION]` 语句会显式地开启一个事务，同时也会禁用自动提交，使隐式事务变成显式事务。直到执行 `COMMIT` 或 `ROLLBACK` 语句时才会恢复到此前默认的自动提交状态。 - -对于 DDL 语句，会自动提交并且不能回滚。如果运行 DDL 的时候，正在一个事务的中间过程中，会先自动提交当前事务，再执行 DDL。 - -## 事务隔离级别 - -TiDB **只支持** `SNAPSHOT ISOLATION`，可以通过下面的语句将当前 Session 的隔离级别设置为 `READ COMMITTED`，这只是语法上的兼容，事务依旧是以 `SNAPSHOT ISOLATION` 来执行。 - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -## 惰性检查 - -TiDB 中，对于普通的 `INSERT` 语句写入的值，会进行惰性检查。惰性检查的含义是，不在 `INSERT` 语句执行时进行唯一约束的检查，而在事务提交时进行唯一约束的检查。 - -举例： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE T (I INT KEY); -INSERT INTO T VALUES (1); -BEGIN; -INSERT INTO T VALUES (1); -- MySQL 返回错误；TiDB 返回成功 -INSERT INTO T VALUES (2); -COMMIT; -- MySQL 提交成功；TiDB 返回错误，事务回滚 -SELECT * FROM T; -- MySQL 返回 1 2；TiDB 返回 1 -``` - -惰性检查的意义在于，如果对事务中每个 `INSERT` 语句都立刻进行唯一性约束检查，将造成很高的网络开销。而在提交时进行一次批量检查，将会大幅提升性能。 - -> **注意：** -> -> 本优化仅对普通的 `INSERT` 语句生效，对 `INSERT IGNORE` 和 `INSERT ON DUPLICATE KEY UPDATE` 不会生效。 - -## 语句回滚 - -TiDB 支持语句执行的原子性回滚。在事务内部执行一个语句，遇到错误时，该语句整体不会生效。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -commit; -``` - -上面的例子里面，第二条语句执行失败，但第一和第三条语句仍然能正常提交。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -rollback; -``` - -以上例子中，第二条语句执行失败。由于调用了 `ROLLBACK`，因此事务不会将任何数据写入数据库。 - -## 事务大小 - -对于 TiDB 事务而言，事务太大或太小，都会影响事务的执行效率。 - -### 小事务 - -以如下 query 为例，当 `autocommit = 1` 时，下面三条语句各为一个事务： - -{{< copyable "sql" >}} - -```sql -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -``` - -此时每一条语句都需要经过两阶段提交，频繁的网络交互致使延迟率高。为提升事务执行效率，可以选择使用显式事务，即在一个事务内执行三条语句。 - -优化后版本： - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -COMMIT; -``` - -同理，执行 `INSERT` 语句时，建议使用显式事务。 - -> **注意：** -> -> 由于 TiDB 中的资源是分布式的，TiDB 中单线程 workload 可能不会很好地利用分布式资源，因此性能相比于单实例部署的 MySQL 较低。这与 TiDB 中的事务延迟较高的情況类似。 - -### 大事务 - -由于 TiDB 两阶段提交的要求，修改数据的单个事务过大时会存在以下问题： - -* 客户端在提交之前，数据都写在内存中，而数据量过多时易导致 OOM (Out of Memory) 错误。 -* 在第一阶段写入数据耗时增加，与其他事务出现写冲突的概率会指数级增长。 -* 最终导致事务完成提交的耗时增加。 - -因此，TiDB 对事务做了一些限制： - -* 单个事务包含的 SQL 语句不超过 5000 条（默认） -* 每个键值对不超过 6 MB -* 键值对的总数不超过 300000 -* 键值对的总大小不超过 100 MB - -为了使性能达到最优，建议每 100～500 行写入一个事务。 \ No newline at end of file diff --git a/v2.1/reference/transactions/transaction-isolation.md b/v2.1/reference/transactions/transaction-isolation.md deleted file mode 100644 index 6f291c5bc07a..000000000000 --- a/v2.1/reference/transactions/transaction-isolation.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 事务隔离级别 -summary: 了解 TiDB 事务的隔离级别。 -category: reference ---- - -# TiDB 事务隔离级别 - -事务隔离级别是数据库事务处理的基础，[ACID](/v2.1/glossary.md#acid) 中的 “I”，即 Isolation，指的就是事务的隔离性。 - -SQL-92 标准定义了 4 种隔离级别：读未提交 (READ UNCOMMITTED)、读已提交 (READ COMMITTED)、可重复读 (REPEATABLE READ)、串行化 (SERIALIZABLE)。详见下表： - -| Isolation Level | Dirty Write | Dirty Read | Fuzzy Read | Phantom | -| ---------------- | ------------ | ------------ | ------------ | ------------ | -| READ UNCOMMITTED | Not Possible | Possible | Possible | Possible | -| READ COMMITTED | Not Possible | Not possible | Possible | Possible | -| REPEATABLE READ | Not Possible | Not possible | Not possible | Possible | -| SERIALIZABLE | Not Possible | Not possible | Not possible | Not possible | - -TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](#与-ansi-可重复读隔离级别的区别)和 [MySQL 可重复读隔离级别](#与-mysql-可重复读隔离级别的区别)。 - -> **注意：** -> -> 在 TiDB 2.1 中，事务的自动重试功能默认开启。关于该项功能对隔离级别的影响以及如何开启该项功能，请参考[事务重试](/v2.1/reference/transactions/transaction-optimistic.md#重试机制)。 - -## 可重复读 - -当事务隔离级别为可重复读时，只能读到该事务启动时已经提交的其他事务修改的数据，未提交的数据或在事务启动后其他事务提交的数据是不可见的。对于本事务而言，事务语句可以看到之前的语句做出的修改。 - -对于运行于不同节点的事务而言，不同事务启动和提交的顺序取决于从 PD 获取时间戳的顺序。 - -处于可重复读隔离级别的事务不能并发的更新同一行，当时事务提交时发现该行在该事务启动后，已经被另一个已提交的事务更新过，那么该事务会回滚并启动自动重试。示例如下： - -```sql -create table t1(id int); -insert into t1 values(0); - -start transaction; | start transaction; -select * from t1; | select * from t1; -update t1 set id=id+1; | update t1 set id=id+1; -commit; | - | commit; -- 事务提交失败，回滚 -``` - -### 与 ANSI 可重复读隔离级别的区别 - -尽管名称是可重复读隔离级别，但是 TiDB 中可重复读隔离级别和 ANSI 可重复隔离级别是不同的。按照 [A Critique of ANSI SQL Isolation Levels](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf) 论文中的标准，TiDB 实现的是论文中的快照隔离级别。该隔离级别不会出现狭义上的幻读 (A3)，但不会阻止广义上的幻读 (P3)，同时，SI 还会出现写偏斜，而 ANSI 可重复读隔离级别不会出现写偏斜，会出现幻读。 - -### 与 MySQL 可重复读隔离级别的区别 - -MySQL 可重复读隔离级别在更新时并不检验当前版本是否可见，也就是说，即使该行在事务启动后被更新过，同样可以继续更新。这种情况在 TiDB 会导致事务回滚，导致事务最终失败，而 MySQL 是可以更新成功的。MySQL 的可重复读隔离级别并非快照隔离级别，MySQL 可重复读隔离级别的一致性要弱于快照隔离级别，也弱于 TiDB 的可重复读隔离级别。 - -## 更多阅读 - -- [TiKV 的 MVCC (Multi-Version Concurrency Control) 机制](https://pingcap.com/blog-cn/mvcc-in-tikv/) \ No newline at end of file diff --git a/v2.1/reference/transactions/transaction-optimistic.md b/v2.1/reference/transactions/transaction-optimistic.md deleted file mode 100644 index 92f25c752e4d..000000000000 --- a/v2.1/reference/transactions/transaction-optimistic.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: TiDB 乐观事务模型 -summary: 了解 TiDB 的乐观事务模型。 -category: reference -aliases: ['/docs-cn/v2.1/reference/transactions/transaction-model/'] ---- - -# TiDB 乐观事务模型 - -本文介绍 TiDB 乐观事务的原理，以及相关特性。本文假定你对 [TiDB 的整体架构](/v2.1/architecture.md#tidb-整体架构)、[Percolator](https://www.usenix.org/legacy/event/osdi10/tech/full_papers/Peng.pdf) 事务模型以及事务的 [ACID 特性](/v2.1/glossary.md#acid)都有一定了解。 - -TiDB 默认使用乐观事务模型，不会出现读写冲突，所有的读操作都不会被写操作阻塞。对于写写冲突，只有在客户端执行 `COMMIT` 时，才会触发两阶段提交并检测是否存在写写冲突。 - -## 乐观事务原理 - -TiDB 中事务使用两阶段提交，流程如下： - -![TiDB 中的两阶段提交](/media/2pc-in-tidb.png) - -1. 客户端开始一个事务。 - - TiDB 从 PD 获取一个全局唯一递增的版本号作为当前事务的开始版本号，这里定义为该事务的 `start_ts` 版本。 - -2. 客户端发起读请求。 - - 1. TiDB 从 PD 获取数据路由信息，即数据具体存在哪个 TiKV 节点上。 - 2. TiDB 从 TiKV 获取 `start_ts` 版本下对应的数据信息。 - -3. 客户端发起写请求。 - - TiDB 校验写入数据是否符合一致性约束（如数据类型是否正确、是否符合唯一索引约束等）。**校验通过的数据将存放在内存里。** - -4. 客户端发起 commit。 - -5. TiDB 开始两阶段提交，保证分布式事务的原子性，让数据真正落盘。 - - 1. TiDB 从当前要写入的数据中选择一个 Key 作为当前事务的 Primary Key。 - 2. TiDB 从 PD 获取所有数据的写入路由信息，并将所有的 Key 按照所有的路由进行分类。 - 3. TiDB 并发地向所有涉及的 TiKV 发起 prewrite 请求。TiKV 收到 prewrite 数据后，检查数据版本信息是否存在冲突或已过期。符合条件的数据会被加锁。 - 4. TiDB 收到所有 prewrite 响应且所有 prewrite 都成功。 - 5. TiDB 向 PD 获取第二个全局唯一递增版本号，定义为本次事务的 `commit_ts`。 - 6. TiDB 向 Primary Key 所在 TiKV 发起第二阶段提交。TiKV 收到 commit 操作后，检查数据合法性，清理 prewrite 阶段留下的锁。 - 7. TiDB 收到两阶段提交成功的信息。 - -6. TiDB 向客户端返回事务提交成功的信息。 - -7. TiDB 异步清理本次事务遗留的锁信息。 - -## 优缺点分析 - -通过分析 TiDB 中事务的处理流程，可以发现 TiDB 事务有如下优点： - -* 实现原理简单，易于理解。 -* 基于单实例事务实现了跨节点事务。 -* 锁管理实现了去中心化。 - -但 TiDB 事务也存在以下缺点： - -* 两阶段提交使网络交互增多。 -* 需要一个中心化的版本管理服务。 -* 事务数据量过大时易导致内存暴涨。 - -实际应用中，你可以[根据事务的大小进行针对性处理](/v2.1/reference/transactions/overview.md#事务大小)，以提高事务的执行效率。 - -## 事务的重试 - -使用乐观事务模型时，在高冲突率的场景中，事务很容易提交失败。而 MySQL 内部使用的是悲观事务模型，在执行 SQL 语句的过程中进行冲突检测，所以提交时很难出现异常。为了兼容 MySQL 的悲观事务行为，TiDB 提供了重试机制。 - -### 重试机制 - -当事务提交后，如果发现冲突，TiDB 内部重新执行包含写操作的 SQL 语句。你可以通过设置 `tidb_disable_txn_auto_retry = off` 开启自动重试，并通过 `tidb_retry_limit` 设置重试次数： - -```sql -# 设置是否禁用自动重试，默认为 “on”，即不重试。 -tidb_disable_txn_auto_retry = off -# 控制重试次数，默认为 “10”。只有自动重试启用时该参数才会生效。 -# 当 “tidb_retry_limit= 0” 时，也会禁用自动重试。 -tidb_retry_limit = 10 -``` - -你也可以修改当前 Session 或 Global 的值： - -- Session 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@tidb_retry_limit = 10; - ``` - -- Global 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_retry_limit = 10; - ``` - -> **注意：** -> -> `tidb_retry_limit` 变量决定了事务重试的最大次数。当它被设置为 0 时，所有事务都不会自动重试，包括自动提交的单语句隐式事务。这是彻底禁用 TiDB 中自动重试机制的方法。禁用自动重试后，所有冲突的事务都会以最快的方式上报失败信息 (`try again later`) 给应用层。 - -### 重试的局限性 - -TiDB 默认不进行事务重试，因为重试事务可能会导致更新丢失，从而破坏[可重复读的隔离级别](/v2.1/reference/transactions/transaction-isolation.md)。 - -事务重试的局限性与其原理有关。事务重试可概括为以下三个步骤： - -1. 重新获取 `start_ts`。 -2. 重新执行包含写操作的 SQL 语句。 -3. 再次进行两阶段提交。 - -第二步中，重试时仅重新执行包含写操作的 SQL 语句，并不涉及读操作的 SQL 语句。但是当前事务中读到数据的时间与事务真正开始的时间发生了变化，写入的版本变成了重试时获取的 `start_ts` 而非事务一开始时获取的 `start_ts`。因此，当事务中存在依赖查询结果来更新的语句时，重试将无法保证事务原本可重复读的隔离级别，最终可能导致结果与预期出现不一致。 - -如果业务可以容忍事务重试导致的异常，或并不关注事务是否以可重复读的隔离级别来执行，则可以开启自动重试。 - -## 冲突检测 - -乐观事务下，检测底层数据是否存在写写冲突是一个很重要的操作。具体而言，TiKV 在 prewrite 阶段就需要读取数据进行检测。为了优化这一块性能，TiDB 集群会在内存里面进行一次冲突预检测。 - -作为一个分布式系统，TiDB 在内存中的冲突检测主要在两个模块进行： - -- TiDB 层。如果发现 TiDB 实例本身就存在写写冲突，那么第一个写入发出后，后面的写入已经清楚地知道自己冲突了，无需再往下层 TiKV 发送请求去检测冲突。 -- TiKV 层。主要发生在 prewrite 阶段。因为 TiDB 集群是一个分布式系统，TiDB 实例本身无状态，实例之间无法感知到彼此的存在，也就无法确认自己的写入与别的 TiDB 实例是否存在冲突，所以会在 TiKV 这一层检测具体的数据是否有冲突。 - -其中 TiDB 层的冲突检测可以根据场景需要选择打开或关闭，具体配置项如下： - -```toml -# 事务内存锁相关配置，当本地事务冲突比较多时建议开启。 -[txn-local-latches] -# 是否开启内存锁，默认为 false，即不开启。 -enabled = false -# Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。 -# 每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据）， -# 设置过小会导致变慢，性能下降。（默认为 2048000） -capacity = 2048000 -``` - -配置项 `capacity` 主要影响到冲突判断的正确性。在实现冲突检测时，不可能把所有的 Key 都存到内存里，所以真正存下来的是每个 Key 的 Hash 值。有 Hash 算法就有碰撞也就是误判的概率，这里可以通过配置 `capacity` 来控制 Hash 取模的值： - -* `capacity` 值越小，占用内存小，误判概率越大。 -* `capacity` 值越大，占用内存大，误判概率越小。 - -实际应用时，如果业务场景能够预判断写入不存在冲突（如导入数据操作），建议关闭冲突检测。 - -相应地，在 TiKV 层检测内存中是否存在冲突也有类似的机制。不同的是，TiKV 层的检测会更严格且不允许关闭，仅支持对 Hash 取模值进行配置： - -```toml -# scheduler 内置一个内存锁机制，防止同时对一个 Key 进行操作。 -# 每个 Key hash 到不同的 slot。（默认为 2048000） -scheduler-concurrency = 2048000 -``` - -此外，TiKV 支持监控等待 latch 的时间： - -![Scheduler latch wait duration](/media/optimistic-transaction-metric.png) - -当 `Scheduler latch wait duration` 的值特别高时，说明大量时间消耗在等待锁的请求上。如果不存在底层写入慢的问题，基本上可以判断该段时间内冲突比较多。 - -## 更多阅读 - -- [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/) \ No newline at end of file diff --git a/v2.1/releases/11alpha.md b/v2.1/releases/11alpha.md deleted file mode 100644 index e7d5f179b235..000000000000 --- a/v2.1/releases/11alpha.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB 1.1 Alpha Release Notes -category: Releases ---- - -# TiDB 1.1 Alpha Release Notes - -2018 年 1 月 19 日，TiDB 发布 1.1 Alpha 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -- SQL parser - - 兼容更多语法 -- SQL 查询优化器 - - 统计信息减小内存占用 - - 优化统计信息启动时载入的时间 - - 更精确的代价估算 - - 使用 `Count-Min Sketch` 更精确地估算点查的代价 - - 支持更复杂的条件，更充分使用索引 -- SQL 执行器 - - 使用 Chunk 结构重构所有执行器算子，提升分析型语句执行性能，减少内存占用 - - 优化 `INSERT IGNORE` 语句性能 - - 下推更多的类型和函数 - - 支持更多的 `SQL_MODE` - - 优化 `Load Data` 性能，速度提升 10 倍 - - 优化 `Use Database` 性能 - - 支持对物理算子内存使用进行统计 -- Server - - 支持 PROXY protocol - -## PD - -- 增加更多的 API -- 支持 TLS -- 给 Simulator 增加更多的 case -- 调度适应不同的 Region size -- Fix 了一些调度的 bug - -## TiKV - -- 支持 Raft learner -- 优化 Raft Snapshot，减少 I/O 开销 -- 支持 TLS -- 优化 RocksDB 配置，提升性能 -- 优化 Coprocessor `count (*)` 和点查 unique index 的性能 -- 增加更多的 Failpoint 以及稳定性测试 case -- 解决 PD 和 TiKV 之间重连的问题 -- 增强数据恢复工具 `tikv-ctl` 的功能 -- Region 支持按 table 进行分裂 -- 支持 `Delete Range` 功能 -- 支持设置 snapshot 导致的 I/O 上限 -- 完善流控机制 diff --git a/v2.1/releases/11beta.md b/v2.1/releases/11beta.md deleted file mode 100644 index be72f038e76f..000000000000 --- a/v2.1/releases/11beta.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB 1.1 Beta Release Notes -category: Releases ---- - -# TiDB 1.1 Beta Release Notes - -2018 年 2 月 24 日，TiDB 发布 1.1 Beta 版。该版本在 1.1 Alpha 版的基础上，对 MySQL 兼容性、系统稳定性做了很多改进。 - -## TiDB - -+ 添加更多监控项, 优化日志 -+ 兼容更多 MySQL 语法 -+ 在 `information_schema` 中支持显示建表时间 -+ 提速包含 `MaxOneRow` 算子的查询 -+ 控制 Join 产生的中间结果集大小，进一步减少 Join 的内存使用 -+ 增加 `tidb_config` session 变量，输出当前 TiDB 配置 -+ 修复 `Union` 和 `Index Join` 算子中遇到的 panic 问题 -+ 修复 `Sort Merge Join` 算子在部分场景下结果错误的问题 -+ 修复 `Show Index` 语句显示正在添加过程中的索引的问题 -+ 修复 `Drop Stats` 语句失败的问题 -+ 优化 SQL 引擎查询性能，Sysbench 的 Select/OLTP 测试结果提升 10% -+ 使用新的执行引擎提升优化器中的子查询计算速度；相比 1.0 版本，在 TPC-H 以及 TPC-DS 等测试中有显著提升 - -## PD - -+ 增加 Drop Region 调试接口 -+ 支持设置 PD leader 优先级 -+ 支持配置特定 label 的节点不调度 Raft leader -+ 增加枚举各个 PD health 状态的接口 -+ 添加更多 metrics -+ PD leader 尽量与 etcd leader 保持同步 -+ 提高 TiKV 宕机时数据恢复优先级和恢复速度 -+ 完善 `data-dir` 配置项的合法性较验 -+ 优化 Region heartbeat 性能 -+ 修复热点调度破坏 label 约束的问题 -+ 其他稳定性问题修复 - -## TiKV - -+ 使用 offset + limit 遍历 lock，消除潜在的 GC 问题 -+ 支持批量 resolve lock，提升 GC 速度 -+ 支持并行 GC，提升 GC 速度 -+ 使用 RocksDB compaction listener 更新 Region Size，让 PD 更精确的进行调度 -+ 使用 `DeleteFilesInRanges` 批量删除过期数据，提高 TiKV 启动速度 -+ 设置 Raft snapshot max size，防止遗留文件占用太多空间 -+ `tikv-ctl` 支持更多修复操作 -+ 优化有序流式聚合操作 -+ 完善 metrics，修复 bug \ No newline at end of file diff --git a/v2.1/releases/2.0.10.md b/v2.1/releases/2.0.10.md deleted file mode 100644 index 4eced6e55285..000000000000 --- a/v2.1/releases/2.0.10.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.0.10 Release Notes -category: Releases ---- - -# TiDB 2.0.10 Release Notes - -2018 年 12 月 18 日，TiDB 发布 2.0.10 版，TiDB Ansible 相应发布 2.0.10 版本。该版本在 2.0.9 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复取消 DDL 任务的时候可能导致的问题 [#8513](https://github.com/pingcap/tidb/pull/8513) -- 修复 `ORDER BY`，`UNION` 语句无法引用带表名的列的问题 [#8514](https://github.com/pingcap/tidb/pull/8514) -- 修复 `UNCOMPRESS` 函数没有判断错误输入长度的问题 [#8607](https://github.com/pingcap/tidb/pull/8607) -- 修复 `ANSI_QUOTES SQL_MODE` 在 TiDB 升级的时候遇到的问题 [#8575](https://github.com/pingcap/tidb/pull/8575) -- 修复某些情况下 `select` 返回结果错误的问题 [#8570](https://github.com/pingcap/tidb/pull/8570) -- 修复 TiDB 在收到退出信号的时候可能无法退出的问题 [#8501](https://github.com/pingcap/tidb/pull/8501) -- 修复某些情况下 `IndexLookUpJoin` 返回错误结果的问题 [#8508](https://github.com/pingcap/tidb/pull/8508) -- 避免下推有 `GetVar` 或 `SetVar 的 filter` [#8454](https://github.com/pingcap/tidb/pull/8454) -- 修复某些情况下 `UNION` 语句结果长度错误的问题 [#8491](https://github.com/pingcap/tidb/pull/8491) -- 修复 `PREPARE FROM @var_name` 的问题 [#8488](https://github.com/pingcap/tidb/pull/8488) -- 修复某些情况下导出统计信息 panic 的问题 [#8464](https://github.com/pingcap/tidb/pull/8464) -- 修复统计信息某些情况下对点查估算的问题 [#8493](https://github.com/pingcap/tidb/pull/8493) -- 修复某些情况下返回 Enum 默认值为字符串导致的 panic [#8476](https://github.com/pingcap/tidb/pull/8476) -- 修复在宽表场景下，占用太多内存的问题 [#8467](https://github.com/pingcap/tidb/pull/8467) -- 修复 Parser 对取模操作错误格式化导致的问题 [#8431](https://github.com/pingcap/tidb/pull/8431) -- 修复某些情况下添加外键约束导致的 panic 问题 [#8421](https://github.com/pingcap/tidb/pull/8421)，[#8410](https://github.com/pingcap/tidb/pull/8410) -- 修复 `YEAR` 类型错误转换零值的问题 [#8396](https://github.com/pingcap/tidb/pull/8396) -- 修复 `VALUES` 函数在参数不为列的时候 panic 的问题 [#8404](https://github.com/pingcap/tidb/pull/8404) -- 存在子查询的语句禁用 Plan Cache [#8395](https://github.com/pingcap/tidb/pull/8395) - -## PD - -- 修复 RaftCluster 在退出时可能的死锁问题 [#1370](https://github.com/pingcap/pd/pull/1370) - -## TiKV - -- 修复迁移 Leader 到新节点时造成请求延时问题 [#3929](https://github.com/tikv/tikv/pull/3929) -- 修复多余的 Region 心跳 [#3930](https://github.com/tikv/tikv/pull/3930) diff --git a/v2.1/releases/2.0.11.md b/v2.1/releases/2.0.11.md deleted file mode 100644 index 762cfefa246b..000000000000 --- a/v2.1/releases/2.0.11.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: TiDB 2.0.11 Release Notes -category: Releases ---- - -# TiDB 2.0.11 Release Notes - -2019 年 1 月 3 日，TiDB 发布 2.0.11 版，TiDB Ansible 相应发布 2.0.11 版本。该版本在 2.0.10 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复 PD 发生异常的情况下，Error 没有被正确处理的问题 [#8764](https://github.com/pingcap/tidb/pull/8764) -- 修复 Rename 相同表的行为，跟 MySQL 保持一致 [#8809](https://github.com/pingcap/tidb/pull/8809) -- 修复 `ADMIN CHECK TABLE` 在 `ADD INDEX` 过程中误报的问题 [#8750](https://github.com/pingcap/tidb/pull/8750) -- 修复前缀索引在某些情况下，开闭范围区间错误的问题 [#8877](https://github.com/pingcap/tidb/pull/8877) -- 修复在某些添加列的情况下，`UPDATE` 语句 panic 的问题 [#8904](https://github.com/pingcap/tidb/pull/8904) - -## TiKV - -- 修复了两个 Region merge 相关的问题 -[#4003](https://github.com/tikv/tikv/pull/4003)，[#4004](https://github.com/tikv/tikv/pull/4004) diff --git a/v2.1/releases/2.0ga.md b/v2.1/releases/2.0ga.md deleted file mode 100644 index bf90ec62748a..000000000000 --- a/v2.1/releases/2.0ga.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: TiDB 2.0 release notes -category: Releases ---- - -# TiDB 2.0 Release Notes - -2018 年 4 月 27 日，TiDB 发布 2.0 GA 版。相比 1.0 版本，该版本对 MySQL 兼容性、系统稳定性、优化器和执行器做了很多改进。 - -## TiDB - -- SQL 优化器 - - 精简统计信息数据结构，减小内存占用 - - 加快进程启动时加载统计信息速度 - - 支持统计信息动态更新 [experimental] - - 优化代价模型，对代价估算更精准 - - 使用 `Count-Min Sketch` 更精确地估算点查的代价 - - 支持分析更复杂的条件，尽可能充分的使用索引 - - 支持通过 `STRAIGHT_JOIN` 语法手动指定 Join 顺序 - - `GROUP BY`子句为空时使用 Stream Aggregation 算子，提升性能 - - 支持使用索引计算 `Max/Min` 函数 - - 优化关联子查询处理算法，支持将更多类型的关联子查询解关联并转化成 `Left Outer Join` - - 扩大 `IndexLookupJoin` 的使用范围，索引前缀匹配的场景也可以使用该算法 -- SQL 执行引擎 - - 使用 Chunk 结构重构所有执行器算子，提升分析型语句执行性能，减少内存占用，显著提升 TPC-H 结果 - - 支持 Streaming Aggregation 算子下推 - - 优化 `Insert Into Ignore` 语句性能，提升 10 倍以上 - - 优化 `Insert On Duplicate Key Update` 语句性能，提升 10 倍以上 - - 下推更多的数据类型和函数到 TiKV 计算 - - 优化 `Load Data` 性能，提升 10 倍以上 - - 支持对物理算子内存使用进行统计，通过配置文件以及系统变量指定超过阈值后的处理行为 - - 支持限制单条 SQL 语句使用内存的大小，减少程序 OOM 风险 - - 支持在 CRUD 操作中使用隐式的行 ID - - 提升点查性能 -- Server - - 支持 Proxy Protocol - - 添加大量监控项, 优化日志 - - 支持配置文件的合法性检测 - - 支持 HTTP API 获取 TiDB 参数信息 - - 使用 Batch 方式 Resolve Lock，提升垃圾回收速度 - - 支持多线程垃圾回收 - - 支持 TLS -- 兼容性 - - 支持更多 MySQL 语法 - - 支持配置文件修改 `lower_case_table_names` 系统变量，用于支持 OGG 数据同步工具 - - 提升对 Navicat 的兼容性 - - 在 `Information_Schema` 中支持显示建表时间 - - 修复部分函数/表达式返回类型和 MySQL 不同的问题 - - 提升对 JDBC 兼容性 - - 支持更多的 `SQL_MODE` -- DDL - - 优化 `Add Index` 的执行速度，部分场景下速度大幅度提升 - - `Add Index` 操作变更为低优先级，降低对线上业务影响 - - `Admin Show DDL Jobs` 输出更详细的 DDL 任务状态信息 - - 支持 `Admin Show DDL Job Queries JobID` 查询当前正在运行的 DDL 任务的原始语句 - - 支持 `Admin Recover Index` 命令，用于灾难恢复情况下修复索引数据 - - 支持通过 `Alter` 语句修改 Table Options - -## PD - -- 增加 `Region Merge` 支持，合并数据删除后产生的空 Region [experimental] -- 增加 `Raft Learner` 支持 [experimental] -- 调度器优化 - - 调度器适应不同的 Region size - - 提升 TiKV 宕机时数据恢复的优先级和恢复速度 - - 提升下线 TiKV 节点搬迁数据的速度 - - 优化 TiKV 节点空间不足时的调度策略，尽可能防止空间不足时磁盘被写满 - - 提升 balance-leader scheduler 的调度效率 - - 减少 balance-region scheduler 调度开销 - - 优化 hot-region scheduler 的执行效率 -- 运维接口及配置 - - 增加 TLS 支持 - - 支持设置 PD leader 优先级 - - 支持基于 label 配置属性 - - 支持配置特定 label 的节点不调度 Region leader - - 支持手动 Split Region，可用于处理单 Region 热点的问题 - - 支持打散指定 Region，用于某些情况下手动调整热点 Region 分布 - - 增加配置参数检查规则，完善配置项的合法性较验 -- 调试接口 - - 增加 `Drop Region` 调试接口 - - 增加枚举各个 PD health 状态的接口 -- 统计相关 - - 添加异常 Region 的统计 - - 添加 Region 隔离级别的统计 - - 添加调度相关 metrics -- 性能优化 - - PD leader 尽量与 etcd leader 保持同步，提升写入性能 - - 优化 Region heartbeat 性能，现可支持超过 100 万 Region - -## TiKV - -- 功能 - - 保护关键配置，防止错误修改 - - 支持 `Region Merge` [experimental] - - 添加 `Raw DeleteRange` API - - 添加 `GetMetric` API - - 添加 `Raw Batch Put`，`Raw Batch Get`，`Raw Batch Delete` 和 `Raw Batch Scan` - - 给 Raw KV API 增加 Column Family 参数，能对特定 Column Family 进行操作 - - Coprocessor 支持 streaming 模式，支持 streaming 聚合 - - 支持配置 Coprocessor 请求的超时时间 - - 心跳包携带时间戳 - - 支持在线修改 RocksDB 的一些参数，包括 `block-cache-size` 大小等 - - 支持配置 Coprocessor 遇到某些错误时的行为 - - 支持以导数据模式启动，减少导数据过程中的写放大 - - 支持手动对 region 进行对半 split - - 完善数据修复工具 tikv-ctl - - Coprocessor 返回更多的统计信息，以便指导 TiDB 的行为 - - 支持 ImportSST API，可以用于 SST 文件导入 [experimental] - - 新增 TiKV Importer 二进制，与 TiDB Lightning 集成用于快速导入数据 [experimental] -- 性能 - - 使用 ReadPool 优化读性能，`raw_get/get/batch_get` 提升 30% - - 提升 metrics 的性能 - - Raft snapshot 处理完之后立即通知 PD，加快调度速度 - - 解决 RocksDB 刷盘导致性能抖动问题 - - 提升在数据删除之后的空间回收 - - 加速启动过程中的垃圾清理过程 - - 使用 `DeleteFilesInRanges` 减少副本迁移时 I/O 开销 -- 稳定性 - - 解决在 PD leader 发送切换的情况下 gRPC call 不返回问题 - - 解决由于 snapshot 导致下线节点慢的问题 - - 限制搬移副本临时占用的空间大小 - - 如果有 Region 长时间没有 Leader，进行上报 - - 根据 compaction 事件及时更新统计的 Region size - - 限制单次 scan lock 请求的扫描的数据量，防止超时 - - 限制接收 snapshot 过程中的内存占用，防止 OOM - - 提升 CI test 的速度 - - 解决由于 snapshot 太多导致的 OOM 问题 - - 配置 gRPC 的 `keepalive` 参数 - - 修复 Region 增多容易 OOM 的问题 - -## TiSpark - -TiSpark 使用独立的版本号，现为 1.0 GA。TiSpark 1.0 版本组件提供了针对 TiDB 上的数据使用 Apache Spark 进行分布式计算的能力。 - -- 提供了针对 TiKV 读取的 gRPC 通信框架 -- 提供了对 TiKV 组件数据的和通信协议部分的编码解码 -- 提供了计算下推功能，包含： - - 聚合下推 - - 谓词下推 - - TopN 下推 - - Limit 下推 -- 提供了索引相关的支持 - - 谓词转化聚簇索引范围 - - 谓词转化次级索引 - - Index Only 查询优化 - - 运行时索引退化扫表优化 -- 提供了基于代价的优化 - - 统计信息支持 - - 索引选择 - - 广播表代价估算 -- 多种 Spark Interface 的支持 - - Spark Shell 支持 - - ThriftServer/JDBC 支持 - - Spark-SQL 交互支持 - - PySpark Shell 支持 - - SparkR 支持 diff --git a/v2.1/releases/2.1.1.md b/v2.1/releases/2.1.1.md deleted file mode 100644 index 77e5b53f1155..000000000000 --- a/v2.1/releases/2.1.1.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: TiDB 2.1.1 Release Notes -category: Releases ---- - -# TiDB 2.1.1 Release Notes - -2018 年 12 月 12 日，TiDB 发布 2.1.1 版。相比 2.1.0 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复时间为负值时的四舍五入错误 [#8574](https://github.com/pingcap/tidb/pull/8574) - - 修复 `uncompress` 函数未检查数据长度的问题 [#8606](https://github.com/pingcap/tidb/pull/8606) - - 在执行 `execute` 命令后重置 `prepare` 语句绑定的变量 [#8652](https://github.com/pingcap/tidb/pull/8652) - - 支持对分区表自动收集统计信息 [#8649](https://github.com/pingcap/tidb/pull/8649) - - 修复在下推 `abs` 函数时设置错误的整数类型 [#8628](https://github.com/pingcap/tidb/pull/8628) - - 修复 JSON 列的数据竞争问题 [#8660](https://github.com/pingcap/tidb/pull/8660) -+ Server - - 修复在 PD 故障时获取错误 TSO 的问题 [#8567](https://github.com/pingcap/tidb/pull/8567) - - 修复不规范的语句导致启动失败的问题 [#8576](https://github.com/pingcap/tidb/pull/8576) - - 修复在事务重试时使用了错误的参数 [#8638](https://github.com/pingcap/tidb/pull/8638) -+ DDL - - 将表的默认字符集和排序规则改为 `utf8mb4` 和 `utf8mb4_bin` [#8590](https://github.com/pingcap/tidb/pull/8590) - - 增加变量 `ddl_reorg_batch_size` 来控制添加索引的速度 [#8614](https://github.com/pingcap/tidb/pull/8614) - - DDL 中的 character set 和 collation 选项内容不再大小写敏感 [#8611](https://github.com/pingcap/tidb/pull/8611) - - 修复对于生成列添加索引的问题 [#8655](https://github.com/pingcap/tidb/pull/8655) - -## PD - -- 修复一些配置项无法在配置文件中设置为 `0` 的问题 [#1334](https://github.com/pingcap/pd/pull/1334) -- 启动时检查未定义的配置 [#1362](https://github.com/pingcap/pd/pull/1362) -- 避免 transfer leader 至新创建的 Peer，优化可能产生的延迟增加问题 [#1339](https://github.com/pingcap/pd/pull/1339) -- 修复 RaftCluster 在退出时可能的死锁问题 [#1370](https://github.com/pingcap/pd/pull/1370) - -## TiKV - -- 避免 transfer leader 至新创建的 Peer，优化可能产生的延迟增加问题 [#3878](https://github.com/tikv/tikv/pull/3878) - -## Tools - -+ Lightning - - 优化对导入表的 `analyze` 机制，提升了导入速度 - - 支持 checkpoint 信息储存在本地文件 -+ TiDB Binlog - - 修复 pb files 输出 bug，表只有主键列则无法产生 pb event diff --git a/v2.1/releases/2.1.10.md b/v2.1/releases/2.1.10.md deleted file mode 100644 index 907002e6486e..000000000000 --- a/v2.1/releases/2.1.10.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiDB 2.1.10 Release Notes -category: Releases ---- - -# TiDB 2.1.10 Release Notes - -发版日期：2019 年 5 月 22 日 - -TiDB 版本：2.1.10 - -TiDB Ansible 版本：2.1.10 - -## TiDB - -- 修复在使用 `tidb_snapshot` 读取历史数据的时候，某些异常情况导致的表结构不正确 [#10359](https://github.com/pingcap/tidb/pull/10359) -- 修复 `NOT` 函数在某些情况下导致的读取结果错误的问题 [#10363](https://github.com/pingcap/tidb/pull/10363) -- 修复 `Generated Column` 在 `Replace` 或者 `Insert on duplicate update` 语句中的错误行为 [#10385](https://github.com/pingcap/tidb/pull/10385) -- 修复 `BETWEEN` 函数在 `DATE`/`DATETIME` 类型比较的一个 bug [#10407](https://github.com/pingcap/tidb/pull/10407) -- 修复使用 `SLOW_QUERY` 表查询慢日志时，单行慢日志长度过长导致的报错 [#10412](https://github.com/pingcap/tidb/pull/10412) -- 修复某些情况下 `DATETIME` 和 `INTERVAL` 相加的结果跟 MySQL 不一致的问题 [#10416](https://github.com/pingcap/tidb/pull/10416)，[#10418](https://github.com/pingcap/tidb/pull/10418) -- 增加闰年二月的非法时间的检查 [#10417](https://github.com/pingcap/tidb/pull/10417) -- 内部的初始化操作限制只在 DDL Owner 中执行，避免了初始化集群的时候出现的大量冲突报错 [#10426](https://github.com/pingcap/tidb/pull/10426) -- 修复 `DESC` 在输出时间戳列的默认值为 `default current_timestamp on update current_timestamp` 时跟 MySQL 不兼容的问题 [#10337](https://github.com/pingcap/tidb/issues/10337) -- 修复 `Update` 语句中权限检查出错的问题 [#10439](https://github.com/pingcap/tidb/pull/10439) -- 修复 `CHAR` 类型的列在某些情况下 `RANGE` 计算错误导致的错误结果的问题 [#10455](https://github.com/pingcap/tidb/pull/10455) -- 避免 `ALTER SHARD_ROW_ID_BITS` 缩小 shard bits 位数在极低概率下，可能导致的数据错误 [#9868](https://github.com/pingcap/tidb/pull/9868) -- 修复 `ORDER BY RAND()` 不返回随机数字的问题 [#10064](https://github.com/pingcap/tidb/pull/10064) -- 禁止 `ALTER` 语句修改 DECIMAL 的精度 [#10458](https://github.com/pingcap/tidb/pull/10458) -- 修复 `TIME_FORMAT` 函数与 MySQL 的兼容问题 [#10474](https://github.com/pingcap/tidb/pull/10474) -- 检查 `PERIOD_ADD` 中参数的合法性 [#10430](https://github.com/pingcap/tidb/pull/10430) -- 修复非法的 `YEAR` 字符串在 TiDB 中的表现跟 MySQL 不兼容的问题 [#10493](https://github.com/pingcap/tidb/pull/10493) -- 支持 `ALTER DATABASE` 语法 [#10503](https://github.com/pingcap/tidb/pull/10503) -- 修复 `SLOW_QUERY` 内存表在慢语句没有 `;` 的情况下报错的问题 [#10536](https://github.com/pingcap/tidb/pull/10536) -- 修复某些情况下 `Partitioned Table` 的表 `Add index` 操作没有办法取消的问题 [#10533](https://github.com/pingcap/tidb/pull/10533) -- 修复在某些情况下无法抓住内存使用太多导致 OOM 的问题 [#10545](https://github.com/pingcap/tidb/pull/10545) -- 增强 DDL 操作改写表元信息的安全性 [#10547](https://github.com/pingcap/tidb/pull/10547) - -## PD - -- 修复 Leader 优先级不生效的问题 [#1533](https://github.com/pingcap/pd/pull/1533) - -## TiKV - -- 拒绝在最近发生过成员变更的 Region 上执行 transfer leader，防止迁移失败 [#4684](https://github.com/tikv/tikv/pull/4684) -- Coprocessor metrics 上添加 priority 标签 [#4643](https://github.com/tikv/tikv/pull/4643) -- 修复 transfer leader 中可能发生的脏读问题 [#4724](https://github.com/tikv/tikv/pull/4724) -- 修复某些情况下 `CommitMerge` 导致 TiKV 不能重启的问题 [#4615](https://github.com/tikv/tikv/pull/4615) -- 修复 unknown 的日志 [#4730](https://github.com/tikv/tikv/pull/4730) - -## Tools - -- TiDB Lightning - - 新增 TiDB Lightning 发送数据到 importer 失败时进行重试 [#176](https://github.com/pingcap/tidb-lightning/pull/176) -- TiDB Binlog - - 优化 Pump storage 组件 log，以利于排查问题 [#607](https://github.com/pingcap/tidb-binlog/pull/607) - -## TiDB Ansible - -- 更新 TiDB Lightning 配置文件，新增 `tidb_lightning_ctl` 脚本 [#d3a4a368](https://github.com/pingcap/tidb-ansible/commit/d3a4a368810a421c49980899a286cf010569b4c7) diff --git a/v2.1/releases/2.1.11.md b/v2.1/releases/2.1.11.md deleted file mode 100644 index 46abfc3b9d69..000000000000 --- a/v2.1/releases/2.1.11.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: TiDB 2.1.11 Release Notes -category: Releases ---- - -# TiDB 2.1.11 Release Notes - -发版日期：2019 年 6 月 03 日 - -TiDB 版本：2.1.11 - -TiDB Ansible 版本：2.1.11 - -## TiDB - -- 修复 delete 多表 join 的结果时使用错误 schema 的问题 [#10595](https://github.com/pingcap/tidb/pull/10595) -- 修复 `CONVERT()` 函数返回错误的字段类型的问题 [#10263](https://github.com/pingcap/tidb/pull/10263) -- 更新统计信息时合并不重叠的反馈信息 [#10569](https://github.com/pingcap/tidb/pull/10569) -- 修复 `unix_timestamp()-unix_timestamp(now())` 计算错误的问题 [#10491](https://github.com/pingcap/tidb/pull/10491) -- 修复 `period_diff` 与 MySQL 8.0 不兼容的问题 [#10501](https://github.com/pingcap/tidb/pull/10501) -- 收集统计信息的时候，忽略 `Virtual Column`，避免异常报错 [#10628](https://github.com/pingcap/tidb/pull/10628) -- 支持 `SHOW OPEN TABLES` 语句 [#10374](https://github.com/pingcap/tidb/pull/10374) -- 修复某些情况下导致的 goroutine 泄露问题 [#10656](https://github.com/pingcap/tidb/pull/10656) -- 修复某些情况下设置 `tidb_snapshot` 变量时间格式解析出错的问题 [#10637](https://github.com/pingcap/tidb/pull/10637) - -## PD - -- 修复因为 `balance-region` 可能会导致热点 Region 没有机会调度的问题 [#1551](https://github.com/pingcap/pd/pull/1551) -- 将热点相关调度的优先级改为高优先级 [#1551](https://github.com/pingcap/pd/pull/1551) -- 新增配置项 `hot-region-schedule-limit` 控制同时进行热点调度任务的数量及新增 `hot-region-cache-hits-threshold` 控制判断是否为热点 Region [#1551](https://github.com/pingcap/pd/pull/1551) - -## TiKV - -- 修复在仅有一个 leader，learner 时，learner 读到空 index 的问题 [#4751](https://github.com/tikv/tikv/pull/4751) -- 将 `ScanLock` 和 `ResolveLock` 放在高优先级线程池中处理，减少对普通优先级命令的影响 [#4791](https://github.com/tikv/tikv/pull/4791) -- 同步所有收到的 snapshot 的文件 [#4811](https://github.com/tikv/tikv/pull/4811) - -## Tools - -- TiDB Binlog - - 新增 GC 删数据限速功能，避免因为删除数据导致 QPS 降低的问题 [#620](https://github.com/pingcap/tidb-binlog/pull/620) - -## TiDB Ansible - -- 新增 Drainer 参数 [#760](https://github.com/pingcap/tidb-ansible/pull/760) diff --git a/v2.1/releases/2.1.12.md b/v2.1/releases/2.1.12.md deleted file mode 100644 index 4461812971e9..000000000000 --- a/v2.1/releases/2.1.12.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: TiDB 2.1.12 Release Notes -category: Releases ---- - -# TiDB 2.1.12 Release Notes - -发版日期：2019 年 6 月 13 日 - -TiDB 版本：2.1.12 - -TiDB Ansible 版本：2.1.12 - -## TiDB - -- 修复在使用 feedback 时由于类型不匹配导致进程 panic 的问题 [#10755](https://github.com/pingcap/tidb/pull/10755) -- 修复某些情况下改变字符集导致 BLOB 类型变成 TEXT 类型的问题 [#10745](https://github.com/pingcap/tidb/pull/10745) -- 修复某些情况下在事务中的 `GRANT` 操作误报 "Duplicate Entry" 错误的问题 [#10739](https://github.com/pingcap/tidb/pull/10739) -- 提升以下功能跟 MySQL 的兼容性 - - `DAYNAME` 函数 [#10732](https://github.com/pingcap/tidb/pull/10732) - - `MONTHNAME` 函数 [#10733](https://github.com/pingcap/tidb/pull/10733) - - `EXTRACT` 函数在处理 `MONTH` 的时候支持零值 [#10702](https://github.com/pingcap/tidb/pull/10702) - - `DECIMAL` 类型转换成 `TIMESTAMP` 或者 `DATETIME` 类型 [#10734](https://github.com/pingcap/tidb/pull/10734) -- 修改表的字符集时，同步修改列的字符集 [#10714](https://github.com/pingcap/tidb/pull/10714) -- 修复某些情况下 `DECIMAL` 转换成浮点数的溢出问题 [#10730](https://github.com/pingcap/tidb/pull/10730) -- 修复 TiDB 跟 TiKV 在 gRPC 最大封包设置不一致导致的某些超大封包报 "grpc: received message larger than max" 错误的问题 [#10710](https://github.com/pingcap/tidb/pull/10710) -- 修复某些情况下 `ORDER BY` 没有过滤 NULL 值导致的 panic 问题 [#10488](https://github.com/pingcap/tidb/pull/10488) -- 修复 `UUID` 函数的返回值，在多机器情况可能出现重复的问题 [#10711](https://github.com/pingcap/tidb/pull/10711) -- `CAST(-num as datetime)` 的返回值由错误变更为 NULL 值 [#10703](https://github.com/pingcap/tidb/pull/10703) -- 修复某些情况下 unsigned 列直方图遇到 signed 越界的问题 [#10695](https://github.com/pingcap/tidb/pull/10695) -- 修复统计信息的 feedback 遇到 bigint unsigned 主键时处理不正确导致读数据时报错的问题 [#10307](https://github.com/pingcap/tidb/pull/10307) -- 修复分区表某些情况下 `Show Create Table` 结果显示不正确的问题 [#10690](https://github.com/pingcap/tidb/pull/10690) -- 修复在某些关联子查询上聚合函数 `GROUP_CONCAT` 计算不正确的问题 [#10670](https://github.com/pingcap/tidb/pull/10670) -- 修复某些情况下 slow query 内存表在解析慢日志的时候导致的显示结果错乱的问题 [#10776](https://github.com/pingcap/tidb/pull/10776) - -## PD - -- 修复极端情况下 etcd Leader 选举阻塞的问题 [#1576](https://github.com/pingcap/pd/pull/1576) - -## TiKV - -- 修复极端条件下 Leader 迁移过程中 Region 不可用的问题 [#4799](https://github.com/tikv/tikv/pull/4734) -- 修复在机器异常掉电时由于接收 snapshot 未及时将数据刷新到磁盘导致丢数据的问题 [#4850](https://github.com/tikv/tikv/pull/4850) diff --git a/v2.1/releases/2.1.13.md b/v2.1/releases/2.1.13.md deleted file mode 100644 index 781c56bb8cc2..000000000000 --- a/v2.1/releases/2.1.13.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.13 Release Notes -category: Releases ---- - -# TiDB 2.1.13 Release Notes - -发版日期：2019 年 6 月 21 日 - -TiDB 版本：2.1.13 - -TiDB Ansible 版本：2.1.13 - -## TiDB - -- 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 [#10788](https://github.com/pingcap/tidb/pull/10788) -- 优化无效 DDL 元信息存活时间，缩短集群升级后恢复 DDL 操作正常执行所需的时间 [#10789](https://github.com/pingcap/tidb/pull/10789) -- 修复因持有 `execdetails.ExecDetails` 指针时 Coprocessor 的资源无法快速释放导致的在大并发场景下 OOM 的问题 [#10833](https://github.com/pingcap/tidb/pull/10833) -- 新增 `update-stats`配置项，控制是否更新统计信息 [#10772](https://github.com/pingcap/tidb/pull/10772) -- 新增 3 个 TiDB 特有语法，支持预先切分 Region，解决热点问题： - - 新增 Table Option `PRE_SPLIT_REGIONS` 选项 [#10863](https://github.com/pingcap/tidb/pull/10863) - - 新增 `SPLIT TABLE table_name INDEX index_name` 语法 [#10865](https://github.com/pingcap/tidb/pull/10865) - - 新增 `SPLIT TABLE [table_name] BETWEEN (min_value...) AND (max_value...) REGIONS [region_num]` 语法 [#10882](https://github.com/pingcap/tidb/pull/10882) -- 修复某些情况下 `KILL` 语句导致的 panic 问题 [#10879](https://github.com/pingcap/tidb/pull/10879) -- 增强 `ADD_DATE` 在某些情况下跟 MySQL 的兼容性 [#10718](https://github.com/pingcap/tidb/pull/10718) -- 修复 index join 中内表过滤条件在某些情况下的选择率估计错误的问题 [#10856](https://github.com/pingcap/tidb/pull/10856) - -## TiKV - -- 修复因迭代器未检查状态导致系统生成残缺 snapshot 的问题 [#4940](https://github.com/tikv/tikv/pull/4940) -- 新增检查 `block-size` 配置的有效性功能 [#4930](https://github.com/tikv/tikv/pull/4930) - -## Tools - -TiDB Binlog - -- 修复 Pump 因写入失败时未检查返回值导致偏移量错误问题 [#640](https://github.com/pingcap/tidb-binlog/pull/640) -- Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 [#634](https://github.com/pingcap/tidb-binlog/pull/634) diff --git a/v2.1/releases/2.1.14.md b/v2.1/releases/2.1.14.md deleted file mode 100644 index 068864c31bc5..000000000000 --- a/v2.1/releases/2.1.14.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 2.1.14 Release Notes -category: Releases ---- - -# TiDB 2.1.14 Release Notes - -发版日期：2019 年 7 月 4 日 - -TiDB 版本：2.1.14 - -TiDB Ansible 版本：2.1.14 - -## TiDB - -- 修复某些情况下列裁剪导致查询结果不正确的问题 [#11019](https://github.com/pingcap/tidb/pull/11019) -- 修复 `show processlist` 中 `db` 和 `info` 列信息显示有误的问题 [#11000](https://github.com/pingcap/tidb/pull/11000) -- 修复 `MAX_EXECUTION_TIME` 作为 SQL hint 和全局变量在某些情况下不生效的问题 [#10999](https://github.com/pingcap/tidb/pull/10999) -- 支持根据负载情况自动调整 Auto ID 分配的步长 [#10997](https://github.com/pingcap/tidb/pull/10997) -- 修复 SQL 查询结束时 `MemTracker` 统计的 DistSQL 内存信息未正确清理的问题 [#10971](https://github.com/pingcap/tidb/pull/10971) -- `information_schema.processlist` 表中新增 `MEM` 列用于描述 Query 的内存使用情况 [#10896](https://github.com/pingcap/tidb/pull/10896) -- 新增全局系统变量 `max_execution_time`，用于控制查询的最大执行时间 [10940](https://github.com/pingcap/tidb/pull/10940) -- 修复使用未支持的聚合函数导致 TiDB panic 的问题 [#10911](https://github.com/pingcap/tidb/pull/10911) -- 新增 `load data` 语句失败后自动回滚最后一个事务功能 [#10862](https://github.com/pingcap/tidb/pull/10862) -- 修复 TiDB 超过内存配额的行为配置为 CANCEL 时，某些情况下 TiDB 返回结果不正确的问题 [#11016](https://github.com/pingcap/tidb/pull/11016) -- 禁用 `TRACE` 语句，避免 TiDB panic 问题 [#11039](https://github.com/pingcap/tidb/pull/11039) -- 新增 `mysql.expr_pushdown_blacklist` 系统表，控制动态开启/关闭 TiDB 下推到 Coprocessor 的函数 [#10998](https://github.com/pingcap/tidb/pull/10998) -- 修复 `ANY_VALUE` 函数在 `ONLY_FULL_GROUP_BY` 模式下不生效的问题 [#10994](https://github.com/pingcap/tidb/pull/10994) -- 修复给字符串类型的用户量赋值时因未深度拷贝导致赋值不正确的问题 [#11043](https://github.com/pingcap/tidb/pull/11043) - -## TiKV - -- 优化 Raftstore 消息处理中对空回调的处理流程，避免发送不必要的消息 [#4682](https://github.com/tikv/tikv/pull/4682) - -## PD - -- 调整当读取到无效配置项时日志信息输出的级别，由 Error 调整为 Warning [#1577](https://github.com/pingcap/pd/pull/1577) - -## Tools - -TiDB Binlog - -- Reparo - - 新增 `safe-mode` 配置项，开启后支持导入重复的数据 [#662](https://github.com/pingcap/tidb-binlog/pull/662) -- Pump - - 新增 `stop-write-at-available-space` 配置项，限制 Binlog 空间保留的大小 [#659](https://github.com/pingcap/tidb-binlog/pull/659) - - 修复 LevelDB L0 文件个数为 0 时 GC 有时不生效的问题 [#648](https://github.com/pingcap/tidb-binlog/pull/648) - - 优化 log 文件删除的算法，加速释放空间 [#648](https://github.com/pingcap/tidb-binlog/pull/648) -- Drainer - - 修复下游 TiDB BIT 类型列更新失败的问题 [#655](https://github.com/pingcap/tidb-binlog/pull/655) - -## TiDB Ansible - -- 新增 `ansible` 命令及其 `jmespath`、`Jinja2` 依赖包的预检查功能 [#807](https://github.com/pingcap/tidb-ansible/pull/807) -- Pump 新增 `stop-write-at-available-space` 参数，当磁盘剩余空间小于该值（默认 10 GiB）时，Pump 停止写入 Binlog [#807](https://github.com/pingcap/tidb-ansible/pull/807) diff --git a/v2.1/releases/2.1.15.md b/v2.1/releases/2.1.15.md deleted file mode 100644 index e1b2be612ef3..000000000000 --- a/v2.1/releases/2.1.15.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB 2.1.15 Release Notes -category: Releases ---- - -# TiDB 2.1.15 Release Notes - -发版日期：2019 年 7 月 18 日 - -TiDB 版本：2.1.15 - -TiDB Ansible 版本：2.1.15 - -## TiDB - -+ 修复 `DATE_ADD` 函数处理微秒时由于没有对齐导致结果不正确的问题 [#11289](https://github.com/pingcap/tidb/pull/11289) -+ 修复 `DELETE` 语句中，字符串列中的空值与 FLOAT/INT 做比较时会报错的问题 [#11279](https://github.com/pingcap/tidb/pull/11279) -+ 修复 `INSERT` 函数参数有 `NULL` 值时，未正确返回 `NULL` 值的问题 [#11249](https://github.com/pingcap/tidb/pull/11249) -+ 修复在非字符串类型且长度为 0 的列建立索引时出错的问题 [#11215](https://github.com/pingcap/tidb/pull/11215) -+ 新增 `SHOW TABLE REGIONS` 的语句，支持通过 SQL 查询表的 Region 分布情况 [#11238](https://github.com/pingcap/tidb/pull/11238) -+ 修复 `UPDATE … SELECT` 语句因 `SELECT` 子查询中使用投影消除来优化规则所导致的报错 [#11254](https://github.com/pingcap/tidb/pull/11254) -+ 新增 `ADMIN PLUGINS ENABLE/DISABLE` SQL 语句，支持通过 SQL 动态开启/关闭 Plugin [#11189](https://github.com/pingcap/tidb/pull/11189) -+ Audit Plugin 新增审记连接功能 [#11189](https://github.com/pingcap/tidb/pull/11189) -+ 修复点查时，某列被查询多次而且结果为 NULL 时会 Panic 的问题 [#11227](https://github.com/pingcap/tidb/pull/11227) -+ 新增 `tidb_scatter_region` 配置项，控制创建表时是否开启自己打散 Record Region [#11213](https://github.com/pingcap/tidb/pull/11213) -+ 修复 `RAND` 函数由于非线程安全的 `rand.Rand` 导致的 Data Race 问题 [#11170](https://github.com/pingcap/tidb/pull/11170) -+ 修复某些情况下整数和非整数比较结果不正确的问题 [#11191](https://github.com/pingcap/tidb/pull/11191) -+ 支持修改 Database/Table 的 Collate，条件限制为 Database/Table 字符集必须是 UTF8/UTF8MB4 [#11085](https://github.com/pingcap/tidb/pull/11085) -+ 修复 `CURRENT_TIMESTAMP` 作为列的默认值且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11087](https://github.com/pingcap/tidb/pull/11087) - -## TiKV - -+ 统一日志格式 [#5083](https://github.com/tikv/tikv/pull/5083) -+ 提高 region approximate size/key 在极端情况下的准确性，提升调度准确度 [#5085](https://github.com/tikv/tikv/pull/5085) - -## PD - -+ 统一日志格式 [#1625](https://github.com/pingcap/pd/pull/1625) - -## Tools - -TiDB Binlog - -+ 优化 Pump GC 策略，去掉了未被在线 drainer 消费到的 binlog 保证不清理的限制 [#663](https://github.com/pingcap/tidb-binlog/pull/663) - -TiDB Lightning - -+ 修复 SQL dump 指明的列名不是小写时导入错误的问题 [#210](https://github.com/pingcap/tidb-lightning/pull/210) - -## TiDB Ansible - -+ TiDB Dashboard 新增 `parse duration` 和 `compile duration` 监控项，用于监测 SQL 语句解析耗时和执行计划编译耗时 [#815](https://github.com/pingcap/tidb-ansible/pull/815) diff --git a/v2.1/releases/2.1.16.md b/v2.1/releases/2.1.16.md deleted file mode 100644 index f0db29e15a9f..000000000000 --- a/v2.1/releases/2.1.16.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: TiDB 2.1.16 Release Notes -category: Releases ---- - -# TiDB 2.1.16 Release Notes - -发版日期：2019 年 8 月 15 日 - -TiDB 版本：2.1.16 - -TiDB Ansible 版本：2.1.16 - -## TiDB - -+ SQL 优化器 - - 修复时间列上的等值条件 Row Count 估算不准确的问题 [#11526](https://github.com/pingcap/tidb/pull/11526) - - 修复 `TIDB_INLJ` Hint 不生效或者对非指定的表生效的问题 [#11361](https://github.com/pingcap/tidb/pull/11361) - - 将查询中的 NOT EXISTS 由 OUTER JOIN 实现方式改为 ANTI JOIN ，便于找到更优执行计划 [#11291](https://github.com/pingcap/tidb/pull/11291) - - 支持在 `SHOW` 语句中使用子查询，现在可以支持诸如 `SHOW COLUMNS FROM tbl WHERE FIELDS IN (SELECT 'a')` 的写法 [#11461](https://github.com/pingcap/tidb/pull/11461) - - 修复常量折叠优化导致 `SELECT … CASE WHEN … ELSE NULL ...` 查询结果不正确的问题 [#11441](https://github.com/pingcap/tidb/pull/11441) -+ SQL 执行引擎 - - 修复函数 DATE_ADD 在 INTERVAL 为负的情况下结果错误的问题 [#11616](https://github.com/pingcap/tidb/pull/11616) - - 修复 `DATE_ADD` 函数接受 `FLOAT`、`DOUBLE` 和 `DECIMAL` 类型的参数时，没有正确地进行类型转换而导致结果可能不正确的问题 [#11628](https://github.com/pingcap/tidb/pull/11628) - - 修复 CAST(JSON AS SIGNED) 出现 OVERFLOW 时错误信息不准确的问题 [#11562](https://github.com/pingcap/tidb/pull/11562) - - 修复在关闭 Executor 的过程中，子节点关闭返回错误时其他子节点未关闭的问题 [#11598](https://github.com/pingcap/tidb/pull/11598) - - 支持 SPLIT TABLE 语句返回切分成功的 REGION 数量，并且当部分 REGION SCATTER 在超时未完成调度时，不再返回错误，而是返回完成调度的比例 [#11487](https://github.com/pingcap/tidb/pull/11487) - - 修复 `REGEXP BINARY` 函数对大小写敏感，与 MySQL 不兼容的问题 [#11505](https://github.com/pingcap/tidb/pull/11505) - - 修复 DATE_ADD / DATE_SUB 结果中 YEAR 小于 0 或 大于 65535 时溢出导致结果没有正确返回 NULL 值的问题 [#11477](https://github.com/pingcap/tidb/pull/11477) - - 慢查询表中添加用于表示是否执行成功的 `Succ` 字段 [#11412](https://github.com/pingcap/tidb/pull/11421) - - 修复一条 SQL 语句在涉及当前时间计算时（例如 `CURRENT_TIMESTAMP` 或者 `NOW`），多次取当前时间值，结果与 MySQL不兼容的问题：现在同一条SQL语句中取当前时间时，均使用相同值 [#11392](https://github.com/pingcap/tidb/pull/11392) - - 修复 AUTO INCREMENT 列未处理 FLOAT / DOUBLE 的问题 [#11389](https://github.com/pingcap/tidb/pull/11389) - - 修复 `CONVERT_TZ` 函数在参数不合法时，没有正确返回 NULL 的问题 [#11357](https://github.com/pingcap/tidb/pull/11357) - - 修复 PARTITION BY LIST 报错的问题（仅添加语法支持，TiDB 执行时候会作为普通表创建并提供提示信息） [#11236](https://github.com/pingcap/tidb/pull/11236) - - 修复 `Mod(%)`、`Multiple(*)` 和 `Minus(-)` 返回结果为 0 时，在小数位数较多（例如 `select 0.000 % 0.11234500000000000000`）的情况下与 MySQL 位数不一致的问题 [#11353](https://github.com/pingcap/tidb/pull/11353) -+ Server - - 修复插件在 OnInit 回调中获取 Domain 为 NULL 的问题 [#11426](https://github.com/pingcap/tidb/pull/11426) - - 修复当 Schema 删除后，依然可以通过 HTTP 接口获取该 Schema 中表信息的问题 [#11586](https://github.com/pingcap/tidb/pull/11586) -+ DDL - - 禁止 DROP 自增列索引，修复因为 DROP 自增列上的索引导致自增列结果可能出错的问题 [#11402](https://github.com/pingcap/tidb/pull/11402) - - 修复列和表使用不同的 CHARSET 和 COLLATE 创建表和修改表时，列的字符集不正确的问题 [#11423](https://github.com/pingcap/tidb/pull/11423) - - 修复并行执行 “alter table ... set default...” 和其他修改此列信息的 DDL，可能导致此列的结构出错的问题 [#11374](https://github.com/pingcap/tidb/pull/11374) - - 修复当 Generated column A 依赖 Generated column B 时，使用 A 创建索引，数据回填失败的问题 [#11538](https://github.com/pingcap/tidb/pull/11538) - - 提升 ADMIN CHECK TABLE 的速度 [#11538](https://github.com/pingcap/tidb/pull/11676) - -## TiKV - -+ 访问正在关闭的 TiKV Region 时返回 Close 错误 [#4820](https://github.com/tikv/tikv/pull/4820) -+ 支持逆向 `raw_scan` 和逆向 `raw_batch_scan` 接口 [#5148](https://github.com/tikv/tikv/pull/5148) - -## Tools - -+ TiDB Binlog - - Drainer 增加 `ignore-txn-commit-ts` 配置项，用于跳过执行某些事务语句 [#697](https://github.com/pingcap/tidb-binlog/pull/697) - - 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#708](https://github.com/pingcap/tidb-binlog/pull/708) - - Drainer 增加 `node-id` 配置，用于指定固定逻辑 Drainer [#706](https://github.com/pingcap/tidb-binlog/pull/706) -+ TiDB Lightning - - 修复 2 个 checksum 同时运行的情况下，`tikv_gc_life_time` 没有正常修改回原本值的问题 [#224](https://github.com/pingcap/tidb-lightning/pull/224) - -## TiDB Ansible - -+ Spark 新增 log4j 日志配置 [#842](https://github.com/pingcap/tidb-ansible/pull/842) -+ 更新 tispark jar 包为 v2.1.2 版本 [#863](https://github.com/pingcap/tidb-ansible/pull/863) -+ 修复了 TiDB Binlog 使用 Kafka 或者 ZooKeeper 时导致生成的 Prometheus 配置文件格式错误的问题 [#845](https://github.com/pingcap/tidb-ansible/pull/845) -+ 修复执行 `rolling_update.yml` 操作时，切换 PD Leader 失效的 Bug [#888](https://github.com/pingcap/tidb-ansible/pull/888) -+ 优化滚动升级 PD 节点的逻辑，先升级 Follower 再升级 Leader，提高稳定性 [#895](https://github.com/pingcap/tidb-ansible/pull/895) diff --git a/v2.1/releases/2.1.17.md b/v2.1/releases/2.1.17.md deleted file mode 100644 index 5dd52c509daa..000000000000 --- a/v2.1/releases/2.1.17.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 2.1.17 Release Notes -category: Releases ---- - -# TiDB 2.1.17 Release Notes - -发版日期：2019 年 9 月 11 日 - -TiDB 版本：2.1.17 - -TiDB Ansible 版本：2.1.17 - -- 新特性 - - TiDB 的 `SHOW TABLE REGIONS` 语法新增 `WHERE` 条件子句 - - TiKV、PD 新增 `config-check` 功能，用于配置项检查 - - pd-ctl 新增 `remove-tomestone` 命令，支持清理 tombstone store 记录 - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 - -- 改进提升 - - PD 优化调度流程，支持主动下发调度 - - TiKV 优化启动流程，减少重启节点带来的抖动 - -- 行为变更 - - TiDB 慢日志中的 `start ts` 由最后一次重试的时间改为第一次执行的时间 - - TiDB 慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 - - TiDB 配置文件中添加 `split-region-max-num` 参数，用于调整 `SPLIT TABLE` 语法允许的最大 Region 数量，默认配置下，允许的数量由 1,000 增加至 10,000 - -## TiDB - -+ SQL 优化器 - - 修复 `EvalSubquery` 在构建 `Executor` 出现错误时，错误信息没有被正确返回的问题 [#11811](https://github.com/pingcap/tidb/pull/11811) - - 修复 Index Lookup Join 中，外表的行数大于一个 batch 时，查询的结果可能不正确的问题；扩大 Index Lookup Join 的作用范围：可以使用 `UnionScan` 作为 `IndexJoin` 的子节点 [#11843](https://github.com/pingcap/tidb/pull/11843) - - 针对统计信息的反馈过程可能产生失效 Key 的情况，`SHOW STAT_BUCKETS` 语句现在增加了失效 Key 的显示，例如：`invalid encoded key flag 252` [#12098](https://github.com/pingcap/tidb/pull/12098) -+ SQL 执行引擎 - - 修复 `CAST` 函数在进行数值类型转换时，首先将数值转换为 `UINT` 导致一些结果不正确的问题（例如，`select cast(13835058000000000000 as double)`）[#11712](https://github.com/pingcap/tidb/pull/11712) - - 修复 `DIV` 运算的被除数为 `DECIMAL` 类型且运算含有负数时，运算结果可能不正确的问题 [#11812](https://github.com/pingcap/tidb/pull/11812) - - 添加 `ConvertStrToIntStrict` 函数，修复执行 `SELECT`/`EXPLAIN` 语句时，一些字符串转换 `INT` 类型结果与 MySQL 不兼容的问题 [#11892](https://github.com/pingcap/tidb/pull/11892) - - 修复使用 `EXPLAIN ... FOR CONNECTION` 语法时，`stmtCtx` 没有正确设置导致 `Explain` 结果可能不正确的问题 [#11978](https://github.com/pingcap/tidb/pull/11978) - - 修复 `unaryMinus` 函数，当 Int 结果溢出时，返回结果类型没有为 Decimal 导致与 MySQL 不兼容的问题 [#11990](https://github.com/pingcap/tidb/pull/11990) - - 修复 `LOAD DATA` 语句执行时，计数顺序导致的 `last_insert_id()` 可能不正确的问题 [#11994](https://github.com/pingcap/tidb/pull/11994) - - 修复用户显式、隐式混合写入自增列数据时，`last_insert_id()` 可能不正确的问题 [#12001](https://github.com/pingcap/tidb/pull/12001) - - 修复一个 `JSON_UNQUOTE` 函数兼容性问题：只有在双引号（`"`）内的值需要 Unquote，例如 `SELECT JSON_UNQUOTE("\\\\")` 应当为 "`\\`"（不进行 Unquote）[#12096](https://github.com/pingcap/tidb/pull/12096) -+ Server - - TiDB 事务重试时，记录在慢日志中的 `start ts` 由最后一次重试的时间改为第一次执行的时间 [#11878](https://github.com/pingcap/tidb/pull/11878) - - 在 `LockResolver` 中添加事务的 Key 数量：当 Key 数量较少时，可以避免对整个 Region 的 Scan 操作，减小清锁的代价 [#11889](https://github.com/pingcap/tidb/pull/11889) - - 修复慢日志中，`succ` 字段值可能不正确的问题 [#11886](https://github.com/pingcap/tidb/pull/11886) - - 将慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 [#12063](https://github.com/pingcap/tidb/pull/12063) - - 修复 `Duration` 内容中包含 `-` 时（例如 `select time(‘--’)`），TiDB 解析为 EOF Error 导致连接断开的错误 [#11910](https://github.com/pingcap/tidb/pull/11910) - - 改进 `RegionCache`：当一个 Region 失效时，它将会更快地从 `RegionCache` 中移除，减少向该 Region 发送请求的个数 [#11931](https://github.com/pingcap/tidb/pull/11931) - - 修复 `oom-action = "cancel"` 时，当 `Insert Into … Select` 语句发生 OOM，OOM Panic 没有被正确处理而导致连接断开的问题 [#12126](https://github.com/pingcap/tidb/pull/12126) -+ DDL - - 为 `tikvSnapshot` 添加逆序扫描接口用于高效地查询 DDL History Job，使用该接口后 `ADMIN SHOW DDL JOBS` 的执行时间有明显降低 [#11789](https://github.com/pingcap/tidb/pull/11789) - - 改进 `CREATE TABLE ... PRE_SPLIT_REGION` 的语义：当指定 `PRE_SPLIT_REGION = N` 时，将预切分的 Region 个数由 2^(N-1) 改为 2^N [#11797](https://github.com/pingcap/tidb/pull/11797/files) - - 根据[线上负载与 Add Index 相互影响测试](https://pingcap.com/docs-cn/dev/benchmark/add-index-with-load)，调小 Add Index 后台工作线程的默认参数以避免对线上负载造成较大影响 [#11875](https://github.com/pingcap/tidb/pull/11875) - - 改进 `SPLIT TABLE` 语法的行为：当使用 `SPLIT TABLE ... REGIONS N` 对 Region 切分时，会生成 N 个数据 Region 和 1 个索引 Region [#11929](https://github.com/pingcap/tidb/pull/11929) - - 在配置文件中添加 `split-region-max-num` 参数，使得 `SPLIT TABLE` 语法允许的最大 Region 数量可调整，该参数默认值 `10000` [#12080](https://github.com/pingcap/tidb/pull/12080) - - 修复写 binlog 时，`CREATE TABLE` 语句中 `PRE_SPLIT_REGIONS` 部分没有被注释，导致语句不能被下游 MySQL 解析的问题 [#12121](https://github.com/pingcap/tidb/pull/12121) - - `SHOW TABLE … REGIONS` 和 `SHOW TABLE .. INDEX … REGIONS` 语法新增 `WHERE` 条件子句 [#12124](https://github.com/pingcap/tidb/pull/12124) -+ Monitor - - 增加监控指标 `connection_transient_failure_count`，用于统计 `tikvclient` 的 gRPC 连接错误数量 [#12092](https://github.com/pingcap/tidb/pull/12092) - -## TiKV - -- 解决某些情况下 Region 内 key 个数统计不准的问题 [#5415](https://github.com/tikv/tikv/pull/5415) -- TiKV 新增 `config-check` 选项，用于检查 TiKV 配置项是否合法 [#5391](https://github.com/tikv/tikv/pull/5391) -- 优化启动流程，减少重启节点带来的抖动 [#5277](https://github.com/tikv/tikv/pull/5277) -- 优化某些情况下解锁的流程，加速事务解锁 [#5339](https://github.com/tikv/tikv/pull/5339) -- 优化 `get_txn_commit_info` 的流程，加速事务提交 [#5062](https://github.com/tikv/tikv/pull/5062) -- 简化 Raft 相关的 log [#5425](https://github.com/tikv/tikv/pull/5425) -- 解决在某些情况下 TiKV 异常退出的问题 [#5441](https://github.com/tikv/tikv/pull/5441) - -## PD - -- PD 新增 `config-check` 选项，用于检查 PD 配置项是否合法 [#1725](https://github.com/pingcap/pd/pull/1725) -- pd-ctl 新增 `remove-tomestone` 命令，支持清理 tombstone store 记录 [#1705](https://github.com/pingcap/pd/pull/1705) -- 支持主动下发 Operator，加快调度速度 [#1686](https://github.com/pingcap/pd/pull/1686) - -## Tools - -+ TiDB Binlog - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 [#746](https://github.com/pingcap/tidb-binlog/pull/746) - - Drainer 优化内存使用，提升同步执行效率 [#735](https://github.com/pingcap/tidb-binlog/pull/735) - - Pump 修复有时候无法正常下线的 bug [#739](https://github.com/pingcap/tidb-binlog/pull/739) - - Pump 优化 LevelDB 处理逻辑，提升 GC 执行效率 [#720](https://github.com/pingcap/tidb-binlog/pull/720) - -+ TiDB Lightning - - 修复从 checkpoint 点重新导入可能会导致 tidb-lightning 崩溃的 bug [#239](https://github.com/pingcap/tidb-lightning/pull/239) - -## TiDB Ansible - -- 更新 Spark 版本为 2.4.3，同时更新 TiSpark 为兼容该 Spark 的 2.2.0 版本 [#914](https://github.com/pingcap/tidb-ansible/pull/914)，[#919](https://github.com/pingcap/tidb-ansible/pull/927) -- 修复了当远程机器密码过期时长时间连接等待的问题 [#937](https://github.com/pingcap/tidb-ansible/pull/937)，[#948](https://github.com/pingcap/tidb-ansible/pull/948) diff --git a/v2.1/releases/2.1.18.md b/v2.1/releases/2.1.18.md deleted file mode 100644 index 5d4903f0020a..000000000000 --- a/v2.1/releases/2.1.18.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: TiDB 2.1.18 Release Notes -category: Releases ---- - -# TiDB 2.1.18 Release Notes - -发版日期：2019 年 11 月 4 日 - -TiDB 版本：2.1.18 - -TiDB Ansible 版本：2.1.18 - -## TiDB - -+ SQL 优化器 - - 修复 Feedback 切分查询范围出错的问题 [#12172](https://github.com/pingcap/tidb/pull/12172) - - 修复点查中权限检查不正确的问题 [#12341](https://github.com/pingcap/tidb/pull/12341) - - 将 Limit 算子下推到 `IndexLookUpReader` 执行逻辑中，优化 `select ... limit ... offset ...` 的执行性能 [#12380](https://github.com/pingcap/tidb/pull/12380) - - 支持在 `ORDER BY`、`GROUP BY` 和 `LIMIT OFFSET` 中使用参数 [#12514](https://github.com/pingcap/tidb/pull/12514) - - 修复 partition 表上的 IndexJoin 返回错误结果的问题 [#12713](https://github.com/pingcap/tidb/pull/12713) - - 修复 TiDB 中 `str_to_date` 函数在日期字符串和格式化字符串不匹配的情况下，返回结果与 MySQL 不一致的问题 [#12757](https://github.com/pingcap/tidb/pull/12757) - - 修复当查询条件中包含 cast 函数时 outer join 被错误转化为 inner join 的问题 [#12791](https://github.com/pingcap/tidb/pull/12791) - - 修复 AntiSemiJoin 的 join 条件中错误的表达式传递 [#12800](https://github.com/pingcap/tidb/pull/12800) -+ SQL 执行引擎 - - 修复时间取整不正确的问题 (如 2019-09-11 11:17:47.999999666 应该被取整到 2019-09-11 11:17:48) [#12259](https://github.com/pingcap/tidb/pull/12259) - - 修复 `PREPARE` 语句类型没有记录在监控中的问题 [#12329](https://github.com/pingcap/tidb/pull/12329) - - 修复 `FROM_UNIXTIME` 在检查 NULL 值时 panic 的错误 [#12572](https://github.com/pingcap/tidb/pull/12572) - - 修复 `YEAR` 类型数据插入非法年份时，结果为 `NULL` 而不是 `0000` 的兼容性问题 [#12744](https://github.com/pingcap/tidb/pull/12744) - - 改进 AutoIncrement 列隐式分配时的行为，与 MySQL 自增锁的默认模式 (["consecutive" lock mode](https://dev.mysql.com/doc/refman/5.7/en/innodb-auto-increment-handling.html)) 保持一致：对于单行 Insert 语句的多个自增 AutoIncrement ID 的隐式分配，TiDB 保证分配值的连续性。该改进保证 JDBC `getGeneratedKeys()` 方法在任意场景下都能得到正确的结果。 [#12619](https://github.com/pingcap/tidb/pull/12619) - - 修复当 HashAgg 作为 Apply 子节点时查询 hang 住的问题 [#12769](https://github.com/pingcap/tidb/pull/12769) - - 修复逻辑表达式 AND / OR 在涉及类型转换时返回错误结果的问题 [#12813](https://github.com/pingcap/tidb/pull/12813) -+ Server - - 修复 `KILL TIDB QUERY` 语法对 `SLEEP()` 语句无效的问题 [#12159](https://github.com/pingcap/tidb/pull/12159) - - 修复 AUTO INCREMENT 分配 MAX int64 和 MAX uint64 没有报错的问题 [#12210](https://github.com/pingcap/tidb/pull/12210) - - 修复日志级别设置为 `ERROR` 时，慢日志不会被记录的问题 [#12373](https://github.com/pingcap/tidb/pull/12373) - - 将缓存 100 个 Schema 变更相关的表信息调整成 1024 个，且支持通过 `tidb_max_delta_schema_count` 系统变量修改 [#12515](https://github.com/pingcap/tidb/pull/12515) - - 将 SQL 的统计方式开始时间由“开始执行”改为“开始编译”，使得 SQL 性能统计更加准确 [#12638](https://github.com/pingcap/tidb/pull/12638) - - 在 TiDB 日志中添加 `set session autocommit` 的记录 [#12568](https://github.com/pingcap/tidb/pull/12568) - - 将 SQL 的开始时间记录在 `SessionVars` 中，避免计划执行时，该时间被重置 [#12676](https://github.com/pingcap/tidb/pull/12676) - - 在 `Order By`/`Group By`/`Limit Offset` 字句中支持 `?` 占位符 [#12514](https://github.com/pingcap/tidb/pull/12514) - - 慢日志中添加 `Prev_stmt` 字段，用于最后一条语句是 `COMMIT` 时输出前一条语句 [#12724](https://github.com/pingcap/tidb/pull/12724) - - 当一个显式提交的事务 `COMMIT` 时出错，在日志中记录 `COMMIT` 前一条语句 [#12747](https://github.com/pingcap/tidb/pull/12747) - - 优化在 TiDB Server 执行 SQL 时，对前一条语句的保存方式以提升性能 [#12751](https://github.com/pingcap/tidb/pull/12751) - - 修复 `skip-grant-table=true` 时，`FLUSH PRIVILEGES` 语句导致系统 Panic 的问题 [#12816](https://github.com/pingcap/tidb/pull/12816) - - 将 AutoID 的最小申请步长从 1000 增加为 30000，避免短时间大量写入时频繁请求 AutoID 造成性能瓶颈 [#12891](https://github.com/pingcap/tidb/pull/12891) - - 修复 Prepared 语句在 TiDB 发生 panic 时错误日志中未打印出错 SQL 的问题 [#12954](https://github.com/pingcap/tidb/pull/12954) - - 修复 COM_STMT_FETCH 慢日志时间记录和 MySQL 不一致问题 [#12953](https://github.com/pingcap/tidb/pull/12953) - - 当遇到写冲突时，在报错信息中添加错误码，以方便对冲突原因进行诊断 [#12878](https://github.com/pingcap/tidb/pull/12878) -+ DDL - - 为避免误操作，TiDB 默认不再允许删除列的 `AUTO INCREMENT` 属性，当确实需要删除时，请更改系统变量 `tidb_allow_remove_auto_inc`；相关文档请见：[TiDB 专用系统变量和语法](https://pingcap.com/docs-cn/v2.1/reference/configuration/tidb-server/tidb-specific-variables/) [#12146](https://github.com/pingcap/tidb/pull/12146) - - 支持 Create Table 语句中建唯一索引时带多个 Unique [#12469](https://github.com/pingcap/tidb/pull/12469) - - 修复 `CreateTable` 语句中指定外键约束时，外键表在没有指定 Database 时未能使用主表的 Database 导致报错的问题 [#12678](https://github.com/pingcap/tidb/pull/12678) - - 修复 `ADMIN CANCEL DDL JOBS` 时报 `invalid list index` 错的问题 [#12681](https://github.com/pingcap/tidb/pull/12681) -+ Monitor - - Backoff 监控添加类型，且补充之前没有统计到的 Backoff，比如 commit 时遇到的 Backoff [#12326](https://github.com/pingcap/tidb/pull/12326) - - 添加统计 Add Index 操作进度的监控 [#12389](https://github.com/pingcap/tidb/pull/12389) - -## PD - -- 修复 pd-ctl `--help` 命令输出内容 [#1772](https://github.com/pingcap/pd/pull/1772) - -## Tools - -+ TiDB Binlog - - 修复 `ALTER DATABASE` 相关 DDL 会导致 Drainer 异常退出的问题 [#770](https://github.com/pingcap/tidb-binlog/pull/770) - - 支持对 Commit binlog 查询事务状态信息，提升同步效率 [#761](https://github.com/pingcap/tidb-binlog/pull/761) - - 修复当 Drainer 的 `start_ts` 大于 Pump 中最大的 `commit_ts` 时候有可能引起 Pump panic 的问题 [#759](https://github.com/pingcap/tidb-binlog/pull/759) - -## TiDB Ansible - -- TiDB Binlog 增加 queue size 和 query histogram 监控项 [#952](https://github.com/pingcap/tidb-ansible/pull/952) -- 更新 TiDB 告警表达式 [#961](https://github.com/pingcap/tidb-ansible/pull/961) -- 新增配置文件检查功能，部署或者更新前会检查配置是否合理 [#973](https://github.com/pingcap/tidb-ansible/pull/973) -- TiDB 新增加索引速度监控项 [#987](https://github.com/pingcap/tidb-ansible/pull/987) -- 更新 TiDB Binlog 监控 Dashboard，兼容 4.6.3 版本的 Grafana [#993](https://github.com/pingcap/tidb-ansible/pull/993) diff --git a/v2.1/releases/2.1.19.md b/v2.1/releases/2.1.19.md deleted file mode 100644 index bafa841c7c20..000000000000 --- a/v2.1/releases/2.1.19.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 2.1.19 Release Notes -category: Releases ---- - -# TiDB 2.1.19 Release Notes - -发版日期：2019 年 12 月 27 日 - -TiDB 版本：2.1.19 - -TiDB Ansible 版本：2.1.19 - -## TiDB - -+ SQL 优化器 - - 优化 `select max(_tidb_rowid) from t` 的场景，避免全表扫 [#13294](https://github.com/pingcap/tidb/pull/13294) - - 修复当查询语句中赋予用户变量错误的值且将谓词下推后导致错误的输出结果 [#13230](https://github.com/pingcap/tidb/pull/13230) - - 修复更新统计信息时可能存在数据竞争，导致统计信息不准确的问题 [#13690](https://github.com/pingcap/tidb/pull/13690) - - 修复 `UPDATE` 语句中同时包含子查询和 stored generated column 时结果错误的问题；修复 `UPDATE` 语句中包含不同数据库的两个表名相同时，`UPDATE` 执行报错的问题 [#13357](https://github.com/pingcap/tidb/pull/13357) - - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14134](https://github.com/pingcap/tidb/pull/14134) - - 移除 `minAutoAnalyzeRatio` 约束使自动 `ANALYZE` 更及时 [#14013](https://github.com/pingcap/tidb/pull/14013) - - 当 `WHERE` 子句上有 `UNIQUE KEY` 的等值条件时，估算行数应该不大于 `1` [#13385](https://github.com/pingcap/tidb/pull/13385) -+ SQL 执行引擎 - - 修复 `ConvertJSONToInt` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#13036](https://github.com/pingcap/tidb/pull/13036) - - 修复查询中包含 `SLEEP` 函数时（例如 `select 1 from (select sleep(1)) t;)`），由于列裁剪导致查询中的 `sleep(1)` 失效的问题 [#13039](https://github.com/pingcap/tidb/pull/13039) - - 通过实现在 `INSERT ON DUPLICATE UPDATE` 语句中复用 `Chunk` 来降低内存开销 [#12999](https://github.com/pingcap/tidb/pull/12999) - - 给 `slow_query` 表添加事务相关的信息段 [#13129](https://github.com/pingcap/tidb/pull/13129)，如下： - - `Prewrite_time` - - `Commit_time` - - `Get_commit_ts_time` - - `Commit_backoff_time` - - `Backoff_types` - - `Resolve_lock_time` - - `Local_latch_wait_time` - - `Write_key` - - `Write_size` - - `Prewrite_region` - - `Txn_retry` - - 修复 `UPDATE` 语句中包含子查询时转换子查询出现的错误和当 `UPDATE` 的 `WHERE` 条件中包含子查询时更新失败的问题 [#13120](https://github.com/pingcap/tidb/pull/13120) - - 支持在分区表上执行 `ADMIN CHECK TABLE` [#13143](https://github.com/pingcap/tidb/pull/13143) - - 修复 `ON UPDATE CURRENT_TIMESTAMP` 作为列的属性且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#12462](https://github.com/pingcap/tidb/pull/12462) - - 修复在 `DROP/MODIFY/CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14162](https://github.com/pingcap/tidb/pull/14162) - - 修复 TiDB 开启 `Streaming` 后返回数据可能重复的问题 [#13255](https://github.com/pingcap/tidb/pull/13255) - - 修复夏令时导致的“无效时间格式”问题 [#13624](https://github.com/pingcap/tidb/pull/13624) - - 修复整型数据被转换为无符号 `Real`/`Decimal` 类型时，精度可能丢失的问题 [#13756](https://github.com/pingcap/tidb/pull/13756) - - 修复 `Quote` 函数处理 `null` 值时返回值类型出错的问题 [#13681](https://github.com/pingcap/tidb/pull/13681) - - 修复从字符串解析日期时，由于使用 `golang time.Local` 本地时区导致解析结果的时区不正确的问题 [#13792](https://github.com/pingcap/tidb/pull/13792) - - 修复 `builtinIntervalRealSig` 的实现中，由于 `binSearch` 方法不会返回 error，导致最终结果可能不正确的问题 [#13768](https://github.com/pingcap/tidb/pull/13768) - - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14009](https://github.com/pingcap/tidb/pull/14009) - - 修复 `sum(distinct)` 函数输出结果不正确的问题 [#13041](https://github.com/pingcap/tidb/pull/13041) - - 修复由于对 `jsonUnquoteFunction` 函数的返回类型长度赋值不正确的值，导致在 `union` 中同位置数据上进行 `cast` 转换时会截断数据的问题 [#13645](https://github.com/pingcap/tidb/pull/13645) - - 修复由于权限检查过于严格导致设置密码失败的问题 [#13805](https://github.com/pingcap/tidb/pull/13805) -+ Server - - 修复 `KILL CONNECTION` 可能出现 goroutine 泄漏的问题 [#13252](https://github.com/pingcap/tidb/pull/13252) - - 新增通过 HTTP API 的 `info/all` 接口获取所有 TiDB 节点的 binlog 状态功能 [#13188](https://github.com/pingcap/tidb/pull/13188) - - 修复在 Windows 上 build TiDB 项目失败的问题 [#13650](https://github.com/pingcap/tidb/pull/13650) - - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13904](https://github.com/pingcap/tidb/pull/13904) - - 修复通过 Go1.13 版本编译的二进制程序 `plugin` 不能正常运行的问题 [#13527](https://github.com/pingcap/tidb/pull/13527) -+ DDL - - 新增创建表时如果表包含 `COLLATE` 则列的 `COLLATE` 使用表的 `COLLATE` [#13190](https://github.com/pingcap/tidb/pull/13190) - - 新增创建表时限制索引名字的长度的功能 [#13311](https://github.com/pingcap/tidb/pull/13311) - - 修复 rename table 时未检查表名长度的问题 [#13345](https://github.com/pingcap/tidb/pull/13345) - - 新增 `BIT` 列的宽度范围检查的功能 [#13511](https://github.com/pingcap/tidb/pull/13511) - - 优化 `change/modify column` 的输出的错误信息，让人更容易理解 [#13798](https://github.com/pingcap/tidb/pull/13798) - - 修复执行 `drop column` 操作且下游 Drainer 还没有执行此 `drop column` 操作时，下游可能会收到不带此列的 DML 的问题 [#13974](https://github.com/pingcap/tidb/pull/13974) - -## TiKV - -+ Raftstore - - 修复 Region merge 和应用 Compact log 过程中系统若有重启，当重启时由于未正确设置 `is_merging` 的值导致系统 panic 的问题 [#5884](https://github.com/tikv/tikv/pull/5884) -+ Importer - - 取消 gRPC 的消息长度限制 [#5809](https://github.com/tikv/tikv/pull/5809) - -## PD - -- 提升获取 Region 列表的 HTTP API 性能 [#1988](https://github.com/pingcap/pd/pull/1988) -- 升级 etcd，修复 etcd PreVote 无法选出 leader 的问题（升级后无法降级） [#2052](https://github.com/pingcap/pd/pull/2052) - -## Tools - -+ TiDB Binlog - - 优化通过 binlogctl 输出的节点状态信息 [#777](https://github.com/pingcap/tidb-binlog/pull/777) - - 修复当 Drainer 过滤配置为 `nil` 时 panic 的问题 [#802](https://github.com/pingcap/tidb-binlog/pull/802) - - 优化 Pump 的 `Graceful` 退出方式 [#825](https://github.com/pingcap/tidb-binlog/pull/825) - - 新增 Pump 写 binlog 数据时更详细的监控指标 [#830](https://github.com/pingcap/tidb-binlog/pull/830) - - 优化 Drainer 在执行 DDL 后刷新表结构信息的逻辑 [#836](https://github.com/pingcap/tidb-binlog/pull/836) - - 修复 Pump 在没有收到 DDL 的 commit binlog 时该 binlog 被忽略的问题 [#855](https://github.com/pingcap/tidb-binlog/pull/855) - -## TiDB Ansible - -- TiDB 服务 `Uncommon Error OPM` 监控项更名为 `Write Binlog Error` 并增加对应的告警 [#1038](https://github.com/pingcap/tidb-ansible/pull/1038) -- 升级 TiSpark 版本为 2.1.8 [#1063](https://github.com/pingcap/tidb-ansible/pull/1063) diff --git a/v2.1/releases/2.1.2.md b/v2.1/releases/2.1.2.md deleted file mode 100644 index 532a6b0c2c57..000000000000 --- a/v2.1/releases/2.1.2.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.2 Release Notes -category: Releases ---- - -# TiDB 2.1.2 Release Notes - -2018 年 12 月 22 日，TiDB 发布 2.1.2 版，TiDB Ansible 相应发布 2.1.2 版本。该版本在 2.1.1 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 兼容 Kafka 版本的 TiDB Binlog [#8747](https://github.com/pingcap/tidb/pull/8747) -- 完善滚动升级下 TiDB 的退出机制 [#8707](https://github.com/pingcap/tidb/pull/8707) -- 修复在某些情况下为 generated column 增加索引 panic 的问题 [#8676](https://github.com/pingcap/tidb/pull/8676) -- 修复在某些情况下语句有 `TIDB_SMJ Hint` 的时候优化器无法找到正确执行计划的问题 [#8729](https://github.com/pingcap/tidb/pull/8729) -- 修复在某些情况下 `AntiSemiJoin` 返回错误结果的问题 [#8730](https://github.com/pingcap/tidb/pull/8730) -- 增强 `utf8` 字符集的有效字符检查 [#8754](https://github.com/pingcap/tidb/pull/8754) -- 修复事务中先写后读的情况下时间类型字段可能返回错误结果的问题 [#8746](https://github.com/pingcap/tidb/pull/8746) - -## PD - -- 修复 Region Merge 相关的 Region 信息更新问题 [#1377](https://github.com/pingcap/pd/pull/1377) - -## TiKV - -- 支持以日 (`d`) 为时间单位的配置格式，并解决配置兼容性问题 [#3931](https://github.com/tikv/tikv/pull/3931) -- 修复 Approximate Size Split 可能会 panic 的问题 [#3942](https://github.com/tikv/tikv/pull/3942) -- 修复两个 Region merge 相关问题 [#3822](https://github.com/tikv/tikv/pull/3822)，[#3873](https://github.com/tikv/tikv/pull/3873) - -## Tools - -+ TiDB Lightning - - 支持最小 TiDB 集群版本为 2.1.0 - - 修复解析包含 JSON 类型数据的文件内容出错 [#144](https://github.com/pingcap/tidb-tools/issues/144) - - 修复使用 checkpoint 重启后 `Too many open engines` 错误 -+ TiDB Binlog - - 消除了 Drainer 往 Kafka 写数据的一些瓶颈点 - - TiDB 支持写 [Kafka 版本的 TiDB Binlog](https://github.com/pingcap/docs-cn/blob/master/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md) diff --git a/v2.1/releases/2.1.3.md b/v2.1/releases/2.1.3.md deleted file mode 100644 index ece2ccd5cf96..000000000000 --- a/v2.1/releases/2.1.3.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: TiDB 2.1.3 Release Notes -category: Releases ---- - -# TiDB 2.1.3 Release Notes - -2019 年 01 月 28 日，TiDB 发布 2.1.3 版，TiDB Ansible 相应发布 2.1.3 版本。相比 2.1.2 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复某些情况下 Prepared Plan Cache panic 的问题 [#8826](https://github.com/pingcap/tidb/pull/8826) - - 修复在有前缀索引的某些情况下，Range 计算错误的问题 [#8851](https://github.com/pingcap/tidb/pull/8851) - - 当 `SQL_MODE` 不为 STRICT 时, `CAST(str AS TIME(N))` 在 `str` 为非法的 TIME 格式的字符串时返回 NULL [#8966](https://github.com/pingcap/tidb/pull/8966) - - 修复某些情况下 Generated Column 在 Update 中 Panic 的问题 [#8980](https://github.com/pingcap/tidb/pull/8980) - - 修复统计信息直方图某些情况下上界溢出的问题 [#8989](https://github.com/pingcap/tidb/pull/8989) - - 支持对 `_tidb_rowid` 构造查询的 Range，避免全表扫，减轻集群压力 [#9059](https://github.com/pingcap/tidb/pull/9059) - - `CAST(AS TIME)` 在精度太大的情况下返回一个错误 [#9058](https://github.com/pingcap/tidb/pull/9058) - - 允许把 `Sort Merge Join` 用于笛卡尔积 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 修复统计信息的 worker 在某些情况下 panic 之后无法恢复的问题 [#9085](https://github.com/pingcap/tidb/pull/9085) - - 修复某些情况下 `Sort Merge Join` 结果不正确的问题 [#9046](https://github.com/pingcap/tidb/pull/9046) - - 支持在 `CASE` 子句返回 JSON 类型 [#8355](https://github.com/pingcap/tidb/pull/8355) -+ Server - - 当语句中有非 TiDB hint 的注释时返回警告，而不是错误 [#8766](https://github.com/pingcap/tidb/pull/8766) - - 验证设置的 TIMEZONE 的合法性 [#8879](https://github.com/pingcap/tidb/pull/8879) - - 优化 Metrics 项 `QueryDurationHistogram`，展示更多语句的类型 [#8875](https://github.com/pingcap/tidb/pull/8875) - - 修复 bigint 某些情况下下界溢出的问题 [#8544](https://github.com/pingcap/tidb/pull/8544) - - 支持 `ALLOW_INVALID_DATES` SQL mode [#9110](https://github.com/pingcap/tidb/pull/9110) -+ DDL - - 修复一个 RENAME TABLE 的兼容性问题，保持行为跟 MySQL 一致 [#8808](https://github.com/pingcap/tidb/pull/8808) - - 支持 `ADD INDEX` 的并发修改即时生效 [#8786](https://github.com/pingcap/tidb/pull/8786) - - 修复在 `ADD COLUMN` 的过程中，某些情况 Update 语句 panic 的问题 [#8906](https://github.com/pingcap/tidb/pull/8906) - - 修复某些情况下并发创建 Table Partition 的问题 [#8902](https://github.com/pingcap/tidb/pull/8902) - - 支持把 `utf8` 字符集转换为 `utf8mb4` 字符集 [#8951](https://github.com/pingcap/tidb/pull/8951) [#9152](https://github.com/pingcap/tidb/pull/9152) - - 处理 Shard Bits 溢出的问题 [#8976](https://github.com/pingcap/tidb/pull/8976) - - 支持 `SHOW CREATE TABLE` 输出列的字符集 [#9053](https://github.com/pingcap/tidb/pull/9053) - - 修复 varchar 最大支持字符数在 `utf8mb4` 下限制的问题 [#8818](https://github.com/pingcap/tidb/pull/8818) - - 支持 `ALTER TABLE TRUNCATE TABLE PARTITION` [#9093](https://github.com/pingcap/tidb/pull/9093) - - 修复创建表的时候缺省字符集推算的问题 [#9147](https://github.com/pingcap/tidb/pull/9147) - -## PD - -- 修复 Leader 选举相关的 Watch 问题 [#1396](https://github.com/pingcap/pd/pull/1396) - -## TiKV - -- 支持了使用 HTTP 方式获取监控信息 [#3855](https://github.com/tikv/tikv/pull/3855) -- 修复 `data_format` 遇到 NULL 时的问题 [#4075](https://github.com/tikv/tikv/pull/4075) -- 添加验证 Scan 请求的边界合法性 [#4124](https://github.com/tikv/tikv/pull/4124) - -## Tools - -+ TiDB Binlog - - 修复在启动或者重启时 `no available pump` 的问题 [#157](https://github.com/pingcap/tidb-tools/pull/158) - - 开启 Pump client log 输出 [#165](https://github.com/pingcap/tidb-tools/pull/165) - - 修复表只有 unique key 没有 primary key 的情况下，unique key 包含 NULL 值导致数据更新不一致的问题 diff --git a/v2.1/releases/2.1.4.md b/v2.1/releases/2.1.4.md deleted file mode 100644 index 124e7d016726..000000000000 --- a/v2.1/releases/2.1.4.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB 2.1.4 Release Notes -category: Releases ---- - -# TiDB 2.1.4 Release Notes - -2019 年 2 月 15 日，TiDB 发布 2.1.4 版，TiDB Ansible 相应发布 2.1.4 版本。相比 2.1.3 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复 `VALUES` 函数未正确处理 FLOAT 类型的问题 [#9223](https://github.com/pingcap/tidb/pull/9223) - - 修复某些情况下 `CAST` 浮点数成字符串结果不正确的问题 [#9227](https://github.com/pingcap/tidb/pull/9227) - - 修复 `FORMAT` 函数在某些情况下结果不正确的问题 [#9235](https://github.com/pingcap/tidb/pull/9235) - - 修复某些情况下处理 Join 查询时 panic 的问题 [#9264](https://github.com/pingcap/tidb/pull/9264) - - 修复 `VALUES` 函数未正确处理 ENUM 类型的问题 [#9280](https://github.com/pingcap/tidb/pull/9280) - - 修复 `DATE_ADD`/`DATE_SUB` 在某些情况下结果不正确的问题 [#9284](https://github.com/pingcap/tidb/pull/9284) -+ Server - - 优化 reload privilege success 日志，将其调整为 DEBUG 级别 [#9274](https://github.com/pingcap/tidb/pull/9274) -+ DDL - - `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 变成 GLOBAL 变量 [#9134](https://github.com/pingcap/tidb/pull/9134) - - 修复某些异常情况下，在 Generated column 增加索引导致的 Bug [#9289](https://github.com/pingcap/tidb/pull/9289) - -## TiKV - -- 修复在 TiKV 关闭时可能发生重复写的问题 [#4146](https://github.com/tikv/tikv/pull/4146) -- 修复某些情况下 event listener 结果处理异常的问题 [#4132](https://github.com/tikv/tikv/pull/4132) - -## Tools - -+ Lightning - - 优化内存使用 [#107](https://github.com/pingcap/tidb-lightning/pull/107)，[#108](https://github.com/pingcap/tidb-lightning/pull/108) - - 去掉 dump files 的 chunk 划分，减少对 dump files 的一次额外解析 [#109](https://github.com/pingcap/tidb-lightning/pull/109) - - 限制读取 dump files 的 I/O 并发，避免过多的 cache miss 导致性能下降 [#110](https://github.com/pingcap/tidb-lightning/pull/110) - - 对单个表实现 batch 导入，提高导入的稳定性 [#110](https://github.com/pingcap/tidb-lightning/pull/113) - - TiKV 在 import 模式下开启 auto compactions [#4199](https://github.com/tikv/tikv/pull/4199) - - 增加禁用 TiKV periodic Level-1 compaction 参数，因为当 TiKV 集群为 2.1.4 或更高版本时，在导入模式下会自动执行 Level-1 compaction [#119](https://github.com/pingcap/tidb-lightning/pull/119) - - 限制 import engines 数量，避免过大占用 importer 磁盘空间 [#119](https://github.com/pingcap/tidb-lightning/pull/119) -+ 数据同步对比统计 (sync-diff-inspector) 支持使用 TiDB 统计信息来划分 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) diff --git a/v2.1/releases/2.1.5.md b/v2.1/releases/2.1.5.md deleted file mode 100644 index da0cddef07ef..000000000000 --- a/v2.1/releases/2.1.5.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: TiDB 2.1.5 Release Notes -category: Releases ---- - -# TiDB 2.1.5 Release Notes - -2019 年 2 月 28 日，TiDB 发布 2.1.5 版，TiDB Ansible 相应发布 2.1.5 版本。相比 2.1.4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 当列的字符集信息和表的字符集信息相同时，`SHOW CREATE TABLE` 不再打印列的字符集信息，使其结果更加兼容 MySQL [#9306](https://github.com/pingcap/tidb/pull/9306) - - 将 `Sort` 算子中的表达计算抽取出来用一个 `Project` 算子完成，简化 `Sort` 算子的计算逻辑，修复某些情况下 `Sort` 算子结果不正确或者 panic 的问题 [#9319](https://github.com/pingcap/tidb/pull/9319) - - 移除 `Sort` 算子中的数值为常量的排序字段 [#9335](https://github.com/pingcap/tidb/pull/9335)，[#9440](https://github.com/pingcap/tidb/pull/9440) - - 修复向无符号整数列插入数据时数据溢出的问题 [#9339](https://github.com/pingcap/tidb/pull/9339) - - 目标 binary 的长度超过 `max_allowed_packet` 时，将 `cast_as_binary` 设置为 `NULL` [#9349](https://github.com/pingcap/tidb/pull/9349) - - 优化 `IF` 和 `IFNULL` 的常量折叠过程 [#9351](https://github.com/pingcap/tidb/pull/9351) - - 使用 skyline pruning 优化 TiDB 的索引选择，增加简单查询的稳定性 [#9356](https://github.com/pingcap/tidb/pull/9356) - - 支持对析取范式计算选择率 [#9405](https://github.com/pingcap/tidb/pull/9405) - - 修复 `!=ANY()` 和 `=ALL()` 在某些情况下 SQL 查询结果不正确的问题 [#9403](https://github.com/pingcap/tidb/pull/9403) - - 修复执行 Merge Join 操作的两个表的 Join Key 类型不同时结果可能不正确或者 panic 的问题 [#9438](https://github.com/pingcap/tidb/pull/9438) - - 修复某些情况下 `RAND()` 函数结果和 MySQL 不兼容的问题 [#9446](https://github.com/pingcap/tidb/pull/9446) - - 重构 Semi Join 对 `NULL` 值和空结果集的处理逻辑，使其返回正确的结果，更加兼容 MySQL [#9449](https://github.com/pingcap/tidb/pull/9449) -+ Server - - 增加系统变量 `tidb_constraint_check_in_place`，在 `INSERT` 语句执行时即检查数据的唯一性约束 [#9401](https://github.com/pingcap/tidb/pull/9401) - - 修复系统变量 `tidb_force_priority` 的值和配置文件中的设置的值不一致的问题 [#9347](https://github.com/pingcap/tidb/pull/9347) - - 在 general log 中增加 “current_db” 字段打印当前使用的数据库 [#9346](https://github.com/pingcap/tidb/pull/9346) - - 增加通过表 ID 来获取表信息的 HTTP API [#9408](https://github.com/pingcap/tidb/pull/9408) - - 修复 `LOAD DATA` 在某些情况下导入数据不正确的问题 [#9414](https://github.com/pingcap/tidb/pull/9414) - - 修复某些情况下，客户端建立连接慢的问题 [#9451](https://github.com/pingcap/tidb/pull/9451) -+ DDL - - 修复撤销 `DROP COLUMN` 操作中的一些问题 [#9352](https://github.com/pingcap/tidb/pull/9352) - - 修复撤销 `DROP`/`ADD` 分区表操作中的一些问题 [#9376](https://github.com/pingcap/tidb/pull/9376) - - 修复某些情况下 `ADMIN CHECK TABLE` 误报数据索引不一致的问题 [#9399](https://github.com/pingcap/tidb/pull/9399) - - 修复 `TIMESTAMP` 类型的默认值在时区上的一些问题 [#9108](https://github.com/pingcap/tidb/pull/9108) - -## PD - -- `GetAllStores` 接口提供了 `exclude_tombstone_stores` 选项，将 Tombstone store 从返回结果中去除 [#1444](https://github.com/pingcap/pd/pull/1444) - -## TiKV - -- 修复了某些情况下 Importer 导入失败的问题 [#4223](https://github.com/tikv/tikv/pull/4223) -- 修复了某些情况下 "key not in region" 错误 [#4125](https://github.com/tikv/tikv/pull/4125) -- 修复了某些情况下 Region merge 导致 panic 的问题 [#4235](https://github.com/tikv/tikv/pull/4235) -- 添加了详细的 `StoreNotMatch` 错误信息 [#3885](https://github.com/tikv/tikv/pull/3885) - -## Tools - -+ Lightning - - 集群中有 Tombstone store 时 Lightning 不会再报错退出 [#4223](https://github.com/tikv/tikv/pull/4223) -+ TiDB Binlog - - 修正 DDL Binlog 同步方案，确保 DDL 同步的正确性 [#9304](https://github.com/pingcap/tidb/issues/9304) diff --git a/v2.1/releases/2.1.6.md b/v2.1/releases/2.1.6.md deleted file mode 100644 index 1c55c70b466b..000000000000 --- a/v2.1/releases/2.1.6.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.6 Release Notes -category: Releases ---- - -# TiDB 2.1.6 Release Notes - -2019 年 3 月 15 日，TiDB 发布 2.1.6 版，TiDB Ansible 相应发布 2.1.6 版本。相比 2.1.5 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 当两个表在 `TIDB_INLJ` 的 Hint 中时，基于代价来选择外表 [#9615](https://github.com/pingcap/tidb/pull/9615) - - 修复在某些情况下，没有正确选择 IndexScan 的问题 [#9587](https://github.com/pingcap/tidb/pull/9587) - - 修复聚合函数在子查询里面的检查跟 MySQL 不兼容的行为 [#9551](https://github.com/pingcap/tidb/pull/9551) - - 使 `show stats_histograms` 语句只输出合法的列，避免 Panic [#9502](https://github.com/pingcap/tidb/pull/9502) -+ Server - - 支持变量 `log_bin`，用于开启/关闭 Binlog [#9634](https://github.com/pingcap/tidb/pull/9634) - - 在事务中添加一个防御性检查，避免错误的事务提交 [#9559](https://github.com/pingcap/tidb/pull/9559) - - 修复设置变量导致的 Panic 的问题 [#9539](https://github.com/pingcap/tidb/pull/9539) -+ DDL - - 修复 Create Table Like 语句在某些情况导致 Panic 的问题 [#9652](https://github.com/pingcap/tidb/pull/9652) - - 打开 etcd client 的 AutoSync 特性，防止某些情况下 TiDB 无法连接上 etcd 的问题 [#9600](https://github.com/pingcap/tidb/pull/9600) - -## TiKV - -- 修复在某些情况下解析 protobuf 失败导致 `StoreNotMatch` 错误的问题 [#4303](https://github.com/tikv/tikv/pull/4303) - -## Tools - -+ Lightning - - importer 的默认的 region-split-size 变更为 512 MiB [#4369](https://github.com/tikv/tikv/pull/4369) - - 保存原先在内存中的中间状态的 SST 到磁盘，减少内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 限制 RocksDB 的内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 修复 Region 还没有调度完成时进行 scatter 的问题 [#4369](https://github.com/tikv/tikv/pull/4369) - - 将大表的数据和索引分离导入，在分批导入时能有效降低耗时 [#132](https://github.com/pingcap/tidb-lightning/pull/132) - - 支援 CSV [#111](https://github.com/pingcap/tidb-lightning/pull/111) - - 修复库名中含非英数字符时导入失败的错误 [#9547](https://github.com/pingcap/tidb/pull/9547) diff --git a/v2.1/releases/2.1.7.md b/v2.1/releases/2.1.7.md deleted file mode 100644 index 8ac63197224f..000000000000 --- a/v2.1/releases/2.1.7.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB 2.1.7 Release Notes -category: Releases ---- - -# TiDB 2.1.7 Release Notes - -发版日期：2019 年 3 月 28 日 - -TiDB 版本：2.1.7 - -TiDB Ansible 版本：2.1.7 - -## TiDB - -- 修复因 DDL 被取消导致升级程序时启动时间变长问题 [#9768](https://github.com/pingcap/tidb/pull/9768) -- 修复配置项 `check-mb4-value-in-utf8` 在 `config.example.toml` 中位置错误的问题 [#9852](https://github.com/pingcap/tidb/pull/9852) -- 提升内置函数 `str_to_date` 跟 MySQL 的兼容性 [#9817](https://github.com/pingcap/tidb/pull/9817) -- 修复内置函数 `last_day` 的兼容性问题 [#9750](https://github.com/pingcap/tidb/pull/9750) -- `infoschema.tables` 添加 `tidb_table_id` 列，方便通过 SQL 语句获取 `table_id`，新增 `tidb_indexes` 系统表管理 Table 与 Index 之间的关系 [#9862](https://github.com/pingcap/tidb/pull/9862) -- 增加 Table Partition 定义为空的检查 [#9663](https://github.com/pingcap/tidb/pull/9663) -- 将 `Truncate Table` 需要的权限由删除权限变为删表权限，与 MySQL 保持一致 [#9876](https://github.com/pingcap/tidb/pull/9876) -- 支持在 `DO` 语句中使用子查询 [#9877](https://github.com/pingcap/tidb/pull/9877) -- 修复变量 `default_week_format` 在 week 函数中不生效的问题 [#9753](https://github.com/pingcap/tidb/pull/9753) -- 支持插件机制 [#9880](https://github.com/pingcap/tidb/pull/9880)，[#9888](https://github.com/pingcap/tidb/pull/9888) -- 支持使用系统变量 `log_bin` 查看 binlog 开启状况 [#9634](https://github.com/pingcap/tidb/pull/9634) -- 支持使用 SQL 语句查看 Pump/Drainer 状态 [#9896](https://github.com/pingcap/tidb/pull/9896) -- 修复升级时对 utf8 检查 mb4 字符的兼容性 [#9887](https://github.com/pingcap/tidb/pull/9887) -- 修复某些情况下对 JSON 数据的聚合函数在计算过程中 Panic 的问题 [#9927](https://github.com/pingcap/tidb/pull/9927) - -## PD - -- 修改副本数为 1 时 balance-region 无法迁移 leader 问题 [#1462](https://github.com/pingcap/pd/pull/1462) - -## Tools - -- 支持 binlog 同步 generated column [#491](https://github.com/pingcap/tidb-binlog/pull/491) - -## TiDB Ansible - -- Prometheus 监控数据默认保留时间改成 30d diff --git a/v2.1/releases/2.1.8.md b/v2.1/releases/2.1.8.md deleted file mode 100644 index fec9580a22d7..000000000000 --- a/v2.1/releases/2.1.8.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: TiDB 2.1.8 Release Notes -category: Releases ---- - -# TiDB 2.1.8 Release Notes - -发版日期：2019 年 4 月 12 日 - -TiDB 版本：2.1.8 - -TiDB Ansible 版本：2.1.8 - -## TiDB - -- 修复 `GROUP_CONCAT` 函数在参数存在 NULL 值情况下与 MySQL 处理逻辑不兼容的问题 [#9930](https://github.com/pingcap/tidb/pull/9930) -- 修复在 Distinct 模式下 decimal 类型值之间相等比较的问题 [#9931](https://github.com/pingcap/tidb/pull/9931) -- 修复 `SHOW FULL COLUMNS` 语句在 date，datetime，timestamp 类型的 Collation 的兼容性问题 - - [#9938](https://github.com/pingcap/tidb/pull/9938) - - [#10114](https://github.com/pingcap/tidb/pull/10114) -- 修复过滤条件存在关联列的时候统计信息估算行数不准确的问题 [#9937](https://github.com/pingcap/tidb/pull/9937) -- 修复 `DATE_ADD` 跟 `DATE_SUB` 函数的兼容性问题 - - [#9963](https://github.com/pingcap/tidb/pull/9963) - - [#9966](https://github.com/pingcap/tidb/pull/9966) -- `STR_TO_DATE` 函数支持格式 `%H`，提升兼容性 [#9964](https://github.com/pingcap/tidb/pull/9964) -- 修复 `GROUP_CONCAT` 函数在 group by 唯一索引的情况下结果错误的问题 [#9969](https://github.com/pingcap/tidb/pull/9969) -- 当 Optimizer Hints 存在不匹配的表名的时候返回 warning [#9970](https://github.com/pingcap/tidb/pull/9970) -- 统一日志格式规范，利于工具收集分析 [日志规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md) -- 修复大量 NULL 值导致统计信息估算不准确的问题 [#9979](https://github.com/pingcap/tidb/pull/9979) -- 修复 TIMESTAMP 类型默认值为边界值的时候报错的问题 [#9987](https://github.com/pingcap/tidb/pull/9987) -- 检查设置 `time_zone` 值的合法性 [#10000](https://github.com/pingcap/tidb/pull/10000) -- 支持时间格式 `2019.01.01` [#10001](https://github.com/pingcap/tidb/pull/10001) -- 修复某些情况下 `EXPLAIN` 结果中行数估计错误显示的问题 [#10044](https://github.com/pingcap/tidb/pull/10044) -- 修复 `KILL TIDB [session id]` 某些情况下无法快速停止语句执行的问题 [#9976](https://github.com/pingcap/tidb/pull/9976) -- 修复常量过滤条件在某些情况中谓词下推的问题 [#10049](https://github.com/pingcap/tidb/pull/10049) -- 修复某些情况下 READ-ONLY 语句没有被当成 READ-ONLY 来处理的问题 [#10048](https://github.com/pingcap/tidb/pull/10048) - -## PD - -- 修复 Scatter Region 产生无效 Operator Step 的问题 [#1482](https://github.com/pingcap/pd/pull/1482) -- 修复 store 读热点的 key 统计不正确问题 [#1487](https://github.com/pingcap/pd/pull/1487) -- 修复 Region Merge Operator 超时时间过短的问题 [#1495](https://github.com/pingcap/pd/pull/1495) -- 添加 PD server 端处理 TSO 请求的耗时 metrics [#1502](https://github.com/pingcap/pd/pull/1502) - -## TiKV - -- 修复读流量统计错误的问题 [#4441](https://github.com/tikv/tikv/pull/4441) -- 修复 Region 数过多的情况下 raftstore 的性能问题 [#4484](https://github.com/tikv/tikv/pull/4484) -- 调整当 level 0 SST 数量超过 `level_zero_slowdown_writes_trigger/2` 时不再继续 ingest file [#4464](https://github.com/tikv/tikv/pull/4464) - -## Tools - -- Lightning 优化导入表的顺序，按照表的数据大小顺序进行导入，减少导入过程中大表执行 `Checksum` 和 `Analyze` 对集群的影响，并且提高 `Checksum` 和 `Analyze` 的成功率 [#156](https://github.com/pingcap/tidb-lightning/pull/156) -- 提升 Lightning encode SQL 性能，性能提升 50%，直接解析数据源文件内容成 TiDB 的 `types.Datum`，省去 KV encoder 的多余解析工作 [#145](https://github.com/pingcap/tidb-lightning/pull/145) -- TiDB Binlog Pump 新增 `storage.sync-log` 配置项，支持 Pump 本地存储异步刷盘 [#529](https://github.com/pingcap/tidb-binlog/pull/529) -- TiDB Binlog Pump 和 Drainer 之间通讯支持流量压缩 [#530](https://github.com/pingcap/tidb-binlog/pull/530) -- TiDB Binlog Drainer 新增 `syncer.sql-mode` 配置项，支持使用不同 `sql-mode` 解析 DDL query [#513](https://github.com/pingcap/tidb-binlog/pull/513) -- TiDB Binlog Drainer 新增 `syncer.ignore-table` 配置项，支持过滤不需要同步的表 [#526](https://github.com/pingcap/tidb-binlog/pull/526) - -## TiDB Ansible - -- 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 [#734](https://github.com/pingcap/tidb-ansible/pull/734) -- 添加检测系统是否支持 `epollexclusive` [#728](https://github.com/pingcap/tidb-ansible/pull/728) -- 增加滚动升级版本限制，不允许从 2.0.1 及以下版本滚动升级到 2.1 及以上版本 [#728](https://github.com/pingcap/tidb-ansible/pull/728) diff --git a/v2.1/releases/2.1.9.md b/v2.1/releases/2.1.9.md deleted file mode 100644 index 3f38b3a77279..000000000000 --- a/v2.1/releases/2.1.9.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: TiDB 2.1.9 Release Notes -category: Releases ---- - -# TiDB 2.1.9 Release Notes - -发版日期：2019 年 5 月 6 日 - -TiDB 版本：2.1.9 - -TiDB Ansible 版本：2.1.9 - -## TiDB - -- 修复 `MAKETIME` 函数在 unsigned 类型溢出时的兼容性 [#10089](https://github.com/pingcap/tidb/pull/10089) -- 修复常量折叠在某些情况下导致的栈溢出 [#10189](https://github.com/pingcap/tidb/pull/10189) -- 修复 Update 在某些有别名的情况下权限检查的问题 [#10157](https://github.com/pingcap/tidb/pull/10157) [#10326](https://github.com/pingcap/tidb/pull/10326) -- 追踪以及控制 DistSQL 中的内存使用 [#10197](https://github.com/pingcap/tidb/pull/10197) -- 支持指定 collation 为 utf8mb4_0900_ai_ci [#10201](https://github.com/pingcap/tidb/pull/10201) -- 修复主键为 Unsigned 类型的时候，MAX 函数结果错误的问题 [#10209](https://github.com/pingcap/tidb/pull/10209) -- 修复在非 Strict SQL Mode 下可以插入 NULL 值到 NOT NULL 列的问题 [#10254](https://github.com/pingcap/tidb/pull/10254) -- 修复 COUNT 函数在 DISTINCT 有多列的情况下结果错误的问题 [#10270](https://github.com/pingcap/tidb/pull/10270) -- 修复 LOAD DATA 解析不规则的 CSV 文件时候 Panic 的问题 [#10269](https://github.com/pingcap/tidb/pull/10269) -- 忽略 Index Lookup Join 中内外 join key 类型不一致的时候出现的 overflow 错误 [#10244](https://github.com/pingcap/tidb/pull/10244) -- 修复某些情况下错误判定语句为 point-get 的问题 [#10299](https://github.com/pingcap/tidb/pull/10299) -- 修复某些情况下时间类型未转换时区导致的结果错误问题 [#10345](https://github.com/pingcap/tidb/pull/10345) -- 修复 TiDB 字符集在某些情况下大小写比较不一致的问题 [#10354](https://github.com/pingcap/tidb/pull/10354) -- 支持控制算子返回的行数 [#9166](https://github.com/pingcap/tidb/issues/9166) - - Selection & Projection [#10110](https://github.com/pingcap/tidb/pull/10110) - - StreamAgg & HashAgg [#10133](https://github.com/pingcap/tidb/pull/10133) - - TableReader & IndexReader & IndexLookup [#10169](https://github.com/pingcap/tidb/pull/10169) -- 慢日志改进 - - 增加 SQL Digest 用于区分同类 SQL [#10093](https://github.com/pingcap/tidb/pull/10093) - - 增加慢语句使用的统计信息的版本信息 [#10220](https://github.com/pingcap/tidb/pull/10220) - - 输出语句内存使用量 [#10246](https://github.com/pingcap/tidb/pull/10246) - - 调整 Coprocessor 相关信息的输出格式，让其能被 pt-query-digest 解析 [#10300](https://github.com/pingcap/tidb/pull/10300) - - 修复慢语句中带有 `#` 字符的问题 [#10275](https://github.com/pingcap/tidb/pull/10275) - - 增加一些信息的列到慢查询的内存表 [#10317](https://github.com/pingcap/tidb/pull/10317) - - 将事务提交时间算入慢语句执行时间 [#10310](https://github.com/pingcap/tidb/pull/10310) - - 修复某些时间格式无法被 pt-query-digest 解析的问题 [#10323](https://github.com/pingcap/tidb/pull/10323) - -## PD - -- 支持 GetOperator 服务 [#1514](https://github.com/pingcap/pd/pull/1514) - -## TiKV - -- 修复在 transfer leader 时非预期的 quorum 变化 [#4604](https://github.com/tikv/tikv/pull/4604) - -## Tools - -- TiDB Binlog - - 修复 unsigned int 类型的主键列的 binlog 数据为负数，造成同步出错中断的问题 [#574](https://github.com/pingcap/tidb-binlog/pull/574) - - 删除下游是 `pb` 时的压缩选项，修改下游名字 `pb` 成 `file` [#597](https://github.com/pingcap/tidb-binlog/pull/575) - - 修复 2.1.7 引入的 Reparo 生成错误 update 语句的 bug [#576](https://github.com/pingcap/tidb-binlog/pull/576) -- TiDB Lightning - - 修复 parser 解析 bit 类型的 column 数据错误的 bug [#164](https://github.com/pingcap/tidb-lightning/pull/164) - - 使用 row id 或者列的默认值填充 dump 文件中缺少的 column 数据 [#174](https://github.com/pingcap/tidb-lightning/pull/174) - - Importer 修复部分 SST 导入失败依然返回导入成功的 bug [#4566](https://github.com/tikv/tikv/pull/4566) - - Importer 支持 upload SST 到 TiKV 限速 [#4607](https://github.com/tikv/tikv/pull/4607) - - 修改 Importer RocksDB SST 压缩方法为 `lz4`，减少 CPU 消耗 [#4624](https://github.com/tikv/tikv/pull/4624) -- sync-diff-inspector - - 支持 checkpoint [#227](https://github.com/pingcap/tidb-tools/pull/227) - -## TiDB Ansible - -- 更新 tidb-ansible 中的文档链接，兼容重构之后的文档 [#740](https://github.com/pingcap/tidb-ansible/pull/740)，[#741](https://github.com/pingcap/tidb-ansible/pull/741) -- 移除 `inventory.ini` 中的 `enable_slow_query_log` 参数，默认即将 slow log 输出到单独的日志文件中 [#742](https://github.com/pingcap/tidb-ansible/pull/742) diff --git a/v2.1/releases/2.1ga.md b/v2.1/releases/2.1ga.md deleted file mode 100644 index fcb5ac7a4522..000000000000 --- a/v2.1/releases/2.1ga.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: TiDB 2.1 GA Release Notes -category: Releases ---- - -# TiDB 2.1 GA Release Notes - -2018 年 11 月 30 日，TiDB 发布 2.1 GA 版。相比 2.0 版本，该版本对系统稳定性、性能、兼容性、易用性做了大量改进。 - -## TiDB - -+ SQL 优化器 - - - 优化 `Index Join` 选择范围，提升执行性能 - - 优化 `Index Join` 外表选择，使用估算的行数较少的表作为外表 - - 扩大 Join Hint `TIDB_SMJ` 的作用范围，在没有合适索引可用的情况下也可使用 Merge Join - - 加强 Join Hint `TIDB_INLJ` 的能力，可以指定 Join 中的内表 - - 优化关联子查询，包括下推 Filter 和扩大索引选择范围，部分查询的效率有数量级的提升 - - 支持在 `UPDATE` 和 `DELETE` 语句中使用 Index Hint 和 Join Hint - - 支持更多函数下推：`ABS`/`CEIL`/`FLOOR`/`IS TRUE`/`IS FALSE` - - 优化内建函数 `IF` 和 `IFNULL` 的常量折叠算法 - - 优化 `EXPLAIN` 语句输出格式, 使用层级结构表示算子之间的上下游关系 - -+ SQL 执行引擎 - - - 重构所有聚合函数，提升 `Stream` 和 `Hash` 聚合算子的执行效率 - - 实现并行 `Hash Aggregate` 算子，部分场景下有 350% 的性能提升 - - 实现并行 `Project` 算子，部分场景有 74% 的性能提升 - - 并发地读取 `Hash Join` 的 `Inner` 表和 `Outer` 表的数据，提升执行性能 - - 优化 `REPLACE INTO` 语句的执行速度，性能提升 10x - - 优化时间类型的内存占用，时间类型数据的内存使用降低为原来的一半 - - 优化点查的查询性能，Sysbench 点查效率提升 60% - - TiDB 插入和更新宽表，性能提升接近 20 倍 - - 支持在配置文件中设置单个查询的内存使用上限 - - 优化 `Hash Join` 的执行过程，当 Join 类型为 `Inner Join` 或者 `Semi Join` 时，如果内表为空，不再读取外表数据，快速返回结果 - - 支持 `EXPLAIN ANALYZE` 语句，用于查看 Query 执行过程中各个算子的运行时间，返回结果行数等运行时统计信息 - -+ 统计信息 - - - 支持只在一天中的某个时间段开启统计信息自动 ANALYZE 的功能 - - 支持根据查询的反馈自动更新表的统计信息 - - 支持通过 `ANALYZE TABLE WITH BUCKETS` 语句配置直方图中桶的个数 - - 优化等值查询和范围查询混合的情况下使用直方图估算 Row Count 的算法 - -+ 表达式 - - + 支持内建函数： - - - `json_contains` - - `json_contains_path` - - `encode/decode` - -+ Server - - - 支持在单个 tidb-server 实例内部对冲突事务排队，优化事务间冲突频繁的场景下的性能 - - 支持 Server Side Cursor - - 新增 HTTP 管理接口 - - 打散 table 的 Regions 在 TiKV 集群中的分布 - - 控制是否打开 `general log` - - 在线修改日志级别 - - 查询 TiDB 集群信息 - - 添加 `auto_analyze_ratio` 系统变量控制自动 Analyze 的阈值 - - 添加 `tidb_retry_limit` 系统变量控制事务自动重试的次数 - - 添加 `tidb_disable_txn_auto_retry` 系统变量控制事务是否自动重试 - - 支持使用 `admin show slow` 语句来获取慢查询语句 - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 - -+ DDL - - - 支持 Add Index 语句与其他 DDL 语句并行执行，避免耗时的 Add Index 操作阻塞其他操作 - - 优化 `Add Index` 的速度，在某些场景下速度大幅提升 - - 支持 `select tidb_is_ddl_owner()` 语句，方便判断 TiDB 是否为 `DDL Owner` - - 支持 `ALTER TABLE FORCE` 语法 - - 支持 `ALTER TABLE RENAME KEY TO` 语法 - - `Admin Show DDL Jobs` 输出结果中添加表名、库名等信息 - - 支持使用 `ddl/owner/resign` HTTP 接口释放 DDL Owner 并开启新一轮 DDL Owner 选举 - -+ 兼容性 - - - 支持更多 MySQL 语法 - - `BIT` 聚合函数支持 `ALL` 参数 - - 支持 `SHOW PRIVILEGES` 语句 - - 支持 `LOAD DATA` 语句的 `CHARACTER SET` 语法 - - 支持 `CREATE USER` 语句的 `IDENTIFIED WITH` 语法 - - 支持 `LOAD DATA IGNORE LINES` 语句 - - `Show ProcessList` 语句返回更准确信息 - -## PD (Placement Driver) - -+ 可用性优化 - - - 引入 TiKV 版本控制机制，支持集群滚动兼容升级 - - PD 节点间开启 `Raft PreVote`，避免网络隔离后恢复时产生的重新选举 - - 开启 `raft learner` 功能，降低调度时出现宕机导致数据不可用的风险 - - TSO 分配不再受系统时间回退影响 - - 支持 `Region merge` 功能，减少元数据带来的开销 - -+ 调度器优化 - - - 优化 Down Store 的处理流程，加快发生宕机后补副本的速度 - - 优化热点调度器，在流量统计信息抖动时适应性更好 - - 优化 Coordinator 的启动，减少重启 PD 时带来的不必要调度 - - 优化 Balance Scheduler 频繁调度小 Region 的问题 - - 优化 Region merge，调度时考虑 Region 中数据的行数 - - 新增一些控制调度策略的开关 - - 完善调度模拟器，添加调度场景模拟 - -+ API 及运维工具 - - - 新增 `GetPrevRegion` 接口，用于支持 TiDB reverse scan 功能 - - 新增 `BatchSplitRegion` 接口，用于支持 TiKV 快速 Region 分裂 - - 新增 `GCSafePoint` 接口，用于支持 TiDB 并发分布式 GC - - 新增 `GetAllStores` 接口，用于支持 TiDB 并发分布式 GC - + pd-ctl 新增： - - - 使用统计信息进行 Region split - - 调用 `jq` 来格式化 JSON 输出 - - 查询指定 store 的 Region 信息 - - 查询按 version 排序的 topN 的 Region 列表 - - 查询按 size 排序的 topN 的 Region 列表 - - 更精确的 TSO 解码 - - - pd-recover 不再需要提供 max-replica 参数 - -+ 监控 - - - 增加 `Filter` 相关的监控 - - 新增 etcd Raft 状态机相关监控 - -+ 性能优化 - - - 优化处理 Region heartbeat 的性能，减少 heartbeat 带来的内存开销 - - 优化 Region tree 性能 - - 优化计算热点统计的性能问题 - -## TiKV - -+ Coprocessor - - - 新增支持大量内建函数 - - 新增 Coprocessor ReadPool，提高请求处理并发度 - - 修复时间函数解析以及时区相关问题 - - 优化下推聚合计算的内存使用 - -+ Transaction - - - 优化 MVCC 读取逻辑以及内存使用效率，提高扫描操作的性能，Count 全表性能比 2.0 版本提升 1 倍 - - 折叠 MVCC 中连续的 Rollback 记录，保证记录的读取性能 - - 新增 `UnsafeDestroyRange` API 用于在 drop table/index 的情况下快速回收空间 - - GC 模块独立出来，减少对正常写入的影响 - - kv_scan 命令支持设置 upper bound - -+ Raftstore - - - 优化 snapshot 文件写入流程避免导致 RocksDB stall - - 增加 LocalReader 线程专门处理读请求，降低读请求的延迟 - - 支持 `BatchSplit` 避免大量写入导致产生特别大的 Region - - 支持按照统计信息进行 Region Split，减少 IO 开销 - - 支持按照 Key 的数量进行 Region Split，提高索引扫描的并发度 - - 优化部分 Raft 消息处理流程，避免 Region Split 带来不必要的延迟 - - 启用 `PreVote` 功能，减少网络隔离对服务的影响 - -+ 存储引擎 - - - 修复 RocksDB `CompactFiles` 的 bug，可能影响 Lightning 导入的数据 - - 升级 RocksDB 到 v5.15，解决 snapshot 文件可能会被写坏的问题 - - 优化 `IngestExternalFile`，避免 flush 卡住写入的问题 - -+ tikv-ctl - - - 新增 ldb 命令，方便排查 RocksDB 相关问题 - - compact 命令支持指定是否 compact bottommost 层的数据 - -## Tools - -- 全量数据快速导入工具 TiDB Lightning -- 支持新版本 TiDB Binlog - -## 升级兼容性说明 - -+ 由于新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 -+ 从 2.0.6 之前的版本升级到 2.1 之前，最好确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 Add Index 操作，等 DDL 操作完成后再执行升级操作 -+ 因为 2.1 版本启用了并行 DDL，对于早于 2.0.1 版本的集群，无法滚动升级到 2.1，可以选择下面两种方案： - - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 2.1 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 2.1 版本 \ No newline at end of file diff --git a/v2.1/releases/201.md b/v2.1/releases/201.md deleted file mode 100644 index f716920f38cc..000000000000 --- a/v2.1/releases/201.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: TiDB 2.0.1 release notes -category: Releases ---- - - -# TiDB 2.0.1 Release Notes - -2018 年 5 月 16 日，TiDB 发布 2.0.1 版。该版本在 2.0.0 (GA) 版的基础上，对 MySQL 兼容性、系统稳定性做出了改进。 - -## TiDB - -- 实时更新 `Add Index` 的进度到 DDL 任务信息中 -- 添加 Session 变量 `tidb_auto_analyze_ratio` 控制统计信息自动更新阈值 -- 修复当事务提交失败时可能未清理所有的残留状态的问题 -- 修复加索引在部分情况下的 Bug -- 修复 DDL 修改表面操作在某些并发场景下的正确性问题 -- 修复某些情况下 `LIMIT` 结果不正确的问题 -- 修复 `ADMIN CHECK INDEX` 语句索引名字区分大小写问题 -- 修复 `UNION` 语句的兼容性问题 -- 修复插入 `TIME` 类型数据的兼容性问题 -- 修复某些情况下 `copIteratorTaskSender` 导致的 goroutine 泄漏问题 -- 增加一个选项，用于设置 TiDB 在写 Binlog 失败的情况下的行为 -- 优化 Coprocessor 慢请求日志格式，区分处理时间长与排队时间长的任务 -- MySQL 协议握手阶段发生错误不打印日志，避免 KeepAlive 造成大量日志 -- 优化 `Out of range value for column` 的错误信息 -- 修复 `Update` 语句中遇到子查询导致结果错误的问题 -- 调整 TiDB 进程处理 `SIGTERM` 的行为，不等待正在执行的 Query 完成 - -## PD - -- 添加 `Scatter Range` 调度，调度指定 Key Range 包含的 Region -- 优化 `Merge Region` 调度，使新分裂不久的 Region 不能被合并 -- 添加 learner 相关的 metrics -- 修复重启误删 scheduler 的问题 -- 修复解析配置文件出错问题 -- 修复 etcd leader 和 PD leader 不同步的问题 -- 修复关闭 learner 情况下还有 learner 出现的问题 -- 修复读取包过大造成 load Regions 失败的问题 - -## TiKV - -- 修复 `SELECT FOR UPDATE` 阻止其他人读的问题 -- 优化慢查询的日志 -- 减少 `thread_yield` 的调用次数 -- 修复生成 snapshot 会意外阻塞 raftstore 的 bug -- 修复特殊情况下开启 learner 无法选举成功的问题 -- 修复极端情况下分裂可能导致的脏读问题 -- 修正读线程池的配置默认值 -- 修正删大数据表会影响写性能的问题 diff --git a/v2.1/releases/202.md b/v2.1/releases/202.md deleted file mode 100644 index fcc3842152e3..000000000000 --- a/v2.1/releases/202.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: TiDB 2.0.2 release notes -category: Releases ---- - -# TiDB 2.0.2 Release Notes - -2018 年 5 月 21 日，TiDB 发布 2.0.2 版。该版本在 2.0.1 版的基础上，对系统稳定性做出了改进。 - -## TiDB - -- 修复 Decimal 除法内置函数下推的问题 -- 支持 `Delete` 语句中使用 `USE INDEX` 的语法 -- 禁止在带有 `Auto-Increment` 的列中使用 `shard_row_id_bits` 特性 -- 增加写入 Binlog 的超时机制 - -## PD - -- 使 balance leader scheduler 过滤失连节点 -- 更改 transfer leader operator 的超时时间为 10 秒 -- 修复 label scheduler 在集群 Regions 不健康状态下不调度的问题 -- 修复 evict leader scheduler 调度不当的问题 - -## TiKV - -- 修复 Raft 日志没有打出来的问题 -- 支持配置更多 gRPC 相关参数 -- 支持配置选举超时的取值范围 -- 修复过期 learner 没有删掉的问题 -- 修复 snapshot 中间文件被误删的问题 \ No newline at end of file diff --git a/v2.1/releases/203.md b/v2.1/releases/203.md deleted file mode 100644 index 75974a1d1090..000000000000 --- a/v2.1/releases/203.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: TiDB 2.0.3 release notes -category: Releases ---- - -# TiDB 2.0.3 Release Notes - -2018 年 6 月 1 日，TiDB 发布 2.0.3 版。该版本在 2.0.2 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 支持在线更改日志级别 -- 支持 `COM_CHANGE_USER` 命令 -- 支持二进制协议情况下使用时间类型参数 -- 优化带 `BETWEEN` 表达式的查询条件代价估算 -- 在 `SHOW CREATE TABLE` 里不显示 `FOREIGN KEY` 信息 -- 优化带 `LIMIT` 子句的查询代价估算 -- 修复 `YEAR` 类型作为唯一索引的问题 -- 修复在没有唯一索引的情况下 `ON DUPLICATE KEY UPDATE` 的问题 -- 修复 `CEIL` 函数的兼容性问题 -- 修复 `DECIMAL` 类型计算 `DIV` 的精度问题 -- 修复 `ADMIN CHECK TABLE` 误报的问题 -- 修复 `MAX`/`MIN` 在特定表达式参数下 panic 的问题 -- 修复特殊情况下 `JOIN` 结果为空的问题 -- 修复 `IN` 表达式构造查询 `Range` 的问题 -- 修复使用 `Prepare` 方式进行查询且启用 `Plan Cache` 情况下的 Range 计算问题 -- 修复异常情况下频繁加载 Schema 信息的问题 - -## PD - -- 修复在特定条件下收集 hot-cache metrics 会 panic 的问题 -- 修复对旧的 Region 产生调度的问题 - -## TiKV - -- 修复 learner flag 错误上报给 PD 的 bug -- 在 `do_div_mod` 中 `divisor/dividend` 为 0 时返回错误 \ No newline at end of file diff --git a/v2.1/releases/204.md b/v2.1/releases/204.md deleted file mode 100644 index 23aa7846b142..000000000000 --- a/v2.1/releases/204.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB 2.0.4 release notes -category: Releases ---- - -# TiDB 2.0.4 Release Notes - -2018 年 6 月 15 日，TiDB 发布 2.0.4 版。该版本在 2.0.3 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 支持 `ALTER TABLE t DROP COLUMN a CASCADE` 语法 -- 支持设置 `tidb_snapshot` 变量的值为 `TSO` -- 优化监控项中语句类型展示 -- 优化查询代价估计精度 -- 设置 gRPC 的 `backoff max delay` 参数 -- 支持通过配置文件设置单条语句的内存使用阈值 -- 重构 Optimizer 的 error -- 解决 Cast Decimal 数据的副作用问题 -- 解决特定场景下 `Merge Join` 算子结果错误的问题 -- 解决转换 `Null` 对象到 String 的问题 -- 解决 Cast JSON 数据为 JSON 类型的问题 -- 解决 `Union` + `OrderBy` 情况下结果顺序和 MySQL 不一致的问题 -- 解决 `Union` 语句中对 `Limit`/`OrderBy` 子句的合法性检查规则问题 -- 解决 `Union All` 的结果兼容性问题 -- 解决谓词下推中的一个 Bug -- 解决 `Union` 语句对 `For Update` 子句的兼容性问题 -- 解决 `concat_ws` 函数对结果错误截断的问题 - -## PD - -- 改进 `max-pending-peer-count` 调度参数未设置时的行为，调整为不限制最大 `PendingPeer` 的数量 - -## TiKV - -- 新增 RocksDB `PerfContext` 接口用于调试 -- 移除 `import-mode` 参数 -- 为 `tikv-ctl` 添加 `region-properties` 命令 -- 优化有大量 RocksDB tombstone 时 `reverse-seek` 过慢的问题 -- 修复 `do_sub` 导致的崩溃问题 -- 当 GC 遇到有太多版本的数据时记录日志 diff --git a/v2.1/releases/205.md b/v2.1/releases/205.md deleted file mode 100644 index 588bed594a4d..000000000000 --- a/v2.1/releases/205.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB 2.0.5 release notes -category: Releases ---- - -# TiDB 2.0.5 Release Notes - -2018 年 7 月 6 日，TiDB 发布 2.0.5 版。该版本在 2.0.4 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- New Features - - 增加一个系统变量 `tidb_disable_txn_auto_retry`，用于关闭事务自动重试 [#6877](https://github.com/pingcap/tidb/pull/6877) -- Improvements - - 调整计算 `Selection` 代价的方式，结果更准确 [#6989](https://github.com/pingcap/tidb/pull/6989) - - 查询条件能够完全匹配唯一索引或者主键时，直接选择作为查询路径 [#6966](https://github.com/pingcap/tidb/pull/6966) - - 启动服务失败时，做必要的清理工作 [#6964](https://github.com/pingcap/tidb/pull/6964) - - 在 `Load Data` 语句中，将 `\N` 处理为 NULL [#6962](https://github.com/pingcap/tidb/pull/6962) - - 优化 CBO 代码结构 [#6953](https://github.com/pingcap/tidb/pull/6953) - - 启动服务时，尽早上报监控数据 [#6931](https://github.com/pingcap/tidb/pull/6931) - - 对慢查询日志格式进行优化：去除 SQL 语句中的换行符，增加用户信息 [#6920](https://github.com/pingcap/tidb/pull/6920) - - 支持注释中存在多个星号的情况 [#6858](https://github.com/pingcap/tidb/pull/6858) -- Bug Fixes - - 修复 `KILL QUERY` 语句权限检查问题 [#7003](https://github.com/pingcap/tidb/pull/7003) - - 修复用户数量超过 1024 时可能造成无法登录的问题 [#6986](https://github.com/pingcap/tidb/pull/6986) - - 修复一个写入无符号类型 `float`/`double` 数据的问题 [#6940](https://github.com/pingcap/tidb/pull/6940) - - 修复 `COM_FIELD_LIST` 命令的兼容性，解决部分 MariaDB 客户端遇到 Panic 的问题 [#6929](https://github.com/pingcap/tidb/pull/6929) - - 修复 `CREATE TABLE IF NOT EXISTS LIKE` 行为 [#6928](https://github.com/pingcap/tidb/pull/6928) - - 修复一个 TopN 下推过程中的问题 [#6923](https://github.com/pingcap/tidb/pull/6923) - - 修复 `Add Index` 过程中遇到错误时当前处理的行 ID 记录问题 [#6903](https://github.com/pingcap/tidb/pull/6903) - -## PD - -- 修复某些场景下副本迁移导致 TiKV 磁盘空间耗尽的问题 -- 修复 `AdjacentRegionScheduler` 导致的崩溃问题 - -## TiKV - -- 修复 decimal 运算中潜在的溢出问题 -- 修复 merge 过程中可能发生的脏读问题 \ No newline at end of file diff --git a/v2.1/releases/206.md b/v2.1/releases/206.md deleted file mode 100644 index 439798282357..000000000000 --- a/v2.1/releases/206.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB 2.0.6 release notes -category: Releases ---- - -# TiDB 2.0.6 Release Notes - -2018 年 8 月 6 日，TiDB 发布 2.0.6 版。该版本在 2.0.5 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- Improvements - - 精简 "set system variable" 日志的长度，减少日志文件体积 [#7031](https://github.com/pingcap/tidb/pull/7031) - - 在日志中记录 `ADD INDEX` 执行过程中的慢操作，便于定位问题 [#7083](https://github.com/pingcap/tidb/pull/7083) - - 减少更新统计信息操作中的事务冲突 [#7138](https://github.com/pingcap/tidb/pull/7138) - - 当待估算的值超过统计信息范围时，提高行数估计的准确度 [#7185](https://github.com/pingcap/tidb/pull/7185) - - 当使用 `Index Join` 时，选择行数估计较小的表作为驱动表，提高 `Index Join` 的执行效率 [#7227](https://github.com/pingcap/tidb/pull/7227) - - 为 `ANALYZE TABLE` 语句执行过程中发生的 panic 添加 recover 机制，避免收集统计信息过程中的异常行为导致 tidb-server 不可用 [#7228](https://github.com/pingcap/tidb/pull/7228) - - 当 `RPAD`/`LPAD` 的结果超过设置系统变量 `max_allowed_packet` 时，返回 `NULL` 和对应的 warning，兼容 MySQL [#7244](https://github.com/pingcap/tidb/pull/7244) - - 设置 `PREPARE` 语句中占位符数量上限为 65535，兼容 MySQL [#7250](https://github.com/pingcap/tidb/pull/7250) -- Bug Fixes - - 修复某些情况下，`DROP USER` 语句和 MySQL 行为不兼容的问题 [#7014](https://github.com/pingcap/tidb/pull/7014) - - 修复当 `tidb_batch_insert` 打开后，`INSERT`/`LOAD DATA` 等语句在某些场景下 OOM 的问题 [#7092](https://github.com/pingcap/tidb/pull/7092) - - 修复某个表的数据持续更新时，其统计信息自动更新失效的问题 [#7093](https://github.com/pingcap/tidb/pull/7093) - - 修复防火墙断掉不活跃的 gRPC 连接的问题 [#7099](https://github.com/pingcap/tidb/pull/7099) - - 修复某些场景下使用前缀索引结果不正确的问题 [#7126](https://github.com/pingcap/tidb/pull/7126) - - 修复某些场景下统计信息过时导致 panic 的问题 [#7155](https://github.com/pingcap/tidb/pull/7155) - - 修复某些场景下 `ADD INDEX` 后索引数据少一条的问题 [#7156](https://github.com/pingcap/tidb/pull/7156) - - 修复某些场景下查询唯一索引上的 `NULL` 值结果不正确的问题 [#7172](https://github.com/pingcap/tidb/pull/7172) - - 修复某些场景下 `DECIMAL` 的乘法结果出现乱码的问题 [#7212](https://github.com/pingcap/tidb/pull/7212) - - 修复某些场景下 `DECIMAL` 的取模运算结果不正确的问题 [#7245](https://github.com/pingcap/tidb/pull/7245) - - 修复某些特殊语句序列下在事务中执行 `UPDATE`/`DELETE` 语句后结果不正确的问题 [#7219](https://github.com/pingcap/tidb/pull/7219) - - 修复某些场景下 `UNION ALL`/`UPDATE` 语句在构造执行计划过程中 panic 的问题 [#7225](https://github.com/pingcap/tidb/pull/7225) - - 修复某些场景下前缀索引的索引范围计算错误的问题 [#7231](https://github.com/pingcap/tidb/pull/7231) - - 修复某些场景下 `LOAD DATA` 语句不写 binlog 的问题 [#7242](https://github.com/pingcap/tidb/pull/7242) - - 修复某些场景下在 `ADD INDEX` 过程中 `SHOW CREATE TABLE` 结果不正确的问题 [#7243](https://github.com/pingcap/tidb/pull/7243) - - 修复某些场景下 `Index Join` 因为没有初始化事务时间戳而 panic 的问题 [#7246](https://github.com/pingcap/tidb/pull/7246) - - 修复 `ADMIN CHECK TABLE` 因为误用 session 中的时区而导致误报的问题 [#7258](https://github.com/pingcap/tidb/pull/7258) - - 修复 `ADMIN CLEANUP INDEX` 在某些场景下索引没有清除干净的问题 [#7265](https://github.com/pingcap/tidb/pull/7265) - - 禁用 Read Committed 事务隔离级别 [#7282](https://github.com/pingcap/tidb/pull/7282) - -## TiKV - -- Improvements - - 扩大默认 scheduler slots 值以减少假冲突现象 - - 减少回滚事务的连续标记以提升冲突极端严重下的读性能 - - 限制 RocksDB log 文件的大小和个数以减少长时间运行下不必要的磁盘占用 -- Bug Fixes - - 修复字符串转 Decimal 时出现的 crash \ No newline at end of file diff --git a/v2.1/releases/207.md b/v2.1/releases/207.md deleted file mode 100644 index 82cba1593466..000000000000 --- a/v2.1/releases/207.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: TiDB 2.0.7 release notes -category: Releases ---- - -# TiDB 2.0.7 Release Notes - -2018 年 9 月 7 日，TiDB 发布 2.0.7 版。该版本在 2.0.6 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- New Feature - - 在 `information_schema` 里添加 `PROCESSLIST` 表 [#7286](https://github.com/pingcap/tidb/pull/7286) -- Improvements - - 收集更多语句执行细节，并输出在 `SLOW QUERY` 日志里 [#7364](https://github.com/pingcap/tidb/pull/7364) - - `SHOW CREATE TABLE` 不再输出分区信息 [#7388](https://github.com/pingcap/tidb/pull/7388) - - 通过设置 RC 隔离级别和低优先级优化 `ANALYZE` 语句执行效率 [#7500](https://github.com/pingcap/tidb/pull/7500) - - 加速 `ADD UNIQUE INDEX` [#7562](https://github.com/pingcap/tidb/pull/7562) - - 增加控制 DDL 并发度的选项 [#7563](https://github.com/pingcap/tidb/pull/7563) -- Bug Fixes - - 修复 `PRIMARY KEY` 为整数的表，无法使用 `USE INDEX(PRIMARY)` 的问题 [#7298](https://github.com/pingcap/tidb/pull/7298) - - 修复 `Merge Join` 和 `Index Join` 在 inner row 为 `NULL` 时输出多余结果的问题 [#7301](https://github.com/pingcap/tidb/pull/7301) - - 修复 chunk size 设置过小时，`Join` 输出多余结果的问题 [#7315](https://github.com/pingcap/tidb/pull/7315) - - 修复建表语句中包含 `range column` 语法导致 panic 的问题 [#7379](https://github.com/pingcap/tidb/pull/7379) - - 修复 `admin check table` 对时间类型的列误报的问题 [#7457](https://github.com/pingcap/tidb/pull/7457) - - 修复以默认值 `current_timestamp` 插入的数据无法用 `=` 条件查询到的问题 [#7467](https://github.com/pingcap/tidb/pull/7467) - - 修复以 `ComStmtSendLongData` 命令插入空字符串参数被误解析为 `NULL` 的问题 [#7508](https://github.com/pingcap/tidb/pull/7508) - - 修复特定场景下 `auto analyze` 不断重复执行的问题 [#7556](https://github.com/pingcap/tidb/pull/7556) - - 修复 parser 无法解析以换行符结尾的单行注释的问题 [#7635](https://github.com/pingcap/tidb/pull/7635) - -## TiKV - -- Improvement - - 空集群默认打开 `dynamic-level-bytes` 参数减少空间放大 -- Bug Fix - - 在 Region merge 之后更新 Region 的 `approximate size` 和 keys \ No newline at end of file diff --git a/v2.1/releases/208.md b/v2.1/releases/208.md deleted file mode 100644 index 1e1e1791c1d1..000000000000 --- a/v2.1/releases/208.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB 2.0.8 release notes -category: Releases ---- - -# TiDB 2.0.8 Release Notes - -2018 年 10 月 16 日，TiDB 发布 2.0.8 版。该版本在 2.0.7 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -+ 功能改进 - - 在 `Update` 没有更改相应 AUTO-INCREMENT 列情况下，防止 AUTO-ID 被消耗过快 [#7846](https://github.com/pingcap/tidb/pull/7846) -+ Bug 修复 - - 在 PD Leader 异常宕机的情况下，TiDB 快速创建 etcd Session 恢复服务 [#7810](https://github.com/pingcap/tidb/pull/7810) - - 修复 `DateTime` 类型使用默认值时候没有考虑时区的问题 [#7672](https://github.com/pingcap/tidb/pull/7672) - - 修复 `duplicate key update` 在某些情况下没有正确插入值的问题 [#7685](https://github.com/pingcap/tidb/pull/7685) - - 修复 `UnionScan` 中谓词条件没有下推的问题 [#7726](https://github.com/pingcap/tidb/pull/7726) - - 修复增加 `TIMESTAMP` 索引没有正确处理时区的问题 [#7812](https://github.com/pingcap/tidb/pull/7812) - - 修复某些情况下统计信息模块导致的内存泄露问题 [#7864](https://github.com/pingcap/tidb/pull/7864) - - 修复在某些异常情况下，无法获得 `ANALYZE` 结果的问题 [#7871](https://github.com/pingcap/tidb/pull/7871) - - 令 `SYSDATE` 不做表达式展开，以返回正确的结果 [#7894](https://github.com/pingcap/tidb/pull/7894) - - 修复某些情况下，`substring_index` panic 的问题 [#7896](https://github.com/pingcap/tidb/pull/7896) - - 修复某些情况下，错误将 `OUTER JOIN` 转为 `INNER JOIN` 的问题 [#7899](https://github.com/pingcap/tidb/pull/7899) - -## TiKV - -+ Bug 修复 - - 修复节点宕机时 Raftstore `EntryCache` 占用内存持续上升的问题 [#3529](https://github.com/tikv/tikv/pull/3529) \ No newline at end of file diff --git a/v2.1/releases/209.md b/v2.1/releases/209.md deleted file mode 100644 index 430587a019a9..000000000000 --- a/v2.1/releases/209.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: TiDB 2.0.9 Release Notes -category: Releases ---- - -# TiDB 2.0.9 Release Notes - -2018 年 11 月 19 日，TiDB 发布 2.0.9 版。该版本在 2.0.8 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复统计信息直方图为空的时候导致的问题 [#7927](https://github.com/pingcap/tidb/pull/7927) -- 修复 `UNION ALL` 语句在某些情况下 panic 的问题 [#7942](https://github.com/pingcap/tidb/pull/7942) -- 修复错误的 DDL JOB 情况下导致的递归溢出问题 [#7959](https://github.com/pingcap/tidb/pull/7959) -- 为 `Commit` 操作加上慢操作日志 [#7983](https://github.com/pingcap/tidb/pull/7983) -- 修复 `Limit` 值太大的情况下导致的 panic 问题 [#8004](https://github.com/pingcap/tidb/pull/8004) -- 支持 `USING` 子句指定 `utf8mb4` 字符集 [#8048](https://github.com/pingcap/tidb/pull/8048) -- 内建函数 `TRUNCATE` 支持类型为 unsigned int 的参数 [#8069](https://github.com/pingcap/tidb/pull/8069) -- 修复统计信息模块在某些情况下主键选择率估算的问题 [#8150](https://github.com/pingcap/tidb/pull/8150) -- 增加 `Session` 变量来控制是否允许写入 `_tidb_rowid` [#8126](https://github.com/pingcap/tidb/pull/8126) -- 修复 `PhysicalProjection` 在某些情况下 panic 的问题 [#8154](https://github.com/pingcap/tidb/pull/8154) -- 修复 `Union` 语句在某些情况下结果不稳定的问题 [#8168](https://github.com/pingcap/tidb/pull/8168) -- 修复在非插入语句下 `values` 没有返回 `NULL` 的问题 [#8179](https://github.com/pingcap/tidb/pull/8179) -- 修复某些情况下统计信息模块无法清除过期统计数据的问题 [#8184](https://github.com/pingcap/tidb/pull/8184) -- 让事务允许的最长运行时间变成一个可配置项 [#8209](https://github.com/pingcap/tidb/pull/8209) -- 修复 `expression rewriter` 某些情况下错误的比较逻辑 [#8288](https://github.com/pingcap/tidb/pull/8288) -- 消除 `UNION ORDER BY` 语句生成的多余列的问题 [#8307](https://github.com/pingcap/tidb/pull/8307) -- 支持 `admin show next_row_id` 语句 [#8274](https://github.com/pingcap/tidb/pull/8274) -- 修复 `Show Create Table` 语句中特殊字符转义的问题 [#8321](https://github.com/pingcap/tidb/pull/8321) -- 修复 `UNION` 语句在某些情况下遇到非预期错误的问题 [#8318](https://github.com/pingcap/tidb/pull/8318) -- 修复某些情况下取消 DDL 任务导致的 Schema 没有回滚的问题 [#8312](https://github.com/pingcap/tidb/pull/8312) -- 把变量 `tidb_max_chunk_size` 变成全局环境变量 [#8333](https://github.com/pingcap/tidb/pull/8333) -- ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8309](https://github.com/pingcap/tidb/pull/8309) [#8310](https://github.com/pingcap/tidb/pull/8310) - -## PD - -- 修复 etcd 启动失败导致的服务挂起问题 [#1267](https://github.com/pingcap/pd/pull/1267) -- 修复 `pd-ctl` 读取 Region key 的相关问题 [#1298](https://github.com/pingcap/pd/pull/1298) [#1299](https://github.com/pingcap/pd/pull/1299) [#1308](https://github.com/pingcap/pd/pull/1308) -- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -- 修复 PD join 失败后无法重新 join 的问题 [1279](https://github.com/pingcap/pd/pull/1279) - -## TiKV - -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) -- 废弃配置 `max-tasks-xxx` 并新增 `max-tasks-per-worker-xxx` [#3093](https://github.com/tikv/tikv/pull/3093) -- 修复 RocksDB `CompactFiles` 的问题 [#3789](https://github.com/tikv/tikv/pull/3789) \ No newline at end of file diff --git a/v2.1/releases/21beta.md b/v2.1/releases/21beta.md deleted file mode 100644 index 18cafa4e0de7..000000000000 --- a/v2.1/releases/21beta.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: TiDB 2.1 Beta Release Notes -category: Releases ---- - -# TiDB 2.1 Beta Release Notes - -2018 年 6 月 29 日，TiDB 发布 2.1 Beta 版。相比 2.0 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 优化 `Index Join` 选择范围，提升执行性能 - - 优化关联子查询，下推 Filter 和扩大索引选择范围，部分查询的效率有数量级的提升 - - 在 `UPDATE`、`DELETE` 语句中支持 `Index Hint` 和 `Join Hint` - - 优化器 Hint `TIDM_SMJ` 在没有索引可用的情况下可生效 - - 支持更多函数下推：`ABS`/`CEIL`/`FLOOR`/`IS TRUE`/`IS FALSE` - - 在常量折叠过程中特殊处理函数 `IF` 和 `IFNULL` - - 优化 `EXPLAIN` 语句输出格式 -- SQL 执行引擎 - - 实现并行 `Hash Aggregate` 算子，部分场景下能提高 `Hash Aggregate` 计算性能 350% - - 实现并行 `Project` 算子，部分场景下性能提升达 74% - - 并发地读取 `Hash Join` 的 `Inner` 表和 `Outer` 表的数据，提升执行性能 - - 修复部分场景下 `INSERT … ON DUPLICATE KEY UPDATE …` 结果不正确的问题 - - 修复 `CONCAT_WS`/`FLOOR`/`CEIL`/`DIV` 内建函数的结果不正确的问题 -- Server - - 添加 HTTP API 打散 table 的 Regions 在 TiKV 集群中的分布 - - 添加 `auto_analyze_ratio` 系统变量控制自动 analyze 的阈值 - - 添加 HTTP API 控制是否打开 `general log` - - 添加 HTTP API 在线修改日志级别 - - 在 `general log` 和 `slow query log` 中添加 user 信息 - - 支持 Server side cursor -- 兼容性 - - 支持更多 MySQL 语法 - - `BIT` 聚合函数支持 `ALL` 参数 - - 支持 `SHOW PRIVILEGES` 语句 -- DML - - 减少 `INSERT INTO SELECT` 语句的内存占用 - - 修复 Plan Cache 的性能问题 - - 添加 `tidb_retry_limit` 系统变量控制事务自动重试的次数 - - 添加 `tidb_disable_txn_auto_retry` 系统变量控制事务是否自动重试 - - 修复写入 `time` 类型的数据精度问题 - - 支持本地冲突事务排队，优化冲突事务性能 - - 修复 `UPDATE` 语句的 `Affected Rows` - - 优化 `insert ignore on duplicate key update` 语句性能 - - 优化 `Create Table` 语句的执行速度 - - 优化 `Add index` 的速度，在某些场景下速度大幅提升 - - 修复 `Alter table add column` 增加列超过表的列数限制的问题 - - 修复在某些异常情况下 DDL 任务重试导致 TiKV 压力增加的问题 - - 修复在某些异常情况下 TiDB 不断重载 Schema 信息的问题 -- DDL - - `Show Create Table` 不再输出外键相关的内容 - - 支持 `select tidb_is_ddl_owner()` 语句，方便判断 TiDB 是否为 `DDL Owner` - - 修复某些场景下 `YEAR` 类型删除索引的问题 - - 修复并发执行场景下的 `Rename table` 的问题 - - 支持 `ALTER TABLE FORCE` 语法 - - 支持 `ALTER TABLE RENAME KEY TO` 语法 - - `admin show ddl jobs` 输出信息中添加表名、库名等信息 - -## PD - -- PD 节点间开启 `Raft PreVote`，避免网络隔离后恢复时产生的重新选举 -- 优化 Balance Scheduler 频繁调度小 Region 的问题 -- 优化热点调度器，在流量统计信息抖动时适应性更好 -- `region merge` 调度时跳过数据行数较多的 Region -- 默认开启 `raft learner` 功能，降低调度时出现宕机导致数据不可用的风险 -- `pd-recover` 移除 max-replica 参数 -- 增加 `Filter` 相关的 metrics -- 修复 tikv-ctl unsafe recovery 之后 Region 信息没更新的问题 -- 修复某些场景下副本迁移导致 TiKV 磁盘空间耗尽的问题 -- 兼容性提示 - - 由于新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 - - 新版本默认开启 `raft learner` 功能，如果从 1.x 版本集群升级至 2.1 版本，须停机升级或者先滚动升级 TiKV，完成后再滚动升级 PD - -## TiKV - -- 升级 Rust 到 `nightly-2018-06-14` 版本 -- 开启 `PreVote`，避免网络隔离后恢复时产生的重新选举 -- 添加 metric，显示 RocksDB 内部每层的文件数和 `ingest` 相关的信息 -- GC 运行时打印版本太多的 `key` -- 使用 `static metric` 优化多 label metric 性能（YCSB raw get 提升 3%） -- 去掉多个模块的 `box`，使用范型提升运行时性能（YCSB raw get 提升 3%） -- 使用 `asynchronous log` 提升写日志性能 -- 增加收集线程状态的 metric -- 通过减少程序中 `box` 的使用来减少内存拷贝的次数，提升性能 diff --git a/v2.1/releases/21rc1.md b/v2.1/releases/21rc1.md deleted file mode 100644 index 669d1b947536..000000000000 --- a/v2.1/releases/21rc1.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: TiDB 2.1 RC1 Release Notes -category: Releases ---- - -# TiDB 2.1 RC1 Release Notes - -2018 年 8 月 24 日，TiDB 发布 2.1 RC1 版。相比 2.1 Beta 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 修复某些情况下关联子查询去关联后结果不正确的问题 [#6972](https://github.com/pingcap/tidb/pull/6972) - - 优化 `Explain` 输出结果 [#7011](https://github.com/pingcap/tidb/pull/7011)[#7041](https://github.com/pingcap/tidb/pull/7041) - - 优化 `IndexJoin` 驱动表选择策略[#7019](https://github.com/pingcap/tidb/pull/7019) - - 去掉非 `PREPARE` 语句的 Plan Cache [#7040](https://github.com/pingcap/tidb/pull/7040) - - 修复某些情况下 `INSERT` 语句无法正常解析执行的问题 [#7068](https://github.com/pingcap/tidb/pull/7068) - - 修复某些情况下 `IndexJoin` 结果不正确的问题 [#7150](https://github.com/pingcap/tidb/pull/7150) - - 修复某些情况下使用唯一索引不能查询到 `NULL` 值的问题 [#7163](https://github.com/pingcap/tidb/pull/7163) - - 修复 UTF-8 编码情况下前缀索引的范围计算不正确的问题 [#7194](https://github.com/pingcap/tidb/pull/7194) - - 修复某些情况下 `Project` 算子消除导致的结果不正确的问题 [#7257](https://github.com/pingcap/tidb/pull/7257) - - 修复主键为整数类型时无法使用 `USE INDEX(PRIMARY)` 的问题 [#7316](https://github.com/pingcap/tidb/pull/7316) - - 修复某些情况下使用关联列无法计算索引范围的问题 [#7357](https://github.com/pingcap/tidb/pull/7357) -- SQL 执行引擎 - - 修复某些情况下夏令时时间计算结果不正确的问题 [#6823](https://github.com/pingcap/tidb/pull/6823) - - 重构聚合函数框架，提升 `Stream` 和 `Hash` 聚合算子的执行效率 [#6852](https://github.com/pingcap/tidb/pull/6852) - - 修复某些情况下 `Hash` 聚合算子不能正常退出的问题 [#6982](https://github.com/pingcap/tidb/pull/6982) - - 修复 `BIT_AND`/`BIT_OR`/`BIT_XOR` 没有正确处理非整型数据的问题 [#6994](https://github.com/pingcap/tidb/pull/6994) - - 优化 `REPLACE INTO` 语句的执行速度，性能提升近 10 倍 [#7027](https://github.com/pingcap/tidb/pull/7027) - - 优化时间类型的内存占用，时间类型数据的内存使用降低为原来的一半 [#7043](https://github.com/pingcap/tidb/pull/7043) - - 修复 `UNION` 语句整合有符号和无符号型整数结果时与 MySQL 不兼容的问题 [#7112](https://github.com/pingcap/tidb/pull/7112) - - 修复 `LPAD`/`RPAD`/`TO_BASE64`/`FROM_BASE64`/`REPEAT` 因为申请过多内存导致 TiDB panic 的问题 [#7171](https://github.com/pingcap/tidb/pull/7171) [#7266](https://github.com/pingcap/tidb/pull/7266) [#7409](https://github.com/pingcap/tidb/pull/7409) [#7431](https://github.com/pingcap/tidb/pull/7431) - - 修复 `MergeJoin`/`IndexJoin` 在处理 `NULL` 值时结果不正确的问题 [#7255](https://github.com/pingcap/tidb/pull/7255) - - 修复某些情况下 Outer Join 结果不正确的问题 [#7288](https://github.com/pingcap/tidb/pull/7288) - - 增强 `Data Truncated` 的报错信息，便于定位出错的数据和表中对应的字段 [#7401](https://github.com/pingcap/tidb/pull/7401) - - 修复某些情况下 Decimal 计算结果不正确的问题 [#7001](https://github.com/pingcap/tidb/pull/7001) [#7113](https://github.com/pingcap/tidb/pull/7113) [#7202](https://github.com/pingcap/tidb/pull/7202) [#7208](https://github.com/pingcap/tidb/pull/7208) - - 优化点查的查询性能 [#6937](https://github.com/pingcap/tidb/pull/6937) - - 禁用 `Read Committed` 隔离级别，避免潜在的问题 [#7211](https://github.com/pingcap/tidb/pull/7211) - - 修复某些情况下 `LTRIM`/`RTRIM`/`TRIM` 结果不正确的问题 [#7291](https://github.com/pingcap/tidb/pull/7291) - - 修复 `MaxOneRow` 算子无法保证返回结果不超过 1 行的问题 [#7375](https://github.com/pingcap/tidb/pull/7375) - - 拆分 range 个数过多的 Coprocessor 请求 [#7454](https://github.com/pingcap/tidb/pull/7454) -- 统计信息 - - 优化统计信息动态收集机制 [#6796](https://github.com/pingcap/tidb/pull/6796) - - 解决数据频繁更新场景下 `Auto Analyze` 不工作的问题 [#7022](https://github.com/pingcap/tidb/pull/7022) - - 减少统计信息动态更新过程中的写入冲突 [#7124](https://github.com/pingcap/tidb/pull/7124) - - 优化统计信息不准确情况下的代价估算 [#7175](https://github.com/pingcap/tidb/pull/7175) - - 优化 `AccessPath` 的代价估算策略 [#7233](https://github.com/pingcap/tidb/pull/7233) -- Server - - 修复加载权限信息时的 bug [#6976](https://github.com/pingcap/tidb/pull/6976) - - 修复 `Kill` 命令对权限的检查过严问题 [#6954](https://github.com/pingcap/tidb/pull/6954) - - 解决 Binary 协议中某些数值类型移除的问题 [#6922](https://github.com/pingcap/tidb/pull/6922) - - 精简日志输出 [#7029](https://github.com/pingcap/tidb/pull/7029) - - 处理 `mismatchClusterID` 问题 [#7053](https://github.com/pingcap/tidb/pull/7053) - - 增加 `advertise-address` 配置项 [#7078](https://github.com/pingcap/tidb/pull/7078) - - 增加 `GrpcKeepAlive` 选项 [#7100](https://github.com/pingcap/tidb/pull/7100) - - 增加连接或者 `Token` 时间监控 [#7110](https://github.com/pingcap/tidb/pull/7110) - - 优化数据解码性能 [#7149](https://github.com/pingcap/tidb/pull/7149) - - `INFORMMATION_SCHEMA` 中增加 `PROCESSLIST` 表 [#7236](https://github.com/pingcap/tidb/pull/7236) - - 解决权限验证时多条规则可以命中情况下的顺序问题 [#7211](https://github.com/pingcap/tidb/pull/7211) - - 将部分编码相关的系统变量默认值改为 UTF-8 [#7198](https://github.com/pingcap/tidb/pull/7198) - - 慢查询日志显示更详细的信息 [#7302](https://github.com/pingcap/tidb/pull/7302) - - 支持在 PD 注册 tidb-server 的相关信息并通过 HTTP API 获取 [#7082](https://github.com/pingcap/tidb/pull/7082) -- 兼容性 - - 支持 `Session` 变量 `warning_count` 和 `error_count` [#6945](https://github.com/pingcap/tidb/pull/6945) - - 读取系统变量时增加 Scope 检查 [#6958](https://github.com/pingcap/tidb/pull/6958) - - 支持 `MAX_EXECUTION_TIME` 语法 [#7012](https://github.com/pingcap/tidb/pull/7012) - - 支持更多的 `SET` 语法 [#7020](https://github.com/pingcap/tidb/pull/7020) - - Set 系统变量值过程中增加合法性校验 [#7117](https://github.com/pingcap/tidb/pull/7117) - - 增加 `Prepare` 语句中 `PlaceHolder` 数量的校验 [#7162](https://github.com/pingcap/tidb/pull/7162) - - 支持 `set character_set_results = null` [#7353](https://github.com/pingcap/tidb/pull/7353) - - 支持 `flush status` 语法 [#7369](https://github.com/pingcap/tidb/pull/7369) - - 修复 `SET` 和 `ENUM` 类型在 `information_schema` 里的 column size [#7347](https://github.com/pingcap/tidb/pull/7347) - - 支持建表语句里的 `NATIONAL CHARACTER` 语法 [#7378](https://github.com/pingcap/tidb/pull/7378) - - 支持 `LOAD DATA` 语句的 `CHARACTER SET` 语法 [#7391](https://github.com/pingcap/tidb/pull/7391) - - 修复 `SET` 和 `ENUM `类型的 column info [#7417](https://github.com/pingcap/tidb/pull/7417) - - 支持 `CREATE USER` 语句的 `IDENTIFIED WITH` 语法 [#7402](https://github.com/pingcap/tidb/pull/7402) - - 修复 `TIMESTAMP` 类型计算过程中丢失精度的问题 [#7418](https://github.com/pingcap/tidb/pull/7418) - - 支持更多 `SYSTEM` 变量的合法性验证 [#7196](https://github.com/pingcap/tidb/pull/7196) - - 修复 `CHAR_LENGTH` 函数在计算 binary string 时结果不正确的问题 [#7410](https://github.com/pingcap/tidb/pull/7410) - - 修复在包含 `GROUP BY` 的语句里 `CONCAT` 结果不正确的问题 [#7448](https://github.com/pingcap/tidb/pull/7448) - - 修复 `DECIMAL` 类型 CAST 到 `STRING` 类型时，类型长度不准确的问题 [#7451](https://github.com/pingcap/tidb/pull/7451) -- DML - - 解决 `Load Data` 语句的稳定性 [#6927](https://github.com/pingcap/tidb/pull/6927) - - 解决一些 `Batch` 操作情况下的内存使用问题 [#7086](https://github.com/pingcap/tidb/pull/7086) - - 提升 `Replace Into` 语句的性能 [#7027](https://github.com/pingcap/tidb/pull/7027) - - 修复写入 `CURRENT_TIMESTAMP` 时，精度不一致的问题 [#7355](https://github.com/pingcap/tidb/pull/7355) -- DDL - - 改进 DDL 判断 `Schema` 是否已经同步的方法, 避免某些情况下的误判 [#7319](https://github.com/pingcap/tidb/pull/7319) - - 修复在 `ADD INDEX` 过程中的 `SHOW CREATE TABLE` 结果 [#6993](https://github.com/pingcap/tidb/pull/6993) - - 非严格 `sql-mode` 模式下, `text`/`blob`/`json` 的默认值可以为空 [#7230](https://github.com/pingcap/tidb/pull/7230) - - 修复某些特定场景下 `ADD INDEX` 的问题 [#7142](https://github.com/pingcap/tidb/pull/7142) - - 大幅度提升添加 `UNIQUE-KEY` 索引操作的速度 [#7132](https://github.com/pingcap/tidb/pull/7132) - - 修复 Prefix-index 在 UTF-8 字符集的场景下的截断问题 [#7109](https://github.com/pingcap/tidb/pull/7109) - - 增加环境变量 `tidb_ddl_reorg_priority` 来控制 `add-index` 操作的优先级 [#7116](https://github.com/pingcap/tidb/pull/7116) - - 修复 `information_schema.tables` 中 `AUTO-INCREMENT` 的显示问题 [#7037](https://github.com/pingcap/tidb/pull/7037) - - 支持 `admin show ddl jobs ` 命令, 支持输出 number 个 DDL jobs [#7028](https://github.com/pingcap/tidb/pull/7028) - - 支持并行 DDL 任务执行 [#6955](https://github.com/pingcap/tidb/pull/6955) -- [Table Partition](https://github.com/pingcap/tidb/projects/6)（实验性） - - 支持一级分区 - - 支持 `Range Partition` - -## PD - -- 新特性 - - 引入版本控制机制，支持集群滚动兼容升级 - - 开启 `Region merge` 功能 - - 支持 `GetPrevRegion` 接口 - - 支持批量 `split Region` - - 支持存储 GC safepoint -- 功能改进 - - 优化系统时间回退影响 TSO 分配的问题 - - 优化处理 Region heartbeat 的性能 - - 优化 Region tree 性能 - - 优化计算热点统计的性能问题 - - 优化 API 接口错误码返回 - - 新增一些控制调度策略的开关 - - 禁止在 `label` 中使用特殊字符 - - 完善调度模拟器 - - pd-ctl 支持使用统计信息进行 Region split - - pd-ctl 支持调用 `jq` 来格式化 JSON 输出 - - 新增 etcd Raft 状态机相关 metrics -- Bug 修复 - - 修复 leader 切换后 namespace 未重新加载的问题 - - 修复 namespace 调度超出 schedule limit 配置的问题 - - 修复热点调度超出 schedule limit 的问题 - - 修复 PD client 关闭时输出一些错误日志的问题 - - 修复 Region 心跳延迟统计有误的问题 - -## TiKV - -- 新特性 - - 支持 `batch split`，防止热点 Region 写入产生超大 Region - - 支持设置根据数据行数 split Region，提升 index scan 效率 -- 性能优化 - - 使用 `LocalReader` 将 Read 操作从 raftstore 线程分离，减少 Read 延迟 - - 重构 MVCC 框架，优化 memory 使用，提升 scan read 性能 - - 支持基于统计估算进行 Region split，减少 I/O 开销 - - 优化连续写入 Rollback 记录后影响读性能的问题 - - 减少下推聚合计算的内存开销 -- 功能改进 - - 增加大量内建函数下推支持，更完善的 charset 支持 - - 优化 GC 流程，提升 GC 速度并降低 GC 对系统的影响 - - 开启 `prevote`，加快网络异常时的恢复服务速度 - - 增加 RocksDB 日志文件相关的配置项 - - 调整 `scheduler latch` 默认配置 - - 使用 tikv-ctl 手动 compact 时可设定是否 compact RocksDB 最底层数据 - - 增加启动时的环境变量检查 - - 支持基于已有数据动态设置 `dynamic_level_bytes` 参数 - - 支持自定义日志格式 - - tikv-ctl 整合 tikv-fail 工具 - - 增加 threads IO metrics -- Bug 修复 - - 修复 decimal 相关问题 - - 修复 `gRPC max_send_message_len` 设置有误的问题 - - 修复 `region_size` 配置不当时产生的问题 diff --git a/v2.1/releases/21rc2.md b/v2.1/releases/21rc2.md deleted file mode 100644 index 426e4289e60d..000000000000 --- a/v2.1/releases/21rc2.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: TiDB 2.1 RC2 Release Notes -category: Releases ---- - -# TiDB 2.1 RC2 Release Notes - -2018 年 9 月 14 日，TiDB 发布 2.1 RC2 版。相比 2.1 RC1 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 新版 Planner 设计方案 [#7543](https://github.com/pingcap/tidb/pull/7543) - - 提升常量传播优化规则 [#7276](https://github.com/pingcap/tidb/pull/7276) - - 增强 Range 的计算逻辑使其能够同时处理多个 `IN` 或者等值条件 [#7577](https://github.com/pingcap/tidb/pull/7577) - - 修复当 Range 为空时，`TableScan` 的估算结果不正确的问题 [#7583](https://github.com/pingcap/tidb/pull/7583) - - 为 `UPDATE` 语句支持 `PointGet` 算子 [#7586](https://github.com/pingcap/tidb/pull/7586) - - 修复 `FirstRow` 聚合函数某些情况下在执行过程中 panic 的问题 [#7624](https://github.com/pingcap/tidb/pull/7624) -- SQL 执行引擎 - - 解决 HashJoin 算子在遇到错误的情况下潜在的 DataRace 问题 [#7554](https://github.com/pingcap/tidb/pull/7554) - - HashJoin 算子同时读取内表数据和构建 Hash 表 [#7544](https://github.com/pingcap/tidb/pull/7544) - - 优化 Hash 聚合算子性能 [#7541](https://github.com/pingcap/tidb/pull/7541) - - 优化 Join 算子性能 [#7493](https://github.com/pingcap/tidb/pull/7493)、[#7433](https://github.com/pingcap/tidb/pull/7433) - - 修复 `UPDATE JOIN` 在 Join 顺序改变后结果不正确的问题 [#7571](https://github.com/pingcap/tidb/pull/7571) - - 提升 Chunk 迭代器的性能 [#7585](https://github.com/pingcap/tidb/pull/7585) -- 统计信息 - - 解决重复自动 Analyze 统计信息的问题 [#7550](https://github.com/pingcap/tidb/pull/7550) - - 解决统计信息无变化时更新统计信息遇到错误的问题 [#7530](https://github.com/pingcap/tidb/pull/7530) - - `Analyze` 执行时使用低优先级以及 RC 隔离级别 [#7496](https://github.com/pingcap/tidb/pull/7496) - - 支持只在一天中的某个时间段开启统计信息自动更新的功能 [#7570](https://github.com/pingcap/tidb/pull/7570) - - 修复统计信息写日志时发生的 panic [#7588](https://github.com/pingcap/tidb/pull/7588) - - 支持通过 `ANALYZE TABLE WITH BUCKETS` 语句配置直方图中桶的个数 [#7619](https://github.com/pingcap/tidb/pull/7619) - - 修复更新空的直方图时 panic 的问题 [#7640](https://github.com/pingcap/tidb/pull/7640) - - 使用统计信息更新 `information_schema.tables.data_length` [#7657](https://github.com/pingcap/tidb/pull/7657) -- Server - - 增加 Trace 相关的依赖库 [#7532](https://github.com/pingcap/tidb/pull/7532) - - 开启 Golang 的 mutex profile 功能 [#7512](https://github.com/pingcap/tidb/pull/7512) - - `Admin` 语句需要 `Super_priv` 权限 [#7486](https://github.com/pingcap/tidb/pull/7486) - - 禁止用户 Drop 关键的系统表 [#7471](https://github.com/pingcap/tidb/pull/7471) - - 从 `juju/errors` 切换到 `pkg/errors` [#7151](https://github.com/pingcap/tidb/pull/7151) - - 完成 SQL Tracing 功能原型 [#7016](https://github.com/pingcap/tidb/pull/7016) - - 删除 goroutine pool [#7564](https://github.com/pingcap/tidb/pull/7564) - - 支持使用 `USER1` 信号来查看 goroutine 信息 [#7587](https://github.com/pingcap/tidb/pull/7587) - - 将 TiDB 启动时的内部 SQL 设置为高优先级 [#7616](https://github.com/pingcap/tidb/pull/7616) - - 在监控中用不同的标签区分内部 SQL 和用户 SQL [#7631](https://github.com/pingcap/tidb/pull/7631) - - 缓存最近一周内最慢的 30 条慢查询日志在 TiDB Server 上 [#7646](https://github.com/pingcap/tidb/pull/7646) - - TiDB 集群设置时区的方案 [#7656](https://github.com/pingcap/tidb/pull/7656) - - 丰富 `GC life time is shorter than transaction duration` 错误信息 [#7658](https://github.com/pingcap/tidb/pull/7658) - - 在 TiDB 集群启动时设置集群时区信息 [#7638](https://github.com/pingcap/tidb/pull/7638) -- 兼容性 - - `Year` 类型字段增加 unsigned flag [#7542](https://github.com/pingcap/tidb/pull/7542) - - 修复在 Prepare/Execute 模式下，`Year` 类型结果长度设置问题 [#7525](https://github.com/pingcap/tidb/pull/7525) - - 修复 Prepare/Execute 模式下时间 0 值的处理问题 [#7506](https://github.com/pingcap/tidb/pull/7506) - - 解决整数类型除法实现中的错误处理问题 [#7492](https://github.com/pingcap/tidb/pull/7492) - - 解决 `ComStmtSendLongData` 处理过程中的兼容性问题 [#7485](https://github.com/pingcap/tidb/pull/7485) - - 解决字符串转为整数类型过程中的错误处理问题 [#7483](https://github.com/pingcap/tidb/pull/7483) - - 优化 `information_schema.columns_in_table` 表中的值精度 [#7463](https://github.com/pingcap/tidb/pull/7463) - - 修复使用 MariaDB 客户端对字符串类型数据的写入和更新的兼容性问题 [#7573](https://github.com/pingcap/tidb/pull/7573) - - 修复返回值别名的兼容性问题 [#7600](https://github.com/pingcap/tidb/pull/7600) - - 修复 `information_schema.COLUMNS` 表中浮点数的 `NUMERIC_SCALE` 值不正确的问题 [#7602](https://github.com/pingcap/tidb/pull/7602) - - 解决单行注释内容为空 Parser 报错的问题 [#7612](https://github.com/pingcap/tidb/pull/7612) -- 表达式 - - 在 `insert` 函数中检查 `max_allowed_packet` 的值 [#7528](https://github.com/pingcap/tidb/pull/7528) - - 支持内建函数 `json_contains` [#7443](https://github.com/pingcap/tidb/pull/7443) - - 支持内建函数 `json_contains_path` [#7596](https://github.com/pingcap/tidb/pull/7596) - - 支持内建函数 `encode/decode` [#7622](https://github.com/pingcap/tidb/pull/7622) - - 修复一些时间相关的函数在某些情况下和 MySQL 行为不兼容的问题 [#7636](https://github.com/pingcap/tidb/pull/7636) - - 解决从字符串中解析时间类型数据的兼容性问题 [#7654](https://github.com/pingcap/tidb/pull/7654) - - 解决计算 `DateTime` 类型数据的默认值时没有考虑时区的问题 [#7655](https://github.com/pingcap/tidb/pull/7655) -- DML - - `InsertOnDuplicateUpdate` 语句设置正确的 `last_insert_id` [#7534](https://github.com/pingcap/tidb/pull/7534) - - 减少需要更新 `auto_increment_id` 计数器的情况 [#7515](https://github.com/pingcap/tidb/pull/7515) - - 优化 `Duplicate Key` 错误的报错信息 [#7495](https://github.com/pingcap/tidb/pull/7495) - - 修复 `insert...select...on duplicate key update` 问题 [#7406](https://github.com/pingcap/tidb/pull/7406) - - 支持 `LOAD DATA IGNORE LINES` 语句 [#7576](https://github.com/pingcap/tidb/pull/7576) -- DDL - - 在监控中增加 DDL Job 的类型和当前 Schema 版本的信息 [#7472](https://github.com/pingcap/tidb/pull/7472) - - 完成 `Admin Restore Table` 功能方案设计 [#7383](https://github.com/pingcap/tidb/pull/7383) - - 解决 Bit 类型的默认值超过 128 的问题 [#7249](https://github.com/pingcap/tidb/pull/7249) - - 解决 Bit 类型默认值不能为 `NULL` 的问题 [#7604](https://github.com/pingcap/tidb/pull/7604) - - 减少 DDL 队列中检查 `CREATE TABLE/DATABASE` 任务的时间间隔 [#7608](https://github.com/pingcap/tidb/pull/7608) - - 使用 `ddl/owner/resign` HTTP 接口释放 DDL Owner 并开启新一轮 Owner 选举 [#7649](https://github.com/pingcap/tidb/pull/7649) -- TiKV Go Client - - 支持 `Seek` 操作只获取 `Key` [#7419](https://github.com/pingcap/tidb/pull/7419) -- [Table Partition](https://github.com/pingcap/tidb/projects/6)（实验性） - - 解决无法使用 Bigint 类型列作为 Partition Key 的问题 [#7520](https://github.com/pingcap/tidb/pull/7520) - - 支持 Partitioned Table 添加索引过程中遇到问题回滚操作 [#7437](https://github.com/pingcap/tidb/pull/7437) - -## PD - -- 新特性 - - 支持 `GetAllStores`的接口 [#1228](https://github.com/pingcap/pd/pull/1228) - - Simulator 添加评估调度的统计信息 [#1218](https://github.com/pingcap/pd/pull/1218) -- 功能改进 - - 优化 Down Store 的处理流程，尽快地补副本 [#1222](https://github.com/pingcap/pd/pull/1222) - - 优化 Coordinator 的启动，减少重启 PD 带来的不必要调度 [#1225](https://github.com/pingcap/pd/pull/1225) - - 优化内存使用，减少 heartbeat 带来的内存开销 [#1195](https://github.com/pingcap/pd/pull/1195) - - 优化错误处理，完善日志信息 [#1227](https://github.com/pingcap/pd/pull/1227) - - pd-ctl 支持查询指定 store 的 Region 信息 [#1231](https://github.com/pingcap/pd/pull/1231) - - pd-ctl 支持查询按 version 比对的 topN 的 Region 信息 [#1233](https://github.com/pingcap/pd/pull/1233) - - pd-ctl 支持更精确的 TSO 解码 [#1242](https://github.com/pingcap/pd/pull/1242) -- Bug 修复 - - 修复 pd-ctl 使用 hot store 命令错误退出的问题 [#1244](https://github.com/pingcap/pd/pull/1244) - -## TiKV - -- 性能优化 - - 支持基于统计估算进行 Region split，减少 I/O 开销 [#3511](https://github.com/tikv/tikv/pull/3511) - - 减少部分组件的内存拷贝 [#3530](https://github.com/tikv/tikv/pull/3530) -- 功能改进 - - 增加大量内建函数下推支持 - - 增加 `leader-transfer-max-log-lag` 配置解决特定场景 leader 调度失败的问题 [#3507](https://github.com/tikv/tikv/pull/3507) - - 增加 `max-open-engines` 配置限制 `tikv-importer` 同时打开的 engine 个数 [#3496](https://github.com/tikv/tikv/pull/3496) - - 限制垃圾数据的清理速度，减少对 `snapshot apply` 的影响 [#3547](https://github.com/tikv/tikv/pull/3547) - - 对关键 Raft 消息广播 commit 信息，避免不必要的延迟 [#3592](https://github.com/tikv/tikv/pull/3592) -- Bug 修复 - - 修复新分裂 Region 的 PreVote 消息被丢弃导致的 leader 选举问题 [#3557](https://github.com/tikv/tikv/pull/3557) - - 修复 Region merge 以后 follower 的相关统计信息 [#3573](https://github.com/tikv/tikv/pull/3573) - - 修复 local reader 使用过期 Region 信息的问题 [#3565](https://github.com/tikv/tikv/pull/3565) diff --git a/v2.1/releases/21rc3.md b/v2.1/releases/21rc3.md deleted file mode 100644 index 04170e77ceac..000000000000 --- a/v2.1/releases/21rc3.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 2.1 RC3 Release Notes -category: Releases ---- - -# TiDB 2.1 RC3 Release Notes - -2018 年 9 月 29 日，TiDB 发布 2.1 RC3 版。相比 2.1 RC2 版本，该版本对系统稳定性、兼容性、优化器以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复语句内包含内嵌的 `LEFT OUTER JOIN` 时，结果不正确的问题 [#7689](https://github.com/pingcap/tidb/pull/7689) - - 增强 `JOIN` 语句上的 predicate pushdown 优化规则 [#7645](https://github.com/pingcap/tidb/pull/7645) - - 修复 `UnionScan` 算子的 predicate pushdown 优化规则 [#7695](https://github.com/pingcap/tidb/pull/7695) - - 修复 `Union` 算子的 unique key 属性设置不正确的问题 [#7680](https://github.com/pingcap/tidb/pull/7680) - - 增强常量折叠的优化规则 [#7696](https://github.com/pingcap/tidb/pull/7696) - - 把常量传播后的 filter 是 null 的 data source 优化成 table dual [#7756](https://github.com/pingcap/tidb/pull/7756) -+ SQL 执行引擎 - - 优化事务内读请求的性能 [#7717](https://github.com/pingcap/tidb/pull/7717) - - 优化部分执行器 Chunk 内存分配的开销 [#7540](https://github.com/pingcap/tidb/pull/7540) - - 修复点查全部为 NULL 的列导致数组越界的问题 [#7790](https://github.com/pingcap/tidb/pull/7790) -+ Server - - 修复配置文件里内存配额选项不生效的问题 [#7729](https://github.com/pingcap/tidb/pull/7729) - - 添加 tidb_force_priority 系统变量用来整体设置语句执行的优先级 [#7694](https://github.com/pingcap/tidb/pull/7694) - - 支持使用 `admin show slow` 语句来获取 SLOW QUERY LOG [#7785](https://github.com/pingcap/tidb/pull/7785) -+ 兼容性 - - 修复 `information_schema.schemata` 里 `charset/collation` 结果不正确的问题 [#7751](https://github.com/pingcap/tidb/pull/7751) - - 修复 `hostname` 系统变量的值为空的问题 [#7750](https://github.com/pingcap/tidb/pull/7750) -+ 表达式 - - 内建函数 `AES_ENCRYPT/AES_DECRYPT` 支持 `init_vecter` 参数 [#7425](https://github.com/pingcap/tidb/pull/7425) - - 修复部分表达式 `Format` 结果不正确的问题 [#7770](https://github.com/pingcap/tidb/pull/7770) - - 支持内建函数 `JSON_LENGTH` [#7739](https://github.com/pingcap/tidb/pull/7739) - - 修复 unsigned integer 类型 cast 为 decimal 类型结果不正确的问题 [#7792](https://github.com/pingcap/tidb/pull/7792) -+ DML - - 修复 `INSERT … ON DUPLICATE KEY UPDATE` 语句在 unique key 更新时结果不正确的问题 [#7675](https://github.com/pingcap/tidb/pull/7675) -+ DDL - - 修复在新建的 timestamp 类型的列上新建索引时，索引值没有做时区转换的问题 [#7724](https://github.com/pingcap/tidb/pull/7724) - - 支持 enum 类型 append 新的值 [#7767](https://github.com/pingcap/tidb/pull/7767) - - 快速新建 etcd session，使网络隔离后，集群更快恢复可用 [#7774](https://github.com/pingcap/tidb/pull/7774) - -## PD - -+ 新特性 - - 添加获取按大小逆序排序的 Region 列表 API (/size) [#1254](https://github.com/pingcap/pd/pull/1254) -+ 功能改进 - - Region API 会返回更详细的信息 [#1252](https://github.com/pingcap/pd/pull/1252) -+ Bug 修复 - - 修复 PD 切换 leader 以后 `adjacent-region-scheduler` 可能会导致 crash 的问题 [#1250](https://github.com/pingcap/pd/pull/1250) - -## TiKV - -+ 性能优化 - - 优化函数下推的并发支持 [#3515](https://github.com/tikv/tikv/pull/3515) -+ 新特性 - - 添加对 Log 函数的支持 [#3603](https://github.com/tikv/tikv/pull/3603) - - 添加对 `sha1` 函数的支持 [#3612](https://github.com/tikv/tikv/pull/3612) - - 添加 `truncate_int` 函数的支持 [#3532](https://github.com/tikv/tikv/pull/3532) - - 添加 `year` 函数的支持 [#3622](https://github.com/tikv/tikv/pull/3622) - - 添加 `truncate_real` 函数的支持 [#3633](https://github.com/tikv/tikv/pull/3633) -+ Bug 修复 - - 修正时间函数相关的报错行为 [#3487](https://github.com/tikv/tikv/pull/3487) [#3615](https://github.com/tikv/tikv/pull/3615) - - 修复字符串解析成时间与 TiDB 不一致的问题 [#3589](https://github.com/tikv/tikv/pull/3589) \ No newline at end of file diff --git a/v2.1/releases/21rc4.md b/v2.1/releases/21rc4.md deleted file mode 100644 index 6a46324f7c82..000000000000 --- a/v2.1/releases/21rc4.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: TiDB 2.1 RC4 Release Notes -category: Releases ---- - -# TiDB 2.1 RC4 Release Notes - -2018 年 10 月 23 日，TiDB 发布 2.1 RC4 版。相比 2.1 RC3 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复某些情况下 `UnionAll` 的列裁剪不正确的问题 [#7941](https://github.com/pingcap/tidb/pull/7941) - - 修复某些情况下 `UnionAll` 算子结果不正确的问题 [#8007](https://github.com/pingcap/tidb/pull/8007) -+ SQL 执行引擎 - - 修复 `AVG` 函数的精度问题 [#7874](https://github.com/pingcap/tidb/pull/7874) - - 支持通过 `EXPLAIN ANALYZE` 语句查看 Query 执行过程中各个算子的运行时间，返回结果行数等运行时统计信息 [#7925](https://github.com/pingcap/tidb/pull/7925) - - 修复多次引用同一列时 `PointGet` 算子 panic 的问题 [#7943](https://github.com/pingcap/tidb/pull/7943) - - 修复当 `Limit` 子句中的值太大时 panic 的问题 [#8002](https://github.com/pingcap/tidb/pull/8002) - - 修复某些情况下 `AddDate`/`SubDate` 执行过程中 panic 的问题 [#8009](https://github.com/pingcap/tidb/pull/8009) -+ 统计信息 - - 修复将组合索引的直方图下边界前缀判断为越界的问题 [#7856](https://github.com/pingcap/tidb/pull/7856) - - 修复统计信息收集引发的内存泄漏问题 [#7873](https://github.com/pingcap/tidb/pull/7873) - - 修复直方图为空时 panic 的问题 [#7928](https://github.com/pingcap/tidb/pull/7928) - - 修复加载统计信息时直方图边界越界的问题 [#7944](https://github.com/pingcap/tidb/pull/7944) - - 限制统计信息采样过程中数值的最大长度 [#7982](https://github.com/pingcap/tidb/pull/7982) -+ Server - - 重构 Latch，避免事务冲突误判，提升并发事务的执行性能 [#7711](https://github.com/pingcap/tidb/pull/7711) - - 修复某些情况下收集 Slow Query 导致的 panic 问题 [#7874](https://github.com/pingcap/tidb/pull/7847) - - 修复 `LOAD DATA` 语句中，`ESCAPED BY` 为空字符串时 panic 的问题 [#8005](https://github.com/pingcap/tidb/pull/8005) - - 完善 “coprocessor error” 日志信息 [#8006](https://github.com/pingcap/tidb/pull/8006) -+ 兼容性 - - 当 Query 为空时，将 `SHOW PROCESSLIST` 结果中的 `Command` 字段设置为 “Sleep” [#7839](https://github.com/pingcap/tidb/pull/7839) -+ 表达式 - - 修复 `SYSDATE` 函数被常量折叠的问题 [#7895](https://github.com/pingcap/tidb/pull/7895) - - 修复 `SUBSTRING_INDEX` 在某些情况下 panic 的问题 [#7897](https://github.com/pingcap/tidb/pull/7897) -+ DDL - - 修复抛出 “invalid ddl job type” 的错误时导致栈溢出的问题 [#7958](https://github.com/pingcap/tidb/pull/7958) - - 修复某些情况下 `ADMIN CHECK TABLE` 结果不正确的问题 [#7975](https://github.com/pingcap/tidb/pull/7975) - -## PD - -- 修复下线后的 TiKV 没有从 Grafana 面板中移除的问题 [#1261](https://github.com/pingcap/pd/pull/1261) -- 修复 grpc-go 设置 status 时的 data race 问题[#1265](https://github.com/pingcap/pd/pull/1265) -- 修复 etcd 启动失败导致的服务挂起问题 [#1267](https://github.com/pingcap/pd/pull/1267) -- 修复 leader 切换过程中可能产生的 data race [#1273](https://github.com/pingcap/pd/pull/1273) -- 修复下线 TiKV 时可能输出多余 warning 日志的问题 [#1280](https://github.com/pingcap/pd/pull/1273) - -## TiKV - -- 优化 apply snapshot 导致的 RocksDB Write stall 的问题 [#3606](https://github.com/tikv/tikv/pull/3606) -- 增加 raftstore tick 相关 metrics [#3657](https://github.com/tikv/tikv/pull/3657) -- 升级 RocksDB，修复写入卡死及 IngestExternalFile 时可能写坏源文件的问题 [#3661](https://github.com/tikv/tikv/pull/3661) -- 升级 grpcio，修复 “too many pings” 误报的问题 [#3650](https://github.com/tikv/tikv/pull/3650) diff --git a/v2.1/releases/21rc5.md b/v2.1/releases/21rc5.md deleted file mode 100644 index 243d09f0beb8..000000000000 --- a/v2.1/releases/21rc5.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 2.1 RC5 Release Notes -category: Releases ---- - - - -# TiDB 2.1 RC5 Release Notes - -2018 年 11 月 12 日，TiDB 发布 2.1 RC5 版。相比 2.1 RC4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复 `IndexReader` 在某些情况下读取的 handle 不正确的问题 [#8132](https://github.com/pingcap/tidb/pull/8132) - - 修复 `IndexScan Prepared` 语句在使用 `Plan Cache` 的时候的问题 [#8055](https://github.com/pingcap/tidb/pull/8055) - - 修复 `Union` 语句结果不稳定的问题 [#8165](https://github.com/pingcap/tidb/pull/8165) -+ 执行器 - - 提升 TiDB 插入和更新宽表的性能 [#8024](https://github.com/pingcap/tidb/pull/8024) - - 内建函数 `Truncate` 支持 unsigned `int` 参数 [#8068](https://github.com/pingcap/tidb/pull/8068) - - 修复转换 JSON 数据到 decimal 类型出错的问题 [#8109](https://github.com/pingcap/tidb/pull/8109) - - 修复 float 类型在 `Update` 时出错的问题 [#8170](https://github.com/pingcap/tidb/pull/8170) -+ 统计信息 - - 修复点查在某些情况下，统计信息出现错误的问题 [#8035](https://github.com/pingcap/tidb/pull/8035) - - 修复统计信息某些情况下在 primary key 的选择率的问题 [#8149](https://github.com/pingcap/tidb/pull/8149) - - 修复被删除的表的统计信息长时间没有清理的问题 [#8182](https://github.com/pingcap/tidb/pull/8182) -+ Server - + 提升日志的可读性，完善日志信息 - - [#8063](https://github.com/pingcap/tidb/pull/8063) - - [#8053](https://github.com/pingcap/tidb/pull/8053) - - [#8224](https://github.com/pingcap/tidb/pull/8224) - - 修复获取 `infoschema.profiling` 表数据出错的问题 [#8096](https://github.com/pingcap/tidb/pull/8096) - - 替换 unix socket，使用 pumps client 来写 binlog [#8098](https://github.com/pingcap/tidb/pull/8098) - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 [#8094](https://github.com/pingcap/tidb/pull/8094) - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 [#8200](https://github.com/pingcap/tidb/pull/8200) - - 增加环境变量 `tidb_opt_write_row_id` 来控制是否允许写入 `_tidb_rowid` [#8218](https://github.com/pingcap/tidb/pull/8218) - - ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8081](https://github.com/pingcap/tidb/pull/8081)，[#8247](https://github.com/pingcap/tidb/pull/8247) -+ DDL - - 修复在事务中某些情况下执行 DDL 语句出错的问题 [#8056](https://github.com/pingcap/tidb/pull/8056) - - 修复 partition 分区表执行 `truncate table` 没有生效的问题 [#8103](https://github.com/pingcap/tidb/pull/8103) - - 修复某些情况下 DDL 操作在被 cancel 之后没有正确回滚的问题 [#8057](https://github.com/pingcap/tidb/pull/8057) - - 增加命令 `admin show next_row_id`，返回下一个可用的行 ID [#8268](https://github.com/pingcap/tidb/pull/8268) - -## PD - -+ 修复 `pd-ctl` 读取 Region key 的相关问题 - - [#1298](https://github.com/pingcap/pd/pull/1298) - - [#1299](https://github.com/pingcap/pd/pull/1299) - - [#1308](https://github.com/pingcap/pd/pull/1308) -+ 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -+ 修复 PD join 失败后无法重新 join 的问题 [#1279](https://github.com/pingcap/pd/pull/1279) -+ 修复某些情况下 watch leader 会丢失事件的问题 [#1317](https://github.com/pingcap/pd/pull/1317) - -## TiKV - -- 优化 `WriteConflict` 报错信息 [#3750](https://github.com/tikv/tikv/pull/3750) -- 增加 panic 标记文件 [#3746](https://github.com/tikv/tikv/pull/3746) -- 降级 grpcio，避免新版本 gRPC 导致的 segment fault 问题 [#3650](https://github.com/tikv/tikv/pull/3650) -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) - -## Tools - -- TiDB 支持 TiDB Binlog cluster，不兼容旧版本 TiDB Binlog [#8093](https://github.com/pingcap/tidb/pull/8093)，[使用文档](/v2.1/reference/tidb-binlog/overview.md) diff --git a/v2.1/releases/2rc1.md b/v2.1/releases/2rc1.md deleted file mode 100644 index 5df84ccb29ec..000000000000 --- a/v2.1/releases/2rc1.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.0 RC1 Release Notes -category: Releases ---- - -# TiDB 2.0 RC1 Release Notes - -2018 年 3 月 9 日，TiDB 发布 2.0 RC1 版。该版本在上一版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -+ 支持限制单条 SQL 语句使用内存的大小，减少程序 OOM 风险 -+ 支持下推流式聚合算子到 TiKV -+ 支持配置文件的合法性检测 -+ 支持 HTTP API 获取 TiDB 参数信息 -+ Parser 兼容更多 MySQL 语法 -+ 提升对 Navicat 的兼容性 -+ 优化器提升，提取多个 OR 条件的公共表达式，选取更优执行计划 -+ 优化器提升，在更多场景下将子查询转换成 Join 算子，选取更优查询计划 -+ 使用 Batch 方式 Resolve Lock，提升垃圾回收速度 -+ 修复 Boolean 类型的字段长度，提升兼容性 -+ 优化 Add Index 操作，所有的读写操作采用低优先级，减小对在线业务的影响 - -## PD - -+ 优化检查 Region 状态的代码逻辑，提升程序性能 -+ 优化异常情况下日志信息输出，便于调试 -+ 修复监控中关于 TiKV 节点磁盘空间不足情况的统计 -+ 修复开启 TLS 时健康检查接口误报的问题 -+ 修复同时添加副本数量可能超过配置阈值的问题，提升程序稳定性 - -## TiKV - -+ 修复 PD leader 切换，gRPC call 没被 cancel 的问题 -+ 对重要配置进行保护，第一次设置之后不允许变更 -+ 增加获取 metrics 的 gRPC API -+ 启动时候，检查是否使用 SSD -+ 使用 ReadPool 优化读性能，`raw get` 测试性能提升 30% -+ 完善 metrics，优化 metrics 的使用 \ No newline at end of file diff --git a/v2.1/releases/2rc3.md b/v2.1/releases/2rc3.md deleted file mode 100644 index 4489e7e0ab15..000000000000 --- a/v2.1/releases/2rc3.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: TiDB 2.0 RC3 Release Notes -category: Releases ---- - -# TiDB 2.0 RC3 Release Notes - -2018 年 3 月 23 日，TiDB 发布 2.0 RC3 版。该版本在 2.0 RC2 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 修复部分场景下 `MAX/MIN` 结果不正确的问题 -- 修复部分场景下 `Sort Merge Join` 结果未按照 Join Key 有序的问题 -- 修复边界条件下 `uint` 和 `int` 比较的错误 -- 完善浮点数类型的长度和精度检查，提升 MySQL 兼容性 -- 完善时间类型解析报错日志，添加更多错误信息 -- 完善内存控制，新增对 `IndexLookupExecutor` 的内存统计 -- 优化 `ADD INDEX` 的执行速度，部分场景下速度大幅度提升 -- `GROUP BY` 子句为空时使用 Stream Aggregation 算子，提升速度 -- 支持通过 `STRAIGHT_JOIN` 来关闭优化器的 `Join Reorder` 优化 -- `ADMIN SHOW DDL JOBS` 输出更详细的 DDL 任务状态信息 -- 支持 `ADMIN SHOW DDL JOB QUERIES` 查询当前正在运行的 DDL 任务的原始语句 -- 支持 `ADMIN RECOVER INDEX` 命令，用于灾难恢复情况下修复索引数据 -- `ADD INDEX` 操作变更为低优先级，降低对线上业务影响 -- 支持参数为 JSON 类型的 `SUM/AVG` 等聚合函数 -- 支持配置文件修改 `lower_case_table_names` 系统变量，用于支持 OGG 数据同步工具 -- 提升对 Navicat 管理工具的兼容性 -- 支持在 CRUD 操作中使用隐式的行 ID - -## PD - -- 支持 Region Merge，合并数据删除后产生的空 Region 或小 Region -- 添加副本时忽略有大量 pending peer 的节点，提升恢复副本及下线的速度 -- 优化有大量空 Region 时产生的频繁调度问题 -- 优化不同 label 中资源不均衡的场景中 leader balance 调度的速度 -- 添加更多异常 Region 的统计 - -## TiKV - -- 支持 Region Merge -- Raft snapshot 流程完成之后立刻通知 PD，加速调度 -- 增加 Raw DeleteRange API -- 增加 GetMetric API -- 减缓 RocksDB sync 文件造成的 I/O 波动 -- 优化了对 delete 掉数据的空间回收机制 -- 完善数据恢复工具 `tikv-ctl` -- 解决了由于 snapshot 导致下线节点慢的问题 -- Coprocessor 支持 streaming -- 支持 Readpool，`raw_get/get/batch_get` 性能提升 30% -- 支持配置 Coprocessor 请求超时时间 -- Coprocessor 支持 streaming aggregation -- 上报 Region heartbeat 时携带时间信息 -- 限制 snapshot 文件的空间使用，防止占用过多磁盘空间 -- 对长时间不能选出 leader 的 Region 进行记录上报 -- 加速启动阶段的垃圾清理工作 -- 根据 compaction 事件及时更新对应 Region 的 size 信息 -- 对 `scan lock` 的大小进行限制，防止请求超时 -- 使用 `DeleteRange` 加速 Region 删除 -- 支持在线修改 RocksDB 的参数 \ No newline at end of file diff --git a/v2.1/releases/2rc4.md b/v2.1/releases/2rc4.md deleted file mode 100644 index 9858c86e4959..000000000000 --- a/v2.1/releases/2rc4.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.0 RC4 Release Notes -category: Releases ---- - -# TiDB 2.0 RC4 Release Notes - -2018 年 3 月 30 日，TiDB 发布 2.0 RC4 版。该版本在 2.0 RC3 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 支持 `SHOW GRANTS FOR CURRENT_USER();` -- 修复 `UnionScan` 里的 `Expression` 没有 Clone 的问题 -- 支持 `SET TRANSACTION` 语法 -- 修复 `copIterator` 中潜在的 goroutine 泄露问题 -- 修复 `admin check table` 对包含 null 的 unique index 误判的问题 -- 支持用科学计数法显示浮点数 -- 修复 binary literal 计算时的类型推导 -- 修复解析 `CREATE VIEW` 语句的问题 -- 修复语句中同时包含 `ORDER BY` 和 `LIMIT 0` 时 panic 的问题 -- 提升 `DecodeBytes` 执行性能 -- 优化 `LIMIT 0` 为 `TableDual`，避免无用的执行计划构建 - -## PD - -- 支持手动 split Region，可用于处理单 Region 热点的问题 -- 修复 `pdctl` 运行 `config show all` 不显示 label property 的问题 -- metrics 及代码结构相关的优化 - -## TiKV - -- 限制接收 snapshot 时的内存使用，解决极端情况下的 OOM -- 可以配置 Coprocessor 在遇到 warnings 时的行为 -- TiKV 支持导数据模式 -- 支持 Region 从正中间分裂 -- 提升 CI test 的速度 -- 使用 `crossbeam channel` -- 改善 TiKV 在被隔离的情况下由于 leader missing 输出太多日志的问题 diff --git a/v2.1/releases/2rc5.md b/v2.1/releases/2rc5.md deleted file mode 100644 index 709bcef9cd7f..000000000000 --- a/v2.1/releases/2rc5.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: TiDB 2.0 RC5 Release Notes -category: Releases ---- - -# TiDB 2.0 RC5 Release Notes - -2018 年 4 月 17 日，TiDB 发布 2.0 RC5 版。该版本在 RC4 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 修复应用 `Top-N` 下推规则的问题 -- 修复对包含 NULL 值的列的行数估算 -- 修复 Binary 类型的 0 值 -- 修复事务内的 `BatchGet` 问题 -- 回滚 `Add Index` 操作的时候，清除清除已写入的数据，减少空间占用 -- 优化 `insert on duplicate key update` 语句性能，提升 10 倍以上 -- 修复 `UNIX_TIMESTAMP` 函数返回结果类型问题返回结果类型问题 -- 修复在添加 NOT NULL 列的过程中，插入 NULL 值的问题 -- `Show Process List` 语句支持显示执行语句的内存占用 -- 修复极端情况下 `Alter Table Modify Column` 出错问题 -- 支持通过 `Alter` 语句设置 table comment - -## PD - -- 添加 Raft Learner 支持 -- 优化 Balance Region Scheduler，减少调度开销 -- 调整默认 `schedule-limit` 配置 -- 修复频繁分配 ID 问题 -- 修复添加调度兼容性问题 - -## TiKV - -- `tikv-ctl` 支持 compact 指定的 Region -- Raw KV 支持 Batch Put、Batch Get、Batch Delete 和 Batch Scan -- 解决太多 snapshot 导致的 OOM 问题 -- Coprocessor 返回更详细的错误信息 -- 支持通过 `tikv-ctl` 动态修改 TiKV 的 `block-cache-size` -- 进一步完善 importer 功能 -- 简化 `ImportSST::Upload` 接口 -- 设置 gRPC 的 `keepalive` 属性 -- `tikv-importer` 作为独立的 binary 从 TiKV 中分离出来 -- 统计 Coprocessor 每个 scan range 命令扫描了多少行数据 -- 解决在 macOS 系统上的编译问题 -- 优化 metric 相关的内容 -- 解决 snapshot 相关的一个潜在 bug -- 解决误用了一个 RocksDB metric 的问题 -- Coprocessor 支持 `overflow as warning` 选项 \ No newline at end of file diff --git a/v2.1/releases/3.0-ga.md b/v2.1/releases/3.0-ga.md deleted file mode 100644 index 2d7962a367a9..000000000000 --- a/v2.1/releases/3.0-ga.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: TiDB 3.0 GA Release Notes -category: Releases ---- - -# TiDB 3.0 GA Release Notes - -发版日期：2019 年 6 月 28 日 - -TiDB 版本：3.0.0 - -TiDB Ansible 版本：3.0.0 - -## Overview - -2019 年 6 月 28 日，TiDB 发布 3.0 GA 版本，对应的 TiDB Ansible 版本为 3.0.0。 -相比于 V2.1，V3.0.0 版本在以下方面有重要改进： - -- 稳定性方面，显著提升了大规模集群的稳定性，集群支持 150+ 存储节点，300+ TB 存储容量长期稳定运行。 -- 易用性方面有显著的提升，降低用户运维成本，例如：标准化慢查询日志，制定日志文件输出规范，新增 `EXPLAIN ANALYZE`，SQL Trace 功能方便排查问题等。 -- 性能方面，与 2.1 相比，TPC-C 性能提升约 4.5 倍，Sysbench 性能提升约 1.5 倍。因支持 View，TPC-H 50G Q15 可正常运行。 -- 新功能方面增加了窗口函数、视图（**实验特性**）、分区表、插件系统、悲观锁（**实验特性**）、`SQL Plan Management` 等特性。 - -## TiDB - -+ 新功能 - - 新增 Window Function，支持所有 MySQL 8.0 中的窗口函数，包括 `NTILE`，`LEAD`，`LAG`、`PERCENT_RANK`、`NTH_VALUE`、`CUME_DIST`、`FIRST_VALUE`、`LAST_VALUE`、`RANK`、`DENSE_RANK`、`ROW_NUMBER` 函数 - - 新增 View 功能（**实验特性**） - - 完善 Table Partition 功能： - - Range Partition - - Hash Partition - - 新增插件系统，官方提供 IP 白名单（**企业版特性**），审记日志（**企业版特性**）等插件 - - 新增 `SQL Plan Management` 功能，通过绑定 SQL 执行计划确保查询的稳定性（**实验特性**） -+ SQL 优化器 - - 优化`NOT EXISTS` 子查询，转化为 Anti Semi Join 提升性能 - - 优化 `Outer Join` 常量传播，新增 `Outer Join` 消除优化规则，避免无效计算，提升性能 - - 优化 `IN` 子查询，先聚合后执行 `Inner Join`，提升性能 - - 优化 Index Join，适应更多的场景，提升性能 - - 优化 Range Partition 的 Partition Pruning 优化规则，提升性能 - - 优化 `_tidb_rowid` 查询逻辑，避免全表扫描，提升性能 - - 当过滤条件中包含相关列时，在抽取复合索引的访问条件时尽可能多地匹配索引的前缀列，提升性能 - - 利用列之间的顺序相关性，提升代价估算准确度 - - 基于统计信息的贪心算法及动态规划算法改进了 `Join Order`，提升多表关联的执行速度 - - 新增 Skyline Pruning，利用规则防止执行计划过于依赖统计信息，提升查询的稳定性 - - 提升单列索引上值为 NULL 时行数估算准确度 - - 新增 `FAST ANALYZE`，通过在各个 Region 中随机采样避免全表扫描的方式提升统计信息收集性能 - - 新增单调递增的索引列增量 `Analyze` 功能，提升统计信息收集性能 - - 支持 `DO` 语句中使用子查询 - - 支持在事务中使用 Index Join - - 优化 `prepare`/`execute`，支持不带参数的 DDL 语句 - - 修改变量 `stats-lease` 值为 0 时系统的行为，使其自动加载统计 - - 新增导出历史统计信息功能 - - 新增导入导出列的关联性信息功能 -+ SQL 执行引擎 - - 优化日志输出，`EXECUTE` 语句输出用户变量，`COMMIT` 语句输出慢查询日志，方便排查问题 - - 新增 `EXPLAIN ANALYZE` 功能，提升SQL 调优易用性 - - 新增 `admin show next_row_id` 功能，方便获取下一行 ID - - 新增`JSON_QUOTE`、`JSON_ARRAY_APPEND`、`JSON_MERGE_PRESERVE`、`BENCHMARK`、`COALESCE`、`NAME_CONST` 6 个内建函数 - - 优化 Chunk 大小控制逻辑，根据查询上下文件动态调整，降低 SQL 执行时间和资源消耗，提升性能 - - 新增 `TableReader`、`IndexReader` 和 `IndexLookupReader` 算子内存追踪控制 - - 优化 Merge Join 算子，使其支持空的 `ON` 条件 - - 优化单个表列较多时写入性能，提升数倍性能 - - 通过支持逆序扫数据提升 `admin show ddl jobs` 的性能 - - 新增 `split table region` 语句，手动分裂表的 Region，缓解热点问题 - - 新增 `split index region` 语句，手动分裂索引的 Region，缓解热点问题 - - 新增黑名单禁止下推表达式到 Coprocessor 功能 - - 优化 Expensive Query 日志，在日志中打印执行时间或者使用内存超过阈值的 SQL 查询 -+ DDL - - 支持字符集从 `utf8` 转换到 `utf8mb4` 的功能 - - 修改默认字符集从 `utf8` 变为 `utf8mb4` - - 新增 `alter schema` 语句修改数据库 charset 和 collation 功能 - - 新增 ALTER ALGORITHM `INPLACE`/`INSTANT` 功能 - - 新增 `SHOW CREATE VIEW` 功能 - - 新增 `SHOW CREATE USER` 功能 - - 新增快速恢复误删除的表功能 - - 新增动态调整 `ADD INDEX` 的并发数功能 - - 新增 pre_split_regions 选项，在 `CREATE TABLE` 时预先分配 Region，缓解建表后大量写入造成的写热点问题 - - 新增通过 SQL 语句指定表的索引及范围分裂 Region，缓解热点问题 - - 新增 `ddl_error_count_limit` 全局变量，控制 DDL 任务重次数 - - 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 - - 优化无效 DDL 元信息存活时间，使集群升级后一段时间 DDL 操作比较慢的情况变短 -+ 事务 - - 新增悲观事务模型（**实验特性**） - - 优化事务处理逻辑，适应更多场景，具体如下： - - `tidb_disable_txn_auto_retry` 的默认值为 `on`，即不会重试非自动提交的事务 - - 新增 `tidb_batch_commit` 系统变量控制将事务拆分成多个事务并发执行 - - 新增 `tidb_low_resolution_tso` 系统变量控制批量获取 `tso` 个数，减少事务获取 `tso` 的次数以适应某些数据一致性要求较低的场景 - - 新增 `tidb_skip_isolation_level_check` 变量控制事务检查隔离级别设置为 SERIALIZABLE 时是否报错 - - 修改 `tidb_disable_txn_auto_retry` 系统变量的行为，修改为影响所有的可重试错误 -+ 权限管理 - - 对 `ANALYZE`、`USE`、`SET GLOBAL`、`SHOW PROCESSLIST` 语句进行权限检查 - - 新增基于角色的权限访问控制功能 (RBAC)（**实验特性**） -+ Server - - 优化慢查询日志，具体包括： - - 重构慢查询日志格式 - - 优化慢查询日志内容 - - 优化查询慢查询日志的方法，通过内存表 `INFORMATION_SCHEMA.SLOW_QUERY`，`ADMIN SHOW SLOW` 语句查询慢查询日志 - - 制定日志格式规范，重构日志系统，方便工具收集分析 - - 新增 SQL 语句管理 TiDB Binlog 服务功能，包括查询状态，开启 TiDB Binlog，维护发送 TiDB Binlog 策略 - - 新增通过 `unix_socket` 方式连接数据库 - - 新增 SQL 语句 `Trace` 功能 - - 新增 `/debug/zip` HTTP 接口，获取 TiDB 实例的信息，方便排查问题 - - 优化监控项，方便排查问题，如下： - - 新增 `high_error_rate_feedback_total` 监控项，监控真实数据量与统计信息估算数据量之间的差距 - - 新增 Database 维度的 QPS 监控项 - - 优化系统初始化流程，仅允许 DDL Owner 执行初始化操作，缩短初始化或升级过程中的启动时间 - - 优化 `kill query` 语句执行逻辑，提升性能，确保资源正确释放 - - 新增启动选项 `config-check` 检查配置文件合法性 - - 新增 `tidb_back_off_weight` 系统变量，控制内部出错重试的退避时间 - - 新增 `wait_timeout`、`interactive_timeout` 系统变量，控制连接空闲超过变量的值，系统自动断开连接。 - - 新增连接 TiKV 的连接池，减少连接创建时间 -+ 兼容性 - - 支持 `ALLOW_INVALID_DATES` SQL mode - - 支持 MySQL 320 握手协议 - - 支持将 unsigned bigint 列声明为自增列 - - 支持 `SHOW CREATE DATABASE IF NOT EXISTS` 语法 - - 优化 load data 对 CSV 文件的容错 - - 过滤条件中包含用户变量时谓词不下推，兼容 MySQL Window Function 中使用用户变量行为 - -## PD - -+ 新增从单个节点重建集群的功能 -+ 将 Region 元信息从 etcd 移到 go-leveldb 存储引擎，解决大规模集群 etcd 存储瓶颈问题 -+ API - - 新增 `remove-tombstone` 接口，用于清理 Tombstone Store - - 新增 `ScanRegions` 接口，用于批量查询 Region 信息 - - 新增 `GetOperator` 接口，用于查询运行中的 Operator - - 优化 `GetStores` 接口的性能 -+ 配置 - - 优化配置检查逻辑，防止配置项错误 - - 新增 `enable-two-way-merge`，用于控制 Region merge 的方向 - - 新增 `hot-region-schedule-limit`，用于控制热点 Region 调度速度 - - 新增 `hot-region-cache-hits-threshold`，连续命中阀值用于判断热点 - - 新增 `store-balance-rate` 配置，用于控制每分钟产生 balance Region Operator 数量的上限 -+ 调度器优化 - - 添加 Store Limit 机制限制调度速度，使得速度限制适用于不同规模的集群 - - 添加 `waitingOperator` 队列，用于优化不同调度器之间资源竞争的问题 - - 支持调度限速功能，主动向 TiKV 下发调度操作，限制单节点同时执行调度任务的个数，提升调度速度 - - Region Scatter 调度不再受 limit 机制限制，提升调度的速度 - - 新增 `shuffle-hot-region` 调度器，解决稳定性测试易用性问题 -+ 模拟器 - - 新增数据导入场景模拟 - - 新增为 Store 设置不同的心跳间隔的功能 -+ 其他 - - 升级 etcd，解决输出日志格式不一致，prevote 时选举不出 Leader，Lease 死锁等问题 - - 制定日志格式规范，重构日志系统，方便工具收集分析 - - 新增调度参数，集群 Label 信息，PD 处理 TSO 请求的耗时，Store ID 与地址信息等监控指标 - -## TiKV - -+ 新增分布式 GC 以及并行 Resolve Lock 功能，提升 GC 的性能 -+ 新增逆向 `raw_scan` 和 `raw_batch_scan` 功能 -+ 新增多线程 Raftstore 和 Apply 功能，提升单节点内可扩展性，提升单节点内并发处理能力，提升单节点的资源利用率，降低延时，同等压力情况下性能提升 70% -+ 新增批量接收和发送 Raft 消息功能，写入密集的场景 TPS 提升 7% -+ 新增 Apply snapshot 之前检查 RocksDB level 0 文件的优化，避免产生 Write stall -+ 新增 Titan 存储引擎插件，提升 Value 超过 1KiB 时系统的性能，一定程度上缓解写放大问题（**实验特性**） -+ 新增悲观事务模型（**实验特性**） -+ 新增通过 HTTP 方式获取监控信息功能 -+ 修改 Insert 语义，仅在 Key 不存在的时候 Prewrite 才成功 -+ 制定日志格式规范，重构日志系统，方便工具收集分析 -+ 新增配置信息，Key 越界相关的性能监控指标 -+ RawKV 使用 Local Reader，提升性能 -+ Engine - - 优化内存管理，减少 `Iterator Key Bound Option` 的内存分配和拷贝，提升性能 - - 支持多个 column family 共享 block cache，提升资源的利用率 -+ Server - - 优化 `batch commands` 的上下文切换开销，提升性能 - - 删除 txn scheduler - - 新增 read index，GC worker 相关监控项 -+ RaftStore - - 新增 hibernate Regions 功能，优化 RaftStore CPU 的消耗（**实验特性**） - - 删除 local reader 线程 -+ Coprocessor - - 重构计算框架，实现向量化算子、向量化表达式计算、向量化聚合，提升性能 - - 支持为 TiDB `EXPLAIN ANALYZE` 语句提供算子执行详情 - - 改用 work-stealing 线程池模型，减少上下文切换 - -## Tools - -+ TiDB Lightning - - 支持数据表重定向同步功能 - - 新增导入 CSV 文件功能 - - 提升 SQL 转 KV 对的性能 - - 单表支持批量导入功能，提升单表导入的性能 - - 支持将大表的数据和索引分别导入，提升 `TiKV-Importer` 导入数据性能 - - 支持对新增文件中缺少 Column 数据时使用 row id 或者列的默认值填充缺少的 column 数据 - - `TiKV-Importer` 支持对 upload SST 到 TiKV 限速功能 -+ TiDB Binlog - - Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 - - Pump 使用 TiKV GetMvccByKey 接口加快事务状态查询 - - 新增组件之间通讯数据压缩功能，减少网络资源消耗 - - 新增 Arbiter 工具支持从 Kafka 读取 binlog 并同步到 MySQL 功能 - - Reparo 支持过滤不需要被同步的文件的功能 - - 新增同步 Generated column 功能 - - 新增 syncer.sql-mode 配置项，支持采用不同的 SQL mode 解析 DDL - - 新增 syncer.ignore-table 配置项，过滤不需要被同步的表 -+ sync-diff-inspector - - 新增 checkpoint 功能，支持从断点继续校验的功能 - - 新增 only-use-checksum 配置项，控制仅通过计算 checksum 校验数据的一致性 - - 新增采用 TiDB 统计信息以及使用多个 Column 划分 Chunk 的功能，适应更多的场景 - -## TiDB Ansible - -- 升级监控组件版本到安全的版本 - - Prometheus 从 2.2.1 升级到 2.8.1 版本 - - Pushgateway 从 0.4.0 升级到 0.7.0 版本 - - Node_exporter 从 0.15.2 升级到 0.17.0 版本 - - Alertmanager 从 0.14.0 升级到 0.17.0 版本 - - Grafana 从 4.6.3 升级到 6.1.6 版本 - - Ansible 从 2.5.14 升级到 2.7.11 版本 -- 新增 TiKV summary 监控面板，方便查看集群状态 -- 新增 TiKV trouble_shooting 监控面板，删除重复项，方便排查问题 -- 新增 TiKV details 监控面板，方便调试排查问题 -- 新增滚动升级并发检测版本是否一致功能，提升滚动升级性能 -- 新增 lightning 部署运维功能 -- 优化 `table-regions.py` 脚本，新增按表显示 leader 分布功能 -- 优化 TiDB 监控，新增以 SQL 类别显示延迟的监控项 -- 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 -- 新增预测集群最大 QPS 的监控项，默认隐藏 diff --git a/v2.1/releases/3.0.0-beta.1.md b/v2.1/releases/3.0.0-beta.1.md deleted file mode 100644 index af1f786ebadf..000000000000 --- a/v2.1/releases/3.0.0-beta.1.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: TiDB 3.0.0 Beta.1 Release Notes -category: Releases ---- - -# TiDB 3.0.0 Beta.1 Release Notes - -发版日期：2019 年 3 月 26 日 - -TiDB 版本：3.0.0-beta.1 - -TiDB Ansible 版本：3.0.0-beta.1 - -## Overview - -2019 年 03 月 26 日，TiDB 发布 3.0.0 Beta.1 版，对应的 TiDB Ansible 版本为 3.0.0 Beta.1。相比 3.0.0 Beta 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 支持使用 Sort Merge Join 计算笛卡尔积 [#9032](https://github.com/pingcap/tidb/pull/9037) - - 支持 Skyline Pruning，用一些规则来防止执行计划过于依赖统计信息 [#9337](https://github.com/pingcap/tidb/pull/9337) - + 支持 Window Functions - - `NTILE` [#9682](https://github.com/pingcap/tidb/pull/9682) - - `LEAD` 和 `LAG` [#9672](https://github.com/pingcap/tidb/pull/9672) - - `PERCENT_RANK` [#9671](https://github.com/pingcap/tidb/pull/9671) - - `NTH_VALUE` [#9596](https://github.com/pingcap/tidb/pull/9596) - - `CUME_DIST` [#9619](https://github.com/pingcap/tidb/pull/9619) - - `FIRST_VALUE` 和 `LAST_VALUE` [#9560](https://github.com/pingcap/tidb/pull/9560) - - `RANK` 和 `DENSE_RANK` [#9500](https://github.com/pingcap/tidb/pull/9500) - - `RANGE FRAMED` [#9450](https://github.com/pingcap/tidb/pull/9450) - - `ROW FRAMED` [#9358](https://github.com/pingcap/tidb/pull/9358) - - `ROW NUMBER` [#9098](https://github.com/pingcap/tidb/pull/9098) - - 增加了一类统计信息，表示列和 handle 列之间顺序的相关性 [#9315](https://github.com/pingcap/tidb/pull/9315) -+ SQL 执行引擎 - + 增加内建函数 - - `JSON_QUOTE` [#7832](https://github.com/pingcap/tidb/pull/7832) - - `JSON_ARRAY_APPEND` [#9609](https://github.com/pingcap/tidb/pull/9609) - - `JSON_MERGE_PRESERVE` [#8931](https://github.com/pingcap/tidb/pull/8931) - - `BENCHMARK` [#9252](https://github.com/pingcap/tidb/pull/9252) - - `COALESCE` [#9087](https://github.com/pingcap/tidb/pull/9087) - - `NAME_CONST` [#9261](https://github.com/pingcap/tidb/pull/9261) - - 根据查询上下文优化 Chunk 大小，降低 SQL 执行时间和集群的资源消耗 [#6489](https://github.com/pingcap/tidb/issues/6489) -+ 权限管理 - - 支持 `SET ROLE` 和 `CURRENT_ROLE` [#9581](https://github.com/pingcap/tidb/pull/9581) - - 支持 `DROP ROLE` [#9616](https://github.com/pingcap/tidb/pull/9616) - - 支持 `CREATE ROLE` [#9461](https://github.com/pingcap/tidb/pull/9461) -+ Server - - 新增 `/debug/zip` HTTP 接口，获取当前 TiDB 实例的信息 [#9651](https://github.com/pingcap/tidb/pull/9651) - - 支持使用 `show pump status`/`show drainer status` 语句查看 Pump/Drainer 状态 [#9456](https://github.com/pingcap/tidb/pull/9456) - - 支持使用 SQL 语句在线修改 Pump/Drainer 状态 [#9789](https://github.com/pingcap/tidb/pull/9789) - - 支持给 SQL 文本加上 HASH 指纹，方便追查慢 SQL [#9662](https://github.com/pingcap/tidb/pull/9662) - - 新增 `log_bin` 系统变量，默认：0，管理 binlog 开启状态，当前仅支持查看状态 [#9343](https://github.com/pingcap/tidb/pull/9343) - - 支持通过配置文件管理发送 binlog 策略 [#9864](https://github.com/pingcap/tidb/pull/9864) - - 支持通过内存表 `INFORMATION_SCHEMA.SLOW_QUERY` 查询慢日志 [#9290](https://github.com/pingcap/tidb/pull/9290) - - 将 TiDB 显示的 MySQL Version 从 5.7.10 变更为 5.7.25 [#9553](https://github.com/pingcap/tidb/pull/9553) - - 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 - - 增加监控项 `high_error_rate_feedback_total`，记录实际数据量与统计信息估算数据量差距情况 [#9209](https://github.com/pingcap/tidb/pull/9209) - - 新增 Database 维度的 QPS 监控项 , 可以通过配置项开启 [#9151](https://github.com/pingcap/tidb/pull/9151) -+ DDL - - 增加`ddl_error_count_limit`全局变量，默认值：512，限制 DDL 任务重试次数，超过限制次数会取消出错的 DDL [#9295](https://github.com/pingcap/tidb/pull/9295) - - 支持 ALTER ALGORITHM `INPLACE`/`INSTANT` [#8811](https://github.com/pingcap/tidb/pull/8811) - - 支持 `SHOW CREATE VIEW` 语句 [#9309](https://github.com/pingcap/tidb/pull/9309) - - 支持 `SHOW CREATE USER` 语句 [#9240](https://github.com/pingcap/tidb/pull/9240) - -## PD - -+ 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 -+ 模拟器 - - 支持不同 store 可采用不同的心跳间隔时间 [#1418](https://github.com/pingcap/pd/pull/1418) - - 添加导入数据的场景 [#1263](https://github.com/pingcap/pd/pull/1263) -+ 热点调度可配置化 [#1412](https://github.com/pingcap/pd/pull/1412) -+ 增加 store 地址为维度的监控项，代替原有的 Store ID [#1429](https://github.com/pingcap/pd/pull/1429) -+ 优化 `GetStores` 开销，加快 Region 巡检周期 [#1410](https://github.com/pingcap/pd/pull/1410) -+ 新增删除 Tombstone Store 的接口 [#1472](https://github.com/pingcap/pd/pull/1472) - -## TiKV - -+ 优化 Coprocessor 计算执行框架，完成 TableScan 算子，单 TableScan 即扫表操作性能提升 5% ~ 30% -+ 实现行 `BatchRows` 和列 `BatchColumn` 的定义 [#3660](https://github.com/tikv/tikv/pull/3660) - - 实现 `VectorLike` 使得编码和解码的数据能够用统一的方式访问 [#4242](https://github.com/tikv/tikv/pull/4242) - - 定义 `BatchExecutor` 接口，实现将请求转化为 `BatchExecutor` 的方法 [#4243](https://github.com/tikv/tikv/pull/4243) - - 实现将表达式树转化成 RPN 格式 [#4329](https://github.com/tikv/tikv/pull/4329) - - TableScan 算子实现为 Batch 方式，通过向量化计算加速计算 [#4351](https://github.com/tikv/tikv/pull/4351) -+ 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 -+ 支持 Raw Read 接口使用 Local Reader 进行读 [#4222](https://github.com/tikv/tikv/pull/4222) -+ 新增配置信息的 Metrics [#4206](https://github.com/tikv/tikv/pull/4206) -+ 新增 Key 越界的 Metrics [#4255](https://github.com/tikv/tikv/pull/4255) -+ 新增碰到扫越界错误时 Panic 或者报错选项 [#4254](https://github.com/tikv/tikv/pull/4254) -+ 增加 Insert 语义，只有在 Key 不存在的时候 Prewrite 才成功，消除 Batch Get [#4085](https://github.com/tikv/tikv/pull/4085) -+ Batch System 使用更加公平的 batch 策略 [#4200](https://github.com/tikv/tikv/pull/4200) -+ tikv-ctl 支持 Raw scan [#3825](https://github.com/tikv/tikv/pull/3825) - -## Tools - -+ TiDB Binlog - - 新增 Arbiter 工具支持从 Kafka 读取 binlog 同步到 MySQL - - Reparo 支持过滤不需要同步的文件 - - 支持同步 generated column -+ Lightning - - 支持禁用 TiKV periodic Level-1 compaction，当 TiKV 集群为 2.1.4 或更高时，在导入模式下会自动执行 Level-1 compaction [#119](https://github.com/pingcap/tidb-lightning/pull/119)，[#4199](https://github.com/tikv/tikv/pull/4199) - - 根据 `table_concurrency` 配置项限制 import engines 数量，默认值：16，防止过多占用 importer 磁盘空间 [#119](https://github.com/pingcap/tidb-lightning/pull/119) - - 支持保存中间状态的 SST 到磁盘，减少内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 优化 TiKV-Importer 导入性能，支持将大表的数据和索引分离导入 [#132](https://github.com/pingcap/tidb-lightning/pull/132) - - 支持 CSV 文件导入 [#111](https://github.com/pingcap/tidb-lightning/pull/111) -+ 数据同步对比工具 (sync-diff-inspector) - - 支持使用 TiDB 统计信息来划分对比的 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) - - 支持使用多个 column 来划分对比的 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) diff --git a/v2.1/releases/3.0.0-rc.1.md b/v2.1/releases/3.0.0-rc.1.md deleted file mode 100644 index 96a8eb344669..000000000000 --- a/v2.1/releases/3.0.0-rc.1.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: TiDB 3.0.0-rc.1 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.1 Release Notes - -发版日期：2019 年 5 月 10 日 - -TiDB 版本：3.0.0-rc.1 - -TiDB Ansible 版本：3.0.0-rc.1 - -## Overview - -2019 年 5 月 10 日，TiDB 发布 3.0.0-rc.1 版，对应的 TiDB Ansible 版本为 3.0.0-rc.1。相比 3.0.0-beta.1 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 利用列之间的顺序相关性提升代价估算准确度，并提供启发式参数 `tidb_opt_correlation_exp_factor` 用于控制在相关性无法被直接用于估算的场景下对索引扫描的偏好程度。[#9839](https://github.com/pingcap/tidb/pull/9839) - - 当过滤条件中包含相关列时，在抽取复合索引的访问条件时尽可能多地匹配索引的前缀列。[#10053](https://github.com/pingcap/tidb/pull/10053) - - 用动态规划决定连接的执行顺序，当参与连接的表数量不多于 `tidb_opt_join_reorder_threshold` 时启用。[#8816](https://github.com/pingcap/tidb/pull/8816) - - 在构造 Index Join 的的内表中，以复合索引作为访问条件时，尽可能多地匹配索引的前缀列。[#8471](https://github.com/pingcap/tidb/pull/8471) - - 提升对单列索引上值为 NULL 的行数估算准确度。[#9474](https://github.com/pingcap/tidb/pull/9474) - - 在逻辑优化阶段消除聚合函数时特殊处理 `GROUP_CONCAT` ，防止产生错误的执行结果。[#9967](https://github.com/pingcap/tidb/pull/9967) - - 当过滤条件为常量时，正确地将它下推到连接算子的子节点上。[#9848](https://github.com/pingcap/tidb/pull/9848) - - 在逻辑优化阶段列剪裁时特殊处理一些函数，例如 `RAND()` ，防止产生和 MySQL 不兼容的执行结果。[#10064](https://github.com/pingcap/tidb/pull/10064) - - 支持 `FAST ANALYZE`，通过`tidb_enable_fast_analyze` 变量控制。该特性通过用对 Region 进行采样取代扫描整个 region 的方式加速统计信息收集。[#10258](https://github.com/pingcap/tidb/pull/10258) - - 支持 `SQL PLAN MANAGEMENT`。该特性通过对 SQL 进行执行计划绑定，以确保执行稳定性。该特性目前处于测试阶段，仅支持对 SELECT 语句使用绑定的执行计划，不建议在生产场景中直接使用。[#10284](https://github.com/pingcap/tidb/pull/10284) - -+ 执行引擎 - - 支持对 `TableReader`、`IndexReader` 和 `IndexLookupReader` 算子进行内存追踪控制。[#10003](https://github.com/pingcap/tidb/pull/10003) - - 在慢日志中展示更多 COPROCESSOR 端执行任务相关细节。如 COPROCESSOR 任务数，平均/最长/90% 执行/等待时间，执行/等待时间最长的 TiKV 地址等。[#10165](https://github.com/pingcap/tidb/pull/10165) - - 支持 PREPARE 不含占位符的 DDL 语句。[#10144](https://github.com/pingcap/tidb/pull/10144) - -+ Server - - TiDB 启动时，只允许 DDL owner 执行 bootstrap [#10029](https://github.com/pingcap/tidb/pull/10029) - - 新增 `tidb_skip_isolation_level_check` 变量控制检查隔离级别设置为 SERIALIZABLE 时不报错 [#10065](https://github.com/pingcap/tidb/pull/10065) - - 在慢日志中，将隐式提交的时间与 SQL 执行时间融合在一起 [#10294](https://github.com/pingcap/tidb/pull/10294) - + RBAC 权限管理 - - 支持 `SHOW GRANT` [#10016](https://github.com/pingcap/tidb/pull/10016) - - 支持 `SET DEFAULT ROLE` [#9949](https://github.com/pingcap/tidb/pull/9949) - - 支持 `GRANT ROLE` [#9721](https://github.com/pingcap/tidb/pull/9721) - - 修正了插件退出时导致 TiDB 退出的问题 [#9889](https://github.com/pingcap/tidb/pull/9889) - - 修正只读语句被错误地放到事务历史中的问题 [#9723](https://github.com/pingcap/tidb/pull/9723) - - kill 语句可以更快的结束 SQL 的执行，并快速释放资源 [#9844](https://github.com/pingcap/tidb/pull/9844) - - 增加启动选项 `config-check` 来检查配置文件的合法性 [#9855](https://github.com/pingcap/tidb/pull/9855) - - 修正非严格模式下对于写入 NULL 字段的合法性检查 [#10161](https://github.com/pingcap/tidb/pull/10161) - -+ DDL - - 为 CREATE TABLE 添加了 pre_split_regions 选项，该选项可以在建表时预先分配 Table Region，避免建表后大量写入造成的写热点 [#10138](https://github.com/pingcap/tidb/pull/10138) - - 优化了部分 DDL 语句的执行性能 [#10170](https://github.com/pingcap/tidb/pull/10170) - - FULLTEXT KEY 新增不支持全文索引的 warning [#9821](https://github.com/pingcap/tidb/pull/9821) - - 修正了旧版本 TiDB 中，UTF8 和 UTF8MB4 编码的兼容性问题 [#9820](https://github.com/pingcap/tidb/pull/9820) - - 修正了一个表的 shard_row_id_bits 的潜在 BUG [#9868](https://github.com/pingcap/tidb/pull/9868) - - 修正了 ALTER TABLE Charset 后，Column Charset 不会跟随变化的 BUG [#9790](https://github.com/pingcap/tidb/pull/9790) - - 修正了使用 BINARY/BIT 作为 Column Default Value 时，SHOW COLUMN 可能出错的 BUG [#9897](https://github.com/pingcap/tidb/pull/9897) - - 修正了 SHOW FULL COLUMNS 语句中，CHARSET / COLLATION 显示的兼容性问题 [#10007](https://github.com/pingcap/tidb/pull/10007) - - 现在 SHOW COLLATIONS 语句只会列出 TiDB 所实际支持的 COLLATIONS [#10186](https://github.com/pingcap/tidb/pull/10186) - -## PD - -+ 升级 ETCD 版本 [#1452](https://github.com/pingcap/pd/pull/1452) - - 统一 etcd 的日志格式与 pd server 一致 - - 修复 prevote 可能无法选出 Leader 的问题 - - 快速 drop 掉会失败的 propose 和 read 请求，减少阻塞后面的请求时间 - - 修复 Lease 的死锁问题 -+ 修复 store 读热点的 keys 统计不正确问题 [#1487](https://github.com/pingcap/pd/pull/1487) -+ 支持从单一 PD 节点强制重建 PD 集群 [#1485](https://github.com/pingcap/pd/pull/1485) -+ 修复 Scatter Region 产生无效 Operator Step 的问题 [#1482](https://github.com/pingcap/pd/pull/1482) -+ 修复 Region Merge Operator 超时时间过短的问题 [#1495](https://github.com/pingcap/pd/pull/1495) -+ 热点调度使用高优先级 [#1492](https://github.com/pingcap/pd/pull/1492) -+ 添加 PD server 端处理 TSO 请求的耗时 Metrics [#1502](https://github.com/pingcap/pd/pull/1502) -+ 添加相对应的 Store ID 和 Address 到 store 相关的 Metrics [#1506](https://github.com/pingcap/pd/pull/1506) -+ 支持 GetOperator 服务 [#1477](https://github.com/pingcap/pd/pull/1477) -+ 修复 Heartbeat stream 下发送 error 找不到 store 的问题 [#1521](https://github.com/pingcap/pd/pull/1521) - -## TiKV - -+ Engine - - 修复读流量统计不准确问题 [#4436](https://github.com/tikv/tikv/pull/4436) - - 修复 prefix extractor panic 的问题 [#4503](https://github.com/tikv/tikv/pull/4503) - - 优化内存管理，减少 `Iterator Key Bound Option` 的内存分配和拷贝 [#4537](https://github.com/tikv/tikv/pull/4537) - - 修复 Merge Region 时未考虑 Learner log gap 造成的 panic 问题 [#4559](https://github.com/tikv/tikv/pull/4559) - - 支持不同的 `column families` 共享 `block cache` [#4612](https://github.com/tikv/tikv/pull/4612) -+ Server - - 减少 `batch commands` 的上下文切换开销 [#4473](https://github.com/tikv/tikv/pull/4473) - - 检查 seek iterator status 的合法性 [#4470](https://github.com/tikv/tikv/pull/4470) -+ RaftStore - - 可配置化 `properties index distance` [#4517](https://github.com/tikv/tikv/pull/4517) -+ Coprocessor - - 新增 batch index scan executor [#4419](https://github.com/tikv/tikv/pull/4419) - - 新增向量化 evaluation 框架 [#4322](https://github.com/tikv/tikv/pull/4322) - - 新增 batch 执行器统计框架 [#4433](https://github.com/tikv/tikv/pull/4433) - - 构建 RPN expression 时检查 max column 以防止 evaluation 阶段 column offset 越界的问题 [#4481](https://github.com/tikv/tikv/pull/4481) - - 实现 `BatchLimitExecutor` [#4469](https://github.com/tikv/tikv/pull/4469) - - ReadPool 使用 `tokio-threadpool` 替换原本的 `futures-cpupool`，减少 context switch [#4486](https://github.com/tikv/tikv/pull/4486) - - 新增 batch 聚合框架 [#4533](https://github.com/tikv/tikv/pull/4533) - - 新增 `BatchSelectionExecutor` [#4562](https://github.com/tikv/tikv/pull/4562) - - 实现 batch aggression function `AVG` [#4570](https://github.com/tikv/tikv/pull/4570) - - 实现 RPN function `LogicalAnd` [#4575](https://github.com/tikv/tikv/pull/4575) -+ Misc - - 支持选用 tcmalloc 为内存分配器 [#4370](https://github.com/tikv/tikv/pull/4370) - -## Tools - -+ TiDB Binlog - - 修复 unsigned int 类型的主键列的 binlog 数据为负数，造成同步出错中断的问题 [#573](https://github.com/pingcap/tidb-binlog/pull/573) - - 删除下游是 pb 时的压缩选项，修改下游名字 pb 成 file [#559](https://github.com/pingcap/tidb-binlog/pull/559) - - Pump 新增 storage.sync-log 配置项，支持 Pump 本地存储异步刷盘 [#509](https://github.com/pingcap/tidb-binlog/pull/509) - - Pump 和 Drainer 之间通讯支持流量压缩 [#495](https://github.com/pingcap/tidb-binlog/pull/495) - - Drainer 新增 syncer.sql-mode 配置项，支持使用不同 sql-mode 解析 DDL query [#511](https://github.com/pingcap/tidb-binlog/pull/511) - - Drainer 新增 syncer.ignore-table 配置项，支持过滤不需要同步的表 [#520](https://github.com/pingcap/tidb-binlog/pull/520) -+ Lightning - - 使用 row id 或者列的默认值填充 dump 文件中缺少的 column 数据 [#170](https://github.com/pingcap/tidb-lightning/pull/170) - - Importer 修复部分 SST 导入失败依然返回导入成功的 bug [#4566](https://github.com/tikv/tikv/pull/4566) - - Importer 支持 upload SST 到 TiKV 限速 [#4412](https://github.com/tikv/tikv/pull/4412) - - Lightning 优化导入表的顺序，按照表的数据大小顺序进行导入，减少导入过程中大表执行 checksum 和 Analyze 对集群的影响，并且提高 Checksum 和 Analyze 的成功率 [#156](https://github.com/pingcap/tidb-lightning/pull/156) - - 提升 Lightning encode SQL 性能，性能提升 50%，直接解析数据源文件内容成 TiDB 的 types.Datum，省去 KV encoder 的多余解析工作 [#145](https://github.com/pingcap/tidb-lightning/pull/145) - - 日志格式改为 [Unified Log Format](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md) [#162](https://github.com/pingcap/tidb-lightning/pull/162) - - 新增一些命令行选项，即使缺少配置文件也能使用。[#157](https://github.com/pingcap/tidb-lightning/pull/157) -+ 数据同步对比工具 (sync-diff-inspector) - - 支持 checkpoint，记录校验状态，重启后从上次进度继续校验 [#224](https://github.com/pingcap/tidb-tools/pull/224) - - 增加配置项 only-use-checksum，只通过计算 checksum 来检查数据是否一致 [#215](https://github.com/pingcap/tidb-tools/pull/215) - -## TiDB Ansible - -+ TiKV 监控变更以及更新 Ansible、Grafana、Prometheus 版本 [#727](https://github.com/pingcap/tidb-ansible/pull/727) - - summary 监控适用于用户查看集群状态 - - trouble_shooting 监控适用于 DBA 排查问题 - - details 监控适用于开发分析问题 -+ 修复下载 Kafka 版本 Binlog 失败的 BUG [#730](https://github.com/pingcap/tidb-ansible/pull/730) -+ 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 [#733](https://github.com/pingcap/tidb-ansible/pull/733) -+ 滚动升级时的版本检测改为多并发 [#736](https://github.com/pingcap/tidb-ansible/pull/736) -+ 更新 README 中文档链接[#740](https://github.com/pingcap/tidb-ansible/pull/740) -+ 移除重复的 TiKV 监控项，新增 trouble shooting 监控项 [#735](https://github.com/pingcap/tidb-ansible/pull/735) -+ 优化 `table-regions.py` 脚本，按表显示 leader 分布 [#739](https://github.com/pingcap/tidb-ansible/pull/739) -+ 更新 drainer 配置文件 [#745](https://github.com/pingcap/tidb-ansible/pull/745) -+ 优化 TiDB 监控，新增以 SQL 类别显示延迟的监控项 [#747](https://github.com/pingcap/tidb-ansible/pull/747) -+ 更新 Lightning 配置文件，新增 tidb_lightning_ctl 脚本 [#1e946f8](https://github.com/pingcap/tidb-ansible/commit/1e946f89908e8fd6ef84128c6da3064ddfccf6a8) diff --git a/v2.1/releases/3.0.0-rc.2.md b/v2.1/releases/3.0.0-rc.2.md deleted file mode 100644 index 930f646c735c..000000000000 --- a/v2.1/releases/3.0.0-rc.2.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: TiDB 3.0.0-rc.2 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.2 Release Notes - -发版日期：2019 年 5 月 28 日 - -TiDB 版本：3.0.0-rc.2 - -TiDB Ansible 版本：3.0.0-rc.2 - -## Overview - -2019 年 5 月 28 日，TiDB 发布 3.0.0-rc.2 版本，对应的 TiDB Ansible 版本为 3.0.0-rc.2。相比 3.0.0-rc.1 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 在更多的场景中支持 Index Join [#10540](https://github.com/pingcap/tidb/pull/10540) - - 支持导出历史统计信息 [#10291](https://github.com/pingcap/tidb/pull/10291) - - 支持对单调递增的索引列增量 `Analyze` [#10355](https://github.com/pingcap/tidb/pull/10355) - - 忽略 `Order By` 子句中的 NULL 值 [#10488](https://github.com/pingcap/tidb/pull/10488) - - 修复精简列信息时逻辑算子 `UnionAll` 的 Schema 信息的计算不正确的问题 [#10384](https://github.com/pingcap/tidb/pull/10384) - - 下推 `Not` 操作符时避免修改原表达式 [#10363](https://github.com/pingcap/tidb/pull/10363) - - 支持导入导出列的关联性信息 [#10573](https://github.com/pingcap/tidb/pull/10573) - -+ 执行引擎 - - 有唯一索引的虚拟生成列可以在 `replace on duplicate key update`/`insert on duplicate key update` 语句中被正确地处理 [#10370](https://github.com/pingcap/tidb/pull/10370) - - 修复 CHAR 列上的扫描范围计算 [#10124](https://github.com/pingcap/tidb/pull/10124) - - 修复 `PointGet` 处理负数不正确问题 [#10113](https://github.com/pingcap/tidb/pull/10113) - - 合并具有相同窗口名的窗口函数，提高执行效率 [#9866](https://github.com/pingcap/tidb/pull/9866) - - 窗口函数中 Range Frame 可以无需 `Order By` 子句 [#10496](https://github.com/pingcap/tidb/pull/10496) - -+ Server - - 修复 TiKV 故障时，TiDB 不断创建与 TiKV 的新连接的问题 [#10301](https://github.com/pingcap/tidb/pull/10301) - - `tidb_disable_txn_auto_retry` 不再只影响写入冲突错误，而是影响所有的可重试错误 [#10339](https://github.com/pingcap/tidb/pull/10339) - - 不带参数的 DDL 语句可以通过 `prepare`/`execute` 来执行 [#10144](https://github.com/pingcap/tidb/pull/10144) - - 新增 `tidb_back_off_weight` 变量，控制 TiDB 内部 back off 时间的长短 [#10266](https://github.com/pingcap/tidb/pull/10266) - - `tidb_disable_txn_auto_retry` 的默认值改为 on，即默认情况下，TiDB 不会重试非自动提交的事务 [#10266](https://github.com/pingcap/tidb/pull/10266) - - 修复 RBAC 中对 role 的数据库权限的判断不正确的问题 [#10261](https://github.com/pingcap/tidb/pull/10261) - - 支持悲观事务模型（实验性）[#10297](https://github.com/pingcap/tidb/pull/10297) - - 降低某些情况下处理锁冲突时的等待时间 [#10006](https://github.com/pingcap/tidb/pull/10006) - - 重构 Region cache，增加在 Region 故障时的轮询逻辑 [#10256](https://github.com/pingcap/tidb/pull/10256) - - 新增 `tidb_low_resolution_tso` 变量，控制批量获取 `tso` 个数，减少事务获取 `tso` 的次数，以适应某些数据一致性要求较低的场景 [#10428](https://github.com/pingcap/tidb/pull/10428) - -+ DDL - - 修复旧版本的 TiDB 存储的字符集名称大写的问题 [#10272](https://github.com/pingcap/tidb/pull/10272) - - 支持 table partition 预分裂 Region 功能，该选项可以在建表时预先分配 table Region，避免建表后大量写入造成的写热点 [#10221](https://github.com/pingcap/tidb/pull/10221) - - 修复某些情况下 TiDB 更新版本信息到 PD 不准确的问题 [#10324](https://github.com/pingcap/tidb/pull/10324) - - 支持通过 `alter schema` 语句修改数据库 charset 和 collation [#10393](https://github.com/pingcap/tidb/pull/10393) - - 支持通过语句按指定表的索引及范围分裂 Region，用于缓解热点问题 [#10203](https://github.com/pingcap/tidb/pull/10203) - - 禁止 `alter table` 语句修改 `decimal` 列的精度 [#10433](https://github.com/pingcap/tidb/pull/10433) - - 修复 hash partition 中对表达式和函数的约束 [#10273](https://github.com/pingcap/tidb/pull/10273) - - 修复某些情况下对含有 partition 的 table 添加索引时引发 TiDB panic 的问题 [#10475](https://github.com/pingcap/tidb/pull/10475) - - 添加对某些极端情况下导致 schema 出错的防护功能 [#10464](https://github.com/pingcap/tidb/pull/10464) - - 创建 range partition 若有单列或者创建 hash partition 时默认开启分区功能 [#9936](https://github.com/pingcap/tidb/pull/9936) - -## PD - -- 默认开启 Region storage 将 Region 元信息存储到 Region storage 中 [#1524](https://github.com/pingcap/pd/pull/1524) -- 修复热点调度受其他调度器抢占的问题 [#1522](https://github.com/pingcap/pd/pull/1522) -- 修复 Leader 优先级不生效的问题 [#1533](https://github.com/pingcap/pd/pull/1533) -- 新增 `ScanRegions` 的 gRPC 接口 [#1535](https://github.com/pingcap/pd/pull/1535) -- 主动下发 operator 加快调度速度 [#1536](https://github.com/pingcap/pd/pull/1536) -- 添加 store limit 机制，限制单个 store 的调度速度 [#1474](https://github.com/pingcap/pd/pull/1474) -- 修复 `config` 状态不一致的问题 [#1476](https://github.com/pingcap/pd/pull/1476) - -## TiKV - -+ Engine - - 支持多个 column family 共享 block cache [#4563](https://github.com/tikv/tikv/pull/4563) -+ Server - - 移除 txn scheduler [#4098](https://github.com/tikv/tikv/pull/4098) - - 支持悲观锁事务 [#4698](https://github.com/tikv/tikv/pull/4698) -+ Raftstore - - 新增 hibernate Regions 特性，减少 raftstore CPU 的消耗 [#4591](https://github.com/tikv/tikv/pull/4591) - - 移除 local reader 线程 [#4558](https://github.com/tikv/tikv/pull/4558) - - 修复 Leader 不回复 Learner `ReadIndex` 请求的问题 [#4653](https://github.com/tikv/tikv/pull/4653) - - 修复在某些情况下 transfer leader 失败的问题 [#4684](https://github.com/tikv/tikv/pull/4684) - - 修复在某些情况下可能发生的脏读问题 [#4688](https://github.com/tikv/tikv/pull/4688) - - 修复在某些情况下 snapshot 少包含数据的问题 [#4716](https://github.com/tikv/tikv/pull/4716) -+ Coprocessor - - 新增更多的 RPN 函数 - - `LogicalOr` [#4691](https://github.com/tikv/tikv/pull/4601) - - `LTReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `LEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `GTReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `GEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `NEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `EQReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `IsNull` [#4720](https://github.com/tikv/tikv/pull/4720) - - `IsTrue` [#4720](https://github.com/tikv/tikv/pull/4720) - - `IsFalse` [#4720](https://github.com/tikv/tikv/pull/4720) - - 支持 `Int` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Decimal` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `String` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Time` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Duration` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Json` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Int` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Real` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Decimal` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Int` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Real` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Decimal` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Int` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - - 支持 `Real` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - - 支持 `Decimal` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - -## Tools - -+ TiDB Binlog - - Drainer 增加下游同步延迟监控项 `checkpoint_delay` [#594](https://github.com/pingcap/tidb-binlog/pull/594) - -+ TiDB Lightning - - 支持数据库合并，数据表合并同步功能 [#95](https://github.com/pingcap/tidb-lightning/pull/95) - - 新增 KV 写入失败重试机制 [#176](https://github.com/pingcap/tidb-lightning/pull/176) - - 配置项 `table-concurrency` 默认值修改为 6 [#175](https://github.com/pingcap/tidb-lightning/pull/175) - - 减少必要的配置项，`tidb.port` 和 `tidb..pd-addr` 支持自动获取 [#173](https://github.com/pingcap/tidb-lightning/pull/173) diff --git a/v2.1/releases/3.0.0-rc.3.md b/v2.1/releases/3.0.0-rc.3.md deleted file mode 100644 index 141b3c897e54..000000000000 --- a/v2.1/releases/3.0.0-rc.3.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: TiDB 3.0.0-rc.3 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.3 Release Notes - -发版日期：2019 年 6 月 21 日 - -TiDB 版本：3.0.0-rc.3 - -TiDB Ansible 版本：3.0.0-rc.3 - -## Overview - -2019 年 6 月 21 日，TiDB 发布 3.0.0-rc.3 版本，对应的 TiDB Ansible 版本为 3.0.0-rc.3。相比 3.0.0-rc.2 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 删除收集虚拟生成列的统计信息功能 [#10629](https://github.com/pingcap/tidb/pull/10629) - - 修复点查时主键常量溢出的问题 [#10699](https://github.com/pingcap/tidb/pull/10699) - - 修复 `fast analyze` 因使用未初始化的信息导致 panic [#10691](https://github.com/pingcap/tidb/pull/10691) - - 修复 prepare `create view` 语句执行过程中因列信息错误导致执行失败的问题 [#10713](https://github.com/pingcap/tidb/pull/10713) - - 修复在处理 window function 时列信息未拷贝的问题 [#10720](https://github.com/pingcap/tidb/pull/10720) - - 修复 index join 中内表过滤条件在某些情况下的选择率估计错误的问题 [#10854](https://github.com/pingcap/tidb/pull/10854) - - 新增变量 `stats-lease` 值为 0 时系统自动加载统计数据功能 [#10811](https://github.com/pingcap/tidb/pull/10811) - -+ 执行引擎 - - 修复在 `StreamAggExec` 调用 `Close` 函数资源未正确释放问题 [#10636](https://github.com/pingcap/tidb/pull/10636) - - 修复对分区表执行 `show create table` 结果中 `table_option` 与 `partition_options` 顺序不正确问题 [#10689](https://github.com/pingcap/tidb/pull/10689) - - 通过支持逆序扫数据提升 `admin show ddl jobs` 的性能 [#10687](https://github.com/pingcap/tidb/pull/10687) - - 修复 RBAC 中对 `show grants` 语句带 `current_user` 字段时结果与 MySQL 不兼容的问题 [#10684](https://github.com/pingcap/tidb/pull/10684) - - 修复 UUID 在多节点上可能生成重复值的问题 [#10712](https://github.com/pingcap/tidb/pull/10712) - - 修复 `explain` 没考虑 `show view` 权限的问题 [#10635](https://github.com/pingcap/tidb/pull/10635) - - 新增 `split table region` 语句，手动分裂表的 Region，缓解热点问题 [#10765](https://github.com/pingcap/tidb/pull/10765) - - 新增 `split index region` 语句，手动分裂索引的 region 缓解热点问题 [#10764](https://github.com/pingcap/tidb/pull/10764) - - 修复连续执行多个 `create user`、`grant` 或 `revoke` 等类似语句执行不正确的问题 [#10737](https://github.com/pingcap/tidb/pull/10737) - - 新增黑名单禁止下推表达式到 coprocessor 功能 [#10791](https://github.com/pingcap/tidb/pull/10791) - - 新增查询超出内存配置限制时打印 `expensive query` 日志的功能 [#10849](https://github.com/pingcap/tidb/pull/10849) - - 新增 `bind-info-lease` 配置项控制修改绑定执行计划的更新时间 [#10727](https://github.com/pingcap/tidb/pull/10727) - - 修复因持有 `execdetails.ExecDetails` 指针时 Coprocessor 的资源无法快速释放导致的在大并发场景下 OOM 的问题 [#10832](https://github.com/pingcap/tidb/pull/10832) - - 修复某些情况下 `kill` 语句导致的 panic 问题 [#10876](https://github.com/pingcap/tidb/pull/10876) - -+ Server - - 修复 GC 时可能发生的 goroutine 泄露问题 [#10683](https://github.com/pingcap/tidb/pull/10683) - - 支持 slow query 里面显示 `host` 信息 [#10693](https://github.com/pingcap/tidb/pull/10693) - - 支持循环利用与 TiKV 交互的空闲链接 [#10632](https://github.com/pingcap/tidb/pull/10632) - - 修复 RBAC 对开启 `skip-grant-table` 选项的支持问题 [#10738](https://github.com/pingcap/tidb/pull/10738) - - 修复 `pessimistic-txn` 配置失效的问题 [#10825](https://github.com/pingcap/tidb/pull/10825) - - 修复主动取消的 ticlient 请求还会被重试的问题 [#10850](https://github.com/pingcap/tidb/pull/10850) - - 提高在悲观事务和乐观事务冲突情况下的性能 [#10881](https://github.com/pingcap/tidb/pull/10881) - -+ DDL - - 修复在使用 `alter table` 修改 charset 时导致 `blob` 类型改变的问题 [#10698](https://github.com/pingcap/tidb/pull/10698) - - 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 [#10794](https://github.com/pingcap/tidb/pull/10794) - - 禁止通过 `alter table` 添加存储的生成列 [#10808](https://github.com/pingcap/tidb/pull/10808) - - 优化无效 DDL 元信息存活时间，使集群升级后一段时间 DDL 操作比较慢的情况变短 [#10795](https://github.com/pingcap/tidb/pull/10795) - -## PD - -- 新增 `enable-two-way-merge` 配置项，控制合并时仅允许单向合并 [#1583](https://github.com/pingcap/pd/pull/1583) -- 新增 `AddLightLearner` 和 `AddLightPeer` 的调度操作，Region Scatter 调度不受 limit 机制限 [#1563](https://github.com/pingcap/pd/pull/1563) -- 修复系统启动时因数据可能只进行一副本复制而导致可靠性不足的问题 [#1581](https://github.com/pingcap/pd/pull/1581) -- 优化配置检查逻辑，防止配置项错误 [#1585](https://github.com/pingcap/pd/pull/1585) -- 调整 `store-balance-rate` 配置的定义为每分钟产生 balance operator 数量的上限 [#1591](https://github.com/pingcap/pd/pull/1591) -- 修复 store 可能一直无法产生调度操作的问题 [#1590](https://github.com/pingcap/pd/pull/1590) - -## TiKV - -+ Engine - - 修复因迭代器未检查状态导致系统生成残缺 snapshot 的问题 [#4936](https://github.com/tikv/tikv/pull/4936) - - 修复在机器异常掉电时由于接收 snapshot 未及时将数据刷新到磁盘导致丢数据的问题 [#4937](https://github.com/tikv/tikv/pull/4937) - -+ Server - - 新增检查 `block-size` 配置的有效性功能 [#4928](https://github.com/tikv/tikv/pull/4928) - - 新增 read index 相关监控项 [#4830](https://github.com/tikv/tikv/pull/4830) - - 新增 GC worker 相关监控项 [#4922](https://github.com/tikv/tikv/pull/4922) - -+ Raftstore - - 修复 local reader 的 cache 没有正确清理的问题 [#4778](https://github.com/tikv/tikv/pull/4778) - - 修复进行 transfer leader 和 conf change 时可能导致请求延迟增加的问题 [#4734](https://github.com/tikv/tikv/pull/4734) - - 修复误报 stale command 的问题 [#4682](https://github.com/tikv/tikv/pull/4682) - - 修复 command 可能一直 pending 的问题 [#4810](https://github.com/tikv/tikv/pull/4810) - - 修复 snapshot 文件未及时落盘而导致掉电后文件损坏的问题 [#4807](https://github.com/tikv/tikv/pull/4807)，[#4850](https://github.com/tikv/tikv/pull/4850) - -+ Coprocessor - - 向量计算支持 Top-N [#4827](https://github.com/tikv/tikv/pull/4827) - - 向量计算支持 Stream 聚合 [#4786](https://github.com/tikv/tikv/pull/4786) - - 向量计算中支持 AVG 聚合函 [#4777](https://github.com/tikv/tikv/pull/4777) - - 向量计算中支持 First 聚合函数 [#4771](https://github.com/tikv/tikv/pull/4771) - - 向量计算中支持 SUM 聚合函数 [#4797](https://github.com/tikv/tikv/pull/4797) - - 向量计算中支持 MAX/MIN 聚合函数 [#4837](https://github.com/tikv/tikv/pull/4837) - - 向量计算中支持 Like 表达式 [#4747](https://github.com/tikv/tikv/pull/4747) - - 向量计算中支持 MultiplyDecimal 表达式 [#4849](https://github.com/tikv/tikv/pull/4849 ) - - 向量计算中支持 BitAnd/BitOr/BitXor 表达式 [#4724](https://github.com/tikv/tikv/pull/4724) - - 向量计算中支持 UnaryNot 表达式 [#4808](https://github.com/tikv/tikv/pull/4808) - -+ Transaction - - 修复悲观事务中非悲观锁冲突导致出错的问题 [#4801](https://github.com/tikv/tikv/pull/4801)，[#4883](https://github.com/tikv/tikv/pull/4883) - - 减少在开启悲观事务后乐观事务的无用计算，提高性能 [#4813](https://github.com/tikv/tikv/pull/4813) - - 新增单语句 rollback，保证在当前语句发生死锁时不需要 rollback 整个事务 [#4848](https://github.com/tikv/tikv/pull/4848) - - 新增悲观事务相关监控项 [#4852](https://github.com/tikv/tikv/pull/4852) - - 支持 `ResolveLockLite` 命令用于轻量级清锁以优化在冲突严重时的性能 [#4882](https://github.com/tikv/tikv/pull/4882) - -+ tikv-ctl - - 新增 `bad-regions` 命令支持检测更多的异常情况 [#4862](https://github.com/tikv/tikv/pull/4862) - - `tombstone` 命令新增强制执行功能 [#4862](https://github.com/tikv/tikv/pull/4862) - -+ Misc - - 新增 `dist_release` 编译命令 [#4841](https://github.com/tikv/tikv/pull/4841) - -## Tools - -+ TiDB Binlog - - 修复 Pump 因写入失败时未检查返回值导致偏移量错误的问题 [#640](https://github.com/pingcap/tidb-binlog/pull/640) - - Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 [#634](https://github.com/pingcap/tidb-binlog/pull/634) - - Pump 新增 `GetMvccByEncodeKey` 函数，加快事务状态查询 [#632](https://github.com/pingcap/tidb-binlog/pull/632) - -## TiDB Ansible - -- 新增预测集群最大 QPS 的监控项（默认隐藏）[#f5cfa4d](https://github.com/pingcap/tidb-ansible/commit/f5cfa4d903bbcd77e01eddc8d31eabb6e6157f73) \ No newline at end of file diff --git a/v2.1/releases/3.0.1.md b/v2.1/releases/3.0.1.md deleted file mode 100644 index e8f66f04e20d..000000000000 --- a/v2.1/releases/3.0.1.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: TiDB 3.0.1 Release Notes -category: Releases ---- - -# TiDB 3.0.1 Release Notes - -发版日期：2019 年 7 月 16 日 - -TiDB 版本：3.0.1 - -TiDB Ansible 版本：3.0.1 - -## TiDB - -+ 新增对 `MAX_EXECUTION_TIME` 特性的支持 [#11026](https://github.com/pingcap/tidb/pull/11026) -+ 新增 `tidb_wait_split_region_finish_backoff` Session 变量，用于控制 Region 打散的 Backoff 时间 [#11166](https://github.com/pingcap/tidb/pull/11166) -+ 新增根据负载情况自动调整 Auto ID 分配的步长功能，步长自动调整范围最小 1000，最大 2000000 [#11006](https://github.com/pingcap/tidb/pull/11006) -+ 新增 `ADMIN PLUGINS ENABLE`/`ADMIN PLUGINS DISABLE` SQL 语句，管理 Plugin 的动态开启或关闭 [#11157](https://github.com/pingcap/tidb/pull/11157) -+ Audit Plugin 新增审记连接功能 [#11013](https://github.com/pingcap/tidb/pull/11013) -+ 修改 Region 打散时的默认行为为等待 PD 调度完成 [#11166](https://github.com/pingcap/tidb/pull/11166) -+ 禁止 Window Function 在 Prepare Plan Cache 中被缓存，避免某些情况下出现结果不正确的问题 [#11048](https://github.com/pingcap/tidb/pull/11048) -+ 禁止使用 Alter 语句修改 Stored Generated Column 的定义 [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 禁止将 Virtual Generated Column 更改为 Stored Generated Column [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 禁止改变带有索引的 Generated Column 的表达式 [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 支持 TiDB 在 ARM64 架构下的编译 [#11150](https://github.com/pingcap/tidb/pull/11150) -+ 支持修改 Database/Table 的 Collate，条件限制为 Database/Table 字符集必须是 UTF8/UTF8MB4 [#11086](https://github.com/pingcap/tidb/pull/11086) -+ 修复 `UPDATE … SELECT` 语句中，`SELECT` 子查询没有解析到 `UPDATE` 表达式中的列而被误裁剪，导致报错的问题 [#11252](https://github.com/pingcap/tidb/pull/11252) -+ 修复点查时，某列被查询多次而且结果为 NULL 时会 Panic 的问题 [#11226](https://github.com/pingcap/tidb/pull/11226) -+ 修复 `RAND` 函数由于非线程安全的 `rand.Rand` 导致的 Data Race 问题 [#11169](https://github.com/pingcap/tidb/pull/11169) -+ 修复 `oom-action="cancel"` 时，某些情况下 SQL 内存使用超阈值没有被取消执行，返回结果不正确的问题 [#11004](https://github.com/pingcap/tidb/pull/11004) -+ 修复 MemTracker 未正确清理统计的内存使用值导致 `SHOW PROCESSLIST` 显示内存使用不为 0 的问题 [#10970](https://github.com/pingcap/tidb/pull/10970) -+ 修复某些情况下整数和非整数比较结果不正确的问题 [#11194](https://github.com/pingcap/tidb/pull/11194) -+ 修复在显式事务中查询对 Table Partition 的查询包含谓词时，查询结果不正确的问题 [#11196](https://github.com/pingcap/tidb/pull/11196) -+ 修复 DDL Job 由于 `infoHandle` 可能为 `NULL` 导致 Panic 的问题 [#11022](https://github.com/pingcap/tidb/pull/11022) -+ 修复嵌套聚合查询时，由于被查询列在子查询中没有引用而被误裁剪导致查询结果错误的问题 [#11020](https://github.com/pingcap/tidb/pull/11020) -+ 修复 `Sleep` 函数响应 Kill 命令不及时的问题 [#11028](https://github.com/pingcap/tidb/pull/11028) -+ 修复 `SHOW PROCESSLIST` 命令显示的 `DB` 和 `INFO` 列与 MySQL 不兼容的问题 [#11003](https://github.com/pingcap/tidb/pull/11003) -+ 修复 `skip-grant-table=true` 时，`FLUSH PRIVILEGES` 语句导致系统 Panic 的问题 [#11027](https://github.com/pingcap/tidb/pull/11027) -+ 修复表主键为 `UNSIGNED` 整数时，`FAST ANALYZE` 收集主键的统计信息不正确的问题 [#11099](https://github.com/pingcap/tidb/pull/11099) -+ 修复某些情况下 `FAST ANALYZE` 语句报 “invalid key” Error 的问题 [#11098](https://github.com/pingcap/tidb/pull/11098) -+ 修复 `CURRENT_TIMESTAMP` 作为列的默认值且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11088](https://github.com/pingcap/tidb/pull/11088) -+ 修复窗口函数报错时函数名没有小写的问题，兼容 MySQL [#11118](https://github.com/pingcap/tidb/pull/11118) -+ 修复 TiKV Client Batch gRPC 的后台线程 panic 后导致 TiDB 无法正常连接 TiKV 进而无法提供服务的问题 [#11101](https://github.com/pingcap/tidb/pull/11101) -+ 修复 `SetVar` 方法由于字符串浅拷贝导致设置的变量不正确的问题 [#11044](https://github.com/pingcap/tidb/pull/11044) -+ 修复 `INSERT … ON DUPLICATE` 语句作用在 Table Partition 时执行失败报错的问题 [#11231](https://github.com/pingcap/tidb/pull/11231) -+ 悲观锁（实验性特性） - - 修复悲观锁进行点查且数据为空时，由于行锁未生效导致结果不正确的问题 [#10976](https://github.com/pingcap/tidb/pull/10976) - - 修复使用悲观锁查询时由于没有使用 `SELECT … FOR UPDATE` 的 TSO 导致查询结果不正确的问题 [#11015](https://github.com/pingcap/tidb/pull/11015) - - 修改乐观锁与悲观锁同时使用时，乐观事务遇到悲观锁冲突时，检测行为由立即检测冲突修改为等待，防止锁冲突进一步恶化 [#11051](https://github.com/pingcap/tidb/pull/11051) - -## TiKV - -- 统计信息中新增对 Blob 文件大小的统计 [#5060](https://github.com/tikv/tikv/pull/5060) -- 修复由于进程退出未正确清理内存资源导致进程在退出时 core dump 问题 [#5053](https://github.com/tikv/tikv/pull/5053) -- 新增与 Titan 引擎相关的所有监控指标 [#4772](https://github.com/tikv/tikv/pull/4772)，[#4836](https://github.com/tikv/tikv/pull/4836) -- 统计打开文件句柄数量时，新增 Titan 引擎打开文件句柄数量，防止因文件句柄数统计不准确导致系统无文件句柄可用的问题 [#5026](https://github.com/tikv/tikv/pull/5026) -- 通过设置 `blob_run_mode` 来决定是否在某个 CF 上启动 Titan 引擎 [#4991](https://github.com/tikv/tikv/pull/4991) -- 修复读操作读不到悲观事务 commit 信息的问题 [#5067](https://github.com/tikv/tikv/pull/5067) -- 新增 `blob-run-mode` 配置参数控制 Titan 引擎的运行模式，取值：normal、read-only、fallback [#4865](https://github.com/tikv/tikv/pull/4865) -- 提升死锁检测的性能 [#5089](https://github.com/tikv/tikv/pull/5089) - -## PD - -- 修复热点 Region 调度时，调度限制会自动调整为 0 的问题 [#1552](https://github.com/pingcap/pd/pull/1552) -- 新增 `enable-grpc-gateway` 的配置选项，用于开启 etcd 的 grpc gateway 功能 [#1596](https://github.com/pingcap/pd/pull/1596) -- 新增 `store-balance-rate`、`hot-region-schedule-limit` 等与调度器配置相关的统计信息 [#1601](https://github.com/pingcap/pd/pull/1601) -- 优化热点 Region 调度策略，调度时跳过缺失副本的 Region，防止多个副本调度到同一个机房 [#1609](https://github.com/pingcap/pd/pull/1609) -- 优化 Region Merge 处理逻辑，优先 Merge Region Size 较小的 Region，提升 Region Merge 的速度 [#1613](https://github.com/pingcap/pd/pull/1613) -- 优化单次调度热点 Region 的限制值为 64，防止调度任务过多占用系统资源，影响性能 [#1616](https://github.com/pingcap/pd/pull/1616) -- 优化 Region 调度策略，新增优先调度 Pending 状态的 Region 功能 [#1617](https://github.com/pingcap/pd/pull/1617) -- 修复无法添加 `random-merge` 和 `admin-merge-region` operator 的问题 [#1634](https://github.com/pingcap/pd/pull/1634) -- 调整日志中输出 Region 中 Key 的格式为 16 进制，方便用户查看 [#1639](https://github.com/pingcap/pd/pull/1639) - -## Tools - -TiDB Binlog - -- 优化 Pump GC 策略，删除保证未被消费的 Binlog 不被清理的限制，确保资源不会长期占用 [#646](https://github.com/pingcap/tidb-binlog/pull/646) - -TiDB Lightning - -- 修正 SQL dump 指明的列名不是小写时导入错误的问题 [#210](https://github.com/pingcap/tidb-lightning/pull/210) - -## TiDB Ansible - -- 新增 `ansible` 命令及其 `jmespath`、`Jinja2` 依赖包的预检查功能 [#803](https://github.com/pingcap/tidb-ansible/pull/803)，[#813](https://github.com/pingcap/tidb-ansible/pull/813) -- Pump 新增 `stop-write-at-available-space` 参数，控制当磁盘剩余空间小于该值（默认 10 GiB）时，Pump 停止写入 Binlog [#806](https://github.com/pingcap/tidb-ansible/pull/806) -- 更新 TiKV 监控中的 IO 监控项，兼容新版本监控组件 [#820](https://github.com/pingcap/tidb-ansible/pull/820) -- 更新 PD 监控信息，并修复 Disk Performance Dashboard 中 Disk Latency 显示为空的异常 [#817](https://github.com/pingcap/tidb-ansible/pull/817) -- TiKV Details Dashboard 新增 Titan 监控项 [#824](https://github.com/pingcap/tidb-ansible/pull/824) diff --git a/v2.1/releases/3.0beta.md b/v2.1/releases/3.0beta.md deleted file mode 100644 index b538dc6d68bf..000000000000 --- a/v2.1/releases/3.0beta.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: TiDB 3.0 Beta Release Notes -category: Releases ---- - -# TiDB 3.0 Beta Release Notes - -2019 年 1 月 19 日，TiDB 发布 3.0 Beta 版，TiDB Ansible 相应发布 3.0 Beta 版本。相比 2.1 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 新特性 - - 支持 View - - 支持窗口函数 - - 支持 Range 分区 - - 支持 Hash 分区 -+ SQL 优化器 - - 重新支持聚合消除的优化规则 [#7676](https://github.com/pingcap/tidb/pull/7676) - - 优化 `NOT EXISTS` 子查询，将其转化为 Anti Semi Join [#7842](https://github.com/pingcap/tidb/pull/7842) - - 添加 `tidb_enable_cascades_planner` 变量以支持新的 Cascades 优化器。目前 Cascades 优化器尚未实现完全，默认关闭 [#7879](https://github.com/pingcap/tidb/pull/7879) - - 支持在事务中使用 Index Join [#7877](https://github.com/pingcap/tidb/pull/7877) - - 优化 Outer Join 上的常量传播，使得对 Join 结果里和 Outer 表相关的过滤条件能够下推过 Outer Join 到 Outer 表上，减少 Outer Join 的无用计算量，提升执行性能 [#7794](https://github.com/pingcap/tidb/pull/7794) - - 调整投影消除的优化规则到聚合消除之后，消除掉冗余的 `Project` 算子 [#7909](https://github.com/pingcap/tidb/pull/7909) - - 优化 `IFNULL` 函数，当输入参数具有非 NULL 的属性的时候，消除该函数 [#7924](https://github.com/pingcap/tidb/pull/7924) - - 支持对 `_tidb_rowid` 构造查询的 Range，避免全表扫，减轻集群压力 [#8047](https://github.com/pingcap/tidb/pull/8047) - - 优化 `IN` 子查询为先聚合后做 Inner Join 并，添加变量 `tidb_opt_insubq_to_join_and_agg` 以控制是否开启该优化规则并默认打开 [#7531](https://github.com/pingcap/tidb/pull/7531) - - 支持在 `DO` 语句中使用子查询 [#8343](https://github.com/pingcap/tidb/pull/8343) - - 添加 Outer Join 消除的优化规则，减少不必要的扫表和 Join 操作，提升执行性能 [#8021](https://github.com/pingcap/tidb/pull/8021) - - 修改 `TIDB_INLJ` 优化器 Hint 的行为，优化器将使用 Hint 中指定的表当做 Index Join 的 Inner 表 [#8243](https://github.com/pingcap/tidb/pull/8243) - - 更大范围的启用 `PointGet`，使得当 Prepare 语句的执行计划缓存生效时也能利用上它 [#8108](https://github.com/pingcap/tidb/pull/8108) - - 引入贪心的 Join Reorder 算法，优化多表 Join 时 Join 顺序选择的问题 [#8394](https://github.com/pingcap/tidb/pull/8394) - - 支持 View [#8757](https://github.com/pingcap/tidb/pull/8757) - - 支持 Window Function [#8630](https://github.com/pingcap/tidb/pull/8630) - - 当 `TIDB_INLJ` 未生效时，返回 warning 给客户端，增强易用性 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 支持根据过滤条件和表的统计信息推导过滤后数据的统计信息的功能 [#7921](https://github.com/pingcap/tidb/pull/7921) - - 增强 Range Partition 的 Partition Pruning 优化规则 [#8885](https://github.com/pingcap/tidb/pull/8885) -+ SQL 执行引擎 - - 优化 Merge Join 算子，使其支持空的 `ON` 条件 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 优化日志，打印执行 `EXECUTE` 语句时使用的用户变量 [#7684](https://github.com/pingcap/tidb/pull/7684) - - 优化日志，为 `COMMIT` 语句打印慢查询信息 [#7951](https://github.com/pingcap/tidb/pull/7951) - - 支持 `EXPLAIN ANALYZE` 功能，使得 SQL 调优过程更加简单 [#7827](https://github.com/pingcap/tidb/pull/7827) - - 优化列很多的宽表的写入性能 [#7935](https://github.com/pingcap/tidb/pull/7935) - - 支持 `admin show next_row_id` [#8242](https://github.com/pingcap/tidb/pull/8242) - - 添加变量 `tidb_init_chunk_size` 以控制执行引擎使用的初始 Chunk 大小 [#8480](https://github.com/pingcap/tidb/pull/8480) - - 完善 `shard_row_id_bits`，对自增 ID 做越界检查 [#8936](https://github.com/pingcap/tidb/pull/8936) -+ `Prepare` 语句 - - 对包含子查询的 `Prepare` 语句，禁止其添加到 `Prepare` 语句的执行计划缓存中，确保输入不同的用户变量时执行计划的正确性 [#8064](https://github.com/pingcap/tidb/pull/8064) - - 优化 `Prepare` 语句的执行计划缓存，使得当语句中包含非确定性函数的时候，该语句的执行计划也能被缓存 [#8105](https://github.com/pingcap/tidb/pull/8105) - - 优化 `Prepare` 语句的执行计划缓存，使得 `DELETE`/`UPDATE`/`INSERT` 的执行计划也能被缓存 [#8107](https://github.com/pingcap/tidb/pull/8107) - - 优化 `Prepare` 语句的执行计划缓存，当执行 `DEALLOCATE` 语句时从缓存中剔除对应的执行计划 [#8332](https://github.com/pingcap/tidb/pull/8332) - - 优化 `Prepare` 语句的执行计划缓存，通过控制其内存使用以避免缓存过多执行计划导致 TiDB OOM 的问题 [#8339](https://github.com/pingcap/tidb/pull/8339) - - 优化 `Prepare` 语句，使得 `ORDER BY`/`GROUP BY`/`LIMIT` 子句中可以使用 “?” 占位符 [#8206](https://github.com/pingcap/tidb/pull/8206) -+ 权限管理 - - 增加对 `ANALYZE` 语句的权限检查 [#8486](https://github.com/pingcap/tidb/pull/8486) - - 增加对 `USE` 语句的权限检查 [#8414](https://github.com/pingcap/tidb/pull/8418) - - 增加对 `SET GLOBAL` 语句的权限检查 [#8837](https://github.com/pingcap/tidb/pull/8837) - - 增加对 `SHOW PROCESSLIST` 语句的权限检查 [#7858](https://github.com/pingcap/tidb/pull/7858) -+ Server - - 支持了对 SQL 语句的 `Trace` 功能 [#9029](https://github.com/pingcap/tidb/pull/9029) - - 支持了插件框架 [#8788](https://github.com/pingcap/tidb/pull/8788) - - 支持同时使用 `unix_socket` 和 TCP 两种方式连接数据库 [#8836](https://github.com/pingcap/tidb/pull/8836) - - 支持了系统变量 `interactive_timeout` [#8573](https://github.com/pingcap/tidb/pull/8573) - - 支持了系统变量 `wait_timeout` [#8346](https://github.com/pingcap/tidb/pull/8346) - - 提供了变量 `tidb_batch_commit`，可以按语句数将事务分解为多个事务 [#8293](https://github.com/pingcap/tidb/pull/8293) - - 支持 `ADMIN SHOW SLOW` 语句，方便查看慢日志 [#7785](https://github.com/pingcap/tidb/pull/7785) -+ 兼容性 - - 支持了 `ALLOW_INVALID_DATES` 这种 SQL mode [#9027](https://github.com/pingcap/tidb/pull/9027) - - 提升了 load data 对 CSV 文件的容错能力 [#9005](https://github.com/pingcap/tidb/pull/9005) - - 支持了 MySQL 320 握手协议 [#8812](https://github.com/pingcap/tidb/pull/8812) - - 支持将 unsigned bigint 列声明为自增列 [#8181](https://github.com/pingcap/tidb/pull/8181) - - 支持 `SHOW CREATE DATABASE IF NOT EXISTS` 语法 [#8926](https://github.com/pingcap/tidb/pull/8926) - - 当过滤条件中包含用户变量时不对其进行谓词下推的操作，更加兼容 MySQL 中使用用户变量模拟 Window Function 的行为 [#8412](https://github.com/pingcap/tidb/pull/8412) -+ DDL - - 支持快速恢复误删除的表 [#7937](https://github.com/pingcap/tidb/pull/7937) - - 支持动态调整 ADD INDEX 的并发数 [#8295](https://github.com/pingcap/tidb/pull/8295) - - 支持更改表或者列的字符集到 utf8/utf8mb4 [#8037](https://github.com/pingcap/tidb/pull/8037) - - 默认字符集从 `utf8` 变为 `utf8mb4` [#7965](https://github.com/pingcap/tidb/pull/7965) - - 支持 RANGE PARTITION [#8011](https://github.com/pingcap/tidb/pull/8011) - -## Tools - -+ TiDB Lightning - - 大幅优化 SQL 转 KV 的处理速度 [#110](https://github.com/pingcap/tidb-lightning/pull/110) - - 对单表支持 batch 导入，提高导入性能和稳定性 [#113](https://github.com/pingcap/tidb-lightning/pull/113) - -## PD - -- 增加 `RegionStorage` 单独存储 Region 元信息 [#1237](https://github.com/pingcap/pd/pull/1237) -- 增加 shuffle hot region 调度 [#1361](https://github.com/pingcap/pd/pull/1361) -- 增加调度参数相关 Metrics [#1406](https://github.com/pingcap/pd/pull/1406) -- 增加集群 Label 信息相关 Metrics [#1402](https://github.com/pingcap/pd/pull/1402) -- 增加导入数据场景模拟 [#1263](https://github.com/pingcap/pd/pull/1263) -- 修复 Leader 选举相关的 Watch 问题 [#1396](https://github.com/pingcap/pd/pull/1396) - -## TiKV - -- 支持了分布式 GC [#3179](https://github.com/tikv/tikv/pull/3179) -- 在 Apply snapshot 之前检查 RocksDB level 0 文件，避免产生 Write stall [#3606](https://github.com/tikv/tikv/pull/3606) -- 支持了逆向 `raw_scan` 和 `raw_batch_scan` [#3742](https://github.com/tikv/tikv/pull/3724) -- 更好的夏令时支持 [#3786](https://github.com/tikv/tikv/pull/3786) -- 支持了使用 HTTP 方式获取监控信息 [#3855](https://github.com/tikv/tikv/pull/3855) -- 支持批量方式接收和发送 Raft 消息 [#3931](https://github.com/tikv/tikv/pull/3913) -- 引入了新的存储引擎 Titan [#3985](https://github.com/tikv/tikv/pull/3985) -- 升级 gRPC 到 v1.17.2 [#4023](https://github.com/tikv/tikv/pull/4023) -- 支持批量方式接收客户端请求和发送回复 [#4043](https://github.com/tikv/tikv/pull/4043) -- 多线程 Apply [#4044](https://github.com/tikv/tikv/pull/4044) -- 多线程 Raftstore [#4066](https://github.com/tikv/tikv/pull/4066) diff --git a/v2.1/releases/ga.md b/v2.1/releases/ga.md deleted file mode 100644 index 65743083591f..000000000000 --- a/v2.1/releases/ga.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: TiDB 1.0 release notes -category: Releases ---- - -# TiDB 1.0 Release Notes - -2017 年 10 月 16 日，TiDB 发布 GA 版（TiDB 1.0）。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -+ SQL 查询优化器 - - 调整代价模型 - - Analyze 下推 - - 函数签名下推 - -+ 优化内部数据格式，减小中间结果大小 -+ 提升 MySQL 兼容性 -+ 支持 `NO_SQL_CACHE` 语法，控制存储引擎对缓存的使用 -+ 重构 Hash Aggregator 算子，降低内存使用 -+ 支持 Stream Aggragator 算子 - -## PD - -+ 支持基于读流量的热点调度 -+ 支持设置 Store 权重，以及基于权重的调度 - -## TiKV - -+ Coprocessor 支持更多下推函数 -+ 支持取样操作下推 -+ 支持手动触发数据 Compact，用于快速回收空间 -+ 提升性能和稳定性 -+ 增加 Debug API，方便调试 - -## TiSpark Beta Release - -+ 支持可配置框架 -+ 支持 ThriftSever/JDBC 和 Spark SQL 脚本入口 - -## 源码地址 - -[源码地址](https://github.com/pingcap/tidb) - -## 鸣谢 - -### 特别感谢参与项目的企业和团队 - -- Archon -- Mobike -- SpeedyCloud -- UCloud -- 腾讯云 -- 韩国三星研究院 - -### 感谢以下组织/个人提供出色的开源软件/服务 - -- Asta Xie -- CNCF -- CoreOS -- Databricks -- Docker -- Github -- Grafana -- gRPC -- Jepsen -- Kubernetes -- Namazu -- Prometheus -- RedHat -- RocksDB Team -- Rust Team - -### 感谢社区个人贡献者 TiDB Contributor - -- 8cbx -- Akihiro Suda -- aliyx -- alston111111 -- andelf -- Andy Librian -- Arthur Yang -- astaxie -- Bai, Yang -- bailaohe -- Bin Liu -- Blame cosmos -- Breezewish -- Carlos Ferreira -- Ce Gao -- Changjian Zhang -- Cheng Lian -- Cholerae Hu -- Chu Chao -- coldwater -- Cole R Lawrence -- cuiqiu -- cuiyuan -- Cwen -- Dagang -- David Chen -- David Ding -- dawxy -- dcadevil -- Deshi Xiao -- Di Tang -- disksing -- dongxu -- dreamquster -- Drogon -- Du Chuan -- Dylan Wen -- eBoyy -- Eric Romano -- Ewan Chou -- Fiisio -- follitude -- Fred Wang -- follitude -- fud -- fudali -- gaoyangxiaozhu -- Gogs -- goroutine -- Gregory Ian -- Guanqun Lu -- Guilherme Hübner Franco -- Haibin Xie -- Han Fei -- Hiroaki Nakamura -- hiwjd -- Hongyuan Wang -- Hu Ming -- Hu Ziming -- Huachao Huang -- HuaiyuXu -- Huxley Hu -- iamxy -- Ian -- insion -- iroi44 -- Ivan.Yang -- Jack Yu -- jacky liu -- Jan Mercl -- Jason W -- Jay -- Jay Lee -- Jianfei Wang -- Jiaxing Liang -- Jie Zhou -- jinhelin -- Jonathan Boulle -- Karl Ostendorf -- knarfeh -- Kuiba -- leixuechun -- li -- Li Shihai -- Liao Qiang -- Light -- lijian -- Lilian Lee -- Liqueur Librazy -- Liu Cong -- Liu Shaohui -- liubo0127 -- liyanan -- lkk2003rty -- Louis -- louishust -- luckcolors -- Lynn -- Mae Huang -- maiyang -- maxwell -- mengshangqi -- Michael Belenchenko -- mo2zie -- morefreeze -- MQ -- mxlxm -- Neil Shen -- netroby -- ngaut -- Nicole Nie -- nolouch -- onlymellb -- overvenus -- PaladinTyrion -- paulg -- Priya Seth -- qgxiaozhan -- qhsong -- Qiannan -- qiuyesuifeng -- queenypingcap -- qupeng -- Rain Li -- ranxiaolong -- Ray -- Rick Yu -- shady -- ShawnLi -- Shen Li -- Sheng Tang -- Shirly -- Shuai Li -- ShuNing -- ShuYu Wang -- siddontang -- silenceper -- Simon J Mudd -- Simon Xia -- skimmilk6877 -- sllt -- soup -- Sphinx -- Steffen -- sumBug -- sunhao2017 -- Tao Meng -- Tao Zhou -- tennix -- tiancaiamao -- TianGuangyu -- Tristan Su -- ueizhou -- UncP -- Unknwon -- v01dstar -- Van -- WangXiangUSTC -- wangyisong1996 -- weekface -- wegel -- Wei Fu -- Wenbin Xiao -- Wenting Li -- Wenxuan Shi -- winkyao -- woodpenker -- wuxuelian -- Xiang Li -- xiaojian cai -- Xuanjia Yang -- Xuanwo -- XuHuaiyu -- Yang Zhexuan -- Yann Autissier -- Yanzhe Chen -- Yiding Cui -- Yim -- youyouhu -- Yu Jun -- Yuwen Shen -- Zejun Li -- Zhang Yuning -- zhangjinpeng1987 -- ZHAO Yijun -- ZhengQian -- ZhengQianFang -- zhengwanbo -- Zhe-xuan Yang -- ZhiFeng Hu -- Zhiyuan Zheng -- Zhou Tao -- Zhoubirdblue -- zhouningnan -- Ziyi Yan -- zs634134578 -- zyguan -- zz-jason -- qiukeren -- hawkingrei -- wangyanjun -- zxylvlp diff --git a/v2.1/releases/prega.md b/v2.1/releases/prega.md deleted file mode 100644 index 75d0d1fcfa44..000000000000 --- a/v2.1/releases/prega.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB Pre-GA Release Notes -category: Releases ---- - -# TiDB Pre-GA Release Notes - -2017 年 8 月 30 日，TiDB 发布 Pre-GA 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -+ SQL 查询优化器 - - 调整代价模型 - - 优化索引选择，支持不同类型字段比较的索引选择 - - 支持基于贪心算法的 Join Reorder -+ 大量 MySQL 兼容性相关功能 -+ 支持 Natural Join -+ 完成 JSON 类型支持 (Experimental)，包括对 JSON 中的字段查询、更新、建索引 -+ 裁剪无用数据，减小执行器内存消耗 -+ 支持在 SQL 语句中设置优先级，并根据查询类型自动设置部分语句的优先级 -+ 完成表达式重构，执行速度提升 30% 左右 - -## PD - -+ 支持手动切换 PD 集群 Leader - -## TiKV - -+ Raft Log 使用独立的 RocksDB 实例 -+ 使用 DeleteRange 加快删除副本速度 -+ Coprocessor 支持更多运算符下推 -+ 提升性能，提升稳定性 - -## TiSpark Beta Release - -+ 支持谓词下推 -+ 支持聚合下推 -+ 支持范围裁剪 -+ 通过 TPC-H 测试 (除去一个需要 View 的 Query) diff --git a/v2.1/releases/rc1.md b/v2.1/releases/rc1.md deleted file mode 100644 index cf7f40d3fdc4..000000000000 --- a/v2.1/releases/rc1.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB RC1 Release Notes -category: Releases ---- - -# TiDB RC1 Release Notes - -2016 年 12 月 23 日，分布式关系型数据库 TiDB 正式发布 RC1。 - -## TiKV - -+ 提升写入速度 -+ 降低磁盘空间占用 -+ 支持百 TB 级别数据 -+ 提升稳定性，集群规模支持 200 个节点 -+ 提供 Raw KV API，以及 Golang client - -## PD - -+ PD 调度策略框架优化，策略更加灵活合理 -+ 添加 label 支持，支持跨 DC 调度 -+ 提供 PD Controler，方便操作 PD 集群 - -## TiDB - -+ SQL 查询优化器 - - 支持 eager aggregate - - 更详细的 explain 信息 - - union 算子并行化 - - 子查询性能优化 - - 条件下推优化 - - 优化 CBO 框架 -+ 重构 time 相关类型的实现，提升和 MySQL 的兼容性 -+ 支持更多的 MySQL 内建函数 -+ Add Index 语句提速 -+ 支持用 change column 语句修改列名；支持使用 Alter table 的 modify column 和 change column 完成部分列类型转换 - -## 工具 - -+ Loader：兼容 Percona 的 Mydumper 数据格式，提供多线程导入、出错重试、断点续传等功能，并且针对 TiDB 有优化 -+ 开发完成一键部署工具 diff --git a/v2.1/releases/rc2.md b/v2.1/releases/rc2.md deleted file mode 100644 index ff0f2cf18865..000000000000 --- a/v2.1/releases/rc2.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB RC2 Release Notes -category: Releases ---- - -# TiDB RC2 Release Notes - -2017 年 3 月 1 日，TiDB 正式发布 RC2 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。对于 OLTP 场景，读取性能提升 60%，写入性能提升 30%。另外提供了权限管理功能，用户可以按照 MySQL 的权限管理方式控制数据访问权限。 - -## TiDB - -+ SQL 查询优化器 - - 统计信息收集和使用 - - 关联子查询优化 - - 优化 CBO 框架 - - 通过 Unique Key 信息消除聚合 - - 重构 Expression - - Distinct 转换为 GroupBy - - 支持 topn 操作下推 -+ 支持基本权限管理 -+ 新增大量 MySQL 内建函数 -+ 完善 Alter Table 语句，支持修改表名、默认值、注释 -+ 支持 Create Table Like 语句 -+ 支持 Show Warnings 语句 -+ 支持 Rename Table 语句 -+ 限制单个事务大小，避免大事务阻塞整个集群 -+ Load Data 过程中对数据进行自动拆分 -+ 优化 AddIndex、Delete 语句性能 -+ 支持 "ANSI_QUOTES" sql_mode -+ 完善监控 -+ 修复 Bug -+ 修复内存泄漏问题 - -## PD - -+ 支持 Label 对副本进行 Location 调度 -+ 基于 region 数量的快速调度 -+ pd-ctl 支持更多功能 - - 添加、删除 PD - - 通过 Key 获取 Region 信息 - - 添加、删除 scheduler 和 operator - - 获取集群 label 信息 - -## TiKV - -+ 支持 Async Apply 提升整体写入性能 -+ 使用 prefix seek 提升 Write CF 的读取性能 -+ 使用 memory hint prefix 提升 Raft CF 插入性能 -+ 优化单行读事务性能 -+ 支持更多下推功能 -+ 加入更多统计 -+ 修复 Bug diff --git a/v2.1/releases/rc3.md b/v2.1/releases/rc3.md deleted file mode 100644 index 8c2705dd5e2d..000000000000 --- a/v2.1/releases/rc3.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: TiDB RC3 Release Notes -category: Releases ---- - -# TiDB RC3 Release Notes - -2017 年 6 月 16 日，TiDB 正式发布 RC3 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。性能方面重点优化了负载均衡调度策略和流程。功能方面进一步完善权限管理功能，用户可以按照 MySQL 的权限管理方式控制数据访问权限。另外 DDL 的速度也得到显著的提升。 -同时为了简化运维工作，开源了 TiDB Ansible 项目，可以一键部署/升级/启停 TiDB 集群。 - -## TiDB - -+ SQL 查询优化器 - - 统计信息收集和使用 - - 关联子查询优化 - - 优化 CBO 框架 - - 通过 Unique Key 信息消除聚合 - - 重构 Expression - - Distinct 转换为 GroupBy - - 支持 topn 操作下推 -+ 支持基本权限管理 -+ 新增大量 MySQL 内建函数 -+ 完善 Alter Table 语句，支持修改表名、默认值、注释 -+ 支持 Create Table Like 语句 -+ 支持 Show Warnings 语句 -+ 支持 Rename Table 语句 -+ 限制单个事务大小，避免大事务阻塞整个集群 -+ Load Data 过程中对数据进行自动拆分 -+ 优化 AddIndex、Delete 语句性能 -+ 支持 "ANSI_QUOTES" sql_mode -+ 完善监控 -+ 修复 Bug -+ 修复内存泄漏问题 - -## PD - -+ 支持 Label 对副本进行 Location 调度 -+ 基于 region 数量的快速调度 -+ pd-ctl 支持更多功能 - - 添加、删除 PD - - 通过 Key 获取 Region 信息 - - 添加、删除 scheduler 和 operator - - 获取集群 label 信息 - -## TiKV - -+ 支持 Async Apply 提升整体写入性能 -+ 使用 prefix seek 提升 Write CF 的读取性能 -+ 使用 memory hint prefix 提升 Raft CF 插入性能 -+ 优化单行读事务性能 -+ 支持更多下推功能 -+ 加入更多统计 -+ 修复 Bug diff --git a/v2.1/releases/rc4.md b/v2.1/releases/rc4.md deleted file mode 100644 index 49aad74892c0..000000000000 --- a/v2.1/releases/rc4.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: TiDB RC4 Release Notes -category: Releases ---- - -# TiDB RC4 Release Notes - -2017 年 8 月 4 日，TiDB 正式发布 RC4 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。性能方面重点优化了写入速度，计算任务调度支持优先级，避免分析型大事务影响在线事务。SQL 优化器全新改版，查询代价估算更加准确，且能够自动选择 Join 物理算子。功能方面进一步 MySQL 兼容性。 -同时为了更好的支持 OLAP 业务，开源了 TiSpark 项目，可以通过 Spark 读取和分析 TiKV 中的数据。 - -## TiDB - -+ SQL 查询优化器重构 - - 更好的支持 TopN 查询 - - 支持 Join 算子根据代价自动选择 - - 更完善的 Projection Elimination -+ Schema 版本检查区分 Table，避免 DDL 干扰其他正在执行的事务 -+ 支持 BatchIndexJoin -+ 完善 Explain 语句 -+ 提升 Index Scan 性能 -+ 大量 MySQL 兼容性相关功能 -+ 支持 Json 类型及其操作 -+ 支持查询优先级、隔离级别的设置 - -## PD - -+ 支持通过 PD 设置 TiKV location labels -+ 调度优化 - - 支持 PD 主动向 TiKV 下发调度命令 - - 加快 region heartbeat 响应速度 - - 优化 balance 算法 -+ 优化数据加载，加快 failover 速度 - -## TiKV - -+ 支持查询优先级设置 -+ 支持 RC 隔离级别 -+ 完善 Jepsen，提升稳定性 -+ 支持 Document Store -+ Coprocessor 支持更多下推函数 -+ 提升性能，提升稳定性 - -## TiSpark Beta Release - -+ 支持谓词下推 -+ 支持聚合下推 -+ 支持范围裁剪 -+ 通过 TPC-H 测试（除去一个需要 View 的 Query） diff --git a/v2.1/releases/rn.md b/v2.1/releases/rn.md deleted file mode 100644 index b534b7aa66d2..000000000000 --- a/v2.1/releases/rn.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: TiDB 版本发布历史 -category: release ---- - -# TiDB 版本发布历史 - -TiDB 历史版本发布声明如下： - -## 3.0 - -- [3.0.1](/v2.1/releases/3.0.1.md) -- [3.0 GA](/v2.1/releases/3.0-ga.md) -- [3.0.0-rc.3](/v2.1/releases/3.0.0-rc.3.md) -- [3.0.0-rc.2](/v2.1/releases/3.0.0-rc.2.md) -- [3.0.0-rc.1](/v2.1/releases/3.0.0-rc.1.md) -- [3.0.0-beta.1](/v2.1/releases/3.0.0-beta.1.md) -- [3.0.0-beta](/v2.1/releases/3.0beta.md) - -## 2.1 - -- [2.1.19](/v2.1/releases/2.1.19.md) -- [2.1.18](/v2.1/releases/2.1.18.md) -- [2.1.17](/v2.1/releases/2.1.17.md) -- [2.1.16](/v2.1/releases/2.1.16.md) -- [2.1.15](/v2.1/releases/2.1.15.md) -- [2.1.14](/v2.1/releases/2.1.14.md) -- [2.1.13](/v2.1/releases/2.1.13.md) -- [2.1.12](/v2.1/releases/2.1.12.md) -- [2.1.11](/v2.1/releases/2.1.11.md) -- [2.1.10](/v2.1/releases/2.1.10.md) -- [2.1.9](/v2.1/releases/2.1.9.md) -- [2.1.8](/v2.1/releases/2.1.8.md) -- [2.1.7](/v2.1/releases/2.1.7.md) -- [2.1.6](/v2.1/releases/2.1.6.md) -- [2.1.5](/v2.1/releases/2.1.5.md) -- [2.1.4](/v2.1/releases/2.1.4.md) -- [2.1.3](/v2.1/releases/2.1.3.md) -- [2.1.2](/v2.1/releases/2.1.2.md) -- [2.1.1](/v2.1/releases/2.1.1.md) -- [2.1 GA](/v2.1/releases/2.1ga.md) -- [2.1 RC5](/v2.1/releases/21rc5.md) -- [2.1 RC4](/v2.1/releases/21rc4.md) -- [2.1 RC3](/v2.1/releases/21rc3.md) -- [2.1 RC2](/v2.1/releases/21rc2.md) -- [2.1 RC1](/v2.1/releases/21rc1.md) -- [2.1 Beta](/v2.1/releases/21beta.md) - -## 2.0 - -- [2.0.11](/v2.1/releases/2.0.11.md) -- [2.0.10](/v2.1/releases/2.0.10.md) -- [2.0.9](/v2.1/releases/209.md) -- [2.0.8](/v2.1/releases/208.md) -- [2.0.7](/v2.1/releases/207.md) -- [2.0.6](/v2.1/releases/206.md) -- [2.0.5](/v2.1/releases/205.md) -- [2.0.4](/v2.1/releases/204.md) -- [2.0.3](/v2.1/releases/203.md) -- [2.0.2](/v2.1/releases/202.md) -- [2.0.1](/v2.1/releases/201.md) -- [2.0](/v2.1/releases/2.0ga.md) -- [2.0 RC5](/v2.1/releases/2rc5.md) -- [2.0 RC4](/v2.1/releases/2rc4.md) -- [2.0 RC3](/v2.1/releases/2rc3.md) -- [2.0 RC1](/v2.1/releases/2rc1.md) -- [1.1 Beta](/v2.1/releases/11beta.md) -- [1.1 Alpha](/v2.1/releases/11alpha.md) - -## 1.0 - -- [1.0](/v2.1/releases/ga.md) -- [Pre-GA](/v2.1/releases/prega.md) -- [RC4](/v2.1/releases/rc4.md) -- [RC3](/v2.1/releases/rc3.md) -- [RC2](/v2.1/releases/rc2.md) -- [RC1](/v2.1/releases/rc1.md) diff --git a/v2.1/report-issue.md b/v2.1/report-issue.md deleted file mode 100644 index 070d8e04416a..000000000000 --- a/v2.1/report-issue.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 提交 Issue -category: report issue ---- - -# 提交 Issue - -我们正在努力使 TiDB 与 MySQL 5.7 兼容。如果您发现了任何未记录在文档中的表现差异、bug 或奇怪的性能特征，请[在 GitHub 中提交新的 Issue](https://github.com/pingcap/tidb/issues)。 - -在 GitHub 上提交的新 Issue 分为以下几种： - -- 错误报告 (Bug Reports) -- 功能请求 (Feature Requests) -- 常规问题 (General Questions) -- 性能问题 (Performance Questions) - -请确保您完全按照 Issue 模板进行填写，以便我们迅速定位问题并作出回应。 diff --git a/v2.1/roadmap.md b/v2.1/roadmap.md deleted file mode 100644 index 095c7f81d8b9..000000000000 --- a/v2.1/roadmap.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: TiDB 路线图 -category: Roadmap ---- - -# TiDB 路线图 - -## TiDB - -- [ ] 优化器 - - [ ] 统计信息优化 - - [ ] Multi-Column Statistics - - [ ] Cascades Planner - - [ ] Plan Management - - [ ] SQL Tuning Advisor - - [ ] Robust Access Path Selection：增加启发式规则，提升 OLTP 场景中索引选择正确率 - - [ ] Adaptive Query Optimization -- [ ] 执行引擎 - - [ ] 算子并行化 - - [ ] 内存控制 - - [ ] 并发控制 - - [ ] Shuffle 算子 - - [ ] Vectorized 表达式计算 - - [ ] UDF -- [ ] SQL 功能 - - [ ] 支持 View - - [ ] 支持窗口函数 - - [ ] 支持 Common Table Expression - - [ ] 支持 Hash 分区表 - - [ ] 支持 utf8_general_ci collation -- [ ] DDL 改进 - - [ ] 支持 Table Lock - - [ ] 支持 Change column type - - [ ] 支持单条语句中多个 DDL 操作 - - [ ] 支持不可见索引（invisible index） -- [ ] 支持插件系统 - - [ ] 支持白名单插件 - - [ ] 支持审计日志插件 - - [ ] 支持 RBAC 插件 - - [ ] 支持诊断插件 -- [ ] 支持 Query Tracing -- [ ] 支持行列混合存储引擎 -- [ ] 支持 New Storage Row Format，提升性能并减小内存占用 -- [ ] RowID 实现非整数类型 -- [ ] 事务 - - [ ] 减少读写冲突 - - [ ] 优化事务调度机制 - - [ ] 改善模型，降低延迟 - - [ ] 支持最小事务 (like the mini-transaction of InnoDB) - -## TiKV - -+ Raft - - [x] Region Merge - 合并小的 Region 以减少开销 - - [x] Local Read Thread - 把读请求放在一个单独的线程处理 - - [x] 批量 Region Split - 加速大的 Region 的分裂 - - [x] Raft Learner - 支持 Raft learner 使得成员变更过程更加平滑 - - [x] Raft Pre-voter - 支持 Raft Pre-vote 避免网络隔离带来不必要的选举 - - [ ] Joint Consensus - 安全地进行多个成员变更 - - [ ] 多线程 Raftstore - 在多个线程处理不同 Region 的 Raft 逻辑 - - [ ] 多线程 Apply Pool - 在多个线程执行不同 Region 已经提交了的命令 -+ Engine - - [ ] Titan - 把大的 key-values 从 LSM-Tree 中分离出来 - - [ ] 可拔插的 Engine 接口 - 简化接口逻辑并且提供可扩展性 -+ Storage - - [ ] 在 scheduler 里做流控提前避免 write stall -+ Transaction - - [x] 优化事务冲突 - - [ ] 分布式 GC - 把 MVCC 垃圾回收的逻辑分布到 TiKV 控制 -+ Coprocessor - - [x] Streaming - 把大的数据集切成小块返回以减少内存消耗 - - [ ] Chunk Execution - 按 chunk 的方式来处理数据以提高性能 - - [ ] 请求跟踪 - 提供单个请求执行的详细信息 -+ Tools - - [x] TiKV Importer - 通过直接导入 SST 文件的方式加速数据导入 -+ Client - - [ ] 提供 Rust 版本的 TiKV client - - [ ] gRPC 消息批量化 - 减少消息交互的开销 - -## PD - -- [x] Namespace 完善 - - [x] 不同 Namespace 或者 Table 配置不同的副本策略 -- [x] Table Region 分散调度 -- [x] 调度支持优先级，更加可控 -- [ ] 使用机器学习优化调度 -- [ ] 优化 Region 元信息存储 - 把元信息存储在一个独立的存储引擎里 - -## TiSpark - -- [ ] Limit/Order 下推 -- [x] DAG 接口接入（废除 Select 接口） -- [ ] Index Join 和并行 merge join -- [ ] Data Federation（桥接其他数据源，最好能和社区同步，这个接进来可以比较好扩展 Usecase，如果再做一个 InputFormat 适配就可以接 Hive 和 Presto 这些 Hadoop 上的数仓） - -## Tools - -- [x] 集群部署工具 -- [X] 高性能数据导入工具（lightning） -- [X] 集群备份和恢复工具（包括全量+增量备份，Mydumper + drainer/reparo） -- [X] 改进 TiDB Binlog 架构 -- [ ] 数据在线迁移工具（Syncer 升级版） -- [ ] 集群诊断和分析工具 diff --git a/v2.1/support-resources.md b/v2.1/support-resources.md deleted file mode 100644 index f705fb131484..000000000000 --- a/v2.1/support-resources.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 支持资源 -category: resources ---- - -# 支持资源 - -您可以通过以下任何一种方式找到我们的社区成员： - -+ Slack Channel: [https://pingcap.com/tidbslack](https://pingcap.com/tidbslack) -+ Stack Overflow: [https://stackoverflow.com/questions/tagged/tidb](https://stackoverflow.com/questions/tagged/tidb) -+ Reddit: [https://www.reddit.com/r/TiDB](https://www.reddit.com/r/TiDB) -+ GitHub: [https://github.com/pingcap/tidb/issues](https://github.com/pingcap/tidb/issues) - -有关企业支持合作的信息，请[联系我们](mailto:info@pingcap.com)。 diff --git a/v2.1/tispark/tispark-quick-start-guide_v1.x.md b/v2.1/tispark/tispark-quick-start-guide_v1.x.md deleted file mode 100644 index c0166c89bbdc..000000000000 --- a/v2.1/tispark/tispark-quick-start-guide_v1.x.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: TiSpark 快速入门指南 -category: tispark ---- - -# TiSpark 快速入门指南 - -为了让大家快速体验 [TiSpark](/v2.1/reference/tispark.md)，通过 TiDB Ansible 安装的 TiDB 集群中默认已集成 Spark、TiSpark jar 包及 TiSpark sample data。 - -## 部署信息 - -- Spark 默认部署在 TiDB 实例部署目录下 spark 目录中 -- TiSpark jar 包默认部署在 Spark 部署目录 jars 文件夹下： - - spark/jars/tispark-SNAPSHOT-jar-with-dependencies.jar - -- TiSpark sample data 及导入脚本默认部署在 TiDB Ansible 目录下： - - tidb-ansible/resources/bin/tispark-sample-data - -## 环境准备 - -### 在 TiDB 实例上安装 JDK - -在 [Oracle JDK 官方下载页面](http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html) 下载 JDK 1.8 当前最新版，本示例中下载的版本为 `jdk-8u141-linux-x64.tar.gz`。 - -解压并根据你的 JDK 部署目录设置环境变量， -编辑 `~/.bashrc` 文件，比如： - -```bashrc -export JAVA_HOME=/home/pingcap/jdk1.8.0_144 -export PATH=$JAVA_HOME/bin:$PATH -``` - -验证 JDK 有效性： - -``` -$ java -version -java version "1.8.0_144" -Java(TM) SE Runtime Environment (build 1.8.0_144-b01) -Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode) -``` - -### 导入样例数据 - -假设 TiDB 集群已启动，其中一台 TiDB 实例服务 IP 为 192.168.0.2，端口为 4000，用户名为 root，密码为空。 - -``` -cd tidb-ansible/resources/bin/tispark-sample-data -``` - -修改 `sample_data.sh` 中 TiDB 登录信息，比如： - -``` -mysql --local-infile=1 -h 192.168.0.2 -P 4000 -u root < dss.ddl -``` - -执行以下脚本： - -``` -./sample_data.sh -``` - -> **注意：** -> -> 执行脚本的机器上需要安装 MySQL client，CentOS 用户可通过 `yum -y install mysql` 来安装。 - -登录 TiDB 并验证数据包含 `TPCH_001` 库及以下表： - -``` -$ mysql -uroot -P4000 -h192.168.0.2 -MySQL [(none)]> show databases; -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| TPCH_001 | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) - -MySQL [(none)]> use TPCH_001 -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -MySQL [TPCH_001]> show tables; -+--------------------+ -| Tables_in_TPCH_001 | -+--------------------+ -| CUSTOMER | -| LINEITEM | -| NATION | -| ORDERS | -| PART | -| PARTSUPP | -| REGION | -| SUPPLIER | -+--------------------+ -8 rows in set (0.00 sec) -``` - -## 使用范例 - -进入 spark 部署目录启动 spark-shell ： - -``` -$ cd spark -$ bin/spark-shell -``` - -```scala -scala> import org.apache.spark.sql.TiContext -scala> val ti = new TiContext(spark) - -// Mapping all TiDB tables from `TPCH_001` database as Spark SQL tables -scala> ti.tidbMapDatabase("TPCH_001") -``` - -之后可以直接调用 Spark SQL ： - -```scala -scala> spark.sql("select count(*) from lineitem").show -``` - -结果为： - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -下面执行另一个复杂一点的 Spark SQL ： - -```scala -scala> spark.sql( - """select - | l_returnflag, - | l_linestatus, - | sum(l_quantity) as sum_qty, - | sum(l_extendedprice) as sum_base_price, - | sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, - | sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, - | avg(l_quantity) as avg_qty, - | avg(l_extendedprice) as avg_price, - | avg(l_discount) as avg_disc, - | count(*) as count_order - |from - | lineitem - |where - | l_shipdate <= date '1998-12-01' - interval '90' day - |group by - | l_returnflag, - | l_linestatus - |order by - | l_returnflag, - | l_linestatus - """.stripMargin).show -``` - -结果为： - -``` -+------------+------------+---------+--------------+--------------+ -|l_returnflag|l_linestatus| sum_qty|sum_base_price|sum_disc_price| -+------------+------------+---------+--------------+--------------+ -| A| F|380456.00| 532348211.65|505822441.4861| -| N| F| 8971.00| 12384801.37| 11798257.2080| -| N| O|742802.00| 1041502841.45|989737518.6346| -| R| F|381449.00| 534594445.35|507996454.4067| -+------------+------------+---------+--------------+--------------+ -(续) ------------------+---------+------------+--------+-----------+ - sum_charge| avg_qty| avg_price|avg_disc|count_order| ------------------+---------+------------+--------+-----------+ - 526165934.000839|25.575155|35785.709307|0.050081| 14876| - 12282485.056933|25.778736|35588.509684|0.047759| 348| -1029418531.523350|25.454988|35691.129209|0.049931| 29181| - 528524219.358903|25.597168|35874.006533|0.049828| 14902| ------------------+---------+------------+--------+-----------+ -``` - -更多样例请参考 。 diff --git a/v2.1/tispark/tispark-user-guide_v1.x.md b/v2.1/tispark/tispark-user-guide_v1.x.md deleted file mode 100644 index 1586ddaa9dce..000000000000 --- a/v2.1/tispark/tispark-user-guide_v1.x.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: TiSpark 用户指南 -category: tispark ---- - -# TiSpark 用户指南 - -TiSpark 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。TiSpark 依赖于 TiKV 集群和 Placement Driver (PD)，也需要你搭建一个 Spark 集群。 - -本文简单介绍如何部署和使用 TiSpark。本文假设你对 Spark 有基本认知。你可以参阅 [Apache Spark 官网](https://spark.apache.org/docs/latest/index.html) 了解 Spark 的相关信息。 - -## 概述 - -TiSpark 是将 Spark SQL 直接运行在分布式存储引擎 TiKV 上的 OLAP 解决方案。其架构图如下： - -![TiSpark Architecture](/media/tispark-architecture.png) - -+ TiSpark 深度整合了 Spark Catalyst 引擎, 可以对计算提供精确的控制，使 Spark 能够高效的读取 TiKV 中的数据，提供索引支持以实现高速的点查。 -+ 通过多种计算下推减少 Spark SQL 需要处理的数据大小，以加速查询；利用 TiDB 的内建的统计信息选择更优的查询计划。 -+ 从数据集群的角度看，TiSpark + TiDB 可以让用户无需进行脆弱和难以维护的 ETL，直接在同一个平台进行事务和分析两种工作，简化了系统架构和运维。 -+ 除此之外，用户借助 TiSpark 项目可以在 TiDB 上使用 Spark 生态圈提供的多种工具进行数据处理。例如，使用 TiSpark 进行数据分析和 ETL；使用 TiKV 作为机器学习的数据源；借助调度系统产生定时报表等等。 - -## 环境准备 - -现有 TiSpark 版本支持 Spark 2.1。对于 Spark 2.0 及 Spark 2.2 尚未经过良好的测试验证，对于更低版本暂时不支持。 - -TiSpark 需要 JDK 1.8+ 以及 Scala 2.11（Spark2.0+ 默认 Scala 版本）。 - -TiSpark 可以在 YARN，Mesos，Standalone 等任意 Spark 模式下运行。 - -## 推荐配置 - -本部分描述了 TiKV 与 TiSpark 集群分开部署、Spark 与 TiSpark 集群独立部署，以及TiSpark 与 TiKV 集群混合部署的建议配置。 - -### TiKV 与 TiSpark 集群分开部署的配置 - -对于 TiKV 与 TiSpark 分开部署的场景，可以参考如下建议配置： - -+ 硬件配置建议 - - 普通场景可以参考 [TiDB 和 TiKV 硬件配置建议](/v2.1/how-to/deploy/hardware-recommendations.md)，但是如果是偏重分析的场景，可以将 TiKV 节点增加到至少 64G 内存。 - -+ TiKV 参数建议 - - ```toml - [server] - end-point-concurrency = 8 # 如果使用场景偏向分析，则可以考虑扩大这个参数 - [raftstore] - sync-log = false - [rocksdb] - max-background-compactions = 6 - max-background-flushes = 2 - [rocksdb.defaultcf] - block-cache-size = "10GB" - [rocksdb.writecf] - block-cache-size = "4GB" - [rocksdb.raftcf] - block-cache-size = "1GB" - [rocksdb.lockcf] - block-cache-size = "1GB" - [storage] - scheduler-worker-pool-size = 4 - ``` - -### Spark 与 TiSpark 集群独立部署的配置 - -关于 Spark 的详细硬件推荐配置请参考[官网](https://spark.apache.org/docs/latest/hardware-provisioning.html)，如下是 TiSpark 所需环境的简单描述： - -Spark 推荐 32G 内存以上的配额。请在配置中预留 25% 的内存给操作系统。 - -Spark 推荐每台计算节点配备 CPU 累计 8 到 16 核以上。你可以初始设定分配所有 CPU 核给 Spark。 - -Spark 的具体配置方式也请参考[官方说明](https://spark.apache.org/docs/latest/spark-standalone.html)。以下为根据 `spark-env.sh` 配置的范例： - -``` -SPARK_EXECUTOR_CORES: 5 -SPARK_EXECUTOR_MEMORY: 10g -SPARK_WORKER_CORES: 5 -SPARK_WORKER_MEMORY: 10g -``` - -### TiSpark 与 TiKV 集群混合部署的配置 - -对于 TiKV 与 TiSpark 混合部署的场景，需在原有 TiKV 预留资源之外累加 Spark 所需部分，并分配 25% 的内存作为系统本身占用。 - -## 部署 TiSpark - -TiSpark 的 jar 包可以在[这里](https://download.pingcap.org/tispark-0.1.0-SNAPSHOT-jar-with-dependencies.jar)下载。 - -### 已有 Spark 集群的部署方式 - -如果在已有 Spark 集群上运行 TiSpark，无需重启集群。可以使用 Spark 的 `--jars` 参数将 TiSpark 作为依赖引入： - -``` -spark-shell --jars $PATH/tispark-0.1.0.jar -``` - -如果想将 TiSpark 作为默认组件部署，只需要将 TiSpark 的 jar 包放进 Spark 集群每个节点的 jars 路径并重启 Spark 集群： - -``` -${SPARK_INSTALL_PATH}/jars -``` - -这样无论是使用 Spark-Submit 还是 Spark-Shell 都可以直接使用 TiSpark。 - -### 没有 Spark 集群的部署方式 - -如果没有使用中的 Spark 集群，推荐使用 Saprk Standalone 方式部署。这里简单介绍下 Standalone 部署方式。如果遇到问题，可以去官网寻求[帮助](https://spark.apache.org/docs/latest/spark-standalone.html)；也欢迎在我们的 GitHub 上提 [issue](https://github.com/pingcap/tispark/issues/new)。 - -#### 下载安装包并安装 - -你可以在 [Download Apache Spark™ 页面](https://spark.apache.org/downloads.html)下载 Apache Spark。 - -对于 Standalone 模式且无需 Hadoop 支持，则选择 Spark 2.1.x 且带有 Hadoop 依赖的 Pre-build with Apache Hadoop 2.x 任意版本。如有需要配合使用的 Hadoop 集群，则选择对应的 Hadoop 版本号。你也可以选择从源代码[自行构建](https://spark.apache.org/docs/2.1.0/building-spark.html)以配合官方 Hadoop 2.6 之前的版本。 - -> **注意：** -> -> 目前 TiSpark 仅支持 Spark 2.1.x 版本。 - -如果你已经有了 Spark 二进制文件，并且当前 PATH 为 SPARKPATH，需将 TiSpark jar 包拷贝到 `${SPARKPATH}/jars` 目录下。 - -#### 启动 Master - -在选中的 Spark Master 节点执行如下命令： - -``` -cd $SPARKPATH -./sbin/start-master.sh -``` - -在这步完成以后，屏幕上会打印出一个 log 文件。检查 log 文件确认 Spark-Master 是否启动成功。你可以打开 查看集群信息（如果你没有改动 Spark-Master 默认 Port Number）。在启动 Spark-Slave 的时候，也可以通过这个面板来确认 Slave 是否已经加入集群。 - -#### 启动 Slave - -类似地，可以用如下命令启动 Spark-Slave 节点： - -```bash -./sbin/start-slave.sh spark://spark-master-hostname:7077 -``` - -命令返回以后，即可通过刚才的面板查看这个 Slave 是否已经正确地加入了 Spark 集群。在所有 Slave 节点重复刚才的命令。确认所有的 Slave 都可以正确连接 Master，这样你就拥有了一个 Standalone 模式的 Spark 集群。 - -## 一个使用范例 - -假设你已经按照上述步骤成功启动了 TiSpark 集群，下面简单介绍如何使用 Spark SQL 来做 OLAP 分析。这里我们用名为 tpch 数据库中的 lineitem 表作为范例。 - -假设你的 PD 节点位于 192.168.1.100，端口为 2379，在`$SPARK_HOME/conf/spark-defaults.conf`加入： - -``` -spark.tispark.pd.addresses 192.168.1.100:2379 -``` - -然后在 Spark-Shell 里输入下面的命令： - -```scala -import org.apache.spark.sql.TiContext - -val ti = new TiContext(spark) - -ti.tidbMapDatabase("tpch") -``` - -之后你可以直接调用 Spark SQL: - -```scala -spark.sql("select count(*) from lineitem").show -``` - -结果为： - -``` -+-------------+ -| Count (1) | -+-------------+ -| 600000000 | -+-------------+ -``` - -## TiSpark FAQ - -- Q. 是独立部署还是和现有 Spark／Hadoop 集群共用资源？ - - A. 可以利用现有 Spark 集群无需单独部署，但是如果现有集群繁忙，TiSpark 将无法达到理想速度。 - -- Q. 是否可以和 TiKV 混合部署？ - - A. 如果 TiDB 以及 TiKV 负载较高且运行关键的线上任务，请考虑单独部署 TiSpark；并且考虑使用不同的网卡保证 OLTP 的网络资源不被侵占而影响线上业务。如果线上业务要求不高或者机器负载不大，可以考虑与 TiKV 混合部署。 diff --git a/v3.0/TOC.md b/v3.0/TOC.md deleted file mode 100644 index 1a53cbb5b2f8..000000000000 --- a/v3.0/TOC.md +++ /dev/null @@ -1,482 +0,0 @@ -# TiDB 中文用户文档 - - - - -## 目录 - -+ 关于 TiDB - - [TiDB 简介](/v3.0/overview.md) - + Benchmark 测试 - - [如何用 Sysbench 测试 TiDB](/v3.0/benchmark/how-to-run-sysbench.md) - - [如何对 TiDB 进行 TPC-C 测试](/v3.0/benchmark/how-to-run-tpcc.md) - - [Sysbench 性能对比 - v3.0 对比 v2.1](/v3.0/benchmark/sysbench-v4.md) - - [TPC-C 性能对比 - v3.0 对比 v2.1](/v3.0/benchmark/tpcc.md) - - [线上负载与 `Add Index` 相互影响测试](/v3.0/benchmark/add-index-with-load.md) - - [TiDB in Kubernetes Sysbench 性能测试](/v3.0/benchmark/sysbench-in-k8s.md) - - [DM 1.0-GA 性能测试](/v3.0/benchmark/dm-v1.0-ga.md) -+ 主要概念 - - [整体架构](/v3.0/architecture.md) - + 核心特性 - - [水平扩展](/v3.0/key-features.md#水平扩展) - - [高可用](/v3.0/key-features.md#高可用) -+ 操作指南 - + 快速上手 - + 创建集群 - - [使用 Docker Compose 部署 TiDB 集群](https://pingcap.com/docs-cn/dev/how-to/get-started/deploy-tidb-from-docker-compose/) - - [SQL 基本操作](/v3.0/how-to/get-started/explore-sql.md) - - [读取历史数据](/v3.0/how-to/get-started/read-historical-data.md) - - [TiDB Binlog 教程](/v3.0/how-to/get-started/tidb-binlog.md) - - [TiDB Data Migration 教程](/v3.0/how-to/get-started/data-migration.md) - - [TiDB Lightning 教程](/v3.0/how-to/get-started/tidb-lightning.md) - - [TiSpark 教程](/v3.0/how-to/get-started/tispark.md) - + 部署 - - [软硬件环境需求](/v3.0/how-to/deploy/hardware-recommendations.md) - + 集群部署方式 - - [使用 Ansible 部署（推荐）](/v3.0/how-to/deploy/orchestrated/ansible.md) - - [使用 Ansible 离线部署](/v3.0/how-to/deploy/orchestrated/offline-ansible.md) - - [使用 Docker 部署](/v3.0/how-to/deploy/orchestrated/docker.md) - + 跨地域冗余 - - [跨数据中心部署方案](/v3.0/how-to/deploy/geographic-redundancy/overview.md) - - [配置集群拓扑](/v3.0/how-to/deploy/geographic-redundancy/location-awareness.md) - - [使用 Ansible 部署 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md) - + 配置 - - [时区](/v3.0/how-to/configure/time-zone.md) - - [内存控制](/v3.0/how-to/configure/memory-control.md) - + 安全 - + 安全传输层协议 (TLS) - - [为 MySQL 客户端开启 TLS](/v3.0/how-to/secure/enable-tls-clients.md) - - [为 TiDB 组件间开启 TLS](/v3.0/how-to/secure/enable-tls-between-components.md) - - [生成自签名证书](/v3.0/how-to/secure/generate-self-signed-certificates.md) - + 监控 - - [概述](/v3.0/how-to/monitor/overview.md) - - [监控 TiDB 集群](/v3.0/how-to/monitor/monitor-a-cluster.md) - + 迁移 - - [迁移工具使用指南](/v3.0/reference/tools/user-guide.md) - + 从 MySQL 迁移 - - [以 Amazon Aurora MySQL 为例](/v3.0/how-to/migrate/from-mysql-aurora.md) - - [从 CSV 迁移](/v3.0/reference/tools/tidb-lightning/csv.md) - + 运维 - - [Ansible 常见运维操作](/v3.0/how-to/maintain/ansible-operations.md) - + [备份与恢复](/v3.0/how-to/maintain/backup-and-restore.md) - + 定位异常查询 - - [定位慢查询](/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) - - [定位消耗系统资源多的查询](/v3.0/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md) - + 扩容缩容 - - [使用 Ansible 扩容缩容](/v3.0/how-to/scale/with-ansible.md) - + 升级 - - [升级至 TiDB 3.0](/v3.0/how-to/upgrade/from-previous-version.md) - + 故障诊断 - - [集群配置诊断](/v3.0/how-to/troubleshoot/cluster-setup.md) - - [TiDB Lightning 故障诊断](/v3.0/how-to/troubleshoot/tidb-lightning.md) -+ 参考手册 - + SQL - - [与 MySQL 兼容性对比](/v3.0/reference/mysql-compatibility.md) - + SQL 语言结构 - - [字面值](/v3.0/reference/sql/language-structure/literal-values.md) - - [Schema 对象名](/v3.0/reference/sql/language-structure/schema-object-names.md) - - [关键字和保留字](/v3.0/reference/sql/language-structure/keywords-and-reserved-words.md) - - [用户自定义变量](/v3.0/reference/sql/language-structure/user-defined-variables.md) - - [表达式语法](/v3.0/reference/sql/language-structure/expression-syntax.md) - - [注释语法](/v3.0/reference/sql/language-structure/comment-syntax.md) - + 数据类型 - - [概述](/v3.0/reference/sql/data-types/overview.md) - - [默认值](/v3.0/reference/sql/data-types/default-values.md) - + 数值类型 - - [`BIT`](/v3.0/reference/sql/data-types/numeric.md#bit-类型) - - [`BOOL|BOOLEAN`](/v3.0/reference/sql/data-types/numeric.md#boolean-类型) - - [`TINYINT`](/v3.0/reference/sql/data-types/numeric.md#tinyint-类型) - - [`SMALLINT`](/v3.0/reference/sql/data-types/numeric.md#smallint-类型) - - [`MEDIUMINT`](/v3.0/reference/sql/data-types/numeric.md#mediumint-类型) - - [`INT|INTEGER`](/v3.0/reference/sql/data-types/numeric.md#integer-类型) - - [`BIGINT`](/v3.0/reference/sql/data-types/numeric.md#bigint-类型) - - [`DECIMAL`](/v3.0/reference/sql/data-types/numeric.md#decimal-类型) - - [`FLOAT`](/v3.0/reference/sql/data-types/numeric.md#float-类型) - - [`DOUBLE`](/v3.0/reference/sql/data-types/numeric.md#double-类型) - + 日期和时间类型 - - [`DATE`](/v3.0/reference/sql/data-types/date-and-time.md#date-类型) - - [`DATETIME`](/v3.0/reference/sql/data-types/date-and-time.md#datetime-类型) - - [`TIMESTAMP`](/v3.0/reference/sql/data-types/date-and-time.md#timestamp-类型) - - [`TIME`](/v3.0/reference/sql/data-types/date-and-time.md#time-类型) - - [`YEAR`](/v3.0/reference/sql/data-types/date-and-time.md#year-类型) - + 字符串类型 - - [`CHAR`](/v3.0/reference/sql/data-types/string.md#char-类型) - - [`VARCHAR`](/v3.0/reference/sql/data-types/string.md#varchar-类型) - - [`TEXT`](/v3.0/reference/sql/data-types/string.md#text-类型) - - [`LONGTEXT`](/v3.0/reference/sql/data-types/string.md#longtext-类型) - - [`BINARY`](/v3.0/reference/sql/data-types/string.md#binary-类型) - - [`VARBINARY`](/v3.0/reference/sql/data-types/string.md#varbinary-类型) - - [`TINYBLOB`](/v3.0/reference/sql/data-types/string.md#tinyblob-类型) - - [`BLOB`](/v3.0/reference/sql/data-types/string.md#blob-类型) - - [`MEDIUMBLOB`](/v3.0/reference/sql/data-types/string.md#mediumblob-类型) - - [`LONGBLOB`](/v3.0/reference/sql/data-types/string.md#longblob-类型) - - [`ENUM`](/v3.0/reference/sql/data-types/string.md#enum-类型) - - [`SET`](/v3.0/reference/sql/data-types/string.md#set-类型) - - [JSON Type](/v3.0/reference/sql/data-types/json.md) - + 函数与操作符 - - [函数与操作符概述](/v3.0/reference/sql/functions-and-operators/reference.md) - - [表达式求值的类型转换](/v3.0/reference/sql/functions-and-operators/type-conversion.md) - - [操作符](/v3.0/reference/sql/functions-and-operators/operators.md) - - [控制流程函数](/v3.0/reference/sql/functions-and-operators/control-flow-functions.md) - - [字符串函数](/v3.0/reference/sql/functions-and-operators/string-functions.md) - - [数值函数与操作符](/v3.0/reference/sql/functions-and-operators/numeric-functions-and-operators.md) - - [日期和时间函数](/v3.0/reference/sql/functions-and-operators/date-and-time-functions.md) - - [位函数和操作符](/v3.0/reference/sql/functions-and-operators/bit-functions-and-operators.md) - - [Cast 函数和操作符](/v3.0/reference/sql/functions-and-operators/cast-functions-and-operators.md) - - [加密和压缩函数](/v3.0/reference/sql/functions-and-operators/encryption-and-compression-functions.md) - - [信息函数](/v3.0/reference/sql/functions-and-operators/information-functions.md) - - [JSON 函数](/v3.0/reference/sql/functions-and-operators/json-functions.md) - - [GROUP BY 聚合函数](/v3.0/reference/sql/functions-and-operators/aggregate-group-by-functions.md) - - [窗口函数](/v3.0/reference/sql/functions-and-operators/window-functions.md) - - [其它函数](/v3.0/reference/sql/functions-and-operators/miscellaneous-functions.md) - - [精度数学](/v3.0/reference/sql/functions-and-operators/precision-math.md) - - [下推到 TiKV 的表达式列表](/v3.0/reference/sql/functions-and-operators/expressions-pushed-down.md) - + SQL 语句 - - [`ADD COLUMN`](/v3.0/reference/sql/statements/add-column.md) - - [`ADD INDEX`](/v3.0/reference/sql/statements/add-index.md) - - [`ADMIN`](/v3.0/reference/sql/statements/admin.md) - - [`ALTER DATABASE`](/v3.0/reference/sql/statements/alter-database.md) - - [`ALTER TABLE`](/v3.0/reference/sql/statements/alter-table.md) - - [`ALTER USER`](/v3.0/reference/sql/statements/alter-user.md) - - [`ANALYZE TABLE`](/v3.0/reference/sql/statements/analyze-table.md) - - [`BEGIN`](/v3.0/reference/sql/statements/begin.md) - - [`COMMIT`](/v3.0/reference/sql/statements/commit.md) - - [`CREATE DATABASE`](/v3.0/reference/sql/statements/create-database.md) - - [`CREATE INDEX`](/v3.0/reference/sql/statements/create-index.md) - - [`CREATE TABLE LIKE`](/v3.0/reference/sql/statements/create-table-like.md) - - [`CREATE TABLE`](/v3.0/reference/sql/statements/create-table.md) - - [`CREATE USER`](/v3.0/reference/sql/statements/create-user.md) - - [`CREATE VIEW`](/v3.0/reference/sql/statements/create-view.md) - - [`DEALLOCATE`](/v3.0/reference/sql/statements/deallocate.md) - - [`DELETE`](/v3.0/reference/sql/statements/delete.md) - - [`DESC`](/v3.0/reference/sql/statements/desc.md) - - [`DESCRIBE`](/v3.0/reference/sql/statements/describe.md) - - [`DO`](/v3.0/reference/sql/statements/do.md) - - [`DROP COLUMN`](/v3.0/reference/sql/statements/drop-column.md) - - [`DROP DATABASE`](/v3.0/reference/sql/statements/drop-database.md) - - [`DROP INDEX`](/v3.0/reference/sql/statements/drop-index.md) - - [`DROP TABLE`](/v3.0/reference/sql/statements/drop-table.md) - - [`DROP USER`](/v3.0/reference/sql/statements/drop-user.md) - - [`DROP VIEW`](/v3.0/reference/sql/statements/drop-view.md) - - [`EXECUTE`](/v3.0/reference/sql/statements/execute.md) - - [`EXPLAIN ANALYZE`](/v3.0/reference/sql/statements/explain-analyze.md) - - [`EXPLAIN`](/v3.0/reference/sql/statements/explain.md) - - [`FLUSH PRIVILEGES`](/v3.0/reference/sql/statements/flush-privileges.md) - - [`FLUSH STATUS`](/v3.0/reference/sql/statements/flush-status.md) - - [`FLUSH TABLES`](/v3.0/reference/sql/statements/flush-tables.md) - - [`GRANT `](/v3.0/reference/sql/statements/grant-privileges.md) - - [`INSERT`](/v3.0/reference/sql/statements/insert.md) - - [`KILL [TIDB]`](/v3.0/reference/sql/statements/kill.md) - - [`LOAD DATA`](/v3.0/reference/sql/statements/load-data.md) - - [`MODIFY COLUMN`](/v3.0/reference/sql/statements/modify-column.md) - - [`PREPARE`](/v3.0/reference/sql/statements/prepare.md) - - [`RECOVER TABLE`](/v3.0/reference/sql/statements/recover-table.md) - - [`RENAME INDEX`](/v3.0/reference/sql/statements/rename-index.md) - - [`RENAME TABLE`](/v3.0/reference/sql/statements/rename-table.md) - - [`REPLACE`](/v3.0/reference/sql/statements/replace.md) - - [`REVOKE `](/v3.0/reference/sql/statements/revoke-privileges.md) - - [`ROLLBACK`](/v3.0/reference/sql/statements/rollback.md) - - [`SELECT`](/v3.0/reference/sql/statements/select.md) - - [`SET [NAMES|CHARACTER SET]`](/v3.0/reference/sql/statements/set-names.md) - - [`SET PASSWORD`](/v3.0/reference/sql/statements/set-password.md) - - [`SET TRANSACTION`](/v3.0/reference/sql/statements/set-transaction.md) - - [`SET [GLOBAL|SESSION] `](/v3.0/reference/sql/statements/set-variable.md) - - [`SHOW CHARACTER SET`](/v3.0/reference/sql/statements/show-character-set.md) - - [`SHOW COLLATION`](/v3.0/reference/sql/statements/show-collation.md) - - [`SHOW [FULL] COLUMNS FROM`](/v3.0/reference/sql/statements/show-columns-from.md) - - [`SHOW CREATE TABLE`](/v3.0/reference/sql/statements/show-create-table.md) - - [`SHOW CREATE USER`](/v3.0/reference/sql/statements/show-create-user.md) - - [`SHOW DATABASES`](/v3.0/reference/sql/statements/show-databases.md) - - [`SHOW ENGINES`](/v3.0/reference/sql/statements/show-engines.md) - - [`SHOW ERRORS`](/v3.0/reference/sql/statements/show-errors.md) - - [`SHOW [FULL] FIELDS FROM`](/v3.0/reference/sql/statements/show-fields-from.md) - - [`SHOW GRANTS`](/v3.0/reference/sql/statements/show-grants.md) - - [`SHOW INDEXES [FROM|IN]`](/v3.0/reference/sql/statements/show-indexes.md) - - [`SHOW INDEX [FROM|IN]`](/v3.0/reference/sql/statements/show-index.md) - - [`SHOW KEYS [FROM|IN]`](/v3.0/reference/sql/statements/show-keys.md) - - [`SHOW PRIVILEGES`](/v3.0/reference/sql/statements/show-privileges.md) - - [`SHOW [FULL] PROCESSSLIST`](/v3.0/reference/sql/statements/show-processlist.md) - - [`SHOW SCHEMAS`](/v3.0/reference/sql/statements/show-schemas.md) - - [`SHOW [FULL] TABLES`](/v3.0/reference/sql/statements/show-tables.md) - - [`SHOW TABLE REGIONS`](/v3.0/reference/sql/statements/show-table-regions.md) - - [`SHOW TABLE STATUS`](/v3.0/reference/sql/statements/show-table-status.md) - - [`SHOW [GLOBAL|SESSION] VARIABLES`](/v3.0/reference/sql/statements/show-variables.md) - - [`SHOW WARNINGS`](/v3.0/reference/sql/statements/show-warnings.md) - - [`SPLIT REGION`](/v3.0/reference/sql/statements/split-region.md) - - [`START TRANSACTION`](/v3.0/reference/sql/statements/start-transaction.md) - - [`TRACE`](/v3.0/reference/sql/statements/trace.md) - - [`TRUNCATE`](/v3.0/reference/sql/statements/truncate.md) - - [`UPDATE`](/v3.0/reference/sql/statements/update.md) - - [`USE`](/v3.0/reference/sql/statements/use.md) - - [约束](/v3.0/reference/sql/constraints.md) - - [生成列](/v3.0/reference/sql/generated-columns.md) - - [分区表](/v3.0/reference/sql/partitioning.md) - - [字符集](/v3.0/reference/sql/character-set.md) - - [SQL 模式](/v3.0/reference/sql/sql-mode.md) - - [视图](/v3.0/reference/sql/view.md) - + 配置 - + tidb-server - - [MySQL 系统变量](/v3.0/reference/configuration/tidb-server/mysql-variables.md) - - [TiDB 特定系统变量](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md) - - [配置参数](/v3.0/reference/configuration/tidb-server/configuration.md) - - [配置文件描述](/v3.0/reference/configuration/tidb-server/configuration-file.md) - + pd-server - - [配置参数](/v3.0/reference/configuration/pd-server/configuration.md) - - [配置文件描述](/v3.0/reference/configuration/pd-server/configuration-file.md) - + tikv-server - - [配置参数](/v3.0/reference/configuration/tikv-server/configuration.md) - - [配置文件描述](/v3.0/reference/configuration/tikv-server/configuration-file.md) - + 安全 - - [与 MySQL 的安全特性差异](/v3.0/reference/security/compatibility.md) - - [TiDB 数据库权限管理](/v3.0/reference/security/privilege-system.md) - - [TiDB 用户账户管理](/v3.0/reference/security/user-account-management.md) - - [基于角色的访问控制](/v3.0/reference/security/role-based-access-control.md) - - [TiDB 证书鉴权使用指南](/v3.0/reference/security/cert-based-authentication.md) - + 事务 - - [事务概览](/v3.0/reference/transactions/overview.md) - - [隔离级别](/v3.0/reference/transactions/transaction-isolation.md) - - [乐观事务](/v3.0/reference/transactions/transaction-optimistic.md) - - [悲观事务](/v3.0/reference/transactions/transaction-pessimistic.md) - + 系统数据库 - - [`mysql`](/v3.0/reference/system-databases/mysql.md) - - [`information_schema`](/v3.0/reference/system-databases/information-schema.md) - - [错误码](/v3.0/reference/error-codes.md) - - [支持的连接器和 API](/v3.0/reference/supported-clients.md) - + 垃圾回收 (GC) - - [GC 机制简介](/v3.0/reference/garbage-collection/overview.md) - - [GC 配置](/v3.0/reference/garbage-collection/configuration.md) - + 性能调优 - - [SQL 优化流程](/v3.0/reference/performance/sql-optimizer-overview.md) - - [理解 TiDB 执行计划](/v3.0/reference/performance/understanding-the-query-execution-plan.md) - - [执行计划绑定](/v3.0/reference/performance/execution-plan-bind.md) - - [统计信息概述](/v3.0/reference/performance/statistics.md) - - [Optimizer Hints](/v3.0/reference/performance/optimizer-hints.md) - - [使用 SQL 语句检查 TiDB 集群状态](/v3.0/reference/performance/check-cluster-status-using-sql-statements.md) - - [Statement Summary Table](/v3.0/reference/performance/statement-summary.md) - - [TiKV 调优](/v3.0/reference/performance/tune-tikv.md) - - [TiDB 最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/) - + 监控指标 - - [Overview 面板](/v3.0/reference/key-monitoring-metrics/overview-dashboard.md) - - [TiDB 面板](/v3.0/reference/key-monitoring-metrics/tidb-dashboard.md) - - [PD 面板](/v3.0/reference/key-monitoring-metrics/pd-dashboard.md) - - [TiKV 面板](/v3.0/reference/key-monitoring-metrics/tikv-dashboard.md) - - [报警规则](/v3.0/reference/alert-rules.md) - + 最佳实践 - - [HAProxy 最佳实践](/v3.0/reference/best-practices/haproxy.md) - - [Java 应用开发最佳实践](/v3.0/reference/best-practices/java-app.md) - - [高并发写入场景最佳实践](/v3.0/reference/best-practices/high-concurrency.md) - - [Grafana 监控最佳实践](/v3.0/reference/best-practices/grafana-monitor.md) - - [PD 调度策略最佳实践](/v3.0/reference/best-practices/pd-scheduling.md) - - [海量 Region 集群调优最佳实践](/v3.0/reference/best-practices/massive-regions.md) - + [TiSpark 使用指南](/v3.0/reference/tispark.md) - + TiDB Binlog - - [概述](/v3.0/reference/tidb-binlog/overview.md) - - [部署使用](/v3.0/reference/tidb-binlog/deploy.md) - - [运维管理](/v3.0/reference/tidb-binlog/maintain.md) - - [版本升级](/v3.0/reference/tidb-binlog/upgrade.md) - - [监控告警](/v3.0/reference/tidb-binlog/monitor.md) - - [增量恢复](/v3.0/reference/tidb-binlog/reparo.md) - - [Kafka 自定义开发](/v3.0/reference/tidb-binlog/binlog-slave-client.md) - - [TiDB Binlog Relay Log](/v3.0/reference/tidb-binlog/relay-log.md) - - [术语表](/v3.0/reference/tidb-binlog/glossary.md) - + 故障诊断 - - [故障诊断](/v3.0/reference/tidb-binlog/troubleshoot/binlog.md) - - [常见错误修复](/v3.0/reference/tidb-binlog/troubleshoot/error-handling.md) - - [FAQ](/v3.0/reference/tidb-binlog/faq.md) - + 周边工具 - - [工具使用指南](/v3.0/reference/tools/user-guide.md) - - [Mydumper](/v3.0/reference/tools/mydumper.md) - - [Loader](/v3.0/reference/tools/loader.md) - - [Syncer](/v3.0/reference/tools/syncer.md) - + Data Migration - + 概述 - - [DM 架构](/v3.0/reference/tools/data-migration/overview.md#dm-架构) - - [同步功能介绍](/v3.0/reference/tools/data-migration/overview.md#同步功能介绍) - - [使用限制](/v3.0/reference/tools/data-migration/overview.md#使用限制) - - [DM-worker 简介](/v3.0/reference/tools/data-migration/dm-worker-intro.md) - - [DM Relay Log](/v3.0/reference/tools/data-migration/relay-log.md) - + 核心特性 - - [Table Routing](/v3.0/reference/tools/data-migration/features/overview.md#table-routing) - - [Black & White Lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists) - - [Binlog Event Filter](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) - - [同步延迟监控](/v3.0/reference/tools/data-migration/features/overview.md#同步延迟监控) - + Shard Support - - [简介](/v3.0/reference/tools/data-migration/features/shard-merge.md) - - [使用限制](/v3.0/reference/tools/data-migration/features/shard-merge.md#使用限制) - - [手动处理 Sharding DDL Lock](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) - + 使用场景 - - [简单的从库同步场景](/v3.0/reference/tools/data-migration/usage-scenarios/simple-synchronization.md) - - [分库分表合并场景](/v3.0/reference/tools/data-migration/usage-scenarios/shard-merge.md) - - [分表合并数据迁移最佳实践](/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md) - - [DM-worker 在上游 MySQL 主从间切换](/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md) - + [部署使用](/v3.0/reference/tools/data-migration/deploy.md) - + 配置 - - [概述](/v3.0/reference/tools/data-migration/configure/overview.md) - - [DM-master 配置](/v3.0/reference/tools/data-migration/configure/dm-master-configuration-file.md) - - [DM-worker 配置](/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - - [任务配置](/v3.0/reference/tools/data-migration/configure/task-configuration-file.md) - + DM 集群管理 - - [集群操作](/v3.0/reference/tools/data-migration/cluster-operations.md) - - [集群升级](/v3.0/reference/tools/data-migration/dm-upgrade.md) - + DM 同步任务管理 - - [管理数据同步任务](/v3.0/reference/tools/data-migration/manage-tasks.md) - - [任务前置检查](/v3.0/reference/tools/data-migration/precheck.md) - - [任务状态查询](/v3.0/reference/tools/data-migration/query-status.md) - - [跳过或替代执行异常的 SQL 语句](/v3.0/reference/tools/data-migration/skip-replace-sqls.md) - - [监控 DM 集群](/v3.0/reference/tools/data-migration/monitor.md) - + 从与 MySQL 兼容的数据库迁移数据 - - [从 MySQL/Amazon Aurora MySQL 迁移数据](/v3.0/how-to/migrate/from-mysql-aurora.md) - - [DM Portal](/v3.0/reference/tools/data-migration/dm-portal.md) - + DM 故障诊断 - - [故障诊断](/v3.0/reference/tools/data-migration/troubleshoot/dm.md) - - [错误含义](/v3.0/reference/tools/data-migration/troubleshoot/error-system.md) - - [常见错误修复](/v3.0/reference/tools/data-migration/troubleshoot/error-handling.md) - - [DM FAQ](/v3.0/reference/tools/data-migration/faq.md) - + 版本发布历史 - + v1.0 - - [1.0.2](/v3.0/reference/tools/data-migration/releases/1.0.2.md) - - [1.0.3](/v3.0/reference/tools/data-migration/releases/1.0.3.md) - - [TiDB DM 术语表](/v3.0/reference/tools/data-migration/glossary.md) - + TiDB Lightning - - [概述](/v3.0/reference/tools/tidb-lightning/overview.md) - - [部署执行](/v3.0/reference/tools/tidb-lightning/deployment.md) - - [参数说明](/v3.0/reference/tools/tidb-lightning/config.md) - - [断点续传](/v3.0/reference/tools/tidb-lightning/checkpoints.md) - - [表库过滤](/v3.0/reference/tools/tidb-lightning/table-filter.md) - - [CSV 支持](/v3.0/reference/tools/tidb-lightning/csv.md) - - [TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) - - [Web 界面](/v3.0/reference/tools/tidb-lightning/web.md) - - [监控告警](/v3.0/reference/tools/tidb-lightning/monitor.md) - - [故障诊断](/v3.0/how-to/troubleshoot/tidb-lightning.md) - - [FAQ](/v3.0/faq/tidb-lightning.md) - - [术语表](/v3.0/reference/tools/tidb-lightning/glossary.md) - - [sync-diff-inspector](/v3.0/reference/tools/sync-diff-inspector/overview.md) - - [PD Control](/v3.0/reference/tools/pd-control.md) - - [PD Recover](/v3.0/reference/tools/pd-recover.md) - - [TiKV Control](/v3.0/reference/tools/tikv-control.md) - - [TiDB Controller](/v3.0/reference/tools/tidb-control.md) - - [工具下载](/v3.0/reference/tools/download.md) -+ TiDB in Kubernetes - - [TiDB Operator 简介](/v3.0/tidb-in-kubernetes/tidb-operator-overview.md) - + 快速上手 - - [kind](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) - - [GKE](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) - - [Minikube](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md) - + 部署 - - [集群环境要求](/v3.0/tidb-in-kubernetes/deploy/prerequisites.md) - - [部署 TiDB Operator](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md) - - [标准 Kubernetes 上的 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md) - - [AWS EKS 上的 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/aws-eks.md) - - [GCP 上的 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md) - - [阿里云上的 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/alibaba-cloud.md) - - [访问 Kubernetes 上的 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/access-tidb.md) - + 配置 - - [初始化集群](/v3.0/tidb-in-kubernetes/initialize-cluster.md) - - [监控](/v3.0/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) - + 运维 - - [销毁 TiDB 集群](/v3.0/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md) - - [维护 TiDB 集群所在节点](/v3.0/tidb-in-kubernetes/maintain/kubernetes-node.md) - - [备份与恢复](/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md) - - [恢复 Kubernetes 上的 TiDB 集群数据](/v3.0/tidb-in-kubernetes/maintain/lightning.md) - - [收集日志](/v3.0/tidb-in-kubernetes/maintain/log-collecting.md) - - [集群故障自动转移](/v3.0/tidb-in-kubernetes/maintain/auto-failover.md) - - [TiDB Binlog](/v3.0/tidb-in-kubernetes/maintain/tidb-binlog.md) - - [重启 TiDB 集群](/v3.0/tidb-in-kubernetes/maintain/restart.md) - - [扩缩容](/v3.0/tidb-in-kubernetes/scale-in-kubernetes.md) - + 升级 - - [TiDB 集群](/v3.0/tidb-in-kubernetes/upgrade/tidb-cluster.md) - - [TiDB Operator](/v3.0/tidb-in-kubernetes/upgrade/tidb-operator.md) - + 参考信息 - + 配置 - - [集群配置](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md) - - [备份配置](/v3.0/tidb-in-kubernetes/reference/configuration/backup.md) - - [PV 配置](/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md) - - [TiDB Drainer](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - + 工具 - - [tkctl](/v3.0/tidb-in-kubernetes/reference/tools/tkctl.md) - - [相关工具使用](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md) - - [故障诊断](/v3.0/tidb-in-kubernetes/troubleshoot.md) - - [常见问题](/v3.0/tidb-in-kubernetes/faq.md) -+ 常见问题 (FAQ) - - [TiDB FAQ](/v3.0/faq/tidb.md) - - [TiDB Lightning FAQ](/v3.0/faq/tidb-lightning.md) - - [升级 FAQ](/v3.0/faq/upgrade.md) -+ 技术支持 - - [支持渠道](/v3.0/support-resources.md) - - [反馈问题](/v3.0/report-issue.md) -+ [贡献](/v3.0/contribute.md) - - [贡献代码](/v3.0/contribute.md#成为-tidb-的贡献者) - - [改进文档](/v3.0/contribute.md#改进文档) -+ [TiDB 路线图](/v3.0/roadmap.md) -+ [版本发布历史](/v3.0/releases/rn.md) - + v3.0 - - [3.0.10](/v3.0/releases/3.0.10.md) - - [3.0.9](/v3.0/releases/3.0.9.md) - - [3.0.8](/v3.0/releases/3.0.8.md) - - [3.0.7](/v3.0/releases/3.0.7.md) - - [3.0.6](/v3.0/releases/3.0.6.md) - - [3.0.5](/v3.0/releases/3.0.5.md) - - [3.0.4](/v3.0/releases/3.0.4.md) - - [3.0.3](/v3.0/releases/3.0.3.md) - - [3.0.2](/v3.0/releases/3.0.2.md) - - [3.0.1](/v3.0/releases/3.0.1.md) - - [3.0 GA](/v3.0/releases/3.0-ga.md) - - [3.0.0-rc.3](/v3.0/releases/3.0.0-rc.3.md) - - [3.0.0-rc.2](/v3.0/releases/3.0.0-rc.2.md) - - [3.0.0-rc.1](/v3.0/releases/3.0.0-rc.1.md) - - [3.0.0-beta.1](/v3.0/releases/3.0.0-beta.1.md) - - [3.0.0-beta](/v3.0/releases/3.0beta.md) - + v2.1 - - [2.1.19](/v3.0/releases/2.1.19.md) - - [2.1.18](/v3.0/releases/2.1.18.md) - - [2.1.17](/v3.0/releases/2.1.17.md) - - [2.1.16](/v3.0/releases/2.1.16.md) - - [2.1.15](/v3.0/releases/2.1.15.md) - - [2.1.14](/v3.0/releases/2.1.14.md) - - [2.1.13](/v3.0/releases/2.1.13.md) - - [2.1.12](/v3.0/releases/2.1.12.md) - - [2.1.11](/v3.0/releases/2.1.11.md) - - [2.1.10](/v3.0/releases/2.1.10.md) - - [2.1.9](/v3.0/releases/2.1.9.md) - - [2.1.8](/v3.0/releases/2.1.8.md) - - [2.1.7](/v3.0/releases/2.1.7.md) - - [2.1.6](/v3.0/releases/2.1.6.md) - - [2.1.5](/v3.0/releases/2.1.5.md) - - [2.1.4](/v3.0/releases/2.1.4.md) - - [2.1.3](/v3.0/releases/2.1.3.md) - - [2.1.2](/v3.0/releases/2.1.2.md) - - [2.1.1](/v3.0/releases/2.1.1.md) - - [2.1 GA](/v3.0/releases/2.1ga.md) - - [2.1 RC5](/v3.0/releases/21rc5.md) - - [2.1 RC4](/v3.0/releases/21rc4.md) - - [2.1 RC3](/v3.0/releases/21rc3.md) - - [2.1 RC2](/v3.0/releases/21rc2.md) - - [2.1 RC1](/v3.0/releases/21rc1.md) - - [2.1 Beta](/v3.0/releases/21beta.md) - + v2.0 - - [2.0.11](/v3.0/releases/2.0.11.md) - - [2.0.10](/v3.0/releases/2.0.10.md) - - [2.0.9](/v3.0/releases/209.md) - - [2.0.8](/v3.0/releases/208.md) - - [2.0.7](/v3.0/releases/207.md) - - [2.0.6](/v3.0/releases/206.md) - - [2.0.5](/v3.0/releases/205.md) - - [2.0.4](/v3.0/releases/204.md) - - [2.0.3](/v3.0/releases/203.md) - - [2.0.2](/v3.0/releases/202.md) - - [2.0.1](/v3.0/releases/201.md) - - [2.0](/v3.0/releases/2.0ga.md) - - [2.0 RC5](/v3.0/releases/2rc5.md) - - [2.0 RC4](/v3.0/releases/2rc4.md) - - [2.0 RC3](/v3.0/releases/2rc3.md) - - [2.0 RC1](/v3.0/releases/2rc1.md) - - [1.1 Beta](/v3.0/releases/11beta.md) - - [1.1 Alpha](/v3.0/releases/11alpha.md) - + v1.0 - - [1.0](/v3.0/releases/ga.md) - - [Pre-GA](/v3.0/releases/prega.md) - - [RC4](/v3.0/releases/rc4.md) - - [RC3](/v3.0/releases/rc3.md) - - [RC2](/v3.0/releases/rc2.md) - - [RC1](/v3.0/releases/rc1.md) -+ [术语表](/v3.0/glossary.md) diff --git a/v3.0/_index.md b/v3.0/_index.md deleted file mode 100755 index a118993c7f76..000000000000 --- a/v3.0/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/v3.0/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v3.0/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/v3.0/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v3.0/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 Docker Compose 部署](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v3.0/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/v3.0/architecture.md b/v3.0/architecture.md deleted file mode 100644 index 07be5ac5cc6a..000000000000 --- a/v3.0/architecture.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB 整体架构 -category: introduction ---- - -# TiDB 整体架构 - -要深入了解 TiDB 的水平扩展和高可用特点，首先需要了解 TiDB 的整体架构。TiDB 集群主要包括三个核心组件：TiDB Server，PD Server 和 TiKV Server。此外，还有用于解决用户复杂 OLAP 需求的 [TiSpark](https://github.com/pingcap/tispark/) 组件和简化云上部署管理的 [TiDB Operator](/v3.0/tidb-in-kubernetes/tidb-operator-overview.md) 组件。 - -![TiDB Architecture](/media/tidb-architecture.png) - -## TiDB Server - -TiDB Server 负责接收 SQL 请求，处理 SQL 相关的逻辑，并通过 PD 找到存储计算所需数据的 TiKV 地址，与 TiKV 交互获取数据，最终返回结果。TiDB Server 是无状态的，其本身并不存储数据，只负责计算，可以无限水平扩展，可以通过负载均衡组件（如LVS、HAProxy 或 F5）对外提供统一的接入地址。 - -## PD Server - -Placement Driver (简称 PD) 是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。 - -PD 通过 Raft 协议保证数据的安全性。Raft 的 leader server 负责处理所有操作，其余的 PD server 仅用于保证高可用。建议部署奇数个 PD 节点。 - -## TiKV Server - -TiKV Server 负责存储数据，从外部看 TiKV 是一个分布式的提供事务的 Key-Value 存储引擎。存储数据的基本单位是 Region，每个 Region 负责存储一个 Key Range（从 StartKey 到 EndKey 的左闭右开区间）的数据，每个 TiKV 节点会负责多个 Region。TiKV 使用 Raft 协议做复制，保持数据的一致性和容灾。副本以 Region 为单位进行管理，不同节点上的多个 Region 构成一个 Raft Group，互为副本。数据在多个 TiKV 之间的负载均衡由 PD 调度，这里也是以 Region 为单位进行调度。 - -## TiSpark - -TiSpark 作为 TiDB 中解决用户复杂 OLAP 需求的主要组件，将 Spark SQL 直接运行在 TiDB 存储层上，同时融合 TiKV 分布式集群的优势，并融入大数据社区生态。至此，TiDB 可以通过一套系统，同时支持 OLTP 与 OLAP，免除用户数据同步的烦恼。 - -## TiDB Operator - -TiDB Operator 提供在主流云基础设施（Kubernetes）上部署管理 TiDB 集群的能力。它结合云原生社区的容器编排最佳实践与 TiDB 的专业运维知识，集成一键部署、多集群混部、自动运维、故障自愈等能力，极大地降低了用户使用和管理 TiDB 的门槛与成本。 diff --git a/v3.0/benchmark/add-index-with-load.md b/v3.0/benchmark/add-index-with-load.md deleted file mode 100644 index 351461fa815c..000000000000 --- a/v3.0/benchmark/add-index-with-load.md +++ /dev/null @@ -1,348 +0,0 @@ ---- -title: 线上负载与 `ADD INDEX` 相互影响测试 -category: benchmark ---- - -# 线上负载与 `ADD INDEX` 相互影响测试 - -## 测试目的 - -测试 OLTP 场景下，`ADD INDEX` 与线上负载的相互影响。 - -## 测试版本、时间、地点 - -TiDB 版本：v3.0.1 - -时间：2019 年 7 月 - -地点：北京 - -## 测试环境 - -测试在 Kubernetes 集群上进行，部署了 3 个 TiDB 实例，3 个 TiKV 实例和 3 个 PD 实例。 - -### 版本信息 - -| 组件 | GitHash | -| :--- | :---------------------------------------- | -| TiDB | `9e4e8da3c58c65123db5f26409759fe1847529f8` | -| TiKV | `4151dc8878985df191b47851d67ca21365396133` | -| PD | `811ce0b9a1335d1b2a049fd97ef9e186f1c9efc1` | - -Sysbench 版本：1.0.17 - -### TiDB 参数配置 - -TiDB、TiKV 和 PD 均使用 [TiDB Operator](https://github.com/pingcap/tidb-operator) 默认配置。 - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-------------------------------------- | :----------| -| 172.31.8.8 | Sysbench | -| 172.31.7.69, 172.31.5.152, 172.31.11.133 | PD | -| 172.31.4.172, 172.31.1.155, 172.31.9.210 | TiKV | -| 172.31.7.80, 172.31.5.163, 172.31.11.123 | TiDB | - -### 使用 Sysbench 模拟线上负载 - -使用 Sysbench 向集群导入 **1 张表，200 万行数据**。 - -执行如下命令导入数据： - -{{< copyable "shell-regular" >}} - -```sh -sysbench oltp_common \ - --threads=16 \ - --rand-type=uniform \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - prepare --tables=1 --table-size=2000000 -``` - -执行如下命令测试数据： - -{{< copyable "shell-regular" >}} - -```sh -sysbench $testname \ - --threads=$threads \ - --time=300000 \ - --report-interval=15 \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - run --tables=1 --table-size=2000000 -``` - -## 测试方案 1：`ADD INDEX` 目标列被频繁 Update - -1. 开始 `oltp_read_write` 测试。 -2. 与步骤 1 同时，使用 `alter table sbtest1 add index c_idx(c)` 添加索引。 -3. 在步骤 2 结束，即索引添加完成时，停止步骤 1 的测试。 -4. 获取 `alter table ... add index` 的运行时间、sysbench 在该时间段内的平均 TPS 和 QPS 作为指标。 -5. 逐渐增大 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 两个参数的值，重复步骤 1-4。 - -### 测试结果 - -#### 无 `ADD INDEX` 时 `oltp_read_write` 的结果 - -| sysbench TPS | sysbench QPS | -| :------- | :-------- | -| 350.31 | 6806 | - -#### `tidb_ddl_reorg_batch_size = 32` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 402 | 338.4 | 6776 | -| 2 | 266 | 330.3 | 6001 | -| 4 | 174 | 288.5 | 5769 | -| 8 | 129 | 280.6 | 5612 | -| 16 | 90 | 263.5 | 5273 | -| 32 | 54 | 229.2 | 4583 | -| 48 | 57 | 230.1 | 4601 | - -![add-index-load-1-b32](/media/add-index-load-1-b32.png) - -#### `tidb_ddl_reorg_batch_size = 64` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 264 | 269.4 | 5388 | -| 2 | 163 | 266.2 | 5324 | -| 4 | 105 | 272.5 | 5430 | -| 8 | 78 | 262.5 | 5228 | -| 16 | 57 | 215.5 | 4308 | -| 32 | 42 | 185.2 | 3715 | -| 48 | 45 | 189.2 | 3794 | - -![add-index-load-1-b64](/media/add-index-load-1-b64.png) - -#### `tidb_ddl_reorg_batch_size = 128` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 171 | 289.1 | 5779 | -| 2 | 110 | 274.2 | 5485 | -| 4 | 79 | 250.6 | 5011 | -| 8 | 51 | 246.1 | 4922 | -| 16 | 39 | 171.1 | 3431 | -| 32 | 35 | 130.8 | 2629 | -| 48 | 35 | 120.5 | 2425 | - -![add-index-load-1-b128](/media/add-index-load-1-b128.png) - -#### `tidb_ddl_reorg_batch_size = 256` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 145 | 283.0 | 5659 | -| 2 | 96 | 282.2 | 5593 | -| 4 | 56 | 236.5 | 4735 | -| 8 | 45 | 194.2 | 3882 | -| 16 | 39 | 149.3 | 2893 | -| 32 | 36 | 113.5 | 2268 | -| 48 | 33 | 86.2 | 1715 | - -![add-index-load-1-b256](/media/add-index-load-1-b256.png) - -#### `tidb_ddl_reorg_batch_size = 512` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 135 | 257.8 | 5147 | -| 2 | 78 | 252.8 | 5053 | -| 4 | 49 | 222.7 | 4478 | -| 8 | 36 | 145.4 | 2904 | -| 16 | 33 | 109 | 2190 | -| 32 | 33 | 72.5 | 1503 | -| 48 | 33 | 54.2 | 1318 | - -![add-index-load-1-b512](/media/add-index-load-1-b512.png) - -#### `tidb_ddl_reorg_batch_size = 1024` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 111 | 244.3 | 4885 | -| 2 | 78 | 228.4 | 4573 | -| 4 | 54 | 168.8 | 3320 | -| 8 | 39 | 123.8 | 2475 | -| 16 | 36 | 59.6 | 1213 | -| 32 | 42 | 93.2 | 1835 | -| 48 | 51 | 115.7 | 2261 | - -![add-index-load-1-b1024](/media/add-index-load-1-b1024.png) - -#### `tidb_ddl_reorg_batch_size = 2048` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 918 | 243.3 | 4855 | -| 2 | 1160 | 209.9 | 4194 | -| 4 | 342 | 185.4 | 3707 | -| 8 | 1316 | 151.0 | 3027 | -| 16 | 795 | 30.5 | 679 | -| 32 | 1130 | 26.69 | 547 | -| 48 | 893 | 27.5 | 552 | - -![add-index-load-1-b2048](/media/add-index-load-1-b2048.png) - -#### `tidb_ddl_reorg_batch_size = 4096` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 3042 | 200.0 | 4001 | -| 2 | 3022 | 203.8 | 4076 | -| 4 | 858 | 195.5 | 3971 | -| 8 | 3015 | 177.1 | 3522 | -| 16 | 837 | 143.8 | 2875 | -| 32 | 942 | 114 | 2267 | -| 48 | 187 | 54.2 | 1416 | - -![add-index-load-1-b4096](/media/add-index-load-1-b4096.png) - -### 测试结论 - -若 `ADD INDEX` 的目标列正在进行较为频繁的写操作（本测试涉及列的 `UPDATE`、`INSERT` 和 `DELETE`），默认 `ADD INDEX` 配置对系统的线上负载有比较明显的影响，该影响主要来源于 `ADD INDEX` 与 Column Update 并发进行造成的写冲突，系统的表现反应在： - -- 随着两个参数的逐渐增大，`TiKV_prewrite_latch_wait_duration` 有明显的升高，造成写入变慢。 -- `tidb_ddl_reorg_worker_cnt` 与 `tidb_ddl_reorg_batch_size` 非常大时，`admin show ddl` 命令可以看到 DDL job 的多次重试（例如 `Write conflict, txnStartTS 410327455965380624 is stale [try again later], ErrCount:38, SnapshotVersion:410327228136030220`），此时 `ADD INDEX` 会持续非常久才能完成。 - -## 测试方案 2：`ADD INDEX` 目标列不涉及写入（仅查询） - -1. 开始 `oltp_read_only` 测试。 -2. 与步骤 1 同时，使用 `alter table sbtest1 add index c_idx(c)` 添加索引。 -3. 在步骤 2 结束，即索引添加完成时，停止步骤 1。 -4. 获取 `alter table ... add index` 的运行时间、sysbench 在该时间段内的平均 TPS 和 QPS 作为指标。 -5. 逐渐增大 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 两个参数，重复步骤 1-4。 - -### 测试结果 - -#### 无 `ADD INDEX` 时 `oltp_read_only` 结果 - -| sysbench TPS | sysbench QPS | -| :------- | :-------- | -| 550.9 | 8812.8 | - -#### `tidb_ddl_reorg_batch_size = 32` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 376 | 548.9 | 8780 | -| 2 | 212 | 541.5 | 8523 | -| 4 | 135 | 538.6 | 8549 | -| 8 | 114 | 536.7 | 8393 | -| 16 | 77 | 533.9 | 8292 | -| 32 | 46 | 533.4 | 8103 | -| 48 | 46 | 532.2 | 8074 | - -![add-index-load-2-b32](/media/add-index-load-2-b32.png) - -#### `tidb_ddl_reorg_batch_size = 1024` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 91 | 536.8 | 8316 | -| 2 | 52 | 533.9 | 8165 | -| 4 | 40 | 522.4 | 7947 | -| 8 | 36 | 510 | 7860 | -| 16 | 33 | 485.5 | 7704 | -| 32 | 31 | 467.5 | 7516 | -| 48 | 30 | 562.1 | 7442 | - -![add-index-load-2-b1024](/media/add-index-load-2-b1024.png) - -#### `tidb_ddl_reorg_batch_size = 4096` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 103 | 502.2 | 7823 | -| 2 | 63 | 486.5 | 7672 | -| 4 | 52 | 467.4 | 7516 | -| 8 | 39 | 452.5 | 7302 | -| 16 | 35 | 447.2 | 7206 | -| 32 | 30 | 441.9 | 7057 | -| 48 | 30 | 440.1 | 7004 | - -![add-index-load-2-b4096](/media/add-index-load-2-b4096.png) - -### 测试结论 - -`ADD INDEX` 的目标列仅有查询负载时，`ADD INDEX` 对负载的影响不明显。 - -## 测试方案 3：集群负载不涉及 `ADD INDEX` 目标列 - -1. 开始 `oltp_read_write` 测试。 -2. 与步骤 1 同时，使用 `alter table test add index pad_idx(pad)` 添加索引。 -3. 在步骤 2 结束，即索引添加完成时，停止步骤 1 的测试。 -4. 获取 `alter table ... add index` 的运行时间、sysbench 在该时间段内的平均 TPS 和 QPS 作为指标。 -5. 逐渐增大 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 两个参数，重复步骤 1-4。 - -### 测试结果 - -#### 无 `ADD INDEX` 时 `oltp_read_write` 的结果 - -| sysbench TPS | sysbench QPS | -| :------- | :-------- | -| 350.31 | 6806 | - -#### `tidb_ddl_reorg_batch_size = 32` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 372 | 350.4 | 6892 | -| 2 | 207 | 344.2 | 6700 | -| 4 | 140 | 343.1 | 6672 | -| 8 | 121 | 339.1 | 6579 | -| 16 | 76 | 340 | 6607 | -| 32 | 42 | 343.1 | 6695 | -| 48 | 42 | 333.4 | 6454 | - -![add-index-load-3-b32](/media/add-index-load-3-b32.png) - -#### `tidb_ddl_reorg_batch_size = 1024` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 94 | 352.4 | 6794 | -| 2 | 50 | 332 | 6493 | -| 4 | 45 | 330 | 6456 | -| 8 | 36 | 325.5 | 6324 | -| 16 | 32 | 312.5 | 6294 | -| 32 | 32 | 300.6 | 6017 | -| 48 | 31 | 279.5 | 5612 | - -![add-index-load-3-b1024](/media/add-index-load-3-b1024.png) - -#### `tidb_ddl_reorg_batch_size = 4096` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 116 | 325.5 | 6324 | -| 2 | 65 | 312.5 | 6290 | -| 4 | 50 | 300.6 | 6017 | -| 8 | 37 | 279.5 | 5612 | -| 16 | 34 | 250.4 | 5365 | -| 32 | 32 | 220.2 | 4924 | -| 48 | 33 | 214.8 | 4544 | - -![add-index-load-3-b4096](/media/add-index-load-3-b4096.png) - -### 测试结论 - -`ADD INDEX` 的目标列与负载无关时，`ADD INDEX` 对负载的影响不明显。 - -## 总结 - -- 当 `ADD INDEX` 的目标列被频繁更新（包含 `UPDATE`、`INSERT` 和 `DELETE`）时，默认配置会造成较为频繁的写冲突，使得在线负载较大；同时 `ADD INDEX` 也可能由于不断地重试，需要很长的时间才能完成。在本次测试中，将 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 的乘积调整为默认值的 1/32（例如 `tidb_ddl_reorg_worker_cnt` = 4，`tidb_ddl_reorg_batch_size` = 256）可以取得较好的效果。 -- 当 `ADD INDEX` 的目标列仅涉及查询负载，或者与线上负载不直接相关时，可以直接使用默认配置。 \ No newline at end of file diff --git a/v3.0/benchmark/dm-v1.0-ga.md b/v3.0/benchmark/dm-v1.0-ga.md deleted file mode 100644 index 3e2a589b2137..000000000000 --- a/v3.0/benchmark/dm-v1.0-ga.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: DM 1.0-GA 性能测试报告 -category: benchmark ---- - -# DM 1.0-GA 性能测试报告 - -本报告记录了对 1.0-GA 版本的 DM 进行性能测试的目的、环境、场景和结果。 - -## 测试目的 - -该性能测试用于评估使用 DM 进行全量数据导入和增量数据同步的性能上限，并根据测试结果提供 DM 同步任务的参考配置。 - -## 测试环境 - -### 测试机器信息 - -系统信息： - -| 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | -| :---------: | :---------------------------: | :-----------------------: | :--------------: | -| 172.16.4.39 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.40 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.41 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.42 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.43 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.44 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | - -硬件信息： - -| 类别 | 指标 | -| :----------: | :-------------------------------------------------: | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| 内存 | 192GB, 12 条 16GB DIMM DDR4 2133 MHz | -| 磁盘 | Intel DC P4510 4TB NVMe PCIe 3.0 | -| 网卡 | 万兆网卡 | - -其他： - -* 服务器间网络延迟：rtt min/avg/max/mdev = 0.074/0.088/0.121/0.019 ms - -### 集群拓扑 - -| 机器 IP | 部署的服务 | -| :---------: | :--------------------------------: | -| 172.16.4.39 | PD1, DM-worker1, DM-master | -| 172.16.4.40 | PD2, MySQL1 | -| 172.16.4.41 | PD3, TiDB | -| 172.16.4.42 | TiKV1 | -| 172.16.4.43 | TiKV2 | -| 172.16.4.44 | TiKV3 | - -### 各服务版本信息 - -- MySQL 版本: 5.7.27-log -- TiDB 版本: v4.0.0-alpha-198-gbde7f440e -- DM 版本: v1.0.1 -- Sysbench 版本: 1.0.17 - -## 测试场景 - -### 同步数据流 - -MySQL1 (172.16.4.40) -> DM-worker1 (172.16.4.39) -> TiDB (172.16.4.41) - -### 公共配置信息 - -#### 同步数据表结构 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `sbtest` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `k` int(11) NOT NULL DEFAULT '0', - `c` char(120) CHARSET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '', - `pad` char(60) CHARSET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -``` - -#### 数据库配置 - -使用 TiDB Ansible 部署 TiDB 测试集群，所有配置使用 TiDB Ansible 提供的默认配置。 - -### 全量导入性能测试用例 - -#### 测试过程 - -- 部署测试环境 -- 使用 `sysbench` 在上游创建测试表，并生成全量导入的测试数据 -- 在 `full` 模式下启动 DM 同步任务 - -`sysbench` 生成数据的命令如下所示： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --test=oltp_insert --tables=4 --mysql-host=172.16.4.40 --mysql-port=3306 --mysql-user=root --mysql-db=dm_benchmark --db-driver=mysql --table-size=50000000 prepare -``` - -#### 全量导入性能测试结果 - -在 `mydumper` 中使用 `--rows` 选项可以开启单表多线程并发导出（当前 `mydumper` 在 MySQL 的单表并发会优先选出一列做拆分基准，选择优先级为主键>唯一索引>普通索引，选出目标列后需保证该列为 INT 类型；针对 `TiDB` 的并发导出则会优先尝试 `_tidb_rowid` 列），以下的第一项测试用于验证开启单表并发导出可以提高数据导出性能。 - -| 测试项 | 导出线程数 | mydumper extra-args 参数 | 导出速度 (MB/s) | -| :----------------: | :---------: | :---------------------------------: | :---------------: | -| 开启单表并发导出 | 32 | "--rows 320000 --regex '^sbtest.*'" | 191.03 | -| 不开启单表并发导出 | 4 | "--regex '^sbtest.*'" | 72.22 | - -| 测试项 | 事务执行延迟 (s) | 每条插入语句包含的行数 | 导入数据量 (GB) | 导入时间 (s) | 导入速度 (MB/s) | -| :-------: | :--------------: | :--------------------: | :-------------: | :----------: | :-------------: | -| load data | 1.737 | 4878 | 38.14 | 2346.9 | 16.64 | - -#### 在 load 处理单元使用不同 pool size 的性能测试对比 - -该测试中全量导入的数据量为 3.78 GB，使用以下 `sysbench` 命令生成： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --test=oltp_insert --tables=4 --mysql-host=172.16.4.40 --mysql-port=3306 --mysql-user=root --mysql-db=dm_benchmark --db-driver=mysql --table-size=5000000 prepare -``` - -| load 处理单元 pool size | 事务执行时间 (s) | 导入时间 (s) | 导入速度 (MB/s) | TiDB 99 duration (s) | -| :---------------------: | :--------------: | :----------: | :-------------: | :------------------: | -| 2 | 0.250 | 425.9 | 9.1 | 0.23 | -| 4 | 0.523 | 360.1 | 10.7 | 0.41 | -| 8 | 0.986 | 267.0 | 14.5 | 0.93 | -| 16 | 2.022 | 265.9 | 14.5 | 2.68 | -| 32 | 3.778 | 262.3 | 14.7 | 6.39 | -| 64 | 7.452 | 281.9 | 13.7 | 8.00 | - -#### 导入数据时每条插入语句包含行数不同的情况下的性能测试对比 - -该测试中全量导入的数据量为 3.78 GB，load 处理单元 `pool-size` 大小为 32。插入语句包含行数通过 mydumper 的 `--statement-size` 来控制。 - -| 每条语句中包含的行数 | mydumper extra-args 参数 | 事务执行时间 (s) | 导入时间 (s) | 导入速度 (MB/s) | TiDB 99 duration (s) | -| :------------------------: | :-----------------------: | :---------------: | :----------: | :-------------: | :------------------: | -| 7426 | -s 1500000 -r 320000 | 6.982 | 258.3 | 15.0 | 10.34 | -| 4903 | -s 1000000 -r 320000 | 3.778 | 262.3 | 14.7 | 6.39 | -| 2470 | -s 500000 -r 320000 | 1.962 | 271.36 | 14.3 | 2.00 | -| 1236 | -s 250000 -r 320000 | 1.911 | 283.3 | 13.7 | 1.50 | -| 618 | -s 125000 -r 320000 | 0.683 | 299.9 | 12.9 | 0.73 | -| 310 | -s 62500 -r 320000 | 0.413 | 322.6 | 12.0 | 0.49 | - -### 增量同步性能测试用例 - -#### 测试过程 - -- 部署测试环境 -- 使用 `sysbench` 在上游创建测试表，并生成全量导入的测试数据 -- 在 `all` 模式下启动 DM 同步任务，等待同步任务进入 `sync` 同步阶段 -- 使用 `sysbench` 在上游持续生成增量数据，通过 `query-status` 命令观测 DM 的同步状态，通过 Grafana 观测 DM 和 TiDB 的监控指标。 - -#### 增量同步性能测试结果 - -上游 `sysbench` 生成增量数据命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --test=oltp_insert --tables=4 --num-threads=32 --mysql-host=172.17.4.40 --mysql-port=3306 --mysql-user=root --mysql-db=dm_benchmark --db-driver=mysql --report-interval=10 --time=1800 run -``` - -该性能测试中同步任务 `sync` 处理单元 `worker-count` 设置为 32，`batch` 大小设置为 100。 - -| 组件 | qps | tps | 95% 延迟 | -| :------------------------: | :----------------------------------------------------------: | :-------------------------------------------------------------: | :--------------------------: | -| MySQL | 42.79k | 42.79k | 1.18ms | -| DM relay log unit | - | 11.3MB/s | 45us (binlog 读延迟) | -| DM binlog replication unit | 22.97k (binlog event 接收qps，不包括忽略的 event) | - | 20ms (事务执行时间) | -| TiDB | 31.30k (Begin/Commit 3.93k Insert 22.76k) | 4.16k | 95%: 6.4ms 99%: 9ms | - -#### 在 sync 处理单元使用不同并发度的性能测试对比 - -| sync 处理单元 worker-count 数 | DM 内部 job tps | DM 事务执行时间 (ms) | TiDB qps | TiDB 99 duration (ms) | -| :---------------------------: | :-------------: | :-----------------------: | :------: | :-------------------: | -| 4 | 7074 | 63 | 7.1k | 3 | -| 8 | 14684 | 64 | 14.9k | 4 | -| 16 | 23486 | 56 | 24.9k | 6 | -| 32 | 23345 | 28 | 29.2k | 10 | -| 64 | 23302 | 30 | 31.2k | 16 | -| 1024 | 22225 | 70 | 56.9k | 70 | - -#### 不同数据分布的增量同步性能测试对比 - -| sysbench 语句类型| DM relay log 持久化速率 (MB/s) | DM 内部 job tps | DM 事务执行时间 (ms) | TiDB qps | TiDB 99 duration (ms) | -| :--------------: | :----------------------------: | :-------------: | :------------------: | :------: | :-------------------: | -| insert_only | 11.3 | 23345 | 28 | 29.2k | 10 | -| write_only | 18.7 | 33470 | 129 | 34.6k | 11 | - -## 推荐同步任务参数配置 - -### dump 处理单元 - -推荐每一条插入语句的大小在 200KB ~ 1MB 之间，相应每条语句包含的行数大约在 1000-5000（具体包含的语句行数与实际场景中每行数据大小有关）。 - -### load 处理单元 - -推荐 `pool-size` 设置为 16。 - -### sync 处理单元 - -推荐将 `batch` 设置为 100，`worker-count` 设置为 16 ~ 32。 diff --git a/v3.0/benchmark/how-to-run-sysbench.md b/v3.0/benchmark/how-to-run-sysbench.md deleted file mode 100644 index 14f83278533b..000000000000 --- a/v3.0/benchmark/how-to-run-sysbench.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: 如何用 Sysbench 测试 TiDB -category: benchmark -aliases: ['/docs-cn/benchmark/how-to-run-sysbench'] ---- - -# 如何用 Sysbench 测试 TiDB - -本次测试使用的是 TiDB 3.0 Beta 和 Sysbench 1.0.14。建议使用 Sysbench 1.0 或之后的更新版本，可在 [Sysbench Release 1.0.14 页面](https://github.com/akopytov/sysbench/releases/tag/1.0.14)下载。 - -## 测试环境 - -- [硬件要求](/v3.0/how-to/deploy/hardware-recommendations.md) - -- 参考 [TiDB 部署文档](/v3.0/how-to/deploy/orchestrated/ansible.md)部署 TiDB 集群。在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD，和 1 个 TiKV 实例。关于磁盘，以 32 张表、每张表 10M 行数据为例，建议 TiKV 的数据目录所在的磁盘空间大于 512 GB。 - 对于单个 TiDB 的并发连接数，建议控制在 500 以内，如需增加整个系统的并发压力，可以增加 TiDB 实例，具体增加的 TiDB 个数视测试压力而定。 - -IDC 机器： - -| 类别 | 名称 | -|:---- |:---- | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel® Xeon® CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Intel Optane SSD P4800X 375G * 1 | -| NIC | 10Gb Ethernet | - -## 测试方案 - -### TiDB 版本信息 - -| 组件 | GitHash | -|:---- |:---- | -| TiDB | 7a240818d19ae96e4165af9ea35df92466f59ce6 | -| TiKV | e26ceadcdfe94fb6ff83b5abb614ea3115394bcd | -| PD | 5e81548c3c1a1adab056d977e7767307a39ecb70 | - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|:---- |:---- | -| 172.16.30.31 | 3*sysbench | -| 172.16.30.33 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.34 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.35 | 1\*tidb 1\*pd 1\*tikv | - -### TiDB 配置 - -升高日志级别，可以减少打印日志数量，对 TiDB 的性能有积极影响。开启 TiDB 配置中的 `prepared plan cache`，以减少优化执行计划的开销。具体在 TiDB 配置文件中加入： - -```toml -[log] -level = "error" -[prepared-plan-cache] -enabled = true -``` - -### TiKV 配置 - -升高 TiKV 的日志级别同样有利于提高性能表现。 - -由于 TiKV 是以集群形式部署的，在 Raft 算法的作用下，能保证大多数节点已经写入数据。因此，除了对数据安全极端敏感的场景之外，raftstore 中的 `sync-log` 选项可以关闭。 - -TiKV 集群存在两个 Column Family（Default CF 和 Write CF），主要用于存储不同类型的数据。对于 Sysbench 测试，导入数据的 Column Family 在 TiDB 集群中的比例是固定的。这个比例是： - -Default CF : Write CF = 4 : 1 - -在 TiKV 中需要根据机器内存大小配置 RocksDB 的 block cache，以充分利用内存。以 40 GB 内存的虚拟机部署一个 TiKV 为例，其 block cache 建议配置如下: - -```toml -log-level = "error" -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "24GB" -[rocksdb.writecf] -block-cache-size = "6GB" -``` - -对于 3.0 及以后的版本，还可以使用共享 block cache 的方式进行设置： - -```toml -log-level = "error" -[raftstore] -sync-log = false -[storage.block-cache] -capacity = "30GB" -``` - -更详细的 TiKV 参数调优请参考 [TiKV 性能参数调优](/v3.0/reference/performance/tune-tikv.md)。 - -## 测试过程 - -> **注意：** -> -> 此次测试并没有使用如 HAproxy 等负载均衡工具。在 TiDB 单一节点上进行 Sysbench 测试，并把结果相加。负载均衡工具和不同版本参数也会影响性能表现。 - -### Sysbench 配置 - -以下为 Sysbench 配置文件样例： - -```txt -mysql-host={TIDB_HOST} -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads={8, 16, 32, 64, 128, 256} -report-interval=10 -db-driver=mysql -``` - -可根据实际需求调整其参数，其中 `TIDB_HOST` 为 TiDB server 的 IP 地址（配置文件中不能写多个地址），`threads` 为测试中的并发连接数，可在 “8, 16, 32, 64, 128, 256” 中调整，导入数据时，建议设置 threads = 8 或者 16。调整后，将该文件保存为名为 **config** 的文件。 - -**配置文件**参考示例如下： - -```txt -mysql-host=172.16.30.33 -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads=16 -report-interval=10 -db-driver=mysql -``` - -### 数据导入 - -在数据导入前，需要对 TiDB 进行简单设置。在 MySQL 客户端中执行如下命令： - -{{< copyable "sql" >}} - -```sql -set global tidb_disable_txn_auto_retry = off; -``` - -然后退出客户端。TiDB 使用乐观事务模型，当发现并发冲突时，会回滚事务。将 `tidb_disable_txn_auto_retry` 设置为 `off` 会开启事务冲突后的自动重试机制，可以尽可能避免事务冲突报错导致 Sysbench 程序退出的问题。 - -重新启动 MySQL 客户端执行以下 SQL 语句，创建数据库 `sbtest`： - -{{< copyable "sql" >}} - -```sql -create database sbtest; -``` - -调整 Sysbench 脚本创建索引的顺序。Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。该方式对于 TiDB 需要花费更多的导入时间。用户可以通过调整顺序来加速数据的导入。 - -假设用户使用的 [Sysbench](https://github.com/akopytov/sysbench/tree/1.0.14) 版本。我们可以通过以下两种方式来修改。 - -1. 直接下载为 TiDB 修改好的 [oltp_common.lua](https://raw.githubusercontent.com/pingcap/tidb-bench/master/sysbench/sysbench-patch/oltp_common.lua) 文件，覆盖 `/usr/share/sysbench/oltp_common.lua` 文件。 -2. 将 `/usr/share/sysbench/oltp_common.lua` 的第 [235](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L235) 行到第 [240](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L240) 行移动到第 198 行以后。 - -> **注意：** -> -> 此操作为可选操作，仅节约了数据导入时间。 - -命令行输入以下命令，开始导入数据，config 文件为上一步中配置的文件： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 prepare -``` - -### 数据预热与统计信息收集 - -数据预热可将磁盘中的数据载入内存的 block cache 中，预热后的数据对系统整体的性能有较大的改善，建议在每次重启集群后进行一次数据预热。 - -Sysbench 1.0.14 没有提供数据预热的功能，因此需要手动进行数据预热。如果使用更新的 Sysbench 版本，可以使用自带的预热功能。 - -以 Sysbench 中某张表 sbtest7 为例，执行如下 SQL 语句 进行数据预热： - -{{< copyable "sql" >}} - -```sql -SELECT COUNT(pad) FROM sbtest7 USE INDEX (k_7); -``` - -统计信息收集有助于优化器选择更为准确的执行计划，可以通过 `analyze` 命令来收集表 sbtest 的统计信息，每个表都需要统计。 - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE sbtest7; -``` - -### Point select 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 run -``` - -### Update index 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_update_index --tables=32 --table-size=10000000 run -``` - -### Read-only 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_read_only --tables=32 --table-size=10000000 run -``` - -## 测试结果 - -测试了数据 32 表，每表有 10M 数据。 - -对每个 tidb-server 进行了 Sysbench 测试，将结果相加，得出最终结果： - -### oltp_point_select - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| point_select | 3\*8 | 67502.55 | 67502.55 | 0.36 | 0.42 | 141.92 | -| point_select | 3\*16 | 120141.84 | 120141.84 | 0.40 | 0.52 | 20.99 | -| point_select | 3\*32 | 170142.92 | 170142.92 | 0.58 | 0.99 | 28.08 | -| point_select | 3\*64 | 195218.54 | 195218.54 | 0.98 | 2.14 | 21.82 | -| point_select | 3\*128 | 208189.53 | 208189.53 | 1.84 | 4.33 | 31.02 | - -![oltp_point_select](/media/oltp_point_select.png) - -### oltp_update_index - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_update_index | 3\*8 | 9668.98 | 9668.98 | 2.51 | 3.19 | 103.88| -| oltp_update_index | 3\*16 | 12834.99 | 12834.99 | 3.79 | 5.47 | 176.90 | -| oltp_update_index | 3\*32 | 15955.77 | 15955.77 | 6.07 | 9.39 | 4787.14 | -| oltp_update_index | 3\*64 | 18697.17 | 18697.17 | 10.34 | 17.63 | 4539.04 | -| oltp_update_index | 3\*128 | 20446.81 | 20446.81 | 18.98 | 40.37 | 5394.75 | -| oltp_update_index | 3\*256 | 23563.03 | 23563.03 | 32.86 | 78.60 | 5530.69 | - -![oltp_update_index](/media/oltp_update_index.png) - -### oltp_read_only - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_read_only | 3\*8 | 2411.00 | 38575.96 | 9.92 | 20.00 | 92.23 | -| oltp_read_only | 3\*16 | 3873.53 | 61976.50 | 12.25 | 16.12 | 56.94 | -| oltp_read_only | 3\*32 | 5066.88 | 81070.16 | 19.42 | 26.20 | 123.41 | -| oltp_read_only | 3\*64 | 5466.36 | 87461.81 | 34.65 | 63.20 | 231.19 | -| oltp_read_only | 3\*128 | 6684.16 | 106946.59 | 57.29 | 97.55 | 180.85 | - -![oltp_read_only](/media/oltp_read_only.png) - -## 常见问题 - -### 在高并发压力下，TiDB、TiKV 的配置都合理，为什么整体性能还是偏低？ - -这种情况可能与使用了 proxy 有关。可以尝试直接对单个 TiDB 加压，将求和后的结果与使用 proxy 的情况进行对比。 - -以 HAproxy 为例。`nbproc` 参数可以增加其最大启动的进程数，较新版本的 HAproxy 还支持 `nbthread` 和 `cpu-map` 等。这些都可以减少对其性能的不利影响。 - -### 在高并发压力下，为什么 TiKV 的 CPU 利用率依然很低？ - -TiKV 虽然整体 CPU 偏低，但部分模块的 CPU 可能已经达到了很高的利用率。 - -TiKV 的其他模块，如 storage readpool、coprocessor 和 gRPC 的最大并发度限制是可以通过 TiKV 的配置文件进行调整的。 - -通过 Grafana 的 TiKV Thread CPU 监控面板可以观察到其实际使用率。如出现多线程模块瓶颈，可以通过增加该模块并发度进行调整。 - -### 在高并发压力下，TiKV 也未达到 CPU 使用瓶颈，为什么 TiDB 的 CPU 利用率依然很低？ - -在某些高端设备上，使用的是 NUMA 架构的 CPU，跨 CPU 访问远端内存将极大降低性能。TiDB 默认将使用服务器所有 CPU，goroutine 的调度不可避免地会出现跨 CPU 内存访问。 - -因此，建议在 NUMA 架构服务器上，部署 *n* 个 TiDB（*n* = NUMA CPU 的个数），同时将 TiDB 的 `max-procs` 变量的值设置为与 NUMA CPU 的核数相同。 diff --git a/v3.0/benchmark/how-to-run-tpcc.md b/v3.0/benchmark/how-to-run-tpcc.md deleted file mode 100644 index cb60663d8e73..000000000000 --- a/v3.0/benchmark/how-to-run-tpcc.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: 如何对 TiDB 进行 TPC-C 测试 -category: benchmark ---- - -# 如何对 TiDB 进行 TPC-C 测试 - -本文介绍如何对 TiDB 进行 [TPC-C](http://www.tpc.org/tpcc/) 测试。 - -## 准备测试程序 - -TPC-C 是一个对 OLTP（联机交易处理）系统进行测试的规范，使用一个商品销售模型对 OLTP 系统进行测试，其中包含五类事务： - -* NewOrder – 新订单的生成 -* Payment – 订单付款 -* OrderStatus – 最近订单查询 -* Delivery – 配送 -* StockLevel – 库存缺货状态分析 - -在测试开始前，TPC-C Benchmark 规定了数据库的初始状态，也就是数据库中数据生成的规则，其中 ITEM 表中固定包含 10 万种商品，仓库的数量可进行调整，假设 WAREHOUSE 表中有 W 条记录，那么： - -* STOCK 表中应有 W \* 10 万条记录（每个仓库对应 10 万种商品的库存数据） -* DISTRICT 表中应有 W \* 10 条记录（每个仓库为 10 个地区提供服务） -* CUSTOMER 表中应有 W \* 10 \* 3000 条记录（每个地区有 3000 个客户） -* HISTORY 表中应有 W \* 10 \* 3000 条记录（每个客户一条交易历史） -* ORDER 表中应有 W \* 10 \* 3000 条记录（每个地区 3000 个订单），并且最后生成的 900 个订单被添加到 NEW-ORDER 表中，每个订单随机生成 5 ~ 15 条 ORDER-LINE 记录。 - -我们将以 1000 WAREHOUSE 为例进行测试。 - -TPC-C 使用 tpmC 值（Transactions per Minute）来衡量系统最大有效吞吐量 (MQTh, Max Qualified Throughput)，其中 Transactions 以 NewOrder Transaction 为准，即最终衡量单位为每分钟处理的新订单数。 - -本文使用开源的 BenchmarkSQL 5.0 作为 TPC-C 测试实现并添加了对 MySQL 协议的支持，可以通过以下命令下载测试程序: - -{{< copyable "shell-regular" >}} - -```shell -git clone -b 5.0-mysql-support-opt-2.1 https://github.com/pingcap/benchmarksql.git -``` - -安装 java 和 ant，以 CentOS 为例，可以执行以下命令进行安装 - -{{< copyable "shell-regular" >}} - -```shell -sudo yum install -y java ant -``` - -进入 benchmarksql 目录并执行 ant 构建 - -{{< copyable "shell-regular" >}} - -```shell -cd benchmarksql -ant -``` - -## 部署 TiDB 集群 - -对于 1000 WAREHOUSE 我们将在 3 台服务器上部署集群。 - -在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD 和 1 个 TiKV 实例。 - -比如这里采用的机器硬件配置是： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD | - -因为该型号 CPU 是 NUMA 架构，建议先用 `taskset` 进行绑核，首先用 `lscpu` 查看 NUMA node，比如： - -```text -NUMA node0 CPU(s): 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 -NUMA node1 CPU(s): 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 -``` - -之后可以通过下面的命令来启动 TiDB： - -{{< copyable "shell-regular" >}} - -```shell -nohup taskset -c 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 bin/tidb-server && \ -nohup taskset -c 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 bin/tidb-server -``` - -最后，可以选择部署一个 HAproxy 来进行多个 TiDB node 的负载均衡，推荐配置 nbproc 为 CPU 核数。 - -## 配置调整 - -### TiDB 配置 - -```toml -[log] -level = "error" - -[performance] -# 根据 NUMA 配置，设置单个 TiDB 最大使用的 CPU 核数 -max-procs = 20 - -[prepared_plan_cache] -# 开启 TiDB 配置中的 prepared plan cache，以减少优化执行计划的开销 -enabled = true -``` - -### TiKV 配置 - -开始可以使用基本的配置，压测运行后可以通过观察 Grafana 并参考 [TiKV 调优说明](/v3.0/reference/performance/tune-tikv.md)进行调整。 - -### BenchmarkSQL 配置 - -修改 `benchmarksql/run/props.mysql`： - -```text -conn=jdbc:mysql://{HAPROXY-HOST}:{HAPROXY-PORT}/tpcc?useSSL=false&useServerPrepStmts=true&useConfigs=maxPerformance -warehouses=1000 # 使用 1000 个 warehouse -terminals=500 # 使用 500 个终端 -loadWorkers=32 # 导入数据的并发数 -``` - -## 导入数据 - -**导入数据通常是整个 TPC-C 测试中最耗时，也是最容易出问题的阶段。** - -首先用 MySQL 客户端连接到 TiDB-Server 并执行： - -{{< copyable "sql" >}} - -```sql -create database tpcc -``` - -之后在 shell 中运行 BenchmarkSQL 建表脚本： - -{{< copyable "shell-regular" >}} - -```shell -cd run && \ -./runSQL.sh props.mysql sql.mysql/tableCreates.sql && \ -./runSQL.sh props.mysql sql.mysql/indexCreates.sql -``` - -### 直接使用 BenchmarkSQL 导入 - -运行导入数据脚本： - -{{< copyable "shell-regular" >}} - -```shell -./runLoader.sh props.mysql -``` - -根据机器配置这个过程可能会持续几个小时。 - -### 通过 TiDB Lightning 导入 - -由于导入数据量随着 warehouse 的增加而增加，当需要导入 1000 warehouse 以上数据时，可以先用 BenchmarkSQL 生成 csv 文件，再将文件通过 TiDB Lightning（以下简称 Lightning）导入的方式来快速导入。生成的 csv 文件也可以多次复用，节省每次生成所需要的时间。 - -#### 修改 BenchmarkSQL 的配置文件 - -1 warehouse 的 csv 文件需要 77 MB 磁盘空间，在生成之前要根据需要分配足够的磁盘空间来保存 csv 文件。可以在 `benchmarksql/run/props.mysql` 文件中增加一行： - -```text -fileLocation=/home/user/csv/ # 存储 csv 文件的目录绝对路径，需保证有足够的空间 -``` - -因为最终要使用 Lightning 导入数据，所以 csv 文件名最好符合 Lightning 要求，即 `{database}.{table}.csv` 的命名法。这里可以将以上配置改为： - -```text -fileLocation=/home/user/csv/tpcc. # 存储 csv 文件的目录绝对路径 + 文件名前缀（database） -``` - -这样生成的 csv 文件名将会是类似 `tpcc.bmsql_warehouse.csv` 的样式，符合 Lightning 的要求。 - -#### 生成 csv 文件 - -{{< copyable "shell-regular" >}} - -```shell -./runLoader.sh props.mysql -``` - -#### 通过 Lightning 导入 - -通过 Lightning 导入数据请参考 [Lightning 部署执行](/v3.0/reference/tools/tidb-lightning/deployment.md)章节。这里我们介绍下通过 tidb-ansible 部署 Lightning 导入数据的方法。 - -##### 修改 inventory.ini - -这里最好手动指定清楚部署的 IP、端口、目录，避免各种冲突问题带来的异常，其中 import_dir 的磁盘空间参考 [Lightning 部署执行](/v3.0/reference/tools/tidb-lightning/deployment.md)，data_source_dir 就是存储上一节 csv 数据的目录。 - -```ini -[importer_server] -IS1 ansible_host=172.16.5.34 deploy_dir=/data2/is1 tikv_importer_port=13323 import_dir=/data2/import - -[lightning_server] -LS1 ansible_host=172.16.5.34 deploy_dir=/data2/ls1 tidb_lightning_pprof_port=23323 data_source_dir=/home/user/csv -``` - -##### 修改 conf/tidb-lightning.yml - -```yaml -mydumper: - no-schema: true - csv: - separator: ',' - delimiter: '' - header: false - not-null: false - 'null': 'NULL' - backslash-escape: true - trim-last-separator: false -``` - -##### 部署 Lightning 和 Importer - -{{< copyable "shell-regular" >}} - -```shell -ansible-playbook deploy.yml --tags=lightning -``` - -##### 启动 - -* 登录到部署 Lightning 和 Importer 的服务器 -* 进入部署目录 -* 在 Importer 目录下执行 `scripts/start_importer.sh`，启动 Importer -* 在 Lightning 目录下执行 `scripts/start_lightning.sh`，开始导入数据 - -由于是用 ansible 进行部署的，可以在监控页面看到 Lightning 的导入进度，或者通过日志查看导入是否结束。 - -### 导入完成后 - -数据导入完成之后，可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句都返回结果为空，即为数据导入正确。 - -## 运行测试 - -执行 BenchmarkSQL 测试脚本： - -{{< copyable "shell-regular" >}} - -```shell -nohup ./runBenchmark.sh props.mysql &> test.log & -``` - -运行结束后通过 `test.log` 查看结果： - -```text -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmC (NewOrders) = 77373.25 -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmTOTAL = 171959.88 -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Session Start = 2019-03-21 07:07:52 -07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Session End = 2019-03-21 07:09:53 -07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Transaction Count = 345240 -``` - -tpmC 部分即为测试结果。 - -测试完成之后，也可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句的返回结果都为空，即为数据测试过程正确。 diff --git a/v3.0/benchmark/sysbench-in-k8s.md b/v3.0/benchmark/sysbench-in-k8s.md deleted file mode 100644 index 84aabca85fa9..000000000000 --- a/v3.0/benchmark/sysbench-in-k8s.md +++ /dev/null @@ -1,449 +0,0 @@ ---- -title: TiDB in Kubernetes Sysbench 性能测试 -category: benchmark ---- - -# TiDB in Kubernetes Sysbench 性能测试 - -随着 [TiDB Operator GA 发布](https://pingcap.com/blog-cn/tidb-operator-1.0-ga/)，越来越多用户开始使用 TiDB Operator 在 Kubernetes 中部署管理 TiDB 集群。在本次测试中，我们选择 GKE 平台做了一次深入、全方位的测试，方便大家了解 TiDB 在 Kubernetes 中性能影响因素。 - -## 目的 - -- 测试典型公有云平台上 TiDB 性能数据 -- 测试公有云平台磁盘、网络、CPU 以及不同 Pod 网络下对 TiDB 性能的影响 - -## 环境 - -### 版本与配置 - -本次测试统一使用 TiDB v3.0.1 版本进行测试。 - -TiDB Operator 使用 v1.0.0 版本。 - -PD、TiDB 和 TiKV 实例数均为 3 个。各组件分别作了如下配置，未配置部分使用默认值。 - -PD: - -```toml -[log] -level = "info" -[replication] -location-labels = ["region", "zone", "rack", "host"] -``` - -TiDB: - -```toml -[log] -level = "error" -[prepared-plan-cache] -enabled = true -[tikv-client] -max-batch-wait-time = 2000000 -``` - -TiKV: - -```toml -log-level = "error" -[server] -status-addr = "0.0.0.0:20180" -grpc-concurrency = 6 -[readpool.storage] -normal-concurrency = 10 -[rocksdb.defaultcf] -block-cache-size = "14GB" -[rocksdb.writecf] -block-cache-size = "8GB" -[rocksdb.lockcf] -block-cache-size = "1GB" -[raftstore] -apply-pool-size = 3 -store-pool-size = 3 -``` - -### TiDB 数据库参数配置 - -``` -set global tidb_hashagg_final_concurrency=1; -set global tidb_hashagg_partial_concurrency=1; -set global tidb_disable_txn_auto_retry=0; -``` - -### 硬件配置 - -#### 机器型号 - -在单可用区测试中，我们选择了如下型号机器： - -| 组件 | 实例类型 | 数量 | -| :--- | :--------- | :---- | -| PD | n1-standard-4 | 3 | -| TiKV | c2-standard-16 | 3 | -| TiDB | c2-standard-16 | 3 | -| Sysbench | c2-standard-30 | 1 | - -分别在多可用区和单可用区中对 TiDB 进行性能测试，并将结果相对比。在测试时 (2019.08)，一个 GCP 区域 (Region) 下不存在三个能同时提供 c2 机器的可用区，所以我们选择了如下机器型号进行测试： - -| 组件 | 实例类型 | 数量 | -| :--- | :--------- | :---- | -| PD | n1-standard-4 | 3 | -| TiKV | n1-standard-16 | 3 | -| TiDB | n1-standard-16 | 3 | -| Sysbench | n1-standard-16 | 3 | - -在高并发读测试中，压测端 sysbench 对 CPU 需求较高，需选择多核较高配置型号，避免压测端成为瓶颈。 - -> **注意：** -> -> GCP 不同的区域可用机型不同。同时测试中发现磁盘性能表现也存在差异，我们统一在 us-central1 中申请机器测试。 - -#### 磁盘 - -GKE 当前的 NVMe 磁盘还在 Alpha 阶段，使用需特殊申请，不具备普遍意义。测试中，本地 SSD 盘统一使用 iSCSI 接口类型。挂载参数参考[官方建议](https://cloud.google.com/compute/docs/disks/performance#optimize_local_ssd)增加了 `discard,nobarrier` 选项。完整挂载例子如下： - -``` -sudo mount -o defaults,nodelalloc,noatime,discard,nobarrier /dev/[LOCAL_SSD_ID] /mnt/disks/[MNT_DIR] -``` - -#### 网络 - -GKE 网络模式使用具备更好扩展性以及功能强大的 [VPC-Native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips) 模式。在性能对比中，我们分别对 TiDB 使用 Kubernetes Pod 和 Host 网络分别做了测试。 - -#### CPU - -在单可用集群测试中，我们为 TiDB/TiKV 选择 c2-standard-16 机型测试。在单可用与多可用集群的对比测试中，因为 GCP 区域 (Region) 下不存在三个能同时申请 c2-standard-16 机型的可用区，所以我们选择了 n1-standard-16 机型测试。 - -### 操作系统及参数 - -GKE 支持两种操作系统：COS (Container Optimized OS) 和 Ubuntu 。Point Select 测试在两种操作系统中进行，并将结果进行了对比。其余测试中，统一使用 Ubuntu 系统进行测试。 - -内核统一做了如下配置: - -```shell -sysctl net.core.somaxconn=32768 -sysctl vm.swappiness=0 -sysctl net.ipv4.tcp_syncookies=0 -``` - -同时对最大文件数配置为 1000000。 - -### Sysbench 版本与运行参数 - -本次测试中 sysbench 版本为 1.0.17。并在测试前统一使用 `oltp_common` 的 `prewarm` 命令进行数据预热。 - -#### 初始化 - -```shell -sysbench \ - --mysql-host= \ - --mysql-port=4000 \ - --mysql-user=root \ - --mysql-db=sbtest \ - --time=600 \ - --threads=16 \ - --report-interval=10 \ - --db-driver=mysql \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --tables=16 \ - --table-size=10000000 \ - oltp_common \ - prepare -``` - -`` 为 TiDB 的数据库地址，根据不同测试需求选择不同的地址，比如 Pod IP、Service 域名、Host IP 以及 Load Balancer IP（下同）。 - -#### 预热 - -```shell -sysbench \ - --mysql-host= \ - --mysql-port=4000 \ - --mysql-user=root \ - --mysql-db=sbtest \ - --time=600 \ - --threads=16 \ - --report-interval=10 \ - --db-driver=mysql \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --tables=16 \ - --table-size=10000000 \ - oltp_common \ - prewarm -``` - -#### 压测 - -```shell -sysbench \ - --mysql-host= \ - --mysql-port=4000 \ - --mysql-user=root \ - --mysql-db=sbtest \ - --time=600 \ - --threads= \ - --report-interval=10 \ - --db-driver=mysql \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --tables=16 \ - --table-size=10000000 \ - \ - run -``` - -`` 为 sysbench 的测试 case。我们选择了 oltp_point_select、oltp_update_index、oltp_update_no_index、oltp_read_write 这几种。 - -## 测试报告 - -### 单可用区测试 - -#### Pod Network vs Host Network - -Kubernetes 允许 Pod 运行在 Host 网络模式下。此部署方式适用于 TiDB 实例独占机器且没有端口冲突的情况。我们分别在两种网络模式下做了 Point Select 测试。 - -此次测试中，操作系统为 COS。 - -Pod Network: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 246386.44 | 0.95 | -| 300 | 346557.39 | 1.55 | -| 600 | 396715.66 | 2.86 | -| 900 | 407437.96 | 4.18 | -| 1200 | 415138.00 | 5.47 | -| 1500 | 419034.43 | 6.91 | - -Host Network: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 255981.11 | 1.06 | -| 300 | 366482.22 | 1.50 | -| 600 | 421279.84 | 2.71 | -| 900 | 438730.81 | 3.96 | -| 1200 | 441084.13 | 5.28 | -| 1500 | 447659.15 | 6.67 | - -QPS 对比： - -![Pod vs Host Network](/media/sysbench-in-k8s/pod-vs-host-network-qps.png) - -Latency 对比： - -![Pod vs Host Network](/media/sysbench-in-k8s/pod-vs-host-network-latency.png) - -从图中可以看到 Host 网络下整体表现略好于 Pod 网络。 - -#### Ubuntu vs COS - -GKE 平台可以为节点选择 [Ubuntu 和 COS 两种操作系统](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images)。本次测试中，分别在两种操作系统中进行了 Point Select 测试。 - -此次测试中 Pod 网络模式为 Host。 - -COS: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 255981.11 | 1.06 | -| 300 | 366482.22 | 1.50 | -| 600 | 421279.84 | 2.71 | -| 900 | 438730.81 | 3.96 | -| 1200 | 441084.13 | 5.28 | -| 1500 | 447659.15 | 6.67 | - -Ubuntu: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 290690.51 | 0.74 | -| 300 | 422941.17 | 1.10 | -| 600 | 476663.44 | 2.14 | -| 900 | 484405.99 | 3.25 | -| 1200 | 489220.93 | 4.33 | -| 1500 | 489988.97 | 5.47 | - -QPS 对比： - -![COS vs Ubuntu](/media/sysbench-in-k8s/cos-vs-ubuntu-qps.png) - -Latency 对比： - -![COS vs Ubuntu](/media/sysbench-in-k8s/cos-vs-ubuntu-latency.png) - -从图中可以看到 Host 模式下，在单纯的 Point Select 测试中，TiDB 在 Ubuntu 系统中的表现比在 COS 系统中的表现要好。 - -> **注意：** -> -> 此测试只针对单一测试集进行了测试，表明不同的操作系统、不同的优化与默认设置，都有可能影响性能，所以我们在此不对操作系统做推荐。COS 系统专为容器优化，在安全性、磁盘性能做了优化，在 GKE 是官方推荐系统。 - -#### K8S Service vs GCP LoadBalancer - -通过 Kubernetes 部署 TiDB 集群后，有两种访问 TiDB 集群的场景：集群内通过 Service 访问或集群外通过 Load Balancer IP 访问。本次测试中分别对这两种情况进行了对比测试。 - -此次测试中操作系统为 Ubuntu，Pod 为 Host 网络。 - -Service: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 290690.51 | 0.74 | -| 300 | 422941.17 | 1.10 | -| 600 | 476663.44 | 2.14 | -| 900 | 484405.99 | 3.25 | -| 1200 | 489220.93 | 4.33 | -| 1500 | 489988.97 | 5.47 | - -Load Balancer: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 255981.11 | 1.06 | -| 300 | 366482.22 | 1.50 | -| 600 | 421279.84 | 2.71 | -| 900 | 438730.81 | 3.96 | -| 1200 | 441084.13 | 5.28 | -| 1500 | 447659.15 | 6.67 | - -QPS 对比： - -![Service vs Load Balancer](/media/sysbench-in-k8s/service-vs-load-balancer-qps.png) - -Latency 对比： - -![Service vs Load Balancer](/media/sysbench-in-k8s/service-vs-load-balancer-latency.png) - -从图中可以看到在单纯的 Point Select 测试中，使用 Kubernetes Service 访问 TiDB 时的表现比使用 GCP Load Balancer 访问时要好。 - -#### n1-standard-16 vs c2-standard-16 - -在 Point Select 读测试中，TiDB 的 CPU 占用首先达到 1400% (16 cores) 以上，此时 TiKV CPU 占用约 1000% (16 cores) 。我们对比了普通型和计算优化型机器下 TiDB 的不同表现。其中 n1-stadnard-16 主频约 2.3G，c2-standard-16 主频约 3.1G。 - -此次测试中操作系统为 Ubuntu，Pod 为 Host 网络，使用 Service 访问 TiDB。 - -n1-standard-16: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 203879.49 | 1.37 | -| 300 | 272175.71 | 2.3 | -| 600 | 287805.13 | 4.1 | -| 900 | 295871.31 | 6.21 | -| 1200 | 294765.83 | 8.43 | -| 1500 | 298619.31 | 10.27 | - -c2-standard-16: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 290690.51 | 0.74 | -| 300 | 422941.17 | 1.10 | -| 600 | 476663.44 | 2.14 | -| 900 | 484405.99 | 3.25 | -| 1200 | 489220.93 | 4.33 | -| 1500 | 489988.97 | 5.47 | - -QPS 对比： - -![n1-standard-16 vs c2-standard-16](/media/sysbench-in-k8s/n1-standard-16-vs-c2-standard-16-qps.png) - -Latency 对比： - -![n1-standard-16 vs c2-standard-16](/media/sysbench-in-k8s/n1-standard-16-vs-c2-standard-16-latency.png) - -### OLTP 其他测试 - -使用 Point Select 测试针对不同操作系统、不同网络情况做了对比测试后，也进行了 OLTP 测试集中的其他测试。这些测试统一使用 Ubuntu 系统、Host 模式并在集群使用 Service 访问 TiDB 集群。 - -#### OLTP Update Index - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 6726.59 | 30.26 | -| 300 | 11067.55 | 36.24 | -| 600 | 17358.46 | 48.34 | -| 900 | 21025.23 | 64.47 | -| 1200 | 22121.87 | 90.78 | -| 1500 | 22650.13 | 118.92 | - -![OLTP Update Index](/media/sysbench-in-k8s/oltp-update-index-qps.png) -![OLTP Update Index](/media/sysbench-in-k8s/oltp-update-index-latency.png) - -#### OLTP Update Non Index - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 9230.60 | 23.95 | -| 300 | 16543.63 | 54.83 | -| 600 | 23551.01 | 61.08 | -| 900 | 31100.10 | 65.65 | -| 1200 | 33942.60 | 54.83 | -| 1500 | 42603.13 | 125.52 | - -![OLTP Update No Index](/media/sysbench-in-k8s/oltp-update-no-index-qps.png) -![OLTP Update No Index](/media/sysbench-in-k8s/oltp-update-no-index-latency.png) - -#### OLTP Read Write - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 60732.84 | 69.29 | -| 300 | 91005.98 | 90.78 | -| 600 | 110517.67 | 167.44 | -| 900 | 119866.38 | 235.74 | -| 1200 | 125615.89 | 282.25 | -| 1500 | 128501.34 | 344.082 | - -![OLTP Read Write](/media/sysbench-in-k8s/oltp-read-write-qps.png) -![OLTP Read Write](/media/sysbench-in-k8s/oltp-read-write-latency.png) - -### 单可用区与多可用区对比 - -GCP 多可用区涉及跨 Zone 通信，网络延迟相比同 Zone 会少许增加。我们使用同样机器配置，对两种部署方案进行同一标准下的性能测试，了解多可用区延迟增加带来的影响。 - -单可用区： - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 203879.49 | 1.37 | -| 300 | 272175.71 | 2.30 | -| 600 | 287805.13 | 4.10 | -| 900 | 295871.31 | 6.21 | -| 1200 | 294765.83 | 8.43 | -| 1500 | 298619.31 | 10.27 | - -多可用区： - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 141027.10 | 1.93 | -| 300 | 220205.85 | 2.91 | -| 600 | 250464.34 | 5.47 | -| 900 | 257717.41 | 7.70 | -| 1200 | 258835.24 | 10.09 | -| 1500 | 280114.00 | 12.75 | - -QPS 对比： - -![Single Zonal vs Regional](/media/sysbench-in-k8s/single-zonal-vs-regional-qps.png) - -Latency 对比： - -![Single Zonal vs Regional](/media/sysbench-in-k8s/single-zonal-vs-regional-latency.png) - -从图中可以看到并发压力增大后，网络额外延迟产生的影响越来越小，额外的网络延迟将不再是主要的性能瓶颈。 - -## 结语 - -此次测试主要将典型公有云部署 Kubernetes 运行 TiDB 集群的几种场景使用 sysbench 做了测试，了解不同因素可能带来的影响。从整体看，主要有以下几点： - -- VPC-Native 模式下 Host 网络性能略好于 Pod 网络（~7%，以 QPS 差异估算，下同） -- GCP 的 Ubuntu 系统 Host 网络下单纯的读测试中性能略好于 COS (~9%) -- 使用 Load Balancer 在集群外访问，会略损失性能 (~5%) -- 多可用区下节点之间延迟增加，会对 TiDB 性能产生一定的影响（30% ~ 6%，随并发数增加而下降） -- Point Select 读测试主要消耗 CPU ，计算型机型相对普通型机器带来了很大 QPS 提升 (50% ~ 60%) - -但要注意的是，这些因素可能随着时间变化，不同公有云下的表现可能会略有不同。在未来，我们将带来更多维度的测试。同时，sysbench 测试用例并不能完全代表实际业务场景，在做选择前建议模拟实际业务测试，并综合不同选择成本进行选择（机器成本、操作系统差异、Host 网络的限制等）。 diff --git a/v3.0/benchmark/sysbench-v2.md b/v3.0/benchmark/sysbench-v2.md deleted file mode 100644 index 2f61be4f68a6..000000000000 --- a/v3.0/benchmark/sysbench-v2.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 -category: benchmark -aliases: ['/docs-cn/benchmark/sysbench-v2/'] ---- - -# TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 - -## 测试目的 - -对比 TiDB 2.0 版本和 1.0 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v1.0.8 Vs v2.0.0-rc6 - -时间：2018 年 4 月 - -地点：北京 - -## 测试环境 - -IDC 机器 - -| 类别 | 名称 | -| :--------: | :---------: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD * 1 | - -## 测试方案 - -### TiDB 版本信息 - -### v1.0.8 - -| 组件 | GitHash | -| :--------: | :---------: | -| TiDB | 571f0bbd28a0b8155a5ee831992c986b90d21ab7 | -| TiKV | 4ef5889947019e3cb55cc744f487aa63b42540e7 | -| PD | 776bcd940b71d295a2c7ed762582bc3aff7d3c0e | - -### v2.0.0-rc6 - -| 组件 | GitHash | -| :--------: | :---------: | -| TiDB | 82d35f1b7f9047c478f4e1e82aa0002abc8107e7 | -| TiKV | 7ed4f6a91f92cad5cd5323aaebe7d9f04b77cc79 | -| PD | 2c8e7d7e33b38e457169ce5dfb2f461fced82d65 | - -### TiKV 参数配置 - -* v1.0.8 - - ``` - sync-log = false - grpc-concurrency = 8 - grpc-raft-conn-num = 24 - ``` - -* v2.0.0-rc6 - - ``` - sync-log = false - grpc-concurrency = 8 - grpc-raft-conn-num = 24 - use-delete-range: false - ``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|--------------|------------| -| 172.16.21.1 | 1*tidb 1*pd 1*sysbench | -| 172.16.21.2 | 1*tidb 1*pd 1*sysbench | -| 172.16.21.3 | 1*tidb 1*pd 1*sysbench | -| 172.16.11.4 | 1*tikv | -| 172.16.11.5 | 1*tikv | -| 172.16.11.6 | 1*tikv | -| 172.16.11.7 | 1*tikv | -| 172.16.11.8 | 1*tikv | -| 172.16.11.9 | 1*tikv | - -## 测试结果 - -### 标准 Select 测试 - -| 版本 | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 201936 | 1.9033 ms / 5.67667 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 208130 | 3.69333 ms / 8.90333 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 211788 | 7.23333 ms / 15.59 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 212868 | 14.5933 ms / 43.2133 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 188686 | 2.03667 ms / 5.99 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 195090 |3.94 ms / 9.12 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 203012 | 7.57333 ms / 15.3733 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 205932 | 14.9267 ms / 40.7633 ms | - -GA2.0 比 GA1.0 在 Select 查询性能上，最高提升了 10% 左右。 - -### 标准 OLTP 测试 - -| 版本 | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---:| -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 5404.22 | 108084.4 | 87.2033 ms / 110 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 5578.165 | 111563.3 | 167.673 ms / 275.623 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 5874.045 | 117480.9 | 315.083 ms / 674.017 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 6290.7 | 125814 | 529.183 ms / 857.007 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 5523.91 | 110478 | 69.53 ms / 88.6333 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 5969.43 | 119389 |128.63 ms / 162.58 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 6308.93 | 126179 | 243.543 ms / 310.913 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 6444.25 | 128885 | 476.787ms / 635.143 ms | - -GA2.0 比 GA1.0 在 OLTP 性能上，性能基本一致。 - -### 标准 Insert 测试 - -| 版本 | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 31707.5 | 12.11 ms / 21.1167 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 38741.2 | 19.8233 ms / 39.65 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 45136.8 | 34.0267 ms / 66.84 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 48667 | 63.1167 ms / 121.08 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 31125.7 | 12.3367 ms / 19.89 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 36800 | 20.8667 ms / 35.3767 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 44123 | 34.8067 ms / 63.32 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 48496 | 63.3333 ms / 118.92 ms | - -GA2.0 比 GA1.0 在 Insert 性能上略有提升。 diff --git a/v3.0/benchmark/sysbench-v3.md b/v3.0/benchmark/sysbench-v3.md deleted file mode 100644 index 1c8cff61684a..000000000000 --- a/v3.0/benchmark/sysbench-v3.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 -category: benchmark -aliases: ['/docs-cn/benchmark/sysbench-v3/'] ---- - -# TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 - -## 测试目的 - -对比 TiDB 2.1 版本和 2.0 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v2.1.0-rc.2 vs. v2.0.6 - -时间：2018 年 9 月 - -地点：北京 - -## 测试环境 - -IDC 机器： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD \* 1 | - -Sysbench 版本：1.1.0 - -## 测试方案 - -使用 Sysbench 向集群导入 **16 张表，每张数据 1000 万**。通过 HAProxy 代理，分别以递增并发数向集群发送请求，单次并发测试时间 5 分钟。 - -### TiDB 版本信息 - -### v2.1.0-rc.2 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 08e56cd3bae166b2af3c2f52354fbc9818717f62 | -| TiKV | 57e684016dafb17dc8a6837d30224be66cbc7246 | -| PD | 6a7832d2d6e5b2923c79683183e63d030f954563 | - -### v2.0.6 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | b13bc08462a584a085f377625a7bab0cc0351570 | -| TiKV | 57c83dc4ebc93d38d77dc8f7d66db224760766cc | -| PD | b64716707b7279a4ae822be767085ff17b5f3fea | - -### TiDB 参数配置 - -两版本 TiDB 均使用**默认配置**。 - -### TiKV 参数配置 - -两版本 TiKV 均使用如下配置： - -```txt -[readpool.storage] -normal-concurrency = 8 -[server] -grpc-concurrency = 8 -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "60GB" -[rocksdb.writecf] -block-cache-size = "20GB" -``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-: | :-: | -| 172.16.30.31 | 1\*Sysbench 1\*HAProxy | -| 172.16.30.32 | 1\*TiDB 1\*pd 1\*TiKV | -| 172.16.30.33 | 1\*TiDB 1\*TiKV | -| 172.16.30.34 | 1\*TiDB 1\*TiKV | - -## 测试结果 - -### Point Select 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 111481.09 | 1.16 | -| v2.1 | 128 | 145102.62 | 2.52 | -| v2.1 | 256 | 161311.9 | 4.57 | -| v2.1 | 512 | 184991.19 | 7.56 | -| v2.1 | 1024 | 230282.74 | 10.84 | -| v2.0 | 64 | 75285.87 | 1.93 | -| v2.0 | 128 | 92141.79 | 3.68 | -| v2.0 | 256 | 107464.93 | 6.67 | -| v2.0 | 512 | 121350.61 | 11.65 | -| v2.0 | 1024 | 150036.31 | 17.32 | - -![point select](/media/sysbench_v3_point_select.png) - -v2.1 比 v2.0 在 Point Select 查询性能上，**提升了 50%**。 - -### Update Non-Index 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 18946.09 | 5.77 | -| v2.1 | 128 | 22022.82 | 12.08 | -| v2.1 | 256 | 24679.68 | 25.74 | -| v2.1 | 512 | 25107.1 | 51.94 | -| v2.1 | 1024 | 27144.92 | 106.75 | -| v2.0 | 64 | 16316.85 | 6.91 | -| v2.0 | 128 | 20944.6 | 11.45 | -| v2.0 | 256 | 24017.42 | 23.1 | -| v2.0 | 512 | 25994.33 | 46.63 | -| v2.0 | 1024 | 27917.52 | 92.42 | - -![update non-index](/media/sysbench_v3_update_non_index.png) - -v2.1 与 v2.0 在 Update Non-Index 写入性能上基本一致。 - -### Update Index 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 9934.49 | 12.08 | -| v2.1 | 128 | 10505.95 | 25.28 | -| v2.1 | 256 | 11007.7 | 55.82 | -| v2.1 | 512 | 11198.81 | 106.75 | -| v2.1 | 1024 | 11591.89 | 200.47 | -| v2.0 | 64 | 9754.68 | 11.65 | -| v2.0 | 128 | 10603.31 | 24.38 | -| v2.0 | 256 | 11011.71 | 50.11 | -| v2.0 | 512 | 11162.63 | 104.84 | -| v2.0 | 1024 | 12067.63 | 179.94 | - -![update index](/media/sysbench_v3_update_index.png) - -v2.1 与 v2.0 在 Update Index 写入性能上基本一致。 diff --git a/v3.0/benchmark/sysbench-v4.md b/v3.0/benchmark/sysbench-v4.md deleted file mode 100644 index 1f269da1d484..000000000000 --- a/v3.0/benchmark/sysbench-v4.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v3.0 对比 v2.1 -category: benchmark -aliases: ['/docs-cn/benchmark/sysbench-v4/'] ---- - -# TiDB Sysbench 性能对比测试报告 - v3.0 对比 v2.1 - -## 测试目的 - -对比 TiDB 3.0 版本和 2.1 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v3.0.0 vs. v2.1.13 - -时间：2019 年 6 月 - -地点：北京 - -## 测试环境 - -测试在 AWS EC2 上进行，使用 CentOS-7.6.1810-Nitro (ami-028946f4cffc8b916) 镜像，各组件实例类型如下： - -| 组件 | 实例类型 | -| :--- | :--------- | -| PD | r5d.xlarge | -| TiKV | c5d.4xlarge | -| TiDB | c5.4xlarge | - -Sysbench 版本：1.0.17 - -## 测试方案 - -使用 Sysbench 向集群导入 **16 张表，每张数据 1000 万**。起 3 个 sysbench 分别向 3 个 TiDB 发压，请求并发数逐步增加，单次测试时间 5 分钟。 - -准备数据命令： - -{{< copyable "shell-regular" >}} - -```sh -sysbench oltp_common \ - --threads=16 \ - --rand-type=uniform \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - --mysql-password=password \ - prepare --tables=16 --table-size=10000000 -``` - -执行测试命令： - -{{< copyable "shell-regular" >}} - -```sh -sysbench $testname \ - --threads=$threads \ - --time=300 \ - --report-interval=15 \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - --mysql-password=password \ - run --tables=16 --table-size=10000000 -``` - -### TiDB 版本信息 - -### v3.0.0 - -| 组件 | GitHash | -| :--- | :---------------------------------------- | -| TiDB | `8efbe62313e2c1c42fd76d35c6f020087eef22c2` | -| TiKV | `a467f410d235fa9c5b3c355e3b620f81d3ac0e0c` | -| PD | `70aaa5eee830e21068f1ba2d4c9bae59153e5ca3` | - -### v2.1.13 - -| 组件 | GitHash | -| :--- | :---------------------------------------- | -| TiDB | `6b5b1a6802f9b8f5a22d8aab24ac80729331e1bc` | -| TiKV | `b3cf3c8d642534ea6fa93d475a46da285cc6acbf` | -| PD | `886362ebfb26ef0834935afc57bcee8a39c88e54` | - -### TiDB 参数配置 - -2.1 和 3.0 中开启 prepared plan cache (出于优化考虑，2.1 的 point select 与 read write 并未开启)： - -```toml -[prepared-plan-cache] -enabled = true -``` - -并设置全局变量： - -{{< copyable "sql" >}} - -```sql -set global tidb_hashagg_final_concurrency=1; -set global tidb_hashagg_partial_concurrency=1; -set global tidb_disable_txn_auto_retry=0; -``` - -此外 3.0 还做了如下配置： - -```toml -[tikv-client] -max-batch-wait-time = 2000000 -``` - -### TiKV 参数配置 - -2.1 和 3.0 使用如下配置： - -```toml -log-level = "error" -[readpool.storage] -normal-concurrency = 10 -[server] -grpc-concurrency = 6 -[rocksdb.defaultcf] -block-cache-size = "14GB" -[rocksdb.writecf] -block-cache-size = "8GB" -[rocksdb.lockcf] -block-cache-size = "1GB" -``` - -3.0 还做了如下配置： - -```toml -[raftstore] -apply-pool-size = 3 -store-pool-size = 3 -``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-------------------------------------- | :----------| -| 172.31.8.8 | 3 * Sysbench | -| 172.31.7.80, 172.31.5.163, 172.31.11.123 | PD | -| 172.31.4.172, 172.31.1.155, 172.31.9.210 | TiKV | -| 172.31.7.80, 172.31.5.163, 172.31.11.123 | TiDB | - -## 测试结果 - -### Point Select 测试 - -**v2.1** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :------------- | -| 150 | 240304.06 | 1.61 | -| 300 | 276635.75 | 2.97 | -| 600 | 307838.06 | 5.18 | -| 900 | 323667.93 | 7.30 | -| 1200 | 330925.73 | 9.39 | -| 1500 | 336250.38 | 11.65 | - - - -**v3.0** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :-------------- | -| 150 | 334219.04 | 0.64 | -| 300 | 456444.86 | 1.10 | -| 600 | 512177.48 | 2.11 | -| 900 | 525945.13 | 3.13 | -| 1200 | 534577.36 | 4.18 | -| 1500 | 533944.64 | 5.28 | - -![point select](/media/sysbench_v4_point_select.png) - -### Update Non-Index 测试 - -**v2.1** - -| threads | qps | 95% latency(ms) | -| ------- | -------: | --------------: | -| 150 | 21785.37 | 8.58 | -| 300 | 28979.27 | 13.70 | -| 600 | 34629.72 | 24.83 | -| 900 | 36410.06 | 43.39 | -| 1200 | 37174.15 | 62.19 | -| 1500 | 37408.88 | 87.56 | - -**v3.0** - -| threads | qps | 95% latency(ms) | -| ------- | -------: | --------------: | -| 150 | 28045.75 | 6.67 | -| 300 | 39237.77 | 9.91 | -| 600 | 49536.56 | 16.71 | -| 900 | 55963.73 | 22.69 | -| 1200 | 59904.02 | 29.72 | -| 1500 | 62247.95 | 42.61 | - -![update non-index](/media/sysbench_v4_update_non_index.png) - -### Update Index 测试 - -**v2.1** - -| Threads | QPS | 95% latency(ms) | -| :------- | :------- | :-------------- | -| 150 | 14378.24 | 13.22 | -| 300 | 16916.43 | 24.38 | -| 600 | 17636.11 | 57.87 | -| 900 | 17740.92 | 95.81 | -| 1200 | 17929.24 | 130.13 | -| 1500 | 18012.80 | 161.51 | - -**v3.0** - -| Threads | QPS | 95% latency(ms) | -| :------- | :------- | :-------------| -| 150 | 19047.32 | 10.09 | -| 300 | 24467.64 | 16.71 | -| 600 | 28882.66 | 31.94 | -| 900 | 30298.41 | 57.87 | -| 1200 | 30419.40 | 92.42 | -| 1500 | 30643.55 | 125.52 | - -![update index](/media/sysbench_v4_update_index.png) - -### Read Write 测试 - -**v2.1** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :-------------- | -| 150 | 85140.60 | 44.98 | -| 300 | 96773.01 | 82.96 | -| 600 | 105139.81 | 153.02 | -| 900 | 110041.83 | 215.44 | -| 1200 | 113242.70 | 277.21 | -| 1500 | 114542.19 | 337.94 | - - - -**v3.0** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :-------------- | -| 150 | 105692.08 | 35.59 | -| 300 | 129769.69 | 58.92 | -| 600 | 141430.86 | 114.72 | -| 900 | 144371.76 | 170.48 | -| 1200 | 143344.37 | 223.34 | -| 1500 | 144567.91 | 277.21 | - -![read write](/media/sysbench_v4_read_write.png) diff --git a/v3.0/benchmark/sysbench.md b/v3.0/benchmark/sysbench.md deleted file mode 100644 index 48daef55e805..000000000000 --- a/v3.0/benchmark/sysbench.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: TiDB Sysbench 性能测试报告 - v1.0.0 -category: benchmark -draft: true -aliases: ['/docs-cn/benchmark/sysbench/'] ---- - -# TiDB Sysbench 性能测试报告 - v1.0.0 - -## 测试目的 - -测试 TiDB 在 OLTP 场景下的性能以及水平扩展能力。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试版本、时间、地点 - -TiDB 版本：v1.0.0 -时间：2017 年 10 月 20 日 -地点：北京 - -## 测试环境 - -IDC 机器 - -| 类别 | 名称 | -| :--------: | :---------: | -| OS | linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | 1.5T SSD \* 2 + Optane SSD \* 1 | - -Sysbench 版本: 1.0.6 - -测试脚本: - -## 测试方案 - -### 场景一：sysbench 标准性能测试 - -测试表结构 - -``` -CREATE TABLE `sbtest` ( - `id` int(10) unsigned NOT NULL AUTO_INCREMENT, - `k` int(10) unsigned NOT NULL DEFAULT '0', - `c` char(120) NOT NULL DEFAULT '', - `pad` char(60) NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB -``` - -部署方案以及配置参数 - -``` -// TiDB 部署方案 -172.16.20.4 4*tikv 1*tidb 1*sysbench -172.16.20.6 4*tikv 1*tidb 1*sysbench -172.16.20.7 4*tikv 1*tidb 1*sysbench -172.16.10.8 1*tidb 1*pd 1*sysbench - -// 每个物理节点有三块盘： -data3: 2 tikv (Optane SSD) -data2: 1 tikv -data1: 1 tikv - -// TiKV 参数配置 -sync-log = false -grpc-concurrency = 8 -grpc-raft-conn-num = 24 -[defaultcf] -block-cache-size = "12GB" -[writecf] -block-cache-size = "5GB" -[raftdb.defaultcf] -block-cache-size = "2GB" - -// Mysql 部署方案 -// 分别使用半同步复制和异步复制，部署两副本 -172.16.20.4 master -172.16.20.6 slave -172.16.20.7 slave -172.16.10.8 1*sysbench -Mysql version: 5.6.37 - -// Mysql 参数配置 -thread_cache_size = 64 -innodb_buffer_pool_size = 64G -innodb_file_per_table = 1 -innodb_flush_log_at_trx_commit = 0 -datadir = /data3/mysql -max_connections = 2000 -``` - -* 标准 oltp 测试 - -| - | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 3834 | 76692 | 67.04 ms / 110.88 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 4172 | 83459 | 124.00 ms / 194.21 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 4577 | 91547 | 228.36 ms / 334.02 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 4032 | 80657 | 256.62 ms / 443.88 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 3811 | 76233 | 269.46 ms / 505.20 ms | -| Mysql | 32 | 100 万 | 64 | 2392 | 47845 | 26.75 ms / 73.13 ms | -| Mysql | 32 | 100 万 | 128 | 2493 | 49874 | 51.32 ms / 173.58 ms | -| Mysql | 32 | 100 万 | 256 | 2561 | 51221 | 99.95 ms / 287.38 ms | -| Mysql | 32 | 500 万 | 256 | 1902 | 38045 | 134.56 ms / 363.18 ms | -| Mysql | 32 | 1000 万 | 256 | 1770 | 35416 | 144.55 ms / 383.33 ms | - -![sysbench-01](/media/sysbench-01.png) - -![sysbench-02](/media/sysbench-02.png) - -* 标准 select 测试 - -| - | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 160299 | 1.61ms / 50.06 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 183347 | 2.85 ms / 8.66 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 196515 | 5.42 ms / 14.43 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 187628 | 5.66 ms / 15.04 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 187440 | 5.65 ms / 15.37 ms | -| Mysql | 32 | 100 万 | 64 | 359572 | 0.18 ms / 0.45 ms | -| Mysql | 32 | 100 万 | 128 | 410426 |0.31 ms / 0.74 ms | -| Mysql | 32 | 100 万 | 256 | 396867 | 0.64 ms / 1.58 ms | -| Mysql | 32 | 500 万 | 256 | 386866 | 0.66 ms / 1.64 ms | -| Mysql | 32 | 1000 万 | 256 | 388273 | 0.66 ms / 1.64 ms | - -![sysbench-03](/media/sysbench-03.png) - -![sysbench-04](/media/sysbench-04.png) - -* 标准 insert 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 25308 | 10.12 ms / 25.40 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 28773 | 17.80 ms / 44.58 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 32641 | 31.38 ms / 73.47 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 30430 | 33.65 ms / 79.32 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 28925 | 35.41 ms / 78.96 ms | -| Mysql | 32 | 100 万 | 64 | 14806 | 4.32 ms / 9.39 ms | -| Mysql | 32 | 100 万 | 128 | 14884 | 8.58 ms / 21.11 ms | -| Mysql | 32 | 100 万 | 256 | 14508 | 17.64 ms / 44.98 ms | -| Mysql | 32 | 500 万 | 256 | 10593 | 24.16 ms / 82.96 ms | -| Mysql | 32 | 1000 万 | 256 | 9813 | 26.08 ms / 94.10 ms | - -![sysbench-05](/media/sysbench-05.png) - -![sysbench-06](/media/sysbench-06.png) - -### 场景二：TiDB 水平扩展能力测试 - -部署方案以及配置参数 - -``` -// TiDB 部署方案 -172.16.20.3 4*tikv -172.16.10.2 1*tidb 1*pd 1*sysbench - -每个物理节点有三块盘： -data3: 2 tikv (Optane SSD) -data2: 1 tikv -data1: 1 tikv - -// TiKV 参数配置 -sync-log = false -grpc-concurrency = 8 -grpc-raft-conn-num = 24 -[defaultcf] -block-cache-size = "12GB" -[writecf] -block-cache-size = "5GB" -[raftdb.defaultcf] -block-cache-size = "2GB" -``` - -* 标准 oltp 测试 - -| - | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| 1 物理节点 TiDB | 32 | 100 万 | 256 * 1 | 2495 | 49902 | 102.42 ms / 125.52 ms | -| 2 物理节点 TiDB | 32 | 100 万 | 256 * 2 | 5007 | 100153 | 102.23 ms / 125.52 ms | -| 4 物理节点 TiDB | 32 | 100 万 | 256 * 4 | 8984 | 179692 | 114.96 ms / 176.73 ms | -| 6 物理节点 TiDB | 32 | 500 万 | 256 * 6 | 12953 | 259072 | 117.80 ms / 200.47 ms | - -![sysbench-07](/media/sysbench-07.png) - -* 标准 select 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| 1 物理节点 TiDB | 32 | 100 万 | 256 * 1 | 71841 | 3.56 ms / 8.74 ms | -| 2 物理节点 TiDB | 32 | 100 万 | 256 * 2 | 146615 | 3.49 ms / 8.74 ms | -| 4 物理节点 TiDB | 32 | 100 万 | 256 * 4 | 289933 | 3.53 ms / 8.74 ms | -| 6 物理节点 TiDB | 32 | 500 万 | 256 * 6 | 435313 | 3.55 ms / 9.17 ms | - -![sysbench-08](/media/sysbench-08.png) - -* 标准 insert 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| 3 物理节点 TiKV | 32 | 100 万 |256 * 3 | 40547 | 18.93 ms / 38.25 ms | -| 5 物理节点 TiKV | 32 | 100 万 | 256 * 3 | 60689 | 37.96 ms / 29.9 ms | -| 7 物理节点 TiKV | 32 | 100 万 | 256 * 3 | 80087 | 9.62 ms / 21.37 ms | - -![sysbench-09](/media/sysbench-09.png) diff --git a/v3.0/benchmark/tpcc.md b/v3.0/benchmark/tpcc.md deleted file mode 100644 index 8cf3926501a2..000000000000 --- a/v3.0/benchmark/tpcc.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v3.0 对比 v2.1 -category: benchmark ---- - -# TiDB TPC-C 性能对比测试报告 - v3.0 对比 v2.1 - -## 测试目的 - -对比 TiDB 3.0 版本和 2.1 版本的 TPC-C 性能表现。 - -## 测试版本、时间、地点 - -TiDB 版本：v3.0.0 vs. v2.1.13 - -时间：2019 年 6 月 - -地点：北京 - -## 测试环境 - -IDC 机器： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | 1.5TB SSD \* 2 | - -本文使用开源的 BenchmarkSQL 5.0 作为 TPC-C 测试工具并添加对 MySQL 协议支持， 可以通过以下命令下载测试程序: - -{{< copyable "shell-regular" >}} - -```shell -git clone -b 5.0-mysql-support-opt https://github.com/pingcap/benchmarksql.git -``` - -## 测试方案 - -使用 BenchmarkSQL 向集群导入 **1000 warehouse** 的数据。通过 HAProxy 代理，分别以递增并发数向集群发送请求，单次并发测试时间 10 分钟。 - -### TiDB 版本信息 - -### v3.0.0 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 46c38e15eba43346fb3001280c5034385171ee20 | -| TiKV | a467f410d235fa9c5b3c355e3b620f81d3ac0e0c | -| PD | 70aaa5eee830e21068f1ba2d4c9bae59153e5ca3 | - -### v2.1.13 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 6b5b1a6802f9b8f5a22d8aab24ac80729331e1bc | -| TiKV | b3cf3c8d642534ea6fa93d475a46da285cc6acbf | -| PD | 886362ebfb26ef0834935afc57bcee8a39c88e54 | - -### TiDB 参数配置 - -```toml -[log] -level = "error" -[performance] -max-procs = 20 -[prepared_plan_cache] -enabled = true -``` - -### TiKV 参数配置 - -默认配置 - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-: | :-: | -| 172.16.4.75 | 2\*TiDB 2\*TiKV 1\*pd | -| 172.16.4.76 | 2\*TiDB 2\*TiKV 1\*pd | -| 172.16.4.77 | 2\*TiDB 2\*TiKV 1\*pd | - -## 测试结果 - -| 版本 | threads | tpmC | -| :-: | :-: | :-: | -| v3.0 | 128 | 44068.55 | -| v3.0 | 256 | 47094.06 | -| v3.0 | 512 | 48808.65 | -| v2.1 | 128 | 10641.71 | -| v2.1 | 256 | 10861.62 | -| v2.1 | 512 | 10965.39 | - -![tpcc](/media/tpcc-2.1-3.0.png) - -v3.0 比 v2.1 在 TPC-C 性能上，**提升了 450%**。 diff --git a/v3.0/benchmark/tpch-v2.md b/v3.0/benchmark/tpch-v2.md deleted file mode 100644 index ad30b453bed9..000000000000 --- a/v3.0/benchmark/tpch-v2.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: TiDB TPC-H 50G 性能测试报告 -category: benchmark -aliases: ['/docs-cn/benchmark/tpch-v2/'] ---- - -# TiDB TPC-H 50G 性能测试报告 - -## 测试目的 - -测试 TiDB 在 OLAP 场景下 2.0 和 2.1 版本的性能对比。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试环境 - -### 测试机器信息 - -1. 系统信息 - -| 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | -|--------------|------------------------|------------------------------|--------------| -| 10.0.1.4 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.5 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.6 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.7 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.8 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | -| 10.0.1.9 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - -2. 硬件信息 - -| 类别 | 10.0.1.4 | 10.0.1.5, 10.0.1.6, 10.0.1.7, 10.0.1.8, 10.0.1.9 | -|------------|------------------------------------------------------|------------------------------------------------------| -| CPU | 16 vCPUs, Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz | 8 vCPUs, Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz | -| 内存 | 110G | 55G | -| 磁盘 | 221G SSD | 111G SSD | -| 网卡 | 万兆网卡, 10000Mb/s | 万兆网卡, 10000Mb/s | - -### TPC-H - -[tidb-bench/tpch](https://github.com/pingcap/tidb-bench/tree/master/tpch) - -### 集群拓扑 - -| 机器 IP | 部署的实例 | -|----------|------------| -| 10.0.1.5 | TiKV \* 1 | -| 10.0.1.6 | TiKV \* 1 | -| 10.0.1.7 | TiKV \* 1 | -| 10.0.1.8 | TiKV \* 1 | -| 10.0.1.9 | TiKV \* 1 | -| 10.0.1.4 | PD \* 1 | -| 10.0.1.4 | TiDB \* 1 | - -### TiDB 版本信息 - -TiDB 2.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.0.7 | 29ec059cb3b7d14b6f52c2f219f94a89570162bc | -| TiKV | v2.0.7 | d0b8cd7c7f62f06e7ef456837bd32a47da1ca4cd | -| PD | v2.0.5 | b64716707b7279a4ae822be767085ff17b5f3fea | - -TiDB 2.1： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.1.0-rc.2 | 16864f95b47f859ed6104555ccff0387abdc2429 | -| TiKV | v2.1.0-rc.2 | 8458ce53ebbd434c48baac6373fe0f0a43a54005 | -| PD | v2.1.0-rc.2 | 55db505e8f35e8ab4e00efd202beb27a8ecc40fb | - -## 测试结果 - -| Query ID | TiDB 2.0 | TiDB 2.1 | -|-----------|----------------|----------------| -| 1 | 121.550595999s | 91.4755480289s | -| 2 | 53.0638680458s | 23.1186130047s | -| 3 | 75.7236940861s | 61.790802002s | -| 4 | 30.2647120953s | 26.3483440876s | -| 6 | 51.4850790501s | 34.6432199478s | -| 7 | 216.787364006s | 94.9856910706s | -| 8 | 188.717588902s | 181.852752209s | -| 9 | 546.438174009s | 414.462754965s | -| 10 | 109.978317022s | 37.0369961262s | -| 11 | 42.9398438931s | 37.6951580048s | -| 12 | 60.455039978s | 40.2236878872s | -| 13 | 230.278712988s | 70.2887151241s | -| 14 | 61.2673521042s | 35.8372960091s | -| 16 | 30.2539310455s | 18.5897550583s | -| 17 | 3200.70173788s | 263.095014811s | -| 18 | 1035.59847498s | 296.360667944s | -| 19 | 54.3732938766s | 40.4523630142s | -| 20 | 105.094577074s | 53.2429068089s | -| 21 | 389.883709908s | 361.034544945s | -| 22 | 64.0494630337s | 65.7153418064s | - -![TPC-H Query Result](/media/tpch-query-result-v2.png) - -说明： -- 图中橙色为 Release 2.1，蓝色为 Release 2.0，纵坐标是 Query 的处理时间，越低越好 -- Query 15 因为 2.1 和 2.0 都还未支持视图，所以未列出结果 -- Query 5 因为 Join Order 问题长时间未跑出结果来，所以未列出结果 diff --git a/v3.0/benchmark/tpch.md b/v3.0/benchmark/tpch.md deleted file mode 100644 index a7693a4310c8..000000000000 --- a/v3.0/benchmark/tpch.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: TiDB TPC-H 50G 性能测试报告 -category: benchmark -aliases: ['/docs-cn/benchmark/tpch/'] ---- - -# TiDB TPC-H 50G 性能测试报告 - -## 测试目的 - -测试 TiDB 在 OLAP 场景下 1.0 和 2.0 版本的性能对比。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试环境 - -### 测试机器信息 - -1. 系统信息 - -| 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | -|--------------|------------------------|------------------------------|--------------| -| 172.16.31.2 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | -| 172.16.31.3 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | -| 172.16.31.4 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | -| 172.16.31.6 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | -| 172.16.31.8 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | -| 172.16.31.10 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | - -2. 硬件信息 - -| 类别 | 名称 | -|------------|------------------------------------------------------| -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| 内存 | 128GB, 8条16GB RDIMM, 2400MT/s, 双列, x8 带宽 | -| 磁盘 | 2 块 Intel P4500 系列 4T SSD 硬盘 | -| 网卡 | 万兆网卡 | - -### TPC-H - -[tidb-bench/tpch](https://github.com/pingcap/tidb-bench/tree/master/tpch) - -### 集群拓扑 - -| 机器 IP | 部署的实例 | -|--------------|------------| -| 172.16.31.2 | TiKV \* 2 | -| 172.16.31.3 | TiKV \* 2 | -| 172.16.31.6 | TiKV \* 2 | -| 172.16.31.8 | TiKV \* 2 | -| 172.16.31.10 | TiKV \* 2 | -| 172.16.31.10 | PD \* 1 | -| 172.16.31.4 | TiDB \* 1 | - -### TiDB 版本信息 - -TiDB 1.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v1.0.9 | 4c7ee3580cd0a69319b2c0c08abdc59900df7344 | -| TiKV | v1.0.8 | 2bb923a4cd23dbf68f0d16169fd526dc5c1a9f4a | -| PD | v1.0.8 | 137fa734472a76c509fbfd9cb9bc6d0dc804a3b7 | - -TiDB 2.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.0.0-rc.6 | 82d35f1b7f9047c478f4e1e82aa0002abc8107e7 | -| TiKV | v2.0.0-rc.6 | 8bd5c54966c6ef42578a27519bce4915c5b0c81f | -| PD | v2.0.0-rc.6 | 9b824d288126173a61ce7d51a71fc4cb12360201 | - -## 测试结果 - -| Query ID | TiDB 2.0 | TiDB 1.0 | -|-----------|--------------------|------------------| -| 1 | 33.915s | 215.305s | -| 2 | 25.575s | NaN | -| 3 | 59.631s | 196.003s | -| 4 | 30.234s | 249.919s | -| 5 | 31.666s | OOM | -| 6 | 13.111s | 118.709s | -| 7 | 31.710s | OOM | -| 8 | 31.734s | 800.546s | -| 9 | 34.211s | 630.639s | -| 10 | 30.774s | 133.547s | -| 11 | 27.692s | 78.026s | -| 12 | 27.962s | 124.641s | -| 13 | 27.676s | 174.695s | -| 14 | 19.676s | 110.602s | -| 15 | View Required | View Required | -| 16 | 24.890s | 40.529s | -| 17 | 245.796s | NaN | -| 18 | 91.256s | OOM | -| 19 | 37.615s | NaN | -| 20 | 44.167s | 212.201s | -| 21 | 31.466s | OOM | -| 22 | 31.539s | 125.471s | - -![TPC-H Query Result](/media/tpch-query-result.png) - -说明： -- 图中橙色为 Release 1.0，蓝色为 Release 2.0，纵坐标是 Query 的处理时间，越低越好 -- Query 15 因为 1.0 和 2.0 都还未支持视图，所以结果标记为 "View Required" -- Query 2, 17, 19 因为 TiDB 1.0 长时间未跑出结果，所以结果标记为 "Nan" -- Query 5, 7, 18, 21 因为 TiDB 1.0 在跑的过程中内存占用过多被 oom-killer 杀死，所以结果标记为 "OOM" diff --git a/v3.0/contribute.md b/v3.0/contribute.md deleted file mode 100644 index 9bd79baa87c6..000000000000 --- a/v3.0/contribute.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 成为贡献者 -category: contribute -aliases: ['/docs-cn/contribute/'] ---- - -# 成为贡献者 - -## 成为 TiDB 的贡献者 - -我们推荐您先尝试解决带 [help-wanted](https://github.com/pingcap/tidb/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) 标签的现有 Issue，这些问题非常适合新的贡献者。 - -一旦您提交给 [TiDB/TiKV/TiSpark/PD/TiDB Operator/Docs/Docs-cn](https://github.com/pingcap) 项目的 PR (Pull Request) 被批准且合并，您即成为 TiDB 的贡献者。 - -在提交 PR 之前，请先签署 [CLA](https://cla-assistant.io/pingcap/tidb?pullRequest=5567)。 - -如果您想实践一个影响范围相对较小的新想法，请遵循以下步骤： - -1. 提交新 Issue，描述您对相关仓库的更改建议。 -2. 相关仓库的负责人将及时回复您的 Issue。 -3. 如果您的更改建议被接受，您需要先签署 [CLA](https://cla-assistant.io/pingcap/tidb?pullRequest=5567)，便可以在您的克隆仓库 (fork) 里开始工作了。 -4. 在测试过所做的更改后，您便可以提交[包含更改的 PR](https://github.com/pingcap/tidb/pull/3113) 了。 - -我们欢迎并非常感谢您的贡献。有关提交补丁和贡献流程的详细信息，请参阅[贡献者指南](https://github.com/pingcap/tidb/blob/master/CONTRIBUTING.md)。 - -## 改进文档 - -我们欢迎更多贡献者来帮助改进文档！ - -TiDB 文档使用 Markdown 语言，并参考了 [Google 开发者文档风格指南](https://developers.google.com/style/)进行编写。如果这些概念对您来说比较陌生，请不要担心，我们很乐意为您提供指导。 - -如要对文档仓库进行贡献，请先 fork [docs-cn 仓库](https://github.com/pingcap/docs-cn)，再提交您的 PR。 diff --git a/v3.0/faq/tidb-lightning.md b/v3.0/faq/tidb-lightning.md deleted file mode 100644 index 4e7dc4c36494..000000000000 --- a/v3.0/faq/tidb-lightning.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: TiDB Lightning 常见问题 -category: FAQ -aliases: ['/docs-cn/tools/lightning/faq/','/docs-cn/faq/tidb-lightning/'] ---- - -# TiDB Lightning 常见问题 - -本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。 - ->**注意：** -> -> 使用 TiDB Lightning 的过程中如遇错误，参考 [TiDB Lightning 故障诊断](/v3.0/how-to/troubleshoot/tidb-lightning.md)进行排查。 - -## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ - -TiDB Lightning 的版本应与集群相同。最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。 - -## TiDB Lightning 支持导入多个库吗？ - -支持。 - -## TiDB Lightning 对下游数据库的账号权限要求是怎样的？ - -TiDB Lightning 需要以下权限： - -* SELECT -* UPDATE -* ALTER -* CREATE -* DROP - -如果选择 [TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) 模式，或目标数据库用于存储断点，则 TiBD Lightning 额外需要以下权限： - -* INSERT -* DELETE - -Importer-backend 无需以上两个权限，因为数据直接被 Ingest 到 TiKV 中，所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问，就可以保证安全。 - -如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？ - -如果只是个别表报错，不会影响整体。报错的那个表会停止处理，继续处理其他的表。 - -## 如何正确重启 TiDB Lightning？ - -根据 `tikv-importer` 的状态，重启 TiDB Lightning 的基本顺序如下： - -如果 `tikv-importer` 仍在运行： - -1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 -3. 如果上面的修改操作更改了任何表，你还需要[清除对应的断点](/v3.0/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-remove)。 -4. 重启 `tidb-lightning`。 - -如果 `tikv-importer` 需要重启： - -1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. [结束 `tikv-importer` 进程](#如何正确结束-tikv-importer-进程)。 -3. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 -4. 重启 `tikv-importer`。 -5. 重启 `tidb-lightning` 并等待，**直到程序因校验和错误（如果有的话）而失败**。 - * 重启 `tikv-importer` 将清除所有仍在写入的引擎文件，但是 `tidb-lightning` 并不会感知到该操作。从 v3.0 开始，最简单的方法是让 `tidb-lightning` 继续，然后再重试。 -6. [清除失败的表及断点](/v3.0/how-to/troubleshoot/tidb-lightning.md#checkpoint-for--has-invalid-status错误码)。 -7. 再次重启 `tidb-lightning`。 - -## 如何校验导入的数据的正确性？ - -TiDB Lightning 默认会对导入数据计算校验和 (checksum)，如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。 - -TiDB 也支持从 MySQL 命令行运行 `ADMIN CHECKSUM TABLE` 指令来计算校验和。 - -{{< copyable "sql" >}} - -```sql -ADMIN CHECKSUM TABLE `schema`.`table`; -``` - -``` -+---------+------------+---------------------+-----------+-------------+ -| Db_name | Table_name | Checksum_crc64_xor | Total_kvs | Total_bytes | -+---------+------------+---------------------+-----------+-------------+ -| schema | table | 5505282386844578743 | 3 | 96 | -+---------+------------+---------------------+-----------+-------------+ -1 row in set (0.01 sec) -``` - -## TiDB Lightning 支持哪些格式的数据源？ - -TiDB Lightning 只支持两种格式的数据源： - -1. [Mydumper](/v3.0/reference/tools/mydumper.md) 生成的 SQL dump -2. 储存在本地文件系统的 [CSV](/v3.0/reference/tools/tidb-lightning/csv.md) 文件 - -## 我已经在下游创建好库和表了，TiDB Lightning 可以忽略建库建表操作吗？ - -可以。在配置文档中的 `[mydumper]` 部分将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。 - -## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入？ - -可以。Lightning 默认的 [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) 为 `"STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"`。 - -这个设置不允许一些非法的数值，例如 `1970-00-00` 这样的日期。可以修改配置文件 `[tidb]` 下的 `sql-mode` 值。 - -```toml -... -[tidb] -sql-mode = "" -... -``` - -## 可以启用一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？ - -只要每个 Lightning 操作的表互不相同就可以。 - -## 如何正确结束 `tikv-importer` 进程？ - -根据部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh`。 - -- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程 ID，然后通过 `kill «pid»` 结束进程。 - -## 如何正确结束 `tidb-lightning` 进程？ - -根据部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh`。 - -- 手动部署：如果 `tidb-lightning` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tidb-lightning` 获取进程 ID，然后通过 `kill -2 «pid»` 结束进程。 - -## `tidb-lightning` 在服务器上运行，进程莫名其妙地退出了，是怎么回事呢？ - -这种情况可能是启动方式不正确，导致收到 SIGHUP 信号而退出。此时 `tidb-lightning.log` 通常有如下日志： - -``` -[2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup] -``` - -不推荐在命令行中直接使用 `nohup` 启动进程，推荐[使用脚本启动 `tidb-lightning`](/v3.0/reference/tools/tidb-lightning/deployment.md)。 - -## 为什么用过 TiDB Lightning 之后，TiDB 集群变得又慢又耗 CPU？ - -如果 `tidb-lightning` 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)： - -{{< copyable "shell-regular" >}} - -```sh -tidb-lightning-ctl --switch-mode=normal -``` - -## TiDB Lightning 可以使用千兆网卡吗？ - -使用 TiDB Lightning 建议配置万兆网卡。**不推荐**使用千兆网卡，尤其是在部署 `tikv-importer` 的机器上。 - -千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。为了避免这种情况，你可以在 [`tikv-importer` 的配置文件](/v3.0/reference/tools/tidb-lightning/config.md#tikv-importer-配置参数)中**限制上传速度**。 - -```toml -[import] -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# 建议将该速度设为 100 MB/s 或更小。 -upload-speed-limit = "100MB" -``` - -## 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间？ - -当使用默认的 3 副本设置时，TiDB Lightning 需要 TiKV 集群预留数据源大小 6 倍的空间。多出来的 2 倍是算上下列没储存在数据源的因素的保守估计： - -- 索引会占据额外的空间 -- RocksDB 的空间放大效应 - -## TiDB Lightning 使用过程中是否可以重启 TiKV Importer？ - -不能，Importer 会在内存中存储一些引擎文件，Importer 重启后，`tidb-lightning` 会因连接失败而停止。此时，你需要[清除失败的断点](/v3.0/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-error-destroy)，因为这些 Importer 特有的信息丢失了。你可以在之后[重启 Lightning](#如何正确重启-tidb-lightning)。 - -## 如何清除所有与 TiDB Lightning 相关的中间数据？ - -1. 删除断点文件。 - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all - ``` - - 如果出于某些原因而无法运行该命令，你可以尝试手动删除 `/tmp/tidb_lightning_checkpoint.pb` 文件。 - -2. 删除 `tikv-importer` 所在机器上的整个 “import” 文件目录。 - -3. 如果需要的话，删除 TiDB 集群上创建的所有表和库。 diff --git a/v3.0/faq/tidb.md b/v3.0/faq/tidb.md deleted file mode 100755 index c171f3645fb5..000000000000 --- a/v3.0/faq/tidb.md +++ /dev/null @@ -1,1084 +0,0 @@ ---- -title: TiDB FAQ -category: FAQ -aliases: ['/docs-cn/FAQ/','/docs-cn/faq/tidb/'] ---- - -# FAQ - -## 一、 TiDB 介绍、架构、原理 - -### 1.1 TiDB 介绍及整体架构 - -#### 1.1.1 TiDB 整体架构 - -[TiDB 简介](/v3.0/overview.md#tidb-简介) - -#### 1.1.2 TiDB 是什么？ - -TiDB 是一个分布式 NewSQL 数据库。它支持水平弹性扩展、ACID 事务、标准 SQL、MySQL 语法和 MySQL 协议，具有数据强一致的高可用特性，是一个不仅适合 OLTP 场景还适合 OLAP 场景的混合数据库。 - -#### 1.1.3 TiDB 是基于 MySQL 开发的吗？ - -不是，虽然 TiDB 支持 MySQL 语法和协议，但是 TiDB 是由 PingCAP 团队完全自主开发的产品。 - -#### 1.1.4 TiDB、TiKV、Placement Driver (PD) 主要作用？ - -- TiDB 是 Server 计算层，主要负责 SQL 的解析、制定查询计划、生成执行器。 -- TiKV 是分布式 Key-Value 存储引擎，用来存储真正的数据，简而言之，TiKV 是 TiDB 的存储引擎。 -- PD 是 TiDB 集群的管理组件，负责存储 TiKV 的元数据，同时也负责分配时间戳以及对 TiKV 做负载均衡调度。 - -#### 1.1.5 TiDB 易用性如何？ - -TiDB 使用起来很简单，可以将 TiDB 集群当成 MySQL 来用，你可以将 TiDB 用在任何以 MySQL 作为后台存储服务的应用中，并且基本上不需要修改应用代码，同时你可以用大部分流行的 MySQL 管理工具来管理 TiDB。 - -#### 1.1.6 TiDB 和 MySQL 兼容性如何？ - -TiDB 目前还不支持触发器、存储过程、自定义函数、外键，除此之外，TiDB 支持绝大部分 MySQL 5.7 的语法。 - -详情参见[与 MySQL 兼容性对比](/v3.0/reference/mysql-compatibility.md)。 - -#### 1.1.7 TiDB 具备高可用的特性吗？ - -TiDB 天然具备高可用特性，TiDB、TiKV、PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。具体见 [TiDB 高可用性](/v3.0/key-features.md#高可用)。 - -#### 1.1.8 TiDB 数据是强一致的吗？ - -TiDB 实现了快照隔离 (Snapshot Isolation) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。 - -在底层，TiKV 使用复制日志 + 状态机 (State Machine) 的模型来复制数据。对于写入请求，数据被写入 Leader，然后 Leader 以日志的形式将命令复制到它的 Follower 中。当集群中的大多数节点收到此日志时，日志会被提交，状态机会相应作出变更。 - -#### 1.1.9 TiDB 支持分布式事务吗？ - -支持。无论是一个地方的几个节点，还是[跨多个数据中心的多个节点](/v3.0/how-to/deploy/geographic-redundancy/overview.md)，TiDB 均支持 ACID 分布式事务。 - -TiDB 事务模型灵感源自 Google Percolator 模型，主体是一个两阶段提交协议，并进行了一些实用的优化。该模型依赖于一个时间戳分配器，为每个事务分配单调递增的时间戳，这样就检测到事务冲突。在 TiDB 集群中，[PD](/v3.0/architecture.md#pd-server) 承担时间戳分配器的角色。 - -#### 1.1.10 TiDB 支持哪些编程语言？ - -只要支持 MySQL Client/Driver 的编程语言，都可以直接使用 TiDB。 - -#### 1.1.11 TiDB 是否支持其他存储引擎？ - -是的，除了 TiKV 之外，TiDB 还支持一些流行的单机存储引擎，比如 GolevelDB、RocksDB、BoltDB 等。如果一个存储引擎是支持事务的 KV 引擎，并且能提供一个满足 TiDB 接口要求的 Client，即可接入 TiDB。 - -#### 1.1.12 官方有没有三中心跨机房多活部署的推荐方案？ - -从 TiDB 架构来讲，支持真正意义上的跨中心异地多活，从操作层面讲，依赖数据中心之间的网络延迟和稳定性，一般建议延迟在 5ms 以下，目前我们已经有相似客户方案，具体请咨询官方 [info@pingcap.com](mailto:info@pingcap.com)。 - -#### 1.1.13 除了官方文档，有没有其他 TiDB 知识获取途径？ - -目前[官方文档](/v3.0/overview.md#tidb-简介)是获取 TiDB 相关知识最主要、最及时的发布途径。除此之外，我们也有一些技术沟通群，如有需求可发邮件至 [info@pingcap.com](mailto:info@pingcap.com) 获取。 - -#### 1.1.14 TiDB 对哪些 MySQL variables 兼容？ - -详细可参考[系统变量](/v3.0/reference/configuration/tidb-server/mysql-variables.md)。 - -#### 1.1.15 TiDB 是否支持 select for update？ - -支持，但语义上和 MySQL 有区别，TiDB 是分布式数据库，采用的乐观锁机制，也就说 select for update 不在事务开启就锁住数据，而是其他事务在提交的时候进行冲突检查，如有冲突，会进行回滚。 - -#### 1.1.16 TiDB 的 codec 能保证 UTF8 的字符串是 memcomparable 的吗？我们的 key 需要支持 UTF8，有什么编码建议吗？ - -TiDB 字符集默认就是 UTF8 而且目前只支持 UTF8，字符串就是 memcomparable 格式的。 - -#### 1.1.17 TiDB 用户名长度限制？ - -在 TiDB 中用户名最长为 32 字符。 - -#### 1.1.18 一个事务中的语句数量最大是多少？ - -一个事务中的语句数量，默认限制最大为 5000 条。 - -#### 1.1.19 TiDB 是否支持 XA？ - -虽然 TiDB 的 JDBC 驱动用的就是 MySQL JDBC（Connector / J），但是当使用 Atomikos 的时候，数据源要配置成类似这样的配置：`type="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"`。MySQL JDBC XADataSource 连接 TiDB 的模式目前是不支持的。MySQL JDBC 中配置好的 XADataSource 模式，只对 MySQL 数据库起作用（DML 去修改 redo 等）。 - -Atomikos 配好两个数据源后，JDBC 驱动都要设置成 XA 模式，然后 Atomikos 在操作 TM 和 RM（DB）的时候，会通过数据源的配置，发起带有 XA 指令到 JDBC 层，JDBC 层 XA 模式启用的情况下，会对 InnoDB（如果是 MySQL 的话）下发操作一连串 XA 逻辑的动作，包括 DML 去变更 redo log 等，就是两阶段递交的那些操作。TiDB 目前的引擎版本中，没有对上层应用层 JTA / XA 的支持，不解析这些 Atomikos 发过来的 XA 类型的操作。 - -MySQL 是单机数据库，只能通过 XA 来满足跨数据库事务，而 TiDB 本身就通过 Google 的 Percolator 事务模型支持分布式事务，性能稳定性比 XA 要高出很多，所以不会也不需要支持 XA。 - -#### 1.1.20 show processlist 是否显示系统进程号？ - -TiDB 的 `show processlist` 与 MySQL 的 `show processlist` 显示内容基本一样，不会显示系统进程号，而 ID 表示当前的 session ID。其中 TiDB 的 `show processlist` 和 MySQL 的 `show processlist` 区别如下： - -1）由于 TiDB 是分布式数据库，tidb-server 实例是无状态的 SQL 解析和执行引擎（详情可参考 [TiDB 整体架构](/v3.0/overview.md#tidb-整体架构)），用户使用 MySQL 客户端登录的是哪个 tidb-server，`show processlist` 就会显示当前连接的这个 tidb-server 中执行的 session 列表，不是整个集群中运行的全部 session 列表；而 MySQL 是单机数据库，`show processlist` 列出的是当前整个 MySQL 数据库的全部执行 SQL 列表。 - -2）TiDB 的 `show processlist` 显示内容比起 MySQL 来讲，多了一个当前 session 使用内存的估算值（单位 Byte）。 - -#### 1.1.21 如何修改用户名密码和权限？ - -TiDB 作为分布式数据库，在 TiDB 中修改用户密码建议使用 `set password for 'root'@'%' = '0101001';` 或 `alter` 方法，不推荐使用 `update mysql.user` 的方法进行，这种方法可能会造成其它节点刷新不及时的情况。修改权限也一样，都建议采用官方的标准语法。详情可参考 [TiDB 用户账户管理](/v3.0/reference/security/user-account-management.md)。 - -#### 1.1.22 TiDB 中，为什么出现后插入数据的自增 ID 反而小？ - -TiDB 的自增 ID (`AUTO_INCREMENT`) 只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。当多个线程并发往不同的 tidb-server 插入数据的时候，有可能会出现后插入的数据自增 ID 小的情况。此外，TiDB允许给整型类型的字段指定 AUTO_INCREMENT，且一个表只允许一个属性为 `AUTO_INCREMENT` 的字段。详情可参考[CREATE TABLE 语法](/v3.0/reference/mysql-compatibility.md#自增-id)。 - -#### 1.1.23 sql_mode 默认除了通过命令 set 修改，配置文件怎么修改？ - -TiDB 的 sql_mode 与 MySQL 的 sql_mode 设置方法有一些差别，TiDB 不支持配置文件配置设置数据库的 sql\_mode，而只能使用 set 命令去设置，具体方法为：`set @@global.sql_mode = 'STRICT_TRANS_TABLES';`。 - -#### 1.1.24 TiDB 支持哪些认证协议，过程是怎样的？ - -这一层跟 MySQL 一样，走的 SASL 认证协议，用于用户登录认证，对密码的处理流程。 - -客户端连接 TiDB 的时候，走的是 challenge-response（挑战-应答）的认证模式，过程如下： - -第一步：客户端连接服务器； - -第二步：服务器发送随机字符串 challenge 给客户端； - -第三步：客户端发送 username + response 给服务器； - -第四步：服务器验证 response。 - -### 1.2 TiDB 原理 - -#### 1.2.1 存储 TiKV - -##### 1.2.1.1 TiKV 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说存储](http://t.cn/RTKRRWv) - -#### 1.2.2 计算 TiDB - -##### 1.2.2.1 TiDB 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说计算](http://t.cn/RTKRkBh) - -#### 1.2.3 调度 PD - -##### 1.2.3.1 PD 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 谈调度](http://t.cn/RTKEZ0U) - -## 二、安装部署升级 - -### 2.1 环境准备 - -#### 2.1.1 操作系统版本要求 - -| **Linux 操作系统平台** | **版本** | -| --- | --- | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | - -##### 2.1.1.1 为什么要在 CentOS 7 上部署 TiDB 集群？ - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络，作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境，具体可以参考 TiDB 的[官方部署要求](/v3.0/how-to/deploy/hardware-recommendations.md)。其中 TiDB 在 CentOS 7.3 的环境下进行大量的测试，同时也有很多这个操作系统的部署最佳实践，因此，我们推荐客户在部署 TiDB 的时候使用 CentOS 7.3+ 以上的Linux 操作系统。 - -#### 2.1.2 硬件要求 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -##### 2.1.2.1 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | -| | | | | 服务器总计 | 4 | - -##### 2.1.2.2 线上环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 48 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 8核+ | 16 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 48 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | -| | | | | 服务器总计 | 9 | - -##### 2.1.2.3 2 块网卡的目的是？万兆的目的是？ - -作为一个分布式集群，TiDB 对时间的要求还是比较高的，尤其是 PD 需要分发唯一的时间戳，如果 PD 时间不统一，如果有 PD 切换，将会等待更长的时间。2 块网卡可以做 bond，保证数据传输的稳定，万兆可以保证数据传输的速度，千兆网卡容易出现瓶颈，我们强烈建议使用万兆网卡。 - -##### 2.1.2.4 SSD 不做 RAID 是否可行？ - -资源可接受的话，我们建议做 RAID 10，如果资源有限，也可以不做 RAID。 - -##### 2.1.2.5 TiDB 集群各个组件的配置推荐？ - -- TiDB 需要 CPU 和内存比较好的机器，参考官网配置要求，如果后期需要开启 Binlog，根据业务量的评估和 GC 时间的要求，也需要本地磁盘大一点，不要求 SSD 磁盘； -- PD 里面存了集群元信息，会有频繁的读写请求，对磁盘 I/O 要求相对比较高，磁盘太差会影响整个集群性能，推荐 SSD 磁盘，空间不用太大。另外集群 Region 数量越多对 CPU、内存的要求越高； -- TiKV 对 CPU、内存、磁盘要求都比较高，一定要用 SSD 磁盘。 - -详情可参考 [TiDB 软硬件环境需求](/v3.0/how-to/deploy/hardware-recommendations.md)。 - -### 2.2 安装部署 - -#### 2.2.1 Ansible 部署方式（强烈推荐） - -详细可参考[使用 TiDB Ansible 部署 TiDB 集群](/v3.0/how-to/deploy/orchestrated/ansible.md)。 - -##### 2.2.1.1 为什么修改了 TiKV/PD 的 toml 配置文件，却没有生效？ - -这种情况一般是因为没有使用 `--config` 参数来指定配置文件（目前只会出现在 binary 部署的场景），TiKV/PD 会按默认值来设置。如果要使用配置文件，请设置 TiKV/PD 的 `--config` 参数。对于 TiKV 组件，修改配置后重启服务即可；对于 PD 组件，只会在第一次启动时读取配置文件，之后可以使用 pd-ctl 的方式来修改配置，详情可参考 [PD 配置参数](/v3.0/reference/configuration/pd-server/configuration.md)。 - -##### 2.2.1.2 TiDB 监控框架 Prometheus + Grafana 监控机器建议单独还是多台部署？ - -监控机建议单独部署。建议 CPU 8 core，内存 16 GB 以上，硬盘 500 GB 以上。 - -##### 2.2.1.3 有一部分监控信息显示不出来？ - -查看访问监控的机器时间跟集群内机器的时间差，如果比较大，更正时间后即可显示正常。 - -##### 2.2.1.4 supervise/svc/svstat 服务具体起什么作用？ - -- supervise 守护进程 -- svc 启停服务 -- svstat 查看进程状态 - -##### 2.2.1.5 inventory.ini 变量参数解读 - -| **变量** | **含义** | -| --- | --- | -| cluster_name | 集群名称，可调整 | -| tidb_version | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| deployment_method | 部署方式，默认为 binary，可选 docker | -| process_supervision | 进程监管方式，默认为 systemd，可选 supervise | -| timezone | 修改部署目标机器时区，默认为 Asia/Shanghai, 可调整，与set_timezone 变量结合使用 | -| set_timezone | 默认为 True，即修改部署目标机器时区，关闭可修改为 False | -| enable_elk | 目前不支持，请忽略 | -| enable_firewalld | 开启防火墙，默认不开启 | -| enable_ntpd | 检测部署目标机器 NTP 服务，默认为 True，请勿关闭 | -| machine_benchmark | 检测部署目标机器磁盘 IOPS，默认为 True，请勿关闭 | -| set_hostname | 根据 IP 修改部署目标机器主机名，默认为 False | -| enable_binlog | 是否部署 pump 并开启 binlog，默认为 False，依赖 Kafka 集群，参见 zookeeper_addrs 变量 | -| zookeeper_addrs | binlog Kafka 集群的 zookeeper 地址 | -| enable_slow_query_log | TiDB 慢查询日志记录到单独文件({{ deploy_dir }}/log/tidb_slow_query.log)，默认为 False，记录到 tidb 日志 | -| deploy_without_tidb | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 inventory.ini 文件中 tidb_servers 主机组 IP 设置为空。 | - -#### 2.2.2 TiDB 离线 Ansible 部署方案 - -首先这不是我们建议的方式，如果中控机没有外网，也可以通过离线 Ansible 部署方式，详情可参考[离线 TiDB Ansible 部署方案](/v3.0/how-to/deploy/orchestrated/offline-ansible.md)。 - -#### 2.2.3 Docker Compose 快速构建集群（单机部署） - -使用 docker-compose 在本地一键拉起一个集群，包括集群监控，还可以根据需求自定义各个组件的软件版本和实例个数，以及自定义配置文件，这种只限于开发环境，详细可参考[官方文档](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -#### 2.2.4 如何单独记录 TiDB 中的慢查询日志，如何定位慢查询 SQL？ - -1）TiDB 中，对慢查询的定义在 tidb-ansible 的 `conf/tidb.yml` 配置文件中，`slow-threshold: 300`，这个参数是配置慢查询记录阈值的，单位是 ms。 - -慢查询日志默认记录到 tidb.log 中，如果希望生成单独的慢查询日志文件，修改 inventory.ini 配置文件的参数 `enable_slow_query_log` 为 True。 - -如上配置修改之后，需要执行 `ansible-playbook rolling_update.yml --tags=tidb`，对 tidb-server 实例进行滚动升级，升级完成后，tidb-server 将在 `tidb_slow_query.log` -文件中记录慢查询日志。 - -2）如果出现了慢查询，可以从 Grafana 监控定位到出现慢查询的 tidb-server 以及时间点，然后在对应节点查找日志中记录的 SQL 信息。 - -3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md#admin-show-slow-命令)。 - -#### 2.2.5 首次部署 TiDB 集群时，没有配置 tikv 的 Label 信息，在后续如何添加配置 Label？ - -TiDB 的 Label 设置是与集群的部署架构相关的，是集群部署中的重要内容，是 PD 进行全局管理和调度的依据。如果集群在初期部署过程中没有设置 Label，需要在后期对部署结构进行调整，就需要手动通过 PD 的管理工具 pd-ctl 来添加 location-labels 信息，例如：`config set location-labels "zone,rack,host"`（根据实际的 label 层级名字配置）。 - -pd-ctl 的使用参考 [PD Control 使用说明](/v3.0/reference/tools/pd-control.md)。 - -#### 2.2.6 为什么测试磁盘的 dd 命令用 oflag=direct 这个选项？ - -Direct 模式就是把写入请求直接封装成 I/O 指令发到磁盘，这样是为了绕开文件系统的缓存，可以直接测试磁盘的真实的 I/O 读写能力。 - -#### 2.2.7 如何用 fio 命令测试 TiKV 实例的磁盘性能？ - -- 随机读测试： - - {{< copyable "shell-regular" >}} - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randread -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json - ``` - -- 顺序写和随机读混合测试： - - {{< copyable "shell-regular" >}} - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randrw -percentage_random=100,0 -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json - ``` - -#### 2.2.8 使用 TiDB Ansible 部署 TiDB 集群的时候，遇到 `UNREACHABLE! "msg": "Failed to connect to the host via ssh: "` 报错是什么原因？ - -有两种可能性： - -- ssh 互信的准备工作未做好，建议严格参照我们的[官方文档步骤](/v3.0/how-to/deploy/orchestrated/ansible.md)配置互信，并使用命令 `ansible -i inventory.ini all -m shell -a 'whoami' -b` 来验证互信配置是否成功。 - -- 如果涉及到单服务器分配了多角色的场景，例如多组件混合部署或单台服务器部署了多个 TiKV 实例，可能是由于 ssh 复用的机制引起这个报错，可以使用 `ansible … -f 1` 的选项来规避这个报错。 - -### 2.3 升级 - -#### 2.3.1 如何使用 Ansible 滚动升级？ - -滚动升级 TiKV 节点( 只升级单独服务 ) - -`ansible-playbook rolling_update.yml --tags=tikv` - -滚动升级所有服务 - -`ansible-playbook rolling_update.yml` - -#### 2.3.2 滚动升级有那些影响? - -滚动升级 TiDB 服务，滚动升级期间不影响业务运行，需要配置最小集群拓扑（TiDB \* 2、PD \* 3、TiKV \* 3），如果集群环境中有 Pump/Drainer 服务，建议先停止 Drainer 后滚动升级（升级 TiDB 时会升级 Pump）。 - -#### 2.3.3 Binary 如何升级？ - -Binary 不是我们建议的安装方式，对升级支持也不友好，建议换成 Ansible 部署。 - -#### 2.3.4 一般升级选择升级 TiKV 还是所有组件都升级？ - -常规需要一起升，因为整个版本都是一起测试的，单独升级只限当发生一个紧急故障时，需要单独对一个有问题的角色做升级。 - -#### 2.3.5 启动集群或者升级集群过程中出现 “Timeout when waiting for search string 200 OK” 是什么原因？如何处理？ - -可能有以下几种原因：进程没有正常启动；端口被占用；进程没有正常停掉；停掉集群的情况下使用 rolling_update.yml 来升级集群（操作错误）。 - -处理方式：登录到相应节点查看进程或者端口的状态；纠正错误的操作步骤。 - -## 三、集群管理 - -### 3.1 集群日常管理 - -#### 3.1.1 Ansible 常见运维操作有那些？ - -| **任务** | **Playbook** | -| --- | --- | -| 启动集群 | ansible-playbook start.yml | -| 停止集群 | ansible-playbook stop.yml | -| 销毁集群 | ansible-playbook unsafe\_cleanup.yml (若部署目录为挂载点，会报错，可忽略） | -| 清除数据(测试用) | ansible-playbook cleanup\_data.yml | -| 滚动升级 | ansible-playbook rolling\_update.yml | -| 滚动升级 TiKV | ansible-playbook rolling\_update.yml --tags=tikv | -| 滚动升级除 PD 外模块 | ansible-playbook rolling\_update.yml --skip-tags=pd | -| 滚动升级监控组件 | ansible-playbook rolling\_update\_monitor.yml | - -#### 3.1.2 TiDB 如何登录？ - -和 MySQL 登录方式一样，可以按照下面例子进行登录。 - -`mysql -h 127.0.0.1 -uroot -P4000` - -#### 3.1.3 TiDB 如何修改数据库系统变量？ - -和 MySQL 一样，TiDB 也分为静态参数和固态参数，静态参数可以直接通过`set global xxx = n`的方式进行修改，不过新参数值只限于该实例生命周期有效。 - -#### 3.1.4 TiDB (TiKV) 有哪些数据目录？ - -默认在 [`--data-dir`](/v3.0/reference/configuration/tikv-server/configuration.md#--data-dir) 目录下，其中包括 backup、db、raft、snap 四个目录，分别存储备份、数据、raft 数据及镜像数据。 - -#### 3.1.5 TiDB 有哪些系统表？ - -和 MySQL 类似，TiDB 中也有系统表，用于存放数据库运行时所需信息，具体信息参考 [TiDB 系统数据库](/v3.0/reference/system-databases/mysql.md)文档。 - -#### 3.1.6 TiDB 各节点服务器下是否有日志文件，如何管理？ - -默认情况下各节点服务器会在日志中输出标准错误，如果启动的时候通过 `--log-file` 参数指定了日志文件，那么日志会输出到指定的文件中，并且按天做 rotation。 - -#### 3.1.7 如何规范停止 TiDB？ - -如果是用 Ansible 部署的，可以使用 `ansible-playbook stop.yml` 命令停止 TiDB 集群。如果不是 Ansible 部署的，可以直接 kill 掉所有服务。如果使用 kill 命令，TiDB 的组件会做 graceful 的 shutdown。 - -#### 3.1.8 TiDB 里面可以执行 kill 命令吗？ - -- 可以 kill DML 语句，首先使用 `show processlist`，找到对应 session 的 id，然后执行 `kill tidb [session id]`。 -- 可以 kill DDL 语句，首先使用 `admin show ddl jobs`，查找需要 kill 的 DDL job ID，然后执行 `admin cancel ddl jobs 'job_id' [, 'job_id'] ...`。具体可以参考 [admin 操作](/v3.0/reference/sql/statements/admin.md)。 - -#### 3.1.9 TiDB 是否支持会话超时？ - -TiDB 暂不支持数据库层面的会话超时，目前想要实现超时，在没 LB（Load Balancing）的时候，需要应用侧记录发起的 Session 的 ID，通过应用自定义超时，超时以后需要到发起 Query 的节点上用 `kill tidb [session id]` 来杀掉 SQL。目前建议使用应用程序来实现会话超时，当达到超时时间，应用层就会抛出异常继续执行后续的程序段。 - -#### 3.1.10 TiDB 生产环境的版本管理策略是怎么样的？如何尽可能避免频繁升级？ - -TiDB 版本目前逐步标准化，每次 Release 都包含详细的 Change log，版本功能[变化详情](https://github.com/pingcap/TiDB/releases)，生产环境是否有必要升级取决于业务系统，建议升级之前详细了解前后版本的功能差异。 - -版本号说明参考：Release Version: `v1.0.3-1-ga80e796` - -- `v1.0.3` 表示 GA 标准版 -- `1` 表示该版本 commit 1 次 -- `ga80e796` 代表版本的 `git-hash` - -#### 3.1.11 分不清 TiDB master 版本之间的区别，经常用错 TiDB Ansible 版本? - -TiDB 目前社区非常活跃，在 1.0 GA 版本发布后，还在不断的优化和修改 BUG，因此 TiDB 的版本更新周期比较快，会不定期有新版本发布，请关注我们的[新版本发布官方网站](https://pingcap.com/weekly/)。此外 TiDB 安装推荐使用 TiDB Ansible 进行安装，TiDB Ansible 的版本也会随着 TiDB 的版本发布进行更新，因此建议用户在安装升级新版本的时候使用最新的 TiDB Ansible 安装包版本进行安装。此外，在 TiDB 1.0 GA 版本后，对 TiDB 的版本号进行了统一管理，TiDB 的版本可以通过以下两种方式进行查看： - -- 通过 `select tidb_version()` 进行查看 -- 通过执行 `tidb-server -V` 进行查看 - -#### 3.1.12 有没有图形化部署 TiDB 的工具？ - -暂时没有。 - -#### 3.1.13 TiDB 如何进行水平扩展？ - -当您的业务不断增长时，数据库可能会面临三方面瓶颈，第一是存储空间，第二是计算资源，第三是读写容量，这时可以对 TiDB 集群做水平扩展。 - -- 如果是存储资源不够，可以通过添加 TiKV Server 节点来解决，新节点启动后，PD 会自动将其他节点的部分数据迁移过去，无需人工介入。 -- 如果是计算资源不够，可以查看 TiDB Server 和 TiKV Server 节点的 CPU 消耗情况，再考虑添加 TiDB Server 节点或者是 TiKV Server 节点来解决，如添加 TiDB Server 节点，将其添加到前端 Load Balancer 配置之中即可。 -- 如果是容量跟不上，一般可以考虑同时增加 TiDB Server 和 TiKV Server 节点。 - -#### 3.1.14 Percolator 用了分布式锁，crash 的客户端会保持锁，会造成锁没有 release？ - -详细可参考 [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/)。 - -#### 3.1.15 TiDB 为什么选用 gRPC 而不选用 Thrift，是因为 Google 在用吗？ - -不只是因为 Google 在用，有一些比较好的特性我们需要，比如流控、加密还有 Streaming。 - -#### 3.1.16 like(bindo.customers.name, jason%, 92) 这个92代表什么？ - -那个是转义字符，默认是 (ASCII 92)。 - -#### 3.1.17 为什么 `information_schema.tables.data_length` 记录的大小和 TiKV 监控面板上的 store size 不一样？ - -这是因为两者计算的角度不一样。`information_schema.tables.data_length` 是通过统计信息（平均每行的大小）得到的估算值。TiKV 监控面板上的 store size 是单个 TiKV 实例的数据文件（RocksDB 的 SST 文件）的大小总和。由于多版本和 TiKV 会压缩数据，所以两者显示的大小不一样。 - -### 3.2 PD 管理 - -#### 3.2.1 访问 PD 报错：TiKV cluster is not bootstrapped - -PD 的大部分 API 需要在初始化 TiKV 集群以后才能使用，如果在部署新集群的时候只启动了 PD，还没有启动 TiKV，这时候访问 PD 就会报这个错误。遇到这个错误应该先把要部署的 TiKV 启动起来，TiKV 会自动完成初始化工作，然后就可以正常访问 PD。 - -#### 3.2.2 PD 启动报错：etcd cluster ID mismatch - -PD 启动参数中的 `--initial-cluster` 包含了某个不属于该集群的成员。遇到这个错误时请检查各个成员的所属集群，剔除错误的成员后即可正常启动。 - -#### 3.2.3 PD 能容忍的时间同步误差是多少？ - -理论上，时间同步误差越小越好。PD 可容忍任意时长的误差，但是，时间同步误差越大意味着 PD 分配的时间戳与真实的物理时间相差越大，这个差距会影响读历史版本等功能。 - -#### 3.2.4 Client 连接是如何寻找 PD 的？ - -Client 连接只能通过 TiDB 访问集群，TiDB 负责连接 PD 与 TiKV，PD 与 TiKV 对 Client 透明。当 TiDB 连接任意一台 PD 的时候，PD 会告知 TiDB 当前的 leader 是谁，如果此台 PD 不是 leader，TiDB 将会重新连接至 leader PD。 - -#### 3.2.5 PD 参数中 leader-schedule-limit 和 region-schedule-limit 调度有什么区别？ - -- leader-schedule-limit 调度是用来均衡不同 TiKV 的 leader 数，影响处理查询的负载。 -- region-schedule-limit 调度是均衡不同 TiKV 的副本数，影响不同节点的数据量。 - -#### 3.2.6 每个 region 的 replica 数量可配置吗？调整的方法是？ - -可以，目前只能调整全局的 replica 数量。首次启动时 PD 会读配置文件（conf/pd.yml），使用其中的 max-replicas 配置，之后修改需要使用 pd-ctl 配置命令 `config set max-replicas $num`，配置后可通过 `config show all` 来查看已生效的配置。调整的时候，不会影响业务，会在后台添加，注意总 TiKV 实例数总是要大于等于设置的副本数，例如 3 副本需要至少 3 个 TiKV。增加副本数量之前需要预估额外的存储需求。pd-ctl 的详细用法可参考 [PD Control 使用说明](/v3.0/reference/tools/pd-control.md)。 - -#### 3.2.7 缺少命令行集群管理工具，整个集群的健康度当前是否正常，不好确认？ - -可以通过 pd-ctl 等工具来判断集群大概的状态，详细的集群状态还是需要通过监控来确认。 - -#### 3.2.8 集群下线节点后，怎么删除老集群节点监控信息？ - -下线节点一般指 TiKV 节点通过 pd-ctl 或者监控判断节点是否下线完成。节点下线完成后，手动停止下线节点上相关的服务。从 Prometheus 配置文件中删除对应节点的 node_exporter 信息。从 Ansible inventory.ini 中删除对应节点的信息。 - -#### 3.2.9 使用 PD Control 连接 PD Server 时，为什么只能通过本机 IP 连接，不能通过 127.0.0.1 连接？ - -因为使用 TiDB Ansible 部署的集群，PD 对外服务端口不会绑定到 127.0.0.1，所以 PD Control 不会识别 127.0.0.1。 - -### 3.3 TiDB server 管理 - -#### 3.3.1 TiDB 的 lease 参数应该如何设置？ - -启动 TiDB Server 时，需要通过命令行参数设置 lease 参数（--lease=60），其值会影响 DDL 的速度（只会影响当前执行 DDL 的 session，其他的 session 不会受影响）。在测试阶段，lease 的值可以设为 1s，加快测试进度；在生产环境下，我们推荐这个值设为分钟级（一般可以设为 60），这样可以保证 DDL 操作的安全。 - -#### 3.3.2 DDL 在正常情况下的耗时是多少？ - -一般情况下处理一个 DDL 操作（之前没有其他 DDL 操作在处理）的耗时基本可以分如下为三种： - -- add index 操作，且此操作对应表数据行数比较少，耗时约为 3s。 -- add index 操作，且此操作对应表数据行数比较多，耗时具体由表中数据行数和当时 QPS 情况定（add index 操作优先级比一般 SQL 低）。 -- 其他 DDL 操作耗时约为 1s。 - -此外，如果接收 DDL 请求的 TiDB 和 DDL owner 所处的 TiDB 是一台，那么上面列举的第一和第三种可能的耗时应该在几十到几百毫秒。 - -#### 3.3.3 为什么有的时候执行 DDL 会很慢？ - -可能原因如下： - -- 多个 DDL 语句一起执行的时候，后面的几个 DDL 语句会比较慢。原因是当前 TiDB 集群中 DDL 操作是串行执行的。 -- 在正常集群启动后，第一个 DDL 操作的执行时间可能会比较久，一般在 30s 左右，这个原因是刚启动时 TiDB 在竞选处理 DDL 的 leader。 -- 由于停 TiDB 时不能与 PD 正常通信（包括停电情况）或者用 `kill -9` 指令停 TiDB 导致 TiDB 没有及时从 PD 清理注册数据，那么会影响 TiDB 启动后 10min 内的 DDL 语句处理时间。这段时间内运行 DDL 语句时，每个 DDL 状态变化都需要等待 2 * lease（默认 lease = 45s）。 -- 当集群中某个 TiDB 与 PD 之间发生通信问题，即 TiDB 不能从 PD 及时获取或更新版本信息，那么这时候 DDL 操作的每个状态处理需要等待 2 * lease。 - -#### 3.3.4 TiDB 可以使用 S3 作为后端存储吗？ - -不可以，目前 TiDB 只支持分布式存储引擎和 GolevelDB/RocksDB/BoltDB 引擎。 - -#### 3.3.5 Information_schema 能否支持更多真实信息？ - -Information_schema 库里面的表主要是为了兼容 MySQL 而存在，有些第三方软件会查询里面的信息。在目前 TiDB 的实现中，里面大部分只是一些空表。后续随着 TiDB 的升级，会提供更多的参数信息。当前 TiDB 支持的 Information\_schema 请参考 [TiDB 系统数据库说明文档](/v3.0/reference/system-databases/information-schema.md)。 - -#### 3.3.6 TiDB Backoff type 主要原因? - -TiDB-server 与 TiKV-server 随时进行通信，在进行大量数据操作过程中，会出现 `Server is busy` 或者 `backoff.maxsleep 20000ms` 的日志提示信息，这是由于 TiKV-server 在处理过程中系统比较忙而出现的提示信息，通常这时候可以通过系统资源监控到 TiKV 主机系统资源使用率比较高的情况出现。如果这种情况出现，可以根据资源使用情况进行相应的扩容操作。 - -#### 3.3.7 TiDB TiClient type 主要原因？ - -TiClient Region Error 该指标描述的是在 TiDB-server 作为客户端通过 KV 接口访问 TiKV-server 进行数据操作过程中，TiDB-server 操作 TiKV-server 中的 Region 数据出现的错误类型与 metric 指标，错误类型包括 not_leader、stale_epoch。出现这些错误的情况是当 TiDB-server 根据自己的缓存信息去操作 Region leader 数据的时候，Region leader 发生了迁移或者 TiKV 当前的 Region 信息与 TiDB 缓存的路由信息不一致而出现的错误提示。一般这种情况下，TiDB-server 都会自动重新从 PD 获取最新的路由数据，重做之前的操作。 - -#### 3.3.8 TiDB 同时支持的最大并发连接数？ - -当前版本 TiDB 没有最大连接数的限制，如果并发过大导致响应时间增加，可以通过增加 TiDB 节点进行扩容。 - -#### 3.3.9 如何查看某张表创建的时间？ - -information_schema 库中的 tables 表里的 create_time 即为表的真实创建时间。 - -#### 3.3.9 TiDB 的日志中 EXPENSIVE_QUERY 是什么意思？ - -TiDB 在执行 SQL 时，预估出来每个 operator 处理了超过 10000 条数据就认为这条 query 是 expensive query。可以通过修改 tidb-server 配置参数来对这个门限值进行调整，调整后需要重新启动 tidb-server。 - -#### 3.3.10 在 TiDB 中如何控制或改变 SQL 提交的执行优先级？ - -TiDB 支持改变 [per-session](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_force_priority)、[全局](/v3.0/reference/configuration/tidb-server/configuration-file.md#force-priority)或单个语句的优先级。优先级包括： - -- HIGH_PRIORITY：该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句 -- LOW_PRIORITY：该语句为低优先级语句，TiDB 在执行阶段会降低这条语句的优先级 - -以上两种参数可以结合 TiDB 的 DML 语言进行使用，使用方法举例如下： - -1. 通过在数据库中写 SQL 的方式来调整优先级： - - {{< copyable "sql" >}} - - ```sql - select HIGH_PRIORITY | LOW_PRIORITY count(*) from table_name; - insert HIGH_PRIORITY | LOW_PRIORITY into table_name insert_values; - delete HIGH_PRIORITY | LOW_PRIORITY from table_name; - update HIGH_PRIORITY | LOW_PRIORITY table_reference set assignment_list where where_condition; - replace HIGH_PRIORITY | LOW_PRIORITY into table_name; - ``` - -2. 全表扫会自动调整为低优先级，analyze 也是默认低优先级。 - -#### 3.3.11 在 TiDB 中 auto analyze 的触发策略是怎样的？ - -触发策略：新表达到 1000 条，并且在 1 分钟内没有写入，会自动触发。 - -当表的（修改数/当前总行数）大于 `tidb_auto_analyze_ratio` 的时候，会自动触发 `analyze` 语句。`tidb_auto_analyze_ratio` 的默认值为 0.5，即默认开启此功能。为了保险起见，在开启此功能的时候，保证了其最小值为 0.3。但是不能大于等于 `pseudo-estimate-ratio`（默认值为 0.8），否则会有一段时间使用 pseudo 统计信息，建议设置值为 0.5。 - -#### 3.3.12 SQL 中如何通过 hint 使用一个具体的 index？ - -同 MySQL 的用法一致，例如： -`select column_name from table_name use index（index_name）where where_condition;` - -#### 3.3.13 触发 Information schema is changed 错误的原因？ - -TiDB 在执行 SQL 语句时，会使用当时的 `schema` 来处理该 SQL 语句，而且 TiDB 支持在线异步变更 DDL。那么，在执行 DML 的时候可能有 DDL 语句也在执行，而你需要确保每个 SQL 语句在同一个 `schema` 上执行。所以当执行 DML 时，遇到正在执行中的 DDL 操作就可能会报 `Information schema is changed` 的错误。为了避免太多的 DML 语句报错，已做了一些优化。 - -现在会报此错的可能原因如下（后两个报错原因与表无关）： - -- 执行的 DML 语句中涉及的表和集群中正在执行的 DDL 的表有相同的，那么这个 DML 语句就会报此错。 -- 这个 DML 执行时间很久，而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 1024（v3.0.5 版本之前此值为定值 100。v3.0.5 及之后版本默认值为 1024，可以通过 `tidb_max_delta_schema_count` 变量修改）。 -- 接受 DML 请求的 TiDB 长时间不能加载到 `schema information`（TiDB 与 PD 或 TiKV 之间的网络连接故障等会导致此问题），而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 100。 - -> **注意：** -> -> + 目前 TiDB 未缓存所有的 `schema` 版本信息。 -> + 对于每个 DDL 操作，`schema` 版本变更的数量与对应 `schema state` 变更的次数一致。 -> + 不同的 DDL 操作版本变更次数不一样。例如，`create table` 操作会有 1 次 `schema` 版本变更；`add column` 操作有 4 次 `schema` 版本变更。 - -#### 3.3.14 触发 Information schema is out of date 错误的原因？ - -当执行 DML 时，TiDB 超过一个 DDL lease 时间（默认 45s）没能加载到最新的 schema 就可能会报 `Information schema is out of date` 的错误。遇到此错的可能原因如下： - -- 执行此 DML 的 TiDB 被 kill 后准备退出，且此 DML 对应的事务执行时间超过一个 DDL lease，在事务提交时会报这个错误。 -- TiDB 在执行此 DML 时，有一段时间内连不上 PD 或者 TiKV，导致 TiDB 超过一个 DDL lease 时间没有 load schema，或者导致 TiDB 断开与 PD 之间带 keep alive 设置的连接。 - -#### 3.3.15 高并发情况下执行 DDL 时报错的原因？ - -高并发情况下执行 DDL（比如批量建表）时，极少部分 DDL 可能会由于并发执行时 key 冲突而执行失败。 - -并发执行 DDL 时，建议将 DDL 数量保持在 20 以下，否则你需要在应用端重试失败的 DDL 语句。 - -### 3.4 TiKV 管理 - -#### 3.4.1 TiKV 集群副本建议配置数量是多少，是不是最小高可用配置（3个）最好？ - -如果是测试环境 3 副本足够；在生产环境中，不可让集群副本数低于 3，需根据架构特点、业务系统及恢复能力的需求，适当增加副本数。值得注意的是，副本升高，性能会有下降，但是安全性更高。 - -#### 3.4.2 TiKV 启动报错：cluster ID mismatch - -TiKV 本地存储的 cluster ID 和指定的 PD 的 cluster ID 不一致。在部署新的 PD 集群的时候，PD 会随机生成一个 cluster ID，TiKV 第一次初始化的时候会从 PD 获取 cluster ID 存储在本地，下次启动的时候会检查本地的 cluster ID 与 PD 的 cluster ID 是否一致，如果不一致则会报错并退出。出现这个错误一个常见的原因是，用户原先部署了一个集群，后来把 PD 的数据删除了并且重新部署了新的 PD，但是 TiKV 还是使用旧的数据重启连到新的 PD 上，就会报这个错误。 - -#### 3.4.3 TiKV 启动报错：duplicated store address - -启动参数中的地址已经被其他的 TiKV 注册在 PD 集群中了。造成该错误的常见情况：TiKV `--data-dir` 指定的路径下没有数据文件夹（删除或移动后没有更新 --data-dir），用之前参数重新启动该 TiKV。请尝试用 pd-ctl 的 [store delete](https://github.com/pingcap/pd/tree/55db505e8f35e8ab4e00efd202beb27a8ecc40fb/tools/pd-ctl#store-delete--label--weight-store_id----jqquery-string) 功能，删除之前的 store，然后重新启动 TiKV 即可。 - -#### 3.4.4 TiKV master 和 slave 用的是一样的压缩算法，为什么效果不一样? - -目前来看 master 有些文件的压缩率会高一些，这个取决于底层数据的分布和 RocksDB 的实现，数据大小偶尔有些波动是正常的，底层存储引擎会根据需要调整数据。 - -#### 3.4.5 TiKV block cache 有哪些特性？ - -TiKV 使用了 RocksDB 的 Column Family (CF) 特性，KV 数据最终存储在默认 RocksDB 内部的 default、write、lock 3 个 CF 内。 - -- default CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中。 -- write CF 存储的是数据的版本信息（MVCC）、索引、小表相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中。 -- lock CF 存储的是锁信息，系统使用默认参数。 -- Raft RocksDB 实例存储 Raft log。default CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 -- 所有 CF 共享一个 Block-cache，用于缓存数据块，加速 RocksDB 的读取速度，Block-cache 的大小通过参数 `block-cache-size` 控制，`block-cache-size` 越大，能够缓存的热点数据越多，对读取操作越有利，同时占用的系统内存也会越多。 -- 每个 CF 有各自的 Write-buffer，大小通过 `write-buffer-size` 控制。 - -#### 3.4.6 TiKV channel full 是什么原因？ - -- Raftstore 线程太忙，或者因 I/O 而卡住。可以看一下 Raftstore 的 CPU 使用情况。 -- TiKV 过忙（CPU、磁盘 I/O 等），请求处理不过来。 - -#### 3.4.7 TiKV 频繁切换 Region leader 是什么原因？ - -- 网络问题导致节点间通信卡了，查看 Report failures 监控。 -- 原主 Leader 的节点卡了，导致没有及时给 Follower 发送消息。 -- Raftstore 线程卡了。 - -#### 3.4.8 如果一个节点挂了会影响服务吗？影响会持续多久？ - -TiDB 使用 Raft 在多个副本之间做数据同步（默认为每个 Region 3 个副本）。当一份备份出现问题时，其他的副本能保证数据的安全。根据 Raft 协议，当某个节点挂掉导致该节点里的 Leader 失效时，在最大 2 * lease time（leasetime 是 10 秒）时间后，通过 Raft 协议会很快将一个另外一个节点里的 Follower 选为新的 Region Leader 来提供服务。 - -#### 3.4.9 TiKV 在分别在那些场景下占用大量 IO、内存、CPU（超过参数配置的多倍）？ - -在大量写入、读取的场景中会占用大量的磁盘 IO、内存、CPU。在执行很复杂的查询，比如会产生很大中间结果集的情况下，会消耗很多的内存和 CPU 资源。 - -#### 3.4.10 TiKV 是否可以使用 SAS/SATA 盘或者进行 SSD/SAS 混合部署？ - -不可以使用，TiDB 在进行 OLTP 场景中，数据访问和操作需要高 IO 磁盘的支持，TiDB 作为强一致的分布式数据库，存在一定的写放大，如副本复制、存储底层 Compaction，因此，TiDB 部署的最佳实践中推荐用户使用 NVMe SSD 磁盘作为数据存储磁盘。另外，TiKV 与 PD 不能混合部署。 - -#### 3.4.11 数据表 Key 的 Range 范围划分是在数据接入之前就已经划分好了吗？ - -不是的，这个和 MySQL 分表规则不一样，需要提前设置好，TiKV 是根据 Region 的大小动态分裂的。 - -#### 3.4.12 Region 是如何进行分裂的？ - -Region 不是前期划分好的，但确实有 Region 分裂机制。当 Region 的大小超过参数 `region-max-size` 或 `region-max-keys` 的值时，就会触发分裂，分裂后的信息会汇报给 PD。 - -#### 3.4.13 TiKV 是否有类似 MySQL 的 `innodb_flush_log_trx_commit` 参数，来保证提交数据不丢失？ - -是的，TiKV 单机的存储引擎目前使用两个 RocksDB 实例，其中一个存储 raft-log，TiKV 有个 sync-log 参数，在 ture 的情况下，每次提交都会强制刷盘到 raft-log，如果发生 crash 后，通过 raft-log 进行 KV 数据的恢复。 - -#### 3.4.14 对 WAL 存储有什么推荐的硬件配置，例如 SSD，RAID 级别，RAID 卡 cache 策略，NUMA 设置，文件系统选择，操作系统的 IO 调度策略等？ - -WAL 属于顺序写，目前我们并没有单独对他进行配置，建议 SSD，RAID 如果允许的话，最好是 RAID 10，RAID 卡 cache、操作系统 I/O 调度目前没有针对性的最佳实践，Linux 7 以上默认配置即可，NUMA 没有特别建议，NUMA 内存分配策略可以尝试使用 `interleave = all`，文件系统建议 ext4。 - -#### 3.4.15 在最严格的 `sync-log = true` 数据可用模式下，写入性能如何？ - -一般来说，开启 `sync-log` 会让性能损耗 30% 左右。关闭 `sync-log` 时的性能表现，请参见 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 - -#### 3.4.16 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠，单机存储引擎是否需要最严格模式？ - -通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。但理论上两个节点也可能同时发生故障，所以除非是对性能要求高于数据安全的场景，一般都强烈推荐开启 `sync-log`。 - -另外，还有一种 `sync-log` 的替代方案，即在 Raft group 中用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 - -对于单机存储引擎也同样推荐打开 `sync-log` 模式。否则如果节点宕机可能会丢失最后一次写入数据。 - -#### 3.4.17 使用 Raft 协议，数据写入会有多次网络的 roundtrip，实际写入延迟如何？ - -理论上，和单机数据库相比，数据写入会多四个网络延迟。 - -#### 3.4.18 有没有类似 MySQL 的 InnoDB Memcached plugin，可以直接使用 KV 接口，可以不需要独立的 Cache？ - -TiKV 支持单独进行接口调用，理论上也可以起个实例做为 Cache，但 TiDB 最大的价值是分布式关系型数据库，我们原则上不对 TiKV 单独进行支持。 - -#### 3.4.19 Coprocessor 组件的主要作用？ - -- 减少 TiDB 与 TiKV 之间的数据传输。 -- 计算下推，充分利用 TiKV 的分布式计算资源。 - -#### 3.4.20 IO error: No space left on device While appending to file - -这是磁盘空间不足导致的，需要加节点或者扩大磁盘空间。 - -#### 3.4.21 为什么 TiKV 容易出现 OOM？ - -TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总内存的 40%。当 TiKV 容易出现 OOM 时，检查 `block-cache-size` 配置是否过高。还需要注意，当单机部署了多个 TiKV 实例时，需要显式地配置该参数，以防止多个实例占用过多系统内存导致 OOM。 - -#### 3.4.22 TiDB 数据和 RawKV 数据可存储于同一个 TiKV 集群里吗？ - -不可以。TiDB 数据（或使用其他事务 API 生成的数据）依赖于一种特殊的键值格式，和 RawKV API 数据（或其他基于 RawKV 的服务生成的数据）并不兼容。 - -### 3.5 TiDB 测试 - -#### 3.5.1 TiDB Sysbench 基准测试结果如何？ - -很多用户在接触 TiDB 都习惯做一个基准测试或者 TiDB 与 MySQL 的对比测试，官方也做了一个类似测试，汇总很多测试结果后，我们发现虽然测试的数据有一定的偏差，但结论或者方向基本一致，由于 TiDB 与 MySQL 由于架构上的差别非常大，很多方面是很难找到一个基准点，所以官方的建议两点： - -- 大家不要用过多精力纠结这类基准测试上，应该更多关注 TiDB 的场景上的区别。 -- 大家可以直接参考 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 - -#### 3.5.2 TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？ - -- 在 10 节点内，TiDB 写入能力（Insert TPS）和节点数量基本成 40% 线性递增，MySQL 由于是单节点写入，所以不具备写入扩展能力。 -- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://t.cn/RTD18qV)。 -- TiDB 不管是读流量、还是写流量都可以通过添加节点快速方便的进行扩展。 - -#### 3.5.3 我们的 DBA 测试过 MySQL 性能，单台 TiDB 的性能没有 MySQL 性能那么好？ - -TiDB 设计的目标就是针对 MySQL 单台容量限制而被迫做的分库分表的场景，或者需要强一致性和完整分布式事务的场景。它的优势是通过尽量下推到存储节点进行并行计算。对于小表（比如千万级以下），不适合 TiDB，因为数据量少，Region 有限，发挥不了并行的优势，最极端的就是计数器表，几行记录高频更新，这几行在 TiDB 里，会变成存储引擎上的几个 KV，然后只落在一个 Region 里，而这个 Region 只落在一个节点上。加上后台强一致性复制的开销，TiDB 引擎到 TiKV 引擎的开销，最后表现出来的就是没有单个 MySQL 好。 - -### 3.6 TiDB 备份恢复 - -#### 3.6.1 TiDB 主要备份方式？ - -目前，推荐的备份方式是使用 [PingCAP fork 的 Mydumper](/v3.0/reference/tools/mydumper.md)。尽管 TiDB 也支持使用 MySQL 官方工具 `mysqldump` 进行数据备份、恢复，但其性能低于 [`mydumper`](/v3.0/reference/tools/mydumper.md)/[`loader`](/v3.0/reference/tools/loader.md)，并且该工具备份、恢复大量数量时，要耗费更多时间。 - -使用 Mydumper 导出来的数据文件尽可能的小, 最好不要超过 64M, 可以设置参数 -F 64； - -loader 的 -t 参数可以根据 TiKV 的实例个数以及负载进行评估调整，例如 3 个 TiKV 的场景， 此值可以设为 3 * (1 ～ n)，当 TiKV 负载过高，loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 可以适当调小该值，当 TiKV 负载不是太高的时候，可以适当调大该值。 - -## 四、数据、流量迁移 - -### 4.1 全量数据导出导入 - -#### 4.1.1 Mydumper - -参见 [Mydumper 使用文档](/v3.0/reference/tools/mydumper.md)。 - -#### 4.1.2 Loader - -参见 [Loader 使用文档](/v3.0/reference/tools/loader.md)。 - -#### 4.1.3 如何将一个运行在 MySQL 上的应用迁移到 TiDB 上？ - -TiDB 支持绝大多数 MySQL 语法，一般不需要修改代码。 - -#### 4.1.4 不小心把 MySQL 的 user 表导入到 TiDB 了，或者忘记密码，无法登录，如何处理？ - -重启 TiDB 服务，配置文件中增加 `-skip-grant-table=true` 参数，无密码登录集群后，可以根据情况重建用户，或者重建 mysql.user 表，具体表结构搜索官网。 - -#### 4.1.5 在 Loader 运行的过程中，TiDB 可以对外提供服务吗？ - -该操作进行逻辑插入，TiDB 仍可对外提供服务，但不要执行相关 DDL 操作。 - -#### 4.1.6 如何导出 TiDB 数据？ - -TiDB 目前暂时不支持 `select into outfile`，可以通过以下方式导出 TiDB 数据：参考 [MySQL 使用 mysqldump 导出某个表的部分数据](https://blog.csdn.net/xin_yu_xin/article/details/7574662)，使用 mysqldump 加 where 条件导出，使用 MySQL client 将 select 的结果输出到一个文件。 - -#### 4.1.7 如何从 DB2、Oracle 数据库迁移到 TiDB？ - -DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： - -- 使用 Oracle 官方迁移工具，如 OGG、Gateway（透明网关）、CDC（Change Data Capture）。 -- 自研数据导出导入程序实现。 -- 导出（Spool）成文本文件，然后通过 Load infile 进行导入。 -- 使用第三方数据迁移工具。 - -目前看来 OGG 最为合适。 - -#### 4.1.8 用 Sqoop 批量写入 TiDB 数据，虽然配置了 `--batch` 选项，但还是会遇到 `java.sql.BatchUpdateExecption:statement count 5001 exceeds the transaction limitation` 的错误，该如何解决？ - -- 在 Sqoop 中，`--batch` 是指每个批次提交 100 条 statement，但是默认每个 statement 包含 100 条 SQL 语句，所以此时 100 * 100 = 10000 条 SQL 语句，超出了 TiDB 的事务限制 5000 条，可以增加选项 `-Dsqoop.export.records.per.statement=10` 来解决这个问题，完整的用法如下： - - {{< copyable "shell-regular" >}} - - ```bash - sqoop export \ - -Dsqoop.export.records.per.statement=10 \ - --connect jdbc:mysql://mysql.example.com/sqoop \ - --username sqoop ${user} \ - --password ${passwd} \ - --table ${tab_name} \ - --export-dir ${dir} \ - --batch - ``` - -- 也可以选择增大 tidb 的单个事物语句数量限制，不过这个会导致内存上涨。 - -#### 4.1.9 TiDB 有像 Oracle 那样的 Flashback Query 功能么，DDL 支持么？ - -有，也支持 DDL。详细参考 [TiDB 历史数据回溯](/v3.0/how-to/get-started/read-historical-data.md)。 - -### 4.2 在线数据同步 - -#### 4.2.1 Syncer 架构 - -详细参考 [解析 TiDB 在线数据同步工具 Syncer](https://pingcap.com/blog-cn/tidb-syncer/)。 - -##### 4.2.1.1 Syncer 使用文档 - -详细参考 [Syncer 使用文档](/v3.0/reference/tools/syncer.md)。 - -##### 4.2.1.2 如何配置监控 Syncer 运行情况？ - -下载 [Syncer Json](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json) 导入到 Grafana，修改 Prometheus 配置文件，添加以下内容： - -- job_name: 'syncer_ops' // 任务名字 - static_configs: -- targets: ['10.10.1.1:10096'] // Syncer 监听地址与端口，通知 prometheus 拉取 Syncer 的数据。 - -重启 Prometheus 即可。 - -##### 4.2.1.3 有没有现成的同步方案，可以将数据同步到 Hbase、Elasticsearh 等其他存储？ - -没有，目前依赖程序自行实现。 - -##### 4.2.1.4 利用 Syncer 做数据同步的时候是否支持只同步部分表？ - -支持，具体参考 Syncer 使用手册 [Syncer 使用文档](/v3.0/reference/tools/syncer.md) - -##### 4.2.1.5 频繁的执行 DDL 会影响 Syncer 同步速度吗？ - -频繁执行 DDL 对同步速度会有影响。对于 Sycner 来说，DDL 是串行执行的，当同步遇到了 DDL，就会以串行的方式执行，所以这种场景就会导致同步速度下降。 - -##### 4.2.1.6 使用 Syncer gtid 的方式同步时，同步过程中会不断更新 syncer.meta 文件，如果 Syncer 所在的机器坏了，导致 syncer.meta 文件所在的目录丢失，该如何处理？ - -当前 Syncer 版本的没有进行高可用设计，Syncer 目前的配置信息 syncer.meta 直接存储在硬盘上，其存储方式类似于其他 MySQL 生态工具，比如 Mydumper。因此，要解决这个问题当前可以有两个方法： - -1）把 syncer.meta 数据放到比较安全的磁盘上，例如磁盘做好 raid1； - -2）可以根据 Syncer 定期上报到 Prometheus 的监控信息来还原出历史同步的位置信息，该方法的位置信息在大量同步数据时由于延迟会可能不准确。 - -##### 4.2.1.7 Syncer 下游 TiDB 数据和 MySQL 数据不一致，DML 会退出么？ - -- 上游 MySQL 中存在数据，下游 TiDB 中该数据不存在，上游 MySQL 执行 `UPDATE` 或 `DELETE`（更新/删除）该条数据的操作时，Syncer 同步过程即不会报错退出也没有该条数据。 -- 下游有主键索引或是唯一索引冲突时，执行 `UPDATE` 会退出，执行 `INSERT` 不会退出。 - -### 4.3 业务流量迁入 - -#### 4.3.1 如何快速迁移业务流量？ - -我们建议通过 Syncer 工具搭建成多源 MySQL -> TiDB 实时同步环境，读写流量可以按照需求分阶段通过修改网络配置进行流量迁移，建议 DB 上层部署一个稳定的网络 LB（HAproxy、LVS、F5、DNS 等），这样直接修改网络配置就能实现无缝流量迁移。 - -#### 4.3.2 TiDB 总读写流量有限制吗？ - -TiDB 读流量可以通过增加 TiDB server 进行扩展，总读容量无限制，写流量可以通过增加 TiKV 节点进行扩容，基本上写容量也没有限制。 - -#### 4.3.3 Transaction too large 是什么原因，怎么解决？ - -由于分布式事务要做两阶段提交，并且底层还需要做 Raft 复制，如果一个事务非常大，会使得提交过程非常慢，并且会卡住下面的 Raft 复制流程。为了避免系统出现被卡住的情况，我们对事务的大小做了限制： - -- 单个事务包含的 SQL 语句不超过 5000 条（默认） -- 单条 KV entry 不超过 6MB -- KV entry 的总条数不超过 30w -- KV entry 的总大小不超过 100MB - -在 Google 的 Cloud Spanner 上面，也有类似的[限制](https://cloud.google.com/spanner/docs/limits)。 - -#### 4.3.4 如何批量导入？ - -导入数据的时候，可以分批插入，每批最好不要超过 1w 行。 - -#### 4.3.5 TiDB 中删除数据后会立即释放空间吗？ - -DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DROP 操作，在达到 TiDB 的 GC (garbage collection) 时间后（默认 10 分钟），TiDB 的 GC 机制会删除数据并释放空间。对于 DELETE 操作 TiDB 的 GC 机制会删除数据，但不会释放空间，而是当后续数据写入 RocksDB 且进行 compact 时对空间重新利用。 - -#### 4.3.6 Load 数据时可以对目标表执行 DDL 操作吗？ - -不可以，加载数据期间不能对目标表执行任何 DDL 操作，这会导致数据加载失败。 - -#### 4.3.7 TiDB 是否支持 replace into 语法？ - -支持，但是 load data 不支持 replace into 语法。 - -#### 4.3.8 数据删除后查询速度为何会变慢？ - -大量删除数据后，会有很多无用的 key 存在，影响查询效率。目前正在开发 Region Merge 功能，完善之后可以解决这个问题，具体看参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 - -#### 4.3.9 数据删除最高效最快的方式？ - -在删除大量数据的时候，建议使用 `Delete * from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -#### 4.3.10 TiDB 如何提高数据加载速度？ - -主要有两个方面： - -- 目前已开发分布式导入工具 [Lightning](/v3.0/reference/tools/tidb-lightning/overview.md)，需要注意的是数据导入过程中为了性能考虑，不会执行完整的事务流程，所以没办法保证导入过程中正在导入的数据的 ACID 约束，只能保证整个导入过程结束以后导入数据的 ACID 约束。因此适用场景主要为新数据的导入（比如新的表或者新的索引），或者是全量的备份恢复（先 Truncate 原表再导入）。 -- TiDB 的数据加载与磁盘以及整体集群状态相关，加载数据时应关注该主机的磁盘利用率，TiClient Error/Backoff/Thread CPU 等相关 metric，可以分析相应瓶颈。 - -#### 4.3.11 对数据做删除操作之后，空间回收比较慢，如何处理？ - -可以设置并行 GC，加快对空间的回收速度。默认并发为 1，最大可调整为 tikv 实例数量的 50%。可使用 `update mysql.tidb set VARIABLE_VALUE="3" where VARIABLE_NAME="tikv_gc_concurrency";` 命令来调整。 - -## 五、SQL 优化 - -### 5.1 TiDB 执行计划解读 - -详细解读 [理解 TiDB 执行计划](/v3.0/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.1 统计信息收集 - -详细解读 [统计信息](/v3.0/reference/performance/statistics.md)。 - -#### 5.1.2 Count 如何加速？ - -Count 就是暴力扫表，提高并发度能显著的提升速度，修改并发度可以参考 `tidb_distsql_scan_concurrency` 变量，但是也要看 CPU 和 I/O 资源。TiDB 每次查询都要访问 TiKV，在数据量小的情况下，MySQL 都在内存里，TiDB 还需要进行一次网络访问。 - -提升建议： - -- 建议提升硬件配置，可以参考[部署建议](/v3.0/how-to/deploy/hardware-recommendations.md)。 -- 提升并发度，默认是 10，可以提升到 50 试试，但是一般提升在 2-4 倍之间。 -- 测试大数据量的 count。 -- 调优 TiKV 配置，可以参考[性能调优](/v3.0/reference/performance/tune-tikv.md)。 - -#### 5.1.3 查看当前 DDL 的进度？ - -通过 `admin show ddl` 查看当前 job 进度。操作如下： - -{{< copyable "sql" >}} - -```sql -admin show ddl; -``` - -``` -*************************** 1. row *************************** - SCHEMA_VER: 140 - OWNER: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -RUNNING_JOBS: ID:121, Type:add index, State:running, SchemaState:write reorganization, SchemaID:1, TableID:118, RowCount:77312, ArgLen:0, start time: 2018-12-05 16:26:10.652 +0800 CST, Err:, ErrCount:0, SnapshotVersion:404749908941733890 - SELF_ID: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -``` - -从上面操作结果可知，当前正在处理的是 `add index` 操作。且从 `RUNNING_JOBS` 列的 `RowCount` 字段可以知道当前 `add index` 操作已经添加了 77312 行索引。 - -#### 5.1.4 如何查看 DDL job？ - -可以使用 `admin show ddl` 语句查看正在运行的 DDL 作业。 - -- `admin show ddl jobs`：用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 -- `admin show ddl job queries 'job_id' [, 'job_id'] ...`：用于显示 `job_id` 对应的 DDL 任务的原始 SQL 语句。此 `job_id` 只搜索正在执行中的任务以及 DDL 历史作业队列中的最近十条结果。 - -#### 5.1.5 TiDB 是否支持基于 COST 的优化（CBO），如果支持，实现到什么程度？ - -是的，TiDB 使用的基于成本的优化器（CBO），我们有一个小组单独会对代价模型、统计信息持续优化，除此之外，我们支持 hash join、soft merge 等关联算法。 - -#### 5.1.6 如何确定某张表是否需要做 analyze ？ - -可以通过 `show stats_healthy` 来查看 Healthy 字段，一般小于等于 60 的表需要做 analyze。 - -#### 5.1.7 SQL 的执行计划展开成了树，ID 的序号有什么规律吗？这棵树的执行顺序会是怎么样的？ - -ID 没什么规律，只要是唯一就行，不过生成的时候，是有一个计数器，生成一个 plan 就加一，执行的顺序和序号无关，整个执行计划是一颗树，执行时从根节点开始，不断地向上返回数据。执行计划的理解，请参考[理解 TiDB 执行计划](/v3.0/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.8 TiDB 执行计划中，task cop 在一个 root 下，这个是并行的么？ - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指被下推到 KV 端分布式执行的计算任务，root task 是指在 TiDB 端单点执行的计算任务。一般来讲 root task 的输入数据是来自于 cop task 的；但是 root task 在处理数据的时候，TiKV 上的 cop task 也可以同时处理数据，等待 TiDB 的 root task 拉取，所以从这个观点上来看，他们是并行的；但是存在数据上下游关系；在执行的过程中，某些时间段其实也是并行的，第一个 cop task 在处理 [100, 200] 的数据，第二个 cop task 在处理 [1, 100] 的数据。执行计划的理解，请参考[理解 TiDB 执行计划](/v3.0/reference/performance/understanding-the-query-execution-plan.md)。 - -## 六、数据库优化 - -### 6.1 TiDB - -#### 6.1.1 TiDB 参数及调整 - -详情参考 [TiDB 配置参数](/v3.0/reference/configuration/tidb-server/configuration.md)。 - -#### 6.1.2 如何打散热点 - -TiDB 中以 Region 分片来管理数据库，通常来讲，TiDB 的热点指的是 Region 的读写访问热点。而 TiDB 中对于 PK 非整数或没有 PK 的表，可以通过设置 `SHARD_ROW_ID_BITS` 来适度分解 Region 分片，以达到打散 Region 热点的效果。详情可参考官网 [TiDB 专用系统变量和语法](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)中 `SHARD_ROW_ID_BITS` 的介绍。 - -### 6.2 TiKV - -#### 6.2.1 TiKV 性能参数调优 - -详情参考 [TiKV 性能参数调优](/v3.0/reference/performance/tune-tikv.md)。 - -## 七、监控 - -### 7.1 Prometheus 监控框架 - -详细参考 [TiDB 监控框架概述](/v3.0/how-to/monitor/overview.md)。 - -### 7.2 监控指标解读 - -详细参考 [重要监控指标详解](/v3.0/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.1 目前的监控使用方式及主要监控指标，有没有更好看的监控？ - -TiDB 使用 Prometheus + Grafana 组成 TiDB 数据库系统的监控系统，用户在 Grafana 上通过 dashboard 可以监控到 TiDB 的各类运行指标，包括系统资源的监控指标，包括客户端连接与 SQL 运行的指标，包括内部通信和 Region 调度的指标，通过这些指标，可以让数据库管理员更好的了解到系统的运行状态，运行瓶颈等内容。在监控指标的过程中，我们按照 TiDB 不同的模块，分别列出了各个模块重要的指标项，一般用户只需要关注这些常见的指标项。具体指标请参见[官方文档](/v3.0/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.2 Prometheus 监控数据默认 15 天自动清除一次，可以自己设定成 2 个月或者手动删除吗？ - -可以的，在 Prometheus 启动的机器上，找到启动脚本，然后修改启动参数，然后重启 Prometheus 生效。 - -```config ---storage.tsdb.retention="60d" -``` - -#### 7.2.3 Region Health 监控项 - -TiDB-2.0 版本中，PD metric 监控页面中，对 Region 健康度进行了监控，其中 Region Health 监控项是对所有 Region 副本状况的一些统计。其中 miss 是缺副本，extra 是多副本。同时也增加了按 Label 统计的隔离级别，level-1 表示这些 Region 的副本在第一级 Label 下是物理隔离的，没有配置 location label 时所有 Region 都在 level-0。 - -#### 7.2.4 Statement Count 监控项中的 selectsimplefull 是什么意思？ - -代表全表扫，但是可能是很小的系统表。 - -#### 7.2.5 监控上的 QPS 和 Statement OPS 有什么区别？ - -QPS 会统计执行的所有 SQL 命令，包括 use database、load data、begin、commit、set、show、insert、select 等。 - -Statement OPS 只统计 select、update、insert 等业务相关的，所以 Statement OPS 的统计和业务比较相符。 - -## 八、Cloud TiDB - -### 8.1 腾讯云 - -#### 8.1.1 目前 Cloud TiDB 都有那些云厂商？ - -Cloud TiDB 目前已经在腾讯云、UCloud 上线，都是数据库一级入口，欢迎大家使用。 - -## 九、故障排除 - -### 9.1 TiDB 自定义报错汇总 - -#### 9.1.1 ERROR 8005 (HY000) : Write Conflict, txnStartTS is stale - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -#### 9.1.2 ERROR 9001 (HY000) : PD Server Timeout - -请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络。 - -#### 9.1.3 ERROR 9002 (HY000) : TiKV Server Timeout - -请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络。 - -#### 9.1.4 ERROR 9003 (HY000) : TiKV Server is Busy - -TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.5 ERROR 9004 (HY000) : Resolve Lock Timeout - -清理锁超时，当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码是否有锁争用。 - -#### 9.1.6 ERROR 9005 (HY000) : Region is unavailable - -访问的 Region 不可用，某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.7 ERROR 9006 (HY000) : GC life time is shorter than transaction duration - -`GC Life Time` 间隔时间过短，长事务本应读到的数据可能被清理了，可使用如下命令增加 `GC Life Time`： - -{{< copyable "sql" >}} - -```sql -update mysql.tidb set variable_value='30m' where variable_name='tikv_gc_life_time'; -``` - -其中 30m 代表仅清理 30 分钟前的数据，这可能会额外占用一定的存储空间。 - -#### 9.1.8 ERROR 9007 (HY000) : Write Conflict - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -### 9.2 MySQL 原生报错汇总 - -#### 9.2.1 ERROR 2013 (HY000): Lost connection to MySQL server during query 问题的排查方法？ - -- log 中是否有 panic -- dmesg 中是否有 oom，命令：`dmesg -T | grep -i oom` -- 长时间没有访问，也会收到这个报错，一般是 tcp 超时导致的，tcp 长时间不用, 会被操作系统 kill。 - -#### 9.2.2 ERROR 1105 (HY000): other error: unknown error Wire Error(InvalidEnumValue(4004)) 是什么意思？ - -这类问题一般是 TiDB 和 TiKV 版本不匹配，在升级过程尽量一起升级，避免版本 mismatch。 - -#### 9.2.3 ERROR 1148 (42000): the used command is not allowed with this TiDB version 问题的处理方法？ - -这个问题是因为在执行 `LOAD DATA LOCAL` 语句的时候，MySQL 客户端不允许执行此语句（即 `local_infile` 选项为 0）。解决方法是在启动 MySQL 客户端时，用 `--local-infile=1` 选项。具体启动指令类似：`mysql --local-infile=1 -u root -h 127.0.0.1 -P 4000`。有些 MySQL 客户端需要设置而有些不需要设置，原因是不同版本的 MySQL 客户端对 `local-infile` 的默认值不同。 - -#### 9.2.4 ERROR 9001 (HY000): PD server timeout start timestamp may fall behind safe point - -这个报错一般是 TiDB 访问 PD 出了问题，TiDB 后台有个 worker 会不断地从 PD 查询 safepoint，如果超过 100s 查不成功就会报这个错。一般是因为 PD 磁盘操作过忙、反应过慢，或者 TiDB 和 PD 之间的网络有问题。TiDB 常见错误码请参考[错误码与故障诊断](/v3.0/reference/error-codes.md)。 - -### 9.3 TiDB 日志中的报错信息 - -#### 9.3.1 EOF - -当客户端或者 proxy 断开连接时，TiDB 不会立刻察觉连接已断开，而是等到开始往连接返回数据时，才发现连接已断开，此时日志会打印 EOF 错误。 diff --git a/v3.0/faq/upgrade.md b/v3.0/faq/upgrade.md deleted file mode 100644 index c90150ea8374..000000000000 --- a/v3.0/faq/upgrade.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: 升级后常见问题 -category: FAQ -aliases: ['/docs-cn/op-guide/upgrade-faq/','/docs-cn/faq/upgrade/'] ---- - -# 升级后常见问题 - -本文列出了一些升级后可能会遇到的问题与解决办法。 - -## 执行 DDL 操作时遇到的字符集 (charset) 问题 - -TiDB 在 v2.1.0 以及之前版本（包括 v2.0 所有版本）中，默认字符集是 UTF8。从 v2.1.1 开始，默认字符集变更为 UTF8MB4。如果在 v2.1.0 及之前版本中，建表时显式指定了 table 的 charset 为 UTF8，那么升级到 v2.1.1 之后，执行 DDL 操作可能会失败。 - -要避免该问题，需注意以下两个要点： - -1. 在 v2.1.3 之前，TiDB 不支持修改 column 的 charset。所以，执行 DDL 操作时，新 column 的 charset 需要和旧 column 的 charset 保持一致。 - -2. 在 v2.1.3 之前，即使 column 的 charset 和 table 的 charset 不一样，`show create table` 也不会显示 column 的 charset，但可以通过 HTTP API 获取 table 的元信息来查看 column 的 charset，下文提供了示例。 - -### 问题 1：`unsupported modify column charset utf8mb4 not match origin utf8` - -- 升级前：v2.1.0 及之前版本 - - {{< copyable "sql" >}} - - ```sql - create table t(a varchar(10)) charset=utf8; - ``` - - ``` - Query OK, 0 rows affected - Time: 0.106s - ``` - - {{< copyable "sql" >}} - - ```sql - show create table t - ``` - - ``` - +-------+-------------------------------------------------------+ - | Table | Create Table | - +-------+-------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+-------------------------------------------------------+ - 1 row in set - Time: 0.006s - ``` - -- 升级后：v2.1.1、v2.1.2 会出现下面的问题，v2.1.3 以及之后版本不会出现下面的问题。 - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(20); - ``` - - ``` - ERROR 1105 (HY000): unsupported modify column charset utf8mb4 not match origin utf8 - ``` - -解决方案：显式指定 column charset，保持和原来的 charset 一致即可。 - -{{< copyable "sql" >}} - -```sql -alter table t change column a a varchar(22) character set utf8; -``` - -- 根据要点 1，此处如果不指定 column 的 charset，会用默认的 UTF8MB4，所以需要指定 column charset 保持和原来一致。 - -- 根据要点 2，用 HTTP API 获取 table 元信息，然后根据 column 名字和 Charset 关键字搜索即可找到 column 的 charset。 - - {{< copyable "shell-regular" >}} - - ```sh - curl "http://$IP:10080/schema/test/t" | python -m json.tool - ``` - - 这里用了 python 的格式化 json的工具，也可以不加，此处只是为了方便注释。 - - ```json - { - "ShardRowIDBits": 0, - "auto_inc_id": 0, - "charset": "utf8", # table 的 charset - "collate": "", - "cols": [ # 从这里开始列举 column 的相关信息 - { - ... - "id": 1, - "name": { - "L": "a", - "O": "a" # column 的名字 - }, - "offset": 0, - "origin_default": null, - "state": 5, - "type": { - "Charset": "utf8", # column a 的 charset - "Collate": "utf8_bin", - "Decimal": 0, - "Elems": null, - "Flag": 0, - "Flen": 10, - "Tp": 15 - } - } - ], - ... - } - ``` - -### 问题 2：`unsupported modify charset from utf8mb4 to utf8` - -- 升级前：v2.1.1，v2.1.2 - - {{< copyable "sql" >}} - - ```sql - create table t(a varchar(10)) charset=utf8; - ``` - - ``` - Query OK, 0 rows affected - Time: 0.109s - ``` - - {{< copyable "sql" >}} - - ```sql - show create table t; - ``` - - ``` - +-------+-------------------------------------------------------+ - | Table | Create Table | - +-------+-------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+-------------------------------------------------------+ - ``` - - 上面 `show create table` 只显示出了 table 的 charset，但其实 column 的 charset 是 UTF8MB4，这可以通过 HTTP API 获取 schema 来确认。这是一个 bug，即此处建表时 column 的 charset 应该要和 table 保持一致为 UTF8，该问题在 v2.1.3 中已经修复。 - -- 升级后：v2.1.3 及之后版本 - - {{< copyable "sql" >}} - - ```sql - show create table t; - ``` - - ``` - +-------+--------------------------------------------------------------------+ - | Table | Create Table | - +-------+--------------------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) CHARSET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+--------------------------------------------------------------------+ - 1 row in set - Time: 0.007s - ``` - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(20); - ``` - - ``` - ERROR 1105 (HY000): unsupported modify charset from utf8mb4 to utf8 - ``` - -解决方案： - -- 因为在 v2.1.3 之后，TiDB 支持修改 column 和 table 的 charset，所以这里推荐修改 table 的 charset 为 UTF8MB4。 - - {{< copyable "sql" >}} - - ```sql - alter table t convert to character set utf8mb4; - ``` - -- 也可以像问题 1 一样指定 column 的 charset，保持和 column 原来的 charset (UTF8MB4) 一致即可。 - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(20) character set utf8mb4; - ``` - -### 问题 3：`ERROR 1366 (HY000): incorrect utf8 value f09f8c80(🌀) for column a` - -TiDB 在 v2.1.1 及之前版本中，如果 charset 是 UTF8，没有对 4-byte 的插入数据进行 UTF8 Unicode encoding 检查。在v2.1.2 及之后版本中，添加了该检查。 - -- 升级前：v2.1.1 及之前版本 - - {{< copyable "sql" >}} - - ```sql - create table t(a varchar(100) charset utf8); - ``` - - ``` - Query OK, 0 rows affected - ``` - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - Query OK, 1 row affected - ``` - -- 升级后：v2.1.2 及之后版本 - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - ERROR 1366 (HY000): incorrect utf8 value f09f8c80(🌀) for column a - ``` - -解决方案： - -- v2.1.2 版本：该版本不支持修改 column charset，所以只能跳过 UTF8 的检查。 - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_skip_utf8_check=1; - ``` - - ``` - Query OK, 0 rows affected - ``` - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - Query OK, 1 row affected - ``` - -- v2.1.3 及之后版本：建议修改 column 的 charset 为 UTF8MB4。或者也可以设置 `tidb_skip_utf8_check` 变量跳过 UTF8 的检查。如果跳过 UTF8 的检查，在需要将数据从 TiDB 同步回 MySQL 的时候，可能会失败，因为 MySQL 会执行该检查。 - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(100) character set utf8mb4; - ``` - - ``` - Query OK, 0 rows affected - ``` - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - Query OK, 1 row affected - ``` - - 关于 `tidb_skip_utf8_check` 变量，具体来说是指跳过 UTF8 和 UTF8MB4 类型对数据的合法性检查。如果跳过这个检查，在需要将数据从 TiDB 同步回 MySQL 的时候，可能会失败，因为 MySQL 执行该检查。如果只想跳过 UTF8 类型的检查，可以设置 `tidb_check_mb4_value_in_utf8` 变量。 - - `tidb_check_mb4_value_in_utf8` 在 v2.1.3 版本加入 `config.toml` 文件，可以修改配置文件里面的 `check-mb4-value-in-utf8` 后重启集群生效。 - - `tidb_check_mb4_value_in_utf8` 在 v2.1.5 版本开始可以用 HTTP API 来设置，也可以用 session 变量来设置。 - - * HTTP API（HTTP API 只在单台服务器上生效） - - * 执行下列命令启用 HTTP API： - - {{< copyable "shell-regular" >}} - - ```sh - curl -X POST -d "check_mb4_value_in_utf8=1" http://{TiDBIP}:10080/settings - ``` - - * 执行下列命令禁用 HTTP API： - - {{< copyable "shell-regular" >}} - - ```sh - curl -X POST -d "check_mb4_value_in_utf8=0" http://{TiDBIP}:10080/settings - ``` - - * Session 变量 - - * 执行下列命令启用 Session 变量： - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_check_mb4_value_in_utf8 = 1; - ``` - - * 执行下列命令禁用 Session 变量： - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_check_mb4_value_in_utf8 = 0; - ``` - -- v2.1.7 及之后版本，如果对表和 column 的字符集没有严格要求为 UTF8，也不想修改客户端代码去跳过 UTF8 检查或者手动修改 column 的 charset，可以在配置文件中把 `treat-old-version-utf8-as-utf8mb4` 打开。该配置的作用是自动把 v2.1.7 版本之前创建的旧版本的表和 column 的 UTF8 字符集转成 UTF8MB4。这个转换是在 TiDB load schema 时在内存中将 UTF8 转成 UTF8MB4，不会对实际存储的数据做任何修改。在配置文件中关闭 `treat-old-version-utf8-as-utf8mb4` 并重启 TiDB 后，以前字符集为 UTF8 的表和 column 的字符集仍然还是 UTF8。 - - > **注意：** - > - > `treat-old-version-utf8-as-utf8mb4` 参数默认打开，如果客户端强制需要用 UTF8 而不用 UTF8MB4，需要在配置文件中关闭。 diff --git a/v3.0/glossary.md b/v3.0/glossary.md deleted file mode 100644 index 3b31e69e5d20..000000000000 --- a/v3.0/glossary.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: 术语表 -summary: 了解 TiDB 相关术语。 -category: glossary ---- - -# 术语表 - -## A - -### ACID - -ACID 是指数据库管理系统在写入或更新资料的过程中，为保证[事务](#事务)是正确可靠的，所必须具备的四个特性：原子性 (atomicity)、一致性 (consistency)、隔离性（isolation）以及持久性（durability）。 - -* 原子性 (atomicity) 指一个事务中的所有操作，或者全部完成，或者全部不完成，不会结束在中间某个环节。TiDB 通过 Primary Key 所在 [Region](#regionpeerraft-group) 的原子性来保证分布式事务的原子性。 -* 一致性 (consistency) 指在事务开始之前和结束以后，数据库的完整性没有被破坏。TiDB 在写入数据之前，会校验数据的一致性，校验通过才会写入内存并返回成功。 -* 隔离性 (isolation) 指数据库允许多个并发事务同时对其数据进行读写和修改的能力。隔离性可以防止多个事务并发执行时由于交叉执行而导致数据的不一致，主要用于处理并发场景。TiDB 目前只支持一种隔离级别，即可重复读。 -* 持久性 (durability) 指事务处理结束后，对数据的修改就是永久的，即便系统故障也不会丢失。在 TiDB 中，事务一旦提交成功，数据全部持久化存储到 TiKV，此时即使 TiDB 服务器宕机也不会出现数据丢失。 - -## L - -### Leader/Follower/Learner - -它们分别对应 [Peer](#regionpeerraft-group) 的三种角色。其中 Leader 负责响应客户端的读写请求；Follower 被动地从 Leader 同步数据，当 Leader 失效时会进行选举产生新的 Leader；Learner 是一种特殊的角色，它只参与同步 raft log 而不参与投票，在目前的实现中只短暂存在于添加副本的中间步骤。 - -## O - -### Operator - -Operator 是应用于一个 Region 的，服务于某个调度目的的一系列操作的集合。例如“将 Region 2 的 Leader 迁移至 Store 5”，“将 Region 2 的副本迁移到 Store 1, 4, 5”等。 - -Operator 可以是由 Scheduler 通过计算生成的，也可以是由外部 API 创建的。 - -### Operator Step - -Operator Step 是 Operator 执行过程的一个步骤，一个 Operator 常常会包含多个 Operator Step。 - -目前 PD 可生成的 Step 包括： - -- `TransferLeader`：将 Region Leader 迁移至指定 Peer -- `AddPeer`：在指定 Store 添加 Follower -- `RemovePeer`：删除一个 Region Peer -- `AddLearner`：在指定 Store 添加 Region Learner -- `PromoteLearner`：将指定 Learner 提升为 Follower -- `SplitRegion`：将指定 Region 一分为二 - -## P - -### Pending/Down - -Pending 和 Down 是 Peer 可能出现的两种特殊状态。其中 Pending 表示 Follower 或 Learner 的 raft log 与 Leader 有较大差距，Pending 状态的 Follower 无法被选举成 Leader。Down 是指 Leader 长时间没有收到对应 Peer 的消息，通常意味着对应节点发生了宕机或者网络隔离。 - -## R - -### Region/Peer/Raft Group - -每个 Region 负责维护集群的一段连续数据（默认配置下平均约 96 MiB），每份数据会在不同的 Store 存储多个副本（默认配置是 3 副本），每个副本称为 Peer。同一个 Region 的多个 Peer 通过 raft 协议进行数据同步，所以 Peer 也用来指代 raft 实例中的成员。TiKV 使用 multi-raft 模式来管理数据，即每个 Region 都对应一个独立运行的 raft 实例，我们也把这样的一个 raft 实例叫做一个 Raft Group。 - -### Region Split - -TiKV 集群中的 Region 不是一开始就划分好的，而是随着数据写入逐渐分裂生成的，分裂的过程被称为 Region Split。 - -其机制是集群初始化时构建一个初始 Region 覆盖整个 key space，随后在运行过程中每当 Region 数据达到一定量之后就通过 Split 产生新的 Region。 - -## S - -### Scheduler - -Scheduler（调度器）是 PD 中生成调度的组件。PD 中每个调度器是独立运行的，分别服务于不同的调度目的。常用的调度器及其调用目标有： - -- `balance-leader-scheduler`：保持不同节点的 Leader 均衡。 -- `balance-region-scheduler`：保持不同节点的 Peer 均衡。 -- `hot-region-scheduler`：保持不同节点的读写热点 Region 均衡。 -- `evict-leader-{store-id}`：驱逐某个节点的所有 Leader。（常用于滚动升级） - -### Store - -PD 中的 Store 指的是集群中的存储节点，也就是 tikv-server 实例。Store 与 TiKV 实例是严格一一对应的，即使在同一主机甚至同一块磁盘部署多个 TiKV 实例，这些实例也对会对应不同的 Store。 diff --git a/v3.0/how-to/configure/memory-control.md b/v3.0/how-to/configure/memory-control.md deleted file mode 100644 index 74814d4182a6..000000000000 --- a/v3.0/how-to/configure/memory-control.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: TiDB 内存控制文档 -category: how-to -aliases: ['/docs-cn/sql/tidb-memory-control/'] ---- - -# TiDB 内存控制文档 - -目前 TiDB 已经能够做到追踪单条 SQL 查询过程中的内存使用情况，当内存使用超过一定阈值后也能采取一些操作来预防 OOM 或者排查 OOM 原因。在 TiDB 的配置文件中，我们可以使用如下配置来控制内存使用超阈值时 TiDB 的行为： - -{{< copyable "" >}} - -``` -# Valid options: ["log", "cancel"] -oom-action = "log" -``` - -- 如果上面的配置项使用的是 "log"，那么当一条 SQL 的内存使用超过一定阈值（由 session 变量 `tidb_mem_quota_query` 来控制）后，TiDB 会在 log 文件中打印一条 LOG，然后这条 SQL 继续执行，之后如果发生了 OOM 可以在 LOG 中找到对应的 SQL。 -- 如果上面的配置项使用的是 "cancel"，那么当一条 SQL 的内存使用超过一定阈值后，TiDB 会立即中断这条 SQL 的执行并给客户端返回一个 error，error 信息中会详细写明这条 SQL 执行过程中各个占用内存比较多的物理执行算子的内存使用情况。 - -## 如何配置一条 SQL 执行过程中的内存使用阈值 - -可以在配置文件中设置每个 Query 默认的 Memory Quota，例如将其设置为 32GB： - -{{< copyable "" >}} - -``` -mem-quota-query = 34359738368 -``` - -此外还可通过如下几个 session 变量来控制一条 Query 中的内存使用，大多数用户只需要设置 `tidb_mem_quota_query` 即可，其他变量是高级配置，大多数用户不需要关心： - -| 变量名 | 作用 | 单位 | 默认值 | -|-----------------------------------|---------------------------------------------------|-------|-----------| -| tidb_mem_quota_query | 配置整条 SQL 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_hashjoin | 配置 Hash Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_mergejoin | 配置 Merge Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_sort | 配置 Sort 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_topn | 配置 TopN 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_indexlookupreader | 配置 Index Lookup Reader 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_indexlookupjoin | 配置 Index Lookup Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_nestedloopapply | 配置 Nested Loop Apply 的内存使用阈值 | Byte | 32 << 30 | - -几个使用例子： - -配置整条 SQL 的内存使用阈值为 8GB： - -{{< copyable "sql" >}} - -```sql -set @@tidb_mem_quota_query = 8 << 30; -``` - -配置整条 SQL 的内存使用阈值为 8MB： - -{{< copyable "sql" >}} - -```sql -set @@tidb_mem_quota_query = 8 << 20; -``` - -配置整条 SQL 的内存使用阈值为 8KB： - -{{< copyable "sql" >}} - -```sql -set @@tidb_mem_quota_query = 8 << 10; -``` \ No newline at end of file diff --git a/v3.0/how-to/configure/time-zone.md b/v3.0/how-to/configure/time-zone.md deleted file mode 100644 index c17b1278328c..000000000000 --- a/v3.0/how-to/configure/time-zone.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: 时区支持 -category: how-to -aliases: ['/docs-cn/sql/time-zone/'] ---- - -# 时区支持 - -TiDB 使用的时区由 `time_zone` 全局变量和 session 变量决定。`time_zone` 的默认值是 `System`，`System` 对应的实际时区在 `TiDB` 集群 bootstrap 初始化时设置。具体逻辑如下: - -* 优先使用 `TZ` 环境变量 -* 如果失败，则从 `/etc/localtime` 的实际软链地址提取。 -* 如果上面两种都失败则使用 `UTC` 作为系统时区。 - -在运行过程中可以修改全局时区： - -{{< copyable "sql" >}} - -```sql -SET GLOBAL time_zone = timezone; -``` - -TiDB 还可以通过设置 session 变量 `time_zone` 为每个连接维护各自的时区。默认条件下，这个值取的是全局变量 `time_zone` 的值。修改 session 使用的时区： - -{{< copyable "sql" >}} - -```sql -SET time_zone = timezone; -``` - -查看当前使用的时区的值： - -{{< copyable "sql" >}} - -```sql -SELECT @@global.time_zone, @@session.time_zone; -``` - -设置 `time_zone` 的值的格式： - -* 'SYSTEM' 表明使用系统时间 -* 相对于 UTC 时间的偏移，比如 '+10:00' 或者 '-6:00' -* 某个时区的名字，比如 'Europe/Helsinki'， 'US/Eastern' 或 'MET' - -`NOW()` 和 `CURTIME()` 的返回值都受到时区设置的影响。 - -> **注意：** -> -> 只有 Timestamp 数据类型的值是受时区影响的。可以理解为， Timestamp 数据类型的实际表示使用的是 (字面值 + 时区信息)。其它时间和日期类型，比如 Datetime/Date/Time 是不包含时区信息的，所以也不受到时区变化的影响。 - -{{< copyable "sql" >}} - -```sql -create table t (ts timestamp, dt datetime); -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@time_zone = 'UTC'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values ('2017-09-30 11:11:11', '2017-09-30 11:11:11'); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@time_zone = '+8:00'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t; -``` - -``` -+---------------------|---------------------+ -| ts | dt | -+---------------------|---------------------+ -| 2017-09-30 19:11:11 | 2017-09-30 11:11:11 | -+---------------------|---------------------+ -1 row in set (0.00 sec) -``` - -上面的例子中，无论怎么调整时区的值，Datetime 类型字段的值是不受影响的，而 Timestamp 则随着时区改变，显示的值会发生变化。其实 Timestamp 持久化到存储的值始终没有变化过，只是根据时区的不同显示值不同。 - -Timestamp 类型和 Datetime 等类型的值，两者相互转换的过程中，会涉及到时区。这种情况一律基于 session 的当前 `time_zone` 时区处理。 - -另外，用户在导数据的过程中，也要需注意主库和从库之间的时区设定是否一致。 diff --git a/v3.0/how-to/deploy/data-migration-with-ansible.md b/v3.0/how-to/deploy/data-migration-with-ansible.md deleted file mode 100644 index 3b664bba6f25..000000000000 --- a/v3.0/how-to/deploy/data-migration-with-ansible.md +++ /dev/null @@ -1,571 +0,0 @@ ---- -title: 使用 DM-Ansible 部署 DM 集群 -category: how-to -aliases: ['/docs-cn/tools/dm/deployment/'] ---- - -# 使用 DM-Ansible 部署 DM 集群 - -DM-Ansible 是 PingCAP 基于 [Ansible](https://docs.ansible.com/ansible/latest/index.html) 的 [Playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html#about-playbooks) 研发的 DM (Data Migration) 集群部署工具。本文将介绍如何使用 DM-Ansible 快速部署 DM 集群。 - -## 准备工作 - -在开始之前，先确保您准备好了以下配置的机器： - -1. 部署目标机器若干，配置如下： - - - CentOS 7.3 (64-bit) 或更高版本，x86_64 架构（AMD64） - - 机器之间内网互通 - - 关闭防火墙，或开放服务端口 - -2. 一台中控机，配置如下： - - - 包含 Python 2.7 的 CentOS 7.3（64-bit）或更高版本 - - Ansible 2.5 或更高版本 - - 互联网访问 - -## 第 1 步：在中控机上安装依赖包 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -根据中控机的操作系统版本，运行相应命令如下： - -- CentOS 7： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && \ - yum -y install python-pip - ``` - -- Ubuntu： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH 密钥 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 为 `tidb` 用户设置密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 在 sudo 文件尾部加上 `tidb ALL=(ALL) NOPASSWD: ALL`，为 `tidb` 用户设置免密使用 sudo。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH 密钥。 - - 执行以下 `su` 命令，将登录用户从 `root` 切换至 `tidb`。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 为 `tidb` 用户创建 SSH 密钥。当提示 `Enter passphrase` 时，按 Enter 键。命令成功执行后，生成的 SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为`/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：下载 DM-Ansible 至中控机 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -1. 打开 `/home/tidb` 目录。 -2. 执行以下命令下载 DM-Ansible。 - - {{< copyable "shell-regular" >}} - - ```bash - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz - ``` - - `{version}` 为期望下载的 DM 版本，如 `v1.0.1`、`v1.0.2` 等， - 可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 第 4 步：安装 DM-Ansible 及其依赖至中控机 - -> **注意：** -> -> - 请确保使用 `tidb` 账户登录中控机。 -> - 您需要使用 `pip` 方式下载安装 Ansible 及其依赖，否则可能会遇到兼容性问题。 DM-Ansible 当前与 Ansible 2.5 或更高版本兼容。 - -1. 在中控机上安装 DM-Ansible 及其依赖包： - - {{< copyable "shell-regular" >}} - - ```bash - tar -xzvf dm-ansible-{version}.tar.gz && \ - mv dm-ansible-{version} dm-ansible && \ - cd /home/tidb/dm-ansible && \ - sudo pip install -r ./requirements.txt - ``` - - Ansible 和相关依赖包含于 `dm-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 版本： - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 第 5 步：在中控机上配置 SSH 互信和 sudo 规则 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录至中控机。 - -1. 将您部署的目标机器的 IP 地址加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && \ - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.71 - 172.16.10.72 - 172.16.10.73 - - [all:vars] - username = tidb - ``` - -2. 运行如下命令，然后输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，创建 sudo 规则，并为中控机和部署目标机器之间配置 SSH 互信。 - -## 第 6 步：下载 DM 及监控组件安装包至中控机 - -> **注意：** -> -> 请确保中控机接入互联网。 - -在中控机上，运行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 第 7 步：编辑 `inventory.ini` 配置文件 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -打开并编辑 `/home/tidb/dm-ansible/inventory.ini` 文件如下，以管控 DM 集群。 - -```ini -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -根据场景需要，您可以在以下两种集群拓扑中任选一种： - -- [单节点上单个 DM-worker 实例的集群拓扑](#选项-1使用单节点上单个-dm-worker-实例的集群拓扑) -- [单节点上多个 DM-worker 实例的集群拓扑](#选项-2使用单节点上多个-dm-worker-实例的集群拓扑) - -通常情况下，我们推荐每个节点上部署单个 DM-Worker 实例。但如果您的机器拥有性能远超 [TiDB 软件和硬件环境要求](/v3.0/how-to/deploy/hardware-recommendations.md)中推荐配置的 CPU 和内存，并且每个节点配置 2 块以上的硬盘或大于 2T 的 SSD，您可以在单个节点上部署不超过 2 个 DM-Worker 实例。 - -### 选项 1：使用单节点上单个 DM-Worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1 | -| node3 | 172.16.10.73 | DM-worker2 | -| mysql-replica-01| 172.16.10.81 | MySQL | -| mysql-replica-02| 172.16.10.82 | MySQL | - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2 ansible_host=172.16.10.73 server_id=102 source_id="mysql-replica-02" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。关于 DM-worker 参数的更多信息，请参考 [DM-worker 配置及参数描述](#dm-worker-配置及参数描述)。 - -### 选项 2：使用单节点上多个 DM-worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1-1, DM-worker1-2 | -| node3 | 172.16.10.73 | DM-worker2-1, DM-worker2-2 | - -编辑 `inventory.ini` 文件时，请注意区分这些变量：`server_id`，`deploy_dir`，和 `dm_worker_port`。 - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1_1 ansible_host=172.16.10.72 server_id=101 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker1_2 ansible_host=172.16.10.72 server_id=102 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2_1 ansible_host=172.16.10.73 server_id=103 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker2_2 ansible_host=172.16.10.73 server_id=104 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.84 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。 - -### DM-worker 配置及参数描述 - -| 变量名称 | 描述 | -| ------------- | ------- -| source_id | DM-worker 绑定到的一个数据库实例或是具有主从架构的复制组。当发生主从切换的时候，只需要更新 `mysql_host` 或 `mysql_port` 而不用更改该 ID 标识。 | -| server_id | DM-worker 伪装成一个 MySQL slave，该变量即为这个 slave 的 server ID，在 MySQL 集群中需保持全局唯一。取值范围 0 ~ 4294967295。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置。 | -| mysql_host | 上游 MySQL 主机。 | -| mysql_user | 上游 MySQL 用户名，默认值为 “root”。| -| mysql_password | 上游 MySQL 用户密码，需使用 `dmctl` 工具加密。请参考[使用 dmctl 加密上游 MySQL 用户密码](#使用-dmctl-加密上游-mysql-用户密码)。 | -| mysql_port | 上游 MySQL 端口， 默认 3306。 | -| enable_gtid | DM-worker 是否使用全局事务标识符（GTID）拉取 binlog。使用前提是在上游 MySQL 已开启 GTID 模式。 | -| relay_binlog_name | DM-worker 是否从指定 binlog 文件位置开始拉取 binlog。仅适用于本地无有效 relay log 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| relay_binlog_gtid | DM-worker 是否从指定 GTID 位置开始拉取 binlog。仅适用于本地无有效 relay log，且 `enable_gtid` 设置为 true 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| flavor | 代表 MySQL 的版本发布类型。 如果是官方版本，Percona 版，或 Cloud MySQL 版，其值为 “mysql”。 如果是 MariaDB，其值为 "mariadb"。默认值是 "mysql"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置。 | - -关于 `deploy_dir` 配置的更多信息，请参考[配置部署目录](#配置部署目录)。 - -### 使用 dmctl 加密上游 MySQL 用户密码 - -假定上游 MySQL 的用户密码为 `123456`，运行以下命令，并将生成的字符串添加至 DM-worker 的 `mysql_password` 变量。 - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/dm-ansible/resources/bin && \ -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -## 第 8 步：编辑 `inventory.ini` 文件中的变量 - -此步介绍如何编辑部署目录中的变量，如何配置 relay log 同步位置以及 relay log GTID 的同步模式。此外，还会描述 `inventory.ini` 中的全局变量。 - -### 配置部署目录 - -编辑 `deploy_dir` 变量以配置部署目录。 - -- 全局变量默认设为 `/home/tidb/deploy`，适用于所有服务。如果数据盘挂载于 `/data1` 目录，您可以通过以下修改将其变更至 `/data1/dm`。 - - ```ini - ## Global variables. - [all:vars] - deploy_dir = /data1/dm - ``` - -- 如果需要为某个服务创建单独的部署目录，您可以在 `inventory.ini` 中配置服务主机列表的同时设置 host 变量。此操作需要您添加第一列别名，以避免在混合服务部署场景下产生混淆。 - - ```ini - dm-master ansible_host=172.16.10.71 deploy_dir=/data1/deploy - ``` - -### 配置 relay log 同步位置 - -首次启动 DM-worker 时，您需要配置 `relay_binlog_name` 变量以指定 DM-worker 拉取上游 MySQL 或 MariaDB binlog 的起始位置。 - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 relay_binlog_name="binlog.000011" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name="binlog.000002" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -> **注意：** -> -> 如未设定 `relay_binlog_name`，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 - -### 开启 relay log GTID 同步模式 - -在 DM 集群中，DM-worker 的 relay log 处理单元负责与上游 MySQL 或 MariaDB 通信，从而将 binlog 拉取至本地文件系统。 - -DM 目前支持 MySQL GTID 和 MariaDB GTID。您可以通过配置以下项目开启 relay log GTID 同步模式： - -- `enable_gtid`：打开 relay log GTID 同步模式以处理 master 和 slave 易位的场景 - -- `relay_binlog_gtid`：指定 DM-worker 开始拉取对应上游 MySQL 或 MariaDB binlog 的起始位置 - -示例配置如下： - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 enable_gtid=true relay_binlog_gtid="aae3683d-f77b-11e7-9e3b-02a495f8993c:1-282967971,cc97fa93-f5cf-11e7-ae19-02915c68ee2e:1-284361339" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name=binlog.000002 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -### 全局变量 - -| 变量名称 | 描述 | -| --------------- | ---------------------------------------------------------- | -| cluster_name | 集群名称，可调整 | -| dm_version | DM 版本，默认已配置 | -| grafana_admin_user | Grafana 管理员用户名称，默认值 `admin` | -| grafana_admin_password | Grafana 管理员账户的密码，用于通过 Ansible 导入 Dashboard。默认值为 `admin`。如果您在 Grafana 网页端修改了密码，请更新此变量。 | - -## 第 9 步：部署 DM 集群 - -使用 `ansible-playbook` 运行 Playbook，默认并发数量是 5。如果部署目标机器较多，您可以使用 `-f` 参数增加并发数量，例如，`ansible-playbook deploy.yml -f 10`。 - -以下部署操作示例使用中运行服务的用户为 `tidb`： - -1. 编辑 `dm-ansible/inventory.ini` 文件，确保 `ansible_user = tidb`。 - - ```ini - ansible_user = tidb - ``` - - > **注意：** - > - > 请勿将 `ansible_user` 设为 `root`，因为 `tidb-ansible` 限制服务需以普通用户运行。 - - 运行以下命令。如果所有服务都返回 `tidb`，则 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 运行以下命令。如果所有服务都返回 `root`，则 `tidb` 用户免密 sudo 操作配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 修改内核参数，并部署 DM 集群组件和监控组件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - -3. 启动 DM 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - - 此操作会按顺序启动 DM 集群的所有组件，包括 DM-master，DM-worker，以及监控组件。当一个 DM 集群被关闭后，您可以使用该命令将其开启。 - -## 第 10 步：关闭 DM 集群 - -如果您需要关闭一个 DM 集群，运行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -该操作会按顺序关闭整个 DM 集群中的所有组件，包括 DM-master，DM-worker，以及监控组件。 - -## 常见部署问题 - -### 默认服务端口 - -| 组件 | 端口变量 | 默认端口 | 描述 | -| :-- | :-- | :-- | :-- | -| DM-master | `dm_master_port` | 8261 | DM-master 服务交流端口 | -| DM-worker | `dm_worker_port` | 8262 | DM-worker 服务交流端口 | -| Prometheus | `prometheus_port` | 9090 | Prometheus 服务交流端口 | -| Grafana | `grafana_port` | 3000 | 外部 Web 监控服务及客户端（浏览器）访问端口 | -| Alertmanager | `alertmanager_port` | 9093 | Alertmanager 服务交流端口 | - -### 自定义端口 - -编辑 `inventory.ini` 文件，将服务端口的相关主机变量添加在对应服务 IP 地址后： - -```ini -dm_master ansible_host=172.16.10.71 dm_master_port=18261 -``` - -### 更新 DM-Ansible - -1. 使用 `tidb` 账户登录至中控机，进入 `/home/tidb` 目录，然后备份`dm-ansible` 文件夹。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - mv dm-ansible dm-ansible-bak - ``` - -2. 下载指定版本 DM-Ansible，解压。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz && \ - tar -xzvf dm-ansible-{version}.tar.gz && \ - mv dm-ansible-{version} dm-ansible - ``` - -3. 迁移 `inventory.ini` 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - cp dm-ansible-bak/inventory.ini dm-ansible/inventory.ini - ``` - -4. 迁移 `dmctl` 配置。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible-bak/dmctl && \ - cp * /home/tidb/dm-ansible/dmctl/ - ``` - -5. 用 Playbook 下载最新的 DM 二进制文件。此文件会自动替换 `/home/tidb/dm-ansible/resource/bin/` 目录下的二进制文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` diff --git a/v3.0/how-to/deploy/data-migration-with-binary.md b/v3.0/how-to/deploy/data-migration-with-binary.md deleted file mode 100644 index 1819d9a67ac6..000000000000 --- a/v3.0/how-to/deploy/data-migration-with-binary.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: 使用 DM binary 部署 DM 集群 -category: how-to ---- - -# 使用 DM binary 部署 DM 集群 - -本文将介绍如何使用 DM binary 快速部署 DM 集群。 - -## 准备工作 - -下载官方 binary，链接地址：[DM 下载](/v3.0/reference/tools/download.md#tidb-dm-data-migration)。 - -下载的文件中包括子目录 bin 和 conf。bin 目录下包含 dm-master、dm-worker、dmctl 以及 Mydumper 的二进制文件。conf 目录下有相关的示例配置文件。 - -## 使用样例 - -假设在两台服务器上部署 MySQL，在一台服务器上部署 TiDB（mocktikv 模式），另外在三台服务器上部署两个 DM-worker 实例和一个 DM-master 实例。各个节点的信息如下： - -| 实例 | 服务器地址 | -| :---------- | :----------- | -| MySQL1 | 192.168.0.1 | -| MySQL2 | 192.168.0.2 | -| TiDB | 192.168.0.3 | -| DM-master | 192.168.0.4 | -| DM-worker1 | 192.168.0.5 | -| DM-worker2 | 192.168.0.6 | - -MySQL1 和 MySQL2 中需要开启 binlog。DM-worker1 负责同步 MySQL1 的数据，DM-worker2 负责同步 MySQL2 的数据。下面以此为例，说明如何部署 DM。 - -### DM-worker 的部署 - -DM-worker 需要连接上游 MySQL，且为了安全，强制用户配置加密后的密码。首先使用 dmctl 对 MySQL 的密码进行加密，以密码为 "123456" 为例： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dmctl --encrypt "123456" -``` - -``` -fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg= -``` - -记录该加密后的值，用于下面部署 DM-worker 时的配置。 - -DM-worker 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -查看 DM-worker 的命令行参数说明： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dm-worker --help -``` - -``` -Usage of worker: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值："info"） - -V 输出版本信息 - -checker-backoff-max duration - 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔（默认值："5m0s"，一般情况下不需要修改。如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-backoff-rollback duration - 任务检查模块中，调整自动恢复等待时间的间隔（默认值："5m0s"，一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-check-enable - 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务（默认值：true） - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -print-sample-config - 打印示例配置 - -purge-expires int - relay log 的过期时间。DM-worker 会尝试自动删除最后修改时间超过了过期时间的 relay log（单位：小时） - -purge-interval int - 定期检查 relay log 是否过期的间隔时间（默认值：3600）（单位：秒） - -purge-remain-space int - 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log（默认值：15）（单位：GB） - -relay-dir string - 存储 relay log 的路径（默认值："./relay_log"） - -worker-addr string - DM-worker 的地址 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件来配置 DM-worker，把以下配置文件内容写入到 `conf/dm-worker1.toml` 中。 - -DM-worker 的配置文件： - -```toml -# Worker Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker 的地址 -worker-addr = ":8262" - -# 作为 MySQL slave 的 server ID，用于获取 MySQL 的 binlog -# 在一个 replication group 中，每个实例（master 和 slave）都应该有唯一的 server ID -# v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置 -server-id = 101 - -# 用于标识一个 replication group 或者 MySQL/MariaDB 实例 -source-id = "mysql-replica-01" - -# 上游实例类型，值可为 "mysql" 或者 "mariadb" -# v1.0.2 及以上版本的 DM 会自动识别上游实例类型，不需要手动配置 -flavor = "mysql" - -# MySQL 的连接地址 -[from] -host = "192.168.0.1" -user = "root" -password = "fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg=" -port = 3306 -``` - -在终端中使用下面的命令运行 DM-worker： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-worker -config conf/dm-worker1.toml -``` - -对于 DM-worker2，修改配置文件中的 `source-id` 为 `mysql-replica-02`，并将 `from` 配置部分修改为 MySQL2 的地址即可。如果因为没有多余的机器，将 DM-worker2 与 DM-worker1 部署在一台机器上，需要把两个 DM-worker 实例部署在不同的路径下，否则保存元信息和 relay log 的默认路径会冲突。 - -### DM-master 的部署 - -DM-master 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -DM-master 的命令行参数说明： - -```bash -./bin/dm-master --help -``` - -``` -Usage of dm-master: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值为 "info"） - -V 输出版本信息 - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -master-addr string - DM-master 的地址 - -print-sample-config - 打印出 DM-master 的示例配置 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件，把以下配置文件内容写入到 `conf/dm-master.toml` 中。 - -DM-master 的配置文件： - -```toml -# Master Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-master.log" - -# DM-master 监听地址 -master-addr = ":8261" - -# DM-Worker 的配置 -[[deploy]] -# 对应 DM-worker1 配置文件中的 source-id -source-id = "mysql-replica-01" -# DM-worker1 的服务地址 -dm-worker = "192.168.0.5:8262" - -[[deploy]] -# 对应 DM-worker2 配置文件中的 source-id -source-id = "mysql-replica-02" -# DM-worker2 的服务地址 -dm-worker = "192.168.0.6:8262" -``` - -在终端中使用下面的命令运行 DM-master： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-master -config conf/dm-master.toml -``` - -这样，DM 集群就部署成功了。下面创建简单的数据同步任务来使用 DM 集群。 - -### 创建数据同步任务 - -假设在 MySQL1 和 MySQL2 实例中有若干个分表，这些分表的结构相同，所在库的名称都以 "sharding" 开头，表名称都以 "t" 开头，并且主键或唯一键不存在冲突（即每张分表的主键或唯一键各不相同）。现在需要把这些分表同步到 TiDB 中的 `db_target.t_target` 表中。 - -首先创建任务的配置文件： - -{{< copyable "" >}} - -```yaml ---- -name: test -task-mode: all -is-sharding: true - -target-database: - host: "192.168.0.3" - port: 4000 - user: "root" - password: "" # 如果密码不为空，也需要配置 dmctl 加密后的密码 - -mysql-instances: - - source-id: "mysql-replica-01" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - -black-white-list: - instance: - do-dbs: ["~^sharding[\\d]+"] - do-tables: - - db-name: "~^sharding[\\d]+" - tbl-name: "~^t[\\d]+" - -routes: - sharding-route-rules-table: - schema-pattern: sharding* - table-pattern: t* - target-schema: db_target - target-table: t_target - - sharding-route-rules-schema: - schema-pattern: sharding* - target-schema: db_target -``` - -将以上配置内容写入到 `conf/task.yaml` 文件中，使用 dmctl 创建任务： - -{{< copyable "shell-regular" >}} - -```bash -bin/dmctl -master-addr 192.168.0.4:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 -» -``` - -{{< copyable "" >}} - -```bash -» start-task conf/task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "192.168.0.5:8262", - "msg": "" - }, - { - "result": true, - "worker": "192.168.0.6:8262", - "msg": "" - } - ] -} -``` - -这样就成功创建了一个将 MySQL1 和 MySQL2 实例中的分表数据同步到 TiDB 的任务。 diff --git a/v3.0/how-to/deploy/geographic-redundancy/location-awareness.md b/v3.0/how-to/deploy/geographic-redundancy/location-awareness.md deleted file mode 100644 index e9fb4a3a3f7f..000000000000 --- a/v3.0/how-to/deploy/geographic-redundancy/location-awareness.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: 集群拓扑信息配置 -category: how-to -aliases: ['/docs-cn/op-guide/location-awareness/'] ---- - -# 集群拓扑信息配置 - -## 概述 - -PD 能够根据 TiKV 集群的拓扑结构进行调度，使得 TiKV 的容灾能力最大化。 - -阅读本章前，请先确保阅读 [Ansible 部署方案](/v3.0/how-to/deploy/orchestrated/ansible.md) 和 [Docker 部署方案](/v3.0/how-to/deploy/orchestrated/docker.md)。 - -## TiKV 上报拓扑信息 - -可以通过 TiKV 的启动参数或者配置文件来让 TiKV 上报拓扑信息给 PD。 - -假设拓扑结构分为三级：zone > rack > host，可以通过 labels 来指定这些信息。 - -启动参数： - -``` -tikv-server --labels zone=,rack=,host= -``` - -配置文件： - -{{< copyable "" >}} - -```toml -[server] -labels = "zone=,rack=,host=" -``` - -## PD 理解 TiKV 拓扑结构 - -可以通过 PD 的配置文件让 PD 理解 TiKV 集群的拓扑结构。 - -{{< copyable "" >}} - -```toml -[replication] -max-replicas = 3 -location-labels = ["zone", "rack", "host"] -``` - -其中 `location-labels` 需要与 TiKV 的 `labels` 名字对应，这样 PD 才能知道这些 `labels` 代表了 TiKV 的拓扑结构。 - -> **注意：** -> -> 必须同时配置 PD 的 `location-labels` 和 TiKV 的 `labels` 参数，否则 `labels` 不会生效。 - -## PD 基于 TiKV 拓扑结构进行调度 - -PD 能够根据我们提供的拓扑信息作出最优的调度，我们只需要关心什么样的拓扑结构能够达到我们想要的效果。 - -假设我们使用三副本，并且希望一个数据中心挂掉的情况下，还能继续保持 TiDB 集群的高可用状态，我们至少需要四个数据中心。 - -假设我们有四个数据中心 (zone)，每个数据中心有两个机架 (rack)，每个机架上有两个主机 (host)。 -每个主机上面启动一个 TiKV 实例： - -``` -# zone=z1 -tikv-server --labels zone=z1,rack=r1,host=h1 -tikv-server --labels zone=z1,rack=r1,host=h2 -tikv-server --labels zone=z1,rack=r2,host=h1 -tikv-server --labels zone=z1,rack=r2,host=h2 - -# zone=z2 -tikv-server --labels zone=z2,rack=r1,host=h1 -tikv-server --labels zone=z2,rack=r1,host=h2 -tikv-server --labels zone=z2,rack=r2,host=h1 -tikv-server --labels zone=z2,rack=r2,host=h2 - -# zone=z3 -tikv-server --labels zone=z3,rack=r1,host=h1 -tikv-server --labels zone=z3,rack=r1,host=h2 -tikv-server --labels zone=z3,rack=r2,host=h1 -tikv-server --labels zone=z3,rack=r2,host=h2 - -# zone=z4 -tikv-server --labels zone=z4,rack=r1,host=h1 -tikv-server --labels zone=z4,rack=r1,host=h2 -tikv-server --labels zone=z4,rack=r2,host=h1 -tikv-server --labels zone=z4,rack=r2,host=h2 -``` - -也就是说，我们有 16 个 TiKV 实例，分布在 4 个不同的数据中心，8 个不同的机架，16 个不同的机器。 - -在这种拓扑结构下，PD 会优先把每一份数据的不同副本调度到不同的数据中心。 -这时候如果其中一个数据中心挂了，不会影响 TiDB 集群的高可用状态。 -如果这个数据中心一段时间内恢复不了，PD 会把这个数据中心的副本迁移出去。 - -总的来说，PD 能够根据当前的拓扑结构使得集群容灾能力最大化，所以如果我们希望达到某个级别的容灾能力， -就需要根据拓扑机构在不同的地理位置提供多于备份数 (`max-replicas`) 的机器。 diff --git a/v3.0/how-to/deploy/geographic-redundancy/overview.md b/v3.0/how-to/deploy/geographic-redundancy/overview.md deleted file mode 100644 index c830fa2f8b92..000000000000 --- a/v3.0/how-to/deploy/geographic-redundancy/overview.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: 跨数据中心部署方案 -category: how-to -aliases: ['/docs-cn/op-guide/cross-dc-deployment/'] ---- - -# 跨数据中心部署方案 - -作为 NewSQL 数据库，TiDB 兼顾了传统关系型数据库的优秀特性以及 NoSQL 数据库可扩展性，以及跨数据中心（下文简称“中心”）场景下的高可用。本文档旨在介绍跨数据中心部署的不同解决方案。 - -## 三中心部署方案 - -TiDB, TiKV, PD 分别分布在 3 个不同的中心，这是最常规，可用性最高的方案。 - -![三中心部署](/media/deploy-3dc.png) - -### 优点 - -所有数据的副本分布在三个数据中心，任何一个数据中心失效后，另外两个数据中心会自动发起 leader election，并在合理长的时间内（通常情况 20s 以内）恢复服务，并且不会产生数据丢失。 - -![三中心部署容灾](/media/deploy-3dc-dr.png) - -### 缺点 - -性能受网络延迟影响。 - -- 对于写入的场景，所有写入的数据需要同步复制到至少 2 个数据中心，由于 TiDB 写入过程使用两阶段提交，故写入延迟至少需要 2 倍数据中心间的延迟。 -- 对于读请求来说，如果数据 leader 与发起读取的 TiDB 节点不在同一个数据中心，也会受网络延迟影响。 -- TiDB 中的每个事务都需要向 PD leader 获取 TSO，当 TiDB 与 PD leader 不在同一个数据中心时，它上面运行的事务也会因此受网络延迟影响，每个有写入的事务会获取两次 TSO。 - -### 读性能优化 - -如果不需要每个数据中心同时对外提供服务，可以将业务流量全部派发到一个数据中心，并通过调度策略把 Region leader 和 PD leader 都迁移到同一个数据中心（我们在上文所述的测试中也做了这个优化）。这样一来，不管是从 PD 获取 TSO 还是读取 Region 都不受数据中心间网络的影响。当该数据中心失效后，PD leader 和 Region leader 会自动在其它数据中心选出，只需要把业务流量转移至其他存活的数据中心即可。 - -![三中心部署读性能优化](/media/deploy-3dc-optimize.png) - -## 两地三中心部署方案 - -两地三中心的方案与三数据中心类似，算是三机房方案根据业务特点进行的优化，区别是其中有两个数据中心距离很近（通常在同一个城市），网络延迟相对很小。这种场景下，我们可以把业务流量同时派发到同城的两个数据中心，同时控制 Region leader 和 PD leader 也分布在同城的两个数据中心。 - -![两地三中心部署方案](/media/deploy-2city3dc.png) - -与三数据中心方案相比，两地三中心有以下优势： - -- 写入速度更优 -- 两中心同时提供服务资源利用率更高 -- 依然能保证任何一个数据中心失效后保持可用并且不发生数据丢失 - -但是，缺陷是如果同城的两个数据中心同时失效（理论上讲要高于异地三数据中心损失 2 个的概率），将会导致不可用以及部分数据丢失。 - -## 两数据中心 + binlog 同步方案 - -两数据中心 + binlog 同步类似于传统的 MySQL 中 master/slave 方案。两个数据中心分别部署一套完整的 TiDB 集群，我们称之为主集群和从集群。正常情况下所有的请求都在主集群，写入的数据通过 binlog 异步同步至从集群并写入。 - -![binlog 同步部署方案](/media/deploy-binlog.png) - -当主集群整个数据中心失效后，业务可以切换至从集群，与 MySQL 类似，这种情况下会有一些数据缺失。对比 MySQL，这个方案的优势是数据中心内的 HA -- 少部分节点故障时，通过重新选举 leader 自动恢复服务，不需要人工干预。 - -![两中心 binlog 相互备份方案](/media/deploy-backup.png) - -另外部分用户采用这种方式做双数据中心多活，两个数据中心各有一个集群，将业务分为两个库，每个库服务一部分数据，每个数据中心的业务只会访问一个库，两个集群之间通过 binlog 将本数据中心业务所涉及的库中的数据变更同步到对端机房，形成环状备份。 - -> **注意：** -> -> 在两数据中心 + binlog 同步部署方案中，数据中心之间只有 binlog 异步复制。在数据中心间的延迟较高的情况下，从集群落后主集群的数据量会增大。当主集群故障后（DR），会造成数据丢失，丢失的数据量受网络延迟等因素影响。 - -## 高可用和容灾分析 - -对于三数据中心方案和两地三中心方案，我们能得到的保障是任意一个数据中心故障时，集群能自动恢复服务，不需要人工介入，并能保证数据一致性。注意各种调度策略都是用于帮助性能优化的，当发生故障时调度机制总是第一优先考虑可用性而不是性能。 - -对于两数据中心 + binlog 同步的方案，主集群内少量节点故障时也能自动恢复服务，不需要人工介入，并能保证数据一致性。当整个主集群故障时，需要人工切换至从集群，并可能发生一些数据丢失，数据丢失的数量取决于同步延迟，和网络条件有关。 diff --git a/v3.0/how-to/deploy/hardware-recommendations.md b/v3.0/how-to/deploy/hardware-recommendations.md deleted file mode 100644 index c2814dbcb933..000000000000 --- a/v3.0/how-to/deploy/hardware-recommendations.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: TiDB 软件和硬件环境建议配置 -category: how-to -aliases: ['/docs-cn/op-guide/recommendation/'] ---- - -# TiDB 软件和硬件环境建议配置 - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 - -## Linux 操作系统版本要求 - -| Linux 操作系统平台 | 版本 | -| :----------------------- | :----------: | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | -| Ubuntu LTS | 16.04 及以上 | - -> **注意：** -> -> - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 -> - TiDB 在 CentOS 7.3 的环境下进行过大量的测试，同时社区也有很多该操作系统部署的最佳实践，因此，建议使用 CentOS 7.3 以上的 Linux 操作系统来部署 TiDB。 -> - 以上 Linux 操作系统可运行在物理服务器以及 VMware、KVM、XEN 主流虚拟化环境上。 - -## 服务器建议配置 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -### 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | 无特殊要求 | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 4核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | - -> **注意：** -> -> - 验证测试环境中的 TiDB 和 PD 可以部署在同一台服务器上。 -> - 如进行性能相关的测试，避免采用低性能存储和网络硬件配置，防止对测试结果的正确性产生干扰。 -> - TiKV 的 SSD 盘推荐使用 NVME 接口以保证读写更快。 -> - 如果仅验证功能，建议使用 [Docker Compose 部署方案](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 -> - TiDB 对于磁盘的使用以存放日志为主，因此在测试环境中对于磁盘类型和容量并无特殊要求。 - -### 生产环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 32 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 4核+ | 8 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 32 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | - -> **注意：** -> -> - 生产环境中的 TiDB 和 PD 可以部署和运行在同服务器上，如对性能和可靠性有更高的要求，应尽可能分开部署。 -> - 生产环境强烈推荐使用更高的配置。 -> - TiKV 硬盘大小配置建议 PCI-E SSD 不超过 2 TB，普通 SSD 不超过 1.5 TB。 - -## 网络要求 - -TiDB 作为开源分布式 NewSQL 数据库，其正常运行需要网络环境提供如下的网络端口配置要求，管理员可根据实际环境中 TiDB 组件部署的方案，在网络侧和主机侧开放相关端口： - -| 组件 | 默认端口 | 说明 | -| :-- | :-- | :-- | -| TiDB | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | 20160 | TiKV 通信端口 | -| PD | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | 2380 | PD 集群节点间通信端口 | -| Pump | 8250 | Pump 通信端口 | -| Drainer | 8249 | Drainer 通信端口 | -| Prometheus | 9090 | Prometheus 服务通信端口 | -| Pushgateway | 9091 | TiDB，TiKV，PD 监控聚合和上报端口 | -| Node_exporter | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | 9308 | Kafka_exporter 通信端口，用于监控 binlog kafka 集群 | - -## 客户端 Web 浏览器要求 - -TiDB 提供了基于 [Grafana](https://grafana.com/) 的技术平台，对数据库集群的各项指标进行可视化展现。采用支持 Javascript 的微软 IE、Google Chrome、Mozilla Firefox 的较新版本即可访问监控入口。 diff --git a/v3.0/how-to/deploy/orchestrated/ansible.md b/v3.0/how-to/deploy/orchestrated/ansible.md deleted file mode 100644 index fd845e2b9eae..000000000000 --- a/v3.0/how-to/deploy/orchestrated/ansible.md +++ /dev/null @@ -1,966 +0,0 @@ ---- -title: 使用 TiDB Ansible 部署 TiDB 集群 -category: how-to -aliases: ['/docs-cn/op-guide/ansible-deployment/'] ---- - -# 使用 TiDB Ansible 部署 TiDB 集群 - -## 概述 - -Ansible 是一款自动化运维工具，[TiDB Ansible](https://github.com/pingcap/tidb-ansible) 是 PingCAP 基于 Ansible playbook 功能编写的集群部署工具。本文档介绍如何使用 TiDB Ansible 部署一个完整的 TiDB 集群。 - -本部署工具可以通过配置文件设置集群拓扑，完成以下各项运维工作： - -- 初始化操作系统参数 -- 部署 TiDB 集群（包括 PD、TiDB、TiKV 等组件和监控组件） -- [启动集群](/v3.0/how-to/maintain/ansible-operations.md#启动集群) -- [关闭集群](/v3.0/how-to/maintain/ansible-operations.md#关闭集群) -- [变更组件配置](/v3.0/how-to/upgrade/from-previous-version.md#编辑-tidb-集群组件配置文件) -- [集群扩容缩容](/v3.0/how-to/scale/with-ansible.md) -- [升级组件版本](/v3.0/how-to/upgrade/from-previous-version.md#滚动升级-tidb-集群组件) -- [集群开启 binlog](/v3.0/reference/tidb-binlog/overview.md) -- [清除集群数据](/v3.0/how-to/maintain/ansible-operations.md#清除集群数据) -- [销毁集群](/v3.0/how-to/maintain/ansible-operations.md#销毁集群) - -> **注意：** -> -> 对于生产环境，须使用 TiDB Ansible 部署 TiDB 集群。如果只是用于测试 TiDB 或体验 TiDB 的特性，建议[使用 Docker Compose 在单机上快速部署 TiDB 集群](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -## 准备机器 - -1. 部署目标机器若干 - - - 建议 4 台及以上，TiKV 至少 3 实例，且与 TiDB、PD 模块不位于同一主机，详见[部署建议](/v3.0/how-to/deploy/hardware-recommendations.md)。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统，x86_64 架构 (amd64)。 - - 机器之间内网互通。 - - > **注意：** - > - > 使用 Ansible 方式部署时，TiKV 及 PD 节点数据目录所在磁盘请使用 SSD 磁盘，否则无法通过检测。**如果仅验证功能，建议使用 [Docker Compose 部署方案](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md) 单机进行测试**。 - -2. 部署中控机一台 - - - 中控机可以是部署目标机器中的某一台。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统（默认包含 Python 2.7）。 - - 该机器需开放外网访问，用于下载 TiDB 及相关软件安装包。 - -## 第 1 步：在中控机上安装系统依赖包 - -以 `root` 用户登录中控机，然后根据操作系统类型执行相应的安装命令。 - -- 如果中控机使用的是 CentOS 7 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && \ - yum -y install python2-pip - ``` - -- 如果是中控机使用的是 Ubuntu 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH key - -以 `root` 用户登录中控机，执行以下步骤： - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 设置 `tidb` 用户密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 配置 `tidb` 用户 sudo 免密码，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾即可。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH key。 - - 执行 `su` 命令，从 `root` 用户切换到 `tidb` 用户下。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 创建 `tidb` 用户 SSH key，提示 `Enter passphrase` 时直接回车即可。执行成功后，SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为 `/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录。使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 3.0 [相应 TAG 版本](https://github.com/pingcap/tidb-ansible/tags)，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone -b $tag https://github.com/pingcap/tidb-ansible.git -``` - -> **注意：** -> -> - `$tag` 替换为选定的 TAG 版本的值，例如 `v3.0.2`。 -> - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 -> - 请务必按文档操作，将 `tidb-ansible` 下载到 `/home/tidb` 目录下，权限为 `tidb` 用户，不要下载到 `/root` 下，否则会遇到权限问题。 - -## 第 4 步：在中控机器上安装 Ansible 及其依赖 - -以 `tidb` 用户登录中控机，请务必按以下方式通过 `pip` 安装 Ansible 及其相关依赖的指定版本，否则会有兼容问题。目前，TiDB release-2.0、release-2.1、release-3.0 及最新开发版本兼容 Ansible 2.4 ~ 2.7.11 (2.4 ≤ Ansible ≤ 2.7.11)。 - -1. 在中控机器上安装 Ansible 及其依赖。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - sudo pip install -r ./requirements.txt - ``` - - Ansible 及相关依赖的版本信息记录在 `tidb-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 的版本。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.7.11 - ``` - -## 第 5 步：在中控机上配置部署机器 SSH 互信及 sudo 规则 - -以 `tidb` 用户登录中控机，然后执行以下步骤： - -1. 将你的部署目标机器 IP 添加到 `hosts.ini` 文件的 `[servers]` 区块下。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - vi hosts.ini - ``` - - ```ini - [servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - - [all:vars] - username = tidb - ntp_server = pool.ntp.org - ``` - -2. 执行以下命令，按提示输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，并配置 sudo 规则，配置中控机与部署目标机器之间的 SSH 互信。 - -如果要手工配置 SSH 互信及 sudo 免密码，可参考[如何手工配置 ssh 互信及 sudo 免密码](#如何手工配置-ssh-互信及-sudo-免密码)。 - -## 第 6 步：在部署目标机器上安装 NTP 服务 - -> **注意：** -> -> 如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略。可参考[如何检测 NTP 服务是否正常](#如何检测-ntp-服务是否正常)。 - -以 `tidb` 用户登录中控机，执行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/tidb-ansible && \ -ansible-playbook -i hosts.ini deploy_ntp.yml -u tidb -b -``` - -该步骤将在部署目标机器上使用系统自带软件源联网安装并启动 NTP 服务，服务使用安装包默认的 NTP server 列表，见配置文件 `/etc/ntp.conf` 中 server 参数。如果使用默认的 NTP server，你的机器需要连接外网。 - -为了让 NTP 尽快开始同步，启动 NTP 服务前，系统会执行 `ntpdate` 命令，与用户在 `hosts.ini` 文件中指定的 `ntp_server` 同步日期与时间。默认的服务器为 `pool.ntp.org`，也可替换为你的 NTP server。 - -## 第 7 步：在部署目标机器上配置 CPUfreq 调节器模式 - -为了让 CPU 发挥最大性能，请将 CPUfreq 调节器模式设置为 `performance` 模式。如需了解 CPUfreq 的更多信息，可查看[使用 CPUFREQ 调控器](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/power_management_guide/cpufreq_governors#cpufreq_setup)文档。 - -### 查看系统支持的调节器模式 - -执行以下 `cpupower` 命令，可查看系统支持的调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: performance powersave -``` - -> **注意：** -> -> 本例中系统支持设置 `performance` 和 `powersave` 模式。如果返回 `Not Available`，表示当前系统不支持配置 CPUfreq，跳过该步骤即可。 - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: Not Available -``` - -### 查看系统当前的 CPUfreq 调节器模式 - -执行以下 `cpupower` 命令，可查看系统当前的 CPUfreq 调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --policy -``` - -``` -analyzing CPU 0: - current policy: frequency should be within 1.20 GHz and 3.20 GHz. - The governor "powersave" may decide which speed to use - within this range. -``` - -如上述代码所示，本例中的当前配置是 `powersave` 模式。 - -### 修改调节器模式 - -你可以通过以下两种方法来修改调节器模式。本例中，当前调节器模式为 `powersave`，以下命令会将模式变更为 `performance`。 - -- 使用 `cpupower frequency-set --governor` 命令来修改。 - - {{< copyable "shell-root" >}} - - ```bash - cpupower frequency-set --governor performance - ``` - -- 使用以下命令在部署目标机器上批量设置。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i hosts.ini all -m shell -a "cpupower frequency-set --governor performance" -u tidb -b - ``` - -## 第 8 步：在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -使用 `root` 用户登录目标机器，将部署目标机器数据盘格式化成 ext4 文件系统，挂载时添加 `nodelalloc` 和 `noatime` 挂载参数。`nodelalloc` 是必选参数，否则 Ansible 安装时检测无法通过；`noatime` 是可选建议参数。 - -> **注意：** -> -> 如果你的数据盘已经格式化成 ext4 并挂载了磁盘，可先执行 `umount /dev/nvme0n1p1` 命令卸载，从编辑 `/etc/fstab` 文件步骤开始执行，添加挂载参数重新挂载即可。 - -以 `/dev/nvme0n1` 数据盘为例，具体操作步骤如下： - -1. 查看数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - fdisk -l - ``` - - ``` - Disk /dev/nvme0n1: 1000 GB - ``` - -2. 创建分区表。 - - {{< copyable "shell-root" >}} - - ```bash - parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1 - ``` - - > **注意：** - > - > 使用 `lsblk` 命令查看分区的设备号：对于 nvme 磁盘，生成的分区设备号一般为 `nvme0n1p1`；对于普通磁盘（例如 `/dev/sdb`），生成的的分区设备号一般为 `sdb1`。 - -3. 格式化文件系统。 - - {{< copyable "shell-root" >}} - - ```bash - mkfs.ext4 /dev/nvme0n1p1 - ``` - -4. 查看数据盘分区 UUID。 - - 本例中 `nvme0n1p1` 的 UUID 为 `c51eb23b-195c-4061-92a9-3fad812cc12f`。 - - {{< copyable "shell-root" >}} - - ```bash - lsblk -f - ``` - - ``` - NAME FSTYPE LABEL UUID MOUNTPOINT - sda - ├─sda1 ext4 237b634b-a565-477b-8371-6dff0c41f5ab /boot - ├─sda2 swap f414c5c0-f823-4bb1-8fdf-e531173a72ed - └─sda3 ext4 547909c1-398d-4696-94c6-03e43e317b60 / - sr0 - nvme0n1 - └─nvme0n1p1 ext4 c51eb23b-195c-4061-92a9-3fad812cc12f - ``` - -5. 编辑 `/etc/fstab` 文件，添加 `nodelalloc` 挂载参数。 - - {{< copyable "shell-root" >}} - - ```bash - vi /etc/fstab - ``` - - ``` - UUID=c51eb23b-195c-4061-92a9-3fad812cc12f /data1 ext4 defaults,nodelalloc,noatime 0 2 - ``` - -6. 挂载数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - mkdir /data1 && \ - mount -a - ``` - -7. 执行以下命令，如果文件系统为 ext4，并且挂载参数中包含 `nodelalloc`，则表示已生效。 - - {{< copyable "shell-root" >}} - - ```bash - mount -t ext4 - ``` - - ``` - /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered) - ``` - -## 第 9 步：编辑 `inventory.ini` 文件，分配机器资源 - -以 `tidb` 用户登录中控机，编辑 `/home/tidb/tidb-ansible/inventory.ini` 文件为 TiDB 集群分配机器资源。一个标准的 TiDB 集群需要 6 台机器：2 个 TiDB 实例，3 个 PD 实例，3 个 TiKV 实例。 - -- 至少需部署 3 个 TiKV 实例。 -- 不要将 TiKV 实例与 TiDB 或 PD 实例混合部署在同一台机器上。 -- 将第一台 TiDB 机器同时用作监控机。 - -> **注意：** -> -> 请使用内网 IP 来部署集群，如果部署目标机器 SSH 端口非默认的 22 端口，需添加 `ansible_port` 变量，如 `TiDB1 ansible_host=172.16.10.1 ansible_port=5555`。 - -你可以根据实际场景从以下两种集群拓扑中选择一种： - -- [单机单 TiKV 实例集群拓扑](#单机单-tikv-实例集群拓扑) - - 默认情况下，建议在每个 TiKV 节点上仅部署一个 TiKV 实例，以提高性能。但是，如果你的 TiKV 部署机器的 CPU 和内存配置是[部署建议](/v3.0/how-to/deploy/hardware-recommendations.md)的两倍或以上，并且一个节点拥有两块 SSD 硬盘或者单块 SSD 硬盘的容量大于 2 TB，则可以考虑部署两实例，但不建议部署两个以上实例。 - -- [单机多 TiKV 实例集群拓扑](#单机多-tikv-实例集群拓扑) - -### 单机单 TiKV 实例集群拓扑 - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -[tikv_servers] -172.16.10.4 -172.16.10.5 -172.16.10.6 - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 -``` - -### 单机多 TiKV 实例集群拓扑 - -以两实例为例： - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1-1, TiKV1-2 | -| node5 | 172.16.10.5 | TiKV2-1, TiKV2-2 | -| node6 | 172.16.10.6 | TiKV3-1, TiKV3-2 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -# 注意：要使用 TiKV 的 labels，必须同时配置 PD 的 location_labels 参数，否则 labels 设置不生效。 -[tikv_servers] -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv1" -TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv1" -TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv2" -TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv2" -TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv3" -TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv3" - -# 部署 3.0 版本的 TiDB 集群时，多实例场景需要额外配置 status 端口，示例如下： -# TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" -# TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" -# TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" -# TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" -# TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" -# TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 - -# 注意：为使 TiKV 的 labels 设置生效，部署集群时必须设置 PD 的 location_labels 参数。 -[pd_servers:vars] -location_labels = ["host"] -``` - -- 服务配置文件参数调整 - - 1. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `block-cache-size` 下面的 `capacity` 参数： - - ```yaml - storage: - block-cache: - capacity: "1GB" - ``` - - > **注意：** - > - > TiKV 实例数量指每个服务器上 TiKV 的进程数量。 - > - > 推荐设置：`capacity` = MEM_TOTAL * 0.5 / TiKV 实例数量 - - 2. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ```yaml - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 推荐配置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 - - 3. 如果多个 TiKV 实例部署在同一块物理磁盘上，需要修改 `conf/tikv.yml` 中的 `capacity` 参数： - - ```yaml - raftstore: - capacity: 0 - ``` - - > **注意：** - > - > 推荐配置：`capacity` = 磁盘总容量 / TiKV 实例数量，例如：`capacity: "100GB"`。 - -## 第 10 步：调整 `inventory.ini` 文件中的变量 - -本小节介绍如何编辑部署目录的变量和 `inventory.ini` 文件中的其它变量。 - -### 调整部署目录 - -部署目录通过 `deploy_dir` 变量控制，默认全局变量已设置为 `/home/tidb/deploy`，对所有服务生效。如数据盘挂载目录为 `/data1`，可设置为 `/data1/deploy`，样例如下： - -```ini -## Global variables -[all:vars] -deploy_dir = /data1/deploy -``` - -如为某一服务单独设置部署目录，可在配置服务主机列表时配置主机变量，以 TiKV 节点为例，其他服务类推，请务必添加第一列别名，以免服务混布时混淆。 - -```ini -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy -``` - -### 调整其它变量（可选） - -> **注意：** -> -> 以下控制变量开启请使用首字母大写 `True`，关闭请使用首字母大写 `False`。 - -| 变量 | 含义 | -| :--------------- | :---------------------------------------------------------- | -| `cluster_name` | 集群名称，可调整 | -| `tidb_version` | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| `process_supervision` | 进程监管方式，默认为 `systemd`，可选 `supervise` | -| `timezone` | 新安装 TiDB 集群第一次启动 bootstrap（初始化）时，将 TiDB 全局默认时区设置为该值。TiDB 使用的时区后续可通过 `time_zone` 全局变量和 session 变量来修改，参考[时区支持](/v3.0/how-to/configure/time-zone.md)。默认为 `Asia/Shanghai`，可选值参考 [timzone 列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。 | -| `enable_firewalld` | 开启防火墙，默认不开启，如需开启，请将[部署建议-网络要求](/v3.0/how-to/deploy/hardware-recommendations.md#网络要求) 中的端口加入白名单 | -| `enable_ntpd` | 检测部署目标机器 NTP 服务，默认为 `True`，请勿关闭 | -| `set_hostname` | 根据 IP 修改部署目标机器主机名，默认为 `False` | -| `enable_binlog` | 是否部署 Pump 并开启 binlog，默认为 `False`，依赖 Kafka 集群，参见 `zookeeper_addrs` 变量 | -| `zookeeper_addrs` | binlog Kafka 集群的 zookeeper 地址 | -| `deploy_without_tidb` | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 `inventory.ini` 文件中 `tidb_servers` 主机组的 IP 设置为空。| -| `alertmanager_target` | 可选：如果你已单独部署 alertmanager，可配置该变量，格式：`alertmanager_host:alertmanager_port` | -| `grafana_admin_user` | Grafana 管理员帐号用户名，默认为 admin | -| `grafana_admin_password` | Grafana 管理员帐号密码，默认为 admin，用于 Ansible 导入 Dashboard 和创建 API Key，如后期通过 grafana web 修改了密码，请更新此变量 | -| `collect_log_recent_hours` | 采集日志时，采集最近几个小时的日志，默认为 2 小时 | -| `enable_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时，是否限速，默认为 `True`，与 `collect_bandwidth_limit` 变量结合使用 | -| `collect_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时限速多少，单位: Kbit/s，默认 10000，即 10Mb/s，如果是单机多 TiKV 实例部署方式，需除以单机实例个数 | -| `prometheus_storage_retention` | Prometheus 监控数据的保留时间（默认为 30 天）；2.1.7、3.0 以及之后的 tidb-ansible 版本中，`group_vars/monitoring_servers.yml` 文件里新增的配置 | - -## 第 11 步：部署 TiDB 集群 - -`ansible-playbook` 执行 Playbook 时，默认并发为 5。部署目标机器较多时，可添加 `-f` 参数指定并发数，例如 `ansible-playbook deploy.yml -f 10`。以下示例使用 `tidb` 用户作为服务运行用户： - -1. 在 `tidb-ansible/inventory.ini` 文件中，确认 `ansible_user = tidb`。 - - ```ini - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - > **注意：** - > - > 不要将 `ansible_user` 设置为 `root` 用户，因为 `tidb-ansible` 限制了服务以普通用户运行。 - - 执行以下命令，如果所有 server 均返回 `tidb`，表示 SSH 互信配置成功： - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 执行以下命令，如果所有 server 均返回 `root`，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到中控机。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -3. 初始化系统环境，修改内核参数。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml - ``` - -4. 部署 TiDB 集群软件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - - > **注意：** - > - > Grafana Dashboard 上的 **Report** 按钮可用来生成 PDF 文件，此功能依赖 `fontconfig` 包和英文字体。如需使用该功能，登录 **grafana_servers** 机器，用以下命令安装： - > - > {{< copyable "shell-regular" >}} - > - > ```bash - > sudo yum install fontconfig open-sans-fonts - > ``` - -5. 启动 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - -## 测试集群 - -TiDB 兼容 MySQL，因此可使用 MySQL 客户端直接连接 TiDB。推荐配置负载均衡以提供统一的 SQL 接口。 - -1. 使用 MySQL 客户端连接 TiDB 集群。TiDB 服务的默认端口为 `4000`。 - - {{< copyable "sql" >}} - - ```sql - mysql -u root -h 172.16.10.1 -P 4000 - ``` - -2. 通过浏览器访问监控平台。 - - - 地址： - - 默认帐号与密码：`admin`；`admin` - -## 常见部署问题 - -本小节介绍使用 Ansible 部署 TiDB 集群过程中的常见问题与解决方案。 - -### 如何自定义端口 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 端口变量 | 默认端口 | 说明 | -| :-- | :-- | :-- | :-- | -| TiDB | tidb_port | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | tidb_status_port | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | tikv_port | 20160 | TiKV 通信端口 | -| TiKV | tikv_status_port | 20180 | 上报 TiKV 状态的通信端口 | -| PD | pd_client_port | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | pd_peer_port | 2380 | PD 集群节点间通信端口 | -| Pump | pump_port | 8250 | Pump 通信端口 | -| Prometheus | prometheus_port | 9090 | Prometheus 服务通信端口 | -| Pushgateway | pushgateway_port | 9091 | TiDB， TiKV， PD 监控聚合和上报端口 | -| Node_exporter | node_exporter_port | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | blackbox_exporter_port | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | grafana_port | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | grafana_collector_port | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | kafka_exporter_port | 9308 | Kafka_exporter 通信端口，用于监控 binlog Kafka 集群 | - -### 如何自定义部署目录 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 目录变量 | 默认目录 | 说明 | -| :-- | :-- | :-- | :-- | -| 全局 | deploy_dir | /home/tidb/deploy | 部署目录 | -| TiDB | tidb_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_data_dir | {{ deploy_dir }}/data | 数据目录 | -| TiKV | wal_dir | "" | rocksdb write-ahead 日志目录，为空时与 TiKV 数据目录一致 | -| TiKV | raftdb_path | "" | raftdb 目录，为空时为 tikv_data_dir/raft | -| PD | pd_log_dir | {{ deploy_dir }}/log | 日志目录 | -| PD | pd_data_dir | {{ deploy_dir }}/data.pd | 数据目录 | -| pump | pump_log_dir | {{ deploy_dir }}/log | 日志目录 | -| pump | pump_data_dir | {{ deploy_dir }}/data.pump | 数据目录 | -| prometheus | prometheus_log_dir | {{ deploy_dir }}/log | 日志目录 | -| prometheus | prometheus_data_dir | {{ deploy_dir }}/data.metrics | 数据目录 | -| pushgateway | pushgateway_log_dir | {{ deploy_dir }}/log | 日志目录 | -| node_exporter | node_exporter_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_data_dir | {{ deploy_dir }}/data.grafana | 数据目录 | - -### 如何检测 NTP 服务是否正常 - -1. 执行以下命令，如果输出 `running` 表示 NTP 服务正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl status ntpd.service - ``` - - ``` - ntpd.service - Network Time Service - Loaded: loaded (/usr/lib/systemd/system/ntpd.service; disabled; vendor preset: disabled) - Active: active (running) since 一 2017-12-18 13:13:19 CST; 3s ago - ``` - -2. 执行 `ntpstat` 命令，如果输出 `synchronised to NTP server`（正在与 NTP server 同步），表示在正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - synchronised to NTP server (85.199.214.101) at stratum 2 - time correct to within 91 ms - polling server every 1024 s - ``` - -> **注意：** -> -> Ubuntu 系统需安装 `ntpstat` 软件包。 - -- 以下情况表示 NTP 服务未正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - unsynchronised - ``` - -- 以下情况表示 NTP 服务未正常运行： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - Unable to talk to NTP daemon. Is it running? - ``` - -- 如果要使 NTP 服务尽快开始同步，执行以下命令。可以将 `pool.ntp.org` 替换为你的 NTP server： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl stop ntpd.service && \ - sudo ntpdate pool.ntp.org && \ - sudo systemctl start ntpd.service - ``` - -- 如果要在 CentOS 7 系统上手动安装 NTP 服务，可执行以下命令： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install ntp ntpdate && \ - sudo systemctl start ntpd.service && \ - sudo systemctl enable ntpd.service - ``` - -### 如何调整进程监管方式从 supervise 到 systemd - -{{< copyable "shell-root" >}} - -```shell -process supervision, [systemd, supervise] -``` - -``` -process_supervision = systemd -``` - -TiDB Anisble 在 TiDB v1.0.4 版本之前进程监管方式默认为 `supervise`。之前安装的集群可保持不变，如需更新为 `systemd`，需关闭集群，按以下方式变更： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml && \ -ansible-playbook deploy.yml -D && \ -ansible-playbook start.yml -``` - -### 如何手工配置 SSH 互信及 sudo 免密码 - -1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 - - {{< copyable "shell-root" >}} - - ```bash - useradd tidb && \ - passwd tidb - ``` - -2. 执行以下命令，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾，即配置好 sudo 免密码。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -3. 以 `tidb` 用户登录到中控机，执行以下命令。将 `172.16.10.61` 替换成你的部署目标机器 IP，按提示输入部署目标机器 `tidb` 用户密码，执行成功后即创建好 SSH 互信，其他机器同理。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-copy-id -i ~/.ssh/id_rsa.pub 172.16.10.61 - ``` - -4. 以 `tidb` 用户登录到中控机，通过 `ssh` 的方式登录目标机器 IP。如果不需要输入密码并登录成功，即表示 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh 172.16.10.61 - ``` - - ``` - [tidb@172.16.10.61 ~]$ - ``` - -5. 以 `tidb` 用户登录到部署目标机器后，执行以下命令，不需要输入密码并切换到 `root` 用户，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - sudo -su root - ``` - - ``` - [root@172.16.10.61 tidb]# - ``` - -### You need to install jmespath prior to running json_query filter 报错 - -1. 请参照[在中控机器上安装 Ansible 及其依赖](#在中控机器上安装-ansible-及其依赖) 在中控机上通过 `pip` 安装 Ansible 及相关依赖的指定版本，默认会安装 `jmespath`。 - -2. 执行以下命令，验证 `jmespath` 是否安装成功： - - {{< copyable "shell-regular" >}} - - ```bash - pip show jmespath - ``` - - ``` - Name: jmespath - Version: 0.9.0 - ``` - -3. 在中控机上 Python 交互窗口里 `import jmespath`。 - - - 如果没有报错，表示依赖安装成功。 - - 如果有 `ImportError: No module named jmespath` 报错，表示未成功安装 Python `jmespath` 模块。 - - {{< copyable "shell-regular" >}} - - ```bash - python - ``` - - ``` - Python 2.7.5 (default, Nov 6 2016, 00:28:07) - [GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - ``` - - {{< copyable "shell-regular" >}} - - ```shell - import jmespath - ``` - -### 启动 Pump/Drainer 报 `zk: node does not exist` 错误 - -请检查 `inventory.ini` 里的 `zookeeper_addrs` 参数配置与 Kafka 集群内的配置是否相同、是否填写了命名空间。关于命名空间的配置说明如下： - -```ini -# ZooKeeper connection string (see ZooKeeper docs for details). -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes. Example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -``` diff --git a/v3.0/how-to/deploy/orchestrated/docker.md b/v3.0/how-to/deploy/orchestrated/docker.md deleted file mode 100644 index 56b6e4155042..000000000000 --- a/v3.0/how-to/deploy/orchestrated/docker.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: TiDB Docker 部署方案 -category: how-to -aliases: ['/docs-cn/op-guide/docker-deployment/'] ---- - -# TiDB Docker 部署方案 - -本文介绍如何使用 Docker 部署一个多节点的 TiDB 集群。 - -> **警告：** -> -> 对于生产环境，不要使用 Docker 进行部署，而应[使用 Ansible 部署 TiDB 集群](/v3.0/how-to/deploy/orchestrated/ansible.md)。 - -## 环境准备 - -### 安装 Docker - -Docker 可以方便地在 Linux / Mac OS / Windows 平台安装，安装方法请参考 [Docker 官方文档](https://www.docker.com/products/docker)。 - -### 拉取 TiDB 的 Docker 镜像 - -部署 TiDB 集群主要包括 3 个服务组件: - -- TiDB -- TiKV -- PD - -对应的最新 Docker 镜像可以通过 [Docker 官方镜像仓库](https://hub.docker.com/u/pingcap) 获取： - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/tidb:latest -``` - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/tikv:latest -``` - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/pd:latest -``` - -## 部署一个多节点集群 - -假设我们打算在 6 台主机上部署一个 TiDB 集群: - -| 主机名 | IP | 部署服务 | 数据盘挂载 | -| --------- | ------------- | ---------- | ----- | -| host1 | 192.168.1.101 | PD1 & TiDB | /data | -| host2 | 192.168.1.102 | PD2 | /data | -| host3 | 192.168.1.103 | PD3 | /data | -| host4 | 192.168.1.104 | TiKV1 | /data | -| host5 | 192.168.1.105 | TiKV2 | /data | -| host6 | 192.168.1.106 | TiKV3 | /data | - -### 启动 PD - -登录 **host1** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host2** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd2 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd2" \ - --data-dir="/data/pd2" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.102:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.102:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host3** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd3 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd3" \ - --data-dir="/data/pd3" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.103:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.103:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -### 启动 TiKV - -登录 **host4** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host5** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv2 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.105:20160" \ - --data-dir="/data/tikv2" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host6** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv3 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.106:20160" \ - --data-dir="/data/tikv3" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 启动 TiDB - -登录 **host1** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tidb \ - -p 4000:4000 \ - -p 10080:10080 \ - -v /etc/localtime:/etc/localtime:ro \ - pingcap/tidb:latest \ - --store=tikv \ - --path="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 使用 MySQL 标准客户端连接 TiDB 测试 - -登录 **host1** 并确保已安装 [MySQL 命令行客户端](http://dev.mysql.com/downloads/mysql/)，执行： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -D test -``` - -{{< copyable "sql" >}} - -```sql -show databases; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -### 如何自定义配置文件 - -TiKV 和 PD 可以通过指定配置文件的方式来加载更加丰富的启动参数，用于性能调优。 - -假定配置文件在宿主机上的存放路径 `/path/to/config/pd.toml` 和 `/path/to/config/tikv.toml`。启动 Docker 时需要调整相应的启动参数，以 tikv1 和 pd1 为例： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/tikv.toml:/tikv.toml:ro \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" \ - --config="/tikv.toml" -``` - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/pd.toml:/pd.toml:ro \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" \ - --config="/pd.toml" -``` diff --git a/v3.0/how-to/deploy/orchestrated/offline-ansible.md b/v3.0/how-to/deploy/orchestrated/offline-ansible.md deleted file mode 100644 index eeefe072566f..000000000000 --- a/v3.0/how-to/deploy/orchestrated/offline-ansible.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: 离线 TiDB Ansible 部署方案 -category: how-to -aliases: ['/docs-cn/op-guide/offline-ansible-deployment/'] ---- - -# 离线 TiDB Ansible 部署方案 - -## 准备机器 - -1. 下载机一台 - - - 该机器需开放外网访问，用于下载 TiDB Ansible、TiDB 及相关软件安装包。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统。 - -2. 部署目标机器若干及部署中控机一台 - - - 系统要求及配置参考[准备机器](/v3.0/how-to/deploy/orchestrated/ansible.md#准备机器)。 - - 可以无法访问外网。 - -## 在中控机上安装系统依赖包 - -1. 在下载机上下载[系统依赖离线安装包](https://download.pingcap.org/ansible-system-rpms.el7.tar.gz)，然后上传至中控机。该离线包仅支持 CentOS 7 系统，包含 `pip` 及 `sshpass`。 - -2. 在中控机上安装系统依赖包： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-system-rpms.el7.tar.gz && - cd ansible-system-rpms.el7 && - chmod u+x install_ansible_system_rpms.sh && - ./install_ansible_system_rpms.sh - ``` - -3. 安装完成后，可通过 `pip -V` 验证 pip 是否安装成功： - - {{< copyable "shell-root" >}} - - ```bash - pip -V - ``` - - ``` - pip 8.1.2 from /usr/lib/python2.7/site-packages (python 2.7) - ``` - -> **注意：** -> -> 如果你的系统已安装 pip，请确认版本 >= 8.1.2，否则离线安装 ansible 及其依赖时，会有兼容问题。 - -## 在中控机上创建 tidb 用户，并生成 ssh key - -参考[在中控机上创建 tidb 用户，并生成 ssh key](/v3.0/how-to/deploy/orchestrated/ansible.md#第-2-步在中控机上创建-tidb-用户并生成-ssh-key) 即可。 - -## 在中控机器上离线安装 Ansible 及其依赖 - -以下是 CentOS 7 系统 Ansible 离线安装方式： - -建议使用 Ansible 2.4 至 2.7.11 版本，Ansible 及相关依赖版本记录在 `tidb-ansible/requirements.txt` 文件中。下面步骤以安装 Ansible 2.5 为例。 - -1. 在下载机上下载 [Ansible 2.5 离线安装包](https://download.pingcap.org/ansible-2.5.0-pip.tar.gz)，然后上传至中控机。 - -2. 离线安装 Ansible 及相关依赖： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-2.5.0-pip.tar.gz && - cd ansible-2.5.0-pip/ && - chmod u+x install_ansible.sh && - ./install_ansible.sh - ``` - -3. 安装完成后，可通过 `ansible --version` 查看版本： - - {{< copyable "shell-root" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 在下载机上下载 TiDB Ansible 及 TiDB 安装包 - -1. 在下载机上安装 Ansible： - - 请按以下方式在 CentOS 7 系统的下载机上在线安装 Ansible。安装完成后，可通过 `ansible --version` 查看版本，请务必确认是 **Ansible 2.5.0** 版本，否则会有兼容问题。 - - {{< copyable "shell-root" >}} - - ```bash - yum install epel-release && - yum install ansible curl && - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -2. 下载 tidb-ansible： - - 使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 3.0 [相应 TAG 版本](https://github.com/pingcap/tidb-ansible/tags)，默认的文件夹名称为 `tidb-ansible`。 - - {{< copyable "shell-regular" >}} - - ```bash - git clone -b $tag https://github.com/pingcap/tidb-ansible.git - ``` - - > **注意：** - > - > - 将 `$tag` 替换为选定的 TAG 版本的值，例如 `v3.0.2`。 - > - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 - -3. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到下载机： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-ansible && - ansible-playbook local_prepare.yml - ``` - -4. 将执行完以上命令之后的 `tidb-ansible` 文件夹拷贝到中控机 `/home/tidb` 目录下，文件属主权限需是 `tidb` 用户。 - -## 在中控机上配置部署机器 SSH 互信及 sudo 规则 - -参考[在中控机上配置部署机器 SSH 互信及 sudo 规则](/v3.0/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)即可。 - -## 在部署目标机器上安装 NTP 服务 - -如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略，可参考[如何检测 NTP 服务是否正常](/v3.0/how-to/deploy/orchestrated/ansible.md#第-6-步在部署目标机器上安装-ntp-服务)。 - -参考[在部署目标机器上安装 NTP 服务](/v3.0/how-to/deploy/orchestrated/ansible.md#在部署目标机器上安装-ntp-服务)即可。 - -## 在部署目标机器上配置 CPUfreq 调节器模式 - -参考[在部署目标机器上配置 CPUfreq 调节器模式](/v3.0/how-to/deploy/orchestrated/ansible.md#第-7-步在部署目标机器上配置-cpufreq-调节器模式)即可。 - -## 在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -参考[在部署目标机器上添加数据盘 ext4 文件系统挂载参数](/v3.0/how-to/deploy/orchestrated/ansible.md#第-8-步在部署目标机器上添加数据盘-ext4-文件系统挂载参数)即可。 - -## 分配机器资源，编辑 inventory.ini 文件 - -参考[分配机器资源，编辑 inventory.ini 文件](/v3.0/how-to/deploy/orchestrated/ansible.md#第-9-步编辑-inventoryini-文件分配机器资源)即可。 - -## 部署任务 - -1. `ansible-playbook local_prepare.yml` 该 playbook 不需要再执行。 - -2. 参考[部署任务](/v3.0/how-to/deploy/orchestrated/ansible.md#第-11-步部署-tidb-集群)即可。 - -## 测试集群 - -参考[测试集群](/v3.0/how-to/deploy/orchestrated/ansible.md#测试集群)即可。 diff --git a/v3.0/how-to/get-started/data-migration.md b/v3.0/how-to/get-started/data-migration.md deleted file mode 100644 index b595dc4c636d..000000000000 --- a/v3.0/how-to/get-started/data-migration.md +++ /dev/null @@ -1,523 +0,0 @@ ---- -title: TiDB Data Migration 教程 -category: how-to ---- - -# TiDB Data Migration 教程 - -TiDB Data Migration (DM) 是一体化的数据同步任务管理平台，支持将大量、复杂的生产环境中的数据从 MySQL 或 MariaDB 迁移到 TiDB。 - -DM 功能如下： - -- 数据迁移 - - 支持导出与导入源数据库的初始全量数据，并在数据迁移过程中读取、应用来自源数据库存储的 binlog，从而保持数据的同步。 - - 通过合并上游的多个 MySQL 或 MariaDB 实例或集群的表，DM 能迁移生产环境中的分库分表。 -- 将 TiDB 作为 MySQL 或 MariaDB 的从库时，DM 能持续提高数据库水平扩展的能力，或在无需 ETL 作业的情况下，在 TiDB 上进行数据实时分析。 - -本教程主要介绍如何使用 DM 迁移上游多个 MySQL 实例的一个分片表。包括两种场景： - -- 合并若干个互不冲突的表或分片，即这些表或分片的表结构并不会造成唯一键的冲突； -- 合并唯一键存在冲突的表。 - -本教程假设目前使用的是一台新的、纯净版 CentOS 7 实例，你能（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为需要运行多个服务，建议内存最好在 1 GB 以上。 - -> **警告：** -> -> 本教程中 TiDB 的部署方法并**不适用**于生产或开发环境。 - -## Data Migration 架构 - -![TiDB Data Migration 架构](/media/dm-architecture.png) - -TiDB Data Migration 平台由 3 部分组成：DM-master、DM-worker 和 dmctl。 - -* DM-master 负责管理和调度数据同步任务的操作。 -* DM-worker 负责执行特定的数据同步任务。 -* dmctl 是一个命令行工具，用于控制 DM 集群。 - -`.yaml` 文件中定义了各个数据同步任务，dmctl 会读取这些文件，并且这些文件会被提交给 DM-master。DM-master 再将关于给定任务的相应职责告知每个 DM-worker 实例。 - -详情参见 [Data Migration 简介](/v3.0/reference/tools/data-migration/overview.md)。 - -## 安装 - -本部分介绍如何部署 3 个 MySQL Server 实例及 `pd-server`、`tikv-server` 和 `tidb-server` 实例各 1 个，以及如何启动 1 个 DM-master 和 3 个 DM-worker 实例。 - -1. 安装 MySQL 5.7，下载或提取 TiDB v3.0 以及 DM v1.0.2 安装包： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install -y http://repo.mysql.com/yum/mysql-5.7-community/el/7/x86_64/mysql57-community-release-el7-10.noarch.rpm && - sudo yum install -y mysql-community-server && - curl https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - && - curl https://download.pingcap.org/dm-v1.0.2-linux-amd64.tar.gz | tar xzf - && - curl -L https://github.com/pingcap/docs/raw/master/dev/how-to/get-started/dm-cnf/dm-cnf.tgz | tar xvzf - - ``` - -2. 创建目录和符号链接： - - {{< copyable "shell-regular" >}} - - ```bash - mkdir -p bin data logs && - ln -sf -t bin/ "$HOME"/*/bin/* && - [[ :$PATH: = *:$HOME/bin:* ]] || echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile && . ~/.bash_profile - ``` - -3. 安装 3 个 MySQL Server 实例的配置： - - {{< copyable "shell-regular" >}} - - ```bash - tee -a "$HOME/.my.cnf" <}} - - ```bash - for i in 1 2 3 - do - echo "mysql$i" - mysqld --defaults-group-suffix="$i" --initialize-insecure - mysqld --defaults-group-suffix="$i" & - done - ``` - -5. 执行 `jobs` 和/或 `pgrep -a mysqld` 以确保 MySQL Server 实例都在运行状态。 - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running mysqld --defaults-group-suffix="$i" & - [2]- Running mysqld --defaults-group-suffix="$i" & - [3]+ Running mysqld --defaults-group-suffix="$i" & - ``` - - {{< copyable "shell-regular" >}} - - ```bash - pgrep -a mysqld - ``` - - ``` - 17672 mysqld --defaults-group-suffix=1 - 17727 mysqld --defaults-group-suffix=2 - 17782 mysqld --defaults-group-suffix=3 - ``` - -## 同步分片数据 - -本示例场景包含 3 个分片，这些分片表结构相同，但自增主键并不重叠。 - -在 `.my.cnf` 文件中设置 `auto-increment-increment=5` 和 `auto-increment-offset` 可以实现这种情况。将 `auto-increment-increment` 设置为 5，则这些实例的自增 ID 以 5 为单位递增；每个实例的 `auto-increment-offset` 都设置得不同，则这些实例的偏移为 0 到开始计数的值。例如，若一个实例的 `auto-increment-increment` 为 5，`auto-increment-offset` 为 2，则会生成自增 ID 序列 {2,7,12,17,22,…}。 - -1. 对于这 3 个 MySQL Server 实例，每个实例都分别创建数据库和表： - - {{< copyable "shell-regular" >}} - - ```bash - for i in 1 2 3 - do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root <}} - - ```bash - for i in 1 2 3; do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root dmtest1 <}} - - ```bash - for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select * from dmtest1.t1' - done | sort -n - ``` - -注意返回的列表左侧是一列递增的、无重叠的 ID，右侧的端口编号显示这些数据插入到哪些实例以及从哪些实例中查询： - -``` -... -1841 e8dfff4676a47048d6f0c4ef899593dd 3307 -1842 57c0531e13f40b91b3b0f1a30b529a1d 3308 -1843 4888241374e8c62ddd9b4c3cfd091f96 3309 -1846 f45a1078feb35de77d26b3f7a52ef502 3307 -1847 82cadb0649a3af4968404c9f6031b233 3308 -1848 7385db9a3f11415bc0e9e2625fae3734 3309 -1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 -1852 eb1e78328c46506b46a4ac4a1e378b91 3308 -1853 7503cfacd12053d309b6bed5c89de212 3309 -1856 3c947bc2f7ff007b86a9428b74654de5 3307 -1857 a3545bd79d31f9a72d3a78690adf73fc 3308 -1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 -``` - -### 启动 DM-master 和 DM-worker - -本小节介绍如何使用 DM 将来自不同的 MySQL 实例的数据合并到 TiDB 的一张表里。 - -配置文件包 `dm-cnf.tgz` 包含： - -- TiDB 集群组件和 DM 组件的配置 -- 本教程后文介绍的 2 个 DM 任务的配置 - -1. 启动单个 `tidb-server` 实例、每个 MySQL Server 实例 （总共 3 个实例）的 DM-worker 进程和一个 DM-master 进程： - - {{< copyable "shell-regular" >}} - - ```bash - tidb-server --log-file=logs/tidb-server.log & - for i in 1 2 3; do dm-worker --config=dm-cnf/dm-worker$i.toml & done - dm-master --config=dm-cnf/dm-master.toml & - ``` - -2. 执行 `jobs` 和/或 `ps -a`，确保这些进程都正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running mysqld --defaults-group-suffix="$i" & - [2] Running mysqld --defaults-group-suffix="$i" & - [3] Running mysqld --defaults-group-suffix="$i" & - [4] Running tidb-server --log-file=logs/tidb-server.log & - [5] Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [6] Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [7]- Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [8]+ Running dm-master --config=dm-cnf/dm-master.toml & - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ps -a - ``` - - ``` - PID TTY TIME CMD - 17317 pts/0 00:00:00 screen - 17672 pts/1 00:00:04 mysqld - 17727 pts/1 00:00:04 mysqld - 17782 pts/1 00:00:04 mysqld - 18586 pts/1 00:00:02 tidb-server - 18587 pts/1 00:00:00 dm-worker - 18588 pts/1 00:00:00 dm-worker - 18589 pts/1 00:00:00 dm-worker - 18590 pts/1 00:00:00 dm-master - 18892 pts/1 00:00:00 ps - ``` - -每个上游的 MySQL Server 实例对应一个单独的 DM-worker 实例，每个 DM-worker 实例都有各自的配置文件。这些文件内容包括： - -- 连接到上游 MySQL Server 的详细信息 -- relay log（上游服务器的 binlog）的存储路径 -- mydumper 的输出 - -各个 DM-worker 通过不同的端口监听（由 `worker-addr` 定义）。 - -以下为 `dm-worker1.toml` 的示例： - -{{< copyable "" >}} - -```toml -# DM-worker 配置 - -server-id = 1 -source-id = "mysql1" -flavor = "mysql" -worker-addr = ":8262" -log-file = "logs/worker1.log" -relay-dir = "data/relay1" -meta-dir = "data/meta1" -dir = "data/dump1" - -[from] -host = "127.0.0.1" -user = "root" -password = "" -port = 3307 -``` - -- 如果从 MySQL Server、Percona Server、Percona XtraDB Cluster、Amazon Aurora 或 RDS 迁移数据，则 `flavor` 配置项应设为 "mysql"（默认值，支持 5.5 < MySQL 版本 < 8.0）。 -- 如果从 MariaDB Server 或 MariaDB (Galera) Cluster 迁移数据，则设置 `flavor = "mariadb"`（仅支持 10.1.2 以上 MariaDB 版本）。 -- 从 DM 1.0.2 版本开始，`flavor`、`server-id` 项均会由 DM 自动生成，一般情况下不需要手动配置。 -- `from` 中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见[使用 dmctl 加密上游 MySQL 用户密码](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -任务在 YAML 文件中定义。以下为一个 `dmtask1.yaml` 文件示例： - -{{< copyable "" >}} - -```yaml -name: dmtask1 -task-mode: all -is-sharding: true -enable-heartbeat: true -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - source-id: "mysql1" - server-id: 1 - black-white-list: "dmtest1" - loader-config-name: "loader1" - - source-id: "mysql2" - server-id: 2 - black-white-list: "dmtest1" - loader-config-name: "loader2" - - source-id: "mysql3" - server-id: 3 - black-white-list: "dmtest1" - loader-config-name: "loader3" - -black-white-list: - dmtest1: - do-dbs: ["dmtest1"] - -loaders: - loader1: - dir: "data/dump1" - loader2: - dir: "data/dump2" - loader3: - dir: "data/dump3" -``` - -以上文件包含一些全局配置项和几组定义各种行为的配置项。 - -* `task-mode: all`：DM 导入上游实例的全量备份，并使用上游 MySQL Server 的 binlog 进行增量同步。 - - * 此外，可将 `task-mode` 设置为 `full` 或 `incremental` 以分别进行全量备份或增量同步。 - -* `is-sharding: true`：多个 DM-worker 实例进行同一个任务，这些实例将上游的若干分片合并到一个下游的表中。 - -* `ignore-checking-items: ["auto_increment_ID"]`：关闭 DM 对上游实例中潜在的自增 ID 冲突的检测。DM 能检测出上游表结构相同、并包含自增列的分片间潜在的列值冲突。通过配置 `auto-increment-increment` 和 `auto-increment-offset` 可使每个 MySQL Server 的 ID 都不重叠，从而避免不同表之间冲突的产生。因此，可以让 DM 关闭对自增 ID 冲突的检测。 - -* `black-white-list`：将一个任务限制在数据库 `dmtest` 中。 - -* `loaders`：定义由各个 DM-worker 实例执行的每个 mydumper 实例的输出地址。 - -* `target-database`：定义目标数据库的链接信息，其中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见 [使用 dmctl 加密上游 MySQL 用户密码](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -`dmctl` 是控制 DM 集群的命令行工具，用于启动任务、查询任务状态。执行 `dmctl -master-addr :8261` 获取如下交互提示，从而启动该工具： - -{{< copyable "shell-regular" >}} - -```bash -dmctl -master-addr :8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-alpha-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 - -» -``` - -执行 `start-task dm-cnf/dmtask1.yaml` 启动 `dmtask1`： - -{{< copyable "shell-regular" >}} - -```bash -start-task dm-cnf/dmtask1.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - }, - { - "result": true, - "worker": "127.0.0.1:8264", - "msg": "" - } - ] -} -``` - -启动该任务意味着启动任务配置文件中定义的行为，包括执行 mydumper 和 loader 实例，加载初次 dump 的数据后，将 DM-worker 作为同步任务的 slave 连接到上游的 MySQL Server。 - -所有的行数据都被迁移到 TiDB Server： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -... -1843 4888241374e8c62ddd9b4c3cfd091f96 3309 -1846 f45a1078feb35de77d26b3f7a52ef502 3307 -1847 82cadb0649a3af4968404c9f6031b233 3308 -1848 7385db9a3f11415bc0e9e2625fae3734 3309 -1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 -1852 eb1e78328c46506b46a4ac4a1e378b91 3308 -1853 7503cfacd12053d309b6bed5c89de212 3309 -1856 3c947bc2f7ff007b86a9428b74654de5 3307 -1857 a3545bd79d31f9a72d3a78690adf73fc 3308 -1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 -``` - -现在 DM 正作为每个 MySQL Server 的 slave，读取 MySQL Server 的 binlog，将更新的数据实时同步到下游的 TiDB Server： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3 -do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select host, command, state from information_schema.processlist where command="Binlog Dump"' -done -``` - -输出结果： - -``` -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:42168 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:42922 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:56798 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -``` - -向上游 MySQL Server 插入几行数据，更新 MySQL 中的这些行，并再次查询这些行： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'insert into t1 (id) select null from t1' dmtest1 -done -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -6313 NULL NULL -6316 NULL NULL -6317 NULL NULL -6318 NULL NULL -6321 NULL NULL -6322 NULL NULL -6323 NULL NULL -6326 NULL NULL -6327 NULL NULL -6328 NULL NULL -``` - -更新这些行，则可见更新的数据已同步到 TiDB 中： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'update t1 set c=md5(id), port=@@port' dmtest1 -done | sort -n -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -6313 2118d8a1b7004ed5baf5347a4f99f502 3309 -6316 6107d91fc9a0b04bc044aa7d8c1443bd 3307 -6317 0e9b734aa25ca8096cb7b56dc0dd8929 3308 -6318 b0eb9a95e8b085e4025eae2f0d76a6a6 3309 -6321 7cb36e23529e4de4c41460940cc85e6e 3307 -6322 fe1f9c70bdf347497e1a01b6c486bdb9 3308 -6323 14eac0d254a6ccaf9b67584c7830a5c0 3309 -6326 17b65afe58c49edc1bdd812c554ee3bb 3307 -6327 c54bc2ded4480856dc9f39bdcf35a3e7 3308 -6328 b294504229c668e750dfcc4ea9617f0a 3309 -``` - -只要 DM-master 和 DM-worker 运行 `dmtest1` 任务，下游的 TiDB Server 将持续和上游的 MySQL Server 实例保持同步的状态。 - -## 结论 - -本教程完成了上游 3 个 MySQL Server 实例的分片迁移，介绍了分片迁移中，DM 如何在集群中导入初始数据，以及如何读取 MySQL 的 binlog 来同步增量数据，从而使下游 TiDB 集群与上游实例保持同步。 - -关于 DM 的更多详情，请参考 [Data Migration 简介](/v3.0/reference/tools/data-migration/overview.md)，或加入 [TiDB Community Slack](https://pingcap.com/tidbslack/) channel 参与讨论。 diff --git a/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md b/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md deleted file mode 100644 index 5108d9ba0736..000000000000 --- a/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 使用 Docker Compose 快速构建 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/get-started/local-cluster/install-from-docker-compose/'] ---- - -# 使用 Docker Compose 快速构建 TiDB 集群 - -本文档介绍如何在单机上通过 Docker Compose 快速一键部署一套 TiDB 测试集群。[Docker Compose](https://docs.docker.com/compose/overview) 可以通过一个 YAML 文件定义多个容器的应用服务，然后一键启动或停止。 - -> **警告：** -> -> 对于生产环境，不要使用 Docker Compose 进行部署，而应[使用 Ansible 部署 TiDB 集群](/v3.0/how-to/deploy/orchestrated/ansible.md)。 - -## 准备环境 - -确保你的机器上已安装： - -- Docker（17.06.0 及以上版本） -- Docker Compose -- Git - -## 快速部署 - -1. 下载 `tidb-docker-compose` - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -2. 创建并启动集群 - - 获取最新 Docker 镜像： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-docker-compose && docker-compose pull && docker-compose up -d - ``` - -3. 访问集群 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - [集群数据可视化](https://github.com/pingcap/tidb-vision)： - -## 自定义集群 - -在完成快速部署后，以下组件已默认部署：3 个 PD，3 个 TiKV，1 个 TiDB 和监控组件 Prometheus，Pushgateway，Grafana 以及 tidb-vision。 - -如果想自定义集群，可以直接修改 `docker-compose.yml`，但是手动修改比较繁琐而且容易出错，强烈建议使用 [Helm](https://helm.sh) 模板引擎生成 `docker-compose.yml` 文件。 - -1. 安装 Helm - - [Helm](https://helm.sh) 可以用作模板渲染引擎，只需要下载其 binary 文件即可以使用。 - - {{< copyable "shell-regular" >}} - - ```bash - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果是 Mac 系统，也可以通过 Homebrew 安装： - - {{< copyable "shell-regular" >}} - - ```bash - brew install kubernetes-helm - ``` - -2. 下载 `tidb-docker-compose` - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -3. 自定义集群 - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-docker-compose && - cp compose/values.yaml values.yaml && - vim values.yaml - ``` - - 修改 `values.yaml` 里面的配置，例如集群规模，TiDB 镜像版本等。 - - [tidb-vision](https://github.com/pingcap/tidb-vision) 是 TiDB 集群可视化页面，可以可视化地显示 PD 对 TiKV 数据的调度。如果不想部署该组件，可以将 `tidbVision` 项留空。 - - PD，TiKV，TiDB 和 tidb-vision 支持从 GitHub 源码或本地文件构建 Docker 镜像，供开发测试使用。 - - - 如果希望从本地已编译好的 binary 文件构建 PD，TiKV 或 TiDB 镜像，需要将其 `image` 字段留空，并将已编译好的 binary 拷贝到对应的 `pd/bin/pd-server`，`tikv/bin/tikv-server`，`tidb/bin/tidb-server`。 - - - 如果希望从本地构建 tidb-vision 镜像，需要将其 `image` 字段留空，并将 tidb-vision 项目拷贝到 `tidb-vision/tidb-vision`。 - -4. 生成 `docker-compose.yml` 文件 - - {{< copyable "shell-regular" >}} - - ```bash - helm template -f values.yaml compose > generated-docker-compose.yml - ``` - -5. 使用生成的 `docker-compose.yml` 创建并启动集群 - - 获取最新 Docker 镜像： - - {{< copyable "shell-regular" >}} - - ```bash - docker-compose -f generated-docker-compose.yml pull - ``` - - {{< copyable "shell-regular" >}} - - ```bash - docker-compose -f generated-docker-compose.yml up -d - ``` - -6. 访问集群 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - 如果启用了 tidb-vision，可以通过 查看。 - -## 访问 Spark shell 并加载 TiSpark - -向 TiDB 集群中插入一些样本数据： - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master bash && -cd /opt/spark/data/tispark-sample-data && -mysql -h tidb -P 4000 -u root < dss.ddl -``` - -当样本数据加载到 TiDB 集群之后，可以使用 `docker-compose exec tispark-master /opt/spark/bin/spark-shell` 来访问 Spark shell。 - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master /opt/spark/bin/spark-shell -``` - -``` -... -Spark context available as 'sc' (master = local[*], app id = local-1527045927617). -Spark session available as 'spark'. -Welcome to - ____ __ - / __/__ ___ _____/ /__ - _\ \/ _ \/ _ `/ __/ '_/ - /___/ .__/\_,_/_/ /_/\_\ version 2.1.1 - /_/ - -Using Scala version 2.11.8 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_172) -Type in expressions to have them evaluated. -Type :help for more information. -``` - -```shell -scala> import org.apache.spark.sql.TiContext -... -scala> val ti = new TiContext(spark) -... -scala> ti.tidbMapDatabase("TPCH_001") -... -scala> spark.sql("select count(*) from lineitem").show -``` - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -你也可以通过 Python 或 R 来访问 Spark： - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master /opt/spark/bin/pyspark && -docker-compose exec tispark-master /opt/spark/bin/sparkR -``` - -更多关于 TiSpark 的信息，参见 [TiSpark 的详细文档](/v3.0/how-to/get-started/tispark.md)。 diff --git a/v3.0/how-to/get-started/explore-sql.md b/v3.0/how-to/get-started/explore-sql.md deleted file mode 100644 index 0d8cd38956c5..000000000000 --- a/v3.0/how-to/get-started/explore-sql.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: TiDB 中的基本 SQL 操作 -category: how-to -aliases: ['/docs-cn/try-tidb/'] ---- - -# TiDB 中的基本 SQL 操作 - -成功部署 TiDB 集群之后，便可以在 TiDB 中执行 SQL 语句了。因为 TiDB 兼容 MySQL，你可以使用 MySQL 客户端连接 TiDB，并且[大多数情况下](/v3.0/reference/mysql-compatibility.md)可以直接执行 MySQL 语句。 - -本文介绍 CRUD 操作等基本的 SQL 语句。完整的 SQL 语句列表，参见 [TiDB SQL 语法详解](https://pingcap.github.io/sqlgram/)。 - -## 创建、查看和删除数据库 - -使用 `CREATE DATABASE` 语句创建数据库。语法如下： - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE db_name [options]; -``` - -例如，要创建一个名为 `samp_db` 的数据库，可使用以下语句： - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE IF NOT EXISTS samp_db; -``` - -使用 `SHOW DATABASES` 语句查看数据库： - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -使用 `DROP DATABASE` 语句删除数据库，例如： - -{{< copyable "sql" >}} - -```sql -DROP DATABASE samp_db; -``` - -## 创建、查看和删除表 - -使用 `CREATE TABLE` 语句创建表。语法如下： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE table_name column_name data_type constraint; -``` - -例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - number INT(11), - name VARCHAR(255), - birthday DATE - ); -``` - -如果表已存在，添加 `IF NOT EXISTS` 可防止发生错误： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE IF NOT EXISTS person ( - number INT(11), - name VARCHAR(255), - birthday DATE -); -``` - -使用 `SHOW CREATE` 语句查看建表语句。例如： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE table person; -``` - -使用 `SHOW FULL COLUMNS` 语句查看表的列。 例如： - -{{< copyable "sql" >}} - -```sql -SHOW FULL COLUMNS FROM person; -``` - -使用 `DROP TABLE` 语句删除表。例如： - -{{< copyable "sql" >}} - -```sql -DROP TABLE person; -``` - -或者 - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS person; -``` - -使用 `SHOW TABLES` 语句查看数据库中的所有表。例如： - -{{< copyable "sql" >}} - -```sql -SHOW TABLES FROM samp_db; -``` - -## 创建、查看和删除索引 - -对于值不唯一的列，可使用 `CREATE INDEX` 或 `ALTER TABLE` 语句。例如： - -{{< copyable "sql" >}} - -```sql -CREATE INDEX person_num ON person (number); -``` - -或者 - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person ADD INDEX person_num (number); -``` - -对于值唯一的列，可以创建唯一索引。例如： - -{{< copyable "sql" >}} - -```sql -CREATE UNIQUE INDEX person_num ON person (number); -``` - -或者 - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person ADD UNIQUE person_num (number); -``` - -使用 `SHOW INDEX` 语句查看表内所有索引： - -{{< copyable "sql" >}} - -```sql -SHOW INDEX from person; -``` - -使用 `ALTER TABLE` 或 `DROP INDEX` 语句来删除索引。与 `CREATE INDEX` 语句类似，`DROP INDEX` 也可以嵌入 `ALTER TABLE` 语句。例如： - -{{< copyable "sql" >}} - -```sql -DROP INDEX person_num ON person; -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person DROP INDEX person_num; -``` - -## 增删改查数据 - -使用 `INSERT` 语句向表内插入数据。例如： - -{{< copyable "sql" >}} - -```sql -INSERT INTO person VALUES("1","tom","20170912"); -``` - -使用 `SELECT` 语句检索表内数据。例如： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-09-12 | -+--------+------+------------+ -``` - -使用 `UPDATE` 语句修改表内数据。例如： - -{{< copyable "sql" >}} - -```sql -UPDATE person SET birthday='20171010' WHERE name='tom'; -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-10-10 | -+--------+------+------------+ -``` - -使用 `DELETE` 语句删除表内数据： - -{{< copyable "sql" >}} - -```sql -DELETE FROM person WHERE number=1; -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -Empty set (0.00 sec) -``` - -## 创建、授权和删除用户 - -使用 `CREATE USER` 语句创建一个用户 `tiuser`，密码为 `123456`： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456'; -``` - -授权用户 `tiuser` 可检索数据库 `samp_db` 内的表： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost'; -``` - -查询用户 `tiuser` 的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS for tiuser@localhost; -``` - -删除用户 `tiuser`： - -{{< copyable "sql" >}} - -```sql -DROP USER 'tiuser'@'localhost'; -``` diff --git a/v3.0/how-to/get-started/read-historical-data.md b/v3.0/how-to/get-started/read-historical-data.md deleted file mode 100644 index af2adaacf1d8..000000000000 --- a/v3.0/how-to/get-started/read-historical-data.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: 读取历史数据 -category: how-to -aliases: ['/docs-cn/op-guide/history-read/'] ---- - -# 读取历史数据 - -本文档介绍 TiDB 如何读取历史版本数据，包括具体的操作流程以及历史数据的保存策略。 - -## 功能说明 - -TiDB 实现了通过标准 SQL 接口读取历史数据功能，无需特殊的 client 或者 driver。当数据被更新、删除后，依然可以通过 SQL 接口将更新/删除前的数据读取出来。 - -另外即使在更新数据之后，表结构发生了变化，TiDB 依旧能用旧的表结构将数据读取出来。 - -## 操作流程 - -为支持读取历史版本数据， 引入了一个新的 system variable: tidb_snapshot ，这个变量是 Session 范围有效，可以通过标准的 Set 语句修改其值。其值为文本，能够存储 TSO 和日期时间。TSO 即是全局授时的时间戳，是从 PD 端获取的; 日期时间的格式可以为： -“2016-10-08 16:45:26.999”，一般来说可以只写到秒，比如”2016-10-08 16:45:26”。 -当这个变量被设置时，TiDB 会用这个时间戳建立 Snapshot（没有开销，只是创建数据结构），随后所有的 Select 操作都会在这个 Snapshot 上读取数据。 - -> **注意：** -> -> TiDB 的事务是通过 PD 进行全局授时，所以存储的数据版本也是以 PD 所授时间戳作为版本号。在生成 Snapshot 时，是以 tidb_snapshot 变量的值作为版本号，如果 TiDB Server 所在机器和 PD Server 所在机器的本地时间相差较大，需要以 PD 的时间为准。 - -当读取历史版本操作结束后，可以结束当前 Session 或者是通过 Set 语句将 tidb_snapshot 变量的值设为 ""，即可读取最新版本的数据。 - -## 历史数据保留策略 - -TiDB 使用 MVCC 管理版本，当更新/删除数据时，不会做真正的数据删除，只会添加一个新版本数据，所以可以保留历史数据。历史数据不会全部保留，超过一定时间的历史数据会被彻底删除，以减小空间占用以及避免历史版本过多引入的性能开销。 - -TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理，关于 GC 的详细介绍参见 [TiDB 垃圾回收 (GC)](/v3.0/reference/garbage-collection/overview.md)。 - -这里需要重点关注的是 `tikv_gc_life_time` 和 `tikv_gc_safe_point` 这条。`tikv_gc_life_time` 用于配置历史版本保留时间，可以手动修改；`tikv_gc_safe_point` 记录了当前的 safePoint，用户可以安全地使用大于 safePoint 的时间戳创建 snapshot 读取历史版本。safePoint 在每次 GC 开始运行时自动更新。 - -## 示例 - -1. 初始化阶段，创建一个表，并插入几行数据： - - {{< copyable "sql" >}} - - ```sql - create table t (c int); - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - insert into t values (1), (2), (3); - ``` - - ``` - Query OK, 3 rows affected (0.00 sec) - ``` - -2. 查看表中的数据： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -3. 查看当前时间： - - {{< copyable "sql" >}} - - ```sql - select now(); - ``` - - ``` - +---------------------+ - | now() | - +---------------------+ - | 2016-10-08 16:45:26 | - +---------------------+ - 1 row in set (0.00 sec) - ``` - -4. 更新某一行数据： - - {{< copyable "sql" >}} - - ```sql - update t set c=22 where c=2; - ``` - - ``` - Query OK, 1 row affected (0.00 sec) - ``` - -5. 确认数据已经被更新： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -6. 设置一个特殊的环境变量，这个是一个 session scope 的变量，其意义为读取这个时间之前的最新的一个版本。 - - {{< copyable "sql" >}} - - ```sql - set @@tidb_snapshot="2016-10-08 16:45:26"; - ``` - - ``` - Query OK, 0 rows affected (0.00 sec) - ``` - - > **注意：** - > - > - 这里的时间设置的是 update 语句之前的那个时间。 - > - 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 - - 这里读取到的内容即为 update 之前的内容，也就是历史版本： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -7. 清空这个变量后，即可读取最新版本数据： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_snapshot=""; - ``` - - ``` - Query OK, 0 rows affected (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - - > **注意：** - > - > 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 diff --git a/v3.0/how-to/get-started/tidb-binlog.md b/v3.0/how-to/get-started/tidb-binlog.md deleted file mode 100644 index 7da2c874a8f5..000000000000 --- a/v3.0/how-to/get-started/tidb-binlog.md +++ /dev/null @@ -1,520 +0,0 @@ ---- -title: TiDB Binlog 教程 -category: how-to ---- - -# TiDB Binlog 教程 - -本文档主要介绍如何使用 TiDB Binlog 将数据从 TiDB 推送到 MariaDB 实例。文中的 TiDB Binlog 集群包含 Pump 和 Drainer 的单个节点，TiDB 集群包含 TiDB、TiKV 和 Placement Driver (PD) 各组件的单个节点。 - -希望上手实践 TiDB Binlog 工具的用户需要对 [TiDB 架构](/v3.0/architecture.md)有一定的了解，最好有创建过 TiDB 集群的经验。该文档也有助于简单快速了解 TiDB Binlog 架构以及相关概念。 - -> **警告：** -> -> 该文档中部署 TiDB 的操作指导**不适用于**在生产或研发环境中部署 TiDB 的情况。 - -该文档假设用户使用的是现代 Linux 发行版本中的 x86-64。示例中使用的是 VMware 中运行的 CentOS 7 最小化安装。建议在一开始就进行清洁安装，以避免受现有环境中未知情况的影响。如果不想使用本地虚拟环境，也可以使用云服务启动 CentOS 7 VM。 - -## TiDB Binlog 简介 - -TiDB Binlog 用于收集 TiDB 中二进制日志数据、提供实时数据备份和同步以及将 TiDB 集群的数据增量同步到下游。 - -TiDB Binlog 支持以下功能场景： - -- 增量备份，将 TiDB 集群中的数据增量同步到另一个集群，或通过 Kafka 增量同步到选择的下游。 -- 当使用 TiDB DM (Data Migration) 将数据从上游 MySQL 或者 MariaDB 迁移到 TiDB 集群时，可使用 TiDB Binlog 保持 TiDB 集群与其一个独立下游 MySQL 或 MariaDB 实例或集群同步。当 TiDB 集群上游数据迁移过程中出现问题，下游数据同步过程中可使用 TiDB Binlog 恢复数据到原先的状态。 - -更多信息参考 [TiDB Binlog Cluster 版本用户文档](/v3.0/reference/tidb-binlog/overview.md)。 - -## 架构 - -TiDB Binlog 集群由 **Pump** 和 **Drainer** 两个组件组成。一个 Pump 集群中有若干个 Pump 节点。TiDB 实例连接到各个 Pump 节点并发送 binlog 数据到 Pump 节点。Pump 集群连接到 Drainer 节点，Drainer 将接收到的更新数据转换到某个特定下游（例如 Kafka、另一个 TiDB 集群或 MySQL 或 MariaDB Server）指定的正确格式。 - -![TiDB Binlog architecture](/media/tidb_binlog_cluster_architecture.png) - -Pump 的集群架构能确保 TiDB 或 Pump 集群中有新的实例加入或退出时更新数据不会丢失。 - -## 安装 - -由于 RHEL/CentOS 7 的默认包装库中包括 MariaDB Server，本示例选择的是 MariaDB Server。后续除了安装服务器，也需要安装客户端。安装指令如下： - -{{< copyable "shell-regular" >}} - -```bash -sudo yum install -y mariadb-server -``` - -预期输出： - -{{< copyable "shell-regular" >}} - -```bash -curl -LO https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - && -cd tidb-v3.0-linux-amd64/ -``` - -``` - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 279M 100 279M 0 0 4983k 0 0:00:57 0:00:57 --:--:-- 3638k -``` - -## 配置 - -通过执行以下步骤配置一个 TiDB 集群，该集群包括 `pd-server`、`tikv-server` 和 `tidb-server` 各组件的单个实例。 - -1. 填充配置文件： - - {{< copyable "shell-regular" >}} - - ```bash - printf > pd.toml %s\\n 'log-file="pd.log"' 'data-dir="pd.data"' && - printf > tikv.toml %s\\n 'log-file="tikv.log"' '[storage]' 'data-dir="tikv.data"' '[pd]' 'endpoints=["127.0.0.1:2379"]' '[rocksdb]' max-open-files=1024 '[raftdb]' max-open-files=1024 && - printf > pump.toml %s\\n 'log-file="pump.log"' 'data-dir="pump.data"' 'addr="127.0.0.1:8250"' 'advertise-addr="127.0.0.1:8250"' 'pd-urls="http://127.0.0.1:2379"' && - printf > tidb.toml %s\\n 'store="tikv"' 'path="127.0.0.1:2379"' '[log.file]' 'filename="tidb.log"' '[binlog]' 'enable=true' && - printf > drainer.toml %s\\n 'log-file="drainer.log"' '[syncer]' 'db-type="mysql"' '[syncer.to]' 'host="127.0.0.1"' 'user="root"' 'password=""' 'port=3306' - ``` - -2. 查看配置细节： - - {{< copyable "shell-regular" >}} - - ```bash - for f in *.toml; do echo "$f:"; cat "$f"; echo; done - ``` - - 预期输出： - - ``` - drainer.toml: - log-file="drainer.log" - [syncer] - db-type="mysql" - [syncer.to] - host="127.0.0.1" - user="root" - password="" - port=3306 - - pd.toml: - log-file="pd.log" - data-dir="pd.data" - - pump.toml: - log-file="pump.log" - data-dir="pump.data" - addr="127.0.0.1:8250" - advertise-addr="127.0.0.1:8250" - pd-urls="http://127.0.0.1:2379" - - tidb.toml: - store="tikv" - path="127.0.0.1:2379" - [log.file] - filename="tidb.log" - [binlog] - enable=true - - tikv.toml: - log-file="tikv.log" - [storage] - data-dir="tikv.data" - [pd] - endpoints=["127.0.0.1:2379"] - [rocksdb] - max-open-files=1024 - [raftdb] - max-open-files=1024 - ``` - -## 启动程序 - -现在可启动各个组件。推荐启动顺序依次为 Placement Driver (PD)、TiKV、Pump（TiDB 发送 binlog 日志必须连接 Pump 服务）、TiDB。 - -1. 启动所有服务： - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pd-server --config=pd.toml &>pd.out & - ``` - - ``` - [1] 20935 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/tikv-server --config=tikv.toml &>tikv.out & - ``` - - ``` - [2] 20944 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump --config=pump.toml &>pump.out & - ``` - - ``` - [3] 21050 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - sleep 3 && - ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - ``` - [4] 21058 - ``` - -2. 如果执行 `jobs`，可以看到后台正在运行的程序，列表如下： - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running ./bin/pd-server --config=pd.toml &>pd.out & - [2] Running ./bin/tikv-server --config=tikv.toml &>tikv.out & - [3]- Running ./bin/pump --config=pump.toml &>pump.out & - [4]+ Running ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - 如果有服务启动失败（例如出现 “`Exit 1`” 而不是 “`Running`”），尝试重启单个组件。 - -## 连接 - -按以上步骤操作后，TiDB 的 4 个组件开始运行。接下来可以使用以下 MariaDB 或 MySQL 命令行客户端，通过 4000 端口连接到 TiDB 服务： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select tidb_version();' -``` - -预期输出： - -``` -*************************** 1. row *************************** -tidb_version(): Release Version: v3.0.0 -Git Commit Hash: 60965b006877ca7234adaced7890d7b029ed1306 -Git Branch: HEAD -UTC Build Time: 2019-06-28 12:14:07 -GoVersion: go version go1.12 linux/amd64 -Race Enabled: false -TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e -Check Table Before Drop: false -``` - -连接后TiDB 集群已开始运行，`pump` 读取集群中的 binlog 数据，并在其数据目录中将 binlog 数据存储为 relay log。下一步是启动一个可供 `drainer` 写入的 MariaDB Server。 - -1. 启动 `drainer`： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl start mariadb && - ./bin/drainer --config=drainer.toml &>drainer.out & - ``` - - 如果你的操作系统更易于安装 MySQL，只需保证监听 3306 端口。另外，可使用密码为空的 "root" 用户连接到 MySQL，或调整 `drainer.toml` 连接到 MySQL。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 3306 -u root - ``` - - 预期输出： - - ``` - Welcome to the MariaDB monitor. Commands end with ; or \g. - Your MariaDB connection id is 20 - Server version: 5.5.60-MariaDB MariaDB Server - - Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - MariaDB [(none)]> - ``` - - {{< copyable "sql" >}} - - ```sql - show databases; - ``` - - 预期输出： - - ``` - +--------------------+ - | Database | - +--------------------+ - | information_schema | - | mysql | - | performance_schema | - | test | - | tidb_binlog | - +--------------------+ - 5 rows in set (0.01 sec) - ``` - - 如下表格是包含 `checkpoint` 表格的 `tidb_binlog` 数据库。`drainer` 使用 `checkpoint` 表格，记录 TiDB 集群中的 binlog 已经更新到了哪个位置。 - - {{< copyable "sql" >}} - - ```sql - use tidb_binlog; - ``` - - ``` - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - select * from checkpoint; - ``` - - ``` - +---------------------+---------------------------------------------+ - | clusterID | checkPoint | - +---------------------+---------------------------------------------+ - | 6678715361817107733 | {"commitTS":407637466476445697,"ts-map":{}} | - +---------------------+---------------------------------------------+ - 1 row in set (0.00 sec) - ``` - - 打开另一个连接到 TiDB 的客户端，创建一个表格并插入几行数据。建议在 GNU Screen 软件中操作，从而同时打开多个客户端。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 --prompt='TiDB [\d]> ' -u root - ``` - - {{< copyable "sql" >}} - - ```sql - create database tidbtest; - ``` - - ``` - Query OK, 0 rows affected (0.12 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - use tidbtest; - ``` - - ``` - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - create table t1 (id int unsigned not null AUTO_INCREMENT primary key); - ``` - - ``` - Query OK, 0 rows affected (0.11 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - insert into t1 () values (),(),(),(),(); - ``` - - ``` - Query OK, 5 rows affected (0.01 sec) - Records: 5 Duplicates: 0 Warnings: 0 - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t1; - ``` - - ``` - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 切换回 MariaDB 客户端可看到新的数据库、新的表格和最近插入的行数据。 - - {{< copyable "sql" >}} - - ```sql - use tidbtest; - ``` - - ``` - Reading table information for completion of table and column names - You can turn off this feature to get a quicker startup with -A - - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - show tables; - ``` - - ``` - +--------------------+ - | Tables_in_tidbtest | - +--------------------+ - | t1 | - +--------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t1; - ``` - - ``` - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 可看到查询 MariaDB 时插入到 TiDB 相同的行数据，表明 TiDB Binlog 安装成功。 - -## binlogctl - -加入到集群的 Pump 和 Drainer 的数据存储在 Placement Driver (PD) 中。binlogctl 可用于查询和修改状态信息。更多信息请参考 [binlogctl guide](/v3.0/reference/tidb-binlog/maintain.md#binlogctl-工具)。 - -使用 `binlogctl` 查看集群中 Pump 和 Drainer 的当前状态： - -{{< copyable "shell-regular" >}} - -```bash -./bin/binlogctl -cmd drainers -``` - -``` -[2019/04/11 17:44:10.861 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: online, MaxCommitTS: 407638907719778305, UpdateTime: 2019-04-11 17:44:10 -0400 EDT}"] -``` - -{{< copyable "shell-regular" >}} - -```bash -./bin/binlogctl -cmd pumps -``` - -``` -[2019/04/11 17:44:13.904 -04:00] [INFO] [nodes.go:47] ["query node"] [type=pump] [node="{NodeID: localhost.localdomain:8250, Addr: 192.168.236.128:8250, State: online, MaxCommitTS: 407638914024079361, UpdateTime: 2019-04-11 17:44:13 -0400 EDT}"] -``` - -如果结束 Drainer 进程，集群会改进程设置“已暂停（即集群等待 Drainer 重新加入）”的状态。 - -{{< copyable "shell-regular" >}} - -```bash -pkill drainer && -./bin/binlogctl -cmd drainers -``` - -预期输出： - -``` -[2019/04/11 17:44:22.640 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: paused, MaxCommitTS: 407638915597467649, UpdateTime: 2019-04-11 17:44:18 -0400 EDT}"] -``` - -使用 binlogctl 的 "NodeIDs" 可控制单个对应节点。在该情况下，Drainer 的节点 ID 是 "localhost.localdomain:8249"，Pump 的节点 ID 是 "localhost.localdomain:8250"。 - -本文档中的 binlogctl 主要用于集群重启。如果在 TiDB 集群中终止并尝试重启所有的进程，由于 Pump 无法连接 Drainer 且认为 Drainer 依旧“在线”，Pump 会拒绝启动。这里的进程并不包括下游的 MySQL 或 MariaDB 或 Drainer。 - -以下有三个方案可解决上述问题： - -- 使用 binlogctl 停止 Drainer，而不是结束进程： - - ```bash - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=drainers && - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=pause-drainer --node-id=localhost.localdomain:8249 - ``` - -- 在启动 Pump **之前**先启动 Drainer。 - -- 在启动 PD 之后但在启动 Drainer 和 Pump 之前，使用 binlogctl 更新已暂定 Drainer 的状态。 - - ```bash - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=update-drainer --node-id=localhost.localdomain:8249 --state=paused - ``` - -## 清理 - -在 shell 终端里可启动创建集群的所有进程（`pd-server` 、`tikv-server`、`pump`、`tidb-server`、`drainer`）。可通过在 shell 终端中执行 `pkill -P $$` 停止 TiDB 集群服务和 TiDB Binlog 进程。按一定的顺序停止这些进程有利于留出足够的时间彻底关闭每个组件。 - -{{< copyable "shell-regular" >}} - -```bash -for p in tidb-server drainer pump tikv-server pd-server; do pkill "$p"; sleep 1; done -``` - -预期输出： - -``` -[4]- Done ./bin/tidb-server --config=tidb.toml &>tidb.out -[5]+ Done ./bin/drainer --config=drainer.toml &>drainer.out -[3]+ Done ./bin/pump --config=pump.toml &>pump.out -[2]+ Done ./bin/tikv-server --config=tikv.toml &>tikv.out -[1]+ Done ./bin/pd-server --config=pd.toml &>pd.out -``` - -如果需要所有服务退出后重启集群，可以使用一开始启动服务的命令。如以上 [`binlogctl`](#binlogctl) 部分所述，需要先启动 Drainer 再启动 Pump，最后启动 `tidb-server`。 - -{{< copyable "shell-regular" >}} - -```bash -./bin/pd-server --config=pd.toml &>pd.out & -./bin/tikv-server --config=tikv.toml &>tikv.out & -./bin/drainer --config=drainer.toml &>drainer.out & -sleep 3 -./bin/pump --config=pump.toml &>pump.out & -sleep 3 -./bin/tidb-server --config=tidb.toml &>tidb.out & -``` - -如果有组件启动失败，请尝试单独重启该组件。 - -## 总结 - -本文档介绍了如何通过设置 TiDB Binlog，使用单个 Pump 和 Drainer 组成的集群同步 TiDB 集群数据到下游的 MariaDB。可以发现，TiDB Binlog 是用于获取处理 TiDB 集群中更新数据的综合性平台工具。 - -在更稳健的开发、测试或生产部署环境中，可以使用多个 TiDB 服务以实现高可用性和扩展性。使用多个 Pump 实例可以避免 Pump 集群中的问题影响发送到 TiDB 实例的应用流量。或者可以使用增加的 Drainer 实例同步数据到不同的下游或实现数据增量备份。 diff --git a/v3.0/how-to/get-started/tidb-lightning.md b/v3.0/how-to/get-started/tidb-lightning.md deleted file mode 100644 index c9c0469eb165..000000000000 --- a/v3.0/how-to/get-started/tidb-lightning.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: TiDB Lightning 教程 -category: how-to ---- - -# TiDB Lightning 教程 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -TiDB Lightning 主要包含两个部分: - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键/值对 (KV 对) 发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，把 `tidb-lightning` 写入的 KV 对缓存、排序、切分并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -本教程假设使用的是若干新的、纯净版 CentOS 7 实例，你可以（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为 TiDB Lightning 对计算机资源消耗较高，建议分配 4 GB 以上的内存。 - -> **警告：** -> -> 本教程中的部署方法只适用于测试及功能体验，并不适用于生产或开发环境。 - -## 准备全量备份数据 - -我们使用 [`mydumper`](/v3.0/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -这样全量备份数据就导出到了 `/data/my_database` 目录中。 - -## 部署 TiDB Lightning - -### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群（版本要求 2.0.9 以上），本教程使用 TiDB 3.0.4 版本。部署方法可参考 [TiDB 快速入门指南](/v3.0/overview.md#部署方式)。 - -### 第 2 步：下载 TiDB Lightning 安装包 - -通过以下链接获取 TiDB Lightning 安装包（选择与 TiDB 集群相同的版本）： - -- **v3.0.4**: [tidb-toolkit-v3.0.4-linux-amd64.tar.gz](https://download.pingcap.org/tidb-toolkit-v3.0.0-linux-amd64.tar.gz) - -### 第 3 步：启动 `tikv-importer` - -1. 将安装包里的 `bin/tikv-importer` 上传至部署 TiDB Lightning 的服务器。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -### 第 4 步：启动 `tidb-lightning` - -1. 将安装包里的 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。 - -2. 将数据源也上传到同样的服务器。 - -3. 配置合适的参数运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning \ - --importer 172.16.31.10:8287 \ - -d /data/my_database/ \ - --tidb-server 172.16.31.2 \ - --tidb-user root \ - --log-file tidb-lightning.log \ - > nohup.out & - ``` - -### 第 5 步：检查数据 - -导入完毕后，TiDB Lightning 会自动退出。若导入成功，日志的最后一行会显示 `tidb lightning exit`。 - -如果出错，请参见 [TiDB Lightning 错误排解](/v3.0/how-to/troubleshoot/tidb-lightning.md)。 - -## 总结 - -本教程对 TiDB Lightning 进行了简单的介绍，并快速部署了一套简单的 TiDB Lightning 集群，将全量备份数据导入到 TiDB 集群中。 - -关于 TiDB Lightning 的详细功能和使用，参见 [TiDB Lightning 简介](/v3.0/reference/tools/tidb-lightning/overview.md)。 diff --git a/v3.0/how-to/get-started/tispark.md b/v3.0/how-to/get-started/tispark.md deleted file mode 100644 index 01fb1ca3c0eb..000000000000 --- a/v3.0/how-to/get-started/tispark.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: TiSpark 快速入门指南 -category: how-to ---- - -# TiSpark 快速入门指南 - -为了让大家快速体验 [TiSpark](/v3.0/reference/tispark.md)，通过 TiDB Ansible 安装的 TiDB 集群中默认已集成 Spark、TiSpark jar 包及 TiSpark sample data。 - -## 部署信息 - -- Spark 默认部署在 TiDB 实例部署目录下 spark 目录中 -- TiSpark jar 包默认部署在 Spark 部署目录 jars 文件夹下：`spark/jars/tispark-${name_with_version}.jar` -- TiSpark sample data 及导入脚本默认部署在 TiDB Ansible 目录下：`tidb-ansible/resources/bin/tispark-sample-data` - -## 环境准备 - -### 在 TiDB 实例上安装 JDK - -在 [Oracle JDK 官方下载页面](http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html) 下载 JDK 1.8 当前最新版，本示例中下载的版本为 `jdk-8u141-linux-x64.tar.gz`。 - -解压并根据您的 JDK 部署目录设置环境变量，编辑 `~/.bashrc` 文件，比如： - -{{< copyable "shell-regular" >}} - -```bash -export JAVA_HOME=/home/pingcap/jdk1.8.0_144 && -export PATH=$JAVA_HOME/bin:$PATH -``` - -验证 JDK 有效性： - -```bash -java -version -``` - -``` -java version "1.8.0_144" -Java(TM) SE Runtime Environment (build 1.8.0_144-b01) -Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode) -``` - -### 导入样例数据 - -假设 TiDB 集群已启动，其中一台 TiDB 实例服务 IP 为 192.168.0.2，端口为 4000，用户名为 root, 密码为空。 - -{{< copyable "shell-regular" >}} - -```bash -cd tidb-ansible/resources/bin/tispark-sample-data -``` - -修改 `sample_data.sh` 中 TiDB 登录信息，比如： - -{{< copyable "shell-regular" >}} - -```bash -mysql --local-infile=1 -h 192.168.0.2 -P 4000 -u root < dss.ddl -``` - -执行脚本 - -{{< copyable "shell-regular" >}} - -```bash -./sample_data.sh -``` - -> **注意：** -> -> 执行脚本的机器上需要安装 MySQL client，CentOS 用户可通过 `yum -y install mysql`来安装。 - -登录 TiDB 并验证数据包含 `TPCH_001` 库及以下表： - -{{< copyable "shell-regular" >}} - -```bash -mysql -uroot -P4000 -h192.168.0.2 -``` - -{{< copyable "sql" >}} - -```sql -show databases; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| TPCH_001 | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -use TPCH_001; -``` - -``` -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -``` - -{{< copyable "sql" >}} - -```sql -show tables; -``` - -``` -+--------------------+ -| Tables_in_TPCH_001 | -+--------------------+ -| CUSTOMER | -| LINEITEM | -| NATION | -| ORDERS | -| PART | -| PARTSUPP | -| REGION | -| SUPPLIER | -+--------------------+ -8 rows in set (0.00 sec) -``` - -## 使用范例 - -进入 spark 部署目录启动 spark-shell: - -{{< copyable "shell-regular" >}} - -```bash -cd spark && -bin/spark-shell -``` - -然后像使用原生 Spark 一样查询 TiDB 表： - -```shell -scala> spark.sql("select count(*) from lineitem").show -``` - -结果为 - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -下面执行另一个复杂一点的 Spark SQL: - -```shell -scala> spark.sql( - """select - | l_returnflag, - | l_linestatus, - | sum(l_quantity) as sum_qty, - | sum(l_extendedprice) as sum_base_price, - | sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, - | sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, - | avg(l_quantity) as avg_qty, - | avg(l_extendedprice) as avg_price, - | avg(l_discount) as avg_disc, - | count(*) as count_order - |from - | lineitem - |where - | l_shipdate <= date '1998-12-01' - interval '90' day - |group by - | l_returnflag, - | l_linestatus - |order by - | l_returnflag, - | l_linestatus - """.stripMargin).show -``` - -结果为： - -``` -+------------+------------+---------+--------------+--------------+ -|l_returnflag|l_linestatus| sum_qty|sum_base_price|sum_disc_price| -+------------+------------+---------+--------------+--------------+ -| A| F|380456.00| 532348211.65|505822441.4861| -| N| F| 8971.00| 12384801.37| 11798257.2080| -| N| O|742802.00| 1041502841.45|989737518.6346| -| R| F|381449.00| 534594445.35|507996454.4067| -+------------+------------+---------+--------------+--------------+ -(续) ------------------+---------+------------+--------+-----------+ - sum_charge| avg_qty| avg_price|avg_disc|count_order| ------------------+---------+------------+--------+-----------+ - 526165934.000839|25.575155|35785.709307|0.050081| 14876| - 12282485.056933|25.778736|35588.509684|0.047759| 348| -1029418531.523350|25.454988|35691.129209|0.049931| 29181| - 528524219.358903|25.597168|35874.006533|0.049828| 14902| ------------------+---------+------------+--------+-----------+ -``` - -更多样例请参考 [`pingcap/tispark-test`](https://github.com/pingcap/tispark-test/tree/master/tpch/sparksql) diff --git a/v3.0/how-to/maintain/ansible-operations.md b/v3.0/how-to/maintain/ansible-operations.md deleted file mode 100644 index a34ff6e8f564..000000000000 --- a/v3.0/how-to/maintain/ansible-operations.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: TiDB Ansible 常见运维操作 -category: how-to -aliases: ['/docs-cn/op-guide/ansible-operation/'] ---- - -# TiDB Ansible 常见运维操作 - -## 启动集群 - -此操作会按顺序启动整个 TiDB 集群所有组件（包括 PD、TiDB、TiKV 等组件和监控组件）。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook start.yml -``` - -## 关闭集群 - -此操作会按顺序关闭整个 TiDB 集群所有组件（包括 PD、TiDB、TiKV 等组件和监控组件）。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -## 清除集群数据 - -此操作会关闭 TiDB、Pump、TiKV、PD 服务，并清空 Pump、TiKV、PD 数据目录。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook unsafe_cleanup_data.yml -``` - -## 销毁集群 - -此操作会关闭集群，并清空部署目录，若部署目录为挂载点，会报错，可忽略。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook unsafe_cleanup.yml -``` diff --git a/v3.0/how-to/maintain/backup-and-restore.md b/v3.0/how-to/maintain/backup-and-restore.md deleted file mode 100644 index b272cfd0423a..000000000000 --- a/v3.0/how-to/maintain/backup-and-restore.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: 使用 Mydumper/TiDB Lightning 进行备份与恢复 -category: how-to ---- - -# 使用 Mydumper/TiDB Lightning 进行备份与恢复 - -本文档将详细介绍如何使用 Mydumper/TiDB Lightning 对 TiDB 进行全量备份与恢复。增量备份与恢复可使用 [TiDB Binlog](/v3.0/reference/tidb-binlog/overview.md)。 - -这里假定 TiDB 服务信息如下： - -|Name|Address|Port|User|Password| -|----|-------|----|----|--------| -|TiDB|127.0.0.1|4000|root|*| - -在这个备份恢复过程中，会用到下面的工具： - -- [Mydumper](/v3.0/reference/tools/mydumper.md) 从 TiDB 导出数据 -- [TiDB Lightning](/v3.0/reference/tools/tidb-lightning/overview.md) 导入数据到 TiDB - -## 使用 Mydumper/TiDB Lightning 全量备份恢复数据 - -`mydumper` 是一个强大的数据备份工具，具体可以参考 [`maxbube/mydumper`](https://github.com/maxbube/mydumper)。 - -可使用 [Mydumper](/v3.0/reference/tools/mydumper.md) 从 TiDB 导出数据进行备份，然后用 [TiDB Lightning](/v3.0/reference/tools/tidb-lightning/overview.md) 将其导入到 TiDB 里面进行恢复。 - -> **注意：** -> -> PingCAP 研发团队对 `mydumper` 进行了针对 TiDB 的适配性改造，建议使用 PingCAP 官方提供的 [Mydumper](/v3.0/reference/tools/mydumper.md)。由于使用 `mysqldump` 进行数据备份和恢复都要耗费许多时间，这里也并不推荐。 - -### Mydumper/TiDB Lightning 全量备份恢复最佳实践 - -为了快速地备份恢复数据 (特别是数据量巨大的库)，可以参考以下建议： - -* 导出来的数据文件应当尽可能的小，可以通过设置参数 `-F` 来控制导出来的文件大小。如果后续使用 TiDB Lightning 对备份文件进行恢复，建议把 `mydumper` -F 参数的值设置为 `256`（单位 MB）；如果使用 `loader` 恢复，则建议设置为 `64`（单位 MB）。 - -## 从 TiDB 备份数据 - -我们使用 `mydumper` 从 TiDB 备份数据，如下: - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -P 4000 -u root -t 32 -F 256 -B test -T t1,t2 --skip-tz-utc -o ./var/test -``` - -上面，我们使用 `-B test` 表明是对 `test` 这个 database 操作，然后用 `-T t1,t2` 表明只导出 `t1`，`t2` 两张表。 - -`-t 32` 表明使用 32 个线程去导出数据。`-F 256` 是将实际的表切分成一定大小的 chunk，这里的 chunk 大小为 256MB。 - -添加 `--skip-tz-utc` 参数后，会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果 `mydumper` 出现以下报错： - -``` -** (mydumper:27528): CRITICAL **: 13:25:09.081: Could not read data from testSchema.testTable: GC life time is shorter than transaction duration, transaction starts at 2019-08-05 21:10:01.451 +0800 CST, GC safe point is 2019-08-05 21:14:53.801 +0800 CST -``` - -就再执行两步命令： - -1. 执行 `mydumper` 命令前，查询 TiDB 集群的 [GC](/v3.0/reference/garbage-collection/overview.md) 值并使用 MySQL 客户端将其调整为合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 执行 `mydumper` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -## 向 TiDB 恢复数据 - -使用 TiDB Lightning 将之前导出的数据导入到 TiDB，完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) diff --git a/v3.0/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md b/v3.0/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md deleted file mode 100644 index 60c4f5ff4cd2..000000000000 --- a/v3.0/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: 定位消耗系统资源多的查询 -category: how-to ---- - -# 定位消耗系统资源多的查询 - -TiDB 会将执行时间超过 [tidb_expensive_query_time_threshold](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_expensive_query_time_threshold)（默认值为 60s），或使用内存超过 [mem-quota-query](/v3.0/reference/configuration/tidb-server/configuration-file.md#mem-quota-query)（默认值为 32 GB）的语句输出到 [tidb-server 日志文件](/v3.0/reference/configuration/tidb-server/configuration-file.md#logfile)（默认文件为：“tidb.log”）中，用于在语句执行结束前定位消耗系统资源多的查询语句（以下简称为 expensive query），帮助用户分析和解决语句执行的性能问题。 - -注意，expensive query 日志和[慢查询日志](/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)的区别是，慢查询日志是在语句执行完后才打印，expensive query 日志可以将正在执行的语句的相关信息打印出来。当一条语句在执行过程中达到资源使用阈值时（执行时间/使用内存量），TiDB 会即时将这条语句的相关信息写入日志。 - -## Expensive query 日志示例 - -```sql -[2020/02/05 15:32:25.096 +08:00] [WARN] [expensivequery.go:167] [expensive_query] [cost_time=60.008338935s] [wait_time=0s] [request_count=1] [total_keys=70] [process_keys=65] [num_cop_tasks=1] [process_avg_time=0s] [process_p90_time=0s] [process_max_time=0s] [process_max_addr=10.0.1.9:20160] [wait_avg_time=0.002s] [wait_p90_time=0.002s] [wait_max_time=0.002s] [wait_max_addr=10.0.1.9:20160] [stats=t:pseudo] [conn_id=60026] [user=root] [database=test] [table_ids="[122]"] [txn_start_ts=414420273735139329] [mem_max="1035 Bytes (1.0107421875 KB)"] [sql="insert into t select sleep(1) from t"] -``` - -## 字段含义说明 - -基本字段： - -* `cost_time`：日志打印时语句已经花费的执行时间。 -* `stats`：语句涉及到的表或索引使用的统计信息版本。值为 pesudo 时表示无可用统计信息，需要对表或索引进行 analyze。 -* `table_ids`：语句涉及到的表的 ID。 -* `txn_start_ts`：事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `sql`：SQL 语句。 - -和内存使用相关的字段： - -* `mem_max`：日志打印时语句已经使用的内存空间。该项使用两种单位标识内存使用量，分别为 Bytes 以及易于阅读的自适应单位（比如 MB、GB 等）。 - -和 SQL 执行的用户相关的字段： - -* `user`：执行语句的用户名。 -* `conn_id`：用户的连接 ID，可以用类似 `con:60026` 的关键字在 TiDB 日志中查找该连接相关的其他日志。 -* `database`：执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `wait_time`：该语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `request_count`：该语句发送的 Coprocessor 请求的数量。 -* `total_keys`：Coprocessor 扫过的 key 的数量。 -* `processed_keys`：Coprocessor 处理的 key 的数量。与 total_keys 相比，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `num_cop_tasks`：该语句发送的 Coprocessor 请求的数量。 -* `process_avg_time`：Coprocessor 执行 task 的平均执行时间。 -* `process_p90_time`：Coprocessor 执行 task 的 P90 分位执行时间。 -* `process_max_time`：Coprocessor 执行 task 的最长执行时间。 -* `process_max_addr`：task 执行时间最长的 Coprocessor 所在地址。 -* `wait_avg_time`：Coprocessor 上 task 的等待时间。 -* `wait_p90_time`：Coprocessor 上 task 的 P90 分位等待时间。 -* `wait_max_time`：Coprocessor 上 task 的最长等待时间。 -* `wait_max_addr`：task 等待时间最长的 Coprocessor 所在地址。 diff --git a/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md b/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md deleted file mode 100644 index af527f971910..000000000000 --- a/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: 慢查询日志 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/maintain/identify-slow-queries/'] ---- - -# 慢查询日志 - -TiDB 会将执行时间超过 [slow-threshold](/v3.0/reference/configuration/tidb-server/configuration-file.md#slow-threshold)（默认值为 300 毫秒）的语句输出到 [slow-query-file](/v3.0/reference/configuration/tidb-server/configuration-file.md#slow-query-file)（默认值："tidb-slow.log"）日志文件中，用于帮助用户定位慢查询语句，分析和解决 SQL 执行的性能问题。 - -## 日志示例 - -```sql -# Time: 2019-08-14T09:26:59.487776265+08:00 -# Txn_start_ts: 410450924122144769 -# User: root@127.0.0.1 -# Conn_ID: 3086 -# Query_time: 1.527627037 -# Parse_time: 0.000054933 -# Compile_time: 0.000129729 -# Process_time: 0.07 Request_count: 1 Total_keys: 131073 Process_keys: 131072 Prewrite_time: 0.335415029 Commit_time: 0.032175429 Get_commit_ts_time: 0.000177098 Local_latch_wait_time: 0.106869448 Write_keys: 131072 Write_size: 3538944 Prewrite_region: 1 -# DB: test -# Is_internal: false -# Digest: 50a2e32d2abbd6c1764b1b7f2058d428ef2712b029282b776beb9506a365c0f1 -# Stats: t:pseudo -# Num_cop_tasks: 1 -# Cop_proc_avg: 0.07 Cop_proc_p90: 0.07 Cop_proc_max: 0.07 Cop_proc_addr: 172.16.5.87:20171 -# Cop_wait_avg: 0 Cop_wait_p90: 0 Cop_wait_max: 0 Cop_wait_addr: 172.16.5.87:20171 -# Mem_max: 525211 -# Succ: true -# Plan: tidb_decode_plan('ZJAwCTMyXzcJMAkyMAlkYXRhOlRhYmxlU2Nhbl82CjEJMTBfNgkxAR0AdAEY1Dp0LCByYW5nZTpbLWluZiwraW5mXSwga2VlcCBvcmRlcjpmYWxzZSwgc3RhdHM6cHNldWRvCg==') -insert into t select * from t; -``` - -## 字段含义说明 - -> **注意：** -> -> 慢查询日志中所有时间相关字段的单位都是 **“秒”** - -Slow Query 基础信息： - -* `Time`：表示日志打印时间。 -* `Query_time`：表示执行这个语句花费的时间。 -* `Parse_time`：表示这个语句在语法解析阶段花费的时间。 -* `Compile_time`：表示这个语句在查询优化阶段花费的时间。 -* `Query`：表示 SQL 语句。慢日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 -* `Digest`：表示 SQL 语句的指纹。 -* `Txn_start_ts`：表示事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `Is_internal`：表示是否为 TiDB 内部的 SQL 语句。`true` 表示 TiDB 系统内部执行的 SQL 语句，`false` 表示用户执行的 SQL 语句。 -* `Index_ids`：表示语句涉及到的索引的 ID。 -* `Succ`：表示语句是否执行成功。 -* `Backoff_time`：表示语句遇到需要重试的错误时在重试前等待的时间，常见的需要重试的错误有以下几种：遇到了 lock、Region 分裂、`tikv server is busy`。 -* `Plan`：表示语句的执行计划，用 `select tidb_decode_plan('xxx...')` SQL 语句可以解析出具体的执行计划。 - -和事务执行相关的字段： - -* `Prewrite_time`：表示事务两阶段提交中第一阶段（prewrite 阶段）的耗时。 -* `Commit_time`：表示事务两阶段提交中第二阶段（commit 阶段）的耗时。 -* `Get_commit_ts_time`：表示事务两阶段提交中第二阶段（commit 阶段）获取 commit 时间戳的耗时。 -* `Local_latch_wait_time`：表示事务两阶段提交中第二阶段（commit 阶段）发起前在 TiDB 侧等锁的耗时。 -* `Write_keys`：表示该事务向 TiKV 的 Write CF 写入 Key 的数量。 -* `Write_size`：表示事务提交时写 key 或 value 的总大小。 -* `Prewrite_region`：表示事务两阶段提交中第一阶段（prewrite 阶段）涉及的 TiKV Region 数量。每个 Region 会触发一次远程过程调用。 - -和内存使用相关的字段： - -* `Memory_max`：表示执行期间 TiDB 使用的最大内存空间，单位为 byte。 - -和 SQL 执行的用户相关的字段： - -* `User`：表示执行语句的用户名。 -* `Conn_ID`：表示用户的链接 ID，可以用类似 `con:3` 的关键字在 TiDB 日志中查找该链接相关的其他日志。 -* `DB`：表示执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `Request_count`：表示这个语句发送的 Coprocessor 请求的数量。 -* `Total_keys`：表示 Coprocessor 扫过的 key 的数量。 -* `Process_time`：执行 SQL 在 TiKV 的处理时间之和，因为数据会并行的发到 TiKV 执行，这个值可能会超过 `Query_time`。 -* `Wait_time`：表示这个语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `Process_keys`：表示 Coprocessor 处理的 key 的数量。相比 total_keys，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `Cop_proc_avg`：cop-task 的平均执行时间。 -* `Cop_proc_p90`：cop-task 的 P90 分位执行时间。 -* `Cop_proc_max`：cop-task 的最大执行时间。 -* `Cop_proc_addr`：执行时间最长的 cop-task 所在地址。 -* `Cop_wait_avg`：cop-task 的平均等待时间。 -* `Cop_wait_p90`：cop-task 的 P90 分位等待时间。 -* `Cop_wait_max`：cop-task 的最大等待时间。 -* `Cop_wait_addr`：等待时间最长的 cop-task 所在地址。 - -## 慢日志内存映射表 - -用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢日志中字段名一一对应，表结构可查看 [Information Schema](/v3.0/reference/system-databases/information-schema.md#information-schema) 中关于 `SLOW_QUERY` 表的介绍。 - -> **注意：** -> -> 每次查询 `SLOW_QUERY` 表时，TiDB 都会去读取和解析一次当前的慢查询日志。 - -## 查询 `SLOW_QUERY` 示例 - -### 搜索 Top N 的慢查询 - -查询 Top 2 的用户慢查询。`is_internal=false` 表示排除 TiDB 内部的慢查询，只看用户的慢查询： - -{{< copyable "sql" >}} - -```sql -select query_time, query -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+--------------+------------------------------------------------------------------+ -| query_time | query | -+--------------+------------------------------------------------------------------+ -| 12.77583857 | select * from t_slim, t_wide where t_slim.c0=t_wide.c0; | -| 0.734982725 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c0; | -+--------------+------------------------------------------------------------------+ -``` - -### 搜索某个用户的 Top N 慢查询 - -下面例子中搜索 test 用户执行的慢查询 SQL，且按执行消耗时间逆序排序显式前 2 条： - -{{< copyable "sql" >}} - -```sql -select query_time, query, user -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL - and user = "test" -- 查找的用户名 -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+-------------+------------------------------------------------------------------+----------------+ -| Query_time | query | user | -+-------------+------------------------------------------------------------------+----------------+ -| 0.676408014 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c1; | test | -+-------------+------------------------------------------------------------------+----------------+ -``` - -### 根据 SQL 指纹搜索同类慢查询 - -在得到 Top N 的慢查询 SQL 后，可通过 SQL 指纹继续搜索同类慢查询 SQL。 - -先获取 Top N 的慢查询和对应的 SQL 指纹： - -{{< copyable "sql" >}} - -```sql -select query_time, query, digest -from information_schema.slow_query -where is_internal = false -order by query_time desc -limit 1; -``` - -输出样例： - -``` -+-------------+-----------------------------+------------------------------------------------------------------+ -| query_time | query | digest | -+-------------+-----------------------------+------------------------------------------------------------------+ -| 0.302558006 | select * from t1 where a=1; | 4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa | -+-------------+-----------------------------+------------------------------------------------------------------+ -``` - -再根据 SQL 指纹搜索同类慢查询： - -{{< copyable "sql" >}} - -```sql -select query, query_time -from information_schema.slow_query -where digest = "4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa"; -``` - -输出样例： - -``` -+-----------------------------+-------------+ -| query | query_time | -+-----------------------------+-------------+ -| select * from t1 where a=1; | 0.302558006 | -| select * from t1 where a=2; | 0.401313532 | -+-----------------------------+-------------+ -``` - -### 搜索统计信息为 pseudo 的慢查询 SQL 语句 - -{{< copyable "sql" >}} - -```sql -select query, query_time, stats -from information_schema.slow_query -where is_internal = false - and stats like '%pseudo%'; -``` - -输出样例： - -``` -+-----------------------------+-------------+---------------------------------+ -| query | query_time | stats | -+-----------------------------+-------------+---------------------------------+ -| select * from t1 where a=1; | 0.302558006 | t1:pseudo | -| select * from t1 where a=2; | 0.401313532 | t1:pseudo | -| select * from t1 where a>2; | 0.602011247 | t1:pseudo | -| select * from t1 where a>3; | 0.50077719 | t1:pseudo | -| select * from t1 join t2; | 0.931260518 | t1:407872303825682445,t2:pseudo | -+-----------------------------+-------------+---------------------------------+ -``` - -## 解析其他的 TiDB 慢日志文件 - -TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHEMA.SLOW_QUERY` 时要读取和解析的文件，可通过修改改 session 变量的值来查询其他慢查询日志文件的内容： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_query_file = "/path-to-log/tidb-slow.log" -``` - -## 用 `pt-query-digest` 工具分析 TiDB 慢日志 - -可以用 `pt-query-digest` 工具分析 TiDB 慢日志。 - -> **注意：** -> -> 建议使用 pt-query-digest 3.0.13 及以上版本。 - -示例如下： - -{{< copyable "shell" >}} - -```shell -pt-query-digest --report tidb-slow.log -``` - -输出样例： - -``` -# 320ms user time, 20ms system time, 27.00M rss, 221.32M vsz -# Current date: Mon Mar 18 13:18:51 2019 -# Hostname: localhost.localdomain -# Files: tidb-slow.log -# Overall: 1.02k total, 21 unique, 0 QPS, 0x concurrency _________________ -# Time range: 2019-03-18-12:22:16 to 2019-03-18-13:08:52 -# Attribute total min max avg 95% stddev median -# ============ ======= ======= ======= ======= ======= ======= ======= -# Exec time 218s 10ms 13s 213ms 30ms 1s 19ms -# Query size 175.37k 9 2.01k 175.89 158.58 122.36 158.58 -# Commit time 46ms 2ms 7ms 3ms 7ms 1ms 3ms -# Conn ID 71 1 16 8.88 15.25 4.06 9.83 -# Process keys 581.87k 2 103.15k 596.43 400.73 3.91k 400.73 -# Process time 31s 1ms 10s 32ms 19ms 334ms 16ms -# Request coun 1.97k 1 10 2.02 1.96 0.33 1.96 -# Total keys 636.43k 2 103.16k 652.35 793.42 3.97k 400.73 -# Txn start ts 374.38E 0 16.00E 375.48P 1.25P 89.05T 1.25P -# Wait time 943ms 1ms 19ms 1ms 2ms 1ms 972us -. -. -. -``` - -### 定位问题语句的方法 - -并不是所有 SLOW_QUERY 的语句都是有问题的。会造成集群整体压力增大的，是那些 process_time 很大的语句。wait_time 很大，但 process_time 很小的语句通常不是问题语句，是因为被问题语句阻塞，在执行队列等待造成的响应时间过长。 - -## `admin show slow` 命令 - -除了获取 TiDB 日志，还有一种定位慢查询的方式是通过 `admin show slow` SQL 命令： - -{{< copyable "sql" >}} - -```sql -admin show slow recent N; -``` - -{{< copyable "sql" >}} - -```sql -admin show slow top [internal | all] N; -``` - -`recent N` 会显示最近的 N 条慢查询记录，例如： - -{{< copyable "sql" >}} - -```sql -admin show slow recent 10; -``` - -`top N` 则显示最近一段时间（大约几天）内，最慢的查询记录。如果指定 `internal` 选项，则返回查询系统内部 SQL 的慢查询记录；如果指定 `all` 选项，返回系统内部和用户 SQL 汇总以后的慢查询记录；默认只返回用户 SQL 中的慢查询记录。 - -{{< copyable "sql" >}} - -```sql -admin show slow top 3; -admin show slow top internal 3; -admin show slow top all 5; -``` - -由于内存限制，保留的慢查询记录的条数是有限的。当命令查询的 `N` 大于记录条数时，返回的结果记录条数会小于 `N`。 - -输出内容详细说明，如下： - -| 列名 | 描述 | -|:------|:---- | -| start | SQL 语句执行开始时间 | -| duration | SQL 语句执行持续时间 | -| details | 执行语句的详细信息 | -| succ | SQL 语句执行是否成功，1: 成功，0: 失败 | -| conn_id | session 连接 ID | -| transcation_ts | 事务提交的 commit ts | -| user | 执行该语句的用户名 | -| db | 执行该 SQL 涉及到 database | -| table_ids | 执行该 SQL 涉及到表的 ID | -| index_ids | 执行该 SQL 涉及到索引 ID | -| internal | 表示为 TiDB 内部的 SQL 语句 | -| digest | 表示 SQL 语句的指纹 | -| sql | 执行的 SQL 语句 | diff --git a/v3.0/how-to/migrate/from-mysql-aurora.md b/v3.0/how-to/migrate/from-mysql-aurora.md deleted file mode 100644 index 8836f9756c88..000000000000 --- a/v3.0/how-to/migrate/from-mysql-aurora.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 -summary: 使用 DM 从 MySQL/Amazon Aurora MySQL 迁移数据。 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/migrate/from-aurora/'] ---- - -# 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 - -本文以 [Amazon Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 为例介绍如何使用 DM 从 MySQL 协议数据库迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/v3.0/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务（`task.yaml` 是之前编辑的配置文件） - - {{< copyable "" >}} - - ```bash - start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "shell-regular" >}} - -```bash -query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ``` -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 `task.yaml` 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/v3.0/how-to/monitor/monitor-a-cluster.md b/v3.0/how-to/monitor/monitor-a-cluster.md deleted file mode 100644 index c890ebcfdbaf..000000000000 --- a/v3.0/how-to/monitor/monitor-a-cluster.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: TiDB 集群监控 -category: how-to -aliases: ['/docs-cn/op-guide/monitor/'] ---- - -# TiDB 集群监控 - -TiDB 提供了以下两种接口来监控集群状态： - -- [状态接口](#使用状态接口)：通过 HTTP 接口对外汇报组件的信息。 -- [Metrics 接口](#使用-metrics-接口)：使用 Prometheus 记录组件中各种操作的详细信息，使用 Grafana 进行可视化展示。 - -## 使用状态接口 - -状态接口用于监控组件的一些基本信息，并且可以作为 keepalive 的监测接口。另外，通过 PD 的状态接口可以看到整个 TiKV 集群的详细信息。 - -### TiDB Server - -- TiDB API 地址：`http://${host}:${port}` -- 默认端口：10080 -- 各类 `api_name` 详细信息：参见 [TiDB API 文档](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) - -以下示例中，通过访问 `http://${host}:${port}/status` 获取当前 TiDB Server 的状态，并判断该 TiDB Server 是否存活。结果以 **JSON** 格式返回： - -{{< copyable "shell-regular" >}} - -```bash -curl http://127.0.0.1:10080/status -``` - -``` -{ - connections: 0, # 当前 TiDB Server 上的客户端连接数 - version: "5.7.25-TiDB-v3.0.0-beta-250-g778c3f4a5", # TiDB 版本号 - git_hash: "778c3f4a5a716880bcd1d71b257c8165685f0d70" # TiDB 当前代码的 Git Hash -} -``` - -### PD Server - -- PD API 地址：`http://${host}:${port}/pd/api/v1/${api_name}` -- 默认端口：2379 -- 各类 `api_name` 详细信息：参见 [PD API Doc](https://download.pingcap.com/pd-api-doc.html) - -通过该接口可以获取当前所有 TiKV 节点的状态以及负载均衡信息。下面以一个单节点的 TiKV 集群为例，说明用户需要了解的信息： - -{{< copyable "shell-regular" >}} - -```bash -curl http://127.0.0.1:2379/pd/api/v1/stores -``` - -``` -{ - "count": 1, # TiKV 节点数量 - "stores": [ # TiKV 节点的列表 - # 集群中单个 TiKV 节点的信息 - { - "store": { - "id": 1, - "address": "127.0.0.1:20160", - "version": "3.0.0-beta", - "state_name": "Up" - }, - "status": { - "capacity": "20 GiB", # 存储总容量 - "available": "16 GiB", # 存储剩余容量 - "leader_count": 17, - "leader_weight": 1, - "leader_score": 17, - "leader_size": 17, - "region_count": 17, - "region_weight": 1, - "region_score": 17, - "region_size": 17, - "start_ts": "2019-03-21T14:09:32+08:00", # 启动时间 - "last_heartbeat_ts": "2019-03-21T14:14:22.961171958+08:00", # 最后一次心跳的时间 - "uptime": "4m50.961171958s" - } - } - ] -``` - -## 使用 metrics 接口 - -Metrics 接口用于监控整个集群的状态和性能。 - -- 如果使用 TiDB Ansible 部署 TiDB 集群，监控系统（Prometheus 和 Grafana）会同时部署。 -- 如果使用其他方式部署 TiDB 集群，在使用 metrics 接口前，需先[部署 Prometheus 和 Grafana](#部署-prometheus-和-grafana)。 - -成功部署 Prometheus 和 Grafana 之后，[配置 Grafana](#配置-grafana)。 - -### 部署 Prometheus 和 Grafana - -假设 TiDB 的拓扑结构如下： - -| 节点 | 主机 IP | 服务 | -| :-- | :-- | :-------------- | -| Node1 | 192.168.199.113| PD1, TiDB, node_export, Prometheus, Grafana | -| Node2 | 192.168.199.114| PD2, node_export | -| Node3 | 192.168.199.115| PD3, node_export | -| Node4 | 192.168.199.116| TiKV1, node_export | -| Node5 | 192.168.199.117| TiKV2, node_export | -| Node6 | 192.168.199.118| TiKV3, node_export | - -#### 第 1 步：下载二进制包 - -下载二进制包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://github.com/prometheus/prometheus/releases/download/v2.2.1/prometheus-2.2.1.linux-amd64.tar.gz && -wget https://github.com/prometheus/node_exporter/releases/download/v0.15.2/node_exporter-0.15.2.linux-amd64.tar.gz && -wget https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.6.3.linux-x64.tar.gz -``` - -解压二进制包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf prometheus-2.2.1.linux-amd64.tar.gz && -tar -xzf node_exporter-0.15.2.linux-amd64.tar.gz && -tar -xzf grafana-4.6.3.linux-x64.tar.gz -``` - -#### 第 2 步：在 Node1，Node2，Node3，Node4 上启动 `node_exporter` - -{{< copyable "shell-regular" >}} - -```bash -cd node_exporter-0.15.2.linux-amd64 -``` - -启动 node_exporter 服务： - -{{< copyable "shell-regular" >}} - -```bash -./node_exporter --web.listen-address=":9100" \ - --log.level="info" & -``` - -#### 第 3 步：在 Node1 上启动 Prometheus - -编辑 Prometheus 的配置文件： - -{{< copyable "shell-regular" >}} - -```bash -cd prometheus-2.2.1.linux-amd64 && -vi prometheus.yml -``` - -```ini -... - -global: - scrape_interval: 15s - evaluation_interval: 15s - # scrape_timeout 设置为全局默认值 (10s) - external_labels: - cluster: 'test-cluster' - monitor: "prometheus" - -scrape_configs: - - job_name: 'overwritten-nodes' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.113:9100' - - '192.168.199.114:9100' - - '192.168.199.115:9100' - - '192.168.199.116:9100' - - '192.168.199.117:9100' - - '192.168.199.118:9100' - - - job_name: 'tidb' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.113:10080' - - - job_name: 'pd' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.113:2379' - - '192.168.199.114:2379' - - '192.168.199.115:2379' - - - job_name: 'tikv' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.116:20180' - - '192.168.199.117:20180' - - '192.168.199.118:20180' - -... -``` - -启动 Prometheus 服务： - -{{< copyable "shell-regular" >}} - -```bash -./prometheus \ - --config.file="./prometheus.yml" \ - --web.listen-address=":9090" \ - --web.external-url="http://192.168.199.113:9090/" \ - --web.enable-admin-api \ - --log.level="info" \ - --storage.tsdb.path="./data.metrics" \ - --storage.tsdb.retention="15d" & -``` - -#### 第 4 步：在 Node1 上启动 Grafana - -编辑 Grafana 的配置文件： - -```bash -cd grafana-4.6.3 && -vi conf/grafana.ini -``` - -```ini -... - -[paths] -data = ./data -logs = ./data/log -plugins = ./data/plugins -[server] -http_port = 3000 -domain = 192.168.199.113 -[database] -[session] -[analytics] -check_for_updates = true -[security] -admin_user = admin -admin_password = admin -[snapshots] -[users] -[auth.anonymous] -[auth.basic] -[auth.ldap] -[smtp] -[emails] -[log] -mode = file -[log.console] -[log.file] -level = info -format = text -[log.syslog] -[event_publisher] -[dashboards.json] -enabled = false -path = ./data/dashboards -[metrics] -[grafana_net] -url = https://grafana.net - -... - -``` - -启动 Grafana 服务： - -{{< copyable "shell-regular" >}} - -```bash -./bin/grafana-server \ - --config="./conf/grafana.ini" & -``` - -### 配置 Grafana - -本小节介绍如何配置 Grafana。 - -#### 第 1 步：添加 Prometheus 数据源 - -1. 登录 Grafana 界面。 - - - 默认地址：`http://localhost:3000` - - 默认账户：admin - - 默认密码：admin - -2. 点击 Grafana 图标打开侧边栏。 - -3. 在侧边栏菜单中，点击 **Data Source**。 - -4. 点击 **Add data source**。 - -5. 指定数据源的相关信息： - - - 在 **Name** 处，为数据源指定一个名称。 - - 在 **Type** 处，选择 **Prometheus**。 - - 在 **URL** 处，指定 Prometheus 的 IP 地址。 - - 根据需求指定其它字段。 - -6. 点击 **Add** 保存新的数据源。 - -#### 第 2 步：导入 Grafana 面板 - -执行以下步骤，为 PD Server、TiKV Server 和 TiDB Server 分别导入 Grafana 面板： - -1. 点击侧边栏的 Grafana 图标。 - -2. 在侧边栏菜单中，依次点击 **Dashboards** > **Import** 打开 **Import Dashboard** 窗口。 - -3. 点击 **Upload .json File** 上传对应的 JSON 文件（下载 [TiDB Grafana 配置文件](https://github.com/pingcap/tidb-ansible/tree/master/scripts))。 - - > **注意：** - > - > TiKV、PD 和 TiDB 面板对应的 JSON 文件分别为 `tikv_summary.json`，`tikv_details.json`，`tikv_trouble_shooting.json`，`pd.json`，`tidb.json`，`tidb_summary.json`。 - -4. 点击 **Load**。 - -5. 选择一个 Prometheus 数据源。 - -6. 点击 **Import**，Prometheus 面板即导入成功。 - -### 查看组件 metrics - -在顶部菜单中，点击 **New dashboard**，选择要查看的面板。 - -![view dashboard](/media/view-dashboard.png) - -可查看以下集群组件信息： - -+ **TiDB Server：** - + query 处理时间，可以看到延迟和吞吐 - + ddl 过程监控 - + TiKV client 相关的监控 - + PD client 相关的监控 - -+ **PD Server：** - + 命令执行的总次数 - + 某个命令执行失败的总次数 - + 某个命令执行成功的耗时统计 - + 某个命令执行失败的耗时统计 - + 某个命令执行完成并返回结果的耗时统计 - -+ **TiKV Server：** - + GC 监控 - + 执行 KV 命令的总次数 - + Scheduler 执行命令的耗时统计 - + Raft propose 命令的总次数 - + Raft 执行命令的耗时统计 - + Raft 执行命令失败的总次数 - + Raft 处理 ready 状态的总次数 diff --git a/v3.0/how-to/monitor/overview.md b/v3.0/how-to/monitor/overview.md deleted file mode 100644 index 01290f2faaeb..000000000000 --- a/v3.0/how-to/monitor/overview.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB 监控框架概述 -category: how-to -aliases: ['/docs-cn/op-guide/monitor-overview/'] ---- - -# TiDB 监控框架概述 - -TiDB 使用开源时序数据库 [Prometheus](https://prometheus.io) 作为监控和性能指标信息存储方案，使用 [Grafana](https://grafana.com/grafana) 作为可视化组件进行展示。 - -## Prometheus 在 TiDB 中的应用 - -Prometheus 是一个拥有多维度数据模型的、灵活的查询语句的时序数据库。Prometheus 作为热门的开源项目，拥有活跃的社区及众多的成功案例。 - -Prometheus 提供了多个组件供用户使用。目前，TiDB 使用了以下组件： - -- Prometheus Server：用于收集和存储时间序列数据。 -- Client 代码库：用于定制程序中需要的 Metric。 -- Alertmanager：用于实现报警机制。 - -其结构如下图所示： - -![Prometheus in TiDB](/media/prometheus-in-tidb.png) - -## Grafana 在 TiDB 中的应用 - -Grafana 是一个开源的 metric 分析及可视化系统。TiDB 使用 Grafana 来展示 TiDB 的各项性能指标。如下图所示： - -![Grafana in TiDB](/media/grafana-screenshot.png) diff --git a/v3.0/how-to/scale/horizontally.md b/v3.0/how-to/scale/horizontally.md deleted file mode 100644 index 85262836b3ca..000000000000 --- a/v3.0/how-to/scale/horizontally.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: TiDB 集群扩容缩容方案 -category: how-to -aliases: ['/docs-cn/op-guide/horizontal-scale/'] ---- - -# TiDB 集群扩容缩容方案 - -TiDB 集群可以在不影响线上服务的情况下动态进行扩容和缩容。 - -> **注意：** -> -> 如果使用 Ansible 部署 TiDB 集群，请参考[使用 Ansible 扩容缩容](/v3.0/how-to/scale/with-ansible.md)。 - -下面分别介绍如何增加或者删除 PD，TiKV 以及 TiDB 的节点。 - -下面用到的 pd-ctl 文档可以参考 [pd-control](/v3.0/reference/tools/pd-control.md)。 - -## PD - -假设现在我们有三个 PD 服务，详细信息如下： - -|Name|ClientUrls|PeerUrls| -|----|----------|--------| -|pd1|`http://host1:2379`|`http://host1:2380`| -|pd2|`http://host2:2379`|`http://host2:2380`| -|pd3|`http://host3:2379`|`http://host3:2380`| - -我们可以通过 pd-ctl 来查看当前所有 PD 节点的信息： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 -i ->> member -``` - -### 动态添加节点 - -我们可以使用 `join` 参数，将一个新的 PD 服务加入到现有的 PD 集群里面。 -如果我们需要添加 `pd4`，只需要在 `--join` 参数里面填入当前 PD 集群任意一个 PD 服务的 client url，比如： - -{{< copyable "shell-regular" >}} - -```bash -./bin/pd-server --name=pd4 \ - --client-urls="http://host4:2379" \ - --peer-urls="http://host4:2380" \ - --join="http://host1:2379" -``` - -### 动态删除节点 - -如果我们需要删除 `pd4`，可以通过 pd-ctl 来完成： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> member delete name pd4 -``` - -### 动态迁移节点 - -如果想把现有的 PD 节点迁移到新的机器上，我们可以先在新的机器上添加节点，然后把旧的机器上的节点删除掉。迁移过程中应该一个节点一个节点逐个迁移，每完成一个步骤可以先查看一下当前的所有节点信息来进行确认。 - -## TiKV - -我们可以通过 pd-ctl 来查看当前所有 TiKV 节点的信息： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store -``` - -### 动态添加节点 - -动态添加一个新的 TiKV 服务非常容易，只需要在新的机器上启动一个 TiKV 服务，不需要其他特殊操作。 -新启动的 TiKV 服务会自动注册到现有集群的 PD 中，PD 会自动做负载均衡，逐步地把一部分数据迁移到新的TiKV 服务中，从而降低现有 TiKV 服务的压力。 - -### 动态删除节点 - -安全地删除（下线）一个 TiKV 服务需要先告诉 PD，这样 PD 可以先把这个 TiKV 服务上面的数据迁移到其他 TiKV 服务上，保证数据有足够的副本数。 - -假设我们需要删除 store id 为 1 的 TiKV 服务，可以通过 pd-ctl 来完成： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store delete 1 -``` - -然后可以查看这个 TiKV 服务的状态： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store 1 -``` - -``` -{ - "store": { - "id": 1, - "address": "127.0.0.1:21060", - "state": 1, - "state_name": "Offline" - }, - "status": { - ... - } -} -``` - -我们可以通过这个 store 的 state_name 来确定这个 store 的状态： - -- Up：这个 store 正常服务 -- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 -- Down：超过一小时（可通过 `max-down-time` 配置）没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 -- Offline：这个 store 正在将其中的 Region 转移到其他节点，此时这个 store 仍在服务中 -- Tombstone：这个 store 已经完成下线，此时 store 上已经没有数据，可以关闭实例 - -### 动态迁移节点 - -迁移 TiKV 服务也是通过先在新的机器上添加节点，然后把旧的机器上的节点下线来完成。迁移过程中可以先把新集群的机器全部添加到已有的集群中，然后再把旧的节点一个一个地下线。可以通过查看正在下线的节点的状态信息来确定这个节点是否已经完成下线，确认完成以后再下线下一个节点。 - -## TiDB - -TiDB 是一个无状态的服务，这也就意味着我们能直接添加和删除 TiDB。需要注意的是，如果我们在 TiDB 的服务的前面搭建了一个 proxy（譬如 HAProxy），则需要更新 proxy 的配置并重新载入。 diff --git a/v3.0/how-to/scale/with-ansible.md b/v3.0/how-to/scale/with-ansible.md deleted file mode 100644 index d86b927e01cb..000000000000 --- a/v3.0/how-to/scale/with-ansible.md +++ /dev/null @@ -1,528 +0,0 @@ ---- -title: 使用 TiDB Ansible 扩容缩容 TiDB 集群 -category: how-to -aliases: ['/docs-cn/op-guide/ansible-deployment-scale/'] ---- - -# 使用 TiDB Ansible 扩容缩容 TiDB 集群 - -TiDB 集群可以在不影响线上服务的情况下进行扩容和缩容。 - -> **注意：** -> -> 以下缩容示例中，被移除的节点没有混合部署其他服务；如果混合部署了其他服务，不能按如下操作。 - -假设拓扑结构如下所示： - -| Name | Host IP | Services | -| ---- | ------- | -------- | -| node1 | 172.16.10.1 | PD1 | -| node2 | 172.16.10.2 | PD2 | -| node3 | 172.16.10.3 | PD3, Monitor | -| node4 | 172.16.10.4 | TiDB1 | -| node5 | 172.16.10.5 | TiDB2 | -| node6 | 172.16.10.6 | TiKV1 | -| node7 | 172.16.10.7 | TiKV2 | -| node8 | 172.16.10.8 | TiKV3 | -| node9 | 172.16.10.9 | TiKV4 | - -## 扩容 TiDB/TiKV 节点 - -例如，如果要添加两个 TiDB 节点（node101、node102），IP 地址为 172.16.10.101、172.16.10.102，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.101 - 172.16.10.102 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - 172.16.10.101 - 172.16.10.102 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | **node101** | **172.16.10.101**|**TiDB3** | - | **node102** | **172.16.10.102**|**TiDB4** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml -l 172.16.10.101,172.16.10.102 - ``` - - > **注意：** - > - > 如果 `inventory.ini` 中为节点配置了别名，如 `node101 ansible_host=172.16.10.101`，执行 ansible-playbook 时 -l 请指定别名，以下步骤类似。例如：`ansible-playbook bootstrap.yml -l node101,node102` - -3. 部署新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml -l 172.16.10.101,172.16.10.102 - ``` - -4. 启动新节点服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml -l 172.16.10.101,172.16.10.102 - ``` - -5. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - - 可使用同样的步骤添加 TiKV 节点。但如果要添加 PD 节点，则需手动更新一些配置文件。 - -## 扩容 PD 节点 - -例如，如果要添加一个 PD 节点（node103），IP 地址为 172.16.10.103，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息置于 `[pd_servers]` 主机组最后一行： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | **node103** | **172.16.10.103** | **PD4** | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml -l 172.16.10.103 - ``` - -3. 部署新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml -l 172.16.10.103 - ``` - -4. 登录新增的 PD 节点，编辑启动脚本：`{deploy_dir}/scripts/run_pd.sh` - - 1. 移除 `--initial-cluster="xxxx" \` 配置，注意这里不能在行开头加注释符 #。 - - 2. 添加 `--join="http://172.16.10.1:2379" \`，IP 地址 （172.16.10.1） 可以是集群内现有 PD IP 地址中的任意一个。 - - 3. 在新增 PD 节点中手动启动 PD 服务： - - {{< copyable "shell-regular" >}} - - ```bash - {deploy_dir}/scripts/start_pd.sh - ``` - - > **注意：** - > - > 启动前，需要通过 [PD Control](/v3.0/reference/tools/pd-control.md) 工具确认当前 PD 节点的 `health` 状态均为 "true"，否则 PD 服务会启动失败，同时日志中报错 `["join meet error"] [error="etcdserver: unhealthy cluster"]`。 - - 4. 使用 `pd-ctl` 检查新节点是否添加成功： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -5. 滚动升级整个集群： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -6. 启动监控服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml -l 172.16.10.103 - ``` - -7. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -8. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - -## 缩容 TiDB 节点 - -例如，如果要移除一个 TiDB 节点（node5），IP 地址为 172.16.10.5，可以进行如下操作： - -1. 停止 node5 节点上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.5 - ``` - -2. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | **node5** | **172.16.10.5** | **TiDB2 已删除** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -3. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -4. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 TiKV 节点 - -例如，如果要移除一个 TiKV 节点（node9），IP 地址为 172.16.10.9，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node9 节点的 store id： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store - ``` - - 2. 从集群中移除 node9，假如 store id 为 10： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store delete 10 - ``` - -2. 使用 Grafana 或者 `pd-ctl` 检查节点是否下线成功（下线需要一定时间，下线节点的状态变为 Tombstone 就说明下线成功了）： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store 10 - ``` - -3. 下线成功后，停止 node9 上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.9 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | **node9** | **172.16.10.9** | **TiKV4 已删除** | - -5. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 PD 节点 - -例如，如果要移除一个 PD 节点（node2），IP 地址为 172.16.10.2，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node2 节点的 name： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - - 2. 从集群中移除 node2，假如 name 为 pd2： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member delete name pd2 - ``` - -2. 使用 `pd-ctl` 检查节点是否下线成功（PD 下线会很快，结果中没有 node2 节点信息即为下线成功）： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -3. 下线成功后，停止 node2 上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.2 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | **node2** | **172.16.10.2** | **PD2 已删除** | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -5. 滚动升级整个集群： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -6. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -7. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 diff --git a/v3.0/how-to/secure/enable-tls-between-components.md b/v3.0/how-to/secure/enable-tls-between-components.md deleted file mode 100644 index d92395648815..000000000000 --- a/v3.0/how-to/secure/enable-tls-between-components.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: 为 TiDB 组件间开启 TLS 和数据加密存储 -category: how-to -aliases: ['/docs-cn/op-guide/security/'] ---- - -# 为 TiDB 组件间开启 TLS 和数据加密存储 - -本文档介绍 TiDB 集群如何开启 TLS 验证和数据加密存储。 - -## 开启 TLS 验证 - -本部分介绍 TiDB 集群如何开启 TLS 验证，TLS 验证支持： - -- TiDB 组件之间的双向验证，包括 TiDB、TiKV、PD 相互之间，TiKV Control 与 TiKV、PD Control 与 PD 的双向认证，以及 TiKV peer 之间、PD peer 之间。一旦开启，所有组件之间均使用验证，不支持只开启某一部分的验证。 -- MySQL Client 与 TiDB 之间的客户端对服务器身份的单向验证以及双向验证。 - -MySQL Client 与 TiDB 之间使用一套证书，TiDB 集群组件之间使用另外一套证书。 - -### TiDB 集群组件间开启 TLS（双向认证） - -1. 准备证书。 - - 推荐为 TiDB、TiKV、PD 分别准备一个 server 证书，并保证可以相互验证，而它们的各种客户端共用 client 证书。 - - 有多种工具可以生成自签名证书，如 `openssl`，`easy-rsa`，`cfssl`。 - - 这里提供一个使用 `cfssl` 生成证书的示例：[生成自签名证书](/v3.0/how-to/secure/generate-self-signed-certificates.md)。 - -2. 配置证书。 - - - TiDB - - 在 `config` 文件或命令行参数中设置： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs for connection with cluster components. - cluster-ssl-ca = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format for connection with cluster components. - cluster-ssl-cert = "/path/to/tidb-server.pem" - # Path of file that contains X509 key in PEM format for connection with cluster components. - cluster-ssl-key = "/path/to/tidb-server-key.pem" - ``` - - - TiKV - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # set the path for certificates. Empty string means disabling secure connectoins. - ca-path = "/path/to/ca.pem" - cert-path = "/path/to/tikv-server.pem" - key-path = "/path/to/tikv-server-key.pem" - ``` - - - PD - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs. if set, following four settings shouldn't be empty - cacert-path = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format. - cert-path = "/path/to/pd-server.pem" - # Path of file that contains X509 key in PEM format. - key-path = "/path/to/pd-server-key.pem" - ``` - - 此时 TiDB 集群各个组件间已开启双向验证。 - - > **注意：** - > - > 若 TiDB 集群各个组件间已开启 TLS，在使用 tikv-ctl 或 pd-ctl 工具连接集群时，需要指定 client 证书，示例： - - {{< copyable "shell-regular" >}} - - ```bash - ./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/client-key.pem" - ``` - -### MySQL 与 TiDB 间开启 TLS - -请参考 [使用加密连接](/v3.0/how-to/secure/enable-tls-clients.md)。 - -## 开启数据加密存储 - -在 TiDB 集群中，用户的数据都存储在 TiKV 中，配置了 TiKV 数据加密存储功能，就代表 TiDB 集群已经加密存储了用户的数据。本部分主要介绍如何配置 TiKV 的加密存储功能。 - -### 操作流程 - -1. 生成 token 文件。 - - token 文件存储的是密钥，用于对用户数据进行加密，以及对已加密的数据进行解密。 - - {{< copyable "shell-regular" >}} - - ```bash - ./tikv-ctl random-hex --len 256 > cipher-file-256 - ``` - - > **注意：** - > - > TiKV 只接受 hex 格式的 token 文件，文件的长度必须是 2^n，并且小于等于 1024。 - -2. 配置 TiKV。 - - ```toml - [security] - # Cipher file 的存储路径 - cipher-file = "/path/to/cipher-file-256" - ``` - -> **注意：** -> -> 若使用 [Lightning](/v3.0/reference/tools/tidb-lightning/overview.md) 向集群导入数据，如果目标集群开启了加密功能，Lightning 生成的 sst 文件也必须是加密的格式。 - -### 使用限制 - -目前 TiKV 数据加密存储存在以下限制： - -- 对之前没有开启加密存储的集群，不支持开启该功能。 -- 已经开启加密功能的集群，不允许关闭加密存储功能。 -- 同一集群内部，不允许部分 TiKV 实例开启该功能，部分 TiKV 实例不开启该功能。对于加密存储功能，所有 TiKV 实例要么都开启该功能，要么都不开启该功能。这是由于 TiKV 实例之间会有数据迁移，如果开启了加密存储功能，迁移过程中数据也是加密的。 diff --git a/v3.0/how-to/secure/enable-tls-clients.md b/v3.0/how-to/secure/enable-tls-clients.md deleted file mode 100644 index 16d9895bcbf9..000000000000 --- a/v3.0/how-to/secure/enable-tls-clients.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: 使用加密连接 -category: how-to -aliases: ['/docs-cn/sql/encrypted-connections/'] ---- - -# 使用加密连接 - -TiDB 服务端默认采用非加密连接，因而具备监视信道流量能力的第三方可以知悉 TiDB 服务端与客户端之间发送和接受的数据，包括但不限于查询语句内容、查询结果等。若信道是不可信的，例如客户端是通过公网连接到 TiDB 服务端的，则非加密连接容易造成信息泄露，建议使用加密连接确保安全性。 - -TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接，协议与 MySQL 加密连接一致，现有 MySQL 客户端如 MySQL 运维工具和 MySQL 驱动等能直接支持。TLS 的前身是 SSL，因而 TLS 有时也被称为 SSL，但由于 SSL 协议有已知安全漏洞，TiDB 实际上并未支持。TiDB 支持的 TLS/SSL 协议版本为 TLS 1.0、TLS 1.1、TLS 1.2。 - -使用加密连接后，连接将具有以下安全性质： - -- 保密性：流量明文无法被窃听； -- 完整性：流量明文无法被篡改； -- 身份验证（可选）：客户端和服务端能验证双方身份，避免中间人攻击。 - -TiDB 的加密连接支持默认是关闭的，必须在 TiDB 服务端通过配置开启加密连接的支持后，才能在客户端中使用加密连接。另外，与 MySQL 一致，TiDB 加密连接是以单个连接为单位的，并且是可选的，因而对于开启了加密连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。大部分 MySQL 客户端默认不采用加密连接，因此一般还要显式地要求客户端使用加密连接。 - -简单来说，要使用加密连接必须同时满足以下两个条件： - -1. TiDB 服务端配置开启加密连接的支持 -2. 客户端指定使用加密连接 - -## 配置 TiDB 启用加密连接支持 - -在启动 TiDB 时，至少需要在配置文件中同时指定 `ssl-cert` 和 `ssl-key` 参数，才能使 TiDB 服务端接受加密连接。还可以指定 `ssl-ca` 参数进行客户端身份验证（请参见[配置启用身份验证](#配置启用身份验证)章节）。 - -- [`ssl-cert`](/v3.0/reference/configuration/tidb-server/configuration-file.md#ssl-cert)：指定 SSL 证书文件路径 -- [`ssl-key`](/v3.0/reference/configuration/tidb-server/configuration-file.md#ssl-key)：指定证书文件对应的私钥 -- [`ssl-ca`](/v3.0/reference/configuration/tidb-server/configuration-file.md#ssl-ca)：可选，指定受信任的 CA 证书文件路径 - -参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端加密连接到 TiDB 服务端。 - -上述证书及密钥可以使用 OpenSSL 签发和生成，也可以使用 MySQL 自带的工具 `mysql_ssl_rsa_setup` 快捷生成： - -{{< copyable "shell-regular" >}} - -```bash -mysql_ssl_rsa_setup --datadir=./certs -``` - -以上命令将在 `certs` 目录下生成以下文件： - -``` -certs -├── ca-key.pem -├── ca.pem -├── client-cert.pem -├── client-key.pem -├── private_key.pem -├── public_key.pem -├── server-cert.pem -└── server-key.pem -``` - -对应的 TiDB 配置文件参数为： - -```toml -[security] -ssl-cert = "certs/server-cert.pem" -ssl-key = "certs/server-key.pem" -``` - -若证书参数无误，则 TiDB 在启动时将会输出 `Secure connection is enabled`，否则 TiDB 会输出 `Secure connection is NOT ENABLED`。 - -## 配置 MySQL 客户端使用加密连接 - -MySQL 5.7 及以上版本自带的客户端默认尝试使用安全连接，若服务端不支持安全连接则自动退回到使用非安全连接；MySQL 5.7 以下版本自带的客户端默认采用非安全连接。 - -可以通过命令行参数修改客户端的连接行为，包括： - -- 强制使用安全连接，若服务端不支持安全连接则连接失败 (`--ssl-mode=REQUIRED`) -- 尝试使用安全连接，若服务端不支持安全连接则退回使用不安全连接 -- 使用不安全连接 (`--ssl-mode=DISABLED`) - -详细信息请参阅 MySQL 文档中关于[客户端配置安全连接](https://dev.mysql.com/doc/refman/5.7/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration)的部分。 - -## 配置启用身份验证 - -若在 TiDB 服务端或 MySQL 客户端中未指定 `ssl-ca` 参数，则默认不会进行客户端或服务端身份验证，无法抵御中间人攻击，例如客户端可能会“安全地”连接到了一个伪装的服务端。可以在服务端和客户端中配置 `ssl-ca` 参数进行身份验证。一般情况下只需验证服务端身份，但也可以验证客户端身份进一步增强安全性。 - -- 若要使 MySQL 客户端验证 TiDB 服务端身份，TiDB 服务端需至少配置 `ssl-cert` 和 `ssl-key` 参数，客户端需至少指定 `--ssl-ca` 参数，且 `--ssl-mode` 至少为 `VERIFY_CA`。必须确保 TiDB 服务端配置的证书（`ssl-cert`）是由客户端 `--ssl-ca` 参数所指定的 CA 所签发的，否则身份验证失败。 -- 若要使 TiDB 服务端验证 MySQL 客户端身份，TiDB 服务端需配置 `ssl-cert`、`ssl-key`、`ssl-ca` 参数，客户端需至少指定 `--ssl-cert`、`--ssl-key` 参数。必须确保服务端配置的证书和客户端配置的证书都是由服务端配置指定的 `ssl-ca` 签发的。 -- 若要进行双向身份验证，请同时满足上述要求。 - -> **注意：** -> -> 目前 TiDB 尚不支持强制验证客户端身份，即服务端对客户端的身份验证是可选的。若客户端在 TLS 握手时未出示自己的身份证书，也能正常建立 TLS 连接。 - -## 检查当前连接是否是加密连接 - -可以通过 `SHOW STATUS LIKE "%Ssl%";` 了解当前连接的详细情况，包括是否使用了安全连接、安全连接采用的加密协议、TLS 版本号等。 - -以下是一个安全连接中执行该语句的结果。由于客户端支持的 TLS 版本号和加密协议会有所不同，执行结果相应地也会有所变化。 - -{{< copyable "sql" >}} - -```sql -SHOW STATUS LIKE "%Ssl%"; -``` - -``` -...... -| Ssl_verify_mode | 5 | -| Ssl_version | TLSv1.2 | -| Ssl_cipher | ECDHE-RSA-AES128-GCM-SHA256 | -...... -``` - -除此以外，对于 MySQL 自带客户端，还可以使用 `STATUS` 或 `\s` 语句查看连接情况： - -{{< copyable "sql" >}} - -```sql -\s -``` - -``` -... -SSL: Cipher in use is ECDHE-RSA-AES128-GCM-SHA256 -... -``` - -## 支持的 TLS 版本及密钥交换协议和加密算法 - -TiDB 支持的 TLS 版本及密钥交换协议和加密算法由 Golang 官方库决定。 - -### 支持的 TLS 版本 - -- TLS 1.0 -- TLS 1.1 -- TLS 1.2 - -### 支持的密钥交换协议及加密算法 - -- TLS\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 -- TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 diff --git a/v3.0/how-to/secure/generate-self-signed-certificates.md b/v3.0/how-to/secure/generate-self-signed-certificates.md deleted file mode 100644 index c6fa6dbc5ec1..000000000000 --- a/v3.0/how-to/secure/generate-self-signed-certificates.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: 生成自签名证书 -category: how-to -aliases: ['/docs-cn/op-guide/generate-self-signed-certificates/'] ---- - -# 生成自签名证书 - -## 概述 - -本文档提供使用 `cfssl` 生成自签名证书的示例。 - -假设实例集群拓扑如下： - -| Name | Host IP | Services | -| ----- | ----------- | ---------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -## 下载 cfssl - -假设使用 x86_64 Linux 主机： - -{{< copyable "shell-regular" >}} - -```bash -mkdir ~/bin && -curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64 && -curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64 && -chmod +x ~/bin/{cfssl,cfssljson} && -export PATH=$PATH:~/bin -``` - -## 初始化证书颁发机构 - -生成 cfssl 的默认配置，以便于之后修改： - -```bash -mkdir ~/cfssl && -cd ~/cfssl && -cfssl print-defaults config > ca-config.json && -cfssl print-defaults csr > ca-csr.json -``` - -## 生成证书 - -### 证书介绍 - -- tidb-server certificate 由 TiDB 使用，为其他组件和客户端验证 TiDB 身份。 -- tikv-server certificate 由 TiKV 使用，为其他组件和客户端验证 TiKV 身份。 -- pd-server certificate 由 PD 使用，为其他组件和客户端验证 PD 身份。 -- client certificate 用于通过 PD、TiKV、TiDB 验证客户端。例如 `pd-ctl`，`tikv-ctl`，`pd-recover`。 - -### 配置 CA 选项 - -根据实际需求修改 `ca-config.json`： - -```json -{ - "signing": { - "default": { - "expiry": "43800h" - }, - "profiles": { - "server": { - "expiry": "43800h", - "usages": [ - "signing", - "key encipherment", - "server auth", - "client auth" - ] - }, - "client": { - "expiry": "43800h", - "usages": [ - "signing", - "key encipherment", - "client auth" - ] - } - } - } -} -``` - -根据实际需求修改 `ca-csr.json` ： - -```json -{ - "CN": "My own CA", - "key": { - "algo": "rsa", - "size": 2048 - }, - "names": [ - { - "C": "CN", - "L": "Beijing", - "O": "PingCAP", - "ST": "Beijing" - } - ] -} -``` - -### 生成 CA 证书 - -{{< copyable "shell-regular" >}} - -```bash -cfssl gencert -initca ca-csr.json | cfssljson -bare ca - -``` - -将会生成以下几个文件： - -``` -ca-key.pem -ca.csr -ca.pem -``` - -### 生成服务器端证书 - -`hostname` 中为各组件的 IP 地址，以及 `127.0.0.1` - -{{< copyable "shell-regular" >}} - -```bash -echo '{"CN":"tidb-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,127.0.0.1" - | cfssljson -bare tidb-server && - -echo '{"CN":"tikv-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.4,172.16.10.5,172.16.10.6,127.0.0.1" - | cfssljson -bare tikv-server && - -echo '{"CN":"pd-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,172.16.10.3,127.0.0.1" - | cfssljson -bare pd-server -``` - -将会生成以下几个文件： - -``` -tidb-server-key.pem tikv-server-key.pem pd-server-key.pem -tidb-server.csr tikv-server.csr pd-server.csr -tidb-server.pem tikv-server.pem pd-server.pem -``` - -### 生成客户端证书 - -{{< copyable "shell-regular" >}} - -```bash -echo '{"CN":"client","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client -hostname="" - | cfssljson -bare client -``` - -将会生成以下几个文件： - -``` -client-key.pem -client.csr -client.pem -``` diff --git a/v3.0/how-to/troubleshoot/cluster-setup.md b/v3.0/how-to/troubleshoot/cluster-setup.md deleted file mode 100644 index 9d1f0be45339..000000000000 --- a/v3.0/how-to/troubleshoot/cluster-setup.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: TiDB 集群故障诊断 -category: how-to -aliases: ['/docs-cn/trouble-shooting/'] ---- - -# TiDB 集群故障诊断 - -当试用 TiDB 遇到问题时，请先参考本篇文档。如果问题未解决，请按文档要求收集必要的信息通过 Github [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - -## 如何给 TiDB 开发者报告错误 - -当使用 TiDB 遇到问题并且通过后面所列信息无法解决时，请收集以下信息并[创建新 Issue](https://github.com/pingcap/tidb/issues/new/choose): - -+ 具体的出错信息以及正在执行的操作 -+ 当前所有组件的状态 -+ 出问题组件 log 中的 error/fatal/panic 信息 -+ 机器配置以及部署拓扑 -+ dmesg 中 TiDB 组件相关的问题 - -## 数据库连接不上 - -首先请确认集群的各项服务是否已经启动，包括 tidb-server、pd-server、tikv-server。请用 ps 命令查看所有进程是否在。如果某个组件的进程已经不在了，请参考对应的章节排查错误。 - -如果所有的进程都在，请查看 tidb-server 的日志，看是否有报错？常见的错误包括： - -+ InformationSchema is out of date - - 无法连接 tikv-server，请检查 pd-server 以及 tikv-server 的状态和日志。 - -+ panic - - 程序有错误，请将具体的 panic log [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - - 如果是清空数据并重新部署服务，请确认以下信息： - -+ pd-server、tikv-server 数据都已清空 - - tikv-server 存储具体的数据，pd-server 存储 tikv-server 中数据的的元信息。如果只清空 pd-server 或只清空 tikv-server 的数据，会导致两边数据不匹配。 - -+ 清空 pd-server 和 tikv-server 的数据并重启后，也需要重启 tidb-server - - 集群 ID 是由 pd-server 在集群初始化时随机分配，所以重新部署集群后，集群 ID 会发生变化。tidb-server 业务需要重启以获取新的集群 ID。 - -## tidb-server 启动报错 - -tidb-server 无法启动的常见情况包括： - -+ 启动参数错误 - - 请参考 [TiDB 命令行参数](/v3.0/reference/configuration/tidb-server/configuration.md) - -+ 端口被占用：`lsof -i:port` - - 请确保 tidb-server 启动所需要的端口未被占用。 - -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志，确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tidb-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。 - - 例如，假设 tidb 服务位于 `192.168.1.100`，无法连接的 pd 位于 `192.168.1.101`，且 2379 为其 client port， - 则可以在 tidb 机器上执行 `nc -v -z 192.168.1.101 2379`，测试是否可以访问端口。 - 或使用 `curl -v 192.168.1.101:2379/pd/api/v1/leader` 直接检查 pd 是否正常服务。 - -## tikv-server 启动报错 - -+ 启动参数错误 - - 请参考 [TiKV 启动参数](/v3.0/reference/configuration/tikv-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 tikv-server 启动所需要的端口未被占用：`lsof -i:port`。 -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志。确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tikv-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。具体命令参考上一节。 - -+ 文件被占用 - - 不要在一个数据库文件目录上打开两个 tikv。 - -## pd-server 启动报错 - -+ 启动参数错误 - - 请参考[PD 命令行参数](/v3.0/reference/configuration/pd-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 pd-server 启动所需要的端口未被占用：`lsof -i:port`。 - -## TiDB/TiKV/PD 进程异常退出 - -+ 进程是否是启动在前台 - - 当前终端退出给其所有子进程发送 HUP 信号，从而导致进程退出。 - -+ 是否是在命令行用过 `nohup+&` 方式直接运行 - - 这样依然可能导致进程因终端连接突然中断，作为终端 SHELL 的子进程被杀掉。 - - 推荐将启动命令写在脚本中，通过脚本运行（相当于二次 fork 启动）。 - -## TiKV 进程异常重启 - -+ 检查 dmesg 或者 syslog 里面是否有 OOM 信息 - - 如果有 OOM 信息并且杀掉的进程为 TiKV，请减少 TiKV 的 RocksDB 的各个 CF 的 `block-cache-size` 值。 - -+ 检查 TiKV 日志是否有 panic 的 log - - 提交 Issue 并附上 panic 的 log。 - -## TiDB panic - -请提供 panic 的 log。 - -## 连接被拒绝 - -+ 请确保操作系统的网络参数正确，包括但不限于 - - 连接字符串中的端口和 tidb-server 启动的端口需要一致 - - 请保证防火墙的配置正确 - -## Too many open files - -在启动进程之前，请确保 `ulimit -n` 的结果足够大，推荐设为 unlimited 或者是大于 1000000。 - -## 数据库访问超时，系统负载高 - -首先检查 [SLOW-QUERY](/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息： - -+ 部署的拓扑结构 - - tidb-server/pd-server/tikv-server 部署了几个实例 - - 这些实例在机器上是如何分布的 -+ 机器的硬件配置 - - CPU 核数 - - 内存大小 - - 硬盘类型（SSD 还是机械硬盘） - - 是实体机还是虚拟机 -+ 机器上除了 TiDB 集群之外是否还有其他服务 -+ pd-server 和 tikv-server 是否分开部署 -+ 目前正在进行什么操作 -+ 用 `top -H` 命令查看当前占用 CPU 的线程名 -+ 最近一段时间的网络/IO 监控数据是否有异常 diff --git a/v3.0/how-to/troubleshoot/tidb-lightning.md b/v3.0/how-to/troubleshoot/tidb-lightning.md deleted file mode 100644 index 22ab5fc89172..000000000000 --- a/v3.0/how-to/troubleshoot/tidb-lightning.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: TiDB Lightning 故障诊断 -category: reference -aliases: ['/docs-cn/tools/lightning/errors/'] ---- - -# TiDB Lightning 故障诊断 - -当 Lightning 遇到不可恢复的错误时便会异常退出，并在日志中记下错误原因。一般可在日志底部找到，也可以搜索 `[error]` 字符串找出中间发生的错误。本文主要描述一些常见的错误及其解决方法。 - -## 导入速度太慢 - -TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件，如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 `restore chunk … takes` 的记录，或者观察 Grafana 的监控信息。 - -导入速度太慢一般有几个原因： - -**原因 1**：`region-concurrency` 设定太高，线程间争用资源反而减低了效率。 - -1. 从日志的开头搜寻 `region-concurrency` 能知道 Lightning 读到的参数是多少。 -2. 如果 Lightning 与其他服务（如 Importer）共用一台服务器，必需**手动**将 `region-concurrency` 设为该服务器 CPU 数量的 75%。 -3. 如果 CPU 设有限额（例如从 Kubernetes 指定的上限），Lightning 可能无法自动判断出来，此时亦需要**手动**调整 `region-concurrency`。 - -**原因 2**：表结构太复杂。 - -每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 - -**原因 3**：Lightning 版本太旧。 - -试试最新的版本吧！可能会有改善。 - -## checksum failed: checksum mismatched remote vs local - -**原因**：本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因： - -1. 这张表可能本身已有数据，影响最终结果。 -2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。 -3. 如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如： - - * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。 - * 唯一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。 -4. 如果 TiDB Lightning 之前失败停机过，但没有正确重启，可能会因为数据不同步而出现校验和不一致。 - -**解决办法**： - -1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。 - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。 - -3. 参考[如何正确重启 TiDB Lightning](/v3.0/faq/tidb-lightning.md#如何正确重启-tidb-lightning)中的解决办法。 - -## Checkpoint for … has invalid status:（错误码） - -**原因**：[断点续传](/v3.0/reference/tools/tidb-lightning/checkpoints.md)已启用。Lightning 或 Importer 之前发生了异常退出。为了防止数据意外损坏，Lightning 在错误解决以前不会启动。 - -错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。 - -**解决办法**： - -如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。 - -{{< copyable "shell-regular" >}} - -```sh -tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all -``` - -其他解决方法请参考[断点续传的控制](/v3.0/reference/tools/tidb-lightning/checkpoints.md#断点续传的控制)。 - -## ResourceTemporarilyUnavailable("Too many open engines …: …") - -**原因**：并行打开的引擎文件 (engine files) 超出 `tikv-importer` 里的限制。这可能由配置错误引起。即使配置没问题，如果 `tidb-lightning` 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。 - -**解决办法**： - -1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为： - - 最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number` - -2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。 - -3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录： - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -## cannot guess encoding for input file, please convert to UTF-8 manually - -**原因**：Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如，因为在不同的环境运行过 `ALTER TABLE`，使表架构同时出现 UTF-8 和 GB-18030 的字符。 - -**解决办法**： - -1. 编辑数据源，保存为纯 UTF-8 或 GB-18030 的文件。 -2. 手动在目标数量库创建所有的表，然后设置 `[mydumper] no-schema = true` 跳过创建表的步骤。 -3. 设置 `[mydumper] character-set = "binary"` 跳过这个检查。但是这样可能使数据库出现乱码。 - -## [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 …}' - -**原因**: 一个 `timestamp` 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。 - -**解决办法**: - -1. 确保 Lightning 与数据源时区一致。 - - * 使用 Ansible 部署的话，修正 [`inventory.ini`] 下的 `timezone` 变量。 - - ```ini - # inventory.ini - [all:vars] - timezone = Asia/Shanghai - ``` - - * 手动部署的话，通过设定 `$TZ` 环境变量强制时区设定。 - - 强制使用 Asia/Shanghai 时区： - - {{< copyable "shell-regular" >}} - - ```sh - TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml - ``` - -2. 导出数据时，必须加上 `--skip-tz-utc` 选项。 - -3. 确保整个集群使用的是同一最新版本的 `tzdata` (2018i 或更高版本)。 - - 如果你使用的是 CentOS 机器，你可以运行 `yum info tzdata` 命令查看 `tzdata` 的版本及是否有更新。然后运行 `yum upgrade tzdata` 命令升级 `tzdata`。 diff --git a/v3.0/how-to/upgrade/from-previous-version.md b/v3.0/how-to/upgrade/from-previous-version.md deleted file mode 100644 index 070b26424d6b..000000000000 --- a/v3.0/how-to/upgrade/from-previous-version.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: TiDB 3.0 升级操作指南 -category: how-to -aliases: ['/docs-cn/op-guide/tidb-v3.0-upgrade-guide/','/docs-cn/v3.0/how-to/upgrade/to-tidb-3.0','/docs-cn/v2.1/how-to/upgrade/to-tidb-3.0/','/docs-cn/v3.0/how-to/upgrade/rolling-updates-with-ansible/'] ---- - -# TiDB 3.0 升级操作指南 - -本文档适用于从 TiDB 2.0 或 2.1 版本升级至 TiDB 3.0 版本以及 TiDB 3.0 低版本升级至 TiDB 3.0 高版本。目前，TiDB 3.0 版本兼容 [TiDB Binlog Cluster 版本](/v3.0/reference/tidb-binlog/overview.md)。 - -## 升级兼容性说明 - -- 不支持在升级后回退至 2.1.x 或更旧版本 -- 从 2.0.6 之前的版本升级到 3.0 之前，需要确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 `Add Index` 操作，等 DDL 操作完成后再执行升级操作 -- 2.1 及之后版本启用了并行 DDL，早于 2.0.1 版本的集群，无法滚动升级到 3.0，可以选择下面两种方案： - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 3.0 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 3.0 版本 - -> **注意：** -> -> 在升级的过程中不要执行 DDL 请求，否则可能会出现行为未定义的问题。 - -## 在中控机器上安装 Ansible 及其依赖 - -> **注意：** -> -> 如果已经安装了 Ansible 及其依赖，可跳过该步骤。 - -TiDB Ansible release-3.0 版本依赖 2.4.2 及以上但不高于 2.7.11 的 Ansible 版本（`2.4.2 ≦ ansible ≦ 2.7.11`，建议 2.7.11 版本），另依赖 Python 模块：`jinja2 ≧ 2.9.6` 和 `jmespath ≧ 0.9.0`。为方便管理依赖，建议使用 `pip` 安装 Ansible 及其依赖，可参照[在中控机器上安装 Ansible 及其依赖](/v3.0/how-to/deploy/orchestrated/ansible.md#在中控机器上安装-ansible-及其依赖) 进行安装。离线环境参照[在中控机器上离线安装 Ansible 及其依赖](/v3.0/how-to/deploy/orchestrated/offline-ansible.md#在中控机器上离线安装-ansible-及其依赖)。 - -安装完成后，可通过以下命令查看版本： - -{{< copyable "shell-regular" >}} - -```bash -ansible --version -``` - -``` -ansible 2.7.11 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jinja2 -``` - -``` -Name: Jinja2 -Version: 2.10 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jmespath -``` - -``` -Name: jmespath -Version: 0.9.0 -``` - -> **注意：** -> -> 请务必按以上文档安装 Ansible 及其依赖。确认 Jinja2 版本是否正确，否则启动 Grafana 时会报错。确认 jmespath 版本是否正确，否则滚动升级 TiKV 时会报错。 - -## 在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录，备份 TiDB 2.0 版本或 TiDB 2.1 版本或 TiDB 3.0 低版本的 tidb-ansible 文件夹： - -{{< copyable "shell-regular" >}} - -```bash -mv tidb-ansible tidb-ansible-bak -``` - -下载 TiDB 3.0 版本对应 tag 的 tidb-ansible [**下载 TiDB Ansible**](/v3.0/how-to/deploy/orchestrated/ansible.md#在中控机器上下载-tidb-ansible)，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone -b $tag https://github.com/pingcap/tidb-ansible.git -``` - -## 编辑 inventory.ini 文件和配置文件 - -以 `tidb` 用户登录中控机并进入 `/home/tidb/tidb-ansible` 目录。 - -### 编辑 `inventory.ini` 文件 - -编辑 `inventory.ini` 文件，IP 信息参照备份文件 `/home/tidb/tidb-ansible-bak/inventory.ini`。 - -以下变量配置，需要重点确认，变量含义可参考 [inventory.ini 变量调整](/v3.0/how-to/deploy/orchestrated/ansible.md#调整其它变量可选)。 - -1. 请确认 `ansible_user` 配置的是普通用户。为统一权限管理，不再支持使用 root 用户远程安装。默认配置中使用 `tidb` 用户作为 SSH 远程用户及程序运行用户。 - - ``` - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - 可参考[如何配置 SSH 互信及 sudo 规则](/v3.0/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)自动配置主机间互信。 - -2. `process_supervision` 变量请与之前版本保持一致，默认推荐使用 `systemd`。 - - ``` - # process supervision, [systemd, supervise] - process_supervision = systemd - ``` - - 如需变更，可参考[如何调整进程监管方式从 supervise 到 systemd](/v3.0/how-to/deploy/orchestrated/ansible.md#如何调整进程监管方式从-supervise-到-systemd)，先使用备份 `/home/tidb/tidb-ansible-bak/` 分支变更进程监管方式再升级。 - -### 编辑 TiDB 集群组件配置文件 - -如之前自定义过 TiDB 集群组件配置文件，请参照备份文件修改 `/home/tidb/tidb-ansible/conf` 下对应配置文件。 - -**注意以下参数变更：** - -- TiKV 配置中 `end-point-concurrency` 变更为 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ``` - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 2.0 版本升级且单机多 TiKV 实例（进程）情况下，需要修改这三个参数。 - > - > 推荐设置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 - -- TiKV 配置中不同 CF 中的 `block-cache-size` 参数变更为 `block-cache`： - - ``` - storage: - block-cache: - capacity: "1GB" - ``` - - > **注意：** - > - > 单机多 TiKV 实例（进程）情况下，需要修改 `capacity` 参数。 - > - > 推荐设置：`capacity` = (MEM_TOTAL * 0.5 / TiKV 实例数量) - -- TiKV 配置中单机多实例场景需要额外配置 `tikv_status_port` 端口： - - ``` - [tikv_servers] - TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" - TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" - TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" - TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" - TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" - TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - ``` - - > **注意：** - > - > 3.0 版本单机多 TiKV 实例（进程）情况下，需要添加 `tikv_status_port` 参数。 - > - > 配置前，注意检查端口是否有冲突。 - -## 下载 TiDB 3.0 binary 到中控机 - -确认 `tidb-ansible/inventory.ini` 文件中 `tidb_version = v3.0.x`，然后执行以下命令下载 TiDB 3.0 binary 到中控机。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 滚动升级 TiDB 集群组件 - -- 如果 `process_supervision` 变量使用默认的 `systemd` 参数： - - - 当前集群版本 < 3.0，则通过 `excessive_rolling_update.yml` 滚动升级 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook excessive_rolling_update.yml - ``` - - - 当前集群版本 ≥ 3.0.0，滚动升级及日常滚动重启 TiDB 集群，使用 `rolling_update.yml`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -- 如果 `process_supervision` 变量使用的是 `supervise` 参数，无论当前集群为哪个版本，均通过 `rolling_update.yml` 来滚动升级 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -## 滚动升级 TiDB 监控组件 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook rolling_update_monitor.yml -``` diff --git a/v3.0/key-features.md b/v3.0/key-features.md deleted file mode 100644 index 55561ef23ec2..000000000000 --- a/v3.0/key-features.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB 核心特性 -category: introduction -aliases: ['/docs-cn/features/','/docs-cn/key-features/'] ---- - -# TiDB 核心特性 - -本文详细介绍 TiDB 的两大核心特性：水平扩展与高可用。 - -## 水平扩展 - -无限水平扩展是 TiDB 的一大特点，这里说的水平扩展包括两方面：计算能力和存储能力。TiDB Server 负责处理 SQL 请求，随着业务的增长，可以简单的添加 TiDB Server 节点，提高整体的处理能力，提供更高的吞吐。TiKV 负责存储数据，随着数据量的增长，可以部署更多的 TiKV Server 节点解决数据 Scale 的问题。PD 会在 TiKV 节点之间以 Region 为单位做调度，将部分数据迁移到新加的节点上。所以在业务的早期，可以只部署少量的服务实例（推荐至少部署 3 个 TiKV， 3 个 PD，2 个 TiDB），随着业务量的增长，按照需求添加 TiKV 或者 TiDB 实例。 - -## 高可用 - -高可用是 TiDB 的另一大特点，TiDB/TiKV/PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。下面分别说明这三个组件的可用性、单个实例失效后的后果以及如何恢复。 - -- TiDB - - TiDB 是无状态的，推荐至少部署两个实例，前端通过负载均衡组件对外提供服务。当单个实例失效时，会影响正在这个实例上进行的 Session，从应用的角度看，会出现单次请求失败的情况，重新连接后即可继续获得服务。单个实例失效后，可以重启这个实例或者部署一个新的实例。 - -- PD - - PD 是一个集群，通过 Raft 协议保持数据的一致性，单个实例失效时，如果这个实例不是 Raft 的 leader，那么服务完全不受影响；如果这个实例是 Raft 的 leader，会重新选出新的 Raft leader，自动恢复服务。PD 在选举的过程中无法对外提供服务，这个时间大约是3秒钟。推荐至少部署三个 PD 实例，单个实例失效后，重启这个实例或者添加新的实例。 - -- TiKV - - TiKV 是一个集群，通过 Raft 协议保持数据的一致性（副本数量可配置，默认保存三副本），并通过 PD 做负载均衡调度。单个节点失效时，会影响这个节点上存储的所有 Region。对于 Region 中的 Leader 节点，会中断服务，等待重新选举；对于 Region 中的 Follower 节点，不会影响服务。当某个 TiKV 节点失效，并且在一段时间内（默认 30 分钟）无法恢复，PD 会将其上的数据迁移到其他的 TiKV 节点上。 diff --git a/v3.0/overview.md b/v3.0/overview.md deleted file mode 100644 index 3d3d3b178f4e..000000000000 --- a/v3.0/overview.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/v3.0/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，配合 [TiDB Operator 项目](/v3.0/tidb-in-kubernetes/tidb-operator-overview.md) 可实现自动化运维，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v3.0/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/v3.0/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，推荐使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v3.0/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 TiDB Operator 部署](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md)：使用 TiDB Operator 在 Kubernetes 集群上部署生产就绪的 TiDB 集群，支持[部署到 AWS EKS](/v3.0/tidb-in-kubernetes/deploy/aws-eks.md)、[部署到谷歌云 GKE (beta)](/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md)、[部署到阿里云 ACK](/v3.0/tidb-in-kubernetes/deploy/alibaba-cloud.md) 等。 -- [使用 Docker Compose 部署](/v3.0/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v3.0/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 -- [使用 TiDB Operator 部署到 Minikube](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：你可以使用 TiDB Opeartor 将 TiDB 集群部署到本地 Minikube 启动的 Kubernetes 集群中。该部署方式不适用于生产环境。 -- [使用 TiDB Operator 部署到 kind](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：你可以使用 TiDB Operator 将 TiDB 集群部署到以 kind 方式启动的 Kubernetes 本地集群中。该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/v3.0/reference/alert-rules.md b/v3.0/reference/alert-rules.md deleted file mode 100644 index 04ef7c659d51..000000000000 --- a/v3.0/reference/alert-rules.md +++ /dev/null @@ -1,1161 +0,0 @@ ---- -title: TiDB 集群报警规则 -summary: TiDB 集群中各组件的报警规则详解。 -category: reference ---- - -# TiDB 集群报警规则 - -本文介绍了 TiDB 集群中各组件的报警规则，包括 TiDB、TiKV、PD、TiDB Binlog、Node_exporter 和 Blackbox_exporter 的各报警项的规则描述及处理方法。 - -## TiDB 报警规则 - -本节介绍了 TiDB 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_schema_error` - -* 报警规则： - - `increase(tidb_session_schema_lease_error_total{type="outdated"}[15m]) > 0` - -* 规则描述： - - TiDB 在一个 Lease 时间内没有重载到最新的 Schema 信息。如果 TiDB 无法继续对外提供服务，则报警。 - -* 处理方法： - - 该问题通常由于 TiKV Region 不可用或超时导致，需要看 TiKV 的监控指标定位问题。 - -#### `TiDB_tikvclient_region_err_total` - -* 报警规则： - - `increase(tidb_tikvclient_region_err_total[10m]) > 6000` - -* 规则描述： - - TiDB 访问 TiKV 时发生了 Region 错误。如果在 10 分钟之内该错误多于 6000 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_domain_load_schema_total` - -* 报警规则： - - `increase(tidb_domain_load_schema_total{type="failed"}[10m]) > 10` - -* 规则描述： - - TiDB 重载最新的 Schema 信息失败的总次数。如果在 10 分钟之内重载失败次数超过 10 次，则报警。 - -* 处理方法： - - 参考 [`TiDB_schema_error`](#tidb_schema_error) 的处理方法。 - -#### `TiDB_monitor_keep_alive` - -* 报警规则： - - `increase(tidb_monitor_keep_alive_total[10m]) < 100` - -* 规则描述： - - 表示 TiDB 的进程是否仍然存在。如果在 10 分钟之内 `tidb_monitor_keep_alive_total` 增加次数少于 100，则 TiDB 的进程可能已经退出，此时会报警。 - -* 处理方法： - - * 检查 TiDB 进程是否 OOM。 - * 检查机器是否发生了重启。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiDB_server_panic_total` - -* 报警规则： - - `increase(tidb_server_panic_total[10m]) > 0` - -* 规则描述： - - 发生崩溃的 TiDB 线程的数量。当出现崩溃的时候会报警。该线程通常会被恢复，否则 TiDB 会频繁重启。 - -* 处理方法： - - 收集 panic 日志，定位原因。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiDB_memory_abnormal` - -* 报警规则： - - `go_memstats_heap_inuse_bytes{job="tidb"} > 1e+10` - -* 规则描述： - - 对 TiDB 内存使用量的监控。如果内存使用大于 10 G，则报警。 - -* 处理方法： - - 通过 HTTP API 来排查 goroutine 泄露的问题。 - -#### `TiDB_query_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tidb_server_handle_query_duration_seconds_bucket[1m])) BY (le, instance)) > 1` - -* 规则描述： - - TiDB 处理请求的延时。如果 .99 的延迟大于 1 秒，则报警。 - -* 处理方法： - - 查看 TiDB 的日志，搜索 SLOW_QUERY 和 TIME_COP_PROCESS 关键字，查找慢 SQL。 - -#### `TiDB_server_event_error` - -* 报警规则： - - `increase(tidb_server_event_total{type=~"server_start|server_hang"}[15m]) > 0` - -* 规则描述： - - TiDB 服务中发生的事件数量。当出现以下事件的时候会报警： - - 1. start：TiDB 服务启动。 - 2. hang：当发生了 Critical 级别的事件时（目前只有 Binlog 写不进去一种情况），TiDB 进入 `hang` 模式，并等待人工 Kill。 - -* 处理方法： - - * 重启 TiDB 以恢复服务。 - * 检查 TiDB Binlog 服务是否正常。 - -#### `TiDB_tikvclient_backoff_total` - -* 报警规则： - - `increase(tidb_tikvclient_backoff_total[10m]) > 10` - -* 规则描述： - - TiDB 访问 TiKV 发生错误时发起重试的次数。如果在 10 分钟之内重试次数多于 10 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_monitor_time_jump_back_error` - -* 报警规则： - - `increase(tidb_monitor_time_jump_back_total[10m]) > 0` - -* 规则描述： - - 如果 TiDB 所在机器的时间发生了回退，则报警。 - -* 处理方法： - - 排查 NTP 配置。 - -#### `TiDB_ddl_waiting_jobs` - -* 报警规则： - - `sum(tidb_ddl_waiting_jobs) > 5` - -* 规则描述： - - 如果 TiDB 中等待执行的 DDL 任务的数量大于 5，则报警。 - -* 处理方法： - - 通过 `admin show ddl` 语句检查是否有耗时的 add index 操作正在执行。 - -## PD 报警规则 - -本节介绍了 PD 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `PD_cluster_offline_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_down_count"}) > 0` - -* 规则描述： - - PD 长时间（默认配置是 30 分钟）没有收到 TiKV 心跳。 - -* 处理方法： - - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `PD_etcd_write_disk_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[1m])) by (instance,job,le)) > 1` - -* 规则描述： - - etcd 写盘慢，这很容易引起 PD leader 超时或者 TSO 无法及时存盘等问题，从而导致整个集群停止服务。 - -* 处理方法： - - * 排查写入慢的原因。可能是由于其他服务导致系统负载过高。可以检查 PD 本身是否占用了大量 CPU 或 IO 资源。 - * 可尝试重启 PD 或手动 transfer leader 至其他的 PD 来恢复服务。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_miss_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="miss_peer_region_count"}) > 100` - -* 规则描述： - - Region 的副本数小于 `max-replicas` 配置的值。这通常是由于 TiKV 宕机等问题导致一段时间内一些 Region 缺副本，下线 TiKV 节点也会导致少量 Region 缺副本（对于有 pending peer 的 Region 会走先减后加的流程）。 - -* 处理方法： - - * 查看是否有 TiKV 宕机或在做下线操作，尝试定位问题产生的原因。 - * 观察 region health 面板，查看 `miss_peer_region_count` 是否在不断减少。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `PD_cluster_lost_connect_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_disconnected_count"}) > 0` - -* 规则描述： - - PD 在 20 秒之内未收到 TiKV 上报心跳。正常情况下是每 10 秒收到 1 次心跳。 - -* 处理方法： - - * 排查是否在重启 TiKV。 - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - * 如果确定 TiKV 可以恢复，但在短时间内还无法恢复，可以考虑延长 `max-down-time` 配置，防止超时后 TiKV 被判定为无法恢复并开始搬移数据。 - -#### `PD_cluster_low_space` - -* 报警规则： - - `sum(pd_cluster_status{type="store_low_space_count"}) > 0` - -* 规则描述： - - 表示 TiKV 节点空间不足。 - -* 处理方法： - - * 检查集群中的空间是否普遍不足。如果是，则需要扩容。 - * 检查 Region balance 调度是否有问题。如果有问题，会导致数据分布不均衡。 - * 检查是否有文件占用了大量磁盘空间，比如日志、快照、core dump 等文件。 - * 降低该节点的 Region weight 来减少数据量。 - * 无法释放空间时，可以考虑主动下线该节点，防止由于磁盘空间不足而宕机。 - -#### `PD_etcd_network_peer_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_network_peer_round_trip_time_seconds_bucket[1m])) by (To,instance,job,le)) > 1` - -* 规则描述： - - PD 节点之间网络延迟高，严重情况下会导致 leader 超时和 TSO 存盘超时，从而影响集群服务。 - -* 处理方法： - - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_tidb_handle_requests_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(pd_client_request_handle_requests_duration_seconds_bucket{type="tso"}[1m])) by (instance,job,le)) > 0.1` - -* 规则描述： - - PD 处理 TSO 请求耗时过长，一般是由于负载过高。 - -* 处理方法： - - * 检查服务器负载状况。 - * 使用 pprof 抓取 PD 的 CPU profile 进行分析。 - * 手动切换 PD leader。 - * 如果是环境问题，则将有问题的 PD 下线替换。 - -#### `PD_down_peer_region_nums` - -* 报警规则： - - `sum(pd_regions_status{type="down_peer_region_count"}) > 0` - -* 规则描述： - - Raft leader 上报有不响应 peer 的 Region 数量。 - -* 处理方法： - - * 检查是否有 TiKV 宕机，或刚发生重启，或者繁忙。 - * 观察 region health 面板，检查 `down_peer_region_count` 是否在不断减少。 - * 检查是否有 TiKV 之间网络不通。 - -#### `PD_pending_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="pending_peer_region_count"}) > 100` - -* 规则描述： - - Raft log 落后的 Region 过多。由于调度产生少量的 pending peer 是正常的，但是如果持续很高，就可能有问题。 - -* 处理方法： - - * 观察 region health 面板，检查 `pending_peer_region_count` 是否在不断减少。 - * 检查 TiKV 之间的网络状况，特别是带宽是否足够。 - -#### `PD_leader_change` - -* 报警规则： - - `count(changes(pd_server_tso{type="save"}[10m]) > 0) >= 2` - -* 规则描述： - - 近期发生了 PD leader 切换。 - -* 处理方法： - - * 排除人为因素，比如重启 PD、手动 transfer leader 或调整 leader 优先级等。 - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `TiKV_space_used_more_than_80%` - -* 报警规则： - - `sum(pd_cluster_status{type="storage_size"}) / sum(pd_cluster_status{type="storage_capacity"}) * 100 > 80` - -* 规则描述： - - 集群空间占用超过 80%。 - -* 处理方法： - - * 确认是否需要扩容。 - * 排查是否有文件占用了大量磁盘空间，比如日志、快照或 core dump等文件。 - -#### `PD_system_time_slow` - -* 报警规则： - - `changes(pd_server_tso{type="system_time_slow"}[10m]) >= 1` - -* 规则描述： - - 系统时间可能发生回退。 - -* 处理方法： - - 检查系统时间设置是否正确。 - -#### `PD_no_store_for_making_replica` - -* 报警规则： - - `increase(pd_checker_event_count{type="replica_checker", name="no_target_store"}[1m]) > 0` - -* 规则描述： - - 没有合适的 store 用来补副本。 - -* 处理方法： - - * 检查 store 是否空间不足。 - * 根据 label 配置（如果有这个配置的话）来检查是否有可以补副本的 store。 - -## TiKV 报警规则 - -本节介绍了 TiKV 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiKV_memory_used_too_fast` - -* 报警规则： - - `process_resident_memory_bytes{job=~"tikv",instance=~".*"} - (process_resident_memory_bytes{job=~"tikv",instance=~".*"} offset 5m) > 5*1024*1024*1024` - -* 规则描述： - - 目前没有和内存相关的 TiKV 的监控，你可以通过 Node_exporter 监控集群内机器的内存使用情况。如上规则表示，如果在 5 分钟之内内存使用超过 5GB（TiKV 内存占用的太快），则报警。 - -* 处理方法： - - 调整 `rockdb.defaultcf` 和 `rocksdb.writecf` 的 `block-cache-size` 的大小。 - -#### `TiKV_GC_can_not_work` - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="success"}[6h])) < 1` - - > **注意：** - > - > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 - -* 规则描述： - - 在 6 小时内 Region 上没有成功执行 GC，说明 GC 不能正常工作了。短期内 GC 不运行不会造成太大的影响，但如果 GC 一直不运行，版本会越来越多，从而导致查询变慢。 - -* 处理方法： - - 1. 执行 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME="tikv_gc_leader_desc"` 来找到 gc leader 对应的 `tidb-server`； - 2. 查看该 `tidb-server` 的日志，grep gc_worker tidb.log； - 3. 如果发现这段时间一直在 resolve locks（最后一条日志是 `start resolve locks`）或者 delete ranges（最后一条日志是 `start delete {number} ranges`），说明 GC 进程是正常的。否则需要报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiKV_server_report_failure_msg_total` - -* 报警规则： - - `sum(rate(tikv_server_report_failure_msg_total{type="unreachable"}[10m])) BY (store_id) > 10` - -* 规则描述： - - 表明无法连接远端的 TiKV。 - -* 处理方法： - - 1. 检查网络是否通畅。 - 2. 检查远端 TiKV 是否挂掉。 - 3. 如果远端 TiKV 没有挂掉，检查压力是否太大，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 处理方法。 - -#### `TiKV_channel_full_total` - -* 报警规则： - - `sum(rate(tikv_channel_full_total[10m])) BY (type, instance) > 0` - -* 规则描述： - - 该错误通常是因为 Raftstore 线程卡死，TiKV 的压力已经非常大了。 - -* 处理方法： - - 1. 观察 Raft Propose 监控，看这个报警的 TiKV 节点是否明显有比其他 TiKV 高很多。如果是，表明这个 TiKV 上有热点，需要检查热点调度是否能正常工作。 - 2. 观察 Raft IO 监控，看延迟是否升高。如果延迟很高，表明磁盘可能有瓶颈。一个能缓解但不怎么安全的办法是将 `sync-log` 改成 `false`。 - 3. 观察 Raft Process 监控，看 tick duration 是否很高。如果是，需要在 `[raftstore]` 配置下加上 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_write_stall` - -* 报警规则： - - `delta(tikv_engine_write_stall[10m]) > 0` - -* 规则描述： - - RocksDB 写入压力太大，出现了 stall。 - -* 处理方法： - - 1. 观察磁盘监控，排除磁盘问题。 - 2. 看 TiKV 是否有写入热点。 - 3. 在 `[rocksdb]` 和 `[raftdb]` 配置下调大 `max-sub-compactions` 的值。 - -#### `TiKV_raft_log_lag` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_log_lag_bucket[1m])) by (le, instance)) > 5000` - -* 规则描述： - - 这个值偏大，表明 Follower 已经远远落后于 Leader，Raft 没法正常同步了。可能的原因是 Follower 所在的 TiKV 卡住或者挂掉了。 - -#### `TiKV_async_request_snapshot_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="snapshot"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raftstore 负载压力很大，可能已经卡住。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_async_request_write_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="write"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raft write 耗时很长。 - -* 处理方法： - - 1. 检查 Raftstore 上的压力，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 检查 apply worker 线程的压力。 - -#### `TiKV_coprocessor_request_wait_seconds` - -* 报警规则： - - `histogram_quantile(0.9999, sum(rate(tikv_coprocessor_request_wait_seconds_bucket[1m])) by (le, instance, req)) > 10` - -* 规则描述： - - 这个值偏大，表明 Coprocessor worker 压力很大。可能有比较慢的任务卡住了 Coprocessor 线程。 - -* 处理方法： - - 1. 从 TiDB 日志中查看慢查询日志，看查询是否用到了索引或全表扫，或者看是否需要做 analyze。 - 2. 排查是否有热点。 - 3. 查看 Coprocessor 监控，看 `coporcessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 - -#### `TiKV_raftstore_thread_cpu_seconds_total` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"raftstore_.*"}[1m])) by (instance, name) > 1.6` - -* 规则描述： - - Raftstore 线程压力太大。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_raft_append_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_append_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 append Raft log 的耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_raft_apply_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_apply_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 apply Raft log 耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_scheduler_latch_wait_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_latch_wait_duration_seconds_bucket[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - Scheduler 中写操作获取内存锁时的等待时间。如果这个值高，表明写操作冲突较多，也可能是某些引起冲突的操作耗时较长，阻塞了其它等待相同锁的操作。 - -* 处理方法： - - 1. 查看 Scheduler-All 监控中的 scheduler command duration，看哪一个命令耗时最大。 - 2. 查看 Scheduler-All 监控中的 scheduler scan details，看 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描，另外观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 - 3. 查看 Storage 监控中的 storage async snapshot/write duration，看是否 Raft 操作不及时。 - -#### `TiKV_thread_apply_worker_cpu_seconds` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name="apply_worker"}[1m])) by (instance) > 1.8` - -* 规则描述： - - Apply Raft log 线程压力太大，通常是因为写入太猛了。 - -#### `TiDB_tikvclient_gc_action_fail`（基本不发生，只在特殊配置下才会发生） - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="fail”}[1m])) > 10` - - > **注意：** - > - > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 - -* 规则描述： - - GC 失败的 Region 较多。 - -* 处理方法： - - 1. 一般是因为并行 GC 开的太高了，可以适当降低 GC 并行度。你需要先确认 GC 失败是由于服务器繁忙导致的。 - 2. 通过执行 `update set VARIABLE_VALUE=”{number}” where VARIABLE_NAME=”tikv_gc_concurrency”` 适当降低并行度。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiKV_leader_drops` - -* 报警规则： - - `delta(tikv_pd_heartbeat_tick_total{type="leader"}[30s]) < -10` - -* 规则描述： - - 该问题通常是因为 Raftstore 线程卡住了。 - -* 处理方法： - - 1. 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 如果 TiKV 压力很小，考虑 PD 的调度是否太频繁。可以查看 PD 页面的 Operator Create 面板，排查 PD 产生调度的类型和数量。 - -#### `TiKV_raft_process_ready_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type='ready'}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft ready 的耗时。这个值大，通常是因为 append log 任务卡住了。 - -#### `TiKV_raft_process_tick_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type=’tick’}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft tick 的耗时，这个值大，通常是因为 Region 太多导致的。 - -* 处理方法： - - 1. 考虑使用更高等级的日志，比如 `warn` 或者 `error`。 - 2. 在 `[raftstore]` 配置下添加 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_scheduler_context_total` - -* 报警规则： - - `abs(delta( tikv_scheduler_context_total[5m])) > 1000` - -* 规则描述： - - Scheduler 正在执行的写命令数量。这个值高，表示任务完成得不及时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_scheduler_command_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_command_duration_seconds_bucket[1m])) by (le, instance, type) / 1000) > 1` - -* 规则描述： - - 表明 Scheduler 执行命令的耗时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_coprocessor_outdated_request_wait_seconds` - -* 报警规则： - - `delta(tikv_coprocessor_outdated_request_wait_seconds_count[10m]) > 0` - -* 规则描述： - - Coprocessor 已经过期的请求等待的时间。这个值高，表示 Coprocessor 压力已经非常大了。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_coprocessor_request_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason!="lock"}[10m]) > 100` - -* 规则描述： - - Coprocessor 的请求错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”和“full”等。“outdated”表示请求超时，很可能是由于排队时间过久，或者单个请求的耗时比较长。“full”表示 Coprocessor 的请求队列已经满了，可能是正在执行的请求比较耗时，导致新来的请求都在排队。耗时比较长的查询需要查看下对应的执行计划是否正确。 - -#### `TiKV_coprocessor_request_lock_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason="lock"}[10m]) > 10000` - -* 规则描述： - - Coprocessor 请求锁的错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”、“full”等。“lock”表示读到的数据正在写入，需要等待一会再读（TiDB 内部会自动重试）。少量这种错误不用关注，如果有大量这种错误，需要查看写入和查询是否有冲突。 - -#### `TiKV_coprocessor_pending_request` - -* 报警规则： - - `delta(tikv_coprocessor_pending_request[10m]) > 5000` - -* 规则描述： - - Coprocessor 排队的请求。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_batch_request_snapshot_nums` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"cop_.*"}[1m])) by (instance) / (count(tikv_thread_cpu_seconds_total{name=~"cop_.*"}) * 0.9) / count(count(tikv_thread_cpu_seconds_total) by (instance)) > 0` - -* 规则描述： - - 某个 TiKV 的 Coprocessor CPU 使用率超过了 90%。 - -#### `TiKV_pending_task` - -* 报警规则： - - `sum(tikv_worker_pending_task_total) BY (instance,name) > 1000` - -* 规则描述： - - TiKV 等待的任务数量。 - -* 处理方法： - - 查看是哪一类任务的值偏高，通常 Coprocessor、apply worker 这类任务都可以在其他指标里找到解决办法。 - -#### `TiKV_low_space_and_add_region` - -* 报警规则： - - `count((sum(tikv_store_size_bytes{type="available"}) by (instance) / sum(tikv_store_size_bytes{type="capacity"}) by (instance) < 0.2) and (sum(tikv_raftstore_snapshot_traffic_total{type="applying"}) by (instance) > 0)) > 0` - -#### `TiKV_approximate_region_size` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_region_size_bucket[1m])) by (le)) > 1073741824` - -* 规则描述： - - TiKV split checker 扫描到的最大的 Region approximate size 在 1 分钟内持续大于 1 GB。 - -* 处理方法： - - Region 分裂的速度不及写入的速度。为缓解这种情况，建议更新到支持 batch-split 的版本 (>= 2.1.0-rc1)。如暂时无法更新，可以使用 `pd-ctl operator add split-region --policy=approximate` 手动分裂 Region。 - -## TiDB Binlog 报警规则 - -关于 TiDB Binlog 报警规则的详细描述，参见 [TiDB Binlog 集群监控报警文档](/v3.0/reference/tidb-binlog/monitor.md#监控报警规则)。 - -## Node_exporter 主机报警规则 - -本节介绍了 Node_exporter 主机的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `NODE_disk_used_more_than_80%` - -* 报警规则： - - `node_filesystem_avail{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} / node_filesystem_size{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} * 100 <= 20` - -* 规则描述： - - 机器磁盘空间使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -h` 命令，查看磁盘空间使用率，做好扩容计划。 - -#### `NODE_disk_inode_more_than_80%` - -* 报警规则： - - `node_filesystem_files_free{fstype=~"(ext.|xfs)"} / node_filesystem_files{fstype=~"(ext.|xfs)"} * 100 < 20` - -* 规则描述： - - 机器磁盘挂载目录文件系统 inode 使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -i` 命令，查看磁盘挂载目录文件系统 inode 使用率，做好扩容计划。 - -#### `NODE_disk_readonly` - -* 报警规则： - - `node_filesystem_readonly{fstype=~"(ext.|xfs)"} == 1` - -* 规则描述： - - 磁盘挂载目录文件系统只读，无法写入数据，一般是因为磁盘故障或文件系统损坏。 - -* 处理方法： - - * 登录机器创建文件测试是否正常。 - * 检查该服务器硬盘指示灯是否正常，如异常，需更换磁盘并修复该机器文件系统。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `NODE_memory_used_more_than_80%` - -* 报警规则： - - `(((node_memory_MemTotal-node_memory_MemFree-node_memory_Cached)/(node_memory_MemTotal)*100)) >= 80` - -* 规则描述： - - 机器内存使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node Exporter 页面查看该主机的 Memory 面板，检查 `Used` 是否过高，`Available` 内存是否过低。 - * 登录机器，执行 `free -m` 命令查看内存使用情况，执行 `top` 看是否有异常进程的内存使用率过高。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `NODE_node_overload` - -* 报警规则： - - `(node_load5 / count without (cpu, mode) (node_cpu{mode="system"})) > 1` - -* 规则描述： - - 机器 CPU 负载较高。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_cpu_used_more_than_80%` - -* 报警规则： - - `avg(irate(node_cpu{mode="idle"}[5m])) by(instance) * 100 <= 20` - -* 规则描述： - - 机器 CPU 使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_tcp_estab_num_more_than_50000` - -* 报警规则： - - `node_netstat_Tcp_CurrEstab > 50000` - -* 规则描述： - - 机器 `establish` 状态的 TCP 链接超过 50,000。 - -* 处理方法： - - 登录机器执行 `ss -s` 可查看当前系统 `estab` 状态的 TCP 链接数，执行 `netstat` 查看是否有异常链接。 - -#### `NODE_disk_read_latency_more_than_32ms` - -* 报警规则： - - `((rate(node_disk_read_time_ms{device=~".+"}[5m]) / rate(node_disk_reads_completed{device=~".+"}[5m])) or (irate(node_disk_read_time_ms{device=~".+"}[5m]) / irate(node_disk_reads_completed{device=~".+"}[5m]))) > 32` - -* 规则描述： - - 磁盘读延迟超过 32 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板观察磁盘的读延迟。 - * 查看 Disk IO Utilization 面板观察 IO 使用率。 - -#### `NODE_disk_write_latency_more_than_16ms` - -* 报警规则： - - `((rate(node_disk_write_time_ms{device=~".+"}[5m]) / rate(node_disk_writes_completed{device=~".+"}[5m])) or (irate(node_disk_write_time_ms{device=~".+"}[5m]) / irate(node_disk_writes_completed{device=~".+"}[5m])))> 16` - -* 规则描述： - - 机器磁盘写延迟超过 16 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板可查看磁盘的写延迟。 - * 查看 Disk IO Utilization 面板可查看 IO 使用率。 - -## Blackbox_exporter TCP、ICMP 和 HTTP 报警规则 - -本节介绍了 Blackbox_exporter TCP、ICMP 和 HTTP 的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_server_is_down` - -* 报警规则： - - `probe_success{group="tidb"} == 0` - -* 规则描述： - - TiDB 服务端口探测失败。 - -* 处理方法： - - * 检查 TiDB 服务所在机器是否宕机。 - * 检查 TiDB 进程是否存在。 - * 检查监控机与 TiDB 服务所在机器之间网络是否正常。 - -#### `Pump_server_is_down` - -* 报警规则： - - `probe_success{group="pump"} == 0` - -* 规则描述： - - Pump 服务端口探测失败。 - -* 处理方法： - - * 检查 Pump 服务所在机器是否宕机。 - * 检查 Pump 进程是否存在。 - * 检查监控机与 Pump 服务所在机器之间网络是否正常。 - -#### `Drainer_server_is_down` - -* 报警规则： - - `probe_success{group="drainer"} == 0` - -* 规则描述： - - Drainer 服务端口探测失败。 - -* 处理方法： - - * 检查 Drainer 服务所在机器是否宕机。 - * 检查 Drainer 进程是否存在。 - * 检查监控机与 Drainer 服务所在机器之间网络是否正常。 - -#### `TiKV_server_is_down` - -* 报警规则： - - `probe_success{group="tikv"} == 0` - -* 规则描述： - - TiKV 服务端口探测失败。 - -* 处理方法： - - * 检查 TiKV 服务所在机器是否宕机。 - * 检查 TiKV 进程是否存在。 - * 检查监控机与 TiKV 服务所在机器之间网络是否正常。 - -#### `PD_server_is_down` - -* 报警规则： - - `probe_success{group="pd"} == 0` - -* 规则描述： - - PD 服务端口探测失败。 - -* 处理方法： - - * 检查 PD 服务所在机器是否宕机。 - * 检查 PD 进程是否存在。 - * 检查监控机与 PD 服务所在机器之间网络是否正常。 - -#### `Node_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="node_exporter"} == 0` - -* 规则描述： - - Node_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Node_exporter 服务所在机器是否宕机。 - * 检查 Node_exporter 进程是否存在。 - * 检查监控机与 Node_exporter 服务所在机器之间网络是否正常。 - -#### `Blackbox_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="blackbox_exporter"} == 0` - -* 规则描述： - - Blackbox_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Blackbox_exporter 服务所在机器是否宕机。 - * 检查 Blackbox_exporter 进程是否存在。 - * 检查监控机与 Blackbox_exporter 服务所在机器之间网络是否正常。 - -#### `Grafana_server_is_down` - -* 报警规则： - - `probe_success{group="grafana"} == 0` - -* 规则描述： - - Grafana 服务端口探测失败。 - -* 处理方法： - - * 检查 Grafana 服务所在机器是否宕机。 - * 检查 Grafana 进程是否存在。 - * 检查监控机与 Grafana 服务所在机器之间网络是否正常。 - -#### `Pushgateway_server_is_down` - -* 报警规则： - - `probe_success{group="pushgateway"} == 0` - -* 规则描述： - - Pushgateway 服务端口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -#### `Kafka_exporter_is_down` - -* 报警规则： - - `probe_success{group="kafka_exporter"} == 0` - -* 规则描述： - - Kafka_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Kafka_exporter 服务所在机器是否宕机。 - * 检查 Kafka_exporter 进程是否存在。 - * 检查监控机与 Kafka_exporter 服务所在机器之间网络是否正常。 - -#### `Pushgateway_metrics_interface` - -* 报警规则： - - `probe_success{job="blackbox_exporter_http"} == 0` - -* 规则描述： - - Pushgateway 服务 http 接口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `BLACKER_ping_latency_more_than_1s` - -* 报警规则： - - `max_over_time(probe_duration_seconds{job=~"blackbox_exporter.*_icmp"}[1m]) > 1` - -* 规则描述： - - Ping 延迟超过 1 秒。 - -* 处理方法： - - * 在 Grafana Blackbox Exporter dashboard 上检查两个节点间的 ping 延迟是否太高。 - * 在 Grafana Blackbox Exporter dashboard 的 tcp 面板上检查是否有丢包。 diff --git a/v3.0/reference/best-practices/grafana-monitor.md b/v3.0/reference/best-practices/grafana-monitor.md deleted file mode 100644 index 9881432fca9a..000000000000 --- a/v3.0/reference/best-practices/grafana-monitor.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 使用 Grafana 监控 TiDB 的最佳实践 -summary: 了解高效利用 Grafana 监控 TiDB 的七个技巧。 -category: reference ---- - -# 使用 Grafana 监控 TiDB 的最佳实践 - -[使用 TiDB Ansible 部署 TiDB 集群](/v3.0/how-to/deploy/orchestrated/ansible.md)时，会同时部署一套 [Grafana + Prometheus 的监控平台](/v3.0/how-to/monitor/overview.md)，用于收集和展示 TiDB 集群各个组件和机器的 metric 信息。本文主要介绍使用 TiDB 监控的最佳实践，旨在帮助 TiDB 用户高效利用丰富的 metric 信息来分析 TiDB 的集群状态或进行故障诊断。 - -## 监控架构 - -Prometheus 是一个拥有多维度数据模型和灵活查询语句的时序数据库。Grafana 是一个开源的 metric 分析及可视化系统。 - -![TiDB 监控整体架构](/media/prometheus-in-tidb.png) - -从 TiDB 2.1.3 版本开始，监控采用 pull 的方式，而之前版本采用的是 push 的方式，这是一个非常好的调整，它有以下几个优点： - -- 如果 Prometheus 需要迁移，无需重启整个 TiDB 集群。调整前，因为组件要调整 push 的目标地址，迁移 Prometheus 需要重启整个集群。 -- 支持部署 2 套独立的 Grafana + Prometheus 的监控平台（非 HA），防止监控的单点。方法是使用 ansible 用不同的 ip 各执行一次部署命令。 -- 去掉了 Pushgateway 这个单点组件。 - -## 监控数据的来源与展示 - -TiDB 的 3 个核心组件（TiDB server、TiKV server 和 PD server）可以通过 HTTP 接口来获取 metric 数据。这些 metric 均是从程序代码中上传的，默认端口如下： - -| 组件 | 端口 | -|:------------|:-------| -| TiDB server | 10080 | -| TiKV server | 20181 | -| PD server | 2379 | - -下面以 TiDB server 为例，展示如何通过 HTTP 接口查看一个语句的 QPS 数据： - -{{< copyable "shell-regular" >}} - -```bash -curl http://__tidb_ip__:10080/metrics |grep tidb_executor_statement_total -``` - -``` -# 可以看到实时 QPS 数据，并根据不同 type 对 SQL 语句进行了区分，value 是 counter 类型的累计值（科学计数法）。 -tidb_executor_statement_total{type="Delete"} 520197 -tidb_executor_statement_total{type="Explain"} 1 -tidb_executor_statement_total{type="Insert"} 7.20799402e+08 -tidb_executor_statement_total{type="Select"} 2.64983586e+08 -tidb_executor_statement_total{type="Set"} 2.399075e+06 -tidb_executor_statement_total{type="Show"} 500531 -tidb_executor_statement_total{type="Use"} 466016 -``` - -这些数据会存储在 Prometheus 中，然后在 Grafana 上进行展示。在面板上点击鼠标右键会出现 **Edit** 按钮（或直接按 E 键），如下图所示： - -![Metrics 面板的编辑入口](/media/best-practices/metric-board-edit-entry.png) - -点击 **Edit** 按钮之后，在 Metrics 面板上可以看到利用该 metric 的 query 表达式。面板上一些细节的含义如下： - -- `rate[1m]`：表示 1 分钟的增长速率，只能用于 counter 类型的数据。 -- `sum`：表示 value 求和。 -- `by type`：表示将求和后的数据按 metric 原始值中的 type 进行分组。 -- `Legend format`：表示指标名称的格式。 -- `Resolution`：默认打点步长是 15s，Resolution 表示是否将多个样本数据合并成一个点。 - -Metrics 面板中的表达式如下： - -![Metric 面板中的表达式](/media/best-practices/metric-board-expression.jpeg) - -Prometheus 支持很多表达式与函数，更多表达式请参考 [Prometheus 官网页面](https://prometheus.io/docs/prometheus/latest/querying)。 - -## Grafana 使用技巧 - -本小节介绍高效利用 Grafana 监控分析 TiDB 指标的七个技巧。 - -### 技巧 1：查看所有维度并编辑表达式 - -在[监控数据的来源与展示](#监控数据的来源与展示)一节的示例中，数据是按照 type 进行分组的。如果你想知道是否还能按其它维度分组，并快速查看还有哪些维度，可采用以下技巧：**在 query 的表达式上只保留指标名称，不做任何计算，`Legend format` 也留空**。这样就能显示出原始的 metric 数据。比如，下图能看到有 3 个维度（`instance`、`job` 和 `type`）： - -![编辑表达式并查看所有维度](/media/best-practices/edit-expression-check-dimensions.jpg) - -然后调整表达式，在原有的 `type` 后面加上 `instance` 这个维度，在 `Legend format` 处增加 `{{instance}}`，就可以看到每个 TiDB server 上执行的不同类型 SQL 语句的 QPS 了。如下图所示： - -![给表达式增加一个 instance 维度](/media/best-practices/add-instance-dimension.jpeg) - -### 技巧 2：调整 Y 轴标尺的计算方式 - -以 Query Duration 指标为例，默认的比例尺采用 2 的对数计算，显示上会将差距缩小。为了观察到明显的变化，可以将比例尺改为线性，从下面两张图中可以看到显示上的区别，明显发现那个时刻有个 SQL 语句运行较慢。 - -当然也不是所有场景都适合用线性，比如观察 1 个月的性能趋势，用线性可能就会有很多噪点，不好观察。 - -标尺默认的比例尺为 2 的对数： - -![标尺默认的比例尺为 2 的对数](/media/best-practices/default-axes-scale.jpg) - -将标尺的比例尺调整为线性： - -![调整标尺的比例尺为线性](/media/best-practices/axes-scale-linear.jpg) - -> **建议：** -> -> 结合技巧 1，会发现这里还有一个 `sql_type` 的维度，可以立刻分析出是 `SELECT` 慢还是 `UPDATE` 慢；并且可以分析出是哪个 instance 上的语句慢。 - -### 技巧 3：调整 Y 轴基线，放大变化 - -有时已经用了线性比例尺，却还是看不出变化趋势。比如下图中，在扩容后想观察 `Store size` 的实时变化效果，但由于基数较大，观察不到微弱的变化。这时可以将 Y 轴最小值从 `0` 改为 `auto`，将上部放大。观察下面两张图的区别，可以看出数据已开始迁移了。 - -基线默认为 `0`： - -![基线默认为 0](/media/best-practices/default-y-min.jpeg) - -将基线调整为 `auto`： - -![调整基线为 auto](/media/best-practices/y-min-auto.jpg) - -### 技巧 4：标尺联动 - -在 **Settings** 面板中，有一个 **Graph Tooltip** 设置项，默认使用 **Default**。 - -![图形展示工具](/media/best-practices/graph-tooltip.jpeg) - -下面将图形展示工具分别调整为 **Shared crosshair** 和 **Shared Tooltip** 看看效果。可以看到标尺能联动展示了，方便排查问题时确认 2 个指标的关联性。 - -将图形展示工具调整为 **Shared crosshair**： - -![调整图形展示工具为 Shared crosshair](/media/best-practices/graph-tooltip-shared-crosshair.jpeg) - -将图形展示工具调整为 **Shared Tooltip**： - -![调整图形展示工具为 Shared Tooltip](/media/best-practices/graph-tooltip-shared-tooltip.jpg) - -### 技巧 5：手动输入 `ip:端口号` 查看历史信息 - -PD 的 dashboard 只展示当前 leader 的 metric 信息，而有时想看历史上 PD leader 当时的状况，但是 `instance` 下拉列表中已不存在这个成员了。此时，可以手动输入 `ip:2379` 来查看当时的数据。 - -![查看历史 metric 信息](/media/best-practices/manually-input-check-metric.jpeg) - -### 技巧 6：巧用 `Avg` 函数 - -通常默认图例中只有 `Max` 和 `Current` 函数。当指标波动较大时，可以增加 `Avg` 等其它汇总函数的图例，来看一段时间的整体趋势。 - -增加 `Avg` 等汇总函数： - -![增加 Avg 等汇总函数](/media/best-practices/add-avg-function.jpeg) - -然后查看整体趋势： - -![增加 Avg 函数查看整体趋势](/media/best-practices/add-avg-function-check-trend.jpg) - -### 技巧 7：使用 Prometheus 的 API 接口获得表达式的结果 - -Grafana 通过 Prometheus 的接口获取数据，你也可以用该接口来获取数据，这个用法还可以衍生出许多功能： - -- 自动获取集群规模、状态等信息。 -- 对表达式稍加改动给报表提供数据，如统计每天的 QPS 总量、每天的 QPS 峰值和每天的响应时间。 -- 将重要的指标进行定期健康巡检。 - -Prometheus 的 API 接口如下： - -![Prometheus 的 API 接口](/media/best-practices/prometheus-api-interface.jpg) - -{{< copyable "shell-regular" >}} - -```bash -curl -u user:pass 'http://__grafana_ip__:3000/api/datasources/proxy/1/api/v1/query_range?query=sum(tikv_engine_size_bytes%7Binstancexxxxxxxxx20181%22%7D)%20by%20(instance)&start=1565879269&end=1565882869&step=30' |python -m json.tool -``` - -``` -{ - "data": { - "result": [ - { - "metric": { - "instance": "xxxxxxxxxx:20181" - }, - "values": [ - [ - 1565879269, - "1006046235280" - ], - [ - 1565879299, - "1006057877794" - ], - [ - 1565879329, - "1006021550039" - ], - [ - 1565879359, - "1006021550039" - ], - [ - 1565882869, - "1006132630123" - ] - ] - } - ], - "resultType": "matrix" - }, - "status": "success" -} -``` - -## 总结 - -Grafana + Prometheus 监控平台是一套非常强大的组合工具，用好这套工具可以为分析节省很多时间，提高效率，更重要的是，我们可以更容易发现问题。在运维 TiDB 集群，尤其是数据量大的情况下，这套工具能派上大用场。 diff --git a/v3.0/reference/best-practices/haproxy.md b/v3.0/reference/best-practices/haproxy.md deleted file mode 100644 index bac220f0a4c8..000000000000 --- a/v3.0/reference/best-practices/haproxy.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: HAProxy 在 TiDB 中的最佳实践 -category: reference ---- - -# HAProxy 在 TiDB 中的最佳实践 - -本文介绍 [HAProxy](https://github.com/haproxy/haproxy) 在 TiDB 中的最佳配置和使用方法。HAProxy 提供 TCP 协议下的负载均衡能力，TiDB 客户端通过连接 HAProxy 提供的浮动 IP 即可对数据进行操作，实现 TiDB Server 层的负载均衡。 - -![HAProxy 在 TiDB 中的最佳实践](/media/haproxy.jpg) - -## HAProxy 简介 - -HAProxy 是由 C 语言编写的自由开放源码的软件，为基于 TCP 和 HTTP 协议的应用程序提供高可用性、负载均衡和代理服务。因为 HAProxy 能够快速、高效使用 CPU 和内存，所以目前使用非常广泛，许多知名网站诸如 GitHub、Bitbucket、Stack Overflow、Reddit、Tumblr、Twitter 和 Tuenti 以及亚马逊网络服务系统都在使用 HAProxy。 - -HAProxy 由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。最新的稳定版本 2.0.0 于 2019 年 8 月 16 日发布，带来更多[优秀的特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 - -## HAProxy 部分核心功能介绍 - -- [高可用性](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.4)：HAProxy 提供优雅关闭服务和无缝切换的高可用功能； -- [负载均衡](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#4.2-balance)：L4 (TCP) 和 L7 (HTTP) 两种负载均衡模式，至少 9 类均衡算法，比如 roundrobin，leastconn，random 等； -- [健康检查](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#5.2-check)：对 HAProxy 配置的 HTTP 或者 TCP 模式状态进行检查； -- [会话保持](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.6)：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能； -- [SSL](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.2)：支持 HTTPS 通信和解析； -- [监控与统计](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.3)：通过 web 页面可以实时监控服务状态以及具体的流量信息。 - -## 准备环境 - -在部署 HAProxy 之前，需准备好以下环境。 - -### 硬件要求 - -根据官方文档，对 HAProxy 的服务器硬件配置有以下建议，也可以根据负载均衡环境进行推算，在此基础上提高服务器配置。 - -|硬件资源|最低配置| -|:---|:---| -|CPU|2 核，3.5 GHz| -|内存|16 GB| -|存储容量|50 GB（SATA 盘）| -|网卡|万兆网卡| - -### 依赖软件 - -根据官方文档，对操作系统和依赖包有以下建议，如果通过 yum 源部署安装 HAProxy 软件，依赖包无需单独安装。 - -#### 操作系统 - -| 操作系统版本 | 架构 | -|:-------------------------|:------------------------------------------| -| Linux 2.4 | x86、x86_64、Alpha、SPARC、MIPS 和 PA-RISC | -| Linux 2.6 或 3.x | x86、x86_64、ARM、SPARC 和 PPC64 | -| Solaris 8 或 9 | UltraSPARC II 和 UltraSPARC III | -| Solaris 10 | Opteron 和 UltraSPARC | -| FreeBSD 4.10 ~ 10 | x86 | -| OpenBSD 3.1 及以上版本 | i386、AMD64、macppc、Alpha 和 SPARC64 | -| AIX 5.1 ~ 5.3 | Power™ | - -#### 依赖包 - -- epel-release -- gcc -- systemd-devel - -执行如下命令安装依赖包： - -{{< copyable "shell-regular" >}} - -```bash -yum -y install epel-release gcc systemd-devel -``` - -## 部署 HAProxy - -HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具有普遍性，不具有特殊性，建议根据实际场景，个性化配置相关的[配置文件](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html)。 - -### 安装 HAProxy - -1. 使用 yum 安装 HAProxy： - - {{< copyable "shell-regular" >}} - - ```bash - yum -y install haproxy - ``` - -2. 验证 HAProxy 安装是否成功： - - {{< copyable "shell-regular" >}} - - ```bash - which haproxy - ``` - - ``` - /usr/sbin/haproxy - ``` - -#### HAProxy 命令介绍 - -执行如下命令查看命令行参数及基本用法： - -{{< copyable "shell-regular" >}} - -```bash -haproxy --help -``` - -| 参数 | 说明 | -| :------- | :--------- | -| `-v` | 显示简略的版本信息。 | -| `-vv` | 显示详细的版本信息。 | -| `-d` | 开启 debug 模式。 | -| `-db` | 禁用后台模式和多进程模式。 | -| `-dM []` | 执行分配内存。| -| `-V` | 启动过程显示配置和轮询信息。 | -| `-D` | 开启守护进程模式。 | -| `-C ` | 在加载配置文件之前更改目录位置至 \。 | -| `-W` | 主从模式。 | -| `-q` | 静默模式，不输出信息。 | -| `-c` | 只检查配置文件并在尝试绑定之前退出。 | -| `-n ` | 设置每个进程的最大总连接数为 \。 | -| `-m ` | 设置所有进程的最大可用内存为 \（单位：MB）。 | -| `-N ` | 设置单点最大连接数为 \，默认为 2000。 | -| `-L ` | 将本地实例对等名称改为 \，默认为本地主机名。 | -| `-p ` | 将 HAProxy 所有子进程的 PID 信息写入 \。 | -| `-de` | 禁止使用 epoll(7)，epoll(7) 仅在 Linux 2.6 和某些定制的 Linux 2.4 系统上可用。 | -| `-dp` | 禁止使用 epoll(2)，可改用 select(2)。 | -| `-dS` | 禁止使用 splice(2)，splice(2) 在一些旧版 Linux 内核上不可用。 | -| `-dR` | 禁止使用 SO_REUSEPORT。 | -| `-dr` | 忽略服务器地址解析失败。 | -| `-dV` | 禁止在服务器端使用 SSL。 | -| `-sf ` | 启动后，向 pidlist 中的 PID 发送 `finish` 信号，收到此信号的进程在退出之前将等待所有会话完成，即优雅停止服务。此选项必须最后指定，后跟任意数量的 PID。从技术上讲，SIGTTOU 和 SIGUSR1 都被发送。 | -| `-st ` | 启动后，向 pidlist 中的 PID 发送 `terminate` 信号，收到此信号的进程将立即终止，关闭所有活动会话。此选项必须最后指定，后跟任意数量的 PID。从技术上讲，SIGTTOU 和 SIGTERM 都被发送。 | -| `-x ` | 连接指定的 socket 并从旧进程中获取所有 listening socket，然后，使用这些 socket 而不是绑定新的。 | -| `-S [,...]` | 主从模式下，创建绑定到主进程的 socket，此 socket 可访问每个子进程的 socket。 | - -更多有关 HAProxy 命令参数的信息，可参阅 [Management Guide of HAProxy](http://cbonte.github.io/haproxy-dconv/1.9/management.html) 和 [General Commands Manual of HAProxy](https://manpages.debian.org/buster-backports/haproxy/haproxy.1.en.html)。 - -### 配置 HAProxy - -yum 安装过程中会生成配置模版，你也可以根据实际场景自定义配置如下配置项。 - -```yaml -global # 全局配置。 - log 127.0.0.1 local2 # 定义全局的 syslog 服务器，最多可以定义两个。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 40 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - stats socket /var/lib/haproxy/stats # 统计信息保存位置。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen admin_stats # frontend 和 backend 的组合体，此监控组的名称可按需进行自定义。 - bind 0.0.0.0:8080 # 监听端口。 - mode http # 监控运行的模式，此处为 `http` 模式。 - option httplog # 开始启用记录 HTTP 请求的日志功能。 - maxconn 10 # 最大并发连接数。 - stats refresh 30s # 每隔 30 秒自动刷新监控页面。 - stats uri /haproxy # 监控页面的 URL。 - stats realm HAProxy # 监控页面的提示信息。 - stats auth admin:pingcap123 # 监控页面的用户和密码，可设置多个用户名。 - stats hide-version # 隐藏监控页面上的 HAProxy 版本信息。 - stats admin if TRUE # 手工启用或禁用后端服务器（HAProxy 1.4.9 及之后版本开始支持）。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 - server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 -``` - -### 启动 HAProxy - -- 方法一：执行 `haproxy`，默认读取 `/etc/haproxy/haproxy.cfg`（推荐）。 - - {{< copyable "shell-regular" >}} - - ```bash - haproxy -f /etc/haproxy/haproxy.cfg - ``` - -- 方法二：使用 `systemd` 启动 HAProxy。 - - {{< copyable "shell-regular" >}} - - ```bash - systemctl start haproxy.service - ``` - -### 停止 HAProxy - -- 方法一：使用 `kill -9`。 - - 1. 执行如下命令： - - {{< copyable "shell-regular" >}} - - ```bash - ps -ef | grep haproxy - ``` - - 2. 终止 HAProxy 相关的 PID 进程： - - {{< copyable "shell-regular" >}} - - ```bash - kill -9 ${haproxy.pid} - ``` - -- 方法二：使用 `systemd`。 - - {{< copyable "shell-regular" >}} - - ```bash - systemctl stop haproxy.service - ``` diff --git a/v3.0/reference/best-practices/high-concurrency.md b/v3.0/reference/best-practices/high-concurrency.md deleted file mode 100644 index fc2f5e946014..000000000000 --- a/v3.0/reference/best-practices/high-concurrency.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: TiDB 高并发写入场景最佳实践 -summary: 了解 TiDB 在高并发写入场景下的最佳实践。 -category: reference ---- - -# TiDB 高并发写入场景最佳实践 - -在 TiDB 的使用过程中，一个典型场景是高并发批量写入数据到 TiDB。本文阐述了该场景中的常见问题，旨在给出一个业务的最佳实践，帮助读者避免因使用 TiDB 不当而影响业务开发。 - -## 目标读者 - -本文假设你已对 TiDB 有一定的了解，推荐先阅读 TiDB 原理相关的三篇文章（[讲存储](https://pingcap.com/blog-cn/tidb-internal-1/)，[说计算](https://pingcap.com/blog-cn/tidb-internal-2/)，[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)），以及 [TiDB Best Practice](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -## 高并发批量插入场景 - -高并发批量插入的场景通常出现在业务系统的批量任务中，例如清算以及结算等业务。此类场景存在以下特点： - -- 数据量大 -- 需要短时间内将历史数据入库 -- 需要短时间内读取大量数据 - -这就对 TiDB 提出了以下挑战： - -- 写入/读取能力是否可以线性水平扩展 -- 随着数据持续大并发写入，数据库性能是否稳定不衰减 - -对于分布式数据库来说，除了本身的基础性能外，最重要的就是充分利用所有节点能力，避免让单个节点成为瓶颈。 - -## TiDB 数据分布原理 - -如果要解决以上挑战，需要从 TiDB 数据切分以及调度的原理开始讲起。这里只作简单说明，详情可参阅[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)。 - -TiDB 以 Region 为单位对数据进行切分，每个 Region 有大小限制（默认 96M）。Region 的切分方式是范围切分。每个 Region 会有多副本，每一组副本，称为一个 Raft Group。每个 Raft Group 中由 Leader 负责执行这块数据的读 & 写（TiDB 即将支持 [Follower-Read](https://zhuanlan.zhihu.com/p/78164196)）。Leader 会自动地被 PD 组件均匀调度在不同的物理节点上，用以均分读写压力。 - -![TiDB 数据概览](/media/best-practices/tidb-data-overview.png) - -只要业务的写入没有 `AUTO_INCREMENT` 的主键，或没有单调递增的索引（即没有业务上的写入热点，更多细节可参阅 [TiDB 正确使用方式](https://zhuanlan.zhihu.com/p/25574778)），从原理上来说，TiDB 依靠这个架构可具备线性扩展的读写能力，并且可以充分利用分布式资源。从这一点看，TiDB 尤其适合高并发批量写入场景的业务。 - -但理论场景和实际情况往往存在不同。以下实例说明了热点是如何产生的。 - -## 热点产生的实例 - -以下为一张示例表： - -```sql -CREATE TABLE IF NOT EXISTS TEST_HOTSPOT( - id BIGINT PRIMARY KEY, - age INT, - user_name VARCHAR(32), - email VARCHAR(128) -) -``` - -这个表的结构非常简单，除了 `id` 为主键以外，没有额外的二级索引。将数据写入该表的语句如下，`id` 通过随机数离散生成： - -{{< copyable "sql" >}} - -```sql -INSERT INTO TEST_HOTSPOT(id, age, user_name, email) values(%v, %v, '%v', '%v'); -``` - -负载是短时间内密集地执行以上写入语句。 - -以上操作看似符合理论场景中的 TiDB 最佳实践，业务上没有热点产生。只要有足够的机器，就可以充分利用 TiDB 的分布式能力。要验证是否真的符合最佳实践，可以在实验环境中进行测试。 - -部署拓扑 2 个 TiDB 节点，3 个 PD 节点，6 个 TiKV 节点。请忽略 QPS，因为测试只是为了阐述原理，并非 benchmark。 - -![QPS1](/media/best-practices/QPS1.png) - -客户端在短时间内发起了“密集”的写入，TiDB 收到的请求是 3K QPS。理论上，压力应该均摊给 6 个 TiKV 节点。但是从 TiKV 节点的 CPU 使用情况上看，存在明显的写入倾斜（tikv - 3 节点是写入热点）： - -![QPS2](/media/best-practices/QPS2.png) - -![QPS3](/media/best-practices/QPS3.png) - -[Raft store CPU](/v3.0/reference/key-monitoring-metrics/tikv-dashboard.md) 为 `raftstore` 线程的 CPU 使用率，通常代表写入的负载。在这个场景下 tikv-3 为 Raft Leader，tikv-0 和 tikv-1 是 Raft 的 Follower，其他的 TiKV 节点的负载几乎为空。 - -从 PD 的监控中也可以证明热点的产生： - -![QPS4](/media/best-practices/QPS4.png) - -## 热点问题产生的原因 - -以上测试并未达到理论场景中最佳实践，因为刚创建表的时候，这个表在 TiKV 中只会对应为一个 Region，范围是： - -``` -[CommonPrefix + TableID, CommonPrefix + TableID + 1) -``` - -短时间内大量数据会持续写入到同一个 Region 上。 - -![TiKV Region 分裂流程](/media/best-practices/tikv-Region-split.png) - -上图简单描述了这个过程，随着数据持续写入，TiKV 会将一个 Region 切分为多个。但因为首先发起选举的是原 Leader 所在的 Store，所以新切分好的两个 Region 的 Leader 很可能还会在原 Store 上。新切分好的 Region 2，3 上，也会重复之前发生在 Region 1 上的过程。也就是压力会密集地集中在 TiKV-Node 1 上。 - -在持续写入的过程中，PD 发现 Node 1 中产生了热点，会将 Leader 均分到其他的 Node 上。如果 TiKV 的节点数多于副本数的话，TiKV 会尽可能将 Region 迁移到空闲的节点上。这两个操作在数据插入的过程中，也能在 PD 监控中得到印证： - -![QPS5](/media/best-practices/QPS5.png) - -在持续写入一段时间后，整个集群会被 PD 自动地调度成一个压力均匀的状态，到那个时候整个集群的能力才会真正被利用起来。在大多数情况下，以上热点产生的过程是没有问题的，这个阶段属于表 Region 的预热阶段。 - -但是对于高并发批量密集写入场景来说，应该避免这个阶段。 - -## 热点问题的规避方法 - -为了达到场景理论中的最佳性能，可以跳过这个预热阶段，直接将 Region 切分为预期的数量，提前调度到集群的各个节点中。 - -TiDB 在 v3.0.x 以及 v2.1.13 后支持一个叫 [Split Region](/v3.0/reference/sql/statements/split-region.md) 的新特性。这个特性提供了新的语法： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] -``` - -但是 TiDB 并不会自动提前完成这个切分操作。原因如下： - -![Table Region Range](/media/best-practices/table-Region-range.png) - -从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 - -如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 - -作为一款通用数据库，TiDB 并不对数据的分布作假设，所以开始只用一个 Region 来对应一个表。等到真实数据插入进来以后，TiDB 自动根据数据的分布来作切分。这种方式是较通用的。 - -所以 TiDB 提供了 Split Region 语法，专门针对短时批量写入场景作优化。基于以上案例，下面尝试用 Split Region 语法提前切散 Region，再观察负载情况。 - -由于测试的写入数据在正数范围内完全离散，所以用以下语句，在 Int64 空间内提前将表切分为 128 个 Region： - -{{< copyable "sql" >}} - -``` -SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; -``` - -切分完成以后，可以通过 `SHOW TABLE test_hotspot REGIONS;` 语句查看打散的情况。如果 `SCATTERING` 列值全部为 `0`，代表调度成功。 - -也可以通过 [table-regions.py](https://github.com/pingcap/tidb-ansible/blob/dabf60baba5e740a4bee9faf95e77563d8084be1/scripts/table-regions.py) 脚本，查看 Region 的分布。目前分布已经比较均匀了： - -``` -[root@172.16.4.4 scripts]# python table-regions.py --host 172.16.4.3 --port 31453 test test_hotspot -[RECORD - test.test_hotspot] - Leaders Distribution: - total leader count: 127 - store: 1, num_leaders: 21, percentage: 16.54% - store: 4, num_leaders: 20, percentage: 15.75% - store: 6, num_leaders: 21, percentage: 16.54% - store: 46, num_leaders: 21, percentage: 16.54% - store: 82, num_leaders: 23, percentage: 18.11% - store: 62, num_leaders: 21, percentage: 16.54% -``` - -再重新运行写入负载： - -![QPS6](/media/best-practices/QPS6.png) - -![QPS7](/media/best-practices/QPS7.png) - -![QPS8](/media/best-practices/QPS8.png) - -可以看到已经消除了明显的热点问题了。 - -本示例仅为一个简单的表，还有索引热点的问题需要考虑。读者可参阅 [Split Region](/v3.0/reference/sql/statements/split-region.md) 文档来了解如何预先切散索引相关的 Region。 - -### 更复杂的热点问题 - -如果表没有主键或者主键不是 Int 类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 - -要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/v3.0/reference/sql/statements/split-region.md#pre_split_regions)）。 - -`SHARD_ROW_ID_BITS` 用于将 `_tidb_rowid` 列生成的行 ID 随机打散。`pre_split_regions` 用于在建完表后预先进行 Split region。 - -> **注意：** -> -> `pre_split_regions` 必须小于或等于 `shard_row_id_bits`。 - -示例： - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; -``` - -- `SHARD_ROW_ID_BITS = 4` 表示 tidb_rowid 的值会随机分布成 16 （16=2^4） 个范围区间。 -- `pre_split_regions=3` 表示建完表后提前切分出 8 (2^3) 个 Region。 - -开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 - -## 参数配置 - -TiDB 2.1 版本中在 SQL 层引入了 [latch 机制](/v3.0/reference/configuration/tidb-server/configuration-file.md#txn-local-latches)，用于在写入冲突比较频繁的场景中提前发现事务冲突，减少 TiDB 和 TiKV 事务提交时写写冲突导致的重试。通常，跑批场景使用的是存量数据，所以并不存在事务的写入冲突。可以把 TiDB 的 latch 功能关闭，以减少为细小对象分配内存： - -``` -[txn-local-latches] -enabled = false -``` diff --git a/v3.0/reference/best-practices/java-app.md b/v3.0/reference/best-practices/java-app.md deleted file mode 100644 index fc1d75d0eb16..000000000000 --- a/v3.0/reference/best-practices/java-app.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: 开发 Java 应用使用 TiDB 的最佳实践 -category: reference -aliases: ['/docs-cn/v3.0/reference/best-practices/using-tidb-in-java/'] ---- - -# 开发 Java 应用使用 TiDB 的最佳实践 - -本文主要介绍如何开发 Java 应用程序以更好地使用 TiDB，包括开发中的常见问题与最佳实践。 - -## Java 应用中的数据库相关组件 - -通常 Java 应用中和数据库相关的常用组件有： - -- 网络协议：客户端通过标准 [MySQL 协议](https://dev.mysql.com/doc/internals/en/client-server-protocol.html)和 TiDB 进行网络交互。 -- JDBC API 及实现：Java 应用通常使用 [JDBC (Java Database Connectivity)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) 来访问数据库。JDBC 定义了访问数据库 API，而 JDBC 实现完成标准 API 到 MySQL 协议的转换，常见的 JDBC 实现是 [MySQL Connector/J](https://github.com/mysql/mysql-connector-j)，此外有些用户可能使用 [MariaDB Connector/J](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#about-mariadb-connectorj)。 -- 数据库连接池：为了避免每次创建连接，通常应用会选择使用数据库连接池来复用连接，JDBC [DataSource](https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html) 定义了连接池 API，开发者可根据实际需求选择使用某种开源连接池实现。 -- 数据访问框架：应用通常选择通过数据访问框架 ([MyBatis](http://www.mybatis.org/mybatis-3/zh/index.html), [Hibernate](https://hibernate.org/)) 的封装来进一步简化和管理数据库访问操作。 -- 业务实现：业务逻辑控制着何时发送和发送什么指令到数据库，其中有些业务会使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 切面来控制管理事务的开始和提交逻辑。 - -![Java Component](/media/java-practice-1.png) - -如上图所示，应用可能使用 Spring Transaction 来管理控制事务非手工启停，通过类似 MyBatis 的数据访问框架管理生成和执行 SQL，通过连接池获取已池化的长连接，最后通过 JDBC 接口调用实现通过 MySQL 协议和 TiDB 完成交互。 - -接下来将分别介绍使用各个组件时可能需要关注的问题。 - -## JDBC - -Java 应用尽管可以选择在不同的框架中封装，但在最底层一般会通过调用 JDBC 来与数据库服务器进行交互。对于 JDBC，需要关注的主要有：API 的使用选择和 API Implementer 的参数配置。 - -### JDBC API - -对于基本的 JDBC API 使用可以参考 [JDBC 官方教程](https://docs.oracle.com/javase/tutorial/jdbc/)，本文主要强调几个比较重要的 API 选择。 - -#### 使用 Prepare API - -对于 OLTP 场景，程序发送给数据库的 SQL 语句在去除参数变化后都是可穷举的某几类，因此建议使用[预处理语句 (Prepared Statements)](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html) 代替普通的[文本执行](https://docs.oracle.com/javase/tutorial/jdbc/basics/processingsqlstatements.html#executing_queries)，并复用预处理语句来直接执行，从而避免 TiDB 重复解析和生成 SQL 执行计划的开销。 - -目前多数上层框架都会调用 Prepare API 进行 SQL 执行，如果直接使用 JDBC API 进行开发，注意选择使用 Prepare API。 - -另外需要注意 MySQL Connector/J 实现中默认只会做客户端的语句预处理，会将 `?` 在客户端替换后以文本形式发送到服务端，所以除了要使用 Prepare API，还需要在 JDBC 连接参数中配置 `useServerPrepStmts = true`，才能在 TiDB 服务器端进行语句预处理（下面参数配置章节有详细介绍）。 - -#### 使用 Batch 批量插入更新 - -对于批量插入更新，如果插入记录较多，可以选择使用 [addBatch/executeBatch API](https://www.tutorialspoint.com/jdbc/jdbc-batch-processing)。通过 addBatch 的方式将多条 SQL 的插入更新记录先缓存在客户端，然后在 executeBatch 时一起发送到数据库服务器。 - -> **注意：** -> -> 对于 MySQL Connector/J 实现，默认 Batch 只是将多次 addBatch 的 SQL 发送时机延迟到调用 executeBatch 的时候，但实际网络发送还是会一条条的发送，通常不会降低与数据库服务器的网络交互次数。 -> -> 如果希望 Batch 网络发送，需要在 JDBC 连接参数中配置 `rewriteBatchedStatements = true`（下面参数配置章节有详细介绍）。 - -#### 使用 StreamingResult 流式获取执行结果 - -一般情况下，为提升执行效率，JDBC 会默认提前获取查询结果并将其保存在客户端内存中。但在查询返回超大结果集的场景中，客户端会希望数据库服务器减少向客户端一次返回的记录数，等客户端在有限内存处理完一部分后再去向服务器要下一批。 - -在 JDBC 中通常有以下两种处理方式： - -- 设置 [`FetchSize` 为 `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-implementation-notes.html#ResultSet) 让客户端不缓存，客户端通过 StreamingResult 的方式从网络连接上流式读取执行结果。 -- 使用 Cursor Fetch，首先需[设置 `FetchSize`](http://makejavafaster.blogspot.com/2015/06/jdbc-fetch-size-performance.html) 为正整数，且在 JDBC URL 中配置 `useCursorFetch = true`。 - -TiDB 中同时支持两种方式，但更推荐使用第一种将 `FetchSize` 设置为 `Integer.MIN_VALUE` 的方式，比第二种功能实现更简单且执行效率更高。 - -### MySQL JDBC 参数 - -JDBC 实现通常通过 JDBC URL 参数的形式来提供实现相关的配置。这里以 MySQL 官方的 Connector/J 来介绍[参数配置](https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-configuration-properties.html)（如果使用的是 MariaDB，可以参考 [MariaDB 的类似配置](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)）。因为配置项较多，这里主要关注几个可能影响到性能的参数。 - -#### Prepare 相关参数 - -##### `useServerPrepStmts` - -默认情况下，`useServerPrepStmts` 的值为 `false`，即尽管使用了 Prepare API，也只会在客户端做 “prepare”。因此为了避免服务器重复解析的开销，如果同一条 SQL 语句需要多次使用 Prepare API，则建议设置该选项为 `true`。 - -在 TiDB 监控中可以通过 **Query Summary** > **QPS By Instance** 查看请求命令类型，如果请求中 `COM_QUERY` 被 `COM_STMT_EXECUTE` 或 `COM_STMT_PREPARE` 代替即生效。 - -##### `cachePrepStmts` - -虽然 `useServerPrepStmts = true` 能让服务端执行预处理语句，但默认情况下客户端每次执行完后会 close 预处理语句，并不会复用，这样预处理的效率甚至不如文本执行。所以建议开启 `useServerPrepStmts = true` 后同时配置 `cachePrepStmts = true`，这会让客户端缓存预处理语句。 - -在 TiDB 监控中可以通过 **Query Summary** > **QPS By Instance** 查看请求命令类型，如果类似下图，请求中 `COM_STMT_EXECUTE` 数目远远多于 `COM_STMT_PREPARE` 即生效。 - -![QPS By Instance](/media/java-practice-2.png) - -另外，通过 `useConfigs = maxPerformance` 配置会同时配置多个参数，其中也包括 `cachePrepStmts = true`。 - -##### `prepStmtCacheSqlLimit` - -在配置 `cachePrepStmts` 后还需要注意 `prepStmtCacheSqlLimit` 配置（默认为 `256`），该配置控制客户端缓存预处理语句的最大长度，超过该长度将不会被缓存。 - -在一些场景 SQL 的长度可能超过该配置，导致预处理 SQL 不能复用，建议根据应用 SQL 长度情况决定是否需要调大该值。 - -在 TiDB 监控中通过 **Query Summary** > **QPS by Instance** 查看请求命令类型，如果已经配置了 `cachePrepStmts = true`，但 `COM_STMT_PREPARE` 还是和 `COM_STMT_EXECUTE` 基本相等且有 `COM_STMT_CLOSE`，需要检查这个配置项是否设置得太小。 - -##### `prepStmtCacheSize` - -`prepStmtCacheSize` 控制缓存的预处理语句数目（默认为 `25`），如果应用需要预处理的 SQL 种类很多且希望复用预处理语句，可以调大该值。 - -和上一条类似，在监控中通过 **Query Summary** > **QPS by Instance** 查看请求中 `COM_STMT_EXECUTE` 数目是否远远多于 `COM_STMT_PREPARE` 来确认是否正常。 - -#### Batch 相关参数 - -在进行 batch 写入处理时推荐配置 `rewriteBatchedStatements = true`，在已经使用 `addBatch` 或 `executeBatch` 后默认 JDBC 还是会一条条 SQL 发送，例如： - -```java -pstmt = prepare(“insert into t (a) values(?)”); -pstmt.setInt(1, 10); -pstmt.addBatch(); -pstmt.setInt(1, 11); -pstmt.addBatch(); -pstmt.setInt(1, 12); -pstmt.executeBatch(); -``` - -虽然使用了 batch 但发送到 TiDB 语句还是单独的多条 insert： - -{{< copyable "sql" >}} - -```sql -insert into t(a) values(10); -insert into t(a) values(11); -insert into t(a) values(12); -``` - -如果设置 `rewriteBatchedStatements = true`，发送到 TiDB 的 SQL 将是： - -{{< copyable "sql" >}} - -```sql -insert into t(a) values(10),(11),(12); -``` - -需要注意的是，insert 语句的改写，只能将多个 values 后的值拼接成一整条 SQL，insert 语句如果有其他差异将无法被改写。 -例如： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10) on duplicate key update a = 10; -insert into t (a) values (11) on duplicate key update a = 11; -insert into t (a) values (12) on duplicate key update a = 12; -``` - -上述 insert 语句将无法被改写成一条语句。该例子中，如果将 SQL 改写成如下形式： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10) on duplicate key update a = values(a); -insert into t (a) values (11) on duplicate key update a = values(a); -insert into t (a) values (12) on duplicate key update a = values(a); -``` - -即可满足改写条件，最终被改写成： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10), (11), (12) on duplicate key update a = values(a); -``` - -批量更新时如果有 3 处或 3 处以上更新，则 SQL 语句会改写为 multiple-queries 的形式并发送，这样可以有效减少客户端到服务器的请求开销，但副作用是会产生较大的 SQL 语句，例如这样： - -{{< copyable "sql" >}} - -```sql -update t set a = 10 where id = 1; update t set a = 11 where id = 2; update t set a = 12 where id = 3; -``` - -另外，因为一个[客户端 bug](https://bugs.mysql.com/bug.php?id=96623)，批量更新时如果要配置 `rewriteBatchedStatements = true` 和 `useServerPrepStmts = true`，推荐同时配置 `allowMultiQueries = true` 参数来避免这个 bug。 - -#### 执行前检查参数 - -通过监控可能会发现，虽然业务只向集群进行 insert 操作，却看到有很多多余的 select 语句。通常这是因为 JDBC 发送了一些查询设置类的 SQL 语句（例如 `select @@session.transaction_read_only`）。这些 SQL 对 TiDB 无用，推荐配置 `useConfigs = maxPerformance` 来避免额外开销。 - -`useConfigs = maxPerformance` 会包含一组配置： - -```ini -cacheServerConfiguration = true -useLocalSessionState = true -elideSetAutoCommits = true -alwaysSendSetIsolation = false -enableQueryTimeouts = false -``` - -配置后查看监控，可以看到多余语句减少。 - -## 连接池 - -TiDB (MySQL) 连接建立是比较昂贵的操作（至少对于 OLTP），除了建立 TCP 连接外还需要进行连接鉴权操作，所以客户端通常会把 TiDB (MySQL) 连接保存到连接池中进行复用。 - -Java 的连接池实现很多 ([HikariCP](https://github.com/brettwooldridge/HikariCP), [tomcat-jdbc](https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html), [durid](https://github.com/alibaba/druid), [c3p0](https://www.mchange.com/projects/c3p0/), [dbcp](https://commons.apache.org/proper/commons-dbcp/))，TiDB 不会限定使用的连接池，应用可以根据业务特点自行选择连接池实现。 - -### 连接数配置 - -比较常见的是应用需要根据自身情况配置合适的连接池大小，以 HikariCP 为例： - -- `maximumPoolSize`：连接池最大连接数，配置过大会导致 TiDB 消耗资源维护无用连接，配置过小则会导致应用获取连接变慢，所以需根据应用自身特点配置合适的值，可参考[这篇文章](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)。 -- `minimumIdle`：连接池最小空闲连接数，主要用于在应用空闲时存留一些连接以应对突发请求，同样是需要根据业务情况进行配置。 - -应用在使用连接池时，需要注意连接使用完成后归还连接，推荐应用使用对应的连接池相关监控（如 `metricRegistry`），通过监控能及时定位连接池问题。 - -### 探活配置 - -连接池维护到 TiDB 的长连接，TiDB 默认不会主动关闭客户端连接（除非报错），但一般客户端到 TiDB 之间还会有 LVS 或 HAProxy 之类的网络代理，它们通常会在连接空闲一定时间后主动清理连接。除了注意代理的 idle 配置外，连接池还需要进行保活或探测连接。 - -如果常在 Java 应用中看到以下错误： - -``` -The last packet sent successfully to the server was 3600000 milliseconds ago. The driver has not received any packets from the server. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure -``` - -如果 `n milliseconds ago` 中的 `n` 如果是 0 或很小的值，则通常是执行的 SQL 导致 TiDB 异常退出引起的报错，推荐查看 TiDB stderr 日志；如果 n 是一个非常大的值（比如这里的 3600000），很可能是因为这个连接空闲太久然后被中间 proxy 关闭了，通常解决方式除了调大 proxy 的 idle 配置，还可以让连接池执行以下操作： - -- 每次使用连接前检查连接是否可用。 -- 使用单独线程定期检查连接是否可用。 -- 定期发送 test query 保活连接。 - -不同的连接池实现可能会支持其中一种或多种方式，可以查看所使用的连接池文档来寻找对应配置。 - -## 数据访问框架 - -业务应用通常会使用某种数据访问框架来简化数据库的访问。 - -### MyBatis - -[MyBatis](http://www.mybatis.org/mybatis-3/) 是目前比较流行的 Java 数据访问框架，主要用于管理 SQL 并完成结果集和 Java 对象的来回映射工作。MyBatis 和 TiDB 兼容性很好，从历史 issue 可以看出 MyBatis 很少出现问题。这里主要关注如下几个配置。 - -#### Mapper 参数 - -MyBatis 的 Mapper 中支持两种参数： - -- `select 1 from t where id = #{param1}` 会作为预处理语句，被转换为 `select 1 from t where id = ?` 进行预处理，并使用实际参数来复用执行，通过配合前面的 Prepare 连接参数能获得最佳性能。 -- `select 1 from t where id = ${param2}` 会做文本替换为 `select 1 from t where id = 1` 执行，如果这条语句被预处理为不同参数，可能会导致 TiDB 缓存大量的预处理语句，并且以这种方式执行 SQL 有注入安全风险。 - -#### 动态 SQL Batch - -[动态 SQL - foreach](http://www.mybatis.org/mybatis-3/dynamic-sql.html#foreach) - -要支持将多条 insert 语句自动重写为 `insert ... values(...), (...), ...` 的形式，除了前面所说的在 JDBC 配置 `rewriteBatchedStatements = true` 外，MyBatis 还可以使用动态 SQL 来半自动生成 batch insert。比如下面的 mapper: - -```xml - - insert into test - (id, v1, v2) - values - - ( - #{item.id}, #{item.v1}, #{item.v2} - ) - - on duplicate key update v2 = v1 + values(v1) - -``` - -会生成一个 `insert on duplicate key update` 语句，values 后面的 `(?, ?, ?)` 数目是根据传入的 list 个数决定，最终效果和使用 `rewriteBatchStatements = true` 类似，可以有效减少客户端和 TiDB 的网络交互次数，同样需要注意预处理后超过 `prepStmtCacheSqlLimit` 限制导致不缓存预处理语句的问题。 - -#### Streaming 结果 - -前面介绍了在 JDBC 中如何使用流式读取结果，除了 JDBC 相应的配置外，在 MyBatis 中如果希望读取超大结果集合也需要注意： - -- 可以通过在 mapper 配置中对单独一条 SQL 设置 `fetchSize`（见上一段代码段），效果等同于调用 JDBC `setFetchSize` -- 可以使用带 `ResultHandler` 的查询接口来避免一次获取整个结果集 -- 可以使用 `Cursor` 类来进行流式读取 - -对于使用 xml 配置映射，可以通过在映射 ` - select * from post; - -``` - -而使用代码配置映射，则可以使用 `@Options(fetchSize = Integer.MIN_VALUE)` 并返回 `Cursor` 从而让 SQL 结果能被流式读取。 - -```java -@Select("select * from post") -@Options(fetchSize = Integer.MIN_VALUE) -Cursor queryAllPost(); -``` - -### `ExecutorType` - -在 `openSession` 的时候可以选择 `ExecutorType`，MyBatis 支持三种 executor： - -- Simple：每次执行都会向 JDBC 进行预处理语句的调用（如果 JDBC 配置有开启 `cachePrepStmts`，重复的预处理语句会复用）。 -- Reuse：在 `executor` 中缓存预处理语句，这样不用 JDBC 的 `cachePrepStmts` 也能减少重复预处理语句的调用。 -- Batch：每次更新只有在 `addBatch` 到 query 或 commit 时才会调用 `executeBatch` 执行，如果 JDBC 层开启了 `rewriteBatchStatements`，则会尝试改写，没有开启则会一条条发送。 - -通常默认值是 `Simple`，需要在调用 `openSession` 时改变 `ExecutorType`。如果是 Batch 执行，会遇到事务中前面的 update 或 insert 都非常快，而在读数据或 commit 事务时比较慢的情况，这实际上是正常的，在排查慢 SQL 时需要注意。 - -## Spring Transaction - -在应用代码中业务可能会通过使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 和 AOP 切面的方式来启停事务。 - -通过在方法定义上添加 `@Transactional` 注解标记方法，AOP 将会在方法前开启事务，方法返回结果前 commit 事务。如果遇到类似业务，可以通过查找代码 `@Transactional` 来确定事务的开启和关闭时机。需要特别注意有内嵌的情况，如果发生内嵌，Spring 会根据 [Propagation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/annotation/Propagation.html) 配置使用不同的行为，因为 TiDB 未支持 savepoint，所以不支持嵌套事务。 - -## 其他 - -### 排查工具 - -在 Java 应用发生问题并且不知道业务逻辑情况下，使用 JVM 强大的排查工具会比较有用。这里简单介绍几个常用工具： - -#### jstack - -[jstack](https://docs.oracle.com/javase/7/docs/technotes/tools/share/jstack.html) 对应于 Go 中的 pprof/goroutine，可以比较方便地排查进程卡死的问题。 - -通过执行 `jstack pid`，即可输出目标进程中所有线程的线程 id 和堆栈信息。输出中默认只有 Java 堆栈，如果希望同时输出 JVM 中的 C++ 堆栈，需要加 `-m` 选项。 - -通过多次 jstack 可以方便地发现卡死问题（比如：都通过 Mybatis BatchExecutor flush 调用 update）或死锁问题（比如：测试程序都在抢占应用中某把锁导致没发送 SQL） - -另外，`top -p $PID -H` 或者 Java swiss knife 都是常用的查看线程 ID 的方法。通过 `printf "%x\n" pid` 把线程 ID 转换成 16 进制，然后去 jstack 输出结果中找对应线程的栈信息，可以定位”某个线程占用 CPU 比较高，不知道它在执行什么”的问题。 - -#### jmap & mat - -和 Go 中的 pprof/heap 不同，[jmap](https://docs.oracle.com/javase/7/docs/technotes/tools/share/jmap.html) 会将整个进程的内存快照 dump 下来（go 是分配器的采样），然后可以通过另一个工具 [mat](https://www.eclipse.org/mat/) 做分析。 - -通过 mat 可以看到进程中所有对象的关联信息和属性，还可以观察线程运行的状态。比如：我们可以通过 mat 找到当前应用中有多少 MySQL 连接对象，每个连接对象的地址和状态信息是什么。 - -需要注意 mat 默认只会处理 reachable objects，如果要排查 young gc 问题可以在 mat 配置中设置查看 unreachable objects。另外对于调查 young gc 问题（或者大量生命周期较短的对象）的内存分配，用 Java Flight Recorder 比较方便。 - -#### trace - -线上应用通常无法修改代码，又希望在 Java 中做动态插桩来定位问题，推荐使用 btrace 或 arthas trace。它们可以在不重启进程的情况下动态插入 trace 代码。 - -#### 火焰图 - -Java 应用中获取火焰图较繁琐，可参阅 [Java Flame Graphs Introduction: Fire For Everyone!](http://psy-lob-saw.blogspot.com/2017/02/flamegraphs-intro-fire-for-everyone.html) 来手动获取。 - -## 总结 - -本文从常用的和数据库交互的 Java 组件的角度，阐述了开发 Java 应用程序使用 TiDB 的常见问题与解决办法。TiDB 是高度兼容 MySQL 协议的数据库，基于 MySQL 开发的 Java 应用的最佳实践也多适用于 TiDB。 - -欢迎大家在 [ASK TUG](https://asktug.com/) 踊跃发言，和我们一起分享讨论 Java 应用使用 TiDB 的实践技巧或遇到的问题。 diff --git a/v3.0/reference/best-practices/massive-regions.md b/v3.0/reference/best-practices/massive-regions.md deleted file mode 100644 index 5d7fc2a0fe20..000000000000 --- a/v3.0/reference/best-practices/massive-regions.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 海量 Region 集群调优最佳实践 -summary: 了解海量 Region 导致性能问题的原因和优化方法。 -category: reference ---- - -# 海量 Region 集群调优最佳实践 - -在 TiDB 的架构中，所有数据以一定 key range 被切分成若干 Region 分布在多个 TiKV 实例上。随着数据的写入，一个集群中会产生上百万个甚至千万个 Region。单个 TiKV 实例上产生过多的 Region 会给集群带来较大的负担，影响整个集群的性能表现。 - -本文将介绍 TiKV 核心模块 Raftstore 的工作流程，海量 Region 导致性能问题的原因，以及优化性能的方法。 - -## Raftstore 的工作流程 - -一个 TiKV 实例上有多个 Region。Region 消息是通过 Raftstore 模块驱动 Raft 状态机来处理的。这些消息包括 Region 上读写请求的处理、Raft log 的持久化和复制、Raft 的心跳处理等。但是，Region 数量增多会影响整个集群的性能。为了解释这一点，需要先了解 TiKV 的核心模块 Raftstore 的工作流程。 - -![图 1 Raftstore 处理流程示意图](/media/best-practices/raft-process.png) - -> **注意：** -> -> 该图仅为示意，不代表代码层面的实际结构。 - -上图是 Raftstore 处理流程的示意图。如图所示，从 TiDB 发来的请求会通过 gRPC 和 storage 模块变成最终的 KV 读写消息，并被发往相应的 Region，而这些消息并不会被立即处理而是被暂存下来。Raftstore 会轮询检查每个 Region 是否有需要处理的消息。如果 Region 有需要处理的消息，那么 Raftstore 会驱动 Raft 状态机去处理这些消息，并根据这些消息所产生的状态变更去进行后续操作。例如，在有写请求时，Raft 状态机需要将日志落盘并且将日志发送给其他 Region 副本；在达到心跳间隔时，Raft 状态机需要将心跳信息发送给其他 Region 副本。 - -## 性能问题 - -从 Raftstore 处理流程示意图可以看出，需要依次处理各个 Region 的消息。那么在 Region 数量较多的情况下，Raftstore 需要花费一些时间去处理大量 Region 的心跳，从而带来一些延迟，导致某些读写请求得不到及时处理。如果读写压力较大，Raftstore 线程的 CPU 使用率容易达到瓶颈，导致延迟进一步增加，进而影响性能表现。 - -通常在有负载的情况下，如果 Raftstore 的 CPU 使用率达到了 85% 以上，即可视为达到繁忙状态且成为了瓶颈，同时 `propose wait duration` 可能会高达百毫秒级别。 - -> **注意：** -> -> + Raftstore 的 CPU 使用率是指单线程的情况。如果是多线程 Raftstore，可等比例放大使用率。 -> + 由于 Raftstore 线程中有 I/O 操作，所以 CPU 使用率不可能达到 100%。 - -### 性能监控 - -可在 Grafana 的 TiKV 面板下查看相关的监控 metrics： - -+ Thread-CPU 下的 `Raft store CPU` - - 参考值：低于 `raftstore.store-pool-size * 85%`。在 v2.1 版本中无此配置项，因此在 v2.1 中可视为 `raftstore.store-pool-size = 1`。 - - ![图 2 查看 Raftstore CPU](/media/best-practices/raft-store-cpu.png) - -+ Raft Propose 下的 `Propose wait duration` - - `Propose wait duration` 是从发送请求给 Raftstore，到 Raftstore 真正开始处理请求之间的延迟时间。如果该延迟时间较长，说明 Raftstore 比较繁忙或者处理 append log 比较耗时导致 Raftstore 不能及时处理请求。 - - 参考值：低于 50-100ms。 - - ![图 3 查看 Propose wait duration](/media/best-practices/propose-wait-duration.png) - -## 性能优化方法 - -找到性能问题的根源后，可从以下两个方向来解决性能问题： - -+ 减少单个 TiKV 实例的 Region 数 -+ 减少单个 Region 的消息数 - -### 方法一：增加 TiKV 实例 - -如果 I/O 资源和 CPU 资源都比较充足，可在单台机器上部署多个 TiKV 实例，以减少单个 TiKV 实例上的 Region 个数；或者增加 TiKV 集群的机器数。 - -### 方法二：调整 `raft-base-tick-interval` - -除了减少 Region 个数外，还可以通过减少 Region 单位时间内的消息数量来减小 Raftstore 的压力。例如，在 TiKV 配置中适当调大 `raft-base-tick-interval`： - -{{< copyable "" >}} - -``` -[raftstore] -raft-base-tick-interval = "2s" -``` - -`raft-base-tick-interval` 是 Raftstore 驱动每个 Region 的 Raft 状态机的时间间隔，也就是每隔该时长就需要向 Raft 状态机发送一个 tick 消息。增加该时间间隔，可以有效减少 Raftstore 的消息数量。 - -需要注意的是，该 tick 消息的间隔也决定了 `election timeout` 和 `heartbeat` 的间隔。示例如下： - -{{< copyable "" >}} - -``` -raft-election-timeout = raft-base-tick-interval * raft-election-timeout-ticks -raft-heartbeat-interval = raft-base-tick-interval * raft-heartbeat-ticks -``` - -如果 Region Follower 在 `raft-election-timeout` 间隔内未收到来自 Leader 的心跳，就会判断 Leader 出现故障而发起新的选举。`raft-heartbeat-interval` 是 Leader 向 Follower 发送心跳的间隔，因此调大 `raft-base-tick-interval` 可以减少单位时间内 Raft 发送的网络消息，但也会让 Raft 检测到 Leader 故障的时间更长。 - -### 方法三：提高 Raftstore 并发数 - -v3.0 版本中的 Raftstore 已经扩展为多线程，极大降低了 Raftstore 线程成为瓶颈的可能性。 - -TiKV 默认将 `raftstore.store-pool-size` 配置为 `2`。如果 Raftstore 出现瓶颈，可以根据实际情况适当调高该参数值，但不建议设置过高以免引入不必要的线程切换开销。 - -### 方法四：开启 Hibernate Region 功能 - -在实际情况中，读写请求并不会均匀分布到每个 Region 上，而是集中在少数的 Region 上。那么可以尽量减少暂时空闲的 Region 的消息数量，这也就是 Hibernate Region 的功能。无必要时可不进行 `raft-base-tick`，即不驱动空闲 Region 的 Raft 状态机，那么就不会触发这些 Region 的 Raft 产生心跳信息，极大地减小了 Raftstore 的工作负担。 - -截至 TiDB v3.0.5，Hibernate Region 仍是一个实验功能，在 [TiKV master](https://github.com/tikv/tikv/tree/master) 分支上已经默认开启。可根据实际情况和需求来开启该功能。Hibernate Region 的配置说明请参考[配置 Hibernate Region](https://github.com/tikv/tikv/blob/master/docs/reference/configuration/raftstore-config.md#hibernate-region)。 - -### 方法五：开启 `Region Merge` - -> **注意：** -> -> `Region Merge` 已在 TiDB v3.0 中默认开启。 - -开启 `Region Merge` 也能减少 Region 的个数。与 `Region Split` 相反，`Region Merge` 是通过调度把相邻的小 Region 合并的过程。在集群中删除数据或者执行 `Drop Table`/`Truncate Table` 语句后，可以将小 Region 甚至空 Region 进行合并以减少资源的消耗。 - -通过 pd-ctl 设置以下参数即可开启 `Region Merge`： - -{{< copyable "" >}} - -``` ->> pd-ctl config set max-merge-region-size 20 ->> pd-ctl config set max-merge-region-keys 200000 ->> pd-ctl config set merge-schedule-limit 8 -``` - -详情请参考[如何配置 Region Merge](https://github.com/tikv/tikv/blob/master/docs/how-to/configure/region-merge.md) 和 [PD 配置文件描述](/v3.0/reference/configuration/pd-server/configuration-file.md#schedule)。 - -同时，默认配置的 `Region Merge` 的参数设置较为保守，可以根据需求参考 [PD 调度策略最佳实践](/v3.0/reference/best-practices/pd-scheduling.md#region-merge-速度慢) 中提供的方法加快 `Region Merge` 过程的速度。 - -## 其他问题和解决方案 - -### 切换 PD Leader 的速度慢 - -PD 需要将 Region Meta 信息持久化在 etcd 上，以保证切换 PD Leader 节点后 PD 能快速继续提供 Region 路由服务。随着 Region 数量的增加，etcd 出现性能问题，使得 PD 在切换 Leader 时从 etcd 获取 Region Meta 信息的速度较慢。在百万 Region 量级时，从 etcd 获取信息的时间可能需要十几秒甚至几十秒。 - -因此在 v3.0 版本中，PD 默认开启配置项 `use-region-storage`，将 Region Meta 信息存在本地的 LevelDB 中，并通过其他机制同步 PD 节点间的信息。 - -### PD 路由信息更新不及时 - -在 TiKV 中，pd-worker 模块将 Region Meta 信息定期上报给 PD，在 TiKV 重启或者切换 Region Leader 时需要通过统计信息重新计算 Region 的 `approximate size/keys`。因此在 Region 数量较多的情况下，pd-worker 单线程可能成为瓶颈，造成任务得不到及时处理而堆积起来。因此 PD 不能及时获取某些 Region Meta 信息以致路由信息更新不及时。该问题不会影响实际的读写，但可能导致 PD 调度不准确以及 TiDB 更新 Region cache 时需要多几次 round-trip。 - -可在 TiKV Grafana 面板中查看 Task 下的 Worker pending tasks 来确定 pd-worker 是否有任务堆积。通常来说，pending tasks 应该维持在一个比较低的值。 - -![图 4 查看 pd-worker](/media/best-practices/pd-worker-metrics.png) - -目前已经在 [TiKV master](https://github.com/tikv/tikv/tree/master) 上对 pd-worker 进行了[效率优化](https://github.com/tikv/tikv/pull/5620)。[TiDB v3.0.5](https://pingcap.com/docs-cn/stable/releases/3.0.5/) 中已带上该优化。如果碰到类似问题，建议升级至 v3.0.5。 - -### Prometheus 查询 metrics 的速度慢 - -在大规模集群中，随着 TiKV 实例数的增加，Prometheus 查询 metrics 时的计算压力较大，导致 Grafana 查看 metrics 的速度较慢。v3.0 版本中设置了一些 metrics 的预计算，让这个问题有所缓解。 diff --git a/v3.0/reference/best-practices/pd-scheduling.md b/v3.0/reference/best-practices/pd-scheduling.md deleted file mode 100644 index cb5107d0cc92..000000000000 --- a/v3.0/reference/best-practices/pd-scheduling.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: PD 调度策略最佳实践 -summary: 了解 PD 调度策略的最佳实践和调优方式 -category: reference ---- - -# PD 调度策略最佳实践 - -本文将详细介绍 PD 调度系统的原理，并通过几个典型场景的分析和处理方式，分享调度策略的最佳实践和调优方式，帮助大家在使用过程中快速定位问题。本文假定你对 TiDB，TiKV 以及 PD 已经有一定的了解，相关核心概念如下： - -- [Leader/Follower/Learner](/v3.0/glossary.md#leaderfollowerlearner) -- [Operator](/v3.0/glossary.md#operator) -- [Operator Step](/v3.0/glossary.md#operator-step) -- [Pending/Down](/v3.0/glossary.md#pendingdown) -- [Region/Peer/Raft Group](/v3.0/glossary.md#regionpeerraft-group) -- [Region Split](/v3.0/glossary.md#region-split) -- [Scheduler](/v3.0/glossary.md#scheduler) -- [Store](/v3.0/glossary.md#store) - -> **注意：** -> -> 本文内容基于 TiDB 3.0 版本，更早的版本（2.x）缺少部分功能的支持，但是基本原理类似，也可以以本文作为参考。 - -## PD 调度原理 - -该部分介绍调度系统涉及到的相关原理和流程。 - -### 调度流程 - -宏观上来看，调度流程大体可划分为 3 个部分： - -1. 信息收集 - - TiKV 节点周期性地向 PD 上报 `StoreHeartbeat` 和 `RegionHeartbeat` 两种心跳消息： - - * `StoreHeartbeat` 包含 Store 的基本信息、容量、剩余空间和读写流量等数据。 - * `RegionHeartbeat` 包含 Region 的范围、副本分布、副本状态、数据量和读写流量等数据。 - - PD 梳理并转存这些信息供调度进行决策。 - -2. 生成调度 - - 不同的调度器从自身的逻辑和需求出发，考虑各种限制和约束后生成待执行的 Operator。这里所说的限制和约束包括但不限于： - - - 不往断连中、下线中、繁忙、空间不足、在大量收发 snapshot 等各种异常状态的 Store 添加副本 - - Balance 时不选择状态异常的 Region - - 不尝试把 Leader 转移给 Pending Peer - - 不尝试直接移除 Leader - - 不破坏 Region 各种副本的物理隔离 - - 不破坏 Label property 等约束 - -3. 执行调度 - - 调度执行的步骤为： - - a. Operator 先进入一个由 `OperatorController` 管理的等待队列。 - - b. `OperatorController` 会根据配置以一定的并发量从等待队列中取出 Operator 并执行。执行的过程就是依次把每个 Operator Step 下发给对应 Region 的 Leader。 - - c. 标记 Operator 为 “finish” 或 “timeout” 状态，然后从执行列表中移除。 - -### 负载均衡 - -Region 负载均衡调度主要依赖 `balance-leader` 和 `balance-region` 两个调度器。二者的调度目标是将 Region 均匀地分散在集群中的所有 Store 上，但它们各有侧重：`balance-leader` 关注 Region 的 Leader，目的是分散处理客户端请求的压力；`balance-region` 关注 Region 的各个 Peer，目的是分散存储的压力，同时避免出现爆盘等状况。 - -`balance-leader` 与 `balance-region` 有着相似的调度流程： - -1. 根据不同 Store 的对应资源量的情况分别打分。 -2. 不断从得分较高的 Store 选择 Leader 或 Peer 迁移到得分较低的 Store 上。 - -两者的分数计算上也有一定差异：`balance-leader` 比较简单，使用 Store 上所有 Leader 所对应的 Region Size 加和作为得分。因为不同节点存储容量可能不一致，计算 `balance-region` 得分会分以下三种情况： - -- 当空间富余时使用数据量计算得分（使不同节点数据量基本上均衡） -- 当空间不足时由使用剩余空间计算得分（使不同节点剩余空间基本均衡） -- 处于中间态时则同时考虑两个因素做加权和当作得分 - -此外，为了应对不同节点可能在性能等方面存在差异的问题，还可为 Store 设置负载均衡的权重。`leader-weight` 和 `region-weight` 分别用于控制 Leader 权重以及 Region 权重（默认值都为 “1”）。假如把某个 Store 的 `leader-weight` 设为 “2”，调度稳定后，则该节点的 Leader 数量约为普通节点的 2 倍；假如把某个 Store 的 `region-weight` 设为 “0.5”，那么调度稳定后该节点的 Region 数量约为其他节点的一半。 - -### 热点调度 - -热点调度对应的调度器是 `hot-region-scheduler`。在 3.0 版本中，统计热点 Region 的方式为： - -1. 根据 Store 上报的信息，统计出持续一段时间读或写流量超过一定阈值的 Region。 -2. 用与负载均衡类似的方式把这些 Region 分散开来。 - -对于写热点，热点调度会同时尝试打散热点 Region 的 Peer 和 Leader；对于读热点，由于只有 Leader 承载读压力，热点调度会尝试将热点 Region 的 Leader 打散。 - -### 集群拓扑感知 - -让 PD 感知不同节点分布的拓扑是为了通过调度使不同 Region 的各个副本尽可能分散，保证高可用和容灾。PD 会在后台不断扫描所有 Region，当发现 Region 的分布不是当前的最优化状态时，会生成调度以替换 Peer，将 Region 调整至最佳状态。 - -负责这个检查的组件叫 `replicaChecker`（跟 Scheduler 类似，但是不可关闭）。它依赖于 `location-labels` 配置项来进行调度。比如配置 `[zone,rack,host]` 定义了三层的拓扑结构：集群分为多个 zone（可用区），每个 zone 下有多个 rack（机架），每个 rack 下有多个 host（主机）。PD 在调度时首先会尝试将 Region 的 Peer 放置在不同的 zone，假如无法满足（比如配置 3 副本但总共只有 2 个 zone）则保证放置在不同的 rack；假如 rack 的数量也不足以保证隔离，那么再尝试 host 级别的隔离，以此类推。 - -### 缩容及故障恢复 - -缩容是指预备将某个 Store 下线，通过命令将该 Store 标记为 “Offline“ 状态，此时 PD 通过调度将待下线节点上的 Region 迁移至其他节点。 - -故障恢复是指当有 Store 发生故障且无法恢复时，有 Peer 分布在对应 Store 上的 Region 会产生缺少副本的状况，此时 PD 需要在其他节点上为这些 Region 补副本。 - -这两种情况的处理过程基本上是一样的。`replicaChecker` 检查到 Region 存在异常状态的 Peer后，生成调度在健康的 Store 上创建新副本替换异常的副本。 - -### Region merge - -Region merge 指的是为了避免删除数据后大量小甚至空的 Region 消耗系统资源，通过调度把相邻的小 Region 合并的过程。Region merge 由 `mergeChecker` 负责，其过程与 `replicaChecker` 类似：PD 在后台遍历，发现连续的小 Region 后发起调度。 - -## 查询调度状态 - -你可以通过观察 PD 相关的 Metrics 或使用 pd-ctl 工具等方式查看调度系统状态。更具体的信息可以参考 [PD 监控](/v3.0/reference/key-monitoring-metrics/pd-dashboard.md)和 [PD Control](/v3.0/reference/tools/pd-control.md)。 - -### Operator 状态 - -**Grafana PD/Operator** 页面展示了 Operator 的相关统计信息。其中比较重要的有： - -- Schedule Operator Create：Operator 的创建情况 -- Operator finish duration：Operator 执行耗时的情况 -- Operator Step duration：不同 Operator Step 执行耗时的情况 - -查询 Operator 的 pd-ctl 命令有： - -- `operator show`：查询当前调度生成的所有 Operator -- `operator show [admin | leader | region]`：按照类型查询 Operator - -### Balance 状态 - -**Grafana PD/Statistics - Balance** 页面展示了负载均衡的相关统计信息，其中比较重要的有： - -- Store Leader/Region score：每个 Store 的得分 -- Store Leader/Region count：每个 Store 的 Leader/Region 数量 -- Store available：每个 Store 的剩余空间 - -使用 pd-ctl 的 `store` 命令可以查询 Store 的得分、数量、剩余空间和 weight 等信息。 - -### 热点调度状态 - -**Grafana PD/Statistics - hotspot** 页面展示了热点 Region 的相关统计信息，其中比较重要的有： - -- Hot write Region’s leader/peer distribution：写热点 Region 的 Leader/Peer 分布情况 -- Hot read Region’s leader distribution：读热点 Region 的 Leader 分布情况 - -使用 pd-ctl 同样可以查询上述信息，可以使用的命令有： - -- `hot read`：查询读热点 Region 信息 -- `hot write`：查询写热点 Region 信息 -- `hot store`：按 Store 统计热点分布情况 -- `region topread [limit]`：查询当前读流量最大的 Region -- `region topwrite [limit]`：查询当前写流量最大的 Region - -### Region 健康度 - -**Grafana PD/Cluster/Region health** 面板展示了异常 Region 的相关统计信息，包括 Pending Peer、Down Peer、Offline Peer，以及副本数过多或过少的 Region。 - -通过 pd-ctl 的 `region check` 命令可以查看具体异常的 Region 列表： - -- `region check miss-peer`：缺副本的 Region -- `region check extra-peer`：多副本的 Region -- `region check down-peer`：有副本状态为 Down 的 Region -- `region check pending-peer`：有副本状态为 Pending 的 Region - -## 调度策略控制 - -使用 pd-ctl 可以从以下三个方面来调整 PD 的调度策略。更具体的信息可以参考 [PD Control](/v3.0/reference/tools/pd-control.md)。 - -### 启停调度器 - -pd-ctl 支持动态创建和删除 Scheduler，你可以通过这些操作来控制 PD 的调度行为，如： - -- `scheduler show`：显示当前系统中的 Scheduler -- `scheduler remove balance-leader-scheduler`：删除（停用）balance region 调度器 -- `scheduler add evict-leader-scheduler-1`：添加移除 Store 1 的所有 Leader 的调度器 - -### 手动添加 Operator - -PD 支持直接通过 pd-ctl 来创建或删除 Operator，如： - -- `operator add add-peer 2 5`：在 Store 5 上为 Region 2 添加 Peer -- `operator add transfer-leader 2 5`：将 Region 2 的 Leader 迁移至 Store 5 -- `operator add split-region 2`：将 Region 2 拆分为 2 个大小相当的 Region -- `operator remove 2`：取消 Region 2 当前待执行的 Operator - -### 调度参数调整 - -使用 pd-ctl 执行 `config show` 命令可以查看所有的调度参数，执行 `config set {key} {value}` 可以调整对应参数的值。常见调整如下： - -- `leader-schedule-limit`：控制 Transfer Leader 调度的并发数 -- `region-schedule-limit`：控制增删 Peer 调度的并发数 -- `disable-replace-offline-replica`：停止处理节点下线的调度 -- `disable-location-replacement`：停止处理调整 Region 隔离级别相关的调度 -- `max-snapshot-count`：每个 Store 允许的最大收发 Snapshot 的并发数 - -## 典型场景分析与处理 - -该部分通过几个典型场景及其应对方式说明 PD 调度策略的最佳实践。 - -### Leader/Region 分布不均衡 - -PD 的打分机制决定了一般情况下，不同 Store 的 Leader Count 和 Region Count 不能完全说明负载均衡状态，所以需要从 TiKV 的实际负载或者存储空间占用来判断是否有负载不均衡的状况。 - -确认 Leader/Region 分布不均衡后，首先观察不同 Store 的打分情况。 - -如果不同 Store 的打分是接近的，说明 PD 认为此时已经是均衡状态了，可能的原因有： - -- 存在热点导致负载不均衡。可以参考[热点分布不均匀](#热点分布不均匀)中的解决办法进行分析处理。 -- 存在大量空 Region 或小 Region，因此不同 Store 的 Leader 数量差别特别大，导致 Raftstore 负担过重。此时需要开启 [Region Merge](#region-merge) 并尽可能加速合并。 -- 不同 Store 的软硬件环境存在差异。可以酌情调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 -- 其他不明原因。仍可以通过调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 - -如果不同 Store 的分数差异较大，需要进一步检查 Operator 的相关 Metrics，特别关注 Operator 的生成和执行情况，这时大体上又分两种情况： - -- 生成的调度是正常的，但是调度的速度很慢。可能的原因有： - - - 调度速度受限于 limit 配置。PD 默认配置的 limit 比较保守，在不对正常业务造成显著影响的前提下，可以酌情将 `leader-schedule-limit` 或 `region-schedule-limit` 调大一些。此外， `max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 - - 系统中同时运行有其他的调度任务产生竞争，导致 balance 速度上不去。这种情况下如果 balance 调度的优先级更高，可以先停掉其他的调度或者限制其他调度的速度。例如 Region 没均衡的情况下做下线节点操作，下线的调度与 Region Balance 会抢占 `region-schedule-limit` 配额，此时你可以调小 `replica-schedule-limit` 以限制下线调度的速度，或者设置 `disable-replace-offline-replica = true` 来暂时关闭下线流程。 - - 调度执行得太慢。可以通过 **Operator step duration** 进行判断。通常不涉及到收发 Snapshot 的 Step（比如 `TransferLeader`，`RemovePeer`，`PromoteLearner` 等）的完成时间应该在毫秒级，涉及到 Snapshot 的 Step（如 `AddLearner`，`AddPeer` 等）的完成时间为数十秒。如果耗时明显过高，可能是 TiKV 压力过大或者网络等方面的瓶颈导致的，需要具体情况具体分析。 - -- 没能生成对应的 balance 调度。可能的原因有： - - - 调度器未被启用。比如对应的 Scheduler 被删除了，或者 limit 被设置为 “0”。 - - 由于其他约束无法进行调度。比如系统中有 `evict-leader-scheduler`，此时无法把 Leader 迁移至对应的 Store。再比如设置了 Label property，也会导致部分 Store 不接受 Leader。 - - 集群拓扑的限制导致无法均衡。比如 3 副本 3 数据中心的集群，由于副本隔离的限制，每个 Region 的 3 个副本都分别分布在不同的数据中心，假如这 3 个数据中心的 Store 数不一样，最后调度就会收敛在每个数据中心均衡，但是全局不均衡的状态。 - -### 节点下线速度慢 - -这个场景需要从 Operator 相关的 Metrics 入手，分析 Operator 的生成执行情况。 - -如果调度在正常生成，只是速度很慢，可能的原因有： - -- 调度速度受限于 limit 配置。可以适当调大 `replica-schedule-limit`，`max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 -- 系统中同时运行有其他的调度任务产生竞争。处理方法参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡)。 -- 下线单个节点时，由于待操作的 Region 有很大一部分（3 副本配置下约 1/3）的 Leader 都集中在下线的节点上，下线速度会受限于这个单点生成 Snapshot 的速度。你可以通过手动给该节点添加一个 `evict-leader-scheduler` 调度器迁走 Leader 来加速。 - -如果没有对应的 Operator 调度生成，可能的原因有： - -- 下线调度被关闭，或者 `replica-schedule-limit` 被设为 “0”。 -- 找不到节点来转移 Region。例如相同 Label 的替代节点可用容量都不足 20%，PD 为了避免爆盘的风险会停止调度。这种情况需要添加更多节点，或者删除一些数据释放空间。 - -### 节点上线速度慢 - -目前 PD 没有对节点上线特殊处理。节点上线实际上是依靠 balance region 机制来调度的，所以参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡) 中的排查步骤即可。 - -### 热点分布不均匀 - -热点调度的问题大体上可以分为以下几种情况： - -- 从 PD 的 Metrics 能看出来有不少 hot Region，但是调度速度跟不上，不能及时地把热点 Region 分散开来。 - - **解决方法**：调大 `hot-region-schedule-limit` 并减少其他调度器的 limit 配额，从而加快热点调度的速度。还可调小 `hot-region-cache-hits-threshold` 使 PD 对更快响应流量的变化。 - -- 单一 Region 形成热点，比如大量请求频繁 scan 一个小表，这个可以从业务角度或者 Metrics 统计的热点信息看出来。由于单 Region 热点现阶段无法使用打散的手段来消除，需要确认热点 Region 后手动添加 `split-region` 调度将这样的 Region 拆开。 - -- 从 PD 的统计来看没有热点，但是从 TiKV 的相关 Metrics 可以看出部分节点负载明显高于其他节点，成为整个系统的瓶颈。这是因为目前 PD 统计热点 Region 的维度比较单一，仅针对流量进行分析，在某些场景下无法准确定位热点。例如部分 Region 有大量的点查请求，从流量上来看并不显著，但是过高的 QPS 导致关键模块达到瓶颈。 - - **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) 文档。 - -### Region Merge 速度慢 - -Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-schedule-limit` 及 `region-schedule-limit`），或者是与其他调度器产生了竞争。具体来说，可有如下处理方式： - -- 假如已经从相关 Metrics 得知系统中有大量的空 Region，这时可以通过把 `max-merge-region-size` 和 `max-merge-region-keys` 调整为较小值来加快 Merge 速度。这是因为 Merge 的过程涉及到副本迁移，所以 Merge 的 Region 越小，速度就越快。如果生成 Merge Operator 的速度很快，想进一步加快 Region Merge 过程，还可以把 `patrol-region-interval` 调整为 "10ms" ，这个能加快巡检 Region 的速度，但是会消耗更多的 CPU 资源。 - -- 创建过大量 Table 后（包括执行 `Truncate Table` 操作）又清空了。此时如果开启了 split table 特性，这些空 Region 是无法合并的，此时需要调整以下参数关闭这个特性： - - - TiKV: `split-region-on-table` 设为 false - - PD: `namespace-classifier` 设为 “” - -- 对于 3.0.4 和 2.1.16 以前的版本，Region 中 Key 的个数（`approximate_keys`）在特定情况下（大部分发生在删表之后）统计不准确，造成 keys 的统计值很大，无法满足 `max-merge-region-keys` 的约束。你可以通过调大 `max-merge-region-keys` 来避免这个问题。 - -### TiKV 节点故障处理策略 - -没有人工介入时，PD 处理 TiKV 节点故障的默认行为是，等待半小时之后（可通过 `max-store-down-time` 配置调整），将此节点设置为 Down 状态，并开始为涉及到的 Region 补充副本。 - -实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 diff --git a/v3.0/reference/configuration/pd-server/configuration-file.md b/v3.0/reference/configuration/pd-server/configuration-file.md deleted file mode 100644 index c6ca2833fb17..000000000000 --- a/v3.0/reference/configuration/pd-server/configuration-file.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: PD 配置文件描述 -category: reference ---- - -# PD 配置文件描述 - - - -PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/config.toml](https://github.com/pingcap/pd/blob/master/conf/config.toml) 找到默认的配置文件。 - -本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [PD 配置参数](/v3.0/reference/configuration/pd-server/configuration.md)。 - -### `lease` - -+ PD Leader Key 租约超时时间，超时系统重新选举 Leader。 -+ 默认：3 -+ 单位：秒 - -### `tso-save-interval` - -+ TSO 分配的时间窗口,实时持久存储。 -+ 默认：3s - -### `initial-cluster-state` - -+ 集群初始状态 -+ 默认：new - -### `enable-prevote` - -+ 开启 raft prevote 的开关。 -+ 默认：true - -### `quota-backend-bytes` - -+ 元信息数据库存储空间的大小，默认 2GB。 -+ 默认：2147483648 - -### `auto-compaction-mod` - -+ 元信息数据库自动压缩的模式，可选项为 periodic（按周期），revision（按版本数）。 -+ 默认：periodic - -### `auto-compaction-retention` - -+ compaction-mode 为 periodic 时为元信息数据库自动压缩的间隔时间；compaction-mode 设置为 revision 时为自动压缩的版本数。 -+ 默认：1h - -### `force-new-cluster` - -+ 强制让该 PD 以一个新集群启动，且修改 raft 成员数为 1。 -+ 默认：false - -### `tick-interval` - -+ etcd raft 的 tick 周期。 -+ 默认：100ms - -### `election-interval` - -+ etcd leader 选举的超时时间。 -+ 默认：3s - -### `use-region-storage` - -+ 开启独立的 region 存储。 -+ 默认：false - -## security - -安全相关配置项。 - -### `cacert-path` - -+ CA 文件路径 -+ 默认："" - -### `cert-path` - -+ 包含 X509 证书的 PEM 文件路径 -+ 默认："" - -### `key-path` - -+ 包含 X509 key 的 PEM 文件路径 -+ 默认："" - -## log - -日志相关的配置项。 - -### `format` - -+ 日志格式，可指定为"text"，"json"， "console"。 -+ 默认：text - -### `disable-timestamp` - -+ 是否禁用日志中自动生成的时间戳。 -+ 默认：false - -## log.file - -日志文件相关的配置项。 - -### `max-size` - -+ 单个日志文件最大大小，超过该值系统自动切分成多个文件。 -+ 默认：300 -+ 单位：MiB -+ 最小值为 1 - -### `max-days` - -+ 日志保留的最长天数。 -+ 默认: 28 -+ 最小值为 1 - -### `max-backups` - -+ 日志文件保留的最大个数。 -+ 默认: 7 -+ 最小值为 1 - -## metric - -监控相关的配置项。 - -### `interval` - -+ 向 promethus 推送监控指标数据的间隔时间。 -+ 默认: 15s - -## schedule - -调度相关的配置项。 - -### `max-merge-region-size` - -+ 控制 Region Merge 的 size 上限，当 Region Size 大于指定值时 PD 不会将其与相邻的 Region 合并。 -+ 默认: 20 - -### `max-merge-region-keys` - -+ 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 -+ 默认: 200000 - -### `patrol-region-interval` - -+ 控制 replicaChecker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整 -+ 默认: 100ms - -### `split-merge-interval` - -+ 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。 -+ 默认: 1h - -### `max-snapshot-count` - -+ 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。 -+ 默认: 3 - -### `max-pending-peer-count` - -+ 控制单个 store 的 pending peer 上限，调度受制于这个配置来防止在部分节点产生大量日志落后的 Region。 -+ 默认：16 - -### `max-store-down-time` - -+ PD 认为失联 store 无法恢复的时间，当超过指定的时间没有收到 store 的心跳后，PD 会在其他节点补充副本。 -+ 默认：30m - -### `leader-schedule-limit` - -+ 同时进行 leader 调度的任务个数。 -+ 默认：4 - -### `region-schedule-limit` - -+ 同时进行 Region 调度的任务个数 -+ 默认：4 - -### `replica-schedule-limit` - -+ 同时进行 replica 调度的任务个数。 -+ 默认：8 - -### `merge-schedule-limit` - -+ 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 -+ 默认：8 - -### `high-space-ratio` - -+ 设置 store 空间充裕的阈值。 -+ 默认：0.6 -+ 最小值：大于 0 -+ 最大值：小于 1 - -### `low-space-ratio` - -+ 设置 store 空间不足的阈值。 -+ 默认：0.8 -+ 最小值：大于 0 -+ 最大值：小于 1 - -### `tolerant-size-ratio` - -+ 控制 balance 缓冲区大小。 -+ 默认：5 -+ 最小值：0 - -### `disable-remove-down-replica` - -+ 关闭自动删除 DownReplica 的特性的开关，当设置为 true 时，PD 不会自动清理宕机状态的副本。 -+ 默认：false - -### `disable-replace-offline-replica` - -+ 关闭迁移 OfflineReplica 的特性的开关，当设置为 true 时，PD 不会迁移下线状态的副本。 -+ 默认：false - -### `disable-make-up-replica` - -+ 关闭补充副本的特性的开关，当设置为 true 时，PD 不会为副本数不足的 Region 补充副本。 -+ 默认：false - -### `disable-remove-extra-replica` - -+ 关闭删除多余副本的特性开关，当设置为 true 时，PD 不会为副本数过多的 Region 删除多余副本。 -+ 默认：false - -### `disable-location-replacement` - -+ 关闭隔离级别检查的开关，当设置为 true 时，PD 不会通过调度来提升 Region 副本的隔离级别。 -+ 默认：false - -## replication - -副本相关的配置项。 - -### `max-replicas` - -+ 副本数量。 -+ 默认：3 - -### `location-labels` - -+ TiKV 集群的拓扑信息。 -+ 默认：[] - -## label-property - -标签相关的配置项。 - -### `key` - -+ 拒绝 leader 的 store 带有的 label key。 -+ 默认："" - -### `value` - -+ 拒绝 leader 的 store 带有的 label value。 -+ 默认："" diff --git a/v3.0/reference/configuration/pd-server/configuration.md b/v3.0/reference/configuration/pd-server/configuration.md deleted file mode 100644 index 70b769bc7359..000000000000 --- a/v3.0/reference/configuration/pd-server/configuration.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: PD 配置参数 -category: reference -aliases: ['/docs-cn/op-guide/pd-configuration/'] ---- - -# PD 配置参数 - -PD 可以通过命令行参数或环境变量配置。 - -## `--advertise-client-urls` - -+ 对外客户端访问 URL 列表。 -+ 默认：`${client-urls}` -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，客户端并不能通过 PD 自己监听的 client URLs 来访问到 PD，这时候，你就可以设置 advertise urls 来让客户端访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 `-p 2379:2379`，那么可以设置为 `--advertise-client-urls="http://192.168.100.113:2379"`，客户端可以通过 `http://192.168.100.113:2379` 来找到这个服务。 - -## `--advertise-peer-urls` - -+ 对外其他 PD 节点访问 URL 列表。 -+ 默认：`${peer-urls}` -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，其他节点并不能通过 PD 自己监听的 peer URLs 来访问到 PD，这时候，你就可以设置 advertise urls 来让其他节点访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 `-p 2380:2380`，那么可以设置为 `--advertise-peer-urls="http://192.168.100.113:2380"`，其他 PD 节点可以通过 `http://192.168.100.113:2380` 来找到这个服务。 - -## `--client-urls` - -+ 处理客户端请求监听 URL 列表。 -+ 默认：`http://127.0.0.1:2379` -+ 如果部署一个集群，\-\-client-urls 必须指定当前主机的 IP 地址，例如 `http://192.168.100.113:2379"`，如果是运行在 docker 则需要指定为 `http://0.0.0.0:2379`。 - -## `--peer-urls` - -+ 处理其他 PD 节点请求监听 URL 列表。 -+ default: `http://127.0.0.1:2380` -+ 如果部署一个集群，\-\-peer-urls 必须指定当前主机的 IP 地址，例如 `http://192.168.100.113:2380`，如果是运行在 docker 则需要指定为 `http://0.0.0.0:2380`。 - -## `--config` - -+ 配置文件。 -+ 默认："" -+ 如果你指定了配置文件，PD 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，PD 就会使用命令行参数的配置来覆盖配置文件里面的。 - -## `--data-dir` - -+ PD 存储数据路径。 -+ 默认：`default.${name}` - -## `--initial-cluster` - -+ 初始化 PD 集群配置。 -+ 默认：`{name}=http://{advertise-peer-url}` -+ 例如，如果 name 是 "pd", 并且 `advertise-peer-urls` 是 `http://192.168.100.113:2380`, 那么 `initial-cluster` 就是 `pd=http://192.168.100.113:2380`。 -+ 如果你需要启动三台 PD，那么 `initial-cluster` 可能就是 - `pd1=http://192.168.100.113:2380, pd2=http://192.168.100.114:2380, pd3=192.168.100.115:2380`。 - -## `--join` - -+ 动态加入 PD 集群。 -+ 默认："" -+ 如果你想动态将一台 PD 加入集群，你可以使用 `--join="${advertise-client-urls}"`， `advertise-client-url` 是当前集群里面任意 PD 的 `advertise-client-url`，你也可以使用多个 PD 的，需要用逗号分隔。 - -## `-L` - -+ Log 级别。 -+ 默认："info" -+ 我们能选择 debug, info, warn, error 或者 fatal。 - -## `--log-file` - -+ Log 文件。 -+ 默认："" -+ 如果没设置这个参数，log 会默认输出到 "stderr"，如果设置了，log 就会输出到对应的文件里面，在每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份。 - -## `--log-rotate` - -+ 是否开启日志切割。 -+ 默认：true -+ 当值为 true 时,按照 PD 配置文件中 `[log.file]` 信息执行。 - -## `--name` - -+ 当前 PD 的名字。 -+ 默认："pd" -+ 如果你需要启动多个 PD，一定要给 PD 使用不同的名字 - -## `--cacert` - -+ CA 文件路径，用于开启 TLS。 -+ 默认："" - -## `--cert` - -+ 包含 X509 证书的 PEM 文件路径，用户开启 TLS。 -+ 默认："" - -## `--key` - -+ 包含 X509 key 的 PEM 文件路径，用于开启 TLS。 -+ 默认："" - -## `--namespace-classifier` - -+ 指定 PD 使用的 namespace 分类器。 -+ 默认："table" -+ 如果 TiKV 不与 TiDB 集群配合运行，建议配置为 'default'。 - -## `--metrics-addr` - -+ 指定 Prometheus Pushgateway 的地址。 -+ 默认："" -+ 如果留空，则不开启 Prometheus Push。 - -## `--force-new-cluster` - -+ 强制使用当前节点创建新的集群。 -+ 默认：false -+ 仅用于在 PD 丢失多数副本的情况下恢复服务，可能会产生部分数据丢失。 - -## `-V`, `--version` - -+ 输出版本信息并退出。 diff --git a/v3.0/reference/configuration/tidb-server/configuration-file.md b/v3.0/reference/configuration/tidb-server/configuration-file.md deleted file mode 100644 index 30ad141cfc53..000000000000 --- a/v3.0/reference/configuration/tidb-server/configuration-file.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -title: TiDB 配置文件描述 -category: reference -aliases: ['/docs-cn/op-guide/tidb-config-file/'] ---- - - - -# TiDB 配置文件描述 - -TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/config.toml.example](https://github.com/pingcap/tidb/blob/release-3.0/config/config.toml.example) 找到默认值的配置文件，重命名为 `config.toml` 即可。本文档只介绍未包含在[命令行参数](https://pingcap.com/docs-cn/v3.0/reference/configuration/tidb-server/configuration)中的参数。 - -### `split-table` - -+ 为每个 table 建立单独的 Region。 -+ 默认值：true -+ 如果需要创建大量的表，我们建议把这个参数设置为 false。 - -### `oom-action` - -+ 指定 TiDB 发生 out-of-memory 错误时的操作。 -+ 默认值："log" -+ 现在合法的选项是 ["log", "cancel"]，如果为 "log"，仅仅是打印日志，不作实质处理。如果为 "cancel"，我们会取消执行这个操作，并且输出日志。 - -### `mem-quota-query` - -+ 单条 SQL 语句可以占用的最大内存阈值。 -+ 默认值：34359738368 -+ 超过该值的请求会被 `oom-action` 定义的行为所处理。 - -### `enable-streaming` - -+ 开启 coprocessor 的 streaming 获取数据模式。 -+ 默认值：false - -### `lower-case-table-names` - -+ 这个选项可以设置 TiDB 的系统变量 `lower_case_table_names` 的值。 -+ 默认值：2 -+ 具体可以查看 MySQL 关于这个变量的[描述](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_lower_case_table_names) - -> **注意：** -> -> 目前 TiDB 只支持将该选项的值设为 2，即按照大小写来保存表名，按照小写来比较（不区分大小写）。 - -### `lease` - -+ DDL 租约超时时间。 -+ 默认值：45s -+ 单位：秒 - -### `compatible-kill-query` - -+ 设置 `KILL` 语句的兼容性。 -+ 默认值：false -+ TiDB 中 `KILL xxx` 的行为和 MySQL 中的行为不相同。为杀死一条查询，在 TiDB 里需要加上 `TIDB` 关键词，即 `KILL TIDB xxx`。但如果把 `compatible-kill-query` 设置为 true，则不需要加上 `TIDB` 关键词。 -+ 这种区别很重要，因为当用户按下 Ctrl+C 时，MySQL 命令行客户端的默认行为是：创建与后台的新连接，并在该新连接中执行 `KILL` 语句。如果负载均衡器或代理已将该新连接发送到与原始会话不同的 TiDB 服务器实例，则该错误会话可能被终止，从而导致使用 TiDB 集群的业务中断。只有当您确定在 `KILL` 语句中引用的连接正好位于 `KILL` 语句发送到的服务器上时，才可以启用 `compatible-kill-query`。 - -### `check-mb4-value-in-utf8` - -+ 开启检查 utf8mb4 字符的开关，如果开启此功能，字符集是 utf8，且在 utf8 插入 mb4 字符，系统将会报错。 -+ 默认值：true - -### `treat-old-version-utf8-as-utf8mb4` - -+ 将旧表中的 utf8 字符集当成 utf8mb4的开关。 -+ 默认值：true - -### `alter-primary-key` - -+ 用于控制添加或者删除主键功能（在 3.0.6 及以后版本支持此配置项）。 -+ 默认值：false -+ 默认情况下，不支持增删主键。将此变量被设置为 true 后，支持增删主键功能。不过对在此开关开启前已经存在的表，且主键是整型类型时，即使之后开启此开关也不支持对此列表删除主键。 - -## log - -日志相关的配置项。 - -### `format` - -+ 指定日志输出的格式，可选项为 [json, text, console]。 -+ 默认值："text" - -### `disable-timestamp` - -+ 是否禁止在日志中输出时间戳。 -+ 默认值：false -+ 如果设置为 true，那么日志里面将不会输出时间戳。 - -### `slow-query-file` - -+ 慢查询日志的文件名。 -+ 默认值："tidb-slow.log"，注：由于 TiDB V2.1.8 更新了慢日志格式，所以将慢日志单独输出到了慢日志文件。V2.1.8 之前的版本，该变量的默认值是 ""。 -+ 设置后，慢查询日志会单独输出到该文件。 - -### `slow-threshold` - -+ 输出慢日志的耗时阈值。 -+ 默认值：300ms -+ 当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。 - -### `expensive-threshold` - -+ 输出 `expensive` 操作的行数阈值。 -+ 默认值：10000 -+ 当查询的行数（包括中间结果，基于统计信息）大于这个值，我们就会当成是一个 `expensive` 的操作，输出一个前缀带有 `[EXPENSIVE_QUERY]` 的日志。 - -### `query-log-max-len` - -+ 最长的 SQL 输出长度。 -+ 默认值：2048 -+ 当语句的长度大于 `query-log-max-len`，将会被截断输出。 - -## log.file - -日志文件相关的配置项。 - -#### `filename` - -+ 一般日志文件名字。 -+ 默认值："" -+ 如果设置，会输出一般日志到这个文件。 - -#### `max-size` - -+ 日志文件的大小限制。 -+ 默认值：300MB -+ 最大设置上限为 4GB。 - -#### `max-days` - -+ 日志最大保留的天数。 -+ 默认值：0 -+ 默认不清理；如果设置了参数值，在 `max-days` 之后 TiDB 会清理过期的日志文件。 - -#### `max-backups` - -+ 保留的日志的最大数量。 -+ 默认值：0 -+ 默认全部保存；如果设置为 7，会最多保留 7 个老的日志文件。 - -#### `log-rotate` - -+ 是否每日创建一个新的日志文件。 -+ 默认值：true -+ 如果设置为 true，每天会新建新的日志文件，如果设置为 false，那么只会输出到一个日志文件。 - -## security - -安全相关配置。 - -### `ssl-ca` - -+ PEM 格式的受信任 CA 的证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-cert`、`--ssl-key` 选项时，TiDB 将在客户端出示证书的情况下根据该选项指定的受信任的 CA 列表验证客户端证书。若验证失败，则连接会被终止。 -+ 即使设置了该选项，若客户端没有出示证书，则安全连接仍然继续，不会进行客户端证书验证。 - -### `ssl-cert` - -+ PEM 格式的 SSL 证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-key` 选项时，TiDB 将接受（但不强制）客户端使用 TLS 安全地连接到 TiDB。 -+ 若指定的证书或私钥无效，则 TiDB 会照常启动，但无法接受安全连接。 - -### `ssl-key` - -+ PEM 格式的 SSL 证书密钥文件路径，即 `--ssl-cert` 所指定的证书的私钥。 -+ 默认值："" -+ 目前 TiDB 不支持加载由密码保护的私钥。 - -### `cluster-ssl-ca` - -+ CA 根证书，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-cert` - -+ ssl 证书文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-key` - -+ ssl 私钥文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `skip-grant-table` - -+ 是否跳过权限检查 -+ 默认值：false - -## performance - -性能相关配置。 - -### `max-procs` - -+ TiDB 的 CPU 使用数量。 -+ 默认值：0 -+ 默认值为 0 表示使用机器上所有的 CPU；如果设置成 n，那么 TiDB 会使用 n 个 CPU 数量。 - -### `max-memory` - -+ Prepare cache LRU 使用的最大内存限制，超过 performance.max-memory * (1 - prepared-plan-cache.memory-guard-ratio)会 剔除 LRU 中的元素。 -+ 默认值：0 -+ 这个配置只有在 prepared-plan-cache.enabled 为 true 的情况才会生效。在 LRU 的 size 大于 prepared-plan-cache.capacity 的情况下，也会剔除 LRU 中的元素。 - -### `stmt-count-limit` - -+ TiDB 一个事务允许的最大语句条数限制。 -+ 默认值：5000 -+ 在一个事务中，超过 `stmt-count-limit` 条语句后还没有 rollback 或者 commit，TiDB 将会返回 `statement count 5001 exceeds the transaction limitation, autocommit = false` 错误。 - -### `tcp-keep-alive` - -+ TiDB 在 TCP 层开启 keepalive。 -+ 默认值：false - -### `cross-join` - -+ 默认值：true -+ 默认可以执行在做 join 时两边表没有任何条件（where 字段）的语句；如果设置为 false，则有这样的 join 语句出现时，server 会拒绝执行 - -### `stats-lease` - -+ TiDB 重载统计信息，更新表行数，检查是否需要自动 analyze，利用 feedback 更新统计信息以及加载列的统计信息的时间间隔。 -+ 默认值：3s - - 每隔 `stats-lease` 时间，TiDB 会检查统计信息是否有更新，如果有会将其更新到内存中 - - 每隔 `20 * stats-lease` 时间，TiDB 会将 DML 产生的总行数以及修改的行数变化更新到系统表中 - - 每隔 `stats-lease` 时间，TiDB 会检查是否有表或者索引需要自动 analyze - - 每隔 `stats-lease` 时间，TiDB 会检查是否有列的统计信息需要被加载到内存中 - - 每隔 `200 * stats-lease` 时间，TiDB 会将内存中缓存的 feedback 写入系统表中 - - 每隔 `5 * stats-lease` 时间，TiDB 会读取系统表中的 feedback，更新内存中缓存的统计信息 -+ 当 `stats-lease` 为 0 时，TiDB 会以 3s 的时间间隔周期性的读取系统表中的统计信息并更新内存中缓存的统计信息。但不会自动修改统计信息相关系统表，具体来说，TiDB 不再自动修改这些表： - - `mysql.stats_meta`：TiDB 不再自动记录事务中对某张表的修改行数，也不会更新到这个系统表中 - - `mysql.stats_histograms`/`mysql.stats_buckets` 和 `mysql.stats_top_n`：TiDB 不再自动 analyze 和主动更新统计信息 - - `mysql.stats_feedback`：TiDB 不再根据被查询的数据反馈的部分统计信息更新表和索引的统计信息，analyze 以及 feedback 等操作都不会再进行。 - -### `run-auto-analyze` - -+ TiDB 是否做自动的 Analyze。 -+ 默认值：true - -### `feedback-probability` - -+ TiDB 对查询收集统计信息反馈的概率。 -+ 默认值：0.05 -+ 对于每一个查询，TiDB 会以 `feedback-probability` 的概率收集查询的反馈，用于更新统计信息。 - -### `query-feedback-limit` - -+ 在内存中缓存的最大 Query Feedback 数量，超过这个数量的 Feedback 会被丢弃。 -+ 默认值：1024 - -### `pseudo-estimate-ratio` - -+ 修改过的行数/表的总行数的比值，超过该值时系统会认为统计信息已经过期，会采用 pseudo 的统计信息。 -+ 默认值：0.8 -+ 最小值为 0；最大值为 1。 - -### `force-priority` - -+ 把所有的语句优先级设置为 force-priority 的值。 -+ 默认值：NO_PRIORITY -+ 可选值：NO_PRIORITY, LOW_PRIORITY, HIGH_PRIORITY, DELAYED。 - -## prepared-plan-cache - -prepare 语句的 Plan cache 设置。 - -### `enabled` - -+ 开启 prepare 语句的 plan cache。 -+ 默认值：false - -### `capacity` - -+ 缓存语句的数量。 -+ 默认值：100 - -### `memory-guard-ratio` - -+ 用于防止超过 performance.max-memory, 超过 max-proc * (1 - prepared-plan-cache.memory-guard-ratio)会剔除 LRU 中的元素。 -+ 默认值：0.1 -+ 最小值为 0；最大值为 1。 - -## tikv-client - -### `grpc-connection-count` - -+ 跟每个 TiKV 之间建立的最大连接数。 -+ 默认值：16 - -### `grpc-keepalive-time` - -+ TiDB 与 TiKV 节点之间 rpc 连接 keepalive 时间间隔，如果超过该值没有网络包，grpc client 会 ping 一下 TiKV 查看是否存活。 -+ 默认值：10 -+ 单位：秒 - -### `grpc-keepalive-timeout` - -+ TiDB 与 TiKV 节点 rpc keepalive 检查的超时时间 -+ 默认值：3 -+ 单位：秒 - -### `commit-timeout` - -+ 执行事务提交时，最大的超时时间。 -+ 默认值：41s -+ 这个值必须是大于两倍 Raft 选举的超时时间。 - -### `max-txn-time-use` - -+ 单个事务允许的最大执行时间。 -+ 默认值：590 -+ 单位：秒 - -### `max-batch-size` - -+ 批量发送 rpc 封包的最大数量，如果不为 0，将使用 BatchCommands api 发送请求到 TiKV，可以在并发度高的情况降低 rpc 的延迟，推荐不修改该值。 -+ 默认值：128 - -### `max-batch-wait-time` - -+ 等待 `max-batch-wait-time` 纳秒批量将此期间的数据包封装成一个大包发送给 TiKV 节点，仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 -+ 默认值：0 -+ 单位：纳秒 - -### `batch-wait-size` - -+ 批量向 TiKV 发送的封包最大数量，不推荐修改该值。 -+ 默认值：8 -+ 若此值为 0 表示关闭此功能。 - -### `overload-threshold` - -+ TiKV 的负载阈值，如果超过此阈值，会收集更多的 batch 封包，来减轻 TiKV 的压力。仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 -+ 默认值：200 - -## txn-local-latches - -事务内存锁相关配置，当本地事务冲突比较多时建议开启。 - -### `enable` - -+ 开启 -+ 默认值：false - -### `capacity` - -+ Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。 -+ 默认值：2048000 - -## binlog - -TiDB Binlog 相关配置。 - -### `enable` - -+ 开启 binlog 开关。 -+ 默认值：false - -### `write-timeout` - -+ 写 binlog 的超时时间，推荐不修改该值。 -+ 默认值：15s -+ 单位：秒 - -### `ignore-error` - -+ 忽略写 binlog 发生的错误时处理开关，推荐不修改该值。 -+ 默认值：false -+ 如果设置为 `true`，发生错误时，TiDB 会停止写入 binlog，并且在监控项 `tidb_server_critical_error_total` 上计数加 1；如果设置为 `false`，写入 binlog 失败，会停止整个 TiDB 的服务。 - -### `binlog-socket` - -+ binlog 输出网络地址。 -+ 默认值："" - -### `strategy` - -+ binlog 输出时选择 pump 的策略，仅支持 hash ，range 方法。 -+ 默认值："range" - -## status - -TiDB 服务状态相关配置。 - -### `report-status` - -+ 开启 HTTP API 服务的开关。 -+ 默认值：true - -### `record-db-qps` - -+ 输与 database 相关的 QPS metrics 到 Prometheus 的开关。 -+ 默认值：false - -## stmt-summary 从 v3.0.4 版本开始引入 - -系统表 `events_statement_summary_by_digest` 的相关配置。 - -### max-stmt-count - -+ `events_statement_summary_by_digest` 表中保存的 SQL 种类的最大数量。 -+ 默认值：100 - -### max-sql-length - -+ `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 -+ 默认值：4096 - -## pessimistic-txn - -### enable - -+ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/v3.0/reference/transactions/transaction-pessimistic.md)。 -+ 默认值：true - -### max-retry-count - -+ 悲观事务中每个语句最大重试次数，超出该限制将会报错。 -+ 默认值：256 diff --git a/v3.0/reference/configuration/tidb-server/configuration.md b/v3.0/reference/configuration/tidb-server/configuration.md deleted file mode 100644 index 9bce1594d1b4..000000000000 --- a/v3.0/reference/configuration/tidb-server/configuration.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: TiDB 命令行参数 -category: reference -aliases: ['/docs-cn/op-guide/configuration/','/docs-cn/sql/server-command-option/','/docs-cn/sql/tidb-server/'] ---- - -# TiDB 命令行参数 - -在启动 TiDB 时，你可以使用命令行参数或环境变量来配置 TiDB。本文将详细介绍 TiDB 的命令行启动参数。TiDB 的默认端口为 4000（客户端请求）与 10080（状态报告）。 - -## `--advertise-address` - -+ 登录 TiDB 的 IP 地址 -+ 默认："" -+ 必须确保用户和集群中的其他机器都能够访问到该 IP 地址 - -## `--binlog-socket` - -+ TiDB 服务使用 unix socket file 方式接受内部连接，如 Pump 服务 -+ 默认："" -+ 例如，可以使用 "/tmp/pump.sock" 来接受 Pump unix socket file 通信 - -## `--config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiDB 会首先读取配置文件的配置。如果对应的配置在命令行参数里面也存在，TiDB 就会使用命令行参数的配置来覆盖配置文件中的配置。详细的配置项请参阅 [TiDB 配置文件描述](/v3.0/reference/configuration/tidb-server/configuration-file.md)。 - -## `--cors` - -+ 用于设置 TiDB HTTP 状态服务的 Access-Control-Allow-Origin -+ 默认："" - -## `--host` - -+ TiDB 服务监听的 host -+ 默认："0.0.0.0" -+ 0.0.0.0 默认会监听所有的网卡地址。如果有多块网卡，可以指定对外提供服务的网卡，如 192.168.100.113 - -## `-L` - -+ Log 级别 -+ 默认："info" -+ 可选项为：debug、info、warn、error、fatal - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 "stderr"；如果设置了该参数，log 会输出到对应的文件中。每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--log-slow-query` - -+ 慢查询日志文件路径 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 `--log-file` 指定的文件中 - -## `--metrics-addr` - -+ Prometheus Pushgateway 地址 -+ 默认："" -+ 如果该参数为空，TiDB 不会将统计信息推送给 Pushgateway。参数格式示例：`--metrics-addr=192.168.100.115:9091` - -## `--metrics-interval` - -+ 推送统计信息到 Prometheus Pushgateway 的时间间隔 -+ 默认：15s -+ 设置为 0 表示不推送统计信息给 Pushgateway。示例：`--metrics-interval=2` 指每两秒推送到 Pushgateway - -## `-P` - -+ TiDB 服务监听端口 -+ 默认："4000" -+ TiDB 服务会使用该端口接受 MySQL 客户端发来的请求 - -## `--path` - -+ 对于本地存储引擎 "mocktikv" 来说，path 指定的是实际的数据存放路径 -+ 当 `--store = tikv` 时，必须指定 path；当 `--store = mocktikv` 时，如果不指定 path，会使用默认值。 -+ 对于 "TiKV" 存储引擎来说，path 指定的是实际的 PD 地址。假如在 192.168.100.113:2379、192.168.100.114:2379 和 192.168.100.115:2379 上面部署了 PD，那么 path 为 "192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379" -+ 默认："/tmp/tidb" -+ 可以通过 `tidb-server --store=mocktikv --path=""` 来启动一个纯内存引擎的 TiDB - -## `--proxy-protocol-networks` - -+ PROXY Protocol 允许的代理服务器地址列表。如需配置多个地址，用 `,` 分隔。 -+ 默认："" -+ 如果该参数为空，TiDB 会禁用 PROXY Protocol 功能。地址可以使用 IP 地址 (192.168.1.50) 或者 CIDR (192.168.1.0/24)，`*` 代表所有地址。 - -## `--proxy-protocol-header-timeout` - -+ PROXY Protocol 请求头读取超时时间 -+ 默认：5 -+ 单位：秒 - -> **注意：** -> -> 不要将该参数配置为 `0`。除非特殊情况，一般使用默认值即可。 - -## `--report-status` - -+ 用于打开或者关闭服务状态监听端口 -+ 默认：true -+ 将参数值设置为 `true` 表明开启状态监听端口；设置为 `false` 表明关闭状态监听端口 - -## `--run-ddl` - -+ tidb-server 是否运行 DDL 语句，集群内至少需要有一台 tidb-server 设置该参数 -+ 默认：true -+ 值可以为 `true` 或者 `false`。设置为 `true` 表明自身会运行 DDL；设置为 `false` 表明自身不会运行 DDL - -## `--socket string` - -+ TiDB 服务使用 unix socket file 方式接受外部连接 -+ 默认："" -+ 例如可以使用 "/tmp/tidb.sock" 来打开 unix socket file - -## `--status` - -+ TiDB 服务状态监听端口 -+ 默认："10080" -+ 该端口用于展示 TiDB 内部数据，包括 [prometheus 统计](https://prometheus.io/) 和 [pprof](https://golang.org/pkg/net/http/pprof/) -+ Prometheus 统计可以通过 `http://host:status_port/metrics` 访问 -+ pprof 数据可以通过 `http://host:status_port/debug/pprof` 访问 - -## `--status-host` - -+ TiDB 服务状态监听 host -+ 默认："0.0.0.0" - -## `--store` - -+ 用来指定 TiDB 底层使用的存储引擎 -+ 默认："mocktikv" -+ 可以选择 "mocktikv"（本地存储引擎）或者 "tikv"（分布式存储引擎） - -## `--token-limit` - -+ TiDB 中同时允许运行的 Session 数量，用于流量控制 -+ 默认：1000 -+ 如果当前运行的连接多于该 token-limit，那么请求会阻塞，等待已经完成的操作释放 Token - -## `-V` - -+ 输出 TiDB 的版本 -+ 默认："" diff --git a/v3.0/reference/configuration/tidb-server/mysql-variables.md b/v3.0/reference/configuration/tidb-server/mysql-variables.md deleted file mode 100644 index 14b367554a1c..000000000000 --- a/v3.0/reference/configuration/tidb-server/mysql-variables.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: 系统变量 -category: reference -aliases: ['/docs-cn/sql/variable/'] - ---- - -# 系统变量 - -MySQL 系统变量 (System Variables) 是一些系统参数，用于调整数据库运行时的行为，根据变量的作用范围分为全局范围有效（Global Scope）以及会话级别有效（Session Scope）。TiDB 支持 MySQL5.7 的所有系统变量，大部分变量仅仅是为了兼容性而支持，不会影响运行时行为。 - -## 设置系统变量 - -通过 [`SET` 语句](/v3.0/reference/sql/statements/set-variable.md) 可以修改系统变量的值。进行修改时，还要考虑变量可修改的范围，不是所有的变量都能在全局/会话范围内进行修改。具体的可修改范围参考 [MySQL 动态变量文档](https://dev.mysql.com/doc/refman/5.7/en/dynamic-system-variables.html)。 - -### 全局范围值 - -* 在变量名前加 `GLOBAL` 关键词或者是使用 `@@global.` 作为修饰符: - - {{< copyable "sql" >}} - - ```sql - SET GLOBAL autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@global.autocommit = 1; - ``` - -> **注意：** -> -> 在分布式 TiDB 中，`GLOBAL` 变量的设置会持久化到存储层中，单个 TiDB 实例每 2 秒会主动进行一次全变量的获取并形成 `gvc` (global variables cache) 缓存，该缓存有效时间最多可持续 2 秒。在设置 `GLOBAL` 变量之后，为了保证新会话的有效性，请确保两个操作之间的间隔大于 2 秒。相关细节可以查看 [Issue #14531](https://github.com/pingcap/tidb/issues/14531)。 - -### 会话范围值 - -* 在变量名前加 `SESSION` 关键词或者是使用 `@@session.` 作为修饰符，或者是不加任何修饰符: - - {{< copyable "sql" >}} - - ```sql - SET SESSION autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@session.autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@autocommit = 1; - ``` - -* `LOCAL` 以及 `@@local.` 是 `SESSION` 以及 `@@session.` 的同义词 - -### 系统变量的作用机制 - -* 会话范围的系统变量仅仅会在创建会话时才会根据全局范围系统变量初始化自己的值。更改全局范围的系统变量不会改变已经创建的会话正在使用的系统变量的值。 - - {{< copyable "sql" >}} - - ```sql - SELECT @@GLOBAL.autocommit; - ``` - - ``` - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | ON | - +---------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SET GLOBAL autocommit = OFF; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - 会话范围的系统变量不会改变，会话中执行的事务依旧是以自动提交的形式来进行： - - {{< copyable "sql" >}} - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SELECT @@GLOBAL.autocommit; - ``` - - ``` - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | OFF | - +---------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - exit - ``` - - ``` - Bye - ``` - - {{< copyable "shell-regular" >}} - - ```shell - mysql -h 127.0.0.1 -P 4000 -u root -D test - ``` - - ``` - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 3 - Server version: 5.7.25-TiDB-None MySQL Community Server (Apache License 2.0) - - Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. - - Oracle is a registered trademark of Oracle Corporation and/or its - affiliates. Other names may be trademarks of their respective - owners. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - mysql> - ``` - - 新建的会话会使用新的全局变量： - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | OFF | - +----------------------+ - 1 row in set (0.00 sec) - ``` - -## TiDB 支持的 MySQL 系统变量 - -下列系统变量是 TiDB 真正支持并且行为和 MySQL 一致： - -| 变量名 | 作用域 | 说明 | -| ---------------- | -------- | -------------------------------------------------- | -| autocommit | GLOBAL \| SESSION | 是否自动 Commit 事务 | -| sql_mode | GLOBAL \| SESSION | 支持部分 MySQL SQL mode，| -| time_zone | GLOBAL \| SESSION | 数据库所使用的时区 | -| tx_isolation | GLOBAL \| SESSION | 事务隔离级别 | -| max\_execution\_time | GLOBAL \| SESSION | 语句超时时间，单位为毫秒 | -| innodb\_lock\_wait\_timeout | GLOBAL \| SESSION | 悲观事务语句等锁时间，单位为秒 | - -> **注意：** -> -> `max_execution_time` 目前对所有类型的 `statement` 生效，并非只对 `SELECT` 语句生效。实际精度在 100ms 级别，而非更准确的毫秒级别。 - -## TiDB 特有的系统变量 - -参见 [TiDB 专用系统变量](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md b/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md deleted file mode 100644 index 0006363caf8b..000000000000 --- a/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md +++ /dev/null @@ -1,672 +0,0 @@ ---- -title: TiDB 专用系统变量和语法 -category: reference -aliases: ['/docs-cn/sql/tidb-specific/'] - ---- - -# TiDB 专用系统变量和语法 - -TiDB 在 MySQL 的基础上，定义了一些专用的系统变量和语法用来优化性能。 - -## 系统变量 - -变量可以通过 SET 语句设置，例如 - -{{< copyable "sql" >}} - -```sql -set @@tidb_distsql_scan_concurrency = 10; -``` - -如果需要设置全局变量，执行 - -{{< copyable "sql" >}} - -```sql -set @@global.tidb_distsql_scan_concurrency = 10; -``` - -### tidb_snapshot - -作用域：SESSION - -默认值：空字符串 - -这个变量用来设置当前会话期待读取的历史数据所处时刻。比如当设置为 "2017-11-11 20:20:20" 时或者一个 TSO 数字 "400036290571534337"，当前会话将能读取到该时刻的数据。 - -### tidb_import_data - -作用域：SESSION - -默认值：0 - -这个变量用来表示当前状态是否为从 dump 文件中导入数据。 -当这个变量被设置为 1 时，唯一索引约束不被检查以加速导入速度。 -这个变量不对外用，只是给 lightning 使用，请用户不要自行修改。 - -### tidb_opt_agg_push_down - -作用域：SESSION - -默认值：0 - -这个变量用来设置优化器是否执行聚合函数下推到 Join 之前的优化操作。 -当查询中聚合操作执行很慢时，可以尝试设置该变量为 1。 - -### tidb_auto_analyze_ratio - -作用域：GLOBAL - -默认值：0.5 - -这个变量用来设置自动 ANALYZE 更新的阈值。当某个表 `tbl` 的修改行数与总行数的比值大于 tidb_auto_analyze_ratio，并且当前时间在 tidb_auto_analyze_start_time 和 tidb_auto_analyze_end_time 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句以自动更新该表的统计信息。注意：只有在 TiDB 的启动配置文件中开启了 run-auto-analyze 选项，该 TiDB 才会触发 auto_analyze。 - -### tidb_auto_analyze_start_time - -作用域：GLOBAL - -默认值：00:00 +0000 - -这个变量用来设置一天中允许自动 ANALYZE 更新的开始时间。 - -### tidb_auto_analyze_end_time - -作用域：GLOBAL - -默认值：23:59 +0000 - -这个变量用来设置一天中允许自动 ANALYZE 更新的结束时间。 - -### tidb_build_stats_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ANALYZE 语句执行时并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_checksum_table_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ADMIN CHECKSUM TABLE 语句执行时扫描索引的并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_current_ts - -作用域：SESSION - -默认值：0 - -这个变量是一个只读变量，用来获取当前事务的时间戳。 - -### tidb_config - -作用域：SESSION - -默认值：空字符串 - -这个变量是一个只读变量，用来获取当前 TiDB Server 的配置信息。 - -### tidb_distsql_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：15 - -这个变量用来设置 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 -对于 AP 类应用，最大值建议不要超过所有 TiKV 节点的 CPU 核数。 - -### tidb_index_lookup_size - -作用域：SESSION | GLOBAL - -默认值：20000 - -这个变量用来设置 index lookup 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup join 算法的并发度。 - -### tidb_hash_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：5 - -这个变量用来设置 hash join 算法的并发度。 - -### tidb_index_serial_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来设置顺序 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_projection_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 Projection 算子的并发度。 - -### tidb_hashagg_partial_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 partial 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_hashagg_final_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 final 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_index_join_batch_size - -作用域：SESSION | GLOBAL - -默认值：25000 - -这个变量用来设置 index lookup join 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_skip_utf8_check - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来设置是否跳过 UTF-8 字符的验证。 -验证 UTF-8 字符需要消耗一定的性能，当可以确认输入的字符串为有效的 UTF-8 字符时，可以将其设置为 1。 - -### tidb_init_chunk_size - -作用域：SESSION | GLOBAL - -默认值：32 - -这个变量用来设置执行过程中初始 chunk 的行数。默认值是 32。 - -### tidb_max_chunk_size - -作用域：SESSION | GLOBAL - -默认值：1024 - -这个变量用来设置执行过程中一个 chunk 最大的行数。 - -### tidb_mem_quota_query - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置一条查询语句的内存使用阈值。 -如果一条查询语句执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_hashjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 HashJoin 算子的内存使用阈值。 -如果 HashJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_mergejoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 MergeJoin 算子的内存使用阈值。 -如果 MergeJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_sort - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 Sort 算子的内存使用阈值。 -如果 Sort 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_topn - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 TopN 算子的内存使用阈值。 -如果 TopN 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupreader - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupReader 算子的内存使用阈值。 - -如果 IndexLookupReader 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupJoin 算子的内存使用阈值。 -如果 IndexLookupJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_nestedloopapply - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 NestedLoopApply 算子的内存使用阈值。 -如果 NestedLoopApply 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_general_log - -作用域：SERVER - -默认值：0 - -这个变量用来设置是否在日志里记录所有的 SQL 语句。 - -### tidb_enable_streaming - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否启用 Streaming。 - -### tidb_retry_limit - -作用域：SESSION | GLOBAL - -默认值：10 - -这个变量用来设置最大重试次数。一个事务执行中遇到可重试的错误（例如事务冲突、事务提交过慢或表结构变更）时，会根据该变量的设置进行重试。注意当 `tidb_retry_limit = 0` 时，也会禁用自动重试。 - -### tidb_disable_txn_auto_retry - -作用域：SESSION | GLOBAL - -默认值：on - -这个变量用来设置是否禁用显式事务自动重试，设置为 `on` 时，不会自动重试，如果遇到事务冲突需要在应用层重试。 - -如果将该变量的值设为 `off`，TiDB 将会自动重试事务，这样在事务提交时遇到的错误更少。需要注意的是，这样可能会导致数据更新丢失。 - -这个变量不会影响自动提交的隐式事务和 TiDB 内部执行的事务，它们依旧会根据 `tidb_retry_limit` 的值来决定最大重试次数。 - -是否需要禁用自动重试，请参考[重试的局限性](/v3.0/reference/transactions/transaction-optimistic.md#重试的局限性)。 - -### tidb_backoff_weight - -作用域：SESSION | GLOBAL - -默认值：2 - -这个变量用来给 TiDB 的 `backoff` 最大时间增加权重，即内部遇到网络或其他组件（TiKV、PD）故障等时，发送重试请求的最大重试时间。可以通过这个变量来调整最大重试时间，最小值为 1。 - -例如，TiDB 向 PD 取 TSO 的基础超时时间是 15 秒，当 `tidb_backoff_weight = 2` 时，取 TSO 的最大超时时间为：基础时间 * 2 等于 30 秒。 - -在网络环境较差的情况下，适当增大该变量值可以有效缓解因为超时而向应用端报错的情况；而如果应用端希望更快地接到报错信息，则应该尽量减小该变量的值。 - -### tidb_enable_table_partition - -作用域：SESSION - -默认值："auto" - -这个变量用来设置是否开启 TABLE PARTITION 特性。默认值 `auto` 表示开启 range partition 和 hash partion。`off` 表示关闭 TABLE PARTITION 的特性，此时语法还是会依旧兼容，只是建立的 partition table 实际上并不是真正的 partition table，而是和普通的 table 一样。`on` 表示开启，目前的作用和 `auto` 一样。 - -注意，目前 TiDB 只支持 range partition 和 hash partition。 - -### tidb_backoff_lock_fast - -作用域：SESSION | GLOBAL - -默认值：100 - -这个变量用来设置读请求遇到锁的 backoff 时间。 - -### tidb_ddl_reorg_worker_cnt - -作用域：GLOBAL - -默认值：16 - -这个变量用来设置 DDL 操作 re-organize 阶段的并发度。 - -### tidb_ddl_reorg_batch_size - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置 DDL 操作 re-organize 阶段的 batch size。比如 Add Index 操作，需要回填索引数据，通过并发 tidb_ddl_reorg_worker_cnt 个 worker 一起回填数据，每个 worker 以 batch 为单位进行回填。如果 Add Index 时有较多 Update 操作或者 Replace 等更新操作，batch size 越大，事务冲突的概率也会越大，此时建议调小 batch size 的值，最小值是 32。在没有事务冲突的情况下，batch size 可设为较大值，最大值是 10240，这样回填数据的速度更快，但是 TiKV 的写入压力也会变大。 - -### tidb_ddl_reorg_priority - -作用域：SESSION | GLOBAL - -默认值：PRIORITY_LOW - -这个变量用来设置 `ADD INDEX` 操作 re-organize 阶段的执行优先级，可设置为 PRIORITY_LOW/PRIORITY_NORMAL/PRIORITY_HIGH。 - -### tidb_ddl_error_count_limit - -作用域：GLOBAL - -默认值：512 - -这个变量用来控制 DDL 操作失败重试的次数。失败重试次数超过该参数的值后，会取消出错的 DDL 操作。 - -### tidb_max_delta_schema_count - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置缓存 schema 版本信息（对应版本修改的相关 table IDs）的个数限制，可设置的范围 100 - 16384。此变量在 2.1.18 及之后版本支持。 - -### tidb_force_priority - -作用域：SESSION - -默认值：`NO_PRIORITY` - -这个变量用于改变 TiDB server 上执行的语句的默认优先级。例如，你可以通过设置该变量来确保正在执行 OLAP 查询的用户优先级低于正在执行 OLTP 查询的用户。 - -可设置为 `NO_PRIORITY`、`LOW_PRIORITY`、`DELAYED` 或 `HIGH_PRIORITY`。 - -### tidb_opt_write_row_id - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否允许 insert、replace 和 update 操作 `_tidb_rowid` 列，默认是不允许操作。该选项仅用于 TiDB 工具导数据时使用。 - -### SHARD_ROW_ID_BITS - -对于 PK 非整数或没有 PK 的表，TiDB 会使用一个隐式的自增 rowid，大量 `INSERT` 时会把数据集中写入单个 Region，造成写入热点。 - -通过设置 `SHARD_ROW_ID_BITS`，可以把 rowid 打散写入多个不同的 Region，缓解写入热点问题。但是设置的过大会造成 RPC 请求数放大，增加 CPU 和网络开销。 - -- `SHARD_ROW_ID_BITS = 4` 表示 16 个分片 -- `SHARD_ROW_ID_BITS = 6` 表示 64 个分片 -- `SHARD_ROW_ID_BITS = 0` 表示默认值 1 个分片 - -语句示例： - -- `CREATE TABLE`：`CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` -- `ALTER TABLE`：`ALTER TABLE t SHARD_ROW_ID_BITS = 4;` - -### tidb_slow_log_threshold - -作用域：SESSION - -默认值：300 - -输出慢日志的耗时阈值。当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。默认为 300ms。 - -示例： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_log_threshold = 200; -``` - -### tidb_query_log_max_len - -作用域：SESSION - -默认值：2048 (bytes) - -最长的 SQL 输出长度。当语句的长度大于 query-log-max-len，将会被截断输出。 - -示例： - -{{< copyable "sql" >}} - -```sql -set tidb_query_log_max_len = 20; -``` - -### tidb_txn_mode 从 v3.0.4 版本开始引入 - -作用域：SESSION（自 TiDB 3.0.4 起支持 GLOBAL） - -默认值："pessimistic" - -这个变量用于设置事务模式。TiDB v3.0 支持了悲观事务，自 v3.0.8 开始，默认使用[悲观事务模式](/v3.0/reference/transactions/transaction-pessimistic.md)。 - -但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 - -将该变量设置为 "optimistic" 或 "" 时，将会使用[乐观事务模式](/v3.0/reference/transactions/transaction-optimistic.md)。 - -自 TiDB 3.0.4 起，该变量也支持 GLOBAL 作用域，用于设定全局的事务模式。当设定全局的事务模式时，仅在修改生效之后创建的 session 会受到影响。 - -### tidb_constraint_check_in_place - -作用域：SESSION | GLOBAL - -默认值：0 - -TiDB 支持乐观事务模型，即在执行写入时，假设不存在冲突。冲突检查是在最后 commit 提交时才去检查。这里的检查指 unique key 检查。 - -这个变量用来控制是否每次写入一行时就执行一次唯一性检查。注意，开启该变量后，在大批量写入场景下，对性能会有影响。 - -示例： - -默认关闭 tidb_constraint_check_in_place 时的行为： - -{{< copyable "sql" >}} - -```sql -create table t (i int key); -insert into t values (1); -begin; -insert into t values (1); -``` - -``` -Query OK, 1 row affected -``` - -commit 时才去做检查： - -{{< copyable "sql" >}} - -```sql -commit; -``` - -``` -ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' -``` - -打开 tidb_constraint_check_in_place 后： - -{{< copyable "sql" >}} - -```sql -set @@tidb_constraint_check_in_place=1; -begin; -insert into t values (1); -``` - -``` -ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' -``` - -### tidb_check_mb4_value_in_utf8 - -作用域：SERVER - -默认值：1 - -这个变量用来设置是否开启对字符集为 UTF8 类型的数据做合法性检查，默认值 `1` 表示开启检查。这个默认行为和 MySQL 是兼容的。 - -注意，如果是旧版本升级时，可能需要关闭该选项，否则由于旧版本（v2.1.1 以及之前）没有对数据做合法性检查，所以旧版本写入非法字符串是可以写入成功的，但是新版本加入合法性检查后会报写入失败。具体可以参考[升级后常见问题](/v3.0/faq/upgrade.md)。 - -### tidb_opt_insubq_to_join_and_agg - -作用域：SESSION | GLOBAL - -默认值：1 - -这个用来设置是否开启优化规则：将子查询转成 join 和 aggregation。 - -示例： - -打开这个优化规则后，会将下面子查询做如下变化： - -{{< copyable "sql" >}} - -```sql -select * from t where t.a in (select aa from t1); -``` - -将子查询转成 join 如下： - -{{< copyable "sql" >}} - -```sql -select * from t, (select aa from t1 group by aa) tmp_t where t.a = tmp_t.aa; -``` - -如果 t1 在列 aa 上有 unique 且 not null 的限制，可以直接改写为如下，不需要添加 aggregation。 - -{{< copyable "sql" >}} - -```sql -select * from t, t1 where t.a=t1.a; -``` - -### tidb_opt_correlation_threshold - -作用域：SESSION | GLOBAL - -默认值：0.9 - -这个变量用来设置优化器启用交叉估算 row count 方法的阈值。如果列和 handle 列之间的顺序相关性超过这个阈值，就会启用交叉估算方法。 - -交叉估算方法可以简单理解为，利用这个列的直方图来估算 handle 列需要扫的行数。 - -### tidb_opt_correlation_exp_factor - -作用域：SESSION | GLOBAL - -默认值：1 - -当交叉估算方法不可用时，会采用启发式估算方法。这个变量用来控制启发式方法的行为。当值为 0 时不用启发式估算方法，大于 0 时，该变量值越大，启发式估算方法越倾向 index scan，越小越倾向 table scan。 - -### tidb_enable_window_function - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来控制是否开启窗口函数的支持。默认值 1 代表开启窗口函数的功能。 - -由于窗口函数会使用一些保留关键字，可能导致原先可以正常执行的 SQL 语句在升级 TiDB 后无法被解析语法，此时可以将 `tidb_enable_window_function` 设置为 `0`。 - -### tidb_slow_query_file - -作用域：SESSION - -默认值："" - -查询 `INFORMATION_SCHEMA.SLOW_QUERY` 只会解析配置文件中 `slow-query-file` 设置的慢日志文件名，默认是 "tidb-slow.log"。但如果想要解析其他的日志文件，可以通过设置 session 变量 `tidb_slow_query_file` 为具体的文件路径，然后查询 `INFORMATION_SCHEMA.SLOW_QUERY` 就会按照设置的路径去解析慢日志文件。更多详情可以参考 [SLOW_QUERY 文档](/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 - -### tidb_enable_fast_analyze - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来控制是否启用统计信息快速分析功能。默认值 0 表示不开启。 - -快速分析功能开启后，TiDB 会随机采样约 10000 行的数据来构建统计信息。因此在数据分布不均匀或者数据量比较少的情况下，统计信息的准确度会比较低。这可能导致执行计划不优，比如选错索引。如果可以接受普通 `ANALYZE` 语句的执行时间，则推荐关闭快速分析功能。 - -### tidb_expensive_query_time_threshold - -作用域：SERVER - -默认值：60 - -这个变量用来控制打印 expensive query 日志的阈值时间，单位是秒，默认值是 60 秒。expensive query 日志和慢日志的差别是，慢日志是在语句执行完后才打印，expensive query 日志可以把正在执行中的语句且执行时间超过阈值的语句及其相关信息打印出来。 - -### tidb_wait_split_region_finish - -作用域：SESSION - -默认值：1 - -由于打散 region 的时间可能比较长，主要由 PD 调度以及 TiKV 的负载情况所决定。这个变量用来设置在执行 `SPLIT REGION` 语句时，是否同步等待所有 region 都打散完成后再返回结果给客户端。默认 1 代表等待打散完成后再返回结果。0 代表不等待 Region 打散完成就返回。 - -需要注意的是，在 region 打散期间，对正在打散 region 上的写入和读取的性能会有一定影响，对于批量写入，导数据等场景，还是建议等待 region 打散完成后再开始导数据。 - -### tidb_wait_split_region_timeout - -作用域：SESSION - -默认值：300 - -这个变量用来设置 `SPLIT REGION` 语句的执行超时时间，单位是秒，默认值是 300 秒，如果超时还未完成，就返回一个超时错误。 - -### tidb_scatter_region - -作用域：GLOBAL - -默认值：0 - -TiDB 默认会在建表时为新表分裂 Region。开启该变量后，会在建表语句执行时，同步打散刚分裂出的 Region。适用于批量建表后紧接着批量写入数据，能让刚分裂出的 Region 先在 TiKV 分散而不用等待 PD 进行调度。为了保证后续批量写入数据的稳定性，建表语句会等待打散 Region 完成后再返回建表成功，建表语句执行时间会是关闭该变量的数倍。 - -### tidb_allow_remove_auto_inc 从 v3.0.4 版本开始引入 - -作用域：SESSION - -默认值：0 - -这个变量用来控制是否允许通过 `ALTER TABLE MODIFY` 或 `ALTER TABLE CHANGE` 来移除某个列的 `AUTO_INCREMENT` 属性。默认为不允许。 - -### tidb_enable_stmt_summary 从 v3.0.4 版本开始引入 - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来控制是否开启 statement summary 功能。如果开启，SQL 的耗时等执行信息将被记录到系统表 `performance_schema.events_statements_summary_by_digest` 中，用于定位和排查 SQL 性能问题。 diff --git a/v3.0/reference/configuration/tikv-server/configuration-file.md b/v3.0/reference/configuration/tikv-server/configuration-file.md deleted file mode 100644 index 322c5edf7b8c..000000000000 --- a/v3.0/reference/configuration/tikv-server/configuration-file.md +++ /dev/null @@ -1,1093 +0,0 @@ ---- -title: TiKV 配置文件描述 -category: reference ---- - - - -# TiKV 配置文件描述 - -TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/config-template.toml](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 找到默认值的配置文件，重命名为 config.toml 即可。 - -本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [TiKV 配置参数](/v3.0/reference/configuration/tikv-server/configuration.md)。 - -### `status-thread-pool-size` - -+ Http API 服务的工作线程数量。 -+ 默认值：1 -+ 最小值：1 - -### `grpc-compression-type` - -+ gRPC 消息的压缩算法，取值：none， deflate， gzip。 -+ 默认值：none - -### `grpc-concurrency` - -+ gRPC 工作线程的数量。 -+ 默认值：4 -+ 最小值：1 - -### `grpc-concurrent-stream` - -+ 一个 gRPC 链接中最多允许的并发请求数量。 -+ 默认值：1024 -+ 最小值：1 - -### `server.grpc-raft-conn-num` - -+ tikv 节点之间用于 raft 通讯的链接最大数量。 -+ 默认值：10 -+ 最小值：1 - -### `server.grpc-stream-initial-window-size` - -+ gRPC stream 的 window 大小。 -+ 默认值：2MB -+ 单位：KB|MB|GB -+ 最小值：1KB - -### `server.grpc-keepalive-time` - -+ gRPC 发送 keep alive ping 消息的间隔时长。 -+ 默认值：10s -+ 最小值：1s - -### `server.grpc-keepalive-timeout` - -+ 关闭 gRPC 链接的超时时长。 -+ 默认值：3s -+ 最小值：1s - -### `server.concurrent-send-snap-limit` - -+ 同时发送 snapshot 的最大个数，默认值：32 -+ 默认值：32 -+ 最小值：1 - -### `server.concurrent-recv-snap-limit` - -+ 同时接受 snapshot 的最大个数，默认值：32 -+ 默认值：32 -+ 最小值：1 - -### `server.end-point-recursion-limit` - -+ endpoint 下推查询请求解码消息时，最多允许的递归层数。 -+ 默认值：1000 -+ 最小值：1 - -### `server.end-point-request-max-handle-duration` - -+ endpoint 下推查询请求处理任务最长允许的时长。 -+ 默认值：60s -+ 最小值：1s - -### `server.snap-max-write-bytes-per-sec` - -+ 处理 snapshot 时最大允许使用的磁盘带宽 -+ 默认值：1000MB -+ 单位：KB|MB|GB -+ 最小值：1KB - -## readpool.storage - -存储线程池相关的配置项。 - -### `high-concurrency` - -+ 处理高优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `normal-concurrency` - -+ 处理普通优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `low-concurrency` - -+ 处理低优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `max-tasks-per-worker-high` - -+ 高优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-normal` - -+ 普通优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-low` - -+ 低优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `stack-size` - -+ Storage 读线程池中线程的栈大小。 -+ 默认值：10MB -+ 单位：KB|MB|GB -+ 最小值：2MB - -## readpool.coprocessor - -协处理器线程池相关的配置项。 - -### `high-concurrency` - -+ 处理高优先级 Coprocessor 请求（如点查）的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `normal-concurrency` - -+ 处理普通优先级 Coprocessor 请求的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `low-concurrency` - -+ 处理低优先级 Coprocessor 请求（如扫表）的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `max-tasks-per-worker-high` - -+ 高优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-normal` - -+ 普通优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-low` - -+ 低优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `stack-size` - -Coprocessor 线程池中线程的栈大小，默认值：10，单位：KiB|MiB|GiB。 - -+ 默认值：10MB -+ 单位：KB|MB|GB -+ 最小值：2MB - -## storage - -存储相关的配置项。 - -### `scheduler-notify-capacity` - -+ scheduler 一次获取最大消息个数 -+ 默认值：10240 -+ 最小值：1 - -### `scheduler-concurrency` - -+ scheduler 内置一个内存锁机制，防止同时对一个 key 进行操作。每个 key hash 到不同的槽。 -+ 默认值：2048000 -+ 最小值：1 - -### `scheduler-worker-pool-size` - -+ scheduler 线程个数，主要负责写入之前的事务一致性检查工作。 -+ 默认值：4 -+ 最小值：1 - -### `scheduler-pending-write-threshold` - -+ 写入数据队列的最大值，超过该值之后对于新的写入 TiKV 会返回 Server Is Busy 错误。 -+ 默认值：100MB -+ 单位: MB|GB - -## raftstore - -raftstore 相关的配置项。 - -### `sync-log` - -+ 数据、log 落盘是否 sync，注意：设置成 false 可能会丢数据。 -+ 默认值：true - -### `prevote` - -+ 开启 Prevote 的开关，开启有助于减少隔离恢复后对系统造成的抖动。 -+ 默认值：true - -### `raftdb-path` - -+ raft 库的路径，默认存储在 storage.data-dir/raft 下。 -+ 默认值："" - -### `raft-base-tick-interval` - -+ 状态机 tick 一次的间隔时间。 -+ 默认值：1s -+ 最小值：大于 0 - -### `raft-heartbeat-ticks` - -+ 发送心跳时经过的 tick 个数，即每隔 raft-base-tick-interval * raft-heartbeat-ticks 时间发送一次心跳。 -+ 默认值：2 -+ 最小值：大于 0 - -### `raft-election-timeout-ticks` - -+ 发起选举时经过的 tick 个数，即如果处于无主状态，大约经过 raft-base-tick-interval * raft-election-timeout-ticks 时间以后发起选举。 -+ 默认值：10 -+ 最小值：raft-heartbeat-ticks - -### `raft-min-election-timeout-ticks` - -+ 发起选举时至少经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks，不能比 raft-election-timeout-ticks 小。 -+ 默认值：0 -+ 最小值：0 - -### `raft-max-election-timeout-ticks` - -+ 发起选举时最多经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks * 2。 -+ 默认值：0 -+ 最小值：0 - -### `raft-max-size-per-message` - -+ 产生的单个消息包的大小限制，软限制。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：MB - -### `raft-max-inflight-msgs` - -+ 待确认日志个数的数量，如果超过这个数量将会减缓发送日志的个数。 -+ 默认值：256 -+ 最小值：大于0 - -### `raft-entry-max-size` - -+ 单个日志最大大小，硬限制。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：MB|GB - -### `raft-log-gc-tick-interval` - -+ 删除 raft 日志的轮询任务调度间隔时间，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `raft-log-gc-threshold` - -+ 允许残余的 raft 日志个数，这是一个软限制。 -+ 默认值：50 -+ 最小值：1 - -### `raft-log-gc-count-limit` - -+ 允许残余的 raft 日志个数，这是一个硬限制。默认值为按照每个日志 1MB 而计算出来的 3/4 region 大小所能容纳的日志个数。 -+ 最小值：0 - -### `raft-log-gc-size-limit` - -+ 允许残余的 raft 日志大小，这是一个硬限制，默认为 region 大小的 3/4。 -+ 最小值：大于 0 - -### `raft-entry-cache-life-time` - -+ 内存中日志 cache 允许的最长残留时间。 -+ 默认值：30s -+ 最小值：0 - -### `raft-reject-transfer-leader-duration` - -+ 新节点保护时间，控制迁移 leader 到新加节点的最小时间，设置过小容易导致迁移 leader 失败。 -+ 默认值：3s -+ 最小值：0 - -### `raftstore.hibernate-regions` (**实验特性**) - -+ 打开或关闭静默 Region。打开后，如果 Region 长时间处于非活跃状态，即被自动设置为静默状态。静默状态的 Region 可以降低 Leader 和 Follower 之间心跳信息的系统开销。可以通过 `raftstore.peer-stale-state-check-interval` 调整 Leader 和 Follower 之间的心跳间隔。 -+ 默认值：false - -### `raftstore.peer-stale-state-check-interval` - -+ 修改对静默 Region 的状态检查间隔时间。 -+ 默认值：5 min - -### `split-region-check-tick-interval` - -+ 检查 region 是否需要分裂的时间间隔，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `region-split-check-diff` - -+ 允许 region 数据超过指定大小的最大值，默认为 region 大小的 1/16。 -+ 最小值：0 - -### `region-compact-check-interval` - -+ 检查是否需要人工触发 rocksdb compaction 的时间间隔，0 表示不启用。 -+ 默认值：5m -+ 最小值：0 - -### `clean-stale-peer-delay` - -+ 延迟删除过期副本数据的时间。 -+ 默认值：10m -+ 最小值：0 - -### `region-compact-check-step` - -+ 每轮校验人工 compaction 时，一次性检查的 region 个数。 -+ 默认值：100 -+ 最小值：0 - -### `region-compact-min-tombstones` - -+ 触发 rocksdb compaction 需要的 tombstone 个数。 -+ 默认值：10000 -+ 最小值：0 - -### `region-compact-tombstones-percent` - -+ 触发 rocksdb compaction 需要的 tombstone 所占比例。 -+ 默认值：30 -+ 最小值：1 -+ 最大值：100 - -### `pd-heartbeat-tick-interval` - -+ 触发 region 对 PD 心跳的时间间隔，0 表示不启用。 -+ 默认值：1m -+ 最小值：0 - -### `pd-store-heartbeat-tick-interval` - -+ 触发 store 对 PD 心跳的时间间隔，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `snap-mgr-gc-tick-interval` - -+ 触发回收过期 snapshot 文件的时间间隔，0 表示不启用。 -+ 默认值：5s -+ 最小值：0 - -### `snap-gc-timeout` - -+ snapshot 文件的最长保存时间。 -+ 默认值：4h -+ 最小值：0 - -### `lock-cf-compact-interval` - -+ 触发对 lock CF compact 检查的时间间隔。 -+ 默认值：10m -+ 最小值：0 - -### `lock-cf-compact-bytes-threshold` - -+ 触发对 lock CF 进行 compact 的大小。 -+ 默认值：256MB -+ 最小值：0 -+ 单位：MB - -### `notify-capacity` - -+ region 消息队列的最长长度。 -+ 默认值：40960 -+ 最小值：0 - -### `messages-per-tick` - -+ 每轮处理的消息最大个数。 -+ 默认值：4096 -+ 最小值：0 - -### `max-peer-down-duration` - -+ 副本允许的最长未响应时间，超过将被标记为 down，后续 PD 会尝试将其删掉。 -+ 默认值：5m -+ 最小值：0 - -### `max-leader-missing-duration` - -+ 允许副本处于无主状态的最长时间，超过将会向 PD 校验自己是否已经被删除。 -+ 默认值：2h -+ 最小值：> abnormal-leader-missing-duration - -### `abnormal-leader-missing-duration` - -+ 允许副本处于无主状态的时间，超过将视为异常，标记在 metrics 和日志中。 -+ 默认值：10m -+ 最小值：> peer-stale-state-check-interval - -### `peer-stale-state-check-interval` - -+ 触发检验副本是否处于无主状态的时间间隔。 -+ 默认值：5m -+ 最小值：> 2 * election-timeout - -### `leader-transfer-max-log-lag` - -+ 尝试转移领导权时被转移者允许的最大日志缺失个数。 -+ 默认值：10 -+ 最小值：10 - -### `snap-apply-batch-size` - -+ 当导入 snapshot 文件需要写数据时，内存写缓存的大小 -+ 默认值：10MB -+ 最小值：0 -+ 单位：MB - -### `consistency-check-interval` - -+ 触发一致性检查的时间间隔, 0 表示不启用。 -+ 默认值：0s -+ 最小值：0 - -### `raft-store-max-leader-lease` - -+ region 主可信任期的最长时间。 -+ 默认值：9s -+ 最小值：0 - -### `right-derive-when-split` - -+ 为 true 时，以最大分裂 key 为起点的 region 复用原 region 的 key；否则以原 region 起点 key 作为起点的 region 复用原 region 的 key。 -+ 默认值：true - -### `allow-remove-leader` - -+ 允许删除主开关。 -+ 默认值：false - -### `merge-max-log-gap` - -+ 进行 merge 时，允许的最大日志缺失个数。 -+ 默认值：10 -+ 最小值：> raft-log-gc-count-limit - -### `merge-check-tick-interval` - -+ 触发 merge 完成检查的时间间隔。 -+ 默认值：10s -+ 最小值：大于 0 - -### `use-delete-range` - -+ 开启 rocksdb delete_range 接口删除数据的开关。 -+ 默认值：false - -### `cleanup-import-sst-interval` - -+ 触发检查过期 SST 文件的时间间隔，0 表示不启用。 -+ 默认值：10m -+ 最小值：0 - -### `local-read-batch-size` - -+ 一轮处理读请求的最大个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `apply-max-batch-size` - -+ 一轮处理数据落盘的最大请求个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `apply-pool-size` - -+ 处理数据落盘的线程池线程数。 -+ 默认值：2 -+ 最小值：大于 0 - -### `store-max-batch-size` - -+ 一轮处理的最大请求个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `store-pool-size` - -+ 处理 raft 的线程池线程数。 -+ 默认值：2 -+ 最小值：大于 0 - -### `future-poll-size` - -+ 驱动 future 的线程池线程数。 -+ 默认值：1 -+ 最小值：大于 0 - -## coprocessor - -协处理器相关的配置项。 - -### `split-region-on-table` - -+ 开启按 table 分裂 Region的开关，建议仅在 TiDB 模式下使用。 -+ 默认值：true - -### `batch-split-limit` - -+ 批量分裂 Region 的阈值，调大该值可加速分裂 Region。 -+ 默认值：10 -+ 最小值：1 - -### `region-max-size` - -+ Region 容量空间最大值，超过时系统分裂成多个 Region。 -+ 默认值：144MB -+ 单位：KB|MB|GB - -### `region-split-size` - -+ 分裂后新 Region 的大小，此值属于估算值。 -+ 默认值：96MB -+ 单位：KB|MB|GB - -### `region-max-keys` - -+ Region 最多允许的 key 的个数，超过时系统分裂成多个 Region。 -+ 默认值：1440000 - -### `region-split-keys` - -+ 分裂后新 Region 的 key 的个数，此值属于估算值。 -+ 默认值：960000 - -## rocksdb - -rocksdb 相关的配置项。 - -### `max-background-jobs` - -+ RocksDB 后台线程个数。 -+ 默认值：8 -+ 最小值：1 - -### `max-sub-compactions` - -+ RocksDB 进行 subcompaction 的并发个数。 -+ 默认值：1 -+ 最小值：1 - -### `max-open-files` - -+ RocksDB 可以打开的文件总数。 -+ 默认值：40960 -+ 最小值：-1 - -### `max-manifest-file-size` - -+ RocksDB Manifest 文件最大大小。 -+ 默认值：128MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `create-if-missing` - -+ 自动创建 DB 开关。 -+ 默认值：true - -### `wal-recovery-mode` - -+ WAL 恢复模式，取值：0（TolerateCorruptedTailRecords），1（AbsoluteConsistency），2（PointInTimeRecovery），3（SkipAnyCorruptedRecords）。 -+ 默认值：2 -+ 最小值：0 -+ 最大值：3 - -### `wal-dir` - -+ WAL 存储目录，默认：“tmp/tikv/store”。 -+ 默认值：/tmp/tikv/store - -### `wal-ttl-seconds` - -+ 归档 WAL 生存周期，超过该值时，系统会删除相关 WAL。 -+ 默认值：0 -+ 最小值：0 -+ 单位：秒 - -### `wal-size-limit` - -+ 归档 WAL 大小限制，超过该值时，系统会删除相关 WAL。 -+ 默认值：0 -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `enable-statistics` - -+ 开启自动优化 Rate LImiter 的配置的开关。 -+ 默认值：false - -### `stats-dump-period` - -+ 开启或关闭 Pipelined Write。 -+ 默认值：true - -### `compaction-readahead-size` - -+ 异步 Sync 限速速率。 -+ 默认值：0 -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `writable-file-max-buffer-size` - -+ WritableFileWrite 所使用的最大的 buffer 大小。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `use-direct-io-for-flush-and-compaction` - -+ flush 或者 compaction 开启 DirectIO 的开关。 -+ 默认值：false - -### `rate-bytes-per-sec` - -+ Rate Limiter 限制速率。 -+ 默认值：0 -+ 最小值：0 -+ 单位：Bytes - -### `rate-limiter-mode` - -+ Rate LImiter 模式，取值：1（ReadOnly），2（WriteOnly），3（AllIo）。 -+ 默认值：2 -+ 最小值：1 -+ 最大值：3 - -### `auto-tuned` - -+ 开启自动优化 Rate LImiter 的配置的开关。 -+ 默认值：false - -### `enable-pipelined-write` - -+ 开启 Pipelined Write 的开关。 -+ 默认值：true - -### `bytes-per-sync` - -+ 异步 Sync 限速速率。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `wal-bytes-per-sync` - -+ WAL Sync 限速速率，默认：512KB。 -+ 默认值：512KB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `info-log-max-size` - -+ Info 日志的最大大小。 -+ 默认值：1GB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `info-log-roll-time` - -+ 日志截断间隔时间，如果为0则不截断。 -+ 默认值：0 - -### `info-log-keep-log-file-num` - -+ 保留日志文件最大个数。 -+ 默认值：10 -+ 最小值：0 - -### `info-log-dir` - -+ 日志存储目录。 -+ 默认值："" - -## rocksdb.titan - -Titan 相关的配置项。 - -### `enabled` - -+ 开启或关闭 Titan。 -+ 默认值：false - -### `dirname` - -+ Titan Blob 文件存储目录。 -+ 默认值：titandb - -### `disable-gc` - -+ 控制是否关闭 Titan 对 Blob 文件的 GC。 -+ 默认值：false - -### `max-background-gc` - -+ Titan 后台 GC 的线程个数。 -+ 默认值：1 -+ 最小值：1 - -## rocksdb.defaultcf - -rocksdb defaultcf 相关的配置项。 - -### `block-size` - -+ 设置 rocksdb block 大小。 -+ 默认值：64KB -+ 最小值：1KB -+ 单位：KB|MB|GB - -### `block-cache-size` - -+ 设置 rocksdb block 缓存大小。 -+ 默认值：机器总内存 / 4 -+ 最小值：0 -+ 单位：KB|MB|GB - -### `disable-block-cache` - -+ 开启或关闭 block cache。 -+ 默认值：false - -### `cache-index-and-filter-blocks` - -+ 开启或关闭缓存 index 和 filter。 -+ 默认值：true - -### `pin-l0-filter-and-index-blocks` - -+ 是否 pin 住 L0 的 index 和 filter。 -+ 默认值：true - -### `use-bloom-filter` - -+ 开启 bloom filter 的开关。 -+ 默认值：true - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：true - -### `whole_key_filtering` - -+ 开启将整个 key 放到 bloom filter 中的开关。 -+ 默认值：true - -### `bloom-filter-bits-per-key` - -bloom filter 为每个 key 预留的长度。 - -+ 默认值：10 -+ 单位：字节 - -### `block-based-bloom-filter` - -+ 开启每个 block 建立 bloom filter 的开关。 -+ 默认值：false - -### `read-amp-bytes-per-bit` - -+ 开启读放大统计的开关，0：不开启，> 0 开启。 -+ 默认值：0 -+ 最小值：0 - -### `compression-per-level` - -+ 每一层默认压缩算法，默认：前两层为 No，后面 5 层为 lz4。 -+ 默认值：["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -### `write-buffer-size` - -+ memtable 大小。 -+ 默认值：128MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `max-write-buffer-number` - -+ 最大 memtable 个数。 -+ 默认值：5 -+ 最小值：0 - -### `min-write-buffer-number-to-merge` - -+ 触发 flush 的最小 memtable 个数。 -+ 默认值：1 -+ 最小值：0 - -### `max-bytes-for-level-base` - -+ base level (L1) 最大字节数，一般设置为 memtable 大小 4 倍。 -+ 默认值：512MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `target-file-size-base` - -+ base level 的目标文件大小。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `level0-file-num-compaction-trigger` - -+ 触发 compaction 的 L0 文件最大个数。 -+ 默认值：4 -+ 最小值：0 - -### `level0-slowdown-writes-trigger` - -+ 触发 write stall 的 L0 文件最大个数。 -+ 默认值：20 -+ 最小值：0 - -### `level0-stop-writes-trigger` - -+ 完全阻停写入的 L0 文件最大个数。 -+ 默认值：36 -+ 最小值：0 - -### `max-compaction-bytes` - -+ 一次 compaction 最大写入字节数，默认 2GB。 -+ 默认值：2GB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `compaction-pri` - -Compaction 优先类型，默认：3（MinOverlappingRatio），0（ByCompensatedSize）， -1（OldestLargestSeqFirst），2（OldestSmallestSeqFirst）。 - -+ 默认值：3 - -### `dynamic-level-bytes` - -+ 开启 dynamic level bytes 优化的开关。 -+ 默认值：true - -### `num-levels` - -+ RocksDB 文件最大层数。 -+ 默认值：7 - -### `max-bytes-for-level-multiplier` - -+ 每一层的默认放大倍数。 -+ 默认值：10 - -### `rocksdb.defaultcf.compaction-style` - -+ Compaction 方法，可选值为 level，universal。 -+ 默认值：level - -### `disable-auto-compactions` - -+ 开启自动 compaction 的开关。 -+ 默认值：false - -### `soft-pending-compaction-bytes-limit` - -+ pending compaction bytes 的软限制。 -+ 默认值：64GB -+ 单位：KB|MB|GB - -### `hard-pending-compaction-bytes-limit` - -+ pending compaction bytes 的硬限制。 -+ 默认值：256GB -+ 单位：KB|MB|GB - -## rocksdb.defaultcf.titan - -rocksdb defaultcf titan 相关的配置项。 - -### `min-blob-size` - -+ 最小存储在 Blob 文件中 value 大小，低于该值的 value 还是存在 LSM-Tree 中。 -+ 默认值：1KB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `blob-file-compression` - -+ Blob 文件所使用的压缩算法，可选值：no, snappy, zlib, bzip2, lz4, lz4hc, zstd。 -+ 默认值：lz4 - -### `blob-cache-size` - -+ Blob 文件的 cache 大小，默认：0GB。 -+ 默认值：0GB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `min-gc-batch-size` - -+ 做一次 GC 所要求的最低 Blob 文件大小总和。 -+ 默认值：16MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `max-gc-batch-size` - -+ 做一次 GC 所要求的最高 Blob 文件大小总和。 -+ 默认值：64MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `discardable-ratio` - -+ Blob 文件 GC 的触发比例，如果某 Blob 文件中的失效 value 的比例高于该值才可能被 GC 选中。 -+ 默认值：0.5 -+ 最小值：0 -+ 最大值：1 - -### `sample-ratio` - -+ 进行 GC 时，对 Blob 文件进行采样时读取数据占整个文件的比例。 -+ 默认值：0.1 -+ 最小值：0 -+ 最大值：1 - -### `merge-small-file-threshold` - -+ Blob 文件的大小小于该值时，无视 discardable-ratio 仍可能被 GC 选中。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：KB|MB|GB - -## rocksdb.writecf - -rocksdb writecf 相关的配置项。 - -### `block-cache-size` - -+ block cache size。 -+ 默认值：机器总内存 * 15% -+ 单位：MB|GB - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：false - -### `whole-key-filtering` - -+ 开启将整个 key 放到 bloom filter 中的开关。 -+ 默认值：false - -## rocksdb.lockcf - -rocksdb lockcf 相关配置项。 - -### `block-cache-size` - -+ block cache size。 -+ 默认值：机器总内存 * 2% -+ 单位：MB|GB - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：false - -### `level0-file-num-compaction-trigger` - -+ 触发 compaction 的 L0 文件个数。 -+ 默认值：1 - -## raftdb - -raftdb 相关配置项。 - -### `max-background-jobs` - -+ RocksDB 后台线程个数。 -+ 默认值：2 -+ 最小值：1 - -### `max-sub-compactions` - -+ RocksDB 进行 subcompaction 的并发数。 -+ 默认值：1 -+ 最小值：1 - -### `wal-dir` - -+ WAL 存储目录。 -+ 默认值：/tmp/tikv/store - -## security - -安全相关配置项。 - -### `ca-path` - -+ CA 文件路径 -+ 默认："" - -### `cert-path` - -+ 包含 X509 证书的 PEM 文件路径 -+ 默认："" - -### `key-path` - -+ 包含 X509 key 的 PEM 文件路径 -+ 默认："" - -## import - -import 相关的配置项。 - -### `num-threads` - -+ 处理 RPC 请求线程数。 -+ 默认值：8 -+ 最小值：1 - -### `num-import-jobs` - -+ 并发导入工作任务数。 -+ 默认值：8 -+ 最小值：1 - -## pessimistic-txn - -### `enabled` - -+ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/v3.0/reference/transactions/transaction-pessimistic.md)。 -+ 默认值：true - -### `wait-for-lock-timeout` - -+ 悲观事务在 TiKV 中等待其他事务释放锁的最长时间，单位为毫秒。若超时则会返回错误给 TiDB 并由 TiDB 重试加锁，语句最长等锁时间由 `innodb_lock_wait_timeout` 控制。 -+ 默认值：1000 -+ 最小值：1 - -### `wait-up-delay-duration` - -+ 悲观事务释放锁时，只会唤醒等锁事务中 start ts 最小的事务，其他事务将会延迟 `wake-up-delay-duration` 毫秒之后被唤醒。 -+ 默认值：20 diff --git a/v3.0/reference/configuration/tikv-server/configuration.md b/v3.0/reference/configuration/tikv-server/configuration.md deleted file mode 100644 index d2eaddea9046..000000000000 --- a/v3.0/reference/configuration/tikv-server/configuration.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: TiKV 配置参数 -category: reference -aliases: ['/docs-cn/op-guide/tikv-configuration/'] ---- - -# TiKV 配置参数 - -TiKV 的命令行参数支持一些可读性好的单位转换。 - -+ 文件大小（以 bytes 为单位）：KB, MB, GB, TB, PB（也可以全小写） -+ 时间（以毫秒为单位）：ms, s, m, h - -## `-A, --addr` - -+ TiKV 监听地址 -+ 默认："127.0.0.1:20160" -+ 如果部署一个集群，\-\-addr 必须指定当前主机的 IP 地址，例如 "192.168.100.113:20160"，如果是运行在 docker 则需要指定为 "0.0.0.0:20160" - -## `--advertise-addr` - -+ TiKV 对外访问地址。 -+ 默认：${addr} -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，客户端并不能通过 TiKV 自己监听的地址来访问到 TiKV，这时候，你就可以设置 advertise addr 来让 客户端访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 -p 20160:20160，那么可以设置为 \-\-advertise-addr="192.168.100.113:20160"，客户端可以通过 192.168.100.113:20160 来找到这个服务 - -## `-C, --config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiKV 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，TiKV 就会使用命令行参数的配置来覆盖配置文件里面的 - -## `--capacity` - -+ TiKV 存储数据的容量 -+ 默认：0 (无限) -+ PD 需要使用这个值来对整个集群做 balance 操作。（提示：你可以使用 10GB 来替代 10737418240，从而简化参数的传递） - -## `--data-dir` - -+ TiKV 数据存储路径 -+ 默认："/tmp/tikv/store" - -## `-L, --log` - -+ Log 级别 -+ 默认："info" -+ 我们能选择 trace, debug, info, warn, error, 或者 off - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果没设置这个参数，log 会默认输出到 "stderr"，如果设置了，log 就会输出到对应的文件里面，在每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--pd` - -+ PD 地址列表。 -+ 默认："" -+ TiKV 必须使用这个值连接 PD，才能正常工作。使用逗号来分隔多个 PD 地址，例如： - 192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379 diff --git a/v3.0/reference/error-codes.md b/v3.0/reference/error-codes.md deleted file mode 100644 index cdedbb0c75d6..000000000000 --- a/v3.0/reference/error-codes.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 错误码与故障诊断 -category: reference -aliases: ['/docs-cn/sql/error/'] ---- - -# 错误码与故障诊断 - -本篇文档描述在使用 TiDB 过程中会遇到的问题以及解决方法。 - -## 错误码 - -TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样的错误码。另外还有一些特有的错误码： - -| 错误码 | 说明 | -| --------------------- | -------------------------------------------------- | -| 8001 | 请求使用的内存超过 TiDB 内存使用的阈值限制 | -| 8002 | 带有 `SELECT FOR UPDATE` 语句的事务，在遇到写入冲突时，为保证一致性无法进行重试，事务将进行回滚并返回该错误 | -| 8003 | `ADMIN CHECK TABLE` 命令在遇到行数据跟索引不一致的时候返回该错误 | -| 8004 | 单个事务过大，原因及解决方法请参考[这里](/v3.0/faq/tidb.md#433-transaction-too-large-是什么原因怎么解决) | -| 8005 | 事务在 TiDB 中遇到了写入冲突，原因及解决方法请参考[这里](/v3.0/faq/tidb.md#九故障排除) | -| 9001 | 请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络 | -| 9002 | 请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络 | -| 9003 | TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志 | -| 9004 | 当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码 | -| 9005 | 某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志 | -| 9006 | GC Life Time 间隔时间过短，长事务本应读到的数据可能被清理了，应增加 GC Life Time | -| 9007 | 事务在 TiKV 中遇到了写入冲突，原因及解决方法请参考[这里](/v3.0/faq/tidb.md#九故障排除) | - -## 故障诊断 - -参见[故障诊断文档](/v3.0/how-to/troubleshoot/cluster-setup.md)以及 [FAQ](/v3.0/faq/tidb.md)。 diff --git a/v3.0/reference/garbage-collection/configuration.md b/v3.0/reference/garbage-collection/configuration.md deleted file mode 100644 index c5692a2a9b3a..000000000000 --- a/v3.0/reference/garbage-collection/configuration.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: GC 配置 -category: reference ---- - -# GC 配置 - -TiDB 的 GC 相关的配置存储于 `mysql.tidb` 系统表中，可以通过 SQL 语句对这些参数进行查询和更改： - -{{< copyable "sql" >}} - -```sql -select VARIABLE_NAME, VARIABLE_VALUE from mysql.tidb; -``` - -``` -+--------------------------+----------------------------------------------------------------------------------------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+--------------------------+----------------------------------------------------------------------------------------------------+ -| bootstrapped | True | -| tidb_server_version | 33 | -| system_tz | UTC | -| tikv_gc_leader_uuid | 5afd54a0ea40005 | -| tikv_gc_leader_desc | host:tidb-cluster-tidb-0, pid:215, start at 2019-07-15 11:09:14.029668932 +0000 UTC m=+0.463731223 | -| tikv_gc_leader_lease | 20190715-12:12:14 +0000 | -| tikv_gc_enable | true | -| tikv_gc_run_interval | 10m0s | -| tikv_gc_life_time | 10m0s | -| tikv_gc_last_run_time | 20190715-12:09:14 +0000 | -| tikv_gc_safe_point | 20190715-11:59:14 +0000 | -| tikv_gc_auto_concurrency | true | -| tikv_gc_mode | distributed | -+--------------------------+----------------------------------------------------------------------------------------------------+ -13 rows in set (0.00 sec) -``` - -例如，如果需要将 GC 调整为保留最近一天以内的数据，只需执行下列语句即可： - -{{< copyable "sql" >}} - -```sql -update mysql.tidb set VARIABLE_VALUE="24h" where VARIABLE_NAME="tikv_gc_life_time"; -``` - -> **注意：** -> -> `mysql.tidb` 系统表中除了下文将要列出的 GC 的配置以外，还包含一些 TiDB 用于储存部分集群状态（包括 GC 状态）的记录。请勿手动更改这些记录。其中，与 GC 有关的记录如下： -> -> - `tikv_gc_leader_uuid`，`tikv_gc_leader_desc` 和 `tikv_gc_leader_lease` 用于记录 GC leader 的状态 -> - `tikv_gc_last_run_time`：上次 GC 运行时间 -> - `tikv_gc_safe_point`：当前 GC 的 safe point - -## `tikv_gc_enable` - -- 控制是否启用 GC。 -- 默认值：`true` - -## `tikv_gc_run_interval` - -- 指定 GC 运行时间间隔。Duration 类型，使用 Go 的 Duration 字符串格式，如 `"1h30m"`，`"15m"` 等。 -- 默认值：`"10m0s"` - -## `tikv_gc_life_time` - -- 每次 GC 时，保留数据的时限。Duration 类型。每次 GC 时将以当前时间减去该配置的值作为 safe point。 -- 默认值：`"10m0s"` - -> **注意：** -> -> - `tikv_gc_life_time` 的值必须大于 TiDB 的配置文件中的 [`max-txn-time-use`](/v3.0/reference/configuration/tidb-server/configuration-file.md#max-txn-time-use) 的值至少 10 秒，且不低于 10 分钟。 -> -> - 在数据更新频繁的场景下，如果将 `tikv_gc_life_time` 设置得比较大（如数天甚至数月），可能会有一些潜在的问题，如： -> - 磁盘空间占用较多。 -> - 大量的历史版本会在一定程度上影响性能，尤其是范围查询（如 `select count(*) from t`）。 - -## `tikv_gc_mode` - -指定 GC 模式。可选值如下： - -- `"distributed"`（默认）：分布式 GC 模式。在此模式下，[Do GC](/v3.0/reference/garbage-collection/overview.md#do-gc) 阶段由 TiDB 上的 GC leader 向 PD 发送 safe point，每个 TiKV 节点各自获取该 safe point 并对所有当前节点上作为 leader 的 Region 进行 GC。此模式于 TiDB 3.0 引入。 - -- `"central"`：集中 GC 模式。在此模式下，[Do GC](/v3.0/reference/garbage-collection/overview.md#do-gc) 阶段由 GC leader 向所有的 Region 发送 GC 请求。TiDB 2.1 及更早版本采用此 GC 模式。 - -## `tikv_gc_auto_concurrency` - -控制是否由 TiDB 自动决定 GC concurrency，即同时进行 GC 的线程数。 - -当 `tikv_gc_mode` 设为 `"distributed"`，GC concurrency 将应用于 [Resolve Locks](/v3.0/reference/garbage-collection/overview.md#resolve-locks) 阶段。当 [`tikv_gc_mode`](#tikv_gc_mode) 设为 `"central"` 时，GC concurrency 将应用于 Resolve Locks 以及 [Do GC](/v3.0/reference/garbage-collection/overview.md#do-gc) 两个阶段。 - -- `true`（默认）：自动以 TiKV 节点的个数作为 GC concurrency -- `false`：使用 [`tikv_gc_concurrency`](#tikv_gc_concurrency) 的值作为 GC 并发数 - -## `tikv_gc_concurrency` - -- 手动设置 GC concurrency。要使用该参数，必须将 [`tikv_gc_auto_concurrency`](#tikv_gc_auto_concurrency) 设为 `false` 。 -- 默认值：2 - -## 关于 GC 流程的说明 - -从 TiDB 3.0 版本起，由于对分布式 GC 模式和并行 Resolve Locks 的支持，部分配置选项的作用发生了变化。可根据下表理解不同版本中这些配置的区别： - -| 版本/配置 | Resolve Locks | Do GC | -|-------------------|---------------|----------------| -| 2.x | 串行 | 并行 | -| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = false` | 并行 | 并行 | -| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = true` | 自动并行 | 自动并行 | -| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = false` | 并行 | 分布式 | -| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = true`
（默认配置） | 自动并行 | 分布式 | - -表格内容说明： - -- 串行：由 TiDB 逐个向 Region 发送请求。 -- 并行：使用 `tikv_gc_concurrency` 选项所指定的线程数，并行地向每个 Region 发送请求。 -- 自动并行：使用 TiKV 节点的个数作为线程数，并行地向每个 Region 发送请求。 -- 分布式：无需 TiDB 通过对 TiKV 发送请求的方式来驱动，而是每台 TiKV 自行工作。 - -## 流控 - -TiKV 在 3.0.6 版本开始支持 GC 流控，可通过配置 `gc.max-write-bytes-per-sec` 限制 GC worker 每秒数据写入量，降低对正常请求的影响，`0` 为关闭该功能。该配置可通过 tikv-ctl 动态修改： - -{{< copyable "shell-regular" >}} - -```bash -tikv-ctl --host=ip:port modify-tikv-config -m server -n gc.max_write_bytes_per_sec -v 10MB -``` diff --git a/v3.0/reference/garbage-collection/overview.md b/v3.0/reference/garbage-collection/overview.md deleted file mode 100644 index 8b21bf450919..000000000000 --- a/v3.0/reference/garbage-collection/overview.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: GC 机制简介 -category: reference -aliases: ['/docs-cn/op-guide/gc/'] ---- - -# GC 机制简介 - -TiDB 的事务的实现采用了 MVCC（多版本并发控制）机制，当新写入的数据覆盖旧的数据时，旧的数据不会被替换掉，而是与新写入的数据同时保留，并以时间戳来区分版本。GC 的任务便是清理不再需要的旧数据。 - -## 整体流程 - -一个 TiDB 集群中会有一个 TiDB 实例被选举为 GC leader，GC 的运行由 GC leader 来控制。 - -GC 会被定期触发，默认情况下每 10 分钟一次。每次 GC 时，首先，TiDB 会计算一个称为 safe point 的时间戳（默认为当前时间减去 10 分钟），接下来 TiDB 会在保证 safe point 之后的快照全部拥有正确数据的前提下，删除更早的过期数据。具体而言，分为以下三个步骤： - -1. Resolve Locks -2. Delete Ranges -3. Do GC - -### Resolve Locks - -TiDB 的事务是基于 [Google Percolator](https://ai.google/research/pubs/pub36726) 模型实现的，事务的提交是一个两阶段提交的过程。第一阶段完成时，所有涉及的 key 会加上一个锁，其中一个锁会被设定为 Primary，其余的锁（Secondary）则会指向 Primary；第二阶段会将 Primary 锁所在的 key 加上一个 Write 记录，并去除锁。这里的 Write 记录就是历史上对该 key 进行写入或删除，或者该 key 上发生事务回滚的记录。Primary 锁被替换为何种 Write 记录标志着该事务提交成功与否。接下来，所有 Secondary 锁也会被依次替换。如果替换这些 Secondary 锁的线程死掉了，锁就残留了下来。 - -Resolve Locks 这一步的任务即对 safe point 之前的锁进行回滚或提交，取决于其 Primary 是否被提交。如果一个 Primary 锁也残留了下来，那么该事务应当视为超时并进行回滚。这一步是必不可少的，因为如果其 Primary 的 Write 记录由于太老而被 GC 清除掉了，那么就再也无法知道该事务是否成功。如果该事务存在残留的 Secondary 锁，那么也无法知道它应当被回滚还是提交，也就无法保证一致性。 - -Resolve Locks 的执行方式是由 GC leader 对所有的 Region 发送请求进行处理。从 3.0 起，这个过程默认会并行地执行，并发数量默认与 TiKV 节点个数相同。 - -## Delete Ranges - -在执行 `DROP TABLE/INDEX` 等操作时，会有大量连续的数据被删除。如果对每个 key 都进行删除操作、再对每个 key 进行 GC 的话，那么执行效率和空间回收速度都可能非常的低下。事实上，这种时候 TiDB 并不会对每个 key 进行删除操作，而是将这些待删除的区间及删除操作的时间戳记录下来。Delete Ranges 会将这些时间戳在 safe point 之前的区间进行快速的物理删除。 - -## Do GC - -这一步即删除所有 key 的过期版本。为了保证 safe point 之后的任何时间戳都具有一致的快照，这一步删除 safe point 之前提交的数据，但是会保留 safe point 前的最后一次写入（除非最后一次写入是删除）。 - -TiDB 2.1 及更早版本使用的 GC 方式是由 GC leader 向所有 Region 发送 GC 请求。从 3.0 起，GC leader 只需将 safe point 上传至 PD。每个 TiKV 节点都会各自从 PD 获取 safe point。当 TiKV 发现 safe point 发生更新时，便会对当前节点上所有作为 leader 的 Region 进行 GC。与此同时，GC leader 可以继续触发下一轮 GC。 - -> **注意：** -> -> 通过修改配置可以继续使用旧的 GC 方式，详情请参考 [GC 配置](/v3.0/reference/garbage-collection/configuration.md)。 diff --git a/v3.0/reference/key-monitoring-metrics/overview-dashboard.md b/v3.0/reference/key-monitoring-metrics/overview-dashboard.md deleted file mode 100644 index 356f0a91570a..000000000000 --- a/v3.0/reference/key-monitoring-metrics/overview-dashboard.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Overview 面板重要监控指标详解 -category: reference -aliases: ['/docs-cn/op-guide/dashboard-overview-info/'] ---- - -# Overview 面板重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.0/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们单独挑选出重要的 Metrics 放在 Overview 页面，方便日常运维人员观察集群组件 (PD, TiDB, TiKV) 使用状态以及集群使用状态。 - -以下为 Overview Dashboard 监控说明： - -## Services Port Status - -- Services Online：各服务在线节点数量 -- Services Offline：各服务 Down 掉节点数量 - -## PD - -- Storage Capacity：TiDB 集群总可用数据库空间大小 -- Current Storage Size：TiDB 集群目前已用数据库空间大小 -- Number of Regions：当前集群的 Region 总量 -- Leader Balance Ratio：Leader 数量最多和最少节点相差的百分比，一般小于 5%，节点重启时会有比较大的波动 -- Region Balance Ratio：Region 数量最多和最少节点相差的百分比，一般小于 5%，新增/下线节点时相差比较大 -- Store Status：集群 TiKV 节点的状态 - - Up Stores：正常运行的 TiKV 节点数量 - - Disconnect Stores：短时间内通信异常的 TiKV 节点数量 - - LowSpace Stores：剩余可用空间小于 20% 的 TiKV 节点数量 - - Down Stores：停止工作的 TiKV 节点数量，如果大于 0，说明有节点不正常 - - Offline Stores：正在下线的 TiKV 节点数量（正在下线的 TiKV 节点还在提供服务） - - Tombstone Stores：下线成功的 TiKV 节点数量 -- 99% completed\_cmds\_duration\_seconds：单位时间内，99% 的 pd-server 请求执行时间小于监控曲线的值，一般 <= 5ms -- handle\_requests\_duration\_seconds：PD 发送请求的网络耗时 - -## TiDB - -- Statement OPS：SQL 执行数量统计（包含 select、insert、update 等） -- Duration：SQL 执行的时间 -- QPS By Instance：每个 TiDB 上的 QPS -- Failed Query OPM：失败 SQL 的统计，例如语法错误、主键冲突等 -- Connection count：每个 TiDB 的连接数 -- Heap Memory Usage：每个 TiDB 使用的堆内存大小 -- Transaction OPS：事务执行数量统计 -- Transaction Duration：事务执行的时间 -- KV Cmd OPS：KV 命令执行数量统计 -- KV Cmd Duration 99：KV 命令执行的时间 -- PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 -- PD TSO Wait Duration：TiDB 从 PD 获取 TS 的时间 -- TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 -- Lock Resolve OPS：事务冲突相关的数量 -- Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 -- KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - -## TiKV - -- leader：各个 TiKV 节点上 Leader 的数量分布 -- region：各个 TiKV 节点上 Region 的数量分布 -- CPU：各个 TiKV 节点的 CPU 使用率 -- Memory：各个 TiKV 节点的内存使用量 -- store size：各个 TiKV 节点存储的数据量 -- cf size：集群不同 CF 存储的数据量 -- channel full：正常情况显示 No data，如果有了监控值，说明对应 TiKV 节点的消息处理不过来了 -- server report failures：正常情况显示 No data，如果出现了 Unreachable，说明 TiKV 之间通信有问题 -- scheduler pending commands：写入堆积的数量，偶尔出现峰值属于正常现象 -- coprocessor pending requests：正常情况监控为 0 或者数量很少 -- coprocessor executor count：不同类型的查询操作数量 -- coprocessor request duration：TiKV 中查询消耗的时间 -- raft store CPU：raftstore 线程的 CPU 使用率，线程数量默认为 2 (通过 `raftstore.store-pool-size` 配置)。如果单个线程使用率超过 80%，说明使用率很高 -- Coprocessor CPU：TiKV 查询线程的 CPU 使用率，和业务相关，复杂查询会使用大量的 CPU 资源 - -## System Info - -- Vcores：CPU 核心数量 -- Memory：内存总大小 -- CPU Usage：CPU 使用率，最大为 100% -- Load [1m]：1 分钟的负载情况 -- Memory Available：剩余内存大小 -- Network Traffic：网卡流量统计 -- TCP Retrans：网络监控，TCP 相关信息统计 -- IO Util：磁盘使用率，最高为 100%，一般到 80% - 90% 就需要考虑加节点 - -## 图例 - -![overview](/media/overview.png) diff --git a/v3.0/reference/key-monitoring-metrics/pd-dashboard.md b/v3.0/reference/key-monitoring-metrics/pd-dashboard.md deleted file mode 100644 index 3386967b2e6c..000000000000 --- a/v3.0/reference/key-monitoring-metrics/pd-dashboard.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: PD 重要监控指标详解 -category: reference -aliases: ['/docs-cn/op-guide/dashboard-pd-info/'] ---- - -# PD 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.0/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 PD 面板上的 Metrics，可以了解 PD 当前的状态。 - -以下为 PD Dashboard 监控说明： - -## Cluster - -- PD role：当前 PD 的角色 -- Storage capacity：TiDB 集群总可用数据库空间大小 -- Current storage size：TiDB 集群目前已用数据库空间大小 -- Current storage usage：TiDB 集群存储空间的使用率 -- Normal stores：处于正常状态的节点数目 -- Number of Regions：当前集群的 Region 总量 -- PD scheduler config：PD 调度配置列表 -- Region label isolation level：不同 label 所在的 level 的 Region 数量 -- Label distribution：集群中 TiKV 节点的 label 分布情况 -- Abnormal stores：处于异常状态的节点数目，正常情况应当为 0 -- pd_cluster_metadata：记录集群 ID，时间戳和生成的 ID -- Current peer count：当前集群 peer 的总量 -- Region health：每个 Region 的状态，通常情况下，pending 的 peer 应该少于 100，miss 的 peer 不能一直大于 0 - -![PD Dashboard - Cluster metrics](/media/pd-dashboard-cluster-v2.png) - -## Operator - -- Schedule operator create：新创建的不同 operator 的数量 -- Schedule operator check：已检查的 operator 的数量，主要检查是否当前步骤已经执行完成，如果是，则执行下一个步骤 -- Schedule operator finish：已完成调度的 operator 的数量 -- Schedule operator timeout：已超时的 operator 的数量 -- Schedule operator replaced or canceled：已取消或者被替换的 operator 的数量 -- Schedule operators count by state：不同状态的 operator 的数量 -- 99% Operator finish duration：99% 已完成 operator 所花费的最长时间 -- 50% Operator finish duration：50% 已完成 operator 所花费的最长时间 -- 99% Operator step duration：99% 已完成的 operator 步骤所花费的最长时间 -- 50% Operator step duration：50% 已完成的 operator 步骤所花费的最长时间 - -![PD Dashboard - Operator metrics](/media/pd-dashboard-operator-v2.png) - -## Statistics - Balance - -- Store capacity：每个 TiKV 实例的总的空间大小 -- Store available：每个 TiKV 实例的可用空间大小 -- Store used：每个 TiKV 实例的已使用空间大小 -- Size amplification：每个 TiKV 实例的空间放大比率 -- Size available ratio：每个 TiKV 实例的可用空间比率 -- Store leader score：每个 TiKV 实例的 leader 分数 -- Store Region score：每个 TiKV 实例的 Region 分数 -- Store leader size：每个 TiKV 实例上所有 leader 的大小 -- Store Region size：每个 TiKV 实例上所有 Region 的大小 -- Store leader count：每个 TiKV 实例上所有 leader 的数量 -- Store Region count：每个 TiKV 实例上所有 Region 的数量 - -![PD Dashboard - Balance metrics](/media/pd-dashboard-balance-v2.png) - -## Statistics - hotspot - -- Hot write Region's leader distribution：每个 TiKV 实例上是写入热点的 leader 的数量 -- Hot write Region's peer distribution：每个 TiKV 实例上是写入热点的 peer 的数量 -- Hot write Region's leader written bytes：每个 TiKV 实例上热点的 leader 的写入大小 -- Hot write Region's peer written bytes：每个 TiKV 实例上热点的 peer 的写入大小 -- Hot read Region's leader distribution：每个 TiKV 实例上是读取热点的 leader 的数量 -- Hot read Region's peer distribution：每个 TiKV 实例上是读取热点的 peer 的数量 -- Hot read Region's leader read bytes：每个 TiKV 实例上热点的 leader 的读取大小 -- Hot read Region's peer read bytes：每个 TiKV 实例上热点的 peer 的读取字节数 - -![PD Dashboard - Hotspot metrics](/media/pd-dashboard-hotspot.png) - -## Scheduler - -- Scheduler is running：所有正在运行的 scheduler -- Balance leader movement：leader 移动的详细情况 -- Balance Region movement：Region 移动的详细情况 -- Balance leader event：balance leader 的事件数量 -- Balance Region event：balance Region 的事件数量 -- Balance leader scheduler：balance-leader scheduler 的状态 -- Balance Region scheduler：balance-region scheduler 的状态 -- Namespace checker：namespace checker 的状态 -- Replica checker：replica checker 的状态 -- Region merge checker：merge checker 的状态 -- Filter target：尝试选择 Store 作为调度 taget 时没有通过 Filter 的计数 -- Filter source：尝试选择 Store 作为调度 source 时没有通过 Filter 的计数 -- Balance Direction：Store 被选作调度 target 或 source 的次数 -- Store Limit：Store 的调度限流状态 - -![PD Dashboard - Scheduler metrics](/media/pd-dashboard-scheduler-v2.png) - -## gRPC - -- Completed commands rate：gRPC 命令的完成速率 -- 99% Completed commands duration：99% 命令的最长消耗时间 - -![PD Dashboard - gRPC metrics](/media/pd-dashboard-grpc-v2.png) - -## etcd - -- Handle transactions count：etcd 的事务个数 -- 99% Handle transactions duration：99% 的情况下，处理 etcd 事务所需花费的时间 -- 99% WAL fsync duration：99% 的情况下，持久化 WAL 所需花费的时间，这个值通常应该小于 1s -- 99% Peer round trip time seconds：99% 的情况下，etcd 的网络延时，这个值通常应该小于 1s -- etcd disk WAL fsync rate：etcd 持久化 WAL 的速率 -- Raft term：当前 Raft 的 term -- Raft committed index：最后一次 commit 的 Raft index -- Raft applied index：最后一次 apply 的 Raft index - -![PD Dashboard - etcd metrics](/media/pd-dashboard-etcd-v2.png) - -## TiDB - -- Handle requests count：TiDB 的请求数量 -- Handle requests duration：每个请求所花费的时间，99% 的情况下，应该小于 100ms - -![PD Dashboard - TiDB metrics](/media/pd-dashboard-tidb-v2.png) - -## Heartbeat - -- Region heartbeat report：TiKV 向 PD 发送的心跳个数 -- Region heartbeat report error：TiKV 向 PD 发送的异常的心跳个数 -- Region heartbeat report active：TiKV 向 PD 发送的正常的心跳个数 -- Region schedule push：PD 向 TiKV 发送的调度命令的个数 -- 99% Region heartbeat latency：99% 的情况下，心跳的延迟 - -![PD Dashboard - Heartbeat metrics](/media/pd-dashboard-heartbeat-v2.png) - -## Region storage - -- Syncer Index：Leader 记录 Region 变更历史的最大 index -- history last index：Follower 成功同步的 Region 变更历史的 index - -![PD Dashboard - Region storage](/media/pd-dashboard-region-storage.png) diff --git a/v3.0/reference/key-monitoring-metrics/tidb-dashboard.md b/v3.0/reference/key-monitoring-metrics/tidb-dashboard.md deleted file mode 100644 index 061280a983ce..000000000000 --- a/v3.0/reference/key-monitoring-metrics/tidb-dashboard.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: TiDB 重要监控指标详解 -category: reference ---- - -# TiDB 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.0/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等，TiDB 分为 TiDB 和 TiDB Summary 面板（其中 TiDB 面板包含 TiDB Summary 面板的内容）。 - -以下为 TiDB Dashboard 部分监控说明： - -## 说明 - -- Query Summary - - Duration：SQL 执行的时间 - - QPS：每个 TiDB 上的 SQL 执行结果按照 OK/Error 统计 - - Statement OPS：SQL 执行数量统计（包含 `SELECT`、`INSERT`、`UPDATE` 等） - - QPS By Instance：每个 TiDB 上的 QPS - - Failed Query OPM：每个 TiDB 实例上，执行 SQL 语句发生错误按照错误类型的统计（例如语法错误、主键冲突等） - - Slow query：慢查询处理时间统计（整个慢查询耗时、Coprocessor 耗时、Coprocessor 调度等待时间） - - 999/99/95/80 Duration：不同类型的 SQL 语句执行耗时统计（不同百分位） - -- Query Detail - - Duration 80/95/99/999 By Instance：每个 TiDB 实例执行 SQL 语句的耗时统计（不同百分位） - - Failed Query OPM Detail：整个集群执行 SQL 语句发生的错误按照错误类型统计（例如语法错误、主键冲突等） - - Internal SQL OPS：TiDB 内部 SQL 语句执行数量统计 - -- Server - - Uptime：TiDB 运行时间 - - Memory Usage：不同 TiDB 实例的内存使用统计 - - CPU Usage：不同 TiDB 实例的 CPU 使用统计 - - Connection Count：每个 TiDB 的连接数 - - Open FD Count：不同 TiDB 实例的打开的文件描述符统计 - - Goroutine Count：不同 TiDB 实例的 Goroutine 数量 - - Go GC Duration：不同 TiDB 实例的 GC 耗时统计 - - Go Threads：不同 TiDB 实例的线程数量 - - Go GC Count：不同 TiDB 实例的 GC 执行次数统计 - - Go GC CPU Usage：不同 TiDB 实例的 GC CPU 统计 - - Events OPM：统计关键事件，例如 start，close，graceful-shutdown，kill，hang 等 - - Keep Alive OPM：不同 TiDB 实例每分钟刷新监控的次数 - - Prepare Statement Count：不同 TiDB 实例执行 Prepare 语句数以及总数统计 - - Time Jump Back OPS：不同 TiDB 实例上每秒钟时间回跳的次数 - - Heap Memory Usage：每个 TiDB 使用的堆内存大小 - - Uncommon Error OPM：TiDB 非正常错误的统计，包括 panic，binlog 写失败等 - - Handshake Error OPS：不同 TiDB 实例每秒握手错误的次数统计 - - Get Token Duration：建立连接后获取 Token 耗时 - -- Transaction - - Transaction OPS：事务执行数量统计 - - Duration：事务执行的时间 - - Transaction Retry Num：事务重试次数 - - Transaction Statement Num：一个事务中的 SQL 语句数量 - - Session Retry Error OPS：事务重试时遇到的错误数量 - - Local Latch Wait Duration：本地事务等待时间 - -- Executor - - Parse Duration：SQL 语句解析耗时统计 - - Compile Duration：将 SQL AST 编译成执行计划耗时统计 - - Execution Duration：SQL 语句执行耗时统计 - - Expensive Executor OPS：消耗系统资源比较多的算子统计，包括 Merge Join，Hash Join，Index Look Up Join，Hash Agg，Stream Agg，Sort，TopN 等 - - Queries Using Plan Cache OPS：使用 Plan Cache 的查询数量统计 - -- Distsql - - Distsql Duration：Distsql 处理的时长 - - Distsql QPS：Distsql 的数量统计 - - Distsql Partial QPS：每秒 Partial Results 的数量 - - Scan Keys Num：每个 Query 扫描的 Key 的数量 - - Scan Keys Partial Num：每一个 Partial Result 扫描的 Key 的数量 - - Partial Num：每个 SQL 语句 Partial Results 的数量 - -- KV Errors - - KV Retry Duration：KV 重试请求的时间 - - TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 - - KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - - Lock Resolve OPS：事务冲突相关的数量 - - Other Errors OPS：其他类型的错误数量，包括清锁和更新 SafePoint - -- KV Duration - - KV Request Duration 999 by store：KV Request 执行时间，根据 TiKV 显示 - - KV Request Duration 999 by type：KV Request 执行时间，根据请求类型显示 - - KV Cmd Duration 99/999：KV 命令执行的时间 - -- KV Count - - KV Cmd OPS：KV 命令执行数量统计 - - KV Txn OPS：启动事务的数量统计 - - Txn Regions Num 90：事务使用的 Region 数量统计 - - Txn Write Size Bytes 100：事务写入的字节数统计 - - Txn Write KV Num 100：事务写入的 KV 数量统计 - - Load SafePoint OPS：更新 SafePoint 的数量统计 - -- PD Client - - PD Client CMD OPS：PD Client 执行命令数量统计 - - PD Client CMD Duration: PD Client 执行命令耗时 - - PD Client CMD Fail OPS：PD Client 执行命令失败统计 - - PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 - - PD TSO Wait Duration：TiDB 从 PD 获取 TSO 的时间 - - PD TSO RPC Duration：TiDB 从调用 PD 获取 TSO gRPC 接口花费的时间 - -- Schema Load - - Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 - - Load Schema OPS：TiDB 从 TiKV 获取 Schema 的数量统计 - - Schema Lease Error OPM：Schema Lease 出错，包括 change 和 outdate 两种，出现 outdate 错误时会报警 - -- DDL - - DDL Duration 95：DDL 语句处理时间统计 - - Batch Add Index Duration 100：创建索引时每个 Batch 所花费的时间统计 - - DDL Waiting Jobs Count：等待的 DDL 任务数量 - - DDL META OPM：DDL 每分钟获取 META 的次数 - - Deploy Syncer Duration：Schema Version Syncer 初始化，重启，清空等操作耗时 - - Owner Handle Syncer Duration：DDL Owner 在执行更新，获取以及检查 Schema Version 的耗时 - - Update Self Version Duration：Schema Version Syncer 更新版本信息耗时 - -- Statistics - - Auto Analyze Duration 95：自动 ANALYZE 耗时统计 - - Auto Analyze QPS：自动 ANALYZE 数量统计 - - Stats Inaccuracy Rate：统计信息不准确度统计 - - Pseudo Estimation OPS：使用假的统计信息优化 SQL 的数量统计 - - Dump Feedback OPS：存储统计信息 Feedback 的数量统计 - - Update Stats OPS：利用 Feedback 更新统计信息的数量统计 - - Significant Feedback：重要的 Feedback 更新统计信息的数量统计 - -- Meta - - AutoID QPS：AutoID 相关操作的数量统计，包括全局 ID 分配、单个 Table AutoID 分配、单个 Table AutoID Rebase 三种操作 - - AutoID Duration：AutoID 相关操作的耗时 - - Meta Operations Duration 99：Meta 操作延迟 - -- GC - - Worker Action OPM：GC 相关操作的数量统计，包括 run\_job，resolve\_lock，delete\_range 等操作 - - Duration 99：GC 相关操作的耗时统计 - - GC Failure OPM：GC 相关操作失败数量统计 - - Action Result OPM：GC 相关操作结果数量统计 - - Too Many Locks Error OPM：GC 清锁过多错误的数量统计 - -- Batch Client - - Pending Request Count by TiKV：等待处理的 Batch 消息数量统计 - - Wait Duration 95：等待处理的 Batch 消息延迟统计 - - Batch Client Unavailable Duration 95：Batch 客户端不可用的时间统计 diff --git a/v3.0/reference/key-monitoring-metrics/tikv-dashboard.md b/v3.0/reference/key-monitoring-metrics/tikv-dashboard.md deleted file mode 100644 index b413a70a3886..000000000000 --- a/v3.0/reference/key-monitoring-metrics/tikv-dashboard.md +++ /dev/null @@ -1,430 +0,0 @@ ---- -title: TiKV 重要监控指标详解 -category: reference -aliases: ['/docs-cn/op-guide/dashboard-tikv-info/'] ---- - -# TiKV 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.0/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 TiKV 面板上的 Metrics，可以了解 TiKV 当前的状态。 - -以下为 TiKV Dashboard 监控说明： - -## Cluster - -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Available size：每个 TiKV 实例的可用的存储空间的大小 -- Capacity size：每个 TiKV 实例的存储容量的大小 -- CPU：每个 TiKV 实例 CPU 的使用率 -- Memory：每个 TiKV 实例内存的使用情况 -- IO utilization：每个 TiKV 实例 IO 的使用率 -- MBps：每个 TiKV 实例写入和读取的数据量大小 -- QPS：每个 TiKV 实例上各种命令的 QPS -- Errps：每个 TiKV 实例上 gRPC 消息失败的个数 -- leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 - -![TiKV Dashboard - Cluster metrics](/media/tikv-dashboard-cluster.png) - -## Errors - -- Server is busy：各种会导致 server 繁忙的事件个数，如 write stall，channel full 等，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Raftstore error：每个 TiKV 实例上 raftstore 发生错误的个数 -- Scheduler error：每个 TiKV 实例上 scheduler 发生错误的个数 -- Coprocessor error：每个 TiKV 实例上 coprocessor 发生错误的个数 -- gRPC message error：每个 TiKV 实例上 gRPC 消息发生错误的个数 -- Leader drop：每个 TiKV 实例上 drop leader 的个数 -- Leader missing：每个 TiKV 实例上 missing leader 的个数 - -![TiKV Dashboard - Errors metrics](/media/tikv-dashboard-errors.png) - -## Server - -- Leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 -- CF size：每个 CF 的大小 -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Channel full：每个 TiKV 实例上 channel full 错误的数量，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Region average written keys：每个 TiKV 实例上所有 Region 的平均 key 写入个数 -- Region average written bytes：每个 TiKV 实例上所有 Region 的平均写入大小 -- Active written leaders：每个 TiKV 实例上有效的 leader 个数 -- Approximate Region size：每个 Region 近似的大小 - -![TiKV Dashboard - Server metrics](/media/tikv-dashboard-server.png) - -## Raft IO - -- Apply log duration：Raft apply 日志所花费的时间 -- Apply log duration per server：每个 TiKV 实例上 Raft apply 日志所花费的时间 -- Append log duration：Raft append 日志所花费的时间 -- Append log duration per server：每个 TiKV 实例上 Raft append 日志所花费的时间 - -![TiKV Dashboard - Raft IO metrics](/media/tikv-dashboard-raftio.png) - -## Raft process - -- Ready handled：Raft 中不同 ready 类型的个数 -- Process ready duration per server：每个 TiKV 实例处理 ready 所花费的时间，99.99% 的情况下，应该小于 2s -- Process tick duration per server：每个 TiKV 实例处理 tick 所花费的时间 -- 0.99 Duration of Raft store events：99% 的 raftstore 事件所花费的时间 - -![TiKV Dashboard - Raft process metrics](/media/tikv-dashboard-raft-process.png) - -## Raft message - -- Sent messages per server：每个 TiKV 实例发送 Raft 消息的个数 -- Flush messages per server：每个 TiKV 实例持久化 Raft 消息的个数 -- Receive messages per server：每个 TiKV 实例接受 Raft 消息的个数 -- Messages：发送不同类型的 Raft 消息的个数 -- Vote：Raft 投票消息发送的个数 -- Raft dropped messages：丢弃不同类型的 Raft 消息的个数 - -![TiKV Dashboard - Raft message metrics](/media/tikv-dashboard-raft-message.png) - -## Raft propose - -- Raft proposals per ready：在一个 mio tick 内，所有 Region proposal 的个数 -- Raft read/write proposals：不同类型的 proposal 的个数 -- Raft read proposals per server：每个 TiKV 实例发起读 proposal 的个数 -- Raft write proposals per server：每个 TiKV 实例发起写 proposal 的个数 -- Propose wait duration：每个 proposal 的等待时间 -- Propose wait duration per server：每个 TiKV 实例上每个 proposal 的等待时间 -- Raft log speed：peer propose 日志的速度 - -![TiKV Dashboard - Raft propose metrics](/media/tikv-dashboard-raft-propose.png) - -## Raft admin - -- Admin proposals：admin proposal 的个数 -- Admin apply：apply 命令的个数 -- Check split：split check 命令的个数 -- 99.99% Check split duration：99.99% 的情况下，split check 所需花费的时间 - -![TiKV Dashboard - Raft admin metrics](/media/tikv-dashboard-raft-admin.png) - -## Local reader - -- Local reader requests：所有请求的总数以及 local read 线程拒绝的请求数量 -- Local read requests duration：local read 请求的等待时间 -- Local read requests batch size：local read 请求的批量大小 - -![TiKV Dashboard - Local reader metrics](/media/tikv-dashboard-local-reader.png) - -## Storage - -- Storage command total：收到不同命令的个数 -- Storage async request error：异步请求出错的个数 -- Storage async snapshot duration：异步处理 snapshot 所花费的时间，99% 的情况下，应该小于 1s -- Storage async write duration：异步写所花费的时间，99% 的情况下，应该小于 1s - -![TiKV Dashboard - Storage metrics](/media/tikv-dashboard-storage.png) - -## Scheduler - -- Scheduler stage total：每种命令不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler priority commands：不同优先级命令的个数 -- Scheduler pending commands：每个 TiKV 实例上 pending 命令的个数 - -![TiKV Dashboard - Scheduler metrics](/media/tikv-dashboard-scheduler.png) - -## Scheduler - batch_get - -- Scheduler stage total：batch_get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 batch_get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：batch_get 命令读取 key 的个数 -- Scheduler keys written：batch_get 命令写入 key 的个数 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 batch_get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 batch_get 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - batch_get metrics](/media/tikv-dashboard-scheduler-batch-get.png) - -## Scheduler - cleanup - -- Scheduler stage total：cleanup 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 cleanup 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：cleanup 命令读取 key 的个数 -- Scheduler keys written：cleanup 命令写入 key 的个数 -- Scheduler scan details：执行 cleanup 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 cleanup 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 cleanup 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 cleanup 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - cleanup metrics](/media/tikv-dashboard-scheduler-cleanup.png) - -## Scheduler - commit - -- Scheduler stage total：commit 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 commit 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：commit 命令读取 key 的个数 -- Scheduler keys written：commit 命令写入 key 的个数 -- Scheduler scan details：执行 commit 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 commit 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 commit 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 commit 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler commit metrics](/media/tikv-dashboard-scheduler-commit.png) - -## Scheduler - gc - -- Scheduler stage total：gc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 gc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：gc 命令读取 key 的个数 -- Scheduler keys written：gc 命令写入 key 的个数 -- Scheduler scan details：执行 gc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 gc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 gc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 gc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - get - -- Scheduler stage total：get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：get 命令读取 key 的个数 -- Scheduler keys written：get 命令写入 key 的个数 -- Scheduler scan details：执行 get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 get 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - key_mvcc - -- Scheduler stage total：key_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 key_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：key_mvcc 命令读取 key 的个数 -- Scheduler keys written：key_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 key_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 key_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 key_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 key_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - prewrite - -- Scheduler stage total：prewrite 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 prewrite 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：prewrite 命令读取 key 的个数 -- Scheduler keys written：prewrite 命令写入 key 的个数 -- Scheduler scan details：执行 prewrite 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 prewrite 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 prewrite 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 prewrite 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - resolve_lock - -- Scheduler stage total：resolve_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 resolve_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：resolve_lock 命令读取 key 的个数 -- Scheduler keys written：resolve_lock 命令写入 key 的个数 -- Scheduler scan details：执行 resolve_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 resolve_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 resolve_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 resolve_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan - -- Scheduler stage total：scan 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan 命令读取 key 的个数 -- Scheduler keys written：scan 命令写入 key 的个数 -- Scheduler scan details：执行 scan 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan_lock - -- Scheduler stage total：scan_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan_lock 命令读取 key 的个数 -- Scheduler keys written：scan_lock 命令写入 key 的个数 -- Scheduler scan details：执行 scan_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - start_ts_mvcc - -- Scheduler stage total：start_ts_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 start_ts_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：start_ts_mvcc 命令读取 key 的个数 -- Scheduler keys written：start_ts_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 start_ts_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 start_ts_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 start_ts_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 start_ts_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - unsafe_destroy_range - -- Scheduler stage total：unsafe_destroy_range 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 unsafe_destroy_range 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：unsafe_destroy_range 命令读取 key 的个数 -- Scheduler keys written：unsafe_destroy_range 命令写入 key 的个数 -- Scheduler scan details：执行 unsafe_destroy_range 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 unsafe_destroy_range 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 unsafe_destroy_range 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 unsafe_destroy_range 命令时，扫描每个 default CF 中 key 的详细情况 - -## Coprocessor - -- Request duration：处理 coprocessor 读请求所花费的时间 -- Wait duration：coprocessor 请求的等待时间，99.99% 的情况下，应该小于 10s -- Handle duration：处理 coprocessor 请求所花费的时间 -- 95% Request duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 读请求所花费的时间 -- 95% Wait duration by store：95% 的情况下，每个 TiKV 实例上 coprocessor 请求的等待时间 -- 95% Handle duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 请求所花费的时间 -- Request errors：下推的请求发生错误的个数，正常情况下，短时间内不应该有大量的错误 -- DAG executors：DAG executor 的个数 -- Scan keys：每个请求 scan key 的个数 -- Scan details：scan 每个 CF 的详细情况 -- Table Scan - Details by CF：table scan 针对每个 CF 的详细情况 -- Index Scan - Details by CF：index scan 针对每个 CF 的详细情况 -- Table Scan - Perf Statistics：执行 table sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 -- Index Scan - Perf Statistics：执行 index sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 - -## GC - -- MVCC versions：每个 key 的版本个数 -- MVCC delete versions：GC 删除掉的每个 key 的版本个数 -- GC tasks：由 gc_worker 处理的 GC 任务的个数 -- GC tasks Duration：执行 GC 任务时所花费的时间 -- GC keys (write CF)：在 GC 过程中，write CF 中 受影响的 key 的个数 -- TiDB GC actions result：TiDB Region 层面的 GC 结果 -- TiDB GC worker actions：TiDB GC worker 的不同 action 的个数 -- TiDB GC seconds：TiDB 执行 GC 花费的时间 -- TiDB GC failure：TiDB GC job 失败的个数 -- GC lifetime：TiDB 设置的 GC lifetime -- GC interval：TiDB 设置的 GC 间隔 - -## Snapshot - -- Rate snapshot message：发送 Raft snapshot 消息的速率 -- 99% Handle snapshot duration：99% 的情况下，处理 snapshot 所需花费的时间 -- Snapshot state count：不同状态的 snapshot 的个数 -- 99.99% Snapshot size：99.99% 的 snapshot 的大小 -- 99.99% Snapshot KV count：99.99% 的 snapshot 包含的 key 的个数 - -## Task - -- Worker handled tasks：worker 处理的任务个数 -- Worker pending tasks：当前 worker 中，pending 和 running 的任务个数，正常情况下，应该小于 1000 -- FuturePool handled tasks：future pool 处理的任务个数 -- FuturePool pending tasks：当前 future pool 中，pending 和 running 的任务个数 - -## Thread CPU - -- Raft store CPU：raftstore 线程的 CPU 使用率，通常应低于 80% -- Async apply CPU：async apply 线程的 CPU 使用率，通常应低于 90% -- Scheduler CPU：scheduler 线程的 CPU 使用率，通常应低于 80% -- Scheduler worker CPU：scheduler worker 线程的 CPU 使用率 -- Storage ReadPool CPU：Readpool 线程的 CPU 使用率 -- Coprocessor CPU：coprocessor 线程的 CPU 使用率 -- Snapshot worker CPU：snapshot worker 线程的 CPU 使用率 -- Split check CPU：split check 线程的 CPU 使用率 -- RocksDB CPU：RocksDB 线程的 CPU 使用率 -- gRPC poll CPU：gRPC 线程的 CPU 使用率，通常应低于 80% - -## RocksDB - kv - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## RocksDB - raft - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## gRPC - -- gRPC message count：每种 gRPC 消息的个数 -- gRPC message failed：失败的 gRPC 消息的个数 -- 99% gRPC message duration：在 99% gRPC 消息的执行时间 -- gRPC GC message count：gRPC GC 消息的个数 -- 99% gRPC KV GC message duration：在 99% 情况下，gRPC GC 消息的执行时间 - -## PD - -- PD requests：TiKV 发送给 PD 的请求个数 -- PD request duration (average)：TiKV 发送给 PD 的请求所需的平均时间 -- PD heartbeats：发送给 PD 的心跳个数 -- PD validate peers：通过 PD 验证 TiKV 的 peer 有效的个数 diff --git a/v3.0/reference/mysql-compatibility.md b/v3.0/reference/mysql-compatibility.md deleted file mode 100644 index 4e7d2f75c90b..000000000000 --- a/v3.0/reference/mysql-compatibility.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: 与 MySQL 兼容性对比 -category: reference ---- - -# 与 MySQL 兼容性对比 - -TiDB 支持 MySQL 传输协议及其绝大多数的语法。这意味着您现有的 MySQL 连接器和客户端都可以继续使用。大多数情况下您现有的应用都可以迁移至 TiDB，无需任何代码修改。 - -当前 TiDB 服务器官方支持的版本为 MySQL 5.7。大部分 MySQL 运维工具（如 PHPMyAdmin, Navicat, MySQL Workbench 等），以及备份恢复工具（如 mysqldump, Mydumper/myloader）等都可以直接使用。 - -不过一些特性由于在分布式环境下没法很好的实现，目前暂时不支持或者是表现与 MySQL 有差异。一些 MySQL 语法在 TiDB 中可以解析通过，但是不会做任何后续的处理，例如 `Create Table` 语句中 `Engine`，是解析并忽略。 - -> **注意：** -> -> 本页内容仅涉及 MySQL 与 TiDB 的总体差异。关于[安全特性](/v3.0/reference/security/compatibility.md)、[悲观事务模型](/v3.0/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)的兼容信息请查看各自具体页面。 - -## 不支持的特性 - -* 存储过程与函数 -* 触发器 -* 事件 -* 自定义函数 -* 外键约束 -* 全文/空间函数与索引 -* 非 `ascii`/`latin1`/`binary`/`utf8`/`utf8mb4` 的字符集 -* `BINARY` 之外的排序规则 -* 增加/删除主键 -* SYS schema -* MySQL 追踪优化器 -* XML 函数 -* X Protocol -* Savepoints -* 列级权限 -* `XA` 语法（TiDB 内部使用两阶段提交，但并没有通过 SQL 接口公开） -* `CREATE TABLE tblName AS SELECT stmt` 语法 -* `CREATE TEMPORARY TABLE` 语法 -* `CHECK TABLE` 语法 -* `CHECKSUM TABLE` 语法 -* `SELECT INTO FILE` 语法 - -## 与 MySQL 有差异的特性 - -### 自增 ID - -TiDB 中，自增列只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配 ID 的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。 - -在集群中有多个 tidb-server 实例时，如果表结构中有自增 ID，建议不要混用缺省值和自定义值，否则在如下情况下会遇到问题。 - -假设有这样一个带有自增 ID 的表： - -{{< copyable "sql" >}} - -```sql -create table t(id int unique key AUTO_INCREMENT, c int); -``` - -TiDB 实现自增 ID 的原理是每个 tidb-server 实例缓存一段 ID 值用于分配（目前会缓存 30000 个 ID），用完这段值再去取下一段。 - -假设集群中有两个 tidb-server 实例 A 和 B（A 缓存 [1,30000] 的自增 ID，B 缓存 [30001,60000] 的自增 ID），依次执行如下操作： - -1. 客户端向 B 插入一条将 `id` 设置为 1 的语句 `insert into t values (1, 1)`，并执行成功。 -2. 客户端向 A 发送 Insert 语句 `insert into t (c) (1)`，这条语句中没有指定 `id` 的值，所以会由 A 分配，当前 A 缓存了 [1, 30000] 这段 ID，所以会分配 1 为自增 ID 的值，并把本地计数器加 1。而此时数据库中已经存在 `id` 为 1 的数据，最终返回 `Duplicated Error` 错误。 - -另外，从 TiDB 3.0.4 版本开始，TiDB 将通过系统变量 `@@tidb_allow_remove_auto_inc` 控制是否允许通过 `alter table modify` 或 `alter table change` 来移除列的 `AUTO_INCREMENT` 属性，默认是不允许移除。 - -### Performance schema - -Performance schema 表在 TiDB 中返回结果为空。TiDB 使用 [Prometheus 和 Grafana](/v3.0/how-to/monitor/monitor-a-cluster.md) 来监测性能指标。 - -从 TiDB 3.0.4 版本开始，TiDB 支持 `events_statements_summary_by_digest`，参见 [Statement Summary Table](/v3.0/reference/performance/statement-summary.md)。 - -### 查询计划 - -TiDB 的查询计划（`EXPLAIN`/`EXPLAIN FOR`）输出格式与 MySQL 差别较大，同时 `EXPLAIN FOR` 的输出内容与权限设置与 MySQL 不一致，参见[理解 TiDB 执行计划](/v3.0/reference/performance/understanding-the-query-execution-plan.md)。 - -### 内建函数 - -TiDB 支持常用的 MySQL 内建函数，但是不是所有的函数都已经支持，具体请参考[语法文档](https://pingcap.github.io/sqlgram/#functioncallkeyword)。 - -### DDL - -在 TiDB 中，运行的 DDL 操作不会影响对表的读取或写入。但是，目前 DDL 变更有如下一些限制： - -+ Add Index - - 不支持同时创建多个索引 - - 不支持 `VISIBLE/INVISIBLE` 的索引 - - 不支持通过 `ALTER TABLE` 在所生成的列上添加索引 - - 其他类型的 Index Type (HASH/BTREE/RTREE) 只有语法支持，功能不支持 -+ Add Column - - 不支持同时创建多个列 - - 不支持将新创建的列设为主键或唯一索引，也不支持将此列设成 AUTO_INCREMENT 属性 -+ Drop Column: 不支持删除主键列或索引列 -+ Change/Modify Column - - 不支持有损变更，比如从 `BIGINT` 变为 `INTEGER`，或者从 `VARCHAR(255)` 变为 `VARCHAR(10)` - - 不支持修改 `DECIMAL` 类型的精度 - - 不支持更改 `UNSIGNED` 属性 - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ Alter Database - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}`: TiDB 支持的语法，但是在 TiDB 中不会生效。所有支持的 DDL 变更都不会锁表。 -+ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}`: TiDB 完全支持 `ALGORITHM=INSTANT` 和 `ALGORITHM=INPLACE` 语法，但运行过程与 MySQL 有所不同，因为 MySQL 中的一些 `INPLACE` 操作实际上是 TiDB 中的 `INSTANT` 操作。`ALGORITHM=COPY` 语法在 TiDB 中不会生效，会返回警告信息。 -+ Table Option 不支持以下语法 - - `WITH/WITHOUT VALIDATION` - - `SECONDARY_LOAD/SECONDARY_UNLOAD` - - `CHECK/DROP CHECK` - - `STATS_AUTO_RECALC/STATS_SAMPLE_PAGES` - - `SECONDARY_ENGINE` - - `ENCRYPTION` -+ Table Partition 不支持以下语法 - - `PARTITION BY LIST` - - `PARTITION BY KEY` - - `SUBPARTITION` - - `{CHECK|EXCHANGE|TRUNCATE|OPTIMIZE|REPAIR|IMPORT|DISCARD|REBUILD|REORGANIZE} PARTITION` - -### `ANALYZE TABLE` - -- [`ANALYZE TABLE`](/v3.0/reference/performance/statistics.md#手动收集) 语句在 TiDB 和 MySQL 中表现不同。在 MySQL/InnoDB 中，它是一个轻量级语句，执行过程较短；而在 TiDB 中，它会完全重构表的统计数据，语句执行过程较长。 - -### 视图 - -目前 TiDB 不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 - -### 存储引擎 - -出于兼容性原因，TiDB 支持使用备用存储引擎创建表的语法。元数据命令将表描述为 InnoDB 存储引擎： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT) ENGINE=MyISAM; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -从架构上讲，TiDB 确实支持类似 MySQL 的存储引擎抽象，在启动 TiDB（通常是 `tikv`）时 [`--store`](/v3.0/reference/configuration/tidb-server/configuration.md#store) 选项指定的引擎中创建用户表。 - -### SQL 模式 - -TiDB 支持 MySQL 5.7 中 **绝大多数的 SQL 模式**，以下几种模式除外： - -- TiDB 不支持兼容模式（例如 `ORACLE` 和 `POSTGRESQL`）。MySQL 5.7 已弃用兼容模式，MySQL 8.0 已移除兼容模式。 -- TiDB 中的 `ONLY_FULL_GROUP_BY` 与 MySQL 5.7 相比有细微的[语义差别](/v3.0/reference/sql/functions-and-operators/aggregate-group-by-functions.md#与-mysql-的区别)，此问题日后将予以解决。 -- `NO_DIR_IN_CREATE` 和 `NO_ENGINE_SUBSTITUTION` 这两种 SQL 模式用于解决兼容问题，但并不适用于 TiDB。 - -### 默认设置的区别 - -+ 默认字符集与 MySQL 不同： - + TiDB 中为 `utf8mb4` - + MySQL 5.7 中为 `latin1`，MySQL 8.0 中修改为 `utf8mb4` -+ 默认排序规则不同： - + TiDB 中，`utf8mb4` 的默认排序规则为 `utf8mb4_bin` - + MySQL 5.7 中，`utf8mb4` 的默认排序规则为 `utf8mb4_general_ci`，MySQL 8.0 中修改为 `utf8mb4_0900_ai_ci` - + 请使用 [`SHOW CHARACTER SET`](/v3.0/reference/sql/statements/show-character-set.md) 语句查看所有字符集的默认排序规则 -+ `foreign_key_checks` 的默认值不同： - + TiDB 中该值默认为 `OFF`，并且目前 TiDB 只支持设置该值为 `OFF`。 - + MySQL 5.7 中该值默认为 `ON`。 -+ 默认 SQL mode 与 MySQL 5.7 相同，与 MySQL 8.0 不同： - + TiDB 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` - + MySQL 中默认设置： - + MySQL 5.7 的默认 SQL mode 与 TiDB 相同 - + MySQL 8.0 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION` -+ `lower_case_table_names` 的默认值不同： - + TiDB 中该值默认为 2，并且目前 TiDB 只支持设置该值为 2 - + MySQL 中默认设置： - + Linux 系统中该值为 0 - + Windows 系统中该值为 1 - + macOS 系统中该值为 2 -+ `explicit_defaults_for_timestamp` 的默认值不同： - + TiDB 中该值默认为 `ON`，并且目前 TiDB 只支持设置该值为 `ON` - + MySQL 中默认设置： - + MySQL 5.7：`OFF` - + MySQL 8.0：`ON` - -### 日期时间处理的区别 - -#### 时区 - -MySQL 默认使用本地时区，依赖于系统内置的当前的时区规则（例如什么时候开始夏令时等）进行计算；且在未[导入时区表数据](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation)的情况下不能通过时区名称来指定时区。 - -TiDB 不需要导入时区表数据也能使用所有时区名称，采用系统当前安装的所有时区规则进行计算（一般为 `tzdata` 包），且无法通过导入时区表数据的形式修改计算规则。 - -> **注意：** -> -> 能下推到 TiKV 的时间相关表达式会由 TiKV 进行计算。TiKV 总是采用 TiKV 内置时区规则计算，而不依赖于系统所安装的时区规则。若系统安装的时区规则与 TiKV 内置的时区规则版本不匹配，则在少数情况下可能发生能插入的时间数据无法再读出来的问题。例如，若系统上安装了 tzdata 2018a 时区规则，则在时区设置为 Asia/Shanghai 或时区设置为本地时区且本地时区为 Asia/Shanghai 的情况下，时间 `1988-04-17 02:00:00` 可以被正常插入 TiDB 3.0 RC.1，但该记录对于特定类型 SQL 则无法再读出来，原因是 TiKV 3.0 RC.1 依据的 tzdata 2018i 规则中该时间在 Asia/Shanghai 时区中不存在（夏令时时间后移一小时）。 -> -> TiKV 各个版本内置的时区规则如下： -> -> - 3.0.0 RC.1 及以后：[tzdata 2018i](https://github.com/eggert/tz/tree/2018i) -> - 2.1.0 RC.1 及以后：[tzdata 2018e](https://github.com/eggert/tz/tree/2018e) - -#### 零月和零日 - -目前 TiDB 尚不能完整支持月为 `0` 或日为 `0`（但年不为 `0`）的日期。在非严格模式下，此类日期时间能被正常插入。但对于特定类型的 SQL 语句，可能出现无法读出来的情况。 - -#### 字符串类型行末空格的处理 - -目前 TiDB 在进行数据插入时，对于 `VARCHAR` 类型会保留行末空格，对于 `CHAR` 类型会插入截断空格后的数据。在没有索引的情况下，TiDB 和 MySQL 行为保持一致。如果 `VARCHAR` 类型上有 `UNIQUE` 索引，MySQL 在判断是否重复的时候，和处理 `CHAR` 类型一样，先截断 `VARCHAR` 数据末行空格再作判断；TiDB 则是按照保留空格的情况处理。 - -在做比较时，MySQL 会先截去常量和 Column 的末尾空格再作比较，而 TiDB 则是保留常量和 Column 的末尾空格来做精确比较。 - -### 类型系统的区别 - -以下的列类型 MySQL 支持，但 TiDB 不支持： - -+ FLOAT4/FLOAT8 -+ FIXED (alias for DECIMAL) -+ SERIAL (alias for BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE) -+ SQL_TSI_* （包括 SQL_TSI_YEAR、SQL_TSI_MONTH、SQL_TSI_WEEK、SQL_TSI_DAY、SQL_TSI_HOUR、SQL_TSI_MINUTE 和 SQL_TSI_SECOND） diff --git a/v3.0/reference/performance/check-cluster-status-using-sql-statements.md b/v3.0/reference/performance/check-cluster-status-using-sql-statements.md deleted file mode 100644 index cf0017647e54..000000000000 --- a/v3.0/reference/performance/check-cluster-status-using-sql-statements.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 使用 SQL 语句检查 TiDB 集群状态 -category: reference ---- - -# 使用 SQL 语句检查 TiDB 集群状态 - -为了方便排查问题，TiDB 提供了一些 SQL 语句和系统表以查询一些有用的信息。 - -`INFORMATION\_SCHEMA` 中提供了如下几个系统表，用于查询集群状态，诊断常见的集群问题。 - -- [`TABLES`](/v3.0/reference/system-databases/information-schema.md#tables-表) -- [`TIDB_INDEXES`](/v3.0/reference/system-databases/information-schema.md#tidb_indexes-表) -- [`ANALYZE_STATUS`](/v3.0/reference/system-databases/information-schema.md#analyze_status-表) -- [`TIDB_HOT_REGIONS`](/v3.0/reference/system-databases/information-schema.md#tidb_hot_regions-表) -- [`TIKV_STORE_STATUS`](/v3.0/reference/system-databases/information-schema.md#tikv_store_status-表) -- [`TIKV_REGION_STATUS`](/v3.0/reference/system-databases/information-schema.md#tikv_region_status-表) -- [`TIKV_REGION_PEERS`](/v3.0/reference/system-databases/information-schema.md#tikv_region_peers-表) - -除此之外，执行下列语句也可获得对排查问题或查询集群状态有用的信息： - -- `ADMIN SHOW DDL` 可以获得是 `DDL owner` 角色的 TiDB 的 ID 及 `IP:PORT` 等具体信息。 -- `SHOW ANALYZE STATUS` 和 [`ANALYZE_STATUS`](/v3.0/reference/system-databases/information-schema.md#analyze_status-表) 表的功能相同。 -- 特殊的 `EXPLAIN` 语句： - - `EXPLAIN ANALYZE` 语句可以获得一个 SQL 语句执行中的一些具体信息。 - - `EXPLAIN FOR CONNECTION` 可以获得一个连接中最后执行的查询的执行计划。可以配合 `SHOW PROCESSLIST` 使用。 - - 关于 `EXPLAIN` 相关的更具体的信息，参考文档[理解 TiDB 执行计划](/v3.0/reference/performance/understanding-the-query-execution-plan.md)。 \ No newline at end of file diff --git a/v3.0/reference/performance/execution-plan-bind.md b/v3.0/reference/performance/execution-plan-bind.md deleted file mode 100644 index 8c22b278d7ba..000000000000 --- a/v3.0/reference/performance/execution-plan-bind.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 执行计划绑定 -category: reference ---- - -# 执行计划绑定 - -在[优化器 Hints](/v3.0/reference/performance/optimizer-hints.md) 中介绍了可以通过 Hint 的方式选择指定的执行计划，但有的时候需要在不修改 SQL 语句的情况下干预执行计划的选择。执行计划绑定提供了一系列功能使得可以在不修改 SQL 语句的情况下选择指定的执行计划。 - -## 语法 - -### 创建绑定 - -{{< copyable "sql" >}} - -```sql -CREATE [GLOBAL | SESSION] BINDING FOR SelectStmt USING SelectStmt; -``` - -该语句可以在 GLOBAL 或者 SESSION 作用域内为 SQL 绑定执行计划。在不指定作用域时，隐式作用域为 SESSION。被绑定的 SQL 会被参数化后存储到系统表中。在处理 SQL 查询时，只要参数化后的 SQL 和系统表中某个被绑定的 SQL 一致即可使用相应的优化器 Hint。 - -`参数化`：把 SQL 中的常量变成变量参数，并对 SQL 中的空格和换行符等做标准化处理。例如： - -```sql -select * from t where a > 1 --- 参数化后： -select * from t where a > ？ -``` - -需要注意的是原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本必须相同，否则创建会失败，例如： - -{{< copyable "sql" >}} - -```sql -CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE a > 2; -``` - -可以创建成功，因为原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本都是 `select * from t where a > ?`，而 - -{{< copyable "sql" >}} - -```sql -CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE b > 2; -``` - -则不可以创建成功，因为原始 SQL 在经过处理后是 `select * from t where a > ?`，而绑定 SQL 在经过处理后是 `select * from t where b > ?`。 - -### 删除绑定 - -{{< copyable "sql" >}} - -```sql -DROP [GLOBAL | SESSION] BINDING FOR SelectStmt; -``` - -该语句可以在 GLOBAL 或者 SESSION 作用域内删除指定的执行计划绑定，在不指定作用域时默认作用域为 SESSION。 - -### 查看绑定 - -{{< copyable "sql" >}} - -```sql -SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere]; -``` - -该语句会输出 GLOBAL 或者 SESSION 作用域内的执行计划绑定，在不指定作用域时默认作用域为 SESSION。目前 `SHOW BINDINGS` 会输出 8 列，具体如下： - -| 列名 | 说明 | -| -------- | ------------- | -| original_sql | 参数化后的原始 SQL | -| bind_sql | 带 Hint 的绑定 SQL | -| default_db | 默认数据库名 | -| status | 状态，包括 using（正在使用）、deleted（已删除）和 invalid（无效） | -| create_time | 创建时间 | -| update_time | 更新时间 | -| charset | 字符集 | -| collation | 排序规则 | diff --git a/v3.0/reference/performance/optimizer-hints.md b/v3.0/reference/performance/optimizer-hints.md deleted file mode 100644 index dc60224e0da3..000000000000 --- a/v3.0/reference/performance/optimizer-hints.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Optimizer Hints -category: reference -aliases: ['/docs-cn/sql/optimizer-hints/'] ---- - -# Optimizer Hints - -TiDB 支持 Optimizer Hints 语法，它基于 MySQL 5.7 中介绍的类似 comment 的语法，例如 `/*+ TIDB_XX(t1, t2) */`。当 TiDB 优化器选择的不是最优查询计划时，建议使用 Optimizer Hints。 - -> **注意：** -> -> MySQL 命令行客户端在 5.7.7 版本之前默认清除了 Optimizer Hints。如果需要在这些早期版本的客户端中使用 `Hint` 语法，需要在启动客户端时加上 `--comments` 选项，例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。 - -## 语法 - -### TIDB_SMJ(t1, t2) - -{{< copyable "sql" >}} - -```sql -SELECT /*+ TIDB_SMJ(t1, t2) */ * from t1，t2 where t1.id = t2.id; -``` - -提示优化器使用 Sort Merge Join 算法，这个算法通常会占用更少的内存，但执行时间会更久。 -当数据量太大，或系统内存不足时，建议尝试使用。 - -### TIDB_INLJ(t1, t2) - -{{< copyable "sql" >}} - -```sql -SELECT /*+ TIDB_INLJ(t1, t2) */ * from t1，t2 where t1.id = t2.id; -``` - -提示优化器使用 Index Nested Loop Join 算法，这个算法可能会在某些场景更快，消耗更少系统资源，有的场景会更慢，消耗更多系统资源。对于外表经过 WHERE 条件过滤后结果集较小（小于 1 万行）的场景，可以尝试使用。`TIDB_INLJ()` 中的参数是建立查询计划时，内表的候选表。即 `TIDB_INLJ(t1)` 只会考虑使用 t1 作为内表构建查询计划。 - -### TIDB_HJ(t1, t2) - -{{< copyable "sql" >}} - -```sql -SELECT /*+ TIDB_HJ(t1, t2) */ * from t1，t2 where t1.id = t2.id; -``` - -提示优化器使用 Hash Join 算法，这个算法多线程并发执行，执行速度较快，但会消耗较多内存。 - -### MAX\_EXECUTION\_TIME(N) - -在 `SELECT` 语句中可以使用 `MAX_EXECUTION_TIME(N)`，它会限制语句的执行时间不能超过 `N` 毫秒，否则服务器会终止这条语句的执行。 - -例如，下面例子设置了 1 秒超时： - -{{< copyable "sql" >}} - -```sql -SELECT /*+ MAX_EXECUTION_TIME(1000) */ * FROM t1 INNER JOIN t2 WHERE ...; -``` - -除了 hint 之外，环境变量 `max_execution_time` 也会对语句执行时间进行限制。 diff --git a/v3.0/reference/performance/sql-optimizer-overview.md b/v3.0/reference/performance/sql-optimizer-overview.md deleted file mode 100644 index 5a27b760a8ca..000000000000 --- a/v3.0/reference/performance/sql-optimizer-overview.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: SQL 优化流程简介 -category: reference -aliases: ['/docs-cn/sql/sql-optimizer-overview/'] ---- - -# SQL 优化流程简介 - -在 TiDB 中，SQL 优化过程分为逻辑优化和物理优化两个阶段。 - -## 逻辑优化简介 - -逻辑优化是基于规则的优化，对输入的逻辑执行计划按顺序应用一些优化规则，从而使整个逻辑执行计划变得更好。这些优化规则包括： - -- 列裁剪 -- 投影消除 -- 关联子查询去关联 -- Max/Min 消除 -- 谓词下推 -- 分区裁剪 -- TopN 和 Limit 下推 - -## 物理优化简介 - -物理优化是基于代价的优化，为上一阶段产生的逻辑执行计划制定物理执行计划。这一阶段中，优化器会为逻辑执行计划中的每个算子选择具体的物理实现。逻辑算子的不同物理实现有着不同的时间复杂度、资源消耗和物理属性等。在这个过程中，优化器会根据数据的统计信息来确定不同物理实现的代价，并选择整体代价最小的物理执行计划。 - -逻辑执行计划是一个树形结构，每个节点对应 SQL 中的一个逻辑算子。同样的，物理执行计划也是一个树形结构，每个节点对应 SQL 中的一个物理算子。逻辑算子只描述这个算子的功能，而物理算子则描述了完成这个功能的具体算法。对于同一个逻辑算子，可能有多个物理算子实现，比如 `LogicalAggregate`，它的实现可以是采用哈希算法的 `HashAggregate`，也可以是流式的 `StreamAggregate`。不同的物理算子具有不同的物理属性，也对其子节点有着不同的物理属性的要求。物理属性包括数据的顺序和分布等。TiDB 中现在只考虑了数据的顺序。 diff --git a/v3.0/reference/performance/statement-summary.md b/v3.0/reference/performance/statement-summary.md deleted file mode 100644 index 4dec2a67f211..000000000000 --- a/v3.0/reference/performance/statement-summary.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: Statement Summary Tables -category: reference ---- - -# Statement Summary Tables - -针对 SQL 性能相关的问题，MySQL 在 `performance_schema` 提供了 [statement summary tables](https://dev.mysql.com/doc/refman/5.6/en/statement-summary-tables.html)，用来监控和统计 SQL。例如其中的一张表 `events_statements_summary_by_digest`，提供了丰富的字段，包括延迟、执行次数、扫描行数、全表扫描次数等，有助于用户定位 SQL 问题。 - -为此，从 3.0.4 版本开始，TiDB 也提供系统表 `events_statements_summary_by_digest`，从 3.0.8 开始提供系统表 `events_statements_summary_by_digest_history`。本文将详细介绍这两张表，以及如何利用它们来排查 SQL 性能问题。 - -## `events_statements_summary_by_digest` - -`events_statements_summary_by_digest` 是 `performance_schema` 里的一张系统表，它把 SQL 按 SQL digest 和 plan digest 分组，统计每一组的 SQL 信息。 - -此处的 SQL digest 与 slow log 里的 SQL digest 一样，是把 SQL 规一化后算出的唯一标识符。SQL 的规一化会忽略常量、空白符、大小写的差别。即语法一致的 SQL 语句，其 digest 也相同。 - -例如： - -```sql -SELECT * FROM employee WHERE id IN (1, 2, 3) AND salary BETWEEN 1000 AND 2000; -select * from EMPLOYEE where ID in (4, 5) and SALARY between 3000 and 4000; -``` - -规一化后都是： - -```sql -select * from employee where id in (...) and salary between ? and ?; -``` - -此处的 plan digest 是把执行计划规一化后算出的唯一标识符。执行计划的规一化会忽略常量的差别。由于相同的 SQL 可能产生不同的执行计划，所以可能分到多个组，同一个组内的执行计划是相同的。 - -`events_statements_summary_by_digest` 用于保存 SQL 监控指标聚合后的结果。一般来说，每一项监控指标都包含平均值和最大值。例如执行延时对应 `AVG_LATENCY` 和 `MAX_LATENCY` 两个字段，分别是平均延时和最大延时。 - -为了监控指标的即时性，`events_statements_summary_by_digest` 里的数据定期被清空，只展现最近一段时间内的聚合结果。清空周期由系统变量 `tidb_stmt_summary_refresh_interval` 设置。如果刚好在清空之后进行查询，显示的数据可能很少。 - -因为 TiDB 中的很多概念不同于 MySQL，所以 TiDB 中 `events_statements_summary_by_digest` 的表结构与 MySQL 中的有很大区别。 - -以下为查询 `events_statements_summary_by_digest` 的部分结果： - -``` - SUMMARY_BEGIN_TIME: 2020-01-02 11:00:00 - SUMMARY_END_TIME: 2020-01-02 11:30:00 - STMT_TYPE: select - SCHEMA_NAME: test - DIGEST: 0611cc2fe792f8c146cc97d39b31d9562014cf15f8d41f23a4938ca341f54182 - DIGEST_TEXT: select * from employee where id = ? - TABLE_NAMES: test.employee - INDEX_NAMES: NULL - SAMPLE_USER: root - EXEC_COUNT: 3 - SUM_LATENCY: 1035161 - MAX_LATENCY: 399594 - MIN_LATENCY: 301353 - AVG_LATENCY: 345053 - AVG_PARSE_LATENCY: 57000 - MAX_PARSE_LATENCY: 57000 - AVG_COMPILE_LATENCY: 175458 - MAX_COMPILE_LATENCY: 175458 - ........... - AVG_MEM: 103 - MAX_MEM: 103 - AVG_AFFECTED_ROWS: 0 - FIRST_SEEN: 2020-01-02 11:12:54 - LAST_SEEN: 2020-01-02 11:25:24 - QUERY_SAMPLE_TEXT: select * from employee where id=3100 - PREV_SAMPLE_TEXT: - PLAN_DIGEST: f415b8d52640b535b9b12a9c148a8630d2c6d59e419aad29397842e32e8e5de3 - PLAN: Point_Get_1 root 1 table:employee, handle:3100 -``` - -> **注意：** -> -> 在 TiDB 中，statement summary tables 中字段的时间单位是纳秒 (ns)，而 MySQL 中的时间单位是皮秒 (ps)。 - -### 表的字段介绍 - -SQL 的基础信息： - -- `STMT_TYPE`：SQL 语句的类型 -- `SCHEMA_NAME`：执行这类 SQL 的当前 schema -- `DIGEST`：这类 SQL 的 digest -- `DIGEST_TEXT`：规一化后的 SQL -- `QUERY_SAMPLE_TEXT`：这类 SQL 的原 SQL 语句，多条语句只取其中一条 -- `TABLE_NAMES`：SQL 中涉及的所有表，多张表用 `,` 分隔 -- `INDEX_NAMES`：SQL 中使用的索引名，多个索引用 `,` 分隔 -- `SAMPLE_USER`：执行这类 SQL 的用户名，多个用户名只取其中一个 -- `PLAN_DIGEST`：执行计划的 digest -- `PLAN`：原执行计划，多条语句只取其中一条的执行计划 - -执行时间相关的信息： - -- `SUMMARY_BEGIN_TIME`：当前统计的时间段的开始时间 -- `SUMMARY_END_TIME`：当前统计的时间段的结束时间 -- `FIRST_SEEN`：这类 SQL 的首次出现时间 -- `LAST_SEEN`：这类 SQL 的最后一次出现时间 - -在 TiDB server 上的执行数据： - -- `EXEC_COUNT`：这类 SQL 的总执行次数 -- `SUM_LATENCY`：这类 SQL 的总延时 -- `MAX_LATENCY`：这类 SQL 的最大延时 -- `MIN_LATENCY`：这类 SQL 的最小延时 -- `AVG_LATENCY`：这类 SQL 的平均延时 -- `AVG_PARSE_LATENCY`：解析器的平均延时 -- `MAX_PARSE_LATENCY`：解析器的最大延时 -- `AVG_COMPILE_LATENCY`：优化器的平均延时 -- `MAX_COMPILE_LATENCY`：优化器的最大延时 -- `AVG_MEM`：使用的平均内存，单位 byte -- `MAX_MEM`：使用的最大内存，单位 byte - -和 TiKV Coprocessor Task 相关的字段： - -- `COP_TASK_NUM`：每条 SQL 发送的 Coprocessor 请求数量 -- `AVG_COP_PROCESS_TIME`：cop-task 的平均处理时间 -- `MAX_COP_PROCESS_TIME`：cop-task 的最大处理时间 -- `MAX_COP_PROCESS_ADDRESS`：执行时间最长的 cop-task 所在地址 -- `AVG_COP_WAIT_TIME`：cop-task 的平均等待时间 -- `MAX_COP_WAIT_TIME`：cop-task 的最大等待时间 -- `MAX_COP_WAIT_ADDRESS`：等待时间最长的 cop-task 所在地址 -- `AVG_PROCESS_TIME`：SQL 在 TiKV 的平均处理时间 -- `MAX_PROCESS_TIME`：SQL 在 TiKV 的最大处理时间 -- `AVG_WAIT_TIME`：SQL 在 TiKV 的平均等待时间 -- `MAX_WAIT_TIME`：SQL 在 TiKV 的最大等待时间 -- `AVG_BACKOFF_TIME`：SQL 遇到需要重试的错误时在重试前的平均等待时间 -- `MAX_BACKOFF_TIME`：SQL 遇到需要重试的错误时在重试前的最大等待时间 -- `AVG_TOTAL_KEYS`：Coprocessor 扫过的 key 的平均数量 -- `MAX_TOTAL_KEYS`：Coprocessor 扫过的 key 的最大数量 -- `AVG_PROCESSED_KEYS`：Coprocessor 处理的 key 的平均数量。相比 `avg_total_keys`，`avg_processed_keys` 不包含 MVCC 的旧版本。如果 `avg_total_keys` 和 `avg_processed_keys` 相差很大，说明旧版本比较多 -- `MAX_PROCESSED_KEYS`：Coprocessor 处理的 key 的最大数量 - -和事务相关的字段： - -- `AVG_PREWRITE_TIME`：prewrite 阶段消耗的平均时间 -- `MAX_PREWRITE_TIME` prewrite 阶段消耗的最大时间 -- `AVG_COMMIT_TIME`：commit 阶段消耗的平均时间 -- `MAX_COMMIT_TIME`：commit 阶段消耗的最大时间 -- `AVG_GET_COMMIT_TS_TIME`：获取 commit_ts 的平均时间 -- `MAX_GET_COMMIT_TS_TIME`：获取 commit_ts 的最大时间 -- `AVG_COMMIT_BACKOFF_TIME`：commit 时遇到需要重试的错误时在重试前的平均等待时间 -- `MAX_COMMIT_BACKOFF_TIME`：commit 时遇到需要重试的错误时在重试前的最大等待时间 -- `AVG_RESOLVE_LOCK_TIME`：解决事务的锁冲突的平均时间 -- `MAX_RESOLVE_LOCK_TIME`：解决事务的锁冲突的最大时间 -- `AVG_LOCAL_LATCH_WAIT_TIME`：本地事务等待的平均时间 -- `MAX_LOCAL_LATCH_WAIT_TIME`：本地事务等待的最大时间 -- `AVG_WRITE_KEYS`：写入 key 的平均数量 -- `MAX_WRITE_KEYS`：写入 key 的最大数量 -- `AVG_WRITE_SIZE`：写入的平均数据量，单位 byte -- `MAX_WRITE_SIZE`：写入的最大数据量，单位 byte -- `AVG_PREWRITE_REGIONS`：prewrite 涉及的平均 Region 数量 -- `MAX_PREWRITE_REGIONS`：prewrite 涉及的最大 Region 数量 -- `AVG_TXN_RETRY`：事务平均重试次数 -- `MAX_TXN_RETRY`：事务最大重试次数 -- `SUM_BACKOFF_TIMES`：这类 SQL 遇到需要重试的错误后的总重试次数 -- `BACKOFF_TYPES`：遇到需要重试的错误时的所有错误类型及每种类型重试的次数，格式为 `类型:次数`。如有多种错误则用 `,` 分隔，例如 `txnLock:2,pdRPC:1` -- `AVG_AFFECTED_ROWS`：平均影响行数 -- `PREV_SAMPLE_TEXT`：当 SQL 是 `COMMIT` 时，该字段为 `COMMIT` 的前一条语句；否则该字段为空字符串。当 SQL 是 `COMMIT` 时，按 digest 和 `prev_sample_text` 一起分组，即不同 `prev_sample_text` 的 `COMMIT` 也会分到不同的行 - -## `events_statements_summary_by_digest_history` - -`events_statements_summary_by_digest_history` 的表结构与 `events_statements_summary_by_digest` 完全相同，用于保存历史时间段的数据。通过历史数据，可以排查过去出现的异常，也可以对比不同时间的监控指标。 - -字段 `SUMMARY_BEGIN_TIME` 和 `SUMMARY_END_TIME` 代表历史时间段的开始时间和结束时间。 - -## 排查示例 - -下面用两个示例问题演示如何利用 statement summary 来排查。 - -### SQL 延迟比较大，是不是服务端的问题？ - -例如客户端显示 employee 表的点查比较慢，那么可以按 SQL 文本来模糊查询： - -```sql -SELECT avg_latency, exec_count, query_sample_text - FROM performance_schema.events_statements_summary_by_digest - WHERE digest_text LIKE 'select * from employee%'; -``` - -结果如下，`avg_latency` 是 1 ms 和 0.3 ms，在正常范围，所以可以判定不是服务端的问题，继而排查客户端或网络问题。 - -``` -+-------------+------------+------------------------------------------+ -| avg_latency | exec_count | query_sample_text | -+-------------+------------+------------------------------------------+ -| 1042040 | 2 | select * from employee where name='eric' | -| 345053 | 3 | select * from employee where id=3100 | -+-------------+------------+------------------------------------------+ -2 rows in set (0.00 sec) -``` - -### 哪类 SQL 的总耗时最高？ - -假如上午 10:00 到 10:30 的 QPS 明显下降，可以从历史表中找出当时耗时最高的三类 SQL： - -```sql -SELECT sum_latency, avg_latency, exec_count, query_sample_text - FROM performance_schema.events_statements_summary_by_digest_history - WHERE summary_begin_time='2020-01-02 10:00:00' - ORDER BY sum_latency DESC LIMIT 3; -``` - -结果显示以下三类 SQL 的总延迟最高，所以这些 SQL 需要重点优化。 - -``` -+-------------+-------------+------------+-----------------------------------------------------------------------+ -| sum_latency | avg_latency | exec_count | query_sample_text | -+-------------+-------------+------------+-----------------------------------------------------------------------+ -| 7855660 | 1122237 | 7 | select avg(salary) from employee where company_id=2013 | -| 7241960 | 1448392 | 5 | select * from employee join company on employee.company_id=company.id | -| 2084081 | 1042040 | 2 | select * from employee where name='eric' | -+-------------+-------------+------------+-----------------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -## 参数配置 - -statement summary 功能默认关闭，通过设置系统变量打开，例如： - -```sql -set global tidb_enable_stmt_summary = true; -``` - -statement summary 关闭后，系统表里的数据会被清空，下次打开后重新统计。经测试，打开后对性能几乎没有影响。 - -还有两个控制 statement summary 的系统变量： - -- `tidb_stmt_summary_refresh_interval`：`events_statements_summary_by_digest` 的清空周期，单位是秒 (s)，默认值是 `1800`。 -- `tidb_stmt_summary_history_size`：`events_statements_summary_by_digest_history` 保存每种 SQL 的历史的数量，默认值是 `24`。 - -statement summary 配置示例如下： - -```sql -set global tidb_stmt_summary_refresh_interval = 1800; -set global tidb_stmt_summary_history_size = 24; -``` - -以上配置生效后，`events_statements_summary_by_digest` 每 30 分钟清空一次，`events_statements_summary_by_digest_history` 保存最近 12 小时的历史数据。 - -以上两个系统变量都有 global 和 session 两种作用域，它们的生效方式与其他系统变量不一样： - -- 设置 global 变量后整个集群立即生效 -- 设置 session 变量后当前 TiDB server 立即生效，这对于调试单个 TiDB server 比较有用 -- 优先读 session 变量，没有设置过 session 变量才会读 global 变量 -- 把 session 变量设为空字符串，将会重新读 global 变量 - -由于 statement summary tables 是内存表，为了防止内存问题，需要限制保存的 SQL 条数和 SQL 的最大显示长度。这两个参数都在 config.toml 的 `[stmt-summary]` 类别下配置： - -- 通过 `max-stmt-count` 更改保存的 SQL 种类数量，默认 200 条。当 SQL 种类超过 `max-stmt-count` 时，会移除最近没有使用的 SQL。 -- 通过 `max-sql-length` 更改 `DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 的最大显示长度，默认是 4096。 - -> **注意：** -> -> `tidb_stmt_summary_history_size`、`max-stmt-count`、`max-sql-length` 这些配置都影响内存占用，建议根据实际情况调整，不宜设置得过大。 - -## 目前的限制 - -Statement summary tables 现在还存在一些限制： - -- 查询 statement summary tables 时，只会显示当前 TiDB server 的 statement summary，而不是整个集群的 statement summary。 -- TiDB server 重启后 statement summary 会丢失。因为 statement summary tables 是内存表，不会持久化数据，所以一旦 server 被重启，statement summary 随之丢失。 diff --git a/v3.0/reference/performance/statistics.md b/v3.0/reference/performance/statistics.md deleted file mode 100644 index a583200355ef..000000000000 --- a/v3.0/reference/performance/statistics.md +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: 统计信息简介 -category: reference -aliases: ['/docs-cn/sql/statistics/'] ---- - -# 统计信息简介 - -TiDB 优化器会根据统计信息来选择最优的执行计划。统计信息收集了表级别和列级别的信息，表的统计信息包括总行数和修改的行数。列的统计信息包括不同值的数量、NULL 的数量、直方图、列上出现次数最多的值 TOPN 以及该列的 Count-Min Sketch 信息。 - -## 统计信息的收集 - -### 手动收集 - -可以通过执行 `ANALYZE` 语句来收集统计信息。 - -#### 全量收集 - -> **注意：** -> -> 在 TiDB 中执行 `ANALYZE TABLE` 语句比在 MySQL 或 InnoDB 中耗时更长。InnoDB 采样的只是少量页面，但 TiDB 会完全重构一系列统计信息。适用于 MySQL 的脚本会误以为执行 `ANALYZE TABLE` 耗时较短。 -> -> 如需更快的分析速度，可将 `tidb_enable_fast_analyze` 设置为 `1` 来打开快速分析功能。该参数的默认值为 `0`。 -> -> 快速分析功能开启后，TiDB 会随机采样约 10000 行的数据来构建统计信息。因此在数据分布不均匀或者数据量比较少的情况下，统计信息的准确度会比较差。可能导致执行计划不优，比如选错索引。如果可以接受普通 `ANALYZE` 语句的执行时间，则推荐关闭快速分析功能。 - -可以通过以下几种语法进行全量收集。 - -收集 TableNameList 中所有表的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableNameList [WITH NUM BUCKETS]; -``` - -WITH NUM BUCKETS 可以用来指定生成直方图的桶数量上限。 - -收集 TableName 中所有的 IndexNameList 中的索引列的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableName INDEX [IndexNameList] [WITH NUM BUCKETS]; -``` - -IndexNameList 为空时会收集所有索引列的统计信息。 - -收集 TableName 中所有的 PartitionNameList 中分区的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableName PARTITION PartitionNameList [WITH NUM BUCKETS]; -``` - -收集 TableName 中所有的 PartitionNameList 中分区的索引列统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableName PARTITION PartitionNameList [IndexNameList] [WITH NUM BUCKETS]; -``` - -#### 增量收集 - -对于类似时间列这样的单调不减列，在进行全量收集后，可以使用增量收集来单独分析新增的部分，以提高分析的速度。 - -> **注意：** -> -> 1. 目前只有索引提供了增量收集的功能 -> 2. 使用增量收集时，必须保证表上只有插入操作，且应用方需要保证索引列上新插入的值是单调不减的，否则会导致统计信息不准，影响 TiDB 优化器选择合适的执行计划 - -可以通过以下几种语法进行增量收集。 - -增量收集 TableName 中所有的 IndexNameList 中的索引列的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE INCREMENTAL TABLE TableName INDEX [IndexNameList] [WITH NUM BUCKETS]; -``` - -增量收集 TableName 中所有的 PartitionNameList 中分区的索引列统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE INCREMENTAL TABLE TableName PARTITION PartitionNameList INDEX [IndexNameList] [WITH NUM BUCKETS]; -``` - -### 自动更新 - -在发生增加，删除以及修改语句时，TiDB 会自动更新表的总行数以及修改的行数。这些信息会定期持久化下来， -更新的周期是 20 * `stats-lease`，`stats-lease` 的默认值是 3s，如果将其指定为 0，那么将不会自动更新。 - -和统计信息自动更新相关的三个系统变量如下： - -| 系统变量名 | 默认值 | 功能 | -|---|---|---| -| `tidb_auto_analyze_ratio`| 0.5 | 自动更新阈值 | -| `tidb_auto_analyze_start_time` | `00:00 +0000` | 一天中能够进行自动更新的开始时间 | -| `tidb_auto_analyze_end_time` | `23:59 +0000` | 一天中能够进行自动更新的结束时间 | - -当某个表 `tbl` 的修改行数与总行数的比值大于 `tidb_auto_analyze_ratio`，并且当前时间在 `tidb_auto_analyze_start_time` 和 `tidb_auto_analyze_end_time` 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句自动更新这个表的统计信息。 - -在查询语句执行时，TiDB 会以 `feedback-probability` 的概率收集反馈信息，并将其用于更新直方图和 Count-Min Sketch。`feedback-probability` 可通过配置文件修改，其默认值是 `0.0`。 - -### 控制 ANALYZE 并发度 - -执行 ANALYZE 语句的时候，你可以通过一些参数来调整并发度，以控制对系统的影响。 - -#### tidb_build_stats_concurrency - -目前 ANALYZE 执行的时候会被切分成一个个小的任务，每个任务只负责某一个列或者索引。`tidb_build_stats_concurrency` 可以控制同时执行的任务的数量，其默认值是 4。 - -#### tidb_distsql_scan_concurrency - -在执行分析普通列任务的时候，`tidb_distsql_scan_concurrency` 可以用于控制一次读取的 Region 数量，其默认值是 15。 - -#### tidb_index_serial_scan_concurrency - -在执行分析索引列任务的时候，`tidb_index_serial_scan_concurrency` 可以用于控制一次读取的 Region 数量，其默认值是 1。 - -### 查看 ANALYZE 状态 - -在执行 `ANALYZE` 时，可以通过 SQL 语句来查看当前 `ANALYZE` 的状态。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW ANALYZE STATUS [ShowLikeOrWhere]; -``` - -该语句会输出 `ANALYZE` 的状态，可以通过使用 `ShowLikeOrWhere` 来筛选需要的信息。 - -目前 `SHOW ANALYZE STATUS` 会输出 7 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| table_schema | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| job_info | 任务具体信息。如果分析索引则会包含索引名 | -| row_count | 已经分析的行数 | -| start_time | 任务开始执行的时间 | -| state | 任务状态，包括 pending（等待）、running（正在执行）、finished（执行成功）和 failed（执行失败）| - -## 统计信息的查看 - -你可以通过一些语句来查看统计信息的状态。 - -### 表的元信息 - -你可以通过 `SHOW STATS_META` 来查看表的总行数以及修改的行数等信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_META [ShowLikeOrWhere]; -``` - -该语句会输出所有表的总行数以及修改行数等信息，你可以通过 ShowLikeOrWhere 来筛选需要的信息。 - -目前 `SHOW STATS_META` 会输出 6 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| update_time | 更新时间 | -| modify_count | 修改的行数 | -| row_count | 总行数 | - -> **注意：** -> -> 在 TiDB 根据 DML 语句自动更新总行数以及修改的行数时，`update_time` 也会被更新，因此并不能认为 `update_time` 是最近一次发生 Analyze 的时间。 - -### 表的健康度信息 - -通过 `SHOW STATS_HEALTHY` 可以查看表的统计信息健康度，并粗略估计表上统计信息的准确度。当 `modify_count` >= `row_count` 时，健康度为 0；当 `modify_count` < `row_count` 时，健康度为 (1 - `modify_count`/`row_count`) * 100。 - -通过以下命令来查看表的统计信息健康度，你可以通过 `ShowLikeOrWhere` 来筛选需要的信息： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_HEALTHY [ShowLikeOrWhere]; -``` - -目前，`SHOW STATS_HEALTHY` 会输出 4 列，具体如下： - -| 语法元素 | 说明 | -| :-------- | :------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| healthy | 健康度 | - -### 列的元信息 - -你可以通过 `SHOW STATS_HISTOGRAMS` 来查看列的不同值数量以及 NULL 数量等信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_HISTOGRAMS [ShowLikeOrWhere]; -``` - -该语句会输出所有列的不同值数量以及 NULL 数量等信息，你可以通过 ShowLikeOrWhere 来筛选需要的信息。 - -目前 `SHOW STATS_HISTOGRAMS` 会输出 8 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name | 分区名 | -| column_name | 根据 is_index 来变化：is_index 为 0 时是列名，为 1 时是索引名 | -| is_index | 是否是索引列 | -| update_time | 更新时间 | -| distinct_count | 不同值数量 | -| null_count | NULL 的数量 | -| avg_col_size | 列平均长度 | - -### 直方图桶的信息 - -你可以通过 `SHOW STATS_BUCKETS` 来查看直方图每个桶的信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_BUCKETS [ShowLikeOrWhere]; -``` - -该语句会输出所有桶的信息，你可以通过 ShowLikeOrWhere 来筛选需要的信息。 - -目前 `SHOW STATS_BUCKETS` 会输出 10 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name | 分区名 | -| column_name | 根据 is_index 来变化：is_index 为 0 时是列名，为 1 时是索引名 | -| is_index | 是否是索引列 | -| bucket_id | 桶的编号 | -| count | 所有落在这个桶及之前桶中值的数量 | -| repeats | 最大值出现的次数 | -| lower_bound | 最小值 | -| upper_bound | 最大值 | - -## 删除统计信息 - -可以通过执行 `DROP STATS` 语句来删除统计信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -DROP STATS TableName; -``` - -该语句会删除 TableName 中所有的统计信息。 - -## 统计信息的导入导出 - -### 导出统计信息 - -统计信息的导出接口如下。 - -通过以下接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 的 json 格式的统计信息： - -{{< copyable "" >}} - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name} -``` - -通过以下接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 在指定时间上的 json 格式统计信息。指定的时间应在 GC SafePoint 之后。 - -{{< copyable "" >}} - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name}/${yyyyMMddHHmmss} -``` - -通过以下接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 在指定时间上的 json 格式统计信息。指定的时间应在 GC SafePoint 之后。 - -{{< copyable "" >}} - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name}/${yyyy-MM-dd HH:mm:ss} -``` - -### 导入统计信息 - -导入的统计信息一般是通过统计信息导出接口得到的 json 文件。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -LOAD STATS 'file_name'; -``` - -`file_name` 为要导入的统计信息的文件名。 diff --git a/v3.0/reference/performance/tune-tikv.md b/v3.0/reference/performance/tune-tikv.md deleted file mode 100644 index 5d1d06757730..000000000000 --- a/v3.0/reference/performance/tune-tikv.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: TiKV 性能参数调优 -category: reference -aliases: ['/docs-cn/op-guide/tune-tikv/'] ---- - -# TiKV 性能参数调优 - -本文档用于描述如何根据机器配置情况来调整 TiKV 的参数，使 TiKV 的性能达到最优。 - -TiKV 最底层使用的是 RocksDB 做为持久化存储，所以 TiKV 的很多性能相关的参数都是与 RocksDB 相关的。TiKV 使用了两个 RocksDB 实例，默认 RocksDB 实例存储 KV 数据，Raft RocksDB 实例（简称 RaftDB）存储 Raft 数据。 - -TiKV 使用了 RocksDB 的 `Column Families` (CF) 特性。 - -- 默认 RocksDB 实例将 KV 数据存储在内部的 `default`、`write` 和 `lock` 3 个 CF 内。 - - - `default` CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中； - - `write` CF 存储的是数据的版本信息 (MVCC) 以及索引相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中； - - `lock` CF 存储的是锁信息，系统使用默认参数。 - -- Raft RocksDB 实例存储 Raft log。 - - - `default` CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 - -所有的 CF 默认共同使用一个 block cache 实例。通过在 `[storage.block-cache]` 下设置 `capacity` 参数，你可以配置该 block cache 的大小。block cache 越大，能够缓存的热点数据越多，读取数据越容易，同时占用的系统内存也越多。如果要为每个 CF 使用单独的 block cache 实例，需要在 `[storage.block-cache]` 下设置 `shared=false`，并为每个 CF 配置单独的 block cache 大小。例如，可以在 `[rocksdb.writecf]` 下设置 `block-cache-size` 参数来配置 `write` CF 的大小。 - -> **注意：** -> -> 在 TiKV 3.0 之前的版本中，不支持使用 `shared block cache`，需要为每个 CF 单独配置 block cache。 - -每个 CF 有各自的 `write-buffer`，大小通过 `write-buffer-size` 控制。 - -## 参数说明 - -```toml -# 日志级别，可选值为：trace，debug，info，warn，error，off -log-level = "info" - -[server] -# 监听地址 -# addr = "127.0.0.1:20160" - -# gRPC 线程池大小 -# grpc-concurrency = 4 -# TiKV 每个实例之间的 gRPC 连接数 -# grpc-raft-conn-num = 10 - -# TiDB 过来的大部分读请求都会发送到 TiKV 的 Coprocessor 进行处理，该参数用于设置 -# coprocessor 线程的个数，如果业务是读请求比较多，增加 coprocessor 的线程数，但应比系统的 -# CPU 核数小。例如：TiKV 所在的机器有 32 core，在重读的场景下甚至可以将该参数设置为 30。在没有 -# 设置该参数的情况下，TiKV 会自动将该值设置为 CPU 总核数乘以 0.8。 -# end-point-concurrency = 8 - -# 可以给 TiKV 实例打标签，用于副本的调度 -# labels = {zone = "cn-east-1", host = "118", disk = "ssd"} - -[storage] -# 数据目录 -# data-dir = "/tmp/tikv/store" - -# 通常情况下使用默认值就可以了。在导数据的情况下建议将该参数设置为 1024000。 -# scheduler-concurrency = 102400 -# 该参数控制写入线程的个数，当写入操作比较频繁的时候，需要把该参数调大。使用 top -H -p tikv-pid -# 发现名称为 sched-worker-pool 的线程都特别忙，这个时候就需要将 scheduler-worker-pool-size -# 参数调大，增加写线程的个数。 -# scheduler-worker-pool-size = 4 - -[storage.block-cache] -## 是否为 RocksDB 的所有 CF 都创建一个 `shared block cache`。 -## -## RocksDB 使用 block cache 来缓存未压缩的数据块。较大的 block cache 可以加快读取速度。 -## 推荐开启 `shared block cache` 参数。这样只需要设置全部缓存大小，使配置过程更加方便。 -## 在大多数情况下，可以通过 LRU 算法在各 CF 间自动平衡缓存用量。 -## -## `storage.block-cache` 会话中的其余配置仅在开启 `shared block cache` 时起作用。 -# shared = true -## `shared block cache` 的大小。正常情况下应设置为系统全部内存的 30%-50%。 -## 如果未设置该参数，则由以下字段或其默认值的总和决定。 -## -## * rocksdb.defaultcf.block-cache-size 或系统全部内存的 25% -## * rocksdb.writecf.block-cache-size 或系统全部内存的 15% -## * rocksdb.lockcf.block-cache-size 或系统全部内存的 2% -## * raftdb.defaultcf.block-cache-size 或系统全部内存的 2% -## -## 要在单个物理机上部署多个 TiKV 节点，需要显式配置该参数。 -## 否则，TiKV 中可能会出现 OOM 错误。 -# capacity = "1GB" - -[pd] -# pd 的地址 -# endpoints = ["127.0.0.1:2379","127.0.0.2:2379","127.0.0.3:2379"] - -[metric] -# 将 metrics 推送给 Prometheus pushgateway 的时间间隔 -interval = "15s" -# Prometheus pushgateway 的地址 -address = "" -job = "tikv" - -[raftstore] -# 默认为 true，表示强制将数据刷到磁盘上。如果是非金融安全级别的业务场景，建议设置成 false， -# 以便获得更高的性能。 -sync-log = true - -# Raft RocksDB 目录。默认值是 [storage.data-dir] 的 raft 子目录。 -# 如果机器上有多块磁盘，可以将 Raft RocksDB 的数据放在不同的盘上，提高 TiKV 的性能。 -# raftdb-dir = "/tmp/tikv/store/raft" - -region-max-size = "384MB" -# Region 分裂阈值 -region-split-size = "256MB" -# 当 Region 写入的数据量超过该阈值的时候，TiKV 会检查该 Region 是否需要分裂。为了减少检查过程 -# 中扫描数据的成本，数据过程中可以将该值设置为32MB，正常运行状态下使用默认值即可。 -region-split-check-diff = "32MB" - -[rocksdb] -# RocksDB 进行后台任务的最大线程数，后台任务包括 compaction 和 flush。具体 RocksDB 为什么需要进行 compaction， -# 请参考 RocksDB 的相关资料。在写流量比较大的时候（例如导数据），建议开启更多的线程， -# 但应小于 CPU 的核数。例如在导数据的时候，32 核 CPU 的机器，可以设置成 28。 -# max-background-jobs = 8 - -# RocksDB 能够打开的最大文件句柄数。 -# max-open-files = 40960 - -# RocksDB MANIFEST 文件的大小限制.
# 更详细的信息请参考：https://github.com/facebook/rocksdb/wiki/MANIFEST -max-manifest-file-size = "20MB" - -# RocksDB write-ahead logs 目录。如果机器上有两块盘，可以将 RocksDB 的数据和 WAL 日志放在 -# 不同的盘上，提高 TiKV 的性能。 -# wal-dir = "/tmp/tikv/store" - -# 下面两个参数用于怎样处理 RocksDB 归档 WAL。 -# 更多详细信息请参考：https://github.com/facebook/rocksdb/wiki/How-to-persist-in-memory-RocksDB-database%3F -# wal-ttl-seconds = 0 -# wal-size-limit = 0 - -# RocksDB WAL 日志的最大总大小，通常情况下使用默认值就可以了。 -# max-total-wal-size = "4GB" - -# 可以通过该参数打开或者关闭 RocksDB 的统计信息。 -# enable-statistics = true - -# 开启 RocksDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。 -# compaction-readahead-size = "2MB" - -[rocksdb.defaultcf] -# 数据块大小。RocksDB 是按照 block 为单元对数据进行压缩的，同时 block 也是缓存在 block-cache -# 中的最小单元（类似其他数据库的 page 概念）。 -block-size = "64KB" - -# RocksDB 每一层数据的压缩方式，可选的值为：no,snappy,zlib,bzip2,lz4,lz4hc,zstd。 -# no:no:lz4:lz4:lz4:zstd:zstd 表示 level0 和 level1 不压缩，level2 到 level4 采用 lz4 压缩算法, -# level5 和 level6 采用 zstd 压缩算法,。 -# no 表示没有压缩，lz4 是速度和压缩比较为中庸的压缩算法，zlib 的压缩比很高，对存储空间比较友 -# 好，但是压缩速度比较慢，压缩的时候需要占用较多的 CPU 资源。不同的机器需要根据 CPU 以及 I/O 资 -# 源情况来配置怎样的压缩方式。例如：如果采用的压缩方式为"no:no:lz4:lz4:lz4:zstd:zstd"，在大量 -# 写入数据的情况下（导数据），发现系统的 I/O 压力很大（使用 iostat 发现 %util 持续 100% 或者使 -# 用 top 命令发现 iowait 特别多），而 CPU 的资源还比较充裕，这个时候可以考虑将 level0 和 -# level1 开启压缩，用 CPU 资源换取 I/O 资源。如果采用的压缩方式 -# 为"no:no:lz4:lz4:lz4:zstd:zstd"，在大量写入数据的情况下，发现系统的 I/O 压力不大，但是 CPU -# 资源已经吃光了，top -H 发现有大量的 bg 开头的线程（RocksDB 的 compaction 线程）在运行，这 -# 个时候可以考虑用 I/O 资源换取 CPU 资源，将压缩方式改成"no:no:no:lz4:lz4:zstd:zstd"。总之，目 -# 的是为了最大限度地利用系统的现有资源，使 TiKV 的性能在现有的资源情况下充分发挥。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# RocksDB memtable 的大小。 -write-buffer-size = "128MB" - -# 最多允许几个 memtable 存在。写入到 RocksDB 的数据首先会记录到 WAL 日志里面，然后会插入到 -# memtable 里面，当 memtable 的大小到达了 write-buffer-size 限定的大小的时候，当前的 -# memtable 会变成只读的，然后生成一个新的 memtable 接收新的写入。只读的 memtable 会被 -# RocksDB 的 flush 线程（max-background-flushes 参数能够控制 flush 线程的最大个数） -# flush 到磁盘，成为 level0 的一个 sst 文件。当 flush 线程忙不过来，导致等待 flush 到磁盘的 -# memtable 的数量到达 max-write-buffer-number 限定的个数的时候，RocksDB 会将新的写入 -# stall 住，stall 是 RocksDB 的一种流控机制。在导数据的时候可以将 max-write-buffer-number -# 的值设置的更大一点，例如 10。 -max-write-buffer-number = 5 - -# 当 level0 的 sst 文件个数到达 level0-slowdown-writes-trigger 指定的限度的时候， -# RocksDB 会尝试减慢写入的速度。因为 level0 的 sst 太多会导致 RocksDB 的读放大上升。 -# level0-slowdown-writes-trigger 和 level0-stop-writes-trigger 是 RocksDB 进行流控的 -# 另一个表现。当 level0 的 sst 的文件个数到达 4（默认值），level0 的 sst 文件会和 level1 中 -# 有 overlap 的 sst 文件进行 compaction，缓解读放大的问题。 -level0-slowdown-writes-trigger = 20 - -# 当 level0 的 sst 文件个数到达 level0-stop-writes-trigger 指定的限度的时候，RocksDB 会 -# stall 住新的写入。 -level0-stop-writes-trigger = 36 - -# 当 level1 的数据量大小达到 max-bytes-for-level-base 限定的值的时候，会触发 level1 的 -# sst 和 level2 种有 overlap 的 sst 进行 compaction。 -# 黄金定律：max-bytes-for-level-base 的设置的第一参考原则就是保证和 level0 的数据量大致相 -# 等，这样能够减少不必要的 compaction。例如压缩方式为"no:no:lz4:lz4:lz4:lz4:lz4"，那么 -# max-bytes-for-level-base 的值应该是 write-buffer-size 的大小乘以 4，因为 level0 和 -# level1 都没有压缩，而且 level0 触发 compaction 的条件是 sst 的个数到达 4（默认值）。在 -# level0 和 level1 都采取了压缩的情况下，就需要分析下 RocksDB 的日志，看一个 memtable 的压 -# 缩成一个 sst 文件的大小大概是多少，例如 32MB，那么 max-bytes-for-level-base 的建议值就应 -# 该是 32MB * 4 = 128MB。 -max-bytes-for-level-base = "512MB" - -# sst 文件的大小。level0 的 sst 文件的大小受 write-buffer-size 和 level0 采用的压缩算法的 -# 影响，target-file-size-base 参数用于控制 level1-level6 单个 sst 文件的大小。 -target-file-size-base = "32MB" - -[rocksdb.writecf] -# 保持和 rocksdb.defaultcf.compression-per-level 一致。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# 保持和 rocksdb.defaultcf.write-buffer-size 一致。 -write-buffer-size = "128MB" -max-write-buffer-number = 5 -min-write-buffer-number-to-merge = 1 - -# 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。 -max-bytes-for-level-base = "512MB" -target-file-size-base = "32MB" - -[raftdb] -# RaftDB 能够打开的最大文件句柄数。 -# max-open-files = 40960 - -# 可以通过该参数打开或者关闭 RaftDB 的统计信息。 -# enable-statistics = true - -# 开启 RaftDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。 -# compaction-readahead-size = "2MB" - -[raftdb.defaultcf] -# 保持和 rocksdb.defaultcf.compression-per-level 一致。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# 保持和 rocksdb.defaultcf.write-buffer-size 一致。 -write-buffer-size = "128MB" -max-write-buffer-number = 5 -min-write-buffer-number-to-merge = 1 - -# 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。 -max-bytes-for-level-base = "512MB" -target-file-size-base = "32MB" -``` - -## TiKV 内存使用情况 - -除了以上列出的 `block-cache` 以及 `write-buffer` 会占用系统内存外： - -1. 需预留一些内存作为系统的 page cache -2. TiKV 在处理大的查询的时候（例如 `select * from ...`）会读取数据然后在内存中生成对应的数据结构返回给 TiDB，这个过程中 TiKV 会占用一部分内存 - -## TiKV 机器配置推荐 - -1. 生产环境中，不建议将 TiKV 部署在 CPU 核数小于 8 或内存低于 32GB 的机器上 -2. 如果对写入吞吐要求比较高，建议使用吞吐能力比较好的磁盘 -3. 如果对读写的延迟要求非常高，建议使用 IOPS 比较高的 SSD 盘 diff --git a/v3.0/reference/performance/understanding-the-query-execution-plan.md b/v3.0/reference/performance/understanding-the-query-execution-plan.md deleted file mode 100644 index 3e2420931286..000000000000 --- a/v3.0/reference/performance/understanding-the-query-execution-plan.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: 理解 TiDB 执行计划 -category: reference -aliases: ['/docs-cn/sql/understanding-the-query-execution-plan/'] ---- - -# 理解 TiDB 执行计划 - -TiDB 优化器会根据当前数据表的实际情况来选择最优的执行计划，执行计划由一系列的算子构成。本文将详细解释 TiDB 中 `EXPLAIN` 语句返回的执行计划信息。 - -## 使用 `EXPLAIN` 来优化 SQL 语句 - -`EXPLAIN` 语句的返回结果提供了 TiDB 执行 SQL 查询的详细信息： - -- `EXPLAIN` 可以和 `SELECT`，`DELETE` 语句一起使用； -- 执行 `EXPLAIN`，TiDB 会返回被 `EXPLAIN` 的 SQL 语句经过优化器后的最终物理执行计划。也就是说，`EXPLAIN` 展示了 TiDB 执行该 SQL 语句的完整信息，比如以什么样的顺序，什么方式 JOIN 两个表，表达式树长什么样等等。详见 [`EXPLAIN` 输出格式](#explain-输出格式)； -- TiDB 支持 `EXPLAIN [options] FOR CONNECTION connection_id`，但与 MySQL 的 `EXPLAIN FOR` 有一些区别，请参见 [`EXPLAIN FOR CONNECTION`](#explain-for-connection)。 - -通过观察 `EXPLAIN` 的结果，你可以知道如何给数据表添加索引使得执行计划使用索引从而加速 SQL 语句的执行速度；你也可以使用 `EXPLAIN` 来检查优化器是否选择了最优的顺序来 JOIN 数据表。 - -## `EXPLAIN` 输出格式 - -目前 TiDB 的 `EXPLAIN` 会输出 4 列，分别是：id，count，task，operator info。执行计划中每个算子都由这 4 列属性来描述，`EXPLAIN` 结果中每一行描述一个算子。每个属性的具体含义如下： - -| 属性名 | 含义 | -|:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------| -| id | 算子的 ID，在整个执行计划中唯一的标识一个算子。在 TiDB 2.1 中，id 会格式化显示算子的树状结构。数据从 child 流向 parent，每个 算子的 parent 有且仅有一个。 | -| count | 预计当前算子将会输出的数据条数，基于统计信息以及算子的执行逻辑估算而来。 | -| task | 当前这个算子属于什么 task。目前的执行计划分成为两种 task，一种叫 **root** task，在 tidb-server 上执行，一种叫 **cop** task，并行的在 TiKV 上执行。当前的执行计划在 task 级别的拓扑关系是一个 root task 后面可以跟许多 cop task，root task 使用 cop task 的输出结果作为输入。cop task 中执行的也即是 TiDB 下推到 TiKV 上的任务，每个 cop task 分散在 TiKV 集群中，由多个进程共同执行。 | -| operator info | 每个算子的详细信息。各个算子的 operator info 各有不同，详见 [Operator Info](#operator-info)。 | - -## `EXPLAIN ANALYZE` 输出格式 - -作为 `EXPLAIN` 语句的扩展，`EXPLAIN ANALYZE` 语句执行查询并在 `execution info` 列中提供额外的执行统计信息。具体如下： - -* `time` 显示从进入算子到离开算子的全部 wall time，包括所有子算子操作的全部执行时间。如果该算子被父算子多次调用 (`loops`)，这个时间就是累积的时间。 -* `loops` 是当前算子被父算子调用的次数。 -* `rows` 是当前算子返回的行的总数。例如，可以将 `count` 列的精度和 `execution_info` 列中的 `rows`/`loops` 值进行对比，据此评定查询优化器估算的精确度。 - -### 用例 - -使用 [bikeshare example database](https://github.com/pingcap/docs/blob/master/dev/how-to/get-started/import-example-database.md): - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'; -``` - -``` -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -| id | count | task | operator info | -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -| StreamAgg_20 | 1.00 | root | funcs:count(col_0) | -| └─TableReader_21 | 1.00 | root | data:StreamAgg_9 | -| └─StreamAgg_9 | 1.00 | cop | funcs:count(1) | -| └─Selection_19 | 8166.73 | cop | ge(bikeshare.trips.start_date, 2017-07-01 00:00:00.000000), le(bikeshare.trips.start_date, 2017-07-01 23:59:59.000000) | -| └─TableScan_18 | 19117643.00 | cop | table:trips, range:[-inf,+inf], keep order:false | -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -5 rows in set (0.00 sec) -``` - -在上面的例子中，coprocessor 上读取 `trips` 表上的数据（`TableScan_18`），寻找满足 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 条件的数据（`Selection_19`），然后计算满足条件的数据行数（`StreamAgg_9`），最后把结果返回给 TiDB。TiDB 汇总各个 coprocessor 返回的结果（`TableReader_21`），并进一步计算所有数据的行数（`StreamAgg_20`），最终把结果返回给客户端。在上面这个查询中，TiDB 根据 `trips` 表的统计信息估算出 `TableScan_18` 的输出结果行数为 19117643.00，满足条件 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 的有 `8166.73` 条，经过聚合运算后，只有 1 条结果。 - -上述查询中，虽然大部分计算逻辑都下推到了 TiKV 的 coprocessor 上，但是其执行效率还是不够高，可以添加适当的索引来消除 `TableScan_18` 对 `trips` 的全表扫，进一步加速查询的执行： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE trips ADD INDEX (start_date); -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'; -``` - -``` -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -| id | count | task | operator info | -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -| StreamAgg_25 | 1.00 | root | funcs:count(col_0) | -| └─IndexReader_26 | 1.00 | root | index:StreamAgg_9 | -| └─StreamAgg_9 | 1.00 | cop | funcs:count(1) | -| └─IndexScan_24 | 8166.73 | cop | table:trips, index:start_date, range:[2017-07-01 00:00:00,2017-07-01 23:59:59], keep order:false | -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -4 rows in set (0.01 sec) -``` - -在添加完索引后的新执行计划中，使用 `IndexScan_24` 直接读取满足条件 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 的数据，可以看到，估算的要扫描的数据行数从之前的 `19117643.00` 降到了现在的 `8166.73`。在测试环境中显示，这个查询的执行时间从 50.41 秒降到了 0.01 秒！ - -## `EXPLAIN FOR CONNECTION` - -`EXPLAIN FOR CONNECTION` 用于获得一个连接中最后执行的查询的执行计划，其输出格式与 `EXPLAIN` 完全一致。但 TiDB 中的实现与 MySQL 不同，除了输出格式之外，还有以下区别： - -- MySQL 返回的是**正在执行**的查询计划，而 TiDB 返回的是**最后执行**的查询计划。 -- MySQL 的文档中指出，MySQL 要求登录用户与被查询的连接相同，或者拥有 `PROCESS` 权限，而 TiDB 则要求登录用户与被查询的连接相同，或者拥有 `SUPER` 权限。 - -## 概述 - -### Task 简介 - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指使用 TiKV 中的 coprocessor 执行的计算任务，root task 是指在 TiDB 中执行的计算任务。 - -SQL 优化的目标之一是将计算尽可能地下推到 TiKV 中执行。TiKV 中的 coprocessor 能支持大部分 SQL 内建函数（包括聚合函数和标量函数）、SQL `LIMIT` 操作、索引扫描和表扫描。但是，所有的 Join 操作都只能作为 root task 在 TiDB 上执行。 - -### 表数据和索引数据 - -TiDB 的表数据是指一张表的原始数据，存放在 TiKV 中。对于每行表数据，它的 key 是一个 64 位整数，称为 Handle ID。如果一张表存在 int 类型的主键，TiDB 会把主键的值当作表数据的 Handle ID，否则由系统自动生成 Handle ID。表数据的 value 由这一行的所有数据编码而成。在读取表数据的时候，可以按照 Handle ID 递增的顺序返回。 - -TiDB 的索引数据和表数据一样，也存放在 TiKV 中。它的 key 是由索引列编码的有序 bytes，value 是这一行索引数据对应的 Handle ID，通过 Handle ID 可以读取这一行的非索引列。在读取索引数据的时候，TiKV 会按照索引列递增的顺序返回，如果有多个索引列，首先保证第 1 列递增，并且在第 i 列相等的情况下，保证第 i + 1 列递增。 - -### 范围查询 - -在 WHERE/HAVING/ON 条件中，TiDB 优化器会分析主键或索引键的查询返回。如数字、日期类型的比较符，如大于、小于、等于以及大于等于、小于等于，字符类型的 LIKE 符号等。 - -值得注意的是，TiDB 目前只支持比较符一端是列，另一端是常量，或可以计算成某一常量的情况，类似 `year(birth_day) < 1992` 的查询条件是不能利用索引的。还要注意应尽可能使用同一类型进行比较，以避免引入额外的 cast 操作而导致不能利用索引，如 `user_id = 123456`，如果 `user_id` 是字符串，需要将 `123456` 也写成字符串常量的形式。 - -针对同一列的范围查询条件使用 `AND` 和 `OR` 组合后，等于对范围求交集或者并集。对于多维组合索引，可以写多个列的条件。例如对组合索引`(a, b, c)`，当 a 为等值查询时，可以继续求 b 的查询范围，当 b 也为等值查询时，可以继续求 c 的查询范围，反之如果 a 为非等值查询，则只能求 a 的范围。 - -## Operator Info - -### TableReader 和 TableScan - -TableScan 表示在 KV 端对表数据进行扫描，TableReader 表示在 TiDB 端从 TiKV 端读取，属于同一功能的两个算子。table 表示 SQL 语句中的表名，如果表名被重命名，则显示重命名。range 表示扫描的数据范围，如果在查询中不指定 WHERE/HAVING/ON 条件，则会选择全表扫描，如果在 int 类型的主键上有范围查询条件，会选择范围查询。keep order 表示 table scan 是否按顺序返回。 - -### IndexReader 和 IndexLookUp - -Index 在 TiDB 端的读取方式有两种：IndexReader 表示直接从索引中读取索引列，适用于 SQL 语句中仅引用了该索引相关的列或主键；IndexLookUp 表示从索引中过滤部分数据，仅返回这些数据的 Handle ID，通过 Handle ID 再次查找表数据，这种方式需要两次从 TiKV 获取数据。Index 的读取方式是由优化器自动选择的。 - -IndexScan 是 KV 端读取索引数据的算子，和 TableScan 功能类似。table 表示 SQL 语句中的表名，如果表名被重命名，则显示重命名。index 表示索引名。range 表示扫描的数据范围。out of order 表示 index scan 是否按照顺序返回。注意在 TiDB 中，多列或者非 int 列构成的主键是当作唯一索引处理的。 - -### Selection - -Selection 表示 SQL 语句中的选择条件，通常出现在 WHERE/HAVING/ON 子句中。 - -### Projection - -Projection 对应 SQL 语句中的 SELECT 列表，功能是将每一条输入数据映射成新的输出数据。 - -### Aggregation - -Aggregation 对应 SQL 语句中的 Group By 语句或者没有 Group By 语句但是存在聚合函数，例如 count 或 sum 函数等。TiDB 支持两种聚合算法：Hash Aggregation 以及 Stream Aggregation（待补充）。Hash Aggregation 是基于哈希的聚合算法，如果 Hash Aggregation 紧邻 Table 或者 Index 的读取算子，则聚合算子会在 TiKV 端进行预聚合，以提高计算的并行度和减少网络开销。 - -### Join - -TiDB 支持 Inner Join 以及 Left/Right Outer Join，并会自动将可以化简的外连接转换为 Inner Join。 - -TiDB 支持三种 Join 算法：Hash Join，Sort Merge Join 和 Index Look up Join。Hash Join 的原理是将参与连接的小表预先装载到内存中，读取大表的所有数据进行连接。Sort Merge Join 会利用输入数据的有序信息，同时读取两张表的数据并依次进行比较。Index Look Up Join 会读取外表的数据，并对内表进行主键或索引键查询。 - -### Apply - -Apply 是 TiDB 用来描述子查询的一种算子，行为类似于 Nested Loop，即每次从外表中取一条数据，带入到内表的关联列中，并执行，最后根据 Apply 内联的 Join 算法进行连接计算。 - -值得注意的是，Apply 一般会被查询优化器自动转换为 Join 操作。用户在编写 SQL 的过程中应尽量避免 Apply 算子的出现。 diff --git a/v3.0/reference/security/cert-based-authentication.md b/v3.0/reference/security/cert-based-authentication.md deleted file mode 100644 index 268e33b06087..000000000000 --- a/v3.0/reference/security/cert-based-authentication.md +++ /dev/null @@ -1,483 +0,0 @@ ---- -title: TiDB 证书鉴权使用指南 -summary: 了解使用 TiDB 的证书鉴权功能。 -category: reference ---- - -# TiDB 证书鉴权使用指南 从 v3.0.8 版本开始引入 - -从 TiDB 3.0.8 版本开始，TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不同用户签发证书，使用加密连接来传输数据，并在用户登录时验证证书。相比 MySQL 用户常用的用户名密码验证方式，与 MySQL 相兼容的证书鉴权方式更安全，因此越来越多的用户使用证书鉴权来代替用户名密码验证。 - -在 TiDB 上使用证书鉴权的登录方法，可能需要进行以下操作： - -+ 创建安全密钥和证书 -+ 配置 TiDB 和客户端使用的证书 -+ 配置登陆时需要校验的用户证书信息 -+ 更新和替换证书 - -本文介绍了如何进行证书鉴权的上述几个操作。 - -## 创建安全密钥和证书 - -### 安装 OpenSSL - -目前推荐使用 [OpenSSL](https://www.openssl.org/) 来生成密钥和证书。以 Debian 操作系统为例，先执行以下命令来安装 OpenSSL： - -{{< copyable "shell-regular" >}} - -```bash -sudo apt-get install openssl -``` - -### 生成 CA 密钥和证书 - -1. 执行以下命令生成 CA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl genrsa 2048 > ca-key.pem - ``` - - 命令执行后输出以下结果： - - {{< copyable "shell-regular" >}} - - ```bash - Generating RSA private key, 2048 bit long modulus (2 primes) - ....................+++++ - ...............................................+++++ - e is 65537 (0x010001) - ``` - -2. 执行以下命令生成该密钥对应的证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.pem - ``` - -3. 输入证书细节信息，示例如下： - - {{< copyable "shell-regular" >}} - - ```bash - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:San Francisco - Organization Name (eg, company) [Internet Widgits Pty Ltd]:PingCAP Inc. - Organizational Unit Name (eg, section) []:TiDB - Common Name (e.g. server FQDN or YOUR name) []:TiDB admin - Email Address []:s@pingcap.com - ``` - - > **注意：** - > - > 以上信息中，`:` 后的文字为用户输入的信息。 - -### 生成服务端密钥和证书 - -1. 执行以下命令生成服务端的密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.pem -out server-req.pem - ``` - -2. 输入证书细节信息，示例如下： - - {{< copyable "shell-regular" >}} - - ```bash - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:San Francisco - Organization Name (eg, company) [Internet Widgits Pty Ltd]:PingCAP Inc. - Organizational Unit Name (eg, section) []:TiKV - Common Name (e.g. server FQDN or YOUR name) []:TiKV Test Server - Email Address []:k@pingcap.com - - Please enter the following 'extra' attributes - to be sent with your certificate request - A challenge password []: - An optional company name []: - ``` - -3. 执行以下命令生成服务端的 RSA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl rsa -in server-key.pem -out server-key.pem - ``` - - 输出结果如下： - - ```bash - writing RSA key - ``` - -4. 使用 CA 证书签名来生成服务端的证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in server-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem - ``` - - 输出结果示例如下： - - ```bash - Signature ok - subject=C = US, ST = California, L = San Francisco, O = PingCAP Inc., OU = TiKV, CN = TiKV Test Server, emailAddress = k@pingcap.com - Getting CA Private Key - ``` - - > **注意：** - > - > 以上结果中，用户登陆时 TiDB 将强制检查 `subject` 部分的信息是否一致。 - -### 生成客户端密钥和证书 - -生成服务端密钥和证书后，需要生成客户端使用的密钥和证书。通常需要为不同的用户生成不同的密钥和证书。 - -1. 执行以下命令生成客户端的密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.pem -out client-req.pem - ``` - -2. 输入证书细节信息，示例如下： - - {{< copyable "shell-regular" >}} - - ```bash - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:San Francisco - Organization Name (eg, company) [Internet Widgits Pty Ltd]:PingCAP Inc. - Organizational Unit Name (eg, section) []:TiDB - Common Name (e.g. server FQDN or YOUR name) []:tpch-user1 - Email Address []:zz@pingcap.com - - Please enter the following 'extra' attributes - to be sent with your certificate request - A challenge password []: - An optional company name []: - ``` - -3. 执行以下命令生成客户端 RSA 证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl rsa -in client-key.pem -out client-key.pem - ``` - - 以上命令的输出结果如下： - - ```bash - writing RSA key - ``` - -4. 执行以下命令，使用 CA 证书签名来生成客户端证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in client-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem - ``` - - 输出结果示例如下： - - ```bash - Signature ok - subject=C = US, ST = California, L = San Francisco, O = PingCAP Inc., OU = TiDB, CN = tpch-user1, emailAddress = zz@pingcap.com - Getting CA Private Key - ``` - - > **注意：** - > - > 以上结果中，`subject` 部分后的信息会被用来在 `require` 中配置和要求验证。 - -### 验证证书 - -执行以下命令验证证书： - -{{< copyable "shell-regular" >}} - -```bash -openssl verify -CAfile ca-cert.pem server-cert.pem client-cert.pem -``` - -如果验证通过，会显示以下信息： - -``` -server-cert.pem: OK -client-cert.pem: OK -``` - -## 配置 TiDB 和客户端使用证书 - -在生成证书后，需要在 TiDB 中配置服务端所使用的证书，同时让客户端程序使用客户端证书。 - -### 配置 TiDB 服务端 - -修改 TiDB 配置文件中的 `[security]` 段。这一步指定 CA 证书、服务端密钥和服务端证书存放的路径。可将 `path/to/server-cert.pem`、`path/to/server-key.pem` 和 `path/to/ca-cert.pem` 替换成实际的路径。 - -{{< copyable "" >}} - -``` -[security] -ssl-cert ="path/to/server-cert.pem" -ssl-key ="path/to/server-key.pem" -ssl-ca="path/to/ca-cert.pem" -``` - -启动 TiDB 日志。如果日志中有以下内容，即代表配置生效： - -``` -[INFO] [server.go:264] ["secure connection is enabled"] ["client verification enabled"=true] -``` - -### 配置客户端程序 - -配置客户端程序，让客户端使用客户端密钥和证书来登录 TiDB。 - -以 MySQL 客户端为例，可以通过指定 `ssl-cert`、`ssl-key`、`ssl-ca` 来使用新的 CA 证书、客户端密钥和证书： - -{{< copyable "shell-regular" >}} - -```bash -mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem -``` - -> **注意：** -> -> `/path/to/client-cert.new.pem`、`/path/to/client-key.new.pem` 和 `/path/to/ca-cert.pem` 是 CA 证书、客户端密钥和客户端存放的路径。可将以上命令中的这些部分替换为实际的路径。 - -## 配置登陆时需要校验的用户证书信息 - -使用客户端连接 TiDB 进行授权配置。先获取需要验证的用户证书信息，再对这些信息进行配置。 - -### 获取用户证书信息 - -用户证书信息可由 `require subject`、`require issuer` 和 `require cipher` 来指定，用于检查 X.509 certificate attributes。 - -+ `require subject`：指定用户在连接时需要提供客户端证书的 `subject` 内容。指定该选项后，不需要再配置 `require ssl` 或 x509。配置内容对应[生成客户端密钥和证书](#生成客户端密钥和证书) 中的录入信息。 - - 可以执行以下命令来获取该项的信息： - - {{< copyable "shell-regular" >}} - - ``` - openssl x509 -noout -subject -in client-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//' - ``` - -+ `require issuer`：指定签发用户证书的 CA 证书的 `subject` 内容。配置内容对应[生成 CA 密钥和证书](#生成-ca-密钥和证书) 中的录入信息。 - - 可以执行以下命令来获取该项的信息： - - ``` - openssl x509 -noout -subject -in ca-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//' - ``` - -+ `require cipher`：配置该项检查客户端支持的 cipher method。可以使用以下语句来查看支持的列表： - - {{< copyable "sql" >}} - - ```sql - SHOW SESSION STATUS LIKE 'Ssl_cipher_list'; - ``` - -### 配置用户证书信息 - -获取用户证书信息（`require subject`, `require issuer` 和 `require cipher`）后，可在创建用户、赋予权限或更改用户时配置用户证书信息。将以下命令中的 `` 替换为对应的信息。可以选择配置其中一项或多项，使用空格或 `and` 分隔。 - -+ 可以在创建用户 (`create user`) 时配置登陆时需要校验的证书信息： - - {{< copyable "sql" >}} - - ```sql - create user 'u1'@'%' require issuer '' subject '' cipher ''; - ``` - -+ 可以在赋予权限 (`grant`) 时配置登陆时需要校验的证书信息： - - {{< copyable "sql" >}} - - ```sql - grant all on *.* to 'u1'@'%' require issuer '' subject '' cipher ''; - ``` - -+ 还可以在修改已有用户 (alter user) 时配置登陆时需要校验的证书信息： - - {{< copyable "sql" >}} - - ```sql - alter user 'u1'@'%' require issuer '' subject '' cipher ''; - ``` - -配置完成后，用户在登录时 TiDB 会验证以下内容： - -+ 使用 SSL 登录，且证书为服务器配置的 CA 证书所签发 -+ 证书的 `Issuer` 信息和权限配置里的信息相匹配 -+ 证书的 `Subject` 信息和权限配置里的信息相匹配 - -全部验证通过后用户才能登录，否则会报 `ERROR 1045 (28000): Access denied` 错误。登录后，可以通过以下命令来查看当前链接是否使用证书登录、TLS 版本和 Cipher 算法。 - -连接 MySQL 客户端并执行： - -{{< copyable "sql" >}} - -```sql -\s -``` - -返回结果如下： - -``` --------------- -mysql Ver 15.1 Distrib 10.4.10-MariaDB, for Linux (x86_64) using readline 5.1 - -Connection id: 1 -Current database: test -Current user: root@127.0.0.1 -SSL: Cipher in use is TLS_AES_256_GCM_SHA384 -``` - -然后执行： - -{{< copyable "sql" >}} - -```sql -show variables like '%ssl%'; -``` - -返回结果如下： - -``` -+---------------+----------------------------------+ -| Variable_name | Value | -+---------------+----------------------------------+ -| ssl_cert | /path/to/server-cert.pem | -| ssl_ca | /path/to/ca-cert.pem | -| have_ssl | YES | -| have_openssl | YES | -| ssl_key | /path/to/server-key.pem | -+---------------+----------------------------------+ -6 rows in set (0.067 sec) -``` - -## 更新和替换证书 - -证书和密钥通常会周期性更新。下文介绍更新密钥和证书的流程。 - -CA 证书是客户端和服务端相互校验的依据，所以如果需要替换 CA 证书，则需要生成一个组合证书来在替换期间同时支持客户端和服务器上新旧证书的验证，并优先替换客户端和服务端的 CA 证书，再替换客户端和服务端的密钥和证书。 - -### 更新 CA 密钥和证书 - -1. 以替换 CA 密钥为例（假设 `ca-key.pem` 被盗），将旧的 CA 密钥和证书进行备份： - - {{< copyable "shell-regular" >}} - - ```bash - mv ca-key.pem ca-key.old.pem && \ - mv ca-cert.pem ca-cert.old.pem - ``` - -2. 生成新的 CA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl genrsa 2048 > ca-key.pem - ``` - -3. 用新的密钥生成新的 CA 证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.new.pem - ``` - - > **注意：** - > - > 生成新的 CA 证书是为了替换密钥和证书，保证在线用户不受影响。所以以上命令中填写的附加信息必须与已配置的 `require issuer` 信息一致。 - -4. 生成组合 CA 证书： - - {{< copyable "shell-regular" >}} - - ```bash - cat ca-cert.new.pem ca-cert.old.pem > ca-cert.pem - ``` - -之后使用新生成的组合 CA 证书并重启 TiDB Server，此时服务端可以同时接受和使用新旧 CA 证书。 - -之后先将所有客户端用的 CA 证书也替换为新生成的组合 CA 证书，使客户端能同时和使用新旧 CA 证书。 - -### 更新客户端密钥和证书 - -> **注意：** -> -> 需要将集群中所有服务端和客户端使用的 CA 证书都替换为新生成的组合 CA 证书后才能开始进行以下步骤。 - -1. 生成新的客户端 RSA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.new.pem -out client-req.new.pem && \ - sudo openssl rsa -in client-key.new.pem -out client-key.new.pem - ``` - - > **注意：** - > - > 以上命令是为了替换密钥和证书，保证在线用户不受影响，所以以上命令中填写的附加信息必须与已配置的 `require subject` 信息一致。 - -2. 使用新的组合 CA 证书和新 CA 密钥生成新客户端证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in client-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.new.pem - ``` - -3. 让客户端使用新的客户端密钥和证书来连接 TiDB （以 MySQL 客户端为例）： - - {{< copyable "shell-regular" >}} - - ```bash - mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem - ``` - - > **注意：** - > - > `/path/to/client-cert.new.pem`、`/path/to/client-key.new.pem` 和 `/path/to/ca-cert.pem` 是 CA 证书、客户端密钥和客户端存放的路径。可将以上命令中的这些部分替换为实际的路径。 - -### 更新服务端密钥和证书 - -1. 生成新的服务端 RSA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.new.pem -out server-req.new.pem && \ - sudo openssl rsa -in server-key.new.pem -out server-key.new.pem - ``` - -2. 使用新的组合 CA 证书和新 CA 密钥生成新服务端证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in server-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.new.pem - ``` - -3. 配置 TiDB 使用上面新生成的服务端密钥和证书并重启。参见[配置 TiDB 服务端](#配置-tidb-服务端)。 diff --git a/v3.0/reference/security/compatibility.md b/v3.0/reference/security/compatibility.md deleted file mode 100644 index 8b1691a74f4a..000000000000 --- a/v3.0/reference/security/compatibility.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 与 MySQL 安全特性差异 -category: reference -aliases: ['/docs-cn/sql/security-compatibility/'] ---- - -# 与 MySQL 安全特性差异 - -除以下功能外，TiDB 支持与 MySQL 5.7 类似的安全特性。 - -- 仅支持 `mysql_native_password` 身份验证方案。 -- 不支持外部身份验证方式（如 LDAP）。 -- 不支持列级别权限设置。 -- 不支持密码过期，最后一次密码变更记录以及密码生存期。[#9709](https://github.com/pingcap/tidb/issues/9709) -- 不支持权限属性 `max_questions`，`max_updated`，`max_connections` 以及 `max_user_connections`。 -- 不支持密码验证。[#9741](https://github.com/pingcap/tidb/issues/9741) -- 不支持透明数据加密（TDE）。 diff --git a/v3.0/reference/security/privilege-system.md b/v3.0/reference/security/privilege-system.md deleted file mode 100644 index 6d474be6d7bd..000000000000 --- a/v3.0/reference/security/privilege-system.md +++ /dev/null @@ -1,482 +0,0 @@ ---- -title: 权限管理 -category: reference -aliases: ['/docs-cn/sql/privilege/'] ---- - -# 权限管理 - -TiDB 的权限管理系统按照 MySQL 的权限管理进行实现，TiDB 支持大部分的 MySQL 的语法和权限类型。 - -本文档主要介绍 TiDB 权限相关操作、各项操作需要的权限以及权限系统的实现。 - -## 权限相关操作 - -### 授予权限 - -授予 `xxx` 用户对数据库 `test` 的读权限： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO 'xxx'@'%'; -``` - -为 `xxx` 用户授予所有数据库，全部权限： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'xxx'@'%'; -``` - -`GRANT` 为一个不存在的用户授予权限时，默认并不会自动创建用户。该行为受 SQL Mode 中的 `NO_AUTO_CREATE_USER` 控制。 -如果从 SQL Mode 中去掉 `NO_AUTO_CREATE_USER`，当 `GRANT` 的目标用户不存在时，TiDB 会自动创建用户。 - -{{< copyable "sql" >}} - -```sql -mysql> select @@sql_mode; -``` - -```+-------------------------------------------------------------------------------------------------------------------------------------------+ -| @@sql_mode | -+-------------------------------------------------------------------------------------------------------------------------------------------+ -| ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@sql_mode='ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM mysql.user WHERE user='xxxx'; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON test.* TO 'xxxx'@'%' IDENTIFIED BY 'yyyyy'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT user,host FROM mysql.user WHERE user='xxxx'; -``` - -``` -+------|------+ -| user | host | -+------|------+ -| xxxx | % | -+------|------+ -1 row in set (0.00 sec) -``` - -上述示例中，`xxxx@%` 即自动添加的用户。 - -`GRANT` 对于数据库或者表的授权，不检查数据库或表是否存在。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM test.xxxx; -``` - -``` -ERROR 1146 (42S02): Table 'test.xxxx' doesn't exist -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON test.xxxx TO xxxx; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -mysql> SELECT user,host FROM mysql.tables_priv WHERE user='xxxx'; -``` - -``` -+------|------+ -| user | host | -+------|------+ -| xxxx | % | -+------|------+ -1 row in set (0.00 sec) -``` - -`GRANT` 可以模糊匹配地授予数据库和表： - -{{< copyable "sql" >}} - -```sql -mysql> GRANT ALL PRIVILEGES ON `te%`.* TO genius; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT user,host,db FROM mysql.db WHERE user='genius'; -``` - -``` -+--------|------|-----+ -| user | host | db | -+--------|------|-----+ -| genius | % | te% | -+--------|------|-----+ -1 row in set (0.00 sec) -``` - -这个例子中通过 `%` 模糊匹配，所有 `te` 开头的数据库，都被授予了权限。 - -### 收回权限 - -`REVOKE` 语句与 `GRANT` 对应： - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `test`.* FROM 'genius'@'localhost'; -``` - -> **注意：** -> -> `REVOKE` 收回权限时只做精确匹配，若找不到记录则报错。而 `GRANT` 授予权限时可以使用模糊匹配。 - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `te%`.* FROM 'genius'@'%'; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'genius' on host '%' -``` - -关于模糊匹配和转义，字符串和 identifier： - -{{< copyable "sql" >}} - -```sql -mysql> GRANT ALL PRIVILEGES ON `te\%`.* TO 'genius'@'localhost'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -上述例子是精确匹配名为 `te%` 的数据库，注意使用 `\` 转义字符。 - -以单引号包含的部分，是一个字符串。以反引号包含的部分，是一个 identifier。注意下面的区别： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON 'test'.* TO 'genius'@'localhost'; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the -manual that corresponds to your MySQL server version for the right -syntax to use near ''test'.* to 'genius'@'localhost'' at line 1 -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON `test`.* TO 'genius'@'localhost'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -如果想将一些特殊的关键字做为表名，可以用反引号包含起来。比如： - -{{< copyable "sql" >}} - -```sql -mysql> CREATE TABLE `select` (id int); -``` - -``` -Query OK, 0 rows affected (0.27 sec) -``` - -### 查看为用户分配的权限 - -`SHOW GRANTS` 语句可以查看为用户分配了哪些权限。例如： - -查看当前用户的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS; -``` - -查看某个特定用户的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS for 'root'@'%'; -``` - -更精确的方式，可以通过直接查看授权表的数据实现。比如想知道，名为 `test@%` 的用户是否拥有对 `db1.t` 的 `Insert` 权限： - -1. 先查看该用户是否拥有全局 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT Insert_priv FROM mysql.user WHERE user='test' AND host='%'; - ``` - -2. 如果没有，再查看该用户是否拥有 `db1` 数据库级别的 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT Insert_priv FROM mysql.db WHERE user='test' AND host='%'; - ``` - -3. 如果仍然没有，则继续判断是否拥有 `db1.t` 这张表的 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT table_priv FROM mysql.tables_priv WHERE user='test' AND host='%' AND db='db1'; - ``` - -## TiDB 各操作需要的权限 - -TiDB 用户目前拥有的权限可以在 `INFORMATION_SCHEMA.USER_PRIVILEGES` 表中查找到。 - -| 权限类型 | 权限变量名 | 权限简述 | -| :------------ | :------------ | :---------------------- | -| ALL | AllPriv | 所有权限 | -| Drop | DropPriv | 删除 schema/table | -| Index | IndexPriv | 创建/删除 index | -| Alter | AlterPriv | 执行 `ALTER` 语句 | -| Super | SuperPriv | 所有权限 | -| Grant | GrantPriv | 授予其他用户权限 | -| Create | CreatePriv | 创建 schema/table | -| Select | SelectPriv | 读取表内容 | -| Insert | InsertPriv | 插入数据到表 | -| Update | UpdatePriv | 更新表中数据 | -| Delete | DeletePriv | 删除表中数据 | -| Trigger | TriggerPriv | 尚未使用 | -| Process | ProcessPriv | 显示正在运行的任务 | -| Execute | ExecutePriv | 执行 execute 语句 | -| Drop Role | DropRolePriv | 执行 drop role | -| Show View | ShowViewPriv | 执行 show create view | -| References | ReferencesPriv | 尚未使用 | -| Create View | CreateViewPriv | 创建视图 | -| Create User | CreateUserPriv | 创建用户 | -| Create Role | CreateRolePriv | 执行 create role | -| Show Databases | ShowDBPriv | 显示 database 内的表情况 | - -### ALTER - -- 对于所有的 `ALTER` 语句，均需要用户对所操作的表拥有 `ALTER` 权限。 -- 除 `ALTER...DROP` 和 `ALTER...RENAME TO` 外，均需要对所操作表拥有 `INSERT` 和 `CREATE` 权限。 -- 对于 `ALTER...DROP` 语句，需要对表拥有 `DROP` 权限。 -- 对于 `ALTER...RENAME TO` 语句，需要对重命名前的表拥有 `DROP` 权限，对重命名后的表拥有 `CREATE` 和 `INSERT` 权限。 - -> **注意：** -> -> 根据 MySQL 5.7 文档中的说明，对表进行 `ALTER` 操作需要 `INSERT` 和 `CREATE` 权限，但在 MySQL 5.7.25 版本实际情况中，该操作仅需要 `ALTER` 权限。目前，TiDB 中的 `ALTER` 权限与 MySQL 实际行为保持一致。 - -### CREATE DATABASE - -需要对数据库拥有 `CREATE` 权限。 - -### CREATE INDEX - -需要对所操作的表拥有 `INDEX` 权限。 - -### CREATE TABLE - -需要对所操作的表拥有 `CREATE` 权限；若使用 `CREATE TABLE...LIKE...` 需要对相关的表拥有 `SELECT` 权限。 - -### CREATE VIEW - -需要拥有 `CREATE VIEW` 权限。 - -> **注意：** -> -> 如果当前登录用户与创建视图的用户不同，除需要 `CREATE VIEW` 权限外，还需要 `SUPER` 权限。 - -### DROP DATABASE - -需要对数据库拥有 `DROP` 权限。 - -### DROP INDEX - -需要对所操作的表拥有 `INDEX` 权限。 - -### DROP TABLES - -需要对所操作的表拥有 `DROP` 权限。 - -### TRUNCATE TABLE - -需要对所操作的表拥有 `DROP` 权限。 - -### RENAME TABLE - -需要对重命名前的表拥有 `ALTER` 和 `DROP` 权限，对重命名后的表拥有 `CREATE` 和 `INSERT` 权限。 - -### ANALYZE TABLE - -需要对所操作的表拥有 `INSERT` 和 `SELECT` 权限。 - -### SHOW - -`SHOW CREATE TABLE` 需要任意一种权限。 - -`SHOW CREATE VIEW` 需要 `SHOW VIEW` 权限。 - -### CREATE ROLE/USER - -`CREATE ROLE` 需要 `CREATE ROLE` 权限。 - -`CREATE USER` 需要 `CREATE USER` 权限 - -### DROP ROLE/USER - -`DROP ROLE` 需要 `DROPROLE` 权限。 - -`DROP USER` 需要 `CREATEUSER` 权限 - -### ALTER USER - -`ALTER USER` 需要 `CREATEUSER` 权限。 - -### GRANT - -`GRANT` 需要 `GRANT` 权限并且拥有 `GRANT` 所赋予的权限。 - -### REVOKE - -`REVOKE` 需要 `SUPER` 权限。 - -## 权限系统的实现 - -### 授权表 - -以下几张系统表是非常特殊的表，权限相关的数据全部存储在这几张表内。 - -- `mysql.user`：用户账户，全局权限 -- `mysql.db`：数据库级别的权限 -- `mysql.tables_priv`：表级别的权限 -- `mysql.columns_priv`：列级别的权限，当前暂不支持 - -这几张表包含了数据的生效范围和权限信息。例如，`mysql.user` 表的部分数据： - -{{< copyable "sql" >}} - -```sql -SELECT User,Host,Select_priv,Insert_priv FROM mysql.user LIMIT 1; -``` - -``` -+------|------|-------------|-------------+ -| User | Host | Select_priv | Insert_priv | -+------|------|-------------|-------------+ -| root | % | Y | Y | -+------|------|-------------|-------------+ -1 row in set (0.00 sec) -``` - -这条记录中，`Host` 和 `User` 决定了 root 用户从任意主机 (%) 发送过来的连接请求可以被接受，而 `Select_priv` 和 `Insert_priv` 表示用户拥有全局的 `Select` 和 `Insert` 权限。`mysql.user` 这张表里面的生效范围是全局的。 - -`mysql.db` 表里面包含的 `Host` 和 `User` 决定了用户可以访问哪些数据库，权限列的生效范围是数据库。 - -理论上，所有权限管理相关的操作，都可以通过直接对授权表的 CRUD 操作完成。 - -实现层面其实也只是包装了一层语法糖。例如删除用户会执行： - -{{< copyable "sql" >}} - -```sql -DELETE FROM mysql.user WHERE user='test'; -``` - -但是，不推荐手动修改授权表，建议使用 `DROP USER` 语句： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'; -``` - -### 连接验证 - -当客户端发送连接请求时，TiDB 服务器会对登录操作进行验证。验证过程先检查 `mysql.user` 表，当某条记录的 `User` 和 `Host` 和连接请求匹配上了，再去验证 Password。用户身份基于两部分信息，发起连接的客户端的 `Host`，以及用户名 `User`。如果 `User` 不为空，则用户名必须精确匹配。 - -User+Host 可能会匹配 `user` 表里面多行，为了处理这种情况，`user` 表的行是排序过的，客户端连接时会依次去匹配，并使用首次匹配到的那一行做权限验证。排序是按 `Host` 在前，`User` 在后。 - -### 请求验证 - -连接成功之后，请求验证会检测执行操作是否拥有足够的权限。 - -对于数据库相关请求 (`INSERT`，`UPDATE`)，先检查 `mysql.user` 表里面的用户全局权限，如果权限够，则直接可以访问。如果全局权限不足，则再检查 `mysql.db` 表。 - -`user` 表的权限是全局的，并且不管默认数据库是哪一个。比如 `user` 里面有 `DELETE` 权限，任何一行，任何的表，任何的数据库。 - -`db`表里面，User 为空是匹配匿名用户，User 里面不能有通配符。Host 和 Db 列里面可以有 `%` 和 `_`，可以模式匹配。 - -`user` 和 `db` 读到内存也是排序的。 - -`tables_priv` 和 `columns_priv` 中使用 `%` 是类似的，但是在`Db`, `Table_name`, `Column_name` 这些列不能包含 `%`。加载进来时排序也是类似的。 - -### 生效时机 - -TiDB 启动时，将一些权限检查的表加载到内存，之后使用缓存的数据来验证权限。系统会周期性的将授权表从数据库同步到缓存，生效则是由同步的周期决定，目前这个值设定的是 5 分钟。 - -修改了授权表，如果需要立即生效，可以手动调用： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -### 限制和约束 - -一些使用频率偏低的权限当前版本的实现中还未做检查，比如 `FILE`/`USAGE`/`SHUTDOWN`/`EXECUTE`/`PROCESS`/`INDEX` 等等，未来会陆续完善。 - -现阶段对权限的支持还没有做到 column 级别。 diff --git a/v3.0/reference/security/role-based-access-control.md b/v3.0/reference/security/role-based-access-control.md deleted file mode 100644 index 5e33e8516ae8..000000000000 --- a/v3.0/reference/security/role-based-access-control.md +++ /dev/null @@ -1,386 +0,0 @@ ---- -title: 基于角色的访问控制 -category: reference ---- - -# 基于角色的访问控制 - -TiDB 的基于角色的访问控制 (RBAC) 系统的实现类似于 MySQL 8.0 的 RBAC 系统。TiDB 兼容大部分 MySQL RBAC 系统的语法。 - -本文档主要介绍 TiDB 基于角色的访问控制相关操作及实现。 - -## 角色访问控制相关操作 - -角色是一系列权限的集合。用户可以创建角色、删除角色、将权限赋予角色；也可以将角色授予给其他用户，被授予的用户在启用角色后，可以得到角色所包含的权限。 - -### 创建角色 - -创建角色 r_1 和 r_2： - -{{< copyable "sql" >}} - -```sql -CREATE ROLE `r_1`@`%`, `r_2`@`%`; -``` - -角色名的格式和规范可以参考 [TiDB 用户账户管理](/v3.0/reference/security/user-account-management.md)。 - -角色会被保存在 `mysql.user` 表中，如果表中有同名角色或用户，角色会创建失败并报错。 -创建角色的用户需要拥有 `CREATE ROLE` 或 `CREATE USER` 权限。 - -### 删除角色 - -删除角色 r_1 和 r_2： - -{{< copyable "sql" >}} - -```sql -DROP ROLE `r_1`@`%`, `r_2`@`%`; -``` - -这个操作会清除角色在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录，解除和其相关的授权关系。 -执行删除角色的用户需要拥有 `DROP ROLE` 或 `DROP USER` 权限。 - -### 授予角色权限 - -为角色授予权限和为用户授予权限操作相同，可参考 [TiDB 权限管理](/v3.0/reference/security/privilege-system.md)。 - -为 `analyst` 角色授予数据库 `test` 的读权限： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO 'analyst'@'%'; -``` - -为 `analyst` 角色授予所有数据库的全部权限： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'analyst'@'%'; -``` - -### 收回权限 - -`REVOKE` 语句与 `GRANT` 对应： - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `test`.* FROM 'analyst'@'%'; -``` - -具体可参考 [TiDB 权限管理](/v3.0/reference/security/privilege-system.md)。 - -### 将角色授予给用户 - -将角色 role1 和 role2 同时授予给用户 `user1@localhost` 和 `user2@localhost`。 - -{{< copyable "sql" >}} - -```sql -GRANT 'role1', 'role2' TO 'user1'@'localhost', 'user2'@'localhost'; -``` - -用户执行将角色授予给其他用户或者收回角色的命令，需要用户拥有 `SUPER` 权限。 -将角色授予给用户时并不会启用该角色，启用角色需要额外的操作。 - -以下操作可能会形成一个“关系环”： - -```sql -CREATE USER 'u1', 'u2'; -CREATE ROLE 'r1', 'r2'; - -GRANT 'u1' TO 'u1'; -GRANT 'r1' TO 'r1'; - -GRANT 'r2' TO 'u2'; -GRANT 'u2' TO 'r2'; -``` - -TiDB 允许这种多层授权关系存在，可以使用多层授权关系实现权限继承。 - -### 收回角色 - -解除角色 role1、role2 与用户 `user1@localhost`、`user2@localhost` 的授权关系。 - -{{< copyable "sql" >}} - -```sql -REVOKE 'role1', 'role2' FROM 'user1'@'localhost', 'user2'@'localhost'; -``` - -解除角色授权具有原子性，如果在撤销授权操作中失败会回滚。 - -### 设置默认启用角色 - -角色在授予给用户之后，并不会生效；只有在用户启用了某些角色之后，才可以使用角色拥有的权限。 - -可以对用户设置默认启用的角色；用户在登陆时，默认启用的角色会被自动启用。 - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE - {NONE | ALL | role [, role ] ...} - TO user [, user ] -``` - -比如将 administrator 和 developer 设置为 `test@localhost` 的默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE administrator, developer TO 'test'@'localhost'; -``` - -将 `test@localhost` 的所有角色，设为其默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE ALL TO 'test'@'localhost'; -``` - -关闭 `test@localhost` 的所有默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE NONE TO 'test'@'localhost'; -``` - -需要注意的是，设置为默认启用角色的角色必须已经授予给那个用户。 - -### 在当前 session 启用角色 - -除了使用 `SET DEFAULT ROLE` 启用角色外，TiDB 还提供让用户在当前 session 启用某些角色的功能。 - -```sql -SET ROLE { - DEFAULT - | NONE - | ALL - | ALL EXCEPT role [, role ] ... - | role [, role ] ... -} -``` - -例如，为当前用户启用角色 role1 和 role2 ，仅在当前 session 有效： - -{{< copyable "sql" >}} - -```sql -SET ROLE 'role1', 'role2'; -``` - -启用当前用户的默认角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE DEFAULT -``` - -启用授予给当前用户的所有角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE ALL -``` - -不启用任何角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE NONE -``` - -启用除 role1 和 role2 外的角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE ALL EXCEPT 'role1', 'role2' -``` - -> **注意：** -> -> 使用 `SET ROLE` 启用的角色只有在当前 session 才会有效。 - -### 查看当前启用角色 - -当前用户可以通过 `CURRENT_ROLE()` 函数查看当前用户启用了哪些角色。 - -例如，先对 `u1'@'localhost` 授予角色： - -{{< copyable "sql" >}} - -```sql -GRANT 'r1', 'r2' TO 'u1'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE ALL TO 'u1'@'localhost'; -``` - -在 u1 登陆后： - -{{< copyable "sql" >}} - -```sql -SELECT CURRENT_ROLE(); -``` - -``` -+-------------------+ -| CURRENT_ROLE() | -+-------------------+ -| `r1`@`%`,`r2`@`%` | -+-------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SET ROLE 'r1'; SELECT CURRENT_ROLE(); -``` - -``` -+----------------+ -| CURRENT_ROLE() | -+----------------+ -| `r1`@`%` | -+----------------+ -``` - -### 查看角色拥有的权限 - -可以通过 `SHOW GRANTS` 语句查看用户被授予了哪些角色。 -当用户查看其他用户权限相关信息时，需要对 `mysql` 数据库拥有 `SELECT` 权限。 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost'; -``` - -``` -+---------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------+ -``` - -可以通过使用 `SHOW GRANTS` 的 `USING` 选项来查看角色对应的权限。 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r1'; -``` - -``` -+---------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Select ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r2'; -``` - -``` -+-------------------------------------------------------------+ -| Grants for u1@localhost | -+-------------------------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+-------------------------------------------------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r1', 'r2'; -``` - -``` -+---------------------------------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Select, Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------------------------------+ -``` - -可以使用 `SHOW GRANTS` 或 `SHOW GRANTS FOR CURRENT_USER()` 查看当前用户的权限。 -这两个语句有细微的差异，`SHOW GRANTS` 会显示当前用户的启用角色的权限，而 `SHOW GRANTS FOR CURRENT_USER()` 则不会显示启用角色的权限。 - -### 授权表 - -在原有的四张[系统权限表](/v3.0/reference/security/privilege-system.md#授权表)的基础上，角色访问控制引入了两张新的系统表： - -- `mysql.role_edges`：记录角色与用户的授权关系 -- `mysql.default_roles`：记录每个用户默认启用的角色 - -以下是 `mysql.role_edges` 所包含的数据。 - -{{< copyable "sql" >}} - -```sql -select * from mysql.role_edges; -``` - -``` -+-----------+-----------+---------+---------+-------------------+ -| FROM_HOST | FROM_USER | TO_HOST | TO_USER | WITH_ADMIN_OPTION | -+-----------+-----------+---------+---------+-------------------+ -| % | r_1 | % | u_1 | N | -+-----------+-----------+---------+---------+-------------------+ -1 row in set (0.00 sec) -``` - -其中 `FROM_HOST` 和 `FROM_USER` 分别表示角色的主机名和用户名，`TO_HOST` 和 `TO_USER` 分别表示被授予角色的用户的主机名和用户名。 - -`mysql.default_roles` 中包含了每个用户默认启用了哪些角色。 - -{{< copyable "sql" >}} - -```sql -select * from mysql.default_roles; -``` - -``` -+------+------+-------------------+-------------------+ -| HOST | USER | DEFAULT_ROLE_HOST | DEFAULT_ROLE_USER | -+------+------+-------------------+-------------------+ -| % | u_1 | % | r_1 | -| % | u_1 | % | r_2 | -+------+------+-------------------+-------------------+ -2 rows in set (0.00 sec) -``` - -`HOST` 和 `USER` 分别表示用户的主机名和用户名，`DEFAULT_ROLE_HOST` 和 `DEFAULT_ROLE_USER` 分别表示默认启用的角色的主机名和用户名。 - -### 其他 - -由于基于角色的访问控制模块和用户管理以及权限管理结合十分紧密，因此需要参考一些操作的细节： - -- [TiDB 权限管理](/v3.0/reference/security/privilege-system.md) -- [TiDB 用户账户管理](/v3.0/reference/security/user-account-management.md) diff --git a/v3.0/reference/security/user-account-management.md b/v3.0/reference/security/user-account-management.md deleted file mode 100644 index b34f7b5fd656..000000000000 --- a/v3.0/reference/security/user-account-management.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: TiDB 用户账户管理 -category: reference -aliases: ['/docs-cn/sql/user-account-management/'] ---- - -# TiDB 用户账户管理 - -本文档主要介绍如何管理 TiDB 用户账户。 - -## 用户名和密码 - -TiDB 将用户账户存储在 `mysql.user` 系统表里面。每个账户由用户名和 host 作为标识。每个账户可以设置一个密码。 - -通过 MySQL 客户端连接到 TiDB 服务器，通过指定的账户和密码登录： - -{{< copyable "shell-regular" >}} - -``` -mysql --port 4000 --user xxx --password -``` - -使用缩写的命令行参数则是： - -{{< copyable "shell-regular" >}} - -``` -mysql -P 4000 -u xxx -p -``` - -## 添加用户 - -添加用户有两种方式： - -* 通过标准的用户管理的 SQL 语句创建用户以及授予权限，比如 `CREATE USER` 和 `GRANT`。 -* 直接通过 `INSERT`、`UPDATE` 和 `DELETE` 操作授权表。 - -推荐使用第一种方式。第二种方式修改容易导致一些不完整的修改，因此不推荐。还有另一种可选方式是使用第三方工具的图形化界面工具。 - -{{< copyable "sql" >}} - -```sql -CREATE USER [IF NOT EXISTS] - user [auth_spec] [, user [auth_spec]] ... -``` - -{{< copyable "sql" >}} - -```sql -auth_spec: { - IDENTIFIED BY 'auth_string' - | IDENTIFIED BY PASSWORD 'hash_string' -} -``` - -* `IDENTIFIED BY 'auth_string'`：设置登录密码时，`auth_string` 会被 TiDB 经过加密存储在 `mysql.user` 表中。 -* `IDENTIFIED BY PASSWORD 'hash_string'`：设置登录密码，`hash_string` 是一个类似于 `*EBE2869D7542FCE37D1C9BBC724B97BDE54428F1` 的 41 位字符串，会被 TiDB 直接存储在 `mysql.user` 表中，该字符串可以通过 `SELECT password('auth_string')` 加密得到。 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'127.0.0.1' IDENTIFIED BY 'xxx'; -``` - -TiDB 的用户账户名由一个用户名和一个主机名组成。账户名的语法为 `'user_name'@'host_name'`。 - -- `user_name` 大小写敏感。 -- `host_name` 可以是一个主机名或 IP 地址。主机名或 IP 地址中允许使用通配符 `%` 和 `_`。例如，名为 `'%'` 的主机名可以匹配所有主机，`'192.168.1.%'` 可以匹配子网中的所有主机。 - -host 支持模糊匹配，比如： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'192.168.10.%'; -``` - -允许 `test` 用户从 `192.168.10` 子网的任何一个主机登录。 - -如果没有指定 host，则默认是所有 IP 均可登录。如果没有指定密码，默认为空： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'; -``` - -等价于： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'%' IDENTIFIED BY ''; -``` - -下面的例子用 `CREATE USER` 和 `GRANT` 语句创建了四个账户： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'localhost' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'localhost' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'%' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'%' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'dummy'@'localhost'; -``` - -使用 `SHOW GRANTS` 可以看到为一个用户授予的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'admin'@'localhost'; -``` - -``` -+-----------------------------------------------------+ -| Grants for admin@localhost | -+-----------------------------------------------------+ -| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' | -+-----------------------------------------------------+ -``` - -## 删除用户 - -使用 `DROP USER` 语句可以删除用户，例如： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'@'localhost'; -``` - -这个操作会清除用户在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录。 - -## 保留用户账户 - -TiDB 在数据库初始化时会生成一个 `'root'@'%'` 的默认账户。 - -## 设置资源限制 - -暂不支持。 - -## 设置密码 - -TiDB 将密码存在 `mysql.user` 系统数据库里面。只有拥有 `CREATE USER` 权限，或者拥有 `mysql` 数据库权限（`INSERT` 权限用于创建，`UPDATE` 权限用于更新）的用户才能够设置或修改密码。 - -- 在 `CREATE USER` 创建用户时可以通过 `IDENTIFIED BY` 指定密码： - - {{< copyable "sql" >}} - - ```sql - CREATE USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -- 为一个已存在的账户修改密码，可以通过 `SET PASSWORD FOR` 或者 `ALTER USER` 语句完成： - - {{< copyable "sql" >}} - - ```sql - SET PASSWORD FOR 'root'@'%' = 'xxx'; - ``` - - 或者： - - {{< copyable "sql" >}} - - ```sql - ALTER USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -## 忘记 `root` 密码 - -1. 修改配置文件，在 `security` 部分添加 `skip-grant-table`： - - {{< copyable "" >}} - - ``` - [security] - skip-grant-table = true - ``` - -2. 然后使用 `root` 登录后修改密码： - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -## `FLUSH PRIVILEGES` - -如果授权表已被直接修改，运行如下命令可使改动立即生效： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -详情参见[权限管理](/v3.0/reference/security/privilege-system.md)。 diff --git a/v3.0/reference/sql/character-set.md b/v3.0/reference/sql/character-set.md deleted file mode 100644 index cfe919977b3d..000000000000 --- a/v3.0/reference/sql/character-set.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: 字符集支持 -category: reference -aliases: ['/docs-cn/sql/character-set-support/'] ---- - -# 字符集支持 - -名词解释，下面的阐述中会交错使用中文或者英文，请互相对照： - -* Character Set：字符集 -* Collation：排序规则 - -目前 `TiDB` 支持以下字符集： - -{{< copyable "sql" >}} - -```sql -SHOW CHARACTER SET; -``` - -``` -+---------|---------------|-------------------|--------+ -| Charset | Description | Default collation | Maxlen | -+---------|---------------|-------------------|--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------|---------------|-------------------|--------+ -5 rows in set (0.00 sec) -``` - -> **注意：** -> -> - 在 `TiDB` 中 `utf8` 被当做成了 `utf8mb4` 来处理。 -> - 每种字符集都对应一个默认的 Collation，当前有且仅有一个。 - -对于字符集来说，至少会有一个 Collation（排序规则）与之对应。而大部分字符集实际上会有多个 Collation。利用以下的语句可以查看： - -{{< copyable "sql" >}} - -```sql -SHOW COLLATION WHERE Charset = 'latin1'; -``` - -``` -+-------------------|---------|------|---------|----------|---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+-------------------|---------|------|---------|----------|---------+ -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -+-------------------|---------|------|---------|----------|---------+ -8 rows in set (0.00 sec) -``` - -`latin1` Collation（排序规则）分别有以下含义： - -| Collation | 含义 | -|:------------------|:----------------------------------| -| latin1_bin | latin1 编码的二进制表示 | -| latin1_danish_ci | 丹麦语/挪威语，不区分大小写 | -| latin1_general_ci | 多种语言的 (西欧)，不区分大小写 | -| latin1_general_cs | 多种语言的 (ISO 西欧)，区分大小写 | -| latin1_german1_ci | 德国 DIN-1 (字典序)，不区分大小写 | -| latin1_german2_ci | 德国 DIN-2，不区分大小写 | -| latin1_spanish_ci | 现代西班牙语，不区分大小写 | -| latin1_swedish_ci | 瑞典语/芬兰语，不区分大小写 | - -每一个字符集，都有一个默认的 Collation，例如 `utf8` 的默认 Collation 就为 `utf8_bin`。 - -> **注意：** -> -> `TiDB` 目前的 Collation 只支持区分大小写的比较排序规则。 - -## Collation 命名规则 - -`TiDB` 的 Collation 遵循着如下的命名规则： - -* Collation 的前缀是它相应的字符集，通常之后会跟着一个或者更多的后缀来表名其他的排序规则， 例如：utf8_general_ci 和 lation1_swedish_ci 是 utf8 - 和 latin1 字符集的 Collation。但是 binary 字符集只有一个 Collation，就是 binary。 -* 一个语言对应的 Collation 会包含语言的名字，例如 utf8_turkish_ci 和 utf8_hungarian_ci 是依据 Turkish(土耳其语) 和 Hungarian(匈牙利语) 的排序规则来排序。 -* Collation 的后缀表示了 Collation 是否区分大小写和是否区分口音。下面的表展示了这些特性： - -| 后缀 | 含义 | -|:-----|:---------------------------------| -| \_ai | 口音不敏感（Accent insensitive） | -| \_as | 口音敏感 （Accent sensitive） | -| \_ci | 大小写不敏感 | -| \_cs | 大小写敏感 | - -> **注意：** -> -> 目前为止 TiDB 只支持部分以上提到的 Collation。 - -## 集群 Character Set 和 Collation - -暂不支持 - -## 数据库 Character Set 和 Collation - -每个数据库都有相应的 Character Set 和 Collation，数据库的 Character Set 和 Collation 可以通过以下语句来设置： - -```sql -CREATE DATABASE db_name - [[DEFAULT] CHARACTER SET charset_name] - [[DEFAULT] COLLATE collation_name] - -ALTER DATABASE db_name - [[DEFAULT] CHARACTER SET charset_name] - [[DEFAULT] COLLATE collation_name] -``` - -在这里 `DATABASE` 可以跟 `SCHEMA` 互换使用。 - -不同的数据库之间可以使用不一样的字符集和排序规则。 - -通过系统变量 `character_set_database` 和 `collation_database` 可以查看到当前数据库的字符集以及排序规则： - -{{< copyable "sql" >}} - -```sql -create schema test1 character set utf8 COLLATE uft8_general_ci; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -use test1; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SELECT @@character_set_database, @@collation_database; -``` - -``` -+--------------------------|----------------------+ -| @@character_set_database | @@collation_database | -+--------------------------|----------------------+ -| utf8 | uft8_general_ci | -+--------------------------|----------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -create schema test2 character set latin1 COLLATE latin1_general_ci; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -use test2; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SELECT @@character_set_database, @@collation_database; -``` - -``` -+--------------------------|----------------------+ -| @@character_set_database | @@collation_database | -+--------------------------|----------------------+ -| latin1 | latin1_general_ci | -+--------------------------|----------------------+ -1 row in set (0.00 sec) -``` - -在 INFORMATION_SCHEMA 中也可以查看到这两个值： - -{{< copyable "sql" >}} - -```sql -SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME -FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = 'db_name'; -``` - -## 表的 Character Set 和 Collation - -表的 Character Set 和 Collation 可以通过以下语句来设置： - -```sql -CREATE TABLE tbl_name (column_list) - [[DEFAULT] CHARACTER SET charset_name] - [COLLATE collation_name]] - -ALTER TABLE tbl_name - [[DEFAULT] CHARACTER SET charset_name] - [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1(a int) CHARACTER SET utf8 COLLATE utf8_general_ci; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -如果表的字符集和排序规则没有设置，那么数据库的字符集和排序规则就作为其默认值。 - -## 列的 Character Set 和 Collation - -列的 Character Set 和 Collation 的语法如下： - -```sql -col_name {CHAR | VARCHAR | TEXT} (col_length) - [CHARACTER SET charset_name] - [COLLATE collation_name] - -col_name {ENUM | SET} (val_list) - [CHARACTER SET charset_name] - [COLLATE collation_name] -``` - -如果列的字符集和排序规则没有设置，那么表的字符集和排序规则就作为其默认值。 - -## 字符串 Character Sets 和 Collation - -每一字符串字符文字有一个字符集和一个比较排序规则，在使用字符串时指，此选项可选，如下： - -```sql -[_charset_name]'string' [COLLATE collation_name] -``` - -示例，如下： - -{{< copyable "sql" >}} - -```sql -SELECT 'string'; -SELECT _latin1'string'; -SELECT _latin1'string' COLLATE latin1_danish_ci; -``` - -规则，如下： - -* 规则1： 指定 CHARACTER SET charset_name 和 COLLATE collation_name，则直接使用 CHARACTER SET charset_name 和COLLATE collation_name。 -* 规则2: 指定 CHARACTER SET charset_name 且未指定 COLLATE collation_name，则使用 CHARACTER SET charset_name 和 CHARACTER SET charset_name 默认的排序比较规则。 -* 规则3: CHARACTER SET charset_name 和 COLLATE collation_name 都未指定，则使用 character_set_connection 和 collation_connection 系统变量给出的字符集和比较排序规则。 - -## 客户端连接的 Character Sets 和 Collations - -* 服务器的字符集和排序规则可以通过系统变量 `character_set_server` 和 `collation_server` 获取。 -* 数据库的字符集和排序规则可以通过环境变量 `character_set_database` 和 `collation_database` 获取。 - -对于每一个客户端的连接，也有相应的变量表示字符集和排序规则：`character_set_connection` 和 `collation_connection`。 - -`character_set_client` 代表客户端的字符集。在返回结果前，服务端会把结果根据 `character_set_results` 转换成对应的字符集。包括结果的元信息等。 - -可以用以下的语句来影响这些跟客户端相关的字符集变量： - -* `SET NAMES 'charset_name' [COLLATE 'collation_name']` - -`SET NAMES` 用来设定客户端会在之后的请求中使用的字符集。`SET NAMES utf8` 表示客户端会在接下来的请求中，都使用 utf8 字符集。服务端也会在之后返回结果的时候使用 utf8 字符集。 -`SET NAMES 'charset_name'` 语句其实等于下面语句的组合： - -{{< copyable "sql" >}} - -```sql -SET character_set_client = charset_name; -SET character_set_results = charset_name; -SET character_set_connection = charset_name; -``` - -`COLLATE` 是可选的，如果没有提供，将会用 charset_name 默认的 Collation。 - -* `SET CHARACTER SET 'charset_name'` - -跟 `SET NAMES` 类似，等价于下面语句的组合： - -{{< copyable "sql" >}} - -```sql -SET character_set_client = charset_name; -SET character_set_results = charset_name; -SET collation_connection = @@collation_database; -``` - -## 集群，服务器，数据库，表，列，字符串 Character Sets 和 Collation 优化级 - -字符串 => 列 => 表 => 数据库 => 服务器 => 集群 - -## Character Sets 和 Collation 通用选择规则 - -* 规则1： 指定 CHARACTER SET charset_name 和 COLLATE collation_name，则直接使用 CHARACTER SET charset_name 和COLLATE collation_name。 -* 规则2: 指定 CHARACTER SET charset_name 且未指定 COLLATE collation_name，则使用 CHARACTER SET charset_name 和 CHARACTER SET charset_name 默认的排序比较规则。 -* 规则3: CHARACTER SET charset_name 和 COLLATE collation_name 都未指定，则使用更高优化级给出的字符集和排序比较规则。 - -## 字符合法性检查 - -当指定的字符集为 utf8 或 utf8mb4 时，TiDB 仅支持合法的 utf8 字符。对于不合法的字符，会报错：`incorrect utf8 value`。该字符合法性检查与 MySQL 8.0 兼容，与 MySQL 5.7 及以下版本不兼容。 - -如果不希望报错，可以通过 `set @@tidb_skip_utf8_check=1;` 跳过字符检查。 - -更多细节，参考 [Connection Character Sets and Collations](https://dev.mysql.com/doc/refman/5.7/en/charset-connection.html)。 diff --git a/v3.0/reference/sql/constraints.md b/v3.0/reference/sql/constraints.md deleted file mode 100644 index e9c8fbd66d06..000000000000 --- a/v3.0/reference/sql/constraints.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: 约束 -category: reference -aliases: ['/docs-cn/sql/constraints/'] ---- - -# 约束 - -TiDB 支持的基本约束与 MySQL 的基本相同，但有以下区别： - -- 默认对唯一约束进行[惰性检查](/v3.0/reference/transactions/overview.md#事务的惰性检查)。通过在事务提交时再进行批量检查，TiDB 能够减少网络开销、提升性能。您可通过设置 `tidb_constraint_check_in_place` 为 `TRUE` 改变此行为。 - -- TiDB 支持创建外键约束，但不会在 DML 语句中对外键进行约束（即外键约束不生效）。 - -## 外键约束 - -目前，TiDB 支持创建外键。例如： - -```sql -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - doc JSON -); -CREATE TABLE orders ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - user_id INT NOT NULL, - doc JSON, - FOREIGN KEY fk_user_id (user_id) REFERENCES users(id) -); -``` - -{{< copyable "sql" >}} - -```sql -SELECT table_name, column_name, constraint_name, referenced_table_name, referenced_column_name -FROM information_schema.key_column_usage WHERE table_name IN ('users', 'orders'); -``` - -``` -+------------+-------------+-----------------+-----------------------+------------------------+ -| table_name | column_name | constraint_name | referenced_table_name | referenced_column_name | -+------------+-------------+-----------------+-----------------------+------------------------+ -| users | id | PRIMARY | NULL | NULL | -| orders | id | PRIMARY | NULL | NULL | -| orders | user_id | fk_user_id | users | id | -+------------+-------------+-----------------+-----------------------+------------------------+ -3 rows in set (0.00 sec) -``` - -TiDB 也支持使用 `ALTER TABLE` 命令来删除外键（`DROP FOREIGN KEY`）和添加外键（`ADD FOREIGN KEY`）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE orders DROP FOREIGN KEY fk_user_id; -ALTER TABLE orders ADD FOREIGN KEY fk_user_id (user_id) REFERENCES users(id); -``` - -### 注意 - -* TiDB 支持外键是为了在将其他数据库迁移到 TiDB 时，不会因为此语法报错。但是，TiDB 不会在 DML 语句中对外键进行约束。例如，即使 `users` 表中不存在 `id=123` 的记录，下列事务也能提交成功： - - ``` - START TRANSACTION; - INSERT INTO orders (user_id, doc) VALUES (123, NULL); - COMMIT; - ``` - -* TiDB 在执行 `SHOW CREATE TABLE` 语句的结果中不显示外键信息。 - -## 非空约束 - -TiDB 支持的非空约束规则与 MySQL 支持的一致。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - age INT NOT NULL, - last_login TIMESTAMP -); -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,123,NOW()); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,NULL,NOW()); -``` - -``` -ERROR 1048 (23000): Column 'age' cannot be null -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,123,NULL); -``` - -``` -Query OK, 1 row affected (0.03 sec) -``` - -* 第一条 `INSERT` 语句成功，因为对于定义为 `AUTO_INCREMENT` 的列，允许 `NULL` 作为其特殊值。TiDB 将为其分配下一个自动值。 - -* 第二条 `INSERT` 语句失败，因为 `age` 列被定义为 `NOT NULL`。 - -* 第三条 `INSERT` 语句成功，因为 `last_login` 列没有被明确地指定为 `NOT NULL`。默认允许 `NULL` 值。 - -## 主键约束 - -TiDB 支持的主键约束规则与 MySQL 支持的相似。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 (a INT NULL PRIMARY KEY); -``` - -``` -ERROR 1171 (42000): All parts of a PRIMARY KEY must be NOT NULL; if you need NULL in a key, use UNIQUE instead -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t3 (a INT NOT NULL PRIMARY KEY, b INT NOT NULL PRIMARY KEY); -``` - -``` -ERROR 1068 (42000): Multiple primary key defined -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t4 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b)); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -* 表 `t2` 创建失败，因为定义为主键的列 `a` 不能允许 `NULL` 值。 -* 表 `t3` 创建失败，因为一张表只能有一个主键。 -* 表 `t4` 创建成功，因为虽然只能有一个主键，但 TiDB 支持定义一个多列组合作为复合主键。 - -除上述规则外，TiDB 还强加了另一个限制，即一旦一张表创建成功，其主键就不能再改变。 - -## 唯一约束 - -在 TiDB 中，默认会对唯一约束进行惰性检查。通过直到事务提交时才进行批量检查，TiDB 能够减少网络通信开销。例如： - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -``` - -``` -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('steve'),('elizabeth'); -``` - -``` -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -``` - -* 第一条 `INSERT` 语句不会导致重复键错误，这同 MySQL 的规则一致。该检查将推迟到事务提交时才会进行。 - -如果将 `tidb_constraint_check_in_place` 更改为 `TRUE`，则会在执行语句时就对唯一约束进行检查。例如： - -```sql -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -``` - -{{< copyable "sql" >}} - -```sql -SET tidb_constraint_check_in_place = TRUE; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -``` - -``` -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -.. -``` - -* 第一条 `INSERT` 语句导致了重复键错误。这会造成额外的网络通信开销，并可能降低插入操作的吞吐量。 diff --git a/v3.0/reference/sql/data-types/date-and-time.md b/v3.0/reference/sql/data-types/date-and-time.md deleted file mode 100644 index 6645d949bd38..000000000000 --- a/v3.0/reference/sql/data-types/date-and-time.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 日期和时间类型 -category: reference ---- - -# 日期和时间类型 - -TiDB 支持 MySQL 所有的日期和时间类型，包括 DATE、DATETIME、TIMESTAMP、TIME 以及 YEAR，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-types.html)文档。 - -## 类型定义 - -### `DATE` 类型 - -`DATE` 类型的格式为 `YYYY-MM-DD`，支持的范围是 `1000-01-01` 到 `9999-12-31`。 - -{{< copyable "sql" >}} - -```sql -DATE -``` - -### `TIME` 类型 - -`TIME` 类型的格式为 `HH:MM:SS[.fraction]`，支持的范围是 `-838:59:59.000000` 到 `838:59:59.000000`。`TIME` 不仅可用于指示一天内的时间，还可用于指两个事件之间的时间间隔。`fsp` 参数表示秒精度，取值范围为：0 ~ 6，默认值为 0。 - -{{< copyable "sql" >}} - -```sql -TIME[(fsp)] -``` - -> **注意：** -> -> 注意 `TIME` 的缩写形式。例如，'11:12' 表示 '11:12:00' 而不是 '00:11:12'。但是，'1112' 表示 '00:11:12'。这些差异取决于 `:` 字符的存在与否。 - -### `DATETIME` 类型 - -`DATETIME` 类型是日期和时间的组合，格式为 `YYYY-MM-DD HH:MM:SS[.fraction]`。支持的范围是 `1000-01-01 00:00:00.000000` 到 `9999-12-31 23:59:59.000000`。`fsp` 参数表示秒精度，取值范围为 0~6，默认值为 0。 - -{{< copyable "sql" >}} - -```sql -DATETIME[(fsp)] -``` - -### `TIMESTAMP` 类型 - -`TIMESTAMP` 类型包含日期和时间，支持的范围是 `1970-01-01 00:00:01.000000` 到 `2038-01-19 03:14:07.999999`。`fsp` 参数表示秒精度，取值范围为 0~6，默认值为 0。在 `TIMESTAMP` 中，不允许零出现在月份部分或日期部分，唯一的例外是零值本身 '0000-00-00 00:00:00'。 - -{{< copyable "sql" >}} - -```sql -TIMESTAMP[(fsp)] -``` - -### `YEAR` 类型 - -`YEAR` 类型的格式为 'YYYY'，支持的值范围是 1901 到 2155，或零值 0000。 - -{{< copyable "sql" >}} - -```sql -YEAR[(4)] -``` diff --git a/v3.0/reference/sql/data-types/default-values.md b/v3.0/reference/sql/data-types/default-values.md deleted file mode 100644 index cfe82fb74cb7..000000000000 --- a/v3.0/reference/sql/data-types/default-values.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 数据类型的默认值 -category: reference ---- - -# 数据类型的默认值 - -在一个数据类型描述中的 `DEFAULT value` 段描述了一个列的默认值。这个默认值必须是常量，不可以是一个函数或者是表达式。但是对于时间类型，可以例外的使用 `NOW`、`CURRENT_TIMESTAMP`、`LOCALTIME`、`LOCALTIMESTAMP` 等函数作为 `DATETIME` 或者 `TIMESTAMP` 的默认值。 - -`BLOB`、`TEXT` 以及 `JSON` 不可以设置默认值。 - -如果一个列的定义中没有 `DEFAULT` 的设置。TiDB 按照如下的规则决定: - -* 如果该类型可以使用 `NULL` 作为值，那么这个列会在定义时添加隐式的默认值设置 `DEFAULT NULL`。 -* 如果该类型无法使用 `NULL` 作为值，那么这个列在定义时不会添加隐式的默认值设置。 - -对于一个设置了 `NOT NULL` 但是没有显式设置 `DEFAULT` 的列，当 `INSERT`、`REPLACE` 没有涉及到该列的值时，TiDB 根据当时的 `SQL_MODE` 进行不同的行为： - -* 如果此时是 `strict sql mode`，在事务中的语句会导致事务失败并回滚，非事务中的语句会直接报错。 -* 如果此时不是 `strict sql mode`，TiDB 会为这列赋值为列数据类型的隐式默认值。 - -此时隐式默认值的设置按照如下规则： - -* 对于数值类型，它们的默认值是 0。当有 `AUTO_INCREMENT` 参数时，默认值会按照增量情况赋予正确的值。 -* 对于除了时间戳外的日期时间类型，默认值会是该类型的“零值”。时间戳类型的默认值会是当前的时间。 -* 对于除枚举以外的字符串类型，默认值会是空字符串。对于枚举类型，默认值是枚举中的第一个值。 diff --git a/v3.0/reference/sql/data-types/json.md b/v3.0/reference/sql/data-types/json.md deleted file mode 100644 index 5bfc89554dc4..000000000000 --- a/v3.0/reference/sql/data-types/json.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: JSON 类型 -category: reference ---- - -# JSON 类型 - -JSON 类型可以存储 JSON 这种半结构化的数据，相比于直接将 JSON 存储为字符串，它的好处在于： - -1. 使用 Binary 格式进行序列化，对 JSON 的内部字段的查询、解析加快； -2. 多了 JSON 合法性验证的步骤，只有合法的 JSON 文档才可以放入这个字段中； - -JSON 字段本身上，并不能创建索引。相反，可以对 JSON 文档中的某个子字段创建索引。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE city ( - id INT PRIMARY KEY, - detail JSON, - population INT AS (JSON_EXTRACT(detail, '$.population')) -); -INSERT INTO city (id,detail) VALUES (1, '{"name": "Beijing", "population": 100}'); -SELECT id FROM city WHERE population >= 100; -``` diff --git a/v3.0/reference/sql/data-types/numeric.md b/v3.0/reference/sql/data-types/numeric.md deleted file mode 100644 index 08cd36538837..000000000000 --- a/v3.0/reference/sql/data-types/numeric.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 数值类型 -category: reference ---- - -# 数值类型 - -TiDB 支持 MySQL 所有的数值类型，按照精度可以分为: - -+ [整数类型（精确值)](#整数类型) -+ [浮点类型（近似值)](#浮点类型) -+ [定点类型（精确值)](#定点类型) - -## 整数类型 - -TiDB 支持 MySQL 所有的整数类型，包括 `INTEGER`/`INT`、`TINYINT`、`SMALLINT`、`MEDIUMINT` 以及 `BIGINT`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/numeric-type-overview.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| ---- | --------| -| M | 类型显示宽度，可选 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识，但是没有做补零的操作 | - -### 类型定义 - -#### `BIT` 类型 - -比特值类型。M 表示比特位的长度，取值范围从1到64，其默认值是1。 - -{{< copyable "sql" >}} - -```sql -BIT[(M)] -``` - -#### `BOOLEAN` 类型 - -布尔类型，别名为 `BOOL`，和 `TINYINT(1)` 等价。零值被认为是 `False`，非零值认为是 `True`。在 TiDB 内部，`True` 存储为 `1`，`False` 存储为 `0`。 - -{{< copyable "sql" >}} - -```sql -BOOLEAN -``` - -#### `TINYINT` 类型 - -`TINYINT` 类型。有符号数的范围是 `[-128, 127]`。无符号数的范围是 `[0, 255]`。 - -{{< copyable "sql" >}} - -```sql -TINYINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -#### `SMALLINT` 类型 - -`SMALLINT` 类型。有符号数的范围是 `[-32768, 32767]`。无符号数的范围是 `[0, 65535]`。 - -{{< copyable "sql" >}} - -```sql -SMALLINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -#### `MEDIUMINT` 类型 - -`MEDIUMINT` 类型。有符号数的范围是 `[-8388608, 8388607]`。无符号数的范围是 `[0, 16777215]`。 - -{{< copyable "sql" >}} - -```sql -MEDIUMINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -### `INTEGER` 类型 - -`INTEGER` 类型，别名 `INT`。有符号数的范围是 `[-2147483648, 2147483647]`。无符号数的范围是 `[0, 4294967295]`。 - -{{< copyable "sql" >}} - -```sql -INT[(M)] [UNSIGNED] [ZEROFILL] -``` - -或者： - -{{< copyable "sql" >}} - -```sql -INTEGER[(M)] [UNSIGNED] [ZEROFILL] -``` - -### `BIGINT` 类型 - -`BIGINT` 类型。有符号数的范围是 `[-9223372036854775808, 9223372036854775807]`。无符号数的范围是 `[0, 18446744073709551615]`。 - -{{< copyable "sql" >}} - -```sql -BIGINT[(M)] [UNSIGNED] [ZEROFILL] -> -``` - -### 存储空间以及取值范围 - -每种类型对存储空间的需求以及最大/最小值如下表所示: - -| 类型 | 存储空间 | 最小值(有符号/无符号) | 最大值(有符号/无符号) | -| ----------- |----------|-----------------------| --------------------- | -| `TINYINT` | 1 | -128 / 0 | 127 / 255 | -| `SMALLINT` | 2 | -32768 / 0 | 32767 / 65535 | -| `MEDIUMINT` | 3 | -8388608 / 0 | 8388607 / 16777215 | -| `INT` | 4 | -2147483648 / 0 | 2147483647 / 4294967295 | -| `BIGINT` | 8 | -9223372036854775808 / 0 | 9223372036854775807 / 18446744073709551615 | - -## 浮点类型 - -TiDB 支持 MySQL 所有的浮点类型，包括 `FLOAT`、`DOUBLE`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| -------- | ------------------------------- | -| M | 小数总位数 | -| D | 小数点后位数 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识 | - -### 类型定义 - -#### `FLOAT` 类型 - -单精度浮点数。允许的值范围为 -2^128 ~ +2^128，也即 -3.402823466E+38 到 -1.175494351E-38、0 和 1.175494351E-38 到 3.402823466E+38。这些是基于 IEEE 标准的理论限制。实际的范围根据硬件或操作系统的不同可能稍微小些。 - -`FLOAT(p)` 类型中，`p` 表示精度（以位数表示）。只使用该值来确定是否结果列的数据类型为 `FLOAT` 或 `DOUBLE`。如果 `p` 为从 0 到 24，数据类型变为没有 M 或 D 值的 `FLOAT`。如果 `p` 为从 25 到 53，数据类型变为没有 M 或 D 值的 `DOUBLE`。结果列范围与本节前面描述的单精度 `FLOAT` 或双精度 `DOUBLE` 数据类型相同。 - -{{< copyable "sql" >}} - -```sql -FLOAT[(M,D)] [UNSIGNED] [ZEROFILL] -FLOAT(p) [UNSIGNED] [ZEROFILL] -``` - -> **警告：** -> -> 与在 MySQL 中一样，`FLOAT` 数据类型存储近似值。对于货币之类的精确值，建议使用 `DECIMAL` 类型。 - -#### `DOUBLE` 类型 - -双精度浮点数，别名为 `DOUBLE PRECISION`。允许的值范围为：-2^1024 ~ +2^1024，也即是 -1.7976931348623157E+308 到 -2.2250738585072014E-308、0 和 2.2250738585072014E-308 到 1.7976931348623157E+308。这些是基于 IEEE 标准的理论限制。实际的范围根据硬件或操作系统的不同可能稍微小些。 - -{{< copyable "sql" >}} - -```sql -DOUBLE[(M,D)] [UNSIGNED] [ZEROFILL] -DOUBLE PRECISION [(M,D)] [UNSIGNED] [ZEROFILL], REAL[(M,D)] [UNSIGNED] [ZEROFILL] -``` - -> **警告：** -> -> 与在 MySQL 中一样，`DOUBLE` 数据类型存储近似值。对于货币之类的精确值，建议使用 `DECIMAL` 类型。 - -### 存储空间 - -每种类型对存储空间的需求如下表所示: - -| 类型 | 存储空间 | -| ----------- |----------| -| `FLOAT` | 4 | -| `FLOAT(p)` | 如果 0 <= p <= 24 为 4 个字节, 如果 25 <= p <= 53 为 8 个字节| -| `DOUBLE` | 8 | - -## 定点类型 - -TiDB 支持 MySQL 所有的定点类型，包括 `DECIMAL`、`NUMERIC`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/fixed-point-types.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| -------- | ------------------------------- | -| M | 小数总位数 | -| D | 小数点后位数 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识 | - -### 类型定义 - -#### `DECIMAL` 类型 - -定点数，别名为 `NUMERIC`。M 是小数位数（精度）的总数，D 是小数点（标度）后面的位数。小数点和 `-`（负数）符号不包括在 M 中。如果 D 是 0，则值没有小数点或分数部分。如果 D 被省略，默认是 0。如果 M 被省略，默认是 10。 - -{{< copyable "sql" >}} - -```sql -DECIMAL[(M[,D])] [UNSIGNED] [ZEROFILL] -NUMERIC[(M[,D])] [UNSIGNED] [ZEROFILL] -``` diff --git a/v3.0/reference/sql/data-types/overview.md b/v3.0/reference/sql/data-types/overview.md deleted file mode 100644 index bd2a691cd381..000000000000 --- a/v3.0/reference/sql/data-types/overview.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 数据类型概述 -category: reference -aliases: ['/docs-cn/sql/datatype/','/docs-cn/v3.0/reference/sql/data-types/'] ---- - -# 数据类型概述 - -TiDB 支持除空间类型 (`SPATIAL`) 之外的所有 MySQL 数据类型，包括[数值型类型](/v3.0/reference/sql/data-types/numeric.md)、[字符串类型](/v3.0/reference/sql/data-types/string.md)、[时间和日期类型](/v3.0/reference/sql/data-types/date-and-time.md)、[JSON 类型](/v3.0/reference/sql/data-types/json.md)。 - -数据类型定义一般为 `T(M[, D])`，其中： - -* `T` 表示具体的类型。 -* `M` 在整数类型中表示最大显示长度；在浮点数或者定点数中表示精度；在字符类型中表示最大长度。`M` 的最大值取决于具体的类型。 -* `D` 表示浮点数、定点数的小数位长度。 -* `fsp` 在时间和日期类型里的 `TIME`、`DATETIME` 以及 `TIMESTAMP` 中表示秒的精度，其取值范围是 0 到 6。值为 0 表示没有小数部分。如果省略，则默认精度为 0。 diff --git a/v3.0/reference/sql/data-types/string.md b/v3.0/reference/sql/data-types/string.md deleted file mode 100644 index 801998dc71b6..000000000000 --- a/v3.0/reference/sql/data-types/string.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 字符串类型 -category: reference ---- - -# 字符串类型 - -TiDB 支持 MySQL 所有的字符串类型，包括 `CHAR`、`VARCHAR`、`BINARY`、`VARBINARY`、`BLOB`、`TEXT`、`ENUM` 以及 `SET`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/string-types.html)文档。 - -## 类型定义 - -### `CHAR` 类型 - -定长字符串。`CHAR` 列的长度固定为创建表时声明的长度。长度可以为从 0 到 255 的任何值。当保存 CHAR 值时，在它们的右边填充空格以达到指定的长度。 - -{{< copyable "sql" >}} - -```sql -[NATIONAL] CHAR[(M)] [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `VARCHAR` 类型 - -变长字符串。M 表示最大列长度，范围是 0 到 65535。VARCHAR 的最大实际长度由最长的行的大小和使用的字符集确定。 - -{{< copyable "sql" >}} - -```sql -[NATIONAL] VARCHAR(M) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `TEXT` 类型 - -文本串。M 表示最大列长度，范围是 0 到 65535。TEXT 的最大实际长度由最长的行的大小和使用的字符集确定。 - -{{< copyable "sql" >}} - -```sql -TEXT[(M)] [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `TINYTEXT` 类型 - -类似于 `TEXT`，区别在于最大列长度为 255。 - -{{< copyable "sql" >}} - -```sql -TINYTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `MEDIUMTEXT` 类型 - -类似于 TEXT，区别在于最大列长度为 16,777,215。 - -{{< copyable "sql" >}} - -```sql -MEDIUMTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `LONGTEXT` 类型 - -类似于 `TEXT`，区别在于最大列长度为 4,294,967,295。 - -{{< copyable "sql" >}} - -```sql -LONGTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `BINARY` 类型 - -类似于 `CHAR`，区别在于 BINARY 存储的是二进制字符串。 - -{{< copyable "sql" >}} - -```sql -BINARY(M) -``` - -### `VARBINARY` 类型 - -类似于 `VARCHAR`，区别在于 VARBINARY 存储的是二进制字符串。 - -{{< copyable "sql" >}} - -```sql -VARBINARY(M) -``` - -### `TINYBLOB` 类型 - -类似于 BLOB，区别在于最大列长度为 255。 - -{{< copyable "sql" >}} - -```sql -TINYBLOB -``` - -### `BLOB` 类型 - -二进制大文件。M 表示最大列长度，范围是 0 到 65535。 - -{{< copyable "sql" >}} - -```sql -BLOB[(M)] -``` - -### `MEDIUMBLOB` 类型 - -类似于 `BLOB`，区别在于最大列长度为 16,777,215。 - -{{< copyable "sql" >}} - -```sql -MEDIUMBLOB -``` - -### `LONGBLOB` 类型 - -类似于 `BLOB`，区别在于最大列长度为 4,294,967,295。 - -{{< copyable "sql" >}} - -```sql -LONGBLOB -``` - -### `ENUM` 类型 - -枚举类型是一个字符串，它只能有一个值的字符串对象。其值必须是从一个固定集合中选取，这个固定集合在创建表的时候定义，语法是： - -{{< copyable "sql" >}} - -```sql -ENUM('value1','value2',...) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -ENUM('apple', 'orange', 'pear') -``` - -枚举类型的值在 TiDB 内部使用数值来存储，每个值会按照定义的顺序转换为一个数字，比如上面的例子中，每个字符串值都会映射为一个数字： - -| 值 | 数字 | -| ---- | ---- | -| NULL | NULL | -| '' | 0 | -| 'apple' | 1 | -| 'orange' | 2 | -| 'pear' | 3 | - -更多信息参考 [MySQL 枚举文档](https://dev.mysql.com/doc/refman/5.7/en/enum.html)。 - -### `SET` 类型 - -集合类型是一个包含零个或多个值的字符串，其中每个值必须是从一个固定集合中选取，这个固定集合在创建表的时候定义，语法是： - -{{< copyable "sql" >}} - -```sql -SET('value1','value2',...) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -SET('1', '2') NOT NULL -``` - -上面的例子中，这列的有效值可以是： - -``` -'' -'1' -'2' -'1,2' -``` - -集合类型的值在 TiDB 内部会转换为一个 Int64 数值，每个元素是否存在用一个二进制位的 0/1 值来表示，比如这个例子 `SET('a','b','c','d')`，每一个元素都被映射为一个数字，且每个数字的二进制表示只会有一位是 1： - -| 成员 | 十进制表示 | 二进制表示 | -| ---- | ---- | ------ | -| 'a' | 1 | 0001 | -| 'b' | 2 | 0010 | -| 'c' | 4 | 0100 | -| 'd' | 8 | 1000 | - -这样对于值为 `('a', 'c')` 的元素，其二进制表示即为 0101。 - -更多信息参考 [MySQL 集合文档](https://dev.mysql.com/doc/refman/5.7/en/set.html)。 diff --git a/v3.0/reference/sql/functions-and-operators/aggregate-group-by-functions.md b/v3.0/reference/sql/functions-and-operators/aggregate-group-by-functions.md deleted file mode 100644 index bcb73ba0ea78..000000000000 --- a/v3.0/reference/sql/functions-and-operators/aggregate-group-by-functions.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: GROUP BY 聚合函数 -category: reference -aliases: ['/docs-cn/sql/aggregate-group-by-functions/'] ---- - -# GROUP BY 聚合函数 - -本文将详细介绍 TiDB 支持的聚合函数。 - -## TiDB 支持的聚合函数 - -TiDB 支持的 MySQL GROUP BY 聚合函数如下所示： - -| 函数名 | 功能描述 | -|:---------|:--------------------| -| [`COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count) | 返回检索到的行的数目| -| [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count-distinct) | 返回不同值的数目 | -| [`SUM()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_sum) | 返回和 | -| [`AVG()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_avg) | 返回平均值 | -| [`MAX()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_max) | 返回最大值 | -| [`MIN()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_min) | 返回最小值 | -| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_group-concat) | 返回连接的字符串 | - -> **注意：** -> -> - 除非另有说明，否则聚合函数默认忽略 `NULL` 值。 -> - 如果在不包含 `GROUP BY` 子句的语句中使用聚合函数，则相当于对所有行进行分组。 - -## GROUP BY 修饰符 - -TiDB 目前不支持 `GROUP BY` 修饰符，例如 `WITH ROLLUP`，将来会提供支持。详情参阅 [#4250](https://github.com/pingcap/tidb/issues/4250)。 - -## 对 SQL 模式的支持 - -TiDB 支持 SQL 模式 `ONLY_FULL_GROUP_BY`，当启用该模式时，TiDB 拒绝不明确的非聚合列的查询。例如，以下查询在启用 `ONLY_FULL_GROUP_BY` 时是不合规的，因为 `SELECT` 列表中的非聚合列 "b" 在 `GROUP BY` 语句中不显示： - -{{< copyable "sql" >}} - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 3), (2, 2, 3), (3, 2, 3); -``` - -{{< copyable "sql" >}} - -```sql -select a, b, sum(c) from t group by a; -``` - -``` -+------+------+--------+ -| a | b | sum(c) | -+------+------+--------+ -| 1 | 2 | 3 | -| 2 | 2 | 3 | -| 3 | 2 | 3 | -+------+------+--------+ -3 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -set sql_mode = 'ONLY_FULL_GROUP_BY'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select a, b, sum(c) from t group by a; -``` - -``` -ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP BY clause and contains nonaggregated column 'b' which is not functionally dependent on columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by -``` - -目前，TiDB 默认开启 SQL 模式 [`ONLY_FULL_GROUP_BY`](/v3.0/reference/mysql-compatibility.md#默认设置的区别)。 - -### 与 MySQL 的区别 - -TiDB 目前实现的 `ONLY_FULL_GROUP_BY` 没有 MySQL 5.7 严格。例如，假设我们执行以下查询，希望结果按 "c" 排序： - -{{< copyable "sql" >}} - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 1), (1, 2, 2), (1, 3, 1), (1, 3, 2); -select distinct a, b from t order by c; -``` - -要对结果进行排序，必须先清除重复。但选择保留哪一行会影响 `c` 的保留值，也会影响排序，并使其具有任意性。 - -在 MySQL 中，`ORDER BY` 表达式需至少满足以下条件之一，否则 `DISTINCT` 和 `ORDER BY` 查询将因不合规而被拒绝： - -- 表达式等同于 `SELECT` 列表中的一个。 -- 表达式引用并属于查询选择表的所有列都是 `SELECT` 列表的元素。 - -但是在 TiDB 中，上述查询是合规的，详情参阅 [#4254](https://github.com/pingcap/tidb/issues/4254)。 - -TiDB 中另一个标准 SQL 的扩展允许 `HAVING` 子句中的引用使用 `SELECT` 列表中的别名表达式。例如：以下查询返回在 `orders` 中只出现一次的 `name` 值： - -{{< copyable "sql" >}} - -```sql -select name, count(name) from orders -group by name -having count(name) = 1; -``` - -这个 TiDB 扩展允许在聚合列的 `HAVING` 子句中使用别名： - -{{< copyable "sql" >}} - -```sql -select name, count(name) as c from orders -group by name -having c = 1; -``` - -标准 SQL 只支持 `GROUP BY` 子句中的列表达式，以下语句不合规，因为 `FLOOR(value/100)` 是一个非列表达式： - -{{< copyable "sql" >}} - -```sql -select id, floor(value/100) -from tbl_name -group by id, floor(value/100); -``` - -TiDB 对标准 SQL 的扩展支持 `GROUP BY` 子句中非列表达式，认为上述语句合规。 - -标准 SQL 也不支持 `GROUP BY` 子句中使用别名。TiDB 对标准 SQL 的扩展支持使用别名，查询的另一种写法如下： - -{{< copyable "sql" >}} - -```sql -select id, floor(value/100) as val -from tbl_name -group by id, val; -``` - -## TiDB 不支持的聚合函数 - -TiDB 目前不支持的聚合函数如下所示，相关进展参阅 [TiDB #7623](https://github.com/pingcap/tidb/issues/7623)。 - -- `STD`, `STDDEV`, `STDDEV_POP` -- `STDDEV_SAMP` -- `VARIANCE`, `VAR_POP` -- `VAR_SAMP` -- `JSON_ARRAYAGG` -- `JSON_OBJECTAGG` diff --git a/v3.0/reference/sql/functions-and-operators/bit-functions-and-operators.md b/v3.0/reference/sql/functions-and-operators/bit-functions-and-operators.md deleted file mode 100644 index e4519ff935d3..000000000000 --- a/v3.0/reference/sql/functions-and-operators/bit-functions-and-operators.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 位函数和操作符 -category: reference -aliases: ['/docs-cn/sql/bit-functions-and-operators/'] ---- - -# 位函数和操作符 - -TiDB 支持使用 MySQL 5.7 中提供的所有[位函数和操作符](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html)。 - -**位函数和操作符表** - -| 函数和操作符名 | 功能描述 | -| -------------- | ------------------------------------- | -| [`BIT_COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#function_bit-count) | 返回参数二进制表示中为 1 的个数 | -| [&](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-and) | 位与 | -| [~](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-invert) | 按位取反 | -| [\|](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-or) | 位或 | -| [^](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-xor) | 位亦或 | -| [<<](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_left-shift) | 左移 | -| [>>](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_right-shift) | 右移 | diff --git a/v3.0/reference/sql/functions-and-operators/cast-functions-and-operators.md b/v3.0/reference/sql/functions-and-operators/cast-functions-and-operators.md deleted file mode 100644 index 6705a605374e..000000000000 --- a/v3.0/reference/sql/functions-and-operators/cast-functions-and-operators.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Cast 函数和操作符 -category: reference -aliases: ['/docs-cn/sql/cast-functions-and-operators/'] ---- - -# Cast 函数和操作符 - -Cast 函数和操作符用于将某种数据类型的值转换为另一种数据类型。TiDB 支持使用 MySQL 5.7 中提供的所有 [Cast 函数和操作符](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html)。 - -## Cast 函数和操作符表 - -| 函数和操作符名 | 功能描述 | -| --------------- | ----------------------------------- | -| [`BINARY`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#operator_binary) | 将一个字符串转换成一个二进制字符串 | -| [`CAST()`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_cast) | 将一个值转换成一个确定类型 | -| [`CONVERT()`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_convert) | 将一个值转换成一个确定类型 | diff --git a/v3.0/reference/sql/functions-and-operators/control-flow-functions.md b/v3.0/reference/sql/functions-and-operators/control-flow-functions.md deleted file mode 100644 index 46aa98621d39..000000000000 --- a/v3.0/reference/sql/functions-and-operators/control-flow-functions.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 控制流程函数 -category: reference -aliases: ['/docs-cn/sql/control-flow-functions/'] ---- - -# 控制流程函数 - -TiDB 支持使用 MySQL 5.7 中提供的所有[控制流程函数](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html)。 - -| 函数名 | 功能描述 | -|:--------------------------------------------------------------------------------------------------|:----------------------------------| -| [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case) | Case 操作符 | -| [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if) | 构建 if/else | -| [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | 构建 Null if/else | -| [`NULLIF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_nullif) | 如果 expr1 = expr2，返回 `NULL` | diff --git a/v3.0/reference/sql/functions-and-operators/date-and-time-functions.md b/v3.0/reference/sql/functions-and-operators/date-and-time-functions.md deleted file mode 100644 index 7dcb6633415b..000000000000 --- a/v3.0/reference/sql/functions-and-operators/date-and-time-functions.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: 日期和时间函数 -category: reference -aliases: ['/docs-cn/sql/date-and-time-functions/'] ---- - -# 日期和时间函数 - -TiDB 支持使用 MySQL 5.7 中提供的所有[日期和时间函数](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html)。 - -## 日期时间函数表 - -| 函数名 | 功能描述 | -| ------ | ---------------------------------------- | -| [`ADDDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_adddate) | 将时间间隔添加到日期上 | -| [`ADDTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_addtime) | 时间数值相加 | -| [`CONVERT_TZ()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_convert-tz) | 转换时区 | -| [`CURDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_curdate) | 返回当前日期 | -| [`CURRENT_DATE()`, `CURRENT_DATE`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-date) | 与 CURDATE() 同义 | -| [`CURRENT_TIME()`, `CURRENT_TIME`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-time) | 与 CURTIME() 同义 | -| [`CURRENT_TIMESTAMP()`, `CURRENT_TIMESTAMP`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-timestamp) | 与 NOW() 同义 | -| [`CURTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_curtime) | 返回当前时间 | -| [`DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date) | 从日期或日期/时间表达式中提取日期部分| -| [`DATE_ADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-add) | 将时间间隔添加到日期上| -| [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | 返回满足指定格式的日期/时间 | -| [`DATE_SUB()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-sub) | 从日期减去指定的时间间隔 | -| [`DATEDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_datediff) | 返回两个日期间隔的天数| -| [`DAY()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_day) | 与 DAYOFMONTH() 同义| -| [`DAYNAME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayname) | 返回星期名称 | -| [`DAYOFMONTH()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofmonth) | 返回参数对应的天数部分(1-31)| -| [`DAYOFWEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofweek) | 返回参数对应的星期下标| -| [`DAYOFYEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofyear) | 返回参数代表一年的哪一天 (1-366) | -| [`EXTRACT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_extract) | 提取日期/时间中的单独部分| -| [`FROM_DAYS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_from-days) | 将天数转化为日期 | -| [`FROM_UNIXTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_from-unixtime) | 将 Unix 时间戳格式化为日期 | -| [`GET_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_get-format) | 返回满足日期格式的字符串 | -| [`HOUR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_hour) | 提取日期/时间表达式中的小时部分 | -| [`LAST_DAY`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_last-day) | 返回参数中月份的最后一天 | -| [`LOCALTIME()`, `LOCALTIME`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_localtime) | 与 NOW() 同义 | -| [`LOCALTIMESTAMP`, `LOCALTIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_localtimestamp) | 与 NOW() 同义 | -| [`MAKEDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_makedate) | 根据给定的年份和一年中的天数生成一个日期 | -| [`MAKETIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_maketime) | 根据给定的时、分、秒生成一个时间 | -| [`MICROSECOND()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_microsecond) | 返回参数的微秒部分| -| [`MINUTE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_minute) | 返回参数的分钟部分| -| [`MONTH()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_month) | 返回参数的月份部分| -| [`MONTHNAME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_monthname) | 返回参数的月份名称| -| [`NOW()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_now) | 返回当前日期和时间| -| [`PERIOD_ADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_period-add) | 在年-月表达式上添加一段时间(数个月)| -| [`PERIOD_DIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_period-diff) | 返回间隔的月数| -| [`QUARTER()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_quarter) | 返回参数对应的季度(1-4) | -| [`SEC_TO_TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_sec-to-time) | 将秒数转化为 'HH:MM:SS' 的格式| -| [`SECOND()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_second) | 返回秒数(0-59) | -| [`STR_TO_DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_str-to-date) | 将字符串转化为日期| -| [`SUBDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_subdate) | 当传入三个参数时作为 DATE_SUB() 的同义| -| [`SUBTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_subtime) | 从一个时间中减去一段时间 | -| [`SYSDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_sysdate) | 返回该方法执行时的时间| -| [`TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time) | 返回参数的时间表达式部分 | -| [`TIME_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time-format) | 格式化时间| -| [`TIME_TO_SEC()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time-to-sec) | 返回参数对应的秒数| -| [`TIMEDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timediff) | 返回时间间隔 | -| [`TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestamp) | 传入一个参数时候,该方法返回日期或日期/时间表达式, 传入两个参数时候, 返回参数的和 | -| [`TIMESTAMPADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestampadd) | 在日期/时间表达式上增加一段时间间隔 | -| [`TIMESTAMPDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestampdiff) | 从日期/时间表达式中减去一段时间间隔 | -| [`TO_DAYS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_to-days) | 将参数转化对应的天数(从第 0 年开始) | -| [`TO_SECONDS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_to-seconds) | 将日期或日期/时间参数转化为秒数(从第 0 年开始) | -| [`UNIX_TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_unix-timestamp) | 返回一个 Unix 时间戳| -| [`UTC_DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-date) | 返回当前的 UTC 日期 | -| [`UTC_TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-time) | 返回当前的 UTC 时间 | -| [`UTC_TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-timestamp) | 返回当前的 UTC 日期和时间| -| [`WEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_week) | 返回参数所在的一年中的星期数 | -| [`WEEKDAY()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_weekday) | 返回星期下标 | -| [`WEEKOFYEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_weekofyear) | 返回参数在日历中对应的一年中的星期数 | -| [`YEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_year) | 返回参数对应的年数| -| [`YEARWEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_yearweek) | 返回年数和星期数 | diff --git a/v3.0/reference/sql/functions-and-operators/encryption-and-compression-functions.md b/v3.0/reference/sql/functions-and-operators/encryption-and-compression-functions.md deleted file mode 100644 index c0fc3c6cfbfb..000000000000 --- a/v3.0/reference/sql/functions-and-operators/encryption-and-compression-functions.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 加密和压缩函数 -category: reference -aliases: ['/docs-cn/sql/encryption-and-compression-functions/'] ---- - -# 加密和压缩函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[加密和压缩函数](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -|:-----------|:----------------------------| -| [`MD5()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_md5)                                                             | 计算字符串的 MD5 校验和       | -| [`PASSWORD()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_password) | 计算并返回密码字符串 | -| [`RANDOM_BYTES()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_random-bytes) | 返回随机字节向量 | -| [`SHA1()`, `SHA()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_sha1)                                                   | 计算 SHA-1 160 位校验和               | -| [`SHA2()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_sha2)                                                           | 计算 SHA-2 校验和                       | -| [`AES_DECRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_aes-decrypt) | 使用 AES 解密 | -| [`AES_ENCRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_aes-encrypt) | 使用 AES 加密 | -| [`COMPRESS()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_compress) | 返回经过压缩的二进制字符串 | -| [`UNCOMPRESS()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_uncompress) | 解压缩字符串 | -| [`UNCOMPRESSED_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_uncompressed-length)                             | 返回字符串解压后的长度 | -| [`CREATE_ASYMMETRIC_PRIV_KEY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-asymmetric-priv-key) | 创建私钥 | -| [`CREATE_ASYMMETRIC_PUB_KEY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-asymmetric-pub-key) | 创建公钥 | -| [`CREATE_DH_PARAMETERS()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-dh-parameters) | 创建 DH 共享密钥 | -| [`CREATE_DIGEST()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-digest) | 从字符串创建摘要 | -| [`ASYMMETRIC_DECRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-decrypt) | 使用公钥或私钥解密密文 | -| [`ASYMMETRIC_DERIVE()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-derive) | 从非对称密钥导出对称密钥 | -| [`ASYMMETRIC_ENCRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-encrypt) | 使用公钥或私钥加密明文 | -| [`ASYMMETRIC_SIGN()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-sign) | 从摘要创建签名 | -| [`ASYMMETRIC_VERIFY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-verify) | 验证签名字符串是否匹配摘要字符串 | - -## 不支持的函数 - -* `DES_DECRYPT()`、`DES_ENCRYPT()`、`OLD_PASSWORD()` 和 `ENCRYPT()`：这些函数在 MySQL 5.7 中被废弃，并且已在 MySQL 8.0 中移除。 -* `VALIDATE_PASSWORD_STRENGTH()` 函数。 -* 只在 MySQL 企业版中支持的函数。见 [Issue #2632](https://github.com/pingcap/tidb/issues/2632)。 \ No newline at end of file diff --git a/v3.0/reference/sql/functions-and-operators/expressions-pushed-down.md b/v3.0/reference/sql/functions-and-operators/expressions-pushed-down.md deleted file mode 100644 index c5b57363058e..000000000000 --- a/v3.0/reference/sql/functions-and-operators/expressions-pushed-down.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: 下推到 TiKV 的表达式列表 -summary: TiDB 中下推到 TiKV 的表达式列表及相关设置。 -category: reference ---- - -# 下推到 TiKV 的表达式列表 - -当 TiDB 从 TiKV 中读取数据的时候，TiDB 会尽量下推一些表达式运算到 TiKV 中，从而减少数据传输量以及 TiDB 单一节点的计算压力。本文将介绍 TiDB 已支持下推的表达式，以及如何禁止下推特定表达式。 - -## 已支持下推的表达式列表 - -| 表达式分类 | 具体操作 | -| :-------------- | :------------------------------------- | -| [逻辑运算](/v3.0/reference/sql/functions-and-operators/operators.md#逻辑操作符) | AND (&&), OR (||), NOT (!) | -| [比较运算](/v3.0/reference/sql/functions-and-operators/operators.md#比较方法和操作符) | <, <=, =, != (<>), >, >=, [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to), [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in), IS NULL, LIKE, IS TRUE, IS FALSE, [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | -| [数值运算](/v3.0/reference/sql/functions-and-operators/numeric-functions-and-operators.md) | +, -, *, /, [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs), [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil), [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling), [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | -| [控制流运算](/v3.0/reference/sql/functions-and-operators/control-flow-functions.md) | [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case), [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if), [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | -| [JSON运算](/v3.0/reference/sql/functions-and-operators/json-functions.md) | [JSON_TYPE(json_val)][json_type],
[JSON_EXTRACT(json_doc, path[, path] ...)][json_extract],
[JSON_UNQUOTE(json_val)][json_unquote],
[JSON_OBJECT(key, val[, key, val] ...)][json_object],
[JSON_ARRAY([val[, val] ...])][json_array],
[JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge],
[JSON_SET(json_doc, path, val[, path, val] ...)][json_set],
[JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert],
[JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace],
[JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | -| [日期运算](/v3.0/reference/sql/functions-and-operators/date-and-time-functions.md) | [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | - -## 禁止特定表达式下推 - -当函数的计算过程由于下推而出现异常时，可通过黑名单功能禁止其下推来快速恢复业务。具体而言，你可以将上述支持的函数或运算符名加入黑名单 `mysql.expr_pushdown_blacklist` 中，以禁止特定表达式下推。 - -### 加入黑名单 - -执行以下步骤，可将一个或多个函数或运算符加入黑名单： - -1. 向 `mysql.expr_pushdown_blacklist` 插入对应的函数名或运算符名。 -2. 执行 `admin reload expr_pushdown_blacklist;`。 - -### 移出黑名单 - -执行以下步骤，可将一个或多个函数及运算符移出黑名单： - -1. 从 `mysql.expr_pushdown_blacklist` 表中删除对应的函数名或运算符名。 -2. 执行 `admin reload expr_pushdown_blacklist;`。 - -### 黑名单用法示例 - -以下示例首先将运算符 `<` 及 `>` 加入黑名单，然后将运算符 `>` 从黑名单中移出。 - -黑名单是否生效可以从 `explain` 结果中进行观察（参见[如何理解 `explain` 结果](/v3.0/reference/performance/understanding-the-query-execution-plan.md)）。 - -```sql -tidb> create table t(a int); -Query OK, 0 rows affected (0.01 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+---------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+------------------------------------------------------------+ -| TableReader_7 | 0.00 | root | data:Selection_6 | -| └─Selection_6 | 0.00 | cop | gt(test.t.a, 2), lt(test.t.a, 2) | -| └─TableScan_5 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+------------------------------------------------------------+ -3 rows in set (0.00 sec) - -tidb> insert into mysql.expr_pushdown_blacklist values('<'), ('>'); -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 - -tidb> admin reload expr_pushdown_blacklist; -Query OK, 0 rows affected (0.00 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+---------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+------------------------------------------------------------+ -| Selection_5 | 8000.00 | root | gt(test.t.a, 2), lt(test.t.a, 2) | -| └─TableReader_7 | 10000.00 | root | data:TableScan_6 | -| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+------------------------------------------------------------+ -3 rows in set (0.00 sec) - -tidb> delete from mysql.expr_pushdown_blacklist where name = '>'; -Query OK, 1 row affected (0.00 sec) - -tidb> admin reload expr_pushdown_blacklist; -Query OK, 0 rows affected (0.00 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+-----------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+-----------------------+----------+------+------------------------------------------------------------+ -| Selection_5 | 2666.67 | root | lt(test.t.a, 2) | -| └─TableReader_8 | 3333.33 | root | data:Selection_7 | -| └─Selection_7 | 3333.33 | cop | gt(test.t.a, 2) | -| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+-----------------------+----------+------+------------------------------------------------------------+ -4 rows in set (0.00 sec) -``` - -> **注意：** -> -> - `admin reload expr_pushdown_blacklist` 只对执行该 SQL 语句的 TiDB server 生效。若需要集群中所有 TiDB server 生效，需要在每台 TiDB server 上执行该 SQL 语句。 -> - 表达式黑名单功能在 v3.0.0 及以上版本中支持。 -> - 在 v3.0.3 及以下版本中，不支持将某些运算符的原始名称文本（如 ">"、"+" 和 "is null"）加入黑名单中，部分运算符在黑名单中需使用别名。已支持下推的表达式中，别名与原始名不同的运算符见下表（区分大小写）。 - -| 运算符原始名称 | 运算符别名 | -| :-------- | :---------- | -| < | lt | -| > | gt | -| <= | le | -| >= | ge | -| = | eq | -| != | ne | -| <> | ne | -| <=> | nulleq | -| | | bitor | -| && | bitand| -| || | or | -| ! | not | -| in | in | -| + | plus| -| - | minus | -| * | mul | -| / | div | -| DIV | intdiv| -| IS NULL | isnull | -| IS TRUE | istrue | -| IS FALSE | isfalse | - -[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract -[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path -[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path -[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote -[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type -[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set -[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert -[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace -[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove -[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge -[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve -[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object -[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array -[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys -[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length -[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid -[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote -[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains -[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path -[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg -[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/v3.0/reference/sql/functions-and-operators/information-functions.md b/v3.0/reference/sql/functions-and-operators/information-functions.md deleted file mode 100644 index d7944aae92ff..000000000000 --- a/v3.0/reference/sql/functions-and-operators/information-functions.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 信息函数 -category: reference -aliases: ['/docs-cn/sql/information-function/'] ---- - -# 信息函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[信息函数](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -| ------ | ---------------------------------------- | -| [`BENCHMARK()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_benchmark) | 循环执行一个表达式 | -| [`CONNECTION_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_connection-id) | 返回当前连接的连接 ID (线程 ID) | -| [`CURRENT_USER()`, `CURRENT_USER`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_current-user) | 返回当前用户的用户名和主机名 | -| [`DATABASE()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_database) | 返回默认(当前)的数据库名 | -| [`FOUND_ROWS()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_found-rows) | 该函数返回对于一个包含 LIMIT 的 SELECT 查询语句，在不包含 LIMIT 的情况下回返回的记录数 | -| [`LAST_INSERT_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_last-insert-id) | 返回最后一条 INSERT 语句中自增列的值 | -| [`ROW_COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_row-count) | 影响的行数 | -| [`SCHEMA()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_schema) | 与 DATABASE() 同义 | -| [`SESSION_USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_session-user) | 与 USER() 同义 | -| [`SYSTEM_USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_system-user) | 与 USER() 同义 | -| [`USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_user) | 返回客户端提供的用户名和主机名 | -| [`VERSION()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_version) | 返回当前 MySQL 服务器的版本信息 | -| `TIDB_VERSION()` | 返回当前 TiDB 服务器的版本信息 | - -## 不支持的函数 - -* `CHARSET()` -* `COERCIBILITY()` -* `COLLATION()` diff --git a/v3.0/reference/sql/functions-and-operators/json-functions.md b/v3.0/reference/sql/functions-and-operators/json-functions.md deleted file mode 100644 index 5d0469dc332d..000000000000 --- a/v3.0/reference/sql/functions-and-operators/json-functions.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: JSON 函数及语法糖 -category: reference -aliases: ['/docs-cn/sql/json-functions/'] ---- - -# JSON 函数及语法糖 - -TiDB 支持 MySQL 5.7 GA 版本发布的大多数 JSON 函数。MySQL 5.7 发布后，又增加了更多 JSON 函数，TiDB 并未支持所有这些函数（参见[未支持的函数](#未支持的函数)）。 - -## 创建 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| ------------------------------------------------------------------ | ---------------------------------------------------------- | -| [JSON_ARRAY([val[, val] ...])][json_array] | 根据一系列元素创建一个 JSON 文档 | -| [JSON_OBJECT(key, val[, key, val] ...)][json_object] | 根据一系列 K/V 对创建一个 JSON 文档 | -| [JSON_QUOTE(string)][json_quote] | 返回一个字符串，该字符串为带引号的 JSON 值 | - -## 搜索 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| ------------------------------------------------------------------ | ---------------------------------------------------------- | -| [JSON_CONTAINS(target, candidate[, path])][json_contains] | 通过返回 1 或 0 来表示目标 JSON 文档中是否包含给定的 candidate JSON 文档 | -| [JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)][json_contains_path] | 通过返回 0 或 1 来表示一个 JSON 文档在给定路径是否包含数据 | -| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract] | 从 JSON 文档中解出某一路径对应的子文档 | -| [->][json_short_extract] | 返回执行路径后面的 JSON 列的值；`JSON_EXTRACT(doc, path_literal)` 的语法糖 | -| [->>][json_short_extract_unquote] | 返回执行路径后面的 JSON 列的值和转义后的结果； `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` 的语法糖 | -| [JSON_KEYS(json_doc[, path])][json_keys] | 返回从 JSON 对象的顶级值作为 JSON array 的键，如果给定了路径参数，则从选定路径中获取顶级键 | - -## 修改 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| --------------------------------- | ----------- | -| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | 在 JSON 文档中在某一路径下插入子文档 | -| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge] | 已废弃的 `JSON_MERGE_PRESERVE` 别名 | -| [JSON_MERGE_PRESERVE(json_doc, json_doc[, json_doc] ...)][json_merge_preserve] | 将两个或多个 JSON 文档合并成一个文档，并返回合并结果 | -| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | 移除 JSON 文档中某一路径下的子文档 | -| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | 替换 JSON 文档中的某一路径下的子文档 | -| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set] | 在 JSON 文档中为某一路径设置子文档 | -| [JSON_UNQUOTE(json_val)][json_unquote] | 去掉 JSON 值外面的引号，返回结果为字符串 | - -## 返回 JSON 值属性的函数 - -| 函数及语法糖 | 功能描述 | -| --------------------------------- | ----------- | -| [JSON_DEPTH(json_doc)][json_depth] | 返回 JSON 文档的最大深度 | -| [JSON_LENGTH(json_doc[, path])][json_length] | 返回 JSON 文档的长度；如果路径参数已定，则返回该路径下值的长度 | -| [JSON_TYPE(json_val)][json_type] | 检查某 JSON 文档内部内容的类型 | - -## 未支持的函数 - -TiDB 暂未支持以下 JSON 函数。相关进展参见 [TiDB #7546](https://github.com/pingcap/tidb/issues/7546): - -* `JSON_APPEND` 及其别名 `JSON_ARRAY_APPEND` -* `JSON_ARRAY_INSERT` -* `JSON_DEPTH` -* `JSON_MERGE_PATCH` -* `JSON_PRETTY` -* `JSON_SEARCH` -* `JSON_STORAGE_SIZE` -* `JSON_VALID` -* `JSON_ARRAYAGG` -* `JSON_OBJECTAGG` - -[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract -[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path -[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path -[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote -[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type -[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set -[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert -[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace -[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove -[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge -[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve -[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object -[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array -[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys -[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length -[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid -[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote -[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains -[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path -[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg -[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/v3.0/reference/sql/functions-and-operators/miscellaneous-functions.md b/v3.0/reference/sql/functions-and-operators/miscellaneous-functions.md deleted file mode 100644 index e36c39e2b23d..000000000000 --- a/v3.0/reference/sql/functions-and-operators/miscellaneous-functions.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: 其他函数 -category: reference -aliases: ['/docs-cn/sql/miscellaneous-functions/'] ---- - -# 其他函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[其他函数](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -|:------|:-----------| -| [`ANY_VALUE()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_any-value) | 在 `ONLY_FULL_GROUP_BY` 模式下，防止带有 `GROUP BY` 的语句报错 | -| [`DEFAULT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_default) | 返回表的某一列的默认值 | -| [`INET_ATON()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet-aton) | 将 IP 地址转换为数值 | -| [`INET_NTOA()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet-ntoa) | 将数值转换为 IP 地址 | -| [`INET6_ATON()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet6-aton) | 将 IPv6 地址转换为数值 | -| [`INET6_NTOA()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet6-ntoa) | 将数值转换为 IPv6 地址 | -| [`IS_IPV4()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4) | 判断参数是否为 IPv4 地址 | -| [`IS_IPV4_COMPAT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4-compat) | 判断参数是否为兼容 IPv4 的地址 | -| [`IS_IPV4_MAPPED()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4-mapped) | 判断参数是否为 IPv4 映射的地址 | -| [`IS_IPV6()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv6) | 判断参数是否为 IPv6 地址 | -| [`NAME_CONST()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_name-const) | 可以用于重命名列名 | -| [`SLEEP()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_sleep) | 让语句暂停执行几秒时间 | -| [`UUID()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_uuid) | 返回一个通用唯一识别码 (UUID) | -| [`VALUES()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_values) | 定义 `INSERT` 语句使用的值 | - -## 不支持的函数 - -| 函数名 | 功能描述 | -|:------|:-----------| -| [`GET_LOCK()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock) | 获取命名锁，详见 [TiDB #10929](https://github.com/pingcap/tidb/issues/10929) | -| [`RELEASE_LOCK()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_release-lock) | 释放命名锁，详见 [TiDB #10929](https://github.com/pingcap/tidb/issues/10929) | -| [`UUID_SHORT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_uuid-short) | 基于特定假设提供唯一的 UUID，目前这些假设在 TiDB 中不存在，详见 [TiDB #4620](https://github.com/pingcap/tidb/issues/4620) | -| [`MASTER_WAIT_POS()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_master-pos-wait) | 与 MySQL 同步相关 | \ No newline at end of file diff --git a/v3.0/reference/sql/functions-and-operators/numeric-functions-and-operators.md b/v3.0/reference/sql/functions-and-operators/numeric-functions-and-operators.md deleted file mode 100644 index 53ae8e8f778e..000000000000 --- a/v3.0/reference/sql/functions-and-operators/numeric-functions-and-operators.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: 数值函数与操作符 -category: reference -aliases: ['/docs-cn/sql/numeric-functions-and-operators/'] ---- - -# 数值函数与操作符 - -TiDB 支持使用 MySQL 5.7 中提供的所有[数值函数与操作符](https://dev.mysql.com/doc/refman/5.7/en/numeric-functions.html)。 - -## 算术操作符 - -| 操作符名 | 功能描述 | -|:-------------|:--------------------------------| -| [`+`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_plus) | 加号 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_minus) | 减号 | -| [`*`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_times) | 乘号 | -| [`/`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_divide) | 除号 | -| [`DIV`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_div) | 整数除法 | -| [`%`, `MOD`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod) | 模运算，取余 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_unary-minus) | 更改参数符号 | - -## 数学函数 - -| 函数名 | 功能描述 | -|:----------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| -| [`POW()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_pow) | 返回参数的指定乘方的结果值 | -| [`POWER()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_power) | 返回参数的指定乘方的结果值 | -| [`EXP()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_exp) | 返回 e（自然对数的底）的指定乘方后的值 | -| [`SQRT()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sqrt) | 返回非负数的二次方根 | -| [`LN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ln) | 返回参数的自然对数 | -| [`LOG()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log) | 返回第一个参数的自然对数 | -| [`LOG2()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log2) | 返回参数以 2 为底的对数 | -| [`LOG10()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log10) | 返回参数以 10 为底的对数 | -| [`PI()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_pi) | 返回 pi 的值 | -| [`TAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_tan) | 返回参数的正切值 | -| [`COT()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_cot) | 返回参数的余切值 | -| [`SIN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sin) | 返回参数的正弦值 | -| [`COS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_cos) | 返回参数的余弦值 | -| [`ATAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_atan) | 返回参数的反正切值 | -| [`ATAN2(), ATAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_atan2) | 返回两个参数的反正切值 | -| [`ASIN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_asin) | 返回参数的反正弦值 | -| [`ACOS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_acos) | 返回参数的反余弦值 | -| [`RADIANS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_radians) | 返回由度转化为弧度的参数 | -| [`DEGREES()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_degrees) | 返回由弧度转化为度的参数 | -| [`MOD()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_mod) | 返回余数 | -| [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs) | 返回参数的绝对值 | -| [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil) | 返回不小于参数的最小整数值 | -| [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling) | 返回不小于参数的最小整数值 | -| [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | 返回不大于参数的最大整数值 | -| [`ROUND()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_round) | 返回参数最近似的整数或指定小数位数的数值 | -| [`RAND()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_rand) | 返回一个随机浮点值 | -| [`SIGN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sign) | 返回参数的符号 | -| [`CONV()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_conv) | 不同数基间转换数字，返回数字的字符串表示 | -| [`TRUNCATE()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_truncate) | 返回被舍位至指定小数位数的数字 | -| [`CRC32()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_crc32)           | 计算循环冗余码校验值并返回一个 32 位无符号值                     | diff --git a/v3.0/reference/sql/functions-and-operators/operators.md b/v3.0/reference/sql/functions-and-operators/operators.md deleted file mode 100644 index 904aa23166cd..000000000000 --- a/v3.0/reference/sql/functions-and-operators/operators.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: 操作符 -category: reference -aliases: ['/docs-cn/sql/operators/'] ---- - -# 操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`AND`, &&](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_and) | 逻辑与 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-equal) | 赋值 (可用于 [`SET`](https://dev.mysql.com/doc/refman/5.7/en/set-variable.html) 语句中, 或用于 [`UPDATE`](https://dev.mysql.com/doc/refman/5.7/en/update.html) 语句的 `SET` 中 ) | -| [`:=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-value) | 赋值 | -| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_between) | 判断值满足范围 | -| [`BINARY`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#operator_binary) | 将一个字符串转换为一个二进制字符串 | -| [&](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-and) | 位与 | -| [~](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-invert) | 位非 | -| [`\|`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-or) | 位或 | -| [`^`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-xor) | 按位异或 | -| [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case) | case 操作符 | -| [`DIV`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_div) | 整数除 | -| [`/`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_divide) | 除法 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal) | 相等比较 | -| [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to) | 空值安全型相等比较 | -| [`>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than) | 大于 | -| [`>=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than-or-equal) | 大于或等于 | -| [`IS`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is) | 判断一个值是否等于一个布尔值 | -| [`IS NOT`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not) | 判断一个值是否不等于一个布尔值 | -| [`IS NOT NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not-null) | 非空判断 | -| [`IS NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-null) | 空值判断 | -| [`<<`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_left-shift) | 左移 | -| [`<`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than) | 小于 | -| [`<=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than-or-equal) | 小于或等于 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 简单模式匹配 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_minus) | 减 | -| [`%`, `MOD`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod) | 求余 | -| [`NOT`, `!`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_not) | 取反 | -| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-between) | 判断值是否不在范围内 | -| [`!=`, `<>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-equal) | 不等于 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 不符合简单模式匹配 | -| [`NOT REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_not-regexp) | 不符合正则表达式模式匹配 | -| [`\|\|`, `OR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_or) | 逻辑或 | -| [`+`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_plus) | 加 | -| [`REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 使用正则表达式进行模式匹配 | -| [`>>`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_right-shift) | 右移 | -| [`RLIKE`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | REGEXP 同义词 | -| [`*`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_times) | 乘 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_unary-minus) | 取反符号 | -| [`XOR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_xor) | 逻辑亦或 | - -## 操作符优先级 - -操作符优先级显示在以下列表中，从最高优先级到最低优先级。同一行显示的操作符具有相同的优先级。 - -```sql -INTERVAL -BINARY -! -- (unary minus), ~ (unary bit inversion) -^ -*, /, DIV, %, MOD --, + -<<, >> -& -| -= (comparison), <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN -BETWEEN, CASE, WHEN, THEN, ELSE -NOT -AND, && -XOR -OR, || -= (assignment), := -``` - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/operator-precedence.html). - -## 比较方法和操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_between) | 判断值是否在范围内 | -| [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | 返回第一个非空值 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal) | 相等比较 | -| [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to) | 空值安全型相等比较 | -| [`>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than) | 大于 | -| [`>=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than-or-equal) | 大于或等于 | -| [`GREATEST()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_greatest) | 返回最大值 | -| [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in) | 判断值是否在一个值的集合内 | -| [`INTERVAL()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_interval) | 返回一个小于第一个参数的参数的下标 | -| [`IS`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is) | 判断是否等于一个布尔值 | -| [`IS NOT`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not) | 判断是否不等于一个布尔值 | -| [`IS NOT NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not-null) | 非空判断 | -| [`IS NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-null) | 空值判断 | -| [`ISNULL()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_isnull) | 判断参数是否为空 | -| [`LEAST()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_least) | 返回最小值 | -| [`<`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than) | 小于 | -| [`<=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than-or-equal) | 小于或等于 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 简单模式匹配 | -| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-between) | 判断值是否不在范围内 | -| [`!=`, `<>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-equal) | 不等于 | -| [`NOT IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_not-in) | 判断值是否不在一个值的集合内 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 不满足简单模式匹配 | -| [`STRCMP()`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#function_strcmp) | 比较两个字符串 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html). - -## 逻辑操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`AND`, &&](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_and) | 逻辑与 | -| [`NOT`, `!`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_not) | 逻辑非 | -| [`\|\|`, `OR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_or) | 逻辑或 | -| [`XOR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_xor) | 逻辑亦或 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/group-by-handling.html). - -## 赋值操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-equal) | 赋值 (可用于 [`SET`](https://dev.mysql.com/doc/refman/5.7/en/set-variable.html) 语句中, 或用于 [`UPDATE`](https://dev.mysql.com/doc/refman/5.7/en/update.html) 语句的 `SET` 中 ) | -| [`:=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-value) | 赋值 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/group-by-functional-dependence.html). diff --git a/v3.0/reference/sql/functions-and-operators/precision-math.md b/v3.0/reference/sql/functions-and-operators/precision-math.md deleted file mode 100644 index e58e553a79d6..000000000000 --- a/v3.0/reference/sql/functions-and-operators/precision-math.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: 精度数学 -category: reference -aliases: ['/docs-cn/sql/precision-math/'] ---- - -# 精度数学 - -TiDB 中精度数学计算与 MySQL 中基本一致, 详情请参见: [Precision Math](https://dev.mysql.com/doc/refman/5.7/en/precision-math.html). - -- 数值类型 -- DECIMAL 数据类型的特性 - -## 数值类型 - -精确数值运算的范围包括精确值数据类型(整型和 DECIMAL 类型), 以及精确值数字字面量. 近似值数据类型和近似值数字字面量被作为浮点数来处理. - -精确值数字字面量包含整数部分或小数部分, 或二者都包含. 精确值数字字面量可以包含符号位. 例如: 1, .2, 3.4, -5, -6.78, +9.10. - -近似值数字字面量以一个包含尾数和指数的科学计数法表示(基数为 10). 其中尾数和指数可以分别或同时带有符号位. 例如: 1.2E3, 1.2E-3, -1.2E3, -1.2E-3. - -两个看起来相似的数字可能会被以不同的方式进行处理. 例如, 2.34 是精确值(定点数), 而 2.3E0 是近似值(浮点数). - -DECIMAL 数据类型是定点数类型, 其运算是精确计算. FLOAT 和 DOUBLE 数据类型是浮点类型, 其运算是近似计算. - -## DECIMAL 数据类型的特性 - -本节讨论 DECIMAL 数据类型的特性, 主要涉及以下几点: - -1. 最大位数 -2. 存储格式 -3. 存储要求 - -DECIMAL 列的声明语法为 DECIMAL(M, D). 其中参数值意义及其范围如下: - -- M 表示最大的数字位数 (精度). 1<= M <= 65. -- D 表示小数点右边数字的位数 (标度). 1 <= D <= 30 且 不大于 M. - -M 的最大值 65 表示 DECIMAL 值的计算精确到 65 位数字. 该精度同样适用于其精确值字面量. - -DECIMAL 列的值采用二进制进行存储, 其将每 9 位十进制数字包装成 4 个字节. 其中整数和小数部分分别确定所需的存储空间. 如果数字位数为 9 的倍数, 则每 9 位十进制数字各采用 4 个字节进行存储, 对于剩余不足 9 位的数字, 所需的存储空间如下表所示. - -| 剩余数字位数 | 存储所需字节数 | -| --- | --- | -| 0 | 0 | -| 1–2 | 1 | -| 3–4 | 2 | -| 5–6 | 3 | -| 7–9 | 4 | - -例如, 定义类型为 DECIMAL(18, 9) 的列, 其小数点两侧均各包含 9 位十进制数字, 因此, 分别需要 4 个字节的存储空间. 定义类型为 DECIMAL(20, 6) 的列, 其小数部分包含 6 位十进制数字, 整数部分包含 14 位十进制数字. 整数部分中 9 位数字需要 4 个字节进行存储, 其余 5 位数字需要 3 个字节进行存储. 小数部分 6 位数字需要 3 个字节进行存储. - -DECIMAL 列不存储前导的字符 `+` 或字符 `-` 或数字 `0`. 如果将 +0003.1 插入到 DECIMAL(5, 1) 列中, 则将其存储为3.1. 对于负数, 不存储字符 `-` 的字面值. - -DECIMAL 列不允许插入大于列定义的隐含范围的值. 例如, DECIMAL(3, 0) 列范围为 -999 到 999. DECIMAL(M, D) 列小数点左边部分最多支持 M-D 位数字. - -有关 DECIMAL 值的内部格式完整说明, 请参阅 TiDB 源码文件 [types/mydecimal.go](https://github.com/pingcap/tidb/blob/master/types/mydecimal.go). - -## 表达式计算 - -在涉及精度数学计算的表达式中，TiDB 会尽可能不做任何修改的使用每个输入的数值。比如：在计算比较函数时，参与运算的数字将不做任何改变。在严格 SQL 模式下，向一个数据列插入一个值时，如果该值处于这一列的值域范围内，这个值将直接不做任何修改的直接插入进去，提取这个值的时候，取得的值和插入的值将会是同一个值。当处于非严格 SQL 模式时，TiDB 会允许数据插入过程中发生的数据截断。 - -处理数值类型表达式取决于这个表达式参数的具体值： - -* 当表达式参数中包含近似值时，这个表达式的结果也是近似值，TiDB 会使用浮点数对应的计算逻辑返回一个浮点数的结果 -* 当表达式参数中不包含任何近似值时（也就是说表达式的参数全部是精确值），如果某个精确值包含小数部分，TIDB 会对这个表达式使用 `DECIMAL` 对应的计算逻辑，返回一个 `DECIMAL` 的结果，精确到 65 位数字 -* 其他情况下，表达式只会包含整数参数，这个表达式的结果也是精确的，TiDB 会使用整数对应的计算逻辑返回一个整数结果，精度和 `BIGINT` 保持一致（64位） - -如果数值类型表达式中包含字符串参数，这些字符串参数将被转换成双精度浮点数，这个表达式的计算结果将是个近似值。 - -向一个数值类型列插入数据的具体行为会受到 SQL 模式的影响。接下来的讨论将围绕严格模式以及 `ERROR_FOR_DIVISION_BY_ZERO` 模式展开，如果要打开所有的限制，可以简单的使用 `TRADITIONAL` 模式，这个模式将同时使用严格模式以及 `ERROR_FOR_DIVISION_BY_ZERO` 模式： - -{{< copyable "sql" >}} - -```sql -SET sql_mode = 'TRADITIONAL'; -``` - -向一个具有精确值类型（`DECIMAL` 或者整数类型）的列插入数据时，如果插入的数据位于该列的值域范围内将使用该数据的精确值。如果该数据的小数部分太长，将会发生数值修约，这时会有 warning 产生，具体内容可以看"数值修约"。 - -如果该数据整数部分太长： - -* 如果没有开启严格模式，这个值会被截断并产生一个 warning -* 如果开启了严格模式，将会产生一个数据溢出的 error - -如果向一个数值类型列插入字符串，如果该字符串中包含非数值部分，TiDB 将这样做类型转换： - -* 在严格模式下，没有以数字开头的字符串（即使是一个空字符串）不能被被用作数字值并会返回一个 error 或者是 warning； -* 以数字开头的字符串可以被转换，不过末尾的非数字部分会被截断。如果被截断的部分包含的不全是空格，在严格模式下这回产生一个 error 或者 warning - -默认情况下，如果计算的过程中发生了除数是 0 的现象将会得到一个 `NULL` 结果，并且不会有 warning 产生。通过设置适当的 SQL 模式，除以 0 的操作可以被限制：当设置 `ERROR_FOR_DIVISION_BY_ZERO` SQL 模式时，TiDB 的行为是： - -* 如果设置了严格 SQL 模式，`INSERT` 和 `UPDATE` 的过程中如果发生了除以 0 的操作，正在进行的 `INSERT` 或者 `UPDATE` 操作会被禁止，并且会返回一个 error -* 如果没有设置严格 SQL 模式，除以 0 的操作仅会返回一个 warning - -假设我们有如下的 SQL 语句： - -{{< copyable "sql" >}} - -```sql -INSERT INTO t SET i = 1/0; -``` - -不同的 SQL 模式将会导致不同的结果如下： - -| `sql_mode` 的值 | 结果 | -| :--- | :--- | -| '' | 没有 warning，没有 error，i 被设为 NULL | -| strict | 没有 warning，没有 error，i 被设为 NULL | -| `ERROR_FOR_DIVISION_BY_ZERO` | 有 warning，没有 error，i 被设为 NULL | -| strict, `ERROR_FOR_DIVISION_BY_ZERO` | 有 error，插入失败 | - -## 数值修约 - -`round()` 函数的结果取决于他的参数是否是精确值： - -* 如果参数是精确值，`round()` 函数将使用四舍五入的规则 -* 如果参数是一个近似值，`round()` 表达式的结果可能和 MySQL 不太一样 - -{{< copyable "sql" >}} - -```sql -SELECT ROUND(2.5), ROUND(25E-1); -``` - -``` -+------------+--------------+ -| ROUND(2.5) | ROUND(25E-1) | -+------------+--------------+ -| 3 | 3 | -+------------+--------------+ -1 row in set (0.00 sec) -``` - -向一个 `DECIMAL` 或者整数类型列插入数据时，round 的规则将采用 [round half away from zero](https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero) 的方式： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t (d DECIMAL(10,0)); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t VALUES(2.5),(2.5E0); -``` - -``` -Query OK, 2 rows affected, 2 warnings (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT d FROM t; -``` - -``` -+------+ -| d | -+------+ -| 3 | -| 3 | -+------+ -2 rows in set (0.00 sec) -``` diff --git a/v3.0/reference/sql/functions-and-operators/reference.md b/v3.0/reference/sql/functions-and-operators/reference.md deleted file mode 100644 index f3d03d9e678b..000000000000 --- a/v3.0/reference/sql/functions-and-operators/reference.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 函数和操作符概述 -category: reference -aliases: ['/docs-cn/sql/functions-and-operators-reference/'] ---- - -# 函数和操作符概述 - -TiDB 中函数和操作符使用方法与 MySQL 基本一致，详情参见: [Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/functions.html)。 - -在 SQL 语句中，表达式可用于诸如 `SELECT` 语句的 `ORDER BY` 或 `HAVING` 子句，`SELECT`/`DELETE`/`UPDATE` 语句的 `WHERE` 子句，或 `SET` 语句之类的地方。 - -可使用字面值，列名，NULL，内置函数，操作符等来书写表达式。其中有些表达式下推到 TiKV 上执行，详见[下推到 TiKV 的表达式列表](/v3.0/reference/sql/functions-and-operators/expressions-pushed-down.md)。 \ No newline at end of file diff --git a/v3.0/reference/sql/functions-and-operators/string-functions.md b/v3.0/reference/sql/functions-and-operators/string-functions.md deleted file mode 100644 index 07d94a383718..000000000000 --- a/v3.0/reference/sql/functions-and-operators/string-functions.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: 字符串函数 -category: reference -aliases: ['/docs-cn/sql/string-functions/'] ---- - -# 字符串函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[字符串函数](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -|:----------|:-----------------------| -| [`ASCII()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ascii) | 返回最左字符的数值 | -| [`BIN()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_bin) | 返回一个数的二进制值的字符串表示 | -| [`BIT_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_bit-length) | 返回字符串的位长度 | -| [`CHAR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_char)    | 返回由整数的代码值所给出的字符组成的字符串 | -| [`CHAR_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_char-length) | 返回字符串的字符长度 | -| [`CHARACTER_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_character-length) | 与 `CHAR_LENGTH()` 功能相同 | -| [`CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_concat) | 返回连接的字符串 | -| [`CONCAT_WS()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_concat-ws) | 返回由分隔符连接的字符串 | -| [`ELT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_elt) | 返回指定位置的字符串 | -| [`EXPORT_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_export-set) | 返回一个字符串，其中值位中设置的每个位，可以得到一个 on 字符串，而每个未设置的位，可以得到一个 off 字符串 | -| [`FIELD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_field) | 返回参数在后续参数中出现的第一个位置 | -| [`FIND_IN_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_find-in-set) | 返回第一个参数在第二个参数中出现的位置 | -| [`FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_format) | 返回指定小数位数格式的数字 | -| [`FROM_BASE64()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_from-base64) | 解码 base-64 表示的字符串，并返回结果 | -| [`HEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_hex) | 返回一个十进制数或字符串值的 16 进制表示 | -| [`INSERT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_insert) | 在指定位置插入一个子字符串，最多不超过指定字符数 | -| [`INSTR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_instr) | 返回第一次出现的子字符串的索引 | -| [`LCASE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lcase) | 与 `LOWER()` 功能相同 | -| [`LEFT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_left) | 返回最左侧指定长度的字符 | -| [`LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_length) | 返回字符串长度，单位为字节 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 进行简单模式匹配 | -| [`LOCATE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_locate) | 返回第一次出现的子字符串的位置 | -| [`LOWER()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lower) | 返回全小写的参数 | -| [`LPAD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lpad) | 返回字符串参数，左侧添加指定字符串 | -| [`LTRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ltrim) | 去掉前缀空格 | -| [`MAKE_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_make-set) | 返回一组用逗号分隔的字符串，这些字符串的位数与给定的 bits 参数对应 | -| [`MID()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_mid) | 返回一个以指定位置开始的子字符串 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 否定简单模式匹配 | -| [`NOT REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_not-regexp) | `REGEXP` 的否定形式 | -| [`OCT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_oct) | 返回一个数值的八进制表示，形式为字符串 | -| [`OCTET_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_octet-length) | 与 `LENGTH()` 功能相同 | -| [`ORD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ord) | 返回该参数最左侧字符的字符编码 | -| [`POSITION()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_position) | 与 `LOCATE()` 功能相同 | -| [`QUOTE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_quote) | 使参数逃逸，为了在 SQL 语句中使用 | -| [`REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 使用正则表达式匹配模式 | -| [`REPEAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_repeat) | 以指定次数重复一个字符串 | -| [`REPLACE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_replace) | 替换所有出现的指定字符串 | -| [`REVERSE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_reverse) | 反转字符串里的所有字符 | -| [`RIGHT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_right) | 返回指定数量的最右侧的字符 | -| [`RLIKE`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 与 `REGEXP` 功能相同 | -| [`RPAD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_rpad) | 以指定次数添加字符串 | -| [`RTRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_rtrim) | 去掉后缀空格 | -| [`SPACE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_space) | 返回指定数量的空格，形式为字符串 | -| [`STRCMP()`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#function_strcmp) | 比较两个字符串 | -| [`SUBSTR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substr) | 返回指定的子字符串 | -| [`SUBSTRING()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substring) | 返回指定的子字符串 | -| [`SUBSTRING_INDEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substring-index) | 从一个字符串中返回指定出现次数的定界符之前的子字符串 | -| [`TO_BASE64()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_to-base64) | 返回转化为 base-64 表示的字符串参数 | -| [`TRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_trim) | 去掉前缀和后缀空格 | -| [`UCASE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ucase) | 与 `UPPER()` 功能相同 | -| [`UNHEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_unhex) | 返回一个数的十六进制表示，形式为字符串 | -| [`UPPER()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_upper) | 参数转换为大写形式 | - -## 不支持的函数 - -* `LOAD_FILE()` -* `MATCH` -* `SOUNDEX()` -* `SOUNDS LIKE` -* `WEIGHT_STRING()` diff --git a/v3.0/reference/sql/functions-and-operators/type-conversion.md b/v3.0/reference/sql/functions-and-operators/type-conversion.md deleted file mode 100644 index 504660698989..000000000000 --- a/v3.0/reference/sql/functions-and-operators/type-conversion.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: 表达式求值的类型转换 -category: reference -aliases: ['/docs-cn/sql/type-conversion-in-expression-evaluation/'] ---- - -# 表达式求值的类型转换 - -TiDB 中表达式求值的类型转换与 MySQL 基本一致，详情参见 [MySQL 表达式求值的类型转换](https://dev.mysql.com/doc/refman/5.7/en/type-conversion.html)。 diff --git a/v3.0/reference/sql/functions-and-operators/window-functions.md b/v3.0/reference/sql/functions-and-operators/window-functions.md deleted file mode 100644 index e9f47078d46f..000000000000 --- a/v3.0/reference/sql/functions-and-operators/window-functions.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 窗口函数 -category: reference ---- - -# 窗口函数 - -TiDB 中窗口函数的使用方法与 MySQL 8.0 基本一致，详情可参见 [MySQL 窗口函数](https://dev.mysql.com/doc/refman/8.0/en/window-functions.html)。由于窗口函数会使用一些保留关键字，可能导致原先可以正常执行的 SQL 语句在升级 TiDB 后无法被解析语法，此时可以将 `tidb_enable_window_function` 设置为 `0`，该参数的默认值为 `1`。 - -TiDB 支持的窗口函数如下所示： - -| 函数名 | 功能描述 | -| :-------------- | :------------------------------------- | -| [`CUME_DIST()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_cume-dist) | 返回一组值中的累积分布 | -| [`DENSE_RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_dense-rank) | 返回分区中当前行的排名，并且排名是连续的| -| [`FIRST_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_first-value) | 当前窗口中第一行的表达式值 | -| [`LAG()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_lag) | 分区中当前行前面第 N 行的表达式值| -| [`LAST_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_last-value) | 当前窗口中最后一行的表达式值 | -| [`LEAD()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_lead) | 分区中当前行后面第 N 行的表达式值 | -| [`NTH_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_nth-value) | 当前窗口中第 N 行的表达式值 | -| [`NTILE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_ntile)| 将分区划分为 N 桶，为分区中的每一行分配桶号 | -| [`PERCENT_RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_percent-rank)|返回分区中小于当前行的百分比 | -| [`RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_rank)| 返回分区中当前行的排名，排名可能不连续 | -| [`ROW_NUMBER()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_row-number)| 返回分区中当前行的编号 | diff --git a/v3.0/reference/sql/generated-columns.md b/v3.0/reference/sql/generated-columns.md deleted file mode 100644 index 2e04cf5739c6..000000000000 --- a/v3.0/reference/sql/generated-columns.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: 生成列 -category: reference -aliases: ['/docs-cn/sql/generated-columns/'] ---- - -# 生成列 - -为了在功能上兼容 MySQL 5.7，TiDB 支持生成列 (generated column)。生成列的主要的作用之一：从 JSON 数据类型中解出数据，并为该数据建立索引。 - -## 使用 generated column 对 JSON 建索引 - -MySQL 5.7 及 TiDB 都不能直接为 JSON 类型的列添加索引，即**不支持**如下表结构： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - KEY (address_info) -); -``` - -为 JSON 列添加索引之前，首先必须抽取该列为 generated column。 - -以 `city` generated stored column 为例，你可以添加索引： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED, - KEY (city) -); -``` - -该表中，`city` 列是一个 **generated stored column**。顾名思义，此列由该表的其他列生成，对此列进行插入或更新操作时，并不能对之赋值。此列按其定义的表达式生成，并存储在数据库中，这样在读取此列时，就可以直接读取，不用再读取其依赖的 `address_info` 列后再计算得到。`city` 列的索引**存储在数据库中**，并使用和 `varchar(64)` 类的其他索引相同的结构。 - -可使用 generated stored column 的索引，以提高如下语句的执行速度： - -{{< copyable "sql" >}} - -```sql -SELECT name, id FROM person WHERE city = 'Beijing'; -``` - -如果 `$.city` 路径中无数据，则 `JSON_EXTRACT` 返回 `NULL`。如果想增加约束，`city` 列必须是 `NOT NULL`，则可按照以下方式定义 virtual column： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED NOT NULL, - KEY (city) -); -``` - -`INSERT` 和 `UPDATE` 语句都会检查 virtual column 的定义。未通过有效性检测的行会返回错误： - -{{< copyable "sql" >}} - -```sql -INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada')); -``` - -``` -ERROR 1048 (23000): Column 'city' cannot be null -``` - -## 使用 generated virtual column - -TiDB 也支持 generated virtual column，和 generated store column 不同的是，此列按需生成，并不存储在数据库中，也不占用内存空间，因而是**虚拟的**。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) VIRTUAL -); -``` - -## 局限性 - -目前 JSON and generated column 有以下局限性： - -- 不能通过 `ALTER TABLE` 增加 `STORED` 存储方式的 generated column； -- 不能通过 `ALTER TABLE` 在 generated column 上增加索引； -- 不能通过 `ALTER TABLE` 将 generated stored column 转换为普通列，也不能将普通列转换成 generated stored column； -- 不能通过 `ALTER TABLE` 修改 generated stored column 的**生成列表达式**； -- 并未支持所有的 [JSON 函数](/v3.0/reference/sql/functions-and-operators/json-functions.md)。 diff --git a/v3.0/reference/sql/language-structure/comment-syntax.md b/v3.0/reference/sql/language-structure/comment-syntax.md deleted file mode 100644 index 81b24b979a7d..000000000000 --- a/v3.0/reference/sql/language-structure/comment-syntax.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: 注释语法 -category: reference -aliases: ['/docs-cn/sql/comment-syntax/'] ---- - -# 注释语法 - -TiDB 支持三种注释风格： - -* 用 `#` 注释一行 -* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。 -* 用 `/* */` 注释一块，可以注释多行。 - -例： - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; # 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; -- 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1 /* 这是行内注释文字 */ + 1; -``` - -``` -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+ - -> /* - /*> 这是一条 - /*> 多行注释 - /*> */ - -> 1; -``` - -``` -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1--1; -``` - -``` -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) -``` - -TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： - -``` -/*! Specific code */ -``` - -在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 - -例如：`SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...` - -在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` - -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。 - -还有一种注释会被当做是优化器 Hint 特殊对待： - -{{< copyable "sql" >}} - -```sql -SELECT /*+ hint */ FROM ...; -``` - -由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments - -TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/v3.0/reference/performance/optimizer-hints.md) - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 diff --git a/v3.0/reference/sql/language-structure/expression-syntax.md b/v3.0/reference/sql/language-structure/expression-syntax.md deleted file mode 100644 index 011858ae28ab..000000000000 --- a/v3.0/reference/sql/language-structure/expression-syntax.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: 表达式语法 -category: reference -aliases: ['/docs-cn/sql/expression-syntax/'] ---- - -# 表达式语法 (Expression Syntax) - -在 TiDB 中，以下规则是表达式的语法，你可以在 `parser/parser.y` 中找到定义。TiDB 的语法解析是基于 yacc 的。 - -``` -Expression: - singleAtIdentifier assignmentEq Expression - | Expression logOr Expression - | Expression "XOR" Expression - | Expression logAnd Expression - | "NOT" Expression - | Factor IsOrNotOp trueKwd - | Factor IsOrNotOp falseKwd - | Factor IsOrNotOp "UNKNOWN" - | Factor - -Factor: - Factor IsOrNotOp "NULL" - | Factor CompareOp PredicateExpr - | Factor CompareOp singleAtIdentifier assignmentEq PredicateExpr - | Factor CompareOp AnyOrAll SubSelect - | PredicateExpr - -PredicateExpr: - PrimaryFactor InOrNotOp '(' ExpressionList ')' - | PrimaryFactor InOrNotOp SubSelect - | PrimaryFactor BetweenOrNotOp PrimaryFactor "AND" PredicateExpr - | PrimaryFactor LikeOrNotOp PrimaryExpression LikeEscapeOpt - | PrimaryFactor RegexpOrNotOp PrimaryExpression - | PrimaryFactor - -PrimaryFactor: - PrimaryFactor '|' PrimaryFactor - | PrimaryFactor '&' PrimaryFactor - | PrimaryFactor "<<" PrimaryFactor - | PrimaryFactor ">>" PrimaryFactor - | PrimaryFactor '+' PrimaryFactor - | PrimaryFactor '-' PrimaryFactor - | PrimaryFactor '*' PrimaryFactor - | PrimaryFactor '/' PrimaryFactor - | PrimaryFactor '%' PrimaryFactor - | PrimaryFactor "DIV" PrimaryFactor - | PrimaryFactor "MOD" PrimaryFactor - | PrimaryFactor '^' PrimaryFactor - | PrimaryExpression - -PrimaryExpression: - Operand - | FunctionCallKeyword - | FunctionCallNonKeyword - | FunctionCallAgg - | FunctionCallGeneric - | Identifier jss stringLit - | Identifier juss stringLit - | SubSelect - | '!' PrimaryExpression - | '~' PrimaryExpression - | '-' PrimaryExpression - | '+' PrimaryExpression - | "BINARY" PrimaryExpression - | PrimaryExpression "COLLATE" StringName -``` diff --git a/v3.0/reference/sql/language-structure/keywords-and-reserved-words.md b/v3.0/reference/sql/language-structure/keywords-and-reserved-words.md deleted file mode 100644 index 171de01773a4..000000000000 --- a/v3.0/reference/sql/language-structure/keywords-and-reserved-words.md +++ /dev/null @@ -1,484 +0,0 @@ ---- -title: 关键字和保留字 -category: reference -aliases: ['/docs-cn/sql/keywords-and-reserved-words/'] ---- - -# 关键字和保留字 - -关键字在 SQL 中有特殊的意义， 例如 `SELECT`，`UPDATE`，`DELETE`，在作为表名跟函数名的时候，需要特殊对待，例如作为表名，保留字需要被反引号包住： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE select (a INT); -``` - -``` -ERROR 1105 (HY000): line 0 column 19 near " (a INT)" (total length 27) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `select` (a INT); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -`BEGIN` 和 `END` 是关键字， 但不是保留字，所以不需要反引号： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `select` (BEGIN int, END int); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -有一种特殊情况， 如果使用了限定符 `.`，那么也不需要用反引号： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.select (BEGIN int, END int); -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -下表列出了 TiDB 中的关键字和保留字。保留字用 `(R)` 来标识。[窗口函数](/v3.0/reference/sql/functions-and-operators/window-functions.md)的保留字用 `(R-Window)` 来标识 - -{{< tabs-panel "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z" >}} - -A - -- ACTION -- ADD (R) -- ADDDATE -- ADMIN -- AFTER -- ALL (R) -- ALTER (R) -- ALWAYS -- ANALYZE(R) -- AND (R) -- ANY -- AS (R) -- ASC (R) -- ASCII -- AUTO_INCREMENT -- AVG -- AVG_ROW_LENGTH - -B - -- BEGIN -- BETWEEN (R) -- BIGINT (R) -- BINARY (R) -- BINLOG -- BIT -- BIT_XOR -- BLOB (R) -- BOOL -- BOOLEAN -- BOTH (R) -- BTREE -- BY (R) -- BYTE - -C - -- CASCADE (R) -- CASE (R) -- CAST -- CHANGE (R) -- CHAR (R) -- CHARACTER (R) -- CHARSET -- CHECK (R) -- CHECKSUM -- COALESCE -- COLLATE (R) -- COLLATION -- COLUMN (R) -- COLUMNS -- COMMENT -- COMMIT -- COMMITTED -- COMPACT -- COMPRESSED -- COMPRESSION -- CONNECTION -- CONSISTENT -- CONSTRAINT (R) -- CONVERT (R) -- COUNT -- CREATE (R) -- CROSS (R) -- CUME_DIST (R-Window) -- CURRENT_DATE (R) -- CURRENT_TIME (R) -- CURRENT_TIMESTAMP (R) -- CURRENT_USER (R) -- CURTIME - -D - -- DATA -- DATABASE (R) -- DATABASES (R) -- DATE -- DATE_ADD -- DATE_SUB -- DATETIME -- DAY -- DAY_HOUR (R) -- DAY_MICROSECOND (R) -- DAY_MINUTE (R) -- DAY_SECOND (R) -- DDL -- DEALLOCATE -- DEC -- DECIMAL (R) -- DEFAULT (R) -- DELAY_KEY_WRITE -- DELAYED (R) -- DELETE (R) -- DENSE_RANK (R-Window) -- DESC (R) -- DESCRIBE (R) -- DISABLE -- DISTINCT (R) -- DISTINCTROW (R) -- DIV (R) -- DO -- DOUBLE (R) -- DROP (R) -- DUAL (R) -- DUPLICATE -- DYNAMIC - -E - -- ELSE (R) -- ENABLE -- ENCLOSED -- END -- ENGINE -- ENGINES -- ENUM -- ESCAPE -- ESCAPED -- EVENTS -- EXCLUSIVE -- EXECUTE -- EXISTS -- EXPLAIN (R) -- EXTRACT - -F - -- FALSE (R) -- FIELDS -- FIRST -- FIRST_VALUE (R-Window) -- FIXED -- FLOAT (R) -- FLUSH -- FOR (R) -- FORCE (R) -- FOREIGN (R) -- FORMAT -- FROM (R) -- FULL -- FULLTEXT (R) -- FUNCTION - -G - -- GENERATED (R) -- GET_FORMAT -- GLOBAL -- GRANT (R) -- GRANTS -- GROUP (R) -- GROUP_CONCAT -- GROUPS (R-Window) - -H - -- HASH -- HAVING (R) -- HIGH_PRIORITY (R) -- HOUR -- HOUR_MICROSECOND (R) -- HOUR_MINUTE (R) -- HOUR_SECOND (R) - -I - -- IDENTIFIED -- IF (R) -- IGNORE (R) -- IN (R) -- INDEX (R) -- INDEXES -- INFILE (R) -- INNER (R) -- INSERT (R) -- INT (R) -- INTEGER (R) -- INTERVAL (R) -- INTO (R) -- IS (R) -- ISOLATION - -J - -- JOBS -- JOIN (R) -- JSON - -K - -- KEY (R) -- KEY_BLOCK_SIZE -- KEYS (R) -- KILL (R) - -L - -- LAG (R-Window) -- LAST_VALUE (R-Window) -- LEAD (R-Window) -- LEADING (R) -- LEFT (R) -- LESS -- LEVEL -- LIKE (R) -- LIMIT (R) -- LINES (R) -- LOAD (R) -- LOCAL -- LOCALTIME (R) -- LOCALTIMESTAMP (R) -- LOCK (R) -- LONGBLOB (R) -- LONGTEXT (R) -- LOW_PRIORITY (R) - -M - -- MAX -- MAX_ROWS -- MAXVALUE (R) -- MEDIUMBLOB (R) -- MEDIUMINT (R) -- MEDIUMTEXT (R) -- MICROSECOND -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND (R) -- MINUTE_SECOND (R) -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND -- MINUTE_SECOND -- MOD (R) -- MODE -- MODIRY -- MONTH - -N - -- NAMES -- NATIONAL -- NATURAL (R) -- NO -- NO_WRITE_TO_BINLOG (R) -- NONE -- NOT (R) -- NOW -- NTH_VALUE (R-Window) -- NTILE (R-Window) -- NULL (R) -- NUMERIC (R) -- NVARCHAR (R) - -O - -- OFFSET -- ON (R) -- ONLY -- OPTION (R) -- OR (R) -- ORDER (R) -- OUTER (R) -- OVER (R-Window) - -P - -- PARTITION (R) -- PARTITIONS -- PASSWORD -- PERCENT_RANK (R-Window) -- PLUGINS -- POSITION -- PRECISION (R) -- PREPARE -- PRIMARY (R) -- PRIVILEGES -- PROCEDURE (R) -- PROCESS -- PROCESSLIST - -Q - -- QUARTER -- QUERY -- QUICK - -R - -- RANGE (R) -- RANK (R-Window) -- READ (R) -- REAL (R) -- REDUNDANT -- REFERENCES (R) -- REGEXP (R) -- RENAME (R) -- REPEAT (R) -- REPEATABLE -- REPLACE (R) -- RESTRICT (R) -- REVERSE -- REVOKE (R) -- RIGHT (R) -- RLIKE (R) -- ROLLBACK -- ROW -- ROW_COUNT -- ROW_FORMAT -- ROW_NUMBER (R-Window) -- ROWS (R-Window) - -S - -- SCHEMA -- SCHEMAS -- SECOND -- SECOND_MICROSECOND (R) -- SELECT (R) -- SERIALIZABLE -- SESSION -- SET (R) -- SHARE -- SHARED -- SHOW (R) -- SIGNED -- SMALLINT (R) -- SNAPSHOT -- SOME -- SQL_CACHE -- SQL_CALC_FOUND_ROWS (R) -- SQL_NO_CACHE -- START -- STARTING (R) -- STATS -- STATS_BUCKETS -- STATS_HISTOGRAMS -- STATS_META -- STATS_PERSISTENT -- STATUS -- STORED (R) -- SUBDATE -- SUBSTR -- SUBSTRING -- SUM -- SUPER - -T - -- TABLE (R) -- TABLES -- TERMINATED (R) -- TEXT -- THAN -- THEN (R) -- TIDB -- TIDB_INLJ -- TIDB_SMJ -- TIME -- TIMESTAMP -- TIMESTAMPADD -- TIMESTAMPDIFF -- TINYBLOB (R) -- TINYINT (R) -- TINYTEXT (R) -- TO (R) -- TRAILING (R) -- TRANSACTION -- TRIGGER (R) -- TRIGGERS -- TRIM -- TRUE (R) -- TRUNCATE - -U - -- UNCOMMITTED -- UNION (R) -- UNIQUE (R) -- UNKNOWN -- UNLOCK (R) -- UNSIGNED (R) -- UPDATE (R) -- USE (R) -- USER -- USING (R) -- UTC_DATE (R) -- UTC_TIME (R) -- UTC_TIMESTAMP (R) - -V - -- VALUE -- VALUES (R) -- VARBINARY (R) -- VARCHAR (R) -- VARIABLES -- VIEW -- VIRTUAL (R) - -W - -- WARNINGS -- WEEK -- WHEN (R) -- WHERE (R) -- WINDOW (R-Window) -- WITH (R) -- WRITE (R) - -X - -- XOR (R) - -Y - -- YEAR -- YEAR_MONTH (R) - -Z - -- ZEROFILL (R) diff --git a/v3.0/reference/sql/language-structure/literal-values.md b/v3.0/reference/sql/language-structure/literal-values.md deleted file mode 100644 index 0a31abd5c8bf..000000000000 --- a/v3.0/reference/sql/language-structure/literal-values.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -title: 字面值 -category: reference -aliases: ['/docs-cn/sql/literal-values/'] ---- - -# 字面值 - -## String Literals - -String Literals 是一个 bytes 或者 characters 的序列，两端被单引号 `'` 或者双引号 `"` 包围，例如： - -``` -'example string' -"example string" -``` - -如果字符串是连续的，会被合并为一个独立的 string。以下表示是一样的： - -``` -'a string' -'a' ' ' 'string' -"a" ' ' "string" -``` - -如果 `ANSI_QUOTES` SQL MODE 开启了，那么只有单引号内的会被认为是 String Literals，对于双引号内的字符串，会被认为是一个 identifier。 - -binary string 是一串 bytes 组成的字符串，每一个 binary string 有一个叫做 `binary` 的 character set 和 collation。一个非二进制的字符串是一个由字符组成的字符串，它有除 `binary` 外的 character set和与之兼容的 collation。 - -对于两种字符串类型，比较都是基于每个字符的数值。对于 binary string 而言，比较单元就是字节，对于非二进制的字符串，那么单元就是字符，而有的字符集支持多字节字符。 - -一个 String Literal 可以拥有一个可选的 `character set introducer` 和 `COLLATE clause`，可以用来指派特定的字符集跟 collation（TiDB 对此只是做了语法上的兼容，并不实质做处理)。 - -``` -[_charset_name]'string' [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -SELECT _latin1'string'; -SELECT _binary'string'; -SELECT _utf8'string' COLLATE utf8_bin; -``` - -你可以使用 N'literal' 或者 n'literal' 来创建使用 national character set 的字符串，下列语句是一样的： - -{{< copyable "sql" >}} - -```sql -SELECT N'some text'; -SELECT n'some text'; -SELECT _utf8'some text'; -``` - -转义字符： - -- \\0: ASCII NUL (X'00') 字符 -- \\': 单引号 -- \\": 双引号 -- \\b: 退格符号 -- \\n: 换行符 -- \\r: 回车符 -- \\t: tab 符（制表符） -- \\z: ASCII 26 (Ctrl + Z) -- \\\\: 反斜杠 \\ -- \\%: \% -- \\_: \_ - -如果要在 string literal 中使用 `'` 或者 `"`，有以下几种办法： - -* 在 `'` 引用的字符串中，可以用 `''` 来表示单引号。 -* 在 `"` 引用的字符串中，可以用 `""` 来表示双引号。 -* 前面接转义符`\`。 -* 在 `'` 中表示 `"` 或者在 `"` 中表示 `'` 都不需要特别的处理。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/string-literals.html)。 - -## Numeric Literals - -数值字面值包括 integer 跟 Decimal 类型跟浮点数字面值。 - -integer 可以包括 `.` 作为小数点分隔，数字前可以有 `-` 或者 `+` 来表示正数或者负数。 - -精确数值字面值可以表示为如下格式：`1, .2, 3.4, -5, -6.78, +9.10`. - -科学记数法也是被允许的，表示为如下格式：`1.2E3, 1.2E-3, -1.2E3, -1.2E-3`。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/number-literals.html)。 - -## NULL Values - -`NULL` 代表数据为空，它是大小写不敏感的，与 `\N`(大小写敏感) 同义。 - -> **注意：** -> -> `NULL` 跟 `0` 并不一样，跟空字符串 `''` 也不一样。 - -## Hexadecimal Literals - -十六进制字面值是有 `X` 和 `0x` 前缀的字符串，后接表示十六进制的数字。注意 `0x` 是大小写敏感的，不能表示为 `0X`。 - -例: - -``` -X'ac12' -X'12AC' -x'ac12' -x'12AC' -0xac12 -0x12AC -``` - -以下是不合法的十六进制字面值： - -``` -X'1z' (z 不是合法的十六进制值) -0X12AC (0X 必须用小写的 0x) -``` - -对于使用 `X'val'` 格式的十六进制字面值，`val` 必须要有一个数字，可以在前面补一个 0 来避免语法错误。 - -{{< copyable "sql" >}} - -```sql -select X'aff'; -``` - -``` -ERROR 1105 (HY000): line 0 column 13 near ""hex literal: invalid hexadecimal format, must even numbers, but 3 (total length 13) -``` - -{{< copyable "sql" >}} - -```sql -select X'0aff'; -``` - -``` -+---------+ -| X'0aff' | -+---------+ -| - | -+---------+ -1 row in set (0.00 sec) -``` - -默认情况，十六进制字面值是一个二进制字符串。 - -如果需要将一个字符串或者数字转换为十六进制字面值，可以使用内建函数 `HEX()`： - -{{< copyable "sql" >}} - -```sql -SELECT HEX('TiDB'); -``` - -``` -+-------------+ -| HEX('TiDB') | -+-------------+ -| 54694442 | -+-------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT X'54694442'; -``` - -``` -+-------------+ -| X'54694442' | -+-------------+ -| TiDB | -+-------------+ -1 row in set (0.00 sec) -``` - -## Date and Time Literals - -Date 跟 Time 字面值有几种格式，例如用字符串表示，或者直接用数字表示。在 TiDB 里面，当 TiDB 期望一个 Date 的时候，它会把 `'2017-08-24'`， `'20170824'`，`20170824` 当做是 Date。 - -TiDB 的 Date 值有以下几种格式： - -* `'YYYY-MM-DD'` 或者 `'YY-MM-DD'`，这里的 `-` 分隔符并不是严格的，可以是任意的标点符号。比如 `'2017-08-24'`，`'2017&08&24'`， `'2012@12^31'` 都是一样的。唯一需要特别对待的是 '.' 号，它被当做是小数点，用于分隔整数和小数部分。 - Date 和 Time 部分可以被 'T' 分隔，它的作用跟空格符是一样的，例如 `2017-8-24 10:42:00` 跟 `2017-8-24T10:42:00` 是一样的。 -* `'YYYYMMDDHHMMSS'` 或者 `'YYMMDDHHMMSS'`，例如 `'20170824104520'` 和 `'170824104520'` 被当做是 `'2017-08-24 10:45:20'`，但是如果你提供了一个超过范围的值，例如`'170824304520'`，那这就不是一个有效的 Date 字面值。 -* `YYYYMMDDHHMMSS` 或者 `YYMMDDHHMMSS` 注意这里没有单引号或者双引号，是一个数字。例如 `20170824104520`表示为 `'2017-08-24 10:45:20'`。 - -DATETIME 或者 TIMESTAMP 值可以接一个小数部分，用来表示微秒（精度最多到小数点后 6 位），用小数点 `.` 分隔。 - -Dates 如果 year 部分只有两个数字，这是有歧义的（推荐使用四个数字的格式），TiDB 会尝试用以下的规则来解释： - -* year 值如果在 `70-99` 范围，那么被转换成 `1970-1999`。 -* year 值如果在 `00-69` 范围，那么被转换成 `2000-2069`。 - -对于小于 10 的 month 或者 day 值，`'2017-8-4'` 跟 `'2017-08-04'` 是一样的。对于 Time 也是一样，比如 `'2017-08-24 1:2:3'` 跟 `'2017-08-24 01:02:03'`是一样的。 - -在需要 Date 或者 Time 的语境下, 对于数值，TiDB 会根据数值的长度来选定指定的格式： - -* 6 个数字，会被解释为 `YYMMDD`。 -* 12 个数字，会被解释为 `YYMMDDHHMMSS`。 -* 8 个数字，会解释为 `YYYYMMDD`。 -* 14 个数字，会被解释为 `YYYYMMDDHHMMSS`。 - -对于 Time 类型，TiDB 用以下格式来表示： - -* `'D HH:MM:SS'`，或者 `'HH:MM:SS'`，`'HH:MM'`，`'D HH:MM'`，`'D HH'`，`'SS'`，这里的 D 表示 days，合法的范围是 `0-34`。 -* 数值 `HHMMSS`，例如 `231010` 被解释为`'23:10:10'`。 -* 数值 `SS`，`MMSS`，`HHMMSS` 都是可以被当做 Time。 - -Time 类型的小数点也是 `.`，精度最多小数点后 6 位。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-literals.html)。 - -## Boolean Literals - -常量 `TRUE` 和 `FALSE` 等于 1 和 0，它是大小写不敏感的。 - -{{< copyable "sql" >}} - -```sql -SELECT TRUE, true, tRuE, FALSE, FaLsE, false; -``` - -``` -+------+------+------+-------+-------+-------+ -| TRUE | true | tRuE | FALSE | FaLsE | false | -+------+------+------+-------+-------+-------+ -| 1 | 1 | 1 | 0 | 0 | 0 | -+------+------+------+-------+-------+-------+ -1 row in set (0.00 sec) -``` - -## Bit-Value Literals - -位值字面值用 `b` 或者 `0b` 做前缀，后接以 0 跟 1 组成的二进制数字。其中 `0b` 是区分大小写的，`0B` 是会报错的。 - -合法的 Bit-value： - -* b'01' -* B'01' -* 0b01 - -非法的 Bit-value： - -* b'2' (2 不是二进制数值, 必须为 0 或 1) -* 0B01 (0B 必须是小写 0b) - -默认情况，位值字面值是一个二进制字符串。 - -Bit-value 是作为二进制返回的，所以输出到 MySQL Client 可能会显示不出来，如果要转换为可打印的字符，可以使用内建函数 `BIN()` 或者 `HEX()`： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t (b BIT(8)); -INSERT INTO t SET b = b'00010011'; -INSERT INTO t SET b = b'1110'; -INSERT INTO t SET b = b'100101'; -``` - -{{< copyable "sql" >}} - -```sql -SELECT b+0, BIN(b), HEX(b) FROM t; -``` - -``` -+------+--------+--------+ -| b+0 | BIN(b) | HEX(b) | -+------+--------+--------+ -| 19 | 10011 | 13 | -| 14 | 1110 | E | -| 37 | 100101 | 25 | -+------+--------+--------+ -3 rows in set (0.00 sec) -``` diff --git a/v3.0/reference/sql/language-structure/schema-object-names.md b/v3.0/reference/sql/language-structure/schema-object-names.md deleted file mode 100644 index 979070e2db1f..000000000000 --- a/v3.0/reference/sql/language-structure/schema-object-names.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Schema Object Names -category: reference -aliases: ['/docs-cn/sql/schema-object-names/'] ---- - -# Schema Object Names - -在 TiDB 中，包括 database，table，index，column，alias 等等都被认为是 identifier (标识符，之后阐述用英文). - -在 TiDB 中，identifier可以被反引号 (\`) 包裹，为了阐述方便，我们叫这种情况为 `被引用`。identifier 也可以不被 \` 包裹。但是如果一个 identifier 存在一个特殊符号或者是一个保留关键字，那么你必须要 `引用` 它。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM `table` WHERE `table`.id = 20; -``` - -如果`ANSI_QUOTES` sql mode 被设置了，那么我们认为被双引号 `"` 包裹的字符串为 identifier。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE "test" (a varchar(10)); -``` - -``` -ERROR 1105 (HY000): line 0 column 19 near " (a varchar(10))" (total length 35) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION sql_mode='ANSI_QUOTES'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE "test" (a varchar(10)); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -如果你需要在被引用的 identifier 中使用反引号这个字符，那你需要重复两次，例如你需要创建一个表为 a`b： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `a``b` (a int); -``` - -在 select 语句中，alias 语句可以用 identifier 或者字符串： - -{{< copyable "sql" >}} - -```sql -SELECT 1 AS `identifier`, 2 AS 'string'; -``` - -``` -+------------+--------+ -| identifier | string | -+------------+--------+ -| 1 | 2 | -+------------+--------+ -1 row in set (0.00 sec) -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/identifiers.html) - -## Identifier Qualifiers - -Object Names (对象名字) 可以被限定也可以不用。例如你可以在创建表的时候不指定 database names： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t (i int); -``` - -但是如果你之前没有设定过默认的数据库，会报 `ERROR 1046 (3D000): No database selected` 错误。当然你也可以指定数据库限定名： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.t (i int); -``` - -对于 `.` 左右两端可以出现空格，`table_name.col_name` 等于 `table_name . col_name`。 - -如果你要引用这个 identifier，那么请使用： - -``` -`table_name`.`col_name` -``` - -而不是： - -``` -`table_name.col_name` -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/identifier-qualifiers.html) diff --git a/v3.0/reference/sql/language-structure/user-defined-variables.md b/v3.0/reference/sql/language-structure/user-defined-variables.md deleted file mode 100644 index 66bad5400c7e..000000000000 --- a/v3.0/reference/sql/language-structure/user-defined-variables.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -title: 用户自定义变量 -category: reference -aliases: ['/docs-cn/sql/user-defined-variables/'] ---- - -# 用户自定义变量 - -用户自定义变量格式为 `@var_name`。`var_name` 目前只支持字母，数字，`_$`组成。用户自定义变量是大小写不敏感的。 - -用户自定义变量是跟 session 绑定的，也就是说只有当前连接可以看见设置的用户变量，其他客户端连接无法查看到。 - -用 `SET` 语句可以设置用户自定义变量： - -{{< copyable "sql" >}} - -```sql -SET @var_name = expr [, @var_name = expr] ...; -``` - -或 - -{{< copyable "sql" >}} - -```sql -SET @var_name := expr; -``` - -对于 `SET` 语句，赋值操作符可以是 `=` 也可以是 `:=` - -例： - -{{< copyable "sql" >}} - -```sql -SET @a1=1, @a2=2, @a3:=4; -``` - -{{< copyable "sql" >}} - -```sql -SELECT @a1, @a2, @t3, @a4 := @a1+@a2+@a3; -``` - -``` -+------+------+------+--------------------+ -| @a1 | @a2 | @a3 | @a4 := @a1+@a2+@a3 | -+------+------+------+--------------------+ -| 1 | 2 | 4 | 7 | -+------+------+------+--------------------+ -``` - -如果设置用户变量用了 `HEX` 或者 `BIT` 值，TiDB会把它当成二进制字符串。如果你要将其设置成数字，那么需要手动加上 `CAST转换`: `CAST(.. AS UNSIGNED)`： - -{{< copyable "sql" >}} - -```sql -SELECT @v1, @v2, @v3; -``` - -``` -+------+------+------+ -| @v1 | @v2 | @v3 | -+------+------+------+ -| A | 65 | 65 | -+------+------+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @v1 = b'1000001'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @v2 = b'1000001'+0; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @v3 = CAST(b'1000001' AS UNSIGNED); -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT @v1, @v2, @v3; -``` - -``` -+------+------+------+ -| @v1 | @v2 | @v3 | -+------+------+------+ -| A | 65 | 65 | -+------+------+------+ -1 row in set (0.00 sec) -``` - -如果获取一个没有设置过的变量，会返回一个 NULL： - -{{< copyable "sql" >}} - -```sql -select @not_exist; -``` - -``` -+------------+ -| @not_exist | -+------------+ -| NULL | -+------------+ -1 row in set (0.00 sec) -``` - -用户自定义变量不能直接在 SQL 语句中被当成 identifier，例： - -{{< copyable "sql" >}} - -```sql -select * from t; -``` - -``` -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @col = "a"; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT @col FROM t; -``` - -``` -+------+ -| @col | -+------+ -| a | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT `@col` FROM t; -``` - -``` -ERROR 1054 (42S22): Unknown column '@col' in 'field list' -``` - -{{< copyable "sql" >}} - -```sql -SET @col = "`a`"; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT @col FROM t; -``` - -``` -+------+ -| @col | -+------+ -| `a` | -+------+ -1 row in set (0.01 sec) -``` - -但是有一个例外是如果你在 PREPARE 语句中使用它，是可以的： - -{{< copyable "sql" >}} - -```sql -PREPARE stmt FROM "SELECT @c FROM t"; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE stmt; -``` - -``` -+------+ -| @c | -+------+ -| a | -+------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE stmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/user-variables.html)。 diff --git a/v3.0/reference/sql/partitioning.md b/v3.0/reference/sql/partitioning.md deleted file mode 100644 index bd78f0cd6e82..000000000000 --- a/v3.0/reference/sql/partitioning.md +++ /dev/null @@ -1,913 +0,0 @@ ---- -title: 分区表 -category: reference ---- - -# 分区表 - -本文介绍 TiDB 的分区表。 - -## 分区类型 - -本节介绍在 TiDB 中的分区类型。当前支持的类型包括 Range 分区和 Hash 分区。Range 分区可以用于解决业务中大量删除带来的性能问题，支持快速删除分区。Hash 分区则可以用于大量写入场景下的数据打散。 - -### Range 分区 - -一个表按 range 分区是指，对于表的每个分区中包含的所有行，按分区表达式计算的值都落在给定的范围内。Range 必须是连续的，并且不能有重叠，通过使用 `VALUES LESS THAN` 操作进行定义。 - -下列场景中，假设你要创建一个人事记录的表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -); -``` - -你可以根据需求按各种方式进行 range 分区。其中一种方式是按 `store_id` 列进行分区。你可以这样做： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -) - -PARTITION BY RANGE (store_id) ( - PARTITION p0 VALUES LESS THAN (6), - PARTITION p1 VALUES LESS THAN (11), - PARTITION p2 VALUES LESS THAN (16), - PARTITION p3 VALUES LESS THAN (21) -); -``` - -在这个分区模式中，所有 `store_id` 为 1 到 5 的员工，都存储在分区 `p0` 里面，`store_id` 为 6 到 10 的员工则存储在分区 `p1` 里面。range 分区要求，分区的定义必须是有序的，按从小到大递增。 - -新插入一行数据 `(72, 'Mitchell', 'Wilson', '1998-06-25', NULL, 13)` 将会落到分区 `p2` 里面。但如果你插入一条 `store_id` 大于 20 的记录，则会报错，因为 TiDB 无法知晓应该将它插入到哪个分区。这种情况下，可以在建表时使用最大值： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -) - -PARTITION BY RANGE (store_id) ( - PARTITION p0 VALUES LESS THAN (6), - PARTITION p1 VALUES LESS THAN (11), - PARTITION p2 VALUES LESS THAN (16), - PARTITION p3 VALUES LESS THAN MAXVALUE -); -``` - -`MAXVALUE` 表示一个比所有整数都大的整数。现在，所有 `store_id` 列大于等于 16 的记录都会存储在 `p3` 分区中。 - -你也可以按员工的职位编号进行分区，也就是使用 `job_code` 列的值进行分区。假设两位数字编号是用于普通员工，三位数字编号是用于办公室以及客户支持，四位数字编号是管理层职位，那么你可以这样建表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -) - -PARTITION BY RANGE (job_code) ( - PARTITION p0 VALUES LESS THAN (100), - PARTITION p1 VALUES LESS THAN (1000), - PARTITION p2 VALUES LESS THAN (10000) -); -``` - -在这个例子中，所有普通员工存储在 `p0` 分区，办公室以及支持人员在 `p1` 分区，管理者在 `p2` 分区。 - -除了可以按 `store_id` 切分，你还可以按日期切分。例如，假设按员工离职的年份进行分区： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT, - store_id INT -) - -PARTITION BY RANGE ( YEAR(separated) ) ( - PARTITION p0 VALUES LESS THAN (1991), - PARTITION p1 VALUES LESS THAN (1996), - PARTITION p2 VALUES LESS THAN (2001), - PARTITION p3 VALUES LESS THAN MAXVALUE -); -``` - -在 range 分区中，可以基于 `timestamp` 列的值分区，并使用 `unix_timestamp()` 函数，例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE quarterly_report_status ( - report_id INT NOT NULL, - report_status VARCHAR(20) NOT NULL, - report_updated TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP -) - -PARTITION BY RANGE ( UNIX_TIMESTAMP(report_updated) ) ( - PARTITION p0 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-01-01 00:00:00') ), - PARTITION p1 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-04-01 00:00:00') ), - PARTITION p2 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-07-01 00:00:00') ), - PARTITION p3 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-10-01 00:00:00') ), - PARTITION p4 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-01-01 00:00:00') ), - PARTITION p5 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-04-01 00:00:00') ), - PARTITION p6 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-07-01 00:00:00') ), - PARTITION p7 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-10-01 00:00:00') ), - PARTITION p8 VALUES LESS THAN ( UNIX_TIMESTAMP('2010-01-01 00:00:00') ), - PARTITION p9 VALUES LESS THAN (MAXVALUE) -); -``` - -对于 timestamp 值，使用其它的分区表达式是不允许的。 - -Range 分区在下列条件之一或者多个都满足时，尤其有效： - -* 删除旧数据。如果你使用之前的 `employees` 表的例子，你可以简单使用 `ALTER TABLE employees DROP PARTITION p0;` 删除所有在 1991 年以前停止继续在这家公司工作的员工记录。这会比使用 `DELETE FROM employees WHERE YEAR(separated) <= 1990;` 执行快得多。 -* 使用包含时间或者日期的列，或者是其它按序生成的数据。 -* 频繁查询分区使用的列。例如执行这样的查询 `EXPLAIN SELECT COUNT(*) FROM employees WHERE separated BETWEEN '2000-01-01' AND '2000-12-31' GROUP BY store_id;` 时，TiDB 可以迅速确定，只需要扫描 `p2` 分区的数据，因为其它的分区不满足 `where` 条件。 - -### Hash 分区 - -Hash 分区主要用于保证数据均匀地分散到一定数量的分区里面。在 range 分区中你必须为每个分区指定值的范围；在 hash 分区中，你只需要指定分区的数量。 - -使用 hash 分区时，需要在 `CREATE TABLE` 后面添加 `PARTITION BY HASH (expr)`，其中 `expr` 是一个返回整数的表达式。当这一列的类型是整数类型时，它可以是一个列名。此外，你很可能还需要加上 `PARTITIONS num`，其中 `num` 是一个正整数，表示将表划分多少分区。 - -下面的语句将创建一个 hash 分区表，按 `store_id` 分成 4 个分区： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT, - store_id INT -) - -PARTITION BY HASH(store_id) -PARTITIONS 4; -``` - -如果不指定 `PARTITIONS num`，默认的分区数量为 1。 - -你也可以使用一个返回整数的 SQL 表达式。例如，你可以按入职年份分区： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT, - store_id INT -) - -PARTITION BY HASH( YEAR(hired) ) -PARTITIONS 4; -``` - -最高效的 hash 函数是作用在单列上，并且函数的单调性是跟列的值是一样递增或者递减的，因为这种情况可以像 range 分区一样裁剪。 - -例如，`date_col` 是类型为 `DATE` 的列，表达式 `TO_DAYS(date_col)` 的值是直接随 `date_col` 的值变化的。`YEAR(date_col)` 跟 `TO_DAYS(date_col)` 就不太一样，因为不是每次 `date_col` 变化时 `YEAR(date_col)` 都会得到不同的值。即使如此，`YEAR(date_col)` 也仍然是一个比较好的 hash 函数，因为它的结果是随着 `date_col` 的值的比例变化的。 - -作为对比，假设我们有一个类型是 INT 的 `int_col` 的列。考虑一下表达式 `POW(5-int_col,3) + 6`，这并不是一个比较好的 hash 函数，因为随着 `int_col` 的值的变化，表达式的结果不会成比例地变化。改变 `int_col` 的值会使表达式的结果的值变化巨大。例如，`int_col` 从 5 变到 6 表达式的结果变化是 -1，但是从 6 变到 7 的时候表达式的值的变化是 -7。 - -总而言之，表达式越接近 `y = cx` 的形式，它越是适合作为 hash 函数。因为表达式越是非线性的，在各个分区上面的数据的分布越是倾向于不均匀。 - -理论上，hash 分区也是可以做分区裁剪的。而实际上对于多列的情况，实现很难并且计算很耗时。因此，不推荐 hash 分区在表达式中涉及多列。 - -使用 `PARTITIION BY HASH` 的时候，TiDB 通过表达式的结果做“取余”运算，决定数据落在哪个分区。换句话说，如果分区表达式是 `expr`，分区数是 `num`，则由 `MOD(expr, num)` 决定存储的分区。假设 `t1` 定义如下： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATE) - PARTITION BY HASH( YEAR(col3) ) - PARTITIONS 4; -``` - -向 `t1` 插入一行数据，其中 `col3` 列的值是 '2005-09-15'，这条数据会被插入到分区 1 中： - -``` -MOD(YEAR('2005-09-01'),4) -= MOD(2005,4) -= 1 -``` - -### 分区对 NULL 值的处理 - -TiDB 允许计算结果为 NULL 的分区表达式。注意，NULL 不是一个整数类型，NULL 小于所有的整数类型值，正如 `ORDER BY` 的规则一样。 - -#### Range 分区对 NULL 的处理 - -如果插入一行到 range 分区表，它的分区列的计算结果是 NULL，那么这一行会被插入到最小的那个分区。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - c1 INT, - c2 VARCHAR(20) -) - -PARTITION BY RANGE(c1) ( - PARTITION p0 VALUES LESS THAN (0), - PARTITION p1 VALUES LESS THAN (10), - PARTITION p2 VALUES LESS THAN MAXVALUE -); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1 partition(p0); -``` - -``` -+------|--------+ -| c1 | c2 | -+------|--------+ -| NULL | mothra | -+------|--------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1 partition(p1); -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1 partition(p2); -``` - -``` -Empty set (0.00 sec) -``` - -删除 `p0` 后验证： - -{{< copyable "sql" >}} - -```sql -alter table t1 drop partition p0; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1; -``` - -``` -Empty set (0.00 sec) -``` - -#### Hash 分区对 NULL 的处理 - -在 Hash 分区中 NULL 值的处理有所不同，如果分区表达式的计算结果为 NULL，它会被当作 0 值处理。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE th ( - c1 INT, - c2 VARCHAR(20) -) - -PARTITION BY HASH(c1) -PARTITIONS 2; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO th VALUES (NULL, 'mothra'), (0, 'gigan'); -``` - -``` -Query OK, 2 rows affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from th partition (p0); -``` - -``` -+------|--------+ -| c1 | c2 | -+------|--------+ -| NULL | mothra | -| 0 | gigan | -+------|--------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from th partition (p1); -``` - -``` -Empty set (0.00 sec) -``` - -可以看到，插入的记录 `(NULL, 'mothra')` 跟 `(0, 'gigan')` 落在了同一个分区。 - -## 分区管理 - -通过 `ALTER TABLE` 语句可以执行一些添加、删除、合并、切分、重定义分区的操作。 - -### Range 分区管理 - -创建分区表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE members ( - id INT, - fname VARCHAR(25), - lname VARCHAR(25), - dob DATE -) - -PARTITION BY RANGE( YEAR(dob) ) ( - PARTITION p0 VALUES LESS THAN (1980), - PARTITION p1 VALUES LESS THAN (1990), - PARTITION p2 VALUES LESS THAN (2000) -); -``` - -删除分区： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members DROP PARTITION p2; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -清空分区： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members TRUNCATE PARTITION p1; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -> **注意：** -> -> `ALTER TABLE ... REORGANIZE PARTITION` 在 TiDB 中暂不支持。 - -添加分区： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members ADD PARTITION (PARTITION p3 VALUES LESS THAN (2010)); -``` - -Range 分区中，`ADD PARTITION` 只能在分区列表的最后面添加，如果是添加到已存在的分区范围则会报错： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members - ADD PARTITION ( - PARTITION n VALUES LESS THAN (1970)); -``` - -``` -ERROR 1463 (HY000): VALUES LESS THAN value must be strictly » - increasing for each partition -``` - -### Hash 分区管理 - -跟 Range 分区不同，Hash 分区不能够 `DROP PARTITION`。 - -目前 TiDB 的实现暂时不支持 `ALTER TABLE ... COALESCE PARTITION`。 - -## 分区裁剪 - -有一个优化叫做“分区裁剪”，它基于一个非常简单的概念：不需要扫描那些匹配不上的分区。 - -假设创建一个分区表 `t1`： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - fname VARCHAR(50) NOT NULL, - lname VARCHAR(50) NOT NULL, - region_code TINYINT UNSIGNED NOT NULL, - dob DATE NOT NULL -) - -PARTITION BY RANGE( region_code ) ( - PARTITION p0 VALUES LESS THAN (64), - PARTITION p1 VALUES LESS THAN (128), - PARTITION p2 VALUES LESS THAN (192), - PARTITION p3 VALUES LESS THAN MAXVALUE -); -``` - -如果你想获得这个 select 语句的结果： - -{{< copyable "sql" >}} - -```sql -SELECT fname, lname, region_code, dob - FROM t1 - WHERE region_code > 125 AND region_code < 130; -``` - -很显然，结果必然是在分区 `p1` 或者 `p2` 里面，也就是说，我们只需要在 `p1` 和 `p2` 里面去搜索匹配的行。去掉不必要的分区就是所谓的裁剪。优化器如果能裁剪掉一部分的分区，则执行会快于处理整个不做分区的表的相同查询。 - -优化器可以通过 where 条件裁剪的两个场景： - -* partition_column = constant -* partition_column IN (constant1, constant2, ..., constantN) - -## 分区选择 - -SELECT 语句中支持分区选择。实现通过使用一个 `PARTITION` 选项实现。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - fname VARCHAR(25) NOT NULL, - lname VARCHAR(25) NOT NULL, - store_id INT NOT NULL, - department_id INT NOT NULL -) - -PARTITION BY RANGE(id) ( - PARTITION p0 VALUES LESS THAN (5), - PARTITION p1 VALUES LESS THAN (10), - PARTITION p2 VALUES LESS THAN (15), - PARTITION p3 VALUES LESS THAN MAXVALUE -); - -INSERT INTO employees VALUES - ('', 'Bob', 'Taylor', 3, 2), ('', 'Frank', 'Williams', 1, 2), - ('', 'Ellen', 'Johnson', 3, 4), ('', 'Jim', 'Smith', 2, 4), - ('', 'Mary', 'Jones', 1, 1), ('', 'Linda', 'Black', 2, 3), - ('', 'Ed', 'Jones', 2, 1), ('', 'June', 'Wilson', 3, 1), - ('', 'Andy', 'Smith', 1, 3), ('', 'Lou', 'Waters', 2, 4), - ('', 'Jill', 'Stone', 1, 4), ('', 'Roger', 'White', 3, 2), - ('', 'Howard', 'Andrews', 1, 2), ('', 'Fred', 'Goldberg', 3, 3), - ('', 'Barbara', 'Brown', 2, 3), ('', 'Alice', 'Rogers', 2, 2), - ('', 'Mark', 'Morgan', 3, 3), ('', 'Karen', 'Cole', 3, 2); -``` - -你可以查看存储在分区 `p1` 中的行： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM employees PARTITION (p1); -``` - -``` -+----|-------|--------|----------|---------------+ -| id | fname | lname | store_id | department_id | -+----|-------|--------|----------|---------------+ -| 5 | Mary | Jones | 1 | 1 | -| 6 | Linda | Black | 2 | 3 | -| 7 | Ed | Jones | 2 | 1 | -| 8 | June | Wilson | 3 | 1 | -| 9 | Andy | Smith | 1 | 3 | -+----|-------|--------|----------|---------------+ -5 rows in set (0.00 sec) -``` - -如果希望获得多个分区中的行，可以提供分区名的列表，用逗号隔开。例如，`SELECT * FROM employees PARTITION (p1, p2)` 返回分区 `p1` 和 `p2` 的所有行。 - -使用分区选择时，仍然可以使用 where 条件，以及 ORDER BY 和 LIMIT 等选项。使用 HAVING 和 GROUP BY 等聚合选项也是支持的。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM employees PARTITION (p0, p2) - WHERE lname LIKE 'S%'; -``` - -``` -+----|-------|-------|----------|---------------+ -| id | fname | lname | store_id | department_id | -+----|-------|-------|----------|---------------+ -| 4 | Jim | Smith | 2 | 4 | -| 11 | Jill | Stone | 1 | 4 | -+----|-------|-------|----------|---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT id, CONCAT(fname, ' ', lname) AS name - FROM employees PARTITION (p0) ORDER BY lname; -``` - -``` -+----|----------------+ -| id | name | -+----|----------------+ -| 3 | Ellen Johnson | -| 4 | Jim Smith | -| 1 | Bob Taylor | -| 2 | Frank Williams | -+----|----------------+ -4 rows in set (0.06 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT store_id, COUNT(department_id) AS c - FROM employees PARTITION (p1,p2,p3) - GROUP BY store_id HAVING c > 4; -``` - -``` -+---|----------+ -| c | store_id | -+---|----------+ -| 5 | 2 | -| 5 | 3 | -+---|----------+ -2 rows in set (0.00 sec) -``` - -分支选择支持所有类型的分区表，无论是 range 分区或是 hash 分区等。对于 hash 分区，如果没有指定分区名，会自动使用 `p0`、`p1`、`p2`、……、或 `pN-1` 作为分区名。 - -在 `INSERT ... SELECT` 的 `SELECT` 中也是可以使用分区选择的。 - -## 分区的约束和限制 - -本节介绍当前 TiDB 分区表的一些约束和限制。 - -### 分区键，主键和唯一键 - -本节讨论分区键，主键和唯一键之间的关系。一句话总结它们之间的关系要满足的规则：**分区表的每个唯一键，必须包含分区表达式中用到的所有列**。 - -> every unique key on the table must use every column in the table's partitioning expression. - -这里所指的唯一也包含了主键，因为根据主键的定义，主键必须是唯一的。例如，下面这些建表语句就是无效的： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col2) -) - -PARTITION BY HASH(col3) -PARTITIONS 4; - -CREATE TABLE t2 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1), - UNIQUE KEY (col3) -) - -PARTITION BY HASH(col1 + col3) -PARTITIONS 4; -``` - -它们都是有唯一键但没有包含所有分区键的。 - -下面是一些合法的语句的例子： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col2, col3) -) - -PARTITION BY HASH(col3) -PARTITIONS 4; - -CREATE TABLE t2 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col3) -) - -PARTITION BY HASH(col1 + col3) -PARTITIONS 4; -``` - -下例中会产生一个报错： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t3 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col2), - UNIQUE KEY (col3) -) - -PARTITION BY HASH(col1 + col3) - PARTITIONS 4; -``` - -``` -ERROR 1491 (HY000): A PRIMARY KEY must include all columns in the table's partitioning function -``` - -原因是 `col1` 和 `col3` 出现在分区键中，但是几个唯一键定义并没有完全包含它们。 - -下面这个表就没法做分区了，因为无论如何都不可能找到满足条件的分区键： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t4 ( - col1 INT NOT NULL, - col2 INT NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col3), - UNIQUE KEY (col2, col4) -); -``` - -根据定义，主键也是唯一键，下面两个建表语句是无效的： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t5 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - PRIMARY KEY(col1, col2) -) - -PARTITION BY HASH(col3) -PARTITIONS 4; - -CREATE TABLE t6 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - PRIMARY KEY(col1, col3), - UNIQUE KEY(col2) -) - -PARTITION BY HASH( YEAR(col2) ) -PARTITIONS 4; -``` - -两个例子中，主键都没有包含分区表达式中的全部的列。 - -如果既没有主键，也没有唯一键，则不存在这个限制。 - -DDL 变更时，添加唯一索引也需要考虑到这个限制。比如创建了这样一个表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t_no_pk (c1 INT, c2 INT) - PARTITION BY RANGE(c1) ( - PARTITION p0 VALUES LESS THAN (10), - PARTITION p1 VALUES LESS THAN (20), - PARTITION p2 VALUES LESS THAN (30), - PARTITION p3 VALUES LESS THAN (40) - ); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -通过 `ALTER TABLE` 添加非唯一索引是可以的。但是添加唯一索引时，唯一索引里面必须包含 `c1` 列。 - -### 关于函数的分区限制 - -只有以下函数可以用于分区表达式： - -``` -ABS() -CEILING() (see CEILING() and FLOOR()) -DATEDIFF() -DAY() -DAYOFMONTH() -DAYOFWEEK() -DAYOFYEAR() -EXTRACT() (see EXTRACT() function with WEEK specifier) -FLOOR() (see CEILING() and FLOOR()) -HOUR() -MICROSECOND() -MINUTE() -MOD() -MONTH() -QUARTER() -SECOND() -TIME_TO_SEC() -TO_DAYS() -TO_SECONDS() -UNIX_TIMESTAMP() (with TIMESTAMP columns) -WEEKDAY() -YEAR() -YEARWEEK() -``` - -### 兼容性 - -目前 TiDB 里面只实现了 Range 分区和 Hash 分区，其它的 MySQL 分区类型比如 List 分区和 Key 分区尚不支持。 - -对于 Range Columns 类型的分区表，目前只支持单列的场景。 - -分区管理方面，只要底层实现可能会涉及数据挪到的操作，目前都暂不支持。包括且不限于：调整 Hash 分区表的分区数量，修改 Range 分区表的范围，合并分区，交换分区等。 - -对于暂不支持的分区类型，在 TiDB 中建表时会忽略分区信息，以普通表的形式创建，并且会报 Warning。 - -INFORMATION_SCHEMA.PARTITION 表暂不支持。 - -Load Data 暂时不支持分区选择。 - -{{< copyable "sql" >}} - -```sql -create table t (id int, val int) partition by hash(id) partitions 4; -``` - -普通的 Load Data 操作在 TiDB 中是支持的，如下： - -{{< copyable "sql" >}} - -```sql -load local data infile "xxx" into t ... -``` - -但 Load Data 不支持分区选择操作： - -{{< copyable "sql" >}} - -```sql -load local data infile "xxx" into t partition (p1)... -``` - -对于分区表，`select * from t` 的返回结果是分区之间无序的。这跟 MySQL 不同，MySQL 的返回结果是分区之间有序，分区内部无序。 - -{{< copyable "sql" >}} - -```sql -create table t (id int, val int) partition by range (id) ( - partition p0 values less than (3), - partition p1 values less than (7), - partition p2 values less than (11)); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values (1, 2), (3, 4),(5, 6),(7,8),(9,10); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -TiDB 每次返回结果会不同，例如： - -{{< copyable "sql" >}} - -``` -select * from t; -``` - -``` -+------|------+ -| id | val | -+------|------+ -| 7 | 8 | -| 9 | 10 | -| 1 | 2 | -| 3 | 4 | -| 5 | 6 | -+------|------+ -5 rows in set (0.00 sec) -``` - -MySQL 的返回结果： - -{{< copyable "sql" >}} - -``` -select * from t; -``` - -``` -+------|------+ -| id | val | -+------|------+ -| 1 | 2 | -| 3 | 4 | -| 5 | 6 | -| 7 | 8 | -| 9 | 10 | -+------|------+ -5 rows in set (0.00 sec) -``` diff --git a/v3.0/reference/sql/sql-mode.md b/v3.0/reference/sql/sql-mode.md deleted file mode 100644 index 31f30793da4a..000000000000 --- a/v3.0/reference/sql/sql-mode.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: SQL Mode -category: reference ---- - -# SQL 模式 - -TiDB 服务器采用不同 SQL 模式来操作，且不同客户端可以应用不同模式。SQL 模式定义 TiDB 支持哪些 SQL 语法及执行哪种数据验证检查. - -TiDB 启动之前采用修改 `--sql-mode="modes"` 配项设置 SQL 模式。 - -TiDB 启动之后采用 `SET [ SESSION | GLOBAL ] sql_mode='modes'`设置 SQL 模式。设置 GLOBAL 级别的 SQL 模式时用户需要有 SUPER 权限，并且只会影响到从设置 SQL 模式开始后续新建立的连接（注：老连接不受影响)。 SESSION 级别的 SQL 模式的变化只会影响当前的客户端。 - -Modes 是用逗号 (',') 间隔开的一系列不同的模式。使用 `SELECT @@sql_mode` 语句查询当前 SQL 模式，SQL 模式默认值：`ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION`。 - -## 重要的 sql_mode 值 - -* ANSI: 符合标准 SQL ，对数据进行校验，如果不符合定义类型或长度，对数据类型调整或截断保存，且返回warning警告。 -* STRICT_TRANS_TABLES: 严格模式，对数据进严格校验，但数据出现错误时，插入到表中，并且返回错误。 -* TRADITIONAL: 采用此模式使 TiDB 的行为象 "传统" SQL 数据库系统，当在列中插入不正确的值时“给出错误而不是警告”，一旦发现错误立即放弃INSERT/UPDATE。 - -## SQL mode 列表 - -| 名称 | 含义 | -| --- | --- | -| PIPES_AS_CONCAT | 将 "\|\|" 视为字符串连接操作符（＋）(同CONCAT())，而不视为OR（支持) | -| ANSI_QUOTES | 将 `"` 视为识别符，如果启用 ANSI_QUOTES，只单引号内的会被认为是 String Literals，双引号被解释为识别符，因此不能用双引号来引用字符串（支持）| -| IGNORE_SPACE | 若开启该模式，系统忽略空格。例如：“user” 和 “user “ 是相同的（支持）| -| ONLY_FULL_GROUP_BY | 如果 GROUP BY 出现的列并没有在 SELECT，HAVING，ORDER BY 中出现，此 SQL 不合法，因为不在 GROUP BY 中的列被查询展示出来不符合正常现象 （支持) | -| NO_UNSIGNED_SUBTRACTION | 在减运算中，如果某个操作数没有符号，不要将结果标记为UNSIGNED （支持）| -| NO_DIR_IN_CREATE | 创建表时，忽视所有 INDEX DIRECTORY 和 DATA DIRECTORY 指令，该选项仅对从复制服务器有用 （仅语法支持）| -| NO_KEY_OPTIONS | 使用 SHOW CREATE TABLE 时不会输出 MySQL 特有的语法部分，如 ENGINE ，使用 mysqldump 跨DB种类迁移的时需要考虑此选项（仅语法支持）| -| NO_FIELD_OPTIONS | 使用 SHOW CREATE TABLE 时不会输出 MySQL 特有的语法部分，如 ENGINE ，使用 mysqldump 跨DB种类迁移的时需要考虑此选项（仅语法支持）| -| NO_TABLE_OPTIONS | 使用 SHOW CREATE TABLE 时不会输出 MySQL 特有的语法部分，如 ENGINE ，使用 mysqldump 跨DB种类迁移的时需要考虑此选项（仅语法支持）| -| NO_AUTO_VALUE_ON_ZERO | 若启用该模式，在AUTO_INCREMENT列的处理传入的值是 0 或者具体数值时系统直接将该值写入此列，传入 NULL 时系统自动生成下一个序列号（支持）| -| NO_BACKSLASH_ESCAPES | 若启用该模式，`\` 反斜杠符号仅代表它自己（支持）| -| STRICT_TRANS_TABLES | 对于事务存储引擎启用严格模式，insert非法值之后，回滚整条语句（支持）| -| STRICT_ALL_TABLES | 对于事务型表，写入非法值之后，回滚整个事务语句（支持）| -| NO_ZERO_IN_DATE | 在严格模式，不接受月或日部分为0的日期。如果使用IGNORE选项，我们为类似的日期插入'0000-00-00'。在非严格模式，可以接受该日期，但会生成警告 （支持） -| NO_ZERO_DATE | 在严格模式，不要将 '0000-00-00'做为合法日期。你仍然可以用IGNORE选项插入零日期。在非严格模式，可以接受该日期，但会生成警告 （支持）| -| ALLOW_INVALID_DATES | 不检查全部日期的合法性，仅检查月份值在 1 到 12 及 日期值在 1 到31 之间，仅适用于 DATE 和 DATATIME 列，TIMESTAMP 列需要全部检查其合法性 （支持）| -| ERROR_FOR_DIVISION_BY_ZERO | 若启用该模式，在 INSERT 或 UPDATE 过程中，被除数为 0 值时，系统产生错误
若未启用该模式，被除数为 0 值时，系统产生警告，并用 NULL 代替 （支持） | -| NO_AUTO_CREATE_USER | 防止GRANT自动创建新用户，但指定密码除外 （支持）| -| HIGH_NOT_PRECEDENCE | NOT 操作符的优先级是表达式。例如： NOT a BETWEEN b AND c 被解释为 NOT (a BETWEEN b AND c)。在部份旧版本MySQL中， 表达式被解释为(NOT a) BETWEEN b AND c (支持) | -| NO_ENGINE_SUBSTITUTION | 如果需要的存储引擎被禁用或未编译，可以防止自动替换存储引擎 （仅语法支持）| -| PAD_CHAR_TO_FULL_LENGTH | 若启用该模式，系统对于 CHAR 类型不会截断尾部空格（支持）| -| REAL_AS_FLOAT | 将REAL视为FLOAT的同义词，而不是DOUBLE的同义词 （支持）| -| POSTGRESQL | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS （支持）| -| MSSQL | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、 NO_FIELD_OPTIONS （支持）| -| DB2 | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS （支持）| -| MAXDB | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS、NO_AUTO_CREATE_USER （支持）| -| MySQL323 | 等同于 NO_FIELD_OPTIONS、HIGH_NOT_PRECEDENCE (支持)| -| MYSQL40 | 等同于 NO_FIELD_OPTIONS、HIGH_NOT_PRECEDENCE （支持）| -| ANSI | 等同于 REAL_AS_FLOAT、PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE （支持）| -| TRADITIONAL | 等同于 STRICT_TRANS_TABLES、STRICT_ALL_TABLES、NO_ZERO_IN_DATE、NO_ZERO_DATE、ERROR_FOR_DIVISION_BY_ZERO、NO_AUTO_CREATE_USER(支持) | -| ORACLE | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS、NO_AUTO_CREATE_USER （支持）| diff --git a/v3.0/reference/sql/statements/add-column.md b/v3.0/reference/sql/statements/add-column.md deleted file mode 100644 index 3b11d23ce211..000000000000 --- a/v3.0/reference/sql/statements/add-column.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: ADD COLUMN -summary: TiDB 数据库中 ADD COLUMN 的使用概况。 -category: reference ---- - -# ADD COLUMN - -`ALTER TABLE.. ADD COLUMN` 语句用于在已有表中添加列。在 TiDB 中，`ADD COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (NULL); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+ -| id | -+----+ -| 1 | -+----+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD COLUMN c1 INT NOT NULL; -``` - -``` -Query OK, 0 rows affected (0.28 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 0 | -+----+----+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD c2 INT NOT NULL AFTER c1; -``` - -``` -Query OK, 0 rows affected (0.28 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+----+ -| id | c1 | c2 | -+----+----+----+ -| 1 | 0 | 0 | -+----+----+----+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持同时添加多列。 -* 不支持将新添加的列设为 `PRIMARY KEY`。 -* 不支持将新添加的列设为 `AUTO_INCREMENT`。 - -## 另请参阅 - -* [ADD INDEX](/v3.0/reference/sql/statements/add-index.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) diff --git a/v3.0/reference/sql/statements/add-index.md b/v3.0/reference/sql/statements/add-index.md deleted file mode 100644 index 89af862cec87..000000000000 --- a/v3.0/reference/sql/statements/add-index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: ADD INDEX -summary: TiDB 数据库中 ADD INDEX 的使用概况。 -category: reference ---- - -# ADD INDEX - -`ALTER TABLE.. ADD INDEX` 语句用于在已有表中添加一个索引。在 TiDB 中，`ADD INDEX` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引（类似于 MySQL 5.7）。 -* 目前尚不支持同时添加多个索引。 -* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/v3.0/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [CREATE INDEX](/v3.0/reference/sql/statements/create-index.md) -* [DROP INDEX](/v3.0/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v3.0/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/v3.0/reference/sql/statements/add-column.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [EXPLAIN](/v3.0/reference/sql/statements/explain.md) diff --git a/v3.0/reference/sql/statements/admin.md b/v3.0/reference/sql/statements/admin.md deleted file mode 100644 index 597f65fa13ba..000000000000 --- a/v3.0/reference/sql/statements/admin.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: ADMIN -category: reference -aliases: ['/docs-cn/sql/admin/'] ---- - -# ADMIN - -`ADMIN` 语句是 TiDB 扩展语法，用于查看 TiDB 自身的状态，并对 TiDB 中的表数据进行校验。示例如下。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL; -``` - -`ADMIN SHOW DDL` 用于查看当前正在执行的 DDL 作业。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOBS; -``` - -`ADMIN SHOW DDL JOBS` 用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CANCEL DDL JOBS job_id [, job_id] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CHECK TABLE tbl_name [, tbl_name] ...; -``` - -## 语句概览 - -**AdminStmt**： - -![AdminStmt](/media/sqlgram/AdminStmt.png) - -## 使用示例 - -{{< copyable "sql" >}} - -```sql -admin show ddl jobs; -``` - -``` -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | running | -| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | rollback done | -| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | synced | -| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | synced | -| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | synced | -| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | synced | -| 39 | test | t1 | add column | public | 32 | 37 | 0 | 2019-01-10 12:32:55.42 +0800 CST | synced | -| 38 | test | t1 | create table | public | 32 | 37 | 0 | 2019-01-10 12:32:41.956 +0800 CST | synced | -| 36 | test | | drop table | none | 32 | 34 | 0 | 2019-01-10 11:29:59.982 +0800 CST | synced | -| 35 | test | | create table | public | 32 | 34 | 0 | 2019-01-10 11:29:40.741 +0800 CST | synced | -| 33 | test | | create schema | public | 32 | 0 | 0 | 2019-01-10 11:29:22.813 +0800 CST | synced | -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -``` - -* `JOB_ID`：每个 DDL 操作对应一个 DDL 作业，`JOB_ID` 全局唯一。 -* `DB_NAME`：执行 DDL 操作的数据库的名称。 -* `TABLE_NAME`：执行 DDL 操作的表的名称。 -* `JOB_TYPE`：DDL 操作的类型。 -* `SCHEMA_STATE`：schema 的当前状态。如果 `JOB_TYPE` 是 `add index`，则为 index 的状态；如果是 `add column`，则为 column 的状态，如果是 `create table`，则为 table 的状态。常见的状态有以下几种： - * `none`：表示不存在。一般 `drop` 操作或者 `create` 操作失败回滚后，会变为 `none` 状态。 - * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在 [Online, Asynchronous Schema Change in F1](http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。 - * `public`：表示存在且可用。一般 `create table` 和 `add index/column` 等操作完成后，会变为 `public` 状态，表示新建的 table/column/index 可以正常读写了。 -* `SCHEMA_ID`：执行 DDL 操作的数据库的 ID。 -* `TABLE_ID`：执行 DDL 操作的表的 ID。 -* `ROW_COUNT`：执行 `add index` 操作时，当前已经添加完成的数据行数。 -* `START_TIME`：DDL 操作的开始时间。 -* `STATE`：DDL 操作的状态。常见的状态有以下几种： - * `none`：表示该操作任务已经进入 DDL 作业队列中，但尚未执行，因为还在排队等待前面的 DDL 作业完成。另一种原因可能是执行 `drop` 操作后，会变为 `none` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。 - * `running`：表示该操作正在执行。 - * `synced`：表示该操作已经执行成功，且所有 TiDB 实例都已经同步该状态。 - * `rollback done`：表示该操作执行失败，回滚完成。 - * `rollingback`：表示该操作执行失败，正在回滚。 - * `cancelling`：表示正在取消该操作。这个状态只有在用 `ADMIN CANCEL DDL JOBS` 命令取消 DDL 作业时才会出现。 - -- `ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...`：用于查看 `job_id` 对应的 DDL 任务的原始 SQL 语句。这个 `job_id` 只会搜索正在运行中的 DDL 作业以及 DDL 历史作业队列中最近的十条结果。 -- `ADMIN CANCEL DDL JOBS job_id [, job_id] ...`：用于取消当前正在运行的 DDL 作业，并返回对应作业是否取消成功。如果取消失败，会显示失败的具体原因。 - - > **注意：** - > - > - 只有该操作可以取消 DDL 作业，其他所有的操作和环境变更（例如机器重启、集群重启）都不会取消 DDL 作业。 - > - 该操作可以同时取消多个 DDL 作业。可以通过 `ADMIN SHOW DDL JOBS` 语句来获取 DDL 作业的 ID。 - > - 如果希望取消的作业已经完成，则取消操作将会失败。 - -- `ADMIN CHECK TABLE tbl_name [, tbl_name] ...`：用于对给定表中的所有数据和对应索引进行一致性校验，若通过校验，则返回空的查询结果；否则返回数据不一致的错误信息。 - -## MySQL 兼容性 - -ADMIN 语句是 TiDB 对于 MySQL 语法的扩展。 diff --git a/v3.0/reference/sql/statements/alter-database.md b/v3.0/reference/sql/statements/alter-database.md deleted file mode 100644 index ef84abb4b939..000000000000 --- a/v3.0/reference/sql/statements/alter-database.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: ALTER DATABASE -summary: TiDB 数据库中 ALTER DATABASE 的使用概况。 -category: reference ---- - -# ALTER DATABASE - -`ALTER DATABASE` 用于修改指定或当前数据库的默认字符集和排序规则。`ALTER SCHEMA` 跟 `ALTER DATABASE` 操作效果一样。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -ALTER {DATABASE | SCHEMA} [db_name] - alter_specification ... -alter_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -`alter_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/v3.0/reference/sql/character-set.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v3.0/reference/sql/statements/create-database.md) -* [SHOW DATABASES](/v3.0/reference/sql/statements/show-databases.md) diff --git a/v3.0/reference/sql/statements/alter-table.md b/v3.0/reference/sql/statements/alter-table.md deleted file mode 100644 index 183b8af613ec..000000000000 --- a/v3.0/reference/sql/statements/alter-table.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: ALTER TABLE -summary: TiDB 数据库中 ALTER TABLE 的使用概况。 -category: reference ---- - -# ALTER TABLE - -`ALTER TABLE` 语句用于对已有表进行修改，以符合新表结构。`ALTER TABLE` 语句可用于： - -* [`ADD`](/v3.0/reference/sql/statements/add-index.md)，[`DROP`](/v3.0/reference/sql/statements/drop-index.md)，或 [`RENAME`](/v3.0/reference/sql/statements/rename-index.md) 索引 -* [`ADD`](/v3.0/reference/sql/statements/add-column.md)，[`DROP`](/v3.0/reference/sql/statements/drop-column.md)，[`MODIFY`](/v3.0/reference/sql/statements/modify-column.md) 或 [`CHANGE`](/v3.0/reference/sql/statements/change-column.md) 列 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 支持除空间类型外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 - -## 另请参阅 - -* [ADD COLUMN](/v3.0/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v3.0/reference/sql/statements/drop-column.md) -* [ADD INDEX](/v3.0/reference/sql/statements/add-index.md) -* [DROP INDEX](/v3.0/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v3.0/reference/sql/statements/rename-index.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) diff --git a/v3.0/reference/sql/statements/alter-user.md b/v3.0/reference/sql/statements/alter-user.md deleted file mode 100644 index 95bba6f46e05..000000000000 --- a/v3.0/reference/sql/statements/alter-user.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: ALTER USER -summary: TiDB 数据库中 ALTER USER 的使用概况。 -category: reference ---- - -# ALTER USER - -`ALTER USER` 语句用于更改 TiDB 权限系统内的已有用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**AlterUserStmt:** - -![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'newuser'; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*5806E04BBEE79E1899964C6A04D68BCA69B1A879' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER USER 'newuser' IDENTIFIED BY 'newnewpassword'; -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'newuser'; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*FB8A1EA1353E8775CA836233E367FBDFCB37BE73' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，`ALTER` 语句用于更改属性，例如使密码失效。但 TiDB 尚不支持此功能。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/v3.0/reference/security/compatibility.md) -* [CREATE USER](/v3.0/reference/sql/statements/create-user.md) -* [DROP USER](/v3.0/reference/sql/statements/drop-user.md) -* [SHOW CREATE USER](/v3.0/reference/sql/statements/show-create-user.md) diff --git a/v3.0/reference/sql/statements/analyze-table.md b/v3.0/reference/sql/statements/analyze-table.md deleted file mode 100644 index 34ece7d231d3..000000000000 --- a/v3.0/reference/sql/statements/analyze-table.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: ANALYZE TABLE -summary: TiDB 数据库中 ANALYZE TABLE 的使用概况。 -category: reference ---- - -# ANALYZE TABLE - -`ANALYZE TABLE` 语句用于更新 TiDB 在表和索引上留下的统计信息。执行大批量更新或导入记录后，或查询执行计划不是最佳时，建议运行 `ANALYZE TABLE`。 - -当 TiDB 逐渐发现这些统计数据与预估不一致时，也会自动更新其统计数据。 - -## 语法图 - -**AnalyzeTableStmt:** - -![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -analyze table t1; -``` - -``` -Query OK, 0 rows affected (0.13 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+---------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------------------------------------------+ -| IndexReader_6 | 1.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 1.00 | cop | table:t1, index:c1, range:[3,3], keep order:false | -+-------------------+-------+------+---------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`ANALYZE TABLE` 在语法上与 MySQL 类似。但 `ANALYZE TABLE` 在 TiDB 上执行所需时间可能长得多，因为它的内部运行方式不同。 - -## 另请参阅 - -* [EXPLAIN](/v3.0/reference/sql/statements/explain.md) -* [EXPLAIN ANALYZE](/v3.0/reference/sql/statements/explain-analyze.md) diff --git a/v3.0/reference/sql/statements/begin.md b/v3.0/reference/sql/statements/begin.md deleted file mode 100644 index d9deeb04c177..000000000000 --- a/v3.0/reference/sql/statements/begin.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: BEGIN -summary: TiDB 数据库中 BEGIN 的使用概况。 -category: reference ---- - -# BEGIN - -`BEGIN` 语句用于在 TiDB 内启动一个新事务，类似于 `START TRANSACTION` 和 `SET autocommit=0` 语句。 - -在没有 `BEGIN` 语句的情况下，每个语句默认在各自的事务中自动提交，从而确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`BEGIN` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上[提交 issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v3.0/reference/sql/statements/commit.md) -* [ROLLBACK](/v3.0/reference/sql/statements/rollback.md) -* [START TRANSACTION](/v3.0/reference/sql/statements/start-transaction.md) diff --git a/v3.0/reference/sql/statements/change-column.md b/v3.0/reference/sql/statements/change-column.md deleted file mode 100644 index 1e014f598d4d..000000000000 --- a/v3.0/reference/sql/statements/change-column.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: CHANGE COLUMN -summary: TiDB 数据库中 CHANGE COLUMN 的使用概况。 -category: reference ---- - -# CHANGE COLUMN - -`ALTER TABLE.. CHANGE COLUMN` 语句用于在已有表上更改列，包括对列进行重命名，和将数据改为兼容类型。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col1 col2 INT; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col2 col3 BIGINT, ALGORITHM=INSTANT; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col3 INT; -``` - -``` -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col3 BLOB; -``` - -``` -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col4 BIGINT, CHANGE id id2 INT NOT NULL; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前尚不支持在单个 `ALTER TABLE` 语句中进行多个更改。 -* 仅支持特定的数据类型更改。例如，支持将 `INTEGER` 更改为 `BIGINT`，但不支持将 `BIGINT` 更改为 `INTEGER`。不支持从整数更改为字符串格式或 BLOB 类型。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/v3.0/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v3.0/reference/sql/statements/drop-column.md) -* [MODIFY COLUMN](/v3.0/reference/sql/statements/modify-column.md) diff --git a/v3.0/reference/sql/statements/commit.md b/v3.0/reference/sql/statements/commit.md deleted file mode 100644 index 2a401b8655ec..000000000000 --- a/v3.0/reference/sql/statements/commit.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: COMMIT -summary: TiDB 数据库中 COMMIT 的使用概况。 -category: reference ---- - -# COMMIT - -`COMMIT` 语句用于在 TiDB 服务器内部提交事务。 - -在不使用 `BEGIN` 或 `START TRANSACTION` 语句的情况下，TiDB 中每一个查询语句本身也会默认作为事务处理，自动提交，确保了与 MySQL 的兼容。 - -## 语法图 - -**CommitStmt:** - -![CommitStmt](/media/sqlgram/CommitStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，除了有多个 primary 的群组复制以外，`COMMIT` 语句通常不会导致错误。相比之下，TiDB 使用乐观并发控制，冲突可能导致 `COMMIT` 返回错误。 -* 默认情况下，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。 - -## 另请参阅 - -* [START TRANSACTION](/v3.0/reference/sql/statements/start-transaction.md) -* [ROLLBACK](/v3.0/reference/sql/statements/rollback.md) -* [BEGIN](/v3.0/reference/sql/statements/begin.md) -* [事务的惰性检查](/v3.0/reference/transactions/overview.md#事务的惰性检查) \ No newline at end of file diff --git a/v3.0/reference/sql/statements/create-database.md b/v3.0/reference/sql/statements/create-database.md deleted file mode 100644 index 624f3b0807da..000000000000 --- a/v3.0/reference/sql/statements/create-database.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: CREATE DATABASE -summary: TiDB 数据库中 CREATE DATABASE 的使用概况。 -category: reference ---- - -# CREATE DATABASE - -`CREATE DATABASE` 语句用于在 TiDB 上创建新数据库。按照 SQL 标准，“数据库” 一词在 MySQL 术语中最接近 “schema”。 - -## 语法图 - -**CreateDatabaseStmt:** - -![CreateDatabaseStmt](/media/sqlgram/CreateDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -**DatabaseOptionListOpt:** - -![DatabaseOptionListOpt](/media/sqlgram/DatabaseOptionListOpt.png) - -## 语法说明 - -`CREATE DATABASE` 用于创建数据库，并可以指定数据库的默认属性（如数据库默认字符集、排序规则）。`CREATE SCHEMA` 跟 `CREATE DATABASE` 操作效果一样。 - -{{< copyable "sql" >}} - -```sql -CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name - [create_specification] ... - -create_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -当创建已存在的数据库且不指定使用 `IF NOT EXISTS` 时会报错。 - -`create_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/v3.0/reference/sql/character-set.md)。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE mynewdatabase; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -USE mynewdatabase; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+-------------------------+ -| Tables_in_mynewdatabase | -+-------------------------+ -| t1 | -+-------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [USE](/v3.0/reference/sql/statements/use.md) -* [ALTER DATABASE](/v3.0/reference/sql/statements/alter-database.md) -* [DROP DATABASE](/v3.0/reference/sql/statements/drop-database.md) -* [SHOW DATABASES](/v3.0/reference/sql/statements/show-databases.md) diff --git a/v3.0/reference/sql/statements/create-index.md b/v3.0/reference/sql/statements/create-index.md deleted file mode 100644 index c5f4971982c5..000000000000 --- a/v3.0/reference/sql/statements/create-index.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: CREATE INDEX -summary: CREATE INDEX 在 TiDB 中的使用概况 -category: reference ---- - -# CREATE INDEX - -`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 `ALTER TABLE .. ADD INDEX`。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**CreateIndexStmt:** - -![CreateIndexStmt](/media/sqlgram/CreateIndexStmt.png) - -**CreateIndexStmtUnique:** - -![CreateIndexStmtUnique](/media/sqlgram/CreateIndexStmtUnique.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -**IndexTypeOpt:** - -![IndexTypeOpt](/media/sqlgram/IndexTypeOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**IndexColNameList:** - -![IndexColNameList](/media/sqlgram/IndexColNameList.png) - -**IndexOptionList:** - -![IndexOptionList](/media/sqlgram/IndexOptionList.png) - -**IndexOption:** - -![IndexOption](/media/sqlgram/IndexOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE UNIQUE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.31 sec) -``` - -## 相关 session 变量 - -和 `CREATE INDEX` 语句相关的全局变量有 `tidb_ddl_reorg_worker_cnt`，`tidb_ddl_reorg_batch_size` 和 `tidb_ddl_reorg_priority`，具体可以参考 [TiDB 特定系统变量](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_ddl_reorg_worker_cnt)。 - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引 （类似于 MySQL 5.7）。 -* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/v3.0/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [ADD INDEX](/v3.0/reference/sql/statements/add-index.md) -* [DROP INDEX](/v3.0/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v3.0/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/v3.0/reference/sql/statements/add-column.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [EXPLAIN](/v3.0/reference/sql/statements/explain.md) diff --git a/v3.0/reference/sql/statements/create-table-like.md b/v3.0/reference/sql/statements/create-table-like.md deleted file mode 100644 index a02d85b9b392..000000000000 --- a/v3.0/reference/sql/statements/create-table-like.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: CREATE TABLE LIKE -summary: TiDB 数据库中 CREATE TABLE LIKE 的使用概况。 -category: reference ---- - -# CREATE TABLE LIKE - -`CREATE TABLE LIKE` 语句用于复制已有表的定义，但不复制任何数据。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**LikeTableWithOrWithoutParen:** - -![LikeTableWithOrWithoutParen](/media/sqlgram/LikeTableWithOrWithoutParen.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.13 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE TABLE LIKE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) \ No newline at end of file diff --git a/v3.0/reference/sql/statements/create-table.md b/v3.0/reference/sql/statements/create-table.md deleted file mode 100644 index 225ece37e811..000000000000 --- a/v3.0/reference/sql/statements/create-table.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -title: CREATE TABLE -summary: TiDB 数据库中 CREATE TABLE 的使用概况 -category: reference -aliases: ['/docs-cn/sql/ddl/','/docs-cn/v3.0/reference/sql/statements/ddl/'] ---- - -# CREATE TABLE - -`CREATE TABLE` 语句用于在当前所选数据库中创建新表。另可参阅单独的 `CREATE TABLE LIKE` 文档。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**TableElementListOpt:** - -![TableElementListOpt](/media/sqlgram/TableElementListOpt.png) - -**TableElement:** - -![TableElement](/media/sqlgram/TableElement.png) - -**PartitionOpt:** - -![PartitionOpt](/media/sqlgram/PartitionOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**Type:** - -![Type](/media/sqlgram/Type.png) - -**ColumnOptionListOpt:** - -![ColumnOptionListOpt](/media/sqlgram/ColumnOptionListOpt.png) - -**TableOptionListOpt:** - -![TableOptionListOpt](/media/sqlgram/TableOptionListOpt.png) - -## 语法说明 - -`CREATE TABLE` 用于创建一个表。目前不支持临时表，不支持 `CHECK` 约束，不支持创建表的同时从其它表导入数据功能。在语法上也支持一些 `Partition_options`，但是并不完全，就不做列举了。 - -以下是 `CREATE TABLE` 相关的语法说明： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - (create_definition,...) - [table_options] -``` - -使用 `IF NOT EXIST` 时，即使创建的表已经存在，也不会报错，如果不指定时，则报错。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - { LIKE old_tbl_name | (LIKE old_tbl_name) } -``` - -使用 `LIKE` 基于一个表的定义创建一个空表，包括这个表中的列属性和索引属性。 - -```sql -create_definition: - col_name column_definition - | [CONSTRAINT [symbol]] PRIMARY KEY [index_type] (index_col_name,...) - [index_option] ... - | {INDEX|KEY} [index_name] [index_type] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY] - [index_name] [index_type] (index_col_name,...) - [index_option] ... - | {FULLTEXT} [INDEX|KEY] [index_name] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] FOREIGN KEY - [index_name] (index_col_name,...) reference_definition -``` - -`create_definition` 中 `FULLTEXT` 和 `FOREIGN KEY` 目前只是语法上支持。 - -```sql -column_definition: - data_type [NOT NULL | NULL] [DEFAULT default_value] - [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] - [COMMENT 'string'] - [reference_definition] - | data_type [GENERATED ALWAYS] AS (expression) - [VIRTUAL | STORED] [UNIQUE [KEY]] [COMMENT comment] - [NOT NULL | NULL] [[PRIMARY] KEY] - -data_type: - BIT[(length)] - | TINYINT[(length)] [UNSIGNED] [ZEROFILL] - | SMALLINT[(length)] [UNSIGNED] [ZEROFILL] - | MEDIUMINT[(length)] [UNSIGNED] [ZEROFILL] - | INT[(length)] [UNSIGNED] [ZEROFILL] - | INTEGER[(length)] [UNSIGNED] [ZEROFILL] - | BIGINT[(length)] [UNSIGNED] [ZEROFILL] - | REAL[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DOUBLE[(length,decimals)] [UNSIGNED] [ZEROFILL] - | FLOAT[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DECIMAL[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | NUMERIC[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | DATE - | TIME[(fsp)] - | TIMESTAMP[(fsp)] - | DATETIME[(fsp)] - | YEAR - | CHAR[(length)] [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | VARCHAR(length) [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | BINARY[(length)] - | VARBINARY(length) - | TINYBLOB - | BLOB - | MEDIUMBLOB - | LONGBLOB - | TINYTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | TEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | MEDIUMTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | LONGTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | ENUM(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | SET(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | JSON -``` - -`data_type` 请参考[数据类型](/v3.0/reference/sql/data-types/overview.md)章节。 - -```sql -index_col_name: - col_name [(length)] [ASC | DESC] -``` - -`index_col_name` 中 `[ASC | DESC]` 目前只是语法上支持。 - -```sql -index_type: - USING {BTREE | HASH} -``` - -`index_type` 目前只是语法上支持。 - -```sql -index_option: - KEY_BLOCK_SIZE [=] value - | index_type - | COMMENT 'string' -``` - -`index_option` 中 `KEY_BLOCK_SIZE` 目前只是语法上支持。 - -```sql -reference_definition: - REFERENCES tbl_name (index_col_name,...) - [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] - [ON DELETE reference_option] - [ON UPDATE reference_option] - -reference_option: - RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT -``` - -```sql -table_options: - table_option [[,] table_option] ... - -table_option: - AUTO_INCREMENT [=] value - | AVG_ROW_LENGTH [=] value - | SHARD_ROW_ID_BITS [=] value - | PRE_SPLIT_REGIONS [=] value - | [DEFAULT] CHARACTER SET [=] charset_name - | CHECKSUM [=] {0 | 1} - | [DEFAULT] COLLATE [=] collation_name - | COMMENT [=] 'string' - | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'} - | CONNECTION [=] 'connect_string' - | DELAY_KEY_WRITE [=] {0 | 1} - | ENGINE [=] engine_name - | KEY_BLOCK_SIZE [=] value - | MAX_ROWS [=] value - | MIN_ROWS [=] value - | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT} - | STATS_PERSISTENT [=] {DEFAULT|0|1} -``` - -`table_option` 目前支持的只有 `AUTO_INCREMENT`、`SHARD_ROW_ID_BITS`（详情介绍请参考 [TiDB 专用系统变量和语法](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）、`PRE_SPLIT_REGIONS`、`CHARACTER SET`、`COLLATE` 和 `COMMENT`，其它只是语法上支持。具体内容参考下表，各个子句之间用逗号隔开。 - -| 参数 |含义 |举例 | -|----------------|--------------------------------------|----------------------------| -|`AUTO_INCREMENT`|自增字段初始值 |`AUTO_INCREMENT` = 5| -|`SHARD_ROW_ID_BITS`|用来设置隐式 _tidb_rowid 的分片数量的 bit 位数 |`SHARD_ROW_ID_BITS` = 4| -|`PRE_SPLIT_REGIONS`|用来在建表时预先均匀切分 `2^(PRE_SPLIT_REGIONS)` 个 Region |`PRE_SPLIT_REGIONS` = 4| -|`CHARACTER SET` |指定该表所使用的字符集 | `CHARACTER SET` = 'utf8mb4'| -|`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| -|`COMMENT` |注释信息 | `COMMENT` = 'comment info'| - -`split-table` 配置项默认情况下会开启，在此配置项开启时，建表操作会为每个表建立单独的 Region。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESC t1; -``` - -``` -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 不支持 `CREATE TEMPORARY TABLE` 语法。 -* 支持除空间类型以外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* `KEY_BLOCK_SIZE` 和 `ENGINE` 属性可被解析，但会被忽略。 -* `index_col_name` 属性支持 length 选项，最大长度限制为 3072 字节。此长度限制不会更改，具体取决于存储引擎和建表时使用的字符集。 -* `index_col_name` 属性支持 `ASC` 和 `DESC` 的索引排序选项。 -* `COMMENT` 属性最多支持 1024 个字符，不支持 `WITH PARSER` 选项。 -* TiDB 在单个表中最多支持 512 列。InnoDB 中相应的数量限制为 1017，MySQL 中的硬限制为 4096。 - -## 另请参阅 - -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [CREATE TABLE LIKE](/v3.0/reference/sql/statements/create-table-like.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) diff --git a/v3.0/reference/sql/statements/create-user.md b/v3.0/reference/sql/statements/create-user.md deleted file mode 100644 index 80519fa86792..000000000000 --- a/v3.0/reference/sql/statements/create-user.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: CREATE USER -summary: TiDB 数据库中 CREATE USER 的使用概况。 -category: reference ---- - -# CREATE USER - -`CREATE USER` 语句用于创建带有指定密码的新用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**CreateUserStmt:** - -![CreateUserStmt](/media/sqlgram/CreateUserStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -**AuthOption:** - -![AuthOption](/media/sqlgram/AuthOption.png) - -**StringName:** - -![StringName](/media/sqlgram/StringName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser2'@'192.168.1.1' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -## MySQL 兼容性 - -* TiDB 尚不支持若干 `CREATE` 选项。这些选项可被解析，但会被忽略。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/v3.0/reference/security/compatibility.md) -* [DROP USER](/v3.0/reference/sql/statements/drop-user.md) -* [SHOW CREATE USER](/v3.0/reference/sql/statements/show-create-user.md) -* [ALTER USER](/v3.0/reference/sql/statements/alter-user.md) -* [Privilege Management](/v3.0/reference/security/privilege-system.md) diff --git a/v3.0/reference/sql/statements/create-view.md b/v3.0/reference/sql/statements/create-view.md deleted file mode 100644 index aab12300e93c..000000000000 --- a/v3.0/reference/sql/statements/create-view.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: CREATE VIEW -summary: TiDB 数据库中 CREATE VIEW 的使用概况。 -category: reference ---- - -# CREATE VIEW - -使用 `CREATE VIEW` 语句将 `SELECT` 语句保存为类似于表的可查询对象。TiDB 中的视图是非物化的，这意味着在查询视图时，TiDB 将在内部重写查询，以将视图定义与 SQL 查询结合起来。 - -## 语法图 - -**CreateViewStmt:** - -![CreateViewStmt](/media/sqlgram/CreateViewStmt.png) - -**OrReplace:** - -![OrReplace](/media/sqlgram/OrReplace.png) - -**ViewAlgorithm:** - -![ViewAlgorithm](/media/sqlgram/ViewAlgorithm.png) - -**ViewDefiner:** - -![ViewDefiner](/media/sqlgram/ViewDefiner.png) - -**ViewSQLSecurity:** - -![ViewSQLSecurity](/media/sqlgram/ViewSQLSecurity.png) - -**ViewName:** - -![ViewName](/media/sqlgram/ViewName.png) - -**ViewFieldList:** - -![ViewFieldList](/media/sqlgram/ViewFieldList.png) - -**ViewCheckOption:** - -![ViewCheckOption](/media/sqlgram/ViewCheckOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (6); -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -| 6 | 6 | -+----+----+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO v1 (c1) VALUES (7); -``` - -``` -ERROR 1105 (HY000): insert into view v1 is not supported now. -``` - -## MySQL 兼容性 - -* 目前 TiDB 中的视图不可插入且不可更新。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) diff --git a/v3.0/reference/sql/statements/deallocate.md b/v3.0/reference/sql/statements/deallocate.md deleted file mode 100644 index 2bc660603b8c..000000000000 --- a/v3.0/reference/sql/statements/deallocate.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: DEALLOCATE -summary: TiDB 数据库中 DEALLOCATE 的使用概况。 -category: reference ---- - -# DEALLOCATE - -`DEALLOCATE` 语句用于为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**DeallocateStmt:** - -![DeallocateStmt](/media/sqlgram/DeallocateStmt.png) - -**DeallocateSym:** - -![DeallocateSym](/media/sqlgram/DeallocateSym.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`DEALLOCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/v3.0/reference/sql/statements/prepare.md) -* [EXECUTE](/v3.0/reference/sql/statements/execute.md) diff --git a/v3.0/reference/sql/statements/delete.md b/v3.0/reference/sql/statements/delete.md deleted file mode 100644 index 098407bfd6e4..000000000000 --- a/v3.0/reference/sql/statements/delete.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: DELETE -summary: TiDB 数据库中 DELETE 的使用概况。 -category: reference ---- - -# DELETE - -`DELETE` 语句用于从指定的表中删除行。 - -## 语法图 - -**DeleteFromStmt:** - -![DeleteFromStmt](/media/sqlgram/DeleteFromStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DELETE FROM t1 WHERE id = 4; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 5 | 5 | -+----+----+ -4 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DELETE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v3.0/reference/sql/statements/insert.md) -* [SELECT](/v3.0/reference/sql/statements/select.md) -* [UPDATE](/v3.0/reference/sql/statements/update.md) -* [REPLACE](/v3.0/reference/sql/statements/replace.md) diff --git a/v3.0/reference/sql/statements/desc.md b/v3.0/reference/sql/statements/desc.md deleted file mode 100644 index 1c5ca1ca8ba2..000000000000 --- a/v3.0/reference/sql/statements/desc.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESC -summary: TiDB 数据库中 DESC 的使用概况。 -category: reference ---- - -# DESC - -`DESC` 语句是 [`EXPLAIN`](/v3.0/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v3.0/reference/sql/statements/describe.md b/v3.0/reference/sql/statements/describe.md deleted file mode 100644 index 139e283c840c..000000000000 --- a/v3.0/reference/sql/statements/describe.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESCRIBE -summary: TiDB 数据库中 DESCRIBE 的使用概况。 -category: reference ---- - -# DESCRIBE - -`DESCRIBE` 语句为 [`EXPLAIN`](/v3.0/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v3.0/reference/sql/statements/do.md b/v3.0/reference/sql/statements/do.md deleted file mode 100644 index 1b2c30cbe5c8..000000000000 --- a/v3.0/reference/sql/statements/do.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: DO | TiDB SQL Statement Reference -summary: TiDB 数据库中 DO 的使用概况。 -category: reference ---- - -# DO - -`DO` 语句用于执行表达式，而不返回结果。在 MySQL 中，`DO` 的一个常见用例是执行存储的程序，而无需处理结果。但是 TiDB 不提供存储例程，因此该功能的使用较为受限。 - -## 语法图 - -**DoStmt:** - -![DoStmt](/media/sqlgram/DoStmt.png) - -**ExpressionList:** - -![ExpressionList](/media/sqlgram/ExpressionList.png) - -**Expression:** - -![Expression](/media/sqlgram/Expression.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SELECT SLEEP(5); -``` - -``` -+----------+ -| SLEEP(5) | -+----------+ -| 0 | -+----------+ -1 row in set (5.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DO SLEEP(5); -``` - -``` -Query OK, 0 rows affected (5.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DO SLEEP(1), SLEEP(1.5); -``` - -``` -Query OK, 0 rows affected (2.50 sec) -``` - -## MySQL 兼容性 - -`DO` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SELECT](/v3.0/reference/sql/statements/select.md) diff --git a/v3.0/reference/sql/statements/drop-column.md b/v3.0/reference/sql/statements/drop-column.md deleted file mode 100644 index fa604bfe089f..000000000000 --- a/v3.0/reference/sql/statements/drop-column.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: DROP COLUMN -summary: TiDB 数据库中 DROP COLUMN 的使用概况。 -category: reference ---- - -# DROP COLUMN - -`DROP COLUMN` 语句用于从指定的表中删除列。在 TiDB 中，`COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, col1 INT NOT NULL, col2 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1,col2) VALUES (1,1),(2,2),(3,3),(4,4),(5,5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP COLUMN col1, DROP COLUMN col2; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP COLUMN col1; -``` - -``` -Query OK, 0 rows affected (0.27 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+ -| id | col2 | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持使用相同语句删除多个列。 - -## 另请参阅 - -* [ADD COLUMN](/v3.0/reference/sql/statements/add-column.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) diff --git a/v3.0/reference/sql/statements/drop-database.md b/v3.0/reference/sql/statements/drop-database.md deleted file mode 100644 index 6f395e74f8be..000000000000 --- a/v3.0/reference/sql/statements/drop-database.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: DROP DATABASE -summary: TiDB 数据库中 DROP DATABASE 的使用概况。 -category: reference ---- - -# DROP DATABASE - -`DROP DATABASE` 语句用于永久删除指定的数据库 schema，以及删除所有在 schema 中创建的表和视图。与被删数据库相关联的用户权限不受影响。 - -## 语法图 - -**DropDatabaseStmt:** - -![DropDatabaseStmt](/media/sqlgram/DropDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfExists:** - -![IfExists](/media/sqlgram/IfExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP DATABASE test; -``` - -``` -Query OK, 0 rows affected (0.25 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -+--------------------+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v3.0/reference/sql/statements/create-database.md) -* [ALTER DATABASE](/v3.0/reference/sql/statements/alter-database.md) diff --git a/v3.0/reference/sql/statements/drop-index.md b/v3.0/reference/sql/statements/drop-index.md deleted file mode 100644 index 166ef9144b70..000000000000 --- a/v3.0/reference/sql/statements/drop-index.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: DROP INDEX -summary: TiDB 数据库中 DROP INDEX 的使用概况。 -category: reference ---- - -# DROP INDEX - -`DROP INDEX` 语句用于从指定的表中删除索引，并在 TiKV 中将空间标记为释放。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -## MySQL 兼容性 - -* 默认不支持删除 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/v3.0/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [SHOW INDEX](/v3.0/reference/sql/statements/show-index.md) -* [CREATE INDEX](/v3.0/reference/sql/statements/create-index.md) -* [ADD INDEX](/v3.0/reference/sql/statements/add-index.md) -* [RENAME INDEX](/v3.0/reference/sql/statements/rename-index.md) diff --git a/v3.0/reference/sql/statements/drop-table.md b/v3.0/reference/sql/statements/drop-table.md deleted file mode 100644 index 0ca79e3a4447..000000000000 --- a/v3.0/reference/sql/statements/drop-table.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: DROP TABLE -summary: TiDB 数据库中 DROP TABLE 的使用概况。 -category: reference ---- - -# DROP TABLE - -`DROP TABLE` 语句用于从当前所选的数据库中删除表。如果表不存在则会报错，除非使用 `IF EXISTS` 修饰符。 - -按照设计，`DROP TABLE` 也会删除视图，因为视图与表共享相同的命名空间。 - -## 语法图 - -**DropTableStmt:** - -![DropTableStmt](/media/sqlgram/DropTableStmt.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE t1; -``` - -``` -Query OK, 0 rows affected (0.22 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE table_not_exists; -``` - -``` -ERROR 1051 (42S02): Unknown table 'test.table_not_exists' -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS table_not_exists; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT 1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE v1; -``` - -``` -Query OK, 0 rows affected (0.23 sec) -``` - -## MySQL 兼容性 - -* 在尝试删除不存在的表时，使用 `IF EXISTS` 删除表不会返回警告。[Issue #7867](https://github.com/pingcap/tidb/issues/7867) - -## 另请参阅 - -* [DROP VIEW](/v3.0/reference/sql/statements/drop-view.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [SHOW TABLES](/v3.0/reference/sql/statements/show-tables.md) diff --git a/v3.0/reference/sql/statements/drop-user.md b/v3.0/reference/sql/statements/drop-user.md deleted file mode 100644 index 197e93af832f..000000000000 --- a/v3.0/reference/sql/statements/drop-user.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: DROP USER -summary: TiDB 数据库中 DROP USER 的使用概况。 -category: reference ---- - -# DROP USER - -`DROP USER` 语句用于从 TiDB 系统数据库中删除用户。如果用户不存在，使用关键词 `IF EXISTS` 可避免出现警告。 - -## 语法图 - -**DropUserStmt:** - -![DropUserStmt](/media/sqlgram/DropUserStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -DROP USER idontexist; -``` - -``` -ERROR 1396 (HY000): Operation DROP USER failed for idontexist@% -``` - -{{< copyable "sql" >}} - -```sql -DROP USER IF EXISTS idontexist; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REVOKE ALL ON test.* FROM 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP USER newuser; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR newuser; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -* 在 TiDB 中删除不存在的用户时，使用 `IF EXISTS` 可避免出现警告。[Issue #10196](https://github.com/pingcap/tidb/issues/10196)。 - -## 另请参阅 - -* [CREATE USER](/v3.0/reference/sql/statements/create-user.md) -* [ALTER USER](/v3.0/reference/sql/statements/alter-user.md) -* [SHOW CREATE USER](/v3.0/reference/sql/statements/show-create-user.md) -* [Privilege Management](/v3.0/reference/security/privilege-system.md) diff --git a/v3.0/reference/sql/statements/drop-view.md b/v3.0/reference/sql/statements/drop-view.md deleted file mode 100644 index d3ad88281a40..000000000000 --- a/v3.0/reference/sql/statements/drop-view.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: DROP VIEW -summary: TiDB 数据库中 DROP VIEW 的使用概况。 -category: reference ---- - -# DROP VIEW - -`DROP VIEW` 语句用于从当前所选定的数据库中删除视图对象。视图所引用的基表不受影响。 - -## 语法图 - -**DropViewStmt:** - -![DropViewStmt](/media/sqlgram/DropViewStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP VIEW v1; -``` - -``` -Query OK, 0 rows affected (0.23 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP VIEW` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## See also - -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [CREATE VIEW](/v3.0/reference/sql/statements/create-view.md) diff --git a/v3.0/reference/sql/statements/execute.md b/v3.0/reference/sql/statements/execute.md deleted file mode 100644 index 1a7c28f166ba..000000000000 --- a/v3.0/reference/sql/statements/execute.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: EXECUTE -summary: TiDB 数据库中 EXECUTE 的使用概况。 -category: reference ---- - -# EXECUTE - -`EXECUTE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**ExecuteStmt:** - -![ExecuteStmt](/media/sqlgram/ExecuteStmt.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`EXECUTE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/v3.0/reference/sql/statements/prepare.md) -* [DEALLOCATE](/v3.0/reference/sql/statements/deallocate.md) diff --git a/v3.0/reference/sql/statements/explain-analyze.md b/v3.0/reference/sql/statements/explain-analyze.md deleted file mode 100644 index 83a213d36ab2..000000000000 --- a/v3.0/reference/sql/statements/explain-analyze.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: EXPLAIN ANALYZE -summary: TiDB 数据库中 EXPLAIN ANALYZE 的使用概况。 -category: reference ---- - -# EXPLAIN ANALYZE - -`EXPLAIN ANALYZE` 语句的工作方式类似于 `EXPLAIN`，主要区别在于前者实际上会执行语句。这样可以将查询计划中的估计值与执行时所遇到的实际值进行比较。如果估计值与实际值显著不同，那么应考虑在受影响的表上运行 `ANALYZE TABLE`。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN ANALYZE SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+---------------------------+ -| id | count | task | operator info | execution info | -+-------------+-------+------+--------------------+---------------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | time:0ns, loops:0, rows:0 | -+-------------+-------+------+--------------------+---------------------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN ANALYZE SELECT * FROM t1; -``` - -``` -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| id | count | task | operator info | execution info | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| TableReader_5 | 10000.00 | root | data:TableScan_4 | time:931.759µs, loops:2, rows:3 | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | time:0s, loops:0, rows:3 | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -该语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/v3.0/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN](/v3.0/reference/sql/statements/explain.md) -* [ANALYZE TABLE](/v3.0/reference/sql/statements/analyze-table.md) -* [TRACE](/v3.0/reference/sql/statements/trace.md) diff --git a/v3.0/reference/sql/statements/explain.md b/v3.0/reference/sql/statements/explain.md deleted file mode 100644 index 374291775041..000000000000 --- a/v3.0/reference/sql/statements/explain.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: EXPLAIN -summary: TiDB 数据库中 EXPLAIN 的使用概况。 -category: reference -aliases: ['/docs-cn/sql/util/'] ---- - -# EXPLAIN - -`EXPLAIN` 语句仅用于显示查询的执行计划，而不执行查询。`EXPLAIN ANALYZE` 可执行查询，补充 `EXPLAIN` 语句。如果 `EXPLAIN` 的输出与预期结果不匹配，可考虑在查询的每个表上执行 `ANALYZE TABLE`。 - -语句 `DESC` 和 `DESCRIBE` 是 `EXPLAIN` 的别名。`EXPLAIN ` 的替代用法记录在 [`SHOW [FULL] COLUMNS FROM`](/v3.0/reference/sql/statements/show-columns-from.md) 下。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT 1; -``` - -``` -+-------------------+-------+------+---------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------+ -| Projection_3 | 1.00 | root | 1 | -| └─TableDual_4 | 1.00 | root | rows:1 | -+-------------------+-------+------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESC SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESCRIBE SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN INSERT INTO t1 (c1) VALUES (4); -``` - -``` -ERROR 1105 (HY000): Unsupported type *core.Insert -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN UPDATE t1 SET c1=5 WHERE c1=3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN DELETE FROM t1 WHERE c1=3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -如果未指定 `FORMAT`，或未指定 `FORMAT ="row"`，那么 `EXPLAIN` 语句将以表格格式输出结果。更多信息，可参阅 [Understand the Query Execution Plan](https://pingcap.com/docs/v3.0/reference/performance/understanding-the-query-execution-plan/)。 - -除 MySQL 标准结果格式外，TiDB 还支持 DotGraph。需按照下列所示指定 `FORMAT ="dot"`： - -{{< copyable "sql" >}} - -```sql -create table t(a bigint, b bigint); -desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10; -``` - -```+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dot contents | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| -digraph HashRightJoin_7 { -subgraph cluster7{ -node [style=filled, color=lightgrey] -color=black -label = "root" -"HashRightJoin_7" -> "TableReader_10" -"HashRightJoin_7" -> "TableReader_12" -} -subgraph cluster9{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"Selection_9" -> "TableScan_8" -} -subgraph cluster11{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"TableScan_11" -} -"TableReader_10" -> "Selection_9" -"TableReader_12" -> "TableScan_11" -} - | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -如果你的计算机上安装了 `dot` 程序（在 `graphviz` 包中），可使用以下方法生成 PNG 文件： - -{{< copyable "shell-regular" >}} - -```bash -dot xx.dot -T png -O -``` - -The `xx.dot` is the result returned by the above statement. - -如果你的计算机上未安装 `dot` 程序，可将结果复制到 [本网站](http://www.webgraphviz.com/) 以获取树形图： - -![Explain Dot](/media/explain_dot.png) - -## MySQL 兼容性 - -* `EXPLAIN` 的格式和 TiDB 中潜在的执行计划都与 MySQL 有很大不同。 -* TiDB 不像 MySQL 那样支持 `EXPLAIN FORMAT = JSON`。 -* TiDB 目前不支持插入语句的 `EXPLAIN`。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/v3.0/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN ANALYZE](/v3.0/reference/sql/statements/explain-analyze.md) -* [ANALYZE TABLE](/v3.0/reference/sql/statements/analyze-table.md) -* [TRACE](/v3.0/reference/sql/statements/trace.md) diff --git a/v3.0/reference/sql/statements/flush-privileges.md b/v3.0/reference/sql/statements/flush-privileges.md deleted file mode 100644 index fa67b9480b39..000000000000 --- a/v3.0/reference/sql/statements/flush-privileges.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: FLUSH PRIVILEGES -summary: TiDB 数据库中 FLUSH PRIVILEGES 的使用概况。 -category: reference ---- - -# FLUSH PRIVILEGES - -`FLUSH PRIVILEGES` 语句可触发 TiDB 从权限表中重新加载权限的内存副本。在对如 `mysql.user` 一类的表进行手动编辑后，应当执行 `FLUSH PRIVILEGES`。使用如 `GRANT` 或 `REVOKE` 一类的权限语句后，不需要执行 `FLUSH PRIVILEGES` 语句。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`FLUSH PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [GRANT ](/v3.0/reference/sql/statements/grant-privileges.md) -* [REVOKE](/v3.0/reference/sql/statements/revoke-privileges.md) -* [Privilege Management](/v3.0/reference/security/privilege-system.md) diff --git a/v3.0/reference/sql/statements/flush-status.md b/v3.0/reference/sql/statements/flush-status.md deleted file mode 100644 index bc61cde08594..000000000000 --- a/v3.0/reference/sql/statements/flush-status.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: FLUSH STATUS -summary: TiDB 数据库中 FLUSH STATUS 的使用概况。 -category: reference ---- - -# FLUSH STATUS - -`FLUSH STATUS` 语句用于提供 MySQL 兼容性，但在 TiDB 上并无作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -show global status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -flush status; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| ddl_schema_version | 141 | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `FLUSH STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] STATUS](/v3.0/reference/sql/statements/show-status.md) diff --git a/v3.0/reference/sql/statements/flush-tables.md b/v3.0/reference/sql/statements/flush-tables.md deleted file mode 100644 index 9a7fff17fe46..000000000000 --- a/v3.0/reference/sql/statements/flush-tables.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: FLUSH TABLES -summary: TiDB 数据库中 FLUSH TABLES 的使用概况。 -category: reference ---- - -# FLUSH TABLES - -`FLUSH TABLES` 语句用于提供 MySQL 兼容性，但在 TiDB 中并无有效用途。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameListOpt:** - -![TableNameListOpt](/media/sqlgram/TableNameListOpt.png) - -**WithReadLockOpt:** - -![WithReadLockOpt](/media/sqlgram/WithReadLockOpt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -FLUSH TABLES; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -FLUSH TABLES WITH READ LOCK; -``` - -``` -ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported. Please use @@tidb_snapshot -``` - -## MySQL 兼容性 - -* TiDB 没有 MySQL 中的表缓存这一概念。所以，`FLUSH TABLES` 因 MySQL 兼容性会在 TiDB 中解析出但会被忽略掉。 -* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads] 来实现锁表。 - -## 另请参阅 - -* [Read historical data](/v3.0/how-to/get-started/read-historical-data.md) diff --git a/v3.0/reference/sql/statements/grant-privileges.md b/v3.0/reference/sql/statements/grant-privileges.md deleted file mode 100644 index e66574551b25..000000000000 --- a/v3.0/reference/sql/statements/grant-privileges.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: GRANT -summary: TiDB 数据库中 GRANT 的使用概况。 -category: reference ---- - -# GRANT - -`GRANT ` 语句用于为 TiDB 中已存在的用户分配权限。TiDB 中的权限系统同 MySQL 一样，都基于数据库/表模式来分配凭据。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 与 MySQL 类似，`USAGE` 权限表示登录 TiDB 服务器的能力。 -* 目前不支持列级权限。 -* 与 MySQL 类似，不存在 `NO_AUTO_CREATE_USER` sql 模式时，`GRANT` 语句将在用户不存在时自动创建一个空密码的新用户。删除此 sql-mode（默认情况下已启用）会带来安全风险。 - -## 另请参阅 - -* [REVOKE ](/v3.0/reference/sql/statements/revoke-privileges.md) -* [SHOW GRANTS](/v3.0/reference/sql/statements/show-grants.md) -* [Privilege Management](/v3.0/reference/security/privilege-system.md) diff --git a/v3.0/reference/sql/statements/insert.md b/v3.0/reference/sql/statements/insert.md deleted file mode 100644 index 336d9d14fd48..000000000000 --- a/v3.0/reference/sql/statements/insert.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: INSERT -summary: TiDB 数据库中 INSERT 的使用概况。 -category: reference ---- - -# INSERT - -使用 `INSERT` 语句在表中插入新行。 - -## 语法图 - -**InsertIntoStmt:** - -![InsertIntoStmt](/media/sqlgram/InsertIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IgnoreOptional:** - -![IgnoreOptional](/media/sqlgram/IgnoreOptional.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (a) VALUES (1); -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t2 SELECT * FROM t1; -``` - -``` -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t2 VALUES (2),(3),(4); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -| 2 | -| 3 | -| 4 | -+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`INSERT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/v3.0/reference/sql/statements/delete.md) -* [SELECT](/v3.0/reference/sql/statements/select.md) -* [UPDATE](/v3.0/reference/sql/statements/update.md) -* [REPLACE](/v3.0/reference/sql/statements/replace.md) diff --git a/v3.0/reference/sql/statements/kill.md b/v3.0/reference/sql/statements/kill.md deleted file mode 100644 index b2d16985d017..000000000000 --- a/v3.0/reference/sql/statements/kill.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: KILL [TIDB] -summary: TiDB 数据库中 KILL [TIDB] 的使用概况。 -category: reference ---- - -# KILL [TIDB] - -`KILL TIDB` 语句用于终止 TiDB 中的连接。 - -按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。 - -## 语法图 - -**KillStmt:** - -![KillStmt](/media/sqlgram/KillStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW PROCESSLIST; -``` - -``` -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -KILL TIDB 2; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -* `KILL TIDB` 语句是 TiDB 的扩展语法。如果正尝试终止的会话位于同一个 TiDB 服务器上，可在配置文件里设置 [`compatible-kill-query = true`](/v3.0/reference/configuration/tidb-server/configuration-file.md#compatible-kill-query)。 - -## 另请参阅 - -* [SHOW \[FULL\] PROCESSLIST](/v3.0/reference/sql/statements/show-processlist.md) diff --git a/v3.0/reference/sql/statements/load-data.md b/v3.0/reference/sql/statements/load-data.md deleted file mode 100644 index ab249aa40db4..000000000000 --- a/v3.0/reference/sql/statements/load-data.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: LOAD DATA -summary: TiDB 数据库中 LOAD DATA 的使用概况。 -category: reference ---- - -# LOAD DATA - -`LOAD DATA` 语句用于将数据批量加载到 TiDB 表中。 - -## 语法图 - -**LoadDataStmt:** - -![LoadDataStmt](/media/sqlgram/LoadDataStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE trips ( - -> trip_id bigint NOT NULL PRIMARY KEY AUTO_INCREMENT, - -> duration integer not null, - -> start_date datetime, - -> end_date datetime, - -> start_station_number integer, - -> start_station varchar(255), - -> end_station_number integer, - -> end_station varchar(255), - -> bike_number varchar(255), - -> member_type varchar(255) - -> ); -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); -``` - -``` -Query OK, 815264 rows affected (39.63 sec) -Records: 815264 Deleted: 0 Skipped: 0 Warnings: 0 -``` - -## MySQL 兼容性 - -* 默认情况下，TiDB 每 20,000 行会进行一次提交。这类似于 MySQL NDB Cluster，但并非 InnoDB 存储引擎的默认配置。 - -> **注意：** -> -> 这种拆分事务提交的方式是以打破事务的原子性和隔离性为代价的，使用该特性时，使用者需要保证没有其他对正在处理的表的**任何**操作，并且在出现报错时，需要及时**人工介入，检查数据的一致性和完整性**。因此，不建议在生产环境中使用。 - -## 另请参阅 - -* [INSERT](/v3.0/reference/sql/statements/insert.md) -* [乐观事务模型](/v3.0/reference/transactions/transaction-optimistic.md) diff --git a/v3.0/reference/sql/statements/modify-column.md b/v3.0/reference/sql/statements/modify-column.md deleted file mode 100644 index 89c3368dd8d7..000000000000 --- a/v3.0/reference/sql/statements/modify-column.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: MODIFY COLUMN -summary: TiDB 数据库中 MODIFY COLUMN 的使用概况。 -category: reference ---- - -# MODIFY COLUMN - -`ALTER TABLE .. MODIFY COLUMN` 语句用于修改已有表上的列，包括列的数据类型和属性。若要同时重命名，可改用 [`CHANGE COLUMN`](/v3.0/reference/sql/statements/change-column.md) 语句。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BIGINT; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `col1` bigint(20) DEFAULT NULL, - PRIMARY KEY (`id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=30001 -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 INT; -``` - -``` -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BLOB; -``` - -``` -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BIGINT, MODIFY id BIGINT NOT NULL; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前不支持使用单个 `ALTER TABLE` 语句进行多个修改。 -* 仅支持特定类型的数据类型更改。例如，支持将 `INTEGER` 改为 `BIGINT`，但不支持将 `BIGINT` 改为 `INTEGER`。不支持将整数改为字符串格式或 BLOB 格式。 -* 不支持修改 decimal 类型的精度。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/v3.0/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v3.0/reference/sql/statements/drop-column.md) -* [CHANGE COLUMN](/v3.0/reference/sql/statements/change-column.md) diff --git a/v3.0/reference/sql/statements/prepare.md b/v3.0/reference/sql/statements/prepare.md deleted file mode 100644 index bf5cade9a22a..000000000000 --- a/v3.0/reference/sql/statements/prepare.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: PREPARE -summary: TiDB 数据库中 PREPARE 的使用概况。 -category: reference -aliases: ['/docs-cn/sql/prepare/'] ---- - -# PREPARE - -`PREPARE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**PreparedStmt:** - -![PreparedStmt](/media/sqlgram/PreparedStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`PREPARE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [EXECUTE](/v3.0/reference/sql/statements/execute.md) -* [DEALLOCATE](/v3.0/reference/sql/statements/deallocate.md) diff --git a/v3.0/reference/sql/statements/recover-table.md b/v3.0/reference/sql/statements/recover-table.md deleted file mode 100644 index a220615f99b3..000000000000 --- a/v3.0/reference/sql/statements/recover-table.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: RECOVER TABLE -category: reference ---- - -# RECOVER TABLE - -`RECOVER TABLE` 的功能是恢复被删除的表及其数据。在 `DROP TABLE` 后，在 GC life time 时间内，可以用 `RECOVER TABLE` 语句恢复被删除的表以及其数据。 - -## 语法 - -{{< copyable "sql" >}} - -```sql -RECOVER TABLE table_name -``` - -{{< copyable "sql" >}} - -```sql -RECOVER TABLE BY JOB ddl_job_id -``` - -## 注意事项 - -如果删除表后并过了 GC lifetime，就不能再用 `RECOVER TABLE` 来恢复被删除的表了，执行 `RECOVER TABLE` 语句会返回类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -对于 3.0.0 及之后的 TiDB 版本，不推荐在使用 TiDB Binlog 的情况下使用 `RECOVER TABLE` 功能。 - -TiDB Binlog 在 3.0.1 支持 `RECOVER TABLE` 后，可在下面的情况下使用 `RECOVER TABLE`： - -* 3.0.1+ 版本的 TiDB Binlog -* 主从集群都使用 TiDB 3.0 -* 从集群 GC lifetime 一定要长于主集群（不过由于上下游同步的延迟，可能也会造成下游 recover 失败） - -### TiDB Binlog 同步错误处理 - -当使用 TiDB Binlog 同步工具时，上游 TiDB 使用 `RECOVER TABLE` 后，TiDB Binlog 可能会因为下面几个原因造成同步中断： - -* 下游数据库不支持 `RECOVER TABLE` 语句。类似错误：`check the manual that corresponds to your MySQL server version for the right syntax to use near 'RECOVER TABLE table_name'`。 - -* 上下游数据库的 GC lifetime 不一样。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -* 上下游数据库的同步延迟。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -只能通过重新[全量导入被删除的表](/v3.0/reference/tools/user-guide.md#tidb-集群数据的全量备份及恢复)来恢复 TiDB Binlog 的数据同步。 - -## 示例 - -- 根据表名恢复被删除的表。 - - {{< copyable "sql" >}} - - ```sql - DROP TABLE t; - ``` - - {{< copyable "sql" >}} - - ```sql - RECOVER TABLE t; - ``` - - 根据表名恢复被删除的表需满足以下条件： - - - 最近 DDL JOB 历史中找到的第一个 `DROP TABLE` 操作，且 - - `DROP TABLE` 所删除的表的名称与 `RECOVER TABLE` 语句指定表名相同 - -- 根据删除表时的 DDL JOB ID 恢复被删除的表。 - - 如果第一次删除表 t 后，又新建了一个表 t，然后又把新建的表 t 删除了，此时如果想恢复最开始删除的表 t, 就需要用到指定 DDL JOB ID 的语法了。 - - {{< copyable "sql" >}} - - ```sql - DROP TABLE t; - ``` - - {{< copyable "sql" >}} - - ```sql - ADMIN SHOW DDL JOBS 1; - ``` - - 上面这个语句用来查找删除表 t 时的 DDL JOB ID，这里是 53： - - ``` - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - | JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - | 53 | test | | drop table | none | 1 | 41 | 0 | 2019-07-10 13:23:18.277 +0800 CST | synced | - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - ``` - - {{< copyable "sql" >}} - - ```sql - RECOVER TABLE BY JOB 53; - ``` - - 根据删除表时的 DDL JOB ID 恢复被删除的表，会直接用 DDL JOB ID 找到被删除表进行恢复。如果指定的 DDL JOB ID 的 DDL JOB 不是 `DROP TABLE` 类型，会报错。 - -## 原理 - -TiDB 在删除表时，实际上只删除了表的元信息，并将需要删除的表数据（行数据和索引数据）写一条数据到 `mysql.gc_delete_range` 表。TiDB 后台的 GC Worker 会定期从 `mysql.gc_delete_range` 表中取出超过 GC lifetime 相关范围的 key 进行删除。 - -所以，RECOVER TABLE 只需要在 GC Worker 还没删除表数据前，恢复表的元信息并删除 `mysql.gc_delete_range` 表中相应的行记录就可以了。恢复表的元信息可以用 TiDB 的快照读实现。具体的快照读内容可以参考[读取历史数据](/v3.0/how-to/get-started/read-historical-data.md)文档。 - -TiDB 中表的恢复是通过快照读获取表的元信息后，再走一次类似于 `CREATE TABLE` 的建表流程，所以 `RECOVER TABLE` 实际上也是一种 DDL。 diff --git a/v3.0/reference/sql/statements/rename-index.md b/v3.0/reference/sql/statements/rename-index.md deleted file mode 100644 index 26e0c6cddc34..000000000000 --- a/v3.0/reference/sql/statements/rename-index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: RENAME INDEX -summary: TiDB 数据库中 RENAME INDEX 的使用概况。 -category: reference ---- - -# RENAME INDEX - -`ALTER TABLE .. RENAME INDEX` 语句用于对已有索引进行重命名。这在 TiDB 中是即时操作的，仅需更改元数据。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL, INDEX col1 (c1)); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `col1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 RENAME INDEX col1 TO c1; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `c1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME INDEX` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [CREATE INDEX](/v3.0/reference/sql/statements/create-index.md) -* [DROP INDEX](/v3.0/reference/sql/statements/drop-index.md) -* [SHOW INDEX](/v3.0/reference/sql/statements/show-index.md) diff --git a/v3.0/reference/sql/statements/rename-table.md b/v3.0/reference/sql/statements/rename-table.md deleted file mode 100644 index 54096a94a37c..000000000000 --- a/v3.0/reference/sql/statements/rename-table.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: RENAME TABLE -summary: TiDB 数据库中 RENAME TABLE 的使用概况。 -category: reference ---- - -# RENAME TABLE - -`RENAME TABLE` 语句用于对已有表进行重命名。 - -## 语法图 - -**RenameTableStmt:** - -![RenameTableStmt](/media/sqlgram/RenameTableStmt.png) - -**TableToTable:** - -![TableToTable](/media/sqlgram/TableToTable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -+----------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -RENAME TABLE t1 TO t2; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t2 | -+----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW TABLES](/v3.0/reference/sql/statements/show-tables.md) -* [ALTER TABLE](/v3.0/reference/sql/statements/alter-table.md) diff --git a/v3.0/reference/sql/statements/replace.md b/v3.0/reference/sql/statements/replace.md deleted file mode 100644 index 648d0bfffb4a..000000000000 --- a/v3.0/reference/sql/statements/replace.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: REPLACE -summary: TiDB 数据库中 REPLACE 的使用概况。 -category: reference ---- - -# REPLACE - -从语义上看，`REPLACE` 语句是 `DELETE` 语句和 `INSERT` 语句的结合，可用于简化应用程序代码。 - -## 语法图 - -**ReplaceIntoStmt:** - -![ReplaceIntoStmt](/media/sqlgram/ReplaceIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REPLACE INTO t1 (id, c1) VALUES(3, 99); -``` - -``` -Query OK, 2 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 99 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`REPLACE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/v3.0/reference/sql/statements/delete.md) -* [INSERT](/v3.0/reference/sql/statements/insert.md) -* [SELECT](/v3.0/reference/sql/statements/select.md) -* [UPDATE](/v3.0/reference/sql/statements/update.md) diff --git a/v3.0/reference/sql/statements/revoke-privileges.md b/v3.0/reference/sql/statements/revoke-privileges.md deleted file mode 100644 index d04d0691c16c..000000000000 --- a/v3.0/reference/sql/statements/revoke-privileges.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: REVOKE -summary: TiDB 数据库中 REVOKE 的使用概况。 -category: reference ---- - -# REVOKE - -`REVOKE ` 语句用于删除已有用户的权限。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REVOKE ALL ON test.* FROM 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP USER newuser; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR newuser; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -`REVOKE ` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [GRANT ](/v3.0/reference/sql/statements/grant-privileges.md) -* [SHOW GRANTS](/v3.0/reference/sql/statements/show-grants.md) -* [Privilege Management](/v3.0/reference/security/privilege-system.md) diff --git a/v3.0/reference/sql/statements/rollback.md b/v3.0/reference/sql/statements/rollback.md deleted file mode 100644 index 4f9366675318..000000000000 --- a/v3.0/reference/sql/statements/rollback.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: ROLLBACK -summary: TiDB 数据库中 ROLLBACK 的使用概况。 -category: reference ---- - -# ROLLBACK - -`ROLLBACK` 语句用于还原 TiDB 内当前事务中的所有更改，作用与 `COMMIT` 语句相反。 - -## 语法图 - -**Statement:** - -![Statement](/media/sqlgram/Statement.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -Empty set (0.01 sec) -``` - -## MySQL 兼容性 - -`ROLLBACK` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v3.0/reference/sql/statements/commit.md) -* [BEGIN](/v3.0/reference/sql/statements/begin.md) -* [START TRANSACTION](/v3.0/reference/sql/statements/start-transaction.md) diff --git a/v3.0/reference/sql/statements/select.md b/v3.0/reference/sql/statements/select.md deleted file mode 100644 index ddb41b9bfbbd..000000000000 --- a/v3.0/reference/sql/statements/select.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: SELECT -summary: TiDB 数据库中 SELECT 的使用概况。 -category: reference -aliases: ['/docs-cn/sql/dml/'] ---- - -# SELECT - -`SELECT` 语句用于从 TiDB 读取数据。 - -## 语法图 - -**SelectStmt:** - -![SelectStmt](/media/sqlgram/SelectStmt.png) - -**FromDual:** - -![FromDual](/media/sqlgram/FromDual.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtOpts:** - -![SelectStmtOpts](/media/sqlgram/SelectStmtOpts.png) - -**SelectStmtFieldList:** - -![SelectStmtFieldList](/media/sqlgram/SelectStmtFieldList.png) - -**TableRefsClause:** - -![TableRefsClause](/media/sqlgram/TableRefsClause.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtGroup:** - -![SelectStmtGroup](/media/sqlgram/SelectStmtGroup.png) - -**HavingClause:** - -![HavingClause](/media/sqlgram/HavingClause.png) - -**OrderByOptional:** - -![OrderByOptional](/media/sqlgram/OrderByOptional.png) - -**SelectStmtLimit:** - -![SelectStmtLimit](/media/sqlgram/SelectStmtLimit.png) - -**SelectLockOpt:** - -![SelectLockOpt](/media/sqlgram/SelectLockOpt.png) - -## 语法元素说明 - -|语法元素 | 说明 | -| --------------------- | -------------------------------------------------- | -|`ALL`、`DISTINCT`、`DISTINCTROW` | 查询结果集中可能会包含重复值。指定 DISTINCT/DISTINCTROW 则在查询结果中过滤掉重复的行；指定 ALL 则列出所有的行。默认为 ALL。| -|`HIGH_PRIORITY` | 该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句| -|`SQL_CALC_FOUND_ROWS` | TiDB 出于兼容性解析这个语法，但是不做任何处理| -|`SQL_CACHE`、`SQL_NO_CACHE` | 是否把请求结果缓存到 TiKV (RocksDB) 的 `BlockCache` 中。对于一次性的大数据量的查询，比如 `count(*)` 查询，为了避免冲掉 `BlockCache` 中用户的热点数据，建议填上 `SQL_NO_CACHE` | -|`STRAIGHT_JOIN`|`STRAIGHT_JOIN` 会强制优化器按照 `FROM` 子句中所使用的表的顺序做联合查询。当优化器选择的 Join 顺序并不优秀时，你可以使用这个语法来加速查询的执行| -|`select_expr` | 投影操作列表，一般包括列名、表达式，或者是用 '\*' 表示全部列| -|`FROM table_references` | 表示数据来源，数据来源可以是一个表（`select * from t;`）或者是多个表 (`select * from t1 join t2;`) 或者是0个表 (`select 1+1 from dual;`, 等价于 `select 1+1;`)| -|`WHERE where_condition` | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据| -|`GROUP BY` | GroupBy 子句用于对查询结果集进行分组| -|`HAVING where_condition` | Having 子句与 Where 子句作用类似，Having 子句可以让过滤 GroupBy 后的各种数据，Where 子句用于在聚合前过滤记录。| -|`ORDER BY` | OrderBy 子句用于指定结果排序顺序，可以按照列、表达式或者是 `select_expr` 列表中某个位置的字段进行排序。| -|`LIMIT` | Limit 子句用于限制结果条数。Limit 接受一个或两个数字参数，如果只有一个参数，那么表示返回数据的最大行数；如果是两个参数，那么第一个参数表示返回数据的第一行的偏移量（第一行数据的偏移量是 0），第二个参数指定返回数据的最大条目数。| -|`FOR UPDATE` | 对查询结果集所有行上锁（对于在查询条件内，但是不在结果集的行，将不会加锁，如事务启动后由其他事务写入的行），以监测其他事务对这些的并发修改。使用[乐观事务模型](/v3.0/reference/transactions/transaction-optimistic.md)时，语句执行期间不会检测锁，因此，不会像 PostgreSQL 之类的数据库一样，在当前事务结束前阻止其他事务执行 `UPDATE`、`DELETE` 和 `SELECT FOR UPDATE`。在事务的提交阶段 `SELECT FOR UPDATE` 读到的行，也会进行两阶段提交，因此，它们也可以参与事务冲突检测。如发生写入冲突，那么包含 `SELECT FOR UPDATE` 语句的事务会提交失败。如果没有冲突，事务将成功提交，当提交结束时，这些被加锁的行，会产生一个新版本，可以让其他尚未提交的事务，在将来提交时发现写入冲突。若使用悲观事务，则行为与其他数据库基本相同，不一致之处参考[和 MySQL InnoDB 的差异](/v3.0/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)。 | -|`LOCK IN SHARE MODE` | TiDB 出于兼容性解析这个语法，但是不做任何处理| - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SELECT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v3.0/reference/sql/statements/insert.md) -* [DELETE](/v3.0/reference/sql/statements/delete.md) -* [UPDATE](/v3.0/reference/sql/statements/update.md) -* [REPLACE](/v3.0/reference/sql/statements/replace.md) diff --git a/v3.0/reference/sql/statements/set-names.md b/v3.0/reference/sql/statements/set-names.md deleted file mode 100644 index 595829a17da4..000000000000 --- a/v3.0/reference/sql/statements/set-names.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: SET [NAMES|CHARACTER SET] -summary: TiDB 数据库中 SET [NAMES|CHARACTER SET] 的使用概况。 -category: reference ---- - -# SET [NAMES|CHARACTER SET] - -`SET NAMES`，`SET CHARACTER SET` 和 `SET CHARSET` 语句用于修改当前连接的变量 `character_set_client`，`character_set_results` 和 `character_set_connection`。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET NAMES utf8; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8 | -| character_set_system | utf8 | -| character_set_results | utf8 | -| character_set_client | utf8 | -| character_set_server | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET CHARACTER SET utf8mb4; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [NAMES|CHARACTER SET]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/v3.0/reference/sql/statements/show-variables.md) -* [SET ](/v3.0/reference/sql/statements/set-variable.md) -* [Character Set Support](/v3.0/reference/sql/character-set.md) diff --git a/v3.0/reference/sql/statements/set-password.md b/v3.0/reference/sql/statements/set-password.md deleted file mode 100644 index d8abdd1146cd..000000000000 --- a/v3.0/reference/sql/statements/set-password.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: SET PASSWORD -summary: TiDB 数据库中 SET PASSWORD 的使用概况。 -category: reference ---- - -# SET PASSWORD - -`SET PASSWORD` 语句用于更改 TiDB 系统数据库中的用户密码。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SET PASSWORD='test'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'test'; -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET PASSWORD FOR newuser = 'test'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET PASSWORD FOR newuser = PASSWORD('test'); -``` - -上述语法是早期 MySQL 版本的过时语法。 - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET PASSWORD` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE USER](/v3.0/reference/sql/statements/create-user.md) -* [Privilege Management](/v3.0/reference/security/privilege-system.md) diff --git a/v3.0/reference/sql/statements/set-transaction.md b/v3.0/reference/sql/statements/set-transaction.md deleted file mode 100644 index b2a1d64e9642..000000000000 --- a/v3.0/reference/sql/statements/set-transaction.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: SET TRANSACTION -summary: TiDB 数据库中 SET TRANSACTION 的使用概况。 -category: reference ---- - -# SET TRANSACTION - -`SET TRANSACTION` 语句用于在 `GLOBAL` 或 `SESSION` 的基础上更改当前的隔离级别，是 `SET transaction_isolation ='new-value'` 的替代语句，提供 MySQL 和 SQL 标准的兼容性。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -**TransactionChar:** - -![TransactionChar](/media/sqlgram/TransactionChar.png) - -**IsolationLevel:** - -![IsolationLevel](/media/sqlgram/IsolationLevel.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+----------------+ -| Variable_name | Value | -+-----------------------+----------------+ -| transaction_isolation | READ-COMMITTED | -+-----------------------+----------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION transaction_isolation = 'REPEATABLE-READ'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 支持仅在语法中将事务设置为只读的功能。 -* 不支持隔离级别 `READ-UNCOMMITTED` 和 `SERIALIZABLE`。 -* 隔离级别 `REPEATABLE-READ` 在技术上属于快照隔离（Snapshot Isolation）。在 TiDB 中称为 `REPEATABLE-READ` 是为了和 MySQL 保持一致。 - -## 另请参阅 - -* [SET \[GLOBAL|SESSION\] ](/v3.0/reference/sql/statements/set-variable.md) -* [Isolation Levels](/v3.0/reference/transactions/transaction-isolation.md) diff --git a/v3.0/reference/sql/statements/set-variable.md b/v3.0/reference/sql/statements/set-variable.md deleted file mode 100644 index 5ac7b4358aab..000000000000 --- a/v3.0/reference/sql/statements/set-variable.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: SET [GLOBAL|SESSION] -summary: TiDB 数据库中 SET [GLOBAL|SESSION] 的使用概况。 -category: reference ---- - -# SET [GLOBAL|SESSION] - -`SET [GLOBAL|SESSION]` 语句用于在 `SESSION` 或 `GLOBAL` 的范围内，对某个 TiDB 的内置变量进行更改。需注意，对 `GLOBAL` 变量的更改不适用于已有连接或本地连接，这与 MySQL 类似。只有新会话才会反映值的变化。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [GLOBAL|SESSION]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/v3.0/reference/sql/statements/show-variables.md) diff --git a/v3.0/reference/sql/statements/show-character-set.md b/v3.0/reference/sql/statements/show-character-set.md deleted file mode 100644 index e6d71e40879e..000000000000 --- a/v3.0/reference/sql/statements/show-character-set.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: SHOW CHARACTER SET -summary: TiDB 数据库中 SHOW CHARACTER SET 的使用概况。 -category: reference ---- - -# SHOW CHARACTER SET - -`SHOW CHARACTER SET` 语句提供 TiDB 中可用字符集的静态列表。此列表不反映当前连接或用户的任何属性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**CharsetKw:** - -![CharsetKw](/media/sqlgram/CharsetKw.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW CHARACTER SET; -``` - -``` -+---------+---------------+-------------------+--------+ -| Charset | Description | Default collation | Maxlen | -+---------+---------------+-------------------+--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------+---------------+-------------------+--------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CHARACTER SET` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW COLLATION](/v3.0/reference/sql/statements/show-collation.md) diff --git a/v3.0/reference/sql/statements/show-collation.md b/v3.0/reference/sql/statements/show-collation.md deleted file mode 100644 index 92df129f4ae0..000000000000 --- a/v3.0/reference/sql/statements/show-collation.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: SHOW COLLATION -summary: TiDB 数据库中 SHOW COLLATION 的使用概况。 -category: reference ---- - -# SHOW COLLATION - -`SHOW COLLATION` 语句用于提供一个静态的排序规则列表，确保与 MySQL 客户端库的兼容性。 - -> **注意:** TiDB 目前仅支持二进制排序规则。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW COLLATION; -``` - -``` -+--------------------------+----------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+--------------------------+----------+------+---------+----------+---------+ -| big5_chinese_ci | big5 | 1 | Yes | Yes | 1 | -| latin2_czech_cs | latin2 | 2 | | Yes | 1 | -| dec8_swedish_ci | dec8 | 3 | Yes | Yes | 1 | -| cp850_general_ci | cp850 | 4 | Yes | Yes | 1 | -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| hp8_english_ci | hp8 | 6 | Yes | Yes | 1 | -| koi8r_general_ci | koi8r | 7 | Yes | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin2_general_ci | latin2 | 9 | Yes | Yes | 1 | -| swe7_swedish_ci | swe7 | 10 | Yes | Yes | 1 | -| ascii_general_ci | ascii | 11 | Yes | Yes | 1 | -| ujis_japanese_ci | ujis | 12 | Yes | Yes | 1 | -| sjis_japanese_ci | sjis | 13 | Yes | Yes | 1 | -| cp1251_bulgarian_ci | cp1251 | 14 | | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| hebrew_general_ci | hebrew | 16 | Yes | Yes | 1 | -| tis620_thai_ci | tis620 | 18 | Yes | Yes | 1 | -| euckr_korean_ci | euckr | 19 | Yes | Yes | 1 | -| latin7_estonian_cs | latin7 | 20 | | Yes | 1 | -| latin2_hungarian_ci | latin2 | 21 | | Yes | 1 | -| koi8u_general_ci | koi8u | 22 | Yes | Yes | 1 | -| cp1251_ukrainian_ci | cp1251 | 23 | | Yes | 1 | -| gb2312_chinese_ci | gb2312 | 24 | Yes | Yes | 1 | -| greek_general_ci | greek | 25 | Yes | Yes | 1 | -| cp1250_general_ci | cp1250 | 26 | Yes | Yes | 1 | -| latin2_croatian_ci | latin2 | 27 | | Yes | 1 | -| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | -| cp1257_lithuanian_ci | cp1257 | 29 | | Yes | 1 | -| latin5_turkish_ci | latin5 | 30 | Yes | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| armscii8_general_ci | armscii8 | 32 | Yes | Yes | 1 | -| utf8_general_ci | utf8 | 33 | Yes | Yes | 1 | -| cp1250_czech_cs | cp1250 | 34 | | Yes | 1 | -| ucs2_general_ci | ucs2 | 35 | Yes | Yes | 1 | -| cp866_general_ci | cp866 | 36 | Yes | Yes | 1 | -| keybcs2_general_ci | keybcs2 | 37 | Yes | Yes | 1 | -| macce_general_ci | macce | 38 | Yes | Yes | 1 | -| macroman_general_ci | macroman | 39 | Yes | Yes | 1 | -| cp852_general_ci | cp852 | 40 | Yes | Yes | 1 | -| latin7_general_ci | latin7 | 41 | Yes | Yes | 1 | -| latin7_general_cs | latin7 | 42 | | Yes | 1 | -| macce_bin | macce | 43 | | Yes | 1 | -| cp1250_croatian_ci | cp1250 | 44 | | Yes | 1 | -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| cp1251_bin | cp1251 | 50 | | Yes | 1 | -| cp1251_general_ci | cp1251 | 51 | Yes | Yes | 1 | -| cp1251_general_cs | cp1251 | 52 | | Yes | 1 | -| macroman_bin | macroman | 53 | | Yes | 1 | -| utf16_general_ci | utf16 | 54 | Yes | Yes | 1 | -| utf16_bin | utf16 | 55 | | Yes | 1 | -| utf16le_general_ci | utf16le | 56 | Yes | Yes | 1 | -| cp1256_general_ci | cp1256 | 57 | Yes | Yes | 1 | -| cp1257_bin | cp1257 | 58 | | Yes | 1 | -| cp1257_general_ci | cp1257 | 59 | Yes | Yes | 1 | -| utf32_general_ci | utf32 | 60 | Yes | Yes | 1 | -| utf32_bin | utf32 | 61 | | Yes | 1 | -| utf16le_bin | utf16le | 62 | | Yes | 1 | -| binary | binary | 63 | Yes | Yes | 1 | -| armscii8_bin | armscii8 | 64 | | Yes | 1 | -| ascii_bin | ascii | 65 | | Yes | 1 | -| cp1250_bin | cp1250 | 66 | | Yes | 1 | -| cp1256_bin | cp1256 | 67 | | Yes | 1 | -| cp866_bin | cp866 | 68 | | Yes | 1 | -| dec8_bin | dec8 | 69 | | Yes | 1 | -| greek_bin | greek | 70 | | Yes | 1 | -| hebrew_bin | hebrew | 71 | | Yes | 1 | -| hp8_bin | hp8 | 72 | | Yes | 1 | -| keybcs2_bin | keybcs2 | 73 | | Yes | 1 | -| koi8r_bin | koi8r | 74 | | Yes | 1 | -| koi8u_bin | koi8u | 75 | | Yes | 1 | -| latin2_bin | latin2 | 77 | | Yes | 1 | -| latin5_bin | latin5 | 78 | | Yes | 1 | -| latin7_bin | latin7 | 79 | | Yes | 1 | -| cp850_bin | cp850 | 80 | | Yes | 1 | -| cp852_bin | cp852 | 81 | | Yes | 1 | -| swe7_bin | swe7 | 82 | | Yes | 1 | -| utf8_bin | utf8 | 83 | | Yes | 1 | -| big5_bin | big5 | 84 | | Yes | 1 | -| euckr_bin | euckr | 85 | | Yes | 1 | -| gb2312_bin | gb2312 | 86 | | Yes | 1 | -| gbk_bin | gbk | 87 | | Yes | 1 | -| sjis_bin | sjis | 88 | | Yes | 1 | -| tis620_bin | tis620 | 89 | | Yes | 1 | -| ucs2_bin | ucs2 | 90 | | Yes | 1 | -| ujis_bin | ujis | 91 | | Yes | 1 | -| geostd8_general_ci | geostd8 | 92 | Yes | Yes | 1 | -| geostd8_bin | geostd8 | 93 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -| cp932_japanese_ci | cp932 | 95 | Yes | Yes | 1 | -| cp932_bin | cp932 | 96 | | Yes | 1 | -| eucjpms_japanese_ci | eucjpms | 97 | Yes | Yes | 1 | -| eucjpms_bin | eucjpms | 98 | | Yes | 1 | -| cp1250_polish_ci | cp1250 | 99 | | Yes | 1 | -| utf16_unicode_ci | utf16 | 101 | | Yes | 1 | -| utf16_icelandic_ci | utf16 | 102 | | Yes | 1 | -| utf16_latvian_ci | utf16 | 103 | | Yes | 1 | -| utf16_romanian_ci | utf16 | 104 | | Yes | 1 | -| utf16_slovenian_ci | utf16 | 105 | | Yes | 1 | -| utf16_polish_ci | utf16 | 106 | | Yes | 1 | -| utf16_estonian_ci | utf16 | 107 | | Yes | 1 | -| utf16_spanish_ci | utf16 | 108 | | Yes | 1 | -| utf16_swedish_ci | utf16 | 109 | | Yes | 1 | -| utf16_turkish_ci | utf16 | 110 | | Yes | 1 | -| utf16_czech_ci | utf16 | 111 | | Yes | 1 | -| utf16_danish_ci | utf16 | 112 | | Yes | 1 | -| utf16_lithuanian_ci | utf16 | 113 | | Yes | 1 | -| utf16_slovak_ci | utf16 | 114 | | Yes | 1 | -| utf16_spanish2_ci | utf16 | 115 | | Yes | 1 | -| utf16_roman_ci | utf16 | 116 | | Yes | 1 | -| utf16_persian_ci | utf16 | 117 | | Yes | 1 | -| utf16_esperanto_ci | utf16 | 118 | | Yes | 1 | -| utf16_hungarian_ci | utf16 | 119 | | Yes | 1 | -| utf16_sinhala_ci | utf16 | 120 | | Yes | 1 | -| utf16_german2_ci | utf16 | 121 | | Yes | 1 | -| utf16_croatian_ci | utf16 | 122 | | Yes | 1 | -| utf16_unicode_520_ci | utf16 | 123 | | Yes | 1 | -| utf16_vietnamese_ci | utf16 | 124 | | Yes | 1 | -| ucs2_unicode_ci | ucs2 | 128 | | Yes | 1 | -| ucs2_icelandic_ci | ucs2 | 129 | | Yes | 1 | -| ucs2_latvian_ci | ucs2 | 130 | | Yes | 1 | -| ucs2_romanian_ci | ucs2 | 131 | | Yes | 1 | -| ucs2_slovenian_ci | ucs2 | 132 | | Yes | 1 | -| ucs2_polish_ci | ucs2 | 133 | | Yes | 1 | -| ucs2_estonian_ci | ucs2 | 134 | | Yes | 1 | -| ucs2_spanish_ci | ucs2 | 135 | | Yes | 1 | -| ucs2_swedish_ci | ucs2 | 136 | | Yes | 1 | -| ucs2_turkish_ci | ucs2 | 137 | | Yes | 1 | -| ucs2_czech_ci | ucs2 | 138 | | Yes | 1 | -| ucs2_danish_ci | ucs2 | 139 | | Yes | 1 | -| ucs2_lithuanian_ci | ucs2 | 140 | | Yes | 1 | -| ucs2_slovak_ci | ucs2 | 141 | | Yes | 1 | -| ucs2_spanish2_ci | ucs2 | 142 | | Yes | 1 | -| ucs2_roman_ci | ucs2 | 143 | | Yes | 1 | -| ucs2_persian_ci | ucs2 | 144 | | Yes | 1 | -| ucs2_esperanto_ci | ucs2 | 145 | | Yes | 1 | -| ucs2_hungarian_ci | ucs2 | 146 | | Yes | 1 | -| ucs2_sinhala_ci | ucs2 | 147 | | Yes | 1 | -| ucs2_german2_ci | ucs2 | 148 | | Yes | 1 | -| ucs2_croatian_ci | ucs2 | 149 | | Yes | 1 | -| ucs2_unicode_520_ci | ucs2 | 150 | | Yes | 1 | -| ucs2_vietnamese_ci | ucs2 | 151 | | Yes | 1 | -| ucs2_general_mysql500_ci | ucs2 | 159 | | Yes | 1 | -| utf32_unicode_ci | utf32 | 160 | | Yes | 1 | -| utf32_icelandic_ci | utf32 | 161 | | Yes | 1 | -| utf32_latvian_ci | utf32 | 162 | | Yes | 1 | -| utf32_romanian_ci | utf32 | 163 | | Yes | 1 | -| utf32_slovenian_ci | utf32 | 164 | | Yes | 1 | -| utf32_polish_ci | utf32 | 165 | | Yes | 1 | -| utf32_estonian_ci | utf32 | 166 | | Yes | 1 | -| utf32_spanish_ci | utf32 | 167 | | Yes | 1 | -| utf32_swedish_ci | utf32 | 168 | | Yes | 1 | -| utf32_turkish_ci | utf32 | 169 | | Yes | 1 | -| utf32_czech_ci | utf32 | 170 | | Yes | 1 | -| utf32_danish_ci | utf32 | 171 | | Yes | 1 | -| utf32_lithuanian_ci | utf32 | 172 | | Yes | 1 | -| utf32_slovak_ci | utf32 | 173 | | Yes | 1 | -| utf32_spanish2_ci | utf32 | 174 | | Yes | 1 | -| utf32_roman_ci | utf32 | 175 | | Yes | 1 | -| utf32_persian_ci | utf32 | 176 | | Yes | 1 | -| utf32_esperanto_ci | utf32 | 177 | | Yes | 1 | -| utf32_hungarian_ci | utf32 | 178 | | Yes | 1 | -| utf32_sinhala_ci | utf32 | 179 | | Yes | 1 | -| utf32_german2_ci | utf32 | 180 | | Yes | 1 | -| utf32_croatian_ci | utf32 | 181 | | Yes | 1 | -| utf32_unicode_520_ci | utf32 | 182 | | Yes | 1 | -| utf32_vietnamese_ci | utf32 | 183 | | Yes | 1 | -| utf8_unicode_ci | utf8 | 192 | | Yes | 1 | -| utf8_icelandic_ci | utf8 | 193 | | Yes | 1 | -| utf8_latvian_ci | utf8 | 194 | | Yes | 1 | -| utf8_romanian_ci | utf8 | 195 | | Yes | 1 | -| utf8_slovenian_ci | utf8 | 196 | | Yes | 1 | -| utf8_polish_ci | utf8 | 197 | | Yes | 1 | -| utf8_estonian_ci | utf8 | 198 | | Yes | 1 | -| utf8_spanish_ci | utf8 | 199 | | Yes | 1 | -| utf8_swedish_ci | utf8 | 200 | | Yes | 1 | -| utf8_turkish_ci | utf8 | 201 | | Yes | 1 | -| utf8_czech_ci | utf8 | 202 | | Yes | 1 | -| utf8_danish_ci | utf8 | 203 | | Yes | 1 | -| utf8_lithuanian_ci | utf8 | 204 | | Yes | 1 | -| utf8_slovak_ci | utf8 | 205 | | Yes | 1 | -| utf8_spanish2_ci | utf8 | 206 | | Yes | 1 | -| utf8_roman_ci | utf8 | 207 | | Yes | 1 | -| utf8_persian_ci | utf8 | 208 | | Yes | 1 | -| utf8_esperanto_ci | utf8 | 209 | | Yes | 1 | -| utf8_hungarian_ci | utf8 | 210 | | Yes | 1 | -| utf8_sinhala_ci | utf8 | 211 | | Yes | 1 | -| utf8_german2_ci | utf8 | 212 | | Yes | 1 | -| utf8_croatian_ci | utf8 | 213 | | Yes | 1 | -| utf8_unicode_520_ci | utf8 | 214 | | Yes | 1 | -| utf8_vietnamese_ci | utf8 | 215 | | Yes | 1 | -| utf8_general_mysql500_ci | utf8 | 223 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+--------------------------+----------+------+---------+----------+---------+ -219 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -TiDB 不支持二进制以外的排序规则。`SHOW COLLATION` 语句仅用于确保与 MySQL 的兼容性。 - -## 另请参阅 - -* [SHOW CHARACTER SET](/v3.0/reference/sql/statements/show-character-set.md) diff --git a/v3.0/reference/sql/statements/show-columns-from.md b/v3.0/reference/sql/statements/show-columns-from.md deleted file mode 100644 index 9a3e29ffd836..000000000000 --- a/v3.0/reference/sql/statements/show-columns-from.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: SHOW [FULL] COLUMNS FROM -summary: TiDB 数据库中 SHOW [FULL] COLUMNS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] COLUMNS FROM - -`SHOW [FULL] COLUMNS FROM` 语句用于以表格格式描述表或视图中的列。可选关键字 `FULL` 用于显示当前用户对该列的权限，以及表定义中的 `comment`。 - -`SHOW [FULL] FIELDS FROM`，`DESC
`，`DESCRIBE
` 和 `EXPLAIN
` 语句都是 `SHOW [FULL] COLUMNS FROM` 的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -create view v1 as select 1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -show columns from v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -desc v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -describe v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -explain v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show fields from v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show full columns from v1; -``` - -``` -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| 1 | bigint(1) | NULL | YES | | NULL | | select,insert,update,references | | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show full columns from mysql.user; -``` - -``` -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Host | char(64) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| User | char(32) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| Password | char(41) | utf8mb4_bin | YES | | NULL | | select,insert,update,references | | -| Select_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Insert_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Update_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Delete_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Process_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Grant_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| References_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_db_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Super_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_tmp_table_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Lock_tables_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Execute_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Index_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_user_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Event_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Trigger_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Account_locked | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -29 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] COLUMNS FROM` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) diff --git a/v3.0/reference/sql/statements/show-create-table.md b/v3.0/reference/sql/statements/show-create-table.md deleted file mode 100644 index 7a590685b2c2..000000000000 --- a/v3.0/reference/sql/statements/show-create-table.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: SHOW CREATE TABLE -summary: TiDB 数据库中 SHOW CREATE TABLE 的使用概况。 -category: reference ---- - -# SHOW CREATE TABLE - -`SHOW CREATE TABLE` 语句用于显示用 SQL 重新创建已有表的确切语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -+-------+------------------------------------------------------------------------------------------------------------+ -| Table | Create Table | -+-------+------------------------------------------------------------------------------------------------------------+ -| t1 | CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | -+-------+------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CREATE TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [SHOW TABLES](/v3.0/reference/sql/statements/show-tables.md) -* [SHOW COLUMNS FROM](/v3.0/reference/sql/statements/show-columns-from.md) diff --git a/v3.0/reference/sql/statements/show-create-user.md b/v3.0/reference/sql/statements/show-create-user.md deleted file mode 100644 index 16deeaa3cc26..000000000000 --- a/v3.0/reference/sql/statements/show-create-user.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: SHOW CREATE USER -summary: TiDB 数据库中 SHOW CREATE USER 的使用概况。 -category: reference ---- - -# SHOW CREATE USER - -`SHOW CREATE USER` 语句用于显示如何使用 `CREATE USER` 语法来重新创建用户。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'root'; -``` - -```+--------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for root@% | -+--------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'root'@'%' IDENTIFIED WITH 'mysql_native_password' AS '' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+--------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SHOW GRANTS FOR 'root'; -+-------------------------------------------+ -| Grants for root@% | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `SHOW CREATE USER` 的输出结果旨在匹配 MySQL，但 TiDB 尚不支持若干 `CREATE` 选项。尚未支持的选项在语句执行过程中会被解析但会被跳过执行。详情可参阅 [security compatibility]。 - -## 另请参阅 - -* [CREATE USER](/v3.0/reference/sql/statements/create-user.md) -* [SHOW GRANTS](/v3.0/reference/sql/statements/show-grants.md) -* [DROP USER](/v3.0/reference/sql/statements/drop-user.md) diff --git a/v3.0/reference/sql/statements/show-databases.md b/v3.0/reference/sql/statements/show-databases.md deleted file mode 100644 index f91943aedeb3..000000000000 --- a/v3.0/reference/sql/statements/show-databases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: SHOW DATABASES -summary: TiDB 数据库中 SHOW DATABASES 的使用概况。 -category: reference ---- - -# SHOW DATABASES - -`SHOW DATABASES` 语句用于显示当前用户有权访问的数据库列表。当前用户无权访问的数据库将从列表中隐藏。`information_schema` 数据库始终出现在列表的最前面。 - -`SHOW SCHEMAS` 是 `SHOW DATABASES` 语句的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE mynewdb; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mynewdb | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW DATABASES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW SCHEMAS](/v3.0/reference/sql/statements/show-schemas.md) -* [DROP DATABASE](/v3.0/reference/sql/statements/drop-database.md) -* [CREATE DATABASE](/v3.0/reference/sql/statements/create-database.md) diff --git a/v3.0/reference/sql/statements/show-engines.md b/v3.0/reference/sql/statements/show-engines.md deleted file mode 100644 index 800f8deaced4..000000000000 --- a/v3.0/reference/sql/statements/show-engines.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SHOW ENGINES -summary: TiDB 数据库中 SHOW ENGINES 的使用概况。 -category: reference ---- - -# SHOW ENGINES - -`SHOW ENGINES` 语句仅提供 MySQL 兼容性。 - -## 语法图 - -```sql -SHOW ENGINES; -``` - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW ENGINES; -``` - -``` -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -| Engine | Support | Comment | Transactions | XA | Savepoints | -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -| InnoDB | DEFAULT | Supports transactions, row-level locking, and foreign keys | YES | YES | YES | -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `SHOW ENGINES` 语句始终只返回 InnoDB 作为其支持的引擎。但 TiDB 内部通常使用 TiKV 作为存储引擎。 diff --git a/v3.0/reference/sql/statements/show-errors.md b/v3.0/reference/sql/statements/show-errors.md deleted file mode 100644 index 4b38d4c4d057..000000000000 --- a/v3.0/reference/sql/statements/show-errors.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: SHOW ERRORS -summary: TiDB 数据库中 SHOW ERRORS 的使用概况。 -category: reference ---- - -# SHOW ERRORS - -`SHOW ERRORS` 语句用于显示已执行语句中的错误。一旦先前的语句成功执行，就会清除错误缓冲区，这时 `SHOW ERRORS` 会返回一个空集。 - -当前的 `sql_mode` 很大程度决定了哪些语句会产生错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -select invalid; -``` - -``` -ERROR 1054 (42S22): Unknown column 'invalid' in 'field list' -``` - -{{< copyable "sql" >}} - -```sql -create invalid; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" -``` - -{{< copyable "sql" >}} - -```sql -SHOW ERRORS; -``` - -``` -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Level | Code | Message | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Error | 1054 | Unknown column 'invalid' in 'field list' | -| Error | 1064 | You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE invalid2; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 15 near "invalid2" -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1; -``` - -``` -+------+ -| 1 | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW ERRORS; -``` - -``` -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW ERRORS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW WARNINGS](/v3.0/reference/sql/statements/show-warnings.md) diff --git a/v3.0/reference/sql/statements/show-fields-from.md b/v3.0/reference/sql/statements/show-fields-from.md deleted file mode 100644 index 71b37688e3d2..000000000000 --- a/v3.0/reference/sql/statements/show-fields-from.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW [FULL] FIELDS FROM -summary: TiDB 数据库中 SHOW [FULL] FIELDS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] FIELDS FROM - -`SHOW [FULL] FIELDS FROM` 是 [`SHOW [FULL] COLUMNS FROM`](/v3.0/reference/sql/statements/show-columns-from.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/v3.0/reference/sql/statements/show-grants.md b/v3.0/reference/sql/statements/show-grants.md deleted file mode 100644 index 0daf70de199c..000000000000 --- a/v3.0/reference/sql/statements/show-grants.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: SHOW GRANTS -summary: TiDB 数据库中 SHOW GRANTS 的使用概况。 -category: reference ---- - -# SHOW GRANTS - -`SHOW GRANTS` 语句用于显示与用户关联的权限列表。与在 MySQL 中一样，`USAGE` 权限表示登录 TiDB 的能力。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS; -``` - -``` -+-------------------------------------------+ -| Grants for User | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'u1' on host '%' -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER u1; -``` - -``` -Query OK, 1 row affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO u1; -``` - -``` -Query OK, 0 rows affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR u1; -``` - -``` -+------------------------------------+ -| Grants for u1@% | -+------------------------------------+ -| GRANT USAGE ON *.* TO 'u1'@'%' | -| GRANT Select ON test.* TO 'u1'@'%' | -+------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW GRANTS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE USER](/v3.0/reference/sql/statements/show-create-user.md) -* [GRANT](/v3.0/reference/sql/statements/grant-privileges.md) diff --git a/v3.0/reference/sql/statements/show-index.md b/v3.0/reference/sql/statements/show-index.md deleted file mode 100644 index e730a435ccba..000000000000 --- a/v3.0/reference/sql/statements/show-index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW INDEX [FROM|IN] -summary: TiDB 数据库中 SHOW INDEX [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEX [FROM|IN] - -`SHOW INDEX [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/v3.0/reference/sql/statements/show-indexes.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/v3.0/reference/sql/statements/show-indexes.md b/v3.0/reference/sql/statements/show-indexes.md deleted file mode 100644 index 2d4b214223d8..000000000000 --- a/v3.0/reference/sql/statements/show-indexes.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: SHOW INDEXES [FROM|IN] -summary: TiDB 数据库中 SHOW INDEXES [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEXES [FROM|IN] - -`SHOW INDEXES [FROM|IN]` 语句用于列出指定表上的索引。`SHOW INDEX [FROM | IN]` 和 `SHOW KEYS [FROM | IN]` 是该语句的别名。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowIndexKwd:** - -![ShowIndexKwd](/media/sqlgram/ShowIndexKwd.png) - -**FromOrIn:** - -![FromOrIn](/media/sqlgram/FromOrIn.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT, INDEX(col1)); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEXES FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEX FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW KEYS FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW INDEXES [FROM|IN]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) -* [DROP INDEX](/v3.0/reference/sql/statements/drop-index.md) -* [CREATE INDEX](/v3.0/reference/sql/statements/create-index.md) diff --git a/v3.0/reference/sql/statements/show-keys.md b/v3.0/reference/sql/statements/show-keys.md deleted file mode 100644 index 928a76bf740b..000000000000 --- a/v3.0/reference/sql/statements/show-keys.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW KEYS [FROM|IN] -summary: TiDB 数据库中 SHOW KEYS [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW KEYS [FROM|IN] - -`SHOW KEYS [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/v3.0/reference/sql/statements/show-indexes.md) 语句的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/v3.0/reference/sql/statements/show-privileges.md b/v3.0/reference/sql/statements/show-privileges.md deleted file mode 100644 index ae3f6ae0d2d4..000000000000 --- a/v3.0/reference/sql/statements/show-privileges.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: SHOW PRIVILEGES -summary: TiDB 数据库中 SHOW PRIVILEGES 的使用概况。 -category: reference ---- - -# SHOW PRIVILEGES - -`SHOW PRIVILEGES` 语句用于显示 TiDB 中可分配权限的列表。此列表为静态列表，不反映当前用户的权限。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show privileges; -``` - -``` -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Privilege | Context | Comment | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Alter | Tables | To alter the table | -| Alter | Tables | To alter the table | -| Alter routine | Functions,Procedures | To alter or drop stored functions/procedures | -| Create | Databases,Tables,Indexes | To create new databases and tables | -| Create routine | Databases | To use CREATE FUNCTION/PROCEDURE | -| Create temporary tables | Databases | To use CREATE TEMPORARY TABLE | -| Create view | Tables | To create new views | -| Create user | Server Admin | To create new users | -| Delete | Tables | To delete existing rows | -| Drop | Databases,Tables | To drop databases, tables, and views | -| Event | Server Admin | To create, alter, drop and execute events | -| Execute | Functions,Procedures | To execute stored routines | -| File | File access on server | To read and write files on the server | -| Grant option | Databases,Tables,Functions,Procedures | To give to other users those privileges you possess | -| Index | Tables | To create or drop indexes | -| Insert | Tables | To insert data into tables | -| Lock tables | Databases | To use LOCK TABLES (together with SELECT privilege) | -| Process | Server Admin | To view the plain text of currently executing queries | -| Proxy | Server Admin | To make proxy user possible | -| References | Databases,Tables | To have references on tables | -| Reload | Server Admin | To reload or refresh tables, logs and privileges | -| Replication client | Server Admin | To ask where the slave or master servers are | -| Replication slave | Server Admin | To read binary log events from the master | -| Select | Tables | To retrieve rows from table | -| Show databases | Server Admin | To see all databases with SHOW DATABASES | -| Show view | Tables | To see views with SHOW CREATE VIEW | -| Shutdown | Server Admin | To shut down the server | -| Super | Server Admin | To use KILL thread, SET GLOBAL, CHANGE MASTER, etc. | -| Trigger | Tables | To use triggers | -| Create tablespace | Server Admin | To create/alter/drop tablespaces | -| Update | Tables | To update existing rows | -| Usage | Server Admin | No privileges - allow connect only | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -32 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW GRANTS](/v3.0/reference/sql/statements/show-grants.md) -* [GRANT ](/v3.0/reference/sql/statements/grant-privileges.md) diff --git a/v3.0/reference/sql/statements/show-processlist.md b/v3.0/reference/sql/statements/show-processlist.md deleted file mode 100644 index de34a95b0fef..000000000000 --- a/v3.0/reference/sql/statements/show-processlist.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: SHOW [FULL] PROCESSLIST -summary: TiDB 数据库中 SHOW [FULL] PROCESSLIST 的使用概况。 -category: reference ---- - -# SHOW [FULL] PROCESSLIST - -`SHOW [FULL] PROCESSLIST` 语句列出连接到相同 TiDB 服务器的当前会话。`Info` 列包含查询文本，除非指定可选关键字 `FULL`，否则文本会被截断。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW PROCESSLIST; -``` - -``` -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 中的 `State` 列是非描述性的。在 TiDB 中，将状态表示为单个值更复杂，因为查询是并行执行的，而且每个 GO 线程在任一时刻都有不同的状态。 - -## 另请参阅 - -* [KILL \[TIDB\]](/v3.0/reference/sql/statements/kill.md) diff --git a/v3.0/reference/sql/statements/show-schemas.md b/v3.0/reference/sql/statements/show-schemas.md deleted file mode 100644 index 8846a5d79e4b..000000000000 --- a/v3.0/reference/sql/statements/show-schemas.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW SCHEMAS -summary: TiDB 数据库中 SHOW SCHEMAS 的使用概况。 -category: reference ---- - -# SHOW SCHEMAS - -`SHOW SCHEMAS` 语句是 [`SHOW DATABASES`](/v3.0/reference/sql/statements/show-databases.md) 的别名。包含该语句提供了 MySQL 兼容性。。 diff --git a/v3.0/reference/sql/statements/show-status.md b/v3.0/reference/sql/statements/show-status.md deleted file mode 100644 index 1b9015a438d4..000000000000 --- a/v3.0/reference/sql/statements/show-status.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] STATUS -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] STATUS 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] STATUS - -`SHOW [GLOBAL|SESSION] STATUS` 语句用于提供 MySQL 兼容性，对 TiDB 没有作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -show global status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [FLUSH STATUS](/v3.0/reference/sql/statements/flush-status.md) diff --git a/v3.0/reference/sql/statements/show-table-regions.md b/v3.0/reference/sql/statements/show-table-regions.md deleted file mode 100644 index 25bbbac4a437..000000000000 --- a/v3.0/reference/sql/statements/show-table-regions.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: SHOW TABLE REGIONS -summary: 了解如何使用 TiDB 数据库中的 SHOW TABLE REGIONS。 -category: reference ---- - -# SHOW TABLE REGIONS - -`SHOW TABLE REGIONS` 语句用于显示 TiDB 中某个表的 Region 信息。 - -## 语法图 - -```sql -SHOW TABLE [table_name] REGIONS [WhereClauseOptional]; - -SHOW TABLE [table_name] INDEX [index_name] REGIONS [WhereClauseOptional]; -``` - -`SHOW TABLE REGIONS` 会返回如下列： - -* `REGION_ID`：Region 的 ID。 -* `START_KEY`：Region 的 Start key。 -* `END_KEY`：Region 的 End key。 -* `LEADER_ID`：Region 的 Leader ID。 -* `LEADER_STORE_ID`：Region leader 所在的 store (TiKV) ID。 -* `PEERS`：Region 所有副本的 ID。 -* `SCATTERING`：Region 是否正在调度中。1 表示正在调度。 -* `WRITTEN_BYTES`：估算的 Region 在 1 个心跳周期内的写入数据量大小，单位是 byte。 -* `READ_BYTES`：估算的 Region 在 1 个心跳周期内的读数据量大小，单位是 byte。 -* `APPROXIMATE_SIZE(MB)`：估算的 Region 的数据量大小，单位是 MB。 -* `APPROXIMATE_KEYS`：估算的 Region 内 Key 的个数。 - -> **注意：** -> -> `WRITTEN_BYTES`，`READ_BYTES`，`APPROXIMATE_SIZE(MB)`，`APPROXIMATE_KEYS` 的值是 PD 根据 Region 的心跳汇报信息统计，估算出来的数据，所以不是精确的数据。 - -## 示例 - -```sql -test> create table t (id int key,name varchar(50), index (name)); -Query OK, 0 rows affected - --- 默认新建表后会单独 split 出一个 Region 来存放该表的数据，开始时行数据和索引数据都会写到这个 Region。 -test> show table t regions; -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -| 3 | t_43_ | | 73 | 9 | 5, 73, 93 | 0 | 35 | 0 | 1 | 0 | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ --- 上面 START_KEY 列的值 t_43_ 中，t 是表数据的前缀，43 是表 t 的 table ID。 --- END_KEY 列的值为空（""）表示无穷大。 -1 row in set - --- 用 `SPLIT TABLE REGION` 语法切分行数据的 Region，下面语法把表 t 的行数据切分成 5 个 Region。 -test> split table t between (0) and (100000) regions 5; -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 5 | 1.0 | -+--------------------+----------------------+ --- TOTAL_SPLIT_REGION 表示新切的 region 数量，这是新切了 5 个 region. --- SCATTER_FINISH_RATIO 表示新切的 region 的打散成功率，1.0 表示都已经打散了。 - --- 表 t 现在一共有 6 个 Region，其中 102、106、110、114、3 用来存行数据，Region 98 用来存索引数据。 -test> show table t regions; -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | -| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 107, 108, 120 | 0 | 23 | 0 | 1 | 0 | -| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | -| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | -| 3 | t_43_r_80000 | | 93 | 8 | 5, 73, 93 | 0 | 0 | 0 | 1 | 0 | -| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ - --- Region 102 的 START_KEY 和 END_KEY 中，t_43 是表数据前缀和 table ID，_r 是表 t record 数据的前缀，索引数据的前缀是 _i， --- 所以 Region 102 的 START_KEY 和 END_KEY 表示用来存储 [-inf, 20000) 之前的 record 数据。其他 Region (103, 109, 113, 2) 的存储范围依次类推。 --- Region 98 用来存储索引数据存储。表 t 索引数据的起始 key 是 t_43_i，处于 Region 98 的存储范围内。 -6 rows in set - --- 查看表 t 在 store 1 上的 region，用 where 条件过滤。 -test> show table t regions where leader_store_id =1; -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ - - --- 用 `SPLIT TABLE REGION` 语法切分索引数据的 Region，下面语法把表 t 的索引 name 数据在 [a,z] 范围内切分成 2 个 Region。 -test> split table t index name between ("a") and ("z") regions 2; -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 2 | 1.0 | -+--------------------+----------------------+ -1 row in set - --- 现在表 t 一共有 7 个 Region，其中 5 个 Region (102, 106, 110, 114, 3) 用来存表 t 的 record 数据，另外 2 个 Region (135, 98) 用来存 name 索引的数据。 -test> show table t regions; -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | -| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 108, 120, 126 | 0 | 0 | 0 | 1 | 0 | -| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | -| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | -| 3 | t_43_r_80000 | | 93 | 8 | 73, 93, 128 | 0 | 0 | 0 | 1 | 0 | -| 135 | t_43_i_1_ | t_43_i_1_016d80000000000000 | 139 | 2 | 138, 139, 140 | 0 | 35 | 0 | 1 | 0 | -| 98 | t_43_i_1_016d80000000000000 | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -7 rows in set -``` - -## 另请参阅 - -* [SPLIT REGION](/v3.0/reference/sql/statements/split-region.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) diff --git a/v3.0/reference/sql/statements/show-table-status.md b/v3.0/reference/sql/statements/show-table-status.md deleted file mode 100644 index 2a6ef671116b..000000000000 --- a/v3.0/reference/sql/statements/show-table-status.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: SHOW TABLE STATUS -summary: TiDB 数据库中 SHOW TABLE STATUS 的使用概况。 -category: reference ---- - -# SHOW TABLE STATUS - -`SHOW TABLE STATUS` 语句用于显示 TiDB 中表的各种统计信息。如果显示统计信息过期，建议运行 [`ANALYZE TABLE`](/v3.0/reference/sql/statements/analyze-table.md)。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLE STATUS LIKE 't1'; -``` - -``` -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 0 - Avg_row_length: 0 - Data_length: 0 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -analyze table t1; -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLE STATUS LIKE 't1'; -``` - -``` -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 5 - Avg_row_length: 16 - Data_length: 80 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW TABLE STATUS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW TABLES](/v3.0/reference/sql/statements/show-tables.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) diff --git a/v3.0/reference/sql/statements/show-tables.md b/v3.0/reference/sql/statements/show-tables.md deleted file mode 100644 index 4cc4750a137f..000000000000 --- a/v3.0/reference/sql/statements/show-tables.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: SHOW [FULL] TABLES -summary: TiDB 数据库中 SHOW [FULL] TABLES 的使用概况。 -category: reference ---- - -# SHOW [FULL] TABLES - -`SHOW [FULL] TABLES` 语句用于显示当前所选数据库中表和视图的列表。可选关键字 `FULL` 说明表的类型是 `BASE TABLE` 还是 `VIEW`。 - -若要在不同的数据库中显示表，可使用 `SHOW TABLES IN DatabaseName` 语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.12 sec) - -mysql> CREATE VIEW v1 AS SELECT 1; -Query OK, 0 rows affected (0.10 sec) - -mysql> SHOW TABLES; -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -| v1 | -+----------------+ -2 rows in set (0.00 sec) - -mysql> SHOW FULL TABLES; -+----------------+------------+ -| Tables_in_test | Table_type | -+----------------+------------+ -| t1 | BASE TABLE | -| v1 | VIEW | -+----------------+------------+ -2 rows in set (0.00 sec) - -mysql> SHOW TABLES IN mysql; -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] TABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) diff --git a/v3.0/reference/sql/statements/show-variables.md b/v3.0/reference/sql/statements/show-variables.md deleted file mode 100644 index 5df75d4f95b3..000000000000 --- a/v3.0/reference/sql/statements/show-variables.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] VARIABLES -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] VARIABLES 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] VARIABLES - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句用于显示 `GLOBAL` 或 `SESSION` 范围的变量列表。如果未指定范围，则应用默认范围 `SESSION`。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'tidb%'; -``` - -``` -+-------------------------------------+---------------+ -| Variable_name | Value | -+-------------------------------------+---------------+ -| tidb_retry_limit | 10 | -| tidb_enable_streaming | 0 | -| tidb_hashagg_final_concurrency | 4 | -| tidb_disable_txn_auto_retry | 1 | -| tidb_mem_quota_query | 34359738368 | -| tidb_skip_isolation_level_check | 0 | -| tidb_ddl_reorg_batch_size | 1024 | -| tidb_constraint_check_in_place | 0 | -| tidb_current_ts | 0 | -| tidb_opt_insubq_to_join_and_agg | 1 | -| tidb_enable_window_function | 1 | -| tidb_ddl_error_count_limit | 512 | -| tidb_checksum_table_concurrency | 4 | -| tidb_config | | -| tidb_batch_insert | 0 | -| tidb_opt_join_reorder_threshold | 0 | -| tidb_auto_analyze_end_time | 23:59 +0000 | -| tidb_index_lookup_size | 20000 | -| tidb_projection_concurrency | 4 | -| tidb_opt_correlation_threshold | 0.9 | -| tidb_enable_table_partition | auto | -| tidb_wait_split_region_timeout | 300 | -| tidb_skip_utf8_check | 0 | -| tidb_dml_batch_size | 20000 | -| tidb_backoff_weight | 2 | -| tidb_txn_mode | | -| tidb_mem_quota_indexlookupjoin | 34359738368 | -| tidb_hashagg_partial_concurrency | 4 | -| tidb_enable_radix_join | 0 | -| tidb_mem_quota_topn | 34359738368 | -| tidb_hash_join_concurrency | 5 | -| tidb_max_chunk_size | 1024 | -| tidb_mem_quota_indexlookupreader | 34359738368 | -| tidb_expensive_query_time_threshold | 60 | -| tidb_enable_cascades_planner | 0 | -| tidb_mem_quota_mergejoin | 34359738368 | -| tidb_auto_analyze_ratio | 0.5 | -| tidb_index_lookup_concurrency | 4 | -| tidb_force_priority | NO_PRIORITY | -| tidb_ddl_reorg_priority | PRIORITY_LOW | -| tidb_index_lookup_join_concurrency | 4 | -| tidb_index_join_batch_size | 25000 | -| tidb_index_serial_scan_concurrency | 1 | -| tidb_mem_quota_nestedloopapply | 34359738368 | -| tidb_auto_analyze_start_time | 00:00 +0000 | -| tidb_snapshot | | -| tidb_low_resolution_tso | 0 | -| tidb_batch_commit | 0 | -| tidb_init_chunk_size | 32 | -| tidb_build_stats_concurrency | 4 | -| tidb_backoff_lock_fast | 100 | -| tidb_optimizer_selectivity_level | 0 | -| tidb_batch_delete | 0 | -| tidb_distsql_scan_concurrency | 15 | -| tidb_scatter_region | 0 | -| tidb_opt_correlation_exp_factor | 1 | -| tidb_ddl_reorg_worker_cnt | 16 | -| tidb_wait_split_region_finish | 1 | -| tidb_mem_quota_sort | 34359738368 | -| tidb_general_log | 0 | -| tidb_opt_write_row_id | 0 | -| tidb_check_mb4_value_in_utf8 | 1 | -| tidb_enable_fast_analyze | 0 | -| tidb_slow_query_file | tidb-slow.log | -| tidb_slow_log_threshold | 300 | -| tidb_opt_agg_push_down | 0 | -| tidb_mem_quota_hashjoin | 34359738368 | -| tidb_query_log_max_len | 2048 | -+-------------------------------------+---------------+ -68 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'time_zone%'; -``` - -``` -+---------------+--------+ -| Variable_name | Value | -+---------------+--------+ -| time_zone | SYSTEM | -+---------------+--------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SET](/v3.0/reference/sql/statements/set-variable.md) diff --git a/v3.0/reference/sql/statements/show-warnings.md b/v3.0/reference/sql/statements/show-warnings.md deleted file mode 100644 index b64928e1d183..000000000000 --- a/v3.0/reference/sql/statements/show-warnings.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: SHOW WARNINGS -summary: TiDB 数据库中 SHOW WARNINGS 的使用概况。 -category: reference ---- - -# SHOW WARNINGS - -`SHOW WARNINGS` 语句用于显示当前客户端连接中已执行语句的报错列表。与在 MySQL 中一样，`sql_mode` 极大地影响哪些语句会导致错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT UNSIGNED); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (0); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1/a FROM t1; -``` - -``` -+------+ -| 1/a | -+------+ -| NULL | -+------+ -1 row in set, 1 warning (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW WARNINGS; -``` - -``` -+---------+------+---------------+ -| Level | Code | Message | -+---------+------+---------------+ -| Warning | 1365 | Division by 0 | -+---------+------+---------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (-1); -``` - -``` -ERROR 1264 (22003): Out of range value for column 'a' at row 1 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 0 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET sql_mode=''; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (-1); -``` - -``` -Query OK, 1 row affected, 1 warning (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW WARNINGS; -``` - -``` -+---------+------+---------------------------+ -| Level | Code | Message | -+---------+------+---------------------------+ -| Warning | 1690 | constant -1 overflows int | -+---------+------+---------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 0 | -| 0 | -+------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW WARNINGS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [SHOW ERRORS](/v3.0/reference/sql/statements/show-errors.md) diff --git a/v3.0/reference/sql/statements/split-region.md b/v3.0/reference/sql/statements/split-region.md deleted file mode 100644 index 7b61d7691e36..000000000000 --- a/v3.0/reference/sql/statements/split-region.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Split Region 使用文档 -category: reference ---- - -# Split Region 使用文档 - -在 TiDB 中新建一个表后，默认会单独切分出 1 个 Region 来存储这个表的数据，这个默认行为由配置文件中的 `split-table` 控制。当这个 Region 中的数据超过默认 Region 大小限制后，这个 Region 会开始分裂成 2 个 Region。 - -上述情况中，如果在新建的表上发生大批量写入，则会造成热点，因为开始只有一个 Region，所有的写请求都发生在该 Region 所在的那台 TiKV 上。 - -为解决上述场景中的热点问题，TiDB 引入了预切分 Region 的功能，即可以根据指定的参数，预先为某个表切分出多个 Region，并打散到各个 TiKV 上去。 - -## Split Region 的使用 - -Split Region 有 2 种不同的语法，具体如下： - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -`BETWEEN lower_value AND upper_value REGIONS region_num` 语法是通过指定上、下边界和 Region 数量，然后在上、下边界之间均匀切分出 `region_num` 个 Region。 - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ... -``` - -`BY value_list…` 语法将手动指定一系列的点，然后根据这些指定的点切分 Region，适用于数据不均匀分布的场景。 - -### Split Table Region - -表中行数据的 key 由 `table_id` 和 `row_id` 编码组成，格式如下： - -```go -t[table_id]_r[row_id] -``` - -例如，当 `table_id` 是 22，`row_id` 是 11 时： - -```go -t22_r11 -``` - -同一表中行数据的 `table_id` 是一样的，但 `row_id` 肯定不一样，所以可以根据 `row_id` 来切分 Region。 - -#### 均匀切分 - -由于 `row_id` 是整数，所以根据指定的 `lower_value`、`upper_value` 以及 `region_num`，可以推算出需要切分的 key。TiDB 先计算 step（`step = (upper_value - lower_value)/num`），然后在 `lower_value` 和 `upper_value` 之间每隔 step 区间切一次，最终切出 `num` 个 Region。 - -例如，对于表 t，如果想要从 `minInt64`~`maxInt64` 之间均匀切割出 16 个 Region，可以用以下语句： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 从 minInt64 到 maxInt64 之间均匀切割出 16 个 Region。如果已知主键的范围没有这么大，比如只会在 0~1000000000 之间，那可以用 0 和 1000000000 分别代替上面的 minInt64 和 maxInt64 来切分 Region。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (0) AND (1000000000) REGIONS 16; -``` - -#### 不均匀切分 - -如果已知数据不是均匀分布的，比如想要 -inf ~ 10000 切一个 Region，10000 ~ 90000 切一个 Region，90000 ~ +inf 切一个 Region，可以通过手动指定点来切分 Region，示例如下： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BY (10000), (90000); -``` - -### Split Index Region - -表中索引数据的 key 由 `table_id`、`index_id` 以及索引列的值编码组成，格式如下： - -```go -t[table_id]_i[index_id][index_value] -``` - -例如，当 `table_id` 是 22，`index_id` 是 5，`index_value` 是 abc 时： - -```go -t22_i5abc -``` - -同一表中同一索引数据的 `table_id` 和 `index_id` 是一样的，所以要根据 `index_value` 切分索引 Region。 - -#### 均匀切分 - -索引均匀切分与行数据均匀切分的原理一样，只是计算 step 的值较为复杂，因为 `index_value` 可能不是整数。 - -`upper` 和 `lower` 的值会先编码成 byte 数组，去掉 `lower` 和 `upper` byte 数组的最长公共前缀后，从 `lower` 和 `upper` 各取前 8 字节转成 uint64，再计算 `step = (upper - lower)/num`。计算出 step 后再将 step 编码成 byte 数组，添加到之前 `upper`和 `lower`的最长公共前缀后面组成一个 key 后去做切分。示例如下： - -如果索引 idx 的列也是整数类型，可以用如下 SQL 语句切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 中 idx 索引数据 Region 从 `minInt64` 到 `maxInt64` 之间均匀切割出 16 个 Region。 - -如果索引 idx1 的列是 varchar 类型，希望根据前缀字母来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx1 BETWEEN ("a") AND ("z") REGIONS 26; -``` - -该语句会把表 t 中 idx1 索引数据的 Region 从 a~z 切成 26 个 Region，region1 的范围是 [minIndexValue, b)，region2 的范围是 [b, c)，……，region26 的范围是 [z, maxIndexValue)。对于 idx 索引以 a 为前缀的数据都会写到 region1，以 b 为前缀的索引数据都会写到 region2，以此类推。 - -如果索引 idx2 的列是 timestamp/datetime 等时间类型，希望根据时间区间来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx2 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -该语句会把表 t 中 idx2 的索引数据 Region 从 `2010-01-01 00:00:00` 到 `2020-01-01 00:00:00` 切成 10 个 Region。region1 的范围是从 `[minIndexValue, 2011-01-01 00:00:00)`，region2 的范围是 `[2011-01-01 00:00:00, 2012-01-01 00:00:00)`…… - -其他索引列类型的切分方法也是类似的。 - -对于联合索引的数据 Region 切分，唯一不同的是可以指定多个 column 的值。 - -比如索引 `idx3 (a, b)` 包含 2 列，a 是 timestamp，b 是 int。如果只想根据 a 列做时间范围的切分，可以用切分单列时间索引的 SQL 语句来切分，`lower_value` 和 `upper_velue` 中不指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -如果想在时间相同的情况下，根据 b 列再做一次切分，在切分时指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00", "a") AND ("2010-01-01 00:00:00", "z") REGIONS 10; -``` - -该语句在 a 列时间前缀相同的情况下，根据 b 列的值从 a~z 切了 10 个 Region。如果指定的 a 列的值不相同，那么可能不会用到 b 列的值。 - -#### 不均匀切分 - -索引数据也可以根据用户指定的索引值来做切分。 - -假如有 idx4 (a,b)，其中 a 列是 varchar 类型， b 列是 timestamp 类型。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t1 INDEX idx4 BY ("a", "2000-01-01 00:00:01"), ("b", "2019-04-17 14:26:19"), ("c", ""); -``` - -该语句指定了 3 个值，会切分出 4 个 Region，每个 Region 的范围如下。 - -``` -region1 [ minIndexValue , ("a", "2000-01-01 00:00:01")) -region2 [("a", "2000-01-01 00:00:01") , ("b", "2019-04-17 14:26:19")) -region3 [("b", "2019-04-17 14:26:19") , ("c", "") ) -region4 [("c", "") , maxIndexValue ) -``` - -## pre_split_regions - -使用带有 `shard_row_id_bits` 的表时，如果希望建表时就均匀切分 Region，可以考虑配合 `pre_split_regions` 一起使用，用来在建表成功后就开始预均匀切分 `2^(pre_split_regions)` 个 Region。 - -> **注意：** -> -> `pre_split_regions` 必须小于等于 `shard_row_id_bits`。 - -### 示例 - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int,index idx1(a)) shard_row_id_bits = 4 pre_split_regions=2; -``` - -该语句在建表后，会对这个表 t 预切分出 4 + 1 个 Region。4 (2^2) 个 Region 是用来存 table 的行数据的，1 个 Region 是用来存 idx1 索引的数据。 - -4 个 table Region 的范围区间如下： - -``` -region1: [ -inf , 1<<61 ) -region2: [ 1<<61 , 2<<61 ) -region3: [ 2<<61 , 3<<61 ) -region4: [ 3<<61 , +inf ) -``` - -## 相关 session 变量 - -和 `SPLIT REGION` 语句相关的 session 变量有 `tidb_scatter_region`，`tidb_wait_split_region_finish` 和 `tidb_wait_split_region_timeout`，具体可参考 [TiDB 专用系统变量和语法](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/v3.0/reference/sql/statements/start-transaction.md b/v3.0/reference/sql/statements/start-transaction.md deleted file mode 100644 index 5c4e18a4da2b..000000000000 --- a/v3.0/reference/sql/statements/start-transaction.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: START TRANSACTION -summary: TiDB 数据库中 START TRANSACTION 的使用概况。 -category: reference ---- - -# START TRANSACTION - -`START TRANSACTION` 语句用于在 TiDB 内部启动新事务。它类似于语句 `BEGIN` 和 `SET autocommit = 0`。 - -在没有 `START TRANSACTION` 语句的情况下，每个语句都会在各自的事务中自动提交，这样可确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`START TRANSACTION` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v3.0/reference/sql/statements/commit.md) -* [ROLLBACK](/v3.0/reference/sql/statements/rollback.md) -* [BEGIN](/v3.0/reference/sql/statements/begin.md) diff --git a/v3.0/reference/sql/statements/trace.md b/v3.0/reference/sql/statements/trace.md deleted file mode 100644 index 5f074c0e6698..000000000000 --- a/v3.0/reference/sql/statements/trace.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: TRACE -summary: TiDB 数据库中 TRACE 的使用概况。 -category: reference ---- - -# TRACE - -`TRACE` 语句用于提供查询执行的详细信息，可通过 TiDB 服务器状态端口所公开的图形界面进行查看。 - -## 语法图 - -**TraceStmt:** - -![TraceStmt](/media/sqlgram/TraceStmt.png) - -**TraceableStmt:** - -![TraceableStmt](/media/sqlgram/TraceableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -trace format='row' select * from mysql.user; -``` - -``` -+---------------------------+-----------------+------------+ -| operation | startTS | duration | -+---------------------------+-----------------+------------+ -| session.getTxnFuture | 10:33:34.647148 | 3.847µs | -| ├─session.Execute | 10:33:34.647146 | 536.233µs | -| ├─session.ParseSQL | 10:33:34.647182 | 19.868µs | -| ├─executor.Compile | 10:33:34.647219 | 295.688µs | -| ├─session.runStmt | 10:33:34.647533 | 116.229µs | -| ├─session.CommitTxn | 10:33:34.647631 | 5.44µs | -| ├─recordSet.Next | 10:33:34.647707 | 833.103µs | -| ├─tableReader.Next | 10:33:34.647709 | 806.783µs | -| ├─recordSet.Next | 10:33:34.648572 | 19.367µs | -| └─tableReader.Next | 10:33:34.648575 | 1.783µs | -+---------------------------+-----------------+------------+ -10 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -TRACE FORMAT='json' SELECT * FROM t1 WHERE id = 2; -``` - -``` -operation: [ - {"ID":{"Trace":"60d20d005593de87","Span":"44e5b309242ffe2f","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5nZXRUeG5GdXR1cmU="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTQ3ODYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MjA0MDYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":[ - {"ID":{"Trace":"60d20d005593de87","Span":"4dbf8f2ca373b4b0","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5QYXJzZVNRTA=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2NjE1MTQtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MDYxNjgtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6b6d6916df809604","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"ZXhlY3V0b3IuQ29tcGlsZQ=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NTcyODUtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MzE0MjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"3f1bcdd402a72911","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5Db21taXRUeG4="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3OTgyNjItMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MDU1NzYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"58c1f7d66dc5afbc","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5ydW5TdG10"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Msg","Value":"eyJzcWwiOiJTRUxFQ1QgKiBGUk9NIHQxIFdIRVJFIGlkID0gMiJ9"}, - {"Key":"Time","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3ODA1NjgtMDY6MDA="}, - {"Key":"_schema:log","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MTk5MzMtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NzcyNDItMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6bd8cc440fb31ed7","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5FeGVjdXRl"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTEwODktMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NTU0My0wNjowMA=="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"61d0b809f6cc018b","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NzQ1NTYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIyOTg4NjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"2bd2c3d47ccb1133","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjY0ODgtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjkwMDMtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null} - ] - } -] -1 row in set (0.00 sec) -``` - -可将 JSON 格式的跟踪文件粘贴到跟踪查看器中。查看器可通过 TiDB 状态端口访问： - -![TiDB Trace Viewer-1](/media/trace-paste.png) - -![TiDB Trace Viewer-2](/media/trace-view.png) - -## MySQL 兼容性 - -`TRACE` 语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [EXPLAIN ANALYZE](/v3.0/reference/sql/statements/explain-analyze.md) diff --git a/v3.0/reference/sql/statements/truncate.md b/v3.0/reference/sql/statements/truncate.md deleted file mode 100644 index 655481139fb0..000000000000 --- a/v3.0/reference/sql/statements/truncate.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: TRUNCATE -summary: TiDB 数据库中 TRUNCATE 的使用概况。 -category: reference ---- - -# TRUNCATE - -`TRUNCATE` 语句以非事务方式从表中删除所有数据。可认为 `TRUNCATE` 语句同 `DROP TABLE` + `CREATE TABLE` 组合在语义上相同，定义与 `DROP TABLE` 语句相同。 - -`TRUNCATE TABLE tableName` 和 `TRUNCATE tableName` 均为有效语法。 - -## 语法图 - -**TruncateTableStmt:** - -![TruncateTableStmt](/media/sqlgram/TruncateTableStmt.png) - -**OptTable:** - -![OptTable](/media/sqlgram/OptTable.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -TRUNCATE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sqlS -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -TRUNCATE TABLE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -## MySQL 兼容性 - -`TRUNCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [DROP TABLE](/v3.0/reference/sql/statements/drop-table.md) -* [DELETE](/v3.0/reference/sql/statements/delete.md) -* [CREATE TABLE](/v3.0/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.0/reference/sql/statements/show-create-table.md) diff --git a/v3.0/reference/sql/statements/update.md b/v3.0/reference/sql/statements/update.md deleted file mode 100644 index 82281637de4d..000000000000 --- a/v3.0/reference/sql/statements/update.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: UPDATE -summary: TiDB 数据库中 UPDATE 的使用概况。 -category: reference ---- - -# UPDATE - -`UPDATE` 语句用于修改指定表中的数据。 - -## 语法图 - -**UpdateStmt:** - -![UpdateStmt](/media/sqlgram/UpdateStmt.png) - -**TableRef:** - -![TableRef](/media/sqlgram/TableRef.png) - -**TableRefs:** - -![TableRefs](/media/sqlgram/TableRefs.png) - -**AssignmentList:** - -![AssignmentList](/media/sqlgram/AssignmentList.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -UPDATE t1 SET c1=5 WHERE c1=3; -``` - -``` -Query OK, 1 row affected (0.01 sec) -Rows matched: 1 Changed: 1 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`UPDATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v3.0/reference/sql/statements/insert.md) -* [SELECT](/v3.0/reference/sql/statements/select.md) -* [DELETE](/v3.0/reference/sql/statements/delete.md) -* [REPLACE](/v3.0/reference/sql/statements/replace.md) diff --git a/v3.0/reference/sql/statements/use.md b/v3.0/reference/sql/statements/use.md deleted file mode 100644 index 6cec9adac62e..000000000000 --- a/v3.0/reference/sql/statements/use.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: USE -summary: TiDB 数据库中 USE 的使用概况。 -category: reference ---- - -# USE - -`USE` 语句可为用户会话选择当前数据库。 - -## 语法图 - -**UseStmt:** - -![UseStmt](/media/sqlgram/UseStmt.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -USE mysql; -``` - -``` -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE newtest; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -USE newtest; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+-------------------+ -| Tables_in_newtest | -+-------------------+ -| t1 | -+-------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`USE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.0/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v3.0/reference/sql/statements/create-database.md) -* [SHOW TABLES](/v3.0/reference/sql/statements/show-tables.md) diff --git a/v3.0/reference/sql/view.md b/v3.0/reference/sql/view.md deleted file mode 100644 index e748251b4ba9..000000000000 --- a/v3.0/reference/sql/view.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: 视图 -category: reference ---- - -# 视图 - -TiDB 支持视图，视图是一张虚拟表，该虚拟表的结构由创建视图时的 `SELECT` 语句定义。使用视图一方面可以对用户只暴露安全的字段及数据，进而保证底层表的敏感字段及数据的安全。另一方面，将频繁出现的复杂查询定义为视图，可以使复杂查询更加简单便捷。 - -## 查询视图 - -查询一个视图和查询一张普通表类似。但是 TiDB 在真正执行查询视图时，会将视图展开成创建视图时定义的 `SELECT` 语句，进而执行展开后的查询语句。 - -## 样例 - -以下例子将创建一个视图，并在该视图上进行查询，最后删除该视图。 - -{{< copyable "sql" >}} - -```sql -create table t(a int, b int); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values(1, 1),(2,2),(3,3); -``` - -``` -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -create table s(a int); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into s values(2),(3); -``` - -``` -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -create view v as select s.a from t left join s on t.a = s.a; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from v; -``` - -``` -+------+ -| a | -+------+ -| NULL | -| 2 | -| 3 | -+------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -drop view v; -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -## 局限性 - -目前 TiDB 中的视图有以下局限性： - -- 不支持物化视图。 -- TiDB 中视图为只读视图，不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 -- 对已创建的视图仅支持 `DROP` 的 DDL 操作，即 `DROP [VIEW | TABLE]`。 - -## 扩展阅读 - -- [创建视图](/v3.0/reference/sql/statements/create-view.md) -- [删除视图](/v3.0/reference/sql/statements/drop-view.md) diff --git a/v3.0/reference/supported-clients.md b/v3.0/reference/supported-clients.md deleted file mode 100644 index 6fb259996054..000000000000 --- a/v3.0/reference/supported-clients.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: 连接器和 API -category: reference -aliases: ['/docs-cn/sql/connection-and-APIs/'] ---- - -# 连接器和 API - -数据库连接器为客户端提供了连接数据库服务端的方式，APIs 提供了使用 MySQL 协议和资源的底层接口。无论是连接器还是 API，都可以用来在不同的语言和环境内连接服务器并执行 sql 语句，包括 odbc、java(jdbc)、Perl、Python、PHP、Ruby 和 C。 - -TiDB 兼容 MySQL(5.6、5.7) 的所有连接器和 API，包括： - -+ [MySQL Connector/C++](https://dev.mysql.com/doc/refman/5.7/en/connector-cpp-info.html) -+ [MySQL Connector/J](https://dev.mysql.com/doc/refman/5.7/en/connector-j-info.html) -+ [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html) -+ [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html) -+ [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html) -+ [MySQL C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html) -+ [MySQL PHP API](https://dev.mysql.com/doc/refman/5.7/en/apis-php-info.html) -+ [MySQL Perl API](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html) -+ [MySQL Python API](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html) -+ [MySQL Ruby APIs](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby.html) -+ [MySQL Tcl API](https://dev.mysql.com/doc/refman/5.7/en/apis-tcl.html) -+ [MySQL Eiffel Wrapper](https://dev.mysql.com/doc/refman/5.7/en/apis-eiffel.html) -+ [Mysql Go API](https://github.com/go-sql-driver/mysql) - -## 使用 MySQL 连接器连接 TiDB - -Oracle 官方提供了以下 API，TiDB 可以兼容所有这些 API。 - -+ [MySQL Connector/C++](https://dev.mysql.com/doc/refman/5.7/en/connector-cpp-info.html)：C++ 语言的客户端库 -+ [MySQL Connector/J](https://dev.mysql.com/doc/refman/5.7/en/connector-j-info.html)：Java 语言的客户端库，基于标准 JDBC 接口 -+ [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html)：.Net 语言的客户端库，[MySQL for Visual Studio](https://dev.mysql.com/doc/visual-studio/en/)使用这个库，支持 Microsoft Visual Studio 2012，2013，2015和2017版本 -+ [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html)：标准的 ODBC 接口，支持 Windows，Unix 和 OS X -+ [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html)：Python 语言的客户端包，和 [Python DB API version 2.0](http://www.python.org/dev/peps/pep-0249/) 一致 - -## 使用 MySQL C API 连接 TiDB - -如果使用 C 语言程序直接连接 TiDB，可以直接链接 libmysqlclient 库，使用 MySQL 的 [C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html)，这是最主要的一种 C 语言连接方式，被各种客户端和 API 广泛使用，包括 Connector/C。 - -## 使用 MySQL 第三方 API 连接 TiDB - -第三方 API 非 Oracle 官方提供，下表列出了常用的第三方 API： - -| Environment | API | Type | Notes | -| -------------- | ---------------------------------------- | -------------------------------- | ---------------------------------------- | -| Ada | GNU Ada MySQL Bindings | `libmysqlclient` | See [MySQL Bindings for GNU Ada](http://gnade.sourceforge.net/) | -| C | C API | `libmysqlclient` | See [Section 27.8, “MySQL C API”](https://dev.mysql.com/doc/refman/5.7/en/c-api.html). | -| C++ | Connector/C++ | `libmysqlclient` | See [MySQL Connector/C++ Developer Guide](https://dev.mysql.com/doc/connector-cpp/en/). | -| | MySQL++ | `libmysqlclient` | See [MySQL++ Web site](http://tangentsoft.net/mysql++/doc/). | -| | MySQL wrapped | `libmysqlclient` | See [MySQL wrapped](http://www.alhem.net/project/mysql/). | -| Go | go-sql-driver | Native Driver | See [Mysql Go API](https://github.com/go-sql-driver/mysql) | -| Cocoa | MySQL-Cocoa | `libmysqlclient` | Compatible with the Objective-C Cocoa environment. See | -| D | MySQL for D | `libmysqlclient` | See [MySQL for D](https://github.com/mysql-d/mysql-native). | -| Eiffel | Eiffel MySQL | `libmysqlclient` | See [Section 27.14, “MySQL Eiffel Wrapper”](https://dev.mysql.com/doc/refman/5.7/en/apis-eiffel.html). | -| Erlang | `erlang-mysql-driver` | `libmysqlclient` | See [`erlang-mysql-driver`.](http://code.google.com/p/erlang-mysql-driver/) | -| Haskell | Haskell MySQL Bindings | Native Driver | See [Brian O'Sullivan's pure Haskell MySQL bindings](http://www.serpentine.com/blog/software/mysql/). | -| | `hsql-mysql` | `libmysqlclient` | See [MySQL driver for Haskell](http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hsql-mysql-1.7). | -| Java/JDBC | Connector/J | Native Driver | See [MySQL Connector/J 5.1 Developer Guide](https://dev.mysql.com/doc/connector-j/5.1/en/). | -| Lua | LuaSQL | `libmysqlclient` | See [LuaSQL](http://keplerproject.github.io/luasql/manual.html). | -| .NET/Mono | Connector/Net | Native Driver | See [MySQL Connector/Net Developer Guide](https://dev.mysql.com/doc/connector-net/en/). | -| Objective Caml | OBjective Caml MySQL Bindings | `libmysqlclient` | See [MySQL Bindings for Objective Caml](http://raevnos.pennmush.org/code/ocaml-mysql/). | -| Octave | Database bindings for GNU Octave | `libmysqlclient` | See [Database bindings for GNU Octave](http://octave.sourceforge.net/database/index.html). | -| ODBC | Connector/ODBC | `libmysqlclient` | See [MySQL Connector/ODBC Developer Guide](https://dev.mysql.com/doc/connector-odbc/en/). | -| Perl | `DBI`/`DBD::mysql` | `libmysqlclient` | See [Section 27.10, “MySQL Perl API”](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html). | -| | `Net::MySQL` | Native Driver | See [`Net::MySQL`](http://search.cpan.org/dist/Net-MySQL/MySQL.pm) at CPAN | -| PHP | `mysql`, `ext/mysql`interface (deprecated) | `libmysqlclient` | See [Original MySQL API](https://dev.mysql.com/doc/apis-php/en/apis-php-mysql.html). | -| | `mysqli`, `ext/mysqli`interface | `libmysqlclient` | See [MySQL Improved Extension](https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.html). | -| | `PDO_MYSQL` | `libmysqlclient` | See [MySQL Functions (PDO_MYSQL)](https://dev.mysql.com/doc/apis-php/en/apis-php-pdo-mysql.html). | -| | PDO mysqlnd | Native Driver | | -| Python | Connector/Python | Native Driver | See [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/). | -| Python | Connector/Python C Extension | `libmysqlclient` | See [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/). | -| | MySQLdb | `libmysqlclient` | See [Section 27.11, “MySQL Python API”](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html). | -| Ruby | MySQL/Ruby | `libmysqlclient` | Uses `libmysqlclient`. See [Section 27.12.1, “The MySQL/Ruby API”](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby-mysqlruby.html). | -| | Ruby/MySQL | Native Driver | See [Section 27.12.2, “The Ruby/MySQL API”](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby-rubymysql.html). | -| Scheme | `Myscsh` | `libmysqlclient` | See [`Myscsh`](https://github.com/aehrisch/myscsh). | -| SPL | `sql_mysql` | `libmysqlclient` | See [`sql_mysql` for SPL](http://www.clifford.at/spl/spldoc/sql_mysql.html). | -| Tcl | MySQLtcl | `libmysqlclient` | See [Section 27.13, “MySQL Tcl API”](https://dev.mysql.com/doc/refman/5.7/en/apis-tcl.html). | - -## TiDB 支持的连接器版本 - -| Connector | Connector version | -| ---------------- | ---------------------------- | -| Connector/C | 6.1.0 GA | -| Connector/C++ | 1.0.5 GA | -| Connector/J | 5.1.8 | -| Connector/Net | 6.9.9 GA | -| Connector/Net | 6.8.8 GA | -| Connector/ODBC | 5.1 | -| Connector/ODBC | 3.51 (Unicode not supported) | -| Connector/Python | 2.0 | -| Connector/Python | 1.2 | diff --git a/v3.0/reference/system-databases/information-schema.md b/v3.0/reference/system-databases/information-schema.md deleted file mode 100644 index c7343a2b0ee3..000000000000 --- a/v3.0/reference/system-databases/information-schema.md +++ /dev/null @@ -1,757 +0,0 @@ ---- -title: Information Schema -category: reference -aliases: ['/docs-cn/sql/information-schema/'] ---- - -# Information Schema - -为了和 MySQL 保持兼容，TiDB 支持很多 `INFORMATION_SCHEMA` 表，其中有不少表都支持相应的 `SHOW` 命令。查询 `INFORMATION_SCHEMA` 表也为表的连接操作提供了可能。 - -## ANALYZE_STATUS 表 - -`ANALYZE_STATUS` 表提供正在执行的收集统计信息的任务以及有限条历史任务记录。 - -{{< copyable "sql" >}} - -```sql -select * from `ANALYZE_STATUS`; -``` - -``` -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -| TABLE_SCHEMA | TABLE_NAME | PARTITION_NAME | JOB_INFO | PROCESSED_ROWS | START_TIME | STATE | -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -| test | t | | analyze index idx | 2 | 2019-06-21 19:51:14 | finished | -| test | t | | analyze columns | 2 | 2019-06-21 19:51:14 | finished | -| test | t1 | p0 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p3 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p1 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p2 | analyze columns | 1 | 2019-06-21 19:51:15 | finished | -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -6 rows in set -``` - -## CHARACTER_SETS 表 - -`CHARACTER_SETS` 表提供[字符集](/v3.0/reference/sql/character-set.md)相关的信息。TiDB 目前仅支持部分字符集。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM character_sets; -``` - -``` -+--------------------+----------------------+---------------+--------+ -| CHARACTER_SET_NAME | DEFAULT_COLLATE_NAME | DESCRIPTION | MAXLEN | -+--------------------+----------------------+---------------+--------+ -| utf8 | utf8_bin | UTF-8 Unicode | 3 | -| utf8mb4 | utf8mb4_bin | UTF-8 Unicode | 4 | -| ascii | ascii_bin | US ASCII | 1 | -| latin1 | latin1_bin | Latin1 | 1 | -| binary | binary | binary | 1 | -+--------------------+----------------------+---------------+--------+ -5 rows in set (0.00 sec) -``` - -## COLLATIONS 表 - -`COLLATIONS` 表提供了 `CHARACTER_SETS` 表中字符集对应的排序规则列表。TiDB 当前仅支持二进制排序规则，包含该表仅为兼容 MySQL。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM collations WHERE character_set_name='utf8mb4'; -``` - -``` -+------------------------+--------------------+------+------------+-------------+---------+ -| COLLATION_NAME | CHARACTER_SET_NAME | ID | IS_DEFAULT | IS_COMPILED | SORTLEN | -+------------------------+--------------------+------+------------+-------------+---------+ -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+------------------------+--------------------+------+------------+-------------+---------+ -26 rows in set (0.00 sec) -``` - -## COLLATION_CHARACTER_SET_APPLICABILITY 表 - -`COLLATION_CHARACTER_SET_APPLICABILITY` 表将排序规则映射至适用的字符集名称。和 `COLLATIONS` 表一样，包含此表也是为了兼容 MySQL。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM collation_character_set_applicability WHERE character_set_name='utf8mb4'; -``` - -``` -+------------------------+--------------------+ -| COLLATION_NAME | CHARACTER_SET_NAME | -+------------------------+--------------------+ -| utf8mb4_general_ci | utf8mb4 | -| utf8mb4_bin | utf8mb4 | -| utf8mb4_unicode_ci | utf8mb4 | -| utf8mb4_icelandic_ci | utf8mb4 | -| utf8mb4_latvian_ci | utf8mb4 | -| utf8mb4_romanian_ci | utf8mb4 | -| utf8mb4_slovenian_ci | utf8mb4 | -| utf8mb4_polish_ci | utf8mb4 | -| utf8mb4_estonian_ci | utf8mb4 | -| utf8mb4_spanish_ci | utf8mb4 | -| utf8mb4_swedish_ci | utf8mb4 | -| utf8mb4_turkish_ci | utf8mb4 | -| utf8mb4_czech_ci | utf8mb4 | -| utf8mb4_danish_ci | utf8mb4 | -| utf8mb4_lithuanian_ci | utf8mb4 | -| utf8mb4_slovak_ci | utf8mb4 | -| utf8mb4_spanish2_ci | utf8mb4 | -| utf8mb4_roman_ci | utf8mb4 | -| utf8mb4_persian_ci | utf8mb4 | -| utf8mb4_esperanto_ci | utf8mb4 | -| utf8mb4_hungarian_ci | utf8mb4 | -| utf8mb4_sinhala_ci | utf8mb4 | -| utf8mb4_german2_ci | utf8mb4 | -| utf8mb4_croatian_ci | utf8mb4 | -| utf8mb4_unicode_520_ci | utf8mb4 | -| utf8mb4_vietnamese_ci | utf8mb4 | -+------------------------+--------------------+ -26 rows in set (0.00 sec) -``` - -## COLUMNS 表 - -`COLUMNS` 表提供了表的所有列的信息。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.t1 (a int); -``` - -``` -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM information_schema.columns WHERE table_schema='test' AND TABLE_NAME='t1'; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: t1 - COLUMN_NAME: a - ORDINAL_POSITION: 1 - COLUMN_DEFAULT: NULL - IS_NULLABLE: YES - DATA_TYPE: int -CHARACTER_MAXIMUM_LENGTH: NULL - CHARACTER_OCTET_LENGTH: NULL - NUMERIC_PRECISION: 11 - NUMERIC_SCALE: 0 - DATETIME_PRECISION: NULL - CHARACTER_SET_NAME: NULL - COLLATION_NAME: NULL - COLUMN_TYPE: int(11) - COLUMN_KEY: - EXTRA: - PRIVILEGES: select,insert,update,references - COLUMN_COMMENT: - GENERATION_EXPRESSION: -1 row in set (0.01 sec) -``` - -对应的 `SHOW` 语句如下： - -{{< copyable "sql" >}} - -```sql -SHOW COLUMNS FROM t1 FROM test; -``` - -``` -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -## ENGINES 表 - -`ENGINES` 表提供了关于存储引擎的信息。从和 MySQL 兼容性上考虑，TiDB 会一直将 InnoDB 描述为唯一支持的引擎。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM engines; -``` - -``` -*************************** 1. row *************************** - ENGINE: InnoDB - SUPPORT: DEFAULT - COMMENT: Supports transactions, row-level locking, and foreign keys -TRANSACTIONS: YES - XA: YES - SAVEPOINTS: YES -1 row in set (0.00 sec) -``` - -## KEY_COLUMN_USAGE 表 - -`KEY_COLUMN_USAGE` 表描述了列的键约束，比如主键约束。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM key_column_usage WHERE table_schema='mysql' and table_name='user'; -``` - -``` -*************************** 1. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: Host - ORDINAL_POSITION: 1 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -*************************** 2. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: User - ORDINAL_POSITION: 2 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -2 rows in set (0.00 sec) -``` - -## PROCESSLIST 表 - -`PROCESSLIST` 和 `show processlist` 的功能一样，都是查看当前正在处理的请求。 - -`PROCESSLIST` 表会比 `show processlist` 多一个 `MEM` 列 从 v3.0.5 开始引入，`MEM` 是指正在处理的请求已使用的内存，单位是 byte。 - -```sql -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -| ID | USER | HOST | DB | COMMAND | TIME | STATE | INFO | MEM | -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -| 1 | root | ::1 | INFORMATION_SCHEMA | Query | 0 | 2 | select * from PROCESSLIST | 0 | -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -``` - -## SCHEMATA 表 - -`SCHEMATA` 表提供了关于数据库的信息。表中的数据与 `SHOW DATABASES` 语句的执行结果等价。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM schemata; -``` - -``` -+--------------+--------------------+----------------------------+------------------------+----------+ -| CATALOG_NAME | SCHEMA_NAME | DEFAULT_CHARACTER_SET_NAME | DEFAULT_COLLATION_NAME | SQL_PATH | -+--------------+--------------------+----------------------------+------------------------+----------+ -| def | INFORMATION_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | mynewdb | utf8mb4 | utf8mb4_bin | NULL | -| def | mysql | utf8mb4 | utf8mb4_bin | NULL | -| def | PERFORMANCE_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | test | utf8mb4 | utf8mb4_bin | NULL | -+--------------+--------------------+----------------------------+------------------------+----------+ -5 rows in set (0.00 sec) -``` - -## SESSION_VARIABLES 表 - -`SESSION_VARIABLES` 表提供了关于 session 变量的信息。表中的数据跟 `SHOW SESSION VARIABLES` 语句执行结果类似。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM session_variables LIMIT 10; -``` - -``` -+----------------------------------+----------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+----------------------------------+----------------------+ -| max_write_lock_count | 18446744073709551615 | -| server_id_bits | 32 | -| net_read_timeout | 30 | -| innodb_online_alter_log_max_size | 134217728 | -| innodb_optimize_fulltext_only | OFF | -| max_join_size | 18446744073709551615 | -| innodb_read_io_threads | 4 | -| session_track_gtids | OFF | -| have_ssl | DISABLED | -| max_binlog_cache_size | 18446744073709547520 | -+----------------------------------+----------------------+ -10 rows in set (0.00 sec) -``` - -## SLOW_QUERY 表 - -`SLOW_QUERY` 表中提供了慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，列名和慢日志中的字段名是一一对应。关于如何使用该表调查和改善慢查询请参考[慢查询日志文档](/v3.0/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 - -```sql -mysql> desc information_schema.slow_query; -+---------------+---------------------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+------+---------+-------+ -| Time | timestamp unsigned | YES | | NULL | | -| Txn_start_ts | bigint(20) unsigned | YES | | NULL | | -| User | varchar(64) | YES | | NULL | | -| Host | varchar(64) | YES | | NULL | | -| Conn_ID | bigint(20) unsigned | YES | | NULL | | -| Query_time | double unsigned | YES | | NULL | | -| Process_time | double unsigned | YES | | NULL | | -| Wait_time | double unsigned | YES | | NULL | | -| Backoff_time | double unsigned | YES | | NULL | | -| Request_count | bigint(20) unsigned | YES | | NULL | | -| Total_keys | bigint(20) unsigned | YES | | NULL | | -| Process_keys | bigint(20) unsigned | YES | | NULL | | -| DB | varchar(64) | YES | | NULL | | -| Index_ids | varchar(100) | YES | | NULL | | -| Is_internal | tinyint(1) unsigned | YES | | NULL | | -| Digest | varchar(64) | YES | | NULL | | -| Stats | varchar(512) | YES | | NULL | | -| Cop_proc_avg | double unsigned | YES | | NULL | | -| Cop_proc_p90 | double unsigned | YES | | NULL | | -| Cop_proc_max | double unsigned | YES | | NULL | | -| Cop_proc_addr | varchar(64) | YES | | NULL | | -| Cop_wait_avg | double unsigned | YES | | NULL | | -| Cop_wait_p90 | double unsigned | YES | | NULL | | -| Cop_wait_max | double unsigned | YES | | NULL | | -| Cop_wait_addr | varchar(64) | YES | | NULL | | -| Mem_max | bigint(20) unsigned | YES | | NULL | | -| Succ | tinyint(1) unsigned | YES | | NULL | | -| Query | longblob unsigned | YES | | NULL | | -+---------------+---------------------+------+------+---------+-------+ -``` - -## STATISTICS 表 - -`STATISTICS` 表提供了关于表索引的信息。 - -{{< copyable "sql" >}} - -```sql -desc statistics; -``` - -``` -+---------------|---------------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------|---------------------|------|------|---------|-------+ -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| TABLE_SCHEMA | varchar(64) | YES | | NULL | | -| TABLE_NAME | varchar(64) | YES | | NULL | | -| NON_UNIQUE | varchar(1) | YES | | NULL | | -| INDEX_SCHEMA | varchar(64) | YES | | NULL | | -| INDEX_NAME | varchar(64) | YES | | NULL | | -| SEQ_IN_INDEX | bigint(2) UNSIGNED | YES | | NULL | | -| COLUMN_NAME | varchar(21) | YES | | NULL | | -| COLLATION | varchar(1) | YES | | NULL | | -| CARDINALITY | bigint(21) UNSIGNED | YES | | NULL | | -| SUB_PART | bigint(3) UNSIGNED | YES | | NULL | | -| PACKED | varchar(10) | YES | | NULL | | -| NULLABLE | varchar(3) | YES | | NULL | | -| INDEX_TYPE | varchar(16) | YES | | NULL | | -| COMMENT | varchar(16) | YES | | NULL | | -| INDEX_COMMENT | varchar(1024) | YES | | NULL | | -+---------------|---------------------|------|------|---------|-------+ -``` - -下列语句是等价的： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM INFORMATION_SCHEMA.STATISTICS - WHERE table_name = 'tbl_name' - AND table_schema = 'db_name' -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEX - FROM tbl_name - FROM db_name -``` - -## TABLES 表 - -`TABLES` 表提供了数据库里面关于表的信息。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - TABLE_TYPE: BASE TABLE - ENGINE: InnoDB - VERSION: 10 - ROW_FORMAT: Compact - TABLE_ROWS: 0 - AVG_ROW_LENGTH: 0 - DATA_LENGTH: 0 -MAX_DATA_LENGTH: 0 - INDEX_LENGTH: 0 - DATA_FREE: 0 - AUTO_INCREMENT: 0 - CREATE_TIME: 2019-03-29 09:17:27 - UPDATE_TIME: NULL - CHECK_TIME: NULL -TABLE_COLLATION: utf8mb4_bin - CHECKSUM: NULL - CREATE_OPTIONS: - TABLE_COMMENT: - TIDB_TABLE_ID: 5 -1 row in set (0.00 sec) -``` - -以下操作是等价的： - -{{< copyable "sql" >}} - -```sql -SELECT table_name FROM INFORMATION_SCHEMA.TABLES - WHERE table_schema = 'db_name' - [AND table_name LIKE 'wild'] -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES - FROM db_name - [LIKE 'wild'] -``` - -## TABLE_CONSTRAINTS 表 - -`TABLE_CONSTRAINTS` 表记录了表的约束信息。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM table_constraints WHERE constraint_type='UNIQUE'; -``` - -``` -*************************** 1. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: name - TABLE_SCHEMA: mysql - TABLE_NAME: help_topic - CONSTRAINT_TYPE: UNIQUE -*************************** 2. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_meta - CONSTRAINT_TYPE: UNIQUE -*************************** 3. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_histograms - CONSTRAINT_TYPE: UNIQUE -*************************** 4. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_buckets - CONSTRAINT_TYPE: UNIQUE -*************************** 5. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range - CONSTRAINT_TYPE: UNIQUE -*************************** 6. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_done_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range_done - CONSTRAINT_TYPE: UNIQUE -6 rows in set (0.00 sec) -``` - -其中： - -* `CONSTRAINT_TYPE` 的取值可以是 `UNIQUE`，`PRIMARY KEY`，或者 `FOREIGN KEY`。 -* `UNIQUE` 和 `PRIMARY KEY` 信息与 `SHOW INDEX` 语句的执行结果类似。 - -## TIDB_HOT_REGIONS 表 - -`TIDB_HOT_REGIONS` 表提供了关于热点 REGION 的相关信息。 - -{{< copyable "sql" >}} - -```sql -desc TIDB_HOT_REGIONS; -``` - -``` -+----------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------+---------------------+------+-----+---------+-------+ -| TABLE_ID | bigint(21) unsigned | YES | | | | -| INDEX_ID | bigint(21) unsigned | YES | | | | -| DB_NAME | varchar(64) | YES | | | | -| TABLE_NAME | varchar(64) | YES | | | | -| INDEX_NAME | varchar(64) | YES | | | | -| TYPE | varchar(64) | YES | | | | -| MAX_HOT_DEGREE | bigint(21) unsigned | YES | | | | -| REGION_COUNT | bigint(21) unsigned | YES | | | | -| FLOW_BYTES | bigint(21) unsigned | YES | | | | -+----------------+---------------------+------+-----+---------+-------+ -``` - -## TIDB_INDEXES 表 - -`TIDB_INDEXES` 记录了所有表中的 INDEX 信息。 - -{{< copyable "sql" >}} - -```sql -desc TIDB_INDEXES; -``` - -``` -+---------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+-----+---------+-------+ -| TABLE_SCHEMA | varchar(64) | YES | | | | -| TABLE_NAME | varchar(64) | YES | | | | -| NON_UNIQUE | bigint(21) unsigned | YES | | | | -| KEY_NAME | varchar(64) | YES | | | | -| SEQ_IN_INDEX | bigint(21) unsigned | YES | | | | -| COLUMN_NAME | varchar(64) | YES | | | | -| SUB_PART | bigint(21) unsigned | YES | | | | -| INDEX_COMMENT | varchar(2048) | YES | | | | -| INDEX_ID | bigint(21) unsigned | YES | | | | -+---------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_REGION_PEERS 表 - -`TIKV_REGION_PEERS` 表提供了所有 REGION 的 peer 信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_REGION_PEERS; -``` - -``` -+--------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+---------------------+------+-----+---------+-------+ -| REGION_ID | bigint(21) unsigned | YES | | | | -| PEER_ID | bigint(21) unsigned | YES | | | | -| STORE_ID | bigint(21) unsigned | YES | | | | -| IS_LEARNER | tinyint(1) unsigned | YES | | | | -| IS_LEADER | tinyint(1) unsigned | YES | | | | -| STATUS | varchar(10) | YES | | | | -| DOWN_SECONDS | bigint(21) unsigned | YES | | | | -+--------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_REGION_STATUS 表 - -`TIKV_REGION_STATUS` 表提供了所有 REGION 的状态信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_REGION_STATUS; -``` - -``` -+------------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+------------------+---------------------+------+-----+---------+-------+ -| REGION_ID | bigint(21) unsigned | YES | | | | -| START_KEY | text | YES | | | | -| END_KEY | text | YES | | | | -| EPOCH_CONF_VER | bigint(21) unsigned | YES | | | | -| EPOCH_VERSION | bigint(21) unsigned | YES | | | | -| WRITTEN_BYTES | bigint(21) unsigned | YES | | | | -| READ_BYTES | bigint(21) unsigned | YES | | | | -| APPROXIMATE_SIZE | bigint(21) unsigned | YES | | | | -| APPROXIMATE_KEYS | bigint(21) unsigned | YES | | | | -+------------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_STORE_STATUS 表 - -`TIKV_STORE_STATUS` 表提供了所有 TiKV Store 的状态信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_STORE_STATUS; -``` - -``` -+-------------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------------------+---------------------+------+-----+---------+-------+ -| STORE_ID | bigint(21) unsigned | YES | | | | -| ADDRESS | varchar(64) | YES | | | | -| STORE_STATE | bigint(21) unsigned | YES | | | | -| STORE_STATE_NAME | varchar(64) | YES | | | | -| LABEL | json unsigned | YES | | | | -| VERSION | varchar(64) | YES | | | | -| CAPACITY | varchar(64) | YES | | | | -| AVAILABLE | varchar(64) | YES | | | | -| LEADER_COUNT | bigint(21) unsigned | YES | | | | -| LEADER_WEIGHT | bigint(21) unsigned | YES | | | | -| LEADER_SCORE | bigint(21) unsigned | YES | | | | -| LEADER_SIZE | bigint(21) unsigned | YES | | | | -| REGION_COUNT | bigint(21) unsigned | YES | | | | -| REGION_WEIGHT | bigint(21) unsigned | YES | | | | -| REGION_SCORE | bigint(21) unsigned | YES | | | | -| REGION_SIZE | bigint(21) unsigned | YES | | | | -| START_TS | datetime unsigned | YES | | | | -| LAST_HEARTBEAT_TS | datetime unsigned | YES | | | | -| UPTIME | varchar(64) | YES | | | | -+-------------------+---------------------+------+-----+---------+-------+ -``` - -## USER_PRIVILEGES 表 - -`USER_PRIVILEGES` 表提供了关于全局权限的信息。该表的数据根据 `mysql.user` 系统表生成。 - -{{< copyable "sql" >}} - -```sql -desc USER_PRIVILEGES; -``` - -``` -+----------------|--------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------|--------------|------|------|---------|-------+ -| GRANTEE | varchar(81) | YES | | NULL | | -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| PRIVILEGE_TYPE | varchar(64) | YES | | NULL | | -| IS_GRANTABLE | varchar(3) | YES | | NULL | | -+----------------|--------------|------|------|---------|-------+ -4 rows in set (0.00 sec) -``` - -## VIEWS 表 - -`VIEWS` 表提供了关于 SQL 视图的信息。 - -{{< copyable "sql" >}} - -```sql -create view test.v1 as select 1; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from views; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: v1 - VIEW_DEFINITION: select 1 - CHECK_OPTION: CASCADED - IS_UPDATABLE: NO - DEFINER: root@127.0.0.1 - SECURITY_TYPE: DEFINER -CHARACTER_SET_CLIENT: utf8 -COLLATION_CONNECTION: utf8_general_ci -1 row in set (0.00 sec) -``` - -## 不支持的 Information Schema 表 - -TiDB 包含以下 `INFORMATION_SCHEMA` 表，但仅会返回空行： - -* `COLUMN_PRIVILEGES` -* `EVENTS` -* `FILES` -* `GLOBAL_STATUS` -* `GLOBAL_VARIABLES` -* `OPTIMIZER_TRACE` -* `PARAMETERS` -* `PARTITIONS` -* `PLUGINS` -* `PROFILING` -* `REFERENTIAL_CONSTRAINTS` -* `ROUTINES` -* `SCHEMA_PRIVILEGES` -* `SESSION_STATUS` -* `TABLESPACES` -* `TABLE_PRIVILEGES` -* `TRIGGERS` diff --git a/v3.0/reference/system-databases/mysql.md b/v3.0/reference/system-databases/mysql.md deleted file mode 100644 index 617d0f3c900a..000000000000 --- a/v3.0/reference/system-databases/mysql.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: TiDB 系统表 -category: reference -aliases: ['/docs-cn/sql/system-database/'] ---- - -# TiDB 系统表 - -本文档主要介绍 TiDB 支持的系统表。 - -## 权限系统表 - -这些系统表里面包含了用户账户以及相应的授权信息： - -* `user` 用户账户，全局权限，以及其它一些非权限的列 -* `db` 数据库级别的权限 -* `tables_priv` 表级的权限 -* `columns_priv` 列级的权限 - -## 服务端帮助信息系统表 - -* `help_topic` 目前为空 - -## 统计信息相关系统表 - -* `stats_buckets` 统计信息的桶 -* `stats_histograms` 统计信息的直方图 -* `stats_meta` 表的元信息，比如总行数和修改数 - -## GC Worker 相关系统表 - -* `gc_delete_range` - -## 其它系统表 - -* `GLOBAL_VARIABLES` 全局系统变量表 -* `tidb` 用于 TiDB 在 bootstrap 的时候记录相关版本信息 diff --git a/v3.0/reference/tidb-binlog/binlog-slave-client.md b/v3.0/reference/tidb-binlog/binlog-slave-client.md deleted file mode 100644 index f5073c7beeef..000000000000 --- a/v3.0/reference/tidb-binlog/binlog-slave-client.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Binlog Slave Client 用户文档 -category: reference -aliases: ['/docs-cn/tools/binlog/binlog-slave-client/','/docs-cn/v3.0/reference/tools/tidb-binlog/binlog-slave-client/'] ---- - -# Binlog Slave Client 用户文档 - -目前 Drainer 提供了多种输出方式，包括 MySQL、TiDB、file 等。但是用户往往有一些自定义的需求，比如输出到 Elasticsearch、Hive 等，这些需求 Drainer 现在还没有实现，因此 Drainer 增加了输出到 Kafka 的功能，将 binlog 数据解析后按一定的格式再输出到 Kafka 中，用户编写代码从 Kafka 中读出数据再进行处理。 - -## 配置 Kafka Drainer - -修改 Drainer 的配置文件，设置输出为 Kafka，相关配置如下： - -``` -[syncer] -db-type = "kafka" - -[syncer.to] -# Kafka 地址 -kafka-addrs = "127.0.0.1:9092" -# Kafka 版本号 -kafka-version = "0.8.2.0" -``` - -## 自定义开发 - -### 数据格式 - -首先需要了解 Drainer 写入到 Kafka 中的数据格式： - -``` -// Column 保存列的数据，针对数据的类型，保存在对应的变量中 -message Column { - // 数据是否为 null - optional bool is_null = 1 [ default = false ]; - // 保存 int 类型的数据 - optional int64 int64_value = 2; - // 保存 uint、enum, set 类型的数据 - optional uint64 uint64_value = 3; - // 保存 float、double 类型的数据 - optional double double_value = 4; - // 保存 bit、blob、binary、json 类型的数据 - optional bytes bytes_value = 5; - // 保存 date、time、decimal、text、char 类型的数据 - optional string string_value = 6; -} - -// ColumnInfo 保存列的信息，包括列名、类型、是否为主键 -message ColumnInfo { - optional string name = 1 [ (gogoproto.nullable) = false ]; - // MySQL 中小写的列字段类型 - // https://dev.mysql.com/doc/refman/8.0/en/data-types.html - // numeric 类型：int bigint smallint tinyint float double decimal bit - // string 类型：text longtext mediumtext char tinytext varchar - // blob longblob mediumblob binary tinyblob varbinary - // enum set - // json 类型：json - optional string mysql_type = 2 [ (gogoproto.nullable) = false ]; - optional bool is_primary_key = 3 [ (gogoproto.nullable) = false ]; -} - -// Row 保存一行的具体数据 -message Row { repeated Column columns = 1; } - -// MutationType 表示 DML 的类型 -enum MutationType { - Insert = 0; - Update = 1; - Delete = 2; -} - -// Table 包含一个表的数据变更 -message Table { - optional string schema_name = 1; - optional string table_name = 2; - repeated ColumnInfo column_info = 3; - repeated TableMutation mutations = 4; -} - -// TableMutation 保存一行数据的变更 -message TableMutation { - required MutationType type = 1; - // 修改后的数据 - required Row row = 2; - // 修改前的数据，只对 Update MutationType 有效 - optional Row change_row = 3; -} - -// DMLData 保存一个事务所有的 DML 造成的数据变更 -message DMLData { - // `tables` 包含事务中所有表的数据变更 - repeated Table tables = 1; -} - -// DDLData 保存 DDL 的信息 -message DDLData { - // 当前使用的数据库 - optional string schema_name = 1; - // 相关表 - optional string table_name = 2; - // `ddl_query` 是原始的 DDL 语句 query - optional bytes ddl_query = 3; -} - -// BinlogType 为 Binlog 的类型，分为 DML 和 DDL -enum BinlogType { - DML = 0; // Has `dml_data` - DDL = 1; // Has `ddl_query` -} - -// Binlog 保存一个事务所有的变更，Kafka 中保存的数据为该结构数据序列化后的结果 -message Binlog { - optional BinlogType type = 1 [ (gogoproto.nullable) = false ]; - optional int64 commit_ts = 2 [ (gogoproto.nullable) = false ]; - optional DMLData dml_data = 3; - optional DDLData ddl_data = 4; -} -``` - -查看数据格式的具体定义，参见 [binlog.proto](https://github.com/pingcap/tidb-tools/blob/master/tidb-binlog/slave_binlog_proto/proto/binlog.proto)。 - -### Driver - -TiDB-Tools 项目提供了用于读取 Kafka 中 binlog 数据的 Driver，具有如下功能： - -* 读取 Kafka 的数据 -* 根据 commit ts 查找 binlog 在 kafka 中的储存位置 - -使用该 Driver 时，用户需要配置如下信息： - -* KafkaAddr：Kafka 集群的地址 -* CommitTS：从哪个 commit ts 开始读取 binlog -* Offset：从 Kafka 哪个 offset 开始读取，如果设置了 CommitTS 就不用配置该参数 -* ClusterID：TiDB 集群的 cluster ID -* Topic: Kafka Topic 名称，如果 Topic 名称为空，将会使用 drainer _obinlog 中的默认名称 - -用户以包的形式引用 Driver 的代码即可使用，可以参考 Driver 中提供的示例代码来学习如何使用 Driver 以及 binlog 数据的解析，目前提供了两个例子： - -* 使用该 Driver 将数据同步到 MySQL，该示例包含将 binlog 转化为 SQL 的具体方法 -* 使用该 Driver 将数据打印出来 - -Driver 项目地址：[Binlog Slave Driver](https://github.com/pingcap/tidb-tools/tree/master/tidb-binlog/driver)。 - -> **注意：** -> -> - 示例代码仅仅用于示范如何使用 Driver，如果需要用于生产环境需要优化代码。 -> - 目前仅提供了 golang 版本的 Driver 以及示例代码。如果需要使用其他语言，用户需要根据 binlog 的 proto 文件生成相应语言的代码文件，并自行开发程序读取 Kafka 中的 binlog 数据、解析数据、输出到下游。也欢迎用户优化 example 代码，以及提交其他语言的示例代码到 [TiDB-Tools](https://github.com/pingcap/tidb-tools)。 diff --git a/v3.0/reference/tidb-binlog/deploy.md b/v3.0/reference/tidb-binlog/deploy.md deleted file mode 100644 index 4d0ba1ca26ad..000000000000 --- a/v3.0/reference/tidb-binlog/deploy.md +++ /dev/null @@ -1,645 +0,0 @@ ---- -title: TiDB Binlog 集群部署 -category: reference -aliases: ['/docs-cn/tools/binlog/deploy/','/docs-cn/v3.0/how-to/deploy/tidb-binlog/','/docs-cn/v3.0/reference/tools/tidb-binlog/deploy/'] ---- - -# TiDB Binlog 集群部署 - -## 服务器要求 - -Pump 和 Drainer 均可部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台上。在开发、测试和生产环境下，对服务器硬件配置的要求和建议如下： - -| 服务 | 部署数量 | CPU | 磁盘 | 内存 | -| :-------- | :-------- | :--------| :--------------- | :------ | -| Pump | 3 | 8核+ | SSD, 200 GB+ | 16G | -| Drainer | 1 | 8核+ | SAS, 100 GB+ （如果输出 binlog 为本地文件，磁盘大小视保留数据天数而定） | 16G | - -## 使用 TiDB Ansible 部署 TiDB Binlog - -### 第 1 步：下载 TiDB Ansible - -1. 以 TiDB 用户登录中控机并进入 `/home/tidb` 目录。以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - - | TiDB Ansible 分支 | TiDB 版本 | 备注 | - | ---------------- | --------- | --- | - | release-3.0 | 3.0 版本 | 最新 3.0 稳定版本，可用于生产环境（建议）。 | - -2. 使用以下命令从 GitHub [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应分支，默认的文件夹名称为 `tidb-ansible`。 - - - 下载 3.0 版本： - - {{< copyable "shell-regular" >}} - - ```bash - git clone -b release-3.0 https://github.com/pingcap/tidb-ansible.git - ``` - -### 第 2 步：部署 Pump - -1. 修改 tidb-ansible/inventory.ini 文件 - - 1. 设置 `enable_binlog = True`，表示 TiDB 集群开启 binlog。 - - ```ini - ## binlog trigger - enable_binlog = True - ``` - - 2. 为 `pump_servers` 主机组添加部署机器 IP。 - - ```ini - ## Binlog Part - [pump_servers] - 172.16.10.72 - 172.16.10.73 - 172.16.10.74 - ``` - - 默认 Pump 保留 7 天数据，如需修改可修改 `tidb-ansible/conf/pump.yml`（TiDB 3.0.2 及之前版本中为 `tidb-ansible/conf/pump-cluster.yml`）文件中 `gc` 变量值，并取消注释。 - - {{< copyable "" >}} - - ```yaml - global: - # an integer value to control the expiry date of the binlog data, which indicates for how long (in days) the binlog data would be stored - # must be bigger than 0 - # gc: 7 - ``` - - 请确保部署目录有足够空间存储 binlog，详见[调整部署目录](/v3.0/how-to/deploy/orchestrated/ansible.md#调整部署目录)，也可为 Pump 设置单独的部署目录。 - - ```ini - ## Binlog Part - [pump_servers] - pump1 ansible_host=172.16.10.72 deploy_dir=/data1/pump - pump2 ansible_host=172.16.10.73 deploy_dir=/data2/pump - pump3 ansible_host=172.16.10.74 deploy_dir=/data3/pump - ``` - -2. 部署并启动含 Pump 组件的 TiDB 集群 - - 参照上文配置完 `inventory.ini` 文件后，从以下两种方式中选择一种进行部署。 - - **方式一**：在已有的 TiDB 集群上增加 Pump 组件，需按以下步骤逐步进行。 - - 1. 部署 pump_servers 和 node_exporters - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=pump -l ${pump1_ip},${pump2_ip},[${alias1_name},${alias2_name}] - ``` - - > **注意：** - > - > 以上命令中，逗号后不要加空格，否则会报错。 - - 2. 启动 pump_servers - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=pump - ``` - - 3. 更新并重启 tidb_servers - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=tidb - ``` - - 4. 更新监控信息 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - - **方式二**：从零开始部署含 Pump 组件的 TiDB 集群 - - 使用 Ansible 部署 TiDB 集群，方法参考 [使用 TiDB Ansible 部署 TiDB 集群](/v3.0/how-to/deploy/orchestrated/ansible.md)。 - -3. 查看 Pump 服务状态 - - 使用 binlogctl 查看 Pump 服务状态，pd-urls 参数请替换为集群 PD 地址，结果 State 为 online 表示 Pump 启动成功。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && - resources/bin/binlogctl -pd-urls=http://172.16.10.72:2379 -cmd pumps - ``` - - ``` - INFO[0000] pump: {NodeID: ip-172-16-10-72:8250, Addr: 172.16.10.72:8250, State: online, MaxCommitTS: 403051525690884099, UpdateTime: 2018-12-25 14:23:37 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-73:8250, Addr: 172.16.10.73:8250, State: online, MaxCommitTS: 403051525703991299, UpdateTime: 2018-12-25 14:23:36 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-74:8250, Addr: 172.16.10.74:8250, State: online, MaxCommitTS: 403051525717360643, UpdateTime: 2018-12-25 14:23:35 +0800 CST} - ``` - -### 第 3 步：部署 Drainer - -1. 获取 initial_commit_ts 的值 - - Drainer 初次启动时需要获取 initial_commit_ts 这个时间戳信息。 - - - 如果从最近的时间点开始同步，从 v3.0.6 开始 initial_commit_ts 使用 `-1` 即可。否则，需要使用 binlogctl 工具获取一个最新的时间戳，来作为 initial_commit_ts 的值。获取最新时间戳的方法如下： - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && - resources/bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd generate_meta - ``` - - ``` - INFO[0000] [pd] create pd client with endpoints [http://192.168.199.118:32379] - INFO[0000] [pd] leader switches to: http://192.168.199.118:32379, previous: - INFO[0000] [pd] init cluster id 6569368151110378289 - 2018/06/21 11:24:47 meta.go:117: [info] meta: &{CommitTS:400962745252184065} - ``` - - 该命令会输出 `meta: &{CommitTS:400962745252184065}`，其中 CommitTS 的值即所需的最新的时间戳。 - - - 如果下游为 MySQL 或 TiDB，为了保证数据的完整性，需要进行全量数据的备份与恢复。此时 initial_commit_ts 的值必须是全量备份的时间戳。 - - 如果使用 mydumper，可以在导出目录中找到 metadata 文件，其中的 `Pos` 字段值即全量备份的时间戳。metadata 文件示例如下： - - ``` - Started dump at: 2019-12-30 13:25:41 - SHOW MASTER STATUS: - Log: tidb-binlog - Pos: 413580274257362947 - GTID: - - Finished dump at: 2019-12-30 13:25:41 - ``` - -2. 修改 `tidb-ansible/inventory.ini` 文件 - - 为 `drainer_servers` 主机组添加部署机器 IP，initial_commit_ts 请设置为获取的 initial_commit_ts，仅用于 Drainer 第一次启动。 - - - 以下游为 MySQL 为例，别名为 `drainer_mysql`。 - - ```ini - [drainer_servers] - drainer_mysql ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - - - 以下游为 file 为例，别名为 `drainer_file`。 - - ```ini - [drainer_servers] - drainer_file ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - -3. 修改配置文件 - - - 以下游为 MySQL 为例 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible/conf && - cp drainer.toml drainer_mysql_drainer.toml && - vi drainer_mysql_drainer.toml - ``` - - > **注意：** - > - > 配置文件名命名规则为 `别名_drainer.toml`，否则部署时无法找到自定义配置文件。 - > 但是需要注意 v3.0.0，v3.0.1 的配置文件命名规则与其余版本略有不同，为 `别名_drainer-cluster.toml`。 - - db-type 设置为 "mysql"， 配置下游 MySQL 信息。 - - {{< copyable "" >}} - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "mysql" - - # the downstream MySQL protocol database - [syncer.to] - host = "172.16.10.72" - user = "root" - password = "123456" - port = 3306 - ``` - - - 以下游为增量备份文件为例 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible/conf && - cp drainer.toml drainer_file_drainer.toml && - vi drainer_file_drainer.toml - ``` - - db-type 设置为 "file"。 - - {{< copyable "" >}} - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "file" - - # Uncomment this if you want to use "file" as "db-type". - [syncer.to] - # default data directory: "{{ deploy_dir }}/data.drainer" - dir = "data.drainer" - ``` - -4. 部署 Drainer - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy_drainer.yml - ``` - -5. 启动 Drainer - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start_drainer.yml - ``` - -## 使用 Binary 部署 TiDB Binlog - -### 下载官方 Binary - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，Pump 和 Drainer 已经包含在 TiDB 的下载包中，其他版本需要单独下载 Pump 和 Drainer: - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-binlog-latest-linux-amd64.sha256 -``` - -### 使用样例 - -假设有三个 PD，一个 TiDB，另外有两台机器用于部署 Pump，一台机器用于部署 Drainer。各个节点信息如下： - -``` -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -Pump="192.168.0.11" -Pump="192.168.0.12" -Drainer="192.168.0.13" -``` - -下面以此为例，说明 Pump/Drainer 的使用。 - -1. 使用 binary 部署 Pump - - - Pump 命令行参数说明（以在 “192.168.0.11” 上部署为例） - - ```bash - Usage of Pump: - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.11:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.11:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置; - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里的配置。 - -data-dir string - Pump 数据存储位置路径 - -gc int - Pump 只保留多少天以内的数据 (默认 7) - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -node-id string - Pump 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -fake-binlog-interval int - Pump 节点生成 fake binlog 的频率 (默认 3，单位 秒) - ``` - - - Pump 配置文件（以在 “192.168.0.11” 上部署为例） - - ```toml - # Pump Configuration - - # Pump 绑定的地址 - addr = "192.168.0.11:8250" - - # Pump 对外提供服务的地址 - advertise-addr = "192.168.0.11:8250" - - # Pump 只保留多少天以内的数据 (默认 7) - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 2 - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/drainer.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/drainer-key.pem" - - # [storage] - # 设置为 true（默认值）来保证可靠性，确保 binlog 数据刷新到磁盘 - # sync-log = true - - # 当可用磁盘容量小于该设置值时，Pump 将停止写入数据，v3.0.1 后支持该功能 - # 42 MB -> 42000000, 42 mib -> 44040192 - # default: 10 gib - # stop-write-at-available-space = "10 gib" - - # Pump 内嵌的 LSM DB 设置，除非对该部分很了解，否则一般注解掉 - # [storage.kv] - # block-cache-capacity = 8388608 - # block-restart-interval = 16 - # block-size = 4096 - # compaction-L0-trigger = 8 - # compaction-table-size = 67108864 - # compaction-total-size = 536870912 - # compaction-total-size-multiplier = 8.0 - # write-buffer = 67108864 - # write-L0-pause-trigger = 24 - # write-L0-slowdown-trigger = 17 - ``` - - - 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -2. 使用 binary 部署 Drainer - - - Drainer 命令行参数说明（以在 “192.168.0.13” 上部署为例） - - ```bash - Usage of Drainer - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.13:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -cache-binlog-count int - 缓存中的 binlog 数目限制（默认 8） - 如果上游的单个 binlog 较大导致 Drainer 出现 OOM 时，可尝试调小该值减少内存使用 - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的配置 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql，支持 tidb、kafka、file) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则每个 binlog - 按顺序依次还原成单个事务进行同步（下游服务类型为 MySQL，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts（默认为 `0`，v3.0.6 开始默认值为 `-1`） - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - 该参数值为 -1 时，Drainer 会自动从 PD 获取一个最新的时间戳 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位：秒） - -node-id string - v3.0.2 后支持该功能，drainer 节点的唯一识别 ID，如果不指定程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -safe-mode - 是否开启安全模式使得下游 MySQL/TiDB 可被重复写入 - 即将 insert 语句换为 replace 语句，将 update 语句拆分为 delete + replace 语句 - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - - - Drainer 配置文件（以在 “192.168.0.13” 上部署为例） - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.13:8249") - addr = "192.168.0.13:8249" - - # Drainer 对外提供服务的地址 - advertise-addr = "192.168.0.13:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Drainer 从 Pump 获取 binlog 时对数据进行压缩，值可以为 "gzip"，如果不配置则不进行压缩 - # compressor = "gzip" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/pump.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/pump-key.pem" - - # Syncer Configuration - [syncer] - # 如果设置了该项，会使用该 sql-mode 解析 DDL 语句，此时如果下游是 MySQL 或 TiDB 则 - # 下游的 sql-mode 也会被设置为该值 - # sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" - - # 输出到下游数据库一个事务的 SQL 语句数量 (默认 20) - txn-batch = 20 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (默认 16) - worker-count = 16 - - # 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 MySQL, 该项设置为 False） - disable-dispatch = false - - # safe mode 会使写下游 MySQL/TiDB 可被重复写入 - # 会用 replace 替换 insert 语句，用 delete + replace 替换 update 语句 - safe-mode = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql"，"tidb"，"file"，"kafka" - db-type = "mysql" - - # 事务的 commit ts 若在该列表中，则该事务将被过滤，不会同步至下游，v3.0.2 后支持该功能 - ignore-txn-commit-ts = [] - - # db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - # 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。 - # 以 '~' 开始声明使用正则表达式 - - # replicate-do-db = ["~^b.*","s1"] - - # [syncer.relay] - # 保存 relay log 的目录，空值表示不开启。 - # 只有下游是 TiDB 或 MySQL 时该配置才生效。 - # log-dir = "" - # 每个文件的大小上限 - # max-file-size = 10485760 - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "log" - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "~^a.*" - - # 忽略同步某些表 - # [[syncer.ignore-table]] - # db-name = "test" - # tbl-name = "log" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.13" - user = "root" - password = "" - # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 - # encrypted_password 非空时 password 会被忽略 - encrypted_password = "" - port = 3306 - - [syncer.to.checkpoint] - # 当 checkpoint type 是 mysql 或 tidb 时可以开启该选项，以改变保存 checkpoint 的数据库 - # schema = "tidb_binlog" - # v3.0.6 开始支持配置 checkpoint 的保存类型。 - # 目前只支持 mysql 或者 tidb 类型。可以去掉注释来控制 checkpoint 保存的位置。 - # db-type 默认的 checkpoint 保存方式是: - # mysql/tidb -> 对应的下游 mysql/tidb - # file/kafka -> file in `data-dir` - # type = "mysql" - # host = "127.0.0.1" - # user = "root" - # password = "" - # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 - # encrypted_password 非空时 password 会被忽略 - # encrypted_password = "" - # port = 3306 - - # db-type 设置为 file 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - - # db-type 设置为 kafka 时，Kafka 相关配置 - # [syncer.to] - # kafka-addrs 和 zookeeper-addrs 只需要一个，两者都有时程序会优先用 zookeeper 中的 kafka 地址 - # zookeeper-addrs = "127.0.0.1:2181" - # kafka-addrs = "127.0.0.1:9092" - # kafka-version = "0.8.2.0" - # kafka-max-messages = 1024 - - # 保存 binlog 数据的 Kafka 集群的 topic 名称，默认值为 _obinlog - # 如果运行多个 Drainer 同步数据到同一个 Kafka 集群，每个 Drainer 的 topic-name 需要设置不同的名称 - # topic-name = "" - - ``` - - - 启动示例 - - > **注意：** - > - > 如果下游为 MySQL/TiDB，为了保证数据的完整性，在 Drainer 初次启动前需要获取 `initial-commit-ts` 的值，并进行全量数据的备份与恢复。详细信息参见[部署 Drainer](#第-3-步部署-drainer)。 - - 初次启动时使用参数 `initial-commit-ts`， 命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml -initial-commit-ts {initial-commit-ts} - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -> **注意：** -> -> - 在运行 TiDB 时，需要保证至少一个 Pump 正常运行。 -> - 通过给 TiDB 增加启动参数 `enable-binlog` 来开启 binlog 服务。尽量保证同一集群的所有 TiDB 都开启了 binlog 服务，否则在同步数据时可能会导致上下游数据不一致。如果要临时运行一个不开启 binlog 服务的 TiDB 实例，需要在 TiDB 的配置文件中设置 `run_ddl= false`。 -> - Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 -> - 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取**快照时间戳**，然后导入全量备份，最后启动 Drainer 从对应的快照时间戳开始同步增量数据。 -> - 下游使用 MySQL 或 TiDB 时应当保证上下游数据库的 sql_mode 具有一致性，即下游数据库同步每条 SQL 语句时的 sql_mode 应当与上游数据库执行该条 SQL 语句时的 sql_mode 保持一致。可以在上下游分别执行 `select @@sql_mode;` 进行查询和比对。 -> - 如果存在上游 TiDB 能运行但下游 MySQL 不支持的 DDL 语句时（例如下游 MySQL 使用 InnoDB 引擎时同步语句 `CREATE TABLE t1(a INT) ROW_FORMAT=FIXED;`），Drainer 也会同步失败，此时可以在 Drainer 配置中跳过该事务，同时在下游手动执行兼容的语句，详见[跳过事务](/v3.0/reference/tidb-binlog/faq.md#同步时出现上游数据库支持但是下游数据库执行会出错的-ddl应该怎么办)。 diff --git a/v3.0/reference/tidb-binlog/faq.md b/v3.0/reference/tidb-binlog/faq.md deleted file mode 100644 index 84703ea9595a..000000000000 --- a/v3.0/reference/tidb-binlog/faq.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: TiDB Binlog 常见问题 -category: FAQ -aliases: ['/docs-cn/v3.0/faq/tidb-binlog/','/docs-cn/v3.0/reference/tools/tidb-binlog/faq/'] ---- - -# TiDB Binlog 常见问题 - -本文介绍 TiDB Binlog 使用过程中的常见问题及解决方案。 - -## 开启 binog 对 TiDB 的性能有何影响？ - -- 对于查询无影响。 - -- 对于有写入或更新数据的事务有一点性能影响。延迟上，在 Prewrite 阶段要并发写一条 p-binlog 成功后才可以提交事务，一般写 binlog 比 KV Prewrite 快，所以不会增加延迟。可以在 Pump 的监控面板看到写 binlog 的响应时间。 - -## Drainer 同步下游 TiDB/MySQL 的帐号需要哪些权限？ - -Drainer 同步帐号需要有如下权限： - -* Insert -* Update -* Delete -* Create -* Drop -* Alter -* Execute -* Index -* Select - -## Pump 磁盘快满了怎么办？ - -确认 GC 正常： - -- 确认 pump 监控面板 **gc_tso** 时间是否与配置一致，版本 <= v3.0.0 的 pump 会保证非 `offline` 状态 Drainer 消费了数据才会 gc，如果有不再使用的 drainer 需要使用 binlogctl 下线。 - -如 gc 正常以下调整可以降低单个 pump 需要的空间大小： - -- 调整 pump **GC** 参数减少保留数据天数。 -- 添加 pump 结点。 - -## Drainer 同步中断怎么办？ - -使用以下 binlogctl 命令查看 Pump 状态是否正常，以及是否全部非 `offline` 状态的 Pump 都在正常运行。 - -{{< copyable "shell-regular" >}} - -```bash -binlogctl -cmd pumps -``` - -查看 Drainer 监控与日志是否有对应报错，根据具体问题进行处理。 - -## Drainer 同步下游 TiDB/MySQL 慢怎么办？ - -特别关注以下监控项： - -- 通过 Drainer 监控 **drainer event**，可以看到 Drainer 当前每秒同步 Insert/Update/Delete 事件到下游的速度。 -- 通过 Drainer 监控 **sql query time**，可以看到 Drainer 在下游执行 SQL 的响应时间。 - -同步慢的可能原因与解决方案： - -- 同步的数据库包含没有主键或者唯一索引的表，需要给表加上主键。 -- Drainer 与下游之间延迟大，可以调大 Drainer `worker-count` 参数（跨机房同步建议将 Drainer 部署在下游）。 -- 下游负载不高，可以尝试调大 Drainer `worker-count` 参数。 - -## 假如有一个 Pump crash 了会怎样？ - -Drainer 会因为获取不到这个 Pump 的数据没法同步数据到下游。如果这个 Pump 能恢复，Drainer 就能恢复同步。 - -如果 Pump 没法恢复，可采用以下方式进行处理： - -1. 使用 [binlogctl 将该 Pump 状态修改为 `offline`](/v3.0/reference/tidb-binlog/maintain.md)（丢失这个 Pump 的数据） -2. Drainer 获取到的数据会丢失这个 Pump 上的数据，下游跟上游数据会不一致，需要重新做全量 + 增量同步。具体步骤如下： - 1. 停止当前 Drainer。 - 2. 上游做全量备份。 - 3. 清理掉下游数据，包括 checkpoint 表 `tidb_binlog.checkpoint`。 - 4. 使用上游的全量备份恢复下游数据。 - 5. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 什么是 checkpoint？ - -Checkpoint 记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 -Drainer 日志 `["write save point"] [ts=411222863322546177]` 表示保存对应时间戳的 checkpoint。 - -下游类型不同，checkpoint 的保存方式也不同： - -- 下游 MySQL/TiDB 保存在 `tidb_binlog.checkpoint` 表。 -- 下游 kafka/file 保存在对应配置目录里的文件。 - -因为 kafka/file 的数据内容包含了 commit-ts，所以如果 checkpoint 丢失，可以消费下游最新的一条数据看写到下游数据的最新 commit-ts。 - -Drainer 启动的时候会去读取 checkpoint，如果读取不到，就会使用配置的 `initial-commit-ts` 做为初次启动开始的同步时间点。 - -## Drainer 机器发生故障，下游数据还在，如何在新机器上重新部署 Drainer？ - -如果下游数据还在，只要保证能从对应 checkpoint 接着同步即可。 - -假如 checkpoint 还在，可采用以下方式进行处理： - -1. 部署新的 Drainer 并启动即可（参考 checkpoint 介绍，Drainer 可以读取 checkpoint 接着同步）。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/v3.0/reference/tidb-binlog/maintain.md)。 - -假如 checkpoint 不在，可以如下处理： - -1. 获取之前 Drainer 的 checkpoint `commit-ts`，做为新部署 Drainer 的 `initial-commit-ts` 配置来部署新的 Drainer。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/v3.0/reference/tidb-binlog/maintain.md)。 - -## 如何用全量 + binlog 备份文件来恢复一个集群？ - -1. 清理集群数据并使用全部备份恢复数据。 -2. 使用 reparo 设置 `start-tso` = {全量备份文件快照时间戳+1}，`end-ts` = 0（或者指定时间点），恢复到备份文件最新的数据。 - -## 主从同步开启 `ignore-error` 触发 critical error 后如何重新部署？ - -TiDB 配置开启 `ignore-error` 写 binlog 失败后触发 critical error 告警，后续都不会再写 binlog，所以会有 binlog 数据丢失。如果要恢复同步，需要如下处理： - -1. 停止当前 Drainer。 -2. 重启触发 critical error 的 `tidb-server` 实例重新开始写 binlog（触发 critical error 后不会再写 binlog 到 pump）。 -3. 上游做全量备份。 -4. 清理掉下游数据包括 checkpoint 表 `tidb_binlog.checkpoint`。 -5. 使用上游的全量备份恢复下游。 -6. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 同步时出现上游数据库支持但是下游数据库执行会出错的 DDL，应该怎么办？ - -1. 查看 drainer.log 日志，查找 `exec failed` 找到 Drainer 退出前最后一条执行失败的 DDL。 -2. 将 DDL 改为下游兼容支持的版本，在下游数据库中手动执行。 -3. 查看 drainer.log 日志，查找执行失败的 DDL 语句，可以查询到该 DDL 的 commit-ts。 -4. 编辑 `drainer.toml` 配置文件，在 `ignore-txn-commit-ts` 项中添加该 commit-ts，重启 Drainer。 - -在绝大部分情况下，TiDB 和 MySQL 的语句都是兼容的。用户需要注意的是上下游的 `sql_mode` 应当保持一致。 - -## 在什么情况下暂停和下线 Pump/Drainer？ - -首先需要通过以下内容来了解 Pump/Drainer 的状态定义和启动、退出的流程。 - -暂停主要针对临时需要停止服务的场景，例如： - -- 版本升级：停止进程后使用新的 binary 启动服务。 -- 服务器维护：需要对服务器进行停机维护。退出进程，等维护完成后重启服务。 - -下线主要针对永久（或长时间）不再使用该服务的场景，例如： - -- Pump 缩容：不再需要那么多 Pump 服务了，所以下线部分服务。 -- 同步任务取消：不再需要将数据同步到某个下游，所以下线对应的 Drainer。 -- 服务器迁移：需要将服务迁移到其他服务器。下线服务，在新的服务器上重新部署。 - -## 可以通过哪些方式暂停 Pump/Drainer？ - -- 直接 kill 进程。 - - >**注意：** - > - > 不能使用 `kill -9` 命令，否则 Pump/Drainer 无法对信号进行处理。 - -- 如果 Pump/Drainer 运行在前台，则可以通过按下 Ctrl+C 来暂停。 -- 使用 binlogctl 的 `pause-pump` 或 `pause-drainer` 命令。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来下线 Pump/Drainer 服务吗？ - -不可以。使用 `update-pump`/`update-drainer` 命令会直接修改 PD 中保存的状态信息，并且不会通知 Pump/Drainer 做相应的操作。使用不当时，可能会干扰数据同步，某些情况下还可能会造成**数据不一致**的严重后果。例如： - -- 当 Pump 正常运行或者处于暂停状态时，如果使用 `update-pump` 将该 Pump 设置为 `offline`，那么 Drainer 会放弃获取处于 `offline` 状态的 Pump 的 binlog 数据，导致该 Pump 最新的 binlog 数据没有同步到 Drainer，造成上下游数据不一致。 -- 当 Drainer 正常运行时，使用 `update-drainer` 命令将该 Drainer 设置为 `offline`。如果这时启动一个 Pump 节点，Pump 只会通知 `online` 状态的 Drainer，导致该 Drainer 没有及时获取到该 Pump 的 binlog 数据，造成上下游数据不一致。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来暂停 Pump/Drainer 服务吗？ - -不可以。`update-pump`/`update-drainer` 命令直接修改 PD 中保存的状态信息。执行这个命令并不会通知 Pump/Drainer 做相应的操作，**而且使用不当会使数据同步中断，甚至造成数据丢失。** - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `paused`？ - -在某些异常情况下，Pump 没有正确维护自己的状态，实际上状态应该为 `paused`。这时可以使用 `update-pump` 对状态进行修正，例如： - -- Pump 异常退出（可能由 panic 或者误操作执行 `kill -9` 命令直接 kill 掉进程导致），Pump 保存在 PD 中的状态仍然为 `online`。如果暂时不需要重启 Pump 恢复服务，可以使用 `update-pump` 把该 Pump 状态设置为 `paused`，避免对 TiDB 写 binlog 和 Drainer 获取 binlog 造成干扰。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `paused`？ - -在某些异常情况下，Drainer 没有正确维护自己的状态，，对数据同步造成了影响，实际上状态应该为 `paused`。这时可以使用 `update-drainer` 对状态进行修正，例如： - -- Drainer 异常退出（出现 panic 直接退出进程，或者误操作执行 `kill -9` 命令直接 kill 掉进程），Drainer 保存在 PD 中的状态仍然为 `online`。当 Pump 启动时无法正常通知该 Drainer（报错 `notify drainer ...`），导致 Pump 无法正常运行。这个时候可以使用 `update-drainer` 将 Drainer 状态更新为 `paused`，再启动 Pump。 - -## 可以通过哪些方式下线 Pump/Drainer？ - -目前只可以使用 binlogctl 的 `offline-pump` 和 `offline-drainer` 命令来下线 Pump 和 Drainer。 - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `offline`? - -> **警告：** -> -> 仅在可以容忍 binlog **数据丢失、上下游数据不一致**或者确认不再需要使用该 Pump 存储的 binlog 数据的情况下，才能使用 `update-pump` 修改 Pump 状态为 `offline`。 - -可以使用 `update-pump` 修改 Pump 状态为 `offline` 的情况有： - -- 在某些情况下，Pump 异常退出进程，且无法恢复服务，同步就会中断。如果希望恢复同步且可以容忍部分 binlog 数据丢失，可以使用 `update-pump` 命令将该 Pump 状态设置为 `offline`，则 Drainer 会放弃拉取该 Pump 的 binlog 然后继续同步数据。 -- 有从历史任务遗留下来且不再使用的 Pump 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-pump` 将该 Pump 设置为 `offline`。 - -在其他情况下一定要使用 `offline-pump` 命令让 Pump 走正常的下线处理流程。 - -## Pump 进程已经退出，且状态为 `paused`，现在不想使用这个 Pump 节点了，能否用 binlogctl 的 `update-pump` 命令设置节点状态为 `offline`？ - -Pump 以 `paused` 状态退出进程时，不保证所有 binlog 数据被下游 Drainer 消费。所以这样做会有上下游数据不一致的风险。正确的做法是重新启动 Pump，然后使用 `offline-pump` 下线该 Pump。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `offline`？ - -- 有从历史任务遗留下来且不再使用的 Drainer 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-drainer` 将该 Drainer 设置为 `offline`。 - -## 可以使用 `change pump`、`change drainer` 等 SQL 操作来暂停或者下线 Pump/Drainer 服务吗？ - -目前还不支持。这种 SQL 操作会直接修改 PD 中保存的状态，在功能上等同于使用 binlogctl 的 `update-pump`、`update-drainer` 命令。如果需要暂停或者下线，仍然要使用 binlogctl。 diff --git a/v3.0/reference/tidb-binlog/glossary.md b/v3.0/reference/tidb-binlog/glossary.md deleted file mode 100644 index 473cfa7fece0..000000000000 --- a/v3.0/reference/tidb-binlog/glossary.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB Binlog 术语表 -summary: 学习 TiDB Binlog 相关术语 -category: glossary ---- - -# TiDB Binlog 术语表 - -本文档介绍 TiDB Binlog 相关术语。 - -## Binlog - -在 TiDB Binlog 中，Binlog 通常 TiDB 写的 Binlog 数据，注意 TiDB Binlog 的格式跟 MySQL 不同，也指 Drainer 写到 Kafka 或者文件的 Binlog 数据，但他们的格式不一样。 - -## Binlog event - -TiDB 写的 DML Binlog 有 3 种 event, 分别是 Insert, Update, Delete, Drainer 监控面板 可以看到对应同步数据不同 event 的个数。 - -## Checkpoint - -Checkpoint 指保存的断点信息，记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 - -## Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在 Drainer 启动的前 5 分钟会自动启动 Safe mode，另外也可以配置文件中通过 `safe-mode` 参数手动开启。 - -该配置仅对下游是 MySQL/TiDB 有效。 diff --git a/v3.0/reference/tidb-binlog/maintain.md b/v3.0/reference/tidb-binlog/maintain.md deleted file mode 100644 index f214fcd9e333..000000000000 --- a/v3.0/reference/tidb-binlog/maintain.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: TiDB Binlog 集群运维 -category: reference -aliases: ['/docs-cn/v3.0/how-to/maintain/tidb-binlog/','/docs-cn/v3.0/reference/tools/tidb-binlog/maintain/'] ---- - -# TiDB Binlog 集群运维 - -本文首先介绍 Pump 和 Drainer 的状态及启动、退出的内部处理流程，然后说明如何通过 binlogctl 工具或者直接在 TiDB 执行 SQL 操作来管理 binlog 集群，最后的 FAQ 部分会介绍一些常见问题以及处理方法。 - -## Pump/Drainer 的状态 - -Pump/Drainer 中状态的定义： - -* online：正常运行中 -* pausing：暂停中 -* paused：已暂停 -* closing：下线中 -* offline：已下线 - -这些状态由 Pump/Drainer 服务自身进行维护，并定时将状态信息更新到 PD 中。 - -## Pump/Drainer 的启动、退出流程 - -### Pump - -* 启动：Pump 启动时会通知所有 online 状态的 Drainer，如果通知成功，则 Pump 将状态设置为 online，否则 Pump 将报错，然后将状态设置为 paused 并退出进程。 -* 退出：Pump 进程正常退出前要选择进入暂停或者下线状态；非正常退出（kill -9、进程 panic、宕机）都依然保持 online 状态。 - - * 暂停：使用 kill（非 kill -9）、Ctrl+C 或者使用 binlogctl 的 pause-pump 命令都可以暂停 Pump。接收到暂停指令后，Pump 会变更状态为 pausing，并停止接受 binlog 的写请求，也停止向 Drainer 提供 binlog 数据。安全退出所有线程后，更新状态为 paused 然后退出进程。 - * 下线：仅在使用 binlogctl 的 offline-pump 命令的情况下才会下线 Pump。接收到下线指令后，Pump 会变更状态为 closing，并停止接受 binlog 的写请求。Pump 继续向 Drainer 提供 binlog，等待所有 binlog 数据都被 Drainer 消费后再将状态设置为 offline 并退出进程。 - -### Drainer - -* 启动：Drainer 启动时将状态设置为 online，并尝试从所有非 offline 状态的 Pump 获取 binlog，如果获取 binlog 失败，会不断尝试重新获取。 -* 退出：Drainer 进程正常退出前要选择进入暂停或者下线状态；非正常退出（kill -9 、进程 panic、宕机）都依然保持 online 状态。 - - * 暂停：使用 kill（非 kill -9）、Ctrl+C 或者使用 binlogctl 的 pause-drainer 命令都可以暂停 Drainer。接收到指令后，Drainer 会变更状态为 pausing，并停止从 Pump 获取 binlog。安全退出所有线程后，更新状态为 paused 然后退出进程。 - * 下线：仅在使用 binlogctl 的 offline-drainer 命令的情况下才会下线 Drainer。接收到下线指令后，Drainer 变更状态为 closing，并停止从 Pump 获取 binlog。安全退出所有线程后，更新状态为 offline 然后退出进程。 - -关于 Pump/Drainer 暂停、下线、状态查询、状态修改等具体的操作方法，参考如下 binlogctl 工具的使用方法介绍。 - -## binlogctl 工具 - -支持如下这些功能： - -* 查看 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer -* Pump/Drainer 异常状态处理 - -使用 binlogctl 的场景： - -* 同步出现故障/检查运行情况，需要查看 Pump/Drainer 的状态 -* 维护集群，需要暂停/下线 Pump/Drainer -* Pump/Drainer 异常退出，状态没有更新，或者状态不符合预期，对业务造成影响 - -binlogctl 下载链接： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，binlogctl 已经包含在 TiDB 的下载包中，其他版本需要单独下载 binlogctl: - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -binlogctl 使用说明： - -命令行参数： - -```bash -Usage of binlogctl: --V -输出 binlogctl 的版本信息 --cmd string - 命令模式，包括 "generate_meta"（已废弃）, "pumps", "drainers", "update-pump" ,"update-drainer", "pause-pump", "pause-drainer", "offline-pump", "offline-drainer" --data-dir string - 保存 Drainer 的 checkpoint 的文件的路径 (默认 "binlog_position")（已废弃） --node-id string - Pump/Drainer 的 ID --pd-urls string - PD 的地址，如果有多个，则用"," 连接 (默认 "http://127.0.0.1:2379") --ssl-ca string - SSL CAs 文件的路径 --ssl-cert string - PEM 格式的 X509 认证文件的路径 --ssl-key string - PEM 格式的 X509 key 文件的路径 --time-zone string - 如果设置时区，在 "generate_meta" 模式下会打印出获取到的 tso 对应的时间。例如 "Asia/Shanghai" 为 CST 时区，"Local" 为本地时区 --show-offline-nodes - 在用 -cmd pumps 或 -cmd drainers 时使用，这两个命令默认不显示 offline 的节点，仅当明确指定 -show-offline-nodes 时会显示 -``` - -命令示例： - -- 查询所有的 Pump/Drainer 的状态： - - 设置 `cmd` 为 `pumps` 或者 `drainers` 来查看所有 Pump 或者 Drainer 的状态。例如： - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pumps - ``` - - ``` - [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=pump] [node="{NodeID: 1.1.1.1:8250, Addr: pump:8250, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"] - ``` - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd drainers - ``` - - ``` - [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=drainer] [node="{NodeID: 1.1.1.1:8249, Addr: 1.1.1.1:8249, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"] - ``` - -- 暂停/下线 Pump/Drainer - - binlogctl 提供以下命令暂停/下线服务： - - | cmd | 说明 | 示例 | - | --------------- | ------------- | ------------------------------------------------------------------------------------------------| - | pause-pump | 暂停 Pump | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-pump -node-id ip-127-0-0-1:8250` | - | pause-drainer | 暂停 Drainer | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-drainer -node-id ip-127-0-0-1:8249` | - | offline-pump | 下线 Pump | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-pump -node-id ip-127-0-0-1:8250` | - | offline-drainer | 下线 Drainer | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-drainer -node-id ip-127-0-0-1:8249` | - - binlogctl 会发送 HTTP 请求给 Pump/Drainer，Pump/Drainer 收到命令后会主动执行对应的退出流程。 - -- 异常情况下修改 Pump/Drainer 的状态 - - 在服务正常运行以及符合流程的暂停、下线过程中，Pump/Drainer 的状态都是可以正确的。但是在一些异常情况下 Pump/Drainer 无法正确维护自己的状态，可能会影响数据同步任务，在这种情况下需要使用 binlogctl 修复状态信息。 - - 设置 `cmd` 为 `update-pump` 或者 `update-drainer` 来更新 Pump 或者 Drainer 的状态。Pump 和 Drainer 的状态可以为 paused 或者 offline。例如： - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd update-pump -node-id ip-127-0-0-1:8250 -state paused - ``` - - > **注意：** - > - > Pump/Drainer 在正常运行过程中会定期在 PD 中更新自己的状态，而这条命令是直接去修改 Pump/Drainer 保存在 PD 中的状态，所以在 Pump/Drainer 服务正常的情况下使用这些命令是没有意义的。仅在 Pump/Drainer 服务异常的情况下使用，具体哪些场景下使用这条命令可以参考 FAQ。 - -## 使用 TiDB SQL 管理 Pump/Drainer - -要查看和管理 binlog 相关的状态，可在 TiDB 中执行相应的 SQL 语句。 - -- 查看 TiDB 是否开启 binlog - - {{< copyable "sql" >}} - - ```sql - show variables like "log_bin"; - ``` - - ``` - +---------------+-------+ - | Variable_name | Value | - +---------------+-------+ - | log_bin | ON | - +---------------+-------+ - ``` - - 值为 `ON` 时表示 TiDB 开启了 binlog。 - -- 查看 Pump/Drainer 状态 - - {{< copyable "sql" >}} - - ```sql - show pump status; - ``` - - ``` - +--------|----------------|--------|--------------------|---------------------| - | NodeID | Address | State | Max_Commit_Ts | Update_Time | - +--------|----------------|--------|--------------------|---------------------| - | pump1 | 127.0.0.1:8250 | Online | 408553768673342237 | 2019-05-01 00:00:01 | - +--------|----------------|--------|--------------------|---------------------| - | pump2 | 127.0.0.2:8250 | Online | 408553768673342335 | 2019-05-01 00:00:02 | - +--------|----------------|--------|--------------------|---------------------| - ``` - - {{< copyable "sql" >}} - - ```sql - show drainer status; - ``` - - ``` - +----------|----------------|--------|--------------------|---------------------| - | NodeID | Address | State | Max_Commit_Ts | Update_Time | - +----------|----------------|--------|--------------------|---------------------| - | drainer1 | 127.0.0.3:8249 | Online | 408553768673342532 | 2019-05-01 00:00:03 | - +----------|----------------|--------|--------------------|---------------------| - | drainer2 | 127.0.0.4:8249 | Online | 408553768673345531 | 2019-05-01 00:00:04 | - +----------|----------------|--------|--------------------|---------------------| - ``` - -- 异常情况下修改 Pump/Drainer 状态 - - {{< copyable "sql" >}} - - ```sql - change pump to node_state ='paused' for node_id 'pump1'; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - change drainer to node_state ='paused' for node_id 'drainer1'; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - 该 SQL 的功能和 binlogctl 中的 update-pump 和 update-drainer 命令的功能一样，因此也只有在 Pump/Drainer 异常的情况下使用。 - -> **注意：** -> -> 1. 查看 binlog 开启状态以及 Pump/Drainer 状态的功能在 TiDB v2.1.7 及以上版本中支持。 -> 2. 修改 Pump/Drainer 状态的功能在 TiDB v3.0.0-rc.1 及以上版本中支持。该功能只修改 PD 中存储的 Pump/Drainer 状态，如果需要暂停/下线节点，仍然需要使用 `binlogctl`。 diff --git a/v3.0/reference/tidb-binlog/monitor.md b/v3.0/reference/tidb-binlog/monitor.md deleted file mode 100644 index 05b06a6ad53b..000000000000 --- a/v3.0/reference/tidb-binlog/monitor.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: TiDB Binlog 集群监控 -category: reference -aliases: ['/docs-cn/v3.0/how-to/monitor/tidb-binlog-monitor/','/docs-cn/v3.0/reference/tools/tidb-binlog/monitor/','/docs-cn/v3.0/how-to/monitor/tidb-binlog/'] ---- - -# TiDB Binlog 集群监控 - -使用 Ansible 成功部署 TiDB Binlog 集群后，可以进入 Grafana Web 界面（默认地址: ，默认账号：admin，密码：admin）查看 Pump 和 Drainer 的运行状态。 - -## 监控指标 - -### Pump - -| metric 名称 | 说明 | -|:----|:------------| -| Storage Size | 记录磁盘的总空间大小 (capacity)，以及可用磁盘空间大小 (available) | -| Metadata | 记录每个 Pump 的可删除 binlog 的最大 tso (gc_tso)，以及保存的 binlog 的最大的 commit tso (max_commit_tso)。 | -| Write Binlog QPS by Instance | 每个 Pump 接收到的写 binlog 请求的 QPS | -| Write Binlog Latency | 记录每个 Pump 写 binlog 的延迟时间 | -| Storage Write Binlog Size | Pump 写 binlog 数据的大小 | -| Storage Write Binlog Latency | Pump 中的 storage 模块写 binlog 数据的延迟 | -| Pump Storage Error By Type | Pump 遇到的 error 数量，按照 error 的类型进行统计 | -| Query TiKV | Pump 通过 TiKV 查询事务状态的次数 | - -### Drainer - -| metric 名称 | 说明 | -|:----|:------------| -| Checkpoint TSO | Drainer 已经同步到下游的 binlog 的最大 TSO 对应的时间。可以通过该指标估算同步延迟时间 | -| Pump Handle TSO | 记录 Drainer 从各个 Pump 获取到的 binlog 的最大 TSO 对应的时间 | | Pull Binlog QPS by Pump NodeID | Drainer 从每个 Pump 获取 binlog 的 QPS | -| 95% Binlog Reach Duration By Pump | 记录 binlog 从写入 Pump 到被 Drainer 获取到这个过程的延迟时间 | -| Error By Type | Drainer 遇到的 error 数量，按照 error 的类型进行统计 | -| SQL Query Time| Drainer 在下游执行 SQL 的耗时 | -| Drainer Event | 各种类型 event 的数量，event 包括 ddl、insert、delete、update、flush、savepoint | -| Execute Time | 写入 binlog 到同步下游模块所消耗的时间 | -| 95% Binlog Size | Drainer 从各个 Pump 获取到 binlog 数据的大小 | -| DL Job Count | Drainer 处理的 DDL 的数量| -| Queue Size | Drainer 内部工作队列大小 | - -## 监控报警规则 - -本节介绍了 TiDB Binlog 组件的报警项及相应的报警规则。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别 (Emergency)、重要级别 (Critical)、警告级别 (Warning)。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `binlog_pump_storage_error_count` - -* 报警规则： - - `changes(binlog_pump_storage_error_count[1m]) > 0` - -* 规则描述： - - Pump 写 binlog 到本地存储时失败。 - -* 处理方法： - - 确认 `pump_storage_error` 监控是否存在错误，查看 Pump 日志确认原因。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `binlog_drainer_checkpoint_high_delay` - -* 报警规则： - - `(time() - binlog_drainer_checkpoint_tso / 1000) > 3600` - -* 规则描述： - - Drainer 同步落后延迟超过 1 个小时。 - -* 处理方法： - - * 判断从 Pump 获取数据是否太慢： - - 监控 Pump handle tso 可以看每个 Pump 最近一条消息的时间，是不是有延迟特别大的 Pump，确认对应 Pump 正常运行。 - - * 根据 Drainer event 和 Drainer execute latency 来判断是否下游同步太慢： - - * 如果 Drainer execute time 过大，则检查到目标库网络带宽和延迟，以及目标库状态。 - * 如果 Drainer execute time 不大，Drainer event 过小，则增加 work count 和 batch 进行重试。 - - * 如果上面都不满足或者操作后没有改观，则报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `binlog_pump_write_binlog_rpc_duration_seconds_bucket` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_pump_rpc_duration_seconds_bucket{method="WriteBinlog"}[5m])) > 1` - -* 规则描述： - - Pump 处理 TiDB 写 Binlog 请求耗时过大。 - -* 处理方法： - - * 确认磁盘性能压力，通过 `node exported` 查看 disk performance 监控。 - * 如果 `disk latency` 和 `util` 都很低，那么报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -#### `binlog_pump_storage_write_binlog_duration_time_bucket` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_pump_storage_write_binlog_duration_time_bucket{type="batch"}[5m])) > 1` - -* 规则描述： - - Pump 写本地 binlog 到本地盘的耗时。 - -* 处理方法： - - 确认 Pump 本地盘情况，进行修复。 - -#### `binlog_pump_storage_available_size_less_than_20G` - -* 报警规则： - - `binlog_pump_storage_storage_size_bytes{type="available"} < 20 * 1024 * 1024 * 1024` - -* 规则描述： - - Pump 剩余可用磁盘空间不足 20 G。 - -* 处理方法： - - 监控确认 Pump 的 `gc_tso` 是否正常。如果不正常，调整 Pump 的 GC 时间配置或者下线对应 Pump。 - -#### `binlog_drainer_checkpoint_tso_no_change_for_1m` - -* 报警规则： - - `changes(binlog_drainer_checkpoint_tso[1m]) < 1` - -* 规则描述： - - Drainer 的 `checkpoint` 在 1 分钟内没有更新。 - -* 处理方法： - - 确认所有非下线的 Pump 是否正常运行。 - -#### `binlog_drainer_execute_duration_time_more_than_10s` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_drainer_execute_duration_time_bucket[1m])) > 10` - -* 规则描述： - - Drainer 同步到 TiDB 的事务耗时。如果这个值过大，会影响 Drainer 同步。 - -* 处理方法： - - * 查看 TiDB 集群的状态。 - * 查看 Drainer 日志或监控，如果是 DDL 操作导致了该问题，则忽略。 diff --git a/v3.0/reference/tidb-binlog/overview.md b/v3.0/reference/tidb-binlog/overview.md deleted file mode 100644 index 5f4593ec658b..000000000000 --- a/v3.0/reference/tidb-binlog/overview.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiDB Binlog 简介 -category: reference -aliases: ['/docs-cn/tools/binlog/overview/','/docs-cn/tools/tidb-binlog-cluster/','/docs-cn/v3.0/reference/tidb-binlog-overview/','/docs-cn/v3.0/reference/tools/tidb-binlog/overview/'] ---- - -# TiDB Binlog 简介 - -TiDB Binlog 是一个用于收集 TiDB 的 binlog，并提供准实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景： - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog 整体架构 - -![TiDB Binlog 架构](/media/tidb_binlog_cluster_architecture.png) - -TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl 工具： - -### Pump - -[Pump](https://github.com/pingcap/tidb-binlog/blob/master/pump) 用于实时记录 TiDB 产生的 Binlog，并将 Binlog 按照事务的提交时间进行排序，再提供给 Drainer 进行消费。 - -### Drainer - -[Drainer](https://github.com/pingcap/tidb-binlog/tree/master/drainer) 从各个 Pump 中收集 Binlog 进行归并，再将 Binlog 转化成 SQL 或者指定格式的数据，最终同步到下游。 - -### binlogctl 工具 - -[`binlogctl`](https://github.com/pingcap/tidb-binlog/tree/master/binlogctl) 是一个 TiDB Binlog 配套的运维工具，具有如下功能： - -* 获取 TiDB 集群当前的 TSO -* 查看 Pump/Drainer 状态 -* 修改 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer - -## 主要特性 - -* 多个 Pump 形成一个集群，可以水平扩容。 -* TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。 -* Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。 -* Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。 -* Drainer 支持 [relay log](/v3.0/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。 - -## 注意事项 - -* 需要使用 TiDB v2.0.8-binlog、v2.1.0-rc.5 及以上版本，否则不兼容该版本的 TiDB Binlog。 - -* Drainer 支持将 Binlog 同步到 MySQL、TiDB、Kafka 或者本地文件。如果需要将 Binlog 同步到其他 Drainer 不支持的类型的系统中，可以设置 Drainer 将 Binlog 同步到 Kafka，然后根据 binlog slave protocol 进行定制处理，参考 [binlog slave client 用户文档](/v3.0/reference/tidb-binlog/binlog-slave-client.md)。 - -* 如果 TiDB Binlog 用于增量恢复，可以设置配置项 `db-type="file"`，Drainer 会将 binlog 转化为指定的 [proto buffer 格式](https://github.com/pingcap/tidb-binlog/blob/master/proto/binlog.proto)的数据，再写入到本地文件中。这样就可以使用 [Reparo](/v3.0/reference/tidb-binlog/reparo.md) 恢复增量数据。 - - 关于 `db-type` 的取值，应注意： - - - 如果 TiDB 版本 < 2.1.9，则 `db-type="pb"`。 - - 如果 TiDB 版本 > = 2.1.9，则 `db-type="file"` 或 `db-type="pb"`。 - -* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/v3.0/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。 diff --git a/v3.0/reference/tidb-binlog/relay-log.md b/v3.0/reference/tidb-binlog/relay-log.md deleted file mode 100644 index c9620fcd2092..000000000000 --- a/v3.0/reference/tidb-binlog/relay-log.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB Binlog Relay Log -category: reference -aliases: ['/docs-cn/v3.0/reference/tools/tidb-binlog/relay-log/'] ---- - -# TiDB Binlog Relay Log - -Drainer 同步 binlog 时会拆分上游的事务，并将拆分的事务并发同步到下游。在极端情况下，上游集群不可用并且 Drainer 异常退出后，下游集群（MySQL 或 TiDB）可能处于数据不一致的中间状态。在此场景下，Drainer 借助 relay log 可以确保将下游集群同步到一个一致的状态。 - -## Drainer 同步时的一致性状态 - -下游集群达到一致的状态是指：下游集群的数据等同于上游设置了 `tidb_snapshot = ts` 的快照。 - -checkpoint 状态一致性是指：Drainer checkpoint 通过 `consistent` 保存了同步的一致性状态。Drainer 运行时 `consistent` 为 `false`，Drainer 正常退出后 `consistent` 更新为 `true`。 - -查询下游 checkpoint 表的示例如下： - -``` -mysql> select * from tidb_binlog.checkpoint; -+---------------------+----------------------------------------------------------------+ -| clusterID | checkPoint | -+---------------------+----------------------------------------------------------------+ -| 6791641053252586769 | {"consistent":false,"commitTS":414529105591271429,"ts-map":{}} | -+---------------------+----------------------------------------------------------------+ -``` - -## 工作原理 - -Drainer 开启 relay log 后会先将 binlog event 写到磁盘上，然后再同步给下游集群。如果上游集群不可用，Drainer 可以通过读取 relay log 把下游集群恢复到一个一致的状态。 - -> **注意：** -> -> 若同时丢失 relay log 数据，该方法将不可用，不过这是概率极小的事件。此外可以使用 NFS 等网络文件系统来保证 relay log 的数据安全。 - -### Drainer 从 relay log 消费 binlog 的触发场景 - -如果 Drainer 启动时无法连接到上游集群的 PD，并且探测到 checkpoint 的 `consistent = false`，此时会尝试读取 relay log，并将下游集群恢复到一致的状态。然后 Drainer 进程将 checkpoint 的 `status` 设置为 `0` 后主动退出。 - -### Relay log 的清理（GC）机制 - -Drainer 在运行时，如果确认已经将一个 relay log 文件的全部数据都成功同步到下游了，就会马上删除这个文件，所以 relay log 不会占用过多空间。一个 relay log 文件大小达到 10MB（默认）时就会做切分，数据开始写入新的 relay log 文件。 - -## 配置 - -在 Drainer 中添加以下配置来开启 relay log 功能： - -{{< copyable "" >}} - -``` -[syncer.relay] -# 保存 relay log 的目录，空值表示不开启。 -# 只有下游是 TiDB 或 MySQL 时该配置才有生效。 -log-dir = "/dir/to/save/log" -``` diff --git a/v3.0/reference/tidb-binlog/reparo.md b/v3.0/reference/tidb-binlog/reparo.md deleted file mode 100644 index 3baf8107016f..000000000000 --- a/v3.0/reference/tidb-binlog/reparo.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Reparo 使用文档 -category: reference -aliases: ['/docs-cn/tools/binlog/reparo/','/docs-cn/v3.0/reference/tools/tidb-binlog/reparo/'] ---- - -# Reparo 使用文档 - -Reparo 是 TiDB Binlog 的一个配套工具，用于增量的恢复。使用 TiDB Binlog 中的 Drainer 将 binlog 按照 protobuf 格式输出到文件，通过这种方式来备份增量数据。当需要恢复增量数据时，使用 Reparo 解析文件中的 binlog，并将其应用到 TiDB／MySQL 中。 - -下载链接：[tidb-binlog-cluster-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-binlog-cluster-latest-linux-amd64.tar.gz) - -## Reparo 使用 - -### 命令行参数说明 - -``` -Usage of Reparo: --L string - 日志输出信息等级设置：debug, info, warn, error, fatal（默认值：info）。 --V 打印版本信息。 --c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好（默认 16）。 --config string - 配置文件路径，如果指定了配置文件，Reparo 会首先读取配置文件的配置；如果对应的配置在命令行参数里面也存在，Reparo 就会使用命令行参数的配置来覆盖配置文件里面的。 --data-dir string - Drainer 输出的 protobuf 格式 binlog 文件的存储路径 (默认值： data.drainer)。 --dest-type string - 下游服务类型。 取值为 print, mysql（默认值：print）。当值为 print 时，只做解析打印到标准输出，不执行 SQL；如果为 mysql，则需要在配置文件内配置 host、port、user、password 等信息。 --log-file string - log 文件路径。 --log-rotate string - log 文件切换频率，取值为 hour、day。 --start-datetime string - 用于指定开始恢复的时间点，格式为 “2006-01-02 15:04:05”。如果不设置该参数则从最早的 binlog 文件开始恢复。 --stop-datetime string - 用于指定结束恢复的时间点，格式同上。如果不设置该参数则恢复到最后一个 binlog 文件。 --safe-mode bool - 指定是否开启安全模式，开启后可支持反复同步。 --txn-batch int - 输出到下游数据库一个事务的 SQL 语句数量（默认 20）。 -``` - -### 配置文件说明 - -```toml -# Drainer 输出的 protobuf 格式 binlog 文件的存储路径。 -data-dir = "./data.drainer" - -# 使用索引文件来搜索 ts 的位置，当设置了 `start-ts` 时设置该参数，文件的路径为 {data-dir}/{index-name}。 -# index-name = "binlog.index" -# log-file = "" -# log-rotate = "hour" - -# 日志输出信息等级设置：debug, info, warn, error, fatal (默认值：info)。 -log-level = "info" - -# 使用 start-datetime 和 stop-datetime 来选择恢复指定时间范围内的 binlog，格式为 “2006-01-02 15:04:05”。 -# start-datetime = "" -# stop-datetime = "" - -# start-tso、stop-tso 分别对应 start-datetime 和 stop-datetime，也是用于恢复指定时间范围内的 binlog，用 tso 的值来设置。如果已经设置了 start-datetime 和 stop-datetime，就不需要再设置 start-tso 和 stop-tso。 -# start-tso = 0 -# stop-tso = 0 - -# 下游服务类型。 取值为 print, mysql（默认值：print）。当值为 print 时，只做解析打印到标准输出，不执行 SQL；如果为 mysql，则需要在 [dest-db] 中配置 host、port、user、password 等信息。 -dest-type = "mysql" - -# 输出到下游数据库一个事务的 SQL 语句数量（默认 20）。 -txn-batch = 20 - -# 同步下游的并发数，该值设置越高同步的吞吐性能越好（默认 16）。 -worker-count = 16 - -# 安全模式配置。取值为 true 或 false（默认值：false）。当值为 true 时，Reparo 会将 update 语句拆分为 delete + replace 语句。 -safe-mode = false - -# replicate-do-db 和 replicate-do-table 用于指定恢复的库和表，replicate-do-db 的优先级高于 replicate-do-table。支持使用正则表达式来配置，需要以 '~' 开始声明使用正则表达式。 -# 注：replicate-do-db 和 replicate-do-table 使用方式与 Drainer 的使用方式一致。 -# replicate-do-db = ["~^b.*","s1"] -# [[replicate-do-table]] -# db-name ="test" -# tbl-name = "log" -# [[replicate-do-table]] -# db-name ="test" -# tbl-name = "~^a.*" - -# 如果 dest-type 设置为 mysql, 需要配置 dest-db。 -[dest-db] -host = "127.0.0.1" -port = 3309 -user = "root" -password = "" -``` - -### 启动示例 - -{{< copyable "shell-regular" >}} - -```bash -./bin/reparo -config reparo.toml -``` - -> **注意：** -> -> - data-dir 用于指定 Drainer 输出的 binlog 文件目录。 -> - start-datatime 和 start-tso 效果一样，只是时间格式上的区别，用于指定开始恢复的时间点；如果不指定，则默认在第一个 binlog 文件开始恢复。 -> - stop-datetime 和 stop-tso 效果一样，只是时间格式上的区别，用于指定结束恢复的时间点；如果不指定，则恢复到最后一个 binlog 文件的结尾。 -> - dest-type 指定目标类型，取值为 `mysql`、`print`。 当值为 `mysql` 时，可以恢复到 MySQL/TiDB 等使用或兼容 MySQL 协议的数据库，需要在配置下面的 [dest-db] 填写数据库信息；当取值为 `print` 的时候，只是打印 binlog 信息，通常用于 debug，以及查看 binlog 的内容，此时不需要填写 `[dest-db]`。 -> - replicate-do-db 用于指定恢复的库，不指定的话，则全部都恢复。 -> - replicate-do-table 用于指定要恢复的表，不指定的话，则全部都恢复。 diff --git a/v3.0/reference/tidb-binlog/tidb-binlog-kafka.md b/v3.0/reference/tidb-binlog/tidb-binlog-kafka.md deleted file mode 100644 index e623c6ba5e10..000000000000 --- a/v3.0/reference/tidb-binlog/tidb-binlog-kafka.md +++ /dev/null @@ -1,458 +0,0 @@ ---- -title: TiDB Binlog kafka 部署方案 -category: reference -aliases: ['/docs-cn/tools/binlog/tidb-binlog-kafka/','/docs-cn/v3.0/reference/tools/tidb-binlog/tidb-binlog-kafka/'] ---- - -# TiDB Binlog Kafka 部署方案 - -本文档介绍如何部署 Kafka 版本的 TiDB Binlog。 - -## TiDB Binlog 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog Kafka 架构 - -首先介绍 TiDB Binlog 的整体架构。 - -![TiDB Binlog 架构](/media/tidb_binlog_kafka_architecture.png) - -TiDB Binlog 集群主要分为三个组件： - -### Pump - -Pump 是一个守护进程，在每个 TiDB 主机的后台运行。其主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入 Kafka 中。 - -### Drainer - -Drainer 从 Kafka 中收集 Binlog，并按照 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件。 - -### Kafka & ZooKeeper - -Kafka 集群用来存储由 Pump 写入的 Binlog 数据，并提供给 Drainer 进行读取。 - -> **注意：** -> -> Local 版本将 Binlog 存储在文件中，Kafka 版本则使用 Kafka 存储。 - -## TiDB Binlog 安装 - -以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - -| TiDB Ansible 分支 | TiDB 版本 | 备注 | -|:----|:----|:----| -| release-2.0 | 2.0 版本 | 最新 2.0 稳定版本，可用于生产环境。 | - -### 下载官方 Binary - -环境：CentOS 7+ - -下载压缩包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-binlog-kafka-linux-amd64.sha256 -``` - -解开压缩包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf tidb-binlog-kafka-linux-amd64.tar.gz && -cd tidb-binlog-kafka-linux-amd64 -``` - -### TiDB Binlog 部署 - -#### 注意事项 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 的方式输出 Binlog。 - -* 手动部署时，启动顺序为：Pump > TiDB。停止顺序为 TiDB > Pump。 - - 设置 TiDB 启动参数 `binlog-socket` 为对应的 Pump 参数 `socket` 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 - -* 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取 savepoint，然后导入全量备份，最后启动 Drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 Pump 运行 10 分钟左右后按顺序进行如下操作： - - * 使用 [binlogctl](https://github.com/pingcap/tidb-tools/tree/binlog-kafka/tidb_binlog/binlogctl) 工具生成 Drainer 初次启动所需的 position - * 全量备份，例如 Mydumper 备份 TiDB - * 全量导入备份到目标系统 - * Kafka 版本 Drainer 启动的 savepoint 默认保存在下游 database tidb_binlog 下的 checkpoint 表中，如果 checkpoint 表中没有有效的数据，可以通过设置 `initial-commit-ts` 启动 Drainer 从指定位置开始消费 - `bin/drainer --config=conf/drainer.toml --initial-commit-ts=${position}` - -* Drainer 输出为 pb，要在配置文件中设置如下参数： - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -* Drainer 输出为 kafka，要在配置文件中设置如下参数： - - ```toml - [syncer] - db-type = "kafka" - - # when db-type is kafka, you need to use this to config the down stream kafka, or it will be the same kafka addrs where drainer pull binlog from. - [syncer.to] - kafka-addrs = "127.0.0.1:9092" - kafka-version = "0.8.2.0" - ``` - - 输出到 kafka 的数据为按 ts 排好序的 protobuf 定义 binlog 格式，可以参考 [driver](https://github.com/pingcap/tidb-tools/tree/master/tidb-binlog/driver) 获取数据同步到下游。 - -* Kafka 和 ZooKeeper 集群需要在部署 TiDB Binlog 之前部署好。Kafka 需要 0.9 及以上版本。 - -#### Kafka 集群配置推荐 - -|名字|数量|内存|CPU|硬盘| -|:---:|:---:|:---:|:---:|:---:| -|Kafka|3+|16G|8+|2+ 1TB| -|ZooKeeper|3+|8G|4+|2+ 300G| - -#### Kafka 配置参数推荐 - -- `auto.create.topics.enable = true`：如果还没有创建 topic，Kafka 会在 broker 上自动创建 topic -- `broker.id`：用来标识 Kafka 集群的必备参数，不能重复，如 `broker.id = 1` -- `fs.file-max = 1000000`：Kafka 会使用大量文件和网络 socket，建议修改成 1000000，通过 `vi /etc/sysctl.conf` 进行修改 -- 修改以下配置为1G, 否则很容易出现事务修改数据较多导致单个消息过大写 kafka 失败 - - * `message.max.bytes=1073741824` - * `replica.fetch.max.bytes=1073741824` - * `fetch.message.max.bytes=1073741824` - -#### 使用 TiDB Ansible 部署 Pump - -- 如无 Kafka 集群，可使用 [kafka-ansible](https://github.com/pingcap/thirdparty-ops/tree/master/kafka-ansible) 部署 Kafka 集群。 -- 使用 [tidb-ansible](https://github.com/pingcap/tidb-ansible) 部署 TiDB 集群时，修改 `tidb-ansible/inventory.ini` 文件，设置 `enable_binlog = True`，并配置 `zookeeper_addrs` 变量为 Kafka 集群的 ZooKeeper 地址，这样部署 TiDB 集群时会部署 Pump。 - -配置样例: - -```ini -# binlog trigger -enable_binlog = True -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -``` - -#### 使用 Binary 部署 Pump - -使用样例： - -假设我们有三个 PD，三个 ZooKeeper，一个 TiDB，各个节点信息如下： - -```ini -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -ZK1="192.168.0.13" -ZK2="192.168.0.12" -ZK3="192.168.0.11" -``` - -在 ip="192.168.0.10" 的机器上面部署 Drainer/Pump。 - -对应的 PD 集群的 ip="192.168.0.16,192.168.0.15,192.168.0.14"。 - -对应的 Kafka 集群的 ZooKeeper 的 ip="192.168.0.13,192.168.0.12,192.168.0.11"。以此为例，说明 Pump/Drainer 的使用。 - -1. Pump 命令行参数说明 - - ``` - Usage of Pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.10:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.10:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里面的。 - -data-dir string - Pump 数据存储位置路径 - -enable-tolerant - 开启 tolerant 后，如果 binlog 写入失败，Pump 不会报错（默认开启） - -zookeeper-addrs string (-zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181") - ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，需要和 Kafka 中配置相同 - -gc int - 日志最大保留天数 (默认 7)，设置为 0 可永久保存 - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -socket string - unix socket 模式服务监听地址（默认 unix:///tmp/pump.sock） - ``` - -2. Pump 配置文件 - - ```toml - # Pump Configuration. - - # Pump 提供服务的 RPC 地址("192.168.0.10:8250") - addr = "192.168.0.10:8250" - - # Pump 对外提供服务的 RPC 地址("192.168.0.10:8250") - advertise-addr = "" - - # binlog 最大保留天数 (默认 7)，设置为 0 可永久保存 - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，若 Kafka 中配置了命名空间，则此处需同样配置 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" - # 配置了命令空间的 ZooKeeper 地址配置示例 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 3 - - # PD 集群节点的地址 - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of Drainer: - -L string - 日志输出信息等级设置：debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.10:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -zookeeper-addrs string (-zookeeper-addrs="192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181") - ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，需要和 Kafka 中配置相同 - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步（下游服务类型为 mysql，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts (默认为 0) - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位 秒） - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - -2. Drainer 配置文件 - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.10:8249") - addr = "192.168.0.10:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，若 Kafka 中配置了命名空间，则此处需同样配置 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" - # 配置了命令空间的 ZooKeeper 地址配置示例 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" - - # PD 集群节点的地址 - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 SQL 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 mysql, 该项设置为 False） - disable-dispatch = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db prioritizes over replicate-do-table when they have the same db name - # and we support regex expressions, - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.10" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## 下载 PbReader 工具 (Linux) - -PbReader 用于解析 Drainer 生成的 Pb 文件，并翻译成对应的 SQL 语句。 - -环境：CentOS 7+ - -下载 PbReader 压缩包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/pb_reader-latest-linux-amd64.tar.gz && -wget https://download.pingcap.org/pb_reader-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c pb_reader-latest-linux-amd64.sha256 -``` - -解开压缩包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf pb_reader-latest-linux-amd64.tar.gz && -cd pb_reader-latest-linux-amd64 -``` - -PbReader 使用示例： - -{{< copyable "shell-regular" >}} - -```bash -./bin/pbReader -binlog-file=${path}/binlog-0000000000000000 -``` - -## TiDB Binlog 监控 - -本部分主要介绍如何对 TiDB Binlog 的状态、性能做监控，并通过 Prometheus + Grafana 展现 metrics 数据。 - -### Pump/Drainer 配置 - -使用 Ansible 部署的 Pump 服务已经在启动参数设置 metrics。启动 Drainer 时可以设置以下两个参数： - -- `--metrics-addr`：设为 Push Gateway 的地址 -- `--metrics-interval`：设为 push 的频率，单位为秒，默认值为 15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号：admin，密码：admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 - - > **注意：** - > - > Type 选 Prometheus，URL 为 Prometheus 地址，根据实际情况添加/填写。 - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json)上传 -> 选择对应的 data source diff --git a/v3.0/reference/tidb-binlog/tidb-binlog-local.md b/v3.0/reference/tidb-binlog/tidb-binlog-local.md deleted file mode 100644 index e36a3f8313a5..000000000000 --- a/v3.0/reference/tidb-binlog/tidb-binlog-local.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -title: TiDB Binlog Local 部署方案 -category: reference -aliases: ['/docs-cn/tools/binlog/tidb-binlog-local/','/docs-cn/v3.0/reference/tools/tidb-binlog/tidb-binlog-local/'] ---- - -# TiDB Binlog Local 部署方案 - -## TiDB Binlog Local 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -* **数据同步**：同步 TiDB 集群数据到其他数据库。 -* **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复。 - -## TiDB Binlog Local 架构 - -下图为 TiDB Binlog Local的整体架构。 - -![TiDB Binlog 架构](/media/architecture.jpeg) - -TiDB Binlog Local 主要分为两个组件： - -- **Pump** 是一个守护进程，在每个 TiDB 的主机上后台运行。他的主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入磁盘文件 - -- **Drainer** 从各个 Pump 节点收集 Binlog，并按照在 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件 - -## TiDB Binlog Local 安装 - -### TiDB Binlog Local 下载 - -TiDB Binlog 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v3.0/reference/tools/download.md)。 - -### TiDB Binlog Local 部署 - -#### 注意 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 方式的输出 binlog。 -* 手动部署时， 启动顺序为： Pump > TiDB，停止顺序为 TiDB > Pump - - 我们设置 TiDB 启动参数 binlog-socket 为对应的 Pump 的参数 socket 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* drainer 不支持对 ignore schemas（在过滤列表中的 schemas） 的 table 进行 rename DDL 操作 - -* 在已有的 TiDB 集群中启动 drainer，一般需要全量备份 并且获取 savepoint，然后导入全量备份，最后启动 drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 pump 运行 10 分钟左右后按顺序进行下面的操作 - - * 以 gen-savepoint model 运行 drainer 生成 drainer savepint 文件，`bin/drainer -gen-savepoint --data-dir= ${drainer_savepoint_dir} --pd-urls=${pd_urls}` - * 全量备份，例如 Mydumper 备份 tidb - * 全量导入备份到目标系统 - * 设置 savepoint 文件路径，然后启动 drainer，`bin/drainer --config=conf/drainer.toml --data-dir=${drainer_savepoint_dir}` - -* drainer 输出的 pb, 需要在配置文件设置下面的参数 - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -#### 使用 TiDB Ansible 部署 Pump (推荐) - -* 搭建全新的 TiDB Cluster，启动顺序 pd-server -> tikv-server -> pump -> tidb-server -> drainer - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook deploy.yml - * 执行 ansible-playbook start.yml - * drainer 目前需要手动部署 - -* 对已有的 TiDB Cluster 部署 binlog - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook rolling_update.yml --tags=tidb - * drainer 目前需要手动部署 - -#### 使用 Binary 部署 Pump - -1. PUMP 命令行参数说明 - - ``` - Usage of pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -advertise-addr string - pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -config string - 配置文件路径,如果你指定了配置文件，pump 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，pump 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - pump 数据存储位置路径 - -gc int - 日志最大保留天数 (默认 7)， 设置为 0 可永久保存 - -heartbeat-interval uint - pump 向 pd 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -socket string - unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - ``` - - 2. PUMP 配置文件 - - ```toml - # pump Configuration. - # pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - addr = "127.0.0.1:8250" - # pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - advertise-addr = "" - # binlog 最大保留天数 (默认 7)， 设置为 0 可永久保存 - gc = 7 - # pump 数据存储位置路径 - data-dir = "data.pump" - # pump 向 pd 发送心跳间隔 (单位 秒) - heartbeat-interval = 3 - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of drainer: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - drainer 提供服务的地址(默认 "127.0.0.1:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径, drainer 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 pd 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - -gen-savepoint - 如果设置为 true, 则只生成 drainer 的 savepoint meta 文件, 可以配合 Mydumper 使用 - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -txn-batch int - 输出到下游数据库一个事务的 sql 数量 (default 1) - ``` - -2. Drainer 配置文件 - - ```toml - # drainer Configuration. - - # drainer 提供服务的地址(默认 "127.0.0.1:8249") - addr = "127.0.0.1:8249" - - # 向 pd 查询在线 pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 sql 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - disable-dispatch = false - - # drainer 下游服务类型 (默认为 mysql) - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db priority over replicate-do-table if have same db name - # and we support regex expression , - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "127.0.0.1" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时,存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## TiDB Binlog Local 监控 - -这部分主要对 TiDB Binlog 的状态、性能做监控，通过 Prometheus + Grafana 展现 metrics 数据， - -### pump/drainer 配置 - -使用 ansible 部署的 pump 服务，已经在启动参数设置 metrics 。 - -drainer 启动时可以设置 `--metrics-addr` 和 `--metrics-interval` 两个参数，其中 metrics-addr 设为 Push Gateway 的地址，metrics-interval 为 push 的频率，单位为秒，默认值为15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号: admin 密码: admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 ( 注: Type 选 Prometheus，Url 为 Prometheus 地址，根据实际情况 添加/填写 ） - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/binlog.json)上传 -> 选择对应的 data source diff --git a/v3.0/reference/tidb-binlog/troubleshoot/binlog.md b/v3.0/reference/tidb-binlog/troubleshoot/binlog.md deleted file mode 100644 index daa06b3c5fc6..000000000000 --- a/v3.0/reference/tidb-binlog/troubleshoot/binlog.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: TiDB Binlog 故障诊断 -category: reference -aliases: ['/docs-cn/v3.0/how-to/troubleshoot/tidb-binlog/'] ---- - -# TiDB Binlog 故障诊断 - -本文总结了在 TiDB Binlog 的使用过程中遇到问题的诊断流程，并指引用户通过监控、状态、日志等信息查找相应的解决方案。 - -如果你在使用 TiDB Binlog 时出现了异常，请尝试以下方式排查问题： - -1. 查看各个监控指标是否异常，参见[TiDB Binlog 集群监控](/v3.0/reference/tidb-binlog/monitor.md)。 - -2. 使用 [binlogctl 工具](/v3.0/reference/tidb-binlog/maintain.md#binlogctl-工具)查看各个 Pump、Drainer 的状态是否有异常。 - -3. 查看 Pump、Drainer 日志中是否有 `ERROR`、`WARN`，并根据详细的日志信息初步判断问题原因。 - -通过以上方式定位到问题后，在 [FAQ](/v3.0/reference/tidb-binlog/faq.md) 以及 [常见错误及修复](/v3.0/reference/tidb-binlog/troubleshoot/error-handling.md) 中查找解决方案，如果没有查找到解决方案或者提供的解决方案无法解决问题，请提交 [issue](https://github.com/pingcap/tidb-binlog/issues) 或者联系相关技术支持人员。 diff --git a/v3.0/reference/tidb-binlog/troubleshoot/error-handling.md b/v3.0/reference/tidb-binlog/troubleshoot/error-handling.md deleted file mode 100644 index a38d88c4dd07..000000000000 --- a/v3.0/reference/tidb-binlog/troubleshoot/error-handling.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB Binlog 常见错误修复 -category: reference ---- - -# TiDB Binlog 常见错误修复 - -本文档介绍 TiDB Binlog 中常见的错误以及修复方法。 - -## Drainer 同步数据到 Kafka 时报错 "kafka server: Message was too large, server rejected it to avoid allocation error" - -报错原因：如果在 TiDB 中执行了大事务，则生成的 binlog 数据会比较大，可能超过了 Kafka 的消息大小限制。 - -解决方法：需要调整 Kafka 的配置参数，如下所示。 - -``` -message.max.bytes=1073741824 -replica.fetch.max.bytes=1073741824 -fetch.message.max.bytes=1073741824 -``` - -## Pump 报错 "no space left on device" - -报错原因：本地磁盘空间不足，Pump 无法正常写 binlog 数据。 - -解决方法：需要清理磁盘空间，然后重启 Pump。 - -## Pump 启动时报错 "fail to notify all living drainer" - -报错原因：Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。 - -解决方法：可以使用 [binlogctl 工具](/v3.0/reference/tidb-binlog/maintain.md#binlogctl-工具)查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。 diff --git a/v3.0/reference/tidb-binlog/upgrade.md b/v3.0/reference/tidb-binlog/upgrade.md deleted file mode 100644 index e8af2bde56da..000000000000 --- a/v3.0/reference/tidb-binlog/upgrade.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: TiDB Binlog 版本升级方法 -category: reference -aliases: ['/docs-cn/v3.0/how-to/upgrade/tidb-binlog/','/docs-cn/v3.0/reference/tools/tidb-binlog/upgrade/'] ---- - -# TiDB Binlog 版本升级方法 - -如未特别指明，文中出现的 TiDB Binlog 均指最新的 [Cluster](/v3.0/reference/tidb-binlog/overview.md) 版本。 - -本文会分 Ansible 部署和手动部署两种情况介绍 TiDB Binlog 版本升级的方法，另外有一小节介绍如何从更早的不兼容版本（Kafka/Local 版本）升级到最新版本。 - -## Ansible 部署 - -本节适用于使用 [TiDB Ansible Playbook](https://github.com/pingcap/tidb-ansible) 部署的情况。 - -### 升级 Pump - -1. 将新版本的二进制文件 `pump` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook rolling_update.yml --tags=pump` 命令来滚动升级 Pump - -### 升级 Drainer - -1. 将新版本的二进制文件 `drainer` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook stop_drainer.yml --tags=drainer` 命令 -3. 执行 `ansible-playbook start_drainer.yml --tags=drainer` 命令 - -## 手动部署 - -### 升级 Pump - -对集群里的每个 Pump 逐一升级，确保集群中总有 Pump 可以接收 TiDB 发来的 Binlog。 - -1. 用新版本的 `pump` 替换原来的文件 -2. 重启 Pump 进程 - -### 升级 Drainer - -1. 用新版本的 `drainer` 替换原来的文件 -2. 重启 Drainer 进程 - -## 从 Kafka/Local 版本升级到 Cluster 版本 - -新版本的 TiDB（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）不兼容 [Kafka 版本](/v3.0/reference/tidb-binlog/tidb-binlog-kafka.md)以及 [Local 版本](/v3.0/reference/tidb-binlog/tidb-binlog-local.md)的 TiDB Binlog，集群升级到新版本后只能使用 Cluster 版本的 TiDB Binlog。如果在升级前已经使用了 Kafka／Local 版本的 TiDB Binlog，必须将其升级到 Cluster 版本。 - -TiDB Binlog 版本与 TiDB 版本的对应关系如下： - -| TiDB Binlog 版本 | TiDB 版本 | 说明 | -|---|---|---| -| Local | TiDB 1.0 及更低版本 || -| Kafka | TiDB 1.0 ~ TiDB 2.1 RC5 | TiDB 1.0 支持 local 版本和 Kafka 版本的 TiDB Binlog。 | -| Cluster | TiDB v2.0.8-binlog，TiDB 2.1 RC5 及更高版本 | TiDB v2.0.8-binlog 是一个支持 Cluster 版本 TiDB Binlog 的 2.0 特殊版本。 | - -### 升级流程 - -> **注意：** -> -> 如果能接受重新导全量数据，则可以直接废弃老版本，按 [TiDB Binlog 集群部署](/v3.0/reference/tidb-binlog/deploy.md)中的步骤重新部署。 - -如果想从原来的 checkpoint 继续同步，使用以下升级流程： - -1. 部署新版本 Pump。 -2. 暂停 TiDB 集群业务。 -3. 更新 TiDB 以及配置，写 Binlog 到新的 Pump Cluster。 -4. TiDB 集群重新接入业务。 -5. 确认老版本的 Drainer 已经将老版本的 Pump 的数据完全同步到下游。 - - 查询 Drainer 的 `status` 接口，示例命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - curl 'http://172.16.10.49:8249/status' - ``` - - ``` - {"PumpPos":{"172.16.10.49:8250":{"offset":32686}},"Synced": true ,"DepositWindow":{"Upper":398907800202772481,"Lower":398907799455662081}} - ``` - - 如果返回的 `Synced` 为 true，则可以认为 Binlog 数据已经全部同步到了下游。 - -6. 启动新版本 Drainer； -7. 下线老版本的 Pump、Drainer 以及依赖的 Kafka 和 ZookeSeper。 diff --git a/v3.0/reference/tispark.md b/v3.0/reference/tispark.md deleted file mode 100644 index 68f3ac3b35b3..000000000000 --- a/v3.0/reference/tispark.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: TiSpark 用户指南 -category: reference ---- - -# TiSpark 用户指南 - -TiSpark 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。TiSpark 依赖于 TiKV 集群和 Placement Driver (PD)，也需要你搭建一个 Spark 集群。 - -本文简单介绍如何部署和使用 TiSpark。本文假设你对 Spark 有基本认知。你可以参阅 [Apache Spark 官网](https://spark.apache.org/docs/latest/index.html) 了解 Spark 的相关信息。 - -## 概述 - -TiSpark 是将 Spark SQL 直接运行在分布式存储引擎 TiKV 上的 OLAP 解决方案。其架构图如下： - -![TiSpark Architecture](/media/tispark-architecture.png) - -+ TiSpark 深度整合了 Spark Catalyst 引擎, 可以对计算提供精确的控制，使 Spark 能够高效的读取 TiKV 中的数据，提供索引支持以实现高速的点查。 -+ 通过多种计算下推减少 Spark SQL 需要处理的数据大小，以加速查询；利用 TiDB 的内建的统计信息选择更优的查询计划。 -+ 从数据集群的角度看，TiSpark + TiDB 可以让用户无需进行脆弱和难以维护的 ETL，直接在同一个平台进行事务和分析两种工作，简化了系统架构和运维。 -+ 除此之外，用户借助 TiSpark 项目可以在 TiDB 上使用 Spark 生态圈提供的多种工具进行数据处理。例如，使用 TiSpark 进行数据分析和 ETL；使用 TiKV 作为机器学习的数据源；借助调度系统产生定时报表等等。 - -## 环境准备 - -现有 TiSpark 2.x 版本支持 Spark 2.3.x 和 Spark 2.4.x。如果你希望使用 Spark 2.1.x 版本，需使用 TiSpark 1.x。 - -TiSpark 需要 JDK 1.8+ 以及 Scala 2.11（Spark2.0+ 默认 Scala 版本）。 - -TiSpark 可以在 YARN，Mesos，Standalone 等任意 Spark 模式下运行。 - -## 推荐配置 - -本部分描述了 TiKV 与 TiSpark 集群分开部署、Spark 与 TiSpark 集群独立部署，以及TiSpark 与 TiKV 集群混合部署的建议配置。 - -### TiKV 与 TiSpark 集群分开部署的配置 - -对于 TiKV 与 TiSpark 分开部署的场景，可以参考如下建议配置： - -+ 硬件配置建议 - - 普通场景可以参考 [TiDB 和 TiKV 硬件配置建议](/v3.0/how-to/deploy/hardware-recommendations.md)，但是如果是偏重分析的场景，可以将 TiKV 节点增加到至少 64G 内存。 - -### Spark 与 TiSpark 集群独立部署的配置 - -关于 Spark 的详细硬件推荐配置请参考[官网](https://spark.apache.org/docs/latest/hardware-provisioning.html)，如下是 TiSpark 所需环境的简单描述： - -Spark 推荐 32G 内存以上的配额。请在配置中预留 25% 的内存给操作系统。 - -Spark 推荐每台计算节点配备 CPU 累计 8 到 16 核以上。你可以初始设定分配所有 CPU 核给 Spark。 - -Spark 的具体配置方式也请参考[官方说明](https://spark.apache.org/docs/latest/spark-standalone.html)。以下为根据 `spark-env.sh` 配置的范例： - -{{< copyable "" >}} - -``` -SPARK_EXECUTOR_CORES: 5 -SPARK_EXECUTOR_MEMORY: 10g -SPARK_WORKER_CORES: 5 -SPARK_WORKER_MEMORY: 10g -``` - -在 `spark-defaults.conf` 中，增加如下配置： - -{{< copyable "" >}} - -``` -spark.tispark.pd.addresses $your_pd_servers -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -`your_pd_servers` 是用逗号分隔的 PD 地址，每个地址使用 `地址:端口` 的格式。 - -例如你有一组 PD 在`10.16.20.1`，`10.16.20.2`，`10.16.20.3`，那么 PD 配置格式是`10.16.20.1:2379,10.16.20.2:2379,10.16.20.3:2379`。 - -### TiSpark 与 TiKV 集群混合部署的配置 - -对于 TiKV 与 TiSpark 混合部署的场景，需在原有 TiKV 预留资源之外累加 Spark 所需部分，并分配 25% 的内存作为系统本身占用。 - -## 部署 TiSpark - -TiSpark 的 jar 包可以在 [TiSpark Releases 页面](https://github.com/pingcap/tispark/releases)下载对应版本的 jar 包并拷贝到合适的目录。 - -### 已有 Spark 集群的部署方式 - -如果在已有 Spark 集群上运行 TiSpark，无需重启集群。可以使用 Spark 的 `--jars` 参数将 TiSpark 作为依赖引入： - -{{< copyable "shell-regular" >}} - -```shell -spark-shell --jars $TISPARK_FOLDER/tispark-${name_with_version}.jar -``` - -### 没有 Spark 集群的部署方式 - -如果没有使用中的 Spark 集群，推荐使用 Saprk Standalone 方式部署。这里简单介绍下 Standalone 部署方式。如果遇到问题，可以去官网寻求[帮助](https://spark.apache.org/docs/latest/spark-standalone.html)；也欢迎在我们的 GitHub 上提 [issue](https://github.com/pingcap/tispark/issues/new)。 - -#### 下载安装包并安装 - -你可以在 [Apache Spark™ 下载页面](https://spark.apache.org/downloads.html)下载 Apache Spark。 - -对于 Standalone 模式且无需 Hadoop 支持，则选择 Spark 2.3.x 或者 Spark 2.4.x 且带有 Hadoop 依赖的 Pre-build with Apache Hadoop 2.x 任意版本。如有需要配合使用的 Hadoop 集群，则选择对应的 Hadoop 版本号。你也可以选择从源代码[自行构建](https://spark.apache.org/docs/latest/building-spark.html)以配合官方 Hadoop 2.x 之前的版本。 - -如果你已经有了 Spark 二进制文件，并且当前 PATH 为 SPARKPATH，需将 TiSpark jar 包拷贝到 `${SPARKPATH}/jars` 目录下。 - -#### 启动 Master - -在选中的 Spark Master 节点执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd $SPARKPATH -``` - -{{< copyable "shell-regular" >}} - -```bash -./sbin/start-master.sh -``` - -在这步完成以后，屏幕上会打印出一个 log 文件。检查 log 文件确认 Spark-Master 是否启动成功。你可以打开 查看集群信息（如果你没有改动 Spark-Master 默认 Port Numebr）。在启动 Spark-Slave 的时候，也可以通过这个面板来确认 Slave 是否已经加入集群。 - -#### 启动 Slave - -类似地，可以用如下命令启动 Spark-Slave 节点： - -{{< copyable "shell-regular" >}} - -```bash -./sbin/start-slave.sh spark://spark-master-hostname:7077 -``` - -命令返回以后，即可通过刚才的面板查看这个 Slave 是否已经正确地加入了 Spark 集群。在所有 Slave 节点重复刚才的命令。确认所有的 Slave 都可以正确连接 Master，这样你就拥有了一个 Standalone 模式的 Spark 集群。 - -#### Spark SQL shell 和 JDBC 服务器 - -当前版本的 TiSpark 可以直接使用 `spark-sql` 和 Spark 的 ThriftServer JDBC 服务器。 - -## 一个使用范例 - -假设你已经按照上述步骤成功启动了 TiSpark 集群，下面简单介绍如何使用 Spark SQL 来做 OLAP 分析。这里我们用名为 tpch 数据库中的 lineitem 表作为范例。 - -假设你的 PD 节点位于 192.168.1.100，端口为 2379，在 `$SPARK_HOME/conf/spark-defaults.conf` 加入： - -{{< copyable "" >}} - -``` -spark.tispark.pd.addresses 192.168.1.100:2379 -``` - -{{< copyable "" >}} - -``` -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -然后在 Spark-Shell 里像原生 Spark 一样输入下面的命令： - -{{< copyable "" >}} - -```scala -spark.sql("use tpch") -``` - -{{< copyable "" >}} - -```scala -spark.sql("select count(*) from lineitem").show -``` - -结果为： - -``` -+-------------+ -| Count (1) | -+-------------+ -| 600000000 | -+-------------+ -``` - -Spark SQL 交互 Shell 和原生 Spark 一致： - -{{< copyable "" >}} - -```shell -spark-sql> use tpch; -``` - -``` -Time taken: 0.015 seconds -``` - -{{< copyable "" >}} - -```shell -spark-sql> select count(*) from lineitem; -``` - -``` -2000 -Time taken: 0.673 seconds, Fetched 1 row(s) -``` - -SQuirreLSQL 和 hive-beeline 可以使用 JDBC 连接 Thrift 服务器。 -例如，使用 beeline 连接： - -{{< copyable "shell-regular" >}} - -```shell -./beeline -``` - -``` -Beeline version 1.2.2 by Apache Hive -``` - -{{< copyable "" >}} - -```shell -beeline> !connect jdbc:hive2://localhost:10000 -``` - -{{< copyable "" >}} - -```shell -1: jdbc:hive2://localhost:10000> use testdb; -``` - -``` -+---------+--+ -| Result | -+---------+--+ -+---------+--+ -No rows selected (0.013 seconds) -``` - -{{< copyable "sql" >}} - -```sql -select count(*) from account; -``` - -``` -+-----------+--+ -| count(1) | -+-----------+--+ -| 1000000 | -+-----------+--+ -1 row selected (1.97 seconds) -``` - -## 和 Hive 一起使用 TiSpark - -TiSpark 可以和 Hive 混合使用。 -在启动 Spark 之前，需要添加 HADOOP_CONF_DIR 环境变量指向 Hadoop 配置目录并且将 `hive-site.xml` 拷贝到 `$SPARK_HOME/conf` 目录下。 - -``` -val tisparkDF = spark.sql("select * from tispark_table").toDF -tisparkDF.write.saveAsTable("hive_table") // save table to hive -spark.sql("select * from hive_table a, tispark_table b where a.col1 = b.col1").show // join table across Hive and Tispark -``` - -## 通过 JDBC 将 DataFrame 写入 TiDB - -暂时 TiSpark 不支持直接将数据写入 TiDB 集群，但可以使用 Spark 原生的 JDBC 支持进行写入： - -```scala -import org.apache.spark.sql.execution.datasources.jdbc.JDBCOptions - -val customer = spark.sql("select * from customer limit 100000") -// you might repartition source to make it balance across nodes -// and increase concurrency -val df = customer.repartition(32) -df.write -.mode(saveMode = "append") -.format("jdbc") -.option("driver", "com.mysql.jdbc.Driver") - // replace host and port as your and be sure to use rewrite batch -.option("url", "jdbc:mysql://127.0.0.1:4000/test?rewriteBatchedStatements=true") -.option("useSSL", "false") -// As tested, 150 is good practice -.option(JDBCOptions.JDBC_BATCH_INSERT_SIZE, 150) -.option("dbtable", s"cust_test_select") // database name and table name here -.option("isolationLevel", "NONE") // recommended to set isolationLevel to NONE if you have a large DF to load. -.option("user", "root") // TiDB user here -.save() -``` - -推荐将 `isolationLevel` 设置为 `NONE`，否则单一大事务有可能造成 TiDB 服务器内存溢出。 - -## 统计信息 - -TiSpark 可以使用 TiDB 的统计信息： - -1. 选择代价最低的索引或扫表访问 -2. 估算数据大小以决定是否进行广播优化 - -如果希望使用统计信息支持，需要确保所涉及的表已经被分析。请阅读[这份文档](https://pingcap.com/docs-cn/v3.0/reference/performance/statistics/)了解如何进行表分析。 - -从 TiSpark 2.0 开始，统计信息将会默认被读取。 - -统计信息将在 Spark Driver 进行缓存，请确定 Driver 内存足够缓存统计信息。 -可以在`spark-defaults.conf`中开启或关闭统计信息读取： - -| Property Name | Default | Description -| -------- | -----: | :----: | -| spark.tispark.statistics.auto_load | true | 是否默认进行统计信息读取 | - -## TiSpark FAQ - -- Q. 是独立部署还是和现有 Spark／Hadoop 集群共用资源？ - - A. 可以利用现有 Spark 集群无需单独部署，但是如果现有集群繁忙，TiSpark 将无法达到理想速度。 - -- Q. 是否可以和 TiKV 混合部署？ - - A. 如果 TiDB 以及 TiKV 负载较高且运行关键的线上任务，请考虑单独部署 TiSpark；并且考虑使用不同的网卡保证 OLTP 的网络资源不被侵占而影响线上业务。如果线上业务要求不高或者机器负载不大，可以考虑与 TiKV 混合部署。 - -- Q. Spark 执行中报 warning：WARN ObjectStore:568 - Failed to get database - - A. Warning 忽略即可，原因是 Spark 找不到对应的 hive 库，因为这个库是在 TIKV 中，而不是在 hive 中。可以考虑调整 [log4j 日志](https://github.com/pingcap/tidb-docker-compose/blob/master/tispark/conf/log4j.properties#L43)，将该参数添加到 spark 下 conf 里 log4j 文件(如果后缀是 template 那先 mv 成后缀 properties)。 - -- Q. Spark 执行中报 java.sql.BatchUpdateException: Data Truncated - - A. 写入的数据长度超过了数据库定义的数据类型的长度，可以确认 target table 的字段长度，进行调整。 - -- Q. TiSpark 任务是否默认读取 Hive 的元数据？ - - A. TiSpark 通过读取 hive-site 里的 meta 来搜寻 hive 的库。如果搜寻不到，就通过读取 tidb meta 搜寻 tidb 库。如果不需要该行为，可不在 hive site 中配置 hive 的 meta。 - -- Q. TiSpark 执行 Spark 任务时报：Error：java.io.InvalidClassException: com.pingcap.tikv.region.TiRegion; local class incompatible: stream classdesc serialVersionUID ... - - A. 该报错日志中显示 serialVersionUID 冲突，说明存在不同版本的 class 和 TiRegion。因为 TiRegion 是 TiSpark 独有的，所以可能存在多个版本的 TiSpark 包。要解决该报错，请确保集群中各节点的 TiSpark 依赖包版本一致。 diff --git a/v3.0/reference/tools/data-migration/cluster-operations.md b/v3.0/reference/tools/data-migration/cluster-operations.md deleted file mode 100644 index 5643d92d15e3..000000000000 --- a/v3.0/reference/tools/data-migration/cluster-operations.md +++ /dev/null @@ -1,490 +0,0 @@ ---- -title: DM 集群操作 -category: reference -aliases: ['/docs-cn/tools/dm/cluster-operations/'] ---- - -# DM 集群操作 - -本文介绍 DM 集群操作以及使用 DM-Ansible 管理 DM 集群时需要注意的事项。 - -## 启动集群 - -运行以下命令以启动整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook start.yml -``` - -## 下线集群 - -运行以下命令以下线整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -## 重启集群组件 - -在以下情况下，需要更新 DM 集群组件： - -- 您想要[更新组件版本](#更新组件版本)。 -- 发生了严重的错误，您需要重启组件完成临时恢复。 -- DM 集群所在的机器由于某种原因重启。 - -### 重启注意事项 - -该部分描述重启 DM 各组件时需要了解的事项。 - -#### DM-worker 重启事项 - -**全量数据导入过程中：** - -对于全量数据导入时的 SQL 文件，DM 使用下游数据库记录断点信息，DM-worker 会在本地 meta 文件记录子任务信息。DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -**增量数据同步过程中：** - -对于增量数据导入过程中的 binlog，DM 使用下游数据库记录断点信息，并会在同步任务开始或恢复后的第一个五分钟之内开启安全模式。 - -+ 未启用 sharding DDL 同步 - - 如果 DM-worker 上运行的任务未启用 sharding DDL 同步功能，DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -+ 已启用 sharding DDL 同步 - - - DM 同步 sharding DDL 语句时，如果 DM-worker 成功执行（或跳过）sharding DDL 的 binlog event，与 DM-worker 中的 sharding DDL 语句相关的所有表的断点信息都会被更新至 DDL 语句对应的 binlog event 之后的位置。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步开始前或完成后，DM-worker 会根据断点信息和本地记录的子任务信息自动恢复数据同步。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步过程中，可能会出现作为 DDL lock owner 的 DM-worker 实例已执行了 DDL 语句并成功变更了下游数据库表结构，但其他 DM-worker 实例重启而无法跳过 DDL 语句也无法更新断点的情况。 - - 此时 DM 会再次尝试同步这些未跳过执行的 DDL 语句。然而，由于未重启的 DM-worker 实例已经执行到了此 DDL 对应的 binlog event 之后，重启的 DM-worker 实例会被阻滞在重启前 DDL binlog event 对应的位置。 - - 要解决这个问题，请按照[手动处理 Sharding DDL Lock](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#场景二unlock-过程中部分-dm-worker-重启) 中描述的步骤操作。 - -**总结**：尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -#### DM-master 重启事项 - -由 DM-master 维护的信息包括以下两种。重启 DM-master 不会持久化保存这些信息的相关数据。 - -- 任务信息 -- Sharding DDL lock 信息 - -DM-master 重启时会自动向每个 DM-worker 实例请求任务信息，重建任务与 DM-worker 之间的对应关系，并从每个 DM-worker 实例获取 sharding DDL 信息。这样，就可以准确重建相应的 DDL lock，也可以自动解除 sharding DDL lock。 - -### 重启 DM-worker - -> **注意：** -> -> 尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -使用以下两种方法中任一种重启 DM-worker 组件： - -- 对 DM-worker 执行滚动升级。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - -- 先停止 DM-worker，然后重启。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker && - ansible-playbook start.yml --tags=dm-worker - ``` - -### 重启 DM-master - -在以下两种方法中任选一种，重启 DM-master 组件： - -- 对 DM-master 执行滚动升级。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -- 停止 DM-master，然后重启。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-master && - ansible-playbook start.yml --tags=dm-master - ``` - -## 更新组件版本 - -1. 下载 DM 二进制文件。 - - 1. 从 `downloads` 目录删除已有文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - rm -rf downloads - ``` - - 2. 用 Playbook 下载 inventory.ini 文件中指定版本的最新 DM 二进制文件。这会自动替换 `/home/tidb/dm-ansible/resource/bin/` 中已有文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -2. 使用 Ansible 执行滚动升级。 - - 1. 对 DM-worker 实例执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - - 2. 对 DM-master 实例执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - - 3. 升级 dmctl： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dmctl - ``` - - 4. 对 DM-worker， DM-master， 以及 dmctl 整体执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -## 创建 DM-worker 实例 - -假设您想要在机器 `172.16.10.74` 上创建一个名为 `dm_worker3` 的 DM-worker 实例，按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v3.0/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 用户登录至中控机，并将 `172.16.10.74` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.74 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.74`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.74` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 修改 `inventory.ini` 文件，创建新 DM-worker 实例 `dm_worker3`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -3. 部署新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-worker -l dm_worker3 - ``` - -4. 启用新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-worker -l dm_worker3 - ``` - -5. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -6. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 下线 DM-worker 实例 - -假设您想要下线的 DM-worker 实例为 `dm_worker3`。按以下步骤操作： - -1. 关闭您想要下线的 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker -l dm_worker3 - ``` - -2. 修改 `inventory.ini` 文件，注释或删除 `dm_worker3` 实例所在行。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - # dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 # Comment or delete this line - ``` - -3. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -4. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 替换/迁移 DM-master 实例 - -假设机器 `172.16.10.71` 需要进行维护或者已崩溃，需要将 DM-master 实例从 `172.16.10.71` 迁移至 `172.16.10.80`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v3.0/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.80` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.80 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.80`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.80` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 关闭待替换的 DM-master 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-master - ``` - -3. 修改 `inventory.ini` 文件。注释或删除待替换实例所在行，同时为新 DM-master 实例添加相关信息。 - - ```ini - [dm_master_servers] - # dm_master ansible_host=172.16.10.71 - dm_master ansible_host=172.16.10.80 - ``` - -4. 部署新 DM-master 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-master - ``` - -5. 启用新 DM-master 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-master - ``` - -6. 更新 dmctl 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dmctl - ``` - -## 替换/迁移 DM-worker 实例 - -假设机器 `172.16.10.72` 需要进行维护或者已崩溃，您需要将 `dm_worker1` 实例从 `172.16.10.72` 迁移至 `172.16.10.75`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v3.0/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.75` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.75 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.85`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.75` 上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 下线待替换 DM-worker 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker -l dm_worker1 - ``` - -3. 修改 `inventory.ini` 文件，为新 DM-worker 实例添加相关信息。 - - 修改 `inventory.ini` 文件。注释或删除旧 `dm_worker1` 实例所在行；同时为新 `dm_worker1` 实例添加相关信息。 - - 如果希望从不同的 binlog position 或 GTID Sets 拉取 relay log，则也需要更新对应的 `{relay_binlog_name}` 或 `{relay_binlog_gtid}`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.75 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - # dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -4. 部署新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-worker -l dm_worker1 - ``` - -5. 迁移 relay log 数据。 - - - 如果待替换 DM-worker 实例所在机器仍能访问，则可直接将该实例的 `{dm_worker_relay_dir}` 目录下的所有数据复制到新 DM-worker 实例的对应目录。 - - - 如果待替换 DM-worker 实例所在机器已无法访问，可能需在第 9 步中手动恢复 relay log 目录等信息。 - -6. 启动新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-worker -l dm_worker1 - ``` - -7. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -8. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -9. 启动并验证数据迁移任务。 - - 使用 `start-task` 命令启动数据迁移任务，如果任务运行正常，则表示 DM-worker 迁移顺利完成；如果报类似如下错误，则需要对 relay log 目录进行手动修复。 - - ```log - fail to initial unit Sync of subtask test-task : UUID suffix 000002 with UUIDs [1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001] not found - ``` - - 如果待替换 DM-worker 所连接的上游 MySQL 已发生过切换，则会产生如上错误。此时可通过如下步骤手动修复： - - 1. 使用 `stop-task` 命令停止数据迁移任务。 - - 2. 通过 `$ ansible-playbook stop.yml --tags=dm-worker -l dm_worker1` 停止 DM-worker 实例。 - - 3. 更新 relay log 子目录的后缀，例如将 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 重命名为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 4. 更新 relay log 子目录索引文件 `server-uuid.index`，例如将其中的内容由 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 变更为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 5. 通过 `$ ansible-playbook start.yml --tags=dm-worker -l dm_worker1` 启动 DM-worker 实例。 - - 6. 再次启动并验证数据迁移任务。 diff --git a/v3.0/reference/tools/data-migration/configure/dm-master-configuration-file.md b/v3.0/reference/tools/data-migration/configure/dm-master-configuration-file.md deleted file mode 100644 index 6d01371b976b..000000000000 --- a/v3.0/reference/tools/data-migration/configure/dm-master-configuration-file.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: DM-master 配置文件介绍 -category: reference ---- - -# DM-master 配置文件介绍 - -本文介绍 DM-master 的配置文件，包括配置文件示例与配置项说明。 - -## 配置文件示例 - -DM-master 的示例配置文件如下所示： - -```toml -# log configuration -log-file = "dm-master.log" - -# DM-master listening address -master-addr = ":8261" - -# DM-worker deployment. It will be refined when the new deployment function is available. -[[deploy]] -source-id = "mysql-replica-01" -dm-worker = "172.16.10.72:8262" - -[[deploy]] -source-id = "mysql-replica-02" -dm-worker = "172.16.10.73:8262" -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置，日志会输出到标准输出中。 | -| `master-addr` | DM-master 服务的地址，可以省略 IP 信息，例如：":8261"。 | - -### DM-Worker 的配置 - -配置在 `deploy` 中，每一个 DM-worker 都需要设置一个 `deploy`。 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `source-id` | 一个 replication group 或者 MySQL/MariaDB 实例的标识，需要和 DM-worker 中的 `source-id` 一致。 | -| `dm-worker` | DM-worker 的服务地址。 | diff --git a/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md b/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md deleted file mode 100644 index 4b794e2f49f7..000000000000 --- a/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: DM-worker 完整配置说明 -category: reference ---- - -# DM-worker 完整配置说明 - -本文完整地介绍 DM-worker 的配置，包括配置文件示例与配置项说明。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker listening address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in the replication group should have a different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory used to store relay log. -relay-dir = "./relay_log" - -# Enables gtid in the relay log unit -enable-gtid = false - -relay-binlog-name = "" -relay-binlog-gtid = "" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 - -# Relay log purge strategy. -[purge] -interval = 3600 -expires = 24 -remain-space = 15 - -# Task status checker. -[checker] -check-enable = true -backoff-rollback = "5m" -backoff-max = "5m" -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-level` | 日志等级，值可以为 "debug"、"info"、"warn"、"error"、"fatal"，默认值为 "info"。一般情况下不需要手动配置，如果需要排查问题，可以将等级设置为 "debug"。 | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。 | -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中必须是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | -| `enable-gtid` | 是否使用 GTID 方式从上游拉取 binlog，默认值为 false。一般情况下不需要手动配置，如果上游数据库启用了 GTID 支持，且需要做主从切换，则将该配置项设置为 true。 | -| `relay-binlog-name` | 拉取上游 binlog 的起始文件名，例如 "mysql-bin.000002"，该配置在 `enable-gtid` 为 false 的情况下生效。如果不配置该项，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 | -| `relay-binlog-gtid` | 拉取上游 binlog 的起始 GTID，例如 "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"，该配置在 `enable-gtid` 为 true 的情况下生效。如果不配置该项，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog GTID 开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog GTID 开始拉取 binlog，一般情况下不需要手动配置。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。 | -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -### relay log 清理策略配置（purge 配置项） - -一般情况下不需要手动配置，如果 relay log 数据量较大，磁盘空间不足，则可以通过该配置项设置，避免 relay log 写满磁盘。 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `interval` | 定期检查 relay log 是否过期的间隔时间，默认值：3600，单位：秒。 | -| `expires` | relay log 的过期时间，默认值为 0，单位：小时。超过过期时间的 relay log 会被 DM 删除。如果不设置则 DM 不会自动清理过期的 relay log。 | -| `remain-space` | 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log，默认值：15，单位：GB。 | - -> **注意：** -> -> 仅在 `interval` 不为 0 且 `expires` 和 `remain-space` 两个配置项中至少有一个不为 0 的情况下 DM 的自动清理策略才会生效。 - -### 任务检查模块配置（checker 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `check-enable` | 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务，默认值：true。 | -| `backoff-rollback` | 任务检查模块中，定时调整恢复等待时间的间隔，默认值："5m0s"。 | -| `backoff-max` | 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔，默认值："5m0s"。 | - -> **注意：** -> -> 用户只需要通过配置 `check-enable` 开启或者关闭任务状态检查功能。对于 `backoff-rollback` 和 `backoff-max` 一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改这两项参数。 diff --git a/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file.md b/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file.md deleted file mode 100644 index 1b1a997c04e6..000000000000 --- a/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: DM-worker 配置文件介绍 -category: reference ---- - -# DM-worker 配置文件介绍 - -本文档主要介绍 DM-worker 的基础配置文件。在一般场景中，用户只需要使用基础配置即可完成 DM-worker 的部署。 - -完整配置项参考 [DM-worker 完整配置说明](/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-file = "dm-worker.log" - -# DM-worker listen address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in replication group should have different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory that used to store relay log. -relay-dir = "./relay_log" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。| -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。| -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -> **注意：** -> -> 以上配置为部署 DM-worker 的基础配置，一般情况下使用基础配置即可，更多配置项参考 [DM-worker 完整配置说明](/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 diff --git a/v3.0/reference/tools/data-migration/configure/overview.md b/v3.0/reference/tools/data-migration/configure/overview.md deleted file mode 100644 index 10a711cb1c1f..000000000000 --- a/v3.0/reference/tools/data-migration/configure/overview.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: DM 配置简介 -category: reference -aliases: ['/docs-cn/tools/dm/dm-configuration-file-overview/'] ---- - -# DM 配置简介 - -本文档简要介绍 DM (Data Migration) 的配置文件和数据同步任务的配置。 - -## 配置文件 - -- `inventory.ini`：使用 DM-Ansible 部署 DM 集群的配置文件。需要根据所选用的集群拓扑来进行编辑。详见[编辑 `inventory.ini` 配置文件](/v3.0/how-to/deploy/data-migration-with-ansible.md#第-7-步编辑-inventoryini-配置文件)。 -- `dm-master.toml`：DM-master 进程的配置文件，包括 DM 集群的拓扑信息、MySQL 实例与 DM-worker 之间的关系（必须为一对一的关系）。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-master.toml` 文件，各项配置说明详见 [DM-master 配置文件介绍](/v3.0/reference/tools/data-migration/configure/dm-master-configuration-file.md) -- `dm-worker.toml`：DM-worker 进程的配置文件，包括上游 MySQL 实例的配置和 relay log 的配置。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-worker.toml` 文件，各项配置说明详见 [DM-worker 配置文件介绍](/v3.0/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - -## 同步任务配置 - -### 任务配置文件 - -使用 DM-Ansible 部署 DM 集群时，`/conf` 中提供了任务配置文件模板：`task.yaml.exmaple` 文件。该文件是 DM 同步任务配置的标准文件，每一个具体的任务对应一个 `task.yaml` 文件。关于该配置文件的详细介绍，参见 [任务配置文件](/v3.0/reference/tools/data-migration/configure/task-configuration-file.md)。 - -### 创建数据同步任务 - -你可以基于 `task.yaml.example` 文件来创建数据同步任务，具体步骤如下： - -1. 复制 `task.yaml.example` 为 `your_task.yaml`。 -2. 参考[任务配置文件](/v3.0/reference/tools/data-migration/configure/task-configuration-file.md)来修改 `your_task.yaml` 文件。 -3. [使用 dmctl 创建数据同步任务](/v3.0/reference/tools/data-migration/manage-tasks.md#创建数据同步任务)。 - -### 关键概念 - -DM 配置的关键概念如下： - -| 概念 | 解释 | 配置文件 | -| :------------ | :------------ | :------------------ | -| source-id | 唯一确定一个 MySQL 或 MariaDB 实例，或者一个具有主从结构的复制组，字符串长度不大于 32 | `inventory.ini` 的 `source_id`；
`dm-master.toml` 的 `source-id`；
`task.yaml` 的 `source-id` | -| DM-worker ID | 唯一确定一个 DM-worker（取值于 `dm-worker.toml` 的 `worker-addr` 参数） | `dm-worker.toml` 的 `worker-addr`；
dmctl 命令行的 `-worker` / `-w` flag | diff --git a/v3.0/reference/tools/data-migration/configure/task-configuration-file-full.md b/v3.0/reference/tools/data-migration/configure/task-configuration-file-full.md deleted file mode 100644 index cdc5b6e88d3a..000000000000 --- a/v3.0/reference/tools/data-migration/configure/task-configuration-file-full.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: DM 任务完整配置文件介绍 -category: reference ---- - -# DM 任务完整配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务完整的配置文件 [`task_advanced.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_advanced.yaml)，包含[全局配置](#全局配置) 和[实例配置](#实例配置) 两部分。 - -关于各配置项的功能和配置，请参阅[数据同步功能](/v3.0/reference/tools/data-migration/features/overview.md#同步功能介绍)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/v3.0/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 完整配置文件示例 - -下面是一个完整的配置文件示例，通过该示例可以完成复杂的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" -is-sharding: true # 是否为分库分表合并任务 -meta-schema: "dm_meta" # 下游储存 `meta` 信息的数据库 -remove-meta: false # 是否在任务同步开始前移除该任务名对应的 `meta`（`checkpoint` 和 `onlineddl` 等）。 -enable-heartbeat: false # 是否开启 `heartbeat` 功能 - -target-database: # 下游数据库实例配置 - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - - -## ******** 功能配置集 ********** - -routes: # 上游和下游表之间的路由 table routing 规则集 - route-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - target-schema: "test" # 目标库名称 - target-table: "t" # 目标表名称 - route-rule-2: - schema-pattern: "test_*" - target-schema: "test" - -filters: # 上游数据库实例匹配的表的 binlog event filter 规则集 - filter-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - events: ["truncate table", "drop table"] # 匹配哪些 event 类型 - action: Ignore # 对与符合匹配规则的 binlog 同步（Do）还是忽略(Ignore) - filter-rule-2: - schema-pattern: "test_*" - events: ["all dml"] - action: Do - -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 配置名称 - do-dbs: ["~^test.*", "user"] # 同步哪些库 - ignore-dbs: ["mysql", "account"] # 忽略哪些库 - do-tables: # 同步哪些表 - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "user" - tbl-name: "information" - ignore-tables: # 忽略哪些表 - - db-name: "user" - tbl-name: "log" - -mydumpers: # mydumper 处理单元运行配置参数 - global: # 配置名称 - mydumper-path: "./bin/mydumper" # mydumper binary 文件地址，默认值为 "./bin/mydumper" - threads: 4 # mydumper 从上游数据库实例导出数据的线程数量，默认值为 4 - chunk-filesize: 64 # mydumper 生成的数据文件大小，默认值为 64，单位为 MB - skip-tz-utc: true # 忽略对时间类型数据进行时区转化，默认值为 true - extra-args: "--no-locks" # mydumper 的其他参数，在 v1.0.2 版本中 DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置 - -loaders: # loader 处理单元运行配置参数 - global: # 配置名称 - pool-size: 16 # loader 并发执行 mydumper 的 SQL 文件的线程数量，默认值为 16 - dir: "./dumped_data" # loader 读取 mydumper 输出文件的地址，同实例对应的不同任务必须不同（mydumper 会根据这个地址输出 SQL 文件），默认值为 "./dumped_data" - -syncers: # syncer 处理单元运行配置参数 - global: # 配置名称 - worker-count: 16 # syncer 并发同步 binlog event 的线程数量，默认值为 16 - batch: 100 # syncer 同步到下游数据库的一个事务批次 SQL 语句数，默认值为 100 - -# ----------- 实例配置 ----------- -mysql-instances: - - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - meta: # `task-mode` 为 `incremental` 且下游数据库的 `checkpoint` 不存在时 binlog 同步开始的位置; 如果 checkpoint 存在，则以 `checkpoint` 为准 - binlog-name: binlog.000001 - binlog-pos: 4 - - route-rules: ["route-rule-1", "route-rule-2"] # 该上游数据库实例匹配的表到下游数据库的 table routing 规则名称 - filter-rules: ["filter-rule-1"] # 该上游数据库实例匹配的表的 binlog event filter 规则名称 - black-white-list: "bw-rule-1" # 该上游数据库实例匹配的表的 black & white list 过滤规则名称 - - mydumper-config-name: "global" # mydumper 配置名称 - loader-config-name: "global" # loader 配置名称 - syncer-config-name: "global" # Syncer 配置名称 - - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，等同于 mydumper 处理单元配置中的 `threads`，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，等同于 loader 处理单元配置中的 `pool-size`, 在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，等同于 syncer 处理单元配置中的 `worker-count`，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基本信息配置`和`实例配置`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。其中 `task-mode` 需要特殊说明： - -`task-mode` - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -全局配置主要包含下列功能配置集： - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `routes` | 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/v3.0/reference/tools/data-migration/features/overview.md#table-routing) | -| `filters` | 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) | -| `black-white-list` | 该上游数据库实例匹配的表的 black & white list 过滤规则集。建议通过该项指定需要同步的库和表，否则会同步所有的库和表。使用场景及示例配置参见 [Black & White Lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists) | -| `mydumpers` | mydumper 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 | -| `loaders` | loader 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 | -| `syncers` | syncer 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 | - -各个功能配置集的参数及解释参见[完整配置文件示例](#完整配置文件示例)中的注释说明。 - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 - -在该项配置中设置数据同步子任务中各个功能对应的配置集中的配置名称，关于这些配置项的更多配置细节，参见[功能配置集](#功能配置集)的相关配置项，对应关系如下： - -| 配置项 | 相关配置项 | -| :------ | :------------------ | -| `route-rules` | `routes` | -| `filter-rules` | `filters` | -| `black-white-list` | `black-white-list` | -| `mydumper-config-name` | `mydumpers` | -| `loader-config-name` | `loaders` | -| `syncer-config-name` | `syncers` | diff --git a/v3.0/reference/tools/data-migration/configure/task-configuration-file.md b/v3.0/reference/tools/data-migration/configure/task-configuration-file.md deleted file mode 100644 index 6a8f362f2145..000000000000 --- a/v3.0/reference/tools/data-migration/configure/task-configuration-file.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: DM 任务配置文件介绍 -category: reference -aliases: ['/docs-cn/tools/dm/task-configuration-file-intro/'] ---- - -# DM 任务配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务基础配置文件 [`task_basic.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_basic.yaml)，包含[全局配置](#全局配置)和[实例配置](#实例配置)两部分。 - -完整的任务配置参见 [DM 任务完整配置文件介绍](/v3.0/reference/tools/data-migration/configure/task-configuration-file-full.md) - -关于各配置项的功能和配置，请参阅[数据同步功能](/v3.0/reference/tools/data-migration/features/overview.md)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/v3.0/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 基础配置文件示例 - -下面是一个基础的配置文件示例，通过该示例可以完成简单的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" - -target-database: # 下游数据库实例配置 - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - -## ******** 功能配置集 ********** -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 黑白名单配置的名称 - do-dbs: ["all_mode"] # 同步哪些库 - -# ----------- 实例配置 ----------- -mysql-instances: - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基础信息配置`和`功能配置集`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。关于 `task-mode` 的特殊说明如下： - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -对于一般的业务场景，只需要配置黑白名单过滤规则集，配置说明参见以上示例配置文件中 `black-white-list` 的注释以及 [Black & white table lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists) - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 -配置项说明参见以上示例配置文件中 `mysql-instances` 的注释。 diff --git a/v3.0/reference/tools/data-migration/deploy.md b/v3.0/reference/tools/data-migration/deploy.md deleted file mode 100644 index 52f6094866da..000000000000 --- a/v3.0/reference/tools/data-migration/deploy.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: 使用 DM 同步数据 -category: reference -aliases: ['/docs-cn/tools/dm/practice/'] ---- - -# 使用 DM 同步数据 - -本文介绍如何使用 DM (Data Migration) 同步数据。 - -## 第 1 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照 [使用 DM-Ansible 部署 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md)；也可以使用 binary 部署 DM 集群用于体验或者测试，具体部署方法参照[使用 DM binary 部署 DM 集群](/v3.0/how-to/deploy/data-migration-with-binary.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 2 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 MySQL-1 | 172.16.10.81 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 MySQL-2 | 172.16.10.82 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - - > **注意：** - > - > `{ansible deploy}/conf/dm-master.toml` 中的 `{ansible deploy}` 表示使用 DM-Ansible 部署 DM 时通过 `deploy_dir` 参数指定的目录。 - -## 第 3 步：配置任务 - -假设需要将 MySQL-1 和 MySQL-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - mydumper-path: "./bin/mydumper" # Mydumper 二进制文件的路径。 - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 4 步：启动任务 - -为了提前发现数据同步任务的一些配置错误，DM 中增加了[前置检查](/v3.0/reference/tools/data-migration/precheck.md)功能： - -- 启动数据同步任务时，DM 自动检查相应的权限和配置。 -- 也可使用 `check-task` 命令手动前置检查上游的 MySQL 实例配置是否符合 DM 的配置要求。 - -> **注意：** -> -> 第一次启动数据同步任务时，必须确保上游数据库已配置。否则，启动任务时会报错。 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/`。 - -2. 执行以下命令启动 dmctl。 - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务。其中，`task.yaml` 是之前编辑的配置文件。 - - {{< copyable "" >}} - - ```bash - » start-task ./task.yaml - ``` - - - 如果执行该命令后返回的结果如下，则表明任务已成功启动。 - - ```json - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.10.72:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.10.73:8262", - "msg": "" - } - ] - } - ``` - - - 如果任务启动失败，可根据返回结果的提示进行配置变更后执行 `start-task task.yaml` 命令重新启动任务。 - -## 第 5 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "" >}} - -```bash -» query-status -``` - -## 第 6 步：停止任务 - -如果不再需要进行数据同步，可以在 dmctl 内使用以下命令停止同步任务： - -{{< copyable "" >}} - -```bash -» stop-task test -``` - -其中的 `test` 是 `task.yaml` 配置文件中 `name` 配置项设置的任务名。 - -## 第 7 步：监控任务与查看日志 - -如果使用 DM-Ansible 部署 DM 集群时，正确部署了 Prometheus 与 Grafana，且 Grafana 的地址为 `172.16.10.71`，可在浏览器中打开 进入 Grafana，选择 DM 的 dashboard 即可查看 DM 相关监控项。 - -DM 在运行过程中，DM-worker, DM-master 及 dmctl 都会通过日志输出相关信息。各组件的日志目录如下： - -- DM-master 日志目录：通过 DM-master 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-master 节点的 `{ansible deploy}/log/dm-master.log`。 -- DM-worker 日志目录：通过 DM-worker 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-worker 节点的 `{ansible deploy}/log/dm-worker.log`。 -- dmctl 日志目录：与其二进制文件目录相同。 diff --git a/v3.0/reference/tools/data-migration/dm-portal.md b/v3.0/reference/tools/data-migration/dm-portal.md deleted file mode 100644 index c04b4edeb42d..000000000000 --- a/v3.0/reference/tools/data-migration/dm-portal.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: DM Portal 简介 -category: reference ---- - -# DM Portal 简介 - -当前版本的 DM 提供了丰富多样的功能特性，包括 [Table routing](/v3.0/reference/tools/data-migration/features/overview.md#table-routing)，[Black & white table lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists)，[Binlog event filter](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) 等。但这些功能特性同时也增加了用户使用 DM 的复杂度，尤其在编写 [DM 任务配置](/v3.0/reference/tools/data-migration/configure/task-configuration-file.md)的时候。 - -针对这个问题，DM 提供了一个精简的网页程序 DM Portal，能够帮助用户以可视化的方式去配置需要的同步任务，并且生成可以直接让 DM 直接执行的 `task.yaml` 文件。 - -## 功能描述 - -### 同步模式配置 - -支持 DM 的三种同步模式： - -- 全量同步 -- 增量同步 -- All（全量+增量） - -### 实例信息配置 - -支持配置库表同步路由方式，能够支持 DM 中分库分表合并的配置方式。 - -### binlog 过滤配置 - -支持对数据库、数据表配置 binlog event 过滤。 - -### 配置文件生成 - -支持配置文件创建，能够将配置文件下载到本地并且同时会在 dm-portal 服务器的 `/tmp/` 目录下自动创建。 - -### 使用限制 - -当前的 DM 配置可视化生成页面能够覆盖绝大部分的 DM 配置场景，但也有一定的使用限制： - -- 不支持 [Binlog event filter](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) 的 SQL pattern 方式 -- 编辑功能不支持解析用户之前写的 `task.yaml` 文件，页面只能编辑由页面生成的 `task.yaml` 文件 -- 编辑功能不支持修改实例配置信息，如果用户需要调整实例配置，需要重新生成 `task.yaml` 文件 -- 页面的上游实例配置仅用于获取上游库表结构，DM-worker 里依旧需要配置对应的上游实例信息 -- 生成的 `task.yaml` 中，默认 mydumper-path 为 `./bin/mydumper`，如果实际使用其他路径，需要在生成的配置文件中进行手动修改。 - -## 部署使用 - -### Binary 部署 - -DM Portal 可以在 [dm-portal-latest-linux-amd64.tar.gz](https://download.pingcap.org/dm-portal-latest-linux-amd64.tar.gz) 下载，通过 `./dm-portal` 的命令即可直接启动。 - -* 如果在本地启动，浏览器访问 `127.0.0.1:8280` 即可使用。 -* 如果在服务器上启动，需要为服务器上配置访问代理。 - -### DM Ansible 部署 - -可以使用 DM Ansible 部署 DM Portal，具体部署方法参照[使用 DM Ansible 部署 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md)。 - -## 使用说明 - -### 新建规则 - -#### 功能描述 - -用于新建一个 `task.yaml` 文件，需要选择同步模式、配置上下游实例、配置库表路由，配置 binlog 过滤。 - -#### 操作步骤 - -登录 dm-portal 页面，点击**新建任务规则**。 - -### 基础信息配置 - -#### 功能描述 - -用于填写任务名称，以及选择任务类型。 - -#### 前置条件 - -已选择**新建同步规则**。 - -#### 操作步骤 - -1. 填写任务名称。 -2. 选择任务类型。 - -![DM Portal BasicConfig](/media/dm-portal-basicconfig.png) - -### 实例信息配置 - -#### 功能描述 - -用于配置上下游实例信息，包括 Host、Port、Username、Password。 - -#### 前置条件 - -已填写任务名称和选择任务类型。 - -#### 注意事项 - -如果任务类型选择**增量**或者 **All**，在配置上游实例信息时候，还需要配置 binlog-file 和 binlog-pos。 - -#### 操作步骤 - -1. 填写上游实例信息。 -2. 填写下游实例信息。 -3. 点击**下一步**。 - -![DM Portal InstanceConfig](/media/dm-portal-instanceconfig.png) - -### binlog 过滤配置 - -#### 功能描述 - -用于配置上游的 binlog 过滤，可以选择需要过滤的 DDL/DML，并且在数据库上配置的 filter 后会自动给其下的数据表继承。 - -#### 前置条件 - -已经配置好上下游实例信息并且连接验证没问题。 - -#### 注意事项 - -* binlog 过滤配置只能在上游实例处进行修改编辑，一旦数据库或者数据表被移动到下游实例后，就不可以进行修改编辑。 -* 在数据库上配置的 binlog 过滤会自动被其下的数据表继承。 - -#### 操作步骤 - -1. 点击需要配置的数据库或者数据表。 -2. 点击编辑按钮，选择需要过滤的 binlog 类型。 - -![DM Portal InstanceShow](/media/dm-portal-instanceshow.png) - -![DM Portal BinlogFilter 1](/media/dm-portal-binlogfilter-1.png) - -![DM Portal BinlogFilter 2](/media/dm-portal-binlogfilter-2.png) - -### 库表路由配置 - -#### 功能描述 - -可以选择需要同步的数据库和数据表，并且进行修改名称、合并库、合并表等操作。可以对上一步操作进行撤销，可以对库表路由配置进行全部重置。在完成任务配置后，DM Portal 会帮忙生成对应的 `task.yaml` 文件。 - -#### 前置条件 - -* 已经配置好需要的 binlog 过滤规则。 - -#### 注意事项 - -* 在合并库表操作的时候，不允许批量操作，只能逐一拖动。 -* 在合表库表操作的时候，只能对数据表进行拖动操作，不能对数据库进行数据库进行拖动操作。 - -#### 操作步骤 - -1. 在**上游实例**处，选择需要同步的数据库和数据表。 -2. 点击移动按钮，将需要同步的库表移动至**下游实例**处。 -3. 点击右键按钮，可以对库表进行改名操作。 -4. 选中需要操作的数据表，可以拖动至别的数据表图标上创建出合并表；可以拖动到数据库图标上移动至该库下；可以拖动到 target-instance 图标上移动到一个新的数据库下。 -5. 点击**完成**，自动下载 `task.yaml` 到本地，并且在 DM Portal 服务器上的 `/tmp/` 目录下自动创建一份 `task.yaml` 配置文件。 - -##### 移动同步库表 - -![DM Portal TableRoute 1](/media/dm-portal-tableroute-1.png) - -![DM Portal TableRoute 2](/media/dm-portal-tableroute-2.png) - -##### 右键修改库表名称 - -![DM Portal ChangeTableName](/media/dm-portal-changetablename.png) - -##### 合并数据表操作 - -![DM Portal MergeTable 1](/media/dm-portal-mergetable-1.png) - -![DM Portal MergeTable 2](/media/dm-portal-mergetable-2.png) - -##### 移动数据表至其他数据库 - -![DM Portal MoveToDB 1](/media/dm-portal-movetodb-1.png) - -![DM Portal MoveToDB 2](/media/dm-portal-movetodb-2.png) - -##### 移动数据表至新建默认数据库 - -![DM Portal MoveToNewDB 1](/media/dm-portal-movetonewdb-1.png) - -![DM Portal MoveToNewDB 2](/media/dm-portal-movetonewdb-2.png) - -##### 撤销本次操作 - -![DM Portal Revert](/media/dm-portal-revert.png) - -##### 清空下游实例 - -![DM Portal Reset](/media/dm-portal-reset.png) - -##### 完成并下载 - -![DM Portal GenerateConfig](/media/dm-portal-generateconfig.png) - -### 编辑规则 - -#### 功能描述 - -可以将之前创建的 `task.yaml` 上传后，解析出来之前的填写的配置信息，对部分配置进行修改。 - -#### 前置条件 - -* 已经创建出 `task.yaml` 文件。 -* 非 DM Portal 创建出来的 `task.yaml` 文件不可使用。 - -#### 注意事项 - -* 不允许修改实例配置信息 - -#### 操作步骤 - -1. 在首页，点击**编辑同步规则**。 -2. 选择上传 `task.yaml` 文件。 -3. 解析成功后，页面会自动跳转。 - -![DM Portal EditConfig](/media/dm-portal-editconfig.png) - -![DM Portal UploadConfig](/media/dm-portal-uploadconfig.png) diff --git a/v3.0/reference/tools/data-migration/dm-upgrade.md b/v3.0/reference/tools/data-migration/dm-upgrade.md deleted file mode 100644 index aa7d02b240e4..000000000000 --- a/v3.0/reference/tools/data-migration/dm-upgrade.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: DM 版本升级 -category: reference -aliases: ['/docs-cn/tools/dm/dm-upgrade/'] ---- - -# DM 版本升级 - -本文档主要介绍各 DM (Data Migration) 版本间的升级操作步骤。 - -> **注意：** -> -> - 若无特殊说明，各版本的升级操作均为从前一个有升级指引的版本向当前版本升级。 -> - 若无特殊说明，各升级操作示例均假定已经下载了对应版本的 DM 和 DM-Ansible 且 DM binary 存在于 DM-Ansible 的相应目录中（下载 DM binary 可以参考[更新组件版本](/v3.0/reference/tools/data-migration/cluster-operations.md#更新组件版本)）。 -> - 若无特殊说明，各升级操作示例均假定升级前已停止所有同步任务，升级完成后手动重新启动所有同步任务。 -> - 以下版本升级指引逆序展示。 - -## 升级到 v1.0.3 - -### 版本信息 - -```bash -Release Version: v1.0.3 -Git Commit Hash: 41426af6cffcff9a325697a3bdebeadc9baa8aa6 -Git Branch: release-1.0 -UTC Build Time: 2019-12-13 07:04:53 -Go Version: go version go1.13 linux/amd64 -``` - -### 主要变更 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.3` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.3 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.2 - -### 版本信息 - -```bash -Release Version: v1.0.2 -Git Commit Hash: affc6546c0d9810b0630e85502d60ed5c800bf25 -Git Branch: release-1.0 -UTC Build Time: 2019-10-30 05:08:50 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 支持自动为 DM-worker 生成部分配置项，减少人工配置成本 -- 支持自动生成 mydumper 库表参数，减少人工配置成本 -- 优化 `query-status` 默认输出，突出重点信息 -- 直接管理到下游的 DB 连接而不是使用内置连接池，优化 SQL 错误处理与重试 -- 修复 DM-worker 进程启动时、执行 DML 失败时可能 panic 的 bug -- 修复执行 sharding DDL（如 ADD INDEX）超时后可能造成后续 sharding DDL 无法正确协调的 bug -- 修复了有部分 DM-worker 不可访问时无法 `start-task` 的 bug -- 完善了对 1105 错误的自动重试策略 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.2` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.2 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.1 - -### 版本信息 - -```bash -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 修复某些情况下 DM 会频繁重建数据库连接的问题 -- 修复使用 `query-status` 时潜在的 panic 问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.1` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.1 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-10-geb2889c9 (1.0 GA) - -### 版本信息 - -```bash -Release Version: v1.0.0-10-geb2889c9 -Git Commit Hash: eb2889c9dcfbff6653be9c8720a32998b4627db9 -Git Branch: release-1.0 -UTC Build Time: 2019-09-06 03:18:48 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 常见的异常场景支持自动尝试恢复同步任务 -- 提升 DDL 语法兼容性 -- 修复上游数据库连接异常时可能丢失数据的 bug - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.0` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0 GA 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-rc.1-12-gaa39ff9 - -### 版本信息 - -```bash -Release Version: v1.0.0-rc.1-12-gaa39ff9 -Git Commit Hash: aa39ff981dfb3e8c0fa4180127246b253604cc34 -Git Branch: dm-master -UTC Build Time: 2019-07-24 02:26:08 -Go Version: go version go1.11.2 linux/amd64 -``` - -### 主要变更 - -从此版本开始，将对所有的配置进行严格检查，遇到无法识别的配置会报错，以确保用户始终准确地了解自己的配置。 - -### 升级操作示例 - -启动 DM-master 或 DM-worker 前，必须确保已经删除废弃的配置信息，且没有多余的配置项，否则会启动失败。可根据失败信息删除多余的配置。 -可能遗留的废弃配置： - -- `dm-worker.toml` 中的 `meta-file` -- `task.yaml` 中的 `mysql-instances` 中的 `server-id` diff --git a/v3.0/reference/tools/data-migration/dm-worker-intro.md b/v3.0/reference/tools/data-migration/dm-worker-intro.md deleted file mode 100644 index 41ed6b35e456..000000000000 --- a/v3.0/reference/tools/data-migration/dm-worker-intro.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: DM-worker 简介 -category: reference -aliases: ['/docs-cn/tools/dm/dm-worker-intro/'] ---- - -# DM-worker 简介 - -DM-worker 是 DM (Data Migration) 的一个组件，负责执行具体的数据同步任务。 - -其主要功能如下： - -- 注册为一台 MySQL 或 MariaDB 服务器的 slave。 -- 读取 MySQL 或 MariaDB 的 binlog event，并将这些 event 持久化保存在本地 (relay log)。 -- 单个 DM-worker 支持同步一个 MySQL 或 MariaDB 实例的数据到下游的多个 TiDB 实例。 -- 多个 DM-Worker 支持同步多个 MySQL 或 MariaDB 实例的数据到下游的一个 TiDB 实例。 - -## DM-worker 处理单元 - -DM-worker 任务包含如下多个逻辑处理单元。 - -### Relay log - -Relay log 持久化保存从上游 MySQL 或 MariaDB 读取的 binlog，并对 binlog replication 处理单元提供读取 binlog event 的功能。 - -其原理和功能与 MySQL slave relay log 类似，详见 [Slave Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html)。 - -### Dumper - -Dumper 从上游 MySQL 或 MariaDB 导出全量数据到本地磁盘。 - -### Loader - -Loader 读取 dumper 处理单元的数据文件，然后加载到下游 TiDB。 - -### Binlog replication/Syncer - -Binlog replication/Syncer 读取 relay log 处理单元的 binlog event，将这些 event 转化为 SQL 语句，再将这些 SQL 语句应用到下游 TiDB。 - -## DM-worker 所需权限 - -本小节主要介绍使用 DM-worker 时所需的上下游数据库用户权限以及各处理单元所需的用户权限。 - -### 上游数据库用户权限 - -上游数据库 (MySQL/MariaDB) 用户必须拥有以下权限： - -| 权限 | 作用域 | -|:----|:----| -| `SELECT` | Tables | -| `RELOAD` | Global | -| `REPLICATION SLAVE` | Global | -| `REPLICATION CLIENT` | Global | - -如果要同步 `db1` 的数据到 TiDB，可执行如下的 `GRANT` 语句： - -{{< copyable "sql" >}} - -```sql -GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_wildcard_of_host' -GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; -``` - -如果还要同步其他数据库的数据到 TiDB, 请确保已赋予这些库跟 `db1` 一样的权限。 - -### 下游数据库用户权限 - -下游数据库 (TiDB) 用户必须拥有以下权限： - -| 权限 | 作用域 | -|:----|:----| -| `SELECT` | Tables | -| `INSERT` | Tables | -| `UPDATE`| Tables | -| `DELETE` | Tables | -| `CREATE` | Databases，tables | -| `DROP` | Databases，tables | -| `ALTER` | Tables | -| `INDEX` | Tables | - -对要执行同步操作的数据库或表执行下面的 `GRANT` 语句： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,INDEX ON db.table TO 'your_user'@'your_wildcard_of_host'; -``` - -### 处理单元所需的最小权限 - -| 处理单元 | 最小上游 (MySQL/MariaDB) 权限 | 最小下游 (TiDB) 权限 | 最小系统权限 | -|:----|:--------------------|:------------|:----| -| Relay log | `REPLICATION SLAVE` (读取 binlog）
`REPLICATION CLIENT` (`show master status`, `show slave status`) | 无 | 本地读/写磁盘 | -| Dumper | `SELECT`
`RELOAD`（获取读锁将表数据刷到磁盘，进行一些操作后，再释放读锁对表进行解锁）| 无 | 本地写磁盘 | -| Loader | 无 | `SELECT`（查询 checkpoint 历史）
`CREATE`（创建数据库或表）
`DELETE`（删除 checkpoint）
`INSERT`（插入 dump 数据）| 读/写本地文件 | -| Binlog replication | `REPLICATION SLAVE`（读 binlog）
`REPLICATION CLIENT` (`show master status`, `show slave status`) | `SELECT`（显示索引和列）
`INSERT` (DML)
`UPDATE` (DML)
`DELETE` (DML)
`CREATE`（创建数据库或表）
`DROP`（删除数据库或表）
`ALTER`（修改表）
`INDEX`（创建或删除索引）| 本地读/写磁盘 | - -> **注意：** -> -> 这些权限并非一成不变。随着需求改变，这些权限也可能会改变。 diff --git a/v3.0/reference/tools/data-migration/faq.md b/v3.0/reference/tools/data-migration/faq.md deleted file mode 100644 index 0adabc0dbc2e..000000000000 --- a/v3.0/reference/tools/data-migration/faq.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Data Migration 常见问题 -category: FAQ -aliases: ['/docs-cn/v3.0/faq/data-migration/'] ---- - -# Data Migration 常见问题 - -## DM 是否支持同步阿里 RDS 以及其他云数据库的数据？ - -DM 仅支持解析标准版本的 MySQL/MariaDB 的 binlog，对于阿里云 RDS 以及其他云数据库没有进行过测试，如果确认其 binlog 为标准格式，则可以支持。 - -## task 配置中的黑白名单的正则表达式是否支持`非获取匹配`（?!）？ - -目前不支持，DM 仅支持 golang 标准库的正则，可以通过 [re2-syntax](https://github.com/google/re2/wiki/Syntax) 了解 golang 支持的正则表达式。 - -## 如果在上游执行的一个 statement 包含多个 DDL 操作，DM 是否支持同步？ - -DM 会尝试将包含多个 DDL 变更操作的单条语句拆分成只包含一个 DDL 操作的多条语句，但是可能没有覆盖所有的场景。建议在上游执行的一条 statement 中只包含一个 DDL 操作，或者在测试环境中验证一下，如果不支持，可以给 DM 提 [issue](https://github.com/pingcap/dm/issues)。 - -## 如何处理不兼容的 DDL 语句？ - -你需要使用 dmctl 手动处理 TiDB 不兼容的 DDL 语句（包括手动跳过该 DDL 语句或使用用户指定的 DDL 语句替换原 DDL 语句，详见[跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句](/v3.0/reference/tools/data-migration/skip-replace-sqls.md)）。 - -> **注意：** -> -> TiDB 目前并不兼容 MySQL 支持的所有 DDL 语句。 - -## 如何重置数据同步任务？ - -在以下情况中，你需要重置整个数据同步任务： - -- 上游数据库中人为执行了 `RESET MASTER`，造成 relay log 同步出错 - -- relay log 或上游 binlog event 损坏或者丢失 - -此时，relay 处理单元通常会发生错误而退出，且无法优雅地自动恢复，因此需要通过手动方式恢复数据同步： - -1. 使用 `stop-task` 命令停止当前正在运行的所有同步任务。 - -2. 使用 Ansible [停止整个 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md#第-10-步关闭-dm-集群)。 - -3. 手动清理掉与 binlog event 被重置的 MySQL master 相对应的 DM-worker 的 relay log 目录。 - - - 如果是使用 Ansible 部署，relay log 目录即 `/relay_log` 目录。 - - 如果是使用二进制文件手动部署，relay log 目录即 relay-dir 参数设置的目录。 - -4. 清理掉下游已同步的数据。 - -5. 使用 Ansible [启动整个 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md#第-9-步部署-dm-集群)。 - -6. 以新的任务名重启数据同步任务，或设置 `remove-meta` 为 `true` 且 `task-mode` 为 `all`。 diff --git a/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md b/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md deleted file mode 100644 index 975201341937..000000000000 --- a/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md +++ /dev/null @@ -1,541 +0,0 @@ ---- -title: 手动处理 Sharding DDL Lock -category: reference -aliases: ['/docs-cn/tools/dm/manually-handling-sharding-ddl-locks/'] ---- - -# 手动处理 Sharding DDL Lock - -DM (Data Migration) 使用 sharding DDL lock 来确保分库分表的 DDL 操作可以正确执行。绝大多数情况下，该锁定机制可自动完成；但在部分异常情况发生时，需要使用 `unlock-ddl-lock`/`break-ddl-lock` 手动处理异常的 DDL lock。 - -> **注意：** -> -> - 不要轻易使用 `unlock-ddl-lock`/`break-ddl-lock` 命令，除非完全明确当前场景下使用这些命令可能会造成的影响，并能接受这些影响。 -> - 在手动处理异常的 DDL lock 前，请确保已经了解 DM 的[分库分表合并同步原理](/v3.0/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)。 - -## 命令介绍 - -### `show-ddl-locks` - -该命令用于查询当前 DM-master 上存在的 DDL lock 信息。 - -#### 命令示例 - -{{< copyable "" >}} - -```bash -show-ddl-locks [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，查询所有 DM-worker 相关的 lock 信息；指定时，仅查询与这组 DM-worker 相关的 lock 信息，可重复多次指定 - -+ `task-name`： - - 非 flag 参数，string，可选 - - 不指定时，查询与所有任务相关的 lock 信息；指定时，仅查询特定任务相关的 lock 信息 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -» show-ddl-locks test -``` - -``` -{ - "result": true, # 查询 lock 操作本身是否成功 - "msg": "", # 查询 lock 操作失败时的原因或其它描述信息（如不存在任务 lock） - "locks": [ # DM-master 上存在的 lock 信息列表 - { - "ID": "test-`shard_db`.`shard_table`", # lock 的 ID 标识，当前由任务名与 DDL 对应的 schema/table 信息组成 - "task": "test", # lock 所属的任务名 - "owner": "127.0.0.1:8262", # lock 的 owner（第一个遇到该 DDL 的 DM-worker） - "DDLs": [ # lock 对应的 DDL 列表 - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;" - ], - "synced": [ # 已经收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8262" - ], - "unsynced": [ # 尚未收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8263" - ] - } - ] -} -``` - -### `unlock-ddl-lock` - -该命令用于主动请求 DM-master 解除指定的 DDL lock，包括的操作：请求 owner 执行 DDL 操作，请求其他非 owner 的 DM-worker 跳过 DDL 操作，移除 DM-master 上的 lock 信息。 - -#### 命令示例 - -{{< copyable "" >}} - -```bash -» unlock-ddl-lock [--worker=127.0.0.1:8262] [--owner] [--force-remove] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，对所有已经在等待该 lock 的 DM-worker 发起跳过 DDL 操作请求；指定时，仅对这组 DM-worker 发起跳过 DDL 操作请求，可重复多次指定 - -+ `owner`： - - flag 参数，string，`--owner`，可选 - - 不指定时，请求默认的 owner（`show-ddl-locks` 返回结果中的 `owner`）执行 DDL 操作；指定时，请求该 DM-worker（替代默认的 owner）执行 DDL 操作 - -+ `force-remove`： - - flag 参数，boolean，`--force-remove`，可选 - - 不指定时，仅在 owner 执行 DDL 成功时移除 lock 信息；指定时，即使 owner 执行 DDL 失败也强制移除 lock 信息（此后将无法再次查询或操作该 lock） - -+ `lock-ID`： - - 非 flag 参数，string，必选 - - 指定需要执行 unlock 操作的 DDL lock ID（即 `show-ddl-locks` 返回结果中的 `ID`） - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -» unlock-ddl-lock test-`shard_db`.`shard_table` -``` - -``` -{ - "result": true, # unlock lock 操作是否成功 - "msg": "", # unlock lock 操作失败时的原因 - "workers": [ # 各 DM-worker 执行/跳过 DDL 操作结果信息列表 - { - "result": true, # 该 DM-worker 执行/跳过 DDL 操作是否成功 - "worker": "127.0.0.1:8262", # DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker 执行/跳过 DDL 失败时的原因 - } - ] -} -``` - -### break-ddl-lock - -该命令用于主动请求 DM-worker 强制打破当前正在等待 unlock 的 DDL lock，包括请求 DM-worker 执行或跳过 DDL 操作、移除该 DM-worker 上的 DDL lock 信息。 - -#### 命令示例 - -{{< copyable "" >}} - -```bash -» break-ddl-lock <--worker=127.0.0.1:8262> [--remove-id] [--exec] [--skip] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，必选 - - 指定需要执行 break 操作的 DM-worker - -+ `remove-id`：已废弃 - -+ `exec`： - - flag 参数，boolean，`--exec`，可选 - - 不可与 `--skip` 参数同时指定 - - 指定时，请求该 DM-worker 执行（execute）当前 lock 对应的 DDL - -+ `skip`： - - flag 参数，boolean，`--skip`，可选 - - 不可与 `--exec` 参数同时指定 - - 指定时，请求该 DM-worker 跳过（skip）当前 lock 对应的 DDL - -+ `task-name`： - - 非 flag 参数，string，必选 - - 指定要执行 break 操作的 lock 所在的 task 名称（要查看各 task 上是否存在 lock，可通过 [query-status](/v3.0/reference/tools/data-migration/query-status.md) 获得） - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -» break-ddl-lock -w 127.0.0.1:8262 --exec test -``` - -``` -{ - "result": true, # break lock 操作是否成功 - "msg": "", # break lock 操作失败时的原因 - "workers": [ # 执行 break lock 操作的 DM-worker 列表（当前单次操作仅支持对一个 DM-worker 执行 break lock） - { - "result": false, # 该 DM-worker break lock 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker break lock 失败时的原因 - } - ] -} -``` - -## 支持场景 - -目前，使用 `unlock-ddl-lock`/`break-ddl-lock` 命令仅支持处理以下三种 sharding DDL lock 异常情况。 - -### 场景一：部分 DM-worker 下线 - -#### Lock 异常原因 - -在 DM-master 尝试自动 unlock sharding DDL lock 之前，需要等待所有 DM-worker 的 sharding DDL events 全部到达（详见[分库分表合并同步原理](/v3.0/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)）。如果 sharding DDL 已经在同步过程中，且有部分 DM-worker 下线，并且不再计划重启它们（按业务需求移除了这部分 DM-worker），则会由于永远无法等齐所有的 DDL 而造成 lock 无法自动 unlock。 - -#### 手动处理示例 - -假设上游有 MySQL-1 和 MySQL-2 两个实例，其中 MySQL-1 中有 `shard_db_1`.`shard_table_1` 和 `shard_db_1`.`shard_table_2` 两个表，MySQL-2 中有 `shard_db_2`.`shard_table_1` 和 `shard_db_2`.`shard_table_2` 两个表。现在需要将这 4 个表合并后同步到下游 TiDB 的 `shard_db`.`shard_table` 表中。 - -初始表结构如下： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE shard_db_1.shard_table_1; -``` - -``` -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -上游分表将执行以下 DDL 语句变更表结构： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE shard_db_*.shard_table_* ADD COLUMN c2 INT; -``` - -MySQL 及 DM 操作与处理流程如下： - -1. MySQL-1 对应的 DM-worker-1 的两个分表执行了对应的 DDL 操作进行表结构变更。 - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE shard_db_1.shard_table_1 ADD COLUMN c2 INT; - ``` - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE shard_db_1.shard_table_2 ADD COLUMN c2 INT; - ``` - -2. DM-worker-1 接受到两个分表的 DDL 之后，将对应 MySQL-1 相关的 DDL 信息发送给 DM-master，DM-master 创建相应的 DDL lock。 -3. 使用 `show-ddl-lock` 查看当前的 DDL lock 信息。 - - {{< copyable "" >}} - - ```bash - » show-ddl-locks test - ``` - - ``` - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8262", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8262" - ], - "unsynced": [ - "127.0.0.1:8263" - ] - } - ] - } - ``` - -4. 由于业务需要，DM-worker-2 对应的 MySQL-2 的数据不再需要同步到下游 TiDB，对 DM-worker-2 执行了下线处理。 -5. DM-master 上 ID 为 ```test-`shard_db`.`shard_table` ``` 的 lock 无法等到 DM-worker-2 的 DDL 操作信息。 - - `show-ddl-locks` 返回的 `unsynced` 中一直包含 DM-worker-2 的信息（`127.0.0.1:8263`）。 - -6. 使用 `unlock-dll-lock` 来请求 DM-master 主动 unlock 该 DDL lock。 - - - 如果 DDL lock 的 owner 也已经下线，可以使用 `--owner` 参数指定其他 DM-worker 作为新 owner 来执行 DDL。 - - 当存在任意 DM-worker 报错时，`result` 将为 `false`，此时请仔细检查各 DM-worker 的错误是否是预期可接受的。 - - 已下线的 DM-worker 会返回 `rpc error: code = Unavailable` 错误属于预期行为，可以忽略。 - - 如果其它未下线的 DM-worker 返回错误，则需要根据情况额外处理。 - - {{< copyable "" >}} - - ```bash - » unlock-ddl-lock test-`shard_db`.`shard_table` - ``` - - ``` - { - "result": false, - "msg": "github.com/pingcap/tidb-enterprise-tools/dm/master/server.go:1472: DDL lock test-`shard_db`.`shard_table` owner ExecuteDDL successfully, so DDL lock removed. but some dm-workers ExecuteDDL fail, you should to handle dm-worker directly", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": false, - "worker": "127.0.0.1:8263", - "msg": "rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = \"transport: Error while dialing dial tcp 127.0.0.1:8263: connect: connection refused\"" - } - ] - } - ``` - -7. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 - - ```bash - show-ddl-locks test - ``` - - ``` - { - "result": true, - "msg": "no DDL lock exists", - "locks": [ - ] - } - ``` - -8. 查看下游 TiDB 中的表结构是否变更成功。 - - {{< copyable "sql" >}} - - ```sql - SHOW CREATE TABLE shard_db.shard_table; - ``` - - ``` - +-------------+--------------------------------------------------+ - | Table | Create Table | - +-------------+--------------------------------------------------+ - | shard_table | CREATE TABLE `shard_table` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 COLLATE=latin1_bin | - +-------------+--------------------------------------------------+ - ``` - -9. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -使用 `unlock-ddl-lock` 手动执行 unlock 操作后，由于该任务的配置信息中仍然包含了已下线的 DM-worker，如果不进行处理，则当下次 sharding DDL 到达时，仍会出现 lock 无法自动完成同步的情况。 - -因此，在手动解锁 DDL lock 后，需要再执行以下操作： - -1. 使用 `stop-task` 停止运行中的任务。 -2. 更新任务配置文件，将已下线 DM-worker 对应的信息从配置文件中移除。 -3. 使用 `start-task` 及新任务配置文件重新启动任务。 - -> **注意：** -> -> 在 `unlock-ddl-lock` 之后，如果已下线的 DM-worker 重新上线并尝试对其中的分表进行数据同步，则会由于数据与下游的表结构不匹配而发生错误。 - -### 场景二：unlock 过程中部分 DM-worker 重启 - -#### Lock 异常原因 - -在 DM-master 收到所有 DM-worker 的 DDL 信息后，执行自动 unlock DDL lock 的操作主要包括以下步骤： - -1. 请求 lock owner 执行 DDL 操作，并更新对应分表的 checkpoint。 -2. 在 owner 执行 DDL 操作成功后，移除 DM-master 上保存的 DDL lock 信息。 -3. 在 owner 执行 DDL 操作成功后，请求其他所有 DM-worker 跳过 DDL 操作并更新对应分表的 checkpoint。 - -上述 unlock DDL lock 的操作不是原子的，当 owner 执行 DDL 操作成功后，请求其他 DM-worker 跳过 DDL 操作时，如果该 DM-worker 发生了重启，则会造成该 DM-worker 跳过 DDL 操作失败。 - -此时 DM-master 上的 lock 信息被移除，但该 DM-worker 重启后将尝试继续重新同步该 DDL 操作。但是，由于其他 DM-worker（包括原 owner）已经同步完该 DDL 操作，并已经在继续后续的同步，该 DM-worker 将永远无法等待该 DDL 操作对应 lock 的自动 unlock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -当在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息；但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于 DM-worker-2 发生了重启而跳过 DDL 操作失败。 - -DM-worker-2 重启后，将尝试重新同步重启前已经在等待的 DDL lock。此时将在 DM-master 上创建一个新的 lock，并且该 DM-worker 将成为 lock 的 owner（其他 DM-worker 此时已经执行或跳过 DDL 操作并在进行后续同步）。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上存在该 DDL 操作对应的 lock。 - - 应该仅有该重启的 DM-worker（`127.0.0.1:8263`）处于 `syned` 状态： - - {{< copyable "" >}} - - ```bash - » show-ddl-locks - ``` - - ``` - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8263", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8263" - ], - "unsynced": [ - "127.0.0.1:8262" - ] - } - ] - } - ``` - -2. 使用 `unlock-ddl-lock` 请求 DM-master unlock 该 lock。 - - - 使用 `--worker` 参数限定操作仅针对该重启的 DM-worker（`127.0.0.1:8263`）。 - - Lock 过程中该 DM-worker 会尝试再次向下游执行该 DDL 操作（重启前的原 owner 已向下游执行过该 DDL 操作），需要确保该 DDL 操作可被多次执行。 - - {{< copyable "" >}} - - ```bash - » unlock-ddl-lock --worker=127.0.0.1:8263 test-`shard_db`.`shard_table` - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -3. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 -4. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -手动 unlock sharding DDL lock 后，后续的 sharding DDL 将可以自动正常同步。 - -### 场景三：unlock 过程中部分 DM-worker 临时不可达 - -#### Lock 异常原因 - -与 [unlock 过程中部分 DM-worker 重启](#场景二unlock-过程中部分-dm-worker-重启) 造成 lock 异常的原因类似。当请求 DM-worker 跳过 DDL 操作时，如果该 DM-worker 临时不可达，则会造成该 DM-worker 跳过 DDL 操作失败。此时 DM-master 上的 lock 信息被移除，但该 DM-worker 将处于等待一个不再存在的 DDL lock 的状态。 - -场景三与[场景二](#场景二unlock-过程中部分-dm-worker-重启)的区别在于，场景三中 DM-master 没有 lock，而场景二中 DM-master 有一个新的 lock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息，但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于网络原因等临时不可达而跳过 DDL 操作失败。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上不再存在该 DDL 操作对应的 lock。 -2. 使用 `query-status` 确认 DM-worker 仍在等待 lock 同步。 - - {{< copyable "" >}} - - ```bash - » query-status test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - ... - { - ... - "worker": "127.0.0.1:8263", - "subTaskStatus": [ - { - ... - "unresolvedDDLLockID": "test-`shard_db`.`shard_table`", - "sync": { - ... - "blockingDDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "unresolvedGroups": [ - { - "target": "`shard_db`.`shard_table`", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "firstPos": "(mysql-bin|000001.000003, 1752)", - "synced": [ - "`shard_db_2`.`shard_table_1`", - "`shard_db_2`.`shard_table_2`" - ], - "unsynced": [ - ] - } - ], - "synced": false - } - } - ] - ... - } - ] - } - ``` - -3. 使用 `break-ddl-lock` 请求强制 break 该 DM-worker 当前正在等待的 DDL lock。 - - 由于 owner 已经向下游执行了 DDL 操作，因此在 break 时使用 `--skip` 参数。 - - {{< copyable "" >}} - - ```bash - » break-ddl-lock --worker=127.0.0.1:8263 --skip test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -4. 使用 `query-status` 确认同步任务是否正常且不再处于等待 lock 的状态。 - -#### 手动处理后的影响 - -手动强制 break lock 后，后续 sharding DDL 将可以自动正常同步。 diff --git a/v3.0/reference/tools/data-migration/features/overview.md b/v3.0/reference/tools/data-migration/features/overview.md deleted file mode 100644 index a2882fdf9ee4..000000000000 --- a/v3.0/reference/tools/data-migration/features/overview.md +++ /dev/null @@ -1,530 +0,0 @@ ---- -title: 数据同步功能 -summary: DM 提供的功能及其配置介绍 -category: reference -aliases: ['/docs-cn/tools/dm/data-synchronization-features/'] ---- - -# 数据同步功能 - -本文将详细介绍 DM 提供的数据同步功能，以及相关的配置选项。 - -## Table routing - -Table routing 提供将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的功能。 - -> **注意：** -> -> - 不支持对同一个表设置多个不同的路由规则。 -> - Schema 的匹配规则需要单独设置，用来同步 `create/drop schema xx`，例如下面[参数配置](#参数配置)中的 rule-2。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -routes: - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -### 参数解释 - -将根据 [`schema-pattern`/`table-pattern`](/v3.0/reference/tools/data-migration/table-selector.md) 匹配上该规则的上游 MySQL/MariaDB 实例的表同步到下游的 `target-schema`/`target-table`。 - -### 使用示例 - -下面展示了三个不同场景下的配置示例。 - -#### 分库分表合并 - -假设存在分库分表场景，需要将上游两个 MySQL 实例的表 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的一张表 `test`.`t`。 - -为了同步到下游实例的表 `test`.`t` 需要创建两个 table routing 规则： - -- `rule-1` 用来同步匹配上 `schema-pattern: "test_*"` 和 `table-pattern: "t_*"` 的表的 DML/DDL 语句到下游的 `test`.`t`。 -- `rule-2` 用来同步匹配上 `schema-pattern: "test_*"` 的库的 DDL 语句，例如 `create/drop schema xx`。 - -> **注意：** -> -> - 如果下游 TiDB `schema: test` 已经存在， 并且不会被删除，则可以省略 `rule-2`。 -> - 如果下游 TiDB `schema: test` 不存在，只设置了 `rule_1`，则同步会报错 `schema test doesn't exist`。 - -{{< copyable "" >}} - -```yaml - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 分库合并 - -假设存在分库场景，将上游两个 MySQL 实例 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t_{1,2,3...}`，创建一条路由规则即可： - -{{< copyable "" >}} - -```yaml - rule-1: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 错误的 table routing - -假设存在下面两个路由规则，`test_1_bak`.`t_1_bak` 可以匹配上 `rule-1` 和 `rule-2`，违反 table 路由的限制而报错。 - -{{< copyable "" >}} - -```yaml - rule-0: - schema-pattern: "test_*" - target-schema: "test" - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_1_bak" - table-pattern: "t_1_bak" - target-schema: "test" - target-table: "t_bak" -``` - -## Black & white table lists - -上游数据库实例表的黑白名单过滤规则，可以用来过滤或者只同步某些 `database/table` 的所有操作。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -black-white-list: - rule-1: - do-dbs: ["~^test.*"] # 以 ~ 字符开头，表示规则是正则表达式 -​ ignore-dbs: ["mysql"] - do-tables: - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "test" - tbl-name: "t" - ignore-tables: - - db-name: "test" - tbl-name: "log" -``` - -### 参数解释 - -- `do-dbs`：要同步的库的白名单，类似于 MySQL 中的 [`replicate-do-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-db)。 -- `ignore-dbs`：要同步的库的黑名单，类似于 MySQL 中的 [`replicate-ignore-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-db)。 -- `do-tables`：要同步的表的白名单，类似于 MySQL 中的 [`replicate-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-table)。 -- `ignore-tables`：要同步的表的黑名单，类似于 MySQL 中的 [`replicate-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-table)。 - -以上参数值以 `~` 开头时均支持使用[正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)来匹配库名、表名。 - -### 过滤规则 - -`do-dbs` 与 `ignore-dbs` 对应的过滤规则与 MySQL 中的 [Evaluation of Database-Level Replication and Binary Logging Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-db-options.html) 类似，`do-tables` 与 `ignore-tables` 对应的过滤规则与 MySQL 中的 [Evaluation of Table-Level Replication Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-table-options.html) 类似。 - -> **注意：** -> -> DM 中黑白名单过滤规则与 MySQL 中相应规则存在以下区别： -> -> - MySQL 中存在 [`replicate-wild-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-do-table) 与 [`replicate-wild-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-ignore-table) 用于支持通配符，DM 中各配置参数直接支持以 `~` 字符开头的正则表达式。 -> - DM 当前只支持 `ROW` 格式的 binlog，不支持 `STATEMENT`/`MIXED` 格式的 binlog，因此应与 MySQL 中 `ROW` 格式下的规则对应。 -> - 对于 DDL，MySQL 仅依据默认的 database 名称（`USE` 语句显式指定的 database）进行判断，而 DM 优先依据 DDL 中的 database 名称部分进行判断，并当 DDL 中不包含 database 名称时再依据 `USE` 部分进行判断。假设需要判断的 SQL 为 `USE test_db_2; CREATE TABLE test_db_1.test_table (c1 INT PRIMARY KEY)`，且 MySQL 配置了 `replicate-do-db=test_db_1`、DM 配置了 `do-dbs: ["test_db_1"]`，则对于 MySQL 该规则不会生效，而对于 DM 该规则会生效。 - -判断 table `test`.`t` 是否应该被过滤的过滤流程如下： - -1. 首先 **schema 过滤判断** - - - 如果 `do-dbs` 不为空，判断 `do-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则进入 **table 过滤判断**。 - - 如果不存在，则过滤 `test`.`t`。 - - - 如果 `do-dbs` 为空并且 `ignore-dbs` 不为空，判断 `ignore-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则过滤 `test`.`t`。 - - 如果不存在，则进入 **table 过滤判断**。 - - - 如果 `do-dbs` 和 `ignore-dbs` 都为空，则进入 **table 过滤判断**。 - -2. 进行 **table 过滤判断** - - 1. 如果 `do-tables` 不为空，判断 `do-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则同步 `test`.`t`。 - - 如果不存在，则过滤 `test`.`t`。 - - 2. 如果 `ignore-tables` 不为空，判断 `ignore-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则过滤 `test`.`t`. - - 如果不存在，则同步 `test`.`t`。 - - 3. 如果 `do-tables` 和 `ignore-tables` 都为空，则同步 `test`.`t`。 - -> **注意：** -> -> 判断 schema `test` 是否被过滤，只进行 **schema 过滤判断** - -### 使用示例 - -假设上游 MySQL 实例包含以下表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -``` - -配置如下： - -{{< copyable "" >}} - -```yaml -black-white-list: - bw-rule: - do-dbs: ["forum_backup_2018", "forum"] - ignore-dbs: ["~^forum_backup_"] - do-tables: - - db-name: "logs" - tbl-name: "~_2018$" - - db-name: "~^forum.*" -​ tbl-name: "messages" - ignore-tables: - - db-name: "~.*" -​ tbl-name: "^messages.*" -``` - -应用 `bw-rule` 规则后： - -| table | 是否过滤| 过滤的原因 | -|:----|:----|:--------------| -| `logs`.`messages_2016` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2017` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2018` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2016`.`messages` | 是 | schema `forum_backup_2016` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2017`.`messages` | 是 | schema `forum_backup_2017` 没有匹配到 `do-dbs` 任意一项 | -| `forum`.`users` | 是 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 没有匹配到 `do-tables` 和 `ignore-tables` 中任意一项，并且 `do-tables` 不为空，因此过滤 | -| `forum`.`messages` | 否 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | -| `forum_backup_2018`.`messages` | 否 | 1. schema `forum_backup_2018` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | - -## Binlog event filter - -Binlog event filter 是比同步表黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema / table` 的指定类型 binlog，比如 `INSERT`，`TRUNCATE TABLE`。 - -> **注意：** -> -> 同一个表匹配上多个规则，将会顺序应用这些规则，并且黑名单的优先级高于白名单，即如果同时存在规则 `Ignore` 和 `Do` 应用在某个 table 上，那么 `Ignore` 生效。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -filters: - rule-1: - schema-pattern: "test_*" - ​table-pattern: "t_*" - ​events: ["truncate table", "drop table"] - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - ​action: Ignore -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/v3.0/reference/tools/data-migration/table-selector.md)：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句进行以下规则过滤。 - -- `events`：binlog events 数组。 - - | Event | 分类 | 解释 | - | --------------- | ---- | ----------------------------- | - | all | | 代表包含下面所有的 events | - | all dml | | 代表包含下面所有 DML events | - | all ddl | | 代表包含下面所有 DDL events | - | none | | 代表不包含下面所有 events | - | none ddl | | 代表不包含下面所有 DDL events | - | none dml | | 代表不包含下面所有 DML events | - | insert | DML | insert DML event | - | update | DML | update DML event | - | delete | DML | delete DML event | - | create database | DDL | create database event | - | drop database | DDL | drop database event | - | create table | DDL | create table event | - | create index | DDL | create index event | - | drop table | DDL | drop table event | - | truncate table | DDL | truncate table event | - | rename table | DDL | rename table event | - | drop index | DDL | drop index event | - | alter table | DDL | alter table event | - -- `sql-pattern`：用于过滤指定的 DDL SQL 语句，支持正则表达式匹配，例如上面示例 `"^DROP\\s+PROCEDURE"`。 - -- `action`：string(`Do` / `Ignore`)；进行下面规则判断，满足其中之一则过滤，否则不过滤。 - - - `Do`：白名单。binlog event 如果满足下面两个条件之一就会被过滤掉： - - 不在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 没有匹配上 `sql-pattern` 中任意一项。 - - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉： - - 在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 可以匹配上 `sql-pattern` 中任意一项。 - -### 使用示例 - -#### 过滤分库分表的所有删除操作 - -需要设置下面两个 `Binlog event filter rule` 来过滤掉所有的删除操作： - -- `filter-table-rule` 过滤掉所有匹配到 pattern `test_*`.`t_*` 的 table 的 `turncate table`、`drop table`、`delete statement` 操作。 -- `filter-schema-rule` 过滤掉所有匹配到 pattern `test_*` 的 schema 的 `drop database` 操作。 - -{{< copyable "" >}} - -```yaml -filters: - filter-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - filter-schema-rule: - schema-pattern: "test_*" - events: ["drop database"] - action: Ignore -``` - -#### 只同步分库分表的 DML 操作 - -需要设置下面两个 `Binlog event filter rule` 只同步 DML 操作： - -- `do-table-rule` 只同步所有匹配到 pattern `test_*`.`t_*` 的 table 的 `create table`、`insert`、`update`、`delete` 操作。 -- `do-schema-rule` 只同步所有匹配到 pattern `test_*` 的 schema 的 `create database` 操作。 - -> **注意：** -> -> 同步 `create database/table` 的原因是创建库和表后才能同步 `DML`。 - -{{< copyable "" >}} - -```yaml -filters: - do-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["create table", "all dml"] - action: Do - do-schema-rule: - schema-pattern: "test_*" - events: ["create database"] - action: Do -``` - -#### 过滤 TiDB 不支持的 SQL 语句 - -可设置如下规则过滤 TiDB 不支持的 `PROCEDURE` 语句： - -{{< copyable "" >}} - -```yaml -filters: - filter-procedure-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - action: Ignore -``` - -#### 过滤 TiDB parser 不支持的 SQL 语句 - -对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 `schema`/`table` 信息，因此需要使用全局过滤规则：`schema-pattern: "*"`。 - -> **注意：** -> -> 全局过滤规则的设置必须尽可能严格，以避免预期之外地过滤掉需要同步的数据。 - -可设置如下规则过滤 TiDB parser 不支持的 `PARTITION` 语句： - -{{< copyable "" >}} - -```yaml -filters: - filter-partition-rule: - schema-pattern: "*" - sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"] - action: Ignore -``` - -## Column mapping - -> **注意：** -> -> 由于 Column mapping 的使用限制较多，我们不推荐使用 Column mapping 功能作为首选方案。我们优先推荐的方案请参考 [自增主键冲突处理](/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)。 - -Column mapping 提供对表的列值进行修改的功能。可以根据不同的表达式对表的指定列做不同的修改操作，目前只支持 DM 提供的内置表达式。 - -> **注意：** -> -> - 不支持修改 column 的类型和表结构。 -> - 不支持对同一个表设置多个不同的列值转换规则。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/v3.0/reference/tools/data-migration/table-selector.md)：对匹配上该规则的上游 MySQL/MariaDB 实例的表按照指定 `expression` 进行列值修改操作。 -- `source-column`，`target-column`：对 `source-column` 列的值按照指定 `expression` 进行修改，将修改后的值赋值给 `target-column`。 -- `expression`：对数据进行转换的表达式，目前只支持下面的内置计算表达式。 - -#### `partition id` 表达式 - -`partition id` 目的是为了解决分库分表合并同步的自增主键的冲突。 - -**`partition id` 限制** - -注意下面的限制： - -- 只支持类型为 bigint 的列，通常为自增主键，联合主键或者联合唯一索引的其中一列 -- 如果 `schema 前缀` 不为空，则库名的组成必须为 `schema 前缀` 或者 `schema 前缀 + 分隔符 + 数字（即 schema ID）`，例如：支持 `s` 和 `s_1`，不支持 `s_a` -- 如果 `table 前缀` 不为空，则表名的组成必须为 `table 前缀` 或者 `table 前缀 + 分隔符 + 数字（即 table ID）` -- 如果库名/表名不包含 `… + 分隔符 + 数字` 部分，则对应的 ID 默认为 0 -- 对分库分表的规模支持限制如下 - - 支持最多 16 个 MySQL/MariaDB 实例，且需要满足 0 <= instance ID <= 15。 - - 每个实例支持最多 128 个 schema，且需要满足 0 <= schema ID <= 127。 - - 每个实例的每个 schema 支持最多 256 个 table，且需要满足 0 <= table ID <= 255。 - - 进行 Column mapping 的列的范围需要满足 0 <= ID <= 17592186044415。 - - `{instance ID, schema ID, table ID}` 组合需要保持唯一。 -- 目前该功能是定制功能，如果需要调整请联系相关开发人员进行调整 - -**`partition id` 参数配置** - -用户需要在 arguments 里面按顺序设置以下三个或四个参数： - -- `instance_id`：客户指定的上游分库分表的 MySQL/MariaDB instance ID（0 <= instance ID <= 15） -- `schema 前缀`：用来解析库名并获取 `schema ID` -- `table 前缀`：用来解释表名并获取 `table ID` -- 分隔符：用来分隔前缀与 ID，可省略，省略时分隔符默认为空字符串 - -`instance_id`、`schema 前缀` 和 `table 前缀` 这三个参数均可被设置为空字符串（`""`），表示对应的部分不会被编码进 `partition id`。 - -**`partition id` 表达式规则** - -`partition id` 会用 arguments 里面的数字来填充自增主键 ID 的首个比特位，计算出来一个 int64（即 MySQL bigint）类型的值，具体规则如下： - -| instance_id | schema 前缀 | table 前缀 | 编码 | -|:------------|:--------------|:-------------|---------:| -| ☑ 已定义 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 44 比特位] | -| ☐ 空 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 48 比特位] | -| ☑ 已定义 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`T`: 8 比特位] [`P`: 51 比特位] | -| ☑ 已定义 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`P`: 52 比特位] | -| ☐ 空 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`T`: 8 比特位] [`P`: 55 比特位] | -| ☐ 空 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`D`: 7 比特位] [`P`: 56 比特位] | -| ☑ 已定义 | ☐ 空 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`P`: 59 比特位] | - -- `S`：符号位，保留 -- `I`：instance ID，默认 4 比特位 -- `D`：schema ID，默认 7 比特位 -- `T`：table ID，默认 8 比特位 -- `P`：自增主键 ID，占据剩下的比特位（≥44 比特位） - -### 使用示例 - -假设存在分库分表场景：将上游两个 MySQL 实例的 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t`，并且这些表都有自增主键。 - -需要设置下面两个规则： - -{{< copyable "" >}} - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -- MySQL instance 1 的表 `test_1`.`t_1` 的 `ID = 1` 的行经过转换后 ID = 1 变为 `1 << (64-1-4) | 1 << (64-1-4-7) | 1 << 44 | 1 = 580981944116838401` -- MySQL instance 2 的表 `test_1`.`t_2` 的 `ID = 1` 的行经过转换后 ID = 2 变为 `2 << (64-1-4) | 1 << (64-1-4-7) | 2 << 44 | 2 = 1157460288606306306` - -## 同步延迟监控 - -DM 支持通过 heartbeat 真实同步数据来计算每个同步任务与 MySQL/MariaDB 的实时同步延迟。 - -> **注意：** -> -> - 同步延迟的估算的精度在秒级别。 -> - heartbeat 相关的 binlog 不会同步到下游，在计算延迟后会被丢弃。 - -### 系统权限 - -如果开启 heartbeat 功能，需要上游 MySQL/MariaDB 实例提供下面的权限： - -- SELECT -- INSERT -- CREATE (databases, tables) - -### 参数配置 - -在 task 的配置文件中设置： - -``` -enable-heartbeat: true -``` - -### 原理介绍 - -- DM-worker 在对应的上游 MySQL/MariaDB 创建库 `dm_heartbeat`（当前不可配置） -- DM-worker 在对应的上游 MySQL/MariaDB 创建表 `heartbeat`（当前不可配置） -- DM-worker 每秒钟（当前不可配置）在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 表中，利用 `replace statement` 更新当前时间戳 `TS_master` -- DM-worker 每个任务拿到 `dm_heartbeat`.`heartbeat` 的 binlog 后，更新自己的同步时间 `TS_slave_task` -- DM-worker 每 10 秒在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 查询当前的 `TS_master`，并且对每个任务计算 `task_lag` = `TS_master` - `TS_slave_task` - -可以在 metrics 的 [binlog replication](/v3.0/reference/tools/data-migration/monitor.md#binlog-replication) 处理单元找到 replicate lag 监控项。 diff --git a/v3.0/reference/tools/data-migration/features/shard-merge.md b/v3.0/reference/tools/data-migration/features/shard-merge.md deleted file mode 100644 index 247bcb57edd5..000000000000 --- a/v3.0/reference/tools/data-migration/features/shard-merge.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: 分库分表合并同步 -category: reference -aliases: ['/docs-cn/tools/dm/shard-merge/'] ---- - -# 分库分表合并同步 - -本文介绍了 DM 提供的分库分表合并同步功能。此功能用于将上游 MySQL/MariaDB 实例中结构相同的表同步到下游 TiDB 的同一个表中。DM 不仅支持同步上游的 DML 数据，也支持协调同步多个上游分表的 DDL 表结构变更。 - -> **注意：** -> -> 要执行分库分表合并同步任务，必须在任务配置文件中设置 `is-sharding: true`。 - -## 使用限制 - -DM 进行分表 DDL 的同步有以下几点使用限制： - -- 在一个逻辑 sharding group（需要合并同步到下游同一个表的所有分表组成的 group）内，所有上游分表必须以相同的顺序执行相同的 DDL 语句（库名和表名可以不同），并且只有在所有分表执行完当前一条 DDL 语句后，下一条 DDL 语句才能执行。 - - - 比如，如果在 table_1 表中先增加列 a 后再增加列 b，则在 table_2 表中就不能先增加列 b 后再增加列 a，因为 DM 不支持以不同的顺序来执行相同的 DDL 语句。 - -- 对于每个逻辑 sharding group，推荐使用一个独立的任务进行同步。 - - - 如果一个任务内存在多个 sharding group，则必须等待一个 sharding group 的 DDL 语句同步完成后，才能开始对其他 sharding group 执行 DDL 语句。 - -- 在一个逻辑 sharding group 内，所有上游分表都应该执行对应的 DDL 语句。 - - - 比如，若 DM-worker-2 对应的一个或多个上游分表未执行 DDL 语句，则其他已执行 DDL 语句的 DM-worker 都会暂停同步任务，直到等到 DM-worker-2 收到上游对应的 DDL 语句。 - -- sharding group 数据同步任务不支持 `DROP DATABASE/TABLE` 语句。 - - - DM-worker 中的 binlog 同步单元（sync）会自动忽略掉上游分表的 `DROP DATABASE` 和 `DROP TABLE` 语句。 - -- sharding group 数据同步任务支持 `RENAME TABLE` 语句，但有如下限制（online DDL 中的 `RENAME` 有特殊方案进行支持）： - - - 只支持 `RENAME TABLE` 到一个不存在的表。 - - 一条 `RENAME TABLE` 语句只能包含一个 `RENAME` 操作。 - -- 增量同步任务需要确认开始同步的 binlog position 上各分表的表结构必须一致，才能确保来自不同分表的 DML 语句能够同步到表结构确定的下游，并且后续各分表的 DDL 语句能够正确匹配与同步。 - -- 如果需要变更 [table routing 规则](/v3.0/reference/tools/data-migration/features/overview.md#table-routing)，必须先等所有 sharding DDL 语句同步完成。 - - - 在 sharding DDL 语句同步过程中，使用 dmctl 尝试变更 router-rules 会报错。 - -- 如果需要创建新表加入到一个正在执行 DDL 语句的 sharding group 中，则必须保持新表结构和最新更改的表结构一致。 - - - 比如，原 table_1, table_2 表初始时有 (a, b) 两列，sharding DDL 语句执行后有 (a, b, c) 三列，则同步完成后新创建的表也应当有 (a, b, c) 三列。 - -- 由于已经收到 DDL 语句的 DM-worker 会暂停任务以等待其他 DM-worker 收到对应的 DDL 语句，因此数据同步延迟会增加。 - -## 背景 - -目前，DM 使用 ROW 格式的 binlog 进行数据同步，且 binlog 中不包含表结构信息。在 ROW 格式的 binlog 同步过程中，如果不需要将多个上游表合并同步到下游的同一个表，则只存在一个上游表的 DDL 语句会更新对应下游表结构。ROW 格式的 binlog 可以认为是具有 self-description 属性。 - -分库分表合并同步过程中，可以根据 column values 及下游的表结构构造出相应的 DML 语句，但此时若上游的分表执行 DDL 语句进行了表结构变更，则必须对该 DDL 语句进行额外同步处理，以避免因为表结构和 binlog 数据不一致而造成同步出错的问题。 - -以下是一个简化后的例子： - -![shard-ddl-example-1](/media/shard-ddl-example-1.png) - -在上图的例子中，分表的合库合表过程简化成了上游只有两个 MySQL 实例，每个实例内只有一个表。假设在数据同步开始时，将两个分表的表结构版本记为 schema V1，将 DDL 语句执行完后的表结构版本记为 schema V2。 - -现在，假设数据同步过程中，DM-worker 内的 binlog 同步单元（sync）从两个上游分表收到的 binlog 数据有如下时序： - -1. 开始同步时，sync 从两个分表收到的都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到实例 1 上分表的 DDL 语句。 - -3. 从 t2 时刻开始，sync 从实例 1 收到的是 schema V2 版本的 DML 语句；但从实例 2 收到的仍是 schema V1 版本的 DML 语句。 - -4. 在 t3 时刻，sync 收到实例 2 上分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从实例 2 收到的也是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当实例 1 的 DDL 语句同步到下游后，下游的表结构会变更成为 schema V2 版本。但在 t2 到 t3 这段时间内，sync 从实例 2 上收到的仍是 schema V1 版本的 DML 语句。当尝试把这些 schema V1 版本的 DML 语句同步到下游时，就会由于 DML 语句与表结构的不一致而发生错误，从而无法正确同步数据。 - -## 实现原理 - -基于上述例子，本部分介绍了 DM 在合库合表过程中进行 DDL 同步的实现原理。 - -![shard-ddl-flow](/media/shard-ddl-flow.png) - -在这个例子中，DM-worker-1 负责同步来自 MySQL 实例 1 的数据，DM-worker-2 负责同步来自 MySQL 实例 2 的数据，DM-master 负责协调多个 DM-worker 间的 DDL 同步。 - -从 DM-worker-1 收到 DDL 语句开始，简化后的 DDL 同步流程为： - -1. 在 t1 时刻，DM-worker-1 收到来自 MySQL 实例 1 的 DDL 语句，自身暂停该 DDL 语句对应任务的 DDL 及 DML 数据同步，并将 DDL 相关信息发送给 DM-master。 - -2. DM-master 根据收到的 DDL 信息判断得知需要协调该 DDL 语句的同步，于是为该 DDL 语句创建一个锁，并将 DDL 锁信息发回给 DM-worker-1，同时将 DM-worker-1 标记为这个锁的 owner。 - -3. DM-worker-2 继续进行 DML 语句的同步，直到在 t3 时刻收到来自 MySQL 实例 2 的 DDL 语句，自身暂停该 DDL 语句对应任务的数据同步，并将 DDL 相关信息发送给 DM-master。 - -4. DM-master 根据收到的 DDL 信息判断得知该 DDL 语句对应的锁信息已经存在，于是直接将对应锁信息发回给 DM-worker-2。 - -5. 根据任务启动时的配置信息、上游 MySQL 实例分表信息、部署拓扑信息等，DM-master 判断得知自身已经收到了来自待合表的所有上游分表的 DDL 语句，于是请求 DDL 锁的 owner（DM-worker-1）向下游同步执行该 DDL。 - -6. DM-worker-1 根据第二步收到的 DDL 锁信息验证 DDL 语句执行请求；向下游执行 DDL，并将执行结果反馈给 DM-master；若 DDL 语句执行成功，则自身开始继续同步后续的（从 t2 时刻对应的 binlog 开始的）DML 语句。 - -7. DM-master 收到来自 owner 执行 DDL 语句成功的响应，于是请求在等待该 DDL 锁的所有其他 DM-worker（DM-worker-2）忽略该 DDL 语句，直接继续同步后续的（从 t4 时刻对应的 binlog 开始的）DML 语句。 - -根据上面的流程，可以归纳出 DM 协调多个 DM-worker 间 sharding DDL 同步的特点： - -- 根据任务配置与 DM 集群部署拓扑信息，DM-master 内部也会建立一个逻辑 sharding group 来协调 DDL 同步，group 中的成员为负责处理该同步任务拆解后的各子任务的 DM-worker。 - -- 各 DM-worker 从 binlog event 中收到 DDL 语句后，会将 DDL 信息发送给 DM-master。 - -- DM-master 根据来自 DM-worker 的 DDL 信息及 sharding group 信息创建或更新 DDL 锁。 - -- 如果 sharding group 的所有成员都收到了某一条相同的 DDL 语句，则表明上游分表在该 DDL 执行前的 DML 语句都已经同步完成，此时可以执行该 DDL 语句，并继续后续的 DML 同步。 - -- 上游所有分表的 DDL 在经过 [table router](/v3.0/reference/tools/data-migration/features/overview.md#table-routing) 转换后需要保持一致，因此仅需 DDL 锁的 owner 执行一次该 DDL 语句即可，其他 DM-worker 可直接忽略对应的 DDL 语句。 - -在上面的示例中，每个 DM-worker 对应的上游 MySQL 实例中只有一个待合并的分表。但在实际场景下，一个 MySQL 实例可能有多个分库内的多个分表需要进行合并，这种情况下，sharding DDL 的协调同步过程将更加复杂。 - -假设同一个 MySQL 实例中有 table_1 和 table_2 两个分表需要进行合并： - -![shard-ddl-example-2](/media/shard-ddl-example-2.png) - -在这个例子中，由于数据来自同一个 MySQL 实例，因此所有数据都是从同一个 binlog 流中获得，时序如下： - -1. 开始同步时，DM-worker 内的 sync 从两个分表收到的数据都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到 table_1 分表的 DDL 语句。 - -3. 从 t2 到 t3 时刻，sync 收到的数据同时包含 table_1 的 DML 语句（schema V2 版本）及 table_2 的 DML 语句（schema V1 版本）。 - -4. 在 t3 时刻，sync 收到 table_2 分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从两个分表收到的数据都是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当 table_1 的 DDL 语句同步到下游从而变更下游表结构后，table_2 的 DML 语句（schema V1 版本）将无法正常同步。因此，在单个 DM-worker 内部，我们也构造了与 DM-master 内类似的逻辑 sharding group，但 group 的成员是同一个上游 MySQL 实例的不同分表。 - -DM-worker 内协调处理 sharding group 的同步与 DM-master 处理 DM-worker 之间的同步不完全一致，主要原因包括： - -- 当 DM-worker 收到 table_1 分表的 DDL 语句时，同步不能暂停，需要继续解析 binlog 才能获得后续 table_2 分表的 DDL 语句，即需要从 t2 时刻继续解析直到 t3 时刻。 - -- 在继续解析 t2 到 t3 时刻的 binlog 的过程中，table_1 分表的 DML 语句（schema V2 版本）不能向下游同步；但当 sharding DDL 同步并执行成功后，这些 DML 语句则需要同步到下游。 - -DM-worker 内部 sharding DDL 同步的简化流程为： - -1. 在 t1 时刻，DM-worker 收到 table_1 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -2. DM-worker 继续向前解析 t2 到 t3 时刻的 binlog。 - -3. 对于 table_1 的 DML 语句（schema V2 版本），忽略；对于 table_2 的 DML 语句（schema V1 版本），正常同步到下游。 - -4. 在 t3 时刻，DM-worker 收到 table_2 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -5. 根据同步任务配置信息、上游库表信息等，DM-worker 判断得知该 MySQL 实例上所有分表的 DDL 语句都已收到；于是将该 DDL 语句同步到下游执行并变更下游表结构。 - -6. DM-worker 设置 binlog 流的新解析起始位置点为第一步时保存的位置点。 - -7. DM-worker 重新开始解析从 t2 到 t3 时刻的 binlog。 - -8. 对于 table_1 的 DML 语句（schema V2 版本），正常同步到下游；对于 table_2 的 DML 语句（schema V1 版本），忽略。 - -9. 解析到达第四步时保存的 binlog 位置点，可得知在第三步时被忽略的所有 DML 语句都已经重新同步到下游。 - -10. DM-worker 继续从 t4 时刻对应的 binlog 位置点开始正常同步。 - -综上可知，DM 在处理 sharding DDL 同步时，主要通过两级 sharding group 来进行协调控制，简化的流程为： - -1. 各 DM-worker 独立地协调对应上游 MySQL 实例内多个分表组成的 sharding group 的 DDL 同步。 - -2. 当 DM-worker 收到所有分表的 DDL 语句时，向 DM-master 发送 DDL 相关信息。 - -3. DM-master 根据 DM-worker 发来的 DDL 信息，协调由各 DM-worker 组成的 sharing group 的 DDL 同步。 - -4. 当 DM-master 收到所有 DM-worker 的 DDL 信息时，请求 DDL 锁的 owner（某个 DM-worker） 执行该 DDL 语句。 - -5. DDL 锁的 owner 执行 DDL 语句，并将结果反馈给 DM-master；自身开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -6. 当 DM-master 收到 owner 执行 DDL 成功的消息后，请求其他所有 DM-worker 继续开始同步。 - -7. 其他所有 DM-worker 各自开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -8. 在完成被忽略的 DML 语句的重新同步后，所有 DM-worker 继续正常同步。 diff --git a/v3.0/reference/tools/data-migration/from-aurora.md b/v3.0/reference/tools/data-migration/from-aurora.md deleted file mode 100644 index ff40a412d42e..000000000000 --- a/v3.0/reference/tools/data-migration/from-aurora.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: 从 AWS Aurora MySQL 迁移数据 -summary: 使用 DM 从 AWS Aurora MySQL 迁移数据。 -category: reference -aliases: ['/docs-cn/tools/dm/from-aurora/'] ---- - -# 从 AWS Aurora MySQL 迁移数据 - -本文介绍如何使用 DM 从 [AWS Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/v3.0/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/v3.0/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 - - {{< copyable "" >}} - - ```bash - » start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "" >}} - -```bash -» query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ```bash -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 task.yaml 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/v3.0/reference/tools/data-migration/glossary.md b/v3.0/reference/tools/data-migration/glossary.md deleted file mode 100644 index 7043c476ba74..000000000000 --- a/v3.0/reference/tools/data-migration/glossary.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: TiDB Data Migration 术语表 -summary: 学习 TiDB Data Migration 相关术语 -category: glossary ---- - -# TiDB Data Migration 术语表 - -本文档介绍 TiDB Data Migration (TiDB DM) 相关术语。 - -## B - -### Binlog - -在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/internals/en/binary-log.html) 与 [MariaDB Binary Log](https://mariadb.com/kb/en/library/binary-log/)。 - -### Binlog event - -MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/internals/en/binlog-event.html) 与 [MariaDB Binlog Event](https://mariadb.com/kb/en/library/1-binlog-events/)。 - -### Binlog event filter - -比 Black & white table list 更加细粒度的过滤功能，具体可参考 [Binlog event filter](/v3.0/reference/tools/data-migration/overview.md#binlog-event-filter)。 - -### Binlog position - -特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/kb/en/library/show-binlog-events/)。 - -### Binlog replication 处理单元 - -DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游的处理单元，每个 Subtask 对应一个 Binlog replication 处理单元。在当前文档中，有时也称作 Sync 处理单元。 - -### Black & white table list - -针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Black & white table lists](/v3.0/reference/tools/data-migration/overview.md#black--white-table-lists)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。 - -## C - -### Checkpoint - -TiDB DM 在全量导入与增量复制过程中的断点信息，用于在重新启动或恢复任务时从之前已经处理过的位置继续执行。 - -- 对于全量导入，Checkpoint 信息对应于每个数据文件已经被成功导入的数据对应的文件内偏移量等信息，其在每个导入数据的事务中同步更新； -- 对于增量复制，Checkpoint 信息对应于已经成功解析并导入到下游的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 等信息，其在 DDL 导入成功后或距上次更新时间超过 30 秒等条件下更新。 - -另外，[Relay 处理单元](#relay-处理单元) 对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#GTID) 信息。 - -## D - -### Dump 处理单元 - -DM-worker 内部用于从上游导出全量数据的处理单元，每个 Subtask 对应一个 Dump 处理单元。 - -## G - -### GTID - -MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/kb/en/library/gtid/)。 - -## H - -### Heartbeat - -在增量数据迁移过程中，用于估算数据从在上游写入后到达 Binlog replication 处理单元延迟时间的机制，具体可参考[同步延迟监控](/v3.0/reference/tools/data-migration/features/overview.md#同步延迟监控)。 - -## L - -### Load 处理单元 - -DM-worker 内部用于将全量导出数据导入到下游的处理单元，每个 Subtask 对应一个 Load 处理单元。在当前文档中，有时也称作 Import 处理单元。 - -## R - -### Relay log - -DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/kb/en/library/relay-log/) 相近。 - -有关 TiDB DM 内 Relay log 的目录结构、初始同步规则、数据清理等内容，可参考 [TiDB DM Relay Log](https://pingcap.com/docs-cn/stable/reference/tools/data-migration/relay-log/)。 - -### Relay 处理单元 - -DM-worker 内部用于从上游拉取 Binlog 并写入数据到 Relay log 的处理单元，每个 DM-worker 实例内部仅存在一个该处理单元。 - -## S - -### Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在启动或恢复增量迁移任务的前 5 分钟 TiDB DM 会自动启动 Safe mode，另外也可以在任务配置文件中通过 `safe-mode` 参数手动开启。 - -### Shard DDL - -指合库合表迁移过程中，在上游各分表 (shard) 上执行的需要 TiDB DM 进行协调迁移的 DDL。在当前文档中，有时也称作 Sharding DDL。 - -### Shard DDL lock - -用于协调 Shard DDL 迁移的锁机制，具体原理可查看[分库分表合并同步实现原理](/v3.0/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding DDL lock。 - -### Shard group - -指合库合表迁移过程中，需要合并迁移到下游同一张表的所有上游分表 (shard)，TiDB DM 内部具体实现时使用了两级抽象的 Shard group，具体可查看[分库分表合并同步实现原理](/v3.0/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding group。 - -### Subtask - -数据迁移子任务，即数据迁移任务运行在单个 DM-worker 实例上的部分。根据任务配置的不同，单个数据迁移任务可能只有一个子任务，也可能有多个子任务。 - -### Subtask status - -数据迁移子任务所处的状态，目前包括 `New`、`Running`、`Paused`、`Stopped` 及 `Finished` 5 种状态。有关数据迁移任务、子任务状态的更多信息可参考[任务状态](/v3.0/reference/tools/data-migration/query-status.md#任务状态)。 - -## T - -### Table routing - -用于支持将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步，具体可参考 [Table routing](/v3.0/reference/tools/data-migration/features/overview.md#table-routing)。 - -### Task - -数据迁移任务，执行 `start-task` 命令成功后即启动一个数据迁移任务。根据任务配置的不同，单个数据迁移任务既可能只在单个 DM-worker 实例上运行，也可能同时在多个 DM-worker 实例上运行。 - -### Task status - -数据迁移子任务所处的状态，由 [Subtask status](#subtask-status) 整合而来，具体信息可查看[任务状态](/v3.0/reference/tools/data-migration/query-status.md#任务状态)。 diff --git a/v3.0/reference/tools/data-migration/manage-tasks.md b/v3.0/reference/tools/data-migration/manage-tasks.md deleted file mode 100644 index adbef7508fe5..000000000000 --- a/v3.0/reference/tools/data-migration/manage-tasks.md +++ /dev/null @@ -1,957 +0,0 @@ ---- -title: 管理数据同步任务 -category: reference -aliases: ['/docs-cn/tools/dm/manage-task/'] ---- - -# 管理数据同步任务 - -本文介绍了如何使用 [dmctl](/v3.0/reference/tools/data-migration/overview.md#dmctl) 组件来进行数据同步任务的管理和维护。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 `dm-ansible/dmctl`。 - -dmctl 支持交互模式用于人工操作，同时也支持命令模式用于脚本。 - -## dmctl 交互模式 - -本部分描述了在交互模式下一些 dmctl 命令的基本用法。 - -### dmctl 使用帮助 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl --help -``` - -``` -Usage of dmctl: - -V prints version and exit - -config string - path to config file - # 按照 DM 提供的加密方法加密数据库密码，用于 DM 的配置文件 - -encrypt string - encrypt plaintext to ciphertext - # DM-master 访问地址，dmctl 与 DM-master 交互以完成任务管理操作 - -master-addr string - master API server addr - -rpc-timeout string - rpc timeout, default is 10m (default "10m") -``` - -### 加密数据库密码 - -在 DM 相关配置文件中，要求必须使用经 dmctl 加密后的密码，否则会报错。对于同一个原始密码，每次加密后密码不同。 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -### 任务管理概览 - -进入交互模式，与 DM-master 进行交互： - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 - -» help -DM control - -Usage: - dmctl [command] - -Available Commands: - break-ddl-lock forcefully break DM-worker's DDL lock - check-task check the config file of the task - help help about any command - migrate-relay migrate DM-worker's relay unit - pause-relay pause DM-worker's relay unit - pause-task pause a specified running task - purge-relay purge relay log files of the DM-worker according to the specified filename - query-error query task error - query-status query task status - refresh-worker-tasks refresh worker -> tasks mapper - resume-relay resume DM-worker's relay unit - resume-task resume a specified paused task - show-ddl-locks show un-resolved DDL locks - sql-inject inject (limited) SQLs into binlog replication unit as binlog events - sql-replace replace SQLs matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern); each SQL must end with a semicolon - sql-skip skip the binlog event matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern) - start-task start a task as defined in the config file - stop-task stop a specified task - switch-relay-master switch the master server of the DM-worker's relay unit - unlock-ddl-lock forcefully unlock DDL lock - update-master-config update the config of the DM-master - update-relay update the relay unit config of the DM-worker - update-task update a task's config for routes, filters, or black-white-list - -Flags: - -h, --help help for dmctl - -w, --worker strings DM-worker ID - -# 使用 `dmctl [command] --help` 来获取某个命令的更多信息 -``` - -## 管理数据同步任务 - -本部分描述了如何使用不同的任务管理命令来执行相应操作。 - -### 创建数据同步任务 - -`start-task` 命令用于创建数据同步任务。 当数据同步任务启动时，DM 将[自动对相应权限和配置进行前置检查](/v3.0/reference/tools/data-migration/precheck.md)。 - -{{< copyable "" >}} - -```bash -help start-task -``` - -``` -start a task as defined in the config file - -Usage: - dmctl start-task [-w worker ...] [flags] - -Flags: - -h, --help help for start-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -start-task [ -w "172.16.30.15:8262"] ./task.yaml -``` - -#### 参数解释 - -+ `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上执行 `task.yaml` - - 如果设置，则只启动指定任务在该组 DM-workers 上的子任务 -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -start-task task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -### 查询数据同步任务状态 - -`query-status` 命令用于查询数据同步任务状态。有关查询结果及子任务状态，详见[查询状态](/v3.0/reference/tools/data-migration/query-status.md)。 - -{{< copyable "" >}} - -```bash -help query-status -``` - -``` -query task status - -Usage: - dmctl query-status [-w worker ...] [task-name] [flags] - -Flags: - -h, --help help for query-status - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -query-status -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 查询在指定的一组 DM-workers 上运行的数据同步任务的子任务 -- `task-name`： - - 可选 - - 指定任务名称 - - 如果未设置，则返回全部数据同步任务的查询结果 - -#### 返回结果示例 - -有关查询结果中各参数的意义，详见[查询状态结果](/v3.0/reference/tools/data-migration/query-status.md#查询结果)。 - -### 查询运行错误 - -`query-error` 可用于查询数据同步任务与 relay 处理单元的错误信息。相比于 `query-status`，`query-error` 一般不用于获取除错误信息之外的其他信息。 - -`query-error` 常用于获取 `sql-skip`/`sql-replace` 所需的 binlog position 信息，有关 `query-error` 的参数与结果解释，请参考 [跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 文档中的 query-error](/v3.0/reference/tools/data-migration/skip-replace-sqls.md#query-error)。 - -### 暂停数据同步任务 - -`pause-task` 命令用于暂停数据同步任务。 - -> **注意：** -> -> 有关 `pause-task` 与 `stop-task` 的区别如下： -> -> - 使用 `pause-task` 仅暂停同步任务的执行，但仍然会在内存中保留任务的状态信息等，且可通过 `query-status` 进行查询；使用 `stop-task` 会停止同步任务的执行，并移除内存中与该任务相关的信息，且不可再通过 `query-status` 进行查询，但不会移除已经写入到下游数据库中的数据以及其中的 checkpoint 等 `dm_meta` 信息。 -> - 使用 `pause-task` 暂停同步任务期间，由于任务本身仍然存在，因此不能再启动同名的新任务，且会阻止对该任务所需 relay log 的清理；使用 `stop-task` 停止任务后，由于任务不再存在，因此可以再启动同名的新任务，且不会阻止对 relay log 的清理。 -> - `pause-task` 一般用于临时暂停同步任务以排查问题等；`stop-task` 一般用于永久删除同步任务或通过与 `start-task` 配合以更新配置信息。 - -{{< copyable "" >}} - -```bash -help pause-task -``` - -``` -pause a specified running task - -Usage: - dmctl pause-task [-w worker ...] [flags] - -Flags: - -h, --help help for pause-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上暂停数据同步任务的子任务 - - 如果设置，则只暂停该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-task test -``` - -``` -{ - "op": "Pause", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - } - ] -} -``` - -### 恢复数据同步任务 - -`resume-task` 命令用于恢复处于 `Paused` 状态的数据同步任务，通常用于在人为处理完造成同步任务暂停的故障后手动恢复同步任务。 - -{{< copyable "" >}} - -```bash -help resume-task -``` - -``` -resume a specified paused task - -Usage: - dmctl resume-task [-w worker ...] [flags] - -Flags: - -h, --help help for resume-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上恢复数据同步任务的子任务 - - 如果设置，则只恢复该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-task test -``` - -``` -{ - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - } - ] -} -``` - -### 停止数据同步任务 - -`stop-task` 命令用于停止数据同步任务。有关 `stop-task` 与 `pause-task` 的区别，请参考[暂停数据同步任务](#暂停数据同步任务)中的相关说明。 - -{{< copyable "" >}} - -```bash -help stop-task -``` - -``` -stop a specified task - -Usage: - dmctl stop-task [-w worker ...] [flags] - -Flags: - -h, --help help for stop-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -stop-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上停止数据同步任务的子任务 - - 如果设置，则只停止该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -stop-task test -``` - -``` -{ - "op": "Stop", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - } - ] -} -``` - -### 更新数据同步任务 - -`update-task` 命令用于更新数据同步任务。 - -支持的更新项包括： - -- Table routing 规则 -- Black & white table lists 规则 -- Binlog event filter 规则 - -其余项均不支持更新。 - -> **注意：** -> -> 如果能确保同步任务所需的 relay log 在任务停止期间不会被清理，则推荐使用[不支持更新项的更新步骤](#不支持更新项的更新步骤)来以统一的方式更新任务配置信息。 - -#### 支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若 `stage` 不为 `Paused`，则先使用 `pause-task ` 暂停任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `update-task task.yaml` 更新任务配置。 - -4. 使用 `resume-task ` 恢复任务。 - -#### 不支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若任务存在，则通过 `stop-task ` 停止任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `start-task ` 重启恢复任务。 - -{{< copyable "" >}} - -```bash -help update-task -``` - -``` -update a task's config for routes, filters, or black-white-list - -Usage: - dmctl update-task [-w worker ...] [flags] - -Flags: - -h, --help help for update-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -update-task [-w "127.0.0.1:8262"] ./task.yaml -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上更新数据同步任务的子任务 - - 如果设置，则只更新指定 DM-workers 上的子任务配置 -- `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -update-task task_all_black.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -## 管理 DDL lock - -目前与 DDL lock 相关的命令主要包括 `show-ddl-locks`、`unlock-ddl-lock`、`break-ddl-lock` 等。有关它们的功能、用法以及适用场景等，请参考[手动处理 sharding DDL lock](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 其他任务与集群管理命令 - -除上述常用的任务管理命令外，DM 还提供了其他一些命令用于管理数据同步任务或 DM 集群本身。 - -### 检查任务配置文件 - -`check-task` 命令用于检查指定的数据同步任务配置文件（`task.yaml`）是否合法以及上下游数据库的配置、权限、表结构等是否满足同步需要。具体可参考[上游 MySQL 实例配置前置检查](/v3.0/reference/tools/data-migration/precheck.md)。 - -在使用 `start-task` 启动同步任务时，DM 也会执行 `check-task` 所做的全部检查。 - -{{< copyable "" >}} - -```bash -help check-task -``` - -``` -check the config file of the task - -Usage: - dmctl check-task [flags] - -Flags: - -h, --help help for check-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -check-task task.yaml -``` - -#### 参数解释 - -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -check-task task-test.yaml -``` - -``` -{ - "result": true, - "msg": "check pass!!!" -} -``` - -### 暂停 relay 处理单元 - -relay 处理单元在 DM-worker 进程启动后即开始自动运行。通过使用 `pause-relay` 命令，我们可以暂停 relay 处理单元的运行。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `pause-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help pause-relay -``` - -``` -pause DM-worker's relay unit - -Usage: - dmctl pause-relay <-w worker ...> [flags] - -Flags: - -h, --help help for pause-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要暂停 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "PauseRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 恢复 relay 处理单元 - -`resume-relay` 用于恢复处于 `Paused` 状态的 relay 处理单元。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `resume-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help resume-relay -``` - -``` -resume DM-worker's relay unit - -Usage: - dmctl resume-relay <-w worker ...> [flags] - -Flags: - -h, --help help for resume-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要恢复 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "ResumeRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 切换 relay log 到新的子目录 - -relay 处理单元通过使用不同的子目录来存储来自上游不同 MySQL 实例的 binlog 数据。通过使用 `switch-relay-master` 命令，我们可以变更 relay 处理单元以开始使用一个新的子目录。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `switch-relay-master` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help switch-relay-master -``` - -``` -switch the master server of the DM-worker's relay unit - -Usage: - dmctl switch-relay-master <-w worker ...> [flags] - -Flags: - -h, --help help for switch-relay-master - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要切换 relay 处理单元使用子目录的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "172.16.30.15:8262" -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 手动清理 relay log - -DM 支持[自动清理 relay log](/v3.0/reference/tools/data-migration/relay-log.md#自动数据清理)，但同时 DM 也支持使用 `purge-relay` 命令[手动清理 relay log](/v3.0/reference/tools/data-migration/relay-log.md#手动数据清理)。 - -{{< copyable "" >}} - -```bash -help purge-relay -``` - -``` -purge relay log files of the DM-worker according to the specified filename - -Usage: - dmctl purge-relay <-w worker> [--filename] [--sub-dir] [flags] - -Flags: - -f, --filename string name of the terminal file before which to purge relay log files. Sample format: "mysql-bin.000006" - -h, --help help for purge-relay - -s, --sub-dir string specify relay sub directory for --filename. If not specified, the latest one will be used. Sample format: "2ae76434-f79f-11e8-bde2-0242ac130008.000001" - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要执行 relay log 清理操作的 DM-worker -- `--filename`： - - 必选 - - 指定标识 relay log 将要停止清理的文件名。如指定为 `mysql-bin.000100`，则只尝试清理到 `mysql-bin.000099` -- `--sub-dir`： - - 可选 - - 指定 `--filename` 对应的 relay log 子目录，如果不指定则会使用当前最新的子目录 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -``` -[warn] no --sub-dir specified for --filename; the latest one will be used -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] -} -``` - -### 预设跳过 DDL 操作 - -`sql-skip` 命令用于预设一个跳过操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。相关参数与结果解释，请参考[`sql-skip`](/v3.0/reference/tools/data-migration/skip-replace-sqls.md#sql-skip)。 - -### 预设替换 DDL 操作 - -`sql-replace` 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替换执行操作。相关参数与结果解释，请参考[`sql-replace`](/v3.0/reference/tools/data-migration/skip-replace-sqls.md#sql-replace)。 - -### 强制刷新 `task => DM-workers` 映射关系 - -`refresh-worker-tasks` 命令用于强制刷新 DM-master 内存中维护的 `task => DM-workers` 映射关系。 - -> **注意：** -> -> 一般不需要使用此命令。仅当已确定 `task => DM-workers` 映射关系存在，但执行其它命令时仍提示必须刷新它时，你才需要使用此命令。 - -## dmctl 命令模式 - -命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。 - -> **注意：** -> -> + 一条 dmctl 命令只能跟一个任务操作 -> + 任务操作只能放在 dmctl 命令的最后 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 start-task task.yaml -./dmctl -master-addr 172.16.30.14:8261 stop-task task -./dmctl -master-addr 172.16.30.14:8261 query-status -``` - -``` -Available Commands: - break-ddl-lock break-ddl-lock <-w worker ...> [--remove-id] [--exec] [--skip] - check-task check-task - migrate-relay migrate-relay - pause-relay pause-relay <-w worker ...> - pause-task pause-task [-w worker ...] - purge-relay purge-relay <-w worker> [--filename] [--sub-dir] - query-error query-error [-w worker ...] [task-name] - query-status query-status [-w worker ...] [task-name] - refresh-worker-tasks refresh-worker-tasks - resume-relay resume-relay <-w worker ...> - resume-task resume-task [-w worker ...] - show-ddl-locks show-ddl-locks [-w worker ...] [task-name] - sql-inject sql-inject <-w worker> - sql-replace sql-replace <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - sql-skip sql-skip <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - start-task start-task [-w worker ...] - stop-task stop-task [-w worker ...] - switch-relay-master switch-relay-master <-w worker ...> - unlock-ddl-lock unlock-ddl-lock [-w worker ...] - update-master-config update-master-config - update-relay update-relay [-w worker ...] - update-task update-task [-w worker ...] -``` - -## 废弃或不推荐使用的命令 - -以下命令已经被废弃或仅用于 debug，在接下来的版本中可能会被移除或修改其语义，**强烈不推荐使用**。 - -- `migrate-relay` -- `sql-inject` -- `update-master-config` -- `update-relay` diff --git a/v3.0/reference/tools/data-migration/monitor.md b/v3.0/reference/tools/data-migration/monitor.md deleted file mode 100644 index 47c67c507361..000000000000 --- a/v3.0/reference/tools/data-migration/monitor.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: DM 监控指标 -summary: 介绍 DM 的监控指标 -category: reference ---- - -# DM 监控指标 - -使用 DM-Ansible 部署 DM 集群的时候，会默认部署一套[监控系统](/v3.0/reference/tools/data-migration/deploy.md#第-7-步监控任务与查看日志)。 - -> **注意：** -> -> 目前只有 DM-worker 提供了 metrics，DM-master 暂未提供。 - -## Task - -在 Grafana dashboard 中，DM 默认名称为 `DM-task`。 - -### overview - -overview 下包含运行当前选定 task 的所有 DM-worker instance 的部分监控指标。当前默认告警规则只针对于单个 DM-worker instance。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | N/A | N/A | -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | N/A | N/A | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -### task 状态 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时| critical | - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒| N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### Dump/Load unit - -下面 metrics 仅在 `task-mode` 为 `full` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| data file size | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的总大小 | N/A | N/A | -| dump process exits with error | dump unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| load process exits with error | load unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| table count | load unit 导入的全量数据中 table 的数量总和 | N/A | N/A | -| data file count | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的数量总和| N/A | N/A | -| latency of execute transaction | load unit 在执行事务的时延，单位：秒 | N/A | N/A | -| latency of query | load unit 执行 query 的耗时，单位：秒 | N/A | N/A | - -### Binlog replication - -下面 metrics 仅在 `task-mode` 为 `incremental` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| remaining time to sync | 预计 Syncer 还需要多少分钟可以和 master 完全同步，单位：分钟 | N/A | N/A | -| replicate lag | master 到 Syncer 的 binlog 复制延迟时间，单位：秒 | N/A | N/A | -| process exist with error | binlog replication 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| binlog file gap between master and syncer | 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog file gap between relay and syncer | 与 relay 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog event qps | 单位时间内接收到的 binlog event 数量 (不包含需要跳过的 event) | N/A | N/A | -| skipped binlog event qps | 单位时间内接收到的需要跳过的 binlog event 数量 | N/A | N/A | -| cost of binlog event transform | Syncer 解析并且转换 binlog 成 SQLs 的耗时，单位：秒 | N/A | N/A | -| total sqls jobs | 单位时间内新增的 job 数量 | N/A | N/A | -| finished sqls jobs | 单位时间内完成的 job 数量 | N/A | N/A | -| execution latency | Syncer 执行 transaction 到下游的耗时，单位：秒 | N/A | N/A | -| unsynced tables | 当前子任务内还未收到 shard DDL 的分表数量 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -## Instance - -在 Grafana dashboard 中，instance 的默认名称为 `DM-instance`。 - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒 | N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### task - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时 | critical | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | diff --git a/v3.0/reference/tools/data-migration/overview.md b/v3.0/reference/tools/data-migration/overview.md deleted file mode 100644 index 659a45a02f1e..000000000000 --- a/v3.0/reference/tools/data-migration/overview.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Data Migration 简介 -category: reference -aliases: ['/docs-cn/tools/dm/overview/','/docs-cn/tools/data-migration-overview/'] ---- - -# Data Migration 简介 - -[DM](https://github.com/pingcap/dm) (Data Migration) 是一体化的数据同步任务管理平台，支持从 MySQL 或 MariaDB 到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化错误处理流程，降低运维成本。 - -## DM 架构 - -DM 主要包括三个组件：DM-master，DM-worker 和 dmctl。 - -![Data Migration architecture](/media/dm-architecture.png) - -### DM-master - -DM-master 负责管理和调度数据同步任务的各项操作。 - -- 保存 DM 集群的拓扑信息 -- 监控 DM-worker 进程的运行状态 -- 监控数据同步任务的运行状态 -- 提供数据同步任务管理的统一入口 -- 协调分库分表场景下各个实例分表的 DDL 同步 - -### DM-worker - -DM-worker 负责执行具体的数据同步任务。 - -- 将 binlog 数据持久化保存在本地 -- 保存数据同步子任务的配置信息 -- 编排数据同步子任务的运行 -- 监控数据同步子任务的运行状态 - -DM-worker 启动后，会自动同步上游 binlog 至本地配置目录（如果使用 DM-Ansible 部署 DM 集群，默认的同步目录为 `/relay_log`）。关于 DM-worker，详见 [DM-worker 简介](/v3.0/reference/tools/data-migration/dm-worker-intro.md)。关于 relay log，详见 [DM Relay Log](/v3.0/reference/tools/data-migration/relay-log.md)。 - -### dmctl - -dmctl 是用来控制 DM 集群的命令行工具。 - -- 创建、更新或删除数据同步任务 -- 查看数据同步任务状态 -- 处理数据同步任务错误 -- 校验数据同步任务配置的正确性 - -## 同步功能介绍 - -下面简单介绍 DM 数据同步功能的核心特性。 - -### Table routing - -[Table routing](/v3.0/reference/tools/data-migration/features/overview.md#table-routing) 是指将上游 MySQL 或 MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步。 - -### Black & white table lists - -[Black & white table lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists) 是指上游数据库实例表的黑白名单过滤规则。其过滤规则类似于 MySQL `replication-rules-db`/`replication-rules-table`，可以用来过滤或只同步某些数据库或某些表的所有操作。 - -### Binlog event filter - -[Binlog event filter](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) 是比库表同步黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema`/`table` 的指定类型的 binlog events，比如 `INSERT`，`TRUNCATE TABLE`。 - -### Shard support - -DM 支持对原分库分表进行合库合表操作，但需要满足一些[使用限制](/v3.0/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -## 使用限制 - -在使用 DM 工具之前，需了解以下限制： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - - > **注意：** - > - > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则 - > - > - 5.7.1 < MySQL 版本 < 8.0 - > - MariaDB 版本 >= 10.1.3 - - 在使用 dmctl 启动任务时，DM 会自动对任务上下游数据库的配置、权限等进行[前置检查](/v3.0/reference/tools/data-migration/precheck.md)。 - -+ DDL 语法 - - - 目前，TiDB 部分兼容 MySQL 支持的 DDL 语句。因为 DM 使用 TiDB parser 来解析处理 DDL 语句，所以目前仅支持 TiDB parser 支持的 DDL 语法。 - - DM 遇到不兼容的 DDL 语句时会报错。要解决此报错，需要使用 dmctl 手动处理，要么跳过该 DDL 语句，要么用指定的 DDL 语句来替换它。详见[如何处理不兼容的 DDL 语句](/v3.0/reference/tools/data-migration/faq.md#如何处理不兼容的-ddl-语句) - -+ 分库分表 - - - 如果业务分库分表之间存在数据冲突，可以参考[自增主键冲突处理](/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决；否则不推荐使用 DM 进行同步，如果进行同步则有冲突的数据会相互覆盖造成数据丢失。 - - 关于分库分表合并场景的其它限制，参见[使用限制](/v3.0/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -+ 操作限制 - - - DM-worker 重启后不能自动恢复数据同步任务，需要使用 dmctl 手动执行 `start-task`。详见[管理数据同步任务](/v3.0/reference/tools/data-migration/manage-tasks.md)。 - - 在一些情况下，DM-worker 重启后不能自动恢复 DDL lock 同步，需要手动处理。详见[手动处理 Sharding DDL Lock](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -+ DM-worker 切换 MySQL - - - 当 DM-worker 通过虚拟 IP（VIP）连接到 MySQL 且要切换 VIP 指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。如需切换 VIP 指向的 MySQL 实例，请参考[虚拟 IP 环境下的上游主从切换](/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-ip-环境下切换-dm-worker-与-mysql-实例的连接)对 DM 手动执行变更。 diff --git a/v3.0/reference/tools/data-migration/precheck.md b/v3.0/reference/tools/data-migration/precheck.md deleted file mode 100644 index 01d568d02ec5..000000000000 --- a/v3.0/reference/tools/data-migration/precheck.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 上游 MySQL 实例配置前置检查 -category: reference -aliases: ['/docs-cn/tools/dm/precheck/'] ---- - -# 上游 MySQL 实例配置前置检查 - -本文介绍了 DM 提供的前置检查功能，此功能用于在数据同步任务启动时提前检测出上游 MySQL 实例配置中可能存在的一些错误。 - -## 使用命令 - -`check-task` 命令用于对上游 MySQL 实例配置是否满足 DM 要求进行前置检查。 - -## 检查内容 - -上下游数据库用户必须具备相应读写权限。当数据同步任务启动时，DM 会自动检查下列权限和配置： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - -+ MySQL binlog 配置 - - - binlog 是否开启（DM 要求 binlog 必须开启） - - 是否有 `binlog_format=ROW`（DM 只支持 ROW 格式的 binlog 同步） - - 是否有 `binlog_row_image=FULL`（DM 只支持 `binlog_row_image=FULL`） - -+ 上游 MySQL 实例用户的权限 - - DM 配置中的 MySQL 用户至少需要具备以下权限： - - - REPLICATION SLAVE - - REPLICATION CLIENT - - RELOAD - - SELECT - -+ 上游 MySQL 表结构的兼容性 - - TiDB 和 MySQL 的兼容性存在以下一些区别： - - - TiDB 不支持外键 - - 字符集的兼容性不同，详见 [TiDB 支持的字符集](/v3.0/reference/sql/character-set.md) - -+ 上游 MySQL 多实例分库分表的一致性 - - + 所有分表的表结构是否一致，检查内容包括： - - - Column 数量 - - Column 名称 - - Column 位置 - - Column 类型 - - 主键 - - 唯一索引 - - + 分表中自增主键冲突检查 - - - 在两种情况下会造成检查失败： - - - 分表存在自增主键，且自增主键 column 类型不为 bigint - - 分表存在自增主键，自增主键 column 类型为 bigint，但没有为其配置列值转换 - - - 其他情况下检查将成功 diff --git a/v3.0/reference/tools/data-migration/query-status.md b/v3.0/reference/tools/data-migration/query-status.md deleted file mode 100644 index c060dbbb28fd..000000000000 --- a/v3.0/reference/tools/data-migration/query-status.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: DM 查询状态 -category: reference -aliases: ['/docs-cn/tools/dm/query-status/'] ---- - -# DM 查询状态 - -本文介绍 DM（Data Migration）`query-status` 命令的查询结果、任务状态与子任务状态。 - -## 查询结果 - -{{< copyable "" >}} - -```bash -» query-status -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "tasks": [ # 迁移 task 列表 - { - "taskName": "test-1", # 任务名称 - "taskStatus": "Running", # 任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped”，“Finished” 以及 “Error”。 - "workers": [ # 该任务所使用的 DM-workers 列表 - "127.0.0.1:8262" - ] - }, - { - "taskName": "test-2", - "taskStatus": "Error - Some error occurred in subtask", # 该任务的子任务存在运行错误并暂停的现象 - "workers": [ - "127.0.0.1:8262", - "127.0.0.1:8263" - ] - }, - { - "taskName": "test-3", - "taskStatus": "Error - Relay status is Error", # 该任务的某个处于 Sync 阶段的子任务对应的 Relay 处理单元出错 - "workers": [ - "127.0.0.1:8263", - "127.0.0.1:8264" - ] - } - ] -} -``` - -关于 tasks 下的 taskStatus 状态的详细定义，请参阅[任务状态](#任务状态)。 - -推荐的 `query-status` 使用方法是： - -1. 首先使用 query-status 查看各个 task 的运行状态是否正常。 -2. 如果发现其中某一 task 状态有问题，通过 `query-status <出错任务的 taskName>` 来得到更详细的错误信息。 - -## 任务状态 - -DM 的迁移任务状态取决于其分配到 DM-worker 上的[子任务状态](#子任务状态)，定义见下表： - -| 任务对应的所有子任务的状态 | 任务状态 | -| :--- | :--- | -| 任一子任务处于 “Paused” 状态且返回结果有错误信息 | Error - Some error occurred in subtask | -| 任一处于 Sync 阶段的子任务处于 “Running” 状态但其 Relay 处理单元未运行（处于 Error/Paused/Stopped 状态） | Error - Relay status is Error/Paused/Stopped | -| 任一子任务处于 “Paused” 状态且返回结果没有错误信息 | Paused | -| 所有子任务处于 “New” 状态 | New | -| 所有子任务处于 “Finished” 状态 | Finished | -| 所有子任务处于 “Stopped” 状态 | Stopped | -| 其他情况 | Running | - -## 详情查询结果 - -{{< copyable "" >}} - -```bash -» query-status test -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "workers": [ # DM-worker 列表。 - { - "result": true, - "worker": "172.17.0.2:8262", # DM-worker ID。 - "msg": "", - "subTaskStatus": [ # DM-worker 所有子任务的信息。 - { - "name": "test", # 子任务名称。 - "stage": "Running", # 子任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped” 以及 “Finished”。 - "unit": "Sync", # DM 的处理单元，包括 “Check”，“Dump“，“Load” 以及 “Sync”。 - "result": null, # 子任务失败时显示错误信息。 - "unresolvedDDLLockID": "test-`test`.`t_target`", # sharding DDL lock ID，可用于异常情况下手动处理 sharding DDL lock。 - "sync": { # 当前 `Sync` 处理单元的同步信息。 - "totalEvents": "12", # 该子任务中同步的 binlog event 总数。 - "totalTps": "1", # 该子任务中每秒同步的 binlog event 数量。 - "recentTps": "1", # 该子任务中最后一秒同步的 binlog event 数量。 - "masterBinlog": "(bin.000001, 3234)", # 上游数据库当前的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库当前的 GTID 信息。 - "syncerBinlog": "(bin.000001, 2525)", # 已被 `Sync` 处理单元同步的 binlog position。 - "syncerBinlogGtid": "", # 当前版本总是为空（因为 `Sync` 处理单元暂不使用 GTID 同步数据）。 - "blockingDDLs": [ # 当前被阻塞的 DDL 列表。该项仅在当前 DM-worker 所有上游表都处于 “synced“ 状态时才有数值，此时该列表包含的是待执行或待跳过的 sharding DDL 语句. - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "unresolvedGroups": [ # 没有被解决的 sharding group 信息。 - { - "target": "`test`.`t_target`", # 待同步的下游表。 - "DDLs": [ - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "firstPos": "(bin|000001.000001, 3130)", # sharding DDL 语句起始 binlog position。 - "synced": [ # `Sync` 处理单元已经读到该 sharding DDL 的上游分表。 - "`test`.`t2`" - "`test`.`t3`" - "`test`.`t1`" - ], - "unsynced": [ # `Sync` 处理单元未读到该 sharding DDL 的上游分表。如有上游分表未完成同步，`blockingDDLs` 为空。 - ] - } - ], - "synced": false # 增量同步是否已追上上游。由于后台 `Sync` 单元并不会实时刷新保存点，当前值为 “false“ 并不一定代表发生了同步延迟。 - } - } - ], - "relayStatus": { # relay 单元的同步状态. - "masterBinlog": "(bin.000001, 3234)", # 上游数据库的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库的 binlog GTID 信息。 - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", # 当前使用的 relay log 子目录。 - "relayBinlog": "(bin.000001, 3234)", # 已被拉取至本地存储的 binlog position。 - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 已被拉取至本地存储的 binlog GTID 信息。 - "relayCatchUpMaster": true, # 本地 relay log 同步进度是否与上游一致。 - "stage": "Running", # relay 处理单元状态 - "result": null - } - }, - { - "result": true, - "worker": "172.17.0.3:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Running", - "unit": "Load", - "result": null, - "unresolvedDDLLockID": "", - "load": { # `Load` 处理单元的同步信息。 - "finishedBytes": "115", # 已全量导入字节数。 - "totalBytes": "452", # 总计需要导入的字节数。 - "progress": "25.44 %" # 全量导入进度。 - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 28507)", - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", - "relayBinlog": "(bin.000001, 28507)", - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - } - }, - { - "result": true, - "worker": "172.17.0.6:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Paused", - "unit": "Load", - "result": { # 错误示例 - "isCanceled": false, - "errors": [ - { - "Type": "ExecSQL", - "msg": "Error 1062: Duplicate entry '1155173304420532225' for key 'PRIMARY'\n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:160: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:105: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/loader.go:138: file test.t1.sql" - } - ], - "detail": null - }, - "unresolvedDDLLockID": "", - "load": { - "finishedBytes": "0", - "totalBytes": "156", - "progress": "0.00 %" - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 1691)", - "masterBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relaySubDir": "97b5142f-e19c-11e8-808c-0242ac110005.000001", - "relayBinlog": "(bin.000001, 1691)", - "relayBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - } - } - ] -} -``` - -关于 `workers` 下 `subTaskStatus` 中 `stage` 状态和状态转换关系的详细信息，请参阅[子任务状态](#子任务状态)。 - -关于 `workers` 下 `subTaskStatus` 中 `unresolvedDDLLockID`的操作细节，请参阅[手动处理 Sharding DDL Lock](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 子任务状态 - -### 状态描述 - -- `New`： - - - 初始状态。 - - 如果子任务没有发生错误，状态切换为 `Running`，其他情况则切换为 `Paused`。 - -- `Running`：正常运行状态。 - -- `Paused`： - - - 暂停状态。 - - 子任务发生错误，状态切换为 `Paused`。 - - 如在子任务为 `Running` 状态下执行 `pause-task` 命令，任务状态会切换为 `Paused`。 - - 如子任务处于该状态，可以使用 `resume-task` 命令恢复任务。 - -- `Stopped`： - - - 停止状态。 - - 如在子任务为 `Running` 或 `Paused` 状态下执行 `stop-task` 命令，任务状态会切换为 `Stopped`。 - - 如子任务处于该状态，不可使用 `resume-task` 命令恢复任务。 - -- `Finished`： - - - 任务完成状态。 - - 只有 `task-mode` 为 `full` 的任务正常完成后，任务才会切换为该状态。 - -### 状态转换图 - -``` - error occurs - New --------------------------------| - | | - | resume-task | - | |----------------------------| | - | | | | - | | | | - v v error occurs | v - Finished <-------------- Running -----------------------> Paused - ^ | or pause-task | - | | | - start task | | stop task | - | | | - | v stop task | - Stopped <-------------------------| -``` diff --git a/v3.0/reference/tools/data-migration/relay-log.md b/v3.0/reference/tools/data-migration/relay-log.md deleted file mode 100644 index 2fa78044b5f6..000000000000 --- a/v3.0/reference/tools/data-migration/relay-log.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: DM Relay Log -summary: 了解目录结构、初始同步规则和 DM relay log 的数据清理。 -category: reference -aliases: ['/docs-cn/tools/dm/relay-log/'] ---- - -# DM Relay Log - -DM (Data Migration) 工具的 relay log 由一组有编号的文件和一个索引文件组成。这些有编号的文件包含了描述数据库更改的事件。索引文件包含所有使用过的 relay log 的文件名。 - -DM-worker 在启动后，会自动将上游 binlog 同步到本地配置目录（若使用 DM-Ansible 部署 DM，则同步目录默认为 ` / relay_log` ）。DM-worker 在运行过程中，会将上游 binlog 实时同步到本地文件。DM-worker 的处理单元 Syncer 会实时读取本地 relay log 的 binlog 事件，将这些事件转换为 SQL 语句，再将 SQL 语句同步到下游数据库。 - -本文档介绍 DM relay log 的目录结构、初始同步规则和数据清理方法。 - -## 目录结构 - -Relay-log 本地存储的目录结构示例如下： - -``` -/relay_log/ -|-- 7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001 -| |-- mysql-bin.000001 -| |-- mysql-bin.000002 -| |-- mysql-bin.000003 -| |-- mysql-bin.000004 -| `-- relay.meta -|-- 842965eb-091c-11e9-9e45-9a3bff03fa39.000002 -| |-- mysql-bin.000001 -| `-- relay.meta -`-- server-uuid.index -``` - -- `subdir`： - - - DM-worker 把从上游数据库同步到的 binlog 存储在同一目录下，每个目录都为一个 `subdir`。 - - `subdir` 的命名格式为 `<上游数据库 UUID>.<本地 subdir 序列号>`。 - - 在上游进行 master 和 slave 实例切换后，DM-worker 会生成一个序号递增的新 `subdir` 目录。 - - - 在以上示例中，对于 `7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001` 这一目录，`7e427cc0-091c-11e9-9e45-72b7c59d52d7` 是上游数据库的 UUID，`000001` 是本地 `subdir` 的序列号。 - -- `server-uuid.index`：记录当前可用的 `subdir` 目录。 - -- `relay.meta`：存储每个 `subdir` 中已同步的 binlog 信息。例如， - - ```bash - cat c0149e17-dff1-11e8-b6a8-0242ac110004.000001/relay.meta - ``` - - ``` - binlog-name = "mysql-bin.000010" # 当前同步的 binlog 名 - binlog-pos = 63083620 # 当前同步的 binlog 位置 - binlog-gtid = "c0149e17-dff1-11e8-b6a8-0242ac110004:1-3328" # 当前同步的 binlog GTID - ``` - - 也可能包含多个 GTID： - - ```bash - cat 92acbd8a-c844-11e7-94a1-1866daf8accc.000001/relay.meta - ``` - - ``` - binlog-name = "mysql-bin.018393" - binlog-pos = 277987307 - binlog-gtid = "3ccc475b-2343-11e7-be21-6c0b84d59f30:1-14,406a3f61-690d-11e7-87c5-6c92bf46f384:1-94321383,53bfca22-690d-11e7-8a62-18ded7a37b78:1-495,686e1ab6-c47e-11e7-a42c-6c92bf46f384:1-34981190,03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170,10b039fc-c843-11e7-8f6a-1866daf8d810:1-308290454" - ``` - -## 初始同步规则 - -DM-worker 每次启动时（或在 DM-worker 暂停后 relay log 恢复同步），同步的起始位置会出现以下几种情况： - -- 若是有效的本地 relay log（有效是指 relay log 具有有效的 `server-uuid.index`，`subdir` 和 `relay.meta` 文件），DM-worker 从 `relay.meta` 记录的位置恢复同步。 - -- 若不存在有效的本地 relay log，而且 DM 配置文件中未指定 `relay-binlog-name` 或 `relay-binlog-gtid`： - - - 在非 GTID 模式下，DM-worker 从初始的上游 binlog 开始同步，并将所有上游 binlog 文件连续同步至最新。 - - - 在 GTID 模式下，DM-worker 从初始上游 GTID 开始同步。 - - > **注意：** - > - > 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定同步的起始位置。 - -- 若不存在有效的本地 relay log： - - - 在非 GTID 模式下，若指定了 `relay-binlog-name`，则 DM-worker 从指定的 binlog 文件开始同步。 - - 在 GTID 模式下，若指定了 `relay-binlog-gtid`，则 DM-worker 从指定的 GTID 开始同步。 - -## 数据清理 - -因为存在文件读写的检测机制，所以 DM-worker 不会清理正在使用的 relay log，也不会清理当前任务稍后会使用到的 relay log。 - -Relay log 的数据清理包括自动清理和手动清理这两种方法。 - -### 自动数据清理 - -自动数据清理需对 DM-worker 命令行配置中的以下三项进行配置： - -- `purge-interval` - - 后台自动清理的时间间隔，以秒为单位。 - - 默认为 "3600"，表示每 3600 秒执行一次后台清理任务。 - -- `purge-expires` - - 未更新的 relay log 在被后台清理前可保留的小时数。 - - 默认为 "0"，表示不按 relay log 的更新时间执行数据清理。 - -- `purge-remain-space` - - 剩余磁盘空间，单位为 GB。若剩余磁盘空间小于该配置，则指定的 DM-worker 机器会在后台尝试自动清理可被安全清理的 relay-log。若这一数字被设为 "0"，则表示不按剩余磁盘空间来清理数据。 - - 默认为 "15"，表示可用磁盘空间小于 15GB 时，DM-master 会尝试安全地清理 relay log。 - -或者在 DM-woker 的配置文件中加入 purge 配置： - -```toml -# relay log purge strategy -[purge] -interval = 3600 -expires = 24 -remain-space = 15 -``` - -### 手动数据清理 - -手动数据清理是指使用 dmctl 提供的 `purge-relay` 命令，通过指定 `subdir` 和 binlog 文件名，来清理掉**指定 binlog 之前**的所有 relay log。若在命令中不填 `-subdir` 选项，则默认清理**最新 relay log 子目录之前**的所有 relay log。 - -假设当前 relay log 的目录结构如下： - -{{< copyable "shell-regular" >}} - -```bash -tree . -``` - -``` -. -|-- deb76a2b-09cc-11e9-9129-5242cf3bb246.000001 -| |-- mysql-bin.000001 -| |-- mysql-bin.000002 -| |-- mysql-bin.000003 -| `-- relay.meta -|-- deb76a2b-09cc-11e9-9129-5242cf3bb246.000003 -| |-- mysql-bin.000001 -| `-- relay.meta -|-- e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 -| |-- mysql-bin.000001 -| `-- relay.meta -`-- server-uuid.index -``` - -{{< copyable "shell-regular" >}} - -```bash -cat server-uuid.index -``` - -``` -deb76a2b-09cc-11e9-9129-5242cf3bb246.000001 -e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 -deb76a2b-09cc-11e9-9129-5242cf3bb246.000003 -``` - -在 dmctl 中使用 `purge-relay` 命令的示例如下： - -+ 以下命令指定的 relay log 子目录为 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，该子目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001`。所以该命令实际清空了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 子目录，保留 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002` 和 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。 - - {{< copyable "" >}} - - ```bash - » purge-relay -w 10.128.16.223:10081 --filename mysql-bin.000001 --sub-dir e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 - ``` - -+ 以下命令默认 `--sub-dir` 为最新的 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。该目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 和 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，所以该命令实际清空了这两个子目录，保留了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003`。 - - {{< copyable "" >}} - - ```bash - » purge-relay -w 10.128.16.223:10081 --filename mysql-bin.000001 - ``` diff --git a/v3.0/reference/tools/data-migration/releases/1.0.2.md b/v3.0/reference/tools/data-migration/releases/1.0.2.md deleted file mode 100644 index 176073d7f66d..000000000000 --- a/v3.0/reference/tools/data-migration/releases/1.0.2.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: DM 1.0.2 Release Notes -category: Releases ---- - -# DM 1.0.2 Release Notes - -发版日期：2019 年 10 月 30 日 - -DM 版本：1.0.2 - -DM-Ansible 版本：1.0.2 - -## 改进提升 - -- 支持自动为 DM-worker 生成部分配置项 -- 支持自动为数据迁移任务生成部分配置项 -- 简化 `query-status` 在无参数时的默认输出 -- DM 直接管理到下游数据库的连接 - -## 问题修复 - -- 修复在进程启动过程中以及执行 SQL 失败时可能 panic 的问题 -- 修复 DDL 执行超时后可能造成 sharding DDL 协调异常的问题 -- 修复由于前置检查超时或部分 DM-worker 不可访问而不能启动数据迁移任务的问题 -- 修复 SQL 执行失败后可能错误重试的问题 - -## 详细变更及问题修复 - -- 支持自动为 DM-worker 生成随机的 `server-id` 配置项 [#337](https://github.com/pingcap/dm/pull/337) -- 支持自动为 DM-worker 生成 `flavor` 配置项 [#328](https://github.com/pingcap/dm/pull/328) -- 支持自动为 DM-worker 生成 `relay-binlog-name` 与 `relay-binlog-gtid` 配置项 [#318](https://github.com/pingcap/dm/pull/318) -- 支持根据黑白名单生成 mydumper 需要导出的表名配置项 [#326](https://github.com/pingcap/dm/pull/326) -- 为数据迁移任务增加并发度配置项 (`mydumper-thread`、`loader-thread` 与 `syncer-thread`) [#314](https://github.com/pingcap/dm/pull/314) -- 简化 `query-status` 在无参数时的默认输出 [#340](https://github.com/pingcap/dm/pull/340) -- 修复 DDL 执行超时后可能造成 sharding DDL 协调异常的问题 [#338](https://github.com/pingcap/dm/pull/338) -- 修复 DM-worker 从本地 meta 数据恢复数据迁移任务时可能 panic 的问题 [#311](https://github.com/pingcap/dm/pull/311) -- 修复提交事务失败时可能造成 DM-worker panic 的问题 [#313](https://github.com/pingcap/dm/pull/313) -- 修复监听端口被占用时 DM-worker 或 DM-master 启动过程中可能 panic 的问题 [#301](https://github.com/pingcap/dm/pull/301) -- 修复对 1105 错误码的部分重试问题 [#321](https://github.com/pingcap/dm/pull/321), [#332](https://github.com/pingcap/dm/pull/332) -- 修复对 `Duplicate entry` 与 `Data too long for column` 错误的重试问题 [#313](https://github.com/pingcap/dm/pull/313) -- 修复在上游存在大量需要迁移的表时可能造成启动任务前置检查超时中断的问题 [#327](https://github.com/pingcap/dm/pull/327) -- 修复部分 DM-worker 不可访问时无法启动数据迁移任务的问题 [#319](https://github.com/pingcap/dm/pull/319) -- 修复从损坏的 relay log 恢复时可能错误更新 GTID sets 信息的问题 [#339](https://github.com/pingcap/dm/pull/339) -- 修复 sync 处理单元计算 TPS 错误的问题 [#294](https://github.com/pingcap/dm/pull/294) -- DM 直接管理到下游数据库的连接 [#325](https://github.com/pingcap/dm/pull/325) -- 提升组件内错误信息的传递方式 [#320](https://github.com/pingcap/dm/pull/320) diff --git a/v3.0/reference/tools/data-migration/releases/1.0.3.md b/v3.0/reference/tools/data-migration/releases/1.0.3.md deleted file mode 100644 index 8ae6dda78d5e..000000000000 --- a/v3.0/reference/tools/data-migration/releases/1.0.3.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: DM 1.0.3 Release Notes -category: Releases ---- - -# DM 1.0.3 Release Notes - -发版日期：2019 年 12 月 13 日 - -DM 版本：1.0.3 - -DM-Ansible 版本：1.0.3 - -## 改进提升 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 - -## 问题修复 - -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -## 详细变更及问题修复 - -- dmctl 支持命令式使用 [#364](https://github.com/pingcap/dm/pull/364) -- 优化 DM 错误提示信息 [#351](https://github.com/pingcap/dm/pull/351) -- 优化 `query-status` 命令输出内容 [#357](https://github.com/pingcap/dm/pull/357) -- 优化 DM 不同任务类型的权限检查 [#374](https://github.com/pingcap/dm/pull/374) -- 支持对重复引用的路由配置和过滤配置进行检查 [#385](https://github.com/pingcap/dm/pull/385) -- 支持同步 `ALTER DATABASE` DDL 语句 [#389](https://github.com/pingcap/dm/pull/389) -- 优化 DM 异常重试机制 [#391](https://github.com/pingcap/dm/pull/391) -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 [#353](https://github.com/pingcap/dm/pull/353) -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 [#400](https://github.com/pingcap/dm/pull/400) -- 更新 Golang 版本至 1.13 以及其他依赖包版本 [#362](https://github.com/pingcap/dm/pull/362) -- 过滤 SQL 执行时出现的 `context canceled` 错误 [#382](https://github.com/pingcap/dm/pull/382) -- 修复使用 DM-ansible 滚动升级 DM 监控过程中出错导致升级失败的问题 [#408](https://github.com/pingcap/dm/pull/408) diff --git a/v3.0/reference/tools/data-migration/skip-replace-sqls.md b/v3.0/reference/tools/data-migration/skip-replace-sqls.md deleted file mode 100644 index b7a29f2e8366..000000000000 --- a/v3.0/reference/tools/data-migration/skip-replace-sqls.md +++ /dev/null @@ -1,662 +0,0 @@ ---- -title: 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 -category: reference -aliases: ['/docs-cn/tools/dm/skip-replace-sqls/'] ---- - -# 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 - -本文介绍了如何使用 DM 来处理异常的 SQL 语句。 - -目前，TiDB 并不完全兼容所有的 MySQL 语法。当使用 DM 从 MySQL 同步数据到 TiDB 时，如果 TiDB 不支持对应的 SQL 语句，可能会造成错误并中断同步任务。在这种情况下，DM 提供以下两种方式来恢复同步： - -- 使用 dmctl 来手动跳过该 SQL 语句对应的 binlog event。 - -- 使用 dmctl 来手动指定其他 SQL 语句来替代该 SQL 语句对应的 binlog event，并向下游执行。 - -如果提前预知将要同步 TiDB 不支持的 SQL 语句，也可以使用 dmctl 来手动预设跳过/替代执行操作。当 DM 尝试将该 SQL 语句对应的 binlog event 同步到下游时，该预设的操作将自动执行，从而避免同步过程被中断。 - -## 使用限制 - -- 跳过/替代执行操作只适合用于一次性跳过/替代执行**下游 TiDB 不支持执行的 SQL 语句**，其它同步错误请不要使用此方式进行处理。 - - - 其它同步错误可尝试使用 [black & white table lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists) 或 [binlog event filter](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter)。 - -- 如果业务不能接受下游 TiDB 跳过异常的 DDL 语句，也不接受使用其他 DDL 语句作为替代，则不适合使用此方式进行处理。 - - - 比如：`DROP PRIMARY KEY` - - 这种情况下，只能在下游重建一个（DDL 执行完后的）新表结构对应的表，并将原表的全部数据重新导入该新表。 - -- 单次跳过/替代执行操作都是针对单个 binlog event 的。 - -- `--sharding` 仅用于对 sharding group 预设一些操作，并且必须在 DDL 语句执行之前预设，不能在 DDL 语句已经执行后预设。 - - - `--sharding` 模式下只支持预设，并只能使用 `--sql-pattern` 来匹配 binlog event。 - - 有关使用 DM 处理 sharding DDL 同步的原理，请参阅[分库分表合并同步原理](/v3.0/reference/tools/data-migration/features/shard-merge.md#实现原理)。 - -## 匹配 binlog event - -当同步任务由于执行 SQL 语句出错而中断时，可以使用 `query-error` 命令获取对应 binlog event 的 position 信息。在执行 `sql-skip` / `sql-replace` 时，通过指定该 position 信息，即可与对应的 binlog event 进行匹配。 - -然而，在同步中断前主动处理不被支持的 SQL 语句的情况下，由于无法提前预知 binlog event 的 position 信息，则需要使用其他方式来确保与后续将到达的 binlog event 进行匹配。 - -在 DM 中，支持如下两种 binlog event 匹配模式（两种模式只能选择其中一种）： - -1. binlog position：binlog event 的 position 信息 - - - binlog position 在命令中使用 `--binlog-pos` 参数传入，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - DM 中 binlog filename 的格式与上游 MySQL 中 binlog filename 的格式不完全一致。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -2. DDL pattern：（仅限于 DDL 语句的）正则表达式匹配模式 - - - DDL pattern 在命令中使用 `--sql-pattern` 参数传入，如要匹配 ```ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` ```，则对应的正则表达式为 ```~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` ```。 - - 正则表达式必须以 `~` 为前缀，且不包含任何原始空格（正则表达式字符串中的空格均以 `\s` 或 `\s+` 表示）。 - -对于合库合表场景，如果需要由 DM 自动选择 DDL lock owner 来执行跳过/替代执行操作，则由于不同 DM-worker 上 DDL 语句对应的 binlog position 无逻辑关联且难以确定，因此只能使用 DDL pattern 匹配模式。 - -> **注意：** -> -> - 一个 binlog event 只能注册一个使用 `--binlog-pos` 指定的 operator，后注册的 operator 会覆盖之前已经注册的 operator。 -> - 不要尝试为一个 binlog event 同时使用 `--binlog-pos` 和 `--sql-pattern` 指定 operator。 -> - operator 在与 binlog event 匹配成功后（而非执行成功后）即会被删除，后续如果需要再进行（`--sql-pattern`）匹配则必须重新注册。 - -## 支持场景 - -- 场景一：同步过程中，上游执行了 TiDB 不支持的 DDL 语句并同步到了 DM，造成同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 跳过对该 DDL 语句的同步以恢复同步任务。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 替代该 DDL 的同步以恢复同步任务。 - -- 场景二：同步过程中，预先知道了上游将执行 TiDB 不支持的 DDL 语句，则需要提前处理以避免同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 预设一个跳过该 DDL 语句的操作，当执行到该 DDL 语句时即自动跳过。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 预设一个替代该 DDL 语句的操作，当执行到该 DDL 语句时即自动替代。 - -## 实现原理 - -DM 在进行增量数据同步时，简化后的流程大致为： - -1. relay 处理单元从上游拉取 binlog 存储在本地作为 relay log。 - -2. binlog 同步单元（sync）读取本地 relay log，获取其中的 binlog event。 - -3. binlog 同步单元解析该 binlog event 并构造 DDL/DML 语句，然后将这些语句向下游 TiDB 执行。 - -在 binlog 同步单元解析完 binlog event 并向下游 TiDB 执行时，可能会由于 TiDB 不支持对应的 SQL 语句而报错并造成同步中断。 - -在 DM 中，可以为 binlog event 注册一些跳过/替代执行操作（operator）。在向下游 TiDB 执行 SQL 语句前，将当前的 binlog event 信息（position、DDL 语句）与注册的 operator 进行比较。如果 position 或 DDL 语句与注册的某个 operator 匹配，则执行该 operator 对应的操作并将该 operator 移除。 - -**同步中断后使用 `sql-skip` 或 `sql-replace` 恢复同步的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 binlog position 或 DDL pattern 注册 operator。 - -2. 使用 `resume-task` 恢复之前由于同步出错导致中断的任务。 - -3. 重新解析获得之前造成同步出错的 binlog event。 - -4. 该 binlog event 与第一步注册的 operator 匹配成功。 - -5. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -**同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 DDL pattern 注册 operator。 - -2. 从 relay log 中解析获得 binlog event。 - -3. （包含 TiDB 不支持 SQL 语句的）binlog event 与第一步注册的 operator 匹配成功。 - -4. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务，任务不发生中断。 - -**合库合表同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace`（在 DM-master 上）为指定的 DDL pattern 注册 operator。 - -2. 各 DM-worker 从 relay log 中解析获得 binlog event。 - -3. DM-master 协调各个 DM-worker 进行 DDL lock 同步。 - -4. DM-master 判断得知 DDL lock 同步成功后，将第一步注册的 operator 发送给 DDL lock owner。 - -5. DM-master 请求 DDL lock owner 执行 DDL 语句。 - -6. DDL lock owner 将要执行的 DDL 语句与第四步收到的 operator 匹配成功。 - -7. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -## 命令介绍 - -使用 dmctl 手动处理 TiDB 不支持的 SQL 语句时，主要使用的命令包括 `query-status`、`query-error`、`sql-skip` 和 `sql-replace`。 - -### query-status - -`query-status` 命令用于查询当前 DM-worker 内子任务及 relay 单元等的状态，详见[查询状态](/v3.0/reference/tools/data-migration/query-status.md)。 - -### query-error - -`query-error` 命令用于查询 DM-worker 内子任务及 relay 单元当前在运行中存在的错误。 - -#### 命令用法 - -```bash -query-error [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选； - - 不指定时查询所有 DM-worker 上的错误，指定时仅查询特定一组 DM-worker 上的错误。 - -+ `task-name`： - - 非 flag 参数，string，可选； - - 不指定时查询所有任务内的错误，指定时仅查询特定任务内的错误。 - -#### 结果示例 - -{{< copyable "" >}} - -```bash -» query-error test -``` - -``` -{ - "result": true, # query-error 操作本身是否成功 - "msg": "", # query-error 操作失败的说明信息 - "workers": [ # DM-worker 信息列表 - { - "result": true, # 该 DM-worker 上 query-error 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 的 IP:port（worker-id） - "msg": "", # 该 DM-worker 上 query-error 操作失败的说明信息 - "subTaskError": [ # 该 DM-worker 上运行子任务的错误信息 - { - "name": "test", # 任务名 - "stage": "Paused", # 当前任务的状态 - "unit": "Sync", # 当前正在处理任务的处理单元 - "sync": { # binlog 同步单元（sync）的错误信息 - "errors": [ # 当前处理单元的错误信息列表 - { - // 错误信息描述 - "msg": "exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, err:Error 1105: unsupported modify column length 10 is less than origin 11", - // 发生错误的 binlog event 的 position - "failedBinlogPosition": "mysql-bin|000001.000003:34642", - // 发生错误的 SQL 语句 - "errorSQL": "[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]" - } - ] - } - } - ], - "RelayError": { # 该 DM-worker 上 relay 处理单元的错误信息 - "msg": "" # 错误信息描述 - } - } - ] -} -``` - -### sql-skip - -`sql-skip` 命令用于预设一个跳过操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。 - -#### 命令用法 - -```bash -sql-skip <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`； - - 未指定 `--sharding` 时必选，指定 `--sharding` 时禁止使用； - - `worker` 指定预设操作将生效的 DM-worker。 - -+ `binlog-pos`： - - flag 参数，string，`--binlog-pos`； - - `binlog-pos` 与 `--sql-pattern` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `binlog-pos` 与 binlog event 的 position 匹配时生效，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -+ `sql-pattern`： - - flag 参数，string，`--sql-pattern`； - - `--sql-pattern` 与 `binlog-pos` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `sql-pattern` 与 binlog event 对应的（经过可选的 router-rule 转换后的）DDL 语句匹配时生效。格式为以 `~` 为前缀的正则表达式，如 ```~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT```。 - - 暂时不支持正则表达式中包含原始空格，需要使用 `\s` 或 `\s+` 替代空格。 - - 正则表达式必须以 `~` 为前缀，详见[正则表达式语法](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。 - - 正则表达式中的库名和表名必须是经过可选的 router-rule 转换后的名字，即对应下游的目标库名和表名。如上游为 ``` `shard_db_1`.`shard_tbl_1` ```，下游为 ``` `shard_db`.`shard_tbl` ```，则应该尝试匹配 ``` `shard_db`.`shard_tbl` ```。 - - 正则表达式中的库名、表名及列名需要使用 ``` ` ``` 标记，如 ``` `db1`.`tbl1` ```。 - -+ `sharding`： - - flag 参数，boolean，`--sharding`； - - 未指定 `--worker` 时必选，指定 `--worker` 时禁止使用； - - 在指定时表示预设的操作将在 sharding DDL 同步过程中的 DDL lock owner 内生效。 - -+ `task-name`： - - 非 flag 参数，string，必选； - - 指定预设的操作将生效的任务。 - -### sql-replace - -`sql-replace` 命令用于预设一个替代执行操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替代执行操作。 - -#### 命令用法 - -```bash -sql-replace <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -#### 参数解释 - -+ `worker`： - - 与 `sql-skip` 命令的 `--worker` 参数解释一致。 - -+ `binlog-pos`： - - 与 `sql-skip` 命令的 `--binlog-pos` 参数解释一致。 - -+ `sql-pattern`： - - 与 `sql-skip` 命令的 `--sql-pattern` 参数解释一致。 - -+ `sharding`： - - 与 `sql-skip` 命令的 `--sharding` 参数解释一致。 - -+ `task-name`： - - 与 `sql-skip` 命令的 `task-name` 参数解释一致。 - -+ `SQLs`： - - 非 flag 参数，string，必选； - - `SQLs` 指定将用于替代原 binlog event 的新的 SQL 语句。多条 SQL 语句间以 `;` 分隔，如 ```ALTER TABLE shard_db.shard_table drop index idx_c2;ALTER TABLE shard_db.shard_table DROP COLUMN c2;```。 - -## 使用示例 - -### 同步中断后被动执行跳过操作 - -#### 应用场景 - -假设现在需要将上游的 `db1.tbl1` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE db1.tbl1; -``` - -``` -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl1 | CREATE TABLE `tbl1` ( - `c1` int(11) NOT NULL, - `c2` decimal(11,3) DEFAULT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（将列的 DECIMAL(11, 3) 修改为 DECIMAL(10, 3)）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE db1.tbl1 CHANGE c2 c2 DECIMAL (10, 3); -``` - -则会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -``` -exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, -err:Error 1105: unsupported modify column length 10 is less than origin 11 -``` - -此时使用 `query-status` 查询任务状态，可看到 `stage` 转为了 `Paused`，且 `errors` 中有相关的错误描述信息。 - -使用 `query-error` 可以获取该错误的详细信息。比如，执行 `query-error test` 可获得出错的 binlog event 的 position（`failedBinlogPosition`）为 `mysql-bin|000001.000003:34642`。 - -#### 被动跳过 SQL 语句 - -假设业务上可以接受下游 TiDB 不执行此 DDL 语句（即继续保持原有的表结构），则可以通过使用 `sql-skip` 命令跳过该 DDL 语句以恢复同步任务。操作步骤如下： - -1. 使用 `query-error` 获取同步出错的 binlog event 的 position 信息。 - - position 信息可直接由 `query-error` 返回的 `failedBinlogPosition` 获得。 - - 本示例中的 position 为 `mysql-bin|000001.000003:34642`。 - -2. 使用 `sql-skip` 预设一个 binlog event 跳过操作，该操作将在使用 `resume-task` 后同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-skip --worker=127.0.0.1:8262 --binlog-pos=mysql-bin|000001.000003:34642 test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 11:17:51 operator.go:121: [info] [sql-operator] set a new operator - uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - on replication unit - ``` - -3. 使用 `resume-task` 恢复之前出错中断的同步任务。 - - {{< copyable "" >}} - - ```bash - » resume-task --worker=127.0.0.1:8262 test - ``` - - ``` - { - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "op": "Resume", - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 11:27:46 operator.go:158: [info] [sql-operator] binlog-pos (mysql-bin|000001.000003, 34642) matched, - applying operator uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - ``` - -4. 使用 `query-status` 确认该任务的 `stage` 已经转为 `Running`。 - -5. 使用 `query-error` 确认原错误信息已不再存在。 - -### 同步中断前主动执行替代执行操作 - -#### 应用场景 - -假设现在需要将上游的 `db2.tbl2` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE db2.tbl2; -``` - -``` -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl2 | CREATE TABLE `tbl2` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE db2.tbl2 DROP COLUMN c2; -``` - -当同步该 DDL 语句对应的 binlog event 到下游时，会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -``` -exec sqls[[USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 为该 DDL 语句预设一个跳过（skip）或替代执行（replace）操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP 列 c2。 - -#### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的 DDL 语句（经过可选的 router-rule 转换后的 DDL 语句）设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE db2.tbl2 DROP COLUMN c2;`。 - - 由于该 DDL 语句不存在 router-rule 转换，可设计如下正则表达式： - - ``` - ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`; - ``` - -3. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-replace --worker=127.0.0.1:8262 --sql-pattern=~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 15:33:13 operator.go:121: [info] [sql-operator] set a new operator - uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - on replication unit - ``` - -4. 在上游 MySQL 执行该 DDL 语句。 - -5. 观察下游表结构是否变更成功，对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 15:33:45 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;, - applying operator uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, - pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - -6. 使用 `query-status` 确认该任务的 `stage` 持续为 `Running`。 - -7. 使用 `query-error` 确认不存在 DDL 执行错误。 - -### 合库合表场景下同步中断后被动执行跳过操作 - -#### 应用场景 - -假设现在通过多个 DM-worker 将上游多个 MySQL 实例内的多个表进行合库合表同步到下游 TiDB 的同一个表，并且上游各分表执行了 TiDB 不支持的 DDL 语句。 - -DM-master 通过 DDL lock 协调 DDL 同步、并请求 DDL lock owner 向下游 TiDB 执行该 DDL 语句后，由于 TiDB 不支持该 DDL 语句，同步任务会报错并中断。 - -#### 被动跳过 SQL 语句 - -合库合表场景下，被动跳过 TiDB 不支持的 DDL 语句的处理方式与非合库合表场景下的[同步中断后被动执行跳过操作](#同步中断后被动执行跳过操作)基本一致。 - -但在合库合表场景下，只需要 DDL lock owner 向下游同步该 DDL 语句，因此在两种场景下的处理过程主要存在以下区别： - -1. 合库合表场景下，仅需要对 DDL lock owner 执行 `sql-skip`（`--worker={DDL-lock-owner}`）。 - -2. 合库合表场景下，仅需要对 DDL lock owner 执行 `resume-task`（`--worker={DDL-lock-owner}`）。 - -### 合库合表场景下同步中断前主动执行替代执行操作 - -#### 应用场景 - -假设现在存在如下四个上游表需要合并同步到下游的同一个表 ``` `shard_db`.`shard_table` ```： - -- MySQL 实例 1 内有 `shard_db_1` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 -- MySQL 实例 2 内有 `shard_db_2` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 - -初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE shard_db_1.shard_table_1; -``` - -``` -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -此时，在上游所有分表上都执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2; -``` - -则当 DM 通过 sharding DDL lock 协调两个 DM-worker 同步该 DDL 语句、并请求 DDL lock owner 向下游执行该 DDL 语句时，会由于 TiDB 不支持该 DDL 语句而导致同步任务中断且报如下错误： - -``` -exec sqls[[USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 命令为该 DDL 语句预设一个跳过/替代执行操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP c2 列。 - -#### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的（经过可选的 router-rule 转换后的）DDL 语句设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2`。 - - 由于存在 router-rule 会将表名转换为 ``` `shard_db`.`shard_table` ```，可设计如下正则表达式： - - ``` - ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - -3. 由于这是合库合表场景，因此使用 `--sharding` 参数来由 DM 自动确定替代执行操作只发生在 DDL lock owner 上。 - -4. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-replace --sharding --sql-pattern=~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - ``` - { - "result": true, - "msg": "request with --sharding saved and will be sent to DDL lock's owner when resolving DDL lock", - "workers": [ - ] - } - ``` - - **DM-master** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:53:33 operator.go:105: [info] [sql-operator] set a new operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" - op:REPLACE args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -5. 在上游 MySQL 实例的分表上执行 DDL 语句。 - -6. 观察下游表结构是否变更成功，对应的 DDL lock **owner** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:54:35 operator.go:121: [info] [sql-operator] set a new operator - uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - on replication unit - ``` - - ``` - 2018/12/28 16:54:35 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;, - applying operator uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - 另外，**DM-master** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:54:35 operator.go:122: [info] [sql-operator] get an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - with key ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - - ``` - 2018/12/28 16:54:36 operator.go:145: [info] [sql-operator] remove an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -7. 使用 `query-status` 确认任务的 `stage` 持续为 `Running`，且不存在正阻塞同步的 DDL 语句（`blockingDDLs`）与待解决的 sharding group（`unresolvedGroups`）。 - -8. 使用 `query-error` 确认不存在 DDL 执行错误。 - -9. 使用 `show-ddl-locks` 确认不存在待解决的 DDL lock。 diff --git a/v3.0/reference/tools/data-migration/table-selector.md b/v3.0/reference/tools/data-migration/table-selector.md deleted file mode 100644 index f3acd96f4afa..000000000000 --- a/v3.0/reference/tools/data-migration/table-selector.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Table Selector -summary: 介绍 DM 的 Table Selector -category: reference -aliases: ['/docs-cn/tools/dm/table-selector/'] ---- - -# Table Selector - -Table Selector 提供了一种基于[通配符](https://zh.wikipedia.org/wiki/%E9%80%9A%E9%85%8D%E7%AC%A6) 来匹配指定 `schema/table` 的功能。 - -## 通配符 - -table selector 在 `schema-pattern`/`table-pattern` 中可以使用以下两个通配符： - -+ 星号(`*`) - - - 匹配零个或者多个字符。例如， `doc*` 匹配 `doc` 和 `document`，但是不匹配 `dodo`。 - - `*` 只能放在 pattern 的最后一位，例如，支持 `doc*`，但是不支持 `do*c`。 - -+ 问号(`?`) - - - 匹配任意一个空字符除外的字符。 - -## 匹配规则 - -- `schema-pattern` 限制不能为空； -- `table-pattern` 可以设置为空。设置为空时，将只根据 `schema-pattern` 对 `schema` 进行匹配，然后返回匹配结果； -- `table-pattern` 不为空时，分别根据 `schema-pattern` 和 `table-pattern` 进行匹配，两个都匹配则结果为匹配。 - -## 使用示例 - -- 匹配所有库名以 `schema_` 开头的 schema 和 table - - ```yaml - schema-pattern： "schema_*" - table-pattern： "" - ``` - -- 匹配所有库名以 `schema_` 为前缀，并且表名以 `table_` 前缀的表 - - ```yaml - schema-pattern = "schema_*" - table-pattern = "table_*" - ``` diff --git a/v3.0/reference/tools/data-migration/troubleshoot/dm.md b/v3.0/reference/tools/data-migration/troubleshoot/dm.md deleted file mode 100644 index bf27434c934d..000000000000 --- a/v3.0/reference/tools/data-migration/troubleshoot/dm.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Data Migration 故障诊断 -category: reference -aliases: ['/docs-cn/tools/dm/troubleshooting/','/docs-cn/v3.0/how-to/troubleshoot/data-migration/'] ---- - -# Data Migration 故障诊断 - -本文总结了在 DM 工具使用过程中遇到问题的诊断流程，并指引用户通过错误信息查找相应的解决方案。 - -如果你在运行 DM 工具时出现了错误，请尝试以下解决方案： - -1. 执行 `query-status` 命令查看任务运行状态以及相关错误输出。 - -2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [Data Migration 错误含义](/v3.0/reference/tools/data-migration/troubleshoot/error-system.md) 获取错误的关键信息，然后查看 [Data Migration 常见错误及修复](/v3.0/reference/tools/data-migration/troubleshoot/error-handling.md)以寻找相应的解决方案。 - -3. 如果该错误还没有相应的解决方案，并且你无法通过查询日志或监控指标自行解决此问题，你可以联系相关销售人员进行支持。 - -4. 一般情况下，错误处理完成后，只需使用 dmctl 重启任务即可。 - - {{< copyable "shell-regular" >}} - - ```bash - resume-task ${task name} - ``` - -但在某些情况下，你还需要重置数据同步任务。有关何时需要重置以及如何重置，详见[重置数据同步任务](/v3.0/reference/tools/data-migration/faq.md#重置数据同步任务)。 diff --git a/v3.0/reference/tools/data-migration/troubleshoot/error-handling.md b/v3.0/reference/tools/data-migration/troubleshoot/error-handling.md deleted file mode 100644 index ed2632f72017..000000000000 --- a/v3.0/reference/tools/data-migration/troubleshoot/error-handling.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Data Migration 常见错误修复 -category: reference ---- - -# Data Migration 常见错误修复 - -本文档介绍 DM 中常见的错误以及修复方法。 - -## 常见错误说明和处理方法 - -| 错误码 | 错误说明 | 解决方法 | -| :----------- | :------------------------------------------------------------ | :----------------------------------------------------------- | -| `code=10001` | 数据库操作异常 | 进一步分析错误信息和错误堆栈 | -| `code=10002` | 数据库底层的 `bad connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 | DM 提供针对此类错误的自动恢复。如果长时间未恢复，需要用户检查网络或 TiDB 状态。 | -| `code=10003` | 数据库底层 `invalid connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 | DM 提供针对此类错误的自动恢复。如果未能正常恢复，需要用户进一步检查错误信息并根据具体场景进行分析。 | -| `code=10005` | 数据库查询类语句出错 | | -| `code=10006` | 数据库 `EXECUTE` 类型语句出错，包括 DDL 和 `INSERT`/`UPDATE`/`DELETE` 类型的 DML。更详细的错误信息可通过错误 message 获取。错误 message 中通常包含操作数据库所返回的错误码和错误信息。 | | -| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/v3.0/reference/tools/data-migration/faq.md#处理不兼容的-ddl-语句) 提供的解决方案 | -| `code=20010` | 处理任务配置时，解密数据库的密码出错 | 检查任务配置中提供的下游数据库密码是否有[使用 dmctl 正确加密](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码) | -| `code=26002` | 任务检查创建数据库连接失败。更详细的错误信息可通过错误 message 获取。错误 message 中包含操作数据库所返回的错误码和错误信息。 | 检查 DM-master 所在的机器是否有权限访问上游 | -| `code=32001` | dump 处理单元异常 | 如果报错 `msg` 包含 `mydumper: argument list too long.`，则需要用户根据 black-white list，在 `task.yaml` 的 mydumper `extra-args` 参数中手动加上 `--regex` 正则表达式设置要导出的库表。例如，如果要导出所有库中表名字为 `hello` 的表，可加上 `--regex '.*\\.hello$'`，如果要导出所有表，可加上 `--regex '.*'`。 | -| `code=38008` | DM 组件间的 gRPC 通信出错 | 检查 `class`， 定位错误发生在哪些组件的交互环节，根据错误 message 判断是哪类通信错误。如果是 gRPC 建立连接出错，可检查通信服务端是否运行正常。 | - -## 同步任务中断并包含 `invalid connection` 错误 - -发生 `invalid connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 - -由于 DM 中存在同步任务并发向下游复制数据的特性，因此在任务中断时可能同时包含多个错误（可通过 `query-status` 或 `query-error` 查询当前错误）。 - -- 如果错误中仅包含 `invalid connection` 类型的错误且当前处于增量复制阶段，则 DM 会自动进行重试。 -- 如果 DM 由于版本问题等未自动进行重试或自动重试未能成功，则可尝试先使用 `stop-task` 停止任务，然后再使用 `start-task` 重启任务。 - -## 同步任务中断并包含 `driver: bad connection` 错误 - -发生 `driver: bad connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 - -当前版本 DM 发生该类型错误时，需要先使用 `stop-task` 停止任务后再使用 `start-task` 重启任务。后续 DM 会完善对此错误类型的自动重试机制。 - -## relay 处理单元报错 `event from * in * diff from passed-in event *` 或同步任务中断并包含 `get binlog error ERROR 1236 (HY000)`、`binlog checksum mismatch, data may be corrupted` 等 binlog 获取或解析失败错误 - -在 DM 进行 relay log 拉取与增量同步过程中，如果遇到了上游超过 4GB 的 binlog 文件，就可能出现这两个错误。 - -原因是 DM 在写 relay log 时需要依据 binlog position 及文件大小对 event 进行验证，且需要保存同步的 binlog position 信息作为 checkpoint。但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，进而出现上面的错误。 - -对于 relay 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 停止 DM-worker。 -3. 将上游对应的 binlog 文件复制到 relay log 目录作为 relay log 文件。 -4. 更新 relay log 目录内对应的 `relay.meta` 文件以从下一个 binlog 开始拉取。 - - 例如：报错时有 `binlog-name = "mysql-bin.004451"` 与`binlog-pos = 2453`，则将其分别更新为 `binlog-name = "mysql-bin.004452"` 与`binlog-pos = 4`。 -5. 重启 DM-worker。 - -对于 binlog replication 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 通过 `stop-task` 停止同步任务。 -3. 将下游 `dm_meta` 数据库中 global checkpoint 与每个 table 的 checkpoint 中的 `binlog_name` 更新为出错的 binlog 文件，将 `binlog_pos` 更新为已同步过的一个合法的 position 值，比如 4。 - - 例如：出错任务名为 `dm_test`，对应的 `source-id` 为 `replica-1`，出错时对应的 binlog 文件为 `mysql-bin|000001.004451`，则执行 `UPDATE dm_test_syncer_checkpoint SET binlog_name='mysql-bin|000001.004451', binlog_pos = 4 WHERE id='replica-1';`。 -4. 在同步任务配置中为 `syncers` 部分设置 `safe-mode: true` 以保证可重入执行。 -5. 通过 `start-task` 启动同步任务。 -6. 通过 `query-status` 观察同步任务状态，当原造成出错的 relay log 文件同步完成后，即可还原 `safe-mode` 为原始值并重启同步任务。 - -## 执行 `query-status` 或查看日志时出现 `Access denied for user 'root'@'172.31.43.27' (using password: YES)` - -在所有 DM 配置文件中，数据库相关的密码都必须使用经 dmctl 加密后的密文（若数据库密码为空，则无需加密）。有关如何使用 dmctl 加密明文密码，参见[使用 dmctl 加密上游 MySQL 用户密码](/v3.0/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -此外，在 DM 运行过程中，上下游数据库的用户必须具备相应的读写权限。在启动同步任务过程中，DM 会自动进行相应权限的前置检查，详见[上游 MySQL 实例配置前置检查](/v3.0/reference/tools/data-migration/precheck.md)。 diff --git a/v3.0/reference/tools/data-migration/troubleshoot/error-system.md b/v3.0/reference/tools/data-migration/troubleshoot/error-system.md deleted file mode 100644 index 2c61d7d4193e..000000000000 --- a/v3.0/reference/tools/data-migration/troubleshoot/error-system.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Data Migration 错误说明 -category: reference -aliases: ['/docs-cn/v3.0/reference/tools/data-migration/error-system/'] ---- - -# Data Migration 错误说明 - -本文介绍了 Data Migration (DM) 的错误系统，以及各种错误信息的详细含义。 - -## DM 错误系统 - -DM 1.0.0-GA 版本中引入了新的错误系统。该系统： - -+ 增加了错误码机制。 -+ 增加了 `class`、`scope`、`level` 等错误信息。 -+ 优化了错误描述内容、错误调用链信息和调用堆栈信息。 - -错误系统的详细设计和实现，可参阅 [RFC 文档: Proposal: Improve Error System](https://github.com/pingcap/dm/blob/master/docs/RFCS/20190722_error_handling.md)。 - -## 错误信息示例 - -以下是 DM 实际输出的一条错误信息。本文根据这条信息，对各个字段作详细说明。 - -``` -[code=38008:class=dm-master:scope=internal:level=high] grpc request error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused" -github.com/pingcap/dm/pkg/terror.(*Error).Delegate - /root/code/gopath/src/github.com/pingcap/dm/pkg/terror/terror.go:267 -github.com/pingcap/dm/dm/master/workerrpc.callRPC - /root/code/gopath/src/github.com/pingcap/dm/dm/master/workerrpc/rawgrpc.go:124 -github.com/pingcap/dm/dm/master/workerrpc.(*GRPCClient).SendRequest - /root/code/gopath/src/github.com/pingcap/dm/dm/master/workerrpc/rawgrpc.go:64 -github.com/pingcap/dm/dm/master.(*Server).getStatusFromWorkers.func2 - /root/code/gopath/src/github.com/pingcap/dm/dm/master/server.go:1125 -github.com/pingcap/dm/dm/master.(*AgentPool).Emit - /root/code/gopath/src/github.com/pingcap/dm/dm/master/agent_pool.go:117 -runtime.goexit - /root/.gvm/gos/go1.12/src/runtime/asm_amd64.s:1337 -``` - -DM 中的错误信息均按以下固定格式输出： - -``` -[错误基本信息] + 错误 message 描述 + 错误堆栈信息（可选） -``` - -### 错误基本信息 - -- `code`：错误码，错误唯一标识。 - - 同一种错误都使用相同的错误码。错误码不随 DM 版本改变。 - - 在 DM 迭代过程中，部分错误可能会被移除，但错误码不会。新增的错误会使用新的错误码，不会复用已有的错误码。 - -- `class`：错误分类。 - - 用于标记出现错误的系统子模块。 - - 下表展示所有的错误类别、错误对应的系统子模块、错误样例： - - | 错误类别 | 错误对应的系统子模块 | 错误样例 | - | :-------------- | :------------------------------ | :------------------------------------------------------------ | - | `database` | 执行数据库操作出现错误 | `[code=10003:class=database:scope=downstream:level=medium] database driver: invalid connection` | - | `functional` | 系统底层的基础函数错误 | `[code=11005:class=functional:scope=internal:level=high] not allowed operation: alter multiple tables in one statement` | - | `config` | 配置错误 | `[code=20005:class=config:scope=internal:level=medium] empty source-id not valid` | - | `binlog-op` | binlog 操作出现错误 | `[code=22001:class=binlog-op:scope=internal:level=high] empty UUIDs not valid` | - | `checkpoint` | checkpoint 相关操作出现错误 | `[code=24002:class=checkpoint:scope=internal:level=high] save point bin.1234 is older than current pos bin.1371` | - | `task-check` | 进行任务检查时出现错误 | `[code=26003:class=task-check:scope=internal:level=medium] new table router error` | - | `relay-event-lib`| 执行 relay 模块基础功能时出现错误 | `[code=28001:class=relay-event-lib:scope=internal:level=high] parse server-uuid.index` | - | `relay-unit` | relay 处理单元内出现错误 | `[code=30015:class=relay-unit:scope=upstream:level=high] TCPReader get event: ERROR 1236 (HY000): Could not open log file` | - | `dump-unit` | dump 处理单元内出现错误 | `[code=32001:class=dump-unit:scope=internal:level=high] mydumper runs with error: CRITICAL **: 15:12:17.559: Error connecting to database: Access denied for user 'root'@'172.17.0.1' (using password: NO)` | - | `load-unit` | load 处理单元内出现错误 | `[code=34002:class=load-unit:scope=internal:level=high] corresponding ending of sql: ')' not found` | - | `sync-unit` | sync 处理单元内出现错误 | `[code=36027:class=sync-unit:scope=internal:level=high] Column count doesn't match value count: 9 (columns) vs 10 (values)` | - | `dm-master` | DM-master 服务内部出现错误 | `[code=38008:class=dm-master:scope=internal:level=high] grpc request error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused"` | - | `dm-worker` | DM-worker 服务内部出现错误 | `[code=40066:class=dm-worker:scope=internal:level=high] ExecuteDDL timeout, try use query-status to query whether the DDL is still blocking` | - | `dm-tracer` | DM-tracer 服务内部出现错误 | `[code=42004:class=dm-tracer:scope=internal:level=medium] trace event test.1 not found` | - -- `scope`：错误作用域。 - - 用于标识错误发生时 DM 作用对象的范围和来源，包括未设置 (not-set)、上游数据库 (upstream)、下游数据库 (downstream)、内部 (internal) 四种类型。 - - 如果错误发生的逻辑直接涉及到上下游数据库请求，作用域会设置为 upstream 或 downstream，其他出错场景目前都设置为 internal。 - -- `level`：错误级别。 - - 错误的严重级别，包括低级别 (low)、中级别 (medium)、高级别 (high) 三种。 - - 低级别通常是用户操作、输入错误，不影响正常同步任务；中级别通常是用户配置等错误，会影响部分新启动服务，不影响已有系统同步状态；高级别通常是用户需要关注的一些错误，可能存在同步任务中断等风险，需要用户进行处理。 - -在上述的错误样例中： - -- `code=38008` 表示 gRPC 通信出错的错误码。 -- `class=dm-master`，表示 DM-master 对外发送 gRPC 请求时出错（请求发送至 DM-worker）。 -- `scope=interal` 表示 DM 内部出现错误。 -- `level=high`，表示这是一个高级别错误，需要用户注意。可根据错误 message 和错误堆栈判断出更多错误信息。 - -### 错误 message 描述 - -错误 message 使用描述性语言来表示错误的详细信息。对于错误调用链上每一层额外增加的错误 message，采用 [errors.Wrap](https://godoc.org/github.com/pkg/errors#hdr-Adding_context_to_an_error) 的模式来叠加和保存错误 message。wrap 最外层的 message 是 DM 内部对该错误的描述，wrap 最内层的 message 是该错误最底层出错位置的错误描述。 - -以上述样例错误的 message 为例： - -- wrap 最外层 message，`grpc request error` 是 DM 对该错误的描述。 -- wrap 最内层 message，`connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused"`，是 gRPC 底层建立连接失败时返回的错误。 - -通过对基本错误信息和错误 message 进行分析，可以诊断出错误是在 DM-master 向 DM-worker 发送 gRPC 请求建立连接失败时出现的。该错误通常是由 DM-worker 未正常运行引起。 - -### 错误堆栈信息 - -DM 根据错误的严重程度和必要性来选择是否输出错误堆栈。错误堆栈记录了错误发生时完整的堆栈调用信息。如果用户通过错误基本信息和错误 message 描述不能完全诊断出错误发生的原因，可以通过错误堆栈进一步跟进出错时代码的运行路径。 - -## 常见错误码描述及处理 - -可在 DM 代码仓库[已发布的错误码](https://github.com/pingcap/dm/blob/master/_utils/terror_gen/errors_release.txt)中查询完整的错误码列表。 diff --git a/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md b/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md deleted file mode 100644 index 5a4da9310208..000000000000 --- a/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 分表合并数据迁移最佳实践 -summary: 使用 DM 对分库分表进行合并迁移时的最佳实践。 -category: reference ---- -# 分表合并数据迁移最佳实践 - -本文阐述了使用 TiDB Data Migration（以下简称 DM）对分库分表进行合并迁移的场景中，DM 相关功能的支持和限制，旨在给出一个业务的最佳实践。 - -## 独立的数据迁移任务 - -在[分库分表合并同步的实现原理部分](/v3.0/reference/tools/data-migration/features/shard-merge.md#实现原理)，我们介绍了 sharding group 的概念，简单来说可以理解为需要合并到下游同一个表的所有上游表即组成一个 sharding group。 - -当前的 sharding DDL 算法为了能协调在不同分表执行 DDL 对 schema 变更的影响，加入了一些[使用限制](/v3.0/reference/tools/data-migration/features/shard-merge.md#使用限制)。而当这些使用限制由于某些异常原因被打破时，我们需要[手动处理 Sharding DDL Lock](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) 甚至是完整重做整个数据迁移任务。 - -因此，为了减小异常发生时对数据迁移的影响，我们推荐将每一个 sharding group 拆分成一个独立的数据迁移任务。**这样当异常发生时，可能只有少部分迁移任务需要进行手动处理，其他数据迁移任务可以不受影响。** - -## 手动处理 sharding DDL lock - -从[分库分表合并同步的实现原理部分](/v3.0/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，DM 中的 sharding DDL lock 是用于协调不同上游分表向下游执行 DDL 的一种机制，本身并不是异常。 - -因此，当通过 `show-ddl-locks` 查看到 DM-master 上存在 sharding DDL lock 时，或通过 `query-status` 查看到某些 DM-worker 有 `unresolvedGroups` 或 `blockingDDLs` 时，并不要急于使用 `unlock-ddl-lock` 或 `break-ddl-lock` 尝试去手动解除 sharding DDL lock。 - -只有在确认当前未能自动解除 sharding DDL lock 是文档中所列的[支持场景](/v3.0/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#支持场景)之一时，才能参照对应支持场景中的手动处理示例进行处理。对于其他未被支持的场景，我们建议完整重做整个数据迁移任务，即清空下游数据库中的数据以及该数据迁移任务相关的 `dm_meta` 信息后，重新执行全量数据及增量数据的迁移。 - -## 自增主键冲突处理 - -在 DM 中，我们提供了 [Column mapping](/v3.0/reference/tools/data-migration/features/overview.md#column-mapping) 用于处理 bigint 类型的自增主键在合并时可能出现冲突的问题，但我们**强烈不推荐**使用该功能。如果业务上允许，我们推荐使用以下两种处理方式。 - -### 去掉自增主键的主键属性 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_no_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -- `auto_pk_c1` 列对业务无意义，且不依赖该列的 `PRIMARY KEY` 属性。 -- `uk_c2` 列有 `UNIQUE KEY` 属性，且能保证在所有上游分表间全局唯一。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但将 `auto_pk_c1` 的 `PRIMARY KEY` 属性修改为普通索引。 - - ```sql - CREATE TABLE `tbl_no_pk_2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - INDEX (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 使用联合主键 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_multi_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -* 业务不依赖 `auto_pk_c1` 的 `PRIMARY KEY` 属性。 -* `auto_pk_c1` 与 `uuid_c2` 的组合能确保全局唯一。 -* 业务能接受将 `auto_pk_c1` 与 `uuid_c2` 组成联合 `PRIMARY KEY`。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但不为 `auto_pk_c1` 指定 `PRIMARY KEY` 属性，而是将 `auto_pk_c1` 与 `uuid_c2` 一起组成 `PRIMARY KEY`。 - - ```sql - CREATE TABLE `tbl_multi_pk_c2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`,`uuid_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 - -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -## 合表迁移过程中在上游增/删表 - -从[分库分表合并同步的实现原理部分](/v3.0/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，sharding DDL lock 的协调依赖于是否已收到上游已有各分表对应的 DDL，且当前 DM 在合表迁移过程中暂时**不支持**在上游动态增加或删除分表。如果需要在合表迁移过程中，对上游执行增、删分表操作，推荐按以下方式进行处理。 - -### 在上游增加分表 - -如果需要在上游增加新的分表，推荐按以下顺序执行操作： - -1. 等待在上游分表上执行过的所有 sharding DDL 协调同步完成。 -2. 通过 `stop-task` 停止任务。 -3. 在上游添加新的分表。 -4. 确保 `task.yaml` 配置能使新添加的分表与其他已有的分表能合并到同一个下游表。 -5. 通过 `start-task` 启动任务。 -6. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 在上游删除分表 - -如果需要在上游删除原有的分表，推荐按以下顺序执行操作： - -1. 在上游删除原有的分表，并通过 [`SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/5.7/en/show-binlog-events.html) 获取该 `DROP TABLE` 语句在 binlog 中对应的 `End_log_pos`，记为 _Pos-M_。 -2. 通过 `query-status` 获取当前 DM 已经处理完成的 binlog event 对应的 position（`syncerBinlog`），记为 _Pos-S_。 -3. 当 _Pos-S_ 比 _Pos-M_ 更大后，则说明 DM 已经处理完 `DROP TABLE` 语句，且该表在被删除前的数据都已经同步到下游，可以进行后续操作；否则，继续等待 DM 进行数据同步。 -4. 通过 `stop-task` 停止任务。 -5. 确保 `task.yaml` 配置能忽略上游已删除的分表。 -6. 通过 `start-task` 启动任务。 -7. 通过 `query-status` 验证数据迁移任务是否正常。 - -## 数据迁移限速/流控 - -当将多个上游 MySQL/MariaDB 实例的数据合并迁移到下游同一个 TiDB 集群时，由于每个与上游 MySQL/MariaDB 对应的 DM-worker 都会并发地进行全量与增量数据迁移，默认的并发度（全量阶段的 `pool-size` 与增量阶段的 `worker-count`）通过多个 DM-worker 累加后，可能会给下游造成过大的压力，此时应根据 TiDB 监控及 DM 监控进行初步的性能分析后，适当地调整各并发度参数的大小。后续 DM 也将考虑支持部分自动的流控策略。 diff --git a/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md b/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md deleted file mode 100644 index 1b9e8cc00d0e..000000000000 --- a/v3.0/reference/tools/data-migration/usage-scenarios/master-slave-switch.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 切换 DM-worker 与上游 MySQL 实例的连接 -summary: 了解如何切换 DM-worker 与上游 MySQL 实例的连接。 -category: reference ---- - -# 切换 DM-worker 与上游 MySQL 实例的连接 - -当需要对 DM-worker 所连接的上游 MySQL 实例进行停机维护或该实例意外宕机时，需要将 DM-worker 的连接切换到同一个主从复制集群内的另一个 MySQL 实例上。本文介绍如何将 DM-worker 的连接从一个 MySQL 实例切换到另一个 MySQL 实例上。 - -> **注意：** -> -> - 仅支持在同一个主从复制集内的 MySQL 实例间进行切换。 -> - 将要切换到的 MySQL 实例必须拥有 DM-worker 所需的 binlog。 -> - DM-worker 必须以 GTID sets 模式运行，即 DM 通过 DM-Ansible 部署时必须指定 `enable_gtid=true`。 -> - DM 仅支持以下两种切换场景，且必须严格按照各场景的步骤执行操作，否则可能需要根据切换后的 MySQL 实例重新搭建 DM 集群并完整重做数据迁移任务。 - -有关 GTID sets 的概念解释，请参考 [MySQL 文档](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html#replication-gtids-concepts-gtid-sets)。 - -## 虚拟 IP 环境下切换 DM-worker 与 MySQL 实例的连接 - -如果 DM-worker 通过虚拟 IP (VIP) 连接上游的 MySQL 实例，更改 VIP 所指向的 MySQL 实例，即是在 DM-worker 对应上游连接地址不变的情况下切换 DM-worker 实际所连接的 MySQL 实例。 - -> **注意：** -> -> 如果不对 DM 执行必要变更，当切换 VIP 所指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。 - -如果 DM-worker 连接的 VIP 需要指向新的 MySQL 实例，需要按以下步骤进行操作： - -1. 使用 `query-status` 命令获取当前 relay 处理单元已从原 MySQL 实例获取到的 binlog 对应的 GTID sets (`relayBinlogGtid`)，记为 `gtid-W`。 -2. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_purged;` 获取已经被 purged 的 binlog 对应的 GTID sets，记为 `gtid-P`。 -3. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_executed;` 获取所有已经执行成功的事务对应的 GTID sets，记为 `gtid-E`。 -4. 确保满足以下关系，否则不支持将 DM-worker 连接切换到相应的 MySQL 实例： - - `gtid-W` 包含 `gtid-P`（`gtid-P` 可以为空） - - `gtid-E` 包含 `gtid-W` -5. 使用 `pause-relay` 命令暂停 relay 处理。 -6. 使用 `pause-task` 命令暂停所有运行中的数据迁移任务。 -7. 变更 VIP 以指向新的 MySQL 实例。 -8. 使用 `switch-relay-master` 命令通知 relay 处理单元进行主从切换。 -9. 使用 `resume-relay` 命令恢复 relay 处理，使其从新的 MySQL 实例读取 binlog。 -10. 使用 `resume-task` 命令恢复之前的数据迁移任务。 - -## 变更 DM-worker 连接的上游 MySQL 实例地址 - -若要变更 DM-worker 的配置信息来使 DM-worker 连接到新的上游 MySQL 实例，需要按以下步骤进行操作： - -1. 使用 `query-status` 命令获取当前 relay 处理单元已从原 MySQL 实例获取到的 binlog 对应的 GTID sets (`relayBinlogGtid`)，记为 `gtid-W`。 -2. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_purged;` 获取已经被 purged 的 binlog 对应的 GTID sets，记为 `gtid-P`。 -3. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_executed;` 获取所有已经执行成功的事务对应的 GTID sets，记为 `gtid-E`。 -4. 确保满足以下关系，否则不支持将 DM-worker 连接切换到相应的 MySQL 实例： - - `gtid-W` 包含 `gtid-P`（`gtid-P` 可以为空） - - `gtid-E` 包含 `gtid-W` -5. 使用 `stop-task` 命令停止所有运行中的数据迁移任务。 -6. 更新 `inventory.ini` 中的 DM-worker 配置，并使用 DM-Ansible 对 DM-worker 进行滚动升级操作。 -7. 使用 `start-task` 命令重新启动数据迁移任务。 diff --git a/v3.0/reference/tools/data-migration/usage-scenarios/shard-merge.md b/v3.0/reference/tools/data-migration/usage-scenarios/shard-merge.md deleted file mode 100644 index 9e1b4847678b..000000000000 --- a/v3.0/reference/tools/data-migration/usage-scenarios/shard-merge.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: DM 分库分表合并场景 -category: reference -aliases: ['/docs-cn/tools/dm/shard-merge-scenario/'] ---- - -# DM 分库分表合并场景 - -本文介绍如何在分库分表合并场景中使用 Data Migration (DM)。使用场景中，三个上游 MySQL 实例的分库和分表数据需要同步至下游 TiDB 集群。 - -## 上游实例 - -假设上游库结构如下： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log_north, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log_east, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log_south, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -## 同步需求 - -1. 合并三个实例中的 `user`.`information` 表至下游 TiDB 中的 `user`.`information` 表。 -2. 合并三个实例中的 `user`.`log_{north|south|east}` 表至下游TiDB中的 `user`.`log_{north|south|east}` 表。 -3. 合并三个实例中的 `store_{01|02}`.`sale_{01|02}` 表至下游TiDB中的 `store`.`sale` 表。 -4. 过滤掉三个实例的 `user`.`log_{north|south|east}` 表的所有删除操作。 -5. 过滤掉三个实例的 `user`.`information` 表的所有删除操作。 -6. 过滤掉三个实例的 `store_{01|02}`.`sale_{01|02}` 表的所有删除操作。 -7. 过滤掉三个实例的 `user`.`log_bak` 表。 -8. 因为 `store_{01|02}`.`sale_{01|02}` 表带有 bigint 型的自增主键，将其合并至 TiDB 时会引发冲突。你需要有相应的方案来避免冲突。 - -## 下游实例 - -假设同步后下游库结构如下： - -| Schema | Tables | -|:------|:------| -| user | information, log_north, log_east, log_south| -| store | sale | - -## 同步方案 - -- 要满足同步需求 #1 和 #2，配置 [Table routing 规则](/v3.0/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - {{< copyable "" >}} - - ```yaml - routes: - ... - user-route-rule: - schema-pattern: "user" - target-schema: "user" - ``` - -- 要满足同步需求 #3，配置 [table routing 规则](/v3.0/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - {{< copyable "" >}} - - ```yaml - routes: - ... - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - ``` - -- 要满足同步需求 #4 和 #5，配置 [Binlog event filter 规则](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - {{< copyable "" >}} - - ```yaml - filters: - ... - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - ``` - - > **注意：** - > - > 同步需求 #4、#5 和 #7 的操作意味着过滤掉所有对 `user` 库的删除操作，所以此处配置了库级别的过滤规则。但是 `user` 库以后加入表的删除操作也都会被过滤。 - -- 要满足同步需求 #6，配置 [Binlog event filter 规则](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - {{< copyable "" >}} - - ```yaml - filters: - ... - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - ``` - -- 要满足同步需求 #7，配置 [Black & white table lists](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists) 如下： - - {{< copyable "" >}} - - ```yaml - black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - ``` - -- 要满足同步需求 #8，首先参考[自增主键冲突处理](/v3.0/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决冲突，保证在同步到下游时不会因为分表中有相同的主键值而使同步出现异常；然后需要配置 `ignore-checking-items` 来跳过自增主键冲突的检查： - - {{< copyable "" >}} - - ```yaml - ignore-checking-items: ["auto_increment_ID"] - ``` - -## 同步任务配置 - -同步任务的完整配置如下。详情请参阅 [Data Migration 任务配置文件](/v3.0/reference/tools/data-migration/configure/task-configuration-file.md)。 - -{{< copyable "" >}} - -```yaml -name: "shard_merge" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - - source-id: "instance-2" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例共享的其他通用配置 - -routes: - user-route-rule: - schema-pattern: "user" - target-schema: "user" - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - -filters: - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - -black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/v3.0/reference/tools/data-migration/usage-scenarios/simple-synchronization.md b/v3.0/reference/tools/data-migration/usage-scenarios/simple-synchronization.md deleted file mode 100644 index 9c254d07950d..000000000000 --- a/v3.0/reference/tools/data-migration/usage-scenarios/simple-synchronization.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Data Migration 简单使用场景 -category: reference -aliases: ['/docs-cn/tools/dm/simple-synchronization-scenario/'] ---- - -# Data Migration 简单使用场景 - -本文介绍了 DM 工具的一个简单使用场景（非分库分表合并场景）：将三个上游 MySQL 实例的数据同步到一个下游 TiDB 集群中。 - -## 上游实例 - -假设上游结构为： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_bj, store_tj | - | log | messages | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_sh, store_sz | - | log | messages | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_gz, store_sz | - | log | messages | - -## 同步要求 - -1. 不合并 `user` 库。 - - 1. 将实例 1 中的 `user` 库同步到下游 TiDB 的 `user_north` 库中。 - - 2. 将实例 2 中的 `user` 库同步到下游 TiDB 的 `user_east` 库中。 - - 3. 将实例 3 中的 `user` 库同步到下游 TiDB 的 `user_south` 库中。 - - 4. 任何情况下都不删除 `log` 表的任何数据。 - -2. 将上游 `store` 库同步到下游 `store` 库中，且同步过程中不合并表。 - - 1. 实例 2 和实例 3 中都存在 `store_sz` 表，且这两个 `store_sz` 表分别被同步到下游的 `store_suzhou` 表和 `store_shenzhen` 表中。 - - 2. 任何情况下都不删除 `store` 库的任何数据。 - -3. `log` 库需要被过滤掉。 - -## 下游实例 - -假设下游结构为： - -| Schema | Tables | -|:------|:------| -| user_north | information, log | -| user_east | information, log | -| user_south | information, log | -| store | store_bj, store_tj, store_sh, store_suzhou, store_gz, store_shenzhen | - -## 同步方案 - -- 为了满足[同步要求](#同步要求)中第一点的前三条要求，需要配置以下 [table routing 规则](/v3.0/reference/tools/data-migration/features/overview.md#table-routing)： - - {{< copyable "" >}} - - ```yaml - routes: - ... - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第一条要求，需要配置以下 [table routing 规则](/v3.0/reference/tools/data-migration/features/overview.md#table-routing)： - - {{< copyable "" >}} - - ```yaml - routes: - ... - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - ``` - -- 为了满足[同步要求](#同步要求)中第一点的第四条要求，需要配置以下 [binlog event filter 规则](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - {{< copyable "" >}} - - ```yaml - filters: - ... - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第二条要求，需要配置以下 [binlog event filter 规则](/v3.0/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - {{< copyable "" >}} - - ```yaml - filters: - ... - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - ``` - - > **注意：** - > - > `store-filter-rule` 不同于 `log-filter-rule` 和 `user-filter-rule`。`store-filter-rule` 是针对整个 `store` 库的规则，而 `log-filter-rule` 和 `user-filter-rule` 是针对 `user` 库中 `log` 表的规则。 - -- 为了满足[同步要求](#同步要求)中的第三点要求，需要配置以下 [black & white table lists 规则](/v3.0/reference/tools/data-migration/features/overview.md#black--white-table-lists)： - - {{< copyable "" >}} - - ```yaml - black-white-list: - log-ignored: - ignore-dbs: ["log"] - ``` - -## 同步任务配置 - -以下是完整的同步任务配置，详见[配置介绍](/v3.0/reference/tools/data-migration/configure/task-configuration-file.md)。 - -{{< copyable "" >}} - -```yaml -name: "one-tidb-slave" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["instance-1-user-rule"] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-2" - route-rules: ["instance-2-user-rule", instance-2-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["instance-3-user-rule", instance-3-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例的共有配置 - -routes: - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - -filters: - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - -black-white-list: - log-ignored: - ignore-dbs: ["log"] - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/v3.0/reference/tools/download.md b/v3.0/reference/tools/download.md deleted file mode 100644 index 822fe89cf82f..000000000000 --- a/v3.0/reference/tools/download.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 工具下载 -category: reference ---- - -# TiDB 工具下载 - -本页面汇总了 TiDB 周边工具官方维护版本的下载链接。 - -## TiDB Binlog - -如需下载最新版本的 [TiDB Binlog](/v3.0/reference/tidb-binlog/overview.md)，直接下载 TiDB 安装包即可，因为 TiDB Binlog 包含在 TiDB 安装包中。 - -以下表格中也提供了 Kafka 版本的 TiDB Binlog 下载链接。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (TiDB Binlog) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | -| `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz`（Kafka 版本的 TiDB Binlog）| Linux | amd64 | `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB Lightning - -使用下表中的链接下载 [TiDB Lightning](/v3.0/reference/tools/tidb-lightning/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB Lightning 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB DM (Data Migration) - -使用下表中的链接下载 [DM](/v3.0/reference/tools/data-migration/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/dm-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/dm-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 DM 的版本号。例如，`v1.0.1` 版本的下载链接为 `https://download.pingcap.org/dm-v1.0.1-linux-amd64.tar.gz`。可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## Syncer，Loader 和 Mydumper - -如需下载最新版本的 [Syncer](/v3.0/reference/tools/syncer.md)，[Loader](/v3.0/reference/tools/loader.md) 或 [Mydumper](/v3.0/reference/tools/mydumper.md)，直接下载 tidb-enterprise-tools 安装包即可，因为这些工具均包含在此安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| [tidb-enterprise-tools-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) | Linux | amd64 | [tidb-enterprise-tools-latest-linux-amd64.sha256](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256) | - -tidb-enterprise-tools 安装包包含以下工具： - -- Syncer -- Loader -- Mydumper -- ddl_checker -- [sync-diff-inspector](/v3.0/reference/tools/sync-diff-inspector/overview.md) diff --git a/v3.0/reference/tools/error-case-handling/lightning-misuse-handling.md b/v3.0/reference/tools/error-case-handling/lightning-misuse-handling.md deleted file mode 100644 index 754c9559328e..000000000000 --- a/v3.0/reference/tools/error-case-handling/lightning-misuse-handling.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: TiDB Lightning 常见的错误用法 -category: reference ---- - -# TiDB Lightning 常见的错误用法 - -本文介绍了 [TiDB Lightning](/v3.0/reference/tools/tidb-lightning/overview.md) 使用过程中常见的出错场景以及相应的处理方式。 - -## 报错：`checksum mismatched remote vs local` - -在数据导入过程中遇到下面的报错 - -```log -Error: checksum mismatched remote vs local => (checksum: 3828723015727756136 vs 7895534721177712659) (total_kvs: 1221416844 vs 1501500000) (total_bytes:237660308510 vs 292158203078) -``` - -### 原因 - -* 先前使用过 TiDB Lightning 进行数据导入，但是对应的 [checkpoint](/v3.0/reference/tools/tidb-lightning/checkpoints.md) 的数据没有被清理，存在残留的数据。可以通过查看 TiDB Lightning 第一次启动 log 来确认： - * `[checkpoint] driver = file`，如果对应 TiDB Lightning 导入时间点的 log 存在 `open checkpoint file failed, going to create a new one`，那么 `checkpoint` 已经被正确清理，否则存在残留数据可能导致导入数据缺失； - * `[checkpoint] driver = mysql`，可以通过使用 TiDB API `curl http://{TiDBIP}:10080/schema/{checkpoint.schema}/{checkpoint.table}` 来查询对应 `checkpoint table` 的创建时间，从而判断是否正确清理了 `checkpoint`。 - -* TiDB Lightning 导入的数据源存在冲突的数据 - * 不同行的数据具有相同的主键或唯一键 - -### 解决方案 - -* 删除出现 `checksum mismatch` 错误的表的数据 - - ``` - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -* 需要寻找办法检测数据源是否存在冲突数据，TiDB Lightning 一般需要处理大量的数据，所以目前还未提供有效的冲突检测和处理措施。 diff --git a/v3.0/reference/tools/error-case-handling/load-misuse-handling.md b/v3.0/reference/tools/error-case-handling/load-misuse-handling.md deleted file mode 100644 index bc8805045339..000000000000 --- a/v3.0/reference/tools/error-case-handling/load-misuse-handling.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: 全量数据导入过程常见报错处理 -category: reference ---- - -# 全量数据导入过程常见报错处理 - -本文介绍了使用 [Loader](/v3.0/reference/tools/loader.md) 或者 [TiDB Data Migration](/v3.0/reference/tools/data-migration/overview.md)（以下简称为 DM）进行全量数据导入过程中常见的因为使用造成的出错场景，以及这些错误发生的原因和处理方式。 - -## 报错：```Try adjusting the `max_allowed_packet` variable``` - -在全量数据导入过程中遇到下面的报错 - -``` -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -### 原因 - -* MySQL client 和 MySQL/TiDB Server 都有 `max_allowed_packet` 配额的限制，如果在使用过程中违反其中任何一个 `max_allowed_packet` 配额，客户端程序就会收到对应的报错。目前最新版本的 Syncer、Loader、DM 和 TiDB Server 的默认 `max_allowed_packet` 配额都为 `64M`。 - * 请使用最新版本，或者最新稳定版本的工具。[下载页面](/v3.0/reference/tools/download.md)。 -* Loader 或 DM 的全量数据导入处理模块不支持对 dump sqls 文件进行切分，原因是 Mydumper 采用了最简单的编码实现，正如 Mydumper 代码注释 `/* Poor man's data dump code */` 所言。如果在 Loader 或 DM 实现文件切分，那么需要在 `TiDB parser` 基础上实现一个完备的解析器才能正确的处理数据切分，但是随之会带来以下的问题： - * 工作量大 - * 复杂度高,不容易保证正确性 - * 性能的极大降低 - -### 解决方案 - -* 依据上面的原因，在代码层面不能简单的解决这个困扰，我们推荐的方式是：利用 Mydumper 提供的控制 `Insert Statement` 大小的功能 `-s, --statement-size`: `Attempted size of INSERT statement in bytes, default 1000000"`。 - - 依据默认的 `--statement-size` 设置，Mydumper 默认生成的 `Insert Statement` 大小会尽量接近在 `1M` 左右，使用默认值就可以确保绝大部分情况不会出现该问题。 - - 有时候在 dump 过程中会出现下面的 `WARN` log，但是这个报错不影响 dump 的过程，只是表达了 dump 的表可能是宽表。 - - ``` - Row bigger than statement_size for xxx - ``` - -* 如果宽表的单行超过了 `64M`，那么需要修改以下两个配置，并且使之生效。 - * 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728` （`134217728 = 128M`） - * 根据实际情况为 Loader 的配置文件或者 `DM task` 配置文件中的 db 配置增加类似 `max-allowed-packet=128M`，然后重启进程或者任务 diff --git a/v3.0/reference/tools/loader.md b/v3.0/reference/tools/loader.md deleted file mode 100644 index fa4624ac6c2e..000000000000 --- a/v3.0/reference/tools/loader.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Loader 使用文档 -category: reference -aliases: ['/docs-cn/tools/loader/'] ---- - -# Loader 使用文档 - -## Loader 简介 - -Loader 是由 PingCAP 开发的数据导入工具，用于向 TiDB 中导入数据。 - -Loader 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v3.0/reference/tools/download.md)。 - -## 为什么我们要做这个工具 - -当数据量比较大的时候，如果用 mysqldump 这样的工具迁移数据会比较慢。我们尝试了 [Mydumper/myloader 套件](https://github.com/maxbube/mydumper)，能够多线程导出和导入数据。在使用过程中，Mydumper 问题不大，但是 myloader 由于缺乏出错重试、断点续传这样的功能，使用起来很不方便。所以我们开发了 loader，能够读取 Mydumper 的输出数据文件，通过 MySQL protocol 向 TiDB/MySQL 中导入数据。 - -## Loader 有哪些优点 - -* 多线程导入 -* 支持表级别的并发导入，分散写入热点 -* 支持对单个大表并发导入，分散写入热点 -* 支持 Mydumper 数据格式 -* 出错重试 -* 断点续导 -* 通过 system variable 优化 TiDB 导入数据速度 - -## 使用方法 - -### 注意事项 - -请勿使用 loader 导入 MySQL 实例中 `mysql` 系统数据库到下游 TiDB。 - -如果 Mydumper 使用 -m 参数，会导出不带表结构的数据，这时 loader 无法导入数据。 - -如果使用默认的 `checkpoint-schema` 参数，在导完一个 database 数据库后，请 `drop database tidb_loader` 后再开始导入下一个 database。 - -推荐数据库开始导入的时候，明确指定 `checkpoint-schema = "tidb_loader"` 参数。 - -### 参数说明 - -``` - -L string - log 级别设置，可以设置为 debug, info, warn, error, fatal (默认为 "info") - -P int - TiDB/MySQL 的端口 (默认为 4000) - -V - 打印 loader 版本 - -c string - 指定配置文件启动 loader - -checkpoint-schema string - checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后，会通过这个库获取上次运行的进度 (默认为 "tidb_loader") - -d string - 需要导入的数据存放路径 (default "./") - -h string - TiDB 服务 host IP (default "127.0.0.1") - -p string - TiDB 账户密码 - -status-addr string - Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 - -t int - 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 - -u string - TiDB 的用户名 (默认为 "root") -``` - -### 配置文件 - -除了使用命令行参数外，还可以使用配置文件来配置，配置文件的格式如下： - -```toml -# 日志输出等级；可以设置为 debug, info, warn, error, fatal (默认为 "info") -log-level = "info" - -# 指定 loader 日志目录 -log-file = "loader.log" - -# 需要导入的数据存放路径 (default "./") -dir = "./" - -## Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 -status-addr = ":8272" - -# checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后， -# 会通过这个库获取上次运行的进度 (默认为 "tidb_loader") -checkpoint-schema = "tidb_loader" - -# 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 -pool-size = 16 - -# 目标数据库信息 -[db] -host = "127.0.0.1" -user = "root" -password = "" -port = 4000 - -# 导入数据时数据库连接所使用的 session 级别的 `sql_mode`。如果 `sql-mode` 的值没有提供或者设置为 "@DownstreamDefault"，会使用下游 global 级别的 `sql_mode`。 -# sql-mode = "" -# `max-allowed-packet` 设置数据库连接允许的最大数据包大小，对应于系统参数中的 `max_allowed_packet`。 如果设置为 0，会使用下游数据库 global 级别的 `max_allowed_packet`。 -max-allowed-packet = 67108864 - -# sharding 同步规则，采用 wildcharacter -# 1\. 星号字符 (*) 可以匹配零个或者多个字符, -# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; -# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 -# 2\. 问号字符 (?) 匹配任一一个字符 - -# [[route-rules]] -# pattern-schema = "shard_db_*" -# pattern-table = "shard_table_*" -# target-schema = "shard_db" -# target-table = "shard_table" -``` - -### 使用示例 - -通过命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -d ./test -h 127.0.0.1 -u root -P 4000 -``` - -或者使用配置文件 "config.toml": - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -c=config.toml -``` - -## FAQ - -### 合库合表场景案例说明 - -根据配置文件的 route-rules 可以支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则： - -+ 是否可以利用 route-rules 的语义规则表示 -+ 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 - -Loader 需要配置文件中开启 route-rules 参数以提供合库合表功能 - -+ 如果使用该功能，必须填写 `pattern-schema` 与 `target-schema` -+ 如果 `pattern-table` 与 `target-table` 为空，将不进行表名称合并或转换 - -```toml -[[route-rules]] -pattern-schema = "example_db" -pattern-table = "table_*" -target-schema = "example_db" -target-table = "table" -``` diff --git a/v3.0/reference/tools/mydumper.md b/v3.0/reference/tools/mydumper.md deleted file mode 100644 index b225e4e6cb08..000000000000 --- a/v3.0/reference/tools/mydumper.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: Mydumper 使用文档 -summary: 使用 Mydumper 从 TiDB 导出数据。 -category: reference -aliases: ['/docs-cn/tools/mydumper/'] ---- - -# Mydumper 使用文档 - -## Mydumper 简介 - -[Mydumper](https://github.com/pingcap/mydumper) 是一个 fork 项目，针对 TiDB 的特性进行了优化，推荐使用此工具对 TiDB 进行逻辑备份。 - -Mydumper 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v3.0/reference/tools/download.md)。 - -### 相比于普通的 Mydumper，此工具有哪些改进之处？ - -+ 对于 TiDB 可以设置 [tidb_snapshot](/v3.0/how-to/get-started/read-historical-data.md#操作流程) 的值指定备份数据的时间点，从而保证备份的一致性，而不是通过 `FLUSH TABLES WITH READ LOCK` 来保证备份一致性。 - -+ 使用 TiDB 的隐藏列 `_tidb_rowid` 优化了单表内数据的并发导出性能。 - -## 基本用法 - -### 新添参数 - -- `-z` 或 `--tidb-snapshot`：设置 `tidb_snapshot` 用于备份。默认值为当前 TSO（`SHOW MASTER STATUS` 输出的 `Position` 字段）。此参数可设为 TSO 或有效的 `datetime` 时间，例如：`-z "2016-10-08 16:45:26"`。 - -### 需要的权限 - -- SELECT -- RELOAD -- LOCK TABLES -- REPLICATION CLIENT - -### 使用举例 - -执行如下命令从 TiDB 备份数据，需要根据实际情况添加命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -``` - -## 表内并发 Dump - -### 原理 - -Mydumper 首先计算 `min(_tidb_rowid)` 和 `max(_tidb_rowid)`，然后按照 `-r` 设定的值对表划分 chunks，将 chunks 分配到不同线程并发导出。 - -### 并发 Dump 相关参数 - -- `-t` 或 `--threads`：并发线程数，默认值为 `4`。 -- `-r` 或 `--rows`：每个 chunks 包含的最大行数。设置该值后，Mydumper 将会忽略 `--chunk-filesize` 值。 - -### 示例 - -以下是一条完整的 Mydumper 命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -r 10000 -t 4 -``` - -### 支持 `_tidb_rowid` 索引的 TiDB 版本 - -由于表内并发使用 TiDB 的隐藏列 `_tidb_rowid`，数据库需要支持 `_tidb_rowid` 索引才能发挥并发导出的优势。 - -以下 TiDB 版本支持 `_tidb_rowid` 索引： - -- v2.1.3 及以上 -- v3.0 及以上 - -### 性能评估 - -在 Dump 操作前需要进行性能评估。由于并发 Scan 操作对 TiDB、TiKV 集群都会产生一定压力，所以需要评估与测试 Dump 操作对数据库集群和业务的影响。 - -## FAQ - -### 如何判断使用的 Mydumper 是否为 PingCAP 优化的版本？ - -执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -V -``` - -如果输出结果中包含 `githash`（如下列示例输出中的 `d3e6fec8b069daee772d0dbaa47579f67a5947e7`），则使用的 Mydumper 为 PingCAP 优化的版本。 - -``` -mydumper 0.9.5 (d3e6fec8b069daee772d0dbaa47579f67a5947e7), built against MySQL 5.7.24 -``` - -### 使用 Loader 恢复 Mydumper 备份出来的数据时报错 "invalid mydumper files for there are no `-schema-create.sql` files found"，应该如何解决？ - -检查使用 Mydumper 备份数据时是否使用了 `-T` 或者 `--tables-list` 配置，如果使用了这些配置，Mydumper 就不会生成包含建库 SQL 的文件。 - -**解决方法**：在 Mydumper 备份数据目录下创建文件 `{schema-name}-schema-create.sql`，在文件中写入 "CREATE DATABASE `{schema-name}`"，再运行 Loader 即可。 - -### 为什么使用 Mydumper 导出来的 TIMESTAMP 类型的数据和数据库中的数据不一致？ - -检查一下运行 Mydumper 的服务器的时区与数据库的时区是否一致，Mydumper 会根据运行所在服务器的时区对 TIMESTAMP 类型的数据进行转化，可以给 Mydumper 加上 `--skip-tz-utc` 参数禁止这种转化。 - -### 如何配置 Mydumper 的参数 `-F, --chunk-filesize`？ - -Mydumper 在备份时会根据这个参数的值把每个表的数据划分成多个 chunk，每个 chunk 保存到一个文件中，大小约为 `chunk-filesize`。根据这个参数把数据切分到多个文件中，这样就可以利用 Loader/TiDB Lightning 的并行处理逻辑提高导入速度。如果后续使用 Loader 对备份文件进行恢复，建议把该参数的值设置为 `64`（单位 MB）；如果使用 TiDB Lightning 恢复，则建议设置为 `256`（单位 MB）。 - -### 如何配置 Mydumper 的参数 `-s --statement-size`？ - -Mydumper 使用该参数控制 `Insert Statement` 的大小，默认值为 `10000000`（约 1 MB）。使用该参数来尽量避免在恢复数据时报以下错误： - -```log -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -默认值在绝大部分情况下都可以满足需求，但是**如果表为宽表，单行数据的大小可能超过 statement-size 的限制，Mydumper 会报如下的 Warning**： - -```log -Row bigger than statement_size for xxx -``` - -此时恢复数据时仍然会报 `packet for query is too large` 的错误日志，这个时候需要修改以下两个配置（以设置为 `128M` 为例）： - -* 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728`（`134217728` = `128M`）。 -* 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M` 的语句，然后重启进程或者任务。 - -### 如何设置 Mydumper 的参数 `-l, --long-query-guard`？ - -把该参数设置为预估备份需要消耗的时间，如果 Mydumper 运行时间超过该参数的值，就会报错退出。推荐初次备份设置为 `7200`（单位：秒），之后可根据具体备份时间进行调整。 - -### 如何设置 Mydumper 的参数 `--tidb-force-priority`？ - -仅当备份 TiDB 的数据时才可以设置该参数，值可以为 `LOW_PRIORITY`，`DELAYED` 或者 `HIGH_PRIORITY`。如果不希望数据备份对线上业务造成影响，推荐将该参数设置为 `LOW_PRIORITY`；如果备份的优先级更高，则可以设置为 `HIGH_PRIORITY`。 - -### Mydumper 备份 TiDB 数据报错 "GC life time is shorter than transaction duration" 应该怎么解决？ - -Mydumper 备份 TiDB 数据时为了保证数据的一致性使用了 TiDB 的 snapshot 特性，如果备份过程中 snapshot 对应的历史数据被 TiDB GC 处理了，则会报该错误。解决步骤如下： - -1. 在备份前，使用 MySQL 客户端查询 TiDB 集群的 `tikv_gc_life_time` 的值，并将其调整为一个合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 备份完成后，将 `tikv_gc_life_time` 调整为原来的值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m0s' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -### Mydumper 的参数 `--tidb-rowid` 是否需要配置？ - -如果设置该参数为 true，则导出的数据中会包含 TiDB 的隐藏列的数据。将数据恢复到 TiDB 的时候使用隐藏列会有数据不一致的风险，目前不推荐使用该参数。 - -### Mydumper 报错 "Segmentation fault" 怎么解决？ - -该 bug 已修复。如果仍然报错，可尝试升级到最新版本。 - -### Mydumper 报错 "Error dumping table ({schema}.{table}) data: line ...... (total length ...)" 怎么解决？ - -Mydumper 解析 SQL 时报错，可尝试使用最新版本。如果仍然报错，可以提 issue 到 [mydumper/issues](https://github.com/pingcap/mydumper/issues)。 - -### Mydumper 报错 "Failed to set tidb_snapshot: parsing time \"20190901-10:15:00 +0800\" as \"20190901-10:15:00 +0700 MST\": cannot parse \"\" as \"MST\"" 如何解决？ - -检查 TiDB 的版本是否低于 v2.1.11。如果是的话，需要升级 TiDB 到 v2.1.11 或以上版本。 - -### 未来是否计划让 PingCAP 对 Mydumper 的改动合并到上游？ - -是的，PingCAP 团队计划将对 Mydumper 的改动合并到上游。参见 [PR #155](https://github.com/maxbube/mydumper/pull/155)。 diff --git a/v3.0/reference/tools/pd-control.md b/v3.0/reference/tools/pd-control.md deleted file mode 100644 index 2caedccbc4f1..000000000000 --- a/v3.0/reference/tools/pd-control.md +++ /dev/null @@ -1,1139 +0,0 @@ ---- -title: PD Control 使用说明 -category: reference -aliases: ['/docs-cn/tools/pd-control/'] ---- - -# PD Control 使用说明 - -PD Control 是 PD 的命令行工具，用于获取集群状态信息和调整集群。 - -## 源码编译 - -1. [Go](https://golang.org/) Version 1.9 以上 -2. 在 PD 项目根目录使用 `make` 命令进行编译，生成 bin/pd-ctl - -## 下载安装包 - -如需下载最新版本的 `pd-ctl`，直接下载 TiDB 安装包即可，因为 `pd-ctl` 包含在 TiDB 安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (pd-ctl) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如 `v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 简单例子 - -单命令模式： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl store -u http://127.0.0.1:2379 -``` - -交互模式： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -i -u http://127.0.0.1:2379 -``` - -使用环境变量： - -{{< copyable "shell-regular" >}} - -```bash -export PD_ADDR=http://127.0.0.1:2379 && -./pd-ctl -``` - -使用 TLS 加密： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u https://127.0.0.1:2379 --cacert="path/to/ca" --cert="path/to/cert" --key="path/to/key" -``` - -## 命令行参数(flags) - -### --cacert - -- 指定 PEM 格式的受信任 CA 的证书文件路径 -- 默认值: "" - -### --cert - -- 指定 PEM 格式的 SSL 证书文件路径 -- 默认值: "" - -### \-\-detach,-d - -+ 使用单命令行模式（不进入 readline） -+ 默认值：true - -### \-\-interact,-i - -+ 使用交互模式（进入 readline） -+ 默认值：false - -### --key - -- 指定 PEM 格式的 SSL 证书密钥文件路径，即 `--cert` 所指定的证书的私钥 -- 默认值: "" - -### \-\-pd,-u - -+ 指定 PD 的地址 -+ 默认地址：`http://127.0.0.1:2379` -+ 环境变量：`PD_ADDR` - -### --version,-V - -- 打印版本信息并退出 -- 默认值: false - -## 命令(command) - -### cluster - -用于显示集群基本信息。 - -示例： - -{{< copyable "" >}} - -```bash ->> cluster -``` - -``` -{ - "id": 6493707687106161130, - "max_peer_count": 3 -} -``` - -### config [show | set \
` 操作 -# 来验证数据的完整性。 -checksum = true -# 如果设置为 true，会在导入每张表后执行一次 level-1 Compact。 -# 默认值为 false。 -level-1-compact = false -# 如果设置为 true，会在导入过程结束时对整个 TiKV 集群执行一次 full Compact。 -# 默认值为 false。 -compact = false -# 如果设置为 true，会对所有表逐个执行 `ANALYZE TABLE
` 操作。 -analyze = true - -# 设置周期性后台操作。 -# 支持的单位：h（时）、m（分）、s（秒）。 -[cron] -# Lightning 自动刷新导入模式状态的持续时间，该值应小于 TiKV 对应的设定值。 -switch-mode = "5m" -# 在日志中打印导入进度的持续时间。 -log-progress = "5m" - -# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 -# [black-white-list] -# ... -``` - -### TiKV Importer 配置参数 - -```toml -# TiKV Importer 配置文件模版 - -# 日志文件 -log-file = "tikv-importer.log" -# 日志等级：trace, debug, info, warn, error 和 off -log-level = "info" - -[server] -# tikv-importer 的监听地址，tidb-lightning 需要连到这个地址进行数据写入。 -addr = "192.168.20.10:8287" -# gRPC 服务器的线程池大小。 -grpc-concurrency = 16 - -[metric] -# 给 Prometheus 客户端推送的 job 名称。 -job = "tikv-importer" -# 给 Prometheus 客户端推送的间隔。 -interval = "15s" -# Prometheus Pushgateway 的地址。 -address = "" - -[rocksdb] -# background job 的最大并发数。 -max-background-jobs = 32 - -[rocksdb.defaultcf] -# 数据在刷新到硬盘前能存于内存的容量上限。 -write-buffer-size = "1GB" -# 内存中写缓冲器的最大数量。 -max-write-buffer-number = 8 - -# 各个压缩层级使用的算法。 -# 第 0 层的算法用于压缩 KV 数据。 -# 第 6 层的算法用于压缩 SST 文件。 -# 第 1 至 5 层的算法目前尚未使用。 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[rocksdb.writecf] -# 同上 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[import] -# 存储引擎文件的文件夹路径 -import-dir = "/mnt/ssd/data.import/" -# 处理 RPC 请求的线程数 -num-threads = 16 -# 导入 job 的并发数。 -num-import-jobs = 24 -# 预处理 Region 最长时间。 -# max-prepare-duration = "5m" -# 把要导入的数据切分为这个大小的 Region。 -#region-split-size = "512MB" -# 设置 stream-channel-window 的大小。 -# channel 满了之后 stream 会处于阻塞状态。 -# stream-channel-window = 128 -# 同时打开引擎文档的最大数量。 -max-open-engines = 8 -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# upload-speed-limit = "512MB" -# 目标存储可用空间比率（store_available_space/store_capacity）的最小值。 -# 如果目标存储空间的可用比率低于该值，Importer 将会暂停上传 SST -# 来为 PD 提供足够时间进行 Regions 负载均衡。 -min-available-ratio = 0.05 -``` - -## 命令行参数 - -### `tidb-lightning` - -使用 `tidb-lightning` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:----| -| --config *file* | 从 *file* 读取全局设置。如果没有指定则使用默认设置。 | | -| -V | 输出程序的版本 | | -| -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | -| -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | -| --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | -| --log-file *file* | 日志文件路径 | `lightning.log-file` | -| --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | -| --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | -| --pd-urls *host:port* | PD endpoint 的地址 | `tidb.pd-addr` | -| --tidb-host *host* | TiDB Server 的 host | `tidb.host` | -| --tidb-port *port* | TiDB Server 的端口（默认为 4000） | `tidb.port` | -| --tidb-status *port* | TiDB Server 的状态端口的（默认为 10080） | `tidb.status-port` | -| --tidb-user *user* | 连接到 TiDB 的用户名 | `tidb.user` | -| --tidb-password *password* | 连接到 TiDB 的密码 | `tidb.password` | - -如果同时对命令行参数和配置文件中的对应参数进行更改，命令行参数将优先生效。例如，在 `cfg.toml` 文件中，不管对日志等级做出什么修改，运行 `./tidb-lightning -L debug --config cfg.toml` 命令总是将日志级别设置为 “debug”。 - -### `tidb-lightning-ctl` - -使用 `tidb-lightning-ctl` 可以对下列参数进行配置： - -| 参数 | 描述 | -|:----|:----------| -| --compact | 执行 full compact | -| --switch-mode *mode* | 将每个 TiKV Store 切换到指定模式（normal 或 import） | -| --import-engine *uuid* | 将 TiKV Importer 上关闭的引擎文件导入到 TiKV 集群 | -| --cleanup-engine *uuid* | 删除 TiKV Importer 上的引擎文件 | -| --checkpoint-dump *folder* | 将当前的断点以 CSV 格式存储到文件夹中 | -| --checkpoint-error-destroy *tablename* | 删除断点，如果报错则删除该表 | -| --checkpoint-error-ignore *tablename* | 忽略指定表中断点的报错 | -| --checkpoint-remove *tablename* | 无条件删除表的断点 | - -*tablename* 必须是`` `db`.`tbl` `` 中的限定表名（包括反引号），或关键词 `all`。 - -此外，上表中所有 `tidb-lightning` 的参数也适用于 `tidb-lightning-ctl`。 - -### `tikv-importer` - -使用 `tikv-importer` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:-------| -| -C, --config *file* | 从 *file* 读取配置。如果没有指定，则使用默认设置| | -| -V, --version | 输出程序的版本 | | -| -A, --addr *ip:port* | TiKV Importer 服务器的监听地址 | `server.addr` | -| --import-dir *dir* | 引擎文件的存储目录 | `import.import-dir` | -| --log-level *level* | 日志的等级： trace、debug、info、warn、error 或 off | `log-level` | -| --log-file *file* | 日志文件路径 | `log-file` | diff --git a/v3.0/reference/tools/tidb-lightning/csv.md b/v3.0/reference/tools/tidb-lightning/csv.md deleted file mode 100644 index 249b51a64470..000000000000 --- a/v3.0/reference/tools/tidb-lightning/csv.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: CSV 支持 -category: reference -aliases: ['/docs-cn/tools/lightning/csv/'] ---- - -# CSV 支持 - -TiDB Lightning 支持读取 CSV（逗号分隔值）的数据源，以及其他定界符格式如 TSV（制表符分隔值）。 - -## 文件名 - -包含整张表的 CSV 文件需命名为 `db_name.table_name.csv`，该文件会被解析为数据库 `db_name` 里名为 `table_name` 的表。 - -如果一个表分布于多个 CSV 文件，这些 CSV 文件命名需加上文件编号的后缀，如 `db_name.table_name.003.csv`。 - -文件扩展名必须为 `*.csv`，即使文件的内容并非逗号分隔。 - -## 表结构 - -CSV 文件是没有表结构的。要导入 TiDB，就必须为其提供表结构。可以通过以下任一方法实现： - -* 创建包含 DDL 语句 `CREATE TABLE` 的文件 `db_name.table_name-schema.sql`。 -* 首先在 TiDB 中直接创建空表，然后在 `tidb-lightning.toml` 中设置 `[mydumper] no-schema = true`。 - -## 配置 - -CSV 格式可在 `tidb-lightning.toml` 文件中 `[mydumper.csv]` 下配置。 -大部分设置项在 MySQL [`LOAD DATA`] 语句中都有对应的项目。 - -```toml -[mydumper.csv] -# 字段分隔符，必须为 ASCII 字符。 -separator = ',' -# 引用定界符，可以为 ASCII 字符或空字符。 -delimiter = '"' -# CSV 文件是否包含表头。 -# 如果为 true，首行将会被跳过。 -header = true -# CSV 是否包含 NULL。 -# 如果为 true，CSV 文件的任何列都不能解析为 NULL。 -not-null = false -# 如果 `not-null` 为 false（即 CSV 可以包含 NULL）， -# 为以下值的字段将会被解析为 NULL。 -null = '\N' -# 是否解析字段内的反斜线转义符。 -backslash-escape = true -# 是否移除以分隔符结束的行。 -trim-last-separator = false -``` - -[`LOAD DATA`]: https://dev.mysql.com/doc/refman/8.0/en/load-data.html - -### `separator` - -- 指定字段分隔符。 -- 必须为单个 ASCII 字符。 -- 常用值： - - * CSV 用 `','` - * TSV 用 `"\t"` - -- 对应 LOAD DATA 语句中的 `FIELDS TERMINATED BY` 项。 - -### `delimiter` - -- 指定引用定界符。 -- 如果 `delimiter` 为空，所有字段都会被取消引用。 -- 常用值： - - * `'"'` 使用双引号引用字段，和 [RFC 4180] 一致。 - * `''` 不引用 - -- 对应 LOAD DATA 语句中的 `FIELDS ENCLOSED BY` 项。 - -[RFC 4180]: https://tools.ietf.org/html/rfc4180 - -### `header` - -- 是否*所有* CSV 文件都包含表头行。 -- 如为 true，第一行会被用作*列名*。如为 false，第一行并无特殊性，按普通的数据行处理。 - -### `not-null` 和 `null` - -- `not-null` 决定是否所有字段不能为空。 -- 如果 `not-null` 为 false，设定了 `null` 的字符串会被转换为 SQL NULL 而非具体数值。 -- 引用不影响字段是否为空。 - - 例如有如下 CSV 文件： - - ```csv - A,B,C - \N,"\N", - ``` - - 在默认设置（`not-null = false; null = '\N'`）下，列 `A` and `B` 导入 TiDB 后都将会转换为 NULL。列 `C` 是空字符串 `''`，但并不会解析为 NULL。 - -### `backslash-escape` - -- 是否解析字段内的反斜线转义符。 -- 如果 `backslash-escape` 为 true，下列转义符会被识别并转换。 - - | 转义符 | 转换为 | - |----------|--------------------------| - | `\0` | 空字符 (U+0000) | - | `\b` | 退格 (U+0008) | - | `\n` | 换行 (U+000A) | - | `\r` | 回车 (U+000D) | - | `\t` | 制表符 (U+0009) | - | `\Z` | Windows EOF (U+001A) | - - 其他情况下（如 `\"`）反斜线会被移除，仅在字段中保留其后面的字符（`"`）。 - -- 引用不会影响反斜线转义符的解析与否。 - -- 对应 LOAD DATA 语句中的 `FIELDS ESCAPED BY '\'` 项。 - -### `trim-last-separator` - -- 将 `separator` 字段当作终止符，并移除尾部所有分隔符。 - - 例如有如下 CSV 文件： - - ```csv - A,,B,, - ``` - -- 当 `trim-last-separator = false`，该文件会被解析为包含 5 个字段的行 `('A', '', 'B', '', '')`。 -- 当 `trim-last-separator = true`，该文件会被解析为包含 3 个字段的行 `('A', '', 'B')`。 - -### 不可配置项 - -TiDB Lightning 并不完全支持 `LOAD DATA` 语句中的所有配置项。例如： - -* 行终止符只能是 CR（`\r`），LF（`\n`）或 CRLF（`\r\n`），也就是说，无法自定义 `LINES TERMINATED BY`。 -* 不可使用行前缀 （`LINES STARTING BY`）。 -* 不可跳过表头（`IGNORE n LINES`）。如有表头，必须是有效的列名。 -* 定界符和分隔符只能为单个 ASCII 字符。 - -## 通用配置 - -### CSV - -默认设置已按照 RFC 4180 调整。 - -```toml -[mydumper.csv] -separator = ',' -delimiter = '"' -header = true -not-null = false -null = '\N' -backslash-escape = true -trim-last-separator = false -``` - -示例内容： - -``` -ID,Region,Count -1,"East",32 -2,"South",\N -3,"West",10 -4,"North",39 -``` - -### TSV - -```toml -[mydumper.csv] -separator = "\t" -delimiter = '' -header = true -not-null = false -null = 'NULL' -backslash-escape = false -trim-last-separator = false -``` - -示例内容： - -``` -ID Region Count -1 East 32 -2 South NULL -3 West 10 -4 North 39 -``` - -### TPC-H DBGEN - -```toml -[mydumper.csv] -separator = '|' -delimiter = '' -header = false -not-null = true -backslash-escape = false -trim-last-separator = true -``` - -示例内容： - -``` -1|East|32| -2|South|0| -3|West|10| -4|North|39| -``` diff --git a/v3.0/reference/tools/tidb-lightning/deployment.md b/v3.0/reference/tools/tidb-lightning/deployment.md deleted file mode 100644 index 11984a06c35c..000000000000 --- a/v3.0/reference/tools/tidb-lightning/deployment.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: TiDB Lightning 部署与执行 -category: reference -aliases: ['/docs-cn/tools/lightning/deployment/'] ---- - -# TiDB Lightning 部署与执行 - -本文主要介绍 TiDB Lightning 使用 Importer-backend（默认）进行数据导入的硬件需求，以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 - -如果你想改用 TiDB-backend 进行数据导入，参考 [TiDB Lightning TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 - -## 注意事项 - -在使用 TiDB Lightning 前，需注意以下事项： - -- TiDB Lightning 运行后，TiDB 集群将无法正常对外提供服务。 -- 若 `tidb-lightning` 崩溃，集群会留在“导入模式”。若忘记转回“普通模式”，集群会产生大量未压缩的文件，继而消耗 CPU 并导致延迟。此时，需要使用 `tidb-lightning-ctl` 手动将集群转回“普通模式”： - - {{< copyable "shell-regular" >}} - - ```sh - bin/tidb-lightning-ctl -switch-mode=normal - ``` - -- TiDB Lightning 需要下游 TiDB 有如下权限： - - | 权限 | 作用域 | - |:----|:------| - | SELECT | Tables | - | INSERT | Tables | - | UPDATE | Tables | - | DELETE | Tables | - | CREATE | Databases, tables | - | DROP | Databases, tables | - | ALTER | Tables | - - 如果配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## 硬件需求 - -`tidb-lightning` 和 `tikv-importer` 这两个组件皆为资源密集程序，建议各自单独部署。 - -为了优化效能，建议硬件配置如下： - -- `tidb-lightning` - - - 32+ 逻辑核 CPU - - 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程默认会占满 CPU，建议单独部署。条件不允许的情况下可以和其他组件（比如 `tidb-server`）部署在同一台机器上，然后通过配置 `region-concurrency` 限制 `tidb-lightning` 使用 CPU 资源。 - -- `tikv-importer` - - - 32+ 逻辑核 CPU - - 40 GB+ 内存 - - 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000） - * 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程中 CPU、I/O 和网络带宽都可能占满，建议单独部署。 - -如果机器充裕的话，可以部署多套 `tidb-lightning` + `tikv-importer`，然后将源数据以表为粒度进行切分，并发导入。 - -> **注意：** -> -> - `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 资源分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 “24”。 -> -> - `tikv-importer` 将中间数据存储缓存到内存上以加速导入过程。占用内存大小可以通过 **(`max-open-engines` × `write-buffer-size` × 2) + (`num-import-jobs` × `region-split-size` × 2)** 计算得来。如果磁盘写入速度慢，缓存可能会带来更大的内存占用。 - -此外，目标 TiKV 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](/v3.0/how-to/deploy/hardware-recommendations.md)以外，目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](/v3.0/faq/tidb.md#326-每个-region-的-replica-数量可配置吗调整的方法是) × 2**。例如集群默认使用 3 副本，那么总存储空间需为数据源大小的 6 倍以上。 - -## 导出数据 - -使用 [`mydumper`](/v3.0/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果数据源是 CSV 文件，请参考 [CSV 支持](/v3.0/reference/tools/tidb-lightning/csv.md)获取配置信息。 - -## 部署 TiDB Lightning - -本节介绍 TiDB Lightning 的两种部署方式：[使用 Ansible 部署](#使用-ansible-部署-tidb-lightning)和[手动部署](#手动部署-tidb-lightning)。 - -### 使用 Ansible 部署 TiDB Lightning - -TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/v3.0/how-to/deploy/orchestrated/ansible.md)。 - -1. 编辑 `inventory.ini`，分别配置一个 IP 来部署 `tidb-lightning` 和 `tikv-importer`。 - - ```ini - ... - - [importer_server] - 192.168.20.9 - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 修改 `group_vars/*.yml` 的变量配置这两个工具。 - - - `group_vars/all.yml` - - ```yaml - ... - # tikv-importer 的监听端口。需对 tidb-lightning 服务器开放。 - tikv_importer_port: 8287 - ... - ``` - - - `group_vars/lightning_server.yml` - - ```yaml - --- - dummy: - - # 提供监控告警的端口。需对监控服务器 (monitoring_server) 开放。 - tidb_lightning_pprof_port: 8289 - - # 获取数据源（Mydumper SQL dump 或 CSV）的路径。 - data_source_dir: "{{ deploy_dir }}/mydumper" - ``` - - - `group_vars/importer_server.yml` - - ```yaml - --- - dummy: - - # 储存引擎文件的路径。需存放在空间足够大的分区。 - import_dir: "{{ deploy_dir }}/data.import" - ``` - -3. 开始部署。 - - {{< copyable "shell-regular" >}} - - ```sh - ansible-playbook bootstrap.yml && - ansible-playbook deploy.yml - ``` - -4. 将数据源写入 `data_source_dir` 指定的路径。 - -5. 登录 `tikv-importer` 的服务器，并执行以下命令来启动 Importer。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_importer.sh - ``` - -6. 登录 `tidb-lightning` 的服务器，并执行以下命令来启动 Lightning，开始导入过程。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_lightning.sh - ``` - -7. 完成后，在 `tikv-importer` 的服务器执行 `scripts/stop_importer.sh` 来关闭 Importer。 - -### 手动部署 TiDB Lightning - -#### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群 (版本要求 2.0.9 以上)，建议使用最新版。部署方法可参考 [TiDB 快速入门指南](/v3.0/overview.md#部署方式)。 - -#### 第 2 步：下载 TiDB Lightning 安装包 - -在[工具下载](/v3.0/reference/tools/download.md#tidb-lightning)页面下载 TiDB Lightning 安装包（需选择与 TiDB 集群相同的版本）。 - -#### 第 3 步：启动 `tikv-importer` - -1. 从安装包上传 `bin/tikv-importer`。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [metric] - # 给 Prometheus 客户端的推送任务名称。 - job = "tikv-importer" - # 给 Prometheus 客户端的推送间隔。 - interval = "15s" - # Prometheus Pushgateway 地址。 - address = "" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - - 上面仅列出了 `tikv-importer` 的基本配置。完整配置请参考[`tikv-importer` 配置说明](/v3.0/reference/tools/tidb-lightning/config.md#tikv-importer)。 - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -#### 第 4 步：启动 `tidb-lightning` - -1. 从安装包上传 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl`。 - -2. 将数据源写入到同样的机器。 - -3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置，TiDB Lightning 给出配置错误的提醒并退出。 - - ```toml - [lightning] - - # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。 - # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。 - # region-concurrency = - - # 日志 - level = "info" - file = "tidb-lightning.log" - - [tikv-importer] - # tikv-importer 的监听地址，需改成 tikv-importer 服务器的实际地址。 - addr = "172.16.31.10:8287" - - [mydumper] - # Mydumper 源数据目录。 - data-source-dir = "/data/my_database" - - [tidb] - # 目标集群的信息。tidb-server 的监听地址，填一个即可。 - host = "172.16.31.1" - port = 4000 - user = "root" - password = "" - # 表架构信息在从 TiDB 的“状态端口”获取。 - status-port = 10080 - ``` - - 上面仅列出了 `tidb-lightning` 的基本配置。完整配置请参考[`tidb-lightning` 配置说明](/v3.0/reference/tools/tidb-lightning/config.md#tidb-lightning-全局配置)。 - -4. 运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & - ``` - -## 升级 TiDB Lightning - -你可以通过替换二进制文件升级 TiDB Lightning，无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/v3.0/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 - -如果当前有运行的导入任务，推荐任务完成后再升级 TiDB Lightning。否则，你可能需要从头重新导入，因为无法保证断点可以跨版本工作。 \ No newline at end of file diff --git a/v3.0/reference/tools/tidb-lightning/glossary.md b/v3.0/reference/tools/tidb-lightning/glossary.md deleted file mode 100644 index 7ed4ff16f45b..000000000000 --- a/v3.0/reference/tools/tidb-lightning/glossary.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: TiDB Lightning 术语表 -summary: 了解 TiDB Lightning 相关的术语及定义。 -category: glossary ---- - -# TiDB Lightning 术语表 - -本术语表提供了 TiDB Lightning 相关的术语和定义，这些术语会出现在 TiDB Lightning 的日志、监控指标、配置和文档中。 - - - -## A - -### Analyze - -统计信息分析。指重建 TiDB 表中的统计信息，即运行 [`ANALYZE TABLE`](/v3.0/reference/sql/statements/analyze-table.md) 语句。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，统计信息不会自动更新，所以 TiDB Lightning 在导入后显式地分析每个表。如果不需要该操作，可以将 `post-restore.analyze` 设置为 `false`。 - -### `AUTO_INCREMENT_ID` - -用于为自增列分配默认值的自增 ID 计数器。每张表都有一个相关联的 `AUTO_INCREMENT_ID` 计数器。在 TiDB 中，该计数器还用于分配行 ID。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，`AUTO_INCREMENT_ID` 计数器不会自动更新，所以 TiDB Lightning 显式地将 `AUTO_INCREMENT_ID` 改为一个有效值。即使表中没有自增列，这步仍是会执行。 - - - -## B - -### Backend - -也称作 Back end（后端），用于接受 TiDB Lightning 解析结果。 - -详情参阅 [TiDB Lightning TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md)。 - -### Black-white list - -黑白名单配置列表。用于指定要导入、忽略哪些表和库。 - -详情参阅 [TiDB Lightning 表库过滤](/v3.0/reference/tools/tidb-lightning/table-filter.md)。 - - - -## C - -### Checkpoint - -断点。用于保证 TiDB Lightning 在导入数据时不断地将进度保存到本地文件或远程数据库中。这样即使进程崩溃，TiDB Lightning 也能从中间状态恢复。 - -详情参见 [TiDB Lightning 断点续传](/v3.0/reference/tools/tidb-lightning/checkpoints.md)。 - -### Checksum - -校验和。一种用于[验证导入数据正确性](/v3.0/faq/tidb-lightning.md#如何校验导入的数据的正确性)的方法。 - -在 TiDB Lightning 中，表的校验和是由 3 个数字组成的集合，由该表中每个键值对的内容计算得出。这些数字分别是： - -* 键值对的数量 -* 所有键值对的总长度 -* 每个键值对 [CRC-64-ECMA](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) 按位异或的结果 - -TiDB Lightning 通过比较每个表的[本地校验和](#local-checksum)和[远程校验和](#remote-checksum)来验证导入数据的正确性。如果有任一对校验和不匹配，导入进程就会停止。如果你需要跳过校验和检查，可以将 `post-restore.checksum` 设置为 `false` 。 - -遇到校验和不匹配的问题时，参考[故障排查](/v3.0/how-to/troubleshoot/tidb-lightning.md#checksum-failed-checksum-mismatched-remote-vs-local)进行处理。 - -### Chunk - -指数据源中的单个文件。 - -### Compaction - -压缩。指将多个小 SST 文件合并为一个大 SST 文件并清理已删除的条目。TiDB Lightning 导入数据时，TiKV 在后台会自动压缩数据。 - -> **注意：** -> -> 出于遗留原因，你仍然可以将 TiDB Lightning 配置为在每次导入表时进行显式压缩，但是官方不推荐采用该操作，且该操作的相关设置默认是禁用的。 -> -> 技术细节参阅 [RocksDB 关于压缩的说明](https://github.com/facebook/rocksdb/wiki/Compaction)。 - - - -## D - -### Data engine - -数据引擎。用于对实际的行数据进行排序的[引擎](#engine)。 - -当一个表数据很多的时候，表的数据会被放置在多个数据引擎中以改善任务流水线并节省 TiKV Importer 的空间。默认条件下，每 100 GB 的 SQL 数据会打开一个新的数据引擎（可通过 `mydumper.batch-size` 配置项进行更改）。 - -TiDB Lightning 同时处理多个数据引擎（可通过 `lightning.table-concurrency` 配置项进行更改）。 - - - -## E - -### Engine - -引擎。在 TiKV Importer 中，一个引擎就是一个用于排序键值对的 RocksDB 实例。 - -TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先打开一个引擎，向其发送未排序的键值对，然后关闭引擎。随后，引擎会对收到的键值对进行排序操作。这些关闭的引擎可以进一步上传至 TiKV store 中为 [Ingest](#ingest) 做准备。 - -引擎使用 TiKV Importer 的 `import-dir` 作为临时存储，有时也会被称为引擎文件 (engine files)。 - -另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 - - - -## I - -### Import mode - -导入模式。指通过降低读取速度和减少空间使用，来优化 TiKV 写入的配置模式。 - -导入过程中，TiDB Lightning 自动在导入模式和[普通模式](#normal-mode)中来回切换。如果 TiKV 卡在导入模式，你可以使用 `tidb-lightning-ctl` [强制切换回普通模式](/v3.0/faq/tidb-lightning.md#为什么用过-tidb-lightning-之后tidb-集群变得又慢又耗-cpu)。 - -### Index engine - -索引引擎。用于对索引进行排序的[引擎](#engine)。 - -不管表中有多少索引，每张表都只对应**一个**索引引擎。 - -TiDB Lightning 可同时处理多个索引引擎（可通过 `lightning.index-concurrency` 配置项进行更改）。由于每张表正好对应一个索引引擎，`lightning.index-concurrency` 配置项也限定了可同时处理的表的最大数量。 - -### Ingest - -指将 [SST 文件](#sst-file)的全部内容插入到 RocksDB（TiKV）store 中的操作。 - -与逐个插入键值对相比，Ingest 的效率非常高。因此，该操作直接决定了 TiDB Lightning 的性能。 - -技术细节参阅 [RocksDB 关于创建、Ingest SST 文件的 wiki 页面](https://github.com/facebook/rocksdb/wiki/Creating-and-Ingesting-SST-files)。 - - - -## K - -### KV pair - -即 key-value pair（键值对）。 - -### KV encoder - -用于将 SQL 或 CSV 行解析为键值对的例程。多个 KV encoder 会并行运行以加快处理速度。 - - - -## L - -### Local checksum - -本地校验和。在将键值对发送到 TiKV Importer 前，由 TiDB Lightning 计算的表的校验和。 - - - -## N - -### Normal mode - -普通模式。未启用[导入模式](#import-mode)时的模式。 - - - -## P - -### Post-processing - -指整个数据源被解析发送到 TiKV Importer 之后的一段时间。此时 TiDB Lightning 正在等待 TiKV Importer 上传、[Ingest](#ingest) [SST 文件](#sst-file)。 - - - -## R - -### Remote checksum - -远程校验和。指导入 TiDB 后所计算的表的[校验和](#checksum)。 - - - -## S - -### Scattering - -指随机再分配 [Region](/v3.0/glossary.md#regionpeerraft-group) 中 leader 和 peer 的操作。Scattering 确保导入的数据在 TiKV store 中均匀分布，这样可以降低 PD 调度的压力。 - -### Splitting - -指 TiKV Importer 在上传之前会将单个引擎文件拆分为若干小 [SST 文件](#sst-file)的操作。这是因为引擎文件通常很大（约为 100 GB），在 TiKV 中不适合视为单一的 [Region](/v3.0/glossary.md#regionpeerraft-group)。拆分的文件大小可通过 `import.region-split-size` 配置项更改。 - -### SST file - -Sorted string table file（排序字符串表文件）。SST 文件是一种在 RocksDB 中（因而也是 TiKV 中）键值对集合在本地的存储形式。 - -TiKV Importer 从关闭的[引擎](#engine)中生成 SST 文件。这些 SST 文件接着被上传、[ingest](#ingest) 到 TiKV store 中。 diff --git a/v3.0/reference/tools/tidb-lightning/monitor.md b/v3.0/reference/tools/tidb-lightning/monitor.md deleted file mode 100644 index 1378cba5d0c8..000000000000 --- a/v3.0/reference/tools/tidb-lightning/monitor.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: TiDB Lightning 监控告警 -category: reference ---- - -# TiDB Lightning 监控告警 - -`tidb-lightning` 和 `tikv-importer` 都支持使用 [Prometheus](https://prometheus.io/) 采集监控指标 (metrics)。本文主要介绍 TiDB Lightning 的监控配置与监控指标。 - -## 监控配置 - -- 如果是使用 TiDB Ansible 部署 Lightning，只要将服务器地址加到 `inventory.ini` 文件里的 `[monitored_servers]` 部分即可。 -- 如果是手动部署 Lightning，则参照以下步骤进行配置。 - -### `tikv-importer` - -`tikv-importer` v2.1 使用 [Pushgateway](https://github.com/prometheus/pushgateway) 来推送监控指标。需要配置 `tikv-importer.toml` 来连接 Pushgateway： - -```toml -[metric] - -# 给 Prometheus 客户端的推送任务名称。 -job = "tikv-importer" - -# 给 Prometheus 客户端的推送间隔。 -interval = "15s" - -# Prometheus Pushgateway 地址。 -address = "" -``` - -### `tidb-lightning` - -只要 Prometheus 能发现 `tidb-lightning` 的监控地址，就能收集监控指标。 - -监控的端口可在 `tidb-lightning.toml` 中配置： - -```toml -[lightning] -# 用于调试和 Prometheus 监控的 HTTP 端口。输入 0 关闭。 -pprof-port = 8289 - -... -``` - -要让 Prometheus 发现 Lightning，可以将地址直接写入其配置文件，例如： - -{{< copyable "" >}} - -```yaml -... -scrape_configs: - - job_name: 'tidb-lightning' - static_configs: - - targets: ['192.168.20.10:8289'] -``` - -## Grafana 面板 - -[Grafana](https://grafana.com/) 的可视化面板可以让你在网页上监控 Prometheus 指标。 - -使用 TiDB Ansible 部署 TiDB 集群时，会同时部署一套 Grafana + Prometheus 的监控系统。 - -如果使用其他方式部署 TiDB Lightning，需先导入[面板的 JSON 文件](https://raw.githubusercontent.com/pingcap/tidb-ansible/master/scripts/lightning.json)。 - -### 第一行：速度面板 - -![第一行速度面板](/media/lightning-grafana-row-1.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Import speed | write from lightning | 从 TiDB Lightning 向 TiKV Importer 发送键值对的速度，取决于每个表的复杂性 | -| Import speed | upload to tikv | 从 TiKV Importer 上传 SST 文件到所有 TiKV 副本的总体速度 | -| Chunk process duration | | 完全编码单个数据文件所需的平均时间 | - -有时导入速度会降到 0，这是为了平衡其他部分的速度，属于正常现象。 - -### 第二行：进度面板 - -![第二行进度面板](/media/lightning-grafana-row-2.png) - -| 面板名称 | 描述 | -|:-----|:-----| -| Import progress | 已编码的文件所占百分比 | -| Checksum progress | 已导入的表所占百分比 | -| Failures | 导入失败的表的数量以及故障点，通常为空 | - -### 第三行：资源使用面板 - -![第三行资源使用面板](/media/lightning-grafana-row-3.png) - -| 面板名称 | 描述 | -|:-----|:-----| -| Memory usage | 每个服务占用的内存 | -| Number of Lightning Goroutines | TiDB Lightning 使用的运行中的 goroutines 数量 | -| CPU% | 每个服务使用的逻辑 CPU 数量 | - -### 第四行：配额使用面板 - -![第四行配额使用面板](/media/lightning-grafana-row-4.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Idle workers | io | 未使用的 `io-concurrency` 的数量，通常接近配置值（默认为 5），接近 0 时表示磁盘运行太慢 | -| Idle workers | closed-engine | 已关闭但未清理的引擎数量，通常接近 `index-concurrency` 与 `table-concurrency` 的和（默认为 8），接近 0 时表示 TiDB Lightning 比 TiKV Importer 快，导致 TiDB Lightning 延迟 | -| Idle workers | table | 未使用的 `table-concurrency` 的数量，通常为 0，直到进程结束 | -| Idle workers | index | 未使用的 `index-concurrency` 的数量，通常为 0，直到进程结束 | -| Idle workers | region | 未使用的 `region-concurrency` 的数量，通常为 0，直到进程结束 | -| External resources | KV Encoder | 已激活的 KV encoder 的数量，通常与 `region-concurrency` 的数量相同，直到进程结束 | -| External resources | Importer Engines | 打开的引擎文件数量，不应超过 `max-open-engines` 的设置 | - -### 第五行：读取速度面板 - -![第五行读取速度面板](/media/lightning-grafana-row-5.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Chunk parser read block duration | read block | 读取一个字节块来准备解析时所消耗的时间 | -| Chunk parser read block duration | apply worker | 等待 `io-concurrency` 空闲所消耗的时间 | -| SQL process duration | row encode | 解析和编码单行所消耗的时间 | -| SQL process duration | block deliver | 将一组键值对发送到 TiKV Importer 所消耗的时间 | - -如果上述项的持续时间过长，则表示 TiDB Lightning 使用的磁盘运行太慢或 I/O 太忙。 - -### 第六行：存储空间面板 - -![第六行存储空间面板](/media/lightning-grafana-row-6.png) - -| 面板名称 | 序列 |描述 | -|:-----|:-----|:-----| -| SQL process rate | data deliver rate | 向 TiKV Importer 发送数据键值对的速度 | -| SQL process rate | index deliver rate | 向 TiKV Importer 发送索引键值对的速度 | -| SQL process rate | total deliver rate | 发送数据键值对及索引键值对的速度之和 | -| Total bytes | parser read size | TiDB Lightning 正在读取的字节数 | -| Total bytes | data deliver size | 已发送到 TiKV Importer 的数据键值对的字节数 | -| Total bytes | index deliver size | 已发送到 TiKV Importer 的索引键值对的字节数 | -| Total bytes | storage_size/3 | TiKV 集群占用的存储空间大小的 1/3（3 为默认的副本数量）| - -### 第七行：导入速度面板 - -![第七行导入速度面板](/media/lightning-grafana-row-7.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Delivery duration | Range delivery | 将一个 range 的键值对上传到 TiKV 集群所消耗的时间 | -| Delivery duration | SST delivery | 将单个 SST 文件上传到 TiKV 集群所消耗的时间 | -| SST process duration | Split SST | 将键值对流切分成若干 SST 文件所消耗的时间 | -| SST process duration | SST upload | 上传单个 SST 文件所消耗的时间 | -| SST process duration | SST ingest | ingest 单个 SST 文件所消耗的时间 | -| SST process duration | SST size | 单个 SST 文件的大小 | - -## 监控指标 - -本节将详细描述 `tikv-importer` 和 `tidb-lightning` 的监控指标。 - -### `tikv-importer` - -`tikv-importer` 的监控指标皆以 `tikv_import_*` 为前缀。 - -- **`tikv_import_rpc_duration`**（直方图） - - 完成一次 RPC 用时直方图。标签： - - - **request**：所执行 RPC 请求的类型 - * `switch_mode` — 将一个 TiKV 节点切换为 import/normal 模式 - * `open_engine` — 打开引擎文件 - * `write_engine` — 接收数据并写入引擎文件 - * `close_engine` — 关闭一个引擎文件 - * `import_engine` — 导入一个引擎文件到 TiKV 集群中 - * `cleanup_engine` — 删除一个引擎文件 - * `compact_cluster` — 显式压缩 TiKV 集群 - * `upload` — 上传一个 SST 文件 - * `ingest` — Ingest 一个 SST 文件 - * `compact` — 显式压缩一个 TiKV 节点 - - **result**：RPC 请求的执行结果 - * `ok` - * `error` - -- **`tikv_import_write_chunk_bytes`**（直方图） - - 从 Lightning 接收的键值对区块大小（未压缩）的直方图。 - -- **`tikv_import_write_chunk_duration`**（直方图） - - 从 `tidb-lightning` 接收每个键值对区块所需时间的直方图。 - -- **`tikv_import_upload_chunk_bytes`**（直方图） - - 上传到 TiKV 的每个 SST 文件区块大小（压缩）的直方图。 - -- **`tikv_import_range_delivery_duration`**（直方图） - - 将一个 range 的键值对发送至 `dispatch-job` 任务所需时间的直方图。 - -- **`tikv_import_split_sst_duration`**（直方图） - - 将 range 从引擎文件中分离到单个 SST 文件中所需时间的直方图。 - -- **`tikv_import_sst_delivery_duration`**（直方图） - - 将 SST 文件从 `dispatch-job` 任务发送到 `ImportSSTJob` 任务所需时间的直方图 - -- **`tikv_import_sst_recv_duration`**（直方图） - - `ImportSSTJob` 任务接收从 `dispatch-job` 任务发送过来的 SST 文件所需时间的直方图。 - -- **`tikv_import_sst_upload_duration`**（直方图） - - 从 `ImportSSTJob` 任务上传 SST 文件到 TiKV 节点所需时间的直方图。 - -- **`tikv_import_sst_chunk_bytes`**（直方图） - - 上传到 TiKV 节点的 SST 文件（压缩）大小的直方图。 - -- **`tikv_import_sst_ingest_duration`**（直方图） - - 将 SST 文件传入至 TiKV 所需时间的直方图。 - -- **`tikv_import_each_phase`**（测量仪） - - 表示运行阶段。值为 1 时表示在阶段内运行，值为 0 时表示在阶段内运行。标签： - - - **phase**：`prepare` / `import` - -- **`tikv_import_wait_store_available_count`**（计数器） - - 计算出现 TiKV 节点没有充足空间上传 SST 文件现象的次数。标签： - - - **store_id**： TiKV 存储 ID。 - -- **`tikv_import_upload_chunk_duration`**（直方图） - - 上传到 TiKV 的每个区块所需时间的直方图。 - -### `tidb-lightning` - -`tidb-lightning` 的监控指标皆以 `lightning_*` 为前缀。 - -- **`lightning_importer_engine`**（计数器） - - 计算已开启及关闭的引擎文件数量。标签： - - - **type**: - * `open` - * `closed` - -- **`lightning_idle_workers`**（计量表盘） - - 计算闲置的 worker。标签： - - - **name**： - * `table` — 未使用的 `table-concurrency` 的数量，通常为 0，直到进程结束 - * `index` — 未使用的 `index-concurrency` 的数量，通常为 0，直到进程结束 - * `region` — 未使用的 `region-concurrency` 的数量，通常为 0，直到进程结束 - * `io` — 未使用的 `io-concurrency` 的数量，通常接近配置值（默认为 5），接近 0 时表示磁盘运行太慢 - * `closed-engine` — 已关闭但未清理的引擎数量，通常接近 `index-concurrency` 与 `table-concurrency` 的和（默认为 8），接近 0 时表示 TiDB Lightning 比 TiKV Importer 快，导致 TiDB Lightning 延迟 - -- **`lightning_kv_encoder`**（计数器） - - 计算已开启及关闭的 KV 编码器。KV 编码器是运行于内存的 TiDB 实例，用于将 SQL 的 `INSERT` 语句转换成键值对。此度量的净值（开启减掉关闭）在正常情况下不应持续增长。标签： - - - **type**: - * `open` - * `closed` - -- **`lightning_tables`**（计数器） - - 计算处理过的表及其状态。标签： - - - **state**：表的状态，表明当前应执行的操作 - * `pending` — 等待处理 - * `written` — 所有数据已编码和传输 - * `closed` — 所有对应的引擎文件已关闭 - * `imported` — 所有引擎文件已上传到目标集群 - * `altered_auto_inc` — 自增 ID 已改 - * `checksum` — 已计算校验和 - * `analyzed` — 已进行统计信息分析 - * `completed` — 表格已完全导入并通过验证 - - **result**：当前操作的执行结果 - * `success` — 成功 - * `failure` — 失败（未完成） - -- **`lightning_engines`**（计数器） - - 计算处理后引擎文件的数量以及其状态。标签： - - - **state**：引擎文件的状态，表明当前应执行的操作 - * `pending` — 等待处理 - * `written` — 所有数据已编码和传输 - * `closed` — 引擎文件已关闭 - * `imported` — 当前引擎文件已上传到目标集群 - * `completed` — 当前引擎文件已完全导入 - - **result**：当前操作的执行结果 - * `success` — 成功 - * `failure` — 失败（未完成） - -- **`lightning_chunks`**（计数器） - - 计算处理过的 Chunks 及其状态。标签： - - - **state**: 单个 Chunk 的状态，表明该 Chunk 当前所处的阶段 - * `estimated` — （非状态）当前任务中 Chunk 的数量 - * `pending` — 已载入但未执行 - * `running` — 正在编码和发送数据 - * `finished` — 该 Chunk 已处理完毕 - * `failed` — 处理过程中发生错误 - -- **`lightning_import_seconds`**（直方图） - - 导入每个表所需时间的直方图。 - -- **`lightning_row_read_bytes`**（直方图） - - 单行 SQL 数据大小的直方图。 - -- **`lightning_row_encode_seconds`**（直方图） - - 解码单行 SQL 数据到键值对所需时间的直方图。 - -- **`lightning_row_kv_deliver_seconds`**（直方图） - - 发送一组与单行 SQL 数据对应的键值对所需时间的直方图。 - -- **`lightning_block_deliver_seconds`**（直方图） - - 每个键值对中的区块传送到 `tikv-importer` 所需时间的直方图。 - -- **`lightning_block_deliver_bytes`**（直方图） - - 发送到 Importer 的键值对中区块（未压缩）的大小的直方图。 - -- **`lightning_chunk_parser_read_block_seconds`**（直方图） - - 数据文件解析每个 SQL 区块所需时间的直方图。 - -- **`lightning_checksum_seconds`**（直方图） - - 计算表中 Checksum 所需时间的直方图。 - -- **`lightning_apply_worker_seconds`**（直方图） - - 获取闲置 worker 等待时间的直方图 (参见 `lightning_idle_workers` 计量表盘)。标签： - - - **name**： - * `table` - * `index` - * `region` - * `io` - * `closed-engine` diff --git a/v3.0/reference/tools/tidb-lightning/overview.md b/v3.0/reference/tools/tidb-lightning/overview.md deleted file mode 100644 index 48dd93c937a7..000000000000 --- a/v3.0/reference/tools/tidb-lightning/overview.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: TiDB Lightning 简介 -category: reference ---- - -# TiDB Lightning 简介 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量数据的备份恢复。目前，支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -## TiDB Lightning 整体架构 - -TiDB Lightning 主要包含两个部分： - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键值对（KV 对）发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，对 `tidb-lightning` 写入的键值对进行缓存、排序、切分操作并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -TiDB Lightning 整体工作原理如下： - -1. 在导数据之前，`tidb-lightning` 会自动将 TiKV 集群切换为“导入模式” (import mode)，优化写入效率并停止自动压缩。 - -2. `tidb-lightning` 会在目标数据库建立架构和表，并获取其元数据。 - -3. 每张表都会被分割为多个连续的**区块**，这样来自大表 (200 GB+) 的数据就可以用增量方式导入。 - -4. `tidb-lightning` 会通过 gRPC 让 `tikv-importer` 为每一个区块准备一个“引擎文件 (engine file)”来处理键值对。`tidb-lightning` 会并发读取 SQL dump，将数据源转换成与 TiDB 相同编码的键值对，然后发送到 `tikv-importer` 里对应的引擎文件。 - -5. 当一个引擎文件数据写入完毕时，`tikv-importer` 便开始对目标 TiKV 集群数据进行分裂和调度，然后导入数据到 TiKV 集群。 - - 引擎文件包含两种：**数据引擎**与**索引引擎**，各自又对应两种键值对：行数据和次级索引。通常行数据在数据源里是完全有序的，而次级索引是无序的。因此，数据引擎文件在对应区块写入完成后会被立即上传，而所有的索引引擎文件只有在整张表所有区块编码完成后才会执行导入。 - -6. 整张表相关联的所有引擎文件完成导入后，`tidb-lightning` 会对比本地数据源及下游集群的校验和 (checksum)，确保导入的数据无损，然后让 TiDB 分析 (`ANALYZE`) 这些新增的数据，以优化日后的操作。同时，`tidb-lightning` 调整 `AUTO_INCREMENT` 值防止之后新增数据时发生冲突。 - - 表的自增 ID 是通过行数的**上界**估计值得到的，与表的数据文件总大小成正比。因此，最后的自增 ID 通常比实际行数大得多。这属于正常现象，因为在 TiDB 中自增 ID [不一定是连续分配的](/v3.0/reference/mysql-compatibility.md#auto-increment-id)。 - -7. 在所有步骤完毕后，`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode)，此后 TiDB 集群可以正常对外提供服务。 - -TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似，使用 TiDB-backend 时，`tidb-lightning` 将数据转换为 `INSERT` 语句，然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md)。 \ No newline at end of file diff --git a/v3.0/reference/tools/tidb-lightning/table-filter.md b/v3.0/reference/tools/tidb-lightning/table-filter.md deleted file mode 100644 index 19307fc6deaa..000000000000 --- a/v3.0/reference/tools/tidb-lightning/table-filter.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: TiDB Lightning 表库过滤 -summary: 使用黑白名单把一些表剔出要导入的范围。 -category: reference -aliases: ['/docs-cn/tools/lightning/filter/','/docs-cn/v3.0/reference/tools/tidb-lightning/filter/'] ---- - -# TiDB Lightning 表库过滤 - -TiDB Lightning 支持使用黑名单和白名单来过滤掉某些数据库和表。这可以用来跳过一些用作暂存、毋须迁移的表，或用来手动切分数据源，让多机同时导入。 - -这些过滤规则与 MySQL 的 `replication-rules-db`/`replication-rules-table` 类似。 - -## 过滤数据库 - -```toml -[black-white-list] -do-dbs = ["pattern1", "pattern2", "pattern3"] -ignore-dbs = ["pattern4", "pattern5"] -``` - -* 如果 `[black-white-list]` 下的 `do-dbs` 列表不为空， - * 如数据库名称匹配 `do-dbs` 列表中**任何**一项，则数据库会被导入。 - * 否则，数据库会被略过。 -* 否则，如果数据库名称匹配 `ignore-dbs` 列表中**任何**一项，数据库会被略过。 -* 如果数据库名称**同时**匹配 `do-dbs` 和 `ignore-dbs` 列表，数据库会被导入。 - -如果匹配项首字符为 `~`，它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 - -> **注意：** -> -> 无论你如何设置过滤规则，系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 - -## 过滤表 - -```toml -[[black-white-list.do-tables]] -db-name = "db-pattern-1" -tbl-name = "table-pattern-1" - -[[black-white-list.do-tables]] -db-name = "db-pattern-2" -tbl-name = "table-pattern-2" - -[[black-white-list.do-tables]] -db-name = "db-pattern-3" -tbl-name = "table-pattern-3" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-4" -tbl-name = "table-pattern-4" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-5" -tbl-name = "table-pattern-5" -``` - -* 如果 `do-tables` 列表不为空， - * 如果表的限定名称匹配 `do-tables` 列表中**任何**一对，则表会被导入。 - * 否则，表会被略过。 -* 否则，如果表的限定名称匹配 `ignore-tables` 列表中**任何**一对，表会被略过。 -* 如果表的限定名称**同时**匹配 `do-tables` 和 `ignore-tables` 列表，表会被导入。 - -> **注意：** -> -> Lightning 会先执行数据库过滤规则，之后才执行表的过滤规则。所以，如果一个数据库已被 `ignore-dbs` 略过，即使其下的表匹配 `do-tables` 也不会再被导入。 - -## 例子 - -以下例子演示过滤规则的操作原理。假设数据源包含这些表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -`admin`.`secrets` -``` - -我们使用以下设置： - -```toml -[black-white-list] -do-dbs = [ - "forum_backup_2018", # 规则 A - "~^(logs|forum)$", # 规则 B -] -ignore-dbs = [ - "~^forum_backup_", # 规则 C -] - -[[black-white-list.do-tables]] # 规则 D -db-name = "logs" -tbl-name = "~_2018$" - -[[black-white-list.ignore-tables]] # 规则 E -db-name = "~.*" -tbl-name = "~^messages.*" - -[[black-white-list.do-tables]] # 规则 F -db-name = "~^forum.*" -tbl-name = "messages" -``` - -首先进行数据库过滤： - -| 数据库 | 结果 | -|---------------------------|--------------| -| `` `logs` `` | 导入（规则 B） | -| `` `forum` `` | 导入（规则 B） | -| `` `forum_backup_2016` `` | 略过（规则 C） | -| `` `forum_backup_2017` `` | 略过（规则 C） | -| `` `forum_backup_2018` `` | 导入（规则 A）（不会考虑规则 C） | -| `` `admin` `` | 略过（`do-dbs` 不为空，且没有匹配的项目） | - -然后进行表过滤： - -| 表 | 结果 | -|--------------------------------------|--------------| -| `` `logs`.`messages_2016` `` | 略过（规则 E） | -| `` `logs`.`messages_2017` `` | 略过（规则 E） | -| `` `logs`.`messages_2018` `` | 导入（规则 D）（不会考虑规则 E） | -| `` `forum`.`users` `` | 略过（`do-tables` 不为空，且没有匹配的项目） | -| `` `forum`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `forum_backup_2016`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2017`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2018`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `admin`.`secrets` `` | 略过（数据库已被剔除） | diff --git a/v3.0/reference/tools/tidb-lightning/tidb-backend.md b/v3.0/reference/tools/tidb-lightning/tidb-backend.md deleted file mode 100644 index 8718b60962dd..000000000000 --- a/v3.0/reference/tools/tidb-lightning/tidb-backend.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: TiDB Lightning TiDB-Backend -summary: 了解 TiDB Lightning TiDB-backend。 -category: reference ---- - -# TiDB Lightning TiDB-Backend - -TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前，TiDB Lightning 支持 Importer-backend（默认）和 TiDB-backend 两种后端，两者导入数据的区别如下： - -* **Importer-backend**：`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对，由 `tikv-importer` 对写入的键值对进行排序，然后把这些键值对 Ingest 到 TiKV 节点中。 - -* **TiDB-backend**：`tidb-lightning` 先将数据编码成 `INSERT` 语句，然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 - -| 后端 | Importer-backend | TiDB-backend | -|:---|:---|:---| -| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | -| 资源使用率 | 高 | 低 | -| 导入时是否满足 ACID | 否 | 是 | -| 目标表 | 必须为空 | 可以不为空 | - -## 部署 TiDB-backend - -使用 TiDB-backend 时，你无需部署 `tikv-importer`。与[标准部署过程](/v3.0/reference/tools/tidb-lightning/deployment.md)相比，部署 TiDB-backend 时有如下不同： - -* 可以跳过所有涉及 `tikv-importer` 的步骤。 -* 必须更改相应配置申明使用的是 TiDB-backend。 - -### 硬件需求 - -使用 TiDB-backend 时， TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此，即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下： - -* 16 逻辑核 CPU -* 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 -* 千兆网卡 - -### 使用 Ansible 部署 - -1. `inventory.ini` 文件中，`[importer_server]` 部分可以留空。 - - ```ini - ... - - [importer_server] - # keep empty - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置，`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 - - ```yaml - ... - tikv_importer: - backend: "tidb" # <-- 改成 “tidb” - ... - ``` - -3. 启动、部署集群。 - -4. 为 TiDB Lightning 挂载数据源。 - -5. 启动 `tidb-lightning`。 - -### 手动部署 - -手动部署时，你无需下载和配置 `tikv-importer`。 - -在运行 `tidb-lightning` 之前，在配置文件中加上如下几行： - -```toml -[tikv-importer] -backend = "tidb" -``` - -或者在用命令行启动 `tidb-lightning` 时，传入参数 `--backend tidb`。 - -## 冲突解决 - -TiDB-backend 支持导入到已填充的表（非空表）。但是，新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为： - -```toml -[tikv-importer] -backend = "tidb" -on-duplicate = "replace" # 或者 “error”、“ignore” -``` - -| 设置 | 冲突时默认行为 | 对应 SQL 语句 | -|:---|:---|:---| -| replace | 新数据替代旧数据 | `REPLACE INTO ...` | -| ignore | 保留旧数据，忽略新数据 | `INSERT IGNORE INTO ...` | -| error | 中止导入 | `INSERT INTO ...` | - -## 从 Loader 迁移到 TiDB Lightning TiDB-backend - -TiDB Lightning TiDB-backend 可以完全取代 [Loader](/v3.0/reference/tools/loader.md)。下表说明了如何将 [Loader](/v3.0/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/v3.0/reference/tools/tidb-lightning/config.md)中： - -
- - - - - - - - - -
LoaderTiDB Lightning
- -```toml -# 日志 -log-level = "info" -log-file = "loader.log" -# Prometheus -status-addr = ":8272" -# 线程数 -pool-size = 16 -``` - - - -```toml -[lightning] -# 日志 -level = "info" -file = "tidb-lightning.log" -# Prometheus -pprof-port = 8289 -# 并发度 (最好使用默认设置) -#region-concurrency = 16 -``` - -
- -```toml -# 断点数据库名 -checkpoint-schema = "tidb_loader" -``` - - - -```toml -[checkpoint] -# 断点存储 -enable = true -schema = "tidb_lightning_checkpoint" -# 断点默认存储在本地的文件系统，这样更高效。但你也可以 -# 选择将断点存储在目标数据库中，设置如下： -# driver = "mysql" -``` - -
- -```toml -``` - - - -```toml -[tikv-importer] -# 使用 TiDB-backend -backend = "tidb" -``` - -
- -```toml -# 数据源目录 -dir = "/data/export/" -``` - - - -```toml -[mydumper] -# 数据源目录 -data-source-dir = "/data/export" -``` - -
- -```toml -[db] -# TiDB 连接参数 -host = "127.0.0.1" -port = 4000 -user = "root" -password = "" -#sql-mode = "" -``` - - - -```toml -[tidb] -# TiDB 连接参数 -host = "127.0.0.1" -port = 4000 -status-port = 10080 # <- 必须有的参数 -user = "root" -password = "" -#sql-mode = "" -``` - -
diff --git a/v3.0/reference/tools/tidb-lightning/web.md b/v3.0/reference/tools/tidb-lightning/web.md deleted file mode 100644 index 48da1e95f0ee..000000000000 --- a/v3.0/reference/tools/tidb-lightning/web.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: TiDB Lightning Web 界面 -summary: 了解 TiDB Lightning 的服务器模式——通过 Web 界面来控制 TiDB Lightning。 -category: reference ---- - -# TiDB Lightning Web 界面 - -TiDB Lightning 支持在网页上查看导入进度或执行一些简单任务管理，这就是 TiDB Lightning 的**服务器模式**。本文将介绍服务器模式下的 Web 界面和一些常见操作。 - -启用服务器模式的方式有如下几种： - -1. 在启动 `tidb-lightning` 时加上命令行参数 `--server-mode`。 - - ```sh - ./tidb-lightning --server-mode --status-addr :8289 - ``` - -2. 在配置文件中设置 `lightning.server-mode`。 - - ```toml - [lightning] - server-mode = true - status-addr = ':8289' - ``` - -TiDB Lightning 启动后，可以访问 `http://127.0.0.1:8289` 来管理程序（实际的 URL 取决于你的 `status-addr` 设置）。 - -服务器模式下，TiDB Lightning 不会立即开始运行，而是通过用户在 web 页面提交（多个）**任务**来导入数据。 - -## TiDB Lightning Web 首页 - -![TiDB Lightning Web 首页](/media/lightning-web-frontpage.png) - -标题栏上图标所对应的功能，从左到右依次为： - -| 图标 | 功能 | -|:----|:----| -| "TiDB Lightning" | 点击即返回首页 | -| ⚠ | 显示**前一个**任务的所有错误信息 | -| ⓘ | 列出当前及队列中的任务，可能会出现一个标记提示队列中任务的数量 | -| + | 提交单个任务 | -| ⏸/▶ | 暂停/继续当前操作 | -| ⟳ | 设置网页自动刷新 | - -标题栏下方的三个面板显示了不同状态下的所有表： - -* Active：当前正在导入这些表 -* Completed：这些表导入成功或失败 -* Pending：这些表还没有被处理 - -每个面板都包含用于描述表状态的卡片。 - -## 提交任务 - -点击标题栏的 **+** 图标提交任务。 - -![提交任务对话框](/media/lightning-web-submit.png) - -任务 (task) 为 TOML 格式的文件，具体参考 [TiDB Lightning 任务配置](/v3.0/reference/tools/tidb-lightning/config.md#tidb-lightning-任务配置参数)。你也可以点击 **UPLOAD** 上传一个本地的 TOML 文件。 - -点击 **SUBMIT** 运行任务。如果当前有任务正在运行，新增任务会加入队列并在当前任务结束后执行。 - -## 查看导入进度 - -点击首页表格卡片上的 **>** 图标，查看表格导入的详细进度。 - -![表格导入进度](/media/lightning-web-table.png) - -该页显示每张表的引擎文件的导入过程。 - -点击标题栏上的 **TiDB Lightning** 返回首页。 - -## 管理任务 - -单击标题栏上的 **ⓘ** 图标来管理当前及队列中的任务。 - -![任务管理页面](/media/lightning-web-queue.png) - -每个任务都是依据提交时间来标记。点击该任务将显示 JSON 格式的配置文件。 - -点击任务上的 **⋮** 可以对该任务进行管理。你可以立即停止任务，或重新排序队列中的任务。 diff --git a/v3.0/reference/tools/tikv-control.md b/v3.0/reference/tools/tikv-control.md deleted file mode 100644 index 77e63b91387a..000000000000 --- a/v3.0/reference/tools/tikv-control.md +++ /dev/null @@ -1,414 +0,0 @@ ---- -title: TiKV Control 使用说明 -category: reference ---- - -# TiKV Control 使用说明 - -TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管理 TiKV 集群。 - -编译 TiKV 的同时也会编译 tikv-ctl 命令。如果通过 Ansible 部署集群，则对应的 `tidb-ansible/resources/bin` 目录下会存在 `tikv-ctl` 二进制文件。如果使用二进制文件部署集群，bin 目录下会包含 `tikv-ctl` 文件及 `tidb-server`、`pd-server`、以及 `tikv-server` 等其他文件。 - -## 通用参数 - -tikv-ctl 提供以下两种运行模式： - -- **远程模式**。通过 `--host` 选项接受 TiKV 的服务地址作为参数。在此模式下，如果 TiKV 启用了 SSL，则 tikv-ctl 也需要指定相关的证书文件，例如： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --ca-path ca.pem --cert-path client.pem --key-path client-key.pem --host 127.0.0.1:20160 - ``` - - 某些情况下，tikv-ctl 与 PD 进行通信，而不与 TiKV 通信。此时你需要使用 `--pd` 选项而非 `--host` 选项，例如： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --pd 127.0.0.1:2379 compact-cluster - ``` - - ``` - store:"127.0.0.1:20160" compact db:KV cf:default range:([], []) success! - ``` - -- **本地模式**。通过 `--db` 选项来指定本地 TiKV 数据的目录路径。在此模式下，需要停止正在运行的 TiKV 实例。 - -以下如无特殊说明，所有命令都同时支持这两种模式。 - -除此之外，tikv-ctl 还有两个简单的命令 `--to-hex` 和 `--to-escaped`，用于对 key 的形式作简单的变换。一般使用 `escaped` 形式，示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --to-escaped 0xaaff -``` - -``` -\252\377 -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --to-hex "\252\377" -``` - -``` -AAFF -``` - -> **注意：** -> -> 在命令行上指定 `escaped` 形式的 key 时，需要用双引号引起来，否则 bash 会将反斜杠吃掉，导致结果错误。 - -## 各项子命令及部分参数、选项 - -下面逐一对 tikv-ctl 支持的子命令进行举例说明。有的子命令支持很多可选参数，要查看全部细节，可运行 `tikv-ctl --help `。 - -### 查看 Raft 状态机的信息 - -`raft` 子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 **RegionLocalState**、**RaftLocalState** 和 **RegionApplyState** 三个结构体，及某一条 log 对应的 Entries。 - -您可以使用 `region` 和 `log` 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。它们的用法及输出内容如下所示： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 raft region -r 2 -``` - -``` -region id: 2 -region state key: \001\003\000\000\000\000\000\000\000\002\001 -region state: Some(region {id: 2 region_epoch {conf_ver: 3 version: 1} peers {id: 3 store_id: 1} peers {id: 5 store_id: 4} peers {id: 7 store_id: 6}}) -raft state key: \001\002\000\000\000\000\000\000\000\002\002 -raft state: Some(hard_state {term: 307 vote: 5 commit: 314617} last_index: 314617) -apply state key: \001\002\000\000\000\000\000\000\000\002\003 -apply state: Some(applied_index: 314617 truncated_state {index: 313474 term: 151}) -``` - -### 查看 Region 的大小 - -`size` 命令可以查看 Region 的大小： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db size -r 2 -``` - -``` -region id: 2 -cf default region size: 799.703 MB -cf write region size: 41.250 MB -cf lock region size: 27616 -``` - -### 扫描查看给定范围的 MVCC - -`scan` 命令的 `--from` 和 `--to` 参数接受两个 escaped 形式的 raw key，并用 `--show-cf` 参数指定只需要查看哪些列族。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db scan --from 'zm' --limit 2 --show-cf lock,default,write -``` - -``` -key: zmBootstr\377a\377pKey\000\000\377\000\000\373\000\000\000\000\000\377\000\000s\000\000\000\000\000\372 - write cf value: start_ts: 399650102814441473 commit_ts: 399650102814441475 short_value: "20" -key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371 - write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002" - write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001" -``` - -### 查看给定 key 的 MVCC - -与上个命令类似，`mvcc` 命令可以查看给定 key 的 MVCC： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db mvcc -k "zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371" --show-cf=lock,write,default -``` - -``` -key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371 - write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002" - write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001" -``` - -> **注意：** -> -> 该命令中，key 同样需要是 escaped 形式的 raw key。 - -### 打印某个 key 的值 - -打印某个 key 的值需要用到 `print` 命令。示例从略。 - -### 打印 Region 的 properties 信息 - -为了记录 Region 的状态信息，TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 `region-properties` 运行 tikv-ctl 来查看这些 properties 信息。例如： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host localhost:20160 region-properties -r 2 -``` - -``` -num_files: 0 -num_entries: 0 -num_deletes: 0 -mvcc.min_ts: 18446744073709551615 -mvcc.max_ts: 0 -mvcc.num_rows: 0 -mvcc.num_puts: 0 -mvcc.num_versions: 0 -mvcc.max_row_versions: 0 -middle_key_by_approximate_size: -``` - -这些 properties 信息可以用于检查某个 Region 是否健康或者修复不健康的 Region。例如，使用 `middle_key_approximate_size` 可以手动分裂 Region。 - -### 手动 compact 单个 TiKV 的数据 - -`compact` 命令可以对单个 TiKV 进行手动 compact。如果指定 `--from` 和 `--to` 选项，那么它们的参数也是 escaped raw key 形式的。`--host` 参数可以指定要 compact 的 TiKV，`-d` 参数可以指定要 compact 的 RocksDB，有 `kv` 和 `raft` 参数值可以选。`--threads` 参数可以指定 compact 的并发数，默认值是 8。一般来说，并发数越大， compact 的速度越快，但是也会对服务造成影响，所以需要根据情况选择合适的并发数。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 compact -d kv -``` - -``` -success! -``` - -### 手动 compact 整个 TiKV 集群的数据 - -`compact-cluster` 命令可以对整个 TiKV 集群进行手动 compact。该命令参数的含义和使用与 `compact` 命令一样。 - -### 设置一个 Region 为 tombstone - -`tombstone` 命令常用于没有开启 sync-log，因为机器掉电导致 Raft 状态机丢失部分写入的情况。它可以在一个 TiKV 实例上将一些 Region 设置为 Tombstone 状态，从而在重启时跳过这些 Region。这些 Region 应该在其他 TiKV 上有足够多的健康的副本以便能够继续通过 Raft 机制进行读写。 - -{{< copyable "" >}} - -```shell -pd-ctl>> operator add remove-peer -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r -``` - -``` -success! -``` - -> **注意：** -> -> - **该命令只支持本地模式** -> - `-p` 选项的参数指定 PD 的 endpoints，无需 `http` 前缀。指定 PD 的 endpoints 是为了询问 PD 是否可以安全切换至 Tombstone 状态。因此，在将 PD 置为 Tombstone 之前往往还需要在 `pd-ctl` 中把该 Region 在机器上的对应 Peer 拿掉。 - -### 向 TiKV 发出 consistency-check 请求 - -`consistency-check` 命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败，TiKV 自身会 panic。如果 `--host` 指定的 TiKV 不是这个 Region 的 Leader，则会报告错误。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2 -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:21061 consistency-check -r 2 -``` - -``` -DebugClient::check_region_consistency: RpcFailure(RpcStatus { status: Unknown, details: Some("StringError(\"Leader is on store 1\")") }) -``` - -> **注意：** -> -> - **该命令只支持远程模式**。 -> - 即使该命令返回了成功信息，也需要检查是否有 TiKV panic 了。因为该命令只是向 Leader 请求进行一致性检查，但整个检查流程是否成功并不能在客户端知道。 - -### Dump snapshot 元文件 - -这条子命令可以用于解析指定路径下的 Snapshot 元文件并打印结果。 - -### 打印 Raft 状态机出错的 Region - -前面 `tombstone` 命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态，避免 TiKV 启动时对它们进行检查。在运行 `tombstone` 命令之前，可使用 `bad-regions` 命令找到出错的 Region，以便将多个工具组合起来进行自动化的处理。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db bad-regions -``` - -``` -all regions are healthy -``` - -命令执行成功后会打印以上信息，否则会打印出有错误的 Region 列表。目前可以检出的错误包括 `last index`、`commit index` 和 `apply index` 之间的不匹配，以及 Raft log 的丢失。其他一些情况，比如 Snapshot 文件损坏等仍然需要后续的支持。 - -### 查看 Region 属性 - -本地查看部署在 `/path/to/tikv` 的 tikv 上面 Region 2 的 properties 信息： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/data/db region-properties -r 2 -``` - -在线查看运行在 `127.0.0.1:20160` 的 tikv 上面 Region 2 的 properties 信息： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 region-properties -r 2 -``` - -### 动态修改 TiKV 的 RocksDB 相关配置 - -使用 `modify-tikv-config` 命令可以动态修改配置参数，暂时仅支持对于 RocksDB 相关参数的动态更改。 - -- `-m` 用于指定要修改的模块，有 `storage`、`kvdb` 和 `raftdb` 三个值可以选择。 -- `-n` 用于指定配置名。配置名可以参考 [TiKV 配置模版](https://github.com/pingcap/tikv/blob/master/etc/config-template.toml#L213-L500)中 `[storage]`、`[rocksdb]` 和 `[raftdb]` 下的参数，分别对应 `storage`、`kvdb` 和 `raftdb`。同时，还可以通过 `default|write|lock + . + 参数名` 的形式来指定的不同 CF 的配置。对于 `kvdb` 有 `default`、`write` 和 `lock` 可以选择，对于 `raftdb` 仅有 `default` 可以选择。 -- `-v` 用于指定配置值。 - -设置 `shared block cache` 的大小： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m storage -n block_cache.capacity -v 10GB -``` - -``` -success! -``` - -当禁用 `shared block cache` 时，为 `write` CF 设置 `block cache size`： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m kvdb -n write.block_cache_size -v 256MB -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m kvdb -n max_background_jobs -v 8 -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m raftdb -n default.disable_auto_compactions -v true -``` - -``` -success! -``` - -### 强制 Region 从多副本失败状态恢复服务 - -`unsafe-recover remove-fail-stores` 命令可以将故障机器从指定 Region 的 peer 列表中移除。运行命令之前，需要目标 TiKV 先停掉服务以便释放文件锁。 - -`-s` 选项接受多个以逗号分隔的 `store_id`，并使用 `-r` 参数来指定包含的 Region。如果要对某一个 store 上的全部 Region 都执行这个操作，可简单指定 `--all-regions`。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 3 -r 1001,1002 -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 4,5 --all-regions -``` - -之后启动 TiKV，这些 Region 便可以使用剩下的健康副本继续提供服务了。此命令常用于多个 TiKV store 损坏或被删除的情况。 - -> **注意：** -> -> - 该命令只支持本地模式。在运行成功后，会打印 `success!`。 -> - 一般来说，您需要为指定 Region 的 peers 所在的每个 store 运行此命令。 -> - 如果使用 `--all-regions`，通常需要在集群剩余所有健康的 store 上执行此命令。 - -### 恢复损坏的 MVCC 数据 - -`recover-mvcc` 命令用于 MVCC 数据损坏导致 TiKV 无法正常运行的情况。为了从不同种类的不一致情况中恢复，该命令会交叉检查 3 个 CF ("default", "write", "lock")。 - -`-r` 选项可以通过 `region_id` 指定包含的 Region，`-p` 选项可以指定 PD 的 endpoints。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db recover-mvcc -r 1001,1002 -p 127.0.0.1:2379 -``` - -``` -success! -``` - -> **注意：** -> -> - 该命令只支持本地模式。在运行成功后，会打印 `success!`。 -> - `-p` 选项指定 PD 的 endpoint，不使用 `http` 前缀，用于查询指定的 `region_id` 是否有效。 -> - 对于指定 Region 的 peers 所在的每个 store，均须执行该命令。 - -### Ldb 命令 - -ldb 命令行工具提供多种数据访问以及数据库管理命令。下方列出了一些示例用法。详细信息请在运行 `tikv-ctl ldb` 命令时查看帮助消息或查阅 RocksDB 文档。 - -数据访问序列示例如下。 - -用 HEX 格式 dump 现有 RocksDB 数据: - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl ldb --hex --db=/tmp/db dump -``` - -dump 现有 RocksDB 的声明： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl ldb --hex manifest_dump --path=/tmp/db/MANIFEST-000001 -``` - -您可以通过 `--column_family=` 指定查询的目标列族。 - -通过 `--try_load_options` 命令加载数据库选项文件以打开数据库。在数据库运行时，建议您保持该命令为开启的状态。如果您使用默认配置打开数据库，LSM-tree 存储组织可能会出现混乱，且无法自动恢复。 diff --git a/v3.0/reference/tools/user-guide.md b/v3.0/reference/tools/user-guide.md deleted file mode 100644 index 4830c3e56fee..000000000000 --- a/v3.0/reference/tools/user-guide.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: TiDB 生态工具使用指南 -category: reference -aliases: ['/docs-cn/v3.0/how-to/migrate/from-mysql/', '/docs-cn/v3.0/how-to/migrate/incrementally-from-mysql/', '/docs-cn/v3.0/how-to/migrate/overview/', '/docs-cn/v3.0/reference/tools/use-guide/'] ---- - -# TiDB 生态工具使用指南 - -目前 TiDB 生态工具较多，有些工具之间有功能重叠，也有些属于版本迭代关系。本文档将对各个工具进行介绍，说明各个工具之间的关系，并且说明各个版本、场景下应该使用哪些工具。 - -## TiDB 生态工具概览 - -TiDB 生态工具可以分为几种： - -- 数据导入类，包括全量导入工具、备份和恢复工具、增量导入工具等 -- 数据导出类，包括全量导出工具、增量导出工具等 - -下面将分别介绍这两类工具。 - -### 数据导入类 - -#### 全量导入工具 Loader（停止维护，不推荐使用） - -[Loader](/v3.0/reference/tools/loader.md) 是一款轻量级的全量数据导入工具，数据以 SQL 的形式导入到 TiDB 中。目前这个工具正在逐步被 [TiDB Lightning](#全量导入工具-tidb-lightning) 替换掉，参见 [TiDB Lightning TiDB-backend 文档](/v3.0/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。 - -以下是 Loader 的一些基本信息： - -- Loader 的输入：Mydumper 输出的文件 -- Loader 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：[备份与恢复](/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md) - -#### 全量导入工具 TiDB Lightning - -[TiDB Lightning](/v3.0/reference/tools/tidb-lightning/overview.md) 是将全量数据快速导入到一个新的 TiDB 集群的工具。 - -注意用 TiDB Lightning 导入数据到 TiDB 的时候，有两种模式： - -- 默认模式：`tikv-importer` 为后端，这种模式下导入数据过程中集群无法提供正常的服务，用于导入大量的数据（TB 级别）。 -- 第二种模式：`TiDB` 为后端（相当于 Loader 的功能），相对默认模式导入速度较慢，但是可以在线导入。 - -以下是 TiDB Lightning 的一些基本信息： - -- Lightning 的输入 - - Mydumper 输出文件 - - CSV 格式文件 -- 适用 TiDB 版本：v2.1 及以上 -- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](/v3.0/tidb-in-kubernetes/maintain/lightning.md) - -#### 增量导入工具 Syncer（已停止维护，不推荐使用） - -[Syncer](/v3.0/reference/tools/syncer.md) 是将 MySQL/MariaDB 增量 binlog 数据实时复制导入到 TiDB 的工具。目前推荐使用 [TiDB Data Migration](#增量导入工具-tidb-data-migration) 替换该工具。 - -以下是 Syncer 的一些基本信息： - -- Syncer 的输入：MySQL/MariaDB 的 binlog -- Syncer 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：不支持 - -#### 增量导入工具 TiDB Data Migration - -[TiDB Data Migration (DM)](/v3.0/reference/tools/data-migration/overview.md) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的同步。 - -以下是 DM 的一些基本信息： - -- DM 的输入：MySQL/MariaDB 的全量数据以及 binlog -- DM 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：开发中 - -### 数据导出类 - -#### 全量导出工具 Mydumper - -[Mydumper](/v3.0/reference/tools/mydumper.md) 用于对 MySQL/TiDB 进行全量逻辑备份。 - -以下是 Mydumper 的一些基本信息： - -- Mydumper 的输入：MySQL/TiDB 集群 -- Mydumper 的输出：SQL 文件 -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：[备份与恢复](/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md) - -#### 增量导出工具 TiDB Binlog - -[TiDB Binlog](/v3.0/reference/tidb-binlog/overview.md) 是收集 TiDB 的 binlog，并提供准实时同步和备份的工具。 - -以下是 TiDB Binlog 的一些基本信息： - -- TiDB Binlog 的输入：TiDB 集群 -- TiDB Binlog 的输出：MySQL、TiDB、Kafka 或者增量备份文件 -- 适用 TiDB 版本：v2.1 及以上 -- Kubernetes 支持：[TiDB Binlog 运维文档](/v3.0/tidb-in-kubernetes/maintain/tidb-binlog.md)，[Kubernetes 上的 TiDB Binlog Drainer 配置](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - -## 工具演进路线 - -下面简单的介绍一下 TiDB 生态工具集的演进，方便大家了解工具之间的关系。 - -### MySQL 数据迁移 - -- Mydumper、Loader、Syncer -> DM： - - 使用 Mydumper、Loader、Syncer 将 MySQL 数据迁移到 TiDB，迁移过程比较繁琐。DM 提供了一体化的数据迁移方案，提高了易用性，而且 DM 还支持分库分表的合并。 - -- Loader -> TiDB Lightning： - - TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/v3.0/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，由 TiDB Lightning 统一提供全量数据恢复功能。 - -## 数据迁移解决方案 - -针对 TiDB 的 2.1，3.0 以及 3.1 版本，下面给出典型业务场景下的数据迁移方案。 - -### TiDB 3.0 全链路数据迁移方案 - -#### MySQL 数据迁移到 TiDB - -如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： - -1. 使用 Mydumper 导出 MySQL 全量数据 -2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 -3. 使用 DM 同步 MySQL 增量数据到 TiDB - -如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 - -#### TiDB 集群数据的同步 - -使用 TiDB Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 - -#### TiDB 集群数据的全量备份及恢复 - -推荐步骤： - -1. 使用 Mydumper 进行全量数据的备份 -2. 使用 TiDB Lightning 将全量数据恢复到 TiDB/MySQL diff --git a/v3.0/reference/transactions/overview.md b/v3.0/reference/transactions/overview.md deleted file mode 100644 index d1020e90bb00..000000000000 --- a/v3.0/reference/transactions/overview.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB 事务概览 -summary: 了解 TiDB 中的事务。 -category: reference ---- - -# TiDB 事务概览 - -TiDB 支持完整的分布式事务，提供[乐观事务](/v3.0/reference/transactions/transaction-optimistic.md)与[悲观事务](/v3.0/reference/transactions/transaction-pessimistic.md)（TiDB 3.0 中引入）两种事务模型。本文主要介绍涉及到事务的语句、显式/隐式事务、事务的隔离级别和惰性检查，以及事务大小的限制。 - -常用的变量包括 [`autocommit`](#自动提交)、[`tidb_disable_txn_auto_retry`](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_disable_txn_auto_retry) 以及 [`tidb_retry_limit`](/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_retry_limit)。 - -## 常用事务语句 - -### `BEGIN` 和 `START TRANSACTION` - -语法： - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION WITH CONSISTENT SNAPSHOT; -``` - -以上三条语句都用于开启事务，效果相同。执行开启事务语句可以显式地开启一个新的事务。如果执行以上语句时，当前 Session 正处于一个事务的中间过程，那么系统会先自动提交当前事务，再开启一个新的事务。 - -### `COMMIT` - -语法： - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -该语句用于提交当前的事务，包括从 `[BEGIN|START TRANSACTION]` 到 `COMMIT` 之间的所有修改。 - -### `ROLLBACK` - -语法： - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -该语句用于回滚当前事务，撤销从 `[BEGIN|START TRANSACTION]` 到 `ROLLBACK` 之间的所有修改。 - -## 自动提交 - -语法： - -{{< copyable "sql" >}} - -```sql -SET autocommit = {0 | 1} -``` - -当 `autocommit = 1` 时（默认），当前的 Session 为自动提交状态，即每条语句运行后，TiDB 会自动将修改提交到数据库中。设置 `autocommit = 0` 时更改当前 Session 更改为非自动提交状态，通过执行 `COMMIT` 语句来手动提交事务。 - -> **注意：** -> -> 某些语句执行后会导致隐式提交。例如，执行 `[BEGIN|START TRANCATION]` 语句时，TiDB 会试图提交上一个事务，并开启一个新的事务。详情参见 [implicit commit](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html)。 - -另外，`autocommit` 也是一个系统变量，你可以通过变量赋值语句修改当前 Session 或 Global 的值。 - -{{< copyable "sql" >}} - -```sql -SET @@SESSION.autocommit = {0 | 1}; -``` - -{{< copyable "sql" >}} - -```sql -SET @@GLOBAL.autocommit = {0 | 1}; -``` - -## 显式事务和隐式事务 - -TiDB 可以显式地使用事务（通过 `[BEGIN|START TRANSACTION]`/`COMMIT` 语句定义事务的开始和结束) 或者隐式地使用事务 (`SET autocommit = 1`)。 - -在自动提交状态下，使用 `[BEGIN|START TRANSACTION]` 语句会显式地开启一个事务，同时也会禁用自动提交，使隐式事务变成显式事务。直到执行 `COMMIT` 或 `ROLLBACK` 语句时才会恢复到此前默认的自动提交状态。 - -对于 DDL 语句，会自动提交并且不能回滚。如果运行 DDL 的时候，正在一个事务的中间过程中，会先自动提交当前事务，再执行 DDL。 - -## 事务隔离级别 - -TiDB **只支持** `SNAPSHOT ISOLATION`，可以通过下面的语句将当前 Session 的隔离级别设置为 `READ COMMITTED`，这只是语法上的兼容，事务依旧是以 `SNAPSHOT ISOLATION` 来执行。 - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -## 惰性检查 - -TiDB 中，对于普通的 `INSERT` 语句写入的值，会进行惰性检查。惰性检查的含义是，不在 `INSERT` 语句执行时进行唯一约束的检查，而在事务提交时进行唯一约束的检查。 - -举例： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE T (I INT KEY); -INSERT INTO T VALUES (1); -BEGIN; -INSERT INTO T VALUES (1); -- MySQL 返回错误；TiDB 返回成功 -INSERT INTO T VALUES (2); -COMMIT; -- MySQL 提交成功；TiDB 返回错误，事务回滚 -SELECT * FROM T; -- MySQL 返回 1 2；TiDB 返回 1 -``` - -惰性检查的意义在于，如果对事务中每个 `INSERT` 语句都立刻进行唯一性约束检查，将造成很高的网络开销。而在提交时进行一次批量检查，将会大幅提升性能。 - -> **注意：** -> -> 本优化仅对普通的 `INSERT` 语句生效，对 `INSERT IGNORE` 和 `INSERT ON DUPLICATE KEY UPDATE` 不会生效。 - -## 语句回滚 - -TiDB 支持语句执行的原子性回滚。在事务内部执行一个语句，遇到错误时，该语句整体不会生效。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -commit; -``` - -上面的例子里面，第二条语句执行失败，但第一和第三条语句仍然能正常提交。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -rollback; -``` - -以上例子中，第二条语句执行失败。由于调用了 `ROLLBACK`，因此事务不会将任何数据写入数据库。 - -## 事务大小 - -对于 TiDB 事务而言，事务太大或太小，都会影响事务的执行效率。 - -### 小事务 - -以如下 query 为例，当 `autocommit = 1` 时，下面三条语句各为一个事务： - -{{< copyable "sql" >}} - -```sql -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -``` - -此时每一条语句都需要经过两阶段提交，频繁的网络交互致使延迟率高。为提升事务执行效率，可以选择使用显式事务，即在一个事务内执行三条语句。 - -优化后版本： - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -COMMIT; -``` - -同理，执行 `INSERT` 语句时，建议使用显式事务。 - -> **注意：** -> -> 由于 TiDB 中的资源是分布式的，TiDB 中单线程 workload 可能不会很好地利用分布式资源，因此性能相比于单实例部署的 MySQL 较低。这与 TiDB 中的事务延迟较高的情況类似。 - -### 大事务 - -由于 TiDB 两阶段提交的要求，修改数据的单个事务过大时会存在以下问题： - -* 客户端在提交之前，数据都写在内存中，而数据量过多时易导致 OOM (Out of Memory) 错误。 -* 在第一阶段写入数据耗时增加，与其他事务出现写冲突的概率会指数级增长。 -* 最终导致事务完成提交的耗时增加。 - -因此，TiDB 对事务做了一些限制： - -* 单个事务包含的 SQL 语句不超过 5000 条（默认） -* 每个键值对不超过 6 MB -* 键值对的总数不超过 300000 -* 键值对的总大小不超过 100 MB - -为了使性能达到最优，建议每 100～500 行写入一个事务。 \ No newline at end of file diff --git a/v3.0/reference/transactions/transaction-isolation.md b/v3.0/reference/transactions/transaction-isolation.md deleted file mode 100644 index e2c4c2823eb6..000000000000 --- a/v3.0/reference/transactions/transaction-isolation.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 事务隔离级别 -summary: 了解 TiDB 事务的隔离级别。 -category: reference ---- - -# TiDB 事务隔离级别 - -事务隔离级别是数据库事务处理的基础，[ACID](/v3.0/glossary.md#acid) 中的 “I”，即 Isolation，指的就是事务的隔离性。 - -SQL-92 标准定义了 4 种隔离级别：读未提交 (READ UNCOMMITTED)、读已提交 (READ COMMITTED)、可重复读 (REPEATABLE READ)、串行化 (SERIALIZABLE)。详见下表： - -| Isolation Level | Dirty Write | Dirty Read | Fuzzy Read | Phantom | -| ---------------- | ------------ | ------------ | ------------ | ------------ | -| READ UNCOMMITTED | Not Possible | Possible | Possible | Possible | -| READ COMMITTED | Not Possible | Not possible | Possible | Possible | -| REPEATABLE READ | Not Possible | Not possible | Not possible | Possible | -| SERIALIZABLE | Not Possible | Not possible | Not possible | Not possible | - -TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](#与-ansi-可重复读隔离级别的区别)和 [MySQL 可重复读隔离级别](#与-mysql-可重复读隔离级别的区别)。 - -> **注意：** -> -> 在 TiDB v3.0 中，事务的自动重试功能默认为禁用状态。关于该项功能对隔离级别的影响以及如何开启该项功能，请参考[事务重试](/v3.0/reference/transactions/transaction-optimistic.md#重试机制)。 - -## 可重复读 - -当事务隔离级别为可重复读时，只能读到该事务启动时已经提交的其他事务修改的数据，未提交的数据或在事务启动后其他事务提交的数据是不可见的。对于本事务而言，事务语句可以看到之前的语句做出的修改。 - -对于运行于不同节点的事务而言，不同事务启动和提交的顺序取决于从 PD 获取时间戳的顺序。 - -处于可重复读隔离级别的事务不能并发的更新同一行，当时事务提交时发现该行在该事务启动后，已经被另一个已提交的事务更新过，那么该事务会回滚并启动自动重试。示例如下： - -```sql -create table t1(id int); -insert into t1 values(0); - -start transaction; | start transaction; -select * from t1; | select * from t1; -update t1 set id=id+1; | update t1 set id=id+1; -commit; | - | commit; -- 事务提交失败，回滚 -``` - -### 与 ANSI 可重复读隔离级别的区别 - -尽管名称是可重复读隔离级别，但是 TiDB 中可重复读隔离级别和 ANSI 可重复隔离级别是不同的。按照 [A Critique of ANSI SQL Isolation Levels](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf) 论文中的标准，TiDB 实现的是论文中的快照隔离级别。该隔离级别不会出现狭义上的幻读 (A3)，但不会阻止广义上的幻读 (P3)，同时，SI 还会出现写偏斜，而 ANSI 可重复读隔离级别不会出现写偏斜，会出现幻读。 - -### 与 MySQL 可重复读隔离级别的区别 - -MySQL 可重复读隔离级别在更新时并不检验当前版本是否可见，也就是说，即使该行在事务启动后被更新过，同样可以继续更新。这种情况在 TiDB 会导致事务回滚，导致事务最终失败，而 MySQL 是可以更新成功的。MySQL 的可重复读隔离级别并非快照隔离级别，MySQL 可重复读隔离级别的一致性要弱于快照隔离级别，也弱于 TiDB 的可重复读隔离级别。 - -## 更多阅读 - -- [TiKV 的 MVCC (Multi-Version Concurrency Control) 机制](https://pingcap.com/blog-cn/mvcc-in-tikv/) \ No newline at end of file diff --git a/v3.0/reference/transactions/transaction-optimistic.md b/v3.0/reference/transactions/transaction-optimistic.md deleted file mode 100644 index b1fe521b673a..000000000000 --- a/v3.0/reference/transactions/transaction-optimistic.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: TiDB 乐观事务模型 -summary: 了解 TiDB 的乐观事务模型。 -category: reference -aliases: ['/docs-cn/v3.0/reference/transactions/transaction-model/'] ---- - -# TiDB 乐观事务模型 - -本文介绍 TiDB 乐观事务的原理，以及相关特性。本文假定你对 [TiDB 的整体架构](/v3.0/architecture.md#tidb-整体架构)、[Percolator](https://www.usenix.org/legacy/event/osdi10/tech/full_papers/Peng.pdf) 事务模型以及事务的 [ACID 特性](/v3.0/glossary.md#acid)都有一定了解。 - -TiDB 默认使用乐观事务模型，不会出现读写冲突，所有的读操作都不会被写操作阻塞。对于写写冲突，只有在客户端执行 `COMMIT` 时，才会触发两阶段提交并检测是否存在写写冲突。 - -> **注意：** -> -> 自 v3.0.8 开始，TiDB 默认使用[悲观事务模型](/v3.0/reference/transactions/transaction-pessimistic.md)。但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 - -## 乐观事务原理 - -TiDB 中事务使用两阶段提交，流程如下： - -![TiDB 中的两阶段提交](/media/2pc-in-tidb.png) - -1. 客户端开始一个事务。 - - TiDB 从 PD 获取一个全局唯一递增的版本号作为当前事务的开始版本号，这里定义为该事务的 `start_ts` 版本。 - -2. 客户端发起读请求。 - - 1. TiDB 从 PD 获取数据路由信息，即数据具体存在哪个 TiKV 节点上。 - 2. TiDB 从 TiKV 获取 `start_ts` 版本下对应的数据信息。 - -3. 客户端发起写请求。 - - TiDB 校验写入数据是否符合一致性约束（如数据类型是否正确、是否符合唯一索引约束等）。**校验通过的数据将存放在内存里。** - -4. 客户端发起 commit。 - -5. TiDB 开始两阶段提交，保证分布式事务的原子性，让数据真正落盘。 - - 1. TiDB 从当前要写入的数据中选择一个 Key 作为当前事务的 Primary Key。 - 2. TiDB 从 PD 获取所有数据的写入路由信息，并将所有的 Key 按照所有的路由进行分类。 - 3. TiDB 并发地向所有涉及的 TiKV 发起 prewrite 请求。TiKV 收到 prewrite 数据后，检查数据版本信息是否存在冲突或已过期。符合条件的数据会被加锁。 - 4. TiDB 收到所有 prewrite 响应且所有 prewrite 都成功。 - 5. TiDB 向 PD 获取第二个全局唯一递增版本号，定义为本次事务的 `commit_ts`。 - 6. TiDB 向 Primary Key 所在 TiKV 发起第二阶段提交。TiKV 收到 commit 操作后，检查数据合法性，清理 prewrite 阶段留下的锁。 - 7. TiDB 收到两阶段提交成功的信息。 - -6. TiDB 向客户端返回事务提交成功的信息。 - -7. TiDB 异步清理本次事务遗留的锁信息。 - -## 优缺点分析 - -通过分析 TiDB 中事务的处理流程，可以发现 TiDB 事务有如下优点： - -* 实现原理简单，易于理解。 -* 基于单实例事务实现了跨节点事务。 -* 锁管理实现了去中心化。 - -但 TiDB 事务也存在以下缺点： - -* 两阶段提交使网络交互增多。 -* 需要一个中心化的版本管理服务。 -* 事务数据量过大时易导致内存暴涨。 - -实际应用中，你可以[根据事务的大小进行针对性处理](/v3.0/reference/transactions/overview.md#事务大小)，以提高事务的执行效率。 - -## 事务的重试 - -使用乐观事务模型时，在高冲突率的场景中，事务很容易提交失败。而 MySQL 内部使用的是悲观事务模型，在执行 SQL 语句的过程中进行冲突检测，所以提交时很难出现异常。为了兼容 MySQL 的悲观事务行为，TiDB 提供了重试机制。 - -### 重试机制 - -当事务提交后，如果发现冲突，TiDB 内部重新执行包含写操作的 SQL 语句。你可以通过设置 `tidb_disable_txn_auto_retry = off` 开启自动重试，并通过 `tidb_retry_limit` 设置重试次数： - -```sql -# 设置是否禁用自动重试，默认为 “on”，即不重试。 -tidb_disable_txn_auto_retry = off -# 控制重试次数，默认为 “10”。只有自动重试启用时该参数才会生效。 -# 当 “tidb_retry_limit= 0” 时，也会禁用自动重试。 -tidb_retry_limit = 10 -``` - -你也可以修改当前 Session 或 Global 的值： - -- Session 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@tidb_retry_limit = 10; - ``` - -- Global 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_retry_limit = 10; - ``` - -> **注意：** -> -> `tidb_retry_limit` 变量决定了事务重试的最大次数。当它被设置为 0 时，所有事务都不会自动重试，包括自动提交的单语句隐式事务。这是彻底禁用 TiDB 中自动重试机制的方法。禁用自动重试后，所有冲突的事务都会以最快的方式上报失败信息 (`try again later`) 给应用层。 - -### 重试的局限性 - -TiDB 默认不进行事务重试，因为重试事务可能会导致更新丢失，从而破坏[可重复读的隔离级别](/v3.0/reference/transactions/transaction-isolation.md)。 - -事务重试的局限性与其原理有关。事务重试可概括为以下三个步骤： - -1. 重新获取 `start_ts`。 -2. 重新执行包含写操作的 SQL 语句。 -3. 再次进行两阶段提交。 - -第二步中，重试时仅重新执行包含写操作的 SQL 语句，并不涉及读操作的 SQL 语句。但是当前事务中读到数据的时间与事务真正开始的时间发生了变化，写入的版本变成了重试时获取的 `start_ts` 而非事务一开始时获取的 `start_ts`。因此，当事务中存在依赖查询结果来更新的语句时，重试将无法保证事务原本可重复读的隔离级别，最终可能导致结果与预期出现不一致。 - -如果业务可以容忍事务重试导致的异常，或并不关注事务是否以可重复读的隔离级别来执行，则可以开启自动重试。 - -## 冲突检测 - -乐观事务下，检测底层数据是否存在写写冲突是一个很重要的操作。具体而言，TiKV 在 prewrite 阶段就需要读取数据进行检测。为了优化这一块性能，TiDB 集群会在内存里面进行一次冲突预检测。 - -作为一个分布式系统，TiDB 在内存中的冲突检测主要在两个模块进行： - -- TiDB 层。如果发现 TiDB 实例本身就存在写写冲突，那么第一个写入发出后，后面的写入已经清楚地知道自己冲突了，无需再往下层 TiKV 发送请求去检测冲突。 -- TiKV 层。主要发生在 prewrite 阶段。因为 TiDB 集群是一个分布式系统，TiDB 实例本身无状态，实例之间无法感知到彼此的存在，也就无法确认自己的写入与别的 TiDB 实例是否存在冲突，所以会在 TiKV 这一层检测具体的数据是否有冲突。 - -其中 TiDB 层的冲突检测可以根据场景需要选择打开或关闭，具体配置项如下： - -```toml -# 事务内存锁相关配置，当本地事务冲突比较多时建议开启。 -[txn-local-latches] -# 是否开启内存锁，默认为 false，即不开启。 -enabled = false -# Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。 -# 每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据）， -# 设置过小会导致变慢，性能下降。（默认为 2048000） -capacity = 2048000 -``` - -配置项 `capacity` 主要影响到冲突判断的正确性。在实现冲突检测时，不可能把所有的 Key 都存到内存里，所以真正存下来的是每个 Key 的 Hash 值。有 Hash 算法就有碰撞也就是误判的概率，这里可以通过配置 `capacity` 来控制 Hash 取模的值： - -* `capacity` 值越小，占用内存小，误判概率越大。 -* `capacity` 值越大，占用内存大，误判概率越小。 - -实际应用时，如果业务场景能够预判断写入不存在冲突（如导入数据操作），建议关闭冲突检测。 - -相应地，在 TiKV 层检测内存中是否存在冲突也有类似的机制。不同的是，TiKV 层的检测会更严格且不允许关闭，仅支持对 Hash 取模值进行配置： - -```toml -# scheduler 内置一个内存锁机制，防止同时对一个 Key 进行操作。 -# 每个 Key hash 到不同的 slot。（默认为 2048000） -scheduler-concurrency = 2048000 -``` - -此外，TiKV 支持监控等待 latch 的时间： - -![Scheduler latch wait duration](/media/optimistic-transaction-metric.png) - -当 `Scheduler latch wait duration` 的值特别高时，说明大量时间消耗在等待锁的请求上。如果不存在底层写入慢的问题，基本上可以判断该段时间内冲突比较多。 - -## 更多阅读 - -- [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/) \ No newline at end of file diff --git a/v3.0/reference/transactions/transaction-pessimistic.md b/v3.0/reference/transactions/transaction-pessimistic.md deleted file mode 100644 index 5dd3cb24ff2c..000000000000 --- a/v3.0/reference/transactions/transaction-pessimistic.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: TiDB 悲观事务模型 -summary: 了解 TiDB 的悲观事务模型。 -category: reference ---- - -# TiDB 悲观事务模型 - -在 v3.0.8 之前，TiDB 默认使用的乐观事务模式会导致事务提交时因为冲突而失败。为了保证事务的成功率，需要修改应用程序，加上重试的逻辑。悲观事务模式可以避免这个问题，应用程序无需添加重试逻辑，就可以正常执行。 - -## 悲观事务的使用方法 - -进入悲观事务模式有以下三种方式: - -- 执行 `BEGIN PESSIMISTIC;` 语句开启的事务，会进入悲观事务模式。 -可以通过写成注释的形式 `BEGIN /*!90000 PESSIMISTIC */;` 来兼容 MySQL 语法。 - -- 执行 `set @@tidb_txn_mode = 'pessimistic';`，使这个 session 执行的所有显式事务（即非 autocommit 的事务）都会进入悲观事务模式。 - -- 执行 `set @@global.tidb_txn_mode = 'pessimistic';`，使之后整个集群所有新创建 session 执行的所有显示事务（即非 autocommit 的事务）都会进入悲观事务模式。 - -在配置了 `global.tidb_txn_mode` 为 `pessimistic` 之后，默认进入悲观事务模式，但是可以用以下三种方式使事务进入乐观事务模式： - -- 执行 `BEGIN OPTIMISTIC;` 语句开启的事务，会进入乐观事务模式。 -可以通过写成注释的形式 `BEGIN /*!90000 OPTIMISTIC */;` 来兼容 MySQL 语法。 - -- 执行 `set @@tidb_txn_mode = 'optimistic';` 或 `set @@tidb_txn_mode = '';`，使当前的 session 执行的事务进入乐观事务模式。 - -- 执行 `set @@global.tidb_txn_mode = 'optimistic;'` 或 `set @@global.tidb_txn_mode = '';`，使之后整个集群所有新创建 session 执行的事务都进入乐观事务模式。 - -`BEGIN PESSIMISTIC;` 和 `BEGIN OPTIMISTIC;` 语句的优先级高于 `tidb_txn_mode` 系统变量。使用这两个语句开启的事务，会忽略系统变量，从而支持悲观、乐观事务混合使用。 - -如果想要禁用悲观事务特性，可以修改 TiDB 配置文件，在 `[pessimistic-txn]` 类别下添加 `enable = false`。 - -## 悲观事务模式的行为 - -悲观事务的行为和 MySQL 基本一致（不一致之处详见[和 MySQL InnoDB 的差异](#和-mysql-innodb-的差异)）： - -- `SELECT FOR UPDATE` 会读取已提交的最新数据，并对读取到的数据加悲观锁。 - -- `UPDATE`、`DELETE` 和 `INSERT` 语句都会读取已提交的最新的数据来执行，并对修改的数据加悲观锁。 - -- 当一行数据被加了悲观锁以后，其他尝试修改这一行的写事务会被阻塞，等待悲观锁的释放。 - -- 当一行数据被加了悲观锁以后，其他尝试读取这一行的事务不会被阻塞，可以读到已提交的数据。 - -- 事务提交或回滚的时候，会释放所有的锁。 - -- 当有多个事务同时等待同一个锁释放时，会尽可能按照事务 start ts 顺序获取锁，但不能严格保证。 - -- 如果并发事务出现死锁，会被死锁检测器检测到，随机终止掉其中一个事务并返回兼容 MySQL 的错误码 `1213`。 - -- 乐观事务和悲观事务可以共存，事务可以任意指定使用乐观模式或悲观模式来执行。 - -- 通过设置 `innodb_wait_timeout` 变量，设置等锁超时时间，等锁超时后返回兼容 MySQL 的错误码 `1205`。 - -## 和 MySQL InnoDB 的差异 - -1. TiDB 使用 range 作为 WHERE 条件，执行 DML 和 `SELECT FOR UPDATE` 语句时不会阻塞范围内并发的 `INSERT` 语句的执行。 - - InnoDB 通过实现 gap lock，支持阻塞 range 内并发的 `INSERT` 语句的执行，其主要目的是为了支持 statement based binlog，因此有些业务会通过将隔离级别降低至 READ COMMITTED 来避免 gap lock 导致的并发性能问题。TiDB 不支持 gap lock，也就不需要付出相应的并发性能的代价。 - -2. TiDB 不支持 `SELECT LOCK IN SHARE MODE`。 - - 使用这个语句执行的时候，效果和没有加锁是一样的，不会阻塞其他事务的读写。 - -3. DDL 可能会导致悲观事务提交失败。 - - MySQL 在执行 DDL 时会被正在执行的事务阻塞住，而在 TiDB 中 DDL 操作会成功，造成悲观事务提交失败：`ERROR 1105 (HY000): Information schema is changed. [try again later]`。 - -4. `START TRANSACTION WITH CONSISTENT SNAPSHOT` 之后，MySQL 仍然可以读取到之后在其他事务创建的表，而 TiDB 不能。 - -5. autocommit 事务不支持悲观锁 - - 所有自动提交的语句都不会加悲观锁，该类语句在用户侧感知不到区别，因为悲观事务的本质是把整个事务的重试变成了单个 DML 的重试，autocommit 事务即使在 TiDB 关闭重试时也会自动重试，效果和悲观事务相同。 - - 自动提交的 select for update 语句也不会等锁。 - -## 常见问题 - -1. TiDB 日志出现 `pessimistic write conflict, retry statement`。 - - 当发生 write conflict 时，乐观事务会直接终止，而悲观事务会尝试用最新数据重试该语句直到没有 write conflict，每次重试都会打印该 log，不用特别关注。 - -2. 执行 DML 时报错 `pessimistic lock retry limit reached`。 - - 悲观事务每个语句有重试次数限制，当因 write conflict 重试超过该限制时会报该错误，默认为 256 次，可通过 TiDB 配置文件 `[pessimistic-txn]` 类别下的 `max-retry-limit` 修改。 - -3. 悲观事务执行时间限制。 - - 除了有事务执行时间不能超出 `tikv_gc_life_time` 的限制外，悲观事务的 TTL 有 10 分钟上限，所以执行时间超过 10 分钟的悲观事务有可能提交失败。 diff --git a/v3.0/releases/11alpha.md b/v3.0/releases/11alpha.md deleted file mode 100644 index fcf40ceb9727..000000000000 --- a/v3.0/releases/11alpha.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: TiDB 1.1 Alpha Release Notes -category: Releases -aliases: ['/docs-cn/releases/11alpha/'] ---- - -# TiDB 1.1 Alpha Release Notes - -2018 年 1 月 19 日，TiDB 发布 1.1 Alpha 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB： - -- SQL parser - - 兼容更多语法 -- SQL 查询优化器 - - 统计信息减小内存占用 - - 优化统计信息启动时载入的时间 - - 更精确的代价估算 - - 使用 `Count-Min Sketch` 更精确地估算点查的代价 - - 支持更复杂的条件，更充分使用索引 -- SQL 执行器 - - 使用 Chunk 结构重构所有执行器算子，提升分析型语句执行性能，减少内存占用 - - 优化 `INSERT IGNORE` 语句性能 - - 下推更多的类型和函数 - - 支持更多的 `SQL_MODE` - - 优化 `Load Data` 性能，速度提升 10 倍 - - 优化 `Use Database` 性能 - - 支持对物理算子内存使用进行统计 -- Server - - 支持 PROXY protocol - -## PD： - -- 增加更多的 API -- 支持 TLS -- 给 Simulator 增加更多的 case -- 调度适应不同的 Region size -- Fix 了一些调度的 bug - -## TiKV： - -- 支持 Raft learner -- 优化 Raft Snapshot，减少 I/O 开销 -- 支持 TLS -- 优化 RocksDB 配置，提升性能 -- 优化 Coprocessor `count (*)` 和点查 unique index 的性能 -- 增加更多的 Failpoint 以及稳定性测试 case -- 解决 PD 和 TiKV 之间重连的问题 -- 增强数据恢复工具 `tikv-ctl` 的功能 -- Region 支持按 table 进行分裂 -- 支持 `Delete Range` 功能 -- 支持设置 snapshot 导致的 I/O 上限 -- 完善流控机制 diff --git a/v3.0/releases/11beta.md b/v3.0/releases/11beta.md deleted file mode 100644 index 0946c8fe970b..000000000000 --- a/v3.0/releases/11beta.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: TiDB 1.1 Beta Release Notes -category: Releases -aliases: ['/docs-cn/releases/11beta/'] ---- - -# TiDB 1.1 Beta Release Notes - -2018 年 2 月 24 日，TiDB 发布 1.1 Beta 版。该版本在 1.1 Alpha 版的基础上，对 MySQL 兼容性、系统稳定性做了很多改进。 - -## TiDB - -+ 添加更多监控项, 优化日志 -+ 兼容更多 MySQL 语法 -+ 在 `information_schema` 中支持显示建表时间 -+ 提速包含 `MaxOneRow` 算子的查询 -+ 控制 Join 产生的中间结果集大小，进一步减少 Join 的内存使用 -+ 增加 `tidb_config` session 变量，输出当前 TiDB 配置 -+ 修复 `Union` 和 `Index Join` 算子中遇到的 panic 问题 -+ 修复 `Sort Merge Join` 算子在部分场景下结果错误的问题 -+ 修复 `Show Index` 语句显示正在添加过程中的索引的问题 -+ 修复 `Drop Stats` 语句失败的问题 -+ 优化 SQL 引擎查询性能，Sysbench 的 Select/OLTP 测试结果提升 10% -+ 使用新的执行引擎提升优化器中的子查询计算速度；相比 1.0 版本，在 TPC-H 以及 TPC-DS 等测试中有显著提升 - -## PD - -+ 增加 Drop Region 调试接口 -+ 支持设置 PD leader 优先级 -+ 支持配置特定 label 的节点不调度 Raft leader -+ 增加枚举各个 PD health 状态的接口 -+ 添加更多 metrics -+ PD leader 尽量与 etcd leader 保持同步 -+ 提高 TiKV 宕机时数据恢复优先级和恢复速度 -+ 完善 `data-dir` 配置项的合法性较验 -+ 优化 Region heartbeat 性能 -+ 修复热点调度破坏 label 约束的问题 -+ 其他稳定性问题修复 - -## TiKV - -+ 使用 offset + limit 遍历 lock，消除潜在的 GC 问题 -+ 支持批量 resolve lock，提升 GC 速度 -+ 支持并行 GC，提升 GC 速度 -+ 使用 RocksDB compaction listener 更新 Region Size，让 PD 更精确的进行调度 -+ 使用 `DeleteFilesInRanges` 批量删除过期数据，提高 TiKV 启动速度 -+ 设置 Raft snapshot max size，防止遗留文件占用太多空间 -+ `tikv-ctl` 支持更多修复操作 -+ 优化有序流式聚合操作 -+ 完善 metrics，修复 bug \ No newline at end of file diff --git a/v3.0/releases/2.0.10.md b/v3.0/releases/2.0.10.md deleted file mode 100644 index f488a48537da..000000000000 --- a/v3.0/releases/2.0.10.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB 2.0.10 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.0.10/'] ---- - -# TiDB 2.0.10 Release Notes - -2018 年 12 月 18 日，TiDB 发布 2.0.10 版，TiDB Ansible 相应发布 2.0.10 版本。该版本在 2.0.9 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复取消 DDL 任务的时候可能导致的问题 [#8513](https://github.com/pingcap/tidb/pull/8513) -- 修复 `ORDER BY`，`UNION` 语句无法引用带表名的列的问题 [#8514](https://github.com/pingcap/tidb/pull/8514) -- 修复 `UNCOMPRESS` 函数没有判断错误输入长度的问题 [#8607](https://github.com/pingcap/tidb/pull/8607) -- 修复 `ANSI_QUOTES SQL_MODE` 在 TiDB 升级的时候遇到的问题 [#8575](https://github.com/pingcap/tidb/pull/8575) -- 修复某些情况下 `select` 返回结果错误的问题 [#8570](https://github.com/pingcap/tidb/pull/8570) -- 修复 TiDB 在收到退出信号的时候可能无法退出的问题 [#8501](https://github.com/pingcap/tidb/pull/8501) -- 修复某些情况下 `IndexLookUpJoin` 返回错误结果的问题 [#8508](https://github.com/pingcap/tidb/pull/8508) -- 避免下推有 `GetVar` 或 `SetVar 的 filter` [#8454](https://github.com/pingcap/tidb/pull/8454) -- 修复某些情况下 `UNION` 语句结果长度错误的问题 [#8491](https://github.com/pingcap/tidb/pull/8491) -- 修复 `PREPARE FROM @var_name` 的问题 [#8488](https://github.com/pingcap/tidb/pull/8488) -- 修复某些情况下导出统计信息 panic 的问题 [#8464](https://github.com/pingcap/tidb/pull/8464) -- 修复统计信息某些情况下对点查估算的问题 [#8493](https://github.com/pingcap/tidb/pull/8493) -- 修复某些情况下返回 Enum 默认值为字符串导致的 panic [#8476](https://github.com/pingcap/tidb/pull/8476) -- 修复在宽表场景下，占用太多内存的问题 [#8467](https://github.com/pingcap/tidb/pull/8467) -- 修复 Parser 对取模操作错误格式化导致的问题 [#8431](https://github.com/pingcap/tidb/pull/8431) -- 修复某些情况下添加外键约束导致的 panic 问题 [#8421](https://github.com/pingcap/tidb/pull/8421)，[#8410](https://github.com/pingcap/tidb/pull/8410) -- 修复 `YEAR` 类型错误转换零值的问题 [#8396](https://github.com/pingcap/tidb/pull/8396) -- 修复 `VALUES` 函数在参数不为列的时候 panic 的问题 [#8404](https://github.com/pingcap/tidb/pull/8404) -- 存在子查询的语句禁用 Plan Cache [#8395](https://github.com/pingcap/tidb/pull/8395) - -## PD - -- 修复 RaftCluster 在退出时可能的死锁问题 [#1370](https://github.com/pingcap/pd/pull/1370) - -## TiKV - -- 修复迁移 Leader 到新节点时造成请求延时问题 [#3929](https://github.com/tikv/tikv/pull/3929) -- 修复多余的 Region 心跳 [#3930](https://github.com/tikv/tikv/pull/3930) diff --git a/v3.0/releases/2.0.11.md b/v3.0/releases/2.0.11.md deleted file mode 100644 index 3bdb6b1bc284..000000000000 --- a/v3.0/releases/2.0.11.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: TiDB 2.0.11 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.0.11/'] ---- - -# TiDB 2.0.11 Release Notes - -2019 年 1 月 3 日，TiDB 发布 2.0.11 版，TiDB Ansible 相应发布 2.0.11 版本。该版本在 2.0.10 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复 PD 发生异常的情况下，Error 没有被正确处理的问题 [#8764](https://github.com/pingcap/tidb/pull/8764) -- 修复 Rename 相同表的行为，跟 MySQL 保持一致 [#8809](https://github.com/pingcap/tidb/pull/8809) -- 修复 `ADMIN CHECK TABLE` 在 `ADD INDEX` 过程中误报的问题 [#8750](https://github.com/pingcap/tidb/pull/8750) -- 修复前缀索引在某些情况下，开闭范围区间错误的问题 [#8877](https://github.com/pingcap/tidb/pull/8877) -- 修复在某些添加列的情况下，`UPDATE` 语句 panic 的问题 [#8904](https://github.com/pingcap/tidb/pull/8904) - -## TiKV - -- 修复了两个 Region merge 相关的问题 -[#4003](https://github.com/tikv/tikv/pull/4003)，[#4004](https://github.com/tikv/tikv/pull/4004) \ No newline at end of file diff --git a/v3.0/releases/2.0ga.md b/v3.0/releases/2.0ga.md deleted file mode 100644 index 844e8cd98250..000000000000 --- a/v3.0/releases/2.0ga.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: TiDB 2.0 release notes -category: Releases -aliases: ['/docs-cn/releases/2.0ga/'] ---- - -# TiDB 2.0 Release Notes - -2018 年 4 月 27 日，TiDB 发布 2.0 GA 版。相比 1.0 版本，该版本对 MySQL 兼容性、系统稳定性、优化器和执行器做了很多改进。 - -## TiDB - -- SQL 优化器 - - 精简统计信息数据结构，减小内存占用 - - 加快进程启动时加载统计信息速度 - - 支持统计信息动态更新 [experimental] - - 优化代价模型，对代价估算更精准 - - 使用 `Count-Min Sketch` 更精确地估算点查的代价 - - 支持分析更复杂的条件，尽可能充分的使用索引 - - 支持通过 `STRAIGHT_JOIN` 语法手动指定 Join 顺序 - - `GROUP BY`子句为空时使用 Stream Aggregation 算子，提升性能 - - 支持使用索引计算 `Max/Min` 函数 - - 优化关联子查询处理算法，支持将更多类型的关联子查询解关联并转化成 `Left Outer Join` - - 扩大 `IndexLookupJoin` 的使用范围，索引前缀匹配的场景也可以使用该算法 -- SQL 执行引擎 - - 使用 Chunk 结构重构所有执行器算子，提升分析型语句执行性能，减少内存占用，显著提升 TPC-H 结果 - - 支持 Streaming Aggregation 算子下推 - - 优化 `Insert Into Ignore` 语句性能，提升 10 倍以上 - - 优化 `Insert On Duplicate Key Update` 语句性能，提升 10 倍以上 - - 下推更多的数据类型和函数到 TiKV 计算 - - 优化 `Load Data` 性能，提升 10 倍以上 - - 支持对物理算子内存使用进行统计，通过配置文件以及系统变量指定超过阈值后的处理行为 - - 支持限制单条 SQL 语句使用内存的大小，减少程序 OOM 风险 - - 支持在 CRUD 操作中使用隐式的行 ID - - 提升点查性能 -- Server - - 支持 Proxy Protocol - - 添加大量监控项, 优化日志 - - 支持配置文件的合法性检测 - - 支持 HTTP API 获取 TiDB 参数信息 - - 使用 Batch 方式 Resolve Lock，提升垃圾回收速度 - - 支持多线程垃圾回收 - - 支持 TLS -- 兼容性 - - 支持更多 MySQL 语法 - - 支持配置文件修改 `lower_case_table_names` 系统变量，用于支持 OGG 数据同步工具 - - 提升对 Navicat 的兼容性 - - 在 `Information_Schema` 中支持显示建表时间 - - 修复部分函数/表达式返回类型和 MySQL 不同的问题 - - 提升对 JDBC 兼容性 - - 支持更多的 `SQL_MODE` -- DDL - - 优化 `Add Index` 的执行速度，部分场景下速度大幅度提升 - - `Add Index` 操作变更为低优先级，降低对线上业务影响 - - `Admin Show DDL Jobs` 输出更详细的 DDL 任务状态信息 - - 支持 `Admin Show DDL Job Queries JobID` 查询当前正在运行的 DDL 任务的原始语句 - - 支持 `Admin Recover Index` 命令，用于灾难恢复情况下修复索引数据 - - 支持通过 `Alter` 语句修改 Table Options - -## PD - -- 增加 `Region Merge` 支持，合并数据删除后产生的空 Region [experimental] -- 增加 `Raft Learner` 支持 [experimental] -- 调度器优化 - - 调度器适应不同的 Region size - - 提升 TiKV 宕机时数据恢复的优先级和恢复速度 - - 提升下线 TiKV 节点搬迁数据的速度 - - 优化 TiKV 节点空间不足时的调度策略，尽可能防止空间不足时磁盘被写满 - - 提升 balance-leader scheduler 的调度效率 - - 减少 balance-region scheduler 调度开销 - - 优化 hot-region scheduler 的执行效率 -- 运维接口及配置 - - 增加 TLS 支持 - - 支持设置 PD leader 优先级 - - 支持基于 label 配置属性 - - 支持配置特定 label 的节点不调度 Region leader - - 支持手动 Split Region，可用于处理单 Region 热点的问题 - - 支持打散指定 Region，用于某些情况下手动调整热点 Region 分布 - - 增加配置参数检查规则，完善配置项的合法性较验 -- 调试接口 - - 增加 `Drop Region` 调试接口 - - 增加枚举各个 PD health 状态的接口 -- 统计相关 - - 添加异常 Region 的统计 - - 添加 Region 隔离级别的统计 - - 添加调度相关 metrics -- 性能优化 - - PD leader 尽量与 etcd leader 保持同步，提升写入性能 - - 优化 Region heartbeat 性能，现可支持超过 100 万 Region - -## TiKV - -- 功能 - - 保护关键配置，防止错误修改 - - 支持 `Region Merge` [experimental] - - 添加 `Raw DeleteRange` API - - 添加 `GetMetric` API - - 添加 `Raw Batch Put`，`Raw Batch Get`，`Raw Batch Delete` 和 `Raw Batch Scan` - - 给 Raw KV API 增加 Column Family 参数，能对特定 Column Family 进行操作 - - Coprocessor 支持 streaming 模式，支持 streaming 聚合 - - 支持配置 Coprocessor 请求的超时时间 - - 心跳包携带时间戳 - - 支持在线修改 RocksDB 的一些参数，包括 `block-cache-size` 大小等 - - 支持配置 Coprocessor 遇到某些错误时的行为 - - 支持以导数据模式启动，减少导数据过程中的写放大 - - 支持手动对 region 进行对半 split - - 完善数据修复工具 tikv-ctl - - Coprocessor 返回更多的统计信息，以便指导 TiDB 的行为 - - 支持 ImportSST API，可以用于 SST 文件导入 [experimental] - - 新增 TiKV Importer 二进制，与 TiDB Lightning 集成用于快速导入数据 [experimental] -- 性能 - - 使用 ReadPool 优化读性能，`raw_get/get/batch_get` 提升 30% - - 提升 metrics 的性能 - - Raft snapshot 处理完之后立即通知 PD，加快调度速度 - - 解决 RocksDB 刷盘导致性能抖动问题 - - 提升在数据删除之后的空间回收 - - 加速启动过程中的垃圾清理过程 - - 使用 `DeleteFilesInRanges` 减少副本迁移时 I/O 开销 -- 稳定性 - - 解决在 PD leader 发送切换的情况下 gRPC call 不返回问题 - - 解决由于 snapshot 导致下线节点慢的问题 - - 限制搬移副本临时占用的空间大小 - - 如果有 Region 长时间没有 Leader，进行上报 - - 根据 compaction 事件及时更新统计的 Region size - - 限制单次 scan lock 请求的扫描的数据量，防止超时 - - 限制接收 snapshot 过程中的内存占用，防止 OOM - - 提升 CI test 的速度 - - 解决由于 snapshot 太多导致的 OOM 问题 - - 配置 gRPC 的 `keepalive` 参数 - - 修复 Region 增多容易 OOM 的问题 - -## TiSpark - -TiSpark 使用独立的版本号，现为 1.0 GA。TiSpark 1.0 版本组件提供了针对 TiDB 上的数据使用 Apache Spark 进行分布式计算的能力。 - -- 提供了针对 TiKV 读取的 gRPC 通信框架 -- 提供了对 TiKV 组件数据的和通信协议部分的编码解码 -- 提供了计算下推功能，包含： - - 聚合下推 - - 谓词下推 - - TopN 下推 - - Limit 下推 -- 提供了索引相关的支持 - - 谓词转化聚簇索引范围 - - 谓词转化次级索引 - - Index Only 查询优化 - - 运行时索引退化扫表优化 -- 提供了基于代价的优化 - - 统计信息支持 - - 索引选择 - - 广播表代价估算 -- 多种 Spark Interface 的支持 - - Spark Shell 支持 - - ThriftServer/JDBC 支持 - - Spark-SQL 交互支持 - - PySpark Shell 支持 - - SparkR 支持 diff --git a/v3.0/releases/2.1.1.md b/v3.0/releases/2.1.1.md deleted file mode 100644 index 01938325c172..000000000000 --- a/v3.0/releases/2.1.1.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: TiDB 2.1.1 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.1/'] ---- - -# TiDB 2.1.1 Release Notes - -2018 年 12 月 12 日，TiDB 发布 2.1.1 版。相比 2.1.0 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复时间为负值时的四舍五入错误 [#8574](https://github.com/pingcap/tidb/pull/8574) - - 修复 `uncompress` 函数未检查数据长度的问题 [#8606](https://github.com/pingcap/tidb/pull/8606) - - 在执行 `execute` 命令后重置 `prepare` 语句绑定的变量 [#8652](https://github.com/pingcap/tidb/pull/8652) - - 支持对分区表自动收集统计信息 [#8649](https://github.com/pingcap/tidb/pull/8649) - - 修复在下推 `abs` 函数时设置错误的整数类型 [#8628](https://github.com/pingcap/tidb/pull/8628) - - 修复 JSON 列的数据竞争问题 [#8660](https://github.com/pingcap/tidb/pull/8660) -+ Server - - 修复在 PD 故障时获取错误 TSO 的问题 [#8567](https://github.com/pingcap/tidb/pull/8567) - - 修复不规范的语句导致启动失败的问题 [#8576](https://github.com/pingcap/tidb/pull/8576) - - 修复在事务重试时使用了错误的参数 [#8638](https://github.com/pingcap/tidb/pull/8638) -+ DDL - - 将表的默认字符集和排序规则改为 `utf8mb4` 和 `utf8mb4_bin` [#8590](https://github.com/pingcap/tidb/pull/8590) - - 增加变量 `ddl_reorg_batch_size` 来控制添加索引的速度 [#8614](https://github.com/pingcap/tidb/pull/8614) - - DDL 中的 character set 和 collation 选项内容不再大小写敏感 [#8611](https://github.com/pingcap/tidb/pull/8611) - - 修复对于生成列添加索引的问题 [#8655](https://github.com/pingcap/tidb/pull/8655) - -## PD - -- 修复一些配置项无法在配置文件中设置为 `0` 的问题 [#1334](https://github.com/pingcap/pd/pull/1334) -- 启动时检查未定义的配置 [#1362](https://github.com/pingcap/pd/pull/1362) -- 避免 transfer leader 至新创建的 Peer，优化可能产生的延迟增加问题 [#1339](https://github.com/pingcap/pd/pull/1339) -- 修复 RaftCluster 在退出时可能的死锁问题 [#1370](https://github.com/pingcap/pd/pull/1370) - -## TiKV - -- 避免 transfer leader 至新创建的 Peer，优化可能产生的延迟增加问题 [#3878](https://github.com/tikv/tikv/pull/3878) - -## Tools - -+ Lightning - - 优化对导入表的 `analyze` 机制，提升了导入速度 - - 支持 checkpoint 信息储存在本地文件 -+ TiDB Binlog - - 修复 pb files 输出 bug，表只有主键列则无法产生 pb event \ No newline at end of file diff --git a/v3.0/releases/2.1.10.md b/v3.0/releases/2.1.10.md deleted file mode 100644 index 759a7353874f..000000000000 --- a/v3.0/releases/2.1.10.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: TiDB 2.1.10 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.10/'] ---- - -# TiDB 2.1.10 Release Notes - -发版日期：2019 年 5 月 22 日 - -TiDB 版本：2.1.10 - -TiDB Ansible 版本：2.1.10 - -## TiDB - -- 修复在使用 `tidb_snapshot` 读取历史数据的时候，某些异常情况导致的表结构不正确 [#10359](https://github.com/pingcap/tidb/pull/10359) -- 修复 `NOT` 函数在某些情况下导致的读取结果错误的问题 [#10363](https://github.com/pingcap/tidb/pull/10363) -- 修复 `Generated Column` 在 `Replace` 或者 `Insert on duplicate update` 语句中的错误行为 [#10385](https://github.com/pingcap/tidb/pull/10385) -- 修复 `BETWEEN` 函数在 `DATE`/`DATETIME` 类型比较的一个 bug [#10407](https://github.com/pingcap/tidb/pull/10407) -- 修复使用 `SLOW_QUERY` 表查询慢日志时，单行慢日志长度过长导致的报错 [#10412](https://github.com/pingcap/tidb/pull/10412) -- 修复某些情况下 `DATETIME` 和 `INTERVAL` 相加的结果跟 MySQL 不一致的问题 [#10416](https://github.com/pingcap/tidb/pull/10416)，[#10418](https://github.com/pingcap/tidb/pull/10418) -- 增加闰年二月的非法时间的检查 [#10417](https://github.com/pingcap/tidb/pull/10417) -- 内部的初始化操作限制只在 DDL Owner 中执行，避免了初始化集群的时候出现的大量冲突报错 [#10426](https://github.com/pingcap/tidb/pull/10426) -- 修复 `DESC` 在输出时间戳列的默认值为 `default current_timestamp on update current_timestamp` 时跟 MySQL 不兼容的问题 [#10337](https://github.com/pingcap/tidb/issues/10337) -- 修复 `Update` 语句中权限检查出错的问题 [#10439](https://github.com/pingcap/tidb/pull/10439) -- 修复 `CHAR` 类型的列在某些情况下 `RANGE` 计算错误导致的错误结果的问题 [#10455](https://github.com/pingcap/tidb/pull/10455) -- 避免 `ALTER SHARD_ROW_ID_BITS` 缩小 shard bits 位数在极低概率下，可能导致的数据错误 [#9868](https://github.com/pingcap/tidb/pull/9868) -- 修复 `ORDER BY RAND()` 不返回随机数字的问题 [#10064](https://github.com/pingcap/tidb/pull/10064) -- 禁止 `ALTER` 语句修改 DECIMAL 的精度 [#10458](https://github.com/pingcap/tidb/pull/10458) -- 修复 `TIME_FORMAT` 函数与 MySQL 的兼容问题 [#10474](https://github.com/pingcap/tidb/pull/10474) -- 检查 `PERIOD_ADD` 中参数的合法性 [#10430](https://github.com/pingcap/tidb/pull/10430) -- 修复非法的 `YEAR` 字符串在 TiDB 中的表现跟 MySQL 不兼容的问题 [#10493](https://github.com/pingcap/tidb/pull/10493) -- 支持 `ALTER DATABASE` 语法 [#10503](https://github.com/pingcap/tidb/pull/10503) -- 修复 `SLOW_QUERY` 内存表在慢语句没有 `;` 的情况下报错的问题 [#10536](https://github.com/pingcap/tidb/pull/10536) -- 修复某些情况下 `Partitioned Table` 的表 `Add index` 操作没有办法取消的问题 [#10533](https://github.com/pingcap/tidb/pull/10533) -- 修复在某些情况下无法抓住内存使用太多导致 OOM 的问题 [#10545](https://github.com/pingcap/tidb/pull/10545) -- 增强 DDL 操作改写表元信息的安全性 [#10547](https://github.com/pingcap/tidb/pull/10547) - -## PD - -- 修复 Leader 优先级不生效的问题 [#1533](https://github.com/pingcap/pd/pull/1533) - -## TiKV - -- 拒绝在最近发生过成员变更的 Region 上执行 transfer leader，防止迁移失败 [#4684](https://github.com/tikv/tikv/pull/4684) -- Coprocessor metrics 上添加 priority 标签 [#4643](https://github.com/tikv/tikv/pull/4643) -- 修复 transfer leader 中可能发生的脏读问题 [#4724](https://github.com/tikv/tikv/pull/4724) -- 修复某些情况下 `CommitMerge` 导致 TiKV 不能重启的问题 [#4615](https://github.com/tikv/tikv/pull/4615) -- 修复 unknown 的日志 [#4730](https://github.com/tikv/tikv/pull/4730) - -## Tools - -- TiDB Lightning - - 新增 TiDB Lightning 发送数据到 importer 失败时进行重试 [#176](https://github.com/pingcap/tidb-lightning/pull/176) -- TiDB Binlog - - 优化 Pump storage 组件 log，以利于排查问题 [#607](https://github.com/pingcap/tidb-binlog/pull/607) - -## TiDB Ansible - -- 更新 TiDB Lightning 配置文件，新增 `tidb_lightning_ctl` 脚本 [#d3a4a368](https://github.com/pingcap/tidb-ansible/commit/d3a4a368810a421c49980899a286cf010569b4c7) diff --git a/v3.0/releases/2.1.11.md b/v3.0/releases/2.1.11.md deleted file mode 100644 index 81a7eb513e68..000000000000 --- a/v3.0/releases/2.1.11.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: TiDB 2.1.11 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.11/'] ---- - -# TiDB 2.1.11 Release Notes - -发版日期：2019 年 6 月 03 日 - -TiDB 版本：2.1.11 - -TiDB Ansible 版本：2.1.11 - -## TiDB - -- 修复 delete 多表 join 的结果时使用错误 schema 的问题 [#10595](https://github.com/pingcap/tidb/pull/10595) -- 修复 `CONVERT()` 函数返回错误的字段类型的问题 [#10263](https://github.com/pingcap/tidb/pull/10263) -- 更新统计信息时合并不重叠的反馈信息 [#10569](https://github.com/pingcap/tidb/pull/10569) -- 修复 `unix_timestamp()-unix_timestamp(now())` 计算错误的问题 [#10491](https://github.com/pingcap/tidb/pull/10491) -- 修复 `period_diff` 与 MySQL 8.0 不兼容的问题 [#10501](https://github.com/pingcap/tidb/pull/10501) -- 收集统计信息的时候，忽略 `Virtual Column`，避免异常报错 [#10628](https://github.com/pingcap/tidb/pull/10628) -- 支持 `SHOW OPEN TABLES` 语句 [#10374](https://github.com/pingcap/tidb/pull/10374) -- 修复某些情况下导致的 goroutine 泄露问题 [#10656](https://github.com/pingcap/tidb/pull/10656) -- 修复某些情况下设置 `tidb_snapshot` 变量时间格式解析出错的问题 [#10637](https://github.com/pingcap/tidb/pull/10637) - -## PD - -- 修复因为 `balance-region` 可能会导致热点 Region 没有机会调度的问题 [#1551](https://github.com/pingcap/pd/pull/1551) -- 将热点相关调度的优先级改为高优先级 [#1551](https://github.com/pingcap/pd/pull/1551) -- 新增配置项 `hot-region-schedule-limit` 控制同时进行热点调度任务的数量及新增 `hot-region-cache-hits-threshold` 控制判断是否为热点 Region [#1551](https://github.com/pingcap/pd/pull/1551) - -## TiKV - -- 修复在仅有一个 leader，learner 时，learner 读到空 index 的问题 [#4751](https://github.com/tikv/tikv/pull/4751) -- 将 `ScanLock` 和 `ResolveLock` 放在高优先级线程池中处理，减少对普通优先级命令的影响 [#4791](https://github.com/tikv/tikv/pull/4791) -- 同步所有收到的 snapshot 的文件 [#4811](https://github.com/tikv/tikv/pull/4811) - -## Tools - -- TiDB Binlog - - 新增 GC 删数据限速功能，避免因为删除数据导致 QPS 降低的问题 [#620](https://github.com/pingcap/tidb-binlog/pull/620) - -## TiDB Ansible - -- 新增 Drainer 参数 [#760](https://github.com/pingcap/tidb-ansible/pull/760) diff --git a/v3.0/releases/2.1.12.md b/v3.0/releases/2.1.12.md deleted file mode 100644 index 6bf14bb2bdda..000000000000 --- a/v3.0/releases/2.1.12.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: TiDB 2.1.12 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.12/'] ---- - -# TiDB 2.1.12 Release Notes - -发版日期：2019 年 6 月 13 日 - -TiDB 版本：2.1.12 - -TiDB Ansible 版本：2.1.12 - -## TiDB - -- 修复在使用 feedback 时由于类型不匹配导致进程 panic 的问题 [#10755](https://github.com/pingcap/tidb/pull/10755) -- 修复某些情况下改变字符集导致 BLOB 类型变成 TEXT 类型的问题 [#10745](https://github.com/pingcap/tidb/pull/10745) -- 修复某些情况下在事务中的 `GRANT` 操作误报 "Duplicate Entry" 错误的问题 [#10739](https://github.com/pingcap/tidb/pull/10739) -- 提升以下功能跟 MySQL 的兼容性 - - `DAYNAME` 函数 [#10732](https://github.com/pingcap/tidb/pull/10732) - - `MONTHNAME` 函数 [#10733](https://github.com/pingcap/tidb/pull/10733) - - `EXTRACT` 函数在处理 `MONTH` 的时候支持零值 [#10702](https://github.com/pingcap/tidb/pull/10702) - - `DECIMAL` 类型转换成 `TIMESTAMP` 或者 `DATETIME` 类型 [#10734](https://github.com/pingcap/tidb/pull/10734) -- 修改表的字符集时，同步修改列的字符集 [#10714](https://github.com/pingcap/tidb/pull/10714) -- 修复某些情况下 `DECIMAL` 转换成浮点数的溢出问题 [#10730](https://github.com/pingcap/tidb/pull/10730) -- 修复 TiDB 跟 TiKV 在 gRPC 最大封包设置不一致导致的某些超大封包报 "grpc: received message larger than max" 错误的问题 [#10710](https://github.com/pingcap/tidb/pull/10710) -- 修复某些情况下 `ORDER BY` 没有过滤 NULL 值导致的 panic 问题 [#10488](https://github.com/pingcap/tidb/pull/10488) -- 修复 `UUID` 函数的返回值，在多机器情况可能出现重复的问题 [#10711](https://github.com/pingcap/tidb/pull/10711) -- `CAST(-num as datetime)` 的返回值由错误变更为 NULL 值 [#10703](https://github.com/pingcap/tidb/pull/10703) -- 修复某些情况下 unsigned 列直方图遇到 signed 越界的问题 [#10695](https://github.com/pingcap/tidb/pull/10695) -- 修复统计信息的 feedback 遇到 bigint unsigned 主键时处理不正确导致读数据时报错的问题 [#10307](https://github.com/pingcap/tidb/pull/10307) -- 修复分区表某些情况下 `Show Create Table` 结果显示不正确的问题 [#10690](https://github.com/pingcap/tidb/pull/10690) -- 修复在某些关联子查询上聚合函数 `GROUP_CONCAT` 计算不正确的问题 [#10670](https://github.com/pingcap/tidb/pull/10670) -- 修复某些情况下 slow query 内存表在解析慢日志的时候导致的显示结果错乱的问题 [#10776](https://github.com/pingcap/tidb/pull/10776) - -## PD - -- 修复极端情况下 etcd Leader 选举阻塞的问题 [#1576](https://github.com/pingcap/pd/pull/1576) - -## TiKV - -- 修复极端条件下 Leader 迁移过程中 Region 不可用的问题 [#4799](https://github.com/tikv/tikv/pull/4734) -- 修复在机器异常掉电时由于接收 snapshot 未及时将数据刷新到磁盘导致丢数据的问题 [#4850](https://github.com/tikv/tikv/pull/4850) diff --git a/v3.0/releases/2.1.13.md b/v3.0/releases/2.1.13.md deleted file mode 100644 index 781c56bb8cc2..000000000000 --- a/v3.0/releases/2.1.13.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.13 Release Notes -category: Releases ---- - -# TiDB 2.1.13 Release Notes - -发版日期：2019 年 6 月 21 日 - -TiDB 版本：2.1.13 - -TiDB Ansible 版本：2.1.13 - -## TiDB - -- 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 [#10788](https://github.com/pingcap/tidb/pull/10788) -- 优化无效 DDL 元信息存活时间，缩短集群升级后恢复 DDL 操作正常执行所需的时间 [#10789](https://github.com/pingcap/tidb/pull/10789) -- 修复因持有 `execdetails.ExecDetails` 指针时 Coprocessor 的资源无法快速释放导致的在大并发场景下 OOM 的问题 [#10833](https://github.com/pingcap/tidb/pull/10833) -- 新增 `update-stats`配置项，控制是否更新统计信息 [#10772](https://github.com/pingcap/tidb/pull/10772) -- 新增 3 个 TiDB 特有语法，支持预先切分 Region，解决热点问题： - - 新增 Table Option `PRE_SPLIT_REGIONS` 选项 [#10863](https://github.com/pingcap/tidb/pull/10863) - - 新增 `SPLIT TABLE table_name INDEX index_name` 语法 [#10865](https://github.com/pingcap/tidb/pull/10865) - - 新增 `SPLIT TABLE [table_name] BETWEEN (min_value...) AND (max_value...) REGIONS [region_num]` 语法 [#10882](https://github.com/pingcap/tidb/pull/10882) -- 修复某些情况下 `KILL` 语句导致的 panic 问题 [#10879](https://github.com/pingcap/tidb/pull/10879) -- 增强 `ADD_DATE` 在某些情况下跟 MySQL 的兼容性 [#10718](https://github.com/pingcap/tidb/pull/10718) -- 修复 index join 中内表过滤条件在某些情况下的选择率估计错误的问题 [#10856](https://github.com/pingcap/tidb/pull/10856) - -## TiKV - -- 修复因迭代器未检查状态导致系统生成残缺 snapshot 的问题 [#4940](https://github.com/tikv/tikv/pull/4940) -- 新增检查 `block-size` 配置的有效性功能 [#4930](https://github.com/tikv/tikv/pull/4930) - -## Tools - -TiDB Binlog - -- 修复 Pump 因写入失败时未检查返回值导致偏移量错误问题 [#640](https://github.com/pingcap/tidb-binlog/pull/640) -- Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 [#634](https://github.com/pingcap/tidb-binlog/pull/634) diff --git a/v3.0/releases/2.1.14.md b/v3.0/releases/2.1.14.md deleted file mode 100644 index 068864c31bc5..000000000000 --- a/v3.0/releases/2.1.14.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 2.1.14 Release Notes -category: Releases ---- - -# TiDB 2.1.14 Release Notes - -发版日期：2019 年 7 月 4 日 - -TiDB 版本：2.1.14 - -TiDB Ansible 版本：2.1.14 - -## TiDB - -- 修复某些情况下列裁剪导致查询结果不正确的问题 [#11019](https://github.com/pingcap/tidb/pull/11019) -- 修复 `show processlist` 中 `db` 和 `info` 列信息显示有误的问题 [#11000](https://github.com/pingcap/tidb/pull/11000) -- 修复 `MAX_EXECUTION_TIME` 作为 SQL hint 和全局变量在某些情况下不生效的问题 [#10999](https://github.com/pingcap/tidb/pull/10999) -- 支持根据负载情况自动调整 Auto ID 分配的步长 [#10997](https://github.com/pingcap/tidb/pull/10997) -- 修复 SQL 查询结束时 `MemTracker` 统计的 DistSQL 内存信息未正确清理的问题 [#10971](https://github.com/pingcap/tidb/pull/10971) -- `information_schema.processlist` 表中新增 `MEM` 列用于描述 Query 的内存使用情况 [#10896](https://github.com/pingcap/tidb/pull/10896) -- 新增全局系统变量 `max_execution_time`，用于控制查询的最大执行时间 [10940](https://github.com/pingcap/tidb/pull/10940) -- 修复使用未支持的聚合函数导致 TiDB panic 的问题 [#10911](https://github.com/pingcap/tidb/pull/10911) -- 新增 `load data` 语句失败后自动回滚最后一个事务功能 [#10862](https://github.com/pingcap/tidb/pull/10862) -- 修复 TiDB 超过内存配额的行为配置为 CANCEL 时，某些情况下 TiDB 返回结果不正确的问题 [#11016](https://github.com/pingcap/tidb/pull/11016) -- 禁用 `TRACE` 语句，避免 TiDB panic 问题 [#11039](https://github.com/pingcap/tidb/pull/11039) -- 新增 `mysql.expr_pushdown_blacklist` 系统表，控制动态开启/关闭 TiDB 下推到 Coprocessor 的函数 [#10998](https://github.com/pingcap/tidb/pull/10998) -- 修复 `ANY_VALUE` 函数在 `ONLY_FULL_GROUP_BY` 模式下不生效的问题 [#10994](https://github.com/pingcap/tidb/pull/10994) -- 修复给字符串类型的用户量赋值时因未深度拷贝导致赋值不正确的问题 [#11043](https://github.com/pingcap/tidb/pull/11043) - -## TiKV - -- 优化 Raftstore 消息处理中对空回调的处理流程，避免发送不必要的消息 [#4682](https://github.com/tikv/tikv/pull/4682) - -## PD - -- 调整当读取到无效配置项时日志信息输出的级别，由 Error 调整为 Warning [#1577](https://github.com/pingcap/pd/pull/1577) - -## Tools - -TiDB Binlog - -- Reparo - - 新增 `safe-mode` 配置项，开启后支持导入重复的数据 [#662](https://github.com/pingcap/tidb-binlog/pull/662) -- Pump - - 新增 `stop-write-at-available-space` 配置项，限制 Binlog 空间保留的大小 [#659](https://github.com/pingcap/tidb-binlog/pull/659) - - 修复 LevelDB L0 文件个数为 0 时 GC 有时不生效的问题 [#648](https://github.com/pingcap/tidb-binlog/pull/648) - - 优化 log 文件删除的算法，加速释放空间 [#648](https://github.com/pingcap/tidb-binlog/pull/648) -- Drainer - - 修复下游 TiDB BIT 类型列更新失败的问题 [#655](https://github.com/pingcap/tidb-binlog/pull/655) - -## TiDB Ansible - -- 新增 `ansible` 命令及其 `jmespath`、`Jinja2` 依赖包的预检查功能 [#807](https://github.com/pingcap/tidb-ansible/pull/807) -- Pump 新增 `stop-write-at-available-space` 参数，当磁盘剩余空间小于该值（默认 10 GiB）时，Pump 停止写入 Binlog [#807](https://github.com/pingcap/tidb-ansible/pull/807) diff --git a/v3.0/releases/2.1.15.md b/v3.0/releases/2.1.15.md deleted file mode 100644 index e1b2be612ef3..000000000000 --- a/v3.0/releases/2.1.15.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB 2.1.15 Release Notes -category: Releases ---- - -# TiDB 2.1.15 Release Notes - -发版日期：2019 年 7 月 18 日 - -TiDB 版本：2.1.15 - -TiDB Ansible 版本：2.1.15 - -## TiDB - -+ 修复 `DATE_ADD` 函数处理微秒时由于没有对齐导致结果不正确的问题 [#11289](https://github.com/pingcap/tidb/pull/11289) -+ 修复 `DELETE` 语句中，字符串列中的空值与 FLOAT/INT 做比较时会报错的问题 [#11279](https://github.com/pingcap/tidb/pull/11279) -+ 修复 `INSERT` 函数参数有 `NULL` 值时，未正确返回 `NULL` 值的问题 [#11249](https://github.com/pingcap/tidb/pull/11249) -+ 修复在非字符串类型且长度为 0 的列建立索引时出错的问题 [#11215](https://github.com/pingcap/tidb/pull/11215) -+ 新增 `SHOW TABLE REGIONS` 的语句，支持通过 SQL 查询表的 Region 分布情况 [#11238](https://github.com/pingcap/tidb/pull/11238) -+ 修复 `UPDATE … SELECT` 语句因 `SELECT` 子查询中使用投影消除来优化规则所导致的报错 [#11254](https://github.com/pingcap/tidb/pull/11254) -+ 新增 `ADMIN PLUGINS ENABLE/DISABLE` SQL 语句，支持通过 SQL 动态开启/关闭 Plugin [#11189](https://github.com/pingcap/tidb/pull/11189) -+ Audit Plugin 新增审记连接功能 [#11189](https://github.com/pingcap/tidb/pull/11189) -+ 修复点查时，某列被查询多次而且结果为 NULL 时会 Panic 的问题 [#11227](https://github.com/pingcap/tidb/pull/11227) -+ 新增 `tidb_scatter_region` 配置项，控制创建表时是否开启自己打散 Record Region [#11213](https://github.com/pingcap/tidb/pull/11213) -+ 修复 `RAND` 函数由于非线程安全的 `rand.Rand` 导致的 Data Race 问题 [#11170](https://github.com/pingcap/tidb/pull/11170) -+ 修复某些情况下整数和非整数比较结果不正确的问题 [#11191](https://github.com/pingcap/tidb/pull/11191) -+ 支持修改 Database/Table 的 Collate，条件限制为 Database/Table 字符集必须是 UTF8/UTF8MB4 [#11085](https://github.com/pingcap/tidb/pull/11085) -+ 修复 `CURRENT_TIMESTAMP` 作为列的默认值且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11087](https://github.com/pingcap/tidb/pull/11087) - -## TiKV - -+ 统一日志格式 [#5083](https://github.com/tikv/tikv/pull/5083) -+ 提高 region approximate size/key 在极端情况下的准确性，提升调度准确度 [#5085](https://github.com/tikv/tikv/pull/5085) - -## PD - -+ 统一日志格式 [#1625](https://github.com/pingcap/pd/pull/1625) - -## Tools - -TiDB Binlog - -+ 优化 Pump GC 策略，去掉了未被在线 drainer 消费到的 binlog 保证不清理的限制 [#663](https://github.com/pingcap/tidb-binlog/pull/663) - -TiDB Lightning - -+ 修复 SQL dump 指明的列名不是小写时导入错误的问题 [#210](https://github.com/pingcap/tidb-lightning/pull/210) - -## TiDB Ansible - -+ TiDB Dashboard 新增 `parse duration` 和 `compile duration` 监控项，用于监测 SQL 语句解析耗时和执行计划编译耗时 [#815](https://github.com/pingcap/tidb-ansible/pull/815) diff --git a/v3.0/releases/2.1.16.md b/v3.0/releases/2.1.16.md deleted file mode 100644 index f0db29e15a9f..000000000000 --- a/v3.0/releases/2.1.16.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: TiDB 2.1.16 Release Notes -category: Releases ---- - -# TiDB 2.1.16 Release Notes - -发版日期：2019 年 8 月 15 日 - -TiDB 版本：2.1.16 - -TiDB Ansible 版本：2.1.16 - -## TiDB - -+ SQL 优化器 - - 修复时间列上的等值条件 Row Count 估算不准确的问题 [#11526](https://github.com/pingcap/tidb/pull/11526) - - 修复 `TIDB_INLJ` Hint 不生效或者对非指定的表生效的问题 [#11361](https://github.com/pingcap/tidb/pull/11361) - - 将查询中的 NOT EXISTS 由 OUTER JOIN 实现方式改为 ANTI JOIN ，便于找到更优执行计划 [#11291](https://github.com/pingcap/tidb/pull/11291) - - 支持在 `SHOW` 语句中使用子查询，现在可以支持诸如 `SHOW COLUMNS FROM tbl WHERE FIELDS IN (SELECT 'a')` 的写法 [#11461](https://github.com/pingcap/tidb/pull/11461) - - 修复常量折叠优化导致 `SELECT … CASE WHEN … ELSE NULL ...` 查询结果不正确的问题 [#11441](https://github.com/pingcap/tidb/pull/11441) -+ SQL 执行引擎 - - 修复函数 DATE_ADD 在 INTERVAL 为负的情况下结果错误的问题 [#11616](https://github.com/pingcap/tidb/pull/11616) - - 修复 `DATE_ADD` 函数接受 `FLOAT`、`DOUBLE` 和 `DECIMAL` 类型的参数时，没有正确地进行类型转换而导致结果可能不正确的问题 [#11628](https://github.com/pingcap/tidb/pull/11628) - - 修复 CAST(JSON AS SIGNED) 出现 OVERFLOW 时错误信息不准确的问题 [#11562](https://github.com/pingcap/tidb/pull/11562) - - 修复在关闭 Executor 的过程中，子节点关闭返回错误时其他子节点未关闭的问题 [#11598](https://github.com/pingcap/tidb/pull/11598) - - 支持 SPLIT TABLE 语句返回切分成功的 REGION 数量，并且当部分 REGION SCATTER 在超时未完成调度时，不再返回错误，而是返回完成调度的比例 [#11487](https://github.com/pingcap/tidb/pull/11487) - - 修复 `REGEXP BINARY` 函数对大小写敏感，与 MySQL 不兼容的问题 [#11505](https://github.com/pingcap/tidb/pull/11505) - - 修复 DATE_ADD / DATE_SUB 结果中 YEAR 小于 0 或 大于 65535 时溢出导致结果没有正确返回 NULL 值的问题 [#11477](https://github.com/pingcap/tidb/pull/11477) - - 慢查询表中添加用于表示是否执行成功的 `Succ` 字段 [#11412](https://github.com/pingcap/tidb/pull/11421) - - 修复一条 SQL 语句在涉及当前时间计算时（例如 `CURRENT_TIMESTAMP` 或者 `NOW`），多次取当前时间值，结果与 MySQL不兼容的问题：现在同一条SQL语句中取当前时间时，均使用相同值 [#11392](https://github.com/pingcap/tidb/pull/11392) - - 修复 AUTO INCREMENT 列未处理 FLOAT / DOUBLE 的问题 [#11389](https://github.com/pingcap/tidb/pull/11389) - - 修复 `CONVERT_TZ` 函数在参数不合法时，没有正确返回 NULL 的问题 [#11357](https://github.com/pingcap/tidb/pull/11357) - - 修复 PARTITION BY LIST 报错的问题（仅添加语法支持，TiDB 执行时候会作为普通表创建并提供提示信息） [#11236](https://github.com/pingcap/tidb/pull/11236) - - 修复 `Mod(%)`、`Multiple(*)` 和 `Minus(-)` 返回结果为 0 时，在小数位数较多（例如 `select 0.000 % 0.11234500000000000000`）的情况下与 MySQL 位数不一致的问题 [#11353](https://github.com/pingcap/tidb/pull/11353) -+ Server - - 修复插件在 OnInit 回调中获取 Domain 为 NULL 的问题 [#11426](https://github.com/pingcap/tidb/pull/11426) - - 修复当 Schema 删除后，依然可以通过 HTTP 接口获取该 Schema 中表信息的问题 [#11586](https://github.com/pingcap/tidb/pull/11586) -+ DDL - - 禁止 DROP 自增列索引，修复因为 DROP 自增列上的索引导致自增列结果可能出错的问题 [#11402](https://github.com/pingcap/tidb/pull/11402) - - 修复列和表使用不同的 CHARSET 和 COLLATE 创建表和修改表时，列的字符集不正确的问题 [#11423](https://github.com/pingcap/tidb/pull/11423) - - 修复并行执行 “alter table ... set default...” 和其他修改此列信息的 DDL，可能导致此列的结构出错的问题 [#11374](https://github.com/pingcap/tidb/pull/11374) - - 修复当 Generated column A 依赖 Generated column B 时，使用 A 创建索引，数据回填失败的问题 [#11538](https://github.com/pingcap/tidb/pull/11538) - - 提升 ADMIN CHECK TABLE 的速度 [#11538](https://github.com/pingcap/tidb/pull/11676) - -## TiKV - -+ 访问正在关闭的 TiKV Region 时返回 Close 错误 [#4820](https://github.com/tikv/tikv/pull/4820) -+ 支持逆向 `raw_scan` 和逆向 `raw_batch_scan` 接口 [#5148](https://github.com/tikv/tikv/pull/5148) - -## Tools - -+ TiDB Binlog - - Drainer 增加 `ignore-txn-commit-ts` 配置项，用于跳过执行某些事务语句 [#697](https://github.com/pingcap/tidb-binlog/pull/697) - - 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#708](https://github.com/pingcap/tidb-binlog/pull/708) - - Drainer 增加 `node-id` 配置，用于指定固定逻辑 Drainer [#706](https://github.com/pingcap/tidb-binlog/pull/706) -+ TiDB Lightning - - 修复 2 个 checksum 同时运行的情况下，`tikv_gc_life_time` 没有正常修改回原本值的问题 [#224](https://github.com/pingcap/tidb-lightning/pull/224) - -## TiDB Ansible - -+ Spark 新增 log4j 日志配置 [#842](https://github.com/pingcap/tidb-ansible/pull/842) -+ 更新 tispark jar 包为 v2.1.2 版本 [#863](https://github.com/pingcap/tidb-ansible/pull/863) -+ 修复了 TiDB Binlog 使用 Kafka 或者 ZooKeeper 时导致生成的 Prometheus 配置文件格式错误的问题 [#845](https://github.com/pingcap/tidb-ansible/pull/845) -+ 修复执行 `rolling_update.yml` 操作时，切换 PD Leader 失效的 Bug [#888](https://github.com/pingcap/tidb-ansible/pull/888) -+ 优化滚动升级 PD 节点的逻辑，先升级 Follower 再升级 Leader，提高稳定性 [#895](https://github.com/pingcap/tidb-ansible/pull/895) diff --git a/v3.0/releases/2.1.17.md b/v3.0/releases/2.1.17.md deleted file mode 100644 index 5dd52c509daa..000000000000 --- a/v3.0/releases/2.1.17.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 2.1.17 Release Notes -category: Releases ---- - -# TiDB 2.1.17 Release Notes - -发版日期：2019 年 9 月 11 日 - -TiDB 版本：2.1.17 - -TiDB Ansible 版本：2.1.17 - -- 新特性 - - TiDB 的 `SHOW TABLE REGIONS` 语法新增 `WHERE` 条件子句 - - TiKV、PD 新增 `config-check` 功能，用于配置项检查 - - pd-ctl 新增 `remove-tomestone` 命令，支持清理 tombstone store 记录 - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 - -- 改进提升 - - PD 优化调度流程，支持主动下发调度 - - TiKV 优化启动流程，减少重启节点带来的抖动 - -- 行为变更 - - TiDB 慢日志中的 `start ts` 由最后一次重试的时间改为第一次执行的时间 - - TiDB 慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 - - TiDB 配置文件中添加 `split-region-max-num` 参数，用于调整 `SPLIT TABLE` 语法允许的最大 Region 数量，默认配置下，允许的数量由 1,000 增加至 10,000 - -## TiDB - -+ SQL 优化器 - - 修复 `EvalSubquery` 在构建 `Executor` 出现错误时，错误信息没有被正确返回的问题 [#11811](https://github.com/pingcap/tidb/pull/11811) - - 修复 Index Lookup Join 中，外表的行数大于一个 batch 时，查询的结果可能不正确的问题；扩大 Index Lookup Join 的作用范围：可以使用 `UnionScan` 作为 `IndexJoin` 的子节点 [#11843](https://github.com/pingcap/tidb/pull/11843) - - 针对统计信息的反馈过程可能产生失效 Key 的情况，`SHOW STAT_BUCKETS` 语句现在增加了失效 Key 的显示，例如：`invalid encoded key flag 252` [#12098](https://github.com/pingcap/tidb/pull/12098) -+ SQL 执行引擎 - - 修复 `CAST` 函数在进行数值类型转换时，首先将数值转换为 `UINT` 导致一些结果不正确的问题（例如，`select cast(13835058000000000000 as double)`）[#11712](https://github.com/pingcap/tidb/pull/11712) - - 修复 `DIV` 运算的被除数为 `DECIMAL` 类型且运算含有负数时，运算结果可能不正确的问题 [#11812](https://github.com/pingcap/tidb/pull/11812) - - 添加 `ConvertStrToIntStrict` 函数，修复执行 `SELECT`/`EXPLAIN` 语句时，一些字符串转换 `INT` 类型结果与 MySQL 不兼容的问题 [#11892](https://github.com/pingcap/tidb/pull/11892) - - 修复使用 `EXPLAIN ... FOR CONNECTION` 语法时，`stmtCtx` 没有正确设置导致 `Explain` 结果可能不正确的问题 [#11978](https://github.com/pingcap/tidb/pull/11978) - - 修复 `unaryMinus` 函数，当 Int 结果溢出时，返回结果类型没有为 Decimal 导致与 MySQL 不兼容的问题 [#11990](https://github.com/pingcap/tidb/pull/11990) - - 修复 `LOAD DATA` 语句执行时，计数顺序导致的 `last_insert_id()` 可能不正确的问题 [#11994](https://github.com/pingcap/tidb/pull/11994) - - 修复用户显式、隐式混合写入自增列数据时，`last_insert_id()` 可能不正确的问题 [#12001](https://github.com/pingcap/tidb/pull/12001) - - 修复一个 `JSON_UNQUOTE` 函数兼容性问题：只有在双引号（`"`）内的值需要 Unquote，例如 `SELECT JSON_UNQUOTE("\\\\")` 应当为 "`\\`"（不进行 Unquote）[#12096](https://github.com/pingcap/tidb/pull/12096) -+ Server - - TiDB 事务重试时，记录在慢日志中的 `start ts` 由最后一次重试的时间改为第一次执行的时间 [#11878](https://github.com/pingcap/tidb/pull/11878) - - 在 `LockResolver` 中添加事务的 Key 数量：当 Key 数量较少时，可以避免对整个 Region 的 Scan 操作，减小清锁的代价 [#11889](https://github.com/pingcap/tidb/pull/11889) - - 修复慢日志中，`succ` 字段值可能不正确的问题 [#11886](https://github.com/pingcap/tidb/pull/11886) - - 将慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 [#12063](https://github.com/pingcap/tidb/pull/12063) - - 修复 `Duration` 内容中包含 `-` 时（例如 `select time(‘--’)`），TiDB 解析为 EOF Error 导致连接断开的错误 [#11910](https://github.com/pingcap/tidb/pull/11910) - - 改进 `RegionCache`：当一个 Region 失效时，它将会更快地从 `RegionCache` 中移除，减少向该 Region 发送请求的个数 [#11931](https://github.com/pingcap/tidb/pull/11931) - - 修复 `oom-action = "cancel"` 时，当 `Insert Into … Select` 语句发生 OOM，OOM Panic 没有被正确处理而导致连接断开的问题 [#12126](https://github.com/pingcap/tidb/pull/12126) -+ DDL - - 为 `tikvSnapshot` 添加逆序扫描接口用于高效地查询 DDL History Job，使用该接口后 `ADMIN SHOW DDL JOBS` 的执行时间有明显降低 [#11789](https://github.com/pingcap/tidb/pull/11789) - - 改进 `CREATE TABLE ... PRE_SPLIT_REGION` 的语义：当指定 `PRE_SPLIT_REGION = N` 时，将预切分的 Region 个数由 2^(N-1) 改为 2^N [#11797](https://github.com/pingcap/tidb/pull/11797/files) - - 根据[线上负载与 Add Index 相互影响测试](https://pingcap.com/docs-cn/dev/benchmark/add-index-with-load)，调小 Add Index 后台工作线程的默认参数以避免对线上负载造成较大影响 [#11875](https://github.com/pingcap/tidb/pull/11875) - - 改进 `SPLIT TABLE` 语法的行为：当使用 `SPLIT TABLE ... REGIONS N` 对 Region 切分时，会生成 N 个数据 Region 和 1 个索引 Region [#11929](https://github.com/pingcap/tidb/pull/11929) - - 在配置文件中添加 `split-region-max-num` 参数，使得 `SPLIT TABLE` 语法允许的最大 Region 数量可调整，该参数默认值 `10000` [#12080](https://github.com/pingcap/tidb/pull/12080) - - 修复写 binlog 时，`CREATE TABLE` 语句中 `PRE_SPLIT_REGIONS` 部分没有被注释，导致语句不能被下游 MySQL 解析的问题 [#12121](https://github.com/pingcap/tidb/pull/12121) - - `SHOW TABLE … REGIONS` 和 `SHOW TABLE .. INDEX … REGIONS` 语法新增 `WHERE` 条件子句 [#12124](https://github.com/pingcap/tidb/pull/12124) -+ Monitor - - 增加监控指标 `connection_transient_failure_count`，用于统计 `tikvclient` 的 gRPC 连接错误数量 [#12092](https://github.com/pingcap/tidb/pull/12092) - -## TiKV - -- 解决某些情况下 Region 内 key 个数统计不准的问题 [#5415](https://github.com/tikv/tikv/pull/5415) -- TiKV 新增 `config-check` 选项，用于检查 TiKV 配置项是否合法 [#5391](https://github.com/tikv/tikv/pull/5391) -- 优化启动流程，减少重启节点带来的抖动 [#5277](https://github.com/tikv/tikv/pull/5277) -- 优化某些情况下解锁的流程，加速事务解锁 [#5339](https://github.com/tikv/tikv/pull/5339) -- 优化 `get_txn_commit_info` 的流程，加速事务提交 [#5062](https://github.com/tikv/tikv/pull/5062) -- 简化 Raft 相关的 log [#5425](https://github.com/tikv/tikv/pull/5425) -- 解决在某些情况下 TiKV 异常退出的问题 [#5441](https://github.com/tikv/tikv/pull/5441) - -## PD - -- PD 新增 `config-check` 选项，用于检查 PD 配置项是否合法 [#1725](https://github.com/pingcap/pd/pull/1725) -- pd-ctl 新增 `remove-tomestone` 命令，支持清理 tombstone store 记录 [#1705](https://github.com/pingcap/pd/pull/1705) -- 支持主动下发 Operator，加快调度速度 [#1686](https://github.com/pingcap/pd/pull/1686) - -## Tools - -+ TiDB Binlog - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 [#746](https://github.com/pingcap/tidb-binlog/pull/746) - - Drainer 优化内存使用，提升同步执行效率 [#735](https://github.com/pingcap/tidb-binlog/pull/735) - - Pump 修复有时候无法正常下线的 bug [#739](https://github.com/pingcap/tidb-binlog/pull/739) - - Pump 优化 LevelDB 处理逻辑，提升 GC 执行效率 [#720](https://github.com/pingcap/tidb-binlog/pull/720) - -+ TiDB Lightning - - 修复从 checkpoint 点重新导入可能会导致 tidb-lightning 崩溃的 bug [#239](https://github.com/pingcap/tidb-lightning/pull/239) - -## TiDB Ansible - -- 更新 Spark 版本为 2.4.3，同时更新 TiSpark 为兼容该 Spark 的 2.2.0 版本 [#914](https://github.com/pingcap/tidb-ansible/pull/914)，[#919](https://github.com/pingcap/tidb-ansible/pull/927) -- 修复了当远程机器密码过期时长时间连接等待的问题 [#937](https://github.com/pingcap/tidb-ansible/pull/937)，[#948](https://github.com/pingcap/tidb-ansible/pull/948) diff --git a/v3.0/releases/2.1.18.md b/v3.0/releases/2.1.18.md deleted file mode 100644 index 45b67f0e79be..000000000000 --- a/v3.0/releases/2.1.18.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: TiDB 2.1.18 Release Notes -category: Releases ---- - -# TiDB 2.1.18 Release Notes - -发版日期：2019 年 11 月 4 日 - -TiDB 版本：2.1.18 - -TiDB Ansible 版本：2.1.18 - -## TiDB - -+ SQL 优化器 - - 修复 Feedback 切分查询范围出错的问题 [#12172](https://github.com/pingcap/tidb/pull/12172) - - 修复点查中权限检查不正确的问题 [#12341](https://github.com/pingcap/tidb/pull/12341) - - 将 Limit 算子下推到 `IndexLookUpReader` 执行逻辑中，优化 `select ... limit ... offset ...` 的执行性能 [#12380](https://github.com/pingcap/tidb/pull/12380) - - 支持在 `ORDER BY`、`GROUP BY` 和 `LIMIT OFFSET` 中使用参数 [#12514](https://github.com/pingcap/tidb/pull/12514) - - 修复 partition 表上的 IndexJoin 返回错误结果的问题 [#12713](https://github.com/pingcap/tidb/pull/12713) - - 修复 TiDB 中 `str_to_date` 函数在日期字符串和格式化字符串不匹配的情况下，返回结果与 MySQL 不一致的问题 [#12757](https://github.com/pingcap/tidb/pull/12757) - - 修复当查询条件中包含 cast 函数时 outer join 被错误转化为 inner join 的问题 [#12791](https://github.com/pingcap/tidb/pull/12791) - - 修复 AntiSemiJoin 的 join 条件中错误的表达式传递 [#12800](https://github.com/pingcap/tidb/pull/12800) -+ SQL 执行引擎 - - 修复时间取整不正确的问题 (如 2019-09-11 11:17:47.999999666 应该被取整到 2019-09-11 11:17:48) [#12259](https://github.com/pingcap/tidb/pull/12259) - - 修复 `PREPARE` 语句类型没有记录在监控中的问题 [#12329](https://github.com/pingcap/tidb/pull/12329) - - 修复 `FROM_UNIXTIME` 在检查 NULL 值时 panic 的错误 [#12572](https://github.com/pingcap/tidb/pull/12572) - - 修复 `YEAR` 类型数据插入非法年份时，结果为 `NULL` 而不是 `0000` 的兼容性问题 [#12744](https://github.com/pingcap/tidb/pull/12744) - - 改进 AutoIncrement 列隐式分配时的行为，与 MySQL 自增锁的默认模式 (["consecutive" lock mode](https://dev.mysql.com/doc/refman/5.7/en/innodb-auto-increment-handling.html)) 保持一致：对于单行 Insert 语句的多个自增 AutoIncrement ID 的隐式分配，TiDB 保证分配值的连续性。该改进保证 JDBC `getGeneratedKeys()` 方法在任意场景下都能得到正确的结果。 [#12619](https://github.com/pingcap/tidb/pull/12619) - - 修复当 HashAgg 作为 Apply 子节点时查询 hang 住的问题 [#12769](https://github.com/pingcap/tidb/pull/12769) - - 修复逻辑表达式 AND / OR 在涉及类型转换时返回错误结果的问题 [#12813](https://github.com/pingcap/tidb/pull/12813) -+ Server - - 修复 `KILL TIDB QUERY` 语法对 `SLEEP()` 语句无效的问题 [#12159](https://github.com/pingcap/tidb/pull/12159) - - 修复 AUTO INCREMENT 分配 MAX int64 和 MAX uint64 没有报错的问题 [#12210](https://github.com/pingcap/tidb/pull/12210) - - 修复日志级别设置为 `ERROR` 时，慢日志不会被记录的问题 [#12373](https://github.com/pingcap/tidb/pull/12373) - - 将缓存 100 个 Schema 变更相关的表信息调整成 1024 个，且支持通过 `tidb_max_delta_schema_count` 系统变量修改 [#12515](https://github.com/pingcap/tidb/pull/12515) - - 将 SQL 的统计方式开始时间由“开始执行”改为“开始编译”，使得 SQL 性能统计更加准确 [#12638](https://github.com/pingcap/tidb/pull/12638) - - 在 TiDB 日志中添加 `set session autocommit` 的记录 [#12568](https://github.com/pingcap/tidb/pull/12568) - - 将 SQL 的开始时间记录在 `SessionVars` 中，避免计划执行时，该时间被重置 [#12676](https://github.com/pingcap/tidb/pull/12676) - - 在 `Order By`/`Group By`/`Limit Offset` 字句中支持 `?` 占位符 [#12514](https://github.com/pingcap/tidb/pull/12514) - - 慢日志中添加 `Prev_stmt` 字段，用于最后一条语句是 `COMMIT` 时输出前一条语句 [#12724](https://github.com/pingcap/tidb/pull/12724) - - 当一个显式提交的事务 `COMMIT` 时出错，在日志中记录 `COMMIT` 前一条语句 [#12747](https://github.com/pingcap/tidb/pull/12747) - - 优化在 TiDB Server 执行 SQL 时，对前一条语句的保存方式以提升性能 [#12751](https://github.com/pingcap/tidb/pull/12751) - - 修复 `skip-grant-table=true` 时，`FLUSH PRIVILEGES` 语句导致系统 Panic 的问题 [#12816](https://github.com/pingcap/tidb/pull/12816) - - 将 AutoID 的最小申请步长从 1000 增加为 30000，避免短时间大量写入时频繁请求 AutoID 造成性能瓶颈 [#12891](https://github.com/pingcap/tidb/pull/12891) - - 修复 Prepared 语句在 TiDB 发生 panic 时错误日志中未打印出错 SQL 的问题 [#12954](https://github.com/pingcap/tidb/pull/12954) - - 修复 COM_STMT_FETCH 慢日志时间记录和 MySQL 不一致问题 [#12953](https://github.com/pingcap/tidb/pull/12953) - - 当遇到写冲突时，在报错信息中添加错误码，以方便对冲突原因进行诊断 [#12878](https://github.com/pingcap/tidb/pull/12878) -+ DDL - - 为避免误操作，TiDB 默认不再允许删除列的 `AUTO INCREMENT` 属性，当确实需要删除时，请更改系统变量 `tidb_allow_remove_auto_inc`；相关文档请见：[TiDB 专用系统变量和语法](https://pingcap.com/docs-cn/v3.0/reference/configuration/tidb-server/tidb-specific-variables/) [#12146](https://github.com/pingcap/tidb/pull/12146) - - 支持 Create Table 语句中建唯一索引时带多个 Unique [#12469](https://github.com/pingcap/tidb/pull/12469) - - 修复 `CreateTable` 语句中指定外键约束时，外键表在没有指定 Database 时未能使用主表的 Database 导致报错的问题 [#12678](https://github.com/pingcap/tidb/pull/12678) - - 修复 `ADMIN CANCEL DDL JOBS` 时报 `invalid list index` 错的问题 [#12681](https://github.com/pingcap/tidb/pull/12681) -+ Monitor - - Backoff 监控添加类型，且补充之前没有统计到的 Backoff，比如 commit 时遇到的 Backoff [#12326](https://github.com/pingcap/tidb/pull/12326) - - 添加统计 Add Index 操作进度的监控 [#12389](https://github.com/pingcap/tidb/pull/12389) - -## PD - -- 修复 pd-ctl `--help` 命令输出内容 [#1772](https://github.com/pingcap/pd/pull/1772) - -## Tools - -+ TiDB Binlog - - 修复 `ALTER DATABASE` 相关 DDL 会导致 Drainer 异常退出的问题 [#770](https://github.com/pingcap/tidb-binlog/pull/770) - - 支持对 Commit binlog 查询事务状态信息，提升同步效率 [#761](https://github.com/pingcap/tidb-binlog/pull/761) - - 修复当 Drainer 的 `start_ts` 大于 Pump 中最大的 `commit_ts` 时候有可能引起 Pump panic 的问题 [#759](https://github.com/pingcap/tidb-binlog/pull/759) - -## TiDB Ansible - -- TiDB Binlog 增加 queue size 和 query histogram 监控项 [#952](https://github.com/pingcap/tidb-ansible/pull/952) -- 更新 TiDB 告警表达式 [#961](https://github.com/pingcap/tidb-ansible/pull/961) -- 新增配置文件检查功能，部署或者更新前会检查配置是否合理 [#973](https://github.com/pingcap/tidb-ansible/pull/973) -- TiDB 新增加索引速度监控项 [#987](https://github.com/pingcap/tidb-ansible/pull/987) -- 更新 TiDB Binlog 监控 Dashboard，兼容 4.6.3 版本的 Grafana [#993](https://github.com/pingcap/tidb-ansible/pull/993) diff --git a/v3.0/releases/2.1.19.md b/v3.0/releases/2.1.19.md deleted file mode 100644 index bafa841c7c20..000000000000 --- a/v3.0/releases/2.1.19.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 2.1.19 Release Notes -category: Releases ---- - -# TiDB 2.1.19 Release Notes - -发版日期：2019 年 12 月 27 日 - -TiDB 版本：2.1.19 - -TiDB Ansible 版本：2.1.19 - -## TiDB - -+ SQL 优化器 - - 优化 `select max(_tidb_rowid) from t` 的场景，避免全表扫 [#13294](https://github.com/pingcap/tidb/pull/13294) - - 修复当查询语句中赋予用户变量错误的值且将谓词下推后导致错误的输出结果 [#13230](https://github.com/pingcap/tidb/pull/13230) - - 修复更新统计信息时可能存在数据竞争，导致统计信息不准确的问题 [#13690](https://github.com/pingcap/tidb/pull/13690) - - 修复 `UPDATE` 语句中同时包含子查询和 stored generated column 时结果错误的问题；修复 `UPDATE` 语句中包含不同数据库的两个表名相同时，`UPDATE` 执行报错的问题 [#13357](https://github.com/pingcap/tidb/pull/13357) - - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14134](https://github.com/pingcap/tidb/pull/14134) - - 移除 `minAutoAnalyzeRatio` 约束使自动 `ANALYZE` 更及时 [#14013](https://github.com/pingcap/tidb/pull/14013) - - 当 `WHERE` 子句上有 `UNIQUE KEY` 的等值条件时，估算行数应该不大于 `1` [#13385](https://github.com/pingcap/tidb/pull/13385) -+ SQL 执行引擎 - - 修复 `ConvertJSONToInt` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#13036](https://github.com/pingcap/tidb/pull/13036) - - 修复查询中包含 `SLEEP` 函数时（例如 `select 1 from (select sleep(1)) t;)`），由于列裁剪导致查询中的 `sleep(1)` 失效的问题 [#13039](https://github.com/pingcap/tidb/pull/13039) - - 通过实现在 `INSERT ON DUPLICATE UPDATE` 语句中复用 `Chunk` 来降低内存开销 [#12999](https://github.com/pingcap/tidb/pull/12999) - - 给 `slow_query` 表添加事务相关的信息段 [#13129](https://github.com/pingcap/tidb/pull/13129)，如下： - - `Prewrite_time` - - `Commit_time` - - `Get_commit_ts_time` - - `Commit_backoff_time` - - `Backoff_types` - - `Resolve_lock_time` - - `Local_latch_wait_time` - - `Write_key` - - `Write_size` - - `Prewrite_region` - - `Txn_retry` - - 修复 `UPDATE` 语句中包含子查询时转换子查询出现的错误和当 `UPDATE` 的 `WHERE` 条件中包含子查询时更新失败的问题 [#13120](https://github.com/pingcap/tidb/pull/13120) - - 支持在分区表上执行 `ADMIN CHECK TABLE` [#13143](https://github.com/pingcap/tidb/pull/13143) - - 修复 `ON UPDATE CURRENT_TIMESTAMP` 作为列的属性且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#12462](https://github.com/pingcap/tidb/pull/12462) - - 修复在 `DROP/MODIFY/CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14162](https://github.com/pingcap/tidb/pull/14162) - - 修复 TiDB 开启 `Streaming` 后返回数据可能重复的问题 [#13255](https://github.com/pingcap/tidb/pull/13255) - - 修复夏令时导致的“无效时间格式”问题 [#13624](https://github.com/pingcap/tidb/pull/13624) - - 修复整型数据被转换为无符号 `Real`/`Decimal` 类型时，精度可能丢失的问题 [#13756](https://github.com/pingcap/tidb/pull/13756) - - 修复 `Quote` 函数处理 `null` 值时返回值类型出错的问题 [#13681](https://github.com/pingcap/tidb/pull/13681) - - 修复从字符串解析日期时，由于使用 `golang time.Local` 本地时区导致解析结果的时区不正确的问题 [#13792](https://github.com/pingcap/tidb/pull/13792) - - 修复 `builtinIntervalRealSig` 的实现中，由于 `binSearch` 方法不会返回 error，导致最终结果可能不正确的问题 [#13768](https://github.com/pingcap/tidb/pull/13768) - - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14009](https://github.com/pingcap/tidb/pull/14009) - - 修复 `sum(distinct)` 函数输出结果不正确的问题 [#13041](https://github.com/pingcap/tidb/pull/13041) - - 修复由于对 `jsonUnquoteFunction` 函数的返回类型长度赋值不正确的值，导致在 `union` 中同位置数据上进行 `cast` 转换时会截断数据的问题 [#13645](https://github.com/pingcap/tidb/pull/13645) - - 修复由于权限检查过于严格导致设置密码失败的问题 [#13805](https://github.com/pingcap/tidb/pull/13805) -+ Server - - 修复 `KILL CONNECTION` 可能出现 goroutine 泄漏的问题 [#13252](https://github.com/pingcap/tidb/pull/13252) - - 新增通过 HTTP API 的 `info/all` 接口获取所有 TiDB 节点的 binlog 状态功能 [#13188](https://github.com/pingcap/tidb/pull/13188) - - 修复在 Windows 上 build TiDB 项目失败的问题 [#13650](https://github.com/pingcap/tidb/pull/13650) - - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13904](https://github.com/pingcap/tidb/pull/13904) - - 修复通过 Go1.13 版本编译的二进制程序 `plugin` 不能正常运行的问题 [#13527](https://github.com/pingcap/tidb/pull/13527) -+ DDL - - 新增创建表时如果表包含 `COLLATE` 则列的 `COLLATE` 使用表的 `COLLATE` [#13190](https://github.com/pingcap/tidb/pull/13190) - - 新增创建表时限制索引名字的长度的功能 [#13311](https://github.com/pingcap/tidb/pull/13311) - - 修复 rename table 时未检查表名长度的问题 [#13345](https://github.com/pingcap/tidb/pull/13345) - - 新增 `BIT` 列的宽度范围检查的功能 [#13511](https://github.com/pingcap/tidb/pull/13511) - - 优化 `change/modify column` 的输出的错误信息，让人更容易理解 [#13798](https://github.com/pingcap/tidb/pull/13798) - - 修复执行 `drop column` 操作且下游 Drainer 还没有执行此 `drop column` 操作时，下游可能会收到不带此列的 DML 的问题 [#13974](https://github.com/pingcap/tidb/pull/13974) - -## TiKV - -+ Raftstore - - 修复 Region merge 和应用 Compact log 过程中系统若有重启，当重启时由于未正确设置 `is_merging` 的值导致系统 panic 的问题 [#5884](https://github.com/tikv/tikv/pull/5884) -+ Importer - - 取消 gRPC 的消息长度限制 [#5809](https://github.com/tikv/tikv/pull/5809) - -## PD - -- 提升获取 Region 列表的 HTTP API 性能 [#1988](https://github.com/pingcap/pd/pull/1988) -- 升级 etcd，修复 etcd PreVote 无法选出 leader 的问题（升级后无法降级） [#2052](https://github.com/pingcap/pd/pull/2052) - -## Tools - -+ TiDB Binlog - - 优化通过 binlogctl 输出的节点状态信息 [#777](https://github.com/pingcap/tidb-binlog/pull/777) - - 修复当 Drainer 过滤配置为 `nil` 时 panic 的问题 [#802](https://github.com/pingcap/tidb-binlog/pull/802) - - 优化 Pump 的 `Graceful` 退出方式 [#825](https://github.com/pingcap/tidb-binlog/pull/825) - - 新增 Pump 写 binlog 数据时更详细的监控指标 [#830](https://github.com/pingcap/tidb-binlog/pull/830) - - 优化 Drainer 在执行 DDL 后刷新表结构信息的逻辑 [#836](https://github.com/pingcap/tidb-binlog/pull/836) - - 修复 Pump 在没有收到 DDL 的 commit binlog 时该 binlog 被忽略的问题 [#855](https://github.com/pingcap/tidb-binlog/pull/855) - -## TiDB Ansible - -- TiDB 服务 `Uncommon Error OPM` 监控项更名为 `Write Binlog Error` 并增加对应的告警 [#1038](https://github.com/pingcap/tidb-ansible/pull/1038) -- 升级 TiSpark 版本为 2.1.8 [#1063](https://github.com/pingcap/tidb-ansible/pull/1063) diff --git a/v3.0/releases/2.1.2.md b/v3.0/releases/2.1.2.md deleted file mode 100644 index 5ec9c9b9f137..000000000000 --- a/v3.0/releases/2.1.2.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.1.2 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.2/'] ---- - -# TiDB 2.1.2 Release Notes - -2018 年 12 月 22 日，TiDB 发布 2.1.2 版，TiDB Ansible 相应发布 2.1.2 版本。该版本在 2.1.1 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 兼容 Kafka 版本的 TiDB Binlog [#8747](https://github.com/pingcap/tidb/pull/8747) -- 完善滚动升级下 TiDB 的退出机制 [#8707](https://github.com/pingcap/tidb/pull/8707) -- 修复在某些情况下为 generated column 增加索引 panic 的问题 [#8676](https://github.com/pingcap/tidb/pull/8676) -- 修复在某些情况下语句有 `TIDB_SMJ Hint` 的时候优化器无法找到正确执行计划的问题 [#8729](https://github.com/pingcap/tidb/pull/8729) -- 修复在某些情况下 `AntiSemiJoin` 返回错误结果的问题 [#8730](https://github.com/pingcap/tidb/pull/8730) -- 增强 `utf8` 字符集的有效字符检查 [#8754](https://github.com/pingcap/tidb/pull/8754) -- 修复事务中先写后读的情况下时间类型字段可能返回错误结果的问题 [#8746](https://github.com/pingcap/tidb/pull/8746) - -## PD - -- 修复 Region Merge 相关的 Region 信息更新问题 [#1377](https://github.com/pingcap/pd/pull/1377) - -## TiKV - -- 支持以日 (`d`) 为时间单位的配置格式，并解决配置兼容性问题 [#3931](https://github.com/tikv/tikv/pull/3931) -- 修复 Approximate Size Split 可能会 panic 的问题 [#3942](https://github.com/tikv/tikv/pull/3942) -- 修复两个 Region merge 相关问题 [#3822](https://github.com/tikv/tikv/pull/3822)，[#3873](https://github.com/tikv/tikv/pull/3873) - -## Tools - -+ TiDB Lightning - - 支持最小 TiDB 集群版本为 2.1.0 - - 修复解析包含 JSON 类型数据的文件内容出错 [#144](https://github.com/pingcap/tidb-tools/issues/144) - - 修复使用 checkpoint 重启后 `Too many open engines` 错误 -+ TiDB Binlog - - 消除了 Drainer 往 Kafka 写数据的一些瓶颈点 - - TiDB 支持写 [Kafka 版本的 TiDB Binlog](https://github.com/pingcap/docs-cn/blob/master/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md) diff --git a/v3.0/releases/2.1.3.md b/v3.0/releases/2.1.3.md deleted file mode 100644 index 0f11fd6c94a8..000000000000 --- a/v3.0/releases/2.1.3.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: TiDB 2.1.3 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.3/'] ---- - -# TiDB 2.1.3 Release Notes - -2019 年 01 月 28 日，TiDB 发布 2.1.3 版，TiDB Ansible 相应发布 2.1.3 版本。相比 2.1.2 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复某些情况下 Prepared Plan Cache panic 的问题 [#8826](https://github.com/pingcap/tidb/pull/8826) - - 修复在有前缀索引的某些情况下，Range 计算错误的问题 [#8851](https://github.com/pingcap/tidb/pull/8851) - - 当 `SQL_MODE` 不为 STRICT 时, `CAST(str AS TIME(N))` 在 `str` 为非法的 TIME 格式的字符串时返回 NULL [#8966](https://github.com/pingcap/tidb/pull/8966) - - 修复某些情况下 Generated Column 在 Update 中 Panic 的问题 [#8980](https://github.com/pingcap/tidb/pull/8980) - - 修复统计信息直方图某些情况下上界溢出的问题 [#8989](https://github.com/pingcap/tidb/pull/8989) - - 支持对 `_tidb_rowid` 构造查询的 Range，避免全表扫，减轻集群压力 [#9059](https://github.com/pingcap/tidb/pull/9059) - - `CAST(AS TIME)` 在精度太大的情况下返回一个错误 [#9058](https://github.com/pingcap/tidb/pull/9058) - - 允许把 `Sort Merge Join` 用于笛卡尔积 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 修复统计信息的 worker 在某些情况下 panic 之后无法恢复的问题 [#9085](https://github.com/pingcap/tidb/pull/9085) - - 修复某些情况下 `Sort Merge Join` 结果不正确的问题 [#9046](https://github.com/pingcap/tidb/pull/9046) - - 支持在 `CASE` 子句返回 JSON 类型 [#8355](https://github.com/pingcap/tidb/pull/8355) -+ Server - - 当语句中有非 TiDB hint 的注释时返回警告，而不是错误 [#8766](https://github.com/pingcap/tidb/pull/8766) - - 验证设置的 TIMEZONE 的合法性 [#8879](https://github.com/pingcap/tidb/pull/8879) - - 优化 Metrics 项 `QueryDurationHistogram`，展示更多语句的类型 [#8875](https://github.com/pingcap/tidb/pull/8875) - - 修复 bigint 某些情况下下界溢出的问题 [#8544](https://github.com/pingcap/tidb/pull/8544) - - 支持 `ALLOW_INVALID_DATES` SQL mode [#9110](https://github.com/pingcap/tidb/pull/9110) -+ DDL - - 修复一个 RENAME TABLE 的兼容性问题，保持行为跟 MySQL 一致 [#8808](https://github.com/pingcap/tidb/pull/8808) - - 支持 `ADD INDEX` 的并发修改即时生效 [#8786](https://github.com/pingcap/tidb/pull/8786) - - 修复在 `ADD COLUMN` 的过程中，某些情况 Update 语句 panic 的问题 [#8906](https://github.com/pingcap/tidb/pull/8906) - - 修复某些情况下并发创建 Table Partition 的问题 [#8902](https://github.com/pingcap/tidb/pull/8902) - - 支持把 `utf8` 字符集转换为 `utf8mb4` 字符集 [#8951](https://github.com/pingcap/tidb/pull/8951) [#9152](https://github.com/pingcap/tidb/pull/9152) - - 处理 Shard Bits 溢出的问题 [#8976](https://github.com/pingcap/tidb/pull/8976) - - 支持 `SHOW CREATE TABLE` 输出列的字符集 [#9053](https://github.com/pingcap/tidb/pull/9053) - - 修复 varchar 最大支持字符数在 `utf8mb4` 下限制的问题 [#8818](https://github.com/pingcap/tidb/pull/8818) - - 支持 `ALTER TABLE TRUNCATE TABLE PARTITION` [#9093](https://github.com/pingcap/tidb/pull/9093) - - 修复创建表的时候缺省字符集推算的问题 [#9147](https://github.com/pingcap/tidb/pull/9147) - -## PD - -- 修复 Leader 选举相关的 Watch 问题 [#1396](https://github.com/pingcap/pd/pull/1396) - -## TiKV - -- 支持了使用 HTTP 方式获取监控信息 [#3855](https://github.com/tikv/tikv/pull/3855) -- 修复 `data_format` 遇到 NULL 时的问题 [#4075](https://github.com/tikv/tikv/pull/4075) -- 添加验证 Scan 请求的边界合法性 [#4124](https://github.com/tikv/tikv/pull/4124) - -## Tools - -+ TiDB Binlog - - 修复在启动或者重启时 `no available pump` 的问题 [#157](https://github.com/pingcap/tidb-tools/pull/158) - - 开启 Pump client log 输出 [#165](https://github.com/pingcap/tidb-tools/pull/165) - - 修复表只有 unique key 没有 primary key 的情况下，unique key 包含 NULL 值导致数据更新不一致的问题 diff --git a/v3.0/releases/2.1.4.md b/v3.0/releases/2.1.4.md deleted file mode 100644 index 8dfdeed01f93..000000000000 --- a/v3.0/releases/2.1.4.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB 2.1.4 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.4/'] ---- - -# TiDB 2.1.4 Release Notes - -2019 年 2 月 15 日，TiDB 发布 2.1.4 版，TiDB Ansible 相应发布 2.1.4 版本。相比 2.1.3 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复 `VALUES` 函数未正确处理 FLOAT 类型的问题 [#9223](https://github.com/pingcap/tidb/pull/9223) - - 修复某些情况下 `CAST` 浮点数成字符串结果不正确的问题 [#9227](https://github.com/pingcap/tidb/pull/9227) - - 修复 `FORMAT` 函数在某些情况下结果不正确的问题 [#9235](https://github.com/pingcap/tidb/pull/9235) - - 修复某些情况下处理 Join 查询时 panic 的问题 [#9264](https://github.com/pingcap/tidb/pull/9264) - - 修复 `VALUES` 函数未正确处理 ENUM 类型的问题 [#9280](https://github.com/pingcap/tidb/pull/9280) - - 修复 `DATE_ADD`/`DATE_SUB` 在某些情况下结果不正确的问题 [#9284](https://github.com/pingcap/tidb/pull/9284) -+ Server - - 优化 reload privilege success 日志，将其调整为 DEBUG 级别 [#9274](https://github.com/pingcap/tidb/pull/9274) -+ DDL - - `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 变成 GLOBAL 变量 [#9134](https://github.com/pingcap/tidb/pull/9134) - - 修复某些异常情况下，在 Generated column 增加索引导致的 Bug [#9289](https://github.com/pingcap/tidb/pull/9289) - -## TiKV - -- 修复在 TiKV 关闭时可能发生重复写的问题 [#4146](https://github.com/tikv/tikv/pull/4146) -- 修复某些情况下 event listener 结果处理异常的问题 [#4132](https://github.com/tikv/tikv/pull/4132) - -## Tools - -+ Lightning - - 优化内存使用 [#107](https://github.com/pingcap/tidb-lightning/pull/107)，[#108](https://github.com/pingcap/tidb-lightning/pull/108) - - 去掉 dump files 的 chunk 划分，减少对 dump files 的一次额外解析 [#109](https://github.com/pingcap/tidb-lightning/pull/109) - - 限制读取 dump files 的 I/O 并发，避免过多的 cache miss 导致性能下降 [#110](https://github.com/pingcap/tidb-lightning/pull/110) - - 对单个表实现 batch 导入，提高导入的稳定性 [#110](https://github.com/pingcap/tidb-lightning/pull/113) - - TiKV 在 import 模式下开启 auto compactions [#4199](https://github.com/tikv/tikv/pull/4199) - - 增加禁用 TiKV periodic Level-1 compaction 参数，因为当 TiKV 集群为 2.1.4 或更高版本时，在导入模式下会自动执行 Level-1 compaction [#119](https://github.com/pingcap/tidb-lightning/pull/119) - - 限制 import engines 数量，避免过大占用 importer 磁盘空间 [#119](https://github.com/pingcap/tidb-lightning/pull/119) -+ 数据同步对比统计 (sync-diff-inspector) 支持使用 TiDB 统计信息来划分 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) \ No newline at end of file diff --git a/v3.0/releases/2.1.5.md b/v3.0/releases/2.1.5.md deleted file mode 100644 index 055e8614eedc..000000000000 --- a/v3.0/releases/2.1.5.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 2.1.5 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.5/'] ---- - -# TiDB 2.1.5 Release Notes - -2019 年 2 月 28 日，TiDB 发布 2.1.5 版，TiDB Ansible 相应发布 2.1.5 版本。相比 2.1.4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 当列的字符集信息和表的字符集信息相同时，`SHOW CREATE TABLE` 不再打印列的字符集信息，使其结果更加兼容 MySQL [#9306](https://github.com/pingcap/tidb/pull/9306) - - 将 `Sort` 算子中的表达计算抽取出来用一个 `Project` 算子完成，简化 `Sort` 算子的计算逻辑，修复某些情况下 `Sort` 算子结果不正确或者 panic 的问题 [#9319](https://github.com/pingcap/tidb/pull/9319) - - 移除 `Sort` 算子中的数值为常量的排序字段 [#9335](https://github.com/pingcap/tidb/pull/9335)，[#9440](https://github.com/pingcap/tidb/pull/9440) - - 修复向无符号整数列插入数据时数据溢出的问题 [#9339](https://github.com/pingcap/tidb/pull/9339) - - 目标 binary 的长度超过 `max_allowed_packet` 时，将 `cast_as_binary` 设置为 `NULL` [#9349](https://github.com/pingcap/tidb/pull/9349) - - 优化 `IF` 和 `IFNULL` 的常量折叠过程 [#9351](https://github.com/pingcap/tidb/pull/9351) - - 使用 skyline pruning 优化 TiDB 的索引选择，增加简单查询的稳定性 [#9356](https://github.com/pingcap/tidb/pull/9356) - - 支持对析取范式计算选择率 [#9405](https://github.com/pingcap/tidb/pull/9405) - - 修复 `!=ANY()` 和 `=ALL()` 在某些情况下 SQL 查询结果不正确的问题 [#9403](https://github.com/pingcap/tidb/pull/9403) - - 修复执行 Merge Join 操作的两个表的 Join Key 类型不同时结果可能不正确或者 panic 的问题 [#9438](https://github.com/pingcap/tidb/pull/9438) - - 修复某些情况下 `RAND()` 函数结果和 MySQL 不兼容的问题 [#9446](https://github.com/pingcap/tidb/pull/9446) - - 重构 Semi Join 对 `NULL` 值和空结果集的处理逻辑，使其返回正确的结果，更加兼容 MySQL [#9449](https://github.com/pingcap/tidb/pull/9449) -+ Server - - 增加系统变量 `tidb_constraint_check_in_place`，在 `INSERT` 语句执行时即检查数据的唯一性约束 [#9401](https://github.com/pingcap/tidb/pull/9401) - - 修复系统变量 `tidb_force_priority` 的值和配置文件中的设置的值不一致的问题 [#9347](https://github.com/pingcap/tidb/pull/9347) - - 在 general log 中增加 “current_db” 字段打印当前使用的数据库 [#9346](https://github.com/pingcap/tidb/pull/9346) - - 增加通过表 ID 来获取表信息的 HTTP API [#9408](https://github.com/pingcap/tidb/pull/9408) - - 修复 `LOAD DATA` 在某些情况下导入数据不正确的问题 [#9414](https://github.com/pingcap/tidb/pull/9414) - - 修复某些情况下，客户端建立连接慢的问题 [#9451](https://github.com/pingcap/tidb/pull/9451) -+ DDL - - 修复撤销 `DROP COLUMN` 操作中的一些问题 [#9352](https://github.com/pingcap/tidb/pull/9352) - - 修复撤销 `DROP`/`ADD` 分区表操作中的一些问题 [#9376](https://github.com/pingcap/tidb/pull/9376) - - 修复某些情况下 `ADMIN CHECK TABLE` 误报数据索引不一致的问题 [#9399](https://github.com/pingcap/tidb/pull/9399) - - 修复 `TIMESTAMP` 类型的默认值在时区上的一些问题 [#9108](https://github.com/pingcap/tidb/pull/9108) - -## PD - -- `GetAllStores` 接口提供了 `exclude_tombstone_stores` 选项，将 Tombstone store 从返回结果中去除 [#1444](https://github.com/pingcap/pd/pull/1444) - -## TiKV - -- 修复了某些情况下 Importer 导入失败的问题 [#4223](https://github.com/tikv/tikv/pull/4223) -- 修复了某些情况下 "key not in region" 错误 [#4125](https://github.com/tikv/tikv/pull/4125) -- 修复了某些情况下 Region merge 导致 panic 的问题 [#4235](https://github.com/tikv/tikv/pull/4235) -- 添加了详细的 `StoreNotMatch` 错误信息 [#3885](https://github.com/tikv/tikv/pull/3885) - -## Tools - -+ Lightning - - 集群中有 Tombstone store 时 Lightning 不会再报错退出 [#4223](https://github.com/tikv/tikv/pull/4223) -+ TiDB Binlog - - 修正 DDL Binlog 同步方案，确保 DDL 同步的正确性 [#9304](https://github.com/pingcap/tidb/issues/9304) diff --git a/v3.0/releases/2.1.6.md b/v3.0/releases/2.1.6.md deleted file mode 100644 index 63f6bcabdeeb..000000000000 --- a/v3.0/releases/2.1.6.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.1.6 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.6/'] ---- - -# TiDB 2.1.6 Release Notes - -2019 年 3 月 15 日，TiDB 发布 2.1.6 版，TiDB Ansible 相应发布 2.1.6 版本。相比 2.1.5 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 当两个表在 `TIDB_INLJ` 的 Hint 中时，基于代价来选择外表 [#9615](https://github.com/pingcap/tidb/pull/9615) - - 修复在某些情况下，没有正确选择 IndexScan 的问题 [#9587](https://github.com/pingcap/tidb/pull/9587) - - 修复聚合函数在子查询里面的检查跟 MySQL 不兼容的行为 [#9551](https://github.com/pingcap/tidb/pull/9551) - - 使 `show stats_histograms` 语句只输出合法的列，避免 Panic [#9502](https://github.com/pingcap/tidb/pull/9502) -+ Server - - 支持变量 `log_bin`，用于开启/关闭 Binlog [#9634](https://github.com/pingcap/tidb/pull/9634) - - 在事务中添加一个防御性检查，避免错误的事务提交 [#9559](https://github.com/pingcap/tidb/pull/9559) - - 修复设置变量导致的 Panic 的问题 [#9539](https://github.com/pingcap/tidb/pull/9539) -+ DDL - - 修复 Create Table Like 语句在某些情况导致 Panic 的问题 [#9652](https://github.com/pingcap/tidb/pull/9652) - - 打开 etcd client 的 AutoSync 特性，防止某些情况下 TiDB 无法连接上 etcd 的问题 [#9600](https://github.com/pingcap/tidb/pull/9600) - -## TiKV - -- 修复在某些情况下解析 protobuf 失败导致 `StoreNotMatch` 错误的问题 [#4303](https://github.com/tikv/tikv/pull/4303) - -## Tools - -+ Lightning - - importer 的默认的 region-split-size 变更为 512 MiB [#4369](https://github.com/tikv/tikv/pull/4369) - - 保存原先在内存中的中间状态的 SST 到磁盘，减少内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 限制 RocksDB 的内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 修复 Region 还没有调度完成时进行 scatter 的问题 [#4369](https://github.com/tikv/tikv/pull/4369) - - 将大表的数据和索引分离导入，在分批导入时能有效降低耗时 [#132](https://github.com/pingcap/tidb-lightning/pull/132) - - 支援 CSV [#111](https://github.com/pingcap/tidb-lightning/pull/111) - - 修复库名中含非英数字符时导入失败的错误 [#9547](https://github.com/pingcap/tidb/pull/9547) diff --git a/v3.0/releases/2.1.7.md b/v3.0/releases/2.1.7.md deleted file mode 100644 index 4970bed87b89..000000000000 --- a/v3.0/releases/2.1.7.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: TiDB 2.1.7 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.7/'] ---- - -# TiDB 2.1.7 Release Notes - -发版日期：2019 年 3 月 28 日 - -TiDB 版本：2.1.7 - -TiDB Ansible 版本：2.1.7 - -## TiDB - -- 修复因 DDL 被取消导致升级程序时启动时间变长问题 [#9768](https://github.com/pingcap/tidb/pull/9768) -- 修复配置项 `check-mb4-value-in-utf8` 在 `config.example.toml` 中位置错误的问题 [#9852](https://github.com/pingcap/tidb/pull/9852) -- 提升内置函数 `str_to_date` 跟 MySQL 的兼容性 [#9817](https://github.com/pingcap/tidb/pull/9817) -- 修复内置函数 `last_day` 的兼容性问题 [#9750](https://github.com/pingcap/tidb/pull/9750) -- `infoschema.tables` 添加 `tidb_table_id` 列，方便通过 SQL 语句获取 `table_id`，新增 `tidb_indexes` 系统表管理 Table 与 Index 之间的关系 [#9862](https://github.com/pingcap/tidb/pull/9862) -- 增加 Table Partition 定义为空的检查 [#9663](https://github.com/pingcap/tidb/pull/9663) -- 将 `Truncate Table` 需要的权限由删除权限变为删表权限，与 MySQL 保持一致 [#9876](https://github.com/pingcap/tidb/pull/9876) -- 支持在 `DO` 语句中使用子查询 [#9877](https://github.com/pingcap/tidb/pull/9877) -- 修复变量 `default_week_format` 在 week 函数中不生效的问题 [#9753](https://github.com/pingcap/tidb/pull/9753) -- 支持插件机制 [#9880](https://github.com/pingcap/tidb/pull/9880)，[#9888](https://github.com/pingcap/tidb/pull/9888) -- 支持使用系统变量 `log_bin` 查看 binlog 开启状况 [#9634](https://github.com/pingcap/tidb/pull/9634) -- 支持使用 SQL 语句查看 Pump/Drainer 状态 [#9896](https://github.com/pingcap/tidb/pull/9896) -- 修复升级时对 utf8 检查 mb4 字符的兼容性 [#9887](https://github.com/pingcap/tidb/pull/9887) -- 修复某些情况下对 JSON 数据的聚合函数在计算过程中 Panic 的问题 [#9927](https://github.com/pingcap/tidb/pull/9927) - -## PD - -- 修改副本数为 1 时 balance-region 无法迁移 leader 问题 [#1462](https://github.com/pingcap/pd/pull/1462) - -## Tools - -- 支持 binlog 同步 generated column [#491](https://github.com/pingcap/tidb-binlog/pull/491) - -## TiDB Ansible - -- Prometheus 监控数据默认保留时间改成 30d diff --git a/v3.0/releases/2.1.8.md b/v3.0/releases/2.1.8.md deleted file mode 100644 index 0916143beaeb..000000000000 --- a/v3.0/releases/2.1.8.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: TiDB 2.1.8 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.8/'] ---- - -# TiDB 2.1.8 Release Notes - -发版日期：2019 年 4 月 12 日 - -TiDB 版本：2.1.8 - -TiDB Ansible 版本：2.1.8 - -## TiDB - -- 修复 `GROUP_CONCAT` 函数在参数存在 NULL 值情况下与 MySQL 处理逻辑不兼容的问题 [#9930](https://github.com/pingcap/tidb/pull/9930) -- 修复在 Distinct 模式下 decimal 类型值之间相等比较的问题 [#9931](https://github.com/pingcap/tidb/pull/9931) -- 修复 `SHOW FULL COLUMNS` 语句在 date，datetime，timestamp 类型的 Collation 的兼容性问题 - - [#9938](https://github.com/pingcap/tidb/pull/9938) - - [#10114](https://github.com/pingcap/tidb/pull/10114) -- 修复过滤条件存在关联列的时候统计信息估算行数不准确的问题 [#9937](https://github.com/pingcap/tidb/pull/9937) -- 修复 `DATE_ADD` 跟 `DATE_SUB` 函数的兼容性问题 - - [#9963](https://github.com/pingcap/tidb/pull/9963) - - [#9966](https://github.com/pingcap/tidb/pull/9966) -- `STR_TO_DATE` 函数支持格式 `%H`，提升兼容性 [#9964](https://github.com/pingcap/tidb/pull/9964) -- 修复 `GROUP_CONCAT` 函数在 group by 唯一索引的情况下结果错误的问题 [#9969](https://github.com/pingcap/tidb/pull/9969) -- 当 Optimizer Hints 存在不匹配的表名的时候返回 warning [#9970](https://github.com/pingcap/tidb/pull/9970) -- 统一日志格式规范，利于工具收集分析 [日志规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md) -- 修复大量 NULL 值导致统计信息估算不准确的问题 [#9979](https://github.com/pingcap/tidb/pull/9979) -- 修复 TIMESTAMP 类型默认值为边界值的时候报错的问题 [#9987](https://github.com/pingcap/tidb/pull/9987) -- 检查设置 `time_zone` 值的合法性 [#10000](https://github.com/pingcap/tidb/pull/10000) -- 支持时间格式 `2019.01.01` [#10001](https://github.com/pingcap/tidb/pull/10001) -- 修复某些情况下 `EXPLAIN` 结果中行数估计错误显示的问题 [#10044](https://github.com/pingcap/tidb/pull/10044) -- 修复 `KILL TIDB [session id]` 某些情况下无法快速停止语句执行的问题 [#9976](https://github.com/pingcap/tidb/pull/9976) -- 修复常量过滤条件在某些情况中谓词下推的问题 [#10049](https://github.com/pingcap/tidb/pull/10049) -- 修复某些情况下 READ-ONLY 语句没有被当成 READ-ONLY 来处理的问题 [#10048](https://github.com/pingcap/tidb/pull/10048) - -## PD - -- 修复 Scatter Region 产生无效 Operator Step 的问题 [#1482](https://github.com/pingcap/pd/pull/1482) -- 修复 store 读热点的 key 统计不正确问题 [#1487](https://github.com/pingcap/pd/pull/1487) -- 修复 Region Merge Operator 超时时间过短的问题 [#1495](https://github.com/pingcap/pd/pull/1495) -- 添加 PD server 端处理 TSO 请求的耗时 metrics [#1502](https://github.com/pingcap/pd/pull/1502) - -## TiKV - -- 修复读流量统计错误的问题 [#4441](https://github.com/tikv/tikv/pull/4441) -- 修复 Region 数过多的情况下 raftstore 的性能问题 [#4484](https://github.com/tikv/tikv/pull/4484) -- 调整当 level 0 SST 数量超过 `level_zero_slowdown_writes_trigger/2` 时不再继续 ingest file [#4464](https://github.com/tikv/tikv/pull/4464) - -## Tools - -- Lightning 优化导入表的顺序，按照表的数据大小顺序进行导入，减少导入过程中大表执行 `Checksum` 和 `Analyze` 对集群的影响，并且提高 `Checksum` 和 `Analyze` 的成功率 [#156](https://github.com/pingcap/tidb-lightning/pull/156) -- 提升 Lightning encode SQL 性能，性能提升 50%，直接解析数据源文件内容成 TiDB 的 `types.Datum`，省去 KV encoder 的多余解析工作 [#145](https://github.com/pingcap/tidb-lightning/pull/145) -- TiDB Binlog Pump 新增 `storage.sync-log` 配置项，支持 Pump 本地存储异步刷盘 [#529](https://github.com/pingcap/tidb-binlog/pull/529) -- TiDB Binlog Pump 和 Drainer 之间通讯支持流量压缩 [#530](https://github.com/pingcap/tidb-binlog/pull/530) -- TiDB Binlog Drainer 新增 `syncer.sql-mode` 配置项，支持使用不同 `sql-mode` 解析 DDL query [#513](https://github.com/pingcap/tidb-binlog/pull/513) -- TiDB Binlog Drainer 新增 `syncer.ignore-table` 配置项，支持过滤不需要同步的表 [#526](https://github.com/pingcap/tidb-binlog/pull/526) - -## TiDB Ansible - -- 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 [#734](https://github.com/pingcap/tidb-ansible/pull/734) -- 添加检测系统是否支持 `epollexclusive` [#728](https://github.com/pingcap/tidb-ansible/pull/728) -- 增加滚动升级版本限制，不允许从 2.0.1 及以下版本滚动升级到 2.1 及以上版本 [#728](https://github.com/pingcap/tidb-ansible/pull/728) diff --git a/v3.0/releases/2.1.9.md b/v3.0/releases/2.1.9.md deleted file mode 100644 index 95c499972a07..000000000000 --- a/v3.0/releases/2.1.9.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: TiDB 2.1.9 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1.9/'] ---- - -# TiDB 2.1.9 Release Notes - -发版日期：2019 年 5 月 6 日 - -TiDB 版本：2.1.9 - -TiDB Ansible 版本：2.1.9 - -## TiDB - -- 修复 `MAKETIME` 函数在 unsigned 类型溢出时的兼容性 [#10089](https://github.com/pingcap/tidb/pull/10089) -- 修复常量折叠在某些情况下导致的栈溢出 [#10189](https://github.com/pingcap/tidb/pull/10189) -- 修复 Update 在某些有别名的情况下权限检查的问题 [#10157](https://github.com/pingcap/tidb/pull/10157) [#10326](https://github.com/pingcap/tidb/pull/10326) -- 追踪以及控制 DistSQL 中的内存使用 [#10197](https://github.com/pingcap/tidb/pull/10197) -- 支持指定 collation 为 utf8mb4_0900_ai_ci [#10201](https://github.com/pingcap/tidb/pull/10201) -- 修复主键为 Unsigned 类型的时候，MAX 函数结果错误的问题 [#10209](https://github.com/pingcap/tidb/pull/10209) -- 修复在非 Strict SQL Mode 下可以插入 NULL 值到 NOT NULL 列的问题 [#10254](https://github.com/pingcap/tidb/pull/10254) -- 修复 COUNT 函数在 DISTINCT 有多列的情况下结果错误的问题 [#10270](https://github.com/pingcap/tidb/pull/10270) -- 修复 LOAD DATA 解析不规则的 CSV 文件时候 Panic 的问题 [#10269](https://github.com/pingcap/tidb/pull/10269) -- 忽略 Index Lookup Join 中内外 join key 类型不一致的时候出现的 overflow 错误 [#10244](https://github.com/pingcap/tidb/pull/10244) -- 修复某些情况下错误判定语句为 point-get 的问题 [#10299](https://github.com/pingcap/tidb/pull/10299) -- 修复某些情况下时间类型未转换时区导致的结果错误问题 [#10345](https://github.com/pingcap/tidb/pull/10345) -- 修复 TiDB 字符集在某些情况下大小写比较不一致的问题 [#10354](https://github.com/pingcap/tidb/pull/10354) -- 支持控制算子返回的行数 [#9166](https://github.com/pingcap/tidb/issues/9166) - - Selection & Projection [#10110](https://github.com/pingcap/tidb/pull/10110) - - StreamAgg & HashAgg [#10133](https://github.com/pingcap/tidb/pull/10133) - - TableReader & IndexReader & IndexLookup [#10169](https://github.com/pingcap/tidb/pull/10169) -- 慢日志改进 - - 增加 SQL Digest 用于区分同类 SQL [#10093](https://github.com/pingcap/tidb/pull/10093) - - 增加慢语句使用的统计信息的版本信息 [#10220](https://github.com/pingcap/tidb/pull/10220) - - 输出语句内存使用量 [#10246](https://github.com/pingcap/tidb/pull/10246) - - 调整 Coprocessor 相关信息的输出格式，让其能被 pt-query-digest 解析 [#10300](https://github.com/pingcap/tidb/pull/10300) - - 修复慢语句中带有 `#` 字符的问题 [#10275](https://github.com/pingcap/tidb/pull/10275) - - 增加一些信息的列到慢查询的内存表 [#10317](https://github.com/pingcap/tidb/pull/10317) - - 将事务提交时间算入慢语句执行时间 [#10310](https://github.com/pingcap/tidb/pull/10310) - - 修复某些时间格式无法被 pt-query-digest 解析的问题 [#10323](https://github.com/pingcap/tidb/pull/10323) - -## PD - -- 支持 GetOperator 服务 [#1514](https://github.com/pingcap/pd/pull/1514) - -## TiKV - -- 修复在 transfer leader 时非预期的 quorum 变化 [#4604](https://github.com/tikv/tikv/pull/4604) - -## Tools - -- TiDB Binlog - - 修复 unsigned int 类型的主键列的 binlog 数据为负数，造成同步出错中断的问题 [#574](https://github.com/pingcap/tidb-binlog/pull/574) - - 删除下游是 `pb` 时的压缩选项，修改下游名字 `pb` 成 `file` [#597](https://github.com/pingcap/tidb-binlog/pull/575) - - 修复 2.1.7 引入的 Reparo 生成错误 update 语句的 bug [#576](https://github.com/pingcap/tidb-binlog/pull/576) -- TiDB Lightning - - 修复 parser 解析 bit 类型的 column 数据错误的 bug [#164](https://github.com/pingcap/tidb-lightning/pull/164) - - 使用 row id 或者列的默认值填充 dump 文件中缺少的 column 数据 [#174](https://github.com/pingcap/tidb-lightning/pull/174) - - Importer 修复部分 SST 导入失败依然返回导入成功的 bug [#4566](https://github.com/tikv/tikv/pull/4566) - - Importer 支持 upload SST 到 TiKV 限速 [#4607](https://github.com/tikv/tikv/pull/4607) - - 修改 Importer RocksDB SST 压缩方法为 `lz4`，减少 CPU 消耗 [#4624](https://github.com/tikv/tikv/pull/4624) -- sync-diff-inspector - - 支持 checkpoint [#227](https://github.com/pingcap/tidb-tools/pull/227) - -## TiDB Ansible - -- 更新 tidb-ansible 中的文档链接，兼容重构之后的文档 [#740](https://github.com/pingcap/tidb-ansible/pull/740)，[#741](https://github.com/pingcap/tidb-ansible/pull/741) -- 移除 `inventory.ini` 中的 `enable_slow_query_log` 参数，默认即将 slow log 输出到单独的日志文件中 [#742](https://github.com/pingcap/tidb-ansible/pull/742) diff --git a/v3.0/releases/2.1ga.md b/v3.0/releases/2.1ga.md deleted file mode 100644 index cebf6d0750da..000000000000 --- a/v3.0/releases/2.1ga.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: TiDB 2.1 GA Release Notes -category: Releases -aliases: ['/docs-cn/releases/2.1ga/'] ---- - -# TiDB 2.1 GA Release Notes - -2018 年 11 月 30 日，TiDB 发布 2.1 GA 版。相比 2.0 版本，该版本对系统稳定性、性能、兼容性、易用性做了大量改进。 - -## TiDB - -+ SQL 优化器 - - - 优化 `Index Join` 选择范围，提升执行性能 - - 优化 `Index Join` 外表选择，使用估算的行数较少的表作为外表 - - 扩大 Join Hint `TIDB_SMJ` 的作用范围，在没有合适索引可用的情况下也可使用 Merge Join - - 加强 Join Hint `TIDB_INLJ` 的能力，可以指定 Join 中的内表 - - 优化关联子查询，包括下推 Filter 和扩大索引选择范围，部分查询的效率有数量级的提升 - - 支持在 `UPDATE` 和 `DELETE` 语句中使用 Index Hint 和 Join Hint - - 支持更多函数下推：`ABS`/`CEIL`/`FLOOR`/`IS TRUE`/`IS FALSE` - - 优化内建函数 `IF` 和 `IFNULL` 的常量折叠算法 - - 优化 `EXPLAIN` 语句输出格式, 使用层级结构表示算子之间的上下游关系 - -+ SQL 执行引擎 - - - 重构所有聚合函数，提升 `Stream` 和 `Hash` 聚合算子的执行效率 - - 实现并行 `Hash Aggregate` 算子，部分场景下有 350% 的性能提升 - - 实现并行 `Project` 算子，部分场景有 74% 的性能提升 - - 并发地读取 `Hash Join` 的 `Inner` 表和 `Outer` 表的数据，提升执行性能 - - 优化 `REPLACE INTO` 语句的执行速度，性能提升 10x - - 优化时间类型的内存占用，时间类型数据的内存使用降低为原来的一半 - - 优化点查的查询性能，Sysbench 点查效率提升 60% - - TiDB 插入和更新宽表，性能提升接近 20 倍 - - 支持在配置文件中设置单个查询的内存使用上限 - - 优化 `Hash Join` 的执行过程，当 Join 类型为 `Inner Join` 或者 `Semi Join` 时，如果内表为空，不再读取外表数据，快速返回结果 - - 支持 `EXPLAIN ANALYZE` 语句，用于查看 Query 执行过程中各个算子的运行时间，返回结果行数等运行时统计信息 - -+ 统计信息 - - - 支持只在一天中的某个时间段开启统计信息自动 ANALYZE 的功能 - - 支持根据查询的反馈自动更新表的统计信息 - - 支持通过 `ANALYZE TABLE WITH BUCKETS` 语句配置直方图中桶的个数 - - 优化等值查询和范围查询混合的情况下使用直方图估算 Row Count 的算法 - -+ 表达式 - - + 支持内建函数： - - - `json_contains` - - `json_contains_path` - - `encode/decode` - -+ Server - - - 支持在单个 tidb-server 实例内部对冲突事务排队，优化事务间冲突频繁的场景下的性能 - - 支持 Server Side Cursor - - 新增 HTTP 管理接口 - - 打散 table 的 Regions 在 TiKV 集群中的分布 - - 控制是否打开 `general log` - - 在线修改日志级别 - - 查询 TiDB 集群信息 - - 添加 `auto_analyze_ratio` 系统变量控制自动 Analyze 的阈值 - - 添加 `tidb_retry_limit` 系统变量控制事务自动重试的次数 - - 添加 `tidb_disable_txn_auto_retry` 系统变量控制事务是否自动重试 - - 支持使用 `admin show slow` 语句来获取慢查询语句 - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 - -+ DDL - - - 支持 Add Index 语句与其他 DDL 语句并行执行，避免耗时的 Add Index 操作阻塞其他操作 - - 优化 `Add Index` 的速度，在某些场景下速度大幅提升 - - 支持 `select tidb_is_ddl_owner()` 语句，方便判断 TiDB 是否为 `DDL Owner` - - 支持 `ALTER TABLE FORCE` 语法 - - 支持 `ALTER TABLE RENAME KEY TO` 语法 - - `Admin Show DDL Jobs` 输出结果中添加表名、库名等信息 - - 支持使用 `ddl/owner/resign` HTTP 接口释放 DDL Owner 并开启新一轮 DDL Owner 选举 - -+ 兼容性 - - - 支持更多 MySQL 语法 - - `BIT` 聚合函数支持 `ALL` 参数 - - 支持 `SHOW PRIVILEGES` 语句 - - 支持 `LOAD DATA` 语句的 `CHARACTER SET` 语法 - - 支持 `CREATE USER` 语句的 `IDENTIFIED WITH` 语法 - - 支持 `LOAD DATA IGNORE LINES` 语句 - - `Show ProcessList` 语句返回更准确信息 - -## PD (Placement Driver) - -+ 可用性优化 - - - 引入 TiKV 版本控制机制，支持集群滚动兼容升级 - - PD 节点间开启 `Raft PreVote`，避免网络隔离后恢复时产生的重新选举 - - 开启 `raft learner` 功能，降低调度时出现宕机导致数据不可用的风险 - - TSO 分配不再受系统时间回退影响 - - 支持 `Region merge` 功能，减少元数据带来的开销 - -+ 调度器优化 - - - 优化 Down Store 的处理流程，加快发生宕机后补副本的速度 - - 优化热点调度器，在流量统计信息抖动时适应性更好 - - 优化 Coordinator 的启动，减少重启 PD 时带来的不必要调度 - - 优化 Balance Scheduler 频繁调度小 Region 的问题 - - 优化 Region merge，调度时考虑 Region 中数据的行数 - - 新增一些控制调度策略的开关 - - 完善调度模拟器，添加调度场景模拟 - -+ API 及运维工具 - - - 新增 `GetPrevRegion` 接口，用于支持 TiDB reverse scan 功能 - - 新增 `BatchSplitRegion` 接口，用于支持 TiKV 快速 Region 分裂 - - 新增 `GCSafePoint` 接口，用于支持 TiDB 并发分布式 GC - - 新增 `GetAllStores` 接口，用于支持 TiDB 并发分布式 GC - + pd-ctl 新增： - - - 使用统计信息进行 Region split - - 调用 `jq` 来格式化 JSON 输出 - - 查询指定 store 的 Region 信息 - - 查询按 version 排序的 topN 的 Region 列表 - - 查询按 size 排序的 topN 的 Region 列表 - - 更精确的 TSO 解码 - - - pd-recover 不再需要提供 max-replica 参数 - -+ 监控 - - - 增加 `Filter`相关的监控 - - 新增 etcd Raft 状态机相关监控 - -+ 性能优化 - - - 优化处理 Region heartbeat 的性能，减少 heartbeat 带来的内存开销 - - 优化 Region tree 性能 - - 优化计算热点统计的性能问题 - -## TiKV - -+ Coprocessor - - - 新增支持大量内建函数 - - 新增 Coprocessor ReadPool，提高请求处理并发度 - - 修复时间函数解析以及时区相关问题 - - 优化下推聚合计算的内存使用 - -+ Transaction - - - 优化 MVCC 读取逻辑以及内存使用效率，提高扫描操作的性能，Count 全表性能比 2.0 版本提升 1 倍 - - 折叠 MVCC 中连续的 Rollback 记录，保证记录的读取性能 - - 新增 `UnsafeDestroyRange` API 用于在 drop table/index 的情况下快速回收空间 - - GC 模块独立出来，减少对正常写入的影响 - - kv_scan 命令支持设置 upper bound - -+ Raftstore - - - 优化 snapshot 文件写入流程避免导致 RocksDB stall - - 增加 LocalReader 线程专门处理读请求，降低读请求的延迟 - - 支持 `BatchSplit` 避免大量写入导致产生特别大的 Region - - 支持按照统计信息进行 Region Split，减少 IO 开销 - - 支持按照 Key 的数量进行 Region Split，提高索引扫描的并发度 - - 优化部分 Raft 消息处理流程，避免 Region Split 带来不必要的延迟 - - 启用 `PreVote` 功能，减少网络隔离对服务的影响 - -+ 存储引擎 - - - 修复 RocksDB `CompactFiles` 的 bug，可能影响 Lightning 导入的数据 - - 升级 RocksDB 到 v5.15，解决 snapshot 文件可能会被写坏的问题 - - 优化 `IngestExternalFile`，避免 flush 卡住写入的问题 - -+ tikv-ctl - - - 新增 ldb 命令，方便排查 RocksDB 相关问题 - - compact 命令支持指定是否 compact bottommost 层的数据 - -## Tools - -- 全量数据快速导入工具 TiDB Lightning -- 支持新版本 TiDB Binlog - -## 升级兼容性说明 - -+ 由于新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 -+ 从 2.0.6 之前的版本升级到 2.1 之前，最好确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 Add Index 操作，等 DDL 操作完成后再执行升级操作 -+ 因为 2.1 版本启用了并行 DDL，对于早于 2.0.1 版本的集群，无法滚动升级到 2.1，可以选择下面两种方案： - - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 2.1 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 2.1 版本 diff --git a/v3.0/releases/201.md b/v3.0/releases/201.md deleted file mode 100644 index cbcce71d52e5..000000000000 --- a/v3.0/releases/201.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: TiDB 2.0.1 release notes -category: Releases -aliases: ['/docs-cn/releases/201/'] ---- - - -# TiDB 2.0.1 Release Notes - -2018 年 5 月 16 日，TiDB 发布 2.0.1 版。该版本在 2.0.0 (GA) 版的基础上，对 MySQL 兼容性、系统稳定性做出了改进。 - -## TiDB - -- 实时更新 `Add Index` 的进度到 DDL 任务信息中 -- 添加 Session 变量 `tidb_auto_analyze_ratio` 控制统计信息自动更新阈值 -- 修复当事务提交失败时可能未清理所有的残留状态的问题 -- 修复加索引在部分情况下的 Bug -- 修复 DDL 修改表面操作在某些并发场景下的正确性问题 -- 修复某些情况下 `LIMIT` 结果不正确的问题 -- 修复 `ADMIN CHECK INDEX` 语句索引名字区分大小写问题 -- 修复 `UNION` 语句的兼容性问题 -- 修复插入 `TIME` 类型数据的兼容性问题 -- 修复某些情况下 `copIteratorTaskSender` 导致的 goroutine 泄漏问题 -- 增加一个选项，用于设置 TiDB 在写 Binlog 失败的情况下的行为 -- 优化 Coprocessor 慢请求日志格式，区分处理时间长与排队时间长的任务 -- MySQL 协议握手阶段发生错误不打印日志，避免 KeepAlive 造成大量日志 -- 优化 `Out of range value for column` 的错误信息 -- 修复 `Update` 语句中遇到子查询导致结果错误的问题 -- 调整 TiDB 进程处理 `SIGTERM` 的行为，不等待正在执行的 Query 完成 - -## PD - -- 添加 `Scatter Range` 调度，调度指定 Key Range 包含的 Region -- 优化 `Merge Region` 调度，使新分裂不久的 Region 不能被合并 -- 添加 learner 相关的 metrics -- 修复重启误删 scheduler 的问题 -- 修复解析配置文件出错问题 -- 修复 etcd leader 和 PD leader 不同步的问题 -- 修复关闭 learner 情况下还有 learner 出现的问题 -- 修复读取包过大造成 load Regions 失败的问题 - -## TiKV - -- 修复 `SELECT FOR UPDATE` 阻止其他人读的问题 -- 优化慢查询的日志 -- 减少 `thread_yield` 的调用次数 -- 修复生成 snapshot 会意外阻塞 raftstore 的 bug -- 修复特殊情况下开启 learner 无法选举成功的问题 -- 修复极端情况下分裂可能导致的脏读问题 -- 修正读线程池的配置默认值 -- 修正删大数据表会影响写性能的问题 diff --git a/v3.0/releases/202.md b/v3.0/releases/202.md deleted file mode 100644 index 37e74b633143..000000000000 --- a/v3.0/releases/202.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: TiDB 2.0.2 release notes -category: Releases -aliases: ['/docs-cn/releases/202/'] ---- - -# TiDB 2.0.2 Release Notes - -2018 年 5 月 21 日，TiDB 发布 2.0.2 版。该版本在 2.0.1 版的基础上，对系统稳定性做出了改进。 - -## TiDB - -- 修复 Decimal 除法内置函数下推的问题 -- 支持 `Delete` 语句中使用 `USE INDEX` 的语法 -- 禁止在带有 `Auto-Increment` 的列中使用 `shard_row_id_bits` 特性 -- 增加写入 Binlog 的超时机制 - -## PD - -- 使 balance leader scheduler 过滤失连节点 -- 更改 transfer leader operator 的超时时间为 10 秒 -- 修复 label scheduler 在集群 Regions 不健康状态下不调度的问题 -- 修复 evict leader scheduler 调度不当的问题 - -## TiKV - -- 修复 Raft 日志没有打出来的问题 -- 支持配置更多 gRPC 相关参数 -- 支持配置选举超时的取值范围 -- 修复过期 learner 没有删掉的问题 -- 修复 snapshot 中间文件被误删的问题 \ No newline at end of file diff --git a/v3.0/releases/203.md b/v3.0/releases/203.md deleted file mode 100644 index 84b2df0865ae..000000000000 --- a/v3.0/releases/203.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.0.3 release notes -category: Releases -aliases: ['/docs-cn/releases/203/'] ---- - -# TiDB 2.0.3 Release Notes - -2018 年 6 月 1 日，TiDB 发布 2.0.3 版。该版本在 2.0.2 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 支持在线更改日志级别 -- 支持 `COM_CHANGE_USER` 命令 -- 支持二进制协议情况下使用时间类型参数 -- 优化带 `BETWEEN` 表达式的查询条件代价估算 -- 在 `SHOW CREATE TABLE` 里不显示 `FOREIGN KEY` 信息 -- 优化带 `LIMIT` 子句的查询代价估算 -- 修复 `YEAR` 类型作为唯一索引的问题 -- 修复在没有唯一索引的情况下 `ON DUPLICATE KEY UPDATE` 的问题 -- 修复 `CEIL` 函数的兼容性问题 -- 修复 `DECIMAL` 类型计算 `DIV` 的精度问题 -- 修复 `ADMIN CHECK TABLE` 误报的问题 -- 修复 `MAX`/`MIN` 在特定表达式参数下 panic 的问题 -- 修复特殊情况下 `JOIN` 结果为空的问题 -- 修复 `IN` 表达式构造查询 `Range` 的问题 -- 修复使用 `Prepare` 方式进行查询且启用 `Plan Cache` 情况下的 Range 计算问题 -- 修复异常情况下频繁加载 Schema 信息的问题 - -## PD - -- 修复在特定条件下收集 hot-cache metrics 会 panic 的问题 -- 修复对旧的 Region 产生调度的问题 - -## TiKV - -- 修复 learner flag 错误上报给 PD 的 bug -- 在 `do_div_mod` 中 `divisor/dividend` 为 0 时返回错误 \ No newline at end of file diff --git a/v3.0/releases/204.md b/v3.0/releases/204.md deleted file mode 100644 index 29d8ce0fc568..000000000000 --- a/v3.0/releases/204.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: TiDB 2.0.4 release notes -category: Releases -aliases: ['/docs-cn/releases/204/'] ---- - -# TiDB 2.0.4 Release Notes - -2018 年 6 月 15 日，TiDB 发布 2.0.4 版。该版本在 2.0.3 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 支持 `ALTER TABLE t DROP COLUMN a CASCADE` 语法 -- 支持设置 `tidb_snapshot` 变量的值为 `TSO` -- 优化监控项中语句类型展示 -- 优化查询代价估计精度 -- 设置 gRPC 的 `backoff max delay` 参数 -- 支持通过配置文件设置单条语句的内存使用阈值 -- 重构 Optimizer 的 error -- 解决 Cast Decimal 数据的副作用问题 -- 解决特定场景下 `Merge Join` 算子结果错误的问题 -- 解决转换 `Null` 对象到 String 的问题 -- 解决 Cast JSON 数据为 JSON 类型的问题 -- 解决 `Union` + `OrderBy` 情况下结果顺序和 MySQL 不一致的问题 -- 解决 `Union` 语句中对 `Limit`/`OrderBy` 子句的合法性检查规则问题 -- 解决 `Union All` 的结果兼容性问题 -- 解决谓词下推中的一个 Bug -- 解决 `Union` 语句对 `For Update` 子句的兼容性问题 -- 解决 `concat_ws` 函数对结果错误截断的问题 - -## PD - -- 改进 `max-pending-peer-count` 调度参数未设置时的行为，调整为不限制最大 `PendingPeer` 的数量 - -## TiKV - -- 新增 RocksDB `PerfContext` 接口用于调试 -- 移除 `import-mode` 参数 -- 为 `tikv-ctl` 添加 `region-properties` 命令 -- 优化有大量 RocksDB tombstone 时 `reverse-seek` 过慢的问题 -- 修复 `do_sub` 导致的崩溃问题 -- 当 GC 遇到有太多版本的数据时记录日志 diff --git a/v3.0/releases/205.md b/v3.0/releases/205.md deleted file mode 100644 index c6ea8bfef1a2..000000000000 --- a/v3.0/releases/205.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB 2.0.5 release notes -category: Releases -aliases: ['/docs-cn/releases/205/'] ---- - -# TiDB 2.0.5 Release Notes - -2018 年 7 月 6 日，TiDB 发布 2.0.5 版。该版本在 2.0.4 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- New Features - - 增加一个系统变量 `tidb_disable_txn_auto_retry`，用于关闭事务自动重试 [#6877](https://github.com/pingcap/tidb/pull/6877) -- Improvements - - 调整计算 `Selection` 代价的方式，结果更准确 [#6989](https://github.com/pingcap/tidb/pull/6989) - - 查询条件能够完全匹配唯一索引或者主键时，直接选择作为查询路径 [#6966](https://github.com/pingcap/tidb/pull/6966) - - 启动服务失败时，做必要的清理工作 [#6964](https://github.com/pingcap/tidb/pull/6964) - - 在 `Load Data` 语句中，将 `\N` 处理为 NULL [#6962](https://github.com/pingcap/tidb/pull/6962) - - 优化 CBO 代码结构 [#6953](https://github.com/pingcap/tidb/pull/6953) - - 启动服务时，尽早上报监控数据 [#6931](https://github.com/pingcap/tidb/pull/6931) - - 对慢查询日志格式进行优化：去除 SQL 语句中的换行符，增加用户信息 [#6920](https://github.com/pingcap/tidb/pull/6920) - - 支持注释中存在多个星号的情况 [#6858](https://github.com/pingcap/tidb/pull/6858) -- Bug Fixes - - 修复 `KILL QUERY` 语句权限检查问题 [#7003](https://github.com/pingcap/tidb/pull/7003) - - 修复用户数量超过 1024 时可能造成无法登录的问题 [#6986](https://github.com/pingcap/tidb/pull/6986) - - 修复一个写入无符号类型 `float`/`double` 数据的问题 [#6940](https://github.com/pingcap/tidb/pull/6940) - - 修复 `COM_FIELD_LIST` 命令的兼容性，解决部分 MariaDB 客户端遇到 Panic 的问题 [#6929](https://github.com/pingcap/tidb/pull/6929) - - 修复 `CREATE TABLE IF NOT EXISTS LIKE` 行为 [#6928](https://github.com/pingcap/tidb/pull/6928) - - 修复一个 TopN 下推过程中的问题 [#6923](https://github.com/pingcap/tidb/pull/6923) - - 修复 `Add Index` 过程中遇到错误时当前处理的行 ID 记录问题 [#6903](https://github.com/pingcap/tidb/pull/6903) - -## PD - -- 修复某些场景下副本迁移导致 TiKV 磁盘空间耗尽的问题 -- 修复 `AdjacentRegionScheduler` 导致的崩溃问题 - -## TiKV - -- 修复 decimal 运算中潜在的溢出问题 -- 修复 merge 过程中可能发生的脏读问题 \ No newline at end of file diff --git a/v3.0/releases/206.md b/v3.0/releases/206.md deleted file mode 100644 index d74e0854a8b6..000000000000 --- a/v3.0/releases/206.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: TiDB 2.0.6 release notes -category: Releases -aliases: ['/docs-cn/releases/206/'] ---- - -# TiDB 2.0.6 Release Notes - -2018 年 8 月 6 日，TiDB 发布 2.0.6 版。该版本在 2.0.5 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- Improvements - - 精简 "set system variable" 日志的长度，减少日志文件体积 [#7031](https://github.com/pingcap/tidb/pull/7031) - - 在日志中记录 `ADD INDEX` 执行过程中的慢操作，便于定位问题 [#7083](https://github.com/pingcap/tidb/pull/7083) - - 减少更新统计信息操作中的事务冲突 [#7138](https://github.com/pingcap/tidb/pull/7138) - - 当待估算的值超过统计信息范围时，提高行数估计的准确度 [#7185](https://github.com/pingcap/tidb/pull/7185) - - 当使用 `Index Join` 时，选择行数估计较小的表作为驱动表，提高 `Index Join` 的执行效率 [#7227](https://github.com/pingcap/tidb/pull/7227) - - 为 `ANALYZE TABLE` 语句执行过程中发生的 panic 添加 recover 机制，避免收集统计信息过程中的异常行为导致 tidb-server 不可用 [#7228](https://github.com/pingcap/tidb/pull/7228) - - 当 `RPAD`/`LPAD` 的结果超过设置系统变量 `max_allowed_packet` 时，返回 `NULL` 和对应的 warning，兼容 MySQL [#7244](https://github.com/pingcap/tidb/pull/7244) - - 设置 `PREPARE` 语句中占位符数量上限为 65535，兼容 MySQL [#7250](https://github.com/pingcap/tidb/pull/7250) -- Bug Fixes - - 修复某些情况下，`DROP USER` 语句和 MySQL 行为不兼容的问题 [#7014](https://github.com/pingcap/tidb/pull/7014) - - 修复当 `tidb_batch_insert` 打开后，`INSERT`/`LOAD DATA` 等语句在某些场景下 OOM 的问题 [#7092](https://github.com/pingcap/tidb/pull/7092) - - 修复某个表的数据持续更新时，其统计信息自动更新失效的问题 [#7093](https://github.com/pingcap/tidb/pull/7093) - - 修复防火墙断掉不活跃的 gRPC 连接的问题 [#7099](https://github.com/pingcap/tidb/pull/7099) - - 修复某些场景下使用前缀索引结果不正确的问题 [#7126](https://github.com/pingcap/tidb/pull/7126) - - 修复某些场景下统计信息过时导致 panic 的问题 [#7155](https://github.com/pingcap/tidb/pull/7155) - - 修复某些场景下 `ADD INDEX` 后索引数据少一条的问题 [#7156](https://github.com/pingcap/tidb/pull/7156) - - 修复某些场景下查询唯一索引上的 `NULL` 值结果不正确的问题 [#7172](https://github.com/pingcap/tidb/pull/7172) - - 修复某些场景下 `DECIMAL` 的乘法结果出现乱码的问题 [#7212](https://github.com/pingcap/tidb/pull/7212) - - 修复某些场景下 `DECIMAL` 的取模运算结果不正确的问题 [#7245](https://github.com/pingcap/tidb/pull/7245) - - 修复某些特殊语句序列下在事务中执行 `UPDATE`/`DELETE` 语句后结果不正确的问题 [#7219](https://github.com/pingcap/tidb/pull/7219) - - 修复某些场景下 `UNION ALL`/`UPDATE` 语句在构造执行计划过程中 panic 的问题 [#7225](https://github.com/pingcap/tidb/pull/7225) - - 修复某些场景下前缀索引的索引范围计算错误的问题 [#7231](https://github.com/pingcap/tidb/pull/7231) - - 修复某些场景下 `LOAD DATA` 语句不写 binlog 的问题 [#7242](https://github.com/pingcap/tidb/pull/7242) - - 修复某些场景下在 `ADD INDEX` 过程中 `SHOW CREATE TABLE` 结果不正确的问题 [#7243](https://github.com/pingcap/tidb/pull/7243) - - 修复某些场景下 `Index Join` 因为没有初始化事务时间戳而 panic 的问题 [#7246](https://github.com/pingcap/tidb/pull/7246) - - 修复 `ADMIN CHECK TABLE` 因为误用 session 中的时区而导致误报的问题 [#7258](https://github.com/pingcap/tidb/pull/7258) - - 修复 `ADMIN CLEANUP INDEX` 在某些场景下索引没有清除干净的问题 [#7265](https://github.com/pingcap/tidb/pull/7265) - - 禁用 Read Committed 事务隔离级别 [#7282](https://github.com/pingcap/tidb/pull/7282) - -## TiKV - -- Improvements - - 扩大默认 scheduler slots 值以减少假冲突现象 - - 减少回滚事务的连续标记以提升冲突极端严重下的读性能 - - 限制 RocksDB log 文件的大小和个数以减少长时间运行下不必要的磁盘占用 -- Bug Fixes - - 修复字符串转 Decimal 时出现的 crash \ No newline at end of file diff --git a/v3.0/releases/207.md b/v3.0/releases/207.md deleted file mode 100644 index ffeaaf5377ca..000000000000 --- a/v3.0/releases/207.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: TiDB 2.0.7 release notes -category: Releases -aliases: ['/docs-cn/releases/207/'] ---- - -# TiDB 2.0.7 Release Notes - -2018 年 9 月 7 日，TiDB 发布 2.0.7 版。该版本在 2.0.6 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- New Feature - - 在 `information_schema` 里添加 `PROCESSLIST` 表 [#7286](https://github.com/pingcap/tidb/pull/7286) -- Improvements - - 收集更多语句执行细节，并输出在 `SLOW QUERY` 日志里 [#7364](https://github.com/pingcap/tidb/pull/7364) - - `SHOW CREATE TABLE` 不再输出分区信息 [#7388](https://github.com/pingcap/tidb/pull/7388) - - 通过设置 RC 隔离级别和低优先级优化 `ANALYZE` 语句执行效率 [#7500](https://github.com/pingcap/tidb/pull/7500) - - 加速 `ADD UNIQUE INDEX` [#7562](https://github.com/pingcap/tidb/pull/7562) - - 增加控制 DDL 并发度的选项 [#7563](https://github.com/pingcap/tidb/pull/7563) -- Bug Fixes - - 修复 `PRIMARY KEY` 为整数的表，无法使用 `USE INDEX(PRIMARY)` 的问题 [#7298](https://github.com/pingcap/tidb/pull/7298) - - 修复 `Merge Join` 和 `Index Join` 在 inner row 为 `NULL` 时输出多余结果的问题 [#7301](https://github.com/pingcap/tidb/pull/7301) - - 修复 chunk size 设置过小时，`Join` 输出多余结果的问题 [#7315](https://github.com/pingcap/tidb/pull/7315) - - 修复建表语句中包含 `range column` 语法导致 panic 的问题 [#7379](https://github.com/pingcap/tidb/pull/7379) - - 修复 `admin check table` 对时间类型的列误报的问题 [#7457](https://github.com/pingcap/tidb/pull/7457) - - 修复以默认值 `current_timestamp` 插入的数据无法用 `=` 条件查询到的问题 [#7467](https://github.com/pingcap/tidb/pull/7467) - - 修复以 `ComStmtSendLongData` 命令插入空字符串参数被误解析为 `NULL` 的问题 [#7508](https://github.com/pingcap/tidb/pull/7508) - - 修复特定场景下 `auto analyze` 不断重复执行的问题 [#7556](https://github.com/pingcap/tidb/pull/7556) - - 修复 parser 无法解析以换行符结尾的单行注释的问题 [#7635](https://github.com/pingcap/tidb/pull/7635) - -## TiKV - -- Improvement - - 空集群默认打开 `dynamic-level-bytes` 参数减少空间放大 -- Bug Fix - - 在 Region merge 之后更新 Region 的 `approximate size` 和 keys \ No newline at end of file diff --git a/v3.0/releases/208.md b/v3.0/releases/208.md deleted file mode 100644 index ea0e791a0ac7..000000000000 --- a/v3.0/releases/208.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: TiDB 2.0.8 release notes -category: Releases -aliases: ['/docs-cn/releases/208/'] ---- - -# TiDB 2.0.8 Release Notes - -2018 年 10 月 16 日，TiDB 发布 2.0.8 版。该版本在 2.0.7 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -+ 功能改进 - - 在 `Update` 没有更改相应 AUTO-INCREMENT 列情况下，防止 AUTO-ID 被消耗过快 [#7846](https://github.com/pingcap/tidb/pull/7846) -+ Bug 修复 - - 在 PD Leader 异常宕机的情况下，TiDB 快速创建 etcd Session 恢复服务 [#7810](https://github.com/pingcap/tidb/pull/7810) - - 修复 `DateTime` 类型使用默认值时候没有考虑时区的问题 [#7672](https://github.com/pingcap/tidb/pull/7672) - - 修复 `duplicate key update` 在某些情况下没有正确插入值的问题 [#7685](https://github.com/pingcap/tidb/pull/7685) - - 修复 `UnionScan` 中谓词条件没有下推的问题 [#7726](https://github.com/pingcap/tidb/pull/7726) - - 修复增加 `TIMESTAMP` 索引没有正确处理时区的问题 [#7812](https://github.com/pingcap/tidb/pull/7812) - - 修复某些情况下统计信息模块导致的内存泄露问题 [#7864](https://github.com/pingcap/tidb/pull/7864) - - 修复在某些异常情况下，无法获得 `ANALYZE` 结果的问题 [#7871](https://github.com/pingcap/tidb/pull/7871) - - 令 `SYSDATE` 不做表达式展开，以返回正确的结果 [#7894](https://github.com/pingcap/tidb/pull/7894) - - 修复某些情况下，`substring_index` panic 的问题 [#7896](https://github.com/pingcap/tidb/pull/7896) - - 修复某些情况下，错误将 `OUTER JOIN` 转为 `INNER JOIN` 的问题 [#7899](https://github.com/pingcap/tidb/pull/7899) - -## TiKV - -+ Bug 修复 - - 修复节点宕机时 Raftstore `EntryCache` 占用内存持续上升的问题 [#3529](https://github.com/tikv/tikv/pull/3529) \ No newline at end of file diff --git a/v3.0/releases/209.md b/v3.0/releases/209.md deleted file mode 100644 index a6cde802729c..000000000000 --- a/v3.0/releases/209.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: TiDB 2.0.9 Release Notes -category: Releases -aliases: ['/docs-cn/releases/209/'] ---- - -# TiDB 2.0.9 Release Notes - -2018 年 11 月 19 日，TiDB 发布 2.0.9 版。该版本在 2.0.8 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复统计信息直方图为空的时候导致的问题 [#7927](https://github.com/pingcap/tidb/pull/7927) -- 修复 `UNION ALL` 语句在某些情况下 panic 的问题 [#7942](https://github.com/pingcap/tidb/pull/7942) -- 修复错误的 DDL JOB 情况下导致的递归溢出问题 [#7959](https://github.com/pingcap/tidb/pull/7959) -- 为 `Commit` 操作加上慢操作日志 [#7983](https://github.com/pingcap/tidb/pull/7983) -- 修复 `Limit` 值太大的情况下导致的 panic 问题 [#8004](https://github.com/pingcap/tidb/pull/8004) -- 支持 `USING` 子句指定 `utf8mb4` 字符集 [#8048](https://github.com/pingcap/tidb/pull/8048) -- 内建函数 `TRUNCATE` 支持类型为 unsigned int 的参数 [#8069](https://github.com/pingcap/tidb/pull/8069) -- 修复统计信息模块在某些情况下主键选择率估算的问题 [#8150](https://github.com/pingcap/tidb/pull/8150) -- 增加 `Session` 变量来控制是否允许写入 `_tidb_rowid` [#8126](https://github.com/pingcap/tidb/pull/8126) -- 修复 `PhysicalProjection` 在某些情况下 panic 的问题 [#8154](https://github.com/pingcap/tidb/pull/8154) -- 修复 `Union` 语句在某些情况下结果不稳定的问题 [#8168](https://github.com/pingcap/tidb/pull/8168) -- 修复在非插入语句下 `values` 没有返回 `NULL` 的问题 [#8179](https://github.com/pingcap/tidb/pull/8179) -- 修复某些情况下统计信息模块无法清除过期统计数据的问题 [#8184](https://github.com/pingcap/tidb/pull/8184) -- 让事务允许的最长运行时间变成一个可配置项 [#8209](https://github.com/pingcap/tidb/pull/8209) -- 修复 `expression rewriter` 某些情况下错误的比较逻辑 [#8288](https://github.com/pingcap/tidb/pull/8288) -- 消除 `UNION ORDER BY` 语句生成的多余列的问题 [#8307](https://github.com/pingcap/tidb/pull/8307) -- 支持 `admin show next_row_id` 语句 [#8274](https://github.com/pingcap/tidb/pull/8274) -- 修复 `Show Create Table` 语句中特殊字符转义的问题 [#8321](https://github.com/pingcap/tidb/pull/8321) -- 修复 `UNION` 语句在某些情况下遇到非预期错误的问题 [#8318](https://github.com/pingcap/tidb/pull/8318) -- 修复某些情况下取消 DDL 任务导致的 Schema 没有回滚的问题 [#8312](https://github.com/pingcap/tidb/pull/8312) -- 把变量 `tidb_max_chunk_size` 变成全局环境变量 [#8333](https://github.com/pingcap/tidb/pull/8333) -- ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8309](https://github.com/pingcap/tidb/pull/8309) [#8310](https://github.com/pingcap/tidb/pull/8310) - -## PD - -- 修复 etcd 启动失败导致的服务挂起问题 [#1267](https://github.com/pingcap/pd/pull/1267) -- 修复 `pd-ctl` 读取 Region key 的相关问题 [#1298](https://github.com/pingcap/pd/pull/1298) [#1299](https://github.com/pingcap/pd/pull/1299) [#1308](https://github.com/pingcap/pd/pull/1308) -- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -- 修复 PD join 失败后无法重新 join 的问题 [1279](https://github.com/pingcap/pd/pull/1279) - -## TiKV - -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) -- 废弃配置 `max-tasks-xxx` 并新增 `max-tasks-per-worker-xxx` [#3093](https://github.com/tikv/tikv/pull/3093) -- 修复 RocksDB `CompactFiles` 的问题 [#3789](https://github.com/tikv/tikv/pull/3789) \ No newline at end of file diff --git a/v3.0/releases/21beta.md b/v3.0/releases/21beta.md deleted file mode 100644 index 4ae3d25422bf..000000000000 --- a/v3.0/releases/21beta.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: TiDB 2.1 Beta Release Notes -category: Releases -aliases: ['/docs-cn/releases/21beta/'] ---- - -# TiDB 2.1 Beta Release Notes - -2018 年 6 月 29 日，TiDB 发布 2.1 Beta 版。相比 2.0 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 优化 `Index Join` 选择范围，提升执行性能 - - 优化关联子查询，下推 Filter 和扩大索引选择范围，部分查询的效率有数量级的提升 - - 在 `UPDATE`、`DELETE` 语句中支持 `Index Hint` 和 `Join Hint` - - 优化器 Hint `TIDM_SMJ` 在没有索引可用的情况下可生效 - - 支持更多函数下推：`ABS`/`CEIL`/`FLOOR`/`IS TRUE`/`IS FALSE` - - 在常量折叠过程中特殊处理函数 `IF` 和 `IFNULL` - - 优化 `EXPLAIN` 语句输出格式 -- SQL 执行引擎 - - 实现并行 `Hash Aggregate` 算子，部分场景下能提高 `Hash Aggregate` 计算性能 350% - - 实现并行 `Project` 算子，部分场景下性能提升达 74% - - 并发地读取 `Hash Join` 的 `Inner` 表和 `Outer` 表的数据，提升执行性能 - - 修复部分场景下 `INSERT … ON DUPLICATE KEY UPDATE …` 结果不正确的问题 - - 修复 `CONCAT_WS`/`FLOOR`/`CEIL`/`DIV` 内建函数的结果不正确的问题 -- Server - - 添加 HTTP API 打散 table 的 Regions 在 TiKV 集群中的分布 - - 添加 `auto_analyze_ratio` 系统变量控制自动 analyze 的阈值 - - 添加 HTTP API 控制是否打开 `general log` - - 添加 HTTP API 在线修改日志级别 - - 在 `general log` 和 `slow query log` 中添加 user 信息 - - 支持 Server side cursor -- 兼容性 - - 支持更多 MySQL 语法 - - `BIT` 聚合函数支持 `ALL` 参数 - - 支持 `SHOW PRIVILEGES` 语句 -- DML - - 减少 `INSERT INTO SELECT` 语句的内存占用 - - 修复 Plan Cache 的性能问题 - - 添加 `tidb_retry_limit` 系统变量控制事务自动重试的次数 - - 添加 `tidb_disable_txn_auto_retry` 系统变量控制事务是否自动重试 - - 修复写入 `time` 类型的数据精度问题 - - 支持本地冲突事务排队，优化冲突事务性能 - - 修复 `UPDATE` 语句的 `Affected Rows` - - 优化 `insert ignore on duplicate key update` 语句性能 - - 优化 `Create Table` 语句的执行速度 - - 优化 `Add index` 的速度，在某些场景下速度大幅提升 - - 修复 `Alter table add column` 增加列超过表的列数限制的问题 - - 修复在某些异常情况下 DDL 任务重试导致 TiKV 压力增加的问题 - - 修复在某些异常情况下 TiDB 不断重载 Schema 信息的问题 -- DDL - - `Show Create Table` 不再输出外键相关的内容 - - 支持 `select tidb_is_ddl_owner()` 语句，方便判断 TiDB 是否为 `DDL Owner` - - 修复某些场景下 `YEAR` 类型删除索引的问题 - - 修复并发执行场景下的 `Rename table` 的问题 - - 支持 `ALTER TABLE FORCE` 语法 - - 支持 `ALTER TABLE RENAME KEY TO` 语法 - - `admin show ddl jobs` 输出信息中添加表名、库名等信息 - -## PD - -- PD 节点间开启 `Raft PreVote`，避免网络隔离后恢复时产生的重新选举 -- 优化 Balance Scheduler 频繁调度小 Region 的问题 -- 优化热点调度器，在流量统计信息抖动时适应性更好 -- `region merge` 调度时跳过数据行数较多的 Region -- 默认开启 `raft learner` 功能，降低调度时出现宕机导致数据不可用的风险 -- `pd-recover` 移除 max-replica 参数 -- 增加 `Filter` 相关的 metrics -- 修复 tikv-ctl unsafe recovery 之后 Region 信息没更新的问题 -- 修复某些场景下副本迁移导致 TiKV 磁盘空间耗尽的问题 -- 兼容性提示 - - 由于新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 - - 新版本默认开启 `raft learner` 功能，如果从 1.x 版本集群升级至 2.1 版本，须停机升级或者先滚动升级 TiKV，完成后再滚动升级 PD - -## TiKV - -- 升级 Rust 到 `nightly-2018-06-14` 版本 -- 开启 `PreVote`，避免网络隔离后恢复时产生的重新选举 -- 添加 metric，显示 RocksDB 内部每层的文件数和 `ingest` 相关的信息 -- GC 运行时打印版本太多的 `key` -- 使用 `static metric` 优化多 label metric 性能（YCSB raw get 提升 3%） -- 去掉多个模块的 `box`，使用范型提升运行时性能（YCSB raw get 提升 3%） -- 使用 `asynchronous log` 提升写日志性能 -- 增加收集线程状态的 metric -- 通过减少程序中 `box` 的使用来减少内存拷贝的次数，提升性能 diff --git a/v3.0/releases/21rc1.md b/v3.0/releases/21rc1.md deleted file mode 100644 index bc8c26ac73ef..000000000000 --- a/v3.0/releases/21rc1.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: TiDB 2.1 RC1 Release Notes -category: Releases -aliases: ['/docs-cn/releases/21rc1/'] ---- - -# TiDB 2.1 RC1 Release Notes - -2018 年 8 月 24 日，TiDB 发布 2.1 RC1 版。相比 2.1 Beta 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 修复某些情况下关联子查询去关联后结果不正确的问题 [#6972](https://github.com/pingcap/tidb/pull/6972) - - 优化 `Explain` 输出结果 [#7011](https://github.com/pingcap/tidb/pull/7011)[#7041](https://github.com/pingcap/tidb/pull/7041) - - 优化 `IndexJoin` 驱动表选择策略[#7019](https://github.com/pingcap/tidb/pull/7019) - - 去掉非 `PREPARE` 语句的 Plan Cache [#7040](https://github.com/pingcap/tidb/pull/7040) - - 修复某些情况下 `INSERT` 语句无法正常解析执行的问题 [#7068](https://github.com/pingcap/tidb/pull/7068) - - 修复某些情况下 `IndexJoin` 结果不正确的问题 [#7150](https://github.com/pingcap/tidb/pull/7150) - - 修复某些情况下使用唯一索引不能查询到 `NULL` 值的问题 [#7163](https://github.com/pingcap/tidb/pull/7163) - - 修复 UTF-8 编码情况下前缀索引的范围计算不正确的问题 [#7194](https://github.com/pingcap/tidb/pull/7194) - - 修复某些情况下 `Project` 算子消除导致的结果不正确的问题 [#7257](https://github.com/pingcap/tidb/pull/7257) - - 修复主键为整数类型时无法使用 `USE INDEX(PRIMARY)` 的问题 [#7316](https://github.com/pingcap/tidb/pull/7316) - - 修复某些情况下使用关联列无法计算索引范围的问题 [#7357](https://github.com/pingcap/tidb/pull/7357) -- SQL 执行引擎 - - 修复某些情况下夏令时时间计算结果不正确的问题 [#6823](https://github.com/pingcap/tidb/pull/6823) - - 重构聚合函数框架，提升 `Stream` 和 `Hash` 聚合算子的执行效率 [#6852](https://github.com/pingcap/tidb/pull/6852) - - 修复某些情况下 `Hash` 聚合算子不能正常退出的问题 [#6982](https://github.com/pingcap/tidb/pull/6982) - - 修复 `BIT_AND`/`BIT_OR`/`BIT_XOR` 没有正确处理非整型数据的问题 [#6994](https://github.com/pingcap/tidb/pull/6994) - - 优化 `REPLACE INTO` 语句的执行速度，性能提升近 10 倍 [#7027](https://github.com/pingcap/tidb/pull/7027) - - 优化时间类型的内存占用，时间类型数据的内存使用降低为原来的一半 [#7043](https://github.com/pingcap/tidb/pull/7043) - - 修复 `UNION` 语句整合有符号和无符号型整数结果时与 MySQL 不兼容的问题 [#7112](https://github.com/pingcap/tidb/pull/7112) - - 修复 `LPAD`/`RPAD`/`TO_BASE64`/`FROM_BASE64`/`REPEAT` 因为申请过多内存导致 TiDB panic 的问题 [#7171](https://github.com/pingcap/tidb/pull/7171) [#7266](https://github.com/pingcap/tidb/pull/7266) [#7409](https://github.com/pingcap/tidb/pull/7409) [#7431](https://github.com/pingcap/tidb/pull/7431) - - 修复 `MergeJoin`/`IndexJoin` 在处理 `NULL` 值时结果不正确的问题 [#7255](https://github.com/pingcap/tidb/pull/7255) - - 修复某些情况下 Outer Join 结果不正确的问题 [#7288](https://github.com/pingcap/tidb/pull/7288) - - 增强 `Data Truncated` 的报错信息，便于定位出错的数据和表中对应的字段 [#7401](https://github.com/pingcap/tidb/pull/7401) - - 修复某些情况下 Decimal 计算结果不正确的问题 [#7001](https://github.com/pingcap/tidb/pull/7001) [#7113](https://github.com/pingcap/tidb/pull/7113) [#7202](https://github.com/pingcap/tidb/pull/7202) [#7208](https://github.com/pingcap/tidb/pull/7208) - - 优化点查的查询性能 [#6937](https://github.com/pingcap/tidb/pull/6937) - - 禁用 `Read Committed` 隔离级别，避免潜在的问题 [#7211](https://github.com/pingcap/tidb/pull/7211) - - 修复某些情况下 `LTRIM`/`RTRIM`/`TRIM` 结果不正确的问题 [#7291](https://github.com/pingcap/tidb/pull/7291) - - 修复 `MaxOneRow` 算子无法保证返回结果不超过 1 行的问题 [#7375](https://github.com/pingcap/tidb/pull/7375) - - 拆分 range 个数过多的 Coprocessor 请求 [#7454](https://github.com/pingcap/tidb/pull/7454) -- 统计信息 - - 优化统计信息动态收集机制 [#6796](https://github.com/pingcap/tidb/pull/6796) - - 解决数据频繁更新场景下 `Auto Analyze` 不工作的问题 [#7022](https://github.com/pingcap/tidb/pull/7022) - - 减少统计信息动态更新过程中的写入冲突 [#7124](https://github.com/pingcap/tidb/pull/7124) - - 优化统计信息不准确情况下的代价估算 [#7175](https://github.com/pingcap/tidb/pull/7175) - - 优化 `AccessPath` 的代价估算策略 [#7233](https://github.com/pingcap/tidb/pull/7233) -- Server - - 修复加载权限信息时的 bug [#6976](https://github.com/pingcap/tidb/pull/6976) - - 修复 `Kill` 命令对权限的检查过严问题 [#6954](https://github.com/pingcap/tidb/pull/6954) - - 解决 Binary 协议中某些数值类型移除的问题 [#6922](https://github.com/pingcap/tidb/pull/6922) - - 精简日志输出 [#7029](https://github.com/pingcap/tidb/pull/7029) - - 处理 `mismatchClusterID` 问题 [#7053](https://github.com/pingcap/tidb/pull/7053) - - 增加 `advertise-address` 配置项 [#7078](https://github.com/pingcap/tidb/pull/7078) - - 增加 `GrpcKeepAlive` 选项 [#7100](https://github.com/pingcap/tidb/pull/7100) - - 增加连接或者 `Token` 时间监控 [#7110](https://github.com/pingcap/tidb/pull/7110) - - 优化数据解码性能 [#7149](https://github.com/pingcap/tidb/pull/7149) - - `INFORMMATION_SCHEMA` 中增加 `PROCESSLIST` 表 [#7236](https://github.com/pingcap/tidb/pull/7236) - - 解决权限验证时多条规则可以命中情况下的顺序问题 [#7211](https://github.com/pingcap/tidb/pull/7211) - - 将部分编码相关的系统变量默认值改为 UTF-8 [#7198](https://github.com/pingcap/tidb/pull/7198) - - 慢查询日志显示更详细的信息 [#7302](https://github.com/pingcap/tidb/pull/7302) - - 支持在 PD 注册 tidb-server 的相关信息并通过 HTTP API 获取 [#7082](https://github.com/pingcap/tidb/pull/7082) -- 兼容性 - - 支持 `Session` 变量 `warning_count` 和 `error_count` [#6945](https://github.com/pingcap/tidb/pull/6945) - - 读取系统变量时增加 Scope 检查 [#6958](https://github.com/pingcap/tidb/pull/6958) - - 支持 `MAX_EXECUTION_TIME` 语法 [#7012](https://github.com/pingcap/tidb/pull/7012) - - 支持更多的 `SET` 语法 [#7020](https://github.com/pingcap/tidb/pull/7020) - - Set 系统变量值过程中增加合法性校验 [#7117](https://github.com/pingcap/tidb/pull/7117) - - 增加 `Prepare` 语句中 `PlaceHolder` 数量的校验 [#7162](https://github.com/pingcap/tidb/pull/7162) - - 支持 `set character_set_results = null` [#7353](https://github.com/pingcap/tidb/pull/7353) - - 支持 `flush status` 语法 [#7369](https://github.com/pingcap/tidb/pull/7369) - - 修复 `SET` 和 `ENUM` 类型在 `information_schema` 里的 column size [#7347](https://github.com/pingcap/tidb/pull/7347) - - 支持建表语句里的 `NATIONAL CHARACTER` 语法 [#7378](https://github.com/pingcap/tidb/pull/7378) - - 支持 `LOAD DATA` 语句的 `CHARACTER SET` 语法 [#7391](https://github.com/pingcap/tidb/pull/7391) - - 修复 `SET` 和 `ENUM `类型的 column info [#7417](https://github.com/pingcap/tidb/pull/7417) - - 支持 `CREATE USER` 语句的 `IDENTIFIED WITH` 语法 [#7402](https://github.com/pingcap/tidb/pull/7402) - - 修复 `TIMESTAMP` 类型计算过程中丢失精度的问题 [#7418](https://github.com/pingcap/tidb/pull/7418) - - 支持更多 `SYSTEM` 变量的合法性验证 [#7196](https://github.com/pingcap/tidb/pull/7196) - - 修复 `CHAR_LENGTH` 函数在计算 binary string 时结果不正确的问题 [#7410](https://github.com/pingcap/tidb/pull/7410) - - 修复在包含 `GROUP BY` 的语句里 `CONCAT` 结果不正确的问题 [#7448](https://github.com/pingcap/tidb/pull/7448) - - 修复 `DECIMAL` 类型 CAST 到 `STRING` 类型时，类型长度不准确的问题 [#7451](https://github.com/pingcap/tidb/pull/7451) -- DML - - 解决 `Load Data` 语句的稳定性 [#6927](https://github.com/pingcap/tidb/pull/6927) - - 解决一些 `Batch` 操作情况下的内存使用问题 [#7086](https://github.com/pingcap/tidb/pull/7086) - - 提升 `Replace Into` 语句的性能 [#7027](https://github.com/pingcap/tidb/pull/7027) - - 修复写入 `CURRENT_TIMESTAMP` 时，精度不一致的问题 [#7355](https://github.com/pingcap/tidb/pull/7355) -- DDL - - 改进 DDL 判断 `Schema` 是否已经同步的方法, 避免某些情况下的误判 [#7319](https://github.com/pingcap/tidb/pull/7319) - - 修复在 `ADD INDEX` 过程中的 `SHOW CREATE TABLE` 结果 [#6993](https://github.com/pingcap/tidb/pull/6993) - - 非严格 `sql-mode` 模式下, `text`/`blob`/`json` 的默认值可以为空 [#7230](https://github.com/pingcap/tidb/pull/7230) - - 修复某些特定场景下 `ADD INDEX` 的问题 [#7142](https://github.com/pingcap/tidb/pull/7142) - - 大幅度提升添加 `UNIQUE-KEY` 索引操作的速度 [#7132](https://github.com/pingcap/tidb/pull/7132) - - 修复 Prefix-index 在 UTF-8 字符集的场景下的截断问题 [#7109](https://github.com/pingcap/tidb/pull/7109) - - 增加环境变量 `tidb_ddl_reorg_priority` 来控制 `add-index` 操作的优先级 [#7116](https://github.com/pingcap/tidb/pull/7116) - - 修复 `information_schema.tables` 中 `AUTO-INCREMENT` 的显示问题 [#7037](https://github.com/pingcap/tidb/pull/7037) - - 支持 `admin show ddl jobs ` 命令, 支持输出 number 个 DDL jobs [#7028](https://github.com/pingcap/tidb/pull/7028) - - 支持并行 DDL 任务执行 [#6955](https://github.com/pingcap/tidb/pull/6955) -- [Table Partition](https://github.com/pingcap/tidb/projects/6)（实验性） - - 支持一级分区 - - 支持 `Range Partition` - -## PD - -- 新特性 - - 引入版本控制机制，支持集群滚动兼容升级 - - 开启 `Region merge` 功能 - - 支持 `GetPrevRegion` 接口 - - 支持批量 `split Region` - - 支持存储 GC safepoint -- 功能改进 - - 优化系统时间回退影响 TSO 分配的问题 - - 优化处理 Region heartbeat 的性能 - - 优化 Region tree 性能 - - 优化计算热点统计的性能问题 - - 优化 API 接口错误码返回 - - 新增一些控制调度策略的开关 - - 禁止在 `label` 中使用特殊字符 - - 完善调度模拟器 - - pd-ctl 支持使用统计信息进行 Region split - - pd-ctl 支持调用 `jq` 来格式化 JSON 输出 - - 新增 etcd Raft 状态机相关 metrics -- Bug 修复 - - 修复 leader 切换后 namespace 未重新加载的问题 - - 修复 namespace 调度超出 schedule limit 配置的问题 - - 修复热点调度超出 schedule limit 的问题 - - 修复 PD client 关闭时输出一些错误日志的问题 - - 修复 Region 心跳延迟统计有误的问题 - -## TiKV - -- 新特性 - - 支持 `batch split`，防止热点 Region 写入产生超大 Region - - 支持设置根据数据行数 split Region，提升 index scan 效率 -- 性能优化 - - 使用 `LocalReader` 将 Read 操作从 raftstore 线程分离，减少 Read 延迟 - - 重构 MVCC 框架，优化 memory 使用，提升 scan read 性能 - - 支持基于统计估算进行 Region split，减少 I/O 开销 - - 优化连续写入 Rollback 记录后影响读性能的问题 - - 减少下推聚合计算的内存开销 -- 功能改进 - - 增加大量内建函数下推支持，更完善的 charset 支持 - - 优化 GC 流程，提升 GC 速度并降低 GC 对系统的影响 - - 开启 `prevote`，加快网络异常时的恢复服务速度 - - 增加 RocksDB 日志文件相关的配置项 - - 调整 `scheduler latch` 默认配置 - - 使用 tikv-ctl 手动 compact 时可设定是否 compact RocksDB 最底层数据 - - 增加启动时的环境变量检查 - - 支持基于已有数据动态设置 `dynamic_level_bytes` 参数 - - 支持自定义日志格式 - - tikv-ctl 整合 tikv-fail 工具 - - 增加 threads IO metrics -- Bug 修复 - - 修复 decimal 相关问题 - - 修复 `gRPC max_send_message_len` 设置有误的问题 - - 修复 `region_size` 配置不当时产生的问题 diff --git a/v3.0/releases/21rc2.md b/v3.0/releases/21rc2.md deleted file mode 100644 index 62fef4a8b903..000000000000 --- a/v3.0/releases/21rc2.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: TiDB 2.1 RC2 Release Notes -category: Releases -aliases: ['/docs-cn/releases/21rc2/'] ---- - -# TiDB 2.1 RC2 Release Notes - -2018 年 9 月 14 日，TiDB 发布 2.1 RC2 版。相比 2.1 RC1 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 新版 Planner 设计方案 [#7543](https://github.com/pingcap/tidb/pull/7543) - - 提升常量传播优化规则 [#7276](https://github.com/pingcap/tidb/pull/7276) - - 增强 Range 的计算逻辑使其能够同时处理多个 `IN` 或者等值条件 [#7577](https://github.com/pingcap/tidb/pull/7577) - - 修复当 Range 为空时，`TableScan` 的估算结果不正确的问题 [#7583](https://github.com/pingcap/tidb/pull/7583) - - 为 `UPDATE` 语句支持 `PointGet` 算子 [#7586](https://github.com/pingcap/tidb/pull/7586) - - 修复 `FirstRow` 聚合函数某些情况下在执行过程中 panic 的问题 [#7624](https://github.com/pingcap/tidb/pull/7624) -- SQL 执行引擎 - - 解决 HashJoin 算子在遇到错误的情况下潜在的 DataRace 问题 [#7554](https://github.com/pingcap/tidb/pull/7554) - - HashJoin 算子同时读取内表数据和构建 Hash 表 [#7544](https://github.com/pingcap/tidb/pull/7544) - - 优化 Hash 聚合算子性能 [#7541](https://github.com/pingcap/tidb/pull/7541) - - 优化 Join 算子性能 [#7493](https://github.com/pingcap/tidb/pull/7493)、[#7433](https://github.com/pingcap/tidb/pull/7433) - - 修复 `UPDATE JOIN` 在 Join 顺序改变后结果不正确的问题 [#7571](https://github.com/pingcap/tidb/pull/7571) - - 提升 Chunk 迭代器的性能 [#7585](https://github.com/pingcap/tidb/pull/7585) -- 统计信息 - - 解决重复自动 Analyze 统计信息的问题 [#7550](https://github.com/pingcap/tidb/pull/7550) - - 解决统计信息无变化时更新统计信息遇到错误的问题 [#7530](https://github.com/pingcap/tidb/pull/7530) - - `Analyze` 执行时使用低优先级以及 RC 隔离级别 [#7496](https://github.com/pingcap/tidb/pull/7496) - - 支持只在一天中的某个时间段开启统计信息自动更新的功能 [#7570](https://github.com/pingcap/tidb/pull/7570) - - 修复统计信息写日志时发生的 panic [#7588](https://github.com/pingcap/tidb/pull/7588) - - 支持通过 `ANALYZE TABLE WITH BUCKETS` 语句配置直方图中桶的个数 [#7619](https://github.com/pingcap/tidb/pull/7619) - - 修复更新空的直方图时 panic 的问题 [#7640](https://github.com/pingcap/tidb/pull/7640) - - 使用统计信息更新 `information_schema.tables.data_length` [#7657](https://github.com/pingcap/tidb/pull/7657) -- Server - - 增加 Trace 相关的依赖库 [#7532](https://github.com/pingcap/tidb/pull/7532) - - 开启 Golang 的 mutex profile 功能 [#7512](https://github.com/pingcap/tidb/pull/7512) - - `Admin` 语句需要 `Super_priv` 权限 [#7486](https://github.com/pingcap/tidb/pull/7486) - - 禁止用户 Drop 关键的系统表 [#7471](https://github.com/pingcap/tidb/pull/7471) - - 从 `juju/errors` 切换到 `pkg/errors` [#7151](https://github.com/pingcap/tidb/pull/7151) - - 完成 SQL Tracing 功能原型 [#7016](https://github.com/pingcap/tidb/pull/7016) - - 删除 goroutine pool [#7564](https://github.com/pingcap/tidb/pull/7564) - - 支持使用 `USER1` 信号来查看 goroutine 信息 [#7587](https://github.com/pingcap/tidb/pull/7587) - - 将 TiDB 启动时的内部 SQL 设置为高优先级 [#7616](https://github.com/pingcap/tidb/pull/7616) - - 在监控中用不同的标签区分内部 SQL 和用户 SQL [#7631](https://github.com/pingcap/tidb/pull/7631) - - 缓存最近一周内最慢的 30 条慢查询日志在 TiDB Server 上 [#7646](https://github.com/pingcap/tidb/pull/7646) - - TiDB 集群设置时区的方案 [#7656](https://github.com/pingcap/tidb/pull/7656) - - 丰富 `GC life time is shorter than transaction duration` 错误信息 [#7658](https://github.com/pingcap/tidb/pull/7658) - - 在 TiDB 集群启动时设置集群时区信息 [#7638](https://github.com/pingcap/tidb/pull/7638) -- 兼容性 - - `Year` 类型字段增加 unsigned flag [#7542](https://github.com/pingcap/tidb/pull/7542) - - 修复在 Prepare/Execute 模式下，`Year` 类型结果长度设置问题 [#7525](https://github.com/pingcap/tidb/pull/7525) - - 修复 Prepare/Execute 模式下时间 0 值的处理问题 [#7506](https://github.com/pingcap/tidb/pull/7506) - - 解决整数类型除法实现中的错误处理问题 [#7492](https://github.com/pingcap/tidb/pull/7492) - - 解决 `ComStmtSendLongData` 处理过程中的兼容性问题 [#7485](https://github.com/pingcap/tidb/pull/7485) - - 解决字符串转为整数类型过程中的错误处理问题 [#7483](https://github.com/pingcap/tidb/pull/7483) - - 优化 `information_schema.columns_in_table` 表中的值精度 [#7463](https://github.com/pingcap/tidb/pull/7463) - - 修复使用 MariaDB 客户端对字符串类型数据的写入和更新的兼容性问题 [#7573](https://github.com/pingcap/tidb/pull/7573) - - 修复返回值别名的兼容性问题 [#7600](https://github.com/pingcap/tidb/pull/7600) - - 修复 `information_schema.COLUMNS` 表中浮点数的 `NUMERIC_SCALE` 值不正确的问题 [#7602](https://github.com/pingcap/tidb/pull/7602) - - 解决单行注释内容为空 Parser 报错的问题 [#7612](https://github.com/pingcap/tidb/pull/7612) -- 表达式 - - 在 `insert` 函数中检查 `max_allowed_packet` 的值 [#7528](https://github.com/pingcap/tidb/pull/7528) - - 支持内建函数 `json_contains` [#7443](https://github.com/pingcap/tidb/pull/7443) - - 支持内建函数 `json_contains_path` [#7596](https://github.com/pingcap/tidb/pull/7596) - - 支持内建函数 `encode/decode` [#7622](https://github.com/pingcap/tidb/pull/7622) - - 修复一些时间相关的函数在某些情况下和 MySQL 行为不兼容的问题 [#7636](https://github.com/pingcap/tidb/pull/7636) - - 解决从字符串中解析时间类型数据的兼容性问题 [#7654](https://github.com/pingcap/tidb/pull/7654) - - 解决计算 `DateTime` 类型数据的默认值时没有考虑时区的问题 [#7655](https://github.com/pingcap/tidb/pull/7655) -- DML - - `InsertOnDuplicateUpdate` 语句设置正确的 `last_insert_id` [#7534](https://github.com/pingcap/tidb/pull/7534) - - 减少需要更新 `auto_increment_id` 计数器的情况 [#7515](https://github.com/pingcap/tidb/pull/7515) - - 优化 `Duplicate Key` 错误的报错信息 [#7495](https://github.com/pingcap/tidb/pull/7495) - - 修复 `insert...select...on duplicate key update` 问题 [#7406](https://github.com/pingcap/tidb/pull/7406) - - 支持 `LOAD DATA IGNORE LINES` 语句 [#7576](https://github.com/pingcap/tidb/pull/7576) -- DDL - - 在监控中增加 DDL Job 的类型和当前 Schema 版本的信息 [#7472](https://github.com/pingcap/tidb/pull/7472) - - 完成 `Admin Restore Table` 功能方案设计 [#7383](https://github.com/pingcap/tidb/pull/7383) - - 解决 Bit 类型的默认值超过 128 的问题 [#7249](https://github.com/pingcap/tidb/pull/7249) - - 解决 Bit 类型默认值不能为 `NULL` 的问题 [#7604](https://github.com/pingcap/tidb/pull/7604) - - 减少 DDL 队列中检查 `CREATE TABLE/DATABASE` 任务的时间间隔 [#7608](https://github.com/pingcap/tidb/pull/7608) - - 使用 `ddl/owner/resign` HTTP 接口释放 DDL Owner 并开启新一轮 Owner 选举 [#7649](https://github.com/pingcap/tidb/pull/7649) -- TiKV Go Client - - 支持 `Seek` 操作只获取 `Key` [#7419](https://github.com/pingcap/tidb/pull/7419) -- [Table Partition](https://github.com/pingcap/tidb/projects/6)（实验性） - - 解决无法使用 Bigint 类型列作为 Partition Key 的问题 [#7520](https://github.com/pingcap/tidb/pull/7520) - - 支持 Partitioned Table 添加索引过程中遇到问题回滚操作 [#7437](https://github.com/pingcap/tidb/pull/7437) - -## PD - -- 新特性 - - 支持 `GetAllStores`的接口 [#1228](https://github.com/pingcap/pd/pull/1228) - - Simulator 添加评估调度的统计信息 [#1218](https://github.com/pingcap/pd/pull/1218) -- 功能改进 - - 优化 Down Store 的处理流程，尽快地补副本 [#1222](https://github.com/pingcap/pd/pull/1222) - - 优化 Coordinator 的启动，减少重启 PD 带来的不必要调度 [#1225](https://github.com/pingcap/pd/pull/1225) - - 优化内存使用，减少 heartbeat 带来的内存开销 [#1195](https://github.com/pingcap/pd/pull/1195) - - 优化错误处理，完善日志信息 [#1227](https://github.com/pingcap/pd/pull/1227) - - pd-ctl 支持查询指定 store 的 Region 信息 [#1231](https://github.com/pingcap/pd/pull/1231) - - pd-ctl 支持查询按 version 比对的 topN 的 Region 信息 [#1233](https://github.com/pingcap/pd/pull/1233) - - pd-ctl 支持更精确的 TSO 解码 [#1242](https://github.com/pingcap/pd/pull/1242) -- Bug 修复 - - 修复 pd-ctl 使用 hot store 命令错误退出的问题 [#1244](https://github.com/pingcap/pd/pull/1244) - -## TiKV - -- 性能优化 - - 支持基于统计估算进行 Region split，减少 I/O 开销 [#3511](https://github.com/tikv/tikv/pull/3511) - - 减少部分组件的内存拷贝 [#3530](https://github.com/tikv/tikv/pull/3530) -- 功能改进 - - 增加大量内建函数下推支持 - - 增加 `leader-transfer-max-log-lag` 配置解决特定场景 leader 调度失败的问题 [#3507](https://github.com/tikv/tikv/pull/3507) - - 增加 `max-open-engines` 配置限制 `tikv-importer` 同时打开的 engine 个数 [#3496](https://github.com/tikv/tikv/pull/3496) - - 限制垃圾数据的清理速度，减少对 `snapshot apply` 的影响 [#3547](https://github.com/tikv/tikv/pull/3547) - - 对关键 Raft 消息广播 commit 信息，避免不必要的延迟 [#3592](https://github.com/tikv/tikv/pull/3592) -- Bug 修复 - - 修复新分裂 Region 的 PreVote 消息被丢弃导致的 leader 选举问题 [#3557](https://github.com/tikv/tikv/pull/3557) - - 修复 Region merge 以后 follower 的相关统计信息 [#3573](https://github.com/tikv/tikv/pull/3573) - - 修复 local reader 使用过期 Region 信息的问题 [#3565](https://github.com/tikv/tikv/pull/3565) diff --git a/v3.0/releases/21rc3.md b/v3.0/releases/21rc3.md deleted file mode 100644 index 76196d47dcfb..000000000000 --- a/v3.0/releases/21rc3.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: TiDB 2.1 RC3 Release Notes -category: Releases -aliases: ['/docs-cn/releases/21rc3/'] ---- - -# TiDB 2.1 RC3 Release Notes - -2018 年 9 月 29 日，TiDB 发布 2.1 RC3 版。相比 2.1 RC2 版本，该版本对系统稳定性、兼容性、优化器以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复语句内包含内嵌的 `LEFT OUTER JOIN` 时，结果不正确的问题 [#7689](https://github.com/pingcap/tidb/pull/7689) - - 增强 `JOIN` 语句上的 predicate pushdown 优化规则 [#7645](https://github.com/pingcap/tidb/pull/7645) - - 修复 `UnionScan` 算子的 predicate pushdown 优化规则 [#7695](https://github.com/pingcap/tidb/pull/7695) - - 修复 `Union` 算子的 unique key 属性设置不正确的问题 [#7680](https://github.com/pingcap/tidb/pull/7680) - - 增强常量折叠的优化规则 [#7696](https://github.com/pingcap/tidb/pull/7696) - - 把常量传播后的 filter 是 null 的 data source 优化成 table dual [#7756](https://github.com/pingcap/tidb/pull/7756) -+ SQL 执行引擎 - - 优化事务内读请求的性能 [#7717](https://github.com/pingcap/tidb/pull/7717) - - 优化部分执行器 Chunk 内存分配的开销 [#7540](https://github.com/pingcap/tidb/pull/7540) - - 修复点查全部为 NULL 的列导致数组越界的问题 [#7790](https://github.com/pingcap/tidb/pull/7790) -+ Server - - 修复配置文件里内存配额选项不生效的问题 [#7729](https://github.com/pingcap/tidb/pull/7729) - - 添加 tidb_force_priority 系统变量用来整体设置语句执行的优先级 [#7694](https://github.com/pingcap/tidb/pull/7694) - - 支持使用 `admin show slow` 语句来获取 SLOW QUERY LOG [#7785](https://github.com/pingcap/tidb/pull/7785) -+ 兼容性 - - 修复 `information_schema.schemata` 里 `charset/collation` 结果不正确的问题 [#7751](https://github.com/pingcap/tidb/pull/7751) - - 修复 `hostname` 系统变量的值为空的问题 [#7750](https://github.com/pingcap/tidb/pull/7750) -+ 表达式 - - 内建函数 `AES_ENCRYPT/AES_DECRYPT` 支持 `init_vecter` 参数 [#7425](https://github.com/pingcap/tidb/pull/7425) - - 修复部分表达式 `Format` 结果不正确的问题 [#7770](https://github.com/pingcap/tidb/pull/7770) - - 支持内建函数 `JSON_LENGTH` [#7739](https://github.com/pingcap/tidb/pull/7739) - - 修复 unsigned integer 类型 cast 为 decimal 类型结果不正确的问题 [#7792](https://github.com/pingcap/tidb/pull/7792) -+ DML - - 修复 `INSERT … ON DUPLICATE KEY UPDATE` 语句在 unique key 更新时结果不正确的问题 [#7675](https://github.com/pingcap/tidb/pull/7675) -+ DDL - - 修复在新建的 timestamp 类型的列上新建索引时，索引值没有做时区转换的问题 [#7724](https://github.com/pingcap/tidb/pull/7724) - - 支持 enum 类型 append 新的值 [#7767](https://github.com/pingcap/tidb/pull/7767) - - 快速新建 etcd session，使网络隔离后，集群更快恢复可用 [#7774](https://github.com/pingcap/tidb/pull/7774) - -## PD - -+ 新特性 - - 添加获取按大小逆序排序的 Region 列表 API (/size) [#1254](https://github.com/pingcap/pd/pull/1254) -+ 功能改进 - - Region API 会返回更详细的信息 [#1252](https://github.com/pingcap/pd/pull/1252) -+ Bug 修复 - - 修复 PD 切换 leader 以后 `adjacent-region-scheduler` 可能会导致 crash 的问题 [#1250](https://github.com/pingcap/pd/pull/1250) - -## TiKV - -+ 性能优化 - - 优化函数下推的并发支持 [#3515](https://github.com/tikv/tikv/pull/3515) -+ 新特性 - - 添加对 Log 函数的支持 [#3603](https://github.com/tikv/tikv/pull/3603) - - 添加对 `sha1` 函数的支持 [#3612](https://github.com/tikv/tikv/pull/3612) - - 添加 `truncate_int` 函数的支持 [#3532](https://github.com/tikv/tikv/pull/3532) - - 添加 `year` 函数的支持 [#3622](https://github.com/tikv/tikv/pull/3622) - - 添加 `truncate_real` 函数的支持 [#3633](https://github.com/tikv/tikv/pull/3633) -+ Bug 修复 - - 修正时间函数相关的报错行为 [#3487](https://github.com/tikv/tikv/pull/3487) [#3615](https://github.com/tikv/tikv/pull/3615) - - 修复字符串解析成时间与 TiDB 不一致的问题 [#3589](https://github.com/tikv/tikv/pull/3589) \ No newline at end of file diff --git a/v3.0/releases/21rc4.md b/v3.0/releases/21rc4.md deleted file mode 100644 index 213279a4c52c..000000000000 --- a/v3.0/releases/21rc4.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 2.1 RC4 Release Notes -category: Releases -aliases: ['/docs-cn/releases/21rc4/'] ---- - -# TiDB 2.1 RC4 Release Notes - -2018 年 10 月 23 日，TiDB 发布 2.1 RC4 版。相比 2.1 RC3 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复某些情况下 `UnionAll` 的列裁剪不正确的问题 [#7941](https://github.com/pingcap/tidb/pull/7941) - - 修复某些情况下 `UnionAll` 算子结果不正确的问题 [#8007](https://github.com/pingcap/tidb/pull/8007) -+ SQL 执行引擎 - - 修复 `AVG` 函数的精度问题 [#7874](https://github.com/pingcap/tidb/pull/7874) - - 支持通过 `EXPLAIN ANALYZE` 语句查看 Query 执行过程中各个算子的运行时间，返回结果行数等运行时统计信息 [#7925](https://github.com/pingcap/tidb/pull/7925) - - 修复多次引用同一列时 `PointGet` 算子 panic 的问题 [#7943](https://github.com/pingcap/tidb/pull/7943) - - 修复当 `Limit` 子句中的值太大时 panic 的问题 [#8002](https://github.com/pingcap/tidb/pull/8002) - - 修复某些情况下 `AddDate`/`SubDate` 执行过程中 panic 的问题 [#8009](https://github.com/pingcap/tidb/pull/8009) -+ 统计信息 - - 修复将组合索引的直方图下边界前缀判断为越界的问题 [#7856](https://github.com/pingcap/tidb/pull/7856) - - 修复统计信息收集引发的内存泄漏问题 [#7873](https://github.com/pingcap/tidb/pull/7873) - - 修复直方图为空时 panic 的问题 [#7928](https://github.com/pingcap/tidb/pull/7928) - - 修复加载统计信息时直方图边界越界的问题 [#7944](https://github.com/pingcap/tidb/pull/7944) - - 限制统计信息采样过程中数值的最大长度 [#7982](https://github.com/pingcap/tidb/pull/7982) -+ Server - - 重构 Latch，避免事务冲突误判，提升并发事务的执行性能 [#7711](https://github.com/pingcap/tidb/pull/7711) - - 修复某些情况下收集 Slow Query 导致的 panic 问题 [#7874](https://github.com/pingcap/tidb/pull/7847) - - 修复 `LOAD DATA` 语句中，`ESCAPED BY` 为空字符串时 panic 的问题 [#8005](https://github.com/pingcap/tidb/pull/8005) - - 完善 “coprocessor error” 日志信息 [#8006](https://github.com/pingcap/tidb/pull/8006) -+ 兼容性 - - 当 Query 为空时，将 `SHOW PROCESSLIST` 结果中的 `Command` 字段设置为 “Sleep” [#7839](https://github.com/pingcap/tidb/pull/7839) -+ 表达式 - - 修复 `SYSDATE` 函数被常量折叠的问题 [#7895](https://github.com/pingcap/tidb/pull/7895) - - 修复 `SUBSTRING_INDEX` 在某些情况下 panic 的问题 [#7897](https://github.com/pingcap/tidb/pull/7897) -+ DDL - - 修复抛出 “invalid ddl job type” 的错误时导致栈溢出的问题 [#7958](https://github.com/pingcap/tidb/pull/7958) - - 修复某些情况下 `ADMIN CHECK TABLE` 结果不正确的问题 [#7975](https://github.com/pingcap/tidb/pull/7975) - -## PD - -- 修复下线后的 TiKV 没有从 Grafana 面板中移除的问题 [#1261](https://github.com/pingcap/pd/pull/1261) -- 修复 grpc-go 设置 status 时的 data race 问题[#1265](https://github.com/pingcap/pd/pull/1265) -- 修复 etcd 启动失败导致的服务挂起问题 [#1267](https://github.com/pingcap/pd/pull/1267) -- 修复 leader 切换过程中可能产生的 data race [#1273](https://github.com/pingcap/pd/pull/1273) -- 修复下线 TiKV 时可能输出多余 warning 日志的问题 [#1280](https://github.com/pingcap/pd/pull/1273) - -## TiKV - -- 优化 apply snapshot 导致的 RocksDB Write stall 的问题 [#3606](https://github.com/tikv/tikv/pull/3606) -- 增加 raftstore tick 相关 metrics [#3657](https://github.com/tikv/tikv/pull/3657) -- 升级 RocksDB，修复写入卡死及 IngestExternalFile 时可能写坏源文件的问题 [#3661](https://github.com/tikv/tikv/pull/3661) -- 升级 grpcio，修复 “too many pings” 误报的问题 [#3650](https://github.com/tikv/tikv/pull/3650) diff --git a/v3.0/releases/21rc5.md b/v3.0/releases/21rc5.md deleted file mode 100644 index dd5c33b74385..000000000000 --- a/v3.0/releases/21rc5.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: TiDB 2.1 RC5 Release Notes -category: Releases -aliases: ['/docs-cn/releases/21rc5/'] ---- - - - -# TiDB 2.1 RC5 Release Notes - -2018 年 11 月 12 日，TiDB 发布 2.1 RC5 版。相比 2.1 RC4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复 `IndexReader` 在某些情况下读取的 handle 不正确的问题 [#8132](https://github.com/pingcap/tidb/pull/8132) - - 修复 `IndexScan Prepared` 语句在使用 `Plan Cache` 的时候的问题 [#8055](https://github.com/pingcap/tidb/pull/8055) - - 修复 `Union` 语句结果不稳定的问题 [#8165](https://github.com/pingcap/tidb/pull/8165) -+ 执行器 - - 提升 TiDB 插入和更新宽表的性能 [#8024](https://github.com/pingcap/tidb/pull/8024) - - 内建函数 `Truncate` 支持 unsigned `int` 参数 [#8068](https://github.com/pingcap/tidb/pull/8068) - - 修复转换 JSON 数据到 decimal 类型出错的问题 [#8109](https://github.com/pingcap/tidb/pull/8109) - - 修复 float 类型在 `Update` 时出错的问题 [#8170](https://github.com/pingcap/tidb/pull/8170) -+ 统计信息 - - 修复点查在某些情况下，统计信息出现错误的问题 [#8035](https://github.com/pingcap/tidb/pull/8035) - - 修复统计信息某些情况下在 primary key 的选择率的问题 [#8149](https://github.com/pingcap/tidb/pull/8149) - - 修复被删除的表的统计信息长时间没有清理的问题 [#8182](https://github.com/pingcap/tidb/pull/8182) -+ Server - + 提升日志的可读性，完善日志信息 - - [#8063](https://github.com/pingcap/tidb/pull/8063) - - [#8053](https://github.com/pingcap/tidb/pull/8053) - - [#8224](https://github.com/pingcap/tidb/pull/8224) - - 修复获取 `infoschema.profiling` 表数据出错的问题 [#8096](https://github.com/pingcap/tidb/pull/8096) - - 替换 unix socket，使用 pumps client 来写 binlog [#8098](https://github.com/pingcap/tidb/pull/8098) - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 [#8094](https://github.com/pingcap/tidb/pull/8094) - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 [#8200](https://github.com/pingcap/tidb/pull/8200) - - 增加环境变量 `tidb_opt_write_row_id` 来控制是否允许写入 `_tidb_rowid` [#8218](https://github.com/pingcap/tidb/pull/8218) - - ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8081](https://github.com/pingcap/tidb/pull/8081)，[#8247](https://github.com/pingcap/tidb/pull/8247) -+ DDL - - 修复在事务中某些情况下执行 DDL 语句出错的问题 [#8056](https://github.com/pingcap/tidb/pull/8056) - - 修复 partition 分区表执行 `truncate table` 没有生效的问题 [#8103](https://github.com/pingcap/tidb/pull/8103) - - 修复某些情况下 DDL 操作在被 cancel 之后没有正确回滚的问题 [#8057](https://github.com/pingcap/tidb/pull/8057) - - 增加命令 `admin show next_row_id`，返回下一个可用的行 ID [#8268](https://github.com/pingcap/tidb/pull/8268) - -## PD - -+ 修复 `pd-ctl` 读取 Region key 的相关问题 - - [#1298](https://github.com/pingcap/pd/pull/1298) - - [#1299](https://github.com/pingcap/pd/pull/1299) - - [#1308](https://github.com/pingcap/pd/pull/1308) - -- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -- 修复 PD join 失败后无法重新 join 的问题 [#1279](https://github.com/pingcap/pd/pull/1279) -- 修复某些情况下 watch leader 会丢失事件的问题 [#1317](https://github.com/pingcap/pd/pull/1317) - -## TiKV - -- 优化 `WriteConflict` 报错信息 [#3750](https://github.com/tikv/tikv/pull/3750) -- 增加 panic 标记文件 [#3746](https://github.com/tikv/tikv/pull/3746) -- 降级 grpcio，避免新版本 gRPC 导致的 segment fault 问题 [#3650](https://github.com/tikv/tikv/pull/3650) -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) - -## Tools - -- TiDB 支持 TiDB Binlog cluster，不兼容旧版本 TiDB Binlog [#8093](https://github.com/pingcap/tidb/pull/8093)，[使用文档](/v3.0/reference/tidb-binlog/overview.md) diff --git a/v3.0/releases/2rc1.md b/v3.0/releases/2rc1.md deleted file mode 100644 index be81a3073ac3..000000000000 --- a/v3.0/releases/2rc1.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB 2.0 RC1 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2rc1/'] ---- - -# TiDB 2.0 RC1 Release Notes - -2018 年 3 月 9 日，TiDB 发布 2.0 RC1 版。该版本在上一版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -+ 支持限制单条 SQL 语句使用内存的大小，减少程序 OOM 风险 -+ 支持下推流式聚合算子到 TiKV -+ 支持配置文件的合法性检测 -+ 支持 HTTP API 获取 TiDB 参数信息 -+ Parser 兼容更多 MySQL 语法 -+ 提升对 Navicat 的兼容性 -+ 优化器提升，提取多个 OR 条件的公共表达式，选取更优执行计划 -+ 优化器提升，在更多场景下将子查询转换成 Join 算子，选取更优查询计划 -+ 使用 Batch 方式 Resolve Lock，提升垃圾回收速度 -+ 修复 Boolean 类型的字段长度，提升兼容性 -+ 优化 Add Index 操作，所有的读写操作采用低优先级，减小对在线业务的影响 - -## PD - -+ 优化检查 Region 状态的代码逻辑，提升程序性能 -+ 优化异常情况下日志信息输出，便于调试 -+ 修复监控中关于 TiKV 节点磁盘空间不足情况的统计 -+ 修复开启 TLS 时健康检查接口误报的问题 -+ 修复同时添加副本数量可能超过配置阈值的问题，提升程序稳定性 - -## TiKV - -+ 修复 PD leader 切换，gRPC call 没被 cancel 的问题 -+ 对重要配置进行保护，第一次设置之后不允许变更 -+ 增加获取 metrics 的 gRPC API -+ 启动时候，检查是否使用 SSD -+ 使用 ReadPool 优化读性能，`raw get` 测试性能提升 30% -+ 完善 metrics，优化 metrics 的使用 \ No newline at end of file diff --git a/v3.0/releases/2rc3.md b/v3.0/releases/2rc3.md deleted file mode 100644 index 01510b3bc78f..000000000000 --- a/v3.0/releases/2rc3.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiDB 2.0 RC3 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2rc3/'] ---- - -# TiDB 2.0 RC3 Release Notes - -2018 年 3 月 23 日，TiDB 发布 2.0 RC3 版。该版本在 2.0 RC2 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 修复部分场景下 `MAX/MIN` 结果不正确的问题 -- 修复部分场景下 `Sort Merge Join` 结果未按照 Join Key 有序的问题 -- 修复边界条件下 `uint` 和 `int` 比较的错误 -- 完善浮点数类型的长度和精度检查，提升 MySQL 兼容性 -- 完善时间类型解析报错日志，添加更多错误信息 -- 完善内存控制，新增对 `IndexLookupExecutor` 的内存统计 -- 优化 `ADD INDEX` 的执行速度，部分场景下速度大幅度提升 -- `GROUP BY` 子句为空时使用 Stream Aggregation 算子，提升速度 -- 支持通过 `STRAIGHT_JOIN` 来关闭优化器的 `Join Reorder` 优化 -- `ADMIN SHOW DDL JOBS` 输出更详细的 DDL 任务状态信息 -- 支持 `ADMIN SHOW DDL JOB QUERIES` 查询当前正在运行的 DDL 任务的原始语句 -- 支持 `ADMIN RECOVER INDEX` 命令，用于灾难恢复情况下修复索引数据 -- `ADD INDEX` 操作变更为低优先级，降低对线上业务影响 -- 支持参数为 JSON 类型的 `SUM/AVG` 等聚合函数 -- 支持配置文件修改 `lower_case_table_names` 系统变量，用于支持 OGG 数据同步工具 -- 提升对 Navicat 管理工具的兼容性 -- 支持在 CRUD 操作中使用隐式的行 ID - -## PD - -- 支持 Region Merge，合并数据删除后产生的空 Region 或小 Region -- 添加副本时忽略有大量 pending peer 的节点，提升恢复副本及下线的速度 -- 优化有大量空 Region 时产生的频繁调度问题 -- 优化不同 label 中资源不均衡的场景中 leader balance 调度的速度 -- 添加更多异常 Region 的统计 - -## TiKV - -- 支持 Region Merge -- Raft snapshot 流程完成之后立刻通知 PD，加速调度 -- 增加 Raw DeleteRange API -- 增加 GetMetric API -- 减缓 RocksDB sync 文件造成的 I/O 波动 -- 优化了对 delete 掉数据的空间回收机制 -- 完善数据恢复工具 `tikv-ctl` -- 解决了由于 snapshot 导致下线节点慢的问题 -- Coprocessor 支持 streaming -- 支持 Readpool，`raw_get/get/batch_get` 性能提升 30% -- 支持配置 Coprocessor 请求超时时间 -- Coprocessor 支持 streaming aggregation -- 上报 Region heartbeat 时携带时间信息 -- 限制 snapshot 文件的空间使用，防止占用过多磁盘空间 -- 对长时间不能选出 leader 的 Region 进行记录上报 -- 加速启动阶段的垃圾清理工作 -- 根据 compaction 事件及时更新对应 Region 的 size 信息 -- 对 `scan lock` 的大小进行限制，防止请求超时 -- 使用 `DeleteRange` 加速 Region 删除 -- 支持在线修改 RocksDB 的参数 \ No newline at end of file diff --git a/v3.0/releases/2rc4.md b/v3.0/releases/2rc4.md deleted file mode 100644 index de64d349b841..000000000000 --- a/v3.0/releases/2rc4.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.0 RC4 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2rc4/'] ---- - -# TiDB 2.0 RC4 Release Notes - -2018 年 3 月 30 日，TiDB 发布 2.0 RC4 版。该版本在 2.0 RC3 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 支持 `SHOW GRANTS FOR CURRENT_USER();` -- 修复 `UnionScan` 里的 `Expression` 没有 Clone 的问题 -- 支持 `SET TRANSACTION` 语法 -- 修复 `copIterator` 中潜在的 goroutine 泄露问题 -- 修复 `admin check table` 对包含 null 的 unique index 误判的问题 -- 支持用科学计数法显示浮点数 -- 修复 binary literal 计算时的类型推导 -- 修复解析 `CREATE VIEW` 语句的问题 -- 修复语句中同时包含 `ORDER BY` 和 `LIMIT 0` 时 panic 的问题 -- 提升 `DecodeBytes` 执行性能 -- 优化 `LIMIT 0` 为 `TableDual`，避免无用的执行计划构建 - -## PD - -- 支持手动 split Region，可用于处理单 Region 热点的问题 -- 修复 `pdctl` 运行 `config show all` 不显示 label property 的问题 -- metrics 及代码结构相关的优化 - -## TiKV - -- 限制接收 snapshot 时的内存使用，解决极端情况下的 OOM -- 可以配置 Coprocessor 在遇到 warnings 时的行为 -- TiKV 支持导数据模式 -- 支持 Region 从正中间分裂 -- 提升 CI test 的速度 -- 使用 `crossbeam channel` -- 改善 TiKV 在被隔离的情况下由于 leader missing 输出太多日志的问题 diff --git a/v3.0/releases/2rc5.md b/v3.0/releases/2rc5.md deleted file mode 100644 index 932a8890f0c1..000000000000 --- a/v3.0/releases/2rc5.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB 2.0 RC5 Release Notes -category: Releases -aliases: ['/docs-cn/releases/2rc5/'] ---- - -# TiDB 2.0 RC5 Release Notes - -2018 年 4 月 17 日，TiDB 发布 2.0 RC5 版。该版本在 RC4 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 修复应用 `Top-N` 下推规则的问题 -- 修复对包含 NULL 值的列的行数估算 -- 修复 Binary 类型的 0 值 -- 修复事务内的 `BatchGet` 问题 -- 回滚 `Add Index` 操作的时候，清除清除已写入的数据，减少空间占用 -- 优化 `insert on duplicate key update` 语句性能，提升 10 倍以上 -- 修复 `UNIX_TIMESTAMP` 函数返回结果类型问题返回结果类型问题 -- 修复在添加 NOT NULL 列的过程中，插入 NULL 值的问题 -- `Show Process List` 语句支持显示执行语句的内存占用 -- 修复极端情况下 `Alter Table Modify Column` 出错问题 -- 支持通过 `Alter` 语句设置 table comment - -## PD - -- 添加 Raft Learner 支持 -- 优化 Balance Region Scheduler，减少调度开销 -- 调整默认 `schedule-limit` 配置 -- 修复频繁分配 ID 问题 -- 修复添加调度兼容性问题 - -## TiKV - -- `tikv-ctl` 支持 compact 指定的 Region -- Raw KV 支持 Batch Put、Batch Get、Batch Delete 和 Batch Scan -- 解决太多 snapshot 导致的 OOM 问题 -- Coprocessor 返回更详细的错误信息 -- 支持通过 `tikv-ctl` 动态修改 TiKV 的 `block-cache-size` -- 进一步完善 importer 功能 -- 简化 `ImportSST::Upload` 接口 -- 设置 gRPC 的 `keepalive` 属性 -- `tikv-importer` 作为独立的 binary 从 TiKV 中分离出来 -- 统计 Coprocessor 每个 scan range 命令扫描了多少行数据 -- 解决在 macOS 系统上的编译问题 -- 优化 metric 相关的内容 -- 解决 snapshot 相关的一个潜在 bug -- 解决误用了一个 RocksDB metric 的问题 -- Coprocessor 支持 `overflow as warning` 选项 \ No newline at end of file diff --git a/v3.0/releases/3.0-ga.md b/v3.0/releases/3.0-ga.md deleted file mode 100644 index 2d7962a367a9..000000000000 --- a/v3.0/releases/3.0-ga.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: TiDB 3.0 GA Release Notes -category: Releases ---- - -# TiDB 3.0 GA Release Notes - -发版日期：2019 年 6 月 28 日 - -TiDB 版本：3.0.0 - -TiDB Ansible 版本：3.0.0 - -## Overview - -2019 年 6 月 28 日，TiDB 发布 3.0 GA 版本，对应的 TiDB Ansible 版本为 3.0.0。 -相比于 V2.1，V3.0.0 版本在以下方面有重要改进： - -- 稳定性方面，显著提升了大规模集群的稳定性，集群支持 150+ 存储节点，300+ TB 存储容量长期稳定运行。 -- 易用性方面有显著的提升，降低用户运维成本，例如：标准化慢查询日志，制定日志文件输出规范，新增 `EXPLAIN ANALYZE`，SQL Trace 功能方便排查问题等。 -- 性能方面，与 2.1 相比，TPC-C 性能提升约 4.5 倍，Sysbench 性能提升约 1.5 倍。因支持 View，TPC-H 50G Q15 可正常运行。 -- 新功能方面增加了窗口函数、视图（**实验特性**）、分区表、插件系统、悲观锁（**实验特性**）、`SQL Plan Management` 等特性。 - -## TiDB - -+ 新功能 - - 新增 Window Function，支持所有 MySQL 8.0 中的窗口函数，包括 `NTILE`，`LEAD`，`LAG`、`PERCENT_RANK`、`NTH_VALUE`、`CUME_DIST`、`FIRST_VALUE`、`LAST_VALUE`、`RANK`、`DENSE_RANK`、`ROW_NUMBER` 函数 - - 新增 View 功能（**实验特性**） - - 完善 Table Partition 功能： - - Range Partition - - Hash Partition - - 新增插件系统，官方提供 IP 白名单（**企业版特性**），审记日志（**企业版特性**）等插件 - - 新增 `SQL Plan Management` 功能，通过绑定 SQL 执行计划确保查询的稳定性（**实验特性**） -+ SQL 优化器 - - 优化`NOT EXISTS` 子查询，转化为 Anti Semi Join 提升性能 - - 优化 `Outer Join` 常量传播，新增 `Outer Join` 消除优化规则，避免无效计算，提升性能 - - 优化 `IN` 子查询，先聚合后执行 `Inner Join`，提升性能 - - 优化 Index Join，适应更多的场景，提升性能 - - 优化 Range Partition 的 Partition Pruning 优化规则，提升性能 - - 优化 `_tidb_rowid` 查询逻辑，避免全表扫描，提升性能 - - 当过滤条件中包含相关列时，在抽取复合索引的访问条件时尽可能多地匹配索引的前缀列，提升性能 - - 利用列之间的顺序相关性，提升代价估算准确度 - - 基于统计信息的贪心算法及动态规划算法改进了 `Join Order`，提升多表关联的执行速度 - - 新增 Skyline Pruning，利用规则防止执行计划过于依赖统计信息，提升查询的稳定性 - - 提升单列索引上值为 NULL 时行数估算准确度 - - 新增 `FAST ANALYZE`，通过在各个 Region 中随机采样避免全表扫描的方式提升统计信息收集性能 - - 新增单调递增的索引列增量 `Analyze` 功能，提升统计信息收集性能 - - 支持 `DO` 语句中使用子查询 - - 支持在事务中使用 Index Join - - 优化 `prepare`/`execute`，支持不带参数的 DDL 语句 - - 修改变量 `stats-lease` 值为 0 时系统的行为，使其自动加载统计 - - 新增导出历史统计信息功能 - - 新增导入导出列的关联性信息功能 -+ SQL 执行引擎 - - 优化日志输出，`EXECUTE` 语句输出用户变量，`COMMIT` 语句输出慢查询日志，方便排查问题 - - 新增 `EXPLAIN ANALYZE` 功能，提升SQL 调优易用性 - - 新增 `admin show next_row_id` 功能，方便获取下一行 ID - - 新增`JSON_QUOTE`、`JSON_ARRAY_APPEND`、`JSON_MERGE_PRESERVE`、`BENCHMARK`、`COALESCE`、`NAME_CONST` 6 个内建函数 - - 优化 Chunk 大小控制逻辑，根据查询上下文件动态调整，降低 SQL 执行时间和资源消耗，提升性能 - - 新增 `TableReader`、`IndexReader` 和 `IndexLookupReader` 算子内存追踪控制 - - 优化 Merge Join 算子，使其支持空的 `ON` 条件 - - 优化单个表列较多时写入性能，提升数倍性能 - - 通过支持逆序扫数据提升 `admin show ddl jobs` 的性能 - - 新增 `split table region` 语句，手动分裂表的 Region，缓解热点问题 - - 新增 `split index region` 语句，手动分裂索引的 Region，缓解热点问题 - - 新增黑名单禁止下推表达式到 Coprocessor 功能 - - 优化 Expensive Query 日志，在日志中打印执行时间或者使用内存超过阈值的 SQL 查询 -+ DDL - - 支持字符集从 `utf8` 转换到 `utf8mb4` 的功能 - - 修改默认字符集从 `utf8` 变为 `utf8mb4` - - 新增 `alter schema` 语句修改数据库 charset 和 collation 功能 - - 新增 ALTER ALGORITHM `INPLACE`/`INSTANT` 功能 - - 新增 `SHOW CREATE VIEW` 功能 - - 新增 `SHOW CREATE USER` 功能 - - 新增快速恢复误删除的表功能 - - 新增动态调整 `ADD INDEX` 的并发数功能 - - 新增 pre_split_regions 选项，在 `CREATE TABLE` 时预先分配 Region，缓解建表后大量写入造成的写热点问题 - - 新增通过 SQL 语句指定表的索引及范围分裂 Region，缓解热点问题 - - 新增 `ddl_error_count_limit` 全局变量，控制 DDL 任务重次数 - - 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 - - 优化无效 DDL 元信息存活时间，使集群升级后一段时间 DDL 操作比较慢的情况变短 -+ 事务 - - 新增悲观事务模型（**实验特性**） - - 优化事务处理逻辑，适应更多场景，具体如下： - - `tidb_disable_txn_auto_retry` 的默认值为 `on`，即不会重试非自动提交的事务 - - 新增 `tidb_batch_commit` 系统变量控制将事务拆分成多个事务并发执行 - - 新增 `tidb_low_resolution_tso` 系统变量控制批量获取 `tso` 个数，减少事务获取 `tso` 的次数以适应某些数据一致性要求较低的场景 - - 新增 `tidb_skip_isolation_level_check` 变量控制事务检查隔离级别设置为 SERIALIZABLE 时是否报错 - - 修改 `tidb_disable_txn_auto_retry` 系统变量的行为，修改为影响所有的可重试错误 -+ 权限管理 - - 对 `ANALYZE`、`USE`、`SET GLOBAL`、`SHOW PROCESSLIST` 语句进行权限检查 - - 新增基于角色的权限访问控制功能 (RBAC)（**实验特性**） -+ Server - - 优化慢查询日志，具体包括： - - 重构慢查询日志格式 - - 优化慢查询日志内容 - - 优化查询慢查询日志的方法，通过内存表 `INFORMATION_SCHEMA.SLOW_QUERY`，`ADMIN SHOW SLOW` 语句查询慢查询日志 - - 制定日志格式规范，重构日志系统，方便工具收集分析 - - 新增 SQL 语句管理 TiDB Binlog 服务功能，包括查询状态，开启 TiDB Binlog，维护发送 TiDB Binlog 策略 - - 新增通过 `unix_socket` 方式连接数据库 - - 新增 SQL 语句 `Trace` 功能 - - 新增 `/debug/zip` HTTP 接口，获取 TiDB 实例的信息，方便排查问题 - - 优化监控项，方便排查问题，如下： - - 新增 `high_error_rate_feedback_total` 监控项，监控真实数据量与统计信息估算数据量之间的差距 - - 新增 Database 维度的 QPS 监控项 - - 优化系统初始化流程，仅允许 DDL Owner 执行初始化操作，缩短初始化或升级过程中的启动时间 - - 优化 `kill query` 语句执行逻辑，提升性能，确保资源正确释放 - - 新增启动选项 `config-check` 检查配置文件合法性 - - 新增 `tidb_back_off_weight` 系统变量，控制内部出错重试的退避时间 - - 新增 `wait_timeout`、`interactive_timeout` 系统变量，控制连接空闲超过变量的值，系统自动断开连接。 - - 新增连接 TiKV 的连接池，减少连接创建时间 -+ 兼容性 - - 支持 `ALLOW_INVALID_DATES` SQL mode - - 支持 MySQL 320 握手协议 - - 支持将 unsigned bigint 列声明为自增列 - - 支持 `SHOW CREATE DATABASE IF NOT EXISTS` 语法 - - 优化 load data 对 CSV 文件的容错 - - 过滤条件中包含用户变量时谓词不下推，兼容 MySQL Window Function 中使用用户变量行为 - -## PD - -+ 新增从单个节点重建集群的功能 -+ 将 Region 元信息从 etcd 移到 go-leveldb 存储引擎，解决大规模集群 etcd 存储瓶颈问题 -+ API - - 新增 `remove-tombstone` 接口，用于清理 Tombstone Store - - 新增 `ScanRegions` 接口，用于批量查询 Region 信息 - - 新增 `GetOperator` 接口，用于查询运行中的 Operator - - 优化 `GetStores` 接口的性能 -+ 配置 - - 优化配置检查逻辑，防止配置项错误 - - 新增 `enable-two-way-merge`，用于控制 Region merge 的方向 - - 新增 `hot-region-schedule-limit`，用于控制热点 Region 调度速度 - - 新增 `hot-region-cache-hits-threshold`，连续命中阀值用于判断热点 - - 新增 `store-balance-rate` 配置，用于控制每分钟产生 balance Region Operator 数量的上限 -+ 调度器优化 - - 添加 Store Limit 机制限制调度速度，使得速度限制适用于不同规模的集群 - - 添加 `waitingOperator` 队列，用于优化不同调度器之间资源竞争的问题 - - 支持调度限速功能，主动向 TiKV 下发调度操作，限制单节点同时执行调度任务的个数，提升调度速度 - - Region Scatter 调度不再受 limit 机制限制，提升调度的速度 - - 新增 `shuffle-hot-region` 调度器，解决稳定性测试易用性问题 -+ 模拟器 - - 新增数据导入场景模拟 - - 新增为 Store 设置不同的心跳间隔的功能 -+ 其他 - - 升级 etcd，解决输出日志格式不一致，prevote 时选举不出 Leader，Lease 死锁等问题 - - 制定日志格式规范，重构日志系统，方便工具收集分析 - - 新增调度参数，集群 Label 信息，PD 处理 TSO 请求的耗时，Store ID 与地址信息等监控指标 - -## TiKV - -+ 新增分布式 GC 以及并行 Resolve Lock 功能，提升 GC 的性能 -+ 新增逆向 `raw_scan` 和 `raw_batch_scan` 功能 -+ 新增多线程 Raftstore 和 Apply 功能，提升单节点内可扩展性，提升单节点内并发处理能力，提升单节点的资源利用率，降低延时，同等压力情况下性能提升 70% -+ 新增批量接收和发送 Raft 消息功能，写入密集的场景 TPS 提升 7% -+ 新增 Apply snapshot 之前检查 RocksDB level 0 文件的优化，避免产生 Write stall -+ 新增 Titan 存储引擎插件，提升 Value 超过 1KiB 时系统的性能，一定程度上缓解写放大问题（**实验特性**） -+ 新增悲观事务模型（**实验特性**） -+ 新增通过 HTTP 方式获取监控信息功能 -+ 修改 Insert 语义，仅在 Key 不存在的时候 Prewrite 才成功 -+ 制定日志格式规范，重构日志系统，方便工具收集分析 -+ 新增配置信息，Key 越界相关的性能监控指标 -+ RawKV 使用 Local Reader，提升性能 -+ Engine - - 优化内存管理，减少 `Iterator Key Bound Option` 的内存分配和拷贝，提升性能 - - 支持多个 column family 共享 block cache，提升资源的利用率 -+ Server - - 优化 `batch commands` 的上下文切换开销，提升性能 - - 删除 txn scheduler - - 新增 read index，GC worker 相关监控项 -+ RaftStore - - 新增 hibernate Regions 功能，优化 RaftStore CPU 的消耗（**实验特性**） - - 删除 local reader 线程 -+ Coprocessor - - 重构计算框架，实现向量化算子、向量化表达式计算、向量化聚合，提升性能 - - 支持为 TiDB `EXPLAIN ANALYZE` 语句提供算子执行详情 - - 改用 work-stealing 线程池模型，减少上下文切换 - -## Tools - -+ TiDB Lightning - - 支持数据表重定向同步功能 - - 新增导入 CSV 文件功能 - - 提升 SQL 转 KV 对的性能 - - 单表支持批量导入功能，提升单表导入的性能 - - 支持将大表的数据和索引分别导入，提升 `TiKV-Importer` 导入数据性能 - - 支持对新增文件中缺少 Column 数据时使用 row id 或者列的默认值填充缺少的 column 数据 - - `TiKV-Importer` 支持对 upload SST 到 TiKV 限速功能 -+ TiDB Binlog - - Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 - - Pump 使用 TiKV GetMvccByKey 接口加快事务状态查询 - - 新增组件之间通讯数据压缩功能，减少网络资源消耗 - - 新增 Arbiter 工具支持从 Kafka 读取 binlog 并同步到 MySQL 功能 - - Reparo 支持过滤不需要被同步的文件的功能 - - 新增同步 Generated column 功能 - - 新增 syncer.sql-mode 配置项，支持采用不同的 SQL mode 解析 DDL - - 新增 syncer.ignore-table 配置项，过滤不需要被同步的表 -+ sync-diff-inspector - - 新增 checkpoint 功能，支持从断点继续校验的功能 - - 新增 only-use-checksum 配置项，控制仅通过计算 checksum 校验数据的一致性 - - 新增采用 TiDB 统计信息以及使用多个 Column 划分 Chunk 的功能，适应更多的场景 - -## TiDB Ansible - -- 升级监控组件版本到安全的版本 - - Prometheus 从 2.2.1 升级到 2.8.1 版本 - - Pushgateway 从 0.4.0 升级到 0.7.0 版本 - - Node_exporter 从 0.15.2 升级到 0.17.0 版本 - - Alertmanager 从 0.14.0 升级到 0.17.0 版本 - - Grafana 从 4.6.3 升级到 6.1.6 版本 - - Ansible 从 2.5.14 升级到 2.7.11 版本 -- 新增 TiKV summary 监控面板，方便查看集群状态 -- 新增 TiKV trouble_shooting 监控面板，删除重复项，方便排查问题 -- 新增 TiKV details 监控面板，方便调试排查问题 -- 新增滚动升级并发检测版本是否一致功能，提升滚动升级性能 -- 新增 lightning 部署运维功能 -- 优化 `table-regions.py` 脚本，新增按表显示 leader 分布功能 -- 优化 TiDB 监控，新增以 SQL 类别显示延迟的监控项 -- 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 -- 新增预测集群最大 QPS 的监控项，默认隐藏 diff --git a/v3.0/releases/3.0.0-beta.1.md b/v3.0/releases/3.0.0-beta.1.md deleted file mode 100644 index d7cbcb9d1ac7..000000000000 --- a/v3.0/releases/3.0.0-beta.1.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: TiDB 3.0.0 Beta.1 Release Notes -category: Releases -aliases: ['/docs-cn/releases/3.0.0-beta.1/'] ---- - -# TiDB 3.0.0 Beta.1 Release Notes - -发版日期：2019 年 3 月 26 日 - -TiDB 版本：3.0.0-beta.1 - -TiDB Ansible 版本：3.0.0-beta.1 - -## Overview - -2019 年 03 月 26 日，TiDB 发布 3.0.0 Beta.1 版，对应的 TiDB Ansible 版本为 3.0.0 Beta.1。相比 3.0.0 Beta 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 支持使用 Sort Merge Join 计算笛卡尔积 [#9032](https://github.com/pingcap/tidb/pull/9037) - - 支持 Skyline Pruning，用一些规则来防止执行计划过于依赖统计信息 [#9337](https://github.com/pingcap/tidb/pull/9337) - + 支持 Window Functions - - `NTILE` [#9682](https://github.com/pingcap/tidb/pull/9682) - - `LEAD` 和 `LAG` [#9672](https://github.com/pingcap/tidb/pull/9672) - - `PERCENT_RANK` [#9671](https://github.com/pingcap/tidb/pull/9671) - - `NTH_VALUE` [#9596](https://github.com/pingcap/tidb/pull/9596) - - `CUME_DIST` [#9619](https://github.com/pingcap/tidb/pull/9619) - - `FIRST_VALUE` 和 `LAST_VALUE` [#9560](https://github.com/pingcap/tidb/pull/9560) - - `RANK` 和 `DENSE_RANK` [#9500](https://github.com/pingcap/tidb/pull/9500) - - `RANGE FRAMED` [#9450](https://github.com/pingcap/tidb/pull/9450) - - `ROW FRAMED` [#9358](https://github.com/pingcap/tidb/pull/9358) - - `ROW NUMBER` [#9098](https://github.com/pingcap/tidb/pull/9098) - - 增加了一类统计信息，表示列和 handle 列之间顺序的相关性 [#9315](https://github.com/pingcap/tidb/pull/9315) -+ SQL 执行引擎 - + 增加内建函数 - - `JSON_QUOTE` [#7832](https://github.com/pingcap/tidb/pull/7832) - - `JSON_ARRAY_APPEND` [#9609](https://github.com/pingcap/tidb/pull/9609) - - `JSON_MERGE_PRESERVE` [#8931](https://github.com/pingcap/tidb/pull/8931) - - `BENCHMARK` [#9252](https://github.com/pingcap/tidb/pull/9252) - - `COALESCE` [#9087](https://github.com/pingcap/tidb/pull/9087) - - `NAME_CONST` [#9261](https://github.com/pingcap/tidb/pull/9261) - - 根据查询上下文优化 Chunk 大小，降低 SQL 执行时间和集群的资源消耗 [#6489](https://github.com/pingcap/tidb/issues/6489) -+ 权限管理 - - 支持 `SET ROLE` 和 `CURRENT_ROLE` [#9581](https://github.com/pingcap/tidb/pull/9581) - - 支持 `DROP ROLE` [#9616](https://github.com/pingcap/tidb/pull/9616) - - 支持 `CREATE ROLE` [#9461](https://github.com/pingcap/tidb/pull/9461) -+ Server - - 新增 `/debug/zip` HTTP 接口，获取当前 TiDB 实例的信息 [#9651](https://github.com/pingcap/tidb/pull/9651) - - 支持使用 `show pump status`/`show drainer status` 语句查看 Pump/Drainer 状态 [#9456](https://github.com/pingcap/tidb/pull/9456) - - 支持使用 SQL 语句在线修改 Pump/Drainer 状态 [#9789](https://github.com/pingcap/tidb/pull/9789) - - 支持给 SQL 文本加上 HASH 指纹，方便追查慢 SQL [#9662](https://github.com/pingcap/tidb/pull/9662) - - 新增 `log_bin` 系统变量，默认：0，管理 binlog 开启状态，当前仅支持查看状态 [#9343](https://github.com/pingcap/tidb/pull/9343) - - 支持通过配置文件管理发送 binlog 策略 [#9864](https://github.com/pingcap/tidb/pull/9864) - - 支持通过内存表 `INFORMATION_SCHEMA.SLOW_QUERY` 查询慢日志 [#9290](https://github.com/pingcap/tidb/pull/9290) - - 将 TiDB 显示的 MySQL Version 从 5.7.10 变更为 5.7.25 [#9553](https://github.com/pingcap/tidb/pull/9553) - - 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 - - 增加监控项 `high_error_rate_feedback_total`，记录实际数据量与统计信息估算数据量差距情况 [#9209](https://github.com/pingcap/tidb/pull/9209) - - 新增 Database 维度的 QPS 监控项 , 可以通过配置项开启 [#9151](https://github.com/pingcap/tidb/pull/9151) -+ DDL - - 增加`ddl_error_count_limit`全局变量，默认值：512，限制 DDL 任务重试次数，超过限制次数会取消出错的 DDL [#9295](https://github.com/pingcap/tidb/pull/9295) - - 支持 ALTER ALGORITHM `INPLACE`/`INSTANT` [#8811](https://github.com/pingcap/tidb/pull/8811) - - 支持 `SHOW CREATE VIEW` 语句 [#9309](https://github.com/pingcap/tidb/pull/9309) - - 支持 `SHOW CREATE USER` 语句 [#9240](https://github.com/pingcap/tidb/pull/9240) - -## PD - -+ 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 -+ 模拟器 - - 支持不同 store 可采用不同的心跳间隔时间 [#1418](https://github.com/pingcap/pd/pull/1418) - - 添加导入数据的场景 [#1263](https://github.com/pingcap/pd/pull/1263) -+ 热点调度可配置化 [#1412](https://github.com/pingcap/pd/pull/1412) -+ 增加 store 地址为维度的监控项，代替原有的 Store ID [#1429](https://github.com/pingcap/pd/pull/1429) -+ 优化 `GetStores` 开销，加快 Region 巡检周期 [#1410](https://github.com/pingcap/pd/pull/1410) -+ 新增删除 Tombstone Store 的接口 [#1472](https://github.com/pingcap/pd/pull/1472) - -## TiKV - -+ 优化 Coprocessor 计算执行框架，完成 TableScan 算子，单 TableScan 即扫表操作性能提升 5% ~ 30% -实现行 `BatchRows` 和列 `BatchColumn` 的定义 [#3660](https://github.com/tikv/tikv/pull/3660) - - 实现 `VectorLike` 使得编码和解码的数据能够用统一的方式访问 [#4242](https://github.com/tikv/tikv/pull/4242) - - 定义 `BatchExecutor` 接口，实现将请求转化为 `BatchExecutor` 的方法 [#4243](https://github.com/tikv/tikv/pull/4243) - - 实现将表达式树转化成 RPN 格式 [#4329](https://github.com/tikv/tikv/pull/4329) - - TableScan 算子实现为 Batch 方式，通过向量化计算加速计算 [#4351](https://github.com/tikv/tikv/pull/4351) -+ 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 -+ 支持 Raw Read 接口使用 Local Reader 进行读 [#4222](https://github.com/tikv/tikv/pull/4222) -+ 新增配置信息的 Metrics [#4206](https://github.com/tikv/tikv/pull/4206) -+ 新增 Key 越界的 Metrics [#4255](https://github.com/tikv/tikv/pull/4255) -+ 新增碰到扫越界错误时 Panic 或者报错选项 [#4254](https://github.com/tikv/tikv/pull/4254) -+ 增加 Insert 语义，只有在 Key 不存在的时候 Prewrite 才成功，消除 Batch Get [#4085](https://github.com/tikv/tikv/pull/4085) -+ Batch System 使用更加公平的 batch 策略 [#4200](https://github.com/tikv/tikv/pull/4200) -+ tikv-ctl 支持 Raw scan [#3825](https://github.com/tikv/tikv/pull/3825) - -## Tools - -+ TiDB Binlog - - 新增 Arbiter 工具支持从 Kafka 读取 binlog 同步到 MySQL - - Reparo 支持过滤不需要同步的文件 - - 支持同步 generated column -+ Lightning - - 支持禁用 TiKV periodic Level-1 compaction，当 TiKV 集群为 2.1.4 或更高时，在导入模式下会自动执行 Level-1 compaction [#119](https://github.com/pingcap/tidb-lightning/pull/119)，[#4199](https://github.com/tikv/tikv/pull/4199) - - 根据 `table_concurrency` 配置项限制 import engines 数量，默认值：16，防止过多占用 importer 磁盘空间 [#119](https://github.com/pingcap/tidb-lightning/pull/119) - - 支持保存中间状态的 SST 到磁盘，减少内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 优化 TiKV-Importer 导入性能，支持将大表的数据和索引分离导入 [#132](https://github.com/pingcap/tidb-lightning/pull/132) - - 支持 CSV 文件导入 [#111](https://github.com/pingcap/tidb-lightning/pull/111) -+ 数据同步对比工具 (sync-diff-inspector) - - 支持使用 TiDB 统计信息来划分对比的 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) - - 支持使用多个 column 来划分对比的 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) diff --git a/v3.0/releases/3.0.0-rc.1.md b/v3.0/releases/3.0.0-rc.1.md deleted file mode 100644 index b2c518cefd3e..000000000000 --- a/v3.0/releases/3.0.0-rc.1.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: TiDB 3.0.0-rc.1 Release Notes -category: Releases -aliases: ['/docs-cn/releases/3.0.0-rc.1/'] ---- - -# TiDB 3.0.0-rc.1 Release Notes - -发版日期：2019 年 5 月 10 日 - -TiDB 版本：3.0.0-rc.1 - -TiDB Ansible 版本：3.0.0-rc.1 - -## Overview - -2019 年 5 月 10 日，TiDB 发布 3.0.0-rc.1 版，对应的 TiDB Ansible 版本为 3.0.0-rc.1。相比 3.0.0-beta.1 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 利用列之间的顺序相关性提升代价估算准确度，并提供启发式参数 `tidb_opt_correlation_exp_factor` 用于控制在相关性无法被直接用于估算的场景下对索引扫描的偏好程度。[#9839](https://github.com/pingcap/tidb/pull/9839) - - 当过滤条件中包含相关列时，在抽取复合索引的访问条件时尽可能多地匹配索引的前缀列。[#10053](https://github.com/pingcap/tidb/pull/10053) - - 用动态规划决定连接的执行顺序，当参与连接的表数量不多于 `tidb_opt_join_reorder_threshold` 时启用。[#8816](https://github.com/pingcap/tidb/pull/8816) - - 在构造 Index Join 的的内表中，以复合索引作为访问条件时，尽可能多地匹配索引的前缀列。[#8471](https://github.com/pingcap/tidb/pull/8471) - - 提升对单列索引上值为 NULL 的行数估算准确度。[#9474](https://github.com/pingcap/tidb/pull/9474) - - 在逻辑优化阶段消除聚合函数时特殊处理 `GROUP_CONCAT` ，防止产生错误的执行结果。[#9967](https://github.com/pingcap/tidb/pull/9967) - - 当过滤条件为常量时，正确地将它下推到连接算子的子节点上。[#9848](https://github.com/pingcap/tidb/pull/9848) - - 在逻辑优化阶段列剪裁时特殊处理一些函数，例如 `RAND()` ，防止产生和 MySQL 不兼容的执行结果。[#10064](https://github.com/pingcap/tidb/pull/10064) - - 支持 `FAST ANALYZE`，通过`tidb_enable_fast_analyze` 变量控制。该特性通过用对 Region 进行采样取代扫描整个 region 的方式加速统计信息收集。[#10258](https://github.com/pingcap/tidb/pull/10258) - - 支持 `SQL PLAN MANAGEMENT`。该特性通过对 SQL 进行执行计划绑定，以确保执行稳定性。该特性目前处于测试阶段，仅支持对 SELECT 语句使用绑定的执行计划，不建议在生产场景中直接使用。[#10284](https://github.com/pingcap/tidb/pull/10284) - -+ 执行引擎 - - 支持对 `TableReader`、`IndexReader` 和 `IndexLookupReader` 算子进行内存追踪控制。[#10003](https://github.com/pingcap/tidb/pull/10003) - - 在慢日志中展示更多 COPROCESSOR 端执行任务相关细节。如 COPROCESSOR 任务数，平均/最长/90% 执行/等待时间，执行/等待时间最长的 TiKV 地址等。[#10165](https://github.com/pingcap/tidb/pull/10165) - - 支持 PREPARE 不含占位符的 DDL 语句。[#10144](https://github.com/pingcap/tidb/pull/10144) - -+ Server - - TiDB 启动时，只允许 DDL owner 执行 bootstrap [#10029](https://github.com/pingcap/tidb/pull/10029) - - 新增 `tidb_skip_isolation_level_check` 变量控制检查隔离级别设置为 SERIALIZABLE 时不报错 [#10065](https://github.com/pingcap/tidb/pull/10065) - - 在慢日志中，将隐式提交的时间与 SQL 执行时间融合在一起 [#10294](https://github.com/pingcap/tidb/pull/10294) - + RBAC 权限管理 - - 支持 `SHOW GRANT` [#10016](https://github.com/pingcap/tidb/pull/10016) - - 支持 `SET DEFAULT ROLE` [#9949](https://github.com/pingcap/tidb/pull/9949) - - 支持 `GRANT ROLE` [#9721](https://github.com/pingcap/tidb/pull/9721) - - 修正了插件退出时导致 TiDB 退出的问题 [#9889](https://github.com/pingcap/tidb/pull/9889) - - 修正只读语句被错误地放到事务历史中的问题 [#9723](https://github.com/pingcap/tidb/pull/9723) - - kill 语句可以更快的结束 SQL 的执行，并快速释放资源 [#9844](https://github.com/pingcap/tidb/pull/9844) - - 增加启动选项 `config-check` 来检查配置文件的合法性 [#9855](https://github.com/pingcap/tidb/pull/9855) - - 修正非严格模式下对于写入 NULL 字段的合法性检查 [#10161](https://github.com/pingcap/tidb/pull/10161) - -+ DDL - - 为 CREATE TABLE 添加了 pre_split_regions 选项，该选项可以在建表时预先分配 Table Region，避免建表后大量写入造成的写热点 [#10138](https://github.com/pingcap/tidb/pull/10138) - - 优化了部分 DDL 语句的执行性能 [#10170](https://github.com/pingcap/tidb/pull/10170) - - FULLTEXT KEY 新增不支持全文索引的 warning [#9821](https://github.com/pingcap/tidb/pull/9821) - - 修正了旧版本 TiDB 中，UTF8 和 UTF8MB4 编码的兼容性问题 [#9820](https://github.com/pingcap/tidb/pull/9820) - - 修正了一个表的 shard_row_id_bits 的潜在 BUG [#9868](https://github.com/pingcap/tidb/pull/9868) - - 修正了 ALTER TABLE Charset 后，Column Charset 不会跟随变化的 BUG [#9790](https://github.com/pingcap/tidb/pull/9790) - - 修正了使用 BINARY/BIT 作为 Column Default Value 时，SHOW COLUMN 可能出错的 BUG [#9897](https://github.com/pingcap/tidb/pull/9897) - - 修正了 SHOW FULL COLUMNS 语句中，CHARSET / COLLATION 显示的兼容性问题 [#10007](https://github.com/pingcap/tidb/pull/10007) - - 现在 SHOW COLLATIONS 语句只会列出 TiDB 所实际支持的 COLLATIONS [#10186](https://github.com/pingcap/tidb/pull/10186) - -## PD - -+ 升级 ETCD 版本 [#1452](https://github.com/pingcap/pd/pull/1452) - - 统一 etcd 的日志格式与 pd server 一致 - - 修复 prevote 可能无法选出 Leader 的问题 - - 快速 drop 掉会失败的 propose 和 read 请求，减少阻塞后面的请求时间 - - 修复 Lease 的死锁问题 -+ 修复 store 读热点的 keys 统计不正确问题 [#1487](https://github.com/pingcap/pd/pull/1487) -+ 支持从单一 PD 节点强制重建 PD 集群 [#1485](https://github.com/pingcap/pd/pull/1485) -+ 修复 Scatter Region 产生无效 Operator Step 的问题 [#1482](https://github.com/pingcap/pd/pull/1482) -+ 修复 Region Merge Operator 超时时间过短的问题 [#1495](https://github.com/pingcap/pd/pull/1495) -+ 热点调度使用高优先级 [#1492](https://github.com/pingcap/pd/pull/1492) -+ 添加 PD server 端处理 TSO 请求的耗时 Metrics [#1502](https://github.com/pingcap/pd/pull/1502) -+ 添加相对应的 Store ID 和 Address 到 store 相关的 Metrics [#1506](https://github.com/pingcap/pd/pull/1506) -+ 支持 GetOperator 服务 [#1477](https://github.com/pingcap/pd/pull/1477) -+ 修复 Heartbeat stream 下发送 error 找不到 store 的问题 [#1521](https://github.com/pingcap/pd/pull/1521) - -## TiKV - -+ Engine - - 修复读流量统计不准确问题 [#4436](https://github.com/tikv/tikv/pull/4436) - - 修复 prefix extractor panic 的问题 [#4503](https://github.com/tikv/tikv/pull/4503) - - 优化内存管理，减少 `Iterator Key Bound Option` 的内存分配和拷贝 [#4537](https://github.com/tikv/tikv/pull/4537) - - 修复 Merge Region 时未考虑 Learner log gap 造成的 panic 问题 [#4559](https://github.com/tikv/tikv/pull/4559) - - 支持不同的 `column families` 共享 `block cache` [#4612](https://github.com/tikv/tikv/pull/4612) -+ Server - - 减少 `batch commands` 的上下文切换开销 [#4473](https://github.com/tikv/tikv/pull/4473) - - 检查 seek iterator status 的合法性 [#4470](https://github.com/tikv/tikv/pull/4470) -+ RaftStore - - 可配置化 `properties index distance` [#4517](https://github.com/tikv/tikv/pull/4517) -+ Coprocessor - - 新增 batch index scan executor [#4419](https://github.com/tikv/tikv/pull/4419) - - 新增向量化 evaluation 框架 [#4322](https://github.com/tikv/tikv/pull/4322) - - 新增 batch 执行器统计框架 [#4433](https://github.com/tikv/tikv/pull/4433) - - 构建 RPN expression 时检查 max column 以防止 evaluation 阶段 column offset 越界的问题 [#4481](https://github.com/tikv/tikv/pull/4481) - - 实现 `BatchLimitExecutor` [#4469](https://github.com/tikv/tikv/pull/4469) - - ReadPool 使用 `tokio-threadpool` 替换原本的 `futures-cpupool`，减少 context switch [#4486](https://github.com/tikv/tikv/pull/4486) - - 新增 batch 聚合框架 [#4533](https://github.com/tikv/tikv/pull/4533) - - 新增 `BatchSelectionExecutor` [#4562](https://github.com/tikv/tikv/pull/4562) - - 实现 batch aggression function `AVG` [#4570](https://github.com/tikv/tikv/pull/4570) - - 实现 RPN function `LogicalAnd` [#4575](https://github.com/tikv/tikv/pull/4575) -+ Misc - - 支持选用 tcmalloc 为内存分配器 [#4370](https://github.com/tikv/tikv/pull/4370) - -## Tools - -+ TiDB Binlog - - 修复 unsigned int 类型的主键列的 binlog 数据为负数，造成同步出错中断的问题 [#573](https://github.com/pingcap/tidb-binlog/pull/573) - - 删除下游是 pb 时的压缩选项，修改下游名字 pb 成 file [#559](https://github.com/pingcap/tidb-binlog/pull/559) - - Pump 新增 storage.sync-log 配置项，支持 Pump 本地存储异步刷盘 [#509](https://github.com/pingcap/tidb-binlog/pull/509) - - Pump 和 Drainer 之间通讯支持流量压缩 [#495](https://github.com/pingcap/tidb-binlog/pull/495) - - Drainer 新增 syncer.sql-mode 配置项，支持使用不同 sql-mode 解析 DDL query [#511](https://github.com/pingcap/tidb-binlog/pull/511) - - Drainer 新增 syncer.ignore-table 配置项，支持过滤不需要同步的表 [#520](https://github.com/pingcap/tidb-binlog/pull/520) -+ Lightning - - 使用 row id 或者列的默认值填充 dump 文件中缺少的 column 数据 [#170](https://github.com/pingcap/tidb-lightning/pull/170) - - Importer 修复部分 SST 导入失败依然返回导入成功的 bug [#4566](https://github.com/tikv/tikv/pull/4566) - - Importer 支持 upload SST 到 TiKV 限速 [#4412](https://github.com/tikv/tikv/pull/4412) - - Lightning 优化导入表的顺序，按照表的数据大小顺序进行导入，减少导入过程中大表执行 checksum 和 Analyze 对集群的影响，并且提高 Checksum 和 Analyze 的成功率 [#156](https://github.com/pingcap/tidb-lightning/pull/156) - - 提升 Lightning encode SQL 性能，性能提升 50%，直接解析数据源文件内容成 TiDB 的 types.Datum，省去 KV encoder 的多余解析工作 [#145](https://github.com/pingcap/tidb-lightning/pull/145) - - 日志格式改为 [Unified Log Format](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md) [#162](https://github.com/pingcap/tidb-lightning/pull/162) - - 新增一些命令行选项，即使缺少配置文件也能使用。[#157](https://github.com/pingcap/tidb-lightning/pull/157) -+ 数据同步对比工具 (sync-diff-inspector) - - 支持 checkpoint，记录校验状态，重启后从上次进度继续校验 [#224](https://github.com/pingcap/tidb-tools/pull/224) - - 增加配置项 only-use-checksum，只通过计算 checksum 来检查数据是否一致 [#215](https://github.com/pingcap/tidb-tools/pull/215) - -## TiDB Ansible - -+ TiKV 监控变更以及更新 Ansible、Grafana、Prometheus 版本 [#727](https://github.com/pingcap/tidb-ansible/pull/727) - - summary 监控适用于用户查看集群状态 - - trouble_shooting 监控适用于 DBA 排查问题 - - details 监控适用于开发分析问题 -+ 修复下载 Kafka 版本 Binlog 失败的 BUG [#730](https://github.com/pingcap/tidb-ansible/pull/730) -+ 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 [#733](https://github.com/pingcap/tidb-ansible/pull/733) -+ 滚动升级时的版本检测改为多并发 [#736](https://github.com/pingcap/tidb-ansible/pull/736) -+ 更新 README 中文档链接[#740](https://github.com/pingcap/tidb-ansible/pull/740) -+ 移除重复的 TiKV 监控项，新增 trouble shooting 监控项 [#735](https://github.com/pingcap/tidb-ansible/pull/735) -+ 优化 `table-regions.py` 脚本，按表显示 leader 分布 [#739](https://github.com/pingcap/tidb-ansible/pull/739) -+ 更新 drainer 配置文件 [#745](https://github.com/pingcap/tidb-ansible/pull/745) -+ 优化 TiDB 监控，新增以 SQL 类别显示延迟的监控项 [#747](https://github.com/pingcap/tidb-ansible/pull/747) -+ 更新 Lightning 配置文件，新增 tidb_lightning_ctl 脚本 [#1e946f8](https://github.com/pingcap/tidb-ansible/commit/1e946f89908e8fd6ef84128c6da3064ddfccf6a8) diff --git a/v3.0/releases/3.0.0-rc.2.md b/v3.0/releases/3.0.0-rc.2.md deleted file mode 100644 index 9d6ed2c9c279..000000000000 --- a/v3.0/releases/3.0.0-rc.2.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: TiDB 3.0.0-rc.2 Release Notes -category: Releases -aliases: ['/docs-cn/releases/3.0.0-rc.2/'] ---- - -# TiDB 3.0.0-rc.2 Release Notes - -发版日期：2019 年 5 月 28 日 - -TiDB 版本：3.0.0-rc.2 - -TiDB Ansible 版本：3.0.0-rc.2 - -## Overview - -2019 年 5 月 28 日，TiDB 发布 3.0.0-rc.2 版本，对应的 TiDB Ansible 版本为 3.0.0-rc.2。相比 3.0.0-rc.1 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 在更多的场景中支持 Index Join [#10540](https://github.com/pingcap/tidb/pull/10540) - - 支持导出历史统计信息 [#10291](https://github.com/pingcap/tidb/pull/10291) - - 支持对单调递增的索引列增量 `Analyze` [#10355](https://github.com/pingcap/tidb/pull/10355) - - 忽略 `Order By` 子句中的 NULL 值 [#10488](https://github.com/pingcap/tidb/pull/10488) - - 修复精简列信息时逻辑算子 `UnionAll` 的 Schema 信息的计算不正确的问题 [#10384](https://github.com/pingcap/tidb/pull/10384) - - 下推 `Not` 操作符时避免修改原表达式 [#10363](https://github.com/pingcap/tidb/pull/10363) - - 支持导入导出列的关联性信息 [#10573](https://github.com/pingcap/tidb/pull/10573) - -+ 执行引擎 - - 有唯一索引的虚拟生成列可以在 `replace on duplicate key update`/`insert on duplicate key update` 语句中被正确地处理 [#10370](https://github.com/pingcap/tidb/pull/10370) - - 修复 CHAR 列上的扫描范围计算 [#10124](https://github.com/pingcap/tidb/pull/10124) - - 修复 `PointGet` 处理负数不正确问题 [#10113](https://github.com/pingcap/tidb/pull/10113) - - 合并具有相同窗口名的窗口函数，提高执行效率 [#9866](https://github.com/pingcap/tidb/pull/9866) - - 窗口函数中 Range Frame 可以无需 `Order By` 子句 [#10496](https://github.com/pingcap/tidb/pull/10496) - -+ Server - - 修复 TiKV 故障时，TiDB 不断创建与 TiKV 的新连接的问题 [#10301](https://github.com/pingcap/tidb/pull/10301) - - `tidb_disable_txn_auto_retry` 不再只影响写入冲突错误，而是影响所有的可重试错误 [#10339](https://github.com/pingcap/tidb/pull/10339) - - 不带参数的 DDL 语句可以通过 `prepare`/`execute` 来执行 [#10144](https://github.com/pingcap/tidb/pull/10144) - - 新增 `tidb_back_off_weight` 变量，控制 TiDB 内部 back off 时间的长短 [#10266](https://github.com/pingcap/tidb/pull/10266) - - `tidb_disable_txn_auto_retry` 的默认值改为 on，即默认情况下，TiDB 不会重试非自动提交的事务 [#10266](https://github.com/pingcap/tidb/pull/10266) - - 修复 RBAC 中对 role 的数据库权限的判断不正确的问题 [#10261](https://github.com/pingcap/tidb/pull/10261) - - 支持悲观事务模型（实验性）[#10297](https://github.com/pingcap/tidb/pull/10297) - - 降低某些情况下处理锁冲突时的等待时间 [#10006](https://github.com/pingcap/tidb/pull/10006) - - 重构 Region cache，增加在 Region 故障时的轮询逻辑 [#10256](https://github.com/pingcap/tidb/pull/10256) - - 新增 `tidb_low_resolution_tso` 变量，控制批量获取 `tso` 个数，减少事务获取 `tso` 的次数，以适应某些数据一致性要求较低的场景 [#10428](https://github.com/pingcap/tidb/pull/10428) - -+ DDL - - 修复旧版本的 TiDB 存储的字符集名称大写的问题 [#10272](https://github.com/pingcap/tidb/pull/10272) - - 支持 table partition 预分裂 Region 功能，该选项可以在建表时预先分配 table Region，避免建表后大量写入造成的写热点 [#10221](https://github.com/pingcap/tidb/pull/10221) - - 修复某些情况下 TiDB 更新版本信息到 PD 不准确的问题 [#10324](https://github.com/pingcap/tidb/pull/10324) - - 支持通过 `alter schema` 语句修改数据库 charset 和 collation [#10393](https://github.com/pingcap/tidb/pull/10393) - - 支持通过语句按指定表的索引及范围分裂 Region，用于缓解热点问题 [#10203](https://github.com/pingcap/tidb/pull/10203) - - 禁止 `alter table` 语句修改 `decimal` 列的精度 [#10433](https://github.com/pingcap/tidb/pull/10433) - - 修复 hash partition 中对表达式和函数的约束 [#10273](https://github.com/pingcap/tidb/pull/10273) - - 修复某些情况下对含有 partition 的 table 添加索引时引发 TiDB panic 的问题 [#10475](https://github.com/pingcap/tidb/pull/10475) - - 添加对某些极端情况下导致 schema 出错的防护功能 [#10464](https://github.com/pingcap/tidb/pull/10464) - - 创建 range partition 若有单列或者创建 hash partition 时默认开启分区功能 [#9936](https://github.com/pingcap/tidb/pull/9936) - -## PD - -- 默认开启 Region storage 将 Region 元信息存储到 Region storage 中 [#1524](https://github.com/pingcap/pd/pull/1524) -- 修复热点调度受其他调度器抢占的问题 [#1522](https://github.com/pingcap/pd/pull/1522) -- 修复 Leader 优先级不生效的问题 [#1533](https://github.com/pingcap/pd/pull/1533) -- 新增 `ScanRegions` 的 gRPC 接口 [#1535](https://github.com/pingcap/pd/pull/1535) -- 主动下发 operator 加快调度速度 [#1536](https://github.com/pingcap/pd/pull/1536) -- 添加 store limit 机制，限制单个 store 的调度速度 [#1474](https://github.com/pingcap/pd/pull/1474) -- 修复 `config` 状态不一致的问题 [#1476](https://github.com/pingcap/pd/pull/1476) - -## TiKV - -+ Engine - - 支持多个 column family 共享 block cache [#4563](https://github.com/tikv/tikv/pull/4563) -+ Server - - 移除 txn scheduler [#4098](https://github.com/tikv/tikv/pull/4098) - - 支持悲观锁事务 [#4698](https://github.com/tikv/tikv/pull/4698) -+ Raftstore - - 新增 hibernate Regions 特性，减少 raftstore CPU 的消耗 [#4591](https://github.com/tikv/tikv/pull/4591) - - 移除 local reader 线程 [#4558](https://github.com/tikv/tikv/pull/4558) - - 修复 Leader 不回复 Learner `ReadIndex` 请求的问题 [#4653](https://github.com/tikv/tikv/pull/4653) - - 修复在某些情况下 transfer leader 失败的问题 [#4684](https://github.com/tikv/tikv/pull/4684) - - 修复在某些情况下可能发生的脏读问题 [#4688](https://github.com/tikv/tikv/pull/4688) - - 修复在某些情况下 snapshot 少包含数据的问题 [#4716](https://github.com/tikv/tikv/pull/4716) -+ Coprocessor - - 新增更多的 RPN 函数 - - `LogicalOr` [#4691](https://github.com/tikv/tikv/pull/4601) - - `LTReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `LEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `GTReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `GEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `NEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `EQReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `IsNull` [#4720](https://github.com/tikv/tikv/pull/4720) - - `IsTrue` [#4720](https://github.com/tikv/tikv/pull/4720) - - `IsFalse` [#4720](https://github.com/tikv/tikv/pull/4720) - - 支持 `Int` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Decimal` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `String` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Time` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Duration` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Json` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Int` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Real` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Decimal` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Int` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Real` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Decimal` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Int` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - - 支持 `Real` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - - 支持 `Decimal` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - -## Tools - -+ TiDB Binlog - - Drainer 增加下游同步延迟监控项 `checkpoint_delay` [#594](https://github.com/pingcap/tidb-binlog/pull/594) - -+ TiDB Lightning - - 支持数据库合并，数据表合并同步功能 [#95](https://github.com/pingcap/tidb-lightning/pull/95) - - 新增 KV 写入失败重试机制 [#176](https://github.com/pingcap/tidb-lightning/pull/176) - - 配置项 `table-concurrency` 默认值修改为 6 [#175](https://github.com/pingcap/tidb-lightning/pull/175) - - 减少必要的配置项，`tidb.port` 和 `tidb..pd-addr` 支持自动获取 [#173](https://github.com/pingcap/tidb-lightning/pull/173) diff --git a/v3.0/releases/3.0.0-rc.3.md b/v3.0/releases/3.0.0-rc.3.md deleted file mode 100644 index 141b3c897e54..000000000000 --- a/v3.0/releases/3.0.0-rc.3.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: TiDB 3.0.0-rc.3 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.3 Release Notes - -发版日期：2019 年 6 月 21 日 - -TiDB 版本：3.0.0-rc.3 - -TiDB Ansible 版本：3.0.0-rc.3 - -## Overview - -2019 年 6 月 21 日，TiDB 发布 3.0.0-rc.3 版本，对应的 TiDB Ansible 版本为 3.0.0-rc.3。相比 3.0.0-rc.2 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 删除收集虚拟生成列的统计信息功能 [#10629](https://github.com/pingcap/tidb/pull/10629) - - 修复点查时主键常量溢出的问题 [#10699](https://github.com/pingcap/tidb/pull/10699) - - 修复 `fast analyze` 因使用未初始化的信息导致 panic [#10691](https://github.com/pingcap/tidb/pull/10691) - - 修复 prepare `create view` 语句执行过程中因列信息错误导致执行失败的问题 [#10713](https://github.com/pingcap/tidb/pull/10713) - - 修复在处理 window function 时列信息未拷贝的问题 [#10720](https://github.com/pingcap/tidb/pull/10720) - - 修复 index join 中内表过滤条件在某些情况下的选择率估计错误的问题 [#10854](https://github.com/pingcap/tidb/pull/10854) - - 新增变量 `stats-lease` 值为 0 时系统自动加载统计数据功能 [#10811](https://github.com/pingcap/tidb/pull/10811) - -+ 执行引擎 - - 修复在 `StreamAggExec` 调用 `Close` 函数资源未正确释放问题 [#10636](https://github.com/pingcap/tidb/pull/10636) - - 修复对分区表执行 `show create table` 结果中 `table_option` 与 `partition_options` 顺序不正确问题 [#10689](https://github.com/pingcap/tidb/pull/10689) - - 通过支持逆序扫数据提升 `admin show ddl jobs` 的性能 [#10687](https://github.com/pingcap/tidb/pull/10687) - - 修复 RBAC 中对 `show grants` 语句带 `current_user` 字段时结果与 MySQL 不兼容的问题 [#10684](https://github.com/pingcap/tidb/pull/10684) - - 修复 UUID 在多节点上可能生成重复值的问题 [#10712](https://github.com/pingcap/tidb/pull/10712) - - 修复 `explain` 没考虑 `show view` 权限的问题 [#10635](https://github.com/pingcap/tidb/pull/10635) - - 新增 `split table region` 语句，手动分裂表的 Region，缓解热点问题 [#10765](https://github.com/pingcap/tidb/pull/10765) - - 新增 `split index region` 语句，手动分裂索引的 region 缓解热点问题 [#10764](https://github.com/pingcap/tidb/pull/10764) - - 修复连续执行多个 `create user`、`grant` 或 `revoke` 等类似语句执行不正确的问题 [#10737](https://github.com/pingcap/tidb/pull/10737) - - 新增黑名单禁止下推表达式到 coprocessor 功能 [#10791](https://github.com/pingcap/tidb/pull/10791) - - 新增查询超出内存配置限制时打印 `expensive query` 日志的功能 [#10849](https://github.com/pingcap/tidb/pull/10849) - - 新增 `bind-info-lease` 配置项控制修改绑定执行计划的更新时间 [#10727](https://github.com/pingcap/tidb/pull/10727) - - 修复因持有 `execdetails.ExecDetails` 指针时 Coprocessor 的资源无法快速释放导致的在大并发场景下 OOM 的问题 [#10832](https://github.com/pingcap/tidb/pull/10832) - - 修复某些情况下 `kill` 语句导致的 panic 问题 [#10876](https://github.com/pingcap/tidb/pull/10876) - -+ Server - - 修复 GC 时可能发生的 goroutine 泄露问题 [#10683](https://github.com/pingcap/tidb/pull/10683) - - 支持 slow query 里面显示 `host` 信息 [#10693](https://github.com/pingcap/tidb/pull/10693) - - 支持循环利用与 TiKV 交互的空闲链接 [#10632](https://github.com/pingcap/tidb/pull/10632) - - 修复 RBAC 对开启 `skip-grant-table` 选项的支持问题 [#10738](https://github.com/pingcap/tidb/pull/10738) - - 修复 `pessimistic-txn` 配置失效的问题 [#10825](https://github.com/pingcap/tidb/pull/10825) - - 修复主动取消的 ticlient 请求还会被重试的问题 [#10850](https://github.com/pingcap/tidb/pull/10850) - - 提高在悲观事务和乐观事务冲突情况下的性能 [#10881](https://github.com/pingcap/tidb/pull/10881) - -+ DDL - - 修复在使用 `alter table` 修改 charset 时导致 `blob` 类型改变的问题 [#10698](https://github.com/pingcap/tidb/pull/10698) - - 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 [#10794](https://github.com/pingcap/tidb/pull/10794) - - 禁止通过 `alter table` 添加存储的生成列 [#10808](https://github.com/pingcap/tidb/pull/10808) - - 优化无效 DDL 元信息存活时间，使集群升级后一段时间 DDL 操作比较慢的情况变短 [#10795](https://github.com/pingcap/tidb/pull/10795) - -## PD - -- 新增 `enable-two-way-merge` 配置项，控制合并时仅允许单向合并 [#1583](https://github.com/pingcap/pd/pull/1583) -- 新增 `AddLightLearner` 和 `AddLightPeer` 的调度操作，Region Scatter 调度不受 limit 机制限 [#1563](https://github.com/pingcap/pd/pull/1563) -- 修复系统启动时因数据可能只进行一副本复制而导致可靠性不足的问题 [#1581](https://github.com/pingcap/pd/pull/1581) -- 优化配置检查逻辑，防止配置项错误 [#1585](https://github.com/pingcap/pd/pull/1585) -- 调整 `store-balance-rate` 配置的定义为每分钟产生 balance operator 数量的上限 [#1591](https://github.com/pingcap/pd/pull/1591) -- 修复 store 可能一直无法产生调度操作的问题 [#1590](https://github.com/pingcap/pd/pull/1590) - -## TiKV - -+ Engine - - 修复因迭代器未检查状态导致系统生成残缺 snapshot 的问题 [#4936](https://github.com/tikv/tikv/pull/4936) - - 修复在机器异常掉电时由于接收 snapshot 未及时将数据刷新到磁盘导致丢数据的问题 [#4937](https://github.com/tikv/tikv/pull/4937) - -+ Server - - 新增检查 `block-size` 配置的有效性功能 [#4928](https://github.com/tikv/tikv/pull/4928) - - 新增 read index 相关监控项 [#4830](https://github.com/tikv/tikv/pull/4830) - - 新增 GC worker 相关监控项 [#4922](https://github.com/tikv/tikv/pull/4922) - -+ Raftstore - - 修复 local reader 的 cache 没有正确清理的问题 [#4778](https://github.com/tikv/tikv/pull/4778) - - 修复进行 transfer leader 和 conf change 时可能导致请求延迟增加的问题 [#4734](https://github.com/tikv/tikv/pull/4734) - - 修复误报 stale command 的问题 [#4682](https://github.com/tikv/tikv/pull/4682) - - 修复 command 可能一直 pending 的问题 [#4810](https://github.com/tikv/tikv/pull/4810) - - 修复 snapshot 文件未及时落盘而导致掉电后文件损坏的问题 [#4807](https://github.com/tikv/tikv/pull/4807)，[#4850](https://github.com/tikv/tikv/pull/4850) - -+ Coprocessor - - 向量计算支持 Top-N [#4827](https://github.com/tikv/tikv/pull/4827) - - 向量计算支持 Stream 聚合 [#4786](https://github.com/tikv/tikv/pull/4786) - - 向量计算中支持 AVG 聚合函 [#4777](https://github.com/tikv/tikv/pull/4777) - - 向量计算中支持 First 聚合函数 [#4771](https://github.com/tikv/tikv/pull/4771) - - 向量计算中支持 SUM 聚合函数 [#4797](https://github.com/tikv/tikv/pull/4797) - - 向量计算中支持 MAX/MIN 聚合函数 [#4837](https://github.com/tikv/tikv/pull/4837) - - 向量计算中支持 Like 表达式 [#4747](https://github.com/tikv/tikv/pull/4747) - - 向量计算中支持 MultiplyDecimal 表达式 [#4849](https://github.com/tikv/tikv/pull/4849 ) - - 向量计算中支持 BitAnd/BitOr/BitXor 表达式 [#4724](https://github.com/tikv/tikv/pull/4724) - - 向量计算中支持 UnaryNot 表达式 [#4808](https://github.com/tikv/tikv/pull/4808) - -+ Transaction - - 修复悲观事务中非悲观锁冲突导致出错的问题 [#4801](https://github.com/tikv/tikv/pull/4801)，[#4883](https://github.com/tikv/tikv/pull/4883) - - 减少在开启悲观事务后乐观事务的无用计算，提高性能 [#4813](https://github.com/tikv/tikv/pull/4813) - - 新增单语句 rollback，保证在当前语句发生死锁时不需要 rollback 整个事务 [#4848](https://github.com/tikv/tikv/pull/4848) - - 新增悲观事务相关监控项 [#4852](https://github.com/tikv/tikv/pull/4852) - - 支持 `ResolveLockLite` 命令用于轻量级清锁以优化在冲突严重时的性能 [#4882](https://github.com/tikv/tikv/pull/4882) - -+ tikv-ctl - - 新增 `bad-regions` 命令支持检测更多的异常情况 [#4862](https://github.com/tikv/tikv/pull/4862) - - `tombstone` 命令新增强制执行功能 [#4862](https://github.com/tikv/tikv/pull/4862) - -+ Misc - - 新增 `dist_release` 编译命令 [#4841](https://github.com/tikv/tikv/pull/4841) - -## Tools - -+ TiDB Binlog - - 修复 Pump 因写入失败时未检查返回值导致偏移量错误的问题 [#640](https://github.com/pingcap/tidb-binlog/pull/640) - - Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 [#634](https://github.com/pingcap/tidb-binlog/pull/634) - - Pump 新增 `GetMvccByEncodeKey` 函数，加快事务状态查询 [#632](https://github.com/pingcap/tidb-binlog/pull/632) - -## TiDB Ansible - -- 新增预测集群最大 QPS 的监控项（默认隐藏）[#f5cfa4d](https://github.com/pingcap/tidb-ansible/commit/f5cfa4d903bbcd77e01eddc8d31eabb6e6157f73) \ No newline at end of file diff --git a/v3.0/releases/3.0.1.md b/v3.0/releases/3.0.1.md deleted file mode 100644 index e8f66f04e20d..000000000000 --- a/v3.0/releases/3.0.1.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: TiDB 3.0.1 Release Notes -category: Releases ---- - -# TiDB 3.0.1 Release Notes - -发版日期：2019 年 7 月 16 日 - -TiDB 版本：3.0.1 - -TiDB Ansible 版本：3.0.1 - -## TiDB - -+ 新增对 `MAX_EXECUTION_TIME` 特性的支持 [#11026](https://github.com/pingcap/tidb/pull/11026) -+ 新增 `tidb_wait_split_region_finish_backoff` Session 变量，用于控制 Region 打散的 Backoff 时间 [#11166](https://github.com/pingcap/tidb/pull/11166) -+ 新增根据负载情况自动调整 Auto ID 分配的步长功能，步长自动调整范围最小 1000，最大 2000000 [#11006](https://github.com/pingcap/tidb/pull/11006) -+ 新增 `ADMIN PLUGINS ENABLE`/`ADMIN PLUGINS DISABLE` SQL 语句，管理 Plugin 的动态开启或关闭 [#11157](https://github.com/pingcap/tidb/pull/11157) -+ Audit Plugin 新增审记连接功能 [#11013](https://github.com/pingcap/tidb/pull/11013) -+ 修改 Region 打散时的默认行为为等待 PD 调度完成 [#11166](https://github.com/pingcap/tidb/pull/11166) -+ 禁止 Window Function 在 Prepare Plan Cache 中被缓存，避免某些情况下出现结果不正确的问题 [#11048](https://github.com/pingcap/tidb/pull/11048) -+ 禁止使用 Alter 语句修改 Stored Generated Column 的定义 [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 禁止将 Virtual Generated Column 更改为 Stored Generated Column [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 禁止改变带有索引的 Generated Column 的表达式 [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 支持 TiDB 在 ARM64 架构下的编译 [#11150](https://github.com/pingcap/tidb/pull/11150) -+ 支持修改 Database/Table 的 Collate，条件限制为 Database/Table 字符集必须是 UTF8/UTF8MB4 [#11086](https://github.com/pingcap/tidb/pull/11086) -+ 修复 `UPDATE … SELECT` 语句中，`SELECT` 子查询没有解析到 `UPDATE` 表达式中的列而被误裁剪，导致报错的问题 [#11252](https://github.com/pingcap/tidb/pull/11252) -+ 修复点查时，某列被查询多次而且结果为 NULL 时会 Panic 的问题 [#11226](https://github.com/pingcap/tidb/pull/11226) -+ 修复 `RAND` 函数由于非线程安全的 `rand.Rand` 导致的 Data Race 问题 [#11169](https://github.com/pingcap/tidb/pull/11169) -+ 修复 `oom-action="cancel"` 时，某些情况下 SQL 内存使用超阈值没有被取消执行，返回结果不正确的问题 [#11004](https://github.com/pingcap/tidb/pull/11004) -+ 修复 MemTracker 未正确清理统计的内存使用值导致 `SHOW PROCESSLIST` 显示内存使用不为 0 的问题 [#10970](https://github.com/pingcap/tidb/pull/10970) -+ 修复某些情况下整数和非整数比较结果不正确的问题 [#11194](https://github.com/pingcap/tidb/pull/11194) -+ 修复在显式事务中查询对 Table Partition 的查询包含谓词时，查询结果不正确的问题 [#11196](https://github.com/pingcap/tidb/pull/11196) -+ 修复 DDL Job 由于 `infoHandle` 可能为 `NULL` 导致 Panic 的问题 [#11022](https://github.com/pingcap/tidb/pull/11022) -+ 修复嵌套聚合查询时，由于被查询列在子查询中没有引用而被误裁剪导致查询结果错误的问题 [#11020](https://github.com/pingcap/tidb/pull/11020) -+ 修复 `Sleep` 函数响应 Kill 命令不及时的问题 [#11028](https://github.com/pingcap/tidb/pull/11028) -+ 修复 `SHOW PROCESSLIST` 命令显示的 `DB` 和 `INFO` 列与 MySQL 不兼容的问题 [#11003](https://github.com/pingcap/tidb/pull/11003) -+ 修复 `skip-grant-table=true` 时，`FLUSH PRIVILEGES` 语句导致系统 Panic 的问题 [#11027](https://github.com/pingcap/tidb/pull/11027) -+ 修复表主键为 `UNSIGNED` 整数时，`FAST ANALYZE` 收集主键的统计信息不正确的问题 [#11099](https://github.com/pingcap/tidb/pull/11099) -+ 修复某些情况下 `FAST ANALYZE` 语句报 “invalid key” Error 的问题 [#11098](https://github.com/pingcap/tidb/pull/11098) -+ 修复 `CURRENT_TIMESTAMP` 作为列的默认值且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11088](https://github.com/pingcap/tidb/pull/11088) -+ 修复窗口函数报错时函数名没有小写的问题，兼容 MySQL [#11118](https://github.com/pingcap/tidb/pull/11118) -+ 修复 TiKV Client Batch gRPC 的后台线程 panic 后导致 TiDB 无法正常连接 TiKV 进而无法提供服务的问题 [#11101](https://github.com/pingcap/tidb/pull/11101) -+ 修复 `SetVar` 方法由于字符串浅拷贝导致设置的变量不正确的问题 [#11044](https://github.com/pingcap/tidb/pull/11044) -+ 修复 `INSERT … ON DUPLICATE` 语句作用在 Table Partition 时执行失败报错的问题 [#11231](https://github.com/pingcap/tidb/pull/11231) -+ 悲观锁（实验性特性） - - 修复悲观锁进行点查且数据为空时，由于行锁未生效导致结果不正确的问题 [#10976](https://github.com/pingcap/tidb/pull/10976) - - 修复使用悲观锁查询时由于没有使用 `SELECT … FOR UPDATE` 的 TSO 导致查询结果不正确的问题 [#11015](https://github.com/pingcap/tidb/pull/11015) - - 修改乐观锁与悲观锁同时使用时，乐观事务遇到悲观锁冲突时，检测行为由立即检测冲突修改为等待，防止锁冲突进一步恶化 [#11051](https://github.com/pingcap/tidb/pull/11051) - -## TiKV - -- 统计信息中新增对 Blob 文件大小的统计 [#5060](https://github.com/tikv/tikv/pull/5060) -- 修复由于进程退出未正确清理内存资源导致进程在退出时 core dump 问题 [#5053](https://github.com/tikv/tikv/pull/5053) -- 新增与 Titan 引擎相关的所有监控指标 [#4772](https://github.com/tikv/tikv/pull/4772)，[#4836](https://github.com/tikv/tikv/pull/4836) -- 统计打开文件句柄数量时，新增 Titan 引擎打开文件句柄数量，防止因文件句柄数统计不准确导致系统无文件句柄可用的问题 [#5026](https://github.com/tikv/tikv/pull/5026) -- 通过设置 `blob_run_mode` 来决定是否在某个 CF 上启动 Titan 引擎 [#4991](https://github.com/tikv/tikv/pull/4991) -- 修复读操作读不到悲观事务 commit 信息的问题 [#5067](https://github.com/tikv/tikv/pull/5067) -- 新增 `blob-run-mode` 配置参数控制 Titan 引擎的运行模式，取值：normal、read-only、fallback [#4865](https://github.com/tikv/tikv/pull/4865) -- 提升死锁检测的性能 [#5089](https://github.com/tikv/tikv/pull/5089) - -## PD - -- 修复热点 Region 调度时，调度限制会自动调整为 0 的问题 [#1552](https://github.com/pingcap/pd/pull/1552) -- 新增 `enable-grpc-gateway` 的配置选项，用于开启 etcd 的 grpc gateway 功能 [#1596](https://github.com/pingcap/pd/pull/1596) -- 新增 `store-balance-rate`、`hot-region-schedule-limit` 等与调度器配置相关的统计信息 [#1601](https://github.com/pingcap/pd/pull/1601) -- 优化热点 Region 调度策略，调度时跳过缺失副本的 Region，防止多个副本调度到同一个机房 [#1609](https://github.com/pingcap/pd/pull/1609) -- 优化 Region Merge 处理逻辑，优先 Merge Region Size 较小的 Region，提升 Region Merge 的速度 [#1613](https://github.com/pingcap/pd/pull/1613) -- 优化单次调度热点 Region 的限制值为 64，防止调度任务过多占用系统资源，影响性能 [#1616](https://github.com/pingcap/pd/pull/1616) -- 优化 Region 调度策略，新增优先调度 Pending 状态的 Region 功能 [#1617](https://github.com/pingcap/pd/pull/1617) -- 修复无法添加 `random-merge` 和 `admin-merge-region` operator 的问题 [#1634](https://github.com/pingcap/pd/pull/1634) -- 调整日志中输出 Region 中 Key 的格式为 16 进制，方便用户查看 [#1639](https://github.com/pingcap/pd/pull/1639) - -## Tools - -TiDB Binlog - -- 优化 Pump GC 策略，删除保证未被消费的 Binlog 不被清理的限制，确保资源不会长期占用 [#646](https://github.com/pingcap/tidb-binlog/pull/646) - -TiDB Lightning - -- 修正 SQL dump 指明的列名不是小写时导入错误的问题 [#210](https://github.com/pingcap/tidb-lightning/pull/210) - -## TiDB Ansible - -- 新增 `ansible` 命令及其 `jmespath`、`Jinja2` 依赖包的预检查功能 [#803](https://github.com/pingcap/tidb-ansible/pull/803)，[#813](https://github.com/pingcap/tidb-ansible/pull/813) -- Pump 新增 `stop-write-at-available-space` 参数，控制当磁盘剩余空间小于该值（默认 10 GiB）时，Pump 停止写入 Binlog [#806](https://github.com/pingcap/tidb-ansible/pull/806) -- 更新 TiKV 监控中的 IO 监控项，兼容新版本监控组件 [#820](https://github.com/pingcap/tidb-ansible/pull/820) -- 更新 PD 监控信息，并修复 Disk Performance Dashboard 中 Disk Latency 显示为空的异常 [#817](https://github.com/pingcap/tidb-ansible/pull/817) -- TiKV Details Dashboard 新增 Titan 监控项 [#824](https://github.com/pingcap/tidb-ansible/pull/824) diff --git a/v3.0/releases/3.0.10.md b/v3.0/releases/3.0.10.md deleted file mode 100644 index 99ad46fff3e4..000000000000 --- a/v3.0/releases/3.0.10.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: TiDB 3.0.10 Release Notes -category: Releases ---- - -# TiDB 3.0.10 Release Notes - -发版日期：2020 年 02 月 20 日 - -TiDB 版本：3.0.10 - -TiDB Ansible 版本：3.0.10 - -## TiDB - -- 修复 IndexLookUpJoin 在利用 OtherCondition 构造 InnerRange 时出现错误 Join 结果 [#14599](https://github.com/pingcap/tidb/pull/14599) -- 删除 `tidb_pprof_sql_cpu` 配置项，新增 Server 级别的 `tidb_pprof_sql_cpu` 变量 [#14416](https://github.com/pingcap/tidb/pull/14416) -- 修复用户只在具有全局权限时才能查询所有数据库的问题 [#14386](https://github.com/pingcap/tidb/pull/14386) -- 修复执行 point-get 时由于事务超时导致数据的可见性不符合预期的问题 [#14480](https://github.com/pingcap/tidb/pull/14480) -- 将悲观事务激活的时机改为延迟激活，与乐观事务模型保持一致 [#14474](https://github.com/pingcap/tidb/pull/14474) -- 修复 unixtimestamp 表达式在计算分区表分区的时区不正确的问题 [#14476](https://github.com/pingcap/tidb/pull/14476) -- 新增`tidb_session_statement_deadlock_detect_duration_seconds` 监控项，用于监控死锁检测时间 [#14484](https://github.com/pingcap/tidb/pull/14484) -- 修复 GC worker 由于部分逻辑不正确导致系统 panic 的问题 [#14439](https://github.com/pingcap/tidb/pull/14439) -- 修复 IsTrue 函数的表达式名称不正确的问题 [#14516](https://github.com/pingcap/tidb/pull/14516) -- 修复部分内存使用统计不准确的问题 [#14533](https://github.com/pingcap/tidb/pull/14533) -- 修复统计信息 CM-Sketch 初始化时由于处理逻辑不正确导致系统 panic 的问题 [#14470](https://github.com/pingcap/tidb/pull/14470) -- 修复查询分区表时分区裁剪（partition pruning）不准确的问题 [#14546](https://github.com/pingcap/tidb/pull/14546) -- 修复 SQL 绑定中 SQL 语句默认数据库名设置不正确的问题 [#14548](https://github.com/pingcap/tidb/pull/14548) -- 修复 json_key 与 MySQL 不兼容的问题 [#14561](https://github.com/pingcap/tidb/pull/14561) -- 新增分区表自动更新统计信息的功能 [#14566](https://github.com/pingcap/tidb/pull/14566) -- 修复执行 point-get时 plan id 会变化的问题，正常情况 plan id 始终是 1 [#14595](https://github.com/pingcap/tidb/pull/14595) -- 修复 SQL 绑定不完全匹配时处理逻辑不正确导致系统 panic 的问题 [#14263](https://github.com/pingcap/tidb/pull/14263) -- 新增 `tidb_session_statement_pessimistic_retry_count` 监控项，用于监控悲观事务加锁失败后重试次数 [#14619](https://github.com/pingcap/tidb/pull/14619) -- 修复 `show binding` 语句权限检查不正确的问题 [#14618](https://github.com/pingcap/tidb/pull/14618) -- 修复由于 backoff 的逻辑里没有检查 killed 标记，导致 kill 无法正确执行的问题 [#14614](https://github.com/pingcap/tidb/pull/14614) -- 通过减少持有内部锁的时间来提高 statement summary 的性能 [#14627](https://github.com/pingcap/tidb/pull/14627) -- 修复 TiDB 从字符串解析成时间与 MySQL 不兼容的问题 [#14570](https://github.com/pingcap/tidb/pull/14570) -- 新增审计日志记录用户登录失败的功能 [#14620](https://github.com/pingcap/tidb/pull/14620) -- 新增 `tidb_session_ statement_lock_keys_count` 监控项，用于监控悲观事务的 lock keys 的数量 [#14634](https://github.com/pingcap/tidb/pull/14634) -- 修复 json 对 `&` `<` `>` 等字符输出转义不正确的问题 [#14637](https://github.com/pingcap/tidb/pull/14637) -- 修复 hash-join 在建 hash-table 时由于内存使用过多导致系统 panic 的问题 [#14642](https://github.com/pingcap/tidb/pull/14642) -- 修复 SQL 绑定处理不合法记录时处理逻辑不正确导致 panic 的问题 [#14645](https://github.com/pingcap/tidb/pull/14645) -- 修复 Decimal 除法计算与 MySQL 不兼容的问题，Decimal 除法计算中增加 Truncated 错误检测 [#14673](https://github.com/pingcap/tidb/pull/14673) -- 修复给用户授权不存在的表执行成功的问题 [#14611](https://github.com/pingcap/tidb/pull/14611) - -## TiKV - -+ Raftstore - - 修复由于 Region merge 失败导致系统 Panic [#6460](https://github.com/tikv/tikv/issues/6460) 或者数据丢失 [#598](https://github.com/tikv/tikv/issues/5981) 的问题 [#6481](https://github.com/tikv/tikv/pull/6481) - - 支持 yield 优化调度公平性，支持预迁移 leader 优化 leader 调度的稳定性 [#6563](https://github.com/tikv/tikv/pull/6563) - -## PD - -- 当系统流量有变化时，系统自动更新 Region 缓存信息，解决缓存失效的问题 [#2103](https://github.com/pingcap/pd/pull/2103) -- 采用 leader 租约时间确定 TSO 的有效时间 [#2117](https://github.com/pingcap/pd/pull/2117) - -## Tools - -+ TiDB Binlog - - Drainer 支持 relay log [#893](https://github.com/pingcap/tidb-binlog/pull/893) -+ TiDB Lightning - - 优化配置项，部分配置项在没有设置的时候使用默认配置 [#255](https://github.com/pingcap/tidb-lightning/pull/255) - - 修复在非 server mode 模式下 web 界面无法打开的问题 [#259](https://github.com/pingcap/tidb-lightning/pull/259) - -## TiDB Ansible - -- 修复某些场景获取不到 PD Leader 导致命令执行失败的问题 [#1121](https://github.com/pingcap/tidb-ansible/pull/1121) -- TiDB Dashboard 新增 `Deadlock Detect Duration` 监控项 [#1127](https://github.com/pingcap/tidb-ansible/pull/1127) -- TiDB Dashboard 新增 `Statement Lock Keys Count` 监控项 [#1132](https://github.com/pingcap/tidb-ansible/pull/1132) -- TiDB Dashboard 新增 `Statement Pessimistic Retry Count` 监控项 [#1133](https://github.com/pingcap/tidb-ansible/pull/1133) diff --git a/v3.0/releases/3.0.2.md b/v3.0/releases/3.0.2.md deleted file mode 100644 index 99d71d4b5e84..000000000000 --- a/v3.0/releases/3.0.2.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: TiDB 3.0.2 Release Notes -category: Releases ---- - -# TiDB 3.0.2 Release Notes - -发版日期：2019 年 8 月 7 日 - -TiDB 版本：3.0.2 - -TiDB Ansible 版本：3.0.2 - -## TiDB - -+ SQL 优化器 - - 修复当同一张表在查询里出现多次且逻辑上查询结果恒为空时报错 “Can’t find column in schema” 的问题 [#11247](https://github.com/pingcap/tidb/pull/11247) - - 修复了 `TIDB_INLJ` Hint 无法以指定表为 Inner 表构建 IndexJoin 时仍，会强制将其作为 Outer 表构建 IndexJoin，同时 Hint 可能会在不应生效的地方生效的错误，该错误是由于强制选取 IndexJoin 的判断逻辑有误，以及对表别名的处理有误导致的；该错误仅对包含 `TIDB_INLJ` 的查询产生影响 [#11362](https://github.com/pingcap/tidb/pull/11362) - - 修复某些情况下（例如 `SELECT IF(1,c,c) FROM t`），查询结果的列名称不正确的问题 [#11379](https://github.com/pingcap/tidb/pull/11379) - - 修复 `LIKE` 表达式某些情况下被隐式转换为 0，导致诸如 `SELECT 0 LIKE 'a string'` 返回结果为 `TRUE` 的问题 [#11411](https://github.com/pingcap/tidb/pull/11411) - - 支持在 `SHOW` 语句中使用子查询，现在可以支持诸如 `SHOW COLUMNS FROM tbl WHERE FIELDS IN (SELECT 'a')` 的写法 [#11459](https://github.com/pingcap/tidb/pull/11459) - - 修复 `outerJoinElimination` 优化规则没有正确处理列的别名，导致找不到聚合函数的相关列而查询报错的问题；改进了优化过程中对别名的解析，以使得优化可以覆盖更多类型的查询 [#11377](https://github.com/pingcap/tidb/pull/11377) - - 修复 Window Function 中多个违反语义约束（例如 `UNBOUNDED PRECEDING` 不允许在 Frame 定义的最后）时没有报错的问题 [#11543](https://github.com/pingcap/tidb/pull/11543) - - 修复 `ERROR 3593 (HY000): You cannot use the window function FUNCTION_NAME in this context` 报错信息中，`FUNCTION_NAME` 不为小写的问题，导致与 MySQL 不兼容 [#11535](https://github.com/pingcap/tidb/pull/11535) - - 修复 Window Function 中 `IGNORE NULLS` 语法尚未实现，但使用时没有报错的问题 [#11593](https://github.com/pingcap/tidb/pull/11593) - - 修复优化器对时间类型数据的等值条件代价估算不准确的问题 [#11512](https://github.com/pingcap/tidb/pull/11512) - - 支持根据反馈信息对统计信息 Top-N 进行更新 [#11507](https://github.com/pingcap/tidb/pull/11507) -+ SQL 执行引擎 - - 修复 `INSERT` 函数在参数中包含 `NULL` 时，返回值不为 `NULL` 的问题 [#11248](https://github.com/pingcap/tidb/pull/11248) - - 修复 `ADMIN CHECKSUM` 语句在检查分区表时计算结果不正确的问题 [#11266](https://github.com/pingcap/tidb/pull/11266) - - 修复 INDEX JOIN 在使用前缀索引时可能结果不正确的问题 [#11246](https://github.com/pingcap/tidb/pull/11246) - - 修复 `DATE_ADD` 函数在进行涉及微秒的日期减法时，没有正确地对日期的小数位数进行对齐导致结果不正确的问题 [#11288](https://github.com/pingcap/tidb/pull/11288) - - 修复 `DATE_ADD` 函数没有正确地对 INTERVAL 中的负数部分处理导致结果不正确的问题 [#11325](https://github.com/pingcap/tidb/pull/11325) - - 修复 `Mod(%)`、`Multiple(*)` 和 `Minus(-)` 返回结果为 0 时，在小数位数较多（例如 `select 0.000 % 0.11234500000000000000`）的情况下与 MySQL 位数不一致的问题 [#11251](https://github.com/pingcap/tidb/pull/11251) - - 修复 `CONCAT` 和 `CONCAT_WS` 函数在返回结果长度超过 `max_allowed_packet` 时，没有正确返回 NULL 和 Warning 的问题 [#11275](https://github.com/pingcap/tidb/pull/11275) - - 修复 `SUBTIME` 和 `ADDTIME` 函数在参数不合法时，没有正确返回 NULL 和 Warning 的问题 [#11337](https://github.com/pingcap/tidb/pull/11337) - - 修复 `CONVERT_TZ` 函数在参数不合法时，没有正确返回 NULL 的问题 [#11359](https://github.com/pingcap/tidb/pull/11359) - - `EXPLAIN ANALYZE` 结果中添加了 `MEMORY` 列，显示 QUERY 的内存使用 [#11418](https://github.com/pingcap/tidb/pull/11418) - - `EXPLAIN` 结果中，为笛卡尔积 Join 添加了 `CARTESIAN` 关键字 [#11429](https://github.com/pingcap/tidb/pull/11429) - - 修复类型为 FLOAT 和 DOUBLE 的自增列数据不正确的问题 [#11385](https://github.com/pingcap/tidb/pull/11385) - - 修复 Dump Pseudo Statistics 时，由于部分信息为 `nil` 导致 panic 的问题 [#11460](https://github.com/pingcap/tidb/pull/11460) - - 修复常量折叠优化导致 `SELECT … CASE WHEN … ELSE NULL …` 查询结果不正确的问题 [#11441](https://github.com/pingcap/tidb/pull/11441) - - 修复 `floatStrToIntStr` 对诸如 `+999.9999e2` 的输入没有正确解析的问题 [#11473](https://github.com/pingcap/tidb/pull/11473) - - 修复 `DATE_ADD` 和 `DATE_SUB` 函数结果超出合法范围时，某些情况下不会返回 `NULL` 的问题 [#11476](https://github.com/pingcap/tidb/pull/11476) - - 修复长字符串转换为整型时，若字符串包含不合法字符，转换结果与 MySQL 不一致的问题 [#11469](https://github.com/pingcap/tidb/pull/11469) - - 修复 `REGEXP BINARY` 函数对大小写敏感，导致与 MySQL 不兼容的问题 [#11504](https://github.com/pingcap/tidb/pull/11504) - - 修复 `GRANT ROLE` 语句在接受 `CURRENT_ROLE` 时报错的问题；修复 `REVOKE ROLE` 语句没有能够正确收回 `mysql.default_role` 权限的问题 [#11356](https://github.com/pingcap/tidb/pull/11356) - - 修复执行诸如 `SELECT ADDDATE('2008-01-34', -1)` 时，`Incorrect datetime value` Warning 信息的显示格式问题 [#11447](https://github.com/pingcap/tidb/pull/11447) - - 修复将 JSON 数据中的 Float 类型字段转为 Int 类型溢出时，报错信息中应当提示 `constant … overflows bigint` 而不应当为 `constant … overflows float` 的问题 [#11534](https://github.com/pingcap/tidb/pull/11534) - - 修复 `DATE_ADD` 函数接受 `FLOAT`、`DOUBLE` 和 `DECIMAL` 类型的列参数时，没有正确地进行类型转换而导致结果可能不正确的问题 [#11527](https://github.com/pingcap/tidb/pull/11527) - - 修复 `DATE_ADD` 函数中，没有正确处理 INTERVAL 小数部分的符号而导致结果不正确的问题 [#11615](https://github.com/pingcap/tidb/pull/11615) - - 修复 `Ranger` 没有正确处理前缀索引，导致 Index Lookup Join 中包含前缀索引时，查询结果不正确的问题 [#11565](https://github.com/pingcap/tidb/pull/11565) - - 修复 `NAME_CONST` 函数第二个参数为负数时执行会报 `Incorrect arguments to NAME_CONST` 的问题 [#11268](https://github.com/pingcap/tidb/pull/11268) - - 修复一条 SQL 语句在涉及当前时间计算时（例如 `CURRENT_TIMSTAMP` 或者 `NOW`），多次取当前时间值，结果与 MySQL不兼容的问题：现在同一条SQL语句中取当前时间时，均使用相同值 [#11394](https://github.com/pingcap/tidb/pull/11394) - - 修复了父 Executor `Close` 出现错误时，没有对 `ChildExecutor` 调用 `Close` 的问题，该问题可能导致 `KILL` 语句失效时，子 `ChildExecutor` 没有关闭而导致 Goroutine 泄露 [#11576](https://github.com/pingcap/tidb/pull/11576) -+ Server - - 修复 `LOAD DATA` 处理 CSV 文件中缺失的 `TIMESTAMP` 字段时，自动补充的值是 0 不是当前时间戳的问题 [#11250](https://github.com/pingcap/tidb/pull/11250) - - 修复 `SHOW CREATE USER` 语句没有正确检查相关权限的问题，以及 `SHOW CREATE USER CURRENT_USER()` 结果中 USER、HOST 可能不正确的问题 [#11229](https://github.com/pingcap/tidb/pull/11229) - - 修复在 JDBC 中使用 `executeBatch` 可能返回结果不正确的问题 [#11290](https://github.com/pingcap/tidb/pull/11290) - - TiKV Server 在更换端口时，减少 Streaming Client 的报错信息的日志打印 [#11370](https://github.com/pingcap/tidb/pull/11370) - - 优化 Streaming Client 在重新与 TiKV Server 连接时的逻辑：现在 Streaming Client 不会长时间被 Block [#11372](https://github.com/pingcap/tidb/pull/11372) - - `INFORMATION_SCHEMA.TIDB_HOT_REGIONS` 中新增 `REGION_ID`[#11350](https://github.com/pingcap/tidb/pull/11350) - - 取消了从 PD API 获取 Region 相关信息时的超时时间，保证在 Region 数量较大时，调用 TiDB API `http://{TiDBIP}:10080/regions/hot` 不会因为 PD 超时而获取失败 [#11383](https://github.com/pingcap/tidb/pull/11383) - - 修复 HTTP API 中，与 Region 相关的请求没有返回分区表相关的 Region 问题 [#11466](https://github.com/pingcap/tidb/pull/11466) - - 做以下改动以降低用户手动验证悲观锁时，操作较慢导致锁超时的概率 [#11521](https://github.com/pingcap/tidb/pull/11521)： - - 悲观锁的默认 TTL 时间由 30 秒提升为 40 秒 - - 最大允许的 TTL 时间由 60 秒提升为 120 秒 - - 悲观锁的持续时间改为从第一次 `LockKeys` 请求时开始计算 - - 修改 TiKV Client 中的 `SendRequest` 函数逻辑：当连接无法建立时，由一直等待改为尽快尝试连接其他 Peer [#11531](https://github.com/pingcap/tidb/pull/11531) - - 优化 Region Cache：当一个 Store 下线，同时另一个 Store 以同样的地址上线时，将已下线的 Store 标记为失效以尽快在 Cache 中更新 Store 的信息 [#11567](https://github.com/pingcap/tidb/pull/11567) - - 为 `http://{TiDB_ADDRESS:TIDB_IP}/mvcc/key/{db}/{table}/{handle}` API 的返回结果添加 Region ID 信息 [#11557](https://github.com/pingcap/tidb/pull/11557) - - 修复 Scatter Table API 没有对 Range Key 进行转义导致 Scatter Table 不生效的问题 [#11298](https://github.com/pingcap/tidb/pull/11298) - - 优化 Region Cache：当 Region 所在的 Store 无法访问时，将对应的 Store 信息标记失效以避免对这些 Store 的访问造成查询性能下降 [#11498](https://github.com/pingcap/tidb/pull/11498) - - 修复了多次 DROP 同名 DATABASE 后，DATABASE 内的表结构仍然能够通过 HTTP API 获取到的错误 [#11585](https://github.com/pingcap/tidb/pull/11585) -+ DDL - - 修复在非字符串类型且长度为 0 的列建立索引时出错的问题 [#11214](https://github.com/pingcap/tidb/pull/11214) - - 禁止对带有外键约束和全文索引的列进行修改（注意：TiDB 仍然仅在语法上支持外键约束和全文索引）[#11274](https://github.com/pingcap/tidb/pull/11274) - - 修复并发使用 `ALTER TABLE` 语句更改的位置和列的默认值时，可能导致列的索引 Offset 出错的问题 [#11346](https://github.com/pingcap/tidb/pull/11346) - - 修复解析 JSON 文本的两个问题： - - `ConvertJSONToFloat` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#11433](https://github.com/pingcap/tidb/pull/11433) - - `ConvertJSONToInt` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#11551](https://github.com/pingcap/tidb/pull/11551) - - 禁止 DROP 自增列索引，修复因为 DROP 自增列上的索引导致自增列结果可能出错的问题 [#11399](https://github.com/pingcap/tidb/pull/11399) - - 修复以下问题 [#11492](https://github.com/pingcap/tidb/pull/11492)： - - 修复显式指定列的排序规则但没有指定字符集时，列的字符集与排序规则不一致的问题 - - 修复 `ALTER TABLE … MODIFY COLUMN` 指定的字符集和排序规则冲突时，没有正确报错的问题 - - 修复 `ALTER TABLE … MODIFY COLUMN` 指定多次字符集和排序规则时，行为与 MySQL 不兼容的问题 - - 为 `TRACE` 语句的结果添加子查询的 trace 细节信息 [#11458](https://github.com/pingcap/tidb/pull/11458) - - 优化 `ADMIN CHECK TABLE` 执行性能，大幅降低了语句的执行耗时 [#11547](https://github.com/pingcap/tidb/pull/11547) - - 为 `SPLIT TABLE … REGIONS/INDEX` 添加了返回结果，结果包含 `TOTAL_SPLIT_REGION` 和 `SCATTER_FINISH_RATIO` 展示在超时时间内，切分成功的 Region 数量 [#11484](https://github.com/pingcap/tidb/pull/11484) - - 修复 `ON UPDATE CURRENT_TIMESTAMP` 作为列的属性且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11591](https://github.com/pingcap/tidb/pull/11591) - - 修复一个虚拟生成列的表达式中含有另一个虚拟生成列时，该列的索引结果不能正确被计算的问题 [#11475](https://github.com/pingcap/tidb/pull/11475) - - 修复 `ALTER TABLE … ADD PARTITION …` 语句中，`VALUE LESS THAN` 后不能出现负号的问题 [#11581](https://github.com/pingcap/tidb/pull/11581) -+ Monitor - - 修复 `TiKVTxnCmdCounter` 监控指标没有注册导致数据没有被收集上报的问题 [#11316](https://github.com/pingcap/tidb/pull/11316) - - 为 Bind Info 添加了 `BindUsageCounter`、`BindTotalGauge` 和 `BindMemoryUsage` 监控指标 [#11467](https://github.com/pingcap/tidb/pull/11467) - -## TiKV - -- 修复由于 Raft Log 写入不及时可能导致 TiKV panic 的 bug [#5160](https://github.com/tikv/tikv/pull/5160) -- 修复 TiKV panic 后 panic 信息不会写入日志的 bug [#5198](https://github.com/tikv/tikv/pull/5198) -- 修复了悲观事务下 Insert 行为可能不正确的 bug [#5203](https://github.com/tikv/tikv/pull/5203) -- 降低一部分不需要人工干预的日志输出级别为 INFO [#5193](https://github.com/tikv/tikv/pull/5193) -- 提高存储引擎大小监控项的准确程度 [#5200](https://github.com/tikv/tikv/pull/5200) -- 提高 tikc-ctl 中 Region size 的准确程度 [#5195](https://github.com/tikv/tikv/pull/5195) -- 提高悲观锁死锁检测性能 [#5192](https://github.com/tikv/tikv/pull/5192) -- 提高 Titan 存储引擎 GC 性能 [#5197](https://github.com/tikv/tikv/pull/5197) - -## PD - -- 修复 Scatter Region 调度器不能工作的 bug [#1642](https://github.com/pingcap/pd/pull/1642) -- 修复 pd-ctl 中不能进行 merge Region 操作的 bug [#1653](https://github.com/pingcap/pd/pull/1653) -- 修复 pd-ctl 中不能进行 remove-tombstone 操作的 bug [#1651](https://github.com/pingcap/pd/pull/1651) -- 修复 scan region 不能找到 key 范围相交的 Region 的问题 [#1648](https://github.com/pingcap/pd/pull/1648) -- 增加重试机制确保 PD 增加成员成功 [#1643](https://github.com/pingcap/pd/pull/1643) - -## Tools - -TiDB Binlog - -- 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#687](https://github.com/pingcap/tidb-binlog/pull/687) -- Drainer 增加 `node-id` 配置，用于指定固定逻辑 Drainer [#684](https://github.com/pingcap/tidb-binlog/pull/684) - -TiDB Lightning - -- 修复 2 个 checksum 同时运行的情况下，`tikv_gc_life_time` 没有正常修改回原本值的问题 [#218](https://github.com/pingcap/tidb-lightning/pull/218) -- 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#217](https://github.com/pingcap/tidb-lightning/pull/217) - -## TiDB Ansible - -- 修复 Disk Performance 监控把 second 作为 ms 的单位错误的问题 [#840](https://github.com/pingcap/tidb-ansible/pull/840) -- Spark 新增 log4j 日志配置 [#841](https://github.com/pingcap/tidb-ansible/pull/841) -- 修复在开启了 Binlog 并且设置了 Kafka 或者 ZooKeeper 时导致生成的 Prometheus 配置文件格式错误的问题 [#844](https://github.com/pingcap/tidb-ansible/pull/844) -- 修复生成的 TiDB 配置文件中遗漏 `pessimistic-txn` 配置参数的问题 [#850](https://github.com/pingcap/tidb-ansible/pull/850) -- TiDB Dashboard 新增和优化 Metrics [#853](https://github.com/pingcap/tidb-ansible/pull/853) -- TiDB Dashboard 上每个监控项增加描述 [#854](https://github.com/pingcap/tidb-ansible/pull/854) -- 新增 TiDB Summary Dashboard，用于更好的查看集群状态和排查问题 [#855](https://github.com/pingcap/tidb-ansible/pull/855) -- TiKV Dashboard 更新 Allocator Stats 监控项 [#857](https://github.com/pingcap/tidb-ansible/pull/857) -- 修复 Node Exporter 的告警表达式单位错误的问题 [#860](https://github.com/pingcap/tidb-ansible/pull/860) -- 更新 tispark jar 包为 v2.1.2 版本 [#862](https://github.com/pingcap/tidb-ansible/pull/862) -- 更新 Ansible Task 功能描述 [#867](https://github.com/pingcap/tidb-ansible/pull/867) -- 兼容 TiDB 变更，TiDB Dashboard 更新 Local reader requests 监控项的表达式 [#874](https://github.com/pingcap/tidb-ansible/pull/874) -- Overview Dashboard 更新 TiKV Memory 监控项的表达式，修复监控显示错误的问题 [#879](https://github.com/pingcap/tidb-ansible/pull/879) -- 移除 Kafka 模式 Binlog 的支持 [#878](https://github.com/pingcap/tidb-ansible/pull/878) -- 修复执行 `rolling_update.yml` 操作时，切换 PD Leader 失效的 Bug [#887](https://github.com/pingcap/tidb-ansible/pull/887) diff --git a/v3.0/releases/3.0.3.md b/v3.0/releases/3.0.3.md deleted file mode 100644 index 6a3aa4260a59..000000000000 --- a/v3.0/releases/3.0.3.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: TiDB 3.0.3 Release Notes -category: Releases ---- - -# TiDB 3.0.3 Release Notes - -发版日期：2019 年 8 月 29 日 - -TiDB 版本：3.0.3 - -TiDB Ansible 版本：3.0.3 - -## TiDB - -+ SQL 优化器 - - 添加 `opt_rule_blacklist` 表，用于禁用一些逻辑优化规则，比如 `aggregation_eliminate`，`column_prune` 等 [#11658](https://github.com/pingcap/tidb/pull/11658) - - 修复 Index join 的 join key 中使用前缀索引或者使用 unsigned 的索引列等于负数时结果不正确的问题 -[#11759](https://github.com/pingcap/tidb/pull/11759) - - 修复 `create … binding ...` 的 Select 语句中带有 `”` 或者 `\` 时解析报错的问题 [#11726](https://github.com/pingcap/tidb/pull/11726) -+ SQL 执行引擎 - - 修复 `Quote` 函数处理 null 值的返回值类型出错的问题 [#11619](https://github.com/pingcap/tidb/pull/11619) - - 修复 Max 和 Min 在推导类型时没有去除 NotNullFlag 导致 `ifnull` 结果错误的问题 [#11641](https://github.com/pingcap/tidb/pull/11641) - - 修复对字符形式的 Bit 类型数据比较出错的问题 [#11660](https://github.com/pingcap/tidb/pull/11660) - - 减少需要顺序读取数据的并发度，以降低 OOM 出现概率 [#11679](https://github.com/pingcap/tidb/pull/11679) - - 修复对应含有多个参数的内置函数（如 `if`、`coalesce` 等），在多个参数都为 unsigned 时类型推导不正确的问题 [#11621](https://github.com/pingcap/tidb/pull/11621) - - 修复 `Div` 函数处理 unsigned 的 decimal 类型时与 MySQL 行为不兼容的问题 [#11813](https://github.com/pingcap/tidb/pull/11813) - - 修复执行修改 Pump/Drainer 状态的 SQL 时会报 panic 的问题 [#11827](https://github.com/pingcap/tidb/pull/11827) - - 修复在 Autocommit = 1 且没有 begin 的时，`select ... for update` 出现 panic 的问题 [#11736](https://github.com/pingcap/tidb/pull/11736) - - 修复执行 `set default role` 语句时权限检查出错的问题 [#11777](https://github.com/pingcap/tidb/pull/11777) - - 修复执行 `create user` 和`drop user` 语句出现权限检查错误的问题 [#11814](https://github.com/pingcap/tidb/pull/11814) - - 修复 `select ... for update` 在构建为 PointGetExecutor 时会重试的问题 [#11718](https://github.com/pingcap/tidb/pull/11718) - - 修复 Window function 处理 Partition 时边界出错的问题 [#11825](https://github.com/pingcap/tidb/pull/11825) - - 修复 `time` 函数在处理错误格式参数时直接断链接的问题 [#11893](https://github.com/pingcap/tidb/pull/11893) - - 修复 Window function 没有检查传入参数的问题 [#11705](https://github.com/pingcap/tidb/pull/11705) - - 修复 Explain 查看的 Plan 结果跟真实执行的 Plan 结果不一致的问题 [#11186](https://github.com/pingcap/tidb/pull/11186) - - 修复 Window function 内存重复引用导致崩溃或结果不正确的问题 [#11823](https://github.com/pingcap/tidb/pull/11823) - - 修复 Slow log 里面 Succ 字段信息错误的问题 [#11887](https://github.com/pingcap/tidb/pull/11887) -+ Server - - 重命名 `tidb_back_off_weight` 变量为 `tidb_backoff_weight` [#11665](https://github.com/pingcap/tidb/pull/11665) - - 更新与当前 TiDB 兼容的最低版本的 TiKV 为 v3.0.0 的信息 [#11618](https://github.com/pingcap/tidb/pull/11618) - - 支持 `make testSuite` 来确保测试中的 Suite 都被正确使用 [#11685](https://github.com/pingcap/tidb/pull/11685) -+ DDL - - 禁止不支持的 Partition 相关的 DDL 的执行，其中包括修改 Partition 类型，同时删除多个 Partition 等 [#11373](https://github.com/pingcap/tidb/pull/11373) - - 禁止 Generated Column 的位置在它依赖的列前 [#11686](https://github.com/pingcap/tidb/pull/11686) - - 修改添加索引操作中使用的 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 变量的默认值 [#11874](https://github.com/pingcap/tidb/pull/11874) -+ Monitor - - Backoff 监控添加类型，且补充之前没有统计到的 Backoff，比如 commit 时遇到的 Backoff [#11728](https://github.com/pingcap/tidb/pull/11728) - -## TiKV - -- 修复 ReadIndex 请求可能由于重复 Context 而无法响应请求的问题 [#5256](https://github.com/tikv/tikv/pull/5256) -- 修复 `PutStore` 过早而引起一些调度造成抖动的问题 [#5277](https://github.com/tikv/tikv/pull/5277) -- 修复 Region Heartbeat 上报的时间戳不准的问题 [#5296](https://github.com/tikv/tikv/pull/5296) -- 剔除 share block cache 信息减少 coredump 文件大小 [#5322](https://github.com/tikv/tikv/pull/5322) -- 修复 Region merge 中会引起 TiKV panic 的问题 [#5291](https://github.com/tikv/tikv/pull/5291) -- 加快死锁检测器器的 leader 变更检查 [#5317](https://github.com/tikv/tikv/pull/5317) -- 使用 grpc env 创建 deadlock 的客户端 [#5346](https://github.com/tikv/tikv/pull/5346) -- 添加 `config-check` 检查配置是否正确 [#5349](https://github.com/tikv/tikv/pull/5349) -- 修复 ReadIndex 请求在没有 leader 情况下不返回的问题 [#5351](https://github.com/tikv/tikv/pull/5351) - -## PD - -- `pdctl` 返回成功信息 [#1685](https://github.com/pingcap/pd/pull/1685) - -## Tools - -+ TiDB Binlog - - 将 Drainer `defaultBinlogItemCount` 默认值从 65536 改为 512，减少 Drainer 启动时 OOM 的情况 [#721](https://github.com/pingcap/tidb-binlog/pull/721) - - 优化 Pump server 下线处理逻辑，避免出现 Pump 下线阻塞的问题 [#701](https://github.com/pingcap/tidb-binlog/pull/701) -+ TiDB Lightning - - 导入时默认过滤系统库 `mysql`，`information_schema`，`performance_schema`，`sys` [#225](https://github.com/pingcap/tidb-lightning/pull/225) - -## TiDB Ansible - -- 优化滚动升级 PD 的操作，提高稳定性 [#894](https://github.com/pingcap/tidb-ansible/pull/894) -- 移除当前 Grafana 版本不支持的 Grafana Collector 组件 [#892](https://github.com/pingcap/tidb-ansible/pull/892) -- 更新 TiKV 告警规则 [#898](https://github.com/pingcap/tidb-ansible/pull/898) -- 修复生成的 TiKV 配置遗漏 `pessimistic-txn` 参数的问题 [#911](https://github.com/pingcap/tidb-ansible/pull/911) -- 更新 Spark 版本为 2.4.3，同时更新 TiSpark 为兼容该 Spark 的 2.1.4 版本 [#913](https://github.com/pingcap/tidb-ansible/pull/913) [#918](https://github.com/pingcap/tidb-ansible/pull/918) diff --git a/v3.0/releases/3.0.4.md b/v3.0/releases/3.0.4.md deleted file mode 100644 index 9031256608c8..000000000000 --- a/v3.0/releases/3.0.4.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: TiDB 3.0.4 Release Notes -category: Releases ---- - -# TiDB 3.0.4 Release Notes - -发版日期：2019 年 10 月 8 日 - -TiDB 版本：3.0.4 - -TiDB Ansible 版本：3.0.4 - -- 新特性 - - 新增系统表 `performance_schema.events_statements_summary_by_digest`，用于排查 SQL 级别的性能问题 - - TiDB 的 `SHOW TABLE REGIONS` 语法新增 `WHERE` 条件子句 - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 -- 改进提升 - - TiKV 支持批量 `Split` 和空的 `Split` 命令，使得 Split 可以批量进行 - - TiKV 添加 RocksDB 双向链表支持，提升逆序扫性能 - - Ansible 新增 `iosnoop` 和 `funcslower` 两个 perf 工具，方便诊断集群状态 - - TiDB 优化慢日志输出内容，删除冗余字段 -- 行为变更 - - TiDB 修改 `txn-local-latches.enable` 默认值为 `false`，默认不启用本地事务冲突检测 - - TiDB 添加全局作用域系统变量 `tidb_txn_mode`，允许配置使用悲观锁，请注意默认情况下，TiDB 仍然使用乐观锁 - - TiDB 慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 - - TiDB 配置文件中添加 `split-region-max-num` 参数，用于调整 `SPLIT TABLE` 语法允许的最大 Region 数量 - - TiDB 修改 SQL 超出内存限制后的行为，从断开链接修改为返回 `Out Of Memory Quota` 错误 - - 为避免误操作，TiDB 默认不再允许删除列的 `AUTO_INCREMENT` 属性，当确实需要删除时，请更改系统变量 `tidb_allow_remove_auto_inc` -- 问题修复 - - TiDB 修复特殊语法 `PRE_SPLIT_REGIONS` 没有使用注释的方式向下游同步的问题 - - TiDB 修复使用游标获取 `PREPARE` + `EXECUTE` 执行结果时，慢日志不正确的问题 - - PD 修复相邻小 Region 无法 Merge 的问题 - - TiKV 修复空闲集群中文件描述符泄漏导致长期运行可能会引起 TiKV 进程异常退出的问题 -- 社区贡献者 - - 感谢以下社区贡献者参与本次发版： - - [sduzh](https://github.com/sduzh) - - [lizhenda](https://github.com/lizhenda) - -## TiDB - -- SQL 优化器 - - 修复 `Feedback` 切分查询范围出错的问题 [#12170](https://github.com/pingcap/tidb/pull/12170) - - 修改当 `SHOW STATS_BUCKETS` 结果中包含无效 Key 时的行为，将返回错误修改为使用 16 进制显示 [#12094](https://github.com/pingcap/tidb/pull/12094) - - 修复查询中包含 `SLEEP` 函数时（例如 `select 1 from (select sleep(1)) t;)`），由于列裁剪导致查询中的 `sleep(1)` 失效的问题 [#11953](https://github.com/pingcap/tidb/pull/11953) - - 当查询只关心表的行数而不关心表数据时，使用索引扫描降低 IO [#12112](https://github.com/pingcap/tidb/pull/12112) - - 当 `use index()` 中没有指定索引时不去使用任何索引，和 MySQL 兼容 (如 `explain select a from t use index();`) [#12100](https://github.com/pingcap/tidb/pull/12100) - - 严格限制统计信息 `CMSketch` 中 `TopN` 记录的数量，修复快速 `analyze` 因为超过事务大小限制而失败的问题 [#11914](https://github.com/pingcap/tidb/pull/11914) - - 修复 `Update` 语句包含子查询时，转换子查询出现的错误 [#12483](https://github.com/pingcap/tidb/pull/12483) - - 将 Limit 算子下推到 `IndexLookUpReader` 执行逻辑中优化 `select ... limit ... offset ...` 的执行性能 [#12378](https://github.com/pingcap/tidb/pull/12378) -- SQL 执行引擎 - - `PREPARED` 语句执行错误时，在日志中打印 SQL 语句 [#12191](https://github.com/pingcap/tidb/pull/12191) - - 分区表使用 `UNIX_TIMESTAMP` 函数分区时，支持分区裁剪 [#12169](https://github.com/pingcap/tidb/pull/12169) - - 修复 `AUTO INCREMENT` 分配 `MAX int64` 和 `MAX uint64` 没有报错的问题 [#12162](https://github.com/pingcap/tidb/pull/12162) - - `SHOW TABLE … REGIONS` 和 `SHOW TABLE .. INDEX … REGIONS` 语法新增 `WHERE` 条件子句 [#12123](https://github.com/pingcap/tidb/pull/12123) - - 修改 SQL 超出内存限制后的行为，从断开链接修改为返回 `Out Of Memory Quota` 错误 [#12127](https://github.com/pingcap/tidb/pull/12127) - - 修复 `JSON_UNQUOTE` 函数处理 JSON 文本结果不正确的问题 [#11955](https://github.com/pingcap/tidb/pull/11955) - - 修复 `INSERT` 语句中，第一行中为 `AUTO_INCREMENT` 列赋值，`LAST INSERT ID` 不正确的问题（例如 `insert into t (pk, c) values (1, 2), (NULL, 3)`）[#12002](https://github.com/pingcap/tidb/pull/12002) - - 修复 `PREPARE` 语句中，`GroupBY` 解析规则错误的问题 [#12351](https://github.com/pingcap/tidb/pull/12351) - - 修复点查中权限检查不正确的问题 [#12340](https://github.com/pingcap/tidb/pull/12340) - - 修复 `PREPARE` 语句类型没有记录在监控中的问题 [#12331](https://github.com/pingcap/tidb/pull/12331) - - 支持点查中表名使用别名（例如 `select * from t tmp where a = "aa"`）[#12282](https://github.com/pingcap/tidb/pull/12282) - - 修复向 BIT 类型列插入数值时，值没有作为无符号类型处理而导致插入负数报错的问题 [#12423](https://github.com/pingcap/tidb/pull/12423) - - 修复时间取整不正确的问题（例如 `2019-09-11 11:17:47.999999666` 应该被取整到 `2019-09-11 11:17:48`）[#12258](https://github.com/pingcap/tidb/pull/12258) - - 调整表达式黑名单系统表的用法（例如 `<` 与 `lt` 等价）[#11975](https://github.com/pingcap/tidb/pull/11975) - - 调整函数不存在的错误消息，添加数据库前缀（例如 `[expression:1305]FUNCTION test.std_samp does not exist`）[#12111](https://github.com/pingcap/tidb/pull/12111) -- Server - - 慢日志中添加 `Prev_stmt` 字段，用于最后一条语句是 `COMMIT` 时输出前一条语句 [#12180](https://github.com/pingcap/tidb/pull/12180) - - 优化慢日志输出内容，删除冗余字段 [#12144](https://github.com/pingcap/tidb/pull/12144) - - 修改 `txn-local-latches.enable` 默认值为 `false`，默认不启用本地事务冲突检测 [#12095](https://github.com/pingcap/tidb/pull/12095) - - 将慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 [#12061](https://github.com/pingcap/tidb/pull/12061) - - 添加全局作用域系统变量 `tidb_txn_mode`，允许配置使用悲观锁 [#12049](https://github.com/pingcap/tidb/pull/12049) - - 慢日志中添加 `Backoff` 字段，用来记录 2PC Commit 阶段的 Backoff 信息 [#12335](https://github.com/pingcap/tidb/pull/12335) - - 修复使用游标获取 `PREPARE` + `EXECUTE` 执行结果时，慢日志不正确的问题（例如 `PREPARE stmt1FROM SELECT * FROM t WHERE a > ?; EXECUTE stmt1 USING @variable`）[#12392](https://github.com/pingcap/tidb/pull/12392) - - 支持使用 `tidb_enable_stmt_summary`，开启后会对 SQL 语句进行统计，并可以使用系统表 `performance_schema.events_statements_summary_by_digest` 查询统计结果 [#12308](https://github.com/pingcap/tidb/pull/12308) - - 调整了 tikv-client 中部分日志级别（例如由于连接断开使得打印的 `batchRecvLoop fails` 日志级别由 `ERROR` 改为 `INFO`）[#12383](https://github.com/pingcap/tidb/pull/12383) -- DDL - - 新增变量 `tidb_allow_remove_auto_inc`，默认禁止删除列 `AUTO INCREMENT` 属性 [#12145](https://github.com/pingcap/tidb/pull/12145) - - 修复 TiDB 特殊语法 `PRE_SPLIT_REGIONS` 没有使用注释的方式向下游同步，导致下游数据库报错的问题 [#12120](https://github.com/pingcap/tidb/pull/12120) - - 在配置文件中添加 `split-region-max-num` 参数，使得 `SPLIT TABLE` 语法允许的最大 Region 数量可调整，该参数默认值 `10000` [#12097](https://github.com/pingcap/tidb/pull/12079) - - 支持将一个 Region 切分成多个 Region，并修复打散 Region 超时的问题 [#12343](https://github.com/pingcap/tidb/pull/12343) - - 修复当索引包含自增列，并且该自增列被两个索引引用时删除失败的问题 [#12344](https://github.com/pingcap/tidb/pull/12344) -- Monitor - - 增加监控指标 `connection_transient_failure_count`，用于统计 `tikvclient` 的 gRPC 连接错误数量 [#12093](https://github.com/pingcap/tidb/pull/12093) - -## TiKV - -- Raftstore - - 修复 Raftstore 统计空 Region 中 key 个数不准确问题 [#5414](https://github.com/tikv/tikv/pull/5414) - - 添加 RocksDB 双向链表支持，提升逆序扫性能 [#5368](https://github.com/tikv/tikv/pull/5368) - - 支持 PD 批量 `Split` 和空的 `Split` 命令, 使得 Split 可以批量进行，提高 Split 效率 [#5470](https://github.com/tikv/tikv/pull/5470) -- Server - - 修复查看版本命令的输出格式与 2.X 格式不一致的问题 [#5501](https://github.com/tikv/tikv/pull/5501) - - 更新 Titan 至 3.0 分支最新版本 [#5517](https://github.com/tikv/tikv/pull/5517) - - 更新 grpcio 至 v0.4.5 版本 [#5523](https://github.com/tikv/tikv/pull/5523) - - 修复 gRPC coredump 问题，支持内存共享，以避免此处引起 OOM [#5524](https://github.com/tikv/tikv/pull/5524) - - 修复空闲集群中文件描述符泄漏导致长期运行可能会引起 TiKV 进程异常退出的问题 [#5567](https://github.com/tikv/tikv/pull/5567) -- Storage - - 支持悲观锁事务心跳检测 API，以使得 TiDB 的悲观锁行为与 MySQL 尽量一致 [#5507](https://github.com/tikv/tikv/pull/5507) - - 修复部分情况下点查性能较低的问题 [#5495](https://github.com/tikv/tikv/pull/5495) [#5463](https://github.com/tikv/tikv/pull/5463) - -## PD - -- 修复相邻小 Region 无法 Merge 的问题 [#1726](https://github.com/pingcap/pd/pull/1726) -- 修复 pd-ctl 的 TLS 启用参数失效问题 [#1738](https://github.com/pingcap/pd/pull/1738) -- 修复可能导致 PD operator 被意外移除的线程安全问题 [#1734](https://github.com/pingcap/pd/pull/1734) -- Region syncer 支持 TLS [#1739](https://github.com/pingcap/pd/pull/1739) - -## Tools - -- TiDB Binlog - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 [#746](https://github.com/pingcap/tidb-binlog/pull/746) - - Drainer 优化内存使用，提升同步执行效率 [#737](https://github.com/pingcap/tidb-binlog/pull/737) -- TiDB Lightning - - 修复从 checkpoint 点重新导入可能会导致 TiDB Lightning 崩溃的问题 [#237](https://github.com/pingcap/tidb-lightning/pull/237) - - 修改计算 `AUTO_INCREMENT` 的算法，降低溢出的风险 [#227](https://github.com/pingcap/tidb-lightning/pull/227) - -## TiDB Ansible - -- 更新 TiSpark 版本至 2.2.0 [#926](https://github.com/pingcap/tidb-ansible/pull/926) -- 更新 TiDB 配置项 `pessimistic_txn` 的默认值为 `true` [#933](https://github.com/pingcap/tidb-ansible/pull/933) -- 新增更多系统级别监控到 `node_exporter` [#938](https://github.com/pingcap/tidb-ansible/pull/938) -- 新增 `iosnoop` 和 `funcslower` 两个 perf 工具，方便诊断集群状态 [#946](https://github.com/pingcap/tidb-ansible/pull/946) -- Ansible 的 Raw 模块更新成 Shell 模块，解决密码过期等场景发生的长时间等待问题 [#949](https://github.com/pingcap/tidb-ansible/pull/949) -- 更新 TiDB 配置项 `txn_local_latches` 的默认值为 `false` -- 优化 Grafana dashboard 监控项和告警规则 [#962](https://github.com/pingcap/tidb-ansible/pull/962) [#963](https://github.com/pingcap/tidb-ansible/pull/963) [#969](https://github.com/pingcap/tidb-ansible/pull/963) -- 新增配置文件检查功能，在部署和升级之前检查配置文件是否正确 [#934](https://github.com/pingcap/tidb-ansible/pull/934) [#972](https://github.com/pingcap/tidb-ansible/pull/972) diff --git a/v3.0/releases/3.0.5.md b/v3.0/releases/3.0.5.md deleted file mode 100644 index 1245eaa65f9d..000000000000 --- a/v3.0/releases/3.0.5.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 3.0.5 Release Notes -category: Releases ---- - -# TiDB 3.0.5 Release Notes - -发版日期：2019 年 10 月 25 日 - -TiDB 版本：3.0.5 - -TiDB Ansible 版本：3.0.5 - -## TiDB - -+ SQL 优化器 - - 支持对 Window Functions 进行边界检查 [#12404](https://github.com/pingcap/tidb/pull/12404) - - 修复 partition 表上的 `IndexJoin` 返回错误结果的问题 [#12712](https://github.com/pingcap/tidb/pull/12712) - - 修复外连接 Apply 算子上层的 `ifnull` 函数返回错误结果的问题 [#12694](https://github.com/pingcap/tidb/pull/12694) - - 修复当 `UPDATE` 的 `where` 条件中包含子查询时更新失败的问题 [#12597](https://github.com/pingcap/tidb/pull/12597) - - 修复当查询条件中包含 `cast` 函数时 outer join 被错误转化为 inner join 的问题 [#12790](https://github.com/pingcap/tidb/pull/12790) - - 修复 `AntiSemiJoin` 的 join 条件中错误的表达式传递 [#12799](https://github.com/pingcap/tidb/pull/12799) - - 修复初始化统计信息时由于浅拷贝造成的统计信息出错问题 [#12817](https://github.com/pingcap/tidb/pull/12817) - - 修复 TiDB 中 `str_to_date` 函数在日期字符串和格式化字符串不匹配的情况下，返回结果与 MySQL 不一致的问题 [#12725](https://github.com/pingcap/tidb/pull/12725) -+ SQL 执行引擎 - - 修复在 `from_unixtime` 函数处理 null 时发生 panic 的问题 [#12551](https://github.com/pingcap/tidb/pull/12551) - - 修复 Admin Cancel DDL jobs 时报 `invalid list index` 错的问题 [#12671](https://github.com/pingcap/tidb/pull/12671) - - 修复使用 Window Functions 时发生数组越界的问题 [#12660](https://github.com/pingcap/tidb/pull/12660) - - 改进 `AutoIncrement` 列隐式分配时的行为，与 MySQL 自增锁的默认模式 (["consecutive" lock mode](https://dev.mysql.com/doc/refman/5.7/en/innodb-auto-increment-handling.html)) 保持一致：对于单行 Insert 语句的多个自增 `AutoIncrement` ID 的隐式分配，TiDB 保证分配值的连续性。该改进保证 JDBC `getGeneratedKeys()` 方法在任意场景下都能得到正确的结果。[#12602](https://github.com/pingcap/tidb/pull/12602) - - 修复当 `HashAgg` 作为 Apply 子节点时查询 hang 住的问题 [#12766](https://github.com/pingcap/tidb/pull/12766) - - 修复逻辑表达式 `AND` 或 `OR` 在涉及类型转换时返回错误结果的问题 [#12811](https://github.com/pingcap/tidb/pull/12811) -+ Server - - 实现修改事务 TTL 的接口函数，以助后续支持大事务 [#12397](https://github.com/pingcap/tidb/pull/12397) - - 支持将事务的 TTL 按需延长（最长可到 10min），用于支持悲观事务 [#12579](https://github.com/pingcap/tidb/pull/12579) - - 将 TiDB 缓存 schema 变更及相关表信息的次数从 100 调整为 1024，且支持通过 `tidb_max_delta_schema_count` 系统变量修改 [#12502](https://github.com/pingcap/tidb/pull/12502) - - 更新了 `kvrpc.Cleanup` 协议的行为，不再清理未超时事务的锁 [#12417](https://github.com/pingcap/tidb/pull/12417) - - 支持将 Partition 表信息记录到 `information_schema.tables` 表 [#12631](https://github.com/pingcap/tidb/pull/12631) - - 支持通过 `region-cache-ttl` 配置修改 Region Cache 的 TTL [#12683](https://github.com/pingcap/tidb/pull/12683) - - 支持在慢日志中打印执行计划压缩编码后的信息，此功能默认开启，可以通过 `slow-log-plan` 配置或者 `tidb_record_plan_in_slow_log` 变量进行开关控制。另外支持 `tidb_decode_plan` 函数将慢日志中的执行计划列编码信息解析成执行计划信息。[#12808](https://github.com/pingcap/tidb/pull/12808) - - 在 `information_schema.processlist` 表中支持显示内存使用信息 [#12801](https://github.com/pingcap/tidb/pull/12801) - - 修复 TiKV Client 判断连接空闲时可能出错并出现非预期的告警的问题 [#12846](https://github.com/pingcap/tidb/pull/12846) - - 修复 `tikvSnapshot` 没有正确对 `BatchGet()` 的 KV 结果进行缓存，导致 `INSERT IGNORE` 语句性能有所下降的问题 [#12872](https://github.com/pingcap/tidb/pull/12872) - - 修复了因建立到部分 KV 服务的连接较慢最终导致 TiDB 响应速度相对变慢的情况 [#12814](https://github.com/pingcap/tidb/pull/12814) -+ DDL - - 修复 `Create Table` 操作对 Set 列不能正确设置 Int 类型默认值的问题 [#12267](https://github.com/pingcap/tidb/pull/12267) - - 支持 `Create Table` 语句中建唯一索引时带多个 Unique [#12463](https://github.com/pingcap/tidb/pull/12463) - - 修复使用 `Alter Table` 添加 Bit 类型列时，对存在的行填充此列的默认值可能出错的问题 [#12489](https://github.com/pingcap/tidb/pull/12489) - - 修复 Range 分区表以 Date 或 Datetime 类型列作为分区键时，添加分区失败的问题 [#12815](https://github.com/pingcap/tidb/pull/12815) - - 对于 Date 或 Datetime 类型列作为分区键的 Range 分区表，在建表或者添加分区时，支持检查分区类型与分区键类型的统一性 [#12792](https://github.com/pingcap/tidb/pull/12792) - - 在创建 Range 分区表时，添加对 Unique Key 列集合需大于等于分区列集合的检查 [#12718](https://github.com/pingcap/tidb/pull/12718) -+ Monitor - - 添加统计 Commit 与 Rollback 操作的监控到 **Transaction OPS** 面板 [#12505](https://github.com/pingcap/tidb/pull/12505) - - 添加统计 `Add Index` 操作进度的监控 [#12390](https://github.com/pingcap/tidb/pull/12390) - -## TiKV - -+ Storage - - 悲观事务新特性：事务 Cleanup 接口支持只清理 TTL 已经过期的锁 [#5589](https://github.com/tikv/tikv/pull/5589) - - 修复事务 Primary key 的 Rollback 被折叠的问题 [#5646](https://github.com/tikv/tikv/pull/5646)，[#5671](https://github.com/tikv/tikv/pull/5671) - - 修复悲观锁下点查可能返回历史旧版本的问题 [#5634](https://github.com/tikv/tikv/pull/5634) -+ Raftstore - - 减少 Raftstore 消息的 flush 操作，以提升性能，减少 CPU 占用 [#5617](https://github.com/tikv/tikv/pull/5617) - - 优化获取 Region 的大小和 key 个数估计值的开销，减少心跳的开销，降低 CPU 占用 [#5620](https://github.com/tikv/tikv/pull/5620) - - 修复 Raftstore 取到非法数据时打印错误日志并 panic 的问题 [#5643](https://github.com/tikv/tikv/pull/5643) -+ Engine - - 打开 RocksDB `force_consistency_checks`，提高数据安全性 [#5662](https://github.com/tikv/tikv/pull/5662) - - 修复 Titan 并发 flush 情况下有可能造成数据丢失的问题 [#5672](https://github.com/tikv/tikv/pull/5672) - - 更新 rust-rocksdb 版本以避开 intra-L0 compaction 导致 TiKV 崩溃重启的问题 [#5710](https://github.com/tikv/tikv/pull/5710) - -## PD - -- 提高 Region 占用空间的精度 [#1782](https://github.com/pingcap/pd/pull/1782) -- 修复 `--help` 命令输出内容 [#1763](https://github.com/pingcap/pd/pull/1763) -- 修复 TLS 开启后 http 请求重定向失败的问题 [#1777](https://github.com/pingcap/pd/pull/1777) -- 修复 pd-ctl 使用 `store shows limit` 命令 panic 的问题 [#1808](https://github.com/pingcap/pd/pull/1808) -- 提高 label 监控可读性以及当 leader 发生切换后重置原 leader 的监控数据，防止误报 [#1815](https://github.com/pingcap/pd/pull/1815) - -## Tools - -+ TiDB Binlog - - 修复 `ALTER DATABASE` 相关 DDL 会导致 Drainer 异常退出的问题 [#769](https://github.com/pingcap/tidb-binlog/pull/769) - - 支持对 Commit binlog 查询事务状态信息，提升同步效率 [#757](https://github.com/pingcap/tidb-binlog/pull/757) - - 修复当 Drainer 的 `start_ts` 大于 Pump 中最大的 `commit_ts` 时，有可能引起 Pump panic 的问题 [#758](https://github.com/pingcap/tidb-binlog/pull/758) -+ TiDB Lightning - - 整合 Loader 全量逻辑导入功能，支持配置 backend 模式 [#221](https://github.com/pingcap/tidb-lightning/pull/221) - -## TiDB Ansible - -- 增加 TiDB 添加索引速度的监控 [#986](https://github.com/pingcap/tidb-ansible/pull/986) -- 精简配置文件内容，移除不需要用户配置的参数 [#1043c](https://github.com/pingcap/tidb-ansible/commit/1043c3df7ddb72eb234c55858960e9fdd3830a14)，[#998](https://github.com/pingcap/tidb-ansible/pull/998) -- 修复 performance read 和 performance write 监控表达式错误的问题 [#e90e7](https://github.com/pingcap/tidb-ansible/commit/e90e79f5117bb89197e01b1391fd02e25d57a440) -- 更新 raftstore CPU 使用率的监控显示方式以及 raftstore CPU 使用率的告警规则 [#992](https://github.com/pingcap/tidb-ansible/pull/992) -- 更新 **Overview** 监控面板中 TiKV 的 CPU 监控项，过滤掉多余的监控内容 [#1001](https://github.com/pingcap/tidb-ansible/pull/1001) diff --git a/v3.0/releases/3.0.6.md b/v3.0/releases/3.0.6.md deleted file mode 100644 index 8966bfcea701..000000000000 --- a/v3.0/releases/3.0.6.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: TiDB 3.0.6 Release Notes -category: Releases ---- - -# TiDB 3.0.6 Release Notes - -发版日期：2019 年 11 月 28 日 - -TiDB 版本：3.0.6 - -TiDB Ansible 版本：3.0.6 - -## TiDB - -+ SQL 优化器 - - 修复窗口函数 AST Restore SQL 文本后结果不正确问题，`over w` 不应被 restore 成 `over (w)` [#12933](https://github.com/pingcap/tidb/pull/12933) - - 修复 stream aggregation 下推给 double read 的问题 [#12690](https://github.com/pingcap/tidb/pull/12690) - - 修复 SQL bind 中引号处理不正确的问题 [#13117](https://github.com/pingcap/tidb/pull/13117) - - 优化 `select max(_tidb_rowid) from t` 场景，避免全表扫 [#13095](https://github.com/pingcap/tidb/pull/13095) - - 修复当查询语句中包含变量赋值表达式时查询结果不正确的问题 [#13231](https://github.com/pingcap/tidb/pull/13231) - - 修复 `UPDATE` 语句中同时包含子查询和 generated column 时结果错误的问题；修复 `UPDATE` 语句中包含不同数据库的两个表名相同的表时，`UPDATE` 执行报错的问题 [#13350](https://github.com/pingcap/tidb/pull/13350) - - 支持用 `_tidb_rowid` 做点查 [#13416](https://github.com/pingcap/tidb/pull/13416) - - 修复分区表统计信息使用错误导致生成执行计划不正确的问题 [#13628](https://github.com/pingcap/tidb/pull/13628) -+ SQL 执行引擎 - - 修复 year 类型对于无效值的处理时和 MySQL 不兼容问题 [#12745](https://github.com/pingcap/tidb/pull/12745) - - 在 `INSERT ON DUPLICATE UPDATE` 语句中复用 `Chunk` 以降低内存开销 [#12998](https://github.com/pingcap/tidb/pull/12998) - - 添加内置函数 `JSON_VALID` 的支持 [#13133](https://github.com/pingcap/tidb/pull/13133) - - 支持在分区表上执行 `ADMIN CHECK TABLE` [#13140](https://github.com/pingcap/tidb/pull/13140) - - 修复对空表进行 `FAST ANALYZE` 时 panic 的问题 [#13343](https://github.com/pingcap/tidb/pull/13343) - - 修复在包含多列索引的空表上执行 Fast Analyze 时 panic 的问题 [#13394](https://github.com/pingcap/tidb/pull/13394) - - 修复当 `WHERE` 子句上有 UNIQUE KEY 的等值条件时，估算行数大于 1 的问题 [#13382](https://github.com/pingcap/tidb/pull/13382) - - 修复当 TiDB 开启 `Streaming` 后返回数据有可能重复的问题 [#13254](https://github.com/pingcap/tidb/pull/13254) - - 将 `CMSketch` 中出现次数最多的 N 个值抽取出来，提高估算准确度 [#13429](https://github.com/pingcap/tidb/pull/13429) -+ Server - - 当 gRPC 请求超时时，提前让发往 TiKV 的请求失败 [#12926](https://github.com/pingcap/tidb/pull/12926) - - 添加以下虚拟表：[#13009](https://github.com/pingcap/tidb/pull/13009) - - `performance_schema.tidb_profile_allocs` - - `performance_schema.tidb_profile_block` - - `performance_schema.tidb_profile_cpu` - - `performance_schema.tidb_profile_goroutines` - - 修复 query 在等待悲观锁时，kill query 不生效的问题 [#12989](https://github.com/pingcap/tidb/pull/12989) - - 当悲观事务上锁失败，且事务只涉及一个 key 的修改时，不再异步回滚 [#12707](https://github.com/pingcap/tidb/pull/12707) - - 修复 split Region 请求的 response 为空时 panic 的问题 [#13092](https://github.com/pingcap/tidb/pull/13092) - - 悲观事务在其他事务先锁住导致上锁失败时，避免重复 backoff [#13116](https://github.com/pingcap/tidb/pull/13116) - - 修改 TiDB 检查配置时的行为，出现不能识别的配置选项时，打印警告日志 [#13272](https://github.com/pingcap/tidb/pull/13272) - - 支持通过 `/info/all` 接口获取所有 TiDB 节点的 binlog 状态 [#13187](https://github.com/pingcap/tidb/pull/13187) - - 修复 kill connection 时可能出现 goroutine 泄漏的问题 [#13251](https://github.com/pingcap/tidb/pull/13251) - - 让 `innodb_lock_wait_timeout` 参数在悲观事务中生效，用于控制悲观锁的等锁超时时间 [#13165](https://github.com/pingcap/tidb/pull/13165) - - 当悲观事务的 query 被 kill 后，停止更新悲观事务的 TTL，避免其他的事务做不必要的等待 [#13046](https://github.com/pingcap/tidb/pull/13046) -+ DDL - - 修复 `SHOW CREATE VIEW` 结果与 MySQL 不一致的问题 [#12912](https://github.com/pingcap/tidb/pull/12912) - - 支持基于 UNION 创建 View，例如 `create view v as select * from t1 union select * from t2` [#12955](https://github.com/pingcap/tidb/pull/12955) - - 给 `slow_query` 表添加更多事务相关的字段：[#13072](https://github.com/pingcap/tidb/pull/13072) - - `Prewrite_time` - - `Commit_time` - - `Get_commit_ts_time` - - `Commit_backoff_time` - - `Backoff_types` - - `Resolve_lock_time` - - `Local_latch_wait_time` - - `Write_key` - - `Write_size` - - `Prewrite_region` - - `Txn_retry` - - 创建表时如果表包含 collate 则列使用表的 collate 而不是系统默认的字符集 [#13174](https://github.com/pingcap/tidb/pull/13174) - - 创建表时限制索引名字的长度 [#13310](https://github.com/pingcap/tidb/pull/13310) - - 修复 rename table 时未检查表名长度的问题 [#13346](https://github.com/pingcap/tidb/pull/13346) - - 新增 `alter-primary-key` 配置来支持 TiDB add/drop primary key，该配置默认关闭 [#13522](https://github.com/pingcap/tidb/pull/13522) - -## TiKV - -- 修复 `acquire_pessimistic_lock` 接口返回错误 `txn_size` 的问题 [#5740](https://github.com/tikv/tikv/pull/5740) -- 限制 GC worker 每秒写入量，降低对性能的影响 [#5735](https://github.com/tikv/tikv/pull/5735) -- 优化 lock manager 的准确度 [#5845](https://github.com/tikv/tikv/pull/5845) -- 悲观锁支持 `innodb_lock_wait_timeout` [#5848](https://github.com/tikv/tikv/pull/5848) -- 添加 Titan 相关配置检测 [#5720](https://github.com/tikv/tikv/pull/5720) -- 支持用 tikv-ctl 动态修改 GC 限流配置：`tikv-ctl --host=ip:port modify-tikv-config -m server -n gc.max_write_bytes_per_sec -v 10MB` [#5957](https://github.com/tikv/tikv/pull/5957) -- 减少无用的 clean up 请求，降低死锁检测器的压力 [#5965](https://github.com/tikv/tikv/pull/5965) -- 悲观事务 prewrite 时避免 TTL 被缩短 [#6056](https://github.com/tikv/tikv/pull/6056) -- 修复 Titan 可能发生 missing blob file 的问题 [#5968](https://github.com/tikv/tikv/pull/5968) -- 修复 Titan 可能导致 `RocksDBOptions` 不生效的问题 [#6009](https://github.com/tikv/tikv/pull/6009) - -## PD - -- 为每个过滤器添加一个名为 `ActOn` 的新维度，以指示每个 scheduler 和 checker 受过滤器的影响。删除两个未使用的过滤器：`disconnectFilter` 和 `rejectLeaderFilter` [#1911](https://github.com/pingcap/pd/pull/1911) -- 当 PD 生成时间戳的时间超过5毫秒时，将打印一条 warning 日志 [#1867](https://github.com/pingcap/pd/pull/1867) -- 当存在 endpoint 不可用时，降低 client 日志级别 [#1856](https://github.com/pingcap/pd/pull/1856) -- 修复 `region_syncer` 同步时 gRPC 消息包可能过大的问题 [#1952](https://github.com/pingcap/pd/pull/1952) - -## Tools - -+ TiDB Binlog - - Drainer 配置 `initial-commit-ts` 为 -1 时，从 PD 处获取初始同步时间戳 [#788](https://github.com/pingcap/tidb-binlog/pull/788) - - Drainer checkpoint 存储与下游解耦，支持选择配置 checkpoint 保存到 MySQL 或者本地文件 [#790](https://github.com/pingcap/tidb-binlog/pull/790) - - 修复 Drainer 在配置同步库表过滤使用空值会导致 Panic 的问题 [#801](https://github.com/pingcap/tidb-binlog/pull/801) - - 修复 Drainer 因为向下游应用 Binlog 失败而 Panic 后进程没有退出而是进入死锁状态的问题 [#807](https://github.com/pingcap/tidb-binlog/pull/807) - - 修复 Pump 下线因为 gRPC 的 `GracefulStop` 流程而 hang 住的问题 [#817](https://github.com/pingcap/tidb-binlog/pull/817) - - 修复 Drainer 在 TiDB 执行 `DROP COLUMN` DDL 期间收到缺少一列的 binlog 而同步出错的问题（要求 TiDB 3.0.6 以上）[#827](https://github.com/pingcap/tidb-binlog/pull/827) -+ TiDB Lightning - - TiDB Backend 模式新增 `max-allowed-packet` 配置项，默认值为 64M [#248](https://github.com/pingcap/tidb-lightning/pull/248) diff --git a/v3.0/releases/3.0.7.md b/v3.0/releases/3.0.7.md deleted file mode 100644 index 61e9ea511223..000000000000 --- a/v3.0/releases/3.0.7.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: TiDB 3.0.7 Release Notes -category: Releases ---- - -# TiDB 3.0.7 Release Notes - -发版日期：2019 年 12 月 4 日 - -TiDB 版本：3.0.7 - -TiDB Ansible 版本：3.0.7 - -## TiDB - -- 修复 TiDB server 本地时间落后于 TSO 时间时，可能造成锁的 TTL 过大的问题 [#13868](https://github.com/pingcap/tidb/pull/13868) -- 修复从字符串解析日期时，由于使用本地时区 (`gotime.Local`) 而导致解析结果的时区不正确的问题 [#13793](https://github.com/pingcap/tidb/pull/13793) -- 修复 `builtinIntervalRealSig` 的实现中，`binSearch` 方法不会返回 error，导致最终结果可能不正确的问题 [#13767](https://github.com/pingcap/tidb/pull/13767) -- 修复整型数据被转换为无符号浮点/Decimal 类型时，精度可能丢失造成数据错误的问题 [#13755](https://github.com/pingcap/tidb/pull/13755) -- 修复 Natural Outer Join 和 Outer Join 使用 `USING` 语法时，`not null` 标记没有被重置导致结果错误的问题 [#13739](https://github.com/pingcap/tidb/pull/13739) -- 修复更新统计信息时可能存在数据竞争，导致统计信息不准确的问题 [#13687](https://github.com/pingcap/tidb/pull/13687) - -## TiKV - -- 判断死锁检测服务的第一个 Region 时，加上 Region 合法检测，防止信息不完整的 Region 导致误判 [#6110](https://github.com/tikv/tikv/pull/6110) -- 修复潜在的内存泄漏问题 [#6128](https://github.com/tikv/tikv/pull/6128) diff --git a/v3.0/releases/3.0.8.md b/v3.0/releases/3.0.8.md deleted file mode 100644 index 51bb1a732c0e..000000000000 --- a/v3.0/releases/3.0.8.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: TiDB 3.0.8 Release Notes -category: Releases ---- - -# TiDB 3.0.8 Release Notes - -发版日期：2019 年 12 月 31 日 - -TiDB 版本：3.0.8 - -TiDB Ansible 版本：3.0.8 - -## TiDB - -+ SQL 优化器 - - 修复 SQL Binding 因为 cache 更新不及时，导致绑定计划错误的问题 [#13891](https://github.com/pingcap/tidb/pull/13891) - - 修复当 SQL 包含符号列表（类似于 "?, ?, ?" 这样的占位符）时，SQL Binding 可能失效的问题 [#14004](https://github.com/pingcap/tidb/pull/14004) - - 修复 SQL Binding 由于原 SQL 以 `;` 结尾而不能创建/删除的问题 [#14113](https://github.com/pingcap/tidb/pull/14113) - - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14133](https://github.com/pingcap/tidb/pull/14133) - - 移除 `minAutoAnalyzeRatio` 约束使自动 analyze 更及时 [#14015](https://github.com/pingcap/tidb/pull/14015) -+ SQL 执行引擎 - - 修复 `INSERT/REPLACE/UPDATE ... SET ... = DEFAULT` 语法会报错的问题，修复 `DEFAULT` 表达式与虚拟生成列配合使用会报错的问题 [#13682](https://github.com/pingcap/tidb/pull/13682) - - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14011](https://github.com/pingcap/tidb/pull/14011) - - 修复 `HashAgg` Executor 并发值未被正确初始化，导致聚合操作执行在一些情况下效率低的问题 [#13811](https://github.com/pingcap/tidb/pull/13811) - - 修复 group by item 被括号包含时执行报错的问题 [#13658](https://github.com/pingcap/tidb/pull/13658) - - 修复 TiDB 没有正确计算 group by item，导致某些情况下 OUTER JOIN 执行会报错的问题 [#14014](https://github.com/pingcap/tidb/pull/14014) - - 修复向 Range 分区表写入超过 Range 外的数据时，报错信息不准确的问题 [#14107](https://github.com/pingcap/tidb/pull/14107) - - 鉴于 MySQL 8 即将废弃 `PadCharToFullLength`，revert PR [#10124](https://github.com/pingcap/tidb/pull/10124) 并撤销 `PadCharToFullLength` 的效果，以避免一些特殊情况下查询结果不符合预期 [#14157](https://github.com/pingcap/tidb/pull/14157) - - 修复 `ExplainExec` 中没有保证 `close()` 的调用而导致 `EXPLAIN ANALYZE` 时造成 goroutine 泄露的问题 [#14226](https://github.com/pingcap/tidb/pull/14226) -+ DDL - - 优化 "change column"/"modify column" 的输出的报错信息，让人更容易理解 [#13796](https://github.com/pingcap/tidb/pull/13796) - - 新增 `SPLIT PARTITION TABLE` 语法，支持分区表切分 Region 功能 [#13929](https://github.com/pingcap/tidb/pull/13929) - - 修复创建索引时，没有正确检查长度，导致索引长度超过 3072 字节没有报错的问题 [#13779](https://github.com/pingcap/tidb/pull/13779) - - 修复由于分区表添加索引时若花费时间过长，可能导致输出 `GC life time is shorter than transaction duration` 报错信息的问题 [#14132](https://github.com/pingcap/tidb/pull/14132) - - 修复在 `DROP COLUMN`/`MODIFY COLUMN`/`CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14105](https://github.com/pingcap/tidb/pull/14105) -+ Server - - Statement Summary 功能改进： - - 新增大量的 SQL 指标字段，便于对 SQL 进行更详细的统计分析 [#14151](https://github.com/pingcap/tidb/pull/14151)，[#14168](https://github.com/pingcap/tidb/pull/14168) - - 新增 `stmt-summary.refresh-interval` 参数用于控制定期将 `events_statements_summary_by_digest` 表中过期的数据移到 `events_statements_summary_by_digest_history` 表，默认间隔时间：30min [#14161](https://github.com/pingcap/tidb/pull/14161) - - 新增 `events_statements_summary_by_digest_history` 表，保存从 `events_statements_summary_by_digest` 中过期的数据 [#14166](https://github.com/pingcap/tidb/pull/14166) - - 修复执行 RBAC 相关的内部 SQL 时，错误输出 binlog 的问题 [#13890](https://github.com/pingcap/tidb/pull/13890) - - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13906](https://github.com/pingcap/tidb/pull/13906) - - 新增通过 HTTP 接口恢复 TiDB binlog 写入功能 [#13892](https://github.com/pingcap/tidb/pull/13892) - - 将 `GRANT roles TO user` 所需要的权限由 `GrantPriv` 修改为 `ROLE_ADMIN` 或 `SUPER`，以与 MySQL 保持一致 [#13932](https://github.com/pingcap/tidb/pull/13932) - - 当 `GRANT` 语句未指定 database 名时，TiDB 行为由使用当前 database 改为报错 `No database selected`，与 MySQL 保持兼容 [#13784](https://github.com/pingcap/tidb/pull/13784) - - 修改 `REVOKE` 语句执行权限从 `SuperPriv` 改成用户只需要有对应 Schema 的权限，就可以执行 `REVOKE` 语句，与 MySQL 保持一致 [#13306](https://github.com/pingcap/tidb/pull/13306) - - 修复 `GRANT ALL` 语法在没有 `WITH GRANT OPTION` 时，错误地将 `GrantPriv` 授权给目标用户的问题 [#13943](https://github.com/pingcap/tidb/pull/13943) - - 修复 `LoadDataInfo` 中调用 `addRecord` 报错时，报错信息不包含导致 `LOAD DATA` 语句行为不正确信息的问题 [#13980](https://github.com/pingcap/tidb/pull/13980) - - 修复因查询中多个 SQL 语句共用同一个 `StartTime` 导致输出错误的慢查询信息的问题 [#13898](https://github.com/pingcap/tidb/pull/13898) - - 修复 `batchClient` 处理大事务时可能造成内存泄露的问题 [#14032](https://github.com/pingcap/tidb/pull/14032) - - 修复 `system_time_zone` 固定显示为 `CST` 的问题，现在 TiDB 的 `system_time_zone` 会从 `mysql.tidb` 表中的 `systemTZ` 获取 [#14086](https://github.com/pingcap/tidb/pull/14086) - - 修复 `GRANT ALL` 语法授予权限不完整（例如 `Lock_tables_priv`）的问题 [#14092](https://github.com/pingcap/tidb/pull/14092) - - 修复 `Priv_create_user` 权限不能 `CREATE ROLE` 和 `DROP ROLE`的问题 [#14088](https://github.com/pingcap/tidb/pull/14088) - - 将 `ErrInvalidFieldSize` 的错误码从 `1105(Unknow Error)` 改成 `3013` [#13737](https://github.com/pingcap/tidb/pull/13737) - - 新增 `SHUTDOWN` 命令用于停止 TiDB Server，并新增 `ShutdownPriv` 权限 [#14104](https://github.com/pingcap/tidb/pull/14104) - - 修复 `DROP ROLE` 语句的原子性问题，避免语句执行失败时，一些 ROLE 仍然被非预期地删除 [#14130](https://github.com/pingcap/tidb/pull/14130) - - 修复 3.0 以下版本升级到 3.0 时，`tidb_enable_window_function` 在 `SHOW VARIABLE` 语句的查询结果错误输出 1 的问题，修复后输出 0 [#14131](https://github.com/pingcap/tidb/pull/14131) - - 修复 TiKV 节点下线时，由于 `gcworker` 持续重试导致可能出现 goroutine 泄露的问题 [#14106](https://github.com/pingcap/tidb/pull/14106) - - 在慢日志中记录 Binlog 的 `Prewrite` 的时间，提升问题追查的易用性 [#14138](https://github.com/pingcap/tidb/pull/14138) - - `tidb_enable_table_partition` 变量支持 GLOBAL SCOPE 作用域 [#14091](https://github.com/pingcap/tidb/pull/14091) - - 修复新增权限时未正确将新增的权限赋予对应的用户导致用户权限可能缺失或者被误添加的问题 [#14178](https://github.com/pingcap/tidb/pull/14178) - - 修复当 TiKV 链接断开时，由于 `rpcClient` 不会关闭而导致 `CheckStreamTimeoutLoop` goroutine 会泄露的问题 [#14227](https://github.com/pingcap/tidb/pull/14227) - - 支持基于证书的身份验证（[使用文档](/v3.0/reference/security/cert-based-authentication.md)）[#13955](https://github.com/pingcap/tidb/pull/13955) -+ Transaction - - 创建新集群时，`tidb_txn_mode` 变量的默认值由 `""` 改为 `"pessimistic"` [#14171](https://github.com/pingcap/tidb/pull/14171) - - 修复悲观事务模式，事务重试时单条语句的等锁时间没有被重置导致等锁时间过长的问题 [#13990](https://github.com/pingcap/tidb/pull/13990) - - 修复悲观事务模式，因对没有修改的数据未加锁导致可能读到不正确数据的问题 [#14050](https://github.com/pingcap/tidb/pull/14050) - - 修复 mocktikv 中 prewrite 时，没有区分事务类型，导致重复的 insert value 约束检查 [#14175](https://github.com/pingcap/tidb/pull/14175) - - 修复 `session.TxnState` 状态为 `Invalid` 时，事务没有被正确处理导致 panic 的问题 [#13988](https://github.com/pingcap/tidb/pull/13988) - - 修复 mocktikv 中 `ErrConfclit` 结构未包含 `ConflictCommitTS` 的问题 [#14080](https://github.com/pingcap/tidb/pull/14080) - - 修复 TiDB 在 Resolve Lock 之后，没有正确处理锁超时检查导致事务卡住的问题 [#14083](https://github.com/pingcap/tidb/pull/14083) -+ Monitor - - `LockKeys` 新增 `pessimistic_lock_keys_duration` 监控 [#14194](https://github.com/pingcap/tidb/pull/14194) - -## TiKV - -+ Coprocessor - - 修改 Coprocessor 遇到错误时输出日志的级别从 `error` 改成 `warn` [#6051](https://github.com/tikv/tikv/pull/6051) - - 修改统计信息采样数据的更新行为从直接更行改成先删除再插入，更新行为与 tidb-server 保持一致 [#6069](https://github.com/tikv/tikv/pull/6096) -+ Raftstore - - 修复因重复向 `peerfsm` 发送 destory 消息，`peerfsm` 被多次销毁导致 panic 的问题 [#6297](https://github.com/tikv/tikv/pull/6297) - - `split-region-on-table` 默认值由 `true` 改成 `false`，默认关闭按 table 切分 Region 的功能 [#6253](https://github.com/tikv/tikv/pull/6253) -+ Engine - - 修复极端条件下因 RocksDB 迭代器错误未正确处理导致可能返回空数据的问题 [#6326](https://github.com/tikv/tikv/pull/6326) -+ 事务 - - 修复悲观锁因锁未被正确清理导致 Key 无法写入数据，且出现 GC 卡住的问题 [#6354](https://github.com/tikv/tikv/pull/6354) - - 优化悲观锁等锁机制，提升锁冲突严重场景的性能 [#6296](https://github.com/tikv/tikv/pull/6296) -+ 将内存分配库的默认值由 `tikv_alloc/default` 改成 `jemalloc` [#6206](https://github.com/tikv/tikv/pull/6206) - -## PD - -- Client - - 新增通过 `context` 创建新 client，创建新 client 时可设置超时时间 [#1994](https://github.com/pingcap/pd/pull/1994) - - 新增创建 `KeepAlive` 连接功能 [#2035](https://github.com/pingcap/pd/pull/2035) -- 优化`/api/v1/regions` API 的性能 [#1986](https://github.com/pingcap/pd/pull/1986) -- 修复删除 `tombstone` 状态的 Store 可能会导致 panic 的隐患 [#2038](https://github.com/pingcap/pd/pull/2038) -- 修复从磁盘加载 Region 信息时错误的将范围有重叠的 Region 删除的问题 [#2011](https://github.com/pingcap/pd/issues/2011)，[#2040](https://github.com/pingcap/pd/pull/2040) -- 将 etcd 版本从 3.4.0 升级到 3.4.3 稳定版本，注意升级后只能通过 pd-recover 工具降级 [#2058](https://github.com/pingcap/pd/pull/2058) - -## Tools - -+ TiDB Binlog - - 修复 Pump 由于没有收到 DDL 的 commit binlog 导致 binlog 被忽略的问题 [#853](https://github.com/pingcap/tidb-binlog/pull/853) - -## TiDB Ansible - -- 回滚被精简的配置项 [#1053](https://github.com/pingcap/tidb-ansible/pull/1053) -- 优化滚动升级时 TiDB 版本检查的逻辑 [#1056](https://github.com/pingcap/tidb-ansible/pull/1056) -- TiSpark 版本升级到 2.1.8 [#1061](https://github.com/pingcap/tidb-ansible/pull/1061) -- 修复 Grafana 监控上 PD 页面 Role 监控项显示不正确的问题 [#1065](https://github.com/pingcap/tidb-ansible/pull/1065) -- 优化 Grafana 监控上 TiKV Detail 页面上 `Thread Voluntary Context Switches` 和 `Thread Nonvoluntary Context Switches` 监控项 [#1071](https://github.com/pingcap/tidb-ansible/pull/1071) diff --git a/v3.0/releases/3.0.9.md b/v3.0/releases/3.0.9.md deleted file mode 100644 index 3b35cfaaac19..000000000000 --- a/v3.0/releases/3.0.9.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: TiDB 3.0.9 Release Notes -category: Releases ---- - -# TiDB 3.0.9 Release Notes - -发版日期：2020 年 01 月 14 日 - -TiDB 版本：3.0.9 - -TiDB Ansible 版本：3.0.9 - -## TiDB - -+ Executor - - 修复聚合函数作用于枚举和集合列时结果不正确的问题 [#14364](https://github.com/pingcap/tidb/pull/14364) -+ Server - - 支持系统变量 `auto_increment_increment` 和 `auto_increment_offset` [#14396](https://github.com/pingcap/tidb/pull/14396) - - 新增 `tidb_tikvclient_ttl_lifetime_reach_total` 监控项，监控悲观事务 TTL 达到 10 分钟的数量 [#14300](https://github.com/pingcap/tidb/pull/14300) - - 执行 SQL 过程中当发生 panic 时输出导致 panic 的 SQL 信息 [#14322](https://github.com/pingcap/tidb/pull/14322) - - statement summary 系统表新增 `plan` 和 `plan_digest` 字段，记录当前正在执行的 `plan` 和 `plan` 的签名 [#14285](https://github.com/pingcap/tidb/pull/14285) - - 配置项 `stmt-summary.max-stmt-count` 的默认值从 `100` 调整至 `200` [#14285](https://github.com/pingcap/tidb/pull/14285) - - slow query 表新增 `plan_digest` 字段，记录 `plan` 的签名 [#14292](https://github.com/pingcap/tidb/pull/14292) -+ DDL - - 修复 `alter table ... add index` 语句创建匿名索引行为与 MySQL 不一致的问题 [#14310](https://github.com/pingcap/tidb/pull/14310) - - 修复 `drop table` 错误删除视图的问题 [#14052](https://github.com/pingcap/tidb/pull/14052) -+ Planner - - 提升类似 `select max(a), min(a) from t` 语句的性能。如果 `a` 列表上有索引，该语句会被优化为 `select * from (select a from t order by a desc limit 1) as t1, (select a from t order by a limit 1) as t2` 以避免全表扫 [#14410](https://github.com/pingcap/tidb/pull/14410) - -## TiKV - -+ Raftstore - - 提升 Raft 成员变更的速度 [#6421](https://github.com/tikv/tikv/pull/6421) -+ Transaction - - 新增 `tikv_lock_manager_waiter_lifetime_duration`、`tikv_lock_manager_detect_duration`、`tikv_lock_manager_detect_duration` 监控项，用于监控 `waiter` 的生命周期、死锁检测耗费时间、`wait table` 的状态 [#6392](https://github.com/tikv/tikv/pull/6422) - - 通过优化配置项 `wait-for-lock-time` 默认值从 `3s` 调整到 `1s`、`wake-up-delay-duration` 默认值从 `100ms` 调整为 `20ms`，以降低极端场景下 Region Leader 切换、切换死锁检测的 leader 导致的事务执行延迟 [#6429](https://github.com/tikv/tikv/pull/6429) - - 修复 Region Merge 过程中可能导致死锁检测器 leader 角色误判的问题 [#6431](https://github.com/tikv/tikv/pull/6431) - -## PD - -+ 新增 location label 的名字中允许使用斜杠 `/` 的功能 [#2083](https://github.com/pingcap/pd/pull/2083) -+ 修复因为不正确地统计了 tombstone 的标签，导致该统计信息不准的问题 [#2060](https://github.com/pingcap/pd/issues/2060) - -## Tools - -+ TiDB Binlog - - Drainer 输出的 binlog 协议中新增 unique key 信息 [#862](https://github.com/pingcap/tidb-binlog/pull/862) - - Drainer 支持使用加密后的数据库连接密码 [#868](https://github.com/pingcap/tidb-binlog/pull/868) - -## TiDB Ansible - -+ 优化 Lightning 部署，自动创建相关目录 [#1105](https://github.com/pingcap/tidb-ansible/pull/1105) diff --git a/v3.0/releases/3.0beta.md b/v3.0/releases/3.0beta.md deleted file mode 100644 index d868f298cfb4..000000000000 --- a/v3.0/releases/3.0beta.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: TiDB 3.0 Beta Release Notes -category: Releases -aliases: ['/docs-cn/releases/3.0beta/'] ---- - -# TiDB 3.0 Beta Release Notes - -2019 年 1 月 19 日，TiDB 发布 3.0 Beta 版，TiDB Ansible 相应发布 3.0 Beta 版本。相比 2.1 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 新特性 - - 支持 View - - 支持窗口函数 - - 支持 Range 分区 - - 支持 Hash 分区 -+ SQL 优化器 - - 重新支持聚合消除的优化规则 [#7676](https://github.com/pingcap/tidb/pull/7676) - - 优化 `NOT EXISTS` 子查询，将其转化为 Anti Semi Join [#7842](https://github.com/pingcap/tidb/pull/7842) - - 添加 `tidb_enable_cascades_planner` 变量以支持新的 Cascades 优化器。目前 Cascades 优化器尚未实现完全，默认关闭 [#7879](https://github.com/pingcap/tidb/pull/7879) - - 支持在事务中使用 Index Join [#7877](https://github.com/pingcap/tidb/pull/7877) - - 优化 Outer Join 上的常量传播，使得对 Join 结果里和 Outer 表相关的过滤条件能够下推过 Outer Join 到 Outer 表上，减少 Outer Join 的无用计算量，提升执行性能 [#7794](https://github.com/pingcap/tidb/pull/7794) - - 调整投影消除的优化规则到聚合消除之后，消除掉冗余的 `Project` 算子 [#7909](https://github.com/pingcap/tidb/pull/7909) - - 优化 `IFNULL` 函数，当输入参数具有非 NULL 的属性的时候，消除该函数 [#7924](https://github.com/pingcap/tidb/pull/7924) - - 支持对 `_tidb_rowid` 构造查询的 Range，避免全表扫，减轻集群压力 [#8047](https://github.com/pingcap/tidb/pull/8047) - - 优化 `IN` 子查询为先聚合后做 Inner Join 并，添加变量 `tidb_opt_insubq_to_join_and_agg` 以控制是否开启该优化规则并默认打开 [#7531](https://github.com/pingcap/tidb/pull/7531) - - 支持在 `DO` 语句中使用子查询 [#8343](https://github.com/pingcap/tidb/pull/8343) - - 添加 Outer Join 消除的优化规则，减少不必要的扫表和 Join 操作，提升执行性能 [#8021](https://github.com/pingcap/tidb/pull/8021) - - 修改 `TIDB_INLJ` 优化器 Hint 的行为，优化器将使用 Hint 中指定的表当做 Index Join 的 Inner 表 [#8243](https://github.com/pingcap/tidb/pull/8243) - - 更大范围的启用 `PointGet`，使得当 Prepare 语句的执行计划缓存生效时也能利用上它 [#8108](https://github.com/pingcap/tidb/pull/8108) - - 引入贪心的 Join Reorder 算法，优化多表 Join 时 Join 顺序选择的问题 [#8394](https://github.com/pingcap/tidb/pull/8394) - - 支持 View [#8757](https://github.com/pingcap/tidb/pull/8757) - - 支持 Window Function [#8630](https://github.com/pingcap/tidb/pull/8630) - - 当 `TIDB_INLJ` 未生效时，返回 warning 给客户端，增强易用性 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 支持根据过滤条件和表的统计信息推导过滤后数据的统计信息的功能 [#7921](https://github.com/pingcap/tidb/pull/7921) - - 增强 Range Partition 的 Partition Pruning 优化规则 [#8885](https://github.com/pingcap/tidb/pull/8885) -+ SQL 执行引擎 - - 优化 Merge Join 算子，使其支持空的 `ON` 条件 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 优化日志，打印执行 `EXECUTE` 语句时使用的用户变量 [#7684](https://github.com/pingcap/tidb/pull/7684) - - 优化日志，为 `COMMIT` 语句打印慢查询信息 [#7951](https://github.com/pingcap/tidb/pull/7951) - - 支持 `EXPLAIN ANALYZE` 功能，使得 SQL 调优过程更加简单 [#7827](https://github.com/pingcap/tidb/pull/7827) - - 优化列很多的宽表的写入性能 [#7935](https://github.com/pingcap/tidb/pull/7935) - - 支持 `admin show next_row_id` [#8242](https://github.com/pingcap/tidb/pull/8242) - - 添加变量 `tidb_init_chunk_size` 以控制执行引擎使用的初始 Chunk 大小 [#8480](https://github.com/pingcap/tidb/pull/8480) - - 完善 `shard_row_id_bits`，对自增 ID 做越界检查 [#8936](https://github.com/pingcap/tidb/pull/8936) -+ `Prepare` 语句 - - 对包含子查询的 `Prepare` 语句，禁止其添加到 `Prepare` 语句的执行计划缓存中，确保输入不同的用户变量时执行计划的正确性 [#8064](https://github.com/pingcap/tidb/pull/8064) - - 优化 `Prepare` 语句的执行计划缓存，使得当语句中包含非确定性函数的时候，该语句的执行计划也能被缓存 [#8105](https://github.com/pingcap/tidb/pull/8105) - - 优化 `Prepare` 语句的执行计划缓存，使得 `DELETE`/`UPDATE`/`INSERT` 的执行计划也能被缓存 [#8107](https://github.com/pingcap/tidb/pull/8107) - - 优化 `Prepare` 语句的执行计划缓存，当执行 `DEALLOCATE` 语句时从缓存中剔除对应的执行计划 [#8332](https://github.com/pingcap/tidb/pull/8332) - - 优化 `Prepare` 语句的执行计划缓存，通过控制其内存使用以避免缓存过多执行计划导致 TiDB OOM 的问题 [#8339](https://github.com/pingcap/tidb/pull/8339) - - 优化 `Prepare` 语句，使得 `ORDER BY`/`GROUP BY`/`LIMIT` 子句中可以使用 “?” 占位符 [#8206](https://github.com/pingcap/tidb/pull/8206) -+ 权限管理 - - 增加对 `ANALYZE` 语句的权限检查 [#8486](https://github.com/pingcap/tidb/pull/8486) - - 增加对 `USE` 语句的权限检查 [#8414](https://github.com/pingcap/tidb/pull/8418) - - 增加对 `SET GLOBAL` 语句的权限检查 [#8837](https://github.com/pingcap/tidb/pull/8837) - - 增加对 `SHOW PROCESSLIST` 语句的权限检查 [#7858](https://github.com/pingcap/tidb/pull/7858) -+ Server - - 支持了对 SQL 语句的 `Trace` 功能 [#9029](https://github.com/pingcap/tidb/pull/9029) - - 支持了插件框架 [#8788](https://github.com/pingcap/tidb/pull/8788) - - 支持同时使用 `unix_socket` 和 TCP 两种方式连接数据库 [#8836](https://github.com/pingcap/tidb/pull/8836) - - 支持了系统变量 `interactive_timeout` [#8573](https://github.com/pingcap/tidb/pull/8573) - - 支持了系统变量 `wait_timeout` [#8346](https://github.com/pingcap/tidb/pull/8346) - - 提供了变量 `tidb_batch_commit`，可以按语句数将事务分解为多个事务 [#8293](https://github.com/pingcap/tidb/pull/8293) - - 支持 `ADMIN SHOW SLOW` 语句，方便查看慢日志 [#7785](https://github.com/pingcap/tidb/pull/7785) -+ 兼容性 - - 支持了 `ALLOW_INVALID_DATES` 这种 SQL mode [#9027](https://github.com/pingcap/tidb/pull/9027) - - 提升了 load data 对 CSV 文件的容错能力 [#9005](https://github.com/pingcap/tidb/pull/9005) - - 支持了 MySQL 320 握手协议 [#8812](https://github.com/pingcap/tidb/pull/8812) - - 支持将 unsigned bigint 列声明为自增列 [#8181](https://github.com/pingcap/tidb/pull/8181) - - 支持 `SHOW CREATE DATABASE IF NOT EXISTS` 语法 [#8926](https://github.com/pingcap/tidb/pull/8926) - - 当过滤条件中包含用户变量时不对其进行谓词下推的操作，更加兼容 MySQL 中使用用户变量模拟 Window Function 的行为 [#8412](https://github.com/pingcap/tidb/pull/8412) -+ DDL - - 支持快速恢复误删除的表 [#7937](https://github.com/pingcap/tidb/pull/7937) - - 支持动态调整 ADD INDEX 的并发数 [#8295](https://github.com/pingcap/tidb/pull/8295) - - 支持更改表或者列的字符集到 utf8/utf8mb4 [#8037](https://github.com/pingcap/tidb/pull/8037) - - 默认字符集从 `utf8` 变为 `utf8mb4` [#7965](https://github.com/pingcap/tidb/pull/7965) - - 支持 RANGE PARTITION [#8011](https://github.com/pingcap/tidb/pull/8011) - -## Tools - -+ TiDB Lightning - - 大幅优化 SQL 转 KV 的处理速度 [#110](https://github.com/pingcap/tidb-lightning/pull/110) - - 对单表支持 batch 导入，提高导入性能和稳定性 [#113](https://github.com/pingcap/tidb-lightning/pull/113) - -## PD - -- 增加 `RegionStorage` 单独存储 Region 元信息 [#1237](https://github.com/pingcap/pd/pull/1237) -- 增加 shuffle hot region 调度 [#1361](https://github.com/pingcap/pd/pull/1361) -- 增加调度参数相关 Metrics [#1406](https://github.com/pingcap/pd/pull/1406) -- 增加集群 Label 信息相关 Metrics [#1402](https://github.com/pingcap/pd/pull/1402) -- 增加导入数据场景模拟 [#1263](https://github.com/pingcap/pd/pull/1263) -- 修复 Leader 选举相关的 Watch 问题 [#1396](https://github.com/pingcap/pd/pull/1396) - -## TiKV - -- 支持了分布式 GC [#3179](https://github.com/tikv/tikv/pull/3179) -- 在 Apply snapshot 之前检查 RocksDB level 0 文件，避免产生 Write stall [#3606](https://github.com/tikv/tikv/pull/3606) -- 支持了逆向 `raw_scan` 和 `raw_batch_scan` [#3742](https://github.com/tikv/tikv/pull/3724) -- 更好的夏令时支持 [#3786](https://github.com/tikv/tikv/pull/3786) -- 支持了使用 HTTP 方式获取监控信息 [#3855](https://github.com/tikv/tikv/pull/3855) -- 支持批量方式接收和发送 Raft 消息 [#3931](https://github.com/tikv/tikv/pull/3913) -- 引入了新的存储引擎 Titan [#3985](https://github.com/tikv/tikv/pull/3985) -- 升级 gRPC 到 v1.17.2 [#4023](https://github.com/tikv/tikv/pull/4023) -- 支持批量方式接收客户端请求和发送回复 [#4043](https://github.com/tikv/tikv/pull/4043) -- 多线程 Apply [#4044](https://github.com/tikv/tikv/pull/4044) -- 多线程 Raftstore [#4066](https://github.com/tikv/tikv/pull/4066) diff --git a/v3.0/releases/ga.md b/v3.0/releases/ga.md deleted file mode 100644 index cb7bec61da05..000000000000 --- a/v3.0/releases/ga.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: TiDB 1.0 release notes -category: Releases -aliases: ['/docs-cn/releases/ga/'] ---- - -# TiDB 1.0 Release Notes - -2017 年 10 月 16 日，TiDB 发布 GA 版（TiDB 1.0）。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB: - -+ SQL 查询优化器 - - 调整代价模型 - - Analyze 下推 - - 函数签名下推 - -+ 优化内部数据格式，减小中间结果大小 -+ 提升 MySQL 兼容性 -+ 支持 `NO_SQL_CACHE` 语法，控制存储引擎对缓存的使用 -+ 重构 Hash Aggregator 算子，降低内存使用 -+ 支持 Stream Aggragator 算子 - -## PD: - -+ 支持基于读流量的热点调度 -+ 支持设置 Store 权重，以及基于权重的调度 - -## TiKV: - -+ Coprocessor 支持更多下推函数 -+ 支持取样操作下推 -+ 支持手动触发数据 Compact，用于快速回收空间 -+ 提升性能和稳定性 -+ 增加 Debug API，方便调试 - -## TiSpark Beta Release: - -+ 支持可配置框架 -+ 支持 ThriftSever/JDBC 和 Spark SQL 脚本入口 - -## 源码地址 - -[源码地址](https://github.com/pingcap/tidb) - -## 鸣谢 - -### 特别感谢参与项目的企业和团队 - -- Archon -- Mobike -- SpeedyCloud -- UCloud -- 腾讯云 -- 韩国三星研究院 - -### 感谢以下组织/个人提供出色的开源软件/服务： - -- Asta Xie -- CNCF -- CoreOS -- Databricks -- Docker -- Github -- Grafana -- gRPC -- Jepsen -- Kubernetes -- Namazu -- Prometheus -- RedHat -- RocksDB Team -- Rust Team - -### 感谢社区个人贡献者 TiDB Contributor - -- 8cbx -- Akihiro Suda -- aliyx -- alston111111 -- andelf -- Andy Librian -- Arthur Yang -- astaxie -- Bai, Yang -- bailaohe -- Bin Liu -- Blame cosmos -- Breezewish -- Carlos Ferreira -- Ce Gao -- Changjian Zhang -- Cheng Lian -- Cholerae Hu -- Chu Chao -- coldwater -- Cole R Lawrence -- cuiqiu -- cuiyuan -- Cwen -- Dagang -- David Chen -- David Ding -- dawxy -- dcadevil -- Deshi Xiao -- Di Tang -- disksing -- dongxu -- dreamquster -- Drogon -- Du Chuan -- Dylan Wen -- eBoyy -- Eric Romano -- Ewan Chou -- Fiisio -- follitude -- Fred Wang -- follitude -- fud -- fudali -- gaoyangxiaozhu -- Gogs -- goroutine -- Gregory Ian -- Guanqun Lu -- Guilherme Hübner Franco -- Haibin Xie -- Han Fei -- Hiroaki Nakamura -- hiwjd -- Hongyuan Wang -- Hu Ming -- Hu Ziming -- Huachao Huang -- HuaiyuXu -- Huxley Hu -- iamxy -- Ian -- insion -- iroi44 -- Ivan.Yang -- Jack Yu -- jacky liu -- Jan Mercl -- Jason W -- Jay -- Jay Lee -- Jianfei Wang -- Jiaxing Liang -- Jie Zhou -- jinhelin -- Jonathan Boulle -- Karl Ostendorf -- knarfeh -- Kuiba -- leixuechun -- li -- Li Shihai -- Liao Qiang -- Light -- lijian -- Lilian Lee -- Liqueur Librazy -- Liu Cong -- Liu Shaohui -- liubo0127 -- liyanan -- lkk2003rty -- Louis -- louishust -- luckcolors -- Lynn -- Mae Huang -- maiyang -- maxwell -- mengshangqi -- Michael Belenchenko -- mo2zie -- morefreeze -- MQ -- mxlxm -- Neil Shen -- netroby -- ngaut -- Nicole Nie -- nolouch -- onlymellb -- overvenus -- PaladinTyrion -- paulg -- Priya Seth -- qgxiaozhan -- qhsong -- Qiannan -- qiuyesuifeng -- queenypingcap -- qupeng -- Rain Li -- ranxiaolong -- Ray -- Rick Yu -- shady -- ShawnLi -- Shen Li -- Sheng Tang -- Shirly -- Shuai Li -- ShuNing -- ShuYu Wang -- siddontang -- silenceper -- Simon J Mudd -- Simon Xia -- skimmilk6877 -- sllt -- soup -- Sphinx -- Steffen -- sumBug -- sunhao2017 -- Tao Meng -- Tao Zhou -- tennix -- tiancaiamao -- TianGuangyu -- Tristan Su -- ueizhou -- UncP -- Unknwon -- v01dstar -- Van -- WangXiangUSTC -- wangyisong1996 -- weekface -- wegel -- Wei Fu -- Wenbin Xiao -- Wenting Li -- Wenxuan Shi -- winkyao -- woodpenker -- wuxuelian -- Xiang Li -- xiaojian cai -- Xuanjia Yang -- Xuanwo -- XuHuaiyu -- Yang Zhexuan -- Yann Autissier -- Yanzhe Chen -- Yiding Cui -- Yim -- youyouhu -- Yu Jun -- Yuwen Shen -- Zejun Li -- Zhang Yuning -- zhangjinpeng1987 -- ZHAO Yijun -- ZhengQian -- ZhengQianFang -- zhengwanbo -- Zhe-xuan Yang -- ZhiFeng Hu -- Zhiyuan Zheng -- Zhou Tao -- Zhoubirdblue -- zhouningnan -- Ziyi Yan -- zs634134578 -- zyguan -- zz-jason -- qiukeren -- hawkingrei -- wangyanjun -- zxylvlp diff --git a/v3.0/releases/prega.md b/v3.0/releases/prega.md deleted file mode 100644 index 078e8a5260b9..000000000000 --- a/v3.0/releases/prega.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB Pre-GA Release Notes -category: Releases -aliases: ['/docs-cn/releases/prega/'] ---- - -# TiDB Pre-GA Release Notes - -2017 年 8 月 30 日，TiDB 发布 Pre-GA 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -+ SQL 查询优化器 - - 调整代价模型 - - 优化索引选择，支持不同类型字段比较的索引选择 - - 支持基于贪心算法的 Join Reorder -+ 大量 MySQL 兼容性相关功能 -+ 支持 Natural Join -+ 完成 JSON 类型支持 (Experimental)，包括对 JSON 中的字段查询、更新、建索引 -+ 裁剪无用数据，减小执行器内存消耗 -+ 支持在 SQL 语句中设置优先级，并根据查询类型自动设置部分语句的优先级 -+ 完成表达式重构，执行速度提升 30% 左右 - -## PD - -+ 支持手动切换 PD 集群 Leader - -## TiKV - -+ Raft Log 使用独立的 RocksDB 实例 -+ 使用 DeleteRange 加快删除副本速度 -+ Coprocessor 支持更多运算符下推 -+ 提升性能，提升稳定性 - -## TiSpark Beta Release - -+ 支持谓词下推 -+ 支持聚合下推 -+ 支持范围裁剪 -+ 通过 TPC-H 测试 (除去一个需要 View 的 Query) diff --git a/v3.0/releases/rc1.md b/v3.0/releases/rc1.md deleted file mode 100644 index 617042f6be2d..000000000000 --- a/v3.0/releases/rc1.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: TiDB RC1 Release Notes -category: Releases -aliases: ['/docs-cn/releases/rc1/'] ---- - -# TiDB RC1 Release Notes - -2016 年 12 月 23 日，分布式关系型数据库 TiDB 正式发布 RC1。 - -## TiKV - -+ 提升写入速度 -+ 降低磁盘空间占用 -+ 支持百 TB 级别数据 -+ 提升稳定性，集群规模支持 200 个节点 -+ 提供 Raw KV API，以及 Golang client - -## PD - -+ PD 调度策略框架优化，策略更加灵活合理 -+ 添加 label 支持，支持跨 DC 调度 -+ 提供 PD Controler，方便操作 PD 集群 - -## TiDB - -+ SQL 查询优化器 - - 支持 eager aggregate - - 更详细的 explain 信息 - - union 算子并行化 - - 子查询性能优化 - - 条件下推优化 - - 优化 CBO 框架 -+ 重构 time 相关类型的实现，提升和 MySQL 的兼容性 -+ 支持更多的 MySQL 内建函数 -+ Add Index 语句提速 -+ 支持用 change column 语句修改列名；支持使用 Alter table 的 modify column 和 change column 完成部分列类型转换 - -## 工具 - -+ Loader：兼容 Percona 的 Mydumper 数据格式，提供多线程导入、出错重试、断点续传等功能，并且针对 TiDB 有优化 -+ 开发完成一键部署工具 diff --git a/v3.0/releases/rc2.md b/v3.0/releases/rc2.md deleted file mode 100644 index c7fdb80882be..000000000000 --- a/v3.0/releases/rc2.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: TiDB RC2 Release Notes -category: Releases -aliases: ['/docs-cn/releases/rc2/'] ---- - -# TiDB RC2 Release Notes - -2017 年 3 月 1 日，TiDB 正式发布 RC2 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。对于 OLTP 场景，读取性能提升 60%，写入性能提升 30%。另外提供了权限管理功能，用户可以按照 MySQL 的权限管理方式控制数据访问权限。 - -## TiDB - -+ SQL 查询优化器 - - 统计信息收集和使用 - - 关联子查询优化 - - 优化 CBO 框架 - - 通过 Unique Key 信息消除聚合 - - 重构 Expression - - Distinct 转换为 GroupBy - - 支持 topn 操作下推 -+ 支持基本权限管理 -+ 新增大量 MySQL 内建函数 -+ 完善 Alter Table 语句，支持修改表名、默认值、注释 -+ 支持 Create Table Like 语句 -+ 支持 Show Warnings 语句 -+ 支持 Rename Table 语句 -+ 限制单个事务大小，避免大事务阻塞整个集群 -+ Load Data 过程中对数据进行自动拆分 -+ 优化 AddIndex、Delete 语句性能 -+ 支持 "ANSI_QUOTES" sql_mode -+ 完善监控 -+ 修复 Bug -+ 修复内存泄漏问题 - -## PD - -+ 支持 Label 对副本进行 Location 调度 -+ 基于 region 数量的快速调度 -+ pd-ctl 支持更多功能 - - 添加、删除 PD - - 通过 Key 获取 Region 信息 - - 添加、删除 scheduler 和 operator - - 获取集群 label 信息 - -## TiKV - -+ 支持 Async Apply 提升整体写入性能 -+ 使用 prefix seek 提升 Write CF 的读取性能 -+ 使用 memory hint prefix 提升 Raft CF 插入性能 -+ 优化单行读事务性能 -+ 支持更多下推功能 -+ 加入更多统计 -+ 修复 Bug diff --git a/v3.0/releases/rc3.md b/v3.0/releases/rc3.md deleted file mode 100644 index cd89e6c4ae10..000000000000 --- a/v3.0/releases/rc3.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: TiDB RC3 Release Notes -category: Releases -aliases: ['/docs-cn/releases/rc3/'] ---- - -# TiDB RC3 Release Notes - -2017 年 6 月 16 日，TiDB 正式发布 RC3 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。性能方面重点优化了负载均衡调度策略和流程。功能方面进一步完善权限管理功能，用户可以按照 MySQL 的权限管理方式控制数据访问权限。另外 DDL 的速度也得到显著的提升。 -同时为了简化运维工作，开源了 TiDB Ansible 项目，可以一键部署/升级/启停 TiDB 集群。 - -## TiDB - -+ SQL 查询优化器 - - 统计信息收集和使用 - - 关联子查询优化 - - 优化 CBO 框架 - - 通过 Unique Key 信息消除聚合 - - 重构 Expression - - Distinct 转换为 GroupBy - - 支持 topn 操作下推 -+ 支持基本权限管理 -+ 新增大量 MySQL 内建函数 -+ 完善 Alter Table 语句，支持修改表名、默认值、注释 -+ 支持 Create Table Like 语句 -+ 支持 Show Warnings 语句 -+ 支持 Rename Table 语句 -+ 限制单个事务大小，避免大事务阻塞整个集群 -+ Load Data 过程中对数据进行自动拆分 -+ 优化 AddIndex、Delete 语句性能 -+ 支持 "ANSI_QUOTES" sql_mode -+ 完善监控 -+ 修复 Bug -+ 修复内存泄漏问题 - -## PD - -+ 支持 Label 对副本进行 Location 调度 -+ 基于 region 数量的快速调度 -+ pd-ctl 支持更多功能 - - 添加、删除 PD - - 通过 Key 获取 Region 信息 - - 添加、删除 scheduler 和 operator - - 获取集群 label 信息 - -## TiKV - -+ 支持 Async Apply 提升整体写入性能 -+ 使用 prefix seek 提升 Write CF 的读取性能 -+ 使用 memory hint prefix 提升 Raft CF 插入性能 -+ 优化单行读事务性能 -+ 支持更多下推功能 -+ 加入更多统计 -+ 修复 Bug diff --git a/v3.0/releases/rc4.md b/v3.0/releases/rc4.md deleted file mode 100644 index 5b2e5663bd4d..000000000000 --- a/v3.0/releases/rc4.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB RC4 Release Notes -category: Releases -aliases: ['/docs-cn/releases/rc4/'] ---- - -# TiDB RC4 Release Notes - -2017 年 8 月 4 日，TiDB 正式发布 RC4 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。性能方面重点优化了写入速度，计算任务调度支持优先级，避免分析型大事务影响在线事务。SQL 优化器全新改版，查询代价估算更加准确，且能够自动选择 Join 物理算子。功能方面进一步 MySQL 兼容性。 -同时为了更好的支持 OLAP 业务，开源了 TiSpark 项目，可以通过 Spark 读取和分析 TiKV 中的数据。 - -## TiDB - -+ SQL 查询优化器重构 - - 更好的支持 TopN 查询 - - 支持 Join 算子根据代价自动选择 - - 更完善的 Projection Elimination -+ Schema 版本检查区分 Table，避免 DDL 干扰其他正在执行的事务 -+ 支持 BatchIndexJoin -+ 完善 Explain 语句 -+ 提升 Index Scan 性能 -+ 大量 MySQL 兼容性相关功能 -+ 支持 Json 类型及其操作 -+ 支持查询优先级、隔离级别的设置 - -## PD - -+ 支持通过 PD 设置 TiKV location labels -+ 调度优化 - - 支持 PD 主动向 TiKV 下发调度命令 - - 加快 region heartbeat 响应速度 - - 优化 balance 算法 -+ 优化数据加载，加快 failover 速度 - -## TiKV - -+ 支持查询优先级设置 -+ 支持 RC 隔离级别 -+ 完善 Jepsen，提升稳定性 -+ 支持 Document Store -+ Coprocessor 支持更多下推函数 -+ 提升性能，提升稳定性 - -## TiSpark Beta Release - -+ 支持谓词下推 -+ 支持聚合下推 -+ 支持范围裁剪 -+ 通过 TPC-H 测试 (除去一个需要 View 的 Query) diff --git a/v3.0/releases/rn.md b/v3.0/releases/rn.md deleted file mode 100644 index ff206dbd21eb..000000000000 --- a/v3.0/releases/rn.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: TiDB 版本发布历史 -category: release -aliases: ['/docs-cn/releases/rn/'] ---- - -# TiDB 版本发布历史 - -TiDB 历史版本发布声明如下： - -## 3.0 - -- [3.0.10](/v3.0/releases/3.0.10.md) -- [3.0.9](/v3.0/releases/3.0.9.md) -- [3.0.8](/v3.0/releases/3.0.8.md) -- [3.0.7](/v3.0/releases/3.0.7.md) -- [3.0.6](/v3.0/releases/3.0.6.md) -- [3.0.5](/v3.0/releases/3.0.5.md) -- [3.0.4](/v3.0/releases/3.0.4.md) -- [3.0.3](/v3.0/releases/3.0.3.md) -- [3.0.2](/v3.0/releases/3.0.2.md) -- [3.0.1](/v3.0/releases/3.0.1.md) -- [3.0 GA](/v3.0/releases/3.0-ga.md) -- [3.0.0-rc.3](/v3.0/releases/3.0.0-rc.3.md) -- [3.0.0-rc.2](/v3.0/releases/3.0.0-rc.2.md) -- [3.0.0-rc.1](/v3.0/releases/3.0.0-rc.1.md) -- [3.0.0-beta.1](/v3.0/releases/3.0.0-beta.1.md) -- [3.0.0-beta](/v3.0/releases/3.0beta.md) - -## 2.1 - -- [2.1.19](/v3.0/releases/2.1.19.md) -- [2.1.18](/v3.0/releases/2.1.18.md) -- [2.1.17](/v3.0/releases/2.1.17.md) -- [2.1.16](/v3.0/releases/2.1.16.md) -- [2.1.15](/v3.0/releases/2.1.15.md) -- [2.1.14](/v3.0/releases/2.1.14.md) -- [2.1.13](/v3.0/releases/2.1.13.md) -- [2.1.12](/v3.0/releases/2.1.12.md) -- [2.1.11](/v3.0/releases/2.1.11.md) -- [2.1.10](/v3.0/releases/2.1.10.md) -- [2.1.9](/v3.0/releases/2.1.9.md) -- [2.1.8](/v3.0/releases/2.1.8.md) -- [2.1.7](/v3.0/releases/2.1.7.md) -- [2.1.6](/v3.0/releases/2.1.6.md) -- [2.1.5](/v3.0/releases/2.1.5.md) -- [2.1.4](/v3.0/releases/2.1.4.md) -- [2.1.3](/v3.0/releases/2.1.3.md) -- [2.1.2](/v3.0/releases/2.1.2.md) -- [2.1.1](/v3.0/releases/2.1.1.md) -- [2.1 GA](/v3.0/releases/2.1ga.md) -- [2.1 RC5](/v3.0/releases/21rc5.md) -- [2.1 RC4](/v3.0/releases/21rc4.md) -- [2.1 RC3](/v3.0/releases/21rc3.md) -- [2.1 RC2](/v3.0/releases/21rc2.md) -- [2.1 RC1](/v3.0/releases/21rc1.md) -- [2.1 Beta](/v3.0/releases/21beta.md) - -## 2.0 - -- [2.0.11](/v3.0/releases/2.0.11.md) -- [2.0.10](/v3.0/releases/2.0.10.md) -- [2.0.9](/v3.0/releases/209.md) -- [2.0.8](/v3.0/releases/208.md) -- [2.0.7](/v3.0/releases/207.md) -- [2.0.6](/v3.0/releases/206.md) -- [2.0.5](/v3.0/releases/205.md) -- [2.0.4](/v3.0/releases/204.md) -- [2.0.3](/v3.0/releases/203.md) -- [2.0.2](/v3.0/releases/202.md) -- [2.0.1](/v3.0/releases/201.md) -- [2.0](/v3.0/releases/2.0ga.md) -- [2.0 RC5](/v3.0/releases/2rc5.md) -- [2.0 RC4](/v3.0/releases/2rc4.md) -- [2.0 RC3](/v3.0/releases/2rc3.md) -- [2.0 RC1](/v3.0/releases/2rc1.md) -- [1.1 Beta](/v3.0/releases/11beta.md) -- [1.1 Alpha](/v3.0/releases/11alpha.md) - -## 1.0 - -- [1.0](/v3.0/releases/ga.md) -- [Pre-GA](/v3.0/releases/prega.md) -- [RC4](/v3.0/releases/rc4.md) -- [RC3](/v3.0/releases/rc3.md) -- [RC2](/v3.0/releases/rc2.md) -- [RC1](/v3.0/releases/rc1.md) diff --git a/v3.0/report-issue.md b/v3.0/report-issue.md deleted file mode 100644 index b7e4dca053e4..000000000000 --- a/v3.0/report-issue.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: 提交 Issue -category: report issue -aliases: ['/docs-cn/report-issue/'] ---- - -# 提交 Issue - -我们正在努力使 TiDB 与 MySQL 5.7 兼容。如果您发现了任何未记录在文档中的表现差异、bug 或奇怪的性能特征，请[在 GitHub 中提交新的 Issue](https://github.com/pingcap/tidb/issues)。 - -在 GitHub 上提交的新 Issue 分为以下几种： - -- 错误报告 (Bug Reports) -- 功能请求 (Feature Requests) -- 常规问题 (General Questions) -- 性能问题 (Performance Questions) - -请确保您完全按照 Issue 模板进行填写，以便我们迅速定位问题并作出回应。 diff --git a/v3.0/roadmap.md b/v3.0/roadmap.md deleted file mode 100644 index 095c7f81d8b9..000000000000 --- a/v3.0/roadmap.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: TiDB 路线图 -category: Roadmap ---- - -# TiDB 路线图 - -## TiDB - -- [ ] 优化器 - - [ ] 统计信息优化 - - [ ] Multi-Column Statistics - - [ ] Cascades Planner - - [ ] Plan Management - - [ ] SQL Tuning Advisor - - [ ] Robust Access Path Selection：增加启发式规则，提升 OLTP 场景中索引选择正确率 - - [ ] Adaptive Query Optimization -- [ ] 执行引擎 - - [ ] 算子并行化 - - [ ] 内存控制 - - [ ] 并发控制 - - [ ] Shuffle 算子 - - [ ] Vectorized 表达式计算 - - [ ] UDF -- [ ] SQL 功能 - - [ ] 支持 View - - [ ] 支持窗口函数 - - [ ] 支持 Common Table Expression - - [ ] 支持 Hash 分区表 - - [ ] 支持 utf8_general_ci collation -- [ ] DDL 改进 - - [ ] 支持 Table Lock - - [ ] 支持 Change column type - - [ ] 支持单条语句中多个 DDL 操作 - - [ ] 支持不可见索引（invisible index） -- [ ] 支持插件系统 - - [ ] 支持白名单插件 - - [ ] 支持审计日志插件 - - [ ] 支持 RBAC 插件 - - [ ] 支持诊断插件 -- [ ] 支持 Query Tracing -- [ ] 支持行列混合存储引擎 -- [ ] 支持 New Storage Row Format，提升性能并减小内存占用 -- [ ] RowID 实现非整数类型 -- [ ] 事务 - - [ ] 减少读写冲突 - - [ ] 优化事务调度机制 - - [ ] 改善模型，降低延迟 - - [ ] 支持最小事务 (like the mini-transaction of InnoDB) - -## TiKV - -+ Raft - - [x] Region Merge - 合并小的 Region 以减少开销 - - [x] Local Read Thread - 把读请求放在一个单独的线程处理 - - [x] 批量 Region Split - 加速大的 Region 的分裂 - - [x] Raft Learner - 支持 Raft learner 使得成员变更过程更加平滑 - - [x] Raft Pre-voter - 支持 Raft Pre-vote 避免网络隔离带来不必要的选举 - - [ ] Joint Consensus - 安全地进行多个成员变更 - - [ ] 多线程 Raftstore - 在多个线程处理不同 Region 的 Raft 逻辑 - - [ ] 多线程 Apply Pool - 在多个线程执行不同 Region 已经提交了的命令 -+ Engine - - [ ] Titan - 把大的 key-values 从 LSM-Tree 中分离出来 - - [ ] 可拔插的 Engine 接口 - 简化接口逻辑并且提供可扩展性 -+ Storage - - [ ] 在 scheduler 里做流控提前避免 write stall -+ Transaction - - [x] 优化事务冲突 - - [ ] 分布式 GC - 把 MVCC 垃圾回收的逻辑分布到 TiKV 控制 -+ Coprocessor - - [x] Streaming - 把大的数据集切成小块返回以减少内存消耗 - - [ ] Chunk Execution - 按 chunk 的方式来处理数据以提高性能 - - [ ] 请求跟踪 - 提供单个请求执行的详细信息 -+ Tools - - [x] TiKV Importer - 通过直接导入 SST 文件的方式加速数据导入 -+ Client - - [ ] 提供 Rust 版本的 TiKV client - - [ ] gRPC 消息批量化 - 减少消息交互的开销 - -## PD - -- [x] Namespace 完善 - - [x] 不同 Namespace 或者 Table 配置不同的副本策略 -- [x] Table Region 分散调度 -- [x] 调度支持优先级，更加可控 -- [ ] 使用机器学习优化调度 -- [ ] 优化 Region 元信息存储 - 把元信息存储在一个独立的存储引擎里 - -## TiSpark - -- [ ] Limit/Order 下推 -- [x] DAG 接口接入（废除 Select 接口） -- [ ] Index Join 和并行 merge join -- [ ] Data Federation（桥接其他数据源，最好能和社区同步，这个接进来可以比较好扩展 Usecase，如果再做一个 InputFormat 适配就可以接 Hive 和 Presto 这些 Hadoop 上的数仓） - -## Tools - -- [x] 集群部署工具 -- [X] 高性能数据导入工具（lightning） -- [X] 集群备份和恢复工具（包括全量+增量备份，Mydumper + drainer/reparo） -- [X] 改进 TiDB Binlog 架构 -- [ ] 数据在线迁移工具（Syncer 升级版） -- [ ] 集群诊断和分析工具 diff --git a/v3.0/support-resources.md b/v3.0/support-resources.md deleted file mode 100644 index 5472af54fc79..000000000000 --- a/v3.0/support-resources.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 支持资源 -category: resources -aliases: ['/docs-cn/support/','/docs-cn/support-resources/'] ---- - -# 支持资源 - -您可以通过以下任何一种方式找到我们的社区成员： - -+ Slack Channel: [https://pingcap.com/tidbslack](https://pingcap.com/tidbslack) -+ Stack Overflow: [https://stackoverflow.com/questions/tagged/tidb](https://stackoverflow.com/questions/tagged/tidb) -+ Reddit: [https://www.reddit.com/r/TiDB](https://www.reddit.com/r/TiDB) -+ GitHub: [https://github.com/pingcap/tidb/issues](https://github.com/pingcap/tidb/issues) - -有关企业支持合作的信息，请[联系我们](mailto:info@pingcap.com)。 diff --git a/v3.0/tidb-in-kubernetes/deploy/access-tidb.md b/v3.0/tidb-in-kubernetes/deploy/access-tidb.md deleted file mode 100644 index c6506c6329bf..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/access-tidb.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 访问 Kubernetes 上的 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/orchestrated/tidb-in-kubernetes/access-tidb/','/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/access-tidb/'] ---- - -# 访问 Kubernetes 上的 TiDB 集群 - -在 Kubernetes 集群内访问 TiDB 时，使用 TiDB service 域名 `-tidb.` 即可。若需要在集群外访问，则需将 TiDB 服务端口暴露出去。在 `tidb-cluster` Helm chart 中，通过 `values.yaml` 文件中的 `tidb.service` 字段进行配置： - -{{< copyable "" >}} - -```yaml -tidb: - service: - type: NodePort - # externalTrafficPolicy: Cluster - # annotations: - # cloud.google.com/load-balancer-type: Internal -``` - -## NodePort - -在没有 LoadBalancer 时，可选择通过 NodePort 暴露。NodePort 有两种模式： - -- `externalTrafficPolicy=Cluster`：集群所有的机器都会给 TiDB 分配 TCP 端口，此为默认值 - - 使用 `Cluster` 模式时，可以通过任意一台机器的 IP 加同一个端口访问 TiDB 服务，如果该机器上没有 TiDB Pod，则相应请求会转发到有 TiDB Pod 的机器上。 - - > **注意：** - > - > 该模式下 TiDB 服务获取到的请求源 IP 是主机 IP，并不是真正的客户端源 IP，所以基于客户端源 IP 的访问权限控制在该模式下不可用。 - -- `externalTrafficPolicy=Local`：只有运行 TiDB 的机器会分配 TCP 端口，用于访问本地的 TiDB 实例 - - 使用 `Local` 模式时，建议打开 tidb-scheduler 的 `StableScheduling` 特性。tidb-scheduler 会尽可能在升级过程中将新 TiDB 实例调度到原机器，这样集群外的客户端便不需要在 TiDB 重启后更新配置。 - -### 查看 NodePort 模式下对外暴露的 IP/PORT - -查看 Service 分配的 Node Port，可通过获取 TiDB 的 Service 对象来获知： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n get svc -tidb -ojsonpath="{.spec.ports[?(@.name=='mysql-client')].nodePort}{'\n'}" -``` - -查看可通过哪些节点的 IP 访问 TiDB 服务，有两种情况： - -- `externalTrafficPolicy` 为 `Cluster` 时，所有节点 IP 均可 -- `externalTrafficPolicy` 为 `Local` 时，可通过以下命令获取指定集群的 TiDB 实例所在的节点 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl -n get pods -l "app.kubernetes.io/component=tidb,app.kubernetes.io/instance=" -ojsonpath="{range .items[*]}{.spec.nodeName}{'\n'}{end}" - ``` - -## LoadBalancer - -若运行在有 LoadBalancer 的环境，比如 GCP/AWS 平台，建议使用云平台的 LoadBalancer 特性。 - -访问 [Kubernetes Service 文档](https://kubernetes.io/docs/concepts/services-networking/service/)，了解更多 Service 特性以及云平台 Load Balancer 支持。 diff --git a/v3.0/tidb-in-kubernetes/deploy/alibaba-cloud.md b/v3.0/tidb-in-kubernetes/deploy/alibaba-cloud.md deleted file mode 100644 index 001c2e33ae17..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/alibaba-cloud.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: 在阿里云上部署 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/alibaba-cloud/'] ---- - -# 在阿里云上部署 TiDB 集群 - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在阿里云上部署 TiDB 集群。 - -## 环境需求 - -- [aliyun-cli](https://github.com/aliyun/aliyun-cli) >= 3.0.15 并且[配置 aliyun-cli](https://www.alibabacloud.com/help/doc-detail/90766.htm?spm=a2c63.l28256.a3.4.7b52a893EFVglq) - - > **注意：** - > - > Access Key 需要具有操作相应资源的权限。 - -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.12 -- [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.1 且 <= 2.11.0 -- [jq](https://stedolan.github.io/jq/download/) >= 1.6 -- [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) 0.12.* - -你可以使用阿里云的[云命令行](https://shell.aliyun.com)服务来进行操作，云命令行中已经预装并配置好了所有工具。 - -### 权限 - -完整部署集群需要具备以下权限： - -- AliyunECSFullAccess -- AliyunESSFullAccess -- AliyunVPCFullAccess -- AliyunSLBFullAccess -- AliyunCSFullAccess -- AliyunEIPFullAccess -- AliyunECIFullAccess -- AliyunVPNGatewayFullAccess -- AliyunNATGatewayFullAccess - -## 概览 - -默认配置下，会创建： - -- 一个新的 VPC -- 一台 ECS 实例作为堡垒机 -- 一个托管版 ACK（阿里云 Kubernetes）集群以及一系列 worker 节点： - - 属于一个伸缩组的 2 台 ECS 实例（2 核 2 GB）托管版 Kubernetes 的默认伸缩组中必须至少有两台实例，用于承载整个的系统服务，例如 CoreDNS - - 属于一个伸缩组的 3 台 `ecs.g5.large` 实例，用于部署 PD - - 属于一个伸缩组的 3 台 `ecs.i2.2xlarge` 实例，用于部署 TiKV - - 属于一个伸缩组的 2 台 `ecs.c5.4xlarge` 实例用于部署 TiDB - - 属于一个伸缩组的 1 台 `ecs.c5.xlarge` 实例用于部署监控组件 - - 一块 100 GB 的云盘用作监控数据存储 - -除了默认伸缩组之外的其它所有实例都是跨可用区部署的。而伸缩组 (Auto-scaling Group) 能够保证集群的健康实例数等于期望数值。因此，当发生节点故障甚至可用区故障时，伸缩组能够自动为我们创建新实例来确保服务可用性。 - -## 安装部署 - -1. 设置目标 Region 和阿里云密钥（也可以在运行 `terraform` 命令时根据命令提示输入）： - - {{< copyable "shell-regular" >}} - - ```shell - export TF_VAR_ALICLOUD_REGION= && \ - export TF_VAR_ALICLOUD_ACCESS_KEY= && \ - export TF_VAR_ALICLOUD_SECRET_KEY= - ``` - - 用于部署集群的各变量的默认值存储在 `variables.tf` 文件中，如需定制可以修改此文件或在安装时通过 `-var` 参数覆盖。 - -2. 使用 Terraform 进行安装： - - {{< copyable "shell-regular" >}} - - ```shell - git clone --depth=1 https://github.com/pingcap/tidb-operator && \ - cd tidb-operator/deploy/aliyun - ``` - - {{< copyable "shell-regular" >}} - - ```shell - terraform init - ``` - - `apply` 过程中需要输入 `yes` 来确认执行： - - {{< copyable "shell-regular" >}} - - ```shell - terraform apply - ``` - - 假如在运行 `terraform apply` 时出现报错，可根据报错信息（例如缺少权限）进行修复后再次运行 `terraform apply`。 - - 整个安装过程大约需要 5 至 10 分钟，安装完成后会输出集群的关键信息（想要重新查看这些信息，可以运行 `terraform output`）： - - ``` - Apply complete! Resources: 3 added, 0 changed, 1 destroyed. - - Outputs: - - bastion_ip = 47.96.174.214 - cluster_id = c2d9b20854a194f158ef2bc8ea946f20e - kubeconfig_file = /tidb-operator/deploy/aliyun/credentials/kubeconfig - monitor_endpoint = 121.199.195.236:3000 - region = cn-hangzhou - ssh_key_file = /tidb-operator/deploy/aliyun/credentials/my-cluster-keyZ.pem - tidb_endpoint = 172.21.5.171:4000 - tidb_version = v3.0.0 - vpc_id = vpc-bp1v8i5rwsc7yh8dwyep5 - ``` - -3. 用 `kubectl` 或 `helm` 对集群进行操作： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG=$PWD/credentials/kubeconfig - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl version - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm ls - ``` - -## 连接数据库 - -通过堡垒机可连接 TiDB 集群进行测试，相关信息在安装完成后的输出中均可找到： - -{{< copyable "shell-regular" >}} - -```shell -ssh -i credentials/-key.pem root@ -``` - -{{< copyable "shell-regular" >}} - -```shell -mysql -h -P 4000 -u root -``` - -## 监控 - -访问 `` 就可以查看相关的 Grafana 监控面板。相关信息可在安装完成后的输出中找到。默认帐号密码为： - -- 用户名：admin -- 密码：admin - -> **警告：** -> -> 出于安全考虑，假如你已经或将要配置 VPN 用于访问 VPC，强烈建议将 `deploy/modules/aliyun/tidb-cluster/values/default.yaml` 文件里 `monitor.grafana.service.annotations` 中的 `service.beta.kubernetes.io/alicloud-loadbalancer-address-type` 设置为 `intranet` 以禁止监控服务的公网访问。 - -## 升级 TiDB 集群 - -设置 `variables.tf` 中的 `tidb_version` 参数，并再次运行 `terraform apply` 即可完成升级。 - -升级操作可能会执行较长时间，可以通过以下命令来持续观察进度： - -{{< copyable "shell-regular" >}} - -``` -kubectl get pods --namespace -o wide --watch -``` - -## TiDB 集群水平伸缩 - -按需修改 `variables.tf` 中的 `tikv_count` 和 `tidb_count` 数值，再次运行 `terraform apply` 即可完成 TiDB 集群的水平伸缩。 - -## 销毁集群 - -{{< copyable "shell-regular" >}} - -```shell -terraform destroy -``` - -假如 Kubernetes 集群没有创建成功，那么在 destroy 时会出现报错，无法进行正常清理。此时需要手动将 Kubernetes 资源从本地状态中移除： - -{{< copyable "shell-regular" >}} - -```shell -terraform state list -``` - -{{< copyable "shell-regular" >}} - -```shell -terraform state rm module.ack.alicloud_cs_managed_kubernetes.k8s -``` - -销毁集群操作需要执行较长时间。 - -> **注意：** -> -> 监控组件挂载的云盘需要在阿里云管理控制台中手动删除。 - -## 配置 - -### 配置 TiDB Operator - -通过调整 `variables.tf` 内的值来配置 TiDB Operator，大多数配置项均能按照 `variable` 的注释理解语义后进行修改。需要注意的是，`operator_helm_values` 配置项允许为 TiDB Operator 提供一个自定义的 `values.yaml` 配置文件，示例如下： - -- 在 `terraform.tfvars` 中设置 `operator_helm_values`： - - ```hcl - operator_helm_values = "./my-operator-values.yaml" - ``` - -- 在 `main.tf` 中设置 `operator_helm_values`： - - ```hcl - operator_helm_values = file("./my-operator-values.yaml") - ``` - -同时，在默认配置下 Terraform 脚本会创建一个新的 VPC，假如要使用现有的 VPC，可以在 `variable.tf` 中设置 `vpc_id`。注意，当使用现有 VPC 时，没有设置 vswitch 的可用区将不会部署 Kubernetes 节点。 - -### 配置 TiDB 集群 - -TiDB 集群会使用 `./my-cluster.yaml` 作为集群的 `values.yaml` 配置文件，修改该文件即可配置 TiDB 集群。支持的配置项可参考 [Kubernetes 上的 TiDB 集群配置](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 - -## 管理多个 TiDB 集群 - -需要在一个 Kubernetes 集群下管理多个 TiDB 集群时，需要编辑 `./main.tf`，按实际需要新增 `tidb-cluster` 声明，示例如下： - -```hcl -module "tidb-cluster-dev" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "dev-cluster" - ack = module.tidb-operator - - pd_count = 1 - tikv_count = 1 - tidb_count = 1 - override_values = file("dev-cluster.yaml") -} - -module "tidb-cluster-staging" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "staging-cluster" - ack = module.tidb-operator - - pd_count = 3 - tikv_count = 3 - tidb_count = 2 - override_values = file("staging-cluster.yaml") -} -``` - -注意，多个 TiDB 集群之间 `cluster_name` 必须保持唯一。下面是 `tidb-cluster` 模块的所有可配置参数： - -| 参数名 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `ack` | 封装目标 Kubernetes 集群信息的结构体，必填 | `nil` | -| `cluster_name` | TiDB 集群名，必填且必须唯一 | `nil` | -| `tidb_version` | TiDB 集群版本 | `v3.0.1` | -| `tidb_cluster_chart_version` | `tidb-cluster` helm chart 的版本 | `v1.0.1` | -| `pd_count` | PD 节点数 | 3 | -| `pd_instance_type` | PD 实例类型 | `ecs.g5.large` | -| `tikv_count` | TiKV 节点数 | 3 | -| `tikv_instance_type` | TiKV 实例类型 | `ecs.i2.2xlarge` | -| `tidb_count` | TiDB 节点数 | 2 | -| `tidb_instance_type` | TiDB 实例类型 | `ecs.c5.4xlarge` | -| `monitor_instance_type` | 监控组件的实例类型 | `ecs.c5.xlarge` | -| `override_values` | TiDB 集群的 `values.yaml` 配置文件，通常通过 `file()` 函数从文件中读取 | `nil` | -| `local_exec_interpreter` | 执行命令行指令的解释器 | `["/bin/sh", "-c"]` | - -## 管理多个 Kubernetes 集群 - -推荐针对每个 Kubernetes 集群都使用单独的 Terraform 模块进行管理（一个 Terraform Module 即一个包含 `.tf` 脚本的目录）。 - -`deploy/aliyun` 实际上是将 `deploy/modules` 中的数个可复用的 Terraform 脚本组合在了一起。当管理多个集群时（下面的操作在 `tidb-operator` 项目根目录下进行）： - -1. 首先针对每个集群创建一个目录，如： - - {{< copyable "shell-regular" >}} - - ```shell - mkdir -p deploy/aliyun-staging - ``` - -2. 参考 `deploy/aliyun` 的 `main.tf`，编写自己的脚本，下面是一个简单的例子： - - ```hcl - provider "alicloud" { - region = - access_key = - secret_key = - } - - module "tidb-operator" { - source = "../modules/aliyun/tidb-operator" - - region = - access_key = - secret_key = - cluster_name = "example-cluster" - key_file = "ssh-key.pem" - kubeconfig_file = "kubeconfig" - } - - provider "helm" { - alias = "default" - insecure = true - install_tiller = false - kubernetes { - config_path = module.tidb-operator.kubeconfig_filename - } - } - - module "tidb-cluster" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "example-cluster" - ack = module.tidb-operator - } - - module "bastion" { - source = "../modules/aliyun/bastion" - - bastion_name = "example-bastion" - key_name = module.tidb-operator.key_name - vpc_id = module.tidb-operator.vpc_id - vswitch_id = module.tidb-operator.vswitch_ids[0] - enable_ssh_to_worker = true - worker_security_group_id = module.tidb-operator.security_group_id - } - ``` - -上面的脚本可以自由定制，比如，假如不需要堡垒机则可以移除 `module "bastion"` 相关声明。 - -你也可以直接拷贝 `deploy/aliyun` 目录，但要注意不能拷贝已经运行了 `terraform apply` 的目录，建议重新 clone 仓库再进行拷贝。 - -## 使用限制 - -目前，`pod cidr`，`service cidr` 和节点型号等配置在集群创建后均无法修改。 diff --git a/v3.0/tidb-in-kubernetes/deploy/aws-eks.md b/v3.0/tidb-in-kubernetes/deploy/aws-eks.md deleted file mode 100644 index 105ee5850a56..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/aws-eks.md +++ /dev/null @@ -1,532 +0,0 @@ ---- -title: 在 AWS EKS 上部署 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/aws-eks/','/docs-cn/v3.0/how-to/deploy/orchestrated/aws-eks/'] ---- - -# 在 AWS EKS 上部署 TiDB 集群 - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在 AWS EKS (Elastic Kubernetes Service) 上部署 TiDB 集群。 - -## 环境配置准备 - -部署前，请确认已安装以下软件并完成配置： - -* [awscli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) >= 1.16.73，控制 AWS 资源 - - 要与 AWS 交互，必须[配置 `awscli`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。最快的方式是使用 `aws configure` 命令: - - {{< copyable "shell-regular" >}} - - ``` shell - aws configure - ``` - - 替换下面的 AWS Access Key ID 和 AWS Secret Access Key： - - ``` - AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE - AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - Default region name [None]: us-west-2 - Default output format [None]: json - ``` - - > **注意：** - > - > Access key 必须至少具有以下权限：创建 VPC、创建 EBS、创建 EC2 和创建 Role。 - -* [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) >= 0.12 -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.11 -* [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.0 且 < 3.0.0 -* [jq](https://stedolan.github.io/jq/download/) -* [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html)，AWS 权限鉴定工具，确保安装在 `PATH` 路径下。 - - 最简单的安装方法是下载编译好的二进制文件 `aws-iam-authenticator`，如下所示。 - - Linux 用户下载二进制文件： - - {{< copyable "shell-regular" >}} - - ``` shell - curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/linux/amd64/aws-iam-authenticator - ``` - - macOS 用户下载二进制文件： - - {{< copyable "shell-regular" >}} - - ``` shell - curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/darwin/amd64/aws-iam-authenticator - ``` - - 二进制文件下载完成后，执行以下操作： - - {{< copyable "shell-regular" >}} - - ``` shell - chmod +x ./aws-iam-authenticator && \ - sudo mv ./aws-iam-authenticator /usr/local/bin/aws-iam-authenticator - ``` - -## 部署集群 - -默认部署会创建一个新的 VPC、一个 t2.micro 实例作为堡垒机，并包含以下 ec2 实例作为工作节点的 EKS 集群： - -* 3 台 m5.xlarge 实例，部署 PD -* 3 台 c5d.4xlarge 实例，部署 TiKV -* 2 台 c5.4xlarge 实例，部署 TiDB -* 1 台 c5.2xlarge 实例，部署监控组件 - -使用如下命令部署集群。 - -从 Github 克隆代码并进入指定路径： - -{{< copyable "shell-regular" >}} - -``` shell -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator/deploy/aws -``` - -使用 `terraform` 命令初始化并部署集群： - -{{< copyable "shell-regular" >}} - -``` shell -terraform init -``` - -{{< copyable "shell-regular" >}} - -``` shell -terraform apply -``` - -> **注意：** -> -> `terraform apply` 过程中必须输入 "yes" 才能继续。 - -整个过程可能至少需要 10 分钟。`terraform apply` 执行成功后，控制台会输出类似如下的信息： - -``` -Apply complete! Resources: 67 added，0 changed，0 destroyed. - -Outputs: - -bastion_ip = [ - "34.219.204.217", -] -default-cluster_monitor-dns = a82db513ba84511e9af170283460e413-1838961480.us-west-2.elb.amazonaws.com -default-cluster_tidb-dns = a82df6d13a84511e9af170283460e413-d3ce3b9335901d8c.elb.us-west-2.amazonaws.com -eks_endpoint = https://9A9A5ABB8303DDD35C0C2835A1801723.yl4.us-west-2.eks.amazonaws.com -eks_version = 1.12 -kubeconfig_filename = credentials/kubeconfig_my-cluster -region = us-west-21 -``` - -你可以通过 `terraform output` 命令再次获取上面的输出信息。 - -> **注意：** -> -> 1.14 版本以前的 EKS 不支持自动开启 NLB 跨可用区负载均衡，因此默认配置下 会出现各台 TiDB 实例压力不均衡额状况。生产环境下，强烈建议参考 [AWS 官方文档](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-disable-crosszone-lb.html#enable-cross-zone)手动开启 NLB 的跨可用区负载均衡。 - -## 访问数据库 - -`terraform apply` 完成后，可先通过 `ssh` 远程连接到堡垒机，再通过 MySQL client 来访问 TiDB 集群。 - -所需命令如下（用上面的输出信息替换 `<>` 部分内容)： - -{{< copyable "shell-regular" >}} - -```shell -ssh -i credentials/.pem centos@ -``` - -{{< copyable "shell-regular" >}} - -```shell -mysql -h -P 4000 -u root -``` - -`eks_name` 默认为 `my-cluster`。如果 DNS 名字无法解析，请耐心等待几分钟。 - -你还可以通过 `kubectl` 和 `helm` 命令使用 kubeconfig 文件 `credentials/kubeconfig_` 和 EKS 集群交互，主要有两种方式，如下所示。 - -- 指定 --kubeconfig 参数： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl --kubeconfig credentials/kubeconfig_ get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm --kubeconfig credentials/kubeconfig_ ls - ``` - -- 或者，设置 KUBECONFIG 环境变量： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG=$PWD/credentials/kubeconfig_ - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm ls - ``` - -## Grafana 监控 - -你可以通过浏览器访问 `:3000` 地址查看 Grafana 监控指标。 - -Grafana 默认登录信息： - -- 用户名：admin -- 密码：admin - -## 升级 TiDB 集群 - -要升级 TiDB 集群，可编辑 `variables.tf` 文件，修改 `default_cluster_version` 变量到更高版本，然后运行 `terraform apply`。 - -例如，要升级 TiDB 集群到 3.0.1，则修改 `default_cluster_version` 为 `v3.0.1`： - -```hcl -variable "default_cluster_version" { - default = "v3.0.1" -} -``` - -> **注意：** -> -> 升级过程会持续一段时间，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察升级进度。 - -## 扩容 TiDB 集群 - -若要扩容 TiDB 集群，可按需修改 `variables.tf` 文件中的 `default_cluster_tikv_count` 或者 `default_cluster_tidb_count` 变量，然后运行 `terraform apply`。 - -例如，可以将 `default_cluster_tidb_count` 从 2 改为 4 以扩容 TiDB： - -```hcl - variable "default_cluster_tidb_count" { - default = 4 - } -``` - -> **注意：** -> -> - 由于缩容过程中无法确定会缩掉哪个节点，目前还不支持 TiDB 集群的缩容。 -> - 扩容过程会持续几分钟，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察进度。 - -## 自定义 - -你可以按需修改 `variables.tf` 文件中的默认值，例如集群名称和镜像版本等。 - -### 自定义 AWS 相关的资源 - -默认情况下 terraform 脚本会新建 VPC。你也可以通过设置 `create_vpc` 为 `false`，并指定 `vpc_id`、`private_subnet_ids` 和 `public_subnet_ids` 变量为已有的 VPC id、subnet ids 来使用现有的网络。 - -> **注意：** -> -> - 由于 AWS 和 Terraform 的限制，还不支持复用已有 EKS 集群的 VPC 和 subnets，所以请确保只在你手动创建 VPC 的情况下修改该参数； -> - EKS Node 上的 CNI 插件会为每个节点预留一部分 IP 资源，因此 IP 消耗较大，在手动创建 VPC 时，建议将每个 subnet 的掩码长度设置在 18~20 以确保 IP 资源充足，或参考 [EKS CNI 插件文档](https://github.com/aws/amazon-vpc-cni-k8s#cni-configuration-variables)将节点预留的 IP 资源数调低。 - -由于 TiDB 服务通过 [Internal Elastic Load Balancer](https://aws.amazon.com/blogs/aws/internal-elastic-load-balancers/) 暴露，默认情况下，会创建一个 Amazon EC2 实例作为堡垒机，访问创建的 TiDB 集群。堡垒机上预装了 MySQL 和 Sysbench，所以你可以通过 SSH 方式登陆到堡垒机后通过 ELB 访问 TiDB。如果你的 VPC 中已经有了类似的 EC2 实例，你可以通过设置 `create_bastion` 为 `false` 禁掉堡垒机的创建。 - -TiDB 版本和组件数量也可以在 `variables.tf` 中修改，你可以按照自己的需求配置。 - -目前，由于 PD 和 TiKV 依赖 [NVMe SSD 实例存储卷](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html)，TiDB 集群组件的实例类型不能修改。 - -### 自定义 TiDB 参数配置 - -Terraform 脚本中为运行在 EKS 上的 TiDB 集群提供了合理的默认配置。有自定义需求时，你可以在 `clusters.tf` 中通过 `override_values` 参数为每个 TiDB 集群指定一个 `values.yaml` 文件来自定义集群参数配置。 - -作为例子，默认集群使用了 `./default-cluster.yaml` 作为 `values.yaml` 配置文件，并在配置中打开了"配置文件滚动更新"特性。 - -值得注意的是，在 EKS 上部分配置项无法在 `values.yaml` 中进行修改，包括集群版本、副本数、`NodeSelector` 以及 `Tolerations`。`NodeSelector` 和 `Tolerations` 由 Terraform 直接管理以确保基础设施与 TiDB 集群之间的一致性。集群版本和副本数可以通过 `cluster.tf` 文件中的 `tidb-cluster` module 参数来修改。 - -> **注意：** -> -> 自定义 `values.yaml` 配置文件中，不建议包含如下配置（`tidb-cluster` module 默认固定配置）： - -``` -pd: - storageClassName: ebs-gp2 -tikv: - stroageClassName: local-storage -tidb: - service: - type: LoadBalancer - annotations: - service.beta.kubernetes.io/aws-load-balancer-internal: '0.0.0.0/0' - service.beta.kubernetes.io/aws-load-balancer-type: nlb - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: >'true' - separateSlowLog: true -monitor: - storage: 100Gi - storageClassName: ebs-gp2 - persistent: true - grafana: - config: - GF_AUTH_ANONYMOUS_ENABLED: "true" - service: - type: LoadBalancer -``` - -### 自定义 TiDB Operator - -你可以通过 `variables.tf` 中的 `operator_values` 参数传入自定义的 `values.yaml` 内容来配置 TiDB Operator。示例如下： - -```hcl -variable "operator_values" { - description = "The helm values file for TiDB Operator, path is relative to current working dir" - default = "./operator_values.yaml" -} -``` - -## 管理多个 TiDB 集群 - -一个 `tidb-cluster` 模块的实例对应一个 TiDB 集群，你可以通过编辑 `clusters.tf` 添加新的 `tidb-cluster` 模块实例来新增 TiDB 集群，示例如下： - -```hcl -module example-cluster { - source = "../modules/aws/tidb-cluster" - - # The target EKS, required - eks = local.eks - # The subnets of node pools of this TiDB cluster, required - subnets = local.subnets - # TiDB cluster name, required - cluster_name = "example-cluster" - - # Helm values file - override_values = file("example-cluster.yaml") - # TiDB cluster version - cluster_version = "v3.0.0" - # SSH key of cluster nodes - ssh_key_name = module.key-pair.key_name - # PD replica number - pd_count = 3 - # TiKV instance type - pd_instance_type = "t2.xlarge" - # TiKV replica number - tikv_count = 3 - # TiKV instance type - tikv_instance_type = "t2.xlarge" - # The storage class used by TiKV, if the TiKV instance type do not have local SSD, you should change it to storage class - # TiDB replica number - tidb_count = 2 - # TiDB instance type - tidb_instance_type = "t2.xlarge" - # Monitor instance type - monitor_instance_type = "t2.xlarge" - # The version of tidb-cluster helm chart - tidb_cluster_chart_version = "v1.0.0" - # Decides whether or not to create the tidb-cluster helm release. - # If this variable set to false, you have to - # install the helm release manually - create_tidb_cluster_release = true -} -``` - -> **注意：** -> -> `cluster_name` 必须是唯一的。 - -你可以通过 `kubectl` 获取新集群的监控系统地址与 TiDB 地址。假如你希望让 Terraform 脚本输出这些地址，可以通过在 `outputs.tf` 中增加相关的输出项实现： - -```hcl -output "example-cluster_tidb-hostname" { - value = module.example-cluster.tidb_hostname -} - -output "example-cluster_monitor-hostname" { - value = module.example-cluster.monitor_hostname -} -``` - -修改完成后，执行 `terraform init` 和 `terraform apply` 创建集群。 - -最后，只要移除 `tidb-cluster` 模块调用，对应的 TiDB 集群就会被销毁，EC2 资源也会随之释放。 - -## 仅管理基础设施 - -通过调整配置，你可以控制 Terraform 脚本只创建 Kubernetes 集群和 TiDB Operator。操作步骤如下： - -* 修改 `clusters.tf` 中 TiDB 集群的 `create_tidb_cluster_release` 配置项： - - ```hcl - module "default-cluster" { - ... - create_tidb_cluster_release = false - } - ``` - - 如上所示，当 `create_tidb_cluster_release` 设置为 `false` 时，Terraform 脚本不会创建和修改 TiDB 集群，但仍会创建 TiDB 集群所需的计算和存储资源。此时，你可以使用 Helm 等工具来独立管理集群。 - -> **注意：** -> -> 在已经部署的集群上将 `create_tidb_cluster_release` 调整为 `false` 会导致已安装的 TiDB 集群被删除，对应的 TiDB 集群对象也会随之被删除。 - -## 销毁集群 - -可以通过如下命令销毁集群： - -{{< copyable "shell-regular" >}} - -```shell -terraform destroy -``` - -> **注意：** -> -> * 该操作会销毁 EKS 集群以及部署在该 EKS 集群上的所有 TiDB 集群。 -> * 如果你不再需要存储卷中的数据，在执行 `terraform destroy` 后，你需要在 AWS 控制台手动删除 EBS 卷。 - -## 管理多个 Kubernetes 集群 - -本节详细介绍了如何管理多个 Kubernetes 集群（EKS），并在每个集群上部署一个或更多 TiDB 集群。 - -上述文档中介绍的 Terraform 脚本组合了多个 Terraform 模块： - -- `tidb-operator` 模块，用于创建 EKS 集群并在 EKS 集群上安装配置 [TiDB Operator](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md)。 -- `tidb-cluster` 模块，用于创建 TiDB 集群所需的资源池并部署 TiDB 集群。 -- EKS 上的 TiDB 集群专用的 `vpc` 模块、`key-pair`模块和`bastion` 模块 - -管理多个 Kubernetes 集群的最佳实践是为每个 Kubernetes 集群创建一个单独的目录，并在新目录中自行组合上述 Terraform 模块。这种方式能够保证多个集群间的 Terraform 状态不会互相影响，也便于自由定制和扩展。下面是一个例子： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p deploy/aws-staging -vim deploy/aws-staging/main.tf -``` - -`deploy/aws-staging/main.tf` 的内容可以是： - -```hcl -provider "aws" { - region = "us-west-1" -} - -# 创建一个 ssh key，用于登录堡垒机和 Kubernetes 节点 -module "key-pair" { - source = "../modules/aws/key-pair" - - name = "another-eks-cluster" - path = "${path.cwd}/credentials/" -} - -# 创建一个新的 VPC -module "vpc" { - source = "../modules/aws/vpc" - - vpc_name = "another-eks-cluster" -} - -# 在上面的 VPC 中创建一个 EKS 并部署 tidb-operator -module "tidb-operator" { - source = "../modules/aws/tidb-operator" - - eks_name = "another-eks-cluster" - config_output_path = "credentials/" - subnets = module.vpc.private_subnets - vpc_id = module.vpc.vpc_id - ssh_key_name = module.key-pair.key_name -} - -# 特殊处理，确保 helm 操作在 EKS 创建完毕后进行 -resource "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.eks] - sensitive_content = module.tidb-operator.eks.kubeconfig - filename = module.tidb-operator.eks.kubeconfig_filename -} -provider "helm" { - alias = "eks" - insecure = true - install_tiller = false - kubernetes { - config_path = local_file.kubeconfig.filename - } -} - -# 在上面的 EKS 集群上创建一个 TiDB 集群 -module "tidb-cluster-a" { - source = "../modules/aws/tidb-cluster" - providers = { - helm = "helm.eks" - } - - cluster_name = "tidb-cluster-a" - eks = module.tidb-operator.eks - ssh_key_name = module.key-pair.key_name - subnets = module.vpc.private_subnets -} - -# 在上面的 EKS 集群上创建另一个 TiDB 集群 -module "tidb-cluster-b" { - source = "../modules/aws/tidb-cluster" - providers = { - helm = "helm.eks" - } - - cluster_name = "tidb-cluster-b" - eks = module.tidb-operator.eks - ssh_key_name = module.key-pair.key_name - subnets = module.vpc.private_subnets -} - -# 创建一台堡垒机 -module "bastion" { - source = "../modules/aws/bastion" - - bastion_name = "another-eks-cluster-bastion" - key_name = module.key-pair.key_name - public_subnets = module.vpc.public_subnets - vpc_id = module.vpc.vpc_id - target_security_group_id = module.tidb-operator.eks.worker_security_group_id - enable_ssh_to_workers = true -} - -# 输出 tidb-cluster-a 的 TiDB 服务地址 -output "cluster-a_tidb-dns" { - description = "tidb service endpoints" - value = module.tidb-cluster-a.tidb_hostname -} - -# 输出 tidb-cluster-b 的监控地址 -output "cluster-b_monitor-dns" { - description = "tidb service endpoint" - value = module.tidb-cluster-b.monitor_hostname -} - -# 输出堡垒机 IP -output "bastion_ip" { - description = "Bastion IP address" - value = module.bastion.bastion_ip -} -``` - -上面的例子很容易进行定制，比如，假如你不需要堡垒机，便可以删去对 `bastion` 模块的调用。同时，项目中提供的 Terraform 模块均设置了合理的默认值，因此在调用这些 Terraform 模块时，你可以略去大部分的参数。 - -你可以参考默认的 Terraform 脚本来定制每个模块的参数，也可以参考每个模块的 `variables.tf` 文件来了解所有可配置的参数。 - -另外，这些 Terraform 模块可以很容易地集成到你自己的 Terraform 工作流中。假如你对 Terraform 非常熟悉，这也是我们推荐的一种使用方式。 - -> **注意：** -> -> * 由于 Terraform 本身的限制（[hashicorp/terraform#2430](https://github.com/hashicorp/terraform/issues/2430#issuecomment-370685911)），在你自己的 Terraform 脚本中，也需要保留上述例子中对 `helm provider` 的特殊处理。 -> * 创建新目录时，需要注意与 Terraform 模块之间的相对路径，这会影响调用模块时的 `source` 参数。 -> * 假如你想在 tidb-operator 项目之外使用这些模块，你需要确保 `modules` 目录中的所有模块的相对路径保持不变。 - -假如你不想自己写 Terraform 代码，也可以直接拷贝 `deploy/aws` 目录来创建新的 Kubernetes 集群。但要注意不能拷贝已经运行过 `terraform apply` 的目录（已经有 Terraform 的本地状态）。这种情况下，推荐在拷贝前克隆一个新的仓库。 diff --git a/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md b/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md deleted file mode 100644 index ef36dad785d8..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md +++ /dev/null @@ -1,741 +0,0 @@ ---- -title: 在 GCP GKE 上部署 TiDB 集群 -summary: 了解如何在 GCP GKE 上部署 TiDB 集群。 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/gcp-gke/'] ---- - -# 在 GCP GKE 上部署 TiDB 集群 - - - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在 GCP GKE 上部署 TiDB 集群。 - -> **警告：** -> -> 当前多磁盘聚合功能[存在一些已知问题](https://github.com/pingcap/tidb-operator/issues/684)，不建议在生产环境中每节点配置一块以上磁盘。我们正在修复此问题。 - -## 环境准备 - -部署前，确认已安装以下软件： - -* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -* [Google Cloud SDK](https://cloud.google.com/sdk/install) -* [Terraform](https://www.terraform.io/downloads.html) >= 0.12 -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.14 -* [Helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.0 且 < 3.0.0 -* [jq](https://stedolan.github.io/jq/download/) - -## 配置 - -为保证部署顺利，需要提前进行一些配置。在开始配置 Google Cloud SDK、API、Terraform 前，先下载以下资源： - -{{< copyable "shell-regular" >}} - -```bash -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator/deploy/gcp -``` - -### 配置 Google Cloud SDK - -安装 Google Cloud SDK 后，需要执行 `gcloud init` 进行[初始化](https://cloud.google.com/sdk/docs/initializing)。 - -### 配置 API - -如果使用的 GCP 项目是新项目，需确保以下 API 已启用： - -{{< copyable "shell-regular" >}} - -```bash -gcloud services enable cloudresourcemanager.googleapis.com \ -cloudbilling.googleapis.com iam.googleapis.com \ -compute.googleapis.com container.googleapis.com -``` - -### 配置 Terraform - -要执行 Terraform 脚本，需要设置以下 3 个环境变量。你可以等 Terraform 提示再输入，也可以提前在 `.tfvars` 文件中定义变量。 - -+ `GCP_CREDENTIALS_PATH`：GCP 证书文件路径。 - - - 建议另建一个服务账号给 Terraform 使用，参考[创建与管理服务账号文档](https://cloud.google.com/iam/docs/creating-managing-service-accounts)。`./create-service-account.sh` 会创建最低权限的服务账号。 - - - 参考[服务账号密钥文档](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)来创建服务账号密钥。下面脚本中的步骤详细说明了如何使用 `deploy/gcp` 目录中提供的脚本执行此操作。或者，如果自己创建服务账号和密钥，可以在创建时选择 `JSON` 类型的密钥。下载的包含私钥的 `JSON` 文件即所需的证书文件。 - -+ `GCP_REGION`：创建资源所在的区域，例如：`us-west1`。 -+ `GCP_PROJECT`：GCP 项目的名称。 - -要使用以上 3 个环境变量来配置 Terraform，可执行以下步骤： - -1. 将 `GCP_REGION` 替换为你的 GCP Region。 - - {{< copyable "shell-regular" >}} - - ```bash - echo GCP_REGION=\"us-west1\" >> terraform.tfvars - ``` - -2. 将 `GCP_PROJECT` 替换为你的 GCP 项目名称，确保连接的是正确的 GCP 项目。 - - {{< copyable "shell-regular" >}} - - ```bash - echo "GCP_PROJECT=\"$(gcloud config get-value project)\"" >> terraform.tfvars - ``` - -3. 初始化 Terraform。 - - {{< copyable "shell-regular" >}} - - ```bash - terraform init - ``` - -4. 为 Terraform 创建一个有限权限的服务账号，并设置证书路径。 - - {{< copyable "shell-regular" >}} - - ```bash - ./create-service-account.sh - ``` - -Terraform 自动加载和填充匹配 `terraform.tfvars` 或 `*.auto.tfvars` 文件的变量。相关详细信息，请参阅 [Terraform 文档](https://learn.hashicorp.com/terraform/getting-started/variables.html)。上述步骤会使用 `GCP_REGION` 和 `GCP_PROJECT` 填充 `terraform.tfvars` 文件，使用 `GCP_CREDENTIALS_PATH` 填充 `credentials.auto.tfvars` 文件。 - -## 部署 TiDB 集群 - -本小节介绍如何部署 TiDB 集群。 - -1. 确定实例类型。 - - - 如果只是想试一下 TiDB，又不想花费太高成本，可以采用轻量级的配置： - - {{< copyable "shell-regular" >}} - - ```bash - cat small.tfvars >> terraform.tfvars - ``` - - - 如果要对生产环境的部署进行 benchmark 测试，则建议采用生产级的配置： - - {{< copyable "shell-regular" >}} - - ```bash - cat prod.tfvars >> terraform.tfvars - ``` - - `prod.tfvars` 会默认创建一个新的 VPC，两个子网和一个 f1-micro 实例作为堡垒机，以及使用以下实例类型作为工作节点的 GKE 集群： - - * 3 台 n1-standard-4 实例：部署 PD - * 3 台 n1-highmem-8 实例：部署 TiKV - * 3 台 n1-standard-16 实例：部署 TiDB - * 3 台 n1-standard-2 实例：部署监控组件 - - 如上所述，生产环境的部署需要 91 个 CPU，超过了 GCP 项目的默认配额。可以参考[配额](https://cloud.google.com/compute/quotas)来增加项目配额。扩容同样需要更多 CPU。 - - > **注意：** - > - > 工作节点的数量取决于指定 Region 中可用区的数量。大部分 Region 有 3 个可用区，但是 `us-central1` 有 4 个可用区。参考 [Regions and Zones](https://cloud.google.com/compute/docs/regions-zones/) 查看更多信息。参考[自定义](#自定义)部分来自定义区域集群的节点池。 - -2. 启动脚本来部署 TiDB 集群： - - {{< copyable "shell-regular" >}} - - ```bash - terraform apply - ``` - - > **注意：** - > - > 如果未提前设置上文所述的 3 个环境变量，执行 `terraform apply` 过程中会有提示出现，要求对 3 个变量进行设置。详情请参考[配置 Terraform](#配置-terraform)。 - - 整个过程可能至少需要 10 分钟。`terraform apply` 执行成功后，会输出类似如下的信息: - - ``` - Apply complete! Resources: 23 added, 0 changed, 0 destroyed. - - Outputs: - - how_to_connect_to_default_cluster_tidb_from_bastion = mysql -h 172.31.252.20 -P 4000 -u root - how_to_ssh_to_bastion = gcloud compute ssh tidb-cluster-bastion --zone us-west1-b - how_to_set_reclaim_policy_of_pv_for_default_tidb_cluster_to_delete = kubectl --kubeconfig /.../credentials/kubeconfig_tidb-cluster get pvc -n tidb-cluster -o jsonpath='{.items[*].spec.volumeName}'|fmt -1 | xargs -I {} kubectl --kubeconfig /.../credentials/kubeconfig_tidb-cluster patch pv {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - kubeconfig_file = ./credentials/kubeconfig_tidb-cluster - monitor_lb_ip = 35.227.134.146 - monitor_port = 3000 - region = us-west1 - tidb_version = v3.0.1 - ``` - -## 访问 TiDB 数据库 - -`terraform apply` 运行完成后，可执行以下步骤来访问 TiDB 数据库。注意用[部署 TiDB 集群](#部署-tidb-集群)小节的输出信息替换 `<>` 部分的内容。 - -1. 通过 `ssh` 远程连接到堡垒机。 - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute ssh -bastion --zone - ``` - -2. 通过 MySQL 客户端来访问 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h -P 4000 -u root - ``` - - > **注意：** - > - > 通过 MySQL 连接 TiDB 前，需要先安装 MySQL 客户端。 - -## 与 GKE 集群交互 - -你可以通过 `kubectl` 和 `helm` 使用 kubeconfig 文件 `credentials/kubeconfig_` 和 GKE 集群交互。交互方式主要有以下两种。 - -> **注意：** -> -> `gke_cluster_name` 默认为 `tidb-cluster`，可以通过 `variables.tf` 中 `gke_name` 修改。 - -- 指定 `--kubeconfig` 参数： - - {{< copyable "shell-regular" >}} - - ```bash - kubectl --kubeconfig credentials/kubeconfig_ get po -n - ``` - - > **注意：** - > - > 下面这条命令使用的 `--kubeconfig` 参数至少需要 Helm 2.10.0 版本以上。 - - {{< copyable "shell-regular" >}} - - ```bash - helm --kubeconfig credentials/kubeconfig_ ls - ``` - -- 设置 `KUBECONFIG` 环境变量： - - {{< copyable "shell-regular" >}} - - ```bash - export KUBECONFIG=$PWD/credentials/kubeconfig_ - ``` - - {{< copyable "shell-regular" >}} - - ```bash - kubectl get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```bash - helm ls - ``` - -## 升级 TiDB 集群 - -要升级 TiDB 集群，可执行以下步骤： - -1. 编辑 `variables.tf` 文件，将 `tidb_version` 变量的值修改为更高版本。 -2. 运行 `terraform apply`。 - -例如，要将 TiDB 集群升级到 3.0.0-rc.2，可修改 `tidb_version` 为 `v3.0.0-rc.2`： - -``` -variable "tidb_version" { - description = "TiDB version" - default = "v3.0.0-rc.2" -} -``` - -升级过程会持续一段时间。你可以通过以下命令来持续观察升级进度： - -{{< copyable "shell-regular" >}} - -```bash -kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch -``` - -然后，你可以[访问数据库](#访问-tidb-数据库)并通过 `tidb_version()` 确认 TiDB 集群是否升级成功： - -{{< copyable "sql" >}} - -```sql -select tidb_version(); -``` - -``` -*************************** 1. row *************************** -tidb_version(): Release Version: v3.0.0-rc.2 -Git Commit Hash: 06f3f63d5a87e7f0436c0618cf524fea7172eb93 -Git Branch: HEAD -UTC Build Time: 2019-05-28 12:48:52 -GoVersion: go version go1.12 linux/amd64 -Race Enabled: false -TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e -Check Table Before Drop: false -1 row in set (0.001 sec) -``` - -## 管理多个 TiDB 集群 - -一个 `tidb-cluster` 模块的实例对应一个 GKE 集群中的 TiDB 集群。要添加一个新的 TiDB 集群，可执行以下步骤： - -1. 编辑 `tidbclusters.tf` 文件来添加一个 `tidb-cluster` 模块。 - - 例如： - - {{< copyable "" >}} - - ```hcl - module "example-tidb-cluster" { - providers = { - helm = "helm.gke" - } - source = "../modules/gcp/tidb-cluster" - cluster_id = module.tidb-operator.cluster_id - tidb_operator_id = module.tidb-operator.tidb_operator_id - gcp_project = var.GCP_PROJECT - gke_cluster_location = local.location - gke_cluster_name = - cluster_name = - cluster_version = "v3.0.1" - kubeconfig_path = local.kubeconfig - tidb_cluster_chart_version = "v1.0.0" - pd_instance_type = "n1-standard-1" - tikv_instance_type = "n1-standard-4" - tidb_instance_type = "n1-standard-2" - monitor_instance_type = "n1-standard-1" - pd_node_count = 1 - tikv_node_count = 2 - tidb_node_count = 1 - monitor_node_count = 1 - } - ``` - - > **注意：** - > - > - 每个集群的 `cluster_name` 必须是唯一的。 - > - 为任一组件实际创建的总节点数等于配置文件中的节点数乘以该 Region 中可用区的个数。 - - 你可以通过 `kubectl` 获取创建的 TiDB 集群和监控组件的地址。如果你希望 Terraform 脚本打印此信息，可在 `outputs.tf` 中添加一个 `output` 配置项，如下所示： - - {{< copyable "" >}} - - ```hcl - output "how_to_connect_to_example_tidb_cluster_from_bastion" { - value = module.example-tidb-cluster.how_to_connect_to_tidb_from_bastion - } - ``` - - 上述配置可使该脚本打印出用于连接 TiDB 集群的命令。 - -2. 修改完成后，执行以下命令来创建集群。 - - {{< copyable "shell-regular" >}} - - ```bash - terraform init - ``` - - {{< copyable "shell-regular" >}} - - ```bash - terraform apply - ``` - -## 扩容 - -如果需要扩容 TiDB 集群，可执行以下步骤： - -1. 按需修改 `variables.tf` 文件中的 `tikv_count`、`tidb_count` 变量。 -2. 运行 `terraform apply`。 - -> **警告：** -> -> 由于缩容过程中无法确定哪个节点会被删除，因此目前不支持集群缩容。通过修改 `tikv_count` 来进行缩容可能会导致数据丢失。 - -扩容过程会持续几分钟，你可以通过以下命令来持续观察进度： - -{{< copyable "shell-regular" >}} - -``` -kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch -``` - -例如，可以将 `tidb_count` 从 1 改为 2 来扩容 TiDB： - -```hcl -variable "tidb_count" { - description = "Number of TiDB nodes per availability zone" - default = 2 -} -``` - -> **注意：** -> -> 增加节点数量会在每个可用区都增加节点。 - -## 自定义 - -你可以更改 `variables.tf` 中的默认值，例如集群名称和镜像版本等，但更建议在 `terraform.tfvars` 文件或其它相关文件中来指定值。 - -### 自定义 GCP 资源 - -GCP 允许 `n1-standard-1` 或者更大的实例类型挂载本地 SSD，这提供了更好的自定义特性。 - -### 自定义 TiDB 参数配置 - -Terraform 脚本为 GKE 中的 TiDB 集群提供了默认设置。你也可以在 `tidbclusters.tf` 中为每个 TiDB 集群指定一个覆盖配置 `override_values` 或者覆盖配置文件 `override_values_file`。如果同时配置两个变量，`override_values` 配置将生效，该自定义配置会覆盖默认设置，示例如下： - -{{< copyable "" >}} - -``` -override_values = <}} - -``` -override_values_file = "./test-cluster.yaml" -``` - -集群默认使用 `deploy/modules/gcp/tidb-cluster` 模块中的 `values/default.yaml` 作为覆盖配置文件。 - -在 GKE 中，某些值不支持在 `values.yaml` 中自定义，包括集群版本、副本数、`NodeSelector` 以及 `Tolerations`。`NodeSelector` 和 `Tolerations` 由 Terraform 直接管理，以确保基础设施与 TiDB 集群之间的一致性。 - -如果需要自定义集群版本和副本数，可以修改 `tidbclusters.tf` 文件中每个 `tidb-cluster` module 的参数。 - -> **注意：** -> -> 自定义配置中，不建议在 `values.yaml` 中包含以下配置（`tidb-cluster` module 默认固定配置）： - -```yaml -pd: - storageClassName: pd-ssd -tikv: - stroageClassName: local-storage -tidb: - service: - type: LoadBalancer - annotations: - cloud.google.com/load-balancer-type: "Internal" - separateSlowLog: true -monitor: - storageClassName: pd-ssd - persistent: true - grafana: - config: - GF_AUTH_ANONYMOUS_ENABLED: "true" - service: - type: LoadBalancer -``` - -### 自定义 TiDB Operator - -如果要自定义 TiDB Operator，可以使用 `operator_helm_values` 变量来指定覆盖配置或者使用 `operator_helm_values_file` 变量来指定覆盖配置文件。如果同时配置两个变量，`operator_helm_values` 配置将生效，该自定义配置会传递给 `tidb-operator` 模块，示例如下： - -{{< copyable "" >}} - -``` -operator_helm_values = <}} - -``` -operator_helm_values_file = "./test-operator.yaml" -``` - -### 自定义日志 - -GKE 使用 [Fluentd](https://www.fluentd.org/) 作为其默认的日志收集工具，然后将日志转发到 Stackdriver。Fluentd 进程可能会占用大量资源，消耗大量的 CPU 和 RAM。[Fluent Bit](https://fluentbit.io/) 是一种性能更高，资源占用更少的替代方案。与 Fluentd 相比，更建议在生产环境中使用 Fluent Bit。可参考[在 GKE 集群中设置 Fluent Bit 的示例](https://github.com/pingcap/k8s-fluent-bit-stackdriver)。 - -### 自定义节点池 - -集群是按区域 (regional) 而非按可用区 (zonal) 来创建的。也就是说，GKE 向每个可用区复制相同的节点池，以实现更高的可用性。但对于 Grafana 这样的监控服务来说，通常没有必要维护相同的可用性。你可以通过 `gcloud` 手动删除节点。 - -> **注意：** -> -> GKE 节点池通过实例组管理。如果你使用 `gcloud compute instances delete` 命令删除某个节点，GKE 会自动重新创建节点并将其添加到集群。 - -如果你需要从监控节点池中删掉一个节点，可采用如下步骤： - -1. 获取托管的实例组和所在可用区。 - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed list | grep monitor - ``` - - 输出结果类似： - - ``` - gke-tidb-monitor-pool-08578e18-grp us-west1-b zone gke-tidb-monitor-pool-08578e18 0 0 gke-tidb-monitor-pool-08578e18 no - gke-tidb-monitor-pool-7e31100f-grp us-west1-c zone gke-tidb-monitor-pool-7e31100f 1 1 gke-tidb-monitor-pool-7e31100f no - gke-tidb-monitor-pool-78a961e5-grp us-west1-a zone gke-tidb-monitor-pool-78a961e5 1 1 gke-tidb-monitor-pool-78a961e5 no - ``` - - 第一列是托管的实例组，第二列是所在的可用区。 - -2. 获取实例组中的实例名字。 - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed list-instances --zone - ``` - - 示例： - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed list-instances gke-tidb-monitor-pool-08578e18-grp --zone us-west1-b - ``` - - 输出结果类似： - - ``` - NAME ZONE STATUS ACTION INSTANCE_TEMPLATE VERSION_NAME LAST_ERROR - gke-tidb-monitor-pool-08578e18-c7vd us-west1-b RUNNING NONE gke-tidb-monitor-pool-08578e18 - ``` - -3. 通过指定托管的实例组和实例的名称来删掉该实例。 - - 例如： - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed delete-instances gke-tidb-monitor-pool-08578e18-grp --instances=gke-tidb-monitor-pool-08578e18-c7vd --zone us-west1-b - ``` - -## 销毁 TiDB 集群 - -如果你不想再继续使用 TiDB 集群，可以通过如下命令进行销毁： - -{{< copyable "shell-regular" >}} - -```bash -terraform destroy -``` - -> **注意：** -> -> 在执行 `terraform destroy` 过程中，可能会发生错误：`Error reading Container Cluster "tidb": Cluster "tidb" has status "RECONCILING" with message""`。当 GCP 升级 Kubernetes master 节点时会出现该问题。一旦问题出现，就无法删除集群，需要等待 GCP 升级结束，再次执行 `terraform destroy`。 - -### 删除磁盘 - -如果你不再需要之前的数据，并且想要删除正在使用的磁盘，有以下两种方法可以完成此操作： - -- 手动删除：在 Google Cloud Console 中删除磁盘，或使用 `gcloud` 命令行工具执行删除操作。 - -- 自动删除：在执行 `terraform destroy` 之前将 Kubernetes 的 PV (Persistent Volume) 回收策略设置为 `Delete`，具体操作为在 `terraform destroy` 之前运行以下 `kubectl` 命令： - - {{< copyable "shell-regular" >}} - - ```bash - kubectl --kubeconfig /path/to/kubeconfig/file get pvc -n namespace-of-tidb-cluster -o jsonpath='{.items[*].spec.volumeName}'|fmt -1 | xargs -I {} kubectl --kubeconfig /path/to/kubeconfig/file patch pv {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - ``` - - 上述命令将获取 TiDB 集群命名空间中的 PVC (Persistent Volume Claim)，并将绑定的 PV 的回收策略设置为 `Delete`。在执行 `terraform destroy` 过程中删除 PVC 时，也会将磁盘删除。 - - 下面是一个名为 `change-pv-reclaimpolicy.sh` 的脚本。相对于仓库根目录来说，它在 `deploy/gcp` 目录，简化了上述过程。 - - {{< copyable "shell-regular" >}} - - ```bash - ./change-pv-reclaimpolicy.sh /path/to/kubeconfig/file - ``` - -## 管理多个 Kubernetes 集群 - -本节介绍管理多个 Kubernetes 集群的最佳实践，其中每个 Kubernetes 集群都可以部署一个或多个 TiDB 集群。 - -在 TiDB 的案例中，Terraform 模块通常结合了几个子模块： - -- `tidb-operator`：为 TiDB 集群提供 [Kubernetes Control Plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) 并部署 TiDB Operator。 -- `tidb-cluster`：在目标 Kubernetes 集群中创建资源池并部署 TiDB 集群。 -- 一个 `vpc` 模块，一个 `bastion` 模块和一个 `project-credentials` 模块：专门用于 GKE 上的 TiDB 集群。 - -管理多个 Kubernetes 集群的最佳实践有以下两点： - -1. 为每个 Kubernetes 集群创建一个新目录。 -2. 根据具体需求，使用 Terraform 脚本将上述模块进行组合。 - -如果采用了最佳实践，集群中的 Terraform 状态不会相互干扰，并且可以很方便地管理多个 Kubernetes 集群。示例如下（假设已在项目根目录）： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p deploy/gcp-staging && \ -vim deploy/gcp-staging/main.tf -``` - -`deploy/gcp-staging/main.tf` 中的内容类似： - -```hcl -provider "google" { - credentials = file(var.GCP_CREDENTIALS_PATH) - region = var.GCP_REGION - project = var.GCP_PROJECT -} - -// required for taints on node pools -provider "google-beta" { - credentials = file(var.GCP_CREDENTIALS_PATH) - region = var.GCP_REGION - project = var.GCP_PROJECT -} - -locals { - gke_name = "another-gke-name" - credential_path = "${path.cwd}/credentials" - kubeconfig = "${local.credential_path}/kubeconfig_${var.gke_name}" -} - - -module "project-credentials" { - source = "../modules/gcp/project-credentials" - - path = local.credential_path -} - -module "vpc" { - source = "../modules/gcp/vpc" - create_vpc = true - gcp_project = var.GCP_PROJECT - gcp_region = var.GCP_REGION - vpc_name = "${locals.gke_name}-vpc-network" - private_subnet_name = "${locals.gke_name}-private-subnet" - public_subnet_name = "${locals.gke_name}-public-subnet" -} - -module "tidb-operator" { - source = "../modules/gcp/tidb-operator" - gke_name = locals.gke_name - vpc_name = module.vpc.vpc_name - subnetwork_name = module.vpc.private_subnetwork_name - gcp_project = var.GCP_PROJECT - gcp_region = var.GCP_REGION - kubeconfig_path = local.kubeconfig - tidb_operator_version = "v1.0.0" -} - -module "bastion" { - source = "../modules/gcp/bastion" - vpc_name = module.vpc.vpc_name - public_subnet_name = module.vpc.public_subnetwork_name - gcp_project = var.GCP_PROJECT - bastion_name = "${locals.gke_name}-tidb-bastion" -} - -# HACK: 强制使 Helm 依赖 GKE 集群 -data "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.cluster_id] - filename = module.tidb-operator.kubeconfig_path -} -resource "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.cluster_id] - content = data.local_file.kubeconfig.content - filename = module.tidb-operator.kubeconfig_path -} - -provider "helm" { - alias = "gke" - insecure = true - install_tiller = false - kubernetes { - config_path = local_file.kubeconfig.filename - } -} -module "tidb-cluster-a" { - providers = { - helm = "helm.gke" - } - source = "../modules/gcp/tidb-cluster" - gcp_project = var.GCP_PROJECT - gke_cluster_location = var.GCP_REGION - gke_cluster_name = locals.gke_name - cluster_name = "tidb-cluster-a" - cluster_version = "v3.0.1" - kubeconfig_path = module.tidb-operator.kubeconfig_path - tidb_cluster_chart_version = "v1.0.0" - pd_instance_type = "n1-standard-1" - tikv_instance_type = "n1-standard-4" - tidb_instance_type = "n1-standard-2" - monitor_instance_type = "n1-standard-1" -} - -module "tidb-cluster-b" { - providers = { - helm = "helm.gke" - } - source = "../modules/gcp/tidb-cluster" - gcp_project = var.GCP_PROJECT - gke_cluster_location = var.GCP_REGION - gke_cluster_name = locals.gke_name - cluster_name = "tidb-cluster-b" - cluster_version = "v3.0.1" - kubeconfig_path = module.tidb-operator.kubeconfig_path - tidb_cluster_chart_version = "v1.0.0" - pd_instance_type = "n1-standard-1" - tikv_instance_type = "n1-standard-4" - tidb_instance_type = "n1-standard-2" - monitor_instance_type = "n1-standard-1" -} - -output "how_to_ssh_to_bastion" { - value= module.bastion.how_to_ssh_to_bastion -} - -output "connect_to_tidb_cluster_a_from_bastion" { - value = module.tidb-cluster-a.how_to_connect_to_default_cluster_tidb_from_bastion -} - -output "connect_to_tidb_cluster_b_from_bastion" { - value = module.tidb-cluster-b.how_to_connect_to_default_cluster_tidb_from_bastion -} - -``` - -如上述代码所示，你可以在每个模块调用中省略几个参数，因为有合理的默认值，并且可以轻松地自定义配置。例如，如果你不需要调用堡垒机模块，将其删除即可。 - -如果要自定义每个字段，可使用以下两种方法中的一种： - -- 直接修改 `*.tf` 文件中 `module` 的参数配置。 -- 参考每个模块的 `variables.tf` 文件，了解所有可修改的参数，并在 `terraform.tfvars` 中设置自定义值。 - -> **注意：** -> -> - 创建新目录时，请注意其与 Terraform 模块的相对路径，这会影响模块调用期间的 `source` 参数。 -> - 如果要在 tidb-operator 项目之外使用这些模块，务必确保复制整个 `modules` 目录并保持目录中每个模块的相对路径不变。 -> - 由于 Terraform 的限制[（参见 hashicorp/terraform＃2430）](https://github.com/hashicorp/terraform/issues/2430#issuecomment-370685911)，上面示例中添加了 **HACK: 强制使 Helm 依赖 GKE 集群**部分对 Helm provider 进行处理。如果自己编写 tf 文件，需要包含这部分内容。 - -如果你不愿意编写 Terraform 代码，还可以复制 `deploy/gcp` 目录来创建新的 Kubernetes 集群。但需要注意，不能复制已被执行 `terraform apply` 命令的目录。在这种情况下，建议先克隆新的仓库再复制目录。 diff --git a/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md b/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md deleted file mode 100644 index 7ca3c0d45478..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: 在标准 Kubernetes 上部署 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/general-kubernetes/'] ---- - -# 在标准 Kubernetes 上部署 TiDB 集群 - -本文主要描述了如何在标准的 Kubernetes 集群上通过 TiDB Operator 部署 TiDB 集群。 - -## 前置条件 - -* 参考 [TiDB Operator](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md) 完成集群中的 TiDB Operator 部署； -* 参考 [使用 Helm](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 - -## 配置 TiDB 集群 - -通过下面命令获取待安装的 tidb-cluster chart 的 `values.yaml` 配置文件： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p /home/tidb/ && \ -helm inspect values pingcap/tidb-cluster --version= > /home/tidb//values-.yaml -``` - -> **注意：** -> -> - `/home/tidb` 可以替换为你想用的目录。 -> - `release-name` 将会作为 Kubernetes 相关资源（例如 Pod，Service 等）的前缀名，可以起一个方便记忆的名字，要求全局唯一，通过 `helm ls -q` 可以查看集群中已经有的 `release-name`。 -> - `chart-version` 是 tidb-cluster chart 发布的版本，可以通过 `helm search -l tidb-cluster` 查看当前支持的版本。 -> - 下文会用 `values.yaml` 指代 `/home/tidb//values-.yaml`。 - -### 存储类型 - -集群默认使用 `local-storage` 存储类型。 - -- 生产环境：推荐使用本地存储，但实际 Kubernetes 集群中本地存储可能按磁盘类型进行了分类，例如 `nvme-disks`，`sas-disks`。 -- 演示环境或功能性验证：可以使用网络存储，例如 `ebs`，`nfs` 等。 - -另外 TiDB 集群不同组件对磁盘的要求不一样，所以部署集群前要根据当前 Kubernetes 集群支持的存储类型以及使用场景为 TiDB 集群各组件选择合适的存储类型，通过修改 `values.yaml` 中各组件的 `storageClassName` 字段设置存储类型。关于 Kubernetes 集群支持哪些[存储类型](/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md)，请联系系统管理员确定。 - -> **注意：** -> -> 如果创建集群时设置了集群中不存在的存储类型，则会导致集群创建处于 Pending 状态，需要[将集群彻底销毁掉](/v3.0/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md)。 - -### 集群拓扑 - -默认部署的集群拓扑是：3 个 PD Pod，3 个 TiKV Pod，2 个 TiDB Pod 和 1 个监控 Pod。在该部署拓扑下根据数据高可用原则，TiDB Operator 扩展调度器要求 Kubernetes 集群中至少有 3 个节点。如果 Kubernetes 集群节点个数少于 3 个，将会导致有一个 PD Pod 处于 Pending 状态，而 TiKV 和 TiDB Pod 也都不会被创建。 - -Kubernetes 集群节点个数少于 3 个时，为了使 TiDB 集群能启动起来，可以将默认部署的 PD 和 TiKV Pod 个数都减小到 1 个，或者将 `values.yaml` 中 `schedulerName` 改为 Kubernetes 内置调度器 `default-scheduler`。 - -> **警告：** -> -> `default-scheduler` 仅适用于演示环境，改为 `default-scheduler` 后，TiDB 集群的调度将无法保证数据高可用，另外一些其它特性也无法支持，例如 [TiDB Pod StableScheduling](https://github.com/pingcap/tidb-operator/blob/master/docs/design-proposals/tidb-stable-scheduling.md) 等。 - -其它更多配置参数请参考 [TiDB 集群部署配置文档](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 - -## 部署 TiDB 集群 - -TiDB Operator 部署并配置完成后，可以通过下面命令部署 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster --name= --namespace= --version= -f /home/tidb//values-.yaml -``` - -> **注意：** -> -> `namespace` 是[命名空间](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)，你可以起一个方便记忆的名字，比如和 `release-name` 相同的名称。 - -通过下面命令可以查看 Pod 状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get po -n -l app.kubernetes.io/instance= -``` - -单个 Kubernetes 集群中可以利用 TiDB Operator 部署管理多套 TiDB 集群，重复以上命令并将 `release-name` 替换成不同名字即可。不同集群既可以在相同 `namespace` 中，也可以在不同 `namespace` 中，可根据实际需求进行选择。 diff --git a/v3.0/tidb-in-kubernetes/deploy/prerequisites.md b/v3.0/tidb-in-kubernetes/deploy/prerequisites.md deleted file mode 100644 index 17e499bca361..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/prerequisites.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群环境需求 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/prerequisites/'] ---- - -# Kubernetes 上的 TiDB 集群环境需求 - -本文介绍在 Kubernetes 上部署 TiDB 集群的软硬件环境需求。 - -## 软件版本要求 - -| 软件名称 | 版本 | -| :--- | :--- | -| Docker | Docker CE 18.09.6 | -| Kubernetes | v1.12.5+ | -| CentOS | CentOS 7.6，内核要求为 3.10.0-957 或之后版本 | - -## 内核参数设置 - -| 配置项 | 设置值 | -| :--- | :--- | -| net.core.somaxconn | 32768 | -| vm.swappiness | 0 | -| net.ipv4.tcp_syncookies | 0 | -| net.ipv4.ip_forward | 1 | -| fs.file-max | 1000000 | -| fs.inotify.max_user_watches | 1048576 | -| fs.inotify.max_user_instances | 1024 | -| net.ipv4.conf.all.rp_filter | 1 | -| net.ipv4.neigh.default.gc_thresh1 | 80000 | -| net.ipv4.neigh.default.gc_thresh2 | 90000 | -| net.ipv4.neigh.default.gc_thresh3 | 100000 | -| net.bridge.bridge-nf-call-iptables | 1 | -| net.bridge.bridge-nf-call-arptables | 1 | -| net.bridge.bridge-nf-call-ip6tables | 1 | - -在设置 `net.bridge.bridge-nf-call-*` 这几项参数时，如果选项报错，则可通过如下命令检查是否已经加载该模块： - -{{< copyable "shell-regular" >}} - -```shell -lsmod|grep br_netfilter -``` - -如果没有加载，则执行如下命令加载： - -{{< copyable "shell-regular" >}} - -```shell -modprobe br_netfilter -``` - -同时还需要关闭每个部署 Kubernetes 节点的 swap，执行如下命令： - -{{< copyable "shell-regular" >}} - -```shell -swapoff -a -``` - -执行如下命令检查 swap 是否已经关闭： - -{{< copyable "shell-regular" >}} - -```shell -free -m -``` - -如果执行命令后输出显示 swap 一列全是 0，则表明 swap 已经关闭。 - -此外，为了永久性地关闭 swap，还需要将 `/etc/fstab` 中 swap 相关的条目全部删除。 - -在上述内容都设置完成后，还需要检查是否给机器配置了 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt)，也就是将各个设备对应的中断号分别绑定到不同的 CPU 上，以防止所有中断请求都落在同一个 CPU 上而引发性能瓶颈。对于 TiDB 集群来说，网卡处理包的速度对集群的吞吐率影响很大。因此下文主要描述如何将网卡中断号绑定到特定的 CPU 上，充分利用多核的优势来提高集群的吞吐率。首先可以通过以下命令来查看网卡对应的中断号： - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/interrupts|grep |awk '{print $1,$NF}' -``` - -以上命令输出的第一列是中断号，第二列是设备名称。如果是多队列网卡，上面的命令会显示多行信息，网卡的每个队列对应一个中断号。通过以下命令可以查看该中断号被绑定到哪个 CPU 上： - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/irq//smp_affinity -``` - -上面命令输出 CPU 序号对应的十六进制值。输出结果欠直观。具体计算方法可参见 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt) 文档。 - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/irq//smp_affinity_list -``` - -上面命令输出 CPU 序号对应的十进制值，输出结果较为直观。 - -如果多队列网卡对应的所有中断号都已被绑定到不同的 CPU 上，那么该机器的 SMP IRQ Affinity 配置是正确的。如果中断号都落在同一个 CPU 上，则需要进行调整。调整的方式有以下两种： - -+ 方法一：开启 [irqbalance](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-tool_reference-irqbalance) 服务。在 centos7 系统上的开启命令如下: - - {{< copyable "shell-regular" >}} - - ```shell - systemctl start irqbalance - ``` - -+ 方法二：禁用 irqbalance，自定义中断号和 CPU 的绑定关系。详情参见脚本 [set_irq_affinity.sh](https://gist.githubusercontent.com/SaveTheRbtz/8875474/raw/0c6e500e81e161505d9111ac77115a2367180d12/set_irq_affinity.sh)。 - -上文所描述的是处理多队列网卡和多核心的场景。单队列网卡和多核的场景则有不同的处理方式。在这种场景下，可以使用 [RPS/RFS](https://www.kernel.org/doc/Documentation/networking/scaling.txt) 在软件层面模拟实现硬件的网卡多队列功能 (RSS)。此时不能使用方法一所述的 irqbalance 服务，而是通过使用方法二提供的脚本来设置 RPS。RFS 的配置可以参考[这里](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-networking-configuration_tools#sect-Red_Hat_Enterprise_Linux-Performance_Tuning_Guide-Configuration_tools-Configuring_Receive_Flow_Steering_RFS)。 - -## 硬件和部署要求 - -与使用 binary 方式部署 TiDB 集群一致，要求选用 Intel x86-64 架构的 64 位通用硬件服务器，使用万兆网卡。关于 TiDB 集群在物理机上的具体部署需求，参考 [TiDB 软件和硬件环境建议配置](/v3.0/how-to/deploy/hardware-recommendations.md)。 - -对于服务器 disk、memory、CPU 的选择要根据对集群的容量规划以及部署拓扑来定。线上 Kubernetes 集群部署为了保证高可用，一般需要部署三个 master 节点、三个 etcd 节点以及若干个 worker 节点。同时，为了充分利用机器资源，master 节点一般也充当 worker 节点（也就是 master 节点上也可以调度负载）。通过 kubelet 设置[预留资源](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/)来保证机器上的系统进程以及 Kubernetes 的核心进程在工作负载很高的情况下仍然有足够的资源来运行，从而保证整个系统的稳定。 - -下面按 3 Kubernetes master + 3 etcd + 若干 worker 节点部署方案进行分析。Kubernetes 的多 master 节点高可用部署可参考[官方文档](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/)。 - -## Kubernetes 系统资源要求 - -- 每台机器需要一块比较大的 SAS 盘（至少 1T），这块盘用来存 Docker 和 kubelet 的数据目录。Docker 的数据主要包括镜像和容器日志数据，kubelet 主要占盘的数据是 [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) 所使用的数据。 - -- 如果需要部署 Kubernetes 集群的监控系统, 且监控数据需要落盘，则也需要考虑为 Prometheus 准备一块 SAS 盘，后面日志监控系统也需要大的 SAS 盘，同时考虑到机器采购最好是同构的这一因素，因此每台机器最好有两块大的 SAS 盘。 - - > **注意：** - > - > 生产环境建议给这两种类型的盘做 RAID5，至于使用多少块来做 RAID5 可自己决定。 - -- etcd 的分布建议是和 Kubernetes master 节点保持一致，即有多少个 master 节点就部署多少个 etcd 节点。etcd 数据建议使用 SSD 盘存放。 - -## TiDB 集群资源需求 - -TiDB 集群由 PD、TiKV、TiDB 三个组件组成，在做容量规划的时候一般按照可以支持多少套 TiDB 集群来算。这里按照标准的 TiDB 集群（3 个 PD + 3 个 TiKV + 2 个 TiDB）来算，下面是对每个组件规划的一种建议： - -- PD 组件：PD 占用资源较少，这种集群规模下分配 2C 4GB 即可，占用少量本地盘。 - - 为了便于管理，可以将所有集群的 PD 都放在 master 节点，比如需要支持 5 套 TiDB 集群，则可以规划 3 个 master 节点，每个节点支持部署 5 个 PD 实例，5 个 PD 实例使用同一块 SSD 盘即可（两三百 GB 的盘即可）。通过 bind mount 的方式在这块 SSD 上创建 5 个目录作为挂载点，操作方式见 [Sharing a disk filesystem by multiple filesystem PVs](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)。 - - 如果后续要添加更多机器支持更多的 TiDB 集群，可以在 master 上用这种方式继续增加 PD 实例。如果 master 上资源耗尽，可以找其它的 worker 节点机器用同样的方式添加 PD 实例。这种方式的好处就是方便规划和管理 PD 实例，坏处就是由于 PD 实例过于集中，这些机器中如果有两台宕机会导致所有的 TiDB 集群不可用。 - - 因此建议从所有集群里面的机器都拿出一块 SSD 盘像 master 节点一样提供 PD 实例。比如总共 7 台机器，要支持 7 套 TiDB 标准集群的情况下，则需要每台机器上都能支持部署 3 个 PD 实例，如果后续有集群需要通过扩容机器增加容量，也只需要在新的机器上创建 PD 实例。 - -- TiKV 组件：因为 TiKV 组件的性能很依赖磁盘 I/O 且数据量一般较大，因此建议每个 TiKV 实例独占一块 NVMe 的盘，资源配置为 8C 32GB。如果想要在一个机器上支持部署多个 TiKV 实例，则建议参考这些参数去选择合适的机器，同时在规划容量的时候应当预留出足够的 buffer。 - -- TiDB 组件：TiDB 组件因为不占用磁盘，因此在规划的时候只需要考虑其占用的 CPU 和内存资源即可，这里也按 8C 32 GB 的容量来计算。 - -## TiDB 集群规划示例 - -通过上面的分析，这里给出一个支持部署 5 套规模为 3 个 PD + 3 个 TiKV + 2 个 TiDB 集群的例子，其中 PD 配置为 2C 4GB，TiDB 配置为 8C 32GB，TiKV 配置为 8C 32GB。Kubernetes 节点有 7 个，其中有 3 个节点既是 master 又是 worker 节点，另外 4 个是纯 worker 节点。各组件分布情况如下： - -+ 单个 master 节点： - - - 1 etcd (2C 4GB) + 2 PD (2 \* 2C 2 \* 4GB) + 3 TiKV (3 \* 8C 3 \* 32GB) + 1 TiDB (8C 32GB)，总共是 38C 140GB - - 两块 SSD 盘，一块给 etcd，另外一块给 2 个 PD 实例 - - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 - - 三块 NVMe 盘给 TiKV 实例 - -+ 单个 worker 节点： - - - 3 PD (3 \* 2C 3 \* 4GB) + 2 TiKV (2 \* 8C 2 \* 32GB) + 2 TiDB (2 \* 8C 2 \* 32GB)，总共是 38C 140GB - - 一块 SSD 盘给三个 PD 实例 - - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 - - 两块 NVMe 盘给 TiKV 实例 - -从上面的分析来看，要支持 5 套 TiDB 集群容量共需要 7 台物理机，其中 3 台为 master 兼 worker 节点，其余 4 台为 worker 节点，机器配置需求如下： - -- master 兼 worker 节点：48C 192GB；2 块 SSD 盘，一块做了 RAID5 的 SAS 盘，三块 NVMe 盘 -- worker 节点：48C 192GB；1 块 SSD 盘，一块做了 RAID5 的 SAS 盘，两块 NVMe 盘 - -使用上面的机器配置，除去各个组件占用的资源外，还有比较多的预留资源。如果要考虑加监控和日志组件，则可以用同样的方法去规划需要采购的机器类型以及配置。 - -另外，在生产环境的使用上尽量不要在 master 节点部署 TiDB 实例，或者尽可能少地部署 TiDB 实例。这里的主要考虑点是网卡带宽，因为 master 节点网卡满负荷工作会影响到 worker 节点和 master 节点之间的心跳信息汇报，导致比较严重的问题。 diff --git a/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md b/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md deleted file mode 100644 index 6408d7198b5b..000000000000 --- a/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: 在 Kubernetes 上部署 TiDB Operator -summary: 了解如何在 Kubernetes 上部署 TiDB Operator -category: how-to -aliases: ['/docs-cn/v3.0/how-to/deploy/tidb-in-kubernetes/tidb-operator/'] ---- - -# 在 Kubernetes 上部署 TiDB Operator - -本文介绍如何在 Kubernetes 上部署 TiDB Operator。 - -## 准备环境 - -TiDB Operator 部署前，请确认以下软件需求： - -* Kubernetes v1.12 或者更高版本 -* [DNS 插件](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/) -* [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) -* [RBAC](https://kubernetes.io/docs/admin/authorization/rbac) 启用（可选） -* [Helm](https://helm.sh) 版本 >= v2.8.2 && < v3.0.0 - -> **注意：** -> -> - 尽管 TiDB Operator 可以使用网络卷持久化 TiDB 数据，TiDB 数据自身会存多副本，再走额外的网络卷通常会比较慢。强烈建议搭建[本地卷](https://kubernetes.io/docs/concepts/storage/volumes/#local)以提高性能。 -> - 跨多可用区的网络卷需要 Kubernetes v1.12 或者更高版本。在 `tidb-backup` chart 配置中，建议使用网络卷存储备份数据。 - -## 部署 Kubernetes 集群 - -TiDB Operator 运行在 Kubernetes 集群，你可以使用 [Getting started 页面](https://kubernetes.io/docs/setup/)列出的任何一种方法搭建一套 Kubernetes 集群。只要保证 Kubernetes 版本大于等于 v1.12。如果你使用 AWS、GKE 或者本机，下面是快速上手教程： - -* [kind 教程](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) -* [Google GKE 教程](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) -* [AWS EKS 教程](/v3.0/tidb-in-kubernetes/deploy/aws-eks.md) - -如果你要使用不同环境，必须在 Kubernetes 集群中安装 DNS 插件。可以根据[官方文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/)搭建 DNS 插件。 - -TiDB Operator 使用[持久化卷](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)持久化存储 TiDB 集群数据（包括数据库，监控和备份数据），所以 Kubernetes 集群必须提供至少一种持久化卷。为提高性能，建议使用本地 SSD 盘作为持久化卷。可以根据[这一步](#配置本地持久化卷)自动配置本地持久化卷。 - -Kubernetes 集群建议启用 [RBAC](https://kubernetes.io/docs/admin/authorization/rbac)。否则，需要在 `tidb-operator` 和 `tidb-cluster` chart 的 `values.yaml` 中设置 `rbac.create` 为 `false`。 - -TiDB 默认会使用很多文件描述符，工作节点和上面的 Docker 进程的 `ulimit` 必须设置大于等于 `1048576`： - -* 设置工作节点的 `ulimit` 值，详情可以参考[如何设置 ulimit](https://access.redhat.com/solutions/61334) - - {{< copyable "shell-regular" >}} - - ```shell - sudo vim /etc/security/limits.conf - ``` - - 设置 root 账号的 `soft` 和 `hard` 的 `nofile` 大于等于 `1048576` - -* 设置 Docker 服务的 `ulimit` - - {{< copyable "shell-regular" >}} - - ```shell - sudo vim /etc/systemd/system/docker.service - ``` - - 设置 `LimitNOFILE` 大于等于 `1048576`。 - -> **注意：** -> -> `LimitNOFILE` 需要显式设置为 `1048576` 或者更大，而不是默认的 `infinity`，由于 `systemd` 的 [bug](https://github.com/systemd/systemd/commit/6385cb31ef443be3e0d6da5ea62a267a49174688#diff-108b33cf1bd0765d116dd401376ca356L1186)，`infinity` 在 `systemd` 某些版本中指的是 `65536`。 - -## 安装 Helm - -参考 [使用 Helm](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 - -## 配置本地持久化卷 - -### 准备本地卷 - -参考[本地 PV 配置](/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)在你的 Kubernetes 集群中配置本地持久化卷。 - -## 安装 TiDB Operator - -TiDB Operator 使用 [CRD (Custom Resource Definition)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) 扩展 Kubernetes，所以要使用 TiDB Operator，必须先创建 `TidbCluster` 自定义资源类型。只需要在你的 Kubernetes 集群上创建一次即可： - -{{< copyable "shell-regular" >}} - -```shell -kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/crd.yaml && \ -kubectl get crd tidbclusters.pingcap.com -``` - -创建 `TidbCluster` 自定义资源类型后，接下来在 Kubernetes 集群上安装 TiDB Operator。 - -1. 获取你要安装的 `tidb-operator` chart 中的 `values.yaml` 文件： - - {{< copyable "shell-regular" >}} - - ```shell - mkdir -p /home/tidb/tidb-operator && \ - helm inspect values pingcap/tidb-operator --version= > /home/tidb/tidb-operator/values-tidb-operator.yaml - ``` - - > **注意：** - > - > `` 在后续文档中代表 chart 版本，例如 `v1.0.0`，可以通过 `helm search -l tidb-operator` 查看当前支持的版本。 - -2. 配置 TiDB Operator - - TiDB Operator 里面会用到 `k8s.gcr.io/kube-scheduler` 镜像，如果下载不了该镜像，可以修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 文件中的 `scheduler.kubeSchedulerImageName` 为 `registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler`。 - -3. 安装 TiDB Operator - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-operator --name=tidb-operator --namespace=tidb-admin --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml && \ - kubectl get po -n tidb-admin -l app.kubernetes.io/name=tidb-operator - ``` - -## 自定义 TiDB Operator - -通过修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 中的配置自定义 TiDB Operator。后续文档使用 `values.yaml` 指代 `/home/tidb/tidb-operator/values-tidb-operator.yaml`。 - -TiDB Operator 有两个组件： - -* tidb-controller-manager -* tidb-scheduler - -这两个组件是无状态的，通过 `Deployment` 部署。你可以在 `values.yaml` 中自定义资源 `limit`、`request` 和 `replicas`。 - -修改为 `values.yaml` 后，执行下面命令使配置生效： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade tidb-operator pingcap/tidb-operator --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml -``` diff --git a/v3.0/tidb-in-kubernetes/faq.md b/v3.0/tidb-in-kubernetes/faq.md deleted file mode 100644 index 675ea9be687f..000000000000 --- a/v3.0/tidb-in-kubernetes/faq.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群常见问题 -category: FAQ -aliases: ['/docs-cn/v3.0/faq/tidb-in-kubernetes/'] ---- - -# Kubernetes 上的 TiDB 集群常见问题 - -本文介绍 Kubernetes 上的 TiDB 集群常见问题以及解决方案。 - -## 如何修改时区设置？ - -默认情况下，在 Kubernetes 集群上部署的 TiDB 集群各组件容器中的时区为 UTC，如果要修改时区配置，有下面两种情况： - -* 第一次部署集群 - - 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后部署 TiDB 集群。 - -* 集群已经在运行 - - 如果 TiDB 集群已经在运行，需要做如下修改： - - * 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后升级 TiDB 集群。 - * 参考[时区支持](/v3.0/how-to/configure/time-zone.md)，修改 TiDB 服务时区配置。 - -## TiDB 相关组件可以配置 HPA 或 VPA 么？ - -TiDB 集群目前还不支持 HPA（Horizontal Pod Autoscaling，自动水平扩缩容）和 VPA（Vertical Pod Autoscaling，自动垂直扩缩容），因为对于数据库这种有状态应用而言，实现自动扩缩容难度较大，无法仅通过 CPU 和 memory 监控数据来简单地实现。 - -## 使用 TiDB Operator 编排 TiDB 集群时，有什么场景需要人工介入操作吗？ - -如果不考虑 Kubernetes 集群本身的运维，TiDB Operator 存在以下可能需要人工介入的场景： - -* TiKV 自动故障转移之后的集群调整，参考[自动故障转移](/v3.0/tidb-in-kubernetes/maintain/auto-failover.md)； -* 维护或下线指定的 Kubernetes 节点，参考[维护节点](/v3.0/tidb-in-kubernetes/maintain/kubernetes-node.md)。 - -## 在公有云上使用 TiDB Operator 编排 TiDB 集群时，推荐的部署拓扑是怎样的？ - -首先，为了实现高可用和数据安全，我们在推荐生产环境下的 TiDB 集群中至少部署在三个可用区 (Available Zone)。 - -当考虑 TiDB 集群与业务服务的部署拓扑关系时，TiDB Operator 支持下面几种部署形态。它们有各自的优势与劣势，具体选型需要根据实际业务需求进行权衡： - -* 将 TiDB 集群与业务服务部署在同一个 VPC 中的同一个 Kubernetes 集群上； -* 将 TiDB 集群与业务服务部署在同一个 VPC 中的不同 Kubernetes 集群上； -* 将 TiDB 集群与业务服务部署在不同 VPC 中的不同 Kubernetes 集群上。 - -## TiDB Operator 支持 TiSpark 吗？ - -TiDB Operator 尚不支持自动编排 TiSpark。 - -假如要为 TiDB in Kubernetes 添加 TiSpark 组件，你需要在**同一个** Kubernetes 集群中自行维护 Spark，确保 Spark 能够访问到 PD 和 TiKV 实例的 IP 与端口，并为 Spark 安装 TiSpark 插件，TiSpark 插件的安装方式可以参考 [TiSpark](/v3.0/reference/tispark.md#已有-Spark-集群的部署方式)。 - -在 Kubernetes 上维护 Spark 可以参考 Spark 的官方文档：[Spark on Kubernetes](http://spark.apache.org/docs/latest/running-on-kubernetes.html)。 - -## 如何查看 TiDB 集群配置？ - -如果需要查看当前集群的 PD、TiKV、TiDB 组件的配置信息，可以执行下列命令: - -* 查看 PD 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -n -- cat /etc/pd/pd.toml - ``` - -* 查看 TiKV 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -n -- cat /etc/tikv/tikv.toml - ``` - -* 查看 TiDB 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -c tidb -n -- cat /etc/tidb/tidb.toml - ``` - -## 部署 TiDB 集群时调度失败是什么原因？ - -TiDB Operator 调度 Pod 失败的原因可能有三种情况： - -* 资源不足，导致 Pod 一直阻塞在 `Pending` 状态。详细说明参见[集群故障诊断](/v3.0/tidb-in-kubernetes/troubleshoot.md)。 - -* 部分 Node 被打了 `taint`，导致 Pod 无法调度到对应的 Node 上。详请参考 [taint & toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)。 - -* 调度错误，导致 Pod 一直阻塞在 `ContainerCreating` 状态。这种情况发生时请检查 Kubernetes 集群中是否部署过多个 TiDB Operator。重复的 TiDB Operator 自定义调度器的存在，会导致同一个 Pod 的调度周期不同阶段会分别被不同的调度器处理，从而产生冲突。 - - 执行以下命令，如果有两条及以上记录，就说明 Kubernetes 集群中存在重复的 TiDB Operator，请根据实际情况删除多余的 TiDB Operator。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get deployment --all-namespaces |grep tidb-scheduler - ``` diff --git a/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md b/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md deleted file mode 100644 index 8f774b29fac1..000000000000 --- a/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: 在 GCP 上通过 Kubernetes 部署 TiDB 集群 -summary: 在 GCP 上通过 Kubernetes 部署 TiDB 集群教程 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/get-started/deploy-tidb-from-kubernetes-gke/'] ---- - -# 在 GCP 上通过 Kubernetes 部署 TiDB 集群 - -本文介绍如何使用 [TiDB Operator](https://github.com/pingcap/tidb-operator) 在 GCP 上部署 TiDB 集群。本教程需要在 [Google Cloud Shell](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/pingcap/tidb-operator&tutorial=docs/google-kubernetes-tutorial.md) 上运行。 - -所包含的步骤如下： - -- 启动一个包含 3 个节点的 Kubernetes 集群（可选） -- 安装 Kubernetes 包管理工具 Helm -- 部署 TiDB Operator -- 部署 TiDB 集群 -- 访问 TiDB 集群 -- 扩容 TiDB 集群 -- 删除 Kubernetes 集群（可选） - -> **警告：** -> -> 对于生产环境，不要使用此方式进行部署。 - -## 选择一个项目 - -本教程会启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。价格信息可以参考 [All pricing](https://cloud.google.com/compute/pricing)。 - -继续之前请选择一个项目： - - - - -## 启用 API - -本教程需要使用计算和容器 API。继续之前请启用： - - - - -## 配置 gcloud - -这一步配置 glcoud 默认访问你要用的项目和[可用区](https://cloud.google.com/compute/docs/regions-zones/)，可以简化后面用到的命令： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud config set project {{project-id}} && \ -gcloud config set compute/zone us-west1-a -``` - -## 启动 3 个节点的 Kubernetes 集群 - -下面命令启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。 - -命令执行需要几分钟时间： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud container clusters create tidb -``` - -集群启动完成后，将其设置为默认集群： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud config set container/cluster tidb -``` - -最后验证 `kubectl` 可以访问集群并且 3 个节点正常运行： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get nodes -``` - -如果所有节点状态为 `Ready`，恭喜你，你已经成功搭建你的第一个 Kubernetes 集群。 - -## 安装 Helm - -Helm 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 - -安装 `helm`： - -{{< copyable "shell-regular" >}} - -``` shell -curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash -``` - -复制 `helm` 到你的 `$HOME` 目录下，这样即使 Google Cloud Shell 超时断开连接，再次登录后仍然可以访问 Helm： - -{{< copyable "shell-regular" >}} - -``` shell -mkdir -p ~/bin && \ -cp /usr/local/bin/helm ~/bin && \ -echo 'PATH="$PATH:$HOME/bin"' >> ~/.bashrc -``` - -Helm 正常工作需要一定的权限： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl apply -f ./manifests/tiller-rbac.yaml && \ -helm init --service-account tiller --upgrade -``` - -`tiller` 是 Helm 的服务端组件，初始化完成需要几分钟时间： - -{{< copyable "shell-regular" >}} - -``` shell -watch "kubectl get pods --namespace kube-system | grep tiller" -``` - -当 Pod 状态为 `Running`，Ctrl+C 停止并继续下一步。 - -## 添加 Helm 仓库 - -PingCAP Helm 仓库中存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。使用下面命令添加仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo add pingcap https://charts.pingcap.org/ && \ -helm repo list -``` - -然后你可以查看可用的 chart： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo update && \ -helm search tidb-cluster -l && \ -helm search tidb-operator -l -``` - -## 部署 TiDB 集群 - -> **注意：** -> -> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 - -第一个要安装的 TiDB 组件是 TiDB Operator，TiDB Operator 是管理组件，结合 Kubernetes 启动 TiDB 集群并保证集群正常运行。执行下面命令之前请确保在 `tidb-operator` 目录下： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl apply -f ./manifests/crd.yaml && \ -kubectl apply -f ./manifests/gke/persistent-disk.yaml && \ -helm install pingcap/tidb-operator -n tidb-admin --namespace=tidb-admin --version= -``` - -可以通过下面命令观察 Operator 启动情况： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb-admin -o wide --watch -``` - -如果 tidb-scheduler 和 tidb-controller-manager 状态都为 `Running`，Ctrl+C 停止并继续下一步部署一个 TiDB 集群！ - -## 部署你的第一个 TiDB 集群 - -我们可以一键部署一个 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster -n demo --namespace=tidb --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd --version= -``` - -集群启动需要几分钟时间，可以通过下面命令观察状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb -o wide --watch -``` - -TiDB 集群包含 2 个 TiDB pod，3 个 TiKV pod 和 3 个 PD pod。如果所有 pod 状态都为 `Running`，Ctrl+C 停止并继续！ - -## 访问 TiDB 集群 - -从 pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get svc -n tidb --watch -``` - -如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 - -要访问 Kubernetes 集群中的 TiDB 服务，可以在 TiDB 服务和 Google Cloud Shell 之间建立一条隧道。建议这种方式只用于调试，因为如果 Google Cloud Shell 重启，隧道不会自动重新建立。要建立隧道： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n tidb port-forward svc/demo-tidb 4000:4000 &>/tmp/port-forward.log & -``` - -在 Cloud Shell 上运行： - -{{< copyable "shell-regular" >}} - -``` shell -sudo apt-get install -y mysql-client && \ -mysql -h 127.0.0.1 -u root -P 4000 -``` - -在 MySQL 终端中输入一条 MySQL 命令： - -{{< copyable "sql" >}} - -``` sql -select tidb_version(); -``` - -如果用 Helm 安装的过程中没有指定密码，现在可以设置： - -{{< copyable "sql" >}} - -``` sql -SET PASSWORD FOR 'root'@'%' = ''; -``` - -> **注意：** -> -> 这条命令中包含一些特殊字符，Google Cloud Shell 无法自动填充，你需要手动复制、粘贴到控制台中。 - -恭喜，你已经启动并运行一个兼容 MySQL 的分布式 TiDB 数据库！ - -## 扩容 TiDB 集群 - -我们可以一键扩容 TiDB 集群。如下命令可以扩容 TiKV： - -{{< copyable "shell-regular" >}} - -``` shell -helm upgrade demo pingcap/tidb-cluster --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd,tikv.replicas=5 --version= -``` - -TiKV 的 Pod 数量从 3 增加到了 5。可以通过下面命令查看： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get po -n tidb -``` - -## 访问 Grafana 面板 - -要访问 Grafana 面板，可以在 Grafana 服务和 shell 之间建立一条隧道，可以使用如下命令： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n tidb port-forward svc/demo-grafana 3000:3000 &>/dev/null & -``` - -在 Cloud Shell 中，点击 Web Preview 按钮并输入端口 3000，将打开一个新的浏览器标签页访问 Grafana 面板。或者也可以在新浏览器标签或者窗口中直接访问 URL：。 - -如果没有使用 Cloud Shell，可以在浏览器中访问 `localhost:3000`。 - -## 销毁 TiDB 集群 - -如果不再需要这个 TiDB 集群，可以使用下面命令删除集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm delete demo --purge -``` - -上面的命令只会删除运行的 Pod，但是数据还会保留。如果你不再需要那些数据，可以执行下面的命令清除数据和动态创建的持久化磁盘： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl delete pvc -n tidb -l app.kubernetes.io/instance=demo,app.kubernetes.io/managed-by=tidb-operator && \ -kubectl get pv -l app.kubernetes.io/namespace=tidb,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` - -## 删除 Kubernetes 集群 - -实验结束后，可以使用如下命令删除 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud container clusters delete tidb -``` - -## 更多信息 - -我们还提供简单的[基于 Terraform 的部署方案](/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md)。 diff --git a/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md b/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md deleted file mode 100644 index 0383ca8a3d8c..000000000000 --- a/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: 使用 kind 在 Kubernetes 上部署 TiDB 集群 -summary: 使用 kind 在 Kubernetes 上部署 TiDB 集群。 -category: how-to -aliases: ['/docs-cn/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-dind/'] ---- - -# 使用 kind 在 Kubernetes 上部署 TiDB 集群 - -本文介绍了如何在个人电脑（Linux 或 MacOS）上采用 [kind](https://kind.sigs.k8s.io/) 方式在 Kubernetes 上部署 [TiDB Operator](https://github.com/pingcap/tidb-operator) 和 TiDB 集群。 - -kind 通过使用 Docker 容器作为集群节点模拟出一个本地的 Kubernetes 集群。kind 的设计初衷是为了在本地进行 Kubernetes 集群的一致性测试。Kubernetes 集群版本取决于 kind 使用的镜像，你可以指定任一镜像版本用于集群节点，并在 [Docker hub](https://hub.docker.com/r/kindest/node/tags) 中找到想要部署的 Kubernetes 版本。 - -> **警告：** -> -> 对于生产环境，不要使用此方式进行部署。 - -## 环境准备 - -部署前，请确认软件、资源等满足如下需求： - -- 资源需求：CPU 2 核+、内存 4G+ - - > **注意：** - > - > 对于 macOS 系统，需要给 Docker 分配 2 核+ CPU 和 4G+ 内存。详情请参考 [Mac 上配置 Docker](https://docs.docker.com/docker-for-mac/#advanced)。 - -- [Docker](https://docs.docker.com/install/)：版本 >= 17.03 -- [Helm Client](https://helm.sh/docs/intro/install/)：版本 >= 2.9.0 并且 < 3.0.0 -- [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)：版本 >= 1.10，建议 1.13 或更高版本 - - > **注意：** - > - > 不同 kubectl 版本，输出可能略有不同。 - -- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/)：版本 >= 0.4.0 -- [net.ipv4.ip_forward](https://linuxconfig.org/how-to-turn-on-off-ip-forwarding-in-linux) 需要被设置为 `1` - -## 第 1 步：通过 kind 部署 Kubernetes 集群 - -首先确认 Docker 进程正常运行，然后你可以通过脚本命令快速启动一个本地的 Kubernetes 集群。 - -1. Clone 官方提供的代码： - - {{< copyable "shell-regular" >}} - - ``` shell - git clone --depth=1 https://github.com/pingcap/tidb-operator && \ - cd tidb-operator - ``` - -2. 运行脚本，在本地创建一个 Kubernetes 集群： - - {{< copyable "shell-regular" >}} - - ``` shell - hack/kind-cluster-build.sh - ``` - - > **注意：** - > - > 通过该脚本启动的 Kubernetes 集群默认有 6 个节点，Kubernetes 版本默认为 v1.12.8，每个节点默认挂载数为 9。你可以通过启动参数去修改这些参数： - > - > {{< copyable "shell-regular" >}} - > - > ```shell - > hack/kind-cluster-build.sh --nodeNum 2 --k8sVersion v1.14.6 --volumeNum 3 - > ``` - -3. 集群创建完毕后，执行下列命令将 kubectl 的默认配置文件切换到 `kube-config`，从而连接到该本地 Kubernetes 集群： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG="$(kind get kubeconfig-path)" - ``` - -4. 查看该 kubernetes 集群信息： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl cluster-info - ``` - - 输出如下类似信息： - - ``` shell - Kubernetes master is running at https://127.0.0.1:50295 - KubeDNS is running at https://127.0.0.1:50295/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy - ``` - -5. 查看该 Kubernetes 集群的 `storageClass`： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl get storageClass - ``` - - 输出如下类似信息： - - ``` shell - NAME PROVISIONER AGE - local-storage kubernetes.io/no-provisioner 7m50s - standard (default) kubernetes.io/host-path 8m29s - ``` - -## 第 2 步：在 Kubernetes 集群上部署 TiDB Operator - -1. 安装 Helm 并配置 PingCAP 官方 chart 仓库，参考 [使用 Helm](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 小节中的操作。 - -2. 部署 TiDB Operator，参考 [安装 TiDB Operator](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md#安装-tidb-operator) 小节中的操作。 - -## 第 3 步：在 Kubernetes 集群中部署 TiDB 集群 - -参考[在标准 Kubernetes 上部署 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md#部署-tidb-集群)中的操作。 - -## 访问数据库和监控面板 - -通过 `kubectl port-forward` 暴露服务到主机，可以访问 TiDB 集群。命令中的端口格式为：`<主机端口>:`。 - -- 通过 MySQL 客户端访问 TiDB - - 在访问 TiDB 集群之前，请确保已安装 MySQL client。 - - 1. 使用 kubectl 暴露 TiDB 服务端口： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/-tidb 4000:4000 --namespace= - ``` - - > **注意：** - > - > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:4000 -> 4000`。测试完成后按 `Ctrl + C` 停止代理并退出。 - - 2. 然后，通过 MySQL 客户端访问 TiDB，打开一个**新**终端标签或窗口，执行下面的命令： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -- 查看监控面板 - - 1. 使用 kubectl 暴露 Grafana 服务端口： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/-grafana 3000:3000 --namespace= - ``` - - > **注意：** - > - > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:3000 -> 3000`。测试完成后按 `Ctrl + C` 停止代理并退出。 - - 2. 然后，在浏览器中打开 访问 Grafana 监控面板： - - - 默认用户名：admin - - 默认密码：admin - - > **注意：** - > - > 如果你不是在本地 PC 而是在远程主机上部署的 kind 环境，可能无法通过 localhost 访问远程主机的服务。 - > - > 如果使用 kubectl 1.13 或者更高版本，可以在执行 `kubectl port-forward` 命令时添加 `--address 0.0.0.0` 选项，在 `0.0.0.0` 暴露端口而不是默认的 `127.0.0.1`： - > - > {{< copyable "shell-regular" >}} - > - > ``` - > kubectl port-forward --address 0.0.0.0 -n tidb svc/-grafana 3000:3000 - > ``` - > - > 然后，在浏览器中打开 `http://<远程主机 IP>:3000` 访问 Grafana 监控面板。 - -## 删除 TiDB 集群 与 Kubernetes 集群 - -删除本地 TiDB 集群可参考[销毁 TiDB 集群](/v3.0/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md#销毁-kubernetes-上的-tidb-集群)。 - -通过下面命令删除该 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -kind delete cluster -``` diff --git a/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md b/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md deleted file mode 100644 index 242fd0c231b7..000000000000 --- a/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md +++ /dev/null @@ -1,299 +0,0 @@ ---- -title: 在 Minikube 集群上部署 TiDB 集群 -summary: 在 Minikube 集群上部署 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/get-started/deploy-tidb-from-kubernetes-minikube/'] ---- - -# 在 Minikube 集群上部署 TiDB 集群 - -[Minikube](https://kubernetes.io/docs/setup/minikube/) 可以让你在个人电脑上的虚拟机中创建一个 Kubernetes 集群，支持 macOS、Linux 和 Windows 系统。本文介绍如何在 Minikube 集群上部署 TiDB 集群。 - -> **警告：** -> -> - 对于生产环境，不要使用此方式进行部署。 -> -> - 尽管 Minikube 支持通过 `--vm-driver=none` 选项使用主机 Docker 而不使用虚拟机，但是目前尚没有针对 TiDB Operator 做过全面的测试，可能会无法正常工作。如果你想在不支持虚拟化的系统（例如，VPS）上试用 TiDB Operator，可以考虑使用 [kind](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)。 - -## 安装 Minikube 并启动 Kubernetes 集群 - -参考[安装 Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/)，在你的机器上安装 Minikube 1.0.0+。 - -安装完 Minikube 后，可以执行下面命令启动一个 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -minikube start -``` - -对于中国大陆用户，可以使用国内 gcr.io mirror 仓库，例如 `registry.cn-hangzhou.aliyuncs.com/google_containers`。 - -{{< copyable "shell-regular" >}} - -``` shell -minikube start --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers -``` - -或者给 Docker 配置 HTTP/HTTPS 代理。 - -将下面命令中的 `127.0.0.1:1086` 替换为你自己的 HTTP/HTTPS 代理地址： - -{{< copyable "shell-regular" >}} - -``` shell -minikube start --docker-env https_proxy=http://127.0.0.1:1086 \ - --docker-env http_proxy=http://127.0.0.1:1086 -``` - -> **注意：** -> -> 由于 Minikube 通过虚拟机（默认）运行，`127.0.0.1` 是虚拟机本身，有些情况下你可能想要使用你的主机的实际 IP。 - -参考 [Minikube setup](https://kubernetes.io/docs/setup/minikube/) 查看配置虚拟机和 Kubernetes 集群的更多选项。 - -## 安装 kubectl 并访问集群 - -Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/user-guide/kubectl/)，可以让你执行命令访问 Kubernetes 集群。 - -参考 [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) 安装和配置 kubectl。 - -kubectl 安装完成后，测试 Minikube Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl cluster-info -``` - -## 安装 TiDB Operator 并运行 TiDB 集群 - -### 安装 Helm - -[Helm](https://helm.sh/) 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 - -{{< copyable "shell-regular" >}} - -``` shell -curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash -``` - -安装 helm tiller： - -{{< copyable "shell-regular" >}} - -``` shell -helm init -``` - -如果无法访问 gcr.io，你可以尝试 mirror 仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm init --upgrade --tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:$(helm version --client --short | grep -Eo 'v[0-9]\.[0-9]+\.[0-9]+') -``` - -安装完成后，执行 `helm version` 会同时显示客户端和服务端组件版本： - -{{< copyable "shell-regular" >}} - -``` shell -helm version -``` - -输出类似如下内容： - -``` -Client: &version.Version{SemVer:"v2.13.1", -GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} -Server: &version.Version{SemVer:"v2.13.1", -GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} -``` - -如果只显示客户端版本，表示 `helm` 无法连接到服务端。通过 `kubectl` 查看 tiller pod 是否在运行： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n kube-system get pods -l app=helm -``` - -### 添加 Helm 仓库 - -Helm 仓库 (`https://charts.pingcap.org/`) 存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。可使用以下命令添加仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo add pingcap https://charts.pingcap.org/ && \ -helm repo list -``` - -然后可以查看可用的 chart： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo update && \ -helm search tidb-cluster -l && \ -helm search tidb-operator -l -``` - -### 在 Kubernetes 集群上安装 TiDB Operator - -> **注意：** -> -> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 - -克隆 tidb-operator 代码库并安装 TiDB Operator： - -{{< copyable "shell-regular" >}} - -``` shell -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator && \ -kubectl apply -f ./manifests/crd.yaml && \ -helm install pingcap/tidb-operator --name tidb-operator --namespace tidb-admin --version= -``` - -然后，可以通过如下命令查看 TiDB Operator 的启动情况： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb-admin -o wide --watch -``` - -如果无法访问 gcr.io（Pod 由于 ErrImagePull 无法启动），可以尝试从 mirror 仓库中拉取 kube-scheduler 镜像。可以通过以下命令升级 tidb-operator： - -{{< copyable "shell-regular" >}} - -``` shell -helm upgrade tidb-operator pingcap/tidb-operator --namespace tidb-admin --set \ - scheduler.kubeSchedulerImageName=registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler --version= -``` - -如果 tidb-scheduler 和 tidb-controller-manager 都进入 running 状态，你可以继续下一步启动一个 TiDB 集群。 - -### 启动 TiDB 集群 - -通过下面命令启动 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster --name demo --set \ - schedulerName=default-scheduler,pd.storageClassName=standard,tikv.storageClassName=standard,pd.replicas=1,tikv.replicas=1,tidb.replicas=1 --version= -``` - -可以通过下面命令观察集群的状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace default -l app.kubernetes.io/instance=demo -o wide --watch -``` - -通过 Ctrl+C 停止观察。 - -## 测试 TiDB 集群 - -测试 TiDB 集群之前，请确保已经安装 MySQL 客户端。从 Pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get svc --watch -``` - -如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 - -按照以下步骤访问 TiDB 集群： - -1. 转发本地端口到 TiDB 端口。 - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/demo-tidb 4000:4000 - ``` - -2. 在另一个终端窗口中，通过 MySQL 客户端访问 TiDB： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -uroot - ``` - - 或者可以直接执行 SQL 命令： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -uroot -e 'select tidb_version();' - ``` - -## 监控 TiDB 集群 - -按照以下步骤监控 TiDB 集群状态： - -1. 转发本地端口到 Grafana 端口。 - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/demo-grafana 3000:3000 - ``` - -2. 打开浏览器，通过 `http://localhost:3000` 访问 Grafana。 - - 或者，Minikube 提供了 `minikube service` 的方式暴露 Grafana 服务，可以更方便的接入。 - - {{< copyable "shell-regular" >}} - - ``` shell - minikube service demo-grafana - ``` - - 上述命令会自动搭建代理并在浏览器中打开 Grafana。 - -### 删除 TiDB 集群 - -通过下面命令删除 demo 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm delete --purge demo -``` - -更新 demo 集群使用的 PV 的 reclaim 策略为 Delete： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pv -l app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` - -删除 PVC： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl delete pvc -l app.kubernetes.io/managed-by=tidb-operator -``` - -## FAQ - -### Minikube 上的 TiDB 集群不响应或者响应非常慢 - -Minikube 虚拟机默认配置为 2048 MB 内存和 2 个 CPU。可以在 `minikube start` 时通过`--memory` 和 `--cpus` 选项为其分配更多资源。注意，为了使配置修改生效，你需要重新创建 Minikube 虚拟机。 - -{{< copyable "shell-regular" >}} - -``` shell -minikube delete && \ -minikube start --cpus 4 --memory 4096 ... -``` diff --git a/v3.0/tidb-in-kubernetes/initialize-cluster.md b/v3.0/tidb-in-kubernetes/initialize-cluster.md deleted file mode 100644 index 01545b2ef82b..000000000000 --- a/v3.0/tidb-in-kubernetes/initialize-cluster.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Kubernetes 上的集群初始化配置 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/configure/initialize-cluster/'] ---- - -# Kubernetes 上的集群初始化配置 - -本文介绍如何对 Kubernetes 上的集群进行初始化配置完成初始化账号和密码设置，以及批量自动执行 SQL 语句对数据库进行初始化。 - -> **注意：** -> -> 以下功能只在第一次创建集群时有作用，集群创建之后再设置或修改不会生效。 - -## 设置初始化账号和密码 - -集群创建时默认会创建 `root` 账号，但是密码为空，这会带来一些安全性问题。可以通过如下步骤为 `root` 账号设置初始密码： - -1. 创建 `Namespace` - - 在部署集群前通过下面命令创建 [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create namespace - ``` - -2. 创建 `Secret` - - 在部署集群前通过下面命令创建 [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) 指定 root 账号密码： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic tidb-secret --from-literal=root= --namespace= - ``` - - 如果希望能自动创建其它用户，可以在上面命令里面再加上其他用户的 username 和 password，例如： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic tidb-secret --from-literal=root= --from-literal=developer= --namespace= - ``` - - 该命令会创建 `root` 和 `developer` 两个用户的密码，存到 `tidb-secret` 的 Secret 里面。并且创建的普通用户 `developer` 默认只有 `USAGE` 权限，其他权限请在 `tidb.initSql` 中设置。 - -3. 设置允许访问 TiDB 的主机 - - 在部署集群前可以通过 `tidb.permitHost` 配置项来设置允许访问 TiDB 的主机 **host_name**。如果不设置，则允许所有主机访问。详情请参考 [Mysql GRANT host name](https://dev.mysql.com/doc/refman/5.7/en/grant.html)。 - - ``` - tidb: - passwordSecretName: tidb-secret - permitHost: - ``` - -4. 部署集群 - - 创建 Secret 之后，通过下面命令部署集群： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster -f values.yaml --name= --namespace= --version= - ``` - - 以上命令指定 `tidb.passwordSecretName` 之后，创建的集群会自动创建一个初始化的 Job，该 Job 在集群创建过程中会尝试利用提供的 secret 给 root 账号创建初始密码，并且创建其它账号和密码，如果指定了的话。注意由于 Job 创建时 TiDB 集群的 Pod 还没完全创建，所以可能会失败几次，初始化完成后 Pod 状态会变成 Completed。之后通过 MySQL 客户端登录时需要指定这里设置的密码。 - -## 批量执行初始化 SQL 语句 - -集群在初始化过程还可以自动执行 `tidb.initSql` 中的 SQL 语句用于初始化，该功能可以用于默认给集群创建一些 database 或者 table，并且执行一些用户权限管理类的操作。例如如下设置会在集群创建完成后自动创建名为 `app` 的 database，并且赋予 `developer` 账号对 `app` 的所有管理权限： - -{{< copyable "yaml" >}} - -```yaml -tidb: - passwordSecretName: tidb-secret - initSql: |- - CREATE DATABASE app; - GRANT ALL PRIVILEGES ON app.* TO 'developer'@'%'; -``` - -将上述内容保存到 `values.yaml` 文件，然后执行下面命令部署集群： - -{{< copyable "shell-regular" >}} - -```bash -helm install pingcap/tidb-cluster -f values.yaml --name= --namespace= --version= -``` - -> **注意：** -> -> 目前没有对 initSql 做校验，尽管也可以在 initSql 里面创建账户和设置密码，但这种方式会将密码以明文形式存到 initializer Job 对象上，不建议这么做。 diff --git a/v3.0/tidb-in-kubernetes/maintain/auto-failover.md b/v3.0/tidb-in-kubernetes/maintain/auto-failover.md deleted file mode 100644 index 7ba480556625..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/auto-failover.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群故障自动转移 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/maintain/tidb-in-kubernetes/auto-failover/'] ---- - -# Kubernetes 上的 TiDB 集群故障自动转移 - -故障自动转移是指在 TiDB 集群的某些节点出现故障时，TiDB Operator 会自动添加一个节点，保证 TiDB 集群的高可用，类似于 K8s 的 `Deployment` 行为。 - -由于 TiDB Operator 基于 `StatefulSet` 来管理 Pod，但 `StatefulSet` 在某些 Pod 发生故障时不会自动创建新节点来替换旧节点，所以，TiDB Operator 扩展了 `StatefulSet` 的这种行为，添加了 Auto Failover 功能。 - -Auto Failover 功能在 TiDB Operator 中默认关闭。部署 TiDB Operator 时，可通过设置 `charts/tidb-operator/values.yaml` 文件的 `controllerManager.autoFailover` 为 `true` 开启该功能： - -```yaml -controllerManager: - serviceAccount: tidb-controller-manager - logLevel: 2 - replicas: 1 - resources: - limits: - cpu: 250m - memory: 150Mi - requests: - cpu: 80m - memory: 50Mi - # autoFailover is whether tidb-operator should auto failover when failure occurs - autoFailover: true - # pd failover period default(5m) - pdFailoverPeriod: 5m - # tikv failover period default(5m) - tikvFailoverPeriod: 5m - # tidb failover period default(5m) - tidbFailoverPeriod: 5m -``` - -`pdFailoverPeriod`、`tikvFailoverPeriod` 和 `tidbFailoverPeriod` 默认均为 5 分钟，它们的含义是在确认实例故障后的等待超时时间，超过这个时间后，TiDB Operator 就开始做自动的故障转移。 - -## 实现原理 - -TiDB 集群有 PD、TiKV 和 TiDB 三个组件，它们的故障转移策略有所不同，本节将详细介绍这三种策略。 - -### PD 故障转移策略 - -假设 PD 集群有 3 个节点，如果一个 PD 节点挂掉超过 5 分钟（`pdFailoverPeriod` 可配置），TiDB Operator 首先会将这个 PD 节点下线，然后再添加一个新的 PD 节点。此时会有 4 个 Pod 同时存在，待挂掉的 PD 节点恢复后，TiDB Operator 会将新启动的节点删除掉，恢复成原来的 3 个节点。 - -### TiKV 故障转移策略 - -当一个 TiKV 节点无法正常工作后，该节点的状态会变为 `Disconnected`，30 分钟（通过 `pd.config` 文件中 `[schedule]` 部分的 `max-store-down-time = "30m"` 来配置）后会变成 `Down` 状态，TiDB Operator 会在此基础上再等待 5 分钟（`tikvFailoverPeriod` 可配置），如果该 TiKV 节点仍不能恢复，就会新起一个 TiKV 节点。待挂掉的 TiKV 节点恢复后，TiDB Operator 不会自动删除新起的节点，用户需要手动减少 TiKV 节点，恢复成原来的节点数。操作方法是将该 TiKV 节点从 `TidbCluster` 对象的 `status.tikv.failureStores` 字段中删除： - -{{< copyable "shell-regular" >}} - -```shell -kubectl edit tc -n -``` - -``` -... -status - tikv: - failureStores: - "1": - podName: cluster1-tikv-0 - storeID: "1" - "2": - podName: cluster1-tikv-1 - storeID: "2" -... -``` - -`cluster1-tikv-0` 节点恢复后，将其删除后变为： - -``` -... -status - tikv: - failureStores: - "2": - podName: cluster1-tikv-1 - storeID: "2" -... -``` - -### TiDB 故障转移策略 - -假设 TiDB 集群有 3 个节点，TiDB 的故障转移策略跟 Kubernetes 中的 `Deployment` 的是一致的。如果一个 TiDB 节点挂掉超过 5 分钟（`tidbFailoverPeriod` 可配置），TiDB Operator 会添加一个新的 TiDB 节点。此时会有 4 个 Pod 同时存在，待挂掉的 TiDB 节点恢复后，TiDB Operator 会将新启动的节点删除掉，恢复成原来的 3 个节点。 diff --git a/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md b/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md deleted file mode 100644 index bbbbc45a53f4..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群备份恢复 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/maintain/tidb-in-kubernetes/backup-and-restore/'] ---- - -# Kubernetes 上的 TiDB 集群备份与恢复 - -这篇文档详细描述了如何对 Kubernetes 上的 TiDB 集群进行数据备份和数据恢复。 - -Kubernetes 上的 TiDB 集群支持两种备份策略： - -* [全量备份](#全量备份)（定时执行或 Ad-hoc）：使用 [`mydumper`](/v3.0/reference/tools/mydumper.md) 获取集群的逻辑备份； -* [增量备份](#增量备份)：使用 [`TiDB Binlog`](/v3.0/reference/tidb-binlog/overview.md) 将 TiDB 集群的数据实时复制到其它数据库中或实时获得增量数据备份； - -目前，Kubernetes 上的 TiDB 集群只对 `mydumper` 获取的全量备份数据提供自动化的数据恢复操作。恢复 `TiDB-Binlog` 获取的增量数据需要手动进行。 - -## 全量备份 - -全量备份使用 `mydumper` 来获取 TiDB 集群的逻辑备份数据。全量备份任务会创建一个 PVC ([PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)) 来存储数据。 - -默认配置下，备份任务使用 PV ([Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes)) 来存储备份数据。你也可以通过修改配置将备份数据存储到 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，在这种情况下，数据在上传到对象存储前，会临时存储在 PV 中。参考 [Kubernetes 上的 TiDB 集群备份配置](/v3.0/tidb-in-kubernetes/reference/configuration/backup.md) 了解所有的配置选项。 - -你可以配置一个定时执行的全量备份任务，也可以临时执行一个全量备份任务。 - -### 定时全量备份 - -定时全量备份是一个与 TiDB 集群一同创建的定时任务，它会像 `crontab` 任务那样周期性地运行。 - -你可以修改 TiDB 集群的 `values.yaml` 文件来配置定时全量备份： - -1. 将 `scheduledBackup.create` 设置为 `true`； -2. 将 `scheduledBackup.storageClassName` 设置为用于存储数据的 PV 的 `storageClass`； - - > **注意：** - > - > 你必须将定时全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 - -3. 按照 [Cron](https://en.wikipedia.org/wiki/Cron) 格式设置 `scheduledBackup.schedule` 来定义任务的执行周期与时间； -4. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) 该用户必须拥有数据备份所需的数据库相关权限，同时，将 `scheduledBackup.secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -5. 通过 `helm install` 创建一个配置了定时全量备份的 TiDB 集群，针对现有集群，则使用 `helm upgrade` 为集群打开定时全量备份： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -### Ad-hoc 全量备份 - -Ad-hoc 全量备份封装在 `pingcap/tidb-backup` 这个 Helm chart 中。根据 `values.yaml` 文件中的 `mode` 配置，该 chart 可以执行全量备份或数据恢复。我们会在[数据恢复](#数据恢复)一节中描述如何执行数据恢复。 - -你可以通过下面的步骤执行一次 Ad-hoc 全量备份： - -1. 修改 `values.yaml`： - * 将 `clusterName` 设置为目标 TiDB 集群名字； - * 将 `mode` 设置为 `backup`； - * 将 `storage.className` 设置为用于存储数据的 PV 的 `storageClass`； - * 根据数据量调整 `storage.size`； - - > **注意：** - > - > 你必须将 Ad-hoc 全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 - -2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -3. 使用下面的命令执行一次 Ad-hoc 全量备份： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-backup --name= --namespace= -f values.yaml --version= - ``` - -### 查看备份 - -对于存储在 PV 中的备份，你可以使用下面的命令进行查看： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pvc -n -l app.kubernetes.io/component=backup,pingcap.com/backup-cluster-name= -``` - -假如你将数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你可以用这些存储系统自带的图形界面或命令行工具查看全量备份。 - -## 数据恢复 - - 使用 `pingcap/tidb-backup` 这个 Helm chart 进行数据恢复，步骤如下： - -1. 修改 `values.yaml`： - * 将 `clusterName` 设置为目标 TiDB 集群名； - * 将 `mode` 设置为 `restore`； - * 将 `name` 设置为用于恢复的备份名字（你可以参考[查看备份](#查看备份)来寻找可用的备份数据）。假如备份数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你必须保证这些存储的相关配置与执行[全量备份](#全量备份)时一致。 -2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`，假如你在[全量备份](#全量备份)时已经创建了该 Secret，则可以跳过这步）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -3. 恢复数据： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-backup --namespace= --name= -f values.yaml --version= - ``` - -## 增量备份 - -增量备份使用 [TiDB Binlog](/v3.0/reference/tidb-binlog/overview.md) 工具从 TiDB 集群收集 Binlog，并提供实时备份和向其它数据库的实时同步能力。 - -有关 Kubernetes 上运维 TiDB Binlog 的详细指南，可参阅 [TiDB Binlog](/v3.0/tidb-in-kubernetes/maintain/tidb-binlog.md)。 - -### Pump 缩容 - -缩容 Pump 需要先将单个 Pump 节点从集群中下线，然后运行 `helm upgrade` 命令将对应的 Pump Pod 删除，并对每个节点重复上述步骤。 - -1. 下线 Pump 节点： - - 假设现在有 3 个 Pump 节点，我们需要下线第 3 个 Pump 节点，将 `` 替换成 `2`，操作方式如下（`` 为当前 TiDB 的版本）。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl run offline-pump- --image=pingcap/tidb-binlog: --namespace= --restart=OnFailure -- /binlogctl -pd-urls=http://-pd:2379 -cmd offline-pump -node-id -pump-:8250 - ``` - - 然后查看 Pump 的日志输出，输出 `pump offline, please delete my pod` 后即可确认该节点已经成功下线。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl logs -f -n -pump- - ``` - -2. 删除对应的 Pump Pod： - - 修改 `values.yaml` 文件中 `binlog.pump.replicas` 为 `2`，然后执行如下命令来删除 Pump Pod： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` diff --git a/v3.0/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md b/v3.0/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md deleted file mode 100644 index 6f867b99d59f..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: 销毁 Kubernetes 上的 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/maintain/tidb-in-kubernetes/destroy-cluster/'] ---- - -# 销毁 Kubernetes 上的 TiDB 集群 - -本文描述了如何销毁 Kubernetes 集群上的 TiDB 集群 - -要销毁 TiDB 集群，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -helm delete --purge -``` - -上述命令只是删除运行的 Pod，数据仍然会保留。如果你不再需要那些数据，可以通过下面命令清除数据： - -> **警告：** -> -> 下列命令会彻底删除数据，务必考虑清楚再执行。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pvc -n -l app.kubernetes.io/instance=,app.kubernetes.io/managed-by=tidb-operator -``` - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pv -l app.kubernetes.io/namespace=,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance= -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` diff --git a/v3.0/tidb-in-kubernetes/maintain/kubernetes-node.md b/v3.0/tidb-in-kubernetes/maintain/kubernetes-node.md deleted file mode 100644 index d788c8a556ed..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/kubernetes-node.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: 维护 TiDB 集群所在的 Kubernetes 节点 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/maintain/tidb-in-kubernetes/k8s-node-for-tidb/'] ---- - -# 维护 TiDB 集群所在的 Kubernetes 节点 - -TiDB 是高可用数据库，可以在部分数据库节点下线的情况下正常运行，因此，我们可以安全地对底层 Kubernetes 节点进行停机维护。在具体操作时，针对 PD、TiKV 和 TiDB 实例的不同特性，我们需要采取不同的操作策略。 - -本文档将详细介绍如何对 Kubernetes 节点进行临时或长期的维护操作。 - -环境准备： - -- [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [`tkctl`](/v3.0/tidb-in-kubernetes/reference/tools/tkctl.md) -- [`jq`](https://stedolan.github.io/jq/download/) - -> **注意：** -> -> 长期维护节点前，需要保证 Kubernetes 集群的剩余资源足够运行 TiDB 集群。 - -## 维护 PD 和 TiDB 实例所在节点 - -PD 和 TiDB 实例的迁移较快，可以采取主动驱逐实例到其它节点上的策略进行节点维护： - -1. 检查待维护节点上是否有 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pod --all-namespaces -o wide | grep - ``` - - 假如存在 TiKV 实例，请参考[维护 TiKV 实例所在节点](#维护-tikv-实例所在节点)。 - -2. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl cordon - ``` - -3. 使用 `kubectl drain` 命令将待维护节点上的数据库实例迁移到其它节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl drain --ignore-daemonsets --delete-local-data - ``` - - 运行后，该节点上的 TiDB 实例会自动迁移到其它可用节点上，PD 实例则会在 5 分钟后触发自动故障转移补齐节点。 - -4. 此时，假如希望下线该 Kubernetes 节点，则可以将该节点删除： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete node - ``` - - 假如希望恢复 Kubernetes 节点，则需要在恢复节点后确认其健康状态： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl get node - ``` - - 观察到节点进入 `Ready` 状态后，继续操作。 - -5. 使用 `kubectl uncordon` 命令解除节点的调度限制： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl uncordon - ``` - -6. 观察 Pod 是否全部恢复正常运行： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl get -n $namespace pod -o wide - ``` - - 或者： - - {{< copyable "shell-regular" >}} - - ```sql - watch tkctl get all - ``` - - Pod 恢复正常运行后，操作结束。 - -## 维护 TiKV 实例所在节点 - -TiKV 实例迁移较慢，并且会对集群造成一定的数据迁移负载，因此在维护 TiKV 实例所在节点前，需要根据维护需求选择操作策略： - -- 假如是维护短期内可恢复的节点，则不需要迁移 TiKV 节点，在维护结束后原地恢复节点； -- 假如是维护短期内不可恢复的节点，则需要规划 TiKV 的迁移工作。 - -### 维护短期内可恢复的节点 - -针对短期维护，我们可以通过调整 PD 集群的 `max-store-down-time` 配置来增大集群所允许的 TiKV 实例下线时间，在此时间内维护完毕并恢复 Kubernetes 节点后，所有该节点上的 TiKV 实例会自动恢复。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward svc/-pd 2379:2379 -``` - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -d config set max-store-down-time 10m -``` - -调整 `max-store-down-time` 到合理的值后，后续的操作方式与[维护 PD 和 TiDB 实例所在节点](#维护-pd-和-tidb-实例所在节点)相同。 - -### 维护短期内不可恢复的节点 - -针对短期内不可恢复的节点维护，如节点长期下线等情形，需要使用 `pd-ctl` 主动通知 TiDB 集群下线对应的 TiKV 实例，再手动解除 TiKV 实例与该节点的绑定。 - -1. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl cordon - ``` - -2. 查看待维护节点上的 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - tkctl get -A tikv | grep - ``` - -3. 使用 `pd-ctl` 主动下线 TiKV 实例。 - - > **注意：** - > - > 下线 TiKV 实例前，需要保证集群中剩余的 TiKV 实例数不少于 PD 配置中的 TiKV 数据副本数（配置项：`max-replicas`）。假如不符合该条件，需要先操作扩容 TiKV。 - - 查看 TiKV 实例的 `store-id`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get tc -ojson | jq '.status.tikv.stores | .[] | select ( .podName == "" ) | .id' - ``` - - 下线实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward svc/-pd 2379:2379 - ``` - - {{< copyable "shell-regular" >}} - - ```shell - pd-ctl -d store delete - ``` - -4. 等待 store 状态（`state_name`）转移为 `Tombstone`： - - {{< copyable "shell-regular" >}} - - ```shell - watch pd-ctl -d store - ``` - -5. 解除 TiKV 实例与节点本地盘的绑定。 - - 查询 Pod 使用的 `PesistentVolumeClaim`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n pod -ojson | jq '.spec.volumes | .[] | select (.name == "tikv") | .persistentVolumeClaim.claimName' - ``` - - 删除该 `PesistentVolumeClaim`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pvc - ``` - -6. 删除 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pod - ``` - -7. 观察该 TiKV 实例是否正常调度到其它节点上： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 假如待维护节点上还有其它 TiKV 实例，则重复同样的操作步骤直到所有的 TiKV 实例都迁移到其它节点上。 - -8. 确认节点不再有 TiKV 实例后，再逐出节点上的其它实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl drain --ignore-daemonsets --delete-local-data - ``` - -9. 再次确认节点不再有任何 TiKV、TiDB 和 PD 实例运行： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pod --all-namespaces | grep - ``` - -10. 最后（可选），假如是长期下线节点，建议将节点从 Kubernetes 集群中删除： - - {{< copyable "shell-regular" >}} - - ```shell - kuebctl delete node - ``` - -至此，操作完成。 diff --git a/v3.0/tidb-in-kubernetes/maintain/lightning.md b/v3.0/tidb-in-kubernetes/maintain/lightning.md deleted file mode 100644 index 3c58f193607c..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/lightning.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 恢复 Kubernetes 上的 TiDB 集群数据 -summary: 使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据。 -category: how-to ---- - -# 恢复 Kubernetes 上的 TiDB 集群数据 - -本文介绍了如何使用 [TiDB Lightning](https://github.com/pingcap/tidb-lightning) 快速恢复 Kubernetes 上的 TiDB 集群数据。 - -TiDB Lightning 包含两个组件：tidb-lightning 和 tikv-importer。在 Kubernetes 上，tikv-importer 位于 TiDB 集群的 Helm chart 内，被部署为一个副本数为 1 (`replicas=1`) 的 `StatefulSet`；tidb-lightning 位于单独的 Helm chart 内，被部署为一个 `Job`。 - -为了使用 TiDB Lightning 恢复数据，tikv-importer 和 tidb-lightning 都必须分别部署。 - -## 部署 tikv-importer - -tikv-importer 可以在一个现有的 TiDB 集群上启用，或者在新建 TiDB 集群时启用。 - -* 在新建一个 TiDB 集群时启用 tikv-importer： - - 1. 在 `tidb-cluster` 的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 - - 2. 部署该集群。 - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster --name= --namespace= -f values.yaml --version= - ``` - -* 配置一个现有的 TiDB 集群以启用 tikv-importer： - - 1. 在该 TiDB 集群的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 - - 2. 升级该 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -## 部署 tidb-lightning - -1. 配置 TiDB Lightning - - 使用如下命令获得 TiDB Lightning 的默认配置。 - - {{< copyable "shell-regular" >}} - - ```shell - helm inspect values pingcap/tidb-lightning --version= > tidb-lightning-values.yaml - ``` - - tidb-lightning Helm chart 支持恢复本地或远程的备份数据。 - - * 本地模式 - - 本地模式要求 Mydumper 备份数据位于其中一个 Kubernetes 节点上。要启用该模式，你需要将 `dataSource.local.nodeName` 设置为该节点名称，将 `dataSource.local.hostPath` 设置为 Mydumper 备份数据目录路径，该路径中需要包含名为 `metadata` 的文件。 - - * 远程模式 - - 与本地模式不同，远程模式需要使用 [rclone](https://rclone.org) 将 Mydumper 备份 tarball 文件从网络存储中下载到 PV 中。远程模式能在 rclone 支持的任何云存储下工作，目前已经有以下存储进行了相关测试：[Google Cloud Storage (GCS)](https://cloud.google.com/storage/)、[AWS S3](https://aws.amazon.com/s3/) 和 [Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/)。 - - 1. 确保 `values.yaml` 中的 `dataSource.local.nodeName` 和 `dataSource.local.hostPath` 被注释掉。 - - 2. 新建一个包含 rclone 配置的 `Secret`。rclone 配置示例如下。一般只需要配置一种云存储。有关其他的云存储，请参考 [rclone 官方文档](https://rclone.org/)。 - - {{< copyable "" >}} - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: cloud-storage-secret - type: Opaque - stringData: - rclone.conf: | - [s3] - type = s3 - provider = AWS - env_auth = false - access_key_id = - secret_access_key = - region = us-east-1 - [ceph] - type = s3 - provider = Ceph - env_auth = false - access_key_id = - secret_access_key = - endpoint = - region = :default-placement - [gcs] - type = google cloud storage - # 该服务账号必须被授予 Storage Object Viewer 角色。 - # 该内容可以通过 `cat | jq -c .` 命令获取。 - service_account_credentials = - ``` - - 使用你的实际配置替换上述配置中的占位符，并将该文件存储为 `secret.yaml`。然后通过 `kubectl apply -f secret.yaml -n ` 命令创建该 `Secret`。 - - 3. 将 `dataSource.remote.storageClassName` 设置为 Kubernetes 集群中现有的一个存储类型。 - -2. 部署 TiDB Lightning - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-lightning --name= --namespace= --set failFast=true -f tidb-lightning-values.yaml --version= - ``` - -当 TiDB Lightning 未能成功恢复数据时，不能简单地直接重启进程，必须进行**手动干预**，否则将很容易出现错误。因此，tidb-lightning 的 `Job` 重启策略被设置为 `Never`。 - -> **注意：** -> -> 目前，即使数据被成功恢复，TiDB Lightning 也会[报出非零错误码并退出](https://github.com/pingcap/tidb-lightning/pull/230)，这会导致 `Job` 失败。因此，数据恢复成功与否需要通过查看 tidb-lightning pod 的日志进行确认。 - -如果 TiDB Lightning 未能成功恢复数据，需要采用以下步骤进行手动干预： - -1. 运行 `kubectl delete job -n -tidb-lightning`，删除 lightning `Job`。 - -2. 运行 `helm template pingcap/tidb-lightning --name --set failFast=false -f tidb-lightning-values.yaml | kubectl apply -n -f -`，重新创建禁用 `failFast` 的 lightning `Job`。 - -3. 当 lightning pod 重新运行时，在 lightning 容器中执行 `kubectl exec -it -n sh` 命令。 - -4. 运行 `cat /proc/1/cmdline`，获得启动脚本。 - -5. 参考[故障排除指南](/v3.0/how-to/troubleshoot/tidb-lightning.md#tidb-lightning-troubleshooting)，对 lightning 进行诊断。 - -## 销毁 TiDB Lightning - -目前，TiDB Lightning 只能在线下恢复数据。当恢复过程结束、TiDB 集群需要向外部应用提供服务时，可以销毁 TiDB Lightning 以节省开支。 - -删除 tikv-importer 的步骤： - -1. 在 TiDB 集群 chart 的 `values.yaml` 文件中将 `importer.create` 设置为 `false`。 - -2. 然后运行 `helm upgrade pingcap/tidb-cluster -f values.yaml`。 - -删除 tidb-lightning 的方法： - -* 运行 `helm delete --purge`。 diff --git a/v3.0/tidb-in-kubernetes/maintain/log-collecting.md b/v3.0/tidb-in-kubernetes/maintain/log-collecting.md deleted file mode 100644 index 9fffd1e9e7e2..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/log-collecting.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: 日志收集 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/maintain/tidb-in-kubernetes/log-collecting/'] ---- - -# 日志收集 - -系统与程序的运行日志对排查问题以及实现一些自动化操作可能非常有用。本文将简要说明收集 TiDB 及相关组件日志的方法。 - -## TiDB 与 Kubernetes 组件运行日志 - -通过 TiDB Operator 部署的 TiDB 各组件默认将日志输出在容器的 `stdout` 和 `stderr` 中。对于 Kubernetes 而言，这些日志会被存放在宿主机的 `/var/log/containers` 目录下，并且文件名中包含了 Pod 和容器名称等信息。因此，对容器中应用的日志收集可以直接在宿主机上完成。 - -如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将 Kubernetes 所在的宿主机上的 `/var/log/containers/*.log` 文件加入采集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。 - -Kubernetes 官方文档中提供了 [ElasticSearch](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/) 和 [Stackdriver](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/) 两种日志收集方案可供参考。 - -常见的可用于收集 Kubernetes 日志的开源工具有： - -- [Fluentd](https://www.fluentd.org/) -- [Fluent-bit](https://fluentbit.io/) -- [Filebeat](https://www.elastic.co/products/beats/filebeat) -- [Logstash](https://www.elastic.co/products/logstash) - -收集到的日志通常可以汇总存储在某一特定的服务器上，或存放到 ElasticSearch 等专用的存储、分析系统当中。 - -一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。 - -如果不通过单独的日志收集工具汇总日志，你也可以直接使用 `kubectl` 工具查看某个容器的运行日志，但这一方法无法查看已销毁容器的日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -n -``` - -若需查看容器重启之前的日志，可以在执行上述命令时添加 `-p` 参数。 - -如果需要从多个 Pod 获取日志，可以使用 [`stern`](https://github.com/wercker/stern)： - -{{< copyable "shell-regular" >}} - -```shell -stern -n tidb -c slowlog -``` - -## TiDB 慢查询日志 - -对于 3.0 之前的版本，在默认情况下，TiDB 会打印慢查询日志到标准输出，和应用日志混在一起。 - -- 如果 TiDB 版本 <= v2.1.7，你可以通过关键字 `SLOW_QUERY` 来筛选慢查询日志，例如： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl logs -n | grep SLOW_QUERY - ``` - -- 如果 TiDB 版本 >= v2.1.8，由于慢查询日志格式发生变化，不太方便分离慢查询日志，建议参考下面内容配置 `separateSlowLog: true` 单独查看慢查询日志。 - -在一些情况下，你可能希望使用一些工具或自动化系统对日志内容进行分析、处理。TiDB 各组件的应用日志使用了[统一的日志格式](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)以便于程序解析，但由于慢查询日志使用的是与 MySQL 兼容的多行格式，与应用日志混在一起时可能会对解析造成困难。 - -如果希望将慢查询日志和应用日志区分开，可以在 `values.yaml` 文件中配置 `separateSlowLog` 参数，将慢查询日志输出到一个专用的旁路容器中，这样慢查询日志在宿主机上会被输出到一个单独的文件，和应用日志分开。 - -修改方法为编辑 `values.yaml` 文件，将 `separateSlowLog` 参数设置为 `true`： - -```yaml -# Uncomment the following line to enable separate output of the slow query log - separateSlowLog: true -``` - -之后再运行 `helm upgrade` 使配置生效，然后可以通过名为 `slowlog` 的 sidecar 容器查看慢查询日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -n -c slowlog -``` - -对于 3.0 及更新的版本，TiDB 将慢查询日志输出到独立的 `slowlog.log` 文件中，并且 `separateSlowLog` 是默认开启的，所以可以直接通过 sidecar 容器查看慢查询日志，无需额外设置。 - -> **注意：** -> -> 慢查询日志的格式与 MySQL 的慢查询日志相同，但由于 TiDB 自身的特点，其中的一些具体字段可能存在差异，因此解析 MySQL 慢查询日志的工具不一定能完全兼容 TiDB 的慢查询日志。 - -## 系统日志 - -系统日志可以通过常规方法在 Kubernetes 宿主机上收集，如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将相关服务器和日志文件添加到收集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。 - -上文提到的几种常见日志收集工具均支持对系统日志的收集，一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。 diff --git a/v3.0/tidb-in-kubernetes/maintain/restart.md b/v3.0/tidb-in-kubernetes/maintain/restart.md deleted file mode 100644 index c17138c41384..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/restart.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: 重启 Kubernetes 上的 TiDB 集群 -summary: 了解如何重启 Kubernetes 集群上的 TiDB 集群。 -category: how-to ---- - -# 重启 Kubernetes 上的 TiDB 集群 - -本文描述了如何强制重启 Kubernetes 集群上的 TiDB 集群，包括重启某个 Pod，重启某个组件的所有 Pod 和重启 TiDB 集群的所有 Pod。 - -> **注意：** -> -> TiDB Operator v1.0.x 版本只支持强制重启 Pod。 -> -> - 在强制重启 PD Pod 过程中，如果被重启的 PD Pod 是 Leader，重启过程不会自动迁移 Leader，这会导致 PD 服务短时间中断。 -> - 在强制重启 TiKV Pod 过程中，不会自动迁移 TiKV 的 Region Leader，会导致访问对应数据的请求异常。 -> - 在强制重启 TiDB Pod 过程中，会导致访问对应 TiDB 的请求失败。 - -## 强制重启某个 Pod - -要强制重启某个 Pod，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pod -n -``` - -## 强制重启某个组件的所有 Pod - -通过以下命令可以列出组件目前有哪些 Pod： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pod -n -l app.kubernetes.io/component= -``` - -要强制重启某个组件的所有 Pod，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pod -n -l app.kubernetes.io/component= -``` - -把 `` 分别替换为 `pd`、`tidb`、`tikv`，可以分别强制重启 `PD`、`TiDB`、`TiKV` 组件所有 Pod。 - -## 强制重启 TiDB 集群的所有 Pod - -通过以下命令可以列出 TiDB 集群目前有哪些 Pod，包括 `monitor`、`discovery` 等： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pod -n -l app.kubernetes.io/instance= -``` - -要强制重启 TiDB 集群的所有 Pod，包括 `monitor`、`discovery` 等，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pod -n -l app.kubernetes.io/instance= -``` diff --git a/v3.0/tidb-in-kubernetes/maintain/tidb-binlog.md b/v3.0/tidb-in-kubernetes/maintain/tidb-binlog.md deleted file mode 100644 index 5e4de9610913..000000000000 --- a/v3.0/tidb-in-kubernetes/maintain/tidb-binlog.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB Binlog 运维 -summary: 了解如何在 Kubernetes 上运维 TiDB 集群的 TiDB Binlog。 -category: how-to ---- - -# TiDB Binlog 运维 - -本文档介绍如何在 Kubernetes 上运维 TiDB 集群的 [TiDB Binlog](/v3.0/reference/tidb-binlog/overview.md)。 - -## 运维准备 - -- [部署 TiDB Operator](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md)； -- [安装 Helm](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 并配置 PingCAP 官方 chart 仓库。 - -## 启用 TiDB 集群的 TiDB Binlog - -默认情况下，TiDB Binlog 在 TiDB 集群中处于禁用状态。若要创建一个启用 TiDB Binlog 的 TiDB 集群，或在现有 TiDB 集群中启用 TiDB Binlog，可根据以下步骤进行操作： - -1. 按照以下说明修改 `values.yaml` 文件： - - * 将 `binlog.pump.create` 的值设为 `true`。 - * 将 `binlog.drainer.create` 的值设为 `true`。 - * 将 `binlog.pump.storageClassName` 和 `binlog.drainer.storageClassName` 设为所在 Kubernetes 集群上可用的 `storageClass`。 - * 将 `binlog.drainer.destDBType` 设为所需的下游存储类型。 - - TiDB Binlog 支持三种下游存储类型： - - * PersistenceVolume：默认的下游存储类型。可通过修改 `binlog.drainer.storage` 来为 `drainer` 配置大 PV。 - - * 与 MySQL 兼容的数据库：通过将 `binlog.drainer.destDBType` 设置为 `mysql` 来启用。同时，必须在 `binlog.drainer.mysql` 中配置目标数据库的地址和凭据。 - - * Apache Kafka：通过将 `binlog.drainer.destDBType` 设置为 `kafka` 来启用。同时，必须在 `binlog.drainer.kafka` 中配置目标集群的 zookeeper 地址和 Kafka 地址。 - -2. 为 TiDB 与 Pump 组件设置亲和性和反亲和性： - - > **注意：** - > - > 如果在生产环境中开启 TiDB Binlog，建议为 TiDB 与 Pump 组件设置亲和性和反亲和性。如果在内网测试环境中尝试使用开启 TiDB Binlog，可以跳过此步。 - - 默认情况下，TiDB 的 affinity 亲和性设置为 `{}`。由于目前 Pump 组件与 TiDB 组件默认并非一一对应，当启用 TiDB Binlog 时，如果 Pump 与 TiDB 组件分开部署并出现网络隔离，而且 TiDB 组件还开启了 `ignore-error`，则会导致 TiDB 丢失 Binlog。推荐通过亲和性特性将 TiDB 组件与 Pump 部署在同一台 Node 上，同时通过反亲和性特性将 Pump 分散在不同的 Node 上，每台 Node 上至多仅需一个 Pump 实例。 - - > **注意：** - > - > `` 需要替换为目标 `tidb-cluster` 的 Helm release name。 - - * 将 `tidb.affinity` 按照如下设置： - - ```yaml - tidb: - affinity: - podAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "pump" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - ``` - - * 将 `binlog.pump.affinity` 按照如下设置： - - ```yaml - binlog: - pump: - affinity: - podAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "tidb" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "pump" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - ``` - -3. 创建一个新的 TiDB 集群或更新现有的集群： - - * 创建一个启用 TiDB Binlog 的 TiDB 新集群： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster --name= --namespace= --version= -f - ``` - - * 更新现有的 TiDB 集群以启用 TiDB Binlog： - - > **注意：** - > - > 如果设置了 TiDB 组件的亲和性，那么更新现有的 TiDB 集群将引起 TiDB 集群中的 TiDB 组件滚动更新。 - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster --version= -f - ``` - -## 部署多个 drainer - -默认情况下，仅创建一个下游 drainer。可安装 `tidb-drainer` Helm chart 来为 TiDB 集群部署多个 drainer，示例如下： - -1. 确保 PingCAP Helm 库是最新的： - - {{< copyable "shell-regular" >}} - - ```shell - helm repo update - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm search tidb-drainer -l - ``` - -2. 获取默认的 `values.yaml` 文件以方便自定义： - - {{< copyable "shell-regular" >}} - - ```shell - helm inspect values pingcap/tidb-drainer --version= > values.yaml - ``` - -3. 修改 `values.yaml` 文件以指定源 TiDB 集群和 drainer 的下游数据库。示例如下： - - ```yaml - clusterName: example-tidb - clusterVersion: v3.0.0 - storageClassName: local-storage - storage: 10Gi - config: | - detect-interval = 10 - [syncer] - worker-count = 16 - txn-batch = 20 - disable-dispatch = false - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - safe-mode = false - db-type = "tidb" - [syncer.to] - host = "slave-tidb" - user = "root" - password = "" - port = 4000 - ``` - - `clusterName` 和 `clusterVersion` 必须匹配所需的源 TiDB 集群。 - - 有关完整的配置详细信息，请参阅 [Kubernetes 上的 TiDB Binlog Drainer 配置](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-drainer.md)。 - -4. 部署 drainer： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-drainer --name= --namespace= --version= -f values.yaml - ``` - - > **注意：** - > - > 该 chart 必须与源 TiDB 集群安装在相同的命名空间中。 diff --git a/v3.0/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md b/v3.0/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md deleted file mode 100644 index b3cc90bdd7e0..000000000000 --- a/v3.0/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群监控 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/monitor/tidb-in-kubernetes/'] ---- - -# Kubernetes 上的 TiDB 集群监控 - -基于 Kubernetes 环境部署的 TiDB 集群监控可以大体分为两个部分：对 TiDB 集群本身的监控、对 Kubernetes 集群及 TiDB Operator 的监控。本文将对两者进行简要说明。 - -## TiDB 集群的监控 - -TiDB 通过 Prometheus 和 Grafana 监控 TiDB 集群。在通过 TiDB Operator 创建新的 TiDB 集群时，对于每个 TiDB 集群，会同时创建、配置一套独立的监控系统，与 TiDB 集群运行在同一 Namespace，包括 Prometheus 和 Grafana 两个组件。 - -监控数据默认没有持久化，如果由于某些原因监控容器重启，已有的监控数据会丢失。可以在 `values.yaml` 中设置 `monitor.persistent` 为 `true` 来持久化监控数据。开启此选项时应将 `storageClass` 设置为一个当前集群中已有的存储，并且此存储应当支持将数据持久化，否则仍然会存在数据丢失的风险。 - -在 [TiDB 集群监控](/v3.0/how-to/monitor/monitor-a-cluster.md)中有一些监控系统配置的细节可供参考。 - -### 查看监控面板 - -可以通过 `kubectl port-forward` 查看监控面板： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-grafana 3000:3000 &>/tmp/portforward-grafana.log -``` - -然后在浏览器中打开 [http://localhost:3000](http://localhost:3000)，默认用户名和密码都为 `admin`。 - -Grafana 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.grafana.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问面板。 - -如果不需要使用 Grafana，可以在部署时在 `values.yaml` 中将 `monitor.grafana.create` 设置为 `false` 来节省资源。这一情况下需要使用其他已有或新部署的数据可视化工具直接访问监控数据来完成可视化。 - -### 访问监控数据 - -对于需要直接访问监控数据的情况，可以通过 `kubectl port-forward` 来访问 Prometheus： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-prometheus 9090:9090 &>/tmp/portforward-prometheus.log -``` - -然后在浏览器中打开 [http://localhost:9090](http://localhost:9090)，或通过客户端工具访问此地址即可。 - -Prometheus 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.prometheus.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问监控数据。 - -## Kubernetes 的监控 - -随集群部署的 TiDB 监控只关注 TiDB 本身各组件的运行情况，并不包括对容器资源、宿主机、Kubernetes 组件和 TiDB Operator 等的监控。对于这些组件或资源的监控，需要在整个 Kubernetes 集群维度部署监控系统来实现。 - -### 宿主机监控 - -对宿主机及其资源的监控与传统的服务器物理资源监控相同。 - -如果在你的现有基础设施中已经有针对物理服务器的监控系统，只需要通过常规方法将 Kubernetes 所在的宿主机添加到现有监控系统中即可；如果没有可用的监控系统，或者希望部署一套独立的监控系统用于监控 Kubernetes 所在的宿主机，也可以使用你熟悉的任意监控系统。 - -新部署的监控系统可以运行于独立的服务器、直接运行于 Kubernetes 所在的宿主机，或运行于 Kubernetes 集群内，不同部署方式除在安装配置与资源利用上存在少许差异，在使用上并没有重大区别。 - -常见的可用于监控服务器资源的开源监控系统有： - -- [CollectD](https://collectd.org/) -- [Nagios](https://www.nagios.org/) -- [Prometheus](http://prometheus.io/) & [node_exporter](https://github.com/prometheus/node_exporter) -- [Zabbix](https://www.zabbix.com/) - -一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的监控解决方案可以选择。 - -我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 在 Kubernetes 集群内部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于 Kubernetes 自身组件的监控。 - -### Kubernetes 组件监控 - -对 Kubernetes 组件的监控可以参考[官方文档](https://kubernetes.io/docs/tasks/debug-application-cluster/resource-usage-monitoring/)提供的方案，也可以使用其他兼容 Kubernetes 的监控系统来进行。 - -一些云服务商可能提供了自己的 Kubernetes 组件监控方案，一些专门的性能监控服务商也有各自的 Kubernetes 集成方案可以选择。 - -由于 TiDB Operator 实际上是运行于 Kubernetes 中的容器，选择任一可以覆盖对 Kubernetes 容器状态及资源进行监控的监控系统即可覆盖对 TiDB Operator 的监控，无需再额外部署监控组件。 - -我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于对宿主机资源的监控。 - -## 报警配置 - -### TiDB 集群报警 - -在随 TiDB 集群部署 Prometheus 时，会自动导入一些默认的报警规则，可以通过浏览器访问 Prometheus 的 Alerts 页面查看当前系统中的所有报警规则和状态。 - -我们目前暂不支持报警规则的自定义配置，如果确实需要修改报警规则，可以手动下载 charts 进行修改。 - -默认的 Prometheus 和报警配置不能发送报警消息，如需发送报警消息，可以使用任意支持 Prometheus 报警的工具与其集成。推荐通过 [AlertManager](https://prometheus.io/docs/alerting/alertmanager/) 管理与发送报警消息。 - -如果在你的现有基础设施中已经有可用的 AlertManager 服务，可以在 `values.yaml` 文件中修改 `monitor.prometheus.alertmanagerURL` 配置其地址供 Prometheus 使用；如果没有可用的 AlertManager 服务，或者希望部署一套独立的服务，可以参考官方的[说明](https://github.com/prometheus/alertmanager)部署。 - -### Kubernetes 报警 - -如果使用 Prometheus Operator 部署针对 Kubernetes 宿主机和服务的监控，会默认配置一些告警规则，并且会部署一个 AlertManager 服务，具体的设置方法请参阅 [kube-prometheus](https://github.com/coreos/kube-prometheus) 的说明。 - -如果使用其他的工具或服务对 Kubernetes 宿主机和服务进行监控，请查阅该工具或服务提供商的对应资料。 diff --git a/v3.0/tidb-in-kubernetes/reference/configuration/backup.md b/v3.0/tidb-in-kubernetes/reference/configuration/backup.md deleted file mode 100644 index e36630f704a8..000000000000 --- a/v3.0/tidb-in-kubernetes/reference/configuration/backup.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群备份配置 -category: reference -aliases: ['/docs-cn/v3.0/reference/configuration/tidb-in-kubernetes/cluster-configuration/'] ---- - -# Kubernetes 上的 TiDB 集群备份配置 - -`tidb-backup` 是一个用于 Kubernetes 上 TiDB 集群备份和恢复的 Helm Chart。本文详细介绍了 `tidb-backup` 的可配置参数。 - -## `mode` - -+ 运行模式 -+ 默认："backup" -+ 可选值为 `backup`（备份集群数据）和 `restore`（恢复集群数据） - -## `clusterName` - -+ 目标集群名字 -+ 默认："demo" -+ 指定要从哪个集群进行备份或将数据恢复到哪个集群中 - -## `name` - -+ 备份名 -+ 默认值："fullbackup-"，`` 是备份的开始时间，精确到分钟 -+ 备份名用于区分不同的备份数据 - -## `secretName` - -+ 访问目标集群时使用的凭据 -+ 默认："backup-secret" -+ 该 Kubernetes Secret 中需要存储目标集群的登录用户名和密码，你可以通过以下命令来创建这个 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user=root --from-literal=password= - ``` - -## `storage.className` - -+ Kubernetes StorageClass -+ 默认："local-storage" -+ 备份任务需要绑定一个持久卷 (Persistent Volume, PV) 来永久或临时存储备份数据，`StorageClass` 用于声明持久卷使用的存储类型，需要确保该 `StorageClass` 在 Kubernetes 集群中存在。 - -## `storage.size` - -+ 持久卷的空间大小 -+ 默认："100Gi" - -## `backupOptions` - -+ 备份参数 -+ 默认："--chunk-filesize=100" -+ 为备份数据时使用的 [Mydumper](https://github.com/maxbube/mydumper/blob/master/docs/mydumper_usage.rst#options) 指定额外的运行参数 - -## `restoreOptions` - -+ 恢复参数 -+ 默认："-t 16" -+ 为恢复数据时使用的 [Loader](/v3.0/reference/tools/loader.md) 指定额外的运行参数 - -## `gcp.bucket` - -+ Google Cloud Storage 的 bucket 名字 -+ 默认："" -+ 用于存储备份数据到 Google Cloud Storage 上 - -> **注意：** -> -> 一旦设置了 `gcp` 下的任何参数，备份和恢复就会使用 Google Cloud Storage 进行数据存储。也就是说，假如要设置 `gcp` 下的参数，就需要保证所有 `gcp` 相关参数都得到正确配置，否则会造成备份恢复失败。 - -## `gcp.secretName` - -+ 访问 GCP 时使用的凭据 -+ 默认："" -+ 该 Kubernetes Secret 中需要存储 GCP 的 Service Account 凭据，你可以参考 [Google Cloud Documentation](https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually) 来下载凭据文件，然后通过下面的命令创建 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic gcp-backup-secret -n --from-file=./credentials.json - ``` - -## `ceph.endpoint` - -+ Ceph 对象存储的 Endpoint -+ 默认："" -+ 用于访问 Ceph 对象存储 - -> **注意：** -> -> 一旦设置了 `ceph` 下的任何参数，备份和恢复就会使用 Ceph 对象存储进行数据存储。也就是说，假如要设置 `ceph` 下的参数，就需要保证所有 `ceph` 相关参数都得到正确配置，否则会造成备份恢复失败。 - -## `ceph.bucket` - -+ Ceph 对象存储的 bucket 名字 -+ 默认："" -+ 用于存储数据到 Ceph 对象存储上 - -## `ceph.secretName` - -+ 访问 Ceph 对象存储时使用的凭据 -+ 默认："" -+ 该 Kubernetes Secret 中需要存储访问 Ceph 时使用的 `access_key` 和 `secret_key`。可使用如下命令来创建这个 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic ceph-backup-secret -n --from-literal=access_key= --from-literal=secret_key= - ``` diff --git a/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md b/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md deleted file mode 100644 index 6b7d48c43809..000000000000 --- a/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: Kubernetes 上的持久化存储类型配置 -category: reference -aliases: ['/docs-cn/v3.0/tidb-in-kubernetes/reference/configuration/local-pv/'] ---- - -# Kubernetes 上的持久化存储类型配置 - -TiDB 集群中 PD、TiKV、监控等组件以及 TiDB Binlog 和备份等工具都需要使用将数据持久化的存储。Kubernetes 上的数据持久化需要使用 [PersistentVolume (PV)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)。Kubernetes 提供多种[存储类型](https://kubernetes.io/docs/concepts/storage/volumes/)，主要分为两大类： - -* 网络存储 - - 存储介质不在当前节点，而是通过网络方式挂载到当前节点。一般有多副本冗余提供高可用保证，在节点出现故障时，对应网络存储可以再挂载到其它节点继续使用。 - -* 本地存储 - - 存储介质在当前节点，通常能提供比网络存储更低的延迟，但没有多副本冗余，一旦节点出故障，数据就有可能丢失。如果是 IDC 服务器，节点故障可以一定程度上对数据进行恢复，但公有云上使用本地盘的虚拟机在节点故障后，数据是**无法找回**的。 - -PV 一般由系统管理员或 volume provisioner 自动创建，PV 与 Pod 是通过 [PersistentVolumeClaim (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) 进行关联的。普通用户在使用 PV 时并不需要直接创建 PV，而是通过 PVC 来申请使用 PV，对应的 volume provisioner 根据 PVC 创建符合要求的 PV，并将 PVC 与该 PV 进行绑定。 - -> **警告：** -> -> 为了数据安全，任何情况下都不要直接删除 PV，除非对 volume provisioner 原理非常清楚。 - -## TiDB 集群推荐存储类型 - -TiKV 自身借助 Raft 实现了数据复制，出现节点故障后，PD 会自动进行数据调度补齐缺失的数据副本，同时 TiKV 要求存储有较低的读写延迟，所以生产环境强烈推荐使用本地 SSD 存储。 - -PD 同样借助 Raft 实现了数据复制，但作为存储集群元信息的数据库，并不是 IO 密集型应用，所以一般本地普通 SAS 盘或网络 SSD 存储（例如 AWS 上 gp2 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）就可以满足要求。 - -监控组件以及 TiDB Binlog、备份等工具，由于自身没有做多副本冗余，所以为保证可用性，推荐用网络存储。其中 TiDB Binlog 的 pump 和 drainer 组件属于 IO 密集型应用，需要较低的读写延迟，所以推荐用高性能的网络存储（例如 AWS 上的 io1 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）。 - -在利用 TiDB Operator 部署 TiDB 集群或者备份工具的时候，需要持久化存储的组件都可以通过 values.yaml 配置文件中对应的 `storageClassName` 设置存储类型。不设置时默认都使用 `local-storage`。 - -## 网络 PV 配置 - -Kubernetes 1.11 及以上的版本支持[网络 PV 的动态扩容](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/)，但用户需要为相应的 `StorageClass` 开启动态扩容支持。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl patch storageclass -p '{"allowVolumeExpansion": true}' -``` - -开启动态扩容后，通过下面方式对 PV 进行扩容： - -1. 修改 PVC 大小 - - 假设之前 PVC 大小是 10 Gi，现在需要扩容到 100 Gi - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pvc -n -p '{"spec": {"resources": {"requests": {"storage": "100Gi"}}}' - ``` - -2. 查看 PV 扩容成功 - - 扩容成功后，通过 `kubectl get pvc -n ` 显示的大小仍然是初始大小，但查看 PV 大小会显示已经扩容到预期的大小。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pv | grep - ``` - -## 本地 PV 配置 - -Kubernetes 当前支持静态分配的本地存储。可使用 [local-static-provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner) 项目中的 `local-volume-provisioner` 程序创建本地存储对象。创建流程如下： - -1. 参考 Kubernetes 提供的[操作文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md)，在集群节点中预分配本地存储。 - -2. 部署 `local-volume-provisioner` 程序。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml - ``` - - 通过下面命令查看 Pod 和 PV 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l app=local-volume-provisioner && \ - kubectl get pv | grep local-storage - ``` - - `local-volume-provisioner` 会为发现目录 (discovery directory) 下的每一个挂载点创建一个 PV。注意，在 GKE 上，默认只能创建大小为 375 GiB 的本地卷。 - -更多信息，可参阅 [Kubernetes 本地存储](https://kubernetes.io/docs/concepts/storage/volumes/#local)和 [local-static-provisioner 文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner#overview)。 - -### 最佳实践 - -- Local PV 的路径是本地存储卷的唯一标示符。为了保证唯一性并避免冲突，推荐使用设备的 UUID 来生成唯一的路径 -- 如果想要 IO 隔离，建议每个存储卷使用一块物理盘会比较恰当，在硬件层隔离 -- 如果想要容量隔离，建议每个存储卷一个分区或者每个存储卷使用一块物理盘来实现 - -更多信息，可参阅 local-static-provisioner 的[最佳实践文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/best-practices.md)。 - -### 示例 - -如果监控、TiDB Binlog、备份等组件都使用本地盘存储数据，可以挂载普通 SAS 盘，并分别创建不同的 `StorageClass` 供这些组件使用，具体操作如下： - -- 给监控数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/disks` 目录，后续创建 `local-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量。1 个目录会对应创建 1 个 PV。每个 TiDB 集群的监控数据会使用 1 个 PV。 - -- 给 TiDB Binlog 和备份数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/backup` 目录，后续创建 `backup-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量、每个集群内的 Pump 数量及备份方式。1 个目录会对应创建 1 个 PV。每个 Pump 会使用 1 个 PV，每个 drainer 会使用 1 个 PV，每次 [Ad-hoc 全量备份](/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md#ad-hoc-全量备份)会使用 1 个 PV，所有[定时全量备份](/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md#定时全量备份)会共用 1 个 PV。 - -- 给 PD 数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/sharedssd` 目录，后续创建 `shared-ssd-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量及每个集群内的 PD 数量。1 个目录会对应创建 1 个 PV。每个 PD 会使用一个 PV。 - -- 给 TiKV 数据使用的盘，可通过[普通挂载](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#use-a-whole-disk-as-a-filesystem-pv)方式将盘挂载到 `/mnt/ssd` 目录，后续创建 `ssd-storage` `StorageClass`。 - -盘挂载完成后，需要根据上述磁盘挂载情况修改 [`local-volume-provisioner` yaml 文件](https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml)，配置发现目录并创建必要的 `StorageClass`。以下是根据上述挂载修改的 yaml 文件示例： - -``` -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "local-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "ssd-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "shared-ssd-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "backup-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: local-provisioner-config - namespace: kube-system -data: - nodeLabelsForPV: | - - kubernetes.io/hostname - storageClassMap: | - shared-ssd-storage: - hostDir: /mnt/sharedssd - mountDir: /mnt/sharedssd - ssd-storage: - hostDir: /mnt/ssd - mountDir: /mnt/ssd - local-storage: - hostDir: /mnt/disks - mountDir: /mnt/disks - backup-storage: - hostDir: /mnt/backup - mountDir: /mnt/backup ---- - -...... - - volumeMounts: - - ...... - - - mountPath: /mnt/ssd - name: local-ssd - mountPropagation: "HostToContainer" - - mountPath: /mnt/sharedssd - name: local-sharedssd - mountPropagation: "HostToContainer" - - mountPath: /mnt/disks - name: local-disks - mountPropagation: "HostToContainer" - - mountPath: /mnt/backup - name: local-backup - mountPropagation: "HostToContainer" - volumes: - - ...... - - - name: local-ssd - hostPath: - path: /mnt/ssd - - name: local-sharedssd - hostPath: - path: /mnt/sharedssd - - name: local-disks - hostPath: - path: /mnt/disks - - name: local-backup - hostPath: - path: /mnt/backup -...... - -``` - -最后通过 `kubectl apply` 命令部署 `local-volume-provisioner` 程序。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml -``` - -后续创建 TiDB 集群或备份等组件的时候，再配置相应的 `StorageClass` 供其使用。 - -## 数据安全 - -一般情况下 PVC 在使用完删除后，与其绑定的 PV 会被 provisioner 清理回收再放入资源池中被调度使用。为避免数据意外丢失，可在全局配置 `StorageClass` 的回收策略 (reclaim policy) 为 `Retain` 或者只将某个 PV 的回收策略修改为 `Retain`。`Retain` 模式下，PV 不会自动被回收。 - -* 全局配置 - - `StorageClass` 的回收策略一旦创建就不能再修改，所以只能在创建时进行设置。如果创建时没有设置，可以再创建相同 provisioner 的 `StorageClass`，例如 GKE 上默认的 pd 类型的 `StorageClass` 默认保留策略是 `Delete`，可以再创建一个名为 `pd-standard` 的保留策略是 `Retain` 的存储类型，并在创建 TiDB 集群时将相应组件的 `storageClassName` 修改为 `pd-standard`。 - - {{< copyable "" >}} - - ```yaml - apiVersion: storage.k8s.io/v1 - kind: StorageClass - metadata: - name: pd-standard - parameters: - type: pd-standard - provisioner: kubernetes.io/gce-pd - reclaimPolicy: Retain - volumeBindingMode: Immediate - ``` - -* 配置单个 PV - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' - ``` - -> **注意：** -> -> TiDB Operator 默认会自动将 PD 和 TiKV 的 PV 保留策略修改为 `Retain` 以确保数据安全。 - -PV 保留策略是 `Retain` 时，如果确认某个 PV 的数据可以被删除，需要通过下面的操作来删除 PV 以及对应的数据： - -1. 删除 PV 对应的 PVC 对象： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete pvc --namespace= - ``` - -2. 设置 PV 的保留策略为 `Delete`，PV 会被自动删除并回收： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - ``` - -要了解更多关于 PV 的保留策略可参考[修改 PV 保留策略](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/)。 diff --git a/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md b/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md deleted file mode 100644 index a8c4e6387827..000000000000 --- a/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群配置 -category: reference ---- - -# Kubernetes 上的 TiDB 集群配置 - -本文介绍 Kubernetes 上 TiDB 集群的配置参数、资源配置，以及容灾配置。 - -## 配置参数 - -TiDB Operator 使用 Helm 部署和管理 TiDB 集群。通过 Helm 获取的配置文件默认提供了基本的配置，通过这个基本配置，可以快速启动一个 TiDB 集群。但是如果用户需要特殊配置或是用于生产环境，则需要根据以下配置参数列表手动配置对应的配置项。 - -> **注意：** -> -> 下文用 `values.yaml` 指代要修改的 TiDB 集群配置文件。 - -| 参数名 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `rbac.create` | 是否启用 Kubernetes 的 RBAC | `true` | -| `clusterName` | TiDB 集群名，默认不设置该变量，`tidb-cluster` 会直接用执行安装时的 `ReleaseName` 代替 | `nil` | -| `extraLabels` | 添加额外的 labels 到 `TidbCluster` 对象 (CRD) 上，参考：[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) | `{}` | -| `schedulerName` | TiDB 集群使用的调度器 | `tidb-scheduler` | -| `timezone` | TiDB 集群默认时区 | `UTC` | -| `pvReclaimPolicy` | TiDB 集群使用的 PV (Persistent Volume)的 reclaim policy | `Retain` | -| `services[0].name` | TiDB 集群对外暴露服务的名字 | `nil` | -| `services[0].type` | TiDB 集群对外暴露服务的类型，(从 `ClusterIP`、`NodePort`、`LoadBalancer` 中选择) | `nil` | -| `discovery.image` | TiDB 集群 PD 服务发现组件的镜像，该组件用于在 PD 集群第一次启动时，为各个 PD 实例提供服务发现功能以协调启动顺序 | `pingcap/tidb-operator:v1.0.0-beta.3` | -| `discovery.imagePullPolicy` | PD 服务发现组件镜像的拉取策略 | `IfNotPresent` | -| `discovery.resources.limits.cpu` | PD 服务发现组件的 CPU 资源限额 | `250m` | -| `discovery.resources.limits.memory` | PD 服务发现组件的内存资源限额 | `150Mi` | -| `discovery.resources.requests.cpu` | PD 服务发现组件的 CPU 资源请求 | `80m` | -| `discovery.resources.requests.memory` | PD 服务发现组件的内存资源请求 | `50Mi` | -| `enableConfigMapRollout` | 是否开启 TiDB 集群自动滚动更新。如果启用，则 TiDB 集群的 ConfigMap 变更时，TiDB 集群自动更新对应组件。该配置只在 tidb-operator v1.0 及以上版本才支持 | `false` | -| `pd.config` | 配置文件格式的 PD 的配置，请参考 [`pd/conf/config.toml`](https://github.com/pingcap/pd/blob/master/conf/config.toml) 查看默认 PD 配置文件（选择对应 PD 版本的 tag），可以参考 [PD 配置文件描述](/v3.0/reference/configuration/pd-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置** | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
`[replication]`
`location-labels = ["region", "zone", "rack", "host"]`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"`
    `[replication]`
    `location-labels = ["region", "zone", "rack", "host"]` | -| `pd.replicas` | PD 的 Pod 数 | `3` | -| `pd.image` | PD 镜像 | `pingcap/pd:v3.0.0-rc.1` | -| `pd.imagePullPolicy` | PD 镜像的拉取策略 | `IfNotPresent` | -| `pd.logLevel` | PD 日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[log]`
`level = "info"` | `info` | -| `pd.storageClassName` | PD 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `pd.maxStoreDownTime` | `pd.maxStoreDownTime` 指一个 store 节点断开连接多长时间后状态会被标记为 `down`，当状态变为 `down` 后，store 节点开始迁移数据到其它 store 节点
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[schedule]`
`max-store-down-time = "30m"` | `30m` | -| `pd.maxReplicas` | `pd.maxReplicas` 是 TiDB 集群的数据的副本数
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[replication]`
`max-replicas = 3` | `3` | -| `pd.resources.limits.cpu` | 每个 PD Pod 的 CPU 资源限额 | `nil` | -| `pd.resources.limits.memory` | 每个 PD Pod 的内存资源限额 | `nil` | -| `pd.resources.limits.storage` | 每个 PD Pod 的存储容量限额 | `nil` | -| `pd.resources.requests.cpu` | 每个 PD Pod 的 CPU 资源请求 | `nil` | -| `pd.resources.requests.memory` | 每个 PD Pod 的内存资源请求 | `nil` | -| `pd.resources.requests.storage` | 每个 PD Pod 的存储容量请求 | `1Gi` | -| `pd.affinity` | `pd.affinity` 定义 PD 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `pd.nodeSelector` | `pd.nodeSelector` 确保 PD Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `pd.tolerations` | `pd.tolerations` 应用于 PD Pods，允许 PD Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `pd.annotations` | 为 PD Pods 添加特定的 `annotations` | `{}` | -| `tikv.config` | 配置文件格式的 TiKV 的配置，请参考 [`tikv/etc/config-template.toml`](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 查看默认 TiKV 配置文件（选择对应 TiKV 版本的 tag），可以参考 [TiKV 配置文件描述](https://pingcap.com/docs-cn/v3.0/reference/configuration/tikv-server/configuration-file/)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置**

以下两个配置项需要显式配置：

`[storage.block-cache]`
  `shared = true`
  `capacity = "1GB"`
推荐设置：`capacity` 设置为 `tikv.resources.limits.memory` 的 50%

`[readpool.coprocessor]`
  `high-concurrency = 8`
  `normal-concurrency = 8`
  `low-concurrency = 8`
推荐设置：设置为 `tikv.resources.limits.cpu` 的 80%| TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`log-level = "info"`
配置示例：
  `config:` \|
    `log-level = "info"` | -| `tikv.replicas` | TiKV 的 Pod 数 | `3` | -| `tikv.image` | TiKV 的镜像 | `pingcap/tikv:v3.0.0-rc.1` | -| `tikv.imagePullPolicy` | TiKV 镜像的拉取策略 | `IfNotPresent` | -| `tikv.logLevel` | TiKV 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`log-level = "info"` | `info` | -| `tikv.storageClassName` | TiKV 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `tikv.syncLog` | syncLog 指是否启用 raft 日志同步功能，启用该功能能保证在断电时数据不丢失
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[raftstore]`
`sync-log = true` | `true` | -| `tikv.grpcConcurrency` | 配置 gRPC server 线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[server]`
`grpc-concurrency = 4` | `4` | -| `tikv.resources.limits.cpu` | 每个 TiKV Pod 的 CPU 资源限额 | `nil` | -| `tikv.resources.limits.memory` | 每个 TiKV Pod 的内存资源限额 | `nil` | -| `tikv.resources.limits.storage` | 每个 TiKV Pod 的存储容量限额 | `nil` | -| `tikv.resources.requests.cpu` | 每个 TiKV Pod 的 CPU 资源请求 | `nil` | -| `tikv.resources.requests.memory` | 每个 TiKV Pod 的内存资源请求 | `nil` | -| `tikv.resources.requests.storage` | 每个 TiKV Pod 的存储容量请求 | `10Gi` | -| `tikv.affinity` | `tikv.affinity` 定义 TiKV 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `tikv.nodeSelector` | `tikv.nodeSelector`确保 TiKV Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tikv.tolerations` | `tikv.tolerations` 应用于 TiKV Pods，允许 TiKV Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `tikv.annotations` | 为 TiKV Pods 添加特定的 `annotations` | `{}` | -| `tikv.defaultcfBlockCacheSize` | 指定 block 缓存大小，block 缓存用于缓存未压缩的 block，较大的 block 缓存设置可以加快读取速度。一般推荐设置为 `tikv.resources.limits.memory` 的 30%-50%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.defaultcf]`
`block-cache-size = "1GB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `1GB` | -| `tikv.writecfBlockCacheSize` | 指定 writecf 的 block 缓存大小，一般推荐设置为 `tikv.resources.limits.memory` 的 10%-30%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.writecf]`
`block-cache-size = "256MB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `256MB` | -| `tikv.readpoolStorageConcurrency` | TiKV 存储的高优先级/普通优先级/低优先级操作的线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.storage]`
`high-concurrency = 4`
`normal-concurrency = 4`
`low-concurrency = 4` | `4` | -| `tikv.readpoolCoprocessorConcurrency` | 一般如果 `tikv.resources.limits.cpu` > 8，则 `tikv.readpoolCoprocessorConcurrency` 设置为`tikv.resources.limits.cpu` * 0.8
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.coprocessor]`
`high-concurrency = 8`
`normal-concurrency = 8`
`low-concurrency = 8` | `8` | -| `tikv.storageSchedulerWorkerPoolSize` | TiKV 调度程序的工作池大小，应在重写情况下增加，同时应小于总 CPU 核心
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[storage]`
`scheduler-worker-pool-size = 4` | `4` | -| `tidb.config` | 配置文件格式的 TiDB 的配置，请参考[配置文件](https://github.com/pingcap/tidb/blob/master/config/config.toml.example)查看默认 TiDB 配置文件（选择对应 TiDB 版本的 tag），可以参考 [TiDB 配置文件描述](/v3.0/reference/configuration/tidb-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本）。这里只需要**按照配置文件中的格式修改配置**。

以下配置项需要显式配置：

`[performance]`
  `max-procs = 0`
推荐设置：`max-procs` 设置为 `tidb.resources.limits.cpu` 对应的核心数 | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"` | -| `tidb.replicas` | TiDB 的 Pod 数 | `2` | -| `tidb.image` | TiDB 的镜像 | `pingcap/tidb:v3.0.0-rc.1` | -| `tidb.imagePullPolicy` | TiDB 镜像的拉取策略 | `IfNotPresent` | -| `tidb.logLevel` | TiDB 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[log]`
`level = "info"` | `info` | -| `tidb.resources.limits.cpu` | 每个 TiDB Pod 的 CPU 资源限额 | `nil` | -| `tidb.resources.limits.memory` | 每个 TiDB Pod 的内存资源限额 | `nil` | -| `tidb.resources.requests.cpu` | 每个 TiDB Pod 的 CPU 资源请求 | `nil` | -| `tidb.resources.requests.memory` | 每个 TiDB Pod 的内存资源请求 | `nil` | -| `tidb.passwordSecretName`| 存放 TiDB 用户名及密码的 Secret 的名字，该 Secret 可以使用以下命令创建机密：`kubectl create secret generic tidb secret--from literal=root=--namespace=`，如果没有设置，则 TiDB 根密码为空 | `nil` | -| `tidb.initSql`| 在 TiDB 集群启动成功后，会执行的初始化脚本 | `nil` | -| `tidb.affinity` | `tidb.affinity` 定义 TiDB 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `tidb.nodeSelector` | `tidb.nodeSelector`确保 TiDB Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tidb.tolerations` | `tidb.tolerations` 应用于 TiDB Pods，允许 TiDB Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `tidb.annotations` | 为 TiDB Pods 添加特定的 `annotations` | `{}` | -| `tidb.maxFailoverCount` | TiDB 最大的故障转移数量，假设为 3 即最多支持同时 3 个 TiDB 实例故障转移 | `3` | -| `tidb.service.type` | TiDB 服务对外暴露类型 | `NodePort` | -| `tidb.service.externalTrafficPolicy` | 表示此服务是否希望将外部流量路由到节点本地或集群范围的端点。有两个可用选项：`Cluster`（默认）和 `Local`。`Cluster` 隐藏了客户端源 IP，可能导致流量需要二次跳转到另一个节点，但具有良好的整体负载分布。`Local` 保留客户端源 IP 并避免 LoadBalancer 和 NodePort 类型服务流量的第二次跳转，但存在潜在的不均衡流量传播风险。详细参考：[外部负载均衡器](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) | `nil` | -| `tidb.service.loadBalancerIP` | 指定 tidb 负载均衡 IP，某些云提供程序允许您指定loadBalancerIP。在这些情况下，将使用用户指定的loadBalancerIP创建负载平衡器。如果未指定loadBalancerIP字段，则将使用临时IP地址设置loadBalancer。如果指定loadBalancerIP但云提供程序不支持该功能，则将忽略您设置的loadbalancerIP字段 | `nil` | -| `tidb.service.mysqlNodePort` | TiDB 服务暴露的 mysql NodePort 端口 | | -| `tidb.service.exposeStatus` | TiDB 服务是否暴露状态端口 | `true` | -| `tidb.service.statusNodePort` | 指定 TiDB 服务的状态端口暴露的 `NodePort` | | -| `tidb.separateSlowLog` | 是否以 sidecar 方式运行独立容器输出 TiDB 的 SlowLog | 如果 TiDB Operator 版本 <= v1.0.0-beta.3，默认值为 `false`
如果 TiDB Operator 版本 > v1.0.0-beta.3，默认值为 `true` | -| `tidb.slowLogTailer.image` | TiDB 的 slowLogTailer 的镜像，slowLogTailer 是一个 sidecar 类型的容器，用于输出 TiDB 的 SlowLog，该配置仅在 `tidb.separateSlowLog`=`true` 时生效 | `busybox:1.26.2` | -| `tidb.slowLogTailer.resources.limits.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源限额 | `100m` | -| `tidb.slowLogTailer.resources.limits.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源限额 | `50Mi` | -| `tidb.slowLogTailer.resources.requests.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源请求 | `20m` | -| `tidb.slowLogTailer.resources.requests.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源请求 | `5Mi` | -| `tidb.plugin.enable` | 是否启用 TiDB 插件功能 | `false` | -| `tidb.plugin.directory` | 指定 TiDB 插件所在的目录 | `/plugins` | -| `tidb.plugin.list` | 指定 TiDB 加载的插件列表，plugin ID 命名规则：插件名-版本，例如：'conn_limit-1' | `[]` | -| `tidb.preparedPlanCacheEnabled` | 是否启用 TiDB 的 prepared plan 缓存
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`enabled = false` | `false` | -| `tidb.preparedPlanCacheCapacity` | TiDB 的 prepared plan 缓存数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`capacity = 100` | `100` | -| `tidb.txnLocalLatchesEnabled` | 是否启用事务内存锁，当本地事务冲突比较多时建议开启
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`enabled = false` | `false` | -| `tidb.txnLocalLatchesCapacity` | 事务内存锁的容量，Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`capacity = 10240000` | `10240000` | -| `tidb.tokenLimit` | TiDB 并发执行会话的限制
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`token-limit = 1000` | `1000` | -| `tidb.memQuotaQuery` | TiDB 查询的内存限额，默认 32GB
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`mem-quota-query = 34359738368` | `34359738368` | -| `tidb.checkMb4ValueInUtf8` | 用于控制当字符集为 utf8 时是否检查 mb4 字符
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`check-mb4-value-in-utf8 = true` | `true` | -| `tidb.treatOldVersionUtf8AsUtf8mb4` | 用于升级兼容性。设置为 `true` 将把旧版本的表/列的 `utf8` 字符集视为 `utf8mb4` 字符集
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`treat-old-version-utf8-as-utf8mb4 = true` | `true` | -| `tidb.lease` | `tidb.lease`是 TiDB Schema lease 的期限，对其更改是非常危险的，除非你明确知道可能产生的结果，否则不建议更改。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`lease = "45s"` | `45s` | -| `tidb.maxProcs` | 最大可使用的 CPU 核数，0 代表机器/Pod 上的 CPU 数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[performance]`
`max-procs = 0` | `0` | - -## 资源配置说明 - -部署前需要根据实际情况和需求，为 TiDB 集群各个组件配置资源，其中 PD、TiKV、TiDB 是 TiDB 集群的核心服务组件，在生产环境下它们的资源配置还需要按组件要求指定，具体参考：[资源配置推荐](/v3.0/how-to/deploy/hardware-recommendations.md)。 - -为了保证 TiDB 集群的组件在 Kubernetes 中合理的调度和稳定的运行，建议为其设置 Guaranteed 级别的 QoS，通过在配置资源时让 limits 等于 requests 来实现, 具体参考：[配置 QoS](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/)。 - -如果使用 NUMA 架构的 CPU，为了获得更好的性能，需要在节点上开启 `Static` 的 CPU 管理策略。为了 TiDB 集群组件能独占相应的 CPU 资源，除了为其设置上述 Guaranteed 级别的 QoS 外，还需要保证 CPU 的配额必须是大于或等于 1 的整数。具体参考: [CPU 管理策略](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies)。 - -## 容灾配置说明 - -TiDB 是分布式数据库，它的容灾需要做到在任一个物理拓扑节点发生故障时，不仅服务不受影响，还要保证数据也是完整和可用。下面分别具体说明这两种容灾的配置。 - -### TiDB 服务的容灾 - -TiDB 服务容灾本质上基于 Kubernetes 的调度功能来实现的，为了优化调度，TiDB Operator 提供了自定义的调度器，该调度器通过指定的调度算法能在 host 层面，保证 TiDB 服务的容灾，而且目前 TiDB Cluster 使用该调度器作为默认调度器，设置项是上述列表中的 `schedulerName` 配置项。 - -其它层面的容灾（例如 rack，zone，region）是通过 Affinity 的 `PodAntiAffinity` 来保证，通过 `PodAntiAffinity` 能尽量避免同一组件的不同实例部署到同一个物理拓扑节点上，从而达到容灾的目的，Affinity 的使用参考：[Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity)。 - -下面是一个典型的容灾设置例子： - -{{< copyable "shell-regular" >}} - -```shell -affinity: - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - # this term works when the nodes have the label named region - - weight: 10 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "region" - namespaces: - - - # this term works when the nodes have the label named zone - - weight: 20 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "zone" - namespaces: - - - # this term works when the nodes have the label named rack - - weight: 40 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "rack" - namespaces: - - - # this term works when the nodes have the label named kubernetes.io/hostname - - weight: 80 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "kubernetes.io/hostname" - namespaces: - - -``` - -### 数据的容灾 - -在开始数据容灾配置前，首先请阅读[集群拓扑信息配置](/v3.0/how-to/deploy/geographic-redundancy/location-awareness.md)。该文档描述了 TiDB 集群数据容灾的实现原理。 - -在 Kubernetes 上支持数据容灾的功能，需要如下操作： - -* 为 PD 设置拓扑位置 Label 集合 - - > **注意：** - > - > 除 `kubernetes.io/hostname` 外，目前 PD 暂不支持名字中带 `/` 的 Label。 - - 用 Kubernetes 集群 Node 节点上描述拓扑位置的 Label 集合替换 `pd.config` 配置项中里的 `location-labels` 信息。 - -* 为 TiKV 节点设置所在的 Node 节点的拓扑信息 - - TiDB Operator 会自动为 TiKV 获取其所在 Node 节点的拓扑信息，并调用 PD 接口将这些信息设置为 TiKV 的 store labels 信息，这样 TiDB 集群就能基于这些信息来调度数据副本。 - - 如果当前 Kubernetes 集群的 Node 节点没有表示拓扑位置的 Label，或者已有的拓扑 Label 名字中带有 `/`，可以通过下面的命令手动给 Node 增加标签： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl label node region= zone= rack= kubernetes.io/hostname= - ``` - - 其中 `region`、`zone`、`rack`、`kubernetes.io/hostname` 只是举例，要添加的 Label 名字和数量可以任意定义，只要符合规范且和 `pd.config` 里的 `location-labels` 设置的 Labels 保持一致即可。 diff --git a/v3.0/tidb-in-kubernetes/reference/configuration/tidb-drainer.md b/v3.0/tidb-in-kubernetes/reference/configuration/tidb-drainer.md deleted file mode 100644 index 95eecd8539a0..000000000000 --- a/v3.0/tidb-in-kubernetes/reference/configuration/tidb-drainer.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Kubernetes 上的 TiDB Binlog Drainer 配置 -summary: 了解 Kubernetes 上的 TiDB Binlog Drainer 配置 -category: reference ---- - -# Kubernetes 上的 TiDB Binlog Drainer 配置 - -本文档介绍 Kubernetes 上 TiDB Binlog drainer 的配置参数。 - -## 配置参数 - -下表包含所有用于 `tidb-drainer` chart 的配置参数。关于如何配置这些参数，可参阅[使用 Helm](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm)。 - -| 参数 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `clusterName` | 源 TiDB 集群的名称 | `demo` | -| `clusterVersion` | 源 TiDB 集群的版本 | `v3.0.1` | -| `baseImage` | TiDB Binlog 的基础镜像 | `pingcap/tidb-binlog` | -| `imagePullPolicy` | 镜像的拉取策略 | `IfNotPresent` | -| `logLevel` | drainer 进程的日志级别 | `info` | -| `storageClassName` | drainer 所使用的 `storageClass`。`storageClassName` 是 Kubernetes 集群提供的一种存储，可以映射到服务质量级别、备份策略或集群管理员确定的任何策略。详情可参阅 [storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `storage` | drainer Pod 的存储限制。请注意，如果 `db-type` 设为 `pd`，则应将本参数值设得大一些 | `10Gi` | -| `disableDetect` | 决定是否禁用事故检测 | `false` | -| `initialCommitTs` | 如果 drainer 没有断点，则用于初始化断点 | `0` | -| `config` | 传递到 drainer 的配置文件。详情可参阅 [drainer.toml](https://github.com/pingcap/tidb-binlog/blob/master/cmd/drainer/drainer.toml) |（见下文）| -| `resources` | drainer Pod 的资源限制和请求 | `{}` | -| `nodeSelector` | 确保 drainer Pod 仅被调度到具有特定键值对作为标签的节点上。详情可参阅 [nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tolerations` | 适用于 drainer Pod，允许将 Pod 调度到有指定 taint 的节点上。详情可参阅 [taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `affinity` | 定义 drainer Pod 的调度策略和首选项。详情可参阅 [affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | - -`config` 的默认值为： - -```toml -detect-interval = 10 -compressor = "" -[syncer] -worker-count = 16 -disable-dispatch = false -ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" -safe-mode = false -txn-batch = 20 -db-type = "file" -[syncer.to] -dir = "/data/pb" -``` diff --git a/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md b/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md deleted file mode 100644 index 30a047d439d1..000000000000 --- a/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 工具指南 -category: reference -aliases: ['/docs-cn/v3.0/reference/tools/tools-in-kubernetes/'] ---- - -# Kubernetes 上的 TiDB 工具指南 - -Kubernetes 上的 TiDB 运维管理需要使用一些开源工具。同时，在 Kubernetes 上使用 TiDB 生态工具时，也有特殊的操作要求。本文档详细描述 Kubernetes 上的 TiDB 相关的工具及其使用方法。 - -## 在 Kubernetes 上使用 PD Control - -[PD Control](/v3.0/reference/tools/pd-control.md) 是 PD 的命令行工具，在使用 PD Control 操作 Kubernetes 上的 TiDB 集群时，需要先使用 `kubectl port-forward` 打开本地到 PD 服务的连接： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & -``` - -执行上述命令后，就可以通过 `127.0.0.1:2379` 访问到 PD 服务，从而直接使用 `pd-ctl` 命令的默认参数执行操作，如： - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -d config show -``` - -假如你本地的 2379 被占据，则需要选择其它端口： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & -``` - -此时，需要为 `pd-ctl` 命令显式指定 PD 端口： - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -u 127.0.0.1: -d config show -``` - -## 在 Kubernetes 上使用 TiKV Control - -[TiKV Control](/v3.0/reference/tools/tikv-control.md) 是 TiKV 的命令行工具。在使用 TiKV Control 操作 Kubernetes 上的 TiDB 集群时，针对 TiKV Control 的不同操作模式，有不同的操作步骤。 - -* **远程模式**：此模式下 `tikv-ctl` 命令需要通过网络访问 TiKV 服务或 PD 服务，因此需要先使用 `kubectl port-forward` 打开本地到 PD 服务以及目标 TiKV 节点的连接： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n 20160:20160 &>/tmp/portforward-tikv.log & - ``` - - 打开连接后，即可通过本地的对应端口访问 PD 服务和 TiKV 节点： - - {{< copyable "shell-regular" >}} - - ```shell - $ tikv-ctl --host 127.0.0.1:20160 - ``` - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --pd 127.0.0.1:2379 compact-cluster - ``` - -* **本地模式**：本地模式需要访问 TiKV 的数据文件，并且需要停止正在运行的 TiKV 实例。需要先使用[诊断模式](/v3.0/tidb-in-kubernetes/troubleshoot.md#诊断模式)关闭 TiKV 实例自动重启，关闭 TiKV 进程，再使用 `tkctl debug` 命令在目标 TiKV Pod 中启动一个包含 `tikv-ctl` 可执行文件的新容器来执行操作，步骤如下： - - 1. 进入诊断模式： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl annotate pod -n runmode=debug - ``` - - 2. 关闭 TiKV 进程： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -n -c tikv -- kill -s TERM 1 - ``` - - 3. 启动 debug 容器： - - {{< copyable "shell-regular" >}} - - ```shell - tkctl debug -c tikv - ``` - - 4. 开始使用 `tikv-ctl` 的本地模式，需要注意的是 `tikv` 容器的根文件系统在 `/proc/1/root` 下，因此执行命令时也需要调整数据目录的路径： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --db /path/to/tikv/db size -r 2 - ``` - - Kubernetes 上 TiKV 实例在 debug 容器中的的默认 db 路径是 `/proc/1/root/var/lib/tikv/db size -r 2` - -## 在 Kubernetes 上使用 TiDB Control - -[TiDB Control](/v3.0/reference/tools/tidb-control.md) 是 TiDB 的命令行工具，使用 TiDB Control 时，需要从本地访问 TiDB 节点和 PD 服务，因此建议使用 `kubectl port-forward` 打开到集群中 TiDB 节点和 PD 服务的连接： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & -``` - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n 10080:10080 &>/tmp/portforward-tidb.log & -``` - -接下来便可开始使用 `tidb-ctl` 命令： - -{{< copyable "shell-regular" >}} - -```shell -tidb-ctl schema in mysql -``` - -## 使用 Helm - -[Helm](https://helm.sh/) 是一个 Kubernetes 的包管理工具，你可以参考 [Helm 官方文档](https://github.com/helm/helm#install) 安装 Helm，步骤如下： - -1. 安装 Helm 客户端 - - {{< copyable "shell-regular" >}} - - ```shell - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果使用 macOS，可以通过 homebrew 安装 Helm：`brew install kubernetes-helm`。 - -2. 安装 Helm 服务端 - - {{< copyable "shell-regular" >}} - - 在集群中应用 helm 服务端组件 `tiller` 所需的 `RBAC` 规则并安装 `tiller`： - - ```shell - kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/tiller-rbac.yaml && \ - helm init --service-account=tiller --upgrade - ``` - - 通过下面命令确认 `tiller` Pod 进入 running 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l name=tiller - ``` - - 如果 Kubernetes 集群没有启用 `RBAC`，那么可以直接使用下列命令安装 `tiller`： - - {{< copyable "shell-regular" >}} - - ```shell - helm init --upgrade - ``` - -Kubernetes 应用在 helm 中被打包为 chart。PingCAP 针对 Kubernetes 上的 TiDB 部署运维提供了三个 Helm chart： - -* `tidb-operator`：用于部署 TiDB Operator； -* `tidb-cluster`：用于部署 TiDB 集群； -* `tidb-backup`：用于 TiDB 集群备份恢复； - -这些 chart 都托管在 PingCAP 维护的 helm chart 仓库 `https://charts.pingcap.org/` 中，你可以通过下面的命令添加该仓库： - -{{< copyable "shell-regular" >}} - -```shell -helm repo add pingcap https://charts.pingcap.org/ -``` - -添加完成后，可以使用 `helm search` 搜索 PingCAP 提供的 chart： - -{{< copyable "shell-regular" >}} - -```shell -helm search pingcap -l -``` - -``` -NAME CHART VERSION APP VERSION DESCRIPTION -pingcap/tidb-backup v1.0.0 A Helm chart for TiDB Backup or Restore -pingcap/tidb-cluster v1.0.0 A Helm chart for TiDB Cluster -pingcap/tidb-operator v1.0.0 tidb-operator Helm chart for Kubernetes -``` - -当新版本的 chart 发布后，你可以使用 `helm repo update` 命令更新本地对于仓库的缓存： - -{{< copyable "shell-regular" >}} - -``` -helm repo update -``` - -Helm 的常用操作有部署（`helm install`）、升级（`helm upgrade`)、销毁（`helm del`)、查询（`helm ls`）。Helm chart 往往都有很多可配置参数，通过命令行进行配置比较繁琐，因此推荐使用 YAML 文件的形式来编写这些配置项，基于 Helm 社区约定俗称的命名方式，我们在文档中将用于配置 chart 的 YAML 文件称为 `values.yaml` 文件。 - -执行部署、升级、销毁等操作前，可以使用 `helm ls` 查看集群中已部署的应用： - -{{< copyable "shell-regular" >}} - -```shell -helm ls -``` - -在执行部署和升级操作时，必须指定使用的 chart 名字（`chart-name`）和部署后的应用名（`release-name`），还可以指定一个或多个 `values.yaml` 文件来配置 chart。此外，假如对 chart 有特定的版本需求，则需要通过 `--version` 参数指定 `chart-version` (默认为最新的 GA 版本）。命令形式如下： - -* 执行安装： - - {{< copyable "shell-regular" >}} - - ```shell - helm install --name= --namespace= --version= -f - ``` - -* 执行升级（升级可以是修改 `chart-version` 升级到新版本的 chart，也可以是修改 `values.yaml` 文件更新应用配置）： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade --version= -f - ``` - -最后，假如要删除 helm 部署的应用，可以执行： - -{{< copyable "shell-regular" >}} - -```shell -helm del --purge -``` - -更多 helm 的相关文档，请参考 [Helm 官方文档](https://helm.sh/docs/)。 - -## 使用 Terraform - -[Terraform](https://www.terraform.io/) 是一个基础设施即代码（Infrastructure as Code）管理工具。它允许用户使用声明式的风格描述自己的基础设施，并针对描述生成执行计划来创建或调整真实世界的计算资源。Kubernetes 上的 TiDB 使用 Terraform 来在公有云上创建和管理 TiDB 集群。 - -你可以参考 [Terraform 官方文档](https://www.terraform.io/downloads.html) 来安装 Terraform。 diff --git a/v3.0/tidb-in-kubernetes/reference/tools/tkctl.md b/v3.0/tidb-in-kubernetes/reference/tools/tkctl.md deleted file mode 100644 index 3ae67a7804b5..000000000000 --- a/v3.0/tidb-in-kubernetes/reference/tools/tkctl.md +++ /dev/null @@ -1,396 +0,0 @@ ---- -title: tkctl 使用指南 -category: reference -aliases: ['/docs-cn/v3.0/reference/tools/tkctl/'] ---- - -# tkctl 使用指南 - -`tkctl` (TiDB Kubernetes Control) 是为 TiDB in Kubernetes 设计的命令行工具，用于运维集群和诊断集群问题。 - -## 安装 - -安装 `tkctl` 时，可以直接下载预编译的可执行文件，也可以自行从源码进行编译。 - -### 下载预编译的可执行文件 - -- [MacOS](https://download.pingcap.org/tkctl-darwin-amd64-latest.tgz) -- [Linux](https://download.pingcap.org/tkctl-linux-amd64-latest.tgz) -- [Windows](https://download.pingcap.org/tkctl-windows-amd64-latest.tgz) - -下载解压后，将 `tkctl` 可执行文件加入到可执行文件路径 (`PATH`) 中即完成安装。 - -### 源码编译 - -要求：[Go](https://golang.org/) 版本 1.11 及以上 - -{{< copyable "shell-regular" >}} - -```shell -git clone https://github.com/pingcap/tidb-operator.git && \ -GOOS=${YOUR_GOOS} make cli && \ -mv tkctl /usr/local/bin/tkctl -``` - -## 命令自动补全 - -你可以配置 `tkctl` 的自动补全以简化使用。 - -为 BASH 配置自动补全（需要预先安装 [bash-completion](https://github.com/scop/bash-completion)）的方法如下。 - -在当前 shell 中设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -source <(tkctl completion bash) -``` - -永久设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -echo "if hash tkctl 2>/dev/null; then source <(tkctl completion bash); fi" >> ~/.bashrc -``` - -为 ZSH 配置自动补全的方法如下。 - -在当前 shell 中设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -source <(tkctl completion zsh) -``` - -永久设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -echo "if hash tkctl 2>/dev/null; then source <(tkctl completion zsh); fi" >> ~/.zshrc -``` - -## Kubernetes 配置 - -`tkctl` 复用了 `kubeconfig` 文件（默认位置是 `~/.kube/config`）来连接 Kubernetes 集群。你可以通过下面的命令来验证 `kubeconfig` 是否设置正确： - -{{< copyable "shell-regular" >}} - -```shell -tkctl version -``` - -假如上面的命令正确输出服务端的 TiDB Operator 版本，则 `kubeconfig` 配置正确。 - -## 所有命令 - -### tkctl version - -该命令用于展示本地 **tkctl** 和集群中 **tidb-operator** 的版本： - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl version -``` - -``` -Client Version: v1.0.0-beta.1-p2-93-g6598b4d3e75705-dirty -TiDB Controller Manager Version: pingcap/tidb-operator:latest -TiDB Scheduler Version: pingcap/tidb-operator:latest -``` - -### tkctl list - -该命令用于列出所有已安装的 TiDB 集群： - -| 参数 | 缩写 | 说明 | -| ----- | --------- | ----------- | -| --all-namespaces | -A | 是否查询所有的 Kubernetes Namespace | -| --output | -o | 输出格式，可选值有 [default,json,yaml]，默认值为 `default` | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl list -A -``` - -``` -NAMESPACE NAME PD TIKV TIDB AGE -foo demo-cluster 3/3 3/3 2/2 11m -bar demo-cluster 3/3 3/3 1/2 11m -``` - -### tkctl use - -该命令用于指定当前 `tkctl` 操作的 TiDB 集群，在使用该命令设置当前操作的 TiDB 集群后，所有针对集群的操作命令会自动选定该集群，从而可以略去 `--tidbcluster` 参数。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl use --namespace=foo demo-cluster -``` - -``` -Tidb cluster switched to foo/demo-cluster -``` - -### tkctl info - -该命令用于展示 TiDB 集群的信息。 - -| 参数 | 缩写 | 说明 | -| ----- | --------- | ----------- | -| --tidb-cluster | -t | 指定 TiDB 集群，默认为当前使用的 TiDB 集群 | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl info -``` - -``` -Name: demo-cluster -Namespace: foo -CreationTimestamp: 2019-04-17 17:33:41 +0800 CST -Overview: - Phase Ready Desired CPU Memory Storage Version - ----- ----- ------- --- ------ ------- ------- - PD: Normal 3 3 200m 1Gi 1Gi pingcap/pd:v3.0.0-rc.1 - TiKV: Normal 3 3 1000m 2Gi 10Gi pingcap/tikv:v3.0.0-rc.1 - TiDB Upgrade 1 2 500m 1Gi pingcap/tidb:v3.0.0-rc.1 -Endpoints(NodePort): - - 172.16.4.158:31441 - - 172.16.4.155:31441 -``` - -### tkctl get [component] - -该命令用于获取 TiDB 集群中组件的详细信息。 - -可选的组件 (`component`) 有： `pd`、`tikv`、`tidb`、`volume` 和 `all`（用于同时查询所有组件）。 - -| 参数 | 缩写 | 说明 | -| ----- | --------- | ----------- | -| --tidb-cluster | -t | 指定 TiDB 集群，默认为当前使用的 TiDB 集群 | -| --output | -o | 输出格式，可选值有 `default`、`json` 和 `yaml`，默认值为 `default` | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl get tikv -``` - -``` -NAME READY STATUS MEMORY CPU RESTARTS AGE NODE -demo-cluster-tikv-0 2/2 Running 2098Mi/4196Mi 2/2 0 3m19s 172.16.4.155 -demo-cluster-tikv-1 2/2 Running 2098Mi/4196Mi 2/2 0 4m8s 172.16.4.160 -demo-cluster-tikv-2 2/2 Running 2098Mi/4196Mi 2/2 0 4m45s 172.16.4.157 -``` - -{{< copyable "shell-regular" >}} - -```shell -tkctl get volume -``` - -``` -VOLUME CLAIM STATUS CAPACITY NODE LOCAL -local-pv-d5dad2cf tikv-demo-cluster-tikv-0 Bound 1476Gi 172.16.4.155 /mnt/disks/local-pv56 -local-pv-5ade8580 tikv-demo-cluster-tikv-1 Bound 1476Gi 172.16.4.160 /mnt/disks/local-pv33 -local-pv-ed2ffe50 tikv-demo-cluster-tikv-2 Bound 1476Gi 172.16.4.157 /mnt/disks/local-pv13 -local-pv-74ee0364 pd-demo-cluster-pd-0 Bound 1476Gi 172.16.4.155 /mnt/disks/local-pv46 -local-pv-842034e6 pd-demo-cluster-pd-1 Bound 1476Gi 172.16.4.158 /mnt/disks/local-pv74 -local-pv-e54c122a pd-demo-cluster-pd-2 Bound 1476Gi 172.16.4.156 /mnt/disks/local-pv72 -``` - -### tkctl debug [pod_name] - -该命令用于诊断 TiDB 集群中的 Pod。 - -实际使用时，该命令会在目标 Pod 的宿主机上以指定镜像启动一个 debug 容器，该容器会与目标 Pod 中的容器共享 namespace，因此可以无缝使用 debug 容器中的各种工具对目标容器进行诊断。 - -| 参数 | 缩写 | 描述 | -| ----- | --------- | ----------- | -| --image | | 指定 debug 容器使用的镜像，默认为 `pingcap/tidb-debug:latest` | -| --container | -c | 选择需要诊断的容器，默认为 Pod 定义中的第一个容器 | -| --docker-socket | | 指定目标节点上的 Docker Socket，默认为 `/var/run/docker.sock` | -| --privileged | | 是否为 debug 容器开启 [privileged](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) 模式 | - -> **注意：** -> -> Debug 容器使用的默认镜像包含了绝大多数的诊断工具，因此体积较大，假如只需要 `pd-ctl` 和 `tidb-ctl`，可以使用 `--image=pingcap/tidb-control:latest` 来指定使用 `tidb-control` 镜像。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl debug demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -ps -ef -``` - -由于 debug 容器和目标容器拥有不同的根文件系统，在 `tidb-debug` 容器中使用 GDB 和 perf 等工具时可能会碰到一些问题，下面将补充说明如何解决这些问题。 - -#### GDB - -使用 GDB 调试目标容器中的进程时，需要将 `program` 参数设置为目标容器中的可执行文件。假如是在 `tidb-debug` 以外的其它 debug 容器中进行调试，或者调试的目标进行 pid 不为 1，则需要使用 `set sysroot` 命令调整动态链接库的加载位置。操作如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl debug demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -gdb /proc/${pid:-1}/root/tikv-server 1 -``` - -`tidb-debug` 中预配置的 `.gdbinit` 会将 `sysroot` 设置为 `/proc/1/root/`，因此在 `tidb-debug` 中，假如目标容器的 pid 为 1，则下面的命令可以省略。 - -{{< copyable "shell-regular" >}} - -```shell -(gdb) set sysroot /proc/${pid}/root/ -``` - -开始调试： - -{{< copyable "shell-regular" >}} - -```shell -(gdb) thread apply all bt -``` - -{{< copyable "shell-regular" >}} - -```shell -(gdb) info threads -``` - -#### Perf 以及火焰图 - -使用 `perf` 命令和 `run-flamegraph.sh` 脚本时，需要将目标容器的可执行文件拷贝到 Debug 容器中： - -{{< copyable "shell-regular" >}} - -```shell -tkctl debug demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -cp /proc/1/root/tikv-server / -``` - -{{< copyable "shell-regular" >}} - -```shell -./run_flamegraph.sh 1 -``` - -该脚本会自动将生成的火焰图（SVG 格式）上传至 transfer.sh，通过访问脚本输出的链接即可下载火焰图。 - -### tkctl ctop - -命令的完整形式：`tkctl ctop [pod_name | node/node_name ]`。 - -该命令用于查看集群中 Pod 或 Node 的实时监控信息，和 `kubectl top` 相比，`tkctl ctop` 还会展示网络和磁盘的使用信息。 - -| 参数 | 简写 | 描述 | -| ----- | --------- | ----------- | -| --image | | 指定 ctop 的镜像，默认为 `quay.io/vektorlab/ctop:0.7.2` | -| --docker-socket | | 指定 ctop 使用的 Docker Socket，默认为 `/var/run/docker.sock` | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl ctop demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -tkctl ctop node/172.16.4.155 -``` - -### tkctl help [command] - -该命令用于展示各个子命令的帮助信息。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl help debug -``` - -### tkctl options - -该命令用于展示 `tkctl` 的所有的全局参数。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl options -``` - -``` -The following options can be passed to any command: - - --alsologtostderr=false: log to standard error as well as files - --as='': Username to impersonate for the operation - --as-group=[]: Group to impersonate for the operation, this flag can be repeated to specify multiple groups. - --cache-dir='/Users/alei/.kube/http-cache': Default HTTP cache directory - --certificate-authority='': Path to a cert file for the certificate authority - --client-certificate='': Path to a client certificate file for TLS - --client-key='': Path to a client key file for TLS - --cluster='': The name of the kubeconfig cluster to use - --context='': The name of the kubeconfig context to use - --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will -make your HTTPS connections insecure - --kubeconfig='': Path to the kubeconfig file to use for CLI requests. - --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace - --log_dir='': If non-empty, write log files in this directory - --logtostderr=true: log to standard error instead of files - -n, --namespace='': If present, the namespace scope for this CLI request - --request-timeout='0': The length of time to wait before giving up on a single server request. Non-zero values -should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. - -s, --server='': The address and port of the Kubernetes API server - --stderrthreshold=2: logs at or above this threshold go to stderr - -t, --tidbcluster='': Tidb cluster name - --token='': Bearer token for authentication to the API server - --user='': The name of the kubeconfig user to use - -v, --v=0: log level for V logs - --vmodule=: comma-separated list of pattern=N settings for file-filtered logging -``` - -这些参数主要用于指定如何连接 Kubernetes 集群，其中最常用的参数是： - -- `--context`：指定目标 Kubernetes 集群 -- `--namespace`：指定 Namespace diff --git a/v3.0/tidb-in-kubernetes/scale-in-kubernetes.md b/v3.0/tidb-in-kubernetes/scale-in-kubernetes.md deleted file mode 100644 index dcaab49216b5..000000000000 --- a/v3.0/tidb-in-kubernetes/scale-in-kubernetes.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群扩缩容 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/scale/tidb-in-kubernetes/'] ---- - -# Kubernetes 上的 TiDB 集群扩缩容 - -本文介绍 TiDB 在 Kubernetes 中如何进行水平扩缩容和垂直扩缩容。 - -## 水平扩缩容 - -TiDB 水平扩缩容操作指的是通过增加或减少节点的数量，来达到集群扩缩容的目的。扩缩容 TiDB 集群时，会按照填入的 replicas 值，对 PD、TiKV、TiDB 进行顺序扩缩容操作。扩容操作按照节点编号由小到大增加节点，缩容操作按照节点编号由大到小删除节点。 - -### 水平扩缩容操作 - -1. 修改集群的 `value.yaml` 文件中的 `pd.replicas`、`tidb.replicas`、`tikv.replicas` 至期望值。 - -2. 执行 `helm upgrade` 命令进行扩缩容： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看集群水平扩缩容状态： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有组件的 Pod 数量都达到了预设值，并且都进入 `Running` 状态后，水平扩缩容完成。 - -> **注意：** -> -> - PD、TiKV 组件在滚动升级的过程中不会触发扩缩容操作。 -> - TiKV 组件在缩容过程中会调用 PD 接口将对应 TiKV 标记为下线，然后将其上数据迁移到其它 TiKV 节点，在数据迁移期间 TiKV Pod 依然是 `Running` 状态，数据迁移完成后对应 Pod 才会被删除，缩容时间与待缩容的 TiKV 上的数据量有关，可以通过 `kubectl get tidbcluster -n -o json | jq '.status.tikv.stores'` 查看 TiKV 是否处于下线 `Offline` 状态。 -> - PD、TiKV 组件在缩容过程中被删除的节点的 PVC 会保留，并且由于 PV 的 `Reclaim Policy` 设置为 `Retain`，即使 PVC 被删除，数据依然可以找回。 -> - TiKV 组件不支持在缩容未完成时进行扩容操作，强制执行此操作可能导致集群状态异常。假如异常已经发生，可以参考 [TiKV Store 异常进入 Tombstone 状态](/v3.0/tidb-in-kubernetes/troubleshoot.md#tikv-store-异常进入-tombstone-状态) 进行解决。 - -## 垂直扩缩容 - -垂直扩缩容操作指的是通过增加或减少节点的资源限制，来达到集群扩缩容的目的。垂直扩缩容本质上是节点滚动升级的过程。 - -### 垂直扩缩容操作 - -1. 修改 `values.yaml` 文件中的 `tidb.resources`、`tikv.resources`、`pd.resources` 至期望值。 - -2. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，垂直扩缩容完成。 - -> **注意：** -> -> - 如果在垂直扩容时修改了资源的 `requests` 字段，由于 PD、TiKV 使用了 `Local PV`，升级后还需要调度回原节点，如果原节点资源不够，则会导致 Pod 一直处于 `Pending` 状态而影响服务。 -> - TiDB 作为一个可水平扩展的数据库，推荐通过增加节点个数发挥 TiDB 集群可水平扩展的优势，而不是类似传统数据库升级节点硬件配置来实现垂直扩容。 diff --git a/v3.0/tidb-in-kubernetes/tidb-operator-overview.md b/v3.0/tidb-in-kubernetes/tidb-operator-overview.md deleted file mode 100644 index f5787f73e58a..000000000000 --- a/v3.0/tidb-in-kubernetes/tidb-operator-overview.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: TiDB Operator 简介 -category: reference -aliases: ['/docs-cn/v3.0/reference/tidb-operator-overview/'] ---- - -# TiDB Operator 简介 - -TiDB Operator 是 Kubernetes 上的 TiDB 集群自动运维系统，提供包括部署、升级、扩缩容、备份恢复、配置变更的 TiDB 全生命周期管理。借助 TiDB Operator，TiDB 可以无缝运行在公有云或私有部署的 Kubernetes 集群上。 - -> **注意：** -> -> 每个 Kubernetes 集群中只能部署一个 TiDB Operator。 - -## TiDB Operator 整体架构 - -![TiDB Operator Overview](/media/tidb-operator-overview.png) - -其中，`TidbCluster` 是由 CRD（`CustomResourceDefinition`）定义的自定义资源，用于描述用户期望的 TiDB 集群状态。TiDB 集群的编排和调度逻辑则由下列组件负责： - -* `tidb-controller-manager` 是一组 Kubernetes 上的自定义控制器。这些控制器会不断对比 `TidbCluster` 对象中记录的期望状态与 TiDB 集群的实际状态，并调整 Kubernetes 中的资源以驱动 TiDB 集群满足期望状态； -* `tidb-scheduler` 是一个 Kubernetes 调度器扩展，它为 Kubernetes 调度器注入 TiDB 集群特有的调度逻辑。 - -此外，TiDB Operator 还提供了命令行接口 `tkctl` 用于运维集群和诊断集群问题。 - -![TiDB Operator Control Flow](/media/tidb-operator-control-flow.png) - -上图是 TiDB Operator 的控制流程解析。由于 TiDB 集群还需要监控、初始化、定时备份、Binlog 等组件，TiDB Operator 中使用 Helm Chart 封装了 TiDB 集群定义。整体的控制流程如下： - -1. 用户通过 Helm 创建 `TidbCluster` 对象和相应的一系列 Kubernetes 原生对象，比如执行定时备份的 `CronJob`； -2. TiDB Operator 会 watch `TidbCluster` 以及其它相关对象，基于集群的实际状态不断调整 PD、TiKV、TiDB 的 `StatefulSet` 和 `Service` 对象； -3. Kubernetes 的原生控制器根据 `StatefulSet`、`Deployment`、`CronJob` 等对象创建更新或删除对应的 `Pod`； -4. PD、TiKV、TiDB 的 `Pod` 声明中会指定使用 `tidb-scheduler` 调度器，`tidb-scheduler` 会在调度对应 `Pod` 时应用 TiDB 的特定调度逻辑。 - -基于上述的声明式控制流程，TiDB Operator 能够自动进行集群节点健康检查和故障恢复。部署、升级、扩缩容等操作也可以通过修改 `TidbCluster` 对象声明“一键”完成。 - -## 使用 TiDB Operator 管理 TiDB 集群 - -TiDB Operator 提供了多种方式来部署 Kubernetes 上的 TiDB 集群： - -+ 测试环境： - - [kind](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：采用 [kind](https://kind.sigs.k8s.io/) 方式在本地 Kubernetes 集群上部署 TiDB 集群； - - [Minikube](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：使用 TiDB Operator 在本地 Minikube 环境部署 TiDB 集群； - - [GKE](/v3.0/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md)：使用 TiDB Operator 在 GKE 上部署 TiDB 集群。 - -+ 生产环境： - - - 公有云：参考 [AWS 部署文档](/v3.0/tidb-in-kubernetes/deploy/aws-eks.md)，[GKE 部署文档 (beta)](/v3.0/tidb-in-kubernetes/deploy/gcp-gke.md)，或[阿里云部署文档](/v3.0/tidb-in-kubernetes/deploy/alibaba-cloud.md)在对应的公有云上一键部署生产可用的 TiDB 集群并进行后续的运维管理； - - - 现有 Kubernetes 集群：首先按照[部署 TiDB Operator](/v3.0/tidb-in-kubernetes/deploy/tidb-operator.md)在集群中安装 TiDB Operator，再根据[在标准 Kubernetes 集群上部署 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md)来部署你的 TiDB 集群。对于生产级 TiDB 集群，你还需要参考 [TiDB 集群环境要求](/v3.0/tidb-in-kubernetes/deploy/prerequisites.md)调整 Kubernetes 集群配置并根据[本地 PV 配置](/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)为你的 Kubernetes 集群配置本地 PV，以满足 TiKV 的低延迟本地存储需求。 - -在任何环境上部署前，都可以参考 [TiDB 集群配置](/v3.0/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)来自定义 TiDB 配置。 - -部署完成后，你可以参考下面的文档进行 Kubernetes 上 TiDB 集群的使用和运维： - -+ [部署 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/general-kubernetes.md) -+ [访问 TiDB 集群](/v3.0/tidb-in-kubernetes/deploy/access-tidb.md) -+ [TiDB 集群扩缩容](/v3.0/tidb-in-kubernetes/scale-in-kubernetes.md) -+ [TiDB 集群升级](/v3.0/tidb-in-kubernetes/upgrade/tidb-cluster.md#升级-tidb-版本) -+ [TiDB 集群配置变更](/v3.0/tidb-in-kubernetes/upgrade/tidb-cluster.md#更新-tidb-集群配置) -+ [TiDB 集群备份恢复](/v3.0/tidb-in-kubernetes/maintain/backup-and-restore.md) -+ [配置 TiDB 集群故障自动转移](/v3.0/tidb-in-kubernetes/maintain/auto-failover.md) -+ [监控 TiDB 集群](/v3.0/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) -+ [TiDB 集群日志收集](/v3.0/tidb-in-kubernetes/maintain/log-collecting.md) -+ [维护 TiDB 所在的 Kubernetes 节点](/v3.0/tidb-in-kubernetes/maintain/kubernetes-node.md) - -当集群出现问题需要进行诊断时，你可以： - -+ 查阅 [Kubernetes 上的 TiDB FAQ](/v3.0/tidb-in-kubernetes/faq.md) 寻找是否存在现成的解决办法； -+ 参考 [Kubernetes 上的 TiDB 故障诊断](/v3.0/tidb-in-kubernetes/troubleshoot.md)解决故障。 - -Kubernetes 上的 TiDB 提供了专用的命令行工具 `tkctl` 用于集群管理和辅助诊断，同时，在 Kubernetes 上，TiDB 的部分生态工具的使用方法也有所不同，你可以： - -+ 参考 [`tkctl` 使用指南](/v3.0/tidb-in-kubernetes/reference/tools/tkctl.md) 来使用 `tkctl`； -+ 参考 [Kubernetes 上的 TiDB 相关工具使用指南](/v3.0/tidb-in-kubernetes/reference/tools/in-kubernetes.md)来了解 TiDB 生态工具在 Kubernetes 上的使用方法。 - -最后，当 TiDB Operator 发布新版本时，你可以参考[升级 TiDB Operator](/v3.0/tidb-in-kubernetes/upgrade/tidb-operator.md) 进行版本更新。 diff --git a/v3.0/tidb-in-kubernetes/troubleshoot.md b/v3.0/tidb-in-kubernetes/troubleshoot.md deleted file mode 100644 index b757f0c64955..000000000000 --- a/v3.0/tidb-in-kubernetes/troubleshoot.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群故障诊断 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/troubleshoot/tidb-in-kubernetes/'] ---- - -# Kubernetes 上的 TiDB 集群故障诊断 - -本文介绍了 Kubernetes 上 TiDB 集群的一些常见故障以及诊断解决方案。 - -## 诊断模式 - -当 Pod 处于 `CrashLoopBackoff` 状态时，Pod 内会容器不断退出，导致无法正常使用 `kubectl exec` 或 `tkctl debug`，给诊断带来不便。为了解决这个问题，TiDB in Kubernetes 提供了 PD/TiKV/TiDB Pod 诊断模式。在诊断模式下，Pod 内的容器启动后会直接挂起，不会再进入重复 Crash 的状态，此时，便可以通过 `kubectl exec` 或 `tkctl debug` 连接 Pod 内的容器进行诊断。 - -操作方式： - -首先，为待诊断的 Pod 添加 Annotation： - -{{< copyable "shell-regular" >}} - -```shell -kubectl annotate pod -n runmode=debug -``` - -在 Pod 内的容器下次重启时，会检测到该 Annotation，进入诊断模式。等待 Pod 进入 Running 状态即可开始诊断： - -{{< copyable "shell-regular" >}} - -```shell -watch kubectl get pod -n -``` - -下面是使用 `kubectl exec` 进入容器进行诊断工作的例子： - -{{< copyable "shell-regular" >}} - -```shell -kubectl exec -it -n -- /bin/sh -``` - -诊断完毕，修复问题后，删除 Pod： - -```shell -kubectl delete pod -n -``` - -Pod 重建后会自动回到正常运行模式。 - -## 集群意外删除后恢复 - -TiDB Operator 使用 PV (Persistent Volume)、PVC (Persistent Volume Claim) 来存储持久化的数据，如果不小心使用 `helm delete` 意外删除了集群，PV/PVC 对象以及数据都会保留下来，以最大程度保证数据安全。 - -此时集群恢复的办法就是使用 `helm install` 命令来创建一个同名的集群，之前保留下来未被删除的 PV/PVC 以及数据会被复用： - -{{< copyable "shell-regular" >}} - -```shell -helm install pingcap/tidb-cluster -n --namespace= --version= -f values.yaml -``` - -## Pod 未正常创建 - -通过 `helm install` 创建集群后，如果 Pod 没有创建，则可以通过以下方式进行诊断： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get tidbclusters -n -kubectl get statefulsets -n -kubectl describe statefulsets -n -pd -``` - -## Pod 之间网络不通 - -针对 TiDB 集群而言，绝大部分 Pod 间的访问均通过 Pod 的域名（使用 Headless Service 分配）进行，例外的情况是 TiDB Operator 在收集集群信息或下发控制指令时，会通过 PD Service 的 `service-name` 访问 PD 集群。 - -当通过日志或监控确认 Pod 间存在网络连通性问题，或根据故障情况推断出 Pod 间网络连接可能不正常时，可以按照下面的流程进行诊断，逐步缩小问题范围： - -1. 确认 Service 和 Headless Service 的 Endpoints 是否正常： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl -n get endpoints -pd - kubectl -n get endpoints -tidb - kubectl -n get endpoints -pd-peer - kubectl -n get endpoints -tikv-peer - kubectl -n get endpoints -tidb-peer - ``` - - 以上命令展示的 `ENDPOINTS` 字段中，应当是由逗号分隔的 `cluster_ip:port` 列表。假如字段为空或不正确，请检查 Pod 的健康状态以及 `kube-controller-manager` 是否正常工作。 - -2. 进入 Pod 的 Network Namespace 诊断网络问题： - - {{< copyable "shell-regular" >}} - - ``` - tkctl debug -n - ``` - - 远端 shell 启动后，使用 `dig` 命令诊断 DNS 解析，假如 DNS 解析异常，请参照[诊断 Kubernetes DNS 解析](https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/)进行故障排除： - - {{< copyable "shell-regular" >}} - - ```shell - dig - ``` - - 使用 `ping` 命令诊断到目的 IP 的三层网络是否连通（目的 IP 为使用 `dig` 解析出的 ClusterIP）: - - {{< copyable "shell-regular" >}} - - ```shell - ping - ``` - - 假如 ping 检查失败，请参照[诊断 Kubernetes 网络](https://www.praqma.com/stories/debugging-kubernetes-networking/)进行故障排除。 - - 假如 ping 检查正常，继续使用 `telnet` 检查目标端口是否打开： - - {{< copyable "shell-regular" >}} - - ```shell - telnet - ``` - - 假如 `telnet` 检查失败，则需要验证 Pod 的对应端口是否正确暴露以及应用的端口是否配置正确： - - {{< copyable "shell-regular" >}} - - ```shell - # 检查端口是否一致 - kubectl -n get po -ojson | jq '.spec.containers[].ports[].containerPort' - - # 检查应用是否被正确配置服务于指定端口上 - # PD, 未配置时默认为 2379 端口 - kubectl -n -it exec -- cat /etc/pd/pd.toml | grep client-urls - # TiKV, 未配置时默认为 20160 端口 - kubectl -n -it exec -- cat /etc/tikv/tikv.toml | grep addr - # TiDB, 未配置时默认为 4000 端口 - kubectl -n -it exec -- cat /etc/tidb/tidb.toml | grep port - ``` - -## Pod 处于 Pending 状态 - -Pod 处于 Pending 状态，通常都是资源不满足导致的，比如： - -* 使用持久化存储的 PD、TiKV、Monitor Pod 使用的 PVC 的 StorageClass 不存在或 PV 不足 -* Kubernetes 集群中没有节点能满足 Pod 申请的 CPU 或内存 -* PD 或者 TiKV Replicas 数量和集群内节点数量不满足 tidb-scheduler 高可用调度策略 - -此时，可以通过 `kubectl describe pod` 命令查看 Pending 的具体原因： - -{{< copyable "shell-regular" >}} - -``` -kubectl describe po -n -``` - -如果是 CPU 或内存资源不足，可以通过降低对应组件的 CPU 或内存资源申请使其能够得到调度，或是增加新的 Kubernetes 节点。 - -如果是 PVC 的 StorageClass 找不到，需要在 `values.yaml` 里面将 `storageClassName` 修改为集群中可用的 StorageClass 名字，执行 `helm upgrade`，然后将 Statefulset 删除，并且将对应的 PVC 也都删除，可以通过以下命令获取集群中可用的 StorageClass： - -{{< copyable "shell-regular" >}} - -``` -kubectl get storageclass -``` - -如果集群中有 StorageClass，但可用的 PV 不足，则需要添加对应的 PV 资源。对于 Local PV，可以参考[本地 PV 配置](/v3.0/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)进行扩充。 - -tidb-scheduler 针对 PD 和 TiKV 定制了高可用调度策略。对于同一个 TiDB 集群，假设 PD 或者 TiKV 的 Replicas 数量为 N，那么可以调度到每个节点的 PD Pod 数量最多为 `M=(N-1)/2`（如果 N<3，M=1），可以调度到每个节点的 TiKV Pod 数量最多为 `M=ceil(N/3)`（ceil 表示向上取整，如果 N<3，M=1）。如果 Pod 因为不满足高可用调度策略而导致状态为 Pending，需要往集群内添加节点。 - -## Pod 处于 CrashLoopBackOff 状态 - -Pod 处于 CrashLoopBackOff 状态意味着 Pod 内的容器重复地异常退出（异常退出后，容器被 Kubelet 重启，重启后又异常退出，如此往复）。可能导致 CrashLoopBackOff 的原因有很多，此时，最有效的定位办法是查看 Pod 内容器的日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n logs -f -``` - -假如本次日志没有能够帮助诊断的有效信息，可以添加 `-p` 参数输出容器上次启动时的日志信息： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n logs -p -``` - -确认日志中的错误信息后，可以根据 [tidb-server 启动报错](/v3.0/how-to/troubleshoot/cluster-setup.md#tidb-server-启动报错)，[tikv-server 启动报错](/v3.0/how-to/troubleshoot/cluster-setup.md#tikv-server-启动报错)，[pd-server 启动报错](/v3.0/how-to/troubleshoot/cluster-setup.md#pd-server-启动报错)中的指引信息进行进一步排查解决。 - -若是 TiKV Pod 日志中出现 "cluster id mismatch" 信息，则 TiKV Pod 使用的数据可能是其他或之前的 TiKV Pod 的旧数据。在集群配置本地存储时未清除机器上本地磁盘上的数据，或者强制删除了 PV 导致数据并没有被 local volume provisioner 程序回收，可能导致 PV 遗留旧数据，导致错误。 - -在确认该 TiKV 应作为新节点加入集群、且 PV 上的数据应该删除后，可以删除该 TiKV Pod 和关联 PVC。TiKV Pod 将自动重建并绑定新的 PV 来使用。集群本地存储配置中，应对机器上的本地存储删除，避免 Kubernetes 使用机器上遗留的数据。集群运维中，不可强制删除 PV ，应由 local volume provisioner 程序管理。用户通过创建、删除 PVC 以及设置 PV 的 reclaimPolicy 来管理 PV 的生命周期。 - -另外，TiKV 在 ulimit 不足时也会发生启动失败的状况，对于这种情况，可以修改 Kubernetes 节点的 `/etc/security/limits.conf` 调大 ulimit： - -``` -root soft nofile 1000000 -root hard nofile 1000000 -root soft core unlimited -root soft stack 10240 -``` - -假如通过日志无法确认失败原因，ulimit 也设置正常，那么可以通过[诊断模式](#诊断模式)进行进一步排查。 - -## 无法访问 TiDB 服务 - -TiDB 服务访问不了时，首先确认 TiDB 服务是否部署成功，确认方法如下： - -查看该集群的所有组件是否全部都启动了，状态是否为 Running。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl get po -n -``` - -检查 TiDB 组件的日志，看日志是否有报错。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -f -n -c tidb -``` - -如果确定集群部署成功，则进行网络检查： - -1. 如果你是通过 `NodePort` 方式访问不了 TiDB 服务，请在 node 上尝试使用 service domain 或 clusterIP 访问 TiDB 服务，假如 serviceName 或 clusterIP 的方式能访问，基本判断 Kubernetes 集群内的网络是正常的，问题可能出在下面两个方面： - - * 客户端到 node 节点的网络不通。 - * 查看 TiDB service 的 `externalTrafficPolicy` 属性是否为 Local。如果是 Local 则客户端必须通过 TiDB Pod 所在 node 的 IP 来访问。 - -2. 如果 service domain 或 clusterIP 方式也访问不了 TiDB 服务，尝试用 TiDB服务后端的 `:4000` 连接看是否可以访问，如果通过 PodIP 可以访问 TiDB 服务，可以确认问题出在 service domain 或 clusterIP 到 PodIP 之间的连接上，排查项如下： - - * 检查 DNS 服务是否正常： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l k8s-app=kube-dns - dig - ``` - - * 检查各个 node 上的 kube-proxy 是否正常运行： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l k8s-app=kube-proxy - ``` - - * 检查 node 上的 iptables 规则中 TiDB 服务的规则是否正确 - - {{< copyable "shell-regular" >}} - - ```shell - iptables-save -t nat |grep - ``` - - * 检查对应的 endpoint 是否正确 - -3. 如果通过 PodIP 访问不了 TiDB 服务，问题出在 Pod 层面的网络上，排查项如下： - - * 检查 node 上的相关 route 规则是否正确 - * 检查网络插件服务是否正常 - * 参考上面的 [Pod 之间网络不通](#pod-之间网络不通)章节 - -## TiKV Store 异常进入 Tombstone 状态 - -正常情况下，当 TiKV Pod 处于健康状态时（Pod 状态为 `Running`），对应的 TiKV Store 状态也是健康的（Store 状态为 `UP`）。但并发进行 TiKV 组件的扩容和缩容可能会导致部分 TiKV Store 异常并进入 Tombstone 状态。此时，可以按照以下步骤进行修复： - -1. 查看 TiKV Store 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n tidbcluster -ojson | jq '.status.tikv.stores' - ``` - -2. 查看 TiKV Pod 运行状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n po -l app.kubernetes.io/component=tikv - ``` - -3. 对比 Store 状态与 Pod 运行状态。假如某个 TiKV Pod 所对应的 Store 处于 `Offline` 状态，则表明该 Pod 的 Store 正在异常下线中。此时，可以通过下面的命令取消下线进程，进行恢复： - - 1. 打开到 PD 服务的连接： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & - ``` - - 2. 上线对应 Store： - - {{< copyable "shell-regular" >}} - - ```shell - curl -X POST http://127.0.0.1:2379/pd/api/v1/store//state?state=Up - ``` - -4. 假如某个 TiKV Pod 所对应的 `lastHeartbeatTime` 最新的 Store 处于 `Tombstone` 状态 ，则表明异常下线已经完成。此时，需要重建 Pod 并绑定新的 PV 进行恢复： - - 1. 将该 Store 对应 PV 的 `reclaimPolicy` 调整为 `Delete`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch $(kubectl get pv -l app.kubernetes.io/instance=,tidb.pingcap.com/store-id= -o name) -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}} - ``` - - 2. 删除 Pod 使用的 PVC： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pvc tikv- --wait=false - ``` - - 3. 删除 Pod，等待 Pod 重建： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pod - ``` - - Pod 重建后，会以在集群中注册一个新的 Store，恢复完成。 - -## TiDB 长连接被异常中断 - -许多负载均衡器 (Load Balancer) 会设置连接空闲超时时间。当连接上没有数据传输的时间超过设定值，负载均衡器会主动将连接中断。若发现 TiDB 使用过程中，长查询会被异常中断，可检查客户端与 TiDB 服务端之间的中间件程序。若其连接空闲超时时间较短，可尝试增大该超时时间。若不可修改，可打开 TiDB `tcp-keep-alive` 选项，启用 TCP keepalive 特性。 - -默认情况下，Linux 发送 keepalive 探测包的等待时间为 7200 秒。若需减少该时间，可通过 `podSecurityContext` 字段配置 `sysctls`。 - -- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 允许配置 `--allowed-unsafe-sysctls=net.*`，请为 `kubelet` 配置该参数，并按如下方式配置 TiDB： - - {{< copyable "" >}} - - ```yaml - tidb: - ... - podSecurityContext: - sysctls: - - name: net.ipv4.tcp_keepalive_time - value: "300" - ``` - -- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 不允许配置 `--allowed-unsafe-sysctls=net.*`，请按如下方式配置 TiDB： - - {{< copyable "" >}} - - ```yaml - tidb: - annotations: - tidb.pingcap.com/sysctl-init: "true" - podSecurityContext: - sysctls: - - name: net.ipv4.tcp_keepalive_time - value: "300" - ... - ``` - -> **注意：** -> -> 进行以上配置要求 TiDB Operator 1.1 及以上版本。 diff --git a/v3.0/tidb-in-kubernetes/upgrade/tidb-cluster.md b/v3.0/tidb-in-kubernetes/upgrade/tidb-cluster.md deleted file mode 100644 index 79cc10792933..000000000000 --- a/v3.0/tidb-in-kubernetes/upgrade/tidb-cluster.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: 滚动升级 Kubernetes 上的 TiDB 集群 -category: how-to -aliases: ['/docs-cn/v3.0/how-to/upgrade/tidb-in-kubernetes/'] ---- - -# 滚动升级 Kubernetes 上的 TiDB 集群 - -滚动更新 TiDB 集群时，会按 PD、TiKV、TiDB 的顺序，串行删除 Pod，并创建新版本的 Pod，当新版本的 Pod 正常运行后，再处理下一个 Pod。 - -滚动升级过程会自动处理 PD、TiKV 的 Leader 迁移与 TiDB 的 DDL Owner 迁移。因此，在多节点的部署拓扑下（最小环境：PD \* 3、TiKV \* 3、TiDB \* 2），滚动更新 TiKV、PD 不会影响业务正常运行。 - -对于有连接重试功能的客户端，滚动更新 TiDB 同样不会影响业务。对于无法进行重试的客户端，滚动更新 TiDB 则会导致连接到被关闭节点的数据库连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能或在低峰期进行 TiDB 的滚动升级操作。 - -滚动更新可以用于升级 TiDB 版本，也可以用于更新集群配置。 - -## 升级 TiDB 版本 - -1. 修改集群的 `values.yaml` 文件中的 `tidb.image`、`tikv.image`、`pd.image` 的值为新版本镜像； -2. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 - -## 更新 TiDB 集群配置 - -默认条件下，修改配置文件不会自动应用到 TiDB 集群中，只有在实例重启时，才会重新加载新的配置文件。 - -您可以开启配置文件自动更新特性，在每次配置文件更新时，自动执行滚动更新，将修改后的配置应用到集群中。操作步骤如下： - -1. 修改集群的 `values.yaml` 文件，将 `enableConfigMapRollout` 的值设为 `true`； -2. 根据需求修改 `values.yaml` 中需要调整的集群配置项； -3. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -4. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 - -> **注意：** -> -> - 将 `enableConfigMapRollout` 特性从关闭状态打开时，即使没有配置变更，也会触发一次 PD、TiKV、TiDB 的滚动更新。 - -## 强制升级 TiDB 集群 - -如果 PD 集群因为 PD 配置错误、PD 镜像 tag 错误、NodeAffinity 等原因不可用，[TiDB 集群扩缩容](/v3.0/tidb-in-kubernetes/scale-in-kubernetes.md)、[升级 TiDB 版本](#升级-tidb-版本)和[更新 TiDB 集群配置](#更新-tidb-集群配置)这三种操作都无法成功执行。 - -这种情况下，可使用 `force-upgrade`（TiDB Operator 版本 > v1.0.0-beta.3 ）强制升级集群以恢复集群功能。 -首先为集群设置 `annotation`： - -{{< copyable "shell-regular" >}} - -```shell -kubectl annotate --overwrite tc -n tidb.pingcap.com/force-upgrade=true -``` - -然后执行对应操作中的 `helm upgrade` 命令： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade pingcap/tidb-cluster -f values.yaml --version= -``` - -> **警告：** -> -> PD 集群恢复后，**必须**执行下面命令禁用强制升级功能，否则下次升级过程可能会出现异常： -> -> {{< copyable "shell-regular" >}} -> -> ```shell -> kubectl annotate tc -n tidb.pingcap.com/force-upgrade- -> ``` diff --git a/v3.0/tidb-in-kubernetes/upgrade/tidb-operator.md b/v3.0/tidb-in-kubernetes/upgrade/tidb-operator.md deleted file mode 100644 index f09206005bc1..000000000000 --- a/v3.0/tidb-in-kubernetes/upgrade/tidb-operator.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 升级 TiDB Operator -category: how-to -aliases: ['/docs-cn/v3.0/how-to/upgrade/tidb-operator/'] ---- - -# 升级 TiDB Operator - -本文介绍如何升级 TiDB Operator。升级 TiDB Operator 和自定义 TiDB Operator 类似，修改 `values.yaml` 中的镜像版本，然后执行 `helm upgrade`： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade tidb-operator pingcap/tidb-operator --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml -``` - -当新版本 tidb-operator 发布，只要更新 `values.yaml` 中的 `operatorImage` 然后执行上述命令就可以。但是安全起见，最好从新版本 `tidb-operator` chart 中获取新版本 `values.yaml` 并和旧版本 `values.yaml` 合并生成新的 `values.yaml`，然后升级。 - -TiDB Operator 是用来管理 TiDB 集群的，也就是说，如果 TiDB 集群已经启动并正常运行，你甚至可以停掉 TiDB Operator，而 TiDB 集群仍然能正常工作，直到你需要维护 TiDB 集群，比如伸缩、升级等等。 - -## 升级 Kubernetes - -当你的 Kubernetes 集群有版本升级，请确保 `kubeSchedulerImageTag` 与之匹配。默认情况下，这个值是由 Helm 在安装或者升级过程中生成的，要修改它你需要执行 `helm upgrade`。 diff --git a/v3.1/TOC.md b/v3.1/TOC.md deleted file mode 100644 index 223d88acd0f7..000000000000 --- a/v3.1/TOC.md +++ /dev/null @@ -1,489 +0,0 @@ -# TiDB 中文用户文档 - - - - -## 目录 - -+ 关于 TiDB - - [TiDB 简介](/v3.1/overview.md) - + Benchmark 测试 - - [如何用 Sysbench 测试 TiDB](/v3.1/benchmark/how-to-run-sysbench.md) - - [如何对 TiDB 进行 TPC-C 测试](/v3.1/benchmark/how-to-run-tpcc.md) - - [Sysbench 性能对比 - v3.0 对比 v2.1](/v3.1/benchmark/sysbench-v4.md) - - [TPC-C 性能对比 - v3.0 对比 v2.1](/v3.1/benchmark/tpcc.md) - - [线上负载与 `Add Index` 相互影响测试](/v3.1/benchmark/add-index-with-load.md) - - [TiDB in Kubernetes Sysbench 性能测试](/v3.1/benchmark/sysbench-in-k8s.md) - - [DM 1.0-GA 性能测试](/v3.1/benchmark/dm-v1.0-ga.md) -+ 主要概念 - - [整体架构](/v3.1/architecture.md) - + 核心特性 - - [水平扩展](/v3.1/key-features.md#水平扩展) - - [高可用](/v3.1/key-features.md#高可用) -+ 操作指南 - + 快速上手 - + 创建集群 - - [使用 Docker Compose 部署 TiDB 集群](https://pingcap.com/docs-cn/dev/how-to/get-started/deploy-tidb-from-docker-compose/) - - [SQL 基本操作](/v3.1/how-to/get-started/explore-sql.md) - - [读取历史数据](/v3.1/how-to/get-started/read-historical-data.md) - - [TiDB Binlog 教程](/v3.1/how-to/get-started/tidb-binlog.md) - - [TiDB Data Migration 教程](/v3.1/how-to/get-started/data-migration.md) - - [TiDB Lightning 教程](/v3.1/how-to/get-started/tidb-lightning.md) - - [TiSpark 教程](/v3.1/how-to/get-started/tispark.md) - + 部署 - - [软硬件环境需求](/v3.1/how-to/deploy/hardware-recommendations.md) - + 集群部署方式 - - [使用 Ansible 部署（推荐）](/v3.1/how-to/deploy/orchestrated/ansible.md) - - [使用 Ansible 离线部署](/v3.1/how-to/deploy/orchestrated/offline-ansible.md) - - [使用 Docker 部署](/v3.1/how-to/deploy/orchestrated/docker.md) - + 跨地域冗余 - - [跨数据中心部署方案](/v3.1/how-to/deploy/geographic-redundancy/overview.md) - - [配置集群拓扑](/v3.1/how-to/deploy/geographic-redundancy/location-awareness.md) - - [使用 Ansible 部署 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md) - + 配置 - - [时区](/v3.1/how-to/configure/time-zone.md) - - [内存控制](/v3.1/how-to/configure/memory-control.md) - + 安全 - + 安全传输层协议 (TLS) - - [为 MySQL 客户端开启 TLS](/v3.1/how-to/secure/enable-tls-clients.md) - - [为 TiDB 组件间开启 TLS](/v3.1/how-to/secure/enable-tls-between-components.md) - - [生成自签名证书](/v3.1/how-to/secure/generate-self-signed-certificates.md) - + 监控 - - [概述](/v3.1/how-to/monitor/overview.md) - - [监控 TiDB 集群](/v3.1/how-to/monitor/monitor-a-cluster.md) - + 迁移 - - [迁移工具使用指南](/v3.1/reference/tools/user-guide.md) - + 从 MySQL 迁移 - - [以 Amazon Aurora MySQL 为例](/v3.1/how-to/migrate/from-mysql-aurora.md) - - [从 CSV 迁移](/v3.1/reference/tools/tidb-lightning/csv.md) - + 运维 - - [Ansible 常见运维操作](/v3.1/how-to/maintain/ansible-operations.md) - + 备份与恢复 - - [使用 Mydumper/TiDB Lightning 进行备份与恢复](/v3.1/how-to/maintain/backup-and-restore/mydumper-lightning.md) - - [使用 BR 进行备份与恢复](/v3.1/reference/tools/br/br.md) - - [BR 备份与恢复场景示例](/v3.1/reference/tools/br/use-cases.md) - + 定位异常查询 - - [定位慢查询](/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) - - [定位消耗系统资源多的查询](/v3.1/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md) - + 扩容缩容 - - [使用 Ansible 扩容缩容](/v3.1/how-to/scale/with-ansible.md) - + 升级 - - [升级至 TiDB 3.1](/v3.1/how-to/upgrade/from-previous-version.md) - + 故障诊断 - - [集群配置诊断](/v3.1/how-to/troubleshoot/cluster-setup.md) - - [TiDB Lightning 故障诊断](/v3.1/how-to/troubleshoot/tidb-lightning.md) -+ 参考手册 - + SQL - - [与 MySQL 兼容性对比](/v3.1/reference/mysql-compatibility.md) - + SQL 语言结构 - - [字面值](/v3.1/reference/sql/language-structure/literal-values.md) - - [Schema 对象名](/v3.1/reference/sql/language-structure/schema-object-names.md) - - [关键字和保留字](/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md) - - [用户自定义变量](/v3.1/reference/sql/language-structure/user-defined-variables.md) - - [表达式语法](/v3.1/reference/sql/language-structure/expression-syntax.md) - - [注释语法](/v3.1/reference/sql/language-structure/comment-syntax.md) - + 数据类型 - - [概述](/v3.1/reference/sql/data-types/overview.md) - - [默认值](/v3.1/reference/sql/data-types/default-values.md) - + 数值类型 - - [`BIT`](/v3.1/reference/sql/data-types/numeric.md#bit-类型) - - [`BOOL|BOOLEAN`](/v3.1/reference/sql/data-types/numeric.md#boolean-类型) - - [`TINYINT`](/v3.1/reference/sql/data-types/numeric.md#tinyint-类型) - - [`SMALLINT`](/v3.1/reference/sql/data-types/numeric.md#smallint-类型) - - [`MEDIUMINT`](/v3.1/reference/sql/data-types/numeric.md#mediumint-类型) - - [`INT|INTEGER`](/v3.1/reference/sql/data-types/numeric.md#integer-类型) - - [`BIGINT`](/v3.1/reference/sql/data-types/numeric.md#bigint-类型) - - [`DECIMAL`](/v3.1/reference/sql/data-types/numeric.md#decimal-类型) - - [`FLOAT`](/v3.1/reference/sql/data-types/numeric.md#float-类型) - - [`DOUBLE`](/v3.1/reference/sql/data-types/numeric.md#double-类型) - + 日期和时间类型 - - [`DATE`](/v3.1/reference/sql/data-types/date-and-time.md#date-类型) - - [`DATETIME`](/v3.1/reference/sql/data-types/date-and-time.md#datetime-类型) - - [`TIMESTAMP`](/v3.1/reference/sql/data-types/date-and-time.md#timestamp-类型) - - [`TIME`](/v3.1/reference/sql/data-types/date-and-time.md#time-类型) - - [`YEAR`](/v3.1/reference/sql/data-types/date-and-time.md#year-类型) - + 字符串类型 - - [`CHAR`](/v3.1/reference/sql/data-types/string.md#char-类型) - - [`VARCHAR`](/v3.1/reference/sql/data-types/string.md#varchar-类型) - - [`TEXT`](/v3.1/reference/sql/data-types/string.md#text-类型) - - [`LONGTEXT`](/v3.1/reference/sql/data-types/string.md#longtext-类型) - - [`BINARY`](/v3.1/reference/sql/data-types/string.md#binary-类型) - - [`VARBINARY`](/v3.1/reference/sql/data-types/string.md#varbinary-类型) - - [`TINYBLOB`](/v3.1/reference/sql/data-types/string.md#tinyblob-类型) - - [`BLOB`](/v3.1/reference/sql/data-types/string.md#blob-类型) - - [`MEDIUMBLOB`](/v3.1/reference/sql/data-types/string.md#mediumblob-类型) - - [`LONGBLOB`](/v3.1/reference/sql/data-types/string.md#longblob-类型) - - [`ENUM`](/v3.1/reference/sql/data-types/string.md#enum-类型) - - [`SET`](/v3.1/reference/sql/data-types/string.md#set-类型) - - [JSON Type](/v3.1/reference/sql/data-types/json.md) - + 函数与操作符 - - [函数与操作符概述](/v3.1/reference/sql/functions-and-operators/reference.md) - - [表达式求值的类型转换](/v3.1/reference/sql/functions-and-operators/type-conversion.md) - - [操作符](/v3.1/reference/sql/functions-and-operators/operators.md) - - [控制流程函数](/v3.1/reference/sql/functions-and-operators/control-flow-functions.md) - - [字符串函数](/v3.1/reference/sql/functions-and-operators/string-functions.md) - - [数值函数与操作符](/v3.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md) - - [日期和时间函数](/v3.1/reference/sql/functions-and-operators/date-and-time-functions.md) - - [位函数和操作符](/v3.1/reference/sql/functions-and-operators/bit-functions-and-operators.md) - - [Cast 函数和操作符](/v3.1/reference/sql/functions-and-operators/cast-functions-and-operators.md) - - [加密和压缩函数](/v3.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md) - - [信息函数](/v3.1/reference/sql/functions-and-operators/information-functions.md) - - [JSON 函数](/v3.1/reference/sql/functions-and-operators/json-functions.md) - - [GROUP BY 聚合函数](/v3.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md) - - [窗口函数](/v3.1/reference/sql/functions-and-operators/window-functions.md) - - [其它函数](/v3.1/reference/sql/functions-and-operators/miscellaneous-functions.md) - - [精度数学](/v3.1/reference/sql/functions-and-operators/precision-math.md) - - [下推到 TiKV 的表达式列表](/v3.1/reference/sql/functions-and-operators/expressions-pushed-down.md) - + SQL 语句 - - [`ADD COLUMN`](/v3.1/reference/sql/statements/add-column.md) - - [`ADD INDEX`](/v3.1/reference/sql/statements/add-index.md) - - [`ADMIN`](/v3.1/reference/sql/statements/admin.md) - - [`ALTER DATABASE`](/v3.1/reference/sql/statements/alter-database.md) - - [`ALTER TABLE`](/v3.1/reference/sql/statements/alter-table.md) - - [`ALTER USER`](/v3.1/reference/sql/statements/alter-user.md) - - [`ANALYZE TABLE`](/v3.1/reference/sql/statements/analyze-table.md) - - [`BEGIN`](/v3.1/reference/sql/statements/begin.md) - - [`COMMIT`](/v3.1/reference/sql/statements/commit.md) - - [`CREATE DATABASE`](/v3.1/reference/sql/statements/create-database.md) - - [`CREATE INDEX`](/v3.1/reference/sql/statements/create-index.md) - - [`CREATE TABLE LIKE`](/v3.1/reference/sql/statements/create-table-like.md) - - [`CREATE TABLE`](/v3.1/reference/sql/statements/create-table.md) - - [`CREATE USER`](/v3.1/reference/sql/statements/create-user.md) - - [`CREATE VIEW`](/v3.1/reference/sql/statements/create-view.md) - - [`DEALLOCATE`](/v3.1/reference/sql/statements/deallocate.md) - - [`DELETE`](/v3.1/reference/sql/statements/delete.md) - - [`DESC`](/v3.1/reference/sql/statements/desc.md) - - [`DESCRIBE`](/v3.1/reference/sql/statements/describe.md) - - [`DO`](/v3.1/reference/sql/statements/do.md) - - [`DROP COLUMN`](/v3.1/reference/sql/statements/drop-column.md) - - [`DROP DATABASE`](/v3.1/reference/sql/statements/drop-database.md) - - [`DROP INDEX`](/v3.1/reference/sql/statements/drop-index.md) - - [`DROP TABLE`](/v3.1/reference/sql/statements/drop-table.md) - - [`DROP USER`](/v3.1/reference/sql/statements/drop-user.md) - - [`DROP VIEW`](/v3.1/reference/sql/statements/drop-view.md) - - [`EXECUTE`](/v3.1/reference/sql/statements/execute.md) - - [`EXPLAIN ANALYZE`](/v3.1/reference/sql/statements/explain-analyze.md) - - [`EXPLAIN`](/v3.1/reference/sql/statements/explain.md) - - [`FLUSH PRIVILEGES`](/v3.1/reference/sql/statements/flush-privileges.md) - - [`FLUSH STATUS`](/v3.1/reference/sql/statements/flush-status.md) - - [`FLUSH TABLES`](/v3.1/reference/sql/statements/flush-tables.md) - - [`GRANT `](/v3.1/reference/sql/statements/grant-privileges.md) - - [`INSERT`](/v3.1/reference/sql/statements/insert.md) - - [`KILL [TIDB]`](/v3.1/reference/sql/statements/kill.md) - - [`LOAD DATA`](/v3.1/reference/sql/statements/load-data.md) - - [`MODIFY COLUMN`](/v3.1/reference/sql/statements/modify-column.md) - - [`PREPARE`](/v3.1/reference/sql/statements/prepare.md) - - [`RECOVER TABLE`](/v3.1/reference/sql/statements/recover-table.md) - - [`RENAME INDEX`](/v3.1/reference/sql/statements/rename-index.md) - - [`RENAME TABLE`](/v3.1/reference/sql/statements/rename-table.md) - - [`REPLACE`](/v3.1/reference/sql/statements/replace.md) - - [`REVOKE `](/v3.1/reference/sql/statements/revoke-privileges.md) - - [`ROLLBACK`](/v3.1/reference/sql/statements/rollback.md) - - [`SELECT`](/v3.1/reference/sql/statements/select.md) - - [`SET [NAMES|CHARACTER SET]`](/v3.1/reference/sql/statements/set-names.md) - - [`SET PASSWORD`](/v3.1/reference/sql/statements/set-password.md) - - [`SET TRANSACTION`](/v3.1/reference/sql/statements/set-transaction.md) - - [`SET [GLOBAL|SESSION] `](/v3.1/reference/sql/statements/set-variable.md) - - [`SHOW CHARACTER SET`](/v3.1/reference/sql/statements/show-character-set.md) - - [`SHOW COLLATION`](/v3.1/reference/sql/statements/show-collation.md) - - [`SHOW [FULL] COLUMNS FROM`](/v3.1/reference/sql/statements/show-columns-from.md) - - [`SHOW CREATE TABLE`](/v3.1/reference/sql/statements/show-create-table.md) - - [`SHOW CREATE USER`](/v3.1/reference/sql/statements/show-create-user.md) - - [`SHOW DATABASES`](/v3.1/reference/sql/statements/show-databases.md) - - [`SHOW ENGINES`](/v3.1/reference/sql/statements/show-engines.md) - - [`SHOW ERRORS`](/v3.1/reference/sql/statements/show-errors.md) - - [`SHOW [FULL] FIELDS FROM`](/v3.1/reference/sql/statements/show-fields-from.md) - - [`SHOW GRANTS`](/v3.1/reference/sql/statements/show-grants.md) - - [`SHOW INDEXES [FROM|IN]`](/v3.1/reference/sql/statements/show-indexes.md) - - [`SHOW INDEX [FROM|IN]`](/v3.1/reference/sql/statements/show-index.md) - - [`SHOW KEYS [FROM|IN]`](/v3.1/reference/sql/statements/show-keys.md) - - [`SHOW PRIVILEGES`](/v3.1/reference/sql/statements/show-privileges.md) - - [`SHOW [FULL] PROCESSSLIST`](/v3.1/reference/sql/statements/show-processlist.md) - - [`SHOW SCHEMAS`](/v3.1/reference/sql/statements/show-schemas.md) - - [`SHOW [FULL] TABLES`](/v3.1/reference/sql/statements/show-tables.md) - - [`SHOW TABLE REGIONS`](/v3.1/reference/sql/statements/show-table-regions.md) - - [`SHOW TABLE STATUS`](/v3.1/reference/sql/statements/show-table-status.md) - - [`SHOW [GLOBAL|SESSION] VARIABLES`](/v3.1/reference/sql/statements/show-variables.md) - - [`SHOW WARNINGS`](/v3.1/reference/sql/statements/show-warnings.md) - - [`SPLIT REGION`](/v3.1/reference/sql/statements/split-region.md) - - [`START TRANSACTION`](/v3.1/reference/sql/statements/start-transaction.md) - - [`TRACE`](/v3.1/reference/sql/statements/trace.md) - - [`TRUNCATE`](/v3.1/reference/sql/statements/truncate.md) - - [`UPDATE`](/v3.1/reference/sql/statements/update.md) - - [`USE`](/v3.1/reference/sql/statements/use.md) - - [约束](/v3.1/reference/sql/constraints.md) - - [生成列](/v3.1/reference/sql/generated-columns.md) - - [分区表](/v3.1/reference/sql/partitioning.md) - - [字符集](/v3.1/reference/sql/character-set.md) - - [SQL 模式](/v3.1/reference/sql/sql-mode.md) - - [视图](/v3.1/reference/sql/view.md) - + 配置 - + tidb-server - - [MySQL 系统变量](/v3.1/reference/configuration/tidb-server/mysql-variables.md) - - [TiDB 特定系统变量](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md) - - [配置参数](/v3.1/reference/configuration/tidb-server/configuration.md) - - [配置文件描述](/v3.1/reference/configuration/tidb-server/configuration-file.md) - + pd-server - - [配置参数](/v3.1/reference/configuration/pd-server/configuration.md) - - [配置文件描述](/v3.1/reference/configuration/pd-server/configuration-file.md) - + tikv-server - - [配置参数](/v3.1/reference/configuration/tikv-server/configuration.md) - - [配置文件描述](/v3.1/reference/configuration/tikv-server/configuration-file.md) - + 安全 - - [与 MySQL 的安全特性差异](/v3.1/reference/security/compatibility.md) - - [TiDB 数据库权限管理](/v3.1/reference/security/privilege-system.md) - - [TiDB 用户账户管理](/v3.1/reference/security/user-account-management.md) - - [基于角色的访问控制](/v3.1/reference/security/role-based-access-control.md) - - [TiDB 证书鉴权使用指南](/v3.1/reference/security/cert-based-authentication.md) - + 事务 - - [事务概览](/v3.1/reference/transactions/overview.md) - - [隔离级别](/v3.1/reference/transactions/transaction-isolation.md) - - [乐观事务](/v3.1/reference/transactions/transaction-optimistic.md) - - [悲观事务](/v3.1/reference/transactions/transaction-pessimistic.md) - + 系统数据库 - - [`mysql`](/v3.1/reference/system-databases/mysql.md) - - [`information_schema`](/v3.1/reference/system-databases/information-schema.md) - - [错误码](/v3.1/reference/error-codes.md) - - [支持的连接器和 API](/v3.1/reference/supported-clients.md) - + 垃圾回收 (GC) - - [GC 机制简介](/v3.1/reference/garbage-collection/overview.md) - - [GC 配置](/v3.1/reference/garbage-collection/configuration.md) - + 性能调优 - - [SQL 优化流程](/v3.1/reference/performance/sql-optimizer-overview.md) - - [理解 TiDB 执行计划](/v3.1/reference/performance/understanding-the-query-execution-plan.md) - - [执行计划绑定](/v3.1/reference/performance/execution-plan-bind.md) - - [统计信息概述](/v3.1/reference/performance/statistics.md) - - [Optimizer Hints](/v3.1/reference/performance/optimizer-hints.md) - - [Follower Read](/v3.1/reference/performance/follower-read.md) - - [使用 SQL 语句检查 TiDB 集群状态](/v3.1/reference/performance/check-cluster-status-using-sql-statements.md) - - [Statement Summary Table](/v3.1/reference/performance/statement-summary.md) - - [TiKV 调优](/v3.1/reference/performance/tune-tikv.md) - - [TiDB 最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/) - + 监控指标 - - [Overview 面板](/v3.1/reference/key-monitoring-metrics/overview-dashboard.md) - - [TiDB 面板](/v3.1/reference/key-monitoring-metrics/tidb-dashboard.md) - - [PD 面板](/v3.1/reference/key-monitoring-metrics/pd-dashboard.md) - - [TiKV 面板](/v3.1/reference/key-monitoring-metrics/tikv-dashboard.md) - - [报警规则](/v3.1/reference/alert-rules.md) - + 最佳实践 - - [HAProxy 最佳实践](/v3.1/reference/best-practices/haproxy.md) - - [Java 应用开发最佳实践](/v3.1/reference/best-practices/java-app.md) - - [高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) - - [Grafana 监控最佳实践](/v3.1/reference/best-practices/grafana-monitor.md) - - [PD 调度策略最佳实践](/v3.1/reference/best-practices/pd-scheduling.md) - - [海量 Region 集群调优最佳实践](/v3.1/reference/best-practices/massive-regions.md) - + [TiSpark 使用指南](/v3.1/reference/tispark.md) - + TiDB Binlog - - [概述](/v3.1/reference/tidb-binlog/overview.md) - - [部署使用](/v3.1/reference/tidb-binlog/deploy.md) - - [运维管理](/v3.1/reference/tidb-binlog/maintain.md) - - [版本升级](/v3.1/reference/tidb-binlog/upgrade.md) - - [监控告警](/v3.1/reference/tidb-binlog/monitor.md) - - [增量恢复](/v3.1/reference/tidb-binlog/reparo.md) - - [Kafka 自定义开发](/v3.1/reference/tidb-binlog/binlog-slave-client.md) - - [TiDB Binlog Relay Log](/v3.1/reference/tidb-binlog/relay-log.md) - - [术语表](/v3.1/reference/tidb-binlog/glossary.md) - + 故障诊断 - - [故障诊断](/v3.1/reference/tidb-binlog/troubleshoot/binlog.md) - - [常见错误修复](/v3.1/reference/tidb-binlog/troubleshoot/error-handling.md) - - [FAQ](/v3.1/reference/tidb-binlog/faq.md) - + 周边工具 - - [工具使用指南](/v3.1/reference/tools/user-guide.md) - - [Mydumper](/v3.1/reference/tools/mydumper.md) - - [Loader](/v3.1/reference/tools/loader.md) - - [Syncer](/v3.1/reference/tools/syncer.md) - + Data Migration - + 概述 - - [DM 架构](/v3.1/reference/tools/data-migration/overview.md#dm-架构) - - [同步功能介绍](/v3.1/reference/tools/data-migration/overview.md#同步功能介绍) - - [使用限制](/v3.1/reference/tools/data-migration/overview.md#使用限制) - - [DM-worker 简介](/v3.1/reference/tools/data-migration/dm-worker-intro.md) - - [DM Relay Log](/v3.1/reference/tools/data-migration/relay-log.md) - + 核心特性 - - [Table Routing](/v3.1/reference/tools/data-migration/features/overview.md#table-routing) - - [Black & White Lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) - - [Binlog Event Filter](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) - - [同步延迟监控](/v3.1/reference/tools/data-migration/features/overview.md#同步延迟监控) - + Shard Support - - [简介](/v3.1/reference/tools/data-migration/features/shard-merge.md) - - [使用限制](/v3.1/reference/tools/data-migration/features/shard-merge.md#使用限制) - - [手动处理 Sharding DDL Lock](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) - + 使用场景 - - [简单的从库同步场景](/v3.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md) - - [分库分表合并场景](/v3.1/reference/tools/data-migration/usage-scenarios/shard-merge.md) - - [分表合并数据迁移最佳实践](/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md) - - [DM-worker 在上游 MySQL 主从间切换](/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md) - + [部署使用](/v3.1/reference/tools/data-migration/deploy.md) - + 配置 - - [概述](/v3.1/reference/tools/data-migration/configure/overview.md) - - [DM-master 配置](/v3.1/reference/tools/data-migration/configure/dm-master-configuration-file.md) - - [DM-worker 配置](/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - - [任务配置](/v3.1/reference/tools/data-migration/configure/task-configuration-file.md) - + DM 集群管理 - - [集群操作](/v3.1/reference/tools/data-migration/cluster-operations.md) - - [集群升级](/v3.1/reference/tools/data-migration/dm-upgrade.md) - + DM 同步任务管理 - - [管理数据同步任务](/v3.1/reference/tools/data-migration/manage-tasks.md) - - [任务前置检查](/v3.1/reference/tools/data-migration/precheck.md) - - [任务状态查询](/v3.1/reference/tools/data-migration/query-status.md) - - [跳过或替代执行异常的 SQL 语句](/v3.1/reference/tools/data-migration/skip-replace-sqls.md) - - [监控 DM 集群](/v3.1/reference/tools/data-migration/monitor.md) - + 从与 MySQL 兼容的数据库迁移数据 - - [从 MySQL/Amazon Aurora MySQL 迁移数据](/v3.1/how-to/migrate/from-mysql-aurora.md) - - [DM Portal](/v3.1/reference/tools/data-migration/dm-portal.md) - + DM 故障诊断 - - [故障诊断](/v3.1/reference/tools/data-migration/troubleshoot/dm.md) - - [错误含义](/v3.1/reference/tools/data-migration/troubleshoot/error-system.md) - - [常见错误修复](/v3.1/reference/tools/data-migration/troubleshoot/error-handling.md) - - [DM FAQ](/v3.1/reference/tools/data-migration/faq.md) - + 版本发布历史 - + v1.0 - - [1.0.2](/v3.1/reference/tools/data-migration/releases/1.0.2.md) - - [1.0.3](/v3.1/reference/tools/data-migration/releases/1.0.3.md) - - [TiDB DM 术语表](/v3.1/reference/tools/data-migration/glossary.md) - + TiDB Lightning - - [概述](/v3.1/reference/tools/tidb-lightning/overview.md) - - [部署执行](/v3.1/reference/tools/tidb-lightning/deployment.md) - - [参数说明](/v3.1/reference/tools/tidb-lightning/config.md) - - [断点续传](/v3.1/reference/tools/tidb-lightning/checkpoints.md) - - [表库过滤](/v3.1/reference/tools/tidb-lightning/table-filter.md) - - [CSV 支持](/v3.1/reference/tools/tidb-lightning/csv.md) - - [TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) - - [Web 界面](/v3.1/reference/tools/tidb-lightning/web.md) - - [监控告警](/v3.1/reference/tools/tidb-lightning/monitor.md) - - [故障诊断](/v3.1/how-to/troubleshoot/tidb-lightning.md) - - [FAQ](/v3.1/faq/tidb-lightning.md) - - [术语表](/v3.1/reference/tools/tidb-lightning/glossary.md) - - [sync-diff-inspector](/v3.1/reference/tools/sync-diff-inspector/overview.md) - - [PD Control](/v3.1/reference/tools/pd-control.md) - - [PD Recover](/v3.1/reference/tools/pd-recover.md) - - [TiKV Control](/v3.1/reference/tools/tikv-control.md) - - [TiDB Controller](/v3.1/reference/tools/tidb-control.md) - - [工具下载](/v3.1/reference/tools/download.md) -+ TiDB in Kubernetes - - [TiDB Operator 简介](/v3.1/tidb-in-kubernetes/tidb-operator-overview.md) - + 快速上手 - - [kind](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) - - [GKE](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) - - [Minikube](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md) - + 部署 - - [集群环境要求](/v3.1/tidb-in-kubernetes/deploy/prerequisites.md) - - [部署 TiDB Operator](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md) - - [标准 Kubernetes 上的 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md) - - [AWS EKS 上的 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/aws-eks.md) - - [GCP 上的 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md) - - [阿里云上的 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/alibaba-cloud.md) - - [访问 Kubernetes 上的 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/access-tidb.md) - + 配置 - - [初始化集群](/v3.1/tidb-in-kubernetes/initialize-cluster.md) - - [监控](/v3.1/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) - + 运维 - - [销毁 TiDB 集群](/v3.1/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md) - - [维护 TiDB 集群所在节点](/v3.1/tidb-in-kubernetes/maintain/kubernetes-node.md) - - [备份与恢复](/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md) - - [恢复 Kubernetes 上的 TiDB 集群数据](/v3.1/tidb-in-kubernetes/maintain/lightning.md) - - [收集日志](/v3.1/tidb-in-kubernetes/maintain/log-collecting.md) - - [集群故障自动转移](/v3.1/tidb-in-kubernetes/maintain/auto-failover.md) - - [TiDB Binlog](/v3.1/tidb-in-kubernetes/maintain/tidb-binlog.md) - - [重启 TiDB 集群](/v3.1/tidb-in-kubernetes/maintain/restart.md) - - [扩缩容](/v3.1/tidb-in-kubernetes/scale-in-kubernetes.md) - + 升级 - - [TiDB 集群](/v3.1/tidb-in-kubernetes/upgrade/tidb-cluster.md) - - [TiDB Operator](/v3.1/tidb-in-kubernetes/upgrade/tidb-operator.md) - + 参考信息 - + 配置 - - [集群配置](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md) - - [备份配置](/v3.1/tidb-in-kubernetes/reference/configuration/backup.md) - - [PV 配置](/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md) - - [TiDB Drainer](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - + 工具 - - [tkctl](/v3.1/tidb-in-kubernetes/reference/tools/tkctl.md) - - [相关工具使用](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md) - - [故障诊断](/v3.1/tidb-in-kubernetes/troubleshoot.md) - - [常见问题](/v3.1/tidb-in-kubernetes/faq.md) -+ 常见问题 (FAQ) - - [TiDB FAQ](/v3.1/faq/tidb.md) - - [TiDB Lightning FAQ](/v3.1/faq/tidb-lightning.md) - - [升级 FAQ](/v3.1/faq/upgrade.md) -+ 技术支持 - - [支持渠道](/v3.1/support-resources.md) - - [反馈问题](/v3.1/report-issue.md) -+ [贡献](/v3.1/contribute.md) - - [贡献代码](/v3.1/contribute.md#成为-tidb-的贡献者) - - [改进文档](/v3.1/contribute.md#改进文档) -+ [TiDB 路线图](/v3.1/roadmap.md) -+ [版本发布历史](/v3.1/releases/rn.md) - + v3.1 - - [3.1.0-beta.1](/v3.1/releases/3.1.0-beta.1.md) - - [3.1.0-beta](/v3.1/releases/3.1.0-beta.md) - + v3.0 - - [3.0.10](/v3.1/releases/3.0.10.md) - - [3.0.9](/v3.1/releases/3.0.9.md) - - [3.0.8](/v3.1/releases/3.0.8.md) - - [3.0.7](/v3.1/releases/3.0.7.md) - - [3.0.6](/v3.1/releases/3.0.6.md) - - [3.0.5](/v3.1/releases/3.0.5.md) - - [3.0.4](/v3.1/releases/3.0.4.md) - - [3.0.3](/v3.1/releases/3.0.3.md) - - [3.0.2](/v3.1/releases/3.0.2.md) - - [3.0.1](/v3.1/releases/3.0.1.md) - - [3.0 GA](/v3.1/releases/3.0-ga.md) - - [3.0.0-rc.3](/v3.1/releases/3.0.0-rc.3.md) - - [3.0.0-rc.2](/v3.1/releases/3.0.0-rc.2.md) - - [3.0.0-rc.1](/v3.1/releases/3.0.0-rc.1.md) - - [3.0.0-beta.1](/v3.1/releases/3.0.0-beta.1.md) - - [3.0.0-beta](/v3.1/releases/3.0beta.md) - + v2.1 - - [2.1.19](/v3.1/releases/2.1.19.md) - - [2.1.18](/v3.1/releases/2.1.18.md) - - [2.1.17](/v3.1/releases/2.1.17.md) - - [2.1.16](/v3.1/releases/2.1.16.md) - - [2.1.15](/v3.1/releases/2.1.15.md) - - [2.1.14](/v3.1/releases/2.1.14.md) - - [2.1.13](/v3.1/releases/2.1.13.md) - - [2.1.12](/v3.1/releases/2.1.12.md) - - [2.1.11](/v3.1/releases/2.1.11.md) - - [2.1.10](/v3.1/releases/2.1.10.md) - - [2.1.9](/v3.1/releases/2.1.9.md) - - [2.1.8](/v3.1/releases/2.1.8.md) - - [2.1.7](/v3.1/releases/2.1.7.md) - - [2.1.6](/v3.1/releases/2.1.6.md) - - [2.1.5](/v3.1/releases/2.1.5.md) - - [2.1.4](/v3.1/releases/2.1.4.md) - - [2.1.3](/v3.1/releases/2.1.3.md) - - [2.1.2](/v3.1/releases/2.1.2.md) - - [2.1.1](/v3.1/releases/2.1.1.md) - - [2.1 GA](/v3.1/releases/2.1ga.md) - - [2.1 RC5](/v3.1/releases/21rc5.md) - - [2.1 RC4](/v3.1/releases/21rc4.md) - - [2.1 RC3](/v3.1/releases/21rc3.md) - - [2.1 RC2](/v3.1/releases/21rc2.md) - - [2.1 RC1](/v3.1/releases/21rc1.md) - - [2.1 Beta](/v3.1/releases/21beta.md) - + v2.0 - - [2.0.11](/v3.1/releases/2.0.11.md) - - [2.0.10](/v3.1/releases/2.0.10.md) - - [2.0.9](/v3.1/releases/209.md) - - [2.0.8](/v3.1/releases/208.md) - - [2.0.7](/v3.1/releases/207.md) - - [2.0.6](/v3.1/releases/206.md) - - [2.0.5](/v3.1/releases/205.md) - - [2.0.4](/v3.1/releases/204.md) - - [2.0.3](/v3.1/releases/203.md) - - [2.0.2](/v3.1/releases/202.md) - - [2.0.1](/v3.1/releases/201.md) - - [2.0](/v3.1/releases/2.0ga.md) - - [2.0 RC5](/v3.1/releases/2rc5.md) - - [2.0 RC4](/v3.1/releases/2rc4.md) - - [2.0 RC3](/v3.1/releases/2rc3.md) - - [2.0 RC1](/v3.1/releases/2rc1.md) - - [1.1 Beta](/v3.1/releases/11beta.md) - - [1.1 Alpha](/v3.1/releases/11alpha.md) - + v1.0 - - [1.0](/v3.1/releases/ga.md) - - [Pre-GA](/v3.1/releases/prega.md) - - [RC4](/v3.1/releases/rc4.md) - - [RC3](/v3.1/releases/rc3.md) - - [RC2](/v3.1/releases/rc2.md) - - [RC1](/v3.1/releases/rc1.md) -+ [术语表](/v3.1/glossary.md) diff --git a/v3.1/_index.md b/v3.1/_index.md deleted file mode 100755 index c81728e24d78..000000000000 --- a/v3.1/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/v3.1/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v3.1/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/v3.1/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，须使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v3.1/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 Docker Compose 部署](/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v3.1/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/v3.1/architecture.md b/v3.1/architecture.md deleted file mode 100644 index bd3aa2a3ef72..000000000000 --- a/v3.1/architecture.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB 整体架构 -category: introduction ---- - -# TiDB 整体架构 - -要深入了解 TiDB 的水平扩展和高可用特点，首先需要了解 TiDB 的整体架构。TiDB 集群主要包括三个核心组件：TiDB Server，PD Server 和 TiKV Server。此外，还有用于解决用户复杂 OLAP 需求的 [TiSpark](https://github.com/pingcap/tispark/) 组件和简化云上部署管理的 [TiDB Operator](/v3.1/tidb-in-kubernetes/tidb-operator-overview.md) 组件。 - -![TiDB Architecture](/media/tidb-architecture.png) - -## TiDB Server - -TiDB Server 负责接收 SQL 请求，处理 SQL 相关的逻辑，并通过 PD 找到存储计算所需数据的 TiKV 地址，与 TiKV 交互获取数据，最终返回结果。TiDB Server 是无状态的，其本身并不存储数据，只负责计算，可以无限水平扩展，可以通过负载均衡组件（如LVS、HAProxy 或 F5）对外提供统一的接入地址。 - -## PD Server - -Placement Driver (简称 PD) 是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。 - -PD 通过 Raft 协议保证数据的安全性。Raft 的 leader server 负责处理所有操作，其余的 PD server 仅用于保证高可用。建议部署奇数个 PD 节点。 - -## TiKV Server - -TiKV Server 负责存储数据，从外部看 TiKV 是一个分布式的提供事务的 Key-Value 存储引擎。存储数据的基本单位是 Region，每个 Region 负责存储一个 Key Range（从 StartKey 到 EndKey 的左闭右开区间）的数据，每个 TiKV 节点会负责多个 Region。TiKV 使用 Raft 协议做复制，保持数据的一致性和容灾。副本以 Region 为单位进行管理，不同节点上的多个 Region 构成一个 Raft Group，互为副本。数据在多个 TiKV 之间的负载均衡由 PD 调度，这里也是以 Region 为单位进行调度。 - -## TiSpark - -TiSpark 作为 TiDB 中解决用户复杂 OLAP 需求的主要组件，将 Spark SQL 直接运行在 TiDB 存储层上，同时融合 TiKV 分布式集群的优势，并融入大数据社区生态。至此，TiDB 可以通过一套系统，同时支持 OLTP 与 OLAP，免除用户数据同步的烦恼。 - -## TiDB Operator - -TiDB Operator 提供在主流云基础设施（Kubernetes）上部署管理 TiDB 集群的能力。它结合云原生社区的容器编排最佳实践与 TiDB 的专业运维知识，集成一键部署、多集群混部、自动运维、故障自愈等能力，极大地降低了用户使用和管理 TiDB 的门槛与成本。 diff --git a/v3.1/benchmark/add-index-with-load.md b/v3.1/benchmark/add-index-with-load.md deleted file mode 100644 index 351461fa815c..000000000000 --- a/v3.1/benchmark/add-index-with-load.md +++ /dev/null @@ -1,348 +0,0 @@ ---- -title: 线上负载与 `ADD INDEX` 相互影响测试 -category: benchmark ---- - -# 线上负载与 `ADD INDEX` 相互影响测试 - -## 测试目的 - -测试 OLTP 场景下，`ADD INDEX` 与线上负载的相互影响。 - -## 测试版本、时间、地点 - -TiDB 版本：v3.0.1 - -时间：2019 年 7 月 - -地点：北京 - -## 测试环境 - -测试在 Kubernetes 集群上进行，部署了 3 个 TiDB 实例，3 个 TiKV 实例和 3 个 PD 实例。 - -### 版本信息 - -| 组件 | GitHash | -| :--- | :---------------------------------------- | -| TiDB | `9e4e8da3c58c65123db5f26409759fe1847529f8` | -| TiKV | `4151dc8878985df191b47851d67ca21365396133` | -| PD | `811ce0b9a1335d1b2a049fd97ef9e186f1c9efc1` | - -Sysbench 版本：1.0.17 - -### TiDB 参数配置 - -TiDB、TiKV 和 PD 均使用 [TiDB Operator](https://github.com/pingcap/tidb-operator) 默认配置。 - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-------------------------------------- | :----------| -| 172.31.8.8 | Sysbench | -| 172.31.7.69, 172.31.5.152, 172.31.11.133 | PD | -| 172.31.4.172, 172.31.1.155, 172.31.9.210 | TiKV | -| 172.31.7.80, 172.31.5.163, 172.31.11.123 | TiDB | - -### 使用 Sysbench 模拟线上负载 - -使用 Sysbench 向集群导入 **1 张表，200 万行数据**。 - -执行如下命令导入数据： - -{{< copyable "shell-regular" >}} - -```sh -sysbench oltp_common \ - --threads=16 \ - --rand-type=uniform \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - prepare --tables=1 --table-size=2000000 -``` - -执行如下命令测试数据： - -{{< copyable "shell-regular" >}} - -```sh -sysbench $testname \ - --threads=$threads \ - --time=300000 \ - --report-interval=15 \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - run --tables=1 --table-size=2000000 -``` - -## 测试方案 1：`ADD INDEX` 目标列被频繁 Update - -1. 开始 `oltp_read_write` 测试。 -2. 与步骤 1 同时，使用 `alter table sbtest1 add index c_idx(c)` 添加索引。 -3. 在步骤 2 结束，即索引添加完成时，停止步骤 1 的测试。 -4. 获取 `alter table ... add index` 的运行时间、sysbench 在该时间段内的平均 TPS 和 QPS 作为指标。 -5. 逐渐增大 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 两个参数的值，重复步骤 1-4。 - -### 测试结果 - -#### 无 `ADD INDEX` 时 `oltp_read_write` 的结果 - -| sysbench TPS | sysbench QPS | -| :------- | :-------- | -| 350.31 | 6806 | - -#### `tidb_ddl_reorg_batch_size = 32` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 402 | 338.4 | 6776 | -| 2 | 266 | 330.3 | 6001 | -| 4 | 174 | 288.5 | 5769 | -| 8 | 129 | 280.6 | 5612 | -| 16 | 90 | 263.5 | 5273 | -| 32 | 54 | 229.2 | 4583 | -| 48 | 57 | 230.1 | 4601 | - -![add-index-load-1-b32](/media/add-index-load-1-b32.png) - -#### `tidb_ddl_reorg_batch_size = 64` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 264 | 269.4 | 5388 | -| 2 | 163 | 266.2 | 5324 | -| 4 | 105 | 272.5 | 5430 | -| 8 | 78 | 262.5 | 5228 | -| 16 | 57 | 215.5 | 4308 | -| 32 | 42 | 185.2 | 3715 | -| 48 | 45 | 189.2 | 3794 | - -![add-index-load-1-b64](/media/add-index-load-1-b64.png) - -#### `tidb_ddl_reorg_batch_size = 128` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 171 | 289.1 | 5779 | -| 2 | 110 | 274.2 | 5485 | -| 4 | 79 | 250.6 | 5011 | -| 8 | 51 | 246.1 | 4922 | -| 16 | 39 | 171.1 | 3431 | -| 32 | 35 | 130.8 | 2629 | -| 48 | 35 | 120.5 | 2425 | - -![add-index-load-1-b128](/media/add-index-load-1-b128.png) - -#### `tidb_ddl_reorg_batch_size = 256` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 145 | 283.0 | 5659 | -| 2 | 96 | 282.2 | 5593 | -| 4 | 56 | 236.5 | 4735 | -| 8 | 45 | 194.2 | 3882 | -| 16 | 39 | 149.3 | 2893 | -| 32 | 36 | 113.5 | 2268 | -| 48 | 33 | 86.2 | 1715 | - -![add-index-load-1-b256](/media/add-index-load-1-b256.png) - -#### `tidb_ddl_reorg_batch_size = 512` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 135 | 257.8 | 5147 | -| 2 | 78 | 252.8 | 5053 | -| 4 | 49 | 222.7 | 4478 | -| 8 | 36 | 145.4 | 2904 | -| 16 | 33 | 109 | 2190 | -| 32 | 33 | 72.5 | 1503 | -| 48 | 33 | 54.2 | 1318 | - -![add-index-load-1-b512](/media/add-index-load-1-b512.png) - -#### `tidb_ddl_reorg_batch_size = 1024` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 111 | 244.3 | 4885 | -| 2 | 78 | 228.4 | 4573 | -| 4 | 54 | 168.8 | 3320 | -| 8 | 39 | 123.8 | 2475 | -| 16 | 36 | 59.6 | 1213 | -| 32 | 42 | 93.2 | 1835 | -| 48 | 51 | 115.7 | 2261 | - -![add-index-load-1-b1024](/media/add-index-load-1-b1024.png) - -#### `tidb_ddl_reorg_batch_size = 2048` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 918 | 243.3 | 4855 | -| 2 | 1160 | 209.9 | 4194 | -| 4 | 342 | 185.4 | 3707 | -| 8 | 1316 | 151.0 | 3027 | -| 16 | 795 | 30.5 | 679 | -| 32 | 1130 | 26.69 | 547 | -| 48 | 893 | 27.5 | 552 | - -![add-index-load-1-b2048](/media/add-index-load-1-b2048.png) - -#### `tidb_ddl_reorg_batch_size = 4096` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 3042 | 200.0 | 4001 | -| 2 | 3022 | 203.8 | 4076 | -| 4 | 858 | 195.5 | 3971 | -| 8 | 3015 | 177.1 | 3522 | -| 16 | 837 | 143.8 | 2875 | -| 32 | 942 | 114 | 2267 | -| 48 | 187 | 54.2 | 1416 | - -![add-index-load-1-b4096](/media/add-index-load-1-b4096.png) - -### 测试结论 - -若 `ADD INDEX` 的目标列正在进行较为频繁的写操作（本测试涉及列的 `UPDATE`、`INSERT` 和 `DELETE`），默认 `ADD INDEX` 配置对系统的线上负载有比较明显的影响，该影响主要来源于 `ADD INDEX` 与 Column Update 并发进行造成的写冲突，系统的表现反应在： - -- 随着两个参数的逐渐增大，`TiKV_prewrite_latch_wait_duration` 有明显的升高，造成写入变慢。 -- `tidb_ddl_reorg_worker_cnt` 与 `tidb_ddl_reorg_batch_size` 非常大时，`admin show ddl` 命令可以看到 DDL job 的多次重试（例如 `Write conflict, txnStartTS 410327455965380624 is stale [try again later], ErrCount:38, SnapshotVersion:410327228136030220`），此时 `ADD INDEX` 会持续非常久才能完成。 - -## 测试方案 2：`ADD INDEX` 目标列不涉及写入（仅查询） - -1. 开始 `oltp_read_only` 测试。 -2. 与步骤 1 同时，使用 `alter table sbtest1 add index c_idx(c)` 添加索引。 -3. 在步骤 2 结束，即索引添加完成时，停止步骤 1。 -4. 获取 `alter table ... add index` 的运行时间、sysbench 在该时间段内的平均 TPS 和 QPS 作为指标。 -5. 逐渐增大 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 两个参数，重复步骤 1-4。 - -### 测试结果 - -#### 无 `ADD INDEX` 时 `oltp_read_only` 结果 - -| sysbench TPS | sysbench QPS | -| :------- | :-------- | -| 550.9 | 8812.8 | - -#### `tidb_ddl_reorg_batch_size = 32` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 376 | 548.9 | 8780 | -| 2 | 212 | 541.5 | 8523 | -| 4 | 135 | 538.6 | 8549 | -| 8 | 114 | 536.7 | 8393 | -| 16 | 77 | 533.9 | 8292 | -| 32 | 46 | 533.4 | 8103 | -| 48 | 46 | 532.2 | 8074 | - -![add-index-load-2-b32](/media/add-index-load-2-b32.png) - -#### `tidb_ddl_reorg_batch_size = 1024` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 91 | 536.8 | 8316 | -| 2 | 52 | 533.9 | 8165 | -| 4 | 40 | 522.4 | 7947 | -| 8 | 36 | 510 | 7860 | -| 16 | 33 | 485.5 | 7704 | -| 32 | 31 | 467.5 | 7516 | -| 48 | 30 | 562.1 | 7442 | - -![add-index-load-2-b1024](/media/add-index-load-2-b1024.png) - -#### `tidb_ddl_reorg_batch_size = 4096` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 103 | 502.2 | 7823 | -| 2 | 63 | 486.5 | 7672 | -| 4 | 52 | 467.4 | 7516 | -| 8 | 39 | 452.5 | 7302 | -| 16 | 35 | 447.2 | 7206 | -| 32 | 30 | 441.9 | 7057 | -| 48 | 30 | 440.1 | 7004 | - -![add-index-load-2-b4096](/media/add-index-load-2-b4096.png) - -### 测试结论 - -`ADD INDEX` 的目标列仅有查询负载时，`ADD INDEX` 对负载的影响不明显。 - -## 测试方案 3：集群负载不涉及 `ADD INDEX` 目标列 - -1. 开始 `oltp_read_write` 测试。 -2. 与步骤 1 同时，使用 `alter table test add index pad_idx(pad)` 添加索引。 -3. 在步骤 2 结束，即索引添加完成时，停止步骤 1 的测试。 -4. 获取 `alter table ... add index` 的运行时间、sysbench 在该时间段内的平均 TPS 和 QPS 作为指标。 -5. 逐渐增大 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 两个参数，重复步骤 1-4。 - -### 测试结果 - -#### 无 `ADD INDEX` 时 `oltp_read_write` 的结果 - -| sysbench TPS | sysbench QPS | -| :------- | :-------- | -| 350.31 | 6806 | - -#### `tidb_ddl_reorg_batch_size = 32` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 372 | 350.4 | 6892 | -| 2 | 207 | 344.2 | 6700 | -| 4 | 140 | 343.1 | 6672 | -| 8 | 121 | 339.1 | 6579 | -| 16 | 76 | 340 | 6607 | -| 32 | 42 | 343.1 | 6695 | -| 48 | 42 | 333.4 | 6454 | - -![add-index-load-3-b32](/media/add-index-load-3-b32.png) - -#### `tidb_ddl_reorg_batch_size = 1024` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 94 | 352.4 | 6794 | -| 2 | 50 | 332 | 6493 | -| 4 | 45 | 330 | 6456 | -| 8 | 36 | 325.5 | 6324 | -| 16 | 32 | 312.5 | 6294 | -| 32 | 32 | 300.6 | 6017 | -| 48 | 31 | 279.5 | 5612 | - -![add-index-load-3-b1024](/media/add-index-load-3-b1024.png) - -#### `tidb_ddl_reorg_batch_size = 4096` - -| tidb_ddl_reorg_worker_cnt | add_index_durations(s) | sysbench TPS | sysbench QPS | -| :------------------------ | :---------------------- | :------------- | :----------- | -| 1 | 116 | 325.5 | 6324 | -| 2 | 65 | 312.5 | 6290 | -| 4 | 50 | 300.6 | 6017 | -| 8 | 37 | 279.5 | 5612 | -| 16 | 34 | 250.4 | 5365 | -| 32 | 32 | 220.2 | 4924 | -| 48 | 33 | 214.8 | 4544 | - -![add-index-load-3-b4096](/media/add-index-load-3-b4096.png) - -### 测试结论 - -`ADD INDEX` 的目标列与负载无关时，`ADD INDEX` 对负载的影响不明显。 - -## 总结 - -- 当 `ADD INDEX` 的目标列被频繁更新（包含 `UPDATE`、`INSERT` 和 `DELETE`）时，默认配置会造成较为频繁的写冲突，使得在线负载较大；同时 `ADD INDEX` 也可能由于不断地重试，需要很长的时间才能完成。在本次测试中，将 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 的乘积调整为默认值的 1/32（例如 `tidb_ddl_reorg_worker_cnt` = 4，`tidb_ddl_reorg_batch_size` = 256）可以取得较好的效果。 -- 当 `ADD INDEX` 的目标列仅涉及查询负载，或者与线上负载不直接相关时，可以直接使用默认配置。 \ No newline at end of file diff --git a/v3.1/benchmark/dm-v1.0-ga.md b/v3.1/benchmark/dm-v1.0-ga.md deleted file mode 100644 index 3e2a589b2137..000000000000 --- a/v3.1/benchmark/dm-v1.0-ga.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: DM 1.0-GA 性能测试报告 -category: benchmark ---- - -# DM 1.0-GA 性能测试报告 - -本报告记录了对 1.0-GA 版本的 DM 进行性能测试的目的、环境、场景和结果。 - -## 测试目的 - -该性能测试用于评估使用 DM 进行全量数据导入和增量数据同步的性能上限，并根据测试结果提供 DM 同步任务的参考配置。 - -## 测试环境 - -### 测试机器信息 - -系统信息： - -| 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | -| :---------: | :---------------------------: | :-----------------------: | :--------------: | -| 172.16.4.39 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.40 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.41 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.42 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.43 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | -| 172.16.4.44 | CentOS Linux release 7.6.1810 | 3.10.0-957.1.3.el7.x86_64 | ext4 | - -硬件信息： - -| 类别 | 指标 | -| :----------: | :-------------------------------------------------: | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| 内存 | 192GB, 12 条 16GB DIMM DDR4 2133 MHz | -| 磁盘 | Intel DC P4510 4TB NVMe PCIe 3.0 | -| 网卡 | 万兆网卡 | - -其他： - -* 服务器间网络延迟：rtt min/avg/max/mdev = 0.074/0.088/0.121/0.019 ms - -### 集群拓扑 - -| 机器 IP | 部署的服务 | -| :---------: | :--------------------------------: | -| 172.16.4.39 | PD1, DM-worker1, DM-master | -| 172.16.4.40 | PD2, MySQL1 | -| 172.16.4.41 | PD3, TiDB | -| 172.16.4.42 | TiKV1 | -| 172.16.4.43 | TiKV2 | -| 172.16.4.44 | TiKV3 | - -### 各服务版本信息 - -- MySQL 版本: 5.7.27-log -- TiDB 版本: v4.0.0-alpha-198-gbde7f440e -- DM 版本: v1.0.1 -- Sysbench 版本: 1.0.17 - -## 测试场景 - -### 同步数据流 - -MySQL1 (172.16.4.40) -> DM-worker1 (172.16.4.39) -> TiDB (172.16.4.41) - -### 公共配置信息 - -#### 同步数据表结构 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `sbtest` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `k` int(11) NOT NULL DEFAULT '0', - `c` char(120) CHARSET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '', - `pad` char(60) CHARSET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -``` - -#### 数据库配置 - -使用 TiDB Ansible 部署 TiDB 测试集群，所有配置使用 TiDB Ansible 提供的默认配置。 - -### 全量导入性能测试用例 - -#### 测试过程 - -- 部署测试环境 -- 使用 `sysbench` 在上游创建测试表，并生成全量导入的测试数据 -- 在 `full` 模式下启动 DM 同步任务 - -`sysbench` 生成数据的命令如下所示： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --test=oltp_insert --tables=4 --mysql-host=172.16.4.40 --mysql-port=3306 --mysql-user=root --mysql-db=dm_benchmark --db-driver=mysql --table-size=50000000 prepare -``` - -#### 全量导入性能测试结果 - -在 `mydumper` 中使用 `--rows` 选项可以开启单表多线程并发导出（当前 `mydumper` 在 MySQL 的单表并发会优先选出一列做拆分基准，选择优先级为主键>唯一索引>普通索引，选出目标列后需保证该列为 INT 类型；针对 `TiDB` 的并发导出则会优先尝试 `_tidb_rowid` 列），以下的第一项测试用于验证开启单表并发导出可以提高数据导出性能。 - -| 测试项 | 导出线程数 | mydumper extra-args 参数 | 导出速度 (MB/s) | -| :----------------: | :---------: | :---------------------------------: | :---------------: | -| 开启单表并发导出 | 32 | "--rows 320000 --regex '^sbtest.*'" | 191.03 | -| 不开启单表并发导出 | 4 | "--regex '^sbtest.*'" | 72.22 | - -| 测试项 | 事务执行延迟 (s) | 每条插入语句包含的行数 | 导入数据量 (GB) | 导入时间 (s) | 导入速度 (MB/s) | -| :-------: | :--------------: | :--------------------: | :-------------: | :----------: | :-------------: | -| load data | 1.737 | 4878 | 38.14 | 2346.9 | 16.64 | - -#### 在 load 处理单元使用不同 pool size 的性能测试对比 - -该测试中全量导入的数据量为 3.78 GB，使用以下 `sysbench` 命令生成： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --test=oltp_insert --tables=4 --mysql-host=172.16.4.40 --mysql-port=3306 --mysql-user=root --mysql-db=dm_benchmark --db-driver=mysql --table-size=5000000 prepare -``` - -| load 处理单元 pool size | 事务执行时间 (s) | 导入时间 (s) | 导入速度 (MB/s) | TiDB 99 duration (s) | -| :---------------------: | :--------------: | :----------: | :-------------: | :------------------: | -| 2 | 0.250 | 425.9 | 9.1 | 0.23 | -| 4 | 0.523 | 360.1 | 10.7 | 0.41 | -| 8 | 0.986 | 267.0 | 14.5 | 0.93 | -| 16 | 2.022 | 265.9 | 14.5 | 2.68 | -| 32 | 3.778 | 262.3 | 14.7 | 6.39 | -| 64 | 7.452 | 281.9 | 13.7 | 8.00 | - -#### 导入数据时每条插入语句包含行数不同的情况下的性能测试对比 - -该测试中全量导入的数据量为 3.78 GB，load 处理单元 `pool-size` 大小为 32。插入语句包含行数通过 mydumper 的 `--statement-size` 来控制。 - -| 每条语句中包含的行数 | mydumper extra-args 参数 | 事务执行时间 (s) | 导入时间 (s) | 导入速度 (MB/s) | TiDB 99 duration (s) | -| :------------------------: | :-----------------------: | :---------------: | :----------: | :-------------: | :------------------: | -| 7426 | -s 1500000 -r 320000 | 6.982 | 258.3 | 15.0 | 10.34 | -| 4903 | -s 1000000 -r 320000 | 3.778 | 262.3 | 14.7 | 6.39 | -| 2470 | -s 500000 -r 320000 | 1.962 | 271.36 | 14.3 | 2.00 | -| 1236 | -s 250000 -r 320000 | 1.911 | 283.3 | 13.7 | 1.50 | -| 618 | -s 125000 -r 320000 | 0.683 | 299.9 | 12.9 | 0.73 | -| 310 | -s 62500 -r 320000 | 0.413 | 322.6 | 12.0 | 0.49 | - -### 增量同步性能测试用例 - -#### 测试过程 - -- 部署测试环境 -- 使用 `sysbench` 在上游创建测试表，并生成全量导入的测试数据 -- 在 `all` 模式下启动 DM 同步任务，等待同步任务进入 `sync` 同步阶段 -- 使用 `sysbench` 在上游持续生成增量数据，通过 `query-status` 命令观测 DM 的同步状态，通过 Grafana 观测 DM 和 TiDB 的监控指标。 - -#### 增量同步性能测试结果 - -上游 `sysbench` 生成增量数据命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --test=oltp_insert --tables=4 --num-threads=32 --mysql-host=172.17.4.40 --mysql-port=3306 --mysql-user=root --mysql-db=dm_benchmark --db-driver=mysql --report-interval=10 --time=1800 run -``` - -该性能测试中同步任务 `sync` 处理单元 `worker-count` 设置为 32，`batch` 大小设置为 100。 - -| 组件 | qps | tps | 95% 延迟 | -| :------------------------: | :----------------------------------------------------------: | :-------------------------------------------------------------: | :--------------------------: | -| MySQL | 42.79k | 42.79k | 1.18ms | -| DM relay log unit | - | 11.3MB/s | 45us (binlog 读延迟) | -| DM binlog replication unit | 22.97k (binlog event 接收qps，不包括忽略的 event) | - | 20ms (事务执行时间) | -| TiDB | 31.30k (Begin/Commit 3.93k Insert 22.76k) | 4.16k | 95%: 6.4ms 99%: 9ms | - -#### 在 sync 处理单元使用不同并发度的性能测试对比 - -| sync 处理单元 worker-count 数 | DM 内部 job tps | DM 事务执行时间 (ms) | TiDB qps | TiDB 99 duration (ms) | -| :---------------------------: | :-------------: | :-----------------------: | :------: | :-------------------: | -| 4 | 7074 | 63 | 7.1k | 3 | -| 8 | 14684 | 64 | 14.9k | 4 | -| 16 | 23486 | 56 | 24.9k | 6 | -| 32 | 23345 | 28 | 29.2k | 10 | -| 64 | 23302 | 30 | 31.2k | 16 | -| 1024 | 22225 | 70 | 56.9k | 70 | - -#### 不同数据分布的增量同步性能测试对比 - -| sysbench 语句类型| DM relay log 持久化速率 (MB/s) | DM 内部 job tps | DM 事务执行时间 (ms) | TiDB qps | TiDB 99 duration (ms) | -| :--------------: | :----------------------------: | :-------------: | :------------------: | :------: | :-------------------: | -| insert_only | 11.3 | 23345 | 28 | 29.2k | 10 | -| write_only | 18.7 | 33470 | 129 | 34.6k | 11 | - -## 推荐同步任务参数配置 - -### dump 处理单元 - -推荐每一条插入语句的大小在 200KB ~ 1MB 之间，相应每条语句包含的行数大约在 1000-5000（具体包含的语句行数与实际场景中每行数据大小有关）。 - -### load 处理单元 - -推荐 `pool-size` 设置为 16。 - -### sync 处理单元 - -推荐将 `batch` 设置为 100，`worker-count` 设置为 16 ~ 32。 diff --git a/v3.1/benchmark/how-to-run-sysbench.md b/v3.1/benchmark/how-to-run-sysbench.md deleted file mode 100644 index 29a464ef973a..000000000000 --- a/v3.1/benchmark/how-to-run-sysbench.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: 如何用 Sysbench 测试 TiDB -category: benchmark ---- - -# 如何用 Sysbench 测试 TiDB - -本次测试使用的是 TiDB 3.0 Beta 和 Sysbench 1.0.14。建议使用 Sysbench 1.0 或之后的更新版本，可在 [Sysbench Release 1.0.14 页面](https://github.com/akopytov/sysbench/releases/tag/1.0.14)下载。 - -## 测试环境 - -- [硬件要求](/v3.1/how-to/deploy/hardware-recommendations.md) - -- 参考 [TiDB 部署文档](/v3.1/how-to/deploy/orchestrated/ansible.md)部署 TiDB 集群。在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD，和 1 个 TiKV 实例。关于磁盘，以 32 张表、每张表 10M 行数据为例，建议 TiKV 的数据目录所在的磁盘空间大于 512 GB。 - 对于单个 TiDB 的并发连接数，建议控制在 500 以内，如需增加整个系统的并发压力，可以增加 TiDB 实例，具体增加的 TiDB 个数视测试压力而定。 - -IDC 机器： - -| 类别 | 名称 | -|:---- |:---- | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel® Xeon® CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Intel Optane SSD P4800X 375G * 1 | -| NIC | 10Gb Ethernet | - -## 测试方案 - -### TiDB 版本信息 - -| 组件 | GitHash | -|:---- |:---- | -| TiDB | 7a240818d19ae96e4165af9ea35df92466f59ce6 | -| TiKV | e26ceadcdfe94fb6ff83b5abb614ea3115394bcd | -| PD | 5e81548c3c1a1adab056d977e7767307a39ecb70 | - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|:---- |:---- | -| 172.16.30.31 | 3*sysbench | -| 172.16.30.33 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.34 | 1\*tidb 1\*pd 1\*tikv | -| 172.16.30.35 | 1\*tidb 1\*pd 1\*tikv | - -### TiDB 配置 - -升高日志级别，可以减少打印日志数量，对 TiDB 的性能有积极影响。开启 TiDB 配置中的 `prepared plan cache`，以减少优化执行计划的开销。具体在 TiDB 配置文件中加入： - -```toml -[log] -level = "error" -[prepared-plan-cache] -enabled = true -``` - -### TiKV 配置 - -升高 TiKV 的日志级别同样有利于提高性能表现。 - -由于 TiKV 是以集群形式部署的，在 Raft 算法的作用下，能保证大多数节点已经写入数据。因此，除了对数据安全极端敏感的场景之外，raftstore 中的 `sync-log` 选项可以关闭。 - -TiKV 集群存在两个 Column Family（Default CF 和 Write CF），主要用于存储不同类型的数据。对于 Sysbench 测试，导入数据的 Column Family 在 TiDB 集群中的比例是固定的。这个比例是： - -Default CF : Write CF = 4 : 1 - -在 TiKV 中需要根据机器内存大小配置 RocksDB 的 block cache，以充分利用内存。以 40 GB 内存的虚拟机部署一个 TiKV 为例，其 block cache 建议配置如下: - -```toml -log-level = "error" -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "24GB" -[rocksdb.writecf] -block-cache-size = "6GB" -``` - -对于 3.0 及以后的版本，还可以使用共享 block cache 的方式进行设置： - -```toml -log-level = "error" -[raftstore] -sync-log = false -[storage.block-cache] -capacity = "30GB" -``` - -更详细的 TiKV 参数调优请参考 [TiKV 性能参数调优](/v3.1/reference/performance/tune-tikv.md)。 - -## 测试过程 - -> **注意：** -> -> 此次测试并没有使用如 HAproxy 等负载均衡工具。在 TiDB 单一节点上进行 Sysbench 测试，并把结果相加。负载均衡工具和不同版本参数也会影响性能表现。 - -### Sysbench 配置 - -以下为 Sysbench 配置文件样例： - -```txt -mysql-host={TIDB_HOST} -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads={8, 16, 32, 64, 128, 256} -report-interval=10 -db-driver=mysql -``` - -可根据实际需求调整其参数，其中 `TIDB_HOST` 为 TiDB server 的 IP 地址（配置文件中不能写多个地址），`threads` 为测试中的并发连接数，可在 “8, 16, 32, 64, 128, 256” 中调整，导入数据时，建议设置 threads = 8 或者 16。调整后，将该文件保存为名为 **config** 的文件。 - -**配置文件**参考示例如下： - -```txt -mysql-host=172.16.30.33 -mysql-port=4000 -mysql-user=root -mysql-password=password -mysql-db=sbtest -time=600 -threads=16 -report-interval=10 -db-driver=mysql -``` - -### 数据导入 - -在数据导入前，需要对 TiDB 进行简单设置。在 MySQL 客户端中执行如下命令： - -{{< copyable "sql" >}} - -```sql -set global tidb_disable_txn_auto_retry = off; -``` - -然后退出客户端。TiDB 使用乐观事务模型，当发现并发冲突时，会回滚事务。将 `tidb_disable_txn_auto_retry` 设置为 `off` 会开启事务冲突后的自动重试机制，可以尽可能避免事务冲突报错导致 Sysbench 程序退出的问题。 - -重新启动 MySQL 客户端执行以下 SQL 语句，创建数据库 `sbtest`： - -{{< copyable "sql" >}} - -```sql -create database sbtest; -``` - -调整 Sysbench 脚本创建索引的顺序。Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。该方式对于 TiDB 需要花费更多的导入时间。用户可以通过调整顺序来加速数据的导入。 - -假设用户使用的 [Sysbench](https://github.com/akopytov/sysbench/tree/1.0.14) 版本。我们可以通过以下两种方式来修改。 - -1. 直接下载为 TiDB 修改好的 [oltp_common.lua](https://raw.githubusercontent.com/pingcap/tidb-bench/master/sysbench/sysbench-patch/oltp_common.lua) 文件，覆盖 `/usr/share/sysbench/oltp_common.lua` 文件。 -2. 将 `/usr/share/sysbench/oltp_common.lua` 的第 [235](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L235) 行到第 [240](https://github.com/akopytov/sysbench/blob/1.0.14/src/lua/oltp_common.lua#L240) 行移动到第 198 行以后。 - -> **注意：** -> -> 此操作为可选操作，仅节约了数据导入时间。 - -命令行输入以下命令，开始导入数据，config 文件为上一步中配置的文件： - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 prepare -``` - -### 数据预热与统计信息收集 - -数据预热可将磁盘中的数据载入内存的 block cache 中，预热后的数据对系统整体的性能有较大的改善，建议在每次重启集群后进行一次数据预热。 - -Sysbench 1.0.14 没有提供数据预热的功能，因此需要手动进行数据预热。如果使用更新的 Sysbench 版本，可以使用自带的预热功能。 - -以 Sysbench 中某张表 sbtest7 为例，执行如下 SQL 语句 进行数据预热： - -{{< copyable "sql" >}} - -```sql -SELECT COUNT(pad) FROM sbtest7 USE INDEX (k_7); -``` - -统计信息收集有助于优化器选择更为准确的执行计划，可以通过 `analyze` 命令来收集表 sbtest 的统计信息，每个表都需要统计。 - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE sbtest7; -``` - -### Point select 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_point_select --tables=32 --table-size=10000000 run -``` - -### Update index 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_update_index --tables=32 --table-size=10000000 run -``` - -### Read-only 测试命令 - -{{< copyable "shell-regular" >}} - -```bash -sysbench --config-file=config oltp_read_only --tables=32 --table-size=10000000 run -``` - -## 测试结果 - -测试了数据 32 表，每表有 10M 数据。 - -对每个 tidb-server 进行了 Sysbench 测试，将结果相加，得出最终结果： - -### oltp_point_select - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| point_select | 3\*8 | 67502.55 | 67502.55 | 0.36 | 0.42 | 141.92 | -| point_select | 3\*16 | 120141.84 | 120141.84 | 0.40 | 0.52 | 20.99 | -| point_select | 3\*32 | 170142.92 | 170142.92 | 0.58 | 0.99 | 28.08 | -| point_select | 3\*64 | 195218.54 | 195218.54 | 0.98 | 2.14 | 21.82 | -| point_select | 3\*128 | 208189.53 | 208189.53 | 1.84 | 4.33 | 31.02 | - -![oltp_point_select](/media/oltp_point_select.png) - -### oltp_update_index - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_update_index | 3\*8 | 9668.98 | 9668.98 | 2.51 | 3.19 | 103.88| -| oltp_update_index | 3\*16 | 12834.99 | 12834.99 | 3.79 | 5.47 | 176.90 | -| oltp_update_index | 3\*32 | 15955.77 | 15955.77 | 6.07 | 9.39 | 4787.14 | -| oltp_update_index | 3\*64 | 18697.17 | 18697.17 | 10.34 | 17.63 | 4539.04 | -| oltp_update_index | 3\*128 | 20446.81 | 20446.81 | 18.98 | 40.37 | 5394.75 | -| oltp_update_index | 3\*256 | 23563.03 | 23563.03 | 32.86 | 78.60 | 5530.69 | - -![oltp_update_index](/media/oltp_update_index.png) - -### oltp_read_only - -| 类型 | Thread | TPS | QPS | avg.latency(ms) | .95.latency(ms) | max.latency(ms) | -|:---- |:---- |:---- |:---- |:----------------|:----------------- |:---- | -| oltp_read_only | 3\*8 | 2411.00 | 38575.96 | 9.92 | 20.00 | 92.23 | -| oltp_read_only | 3\*16 | 3873.53 | 61976.50 | 12.25 | 16.12 | 56.94 | -| oltp_read_only | 3\*32 | 5066.88 | 81070.16 | 19.42 | 26.20 | 123.41 | -| oltp_read_only | 3\*64 | 5466.36 | 87461.81 | 34.65 | 63.20 | 231.19 | -| oltp_read_only | 3\*128 | 6684.16 | 106946.59 | 57.29 | 97.55 | 180.85 | - -![oltp_read_only](/media/oltp_read_only.png) - -## 常见问题 - -### 在高并发压力下，TiDB、TiKV 的配置都合理，为什么整体性能还是偏低？ - -这种情况可能与使用了 proxy 有关。可以尝试直接对单个 TiDB 加压，将求和后的结果与使用 proxy 的情况进行对比。 - -以 HAproxy 为例。`nbproc` 参数可以增加其最大启动的进程数，较新版本的 HAproxy 还支持 `nbthread` 和 `cpu-map` 等。这些都可以减少对其性能的不利影响。 - -### 在高并发压力下，为什么 TiKV 的 CPU 利用率依然很低？ - -TiKV 虽然整体 CPU 偏低，但部分模块的 CPU 可能已经达到了很高的利用率。 - -TiKV 的其他模块，如 storage readpool、coprocessor 和 gRPC 的最大并发度限制是可以通过 TiKV 的配置文件进行调整的。 - -通过 Grafana 的 TiKV Thread CPU 监控面板可以观察到其实际使用率。如出现多线程模块瓶颈，可以通过增加该模块并发度进行调整。 - -### 在高并发压力下，TiKV 也未达到 CPU 使用瓶颈，为什么 TiDB 的 CPU 利用率依然很低？ - -在某些高端设备上，使用的是 NUMA 架构的 CPU，跨 CPU 访问远端内存将极大降低性能。TiDB 默认将使用服务器所有 CPU，goroutine 的调度不可避免地会出现跨 CPU 内存访问。 - -因此，建议在 NUMA 架构服务器上，部署 *n* 个 TiDB（*n* = NUMA CPU 的个数），同时将 TiDB 的 `max-procs` 变量的值设置为与 NUMA CPU 的核数相同。 diff --git a/v3.1/benchmark/how-to-run-tpcc.md b/v3.1/benchmark/how-to-run-tpcc.md deleted file mode 100644 index f3bc7f631543..000000000000 --- a/v3.1/benchmark/how-to-run-tpcc.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: 如何对 TiDB 进行 TPC-C 测试 -category: benchmark ---- - -# 如何对 TiDB 进行 TPC-C 测试 - -本文介绍如何对 TiDB 进行 [TPC-C](http://www.tpc.org/tpcc/) 测试。 - -## 准备测试程序 - -TPC-C 是一个对 OLTP（联机交易处理）系统进行测试的规范，使用一个商品销售模型对 OLTP 系统进行测试，其中包含五类事务： - -* NewOrder – 新订单的生成 -* Payment – 订单付款 -* OrderStatus – 最近订单查询 -* Delivery – 配送 -* StockLevel – 库存缺货状态分析 - -在测试开始前，TPC-C Benchmark 规定了数据库的初始状态，也就是数据库中数据生成的规则，其中 ITEM 表中固定包含 10 万种商品，仓库的数量可进行调整，假设 WAREHOUSE 表中有 W 条记录，那么： - -* STOCK 表中应有 W \* 10 万条记录（每个仓库对应 10 万种商品的库存数据） -* DISTRICT 表中应有 W \* 10 条记录（每个仓库为 10 个地区提供服务） -* CUSTOMER 表中应有 W \* 10 \* 3000 条记录（每个地区有 3000 个客户） -* HISTORY 表中应有 W \* 10 \* 3000 条记录（每个客户一条交易历史） -* ORDER 表中应有 W \* 10 \* 3000 条记录（每个地区 3000 个订单），并且最后生成的 900 个订单被添加到 NEW-ORDER 表中，每个订单随机生成 5 ~ 15 条 ORDER-LINE 记录。 - -我们将以 1000 WAREHOUSE 为例进行测试。 - -TPC-C 使用 tpmC 值（Transactions per Minute）来衡量系统最大有效吞吐量 (MQTh, Max Qualified Throughput)，其中 Transactions 以 NewOrder Transaction 为准，即最终衡量单位为每分钟处理的新订单数。 - -本文使用开源的 BenchmarkSQL 5.0 作为 TPC-C 测试实现并添加了对 MySQL 协议的支持，可以通过以下命令下载测试程序: - -{{< copyable "shell-regular" >}} - -```shell -git clone -b 5.0-mysql-support-opt-2.1 https://github.com/pingcap/benchmarksql.git -``` - -安装 java 和 ant，以 CentOS 为例，可以执行以下命令进行安装 - -{{< copyable "shell-regular" >}} - -```shell -sudo yum install -y java ant -``` - -进入 benchmarksql 目录并执行 ant 构建 - -{{< copyable "shell-regular" >}} - -```shell -cd benchmarksql -ant -``` - -## 部署 TiDB 集群 - -对于 1000 WAREHOUSE 我们将在 3 台服务器上部署集群。 - -在 3 台服务器的条件下，建议每台机器部署 1 个 TiDB，1 个 PD 和 1 个 TiKV 实例。 - -比如这里采用的机器硬件配置是： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD | - -因为该型号 CPU 是 NUMA 架构，建议先用 `taskset` 进行绑核，首先用 `lscpu` 查看 NUMA node，比如： - -```text -NUMA node0 CPU(s): 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 -NUMA node1 CPU(s): 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 -``` - -之后可以通过下面的命令来启动 TiDB： - -{{< copyable "shell-regular" >}} - -```shell -nohup taskset -c 0,2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38 bin/tidb-server && \ -nohup taskset -c 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39 bin/tidb-server -``` - -最后，可以选择部署一个 HAproxy 来进行多个 TiDB node 的负载均衡，推荐配置 nbproc 为 CPU 核数。 - -## 配置调整 - -### TiDB 配置 - -```toml -[log] -level = "error" - -[performance] -# 根据 NUMA 配置，设置单个 TiDB 最大使用的 CPU 核数 -max-procs = 20 - -[prepared_plan_cache] -# 开启 TiDB 配置中的 prepared plan cache，以减少优化执行计划的开销 -enabled = true -``` - -### TiKV 配置 - -开始可以使用基本的配置，压测运行后可以通过观察 Grafana 并参考 [TiKV 调优说明](/v3.1/reference/performance/tune-tikv.md)进行调整。 - -### BenchmarkSQL 配置 - -修改 `benchmarksql/run/props.mysql`： - -```text -conn=jdbc:mysql://{HAPROXY-HOST}:{HAPROXY-PORT}/tpcc?useSSL=false&useServerPrepStmts=true&useConfigs=maxPerformance -warehouses=1000 # 使用 1000 个 warehouse -terminals=500 # 使用 500 个终端 -loadWorkers=32 # 导入数据的并发数 -``` - -## 导入数据 - -**导入数据通常是整个 TPC-C 测试中最耗时，也是最容易出问题的阶段。** - -首先用 MySQL 客户端连接到 TiDB-Server 并执行： - -{{< copyable "sql" >}} - -```sql -create database tpcc -``` - -之后在 shell 中运行 BenchmarkSQL 建表脚本： - -{{< copyable "shell-regular" >}} - -```shell -cd run && \ -./runSQL.sh props.mysql sql.mysql/tableCreates.sql && \ -./runSQL.sh props.mysql sql.mysql/indexCreates.sql -``` - -### 直接使用 BenchmarkSQL 导入 - -运行导入数据脚本： - -{{< copyable "shell-regular" >}} - -```shell -./runLoader.sh props.mysql -``` - -根据机器配置这个过程可能会持续几个小时。 - -### 通过 TiDB Lightning 导入 - -由于导入数据量随着 warehouse 的增加而增加，当需要导入 1000 warehouse 以上数据时，可以先用 BenchmarkSQL 生成 csv 文件，再将文件通过 TiDB Lightning（以下简称 Lightning）导入的方式来快速导入。生成的 csv 文件也可以多次复用，节省每次生成所需要的时间。 - -#### 修改 BenchmarkSQL 的配置文件 - -1 warehouse 的 csv 文件需要 77 MB 磁盘空间，在生成之前要根据需要分配足够的磁盘空间来保存 csv 文件。可以在 `benchmarksql/run/props.mysql` 文件中增加一行： - -```text -fileLocation=/home/user/csv/ # 存储 csv 文件的目录绝对路径，需保证有足够的空间 -``` - -因为最终要使用 Lightning 导入数据，所以 csv 文件名最好符合 Lightning 要求，即 `{database}.{table}.csv` 的命名法。这里可以将以上配置改为： - -```text -fileLocation=/home/user/csv/tpcc. # 存储 csv 文件的目录绝对路径 + 文件名前缀（database） -``` - -这样生成的 csv 文件名将会是类似 `tpcc.bmsql_warehouse.csv` 的样式，符合 Lightning 的要求。 - -#### 生成 csv 文件 - -{{< copyable "shell-regular" >}} - -```shell -./runLoader.sh props.mysql -``` - -#### 通过 Lightning 导入 - -通过 Lightning 导入数据请参考 [Lightning 部署执行](/v3.1/reference/tools/tidb-lightning/deployment.md)章节。这里我们介绍下通过 tidb-ansible 部署 Lightning 导入数据的方法。 - -##### 修改 inventory.ini - -这里最好手动指定清楚部署的 IP、端口、目录，避免各种冲突问题带来的异常，其中 import_dir 的磁盘空间参考 [Lightning 部署执行](/v3.1/reference/tools/tidb-lightning/deployment.md)，data_source_dir 就是存储上一节 csv 数据的目录。 - -```ini -[importer_server] -IS1 ansible_host=172.16.5.34 deploy_dir=/data2/is1 tikv_importer_port=13323 import_dir=/data2/import - -[lightning_server] -LS1 ansible_host=172.16.5.34 deploy_dir=/data2/ls1 tidb_lightning_pprof_port=23323 data_source_dir=/home/user/csv -``` - -##### 修改 conf/tidb-lightning.yml - -```yaml -mydumper: - no-schema: true - csv: - separator: ',' - delimiter: '' - header: false - not-null: false - 'null': 'NULL' - backslash-escape: true - trim-last-separator: false -``` - -##### 部署 Lightning 和 Importer - -{{< copyable "shell-regular" >}} - -```shell -ansible-playbook deploy.yml --tags=lightning -``` - -##### 启动 - -* 登录到部署 Lightning 和 Importer 的服务器 -* 进入部署目录 -* 在 Importer 目录下执行 `scripts/start_importer.sh`，启动 Importer -* 在 Lightning 目录下执行 `scripts/start_lightning.sh`，开始导入数据 - -由于是用 ansible 进行部署的，可以在监控页面看到 Lightning 的导入进度，或者通过日志查看导入是否结束。 - -### 导入完成后 - -数据导入完成之后，可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句都返回结果为空，即为数据导入正确。 - -## 运行测试 - -执行 BenchmarkSQL 测试脚本： - -{{< copyable "shell-regular" >}} - -```shell -nohup ./runBenchmark.sh props.mysql &> test.log & -``` - -运行结束后通过 `test.log` 查看结果： - -```text -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmC (NewOrders) = 77373.25 -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Measured tpmTOTAL = 171959.88 -07:09:53,455 [Thread-351] INFO jTPCC : Term-00, Session Start = 2019-03-21 07:07:52 -07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Session End = 2019-03-21 07:09:53 -07:09:53,456 [Thread-351] INFO jTPCC : Term-00, Transaction Count = 345240 -``` - -tpmC 部分即为测试结果。 - -测试完成之后，也可以运行 `sql.common/test.sql` 进行数据正确性验证，如果所有 SQL 语句的返回结果都为空，即为数据测试过程正确。 diff --git a/v3.1/benchmark/sysbench-in-k8s.md b/v3.1/benchmark/sysbench-in-k8s.md deleted file mode 100644 index 84aabca85fa9..000000000000 --- a/v3.1/benchmark/sysbench-in-k8s.md +++ /dev/null @@ -1,449 +0,0 @@ ---- -title: TiDB in Kubernetes Sysbench 性能测试 -category: benchmark ---- - -# TiDB in Kubernetes Sysbench 性能测试 - -随着 [TiDB Operator GA 发布](https://pingcap.com/blog-cn/tidb-operator-1.0-ga/)，越来越多用户开始使用 TiDB Operator 在 Kubernetes 中部署管理 TiDB 集群。在本次测试中，我们选择 GKE 平台做了一次深入、全方位的测试，方便大家了解 TiDB 在 Kubernetes 中性能影响因素。 - -## 目的 - -- 测试典型公有云平台上 TiDB 性能数据 -- 测试公有云平台磁盘、网络、CPU 以及不同 Pod 网络下对 TiDB 性能的影响 - -## 环境 - -### 版本与配置 - -本次测试统一使用 TiDB v3.0.1 版本进行测试。 - -TiDB Operator 使用 v1.0.0 版本。 - -PD、TiDB 和 TiKV 实例数均为 3 个。各组件分别作了如下配置，未配置部分使用默认值。 - -PD: - -```toml -[log] -level = "info" -[replication] -location-labels = ["region", "zone", "rack", "host"] -``` - -TiDB: - -```toml -[log] -level = "error" -[prepared-plan-cache] -enabled = true -[tikv-client] -max-batch-wait-time = 2000000 -``` - -TiKV: - -```toml -log-level = "error" -[server] -status-addr = "0.0.0.0:20180" -grpc-concurrency = 6 -[readpool.storage] -normal-concurrency = 10 -[rocksdb.defaultcf] -block-cache-size = "14GB" -[rocksdb.writecf] -block-cache-size = "8GB" -[rocksdb.lockcf] -block-cache-size = "1GB" -[raftstore] -apply-pool-size = 3 -store-pool-size = 3 -``` - -### TiDB 数据库参数配置 - -``` -set global tidb_hashagg_final_concurrency=1; -set global tidb_hashagg_partial_concurrency=1; -set global tidb_disable_txn_auto_retry=0; -``` - -### 硬件配置 - -#### 机器型号 - -在单可用区测试中，我们选择了如下型号机器： - -| 组件 | 实例类型 | 数量 | -| :--- | :--------- | :---- | -| PD | n1-standard-4 | 3 | -| TiKV | c2-standard-16 | 3 | -| TiDB | c2-standard-16 | 3 | -| Sysbench | c2-standard-30 | 1 | - -分别在多可用区和单可用区中对 TiDB 进行性能测试，并将结果相对比。在测试时 (2019.08)，一个 GCP 区域 (Region) 下不存在三个能同时提供 c2 机器的可用区，所以我们选择了如下机器型号进行测试： - -| 组件 | 实例类型 | 数量 | -| :--- | :--------- | :---- | -| PD | n1-standard-4 | 3 | -| TiKV | n1-standard-16 | 3 | -| TiDB | n1-standard-16 | 3 | -| Sysbench | n1-standard-16 | 3 | - -在高并发读测试中，压测端 sysbench 对 CPU 需求较高，需选择多核较高配置型号，避免压测端成为瓶颈。 - -> **注意：** -> -> GCP 不同的区域可用机型不同。同时测试中发现磁盘性能表现也存在差异，我们统一在 us-central1 中申请机器测试。 - -#### 磁盘 - -GKE 当前的 NVMe 磁盘还在 Alpha 阶段，使用需特殊申请，不具备普遍意义。测试中，本地 SSD 盘统一使用 iSCSI 接口类型。挂载参数参考[官方建议](https://cloud.google.com/compute/docs/disks/performance#optimize_local_ssd)增加了 `discard,nobarrier` 选项。完整挂载例子如下： - -``` -sudo mount -o defaults,nodelalloc,noatime,discard,nobarrier /dev/[LOCAL_SSD_ID] /mnt/disks/[MNT_DIR] -``` - -#### 网络 - -GKE 网络模式使用具备更好扩展性以及功能强大的 [VPC-Native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips) 模式。在性能对比中，我们分别对 TiDB 使用 Kubernetes Pod 和 Host 网络分别做了测试。 - -#### CPU - -在单可用集群测试中，我们为 TiDB/TiKV 选择 c2-standard-16 机型测试。在单可用与多可用集群的对比测试中，因为 GCP 区域 (Region) 下不存在三个能同时申请 c2-standard-16 机型的可用区，所以我们选择了 n1-standard-16 机型测试。 - -### 操作系统及参数 - -GKE 支持两种操作系统：COS (Container Optimized OS) 和 Ubuntu 。Point Select 测试在两种操作系统中进行，并将结果进行了对比。其余测试中，统一使用 Ubuntu 系统进行测试。 - -内核统一做了如下配置: - -```shell -sysctl net.core.somaxconn=32768 -sysctl vm.swappiness=0 -sysctl net.ipv4.tcp_syncookies=0 -``` - -同时对最大文件数配置为 1000000。 - -### Sysbench 版本与运行参数 - -本次测试中 sysbench 版本为 1.0.17。并在测试前统一使用 `oltp_common` 的 `prewarm` 命令进行数据预热。 - -#### 初始化 - -```shell -sysbench \ - --mysql-host= \ - --mysql-port=4000 \ - --mysql-user=root \ - --mysql-db=sbtest \ - --time=600 \ - --threads=16 \ - --report-interval=10 \ - --db-driver=mysql \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --tables=16 \ - --table-size=10000000 \ - oltp_common \ - prepare -``` - -`` 为 TiDB 的数据库地址，根据不同测试需求选择不同的地址，比如 Pod IP、Service 域名、Host IP 以及 Load Balancer IP（下同）。 - -#### 预热 - -```shell -sysbench \ - --mysql-host= \ - --mysql-port=4000 \ - --mysql-user=root \ - --mysql-db=sbtest \ - --time=600 \ - --threads=16 \ - --report-interval=10 \ - --db-driver=mysql \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --tables=16 \ - --table-size=10000000 \ - oltp_common \ - prewarm -``` - -#### 压测 - -```shell -sysbench \ - --mysql-host= \ - --mysql-port=4000 \ - --mysql-user=root \ - --mysql-db=sbtest \ - --time=600 \ - --threads= \ - --report-interval=10 \ - --db-driver=mysql \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --tables=16 \ - --table-size=10000000 \ - \ - run -``` - -`` 为 sysbench 的测试 case。我们选择了 oltp_point_select、oltp_update_index、oltp_update_no_index、oltp_read_write 这几种。 - -## 测试报告 - -### 单可用区测试 - -#### Pod Network vs Host Network - -Kubernetes 允许 Pod 运行在 Host 网络模式下。此部署方式适用于 TiDB 实例独占机器且没有端口冲突的情况。我们分别在两种网络模式下做了 Point Select 测试。 - -此次测试中，操作系统为 COS。 - -Pod Network: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 246386.44 | 0.95 | -| 300 | 346557.39 | 1.55 | -| 600 | 396715.66 | 2.86 | -| 900 | 407437.96 | 4.18 | -| 1200 | 415138.00 | 5.47 | -| 1500 | 419034.43 | 6.91 | - -Host Network: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 255981.11 | 1.06 | -| 300 | 366482.22 | 1.50 | -| 600 | 421279.84 | 2.71 | -| 900 | 438730.81 | 3.96 | -| 1200 | 441084.13 | 5.28 | -| 1500 | 447659.15 | 6.67 | - -QPS 对比： - -![Pod vs Host Network](/media/sysbench-in-k8s/pod-vs-host-network-qps.png) - -Latency 对比： - -![Pod vs Host Network](/media/sysbench-in-k8s/pod-vs-host-network-latency.png) - -从图中可以看到 Host 网络下整体表现略好于 Pod 网络。 - -#### Ubuntu vs COS - -GKE 平台可以为节点选择 [Ubuntu 和 COS 两种操作系统](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images)。本次测试中，分别在两种操作系统中进行了 Point Select 测试。 - -此次测试中 Pod 网络模式为 Host。 - -COS: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 255981.11 | 1.06 | -| 300 | 366482.22 | 1.50 | -| 600 | 421279.84 | 2.71 | -| 900 | 438730.81 | 3.96 | -| 1200 | 441084.13 | 5.28 | -| 1500 | 447659.15 | 6.67 | - -Ubuntu: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 290690.51 | 0.74 | -| 300 | 422941.17 | 1.10 | -| 600 | 476663.44 | 2.14 | -| 900 | 484405.99 | 3.25 | -| 1200 | 489220.93 | 4.33 | -| 1500 | 489988.97 | 5.47 | - -QPS 对比： - -![COS vs Ubuntu](/media/sysbench-in-k8s/cos-vs-ubuntu-qps.png) - -Latency 对比： - -![COS vs Ubuntu](/media/sysbench-in-k8s/cos-vs-ubuntu-latency.png) - -从图中可以看到 Host 模式下，在单纯的 Point Select 测试中，TiDB 在 Ubuntu 系统中的表现比在 COS 系统中的表现要好。 - -> **注意：** -> -> 此测试只针对单一测试集进行了测试，表明不同的操作系统、不同的优化与默认设置，都有可能影响性能，所以我们在此不对操作系统做推荐。COS 系统专为容器优化，在安全性、磁盘性能做了优化，在 GKE 是官方推荐系统。 - -#### K8S Service vs GCP LoadBalancer - -通过 Kubernetes 部署 TiDB 集群后，有两种访问 TiDB 集群的场景：集群内通过 Service 访问或集群外通过 Load Balancer IP 访问。本次测试中分别对这两种情况进行了对比测试。 - -此次测试中操作系统为 Ubuntu，Pod 为 Host 网络。 - -Service: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 290690.51 | 0.74 | -| 300 | 422941.17 | 1.10 | -| 600 | 476663.44 | 2.14 | -| 900 | 484405.99 | 3.25 | -| 1200 | 489220.93 | 4.33 | -| 1500 | 489988.97 | 5.47 | - -Load Balancer: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 255981.11 | 1.06 | -| 300 | 366482.22 | 1.50 | -| 600 | 421279.84 | 2.71 | -| 900 | 438730.81 | 3.96 | -| 1200 | 441084.13 | 5.28 | -| 1500 | 447659.15 | 6.67 | - -QPS 对比： - -![Service vs Load Balancer](/media/sysbench-in-k8s/service-vs-load-balancer-qps.png) - -Latency 对比： - -![Service vs Load Balancer](/media/sysbench-in-k8s/service-vs-load-balancer-latency.png) - -从图中可以看到在单纯的 Point Select 测试中，使用 Kubernetes Service 访问 TiDB 时的表现比使用 GCP Load Balancer 访问时要好。 - -#### n1-standard-16 vs c2-standard-16 - -在 Point Select 读测试中，TiDB 的 CPU 占用首先达到 1400% (16 cores) 以上，此时 TiKV CPU 占用约 1000% (16 cores) 。我们对比了普通型和计算优化型机器下 TiDB 的不同表现。其中 n1-stadnard-16 主频约 2.3G，c2-standard-16 主频约 3.1G。 - -此次测试中操作系统为 Ubuntu，Pod 为 Host 网络，使用 Service 访问 TiDB。 - -n1-standard-16: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 203879.49 | 1.37 | -| 300 | 272175.71 | 2.3 | -| 600 | 287805.13 | 4.1 | -| 900 | 295871.31 | 6.21 | -| 1200 | 294765.83 | 8.43 | -| 1500 | 298619.31 | 10.27 | - -c2-standard-16: - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 290690.51 | 0.74 | -| 300 | 422941.17 | 1.10 | -| 600 | 476663.44 | 2.14 | -| 900 | 484405.99 | 3.25 | -| 1200 | 489220.93 | 4.33 | -| 1500 | 489988.97 | 5.47 | - -QPS 对比： - -![n1-standard-16 vs c2-standard-16](/media/sysbench-in-k8s/n1-standard-16-vs-c2-standard-16-qps.png) - -Latency 对比： - -![n1-standard-16 vs c2-standard-16](/media/sysbench-in-k8s/n1-standard-16-vs-c2-standard-16-latency.png) - -### OLTP 其他测试 - -使用 Point Select 测试针对不同操作系统、不同网络情况做了对比测试后，也进行了 OLTP 测试集中的其他测试。这些测试统一使用 Ubuntu 系统、Host 模式并在集群使用 Service 访问 TiDB 集群。 - -#### OLTP Update Index - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 6726.59 | 30.26 | -| 300 | 11067.55 | 36.24 | -| 600 | 17358.46 | 48.34 | -| 900 | 21025.23 | 64.47 | -| 1200 | 22121.87 | 90.78 | -| 1500 | 22650.13 | 118.92 | - -![OLTP Update Index](/media/sysbench-in-k8s/oltp-update-index-qps.png) -![OLTP Update Index](/media/sysbench-in-k8s/oltp-update-index-latency.png) - -#### OLTP Update Non Index - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 9230.60 | 23.95 | -| 300 | 16543.63 | 54.83 | -| 600 | 23551.01 | 61.08 | -| 900 | 31100.10 | 65.65 | -| 1200 | 33942.60 | 54.83 | -| 1500 | 42603.13 | 125.52 | - -![OLTP Update No Index](/media/sysbench-in-k8s/oltp-update-no-index-qps.png) -![OLTP Update No Index](/media/sysbench-in-k8s/oltp-update-no-index-latency.png) - -#### OLTP Read Write - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 60732.84 | 69.29 | -| 300 | 91005.98 | 90.78 | -| 600 | 110517.67 | 167.44 | -| 900 | 119866.38 | 235.74 | -| 1200 | 125615.89 | 282.25 | -| 1500 | 128501.34 | 344.082 | - -![OLTP Read Write](/media/sysbench-in-k8s/oltp-read-write-qps.png) -![OLTP Read Write](/media/sysbench-in-k8s/oltp-read-write-latency.png) - -### 单可用区与多可用区对比 - -GCP 多可用区涉及跨 Zone 通信，网络延迟相比同 Zone 会少许增加。我们使用同样机器配置，对两种部署方案进行同一标准下的性能测试，了解多可用区延迟增加带来的影响。 - -单可用区： - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 203879.49 | 1.37 | -| 300 | 272175.71 | 2.30 | -| 600 | 287805.13 | 4.10 | -| 900 | 295871.31 | 6.21 | -| 1200 | 294765.83 | 8.43 | -| 1500 | 298619.31 | 10.27 | - -多可用区： - -| Threads | QPS | 95% latency(ms) | -| :------ | :-------- | :-------------- | -| 150 | 141027.10 | 1.93 | -| 300 | 220205.85 | 2.91 | -| 600 | 250464.34 | 5.47 | -| 900 | 257717.41 | 7.70 | -| 1200 | 258835.24 | 10.09 | -| 1500 | 280114.00 | 12.75 | - -QPS 对比： - -![Single Zonal vs Regional](/media/sysbench-in-k8s/single-zonal-vs-regional-qps.png) - -Latency 对比： - -![Single Zonal vs Regional](/media/sysbench-in-k8s/single-zonal-vs-regional-latency.png) - -从图中可以看到并发压力增大后，网络额外延迟产生的影响越来越小，额外的网络延迟将不再是主要的性能瓶颈。 - -## 结语 - -此次测试主要将典型公有云部署 Kubernetes 运行 TiDB 集群的几种场景使用 sysbench 做了测试，了解不同因素可能带来的影响。从整体看，主要有以下几点： - -- VPC-Native 模式下 Host 网络性能略好于 Pod 网络（~7%，以 QPS 差异估算，下同） -- GCP 的 Ubuntu 系统 Host 网络下单纯的读测试中性能略好于 COS (~9%) -- 使用 Load Balancer 在集群外访问，会略损失性能 (~5%) -- 多可用区下节点之间延迟增加，会对 TiDB 性能产生一定的影响（30% ~ 6%，随并发数增加而下降） -- Point Select 读测试主要消耗 CPU ，计算型机型相对普通型机器带来了很大 QPS 提升 (50% ~ 60%) - -但要注意的是，这些因素可能随着时间变化，不同公有云下的表现可能会略有不同。在未来，我们将带来更多维度的测试。同时，sysbench 测试用例并不能完全代表实际业务场景，在做选择前建议模拟实际业务测试，并综合不同选择成本进行选择（机器成本、操作系统差异、Host 网络的限制等）。 diff --git a/v3.1/benchmark/sysbench-v2.md b/v3.1/benchmark/sysbench-v2.md deleted file mode 100644 index bce70f8a8400..000000000000 --- a/v3.1/benchmark/sysbench-v2.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 -category: benchmark ---- - -# TiDB Sysbench 性能对比测试报告 - v2.0.0 对比 v1.0.0 - -## 测试目的 - -对比 TiDB 2.0 版本和 1.0 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v1.0.8 Vs v2.0.0-rc6 - -时间：2018 年 4 月 - -地点：北京 - -## 测试环境 - -IDC 机器 - -| 类别 | 名称 | -| :--------: | :---------: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD * 1 | - -## 测试方案 - -### TiDB 版本信息 - -### v1.0.8 - -| 组件 | GitHash | -| :--------: | :---------: | -| TiDB | 571f0bbd28a0b8155a5ee831992c986b90d21ab7 | -| TiKV | 4ef5889947019e3cb55cc744f487aa63b42540e7 | -| PD | 776bcd940b71d295a2c7ed762582bc3aff7d3c0e | - -### v2.0.0-rc6 - -| 组件 | GitHash | -| :--------: | :---------: | -| TiDB | 82d35f1b7f9047c478f4e1e82aa0002abc8107e7 | -| TiKV | 7ed4f6a91f92cad5cd5323aaebe7d9f04b77cc79 | -| PD | 2c8e7d7e33b38e457169ce5dfb2f461fced82d65 | - -### TiKV 参数配置 - -* v1.0.8 - - ``` - sync-log = false - grpc-concurrency = 8 - grpc-raft-conn-num = 24 - ``` - -* v2.0.0-rc6 - - ``` - sync-log = false - grpc-concurrency = 8 - grpc-raft-conn-num = 24 - use-delete-range: false - ``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -|--------------|------------| -| 172.16.21.1 | 1*tidb 1*pd 1*sysbench | -| 172.16.21.2 | 1*tidb 1*pd 1*sysbench | -| 172.16.21.3 | 1*tidb 1*pd 1*sysbench | -| 172.16.11.4 | 1*tikv | -| 172.16.11.5 | 1*tikv | -| 172.16.11.6 | 1*tikv | -| 172.16.11.7 | 1*tikv | -| 172.16.11.8 | 1*tikv | -| 172.16.11.9 | 1*tikv | - -## 测试结果 - -### 标准 Select 测试 - -| 版本 | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 201936 | 1.9033 ms / 5.67667 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 208130 | 3.69333 ms / 8.90333 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 211788 | 7.23333 ms / 15.59 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 212868 | 14.5933 ms / 43.2133 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 188686 | 2.03667 ms / 5.99 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 195090 |3.94 ms / 9.12 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 203012 | 7.57333 ms / 15.3733 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 205932 | 14.9267 ms / 40.7633 ms | - -GA2.0 比 GA1.0 在 Select 查询性能上，最高提升了 10% 左右。 - -### 标准 OLTP 测试 - -| 版本 | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---:| -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 5404.22 | 108084.4 | 87.2033 ms / 110 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 5578.165 | 111563.3 | 167.673 ms / 275.623 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 5874.045 | 117480.9 | 315.083 ms / 674.017 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 6290.7 | 125814 | 529.183 ms / 857.007 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 5523.91 | 110478 | 69.53 ms / 88.6333 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 5969.43 | 119389 |128.63 ms / 162.58 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 6308.93 | 126179 | 243.543 ms / 310.913 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 6444.25 | 128885 | 476.787ms / 635.143 ms | - -GA2.0 比 GA1.0 在 OLTP 性能上，性能基本一致。 - -### 标准 Insert 测试 - -| 版本 | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| v2.0.0-rc6 | 32 | 1000 万 | 128 * 3 | 31707.5 | 12.11 ms / 21.1167 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 256 * 3 | 38741.2 | 19.8233 ms / 39.65 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 512 * 3 | 45136.8 | 34.0267 ms / 66.84 ms | -| v2.0.0-rc6 | 32 | 1000 万 | 1024 * 3 | 48667 | 63.1167 ms / 121.08 ms | -| v1.0.8 | 32 | 1000 万 | 128 * 3 | 31125.7 | 12.3367 ms / 19.89 ms | -| v1.0.8 | 32 | 1000 万 | 256 * 3 | 36800 | 20.8667 ms / 35.3767 ms | -| v1.0.8 | 32 | 1000 万 | 512 * 3 | 44123 | 34.8067 ms / 63.32 ms | -| v1.0.8 | 32 | 1000 万 | 1024 * 3 | 48496 | 63.3333 ms / 118.92 ms | - -GA2.0 比 GA1.0 在 Insert 性能上略有提升。 diff --git a/v3.1/benchmark/sysbench-v3.md b/v3.1/benchmark/sysbench-v3.md deleted file mode 100644 index 35270f2451c3..000000000000 --- a/v3.1/benchmark/sysbench-v3.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 -category: benchmark ---- - -# TiDB Sysbench 性能对比测试报告 - v2.1 对比 v2.0 - -## 测试目的 - -对比 TiDB 2.1 版本和 2.0 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v2.1.0-rc.2 vs. v2.0.6 - -时间：2018 年 9 月 - -地点：北京 - -## 测试环境 - -IDC 机器： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | Optane 500GB SSD \* 1 | - -Sysbench 版本：1.1.0 - -## 测试方案 - -使用 Sysbench 向集群导入 **16 张表，每张数据 1000 万**。通过 HAProxy 代理，分别以递增并发数向集群发送请求，单次并发测试时间 5 分钟。 - -### TiDB 版本信息 - -### v2.1.0-rc.2 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 08e56cd3bae166b2af3c2f52354fbc9818717f62 | -| TiKV | 57e684016dafb17dc8a6837d30224be66cbc7246 | -| PD | 6a7832d2d6e5b2923c79683183e63d030f954563 | - -### v2.0.6 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | b13bc08462a584a085f377625a7bab0cc0351570 | -| TiKV | 57c83dc4ebc93d38d77dc8f7d66db224760766cc | -| PD | b64716707b7279a4ae822be767085ff17b5f3fea | - -### TiDB 参数配置 - -两版本 TiDB 均使用**默认配置**。 - -### TiKV 参数配置 - -两版本 TiKV 均使用如下配置： - -```txt -[readpool.storage] -normal-concurrency = 8 -[server] -grpc-concurrency = 8 -[raftstore] -sync-log = false -[rocksdb.defaultcf] -block-cache-size = "60GB" -[rocksdb.writecf] -block-cache-size = "20GB" -``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-: | :-: | -| 172.16.30.31 | 1\*Sysbench 1\*HAProxy | -| 172.16.30.32 | 1\*TiDB 1\*pd 1\*TiKV | -| 172.16.30.33 | 1\*TiDB 1\*TiKV | -| 172.16.30.34 | 1\*TiDB 1\*TiKV | - -## 测试结果 - -### Point Select 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 111481.09 | 1.16 | -| v2.1 | 128 | 145102.62 | 2.52 | -| v2.1 | 256 | 161311.9 | 4.57 | -| v2.1 | 512 | 184991.19 | 7.56 | -| v2.1 | 1024 | 230282.74 | 10.84 | -| v2.0 | 64 | 75285.87 | 1.93 | -| v2.0 | 128 | 92141.79 | 3.68 | -| v2.0 | 256 | 107464.93 | 6.67 | -| v2.0 | 512 | 121350.61 | 11.65 | -| v2.0 | 1024 | 150036.31 | 17.32 | - -![point select](/media/sysbench_v3_point_select.png) - -v2.1 比 v2.0 在 Point Select 查询性能上，**提升了 50%**。 - -### Update Non-Index 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 18946.09 | 5.77 | -| v2.1 | 128 | 22022.82 | 12.08 | -| v2.1 | 256 | 24679.68 | 25.74 | -| v2.1 | 512 | 25107.1 | 51.94 | -| v2.1 | 1024 | 27144.92 | 106.75 | -| v2.0 | 64 | 16316.85 | 6.91 | -| v2.0 | 128 | 20944.6 | 11.45 | -| v2.0 | 256 | 24017.42 | 23.1 | -| v2.0 | 512 | 25994.33 | 46.63 | -| v2.0 | 1024 | 27917.52 | 92.42 | - -![update non-index](/media/sysbench_v3_update_non_index.png) - -v2.1 与 v2.0 在 Update Non-Index 写入性能上基本一致。 - -### Update Index 测试 - -| 版本 | threads | qps | 95% latency(ms) | -| :-: | :-: | :-: | :-: | -| v2.1 | 64 | 9934.49 | 12.08 | -| v2.1 | 128 | 10505.95 | 25.28 | -| v2.1 | 256 | 11007.7 | 55.82 | -| v2.1 | 512 | 11198.81 | 106.75 | -| v2.1 | 1024 | 11591.89 | 200.47 | -| v2.0 | 64 | 9754.68 | 11.65 | -| v2.0 | 128 | 10603.31 | 24.38 | -| v2.0 | 256 | 11011.71 | 50.11 | -| v2.0 | 512 | 11162.63 | 104.84 | -| v2.0 | 1024 | 12067.63 | 179.94 | - -![update index](/media/sysbench_v3_update_index.png) - -v2.1 与 v2.0 在 Update Index 写入性能上基本一致。 diff --git a/v3.1/benchmark/sysbench-v4.md b/v3.1/benchmark/sysbench-v4.md deleted file mode 100644 index 31175bd29a26..000000000000 --- a/v3.1/benchmark/sysbench-v4.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: TiDB Sysbench 性能对比测试报告 - v3.0 对比 v2.1 -category: benchmark ---- - -# TiDB Sysbench 性能对比测试报告 - v3.0 对比 v2.1 - -## 测试目的 - -对比 TiDB 3.0 版本和 2.1 版本在 OLTP 场景下的性能。 - -## 测试版本、时间、地点 - -TiDB 版本：v3.0.0 vs. v2.1.13 - -时间：2019 年 6 月 - -地点：北京 - -## 测试环境 - -测试在 AWS EC2 上进行，使用 CentOS-7.6.1810-Nitro (ami-028946f4cffc8b916) 镜像，各组件实例类型如下： - -| 组件 | 实例类型 | -| :--- | :--------- | -| PD | r5d.xlarge | -| TiKV | c5d.4xlarge | -| TiDB | c5.4xlarge | - -Sysbench 版本：1.0.17 - -## 测试方案 - -使用 Sysbench 向集群导入 **16 张表，每张数据 1000 万**。起 3 个 sysbench 分别向 3 个 TiDB 发压，请求并发数逐步增加，单次测试时间 5 分钟。 - -准备数据命令： - -{{< copyable "shell-regular" >}} - -```sh -sysbench oltp_common \ - --threads=16 \ - --rand-type=uniform \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - --mysql-password=password \ - prepare --tables=16 --table-size=10000000 -``` - -执行测试命令： - -{{< copyable "shell-regular" >}} - -```sh -sysbench $testname \ - --threads=$threads \ - --time=300 \ - --report-interval=15 \ - --rand-type=uniform \ - --rand-seed=$RANDOM \ - --db-driver=mysql \ - --mysql-db=sbtest \ - --mysql-host=$tidb_host \ - --mysql-port=$tidb_port \ - --mysql-user=root \ - --mysql-password=password \ - run --tables=16 --table-size=10000000 -``` - -### TiDB 版本信息 - -### v3.0.0 - -| 组件 | GitHash | -| :--- | :---------------------------------------- | -| TiDB | `8efbe62313e2c1c42fd76d35c6f020087eef22c2` | -| TiKV | `a467f410d235fa9c5b3c355e3b620f81d3ac0e0c` | -| PD | `70aaa5eee830e21068f1ba2d4c9bae59153e5ca3` | - -### v2.1.13 - -| 组件 | GitHash | -| :--- | :---------------------------------------- | -| TiDB | `6b5b1a6802f9b8f5a22d8aab24ac80729331e1bc` | -| TiKV | `b3cf3c8d642534ea6fa93d475a46da285cc6acbf` | -| PD | `886362ebfb26ef0834935afc57bcee8a39c88e54` | - -### TiDB 参数配置 - -2.1 和 3.0 中开启 prepared plan cache (出于优化考虑，2.1 的 point select 与 read write 并未开启)： - -```toml -[prepared-plan-cache] -enabled = true -``` - -并设置全局变量： - -{{< copyable "sql" >}} - -```sql -set global tidb_hashagg_final_concurrency=1; -set global tidb_hashagg_partial_concurrency=1; -set global tidb_disable_txn_auto_retry=0; -``` - -此外 3.0 还做了如下配置： - -```toml -[tikv-client] -max-batch-wait-time = 2000000 -``` - -### TiKV 参数配置 - -2.1 和 3.0 使用如下配置： - -```toml -log-level = "error" -[readpool.storage] -normal-concurrency = 10 -[server] -grpc-concurrency = 6 -[rocksdb.defaultcf] -block-cache-size = "14GB" -[rocksdb.writecf] -block-cache-size = "8GB" -[rocksdb.lockcf] -block-cache-size = "1GB" -``` - -3.0 还做了如下配置： - -```toml -[raftstore] -apply-pool-size = 3 -store-pool-size = 3 -``` - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-------------------------------------- | :----------| -| 172.31.8.8 | 3 * Sysbench | -| 172.31.7.80, 172.31.5.163, 172.31.11.123 | PD | -| 172.31.4.172, 172.31.1.155, 172.31.9.210 | TiKV | -| 172.31.7.80, 172.31.5.163, 172.31.11.123 | TiDB | - -## 测试结果 - -### Point Select 测试 - -**v2.1** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :------------- | -| 150 | 240304.06 | 1.61 | -| 300 | 276635.75 | 2.97 | -| 600 | 307838.06 | 5.18 | -| 900 | 323667.93 | 7.30 | -| 1200 | 330925.73 | 9.39 | -| 1500 | 336250.38 | 11.65 | - - - -**v3.0** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :-------------- | -| 150 | 334219.04 | 0.64 | -| 300 | 456444.86 | 1.10 | -| 600 | 512177.48 | 2.11 | -| 900 | 525945.13 | 3.13 | -| 1200 | 534577.36 | 4.18 | -| 1500 | 533944.64 | 5.28 | - -![point select](/media/sysbench_v4_point_select.png) - -### Update Non-Index 测试 - -**v2.1** - -| threads | qps | 95% latency(ms) | -| ------- | -------: | --------------: | -| 150 | 21785.37 | 8.58 | -| 300 | 28979.27 | 13.70 | -| 600 | 34629.72 | 24.83 | -| 900 | 36410.06 | 43.39 | -| 1200 | 37174.15 | 62.19 | -| 1500 | 37408.88 | 87.56 | - -**v3.0** - -| threads | qps | 95% latency(ms) | -| ------- | -------: | --------------: | -| 150 | 28045.75 | 6.67 | -| 300 | 39237.77 | 9.91 | -| 600 | 49536.56 | 16.71 | -| 900 | 55963.73 | 22.69 | -| 1200 | 59904.02 | 29.72 | -| 1500 | 62247.95 | 42.61 | - -![update non-index](/media/sysbench_v4_update_non_index.png) - -### Update Index 测试 - -**v2.1** - -| Threads | QPS | 95% latency(ms) | -| :------- | :------- | :-------------- | -| 150 | 14378.24 | 13.22 | -| 300 | 16916.43 | 24.38 | -| 600 | 17636.11 | 57.87 | -| 900 | 17740.92 | 95.81 | -| 1200 | 17929.24 | 130.13 | -| 1500 | 18012.80 | 161.51 | - -**v3.0** - -| Threads | QPS | 95% latency(ms) | -| :------- | :------- | :-------------| -| 150 | 19047.32 | 10.09 | -| 300 | 24467.64 | 16.71 | -| 600 | 28882.66 | 31.94 | -| 900 | 30298.41 | 57.87 | -| 1200 | 30419.40 | 92.42 | -| 1500 | 30643.55 | 125.52 | - -![update index](/media/sysbench_v4_update_index.png) - -### Read Write 测试 - -**v2.1** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :-------------- | -| 150 | 85140.60 | 44.98 | -| 300 | 96773.01 | 82.96 | -| 600 | 105139.81 | 153.02 | -| 900 | 110041.83 | 215.44 | -| 1200 | 113242.70 | 277.21 | -| 1500 | 114542.19 | 337.94 | - - - -**v3.0** - -| Threads | QPS | 95% latency(ms) | -| :------- | :-------- | :-------------- | -| 150 | 105692.08 | 35.59 | -| 300 | 129769.69 | 58.92 | -| 600 | 141430.86 | 114.72 | -| 900 | 144371.76 | 170.48 | -| 1200 | 143344.37 | 223.34 | -| 1500 | 144567.91 | 277.21 | - -![read write](/media/sysbench_v4_read_write.png) diff --git a/v3.1/benchmark/sysbench.md b/v3.1/benchmark/sysbench.md deleted file mode 100644 index 41c6f79e10e0..000000000000 --- a/v3.1/benchmark/sysbench.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: TiDB Sysbench 性能测试报告 - v1.0.0 -category: benchmark -draft: true ---- - -# TiDB Sysbench 性能测试报告 - v1.0.0 - -## 测试目的 - -测试 TiDB 在 OLTP 场景下的性能以及水平扩展能力。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试版本、时间、地点 - -TiDB 版本：v1.0.0 -时间：2017 年 10 月 20 日 -地点：北京 - -## 测试环境 - -IDC 机器 - -| 类别 | 名称 | -| :--------: | :---------: | -| OS | linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | 1.5T SSD \* 2 + Optane SSD \* 1 | - -Sysbench 版本: 1.0.6 - -测试脚本: - -## 测试方案 - -### 场景一：sysbench 标准性能测试 - -测试表结构 - -``` -CREATE TABLE `sbtest` ( - `id` int(10) unsigned NOT NULL AUTO_INCREMENT, - `k` int(10) unsigned NOT NULL DEFAULT '0', - `c` char(120) NOT NULL DEFAULT '', - `pad` char(60) NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB -``` - -部署方案以及配置参数 - -``` -// TiDB 部署方案 -172.16.20.4 4*tikv 1*tidb 1*sysbench -172.16.20.6 4*tikv 1*tidb 1*sysbench -172.16.20.7 4*tikv 1*tidb 1*sysbench -172.16.10.8 1*tidb 1*pd 1*sysbench - -// 每个物理节点有三块盘： -data3: 2 tikv (Optane SSD) -data2: 1 tikv -data1: 1 tikv - -// TiKV 参数配置 -sync-log = false -grpc-concurrency = 8 -grpc-raft-conn-num = 24 -[defaultcf] -block-cache-size = "12GB" -[writecf] -block-cache-size = "5GB" -[raftdb.defaultcf] -block-cache-size = "2GB" - -// Mysql 部署方案 -// 分别使用半同步复制和异步复制，部署两副本 -172.16.20.4 master -172.16.20.6 slave -172.16.20.7 slave -172.16.10.8 1*sysbench -Mysql version: 5.6.37 - -// Mysql 参数配置 -thread_cache_size = 64 -innodb_buffer_pool_size = 64G -innodb_file_per_table = 1 -innodb_flush_log_at_trx_commit = 0 -datadir = /data3/mysql -max_connections = 2000 -``` - -* 标准 oltp 测试 - -| - | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 3834 | 76692 | 67.04 ms / 110.88 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 4172 | 83459 | 124.00 ms / 194.21 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 4577 | 91547 | 228.36 ms / 334.02 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 4032 | 80657 | 256.62 ms / 443.88 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 3811 | 76233 | 269.46 ms / 505.20 ms | -| Mysql | 32 | 100 万 | 64 | 2392 | 47845 | 26.75 ms / 73.13 ms | -| Mysql | 32 | 100 万 | 128 | 2493 | 49874 | 51.32 ms / 173.58 ms | -| Mysql | 32 | 100 万 | 256 | 2561 | 51221 | 99.95 ms / 287.38 ms | -| Mysql | 32 | 500 万 | 256 | 1902 | 38045 | 134.56 ms / 363.18 ms | -| Mysql | 32 | 1000 万 | 256 | 1770 | 35416 | 144.55 ms / 383.33 ms | - -![sysbench-01](/media/sysbench-01.png) - -![sysbench-02](/media/sysbench-02.png) - -* 标准 select 测试 - -| - | table count | table size | sysbench threads |qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 160299 | 1.61ms / 50.06 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 183347 | 2.85 ms / 8.66 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 196515 | 5.42 ms / 14.43 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 187628 | 5.66 ms / 15.04 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 187440 | 5.65 ms / 15.37 ms | -| Mysql | 32 | 100 万 | 64 | 359572 | 0.18 ms / 0.45 ms | -| Mysql | 32 | 100 万 | 128 | 410426 |0.31 ms / 0.74 ms | -| Mysql | 32 | 100 万 | 256 | 396867 | 0.64 ms / 1.58 ms | -| Mysql | 32 | 500 万 | 256 | 386866 | 0.66 ms / 1.64 ms | -| Mysql | 32 | 1000 万 | 256 | 388273 | 0.66 ms / 1.64 ms | - -![sysbench-03](/media/sysbench-03.png) - -![sysbench-04](/media/sysbench-04.png) - -* 标准 insert 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| TiDB | 32 | 100 万 | 64 * 4 | 25308 | 10.12 ms / 25.40 ms | -| TiDB | 32 | 100 万 | 128 * 4 | 28773 | 17.80 ms / 44.58 ms | -| TiDB | 32 | 100 万 | 256 * 4 | 32641 | 31.38 ms / 73.47 ms | -| TiDB | 32 | 500 万 | 256 * 4 | 30430 | 33.65 ms / 79.32 ms | -| TiDB | 32 | 1000 万 | 256 * 4 | 28925 | 35.41 ms / 78.96 ms | -| Mysql | 32 | 100 万 | 64 | 14806 | 4.32 ms / 9.39 ms | -| Mysql | 32 | 100 万 | 128 | 14884 | 8.58 ms / 21.11 ms | -| Mysql | 32 | 100 万 | 256 | 14508 | 17.64 ms / 44.98 ms | -| Mysql | 32 | 500 万 | 256 | 10593 | 24.16 ms / 82.96 ms | -| Mysql | 32 | 1000 万 | 256 | 9813 | 26.08 ms / 94.10 ms | - -![sysbench-05](/media/sysbench-05.png) - -![sysbench-06](/media/sysbench-06.png) - -### 场景二：TiDB 水平扩展能力测试 - -部署方案以及配置参数 - -``` -// TiDB 部署方案 -172.16.20.3 4*tikv -172.16.10.2 1*tidb 1*pd 1*sysbench - -每个物理节点有三块盘： -data3: 2 tikv (Optane SSD) -data2: 1 tikv -data1: 1 tikv - -// TiKV 参数配置 -sync-log = false -grpc-concurrency = 8 -grpc-raft-conn-num = 24 -[defaultcf] -block-cache-size = "12GB" -[writecf] -block-cache-size = "5GB" -[raftdb.defaultcf] -block-cache-size = "2GB" -``` - -* 标准 oltp 测试 - -| - | table count | table size | sysbench threads | tps | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| 1 物理节点 TiDB | 32 | 100 万 | 256 * 1 | 2495 | 49902 | 102.42 ms / 125.52 ms | -| 2 物理节点 TiDB | 32 | 100 万 | 256 * 2 | 5007 | 100153 | 102.23 ms / 125.52 ms | -| 4 物理节点 TiDB | 32 | 100 万 | 256 * 4 | 8984 | 179692 | 114.96 ms / 176.73 ms | -| 6 物理节点 TiDB | 32 | 500 万 | 256 * 6 | 12953 | 259072 | 117.80 ms / 200.47 ms | - -![sysbench-07](/media/sysbench-07.png) - -* 标准 select 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| 1 物理节点 TiDB | 32 | 100 万 | 256 * 1 | 71841 | 3.56 ms / 8.74 ms | -| 2 物理节点 TiDB | 32 | 100 万 | 256 * 2 | 146615 | 3.49 ms / 8.74 ms | -| 4 物理节点 TiDB | 32 | 100 万 | 256 * 4 | 289933 | 3.53 ms / 8.74 ms | -| 6 物理节点 TiDB | 32 | 500 万 | 256 * 6 | 435313 | 3.55 ms / 9.17 ms | - -![sysbench-08](/media/sysbench-08.png) - -* 标准 insert 测试 - -| - | table count | table size | sysbench threads | qps | latency(avg / .95) | -| :---: | :---: | :---: | :---: | :---: | :---: | -| 3 物理节点 TiKV | 32 | 100 万 |256 * 3 | 40547 | 18.93 ms / 38.25 ms | -| 5 物理节点 TiKV | 32 | 100 万 | 256 * 3 | 60689 | 37.96 ms / 29.9 ms | -| 7 物理节点 TiKV | 32 | 100 万 | 256 * 3 | 80087 | 9.62 ms / 21.37 ms | - -![sysbench-09](/media/sysbench-09.png) diff --git a/v3.1/benchmark/tpcc.md b/v3.1/benchmark/tpcc.md deleted file mode 100644 index 8cf3926501a2..000000000000 --- a/v3.1/benchmark/tpcc.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: TiDB TPC-C 性能对比测试报告 - v3.0 对比 v2.1 -category: benchmark ---- - -# TiDB TPC-C 性能对比测试报告 - v3.0 对比 v2.1 - -## 测试目的 - -对比 TiDB 3.0 版本和 2.1 版本的 TPC-C 性能表现。 - -## 测试版本、时间、地点 - -TiDB 版本：v3.0.0 vs. v2.1.13 - -时间：2019 年 6 月 - -地点：北京 - -## 测试环境 - -IDC 机器： - -| 类别 | 名称 | -| :-: | :-: | -| OS | Linux (CentOS 7.3.1611) | -| CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | -| RAM | 128GB | -| DISK | 1.5TB SSD \* 2 | - -本文使用开源的 BenchmarkSQL 5.0 作为 TPC-C 测试工具并添加对 MySQL 协议支持， 可以通过以下命令下载测试程序: - -{{< copyable "shell-regular" >}} - -```shell -git clone -b 5.0-mysql-support-opt https://github.com/pingcap/benchmarksql.git -``` - -## 测试方案 - -使用 BenchmarkSQL 向集群导入 **1000 warehouse** 的数据。通过 HAProxy 代理，分别以递增并发数向集群发送请求，单次并发测试时间 10 分钟。 - -### TiDB 版本信息 - -### v3.0.0 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 46c38e15eba43346fb3001280c5034385171ee20 | -| TiKV | a467f410d235fa9c5b3c355e3b620f81d3ac0e0c | -| PD | 70aaa5eee830e21068f1ba2d4c9bae59153e5ca3 | - -### v2.1.13 - -| 组件 | GitHash | -| :-: | :-: | -| TiDB | 6b5b1a6802f9b8f5a22d8aab24ac80729331e1bc | -| TiKV | b3cf3c8d642534ea6fa93d475a46da285cc6acbf | -| PD | 886362ebfb26ef0834935afc57bcee8a39c88e54 | - -### TiDB 参数配置 - -```toml -[log] -level = "error" -[performance] -max-procs = 20 -[prepared_plan_cache] -enabled = true -``` - -### TiKV 参数配置 - -默认配置 - -### 集群拓扑 - -| 机器 IP | 部署实例 | -| :-: | :-: | -| 172.16.4.75 | 2\*TiDB 2\*TiKV 1\*pd | -| 172.16.4.76 | 2\*TiDB 2\*TiKV 1\*pd | -| 172.16.4.77 | 2\*TiDB 2\*TiKV 1\*pd | - -## 测试结果 - -| 版本 | threads | tpmC | -| :-: | :-: | :-: | -| v3.0 | 128 | 44068.55 | -| v3.0 | 256 | 47094.06 | -| v3.0 | 512 | 48808.65 | -| v2.1 | 128 | 10641.71 | -| v2.1 | 256 | 10861.62 | -| v2.1 | 512 | 10965.39 | - -![tpcc](/media/tpcc-2.1-3.0.png) - -v3.0 比 v2.1 在 TPC-C 性能上，**提升了 450%**。 diff --git a/v3.1/benchmark/tpch-v2.md b/v3.1/benchmark/tpch-v2.md deleted file mode 100644 index 688a9d0a7e26..000000000000 --- a/v3.1/benchmark/tpch-v2.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: TiDB TPC-H 50G 性能测试报告 -category: benchmark ---- - -# TiDB TPC-H 50G 性能测试报告 - -## 测试目的 - -测试 TiDB 在 OLAP 场景下 2.0 和 2.1 版本的性能对比。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试环境 - -### 测试机器信息 - -1. 系统信息 - - | 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | - |--------------|------------------------|------------------------------|--------------| - | 10.0.1.4 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - | 10.0.1.5 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - | 10.0.1.6 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - | 10.0.1.7 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - | 10.0.1.8 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - | 10.0.1.9 | CentOS 7.5.1804 64bit | 3.10.0-862.3.3.el7.x86\_64 | ext4 | - -2. 硬件信息 - - | 类别 | 10.0.1.4 | 10.0.1.5, 10.0.1.6, 10.0.1.7, 10.0.1.8, 10.0.1.9 | - |------------|------------------------------------------------------|------------------------------------------------------| - | CPU | 16 vCPUs, Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz | 8 vCPUs, Intel(R) Xeon(R) CPU E5-2660 0 @ 2.20GHz | - | 内存 | 110G | 55G | - | 磁盘 | 221G SSD | 111G SSD | - | 网卡 | 万兆网卡, 10000Mb/s | 万兆网卡, 10000Mb/s | - -### TPC-H - -[tidb-bench/tpch](https://github.com/pingcap/tidb-bench/tree/master/tpch) - -### 集群拓扑 - -| 机器 IP | 部署的实例 | -|----------|------------| -| 10.0.1.5 | TiKV \* 1 | -| 10.0.1.6 | TiKV \* 1 | -| 10.0.1.7 | TiKV \* 1 | -| 10.0.1.8 | TiKV \* 1 | -| 10.0.1.9 | TiKV \* 1 | -| 10.0.1.4 | PD \* 1 | -| 10.0.1.4 | TiDB \* 1 | - -### TiDB 版本信息 - -TiDB 2.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.0.7 | 29ec059cb3b7d14b6f52c2f219f94a89570162bc | -| TiKV | v2.0.7 | d0b8cd7c7f62f06e7ef456837bd32a47da1ca4cd | -| PD | v2.0.5 | b64716707b7279a4ae822be767085ff17b5f3fea | - -TiDB 2.1： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.1.0-rc.2 | 16864f95b47f859ed6104555ccff0387abdc2429 | -| TiKV | v2.1.0-rc.2 | 8458ce53ebbd434c48baac6373fe0f0a43a54005 | -| PD | v2.1.0-rc.2 | 55db505e8f35e8ab4e00efd202beb27a8ecc40fb | - -## 测试结果 - -| Query ID | TiDB 2.0 | TiDB 2.1 | -|-----------|----------------|----------------| -| 1 | 121.550595999s | 91.4755480289s | -| 2 | 53.0638680458s | 23.1186130047s | -| 3 | 75.7236940861s | 61.790802002s | -| 4 | 30.2647120953s | 26.3483440876s | -| 6 | 51.4850790501s | 34.6432199478s | -| 7 | 216.787364006s | 94.9856910706s | -| 8 | 188.717588902s | 181.852752209s | -| 9 | 546.438174009s | 414.462754965s | -| 10 | 109.978317022s | 37.0369961262s | -| 11 | 42.9398438931s | 37.6951580048s | -| 12 | 60.455039978s | 40.2236878872s | -| 13 | 230.278712988s | 70.2887151241s | -| 14 | 61.2673521042s | 35.8372960091s | -| 16 | 30.2539310455s | 18.5897550583s | -| 17 | 3200.70173788s | 263.095014811s | -| 18 | 1035.59847498s | 296.360667944s | -| 19 | 54.3732938766s | 40.4523630142s | -| 20 | 105.094577074s | 53.2429068089s | -| 21 | 389.883709908s | 361.034544945s | -| 22 | 64.0494630337s | 65.7153418064s | - -![TPC-H Query Result](/media/tpch-query-result-v2.png) - -说明： - -- 图中橙色为 Release 2.1，蓝色为 Release 2.0，纵坐标是 Query 的处理时间，越低越好 -- Query 15 因为 2.1 和 2.0 都还未支持视图，所以未列出结果 -- Query 5 因为 Join Order 问题长时间未跑出结果来，所以未列出结果 diff --git a/v3.1/benchmark/tpch.md b/v3.1/benchmark/tpch.md deleted file mode 100644 index 2bd7e2e75447..000000000000 --- a/v3.1/benchmark/tpch.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: TiDB TPC-H 50G 性能测试报告 -category: benchmark ---- - -# TiDB TPC-H 50G 性能测试报告 - -## 测试目的 - -测试 TiDB 在 OLAP 场景下 1.0 和 2.0 版本的性能对比。 - -> **注意：** -> -> 不同的测试环境可能使测试结果发生改变。 - -## 测试环境 - -### 测试机器信息 - -1. 系统信息 - - | 机器 IP | 操作系统 | 内核版本 | 文件系统类型 | - |--------------|------------------------|------------------------|--------------| - | 172.16.31.2 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | - | 172.16.31.3 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | - | 172.16.31.4 | Ubuntu 17.10 64bit | 4.13.0-16-generic | ext4 | - | 172.16.31.6 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | - | 172.16.31.8 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | - | 172.16.31.10 | CentOS 7.4.1708 64bit | 3.10.0-693.11.6.el7.x86\_64 | ext4 | - -2. 硬件信息 - - | 类别 | 名称 | - |------------|------------------------------------------------------| - | CPU | 40 vCPUs, Intel(R) Xeon(R) CPU E5-2630 v4 @ 2.20GHz | - | 内存 | 128GB, 8条16GB RDIMM, 2400MT/s, 双列, x8 带宽 | - | 磁盘 | 2 块 Intel P4500 系列 4T SSD 硬盘 | - | 网卡 | 万兆网卡 | - -### TPC-H - -[tidb-bench/tpch](https://github.com/pingcap/tidb-bench/tree/master/tpch) - -### 集群拓扑 - -| 机器 IP | 部署的实例 | -|--------------|------------| -| 172.16.31.2 | TiKV \* 2 | -| 172.16.31.3 | TiKV \* 2 | -| 172.16.31.6 | TiKV \* 2 | -| 172.16.31.8 | TiKV \* 2 | -| 172.16.31.10 | TiKV \* 2 | -| 172.16.31.10 | PD \* 1 | -| 172.16.31.4 | TiDB \* 1 | - -### TiDB 版本信息 - -TiDB 1.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v1.0.9 | 4c7ee3580cd0a69319b2c0c08abdc59900df7344 | -| TiKV | v1.0.8 | 2bb923a4cd23dbf68f0d16169fd526dc5c1a9f4a | -| PD | v1.0.8 | 137fa734472a76c509fbfd9cb9bc6d0dc804a3b7 | - -TiDB 2.0： - -| 组件名 | 版本号 | commit hash | -|--------|-------------|--------------------------------------------| -| TiDB | v2.0.0-rc.6 | 82d35f1b7f9047c478f4e1e82aa0002abc8107e7 | -| TiKV | v2.0.0-rc.6 | 8bd5c54966c6ef42578a27519bce4915c5b0c81f | -| PD | v2.0.0-rc.6 | 9b824d288126173a61ce7d51a71fc4cb12360201 | - -## 测试结果 - -| Query ID | TiDB 2.0 | TiDB 1.0 | -|-----------|--------------------|------------------| -| 1 | 33.915s | 215.305s | -| 2 | 25.575s | NaN | -| 3 | 59.631s | 196.003s | -| 4 | 30.234s | 249.919s | -| 5 | 31.666s | OOM | -| 6 | 13.111s | 118.709s | -| 7 | 31.710s | OOM | -| 8 | 31.734s | 800.546s | -| 9 | 34.211s | 630.639s | -| 10 | 30.774s | 133.547s | -| 11 | 27.692s | 78.026s | -| 12 | 27.962s | 124.641s | -| 13 | 27.676s | 174.695s | -| 14 | 19.676s | 110.602s | -| 15 | View Required | View Required | -| 16 | 24.890s | 40.529s | -| 17 | 245.796s | NaN | -| 18 | 91.256s | OOM | -| 19 | 37.615s | NaN | -| 20 | 44.167s | 212.201s | -| 21 | 31.466s | OOM | -| 22 | 31.539s | 125.471s | - -![TPC-H Query Result](/media/tpch-query-result.png) - -说明： - -- 图中橙色为 Release 1.0，蓝色为 Release 2.0，纵坐标是 Query 的处理时间，越低越好 -- Query 15 因为 1.0 和 2.0 都还未支持视图，所以结果标记为 "View Required" -- Query 2, 17, 19 因为 TiDB 1.0 长时间未跑出结果，所以结果标记为 "Nan" -- Query 5, 7, 18, 21 因为 TiDB 1.0 在跑的过程中内存占用过多被 oom-killer 杀死，所以结果标记为 "OOM" diff --git a/v3.1/contribute.md b/v3.1/contribute.md deleted file mode 100644 index 9747814f9cc9..000000000000 --- a/v3.1/contribute.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 成为贡献者 -category: contribute ---- - -# 成为贡献者 - -## 成为 TiDB 的贡献者 - -我们推荐您先尝试解决带 [help-wanted](https://github.com/pingcap/tidb/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) 标签的现有 Issue，这些问题非常适合新的贡献者。 - -一旦您提交给 [TiDB/TiKV/TiSpark/PD/TiDB Operator/Docs/Docs-cn](https://github.com/pingcap) 项目的 PR (Pull Request) 被批准且合并，您即成为 TiDB 的贡献者。 - -在提交 PR 之前，请先签署 [CLA](https://cla-assistant.io/pingcap/tidb?pullRequest=5567)。 - -如果您想实践一个影响范围相对较小的新想法，请遵循以下步骤： - -1. 提交新 Issue，描述您对相关仓库的更改建议。 -2. 相关仓库的负责人将及时回复您的 Issue。 -3. 如果您的更改建议被接受，您需要先签署 [CLA](https://cla-assistant.io/pingcap/tidb?pullRequest=5567)，便可以在您的克隆仓库 (fork) 里开始工作了。 -4. 在测试过所做的更改后，您便可以提交[包含更改的 PR](https://github.com/pingcap/tidb/pull/3113) 了。 - -我们欢迎并非常感谢您的贡献。有关提交补丁和贡献流程的详细信息，请参阅[贡献者指南](https://github.com/pingcap/tidb/blob/master/CONTRIBUTING.md)。 - -## 改进文档 - -我们欢迎更多贡献者来帮助改进文档！ - -TiDB 文档使用 Markdown 语言，并参考了 [Google 开发者文档风格指南](https://developers.google.com/style/)进行编写。如果这些概念对您来说比较陌生，请不要担心，我们很乐意为您提供指导。 - -如要对文档仓库进行贡献，请先 fork [docs-cn 仓库](https://github.com/pingcap/docs-cn)，再提交您的 PR。 diff --git a/v3.1/faq/tidb-lightning.md b/v3.1/faq/tidb-lightning.md deleted file mode 100644 index 6833c8063fe4..000000000000 --- a/v3.1/faq/tidb-lightning.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: TiDB Lightning 常见问题 -category: FAQ ---- - -# TiDB Lightning 常见问题 - -本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。 - ->**注意：** -> -> 使用 TiDB Lightning 的过程中如遇错误，参考 [TiDB Lightning 故障诊断](/v3.1/how-to/troubleshoot/tidb-lightning.md)进行排查。 - -## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ - -TiDB Lightning 的版本应与集群相同。最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。 - -## TiDB Lightning 支持导入多个库吗？ - -支持。 - -## TiDB Lightning 对下游数据库的账号权限要求是怎样的？ - -TiDB Lightning 需要以下权限： - -* SELECT -* UPDATE -* ALTER -* CREATE -* DROP - -如果选择 [TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) 模式，或目标数据库用于存储断点，则 TiBD Lightning 额外需要以下权限： - -* INSERT -* DELETE - -Importer-backend 无需以上两个权限，因为数据直接被 Ingest 到 TiKV 中，所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问，就可以保证安全。 - -如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？ - -如果只是个别表报错，不会影响整体。报错的那个表会停止处理，继续处理其他的表。 - -## 如何正确重启 TiDB Lightning？ - -根据 `tikv-importer` 的状态，重启 TiDB Lightning 的基本顺序如下： - -如果 `tikv-importer` 仍在运行： - -1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 -3. 如果上面的修改操作更改了任何表，你还需要[清除对应的断点](/v3.1/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-remove)。 -4. 重启 `tidb-lightning`。 - -如果 `tikv-importer` 需要重启： - -1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. [结束 `tikv-importer` 进程](#如何正确结束-tikv-importer-进程)。 -3. 执行修改操作（如修复数据源、更改设置、更换硬件等）。 -4. 重启 `tikv-importer`。 -5. 重启 `tidb-lightning` 并等待，**直到程序因校验和错误（如果有的话）而失败**。 - * 重启 `tikv-importer` 将清除所有仍在写入的引擎文件，但是 `tidb-lightning` 并不会感知到该操作。从 v3.0 开始，最简单的方法是让 `tidb-lightning` 继续，然后再重试。 -6. [清除失败的表及断点](/v3.1/how-to/troubleshoot/tidb-lightning.md#checkpoint-for--has-invalid-status错误码)。 -7. 再次重启 `tidb-lightning`。 - -## 如何校验导入的数据的正确性？ - -TiDB Lightning 默认会对导入数据计算校验和 (checksum)，如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。 - -TiDB 也支持从 MySQL 命令行运行 `ADMIN CHECKSUM TABLE` 指令来计算校验和。 - -{{< copyable "sql" >}} - -```sql -ADMIN CHECKSUM TABLE `schema`.`table`; -``` - -``` -+---------+------------+---------------------+-----------+-------------+ -| Db_name | Table_name | Checksum_crc64_xor | Total_kvs | Total_bytes | -+---------+------------+---------------------+-----------+-------------+ -| schema | table | 5505282386844578743 | 3 | 96 | -+---------+------------+---------------------+-----------+-------------+ -1 row in set (0.01 sec) -``` - -## TiDB Lightning 支持哪些格式的数据源？ - -TiDB Lightning 只支持两种格式的数据源： - -1. [Mydumper](/v3.1/reference/tools/mydumper.md) 生成的 SQL dump -2. 储存在本地文件系统的 [CSV](/v3.1/reference/tools/tidb-lightning/csv.md) 文件 - -## 我已经在下游创建好库和表了，TiDB Lightning 可以忽略建库建表操作吗？ - -可以。在配置文档中的 `[mydumper]` 部分将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。 - -## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入？ - -可以。Lightning 默认的 [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) 为 `"STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"`。 - -这个设置不允许一些非法的数值，例如 `1970-00-00` 这样的日期。可以修改配置文件 `[tidb]` 下的 `sql-mode` 值。 - -```toml -... -[tidb] -sql-mode = "" -... -``` - -## 可以启用一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？ - -只要每个 Lightning 操作的表互不相同就可以。 - -## 如何正确结束 `tikv-importer` 进程？ - -根据部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh`。 - -- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程 ID，然后通过 `kill «pid»` 结束进程。 - -## 如何正确结束 `tidb-lightning` 进程？ - -根据部署方式，选择相应操作结束进程 - -- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh`。 - -- 手动部署：如果 `tidb-lightning` 正在前台运行，可直接按 Ctrl+C 退出。否则，可通过 `ps aux | grep tidb-lightning` 获取进程 ID，然后通过 `kill -2 «pid»` 结束进程。 - -## `tidb-lightning` 在服务器上运行，进程莫名其妙地退出了，是怎么回事呢？ - -这种情况可能是启动方式不正确，导致收到 SIGHUP 信号而退出。此时 `tidb-lightning.log` 通常有如下日志： - -``` -[2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup] -``` - -不推荐在命令行中直接使用 `nohup` 启动进程，推荐[使用脚本启动 `tidb-lightning`](/v3.1/reference/tools/tidb-lightning/deployment.md)。 - -## 为什么用过 TiDB Lightning 之后，TiDB 集群变得又慢又耗 CPU？ - -如果 `tidb-lightning` 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)： - -{{< copyable "shell-regular" >}} - -```sh -tidb-lightning-ctl --switch-mode=normal -``` - -## TiDB Lightning 可以使用千兆网卡吗？ - -使用 TiDB Lightning 建议配置万兆网卡。**不推荐**使用千兆网卡，尤其是在部署 `tikv-importer` 的机器上。 - -千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。为了避免这种情况，你可以在 [`tikv-importer` 的配置文件](/v3.1/reference/tools/tidb-lightning/config.md#tikv-importer-配置参数)中**限制上传速度**。 - -```toml -[import] -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# 建议将该速度设为 100 MB/s 或更小。 -upload-speed-limit = "100MB" -``` - -## 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间？ - -当使用默认的 3 副本设置时，TiDB Lightning 需要 TiKV 集群预留数据源大小 6 倍的空间。多出来的 2 倍是算上下列没储存在数据源的因素的保守估计： - -- 索引会占据额外的空间 -- RocksDB 的空间放大效应 - -## TiDB Lightning 使用过程中是否可以重启 TiKV Importer？ - -不能，Importer 会在内存中存储一些引擎文件，Importer 重启后，`tidb-lightning` 会因连接失败而停止。此时，你需要[清除失败的断点](/v3.1/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-error-destroy)，因为这些 Importer 特有的信息丢失了。你可以在之后[重启 Lightning](#如何正确重启-tidb-lightning)。 - -## 如何清除所有与 TiDB Lightning 相关的中间数据？ - -1. 删除断点文件。 - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all - ``` - - 如果出于某些原因而无法运行该命令，你可以尝试手动删除 `/tmp/tidb_lightning_checkpoint.pb` 文件。 - -2. 删除 `tikv-importer` 所在机器上的整个 “import” 文件目录。 - -3. 如果需要的话，删除 TiDB 集群上创建的所有表和库。 diff --git a/v3.1/faq/tidb.md b/v3.1/faq/tidb.md deleted file mode 100755 index e3cccd75a2e7..000000000000 --- a/v3.1/faq/tidb.md +++ /dev/null @@ -1,1083 +0,0 @@ ---- -title: TiDB FAQ -category: FAQ ---- - -# FAQ - -## 一、 TiDB 介绍、架构、原理 - -### 1.1 TiDB 介绍及整体架构 - -#### 1.1.1 TiDB 整体架构 - -[TiDB 简介](/v3.1/overview.md#tidb-简介) - -#### 1.1.2 TiDB 是什么？ - -TiDB 是一个分布式 NewSQL 数据库。它支持水平弹性扩展、ACID 事务、标准 SQL、MySQL 语法和 MySQL 协议，具有数据强一致的高可用特性，是一个不仅适合 OLTP 场景还适合 OLAP 场景的混合数据库。 - -#### 1.1.3 TiDB 是基于 MySQL 开发的吗？ - -不是，虽然 TiDB 支持 MySQL 语法和协议，但是 TiDB 是由 PingCAP 团队完全自主开发的产品。 - -#### 1.1.4 TiDB、TiKV、Placement Driver (PD) 主要作用？ - -- TiDB 是 Server 计算层，主要负责 SQL 的解析、制定查询计划、生成执行器。 -- TiKV 是分布式 Key-Value 存储引擎，用来存储真正的数据，简而言之，TiKV 是 TiDB 的存储引擎。 -- PD 是 TiDB 集群的管理组件，负责存储 TiKV 的元数据，同时也负责分配时间戳以及对 TiKV 做负载均衡调度。 - -#### 1.1.5 TiDB 易用性如何？ - -TiDB 使用起来很简单，可以将 TiDB 集群当成 MySQL 来用，你可以将 TiDB 用在任何以 MySQL 作为后台存储服务的应用中，并且基本上不需要修改应用代码，同时你可以用大部分流行的 MySQL 管理工具来管理 TiDB。 - -#### 1.1.6 TiDB 和 MySQL 兼容性如何？ - -TiDB 目前还不支持触发器、存储过程、自定义函数、外键，除此之外，TiDB 支持绝大部分 MySQL 5.7 的语法。 - -详情参见[与 MySQL 兼容性对比](/v3.1/reference/mysql-compatibility.md)。 - -#### 1.1.7 TiDB 具备高可用的特性吗？ - -TiDB 天然具备高可用特性，TiDB、TiKV、PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。具体见 [TiDB 高可用性](/v3.1/key-features.md#高可用)。 - -#### 1.1.8 TiDB 数据是强一致的吗？ - -TiDB 实现了快照隔离 (Snapshot Isolation) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。 - -在底层，TiKV 使用复制日志 + 状态机 (State Machine) 的模型来复制数据。对于写入请求，数据被写入 Leader，然后 Leader 以日志的形式将命令复制到它的 Follower 中。当集群中的大多数节点收到此日志时，日志会被提交，状态机会相应作出变更。 - -#### 1.1.9 TiDB 支持分布式事务吗？ - -支持。无论是一个地方的几个节点，还是[跨多个数据中心的多个节点](/v3.1/how-to/deploy/geographic-redundancy/overview.md)，TiDB 均支持 ACID 分布式事务。 - -TiDB 事务模型灵感源自 Google Percolator 模型，主体是一个两阶段提交协议，并进行了一些实用的优化。该模型依赖于一个时间戳分配器，为每个事务分配单调递增的时间戳，这样就检测到事务冲突。在 TiDB 集群中，[PD](/v3.1/architecture.md#pd-server) 承担时间戳分配器的角色。 - -#### 1.1.10 TiDB 支持哪些编程语言？ - -只要支持 MySQL Client/Driver 的编程语言，都可以直接使用 TiDB。 - -#### 1.1.11 TiDB 是否支持其他存储引擎？ - -是的，除了 TiKV 之外，TiDB 还支持一些流行的单机存储引擎，比如 GolevelDB、RocksDB、BoltDB 等。如果一个存储引擎是支持事务的 KV 引擎，并且能提供一个满足 TiDB 接口要求的 Client，即可接入 TiDB。 - -#### 1.1.12 官方有没有三中心跨机房多活部署的推荐方案？ - -从 TiDB 架构来讲，支持真正意义上的跨中心异地多活，从操作层面讲，依赖数据中心之间的网络延迟和稳定性，一般建议延迟在 5ms 以下，目前我们已经有相似客户方案，具体请咨询官方 [info@pingcap.com](mailto:info@pingcap.com)。 - -#### 1.1.13 除了官方文档，有没有其他 TiDB 知识获取途径？ - -目前[官方文档](/v3.1/overview.md#tidb-简介)是获取 TiDB 相关知识最主要、最及时的发布途径。除此之外，我们也有一些技术沟通群，如有需求可发邮件至 [info@pingcap.com](mailto:info@pingcap.com) 获取。 - -#### 1.1.14 TiDB 对哪些 MySQL variables 兼容？ - -详细可参考[系统变量](/v3.1/reference/configuration/tidb-server/mysql-variables.md)。 - -#### 1.1.15 TiDB 是否支持 select for update？ - -支持，但语义上和 MySQL 有区别，TiDB 是分布式数据库，采用的乐观锁机制，也就说 select for update 不在事务开启就锁住数据，而是其他事务在提交的时候进行冲突检查，如有冲突，会进行回滚。 - -#### 1.1.16 TiDB 的 codec 能保证 UTF8 的字符串是 memcomparable 的吗？我们的 key 需要支持 UTF8，有什么编码建议吗？ - -TiDB 字符集默认就是 UTF8 而且目前只支持 UTF8，字符串就是 memcomparable 格式的。 - -#### 1.1.17 TiDB 用户名长度限制？ - -在 TiDB 中用户名最长为 32 字符。 - -#### 1.1.18 一个事务中的语句数量最大是多少？ - -一个事务中的语句数量，默认限制最大为 5000 条。 - -#### 1.1.19 TiDB 是否支持 XA？ - -虽然 TiDB 的 JDBC 驱动用的就是 MySQL JDBC（Connector / J），但是当使用 Atomikos 的时候，数据源要配置成类似这样的配置：`type="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"`。MySQL JDBC XADataSource 连接 TiDB 的模式目前是不支持的。MySQL JDBC 中配置好的 XADataSource 模式，只对 MySQL 数据库起作用（DML 去修改 redo 等）。 - -Atomikos 配好两个数据源后，JDBC 驱动都要设置成 XA 模式，然后 Atomikos 在操作 TM 和 RM（DB）的时候，会通过数据源的配置，发起带有 XA 指令到 JDBC 层，JDBC 层 XA 模式启用的情况下，会对 InnoDB（如果是 MySQL 的话）下发操作一连串 XA 逻辑的动作，包括 DML 去变更 redo log 等，就是两阶段递交的那些操作。TiDB 目前的引擎版本中，没有对上层应用层 JTA / XA 的支持，不解析这些 Atomikos 发过来的 XA 类型的操作。 - -MySQL 是单机数据库，只能通过 XA 来满足跨数据库事务，而 TiDB 本身就通过 Google 的 Percolator 事务模型支持分布式事务，性能稳定性比 XA 要高出很多，所以不会也不需要支持 XA。 - -#### 1.1.20 show processlist 是否显示系统进程号？ - -TiDB 的 `show processlist` 与 MySQL 的 `show processlist` 显示内容基本一样，不会显示系统进程号，而 ID 表示当前的 session ID。其中 TiDB 的 `show processlist` 和 MySQL 的 `show processlist` 区别如下： - -1）由于 TiDB 是分布式数据库，tidb-server 实例是无状态的 SQL 解析和执行引擎（详情可参考 [TiDB 整体架构](/v3.1/overview.md#tidb-整体架构)），用户使用 MySQL 客户端登录的是哪个 tidb-server，`show processlist` 就会显示当前连接的这个 tidb-server 中执行的 session 列表，不是整个集群中运行的全部 session 列表；而 MySQL 是单机数据库，`show processlist` 列出的是当前整个 MySQL 数据库的全部执行 SQL 列表。 - -2）TiDB 的 `show processlist` 显示内容比起 MySQL 来讲，多了一个当前 session 使用内存的估算值（单位 Byte）。 - -#### 1.1.21 如何修改用户名密码和权限？ - -TiDB 作为分布式数据库，在 TiDB 中修改用户密码建议使用 `set password for 'root'@'%' = '0101001';` 或 `alter` 方法，不推荐使用 `update mysql.user` 的方法进行，这种方法可能会造成其它节点刷新不及时的情况。修改权限也一样，都建议采用官方的标准语法。详情可参考 [TiDB 用户账户管理](/v3.1/reference/security/user-account-management.md)。 - -#### 1.1.22 TiDB 中，为什么出现后插入数据的自增 ID 反而小？ - -TiDB 的自增 ID (`AUTO_INCREMENT`) 只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。当多个线程并发往不同的 tidb-server 插入数据的时候，有可能会出现后插入的数据自增 ID 小的情况。此外，TiDB允许给整型类型的字段指定 AUTO_INCREMENT，且一个表只允许一个属性为 `AUTO_INCREMENT` 的字段。详情可参考[CREATE TABLE 语法](/v3.1/reference/mysql-compatibility.md#自增-id)。 - -#### 1.1.23 sql_mode 默认除了通过命令 set 修改，配置文件怎么修改？ - -TiDB 的 sql_mode 与 MySQL 的 sql_mode 设置方法有一些差别，TiDB 不支持配置文件配置设置数据库的 sql\_mode，而只能使用 set 命令去设置，具体方法为：`set @@global.sql_mode = 'STRICT_TRANS_TABLES';`。 - -#### 1.1.24 TiDB 支持哪些认证协议，过程是怎样的？ - -这一层跟 MySQL 一样，走的 SASL 认证协议，用于用户登录认证，对密码的处理流程。 - -客户端连接 TiDB 的时候，走的是 challenge-response（挑战-应答）的认证模式，过程如下： - -第一步：客户端连接服务器； - -第二步：服务器发送随机字符串 challenge 给客户端； - -第三步：客户端发送 username + response 给服务器； - -第四步：服务器验证 response。 - -### 1.2 TiDB 原理 - -#### 1.2.1 存储 TiKV - -##### 1.2.1.1 TiKV 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说存储](http://t.cn/RTKRRWv) - -#### 1.2.2 计算 TiDB - -##### 1.2.2.1 TiDB 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 说计算](http://t.cn/RTKRkBh) - -#### 1.2.3 调度 PD - -##### 1.2.3.1 PD 详细解读 - -[三篇文章了解 TiDB 技术内幕 - 谈调度](http://t.cn/RTKEZ0U) - -## 二、安装部署升级 - -### 2.1 环境准备 - -#### 2.1.1 操作系统版本要求 - -| **Linux 操作系统平台** | **版本** | -| --- | --- | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | - -##### 2.1.1.1 为什么要在 CentOS 7 上部署 TiDB 集群？ - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络，作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境，具体可以参考 TiDB 的[官方部署要求](/v3.1/how-to/deploy/hardware-recommendations.md)。其中 TiDB 在 CentOS 7.3 的环境下进行大量的测试，同时也有很多这个操作系统的部署最佳实践，因此，我们推荐客户在部署 TiDB 的时候使用 CentOS 7.3+ 以上的Linux 操作系统。 - -#### 2.1.2 硬件要求 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -##### 2.1.2.1 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 8核+ | 16 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | -| | | | | 服务器总计 | 4 | - -##### 2.1.2.2 线上环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 48 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 8核+ | 16 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 48 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | -| | | | | 服务器总计 | 9 | - -##### 2.1.2.3 2 块网卡的目的是？万兆的目的是？ - -作为一个分布式集群，TiDB 对时间的要求还是比较高的，尤其是 PD 需要分发唯一的时间戳，如果 PD 时间不统一，如果有 PD 切换，将会等待更长的时间。2 块网卡可以做 bond，保证数据传输的稳定，万兆可以保证数据传输的速度，千兆网卡容易出现瓶颈，我们强烈建议使用万兆网卡。 - -##### 2.1.2.4 SSD 不做 RAID 是否可行？ - -资源可接受的话，我们建议做 RAID 10，如果资源有限，也可以不做 RAID。 - -##### 2.1.2.5 TiDB 集群各个组件的配置推荐？ - -- TiDB 需要 CPU 和内存比较好的机器，参考官网配置要求，如果后期需要开启 Binlog，根据业务量的评估和 GC 时间的要求，也需要本地磁盘大一点，不要求 SSD 磁盘； -- PD 里面存了集群元信息，会有频繁的读写请求，对磁盘 I/O 要求相对比较高，磁盘太差会影响整个集群性能，推荐 SSD 磁盘，空间不用太大。另外集群 Region 数量越多对 CPU、内存的要求越高； -- TiKV 对 CPU、内存、磁盘要求都比较高，一定要用 SSD 磁盘。 - -详情可参考 [TiDB 软硬件环境需求](/v3.1/how-to/deploy/hardware-recommendations.md)。 - -### 2.2 安装部署 - -#### 2.2.1 Ansible 部署方式（强烈推荐） - -详细可参考[使用 TiDB Ansible 部署 TiDB 集群](/v3.1/how-to/deploy/orchestrated/ansible.md)。 - -##### 2.2.1.1 为什么修改了 TiKV/PD 的 toml 配置文件，却没有生效？ - -这种情况一般是因为没有使用 `--config` 参数来指定配置文件（目前只会出现在 binary 部署的场景），TiKV/PD 会按默认值来设置。如果要使用配置文件，请设置 TiKV/PD 的 `--config` 参数。对于 TiKV 组件，修改配置后重启服务即可；对于 PD 组件，只会在第一次启动时读取配置文件，之后可以使用 pd-ctl 的方式来修改配置，详情可参考 [PD 配置参数](/v3.1/reference/configuration/pd-server/configuration.md)。 - -##### 2.2.1.2 TiDB 监控框架 Prometheus + Grafana 监控机器建议单独还是多台部署？ - -监控机建议单独部署。建议 CPU 8 core，内存 16 GB 以上，硬盘 500 GB 以上。 - -##### 2.2.1.3 有一部分监控信息显示不出来？ - -查看访问监控的机器时间跟集群内机器的时间差，如果比较大，更正时间后即可显示正常。 - -##### 2.2.1.4 supervise/svc/svstat 服务具体起什么作用？ - -- supervise 守护进程 -- svc 启停服务 -- svstat 查看进程状态 - -##### 2.2.1.5 inventory.ini 变量参数解读 - -| **变量** | **含义** | -| --- | --- | -| cluster_name | 集群名称，可调整 | -| tidb_version | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| deployment_method | 部署方式，默认为 binary，可选 docker | -| process_supervision | 进程监管方式，默认为 systemd，可选 supervise | -| timezone | 修改部署目标机器时区，默认为 Asia/Shanghai, 可调整，与set_timezone 变量结合使用 | -| set_timezone | 默认为 True，即修改部署目标机器时区，关闭可修改为 False | -| enable_elk | 目前不支持，请忽略 | -| enable_firewalld | 开启防火墙，默认不开启 | -| enable_ntpd | 检测部署目标机器 NTP 服务，默认为 True，请勿关闭 | -| machine_benchmark | 检测部署目标机器磁盘 IOPS，默认为 True，请勿关闭 | -| set_hostname | 根据 IP 修改部署目标机器主机名，默认为 False | -| enable_binlog | 是否部署 pump 并开启 binlog，默认为 False，依赖 Kafka 集群，参见 zookeeper_addrs 变量 | -| zookeeper_addrs | binlog Kafka 集群的 zookeeper 地址 | -| enable_slow_query_log | TiDB 慢查询日志记录到单独文件({{ deploy_dir }}/log/tidb_slow_query.log)，默认为 False，记录到 tidb 日志 | -| deploy_without_tidb | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 inventory.ini 文件中 tidb_servers 主机组 IP 设置为空。 | - -#### 2.2.2 TiDB 离线 Ansible 部署方案 - -首先这不是我们建议的方式，如果中控机没有外网，也可以通过离线 Ansible 部署方式，详情可参考[离线 TiDB Ansible 部署方案](/v3.1/how-to/deploy/orchestrated/offline-ansible.md)。 - -#### 2.2.3 Docker Compose 快速构建集群（单机部署） - -使用 docker-compose 在本地一键拉起一个集群，包括集群监控，还可以根据需求自定义各个组件的软件版本和实例个数，以及自定义配置文件，这种只限于开发环境，详细可参考[官方文档](/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -#### 2.2.4 如何单独记录 TiDB 中的慢查询日志，如何定位慢查询 SQL？ - -1）TiDB 中，对慢查询的定义在 tidb-ansible 的 `conf/tidb.yml` 配置文件中，`slow-threshold: 300`，这个参数是配置慢查询记录阈值的，单位是 ms。 - -慢查询日志默认记录到 tidb.log 中，如果希望生成单独的慢查询日志文件，修改 inventory.ini 配置文件的参数 `enable_slow_query_log` 为 True。 - -如上配置修改之后，需要执行 `ansible-playbook rolling_update.yml --tags=tidb`，对 tidb-server 实例进行滚动升级，升级完成后，tidb-server 将在 `tidb_slow_query.log` -文件中记录慢查询日志。 - -2）如果出现了慢查询，可以从 Grafana 监控定位到出现慢查询的 tidb-server 以及时间点，然后在对应节点查找日志中记录的 SQL 信息。 - -3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md#admin-show-slow-命令)。 - -#### 2.2.5 首次部署 TiDB 集群时，没有配置 tikv 的 Label 信息，在后续如何添加配置 Label？ - -TiDB 的 Label 设置是与集群的部署架构相关的，是集群部署中的重要内容，是 PD 进行全局管理和调度的依据。如果集群在初期部署过程中没有设置 Label，需要在后期对部署结构进行调整，就需要手动通过 PD 的管理工具 pd-ctl 来添加 location-labels 信息，例如：`config set location-labels "zone,rack,host"`（根据实际的 label 层级名字配置）。 - -pd-ctl 的使用参考 [PD Control 使用说明](/v3.1/reference/tools/pd-control.md)。 - -#### 2.2.6 为什么测试磁盘的 dd 命令用 oflag=direct 这个选项？ - -Direct 模式就是把写入请求直接封装成 I/O 指令发到磁盘，这样是为了绕开文件系统的缓存，可以直接测试磁盘的真实的 I/O 读写能力。 - -#### 2.2.7 如何用 fio 命令测试 TiKV 实例的磁盘性能？ - -- 随机读测试： - - {{< copyable "shell-regular" >}} - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randread -size=10G -filename=fio_randread_test.txt -name='fio randread test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_result.json - ``` - -- 顺序写和随机读混合测试： - - {{< copyable "shell-regular" >}} - - ```bash - ./fio -ioengine=psync -bs=32k -fdatasync=1 -thread -rw=randrw -percentage_random=100,0 -size=10G -filename=fio_randread_write_test.txt -name='fio mixed randread and sequential write test' -iodepth=4 -runtime=60 -numjobs=4 -group_reporting --output-format=json --output=fio_randread_write_test.json - ``` - -#### 2.2.8 使用 TiDB Ansible 部署 TiDB 集群的时候，遇到 `UNREACHABLE! "msg": "Failed to connect to the host via ssh: "` 报错是什么原因？ - -有两种可能性： - -- ssh 互信的准备工作未做好，建议严格参照我们的[官方文档步骤](/v3.1/how-to/deploy/orchestrated/ansible.md)配置互信，并使用命令 `ansible -i inventory.ini all -m shell -a 'whoami' -b` 来验证互信配置是否成功。 - -- 如果涉及到单服务器分配了多角色的场景，例如多组件混合部署或单台服务器部署了多个 TiKV 实例，可能是由于 ssh 复用的机制引起这个报错，可以使用 `ansible … -f 1` 的选项来规避这个报错。 - -### 2.3 升级 - -#### 2.3.1 如何使用 Ansible 滚动升级？ - -滚动升级 TiKV 节点( 只升级单独服务 ) - -`ansible-playbook rolling_update.yml --tags=tikv` - -滚动升级所有服务 - -`ansible-playbook rolling_update.yml` - -#### 2.3.2 滚动升级有那些影响? - -滚动升级 TiDB 服务，滚动升级期间不影响业务运行，需要配置最小集群拓扑（TiDB \* 2、PD \* 3、TiKV \* 3），如果集群环境中有 Pump/Drainer 服务，建议先停止 Drainer 后滚动升级（升级 TiDB 时会升级 Pump）。 - -#### 2.3.3 Binary 如何升级？ - -Binary 不是我们建议的安装方式，对升级支持也不友好，建议换成 Ansible 部署。 - -#### 2.3.4 一般升级选择升级 TiKV 还是所有组件都升级？ - -常规需要一起升，因为整个版本都是一起测试的，单独升级只限当发生一个紧急故障时，需要单独对一个有问题的角色做升级。 - -#### 2.3.5 启动集群或者升级集群过程中出现 “Timeout when waiting for search string 200 OK” 是什么原因？如何处理？ - -可能有以下几种原因：进程没有正常启动；端口被占用；进程没有正常停掉；停掉集群的情况下使用 rolling_update.yml 来升级集群（操作错误）。 - -处理方式：登录到相应节点查看进程或者端口的状态；纠正错误的操作步骤。 - -## 三、集群管理 - -### 3.1 集群日常管理 - -#### 3.1.1 Ansible 常见运维操作有那些？ - -| **任务** | **Playbook** | -| --- | --- | -| 启动集群 | ansible-playbook start.yml | -| 停止集群 | ansible-playbook stop.yml | -| 销毁集群 | ansible-playbook unsafe\_cleanup.yml (若部署目录为挂载点，会报错，可忽略） | -| 清除数据(测试用) | ansible-playbook cleanup\_data.yml | -| 滚动升级 | ansible-playbook rolling\_update.yml | -| 滚动升级 TiKV | ansible-playbook rolling\_update.yml --tags=tikv | -| 滚动升级除 PD 外模块 | ansible-playbook rolling\_update.yml --skip-tags=pd | -| 滚动升级监控组件 | ansible-playbook rolling\_update\_monitor.yml | - -#### 3.1.2 TiDB 如何登录？ - -和 MySQL 登录方式一样，可以按照下面例子进行登录。 - -`mysql -h 127.0.0.1 -uroot -P4000` - -#### 3.1.3 TiDB 如何修改数据库系统变量？ - -和 MySQL 一样，TiDB 也分为静态参数和固态参数，静态参数可以直接通过`set global xxx = n`的方式进行修改，不过新参数值只限于该实例生命周期有效。 - -#### 3.1.4 TiDB (TiKV) 有哪些数据目录？ - -默认在 [`--data-dir`](/v3.1/reference/configuration/tikv-server/configuration.md#--data-dir) 目录下，其中包括 backup、db、raft、snap 四个目录，分别存储备份、数据、raft 数据及镜像数据。 - -#### 3.1.5 TiDB 有哪些系统表？ - -和 MySQL 类似，TiDB 中也有系统表，用于存放数据库运行时所需信息，具体信息参考 [TiDB 系统数据库](/v3.1/reference/system-databases/mysql.md)文档。 - -#### 3.1.6 TiDB 各节点服务器下是否有日志文件，如何管理？ - -默认情况下各节点服务器会在日志中输出标准错误，如果启动的时候通过 `--log-file` 参数指定了日志文件，那么日志会输出到指定的文件中，并且按天做 rotation。 - -#### 3.1.7 如何规范停止 TiDB？ - -如果是用 Ansible 部署的，可以使用 `ansible-playbook stop.yml` 命令停止 TiDB 集群。如果不是 Ansible 部署的，可以直接 kill 掉所有服务。如果使用 kill 命令，TiDB 的组件会做 graceful 的 shutdown。 - -#### 3.1.8 TiDB 里面可以执行 kill 命令吗？ - -- 可以 kill DML 语句，首先使用 `show processlist`，找到对应 session 的 id，然后执行 `kill tidb [session id]`。 -- 可以 kill DDL 语句，首先使用 `admin show ddl jobs`，查找需要 kill 的 DDL job ID，然后执行 `admin cancel ddl jobs 'job_id' [, 'job_id'] ...`。具体可以参考 [admin 操作](/v3.1/reference/sql/statements/admin.md)。 - -#### 3.1.9 TiDB 是否支持会话超时？ - -TiDB 暂不支持数据库层面的会话超时，目前想要实现超时，在没 LB（Load Balancing）的时候，需要应用侧记录发起的 Session 的 ID，通过应用自定义超时，超时以后需要到发起 Query 的节点上用 `kill tidb [session id]` 来杀掉 SQL。目前建议使用应用程序来实现会话超时，当达到超时时间，应用层就会抛出异常继续执行后续的程序段。 - -#### 3.1.10 TiDB 生产环境的版本管理策略是怎么样的？如何尽可能避免频繁升级？ - -TiDB 版本目前逐步标准化，每次 Release 都包含详细的 Change log，版本功能[变化详情](https://github.com/pingcap/TiDB/releases)，生产环境是否有必要升级取决于业务系统，建议升级之前详细了解前后版本的功能差异。 - -版本号说明参考：Release Version: `v1.0.3-1-ga80e796` - -- `v1.0.3` 表示 GA 标准版 -- `1` 表示该版本 commit 1 次 -- `ga80e796` 代表版本的 `git-hash` - -#### 3.1.11 分不清 TiDB master 版本之间的区别，经常用错 TiDB Ansible 版本? - -TiDB 目前社区非常活跃，在 1.0 GA 版本发布后，还在不断的优化和修改 BUG，因此 TiDB 的版本更新周期比较快，会不定期有新版本发布，请关注我们的[新版本发布官方网站](https://pingcap.com/weekly/)。此外 TiDB 安装推荐使用 TiDB Ansible 进行安装，TiDB Ansible 的版本也会随着 TiDB 的版本发布进行更新，因此建议用户在安装升级新版本的时候使用最新的 TiDB Ansible 安装包版本进行安装。此外，在 TiDB 1.0 GA 版本后，对 TiDB 的版本号进行了统一管理，TiDB 的版本可以通过以下两种方式进行查看： - -- 通过 `select tidb_version()` 进行查看 -- 通过执行 `tidb-server -V` 进行查看 - -#### 3.1.12 有没有图形化部署 TiDB 的工具？ - -暂时没有。 - -#### 3.1.13 TiDB 如何进行水平扩展？ - -当您的业务不断增长时，数据库可能会面临三方面瓶颈，第一是存储空间，第二是计算资源，第三是读写容量，这时可以对 TiDB 集群做水平扩展。 - -- 如果是存储资源不够，可以通过添加 TiKV Server 节点来解决，新节点启动后，PD 会自动将其他节点的部分数据迁移过去，无需人工介入。 -- 如果是计算资源不够，可以查看 TiDB Server 和 TiKV Server 节点的 CPU 消耗情况，再考虑添加 TiDB Server 节点或者是 TiKV Server 节点来解决，如添加 TiDB Server 节点，将其添加到前端 Load Balancer 配置之中即可。 -- 如果是容量跟不上，一般可以考虑同时增加 TiDB Server 和 TiKV Server 节点。 - -#### 3.1.14 Percolator 用了分布式锁，crash 的客户端会保持锁，会造成锁没有 release？ - -详细可参考 [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/)。 - -#### 3.1.15 TiDB 为什么选用 gRPC 而不选用 Thrift，是因为 Google 在用吗？ - -不只是因为 Google 在用，有一些比较好的特性我们需要，比如流控、加密还有 Streaming。 - -#### 3.1.16 like(bindo.customers.name, jason%, 92) 这个92代表什么？ - -那个是转义字符，默认是 (ASCII 92)。 - -#### 3.1.17 为什么 `information_schema.tables.data_length` 记录的大小和 TiKV 监控面板上的 store size 不一样？ - -这是因为两者计算的角度不一样。`information_schema.tables.data_length` 是通过统计信息（平均每行的大小）得到的估算值。TiKV 监控面板上的 store size 是单个 TiKV 实例的数据文件（RocksDB 的 SST 文件）的大小总和。由于多版本和 TiKV 会压缩数据，所以两者显示的大小不一样。 - -### 3.2 PD 管理 - -#### 3.2.1 访问 PD 报错：TiKV cluster is not bootstrapped - -PD 的大部分 API 需要在初始化 TiKV 集群以后才能使用，如果在部署新集群的时候只启动了 PD，还没有启动 TiKV，这时候访问 PD 就会报这个错误。遇到这个错误应该先把要部署的 TiKV 启动起来，TiKV 会自动完成初始化工作，然后就可以正常访问 PD。 - -#### 3.2.2 PD 启动报错：etcd cluster ID mismatch - -PD 启动参数中的 `--initial-cluster` 包含了某个不属于该集群的成员。遇到这个错误时请检查各个成员的所属集群，剔除错误的成员后即可正常启动。 - -#### 3.2.3 PD 能容忍的时间同步误差是多少？ - -理论上，时间同步误差越小越好。PD 可容忍任意时长的误差，但是，时间同步误差越大意味着 PD 分配的时间戳与真实的物理时间相差越大，这个差距会影响读历史版本等功能。 - -#### 3.2.4 Client 连接是如何寻找 PD 的？ - -Client 连接只能通过 TiDB 访问集群，TiDB 负责连接 PD 与 TiKV，PD 与 TiKV 对 Client 透明。当 TiDB 连接任意一台 PD 的时候，PD 会告知 TiDB 当前的 leader 是谁，如果此台 PD 不是 leader，TiDB 将会重新连接至 leader PD。 - -#### 3.2.5 PD 参数中 leader-schedule-limit 和 region-schedule-limit 调度有什么区别？ - -- leader-schedule-limit 调度是用来均衡不同 TiKV 的 leader 数，影响处理查询的负载。 -- region-schedule-limit 调度是均衡不同 TiKV 的副本数，影响不同节点的数据量。 - -#### 3.2.6 每个 region 的 replica 数量可配置吗？调整的方法是？ - -可以，目前只能调整全局的 replica 数量。首次启动时 PD 会读配置文件（conf/pd.yml），使用其中的 max-replicas 配置，之后修改需要使用 pd-ctl 配置命令 `config set max-replicas $num`，配置后可通过 `config show all` 来查看已生效的配置。调整的时候，不会影响业务，会在后台添加，注意总 TiKV 实例数总是要大于等于设置的副本数，例如 3 副本需要至少 3 个 TiKV。增加副本数量之前需要预估额外的存储需求。pd-ctl 的详细用法可参考 [PD Control 使用说明](/v3.1/reference/tools/pd-control.md)。 - -#### 3.2.7 缺少命令行集群管理工具，整个集群的健康度当前是否正常，不好确认？ - -可以通过 pd-ctl 等工具来判断集群大概的状态，详细的集群状态还是需要通过监控来确认。 - -#### 3.2.8 集群下线节点后，怎么删除老集群节点监控信息？ - -下线节点一般指 TiKV 节点通过 pd-ctl 或者监控判断节点是否下线完成。节点下线完成后，手动停止下线节点上相关的服务。从 Prometheus 配置文件中删除对应节点的 node_exporter 信息。从 Ansible inventory.ini 中删除对应节点的信息。 - -#### 3.2.9 使用 PD Control 连接 PD Server 时，为什么只能通过本机 IP 连接，不能通过 127.0.0.1 连接？ - -因为使用 TiDB Ansible 部署的集群，PD 对外服务端口不会绑定到 127.0.0.1，所以 PD Control 不会识别 127.0.0.1。 - -### 3.3 TiDB server 管理 - -#### 3.3.1 TiDB 的 lease 参数应该如何设置？ - -启动 TiDB Server 时，需要通过命令行参数设置 lease 参数（--lease=60），其值会影响 DDL 的速度（只会影响当前执行 DDL 的 session，其他的 session 不会受影响）。在测试阶段，lease 的值可以设为 1s，加快测试进度；在生产环境下，我们推荐这个值设为分钟级（一般可以设为 60），这样可以保证 DDL 操作的安全。 - -#### 3.3.2 DDL 在正常情况下的耗时是多少？ - -一般情况下处理一个 DDL 操作（之前没有其他 DDL 操作在处理）的耗时基本可以分如下为三种： - -- add index 操作，且此操作对应表数据行数比较少，耗时约为 3s。 -- add index 操作，且此操作对应表数据行数比较多，耗时具体由表中数据行数和当时 QPS 情况定（add index 操作优先级比一般 SQL 低）。 -- 其他 DDL 操作耗时约为 1s。 - -此外，如果接收 DDL 请求的 TiDB 和 DDL owner 所处的 TiDB 是一台，那么上面列举的第一和第三种可能的耗时应该在几十到几百毫秒。 - -#### 3.3.3 为什么有的时候执行 DDL 会很慢？ - -可能原因如下： - -- 多个 DDL 语句一起执行的时候，后面的几个 DDL 语句会比较慢。原因是当前 TiDB 集群中 DDL 操作是串行执行的。 -- 在正常集群启动后，第一个 DDL 操作的执行时间可能会比较久，一般在 30s 左右，这个原因是刚启动时 TiDB 在竞选处理 DDL 的 leader。 -- 由于停 TiDB 时不能与 PD 正常通信（包括停电情况）或者用 `kill -9` 指令停 TiDB 导致 TiDB 没有及时从 PD 清理注册数据，那么会影响 TiDB 启动后 10min 内的 DDL 语句处理时间。这段时间内运行 DDL 语句时，每个 DDL 状态变化都需要等待 2 * lease（默认 lease = 45s）。 -- 当集群中某个 TiDB 与 PD 之间发生通信问题，即 TiDB 不能从 PD 及时获取或更新版本信息，那么这时候 DDL 操作的每个状态处理需要等待 2 * lease。 - -#### 3.3.4 TiDB 可以使用 S3 作为后端存储吗？ - -不可以，目前 TiDB 只支持分布式存储引擎和 GolevelDB/RocksDB/BoltDB 引擎。 - -#### 3.3.5 Information_schema 能否支持更多真实信息？ - -Information_schema 库里面的表主要是为了兼容 MySQL 而存在，有些第三方软件会查询里面的信息。在目前 TiDB 的实现中，里面大部分只是一些空表。后续随着 TiDB 的升级，会提供更多的参数信息。当前 TiDB 支持的 Information\_schema 请参考 [TiDB 系统数据库说明文档](/v3.1/reference/system-databases/information-schema.md)。 - -#### 3.3.6 TiDB Backoff type 主要原因? - -TiDB-server 与 TiKV-server 随时进行通信，在进行大量数据操作过程中，会出现 `Server is busy` 或者 `backoff.maxsleep 20000ms` 的日志提示信息，这是由于 TiKV-server 在处理过程中系统比较忙而出现的提示信息，通常这时候可以通过系统资源监控到 TiKV 主机系统资源使用率比较高的情况出现。如果这种情况出现，可以根据资源使用情况进行相应的扩容操作。 - -#### 3.3.7 TiDB TiClient type 主要原因？ - -TiClient Region Error 该指标描述的是在 TiDB-server 作为客户端通过 KV 接口访问 TiKV-server 进行数据操作过程中，TiDB-server 操作 TiKV-server 中的 Region 数据出现的错误类型与 metric 指标，错误类型包括 not_leader、stale_epoch。出现这些错误的情况是当 TiDB-server 根据自己的缓存信息去操作 Region leader 数据的时候，Region leader 发生了迁移或者 TiKV 当前的 Region 信息与 TiDB 缓存的路由信息不一致而出现的错误提示。一般这种情况下，TiDB-server 都会自动重新从 PD 获取最新的路由数据，重做之前的操作。 - -#### 3.3.8 TiDB 同时支持的最大并发连接数？ - -当前版本 TiDB 没有最大连接数的限制，如果并发过大导致响应时间增加，可以通过增加 TiDB 节点进行扩容。 - -#### 3.3.9 如何查看某张表创建的时间？ - -information_schema 库中的 tables 表里的 create_time 即为表的真实创建时间。 - -#### 3.3.9 TiDB 的日志中 EXPENSIVE_QUERY 是什么意思？ - -TiDB 在执行 SQL 时，预估出来每个 operator 处理了超过 10000 条数据就认为这条 query 是 expensive query。可以通过修改 tidb-server 配置参数来对这个门限值进行调整，调整后需要重新启动 tidb-server。 - -#### 3.3.10 在 TiDB 中如何控制或改变 SQL 提交的执行优先级？ - -TiDB 支持改变 [per-session](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_force_priority)、[全局](/v3.1/reference/configuration/tidb-server/configuration-file.md#force-priority)或单个语句的优先级。优先级包括： - -- HIGH_PRIORITY：该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句 -- LOW_PRIORITY：该语句为低优先级语句，TiDB 在执行阶段会降低这条语句的优先级 - -以上两种参数可以结合 TiDB 的 DML 语言进行使用，使用方法举例如下： - -1. 通过在数据库中写 SQL 的方式来调整优先级： - - {{< copyable "sql" >}} - - ```sql - select HIGH_PRIORITY | LOW_PRIORITY count(*) from table_name; - insert HIGH_PRIORITY | LOW_PRIORITY into table_name insert_values; - delete HIGH_PRIORITY | LOW_PRIORITY from table_name; - update HIGH_PRIORITY | LOW_PRIORITY table_reference set assignment_list where where_condition; - replace HIGH_PRIORITY | LOW_PRIORITY into table_name; - ``` - -2. 全表扫会自动调整为低优先级，analyze 也是默认低优先级。 - -#### 3.3.11 在 TiDB 中 auto analyze 的触发策略是怎样的？ - -触发策略：新表达到 1000 条，并且在 1 分钟内没有写入，会自动触发。 - -当表的（修改数/当前总行数）大于 `tidb_auto_analyze_ratio` 的时候，会自动触发 `analyze` 语句。`tidb_auto_analyze_ratio` 的默认值为 0.5，即默认开启此功能。为了保险起见，在开启此功能的时候，保证了其最小值为 0.3。但是不能大于等于 `pseudo-estimate-ratio`（默认值为 0.8），否则会有一段时间使用 pseudo 统计信息，建议设置值为 0.5。 - -#### 3.3.12 SQL 中如何通过 hint 使用一个具体的 index？ - -同 MySQL 的用法一致，例如： -`select column_name from table_name use index（index_name）where where_condition;` - -#### 3.3.13 触发 Information schema is changed 错误的原因？ - -TiDB 在执行 SQL 语句时，会使用当时的 `schema` 来处理该 SQL 语句，而且 TiDB 支持在线异步变更 DDL。那么，在执行 DML 的时候可能有 DDL 语句也在执行，而你需要确保每个 SQL 语句在同一个 `schema` 上执行。所以当执行 DML 时，遇到正在执行中的 DDL 操作就可能会报 `Information schema is changed` 的错误。为了避免太多的 DML 语句报错，已做了一些优化。 - -现在会报此错的可能原因如下（后两个报错原因与表无关）： - -- 执行的 DML 语句中涉及的表和集群中正在执行的 DDL 的表有相同的，那么这个 DML 语句就会报此错。 -- 这个 DML 执行时间很久，而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 1024（v3.0.5 版本之前此值为定值 100。v3.0.5 及之后版本默认值为 1024，可以通过 `tidb_max_delta_schema_count` 变量修改）。 -- 接受 DML 请求的 TiDB 长时间不能加载到 `schema information`（TiDB 与 PD 或 TiKV 之间的网络连接故障等会导致此问题），而这段时间内执行了很多 DDL 语句，导致中间 `schema` 版本变更次数超过 100。 - -> **注意：** -> -> + 目前 TiDB 未缓存所有的 `schema` 版本信息。 -> + 对于每个 DDL 操作，`schema` 版本变更的数量与对应 `schema state` 变更的次数一致。 -> + 不同的 DDL 操作版本变更次数不一样。例如，`create table` 操作会有 1 次 `schema` 版本变更；`add column` 操作有 4 次 `schema` 版本变更。 - -#### 3.3.14 触发 Information schema is out of date 错误的原因？ - -当执行 DML 时，TiDB 超过一个 DDL lease 时间（默认 45s）没能加载到最新的 schema 就可能会报 `Information schema is out of date` 的错误。遇到此错的可能原因如下： - -- 执行此 DML 的 TiDB 被 kill 后准备退出，且此 DML 对应的事务执行时间超过一个 DDL lease，在事务提交时会报这个错误。 -- TiDB 在执行此 DML 时，有一段时间内连不上 PD 或者 TiKV，导致 TiDB 超过一个 DDL lease 时间没有 load schema，或者导致 TiDB 断开与 PD 之间带 keep alive 设置的连接。 - -#### 3.3.15 高并发情况下执行 DDL 时报错的原因？ - -高并发情况下执行 DDL（比如批量建表）时，极少部分 DDL 可能会由于并发执行时 key 冲突而执行失败。 - -并发执行 DDL 时，建议将 DDL 数量保持在 20 以下，否则你需要在应用端重试失败的 DDL 语句。 - -### 3.4 TiKV 管理 - -#### 3.4.1 TiKV 集群副本建议配置数量是多少，是不是最小高可用配置（3个）最好？ - -如果是测试环境 3 副本足够；在生产环境中，不可让集群副本数低于 3，需根据架构特点、业务系统及恢复能力的需求，适当增加副本数。值得注意的是，副本升高，性能会有下降，但是安全性更高。 - -#### 3.4.2 TiKV 启动报错：cluster ID mismatch - -TiKV 本地存储的 cluster ID 和指定的 PD 的 cluster ID 不一致。在部署新的 PD 集群的时候，PD 会随机生成一个 cluster ID，TiKV 第一次初始化的时候会从 PD 获取 cluster ID 存储在本地，下次启动的时候会检查本地的 cluster ID 与 PD 的 cluster ID 是否一致，如果不一致则会报错并退出。出现这个错误一个常见的原因是，用户原先部署了一个集群，后来把 PD 的数据删除了并且重新部署了新的 PD，但是 TiKV 还是使用旧的数据重启连到新的 PD 上，就会报这个错误。 - -#### 3.4.3 TiKV 启动报错：duplicated store address - -启动参数中的地址已经被其他的 TiKV 注册在 PD 集群中了。造成该错误的常见情况：TiKV `--data-dir` 指定的路径下没有数据文件夹（删除或移动后没有更新 --data-dir），用之前参数重新启动该 TiKV。请尝试用 pd-ctl 的 [store delete](https://github.com/pingcap/pd/tree/55db505e8f35e8ab4e00efd202beb27a8ecc40fb/tools/pd-ctl#store-delete--label--weight-store_id----jqquery-string) 功能，删除之前的 store，然后重新启动 TiKV 即可。 - -#### 3.4.4 TiKV master 和 slave 用的是一样的压缩算法，为什么效果不一样? - -目前来看 master 有些文件的压缩率会高一些，这个取决于底层数据的分布和 RocksDB 的实现，数据大小偶尔有些波动是正常的，底层存储引擎会根据需要调整数据。 - -#### 3.4.5 TiKV block cache 有哪些特性？ - -TiKV 使用了 RocksDB 的 Column Family (CF) 特性，KV 数据最终存储在默认 RocksDB 内部的 default、write、lock 3 个 CF 内。 - -- default CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中。 -- write CF 存储的是数据的版本信息（MVCC）、索引、小表相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中。 -- lock CF 存储的是锁信息，系统使用默认参数。 -- Raft RocksDB 实例存储 Raft log。default CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 -- 所有 CF 共享一个 Block-cache，用于缓存数据块，加速 RocksDB 的读取速度，Block-cache 的大小通过参数 `block-cache-size` 控制，`block-cache-size` 越大，能够缓存的热点数据越多，对读取操作越有利，同时占用的系统内存也会越多。 -- 每个 CF 有各自的 Write-buffer，大小通过 `write-buffer-size` 控制。 - -#### 3.4.6 TiKV channel full 是什么原因？ - -- Raftstore 线程太忙，或者因 I/O 而卡住。可以看一下 Raftstore 的 CPU 使用情况。 -- TiKV 过忙（CPU、磁盘 I/O 等），请求处理不过来。 - -#### 3.4.7 TiKV 频繁切换 Region leader 是什么原因？ - -- 网络问题导致节点间通信卡了，查看 Report failures 监控。 -- 原主 Leader 的节点卡了，导致没有及时给 Follower 发送消息。 -- Raftstore 线程卡了。 - -#### 3.4.8 如果一个节点挂了会影响服务吗？影响会持续多久？ - -TiDB 使用 Raft 在多个副本之间做数据同步（默认为每个 Region 3 个副本）。当一份备份出现问题时，其他的副本能保证数据的安全。根据 Raft 协议，当某个节点挂掉导致该节点里的 Leader 失效时，在最大 2 * lease time（leasetime 是 10 秒）时间后，通过 Raft 协议会很快将一个另外一个节点里的 Follower 选为新的 Region Leader 来提供服务。 - -#### 3.4.9 TiKV 在分别在那些场景下占用大量 IO、内存、CPU（超过参数配置的多倍）？ - -在大量写入、读取的场景中会占用大量的磁盘 IO、内存、CPU。在执行很复杂的查询，比如会产生很大中间结果集的情况下，会消耗很多的内存和 CPU 资源。 - -#### 3.4.10 TiKV 是否可以使用 SAS/SATA 盘或者进行 SSD/SAS 混合部署？ - -不可以使用，TiDB 在进行 OLTP 场景中，数据访问和操作需要高 IO 磁盘的支持，TiDB 作为强一致的分布式数据库，存在一定的写放大，如副本复制、存储底层 Compaction，因此，TiDB 部署的最佳实践中推荐用户使用 NVMe SSD 磁盘作为数据存储磁盘。另外，TiKV 与 PD 不能混合部署。 - -#### 3.4.11 数据表 Key 的 Range 范围划分是在数据接入之前就已经划分好了吗？ - -不是的，这个和 MySQL 分表规则不一样，需要提前设置好，TiKV 是根据 Region 的大小动态分裂的。 - -#### 3.4.12 Region 是如何进行分裂的？ - -Region 不是前期划分好的，但确实有 Region 分裂机制。当 Region 的大小超过参数 `region-max-size` 或 `region-max-keys` 的值时，就会触发分裂，分裂后的信息会汇报给 PD。 - -#### 3.4.13 TiKV 是否有类似 MySQL 的 `innodb_flush_log_trx_commit` 参数，来保证提交数据不丢失？ - -是的，TiKV 单机的存储引擎目前使用两个 RocksDB 实例，其中一个存储 raft-log，TiKV 有个 sync-log 参数，在 ture 的情况下，每次提交都会强制刷盘到 raft-log，如果发生 crash 后，通过 raft-log 进行 KV 数据的恢复。 - -#### 3.4.14 对 WAL 存储有什么推荐的硬件配置，例如 SSD，RAID 级别，RAID 卡 cache 策略，NUMA 设置，文件系统选择，操作系统的 IO 调度策略等？ - -WAL 属于顺序写，目前我们并没有单独对他进行配置，建议 SSD，RAID 如果允许的话，最好是 RAID 10，RAID 卡 cache、操作系统 I/O 调度目前没有针对性的最佳实践，Linux 7 以上默认配置即可，NUMA 没有特别建议，NUMA 内存分配策略可以尝试使用 `interleave = all`，文件系统建议 ext4。 - -#### 3.4.15 在最严格的 `sync-log = true` 数据可用模式下，写入性能如何？ - -一般来说，开启 `sync-log` 会让性能损耗 30% 左右。关闭 `sync-log` 时的性能表现，请参见 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 - -#### 3.4.16 是否可以利用 TiKV 的 Raft + 多副本达到完全的数据可靠，单机存储引擎是否需要最严格模式？ - -通过使用 [Raft 一致性算法](https://raft.github.io/)，数据在各 TiKV 节点间复制为多副本，以确保某个节点挂掉时数据的安全性。只有当数据已写入超过 50% 的副本时，应用才返回 ACK（三副本中的两副本）。但理论上两个节点也可能同时发生故障，所以除非是对性能要求高于数据安全的场景，一般都强烈推荐开启 `sync-log`。 - -另外，还有一种 `sync-log` 的替代方案，即在 Raft group 中用五个副本而非三个。这将允许两个副本同时发生故障，而仍然能保证数据安全性。 - -对于单机存储引擎也同样推荐打开 `sync-log` 模式。否则如果节点宕机可能会丢失最后一次写入数据。 - -#### 3.4.17 使用 Raft 协议，数据写入会有多次网络的 roundtrip，实际写入延迟如何？ - -理论上，和单机数据库相比，数据写入会多四个网络延迟。 - -#### 3.4.18 有没有类似 MySQL 的 InnoDB Memcached plugin，可以直接使用 KV 接口，可以不需要独立的 Cache？ - -TiKV 支持单独进行接口调用，理论上也可以起个实例做为 Cache，但 TiDB 最大的价值是分布式关系型数据库，我们原则上不对 TiKV 单独进行支持。 - -#### 3.4.19 Coprocessor 组件的主要作用？ - -- 减少 TiDB 与 TiKV 之间的数据传输。 -- 计算下推，充分利用 TiKV 的分布式计算资源。 - -#### 3.4.20 IO error: No space left on device While appending to file - -这是磁盘空间不足导致的，需要加节点或者扩大磁盘空间。 - -#### 3.4.21 为什么 TiKV 容易出现 OOM？ - -TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总内存的 40%。当 TiKV 容易出现 OOM 时，检查 `block-cache-size` 配置是否过高。还需要注意，当单机部署了多个 TiKV 实例时，需要显式地配置该参数，以防止多个实例占用过多系统内存导致 OOM。 - -#### 3.4.22 TiDB 数据和 RawKV 数据可存储于同一个 TiKV 集群里吗？ - -不可以。TiDB 数据（或使用其他事务 API 生成的数据）依赖于一种特殊的键值格式，和 RawKV API 数据（或其他基于 RawKV 的服务生成的数据）并不兼容。 - -### 3.5 TiDB 测试 - -#### 3.5.1 TiDB Sysbench 基准测试结果如何？ - -很多用户在接触 TiDB 都习惯做一个基准测试或者 TiDB 与 MySQL 的对比测试，官方也做了一个类似测试，汇总很多测试结果后，我们发现虽然测试的数据有一定的偏差，但结论或者方向基本一致，由于 TiDB 与 MySQL 由于架构上的差别非常大，很多方面是很难找到一个基准点，所以官方的建议两点： - -- 大家不要用过多精力纠结这类基准测试上，应该更多关注 TiDB 的场景上的区别。 -- 大家可以直接参考 [TiDB Sysbench 性能测试报告](https://github.com/pingcap/docs-cn/blob/master/dev/benchmark/sysbench-v4.md)。 - -#### 3.5.2 TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？ - -- 在 10 节点内，TiDB 写入能力（Insert TPS）和节点数量基本成 40% 线性递增，MySQL 由于是单节点写入，所以不具备写入扩展能力。 -- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://t.cn/RTD18qV)。 -- TiDB 不管是读流量、还是写流量都可以通过添加节点快速方便的进行扩展。 - -#### 3.5.3 我们的 DBA 测试过 MySQL 性能，单台 TiDB 的性能没有 MySQL 性能那么好？ - -TiDB 设计的目标就是针对 MySQL 单台容量限制而被迫做的分库分表的场景，或者需要强一致性和完整分布式事务的场景。它的优势是通过尽量下推到存储节点进行并行计算。对于小表（比如千万级以下），不适合 TiDB，因为数据量少，Region 有限，发挥不了并行的优势，最极端的就是计数器表，几行记录高频更新，这几行在 TiDB 里，会变成存储引擎上的几个 KV，然后只落在一个 Region 里，而这个 Region 只落在一个节点上。加上后台强一致性复制的开销，TiDB 引擎到 TiKV 引擎的开销，最后表现出来的就是没有单个 MySQL 好。 - -### 3.6 TiDB 备份恢复 - -#### 3.6.1 TiDB 主要备份方式？ - -目前，推荐的备份方式是使用 [PingCAP fork 的 Mydumper](/v3.1/reference/tools/mydumper.md)。尽管 TiDB 也支持使用 MySQL 官方工具 `mysqldump` 进行数据备份、恢复，但其性能低于 [`mydumper`](/v3.1/reference/tools/mydumper.md)/[`loader`](/v3.1/reference/tools/loader.md)，并且该工具备份、恢复大量数量时，要耗费更多时间。 - -使用 Mydumper 导出来的数据文件尽可能的小, 最好不要超过 64M, 可以设置参数 -F 64； - -loader 的 -t 参数可以根据 TiKV 的实例个数以及负载进行评估调整，例如 3 个 TiKV 的场景， 此值可以设为 3 * (1 ～ n)，当 TiKV 负载过高，loader 以及 TiDB 日志中出现大量 `backoffer.maxSleep 15000ms is exceeded` 可以适当调小该值，当 TiKV 负载不是太高的时候，可以适当调大该值。 - -## 四、数据、流量迁移 - -### 4.1 全量数据导出导入 - -#### 4.1.1 Mydumper - -参见 [Mydumper 使用文档](/v3.1/reference/tools/mydumper.md)。 - -#### 4.1.2 Loader - -参见 [Loader 使用文档](/v3.1/reference/tools/loader.md)。 - -#### 4.1.3 如何将一个运行在 MySQL 上的应用迁移到 TiDB 上？ - -TiDB 支持绝大多数 MySQL 语法，一般不需要修改代码。 - -#### 4.1.4 不小心把 MySQL 的 user 表导入到 TiDB 了，或者忘记密码，无法登录，如何处理？ - -重启 TiDB 服务，配置文件中增加 `-skip-grant-table=true` 参数，无密码登录集群后，可以根据情况重建用户，或者重建 mysql.user 表，具体表结构搜索官网。 - -#### 4.1.5 在 Loader 运行的过程中，TiDB 可以对外提供服务吗？ - -该操作进行逻辑插入，TiDB 仍可对外提供服务，但不要执行相关 DDL 操作。 - -#### 4.1.6 如何导出 TiDB 数据？ - -TiDB 目前暂时不支持 `select into outfile`，可以通过以下方式导出 TiDB 数据：参考 [MySQL 使用 mysqldump 导出某个表的部分数据](https://blog.csdn.net/xin_yu_xin/article/details/7574662)，使用 mysqldump 加 where 条件导出，使用 MySQL client 将 select 的结果输出到一个文件。 - -#### 4.1.7 如何从 DB2、Oracle 数据库迁移到 TiDB？ - -DB2、Oracle 到 TiDB 数据迁移（增量+全量），通常做法有： - -- 使用 Oracle 官方迁移工具，如 OGG、Gateway（透明网关）、CDC（Change Data Capture）。 -- 自研数据导出导入程序实现。 -- 导出（Spool）成文本文件，然后通过 Load infile 进行导入。 -- 使用第三方数据迁移工具。 - -目前看来 OGG 最为合适。 - -#### 4.1.8 用 Sqoop 批量写入 TiDB 数据，虽然配置了 `--batch` 选项，但还是会遇到 `java.sql.BatchUpdateExecption:statement count 5001 exceeds the transaction limitation` 的错误，该如何解决？ - -- 在 Sqoop 中，`--batch` 是指每个批次提交 100 条 statement，但是默认每个 statement 包含 100 条 SQL 语句，所以此时 100 * 100 = 10000 条 SQL 语句，超出了 TiDB 的事务限制 5000 条，可以增加选项 `-Dsqoop.export.records.per.statement=10` 来解决这个问题，完整的用法如下： - - {{< copyable "shell-regular" >}} - - ```bash - sqoop export \ - -Dsqoop.export.records.per.statement=10 \ - --connect jdbc:mysql://mysql.example.com/sqoop \ - --username sqoop ${user} \ - --password ${passwd} \ - --table ${tab_name} \ - --export-dir ${dir} \ - --batch - ``` - -- 也可以选择增大 tidb 的单个事物语句数量限制，不过这个会导致内存上涨。 - -#### 4.1.9 TiDB 有像 Oracle 那样的 Flashback Query 功能么，DDL 支持么？ - -有，也支持 DDL。详细参考 [TiDB 历史数据回溯](/v3.1/how-to/get-started/read-historical-data.md)。 - -### 4.2 在线数据同步 - -#### 4.2.1 Syncer 架构 - -详细参考 [解析 TiDB 在线数据同步工具 Syncer](https://pingcap.com/blog-cn/tidb-syncer/)。 - -##### 4.2.1.1 Syncer 使用文档 - -详细参考 [Syncer 使用文档](/v3.1/reference/tools/syncer.md)。 - -##### 4.2.1.2 如何配置监控 Syncer 运行情况？ - -下载 [Syncer Json](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json) 导入到 Grafana，修改 Prometheus 配置文件，添加以下内容： - -- job_name: 'syncer_ops' // 任务名字 - static_configs: -- targets: ['10.10.1.1:10096'] // Syncer 监听地址与端口，通知 prometheus 拉取 Syncer 的数据。 - -重启 Prometheus 即可。 - -##### 4.2.1.3 有没有现成的同步方案，可以将数据同步到 Hbase、Elasticsearh 等其他存储？ - -没有，目前依赖程序自行实现。 - -##### 4.2.1.4 利用 Syncer 做数据同步的时候是否支持只同步部分表？ - -支持，具体参考 Syncer 使用手册 [Syncer 使用文档](/v3.1/reference/tools/syncer.md) - -##### 4.2.1.5 频繁的执行 DDL 会影响 Syncer 同步速度吗？ - -频繁执行 DDL 对同步速度会有影响。对于 Sycner 来说，DDL 是串行执行的，当同步遇到了 DDL，就会以串行的方式执行，所以这种场景就会导致同步速度下降。 - -##### 4.2.1.6 使用 Syncer gtid 的方式同步时，同步过程中会不断更新 syncer.meta 文件，如果 Syncer 所在的机器坏了，导致 syncer.meta 文件所在的目录丢失，该如何处理？ - -当前 Syncer 版本的没有进行高可用设计，Syncer 目前的配置信息 syncer.meta 直接存储在硬盘上，其存储方式类似于其他 MySQL 生态工具，比如 Mydumper。因此，要解决这个问题当前可以有两个方法： - -1）把 syncer.meta 数据放到比较安全的磁盘上，例如磁盘做好 raid1； - -2）可以根据 Syncer 定期上报到 Prometheus 的监控信息来还原出历史同步的位置信息，该方法的位置信息在大量同步数据时由于延迟会可能不准确。 - -##### 4.2.1.7 Syncer 下游 TiDB 数据和 MySQL 数据不一致，DML 会退出么？ - -- 上游 MySQL 中存在数据，下游 TiDB 中该数据不存在，上游 MySQL 执行 `UPDATE` 或 `DELETE`（更新/删除）该条数据的操作时，Syncer 同步过程即不会报错退出也没有该条数据。 -- 下游有主键索引或是唯一索引冲突时，执行 `UPDATE` 会退出，执行 `INSERT` 不会退出。 - -### 4.3 业务流量迁入 - -#### 4.3.1 如何快速迁移业务流量？ - -我们建议通过 Syncer 工具搭建成多源 MySQL -> TiDB 实时同步环境，读写流量可以按照需求分阶段通过修改网络配置进行流量迁移，建议 DB 上层部署一个稳定的网络 LB（HAproxy、LVS、F5、DNS 等），这样直接修改网络配置就能实现无缝流量迁移。 - -#### 4.3.2 TiDB 总读写流量有限制吗？ - -TiDB 读流量可以通过增加 TiDB server 进行扩展，总读容量无限制，写流量可以通过增加 TiKV 节点进行扩容，基本上写容量也没有限制。 - -#### 4.3.3 Transaction too large 是什么原因，怎么解决？ - -由于分布式事务要做两阶段提交，并且底层还需要做 Raft 复制，如果一个事务非常大，会使得提交过程非常慢，并且会卡住下面的 Raft 复制流程。为了避免系统出现被卡住的情况，我们对事务的大小做了限制： - -- 单个事务包含的 SQL 语句不超过 5000 条（默认） -- 单条 KV entry 不超过 6MB -- KV entry 的总条数不超过 30w -- KV entry 的总大小不超过 100MB - -在 Google 的 Cloud Spanner 上面，也有类似的[限制](https://cloud.google.com/spanner/docs/limits)。 - -#### 4.3.4 如何批量导入？ - -导入数据的时候，可以分批插入，每批最好不要超过 1w 行。 - -#### 4.3.5 TiDB 中删除数据后会立即释放空间吗？ - -DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DROP 操作，在达到 TiDB 的 GC (garbage collection) 时间后（默认 10 分钟），TiDB 的 GC 机制会删除数据并释放空间。对于 DELETE 操作 TiDB 的 GC 机制会删除数据，但不会释放空间，而是当后续数据写入 RocksDB 且进行 compact 时对空间重新利用。 - -#### 4.3.6 Load 数据时可以对目标表执行 DDL 操作吗？ - -不可以，加载数据期间不能对目标表执行任何 DDL 操作，这会导致数据加载失败。 - -#### 4.3.7 TiDB 是否支持 replace into 语法？ - -支持，但是 load data 不支持 replace into 语法。 - -#### 4.3.8 数据删除后查询速度为何会变慢？ - -大量删除数据后，会有很多无用的 key 存在，影响查询效率。目前正在开发 Region Merge 功能，完善之后可以解决这个问题，具体看参考[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)中的删除数据部分。 - -#### 4.3.9 数据删除最高效最快的方式？ - -在删除大量数据的时候，建议使用 `Delete * from t where xx limit 5000`（xx 建议在满足业务过滤逻辑下，尽量加上强过滤索引列或者直接使用主键选定范围，如 `id >= 5000*n+m and id <= 5000*(n+1)+m` 这样的方案，通过循环来删除，用 `Affected Rows == 0` 作为循环结束条件，这样避免遇到事务大小的限制。如果一次删除的数据量非常大，这种循环的方式会越来越慢，因为每次删除都是从前向后遍历，前面的删除之后，短时间内会残留不少删除标记（后续会被 GC 掉），影响后面的 Delete 语句。如果有可能，建议把 Where 条件细化。可以参考官网[最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -#### 4.3.10 TiDB 如何提高数据加载速度？ - -主要有两个方面： - -- 目前已开发分布式导入工具 [Lightning](/v3.1/reference/tools/tidb-lightning/overview.md)，需要注意的是数据导入过程中为了性能考虑，不会执行完整的事务流程，所以没办法保证导入过程中正在导入的数据的 ACID 约束，只能保证整个导入过程结束以后导入数据的 ACID 约束。因此适用场景主要为新数据的导入（比如新的表或者新的索引），或者是全量的备份恢复（先 Truncate 原表再导入）。 -- TiDB 的数据加载与磁盘以及整体集群状态相关，加载数据时应关注该主机的磁盘利用率，TiClient Error/Backoff/Thread CPU 等相关 metric，可以分析相应瓶颈。 - -#### 4.3.11 对数据做删除操作之后，空间回收比较慢，如何处理？ - -可以设置并行 GC，加快对空间的回收速度。默认并发为 1，最大可调整为 tikv 实例数量的 50%。可使用 `update mysql.tidb set VARIABLE_VALUE="3" where VARIABLE_NAME="tikv_gc_concurrency";` 命令来调整。 - -## 五、SQL 优化 - -### 5.1 TiDB 执行计划解读 - -详细解读 [理解 TiDB 执行计划](/v3.1/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.1 统计信息收集 - -详细解读 [统计信息](/v3.1/reference/performance/statistics.md)。 - -#### 5.1.2 Count 如何加速？ - -Count 就是暴力扫表，提高并发度能显著的提升速度，修改并发度可以参考 `tidb_distsql_scan_concurrency` 变量，但是也要看 CPU 和 I/O 资源。TiDB 每次查询都要访问 TiKV，在数据量小的情况下，MySQL 都在内存里，TiDB 还需要进行一次网络访问。 - -提升建议： - -- 建议提升硬件配置，可以参考[部署建议](/v3.1/how-to/deploy/hardware-recommendations.md)。 -- 提升并发度，默认是 10，可以提升到 50 试试，但是一般提升在 2-4 倍之间。 -- 测试大数据量的 count。 -- 调优 TiKV 配置，可以参考[性能调优](/v3.1/reference/performance/tune-tikv.md)。 - -#### 5.1.3 查看当前 DDL 的进度？ - -通过 `admin show ddl` 查看当前 job 进度。操作如下： - -{{< copyable "sql" >}} - -```sql -admin show ddl; -``` - -``` -*************************** 1. row *************************** - SCHEMA_VER: 140 - OWNER: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -RUNNING_JOBS: ID:121, Type:add index, State:running, SchemaState:write reorganization, SchemaID:1, TableID:118, RowCount:77312, ArgLen:0, start time: 2018-12-05 16:26:10.652 +0800 CST, Err:, ErrCount:0, SnapshotVersion:404749908941733890 - SELF_ID: 1a1c4174-0fcd-4ba0-add9-12d08c4077dc -``` - -从上面操作结果可知，当前正在处理的是 `add index` 操作。且从 `RUNNING_JOBS` 列的 `RowCount` 字段可以知道当前 `add index` 操作已经添加了 77312 行索引。 - -#### 5.1.4 如何查看 DDL job？ - -可以使用 `admin show ddl` 语句查看正在运行的 DDL 作业。 - -- `admin show ddl jobs`：用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 -- `admin show ddl job queries 'job_id' [, 'job_id'] ...`：用于显示 `job_id` 对应的 DDL 任务的原始 SQL 语句。此 `job_id` 只搜索正在执行中的任务以及 DDL 历史作业队列中的最近十条结果。 - -#### 5.1.5 TiDB 是否支持基于 COST 的优化（CBO），如果支持，实现到什么程度？ - -是的，TiDB 使用的基于成本的优化器（CBO），我们有一个小组单独会对代价模型、统计信息持续优化，除此之外，我们支持 hash join、soft merge 等关联算法。 - -#### 5.1.6 如何确定某张表是否需要做 analyze ？ - -可以通过 `show stats_healthy` 来查看 Healthy 字段，一般小于等于 60 的表需要做 analyze。 - -#### 5.1.7 SQL 的执行计划展开成了树，ID 的序号有什么规律吗？这棵树的执行顺序会是怎么样的？ - -ID 没什么规律，只要是唯一就行，不过生成的时候，是有一个计数器，生成一个 plan 就加一，执行的顺序和序号无关，整个执行计划是一颗树，执行时从根节点开始，不断地向上返回数据。执行计划的理解，请参考[理解 TiDB 执行计划](/v3.1/reference/performance/understanding-the-query-execution-plan.md)。 - -#### 5.1.8 TiDB 执行计划中，task cop 在一个 root 下，这个是并行的么？ - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指被下推到 KV 端分布式执行的计算任务，root task 是指在 TiDB 端单点执行的计算任务。一般来讲 root task 的输入数据是来自于 cop task 的；但是 root task 在处理数据的时候，TiKV 上的 cop task 也可以同时处理数据，等待 TiDB 的 root task 拉取，所以从这个观点上来看，他们是并行的；但是存在数据上下游关系；在执行的过程中，某些时间段其实也是并行的，第一个 cop task 在处理 [100, 200] 的数据，第二个 cop task 在处理 [1, 100] 的数据。执行计划的理解，请参考[理解 TiDB 执行计划](/v3.1/reference/performance/understanding-the-query-execution-plan.md)。 - -## 六、数据库优化 - -### 6.1 TiDB - -#### 6.1.1 TiDB 参数及调整 - -详情参考 [TiDB 配置参数](/v3.1/reference/configuration/tidb-server/configuration.md)。 - -#### 6.1.2 如何打散热点 - -TiDB 中以 Region 分片来管理数据库，通常来讲，TiDB 的热点指的是 Region 的读写访问热点。而 TiDB 中对于 PK 非整数或没有 PK 的表，可以通过设置 `SHARD_ROW_ID_BITS` 来适度分解 Region 分片，以达到打散 Region 热点的效果。详情可参考官网 [TiDB 专用系统变量和语法](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)中 `SHARD_ROW_ID_BITS` 的介绍。 - -### 6.2 TiKV - -#### 6.2.1 TiKV 性能参数调优 - -详情参考 [TiKV 性能参数调优](/v3.1/reference/performance/tune-tikv.md)。 - -## 七、监控 - -### 7.1 Prometheus 监控框架 - -详细参考 [TiDB 监控框架概述](/v3.1/how-to/monitor/overview.md)。 - -### 7.2 监控指标解读 - -详细参考 [重要监控指标详解](/v3.1/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.1 目前的监控使用方式及主要监控指标，有没有更好看的监控？ - -TiDB 使用 Prometheus + Grafana 组成 TiDB 数据库系统的监控系统，用户在 Grafana 上通过 dashboard 可以监控到 TiDB 的各类运行指标，包括系统资源的监控指标，包括客户端连接与 SQL 运行的指标，包括内部通信和 Region 调度的指标，通过这些指标，可以让数据库管理员更好的了解到系统的运行状态，运行瓶颈等内容。在监控指标的过程中，我们按照 TiDB 不同的模块，分别列出了各个模块重要的指标项，一般用户只需要关注这些常见的指标项。具体指标请参见[官方文档](/v3.1/reference/key-monitoring-metrics/overview-dashboard.md)。 - -#### 7.2.2 Prometheus 监控数据默认 15 天自动清除一次，可以自己设定成 2 个月或者手动删除吗？ - -可以的，在 Prometheus 启动的机器上，找到启动脚本，然后修改启动参数，然后重启 Prometheus 生效。 - -```config ---storage.tsdb.retention="60d" -``` - -#### 7.2.3 Region Health 监控项 - -TiDB-2.0 版本中，PD metric 监控页面中，对 Region 健康度进行了监控，其中 Region Health 监控项是对所有 Region 副本状况的一些统计。其中 miss 是缺副本，extra 是多副本。同时也增加了按 Label 统计的隔离级别，level-1 表示这些 Region 的副本在第一级 Label 下是物理隔离的，没有配置 location label 时所有 Region 都在 level-0。 - -#### 7.2.4 Statement Count 监控项中的 selectsimplefull 是什么意思？ - -代表全表扫，但是可能是很小的系统表。 - -#### 7.2.5 监控上的 QPS 和 Statement OPS 有什么区别？ - -QPS 会统计执行的所有 SQL 命令，包括 use database、load data、begin、commit、set、show、insert、select 等。 - -Statement OPS 只统计 select、update、insert 等业务相关的，所以 Statement OPS 的统计和业务比较相符。 - -## 八、Cloud TiDB - -### 8.1 腾讯云 - -#### 8.1.1 目前 Cloud TiDB 都有那些云厂商？ - -Cloud TiDB 目前已经在腾讯云、UCloud 上线，都是数据库一级入口，欢迎大家使用。 - -## 九、故障排除 - -### 9.1 TiDB 自定义报错汇总 - -#### 9.1.1 ERROR 8005 (HY000) : Write Conflict, txnStartTS is stale - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -#### 9.1.2 ERROR 9001 (HY000) : PD Server Timeout - -请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络。 - -#### 9.1.3 ERROR 9002 (HY000) : TiKV Server Timeout - -请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络。 - -#### 9.1.4 ERROR 9003 (HY000) : TiKV Server is Busy - -TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.5 ERROR 9004 (HY000) : Resolve Lock Timeout - -清理锁超时，当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码是否有锁争用。 - -#### 9.1.6 ERROR 9005 (HY000) : Region is unavailable - -访问的 Region 不可用，某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志。 - -#### 9.1.7 ERROR 9006 (HY000) : GC life time is shorter than transaction duration - -`GC Life Time` 间隔时间过短，长事务本应读到的数据可能被清理了，可使用如下命令增加 `GC Life Time`： - -{{< copyable "sql" >}} - -```sql -update mysql.tidb set variable_value='30m' where variable_name='tikv_gc_life_time'; -``` - -其中 30m 代表仅清理 30 分钟前的数据，这可能会额外占用一定的存储空间。 - -#### 9.1.8 ERROR 9007 (HY000) : Write Conflict - -可以检查 `tidb_disable_txn_auto_retry` 是否为 on。如是，将其设置为 off；如已经是 off，将 `tidb_retry_limit` 调大到不再发生该错误。 - -### 9.2 MySQL 原生报错汇总 - -#### 9.2.1 ERROR 2013 (HY000): Lost connection to MySQL server during query 问题的排查方法？ - -- log 中是否有 panic -- dmesg 中是否有 oom，命令：`dmesg -T | grep -i oom` -- 长时间没有访问，也会收到这个报错，一般是 tcp 超时导致的，tcp 长时间不用, 会被操作系统 kill。 - -#### 9.2.2 ERROR 1105 (HY000): other error: unknown error Wire Error(InvalidEnumValue(4004)) 是什么意思？ - -这类问题一般是 TiDB 和 TiKV 版本不匹配，在升级过程尽量一起升级，避免版本 mismatch。 - -#### 9.2.3 ERROR 1148 (42000): the used command is not allowed with this TiDB version 问题的处理方法？ - -这个问题是因为在执行 `LOAD DATA LOCAL` 语句的时候，MySQL 客户端不允许执行此语句（即 `local_infile` 选项为 0）。解决方法是在启动 MySQL 客户端时，用 `--local-infile=1` 选项。具体启动指令类似：`mysql --local-infile=1 -u root -h 127.0.0.1 -P 4000`。有些 MySQL 客户端需要设置而有些不需要设置，原因是不同版本的 MySQL 客户端对 `local-infile` 的默认值不同。 - -#### 9.2.4 ERROR 9001 (HY000): PD server timeout start timestamp may fall behind safe point - -这个报错一般是 TiDB 访问 PD 出了问题，TiDB 后台有个 worker 会不断地从 PD 查询 safepoint，如果超过 100s 查不成功就会报这个错。一般是因为 PD 磁盘操作过忙、反应过慢，或者 TiDB 和 PD 之间的网络有问题。TiDB 常见错误码请参考[错误码与故障诊断](/v3.1/reference/error-codes.md)。 - -### 9.3 TiDB 日志中的报错信息 - -#### 9.3.1 EOF - -当客户端或者 proxy 断开连接时，TiDB 不会立刻察觉连接已断开，而是等到开始往连接返回数据时，才发现连接已断开，此时日志会打印 EOF 错误。 diff --git a/v3.1/faq/upgrade.md b/v3.1/faq/upgrade.md deleted file mode 100644 index 5e333f4a41a6..000000000000 --- a/v3.1/faq/upgrade.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: 升级后常见问题 -category: FAQ ---- - -# 升级后常见问题 - -本文列出了一些升级后可能会遇到的问题与解决办法。 - -## 执行 DDL 操作时遇到的字符集 (charset) 问题 - -TiDB 在 v2.1.0 以及之前版本（包括 v2.0 所有版本）中，默认字符集是 UTF8。从 v2.1.1 开始，默认字符集变更为 UTF8MB4。如果在 v2.1.0 及之前版本中，建表时显式指定了 table 的 charset 为 UTF8，那么升级到 v2.1.1 之后，执行 DDL 操作可能会失败。 - -要避免该问题，需注意以下两个要点： - -1. 在 v2.1.3 之前，TiDB 不支持修改 column 的 charset。所以，执行 DDL 操作时，新 column 的 charset 需要和旧 column 的 charset 保持一致。 - -2. 在 v2.1.3 之前，即使 column 的 charset 和 table 的 charset 不一样，`show create table` 也不会显示 column 的 charset，但可以通过 HTTP API 获取 table 的元信息来查看 column 的 charset，下文提供了示例。 - -### 问题 1：`unsupported modify column charset utf8mb4 not match origin utf8` - -- 升级前：v2.1.0 及之前版本 - - {{< copyable "sql" >}} - - ```sql - create table t(a varchar(10)) charset=utf8; - ``` - - ``` - Query OK, 0 rows affected - Time: 0.106s - ``` - - {{< copyable "sql" >}} - - ```sql - show create table t - ``` - - ``` - +-------+-------------------------------------------------------+ - | Table | Create Table | - +-------+-------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+-------------------------------------------------------+ - 1 row in set - Time: 0.006s - ``` - -- 升级后：v2.1.1、v2.1.2 会出现下面的问题，v2.1.3 以及之后版本不会出现下面的问题。 - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(20); - ``` - - ``` - ERROR 1105 (HY000): unsupported modify column charset utf8mb4 not match origin utf8 - ``` - -解决方案：显式指定 column charset，保持和原来的 charset 一致即可。 - -{{< copyable "sql" >}} - -```sql -alter table t change column a a varchar(22) character set utf8; -``` - -- 根据要点 1，此处如果不指定 column 的 charset，会用默认的 UTF8MB4，所以需要指定 column charset 保持和原来一致。 - -- 根据要点 2，用 HTTP API 获取 table 元信息，然后根据 column 名字和 Charset 关键字搜索即可找到 column 的 charset。 - - {{< copyable "shell-regular" >}} - - ```sh - curl "http://$IP:10080/schema/test/t" | python -m json.tool - ``` - - 这里用了 python 的格式化 json的工具，也可以不加，此处只是为了方便注释。 - - ```json - { - "ShardRowIDBits": 0, - "auto_inc_id": 0, - "charset": "utf8", # table 的 charset - "collate": "", - "cols": [ # 从这里开始列举 column 的相关信息 - { - ... - "id": 1, - "name": { - "L": "a", - "O": "a" # column 的名字 - }, - "offset": 0, - "origin_default": null, - "state": 5, - "type": { - "Charset": "utf8", # column a 的 charset - "Collate": "utf8_bin", - "Decimal": 0, - "Elems": null, - "Flag": 0, - "Flen": 10, - "Tp": 15 - } - } - ], - ... - } - ``` - -### 问题 2：`unsupported modify charset from utf8mb4 to utf8` - -- 升级前：v2.1.1，v2.1.2 - - {{< copyable "sql" >}} - - ```sql - create table t(a varchar(10)) charset=utf8; - ``` - - ``` - Query OK, 0 rows affected - Time: 0.109s - ``` - - {{< copyable "sql" >}} - - ```sql - show create table t; - ``` - - ``` - +-------+-------------------------------------------------------+ - | Table | Create Table | - +-------+-------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+-------------------------------------------------------+ - ``` - - 上面 `show create table` 只显示出了 table 的 charset，但其实 column 的 charset 是 UTF8MB4，这可以通过 HTTP API 获取 schema 来确认。这是一个 bug，即此处建表时 column 的 charset 应该要和 table 保持一致为 UTF8，该问题在 v2.1.3 中已经修复。 - -- 升级后：v2.1.3 及之后版本 - - {{< copyable "sql" >}} - - ```sql - show create table t; - ``` - - ``` - +-------+--------------------------------------------------------------------+ - | Table | Create Table | - +-------+--------------------------------------------------------------------+ - | t | CREATE TABLE `t` ( | - | | `a` varchar(10) CHARSET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL | - | | ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin | - +-------+--------------------------------------------------------------------+ - 1 row in set - Time: 0.007s - ``` - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(20); - ``` - - ``` - ERROR 1105 (HY000): unsupported modify charset from utf8mb4 to utf8 - ``` - -解决方案： - -- 因为在 v2.1.3 之后，TiDB 支持修改 column 和 table 的 charset，所以这里推荐修改 table 的 charset 为 UTF8MB4。 - - {{< copyable "sql" >}} - - ```sql - alter table t convert to character set utf8mb4; - ``` - -- 也可以像问题 1 一样指定 column 的 charset，保持和 column 原来的 charset (UTF8MB4) 一致即可。 - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(20) character set utf8mb4; - ``` - -### 问题 3：`ERROR 1366 (HY000): incorrect utf8 value f09f8c80(🌀) for column a` - -TiDB 在 v2.1.1 及之前版本中，如果 charset 是 UTF8，没有对 4-byte 的插入数据进行 UTF8 Unicode encoding 检查。在v2.1.2 及之后版本中，添加了该检查。 - -- 升级前：v2.1.1 及之前版本 - - {{< copyable "sql" >}} - - ```sql - create table t(a varchar(100) charset utf8); - ``` - - ``` - Query OK, 0 rows affected - ``` - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - Query OK, 1 row affected - ``` - -- 升级后：v2.1.2 及之后版本 - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - ERROR 1366 (HY000): incorrect utf8 value f09f8c80(🌀) for column a - ``` - -解决方案： - -- v2.1.2 版本：该版本不支持修改 column charset，所以只能跳过 UTF8 的检查。 - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_skip_utf8_check=1; - ``` - - ``` - Query OK, 0 rows affected - ``` - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - Query OK, 1 row affected - ``` - -- v2.1.3 及之后版本：建议修改 column 的 charset 为 UTF8MB4。或者也可以设置 `tidb_skip_utf8_check` 变量跳过 UTF8 的检查。如果跳过 UTF8 的检查，在需要将数据从 TiDB 同步回 MySQL 的时候，可能会失败，因为 MySQL 会执行该检查。 - - {{< copyable "sql" >}} - - ```sql - alter table t change column a a varchar(100) character set utf8mb4; - ``` - - ``` - Query OK, 0 rows affected - ``` - - {{< copyable "sql" >}} - - ```sql - insert t values (unhex('f09f8c80')); - ``` - - ``` - Query OK, 1 row affected - ``` - - 关于 `tidb_skip_utf8_check` 变量，具体来说是指跳过 UTF8 和 UTF8MB4 类型对数据的合法性检查。如果跳过这个检查，在需要将数据从 TiDB 同步回 MySQL 的时候，可能会失败，因为 MySQL 执行该检查。如果只想跳过 UTF8 类型的检查，可以设置 `tidb_check_mb4_value_in_utf8` 变量。 - - `tidb_check_mb4_value_in_utf8` 在 v2.1.3 版本加入 `config.toml` 文件，可以修改配置文件里面的 `check-mb4-value-in-utf8` 后重启集群生效。 - - `tidb_check_mb4_value_in_utf8` 在 v2.1.5 版本开始可以用 HTTP API 来设置，也可以用 session 变量来设置。 - - * HTTP API（HTTP API 只在单台服务器上生效） - - * 执行下列命令启用 HTTP API： - - {{< copyable "shell-regular" >}} - - ```sh - curl -X POST -d "check_mb4_value_in_utf8=1" http://{TiDBIP}:10080/settings - ``` - - * 执行下列命令禁用 HTTP API： - - {{< copyable "shell-regular" >}} - - ```sh - curl -X POST -d "check_mb4_value_in_utf8=0" http://{TiDBIP}:10080/settings - ``` - - * Session 变量 - - * 执行下列命令启用 Session 变量： - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_check_mb4_value_in_utf8 = 1; - ``` - - * 执行下列命令禁用 Session 变量： - - {{< copyable "sql" >}} - - ```sql - set @@session.tidb_check_mb4_value_in_utf8 = 0; - ``` - -- v2.1.7 及之后版本，如果对表和 column 的字符集没有严格要求为 UTF8，也不想修改客户端代码去跳过 UTF8 检查或者手动修改 column 的 charset，可以在配置文件中把 `treat-old-version-utf8-as-utf8mb4` 打开。该配置的作用是自动把 v2.1.7 版本之前创建的旧版本的表和 column 的 UTF8 字符集转成 UTF8MB4。这个转换是在 TiDB load schema 时在内存中将 UTF8 转成 UTF8MB4，不会对实际存储的数据做任何修改。在配置文件中关闭 `treat-old-version-utf8-as-utf8mb4` 并重启 TiDB 后，以前字符集为 UTF8 的表和 column 的字符集仍然还是 UTF8。 - - > **注意：** - > - > `treat-old-version-utf8-as-utf8mb4` 参数默认打开，如果客户端强制需要用 UTF8 而不用 UTF8MB4，需要在配置文件中关闭。 diff --git a/v3.1/glossary.md b/v3.1/glossary.md deleted file mode 100644 index 3b31e69e5d20..000000000000 --- a/v3.1/glossary.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: 术语表 -summary: 了解 TiDB 相关术语。 -category: glossary ---- - -# 术语表 - -## A - -### ACID - -ACID 是指数据库管理系统在写入或更新资料的过程中，为保证[事务](#事务)是正确可靠的，所必须具备的四个特性：原子性 (atomicity)、一致性 (consistency)、隔离性（isolation）以及持久性（durability）。 - -* 原子性 (atomicity) 指一个事务中的所有操作，或者全部完成，或者全部不完成，不会结束在中间某个环节。TiDB 通过 Primary Key 所在 [Region](#regionpeerraft-group) 的原子性来保证分布式事务的原子性。 -* 一致性 (consistency) 指在事务开始之前和结束以后，数据库的完整性没有被破坏。TiDB 在写入数据之前，会校验数据的一致性，校验通过才会写入内存并返回成功。 -* 隔离性 (isolation) 指数据库允许多个并发事务同时对其数据进行读写和修改的能力。隔离性可以防止多个事务并发执行时由于交叉执行而导致数据的不一致，主要用于处理并发场景。TiDB 目前只支持一种隔离级别，即可重复读。 -* 持久性 (durability) 指事务处理结束后，对数据的修改就是永久的，即便系统故障也不会丢失。在 TiDB 中，事务一旦提交成功，数据全部持久化存储到 TiKV，此时即使 TiDB 服务器宕机也不会出现数据丢失。 - -## L - -### Leader/Follower/Learner - -它们分别对应 [Peer](#regionpeerraft-group) 的三种角色。其中 Leader 负责响应客户端的读写请求；Follower 被动地从 Leader 同步数据，当 Leader 失效时会进行选举产生新的 Leader；Learner 是一种特殊的角色，它只参与同步 raft log 而不参与投票，在目前的实现中只短暂存在于添加副本的中间步骤。 - -## O - -### Operator - -Operator 是应用于一个 Region 的，服务于某个调度目的的一系列操作的集合。例如“将 Region 2 的 Leader 迁移至 Store 5”，“将 Region 2 的副本迁移到 Store 1, 4, 5”等。 - -Operator 可以是由 Scheduler 通过计算生成的，也可以是由外部 API 创建的。 - -### Operator Step - -Operator Step 是 Operator 执行过程的一个步骤，一个 Operator 常常会包含多个 Operator Step。 - -目前 PD 可生成的 Step 包括： - -- `TransferLeader`：将 Region Leader 迁移至指定 Peer -- `AddPeer`：在指定 Store 添加 Follower -- `RemovePeer`：删除一个 Region Peer -- `AddLearner`：在指定 Store 添加 Region Learner -- `PromoteLearner`：将指定 Learner 提升为 Follower -- `SplitRegion`：将指定 Region 一分为二 - -## P - -### Pending/Down - -Pending 和 Down 是 Peer 可能出现的两种特殊状态。其中 Pending 表示 Follower 或 Learner 的 raft log 与 Leader 有较大差距，Pending 状态的 Follower 无法被选举成 Leader。Down 是指 Leader 长时间没有收到对应 Peer 的消息，通常意味着对应节点发生了宕机或者网络隔离。 - -## R - -### Region/Peer/Raft Group - -每个 Region 负责维护集群的一段连续数据（默认配置下平均约 96 MiB），每份数据会在不同的 Store 存储多个副本（默认配置是 3 副本），每个副本称为 Peer。同一个 Region 的多个 Peer 通过 raft 协议进行数据同步，所以 Peer 也用来指代 raft 实例中的成员。TiKV 使用 multi-raft 模式来管理数据，即每个 Region 都对应一个独立运行的 raft 实例，我们也把这样的一个 raft 实例叫做一个 Raft Group。 - -### Region Split - -TiKV 集群中的 Region 不是一开始就划分好的，而是随着数据写入逐渐分裂生成的，分裂的过程被称为 Region Split。 - -其机制是集群初始化时构建一个初始 Region 覆盖整个 key space，随后在运行过程中每当 Region 数据达到一定量之后就通过 Split 产生新的 Region。 - -## S - -### Scheduler - -Scheduler（调度器）是 PD 中生成调度的组件。PD 中每个调度器是独立运行的，分别服务于不同的调度目的。常用的调度器及其调用目标有： - -- `balance-leader-scheduler`：保持不同节点的 Leader 均衡。 -- `balance-region-scheduler`：保持不同节点的 Peer 均衡。 -- `hot-region-scheduler`：保持不同节点的读写热点 Region 均衡。 -- `evict-leader-{store-id}`：驱逐某个节点的所有 Leader。（常用于滚动升级） - -### Store - -PD 中的 Store 指的是集群中的存储节点，也就是 tikv-server 实例。Store 与 TiKV 实例是严格一一对应的，即使在同一主机甚至同一块磁盘部署多个 TiKV 实例，这些实例也对会对应不同的 Store。 diff --git a/v3.1/how-to/configure/memory-control.md b/v3.1/how-to/configure/memory-control.md deleted file mode 100644 index 572802dd125d..000000000000 --- a/v3.1/how-to/configure/memory-control.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: TiDB 内存控制文档 -category: how-to ---- - -# TiDB 内存控制文档 - -目前 TiDB 已经能够做到追踪单条 SQL 查询过程中的内存使用情况，当内存使用超过一定阈值后也能采取一些操作来预防 OOM 或者排查 OOM 原因。在 TiDB 的配置文件中，我们可以使用如下配置来控制内存使用超阈值时 TiDB 的行为： - -{{< copyable "" >}} - -``` -# Valid options: ["log", "cancel"] -oom-action = "log" -``` - -- 如果上面的配置项使用的是 "log"，那么当一条 SQL 的内存使用超过一定阈值（由 session 变量 `tidb_mem_quota_query` 来控制）后，TiDB 会在 log 文件中打印一条 LOG，然后这条 SQL 继续执行，之后如果发生了 OOM 可以在 LOG 中找到对应的 SQL。 -- 如果上面的配置项使用的是 "cancel"，那么当一条 SQL 的内存使用超过一定阈值后，TiDB 会立即中断这条 SQL 的执行并给客户端返回一个 error，error 信息中会详细写明这条 SQL 执行过程中各个占用内存比较多的物理执行算子的内存使用情况。 - -## 如何配置一条 SQL 执行过程中的内存使用阈值 - -可以在配置文件中设置每个 Query 默认的 Memory Quota，例如将其设置为 32GB： - -{{< copyable "" >}} - -``` -mem-quota-query = 34359738368 -``` - -此外还可通过如下几个 session 变量来控制一条 Query 中的内存使用，大多数用户只需要设置 `tidb_mem_quota_query` 即可，其他变量是高级配置，大多数用户不需要关心： - -| 变量名 | 作用 | 单位 | 默认值 | -|-----------------------------------|---------------------------------------------------|-------|-----------| -| tidb_mem_quota_query | 配置整条 SQL 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_hashjoin | 配置 Hash Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_mergejoin | 配置 Merge Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_sort | 配置 Sort 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_topn | 配置 TopN 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_indexlookupreader | 配置 Index Lookup Reader 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_indexlookupjoin | 配置 Index Lookup Join 的内存使用阈值 | Byte | 32 << 30 | -| tidb_mem_quota_nestedloopapply | 配置 Nested Loop Apply 的内存使用阈值 | Byte | 32 << 30 | - -几个使用例子： - -配置整条 SQL 的内存使用阈值为 8GB： - -{{< copyable "sql" >}} - -```sql -set @@tidb_mem_quota_query = 8 << 30; -``` - -配置整条 SQL 的内存使用阈值为 8MB： - -{{< copyable "sql" >}} - -```sql -set @@tidb_mem_quota_query = 8 << 20; -``` - -配置整条 SQL 的内存使用阈值为 8KB： - -{{< copyable "sql" >}} - -```sql -set @@tidb_mem_quota_query = 8 << 10; -``` \ No newline at end of file diff --git a/v3.1/how-to/configure/time-zone.md b/v3.1/how-to/configure/time-zone.md deleted file mode 100644 index 081d51453e45..000000000000 --- a/v3.1/how-to/configure/time-zone.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: 时区支持 -category: how-to ---- - -# 时区支持 - -TiDB 使用的时区由 `time_zone` 全局变量和 session 变量决定。`time_zone` 的默认值是 `System`，`System` 对应的实际时区在 `TiDB` 集群 bootstrap 初始化时设置。具体逻辑如下: - -* 优先使用 `TZ` 环境变量 -* 如果失败，则从 `/etc/localtime` 的实际软链地址提取。 -* 如果上面两种都失败则使用 `UTC` 作为系统时区。 - -在运行过程中可以修改全局时区： - -{{< copyable "sql" >}} - -```sql -SET GLOBAL time_zone = timezone; -``` - -TiDB 还可以通过设置 session 变量 `time_zone` 为每个连接维护各自的时区。默认条件下，这个值取的是全局变量 `time_zone` 的值。修改 session 使用的时区： - -{{< copyable "sql" >}} - -```sql -SET time_zone = timezone; -``` - -查看当前使用的时区的值： - -{{< copyable "sql" >}} - -```sql -SELECT @@global.time_zone, @@session.time_zone; -``` - -设置 `time_zone` 的值的格式： - -* 'SYSTEM' 表明使用系统时间 -* 相对于 UTC 时间的偏移，比如 '+10:00' 或者 '-6:00' -* 某个时区的名字，比如 'Europe/Helsinki'， 'US/Eastern' 或 'MET' - -`NOW()` 和 `CURTIME()` 的返回值都受到时区设置的影响。 - -> **注意：** -> -> 只有 Timestamp 数据类型的值是受时区影响的。可以理解为， Timestamp 数据类型的实际表示使用的是 (字面值 + 时区信息)。其它时间和日期类型，比如 Datetime/Date/Time 是不包含时区信息的，所以也不受到时区变化的影响。 - -{{< copyable "sql" >}} - -```sql -create table t (ts timestamp, dt datetime); -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@time_zone = 'UTC'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values ('2017-09-30 11:11:11', '2017-09-30 11:11:11'); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@time_zone = '+8:00'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t; -``` - -``` -+---------------------|---------------------+ -| ts | dt | -+---------------------|---------------------+ -| 2017-09-30 19:11:11 | 2017-09-30 11:11:11 | -+---------------------|---------------------+ -1 row in set (0.00 sec) -``` - -上面的例子中，无论怎么调整时区的值，Datetime 类型字段的值是不受影响的，而 Timestamp 则随着时区改变，显示的值会发生变化。其实 Timestamp 持久化到存储的值始终没有变化过，只是根据时区的不同显示值不同。 - -Timestamp 类型和 Datetime 等类型的值，两者相互转换的过程中，会涉及到时区。这种情况一律基于 session 的当前 `time_zone` 时区处理。 - -另外，用户在导数据的过程中，也要需注意主库和从库之间的时区设定是否一致。 diff --git a/v3.1/how-to/deploy/data-migration-with-ansible.md b/v3.1/how-to/deploy/data-migration-with-ansible.md deleted file mode 100644 index 495f0123867f..000000000000 --- a/v3.1/how-to/deploy/data-migration-with-ansible.md +++ /dev/null @@ -1,570 +0,0 @@ ---- -title: 使用 DM-Ansible 部署 DM 集群 -category: how-to ---- - -# 使用 DM-Ansible 部署 DM 集群 - -DM-Ansible 是 PingCAP 基于 [Ansible](https://docs.ansible.com/ansible/latest/index.html) 的 [Playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html#about-playbooks) 研发的 DM (Data Migration) 集群部署工具。本文将介绍如何使用 DM-Ansible 快速部署 DM 集群。 - -## 准备工作 - -在开始之前，先确保您准备好了以下配置的机器： - -1. 部署目标机器若干，配置如下： - - - CentOS 7.3 (64-bit) 或更高版本，x86_64 架构（AMD64） - - 机器之间内网互通 - - 关闭防火墙，或开放服务端口 - -2. 一台中控机，配置如下： - - - 包含 Python 2.7 的 CentOS 7.3（64-bit）或更高版本 - - Ansible 2.5 或更高版本 - - 互联网访问 - -## 第 1 步：在中控机上安装依赖包 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -根据中控机的操作系统版本，运行相应命令如下： - -- CentOS 7： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && \ - yum -y install python-pip - ``` - -- Ubuntu： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH 密钥 - -> **注意：** -> -> 请确保使用 `root` 账户登录中控机。 - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 为 `tidb` 用户设置密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 在 sudo 文件尾部加上 `tidb ALL=(ALL) NOPASSWD: ALL`，为 `tidb` 用户设置免密使用 sudo。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH 密钥。 - - 执行以下 `su` 命令，将登录用户从 `root` 切换至 `tidb`。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 为 `tidb` 用户创建 SSH 密钥。当提示 `Enter passphrase` 时，按 Enter 键。命令成功执行后，生成的 SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为`/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：下载 DM-Ansible 至中控机 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -1. 打开 `/home/tidb` 目录。 -2. 执行以下命令下载 DM-Ansible。 - - {{< copyable "shell-regular" >}} - - ```bash - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz - ``` - - `{version}` 为期望下载的 DM 版本，如 `v1.0.1`、`v1.0.2` 等， - 可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 第 4 步：安装 DM-Ansible 及其依赖至中控机 - -> **注意：** -> -> - 请确保使用 `tidb` 账户登录中控机。 -> - 您需要使用 `pip` 方式下载安装 Ansible 及其依赖，否则可能会遇到兼容性问题。 DM-Ansible 当前与 Ansible 2.5 或更高版本兼容。 - -1. 在中控机上安装 DM-Ansible 及其依赖包： - - {{< copyable "shell-regular" >}} - - ```bash - tar -xzvf dm-ansible-{version}.tar.gz && \ - mv dm-ansible-{version} dm-ansible && \ - cd /home/tidb/dm-ansible && \ - sudo pip install -r ./requirements.txt - ``` - - Ansible 和相关依赖包含于 `dm-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 版本： - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 第 5 步：在中控机上配置 SSH 互信和 sudo 规则 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录至中控机。 - -1. 将您部署的目标机器的 IP 地址加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && \ - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.71 - 172.16.10.72 - 172.16.10.73 - - [all:vars] - username = tidb - ``` - -2. 运行如下命令，然后输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，创建 sudo 规则，并为中控机和部署目标机器之间配置 SSH 互信。 - -## 第 6 步：下载 DM 及监控组件安装包至中控机 - -> **注意：** -> -> 请确保中控机接入互联网。 - -在中控机上，运行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 第 7 步：编辑 `inventory.ini` 配置文件 - -> **注意：** -> -> 请确保使用 `tidb` 账户登录中控机。 - -打开并编辑 `/home/tidb/dm-ansible/inventory.ini` 文件如下，以管控 DM 集群。 - -```ini -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -根据场景需要，您可以在以下两种集群拓扑中任选一种： - -- [单节点上单个 DM-worker 实例的集群拓扑](#选项-1使用单节点上单个-dm-worker-实例的集群拓扑) -- [单节点上多个 DM-worker 实例的集群拓扑](#选项-2使用单节点上多个-dm-worker-实例的集群拓扑) - -通常情况下，我们推荐每个节点上部署单个 DM-Worker 实例。但如果您的机器拥有性能远超 [TiDB 软件和硬件环境要求](/v3.1/how-to/deploy/hardware-recommendations.md)中推荐配置的 CPU 和内存，并且每个节点配置 2 块以上的硬盘或大于 2T 的 SSD，您可以在单个节点上部署不超过 2 个 DM-Worker 实例。 - -### 选项 1：使用单节点上单个 DM-Worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1 | -| node3 | 172.16.10.73 | DM-worker2 | -| mysql-replica-01| 172.16.10.81 | MySQL | -| mysql-replica-02| 172.16.10.82 | MySQL | - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1 ansible_host=172.16.10.72 server_id=101 source_id="mysql-replica-01" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2 ansible_host=172.16.10.73 server_id=102 source_id="mysql-replica-02" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。关于 DM-worker 参数的更多信息，请参考 [DM-worker 配置及参数描述](#dm-worker-配置及参数描述)。 - -### 选项 2：使用单节点上多个 DM-worker 实例的集群拓扑 - -| 节点 | 主机 IP | 服务 | -| ---- | ------- | -------- | -| node1 | 172.16.10.71 | DM-master, Prometheus, Grafana, Alertmanager, DM Portal | -| node2 | 172.16.10.72 | DM-worker1-1, DM-worker1-2 | -| node3 | 172.16.10.73 | DM-worker2-1, DM-worker2-2 | - -编辑 `inventory.ini` 文件时，请注意区分这些变量：`server_id`，`deploy_dir`，和 `dm_worker_port`。 - -```ini -# DM 模块 -[dm_master_servers] -dm_master ansible_host=172.16.10.71 - -[dm_worker_servers] -dm_worker1_1 ansible_host=172.16.10.72 server_id=101 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker1_2 ansible_host=172.16.10.72 server_id=102 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm_worker2_1 ansible_host=172.16.10.73 server_id=103 deploy_dir=/data1/dm_worker dm_worker_port=8262 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -dm_worker2_2 ansible_host=172.16.10.73 server_id=104 deploy_dir=/data2/dm_worker dm_worker_port=8263 mysql_host=172.16.10.84 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -[dm_portal_servers] -dm_portal ansible_host=172.16.10.71 - -# 监控模块 -[prometheus_servers] -prometheus ansible_host=172.16.10.71 - -[grafana_servers] -grafana ansible_host=172.16.10.71 - -[alertmanager_servers] -alertmanager ansible_host=172.16.10.71 - -# 全局变量 -[all:vars] -cluster_name = test-cluster - -ansible_user = tidb - -dm_version = {version} - -deploy_dir = /data1/dm - -grafana_admin_user = "admin" -grafana_admin_password = "admin" -``` - -`{version}` 为当前 DM-Ansible 对应的版本号。 - -### DM-worker 配置及参数描述 - -| 变量名称 | 描述 | -| ------------- | ------- -| source_id | DM-worker 绑定到的一个数据库实例或是具有主从架构的复制组。当发生主从切换的时候，只需要更新 `mysql_host` 或 `mysql_port` 而不用更改该 ID 标识。 | -| server_id | DM-worker 伪装成一个 MySQL slave，该变量即为这个 slave 的 server ID，在 MySQL 集群中需保持全局唯一。取值范围 0 ~ 4294967295。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置。 | -| mysql_host | 上游 MySQL 主机。 | -| mysql_user | 上游 MySQL 用户名，默认值为 “root”。| -| mysql_password | 上游 MySQL 用户密码，需使用 `dmctl` 工具加密。请参考[使用 dmctl 加密上游 MySQL 用户密码](#使用-dmctl-加密上游-mysql-用户密码)。 | -| mysql_port | 上游 MySQL 端口， 默认 3306。 | -| enable_gtid | DM-worker 是否使用全局事务标识符（GTID）拉取 binlog。使用前提是在上游 MySQL 已开启 GTID 模式。 | -| relay_binlog_name | DM-worker 是否从指定 binlog 文件位置开始拉取 binlog。仅适用于本地无有效 relay log 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| relay_binlog_gtid | DM-worker 是否从指定 GTID 位置开始拉取 binlog。仅适用于本地无有效 relay log，且 `enable_gtid` 设置为 true 的情况。v1.0.2 及以上版本的 DM 会默认从最新位置开始拉取 binlog，一般情况下不需要手动配置。 | -| flavor | 代表 MySQL 的版本发布类型。 如果是官方版本，Percona 版，或 Cloud MySQL 版，其值为 “mysql”。 如果是 MariaDB，其值为 "mariadb"。默认值是 "mysql"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置。 | - -关于 `deploy_dir` 配置的更多信息，请参考[配置部署目录](#配置部署目录)。 - -### 使用 dmctl 加密上游 MySQL 用户密码 - -假定上游 MySQL 的用户密码为 `123456`，运行以下命令，并将生成的字符串添加至 DM-worker 的 `mysql_password` 变量。 - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/dm-ansible/resources/bin && \ -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -## 第 8 步：编辑 `inventory.ini` 文件中的变量 - -此步介绍如何编辑部署目录中的变量，如何配置 relay log 同步位置以及 relay log GTID 的同步模式。此外，还会描述 `inventory.ini` 中的全局变量。 - -### 配置部署目录 - -编辑 `deploy_dir` 变量以配置部署目录。 - -- 全局变量默认设为 `/home/tidb/deploy`，适用于所有服务。如果数据盘挂载于 `/data1` 目录，您可以通过以下修改将其变更至 `/data1/dm`。 - - ```ini - ## Global variables. - [all:vars] - deploy_dir = /data1/dm - ``` - -- 如果需要为某个服务创建单独的部署目录，您可以在 `inventory.ini` 中配置服务主机列表的同时设置 host 变量。此操作需要您添加第一列别名，以避免在混合服务部署场景下产生混淆。 - - ```ini - dm-master ansible_host=172.16.10.71 deploy_dir=/data1/deploy - ``` - -### 配置 relay log 同步位置 - -首次启动 DM-worker 时，您需要配置 `relay_binlog_name` 变量以指定 DM-worker 拉取上游 MySQL 或 MariaDB binlog 的起始位置。 - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 relay_binlog_name="binlog.000011" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name="binlog.000002" mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -> **注意：** -> -> 如未设定 `relay_binlog_name`，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 - -### 开启 relay log GTID 同步模式 - -在 DM 集群中，DM-worker 的 relay log 处理单元负责与上游 MySQL 或 MariaDB 通信，从而将 binlog 拉取至本地文件系统。 - -DM 目前支持 MySQL GTID 和 MariaDB GTID。您可以通过配置以下项目开启 relay log GTID 同步模式： - -- `enable_gtid`：打开 relay log GTID 同步模式以处理 master 和 slave 易位的场景 - -- `relay_binlog_gtid`：指定 DM-worker 开始拉取对应上游 MySQL 或 MariaDB binlog 的起始位置 - -示例配置如下： - -```yaml -[dm_worker_servers] -dm-worker1 ansible_host=172.16.10.72 source_id="mysql-replica-01" server_id=101 enable_gtid=true relay_binlog_gtid="aae3683d-f77b-11e7-9e3b-02a495f8993c:1-282967971,cc97fa93-f5cf-11e7-ae19-02915c68ee2e:1-284361339" mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - -dm-worker2 ansible_host=172.16.10.73 source_id="mysql-replica-02" server_id=102 relay_binlog_name=binlog.000002 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 -``` - -### 全局变量 - -| 变量名称 | 描述 | -| --------------- | ---------------------------------------------------------- | -| cluster_name | 集群名称，可调整 | -| dm_version | DM 版本，默认已配置 | -| grafana_admin_user | Grafana 管理员用户名称，默认值 `admin` | -| grafana_admin_password | Grafana 管理员账户的密码，用于通过 Ansible 导入 Dashboard。默认值为 `admin`。如果您在 Grafana 网页端修改了密码，请更新此变量。 | - -## 第 9 步：部署 DM 集群 - -使用 `ansible-playbook` 运行 Playbook，默认并发数量是 5。如果部署目标机器较多，您可以使用 `-f` 参数增加并发数量，例如，`ansible-playbook deploy.yml -f 10`。 - -以下部署操作示例使用中运行服务的用户为 `tidb`： - -1. 编辑 `dm-ansible/inventory.ini` 文件，确保 `ansible_user = tidb`。 - - ```ini - ansible_user = tidb - ``` - - > **注意：** - > - > 请勿将 `ansible_user` 设为 `root`，因为 `tidb-ansible` 限制服务需以普通用户运行。 - - 运行以下命令。如果所有服务都返回 `tidb`，则 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 运行以下命令。如果所有服务都返回 `root`，则 `tidb` 用户免密 sudo 操作配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 修改内核参数，并部署 DM 集群组件和监控组件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - -3. 启动 DM 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - - 此操作会按顺序启动 DM 集群的所有组件，包括 DM-master，DM-worker，以及监控组件。当一个 DM 集群被关闭后，您可以使用该命令将其开启。 - -## 第 10 步：关闭 DM 集群 - -如果您需要关闭一个 DM 集群，运行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -该操作会按顺序关闭整个 DM 集群中的所有组件，包括 DM-master，DM-worker，以及监控组件。 - -## 常见部署问题 - -### 默认服务端口 - -| 组件 | 端口变量 | 默认端口 | 描述 | -| :-- | :-- | :-- | :-- | -| DM-master | `dm_master_port` | 8261 | DM-master 服务交流端口 | -| DM-worker | `dm_worker_port` | 8262 | DM-worker 服务交流端口 | -| Prometheus | `prometheus_port` | 9090 | Prometheus 服务交流端口 | -| Grafana | `grafana_port` | 3000 | 外部 Web 监控服务及客户端（浏览器）访问端口 | -| Alertmanager | `alertmanager_port` | 9093 | Alertmanager 服务交流端口 | - -### 自定义端口 - -编辑 `inventory.ini` 文件，将服务端口的相关主机变量添加在对应服务 IP 地址后： - -```ini -dm_master ansible_host=172.16.10.71 dm_master_port=18261 -``` - -### 更新 DM-Ansible - -1. 使用 `tidb` 账户登录至中控机，进入 `/home/tidb` 目录，然后备份`dm-ansible` 文件夹。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - mv dm-ansible dm-ansible-bak - ``` - -2. 下载指定版本 DM-Ansible，解压。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - wget https://download.pingcap.org/dm-ansible-{version}.tar.gz && \ - tar -xzvf dm-ansible-{version}.tar.gz && \ - mv dm-ansible-{version} dm-ansible - ``` - -3. 迁移 `inventory.ini` 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb && \ - cp dm-ansible-bak/inventory.ini dm-ansible/inventory.ini - ``` - -4. 迁移 `dmctl` 配置。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible-bak/dmctl && \ - cp * /home/tidb/dm-ansible/dmctl/ - ``` - -5. 用 Playbook 下载最新的 DM 二进制文件。此文件会自动替换 `/home/tidb/dm-ansible/resource/bin/` 目录下的二进制文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` diff --git a/v3.1/how-to/deploy/data-migration-with-binary.md b/v3.1/how-to/deploy/data-migration-with-binary.md deleted file mode 100644 index 4edb3465ed87..000000000000 --- a/v3.1/how-to/deploy/data-migration-with-binary.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: 使用 DM binary 部署 DM 集群 -category: how-to ---- - -# 使用 DM binary 部署 DM 集群 - -本文将介绍如何使用 DM binary 快速部署 DM 集群。 - -## 准备工作 - -下载官方 binary，链接地址：[DM 下载](/v3.1/reference/tools/download.md#tidb-dm-data-migration)。 - -下载的文件中包括子目录 bin 和 conf。bin 目录下包含 dm-master、dm-worker、dmctl 以及 Mydumper 的二进制文件。conf 目录下有相关的示例配置文件。 - -## 使用样例 - -假设在两台服务器上部署 MySQL，在一台服务器上部署 TiDB（mocktikv 模式），另外在三台服务器上部署两个 DM-worker 实例和一个 DM-master 实例。各个节点的信息如下： - -| 实例 | 服务器地址 | -| :---------- | :----------- | -| MySQL1 | 192.168.0.1 | -| MySQL2 | 192.168.0.2 | -| TiDB | 192.168.0.3 | -| DM-master | 192.168.0.4 | -| DM-worker1 | 192.168.0.5 | -| DM-worker2 | 192.168.0.6 | - -MySQL1 和 MySQL2 中需要开启 binlog。DM-worker1 负责同步 MySQL1 的数据，DM-worker2 负责同步 MySQL2 的数据。下面以此为例，说明如何部署 DM。 - -### DM-worker 的部署 - -DM-worker 需要连接上游 MySQL，且为了安全，强制用户配置加密后的密码。首先使用 dmctl 对 MySQL 的密码进行加密，以密码为 "123456" 为例： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dmctl --encrypt "123456" -``` - -``` -fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg= -``` - -记录该加密后的值，用于下面部署 DM-worker 时的配置。 - -DM-worker 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -查看 DM-worker 的命令行参数说明： - -{{< copyable "shell-regular" >}} - -```bash -./bin/dm-worker --help -``` - -``` -Usage of worker: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值："info"） - -V 输出版本信息 - -checker-backoff-max duration - 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔（默认值："5m0s"，一般情况下不需要修改。如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-backoff-rollback duration - 任务检查模块中，调整自动恢复等待时间的间隔（默认值："5m0s"，一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改该参数） - -checker-check-enable - 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务（默认值：true） - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -print-sample-config - 打印示例配置 - -purge-expires int - relay log 的过期时间。DM-worker 会尝试自动删除最后修改时间超过了过期时间的 relay log（单位：小时） - -purge-interval int - 定期检查 relay log 是否过期的间隔时间（默认值：3600）（单位：秒） - -purge-remain-space int - 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log（默认值：15）（单位：GB） - -relay-dir string - 存储 relay log 的路径（默认值："./relay_log"） - -worker-addr string - DM-worker 的地址 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件来配置 DM-worker，把以下配置文件内容写入到 `conf/dm-worker1.toml` 中。 - -DM-worker 的配置文件： - -```toml -# Worker Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker 的地址 -worker-addr = ":8262" - -# 作为 MySQL slave 的 server ID，用于获取 MySQL 的 binlog -# 在一个 replication group 中，每个实例（master 和 slave）都应该有唯一的 server ID -# v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置 -server-id = 101 - -# 用于标识一个 replication group 或者 MySQL/MariaDB 实例 -source-id = "mysql-replica-01" - -# 上游实例类型，值可为 "mysql" 或者 "mariadb" -# v1.0.2 及以上版本的 DM 会自动识别上游实例类型，不需要手动配置 -flavor = "mysql" - -# MySQL 的连接地址 -[from] -host = "192.168.0.1" -user = "root" -password = "fCxfQ9XKCezSzuCD0Wf5dUD+LsKegSg=" -port = 3306 -``` - -在终端中使用下面的命令运行 DM-worker： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-worker -config conf/dm-worker1.toml -``` - -对于 DM-worker2，修改配置文件中的 `source-id` 为 `mysql-replica-02`，并将 `from` 配置部分修改为 MySQL2 的地址即可。如果因为没有多余的机器，将 DM-worker2 与 DM-worker1 部署在一台机器上，需要把两个 DM-worker 实例部署在不同的路径下，否则保存元信息和 relay log 的默认路径会冲突。 - -### DM-master 的部署 - -DM-master 提供命令行参数和配置文件两种配置方式。 - -**配置方式 1：命令行参数** - -DM-master 的命令行参数说明： - -```bash -./bin/dm-master --help -``` - -``` -Usage of dm-master: - -L string - 日志等级，值可以为 "debug"，"info"，"warn"，"error" 或者 "fatal"（默认值为 "info"） - -V 输出版本信息 - -config string - 配置文件的路径 - -log-file string - 日志文件的路径 - -master-addr string - DM-master 的地址 - -print-sample-config - 打印出 DM-master 的示例配置 -``` - -> **注意：** -> -> 某些情况下，无法使用命令行参数的方法来配置 DM-worker，因为有的配置并未暴露给命令行。 - -**配置方式 2：配置文件** - -推荐使用配置文件，把以下配置文件内容写入到 `conf/dm-master.toml` 中。 - -DM-master 的配置文件： - -```toml -# Master Configuration. - -# 日志配置 -log-level = "info" -log-file = "dm-master.log" - -# DM-master 监听地址 -master-addr = ":8261" - -# DM-Worker 的配置 -[[deploy]] -# 对应 DM-worker1 配置文件中的 source-id -source-id = "mysql-replica-01" -# DM-worker1 的服务地址 -dm-worker = "192.168.0.5:8262" - -[[deploy]] -# 对应 DM-worker2 配置文件中的 source-id -source-id = "mysql-replica-02" -# DM-worker2 的服务地址 -dm-worker = "192.168.0.6:8262" -``` - -在终端中使用下面的命令运行 DM-master： - -{{< copyable "shell-regular" >}} - -```bash -bin/dm-master -config conf/dm-master.toml -``` - -这样，DM 集群就部署成功了。下面创建简单的数据同步任务来使用 DM 集群。 - -### 创建数据同步任务 - -假设在 MySQL1 和 MySQL2 实例中有若干个分表，这些分表的结构相同，所在库的名称都以 "sharding" 开头，表名称都以 "t" 开头，并且主键或唯一键不存在冲突（即每张分表的主键或唯一键各不相同）。现在需要把这些分表同步到 TiDB 中的 `db_target.t_target` 表中。 - -首先创建任务的配置文件： - -{{< copyable "" >}} - -```yaml ---- -name: test -task-mode: all -is-sharding: true - -target-database: - host: "192.168.0.3" - port: 4000 - user: "root" - password: "" # 如果密码不为空，也需要配置 dmctl 加密后的密码 - -mysql-instances: - - source-id: "mysql-replica-01" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" - black-white-list: "instance" - route-rules: ["sharding-route-rules-table", "sharding-route-rules-schema"] - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - -black-white-list: - instance: - do-dbs: ["~^sharding[\\d]+"] - do-tables: - - db-name: "~^sharding[\\d]+" - tbl-name: "~^t[\\d]+" - -routes: - sharding-route-rules-table: - schema-pattern: sharding* - table-pattern: t* - target-schema: db_target - target-table: t_target - - sharding-route-rules-schema: - schema-pattern: sharding* - target-schema: db_target -``` - -将以上配置内容写入到 `conf/task.yaml` 文件中，使用 dmctl 创建任务： - -{{< copyable "shell-regular" >}} - -```bash -bin/dmctl -master-addr 192.168.0.4:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 -» -``` - -{{< copyable "" >}} - -```bash -» start-task conf/task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "192.168.0.5:8262", - "msg": "" - }, - { - "result": true, - "worker": "192.168.0.6:8262", - "msg": "" - } - ] -} -``` - -这样就成功创建了一个将 MySQL1 和 MySQL2 实例中的分表数据同步到 TiDB 的任务。 diff --git a/v3.1/how-to/deploy/geographic-redundancy/location-awareness.md b/v3.1/how-to/deploy/geographic-redundancy/location-awareness.md deleted file mode 100644 index d83363fd6c67..000000000000 --- a/v3.1/how-to/deploy/geographic-redundancy/location-awareness.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: 集群拓扑信息配置 -category: how-to ---- - -# 集群拓扑信息配置 - -## 概述 - -PD 能够根据 TiKV 集群的拓扑结构进行调度，使得 TiKV 的容灾能力最大化。 - -阅读本章前，请先确保阅读 [Ansible 部署方案](/v3.1/how-to/deploy/orchestrated/ansible.md) 和 [Docker 部署方案](/v3.1/how-to/deploy/orchestrated/docker.md)。 - -## TiKV 上报拓扑信息 - -可以通过 TiKV 的启动参数或者配置文件来让 TiKV 上报拓扑信息给 PD。 - -假设拓扑结构分为三级：zone > rack > host，可以通过 labels 来指定这些信息。 - -启动参数： - -``` -tikv-server --labels zone=,rack=,host= -``` - -配置文件： - -{{< copyable "" >}} - -```toml -[server] -labels = "zone=,rack=,host=" -``` - -## PD 理解 TiKV 拓扑结构 - -可以通过 PD 的配置文件让 PD 理解 TiKV 集群的拓扑结构。 - -{{< copyable "" >}} - -```toml -[replication] -max-replicas = 3 -location-labels = ["zone", "rack", "host"] -``` - -其中 `location-labels` 需要与 TiKV 的 `labels` 名字对应，这样 PD 才能知道这些 `labels` 代表了 TiKV 的拓扑结构。 - -> **注意：** -> -> 必须同时配置 PD 的 `location-labels` 和 TiKV 的 `labels` 参数，否则 `labels` 不会生效。 - -## PD 基于 TiKV 拓扑结构进行调度 - -PD 能够根据我们提供的拓扑信息作出最优的调度，我们只需要关心什么样的拓扑结构能够达到我们想要的效果。 - -假设我们使用三副本，并且希望一个数据中心挂掉的情况下，还能继续保持 TiDB 集群的高可用状态，我们至少需要四个数据中心。 - -假设我们有四个数据中心 (zone)，每个数据中心有两个机架 (rack)，每个机架上有两个主机 (host)。 -每个主机上面启动一个 TiKV 实例： - -``` -# zone=z1 -tikv-server --labels zone=z1,rack=r1,host=h1 -tikv-server --labels zone=z1,rack=r1,host=h2 -tikv-server --labels zone=z1,rack=r2,host=h1 -tikv-server --labels zone=z1,rack=r2,host=h2 - -# zone=z2 -tikv-server --labels zone=z2,rack=r1,host=h1 -tikv-server --labels zone=z2,rack=r1,host=h2 -tikv-server --labels zone=z2,rack=r2,host=h1 -tikv-server --labels zone=z2,rack=r2,host=h2 - -# zone=z3 -tikv-server --labels zone=z3,rack=r1,host=h1 -tikv-server --labels zone=z3,rack=r1,host=h2 -tikv-server --labels zone=z3,rack=r2,host=h1 -tikv-server --labels zone=z3,rack=r2,host=h2 - -# zone=z4 -tikv-server --labels zone=z4,rack=r1,host=h1 -tikv-server --labels zone=z4,rack=r1,host=h2 -tikv-server --labels zone=z4,rack=r2,host=h1 -tikv-server --labels zone=z4,rack=r2,host=h2 -``` - -也就是说，我们有 16 个 TiKV 实例，分布在 4 个不同的数据中心，8 个不同的机架，16 个不同的机器。 - -在这种拓扑结构下，PD 会优先把每一份数据的不同副本调度到不同的数据中心。 -这时候如果其中一个数据中心挂了，不会影响 TiDB 集群的高可用状态。 -如果这个数据中心一段时间内恢复不了，PD 会把这个数据中心的副本迁移出去。 - -总的来说，PD 能够根据当前的拓扑结构使得集群容灾能力最大化，所以如果我们希望达到某个级别的容灾能力， -就需要根据拓扑机构在不同的地理位置提供多于备份数 (`max-replicas`) 的机器。 diff --git a/v3.1/how-to/deploy/geographic-redundancy/overview.md b/v3.1/how-to/deploy/geographic-redundancy/overview.md deleted file mode 100644 index 80daae48a75e..000000000000 --- a/v3.1/how-to/deploy/geographic-redundancy/overview.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: 跨数据中心部署方案 -category: how-to ---- - -# 跨数据中心部署方案 - -作为 NewSQL 数据库，TiDB 兼顾了传统关系型数据库的优秀特性以及 NoSQL 数据库可扩展性，以及跨数据中心（下文简称“中心”）场景下的高可用。本文档旨在介绍跨数据中心部署的不同解决方案。 - -## 三中心部署方案 - -TiDB, TiKV, PD 分别分布在 3 个不同的中心，这是最常规，可用性最高的方案。 - -![三中心部署](/media/deploy-3dc.png) - -### 优点 - -所有数据的副本分布在三个数据中心，任何一个数据中心失效后，另外两个数据中心会自动发起 leader election，并在合理长的时间内（通常情况 20s 以内）恢复服务，并且不会产生数据丢失。 - -![三中心部署容灾](/media/deploy-3dc-dr.png) - -### 缺点 - -性能受网络延迟影响。 - -- 对于写入的场景，所有写入的数据需要同步复制到至少 2 个数据中心，由于 TiDB 写入过程使用两阶段提交，故写入延迟至少需要 2 倍数据中心间的延迟。 -- 对于读请求来说，如果数据 leader 与发起读取的 TiDB 节点不在同一个数据中心，也会受网络延迟影响。 -- TiDB 中的每个事务都需要向 PD leader 获取 TSO，当 TiDB 与 PD leader 不在同一个数据中心时，它上面运行的事务也会因此受网络延迟影响，每个有写入的事务会获取两次 TSO。 - -### 读性能优化 - -如果不需要每个数据中心同时对外提供服务，可以将业务流量全部派发到一个数据中心，并通过调度策略把 Region leader 和 PD leader 都迁移到同一个数据中心（我们在上文所述的测试中也做了这个优化）。这样一来，不管是从 PD 获取 TSO 还是读取 Region 都不受数据中心间网络的影响。当该数据中心失效后，PD leader 和 Region leader 会自动在其它数据中心选出，只需要把业务流量转移至其他存活的数据中心即可。 - -![三中心部署读性能优化](/media/deploy-3dc-optimize.png) - -## 两地三中心部署方案 - -两地三中心的方案与三数据中心类似，算是三机房方案根据业务特点进行的优化，区别是其中有两个数据中心距离很近（通常在同一个城市），网络延迟相对很小。这种场景下，我们可以把业务流量同时派发到同城的两个数据中心，同时控制 Region leader 和 PD leader 也分布在同城的两个数据中心。 - -![两地三中心部署方案](/media/deploy-2city3dc.png) - -与三数据中心方案相比，两地三中心有以下优势： - -- 写入速度更优 -- 两中心同时提供服务资源利用率更高 -- 依然能保证任何一个数据中心失效后保持可用并且不发生数据丢失 - -但是，缺陷是如果同城的两个数据中心同时失效（理论上讲要高于异地三数据中心损失 2 个的概率），将会导致不可用以及部分数据丢失。 - -## 两数据中心 + binlog 同步方案 - -两数据中心 + binlog 同步类似于传统的 MySQL 中 master/slave 方案。两个数据中心分别部署一套完整的 TiDB 集群，我们称之为主集群和从集群。正常情况下所有的请求都在主集群，写入的数据通过 binlog 异步同步至从集群并写入。 - -![binlog 同步部署方案](/media/deploy-binlog.png) - -当主集群整个数据中心失效后，业务可以切换至从集群，与 MySQL 类似，这种情况下会有一些数据缺失。对比 MySQL，这个方案的优势是数据中心内的 HA -- 少部分节点故障时，通过重新选举 leader 自动恢复服务，不需要人工干预。 - -![两中心 binlog 相互备份方案](/media/deploy-backup.png) - -另外部分用户采用这种方式做双数据中心多活，两个数据中心各有一个集群，将业务分为两个库，每个库服务一部分数据，每个数据中心的业务只会访问一个库，两个集群之间通过 binlog 将本数据中心业务所涉及的库中的数据变更同步到对端机房，形成环状备份。 - -> **注意：** -> -> 在两数据中心 + binlog 同步部署方案中，数据中心之间只有 binlog 异步复制。在数据中心间的延迟较高的情况下，从集群落后主集群的数据量会增大。当主集群故障后（DR），会造成数据丢失，丢失的数据量受网络延迟等因素影响。 - -## 高可用和容灾分析 - -对于三数据中心方案和两地三中心方案，我们能得到的保障是任意一个数据中心故障时，集群能自动恢复服务，不需要人工介入，并能保证数据一致性。注意各种调度策略都是用于帮助性能优化的，当发生故障时调度机制总是第一优先考虑可用性而不是性能。 - -对于两数据中心 + binlog 同步的方案，主集群内少量节点故障时也能自动恢复服务，不需要人工介入，并能保证数据一致性。当整个主集群故障时，需要人工切换至从集群，并可能发生一些数据丢失，数据丢失的数量取决于同步延迟，和网络条件有关。 diff --git a/v3.1/how-to/deploy/hardware-recommendations.md b/v3.1/how-to/deploy/hardware-recommendations.md deleted file mode 100644 index 198401dfa6a5..000000000000 --- a/v3.1/how-to/deploy/hardware-recommendations.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: TiDB 软件和硬件环境建议配置 -category: how-to ---- - -# TiDB 软件和硬件环境建议配置 - -TiDB 作为一款开源分布式 NewSQL 数据库，可以很好的部署和运行在 Intel 架构服务器环境及主流虚拟化环境，并支持绝大多数的主流硬件网络。作为一款高性能数据库系统，TiDB 支持主流的 Linux 操作系统环境。 - -## Linux 操作系统版本要求 - -| Linux 操作系统平台 | 版本 | -| :----------------------- | :----------: | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | -| Oracle Enterprise Linux | 7.3 及以上 | -| Ubuntu LTS | 16.04 及以上 | - -> **注意：** -> -> - TiDB 只支持 Red Hat 兼容内核 (RHCK) 的 Oracle Enterprise Linux，不支持 Oracle Enterprise Linux 提供的 Unbreakable Enterprise Kernel。 -> - TiDB 在 CentOS 7.3 的环境下进行过大量的测试，同时社区也有很多该操作系统部署的最佳实践，因此，建议使用 CentOS 7.3 以上的 Linux 操作系统来部署 TiDB。 -> - 以上 Linux 操作系统可运行在物理服务器以及 VMware、KVM、XEN 主流虚拟化环境上。 - -## 服务器建议配置 - -TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台。对于开发，测试，及生产环境的服务器硬件配置有以下要求和建议： - -### 开发及测试环境 - -| **组件** | **CPU** | **内存** | **本地存储** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 8核+ | 16 GB+ | 无特殊要求 | 千兆网卡 | 1（可与 PD 同机器） | -| PD | 4核+ | 8 GB+ | SAS, 200 GB+ | 千兆网卡 | 1（可与 TiDB 同机器） | -| TiKV | 8核+ | 32 GB+ | SSD, 200 GB+ | 千兆网卡 | 3 | - -> **注意：** -> -> - 验证测试环境中的 TiDB 和 PD 可以部署在同一台服务器上。 -> - 如进行性能相关的测试，避免采用低性能存储和网络硬件配置，防止对测试结果的正确性产生干扰。 -> - TiKV 的 SSD 盘推荐使用 NVME 接口以保证读写更快。 -> - 如果仅验证功能，建议使用 [Docker Compose 部署方案](/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md)单机进行测试。 -> - TiDB 对于磁盘的使用以存放日志为主，因此在测试环境中对于磁盘类型和容量并无特殊要求。 - -### 生产环境 - -| **组件** | **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | --- | -| TiDB | 16核+ | 32 GB+ | SAS | 万兆网卡（2块最佳） | 2 | -| PD | 4核+ | 8 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| TiKV | 16核+ | 32 GB+ | SSD | 万兆网卡（2块最佳） | 3 | -| 监控 | 8核+ | 16 GB+ | SAS | 千兆网卡 | 1 | - -> **注意：** -> -> - 生产环境中的 TiDB 和 PD 可以部署和运行在同服务器上，如对性能和可靠性有更高的要求，应尽可能分开部署。 -> - 生产环境强烈推荐使用更高的配置。 -> - TiKV 硬盘大小配置建议 PCI-E SSD 不超过 2 TB，普通 SSD 不超过 1.5 TB。 - -## 网络要求 - -TiDB 作为开源分布式 NewSQL 数据库，其正常运行需要网络环境提供如下的网络端口配置要求，管理员可根据实际环境中 TiDB 组件部署的方案，在网络侧和主机侧开放相关端口： - -| 组件 | 默认端口 | 说明 | -| :-- | :-- | :-- | -| TiDB | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | 20160 | TiKV 通信端口 | -| PD | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | 2380 | PD 集群节点间通信端口 | -| Pump | 8250 | Pump 通信端口 | -| Drainer | 8249 | Drainer 通信端口 | -| Prometheus | 9090 | Prometheus 服务通信端口 | -| Pushgateway | 9091 | TiDB，TiKV，PD 监控聚合和上报端口 | -| Node_exporter | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | 9308 | Kafka_exporter 通信端口，用于监控 binlog kafka 集群 | - -## 客户端 Web 浏览器要求 - -TiDB 提供了基于 [Grafana](https://grafana.com/) 的技术平台，对数据库集群的各项指标进行可视化展现。采用支持 Javascript 的微软 IE、Google Chrome、Mozilla Firefox 的较新版本即可访问监控入口。 diff --git a/v3.1/how-to/deploy/orchestrated/ansible.md b/v3.1/how-to/deploy/orchestrated/ansible.md deleted file mode 100644 index d933c4e85a67..000000000000 --- a/v3.1/how-to/deploy/orchestrated/ansible.md +++ /dev/null @@ -1,965 +0,0 @@ ---- -title: 使用 TiDB Ansible 部署 TiDB 集群 -category: how-to ---- - -# 使用 TiDB Ansible 部署 TiDB 集群 - -## 概述 - -Ansible 是一款自动化运维工具，[TiDB Ansible](https://github.com/pingcap/tidb-ansible) 是 PingCAP 基于 Ansible playbook 功能编写的集群部署工具。本文档介绍如何使用 TiDB Ansible 部署一个完整的 TiDB 集群。 - -本部署工具可以通过配置文件设置集群拓扑，完成以下各项运维工作： - -- 初始化操作系统参数 -- 部署 TiDB 集群（包括 PD、TiDB、TiKV 等组件和监控组件） -- [启动集群](/v3.1/how-to/maintain/ansible-operations.md#启动集群) -- [关闭集群](/v3.1/how-to/maintain/ansible-operations.md#关闭集群) -- [变更组件配置](/v3.1/how-to/upgrade/from-previous-version.md#编辑-tidb-集群组件配置文件) -- [集群扩容缩容](/v3.1/how-to/scale/with-ansible.md) -- [升级组件版本](/v3.1/how-to/upgrade/from-previous-version.md#滚动升级-tidb-集群组件) -- [集群开启 binlog](/v3.1/reference/tidb-binlog/overview.md) -- [清除集群数据](/v3.1/how-to/maintain/ansible-operations.md#清除集群数据) -- [销毁集群](/v3.1/how-to/maintain/ansible-operations.md#销毁集群) - -> **注意：** -> -> 对于生产环境，须使用 TiDB Ansible 部署 TiDB 集群。如果只是用于测试 TiDB 或体验 TiDB 的特性，建议[使用 Docker Compose 在单机上快速部署 TiDB 集群](/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md)。 - -## 准备机器 - -1. 部署目标机器若干 - - - 建议 4 台及以上，TiKV 至少 3 实例，且与 TiDB、PD 模块不位于同一主机，详见[部署建议](/v3.1/how-to/deploy/hardware-recommendations.md)。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统，x86_64 架构 (amd64)。 - - 机器之间内网互通。 - - > **注意：** - > - > 使用 Ansible 方式部署时，TiKV 及 PD 节点数据目录所在磁盘请使用 SSD 磁盘，否则无法通过检测。**如果仅验证功能，建议使用 [Docker Compose 部署方案](/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md) 单机进行测试**。 - -2. 部署中控机一台 - - - 中控机可以是部署目标机器中的某一台。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统（默认包含 Python 2.7）。 - - 该机器需开放外网访问，用于下载 TiDB 及相关软件安装包。 - -## 第 1 步：在中控机上安装系统依赖包 - -以 `root` 用户登录中控机，然后根据操作系统类型执行相应的安装命令。 - -- 如果中控机使用的是 CentOS 7 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - yum -y install epel-release git curl sshpass && \ - yum -y install python2-pip - ``` - -- 如果是中控机使用的是 Ubuntu 系统，执行以下命令： - - {{< copyable "shell-root" >}} - - ```bash - apt-get -y install git curl sshpass python-pip - ``` - -## 第 2 步：在中控机上创建 `tidb` 用户，并生成 SSH key - -以 `root` 用户登录中控机，执行以下步骤： - -1. 创建 `tidb` 用户。 - - {{< copyable "shell-root" >}} - - ```bash - useradd -m -d /home/tidb tidb - ``` - -2. 设置 `tidb` 用户密码。 - - {{< copyable "shell-root" >}} - - ```bash - passwd tidb - ``` - -3. 配置 `tidb` 用户 sudo 免密码，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾即可。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -4. 生成 SSH key。 - - 执行 `su` 命令，从 `root` 用户切换到 `tidb` 用户下。 - - {{< copyable "shell-root" >}} - - ```bash - su - tidb - ``` - - 创建 `tidb` 用户 SSH key，提示 `Enter passphrase` 时直接回车即可。执行成功后，SSH 私钥文件为 `/home/tidb/.ssh/id_rsa`，SSH 公钥文件为 `/home/tidb/.ssh/id_rsa.pub`。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-keygen -t rsa - ``` - - ``` - Generating public/private rsa key pair. - Enter file in which to save the key (/home/tidb/.ssh/id_rsa): - Created directory '/home/tidb/.ssh'. - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/tidb/.ssh/id_rsa. - Your public key has been saved in /home/tidb/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:eIBykszR1KyECA/h0d7PRKz4fhAeli7IrVphhte7/So tidb@172.16.10.49 - The key's randomart image is: - +---[RSA 2048]----+ - |=+o+.o. | - |o=o+o.oo | - | .O.=.= | - | . B.B + | - |o B * B S | - | * + * + | - | o + . | - | o E+ . | - |o ..+o. | - +----[SHA256]-----+ - ``` - -## 第 3 步：在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录。使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 3.0 [相应 TAG 版本](https://github.com/pingcap/tidb-ansible/tags)，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone -b $tag https://github.com/pingcap/tidb-ansible.git -``` - -> **注意：** -> -> - `$tag` 替换为选定的 TAG 版本的值，例如 `v3.0.2`。 -> - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 -> - 请务必按文档操作，将 `tidb-ansible` 下载到 `/home/tidb` 目录下，权限为 `tidb` 用户，不要下载到 `/root` 下，否则会遇到权限问题。 - -## 第 4 步：在中控机器上安装 Ansible 及其依赖 - -以 `tidb` 用户登录中控机，请务必按以下方式通过 `pip` 安装 Ansible 及其相关依赖的指定版本，否则会有兼容问题。目前，TiDB release-2.0、release-2.1、release-3.0、release-3.1 及最新开发版本兼容 Ansible 2.4 ~ 2.7.11 (2.4 ≤ Ansible ≤ 2.7.11)。 - -1. 在中控机器上安装 Ansible 及其依赖。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - sudo pip install -r ./requirements.txt - ``` - - Ansible 及相关依赖的版本信息记录在 `tidb-ansible/requirements.txt` 文件中。 - -2. 查看 Ansible 的版本。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.7.11 - ``` - -## 第 5 步：在中控机上配置部署机器 SSH 互信及 sudo 规则 - -以 `tidb` 用户登录中控机，然后执行以下步骤： - -1. 将你的部署目标机器 IP 添加到 `hosts.ini` 文件的 `[servers]` 区块下。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && \ - vi hosts.ini - ``` - - ```ini - [servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - - [all:vars] - username = tidb - ntp_server = pool.ntp.org - ``` - -2. 执行以下命令，按提示输入部署目标机器的 `root` 用户密码。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步骤将在部署目标机器上创建 `tidb` 用户，并配置 sudo 规则，配置中控机与部署目标机器之间的 SSH 互信。 - -如果要手工配置 SSH 互信及 sudo 免密码，可参考[如何手工配置 ssh 互信及 sudo 免密码](#如何手工配置-ssh-互信及-sudo-免密码)。 - -## 第 6 步：在部署目标机器上安装 NTP 服务 - -> **注意：** -> -> 如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略。可参考[如何检测 NTP 服务是否正常](#如何检测-ntp-服务是否正常)。 - -以 `tidb` 用户登录中控机，执行以下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd /home/tidb/tidb-ansible && \ -ansible-playbook -i hosts.ini deploy_ntp.yml -u tidb -b -``` - -该步骤将在部署目标机器上使用系统自带软件源联网安装并启动 NTP 服务，服务使用安装包默认的 NTP server 列表，见配置文件 `/etc/ntp.conf` 中 server 参数。如果使用默认的 NTP server，你的机器需要连接外网。 - -为了让 NTP 尽快开始同步，启动 NTP 服务前，系统会执行 `ntpdate` 命令，与用户在 `hosts.ini` 文件中指定的 `ntp_server` 同步日期与时间。默认的服务器为 `pool.ntp.org`，也可替换为你的 NTP server。 - -## 第 7 步：在部署目标机器上配置 CPUfreq 调节器模式 - -为了让 CPU 发挥最大性能，请将 CPUfreq 调节器模式设置为 `performance` 模式。如需了解 CPUfreq 的更多信息，可查看[使用 CPUFREQ 调控器](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/power_management_guide/cpufreq_governors#cpufreq_setup)文档。 - -### 查看系统支持的调节器模式 - -执行以下 `cpupower` 命令，可查看系统支持的调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: performance powersave -``` - -> **注意：** -> -> 本例中系统支持设置 `performance` 和 `powersave` 模式。如果返回 `Not Available`，表示当前系统不支持配置 CPUfreq，跳过该步骤即可。 - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --governors -``` - -``` -analyzing CPU 0: - available cpufreq governors: Not Available -``` - -### 查看系统当前的 CPUfreq 调节器模式 - -执行以下 `cpupower` 命令，可查看系统当前的 CPUfreq 调节器模式： - -{{< copyable "shell-root" >}} - -```bash -cpupower frequency-info --policy -``` - -``` -analyzing CPU 0: - current policy: frequency should be within 1.20 GHz and 3.20 GHz. - The governor "powersave" may decide which speed to use - within this range. -``` - -如上述代码所示，本例中的当前配置是 `powersave` 模式。 - -### 修改调节器模式 - -你可以通过以下两种方法来修改调节器模式。本例中，当前调节器模式为 `powersave`，以下命令会将模式变更为 `performance`。 - -- 使用 `cpupower frequency-set --governor` 命令来修改。 - - {{< copyable "shell-root" >}} - - ```bash - cpupower frequency-set --governor performance - ``` - -- 使用以下命令在部署目标机器上批量设置。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i hosts.ini all -m shell -a "cpupower frequency-set --governor performance" -u tidb -b - ``` - -## 第 8 步：在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -使用 `root` 用户登录目标机器，将部署目标机器数据盘格式化成 ext4 文件系统，挂载时添加 `nodelalloc` 和 `noatime` 挂载参数。`nodelalloc` 是必选参数，否则 Ansible 安装时检测无法通过；`noatime` 是可选建议参数。 - -> **注意：** -> -> 如果你的数据盘已经格式化成 ext4 并挂载了磁盘，可先执行 `umount /dev/nvme0n1p1` 命令卸载，从编辑 `/etc/fstab` 文件步骤开始执行，添加挂载参数重新挂载即可。 - -以 `/dev/nvme0n1` 数据盘为例，具体操作步骤如下： - -1. 查看数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - fdisk -l - ``` - - ``` - Disk /dev/nvme0n1: 1000 GB - ``` - -2. 创建分区表。 - - {{< copyable "shell-root" >}} - - ```bash - parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1 - ``` - - > **注意：** - > - > 使用 `lsblk` 命令查看分区的设备号：对于 nvme 磁盘，生成的分区设备号一般为 `nvme0n1p1`；对于普通磁盘（例如 `/dev/sdb`），生成的的分区设备号一般为 `sdb1`。 - -3. 格式化文件系统。 - - {{< copyable "shell-root" >}} - - ```bash - mkfs.ext4 /dev/nvme0n1p1 - ``` - -4. 查看数据盘分区 UUID。 - - 本例中 `nvme0n1p1` 的 UUID 为 `c51eb23b-195c-4061-92a9-3fad812cc12f`。 - - {{< copyable "shell-root" >}} - - ```bash - lsblk -f - ``` - - ``` - NAME FSTYPE LABEL UUID MOUNTPOINT - sda - ├─sda1 ext4 237b634b-a565-477b-8371-6dff0c41f5ab /boot - ├─sda2 swap f414c5c0-f823-4bb1-8fdf-e531173a72ed - └─sda3 ext4 547909c1-398d-4696-94c6-03e43e317b60 / - sr0 - nvme0n1 - └─nvme0n1p1 ext4 c51eb23b-195c-4061-92a9-3fad812cc12f - ``` - -5. 编辑 `/etc/fstab` 文件，添加 `nodelalloc` 挂载参数。 - - {{< copyable "shell-root" >}} - - ```bash - vi /etc/fstab - ``` - - ``` - UUID=c51eb23b-195c-4061-92a9-3fad812cc12f /data1 ext4 defaults,nodelalloc,noatime 0 2 - ``` - -6. 挂载数据盘。 - - {{< copyable "shell-root" >}} - - ```bash - mkdir /data1 && \ - mount -a - ``` - -7. 执行以下命令，如果文件系统为 ext4，并且挂载参数中包含 `nodelalloc`，则表示已生效。 - - {{< copyable "shell-root" >}} - - ```bash - mount -t ext4 - ``` - - ``` - /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered) - ``` - -## 第 9 步：编辑 `inventory.ini` 文件，分配机器资源 - -以 `tidb` 用户登录中控机，编辑 `/home/tidb/tidb-ansible/inventory.ini` 文件为 TiDB 集群分配机器资源。一个标准的 TiDB 集群需要 6 台机器：2 个 TiDB 实例，3 个 PD 实例，3 个 TiKV 实例。 - -- 至少需部署 3 个 TiKV 实例。 -- 不要将 TiKV 实例与 TiDB 或 PD 实例混合部署在同一台机器上。 -- 将第一台 TiDB 机器同时用作监控机。 - -> **注意：** -> -> 请使用内网 IP 来部署集群，如果部署目标机器 SSH 端口非默认的 22 端口，需添加 `ansible_port` 变量，如 `TiDB1 ansible_host=172.16.10.1 ansible_port=5555`。 - -你可以根据实际场景从以下两种集群拓扑中选择一种： - -- [单机单 TiKV 实例集群拓扑](#单机单-tikv-实例集群拓扑) - - 默认情况下，建议在每个 TiKV 节点上仅部署一个 TiKV 实例，以提高性能。但是，如果你的 TiKV 部署机器的 CPU 和内存配置是[部署建议](/v3.1/how-to/deploy/hardware-recommendations.md)的两倍或以上，并且一个节点拥有两块 SSD 硬盘或者单块 SSD 硬盘的容量大于 2 TB，则可以考虑部署两实例，但不建议部署两个以上实例。 - -- [单机多 TiKV 实例集群拓扑](#单机多-tikv-实例集群拓扑) - -### 单机单 TiKV 实例集群拓扑 - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -[tikv_servers] -172.16.10.4 -172.16.10.5 -172.16.10.6 - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 -``` - -### 单机多 TiKV 实例集群拓扑 - -以两实例为例： - -| Name | Host IP | Services | -| :---- | :------- | :-------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1-1, TiKV1-2 | -| node5 | 172.16.10.5 | TiKV2-1, TiKV2-2 | -| node6 | 172.16.10.6 | TiKV3-1, TiKV3-2 | - -```ini -[tidb_servers] -172.16.10.1 -172.16.10.2 - -[pd_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 - -# 注意：要使用 TiKV 的 labels，必须同时配置 PD 的 location_labels 参数，否则 labels 设置不生效。 -[tikv_servers] -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv1" -TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv1" -TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv2" -TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv2" -TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 labels="host=tikv3" -TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 labels="host=tikv3" - -# 部署 3.0 版本的 TiDB 集群时，多实例场景需要额外配置 status 端口，示例如下： -# TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" -# TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" -# TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" -# TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" -# TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" -# TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - -[monitoring_servers] -172.16.10.1 - -[grafana_servers] -172.16.10.1 - -[monitored_servers] -172.16.10.1 -172.16.10.2 -172.16.10.3 -172.16.10.4 -172.16.10.5 -172.16.10.6 - -# 注意：为使 TiKV 的 labels 设置生效，部署集群时必须设置 PD 的 location_labels 参数。 -[pd_servers:vars] -location_labels = ["host"] -``` - -- 服务配置文件参数调整 - - 1. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `block-cache-size` 下面的 `capacity` 参数： - - ```yaml - storage: - block-cache: - capacity: "1GB" - ``` - - > **注意：** - > - > TiKV 实例数量指每个服务器上 TiKV 的进程数量。 - > - > 推荐设置：`capacity` = MEM_TOTAL * 0.5 / TiKV 实例数量 - - 2. 多实例情况下，需要修改 `tidb-ansible/conf/tikv.yml` 中 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ```yaml - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 推荐配置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 - - 3. 如果多个 TiKV 实例部署在同一块物理磁盘上，需要修改 `conf/tikv.yml` 中的 `capacity` 参数： - - ```yaml - raftstore: - capacity: 0 - ``` - - > **注意：** - > - > 推荐配置：`capacity` = 磁盘总容量 / TiKV 实例数量，例如：`capacity: "100GB"`。 - -## 第 10 步：调整 `inventory.ini` 文件中的变量 - -本小节介绍如何编辑部署目录的变量和 `inventory.ini` 文件中的其它变量。 - -### 调整部署目录 - -部署目录通过 `deploy_dir` 变量控制，默认全局变量已设置为 `/home/tidb/deploy`，对所有服务生效。如数据盘挂载目录为 `/data1`，可设置为 `/data1/deploy`，样例如下： - -```ini -## Global variables -[all:vars] -deploy_dir = /data1/deploy -``` - -如为某一服务单独设置部署目录，可在配置服务主机列表时配置主机变量，以 TiKV 节点为例，其他服务类推，请务必添加第一列别名，以免服务混布时混淆。 - -```ini -TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy -``` - -### 调整其它变量（可选） - -> **注意：** -> -> 以下控制变量开启请使用首字母大写 `True`，关闭请使用首字母大写 `False`。 - -| 变量 | 含义 | -| :--------------- | :---------------------------------------------------------- | -| `cluster_name` | 集群名称，可调整 | -| `tidb_version` | TiDB 版本，TiDB Ansible 各分支默认已配置 | -| `process_supervision` | 进程监管方式，默认为 `systemd`，可选 `supervise` | -| `timezone` | 新安装 TiDB 集群第一次启动 bootstrap（初始化）时，将 TiDB 全局默认时区设置为该值。TiDB 使用的时区后续可通过 `time_zone` 全局变量和 session 变量来修改，参考[时区支持](/v3.1/how-to/configure/time-zone.md)。默认为 `Asia/Shanghai`，可选值参考 [timzone 列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。 | -| `enable_firewalld` | 开启防火墙，默认不开启，如需开启，请将[部署建议-网络要求](/v3.1/how-to/deploy/hardware-recommendations.md#网络要求) 中的端口加入白名单 | -| `enable_ntpd` | 检测部署目标机器 NTP 服务，默认为 `True`，请勿关闭 | -| `set_hostname` | 根据 IP 修改部署目标机器主机名，默认为 `False` | -| `enable_binlog` | 是否部署 Pump 并开启 binlog，默认为 `False`，依赖 Kafka 集群，参见 `zookeeper_addrs` 变量 | -| `zookeeper_addrs` | binlog Kafka 集群的 zookeeper 地址 | -| `deploy_without_tidb` | KV 模式，不部署 TiDB 服务，仅部署 PD、TiKV 及监控服务，请将 `inventory.ini` 文件中 `tidb_servers` 主机组的 IP 设置为空。| -| `alertmanager_target` | 可选：如果你已单独部署 alertmanager，可配置该变量，格式：`alertmanager_host:alertmanager_port` | -| `grafana_admin_user` | Grafana 管理员帐号用户名，默认为 admin | -| `grafana_admin_password` | Grafana 管理员帐号密码，默认为 admin，用于 Ansible 导入 Dashboard 和创建 API Key，如后期通过 grafana web 修改了密码，请更新此变量 | -| `collect_log_recent_hours` | 采集日志时，采集最近几个小时的日志，默认为 2 小时 | -| `enable_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时，是否限速，默认为 `True`，与 `collect_bandwidth_limit` 变量结合使用 | -| `collect_bandwidth_limit` | 在中控机上从部署目标机器拉取诊断数据时限速多少，单位: Kbit/s，默认 10000，即 10Mb/s，如果是单机多 TiKV 实例部署方式，需除以单机实例个数 | -| `prometheus_storage_retention` | Prometheus 监控数据的保留时间（默认为 30 天）；2.1.7、3.0 以及之后的 tidb-ansible 版本中，`group_vars/monitoring_servers.yml` 文件里新增的配置 | - -## 第 11 步：部署 TiDB 集群 - -`ansible-playbook` 执行 Playbook 时，默认并发为 5。部署目标机器较多时，可添加 `-f` 参数指定并发数，例如 `ansible-playbook deploy.yml -f 10`。以下示例使用 `tidb` 用户作为服务运行用户： - -1. 在 `tidb-ansible/inventory.ini` 文件中，确认 `ansible_user = tidb`。 - - ```ini - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - > **注意：** - > - > 不要将 `ansible_user` 设置为 `root` 用户，因为 `tidb-ansible` 限制了服务以普通用户运行。 - - 执行以下命令，如果所有 server 均返回 `tidb`，表示 SSH 互信配置成功： - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' - ``` - - 执行以下命令，如果所有 server 均返回 `root`，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible -i inventory.ini all -m shell -a 'whoami' -b - ``` - -2. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到中控机。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -3. 初始化系统环境，修改内核参数。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml - ``` - -4. 部署 TiDB 集群软件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml - ``` - - > **注意：** - > - > Grafana Dashboard 上的 **Report** 按钮可用来生成 PDF 文件，此功能依赖 `fontconfig` 包和英文字体。如需使用该功能，登录 **grafana_servers** 机器，用以下命令安装： - > - > {{< copyable "shell-regular" >}} - > - > ```bash - > sudo yum install fontconfig open-sans-fonts - > ``` - -5. 启动 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml - ``` - -## 测试集群 - -TiDB 兼容 MySQL，因此可使用 MySQL 客户端直接连接 TiDB。推荐配置负载均衡以提供统一的 SQL 接口。 - -1. 使用 MySQL 客户端连接 TiDB 集群。TiDB 服务的默认端口为 `4000`。 - - {{< copyable "sql" >}} - - ```sql - mysql -u root -h 172.16.10.1 -P 4000 - ``` - -2. 通过浏览器访问监控平台。 - - - 地址： - - 默认帐号与密码：`admin`；`admin` - -## 常见部署问题 - -本小节介绍使用 Ansible 部署 TiDB 集群过程中的常见问题与解决方案。 - -### 如何自定义端口 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 端口变量 | 默认端口 | 说明 | -| :-- | :-- | :-- | :-- | -| TiDB | tidb_port | 4000 | 应用及 DBA 工具访问通信端口 | -| TiDB | tidb_status_port | 10080 | TiDB 状态信息上报通信端口 | -| TiKV | tikv_port | 20160 | TiKV 通信端口 | -| TiKV | tikv_status_port | 20180 | 上报 TiKV 状态的通信端口 | -| PD | pd_client_port | 2379 | 提供 TiDB 和 PD 通信端口 | -| PD | pd_peer_port | 2380 | PD 集群节点间通信端口 | -| Pump | pump_port | 8250 | Pump 通信端口 | -| Prometheus | prometheus_port | 9090 | Prometheus 服务通信端口 | -| Pushgateway | pushgateway_port | 9091 | TiDB， TiKV， PD 监控聚合和上报端口 | -| Node_exporter | node_exporter_port | 9100 | TiDB 集群每个节点的系统信息上报通信端口 | -| Blackbox_exporter | blackbox_exporter_port | 9115 | Blackbox_exporter 通信端口，用于 TiDB 集群端口监控 | -| Grafana | grafana_port | 3000 | Web 监控服务对外服务和客户端(浏览器)访问端口 | -| Grafana | grafana_collector_port | 8686 | grafana_collector 通信端口，用于将 Dashboard 导出为 PDF 格式 | -| Kafka_exporter | kafka_exporter_port | 9308 | Kafka_exporter 通信端口，用于监控 binlog Kafka 集群 | - -### 如何自定义部署目录 - -修改 `inventory.ini` 文件，在相应服务 IP 后添加以下主机变量即可： - -| 组件 | 目录变量 | 默认目录 | 说明 | -| :-- | :-- | :-- | :-- | -| 全局 | deploy_dir | /home/tidb/deploy | 部署目录 | -| TiDB | tidb_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_log_dir | {{ deploy_dir }}/log | 日志目录 | -| TiKV | tikv_data_dir | {{ deploy_dir }}/data | 数据目录 | -| TiKV | wal_dir | "" | rocksdb write-ahead 日志目录，为空时与 TiKV 数据目录一致 | -| TiKV | raftdb_path | "" | raftdb 目录，为空时为 tikv_data_dir/raft | -| PD | pd_log_dir | {{ deploy_dir }}/log | 日志目录 | -| PD | pd_data_dir | {{ deploy_dir }}/data.pd | 数据目录 | -| pump | pump_log_dir | {{ deploy_dir }}/log | 日志目录 | -| pump | pump_data_dir | {{ deploy_dir }}/data.pump | 数据目录 | -| prometheus | prometheus_log_dir | {{ deploy_dir }}/log | 日志目录 | -| prometheus | prometheus_data_dir | {{ deploy_dir }}/data.metrics | 数据目录 | -| pushgateway | pushgateway_log_dir | {{ deploy_dir }}/log | 日志目录 | -| node_exporter | node_exporter_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_log_dir | {{ deploy_dir }}/log | 日志目录 | -| grafana | grafana_data_dir | {{ deploy_dir }}/data.grafana | 数据目录 | - -### 如何检测 NTP 服务是否正常 - -1. 执行以下命令，如果输出 `running` 表示 NTP 服务正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl status ntpd.service - ``` - - ``` - ntpd.service - Network Time Service - Loaded: loaded (/usr/lib/systemd/system/ntpd.service; disabled; vendor preset: disabled) - Active: active (running) since 一 2017-12-18 13:13:19 CST; 3s ago - ``` - -2. 执行 `ntpstat` 命令，如果输出 `synchronised to NTP server`（正在与 NTP server 同步），表示在正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - synchronised to NTP server (85.199.214.101) at stratum 2 - time correct to within 91 ms - polling server every 1024 s - ``` - -> **注意：** -> -> Ubuntu 系统需安装 `ntpstat` 软件包。 - -- 以下情况表示 NTP 服务未正常同步： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - unsynchronised - ``` - -- 以下情况表示 NTP 服务未正常运行： - - {{< copyable "shell-regular" >}} - - ```bash - ntpstat - ``` - - ``` - Unable to talk to NTP daemon. Is it running? - ``` - -- 如果要使 NTP 服务尽快开始同步，执行以下命令。可以将 `pool.ntp.org` 替换为你的 NTP server： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl stop ntpd.service && \ - sudo ntpdate pool.ntp.org && \ - sudo systemctl start ntpd.service - ``` - -- 如果要在 CentOS 7 系统上手动安装 NTP 服务，可执行以下命令： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install ntp ntpdate && \ - sudo systemctl start ntpd.service && \ - sudo systemctl enable ntpd.service - ``` - -### 如何调整进程监管方式从 supervise 到 systemd - -{{< copyable "shell-root" >}} - -```shell -process supervision, [systemd, supervise] -``` - -``` -process_supervision = systemd -``` - -TiDB Anisble 在 TiDB v1.0.4 版本之前进程监管方式默认为 `supervise`。之前安装的集群可保持不变，如需更新为 `systemd`，需关闭集群，按以下方式变更： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml && \ -ansible-playbook deploy.yml -D && \ -ansible-playbook start.yml -``` - -### 如何手工配置 SSH 互信及 sudo 免密码 - -1. 以 `root` 用户依次登录到部署目标机器创建 `tidb` 用户并设置登录密码。 - - {{< copyable "shell-root" >}} - - ```bash - useradd tidb && \ - passwd tidb - ``` - -2. 执行以下命令，将 `tidb ALL=(ALL) NOPASSWD: ALL` 添加到文件末尾，即配置好 sudo 免密码。 - - {{< copyable "shell-root" >}} - - ```bash - visudo - ``` - - ``` - tidb ALL=(ALL) NOPASSWD: ALL - ``` - -3. 以 `tidb` 用户登录到中控机，执行以下命令。将 `172.16.10.61` 替换成你的部署目标机器 IP，按提示输入部署目标机器 `tidb` 用户密码，执行成功后即创建好 SSH 互信，其他机器同理。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh-copy-id -i ~/.ssh/id_rsa.pub 172.16.10.61 - ``` - -4. 以 `tidb` 用户登录到中控机，通过 `ssh` 的方式登录目标机器 IP。如果不需要输入密码并登录成功，即表示 SSH 互信配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - ssh 172.16.10.61 - ``` - - ``` - [tidb@172.16.10.61 ~]$ - ``` - -5. 以 `tidb` 用户登录到部署目标机器后，执行以下命令，不需要输入密码并切换到 `root` 用户，表示 `tidb` 用户 sudo 免密码配置成功。 - - {{< copyable "shell-regular" >}} - - ```bash - sudo -su root - ``` - - ``` - [root@172.16.10.61 tidb]# - ``` - -### You need to install jmespath prior to running json_query filter 报错 - -1. 请参照[在中控机器上安装 Ansible 及其依赖](#在中控机器上安装-ansible-及其依赖) 在中控机上通过 `pip` 安装 Ansible 及相关依赖的指定版本，默认会安装 `jmespath`。 - -2. 执行以下命令，验证 `jmespath` 是否安装成功： - - {{< copyable "shell-regular" >}} - - ```bash - pip show jmespath - ``` - - ``` - Name: jmespath - Version: 0.9.0 - ``` - -3. 在中控机上 Python 交互窗口里 `import jmespath`。 - - - 如果没有报错，表示依赖安装成功。 - - 如果有 `ImportError: No module named jmespath` 报错，表示未成功安装 Python `jmespath` 模块。 - - {{< copyable "shell-regular" >}} - - ```bash - python - ``` - - ``` - Python 2.7.5 (default, Nov 6 2016, 00:28:07) - [GCC 4.8.5 20150623 (Red Hat 4.8.5-11)] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - ``` - - {{< copyable "shell-regular" >}} - - ```shell - import jmespath - ``` - -### 启动 Pump/Drainer 报 `zk: node does not exist` 错误 - -请检查 `inventory.ini` 里的 `zookeeper_addrs` 参数配置与 Kafka 集群内的配置是否相同、是否填写了命名空间。关于命名空间的配置说明如下： - -```ini -# ZooKeeper connection string (see ZooKeeper docs for details). -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes. Example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -``` diff --git a/v3.1/how-to/deploy/orchestrated/docker.md b/v3.1/how-to/deploy/orchestrated/docker.md deleted file mode 100644 index f3e51e18b240..000000000000 --- a/v3.1/how-to/deploy/orchestrated/docker.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: TiDB Docker 部署方案 -category: how-to ---- - -# TiDB Docker 部署方案 - -本文介绍如何使用 Docker 部署一个多节点的 TiDB 集群。 - -> **警告：** -> -> 对于生产环境，不要使用 Docker 进行部署，而应[使用 Ansible 部署 TiDB 集群](/v3.1/how-to/deploy/orchestrated/ansible.md)。 - -## 环境准备 - -### 安装 Docker - -Docker 可以方便地在 Linux / Mac OS / Windows 平台安装，安装方法请参考 [Docker 官方文档](https://www.docker.com/products/docker)。 - -### 拉取 TiDB 的 Docker 镜像 - -部署 TiDB 集群主要包括 3 个服务组件: - -- TiDB -- TiKV -- PD - -对应的最新 Docker 镜像可以通过 [Docker 官方镜像仓库](https://hub.docker.com/u/pingcap) 获取： - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/tidb:latest -``` - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/tikv:latest -``` - -{{< copyable "shell-regular" >}} - -```bash -docker pull pingcap/pd:latest -``` - -## 部署一个多节点集群 - -假设我们打算在 6 台主机上部署一个 TiDB 集群: - -| 主机名 | IP | 部署服务 | 数据盘挂载 | -| --------- | ------------- | ---------- | ----- | -| host1 | 192.168.1.101 | PD1 & TiDB | /data | -| host2 | 192.168.1.102 | PD2 | /data | -| host3 | 192.168.1.103 | PD3 | /data | -| host4 | 192.168.1.104 | TiKV1 | /data | -| host5 | 192.168.1.105 | TiKV2 | /data | -| host6 | 192.168.1.106 | TiKV3 | /data | - -### 启动 PD - -登录 **host1** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host2** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd2 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd2" \ - --data-dir="/data/pd2" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.102:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.102:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -登录 **host3** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd3 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/pd:latest \ - --name="pd3" \ - --data-dir="/data/pd3" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.103:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.103:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" -``` - -### 启动 TiKV - -登录 **host4** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host5** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv2 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.105:20160" \ - --data-dir="/data/tikv2" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -登录 **host6** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv3 \ - -p 20160:20160 \ - --ulimit nofile=1000000:1000000 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.106:20160" \ - --data-dir="/data/tikv3" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 启动 TiDB - -登录 **host1** 执行： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tidb \ - -p 4000:4000 \ - -p 10080:10080 \ - -v /etc/localtime:/etc/localtime:ro \ - pingcap/tidb:latest \ - --store=tikv \ - --path="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" -``` - -### 使用 MySQL 标准客户端连接 TiDB 测试 - -登录 **host1** 并确保已安装 [MySQL 命令行客户端](http://dev.mysql.com/downloads/mysql/)，执行： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -D test -``` - -{{< copyable "sql" >}} - -```sql -show databases; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -### 如何自定义配置文件 - -TiKV 和 PD 可以通过指定配置文件的方式来加载更加丰富的启动参数，用于性能调优。 - -假定配置文件在宿主机上的存放路径 `/path/to/config/pd.toml` 和 `/path/to/config/tikv.toml`。启动 Docker 时需要调整相应的启动参数，以 tikv1 和 pd1 为例： - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name tikv1 \ - -p 20160:20160 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/tikv.toml:/tikv.toml:ro \ - pingcap/tikv:latest \ - --addr="0.0.0.0:20160" \ - --advertise-addr="192.168.1.104:20160" \ - --data-dir="/data/tikv1" \ - --pd="192.168.1.101:2379,192.168.1.102:2379,192.168.1.103:2379" \ - --config="/tikv.toml" -``` - -{{< copyable "shell-regular" >}} - -```bash -docker run -d --name pd1 \ - -p 2379:2379 \ - -p 2380:2380 \ - -v /etc/localtime:/etc/localtime:ro \ - -v /data:/data \ - -v /path/to/config/pd.toml:/pd.toml:ro \ - pingcap/pd:latest \ - --name="pd1" \ - --data-dir="/data/pd1" \ - --client-urls="http://0.0.0.0:2379" \ - --advertise-client-urls="http://192.168.1.101:2379" \ - --peer-urls="http://0.0.0.0:2380" \ - --advertise-peer-urls="http://192.168.1.101:2380" \ - --initial-cluster="pd1=http://192.168.1.101:2380,pd2=http://192.168.1.102:2380,pd3=http://192.168.1.103:2380" \ - --config="/pd.toml" -``` diff --git a/v3.1/how-to/deploy/orchestrated/offline-ansible.md b/v3.1/how-to/deploy/orchestrated/offline-ansible.md deleted file mode 100644 index 6f7ceddf720d..000000000000 --- a/v3.1/how-to/deploy/orchestrated/offline-ansible.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: 离线 TiDB Ansible 部署方案 -category: how-to ---- - -# 离线 TiDB Ansible 部署方案 - -## 准备机器 - -1. 下载机一台 - - - 该机器需开放外网访问，用于下载 TiDB Ansible、TiDB 及相关软件安装包。 - - 推荐安装 CentOS 7.3 及以上版本 Linux 操作系统。 - -2. 部署目标机器若干及部署中控机一台 - - - 系统要求及配置参考[准备机器](/v3.1/how-to/deploy/orchestrated/ansible.md#准备机器)。 - - 可以无法访问外网。 - -## 在中控机上安装系统依赖包 - -1. 在下载机上下载[系统依赖离线安装包](https://download.pingcap.org/ansible-system-rpms.el7.tar.gz)，然后上传至中控机。该离线包仅支持 CentOS 7 系统，包含 `pip` 及 `sshpass`。 - -2. 在中控机上安装系统依赖包： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-system-rpms.el7.tar.gz && - cd ansible-system-rpms.el7 && - chmod u+x install_ansible_system_rpms.sh && - ./install_ansible_system_rpms.sh - ``` - -3. 安装完成后，可通过 `pip -V` 验证 pip 是否安装成功： - - {{< copyable "shell-root" >}} - - ```bash - pip -V - ``` - - ``` - pip 8.1.2 from /usr/lib/python2.7/site-packages (python 2.7) - ``` - -> **注意：** -> -> 如果你的系统已安装 pip，请确认版本 >= 8.1.2，否则离线安装 ansible 及其依赖时，会有兼容问题。 - -## 在中控机上创建 tidb 用户，并生成 ssh key - -参考[在中控机上创建 tidb 用户，并生成 ssh key](/v3.1/how-to/deploy/orchestrated/ansible.md#第-2-步在中控机上创建-tidb-用户并生成-ssh-key) 即可。 - -## 在中控机器上离线安装 Ansible 及其依赖 - -以下是 CentOS 7 系统 Ansible 离线安装方式： - -建议使用 Ansible 2.4 至 2.7.11 版本，Ansible 及相关依赖版本记录在 `tidb-ansible/requirements.txt` 文件中。下面步骤以安装 Ansible 2.5 为例。 - -1. 在下载机上下载 [Ansible 2.5 离线安装包](https://download.pingcap.org/ansible-2.5.0-pip.tar.gz)，然后上传至中控机。 - -2. 离线安装 Ansible 及相关依赖： - - {{< copyable "shell-root" >}} - - ```bash - tar -xzvf ansible-2.5.0-pip.tar.gz && - cd ansible-2.5.0-pip/ && - chmod u+x install_ansible.sh && - ./install_ansible.sh - ``` - -3. 安装完成后，可通过 `ansible --version` 查看版本： - - {{< copyable "shell-root" >}} - - ```bash - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -## 在下载机上下载 TiDB Ansible 及 TiDB 安装包 - -1. 在下载机上安装 Ansible： - - 请按以下方式在 CentOS 7 系统的下载机上在线安装 Ansible。安装完成后，可通过 `ansible --version` 查看版本，请务必确认是 **Ansible 2.5.0** 版本，否则会有兼容问题。 - - {{< copyable "shell-root" >}} - - ```bash - yum install epel-release && - yum install ansible curl && - ansible --version - ``` - - ``` - ansible 2.5.0 - ``` - -2. 下载 tidb-ansible： - - 使用以下命令从 [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 3.0 [相应 TAG 版本](https://github.com/pingcap/tidb-ansible/tags)，默认的文件夹名称为 `tidb-ansible`。 - - {{< copyable "shell-regular" >}} - - ```bash - git clone -b $tag https://github.com/pingcap/tidb-ansible.git - ``` - - > **注意：** - > - > - 将 `$tag` 替换为选定的 TAG 版本的值，例如 `v3.0.2`。 - > - 部署和升级 TiDB 集群需使用对应的 tidb-ansible 版本，通过改 `inventory.ini` 文件中的版本来混用可能会产生一些错误。 - -3. 执行 `local_prepare.yml` playbook，联网下载 TiDB binary 到下载机： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-ansible && - ansible-playbook local_prepare.yml - ``` - -4. 将执行完以上命令之后的 `tidb-ansible` 文件夹拷贝到中控机 `/home/tidb` 目录下，文件属主权限需是 `tidb` 用户。 - -## 在中控机上配置部署机器 SSH 互信及 sudo 规则 - -参考[在中控机上配置部署机器 SSH 互信及 sudo 规则](/v3.1/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)即可。 - -## 在部署目标机器上安装 NTP 服务 - -如果你的部署目标机器时间、时区设置一致，已开启 NTP 服务且在正常同步时间，此步骤可忽略，可参考[如何检测 NTP 服务是否正常](/v3.1/how-to/deploy/orchestrated/ansible.md#第-6-步在部署目标机器上安装-ntp-服务)。 - -参考[在部署目标机器上安装 NTP 服务](/v3.1/how-to/deploy/orchestrated/ansible.md#在部署目标机器上安装-ntp-服务)即可。 - -## 在部署目标机器上配置 CPUfreq 调节器模式 - -参考[在部署目标机器上配置 CPUfreq 调节器模式](/v3.1/how-to/deploy/orchestrated/ansible.md#第-7-步在部署目标机器上配置-cpufreq-调节器模式)即可。 - -## 在部署目标机器上添加数据盘 ext4 文件系统挂载参数 - -参考[在部署目标机器上添加数据盘 ext4 文件系统挂载参数](/v3.1/how-to/deploy/orchestrated/ansible.md#第-8-步在部署目标机器上添加数据盘-ext4-文件系统挂载参数)即可。 - -## 分配机器资源，编辑 inventory.ini 文件 - -参考[分配机器资源，编辑 inventory.ini 文件](/v3.1/how-to/deploy/orchestrated/ansible.md#第-9-步编辑-inventoryini-文件分配机器资源)即可。 - -## 部署任务 - -1. `ansible-playbook local_prepare.yml` 该 playbook 不需要再执行。 - -2. 参考[部署任务](/v3.1/how-to/deploy/orchestrated/ansible.md#第-11-步部署-tidb-集群)即可。 - -## 测试集群 - -参考[测试集群](/v3.1/how-to/deploy/orchestrated/ansible.md#测试集群)即可。 diff --git a/v3.1/how-to/get-started/data-migration.md b/v3.1/how-to/get-started/data-migration.md deleted file mode 100644 index c34ed28019e0..000000000000 --- a/v3.1/how-to/get-started/data-migration.md +++ /dev/null @@ -1,523 +0,0 @@ ---- -title: TiDB Data Migration 教程 -category: how-to ---- - -# TiDB Data Migration 教程 - -TiDB Data Migration (DM) 是一体化的数据同步任务管理平台，支持将大量、复杂的生产环境中的数据从 MySQL 或 MariaDB 迁移到 TiDB。 - -DM 功能如下： - -- 数据迁移 - - 支持导出与导入源数据库的初始全量数据，并在数据迁移过程中读取、应用来自源数据库存储的 binlog，从而保持数据的同步。 - - 通过合并上游的多个 MySQL 或 MariaDB 实例或集群的表，DM 能迁移生产环境中的分库分表。 -- 将 TiDB 作为 MySQL 或 MariaDB 的从库时，DM 能持续提高数据库水平扩展的能力，或在无需 ETL 作业的情况下，在 TiDB 上进行数据实时分析。 - -本教程主要介绍如何使用 DM 迁移上游多个 MySQL 实例的一个分片表。包括两种场景： - -- 合并若干个互不冲突的表或分片，即这些表或分片的表结构并不会造成唯一键的冲突； -- 合并唯一键存在冲突的表。 - -本教程假设目前使用的是一台新的、纯净版 CentOS 7 实例，你能（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为需要运行多个服务，建议内存最好在 1 GB 以上。 - -> **警告：** -> -> 本教程中 TiDB 的部署方法并**不适用**于生产或开发环境。 - -## Data Migration 架构 - -![TiDB Data Migration 架构](/media/dm-architecture.png) - -TiDB Data Migration 平台由 3 部分组成：DM-master、DM-worker 和 dmctl。 - -* DM-master 负责管理和调度数据同步任务的操作。 -* DM-worker 负责执行特定的数据同步任务。 -* dmctl 是一个命令行工具，用于控制 DM 集群。 - -`.yaml` 文件中定义了各个数据同步任务，dmctl 会读取这些文件，并且这些文件会被提交给 DM-master。DM-master 再将关于给定任务的相应职责告知每个 DM-worker 实例。 - -详情参见 [Data Migration 简介](/v3.1/reference/tools/data-migration/overview.md)。 - -## 安装 - -本部分介绍如何部署 3 个 MySQL Server 实例及 `pd-server`、`tikv-server` 和 `tidb-server` 实例各 1 个，以及如何启动 1 个 DM-master 和 3 个 DM-worker 实例。 - -1. 安装 MySQL 5.7，下载或提取 TiDB v3.0 以及 DM v1.0.2 安装包： - - {{< copyable "shell-regular" >}} - - ```bash - sudo yum install -y http://repo.mysql.com/yum/mysql-5.7-community/el/7/x86_64/mysql57-community-release-el7-10.noarch.rpm && - sudo yum install -y mysql-community-server && - curl https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - && - curl https://download.pingcap.org/dm-v1.0.2-linux-amd64.tar.gz | tar xzf - && - curl -L https://github.com/pingcap/docs/raw/master/dev/how-to/get-started/dm-cnf/dm-cnf.tgz | tar xvzf - - ``` - -2. 创建目录和符号链接： - - {{< copyable "shell-regular" >}} - - ```bash - mkdir -p bin data logs && - ln -sf -t bin/ "$HOME"/*/bin/* && - [[ :$PATH: = *:$HOME/bin:* ]] || echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile && . ~/.bash_profile - ``` - -3. 安装 3 个 MySQL Server 实例的配置： - - {{< copyable "shell-regular" >}} - - ```bash - tee -a "$HOME/.my.cnf" <}} - - ```bash - for i in 1 2 3 - do - echo "mysql$i" - mysqld --defaults-group-suffix="$i" --initialize-insecure - mysqld --defaults-group-suffix="$i" & - done - ``` - -5. 执行 `jobs` 和/或 `pgrep -a mysqld` 以确保 MySQL Server 实例都在运行状态。 - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running mysqld --defaults-group-suffix="$i" & - [2]- Running mysqld --defaults-group-suffix="$i" & - [3]+ Running mysqld --defaults-group-suffix="$i" & - ``` - - {{< copyable "shell-regular" >}} - - ```bash - pgrep -a mysqld - ``` - - ``` - 17672 mysqld --defaults-group-suffix=1 - 17727 mysqld --defaults-group-suffix=2 - 17782 mysqld --defaults-group-suffix=3 - ``` - -## 同步分片数据 - -本示例场景包含 3 个分片，这些分片表结构相同，但自增主键并不重叠。 - -在 `.my.cnf` 文件中设置 `auto-increment-increment=5` 和 `auto-increment-offset` 可以实现这种情况。将 `auto-increment-increment` 设置为 5，则这些实例的自增 ID 以 5 为单位递增；每个实例的 `auto-increment-offset` 都设置得不同，则这些实例的偏移为 0 到开始计数的值。例如，若一个实例的 `auto-increment-increment` 为 5，`auto-increment-offset` 为 2，则会生成自增 ID 序列 {2,7,12,17,22,…}。 - -1. 对于这 3 个 MySQL Server 实例，每个实例都分别创建数据库和表： - - {{< copyable "shell-regular" >}} - - ```bash - for i in 1 2 3 - do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root <}} - - ```bash - for i in 1 2 3; do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root dmtest1 <}} - - ```bash - for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select * from dmtest1.t1' - done | sort -n - ``` - -注意返回的列表左侧是一列递增的、无重叠的 ID，右侧的端口编号显示这些数据插入到哪些实例以及从哪些实例中查询： - -``` -... -1841 e8dfff4676a47048d6f0c4ef899593dd 3307 -1842 57c0531e13f40b91b3b0f1a30b529a1d 3308 -1843 4888241374e8c62ddd9b4c3cfd091f96 3309 -1846 f45a1078feb35de77d26b3f7a52ef502 3307 -1847 82cadb0649a3af4968404c9f6031b233 3308 -1848 7385db9a3f11415bc0e9e2625fae3734 3309 -1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 -1852 eb1e78328c46506b46a4ac4a1e378b91 3308 -1853 7503cfacd12053d309b6bed5c89de212 3309 -1856 3c947bc2f7ff007b86a9428b74654de5 3307 -1857 a3545bd79d31f9a72d3a78690adf73fc 3308 -1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 -``` - -### 启动 DM-master 和 DM-worker - -本小节介绍如何使用 DM 将来自不同的 MySQL 实例的数据合并到 TiDB 的一张表里。 - -配置文件包 `dm-cnf.tgz` 包含： - -- TiDB 集群组件和 DM 组件的配置 -- 本教程后文介绍的 2 个 DM 任务的配置 - -1. 启动单个 `tidb-server` 实例、每个 MySQL Server 实例 （总共 3 个实例）的 DM-worker 进程和一个 DM-master 进程： - - {{< copyable "shell-regular" >}} - - ```bash - tidb-server --log-file=logs/tidb-server.log & - for i in 1 2 3; do dm-worker --config=dm-cnf/dm-worker$i.toml & done - dm-master --config=dm-cnf/dm-master.toml & - ``` - -2. 执行 `jobs` 和/或 `ps -a`，确保这些进程都正在运行： - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running mysqld --defaults-group-suffix="$i" & - [2] Running mysqld --defaults-group-suffix="$i" & - [3] Running mysqld --defaults-group-suffix="$i" & - [4] Running tidb-server --log-file=logs/tidb-server.log & - [5] Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [6] Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [7]- Running dm-worker --config=dm-cnf/dm-worker$i.toml & - [8]+ Running dm-master --config=dm-cnf/dm-master.toml & - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ps -a - ``` - - ``` - PID TTY TIME CMD - 17317 pts/0 00:00:00 screen - 17672 pts/1 00:00:04 mysqld - 17727 pts/1 00:00:04 mysqld - 17782 pts/1 00:00:04 mysqld - 18586 pts/1 00:00:02 tidb-server - 18587 pts/1 00:00:00 dm-worker - 18588 pts/1 00:00:00 dm-worker - 18589 pts/1 00:00:00 dm-worker - 18590 pts/1 00:00:00 dm-master - 18892 pts/1 00:00:00 ps - ``` - -每个上游的 MySQL Server 实例对应一个单独的 DM-worker 实例，每个 DM-worker 实例都有各自的配置文件。这些文件内容包括： - -- 连接到上游 MySQL Server 的详细信息 -- relay log（上游服务器的 binlog）的存储路径 -- mydumper 的输出 - -各个 DM-worker 通过不同的端口监听（由 `worker-addr` 定义）。 - -以下为 `dm-worker1.toml` 的示例： - -{{< copyable "" >}} - -```toml -# DM-worker 配置 - -server-id = 1 -source-id = "mysql1" -flavor = "mysql" -worker-addr = ":8262" -log-file = "logs/worker1.log" -relay-dir = "data/relay1" -meta-dir = "data/meta1" -dir = "data/dump1" - -[from] -host = "127.0.0.1" -user = "root" -password = "" -port = 3307 -``` - -- 如果从 MySQL Server、Percona Server、Percona XtraDB Cluster、Amazon Aurora 或 RDS 迁移数据，则 `flavor` 配置项应设为 "mysql"（默认值，支持 5.5 < MySQL 版本 < 8.0）。 -- 如果从 MariaDB Server 或 MariaDB (Galera) Cluster 迁移数据，则设置 `flavor = "mariadb"`（仅支持 10.1.2 以上 MariaDB 版本）。 -- 从 DM 1.0.2 版本开始，`flavor`、`server-id` 项均会由 DM 自动生成，一般情况下不需要手动配置。 -- `from` 中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见[使用 dmctl 加密上游 MySQL 用户密码](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -任务在 YAML 文件中定义。以下为一个 `dmtask1.yaml` 文件示例： - -{{< copyable "" >}} - -```yaml -name: dmtask1 -task-mode: all -is-sharding: true -enable-heartbeat: true -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - source-id: "mysql1" - server-id: 1 - black-white-list: "dmtest1" - loader-config-name: "loader1" - - source-id: "mysql2" - server-id: 2 - black-white-list: "dmtest1" - loader-config-name: "loader2" - - source-id: "mysql3" - server-id: 3 - black-white-list: "dmtest1" - loader-config-name: "loader3" - -black-white-list: - dmtest1: - do-dbs: ["dmtest1"] - -loaders: - loader1: - dir: "data/dump1" - loader2: - dir: "data/dump2" - loader3: - dir: "data/dump3" -``` - -以上文件包含一些全局配置项和几组定义各种行为的配置项。 - -* `task-mode: all`：DM 导入上游实例的全量备份，并使用上游 MySQL Server 的 binlog 进行增量同步。 - - * 此外，可将 `task-mode` 设置为 `full` 或 `incremental` 以分别进行全量备份或增量同步。 - -* `is-sharding: true`：多个 DM-worker 实例进行同一个任务，这些实例将上游的若干分片合并到一个下游的表中。 - -* `ignore-checking-items: ["auto_increment_ID"]`：关闭 DM 对上游实例中潜在的自增 ID 冲突的检测。DM 能检测出上游表结构相同、并包含自增列的分片间潜在的列值冲突。通过配置 `auto-increment-increment` 和 `auto-increment-offset` 可使每个 MySQL Server 的 ID 都不重叠，从而避免不同表之间冲突的产生。因此，可以让 DM 关闭对自增 ID 冲突的检测。 - -* `black-white-list`：将一个任务限制在数据库 `dmtest` 中。 - -* `loaders`：定义由各个 DM-worker 实例执行的每个 mydumper 实例的输出地址。 - -* `target-database`：定义目标数据库的链接信息，其中的 `password` 如果不为空，则需要使用 dmctl 进行加密，参见 [使用 dmctl 加密上游 MySQL 用户密码](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -`dmctl` 是控制 DM 集群的命令行工具，用于启动任务、查询任务状态。执行 `dmctl -master-addr :8261` 获取如下交互提示，从而启动该工具： - -{{< copyable "shell-regular" >}} - -```bash -dmctl -master-addr :8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.0-alpha-69-g5134ad1 -Git Commit Hash: 5134ad19fbf6c57da0c7af548f5ca2a890bddbe4 -Git Branch: master -UTC Build Time: 2019-04-29 09:36:42 -Go Version: go version go1.12 linux/amd64 - -» -``` - -执行 `start-task dm-cnf/dmtask1.yaml` 启动 `dmtask1`： - -{{< copyable "shell-regular" >}} - -```bash -start-task dm-cnf/dmtask1.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - }, - { - "result": true, - "worker": "127.0.0.1:8264", - "msg": "" - } - ] -} -``` - -启动该任务意味着启动任务配置文件中定义的行为，包括执行 mydumper 和 loader 实例，加载初次 dump 的数据后，将 DM-worker 作为同步任务的 slave 连接到上游的 MySQL Server。 - -所有的行数据都被迁移到 TiDB Server： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -... -1843 4888241374e8c62ddd9b4c3cfd091f96 3309 -1846 f45a1078feb35de77d26b3f7a52ef502 3307 -1847 82cadb0649a3af4968404c9f6031b233 3308 -1848 7385db9a3f11415bc0e9e2625fae3734 3309 -1851 ff1418e8cc993fe8abcfe3ce2003e5c5 3307 -1852 eb1e78328c46506b46a4ac4a1e378b91 3308 -1853 7503cfacd12053d309b6bed5c89de212 3309 -1856 3c947bc2f7ff007b86a9428b74654de5 3307 -1857 a3545bd79d31f9a72d3a78690adf73fc 3308 -1858 d7fd118e6f226a71b5f1ffe10efd0a78 3309 -``` - -现在 DM 正作为每个 MySQL Server 的 slave，读取 MySQL Server 的 binlog，将更新的数据实时同步到下游的 TiDB Server： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3 -do - mysql -h 127.0.0.1 -P "$((3306+i))" -u root -e 'select host, command, state from information_schema.processlist where command="Binlog Dump"' -done -``` - -输出结果： - -``` -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:42168 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:42922 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -+-----------------+-------------+---------------------------------------------------------------+ -| host | command | state | -+-----------------+-------------+---------------------------------------------------------------+ -| localhost:56798 | Binlog Dump | Master has sent all binlog to slave; waiting for more updates | -+-----------------+-------------+---------------------------------------------------------------+ -``` - -向上游 MySQL Server 插入几行数据，更新 MySQL 中的这些行，并再次查询这些行： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'insert into t1 (id) select null from t1' dmtest1 -done -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -6313 NULL NULL -6316 NULL NULL -6317 NULL NULL -6318 NULL NULL -6321 NULL NULL -6322 NULL NULL -6323 NULL NULL -6326 NULL NULL -6327 NULL NULL -6328 NULL NULL -``` - -更新这些行，则可见更新的数据已同步到 TiDB 中： - -{{< copyable "shell-regular" >}} - -```bash -for i in 1 2 3; do - mysql -N -h 127.0.0.1 -P "$((3306+i))" -u root -e 'update t1 set c=md5(id), port=@@port' dmtest1 -done | sort -n -mysql -h 127.0.0.1 -P 4000 -u root -e 'select * from t1' dmtest1 | tail -``` - -输出结果： - -``` -6313 2118d8a1b7004ed5baf5347a4f99f502 3309 -6316 6107d91fc9a0b04bc044aa7d8c1443bd 3307 -6317 0e9b734aa25ca8096cb7b56dc0dd8929 3308 -6318 b0eb9a95e8b085e4025eae2f0d76a6a6 3309 -6321 7cb36e23529e4de4c41460940cc85e6e 3307 -6322 fe1f9c70bdf347497e1a01b6c486bdb9 3308 -6323 14eac0d254a6ccaf9b67584c7830a5c0 3309 -6326 17b65afe58c49edc1bdd812c554ee3bb 3307 -6327 c54bc2ded4480856dc9f39bdcf35a3e7 3308 -6328 b294504229c668e750dfcc4ea9617f0a 3309 -``` - -只要 DM-master 和 DM-worker 运行 `dmtest1` 任务，下游的 TiDB Server 将持续和上游的 MySQL Server 实例保持同步的状态。 - -## 结论 - -本教程完成了上游 3 个 MySQL Server 实例的分片迁移，介绍了分片迁移中，DM 如何在集群中导入初始数据，以及如何读取 MySQL 的 binlog 来同步增量数据，从而使下游 TiDB 集群与上游实例保持同步。 - -关于 DM 的更多详情，请参考 [Data Migration 简介](/v3.1/reference/tools/data-migration/overview.md)，或加入 [TiDB Community Slack](https://pingcap.com/tidbslack/) channel 参与讨论。 diff --git a/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md b/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md deleted file mode 100644 index 399e4556ce5a..000000000000 --- a/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: 使用 Docker Compose 快速构建 TiDB 集群 -category: how-to ---- - -# 使用 Docker Compose 快速构建 TiDB 集群 - -本文档介绍如何在单机上通过 Docker Compose 快速一键部署一套 TiDB 测试集群。[Docker Compose](https://docs.docker.com/compose/overview) 可以通过一个 YAML 文件定义多个容器的应用服务，然后一键启动或停止。 - -> **警告：** -> -> 对于生产环境，不要使用 Docker Compose 进行部署，而应[使用 Ansible 部署 TiDB 集群](/v3.1/how-to/deploy/orchestrated/ansible.md)。 - -## 准备环境 - -确保你的机器上已安装： - -- Docker（17.06.0 及以上版本） -- Docker Compose -- Git - -## 快速部署 - -1. 下载 `tidb-docker-compose` - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -2. 创建并启动集群 - - 获取最新 Docker 镜像： - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-docker-compose && docker-compose pull && docker-compose up -d - ``` - -3. 访问集群 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - [集群数据可视化](https://github.com/pingcap/tidb-vision)： - -## 自定义集群 - -在完成快速部署后，以下组件已默认部署：3 个 PD，3 个 TiKV，1 个 TiDB 和监控组件 Prometheus，Pushgateway，Grafana 以及 tidb-vision。 - -如果想自定义集群，可以直接修改 `docker-compose.yml`，但是手动修改比较繁琐而且容易出错，强烈建议使用 [Helm](https://helm.sh) 模板引擎生成 `docker-compose.yml` 文件。 - -1. 安装 Helm - - [Helm](https://helm.sh) 可以用作模板渲染引擎，只需要下载其 binary 文件即可以使用。 - - {{< copyable "shell-regular" >}} - - ```bash - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果是 Mac 系统，也可以通过 Homebrew 安装： - - {{< copyable "shell-regular" >}} - - ```bash - brew install kubernetes-helm - ``` - -2. 下载 `tidb-docker-compose` - - {{< copyable "shell-regular" >}} - - ```bash - git clone https://github.com/pingcap/tidb-docker-compose.git - ``` - -3. 自定义集群 - - {{< copyable "shell-regular" >}} - - ```bash - cd tidb-docker-compose && - cp compose/values.yaml values.yaml && - vim values.yaml - ``` - - 修改 `values.yaml` 里面的配置，例如集群规模，TiDB 镜像版本等。 - - [tidb-vision](https://github.com/pingcap/tidb-vision) 是 TiDB 集群可视化页面，可以可视化地显示 PD 对 TiKV 数据的调度。如果不想部署该组件，可以将 `tidbVision` 项留空。 - - PD，TiKV，TiDB 和 tidb-vision 支持从 GitHub 源码或本地文件构建 Docker 镜像，供开发测试使用。 - - - 如果希望从本地已编译好的 binary 文件构建 PD，TiKV 或 TiDB 镜像，需要将其 `image` 字段留空，并将已编译好的 binary 拷贝到对应的 `pd/bin/pd-server`，`tikv/bin/tikv-server`，`tidb/bin/tidb-server`。 - - - 如果希望从本地构建 tidb-vision 镜像，需要将其 `image` 字段留空，并将 tidb-vision 项目拷贝到 `tidb-vision/tidb-vision`。 - -4. 生成 `docker-compose.yml` 文件 - - {{< copyable "shell-regular" >}} - - ```bash - helm template -f values.yaml compose > generated-docker-compose.yml - ``` - -5. 使用生成的 `docker-compose.yml` 创建并启动集群 - - 获取最新 Docker 镜像： - - {{< copyable "shell-regular" >}} - - ```bash - docker-compose -f generated-docker-compose.yml pull - ``` - - {{< copyable "shell-regular" >}} - - ```bash - docker-compose -f generated-docker-compose.yml up -d - ``` - -6. 访问集群 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - - 访问集群 Grafana 监控页面： 默认用户名和密码均为 admin。 - - 如果启用了 tidb-vision，可以通过 查看。 - -## 访问 Spark shell 并加载 TiSpark - -向 TiDB 集群中插入一些样本数据： - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master bash && -cd /opt/spark/data/tispark-sample-data && -mysql -h tidb -P 4000 -u root < dss.ddl -``` - -当样本数据加载到 TiDB 集群之后，可以使用 `docker-compose exec tispark-master /opt/spark/bin/spark-shell` 来访问 Spark shell。 - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master /opt/spark/bin/spark-shell -``` - -``` -... -Spark context available as 'sc' (master = local[*], app id = local-1527045927617). -Spark session available as 'spark'. -Welcome to - ____ __ - / __/__ ___ _____/ /__ - _\ \/ _ \/ _ `/ __/ '_/ - /___/ .__/\_,_/_/ /_/\_\ version 2.1.1 - /_/ - -Using Scala version 2.11.8 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_172) -Type in expressions to have them evaluated. -Type :help for more information. -``` - -```shell -scala> import org.apache.spark.sql.TiContext -... -scala> val ti = new TiContext(spark) -... -scala> ti.tidbMapDatabase("TPCH_001") -... -scala> spark.sql("select count(*) from lineitem").show -``` - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -你也可以通过 Python 或 R 来访问 Spark： - -{{< copyable "shell-regular" >}} - -```bash -docker-compose exec tispark-master /opt/spark/bin/pyspark && -docker-compose exec tispark-master /opt/spark/bin/sparkR -``` - -更多关于 TiSpark 的信息，参见 [TiSpark 的详细文档](/v3.1/how-to/get-started/tispark.md)。 diff --git a/v3.1/how-to/get-started/explore-sql.md b/v3.1/how-to/get-started/explore-sql.md deleted file mode 100644 index 3ad1c469cc9c..000000000000 --- a/v3.1/how-to/get-started/explore-sql.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: TiDB 中的基本 SQL 操作 -category: how-to ---- - -# TiDB 中的基本 SQL 操作 - -成功部署 TiDB 集群之后，便可以在 TiDB 中执行 SQL 语句了。因为 TiDB 兼容 MySQL，你可以使用 MySQL 客户端连接 TiDB，并且[大多数情况下](/v3.1/reference/mysql-compatibility.md)可以直接执行 MySQL 语句。 - -本文介绍 CRUD 操作等基本的 SQL 语句。完整的 SQL 语句列表，参见 [TiDB SQL 语法详解](https://pingcap.github.io/sqlgram/)。 - -## 创建、查看和删除数据库 - -使用 `CREATE DATABASE` 语句创建数据库。语法如下： - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE db_name [options]; -``` - -例如，要创建一个名为 `samp_db` 的数据库，可使用以下语句： - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE IF NOT EXISTS samp_db; -``` - -使用 `SHOW DATABASES` 语句查看数据库： - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -使用 `DROP DATABASE` 语句删除数据库，例如： - -{{< copyable "sql" >}} - -```sql -DROP DATABASE samp_db; -``` - -## 创建、查看和删除表 - -使用 `CREATE TABLE` 语句创建表。语法如下： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE table_name column_name data_type constraint; -``` - -例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - number INT(11), - name VARCHAR(255), - birthday DATE - ); -``` - -如果表已存在，添加 `IF NOT EXISTS` 可防止发生错误： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE IF NOT EXISTS person ( - number INT(11), - name VARCHAR(255), - birthday DATE -); -``` - -使用 `SHOW CREATE` 语句查看建表语句。例如： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE table person; -``` - -使用 `SHOW FULL COLUMNS` 语句查看表的列。 例如： - -{{< copyable "sql" >}} - -```sql -SHOW FULL COLUMNS FROM person; -``` - -使用 `DROP TABLE` 语句删除表。例如： - -{{< copyable "sql" >}} - -```sql -DROP TABLE person; -``` - -或者 - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS person; -``` - -使用 `SHOW TABLES` 语句查看数据库中的所有表。例如： - -{{< copyable "sql" >}} - -```sql -SHOW TABLES FROM samp_db; -``` - -## 创建、查看和删除索引 - -对于值不唯一的列，可使用 `CREATE INDEX` 或 `ALTER TABLE` 语句。例如： - -{{< copyable "sql" >}} - -```sql -CREATE INDEX person_num ON person (number); -``` - -或者 - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person ADD INDEX person_num (number); -``` - -对于值唯一的列，可以创建唯一索引。例如： - -{{< copyable "sql" >}} - -```sql -CREATE UNIQUE INDEX person_num ON person (number); -``` - -或者 - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person ADD UNIQUE person_num (number); -``` - -使用 `SHOW INDEX` 语句查看表内所有索引： - -{{< copyable "sql" >}} - -```sql -SHOW INDEX from person; -``` - -使用 `ALTER TABLE` 或 `DROP INDEX` 语句来删除索引。与 `CREATE INDEX` 语句类似，`DROP INDEX` 也可以嵌入 `ALTER TABLE` 语句。例如： - -{{< copyable "sql" >}} - -```sql -DROP INDEX person_num ON person; -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE person DROP INDEX person_num; -``` - -## 增删改查数据 - -使用 `INSERT` 语句向表内插入数据。例如： - -{{< copyable "sql" >}} - -```sql -INSERT INTO person VALUES("1","tom","20170912"); -``` - -使用 `SELECT` 语句检索表内数据。例如： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-09-12 | -+--------+------+------------+ -``` - -使用 `UPDATE` 语句修改表内数据。例如： - -{{< copyable "sql" >}} - -```sql -UPDATE person SET birthday='20171010' WHERE name='tom'; -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -+--------+------+------------+ -| number | name | birthday | -+--------+------+------------+ -| 1 | tom | 2017-10-10 | -+--------+------+------------+ -``` - -使用 `DELETE` 语句删除表内数据： - -{{< copyable "sql" >}} - -```sql -DELETE FROM person WHERE number=1; -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM person; -``` - -``` -Empty set (0.00 sec) -``` - -## 创建、授权和删除用户 - -使用 `CREATE USER` 语句创建一个用户 `tiuser`，密码为 `123456`： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456'; -``` - -授权用户 `tiuser` 可检索数据库 `samp_db` 内的表： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost'; -``` - -查询用户 `tiuser` 的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS for tiuser@localhost; -``` - -删除用户 `tiuser`： - -{{< copyable "sql" >}} - -```sql -DROP USER 'tiuser'@'localhost'; -``` diff --git a/v3.1/how-to/get-started/read-historical-data.md b/v3.1/how-to/get-started/read-historical-data.md deleted file mode 100644 index d5063930da84..000000000000 --- a/v3.1/how-to/get-started/read-historical-data.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: 读取历史数据 -category: how-to ---- - -# 读取历史数据 - -本文档介绍 TiDB 如何读取历史版本数据，包括具体的操作流程以及历史数据的保存策略。 - -## 功能说明 - -TiDB 实现了通过标准 SQL 接口读取历史数据功能，无需特殊的 client 或者 driver。当数据被更新、删除后，依然可以通过 SQL 接口将更新/删除前的数据读取出来。 - -另外即使在更新数据之后，表结构发生了变化，TiDB 依旧能用旧的表结构将数据读取出来。 - -## 操作流程 - -为支持读取历史版本数据， 引入了一个新的 system variable: tidb_snapshot ，这个变量是 Session 范围有效，可以通过标准的 Set 语句修改其值。其值为文本，能够存储 TSO 和日期时间。TSO 即是全局授时的时间戳，是从 PD 端获取的; 日期时间的格式可以为： -“2016-10-08 16:45:26.999”，一般来说可以只写到秒，比如”2016-10-08 16:45:26”。 -当这个变量被设置时，TiDB 会用这个时间戳建立 Snapshot（没有开销，只是创建数据结构），随后所有的 Select 操作都会在这个 Snapshot 上读取数据。 - -> **注意：** -> -> TiDB 的事务是通过 PD 进行全局授时，所以存储的数据版本也是以 PD 所授时间戳作为版本号。在生成 Snapshot 时，是以 tidb_snapshot 变量的值作为版本号，如果 TiDB Server 所在机器和 PD Server 所在机器的本地时间相差较大，需要以 PD 的时间为准。 - -当读取历史版本操作结束后，可以结束当前 Session 或者是通过 Set 语句将 tidb_snapshot 变量的值设为 ""，即可读取最新版本的数据。 - -## 历史数据保留策略 - -TiDB 使用 MVCC 管理版本，当更新/删除数据时，不会做真正的数据删除，只会添加一个新版本数据，所以可以保留历史数据。历史数据不会全部保留，超过一定时间的历史数据会被彻底删除，以减小空间占用以及避免历史版本过多引入的性能开销。 - -TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理，关于 GC 的详细介绍参见 [TiDB 垃圾回收 (GC)](/v3.1/reference/garbage-collection/overview.md)。 - -这里需要重点关注的是 `tikv_gc_life_time` 和 `tikv_gc_safe_point` 这条。`tikv_gc_life_time` 用于配置历史版本保留时间，可以手动修改；`tikv_gc_safe_point` 记录了当前的 safePoint，用户可以安全地使用大于 safePoint 的时间戳创建 snapshot 读取历史版本。safePoint 在每次 GC 开始运行时自动更新。 - -## 示例 - -1. 初始化阶段，创建一个表，并插入几行数据： - - {{< copyable "sql" >}} - - ```sql - create table t (c int); - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - insert into t values (1), (2), (3); - ``` - - ``` - Query OK, 3 rows affected (0.00 sec) - ``` - -2. 查看表中的数据： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -3. 查看当前时间： - - {{< copyable "sql" >}} - - ```sql - select now(); - ``` - - ``` - +---------------------+ - | now() | - +---------------------+ - | 2016-10-08 16:45:26 | - +---------------------+ - 1 row in set (0.00 sec) - ``` - -4. 更新某一行数据： - - {{< copyable "sql" >}} - - ```sql - update t set c=22 where c=2; - ``` - - ``` - Query OK, 1 row affected (0.00 sec) - ``` - -5. 确认数据已经被更新： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -6. 设置一个特殊的环境变量，这个是一个 session scope 的变量，其意义为读取这个时间之前的最新的一个版本。 - - {{< copyable "sql" >}} - - ```sql - set @@tidb_snapshot="2016-10-08 16:45:26"; - ``` - - ``` - Query OK, 0 rows affected (0.00 sec) - ``` - - > **注意：** - > - > - 这里的时间设置的是 update 语句之前的那个时间。 - > - 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 - - 这里读取到的内容即为 update 之前的内容，也就是历史版本： - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 2 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - -7. 清空这个变量后，即可读取最新版本数据： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_snapshot=""; - ``` - - ``` - Query OK, 0 rows affected (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t; - ``` - - ``` - +------+ - | c | - +------+ - | 1 | - | 22 | - | 3 | - +------+ - 3 rows in set (0.00 sec) - ``` - - > **注意：** - > - > 在 `tidb_snapshot` 前须使用 `@@` 而非 `@`，因为 `@@` 表示系统变量，`@` 表示用户变量。 diff --git a/v3.1/how-to/get-started/tidb-binlog.md b/v3.1/how-to/get-started/tidb-binlog.md deleted file mode 100644 index c7ecf23d9a97..000000000000 --- a/v3.1/how-to/get-started/tidb-binlog.md +++ /dev/null @@ -1,520 +0,0 @@ ---- -title: TiDB Binlog 教程 -category: how-to ---- - -# TiDB Binlog 教程 - -本文档主要介绍如何使用 TiDB Binlog 将数据从 TiDB 推送到 MariaDB 实例。文中的 TiDB Binlog 集群包含 Pump 和 Drainer 的单个节点，TiDB 集群包含 TiDB、TiKV 和 Placement Driver (PD) 各组件的单个节点。 - -希望上手实践 TiDB Binlog 工具的用户需要对 [TiDB 架构](/v3.1/architecture.md)有一定的了解，最好有创建过 TiDB 集群的经验。该文档也有助于简单快速了解 TiDB Binlog 架构以及相关概念。 - -> **警告：** -> -> 该文档中部署 TiDB 的操作指导**不适用于**在生产或研发环境中部署 TiDB 的情况。 - -该文档假设用户使用的是现代 Linux 发行版本中的 x86-64。示例中使用的是 VMware 中运行的 CentOS 7 最小化安装。建议在一开始就进行清洁安装，以避免受现有环境中未知情况的影响。如果不想使用本地虚拟环境，也可以使用云服务启动 CentOS 7 VM。 - -## TiDB Binlog 简介 - -TiDB Binlog 用于收集 TiDB 中二进制日志数据、提供实时数据备份和同步以及将 TiDB 集群的数据增量同步到下游。 - -TiDB Binlog 支持以下功能场景： - -- 增量备份，将 TiDB 集群中的数据增量同步到另一个集群，或通过 Kafka 增量同步到选择的下游。 -- 当使用 TiDB DM (Data Migration) 将数据从上游 MySQL 或者 MariaDB 迁移到 TiDB 集群时，可使用 TiDB Binlog 保持 TiDB 集群与其一个独立下游 MySQL 或 MariaDB 实例或集群同步。当 TiDB 集群上游数据迁移过程中出现问题，下游数据同步过程中可使用 TiDB Binlog 恢复数据到原先的状态。 - -更多信息参考 [TiDB Binlog Cluster 版本用户文档](/v3.1/reference/tidb-binlog/overview.md)。 - -## 架构 - -TiDB Binlog 集群由 **Pump** 和 **Drainer** 两个组件组成。一个 Pump 集群中有若干个 Pump 节点。TiDB 实例连接到各个 Pump 节点并发送 binlog 数据到 Pump 节点。Pump 集群连接到 Drainer 节点，Drainer 将接收到的更新数据转换到某个特定下游（例如 Kafka、另一个 TiDB 集群或 MySQL 或 MariaDB Server）指定的正确格式。 - -![TiDB Binlog architecture](/media/tidb_binlog_cluster_architecture.png) - -Pump 的集群架构能确保 TiDB 或 Pump 集群中有新的实例加入或退出时更新数据不会丢失。 - -## 安装 - -由于 RHEL/CentOS 7 的默认包装库中包括 MariaDB Server，本示例选择的是 MariaDB Server。后续除了安装服务器，也需要安装客户端。安装指令如下： - -{{< copyable "shell-regular" >}} - -```bash -sudo yum install -y mariadb-server -``` - -预期输出： - -{{< copyable "shell-regular" >}} - -```bash -curl -LO https://download.pingcap.org/tidb-v3.0-linux-amd64.tar.gz | tar xzf - && -cd tidb-v3.0-linux-amd64/ -``` - -``` - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 279M 100 279M 0 0 4983k 0 0:00:57 0:00:57 --:--:-- 3638k -``` - -## 配置 - -通过执行以下步骤配置一个 TiDB 集群，该集群包括 `pd-server`、`tikv-server` 和 `tidb-server` 各组件的单个实例。 - -1. 填充配置文件： - - {{< copyable "shell-regular" >}} - - ```bash - printf > pd.toml %s\\n 'log-file="pd.log"' 'data-dir="pd.data"' && - printf > tikv.toml %s\\n 'log-file="tikv.log"' '[storage]' 'data-dir="tikv.data"' '[pd]' 'endpoints=["127.0.0.1:2379"]' '[rocksdb]' max-open-files=1024 '[raftdb]' max-open-files=1024 && - printf > pump.toml %s\\n 'log-file="pump.log"' 'data-dir="pump.data"' 'addr="127.0.0.1:8250"' 'advertise-addr="127.0.0.1:8250"' 'pd-urls="http://127.0.0.1:2379"' && - printf > tidb.toml %s\\n 'store="tikv"' 'path="127.0.0.1:2379"' '[log.file]' 'filename="tidb.log"' '[binlog]' 'enable=true' && - printf > drainer.toml %s\\n 'log-file="drainer.log"' '[syncer]' 'db-type="mysql"' '[syncer.to]' 'host="127.0.0.1"' 'user="root"' 'password=""' 'port=3306' - ``` - -2. 查看配置细节： - - {{< copyable "shell-regular" >}} - - ```bash - for f in *.toml; do echo "$f:"; cat "$f"; echo; done - ``` - - 预期输出： - - ``` - drainer.toml: - log-file="drainer.log" - [syncer] - db-type="mysql" - [syncer.to] - host="127.0.0.1" - user="root" - password="" - port=3306 - - pd.toml: - log-file="pd.log" - data-dir="pd.data" - - pump.toml: - log-file="pump.log" - data-dir="pump.data" - addr="127.0.0.1:8250" - advertise-addr="127.0.0.1:8250" - pd-urls="http://127.0.0.1:2379" - - tidb.toml: - store="tikv" - path="127.0.0.1:2379" - [log.file] - filename="tidb.log" - [binlog] - enable=true - - tikv.toml: - log-file="tikv.log" - [storage] - data-dir="tikv.data" - [pd] - endpoints=["127.0.0.1:2379"] - [rocksdb] - max-open-files=1024 - [raftdb] - max-open-files=1024 - ``` - -## 启动程序 - -现在可启动各个组件。推荐启动顺序依次为 Placement Driver (PD)、TiKV、Pump（TiDB 发送 binlog 日志必须连接 Pump 服务）、TiDB。 - -1. 启动所有服务： - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pd-server --config=pd.toml &>pd.out & - ``` - - ``` - [1] 20935 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/tikv-server --config=tikv.toml &>tikv.out & - ``` - - ``` - [2] 20944 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump --config=pump.toml &>pump.out & - ``` - - ``` - [3] 21050 - ``` - - {{< copyable "shell-regular" >}} - - ```bash - sleep 3 && - ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - ``` - [4] 21058 - ``` - -2. 如果执行 `jobs`，可以看到后台正在运行的程序，列表如下： - - {{< copyable "shell-regular" >}} - - ```bash - jobs - ``` - - ``` - [1] Running ./bin/pd-server --config=pd.toml &>pd.out & - [2] Running ./bin/tikv-server --config=tikv.toml &>tikv.out & - [3]- Running ./bin/pump --config=pump.toml &>pump.out & - [4]+ Running ./bin/tidb-server --config=tidb.toml &>tidb.out & - ``` - - 如果有服务启动失败（例如出现 “`Exit 1`” 而不是 “`Running`”），尝试重启单个组件。 - -## 连接 - -按以上步骤操作后，TiDB 的 4 个组件开始运行。接下来可以使用以下 MariaDB 或 MySQL 命令行客户端，通过 4000 端口连接到 TiDB 服务： - -{{< copyable "shell-regular" >}} - -```bash -mysql -h 127.0.0.1 -P 4000 -u root -e 'select tidb_version();' -``` - -预期输出： - -``` -*************************** 1. row *************************** -tidb_version(): Release Version: v3.0.0 -Git Commit Hash: 60965b006877ca7234adaced7890d7b029ed1306 -Git Branch: HEAD -UTC Build Time: 2019-06-28 12:14:07 -GoVersion: go version go1.12 linux/amd64 -Race Enabled: false -TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e -Check Table Before Drop: false -``` - -连接后TiDB 集群已开始运行，`pump` 读取集群中的 binlog 数据，并在其数据目录中将 binlog 数据存储为 relay log。下一步是启动一个可供 `drainer` 写入的 MariaDB Server。 - -1. 启动 `drainer`： - - {{< copyable "shell-regular" >}} - - ```bash - sudo systemctl start mariadb && - ./bin/drainer --config=drainer.toml &>drainer.out & - ``` - - 如果你的操作系统更易于安装 MySQL，只需保证监听 3306 端口。另外，可使用密码为空的 "root" 用户连接到 MySQL，或调整 `drainer.toml` 连接到 MySQL。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 3306 -u root - ``` - - 预期输出： - - ``` - Welcome to the MariaDB monitor. Commands end with ; or \g. - Your MariaDB connection id is 20 - Server version: 5.5.60-MariaDB MariaDB Server - - Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - MariaDB [(none)]> - ``` - - {{< copyable "sql" >}} - - ```sql - show databases; - ``` - - 预期输出： - - ``` - +--------------------+ - | Database | - +--------------------+ - | information_schema | - | mysql | - | performance_schema | - | test | - | tidb_binlog | - +--------------------+ - 5 rows in set (0.01 sec) - ``` - - 如下表格是包含 `checkpoint` 表格的 `tidb_binlog` 数据库。`drainer` 使用 `checkpoint` 表格，记录 TiDB 集群中的 binlog 已经更新到了哪个位置。 - - {{< copyable "sql" >}} - - ```sql - use tidb_binlog; - ``` - - ``` - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - select * from checkpoint; - ``` - - ``` - +---------------------+---------------------------------------------+ - | clusterID | checkPoint | - +---------------------+---------------------------------------------+ - | 6678715361817107733 | {"commitTS":407637466476445697,"ts-map":{}} | - +---------------------+---------------------------------------------+ - 1 row in set (0.00 sec) - ``` - - 打开另一个连接到 TiDB 的客户端，创建一个表格并插入几行数据。建议在 GNU Screen 软件中操作，从而同时打开多个客户端。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 --prompt='TiDB [\d]> ' -u root - ``` - - {{< copyable "sql" >}} - - ```sql - create database tidbtest; - ``` - - ``` - Query OK, 0 rows affected (0.12 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - use tidbtest; - ``` - - ``` - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - create table t1 (id int unsigned not null AUTO_INCREMENT primary key); - ``` - - ``` - Query OK, 0 rows affected (0.11 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - insert into t1 () values (),(),(),(),(); - ``` - - ``` - Query OK, 5 rows affected (0.01 sec) - Records: 5 Duplicates: 0 Warnings: 0 - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t1; - ``` - - ``` - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 切换回 MariaDB 客户端可看到新的数据库、新的表格和最近插入的行数据。 - - {{< copyable "sql" >}} - - ```sql - use tidbtest; - ``` - - ``` - Reading table information for completion of table and column names - You can turn off this feature to get a quicker startup with -A - - Database changed - ``` - - {{< copyable "sql" >}} - - ```sql - show tables; - ``` - - ``` - +--------------------+ - | Tables_in_tidbtest | - +--------------------+ - | t1 | - +--------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - select * from t1; - ``` - - ``` - +----+ - | id | - +----+ - | 1 | - | 2 | - | 3 | - | 4 | - | 5 | - +----+ - 5 rows in set (0.00 sec) - ``` - - 可看到查询 MariaDB 时插入到 TiDB 相同的行数据，表明 TiDB Binlog 安装成功。 - -## binlogctl - -加入到集群的 Pump 和 Drainer 的数据存储在 Placement Driver (PD) 中。binlogctl 可用于查询和修改状态信息。更多信息请参考 [binlogctl guide](/v3.1/reference/tidb-binlog/maintain.md#binlogctl-工具)。 - -使用 `binlogctl` 查看集群中 Pump 和 Drainer 的当前状态： - -{{< copyable "shell-regular" >}} - -```bash -./bin/binlogctl -cmd drainers -``` - -``` -[2019/04/11 17:44:10.861 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: online, MaxCommitTS: 407638907719778305, UpdateTime: 2019-04-11 17:44:10 -0400 EDT}"] -``` - -{{< copyable "shell-regular" >}} - -```bash -./bin/binlogctl -cmd pumps -``` - -``` -[2019/04/11 17:44:13.904 -04:00] [INFO] [nodes.go:47] ["query node"] [type=pump] [node="{NodeID: localhost.localdomain:8250, Addr: 192.168.236.128:8250, State: online, MaxCommitTS: 407638914024079361, UpdateTime: 2019-04-11 17:44:13 -0400 EDT}"] -``` - -如果结束 Drainer 进程，集群会改进程设置“已暂停（即集群等待 Drainer 重新加入）”的状态。 - -{{< copyable "shell-regular" >}} - -```bash -pkill drainer && -./bin/binlogctl -cmd drainers -``` - -预期输出： - -``` -[2019/04/11 17:44:22.640 -04:00] [INFO] [nodes.go:47] ["query node"] [type=drainer] [node="{NodeID: localhost.localdomain:8249, Addr: 192.168.236.128:8249, State: paused, MaxCommitTS: 407638915597467649, UpdateTime: 2019-04-11 17:44:18 -0400 EDT}"] -``` - -使用 binlogctl 的 "NodeIDs" 可控制单个对应节点。在该情况下，Drainer 的节点 ID 是 "localhost.localdomain:8249"，Pump 的节点 ID 是 "localhost.localdomain:8250"。 - -本文档中的 binlogctl 主要用于集群重启。如果在 TiDB 集群中终止并尝试重启所有的进程，由于 Pump 无法连接 Drainer 且认为 Drainer 依旧“在线”，Pump 会拒绝启动。这里的进程并不包括下游的 MySQL 或 MariaDB 或 Drainer。 - -以下有三个方案可解决上述问题： - -- 使用 binlogctl 停止 Drainer，而不是结束进程： - - ```bash - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=drainers && - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=pause-drainer --node-id=localhost.localdomain:8249 - ``` - -- 在启动 Pump **之前**先启动 Drainer。 - -- 在启动 PD 之后但在启动 Drainer 和 Pump 之前，使用 binlogctl 更新已暂定 Drainer 的状态。 - - ```bash - ./bin/binlogctl --pd-urls=http://127.0.0.1:2379 --cmd=update-drainer --node-id=localhost.localdomain:8249 --state=paused - ``` - -## 清理 - -在 shell 终端里可启动创建集群的所有进程（`pd-server` 、`tikv-server`、`pump`、`tidb-server`、`drainer`）。可通过在 shell 终端中执行 `pkill -P $$` 停止 TiDB 集群服务和 TiDB Binlog 进程。按一定的顺序停止这些进程有利于留出足够的时间彻底关闭每个组件。 - -{{< copyable "shell-regular" >}} - -```bash -for p in tidb-server drainer pump tikv-server pd-server; do pkill "$p"; sleep 1; done -``` - -预期输出： - -``` -[4]- Done ./bin/tidb-server --config=tidb.toml &>tidb.out -[5]+ Done ./bin/drainer --config=drainer.toml &>drainer.out -[3]+ Done ./bin/pump --config=pump.toml &>pump.out -[2]+ Done ./bin/tikv-server --config=tikv.toml &>tikv.out -[1]+ Done ./bin/pd-server --config=pd.toml &>pd.out -``` - -如果需要所有服务退出后重启集群，可以使用一开始启动服务的命令。如以上 [`binlogctl`](#binlogctl) 部分所述，需要先启动 Drainer 再启动 Pump，最后启动 `tidb-server`。 - -{{< copyable "shell-regular" >}} - -```bash -./bin/pd-server --config=pd.toml &>pd.out & -./bin/tikv-server --config=tikv.toml &>tikv.out & -./bin/drainer --config=drainer.toml &>drainer.out & -sleep 3 -./bin/pump --config=pump.toml &>pump.out & -sleep 3 -./bin/tidb-server --config=tidb.toml &>tidb.out & -``` - -如果有组件启动失败，请尝试单独重启该组件。 - -## 总结 - -本文档介绍了如何通过设置 TiDB Binlog，使用单个 Pump 和 Drainer 组成的集群同步 TiDB 集群数据到下游的 MariaDB。可以发现，TiDB Binlog 是用于获取处理 TiDB 集群中更新数据的综合性平台工具。 - -在更稳健的开发、测试或生产部署环境中，可以使用多个 TiDB 服务以实现高可用性和扩展性。使用多个 Pump 实例可以避免 Pump 集群中的问题影响发送到 TiDB 实例的应用流量。或者可以使用增加的 Drainer 实例同步数据到不同的下游或实现数据增量备份。 diff --git a/v3.1/how-to/get-started/tidb-lightning.md b/v3.1/how-to/get-started/tidb-lightning.md deleted file mode 100644 index 11b0b0bd1f07..000000000000 --- a/v3.1/how-to/get-started/tidb-lightning.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: TiDB Lightning 教程 -category: how-to ---- - -# TiDB Lightning 教程 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -TiDB Lightning 主要包含两个部分: - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键/值对 (KV 对) 发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，把 `tidb-lightning` 写入的 KV 对缓存、排序、切分并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -本教程假设使用的是若干新的、纯净版 CentOS 7 实例，你可以（使用 VMware、VirtualBox 及其他工具）在本地虚拟化或在供应商提供的平台上部署一台小型的云虚拟主机。因为 TiDB Lightning 对计算机资源消耗较高，建议分配 4 GB 以上的内存。 - -> **警告：** -> -> 本教程中的部署方法只适用于测试及功能体验，并不适用于生产或开发环境。 - -## 准备全量备份数据 - -我们使用 [`mydumper`](/v3.1/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -这样全量备份数据就导出到了 `/data/my_database` 目录中。 - -## 部署 TiDB Lightning - -### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群（版本要求 2.0.9 以上），本教程使用 TiDB 3.0.4 版本。部署方法可参考 [TiDB 快速入门指南](/v3.1/overview.md#部署方式)。 - -### 第 2 步：下载 TiDB Lightning 安装包 - -通过以下链接获取 TiDB Lightning 安装包（选择与 TiDB 集群相同的版本）： - -- **v3.0.4**: [tidb-toolkit-v3.0.4-linux-amd64.tar.gz](https://download.pingcap.org/tidb-toolkit-v3.0.0-linux-amd64.tar.gz) - -### 第 3 步：启动 `tikv-importer` - -1. 将安装包里的 `bin/tikv-importer` 上传至部署 TiDB Lightning 的服务器。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -### 第 4 步：启动 `tidb-lightning` - -1. 将安装包里的 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl` 上传至部署 TiDB Lightning 的服务器。 - -2. 将数据源也上传到同样的服务器。 - -3. 配置合适的参数运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning \ - --importer 172.16.31.10:8287 \ - -d /data/my_database/ \ - --tidb-server 172.16.31.2 \ - --tidb-user root \ - --log-file tidb-lightning.log \ - > nohup.out & - ``` - -### 第 5 步：检查数据 - -导入完毕后，TiDB Lightning 会自动退出。若导入成功，日志的最后一行会显示 `tidb lightning exit`。 - -如果出错，请参见 [TiDB Lightning 错误排解](/v3.1/how-to/troubleshoot/tidb-lightning.md)。 - -## 总结 - -本教程对 TiDB Lightning 进行了简单的介绍，并快速部署了一套简单的 TiDB Lightning 集群，将全量备份数据导入到 TiDB 集群中。 - -关于 TiDB Lightning 的详细功能和使用，参见 [TiDB Lightning 简介](/v3.1/reference/tools/tidb-lightning/overview.md)。 diff --git a/v3.1/how-to/get-started/tispark.md b/v3.1/how-to/get-started/tispark.md deleted file mode 100644 index d225e6e657d8..000000000000 --- a/v3.1/how-to/get-started/tispark.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: TiSpark 快速入门指南 -category: how-to ---- - -# TiSpark 快速入门指南 - -为了让大家快速体验 [TiSpark](/v3.1/reference/tispark.md)，通过 TiDB Ansible 安装的 TiDB 集群中默认已集成 Spark、TiSpark jar 包及 TiSpark sample data。 - -## 部署信息 - -- Spark 默认部署在 TiDB 实例部署目录下 spark 目录中 -- TiSpark jar 包默认部署在 Spark 部署目录 jars 文件夹下：`spark/jars/tispark-${name_with_version}.jar` -- TiSpark sample data 及导入脚本默认部署在 TiDB Ansible 目录下：`tidb-ansible/resources/bin/tispark-sample-data` - -## 环境准备 - -### 在 TiDB 实例上安装 JDK - -在 [Oracle JDK 官方下载页面](http://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html) 下载 JDK 1.8 当前最新版，本示例中下载的版本为 `jdk-8u141-linux-x64.tar.gz`。 - -解压并根据您的 JDK 部署目录设置环境变量，编辑 `~/.bashrc` 文件，比如： - -{{< copyable "shell-regular" >}} - -```bash -export JAVA_HOME=/home/pingcap/jdk1.8.0_144 && -export PATH=$JAVA_HOME/bin:$PATH -``` - -验证 JDK 有效性： - -```bash -java -version -``` - -``` -java version "1.8.0_144" -Java(TM) SE Runtime Environment (build 1.8.0_144-b01) -Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode) -``` - -### 导入样例数据 - -假设 TiDB 集群已启动，其中一台 TiDB 实例服务 IP 为 192.168.0.2，端口为 4000，用户名为 root, 密码为空。 - -{{< copyable "shell-regular" >}} - -```bash -cd tidb-ansible/resources/bin/tispark-sample-data -``` - -修改 `sample_data.sh` 中 TiDB 登录信息，比如： - -{{< copyable "shell-regular" >}} - -```bash -mysql --local-infile=1 -h 192.168.0.2 -P 4000 -u root < dss.ddl -``` - -执行脚本 - -{{< copyable "shell-regular" >}} - -```bash -./sample_data.sh -``` - -> **注意：** -> -> 执行脚本的机器上需要安装 MySQL client，CentOS 用户可通过 `yum -y install mysql`来安装。 - -登录 TiDB 并验证数据包含 `TPCH_001` 库及以下表： - -{{< copyable "shell-regular" >}} - -```bash -mysql -uroot -P4000 -h192.168.0.2 -``` - -{{< copyable "sql" >}} - -```sql -show databases; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| TPCH_001 | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -use TPCH_001; -``` - -``` -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -``` - -{{< copyable "sql" >}} - -```sql -show tables; -``` - -``` -+--------------------+ -| Tables_in_TPCH_001 | -+--------------------+ -| CUSTOMER | -| LINEITEM | -| NATION | -| ORDERS | -| PART | -| PARTSUPP | -| REGION | -| SUPPLIER | -+--------------------+ -8 rows in set (0.00 sec) -``` - -## 使用范例 - -进入 spark 部署目录启动 spark-shell: - -{{< copyable "shell-regular" >}} - -```bash -cd spark && -bin/spark-shell -``` - -然后像使用原生 Spark 一样查询 TiDB 表： - -```shell -scala> spark.sql("select count(*) from lineitem").show -``` - -结果为 - -``` -+--------+ -|count(1)| -+--------+ -| 60175| -+--------+ -``` - -下面执行另一个复杂一点的 Spark SQL: - -```shell -scala> spark.sql( - """select - | l_returnflag, - | l_linestatus, - | sum(l_quantity) as sum_qty, - | sum(l_extendedprice) as sum_base_price, - | sum(l_extendedprice * (1 - l_discount)) as sum_disc_price, - | sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge, - | avg(l_quantity) as avg_qty, - | avg(l_extendedprice) as avg_price, - | avg(l_discount) as avg_disc, - | count(*) as count_order - |from - | lineitem - |where - | l_shipdate <= date '1998-12-01' - interval '90' day - |group by - | l_returnflag, - | l_linestatus - |order by - | l_returnflag, - | l_linestatus - """.stripMargin).show -``` - -结果为： - -``` -+------------+------------+---------+--------------+--------------+ -|l_returnflag|l_linestatus| sum_qty|sum_base_price|sum_disc_price| -+------------+------------+---------+--------------+--------------+ -| A| F|380456.00| 532348211.65|505822441.4861| -| N| F| 8971.00| 12384801.37| 11798257.2080| -| N| O|742802.00| 1041502841.45|989737518.6346| -| R| F|381449.00| 534594445.35|507996454.4067| -+------------+------------+---------+--------------+--------------+ -(续) ------------------+---------+------------+--------+-----------+ - sum_charge| avg_qty| avg_price|avg_disc|count_order| ------------------+---------+------------+--------+-----------+ - 526165934.000839|25.575155|35785.709307|0.050081| 14876| - 12282485.056933|25.778736|35588.509684|0.047759| 348| -1029418531.523350|25.454988|35691.129209|0.049931| 29181| - 528524219.358903|25.597168|35874.006533|0.049828| 14902| ------------------+---------+------------+--------+-----------+ -``` - -更多样例请参考 [`pingcap/tispark-test`](https://github.com/pingcap/tispark-test/tree/master/tpch/sparksql) diff --git a/v3.1/how-to/maintain/ansible-operations.md b/v3.1/how-to/maintain/ansible-operations.md deleted file mode 100644 index 6e79a18ab33c..000000000000 --- a/v3.1/how-to/maintain/ansible-operations.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: TiDB Ansible 常见运维操作 -category: how-to ---- - -# TiDB Ansible 常见运维操作 - -## 启动集群 - -此操作会按顺序启动整个 TiDB 集群所有组件（包括 PD、TiDB、TiKV 等组件和监控组件）。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook start.yml -``` - -## 关闭集群 - -此操作会按顺序关闭整个 TiDB 集群所有组件（包括 PD、TiDB、TiKV 等组件和监控组件）。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -## 清除集群数据 - -此操作会关闭 TiDB、Pump、TiKV、PD 服务，并清空 Pump、TiKV、PD 数据目录。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook unsafe_cleanup_data.yml -``` - -## 销毁集群 - -此操作会关闭集群，并清空部署目录，若部署目录为挂载点，会报错，可忽略。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook unsafe_cleanup.yml -``` diff --git a/v3.1/how-to/maintain/backup-and-restore/mydumper-lightning.md b/v3.1/how-to/maintain/backup-and-restore/mydumper-lightning.md deleted file mode 100644 index 6fb911b3c1fc..000000000000 --- a/v3.1/how-to/maintain/backup-and-restore/mydumper-lightning.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: 使用 Mydumper/TiDB Lightning 进行备份与恢复 -category: how-to -aliases: ['/docs-cn/v3.1/how-to/maintain/backup-and-restore/'] ---- - -# 使用 Mydumper/TiDB Lightning 进行备份与恢复 - -本文档将详细介绍如何使用 Mydumper/TiDB Lightning 对 TiDB 进行全量备份与恢复。增量备份与恢复可使用 [TiDB Binlog](/v3.1/reference/tidb-binlog/overview.md)。 - -这里假定 TiDB 服务信息如下： - -|Name|Address|Port|User|Password| -|----|-------|----|----|--------| -|TiDB|127.0.0.1|4000|root|*| - -在这个备份恢复过程中，会用到下面的工具： - -- [Mydumper](/v3.1/reference/tools/mydumper.md) 从 TiDB 导出数据 -- [TiDB Lightning](/v3.1/reference/tools/tidb-lightning/overview.md) 导入数据到 TiDB - -## 使用 Mydumper/TiDB Lightning 全量备份恢复数据 - -`mydumper` 是一个强大的数据备份工具，具体可以参考 [`maxbube/mydumper`](https://github.com/maxbube/mydumper)。 - -可使用 [Mydumper](/v3.1/reference/tools/mydumper.md) 从 TiDB 导出数据进行备份，然后用 [TiDB Lightning](/v3.1/reference/tools/tidb-lightning/overview.md) 将其导入到 TiDB 里面进行恢复。 - -> **注意：** -> -> PingCAP 研发团队对 `mydumper` 进行了针对 TiDB 的适配性改造，建议使用 PingCAP 官方提供的 [Mydumper](/v3.1/reference/tools/mydumper.md)。由于使用 `mysqldump` 进行数据备份和恢复都要耗费许多时间，这里也并不推荐。 - -### Mydumper/TiDB Lightning 全量备份恢复最佳实践 - -为了快速地备份恢复数据 (特别是数据量巨大的库)，可以参考以下建议： - -* 导出来的数据文件应当尽可能的小，可以通过设置参数 `-F` 来控制导出来的文件大小。如果后续使用 TiDB Lightning 对备份文件进行恢复，建议把 `mydumper` -F 参数的值设置为 `256`（单位 MB）；如果使用 `loader` 恢复，则建议设置为 `64`（单位 MB）。 - -## 从 TiDB 备份数据 - -我们使用 `mydumper` 从 TiDB 备份数据，如下: - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -P 4000 -u root -t 32 -F 256 -B test -T t1,t2 --skip-tz-utc -o ./var/test -``` - -上面，我们使用 `-B test` 表明是对 `test` 这个 database 操作，然后用 `-T t1,t2` 表明只导出 `t1`，`t2` 两张表。 - -`-t 32` 表明使用 32 个线程去导出数据。`-F 256` 是将实际的表切分成一定大小的 chunk，这里的 chunk 大小为 256MB。 - -添加 `--skip-tz-utc` 参数后，会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果 `mydumper` 出现以下报错： - -``` -** (mydumper:27528): CRITICAL **: 13:25:09.081: Could not read data from testSchema.testTable: GC life time is shorter than transaction duration, transaction starts at 2019-08-05 21:10:01.451 +0800 CST, GC safe point is 2019-08-05 21:14:53.801 +0800 CST -``` - -就再执行两步命令： - -1. 执行 `mydumper` 命令前，查询 TiDB 集群的 [GC](/v3.1/reference/garbage-collection/overview.md) 值并使用 MySQL 客户端将其调整为合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 执行 `mydumper` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -## 向 TiDB 恢复数据 - -使用 TiDB Lightning 将之前导出的数据导入到 TiDB，完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) diff --git a/v3.1/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md b/v3.1/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md deleted file mode 100644 index b300d0381e6a..000000000000 --- a/v3.1/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: 定位消耗系统资源多的查询 -category: how-to ---- - -# 定位消耗系统资源多的查询 - -TiDB 会将执行时间超过 [tidb_expensive_query_time_threshold](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_expensive_query_time_threshold)（默认值为 60s），或使用内存超过 [mem-quota-query](/v3.1/reference/configuration/tidb-server/configuration-file.md#mem-quota-query)（默认值为 32 GB）的语句输出到 [tidb-server 日志文件](/v3.1/reference/configuration/tidb-server/configuration-file.md#logfile)（默认文件为：“tidb.log”）中，用于在语句执行结束前定位消耗系统资源多的查询语句（以下简称为 expensive query），帮助用户分析和解决语句执行的性能问题。 - -注意，expensive query 日志和[慢查询日志](/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)的区别是，慢查询日志是在语句执行完后才打印，expensive query 日志可以将正在执行的语句的相关信息打印出来。当一条语句在执行过程中达到资源使用阈值时（执行时间/使用内存量），TiDB 会即时将这条语句的相关信息写入日志。 - -## Expensive query 日志示例 - -```sql -[2020/02/05 15:32:25.096 +08:00] [WARN] [expensivequery.go:167] [expensive_query] [cost_time=60.008338935s] [wait_time=0s] [request_count=1] [total_keys=70] [process_keys=65] [num_cop_tasks=1] [process_avg_time=0s] [process_p90_time=0s] [process_max_time=0s] [process_max_addr=10.0.1.9:20160] [wait_avg_time=0.002s] [wait_p90_time=0.002s] [wait_max_time=0.002s] [wait_max_addr=10.0.1.9:20160] [stats=t:pseudo] [conn_id=60026] [user=root] [database=test] [table_ids="[122]"] [txn_start_ts=414420273735139329] [mem_max="1035 Bytes (1.0107421875 KB)"] [sql="insert into t select sleep(1) from t"] -``` - -## 字段含义说明 - -基本字段： - -* `cost_time`：日志打印时语句已经花费的执行时间。 -* `stats`：语句涉及到的表或索引使用的统计信息版本。值为 pesudo 时表示无可用统计信息，需要对表或索引进行 analyze。 -* `table_ids`：语句涉及到的表的 ID。 -* `txn_start_ts`：事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `sql`：SQL 语句。 - -和内存使用相关的字段： - -* `mem_max`：日志打印时语句已经使用的内存空间。该项使用两种单位标识内存使用量，分别为 Bytes 以及易于阅读的自适应单位（比如 MB、GB 等）。 - -和 SQL 执行的用户相关的字段： - -* `user`：执行语句的用户名。 -* `conn_id`：用户的连接 ID，可以用类似 `con:60026` 的关键字在 TiDB 日志中查找该连接相关的其他日志。 -* `database`：执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `wait_time`：该语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `request_count`：该语句发送的 Coprocessor 请求的数量。 -* `total_keys`：Coprocessor 扫过的 key 的数量。 -* `processed_keys`：Coprocessor 处理的 key 的数量。与 total_keys 相比，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `num_cop_tasks`：该语句发送的 Coprocessor 请求的数量。 -* `process_avg_time`：Coprocessor 执行 task 的平均执行时间。 -* `process_p90_time`：Coprocessor 执行 task 的 P90 分位执行时间。 -* `process_max_time`：Coprocessor 执行 task 的最长执行时间。 -* `process_max_addr`：task 执行时间最长的 Coprocessor 所在地址。 -* `wait_avg_time`：Coprocessor 上 task 的等待时间。 -* `wait_p90_time`：Coprocessor 上 task 的 P90 分位等待时间。 -* `wait_max_time`：Coprocessor 上 task 的最长等待时间。 -* `wait_max_addr`：task 等待时间最长的 Coprocessor 所在地址。 diff --git a/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md b/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md deleted file mode 100644 index 0d015f1580cd..000000000000 --- a/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: 慢查询日志 -category: how-to -aliases: ['/docs-cn/v3.1/how-to/maintain/identify-slow-queries/'] ---- - -# 慢查询日志 - -TiDB 会将执行时间超过 [slow-threshold](/v3.1/reference/configuration/tidb-server/configuration-file.md#slow-threshold)（默认值为 300 毫秒）的语句输出到 [slow-query-file](/v3.1/reference/configuration/tidb-server/configuration-file.md#slow-query-file)（默认值："tidb-slow.log"）日志文件中，用于帮助用户定位慢查询语句，分析和解决 SQL 执行的性能问题。 - -## 日志示例 - -```sql -# Time: 2019-08-14T09:26:59.487776265+08:00 -# Txn_start_ts: 410450924122144769 -# User: root@127.0.0.1 -# Conn_ID: 3086 -# Query_time: 1.527627037 -# Parse_time: 0.000054933 -# Compile_time: 0.000129729 -# Process_time: 0.07 Request_count: 1 Total_keys: 131073 Process_keys: 131072 Prewrite_time: 0.335415029 Commit_time: 0.032175429 Get_commit_ts_time: 0.000177098 Local_latch_wait_time: 0.106869448 Write_keys: 131072 Write_size: 3538944 Prewrite_region: 1 -# DB: test -# Is_internal: false -# Digest: 50a2e32d2abbd6c1764b1b7f2058d428ef2712b029282b776beb9506a365c0f1 -# Stats: t:pseudo -# Num_cop_tasks: 1 -# Cop_proc_avg: 0.07 Cop_proc_p90: 0.07 Cop_proc_max: 0.07 Cop_proc_addr: 172.16.5.87:20171 -# Cop_wait_avg: 0 Cop_wait_p90: 0 Cop_wait_max: 0 Cop_wait_addr: 172.16.5.87:20171 -# Mem_max: 525211 -# Succ: true -# Plan: tidb_decode_plan('ZJAwCTMyXzcJMAkyMAlkYXRhOlRhYmxlU2Nhbl82CjEJMTBfNgkxAR0AdAEY1Dp0LCByYW5nZTpbLWluZiwraW5mXSwga2VlcCBvcmRlcjpmYWxzZSwgc3RhdHM6cHNldWRvCg==') -insert into t select * from t; -``` - -## 字段含义说明 - -> **注意：** -> -> 慢查询日志中所有时间相关字段的单位都是 **“秒”** - -Slow Query 基础信息： - -* `Time`：表示日志打印时间。 -* `Query_time`：表示执行这个语句花费的时间。 -* `Parse_time`：表示这个语句在语法解析阶段花费的时间。 -* `Compile_time`：表示这个语句在查询优化阶段花费的时间。 -* `Query`：表示 SQL 语句。慢日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 -* `Digest`：表示 SQL 语句的指纹。 -* `Txn_start_ts`：表示事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 -* `Is_internal`：表示是否为 TiDB 内部的 SQL 语句。`true` 表示 TiDB 系统内部执行的 SQL 语句，`false` 表示用户执行的 SQL 语句。 -* `Index_ids`：表示语句涉及到的索引的 ID。 -* `Succ`：表示语句是否执行成功。 -* `Backoff_time`：表示语句遇到需要重试的错误时在重试前等待的时间，常见的需要重试的错误有以下几种：遇到了 lock、Region 分裂、`tikv server is busy`。 -* `Plan`：表示语句的执行计划，用 `select tidb_decode_plan('xxx...')` SQL 语句可以解析出具体的执行计划。 - -和事务执行相关的字段： - -* `Prewrite_time`：表示事务两阶段提交中第一阶段（prewrite 阶段）的耗时。 -* `Commit_time`：表示事务两阶段提交中第二阶段（commit 阶段）的耗时。 -* `Get_commit_ts_time`：表示事务两阶段提交中第二阶段（commit 阶段）获取 commit 时间戳的耗时。 -* `Local_latch_wait_time`：表示事务两阶段提交中第二阶段（commit 阶段）发起前在 TiDB 侧等锁的耗时。 -* `Write_keys`：表示该事务向 TiKV 的 Write CF 写入 Key 的数量。 -* `Write_size`：表示事务提交时写 key 或 value 的总大小。 -* `Prewrite_region`：表示事务两阶段提交中第一阶段（prewrite 阶段）涉及的 TiKV Region 数量。每个 Region 会触发一次远程过程调用。 - -和内存使用相关的字段： - -* `Memory_max`：表示执行期间 TiDB 使用的最大内存空间，单位为 byte。 - -和 SQL 执行的用户相关的字段： - -* `User`：表示执行语句的用户名。 -* `Conn_ID`：表示用户的链接 ID，可以用类似 `con:3` 的关键字在 TiDB 日志中查找该链接相关的其他日志。 -* `DB`：表示执行语句时使用的 database。 - -和 TiKV Coprocessor Task 相关的字段： - -* `Request_count`：表示这个语句发送的 Coprocessor 请求的数量。 -* `Total_keys`：表示 Coprocessor 扫过的 key 的数量。 -* `Process_time`：执行 SQL 在 TiKV 的处理时间之和，因为数据会并行的发到 TiKV 执行，这个值可能会超过 `Query_time`。 -* `Wait_time`：表示这个语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。 -* `Process_keys`：表示 Coprocessor 处理的 key 的数量。相比 total_keys，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。 -* `Cop_proc_avg`：cop-task 的平均执行时间。 -* `Cop_proc_p90`：cop-task 的 P90 分位执行时间。 -* `Cop_proc_max`：cop-task 的最大执行时间。 -* `Cop_proc_addr`：执行时间最长的 cop-task 所在地址。 -* `Cop_wait_avg`：cop-task 的平均等待时间。 -* `Cop_wait_p90`：cop-task 的 P90 分位等待时间。 -* `Cop_wait_max`：cop-task 的最大等待时间。 -* `Cop_wait_addr`：等待时间最长的 cop-task 所在地址。 - -## 慢日志内存映射表 - -用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢日志中字段名一一对应，表结构可查看 [Information Schema](/v3.1/reference/system-databases/information-schema.md#information-schema) 中关于 `SLOW_QUERY` 表的介绍。 - -> **注意：** -> -> 每次查询 `SLOW_QUERY` 表时，TiDB 都会去读取和解析一次当前的慢查询日志。 - -## 查询 `SLOW_QUERY` 示例 - -### 搜索 Top N 的慢查询 - -查询 Top 2 的用户慢查询。`is_internal=false` 表示排除 TiDB 内部的慢查询，只看用户的慢查询： - -{{< copyable "sql" >}} - -```sql -select query_time, query -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+--------------+------------------------------------------------------------------+ -| query_time | query | -+--------------+------------------------------------------------------------------+ -| 12.77583857 | select * from t_slim, t_wide where t_slim.c0=t_wide.c0; | -| 0.734982725 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c0; | -+--------------+------------------------------------------------------------------+ -``` - -### 搜索某个用户的 Top N 慢查询 - -下面例子中搜索 test 用户执行的慢查询 SQL，且按执行消耗时间逆序排序显式前 2 条： - -{{< copyable "sql" >}} - -```sql -select query_time, query, user -from information_schema.slow_query -where is_internal = false -- 排除 TiDB 内部的慢查询 SQL - and user = "test" -- 查找的用户名 -order by query_time desc -limit 2; -``` - -输出样例： - -``` -+-------------+------------------------------------------------------------------+----------------+ -| Query_time | query | user | -+-------------+------------------------------------------------------------------+----------------+ -| 0.676408014 | select t0.c0, t1.c1 from t_slim t0, t_wide t1 where t0.c0=t1.c1; | test | -+-------------+------------------------------------------------------------------+----------------+ -``` - -### 根据 SQL 指纹搜索同类慢查询 - -在得到 Top N 的慢查询 SQL 后，可通过 SQL 指纹继续搜索同类慢查询 SQL。 - -先获取 Top N 的慢查询和对应的 SQL 指纹： - -{{< copyable "sql" >}} - -```sql -select query_time, query, digest -from information_schema.slow_query -where is_internal = false -order by query_time desc -limit 1; -``` - -输出样例： - -``` -+-------------+-----------------------------+------------------------------------------------------------------+ -| query_time | query | digest | -+-------------+-----------------------------+------------------------------------------------------------------+ -| 0.302558006 | select * from t1 where a=1; | 4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa | -+-------------+-----------------------------+------------------------------------------------------------------+ -``` - -再根据 SQL 指纹搜索同类慢查询： - -{{< copyable "sql" >}} - -```sql -select query, query_time -from information_schema.slow_query -where digest = "4751cb6008fda383e22dacb601fde85425dc8f8cf669338d55d944bafb46a6fa"; -``` - -输出样例： - -``` -+-----------------------------+-------------+ -| query | query_time | -+-----------------------------+-------------+ -| select * from t1 where a=1; | 0.302558006 | -| select * from t1 where a=2; | 0.401313532 | -+-----------------------------+-------------+ -``` - -### 搜索统计信息为 pseudo 的慢查询 SQL 语句 - -{{< copyable "sql" >}} - -```sql -select query, query_time, stats -from information_schema.slow_query -where is_internal = false - and stats like '%pseudo%'; -``` - -输出样例： - -``` -+-----------------------------+-------------+---------------------------------+ -| query | query_time | stats | -+-----------------------------+-------------+---------------------------------+ -| select * from t1 where a=1; | 0.302558006 | t1:pseudo | -| select * from t1 where a=2; | 0.401313532 | t1:pseudo | -| select * from t1 where a>2; | 0.602011247 | t1:pseudo | -| select * from t1 where a>3; | 0.50077719 | t1:pseudo | -| select * from t1 join t2; | 0.931260518 | t1:407872303825682445,t2:pseudo | -+-----------------------------+-------------+---------------------------------+ -``` - -## 解析其他的 TiDB 慢日志文件 - -TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHEMA.SLOW_QUERY` 时要读取和解析的文件，可通过修改改 session 变量的值来查询其他慢查询日志文件的内容： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_query_file = "/path-to-log/tidb-slow.log" -``` - -## 用 `pt-query-digest` 工具分析 TiDB 慢日志 - -可以用 `pt-query-digest` 工具分析 TiDB 慢日志。 - -> **注意：** -> -> 建议使用 pt-query-digest 3.0.13 及以上版本。 - -示例如下： - -{{< copyable "shell" >}} - -```shell -pt-query-digest --report tidb-slow.log -``` - -输出样例： - -``` -# 320ms user time, 20ms system time, 27.00M rss, 221.32M vsz -# Current date: Mon Mar 18 13:18:51 2019 -# Hostname: localhost.localdomain -# Files: tidb-slow.log -# Overall: 1.02k total, 21 unique, 0 QPS, 0x concurrency _________________ -# Time range: 2019-03-18-12:22:16 to 2019-03-18-13:08:52 -# Attribute total min max avg 95% stddev median -# ============ ======= ======= ======= ======= ======= ======= ======= -# Exec time 218s 10ms 13s 213ms 30ms 1s 19ms -# Query size 175.37k 9 2.01k 175.89 158.58 122.36 158.58 -# Commit time 46ms 2ms 7ms 3ms 7ms 1ms 3ms -# Conn ID 71 1 16 8.88 15.25 4.06 9.83 -# Process keys 581.87k 2 103.15k 596.43 400.73 3.91k 400.73 -# Process time 31s 1ms 10s 32ms 19ms 334ms 16ms -# Request coun 1.97k 1 10 2.02 1.96 0.33 1.96 -# Total keys 636.43k 2 103.16k 652.35 793.42 3.97k 400.73 -# Txn start ts 374.38E 0 16.00E 375.48P 1.25P 89.05T 1.25P -# Wait time 943ms 1ms 19ms 1ms 2ms 1ms 972us -. -. -. -``` - -### 定位问题语句的方法 - -并不是所有 SLOW_QUERY 的语句都是有问题的。会造成集群整体压力增大的，是那些 process_time 很大的语句。wait_time 很大，但 process_time 很小的语句通常不是问题语句，是因为被问题语句阻塞，在执行队列等待造成的响应时间过长。 - -## `admin show slow` 命令 - -除了获取 TiDB 日志，还有一种定位慢查询的方式是通过 `admin show slow` SQL 命令： - -{{< copyable "sql" >}} - -```sql -admin show slow recent N; -``` - -{{< copyable "sql" >}} - -```sql -admin show slow top [internal | all] N; -``` - -`recent N` 会显示最近的 N 条慢查询记录，例如： - -{{< copyable "sql" >}} - -```sql -admin show slow recent 10; -``` - -`top N` 则显示最近一段时间（大约几天）内，最慢的查询记录。如果指定 `internal` 选项，则返回查询系统内部 SQL 的慢查询记录；如果指定 `all` 选项，返回系统内部和用户 SQL 汇总以后的慢查询记录；默认只返回用户 SQL 中的慢查询记录。 - -{{< copyable "sql" >}} - -```sql -admin show slow top 3; -admin show slow top internal 3; -admin show slow top all 5; -``` - -由于内存限制，保留的慢查询记录的条数是有限的。当命令查询的 `N` 大于记录条数时，返回的结果记录条数会小于 `N`。 - -输出内容详细说明，如下： - -| 列名 | 描述 | -|:------|:---- | -| start | SQL 语句执行开始时间 | -| duration | SQL 语句执行持续时间 | -| details | 执行语句的详细信息 | -| succ | SQL 语句执行是否成功，1: 成功，0: 失败 | -| conn_id | session 连接 ID | -| transcation_ts | 事务提交的 commit ts | -| user | 执行该语句的用户名 | -| db | 执行该 SQL 涉及到 database | -| table_ids | 执行该 SQL 涉及到表的 ID | -| index_ids | 执行该 SQL 涉及到索引 ID | -| internal | 表示为 TiDB 内部的 SQL 语句 | -| digest | 表示 SQL 语句的指纹 | -| sql | 执行的 SQL 语句 | diff --git a/v3.1/how-to/migrate/from-mysql-aurora.md b/v3.1/how-to/migrate/from-mysql-aurora.md deleted file mode 100644 index 9cd709d62862..000000000000 --- a/v3.1/how-to/migrate/from-mysql-aurora.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 -summary: 使用 DM 从 MySQL/Amazon Aurora MySQL 迁移数据。 -category: how-to -aliases: ['/docs-cn/v3.1/how-to/migrate/from-aurora/'] ---- - -# 从 MySQL 迁移数据 —— 以 Amazon Aurora MySQL 为例 - -本文以 [Amazon Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 为例介绍如何使用 DM 从 MySQL 协议数据库迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/v3.1/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务（`task.yaml` 是之前编辑的配置文件） - - {{< copyable "" >}} - - ```bash - start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "shell-regular" >}} - -```bash -query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ``` -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 `task.yaml` 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/v3.1/how-to/monitor/monitor-a-cluster.md b/v3.1/how-to/monitor/monitor-a-cluster.md deleted file mode 100644 index afafe8423dee..000000000000 --- a/v3.1/how-to/monitor/monitor-a-cluster.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -title: TiDB 集群监控 -category: how-to ---- - -# TiDB 集群监控 - -TiDB 提供了以下两种接口来监控集群状态： - -- [状态接口](#使用状态接口)：通过 HTTP 接口对外汇报组件的信息。 -- [Metrics 接口](#使用-metrics-接口)：使用 Prometheus 记录组件中各种操作的详细信息，使用 Grafana 进行可视化展示。 - -## 使用状态接口 - -状态接口用于监控组件的一些基本信息，并且可以作为 keepalive 的监测接口。另外，通过 PD 的状态接口可以看到整个 TiKV 集群的详细信息。 - -### TiDB Server - -- TiDB API 地址：`http://${host}:${port}` -- 默认端口：10080 -- 各类 `api_name` 详细信息：参见 [TiDB API 文档](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) - -以下示例中，通过访问 `http://${host}:${port}/status` 获取当前 TiDB Server 的状态，并判断该 TiDB Server 是否存活。结果以 **JSON** 格式返回： - -{{< copyable "shell-regular" >}} - -```bash -curl http://127.0.0.1:10080/status -``` - -``` -{ - connections: 0, # 当前 TiDB Server 上的客户端连接数 - version: "5.7.25-TiDB-v3.0.0-beta-250-g778c3f4a5", # TiDB 版本号 - git_hash: "778c3f4a5a716880bcd1d71b257c8165685f0d70" # TiDB 当前代码的 Git Hash -} -``` - -### PD Server - -- PD API 地址：`http://${host}:${port}/pd/api/v1/${api_name}` -- 默认端口：2379 -- 各类 `api_name` 详细信息：参见 [PD API Doc](https://download.pingcap.com/pd-api-doc.html) - -通过该接口可以获取当前所有 TiKV 节点的状态以及负载均衡信息。下面以一个单节点的 TiKV 集群为例，说明用户需要了解的信息： - -{{< copyable "shell-regular" >}} - -```bash -curl http://127.0.0.1:2379/pd/api/v1/stores -``` - -``` -{ - "count": 1, # TiKV 节点数量 - "stores": [ # TiKV 节点的列表 - # 集群中单个 TiKV 节点的信息 - { - "store": { - "id": 1, - "address": "127.0.0.1:20160", - "version": "3.0.0-beta", - "state_name": "Up" - }, - "status": { - "capacity": "20 GiB", # 存储总容量 - "available": "16 GiB", # 存储剩余容量 - "leader_count": 17, - "leader_weight": 1, - "leader_score": 17, - "leader_size": 17, - "region_count": 17, - "region_weight": 1, - "region_score": 17, - "region_size": 17, - "start_ts": "2019-03-21T14:09:32+08:00", # 启动时间 - "last_heartbeat_ts": "2019-03-21T14:14:22.961171958+08:00", # 最后一次心跳的时间 - "uptime": "4m50.961171958s" - } - } - ] -``` - -## 使用 metrics 接口 - -Metrics 接口用于监控整个集群的状态和性能。 - -- 如果使用 TiDB Ansible 部署 TiDB 集群，监控系统（Prometheus 和 Grafana）会同时部署。 -- 如果使用其他方式部署 TiDB 集群，在使用 metrics 接口前，需先[部署 Prometheus 和 Grafana](#部署-prometheus-和-grafana)。 - -成功部署 Prometheus 和 Grafana 之后，[配置 Grafana](#配置-grafana)。 - -### 部署 Prometheus 和 Grafana - -假设 TiDB 的拓扑结构如下： - -| 节点 | 主机 IP | 服务 | -| :-- | :-- | :-------------- | -| Node1 | 192.168.199.113| PD1, TiDB, node_export, Prometheus, Grafana | -| Node2 | 192.168.199.114| PD2, node_export | -| Node3 | 192.168.199.115| PD3, node_export | -| Node4 | 192.168.199.116| TiKV1, node_export | -| Node5 | 192.168.199.117| TiKV2, node_export | -| Node6 | 192.168.199.118| TiKV3, node_export | - -#### 第 1 步：下载二进制包 - -下载二进制包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://github.com/prometheus/prometheus/releases/download/v2.2.1/prometheus-2.2.1.linux-amd64.tar.gz && -wget https://github.com/prometheus/node_exporter/releases/download/v0.15.2/node_exporter-0.15.2.linux-amd64.tar.gz && -wget https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.6.3.linux-x64.tar.gz -``` - -解压二进制包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf prometheus-2.2.1.linux-amd64.tar.gz && -tar -xzf node_exporter-0.15.2.linux-amd64.tar.gz && -tar -xzf grafana-4.6.3.linux-x64.tar.gz -``` - -#### 第 2 步：在 Node1，Node2，Node3，Node4 上启动 `node_exporter` - -{{< copyable "shell-regular" >}} - -```bash -cd node_exporter-0.15.2.linux-amd64 -``` - -启动 node_exporter 服务： - -{{< copyable "shell-regular" >}} - -```bash -./node_exporter --web.listen-address=":9100" \ - --log.level="info" & -``` - -#### 第 3 步：在 Node1 上启动 Prometheus - -编辑 Prometheus 的配置文件： - -{{< copyable "shell-regular" >}} - -```bash -cd prometheus-2.2.1.linux-amd64 && -vi prometheus.yml -``` - -```ini -... - -global: - scrape_interval: 15s - evaluation_interval: 15s - # scrape_timeout 设置为全局默认值 (10s) - external_labels: - cluster: 'test-cluster' - monitor: "prometheus" - -scrape_configs: - - job_name: 'overwritten-nodes' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.113:9100' - - '192.168.199.114:9100' - - '192.168.199.115:9100' - - '192.168.199.116:9100' - - '192.168.199.117:9100' - - '192.168.199.118:9100' - - - job_name: 'tidb' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.113:10080' - - - job_name: 'pd' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.113:2379' - - '192.168.199.114:2379' - - '192.168.199.115:2379' - - - job_name: 'tikv' - honor_labels: true # 不要覆盖 job 和实例的 label - static_configs: - - targets: - - '192.168.199.116:20180' - - '192.168.199.117:20180' - - '192.168.199.118:20180' - -... -``` - -启动 Prometheus 服务： - -{{< copyable "shell-regular" >}} - -```bash -./prometheus \ - --config.file="./prometheus.yml" \ - --web.listen-address=":9090" \ - --web.external-url="http://192.168.199.113:9090/" \ - --web.enable-admin-api \ - --log.level="info" \ - --storage.tsdb.path="./data.metrics" \ - --storage.tsdb.retention="15d" & -``` - -#### 第 4 步：在 Node1 上启动 Grafana - -编辑 Grafana 的配置文件： - -```bash -cd grafana-4.6.3 && -vi conf/grafana.ini -``` - -```ini -... - -[paths] -data = ./data -logs = ./data/log -plugins = ./data/plugins -[server] -http_port = 3000 -domain = 192.168.199.113 -[database] -[session] -[analytics] -check_for_updates = true -[security] -admin_user = admin -admin_password = admin -[snapshots] -[users] -[auth.anonymous] -[auth.basic] -[auth.ldap] -[smtp] -[emails] -[log] -mode = file -[log.console] -[log.file] -level = info -format = text -[log.syslog] -[event_publisher] -[dashboards.json] -enabled = false -path = ./data/dashboards -[metrics] -[grafana_net] -url = https://grafana.net - -... - -``` - -启动 Grafana 服务： - -{{< copyable "shell-regular" >}} - -```bash -./bin/grafana-server \ - --config="./conf/grafana.ini" & -``` - -### 配置 Grafana - -本小节介绍如何配置 Grafana。 - -#### 第 1 步：添加 Prometheus 数据源 - -1. 登录 Grafana 界面。 - - - 默认地址：`http://localhost:3000` - - 默认账户：admin - - 默认密码：admin - -2. 点击 Grafana 图标打开侧边栏。 - -3. 在侧边栏菜单中，点击 **Data Source**。 - -4. 点击 **Add data source**。 - -5. 指定数据源的相关信息： - - - 在 **Name** 处，为数据源指定一个名称。 - - 在 **Type** 处，选择 **Prometheus**。 - - 在 **URL** 处，指定 Prometheus 的 IP 地址。 - - 根据需求指定其它字段。 - -6. 点击 **Add** 保存新的数据源。 - -#### 第 2 步：导入 Grafana 面板 - -执行以下步骤，为 PD Server、TiKV Server 和 TiDB Server 分别导入 Grafana 面板： - -1. 点击侧边栏的 Grafana 图标。 - -2. 在侧边栏菜单中，依次点击 **Dashboards** > **Import** 打开 **Import Dashboard** 窗口。 - -3. 点击 **Upload .json File** 上传对应的 JSON 文件（下载 [TiDB Grafana 配置文件](https://github.com/pingcap/tidb-ansible/tree/master/scripts))。 - - > **注意：** - > - > TiKV、PD 和 TiDB 面板对应的 JSON 文件分别为 `tikv_summary.json`，`tikv_details.json`，`tikv_trouble_shooting.json`，`pd.json`，`tidb.json`，`tidb_summary.json`。 - -4. 点击 **Load**。 - -5. 选择一个 Prometheus 数据源。 - -6. 点击 **Import**，Prometheus 面板即导入成功。 - -### 查看组件 metrics - -在顶部菜单中，点击 **New dashboard**，选择要查看的面板。 - -![view dashboard](/media/view-dashboard.png) - -可查看以下集群组件信息： - -+ **TiDB Server：** - + query 处理时间，可以看到延迟和吞吐 - + ddl 过程监控 - + TiKV client 相关的监控 - + PD client 相关的监控 - -+ **PD Server：** - + 命令执行的总次数 - + 某个命令执行失败的总次数 - + 某个命令执行成功的耗时统计 - + 某个命令执行失败的耗时统计 - + 某个命令执行完成并返回结果的耗时统计 - -+ **TiKV Server：** - + GC 监控 - + 执行 KV 命令的总次数 - + Scheduler 执行命令的耗时统计 - + Raft propose 命令的总次数 - + Raft 执行命令的耗时统计 - + Raft 执行命令失败的总次数 - + Raft 处理 ready 状态的总次数 diff --git a/v3.1/how-to/monitor/overview.md b/v3.1/how-to/monitor/overview.md deleted file mode 100644 index a23871517f14..000000000000 --- a/v3.1/how-to/monitor/overview.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: TiDB 监控框架概述 -category: how-to ---- - -# TiDB 监控框架概述 - -TiDB 使用开源时序数据库 [Prometheus](https://prometheus.io) 作为监控和性能指标信息存储方案，使用 [Grafana](https://grafana.com/grafana) 作为可视化组件进行展示。 - -## Prometheus 在 TiDB 中的应用 - -Prometheus 是一个拥有多维度数据模型的、灵活的查询语句的时序数据库。Prometheus 作为热门的开源项目，拥有活跃的社区及众多的成功案例。 - -Prometheus 提供了多个组件供用户使用。目前，TiDB 使用了以下组件： - -- Prometheus Server：用于收集和存储时间序列数据。 -- Client 代码库：用于定制程序中需要的 Metric。 -- Alertmanager：用于实现报警机制。 - -其结构如下图所示： - -![Prometheus in TiDB](/media/prometheus-in-tidb.png) - -## Grafana 在 TiDB 中的应用 - -Grafana 是一个开源的 metric 分析及可视化系统。TiDB 使用 Grafana 来展示 TiDB 的各项性能指标。如下图所示： - -![Grafana in TiDB](/media/grafana-screenshot.png) diff --git a/v3.1/how-to/scale/horizontally.md b/v3.1/how-to/scale/horizontally.md deleted file mode 100644 index 031f68f9f774..000000000000 --- a/v3.1/how-to/scale/horizontally.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: TiDB 集群扩容缩容方案 -category: how-to ---- - -# TiDB 集群扩容缩容方案 - -TiDB 集群可以在不影响线上服务的情况下动态进行扩容和缩容。 - -> **注意：** -> -> 如果使用 Ansible 部署 TiDB 集群，请参考[使用 Ansible 扩容缩容](/v3.1/how-to/scale/with-ansible.md)。 - -下面分别介绍如何增加或者删除 PD，TiKV 以及 TiDB 的节点。 - -下面用到的 pd-ctl 文档可以参考 [pd-control](/v3.1/reference/tools/pd-control.md)。 - -## PD - -假设现在我们有三个 PD 服务，详细信息如下： - -|Name|ClientUrls|PeerUrls| -|----|----------|--------| -|pd1|`http://host1:2379`|`http://host1:2380`| -|pd2|`http://host2:2379`|`http://host2:2380`| -|pd3|`http://host3:2379`|`http://host3:2380`| - -我们可以通过 pd-ctl 来查看当前所有 PD 节点的信息： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 -i ->> member -``` - -### 动态添加节点 - -我们可以使用 `join` 参数，将一个新的 PD 服务加入到现有的 PD 集群里面。 -如果我们需要添加 `pd4`，只需要在 `--join` 参数里面填入当前 PD 集群任意一个 PD 服务的 client url，比如： - -{{< copyable "shell-regular" >}} - -```bash -./bin/pd-server --name=pd4 \ - --client-urls="http://host4:2379" \ - --peer-urls="http://host4:2380" \ - --join="http://host1:2379" -``` - -### 动态删除节点 - -如果我们需要删除 `pd4`，可以通过 pd-ctl 来完成： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> member delete name pd4 -``` - -### 动态迁移节点 - -如果想把现有的 PD 节点迁移到新的机器上，我们可以先在新的机器上添加节点，然后把旧的机器上的节点删除掉。迁移过程中应该一个节点一个节点逐个迁移，每完成一个步骤可以先查看一下当前的所有节点信息来进行确认。 - -## TiKV - -我们可以通过 pd-ctl 来查看当前所有 TiKV 节点的信息： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store -``` - -### 动态添加节点 - -动态添加一个新的 TiKV 服务非常容易，只需要在新的机器上启动一个 TiKV 服务，不需要其他特殊操作。 -新启动的 TiKV 服务会自动注册到现有集群的 PD 中，PD 会自动做负载均衡，逐步地把一部分数据迁移到新的TiKV 服务中，从而降低现有 TiKV 服务的压力。 - -### 动态删除节点 - -安全地删除（下线）一个 TiKV 服务需要先告诉 PD，这样 PD 可以先把这个 TiKV 服务上面的数据迁移到其他 TiKV 服务上，保证数据有足够的副本数。 - -假设我们需要删除 store id 为 1 的 TiKV 服务，可以通过 pd-ctl 来完成： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store delete 1 -``` - -然后可以查看这个 TiKV 服务的状态： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u http://host1:2379 ->> store 1 -``` - -``` -{ - "store": { - "id": 1, - "address": "127.0.0.1:21060", - "state": 1, - "state_name": "Offline" - }, - "status": { - ... - } -} -``` - -我们可以通过这个 store 的 state_name 来确定这个 store 的状态： - -- Up：这个 store 正常服务 -- Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 -- Down：超过一小时（可通过 `max-down-time` 配置）没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 -- Offline：这个 store 正在将其中的 Region 转移到其他节点，此时这个 store 仍在服务中 -- Tombstone：这个 store 已经完成下线，此时 store 上已经没有数据，可以关闭实例 - -### 动态迁移节点 - -迁移 TiKV 服务也是通过先在新的机器上添加节点，然后把旧的机器上的节点下线来完成。迁移过程中可以先把新集群的机器全部添加到已有的集群中，然后再把旧的节点一个一个地下线。可以通过查看正在下线的节点的状态信息来确定这个节点是否已经完成下线，确认完成以后再下线下一个节点。 - -## TiDB - -TiDB 是一个无状态的服务，这也就意味着我们能直接添加和删除 TiDB。需要注意的是，如果我们在 TiDB 的服务的前面搭建了一个 proxy（譬如 HAProxy），则需要更新 proxy 的配置并重新载入。 diff --git a/v3.1/how-to/scale/with-ansible.md b/v3.1/how-to/scale/with-ansible.md deleted file mode 100644 index 73dd9de9a285..000000000000 --- a/v3.1/how-to/scale/with-ansible.md +++ /dev/null @@ -1,527 +0,0 @@ ---- -title: 使用 TiDB Ansible 扩容缩容 TiDB 集群 -category: how-to ---- - -# 使用 TiDB Ansible 扩容缩容 TiDB 集群 - -TiDB 集群可以在不影响线上服务的情况下进行扩容和缩容。 - -> **注意：** -> -> 以下缩容示例中，被移除的节点没有混合部署其他服务；如果混合部署了其他服务，不能按如下操作。 - -假设拓扑结构如下所示： - -| Name | Host IP | Services | -| ---- | ------- | -------- | -| node1 | 172.16.10.1 | PD1 | -| node2 | 172.16.10.2 | PD2 | -| node3 | 172.16.10.3 | PD3, Monitor | -| node4 | 172.16.10.4 | TiDB1 | -| node5 | 172.16.10.5 | TiDB2 | -| node6 | 172.16.10.6 | TiKV1 | -| node7 | 172.16.10.7 | TiKV2 | -| node8 | 172.16.10.8 | TiKV3 | -| node9 | 172.16.10.9 | TiKV4 | - -## 扩容 TiDB/TiKV 节点 - -例如，如果要添加两个 TiDB 节点（node101、node102），IP 地址为 172.16.10.101、172.16.10.102，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.101 - 172.16.10.102 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.4 - 172.16.10.5 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - 172.16.10.101 - 172.16.10.102 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | **node101** | **172.16.10.101**|**TiDB3** | - | **node102** | **172.16.10.102**|**TiDB4** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml -l 172.16.10.101,172.16.10.102 - ``` - - > **注意：** - > - > 如果 `inventory.ini` 中为节点配置了别名，如 `node101 ansible_host=172.16.10.101`，执行 ansible-playbook 时 -l 请指定别名，以下步骤类似。例如：`ansible-playbook bootstrap.yml -l node101,node102` - -3. 部署新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml -l 172.16.10.101,172.16.10.102 - ``` - -4. 启动新节点服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml -l 172.16.10.101,172.16.10.102 - ``` - -5. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - - 可使用同样的步骤添加 TiKV 节点。但如果要添加 PD 节点，则需手动更新一些配置文件。 - -## 扩容 PD 节点 - -例如，如果要添加一个 PD 节点（node103），IP 地址为 172.16.10.103，可以进行如下操作： - -1. 编辑 `inventory.ini` 文件，添加节点信息置于 `[pd_servers]` 主机组最后一行： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.103 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | **node103** | **172.16.10.103** | **PD4** | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -2. 初始化新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook bootstrap.yml -l 172.16.10.103 - ``` - -3. 部署新增节点： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml -l 172.16.10.103 - ``` - -4. 登录新增的 PD 节点，编辑启动脚本：`{deploy_dir}/scripts/run_pd.sh` - - 1. 移除 `--initial-cluster="xxxx" \` 配置，注意这里不能在行开头加注释符 #。 - - 2. 添加 `--join="http://172.16.10.1:2379" \`，IP 地址 （172.16.10.1） 可以是集群内现有 PD IP 地址中的任意一个。 - - 3. 在新增 PD 节点中手动启动 PD 服务： - - {{< copyable "shell-regular" >}} - - ```bash - {deploy_dir}/scripts/start_pd.sh - ``` - - > **注意：** - > - > 启动前，需要通过 [PD Control](/v3.1/reference/tools/pd-control.md) 工具确认当前 PD 节点的 `health` 状态均为 "true"，否则 PD 服务会启动失败，同时日志中报错 `["join meet error"] [error="etcdserver: unhealthy cluster"]`。 - - 4. 使用 `pd-ctl` 检查新节点是否添加成功： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -5. 滚动升级整个集群： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -6. 启动监控服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml -l 172.16.10.103 - ``` - -7. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -8. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群和新增节点的状态。 - -## 缩容 TiDB 节点 - -例如，如果要移除一个 TiDB 节点（node5），IP 地址为 172.16.10.5，可以进行如下操作： - -1. 停止 node5 节点上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.5 - ``` - -2. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - #172.16.10.5 # 注释被移除节点 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | **node5** | **172.16.10.5** | **TiDB2 已删除** | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -3. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -4. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 TiKV 节点 - -例如，如果要移除一个 TiKV 节点（node9），IP 地址为 172.16.10.9，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node9 节点的 store id： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store - ``` - - 2. 从集群中移除 node9，假如 store id 为 10： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store delete 10 - ``` - -2. 使用 Grafana 或者 `pd-ctl` 检查节点是否下线成功（下线需要一定时间，下线节点的状态变为 Tombstone 就说明下线成功了）： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d store 10 - ``` - -3. 下线成功后，停止 node9 上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.9 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - 172.16.10.2 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - #172.16.10.9 # 注释被移除节点 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | node2 | 172.16.10.2 | PD2 | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | **node9** | **172.16.10.9** | **TiKV4 已删除** | - -5. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -6. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 - -## 缩容 PD 节点 - -例如，如果要移除一个 PD 节点（node2），IP 地址为 172.16.10.2，可以进行如下操作： - -1. 使用 `pd-ctl` 从集群中移除节点： - - 1. 查看 node2 节点的 name： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - - 2. 从集群中移除 node2，假如 name 为 pd2： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member delete name pd2 - ``` - -2. 使用 `pd-ctl` 检查节点是否下线成功（PD 下线会很快，结果中没有 node2 节点信息即为下线成功）： - - {{< copyable "shell-regular" >}} - - ```bash - /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://172.16.10.1:2379" -d member - ``` - -3. 下线成功后，停止 node2 上的服务： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml -l 172.16.10.2 - ``` - -4. 编辑 `inventory.ini` 文件，移除节点信息： - - ```ini - [tidb_servers] - 172.16.10.4 - 172.16.10.5 - - [pd_servers] - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - - [tikv_servers] - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitored_servers] - 172.16.10.4 - 172.16.10.5 - 172.16.10.1 - #172.16.10.2 # 注释被移除节点 - 172.16.10.3 - 172.16.10.6 - 172.16.10.7 - 172.16.10.8 - 172.16.10.9 - - [monitoring_servers] - 172.16.10.3 - - [grafana_servers] - 172.16.10.3 - ``` - - 现在拓扑结构如下所示： - - | Name | Host IP | Services | - | ---- | ------- | -------- | - | node1 | 172.16.10.1 | PD1 | - | **node2** | **172.16.10.2** | **PD2 已删除** | - | node3 | 172.16.10.3 | PD3, Monitor | - | node4 | 172.16.10.4 | TiDB1 | - | node5 | 172.16.10.5 | TiDB2 | - | node6 | 172.16.10.6 | TiKV1 | - | node7 | 172.16.10.7 | TiKV2 | - | node8 | 172.16.10.8 | TiKV3 | - | node9 | 172.16.10.9 | TiKV4 | - -5. 滚动升级整个集群： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -6. 更新 Prometheus 配置并重启： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -7. 打开浏览器访问监控平台：`http://172.16.10.3:3000`，监控整个集群的状态。 diff --git a/v3.1/how-to/secure/enable-tls-between-components.md b/v3.1/how-to/secure/enable-tls-between-components.md deleted file mode 100644 index b5a363b76209..000000000000 --- a/v3.1/how-to/secure/enable-tls-between-components.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 为 TiDB 组件间开启 TLS 和数据加密存储 -category: how-to ---- - -# 为 TiDB 组件间开启 TLS 和数据加密存储 - -本文档介绍 TiDB 集群如何开启 TLS 验证和数据加密存储。 - -## 开启 TLS 验证 - -本部分介绍 TiDB 集群如何开启 TLS 验证，TLS 验证支持： - -- TiDB 组件之间的双向验证，包括 TiDB、TiKV、PD 相互之间，TiKV Control 与 TiKV、PD Control 与 PD 的双向认证，以及 TiKV peer 之间、PD peer 之间。一旦开启，所有组件之间均使用验证，不支持只开启某一部分的验证。 -- MySQL Client 与 TiDB 之间的客户端对服务器身份的单向验证以及双向验证。 - -MySQL Client 与 TiDB 之间使用一套证书，TiDB 集群组件之间使用另外一套证书。 - -### TiDB 集群组件间开启 TLS（双向认证） - -1. 准备证书。 - - 推荐为 TiDB、TiKV、PD 分别准备一个 server 证书，并保证可以相互验证，而它们的各种客户端共用 client 证书。 - - 有多种工具可以生成自签名证书，如 `openssl`，`easy-rsa`，`cfssl`。 - - 这里提供一个使用 `cfssl` 生成证书的示例：[生成自签名证书](/v3.1/how-to/secure/generate-self-signed-certificates.md)。 - -2. 配置证书。 - - - TiDB - - 在 `config` 文件或命令行参数中设置： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs for connection with cluster components. - cluster-ssl-ca = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format for connection with cluster components. - cluster-ssl-cert = "/path/to/tidb-server.pem" - # Path of file that contains X509 key in PEM format for connection with cluster components. - cluster-ssl-key = "/path/to/tidb-server-key.pem" - ``` - - - TiKV - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # set the path for certificates. Empty string means disabling secure connectoins. - ca-path = "/path/to/ca.pem" - cert-path = "/path/to/tikv-server.pem" - key-path = "/path/to/tikv-server-key.pem" - ``` - - - PD - - 在 `config` 文件或命令行参数中设置，并设置相应的 URL 为 https： - - ```toml - [security] - # Path of file that contains list of trusted SSL CAs. if set, following four settings shouldn't be empty - cacert-path = "/path/to/ca.pem" - # Path of file that contains X509 certificate in PEM format. - cert-path = "/path/to/pd-server.pem" - # Path of file that contains X509 key in PEM format. - key-path = "/path/to/pd-server-key.pem" - ``` - - 此时 TiDB 集群各个组件间已开启双向验证。 - - > **注意：** - > - > 若 TiDB 集群各个组件间已开启 TLS，在使用 tikv-ctl 或 pd-ctl 工具连接集群时，需要指定 client 证书，示例： - - {{< copyable "shell-regular" >}} - - ```bash - ./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem - ``` - - {{< copyable "shell-regular" >}} - - ```bash - ./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/client-key.pem" - ``` - -### MySQL 与 TiDB 间开启 TLS - -请参考 [使用加密连接](/v3.1/how-to/secure/enable-tls-clients.md)。 - -## 开启数据加密存储 - -在 TiDB 集群中，用户的数据都存储在 TiKV 中，配置了 TiKV 数据加密存储功能，就代表 TiDB 集群已经加密存储了用户的数据。本部分主要介绍如何配置 TiKV 的加密存储功能。 - -### 操作流程 - -1. 生成 token 文件。 - - token 文件存储的是密钥，用于对用户数据进行加密，以及对已加密的数据进行解密。 - - {{< copyable "shell-regular" >}} - - ```bash - ./tikv-ctl random-hex --len 256 > cipher-file-256 - ``` - - > **注意：** - > - > TiKV 只接受 hex 格式的 token 文件，文件的长度必须是 2^n，并且小于等于 1024。 - -2. 配置 TiKV。 - - ```toml - [security] - # Cipher file 的存储路径 - cipher-file = "/path/to/cipher-file-256" - ``` - -> **注意：** -> -> 若使用 [Lightning](/v3.1/reference/tools/tidb-lightning/overview.md) 向集群导入数据，如果目标集群开启了加密功能，Lightning 生成的 sst 文件也必须是加密的格式。 - -### 使用限制 - -目前 TiKV 数据加密存储存在以下限制： - -- 对之前没有开启加密存储的集群，不支持开启该功能。 -- 已经开启加密功能的集群，不允许关闭加密存储功能。 -- 同一集群内部，不允许部分 TiKV 实例开启该功能，部分 TiKV 实例不开启该功能。对于加密存储功能，所有 TiKV 实例要么都开启该功能，要么都不开启该功能。这是由于 TiKV 实例之间会有数据迁移，如果开启了加密存储功能，迁移过程中数据也是加密的。 diff --git a/v3.1/how-to/secure/enable-tls-clients.md b/v3.1/how-to/secure/enable-tls-clients.md deleted file mode 100644 index 7eb9ddbad06a..000000000000 --- a/v3.1/how-to/secure/enable-tls-clients.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: 使用加密连接 -category: how-to ---- - -# 使用加密连接 - -TiDB 服务端默认采用非加密连接，因而具备监视信道流量能力的第三方可以知悉 TiDB 服务端与客户端之间发送和接受的数据，包括但不限于查询语句内容、查询结果等。若信道是不可信的，例如客户端是通过公网连接到 TiDB 服务端的，则非加密连接容易造成信息泄露，建议使用加密连接确保安全性。 - -TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接，协议与 MySQL 加密连接一致，现有 MySQL 客户端如 MySQL 运维工具和 MySQL 驱动等能直接支持。TLS 的前身是 SSL，因而 TLS 有时也被称为 SSL，但由于 SSL 协议有已知安全漏洞，TiDB 实际上并未支持。TiDB 支持的 TLS/SSL 协议版本为 TLS 1.0、TLS 1.1、TLS 1.2。 - -使用加密连接后，连接将具有以下安全性质： - -- 保密性：流量明文无法被窃听； -- 完整性：流量明文无法被篡改； -- 身份验证（可选）：客户端和服务端能验证双方身份，避免中间人攻击。 - -TiDB 的加密连接支持默认是关闭的，必须在 TiDB 服务端通过配置开启加密连接的支持后，才能在客户端中使用加密连接。另外，与 MySQL 一致，TiDB 加密连接是以单个连接为单位的，并且是可选的，因而对于开启了加密连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。大部分 MySQL 客户端默认不采用加密连接，因此一般还要显式地要求客户端使用加密连接。 - -简单来说，要使用加密连接必须同时满足以下两个条件： - -1. TiDB 服务端配置开启加密连接的支持 -2. 客户端指定使用加密连接 - -## 配置 TiDB 启用加密连接支持 - -在启动 TiDB 时，至少需要在配置文件中同时指定 `ssl-cert` 和 `ssl-key` 参数，才能使 TiDB 服务端接受加密连接。还可以指定 `ssl-ca` 参数进行客户端身份验证（请参见[配置启用身份验证](#配置启用身份验证)章节）。 - -- [`ssl-cert`](/v3.1/reference/configuration/tidb-server/configuration-file.md#ssl-cert)：指定 SSL 证书文件路径 -- [`ssl-key`](/v3.1/reference/configuration/tidb-server/configuration-file.md#ssl-key)：指定证书文件对应的私钥 -- [`ssl-ca`](/v3.1/reference/configuration/tidb-server/configuration-file.md#ssl-ca)：可选，指定受信任的 CA 证书文件路径 - -参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端加密连接到 TiDB 服务端。 - -上述证书及密钥可以使用 OpenSSL 签发和生成，也可以使用 MySQL 自带的工具 `mysql_ssl_rsa_setup` 快捷生成： - -{{< copyable "shell-regular" >}} - -```bash -mysql_ssl_rsa_setup --datadir=./certs -``` - -以上命令将在 `certs` 目录下生成以下文件： - -``` -certs -├── ca-key.pem -├── ca.pem -├── client-cert.pem -├── client-key.pem -├── private_key.pem -├── public_key.pem -├── server-cert.pem -└── server-key.pem -``` - -对应的 TiDB 配置文件参数为： - -```toml -[security] -ssl-cert = "certs/server-cert.pem" -ssl-key = "certs/server-key.pem" -``` - -若证书参数无误，则 TiDB 在启动时将会输出 `Secure connection is enabled`，否则 TiDB 会输出 `Secure connection is NOT ENABLED`。 - -## 配置 MySQL 客户端使用加密连接 - -MySQL 5.7 及以上版本自带的客户端默认尝试使用安全连接，若服务端不支持安全连接则自动退回到使用非安全连接；MySQL 5.7 以下版本自带的客户端默认采用非安全连接。 - -可以通过命令行参数修改客户端的连接行为，包括： - -- 强制使用安全连接，若服务端不支持安全连接则连接失败 (`--ssl-mode=REQUIRED`) -- 尝试使用安全连接，若服务端不支持安全连接则退回使用不安全连接 -- 使用不安全连接 (`--ssl-mode=DISABLED`) - -详细信息请参阅 MySQL 文档中关于[客户端配置安全连接](https://dev.mysql.com/doc/refman/5.7/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration)的部分。 - -## 配置启用身份验证 - -若在 TiDB 服务端或 MySQL 客户端中未指定 `ssl-ca` 参数，则默认不会进行客户端或服务端身份验证，无法抵御中间人攻击，例如客户端可能会“安全地”连接到了一个伪装的服务端。可以在服务端和客户端中配置 `ssl-ca` 参数进行身份验证。一般情况下只需验证服务端身份，但也可以验证客户端身份进一步增强安全性。 - -- 若要使 MySQL 客户端验证 TiDB 服务端身份，TiDB 服务端需至少配置 `ssl-cert` 和 `ssl-key` 参数，客户端需至少指定 `--ssl-ca` 参数，且 `--ssl-mode` 至少为 `VERIFY_CA`。必须确保 TiDB 服务端配置的证书（`ssl-cert`）是由客户端 `--ssl-ca` 参数所指定的 CA 所签发的，否则身份验证失败。 -- 若要使 TiDB 服务端验证 MySQL 客户端身份，TiDB 服务端需配置 `ssl-cert`、`ssl-key`、`ssl-ca` 参数，客户端需至少指定 `--ssl-cert`、`--ssl-key` 参数。必须确保服务端配置的证书和客户端配置的证书都是由服务端配置指定的 `ssl-ca` 签发的。 -- 若要进行双向身份验证，请同时满足上述要求。 - -> **注意：** -> -> 目前 TiDB 尚不支持强制验证客户端身份，即服务端对客户端的身份验证是可选的。若客户端在 TLS 握手时未出示自己的身份证书，也能正常建立 TLS 连接。 - -## 检查当前连接是否是加密连接 - -可以通过 `SHOW STATUS LIKE "%Ssl%";` 了解当前连接的详细情况，包括是否使用了安全连接、安全连接采用的加密协议、TLS 版本号等。 - -以下是一个安全连接中执行该语句的结果。由于客户端支持的 TLS 版本号和加密协议会有所不同，执行结果相应地也会有所变化。 - -{{< copyable "sql" >}} - -```sql -SHOW STATUS LIKE "%Ssl%"; -``` - -``` -...... -| Ssl_verify_mode | 5 | -| Ssl_version | TLSv1.2 | -| Ssl_cipher | ECDHE-RSA-AES128-GCM-SHA256 | -...... -``` - -除此以外，对于 MySQL 自带客户端，还可以使用 `STATUS` 或 `\s` 语句查看连接情况： - -{{< copyable "sql" >}} - -```sql -\s -``` - -``` -... -SSL: Cipher in use is ECDHE-RSA-AES128-GCM-SHA256 -... -``` - -## 支持的 TLS 版本及密钥交换协议和加密算法 - -TiDB 支持的 TLS 版本及密钥交换协议和加密算法由 Golang 官方库决定。 - -### 支持的 TLS 版本 - -- TLS 1.0 -- TLS 1.1 -- TLS 1.2 - -### 支持的密钥交换协议及加密算法 - -- TLS\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA -- TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256 -- TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384 -- TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305 -- TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305 diff --git a/v3.1/how-to/secure/generate-self-signed-certificates.md b/v3.1/how-to/secure/generate-self-signed-certificates.md deleted file mode 100644 index 4280b63d2d2f..000000000000 --- a/v3.1/how-to/secure/generate-self-signed-certificates.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: 生成自签名证书 -category: how-to ---- - -# 生成自签名证书 - -## 概述 - -本文档提供使用 `cfssl` 生成自签名证书的示例。 - -假设实例集群拓扑如下： - -| Name | Host IP | Services | -| ----- | ----------- | ---------- | -| node1 | 172.16.10.1 | PD1, TiDB1 | -| node2 | 172.16.10.2 | PD2, TiDB2 | -| node3 | 172.16.10.3 | PD3 | -| node4 | 172.16.10.4 | TiKV1 | -| node5 | 172.16.10.5 | TiKV2 | -| node6 | 172.16.10.6 | TiKV3 | - -## 下载 cfssl - -假设使用 x86_64 Linux 主机： - -{{< copyable "shell-regular" >}} - -```bash -mkdir ~/bin && -curl -s -L -o ~/bin/cfssl https://pkg.cfssl.org/R1.2/cfssl_linux-amd64 && -curl -s -L -o ~/bin/cfssljson https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64 && -chmod +x ~/bin/{cfssl,cfssljson} && -export PATH=$PATH:~/bin -``` - -## 初始化证书颁发机构 - -生成 cfssl 的默认配置，以便于之后修改： - -```bash -mkdir ~/cfssl && -cd ~/cfssl && -cfssl print-defaults config > ca-config.json && -cfssl print-defaults csr > ca-csr.json -``` - -## 生成证书 - -### 证书介绍 - -- tidb-server certificate 由 TiDB 使用，为其他组件和客户端验证 TiDB 身份。 -- tikv-server certificate 由 TiKV 使用，为其他组件和客户端验证 TiKV 身份。 -- pd-server certificate 由 PD 使用，为其他组件和客户端验证 PD 身份。 -- client certificate 用于通过 PD、TiKV、TiDB 验证客户端。例如 `pd-ctl`，`tikv-ctl`，`pd-recover`。 - -### 配置 CA 选项 - -根据实际需求修改 `ca-config.json`： - -```json -{ - "signing": { - "default": { - "expiry": "43800h" - }, - "profiles": { - "server": { - "expiry": "43800h", - "usages": [ - "signing", - "key encipherment", - "server auth", - "client auth" - ] - }, - "client": { - "expiry": "43800h", - "usages": [ - "signing", - "key encipherment", - "client auth" - ] - } - } - } -} -``` - -根据实际需求修改 `ca-csr.json` ： - -```json -{ - "CN": "My own CA", - "key": { - "algo": "rsa", - "size": 2048 - }, - "names": [ - { - "C": "CN", - "L": "Beijing", - "O": "PingCAP", - "ST": "Beijing" - } - ] -} -``` - -### 生成 CA 证书 - -{{< copyable "shell-regular" >}} - -```bash -cfssl gencert -initca ca-csr.json | cfssljson -bare ca - -``` - -将会生成以下几个文件： - -``` -ca-key.pem -ca.csr -ca.pem -``` - -### 生成服务器端证书 - -`hostname` 中为各组件的 IP 地址，以及 `127.0.0.1` - -{{< copyable "shell-regular" >}} - -```bash -echo '{"CN":"tidb-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,127.0.0.1" - | cfssljson -bare tidb-server && - -echo '{"CN":"tikv-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.4,172.16.10.5,172.16.10.6,127.0.0.1" - | cfssljson -bare tikv-server && - -echo '{"CN":"pd-server","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=server -hostname="172.16.10.1,172.16.10.2,172.16.10.3,127.0.0.1" - | cfssljson -bare pd-server -``` - -将会生成以下几个文件： - -``` -tidb-server-key.pem tikv-server-key.pem pd-server-key.pem -tidb-server.csr tikv-server.csr pd-server.csr -tidb-server.pem tikv-server.pem pd-server.pem -``` - -### 生成客户端证书 - -{{< copyable "shell-regular" >}} - -```bash -echo '{"CN":"client","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client -hostname="" - | cfssljson -bare client -``` - -将会生成以下几个文件： - -``` -client-key.pem -client.csr -client.pem -``` diff --git a/v3.1/how-to/troubleshoot/cluster-setup.md b/v3.1/how-to/troubleshoot/cluster-setup.md deleted file mode 100644 index 17179d6eb825..000000000000 --- a/v3.1/how-to/troubleshoot/cluster-setup.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: TiDB 集群故障诊断 -category: how-to ---- - -# TiDB 集群故障诊断 - -当试用 TiDB 遇到问题时，请先参考本篇文档。如果问题未解决，请按文档要求收集必要的信息通过 Github [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - -## 如何给 TiDB 开发者报告错误 - -当使用 TiDB 遇到问题并且通过后面所列信息无法解决时，请收集以下信息并[创建新 Issue](https://github.com/pingcap/tidb/issues/new/choose): - -+ 具体的出错信息以及正在执行的操作 -+ 当前所有组件的状态 -+ 出问题组件 log 中的 error/fatal/panic 信息 -+ 机器配置以及部署拓扑 -+ dmesg 中 TiDB 组件相关的问题 - -## 数据库连接不上 - -首先请确认集群的各项服务是否已经启动，包括 tidb-server、pd-server、tikv-server。请用 ps 命令查看所有进程是否在。如果某个组件的进程已经不在了，请参考对应的章节排查错误。 - -如果所有的进程都在，请查看 tidb-server 的日志，看是否有报错？常见的错误包括： - -+ InformationSchema is out of date - - 无法连接 tikv-server，请检查 pd-server 以及 tikv-server 的状态和日志。 - -+ panic - - 程序有错误，请将具体的 panic log [提供给 TiDB 开发者](https://github.com/pingcap/tidb/issues/new/choose)。 - - 如果是清空数据并重新部署服务，请确认以下信息： - -+ pd-server、tikv-server 数据都已清空 - - tikv-server 存储具体的数据，pd-server 存储 tikv-server 中数据的的元信息。如果只清空 pd-server 或只清空 tikv-server 的数据，会导致两边数据不匹配。 - -+ 清空 pd-server 和 tikv-server 的数据并重启后，也需要重启 tidb-server - - 集群 ID 是由 pd-server 在集群初始化时随机分配，所以重新部署集群后，集群 ID 会发生变化。tidb-server 业务需要重启以获取新的集群 ID。 - -## tidb-server 启动报错 - -tidb-server 无法启动的常见情况包括： - -+ 启动参数错误 - - 请参考 [TiDB 命令行参数](/v3.1/reference/configuration/tidb-server/configuration.md) - -+ 端口被占用：`lsof -i:port` - - 请确保 tidb-server 启动所需要的端口未被占用。 - -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志，确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tidb-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。 - - 例如，假设 tidb 服务位于 `192.168.1.100`，无法连接的 pd 位于 `192.168.1.101`，且 2379 为其 client port， - 则可以在 tidb 机器上执行 `nc -v -z 192.168.1.101 2379`，测试是否可以访问端口。 - 或使用 `curl -v 192.168.1.101:2379/pd/api/v1/leader` 直接检查 pd 是否正常服务。 - -## tikv-server 启动报错 - -+ 启动参数错误 - - 请参考 [TiKV 启动参数](/v3.1/reference/configuration/tikv-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 tikv-server 启动所需要的端口未被占用：`lsof -i:port`。 -+ 无法连接 pd-server - - 首先检查 pd-server 的进程状态和日志。确保 pd-server 成功启动，对应端口已打开：`lsof -i:port`。 - - 若 pd-server 正常，则需要检查 tikv-server 机器和 pd-server 对应端口之间的连通性， - 确保网段连通且对应服务端口已添加到防火墙白名单中，可通过 nc 或 curl 工具检查。具体命令参考上一节。 - -+ 文件被占用 - - 不要在一个数据库文件目录上打开两个 tikv。 - -## pd-server 启动报错 - -+ 启动参数错误 - - 请参考[PD 命令行参数](/v3.1/reference/configuration/pd-server/configuration.md)文档。 - -+ 端口被占用：`lsof -i:port` - - 请确保 pd-server 启动所需要的端口未被占用：`lsof -i:port`。 - -## TiDB/TiKV/PD 进程异常退出 - -+ 进程是否是启动在前台 - - 当前终端退出给其所有子进程发送 HUP 信号，从而导致进程退出。 - -+ 是否是在命令行用过 `nohup+&` 方式直接运行 - - 这样依然可能导致进程因终端连接突然中断，作为终端 SHELL 的子进程被杀掉。 - - 推荐将启动命令写在脚本中，通过脚本运行（相当于二次 fork 启动）。 - -## TiKV 进程异常重启 - -+ 检查 dmesg 或者 syslog 里面是否有 OOM 信息 - - 如果有 OOM 信息并且杀掉的进程为 TiKV，请减少 TiKV 的 RocksDB 的各个 CF 的 `block-cache-size` 值。 - -+ 检查 TiKV 日志是否有 panic 的 log - - 提交 Issue 并附上 panic 的 log。 - -## TiDB panic - -请提供 panic 的 log。 - -## 连接被拒绝 - -+ 请确保操作系统的网络参数正确，包括但不限于 - - 连接字符串中的端口和 tidb-server 启动的端口需要一致 - - 请保证防火墙的配置正确 - -## Too many open files - -在启动进程之前，请确保 `ulimit -n` 的结果足够大，推荐设为 unlimited 或者是大于 1000000。 - -## 数据库访问超时，系统负载高 - -首先检查 [SLOW-QUERY](/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息： - -+ 部署的拓扑结构 - - tidb-server/pd-server/tikv-server 部署了几个实例 - - 这些实例在机器上是如何分布的 -+ 机器的硬件配置 - - CPU 核数 - - 内存大小 - - 硬盘类型（SSD 还是机械硬盘） - - 是实体机还是虚拟机 -+ 机器上除了 TiDB 集群之外是否还有其他服务 -+ pd-server 和 tikv-server 是否分开部署 -+ 目前正在进行什么操作 -+ 用 `top -H` 命令查看当前占用 CPU 的线程名 -+ 最近一段时间的网络/IO 监控数据是否有异常 diff --git a/v3.1/how-to/troubleshoot/tidb-lightning.md b/v3.1/how-to/troubleshoot/tidb-lightning.md deleted file mode 100644 index ce1b1010d0b4..000000000000 --- a/v3.1/how-to/troubleshoot/tidb-lightning.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: TiDB Lightning 故障诊断 -category: reference ---- - -# TiDB Lightning 故障诊断 - -当 Lightning 遇到不可恢复的错误时便会异常退出，并在日志中记下错误原因。一般可在日志底部找到，也可以搜索 `[error]` 字符串找出中间发生的错误。本文主要描述一些常见的错误及其解决方法。 - -## 导入速度太慢 - -TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件，如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 `restore chunk … takes` 的记录，或者观察 Grafana 的监控信息。 - -导入速度太慢一般有几个原因： - -**原因 1**：`region-concurrency` 设定太高，线程间争用资源反而减低了效率。 - -1. 从日志的开头搜寻 `region-concurrency` 能知道 Lightning 读到的参数是多少。 -2. 如果 Lightning 与其他服务（如 Importer）共用一台服务器，必需**手动**将 `region-concurrency` 设为该服务器 CPU 数量的 75%。 -3. 如果 CPU 设有限额（例如从 Kubernetes 指定的上限），Lightning 可能无法自动判断出来，此时亦需要**手动**调整 `region-concurrency`。 - -**原因 2**：表结构太复杂。 - -每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 - -**原因 3**：Lightning 版本太旧。 - -试试最新的版本吧！可能会有改善。 - -## checksum failed: checksum mismatched remote vs local - -**原因**：本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因： - -1. 这张表可能本身已有数据，影响最终结果。 -2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。 -3. 如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如： - - * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。 - * 唯一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。 -4. 如果 TiDB Lightning 之前失败停机过，但没有正确重启，可能会因为数据不同步而出现校验和不一致。 - -**解决办法**： - -1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。 - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。 - -3. 参考[如何正确重启 TiDB Lightning](/v3.1/faq/tidb-lightning.md#如何正确重启-tidb-lightning)中的解决办法。 - -## Checkpoint for … has invalid status:（错误码） - -**原因**：[断点续传](/v3.1/reference/tools/tidb-lightning/checkpoints.md)已启用。Lightning 或 Importer 之前发生了异常退出。为了防止数据意外损坏，Lightning 在错误解决以前不会启动。 - -错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。 - -**解决办法**： - -如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。 - -{{< copyable "shell-regular" >}} - -```sh -tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all -``` - -其他解决方法请参考[断点续传的控制](/v3.1/reference/tools/tidb-lightning/checkpoints.md#断点续传的控制)。 - -## ResourceTemporarilyUnavailable("Too many open engines …: …") - -**原因**：并行打开的引擎文件 (engine files) 超出 `tikv-importer` 里的限制。这可能由配置错误引起。即使配置没问题，如果 `tidb-lightning` 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。 - -**解决办法**： - -1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为： - - 最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number` - -2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。 - -3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录： - - {{< copyable "shell-regular" >}} - - ```sh - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -## cannot guess encoding for input file, please convert to UTF-8 manually - -**原因**：Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如，因为在不同的环境运行过 `ALTER TABLE`，使表架构同时出现 UTF-8 和 GB-18030 的字符。 - -**解决办法**： - -1. 编辑数据源，保存为纯 UTF-8 或 GB-18030 的文件。 -2. 手动在目标数量库创建所有的表，然后设置 `[mydumper] no-schema = true` 跳过创建表的步骤。 -3. 设置 `[mydumper] character-set = "binary"` 跳过这个检查。但是这样可能使数据库出现乱码。 - -## [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 …}' - -**原因**: 一个 `timestamp` 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。 - -**解决办法**: - -1. 确保 Lightning 与数据源时区一致。 - - * 使用 Ansible 部署的话，修正 [`inventory.ini`] 下的 `timezone` 变量。 - - ```ini - # inventory.ini - [all:vars] - timezone = Asia/Shanghai - ``` - - * 手动部署的话，通过设定 `$TZ` 环境变量强制时区设定。 - - 强制使用 Asia/Shanghai 时区： - - {{< copyable "shell-regular" >}} - - ```sh - TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml - ``` - -2. 导出数据时，必须加上 `--skip-tz-utc` 选项。 - -3. 确保整个集群使用的是同一最新版本的 `tzdata` (2018i 或更高版本)。 - - 如果你使用的是 CentOS 机器，你可以运行 `yum info tzdata` 命令查看 `tzdata` 的版本及是否有更新。然后运行 `yum upgrade tzdata` 命令升级 `tzdata`。 diff --git a/v3.1/how-to/upgrade/from-previous-version.md b/v3.1/how-to/upgrade/from-previous-version.md deleted file mode 100644 index dcfd26a97acb..000000000000 --- a/v3.1/how-to/upgrade/from-previous-version.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: TiDB 3.1 升级操作指南 -category: how-to ---- - -# TiDB 3.1 升级操作指南 - -本文档适用于从 TiDB 2.0、2.1、3.0 版本升级至 TiDB 3.1 版本以及 TiDB 3.1 低版本升级至 TiDB 3.1 高版本。目前，TiDB 3.1 版本兼容 [TiDB Binlog Cluster 版本](/v3.1/reference/tidb-binlog/overview.md)。 - -## 升级兼容性说明 - -- 不支持在升级后回退至 2.1.x 或更旧版本 -- 从 2.0.6 之前的版本升级到 3.1 之前，需要确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 `Add Index` 操作，等 DDL 操作完成后再执行升级操作 -- 2.1 及之后版本启用了并行 DDL，早于 2.0.1 版本的集群，无法滚动升级到 3.1，可以选择下面两种方案： - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 3.1 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 3.1 版本 - -> **注意：** -> -> 在升级的过程中不要执行 DDL 请求，否则可能会出现行为未定义的问题。 - -## 在中控机器上安装 Ansible 及其依赖 - -> **注意：** -> -> 如果已经安装了 Ansible 及其依赖，可跳过该步骤。 - -TiDB Ansible release-3.1 版本依赖 2.4.2 及以上但不高于 2.7.11 的 Ansible 版本（`2.4.2 ≦ ansible ≦ 2.7.11`，建议 2.7.11 版本），另依赖 Python 模块：`jinja2 ≧ 2.9.6` 和 `jmespath ≧ 0.9.0`。为方便管理依赖，建议使用 `pip` 安装 Ansible 及其依赖，可参照[在中控机器上安装 Ansible 及其依赖](/v3.1/how-to/deploy/orchestrated/ansible.md#在中控机器上安装-ansible-及其依赖) 进行安装。离线环境参照[在中控机器上离线安装 Ansible 及其依赖](/v3.1/how-to/deploy/orchestrated/offline-ansible.md#在中控机器上离线安装-ansible-及其依赖)。 - -安装完成后，可通过以下命令查看版本： - -{{< copyable "shell-regular" >}} - -```bash -ansible --version -``` - -``` -ansible 2.7.11 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jinja2 -``` - -``` -Name: Jinja2 -Version: 2.10 -``` - -{{< copyable "shell-regular" >}} - -```bash -pip show jmespath -``` - -``` -Name: jmespath -Version: 0.9.0 -``` - -> **注意：** -> -> 请务必按以上文档安装 Ansible 及其依赖。确认 Jinja2 版本是否正确，否则启动 Grafana 时会报错。确认 jmespath 版本是否正确，否则滚动升级 TiKV 时会报错。 - -## 在中控机器上下载 TiDB Ansible - -以 `tidb` 用户登录中控机并进入 `/home/tidb` 目录，备份 TiDB 2.0、2.1、3.0 或 TiDB 3.1 低版本的 tidb-ansible 文件夹： - -{{< copyable "shell-regular" >}} - -```bash -mv tidb-ansible tidb-ansible-bak -``` - -下载 TiDB 3.1 版本对应 tag 的 tidb-ansible [**下载 TiDB Ansible**](/v3.1/how-to/deploy/orchestrated/ansible.md#在中控机器上下载-tidb-ansible)，默认的文件夹名称为 `tidb-ansible`。 - -{{< copyable "shell-regular" >}} - -```bash -git clone -b $tag https://github.com/pingcap/tidb-ansible.git -``` - -## 编辑 inventory.ini 文件和配置文件 - -以 `tidb` 用户登录中控机并进入 `/home/tidb/tidb-ansible` 目录。 - -### 编辑 `inventory.ini` 文件 - -编辑 `inventory.ini` 文件，IP 信息参照备份文件 `/home/tidb/tidb-ansible-bak/inventory.ini`。 - -以下变量配置，需要重点确认，变量含义可参考 [inventory.ini 变量调整](/v3.1/how-to/deploy/orchestrated/ansible.md#调整其它变量可选)。 - -1. 请确认 `ansible_user` 配置的是普通用户。为统一权限管理，不再支持使用 root 用户远程安装。默认配置中使用 `tidb` 用户作为 SSH 远程用户及程序运行用户。 - - ``` - ## Connection - # ssh via normal user - ansible_user = tidb - ``` - - 可参考[如何配置 SSH 互信及 sudo 规则](/v3.1/how-to/deploy/orchestrated/ansible.md#第-5-步在中控机上配置部署机器-ssh-互信及-sudo-规则)自动配置主机间互信。 - -2. `process_supervision` 变量请与之前版本保持一致，默认推荐使用 `systemd`。 - - ``` - # process supervision, [systemd, supervise] - process_supervision = systemd - ``` - - 如需变更，可参考[如何调整进程监管方式从 supervise 到 systemd](/v3.1/how-to/deploy/orchestrated/ansible.md#如何调整进程监管方式从-supervise-到-systemd)，先使用备份 `/home/tidb/tidb-ansible-bak/` 分支变更进程监管方式再升级。 - -### 编辑 TiDB 集群组件配置文件 - -如之前自定义过 TiDB 集群组件配置文件，请参照备份文件修改 `/home/tidb/tidb-ansible/conf` 下对应配置文件。 - -**注意以下参数变更：** - -- TiKV 配置中 `end-point-concurrency` 变更为 `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数： - - ``` - readpool: - coprocessor: - # Notice: if CPU_NUM > 8, default thread pool size for coprocessors - # will be set to CPU_NUM * 0.8. - # high-concurrency: 8 - # normal-concurrency: 8 - # low-concurrency: 8 - ``` - - > **注意：** - > - > 2.0 版本升级且单机多 TiKV 实例（进程）情况下，需要修改这三个参数。 - > - > 推荐设置：TiKV 实例数量 \* 参数值 = CPU 核心数量 \* 0.8 - -- TiKV 配置中不同 CF 中的 `block-cache-size` 参数变更为 `block-cache`： - - ``` - storage: - block-cache: - capacity: "1GB" - ``` - - > **注意：** - > - > 单机多 TiKV 实例（进程）情况下，需要修改 `capacity` 参数。 - > - > 推荐设置：`capacity` = (MEM_TOTAL * 0.5 / TiKV 实例数量) - -- TiKV 配置中单机多实例场景需要额外配置 `tikv_status_port` 端口： - - ``` - [tikv_servers] - TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" - TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" - TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" - TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" - TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" - TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3" - ``` - - > **注意：** - > - > 3.0 版本单机多 TiKV 实例（进程）情况下，需要添加 `tikv_status_port` 参数。 - > - > 配置前，注意检查端口是否有冲突。 - -## 下载 TiDB 3.1 binary 到中控机 - -确认 `tidb-ansible/inventory.ini` 文件中 `tidb_version = v3.1.x`，然后执行以下命令下载 TiDB 3.1 binary 到中控机。 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook local_prepare.yml -``` - -## 滚动升级 TiDB 集群组件 - -- 如果 `process_supervision` 变量使用默认的 `systemd` 参数： - - - 当前集群版本 < 3.0，则通过 `excessive_rolling_update.yml` 滚动升级 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook excessive_rolling_update.yml - ``` - - - 当前集群版本 ≥ 3.0.0，滚动升级及日常滚动重启 TiDB 集群，使用 `rolling_update.yml`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -- 如果 `process_supervision` 变量使用的是 `supervise` 参数，无论当前集群为哪个版本，均通过 `rolling_update.yml` 来滚动升级 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -## 滚动升级 TiDB 监控组件 - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook rolling_update_monitor.yml -``` diff --git a/v3.1/key-features.md b/v3.1/key-features.md deleted file mode 100644 index 4d739c036396..000000000000 --- a/v3.1/key-features.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: TiDB 核心特性 -category: introduction ---- - -# TiDB 核心特性 - -本文详细介绍 TiDB 的两大核心特性：水平扩展与高可用。 - -## 水平扩展 - -无限水平扩展是 TiDB 的一大特点，这里说的水平扩展包括两方面：计算能力和存储能力。TiDB Server 负责处理 SQL 请求，随着业务的增长，可以简单的添加 TiDB Server 节点，提高整体的处理能力，提供更高的吞吐。TiKV 负责存储数据，随着数据量的增长，可以部署更多的 TiKV Server 节点解决数据 Scale 的问题。PD 会在 TiKV 节点之间以 Region 为单位做调度，将部分数据迁移到新加的节点上。所以在业务的早期，可以只部署少量的服务实例（推荐至少部署 3 个 TiKV， 3 个 PD，2 个 TiDB），随着业务量的增长，按照需求添加 TiKV 或者 TiDB 实例。 - -## 高可用 - -高可用是 TiDB 的另一大特点，TiDB/TiKV/PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。下面分别说明这三个组件的可用性、单个实例失效后的后果以及如何恢复。 - -- TiDB - - TiDB 是无状态的，推荐至少部署两个实例，前端通过负载均衡组件对外提供服务。当单个实例失效时，会影响正在这个实例上进行的 Session，从应用的角度看，会出现单次请求失败的情况，重新连接后即可继续获得服务。单个实例失效后，可以重启这个实例或者部署一个新的实例。 - -- PD - - PD 是一个集群，通过 Raft 协议保持数据的一致性，单个实例失效时，如果这个实例不是 Raft 的 leader，那么服务完全不受影响；如果这个实例是 Raft 的 leader，会重新选出新的 Raft leader，自动恢复服务。PD 在选举的过程中无法对外提供服务，这个时间大约是3秒钟。推荐至少部署三个 PD 实例，单个实例失效后，重启这个实例或者添加新的实例。 - -- TiKV - - TiKV 是一个集群，通过 Raft 协议保持数据的一致性（副本数量可配置，默认保存三副本），并通过 PD 做负载均衡调度。单个节点失效时，会影响这个节点上存储的所有 Region。对于 Region 中的 Leader 节点，会中断服务，等待重新选举；对于 Region 中的 Follower 节点，不会影响服务。当某个 TiKV 节点失效，并且在一段时间内（默认 30 分钟）无法恢复，PD 会将其上的数据迁移到其他的 TiKV 节点上。 diff --git a/v3.1/overview.md b/v3.1/overview.md deleted file mode 100644 index d8f775c7fcb9..000000000000 --- a/v3.1/overview.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: TiDB 简介 -category: introduction ---- - -# TiDB 简介 - -TiDB 是 PingCAP 公司设计的开源分布式 HTAP (Hybrid Transactional and Analytical Processing) 数据库，结合了传统的 RDBMS 和 NoSQL 的最佳特性。TiDB 兼容 MySQL，支持无限的水平扩展，具备强一致性和高可用性。TiDB 的目标是为 OLTP (Online Transactional Processing) 和 OLAP (Online Analytical Processing) 场景提供一站式的解决方案。 - -TiDB 具备如下特性： - -- 高度兼容 MySQL - - [大多数情况下](/v3.1/reference/mysql-compatibility.md)，无需修改代码即可从 MySQL 轻松迁移至 TiDB，分库分表后的 MySQL 集群亦可通过 TiDB 工具进行实时迁移。 - -- 水平弹性扩展 - - 通过简单地增加新节点即可实现 TiDB 的水平扩展，按需扩展吞吐或存储，轻松应对高并发、海量数据场景。 - -- 分布式事务 - - TiDB 100% 支持标准的 ACID 事务。 - -- 真正金融级高可用 - - 相比于传统主从 (M-S) 复制方案，基于 Raft 的多数派选举协议可以提供金融级的 100% 数据强一致性保证，且在不丢失大多数副本的前提下，可以实现故障的自动恢复 (auto-failover)，无需人工介入。 - -- 一站式 HTAP 解决方案 - - TiDB 作为典型的 OLTP 行存数据库，同时兼具强大的 OLAP 性能，配合 TiSpark，可提供一站式 HTAP 解决方案，一份存储同时处理 OLTP & OLAP，无需传统繁琐的 ETL 过程。 - -- 云原生 SQL 数据库 - - TiDB 是为云而设计的数据库，支持公有云、私有云和混合云，配合 [TiDB Operator 项目](/v3.1/tidb-in-kubernetes/tidb-operator-overview.md) 可实现自动化运维，使部署、配置和维护变得十分简单。 - -TiDB 的设计目标是 100% 的 OLTP 场景和 80% 的 OLAP 场景，更复杂的 OLAP 分析可以通过 [TiSpark 项目](/v3.1/reference/tispark.md)来完成。 - -TiDB 对业务没有任何侵入性，能优雅的替换传统的数据库中间件、数据库分库分表等 Sharding 方案。同时它也让开发运维人员不用关注数据库 Scale 的细节问题，专注于业务开发，极大的提升研发的生产力。 - -三篇文章了解 TiDB 技术内幕： - -- [说存储](https://pingcap.com/blog-cn/tidb-internal-1/) -- [说计算](https://pingcap.com/blog-cn/tidb-internal-2/) -- [谈调度](https://pingcap.com/blog-cn/tidb-internal-3/) - -## 部署方式 - -TiDB 可以部署在本地和云平台上，支持公有云、私有云和混合云。你可以根据实际场景或需求，选择相应的方式来部署 TiDB 集群： - -- [使用 Ansible 部署](/v3.1/how-to/deploy/orchestrated/ansible.md)：如果用于生产环境，推荐使用 Ansible 部署 TiDB 集群。 -- [使用 Ansible 离线部署](/v3.1/how-to/deploy/orchestrated/offline-ansible.md)：如果部署环境无法访问网络，可使用 Ansible 进行离线部署。 -- [使用 TiDB Operator 部署](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md)：使用 TiDB Operator 在 Kubernetes 集群上部署生产就绪的 TiDB 集群，支持[部署到 AWS EKS](/v3.1/tidb-in-kubernetes/deploy/aws-eks.md)、[部署到谷歌云 GKE (beta)](/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md)、[部署到阿里云 ACK](/v3.1/tidb-in-kubernetes/deploy/alibaba-cloud.md) 等。 -- [使用 Docker Compose 部署](/v3.1/how-to/get-started/deploy-tidb-from-docker-compose.md)：如果你只是想测试 TiDB、体验 TiDB 的特性，或者用于开发环境，可以使用 Docker Compose 在本地快速部署 TiDB 集群。该部署方式不适用于生产环境。 -- [使用 Docker 部署](/v3.1/how-to/deploy/orchestrated/docker.md)：你可以使用 Docker 部署 TiDB 集群，但该部署方式不适用于生产环境。 -- [使用 TiDB Operator 部署到 Minikube](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：你可以使用 TiDB Opeartor 将 TiDB 集群部署到本地 Minikube 启动的 Kubernetes 集群中。该部署方式不适用于生产环境。 -- [使用 TiDB Operator 部署到 kind](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：你可以使用 TiDB Operator 将 TiDB 集群部署到以 kind 方式启动的 Kubernetes 本地集群中。该部署方式不适用于生产环境。 - -## 项目源码 - -TiDB 集群所有组件的源码均可从 GitHub 上直接访问： - -- [TiDB](https://github.com/pingcap/tidb) -- [TiKV](https://github.com/tikv/tikv) -- [PD](https://github.com/pingcap/pd) -- [TiSpark](https://github.com/pingcap/tispark) -- [TiDB Operator](https://github.com/pingcap/tidb-operator) diff --git a/v3.1/reference/alert-rules.md b/v3.1/reference/alert-rules.md deleted file mode 100644 index 6b16b3ad38b5..000000000000 --- a/v3.1/reference/alert-rules.md +++ /dev/null @@ -1,1161 +0,0 @@ ---- -title: TiDB 集群报警规则 -summary: TiDB 集群中各组件的报警规则详解。 -category: reference ---- - -# TiDB 集群报警规则 - -本文介绍了 TiDB 集群中各组件的报警规则，包括 TiDB、TiKV、PD、TiDB Binlog、Node_exporter 和 Blackbox_exporter 的各报警项的规则描述及处理方法。 - -## TiDB 报警规则 - -本节介绍了 TiDB 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_schema_error` - -* 报警规则： - - `increase(tidb_session_schema_lease_error_total{type="outdated"}[15m]) > 0` - -* 规则描述： - - TiDB 在一个 Lease 时间内没有重载到最新的 Schema 信息。如果 TiDB 无法继续对外提供服务，则报警。 - -* 处理方法： - - 该问题通常由于 TiKV Region 不可用或超时导致，需要看 TiKV 的监控指标定位问题。 - -#### `TiDB_tikvclient_region_err_total` - -* 报警规则： - - `increase(tidb_tikvclient_region_err_total[10m]) > 6000` - -* 规则描述： - - TiDB 访问 TiKV 时发生了 Region 错误。如果在 10 分钟之内该错误多于 6000 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_domain_load_schema_total` - -* 报警规则： - - `increase(tidb_domain_load_schema_total{type="failed"}[10m]) > 10` - -* 规则描述： - - TiDB 重载最新的 Schema 信息失败的总次数。如果在 10 分钟之内重载失败次数超过 10 次，则报警。 - -* 处理方法： - - 参考 [`TiDB_schema_error`](#tidb_schema_error) 的处理方法。 - -#### `TiDB_monitor_keep_alive` - -* 报警规则： - - `increase(tidb_monitor_keep_alive_total[10m]) < 100` - -* 规则描述： - - 表示 TiDB 的进程是否仍然存在。如果在 10 分钟之内 `tidb_monitor_keep_alive_total` 增加次数少于 100，则 TiDB 的进程可能已经退出，此时会报警。 - -* 处理方法： - - * 检查 TiDB 进程是否 OOM。 - * 检查机器是否发生了重启。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiDB_server_panic_total` - -* 报警规则： - - `increase(tidb_server_panic_total[10m]) > 0` - -* 规则描述： - - 发生崩溃的 TiDB 线程的数量。当出现崩溃的时候会报警。该线程通常会被恢复，否则 TiDB 会频繁重启。 - -* 处理方法： - - 收集 panic 日志，定位原因。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiDB_memory_abnormal` - -* 报警规则： - - `go_memstats_heap_inuse_bytes{job="tidb"} > 1e+10` - -* 规则描述： - - 对 TiDB 内存使用量的监控。如果内存使用大于 10 G，则报警。 - -* 处理方法： - - 通过 HTTP API 来排查 goroutine 泄露的问题。 - -#### `TiDB_query_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tidb_server_handle_query_duration_seconds_bucket[1m])) BY (le, instance)) > 1` - -* 规则描述： - - TiDB 处理请求的延时。如果 .99 的延迟大于 1 秒，则报警。 - -* 处理方法： - - 查看 TiDB 的日志，搜索 SLOW_QUERY 和 TIME_COP_PROCESS 关键字，查找慢 SQL。 - -#### `TiDB_server_event_error` - -* 报警规则： - - `increase(tidb_server_event_total{type=~"server_start|server_hang"}[15m]) > 0` - -* 规则描述： - - TiDB 服务中发生的事件数量。当出现以下事件的时候会报警： - - 1. start：TiDB 服务启动。 - 2. hang：当发生了 Critical 级别的事件时（目前只有 Binlog 写不进去一种情况），TiDB 进入 `hang` 模式，并等待人工 Kill。 - -* 处理方法： - - * 重启 TiDB 以恢复服务。 - * 检查 TiDB Binlog 服务是否正常。 - -#### `TiDB_tikvclient_backoff_total` - -* 报警规则： - - `increase(tidb_tikvclient_backoff_total[10m]) > 10` - -* 规则描述： - - TiDB 访问 TiKV 发生错误时发起重试的次数。如果在 10 分钟之内重试次数多于 10 次，则报警。 - -* 处理方法： - - 查看 TiKV 的监控状态。 - -#### `TiDB_monitor_time_jump_back_error` - -* 报警规则： - - `increase(tidb_monitor_time_jump_back_total[10m]) > 0` - -* 规则描述： - - 如果 TiDB 所在机器的时间发生了回退，则报警。 - -* 处理方法： - - 排查 NTP 配置。 - -#### `TiDB_ddl_waiting_jobs` - -* 报警规则： - - `sum(tidb_ddl_waiting_jobs) > 5` - -* 规则描述： - - 如果 TiDB 中等待执行的 DDL 任务的数量大于 5，则报警。 - -* 处理方法： - - 通过 `admin show ddl` 语句检查是否有耗时的 add index 操作正在执行。 - -## PD 报警规则 - -本节介绍了 PD 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `PD_cluster_offline_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_down_count"}) > 0` - -* 规则描述： - - PD 长时间（默认配置是 30 分钟）没有收到 TiKV 心跳。 - -* 处理方法： - - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `PD_etcd_write_disk_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[1m])) by (instance,job,le)) > 1` - -* 规则描述： - - etcd 写盘慢，这很容易引起 PD leader 超时或者 TSO 无法及时存盘等问题，从而导致整个集群停止服务。 - -* 处理方法： - - * 排查写入慢的原因。可能是由于其他服务导致系统负载过高。可以检查 PD 本身是否占用了大量 CPU 或 IO 资源。 - * 可尝试重启 PD 或手动 transfer leader 至其他的 PD 来恢复服务。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_miss_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="miss_peer_region_count"}) > 100` - -* 规则描述： - - Region 的副本数小于 `max-replicas` 配置的值。这通常是由于 TiKV 宕机等问题导致一段时间内一些 Region 缺副本，下线 TiKV 节点也会导致少量 Region 缺副本（对于有 pending peer 的 Region 会走先减后加的流程）。 - -* 处理方法： - - * 查看是否有 TiKV 宕机或在做下线操作，尝试定位问题产生的原因。 - * 观察 region health 面板，查看 `miss_peer_region_count` 是否在不断减少。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `PD_cluster_lost_connect_tikv_nums` - -* 报警规则： - - `sum(pd_cluster_status{type="store_disconnected_count"}) > 0` - -* 规则描述： - - PD 在 20 秒之内未收到 TiKV 上报心跳。正常情况下是每 10 秒收到 1 次心跳。 - -* 处理方法： - - * 排查是否在重启 TiKV。 - * 检查 TiKV 进程是否正常、网络是否隔离以及负载是否过高，并尽可能地恢复服务。 - * 如果确定 TiKV 无法恢复，可做下线处理。 - * 如果确定 TiKV 可以恢复，但在短时间内还无法恢复，可以考虑延长 `max-down-time` 配置，防止超时后 TiKV 被判定为无法恢复并开始搬移数据。 - -#### `PD_cluster_low_space` - -* 报警规则： - - `sum(pd_cluster_status{type="store_low_space_count"}) > 0` - -* 规则描述： - - 表示 TiKV 节点空间不足。 - -* 处理方法： - - * 检查集群中的空间是否普遍不足。如果是，则需要扩容。 - * 检查 Region balance 调度是否有问题。如果有问题，会导致数据分布不均衡。 - * 检查是否有文件占用了大量磁盘空间，比如日志、快照、core dump 等文件。 - * 降低该节点的 Region weight 来减少数据量。 - * 无法释放空间时，可以考虑主动下线该节点，防止由于磁盘空间不足而宕机。 - -#### `PD_etcd_network_peer_latency` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(etcd_network_peer_round_trip_time_seconds_bucket[1m])) by (To,instance,job,le)) > 1` - -* 规则描述： - - PD 节点之间网络延迟高，严重情况下会导致 leader 超时和 TSO 存盘超时，从而影响集群服务。 - -* 处理方法： - - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `PD_tidb_handle_requests_duration` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(pd_client_request_handle_requests_duration_seconds_bucket{type="tso"}[1m])) by (instance,job,le)) > 0.1` - -* 规则描述： - - PD 处理 TSO 请求耗时过长，一般是由于负载过高。 - -* 处理方法： - - * 检查服务器负载状况。 - * 使用 pprof 抓取 PD 的 CPU profile 进行分析。 - * 手动切换 PD leader。 - * 如果是环境问题，则将有问题的 PD 下线替换。 - -#### `PD_down_peer_region_nums` - -* 报警规则： - - `sum(pd_regions_status{type="down_peer_region_count"}) > 0` - -* 规则描述： - - Raft leader 上报有不响应 peer 的 Region 数量。 - -* 处理方法： - - * 检查是否有 TiKV 宕机，或刚发生重启，或者繁忙。 - * 观察 region health 面板，检查 `down_peer_region_count` 是否在不断减少。 - * 检查是否有 TiKV 之间网络不通。 - -#### `PD_pending_peer_region_count` - -* 报警规则： - - `sum(pd_regions_status{type="pending_peer_region_count"}) > 100` - -* 规则描述： - - Raft log 落后的 Region 过多。由于调度产生少量的 pending peer 是正常的，但是如果持续很高，就可能有问题。 - -* 处理方法： - - * 观察 region health 面板，检查 `pending_peer_region_count` 是否在不断减少。 - * 检查 TiKV 之间的网络状况，特别是带宽是否足够。 - -#### `PD_leader_change` - -* 报警规则： - - `count(changes(pd_server_tso{type="save"}[10m]) > 0) >= 2` - -* 规则描述： - - 近期发生了 PD leader 切换。 - -* 处理方法： - - * 排除人为因素，比如重启 PD、手动 transfer leader 或调整 leader 优先级等。 - * 检查网络状况和系统负载情况。 - * 如果由于环境原因无法恢复，可将有问题的 PD 下线替换。 - -#### `TiKV_space_used_more_than_80%` - -* 报警规则： - - `sum(pd_cluster_status{type="storage_size"}) / sum(pd_cluster_status{type="storage_capacity"}) * 100 > 80` - -* 规则描述： - - 集群空间占用超过 80%。 - -* 处理方法： - - * 确认是否需要扩容。 - * 排查是否有文件占用了大量磁盘空间，比如日志、快照或 core dump等文件。 - -#### `PD_system_time_slow` - -* 报警规则： - - `changes(pd_server_tso{type="system_time_slow"}[10m]) >= 1` - -* 规则描述： - - 系统时间可能发生回退。 - -* 处理方法： - - 检查系统时间设置是否正确。 - -#### `PD_no_store_for_making_replica` - -* 报警规则： - - `increase(pd_checker_event_count{type="replica_checker", name="no_target_store"}[1m]) > 0` - -* 规则描述： - - 没有合适的 store 用来补副本。 - -* 处理方法： - - * 检查 store 是否空间不足。 - * 根据 label 配置（如果有这个配置的话）来检查是否有可以补副本的 store。 - -## TiKV 报警规则 - -本节介绍了 TiKV 组件的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiKV_memory_used_too_fast` - -* 报警规则： - - `process_resident_memory_bytes{job=~"tikv",instance=~".*"} - (process_resident_memory_bytes{job=~"tikv",instance=~".*"} offset 5m) > 5*1024*1024*1024` - -* 规则描述： - - 目前没有和内存相关的 TiKV 的监控，你可以通过 Node_exporter 监控集群内机器的内存使用情况。如上规则表示，如果在 5 分钟之内内存使用超过 5GB（TiKV 内存占用的太快），则报警。 - -* 处理方法： - - 调整 `rockdb.defaultcf` 和 `rocksdb.writecf` 的 `block-cache-size` 的大小。 - -#### `TiKV_GC_can_not_work` - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="success"}[6h])) < 1` - - > **注意：** - > - > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 - -* 规则描述： - - 在 6 小时内 Region 上没有成功执行 GC，说明 GC 不能正常工作了。短期内 GC 不运行不会造成太大的影响，但如果 GC 一直不运行，版本会越来越多，从而导致查询变慢。 - -* 处理方法： - - 1. 执行 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME="tikv_gc_leader_desc"` 来找到 gc leader 对应的 `tidb-server`； - 2. 查看该 `tidb-server` 的日志，grep gc_worker tidb.log； - 3. 如果发现这段时间一直在 resolve locks（最后一条日志是 `start resolve locks`）或者 delete ranges（最后一条日志是 `start delete {number} ranges`），说明 GC 进程是正常的。否则需要报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `TiKV_server_report_failure_msg_total` - -* 报警规则： - - `sum(rate(tikv_server_report_failure_msg_total{type="unreachable"}[10m])) BY (store_id) > 10` - -* 规则描述： - - 表明无法连接远端的 TiKV。 - -* 处理方法： - - 1. 检查网络是否通畅。 - 2. 检查远端 TiKV 是否挂掉。 - 3. 如果远端 TiKV 没有挂掉，检查压力是否太大，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 处理方法。 - -#### `TiKV_channel_full_total` - -* 报警规则： - - `sum(rate(tikv_channel_full_total[10m])) BY (type, instance) > 0` - -* 规则描述： - - 该错误通常是因为 Raftstore 线程卡死，TiKV 的压力已经非常大了。 - -* 处理方法： - - 1. 观察 Raft Propose 监控，看这个报警的 TiKV 节点是否明显有比其他 TiKV 高很多。如果是，表明这个 TiKV 上有热点，需要检查热点调度是否能正常工作。 - 2. 观察 Raft IO 监控，看延迟是否升高。如果延迟很高，表明磁盘可能有瓶颈。一个能缓解但不怎么安全的办法是将 `sync-log` 改成 `false`。 - 3. 观察 Raft Process 监控，看 tick duration 是否很高。如果是，需要在 `[raftstore]` 配置下加上 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_write_stall` - -* 报警规则： - - `delta(tikv_engine_write_stall[10m]) > 0` - -* 规则描述： - - RocksDB 写入压力太大，出现了 stall。 - -* 处理方法： - - 1. 观察磁盘监控，排除磁盘问题。 - 2. 看 TiKV 是否有写入热点。 - 3. 在 `[rocksdb]` 和 `[raftdb]` 配置下调大 `max-sub-compactions` 的值。 - -#### `TiKV_raft_log_lag` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_log_lag_bucket[1m])) by (le, instance)) > 5000` - -* 规则描述： - - 这个值偏大，表明 Follower 已经远远落后于 Leader，Raft 没法正常同步了。可能的原因是 Follower 所在的 TiKV 卡住或者挂掉了。 - -#### `TiKV_async_request_snapshot_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="snapshot"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raftstore 负载压力很大，可能已经卡住。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_async_request_write_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_storage_engine_async_request_duration_seconds_bucket{type="write"}[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - 这个值偏大，表明 Raft write 耗时很长。 - -* 处理方法： - - 1. 检查 Raftstore 上的压力，参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 检查 apply worker 线程的压力。 - -#### `TiKV_coprocessor_request_wait_seconds` - -* 报警规则： - - `histogram_quantile(0.9999, sum(rate(tikv_coprocessor_request_wait_seconds_bucket[1m])) by (le, instance, req)) > 10` - -* 规则描述： - - 这个值偏大，表明 Coprocessor worker 压力很大。可能有比较慢的任务卡住了 Coprocessor 线程。 - -* 处理方法： - - 1. 从 TiDB 日志中查看慢查询日志，看查询是否用到了索引或全表扫，或者看是否需要做 analyze。 - 2. 排查是否有热点。 - 3. 查看 Coprocessor 监控，看 `coporcessor table/index scan` 里 `total` 和 `process` 是否匹配。如果相差太大，表明做了太多的无效查询。看是否有 `over seek bound`，如果有，表明版本太多，GC 工作不及时，需要增大并行 GC 的线程数。 - -#### `TiKV_raftstore_thread_cpu_seconds_total` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"raftstore_.*"}[1m])) by (instance, name) > 1.6` - -* 规则描述： - - Raftstore 线程压力太大。 - -* 处理方法： - - 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - -#### `TiKV_raft_append_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_append_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 append Raft log 的耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_raft_apply_log_duration_secs` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_apply_log_duration_seconds_bucket[1m])) by (le, instance)) > 1` - -* 规则描述： - - 表示 apply Raft log 耗时，如果高，通常是因为 IO 太忙了。 - -#### `TiKV_scheduler_latch_wait_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_latch_wait_duration_seconds_bucket[1m])) by (le, instance, type)) > 1` - -* 规则描述： - - Scheduler 中写操作获取内存锁时的等待时间。如果这个值高，表明写操作冲突较多，也可能是某些引起冲突的操作耗时较长，阻塞了其它等待相同锁的操作。 - -* 处理方法： - - 1. 查看 Scheduler-All 监控中的 scheduler command duration，看哪一个命令耗时最大。 - 2. 查看 Scheduler-All 监控中的 scheduler scan details，看 `total` 和 `process` 是否匹配。如果相差太大，表明有很多无效的扫描，另外观察是否有 `over seek bound`，如果太多，表明 GC 不及时。 - 3. 查看 Storage 监控中的 storage async snapshot/write duration，看是否 Raft 操作不及时。 - -#### `TiKV_thread_apply_worker_cpu_seconds` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name="apply_worker"}[1m])) by (instance) > 1.8` - -* 规则描述： - - Apply Raft log 线程压力太大，通常是因为写入太猛了。 - -#### `TiDB_tikvclient_gc_action_fail`（基本不发生，只在特殊配置下才会发生） - -* 报警规则： - - `sum(increase(tidb_tikvclient_gc_action_result{type="fail”}[1m])) > 10` - - > **注意：** - > - > 由于 3.0 中引入了分布式 GC 且 GC 不会在 TiDB 执行，因此 `tidb_tikvclient_gc_action_result` 指标虽然在 3.* 以上版本中存在，但是不会有值。 - -* 规则描述： - - GC 失败的 Region 较多。 - -* 处理方法： - - 1. 一般是因为并行 GC 开的太高了，可以适当降低 GC 并行度。你需要先确认 GC 失败是由于服务器繁忙导致的。 - 2. 通过执行 `update set VARIABLE_VALUE=”{number}” where VARIABLE_NAME=”tikv_gc_concurrency”` 适当降低并行度。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `TiKV_leader_drops` - -* 报警规则： - - `delta(tikv_pd_heartbeat_tick_total{type="leader"}[30s]) < -10` - -* 规则描述： - - 该问题通常是因为 Raftstore 线程卡住了。 - -* 处理方法： - - 1. 参考 [`TiKV_channel_full_total`](#tikv_channel_full_total) 的处理方法。 - 2. 如果 TiKV 压力很小，考虑 PD 的调度是否太频繁。可以查看 PD 页面的 Operator Create 面板，排查 PD 产生调度的类型和数量。 - -#### `TiKV_raft_process_ready_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type='ready'}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft ready 的耗时。这个值大，通常是因为 append log 任务卡住了。 - -#### `TiKV_raft_process_tick_duration_secs` - -* 报警规则： - - `histogram_quantile(0.999, sum(rate(tikv_raftstore_raft_process_duration_secs_bucket{type=’tick’}[1m])) by (le, instance, type)) > 2` - -* 规则描述： - - 表示处理 Raft tick 的耗时，这个值大，通常是因为 Region 太多导致的。 - -* 处理方法： - - 1. 考虑使用更高等级的日志，比如 `warn` 或者 `error`。 - 2. 在 `[raftstore]` 配置下添加 `raft-base-tick-interval = “2s”`。 - -#### `TiKV_scheduler_context_total` - -* 报警规则： - - `abs(delta( tikv_scheduler_context_total[5m])) > 1000` - -* 规则描述： - - Scheduler 正在执行的写命令数量。这个值高，表示任务完成得不及时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_scheduler_command_duration_seconds` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_scheduler_command_duration_seconds_bucket[1m])) by (le, instance, type) / 1000) > 1` - -* 规则描述： - - 表明 Scheduler 执行命令的耗时。 - -* 处理方法： - - 参考 [`TiKV_scheduler_latch_wait_duration_seconds`](#tikv_scheduler_latch_wait_duration_seconds) 的处理方法。 - -#### `TiKV_coprocessor_outdated_request_wait_seconds` - -* 报警规则： - - `delta(tikv_coprocessor_outdated_request_wait_seconds_count[10m]) > 0` - -* 规则描述： - - Coprocessor 已经过期的请求等待的时间。这个值高，表示 Coprocessor 压力已经非常大了。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_coprocessor_request_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason!="lock"}[10m]) > 100` - -* 规则描述： - - Coprocessor 的请求错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”和“full”等。“outdated”表示请求超时，很可能是由于排队时间过久，或者单个请求的耗时比较长。“full”表示 Coprocessor 的请求队列已经满了，可能是正在执行的请求比较耗时，导致新来的请求都在排队。耗时比较长的查询需要查看下对应的执行计划是否正确。 - -#### `TiKV_coprocessor_request_lock_error` - -* 报警规则： - - `increase(tikv_coprocessor_request_error{reason="lock"}[10m]) > 10000` - -* 规则描述： - - Coprocessor 请求锁的错误。 - -* 处理方法： - - Coprocessor 错误的主要原因分为“lock”、“outdated”、“full”等。“lock”表示读到的数据正在写入，需要等待一会再读（TiDB 内部会自动重试）。少量这种错误不用关注，如果有大量这种错误，需要查看写入和查询是否有冲突。 - -#### `TiKV_coprocessor_pending_request` - -* 报警规则： - - `delta(tikv_coprocessor_pending_request[10m]) > 5000` - -* 规则描述： - - Coprocessor 排队的请求。 - -* 处理方法： - - 参考 [`TiKV_coprocessor_request_wait_seconds`](#tikv_coprocessor_request_wait_seconds) 的处理方法。 - -#### `TiKV_batch_request_snapshot_nums` - -* 报警规则： - - `sum(rate(tikv_thread_cpu_seconds_total{name=~"cop_.*"}[1m])) by (instance) / (count(tikv_thread_cpu_seconds_total{name=~"cop_.*"}) * 0.9) / count(count(tikv_thread_cpu_seconds_total) by (instance)) > 0` - -* 规则描述： - - 某个 TiKV 的 Coprocessor CPU 使用率超过了 90%。 - -#### `TiKV_pending_task` - -* 报警规则： - - `sum(tikv_worker_pending_task_total) BY (instance,name) > 1000` - -* 规则描述： - - TiKV 等待的任务数量。 - -* 处理方法： - - 查看是哪一类任务的值偏高，通常 Coprocessor、apply worker 这类任务都可以在其他指标里找到解决办法。 - -#### `TiKV_low_space_and_add_region` - -* 报警规则： - - `count((sum(tikv_store_size_bytes{type="available"}) by (instance) / sum(tikv_store_size_bytes{type="capacity"}) by (instance) < 0.2) and (sum(tikv_raftstore_snapshot_traffic_total{type="applying"}) by (instance) > 0)) > 0` - -#### `TiKV_approximate_region_size` - -* 报警规则： - - `histogram_quantile(0.99, sum(rate(tikv_raftstore_region_size_bucket[1m])) by (le)) > 1073741824` - -* 规则描述： - - TiKV split checker 扫描到的最大的 Region approximate size 在 1 分钟内持续大于 1 GB。 - -* 处理方法： - - Region 分裂的速度不及写入的速度。为缓解这种情况，建议更新到支持 batch-split 的版本 (>= 2.1.0-rc1)。如暂时无法更新，可以使用 `pd-ctl operator add split-region --policy=approximate` 手动分裂 Region。 - -## TiDB Binlog 报警规则 - -关于 TiDB Binlog 报警规则的详细描述，参见 [TiDB Binlog 集群监控报警文档](/v3.1/reference/tidb-binlog/monitor.md#监控报警规则)。 - -## Node_exporter 主机报警规则 - -本节介绍了 Node_exporter 主机的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `NODE_disk_used_more_than_80%` - -* 报警规则： - - `node_filesystem_avail{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} / node_filesystem_size{fstype=~"(ext.|xfs)", mountpoint!~"/boot"} * 100 <= 20` - -* 规则描述： - - 机器磁盘空间使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -h` 命令，查看磁盘空间使用率，做好扩容计划。 - -#### `NODE_disk_inode_more_than_80%` - -* 报警规则： - - `node_filesystem_files_free{fstype=~"(ext.|xfs)"} / node_filesystem_files{fstype=~"(ext.|xfs)"} * 100 < 20` - -* 规则描述： - - 机器磁盘挂载目录文件系统 inode 使用率超过 80%。 - -* 处理方法： - - 登录机器，执行 `df -i` 命令，查看磁盘挂载目录文件系统 inode 使用率，做好扩容计划。 - -#### `NODE_disk_readonly` - -* 报警规则： - - `node_filesystem_readonly{fstype=~"(ext.|xfs)"} == 1` - -* 规则描述： - - 磁盘挂载目录文件系统只读，无法写入数据，一般是因为磁盘故障或文件系统损坏。 - -* 处理方法： - - * 登录机器创建文件测试是否正常。 - * 检查该服务器硬盘指示灯是否正常，如异常，需更换磁盘并修复该机器文件系统。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `NODE_memory_used_more_than_80%` - -* 报警规则： - - `(((node_memory_MemTotal-node_memory_MemFree-node_memory_Cached)/(node_memory_MemTotal)*100)) >= 80` - -* 规则描述： - - 机器内存使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node Exporter 页面查看该主机的 Memory 面板，检查 `Used` 是否过高，`Available` 内存是否过低。 - * 登录机器，执行 `free -m` 命令查看内存使用情况，执行 `top` 看是否有异常进程的内存使用率过高。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `NODE_node_overload` - -* 报警规则： - - `(node_load5 / count without (cpu, mode) (node_cpu{mode="system"})) > 1` - -* 规则描述： - - 机器 CPU 负载较高。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_cpu_used_more_than_80%` - -* 报警规则： - - `avg(irate(node_cpu{mode="idle"}[5m])) by(instance) * 100 <= 20` - -* 规则描述： - - 机器 CPU 使用率超过 80%。 - -* 处理方法： - - * 在 Grafana Node exporter 页面上查看该主机的 CPU Usage 及 Load Average，检查是否过高。 - * 登录机器，执行 `top` 查看 load average 及 CPU 使用率，看是否是异常进程的 CPU 使用率过高。 - -#### `NODE_tcp_estab_num_more_than_50000` - -* 报警规则： - - `node_netstat_Tcp_CurrEstab > 50000` - -* 规则描述： - - 机器 `establish` 状态的 TCP 链接超过 50,000。 - -* 处理方法： - - 登录机器执行 `ss -s` 可查看当前系统 `estab` 状态的 TCP 链接数，执行 `netstat` 查看是否有异常链接。 - -#### `NODE_disk_read_latency_more_than_32ms` - -* 报警规则： - - `((rate(node_disk_read_time_ms{device=~".+"}[5m]) / rate(node_disk_reads_completed{device=~".+"}[5m])) or (irate(node_disk_read_time_ms{device=~".+"}[5m]) / irate(node_disk_reads_completed{device=~".+"}[5m]))) > 32` - -* 规则描述： - - 磁盘读延迟超过 32 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板观察磁盘的读延迟。 - * 查看 Disk IO Utilization 面板观察 IO 使用率。 - -#### `NODE_disk_write_latency_more_than_16ms` - -* 报警规则： - - `((rate(node_disk_write_time_ms{device=~".+"}[5m]) / rate(node_disk_writes_completed{device=~".+"}[5m])) or (irate(node_disk_write_time_ms{device=~".+"}[5m]) / irate(node_disk_writes_completed{device=~".+"}[5m])))> 16` - -* 规则描述： - - 机器磁盘写延迟超过 16 毫秒。 - -* 处理方法： - - * 查看 Grafana Disk Performance Dashboard 观察磁盘使用情况。 - * 查看 Disk Latency 面板可查看磁盘的写延迟。 - * 查看 Disk IO Utilization 面板可查看 IO 使用率。 - -## Blackbox_exporter TCP、ICMP 和 HTTP 报警规则 - -本节介绍了 Blackbox_exporter TCP、ICMP 和 HTTP 的报警项。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别、重要级别、警告级别。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `TiDB_server_is_down` - -* 报警规则： - - `probe_success{group="tidb"} == 0` - -* 规则描述： - - TiDB 服务端口探测失败。 - -* 处理方法： - - * 检查 TiDB 服务所在机器是否宕机。 - * 检查 TiDB 进程是否存在。 - * 检查监控机与 TiDB 服务所在机器之间网络是否正常。 - -#### `Pump_server_is_down` - -* 报警规则： - - `probe_success{group="pump"} == 0` - -* 规则描述： - - Pump 服务端口探测失败。 - -* 处理方法： - - * 检查 Pump 服务所在机器是否宕机。 - * 检查 Pump 进程是否存在。 - * 检查监控机与 Pump 服务所在机器之间网络是否正常。 - -#### `Drainer_server_is_down` - -* 报警规则： - - `probe_success{group="drainer"} == 0` - -* 规则描述： - - Drainer 服务端口探测失败。 - -* 处理方法： - - * 检查 Drainer 服务所在机器是否宕机。 - * 检查 Drainer 进程是否存在。 - * 检查监控机与 Drainer 服务所在机器之间网络是否正常。 - -#### `TiKV_server_is_down` - -* 报警规则： - - `probe_success{group="tikv"} == 0` - -* 规则描述： - - TiKV 服务端口探测失败。 - -* 处理方法： - - * 检查 TiKV 服务所在机器是否宕机。 - * 检查 TiKV 进程是否存在。 - * 检查监控机与 TiKV 服务所在机器之间网络是否正常。 - -#### `PD_server_is_down` - -* 报警规则： - - `probe_success{group="pd"} == 0` - -* 规则描述： - - PD 服务端口探测失败。 - -* 处理方法： - - * 检查 PD 服务所在机器是否宕机。 - * 检查 PD 进程是否存在。 - * 检查监控机与 PD 服务所在机器之间网络是否正常。 - -#### `Node_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="node_exporter"} == 0` - -* 规则描述： - - Node_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Node_exporter 服务所在机器是否宕机。 - * 检查 Node_exporter 进程是否存在。 - * 检查监控机与 Node_exporter 服务所在机器之间网络是否正常。 - -#### `Blackbox_exporter_server_is_down` - -* 报警规则： - - `probe_success{group="blackbox_exporter"} == 0` - -* 规则描述： - - Blackbox_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Blackbox_exporter 服务所在机器是否宕机。 - * 检查 Blackbox_exporter 进程是否存在。 - * 检查监控机与 Blackbox_exporter 服务所在机器之间网络是否正常。 - -#### `Grafana_server_is_down` - -* 报警规则： - - `probe_success{group="grafana"} == 0` - -* 规则描述： - - Grafana 服务端口探测失败。 - -* 处理方法： - - * 检查 Grafana 服务所在机器是否宕机。 - * 检查 Grafana 进程是否存在。 - * 检查监控机与 Grafana 服务所在机器之间网络是否正常。 - -#### `Pushgateway_server_is_down` - -* 报警规则： - - `probe_success{group="pushgateway"} == 0` - -* 规则描述： - - Pushgateway 服务端口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -#### `Kafka_exporter_is_down` - -* 报警规则： - - `probe_success{group="kafka_exporter"} == 0` - -* 规则描述： - - Kafka_exporter 服务端口探测失败。 - -* 处理方法： - - * 检查 Kafka_exporter 服务所在机器是否宕机。 - * 检查 Kafka_exporter 进程是否存在。 - * 检查监控机与 Kafka_exporter 服务所在机器之间网络是否正常。 - -#### `Pushgateway_metrics_interface` - -* 报警规则： - - `probe_success{job="blackbox_exporter_http"} == 0` - -* 规则描述： - - Pushgateway 服务 http 接口探测失败。 - -* 处理方法： - - * 检查 Pushgateway 服务所在机器是否宕机。 - * 检查 Pushgateway 进程是否存在。 - * 检查监控机与 Pushgateway 服务所在机器之间网络是否正常。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `BLACKER_ping_latency_more_than_1s` - -* 报警规则： - - `max_over_time(probe_duration_seconds{job=~"blackbox_exporter.*_icmp"}[1m]) > 1` - -* 规则描述： - - Ping 延迟超过 1 秒。 - -* 处理方法： - - * 在 Grafana Blackbox Exporter dashboard 上检查两个节点间的 ping 延迟是否太高。 - * 在 Grafana Blackbox Exporter dashboard 的 tcp 面板上检查是否有丢包。 diff --git a/v3.1/reference/best-practices/grafana-monitor.md b/v3.1/reference/best-practices/grafana-monitor.md deleted file mode 100644 index e6cf4acbdac9..000000000000 --- a/v3.1/reference/best-practices/grafana-monitor.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 使用 Grafana 监控 TiDB 的最佳实践 -summary: 了解高效利用 Grafana 监控 TiDB 的七个技巧。 -category: reference ---- - -# 使用 Grafana 监控 TiDB 的最佳实践 - -[使用 TiDB Ansible 部署 TiDB 集群](/v3.1/how-to/deploy/orchestrated/ansible.md)时，会同时部署一套 [Grafana + Prometheus 的监控平台](/v3.1/how-to/monitor/overview.md)，用于收集和展示 TiDB 集群各个组件和机器的 metric 信息。本文主要介绍使用 TiDB 监控的最佳实践，旨在帮助 TiDB 用户高效利用丰富的 metric 信息来分析 TiDB 的集群状态或进行故障诊断。 - -## 监控架构 - -Prometheus 是一个拥有多维度数据模型和灵活查询语句的时序数据库。Grafana 是一个开源的 metric 分析及可视化系统。 - -![TiDB 监控整体架构](/media/prometheus-in-tidb.png) - -从 TiDB 2.1.3 版本开始，监控采用 pull 的方式，而之前版本采用的是 push 的方式，这是一个非常好的调整，它有以下几个优点： - -- 如果 Prometheus 需要迁移，无需重启整个 TiDB 集群。调整前，因为组件要调整 push 的目标地址，迁移 Prometheus 需要重启整个集群。 -- 支持部署 2 套独立的 Grafana + Prometheus 的监控平台（非 HA），防止监控的单点。方法是使用 ansible 用不同的 ip 各执行一次部署命令。 -- 去掉了 Pushgateway 这个单点组件。 - -## 监控数据的来源与展示 - -TiDB 的 3 个核心组件（TiDB server、TiKV server 和 PD server）可以通过 HTTP 接口来获取 metric 数据。这些 metric 均是从程序代码中上传的，默认端口如下： - -| 组件 | 端口 | -|:------------|:-------| -| TiDB server | 10080 | -| TiKV server | 20181 | -| PD server | 2379 | - -下面以 TiDB server 为例，展示如何通过 HTTP 接口查看一个语句的 QPS 数据： - -{{< copyable "shell-regular" >}} - -```bash -curl http://__tidb_ip__:10080/metrics |grep tidb_executor_statement_total -``` - -``` -# 可以看到实时 QPS 数据，并根据不同 type 对 SQL 语句进行了区分，value 是 counter 类型的累计值（科学计数法）。 -tidb_executor_statement_total{type="Delete"} 520197 -tidb_executor_statement_total{type="Explain"} 1 -tidb_executor_statement_total{type="Insert"} 7.20799402e+08 -tidb_executor_statement_total{type="Select"} 2.64983586e+08 -tidb_executor_statement_total{type="Set"} 2.399075e+06 -tidb_executor_statement_total{type="Show"} 500531 -tidb_executor_statement_total{type="Use"} 466016 -``` - -这些数据会存储在 Prometheus 中，然后在 Grafana 上进行展示。在面板上点击鼠标右键会出现 **Edit** 按钮（或直接按 E 键），如下图所示： - -![Metrics 面板的编辑入口](/media/best-practices/metric-board-edit-entry.png) - -点击 **Edit** 按钮之后，在 Metrics 面板上可以看到利用该 metric 的 query 表达式。面板上一些细节的含义如下： - -- `rate[1m]`：表示 1 分钟的增长速率，只能用于 counter 类型的数据。 -- `sum`：表示 value 求和。 -- `by type`：表示将求和后的数据按 metric 原始值中的 type 进行分组。 -- `Legend format`：表示指标名称的格式。 -- `Resolution`：默认打点步长是 15s，Resolution 表示是否将多个样本数据合并成一个点。 - -Metrics 面板中的表达式如下： - -![Metric 面板中的表达式](/media/best-practices/metric-board-expression.jpeg) - -Prometheus 支持很多表达式与函数，更多表达式请参考 [Prometheus 官网页面](https://prometheus.io/docs/prometheus/latest/querying)。 - -## Grafana 使用技巧 - -本小节介绍高效利用 Grafana 监控分析 TiDB 指标的七个技巧。 - -### 技巧 1：查看所有维度并编辑表达式 - -在[监控数据的来源与展示](#监控数据的来源与展示)一节的示例中，数据是按照 type 进行分组的。如果你想知道是否还能按其它维度分组，并快速查看还有哪些维度，可采用以下技巧：**在 query 的表达式上只保留指标名称，不做任何计算，`Legend format` 也留空**。这样就能显示出原始的 metric 数据。比如，下图能看到有 3 个维度（`instance`、`job` 和 `type`）： - -![编辑表达式并查看所有维度](/media/best-practices/edit-expression-check-dimensions.jpg) - -然后调整表达式，在原有的 `type` 后面加上 `instance` 这个维度，在 `Legend format` 处增加 `{{instance}}`，就可以看到每个 TiDB server 上执行的不同类型 SQL 语句的 QPS 了。如下图所示： - -![给表达式增加一个 instance 维度](/media/best-practices/add-instance-dimension.jpeg) - -### 技巧 2：调整 Y 轴标尺的计算方式 - -以 Query Duration 指标为例，默认的比例尺采用 2 的对数计算，显示上会将差距缩小。为了观察到明显的变化，可以将比例尺改为线性，从下面两张图中可以看到显示上的区别，明显发现那个时刻有个 SQL 语句运行较慢。 - -当然也不是所有场景都适合用线性，比如观察 1 个月的性能趋势，用线性可能就会有很多噪点，不好观察。 - -标尺默认的比例尺为 2 的对数： - -![标尺默认的比例尺为 2 的对数](/media/best-practices/default-axes-scale.jpg) - -将标尺的比例尺调整为线性： - -![调整标尺的比例尺为线性](/media/best-practices/axes-scale-linear.jpg) - -> **建议：** -> -> 结合技巧 1，会发现这里还有一个 `sql_type` 的维度，可以立刻分析出是 `SELECT` 慢还是 `UPDATE` 慢；并且可以分析出是哪个 instance 上的语句慢。 - -### 技巧 3：调整 Y 轴基线，放大变化 - -有时已经用了线性比例尺，却还是看不出变化趋势。比如下图中，在扩容后想观察 `Store size` 的实时变化效果，但由于基数较大，观察不到微弱的变化。这时可以将 Y 轴最小值从 `0` 改为 `auto`，将上部放大。观察下面两张图的区别，可以看出数据已开始迁移了。 - -基线默认为 `0`： - -![基线默认为 0](/media/best-practices/default-y-min.jpeg) - -将基线调整为 `auto`： - -![调整基线为 auto](/media/best-practices/y-min-auto.jpg) - -### 技巧 4：标尺联动 - -在 **Settings** 面板中，有一个 **Graph Tooltip** 设置项，默认使用 **Default**。 - -![图形展示工具](/media/best-practices/graph-tooltip.jpeg) - -下面将图形展示工具分别调整为 **Shared crosshair** 和 **Shared Tooltip** 看看效果。可以看到标尺能联动展示了，方便排查问题时确认 2 个指标的关联性。 - -将图形展示工具调整为 **Shared crosshair**： - -![调整图形展示工具为 Shared crosshair](/media/best-practices/graph-tooltip-shared-crosshair.jpeg) - -将图形展示工具调整为 **Shared Tooltip**： - -![调整图形展示工具为 Shared Tooltip](/media/best-practices/graph-tooltip-shared-tooltip.jpg) - -### 技巧 5：手动输入 `ip:端口号` 查看历史信息 - -PD 的 dashboard 只展示当前 leader 的 metric 信息，而有时想看历史上 PD leader 当时的状况，但是 `instance` 下拉列表中已不存在这个成员了。此时，可以手动输入 `ip:2379` 来查看当时的数据。 - -![查看历史 metric 信息](/media/best-practices/manually-input-check-metric.jpeg) - -### 技巧 6：巧用 `Avg` 函数 - -通常默认图例中只有 `Max` 和 `Current` 函数。当指标波动较大时，可以增加 `Avg` 等其它汇总函数的图例，来看一段时间的整体趋势。 - -增加 `Avg` 等汇总函数： - -![增加 Avg 等汇总函数](/media/best-practices/add-avg-function.jpeg) - -然后查看整体趋势： - -![增加 Avg 函数查看整体趋势](/media/best-practices/add-avg-function-check-trend.jpg) - -### 技巧 7：使用 Prometheus 的 API 接口获得表达式的结果 - -Grafana 通过 Prometheus 的接口获取数据，你也可以用该接口来获取数据，这个用法还可以衍生出许多功能： - -- 自动获取集群规模、状态等信息。 -- 对表达式稍加改动给报表提供数据，如统计每天的 QPS 总量、每天的 QPS 峰值和每天的响应时间。 -- 将重要的指标进行定期健康巡检。 - -Prometheus 的 API 接口如下： - -![Prometheus 的 API 接口](/media/best-practices/prometheus-api-interface.jpg) - -{{< copyable "shell-regular" >}} - -```bash -curl -u user:pass 'http://__grafana_ip__:3000/api/datasources/proxy/1/api/v1/query_range?query=sum(tikv_engine_size_bytes%7Binstancexxxxxxxxx20181%22%7D)%20by%20(instance)&start=1565879269&end=1565882869&step=30' |python -m json.tool -``` - -``` -{ - "data": { - "result": [ - { - "metric": { - "instance": "xxxxxxxxxx:20181" - }, - "values": [ - [ - 1565879269, - "1006046235280" - ], - [ - 1565879299, - "1006057877794" - ], - [ - 1565879329, - "1006021550039" - ], - [ - 1565879359, - "1006021550039" - ], - [ - 1565882869, - "1006132630123" - ] - ] - } - ], - "resultType": "matrix" - }, - "status": "success" -} -``` - -## 总结 - -Grafana + Prometheus 监控平台是一套非常强大的组合工具，用好这套工具可以为分析节省很多时间，提高效率，更重要的是，我们可以更容易发现问题。在运维 TiDB 集群，尤其是数据量大的情况下，这套工具能派上大用场。 diff --git a/v3.1/reference/best-practices/haproxy.md b/v3.1/reference/best-practices/haproxy.md deleted file mode 100644 index bac220f0a4c8..000000000000 --- a/v3.1/reference/best-practices/haproxy.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: HAProxy 在 TiDB 中的最佳实践 -category: reference ---- - -# HAProxy 在 TiDB 中的最佳实践 - -本文介绍 [HAProxy](https://github.com/haproxy/haproxy) 在 TiDB 中的最佳配置和使用方法。HAProxy 提供 TCP 协议下的负载均衡能力，TiDB 客户端通过连接 HAProxy 提供的浮动 IP 即可对数据进行操作，实现 TiDB Server 层的负载均衡。 - -![HAProxy 在 TiDB 中的最佳实践](/media/haproxy.jpg) - -## HAProxy 简介 - -HAProxy 是由 C 语言编写的自由开放源码的软件，为基于 TCP 和 HTTP 协议的应用程序提供高可用性、负载均衡和代理服务。因为 HAProxy 能够快速、高效使用 CPU 和内存，所以目前使用非常广泛，许多知名网站诸如 GitHub、Bitbucket、Stack Overflow、Reddit、Tumblr、Twitter 和 Tuenti 以及亚马逊网络服务系统都在使用 HAProxy。 - -HAProxy 由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。最新的稳定版本 2.0.0 于 2019 年 8 月 16 日发布，带来更多[优秀的特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。 - -## HAProxy 部分核心功能介绍 - -- [高可用性](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.4)：HAProxy 提供优雅关闭服务和无缝切换的高可用功能； -- [负载均衡](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#4.2-balance)：L4 (TCP) 和 L7 (HTTP) 两种负载均衡模式，至少 9 类均衡算法，比如 roundrobin，leastconn，random 等； -- [健康检查](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#5.2-check)：对 HAProxy 配置的 HTTP 或者 TCP 模式状态进行检查； -- [会话保持](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.6)：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能； -- [SSL](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.2)：支持 HTTPS 通信和解析； -- [监控与统计](http://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.3)：通过 web 页面可以实时监控服务状态以及具体的流量信息。 - -## 准备环境 - -在部署 HAProxy 之前，需准备好以下环境。 - -### 硬件要求 - -根据官方文档，对 HAProxy 的服务器硬件配置有以下建议，也可以根据负载均衡环境进行推算，在此基础上提高服务器配置。 - -|硬件资源|最低配置| -|:---|:---| -|CPU|2 核，3.5 GHz| -|内存|16 GB| -|存储容量|50 GB（SATA 盘）| -|网卡|万兆网卡| - -### 依赖软件 - -根据官方文档，对操作系统和依赖包有以下建议，如果通过 yum 源部署安装 HAProxy 软件，依赖包无需单独安装。 - -#### 操作系统 - -| 操作系统版本 | 架构 | -|:-------------------------|:------------------------------------------| -| Linux 2.4 | x86、x86_64、Alpha、SPARC、MIPS 和 PA-RISC | -| Linux 2.6 或 3.x | x86、x86_64、ARM、SPARC 和 PPC64 | -| Solaris 8 或 9 | UltraSPARC II 和 UltraSPARC III | -| Solaris 10 | Opteron 和 UltraSPARC | -| FreeBSD 4.10 ~ 10 | x86 | -| OpenBSD 3.1 及以上版本 | i386、AMD64、macppc、Alpha 和 SPARC64 | -| AIX 5.1 ~ 5.3 | Power™ | - -#### 依赖包 - -- epel-release -- gcc -- systemd-devel - -执行如下命令安装依赖包： - -{{< copyable "shell-regular" >}} - -```bash -yum -y install epel-release gcc systemd-devel -``` - -## 部署 HAProxy - -HAProxy 配置 Database 负载均衡场景操作简单，以下部署操作具有普遍性，不具有特殊性，建议根据实际场景，个性化配置相关的[配置文件](http://cbonte.github.io/haproxy-dconv/1.9/configuration.html)。 - -### 安装 HAProxy - -1. 使用 yum 安装 HAProxy： - - {{< copyable "shell-regular" >}} - - ```bash - yum -y install haproxy - ``` - -2. 验证 HAProxy 安装是否成功： - - {{< copyable "shell-regular" >}} - - ```bash - which haproxy - ``` - - ``` - /usr/sbin/haproxy - ``` - -#### HAProxy 命令介绍 - -执行如下命令查看命令行参数及基本用法： - -{{< copyable "shell-regular" >}} - -```bash -haproxy --help -``` - -| 参数 | 说明 | -| :------- | :--------- | -| `-v` | 显示简略的版本信息。 | -| `-vv` | 显示详细的版本信息。 | -| `-d` | 开启 debug 模式。 | -| `-db` | 禁用后台模式和多进程模式。 | -| `-dM []` | 执行分配内存。| -| `-V` | 启动过程显示配置和轮询信息。 | -| `-D` | 开启守护进程模式。 | -| `-C ` | 在加载配置文件之前更改目录位置至 \。 | -| `-W` | 主从模式。 | -| `-q` | 静默模式，不输出信息。 | -| `-c` | 只检查配置文件并在尝试绑定之前退出。 | -| `-n ` | 设置每个进程的最大总连接数为 \。 | -| `-m ` | 设置所有进程的最大可用内存为 \（单位：MB）。 | -| `-N ` | 设置单点最大连接数为 \，默认为 2000。 | -| `-L ` | 将本地实例对等名称改为 \，默认为本地主机名。 | -| `-p ` | 将 HAProxy 所有子进程的 PID 信息写入 \。 | -| `-de` | 禁止使用 epoll(7)，epoll(7) 仅在 Linux 2.6 和某些定制的 Linux 2.4 系统上可用。 | -| `-dp` | 禁止使用 epoll(2)，可改用 select(2)。 | -| `-dS` | 禁止使用 splice(2)，splice(2) 在一些旧版 Linux 内核上不可用。 | -| `-dR` | 禁止使用 SO_REUSEPORT。 | -| `-dr` | 忽略服务器地址解析失败。 | -| `-dV` | 禁止在服务器端使用 SSL。 | -| `-sf ` | 启动后，向 pidlist 中的 PID 发送 `finish` 信号，收到此信号的进程在退出之前将等待所有会话完成，即优雅停止服务。此选项必须最后指定，后跟任意数量的 PID。从技术上讲，SIGTTOU 和 SIGUSR1 都被发送。 | -| `-st ` | 启动后，向 pidlist 中的 PID 发送 `terminate` 信号，收到此信号的进程将立即终止，关闭所有活动会话。此选项必须最后指定，后跟任意数量的 PID。从技术上讲，SIGTTOU 和 SIGTERM 都被发送。 | -| `-x ` | 连接指定的 socket 并从旧进程中获取所有 listening socket，然后，使用这些 socket 而不是绑定新的。 | -| `-S [,...]` | 主从模式下，创建绑定到主进程的 socket，此 socket 可访问每个子进程的 socket。 | - -更多有关 HAProxy 命令参数的信息，可参阅 [Management Guide of HAProxy](http://cbonte.github.io/haproxy-dconv/1.9/management.html) 和 [General Commands Manual of HAProxy](https://manpages.debian.org/buster-backports/haproxy/haproxy.1.en.html)。 - -### 配置 HAProxy - -yum 安装过程中会生成配置模版，你也可以根据实际场景自定义配置如下配置项。 - -```yaml -global # 全局配置。 - log 127.0.0.1 local2 # 定义全局的 syslog 服务器，最多可以定义两个。 - chroot /var/lib/haproxy # 更改当前目录并为启动进程设置超级用户权限，从而提高安全性。 - pidfile /var/run/haproxy.pid # 将 HAProxy 进程的 PID 写入 pidfile。 - maxconn 4000 # 每个 HAProxy 进程所接受的最大并发连接数。 - user haproxy # 同 UID 参数。 - group haproxy # 同 GID 参数，建议使用专用用户组。 - nbproc 40 # 在后台运行时创建的进程数。在启动多个进程转发请求时，确保该值足够大，保证 HAProxy 不会成为瓶颈。 - daemon # 让 HAProxy 以守护进程的方式工作于后台，等同于命令行参数“-D”的功能。当然，也可以在命令行中用“-db”参数将其禁用。 - stats socket /var/lib/haproxy/stats # 统计信息保存位置。 - -defaults # 默认配置。 - log global # 日志继承全局配置段的设置。 - retries 2 # 向上游服务器尝试连接的最大次数，超过此值便认为后端服务器不可用。 - timeout connect 2s # HAProxy 与后端服务器连接超时时间。如果在同一个局域网内，可设置成较短的时间。 - timeout client 30000s # 客户端与 HAProxy 连接后，数据传输完毕，即非活动连接的超时时间。 - timeout server 30000s # 服务器端非活动连接的超时时间。 - -listen admin_stats # frontend 和 backend 的组合体，此监控组的名称可按需进行自定义。 - bind 0.0.0.0:8080 # 监听端口。 - mode http # 监控运行的模式，此处为 `http` 模式。 - option httplog # 开始启用记录 HTTP 请求的日志功能。 - maxconn 10 # 最大并发连接数。 - stats refresh 30s # 每隔 30 秒自动刷新监控页面。 - stats uri /haproxy # 监控页面的 URL。 - stats realm HAProxy # 监控页面的提示信息。 - stats auth admin:pingcap123 # 监控页面的用户和密码，可设置多个用户名。 - stats hide-version # 隐藏监控页面上的 HAProxy 版本信息。 - stats admin if TRUE # 手工启用或禁用后端服务器（HAProxy 1.4.9 及之后版本开始支持）。 - -listen tidb-cluster # 配置 database 负载均衡。 - bind 0.0.0.0:3390 # 浮动 IP 和 监听端口。 - mode tcp # HAProxy 要使用第 4 层的传输层。 - balance leastconn # 连接数最少的服务器优先接收连接。`leastconn` 建议用于长会话服务，例如 LDAP、SQL、TSE 等，而不是短会话协议，如 HTTP。该算法是动态的，对于启动慢的服务器，服务器权重会在运行中作调整。 - server tidb-1 10.9.18.229:4000 check inter 2000 rise 2 fall 3 # 检测 4000 端口，检测频率为每 2000 毫秒一次。如果 2 次检测为成功，则认为服务器可用；如果 3 次检测为失败，则认为服务器不可用。 - server tidb-2 10.9.39.208:4000 check inter 2000 rise 2 fall 3 - server tidb-3 10.9.64.166:4000 check inter 2000 rise 2 fall 3 -``` - -### 启动 HAProxy - -- 方法一：执行 `haproxy`，默认读取 `/etc/haproxy/haproxy.cfg`（推荐）。 - - {{< copyable "shell-regular" >}} - - ```bash - haproxy -f /etc/haproxy/haproxy.cfg - ``` - -- 方法二：使用 `systemd` 启动 HAProxy。 - - {{< copyable "shell-regular" >}} - - ```bash - systemctl start haproxy.service - ``` - -### 停止 HAProxy - -- 方法一：使用 `kill -9`。 - - 1. 执行如下命令： - - {{< copyable "shell-regular" >}} - - ```bash - ps -ef | grep haproxy - ``` - - 2. 终止 HAProxy 相关的 PID 进程： - - {{< copyable "shell-regular" >}} - - ```bash - kill -9 ${haproxy.pid} - ``` - -- 方法二：使用 `systemd`。 - - {{< copyable "shell-regular" >}} - - ```bash - systemctl stop haproxy.service - ``` diff --git a/v3.1/reference/best-practices/high-concurrency.md b/v3.1/reference/best-practices/high-concurrency.md deleted file mode 100644 index 8afbb297066c..000000000000 --- a/v3.1/reference/best-practices/high-concurrency.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: TiDB 高并发写入场景最佳实践 -summary: 了解 TiDB 在高并发写入场景下的最佳实践。 -category: reference ---- - -# TiDB 高并发写入场景最佳实践 - -在 TiDB 的使用过程中，一个典型场景是高并发批量写入数据到 TiDB。本文阐述了该场景中的常见问题，旨在给出一个业务的最佳实践，帮助读者避免因使用 TiDB 不当而影响业务开发。 - -## 目标读者 - -本文假设你已对 TiDB 有一定的了解，推荐先阅读 TiDB 原理相关的三篇文章（[讲存储](https://pingcap.com/blog-cn/tidb-internal-1/)，[说计算](https://pingcap.com/blog-cn/tidb-internal-2/)，[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)），以及 [TiDB Best Practice](https://pingcap.com/blog-cn/tidb-best-practice/)。 - -## 高并发批量插入场景 - -高并发批量插入的场景通常出现在业务系统的批量任务中，例如清算以及结算等业务。此类场景存在以下特点： - -- 数据量大 -- 需要短时间内将历史数据入库 -- 需要短时间内读取大量数据 - -这就对 TiDB 提出了以下挑战： - -- 写入/读取能力是否可以线性水平扩展 -- 随着数据持续大并发写入，数据库性能是否稳定不衰减 - -对于分布式数据库来说，除了本身的基础性能外，最重要的就是充分利用所有节点能力，避免让单个节点成为瓶颈。 - -## TiDB 数据分布原理 - -如果要解决以上挑战，需要从 TiDB 数据切分以及调度的原理开始讲起。这里只作简单说明，详情可参阅[谈调度](https://pingcap.com/blog-cn/tidb-internal-3/)。 - -TiDB 以 Region 为单位对数据进行切分，每个 Region 有大小限制（默认 96M）。Region 的切分方式是范围切分。每个 Region 会有多副本，每一组副本，称为一个 Raft Group。每个 Raft Group 中由 Leader 负责执行这块数据的读 & 写（TiDB 即将支持 [Follower-Read](https://zhuanlan.zhihu.com/p/78164196)）。Leader 会自动地被 PD 组件均匀调度在不同的物理节点上，用以均分读写压力。 - -![TiDB 数据概览](/media/best-practices/tidb-data-overview.png) - -只要业务的写入没有 `AUTO_INCREMENT` 的主键，或没有单调递增的索引（即没有业务上的写入热点，更多细节可参阅 [TiDB 正确使用方式](https://zhuanlan.zhihu.com/p/25574778)），从原理上来说，TiDB 依靠这个架构可具备线性扩展的读写能力，并且可以充分利用分布式资源。从这一点看，TiDB 尤其适合高并发批量写入场景的业务。 - -但理论场景和实际情况往往存在不同。以下实例说明了热点是如何产生的。 - -## 热点产生的实例 - -以下为一张示例表： - -```sql -CREATE TABLE IF NOT EXISTS TEST_HOTSPOT( - id BIGINT PRIMARY KEY, - age INT, - user_name VARCHAR(32), - email VARCHAR(128) -) -``` - -这个表的结构非常简单，除了 `id` 为主键以外，没有额外的二级索引。将数据写入该表的语句如下，`id` 通过随机数离散生成： - -{{< copyable "sql" >}} - -```sql -INSERT INTO TEST_HOTSPOT(id, age, user_name, email) values(%v, %v, '%v', '%v'); -``` - -负载是短时间内密集地执行以上写入语句。 - -以上操作看似符合理论场景中的 TiDB 最佳实践，业务上没有热点产生。只要有足够的机器，就可以充分利用 TiDB 的分布式能力。要验证是否真的符合最佳实践，可以在实验环境中进行测试。 - -部署拓扑 2 个 TiDB 节点，3 个 PD 节点，6 个 TiKV 节点。请忽略 QPS，因为测试只是为了阐述原理，并非 benchmark。 - -![QPS1](/media/best-practices/QPS1.png) - -客户端在短时间内发起了“密集”的写入，TiDB 收到的请求是 3K QPS。理论上，压力应该均摊给 6 个 TiKV 节点。但是从 TiKV 节点的 CPU 使用情况上看，存在明显的写入倾斜（tikv - 3 节点是写入热点）： - -![QPS2](/media/best-practices/QPS2.png) - -![QPS3](/media/best-practices/QPS3.png) - -[Raft store CPU](/v3.1/reference/key-monitoring-metrics/tikv-dashboard.md) 为 `raftstore` 线程的 CPU 使用率，通常代表写入的负载。在这个场景下 tikv-3 为 Raft Leader，tikv-0 和 tikv-1 是 Raft 的 Follower，其他的 TiKV 节点的负载几乎为空。 - -从 PD 的监控中也可以证明热点的产生： - -![QPS4](/media/best-practices/QPS4.png) - -## 热点问题产生的原因 - -以上测试并未达到理论场景中最佳实践，因为刚创建表的时候，这个表在 TiKV 中只会对应为一个 Region，范围是： - -``` -[CommonPrefix + TableID, CommonPrefix + TableID + 1) -``` - -短时间内大量数据会持续写入到同一个 Region 上。 - -![TiKV Region 分裂流程](/media/best-practices/tikv-Region-split.png) - -上图简单描述了这个过程，随着数据持续写入，TiKV 会将一个 Region 切分为多个。但因为首先发起选举的是原 Leader 所在的 Store，所以新切分好的两个 Region 的 Leader 很可能还会在原 Store 上。新切分好的 Region 2，3 上，也会重复之前发生在 Region 1 上的过程。也就是压力会密集地集中在 TiKV-Node 1 上。 - -在持续写入的过程中，PD 发现 Node 1 中产生了热点，会将 Leader 均分到其他的 Node 上。如果 TiKV 的节点数多于副本数的话，TiKV 会尽可能将 Region 迁移到空闲的节点上。这两个操作在数据插入的过程中，也能在 PD 监控中得到印证： - -![QPS5](/media/best-practices/QPS5.png) - -在持续写入一段时间后，整个集群会被 PD 自动地调度成一个压力均匀的状态，到那个时候整个集群的能力才会真正被利用起来。在大多数情况下，以上热点产生的过程是没有问题的，这个阶段属于表 Region 的预热阶段。 - -但是对于高并发批量密集写入场景来说，应该避免这个阶段。 - -## 热点问题的规避方法 - -为了达到场景理论中的最佳性能，可以跳过这个预热阶段，直接将 Region 切分为预期的数量，提前调度到集群的各个节点中。 - -TiDB 在 v3.0.x 以及 v2.1.13 后支持一个叫 [Split Region](/v3.1/reference/sql/statements/split-region.md) 的新特性。这个特性提供了新的语法： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] -``` - -但是 TiDB 并不会自动提前完成这个切分操作。原因如下： - -![Table Region Range](/media/best-practices/table-Region-range.png) - -从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 - -如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 - -作为一款通用数据库，TiDB 并不对数据的分布作假设，所以开始只用一个 Region 来对应一个表。等到真实数据插入进来以后，TiDB 自动根据数据的分布来作切分。这种方式是较通用的。 - -所以 TiDB 提供了 Split Region 语法，专门针对短时批量写入场景作优化。基于以上案例，下面尝试用 Split Region 语法提前切散 Region，再观察负载情况。 - -由于测试的写入数据在正数范围内完全离散，所以用以下语句，在 Int64 空间内提前将表切分为 128 个 Region： - -{{< copyable "sql" >}} - -``` -SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; -``` - -切分完成以后，可以通过 `SHOW TABLE test_hotspot REGIONS;` 语句查看打散的情况。如果 `SCATTERING` 列值全部为 `0`，代表调度成功。 - -也可以通过 [table-regions.py](https://github.com/pingcap/tidb-ansible/blob/dabf60baba5e740a4bee9faf95e77563d8084be1/scripts/table-regions.py) 脚本，查看 Region 的分布。目前分布已经比较均匀了： - -``` -[root@172.16.4.4 scripts]# python table-regions.py --host 172.16.4.3 --port 31453 test test_hotspot -[RECORD - test.test_hotspot] - Leaders Distribution: - total leader count: 127 - store: 1, num_leaders: 21, percentage: 16.54% - store: 4, num_leaders: 20, percentage: 15.75% - store: 6, num_leaders: 21, percentage: 16.54% - store: 46, num_leaders: 21, percentage: 16.54% - store: 82, num_leaders: 23, percentage: 18.11% - store: 62, num_leaders: 21, percentage: 16.54% -``` - -再重新运行写入负载： - -![QPS6](/media/best-practices/QPS6.png) - -![QPS7](/media/best-practices/QPS7.png) - -![QPS8](/media/best-practices/QPS8.png) - -可以看到已经消除了明显的热点问题了。 - -本示例仅为一个简单的表，还有索引热点的问题需要考虑。读者可参阅 [Split Region](/v3.1/reference/sql/statements/split-region.md) 文档来了解如何预先切散索引相关的 Region。 - -### 更复杂的热点问题 - -如果表没有主键或者主键不是 Int 类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 - -要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/v3.1/reference/sql/statements/split-region.md#pre_split_regions)）。 - -`SHARD_ROW_ID_BITS` 用于将 `_tidb_rowid` 列生成的行 ID 随机打散。`pre_split_regions` 用于在建完表后预先进行 Split region。 - -> **注意：** -> -> `pre_split_regions` 必须小于或等于 `shard_row_id_bits`。 - -示例： - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; -``` - -- `SHARD_ROW_ID_BITS = 4` 表示 tidb_rowid 的值会随机分布成 16 （16=2^4） 个范围区间。 -- `pre_split_regions=3` 表示建完表后提前切分出 8 (2^3) 个 Region。 - -开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 - -## 参数配置 - -TiDB 2.1 版本中在 SQL 层引入了 [latch 机制](/v3.1/reference/configuration/tidb-server/configuration-file.md#txn-local-latches)，用于在写入冲突比较频繁的场景中提前发现事务冲突，减少 TiDB 和 TiKV 事务提交时写写冲突导致的重试。通常，跑批场景使用的是存量数据，所以并不存在事务的写入冲突。可以把 TiDB 的 latch 功能关闭，以减少为细小对象分配内存： - -``` -[txn-local-latches] -enabled = false -``` diff --git a/v3.1/reference/best-practices/java-app.md b/v3.1/reference/best-practices/java-app.md deleted file mode 100644 index 82e9f15a7af0..000000000000 --- a/v3.1/reference/best-practices/java-app.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: 开发 Java 应用使用 TiDB 的最佳实践 -category: reference ---- - -# 开发 Java 应用使用 TiDB 的最佳实践 - -本文主要介绍如何开发 Java 应用程序以更好地使用 TiDB，包括开发中的常见问题与最佳实践。 - -## Java 应用中的数据库相关组件 - -通常 Java 应用中和数据库相关的常用组件有： - -- 网络协议：客户端通过标准 [MySQL 协议](https://dev.mysql.com/doc/internals/en/client-server-protocol.html)和 TiDB 进行网络交互。 -- JDBC API 及实现：Java 应用通常使用 [JDBC (Java Database Connectivity)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) 来访问数据库。JDBC 定义了访问数据库 API，而 JDBC 实现完成标准 API 到 MySQL 协议的转换，常见的 JDBC 实现是 [MySQL Connector/J](https://github.com/mysql/mysql-connector-j)，此外有些用户可能使用 [MariaDB Connector/J](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#about-mariadb-connectorj)。 -- 数据库连接池：为了避免每次创建连接，通常应用会选择使用数据库连接池来复用连接，JDBC [DataSource](https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html) 定义了连接池 API，开发者可根据实际需求选择使用某种开源连接池实现。 -- 数据访问框架：应用通常选择通过数据访问框架 ([MyBatis](http://www.mybatis.org/mybatis-3/zh/index.html), [Hibernate](https://hibernate.org/)) 的封装来进一步简化和管理数据库访问操作。 -- 业务实现：业务逻辑控制着何时发送和发送什么指令到数据库，其中有些业务会使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 切面来控制管理事务的开始和提交逻辑。 - -![Java Component](/media/java-practice-1.png) - -如上图所示，应用可能使用 Spring Transaction 来管理控制事务非手工启停，通过类似 MyBatis 的数据访问框架管理生成和执行 SQL，通过连接池获取已池化的长连接，最后通过 JDBC 接口调用实现通过 MySQL 协议和 TiDB 完成交互。 - -接下来将分别介绍使用各个组件时可能需要关注的问题。 - -## JDBC - -Java 应用尽管可以选择在不同的框架中封装，但在最底层一般会通过调用 JDBC 来与数据库服务器进行交互。对于 JDBC，需要关注的主要有：API 的使用选择和 API Implementer 的参数配置。 - -### JDBC API - -对于基本的 JDBC API 使用可以参考 [JDBC 官方教程](https://docs.oracle.com/javase/tutorial/jdbc/)，本文主要强调几个比较重要的 API 选择。 - -#### 使用 Prepare API - -对于 OLTP 场景，程序发送给数据库的 SQL 语句在去除参数变化后都是可穷举的某几类，因此建议使用[预处理语句 (Prepared Statements)](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html) 代替普通的[文本执行](https://docs.oracle.com/javase/tutorial/jdbc/basics/processingsqlstatements.html#executing_queries)，并复用预处理语句来直接执行，从而避免 TiDB 重复解析和生成 SQL 执行计划的开销。 - -目前多数上层框架都会调用 Prepare API 进行 SQL 执行，如果直接使用 JDBC API 进行开发，注意选择使用 Prepare API。 - -另外需要注意 MySQL Connector/J 实现中默认只会做客户端的语句预处理，会将 `?` 在客户端替换后以文本形式发送到服务端，所以除了要使用 Prepare API，还需要在 JDBC 连接参数中配置 `useServerPrepStmts = true`，才能在 TiDB 服务器端进行语句预处理（下面参数配置章节有详细介绍）。 - -#### 使用 Batch 批量插入更新 - -对于批量插入更新，如果插入记录较多，可以选择使用 [addBatch/executeBatch API](https://www.tutorialspoint.com/jdbc/jdbc-batch-processing)。通过 addBatch 的方式将多条 SQL 的插入更新记录先缓存在客户端，然后在 executeBatch 时一起发送到数据库服务器。 - -> **注意：** -> -> 对于 MySQL Connector/J 实现，默认 Batch 只是将多次 addBatch 的 SQL 发送时机延迟到调用 executeBatch 的时候，但实际网络发送还是会一条条的发送，通常不会降低与数据库服务器的网络交互次数。 -> -> 如果希望 Batch 网络发送，需要在 JDBC 连接参数中配置 `rewriteBatchedStatements = true`（下面参数配置章节有详细介绍）。 - -#### 使用 StreamingResult 流式获取执行结果 - -一般情况下，为提升执行效率，JDBC 会默认提前获取查询结果并将其保存在客户端内存中。但在查询返回超大结果集的场景中，客户端会希望数据库服务器减少向客户端一次返回的记录数，等客户端在有限内存处理完一部分后再去向服务器要下一批。 - -在 JDBC 中通常有以下两种处理方式： - -- 设置 [`FetchSize` 为 `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-implementation-notes.html#ResultSet) 让客户端不缓存，客户端通过 StreamingResult 的方式从网络连接上流式读取执行结果。 -- 使用 Cursor Fetch，首先需[设置 `FetchSize`](http://makejavafaster.blogspot.com/2015/06/jdbc-fetch-size-performance.html) 为正整数，且在 JDBC URL 中配置 `useCursorFetch = true`。 - -TiDB 中同时支持两种方式，但更推荐使用第一种将 `FetchSize` 设置为 `Integer.MIN_VALUE` 的方式，比第二种功能实现更简单且执行效率更高。 - -### MySQL JDBC 参数 - -JDBC 实现通常通过 JDBC URL 参数的形式来提供实现相关的配置。这里以 MySQL 官方的 Connector/J 来介绍[参数配置](https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-configuration-properties.html)（如果使用的是 MariaDB，可以参考 [MariaDB 的类似配置](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)）。因为配置项较多，这里主要关注几个可能影响到性能的参数。 - -#### Prepare 相关参数 - -##### `useServerPrepStmts` - -默认情况下，`useServerPrepStmts` 的值为 `false`，即尽管使用了 Prepare API，也只会在客户端做 “prepare”。因此为了避免服务器重复解析的开销，如果同一条 SQL 语句需要多次使用 Prepare API，则建议设置该选项为 `true`。 - -在 TiDB 监控中可以通过 **Query Summary** > **QPS By Instance** 查看请求命令类型，如果请求中 `COM_QUERY` 被 `COM_STMT_EXECUTE` 或 `COM_STMT_PREPARE` 代替即生效。 - -##### `cachePrepStmts` - -虽然 `useServerPrepStmts = true` 能让服务端执行预处理语句，但默认情况下客户端每次执行完后会 close 预处理语句，并不会复用，这样预处理的效率甚至不如文本执行。所以建议开启 `useServerPrepStmts = true` 后同时配置 `cachePrepStmts = true`，这会让客户端缓存预处理语句。 - -在 TiDB 监控中可以通过 **Query Summary** > **QPS By Instance** 查看请求命令类型，如果类似下图，请求中 `COM_STMT_EXECUTE` 数目远远多于 `COM_STMT_PREPARE` 即生效。 - -![QPS By Instance](/media/java-practice-2.png) - -另外，通过 `useConfigs = maxPerformance` 配置会同时配置多个参数，其中也包括 `cachePrepStmts = true`。 - -##### `prepStmtCacheSqlLimit` - -在配置 `cachePrepStmts` 后还需要注意 `prepStmtCacheSqlLimit` 配置（默认为 `256`），该配置控制客户端缓存预处理语句的最大长度，超过该长度将不会被缓存。 - -在一些场景 SQL 的长度可能超过该配置，导致预处理 SQL 不能复用，建议根据应用 SQL 长度情况决定是否需要调大该值。 - -在 TiDB 监控中通过 **Query Summary** > **QPS by Instance** 查看请求命令类型，如果已经配置了 `cachePrepStmts = true`，但 `COM_STMT_PREPARE` 还是和 `COM_STMT_EXECUTE` 基本相等且有 `COM_STMT_CLOSE`，需要检查这个配置项是否设置得太小。 - -##### `prepStmtCacheSize` - -`prepStmtCacheSize` 控制缓存的预处理语句数目（默认为 `25`），如果应用需要预处理的 SQL 种类很多且希望复用预处理语句，可以调大该值。 - -和上一条类似，在监控中通过 **Query Summary** > **QPS by Instance** 查看请求中 `COM_STMT_EXECUTE` 数目是否远远多于 `COM_STMT_PREPARE` 来确认是否正常。 - -#### Batch 相关参数 - -在进行 batch 写入处理时推荐配置 `rewriteBatchedStatements = true`，在已经使用 `addBatch` 或 `executeBatch` 后默认 JDBC 还是会一条条 SQL 发送，例如： - -```java -pstmt = prepare(“insert into t (a) values(?)”); -pstmt.setInt(1, 10); -pstmt.addBatch(); -pstmt.setInt(1, 11); -pstmt.addBatch(); -pstmt.setInt(1, 12); -pstmt.executeBatch(); -``` - -虽然使用了 batch 但发送到 TiDB 语句还是单独的多条 insert： - -{{< copyable "sql" >}} - -```sql -insert into t(a) values(10); -insert into t(a) values(11); -insert into t(a) values(12); -``` - -如果设置 `rewriteBatchedStatements = true`，发送到 TiDB 的 SQL 将是： - -{{< copyable "sql" >}} - -```sql -insert into t(a) values(10),(11),(12); -``` - -需要注意的是，insert 语句的改写，只能将多个 values 后的值拼接成一整条 SQL，insert 语句如果有其他差异将无法被改写。 -例如： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10) on duplicate key update a = 10; -insert into t (a) values (11) on duplicate key update a = 11; -insert into t (a) values (12) on duplicate key update a = 12; -``` - -上述 insert 语句将无法被改写成一条语句。该例子中，如果将 SQL 改写成如下形式： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10) on duplicate key update a = values(a); -insert into t (a) values (11) on duplicate key update a = values(a); -insert into t (a) values (12) on duplicate key update a = values(a); -``` - -即可满足改写条件，最终被改写成： - -{{< copyable "sql" >}} - -```sql -insert into t (a) values (10), (11), (12) on duplicate key update a = values(a); -``` - -批量更新时如果有 3 处或 3 处以上更新，则 SQL 语句会改写为 multiple-queries 的形式并发送，这样可以有效减少客户端到服务器的请求开销，但副作用是会产生较大的 SQL 语句，例如这样： - -{{< copyable "sql" >}} - -```sql -update t set a = 10 where id = 1; update t set a = 11 where id = 2; update t set a = 12 where id = 3; -``` - -另外，因为一个[客户端 bug](https://bugs.mysql.com/bug.php?id=96623)，批量更新时如果要配置 `rewriteBatchedStatements = true` 和 `useServerPrepStmts = true`，推荐同时配置 `allowMultiQueries = true` 参数来避免这个 bug。 - -#### 执行前检查参数 - -通过监控可能会发现，虽然业务只向集群进行 insert 操作，却看到有很多多余的 select 语句。通常这是因为 JDBC 发送了一些查询设置类的 SQL 语句（例如 `select @@session.transaction_read_only`）。这些 SQL 对 TiDB 无用，推荐配置 `useConfigs = maxPerformance` 来避免额外开销。 - -`useConfigs = maxPerformance` 会包含一组配置： - -```ini -cacheServerConfiguration = true -useLocalSessionState = true -elideSetAutoCommits = true -alwaysSendSetIsolation = false -enableQueryTimeouts = false -``` - -配置后查看监控，可以看到多余语句减少。 - -## 连接池 - -TiDB (MySQL) 连接建立是比较昂贵的操作（至少对于 OLTP），除了建立 TCP 连接外还需要进行连接鉴权操作，所以客户端通常会把 TiDB (MySQL) 连接保存到连接池中进行复用。 - -Java 的连接池实现很多 ([HikariCP](https://github.com/brettwooldridge/HikariCP), [tomcat-jdbc](https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html), [durid](https://github.com/alibaba/druid), [c3p0](https://www.mchange.com/projects/c3p0/), [dbcp](https://commons.apache.org/proper/commons-dbcp/))，TiDB 不会限定使用的连接池，应用可以根据业务特点自行选择连接池实现。 - -### 连接数配置 - -比较常见的是应用需要根据自身情况配置合适的连接池大小，以 HikariCP 为例： - -- `maximumPoolSize`：连接池最大连接数，配置过大会导致 TiDB 消耗资源维护无用连接，配置过小则会导致应用获取连接变慢，所以需根据应用自身特点配置合适的值，可参考[这篇文章](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)。 -- `minimumIdle`：连接池最小空闲连接数，主要用于在应用空闲时存留一些连接以应对突发请求，同样是需要根据业务情况进行配置。 - -应用在使用连接池时，需要注意连接使用完成后归还连接，推荐应用使用对应的连接池相关监控（如 `metricRegistry`），通过监控能及时定位连接池问题。 - -### 探活配置 - -连接池维护到 TiDB 的长连接，TiDB 默认不会主动关闭客户端连接（除非报错），但一般客户端到 TiDB 之间还会有 LVS 或 HAProxy 之类的网络代理，它们通常会在连接空闲一定时间后主动清理连接。除了注意代理的 idle 配置外，连接池还需要进行保活或探测连接。 - -如果常在 Java 应用中看到以下错误： - -``` -The last packet sent successfully to the server was 3600000 milliseconds ago. The driver has not received any packets from the server. com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure -``` - -如果 `n milliseconds ago` 中的 `n` 如果是 0 或很小的值，则通常是执行的 SQL 导致 TiDB 异常退出引起的报错，推荐查看 TiDB stderr 日志；如果 n 是一个非常大的值（比如这里的 3600000），很可能是因为这个连接空闲太久然后被中间 proxy 关闭了，通常解决方式除了调大 proxy 的 idle 配置，还可以让连接池执行以下操作： - -- 每次使用连接前检查连接是否可用。 -- 使用单独线程定期检查连接是否可用。 -- 定期发送 test query 保活连接。 - -不同的连接池实现可能会支持其中一种或多种方式，可以查看所使用的连接池文档来寻找对应配置。 - -## 数据访问框架 - -业务应用通常会使用某种数据访问框架来简化数据库的访问。 - -### MyBatis - -[MyBatis](http://www.mybatis.org/mybatis-3/) 是目前比较流行的 Java 数据访问框架，主要用于管理 SQL 并完成结果集和 Java 对象的来回映射工作。MyBatis 和 TiDB 兼容性很好，从历史 issue 可以看出 MyBatis 很少出现问题。这里主要关注如下几个配置。 - -#### Mapper 参数 - -MyBatis 的 Mapper 中支持两种参数： - -- `select 1 from t where id = #{param1}` 会作为预处理语句，被转换为 `select 1 from t where id = ?` 进行预处理，并使用实际参数来复用执行，通过配合前面的 Prepare 连接参数能获得最佳性能。 -- `select 1 from t where id = ${param2}` 会做文本替换为 `select 1 from t where id = 1` 执行，如果这条语句被预处理为不同参数，可能会导致 TiDB 缓存大量的预处理语句，并且以这种方式执行 SQL 有注入安全风险。 - -#### 动态 SQL Batch - -[动态 SQL - foreach](http://www.mybatis.org/mybatis-3/dynamic-sql.html#foreach) - -要支持将多条 insert 语句自动重写为 `insert ... values(...), (...), ...` 的形式，除了前面所说的在 JDBC 配置 `rewriteBatchedStatements = true` 外，MyBatis 还可以使用动态 SQL 来半自动生成 batch insert。比如下面的 mapper: - -```xml - - insert into test - (id, v1, v2) - values - - ( - #{item.id}, #{item.v1}, #{item.v2} - ) - - on duplicate key update v2 = v1 + values(v1) - -``` - -会生成一个 `insert on duplicate key update` 语句，values 后面的 `(?, ?, ?)` 数目是根据传入的 list 个数决定，最终效果和使用 `rewriteBatchStatements = true` 类似，可以有效减少客户端和 TiDB 的网络交互次数，同样需要注意预处理后超过 `prepStmtCacheSqlLimit` 限制导致不缓存预处理语句的问题。 - -#### Streaming 结果 - -前面介绍了在 JDBC 中如何使用流式读取结果，除了 JDBC 相应的配置外，在 MyBatis 中如果希望读取超大结果集合也需要注意： - -- 可以通过在 mapper 配置中对单独一条 SQL 设置 `fetchSize`（见上一段代码段），效果等同于调用 JDBC `setFetchSize` -- 可以使用带 `ResultHandler` 的查询接口来避免一次获取整个结果集 -- 可以使用 `Cursor` 类来进行流式读取 - -对于使用 xml 配置映射，可以通过在映射 ` - select * from post; - -``` - -而使用代码配置映射，则可以使用 `@Options(fetchSize = Integer.MIN_VALUE)` 并返回 `Cursor` 从而让 SQL 结果能被流式读取。 - -```java -@Select("select * from post") -@Options(fetchSize = Integer.MIN_VALUE) -Cursor queryAllPost(); -``` - -### `ExecutorType` - -在 `openSession` 的时候可以选择 `ExecutorType`，MyBatis 支持三种 executor： - -- Simple：每次执行都会向 JDBC 进行预处理语句的调用（如果 JDBC 配置有开启 `cachePrepStmts`，重复的预处理语句会复用）。 -- Reuse：在 `executor` 中缓存预处理语句，这样不用 JDBC 的 `cachePrepStmts` 也能减少重复预处理语句的调用。 -- Batch：每次更新只有在 `addBatch` 到 query 或 commit 时才会调用 `executeBatch` 执行，如果 JDBC 层开启了 `rewriteBatchStatements`，则会尝试改写，没有开启则会一条条发送。 - -通常默认值是 `Simple`，需要在调用 `openSession` 时改变 `ExecutorType`。如果是 Batch 执行，会遇到事务中前面的 update 或 insert 都非常快，而在读数据或 commit 事务时比较慢的情况，这实际上是正常的，在排查慢 SQL 时需要注意。 - -## Spring Transaction - -在应用代码中业务可能会通过使用 [Spring Transaction](https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html) 和 AOP 切面的方式来启停事务。 - -通过在方法定义上添加 `@Transactional` 注解标记方法，AOP 将会在方法前开启事务，方法返回结果前 commit 事务。如果遇到类似业务，可以通过查找代码 `@Transactional` 来确定事务的开启和关闭时机。需要特别注意有内嵌的情况，如果发生内嵌，Spring 会根据 [Propagation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/transaction/annotation/Propagation.html) 配置使用不同的行为，因为 TiDB 未支持 savepoint，所以不支持嵌套事务。 - -## 其他 - -### 排查工具 - -在 Java 应用发生问题并且不知道业务逻辑情况下，使用 JVM 强大的排查工具会比较有用。这里简单介绍几个常用工具： - -#### jstack - -[jstack](https://docs.oracle.com/javase/7/docs/technotes/tools/share/jstack.html) 对应于 Go 中的 pprof/goroutine，可以比较方便地排查进程卡死的问题。 - -通过执行 `jstack pid`，即可输出目标进程中所有线程的线程 id 和堆栈信息。输出中默认只有 Java 堆栈，如果希望同时输出 JVM 中的 C++ 堆栈，需要加 `-m` 选项。 - -通过多次 jstack 可以方便地发现卡死问题（比如：都通过 Mybatis BatchExecutor flush 调用 update）或死锁问题（比如：测试程序都在抢占应用中某把锁导致没发送 SQL） - -另外，`top -p $PID -H` 或者 Java swiss knife 都是常用的查看线程 ID 的方法。通过 `printf "%x\n" pid` 把线程 ID 转换成 16 进制，然后去 jstack 输出结果中找对应线程的栈信息，可以定位”某个线程占用 CPU 比较高，不知道它在执行什么”的问题。 - -#### jmap & mat - -和 Go 中的 pprof/heap 不同，[jmap](https://docs.oracle.com/javase/7/docs/technotes/tools/share/jmap.html) 会将整个进程的内存快照 dump 下来（go 是分配器的采样），然后可以通过另一个工具 [mat](https://www.eclipse.org/mat/) 做分析。 - -通过 mat 可以看到进程中所有对象的关联信息和属性，还可以观察线程运行的状态。比如：我们可以通过 mat 找到当前应用中有多少 MySQL 连接对象，每个连接对象的地址和状态信息是什么。 - -需要注意 mat 默认只会处理 reachable objects，如果要排查 young gc 问题可以在 mat 配置中设置查看 unreachable objects。另外对于调查 young gc 问题（或者大量生命周期较短的对象）的内存分配，用 Java Flight Recorder 比较方便。 - -#### trace - -线上应用通常无法修改代码，又希望在 Java 中做动态插桩来定位问题，推荐使用 btrace 或 arthas trace。它们可以在不重启进程的情况下动态插入 trace 代码。 - -#### 火焰图 - -Java 应用中获取火焰图较繁琐，可参阅 [Java Flame Graphs Introduction: Fire For Everyone!](http://psy-lob-saw.blogspot.com/2017/02/flamegraphs-intro-fire-for-everyone.html) 来手动获取。 - -## 总结 - -本文从常用的和数据库交互的 Java 组件的角度，阐述了开发 Java 应用程序使用 TiDB 的常见问题与解决办法。TiDB 是高度兼容 MySQL 协议的数据库，基于 MySQL 开发的 Java 应用的最佳实践也多适用于 TiDB。 - -欢迎大家在 [ASK TUG](https://asktug.com/) 踊跃发言，和我们一起分享讨论 Java 应用使用 TiDB 的实践技巧或遇到的问题。 diff --git a/v3.1/reference/best-practices/massive-regions.md b/v3.1/reference/best-practices/massive-regions.md deleted file mode 100644 index 795b5d2b7d6d..000000000000 --- a/v3.1/reference/best-practices/massive-regions.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 海量 Region 集群调优最佳实践 -summary: 了解海量 Region 导致性能问题的原因和优化方法。 -category: reference ---- - -# 海量 Region 集群调优最佳实践 - -在 TiDB 的架构中，所有数据以一定 key range 被切分成若干 Region 分布在多个 TiKV 实例上。随着数据的写入，一个集群中会产生上百万个甚至千万个 Region。单个 TiKV 实例上产生过多的 Region 会给集群带来较大的负担，影响整个集群的性能表现。 - -本文将介绍 TiKV 核心模块 Raftstore 的工作流程，海量 Region 导致性能问题的原因，以及优化性能的方法。 - -## Raftstore 的工作流程 - -一个 TiKV 实例上有多个 Region。Region 消息是通过 Raftstore 模块驱动 Raft 状态机来处理的。这些消息包括 Region 上读写请求的处理、Raft log 的持久化和复制、Raft 的心跳处理等。但是，Region 数量增多会影响整个集群的性能。为了解释这一点，需要先了解 TiKV 的核心模块 Raftstore 的工作流程。 - -![图 1 Raftstore 处理流程示意图](/media/best-practices/raft-process.png) - -> **注意：** -> -> 该图仅为示意，不代表代码层面的实际结构。 - -上图是 Raftstore 处理流程的示意图。如图所示，从 TiDB 发来的请求会通过 gRPC 和 storage 模块变成最终的 KV 读写消息，并被发往相应的 Region，而这些消息并不会被立即处理而是被暂存下来。Raftstore 会轮询检查每个 Region 是否有需要处理的消息。如果 Region 有需要处理的消息，那么 Raftstore 会驱动 Raft 状态机去处理这些消息，并根据这些消息所产生的状态变更去进行后续操作。例如，在有写请求时，Raft 状态机需要将日志落盘并且将日志发送给其他 Region 副本；在达到心跳间隔时，Raft 状态机需要将心跳信息发送给其他 Region 副本。 - -## 性能问题 - -从 Raftstore 处理流程示意图可以看出，需要依次处理各个 Region 的消息。那么在 Region 数量较多的情况下，Raftstore 需要花费一些时间去处理大量 Region 的心跳，从而带来一些延迟，导致某些读写请求得不到及时处理。如果读写压力较大，Raftstore 线程的 CPU 使用率容易达到瓶颈，导致延迟进一步增加，进而影响性能表现。 - -通常在有负载的情况下，如果 Raftstore 的 CPU 使用率达到了 85% 以上，即可视为达到繁忙状态且成为了瓶颈，同时 `propose wait duration` 可能会高达百毫秒级别。 - -> **注意：** -> -> + Raftstore 的 CPU 使用率是指单线程的情况。如果是多线程 Raftstore，可等比例放大使用率。 -> + 由于 Raftstore 线程中有 I/O 操作，所以 CPU 使用率不可能达到 100%。 - -### 性能监控 - -可在 Grafana 的 TiKV 面板下查看相关的监控 metrics： - -+ Thread-CPU 下的 `Raft store CPU` - - 参考值：低于 `raftstore.store-pool-size * 85%`。在 v2.1 版本中无此配置项，因此在 v2.1 中可视为 `raftstore.store-pool-size = 1`。 - - ![图 2 查看 Raftstore CPU](/media/best-practices/raft-store-cpu.png) - -+ Raft Propose 下的 `Propose wait duration` - - `Propose wait duration` 是从发送请求给 Raftstore，到 Raftstore 真正开始处理请求之间的延迟时间。如果该延迟时间较长，说明 Raftstore 比较繁忙或者处理 append log 比较耗时导致 Raftstore 不能及时处理请求。 - - 参考值：低于 50-100ms。 - - ![图 3 查看 Propose wait duration](/media/best-practices/propose-wait-duration.png) - -## 性能优化方法 - -找到性能问题的根源后，可从以下两个方向来解决性能问题： - -+ 减少单个 TiKV 实例的 Region 数 -+ 减少单个 Region 的消息数 - -### 方法一：增加 TiKV 实例 - -如果 I/O 资源和 CPU 资源都比较充足，可在单台机器上部署多个 TiKV 实例，以减少单个 TiKV 实例上的 Region 个数；或者增加 TiKV 集群的机器数。 - -### 方法二：调整 `raft-base-tick-interval` - -除了减少 Region 个数外，还可以通过减少 Region 单位时间内的消息数量来减小 Raftstore 的压力。例如，在 TiKV 配置中适当调大 `raft-base-tick-interval`： - -{{< copyable "" >}} - -``` -[raftstore] -raft-base-tick-interval = "2s" -``` - -`raft-base-tick-interval` 是 Raftstore 驱动每个 Region 的 Raft 状态机的时间间隔，也就是每隔该时长就需要向 Raft 状态机发送一个 tick 消息。增加该时间间隔，可以有效减少 Raftstore 的消息数量。 - -需要注意的是，该 tick 消息的间隔也决定了 `election timeout` 和 `heartbeat` 的间隔。示例如下： - -{{< copyable "" >}} - -``` -raft-election-timeout = raft-base-tick-interval * raft-election-timeout-ticks -raft-heartbeat-interval = raft-base-tick-interval * raft-heartbeat-ticks -``` - -如果 Region Follower 在 `raft-election-timeout` 间隔内未收到来自 Leader 的心跳，就会判断 Leader 出现故障而发起新的选举。`raft-heartbeat-interval` 是 Leader 向 Follower 发送心跳的间隔，因此调大 `raft-base-tick-interval` 可以减少单位时间内 Raft 发送的网络消息，但也会让 Raft 检测到 Leader 故障的时间更长。 - -### 方法三：提高 Raftstore 并发数 - -v3.0 版本中的 Raftstore 已经扩展为多线程，极大降低了 Raftstore 线程成为瓶颈的可能性。 - -TiKV 默认将 `raftstore.store-pool-size` 配置为 `2`。如果 Raftstore 出现瓶颈，可以根据实际情况适当调高该参数值，但不建议设置过高以免引入不必要的线程切换开销。 - -### 方法四：开启 Hibernate Region 功能 - -在实际情况中，读写请求并不会均匀分布到每个 Region 上，而是集中在少数的 Region 上。那么可以尽量减少暂时空闲的 Region 的消息数量，这也就是 Hibernate Region 的功能。无必要时可不进行 `raft-base-tick`，即不驱动空闲 Region 的 Raft 状态机，那么就不会触发这些 Region 的 Raft 产生心跳信息，极大地减小了 Raftstore 的工作负担。 - -截至 TiDB v3.0.5，Hibernate Region 仍是一个实验功能，在 [TiKV master](https://github.com/tikv/tikv/tree/master) 分支上已经默认开启。可根据实际情况和需求来开启该功能。Hibernate Region 的配置说明请参考[配置 Hibernate Region](https://github.com/tikv/tikv/blob/master/docs/reference/configuration/raftstore-config.md#hibernate-region)。 - -### 方法五：开启 `Region Merge` - -> **注意：** -> -> `Region Merge` 已在 TiDB v3.0 中默认开启。 - -开启 `Region Merge` 也能减少 Region 的个数。与 `Region Split` 相反，`Region Merge` 是通过调度把相邻的小 Region 合并的过程。在集群中删除数据或者执行 `Drop Table`/`Truncate Table` 语句后，可以将小 Region 甚至空 Region 进行合并以减少资源的消耗。 - -通过 pd-ctl 设置以下参数即可开启 `Region Merge`： - -{{< copyable "" >}} - -``` ->> pd-ctl config set max-merge-region-size 20 ->> pd-ctl config set max-merge-region-keys 200000 ->> pd-ctl config set merge-schedule-limit 8 -``` - -详情请参考[如何配置 Region Merge](https://github.com/tikv/tikv/blob/master/docs/how-to/configure/region-merge.md) 和 [PD 配置文件描述](/v3.1/reference/configuration/pd-server/configuration-file.md#schedule)。 - -同时，默认配置的 `Region Merge` 的参数设置较为保守，可以根据需求参考 [PD 调度策略最佳实践](/v3.1/reference/best-practices/pd-scheduling.md#region-merge-速度慢) 中提供的方法加快 `Region Merge` 过程的速度。 - -## 其他问题和解决方案 - -### 切换 PD Leader 的速度慢 - -PD 需要将 Region Meta 信息持久化在 etcd 上，以保证切换 PD Leader 节点后 PD 能快速继续提供 Region 路由服务。随着 Region 数量的增加，etcd 出现性能问题，使得 PD 在切换 Leader 时从 etcd 获取 Region Meta 信息的速度较慢。在百万 Region 量级时，从 etcd 获取信息的时间可能需要十几秒甚至几十秒。 - -因此在 v3.0 版本中，PD 默认开启配置项 `use-region-storage`，将 Region Meta 信息存在本地的 LevelDB 中，并通过其他机制同步 PD 节点间的信息。 - -### PD 路由信息更新不及时 - -在 TiKV 中，pd-worker 模块将 Region Meta 信息定期上报给 PD，在 TiKV 重启或者切换 Region Leader 时需要通过统计信息重新计算 Region 的 `approximate size/keys`。因此在 Region 数量较多的情况下，pd-worker 单线程可能成为瓶颈，造成任务得不到及时处理而堆积起来。因此 PD 不能及时获取某些 Region Meta 信息以致路由信息更新不及时。该问题不会影响实际的读写，但可能导致 PD 调度不准确以及 TiDB 更新 Region cache 时需要多几次 round-trip。 - -可在 TiKV Grafana 面板中查看 Task 下的 Worker pending tasks 来确定 pd-worker 是否有任务堆积。通常来说，pending tasks 应该维持在一个比较低的值。 - -![图 4 查看 pd-worker](/media/best-practices/pd-worker-metrics.png) - -目前已经在 [TiKV master](https://github.com/tikv/tikv/tree/master) 上对 pd-worker 进行了[效率优化](https://github.com/tikv/tikv/pull/5620)。[TiDB v3.0.5](https://pingcap.com/docs-cn/stable/releases/3.0.5/) 中已带上该优化。如果碰到类似问题，建议升级至 v3.0.5。 - -### Prometheus 查询 metrics 的速度慢 - -在大规模集群中，随着 TiKV 实例数的增加，Prometheus 查询 metrics 时的计算压力较大，导致 Grafana 查看 metrics 的速度较慢。v3.0 版本中设置了一些 metrics 的预计算，让这个问题有所缓解。 diff --git a/v3.1/reference/best-practices/pd-scheduling.md b/v3.1/reference/best-practices/pd-scheduling.md deleted file mode 100644 index ef8c106237e4..000000000000 --- a/v3.1/reference/best-practices/pd-scheduling.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: PD 调度策略最佳实践 -summary: 了解 PD 调度策略的最佳实践和调优方式 -category: reference ---- - -# PD 调度策略最佳实践 - -本文将详细介绍 PD 调度系统的原理，并通过几个典型场景的分析和处理方式，分享调度策略的最佳实践和调优方式，帮助大家在使用过程中快速定位问题。本文假定你对 TiDB，TiKV 以及 PD 已经有一定的了解，相关核心概念如下： - -- [Leader/Follower/Learner](/v3.1/glossary.md#leaderfollowerlearner) -- [Operator](/v3.1/glossary.md#operator) -- [Operator Step](/v3.1/glossary.md#operator-step) -- [Pending/Down](/v3.1/glossary.md#pendingdown) -- [Region/Peer/Raft Group](/v3.1/glossary.md#regionpeerraft-group) -- [Region Split](/v3.1/glossary.md#region-split) -- [Scheduler](/v3.1/glossary.md#scheduler) -- [Store](/v3.1/glossary.md#store) - -> **注意：** -> -> 本文内容基于 TiDB 3.0 版本，更早的版本（2.x）缺少部分功能的支持，但是基本原理类似，也可以以本文作为参考。 - -## PD 调度原理 - -该部分介绍调度系统涉及到的相关原理和流程。 - -### 调度流程 - -宏观上来看，调度流程大体可划分为 3 个部分： - -1. 信息收集 - - TiKV 节点周期性地向 PD 上报 `StoreHeartbeat` 和 `RegionHeartbeat` 两种心跳消息： - - * `StoreHeartbeat` 包含 Store 的基本信息、容量、剩余空间和读写流量等数据。 - * `RegionHeartbeat` 包含 Region 的范围、副本分布、副本状态、数据量和读写流量等数据。 - - PD 梳理并转存这些信息供调度进行决策。 - -2. 生成调度 - - 不同的调度器从自身的逻辑和需求出发，考虑各种限制和约束后生成待执行的 Operator。这里所说的限制和约束包括但不限于： - - - 不往断连中、下线中、繁忙、空间不足、在大量收发 snapshot 等各种异常状态的 Store 添加副本 - - Balance 时不选择状态异常的 Region - - 不尝试把 Leader 转移给 Pending Peer - - 不尝试直接移除 Leader - - 不破坏 Region 各种副本的物理隔离 - - 不破坏 Label property 等约束 - -3. 执行调度 - - 调度执行的步骤为： - - a. Operator 先进入一个由 `OperatorController` 管理的等待队列。 - - b. `OperatorController` 会根据配置以一定的并发量从等待队列中取出 Operator 并执行。执行的过程就是依次把每个 Operator Step 下发给对应 Region 的 Leader。 - - c. 标记 Operator 为 “finish” 或 “timeout” 状态，然后从执行列表中移除。 - -### 负载均衡 - -Region 负载均衡调度主要依赖 `balance-leader` 和 `balance-region` 两个调度器。二者的调度目标是将 Region 均匀地分散在集群中的所有 Store 上，但它们各有侧重：`balance-leader` 关注 Region 的 Leader，目的是分散处理客户端请求的压力；`balance-region` 关注 Region 的各个 Peer，目的是分散存储的压力，同时避免出现爆盘等状况。 - -`balance-leader` 与 `balance-region` 有着相似的调度流程： - -1. 根据不同 Store 的对应资源量的情况分别打分。 -2. 不断从得分较高的 Store 选择 Leader 或 Peer 迁移到得分较低的 Store 上。 - -两者的分数计算上也有一定差异：`balance-leader` 比较简单，使用 Store 上所有 Leader 所对应的 Region Size 加和作为得分。因为不同节点存储容量可能不一致，计算 `balance-region` 得分会分以下三种情况： - -- 当空间富余时使用数据量计算得分（使不同节点数据量基本上均衡） -- 当空间不足时由使用剩余空间计算得分（使不同节点剩余空间基本均衡） -- 处于中间态时则同时考虑两个因素做加权和当作得分 - -此外，为了应对不同节点可能在性能等方面存在差异的问题，还可为 Store 设置负载均衡的权重。`leader-weight` 和 `region-weight` 分别用于控制 Leader 权重以及 Region 权重（默认值都为 “1”）。假如把某个 Store 的 `leader-weight` 设为 “2”，调度稳定后，则该节点的 Leader 数量约为普通节点的 2 倍；假如把某个 Store 的 `region-weight` 设为 “0.5”，那么调度稳定后该节点的 Region 数量约为其他节点的一半。 - -### 热点调度 - -热点调度对应的调度器是 `hot-region-scheduler`。在 3.0 版本中，统计热点 Region 的方式为： - -1. 根据 Store 上报的信息，统计出持续一段时间读或写流量超过一定阈值的 Region。 -2. 用与负载均衡类似的方式把这些 Region 分散开来。 - -对于写热点，热点调度会同时尝试打散热点 Region 的 Peer 和 Leader；对于读热点，由于只有 Leader 承载读压力，热点调度会尝试将热点 Region 的 Leader 打散。 - -### 集群拓扑感知 - -让 PD 感知不同节点分布的拓扑是为了通过调度使不同 Region 的各个副本尽可能分散，保证高可用和容灾。PD 会在后台不断扫描所有 Region，当发现 Region 的分布不是当前的最优化状态时，会生成调度以替换 Peer，将 Region 调整至最佳状态。 - -负责这个检查的组件叫 `replicaChecker`（跟 Scheduler 类似，但是不可关闭）。它依赖于 `location-labels` 配置项来进行调度。比如配置 `[zone,rack,host]` 定义了三层的拓扑结构：集群分为多个 zone（可用区），每个 zone 下有多个 rack（机架），每个 rack 下有多个 host（主机）。PD 在调度时首先会尝试将 Region 的 Peer 放置在不同的 zone，假如无法满足（比如配置 3 副本但总共只有 2 个 zone）则保证放置在不同的 rack；假如 rack 的数量也不足以保证隔离，那么再尝试 host 级别的隔离，以此类推。 - -### 缩容及故障恢复 - -缩容是指预备将某个 Store 下线，通过命令将该 Store 标记为 “Offline“ 状态，此时 PD 通过调度将待下线节点上的 Region 迁移至其他节点。 - -故障恢复是指当有 Store 发生故障且无法恢复时，有 Peer 分布在对应 Store 上的 Region 会产生缺少副本的状况，此时 PD 需要在其他节点上为这些 Region 补副本。 - -这两种情况的处理过程基本上是一样的。`replicaChecker` 检查到 Region 存在异常状态的 Peer后，生成调度在健康的 Store 上创建新副本替换异常的副本。 - -### Region merge - -Region merge 指的是为了避免删除数据后大量小甚至空的 Region 消耗系统资源，通过调度把相邻的小 Region 合并的过程。Region merge 由 `mergeChecker` 负责，其过程与 `replicaChecker` 类似：PD 在后台遍历，发现连续的小 Region 后发起调度。 - -## 查询调度状态 - -你可以通过观察 PD 相关的 Metrics 或使用 pd-ctl 工具等方式查看调度系统状态。更具体的信息可以参考 [PD 监控](/v3.1/reference/key-monitoring-metrics/pd-dashboard.md)和 [PD Control](/v3.1/reference/tools/pd-control.md)。 - -### Operator 状态 - -**Grafana PD/Operator** 页面展示了 Operator 的相关统计信息。其中比较重要的有： - -- Schedule Operator Create：Operator 的创建情况 -- Operator finish duration：Operator 执行耗时的情况 -- Operator Step duration：不同 Operator Step 执行耗时的情况 - -查询 Operator 的 pd-ctl 命令有： - -- `operator show`：查询当前调度生成的所有 Operator -- `operator show [admin | leader | region]`：按照类型查询 Operator - -### Balance 状态 - -**Grafana PD/Statistics - Balance** 页面展示了负载均衡的相关统计信息，其中比较重要的有： - -- Store Leader/Region score：每个 Store 的得分 -- Store Leader/Region count：每个 Store 的 Leader/Region 数量 -- Store available：每个 Store 的剩余空间 - -使用 pd-ctl 的 `store` 命令可以查询 Store 的得分、数量、剩余空间和 weight 等信息。 - -### 热点调度状态 - -**Grafana PD/Statistics - hotspot** 页面展示了热点 Region 的相关统计信息，其中比较重要的有： - -- Hot write Region’s leader/peer distribution：写热点 Region 的 Leader/Peer 分布情况 -- Hot read Region’s leader distribution：读热点 Region 的 Leader 分布情况 - -使用 pd-ctl 同样可以查询上述信息，可以使用的命令有： - -- `hot read`：查询读热点 Region 信息 -- `hot write`：查询写热点 Region 信息 -- `hot store`：按 Store 统计热点分布情况 -- `region topread [limit]`：查询当前读流量最大的 Region -- `region topwrite [limit]`：查询当前写流量最大的 Region - -### Region 健康度 - -**Grafana PD/Cluster/Region health** 面板展示了异常 Region 的相关统计信息，包括 Pending Peer、Down Peer、Offline Peer，以及副本数过多或过少的 Region。 - -通过 pd-ctl 的 `region check` 命令可以查看具体异常的 Region 列表： - -- `region check miss-peer`：缺副本的 Region -- `region check extra-peer`：多副本的 Region -- `region check down-peer`：有副本状态为 Down 的 Region -- `region check pending-peer`：有副本状态为 Pending 的 Region - -## 调度策略控制 - -使用 pd-ctl 可以从以下三个方面来调整 PD 的调度策略。更具体的信息可以参考 [PD Control](/v3.1/reference/tools/pd-control.md)。 - -### 启停调度器 - -pd-ctl 支持动态创建和删除 Scheduler，你可以通过这些操作来控制 PD 的调度行为，如： - -- `scheduler show`：显示当前系统中的 Scheduler -- `scheduler remove balance-leader-scheduler`：删除（停用）balance region 调度器 -- `scheduler add evict-leader-scheduler-1`：添加移除 Store 1 的所有 Leader 的调度器 - -### 手动添加 Operator - -PD 支持直接通过 pd-ctl 来创建或删除 Operator，如： - -- `operator add add-peer 2 5`：在 Store 5 上为 Region 2 添加 Peer -- `operator add transfer-leader 2 5`：将 Region 2 的 Leader 迁移至 Store 5 -- `operator add split-region 2`：将 Region 2 拆分为 2 个大小相当的 Region -- `operator remove 2`：取消 Region 2 当前待执行的 Operator - -### 调度参数调整 - -使用 pd-ctl 执行 `config show` 命令可以查看所有的调度参数，执行 `config set {key} {value}` 可以调整对应参数的值。常见调整如下： - -- `leader-schedule-limit`：控制 Transfer Leader 调度的并发数 -- `region-schedule-limit`：控制增删 Peer 调度的并发数 -- `disable-replace-offline-replica`：停止处理节点下线的调度 -- `disable-location-replacement`：停止处理调整 Region 隔离级别相关的调度 -- `max-snapshot-count`：每个 Store 允许的最大收发 Snapshot 的并发数 - -## 典型场景分析与处理 - -该部分通过几个典型场景及其应对方式说明 PD 调度策略的最佳实践。 - -### Leader/Region 分布不均衡 - -PD 的打分机制决定了一般情况下，不同 Store 的 Leader Count 和 Region Count 不能完全说明负载均衡状态，所以需要从 TiKV 的实际负载或者存储空间占用来判断是否有负载不均衡的状况。 - -确认 Leader/Region 分布不均衡后，首先观察不同 Store 的打分情况。 - -如果不同 Store 的打分是接近的，说明 PD 认为此时已经是均衡状态了，可能的原因有： - -- 存在热点导致负载不均衡。可以参考[热点分布不均匀](#热点分布不均匀)中的解决办法进行分析处理。 -- 存在大量空 Region 或小 Region，因此不同 Store 的 Leader 数量差别特别大，导致 Raftstore 负担过重。此时需要开启 [Region Merge](#region-merge) 并尽可能加速合并。 -- 不同 Store 的软硬件环境存在差异。可以酌情调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 -- 其他不明原因。仍可以通过调整 `leader-weight` 和 `region-weight` 来控制 Leader/Region 的分布。 - -如果不同 Store 的分数差异较大，需要进一步检查 Operator 的相关 Metrics，特别关注 Operator 的生成和执行情况，这时大体上又分两种情况： - -- 生成的调度是正常的，但是调度的速度很慢。可能的原因有： - - - 调度速度受限于 limit 配置。PD 默认配置的 limit 比较保守，在不对正常业务造成显著影响的前提下，可以酌情将 `leader-schedule-limit` 或 `region-schedule-limit` 调大一些。此外， `max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 - - 系统中同时运行有其他的调度任务产生竞争，导致 balance 速度上不去。这种情况下如果 balance 调度的优先级更高，可以先停掉其他的调度或者限制其他调度的速度。例如 Region 没均衡的情况下做下线节点操作，下线的调度与 Region Balance 会抢占 `region-schedule-limit` 配额，此时你可以调小 `replica-schedule-limit` 以限制下线调度的速度，或者设置 `disable-replace-offline-replica = true` 来暂时关闭下线流程。 - - 调度执行得太慢。可以通过 **Operator step duration** 进行判断。通常不涉及到收发 Snapshot 的 Step（比如 `TransferLeader`，`RemovePeer`，`PromoteLearner` 等）的完成时间应该在毫秒级，涉及到 Snapshot 的 Step（如 `AddLearner`，`AddPeer` 等）的完成时间为数十秒。如果耗时明显过高，可能是 TiKV 压力过大或者网络等方面的瓶颈导致的，需要具体情况具体分析。 - -- 没能生成对应的 balance 调度。可能的原因有： - - - 调度器未被启用。比如对应的 Scheduler 被删除了，或者 limit 被设置为 “0”。 - - 由于其他约束无法进行调度。比如系统中有 `evict-leader-scheduler`，此时无法把 Leader 迁移至对应的 Store。再比如设置了 Label property，也会导致部分 Store 不接受 Leader。 - - 集群拓扑的限制导致无法均衡。比如 3 副本 3 数据中心的集群，由于副本隔离的限制，每个 Region 的 3 个副本都分别分布在不同的数据中心，假如这 3 个数据中心的 Store 数不一样，最后调度就会收敛在每个数据中心均衡，但是全局不均衡的状态。 - -### 节点下线速度慢 - -这个场景需要从 Operator 相关的 Metrics 入手，分析 Operator 的生成执行情况。 - -如果调度在正常生成，只是速度很慢，可能的原因有： - -- 调度速度受限于 limit 配置。可以适当调大 `replica-schedule-limit`，`max-pending-peer-count` 以及 `max-snapshot-count` 限制也可以放宽。 -- 系统中同时运行有其他的调度任务产生竞争。处理方法参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡)。 -- 下线单个节点时，由于待操作的 Region 有很大一部分（3 副本配置下约 1/3）的 Leader 都集中在下线的节点上，下线速度会受限于这个单点生成 Snapshot 的速度。你可以通过手动给该节点添加一个 `evict-leader-scheduler` 调度器迁走 Leader 来加速。 - -如果没有对应的 Operator 调度生成，可能的原因有： - -- 下线调度被关闭，或者 `replica-schedule-limit` 被设为 “0”。 -- 找不到节点来转移 Region。例如相同 Label 的替代节点可用容量都不足 20%，PD 为了避免爆盘的风险会停止调度。这种情况需要添加更多节点，或者删除一些数据释放空间。 - -### 节点上线速度慢 - -目前 PD 没有对节点上线特殊处理。节点上线实际上是依靠 balance region 机制来调度的，所以参考[Leader/Region 分布不均衡](#leaderregion-分布不均衡) 中的排查步骤即可。 - -### 热点分布不均匀 - -热点调度的问题大体上可以分为以下几种情况： - -- 从 PD 的 Metrics 能看出来有不少 hot Region，但是调度速度跟不上，不能及时地把热点 Region 分散开来。 - - **解决方法**：调大 `hot-region-schedule-limit` 并减少其他调度器的 limit 配额，从而加快热点调度的速度。还可调小 `hot-region-cache-hits-threshold` 使 PD 对更快响应流量的变化。 - -- 单一 Region 形成热点，比如大量请求频繁 scan 一个小表，这个可以从业务角度或者 Metrics 统计的热点信息看出来。由于单 Region 热点现阶段无法使用打散的手段来消除，需要确认热点 Region 后手动添加 `split-region` 调度将这样的 Region 拆开。 - -- 从 PD 的统计来看没有热点，但是从 TiKV 的相关 Metrics 可以看出部分节点负载明显高于其他节点，成为整个系统的瓶颈。这是因为目前 PD 统计热点 Region 的维度比较单一，仅针对流量进行分析，在某些场景下无法准确定位热点。例如部分 Region 有大量的点查请求，从流量上来看并不显著，但是过高的 QPS 导致关键模块达到瓶颈。 - - **解决方法**：首先从业务层面确定形成热点的 table，然后添加 `scatter-range-scheduler` 调度器使这个 table 的所有 Region 均匀分布。TiDB 也在其 HTTP API 中提供了相关接口来简化这个操作，具体可以参考 [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) 文档。 - -### Region Merge 速度慢 - -Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-schedule-limit` 及 `region-schedule-limit`），或者是与其他调度器产生了竞争。具体来说，可有如下处理方式： - -- 假如已经从相关 Metrics 得知系统中有大量的空 Region，这时可以通过把 `max-merge-region-size` 和 `max-merge-region-keys` 调整为较小值来加快 Merge 速度。这是因为 Merge 的过程涉及到副本迁移，所以 Merge 的 Region 越小，速度就越快。如果生成 Merge Operator 的速度很快，想进一步加快 Region Merge 过程，还可以把 `patrol-region-interval` 调整为 "10ms" ，这个能加快巡检 Region 的速度，但是会消耗更多的 CPU 资源。 - -- 创建过大量 Table 后（包括执行 `Truncate Table` 操作）又清空了。此时如果开启了 split table 特性，这些空 Region 是无法合并的，此时需要调整以下参数关闭这个特性： - - - TiKV: `split-region-on-table` 设为 false - - PD: `namespace-classifier` 设为 “” - -- 对于 3.0.4 和 2.1.16 以前的版本，Region 中 Key 的个数（`approximate_keys`）在特定情况下（大部分发生在删表之后）统计不准确，造成 keys 的统计值很大，无法满足 `max-merge-region-keys` 的约束。你可以通过调大 `max-merge-region-keys` 来避免这个问题。 - -### TiKV 节点故障处理策略 - -没有人工介入时，PD 处理 TiKV 节点故障的默认行为是，等待半小时之后（可通过 `max-store-down-time` 配置调整），将此节点设置为 Down 状态，并开始为涉及到的 Region 补充副本。 - -实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 diff --git a/v3.1/reference/configuration/pd-server/configuration-file.md b/v3.1/reference/configuration/pd-server/configuration-file.md deleted file mode 100644 index 5748adc94007..000000000000 --- a/v3.1/reference/configuration/pd-server/configuration-file.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: PD 配置文件描述 -category: reference ---- - -# PD 配置文件描述 - - - -PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/config.toml](https://github.com/pingcap/pd/blob/master/conf/config.toml) 找到默认的配置文件。 - -本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [PD 配置参数](/v3.1/reference/configuration/pd-server/configuration.md)。 - -### `lease` - -+ PD Leader Key 租约超时时间，超时系统重新选举 Leader。 -+ 默认：3 -+ 单位：秒 - -### `tso-save-interval` - -+ TSO 分配的时间窗口,实时持久存储。 -+ 默认：3s - -### `initial-cluster-state` - -+ 集群初始状态 -+ 默认：new - -### `enable-prevote` - -+ 开启 raft prevote 的开关。 -+ 默认：true - -### `quota-backend-bytes` - -+ 元信息数据库存储空间的大小，默认 2GB。 -+ 默认：2147483648 - -### `auto-compaction-mod` - -+ 元信息数据库自动压缩的模式，可选项为 periodic（按周期），revision（按版本数）。 -+ 默认：periodic - -### `auto-compaction-retention` - -+ compaction-mode 为 periodic 时为元信息数据库自动压缩的间隔时间；compaction-mode 设置为 revision 时为自动压缩的版本数。 -+ 默认：1h - -### `force-new-cluster` - -+ 强制让该 PD 以一个新集群启动，且修改 raft 成员数为 1。 -+ 默认：false - -### `tick-interval` - -+ etcd raft 的 tick 周期。 -+ 默认：100ms - -### `election-interval` - -+ etcd leader 选举的超时时间。 -+ 默认：3s - -### `use-region-storage` - -+ 开启独立的 region 存储。 -+ 默认：false - -## security - -安全相关配置项。 - -### `cacert-path` - -+ CA 文件路径 -+ 默认："" - -### `cert-path` - -+ 包含 X509 证书的 PEM 文件路径 -+ 默认："" - -### `key-path` - -+ 包含 X509 key 的 PEM 文件路径 -+ 默认："" - -## log - -日志相关的配置项。 - -### `format` - -+ 日志格式，可指定为"text"，"json"， "console"。 -+ 默认：text - -### `disable-timestamp` - -+ 是否禁用日志中自动生成的时间戳。 -+ 默认：false - -## log.file - -日志文件相关的配置项。 - -### `max-size` - -+ 单个日志文件最大大小，超过该值系统自动切分成多个文件。 -+ 默认：300 -+ 单位：MiB -+ 最小值为 1 - -### `max-days` - -+ 日志保留的最长天数。 -+ 默认: 28 -+ 最小值为 1 - -### `max-backups` - -+ 日志文件保留的最大个数。 -+ 默认: 7 -+ 最小值为 1 - -## metric - -监控相关的配置项。 - -### `interval` - -+ 向 promethus 推送监控指标数据的间隔时间。 -+ 默认: 15s - -## schedule - -调度相关的配置项。 - -### `max-merge-region-size` - -+ 控制 Region Merge 的 size 上限，当 Region Size 大于指定值时 PD 不会将其与相邻的 Region 合并。 -+ 默认: 20 - -### `max-merge-region-keys` - -+ 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 -+ 默认: 200000 - -### `patrol-region-interval` - -+ 控制 replicaChecker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整 -+ 默认: 100ms - -### `split-merge-interval` - -+ 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。 -+ 默认: 1h - -### `max-snapshot-count` - -+ 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。 -+ 默认: 3 - -### `max-pending-peer-count` - -+ 控制单个 store 的 pending peer 上限，调度受制于这个配置来防止在部分节点产生大量日志落后的 Region。 -+ 默认：16 - -### `max-store-down-time` - -+ PD 认为失联 store 无法恢复的时间，当超过指定的时间没有收到 store 的心跳后，PD 会在其他节点补充副本。 -+ 默认：30m - -### `leader-schedule-limit` - -+ 同时进行 leader 调度的任务个数。 -+ 默认：4 - -### `region-schedule-limit` - -+ 同时进行 Region 调度的任务个数 -+ 默认：4 - -### `replica-schedule-limit` - -+ 同时进行 replica 调度的任务个数。 -+ 默认：8 - -### `merge-schedule-limit` - -+ 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 -+ 默认：8 - -### `high-space-ratio` - -+ 设置 store 空间充裕的阈值。 -+ 默认：0.6 -+ 最小值：大于 0 -+ 最大值：小于 1 - -### `low-space-ratio` - -+ 设置 store 空间不足的阈值。 -+ 默认：0.8 -+ 最小值：大于 0 -+ 最大值：小于 1 - -### `tolerant-size-ratio` - -+ 控制 balance 缓冲区大小。 -+ 默认：5 -+ 最小值：0 - -### `disable-remove-down-replica` - -+ 关闭自动删除 DownReplica 的特性的开关，当设置为 true 时，PD 不会自动清理宕机状态的副本。 -+ 默认：false - -### `disable-replace-offline-replica` - -+ 关闭迁移 OfflineReplica 的特性的开关，当设置为 true 时，PD 不会迁移下线状态的副本。 -+ 默认：false - -### `disable-make-up-replica` - -+ 关闭补充副本的特性的开关，当设置为 true 时，PD 不会为副本数不足的 Region 补充副本。 -+ 默认：false - -### `disable-remove-extra-replica` - -+ 关闭删除多余副本的特性开关，当设置为 true 时，PD 不会为副本数过多的 Region 删除多余副本。 -+ 默认：false - -### `disable-location-replacement` - -+ 关闭隔离级别检查的开关，当设置为 true 时，PD 不会通过调度来提升 Region 副本的隔离级别。 -+ 默认：false - -## replication - -副本相关的配置项。 - -### `max-replicas` - -+ 副本数量。 -+ 默认：3 - -### `location-labels` - -+ TiKV 集群的拓扑信息。 -+ 默认：[] - -## label-property - -标签相关的配置项。 - -### `key` - -+ 拒绝 leader 的 store 带有的 label key。 -+ 默认："" - -### `value` - -+ 拒绝 leader 的 store 带有的 label value。 -+ 默认："" diff --git a/v3.1/reference/configuration/pd-server/configuration.md b/v3.1/reference/configuration/pd-server/configuration.md deleted file mode 100644 index c49a4d81d19d..000000000000 --- a/v3.1/reference/configuration/pd-server/configuration.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: PD 配置参数 -category: reference ---- - -# PD 配置参数 - -PD 可以通过命令行参数或环境变量配置。 - -## `--advertise-client-urls` - -+ 对外客户端访问 URL 列表。 -+ 默认：`${client-urls}` -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，客户端并不能通过 PD 自己监听的 client URLs 来访问到 PD，这时候，你就可以设置 advertise urls 来让客户端访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 `-p 2379:2379`，那么可以设置为 `--advertise-client-urls="http://192.168.100.113:2379"`，客户端可以通过 `http://192.168.100.113:2379` 来找到这个服务。 - -## `--advertise-peer-urls` - -+ 对外其他 PD 节点访问 URL 列表。 -+ 默认：`${peer-urls}` -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，其他节点并不能通过 PD 自己监听的 peer URLs 来访问到 PD，这时候，你就可以设置 advertise urls 来让其他节点访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 `-p 2380:2380`，那么可以设置为 `--advertise-peer-urls="http://192.168.100.113:2380"`，其他 PD 节点可以通过 `http://192.168.100.113:2380` 来找到这个服务。 - -## `--client-urls` - -+ 处理客户端请求监听 URL 列表。 -+ 默认：`http://127.0.0.1:2379` -+ 如果部署一个集群，\-\-client-urls 必须指定当前主机的 IP 地址，例如 `http://192.168.100.113:2379"`，如果是运行在 docker 则需要指定为 `http://0.0.0.0:2379`。 - -## `--peer-urls` - -+ 处理其他 PD 节点请求监听 URL 列表。 -+ default: `http://127.0.0.1:2380` -+ 如果部署一个集群，\-\-peer-urls 必须指定当前主机的 IP 地址，例如 `http://192.168.100.113:2380`，如果是运行在 docker 则需要指定为 `http://0.0.0.0:2380`。 - -## `--config` - -+ 配置文件。 -+ 默认："" -+ 如果你指定了配置文件，PD 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，PD 就会使用命令行参数的配置来覆盖配置文件里面的。 - -## `--data-dir` - -+ PD 存储数据路径。 -+ 默认：`default.${name}` - -## `--initial-cluster` - -+ 初始化 PD 集群配置。 -+ 默认：`{name}=http://{advertise-peer-url}` -+ 例如，如果 name 是 "pd", 并且 `advertise-peer-urls` 是 `http://192.168.100.113:2380`, 那么 `initial-cluster` 就是 `pd=http://192.168.100.113:2380`。 -+ 如果你需要启动三台 PD，那么 `initial-cluster` 可能就是 - `pd1=http://192.168.100.113:2380, pd2=http://192.168.100.114:2380, pd3=192.168.100.115:2380`。 - -## `--join` - -+ 动态加入 PD 集群。 -+ 默认："" -+ 如果你想动态将一台 PD 加入集群，你可以使用 `--join="${advertise-client-urls}"`， `advertise-client-url` 是当前集群里面任意 PD 的 `advertise-client-url`，你也可以使用多个 PD 的，需要用逗号分隔。 - -## `-L` - -+ Log 级别。 -+ 默认："info" -+ 我们能选择 debug, info, warn, error 或者 fatal。 - -## `--log-file` - -+ Log 文件。 -+ 默认："" -+ 如果没设置这个参数，log 会默认输出到 "stderr"，如果设置了，log 就会输出到对应的文件里面，在每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份。 - -## `--log-rotate` - -+ 是否开启日志切割。 -+ 默认：true -+ 当值为 true 时,按照 PD 配置文件中 `[log.file]` 信息执行。 - -## `--name` - -+ 当前 PD 的名字。 -+ 默认："pd" -+ 如果你需要启动多个 PD，一定要给 PD 使用不同的名字 - -## `--cacert` - -+ CA 文件路径，用于开启 TLS。 -+ 默认："" - -## `--cert` - -+ 包含 X509 证书的 PEM 文件路径，用户开启 TLS。 -+ 默认："" - -## `--key` - -+ 包含 X509 key 的 PEM 文件路径，用于开启 TLS。 -+ 默认："" - -## `--namespace-classifier` - -+ 指定 PD 使用的 namespace 分类器。 -+ 默认："table" -+ 如果 TiKV 不与 TiDB 集群配合运行，建议配置为 'default'。 - -## `--metrics-addr` - -+ 指定 Prometheus Pushgateway 的地址。 -+ 默认："" -+ 如果留空，则不开启 Prometheus Push。 - -## `--force-new-cluster` - -+ 强制使用当前节点创建新的集群。 -+ 默认：false -+ 仅用于在 PD 丢失多数副本的情况下恢复服务，可能会产生部分数据丢失。 - -## `-V`, `--version` - -+ 输出版本信息并退出。 diff --git a/v3.1/reference/configuration/tidb-server/configuration-file.md b/v3.1/reference/configuration/tidb-server/configuration-file.md deleted file mode 100644 index a3007f2625f6..000000000000 --- a/v3.1/reference/configuration/tidb-server/configuration-file.md +++ /dev/null @@ -1,422 +0,0 @@ ---- -title: TiDB 配置文件描述 -category: reference ---- - - - -# TiDB 配置文件描述 - -TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/config.toml.example](https://github.com/pingcap/tidb/blob/release-3.0/config/config.toml.example) 找到默认值的配置文件，重命名为 `config.toml` 即可。本文档只介绍未包含在[命令行参数](https://pingcap.com/docs-cn/v3.1/reference/configuration/tidb-server/configuration)中的参数。 - -### `split-table` - -+ 为每个 table 建立单独的 Region。 -+ 默认值：true -+ 如果需要创建大量的表，我们建议把这个参数设置为 false。 - -### `oom-action` - -+ 指定 TiDB 发生 out-of-memory 错误时的操作。 -+ 默认值："log" -+ 现在合法的选项是 ["log", "cancel"]，如果为 "log"，仅仅是打印日志，不作实质处理。如果为 "cancel"，我们会取消执行这个操作，并且输出日志。 - -### `mem-quota-query` - -+ 单条 SQL 语句可以占用的最大内存阈值。 -+ 默认值：34359738368 -+ 超过该值的请求会被 `oom-action` 定义的行为所处理。 - -### `enable-streaming` - -+ 开启 coprocessor 的 streaming 获取数据模式。 -+ 默认值：false - -### `lower-case-table-names` - -+ 这个选项可以设置 TiDB 的系统变量 `lower_case_table_names` 的值。 -+ 默认值：2 -+ 具体可以查看 MySQL 关于这个变量的[描述](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_lower_case_table_names) - -> **注意：** -> -> 目前 TiDB 只支持将该选项的值设为 2，即按照大小写来保存表名，按照小写来比较（不区分大小写）。 - -### `lease` - -+ DDL 租约超时时间。 -+ 默认值：45s -+ 单位：秒 - -### `compatible-kill-query` - -+ 设置 `KILL` 语句的兼容性。 -+ 默认值：false -+ TiDB 中 `KILL xxx` 的行为和 MySQL 中的行为不相同。为杀死一条查询，在 TiDB 里需要加上 `TIDB` 关键词，即 `KILL TIDB xxx`。但如果把 `compatible-kill-query` 设置为 true，则不需要加上 `TIDB` 关键词。 -+ 这种区别很重要，因为当用户按下 Ctrl+C 时，MySQL 命令行客户端的默认行为是：创建与后台的新连接，并在该新连接中执行 `KILL` 语句。如果负载均衡器或代理已将该新连接发送到与原始会话不同的 TiDB 服务器实例，则该错误会话可能被终止，从而导致使用 TiDB 集群的业务中断。只有当您确定在 `KILL` 语句中引用的连接正好位于 `KILL` 语句发送到的服务器上时，才可以启用 `compatible-kill-query`。 - -### `check-mb4-value-in-utf8` - -+ 开启检查 utf8mb4 字符的开关，如果开启此功能，字符集是 utf8，且在 utf8 插入 mb4 字符，系统将会报错。 -+ 默认值：true - -### `treat-old-version-utf8-as-utf8mb4` - -+ 将旧表中的 utf8 字符集当成 utf8mb4的开关。 -+ 默认值：true - -### `alter-primary-key` - -+ 用于控制添加或者删除主键功能。 -+ 默认值：false -+ 默认情况下，不支持增删主键。将此变量被设置为 true 后，支持增删主键功能。不过对在此开关开启前已经存在的表，且主键是整型类型时，即使之后开启此开关也不支持对此列表删除主键。 - -## log - -日志相关的配置项。 - -### `format` - -+ 指定日志输出的格式，可选项为 [json, text, console]。 -+ 默认值："text" - -### `disable-timestamp` - -+ 是否禁止在日志中输出时间戳。 -+ 默认值：false -+ 如果设置为 true，那么日志里面将不会输出时间戳。 - -### `slow-query-file` - -+ 慢查询日志的文件名。 -+ 默认值："tidb-slow.log"，注：由于 TiDB V2.1.8 更新了慢日志格式，所以将慢日志单独输出到了慢日志文件。V2.1.8 之前的版本，该变量的默认值是 ""。 -+ 设置后，慢查询日志会单独输出到该文件。 - -### `slow-threshold` - -+ 输出慢日志的耗时阈值。 -+ 默认值：300ms -+ 当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。 - -### `expensive-threshold` - -+ 输出 `expensive` 操作的行数阈值。 -+ 默认值：10000 -+ 当查询的行数（包括中间结果，基于统计信息）大于这个值，我们就会当成是一个 `expensive` 的操作，输出一个前缀带有 `[EXPENSIVE_QUERY]` 的日志。 - -### `query-log-max-len` - -+ 最长的 SQL 输出长度。 -+ 默认值：2048 -+ 当语句的长度大于 `query-log-max-len`，将会被截断输出。 - -## log.file - -日志文件相关的配置项。 - -#### `filename` - -+ 一般日志文件名字。 -+ 默认值："" -+ 如果设置，会输出一般日志到这个文件。 - -#### `max-size` - -+ 日志文件的大小限制。 -+ 默认值：300MB -+ 最大设置上限为 4GB。 - -#### `max-days` - -+ 日志最大保留的天数。 -+ 默认值：0 -+ 默认不清理；如果设置了参数值，在 `max-days` 之后 TiDB 会清理过期的日志文件。 - -#### `max-backups` - -+ 保留的日志的最大数量。 -+ 默认值：0 -+ 默认全部保存；如果设置为 7，会最多保留 7 个老的日志文件。 - -#### `log-rotate` - -+ 是否每日创建一个新的日志文件。 -+ 默认值：true -+ 如果设置为 true，每天会新建新的日志文件，如果设置为 false，那么只会输出到一个日志文件。 - -## security - -安全相关配置。 - -### `ssl-ca` - -+ PEM 格式的受信任 CA 的证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-cert`、`--ssl-key` 选项时，TiDB 将在客户端出示证书的情况下根据该选项指定的受信任的 CA 列表验证客户端证书。若验证失败，则连接会被终止。 -+ 即使设置了该选项，若客户端没有出示证书，则安全连接仍然继续，不会进行客户端证书验证。 - -### `ssl-cert` - -+ PEM 格式的 SSL 证书文件路径。 -+ 默认值："" -+ 当同时设置了该选项和 `--ssl-key` 选项时，TiDB 将接受（但不强制）客户端使用 TLS 安全地连接到 TiDB。 -+ 若指定的证书或私钥无效，则 TiDB 会照常启动，但无法接受安全连接。 - -### `ssl-key` - -+ PEM 格式的 SSL 证书密钥文件路径，即 `--ssl-cert` 所指定的证书的私钥。 -+ 默认值："" -+ 目前 TiDB 不支持加载由密码保护的私钥。 - -### `cluster-ssl-ca` - -+ CA 根证书，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-cert` - -+ ssl 证书文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `cluster-ssl-key` - -+ ssl 私钥文件路径，用于用 tls 连接 TiKV/PD -+ 默认值："" - -### `skip-grant-table` - -+ 是否跳过权限检查 -+ 默认值：false - -## performance - -性能相关配置。 - -### `max-procs` - -+ TiDB 的 CPU 使用数量。 -+ 默认值：0 -+ 默认值为 0 表示使用机器上所有的 CPU；如果设置成 n，那么 TiDB 会使用 n 个 CPU 数量。 - -### `max-memory` - -+ Prepare cache LRU 使用的最大内存限制，超过 performance.max-memory * (1 - prepared-plan-cache.memory-guard-ratio)会 剔除 LRU 中的元素。 -+ 默认值：0 -+ 这个配置只有在 prepared-plan-cache.enabled 为 true 的情况才会生效。在 LRU 的 size 大于 prepared-plan-cache.capacity 的情况下，也会剔除 LRU 中的元素。 - -### `stmt-count-limit` - -+ TiDB 一个事务允许的最大语句条数限制。 -+ 默认值：5000 -+ 在一个事务中，超过 `stmt-count-limit` 条语句后还没有 rollback 或者 commit，TiDB 将会返回 `statement count 5001 exceeds the transaction limitation, autocommit = false` 错误。 - -### `tcp-keep-alive` - -+ TiDB 在 TCP 层开启 keepalive。 -+ 默认值：false - -### `cross-join` - -+ 默认值：true -+ 默认可以执行在做 join 时两边表没有任何条件（where 字段）的语句；如果设置为 false，则有这样的 join 语句出现时，server 会拒绝执行 - -### `stats-lease` - -+ TiDB 重载统计信息，更新表行数，检查是否需要自动 analyze，利用 feedback 更新统计信息以及加载列的统计信息的时间间隔。 -+ 默认值：3s - - 每隔 `stats-lease` 时间，TiDB 会检查统计信息是否有更新，如果有会将其更新到内存中 - - 每隔 `20 * stats-lease` 时间，TiDB 会将 DML 产生的总行数以及修改的行数变化更新到系统表中 - - 每隔 `stats-lease` 时间，TiDB 会检查是否有表或者索引需要自动 analyze - - 每隔 `stats-lease` 时间，TiDB 会检查是否有列的统计信息需要被加载到内存中 - - 每隔 `200 * stats-lease` 时间，TiDB 会将内存中缓存的 feedback 写入系统表中 - - 每隔 `5 * stats-lease` 时间，TiDB 会读取系统表中的 feedback，更新内存中缓存的统计信息 -+ 当 `stats-lease` 为 0 时，TiDB 会以 3s 的时间间隔周期性的读取系统表中的统计信息并更新内存中缓存的统计信息。但不会自动修改统计信息相关系统表，具体来说，TiDB 不再自动修改这些表： - - `mysql.stats_meta`：TiDB 不再自动记录事务中对某张表的修改行数，也不会更新到这个系统表中 - - `mysql.stats_histograms`/`mysql.stats_buckets` 和 `mysql.stats_top_n`：TiDB 不再自动 analyze 和主动更新统计信息 - - `mysql.stats_feedback`：TiDB 不再根据被查询的数据反馈的部分统计信息更新表和索引的统计信息，analyze 以及 feedback 等操作都不会再进行。 - -### `run-auto-analyze` - -+ TiDB 是否做自动的 Analyze。 -+ 默认值：true - -### `feedback-probability` - -+ TiDB 对查询收集统计信息反馈的概率。 -+ 默认值：0.05 -+ 对于每一个查询，TiDB 会以 `feedback-probability` 的概率收集查询的反馈，用于更新统计信息。 - -### `query-feedback-limit` - -+ 在内存中缓存的最大 Query Feedback 数量，超过这个数量的 Feedback 会被丢弃。 -+ 默认值：1024 - -### `pseudo-estimate-ratio` - -+ 修改过的行数/表的总行数的比值，超过该值时系统会认为统计信息已经过期，会采用 pseudo 的统计信息。 -+ 默认值：0.8 -+ 最小值为 0；最大值为 1。 - -### `force-priority` - -+ 把所有的语句优先级设置为 force-priority 的值。 -+ 默认值：NO_PRIORITY -+ 可选值：NO_PRIORITY, LOW_PRIORITY, HIGH_PRIORITY, DELAYED。 - -## prepared-plan-cache - -prepare 语句的 Plan cache 设置。 - -### `enabled` - -+ 开启 prepare 语句的 plan cache。 -+ 默认值：false - -### `capacity` - -+ 缓存语句的数量。 -+ 默认值：100 - -### `memory-guard-ratio` - -+ 用于防止超过 performance.max-memory, 超过 max-proc * (1 - prepared-plan-cache.memory-guard-ratio)会剔除 LRU 中的元素。 -+ 默认值：0.1 -+ 最小值为 0；最大值为 1。 - -## tikv-client - -### `grpc-connection-count` - -+ 跟每个 TiKV 之间建立的最大连接数。 -+ 默认值：16 - -### `grpc-keepalive-time` - -+ TiDB 与 TiKV 节点之间 rpc 连接 keepalive 时间间隔，如果超过该值没有网络包，grpc client 会 ping 一下 TiKV 查看是否存活。 -+ 默认值：10 -+ 单位：秒 - -### `grpc-keepalive-timeout` - -+ TiDB 与 TiKV 节点 rpc keepalive 检查的超时时间 -+ 默认值：3 -+ 单位：秒 - -### `commit-timeout` - -+ 执行事务提交时，最大的超时时间。 -+ 默认值：41s -+ 这个值必须是大于两倍 Raft 选举的超时时间。 - -### `max-txn-time-use` - -+ 单个事务允许的最大执行时间。 -+ 默认值：590 -+ 单位：秒 - -### `max-batch-size` - -+ 批量发送 rpc 封包的最大数量，如果不为 0，将使用 BatchCommands api 发送请求到 TiKV，可以在并发度高的情况降低 rpc 的延迟，推荐不修改该值。 -+ 默认值：128 - -### `max-batch-wait-time` - -+ 等待 `max-batch-wait-time` 纳秒批量将此期间的数据包封装成一个大包发送给 TiKV 节点，仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 -+ 默认值：0 -+ 单位：纳秒 - -### `batch-wait-size` - -+ 批量向 TiKV 发送的封包最大数量，不推荐修改该值。 -+ 默认值：8 -+ 若此值为 0 表示关闭此功能。 - -### `overload-threshold` - -+ TiKV 的负载阈值，如果超过此阈值，会收集更多的 batch 封包，来减轻 TiKV 的压力。仅在 `tikv-client.max-batch-size` 值大于 0 时有效，不推荐修改该值。 -+ 默认值：200 - -## txn-local-latches - -事务内存锁相关配置，当本地事务冲突比较多时建议开启。 - -### `enable` - -+ 开启 -+ 默认值：false - -### `capacity` - -+ Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。 -+ 默认值：2048000 - -## binlog - -TiDB Binlog 相关配置。 - -### `enable` - -+ 开启 binlog 开关。 -+ 默认值：false - -### `write-timeout` - -+ 写 binlog 的超时时间，推荐不修改该值。 -+ 默认值：15s -+ 单位：秒 - -### `ignore-error` - -+ 忽略写 binlog 发生的错误时处理开关，推荐不修改该值。 -+ 默认值：false -+ 如果设置为 `true`，发生错误时，TiDB 会停止写入 binlog，并且在监控项 `tidb_server_critical_error_total` 上计数加 1；如果设置为 `false`，写入 binlog 失败，会停止整个 TiDB 的服务。 - -### `binlog-socket` - -+ binlog 输出网络地址。 -+ 默认值："" - -### `strategy` - -+ binlog 输出时选择 pump 的策略，仅支持 hash ，range 方法。 -+ 默认值："range" - -## status - -TiDB 服务状态相关配置。 - -### `report-status` - -+ 开启 HTTP API 服务的开关。 -+ 默认值：true - -### `record-db-qps` - -+ 输与 database 相关的 QPS metrics 到 Prometheus 的开关。 -+ 默认值：false - -## stmt-summary 从 v3.0.4 版本开始引入 - -系统表 `events_statement_summary_by_digest` 的相关配置。 - -### max-stmt-count - -+ `events_statement_summary_by_digest` 表中保存的 SQL 种类的最大数量。 -+ 默认值：100 - -### max-sql-length - -+ `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 -+ 默认值：4096 - -## pessimistic-txn - -### enable - -+ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/v3.1/reference/transactions/transaction-pessimistic.md)。 -+ 默认值：true - -### max-retry-count - -+ 悲观事务中每个语句最大重试次数，超出该限制将会报错。 -+ 默认值：256 diff --git a/v3.1/reference/configuration/tidb-server/configuration.md b/v3.1/reference/configuration/tidb-server/configuration.md deleted file mode 100644 index ed7ed9e014ce..000000000000 --- a/v3.1/reference/configuration/tidb-server/configuration.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: TiDB 命令行参数 -category: reference ---- - -# TiDB 命令行参数 - -在启动 TiDB 时，你可以使用命令行参数或环境变量来配置 TiDB。本文将详细介绍 TiDB 的命令行启动参数。TiDB 的默认端口为 4000（客户端请求）与 10080（状态报告）。 - -## `--advertise-address` - -+ 登录 TiDB 的 IP 地址 -+ 默认："" -+ 必须确保用户和集群中的其他机器都能够访问到该 IP 地址 - -## `--binlog-socket` - -+ TiDB 服务使用 unix socket file 方式接受内部连接，如 Pump 服务 -+ 默认："" -+ 例如，可以使用 "/tmp/pump.sock" 来接受 Pump unix socket file 通信 - -## `--config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiDB 会首先读取配置文件的配置。如果对应的配置在命令行参数里面也存在，TiDB 就会使用命令行参数的配置来覆盖配置文件中的配置。详细的配置项请参阅 [TiDB 配置文件描述](/v3.1/reference/configuration/tidb-server/configuration-file.md)。 - -## `--cors` - -+ 用于设置 TiDB HTTP 状态服务的 Access-Control-Allow-Origin -+ 默认："" - -## `--host` - -+ TiDB 服务监听的 host -+ 默认："0.0.0.0" -+ 0.0.0.0 默认会监听所有的网卡地址。如果有多块网卡，可以指定对外提供服务的网卡，如 192.168.100.113 - -## `-L` - -+ Log 级别 -+ 默认："info" -+ 可选项为：debug、info、warn、error、fatal - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 "stderr"；如果设置了该参数，log 会输出到对应的文件中。每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--log-slow-query` - -+ 慢查询日志文件路径 -+ 默认："" -+ 如果未设置该参数，log 会默认输出到 `--log-file` 指定的文件中 - -## `--metrics-addr` - -+ Prometheus Pushgateway 地址 -+ 默认："" -+ 如果该参数为空，TiDB 不会将统计信息推送给 Pushgateway。参数格式示例：`--metrics-addr=192.168.100.115:9091` - -## `--metrics-interval` - -+ 推送统计信息到 Prometheus Pushgateway 的时间间隔 -+ 默认：15s -+ 设置为 0 表示不推送统计信息给 Pushgateway。示例：`--metrics-interval=2` 指每两秒推送到 Pushgateway - -## `-P` - -+ TiDB 服务监听端口 -+ 默认："4000" -+ TiDB 服务会使用该端口接受 MySQL 客户端发来的请求 - -## `--path` - -+ 对于本地存储引擎 "mocktikv" 来说，path 指定的是实际的数据存放路径 -+ 当 `--store = tikv` 时，必须指定 path；当 `--store = mocktikv` 时，如果不指定 path，会使用默认值。 -+ 对于 "TiKV" 存储引擎来说，path 指定的是实际的 PD 地址。假如在 192.168.100.113:2379、192.168.100.114:2379 和 192.168.100.115:2379 上面部署了 PD，那么 path 为 "192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379" -+ 默认："/tmp/tidb" -+ 可以通过 `tidb-server --store=mocktikv --path=""` 来启动一个纯内存引擎的 TiDB - -## `--proxy-protocol-networks` - -+ PROXY Protocol 允许的代理服务器地址列表。如需配置多个地址，用 `,` 分隔。 -+ 默认："" -+ 如果该参数为空，TiDB 会禁用 PROXY Protocol 功能。地址可以使用 IP 地址 (192.168.1.50) 或者 CIDR (192.168.1.0/24)，`*` 代表所有地址。 - -## `--proxy-protocol-header-timeout` - -+ PROXY Protocol 请求头读取超时时间 -+ 默认：5 -+ 单位：秒 - -> **注意：** -> -> 不要将该参数配置为 `0`。除非特殊情况，一般使用默认值即可。 - -## `--report-status` - -+ 用于打开或者关闭服务状态监听端口 -+ 默认：true -+ 将参数值设置为 `true` 表明开启状态监听端口；设置为 `false` 表明关闭状态监听端口 - -## `--run-ddl` - -+ tidb-server 是否运行 DDL 语句，集群内至少需要有一台 tidb-server 设置该参数 -+ 默认：true -+ 值可以为 `true` 或者 `false`。设置为 `true` 表明自身会运行 DDL；设置为 `false` 表明自身不会运行 DDL - -## `--socket string` - -+ TiDB 服务使用 unix socket file 方式接受外部连接 -+ 默认："" -+ 例如可以使用 "/tmp/tidb.sock" 来打开 unix socket file - -## `--status` - -+ TiDB 服务状态监听端口 -+ 默认："10080" -+ 该端口用于展示 TiDB 内部数据，包括 [prometheus 统计](https://prometheus.io/) 和 [pprof](https://golang.org/pkg/net/http/pprof/) -+ Prometheus 统计可以通过 `http://host:status_port/metrics` 访问 -+ pprof 数据可以通过 `http://host:status_port/debug/pprof` 访问 - -## `--status-host` - -+ TiDB 服务状态监听 host -+ 默认："0.0.0.0" - -## `--store` - -+ 用来指定 TiDB 底层使用的存储引擎 -+ 默认："mocktikv" -+ 可以选择 "mocktikv"（本地存储引擎）或者 "tikv"（分布式存储引擎） - -## `--token-limit` - -+ TiDB 中同时允许运行的 Session 数量，用于流量控制 -+ 默认：1000 -+ 如果当前运行的连接多于该 token-limit，那么请求会阻塞，等待已经完成的操作释放 Token - -## `-V` - -+ 输出 TiDB 的版本 -+ 默认："" diff --git a/v3.1/reference/configuration/tidb-server/mysql-variables.md b/v3.1/reference/configuration/tidb-server/mysql-variables.md deleted file mode 100644 index 855bdd756c9b..000000000000 --- a/v3.1/reference/configuration/tidb-server/mysql-variables.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: 系统变量 -category: reference - ---- - -# 系统变量 - -MySQL 系统变量 (System Variables) 是一些系统参数，用于调整数据库运行时的行为，根据变量的作用范围分为全局范围有效（Global Scope）以及会话级别有效（Session Scope）。TiDB 支持 MySQL5.7 的所有系统变量，大部分变量仅仅是为了兼容性而支持，不会影响运行时行为。 - -## 设置系统变量 - -通过 [`SET` 语句](/v3.1/reference/sql/statements/set-variable.md) 可以修改系统变量的值。进行修改时，还要考虑变量可修改的范围，不是所有的变量都能在全局/会话范围内进行修改。具体的可修改范围参考 [MySQL 动态变量文档](https://dev.mysql.com/doc/refman/5.7/en/dynamic-system-variables.html)。 - -### 全局范围值 - -* 在变量名前加 `GLOBAL` 关键词或者是使用 `@@global.` 作为修饰符: - - {{< copyable "sql" >}} - - ```sql - SET GLOBAL autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@global.autocommit = 1; - ``` - -> **注意：** -> -> 在分布式 TiDB 中，`GLOBAL` 变量的设置会持久化到存储层中，单个 TiDB 实例每 2 秒会主动进行一次全变量的获取并形成 `gvc` (global variables cache) 缓存，该缓存有效时间最多可持续 2 秒。在设置 `GLOBAL` 变量之后，为了保证新会话的有效性，请确保两个操作之间的间隔大于 2 秒。相关细节可以查看 [Issue #14531](https://github.com/pingcap/tidb/issues/14531)。 - -### 会话范围值 - -* 在变量名前加 `SESSION` 关键词或者是使用 `@@session.` 作为修饰符，或者是不加任何修饰符: - - {{< copyable "sql" >}} - - ```sql - SET SESSION autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@session.autocommit = 1; - ``` - - {{< copyable "sql" >}} - - ```sql - SET @@autocommit = 1; - ``` - -* `LOCAL` 以及 `@@local.` 是 `SESSION` 以及 `@@session.` 的同义词 - -### 系统变量的作用机制 - -* 会话范围的系统变量仅仅会在创建会话时才会根据全局范围系统变量初始化自己的值。更改全局范围的系统变量不会改变已经创建的会话正在使用的系统变量的值。 - - {{< copyable "sql" >}} - - ```sql - SELECT @@GLOBAL.autocommit; - ``` - - ``` - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | ON | - +---------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SET GLOBAL autocommit = OFF; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - 会话范围的系统变量不会改变，会话中执行的事务依旧是以自动提交的形式来进行： - - {{< copyable "sql" >}} - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | ON | - +----------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - SELECT @@GLOBAL.autocommit; - ``` - - ``` - +---------------------+ - | @@GLOBAL.autocommit | - +---------------------+ - | OFF | - +---------------------+ - 1 row in set (0.00 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - exit - ``` - - ``` - Bye - ``` - - {{< copyable "shell-regular" >}} - - ```shell - mysql -h 127.0.0.1 -P 4000 -u root -D test - ``` - - ``` - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 3 - Server version: 5.7.25-TiDB-None MySQL Community Server (Apache License 2.0) - - Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. - - Oracle is a registered trademark of Oracle Corporation and/or its - affiliates. Other names may be trademarks of their respective - owners. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - mysql> - ``` - - 新建的会话会使用新的全局变量： - - ```sql - SELECT @@SESSION.autocommit; - ``` - - ``` - +----------------------+ - | @@SESSION.autocommit | - +----------------------+ - | OFF | - +----------------------+ - 1 row in set (0.00 sec) - ``` - -## TiDB 支持的 MySQL 系统变量 - -下列系统变量是 TiDB 真正支持并且行为和 MySQL 一致： - -| 变量名 | 作用域 | 说明 | -| ---------------- | -------- | -------------------------------------------------- | -| autocommit | GLOBAL \| SESSION | 是否自动 Commit 事务 | -| sql_mode | GLOBAL \| SESSION | 支持部分 MySQL SQL mode，| -| time_zone | GLOBAL \| SESSION | 数据库所使用的时区 | -| tx_isolation | GLOBAL \| SESSION | 事务隔离级别 | -| max\_execution\_time | GLOBAL \| SESSION | 语句超时时间，单位为毫秒 | -| innodb\_lock\_wait\_timeout | GLOBAL \| SESSION | 悲观事务语句等锁时间，单位为秒 | - -> **注意：** -> -> `max_execution_time` 目前对所有类型的 `statement` 生效，并非只对 `SELECT` 语句生效。实际精度在 100ms 级别，而非更准确的毫秒级别。 - -## TiDB 特有的系统变量 - -参见 [TiDB 专用系统变量](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md b/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md deleted file mode 100644 index c488943b38ce..000000000000 --- a/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md +++ /dev/null @@ -1,669 +0,0 @@ ---- -title: TiDB 专用系统变量和语法 -category: reference - ---- - -# TiDB 专用系统变量和语法 - -TiDB 在 MySQL 的基础上，定义了一些专用的系统变量和语法用来优化性能。 - -## 系统变量 - -变量可以通过 SET 语句设置，例如 - -{{< copyable "sql" >}} - -```sql -set @@tidb_distsql_scan_concurrency = 10; -``` - -如果需要设置全局变量，执行 - -{{< copyable "sql" >}} - -```sql -set @@global.tidb_distsql_scan_concurrency = 10; -``` - -### tidb_snapshot - -作用域：SESSION - -默认值：空字符串 - -这个变量用来设置当前会话期待读取的历史数据所处时刻。比如当设置为 "2017-11-11 20:20:20" 时或者一个 TSO 数字 "400036290571534337"，当前会话将能读取到该时刻的数据。 - -### tidb_import_data - -作用域：SESSION - -默认值：0 - -这个变量用来表示当前状态是否为从 dump 文件中导入数据。 -当这个变量被设置为 1 时，唯一索引约束不被检查以加速导入速度。 -这个变量不对外用，只是给 lightning 使用，请用户不要自行修改。 - -### tidb_opt_agg_push_down - -作用域：SESSION - -默认值：0 - -这个变量用来设置优化器是否执行聚合函数下推到 Join 之前的优化操作。 -当查询中聚合操作执行很慢时，可以尝试设置该变量为 1。 - -### tidb_auto_analyze_ratio - -作用域：GLOBAL - -默认值：0.5 - -这个变量用来设置自动 ANALYZE 更新的阈值。当某个表 `tbl` 的修改行数与总行数的比值大于 tidb_auto_analyze_ratio，并且当前时间在 tidb_auto_analyze_start_time 和 tidb_auto_analyze_end_time 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句以自动更新该表的统计信息。注意：只有在 TiDB 的启动配置文件中开启了 run-auto-analyze 选项，该 TiDB 才会触发 auto_analyze。 - -### tidb_auto_analyze_start_time - -作用域：GLOBAL - -默认值：00:00 +0000 - -这个变量用来设置一天中允许自动 ANALYZE 更新的开始时间。 - -### tidb_auto_analyze_end_time - -作用域：GLOBAL - -默认值：23:59 +0000 - -这个变量用来设置一天中允许自动 ANALYZE 更新的结束时间。 - -### tidb_build_stats_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ANALYZE 语句执行时并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_checksum_table_concurrency - -作用域：SESSION - -默认值：4 - -这个变量用来设置 ADMIN CHECKSUM TABLE 语句执行时扫描索引的并发度。 -当这个变量被设置得更大时，会对其它的查询语句执行性能产生一定影响。 - -### tidb_current_ts - -作用域：SESSION - -默认值：0 - -这个变量是一个只读变量，用来获取当前事务的时间戳。 - -### tidb_config - -作用域：SESSION - -默认值：空字符串 - -这个变量是一个只读变量，用来获取当前 TiDB Server 的配置信息。 - -### tidb_distsql_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：15 - -这个变量用来设置 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 -对于 AP 类应用，最大值建议不要超过所有 TiKV 节点的 CPU 核数。 - -### tidb_index_lookup_size - -作用域：SESSION | GLOBAL - -默认值：20000 - -这个变量用来设置 index lookup 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_index_lookup_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 index lookup join 算法的并发度。 - -### tidb_hash_join_concurrency - -作用域：SESSION | GLOBAL - -默认值：5 - -这个变量用来设置 hash join 算法的并发度。 - -### tidb_index_serial_scan_concurrency - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来设置顺序 scan 操作的并发度，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_projection_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置 Projection 算子的并发度。 - -### tidb_hashagg_partial_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 partial 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_hashagg_final_concurrency - -作用域：SESSION | GLOBAL - -默认值：4 - -这个变量用来设置并行 hash aggregation 算法 final 阶段的执行并发度。对于聚合函数参数不为 distinct 的情况，HashAgg 分为 partial 和 final 阶段分别并行执行。 - -### tidb_index_join_batch_size - -作用域：SESSION | GLOBAL - -默认值：25000 - -这个变量用来设置 index lookup join 操作的 batch 大小，AP 类应用适合较大的值，TP 类应用适合较小的值。 - -### tidb_skip_utf8_check - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来设置是否跳过 UTF-8 字符的验证。 -验证 UTF-8 字符需要消耗一定的性能，当可以确认输入的字符串为有效的 UTF-8 字符时，可以将其设置为 1。 - -### tidb_init_chunk_size - -作用域：SESSION | GLOBAL - -默认值：32 - -这个变量用来设置执行过程中初始 chunk 的行数。默认值是 32。 - -### tidb_max_chunk_size - -作用域：SESSION | GLOBAL - -默认值：1024 - -这个变量用来设置执行过程中一个 chunk 最大的行数。 - -### tidb_mem_quota_query - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置一条查询语句的内存使用阈值。 -如果一条查询语句执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_hashjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 HashJoin 算子的内存使用阈值。 -如果 HashJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_mergejoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 MergeJoin 算子的内存使用阈值。 -如果 MergeJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_sort - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 Sort 算子的内存使用阈值。 -如果 Sort 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_topn - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 TopN 算子的内存使用阈值。 -如果 TopN 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupreader - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupReader 算子的内存使用阈值。 - -如果 IndexLookupReader 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_indexlookupjoin - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 IndexLookupJoin 算子的内存使用阈值。 -如果 IndexLookupJoin 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_mem_quota_nestedloopapply - -作用域：SESSION - -默认值：32 GB - -这个变量用来设置 NestedLoopApply 算子的内存使用阈值。 -如果 NestedLoopApply 算子执行过程中使用的内存空间超过该阈值，会触发 TiDB 启动配置文件中 OOMAction 项所指定的行为。 - -### tidb_general_log - -作用域：SERVER - -默认值：0 - -这个变量用来设置是否在日志里记录所有的 SQL 语句。 - -### tidb_enable_streaming - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否启用 Streaming。 - -### tidb_retry_limit - -作用域：SESSION | GLOBAL - -默认值：10 - -这个变量用来设置最大重试次数。一个事务执行中遇到可重试的错误（例如事务冲突、事务提交过慢或表结构变更）时，会根据该变量的设置进行重试。注意当 `tidb_retry_limit = 0` 时，也会禁用自动重试。 - -### tidb_disable_txn_auto_retry - -作用域：SESSION | GLOBAL - -默认值：on - -这个变量用来设置是否禁用显式事务自动重试，设置为 `on` 时，不会自动重试，如果遇到事务冲突需要在应用层重试。 - -如果将该变量的值设为 `off`，TiDB 将会自动重试事务，这样在事务提交时遇到的错误更少。需要注意的是，这样可能会导致数据更新丢失。 - -这个变量不会影响自动提交的隐式事务和 TiDB 内部执行的事务，它们依旧会根据 `tidb_retry_limit` 的值来决定最大重试次数。 - -是否需要禁用自动重试，请参考[重试的局限性](/v3.1/reference/transactions/transaction-optimistic.md#重试的局限性)。 - -### tidb_backoff_weight - -作用域：SESSION | GLOBAL - -默认值：2 - -这个变量用来给 TiDB 的 `backoff` 最大时间增加权重，即内部遇到网络或其他组件（TiKV、PD）故障等时，发送重试请求的最大重试时间。可以通过这个变量来调整最大重试时间，最小值为 1。 - -例如，TiDB 向 PD 取 TSO 的基础超时时间是 15 秒，当 `tidb_backoff_weight = 2` 时，取 TSO 的最大超时时间为：基础时间 * 2 等于 30 秒。 - -在网络环境较差的情况下，适当增大该变量值可以有效缓解因为超时而向应用端报错的情况；而如果应用端希望更快地接到报错信息，则应该尽量减小该变量的值。 - -### tidb_enable_table_partition - -作用域：SESSION - -默认值："auto" - -这个变量用来设置是否开启 TABLE PARTITION 特性。默认值 `auto` 表示开启 range partition 和 hash partion。`off` 表示关闭 TABLE PARTITION 的特性，此时语法还是会依旧兼容，只是建立的 partition table 实际上并不是真正的 partition table，而是和普通的 table 一样。`on` 表示开启，目前的作用和 `auto` 一样。 - -注意，目前 TiDB 只支持 range partition 和 hash partition。 - -### tidb_backoff_lock_fast - -作用域：SESSION | GLOBAL - -默认值：100 - -这个变量用来设置读请求遇到锁的 backoff 时间。 - -### tidb_ddl_reorg_worker_cnt - -作用域：GLOBAL - -默认值：16 - -这个变量用来设置 DDL 操作 re-organize 阶段的并发度。 - -### tidb_ddl_reorg_batch_size - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置 DDL 操作 re-organize 阶段的 batch size。比如 Add Index 操作，需要回填索引数据，通过并发 tidb_ddl_reorg_worker_cnt 个 worker 一起回填数据，每个 worker 以 batch 为单位进行回填。如果 Add Index 时有较多 Update 操作或者 Replace 等更新操作，batch size 越大，事务冲突的概率也会越大，此时建议调小 batch size 的值，最小值是 32。在没有事务冲突的情况下，batch size 可设为较大值，最大值是 10240，这样回填数据的速度更快，但是 TiKV 的写入压力也会变大。 - -### tidb_ddl_reorg_priority - -作用域：SESSION | GLOBAL - -默认值：PRIORITY_LOW - -这个变量用来设置 `ADD INDEX` 操作 re-organize 阶段的执行优先级，可设置为 PRIORITY_LOW/PRIORITY_NORMAL/PRIORITY_HIGH。 - -### tidb_ddl_error_count_limit - -作用域：GLOBAL - -默认值：512 - -这个变量用来控制 DDL 操作失败重试的次数。失败重试次数超过该参数的值后，会取消出错的 DDL 操作。 - -### tidb_max_delta_schema_count - -作用域：GLOBAL - -默认值：1024 - -这个变量用来设置缓存 schema 版本信息（对应版本修改的相关 table IDs）的个数限制，可设置的范围 100 - 16384。此变量在 2.1.18 及之后版本支持。 - -### tidb_force_priority - -作用域：SESSION - -默认值：`NO_PRIORITY` - -这个变量用于改变 TiDB server 上执行的语句的默认优先级。例如，你可以通过设置该变量来确保正在执行 OLAP 查询的用户优先级低于正在执行 OLTP 查询的用户。 - -可设置为 `NO_PRIORITY`、`LOW_PRIORITY`、`DELAYED` 或 `HIGH_PRIORITY`。 - -### tidb_opt_write_row_id - -作用域：SESSION - -默认值：0 - -这个变量用来设置是否允许 insert、replace 和 update 操作 `_tidb_rowid` 列，默认是不允许操作。该选项仅用于 TiDB 工具导数据时使用。 - -### SHARD_ROW_ID_BITS - -对于 PK 非整数或没有 PK 的表，TiDB 会使用一个隐式的自增 rowid，大量 `INSERT` 时会把数据集中写入单个 Region，造成写入热点。 - -通过设置 `SHARD_ROW_ID_BITS`，可以把 rowid 打散写入多个不同的 Region，缓解写入热点问题。但是设置的过大会造成 RPC 请求数放大，增加 CPU 和网络开销。 - -- `SHARD_ROW_ID_BITS = 4` 表示 16 个分片 -- `SHARD_ROW_ID_BITS = 6` 表示 64 个分片 -- `SHARD_ROW_ID_BITS = 0` 表示默认值 1 个分片 - -语句示例： - -- `CREATE TABLE`：`CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` -- `ALTER TABLE`：`ALTER TABLE t SHARD_ROW_ID_BITS = 4;` - -### tidb_slow_log_threshold - -作用域：SESSION - -默认值：300 - -输出慢日志的耗时阈值。当查询大于这个值，就会当做是一个慢查询，输出到慢查询日志。默认为 300ms。 - -示例： - -{{< copyable "sql" >}} - -```sql -set tidb_slow_log_threshold = 200; -``` - -### tidb_query_log_max_len - -作用域：SESSION - -默认值：2048 (bytes) - -最长的 SQL 输出长度。当语句的长度大于 query-log-max-len，将会被截断输出。 - -示例： - -{{< copyable "sql" >}} - -```sql -set tidb_query_log_max_len = 20; -``` - -### tidb_txn_mode - -作用域：SESSION | GLOBAL - -默认值："pessimistic" - -这个变量用于设置事务模式。TiDB v3.0 支持了悲观事务，自 v3.0.8 开始，默认使用[悲观事务模式](/v3.1/reference/transactions/transaction-pessimistic.md)。 - -但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 - -将该变量设置为 "optimistic" 或 "" 时，将会使用[乐观事务模式](/v3.1/reference/transactions/transaction-optimistic.md)。 - -### tidb_constraint_check_in_place - -作用域：SESSION | GLOBAL - -默认值：0 - -TiDB 支持乐观事务模型，即在执行写入时，假设不存在冲突。冲突检查是在最后 commit 提交时才去检查。这里的检查指 unique key 检查。 - -这个变量用来控制是否每次写入一行时就执行一次唯一性检查。注意，开启该变量后，在大批量写入场景下，对性能会有影响。 - -示例： - -默认关闭 tidb_constraint_check_in_place 时的行为： - -{{< copyable "sql" >}} - -```sql -create table t (i int key); -insert into t values (1); -begin; -insert into t values (1); -``` - -``` -Query OK, 1 row affected -``` - -commit 时才去做检查： - -{{< copyable "sql" >}} - -```sql -commit; -``` - -``` -ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' -``` - -打开 tidb_constraint_check_in_place 后： - -{{< copyable "sql" >}} - -```sql -set @@tidb_constraint_check_in_place=1; -begin; -insert into t values (1); -``` - -``` -ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' -``` - -### tidb_check_mb4_value_in_utf8 - -作用域：SERVER - -默认值：1 - -这个变量用来设置是否开启对字符集为 UTF8 类型的数据做合法性检查，默认值 `1` 表示开启检查。这个默认行为和 MySQL 是兼容的。 - -注意，如果是旧版本升级时，可能需要关闭该选项，否则由于旧版本（v2.1.1 以及之前）没有对数据做合法性检查，所以旧版本写入非法字符串是可以写入成功的，但是新版本加入合法性检查后会报写入失败。具体可以参考[升级后常见问题](/v3.1/faq/upgrade.md)。 - -### tidb_opt_insubq_to_join_and_agg - -作用域：SESSION | GLOBAL - -默认值：1 - -这个用来设置是否开启优化规则：将子查询转成 join 和 aggregation。 - -示例： - -打开这个优化规则后，会将下面子查询做如下变化： - -{{< copyable "sql" >}} - -```sql -select * from t where t.a in (select aa from t1); -``` - -将子查询转成 join 如下： - -{{< copyable "sql" >}} - -```sql -select * from t, (select aa from t1 group by aa) tmp_t where t.a = tmp_t.aa; -``` - -如果 t1 在列 aa 上有 unique 且 not null 的限制，可以直接改写为如下，不需要添加 aggregation。 - -{{< copyable "sql" >}} - -```sql -select * from t, t1 where t.a=t1.a; -``` - -### tidb_opt_correlation_threshold - -作用域：SESSION | GLOBAL - -默认值：0.9 - -这个变量用来设置优化器启用交叉估算 row count 方法的阈值。如果列和 handle 列之间的顺序相关性超过这个阈值，就会启用交叉估算方法。 - -交叉估算方法可以简单理解为，利用这个列的直方图来估算 handle 列需要扫的行数。 - -### tidb_opt_correlation_exp_factor - -作用域：SESSION | GLOBAL - -默认值：1 - -当交叉估算方法不可用时，会采用启发式估算方法。这个变量用来控制启发式方法的行为。当值为 0 时不用启发式估算方法，大于 0 时，该变量值越大，启发式估算方法越倾向 index scan，越小越倾向 table scan。 - -### tidb_enable_window_function - -作用域：SESSION | GLOBAL - -默认值：1 - -这个变量用来控制是否开启窗口函数的支持。默认值 1 代表开启窗口函数的功能。 - -由于窗口函数会使用一些保留关键字，可能导致原先可以正常执行的 SQL 语句在升级 TiDB 后无法被解析语法，此时可以将 `tidb_enable_window_function` 设置为 `0`。 - -### tidb_slow_query_file - -作用域：SESSION - -默认值："" - -查询 `INFORMATION_SCHEMA.SLOW_QUERY` 只会解析配置文件中 `slow-query-file` 设置的慢日志文件名，默认是 "tidb-slow.log"。但如果想要解析其他的日志文件，可以通过设置 session 变量 `tidb_slow_query_file` 为具体的文件路径，然后查询 `INFORMATION_SCHEMA.SLOW_QUERY` 就会按照设置的路径去解析慢日志文件。更多详情可以参考 [SLOW_QUERY 文档](/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 - -### tidb_enable_fast_analyze - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来控制是否启用统计信息快速分析功能。默认值 0 表示不开启。 - -快速分析功能开启后，TiDB 会随机采样约 10000 行的数据来构建统计信息。因此在数据分布不均匀或者数据量比较少的情况下，统计信息的准确度会比较低。这可能导致执行计划不优，比如选错索引。如果可以接受普通 `ANALYZE` 语句的执行时间，则推荐关闭快速分析功能。 - -### tidb_expensive_query_time_threshold - -作用域：SERVER - -默认值：60 - -这个变量用来控制打印 expensive query 日志的阈值时间，单位是秒，默认值是 60 秒。expensive query 日志和慢日志的差别是，慢日志是在语句执行完后才打印，expensive query 日志可以把正在执行中的语句且执行时间超过阈值的语句及其相关信息打印出来。 - -### tidb_wait_split_region_finish - -作用域：SESSION - -默认值：1 - -由于打散 region 的时间可能比较长，主要由 PD 调度以及 TiKV 的负载情况所决定。这个变量用来设置在执行 `SPLIT REGION` 语句时，是否同步等待所有 region 都打散完成后再返回结果给客户端。默认 1 代表等待打散完成后再返回结果。0 代表不等待 Region 打散完成就返回。 - -需要注意的是，在 region 打散期间，对正在打散 region 上的写入和读取的性能会有一定影响，对于批量写入，导数据等场景，还是建议等待 region 打散完成后再开始导数据。 - -### tidb_wait_split_region_timeout - -作用域：SESSION - -默认值：300 - -这个变量用来设置 `SPLIT REGION` 语句的执行超时时间，单位是秒，默认值是 300 秒，如果超时还未完成，就返回一个超时错误。 - -### tidb_scatter_region - -作用域：GLOBAL - -默认值：0 - -TiDB 默认会在建表时为新表分裂 Region。开启该变量后，会在建表语句执行时，同步打散刚分裂出的 Region。适用于批量建表后紧接着批量写入数据，能让刚分裂出的 Region 先在 TiKV 分散而不用等待 PD 进行调度。为了保证后续批量写入数据的稳定性，建表语句会等待打散 Region 完成后再返回建表成功，建表语句执行时间会是关闭该变量的数倍。 - -### tidb_allow_remove_auto_inc 从 v3.0.4 版本开始引入 - -作用域：SESSION - -默认值：0 - -这个变量用来控制是否允许通过 `ALTER TABLE MODIFY` 或 `ALTER TABLE CHANGE` 来移除某个列的 `AUTO_INCREMENT` 属性。默认为不允许。 - -### tidb_enable_stmt_summary 从 v3.0.4 版本开始引入 - -作用域：SESSION | GLOBAL - -默认值：0 - -这个变量用来控制是否开启 statement summary 功能。如果开启，SQL 的耗时等执行信息将被记录到系统表 `performance_schema.events_statements_summary_by_digest` 中，用于定位和排查 SQL 性能问题。 diff --git a/v3.1/reference/configuration/tikv-server/configuration-file.md b/v3.1/reference/configuration/tikv-server/configuration-file.md deleted file mode 100644 index bdf7e680b901..000000000000 --- a/v3.1/reference/configuration/tikv-server/configuration-file.md +++ /dev/null @@ -1,1093 +0,0 @@ ---- -title: TiKV 配置文件描述 -category: reference ---- - - - -# TiKV 配置文件描述 - -TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/config-template.toml](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 找到默认值的配置文件，重命名为 config.toml 即可。 - -本文档只阐述未包含在命令行参数中的参数，命令行参数参见 [TiKV 配置参数](/v3.1/reference/configuration/tikv-server/configuration.md)。 - -### `status-thread-pool-size` - -+ Http API 服务的工作线程数量。 -+ 默认值：1 -+ 最小值：1 - -### `grpc-compression-type` - -+ gRPC 消息的压缩算法，取值：none， deflate， gzip。 -+ 默认值：none - -### `grpc-concurrency` - -+ gRPC 工作线程的数量。 -+ 默认值：4 -+ 最小值：1 - -### `grpc-concurrent-stream` - -+ 一个 gRPC 链接中最多允许的并发请求数量。 -+ 默认值：1024 -+ 最小值：1 - -### `server.grpc-raft-conn-num` - -+ tikv 节点之间用于 raft 通讯的链接最大数量。 -+ 默认值：10 -+ 最小值：1 - -### `server.grpc-stream-initial-window-size` - -+ gRPC stream 的 window 大小。 -+ 默认值：2MB -+ 单位：KB|MB|GB -+ 最小值：1KB - -### `server.grpc-keepalive-time` - -+ gRPC 发送 keep alive ping 消息的间隔时长。 -+ 默认值：10s -+ 最小值：1s - -### `server.grpc-keepalive-timeout` - -+ 关闭 gRPC 链接的超时时长。 -+ 默认值：3s -+ 最小值：1s - -### `server.concurrent-send-snap-limit` - -+ 同时发送 snapshot 的最大个数，默认值：32 -+ 默认值：32 -+ 最小值：1 - -### `server.concurrent-recv-snap-limit` - -+ 同时接受 snapshot 的最大个数，默认值：32 -+ 默认值：32 -+ 最小值：1 - -### `server.end-point-recursion-limit` - -+ endpoint 下推查询请求解码消息时，最多允许的递归层数。 -+ 默认值：1000 -+ 最小值：1 - -### `server.end-point-request-max-handle-duration` - -+ endpoint 下推查询请求处理任务最长允许的时长。 -+ 默认值：60s -+ 最小值：1s - -### `server.snap-max-write-bytes-per-sec` - -+ 处理 snapshot 时最大允许使用的磁盘带宽 -+ 默认值：1000MB -+ 单位：KB|MB|GB -+ 最小值：1KB - -## readpool.storage - -存储线程池相关的配置项。 - -### `high-concurrency` - -+ 处理高优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `normal-concurrency` - -+ 处理普通优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `low-concurrency` - -+ 处理低优先级读请求的线程池线程数量。 -+ 默认值：4 -+ 最小值：1 - -### `max-tasks-per-worker-high` - -+ 高优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-normal` - -+ 普通优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-low` - -+ 低优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `stack-size` - -+ Storage 读线程池中线程的栈大小。 -+ 默认值：10MB -+ 单位：KB|MB|GB -+ 最小值：2MB - -## readpool.coprocessor - -协处理器线程池相关的配置项。 - -### `high-concurrency` - -+ 处理高优先级 Coprocessor 请求（如点查）的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `normal-concurrency` - -+ 处理普通优先级 Coprocessor 请求的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `low-concurrency` - -+ 处理低优先级 Coprocessor 请求（如扫表）的线程池线程数量。 -+ 默认值：CPU * 0.8 -+ 最小值：1 - -### `max-tasks-per-worker-high` - -+ 高优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-normal` - -+ 普通优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `max-tasks-per-worker-low` - -+ 低优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。 -+ 默认值：2000 -+ 最小值：2 - -### `stack-size` - -Coprocessor 线程池中线程的栈大小，默认值：10，单位：KiB|MiB|GiB。 - -+ 默认值：10MB -+ 单位：KB|MB|GB -+ 最小值：2MB - -## storage - -存储相关的配置项。 - -### `scheduler-notify-capacity` - -+ scheduler 一次获取最大消息个数 -+ 默认值：10240 -+ 最小值：1 - -### `scheduler-concurrency` - -+ scheduler 内置一个内存锁机制，防止同时对一个 key 进行操作。每个 key hash 到不同的槽。 -+ 默认值：2048000 -+ 最小值：1 - -### `scheduler-worker-pool-size` - -+ scheduler 线程个数，主要负责写入之前的事务一致性检查工作。 -+ 默认值：4 -+ 最小值：1 - -### `scheduler-pending-write-threshold` - -+ 写入数据队列的最大值，超过该值之后对于新的写入 TiKV 会返回 Server Is Busy 错误。 -+ 默认值：100MB -+ 单位: MB|GB - -## raftstore - -raftstore 相关的配置项。 - -### `sync-log` - -+ 数据、log 落盘是否 sync，注意：设置成 false 可能会丢数据。 -+ 默认值：true - -### `prevote` - -+ 开启 Prevote 的开关，开启有助于减少隔离恢复后对系统造成的抖动。 -+ 默认值：true - -### `raftdb-path` - -+ raft 库的路径，默认存储在 storage.data-dir/raft 下。 -+ 默认值："" - -### `raft-base-tick-interval` - -+ 状态机 tick 一次的间隔时间。 -+ 默认值：1s -+ 最小值：大于 0 - -### `raft-heartbeat-ticks` - -+ 发送心跳时经过的 tick 个数，即每隔 raft-base-tick-interval * raft-heartbeat-ticks 时间发送一次心跳。 -+ 默认值：2 -+ 最小值：大于 0 - -### `raft-election-timeout-ticks` - -+ 发起选举时经过的 tick 个数，即如果处于无主状态，大约经过 raft-base-tick-interval * raft-election-timeout-ticks 时间以后发起选举。 -+ 默认值：10 -+ 最小值：raft-heartbeat-ticks - -### `raft-min-election-timeout-ticks` - -+ 发起选举时至少经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks，不能比 raft-election-timeout-ticks 小。 -+ 默认值：0 -+ 最小值：0 - -### `raft-max-election-timeout-ticks` - -+ 发起选举时最多经过的 tick 个数，如果为 0，则表示使用 raft-election-timeout-ticks * 2。 -+ 默认值：0 -+ 最小值：0 - -### `raft-max-size-per-message` - -+ 产生的单个消息包的大小限制，软限制。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：MB - -### `raft-max-inflight-msgs` - -+ 待确认日志个数的数量，如果超过这个数量将会减缓发送日志的个数。 -+ 默认值：256 -+ 最小值：大于0 - -### `raft-entry-max-size` - -+ 单个日志最大大小，硬限制。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：MB|GB - -### `raft-log-gc-tick-interval` - -+ 删除 raft 日志的轮询任务调度间隔时间，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `raft-log-gc-threshold` - -+ 允许残余的 raft 日志个数，这是一个软限制。 -+ 默认值：50 -+ 最小值：1 - -### `raft-log-gc-count-limit` - -+ 允许残余的 raft 日志个数，这是一个硬限制。默认值为按照每个日志 1MB 而计算出来的 3/4 region 大小所能容纳的日志个数。 -+ 最小值：0 - -### `raft-log-gc-size-limit` - -+ 允许残余的 raft 日志大小，这是一个硬限制，默认为 region 大小的 3/4。 -+ 最小值：大于 0 - -### `raft-entry-cache-life-time` - -+ 内存中日志 cache 允许的最长残留时间。 -+ 默认值：30s -+ 最小值：0 - -### `raft-reject-transfer-leader-duration` - -+ 新节点保护时间，控制迁移 leader 到新加节点的最小时间，设置过小容易导致迁移 leader 失败。 -+ 默认值：3s -+ 最小值：0 - -### `raftstore.hibernate-regions` (**实验特性**) - -+ 打开或关闭静默 Region。打开后，如果 Region 长时间处于非活跃状态，即被自动设置为静默状态。静默状态的 Region 可以降低 Leader 和 Follower 之间心跳信息的系统开销。可以通过 `raftstore.peer-stale-state-check-interval` 调整 Leader 和 Follower 之间的心跳间隔。 -+ 默认值：false - -### `raftstore.peer-stale-state-check-interval` - -+ 修改对 Region 的状态检查间隔时间。 -+ 默认值：5 min - -### `split-region-check-tick-interval` - -+ 检查 region 是否需要分裂的时间间隔，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `region-split-check-diff` - -+ 允许 region 数据超过指定大小的最大值，默认为 region 大小的 1/16。 -+ 最小值：0 - -### `region-compact-check-interval` - -+ 检查是否需要人工触发 rocksdb compaction 的时间间隔，0 表示不启用。 -+ 默认值：5m -+ 最小值：0 - -### `clean-stale-peer-delay` - -+ 延迟删除过期副本数据的时间。 -+ 默认值：10m -+ 最小值：0 - -### `region-compact-check-step` - -+ 每轮校验人工 compaction 时，一次性检查的 region 个数。 -+ 默认值：100 -+ 最小值：0 - -### `region-compact-min-tombstones` - -+ 触发 rocksdb compaction 需要的 tombstone 个数。 -+ 默认值：10000 -+ 最小值：0 - -### `region-compact-tombstones-percent` - -+ 触发 rocksdb compaction 需要的 tombstone 所占比例。 -+ 默认值：30 -+ 最小值：1 -+ 最大值：100 - -### `pd-heartbeat-tick-interval` - -+ 触发 region 对 PD 心跳的时间间隔，0 表示不启用。 -+ 默认值：1m -+ 最小值：0 - -### `pd-store-heartbeat-tick-interval` - -+ 触发 store 对 PD 心跳的时间间隔，0 表示不启用。 -+ 默认值：10s -+ 最小值：0 - -### `snap-mgr-gc-tick-interval` - -+ 触发回收过期 snapshot 文件的时间间隔，0 表示不启用。 -+ 默认值：5s -+ 最小值：0 - -### `snap-gc-timeout` - -+ snapshot 文件的最长保存时间。 -+ 默认值：4h -+ 最小值：0 - -### `lock-cf-compact-interval` - -+ 触发对 lock CF compact 检查的时间间隔。 -+ 默认值：10m -+ 最小值：0 - -### `lock-cf-compact-bytes-threshold` - -+ 触发对 lock CF 进行 compact 的大小。 -+ 默认值：256MB -+ 最小值：0 -+ 单位：MB - -### `notify-capacity` - -+ region 消息队列的最长长度。 -+ 默认值：40960 -+ 最小值：0 - -### `messages-per-tick` - -+ 每轮处理的消息最大个数。 -+ 默认值：4096 -+ 最小值：0 - -### `max-peer-down-duration` - -+ 副本允许的最长未响应时间，超过将被标记为 down，后续 PD 会尝试将其删掉。 -+ 默认值：5m -+ 最小值：0 - -### `max-leader-missing-duration` - -+ 允许副本处于无主状态的最长时间，超过将会向 PD 校验自己是否已经被删除。 -+ 默认值：2h -+ 最小值：> abnormal-leader-missing-duration - -### `abnormal-leader-missing-duration` - -+ 允许副本处于无主状态的时间，超过将视为异常，标记在 metrics 和日志中。 -+ 默认值：10m -+ 最小值：> peer-stale-state-check-interval - -### `peer-stale-state-check-interval` - -+ 触发检验副本是否处于无主状态的时间间隔。 -+ 默认值：5m -+ 最小值：> 2 * election-timeout - -### `leader-transfer-max-log-lag` - -+ 尝试转移领导权时被转移者允许的最大日志缺失个数。 -+ 默认值：10 -+ 最小值：10 - -### `snap-apply-batch-size` - -+ 当导入 snapshot 文件需要写数据时，内存写缓存的大小 -+ 默认值：10MB -+ 最小值：0 -+ 单位：MB - -### `consistency-check-interval` - -+ 触发一致性检查的时间间隔, 0 表示不启用。 -+ 默认值：0s -+ 最小值：0 - -### `raft-store-max-leader-lease` - -+ region 主可信任期的最长时间。 -+ 默认值：9s -+ 最小值：0 - -### `right-derive-when-split` - -+ 为 true 时，以最大分裂 key 为起点的 region 复用原 region 的 key；否则以原 region 起点 key 作为起点的 region 复用原 region 的 key。 -+ 默认值：true - -### `allow-remove-leader` - -+ 允许删除主开关。 -+ 默认值：false - -### `merge-max-log-gap` - -+ 进行 merge 时，允许的最大日志缺失个数。 -+ 默认值：10 -+ 最小值：> raft-log-gc-count-limit - -### `merge-check-tick-interval` - -+ 触发 merge 完成检查的时间间隔。 -+ 默认值：10s -+ 最小值：大于 0 - -### `use-delete-range` - -+ 开启 rocksdb delete_range 接口删除数据的开关。 -+ 默认值：false - -### `cleanup-import-sst-interval` - -+ 触发检查过期 SST 文件的时间间隔，0 表示不启用。 -+ 默认值：10m -+ 最小值：0 - -### `local-read-batch-size` - -+ 一轮处理读请求的最大个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `apply-max-batch-size` - -+ 一轮处理数据落盘的最大请求个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `apply-pool-size` - -+ 处理数据落盘的线程池线程数。 -+ 默认值：2 -+ 最小值：大于 0 - -### `store-max-batch-size` - -+ 一轮处理的最大请求个数。 -+ 默认值：1024 -+ 最小值：大于 0 - -### `store-pool-size` - -+ 处理 raft 的线程池线程数。 -+ 默认值：2 -+ 最小值：大于 0 - -### `future-poll-size` - -+ 驱动 future 的线程池线程数。 -+ 默认值：1 -+ 最小值：大于 0 - -## coprocessor - -协处理器相关的配置项。 - -### `split-region-on-table` - -+ 开启按 table 分裂 Region的开关，建议仅在 TiDB 模式下使用。 -+ 默认值：true - -### `batch-split-limit` - -+ 批量分裂 Region 的阈值，调大该值可加速分裂 Region。 -+ 默认值：10 -+ 最小值：1 - -### `region-max-size` - -+ Region 容量空间最大值，超过时系统分裂成多个 Region。 -+ 默认值：144MB -+ 单位：KB|MB|GB - -### `region-split-size` - -+ 分裂后新 Region 的大小，此值属于估算值。 -+ 默认值：96MB -+ 单位：KB|MB|GB - -### `region-max-keys` - -+ Region 最多允许的 key 的个数，超过时系统分裂成多个 Region。 -+ 默认值：1440000 - -### `region-split-keys` - -+ 分裂后新 Region 的 key 的个数，此值属于估算值。 -+ 默认值：960000 - -## rocksdb - -rocksdb 相关的配置项。 - -### `max-background-jobs` - -+ RocksDB 后台线程个数。 -+ 默认值：8 -+ 最小值：1 - -### `max-sub-compactions` - -+ RocksDB 进行 subcompaction 的并发个数。 -+ 默认值：1 -+ 最小值：1 - -### `max-open-files` - -+ RocksDB 可以打开的文件总数。 -+ 默认值：40960 -+ 最小值：-1 - -### `max-manifest-file-size` - -+ RocksDB Manifest 文件最大大小。 -+ 默认值：128MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `create-if-missing` - -+ 自动创建 DB 开关。 -+ 默认值：true - -### `wal-recovery-mode` - -+ WAL 恢复模式，取值：0（TolerateCorruptedTailRecords），1（AbsoluteConsistency），2（PointInTimeRecovery），3（SkipAnyCorruptedRecords）。 -+ 默认值：2 -+ 最小值：0 -+ 最大值：3 - -### `wal-dir` - -+ WAL 存储目录，默认：“tmp/tikv/store”。 -+ 默认值：/tmp/tikv/store - -### `wal-ttl-seconds` - -+ 归档 WAL 生存周期，超过该值时，系统会删除相关 WAL。 -+ 默认值：0 -+ 最小值：0 -+ 单位：秒 - -### `wal-size-limit` - -+ 归档 WAL 大小限制，超过该值时，系统会删除相关 WAL。 -+ 默认值：0 -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `enable-statistics` - -+ 开启自动优化 Rate LImiter 的配置的开关。 -+ 默认值：false - -### `stats-dump-period` - -+ 开启或关闭 Pipelined Write。 -+ 默认值：true - -### `compaction-readahead-size` - -+ 异步 Sync 限速速率。 -+ 默认值：0 -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `writable-file-max-buffer-size` - -+ WritableFileWrite 所使用的最大的 buffer 大小。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `use-direct-io-for-flush-and-compaction` - -+ flush 或者 compaction 开启 DirectIO 的开关。 -+ 默认值：false - -### `rate-bytes-per-sec` - -+ Rate Limiter 限制速率。 -+ 默认值：0 -+ 最小值：0 -+ 单位：Bytes - -### `rate-limiter-mode` - -+ Rate LImiter 模式，取值：1（ReadOnly），2（WriteOnly），3（AllIo）。 -+ 默认值：2 -+ 最小值：1 -+ 最大值：3 - -### `auto-tuned` - -+ 开启自动优化 Rate LImiter 的配置的开关。 -+ 默认值：false - -### `enable-pipelined-write` - -+ 开启 Pipelined Write 的开关。 -+ 默认值：true - -### `bytes-per-sync` - -+ 异步 Sync 限速速率。 -+ 默认值：1MB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `wal-bytes-per-sync` - -+ WAL Sync 限速速率，默认：512KB。 -+ 默认值：512KB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `info-log-max-size` - -+ Info 日志的最大大小。 -+ 默认值：1GB -+ 最小值：0 -+ 单位：B|KB|MB|GB - -### `info-log-roll-time` - -+ 日志截断间隔时间，如果为0则不截断。 -+ 默认值：0 - -### `info-log-keep-log-file-num` - -+ 保留日志文件最大个数。 -+ 默认值：10 -+ 最小值：0 - -### `info-log-dir` - -+ 日志存储目录。 -+ 默认值："" - -## rocksdb.titan - -Titan 相关的配置项。 - -### `enabled` - -+ 开启或关闭 Titan。 -+ 默认值：false - -### `dirname` - -+ Titan Blob 文件存储目录。 -+ 默认值：titandb - -### `disable-gc` - -+ 控制是否关闭 Titan 对 Blob 文件的 GC。 -+ 默认值：false - -### `max-background-gc` - -+ Titan 后台 GC 的线程个数。 -+ 默认值：1 -+ 最小值：1 - -## rocksdb.defaultcf - -rocksdb defaultcf 相关的配置项。 - -### `block-size` - -+ 设置 rocksdb block 大小。 -+ 默认值：64KB -+ 最小值：1KB -+ 单位：KB|MB|GB - -### `block-cache-size` - -+ 设置 rocksdb block 缓存大小。 -+ 默认值：机器总内存 / 4 -+ 最小值：0 -+ 单位：KB|MB|GB - -### `disable-block-cache` - -+ 开启或关闭 block cache。 -+ 默认值：false - -### `cache-index-and-filter-blocks` - -+ 开启或关闭缓存 index 和 filter。 -+ 默认值：true - -### `pin-l0-filter-and-index-blocks` - -+ 是否 pin 住 L0 的 index 和 filter。 -+ 默认值：true - -### `use-bloom-filter` - -+ 开启 bloom filter 的开关。 -+ 默认值：true - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：true - -### `whole_key_filtering` - -+ 开启将整个 key 放到 bloom filter 中的开关。 -+ 默认值：true - -### `bloom-filter-bits-per-key` - -bloom filter 为每个 key 预留的长度。 - -+ 默认值：10 -+ 单位：字节 - -### `block-based-bloom-filter` - -+ 开启每个 block 建立 bloom filter 的开关。 -+ 默认值：false - -### `read-amp-bytes-per-bit` - -+ 开启读放大统计的开关，0：不开启，> 0 开启。 -+ 默认值：0 -+ 最小值：0 - -### `compression-per-level` - -+ 每一层默认压缩算法，默认：前两层为 No，后面 5 层为 lz4。 -+ 默认值：["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -### `write-buffer-size` - -+ memtable 大小。 -+ 默认值：128MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `max-write-buffer-number` - -+ 最大 memtable 个数。 -+ 默认值：5 -+ 最小值：0 - -### `min-write-buffer-number-to-merge` - -+ 触发 flush 的最小 memtable 个数。 -+ 默认值：1 -+ 最小值：0 - -### `max-bytes-for-level-base` - -+ base level (L1) 最大字节数，一般设置为 memtable 大小 4 倍。 -+ 默认值：512MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `target-file-size-base` - -+ base level 的目标文件大小。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `level0-file-num-compaction-trigger` - -+ 触发 compaction 的 L0 文件最大个数。 -+ 默认值：4 -+ 最小值：0 - -### `level0-slowdown-writes-trigger` - -+ 触发 write stall 的 L0 文件最大个数。 -+ 默认值：20 -+ 最小值：0 - -### `level0-stop-writes-trigger` - -+ 完全阻停写入的 L0 文件最大个数。 -+ 默认值：36 -+ 最小值：0 - -### `max-compaction-bytes` - -+ 一次 compaction 最大写入字节数，默认 2GB。 -+ 默认值：2GB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `compaction-pri` - -Compaction 优先类型，默认：3（MinOverlappingRatio），0（ByCompensatedSize）， -1（OldestLargestSeqFirst），2（OldestSmallestSeqFirst）。 - -+ 默认值：3 - -### `dynamic-level-bytes` - -+ 开启 dynamic level bytes 优化的开关。 -+ 默认值：true - -### `num-levels` - -+ RocksDB 文件最大层数。 -+ 默认值：7 - -### `max-bytes-for-level-multiplier` - -+ 每一层的默认放大倍数。 -+ 默认值：10 - -### `rocksdb.defaultcf.compaction-style` - -+ Compaction 方法，可选值为 level，universal。 -+ 默认值：level - -### `disable-auto-compactions` - -+ 开启自动 compaction 的开关。 -+ 默认值：false - -### `soft-pending-compaction-bytes-limit` - -+ pending compaction bytes 的软限制。 -+ 默认值：64GB -+ 单位：KB|MB|GB - -### `hard-pending-compaction-bytes-limit` - -+ pending compaction bytes 的硬限制。 -+ 默认值：256GB -+ 单位：KB|MB|GB - -## rocksdb.defaultcf.titan - -rocksdb defaultcf titan 相关的配置项。 - -### `min-blob-size` - -+ 最小存储在 Blob 文件中 value 大小，低于该值的 value 还是存在 LSM-Tree 中。 -+ 默认值：1KB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `blob-file-compression` - -+ Blob 文件所使用的压缩算法，可选值：no, snappy, zlib, bzip2, lz4, lz4hc, zstd。 -+ 默认值：lz4 - -### `blob-cache-size` - -+ Blob 文件的 cache 大小，默认：0GB。 -+ 默认值：0GB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `min-gc-batch-size` - -+ 做一次 GC 所要求的最低 Blob 文件大小总和。 -+ 默认值：16MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `max-gc-batch-size` - -+ 做一次 GC 所要求的最高 Blob 文件大小总和。 -+ 默认值：64MB -+ 最小值：0 -+ 单位：KB|MB|GB - -### `discardable-ratio` - -+ Blob 文件 GC 的触发比例，如果某 Blob 文件中的失效 value 的比例高于该值才可能被 GC 选中。 -+ 默认值：0.5 -+ 最小值：0 -+ 最大值：1 - -### `sample-ratio` - -+ 进行 GC 时，对 Blob 文件进行采样时读取数据占整个文件的比例。 -+ 默认值：0.1 -+ 最小值：0 -+ 最大值：1 - -### `merge-small-file-threshold` - -+ Blob 文件的大小小于该值时，无视 discardable-ratio 仍可能被 GC 选中。 -+ 默认值：8MB -+ 最小值：0 -+ 单位：KB|MB|GB - -## rocksdb.writecf - -rocksdb writecf 相关的配置项。 - -### `block-cache-size` - -+ block cache size。 -+ 默认值：机器总内存 * 15% -+ 单位：MB|GB - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：false - -### `whole-key-filtering` - -+ 开启将整个 key 放到 bloom filter 中的开关。 -+ 默认值：false - -## rocksdb.lockcf - -rocksdb lockcf 相关配置项。 - -### `block-cache-size` - -+ block cache size。 -+ 默认值：机器总内存 * 2% -+ 单位：MB|GB - -### `optimize-filters-for-hits` - -+ 开启优化 filter 的命中率的开关。 -+ 默认值：false - -### `level0-file-num-compaction-trigger` - -+ 触发 compaction 的 L0 文件个数。 -+ 默认值：1 - -## raftdb - -raftdb 相关配置项。 - -### `max-background-jobs` - -+ RocksDB 后台线程个数。 -+ 默认值：2 -+ 最小值：1 - -### `max-sub-compactions` - -+ RocksDB 进行 subcompaction 的并发数。 -+ 默认值：1 -+ 最小值：1 - -### `wal-dir` - -+ WAL 存储目录。 -+ 默认值：/tmp/tikv/store - -## security - -安全相关配置项。 - -### `ca-path` - -+ CA 文件路径 -+ 默认："" - -### `cert-path` - -+ 包含 X509 证书的 PEM 文件路径 -+ 默认："" - -### `key-path` - -+ 包含 X509 key 的 PEM 文件路径 -+ 默认："" - -## import - -import 相关的配置项。 - -### `num-threads` - -+ 处理 RPC 请求线程数。 -+ 默认值：8 -+ 最小值：1 - -### `num-import-jobs` - -+ 并发导入工作任务数。 -+ 默认值：8 -+ 最小值：1 - -## pessimistic-txn - -### `enabled` - -+ 开启悲观事务支持，悲观事务使用方法请参考 [TiDB 悲观事务模式](/v3.1/reference/transactions/transaction-pessimistic.md)。 -+ 默认值：true - -### `wait-for-lock-timeout` - -+ 悲观事务在 TiKV 中等待其他事务释放锁的最长时间，单位为毫秒。若超时则会返回错误给 TiDB 并由 TiDB 重试加锁，语句最长等锁时间由 `innodb_lock_wait_timeout` 控制。 -+ 默认值：1000 -+ 最小值：1 - -### `wait-up-delay-duration` - -+ 悲观事务释放锁时，只会唤醒等锁事务中 start ts 最小的事务，其他事务将会延迟 `wake-up-delay-duration` 毫秒之后被唤醒。 -+ 默认值：20 diff --git a/v3.1/reference/configuration/tikv-server/configuration.md b/v3.1/reference/configuration/tikv-server/configuration.md deleted file mode 100644 index df545c42883e..000000000000 --- a/v3.1/reference/configuration/tikv-server/configuration.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiKV 配置参数 -category: reference ---- - -# TiKV 配置参数 - -TiKV 的命令行参数支持一些可读性好的单位转换。 - -+ 文件大小（以 bytes 为单位）：KB, MB, GB, TB, PB（也可以全小写） -+ 时间（以毫秒为单位）：ms, s, m, h - -## `-A, --addr` - -+ TiKV 监听地址 -+ 默认："127.0.0.1:20160" -+ 如果部署一个集群，\-\-addr 必须指定当前主机的 IP 地址，例如 "192.168.100.113:20160"，如果是运行在 docker 则需要指定为 "0.0.0.0:20160" - -## `--advertise-addr` - -+ TiKV 对外访问地址。 -+ 默认：${addr} -+ 在某些情况下，譬如 docker，或者 NAT 网络环境，客户端并不能通过 TiKV 自己监听的地址来访问到 TiKV，这时候，你就可以设置 advertise addr 来让 客户端访问 -+ 例如，docker 内部 IP 地址为 172.17.0.1，而宿主机的 IP 地址为 192.168.100.113 并且设置了端口映射 -p 20160:20160，那么可以设置为 \-\-advertise-addr="192.168.100.113:20160"，客户端可以通过 192.168.100.113:20160 来找到这个服务 - -## `-C, --config` - -+ 配置文件 -+ 默认："" -+ 如果你指定了配置文件，TiKV 会首先读取配置文件的配置。然后如果对应的配置在命令行参数里面也存在，TiKV 就会使用命令行参数的配置来覆盖配置文件里面的 - -## `--capacity` - -+ TiKV 存储数据的容量 -+ 默认：0 (无限) -+ PD 需要使用这个值来对整个集群做 balance 操作。（提示：你可以使用 10GB 来替代 10737418240，从而简化参数的传递） - -## `--data-dir` - -+ TiKV 数据存储路径 -+ 默认："/tmp/tikv/store" - -## `-L, --log` - -+ Log 级别 -+ 默认："info" -+ 我们能选择 trace, debug, info, warn, error, 或者 off - -## `--log-file` - -+ Log 文件 -+ 默认："" -+ 如果没设置这个参数，log 会默认输出到 "stderr"，如果设置了，log 就会输出到对应的文件里面，在每天凌晨，log 会自动轮转使用一个新的文件，并且将以前的文件改名备份 - -## `--pd` - -+ PD 地址列表。 -+ 默认："" -+ TiKV 必须使用这个值连接 PD，才能正常工作。使用逗号来分隔多个 PD 地址，例如： - 192.168.100.113:2379, 192.168.100.114:2379, 192.168.100.115:2379 diff --git a/v3.1/reference/error-codes.md b/v3.1/reference/error-codes.md deleted file mode 100644 index 37ed36333734..000000000000 --- a/v3.1/reference/error-codes.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 错误码与故障诊断 -category: reference ---- - -# 错误码与故障诊断 - -本篇文档描述在使用 TiDB 过程中会遇到的问题以及解决方法。 - -## 错误码 - -TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样的错误码。另外还有一些特有的错误码： - -| 错误码 | 说明 | -| --------------------- | -------------------------------------------------- | -| 8001 | 请求使用的内存超过 TiDB 内存使用的阈值限制 | -| 8002 | 带有 `SELECT FOR UPDATE` 语句的事务，在遇到写入冲突时，为保证一致性无法进行重试，事务将进行回滚并返回该错误 | -| 8003 | `ADMIN CHECK TABLE` 命令在遇到行数据跟索引不一致的时候返回该错误 | -| 8004 | 单个事务过大，原因及解决方法请参考[这里](/v3.1/faq/tidb.md#433-transaction-too-large-是什么原因怎么解决) | -| 8005 | 事务在 TiDB 中遇到了写入冲突，原因及解决方法请参考[这里](/v3.1/faq/tidb.md#九故障排除) | -| 9001 | 请求 PD 超时，请检查 PD Server 状态/监控/日志以及 TiDB Server 与 PD Server 之间的网络 | -| 9002 | 请求 TiKV 超时，请检查 TiKV Server 状态/监控/日志以及 TiDB Server 与 TiKV Server 之间的网络 | -| 9003 | TiKV 操作繁忙，一般出现在数据库负载比较高时，请检查 TiKV Server 状态/监控/日志 | -| 9004 | 当数据库上承载的业务存在大量的事务冲突时，会遇到这种错误，请检查业务代码 | -| 9005 | 某个 Raft Group 不可用，如副本数目不足，出现在 TiKV 比较繁忙或者是 TiKV 节点停机的时候，请检查 TiKV Server 状态/监控/日志 | -| 9006 | GC Life Time 间隔时间过短，长事务本应读到的数据可能被清理了，应增加 GC Life Time | -| 9007 | 事务在 TiKV 中遇到了写入冲突，原因及解决方法请参考[这里](/v3.1/faq/tidb.md#九故障排除) | - -## 故障诊断 - -参见[故障诊断文档](/v3.1/how-to/troubleshoot/cluster-setup.md)以及 [FAQ](/v3.1/faq/tidb.md)。 diff --git a/v3.1/reference/garbage-collection/configuration.md b/v3.1/reference/garbage-collection/configuration.md deleted file mode 100644 index 00af8a0f61fd..000000000000 --- a/v3.1/reference/garbage-collection/configuration.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: GC 配置 -category: reference ---- - -# GC 配置 - -TiDB 的 GC 相关的配置存储于 `mysql.tidb` 系统表中，可以通过 SQL 语句对这些参数进行查询和更改： - -{{< copyable "sql" >}} - -```sql -select VARIABLE_NAME, VARIABLE_VALUE from mysql.tidb; -``` - -``` -+--------------------------+----------------------------------------------------------------------------------------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+--------------------------+----------------------------------------------------------------------------------------------------+ -| bootstrapped | True | -| tidb_server_version | 33 | -| system_tz | UTC | -| tikv_gc_leader_uuid | 5afd54a0ea40005 | -| tikv_gc_leader_desc | host:tidb-cluster-tidb-0, pid:215, start at 2019-07-15 11:09:14.029668932 +0000 UTC m=+0.463731223 | -| tikv_gc_leader_lease | 20190715-12:12:14 +0000 | -| tikv_gc_enable | true | -| tikv_gc_run_interval | 10m0s | -| tikv_gc_life_time | 10m0s | -| tikv_gc_last_run_time | 20190715-12:09:14 +0000 | -| tikv_gc_safe_point | 20190715-11:59:14 +0000 | -| tikv_gc_auto_concurrency | true | -| tikv_gc_mode | distributed | -+--------------------------+----------------------------------------------------------------------------------------------------+ -13 rows in set (0.00 sec) -``` - -例如，如果需要将 GC 调整为保留最近一天以内的数据，只需执行下列语句即可： - -{{< copyable "sql" >}} - -```sql -update mysql.tidb set VARIABLE_VALUE="24h" where VARIABLE_NAME="tikv_gc_life_time"; -``` - -> **注意：** -> -> `mysql.tidb` 系统表中除了下文将要列出的 GC 的配置以外，还包含一些 TiDB 用于储存部分集群状态（包括 GC 状态）的记录。请勿手动更改这些记录。其中，与 GC 有关的记录如下： -> -> - `tikv_gc_leader_uuid`，`tikv_gc_leader_desc` 和 `tikv_gc_leader_lease` 用于记录 GC leader 的状态 -> - `tikv_gc_last_run_time`：上次 GC 运行时间 -> - `tikv_gc_safe_point`：当前 GC 的 safe point - -## `tikv_gc_enable` - -- 控制是否启用 GC。 -- 默认值：`true` - -## `tikv_gc_run_interval` - -- 指定 GC 运行时间间隔。Duration 类型，使用 Go 的 Duration 字符串格式，如 `"1h30m"`，`"15m"` 等。 -- 默认值：`"10m0s"` - -## `tikv_gc_life_time` - -- 每次 GC 时，保留数据的时限。Duration 类型。每次 GC 时将以当前时间减去该配置的值作为 safe point。 -- 默认值：`"10m0s"` - -> **注意：** -> -> - `tikv_gc_life_time` 的值必须大于 TiDB 的配置文件中的 [`max-txn-time-use`](/v3.1/reference/configuration/tidb-server/configuration-file.md#max-txn-time-use) 的值至少 10 秒，且不低于 10 分钟。 -> -> - 在数据更新频繁的场景下，如果将 `tikv_gc_life_time` 设置得比较大（如数天甚至数月），可能会有一些潜在的问题，如： -> - 磁盘空间占用较多。 -> - 大量的历史版本会在一定程度上影响性能，尤其是范围查询（如 `select count(*) from t`）。 - -## `tikv_gc_mode` - -指定 GC 模式。可选值如下： - -- `"distributed"`（默认）：分布式 GC 模式。在此模式下，[Do GC](/v3.1/reference/garbage-collection/overview.md#do-gc) 阶段由 TiDB 上的 GC leader 向 PD 发送 safe point，每个 TiKV 节点各自获取该 safe point 并对所有当前节点上作为 leader 的 Region 进行 GC。此模式于 TiDB 3.0 引入。 - -- `"central"`：集中 GC 模式。在此模式下，[Do GC](/v3.1/reference/garbage-collection/overview.md#do-gc) 阶段由 GC leader 向所有的 Region 发送 GC 请求。TiDB 2.1 及更早版本采用此 GC 模式。 - -## `tikv_gc_auto_concurrency` - -控制是否由 TiDB 自动决定 GC concurrency，即同时进行 GC 的线程数。 - -当 `tikv_gc_mode` 设为 `"distributed"`，GC concurrency 将应用于 [Resolve Locks](/v3.1/reference/garbage-collection/overview.md#resolve-locks) 阶段。当 [`tikv_gc_mode`](#tikv_gc_mode) 设为 `"central"` 时，GC concurrency 将应用于 Resolve Locks 以及 [Do GC](/v3.1/reference/garbage-collection/overview.md#do-gc) 两个阶段。 - -- `true`（默认）：自动以 TiKV 节点的个数作为 GC concurrency -- `false`：使用 [`tikv_gc_concurrency`](#tikv_gc_concurrency) 的值作为 GC 并发数 - -## `tikv_gc_concurrency` - -- 手动设置 GC concurrency。要使用该参数，必须将 [`tikv_gc_auto_concurrency`](#tikv_gc_auto_concurrency) 设为 `false` 。 -- 默认值：2 - -## 关于 GC 流程的说明 - -从 TiDB 3.0 版本起，由于对分布式 GC 模式和并行 Resolve Locks 的支持，部分配置选项的作用发生了变化。可根据下表理解不同版本中这些配置的区别： - -| 版本/配置 | Resolve Locks | Do GC | -|-------------------|---------------|----------------| -| 2.x | 串行 | 并行 | -| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = false` | 并行 | 并行 | -| 3.0
`tikv_gc_mode = centered`
`tikv_gc_auto_concurrency = true` | 自动并行 | 自动并行 | -| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = false` | 并行 | 分布式 | -| 3.0
`tikv_gc_mode = distributed`
`tikv_gc_auto_concurrency = true`
（默认配置） | 自动并行 | 分布式 | - -表格内容说明： - -- 串行：由 TiDB 逐个向 Region 发送请求。 -- 并行：使用 `tikv_gc_concurrency` 选项所指定的线程数，并行地向每个 Region 发送请求。 -- 自动并行：使用 TiKV 节点的个数作为线程数，并行地向每个 Region 发送请求。 -- 分布式：无需 TiDB 通过对 TiKV 发送请求的方式来驱动，而是每台 TiKV 自行工作。 - -## 流控 - -TiKV 在 3.0.6 版本开始支持 GC 流控，可通过配置 `gc.max-write-bytes-per-sec` 限制 GC worker 每秒数据写入量，降低对正常请求的影响，`0` 为关闭该功能。该配置可通过 tikv-ctl 动态修改： - -{{< copyable "shell-regular" >}} - -```bash -tikv-ctl --host=ip:port modify-tikv-config -m server -n gc.max_write_bytes_per_sec -v 10MB -``` diff --git a/v3.1/reference/garbage-collection/overview.md b/v3.1/reference/garbage-collection/overview.md deleted file mode 100644 index f214a3147034..000000000000 --- a/v3.1/reference/garbage-collection/overview.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: GC 机制简介 -category: reference ---- - -# GC 机制简介 - -TiDB 的事务的实现采用了 MVCC（多版本并发控制）机制，当新写入的数据覆盖旧的数据时，旧的数据不会被替换掉，而是与新写入的数据同时保留，并以时间戳来区分版本。GC 的任务便是清理不再需要的旧数据。 - -## 整体流程 - -一个 TiDB 集群中会有一个 TiDB 实例被选举为 GC leader，GC 的运行由 GC leader 来控制。 - -GC 会被定期触发，默认情况下每 10 分钟一次。每次 GC 时，首先，TiDB 会计算一个称为 safe point 的时间戳（默认为当前时间减去 10 分钟），接下来 TiDB 会在保证 safe point 之后的快照全部拥有正确数据的前提下，删除更早的过期数据。具体而言，分为以下三个步骤： - -1. Resolve Locks -2. Delete Ranges -3. Do GC - -### Resolve Locks - -TiDB 的事务是基于 [Google Percolator](https://ai.google/research/pubs/pub36726) 模型实现的，事务的提交是一个两阶段提交的过程。第一阶段完成时，所有涉及的 key 会加上一个锁，其中一个锁会被设定为 Primary，其余的锁（Secondary）则会指向 Primary；第二阶段会将 Primary 锁所在的 key 加上一个 Write 记录，并去除锁。这里的 Write 记录就是历史上对该 key 进行写入或删除，或者该 key 上发生事务回滚的记录。Primary 锁被替换为何种 Write 记录标志着该事务提交成功与否。接下来，所有 Secondary 锁也会被依次替换。如果替换这些 Secondary 锁的线程死掉了，锁就残留了下来。 - -Resolve Locks 这一步的任务即对 safe point 之前的锁进行回滚或提交，取决于其 Primary 是否被提交。如果一个 Primary 锁也残留了下来，那么该事务应当视为超时并进行回滚。这一步是必不可少的，因为如果其 Primary 的 Write 记录由于太老而被 GC 清除掉了，那么就再也无法知道该事务是否成功。如果该事务存在残留的 Secondary 锁，那么也无法知道它应当被回滚还是提交，也就无法保证一致性。 - -Resolve Locks 的执行方式是由 GC leader 对所有的 Region 发送请求进行处理。从 3.0 起，这个过程默认会并行地执行，并发数量默认与 TiKV 节点个数相同。 - -## Delete Ranges - -在执行 `DROP TABLE/INDEX` 等操作时，会有大量连续的数据被删除。如果对每个 key 都进行删除操作、再对每个 key 进行 GC 的话，那么执行效率和空间回收速度都可能非常的低下。事实上，这种时候 TiDB 并不会对每个 key 进行删除操作，而是将这些待删除的区间及删除操作的时间戳记录下来。Delete Ranges 会将这些时间戳在 safe point 之前的区间进行快速的物理删除。 - -## Do GC - -这一步即删除所有 key 的过期版本。为了保证 safe point 之后的任何时间戳都具有一致的快照，这一步删除 safe point 之前提交的数据，但是会保留 safe point 前的最后一次写入（除非最后一次写入是删除）。 - -TiDB 2.1 及更早版本使用的 GC 方式是由 GC leader 向所有 Region 发送 GC 请求。从 3.0 起，GC leader 只需将 safe point 上传至 PD。每个 TiKV 节点都会各自从 PD 获取 safe point。当 TiKV 发现 safe point 发生更新时，便会对当前节点上所有作为 leader 的 Region 进行 GC。与此同时，GC leader 可以继续触发下一轮 GC。 - -> **注意：** -> -> 通过修改配置可以继续使用旧的 GC 方式，详情请参考 [GC 配置](/v3.1/reference/garbage-collection/configuration.md)。 diff --git a/v3.1/reference/key-monitoring-metrics/overview-dashboard.md b/v3.1/reference/key-monitoring-metrics/overview-dashboard.md deleted file mode 100644 index 90f6fa6ae66d..000000000000 --- a/v3.1/reference/key-monitoring-metrics/overview-dashboard.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Overview 面板重要监控指标详解 -category: reference ---- - -# Overview 面板重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们单独挑选出重要的 Metrics 放在 Overview 页面，方便日常运维人员观察集群组件 (PD, TiDB, TiKV) 使用状态以及集群使用状态。 - -以下为 Overview Dashboard 监控说明： - -## Services Port Status - -- Services Online：各服务在线节点数量 -- Services Offline：各服务 Down 掉节点数量 - -## PD - -- Storage Capacity：TiDB 集群总可用数据库空间大小 -- Current Storage Size：TiDB 集群目前已用数据库空间大小 -- Number of Regions：当前集群的 Region 总量 -- Leader Balance Ratio：Leader 数量最多和最少节点相差的百分比，一般小于 5%，节点重启时会有比较大的波动 -- Region Balance Ratio：Region 数量最多和最少节点相差的百分比，一般小于 5%，新增/下线节点时相差比较大 -- Store Status：集群 TiKV 节点的状态 - - Up Stores：正常运行的 TiKV 节点数量 - - Disconnect Stores：短时间内通信异常的 TiKV 节点数量 - - LowSpace Stores：剩余可用空间小于 20% 的 TiKV 节点数量 - - Down Stores：停止工作的 TiKV 节点数量，如果大于 0，说明有节点不正常 - - Offline Stores：正在下线的 TiKV 节点数量（正在下线的 TiKV 节点还在提供服务） - - Tombstone Stores：下线成功的 TiKV 节点数量 -- 99% completed\_cmds\_duration\_seconds：单位时间内，99% 的 pd-server 请求执行时间小于监控曲线的值，一般 <= 5ms -- handle\_requests\_duration\_seconds：PD 发送请求的网络耗时 - -## TiDB - -- Statement OPS：SQL 执行数量统计（包含 select、insert、update 等） -- Duration：SQL 执行的时间 -- QPS By Instance：每个 TiDB 上的 QPS -- Failed Query OPM：失败 SQL 的统计，例如语法错误、主键冲突等 -- Connection count：每个 TiDB 的连接数 -- Heap Memory Usage：每个 TiDB 使用的堆内存大小 -- Transaction OPS：事务执行数量统计 -- Transaction Duration：事务执行的时间 -- KV Cmd OPS：KV 命令执行数量统计 -- KV Cmd Duration 99：KV 命令执行的时间 -- PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 -- PD TSO Wait Duration：TiDB 从 PD 获取 TS 的时间 -- TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 -- Lock Resolve OPS：事务冲突相关的数量 -- Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 -- KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - -## TiKV - -- leader：各个 TiKV 节点上 Leader 的数量分布 -- region：各个 TiKV 节点上 Region 的数量分布 -- CPU：各个 TiKV 节点的 CPU 使用率 -- Memory：各个 TiKV 节点的内存使用量 -- store size：各个 TiKV 节点存储的数据量 -- cf size：集群不同 CF 存储的数据量 -- channel full：正常情况显示 No data，如果有了监控值，说明对应 TiKV 节点的消息处理不过来了 -- server report failures：正常情况显示 No data，如果出现了 Unreachable，说明 TiKV 之间通信有问题 -- scheduler pending commands：写入堆积的数量，偶尔出现峰值属于正常现象 -- coprocessor pending requests：正常情况监控为 0 或者数量很少 -- coprocessor executor count：不同类型的查询操作数量 -- coprocessor request duration：TiKV 中查询消耗的时间 -- raft store CPU：raftstore 线程的 CPU 使用率，线程数量默认为 2 (通过 `raftstore.store-pool-size` 配置)。如果单个线程使用率超过 80%，说明使用率很高 -- Coprocessor CPU：TiKV 查询线程的 CPU 使用率，和业务相关，复杂查询会使用大量的 CPU 资源 - -## System Info - -- Vcores：CPU 核心数量 -- Memory：内存总大小 -- CPU Usage：CPU 使用率，最大为 100% -- Load [1m]：1 分钟的负载情况 -- Memory Available：剩余内存大小 -- Network Traffic：网卡流量统计 -- TCP Retrans：网络监控，TCP 相关信息统计 -- IO Util：磁盘使用率，最高为 100%，一般到 80% - 90% 就需要考虑加节点 - -## 图例 - -![overview](/media/overview.png) diff --git a/v3.1/reference/key-monitoring-metrics/pd-dashboard.md b/v3.1/reference/key-monitoring-metrics/pd-dashboard.md deleted file mode 100644 index fbb065575896..000000000000 --- a/v3.1/reference/key-monitoring-metrics/pd-dashboard.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: PD 重要监控指标详解 -category: reference ---- - -# PD 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 PD 面板上的 Metrics，可以了解 PD 当前的状态。 - -以下为 PD Dashboard 监控说明： - -## Cluster - -- PD role：当前 PD 的角色 -- Storage capacity：TiDB 集群总可用数据库空间大小 -- Current storage size：TiDB 集群目前已用数据库空间大小 -- Current storage usage：TiDB 集群存储空间的使用率 -- Normal stores：处于正常状态的节点数目 -- Number of Regions：当前集群的 Region 总量 -- PD scheduler config：PD 调度配置列表 -- Region label isolation level：不同 label 所在的 level 的 Region 数量 -- Label distribution：集群中 TiKV 节点的 label 分布情况 -- Abnormal stores：处于异常状态的节点数目，正常情况应当为 0 -- pd_cluster_metadata：记录集群 ID，时间戳和生成的 ID -- Current peer count：当前集群 peer 的总量 -- Region health：每个 Region 的状态，通常情况下，pending 的 peer 应该少于 100，miss 的 peer 不能一直大于 0 - -![PD Dashboard - Cluster metrics](/media/pd-dashboard-cluster-v2.png) - -## Operator - -- Schedule operator create：新创建的不同 operator 的数量 -- Schedule operator check：已检查的 operator 的数量，主要检查是否当前步骤已经执行完成，如果是，则执行下一个步骤 -- Schedule operator finish：已完成调度的 operator 的数量 -- Schedule operator timeout：已超时的 operator 的数量 -- Schedule operator replaced or canceled：已取消或者被替换的 operator 的数量 -- Schedule operators count by state：不同状态的 operator 的数量 -- 99% Operator finish duration：99% 已完成 operator 所花费的最长时间 -- 50% Operator finish duration：50% 已完成 operator 所花费的最长时间 -- 99% Operator step duration：99% 已完成的 operator 步骤所花费的最长时间 -- 50% Operator step duration：50% 已完成的 operator 步骤所花费的最长时间 - -![PD Dashboard - Operator metrics](/media/pd-dashboard-operator-v2.png) - -## Statistics - Balance - -- Store capacity：每个 TiKV 实例的总的空间大小 -- Store available：每个 TiKV 实例的可用空间大小 -- Store used：每个 TiKV 实例的已使用空间大小 -- Size amplification：每个 TiKV 实例的空间放大比率 -- Size available ratio：每个 TiKV 实例的可用空间比率 -- Store leader score：每个 TiKV 实例的 leader 分数 -- Store Region score：每个 TiKV 实例的 Region 分数 -- Store leader size：每个 TiKV 实例上所有 leader 的大小 -- Store Region size：每个 TiKV 实例上所有 Region 的大小 -- Store leader count：每个 TiKV 实例上所有 leader 的数量 -- Store Region count：每个 TiKV 实例上所有 Region 的数量 - -![PD Dashboard - Balance metrics](/media/pd-dashboard-balance-v2.png) - -## Statistics - hotspot - -- Hot write Region's leader distribution：每个 TiKV 实例上是写入热点的 leader 的数量 -- Hot write Region's peer distribution：每个 TiKV 实例上是写入热点的 peer 的数量 -- Hot write Region's leader written bytes：每个 TiKV 实例上热点的 leader 的写入大小 -- Hot write Region's peer written bytes：每个 TiKV 实例上热点的 peer 的写入大小 -- Hot read Region's leader distribution：每个 TiKV 实例上是读取热点的 leader 的数量 -- Hot read Region's peer distribution：每个 TiKV 实例上是读取热点的 peer 的数量 -- Hot read Region's leader read bytes：每个 TiKV 实例上热点的 leader 的读取大小 -- Hot read Region's peer read bytes：每个 TiKV 实例上热点的 peer 的读取字节数 - -![PD Dashboard - Hotspot metrics](/media/pd-dashboard-hotspot.png) - -## Scheduler - -- Scheduler is running：所有正在运行的 scheduler -- Balance leader movement：leader 移动的详细情况 -- Balance Region movement：Region 移动的详细情况 -- Balance leader event：balance leader 的事件数量 -- Balance Region event：balance Region 的事件数量 -- Balance leader scheduler：balance-leader scheduler 的状态 -- Balance Region scheduler：balance-region scheduler 的状态 -- Namespace checker：namespace checker 的状态 -- Replica checker：replica checker 的状态 -- Region merge checker：merge checker 的状态 -- Filter target：尝试选择 Store 作为调度 taget 时没有通过 Filter 的计数 -- Filter source：尝试选择 Store 作为调度 source 时没有通过 Filter 的计数 -- Balance Direction：Store 被选作调度 target 或 source 的次数 -- Store Limit：Store 的调度限流状态 - -![PD Dashboard - Scheduler metrics](/media/pd-dashboard-scheduler-v2.png) - -## gRPC - -- Completed commands rate：gRPC 命令的完成速率 -- 99% Completed commands duration：99% 命令的最长消耗时间 - -![PD Dashboard - gRPC metrics](/media/pd-dashboard-grpc-v2.png) - -## etcd - -- Handle transactions count：etcd 的事务个数 -- 99% Handle transactions duration：99% 的情况下，处理 etcd 事务所需花费的时间 -- 99% WAL fsync duration：99% 的情况下，持久化 WAL 所需花费的时间，这个值通常应该小于 1s -- 99% Peer round trip time seconds：99% 的情况下，etcd 的网络延时，这个值通常应该小于 1s -- etcd disk WAL fsync rate：etcd 持久化 WAL 的速率 -- Raft term：当前 Raft 的 term -- Raft committed index：最后一次 commit 的 Raft index -- Raft applied index：最后一次 apply 的 Raft index - -![PD Dashboard - etcd metrics](/media/pd-dashboard-etcd-v2.png) - -## TiDB - -- Handle requests count：TiDB 的请求数量 -- Handle requests duration：每个请求所花费的时间，99% 的情况下，应该小于 100ms - -![PD Dashboard - TiDB metrics](/media/pd-dashboard-tidb-v2.png) - -## Heartbeat - -- Region heartbeat report：TiKV 向 PD 发送的心跳个数 -- Region heartbeat report error：TiKV 向 PD 发送的异常的心跳个数 -- Region heartbeat report active：TiKV 向 PD 发送的正常的心跳个数 -- Region schedule push：PD 向 TiKV 发送的调度命令的个数 -- 99% Region heartbeat latency：99% 的情况下，心跳的延迟 - -![PD Dashboard - Heartbeat metrics](/media/pd-dashboard-heartbeat-v2.png) - -## Region storage - -- Syncer Index：Leader 记录 Region 变更历史的最大 index -- history last index：Follower 成功同步的 Region 变更历史的 index - -![PD Dashboard - Region storage](/media/pd-dashboard-region-storage.png) diff --git a/v3.1/reference/key-monitoring-metrics/tidb-dashboard.md b/v3.1/reference/key-monitoring-metrics/tidb-dashboard.md deleted file mode 100644 index 63c08ff7d54d..000000000000 --- a/v3.1/reference/key-monitoring-metrics/tidb-dashboard.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: TiDB 重要监控指标详解 -category: reference ---- - -# TiDB 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等，TiDB 分为 TiDB 和 TiDB Summary 面板（其中 TiDB 面板包含 TiDB Summary 面板的内容）。 - -以下为 TiDB Dashboard 部分监控说明： - -## 说明 - -- Query Summary - - Duration：SQL 执行的时间 - - QPS：每个 TiDB 上的 SQL 执行结果按照 OK/Error 统计 - - Statement OPS：SQL 执行数量统计（包含 `SELECT`、`INSERT`、`UPDATE` 等） - - QPS By Instance：每个 TiDB 上的 QPS - - Failed Query OPM：每个 TiDB 实例上，执行 SQL 语句发生错误按照错误类型的统计（例如语法错误、主键冲突等） - - Slow query：慢查询处理时间统计（整个慢查询耗时、Coprocessor 耗时、Coprocessor 调度等待时间） - - 999/99/95/80 Duration：不同类型的 SQL 语句执行耗时统计（不同百分位） - -- Query Detail - - Duration 80/95/99/999 By Instance：每个 TiDB 实例执行 SQL 语句的耗时统计（不同百分位） - - Failed Query OPM Detail：整个集群执行 SQL 语句发生的错误按照错误类型统计（例如语法错误、主键冲突等） - - Internal SQL OPS：TiDB 内部 SQL 语句执行数量统计 - -- Server - - Uptime：TiDB 运行时间 - - Memory Usage：不同 TiDB 实例的内存使用统计 - - CPU Usage：不同 TiDB 实例的 CPU 使用统计 - - Connection Count：每个 TiDB 的连接数 - - Open FD Count：不同 TiDB 实例的打开的文件描述符统计 - - Goroutine Count：不同 TiDB 实例的 Goroutine 数量 - - Go GC Duration：不同 TiDB 实例的 GC 耗时统计 - - Go Threads：不同 TiDB 实例的线程数量 - - Go GC Count：不同 TiDB 实例的 GC 执行次数统计 - - Go GC CPU Usage：不同 TiDB 实例的 GC CPU 统计 - - Events OPM：统计关键事件，例如 start，close，graceful-shutdown，kill，hang 等 - - Keep Alive OPM：不同 TiDB 实例每分钟刷新监控的次数 - - Prepare Statement Count：不同 TiDB 实例执行 Prepare 语句数以及总数统计 - - Time Jump Back OPS：不同 TiDB 实例上每秒钟时间回跳的次数 - - Heap Memory Usage：每个 TiDB 使用的堆内存大小 - - Uncommon Error OPM：TiDB 非正常错误的统计，包括 panic，binlog 写失败等 - - Handshake Error OPS：不同 TiDB 实例每秒握手错误的次数统计 - - Get Token Duration：建立连接后获取 Token 耗时 - -- Transaction - - Transaction OPS：事务执行数量统计 - - Duration：事务执行的时间 - - Transaction Retry Num：事务重试次数 - - Transaction Statement Num：一个事务中的 SQL 语句数量 - - Session Retry Error OPS：事务重试时遇到的错误数量 - - Local Latch Wait Duration：本地事务等待时间 - -- Executor - - Parse Duration：SQL 语句解析耗时统计 - - Compile Duration：将 SQL AST 编译成执行计划耗时统计 - - Execution Duration：SQL 语句执行耗时统计 - - Expensive Executor OPS：消耗系统资源比较多的算子统计，包括 Merge Join，Hash Join，Index Look Up Join，Hash Agg，Stream Agg，Sort，TopN 等 - - Queries Using Plan Cache OPS：使用 Plan Cache 的查询数量统计 - -- Distsql - - Distsql Duration：Distsql 处理的时长 - - Distsql QPS：Distsql 的数量统计 - - Distsql Partial QPS：每秒 Partial Results 的数量 - - Scan Keys Num：每个 Query 扫描的 Key 的数量 - - Scan Keys Partial Num：每一个 Partial Result 扫描的 Key 的数量 - - Partial Num：每个 SQL 语句 Partial Results 的数量 - -- KV Errors - - KV Retry Duration：KV 重试请求的时间 - - TiClient Region Error OPS：TiKV 返回 Region 相关错误信息的数量 - - KV Backoff OPS：TiKV 返回错误信息的数量（事务冲突等） - - Lock Resolve OPS：事务冲突相关的数量 - - Other Errors OPS：其他类型的错误数量，包括清锁和更新 SafePoint - -- KV Duration - - KV Request Duration 999 by store：KV Request 执行时间，根据 TiKV 显示 - - KV Request Duration 999 by type：KV Request 执行时间，根据请求类型显示 - - KV Cmd Duration 99/999：KV 命令执行的时间 - -- KV Count - - KV Cmd OPS：KV 命令执行数量统计 - - KV Txn OPS：启动事务的数量统计 - - Txn Regions Num 90：事务使用的 Region 数量统计 - - Txn Write Size Bytes 100：事务写入的字节数统计 - - Txn Write KV Num 100：事务写入的 KV 数量统计 - - Load SafePoint OPS：更新 SafePoint 的数量统计 - -- PD Client - - PD Client CMD OPS：PD Client 执行命令数量统计 - - PD Client CMD Duration: PD Client 执行命令耗时 - - PD Client CMD Fail OPS：PD Client 执行命令失败统计 - - PD TSO OPS：TiDB 从 PD 获取 TSO 的数量 - - PD TSO Wait Duration：TiDB 从 PD 获取 TSO 的时间 - - PD TSO RPC Duration：TiDB 从调用 PD 获取 TSO gRPC 接口花费的时间 - -- Schema Load - - Load Schema Duration：TiDB 从 TiKV 获取 Schema 的时间 - - Load Schema OPS：TiDB 从 TiKV 获取 Schema 的数量统计 - - Schema Lease Error OPM：Schema Lease 出错，包括 change 和 outdate 两种，出现 outdate 错误时会报警 - -- DDL - - DDL Duration 95：DDL 语句处理时间统计 - - Batch Add Index Duration 100：创建索引时每个 Batch 所花费的时间统计 - - DDL Waiting Jobs Count：等待的 DDL 任务数量 - - DDL META OPM：DDL 每分钟获取 META 的次数 - - Deploy Syncer Duration：Schema Version Syncer 初始化，重启，清空等操作耗时 - - Owner Handle Syncer Duration：DDL Owner 在执行更新，获取以及检查 Schema Version 的耗时 - - Update Self Version Duration：Schema Version Syncer 更新版本信息耗时 - -- Statistics - - Auto Analyze Duration 95：自动 ANALYZE 耗时统计 - - Auto Analyze QPS：自动 ANALYZE 数量统计 - - Stats Inaccuracy Rate：统计信息不准确度统计 - - Pseudo Estimation OPS：使用假的统计信息优化 SQL 的数量统计 - - Dump Feedback OPS：存储统计信息 Feedback 的数量统计 - - Update Stats OPS：利用 Feedback 更新统计信息的数量统计 - - Significant Feedback：重要的 Feedback 更新统计信息的数量统计 - -- Meta - - AutoID QPS：AutoID 相关操作的数量统计，包括全局 ID 分配、单个 Table AutoID 分配、单个 Table AutoID Rebase 三种操作 - - AutoID Duration：AutoID 相关操作的耗时 - - Meta Operations Duration 99：Meta 操作延迟 - -- GC - - Worker Action OPM：GC 相关操作的数量统计，包括 run\_job，resolve\_lock，delete\_range 等操作 - - Duration 99：GC 相关操作的耗时统计 - - GC Failure OPM：GC 相关操作失败数量统计 - - Action Result OPM：GC 相关操作结果数量统计 - - Too Many Locks Error OPM：GC 清锁过多错误的数量统计 - -- Batch Client - - Pending Request Count by TiKV：等待处理的 Batch 消息数量统计 - - Wait Duration 95：等待处理的 Batch 消息延迟统计 - - Batch Client Unavailable Duration 95：Batch 客户端不可用的时间统计 diff --git a/v3.1/reference/key-monitoring-metrics/tikv-dashboard.md b/v3.1/reference/key-monitoring-metrics/tikv-dashboard.md deleted file mode 100644 index b1c49470fa67..000000000000 --- a/v3.1/reference/key-monitoring-metrics/tikv-dashboard.md +++ /dev/null @@ -1,429 +0,0 @@ ---- -title: TiKV 重要监控指标详解 -category: reference ---- - -# TiKV 重要监控指标详解 - -使用 Ansible 部署 TiDB 集群时，一键部署监控系统 (Prometheus/Grafana)，监控架构请看 [TiDB 监控框架概述](/v3.1/how-to/monitor/overview.md)。 - -目前 Grafana Dashboard 整体分为 PD、TiDB、TiKV、Node\_exporter、Overview 等。 - -对于日常运维，我们通过观察 TiKV 面板上的 Metrics，可以了解 TiKV 当前的状态。 - -以下为 TiKV Dashboard 监控说明： - -## Cluster - -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Available size：每个 TiKV 实例的可用的存储空间的大小 -- Capacity size：每个 TiKV 实例的存储容量的大小 -- CPU：每个 TiKV 实例 CPU 的使用率 -- Memory：每个 TiKV 实例内存的使用情况 -- IO utilization：每个 TiKV 实例 IO 的使用率 -- MBps：每个 TiKV 实例写入和读取的数据量大小 -- QPS：每个 TiKV 实例上各种命令的 QPS -- Errps：每个 TiKV 实例上 gRPC 消息失败的个数 -- leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 - -![TiKV Dashboard - Cluster metrics](/media/tikv-dashboard-cluster.png) - -## Errors - -- Server is busy：各种会导致 server 繁忙的事件个数，如 write stall，channel full 等，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Raftstore error：每个 TiKV 实例上 raftstore 发生错误的个数 -- Scheduler error：每个 TiKV 实例上 scheduler 发生错误的个数 -- Coprocessor error：每个 TiKV 实例上 coprocessor 发生错误的个数 -- gRPC message error：每个 TiKV 实例上 gRPC 消息发生错误的个数 -- Leader drop：每个 TiKV 实例上 drop leader 的个数 -- Leader missing：每个 TiKV 实例上 missing leader 的个数 - -![TiKV Dashboard - Errors metrics](/media/tikv-dashboard-errors.png) - -## Server - -- Leader：每个 TiKV 实例 leader 的个数 -- Region：每个 TiKV 实例 Region 的个数 -- CF size：每个 CF 的大小 -- Store size：每个 TiKV 实例的使用的存储空间的大小 -- Channel full：每个 TiKV 实例上 channel full 错误的数量，正常情况下应当为 0 -- Server report failures：server 报错的消息个数，正常情况下应当为 0 -- Region average written keys：每个 TiKV 实例上所有 Region 的平均 key 写入个数 -- Region average written bytes：每个 TiKV 实例上所有 Region 的平均写入大小 -- Active written leaders：每个 TiKV 实例上有效的 leader 个数 -- Approximate Region size：每个 Region 近似的大小 - -![TiKV Dashboard - Server metrics](/media/tikv-dashboard-server.png) - -## Raft IO - -- Apply log duration：Raft apply 日志所花费的时间 -- Apply log duration per server：每个 TiKV 实例上 Raft apply 日志所花费的时间 -- Append log duration：Raft append 日志所花费的时间 -- Append log duration per server：每个 TiKV 实例上 Raft append 日志所花费的时间 - -![TiKV Dashboard - Raft IO metrics](/media/tikv-dashboard-raftio.png) - -## Raft process - -- Ready handled：Raft 中不同 ready 类型的个数 -- Process ready duration per server：每个 TiKV 实例处理 ready 所花费的时间，99.99% 的情况下，应该小于 2s -- Process tick duration per server：每个 TiKV 实例处理 tick 所花费的时间 -- 0.99 Duration of Raft store events：99% 的 raftstore 事件所花费的时间 - -![TiKV Dashboard - Raft process metrics](/media/tikv-dashboard-raft-process.png) - -## Raft message - -- Sent messages per server：每个 TiKV 实例发送 Raft 消息的个数 -- Flush messages per server：每个 TiKV 实例持久化 Raft 消息的个数 -- Receive messages per server：每个 TiKV 实例接受 Raft 消息的个数 -- Messages：发送不同类型的 Raft 消息的个数 -- Vote：Raft 投票消息发送的个数 -- Raft dropped messages：丢弃不同类型的 Raft 消息的个数 - -![TiKV Dashboard - Raft message metrics](/media/tikv-dashboard-raft-message.png) - -## Raft propose - -- Raft proposals per ready：在一个 mio tick 内，所有 Region proposal 的个数 -- Raft read/write proposals：不同类型的 proposal 的个数 -- Raft read proposals per server：每个 TiKV 实例发起读 proposal 的个数 -- Raft write proposals per server：每个 TiKV 实例发起写 proposal 的个数 -- Propose wait duration：每个 proposal 的等待时间 -- Propose wait duration per server：每个 TiKV 实例上每个 proposal 的等待时间 -- Raft log speed：peer propose 日志的速度 - -![TiKV Dashboard - Raft propose metrics](/media/tikv-dashboard-raft-propose.png) - -## Raft admin - -- Admin proposals：admin proposal 的个数 -- Admin apply：apply 命令的个数 -- Check split：split check 命令的个数 -- 99.99% Check split duration：99.99% 的情况下，split check 所需花费的时间 - -![TiKV Dashboard - Raft admin metrics](/media/tikv-dashboard-raft-admin.png) - -## Local reader - -- Local reader requests：所有请求的总数以及 local read 线程拒绝的请求数量 -- Local read requests duration：local read 请求的等待时间 -- Local read requests batch size：local read 请求的批量大小 - -![TiKV Dashboard - Local reader metrics](/media/tikv-dashboard-local-reader.png) - -## Storage - -- Storage command total：收到不同命令的个数 -- Storage async request error：异步请求出错的个数 -- Storage async snapshot duration：异步处理 snapshot 所花费的时间，99% 的情况下，应该小于 1s -- Storage async write duration：异步写所花费的时间，99% 的情况下，应该小于 1s - -![TiKV Dashboard - Storage metrics](/media/tikv-dashboard-storage.png) - -## Scheduler - -- Scheduler stage total：每种命令不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler priority commands：不同优先级命令的个数 -- Scheduler pending commands：每个 TiKV 实例上 pending 命令的个数 - -![TiKV Dashboard - Scheduler metrics](/media/tikv-dashboard-scheduler.png) - -## Scheduler - batch_get - -- Scheduler stage total：batch_get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 batch_get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：batch_get 命令读取 key 的个数 -- Scheduler keys written：batch_get 命令写入 key 的个数 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details：执行 batch_get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 batch_get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 batch_get 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - batch_get metrics](/media/tikv-dashboard-scheduler-batch-get.png) - -## Scheduler - cleanup - -- Scheduler stage total：cleanup 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 cleanup 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：cleanup 命令读取 key 的个数 -- Scheduler keys written：cleanup 命令写入 key 的个数 -- Scheduler scan details：执行 cleanup 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 cleanup 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 cleanup 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 cleanup 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler - cleanup metrics](/media/tikv-dashboard-scheduler-cleanup.png) - -## Scheduler - commit - -- Scheduler stage total：commit 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 commit 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：commit 命令读取 key 的个数 -- Scheduler keys written：commit 命令写入 key 的个数 -- Scheduler scan details：执行 commit 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 commit 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 commit 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 commit 命令时，扫描每个 default CF 中 key 的详细情况 - -![TiKV Dashboard - Scheduler commit metrics](/media/tikv-dashboard-scheduler-commit.png) - -## Scheduler - gc - -- Scheduler stage total：gc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 gc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：gc 命令读取 key 的个数 -- Scheduler keys written：gc 命令写入 key 的个数 -- Scheduler scan details：执行 gc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 gc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 gc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 gc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - get - -- Scheduler stage total：get 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 get 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：get 命令读取 key 的个数 -- Scheduler keys written：get 命令写入 key 的个数 -- Scheduler scan details：执行 get 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 get 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 get 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 get 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - key_mvcc - -- Scheduler stage total：key_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 key_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：key_mvcc 命令读取 key 的个数 -- Scheduler keys written：key_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 key_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 key_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 key_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 key_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - prewrite - -- Scheduler stage total：prewrite 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 prewrite 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：prewrite 命令读取 key 的个数 -- Scheduler keys written：prewrite 命令写入 key 的个数 -- Scheduler scan details：执行 prewrite 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 prewrite 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 prewrite 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 prewrite 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - resolve_lock - -- Scheduler stage total：resolve_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 resolve_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：resolve_lock 命令读取 key 的个数 -- Scheduler keys written：resolve_lock 命令写入 key 的个数 -- Scheduler scan details：执行 resolve_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 resolve_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 resolve_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 resolve_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan - -- Scheduler stage total：scan 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan 命令读取 key 的个数 -- Scheduler keys written：scan 命令写入 key 的个数 -- Scheduler scan details：执行 scan 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - scan_lock - -- Scheduler stage total：scan_lock 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 scan_lock 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：scan_lock 命令读取 key 的个数 -- Scheduler keys written：scan_lock 命令写入 key 的个数 -- Scheduler scan details：执行 scan_lock 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 scan_lock 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 scan_lock 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 scan_lock 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - start_ts_mvcc - -- Scheduler stage total：start_ts_mvcc 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 start_ts_mvcc 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：start_ts_mvcc 命令读取 key 的个数 -- Scheduler keys written：start_ts_mvcc 命令写入 key 的个数 -- Scheduler scan details：执行 start_ts_mvcc 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 start_ts_mvcc 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 start_ts_mvcc 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 start_ts_mvcc 命令时，扫描每个 default CF 中 key 的详细情况 - -## Scheduler - unsafe_destroy_range - -- Scheduler stage total：unsafe_destroy_range 中每个命令所处不同阶段的个数，正常情况下，不会在短时间内出现大量的错误 -- Scheduler command duration：执行 unsafe_destroy_range 命令所需花费的时间，正常情况下，应该小于 1s -- Scheduler latch wait duration：由于 latch wait 造成的时间开销，正常情况下，应该小于 1s -- Scheduler keys read：unsafe_destroy_range 命令读取 key 的个数 -- Scheduler keys written：unsafe_destroy_range 命令写入 key 的个数 -- Scheduler scan details：执行 unsafe_destroy_range 命令时，扫描每个 CF 中 key 的详细情况 -- Scheduler scan details [lock]：执行 unsafe_destroy_range 命令时，扫描每个 lock CF 中 key 的详细情况 -- Scheduler scan details [write]：执行 unsafe_destroy_range 命令时，扫描每个 write CF 中 key 的详细情况 -- Scheduler scan details [default]：执行 unsafe_destroy_range 命令时，扫描每个 default CF 中 key 的详细情况 - -## Coprocessor - -- Request duration：处理 coprocessor 读请求所花费的时间 -- Wait duration：coprocessor 请求的等待时间，99.99% 的情况下，应该小于 10s -- Handle duration：处理 coprocessor 请求所花费的时间 -- 95% Request duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 读请求所花费的时间 -- 95% Wait duration by store：95% 的情况下，每个 TiKV 实例上 coprocessor 请求的等待时间 -- 95% Handle duration by store：95% 的情况下，每个 TiKV 实例处理 coprocessor 请求所花费的时间 -- Request errors：下推的请求发生错误的个数，正常情况下，短时间内不应该有大量的错误 -- DAG executors：DAG executor 的个数 -- Scan keys：每个请求 scan key 的个数 -- Scan details：scan 每个 CF 的详细情况 -- Table Scan - Details by CF：table scan 针对每个 CF 的详细情况 -- Index Scan - Details by CF：index scan 针对每个 CF 的详细情况 -- Table Scan - Perf Statistics：执行 table sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 -- Index Scan - Perf Statistics：执行 index sacn 的时候，根据 perf 统计的 RocksDB 内部 operation 的个数 - -## GC - -- MVCC versions：每个 key 的版本个数 -- MVCC delete versions：GC 删除掉的每个 key 的版本个数 -- GC tasks：由 gc_worker 处理的 GC 任务的个数 -- GC tasks Duration：执行 GC 任务时所花费的时间 -- GC keys (write CF)：在 GC 过程中，write CF 中 受影响的 key 的个数 -- TiDB GC actions result：TiDB Region 层面的 GC 结果 -- TiDB GC worker actions：TiDB GC worker 的不同 action 的个数 -- TiDB GC seconds：TiDB 执行 GC 花费的时间 -- TiDB GC failure：TiDB GC job 失败的个数 -- GC lifetime：TiDB 设置的 GC lifetime -- GC interval：TiDB 设置的 GC 间隔 - -## Snapshot - -- Rate snapshot message：发送 Raft snapshot 消息的速率 -- 99% Handle snapshot duration：99% 的情况下，处理 snapshot 所需花费的时间 -- Snapshot state count：不同状态的 snapshot 的个数 -- 99.99% Snapshot size：99.99% 的 snapshot 的大小 -- 99.99% Snapshot KV count：99.99% 的 snapshot 包含的 key 的个数 - -## Task - -- Worker handled tasks：worker 处理的任务个数 -- Worker pending tasks：当前 worker 中，pending 和 running 的任务个数，正常情况下，应该小于 1000 -- FuturePool handled tasks：future pool 处理的任务个数 -- FuturePool pending tasks：当前 future pool 中，pending 和 running 的任务个数 - -## Thread CPU - -- Raft store CPU：raftstore 线程的 CPU 使用率，通常应低于 80% -- Async apply CPU：async apply 线程的 CPU 使用率，通常应低于 90% -- Scheduler CPU：scheduler 线程的 CPU 使用率，通常应低于 80% -- Scheduler worker CPU：scheduler worker 线程的 CPU 使用率 -- Storage ReadPool CPU：Readpool 线程的 CPU 使用率 -- Coprocessor CPU：coprocessor 线程的 CPU 使用率 -- Snapshot worker CPU：snapshot worker 线程的 CPU 使用率 -- Split check CPU：split check 线程的 CPU 使用率 -- RocksDB CPU：RocksDB 线程的 CPU 使用率 -- gRPC poll CPU：gRPC 线程的 CPU 使用率，通常应低于 80% - -## RocksDB - kv - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## RocksDB - raft - -- Get operations：get 操作的个数 -- Get duration：get 操作的耗时 -- Seek operations：seek 操作的个数 -- Seek duration：seek 操作的耗时 -- Write operations：write 操作的个数 -- Write duration：write 操作的耗时 -- WAL sync operations：sync WAL 操作的个数 -- WAL sync duration：sync WAL 操作的耗时 -- Compaction operations：compaction 和 flush 操作的个数 -- Compaction duration：compaction 和 flush 操作的耗时 -- SST read duration：读取 SST 所需的时间 -- Write stall duration：由于 write stall 造成的时间开销，正常情况下应为 0 -- Memtable size：每个 CF 的 memtable 的大小 -- Memtable hit：memtable 的命中率 -- Block cache size：block cache 的大小。如果将 `shared block cache` 禁用，即为每个 CF 的 block cache 的大小 -- Block cache hit：block cache 的命中率 -- Block cache flow：不同 block cache 操作的流量 -- Block cache operations 不同 block cache 操作的个数 -- Keys flow：不同操作造成的 key 的流量 -- Total keys：每个 CF 中 key 的个数 -- Read flow：不同读操作的流量 -- Bytes / Read：每次读的大小 -- Write flow：不同写操作的流量 -- Bytes / Write：每次写的大小 -- Compaction flow：compaction 相关的流量 -- Compaction pending bytes：等待 compaction 的大小 -- Read amplification：每个 TiKV 实例的读放大 -- Compression ratio：每一层的压缩比 -- Number of snapshots：每个 TiKV 的 snapshot 的数量 -- Oldest snapshots duration：最旧的 snapshot 保留的时间 -- Number files at each level：每一层的文件个数 -- Ingest SST duration seconds：ingest SST 所花费的时间 -- Stall conditions changed of each CF：每个 CF stall 的原因 - -## gRPC - -- gRPC message count：每种 gRPC 消息的个数 -- gRPC message failed：失败的 gRPC 消息的个数 -- 99% gRPC message duration：在 99% gRPC 消息的执行时间 -- gRPC GC message count：gRPC GC 消息的个数 -- 99% gRPC KV GC message duration：在 99% 情况下，gRPC GC 消息的执行时间 - -## PD - -- PD requests：TiKV 发送给 PD 的请求个数 -- PD request duration (average)：TiKV 发送给 PD 的请求所需的平均时间 -- PD heartbeats：发送给 PD 的心跳个数 -- PD validate peers：通过 PD 验证 TiKV 的 peer 有效的个数 diff --git a/v3.1/reference/mysql-compatibility.md b/v3.1/reference/mysql-compatibility.md deleted file mode 100644 index 38f7b35e54a3..000000000000 --- a/v3.1/reference/mysql-compatibility.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: 与 MySQL 兼容性对比 -category: reference ---- - -# 与 MySQL 兼容性对比 - -TiDB 支持 MySQL 传输协议及其绝大多数的语法。这意味着您现有的 MySQL 连接器和客户端都可以继续使用。大多数情况下您现有的应用都可以迁移至 TiDB，无需任何代码修改。 - -当前 TiDB 服务器官方支持的版本为 MySQL 5.7。大部分 MySQL 运维工具（如 PHPMyAdmin, Navicat, MySQL Workbench 等），以及备份恢复工具（如 mysqldump, Mydumper/myloader）等都可以直接使用。 - -不过一些特性由于在分布式环境下没法很好的实现，目前暂时不支持或者是表现与 MySQL 有差异。一些 MySQL 语法在 TiDB 中可以解析通过，但是不会做任何后续的处理，例如 `Create Table` 语句中 `Engine`，是解析并忽略。 - -> **注意：** -> -> 本页内容仅涉及 MySQL 与 TiDB 的总体差异。关于[安全特性](/v3.1/reference/security/compatibility.md)、[悲观事务模型](/v3.1/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)的兼容信息请查看各自具体页面。 - -## 不支持的特性 - -* 存储过程与函数 -* 触发器 -* 事件 -* 自定义函数 -* 外键约束 -* 全文/空间函数与索引 -* 非 `ascii`/`latin1`/`binary`/`utf8`/`utf8mb4` 的字符集 -* `BINARY` 之外的排序规则 -* 增加/删除主键 -* SYS schema -* MySQL 追踪优化器 -* XML 函数 -* X Protocol -* Savepoints -* 列级权限 -* `XA` 语法（TiDB 内部使用两阶段提交，但并没有通过 SQL 接口公开） -* `CREATE TABLE tblName AS SELECT stmt` 语法 -* `CREATE TEMPORARY TABLE` 语法 -* `CHECK TABLE` 语法 -* `CHECKSUM TABLE` 语法 -* `SELECT INTO FILE` 语法 - -## 与 MySQL 有差异的特性 - -### 自增 ID - -TiDB 中，自增列只保证自增且唯一，并不保证连续分配。TiDB 目前采用批量分配 ID 的方式，所以如果在多台 TiDB 上同时插入数据，分配的自增 ID 会不连续。 - -在集群中有多个 tidb-server 实例时，如果表结构中有自增 ID，建议不要混用缺省值和自定义值，否则在如下情况下会遇到问题。 - -假设有这样一个带有自增 ID 的表： - -{{< copyable "sql" >}} - -```sql -create table t(id int unique key AUTO_INCREMENT, c int); -``` - -TiDB 实现自增 ID 的原理是每个 tidb-server 实例缓存一段 ID 值用于分配（目前会缓存 30000 个 ID），用完这段值再去取下一段。 - -假设集群中有两个 tidb-server 实例 A 和 B（A 缓存 [1,30000] 的自增 ID，B 缓存 [30001,60000] 的自增 ID），依次执行如下操作： - -1. 客户端向 B 插入一条将 `id` 设置为 1 的语句 `insert into t values (1, 1)`，并执行成功。 -2. 客户端向 A 发送 Insert 语句 `insert into t (c) (1)`，这条语句中没有指定 `id` 的值，所以会由 A 分配，当前 A 缓存了 [1, 30000] 这段 ID，所以会分配 1 为自增 ID 的值，并把本地计数器加 1。而此时数据库中已经存在 `id` 为 1 的数据，最终返回 `Duplicated Error` 错误。 - -另外，从 TiDB 3.0.4 版本开始，TiDB 将通过系统变量 `@@tidb_allow_remove_auto_inc` 控制是否允许通过 `alter table modify` 或 `alter table change` 来移除列的 `AUTO_INCREMENT` 属性，默认是不允许移除。 - -### Performance schema - -Performance schema 表在 TiDB 中返回结果为空。TiDB 使用 [Prometheus 和 Grafana](/v3.1/how-to/monitor/monitor-a-cluster.md) 来监测性能指标。 - -从 TiDB 3.0.4 版本开始，TiDB 支持 `events_statements_summary_by_digest`，参见 [Statement Summary Table](/v3.1/reference/performance/statement-summary.md)。 - -### 查询计划 - -TiDB 的查询计划（`EXPLAIN`/`EXPLAIN FOR`）输出格式与 MySQL 差别较大，同时 `EXPLAIN FOR` 的输出内容与权限设置与 MySQL 不一致，参见[理解 TiDB 执行计划](/v3.1/reference/performance/understanding-the-query-execution-plan.md)。 - -### 内建函数 - -TiDB 支持常用的 MySQL 内建函数，但是不是所有的函数都已经支持，具体请参考[语法文档](https://pingcap.github.io/sqlgram/#functioncallkeyword)。 - -### DDL - -在 TiDB 中，运行的 DDL 操作不会影响对表的读取或写入。但是，目前 DDL 变更有如下一些限制： - -+ Add Index - - 不支持同时创建多个索引 - - 不支持 `VISIBLE/INVISIBLE` 的索引 - - 不支持通过 `ALTER TABLE` 在所生成的列上添加索引 - - 其他类型的 Index Type (HASH/BTREE/RTREE) 只有语法支持，功能不支持 -+ Add Column - - 不支持同时创建多个列 - - 不支持将新创建的列设为主键或唯一索引，也不支持将此列设成 AUTO_INCREMENT 属性 -+ Drop Column: 不支持删除主键列或索引列 -+ Change/Modify Column - - 不支持有损变更，比如从 `BIGINT` 变为 `INTEGER`，或者从 `VARCHAR(255)` 变为 `VARCHAR(10)` - - 不支持修改 `DECIMAL` 类型的精度 - - 不支持更改 `UNSIGNED` 属性 - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ Alter Database - - 只支持将 `CHARACTER SET` 属性从 `utf8` 更改为 `utf8mb4` -+ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}`: TiDB 支持的语法，但是在 TiDB 中不会生效。所有支持的 DDL 变更都不会锁表。 -+ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}`: TiDB 完全支持 `ALGORITHM=INSTANT` 和 `ALGORITHM=INPLACE` 语法，但运行过程与 MySQL 有所不同，因为 MySQL 中的一些 `INPLACE` 操作实际上是 TiDB 中的 `INSTANT` 操作。`ALGORITHM=COPY` 语法在 TiDB 中不会生效，会返回警告信息。 -+ Table Option 不支持以下语法 - - `WITH/WITHOUT VALIDATION` - - `SECONDARY_LOAD/SECONDARY_UNLOAD` - - `CHECK/DROP CHECK` - - `STATS_AUTO_RECALC/STATS_SAMPLE_PAGES` - - `SECONDARY_ENGINE` - - `ENCRYPTION` -+ Table Partition 不支持以下语法 - - `PARTITION BY LIST` - - `PARTITION BY KEY` - - `SUBPARTITION` - - `{CHECK|EXCHANGE|TRUNCATE|OPTIMIZE|REPAIR|IMPORT|DISCARD|REBUILD|REORGANIZE} PARTITION` - -### `ANALYZE TABLE` - -- [`ANALYZE TABLE`](/v3.1/reference/performance/statistics.md#手动收集) 语句在 TiDB 和 MySQL 中表现不同。在 MySQL/InnoDB 中，它是一个轻量级语句，执行过程较短；而在 TiDB 中，它会完全重构表的统计数据，语句执行过程较长。 - -### 视图 - -目前 TiDB 不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 - -### 存储引擎 - -出于兼容性原因，TiDB 支持使用备用存储引擎创建表的语法。元数据命令将表描述为 InnoDB 存储引擎： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT) ENGINE=MyISAM; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -从架构上讲，TiDB 确实支持类似 MySQL 的存储引擎抽象，在启动 TiDB（通常是 `tikv`）时 [`--store`](/v3.1/reference/configuration/tidb-server/configuration.md#store) 选项指定的引擎中创建用户表。 - -### SQL 模式 - -TiDB 支持 MySQL 5.7 中 **绝大多数的 SQL 模式**，以下几种模式除外： - -- TiDB 不支持兼容模式（例如 `ORACLE` 和 `POSTGRESQL`）。MySQL 5.7 已弃用兼容模式，MySQL 8.0 已移除兼容模式。 -- TiDB 中的 `ONLY_FULL_GROUP_BY` 与 MySQL 5.7 相比有细微的[语义差别](/v3.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md#与-mysql-的区别)，此问题日后将予以解决。 -- `NO_DIR_IN_CREATE` 和 `NO_ENGINE_SUBSTITUTION` 这两种 SQL 模式用于解决兼容问题，但并不适用于 TiDB。 - -### 默认设置的区别 - -+ 默认字符集与 MySQL 不同： - + TiDB 中为 `utf8mb4` - + MySQL 5.7 中为 `latin1`，MySQL 8.0 中修改为 `utf8mb4` -+ 默认排序规则不同： - + TiDB 中，`utf8mb4` 的默认排序规则为 `utf8mb4_bin` - + MySQL 5.7 中，`utf8mb4` 的默认排序规则为 `utf8mb4_general_ci`，MySQL 8.0 中修改为 `utf8mb4_0900_ai_ci` - + 请使用 [`SHOW CHARACTER SET`](/v3.1/reference/sql/statements/show-character-set.md) 语句查看所有字符集的默认排序规则 -+ `foreign_key_checks` 的默认值不同： - + TiDB 中该值默认为 `OFF`，并且目前 TiDB 只支持设置该值为 `OFF`。 - + MySQL 5.7 中该值默认为 `ON`。 -+ 默认 SQL mode 与 MySQL 5.7 相同，与 MySQL 8.0 不同： - + TiDB 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` - + MySQL 中默认设置： - + MySQL 5.7 的默认 SQL mode 与 TiDB 相同 - + MySQL 8.0 中为 `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION` -+ `lower_case_table_names` 的默认值不同： - + TiDB 中该值默认为 2，并且目前 TiDB 只支持设置该值为 2 - + MySQL 中默认设置： - + Linux 系统中该值为 0 - + Windows 系统中该值为 1 - + macOS 系统中该值为 2 -+ `explicit_defaults_for_timestamp` 的默认值不同： - + TiDB 中该值默认为 `ON`，并且目前 TiDB 只支持设置该值为 `ON` - + MySQL 中默认设置： - + MySQL 5.7：`OFF` - + MySQL 8.0：`ON` - -### 日期时间处理的区别 - -#### 时区 - -MySQL 默认使用本地时区，依赖于系统内置的当前的时区规则（例如什么时候开始夏令时等）进行计算；且在未[导入时区表数据](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation)的情况下不能通过时区名称来指定时区。 - -TiDB 不需要导入时区表数据也能使用所有时区名称，采用系统当前安装的所有时区规则进行计算（一般为 `tzdata` 包），且无法通过导入时区表数据的形式修改计算规则。 - -> **注意：** -> -> 能下推到 TiKV 的时间相关表达式会由 TiKV 进行计算。TiKV 总是采用 TiKV 内置时区规则计算，而不依赖于系统所安装的时区规则。若系统安装的时区规则与 TiKV 内置的时区规则版本不匹配，则在少数情况下可能发生能插入的时间数据无法再读出来的问题。例如，若系统上安装了 tzdata 2018a 时区规则，则在时区设置为 Asia/Shanghai 或时区设置为本地时区且本地时区为 Asia/Shanghai 的情况下，时间 `1988-04-17 02:00:00` 可以被正常插入 TiDB 3.0 RC.1，但该记录对于特定类型 SQL 则无法再读出来，原因是 TiKV 3.0 RC.1 依据的 tzdata 2018i 规则中该时间在 Asia/Shanghai 时区中不存在（夏令时时间后移一小时）。 -> -> TiKV 各个版本内置的时区规则如下： -> -> - 3.0.0 RC.1 及以后：[tzdata 2018i](https://github.com/eggert/tz/tree/2018i) -> - 2.1.0 RC.1 及以后：[tzdata 2018e](https://github.com/eggert/tz/tree/2018e) - -#### 零月和零日 - -目前 TiDB 尚不能完整支持月为 `0` 或日为 `0`（但年不为 `0`）的日期。在非严格模式下，此类日期时间能被正常插入。但对于特定类型的 SQL 语句，可能出现无法读出来的情况。 - -#### 字符串类型行末空格的处理 - -目前 TiDB 在进行数据插入时，对于 `VARCHAR` 类型会保留行末空格，对于 `CHAR` 类型会插入截断空格后的数据。在没有索引的情况下，TiDB 和 MySQL 行为保持一致。如果 `VARCHAR` 类型上有 `UNIQUE` 索引，MySQL 在判断是否重复的时候，和处理 `CHAR` 类型一样，先截断 `VARCHAR` 数据末行空格再作判断；TiDB 则是按照保留空格的情况处理。 - -在做比较时，MySQL 会先截去常量和 Column 的末尾空格再作比较，而 TiDB 则是保留常量和 Column 的末尾空格来做精确比较。 - -### 类型系统的区别 - -以下的列类型 MySQL 支持，但 TiDB 不支持： - -+ FLOAT4/FLOAT8 -+ FIXED (alias for DECIMAL) -+ SERIAL (alias for BIGINT UNSIGNED NOT NULL AUTO_INCREMENT UNIQUE) -+ SQL_TSI_* （包括 SQL_TSI_YEAR、SQL_TSI_MONTH、SQL_TSI_WEEK、SQL_TSI_DAY、SQL_TSI_HOUR、SQL_TSI_MINUTE 和 SQL_TSI_SECOND） diff --git a/v3.1/reference/performance/check-cluster-status-using-sql-statements.md b/v3.1/reference/performance/check-cluster-status-using-sql-statements.md deleted file mode 100644 index a5328e6a14ec..000000000000 --- a/v3.1/reference/performance/check-cluster-status-using-sql-statements.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 使用 SQL 语句检查 TiDB 集群状态 -category: reference ---- - -# 使用 SQL 语句检查 TiDB 集群状态 - -为了方便排查问题，TiDB 提供了一些 SQL 语句和系统表以查询一些有用的信息。 - -`INFORMATION\_SCHEMA` 中提供了如下几个系统表，用于查询集群状态，诊断常见的集群问题。 - -- [`TABLES`](/v3.1/reference/system-databases/information-schema.md#tables-表) -- [`TIDB_INDEXES`](/v3.1/reference/system-databases/information-schema.md#tidb_indexes-表) -- [`ANALYZE_STATUS`](/v3.1/reference/system-databases/information-schema.md#analyze_status-表) -- [`TIDB_HOT_REGIONS`](/v3.1/reference/system-databases/information-schema.md#tidb_hot_regions-表) -- [`TIKV_STORE_STATUS`](/v3.1/reference/system-databases/information-schema.md#tikv_store_status-表) -- [`TIKV_REGION_STATUS`](/v3.1/reference/system-databases/information-schema.md#tikv_region_status-表) -- [`TIKV_REGION_PEERS`](/v3.1/reference/system-databases/information-schema.md#tikv_region_peers-表) - -除此之外，执行下列语句也可获得对排查问题或查询集群状态有用的信息： - -- `ADMIN SHOW DDL` 可以获得是 `DDL owner` 角色的 TiDB 的 ID 及 `IP:PORT` 等具体信息。 -- `SHOW ANALYZE STATUS` 和 [`ANALYZE_STATUS`](/v3.1/reference/system-databases/information-schema.md#analyze_status-表) 表的功能相同。 -- 特殊的 `EXPLAIN` 语句： - - `EXPLAIN ANALYZE` 语句可以获得一个 SQL 语句执行中的一些具体信息。 - - `EXPLAIN FOR CONNECTION` 可以获得一个连接中最后执行的查询的执行计划。可以配合 `SHOW PROCESSLIST` 使用。 - - 关于 `EXPLAIN` 相关的更具体的信息，参考文档[理解 TiDB 执行计划](/v3.1/reference/performance/understanding-the-query-execution-plan.md)。 \ No newline at end of file diff --git a/v3.1/reference/performance/execution-plan-bind.md b/v3.1/reference/performance/execution-plan-bind.md deleted file mode 100644 index 5464d45241d4..000000000000 --- a/v3.1/reference/performance/execution-plan-bind.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 执行计划绑定 -category: reference ---- - -# 执行计划绑定 - -在[优化器 Hints](/v3.1/reference/performance/optimizer-hints.md) 中介绍了可以通过 Hint 的方式选择指定的执行计划，但有的时候需要在不修改 SQL 语句的情况下干预执行计划的选择。执行计划绑定提供了一系列功能使得可以在不修改 SQL 语句的情况下选择指定的执行计划。 - -## 语法 - -### 创建绑定 - -{{< copyable "sql" >}} - -```sql -CREATE [GLOBAL | SESSION] BINDING FOR SelectStmt USING SelectStmt; -``` - -该语句可以在 GLOBAL 或者 SESSION 作用域内为 SQL 绑定执行计划。在不指定作用域时，隐式作用域为 SESSION。被绑定的 SQL 会被参数化后存储到系统表中。在处理 SQL 查询时，只要参数化后的 SQL 和系统表中某个被绑定的 SQL 一致即可使用相应的优化器 Hint。 - -`参数化`：把 SQL 中的常量变成变量参数，并对 SQL 中的空格和换行符等做标准化处理。例如： - -```sql -select * from t where a > 1 --- 参数化后： -select * from t where a > ？ -``` - -需要注意的是原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本必须相同，否则创建会失败，例如： - -{{< copyable "sql" >}} - -```sql -CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE a > 2; -``` - -可以创建成功，因为原始 SQL 和绑定 SQL 在参数化以及去掉 Hint 后文本都是 `select * from t where a > ?`，而 - -{{< copyable "sql" >}} - -```sql -CREATE BINDING FOR SELECT * FROM t WHERE a > 1 USING SELECT * FROM t use index(idx) WHERE b > 2; -``` - -则不可以创建成功，因为原始 SQL 在经过处理后是 `select * from t where a > ?`，而绑定 SQL 在经过处理后是 `select * from t where b > ?`。 - -### 删除绑定 - -{{< copyable "sql" >}} - -```sql -DROP [GLOBAL | SESSION] BINDING FOR SelectStmt; -``` - -该语句可以在 GLOBAL 或者 SESSION 作用域内删除指定的执行计划绑定，在不指定作用域时默认作用域为 SESSION。 - -### 查看绑定 - -{{< copyable "sql" >}} - -```sql -SHOW [GLOBAL | SESSION] BINDINGS [ShowLikeOrWhere]; -``` - -该语句会输出 GLOBAL 或者 SESSION 作用域内的执行计划绑定，在不指定作用域时默认作用域为 SESSION。目前 `SHOW BINDINGS` 会输出 8 列，具体如下： - -| 列名 | 说明 | -| -------- | ------------- | -| original_sql | 参数化后的原始 SQL | -| bind_sql | 带 Hint 的绑定 SQL | -| default_db | 默认数据库名 | -| status | 状态，包括 using（正在使用）、deleted（已删除）和 invalid（无效） | -| create_time | 创建时间 | -| update_time | 更新时间 | -| charset | 字符集 | -| collation | 排序规则 | diff --git a/v3.1/reference/performance/follower-read.md b/v3.1/reference/performance/follower-read.md deleted file mode 100644 index 48ea4ef91bec..000000000000 --- a/v3.1/reference/performance/follower-read.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Follower Read -summary: 了解 Follower Read 的使用与实现。 -category: reference ---- - -# Follower Read - -当系统中存在读取热点 Region 导致 leader 资源紧张成为整个系统读取瓶颈时，启用 Follower Read 功能可明显降低 leader 的负担，并且通过在多个 follower 之间均衡负载，显著地提升整体系统的吞吐能力。本文主要介绍 Follower Read 的使用方法与实现机制。 - -## 概述 - -Follower Read 功能是指在强一致性读的前提下使用 Region 的 follower 副本来承载数据读取的任务，从而提升 TiDB 集群的吞吐能力并降低 leader 负载。Follower Read 包含一系列将 TiKV 读取负载从 Region 的 leader 副本上 offload 到 follower 副本的负载均衡机制。TiKV 的 Follower Read 可以保证数据读取的线性一致性，配合 TiDB Snapshot Isolation 事务隔离级别，可以为用户提供强一致的数据读取能力。 - -> **注意：** -> -> 为了获得强一致读取的能力，在当前的实现中，follower 节点需要额外付出 `ReadIndex` 开销，因此目前 Follower Read 的主要益处是隔离集群的读写请求以及提升整体读取吞吐。从单个请求的 latency 角度看，会比传统的 leader 读取多付出一次与 Raft `ReadIndex` 的交互开销。 - -## 使用方式 - -要开启 TiDB 的 Follower Read 功能，将 SESSION 变量 `tidb_replica_read` 的值设置为 `follower` 即可： - -{{< copyable "sql" >}} - -```sql -set @@tidb_replica_read = 'follower'; -``` - -作用域：SESSION - -默认值：leader - -该变量用于设置当前会话期待的数据读取方式。 - -- 当设定为默认值 `leader` 或者空字符串时，TiDB 会维持原有行为方式，将所有的读取操作都发送给 leader 副本处理。 -- 当设置为 `follower` 时，TiDB 会选择 Region 的 follower 副本完成所有的数据读取操作。 - -## 实现机制 - -在 Follower Read 功能出现之前，TiDB 采用 strong leader 策略将所有的读写操作全部提交到 Region 的 leader 节点上完成。虽然 TiKV 能够很均匀地将 Region 分散到多个物理节点上，但是对于每一个 Region 来说，只有 leader 副本能够对外提供服务，另外的 follower 除了时刻同步数据准备着 failover 时投票切换成为 leader 外，没有办法对 TiDB 的请求提供任何帮助。 - -为了允许在 TiKV 的 follower 节点进行数据读取，同时又不破坏线性一致性和 Snapshot Isolation 的事务隔离，Region 的 follower 节点需要使用 Raft `ReadIndex` 协议确保当前读请求可以读到当前 leader 上已经 commit 的最新数据。在 TiDB 层面，Follower Read 只需根据负载均衡策略将某个 Region 的读取请求发送到 follower 节点。 - -### Follower 强一致读 - -TiKV follower 节点处理读取请求时，首先使用 Raft `ReadIndex` 协议与 Region 当前的 leader 进行一次交互，来获取当前 Raft group 最新的 commit index。本地 apply 到所获取的 leader 最新 commit index 后，便可以开始正常的读取请求处理流程。 - -### Follower 副本选择策略 - -由于 TiKV 的 Follower Read 可以保证线性一致性，不会破坏 TiDB 的 Snapshot Isolation 事务隔离级别，因此 TiDB 选择 follower 的策略可以采用 round robin 的方式。虽然 TiKV 可以选择任意的 follower 处理任意读取请求，但考虑到多个 follower 间复制速度不同，如果负载均衡的粒度过细，可能会导致明显的 latency 波动。目前，Follower Read 负载均衡策略粒度是连接级别的，对于一个 TiDB 的客户端连接在某个具体的 Region 上会固定使用同一个 follower，只有在选中的 follower 发生故障或者因调度策略发生调整的情况下才会进行切换。 diff --git a/v3.1/reference/performance/optimizer-hints.md b/v3.1/reference/performance/optimizer-hints.md deleted file mode 100644 index b5f8a25e097e..000000000000 --- a/v3.1/reference/performance/optimizer-hints.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: Optimizer Hints -category: reference ---- - -# Optimizer Hints - -TiDB 支持 Optimizer Hints 语法，它基于 MySQL 5.7 中介绍的类似 comment 的语法，例如 `/*+ HINT_NAME(t1, t2) */`。当 TiDB 优化器选择的不是最优查询计划时，建议使用 Optimizer Hints。 - -> **注意：** -> -> MySQL 命令行客户端在 5.7.7 版本之前默认清除了 Optimizer Hints。如果需要在这些早期版本的客户端中使用 `Hint` 语法，需要在启动客户端时加上 `--comments` 选项，例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。 - -## 语法 - -Optimizer Hints 通过 `/*+ ... */` 注释的形式跟在 `SELECT`、`UPDATE` 或 `DELETE` 关键字的后面，常见形式如 `/*+ HINT_NAME([t1_name [, t2_name] ...]) */`。Hint 名称不区分大小写，多个不同的 Hint 之间需用逗号隔开。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ USE_INDEX(t1, idx1), HASH_AGG(), HASH_JOIN(t1) */ count(*) from t t1, t t2 where t1.a = t2.b; -``` - -TiDB 目前支持两类 Hint，具体用法上有一些差别。第一类 Hint 用于控制优化器的行为，例如 [`/*+ HASH_AGG() */`](#hash_agg)。第二类 Hint 用于对单条查询设置一些运行参数，例如 [`/*+ MEMORY_QUOTA(1024 MB)*/`](#memory_quotan)。 - -## 优化器相关 Hint 语法 - -用于控制优化器行为的 Hint 跟在语句中**任意** `SELECT`、`UPDATE` 或 `DELETE` 关键字的后面。Hint 的生效范围以及 Hint 中使用的表的生效范围可通过 [Query Block](#query-block) 来指定，若不显式地指定 Query Block， Hint 的默认生效范围为当前 Query Block。 - -### Query Block - -一条语句中每一个查询和子查询都对应着一个不同的 Query Block，每个 Query Block 有自己对应的 `QB_NAME`。以下面这条语句为例： - -{{< copyable "sql" >}} - -```sql -select * from (select * from t) t1, (select * from t) t2; -``` - -该查询语句有 3 个 Query Block，最外面一层 `SELECT` 所在的 Query Block 的 `QB_NAME` 为 `sel_1`，两个 `SELECT` 子查询的 `QB_NAME` 依次为 `sel_2` 和 `sel_3`。其中数字序号根据 `SELECT` 出现的位置从左到右计数。如果分别用 `DELETE` 和 `UPDATE` 查询替代第一个 `SELECT` 查询，则对应的 `QB_NAME` 分别为 `del_1` 和 `upd_1`。 - -### QB_NAME - -你可以为当前 Query Block 的 `QB_NAME` 指定新的值，同时原本默认的 `QB_NAME` 值仍然有效。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ QB_NAME(QB1) */ * from (select * from t) t1, (select * from t) t2; -``` - -这条 Hint 将 `SELECT` 查询的 `QB_NAME` 设为 `QB1`，此时 `QB1` 和默认名称 `sel_1` 对于这个 Query Block 来说都是有效的。 - -> **注意：** -> -> 上述例子中，如果指定的 `QB_NAME` 为 `sel_2`，并且不给原本 `sel_2` 对应的第二个 Query Block 指定新的 `QB_NAME`，则第二个 Query Block 的 `QB_NAME` 默认值 `sel_2` 会失效。 - -### `@QB_NAME` 参数 - -除 `QB_NAME` 外，其余优化器相关的 Hint 都可以通过可选参数 `@QB_NAME` 来指定该 Hint 的生效范围。该参数需写在最前面，与其他参数用空格隔开。同时，你也可以在参数中的每一个表名后面加 `@QB_NAME` 来指定是哪个 Query Block 中的表。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ HASH_JOIN(@sel_1 t1@sel_1, t3) */ * from (select t1.a, t1.b from t t1, t t2 where t1.a = t2.a) t1, t t3 where t1.b = t3.b; -``` - -### SM_JOIN(t1_name [, tl_name ...]) - -`SM_JOIN(t1_name [, tl_name ...])` 提示优化器对指定表使用 Sort Merge Join 算法。这个算法通常会占用更少的内存，但执行时间会更久。当数据量太大，或系统内存不足时，建议尝试使用。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ SM_JOIN(t1, t2) */ * from t1，t2 where t1.id = t2.id; -``` - -> **注意：** -> -> `SM_JOIN` 的别名是 `TIDB_SMJ`，在 3.0.x 及之前版本仅支持使用该别名；之后的版本同时支持使用这两种名称。 - -### INL_JOIN(t1_name [, tl_name ...]) - -`INL_JOIN(t1_name [, tl_name ...])` 提示优化器对指定表使用 Index Nested Loop Join 算法。这个算法可能会在某些场景更快，消耗更少系统资源，有的场景会更慢，消耗更多系统资源。对于外表经过 WHERE 条件过滤后结果集较小（小于 1 万行）的场景，可以尝试使用。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ INL_JOIN(t1, t2) */ * from t1，t2 where t1.id = t2.id; -``` - -`INL_JOIN()` 中的参数是建立查询计划时内表的候选表，比如 `INL_JOIN(t1)` 只会考虑使用 t1 作为内表构建查询计划。表如果指定了别名，就只能使用表的别名作为 `INL_JOIN()` 的参数；如果没有指定别名，则用表的本名作为其参数。比如在 `select /*+ INL_JOIN(t1) */ * from t t1, t t2 where t1.a = t2.b;` 中，`INL_JOIN()` 的参数只能使用 t 的别名 t1 或 t2，不能用 t。 - -> **注意：** -> -> `INL_JOIN` 的别名是 `TIDB_INLJ`，在 3.0.x 及之前版本仅支持使用该别名；之后的版本同时支持使用这两种名称。 - -### HASH_JOIN(t1_name [, tl_name ...]) - -`HASH_JOIN(t1_name [, tl_name ...])` 提示优化器对指定表使用 Hash Join 算法。这个算法多线程并发执行，执行速度较快，但会消耗较多内存。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ HASH_JOIN(t1, t2) */ * from t1，t2 where t1.id = t2.id; -``` - -> **注意：** -> -> `HASH_JOIN` 的别名是 `TIDB_HJ`，在 3.0.x 及之前版本仅支持使用该别名；之后的版本同时支持使用这两种名称。 - -### HASH_AGG() - -`HASH_AGG()` 提示优化器使用 Hash Aggregation 算法。这个算法多线程并发执行，执行速度较快，但会消耗较多内存。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ HASH_AGG() */ count(*) from t1，t2 where t1.a > 10 group by t1.id; -``` - -### STREAM_AGG() - -`STREAM_AGG()` 提示优化器使用 Stream Aggregation 算法。这个算法通常会占用更少的内存，但执行时间会更久。数据量太大，或系统内存不足时，建议尝试使用。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ STREAM_AGG() */ count(*) from t1，t2 where t1.a > 10 group by t1.id; -``` - -### USE_INDEX(t1_name, idx1_name [, idx2_name ...]) - -`USE_INDEX(t1_name, idx1_name [, idx2_name ...])` 提示优化器对指定表仅使用给出的索引。 - -下面例子的效果等价于 `select * from t t1 use index(idx1, idx2);`： - -{{< copyable "sql" >}} - -```sql -select /*+ USE_INDEX(t1, idx1, idx2) */ * from t t1; -``` - -### IGNORE_INDEX(t1_name, idx1_name [, idx2_name ...]) - -`IGNORE_INDEX(t1_name, idx1_name [, idx2_name ...])` 提示优化器对指定表忽略给出的索引。 - -下面例子的效果等价于 `select * from t t1 ignore index(idx1, idx2);`： - -{{< copyable "sql" >}} - -```sql -select /*+ IGNORE_INDEX(t1, idx1, idx2) */ * from t t1; -``` - -### AGG_TO_COP() - -`AGG_TO_COP()` 提示优化器将聚合操作下推到 coprocessor。如果优化器没有下推某些适合下推的聚合函数，建议尝试使用。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ AGG_TO_COP() */ sum(t1.a) from t t1; -``` - -### READ_FROM_STORAGE(TIFLASH[t1_name [, tl_name ...]], TIKV[t2_name [, tl_name ...]]) - -`READ_FROM_STORAGE(TIFLASH[t1_name [, tl_name ...]], TIKV[t2_name [, tl_name ...]])` 提示优化器从指定的存储引擎来读取指定的表，目前支持的存储引擎参数有 `TIKV` 和 `TIFLASH`。例如： - -{{< copyable "sql" >}} - -```sql -select /*+ READ_FROM_STORAGE(TIFLASH[t1], TIKV[t2]) */ t1.a from t t1, t t2 where t1.a = t2.a; -``` - -## 运行参数相关 Hint 语法 - -运行参数相关的 Hint 只能跟在语句中**第一个** `SELECT`、`UPDATE` 或 `DELETE` 关键字的后面，对当前的这条查询的相关运行参数进行修改。 - -其优先级高于默认设置以及环境变量。 - -### MAX_EXECUTION_TIME(N) - -`MAX_EXECUTION_TIME(N)` 把语句的执行时间限制在 `N` 毫秒以内，超时后服务器会终止这条语句的执行。 - -下面的 Hint 设置了 1000 毫秒（即 1 秒）超时： - -{{< copyable "sql" >}} - -```sql -select /*+ MAX_EXECUTION_TIME(1000) */ * from t1 inner join t2 where t1.id = t2.id; -``` - -除了 Hint 之外，环境变量 `global.max_execution_time` 也能对语句执行时间进行限制。 - -### MEMORY_QUOTA(N) - -`MEMORY_QUOTA(N)` 用于限制语句执行时的内存使用。该 Hint 支持 MB 和 GB 两种单位。内存使用超过该限制时会根据当前设置的内存超限行为来打出一条 log 或者终止语句的执行。 - -下面的 Hint 设置了 1024 MB 的内存限制： - -{{< copyable "sql" >}} - -```sql -select /*+ MEMORY_QUOTA(1024 MB) */ * from t; -``` - -除了 Hint 外，环境变量 `tidb_mem_quota_query` 也能限制语句执行的内存使用。 - -### READ_FROM_REPLICA() - -`READ_FROM_REPLICA()` 会开启从数据一致的 TiKV follower 节点读取数据的特性。 - -下面的例子会从 follower 节点读取数据： - -{{< copyable "sql" >}} - -```sql -select /*+ READ_FROM_REPLICA() */ * from t; -``` - -除了 Hint 外，环境变量 `tidb_replica_read` 设为 `'follower'` 或者 `'leader'` 也能决定是否开启该特性。 - -### USE_TOJA(boolean_value) - -参数 `boolean_value` 可以是 `TRUE` 或者 `FALSE`。`USE_TOJA(TRUE)` 会开启优化器尝试将 in (subquery) 条件转换为 join 和 aggregation 的功能。相对地，`USE_TOJA(FALSE)` 会关闭该功能。 - -下面的例子会将 `in (select t2.a from t2) subq` 转换为等价的 join 和 aggregation： - -{{< copyable "sql" >}} - -```sql -select /*+ USE_TOJA(TRUE) */ t1.a, t1.b from t1 where t1.a in (select t2.a from t2) subq; -``` - -除了 Hint 外，环境变量 `tidb_opt_insubq_to_join_and_agg` 也能决定是否开启该功能。 diff --git a/v3.1/reference/performance/sql-optimizer-overview.md b/v3.1/reference/performance/sql-optimizer-overview.md deleted file mode 100644 index 5d922ce54720..000000000000 --- a/v3.1/reference/performance/sql-optimizer-overview.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: SQL 优化流程简介 -category: reference ---- - -# SQL 优化流程简介 - -在 TiDB 中，SQL 优化过程分为逻辑优化和物理优化两个阶段。 - -## 逻辑优化简介 - -逻辑优化是基于规则的优化，对输入的逻辑执行计划按顺序应用一些优化规则，从而使整个逻辑执行计划变得更好。这些优化规则包括： - -- 列裁剪 -- 投影消除 -- 关联子查询去关联 -- Max/Min 消除 -- 谓词下推 -- 分区裁剪 -- TopN 和 Limit 下推 - -## 物理优化简介 - -物理优化是基于代价的优化，为上一阶段产生的逻辑执行计划制定物理执行计划。这一阶段中，优化器会为逻辑执行计划中的每个算子选择具体的物理实现。逻辑算子的不同物理实现有着不同的时间复杂度、资源消耗和物理属性等。在这个过程中，优化器会根据数据的统计信息来确定不同物理实现的代价，并选择整体代价最小的物理执行计划。 - -逻辑执行计划是一个树形结构，每个节点对应 SQL 中的一个逻辑算子。同样的，物理执行计划也是一个树形结构，每个节点对应 SQL 中的一个物理算子。逻辑算子只描述这个算子的功能，而物理算子则描述了完成这个功能的具体算法。对于同一个逻辑算子，可能有多个物理算子实现，比如 `LogicalAggregate`，它的实现可以是采用哈希算法的 `HashAggregate`，也可以是流式的 `StreamAggregate`。不同的物理算子具有不同的物理属性，也对其子节点有着不同的物理属性的要求。物理属性包括数据的顺序和分布等。TiDB 中现在只考虑了数据的顺序。 diff --git a/v3.1/reference/performance/statement-summary.md b/v3.1/reference/performance/statement-summary.md deleted file mode 100644 index f553fcd49aa5..000000000000 --- a/v3.1/reference/performance/statement-summary.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: Statement Summary Tables -category: reference ---- - -# Statement Summary Tables - -针对 SQL 性能相关的问题，MySQL 在 `performance_schema` 提供了 [statement summary tables](https://dev.mysql.com/doc/refman/5.6/en/statement-summary-tables.html)，用来监控和统计 SQL。例如其中的一张表 `events_statements_summary_by_digest`，提供了丰富的字段，包括延迟、执行次数、扫描行数、全表扫描次数等，有助于用户定位 SQL 问题。 - -为此，从 3.1.0-beta 版本开始，TiDB 也提供系统表 `events_statements_summary_by_digest`，从 3.1.0-beta.1 开始提供系统表 `events_statements_summary_by_digest_history`。本文将详细介绍这两张表，以及如何利用它们来排查 SQL 性能问题。 - -## `events_statements_summary_by_digest` - -`events_statements_summary_by_digest` 是 `performance_schema` 里的一张系统表，它把 SQL 按 SQL digest 和 plan digest 分组，统计每一组的 SQL 信息。 - -此处的 SQL digest 与 slow log 里的 SQL digest 一样，是把 SQL 规一化后算出的唯一标识符。SQL 的规一化会忽略常量、空白符、大小写的差别。即语法一致的 SQL 语句，其 digest 也相同。 - -例如： - -```sql -SELECT * FROM employee WHERE id IN (1, 2, 3) AND salary BETWEEN 1000 AND 2000; -select * from EMPLOYEE where ID in (4, 5) and SALARY between 3000 and 4000; -``` - -规一化后都是： - -```sql -select * from employee where id in (...) and salary between ? and ?; -``` - -此处的 plan digest 是把执行计划规一化后算出的唯一标识符。执行计划的规一化会忽略常量的差别。由于相同的 SQL 可能产生不同的执行计划，所以可能分到多个组，同一个组内的执行计划是相同的。 - -`events_statements_summary_by_digest` 用于保存 SQL 监控指标聚合后的结果。一般来说，每一项监控指标都包含平均值和最大值。例如执行延时对应 `AVG_LATENCY` 和 `MAX_LATENCY` 两个字段，分别是平均延时和最大延时。 - -为了监控指标的即时性，`events_statements_summary_by_digest` 里的数据定期被清空，只展现最近一段时间内的聚合结果。清空周期由系统变量 `tidb_stmt_summary_refresh_interval` 设置。如果刚好在清空之后进行查询，显示的数据可能很少。 - -因为 TiDB 中的很多概念不同于 MySQL，所以 TiDB 中 `events_statements_summary_by_digest` 的表结构与 MySQL 中的有很大区别。 - -以下为查询 `events_statements_summary_by_digest` 的部分结果： - -``` - SUMMARY_BEGIN_TIME: 2020-01-02 11:00:00 - SUMMARY_END_TIME: 2020-01-02 11:30:00 - STMT_TYPE: select - SCHEMA_NAME: test - DIGEST: 0611cc2fe792f8c146cc97d39b31d9562014cf15f8d41f23a4938ca341f54182 - DIGEST_TEXT: select * from employee where id = ? - TABLE_NAMES: test.employee - INDEX_NAMES: NULL - SAMPLE_USER: root - EXEC_COUNT: 3 - SUM_LATENCY: 1035161 - MAX_LATENCY: 399594 - MIN_LATENCY: 301353 - AVG_LATENCY: 345053 - AVG_PARSE_LATENCY: 57000 - MAX_PARSE_LATENCY: 57000 - AVG_COMPILE_LATENCY: 175458 - MAX_COMPILE_LATENCY: 175458 - ........... - AVG_MEM: 103 - MAX_MEM: 103 - AVG_AFFECTED_ROWS: 0 - FIRST_SEEN: 2020-01-02 11:12:54 - LAST_SEEN: 2020-01-02 11:25:24 - QUERY_SAMPLE_TEXT: select * from employee where id=3100 - PREV_SAMPLE_TEXT: - PLAN_DIGEST: f415b8d52640b535b9b12a9c148a8630d2c6d59e419aad29397842e32e8e5de3 - PLAN: Point_Get_1 root 1 table:employee, handle:3100 -``` - -> **注意：** -> -> 在 TiDB 中，statement summary tables 中字段的时间单位是纳秒 (ns)，而 MySQL 中的时间单位是皮秒 (ps)。 - -### 表的字段介绍 - -SQL 的基础信息： - -- `STMT_TYPE`：SQL 语句的类型 -- `SCHEMA_NAME`：执行这类 SQL 的当前 schema -- `DIGEST`：这类 SQL 的 digest -- `DIGEST_TEXT`：规一化后的 SQL -- `QUERY_SAMPLE_TEXT`：这类 SQL 的原 SQL 语句，多条语句只取其中一条 -- `TABLE_NAMES`：SQL 中涉及的所有表，多张表用 `,` 分隔 -- `INDEX_NAMES`：SQL 中使用的索引名，多个索引用 `,` 分隔 -- `SAMPLE_USER`：执行这类 SQL 的用户名，多个用户名只取其中一个 -- `PLAN_DIGEST`：执行计划的 digest -- `PLAN`：原执行计划，多条语句只取其中一条的执行计划 - -执行时间相关的信息： - -- `SUMMARY_BEGIN_TIME`：当前统计的时间段的开始时间 -- `SUMMARY_END_TIME`：当前统计的时间段的结束时间 -- `FIRST_SEEN`：这类 SQL 的首次出现时间 -- `LAST_SEEN`：这类 SQL 的最后一次出现时间 - -在 TiDB server 上的执行数据： - -- `EXEC_COUNT`：这类 SQL 的总执行次数 -- `SUM_LATENCY`：这类 SQL 的总延时 -- `MAX_LATENCY`：这类 SQL 的最大延时 -- `MIN_LATENCY`：这类 SQL 的最小延时 -- `AVG_LATENCY`：这类 SQL 的平均延时 -- `AVG_PARSE_LATENCY`：解析器的平均延时 -- `MAX_PARSE_LATENCY`：解析器的最大延时 -- `AVG_COMPILE_LATENCY`：优化器的平均延时 -- `MAX_COMPILE_LATENCY`：优化器的最大延时 -- `AVG_MEM`：使用的平均内存，单位 byte -- `MAX_MEM`：使用的最大内存，单位 byte - -和 TiKV Coprocessor Task 相关的字段： - -- `COP_TASK_NUM`：每条 SQL 发送的 Coprocessor 请求数量 -- `AVG_COP_PROCESS_TIME`：cop-task 的平均处理时间 -- `MAX_COP_PROCESS_TIME`：cop-task 的最大处理时间 -- `MAX_COP_PROCESS_ADDRESS`：执行时间最长的 cop-task 所在地址 -- `AVG_COP_WAIT_TIME`：cop-task 的平均等待时间 -- `MAX_COP_WAIT_TIME`：cop-task 的最大等待时间 -- `MAX_COP_WAIT_ADDRESS`：等待时间最长的 cop-task 所在地址 -- `AVG_PROCESS_TIME`：SQL 在 TiKV 的平均处理时间 -- `MAX_PROCESS_TIME`：SQL 在 TiKV 的最大处理时间 -- `AVG_WAIT_TIME`：SQL 在 TiKV 的平均等待时间 -- `MAX_WAIT_TIME`：SQL 在 TiKV 的最大等待时间 -- `AVG_BACKOFF_TIME`：SQL 遇到需要重试的错误时在重试前的平均等待时间 -- `MAX_BACKOFF_TIME`：SQL 遇到需要重试的错误时在重试前的最大等待时间 -- `AVG_TOTAL_KEYS`：Coprocessor 扫过的 key 的平均数量 -- `MAX_TOTAL_KEYS`：Coprocessor 扫过的 key 的最大数量 -- `AVG_PROCESSED_KEYS`：Coprocessor 处理的 key 的平均数量。相比 `avg_total_keys`，`avg_processed_keys` 不包含 MVCC 的旧版本。如果 `avg_total_keys` 和 `avg_processed_keys` 相差很大，说明旧版本比较多 -- `MAX_PROCESSED_KEYS`：Coprocessor 处理的 key 的最大数量 - -和事务相关的字段： - -- `AVG_PREWRITE_TIME`：prewrite 阶段消耗的平均时间 -- `MAX_PREWRITE_TIME` prewrite 阶段消耗的最大时间 -- `AVG_COMMIT_TIME`：commit 阶段消耗的平均时间 -- `MAX_COMMIT_TIME`：commit 阶段消耗的最大时间 -- `AVG_GET_COMMIT_TS_TIME`：获取 commit_ts 的平均时间 -- `MAX_GET_COMMIT_TS_TIME`：获取 commit_ts 的最大时间 -- `AVG_COMMIT_BACKOFF_TIME`：commit 时遇到需要重试的错误时在重试前的平均等待时间 -- `MAX_COMMIT_BACKOFF_TIME`：commit 时遇到需要重试的错误时在重试前的最大等待时间 -- `AVG_RESOLVE_LOCK_TIME`：解决事务的锁冲突的平均时间 -- `MAX_RESOLVE_LOCK_TIME`：解决事务的锁冲突的最大时间 -- `AVG_LOCAL_LATCH_WAIT_TIME`：本地事务等待的平均时间 -- `MAX_LOCAL_LATCH_WAIT_TIME`：本地事务等待的最大时间 -- `AVG_WRITE_KEYS`：写入 key 的平均数量 -- `MAX_WRITE_KEYS`：写入 key 的最大数量 -- `AVG_WRITE_SIZE`：写入的平均数据量，单位 byte -- `MAX_WRITE_SIZE`：写入的最大数据量，单位 byte -- `AVG_PREWRITE_REGIONS`：prewrite 涉及的平均 Region 数量 -- `MAX_PREWRITE_REGIONS`：prewrite 涉及的最大 Region 数量 -- `AVG_TXN_RETRY`：事务平均重试次数 -- `MAX_TXN_RETRY`：事务最大重试次数 -- `SUM_BACKOFF_TIMES`：这类 SQL 遇到需要重试的错误后的总重试次数 -- `BACKOFF_TYPES`：遇到需要重试的错误时的所有错误类型及每种类型重试的次数，格式为 `类型:次数`。如有多种错误则用 `,` 分隔，例如 `txnLock:2,pdRPC:1` -- `AVG_AFFECTED_ROWS`：平均影响行数 -- `PREV_SAMPLE_TEXT`：当 SQL 是 `COMMIT` 时，该字段为 `COMMIT` 的前一条语句；否则该字段为空字符串。当 SQL 是 `COMMIT` 时，按 digest 和 `prev_sample_text` 一起分组，即不同 `prev_sample_text` 的 `COMMIT` 也会分到不同的行 - -## `events_statements_summary_by_digest_history` - -`events_statements_summary_by_digest_history` 的表结构与 `events_statements_summary_by_digest` 完全相同，用于保存历史时间段的数据。通过历史数据，可以排查过去出现的异常，也可以对比不同时间的监控指标。 - -字段 `SUMMARY_BEGIN_TIME` 和 `SUMMARY_END_TIME` 代表历史时间段的开始时间和结束时间。 - -## 排查示例 - -下面用两个示例问题演示如何利用 statement summary 来排查。 - -### SQL 延迟比较大，是不是服务端的问题？ - -例如客户端显示 employee 表的点查比较慢，那么可以按 SQL 文本来模糊查询： - -```sql -SELECT avg_latency, exec_count, query_sample_text - FROM performance_schema.events_statements_summary_by_digest - WHERE digest_text LIKE 'select * from employee%'; -``` - -结果如下，`avg_latency` 是 1 ms 和 0.3 ms，在正常范围，所以可以判定不是服务端的问题，继而排查客户端或网络问题。 - -``` -+-------------+------------+------------------------------------------+ -| avg_latency | exec_count | query_sample_text | -+-------------+------------+------------------------------------------+ -| 1042040 | 2 | select * from employee where name='eric' | -| 345053 | 3 | select * from employee where id=3100 | -+-------------+------------+------------------------------------------+ -2 rows in set (0.00 sec) -``` - -### 哪类 SQL 的总耗时最高？ - -假如上午 10:00 到 10:30 的 QPS 明显下降，可以从历史表中找出当时耗时最高的三类 SQL： - -```sql -SELECT sum_latency, avg_latency, exec_count, query_sample_text - FROM performance_schema.events_statements_summary_by_digest_history - WHERE summary_begin_time='2020-01-02 10:00:00' - ORDER BY sum_latency DESC LIMIT 3; -``` - -结果显示以下三类 SQL 的总延迟最高，所以这些 SQL 需要重点优化。 - -``` -+-------------+-------------+------------+-----------------------------------------------------------------------+ -| sum_latency | avg_latency | exec_count | query_sample_text | -+-------------+-------------+------------+-----------------------------------------------------------------------+ -| 7855660 | 1122237 | 7 | select avg(salary) from employee where company_id=2013 | -| 7241960 | 1448392 | 5 | select * from employee join company on employee.company_id=company.id | -| 2084081 | 1042040 | 2 | select * from employee where name='eric' | -+-------------+-------------+------------+-----------------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -## 参数配置 - -statement summary 功能默认关闭，通过设置系统变量打开，例如： - -```sql -set global tidb_enable_stmt_summary = true; -``` - -statement summary 关闭后，系统表里的数据会被清空，下次打开后重新统计。经测试，打开后对性能几乎没有影响。 - -还有两个控制 statement summary 的系统变量： - -- `tidb_stmt_summary_refresh_interval`：`events_statements_summary_by_digest` 的清空周期，单位是秒 (s)，默认值是 `1800`。 -- `tidb_stmt_summary_history_size`：`events_statements_summary_by_digest_history` 保存每种 SQL 的历史的数量，默认值是 `24`。 - -statement summary 配置示例如下： - -```sql -set global tidb_stmt_summary_refresh_interval = 1800; -set global tidb_stmt_summary_history_size = 24; -``` - -以上配置生效后，`events_statements_summary_by_digest` 每 30 分钟清空一次，`events_statements_summary_by_digest_history` 保存最近 12 小时的历史数据。 - -以上两个系统变量都有 global 和 session 两种作用域，它们的生效方式与其他系统变量不一样： - -- 设置 global 变量后整个集群立即生效 -- 设置 session 变量后当前 TiDB server 立即生效，这对于调试单个 TiDB server 比较有用 -- 优先读 session 变量，没有设置过 session 变量才会读 global 变量 -- 把 session 变量设为空字符串，将会重新读 global 变量 - -由于 statement summary tables 是内存表，为了防止内存问题，需要限制保存的 SQL 条数和 SQL 的最大显示长度。这两个参数都在 config.toml 的 `[stmt-summary]` 类别下配置： - -- 通过 `max-stmt-count` 更改保存的 SQL 种类数量，默认 200 条。当 SQL 种类超过 `max-stmt-count` 时，会移除最近没有使用的 SQL。 -- 通过 `max-sql-length` 更改 `DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 的最大显示长度，默认是 4096。 - -> **注意：** -> -> `tidb_stmt_summary_history_size`、`max-stmt-count`、`max-sql-length` 这些配置都影响内存占用，建议根据实际情况调整，不宜设置得过大。 - -## 目前的限制 - -Statement summary tables 现在还存在一些限制： - -- 查询 statement summary tables 时，只会显示当前 TiDB server 的 statement summary，而不是整个集群的 statement summary。 -- TiDB server 重启后 statement summary 会丢失。因为 statement summary tables 是内存表，不会持久化数据，所以一旦 server 被重启，statement summary 随之丢失。 diff --git a/v3.1/reference/performance/statistics.md b/v3.1/reference/performance/statistics.md deleted file mode 100644 index a9c54342abd4..000000000000 --- a/v3.1/reference/performance/statistics.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: 统计信息简介 -category: reference ---- - -# 统计信息简介 - -TiDB 优化器会根据统计信息来选择最优的执行计划。统计信息收集了表级别和列级别的信息，表的统计信息包括总行数和修改的行数。列的统计信息包括不同值的数量、NULL 的数量、直方图、列上出现次数最多的值 TOPN 以及该列的 Count-Min Sketch 信息。 - -## 统计信息的收集 - -### 手动收集 - -可以通过执行 `ANALYZE` 语句来收集统计信息。 - -#### 全量收集 - -> **注意：** -> -> 在 TiDB 中执行 `ANALYZE TABLE` 语句比在 MySQL 或 InnoDB 中耗时更长。InnoDB 采样的只是少量页面，但 TiDB 会完全重构一系列统计信息。适用于 MySQL 的脚本会误以为执行 `ANALYZE TABLE` 耗时较短。 -> -> 如需更快的分析速度，可将 `tidb_enable_fast_analyze` 设置为 `1` 来打开快速分析功能。该参数的默认值为 `0`。 -> -> 快速分析功能开启后，TiDB 会随机采样约 10000 行的数据来构建统计信息。因此在数据分布不均匀或者数据量比较少的情况下，统计信息的准确度会比较差。可能导致执行计划不优，比如选错索引。如果可以接受普通 `ANALYZE` 语句的执行时间，则推荐关闭快速分析功能。 - -可以通过以下几种语法进行全量收集。 - -收集 TableNameList 中所有表的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableNameList [WITH NUM BUCKETS]; -``` - -WITH NUM BUCKETS 可以用来指定生成直方图的桶数量上限。 - -收集 TableName 中所有的 IndexNameList 中的索引列的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableName INDEX [IndexNameList] [WITH NUM BUCKETS]; -``` - -IndexNameList 为空时会收集所有索引列的统计信息。 - -收集 TableName 中所有的 PartitionNameList 中分区的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableName PARTITION PartitionNameList [WITH NUM BUCKETS]; -``` - -收集 TableName 中所有的 PartitionNameList 中分区的索引列统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE TABLE TableName PARTITION PartitionNameList [IndexNameList] [WITH NUM BUCKETS]; -``` - -#### 增量收集 - -对于类似时间列这样的单调不减列，在进行全量收集后，可以使用增量收集来单独分析新增的部分，以提高分析的速度。 - -> **注意：** -> -> 1. 目前只有索引提供了增量收集的功能 -> 2. 使用增量收集时，必须保证表上只有插入操作，且应用方需要保证索引列上新插入的值是单调不减的，否则会导致统计信息不准，影响 TiDB 优化器选择合适的执行计划 - -可以通过以下几种语法进行增量收集。 - -增量收集 TableName 中所有的 IndexNameList 中的索引列的统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE INCREMENTAL TABLE TableName INDEX [IndexNameList] [WITH NUM BUCKETS]; -``` - -增量收集 TableName 中所有的 PartitionNameList 中分区的索引列统计信息： - -{{< copyable "sql" >}} - -```sql -ANALYZE INCREMENTAL TABLE TableName PARTITION PartitionNameList INDEX [IndexNameList] [WITH NUM BUCKETS]; -``` - -### 自动更新 - -在发生增加，删除以及修改语句时，TiDB 会自动更新表的总行数以及修改的行数。这些信息会定期持久化下来， -更新的周期是 20 * `stats-lease`，`stats-lease` 的默认值是 3s，如果将其指定为 0，那么将不会自动更新。 - -和统计信息自动更新相关的三个系统变量如下： - -| 系统变量名 | 默认值 | 功能 | -|---|---|---| -| `tidb_auto_analyze_ratio`| 0.5 | 自动更新阈值 | -| `tidb_auto_analyze_start_time` | `00:00 +0000` | 一天中能够进行自动更新的开始时间 | -| `tidb_auto_analyze_end_time` | `23:59 +0000` | 一天中能够进行自动更新的结束时间 | - -当某个表 `tbl` 的修改行数与总行数的比值大于 `tidb_auto_analyze_ratio`，并且当前时间在 `tidb_auto_analyze_start_time` 和 `tidb_auto_analyze_end_time` 之间时，TiDB 会在后台执行 `ANALYZE TABLE tbl` 语句自动更新这个表的统计信息。 - -在查询语句执行时，TiDB 会以 `feedback-probability` 的概率收集反馈信息，并将其用于更新直方图和 Count-Min Sketch。`feedback-probability` 可通过配置文件修改，其默认值是 `0.0`。 - -### 控制 ANALYZE 并发度 - -执行 ANALYZE 语句的时候，你可以通过一些参数来调整并发度，以控制对系统的影响。 - -#### tidb_build_stats_concurrency - -目前 ANALYZE 执行的时候会被切分成一个个小的任务，每个任务只负责某一个列或者索引。`tidb_build_stats_concurrency` 可以控制同时执行的任务的数量，其默认值是 4。 - -#### tidb_distsql_scan_concurrency - -在执行分析普通列任务的时候，`tidb_distsql_scan_concurrency` 可以用于控制一次读取的 Region 数量，其默认值是 15。 - -#### tidb_index_serial_scan_concurrency - -在执行分析索引列任务的时候，`tidb_index_serial_scan_concurrency` 可以用于控制一次读取的 Region 数量，其默认值是 1。 - -### 查看 ANALYZE 状态 - -在执行 `ANALYZE` 时，可以通过 SQL 语句来查看当前 `ANALYZE` 的状态。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW ANALYZE STATUS [ShowLikeOrWhere]; -``` - -该语句会输出 `ANALYZE` 的状态，可以通过使用 `ShowLikeOrWhere` 来筛选需要的信息。 - -目前 `SHOW ANALYZE STATUS` 会输出 7 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| table_schema | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| job_info | 任务具体信息。如果分析索引则会包含索引名 | -| row_count | 已经分析的行数 | -| start_time | 任务开始执行的时间 | -| state | 任务状态，包括 pending（等待）、running（正在执行）、finished（执行成功）和 failed（执行失败）| - -## 统计信息的查看 - -你可以通过一些语句来查看统计信息的状态。 - -### 表的元信息 - -你可以通过 `SHOW STATS_META` 来查看表的总行数以及修改的行数等信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_META [ShowLikeOrWhere]; -``` - -该语句会输出所有表的总行数以及修改行数等信息，你可以通过 ShowLikeOrWhere 来筛选需要的信息。 - -目前 `SHOW STATS_META` 会输出 6 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| update_time | 更新时间 | -| modify_count | 修改的行数 | -| row_count | 总行数 | - -> **注意：** -> -> 在 TiDB 根据 DML 语句自动更新总行数以及修改的行数时，`update_time` 也会被更新，因此并不能认为 `update_time` 是最近一次发生 Analyze 的时间。 - -### 表的健康度信息 - -通过 `SHOW STATS_HEALTHY` 可以查看表的统计信息健康度，并粗略估计表上统计信息的准确度。当 `modify_count` >= `row_count` 时，健康度为 0；当 `modify_count` < `row_count` 时，健康度为 (1 - `modify_count`/`row_count`) * 100。 - -通过以下命令来查看表的统计信息健康度，你可以通过 `ShowLikeOrWhere` 来筛选需要的信息： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_HEALTHY [ShowLikeOrWhere]; -``` - -目前，`SHOW STATS_HEALTHY` 会输出 4 列，具体如下： - -| 语法元素 | 说明 | -| :-------- | :------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name| 分区名 | -| healthy | 健康度 | - -### 列的元信息 - -你可以通过 `SHOW STATS_HISTOGRAMS` 来查看列的不同值数量以及 NULL 数量等信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_HISTOGRAMS [ShowLikeOrWhere]; -``` - -该语句会输出所有列的不同值数量以及 NULL 数量等信息，你可以通过 ShowLikeOrWhere 来筛选需要的信息。 - -目前 `SHOW STATS_HISTOGRAMS` 会输出 8 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name | 分区名 | -| column_name | 根据 is_index 来变化：is_index 为 0 时是列名，为 1 时是索引名 | -| is_index | 是否是索引列 | -| update_time | 更新时间 | -| distinct_count | 不同值数量 | -| null_count | NULL 的数量 | -| avg_col_size | 列平均长度 | - -### 直方图桶的信息 - -你可以通过 `SHOW STATS_BUCKETS` 来查看直方图每个桶的信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -SHOW STATS_BUCKETS [ShowLikeOrWhere]; -``` - -该语句会输出所有桶的信息，你可以通过 ShowLikeOrWhere 来筛选需要的信息。 - -目前 `SHOW STATS_BUCKETS` 会输出 10 列，具体如下： - -| 语法元素 | 说明 | -| -------- | ------------- | -| db_name | 数据库名 | -| table_name | 表名 | -| partition_name | 分区名 | -| column_name | 根据 is_index 来变化：is_index 为 0 时是列名，为 1 时是索引名 | -| is_index | 是否是索引列 | -| bucket_id | 桶的编号 | -| count | 所有落在这个桶及之前桶中值的数量 | -| repeats | 最大值出现的次数 | -| lower_bound | 最小值 | -| upper_bound | 最大值 | - -## 删除统计信息 - -可以通过执行 `DROP STATS` 语句来删除统计信息。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -DROP STATS TableName; -``` - -该语句会删除 TableName 中所有的统计信息。 - -## 统计信息的导入导出 - -### 导出统计信息 - -统计信息的导出接口如下。 - -通过以下接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 的 json 格式的统计信息： - -{{< copyable "" >}} - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name} -``` - -通过以下接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 在指定时间上的 json 格式统计信息。指定的时间应在 GC SafePoint 之后。 - -{{< copyable "" >}} - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name}/${yyyyMMddHHmmss} -``` - -通过以下接口可以获取数据库 `${db_name}` 中的表 `${table_name}` 在指定时间上的 json 格式统计信息。指定的时间应在 GC SafePoint 之后。 - -{{< copyable "" >}} - -``` -http://${tidb-server-ip}:${tidb-server-status-port}/stats/dump/${db_name}/${table_name}/${yyyy-MM-dd HH:mm:ss} -``` - -### 导入统计信息 - -导入的统计信息一般是通过统计信息导出接口得到的 json 文件。 - -语法如下： - -{{< copyable "sql" >}} - -```sql -LOAD STATS 'file_name'; -``` - -`file_name` 为要导入的统计信息的文件名。 diff --git a/v3.1/reference/performance/tune-tikv.md b/v3.1/reference/performance/tune-tikv.md deleted file mode 100644 index c83b2544e103..000000000000 --- a/v3.1/reference/performance/tune-tikv.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: TiKV 性能参数调优 -category: reference ---- - -# TiKV 性能参数调优 - -本文档用于描述如何根据机器配置情况来调整 TiKV 的参数，使 TiKV 的性能达到最优。 - -TiKV 最底层使用的是 RocksDB 做为持久化存储，所以 TiKV 的很多性能相关的参数都是与 RocksDB 相关的。TiKV 使用了两个 RocksDB 实例，默认 RocksDB 实例存储 KV 数据，Raft RocksDB 实例（简称 RaftDB）存储 Raft 数据。 - -TiKV 使用了 RocksDB 的 `Column Families` (CF) 特性。 - -- 默认 RocksDB 实例将 KV 数据存储在内部的 `default`、`write` 和 `lock` 3 个 CF 内。 - - - `default` CF 存储的是真正的数据，与其对应的参数位于 `[rocksdb.defaultcf]` 项中； - - `write` CF 存储的是数据的版本信息 (MVCC) 以及索引相关的数据，相关的参数位于 `[rocksdb.writecf]` 项中； - - `lock` CF 存储的是锁信息，系统使用默认参数。 - -- Raft RocksDB 实例存储 Raft log。 - - - `default` CF 主要存储的是 Raft log，与其对应的参数位于 `[raftdb.defaultcf]` 项中。 - -所有的 CF 默认共同使用一个 block cache 实例。通过在 `[storage.block-cache]` 下设置 `capacity` 参数，你可以配置该 block cache 的大小。block cache 越大，能够缓存的热点数据越多，读取数据越容易，同时占用的系统内存也越多。如果要为每个 CF 使用单独的 block cache 实例，需要在 `[storage.block-cache]` 下设置 `shared=false`，并为每个 CF 配置单独的 block cache 大小。例如，可以在 `[rocksdb.writecf]` 下设置 `block-cache-size` 参数来配置 `write` CF 的大小。 - -> **注意：** -> -> 在 TiKV 3.0 之前的版本中，不支持使用 `shared block cache`，需要为每个 CF 单独配置 block cache。 - -每个 CF 有各自的 `write-buffer`，大小通过 `write-buffer-size` 控制。 - -## 参数说明 - -```toml -# 日志级别，可选值为：trace，debug，info，warn，error，off -log-level = "info" - -[server] -# 监听地址 -# addr = "127.0.0.1:20160" - -# gRPC 线程池大小 -# grpc-concurrency = 4 -# TiKV 每个实例之间的 gRPC 连接数 -# grpc-raft-conn-num = 10 - -# TiDB 过来的大部分读请求都会发送到 TiKV 的 Coprocessor 进行处理，该参数用于设置 -# coprocessor 线程的个数，如果业务是读请求比较多，增加 coprocessor 的线程数，但应比系统的 -# CPU 核数小。例如：TiKV 所在的机器有 32 core，在重读的场景下甚至可以将该参数设置为 30。在没有 -# 设置该参数的情况下，TiKV 会自动将该值设置为 CPU 总核数乘以 0.8。 -# end-point-concurrency = 8 - -# 可以给 TiKV 实例打标签，用于副本的调度 -# labels = {zone = "cn-east-1", host = "118", disk = "ssd"} - -[storage] -# 数据目录 -# data-dir = "/tmp/tikv/store" - -# 通常情况下使用默认值就可以了。在导数据的情况下建议将该参数设置为 1024000。 -# scheduler-concurrency = 102400 -# 该参数控制写入线程的个数，当写入操作比较频繁的时候，需要把该参数调大。使用 top -H -p tikv-pid -# 发现名称为 sched-worker-pool 的线程都特别忙，这个时候就需要将 scheduler-worker-pool-size -# 参数调大，增加写线程的个数。 -# scheduler-worker-pool-size = 4 - -[storage.block-cache] -## 是否为 RocksDB 的所有 CF 都创建一个 `shared block cache`。 -## -## RocksDB 使用 block cache 来缓存未压缩的数据块。较大的 block cache 可以加快读取速度。 -## 推荐开启 `shared block cache` 参数。这样只需要设置全部缓存大小，使配置过程更加方便。 -## 在大多数情况下，可以通过 LRU 算法在各 CF 间自动平衡缓存用量。 -## -## `storage.block-cache` 会话中的其余配置仅在开启 `shared block cache` 时起作用。 -# shared = true -## `shared block cache` 的大小。正常情况下应设置为系统全部内存的 30%-50%。 -## 如果未设置该参数，则由以下字段或其默认值的总和决定。 -## -## * rocksdb.defaultcf.block-cache-size 或系统全部内存的 25% -## * rocksdb.writecf.block-cache-size 或系统全部内存的 15% -## * rocksdb.lockcf.block-cache-size 或系统全部内存的 2% -## * raftdb.defaultcf.block-cache-size 或系统全部内存的 2% -## -## 要在单个物理机上部署多个 TiKV 节点，需要显式配置该参数。 -## 否则，TiKV 中可能会出现 OOM 错误。 -# capacity = "1GB" - -[pd] -# pd 的地址 -# endpoints = ["127.0.0.1:2379","127.0.0.2:2379","127.0.0.3:2379"] - -[metric] -# 将 metrics 推送给 Prometheus pushgateway 的时间间隔 -interval = "15s" -# Prometheus pushgateway 的地址 -address = "" -job = "tikv" - -[raftstore] -# 默认为 true，表示强制将数据刷到磁盘上。如果是非金融安全级别的业务场景，建议设置成 false， -# 以便获得更高的性能。 -sync-log = true - -# Raft RocksDB 目录。默认值是 [storage.data-dir] 的 raft 子目录。 -# 如果机器上有多块磁盘，可以将 Raft RocksDB 的数据放在不同的盘上，提高 TiKV 的性能。 -# raftdb-dir = "/tmp/tikv/store/raft" - -region-max-size = "384MB" -# Region 分裂阈值 -region-split-size = "256MB" -# 当 Region 写入的数据量超过该阈值的时候，TiKV 会检查该 Region 是否需要分裂。为了减少检查过程 -# 中扫描数据的成本，数据过程中可以将该值设置为32MB，正常运行状态下使用默认值即可。 -region-split-check-diff = "32MB" - -[rocksdb] -# RocksDB 进行后台任务的最大线程数，后台任务包括 compaction 和 flush。具体 RocksDB 为什么需要进行 compaction， -# 请参考 RocksDB 的相关资料。在写流量比较大的时候（例如导数据），建议开启更多的线程， -# 但应小于 CPU 的核数。例如在导数据的时候，32 核 CPU 的机器，可以设置成 28。 -# max-background-jobs = 8 - -# RocksDB 能够打开的最大文件句柄数。 -# max-open-files = 40960 - -# RocksDB MANIFEST 文件的大小限制.
# 更详细的信息请参考：https://github.com/facebook/rocksdb/wiki/MANIFEST -max-manifest-file-size = "20MB" - -# RocksDB write-ahead logs 目录。如果机器上有两块盘，可以将 RocksDB 的数据和 WAL 日志放在 -# 不同的盘上，提高 TiKV 的性能。 -# wal-dir = "/tmp/tikv/store" - -# 下面两个参数用于怎样处理 RocksDB 归档 WAL。 -# 更多详细信息请参考：https://github.com/facebook/rocksdb/wiki/How-to-persist-in-memory-RocksDB-database%3F -# wal-ttl-seconds = 0 -# wal-size-limit = 0 - -# RocksDB WAL 日志的最大总大小，通常情况下使用默认值就可以了。 -# max-total-wal-size = "4GB" - -# 可以通过该参数打开或者关闭 RocksDB 的统计信息。 -# enable-statistics = true - -# 开启 RocksDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。 -# compaction-readahead-size = "2MB" - -[rocksdb.defaultcf] -# 数据块大小。RocksDB 是按照 block 为单元对数据进行压缩的，同时 block 也是缓存在 block-cache -# 中的最小单元（类似其他数据库的 page 概念）。 -block-size = "64KB" - -# RocksDB 每一层数据的压缩方式，可选的值为：no,snappy,zlib,bzip2,lz4,lz4hc,zstd。 -# no:no:lz4:lz4:lz4:zstd:zstd 表示 level0 和 level1 不压缩，level2 到 level4 采用 lz4 压缩算法, -# level5 和 level6 采用 zstd 压缩算法,。 -# no 表示没有压缩，lz4 是速度和压缩比较为中庸的压缩算法，zlib 的压缩比很高，对存储空间比较友 -# 好，但是压缩速度比较慢，压缩的时候需要占用较多的 CPU 资源。不同的机器需要根据 CPU 以及 I/O 资 -# 源情况来配置怎样的压缩方式。例如：如果采用的压缩方式为"no:no:lz4:lz4:lz4:zstd:zstd"，在大量 -# 写入数据的情况下（导数据），发现系统的 I/O 压力很大（使用 iostat 发现 %util 持续 100% 或者使 -# 用 top 命令发现 iowait 特别多），而 CPU 的资源还比较充裕，这个时候可以考虑将 level0 和 -# level1 开启压缩，用 CPU 资源换取 I/O 资源。如果采用的压缩方式 -# 为"no:no:lz4:lz4:lz4:zstd:zstd"，在大量写入数据的情况下，发现系统的 I/O 压力不大，但是 CPU -# 资源已经吃光了，top -H 发现有大量的 bg 开头的线程（RocksDB 的 compaction 线程）在运行，这 -# 个时候可以考虑用 I/O 资源换取 CPU 资源，将压缩方式改成"no:no:no:lz4:lz4:zstd:zstd"。总之，目 -# 的是为了最大限度地利用系统的现有资源，使 TiKV 的性能在现有的资源情况下充分发挥。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# RocksDB memtable 的大小。 -write-buffer-size = "128MB" - -# 最多允许几个 memtable 存在。写入到 RocksDB 的数据首先会记录到 WAL 日志里面，然后会插入到 -# memtable 里面，当 memtable 的大小到达了 write-buffer-size 限定的大小的时候，当前的 -# memtable 会变成只读的，然后生成一个新的 memtable 接收新的写入。只读的 memtable 会被 -# RocksDB 的 flush 线程（max-background-flushes 参数能够控制 flush 线程的最大个数） -# flush 到磁盘，成为 level0 的一个 sst 文件。当 flush 线程忙不过来，导致等待 flush 到磁盘的 -# memtable 的数量到达 max-write-buffer-number 限定的个数的时候，RocksDB 会将新的写入 -# stall 住，stall 是 RocksDB 的一种流控机制。在导数据的时候可以将 max-write-buffer-number -# 的值设置的更大一点，例如 10。 -max-write-buffer-number = 5 - -# 当 level0 的 sst 文件个数到达 level0-slowdown-writes-trigger 指定的限度的时候， -# RocksDB 会尝试减慢写入的速度。因为 level0 的 sst 太多会导致 RocksDB 的读放大上升。 -# level0-slowdown-writes-trigger 和 level0-stop-writes-trigger 是 RocksDB 进行流控的 -# 另一个表现。当 level0 的 sst 的文件个数到达 4（默认值），level0 的 sst 文件会和 level1 中 -# 有 overlap 的 sst 文件进行 compaction，缓解读放大的问题。 -level0-slowdown-writes-trigger = 20 - -# 当 level0 的 sst 文件个数到达 level0-stop-writes-trigger 指定的限度的时候，RocksDB 会 -# stall 住新的写入。 -level0-stop-writes-trigger = 36 - -# 当 level1 的数据量大小达到 max-bytes-for-level-base 限定的值的时候，会触发 level1 的 -# sst 和 level2 种有 overlap 的 sst 进行 compaction。 -# 黄金定律：max-bytes-for-level-base 的设置的第一参考原则就是保证和 level0 的数据量大致相 -# 等，这样能够减少不必要的 compaction。例如压缩方式为"no:no:lz4:lz4:lz4:lz4:lz4"，那么 -# max-bytes-for-level-base 的值应该是 write-buffer-size 的大小乘以 4，因为 level0 和 -# level1 都没有压缩，而且 level0 触发 compaction 的条件是 sst 的个数到达 4（默认值）。在 -# level0 和 level1 都采取了压缩的情况下，就需要分析下 RocksDB 的日志，看一个 memtable 的压 -# 缩成一个 sst 文件的大小大概是多少，例如 32MB，那么 max-bytes-for-level-base 的建议值就应 -# 该是 32MB * 4 = 128MB。 -max-bytes-for-level-base = "512MB" - -# sst 文件的大小。level0 的 sst 文件的大小受 write-buffer-size 和 level0 采用的压缩算法的 -# 影响，target-file-size-base 参数用于控制 level1-level6 单个 sst 文件的大小。 -target-file-size-base = "32MB" - -[rocksdb.writecf] -# 保持和 rocksdb.defaultcf.compression-per-level 一致。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# 保持和 rocksdb.defaultcf.write-buffer-size 一致。 -write-buffer-size = "128MB" -max-write-buffer-number = 5 -min-write-buffer-number-to-merge = 1 - -# 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。 -max-bytes-for-level-base = "512MB" -target-file-size-base = "32MB" - -[raftdb] -# RaftDB 能够打开的最大文件句柄数。 -# max-open-files = 40960 - -# 可以通过该参数打开或者关闭 RaftDB 的统计信息。 -# enable-statistics = true - -# 开启 RaftDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。 -# compaction-readahead-size = "2MB" - -[raftdb.defaultcf] -# 保持和 rocksdb.defaultcf.compression-per-level 一致。 -compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] - -# 保持和 rocksdb.defaultcf.write-buffer-size 一致。 -write-buffer-size = "128MB" -max-write-buffer-number = 5 -min-write-buffer-number-to-merge = 1 - -# 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。 -max-bytes-for-level-base = "512MB" -target-file-size-base = "32MB" -``` - -## TiKV 内存使用情况 - -除了以上列出的 `block-cache` 以及 `write-buffer` 会占用系统内存外： - -1. 需预留一些内存作为系统的 page cache -2. TiKV 在处理大的查询的时候（例如 `select * from ...`）会读取数据然后在内存中生成对应的数据结构返回给 TiDB，这个过程中 TiKV 会占用一部分内存 - -## TiKV 机器配置推荐 - -1. 生产环境中，不建议将 TiKV 部署在 CPU 核数小于 8 或内存低于 32GB 的机器上 -2. 如果对写入吞吐要求比较高，建议使用吞吐能力比较好的磁盘 -3. 如果对读写的延迟要求非常高，建议使用 IOPS 比较高的 SSD 盘 diff --git a/v3.1/reference/performance/understanding-the-query-execution-plan.md b/v3.1/reference/performance/understanding-the-query-execution-plan.md deleted file mode 100644 index 70035dc14edc..000000000000 --- a/v3.1/reference/performance/understanding-the-query-execution-plan.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: 理解 TiDB 执行计划 -category: reference ---- - -# 理解 TiDB 执行计划 - -TiDB 优化器会根据当前数据表的实际情况来选择最优的执行计划，执行计划由一系列的算子构成。本文将详细解释 TiDB 中 `EXPLAIN` 语句返回的执行计划信息。 - -## 使用 `EXPLAIN` 来优化 SQL 语句 - -`EXPLAIN` 语句的返回结果提供了 TiDB 执行 SQL 查询的详细信息： - -- `EXPLAIN` 可以和 `SELECT`，`DELETE` 语句一起使用； -- 执行 `EXPLAIN`，TiDB 会返回被 `EXPLAIN` 的 SQL 语句经过优化器后的最终物理执行计划。也就是说，`EXPLAIN` 展示了 TiDB 执行该 SQL 语句的完整信息，比如以什么样的顺序，什么方式 JOIN 两个表，表达式树长什么样等等。详见 [`EXPLAIN` 输出格式](#explain-输出格式)； -- TiDB 支持 `EXPLAIN [options] FOR CONNECTION connection_id`，但与 MySQL 的 `EXPLAIN FOR` 有一些区别，请参见 [`EXPLAIN FOR CONNECTION`](#explain-for-connection)。 - -通过观察 `EXPLAIN` 的结果，你可以知道如何给数据表添加索引使得执行计划使用索引从而加速 SQL 语句的执行速度；你也可以使用 `EXPLAIN` 来检查优化器是否选择了最优的顺序来 JOIN 数据表。 - -## `EXPLAIN` 输出格式 - -目前 TiDB 的 `EXPLAIN` 会输出 4 列，分别是：id，count，task，operator info。执行计划中每个算子都由这 4 列属性来描述，`EXPLAIN` 结果中每一行描述一个算子。每个属性的具体含义如下： - -| 属性名 | 含义 | -|:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------| -| id | 算子的 ID，在整个执行计划中唯一的标识一个算子。在 TiDB 2.1 中，id 会格式化显示算子的树状结构。数据从 child 流向 parent，每个 算子的 parent 有且仅有一个。 | -| count | 预计当前算子将会输出的数据条数，基于统计信息以及算子的执行逻辑估算而来。 | -| task | 当前这个算子属于什么 task。目前的执行计划分成为两种 task，一种叫 **root** task，在 tidb-server 上执行，一种叫 **cop** task，并行的在 TiKV 上执行。当前的执行计划在 task 级别的拓扑关系是一个 root task 后面可以跟许多 cop task，root task 使用 cop task 的输出结果作为输入。cop task 中执行的也即是 TiDB 下推到 TiKV 上的任务，每个 cop task 分散在 TiKV 集群中，由多个进程共同执行。 | -| operator info | 每个算子的详细信息。各个算子的 operator info 各有不同，详见 [Operator Info](#operator-info)。 | - -## `EXPLAIN ANALYZE` 输出格式 - -作为 `EXPLAIN` 语句的扩展，`EXPLAIN ANALYZE` 语句执行查询并在 `execution info` 列中提供额外的执行统计信息。具体如下： - -* `time` 显示从进入算子到离开算子的全部 wall time，包括所有子算子操作的全部执行时间。如果该算子被父算子多次调用 (`loops`)，这个时间就是累积的时间。 -* `loops` 是当前算子被父算子调用的次数。 -* `rows` 是当前算子返回的行的总数。例如，可以将 `count` 列的精度和 `execution_info` 列中的 `rows`/`loops` 值进行对比，据此评定查询优化器估算的精确度。 - -### 用例 - -使用 [bikeshare example database](https://github.com/pingcap/docs/blob/master/dev/how-to/get-started/import-example-database.md): - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'; -``` - -``` -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -| id | count | task | operator info | -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -| StreamAgg_20 | 1.00 | root | funcs:count(col_0) | -| └─TableReader_21 | 1.00 | root | data:StreamAgg_9 | -| └─StreamAgg_9 | 1.00 | cop | funcs:count(1) | -| └─Selection_19 | 8166.73 | cop | ge(bikeshare.trips.start_date, 2017-07-01 00:00:00.000000), le(bikeshare.trips.start_date, 2017-07-01 23:59:59.000000) | -| └─TableScan_18 | 19117643.00 | cop | table:trips, range:[-inf,+inf], keep order:false | -+--------------------------+-------------+------+------------------------------------------------------------------------------------------------------------------------+ -5 rows in set (0.00 sec) -``` - -在上面的例子中，coprocessor 上读取 `trips` 表上的数据（`TableScan_18`），寻找满足 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 条件的数据（`Selection_19`），然后计算满足条件的数据行数（`StreamAgg_9`），最后把结果返回给 TiDB。TiDB 汇总各个 coprocessor 返回的结果（`TableReader_21`），并进一步计算所有数据的行数（`StreamAgg_20`），最终把结果返回给客户端。在上面这个查询中，TiDB 根据 `trips` 表的统计信息估算出 `TableScan_18` 的输出结果行数为 19117643.00，满足条件 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 的有 `8166.73` 条，经过聚合运算后，只有 1 条结果。 - -上述查询中，虽然大部分计算逻辑都下推到了 TiKV 的 coprocessor 上，但是其执行效率还是不够高，可以添加适当的索引来消除 `TableScan_18` 对 `trips` 的全表扫，进一步加速查询的执行： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE trips ADD INDEX (start_date); -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT count(*) FROM trips WHERE start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'; -``` - -``` -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -| id | count | task | operator info | -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -| StreamAgg_25 | 1.00 | root | funcs:count(col_0) | -| └─IndexReader_26 | 1.00 | root | index:StreamAgg_9 | -| └─StreamAgg_9 | 1.00 | cop | funcs:count(1) | -| └─IndexScan_24 | 8166.73 | cop | table:trips, index:start_date, range:[2017-07-01 00:00:00,2017-07-01 23:59:59], keep order:false | -+------------------------+---------+------+--------------------------------------------------------------------------------------------------+ -4 rows in set (0.01 sec) -``` - -在添加完索引后的新执行计划中，使用 `IndexScan_24` 直接读取满足条件 `start_date BETWEEN '2017-07-01 00:00:00' AND '2017-07-01 23:59:59'` 的数据，可以看到，估算的要扫描的数据行数从之前的 `19117643.00` 降到了现在的 `8166.73`。在测试环境中显示，这个查询的执行时间从 50.41 秒降到了 0.01 秒！ - -## `EXPLAIN FOR CONNECTION` - -`EXPLAIN FOR CONNECTION` 用于获得一个连接中最后执行的查询的执行计划，其输出格式与 `EXPLAIN` 完全一致。但 TiDB 中的实现与 MySQL 不同，除了输出格式之外，还有以下区别： - -- MySQL 返回的是**正在执行**的查询计划，而 TiDB 返回的是**最后执行**的查询计划。 -- MySQL 的文档中指出，MySQL 要求登录用户与被查询的连接相同，或者拥有 `PROCESS` 权限，而 TiDB 则要求登录用户与被查询的连接相同，或者拥有 `SUPER` 权限。 - -## 概述 - -### Task 简介 - -目前 TiDB 的计算任务隶属于两种不同的 task：cop task 和 root task。cop task 是指使用 TiKV 中的 coprocessor 执行的计算任务，root task 是指在 TiDB 中执行的计算任务。 - -SQL 优化的目标之一是将计算尽可能地下推到 TiKV 中执行。TiKV 中的 coprocessor 能支持大部分 SQL 内建函数（包括聚合函数和标量函数）、SQL `LIMIT` 操作、索引扫描和表扫描。但是，所有的 Join 操作都只能作为 root task 在 TiDB 上执行。 - -### 表数据和索引数据 - -TiDB 的表数据是指一张表的原始数据，存放在 TiKV 中。对于每行表数据，它的 key 是一个 64 位整数，称为 Handle ID。如果一张表存在 int 类型的主键，TiDB 会把主键的值当作表数据的 Handle ID，否则由系统自动生成 Handle ID。表数据的 value 由这一行的所有数据编码而成。在读取表数据的时候，可以按照 Handle ID 递增的顺序返回。 - -TiDB 的索引数据和表数据一样，也存放在 TiKV 中。它的 key 是由索引列编码的有序 bytes，value 是这一行索引数据对应的 Handle ID，通过 Handle ID 可以读取这一行的非索引列。在读取索引数据的时候，TiKV 会按照索引列递增的顺序返回，如果有多个索引列，首先保证第 1 列递增，并且在第 i 列相等的情况下，保证第 i + 1 列递增。 - -### 范围查询 - -在 WHERE/HAVING/ON 条件中，TiDB 优化器会分析主键或索引键的查询返回。如数字、日期类型的比较符，如大于、小于、等于以及大于等于、小于等于，字符类型的 LIKE 符号等。 - -值得注意的是，TiDB 目前只支持比较符一端是列，另一端是常量，或可以计算成某一常量的情况，类似 `year(birth_day) < 1992` 的查询条件是不能利用索引的。还要注意应尽可能使用同一类型进行比较，以避免引入额外的 cast 操作而导致不能利用索引，如 `user_id = 123456`，如果 `user_id` 是字符串，需要将 `123456` 也写成字符串常量的形式。 - -针对同一列的范围查询条件使用 `AND` 和 `OR` 组合后，等于对范围求交集或者并集。对于多维组合索引，可以写多个列的条件。例如对组合索引`(a, b, c)`，当 a 为等值查询时，可以继续求 b 的查询范围，当 b 也为等值查询时，可以继续求 c 的查询范围，反之如果 a 为非等值查询，则只能求 a 的范围。 - -## Operator Info - -### TableReader 和 TableScan - -TableScan 表示在 KV 端对表数据进行扫描，TableReader 表示在 TiDB 端从 TiKV 端读取，属于同一功能的两个算子。table 表示 SQL 语句中的表名，如果表名被重命名，则显示重命名。range 表示扫描的数据范围，如果在查询中不指定 WHERE/HAVING/ON 条件，则会选择全表扫描，如果在 int 类型的主键上有范围查询条件，会选择范围查询。keep order 表示 table scan 是否按顺序返回。 - -### IndexReader 和 IndexLookUp - -Index 在 TiDB 端的读取方式有两种：IndexReader 表示直接从索引中读取索引列，适用于 SQL 语句中仅引用了该索引相关的列或主键；IndexLookUp 表示从索引中过滤部分数据，仅返回这些数据的 Handle ID，通过 Handle ID 再次查找表数据，这种方式需要两次从 TiKV 获取数据。Index 的读取方式是由优化器自动选择的。 - -IndexScan 是 KV 端读取索引数据的算子，和 TableScan 功能类似。table 表示 SQL 语句中的表名，如果表名被重命名，则显示重命名。index 表示索引名。range 表示扫描的数据范围。out of order 表示 index scan 是否按照顺序返回。注意在 TiDB 中，多列或者非 int 列构成的主键是当作唯一索引处理的。 - -### Selection - -Selection 表示 SQL 语句中的选择条件，通常出现在 WHERE/HAVING/ON 子句中。 - -### Projection - -Projection 对应 SQL 语句中的 SELECT 列表，功能是将每一条输入数据映射成新的输出数据。 - -### Aggregation - -Aggregation 对应 SQL 语句中的 Group By 语句或者没有 Group By 语句但是存在聚合函数，例如 count 或 sum 函数等。TiDB 支持两种聚合算法：Hash Aggregation 以及 Stream Aggregation（待补充）。Hash Aggregation 是基于哈希的聚合算法，如果 Hash Aggregation 紧邻 Table 或者 Index 的读取算子，则聚合算子会在 TiKV 端进行预聚合，以提高计算的并行度和减少网络开销。 - -### Join - -TiDB 支持 Inner Join 以及 Left/Right Outer Join，并会自动将可以化简的外连接转换为 Inner Join。 - -TiDB 支持三种 Join 算法：Hash Join，Sort Merge Join 和 Index Look up Join。Hash Join 的原理是将参与连接的小表预先装载到内存中，读取大表的所有数据进行连接。Sort Merge Join 会利用输入数据的有序信息，同时读取两张表的数据并依次进行比较。Index Look Up Join 会读取外表的数据，并对内表进行主键或索引键查询。 - -### Apply - -Apply 是 TiDB 用来描述子查询的一种算子，行为类似于 Nested Loop，即每次从外表中取一条数据，带入到内表的关联列中，并执行，最后根据 Apply 内联的 Join 算法进行连接计算。 - -值得注意的是，Apply 一般会被查询优化器自动转换为 Join 操作。用户在编写 SQL 的过程中应尽量避免 Apply 算子的出现。 diff --git a/v3.1/reference/security/cert-based-authentication.md b/v3.1/reference/security/cert-based-authentication.md deleted file mode 100644 index 268e33b06087..000000000000 --- a/v3.1/reference/security/cert-based-authentication.md +++ /dev/null @@ -1,483 +0,0 @@ ---- -title: TiDB 证书鉴权使用指南 -summary: 了解使用 TiDB 的证书鉴权功能。 -category: reference ---- - -# TiDB 证书鉴权使用指南 从 v3.0.8 版本开始引入 - -从 TiDB 3.0.8 版本开始，TiDB 支持基于证书鉴权的登录方式。采用这种方式，TiDB 对不同用户签发证书，使用加密连接来传输数据，并在用户登录时验证证书。相比 MySQL 用户常用的用户名密码验证方式，与 MySQL 相兼容的证书鉴权方式更安全，因此越来越多的用户使用证书鉴权来代替用户名密码验证。 - -在 TiDB 上使用证书鉴权的登录方法，可能需要进行以下操作： - -+ 创建安全密钥和证书 -+ 配置 TiDB 和客户端使用的证书 -+ 配置登陆时需要校验的用户证书信息 -+ 更新和替换证书 - -本文介绍了如何进行证书鉴权的上述几个操作。 - -## 创建安全密钥和证书 - -### 安装 OpenSSL - -目前推荐使用 [OpenSSL](https://www.openssl.org/) 来生成密钥和证书。以 Debian 操作系统为例，先执行以下命令来安装 OpenSSL： - -{{< copyable "shell-regular" >}} - -```bash -sudo apt-get install openssl -``` - -### 生成 CA 密钥和证书 - -1. 执行以下命令生成 CA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl genrsa 2048 > ca-key.pem - ``` - - 命令执行后输出以下结果： - - {{< copyable "shell-regular" >}} - - ```bash - Generating RSA private key, 2048 bit long modulus (2 primes) - ....................+++++ - ...............................................+++++ - e is 65537 (0x010001) - ``` - -2. 执行以下命令生成该密钥对应的证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.pem - ``` - -3. 输入证书细节信息，示例如下： - - {{< copyable "shell-regular" >}} - - ```bash - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:San Francisco - Organization Name (eg, company) [Internet Widgits Pty Ltd]:PingCAP Inc. - Organizational Unit Name (eg, section) []:TiDB - Common Name (e.g. server FQDN or YOUR name) []:TiDB admin - Email Address []:s@pingcap.com - ``` - - > **注意：** - > - > 以上信息中，`:` 后的文字为用户输入的信息。 - -### 生成服务端密钥和证书 - -1. 执行以下命令生成服务端的密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.pem -out server-req.pem - ``` - -2. 输入证书细节信息，示例如下： - - {{< copyable "shell-regular" >}} - - ```bash - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:San Francisco - Organization Name (eg, company) [Internet Widgits Pty Ltd]:PingCAP Inc. - Organizational Unit Name (eg, section) []:TiKV - Common Name (e.g. server FQDN or YOUR name) []:TiKV Test Server - Email Address []:k@pingcap.com - - Please enter the following 'extra' attributes - to be sent with your certificate request - A challenge password []: - An optional company name []: - ``` - -3. 执行以下命令生成服务端的 RSA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl rsa -in server-key.pem -out server-key.pem - ``` - - 输出结果如下： - - ```bash - writing RSA key - ``` - -4. 使用 CA 证书签名来生成服务端的证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in server-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem - ``` - - 输出结果示例如下： - - ```bash - Signature ok - subject=C = US, ST = California, L = San Francisco, O = PingCAP Inc., OU = TiKV, CN = TiKV Test Server, emailAddress = k@pingcap.com - Getting CA Private Key - ``` - - > **注意：** - > - > 以上结果中，用户登陆时 TiDB 将强制检查 `subject` 部分的信息是否一致。 - -### 生成客户端密钥和证书 - -生成服务端密钥和证书后，需要生成客户端使用的密钥和证书。通常需要为不同的用户生成不同的密钥和证书。 - -1. 执行以下命令生成客户端的密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.pem -out client-req.pem - ``` - -2. 输入证书细节信息，示例如下： - - {{< copyable "shell-regular" >}} - - ```bash - Country Name (2 letter code) [AU]:US - State or Province Name (full name) [Some-State]:California - Locality Name (eg, city) []:San Francisco - Organization Name (eg, company) [Internet Widgits Pty Ltd]:PingCAP Inc. - Organizational Unit Name (eg, section) []:TiDB - Common Name (e.g. server FQDN or YOUR name) []:tpch-user1 - Email Address []:zz@pingcap.com - - Please enter the following 'extra' attributes - to be sent with your certificate request - A challenge password []: - An optional company name []: - ``` - -3. 执行以下命令生成客户端 RSA 证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl rsa -in client-key.pem -out client-key.pem - ``` - - 以上命令的输出结果如下： - - ```bash - writing RSA key - ``` - -4. 执行以下命令，使用 CA 证书签名来生成客户端证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in client-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem - ``` - - 输出结果示例如下： - - ```bash - Signature ok - subject=C = US, ST = California, L = San Francisco, O = PingCAP Inc., OU = TiDB, CN = tpch-user1, emailAddress = zz@pingcap.com - Getting CA Private Key - ``` - - > **注意：** - > - > 以上结果中，`subject` 部分后的信息会被用来在 `require` 中配置和要求验证。 - -### 验证证书 - -执行以下命令验证证书： - -{{< copyable "shell-regular" >}} - -```bash -openssl verify -CAfile ca-cert.pem server-cert.pem client-cert.pem -``` - -如果验证通过，会显示以下信息： - -``` -server-cert.pem: OK -client-cert.pem: OK -``` - -## 配置 TiDB 和客户端使用证书 - -在生成证书后，需要在 TiDB 中配置服务端所使用的证书，同时让客户端程序使用客户端证书。 - -### 配置 TiDB 服务端 - -修改 TiDB 配置文件中的 `[security]` 段。这一步指定 CA 证书、服务端密钥和服务端证书存放的路径。可将 `path/to/server-cert.pem`、`path/to/server-key.pem` 和 `path/to/ca-cert.pem` 替换成实际的路径。 - -{{< copyable "" >}} - -``` -[security] -ssl-cert ="path/to/server-cert.pem" -ssl-key ="path/to/server-key.pem" -ssl-ca="path/to/ca-cert.pem" -``` - -启动 TiDB 日志。如果日志中有以下内容，即代表配置生效： - -``` -[INFO] [server.go:264] ["secure connection is enabled"] ["client verification enabled"=true] -``` - -### 配置客户端程序 - -配置客户端程序，让客户端使用客户端密钥和证书来登录 TiDB。 - -以 MySQL 客户端为例，可以通过指定 `ssl-cert`、`ssl-key`、`ssl-ca` 来使用新的 CA 证书、客户端密钥和证书： - -{{< copyable "shell-regular" >}} - -```bash -mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem -``` - -> **注意：** -> -> `/path/to/client-cert.new.pem`、`/path/to/client-key.new.pem` 和 `/path/to/ca-cert.pem` 是 CA 证书、客户端密钥和客户端存放的路径。可将以上命令中的这些部分替换为实际的路径。 - -## 配置登陆时需要校验的用户证书信息 - -使用客户端连接 TiDB 进行授权配置。先获取需要验证的用户证书信息，再对这些信息进行配置。 - -### 获取用户证书信息 - -用户证书信息可由 `require subject`、`require issuer` 和 `require cipher` 来指定，用于检查 X.509 certificate attributes。 - -+ `require subject`：指定用户在连接时需要提供客户端证书的 `subject` 内容。指定该选项后，不需要再配置 `require ssl` 或 x509。配置内容对应[生成客户端密钥和证书](#生成客户端密钥和证书) 中的录入信息。 - - 可以执行以下命令来获取该项的信息： - - {{< copyable "shell-regular" >}} - - ``` - openssl x509 -noout -subject -in client-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//' - ``` - -+ `require issuer`：指定签发用户证书的 CA 证书的 `subject` 内容。配置内容对应[生成 CA 密钥和证书](#生成-ca-密钥和证书) 中的录入信息。 - - 可以执行以下命令来获取该项的信息： - - ``` - openssl x509 -noout -subject -in ca-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//' - ``` - -+ `require cipher`：配置该项检查客户端支持的 cipher method。可以使用以下语句来查看支持的列表： - - {{< copyable "sql" >}} - - ```sql - SHOW SESSION STATUS LIKE 'Ssl_cipher_list'; - ``` - -### 配置用户证书信息 - -获取用户证书信息（`require subject`, `require issuer` 和 `require cipher`）后，可在创建用户、赋予权限或更改用户时配置用户证书信息。将以下命令中的 `` 替换为对应的信息。可以选择配置其中一项或多项，使用空格或 `and` 分隔。 - -+ 可以在创建用户 (`create user`) 时配置登陆时需要校验的证书信息： - - {{< copyable "sql" >}} - - ```sql - create user 'u1'@'%' require issuer '' subject '' cipher ''; - ``` - -+ 可以在赋予权限 (`grant`) 时配置登陆时需要校验的证书信息： - - {{< copyable "sql" >}} - - ```sql - grant all on *.* to 'u1'@'%' require issuer '' subject '' cipher ''; - ``` - -+ 还可以在修改已有用户 (alter user) 时配置登陆时需要校验的证书信息： - - {{< copyable "sql" >}} - - ```sql - alter user 'u1'@'%' require issuer '' subject '' cipher ''; - ``` - -配置完成后，用户在登录时 TiDB 会验证以下内容： - -+ 使用 SSL 登录，且证书为服务器配置的 CA 证书所签发 -+ 证书的 `Issuer` 信息和权限配置里的信息相匹配 -+ 证书的 `Subject` 信息和权限配置里的信息相匹配 - -全部验证通过后用户才能登录，否则会报 `ERROR 1045 (28000): Access denied` 错误。登录后，可以通过以下命令来查看当前链接是否使用证书登录、TLS 版本和 Cipher 算法。 - -连接 MySQL 客户端并执行： - -{{< copyable "sql" >}} - -```sql -\s -``` - -返回结果如下： - -``` --------------- -mysql Ver 15.1 Distrib 10.4.10-MariaDB, for Linux (x86_64) using readline 5.1 - -Connection id: 1 -Current database: test -Current user: root@127.0.0.1 -SSL: Cipher in use is TLS_AES_256_GCM_SHA384 -``` - -然后执行： - -{{< copyable "sql" >}} - -```sql -show variables like '%ssl%'; -``` - -返回结果如下： - -``` -+---------------+----------------------------------+ -| Variable_name | Value | -+---------------+----------------------------------+ -| ssl_cert | /path/to/server-cert.pem | -| ssl_ca | /path/to/ca-cert.pem | -| have_ssl | YES | -| have_openssl | YES | -| ssl_key | /path/to/server-key.pem | -+---------------+----------------------------------+ -6 rows in set (0.067 sec) -``` - -## 更新和替换证书 - -证书和密钥通常会周期性更新。下文介绍更新密钥和证书的流程。 - -CA 证书是客户端和服务端相互校验的依据，所以如果需要替换 CA 证书，则需要生成一个组合证书来在替换期间同时支持客户端和服务器上新旧证书的验证，并优先替换客户端和服务端的 CA 证书，再替换客户端和服务端的密钥和证书。 - -### 更新 CA 密钥和证书 - -1. 以替换 CA 密钥为例（假设 `ca-key.pem` 被盗），将旧的 CA 密钥和证书进行备份： - - {{< copyable "shell-regular" >}} - - ```bash - mv ca-key.pem ca-key.old.pem && \ - mv ca-cert.pem ca-cert.old.pem - ``` - -2. 生成新的 CA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl genrsa 2048 > ca-key.pem - ``` - -3. 用新的密钥生成新的 CA 证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.new.pem - ``` - - > **注意：** - > - > 生成新的 CA 证书是为了替换密钥和证书，保证在线用户不受影响。所以以上命令中填写的附加信息必须与已配置的 `require issuer` 信息一致。 - -4. 生成组合 CA 证书： - - {{< copyable "shell-regular" >}} - - ```bash - cat ca-cert.new.pem ca-cert.old.pem > ca-cert.pem - ``` - -之后使用新生成的组合 CA 证书并重启 TiDB Server，此时服务端可以同时接受和使用新旧 CA 证书。 - -之后先将所有客户端用的 CA 证书也替换为新生成的组合 CA 证书，使客户端能同时和使用新旧 CA 证书。 - -### 更新客户端密钥和证书 - -> **注意：** -> -> 需要将集群中所有服务端和客户端使用的 CA 证书都替换为新生成的组合 CA 证书后才能开始进行以下步骤。 - -1. 生成新的客户端 RSA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.new.pem -out client-req.new.pem && \ - sudo openssl rsa -in client-key.new.pem -out client-key.new.pem - ``` - - > **注意：** - > - > 以上命令是为了替换密钥和证书，保证在线用户不受影响，所以以上命令中填写的附加信息必须与已配置的 `require subject` 信息一致。 - -2. 使用新的组合 CA 证书和新 CA 密钥生成新客户端证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in client-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.new.pem - ``` - -3. 让客户端使用新的客户端密钥和证书来连接 TiDB （以 MySQL 客户端为例）： - - {{< copyable "shell-regular" >}} - - ```bash - mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem - ``` - - > **注意：** - > - > `/path/to/client-cert.new.pem`、`/path/to/client-key.new.pem` 和 `/path/to/ca-cert.pem` 是 CA 证书、客户端密钥和客户端存放的路径。可将以上命令中的这些部分替换为实际的路径。 - -### 更新服务端密钥和证书 - -1. 生成新的服务端 RSA 密钥： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.new.pem -out server-req.new.pem && \ - sudo openssl rsa -in server-key.new.pem -out server-key.new.pem - ``` - -2. 使用新的组合 CA 证书和新 CA 密钥生成新服务端证书： - - {{< copyable "shell-regular" >}} - - ```bash - sudo openssl x509 -req -in server-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.new.pem - ``` - -3. 配置 TiDB 使用上面新生成的服务端密钥和证书并重启。参见[配置 TiDB 服务端](#配置-tidb-服务端)。 diff --git a/v3.1/reference/security/compatibility.md b/v3.1/reference/security/compatibility.md deleted file mode 100644 index 77227fdfb3e8..000000000000 --- a/v3.1/reference/security/compatibility.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 与 MySQL 安全特性差异 -category: reference ---- - -# 与 MySQL 安全特性差异 - -除以下功能外，TiDB 支持与 MySQL 5.7 类似的安全特性。 - -- 仅支持 `mysql_native_password` 身份验证方案。 -- 不支持外部身份验证方式（如 LDAP）。 -- 不支持列级别权限设置。 -- 不支持使用证书验证身份。[#9708](https://github.com/pingcap/tidb/issues/9708) -- 不支持密码过期，最后一次密码变更记录以及密码生存期。[#9709](https://github.com/pingcap/tidb/issues/9709) -- 不支持权限属性 `max_questions`，`max_updated`，`max_connections` 以及 `max_user_connections`。 -- 不支持密码验证。[#9741](https://github.com/pingcap/tidb/issues/9741) -- 不支持透明数据加密（TDE）。 diff --git a/v3.1/reference/security/privilege-system.md b/v3.1/reference/security/privilege-system.md deleted file mode 100644 index bbfa9b76ee36..000000000000 --- a/v3.1/reference/security/privilege-system.md +++ /dev/null @@ -1,481 +0,0 @@ ---- -title: 权限管理 -category: reference ---- - -# 权限管理 - -TiDB 的权限管理系统按照 MySQL 的权限管理进行实现，TiDB 支持大部分的 MySQL 的语法和权限类型。 - -本文档主要介绍 TiDB 权限相关操作、各项操作需要的权限以及权限系统的实现。 - -## 权限相关操作 - -### 授予权限 - -授予 `xxx` 用户对数据库 `test` 的读权限： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO 'xxx'@'%'; -``` - -为 `xxx` 用户授予所有数据库，全部权限： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'xxx'@'%'; -``` - -`GRANT` 为一个不存在的用户授予权限时，默认并不会自动创建用户。该行为受 SQL Mode 中的 `NO_AUTO_CREATE_USER` 控制。 -如果从 SQL Mode 中去掉 `NO_AUTO_CREATE_USER`，当 `GRANT` 的目标用户不存在时，TiDB 会自动创建用户。 - -{{< copyable "sql" >}} - -```sql -mysql> select @@sql_mode; -``` - -```+-------------------------------------------------------------------------------------------------------------------------------------------+ -| @@sql_mode | -+-------------------------------------------------------------------------------------------------------------------------------------------+ -| ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -set @@sql_mode='ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM mysql.user WHERE user='xxxx'; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON test.* TO 'xxxx'@'%' IDENTIFIED BY 'yyyyy'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT user,host FROM mysql.user WHERE user='xxxx'; -``` - -``` -+------|------+ -| user | host | -+------|------+ -| xxxx | % | -+------|------+ -1 row in set (0.00 sec) -``` - -上述示例中，`xxxx@%` 即自动添加的用户。 - -`GRANT` 对于数据库或者表的授权，不检查数据库或表是否存在。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM test.xxxx; -``` - -``` -ERROR 1146 (42S02): Table 'test.xxxx' doesn't exist -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON test.xxxx TO xxxx; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -mysql> SELECT user,host FROM mysql.tables_priv WHERE user='xxxx'; -``` - -``` -+------|------+ -| user | host | -+------|------+ -| xxxx | % | -+------|------+ -1 row in set (0.00 sec) -``` - -`GRANT` 可以模糊匹配地授予数据库和表： - -{{< copyable "sql" >}} - -```sql -mysql> GRANT ALL PRIVILEGES ON `te%`.* TO genius; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT user,host,db FROM mysql.db WHERE user='genius'; -``` - -``` -+--------|------|-----+ -| user | host | db | -+--------|------|-----+ -| genius | % | te% | -+--------|------|-----+ -1 row in set (0.00 sec) -``` - -这个例子中通过 `%` 模糊匹配，所有 `te` 开头的数据库，都被授予了权限。 - -### 收回权限 - -`REVOKE` 语句与 `GRANT` 对应： - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `test`.* FROM 'genius'@'localhost'; -``` - -> **注意：** -> -> `REVOKE` 收回权限时只做精确匹配，若找不到记录则报错。而 `GRANT` 授予权限时可以使用模糊匹配。 - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `te%`.* FROM 'genius'@'%'; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'genius' on host '%' -``` - -关于模糊匹配和转义，字符串和 identifier： - -{{< copyable "sql" >}} - -```sql -mysql> GRANT ALL PRIVILEGES ON `te\%`.* TO 'genius'@'localhost'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -上述例子是精确匹配名为 `te%` 的数据库，注意使用 `\` 转义字符。 - -以单引号包含的部分，是一个字符串。以反引号包含的部分，是一个 identifier。注意下面的区别： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON 'test'.* TO 'genius'@'localhost'; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the -manual that corresponds to your MySQL server version for the right -syntax to use near ''test'.* to 'genius'@'localhost'' at line 1 -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON `test`.* TO 'genius'@'localhost'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -如果想将一些特殊的关键字做为表名，可以用反引号包含起来。比如： - -{{< copyable "sql" >}} - -```sql -mysql> CREATE TABLE `select` (id int); -``` - -``` -Query OK, 0 rows affected (0.27 sec) -``` - -### 查看为用户分配的权限 - -`SHOW GRANTS` 语句可以查看为用户分配了哪些权限。例如： - -查看当前用户的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS; -``` - -查看某个特定用户的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS for 'root'@'%'; -``` - -更精确的方式，可以通过直接查看授权表的数据实现。比如想知道，名为 `test@%` 的用户是否拥有对 `db1.t` 的 `Insert` 权限： - -1. 先查看该用户是否拥有全局 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT Insert_priv FROM mysql.user WHERE user='test' AND host='%'; - ``` - -2. 如果没有，再查看该用户是否拥有 `db1` 数据库级别的 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT Insert_priv FROM mysql.db WHERE user='test' AND host='%'; - ``` - -3. 如果仍然没有，则继续判断是否拥有 `db1.t` 这张表的 `Insert` 权限： - - {{< copyable "sql" >}} - - ```sql - SELECT table_priv FROM mysql.tables_priv WHERE user='test' AND host='%' AND db='db1'; - ``` - -## TiDB 各操作需要的权限 - -TiDB 用户目前拥有的权限可以在 `INFORMATION_SCHEMA.USER_PRIVILEGES` 表中查找到。 - -| 权限类型 | 权限变量名 | 权限简述 | -| :------------ | :------------ | :---------------------- | -| ALL | AllPriv | 所有权限 | -| Drop | DropPriv | 删除 schema/table | -| Index | IndexPriv | 创建/删除 index | -| Alter | AlterPriv | 执行 `ALTER` 语句 | -| Super | SuperPriv | 所有权限 | -| Grant | GrantPriv | 授予其他用户权限 | -| Create | CreatePriv | 创建 schema/table | -| Select | SelectPriv | 读取表内容 | -| Insert | InsertPriv | 插入数据到表 | -| Update | UpdatePriv | 更新表中数据 | -| Delete | DeletePriv | 删除表中数据 | -| Trigger | TriggerPriv | 尚未使用 | -| Process | ProcessPriv | 显示正在运行的任务 | -| Execute | ExecutePriv | 执行 execute 语句 | -| Drop Role | DropRolePriv | 执行 drop role | -| Show View | ShowViewPriv | 执行 show create view | -| References | ReferencesPriv | 尚未使用 | -| Create View | CreateViewPriv | 创建视图 | -| Create User | CreateUserPriv | 创建用户 | -| Create Role | CreateRolePriv | 执行 create role | -| Show Databases | ShowDBPriv | 显示 database 内的表情况 | - -### ALTER - -- 对于所有的 `ALTER` 语句，均需要用户对所操作的表拥有 `ALTER` 权限。 -- 除 `ALTER...DROP` 和 `ALTER...RENAME TO` 外，均需要对所操作表拥有 `INSERT` 和 `CREATE` 权限。 -- 对于 `ALTER...DROP` 语句，需要对表拥有 `DROP` 权限。 -- 对于 `ALTER...RENAME TO` 语句，需要对重命名前的表拥有 `DROP` 权限，对重命名后的表拥有 `CREATE` 和 `INSERT` 权限。 - -> **注意：** -> -> 根据 MySQL 5.7 文档中的说明，对表进行 `ALTER` 操作需要 `INSERT` 和 `CREATE` 权限，但在 MySQL 5.7.25 版本实际情况中，该操作仅需要 `ALTER` 权限。目前，TiDB 中的 `ALTER` 权限与 MySQL 实际行为保持一致。 - -### CREATE DATABASE - -需要对数据库拥有 `CREATE` 权限。 - -### CREATE INDEX - -需要对所操作的表拥有 `INDEX` 权限。 - -### CREATE TABLE - -需要对所操作的表拥有 `CREATE` 权限；若使用 `CREATE TABLE...LIKE...` 需要对相关的表拥有 `SELECT` 权限。 - -### CREATE VIEW - -需要拥有 `CREATE VIEW` 权限。 - -> **注意：** -> -> 如果当前登录用户与创建视图的用户不同，除需要 `CREATE VIEW` 权限外，还需要 `SUPER` 权限。 - -### DROP DATABASE - -需要对数据库拥有 `DROP` 权限。 - -### DROP INDEX - -需要对所操作的表拥有 `INDEX` 权限。 - -### DROP TABLES - -需要对所操作的表拥有 `DROP` 权限。 - -### TRUNCATE TABLE - -需要对所操作的表拥有 `DROP` 权限。 - -### RENAME TABLE - -需要对重命名前的表拥有 `ALTER` 和 `DROP` 权限，对重命名后的表拥有 `CREATE` 和 `INSERT` 权限。 - -### ANALYZE TABLE - -需要对所操作的表拥有 `INSERT` 和 `SELECT` 权限。 - -### SHOW - -`SHOW CREATE TABLE` 需要任意一种权限。 - -`SHOW CREATE VIEW` 需要 `SHOW VIEW` 权限。 - -### CREATE ROLE/USER - -`CREATE ROLE` 需要 `CREATE ROLE` 权限。 - -`CREATE USER` 需要 `CREATE USER` 权限 - -### DROP ROLE/USER - -`DROP ROLE` 需要 `DROPROLE` 权限。 - -`DROP USER` 需要 `CREATEUSER` 权限 - -### ALTER USER - -`ALTER USER` 需要 `CREATEUSER` 权限。 - -### GRANT - -`GRANT` 需要 `GRANT` 权限并且拥有 `GRANT` 所赋予的权限。 - -### REVOKE - -`REVOKE` 需要 `SUPER` 权限。 - -## 权限系统的实现 - -### 授权表 - -以下几张系统表是非常特殊的表，权限相关的数据全部存储在这几张表内。 - -- `mysql.user`：用户账户，全局权限 -- `mysql.db`：数据库级别的权限 -- `mysql.tables_priv`：表级别的权限 -- `mysql.columns_priv`：列级别的权限，当前暂不支持 - -这几张表包含了数据的生效范围和权限信息。例如，`mysql.user` 表的部分数据： - -{{< copyable "sql" >}} - -```sql -SELECT User,Host,Select_priv,Insert_priv FROM mysql.user LIMIT 1; -``` - -``` -+------|------|-------------|-------------+ -| User | Host | Select_priv | Insert_priv | -+------|------|-------------|-------------+ -| root | % | Y | Y | -+------|------|-------------|-------------+ -1 row in set (0.00 sec) -``` - -这条记录中，`Host` 和 `User` 决定了 root 用户从任意主机 (%) 发送过来的连接请求可以被接受，而 `Select_priv` 和 `Insert_priv` 表示用户拥有全局的 `Select` 和 `Insert` 权限。`mysql.user` 这张表里面的生效范围是全局的。 - -`mysql.db` 表里面包含的 `Host` 和 `User` 决定了用户可以访问哪些数据库，权限列的生效范围是数据库。 - -理论上，所有权限管理相关的操作，都可以通过直接对授权表的 CRUD 操作完成。 - -实现层面其实也只是包装了一层语法糖。例如删除用户会执行： - -{{< copyable "sql" >}} - -```sql -DELETE FROM mysql.user WHERE user='test'; -``` - -但是，不推荐手动修改授权表，建议使用 `DROP USER` 语句： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'; -``` - -### 连接验证 - -当客户端发送连接请求时，TiDB 服务器会对登录操作进行验证。验证过程先检查 `mysql.user` 表，当某条记录的 `User` 和 `Host` 和连接请求匹配上了，再去验证 Password。用户身份基于两部分信息，发起连接的客户端的 `Host`，以及用户名 `User`。如果 `User` 不为空，则用户名必须精确匹配。 - -User+Host 可能会匹配 `user` 表里面多行，为了处理这种情况，`user` 表的行是排序过的，客户端连接时会依次去匹配，并使用首次匹配到的那一行做权限验证。排序是按 `Host` 在前，`User` 在后。 - -### 请求验证 - -连接成功之后，请求验证会检测执行操作是否拥有足够的权限。 - -对于数据库相关请求 (`INSERT`，`UPDATE`)，先检查 `mysql.user` 表里面的用户全局权限，如果权限够，则直接可以访问。如果全局权限不足，则再检查 `mysql.db` 表。 - -`user` 表的权限是全局的，并且不管默认数据库是哪一个。比如 `user` 里面有 `DELETE` 权限，任何一行，任何的表，任何的数据库。 - -`db`表里面，User 为空是匹配匿名用户，User 里面不能有通配符。Host 和 Db 列里面可以有 `%` 和 `_`，可以模式匹配。 - -`user` 和 `db` 读到内存也是排序的。 - -`tables_priv` 和 `columns_priv` 中使用 `%` 是类似的，但是在`Db`, `Table_name`, `Column_name` 这些列不能包含 `%`。加载进来时排序也是类似的。 - -### 生效时机 - -TiDB 启动时，将一些权限检查的表加载到内存，之后使用缓存的数据来验证权限。系统会周期性的将授权表从数据库同步到缓存，生效则是由同步的周期决定，目前这个值设定的是 5 分钟。 - -修改了授权表，如果需要立即生效，可以手动调用： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -### 限制和约束 - -一些使用频率偏低的权限当前版本的实现中还未做检查，比如 `FILE`/`USAGE`/`SHUTDOWN`/`EXECUTE`/`PROCESS`/`INDEX` 等等，未来会陆续完善。 - -现阶段对权限的支持还没有做到 column 级别。 diff --git a/v3.1/reference/security/role-based-access-control.md b/v3.1/reference/security/role-based-access-control.md deleted file mode 100644 index c76c1755977f..000000000000 --- a/v3.1/reference/security/role-based-access-control.md +++ /dev/null @@ -1,386 +0,0 @@ ---- -title: 基于角色的访问控制 -category: reference ---- - -# 基于角色的访问控制 - -TiDB 的基于角色的访问控制 (RBAC) 系统的实现类似于 MySQL 8.0 的 RBAC 系统。TiDB 兼容大部分 MySQL RBAC 系统的语法。 - -本文档主要介绍 TiDB 基于角色的访问控制相关操作及实现。 - -## 角色访问控制相关操作 - -角色是一系列权限的集合。用户可以创建角色、删除角色、将权限赋予角色；也可以将角色授予给其他用户，被授予的用户在启用角色后，可以得到角色所包含的权限。 - -### 创建角色 - -创建角色 r_1 和 r_2： - -{{< copyable "sql" >}} - -```sql -CREATE ROLE `r_1`@`%`, `r_2`@`%`; -``` - -角色名的格式和规范可以参考 [TiDB 用户账户管理](/v3.1/reference/security/user-account-management.md)。 - -角色会被保存在 `mysql.user` 表中，如果表中有同名角色或用户，角色会创建失败并报错。 -创建角色的用户需要拥有 `CREATE ROLE` 或 `CREATE USER` 权限。 - -### 删除角色 - -删除角色 r_1 和 r_2： - -{{< copyable "sql" >}} - -```sql -DROP ROLE `r_1`@`%`, `r_2`@`%`; -``` - -这个操作会清除角色在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录，解除和其相关的授权关系。 -执行删除角色的用户需要拥有 `DROP ROLE` 或 `DROP USER` 权限。 - -### 授予角色权限 - -为角色授予权限和为用户授予权限操作相同，可参考 [TiDB 权限管理](/v3.1/reference/security/privilege-system.md)。 - -为 `analyst` 角色授予数据库 `test` 的读权限： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO 'analyst'@'%'; -``` - -为 `analyst` 角色授予所有数据库的全部权限： - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'analyst'@'%'; -``` - -### 收回权限 - -`REVOKE` 语句与 `GRANT` 对应： - -{{< copyable "sql" >}} - -```sql -REVOKE ALL PRIVILEGES ON `test`.* FROM 'analyst'@'%'; -``` - -具体可参考 [TiDB 权限管理](/v3.1/reference/security/privilege-system.md)。 - -### 将角色授予给用户 - -将角色 role1 和 role2 同时授予给用户 `user1@localhost` 和 `user2@localhost`。 - -{{< copyable "sql" >}} - -```sql -GRANT 'role1', 'role2' TO 'user1'@'localhost', 'user2'@'localhost'; -``` - -用户执行将角色授予给其他用户或者收回角色的命令，需要用户拥有 `SUPER` 权限。 -将角色授予给用户时并不会启用该角色，启用角色需要额外的操作。 - -以下操作可能会形成一个“关系环”： - -```sql -CREATE USER 'u1', 'u2'; -CREATE ROLE 'r1', 'r2'; - -GRANT 'u1' TO 'u1'; -GRANT 'r1' TO 'r1'; - -GRANT 'r2' TO 'u2'; -GRANT 'u2' TO 'r2'; -``` - -TiDB 允许这种多层授权关系存在，可以使用多层授权关系实现权限继承。 - -### 收回角色 - -解除角色 role1、role2 与用户 `user1@localhost`、`user2@localhost` 的授权关系。 - -{{< copyable "sql" >}} - -```sql -REVOKE 'role1', 'role2' FROM 'user1'@'localhost', 'user2'@'localhost'; -``` - -解除角色授权具有原子性，如果在撤销授权操作中失败会回滚。 - -### 设置默认启用角色 - -角色在授予给用户之后，并不会生效；只有在用户启用了某些角色之后，才可以使用角色拥有的权限。 - -可以对用户设置默认启用的角色；用户在登陆时，默认启用的角色会被自动启用。 - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE - {NONE | ALL | role [, role ] ...} - TO user [, user ] -``` - -比如将 administrator 和 developer 设置为 `test@localhost` 的默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE administrator, developer TO 'test'@'localhost'; -``` - -将 `test@localhost` 的所有角色，设为其默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE ALL TO 'test'@'localhost'; -``` - -关闭 `test@localhost` 的所有默认启用角色： - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE NONE TO 'test'@'localhost'; -``` - -需要注意的是，设置为默认启用角色的角色必须已经授予给那个用户。 - -### 在当前 session 启用角色 - -除了使用 `SET DEFAULT ROLE` 启用角色外，TiDB 还提供让用户在当前 session 启用某些角色的功能。 - -```sql -SET ROLE { - DEFAULT - | NONE - | ALL - | ALL EXCEPT role [, role ] ... - | role [, role ] ... -} -``` - -例如，为当前用户启用角色 role1 和 role2 ，仅在当前 session 有效： - -{{< copyable "sql" >}} - -```sql -SET ROLE 'role1', 'role2'; -``` - -启用当前用户的默认角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE DEFAULT -``` - -启用授予给当前用户的所有角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE ALL -``` - -不启用任何角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE NONE -``` - -启用除 role1 和 role2 外的角色： - -{{< copyable "sql" >}} - -```sql -SET ROLE ALL EXCEPT 'role1', 'role2' -``` - -> **注意：** -> -> 使用 `SET ROLE` 启用的角色只有在当前 session 才会有效。 - -### 查看当前启用角色 - -当前用户可以通过 `CURRENT_ROLE()` 函数查看当前用户启用了哪些角色。 - -例如，先对 `u1'@'localhost` 授予角色： - -{{< copyable "sql" >}} - -```sql -GRANT 'r1', 'r2' TO 'u1'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -SET DEFAULT ROLE ALL TO 'u1'@'localhost'; -``` - -在 u1 登陆后： - -{{< copyable "sql" >}} - -```sql -SELECT CURRENT_ROLE(); -``` - -``` -+-------------------+ -| CURRENT_ROLE() | -+-------------------+ -| `r1`@`%`,`r2`@`%` | -+-------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SET ROLE 'r1'; SELECT CURRENT_ROLE(); -``` - -``` -+----------------+ -| CURRENT_ROLE() | -+----------------+ -| `r1`@`%` | -+----------------+ -``` - -### 查看角色拥有的权限 - -可以通过 `SHOW GRANTS` 语句查看用户被授予了哪些角色。 -当用户查看其他用户权限相关信息时，需要对 `mysql` 数据库拥有 `SELECT` 权限。 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost'; -``` - -``` -+---------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------+ -``` - -可以通过使用 `SHOW GRANTS` 的 `USING` 选项来查看角色对应的权限。 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r1'; -``` - -``` -+---------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Select ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r2'; -``` - -``` -+-------------------------------------------------------------+ -| Grants for u1@localhost | -+-------------------------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+-------------------------------------------------------------+ -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'@'localhost' USING 'r1', 'r2'; -``` - -``` -+---------------------------------------------------------------------+ -| Grants for u1@localhost | -+---------------------------------------------------------------------+ -| GRANT USAGE ON *.* TO `u1`@`localhost` | -| GRANT Select, Insert, Update, Delete ON `db1`.* TO `u1`@`localhost` | -| GRANT `r1`@`%`,`r2`@`%` TO `u1`@`localhost` | -+---------------------------------------------------------------------+ -``` - -可以使用 `SHOW GRANTS` 或 `SHOW GRANTS FOR CURRENT_USER()` 查看当前用户的权限。 -这两个语句有细微的差异，`SHOW GRANTS` 会显示当前用户的启用角色的权限，而 `SHOW GRANTS FOR CURRENT_USER()` 则不会显示启用角色的权限。 - -### 授权表 - -在原有的四张[系统权限表](/v3.1/reference/security/privilege-system.md#授权表)的基础上，角色访问控制引入了两张新的系统表： - -- `mysql.role_edges`：记录角色与用户的授权关系 -- `mysql.default_roles`：记录每个用户默认启用的角色 - -以下是 `mysql.role_edges` 所包含的数据。 - -{{< copyable "sql" >}} - -```sql -select * from mysql.role_edges; -``` - -``` -+-----------+-----------+---------+---------+-------------------+ -| FROM_HOST | FROM_USER | TO_HOST | TO_USER | WITH_ADMIN_OPTION | -+-----------+-----------+---------+---------+-------------------+ -| % | r_1 | % | u_1 | N | -+-----------+-----------+---------+---------+-------------------+ -1 row in set (0.00 sec) -``` - -其中 `FROM_HOST` 和 `FROM_USER` 分别表示角色的主机名和用户名，`TO_HOST` 和 `TO_USER` 分别表示被授予角色的用户的主机名和用户名。 - -`mysql.default_roles` 中包含了每个用户默认启用了哪些角色。 - -{{< copyable "sql" >}} - -```sql -select * from mysql.default_roles; -``` - -``` -+------+------+-------------------+-------------------+ -| HOST | USER | DEFAULT_ROLE_HOST | DEFAULT_ROLE_USER | -+------+------+-------------------+-------------------+ -| % | u_1 | % | r_1 | -| % | u_1 | % | r_2 | -+------+------+-------------------+-------------------+ -2 rows in set (0.00 sec) -``` - -`HOST` 和 `USER` 分别表示用户的主机名和用户名，`DEFAULT_ROLE_HOST` 和 `DEFAULT_ROLE_USER` 分别表示默认启用的角色的主机名和用户名。 - -### 其他 - -由于基于角色的访问控制模块和用户管理以及权限管理结合十分紧密，因此需要参考一些操作的细节： - -- [TiDB 权限管理](/v3.1/reference/security/privilege-system.md) -- [TiDB 用户账户管理](/v3.1/reference/security/user-account-management.md) diff --git a/v3.1/reference/security/user-account-management.md b/v3.1/reference/security/user-account-management.md deleted file mode 100644 index 116f67723f88..000000000000 --- a/v3.1/reference/security/user-account-management.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: TiDB 用户账户管理 -category: reference ---- - -# TiDB 用户账户管理 - -本文档主要介绍如何管理 TiDB 用户账户。 - -## 用户名和密码 - -TiDB 将用户账户存储在 `mysql.user` 系统表里面。每个账户由用户名和 host 作为标识。每个账户可以设置一个密码。 - -通过 MySQL 客户端连接到 TiDB 服务器，通过指定的账户和密码登录： - -{{< copyable "shell-regular" >}} - -``` -mysql --port 4000 --user xxx --password -``` - -使用缩写的命令行参数则是： - -{{< copyable "shell-regular" >}} - -``` -mysql -P 4000 -u xxx -p -``` - -## 添加用户 - -添加用户有两种方式： - -* 通过标准的用户管理的 SQL 语句创建用户以及授予权限，比如 `CREATE USER` 和 `GRANT`。 -* 直接通过 `INSERT`、`UPDATE` 和 `DELETE` 操作授权表。 - -推荐使用第一种方式。第二种方式修改容易导致一些不完整的修改，因此不推荐。还有另一种可选方式是使用第三方工具的图形化界面工具。 - -{{< copyable "sql" >}} - -```sql -CREATE USER [IF NOT EXISTS] - user [auth_spec] [, user [auth_spec]] ... -``` - -{{< copyable "sql" >}} - -```sql -auth_spec: { - IDENTIFIED BY 'auth_string' - | IDENTIFIED BY PASSWORD 'hash_string' -} -``` - -* `IDENTIFIED BY 'auth_string'`：设置登录密码时，`auth_string` 会被 TiDB 经过加密存储在 `mysql.user` 表中。 -* `IDENTIFIED BY PASSWORD 'hash_string'`：设置登录密码，`hash_string` 是一个类似于 `*EBE2869D7542FCE37D1C9BBC724B97BDE54428F1` 的 41 位字符串，会被 TiDB 直接存储在 `mysql.user` 表中，该字符串可以通过 `SELECT password('auth_string')` 加密得到。 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'127.0.0.1' IDENTIFIED BY 'xxx'; -``` - -TiDB 的用户账户名由一个用户名和一个主机名组成。账户名的语法为 `'user_name'@'host_name'`。 - -- `user_name` 大小写敏感。 -- `host_name` 可以是一个主机名或 IP 地址。主机名或 IP 地址中允许使用通配符 `%` 和 `_`。例如，名为 `'%'` 的主机名可以匹配所有主机，`'192.168.1.%'` 可以匹配子网中的所有主机。 - -host 支持模糊匹配，比如： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'192.168.10.%'; -``` - -允许 `test` 用户从 `192.168.10` 子网的任何一个主机登录。 - -如果没有指定 host，则默认是所有 IP 均可登录。如果没有指定密码，默认为空： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'; -``` - -等价于： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'test'@'%' IDENTIFIED BY ''; -``` - -下面的例子用 `CREATE USER` 和 `GRANT` 语句创建了四个账户： - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'localhost' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'localhost' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'finley'@'%' IDENTIFIED BY 'some_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL PRIVILEGES ON *.* TO 'finley'@'%' WITH GRANT OPTION; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass'; -``` - -{{< copyable "sql" >}} - -```sql -GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'dummy'@'localhost'; -``` - -使用 `SHOW GRANTS` 可以看到为一个用户授予的权限： - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'admin'@'localhost'; -``` - -``` -+-----------------------------------------------------+ -| Grants for admin@localhost | -+-----------------------------------------------------+ -| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' | -+-----------------------------------------------------+ -``` - -## 删除用户 - -使用 `DROP USER` 语句可以删除用户，例如： - -{{< copyable "sql" >}} - -```sql -DROP USER 'test'@'localhost'; -``` - -这个操作会清除用户在 `mysql.user` 表里面的记录项，并且清除在授权表里面的相关记录。 - -## 保留用户账户 - -TiDB 在数据库初始化时会生成一个 `'root'@'%'` 的默认账户。 - -## 设置资源限制 - -暂不支持。 - -## 设置密码 - -TiDB 将密码存在 `mysql.user` 系统数据库里面。只有拥有 `CREATE USER` 权限，或者拥有 `mysql` 数据库权限（`INSERT` 权限用于创建，`UPDATE` 权限用于更新）的用户才能够设置或修改密码。 - -- 在 `CREATE USER` 创建用户时可以通过 `IDENTIFIED BY` 指定密码： - - {{< copyable "sql" >}} - - ```sql - CREATE USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -- 为一个已存在的账户修改密码，可以通过 `SET PASSWORD FOR` 或者 `ALTER USER` 语句完成： - - {{< copyable "sql" >}} - - ```sql - SET PASSWORD FOR 'root'@'%' = 'xxx'; - ``` - - 或者： - - {{< copyable "sql" >}} - - ```sql - ALTER USER 'test'@'localhost' IDENTIFIED BY 'mypass'; - ``` - -## 忘记 `root` 密码 - -1. 修改配置文件，在 `security` 部分添加 `skip-grant-table`： - - {{< copyable "" >}} - - ``` - [security] - skip-grant-table = true - ``` - -2. 然后使用 `root` 登录后修改密码： - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -## `FLUSH PRIVILEGES` - -如果授权表已被直接修改，运行如下命令可使改动立即生效： - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -详情参见[权限管理](/v3.1/reference/security/privilege-system.md)。 diff --git a/v3.1/reference/sql/character-set.md b/v3.1/reference/sql/character-set.md deleted file mode 100644 index 0537b208a809..000000000000 --- a/v3.1/reference/sql/character-set.md +++ /dev/null @@ -1,327 +0,0 @@ ---- -title: 字符集支持 -category: reference ---- - -# 字符集支持 - -名词解释，下面的阐述中会交错使用中文或者英文，请互相对照： - -* Character Set：字符集 -* Collation：排序规则 - -目前 `TiDB` 支持以下字符集： - -{{< copyable "sql" >}} - -```sql -SHOW CHARACTER SET; -``` - -``` -+---------|---------------|-------------------|--------+ -| Charset | Description | Default collation | Maxlen | -+---------|---------------|-------------------|--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------|---------------|-------------------|--------+ -5 rows in set (0.00 sec) -``` - -> **注意：** -> -> - 在 `TiDB` 中 `utf8` 被当做成了 `utf8mb4` 来处理。 -> - 每种字符集都对应一个默认的 Collation，当前有且仅有一个。 - -对于字符集来说，至少会有一个 Collation（排序规则）与之对应。而大部分字符集实际上会有多个 Collation。利用以下的语句可以查看： - -{{< copyable "sql" >}} - -```sql -SHOW COLLATION WHERE Charset = 'latin1'; -``` - -``` -+-------------------|---------|------|---------|----------|---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+-------------------|---------|------|---------|----------|---------+ -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -+-------------------|---------|------|---------|----------|---------+ -8 rows in set (0.00 sec) -``` - -`latin1` Collation（排序规则）分别有以下含义： - -| Collation | 含义 | -|:------------------|:----------------------------------| -| latin1_bin | latin1 编码的二进制表示 | -| latin1_danish_ci | 丹麦语/挪威语，不区分大小写 | -| latin1_general_ci | 多种语言的 (西欧)，不区分大小写 | -| latin1_general_cs | 多种语言的 (ISO 西欧)，区分大小写 | -| latin1_german1_ci | 德国 DIN-1 (字典序)，不区分大小写 | -| latin1_german2_ci | 德国 DIN-2，不区分大小写 | -| latin1_spanish_ci | 现代西班牙语，不区分大小写 | -| latin1_swedish_ci | 瑞典语/芬兰语，不区分大小写 | - -每一个字符集，都有一个默认的 Collation，例如 `utf8` 的默认 Collation 就为 `utf8_bin`。 - -> **注意：** -> -> `TiDB` 目前的 Collation 只支持区分大小写的比较排序规则。 - -## Collation 命名规则 - -`TiDB` 的 Collation 遵循着如下的命名规则： - -* Collation 的前缀是它相应的字符集，通常之后会跟着一个或者更多的后缀来表名其他的排序规则， 例如：utf8_general_ci 和 lation1_swedish_ci 是 utf8 - 和 latin1 字符集的 Collation。但是 binary 字符集只有一个 Collation，就是 binary。 -* 一个语言对应的 Collation 会包含语言的名字，例如 utf8_turkish_ci 和 utf8_hungarian_ci 是依据 Turkish(土耳其语) 和 Hungarian(匈牙利语) 的排序规则来排序。 -* Collation 的后缀表示了 Collation 是否区分大小写和是否区分口音。下面的表展示了这些特性： - -| 后缀 | 含义 | -|:-----|:---------------------------------| -| \_ai | 口音不敏感（Accent insensitive） | -| \_as | 口音敏感 （Accent sensitive） | -| \_ci | 大小写不敏感 | -| \_cs | 大小写敏感 | - -> **注意：** -> -> 目前为止 TiDB 只支持部分以上提到的 Collation。 - -## 集群 Character Set 和 Collation - -暂不支持 - -## 数据库 Character Set 和 Collation - -每个数据库都有相应的 Character Set 和 Collation，数据库的 Character Set 和 Collation 可以通过以下语句来设置： - -```sql -CREATE DATABASE db_name - [[DEFAULT] CHARACTER SET charset_name] - [[DEFAULT] COLLATE collation_name] - -ALTER DATABASE db_name - [[DEFAULT] CHARACTER SET charset_name] - [[DEFAULT] COLLATE collation_name] -``` - -在这里 `DATABASE` 可以跟 `SCHEMA` 互换使用。 - -不同的数据库之间可以使用不一样的字符集和排序规则。 - -通过系统变量 `character_set_database` 和 `collation_database` 可以查看到当前数据库的字符集以及排序规则： - -{{< copyable "sql" >}} - -```sql -create schema test1 character set utf8 COLLATE uft8_general_ci; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -use test1; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SELECT @@character_set_database, @@collation_database; -``` - -``` -+--------------------------|----------------------+ -| @@character_set_database | @@collation_database | -+--------------------------|----------------------+ -| utf8 | uft8_general_ci | -+--------------------------|----------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -create schema test2 character set latin1 COLLATE latin1_general_ci; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -use test2; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SELECT @@character_set_database, @@collation_database; -``` - -``` -+--------------------------|----------------------+ -| @@character_set_database | @@collation_database | -+--------------------------|----------------------+ -| latin1 | latin1_general_ci | -+--------------------------|----------------------+ -1 row in set (0.00 sec) -``` - -在 INFORMATION_SCHEMA 中也可以查看到这两个值： - -{{< copyable "sql" >}} - -```sql -SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME -FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = 'db_name'; -``` - -## 表的 Character Set 和 Collation - -表的 Character Set 和 Collation 可以通过以下语句来设置： - -```sql -CREATE TABLE tbl_name (column_list) - [[DEFAULT] CHARACTER SET charset_name] - [COLLATE collation_name]] - -ALTER TABLE tbl_name - [[DEFAULT] CHARACTER SET charset_name] - [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1(a int) CHARACTER SET utf8 COLLATE utf8_general_ci; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -如果表的字符集和排序规则没有设置，那么数据库的字符集和排序规则就作为其默认值。 - -## 列的 Character Set 和 Collation - -列的 Character Set 和 Collation 的语法如下： - -```sql -col_name {CHAR | VARCHAR | TEXT} (col_length) - [CHARACTER SET charset_name] - [COLLATE collation_name] - -col_name {ENUM | SET} (val_list) - [CHARACTER SET charset_name] - [COLLATE collation_name] -``` - -如果列的字符集和排序规则没有设置，那么表的字符集和排序规则就作为其默认值。 - -## 字符串 Character Sets 和 Collation - -每一字符串字符文字有一个字符集和一个比较排序规则，在使用字符串时指，此选项可选，如下： - -```sql -[_charset_name]'string' [COLLATE collation_name] -``` - -示例，如下： - -{{< copyable "sql" >}} - -```sql -SELECT 'string'; -SELECT _latin1'string'; -SELECT _latin1'string' COLLATE latin1_danish_ci; -``` - -规则，如下： - -* 规则1： 指定 CHARACTER SET charset_name 和 COLLATE collation_name，则直接使用 CHARACTER SET charset_name 和COLLATE collation_name。 -* 规则2: 指定 CHARACTER SET charset_name 且未指定 COLLATE collation_name，则使用 CHARACTER SET charset_name 和 CHARACTER SET charset_name 默认的排序比较规则。 -* 规则3: CHARACTER SET charset_name 和 COLLATE collation_name 都未指定，则使用 character_set_connection 和 collation_connection 系统变量给出的字符集和比较排序规则。 - -## 客户端连接的 Character Sets 和 Collations - -* 服务器的字符集和排序规则可以通过系统变量 `character_set_server` 和 `collation_server` 获取。 -* 数据库的字符集和排序规则可以通过环境变量 `character_set_database` 和 `collation_database` 获取。 - -对于每一个客户端的连接，也有相应的变量表示字符集和排序规则：`character_set_connection` 和 `collation_connection`。 - -`character_set_client` 代表客户端的字符集。在返回结果前，服务端会把结果根据 `character_set_results` 转换成对应的字符集。包括结果的元信息等。 - -可以用以下的语句来影响这些跟客户端相关的字符集变量： - -* `SET NAMES 'charset_name' [COLLATE 'collation_name']` - -`SET NAMES` 用来设定客户端会在之后的请求中使用的字符集。`SET NAMES utf8` 表示客户端会在接下来的请求中，都使用 utf8 字符集。服务端也会在之后返回结果的时候使用 utf8 字符集。 -`SET NAMES 'charset_name'` 语句其实等于下面语句的组合： - -{{< copyable "sql" >}} - -```sql -SET character_set_client = charset_name; -SET character_set_results = charset_name; -SET character_set_connection = charset_name; -``` - -`COLLATE` 是可选的，如果没有提供，将会用 charset_name 默认的 Collation。 - -* `SET CHARACTER SET 'charset_name'` - -跟 `SET NAMES` 类似，等价于下面语句的组合： - -{{< copyable "sql" >}} - -```sql -SET character_set_client = charset_name; -SET character_set_results = charset_name; -SET collation_connection = @@collation_database; -``` - -## 集群，服务器，数据库，表，列，字符串 Character Sets 和 Collation 优化级 - -字符串 => 列 => 表 => 数据库 => 服务器 => 集群 - -## Character Sets 和 Collation 通用选择规则 - -* 规则1： 指定 CHARACTER SET charset_name 和 COLLATE collation_name，则直接使用 CHARACTER SET charset_name 和COLLATE collation_name。 -* 规则2: 指定 CHARACTER SET charset_name 且未指定 COLLATE collation_name，则使用 CHARACTER SET charset_name 和 CHARACTER SET charset_name 默认的排序比较规则。 -* 规则3: CHARACTER SET charset_name 和 COLLATE collation_name 都未指定，则使用更高优化级给出的字符集和排序比较规则。 - -## 字符合法性检查 - -当指定的字符集为 utf8 或 utf8mb4 时，TiDB 仅支持合法的 utf8 字符。对于不合法的字符，会报错：`incorrect utf8 value`。该字符合法性检查与 MySQL 8.0 兼容，与 MySQL 5.7 及以下版本不兼容。 - -如果不希望报错，可以通过 `set @@tidb_skip_utf8_check=1;` 跳过字符检查。 - -更多细节，参考 [Connection Character Sets and Collations](https://dev.mysql.com/doc/refman/5.7/en/charset-connection.html)。 diff --git a/v3.1/reference/sql/constraints.md b/v3.1/reference/sql/constraints.md deleted file mode 100644 index 64bd53180ad2..000000000000 --- a/v3.1/reference/sql/constraints.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: 约束 -category: reference ---- - -# 约束 - -TiDB 支持的基本约束与 MySQL 的基本相同，但有以下区别： - -- 默认对唯一约束进行[惰性检查](/v3.1/reference/transactions/overview.md#事务的惰性检查)。通过在事务提交时再进行批量检查，TiDB 能够减少网络开销、提升性能。您可通过设置 `tidb_constraint_check_in_place` 为 `TRUE` 改变此行为。 - -- TiDB 支持创建外键约束，但不会在 DML 语句中对外键进行约束（即外键约束不生效）。 - -## 外键约束 - -目前，TiDB 支持创建外键。例如： - -```sql -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - doc JSON -); -CREATE TABLE orders ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - user_id INT NOT NULL, - doc JSON, - FOREIGN KEY fk_user_id (user_id) REFERENCES users(id) -); -``` - -{{< copyable "sql" >}} - -```sql -SELECT table_name, column_name, constraint_name, referenced_table_name, referenced_column_name -FROM information_schema.key_column_usage WHERE table_name IN ('users', 'orders'); -``` - -``` -+------------+-------------+-----------------+-----------------------+------------------------+ -| table_name | column_name | constraint_name | referenced_table_name | referenced_column_name | -+------------+-------------+-----------------+-----------------------+------------------------+ -| users | id | PRIMARY | NULL | NULL | -| orders | id | PRIMARY | NULL | NULL | -| orders | user_id | fk_user_id | users | id | -+------------+-------------+-----------------+-----------------------+------------------------+ -3 rows in set (0.00 sec) -``` - -TiDB 也支持使用 `ALTER TABLE` 命令来删除外键（`DROP FOREIGN KEY`）和添加外键（`ADD FOREIGN KEY`）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE orders DROP FOREIGN KEY fk_user_id; -ALTER TABLE orders ADD FOREIGN KEY fk_user_id (user_id) REFERENCES users(id); -``` - -### 注意 - -* TiDB 支持外键是为了在将其他数据库迁移到 TiDB 时，不会因为此语法报错。但是，TiDB 不会在 DML 语句中对外键进行约束。例如，即使 `users` 表中不存在 `id=123` 的记录，下列事务也能提交成功： - - ``` - START TRANSACTION; - INSERT INTO orders (user_id, doc) VALUES (123, NULL); - COMMIT; - ``` - -* TiDB 在执行 `SHOW CREATE TABLE` 语句的结果中不显示外键信息。 - -## 非空约束 - -TiDB 支持的非空约束规则与 MySQL 支持的一致。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - age INT NOT NULL, - last_login TIMESTAMP -); -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,123,NOW()); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,NULL,NOW()); -``` - -``` -ERROR 1048 (23000): Column 'age' cannot be null -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (id,age,last_login) VALUES (NULL,123,NULL); -``` - -``` -Query OK, 1 row affected (0.03 sec) -``` - -* 第一条 `INSERT` 语句成功，因为对于定义为 `AUTO_INCREMENT` 的列，允许 `NULL` 作为其特殊值。TiDB 将为其分配下一个自动值。 - -* 第二条 `INSERT` 语句失败，因为 `age` 列被定义为 `NOT NULL`。 - -* 第三条 `INSERT` 语句成功，因为 `last_login` 列没有被明确地指定为 `NOT NULL`。默认允许 `NULL` 值。 - -## 主键约束 - -TiDB 支持的主键约束规则与 MySQL 支持的相似。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 (a INT NULL PRIMARY KEY); -``` - -``` -ERROR 1171 (42000): All parts of a PRIMARY KEY must be NOT NULL; if you need NULL in a key, use UNIQUE instead -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t3 (a INT NOT NULL PRIMARY KEY, b INT NOT NULL PRIMARY KEY); -``` - -``` -ERROR 1068 (42000): Multiple primary key defined -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t4 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b)); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -* 表 `t2` 创建失败，因为定义为主键的列 `a` 不能允许 `NULL` 值。 -* 表 `t3` 创建失败，因为一张表只能有一个主键。 -* 表 `t4` 创建成功，因为虽然只能有一个主键，但 TiDB 支持定义一个多列组合作为复合主键。 - -除上述规则外，TiDB 还强加了另一个限制，即一旦一张表创建成功，其主键就不能再改变。 - -## 唯一约束 - -在 TiDB 中，默认会对唯一约束进行惰性检查。通过直到事务提交时才进行批量检查，TiDB 能够减少网络通信开销。例如： - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -``` - -``` -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('steve'),('elizabeth'); -``` - -``` -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -``` - -* 第一条 `INSERT` 语句不会导致重复键错误，这同 MySQL 的规则一致。该检查将推迟到事务提交时才会进行。 - -如果将 `tidb_constraint_check_in_place` 更改为 `TRUE`，则会在执行语句时就对唯一约束进行检查。例如： - -```sql -DROP TABLE IF EXISTS users; -CREATE TABLE users ( - id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, - username VARCHAR(60) NOT NULL, - UNIQUE KEY (username) -); -INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill'); -``` - -{{< copyable "sql" >}} - -```sql -SET tidb_constraint_check_in_place = TRUE; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill'); -``` - -``` -ERROR 1062 (23000): Duplicate entry 'bill' for key 'username' -.. -``` - -* 第一条 `INSERT` 语句导致了重复键错误。这会造成额外的网络通信开销，并可能降低插入操作的吞吐量。 diff --git a/v3.1/reference/sql/data-types/date-and-time.md b/v3.1/reference/sql/data-types/date-and-time.md deleted file mode 100644 index 6645d949bd38..000000000000 --- a/v3.1/reference/sql/data-types/date-and-time.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 日期和时间类型 -category: reference ---- - -# 日期和时间类型 - -TiDB 支持 MySQL 所有的日期和时间类型，包括 DATE、DATETIME、TIMESTAMP、TIME 以及 YEAR，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-types.html)文档。 - -## 类型定义 - -### `DATE` 类型 - -`DATE` 类型的格式为 `YYYY-MM-DD`，支持的范围是 `1000-01-01` 到 `9999-12-31`。 - -{{< copyable "sql" >}} - -```sql -DATE -``` - -### `TIME` 类型 - -`TIME` 类型的格式为 `HH:MM:SS[.fraction]`，支持的范围是 `-838:59:59.000000` 到 `838:59:59.000000`。`TIME` 不仅可用于指示一天内的时间，还可用于指两个事件之间的时间间隔。`fsp` 参数表示秒精度，取值范围为：0 ~ 6，默认值为 0。 - -{{< copyable "sql" >}} - -```sql -TIME[(fsp)] -``` - -> **注意：** -> -> 注意 `TIME` 的缩写形式。例如，'11:12' 表示 '11:12:00' 而不是 '00:11:12'。但是，'1112' 表示 '00:11:12'。这些差异取决于 `:` 字符的存在与否。 - -### `DATETIME` 类型 - -`DATETIME` 类型是日期和时间的组合，格式为 `YYYY-MM-DD HH:MM:SS[.fraction]`。支持的范围是 `1000-01-01 00:00:00.000000` 到 `9999-12-31 23:59:59.000000`。`fsp` 参数表示秒精度，取值范围为 0~6，默认值为 0。 - -{{< copyable "sql" >}} - -```sql -DATETIME[(fsp)] -``` - -### `TIMESTAMP` 类型 - -`TIMESTAMP` 类型包含日期和时间，支持的范围是 `1970-01-01 00:00:01.000000` 到 `2038-01-19 03:14:07.999999`。`fsp` 参数表示秒精度，取值范围为 0~6，默认值为 0。在 `TIMESTAMP` 中，不允许零出现在月份部分或日期部分，唯一的例外是零值本身 '0000-00-00 00:00:00'。 - -{{< copyable "sql" >}} - -```sql -TIMESTAMP[(fsp)] -``` - -### `YEAR` 类型 - -`YEAR` 类型的格式为 'YYYY'，支持的值范围是 1901 到 2155，或零值 0000。 - -{{< copyable "sql" >}} - -```sql -YEAR[(4)] -``` diff --git a/v3.1/reference/sql/data-types/default-values.md b/v3.1/reference/sql/data-types/default-values.md deleted file mode 100644 index cfe82fb74cb7..000000000000 --- a/v3.1/reference/sql/data-types/default-values.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 数据类型的默认值 -category: reference ---- - -# 数据类型的默认值 - -在一个数据类型描述中的 `DEFAULT value` 段描述了一个列的默认值。这个默认值必须是常量，不可以是一个函数或者是表达式。但是对于时间类型，可以例外的使用 `NOW`、`CURRENT_TIMESTAMP`、`LOCALTIME`、`LOCALTIMESTAMP` 等函数作为 `DATETIME` 或者 `TIMESTAMP` 的默认值。 - -`BLOB`、`TEXT` 以及 `JSON` 不可以设置默认值。 - -如果一个列的定义中没有 `DEFAULT` 的设置。TiDB 按照如下的规则决定: - -* 如果该类型可以使用 `NULL` 作为值，那么这个列会在定义时添加隐式的默认值设置 `DEFAULT NULL`。 -* 如果该类型无法使用 `NULL` 作为值，那么这个列在定义时不会添加隐式的默认值设置。 - -对于一个设置了 `NOT NULL` 但是没有显式设置 `DEFAULT` 的列，当 `INSERT`、`REPLACE` 没有涉及到该列的值时，TiDB 根据当时的 `SQL_MODE` 进行不同的行为： - -* 如果此时是 `strict sql mode`，在事务中的语句会导致事务失败并回滚，非事务中的语句会直接报错。 -* 如果此时不是 `strict sql mode`，TiDB 会为这列赋值为列数据类型的隐式默认值。 - -此时隐式默认值的设置按照如下规则： - -* 对于数值类型，它们的默认值是 0。当有 `AUTO_INCREMENT` 参数时，默认值会按照增量情况赋予正确的值。 -* 对于除了时间戳外的日期时间类型，默认值会是该类型的“零值”。时间戳类型的默认值会是当前的时间。 -* 对于除枚举以外的字符串类型，默认值会是空字符串。对于枚举类型，默认值是枚举中的第一个值。 diff --git a/v3.1/reference/sql/data-types/json.md b/v3.1/reference/sql/data-types/json.md deleted file mode 100644 index 5bfc89554dc4..000000000000 --- a/v3.1/reference/sql/data-types/json.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: JSON 类型 -category: reference ---- - -# JSON 类型 - -JSON 类型可以存储 JSON 这种半结构化的数据，相比于直接将 JSON 存储为字符串，它的好处在于： - -1. 使用 Binary 格式进行序列化，对 JSON 的内部字段的查询、解析加快； -2. 多了 JSON 合法性验证的步骤，只有合法的 JSON 文档才可以放入这个字段中； - -JSON 字段本身上，并不能创建索引。相反，可以对 JSON 文档中的某个子字段创建索引。例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE city ( - id INT PRIMARY KEY, - detail JSON, - population INT AS (JSON_EXTRACT(detail, '$.population')) -); -INSERT INTO city (id,detail) VALUES (1, '{"name": "Beijing", "population": 100}'); -SELECT id FROM city WHERE population >= 100; -``` diff --git a/v3.1/reference/sql/data-types/numeric.md b/v3.1/reference/sql/data-types/numeric.md deleted file mode 100644 index 08cd36538837..000000000000 --- a/v3.1/reference/sql/data-types/numeric.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 数值类型 -category: reference ---- - -# 数值类型 - -TiDB 支持 MySQL 所有的数值类型，按照精度可以分为: - -+ [整数类型（精确值)](#整数类型) -+ [浮点类型（近似值)](#浮点类型) -+ [定点类型（精确值)](#定点类型) - -## 整数类型 - -TiDB 支持 MySQL 所有的整数类型，包括 `INTEGER`/`INT`、`TINYINT`、`SMALLINT`、`MEDIUMINT` 以及 `BIGINT`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/numeric-type-overview.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| ---- | --------| -| M | 类型显示宽度，可选 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识，但是没有做补零的操作 | - -### 类型定义 - -#### `BIT` 类型 - -比特值类型。M 表示比特位的长度，取值范围从1到64，其默认值是1。 - -{{< copyable "sql" >}} - -```sql -BIT[(M)] -``` - -#### `BOOLEAN` 类型 - -布尔类型，别名为 `BOOL`，和 `TINYINT(1)` 等价。零值被认为是 `False`，非零值认为是 `True`。在 TiDB 内部，`True` 存储为 `1`，`False` 存储为 `0`。 - -{{< copyable "sql" >}} - -```sql -BOOLEAN -``` - -#### `TINYINT` 类型 - -`TINYINT` 类型。有符号数的范围是 `[-128, 127]`。无符号数的范围是 `[0, 255]`。 - -{{< copyable "sql" >}} - -```sql -TINYINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -#### `SMALLINT` 类型 - -`SMALLINT` 类型。有符号数的范围是 `[-32768, 32767]`。无符号数的范围是 `[0, 65535]`。 - -{{< copyable "sql" >}} - -```sql -SMALLINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -#### `MEDIUMINT` 类型 - -`MEDIUMINT` 类型。有符号数的范围是 `[-8388608, 8388607]`。无符号数的范围是 `[0, 16777215]`。 - -{{< copyable "sql" >}} - -```sql -MEDIUMINT[(M)] [UNSIGNED] [ZEROFILL] -``` - -### `INTEGER` 类型 - -`INTEGER` 类型，别名 `INT`。有符号数的范围是 `[-2147483648, 2147483647]`。无符号数的范围是 `[0, 4294967295]`。 - -{{< copyable "sql" >}} - -```sql -INT[(M)] [UNSIGNED] [ZEROFILL] -``` - -或者： - -{{< copyable "sql" >}} - -```sql -INTEGER[(M)] [UNSIGNED] [ZEROFILL] -``` - -### `BIGINT` 类型 - -`BIGINT` 类型。有符号数的范围是 `[-9223372036854775808, 9223372036854775807]`。无符号数的范围是 `[0, 18446744073709551615]`。 - -{{< copyable "sql" >}} - -```sql -BIGINT[(M)] [UNSIGNED] [ZEROFILL] -> -``` - -### 存储空间以及取值范围 - -每种类型对存储空间的需求以及最大/最小值如下表所示: - -| 类型 | 存储空间 | 最小值(有符号/无符号) | 最大值(有符号/无符号) | -| ----------- |----------|-----------------------| --------------------- | -| `TINYINT` | 1 | -128 / 0 | 127 / 255 | -| `SMALLINT` | 2 | -32768 / 0 | 32767 / 65535 | -| `MEDIUMINT` | 3 | -8388608 / 0 | 8388607 / 16777215 | -| `INT` | 4 | -2147483648 / 0 | 2147483647 / 4294967295 | -| `BIGINT` | 8 | -9223372036854775808 / 0 | 9223372036854775807 / 18446744073709551615 | - -## 浮点类型 - -TiDB 支持 MySQL 所有的浮点类型，包括 `FLOAT`、`DOUBLE`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| -------- | ------------------------------- | -| M | 小数总位数 | -| D | 小数点后位数 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识 | - -### 类型定义 - -#### `FLOAT` 类型 - -单精度浮点数。允许的值范围为 -2^128 ~ +2^128，也即 -3.402823466E+38 到 -1.175494351E-38、0 和 1.175494351E-38 到 3.402823466E+38。这些是基于 IEEE 标准的理论限制。实际的范围根据硬件或操作系统的不同可能稍微小些。 - -`FLOAT(p)` 类型中，`p` 表示精度（以位数表示）。只使用该值来确定是否结果列的数据类型为 `FLOAT` 或 `DOUBLE`。如果 `p` 为从 0 到 24，数据类型变为没有 M 或 D 值的 `FLOAT`。如果 `p` 为从 25 到 53，数据类型变为没有 M 或 D 值的 `DOUBLE`。结果列范围与本节前面描述的单精度 `FLOAT` 或双精度 `DOUBLE` 数据类型相同。 - -{{< copyable "sql" >}} - -```sql -FLOAT[(M,D)] [UNSIGNED] [ZEROFILL] -FLOAT(p) [UNSIGNED] [ZEROFILL] -``` - -> **警告：** -> -> 与在 MySQL 中一样，`FLOAT` 数据类型存储近似值。对于货币之类的精确值，建议使用 `DECIMAL` 类型。 - -#### `DOUBLE` 类型 - -双精度浮点数，别名为 `DOUBLE PRECISION`。允许的值范围为：-2^1024 ~ +2^1024，也即是 -1.7976931348623157E+308 到 -2.2250738585072014E-308、0 和 2.2250738585072014E-308 到 1.7976931348623157E+308。这些是基于 IEEE 标准的理论限制。实际的范围根据硬件或操作系统的不同可能稍微小些。 - -{{< copyable "sql" >}} - -```sql -DOUBLE[(M,D)] [UNSIGNED] [ZEROFILL] -DOUBLE PRECISION [(M,D)] [UNSIGNED] [ZEROFILL], REAL[(M,D)] [UNSIGNED] [ZEROFILL] -``` - -> **警告：** -> -> 与在 MySQL 中一样，`DOUBLE` 数据类型存储近似值。对于货币之类的精确值，建议使用 `DECIMAL` 类型。 - -### 存储空间 - -每种类型对存储空间的需求如下表所示: - -| 类型 | 存储空间 | -| ----------- |----------| -| `FLOAT` | 4 | -| `FLOAT(p)` | 如果 0 <= p <= 24 为 4 个字节, 如果 25 <= p <= 53 为 8 个字节| -| `DOUBLE` | 8 | - -## 定点类型 - -TiDB 支持 MySQL 所有的定点类型，包括 `DECIMAL`、`NUMERIC`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/fixed-point-types.html)文档。 - -字段说明： - -| 语法元素 | 说明 | -| -------- | ------------------------------- | -| M | 小数总位数 | -| D | 小数点后位数 | -| UNSIGNED | 无符号数，如果不加这个标识，则为有符号数 | -| ZEROFILL | 补零标识，如果有这个标识，TiDB 会自动给类型增加 UNSIGNED 标识 | - -### 类型定义 - -#### `DECIMAL` 类型 - -定点数，别名为 `NUMERIC`。M 是小数位数（精度）的总数，D 是小数点（标度）后面的位数。小数点和 `-`（负数）符号不包括在 M 中。如果 D 是 0，则值没有小数点或分数部分。如果 D 被省略，默认是 0。如果 M 被省略，默认是 10。 - -{{< copyable "sql" >}} - -```sql -DECIMAL[(M[,D])] [UNSIGNED] [ZEROFILL] -NUMERIC[(M[,D])] [UNSIGNED] [ZEROFILL] -``` diff --git a/v3.1/reference/sql/data-types/overview.md b/v3.1/reference/sql/data-types/overview.md deleted file mode 100644 index c3dbdd8624cb..000000000000 --- a/v3.1/reference/sql/data-types/overview.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 数据类型概述 -category: reference ---- - -# 数据类型概述 - -TiDB 支持除空间类型 (`SPATIAL`) 之外的所有 MySQL 数据类型，包括[数值型类型](/v3.1/reference/sql/data-types/numeric.md)、[字符串类型](/v3.1/reference/sql/data-types/string.md)、[时间和日期类型](/v3.1/reference/sql/data-types/date-and-time.md)、[JSON 类型](/v3.1/reference/sql/data-types/json.md)。 - -数据类型定义一般为 `T(M[, D])`，其中： - -* `T` 表示具体的类型。 -* `M` 在整数类型中表示最大显示长度；在浮点数或者定点数中表示精度；在字符类型中表示最大长度。`M` 的最大值取决于具体的类型。 -* `D` 表示浮点数、定点数的小数位长度。 -* `fsp` 在时间和日期类型里的 `TIME`、`DATETIME` 以及 `TIMESTAMP` 中表示秒的精度，其取值范围是 0 到 6。值为 0 表示没有小数部分。如果省略，则默认精度为 0。 diff --git a/v3.1/reference/sql/data-types/string.md b/v3.1/reference/sql/data-types/string.md deleted file mode 100644 index 801998dc71b6..000000000000 --- a/v3.1/reference/sql/data-types/string.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: 字符串类型 -category: reference ---- - -# 字符串类型 - -TiDB 支持 MySQL 所有的字符串类型，包括 `CHAR`、`VARCHAR`、`BINARY`、`VARBINARY`、`BLOB`、`TEXT`、`ENUM` 以及 `SET`，完整信息参考[这篇](https://dev.mysql.com/doc/refman/5.7/en/string-types.html)文档。 - -## 类型定义 - -### `CHAR` 类型 - -定长字符串。`CHAR` 列的长度固定为创建表时声明的长度。长度可以为从 0 到 255 的任何值。当保存 CHAR 值时，在它们的右边填充空格以达到指定的长度。 - -{{< copyable "sql" >}} - -```sql -[NATIONAL] CHAR[(M)] [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `VARCHAR` 类型 - -变长字符串。M 表示最大列长度，范围是 0 到 65535。VARCHAR 的最大实际长度由最长的行的大小和使用的字符集确定。 - -{{< copyable "sql" >}} - -```sql -[NATIONAL] VARCHAR(M) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `TEXT` 类型 - -文本串。M 表示最大列长度，范围是 0 到 65535。TEXT 的最大实际长度由最长的行的大小和使用的字符集确定。 - -{{< copyable "sql" >}} - -```sql -TEXT[(M)] [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `TINYTEXT` 类型 - -类似于 `TEXT`，区别在于最大列长度为 255。 - -{{< copyable "sql" >}} - -```sql -TINYTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `MEDIUMTEXT` 类型 - -类似于 TEXT，区别在于最大列长度为 16,777,215。 - -{{< copyable "sql" >}} - -```sql -MEDIUMTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `LONGTEXT` 类型 - -类似于 `TEXT`，区别在于最大列长度为 4,294,967,295。 - -{{< copyable "sql" >}} - -```sql -LONGTEXT [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -### `BINARY` 类型 - -类似于 `CHAR`，区别在于 BINARY 存储的是二进制字符串。 - -{{< copyable "sql" >}} - -```sql -BINARY(M) -``` - -### `VARBINARY` 类型 - -类似于 `VARCHAR`，区别在于 VARBINARY 存储的是二进制字符串。 - -{{< copyable "sql" >}} - -```sql -VARBINARY(M) -``` - -### `TINYBLOB` 类型 - -类似于 BLOB，区别在于最大列长度为 255。 - -{{< copyable "sql" >}} - -```sql -TINYBLOB -``` - -### `BLOB` 类型 - -二进制大文件。M 表示最大列长度，范围是 0 到 65535。 - -{{< copyable "sql" >}} - -```sql -BLOB[(M)] -``` - -### `MEDIUMBLOB` 类型 - -类似于 `BLOB`，区别在于最大列长度为 16,777,215。 - -{{< copyable "sql" >}} - -```sql -MEDIUMBLOB -``` - -### `LONGBLOB` 类型 - -类似于 `BLOB`，区别在于最大列长度为 4,294,967,295。 - -{{< copyable "sql" >}} - -```sql -LONGBLOB -``` - -### `ENUM` 类型 - -枚举类型是一个字符串，它只能有一个值的字符串对象。其值必须是从一个固定集合中选取，这个固定集合在创建表的时候定义，语法是： - -{{< copyable "sql" >}} - -```sql -ENUM('value1','value2',...) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -ENUM('apple', 'orange', 'pear') -``` - -枚举类型的值在 TiDB 内部使用数值来存储，每个值会按照定义的顺序转换为一个数字，比如上面的例子中，每个字符串值都会映射为一个数字： - -| 值 | 数字 | -| ---- | ---- | -| NULL | NULL | -| '' | 0 | -| 'apple' | 1 | -| 'orange' | 2 | -| 'pear' | 3 | - -更多信息参考 [MySQL 枚举文档](https://dev.mysql.com/doc/refman/5.7/en/enum.html)。 - -### `SET` 类型 - -集合类型是一个包含零个或多个值的字符串，其中每个值必须是从一个固定集合中选取，这个固定集合在创建表的时候定义，语法是： - -{{< copyable "sql" >}} - -```sql -SET('value1','value2',...) [CHARACTER SET charset_name] [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -SET('1', '2') NOT NULL -``` - -上面的例子中，这列的有效值可以是： - -``` -'' -'1' -'2' -'1,2' -``` - -集合类型的值在 TiDB 内部会转换为一个 Int64 数值，每个元素是否存在用一个二进制位的 0/1 值来表示，比如这个例子 `SET('a','b','c','d')`，每一个元素都被映射为一个数字，且每个数字的二进制表示只会有一位是 1： - -| 成员 | 十进制表示 | 二进制表示 | -| ---- | ---- | ------ | -| 'a' | 1 | 0001 | -| 'b' | 2 | 0010 | -| 'c' | 4 | 0100 | -| 'd' | 8 | 1000 | - -这样对于值为 `('a', 'c')` 的元素，其二进制表示即为 0101。 - -更多信息参考 [MySQL 集合文档](https://dev.mysql.com/doc/refman/5.7/en/set.html)。 diff --git a/v3.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md b/v3.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md deleted file mode 100644 index a15a4eb60660..000000000000 --- a/v3.1/reference/sql/functions-and-operators/aggregate-group-by-functions.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: GROUP BY 聚合函数 -category: reference ---- - -# GROUP BY 聚合函数 - -本文将详细介绍 TiDB 支持的聚合函数。 - -## TiDB 支持的聚合函数 - -TiDB 支持的 MySQL GROUP BY 聚合函数如下所示： - -| 函数名 | 功能描述 | -|:---------|:--------------------| -| [`COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count) | 返回检索到的行的数目| -| [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_count-distinct) | 返回不同值的数目 | -| [`SUM()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_sum) | 返回和 | -| [`AVG()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_avg) | 返回平均值 | -| [`MAX()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_max) | 返回最大值 | -| [`MIN()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_min) | 返回最小值 | -| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_group-concat) | 返回连接的字符串 | - -> **注意：** -> -> - 除非另有说明，否则聚合函数默认忽略 `NULL` 值。 -> - 如果在不包含 `GROUP BY` 子句的语句中使用聚合函数，则相当于对所有行进行分组。 - -## GROUP BY 修饰符 - -TiDB 目前不支持 `GROUP BY` 修饰符，例如 `WITH ROLLUP`，将来会提供支持。详情参阅 [#4250](https://github.com/pingcap/tidb/issues/4250)。 - -## 对 SQL 模式的支持 - -TiDB 支持 SQL 模式 `ONLY_FULL_GROUP_BY`，当启用该模式时，TiDB 拒绝不明确的非聚合列的查询。例如，以下查询在启用 `ONLY_FULL_GROUP_BY` 时是不合规的，因为 `SELECT` 列表中的非聚合列 "b" 在 `GROUP BY` 语句中不显示： - -{{< copyable "sql" >}} - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 3), (2, 2, 3), (3, 2, 3); -``` - -{{< copyable "sql" >}} - -```sql -select a, b, sum(c) from t group by a; -``` - -``` -+------+------+--------+ -| a | b | sum(c) | -+------+------+--------+ -| 1 | 2 | 3 | -| 2 | 2 | 3 | -| 3 | 2 | 3 | -+------+------+--------+ -3 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -set sql_mode = 'ONLY_FULL_GROUP_BY'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select a, b, sum(c) from t group by a; -``` - -``` -ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP BY clause and contains nonaggregated column 'b' which is not functionally dependent on columns in GROUP BY clause; this is incompatible with sql_mode=only_full_group_by -``` - -目前，TiDB 默认开启 SQL 模式 [`ONLY_FULL_GROUP_BY`](/v3.1/reference/mysql-compatibility.md#默认设置的区别)。 - -### 与 MySQL 的区别 - -TiDB 目前实现的 `ONLY_FULL_GROUP_BY` 没有 MySQL 5.7 严格。例如，假设我们执行以下查询，希望结果按 "c" 排序： - -{{< copyable "sql" >}} - -```sql -drop table if exists t; -create table t(a bigint, b bigint, c bigint); -insert into t values(1, 2, 1), (1, 2, 2), (1, 3, 1), (1, 3, 2); -select distinct a, b from t order by c; -``` - -要对结果进行排序，必须先清除重复。但选择保留哪一行会影响 `c` 的保留值，也会影响排序，并使其具有任意性。 - -在 MySQL 中，`ORDER BY` 表达式需至少满足以下条件之一，否则 `DISTINCT` 和 `ORDER BY` 查询将因不合规而被拒绝： - -- 表达式等同于 `SELECT` 列表中的一个。 -- 表达式引用并属于查询选择表的所有列都是 `SELECT` 列表的元素。 - -但是在 TiDB 中，上述查询是合规的，详情参阅 [#4254](https://github.com/pingcap/tidb/issues/4254)。 - -TiDB 中另一个标准 SQL 的扩展允许 `HAVING` 子句中的引用使用 `SELECT` 列表中的别名表达式。例如：以下查询返回在 `orders` 中只出现一次的 `name` 值： - -{{< copyable "sql" >}} - -```sql -select name, count(name) from orders -group by name -having count(name) = 1; -``` - -这个 TiDB 扩展允许在聚合列的 `HAVING` 子句中使用别名： - -{{< copyable "sql" >}} - -```sql -select name, count(name) as c from orders -group by name -having c = 1; -``` - -标准 SQL 只支持 `GROUP BY` 子句中的列表达式，以下语句不合规，因为 `FLOOR(value/100)` 是一个非列表达式： - -{{< copyable "sql" >}} - -```sql -select id, floor(value/100) -from tbl_name -group by id, floor(value/100); -``` - -TiDB 对标准 SQL 的扩展支持 `GROUP BY` 子句中非列表达式，认为上述语句合规。 - -标准 SQL 也不支持 `GROUP BY` 子句中使用别名。TiDB 对标准 SQL 的扩展支持使用别名，查询的另一种写法如下： - -{{< copyable "sql" >}} - -```sql -select id, floor(value/100) as val -from tbl_name -group by id, val; -``` - -## TiDB 不支持的聚合函数 - -TiDB 目前不支持的聚合函数如下所示，相关进展参阅 [TiDB #7623](https://github.com/pingcap/tidb/issues/7623)。 - -- `STD`, `STDDEV`, `STDDEV_POP` -- `STDDEV_SAMP` -- `VARIANCE`, `VAR_POP` -- `VAR_SAMP` -- `JSON_ARRAYAGG` -- `JSON_OBJECTAGG` diff --git a/v3.1/reference/sql/functions-and-operators/bit-functions-and-operators.md b/v3.1/reference/sql/functions-and-operators/bit-functions-and-operators.md deleted file mode 100644 index 9d44c9caf9af..000000000000 --- a/v3.1/reference/sql/functions-and-operators/bit-functions-and-operators.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: 位函数和操作符 -category: reference ---- - -# 位函数和操作符 - -TiDB 支持使用 MySQL 5.7 中提供的所有[位函数和操作符](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html)。 - -**位函数和操作符表** - -| 函数和操作符名 | 功能描述 | -| -------------- | ------------------------------------- | -| [`BIT_COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#function_bit-count) | 返回参数二进制表示中为 1 的个数 | -| [&](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-and) | 位与 | -| [~](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-invert) | 按位取反 | -| [\|](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-or) | 位或 | -| [^](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-xor) | 位亦或 | -| [<<](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_left-shift) | 左移 | -| [>>](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_right-shift) | 右移 | diff --git a/v3.1/reference/sql/functions-and-operators/cast-functions-and-operators.md b/v3.1/reference/sql/functions-and-operators/cast-functions-and-operators.md deleted file mode 100644 index 8a6efeacdb27..000000000000 --- a/v3.1/reference/sql/functions-and-operators/cast-functions-and-operators.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Cast 函数和操作符 -category: reference ---- - -# Cast 函数和操作符 - -Cast 函数和操作符用于将某种数据类型的值转换为另一种数据类型。TiDB 支持使用 MySQL 5.7 中提供的所有 [Cast 函数和操作符](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html)。 - -## Cast 函数和操作符表 - -| 函数和操作符名 | 功能描述 | -| --------------- | ----------------------------------- | -| [`BINARY`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#operator_binary) | 将一个字符串转换成一个二进制字符串 | -| [`CAST()`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_cast) | 将一个值转换成一个确定类型 | -| [`CONVERT()`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_convert) | 将一个值转换成一个确定类型 | diff --git a/v3.1/reference/sql/functions-and-operators/control-flow-functions.md b/v3.1/reference/sql/functions-and-operators/control-flow-functions.md deleted file mode 100644 index 407a57690777..000000000000 --- a/v3.1/reference/sql/functions-and-operators/control-flow-functions.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 控制流程函数 -category: reference ---- - -# 控制流程函数 - -TiDB 支持使用 MySQL 5.7 中提供的所有[控制流程函数](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html)。 - -| 函数名 | 功能描述 | -|:--------------------------------------------------------------------------------------------------|:----------------------------------| -| [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case) | Case 操作符 | -| [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if) | 构建 if/else | -| [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | 构建 Null if/else | -| [`NULLIF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_nullif) | 如果 expr1 = expr2，返回 `NULL` | diff --git a/v3.1/reference/sql/functions-and-operators/date-and-time-functions.md b/v3.1/reference/sql/functions-and-operators/date-and-time-functions.md deleted file mode 100644 index e9bf3ab4b279..000000000000 --- a/v3.1/reference/sql/functions-and-operators/date-and-time-functions.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: 日期和时间函数 -category: reference ---- - -# 日期和时间函数 - -TiDB 支持使用 MySQL 5.7 中提供的所有[日期和时间函数](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html)。 - -## 日期时间函数表 - -| 函数名 | 功能描述 | -| ------ | ---------------------------------------- | -| [`ADDDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_adddate) | 将时间间隔添加到日期上 | -| [`ADDTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_addtime) | 时间数值相加 | -| [`CONVERT_TZ()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_convert-tz) | 转换时区 | -| [`CURDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_curdate) | 返回当前日期 | -| [`CURRENT_DATE()`, `CURRENT_DATE`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-date) | 与 CURDATE() 同义 | -| [`CURRENT_TIME()`, `CURRENT_TIME`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-time) | 与 CURTIME() 同义 | -| [`CURRENT_TIMESTAMP()`, `CURRENT_TIMESTAMP`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_current-timestamp) | 与 NOW() 同义 | -| [`CURTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_curtime) | 返回当前时间 | -| [`DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date) | 从日期或日期/时间表达式中提取日期部分| -| [`DATE_ADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-add) | 将时间间隔添加到日期上| -| [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | 返回满足指定格式的日期/时间 | -| [`DATE_SUB()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-sub) | 从日期减去指定的时间间隔 | -| [`DATEDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_datediff) | 返回两个日期间隔的天数| -| [`DAY()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_day) | 与 DAYOFMONTH() 同义| -| [`DAYNAME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayname) | 返回星期名称 | -| [`DAYOFMONTH()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofmonth) | 返回参数对应的天数部分(1-31)| -| [`DAYOFWEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofweek) | 返回参数对应的星期下标| -| [`DAYOFYEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_dayofyear) | 返回参数代表一年的哪一天 (1-366) | -| [`EXTRACT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_extract) | 提取日期/时间中的单独部分| -| [`FROM_DAYS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_from-days) | 将天数转化为日期 | -| [`FROM_UNIXTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_from-unixtime) | 将 Unix 时间戳格式化为日期 | -| [`GET_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_get-format) | 返回满足日期格式的字符串 | -| [`HOUR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_hour) | 提取日期/时间表达式中的小时部分 | -| [`LAST_DAY`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_last-day) | 返回参数中月份的最后一天 | -| [`LOCALTIME()`, `LOCALTIME`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_localtime) | 与 NOW() 同义 | -| [`LOCALTIMESTAMP`, `LOCALTIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_localtimestamp) | 与 NOW() 同义 | -| [`MAKEDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_makedate) | 根据给定的年份和一年中的天数生成一个日期 | -| [`MAKETIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_maketime) | 根据给定的时、分、秒生成一个时间 | -| [`MICROSECOND()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_microsecond) | 返回参数的微秒部分| -| [`MINUTE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_minute) | 返回参数的分钟部分| -| [`MONTH()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_month) | 返回参数的月份部分| -| [`MONTHNAME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_monthname) | 返回参数的月份名称| -| [`NOW()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_now) | 返回当前日期和时间| -| [`PERIOD_ADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_period-add) | 在年-月表达式上添加一段时间(数个月)| -| [`PERIOD_DIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_period-diff) | 返回间隔的月数| -| [`QUARTER()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_quarter) | 返回参数对应的季度(1-4) | -| [`SEC_TO_TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_sec-to-time) | 将秒数转化为 'HH:MM:SS' 的格式| -| [`SECOND()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_second) | 返回秒数(0-59) | -| [`STR_TO_DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_str-to-date) | 将字符串转化为日期| -| [`SUBDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_subdate) | 当传入三个参数时作为 DATE_SUB() 的同义| -| [`SUBTIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_subtime) | 从一个时间中减去一段时间 | -| [`SYSDATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_sysdate) | 返回该方法执行时的时间| -| [`TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time) | 返回参数的时间表达式部分 | -| [`TIME_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time-format) | 格式化时间| -| [`TIME_TO_SEC()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_time-to-sec) | 返回参数对应的秒数| -| [`TIMEDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timediff) | 返回时间间隔 | -| [`TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestamp) | 传入一个参数时候,该方法返回日期或日期/时间表达式, 传入两个参数时候, 返回参数的和 | -| [`TIMESTAMPADD()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestampadd) | 在日期/时间表达式上增加一段时间间隔 | -| [`TIMESTAMPDIFF()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_timestampdiff) | 从日期/时间表达式中减去一段时间间隔 | -| [`TO_DAYS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_to-days) | 将参数转化对应的天数(从第 0 年开始) | -| [`TO_SECONDS()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_to-seconds) | 将日期或日期/时间参数转化为秒数(从第 0 年开始) | -| [`UNIX_TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_unix-timestamp) | 返回一个 Unix 时间戳| -| [`UTC_DATE()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-date) | 返回当前的 UTC 日期 | -| [`UTC_TIME()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-time) | 返回当前的 UTC 时间 | -| [`UTC_TIMESTAMP()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_utc-timestamp) | 返回当前的 UTC 日期和时间| -| [`WEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_week) | 返回参数所在的一年中的星期数 | -| [`WEEKDAY()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_weekday) | 返回星期下标 | -| [`WEEKOFYEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_weekofyear) | 返回参数在日历中对应的一年中的星期数 | -| [`YEAR()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_year) | 返回参数对应的年数| -| [`YEARWEEK()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_yearweek) | 返回年数和星期数 | diff --git a/v3.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md b/v3.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md deleted file mode 100644 index 34b2a6bbd8fa..000000000000 --- a/v3.1/reference/sql/functions-and-operators/encryption-and-compression-functions.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: 加密和压缩函数 -category: reference ---- - -# 加密和压缩函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[加密和压缩函数](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -|:-----------|:----------------------------| -| [`MD5()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_md5)                                                             | 计算字符串的 MD5 校验和       | -| [`PASSWORD()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_password) | 计算并返回密码字符串 | -| [`RANDOM_BYTES()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_random-bytes) | 返回随机字节向量 | -| [`SHA1()`, `SHA()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_sha1)                                                   | 计算 SHA-1 160 位校验和               | -| [`SHA2()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_sha2)                                                           | 计算 SHA-2 校验和                       | -| [`AES_DECRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_aes-decrypt) | 使用 AES 解密 | -| [`AES_ENCRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_aes-encrypt) | 使用 AES 加密 | -| [`COMPRESS()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_compress) | 返回经过压缩的二进制字符串 | -| [`UNCOMPRESS()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_uncompress) | 解压缩字符串 | -| [`UNCOMPRESSED_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/encryption-functions.html#function_uncompressed-length)                             | 返回字符串解压后的长度 | -| [`CREATE_ASYMMETRIC_PRIV_KEY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-asymmetric-priv-key) | 创建私钥 | -| [`CREATE_ASYMMETRIC_PUB_KEY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-asymmetric-pub-key) | 创建公钥 | -| [`CREATE_DH_PARAMETERS()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-dh-parameters) | 创建 DH 共享密钥 | -| [`CREATE_DIGEST()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_create-digest) | 从字符串创建摘要 | -| [`ASYMMETRIC_DECRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-decrypt) | 使用公钥或私钥解密密文 | -| [`ASYMMETRIC_DERIVE()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-derive) | 从非对称密钥导出对称密钥 | -| [`ASYMMETRIC_ENCRYPT()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-encrypt) | 使用公钥或私钥加密明文 | -| [`ASYMMETRIC_SIGN()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-sign) | 从摘要创建签名 | -| [`ASYMMETRIC_VERIFY()`](https://dev.mysql.com/doc/refman/5.7/en/enterprise-encryption-functions.html#function_asymmetric-verify) | 验证签名字符串是否匹配摘要字符串 | - -## 不支持的函数 - -* `DES_DECRYPT()`、`DES_ENCRYPT()`、`OLD_PASSWORD()` 和 `ENCRYPT()`：这些函数在 MySQL 5.7 中被废弃，并且已在 MySQL 8.0 中移除。 -* `VALIDATE_PASSWORD_STRENGTH()` 函数。 -* 只在 MySQL 企业版中支持的函数。见 [Issue #2632](https://github.com/pingcap/tidb/issues/2632)。 \ No newline at end of file diff --git a/v3.1/reference/sql/functions-and-operators/expressions-pushed-down.md b/v3.1/reference/sql/functions-and-operators/expressions-pushed-down.md deleted file mode 100644 index eb1c13c2f542..000000000000 --- a/v3.1/reference/sql/functions-and-operators/expressions-pushed-down.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: 下推到 TiKV 的表达式列表 -summary: TiDB 中下推到 TiKV 的表达式列表及相关设置。 -category: reference ---- - -# 下推到 TiKV 的表达式列表 - -当 TiDB 从 TiKV 中读取数据的时候，TiDB 会尽量下推一些表达式运算到 TiKV 中，从而减少数据传输量以及 TiDB 单一节点的计算压力。本文将介绍 TiDB 已支持下推的表达式，以及如何禁止下推特定表达式。 - -## 已支持下推的表达式列表 - -| 表达式分类 | 具体操作 | -| :-------------- | :------------------------------------- | -| [逻辑运算](/v3.1/reference/sql/functions-and-operators/operators.md#逻辑操作符) | AND (&&), OR (||), NOT (!) | -| [比较运算](/v3.1/reference/sql/functions-and-operators/operators.md#比较方法和操作符) | <, <=, =, != (<>), >, >=, [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to), [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in), IS NULL, LIKE, IS TRUE, IS FALSE, [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | -| [数值运算](/v3.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md) | +, -, *, /, [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs), [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil), [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling), [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | -| [控制流运算](/v3.1/reference/sql/functions-and-operators/control-flow-functions.md) | [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case), [`IF()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_if), [`IFNULL()`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#function_ifnull) | -| [JSON运算](/v3.1/reference/sql/functions-and-operators/json-functions.md) | [JSON_TYPE(json_val)][json_type],
[JSON_EXTRACT(json_doc, path[, path] ...)][json_extract],
[JSON_UNQUOTE(json_val)][json_unquote],
[JSON_OBJECT(key, val[, key, val] ...)][json_object],
[JSON_ARRAY([val[, val] ...])][json_array],
[JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge],
[JSON_SET(json_doc, path, val[, path, val] ...)][json_set],
[JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert],
[JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace],
[JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | -| [日期运算](/v3.1/reference/sql/functions-and-operators/date-and-time-functions.md) | [`DATE_FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-functions.html#function_date-format) | - -## 禁止特定表达式下推 - -当函数的计算过程由于下推而出现异常时，可通过黑名单功能禁止其下推来快速恢复业务。具体而言，你可以将上述支持的函数或运算符名加入黑名单 `mysql.expr_pushdown_blacklist` 中，以禁止特定表达式下推。 - -### 加入黑名单 - -执行以下步骤，可将一个或多个函数或运算符加入黑名单： - -1. 向 `mysql.expr_pushdown_blacklist` 插入对应的函数名或运算符名。 -2. 执行 `admin reload expr_pushdown_blacklist;`。 - -### 移出黑名单 - -执行以下步骤，可将一个或多个函数及运算符移出黑名单： - -1. 从 `mysql.expr_pushdown_blacklist` 表中删除对应的函数名或运算符名。 -2. 执行 `admin reload expr_pushdown_blacklist;`。 - -### 黑名单用法示例 - -以下示例首先将运算符 `<` 及 `>` 加入黑名单，然后将运算符 `>` 从黑名单中移出。 - -黑名单是否生效可以从 `explain` 结果中进行观察（参见[如何理解 `explain` 结果](/v3.1/reference/performance/understanding-the-query-execution-plan.md)）。 - -```sql -tidb> create table t(a int); -Query OK, 0 rows affected (0.01 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+---------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+------------------------------------------------------------+ -| TableReader_7 | 0.00 | root | data:Selection_6 | -| └─Selection_6 | 0.00 | cop | gt(test.t.a, 2), lt(test.t.a, 2) | -| └─TableScan_5 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+------------------------------------------------------------+ -3 rows in set (0.00 sec) - -tidb> insert into mysql.expr_pushdown_blacklist values('<'), ('>'); -Query OK, 2 rows affected (0.00 sec) -Records: 2 Duplicates: 0 Warnings: 0 - -tidb> admin reload expr_pushdown_blacklist; -Query OK, 0 rows affected (0.00 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+---------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+------------------------------------------------------------+ -| Selection_5 | 8000.00 | root | gt(test.t.a, 2), lt(test.t.a, 2) | -| └─TableReader_7 | 10000.00 | root | data:TableScan_6 | -| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+------------------------------------------------------------+ -3 rows in set (0.00 sec) - -tidb> delete from mysql.expr_pushdown_blacklist where name = '>'; -Query OK, 1 row affected (0.00 sec) - -tidb> admin reload expr_pushdown_blacklist; -Query OK, 0 rows affected (0.00 sec) - -tidb> explain select * from t where a < 2 and a > 2; -+-----------------------+----------+------+------------------------------------------------------------+ -| id | count | task | operator info | -+-----------------------+----------+------+------------------------------------------------------------+ -| Selection_5 | 2666.67 | root | lt(test.t.a, 2) | -| └─TableReader_8 | 3333.33 | root | data:Selection_7 | -| └─Selection_7 | 3333.33 | cop | gt(test.t.a, 2) | -| └─TableScan_6 | 10000.00 | cop | table:t, range:[-inf,+inf], keep order:false, stats:pseudo | -+-----------------------+----------+------+------------------------------------------------------------+ -4 rows in set (0.00 sec) -``` - -> **注意：** -> -> - `admin reload expr_pushdown_blacklist` 只对执行该 SQL 语句的 TiDB server 生效。若需要集群中所有 TiDB server 生效，需要在每台 TiDB server 上执行该 SQL 语句。 -> - 表达式黑名单功能在 v3.0.0 及以上版本中支持。 -> - 在 v3.0.3 及以下版本中，不支持将某些运算符的原始名称文本（如 ">"、"+" 和 "is null"）加入黑名单中，部分运算符在黑名单中需使用别名。已支持下推的表达式中，别名与原始名不同的运算符见下表（区分大小写）。 - -| 运算符原始名称 | 运算符别名 | -| :-------- | :---------- | -| < | lt | -| > | gt | -| <= | le | -| >= | ge | -| = | eq | -| != | ne | -| <> | ne | -| <=> | nulleq | -| | | bitor | -| && | bitand| -| || | or | -| ! | not | -| in | in | -| + | plus| -| - | minus | -| * | mul | -| / | div | -| DIV | intdiv| -| IS NULL | isnull | -| IS TRUE | istrue | -| IS FALSE | isfalse | - -[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract -[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path -[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path -[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote -[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type -[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set -[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert -[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace -[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove -[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge -[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve -[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object -[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array -[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys -[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length -[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid -[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote -[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains -[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path -[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg -[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/v3.1/reference/sql/functions-and-operators/information-functions.md b/v3.1/reference/sql/functions-and-operators/information-functions.md deleted file mode 100644 index b3ec39c0d40a..000000000000 --- a/v3.1/reference/sql/functions-and-operators/information-functions.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 信息函数 -category: reference ---- - -# 信息函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[信息函数](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -| ------ | ---------------------------------------- | -| [`BENCHMARK()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_benchmark) | 循环执行一个表达式 | -| [`CONNECTION_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_connection-id) | 返回当前连接的连接 ID (线程 ID) | -| [`CURRENT_USER()`, `CURRENT_USER`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_current-user) | 返回当前用户的用户名和主机名 | -| [`DATABASE()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_database) | 返回默认(当前)的数据库名 | -| [`FOUND_ROWS()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_found-rows) | 该函数返回对于一个包含 LIMIT 的 SELECT 查询语句，在不包含 LIMIT 的情况下回返回的记录数 | -| [`LAST_INSERT_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_last-insert-id) | 返回最后一条 INSERT 语句中自增列的值 | -| [`ROW_COUNT()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_row-count) | 影响的行数 | -| [`SCHEMA()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_schema) | 与 DATABASE() 同义 | -| [`SESSION_USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_session-user) | 与 USER() 同义 | -| [`SYSTEM_USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_system-user) | 与 USER() 同义 | -| [`USER()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_user) | 返回客户端提供的用户名和主机名 | -| [`VERSION()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_version) | 返回当前 MySQL 服务器的版本信息 | -| `TIDB_VERSION()` | 返回当前 TiDB 服务器的版本信息 | - -## 不支持的函数 - -* `CHARSET()` -* `COERCIBILITY()` -* `COLLATION()` diff --git a/v3.1/reference/sql/functions-and-operators/json-functions.md b/v3.1/reference/sql/functions-and-operators/json-functions.md deleted file mode 100644 index d23f5e6f2b82..000000000000 --- a/v3.1/reference/sql/functions-and-operators/json-functions.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: JSON 函数及语法糖 -category: reference ---- - -# JSON 函数及语法糖 - -TiDB 支持 MySQL 5.7 GA 版本发布的大多数 JSON 函数。MySQL 5.7 发布后，又增加了更多 JSON 函数，TiDB 并未支持所有这些函数（参见[未支持的函数](#未支持的函数)）。 - -## 创建 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| ------------------------------------------------------------------ | ---------------------------------------------------------- | -| [JSON_ARRAY([val[, val] ...])][json_array] | 根据一系列元素创建一个 JSON 文档 | -| [JSON_OBJECT(key, val[, key, val] ...)][json_object] | 根据一系列 K/V 对创建一个 JSON 文档 | -| [JSON_QUOTE(string)][json_quote] | 返回一个字符串，该字符串为带引号的 JSON 值 | - -## 搜索 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| ------------------------------------------------------------------ | ---------------------------------------------------------- | -| [JSON_CONTAINS(target, candidate[, path])][json_contains] | 通过返回 1 或 0 来表示目标 JSON 文档中是否包含给定的 candidate JSON 文档 | -| [JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)][json_contains_path] | 通过返回 0 或 1 来表示一个 JSON 文档在给定路径是否包含数据 | -| [JSON_EXTRACT(json_doc, path[, path] ...)][json_extract] | 从 JSON 文档中解出某一路径对应的子文档 | -| [->][json_short_extract] | 返回执行路径后面的 JSON 列的值；`JSON_EXTRACT(doc, path_literal)` 的语法糖 | -| [->>][json_short_extract_unquote] | 返回执行路径后面的 JSON 列的值和转义后的结果； `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))` 的语法糖 | -| [JSON_KEYS(json_doc[, path])][json_keys] | 返回从 JSON 对象的顶级值作为 JSON array 的键，如果给定了路径参数，则从选定路径中获取顶级键 | - -## 修改 JSON 值的函数 - -| 函数及语法糖 | 功能描述 | -| --------------------------------- | ----------- | -| [JSON_INSERT(json_doc, path, val[, path, val] ...)][json_insert] | 在 JSON 文档中在某一路径下插入子文档 | -| [JSON_MERGE(json_doc, json_doc[, json_doc] ...)][json_merge] | 已废弃的 `JSON_MERGE_PRESERVE` 别名 | -| [JSON_MERGE_PRESERVE(json_doc, json_doc[, json_doc] ...)][json_merge_preserve] | 将两个或多个 JSON 文档合并成一个文档，并返回合并结果 | -| [JSON_REMOVE(json_doc, path[, path] ...)][json_remove] | 移除 JSON 文档中某一路径下的子文档 | -| [JSON_REPLACE(json_doc, path, val[, path, val] ...)][json_replace] | 替换 JSON 文档中的某一路径下的子文档 | -| [JSON_SET(json_doc, path, val[, path, val] ...)][json_set] | 在 JSON 文档中为某一路径设置子文档 | -| [JSON_UNQUOTE(json_val)][json_unquote] | 去掉 JSON 值外面的引号，返回结果为字符串 | - -## 返回 JSON 值属性的函数 - -| 函数及语法糖 | 功能描述 | -| --------------------------------- | ----------- | -| [JSON_DEPTH(json_doc)][json_depth] | 返回 JSON 文档的最大深度 | -| [JSON_LENGTH(json_doc[, path])][json_length] | 返回 JSON 文档的长度；如果路径参数已定，则返回该路径下值的长度 | -| [JSON_TYPE(json_val)][json_type] | 检查某 JSON 文档内部内容的类型 | - -## 未支持的函数 - -TiDB 暂未支持以下 JSON 函数。相关进展参见 [TiDB #7546](https://github.com/pingcap/tidb/issues/7546): - -* `JSON_APPEND` 及其别名 `JSON_ARRAY_APPEND` -* `JSON_ARRAY_INSERT` -* `JSON_DEPTH` -* `JSON_MERGE_PATCH` -* `JSON_PRETTY` -* `JSON_SEARCH` -* `JSON_STORAGE_SIZE` -* `JSON_VALID` -* `JSON_ARRAYAGG` -* `JSON_OBJECTAGG` - -[json_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-extract -[json_short_extract]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-column-path -[json_short_extract_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#operator_json-inline-path -[json_unquote]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-unquote -[json_type]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-type -[json_set]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-set -[json_insert]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-insert -[json_replace]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-replace -[json_remove]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-remove -[json_merge]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge -[json_merge_preserve]: https://dev.mysql.com/doc/refman/5.7/en/json-modification-functions.html#function_json-merge-preserve -[json_object]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-object -[json_array]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-array -[json_keys]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-keys -[json_length]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-length -[json_valid]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-valid -[json_quote]: https://dev.mysql.com/doc/refman/5.7/en/json-creation-functions.html#function_json-quote -[json_contains]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains -[json_contains_path]: https://dev.mysql.com/doc/refman/5.7/en/json-search-functions.html#function_json-contains-path -[json_arrayagg]: https://dev.mysql.com/doc/refman/5.7/en/group-by-functions.html#function_json-arrayagg -[json_depth]: https://dev.mysql.com/doc/refman/5.7/en/json-attribute-functions.html#function_json-depth diff --git a/v3.1/reference/sql/functions-and-operators/miscellaneous-functions.md b/v3.1/reference/sql/functions-and-operators/miscellaneous-functions.md deleted file mode 100644 index 6d6c68fd6fc2..000000000000 --- a/v3.1/reference/sql/functions-and-operators/miscellaneous-functions.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: 其他函数 -category: reference ---- - -# 其他函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[其他函数](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -|:------|:-----------| -| [`ANY_VALUE()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_any-value) | 在 `ONLY_FULL_GROUP_BY` 模式下，防止带有 `GROUP BY` 的语句报错 | -| [`DEFAULT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_default) | 返回表的某一列的默认值 | -| [`INET_ATON()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet-aton) | 将 IP 地址转换为数值 | -| [`INET_NTOA()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet-ntoa) | 将数值转换为 IP 地址 | -| [`INET6_ATON()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet6-aton) | 将 IPv6 地址转换为数值 | -| [`INET6_NTOA()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_inet6-ntoa) | 将数值转换为 IPv6 地址 | -| [`IS_IPV4()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4) | 判断参数是否为 IPv4 地址 | -| [`IS_IPV4_COMPAT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4-compat) | 判断参数是否为兼容 IPv4 的地址 | -| [`IS_IPV4_MAPPED()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv4-mapped) | 判断参数是否为 IPv4 映射的地址 | -| [`IS_IPV6()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_is-ipv6) | 判断参数是否为 IPv6 地址 | -| [`NAME_CONST()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_name-const) | 可以用于重命名列名 | -| [`SLEEP()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_sleep) | 让语句暂停执行几秒时间 | -| [`UUID()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_uuid) | 返回一个通用唯一识别码 (UUID) | -| [`VALUES()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_values) | 定义 `INSERT` 语句使用的值 | - -## 不支持的函数 - -| 函数名 | 功能描述 | -|:------|:-----------| -| [`GET_LOCK()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock) | 获取命名锁，详见 [TiDB #10929](https://github.com/pingcap/tidb/issues/10929) | -| [`RELEASE_LOCK()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_release-lock) | 释放命名锁，详见 [TiDB #10929](https://github.com/pingcap/tidb/issues/10929) | -| [`UUID_SHORT()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_uuid-short) | 基于特定假设提供唯一的 UUID，目前这些假设在 TiDB 中不存在，详见 [TiDB #4620](https://github.com/pingcap/tidb/issues/4620) | -| [`MASTER_WAIT_POS()`](https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_master-pos-wait) | 与 MySQL 同步相关 | \ No newline at end of file diff --git a/v3.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md b/v3.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md deleted file mode 100644 index afd6772b2ad4..000000000000 --- a/v3.1/reference/sql/functions-and-operators/numeric-functions-and-operators.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 数值函数与操作符 -category: reference ---- - -# 数值函数与操作符 - -TiDB 支持使用 MySQL 5.7 中提供的所有[数值函数与操作符](https://dev.mysql.com/doc/refman/5.7/en/numeric-functions.html)。 - -## 算术操作符 - -| 操作符名 | 功能描述 | -|:-------------|:--------------------------------| -| [`+`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_plus) | 加号 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_minus) | 减号 | -| [`*`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_times) | 乘号 | -| [`/`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_divide) | 除号 | -| [`DIV`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_div) | 整数除法 | -| [`%`, `MOD`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod) | 模运算，取余 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_unary-minus) | 更改参数符号 | - -## 数学函数 - -| 函数名 | 功能描述 | -|:----------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| -| [`POW()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_pow) | 返回参数的指定乘方的结果值 | -| [`POWER()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_power) | 返回参数的指定乘方的结果值 | -| [`EXP()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_exp) | 返回 e（自然对数的底）的指定乘方后的值 | -| [`SQRT()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sqrt) | 返回非负数的二次方根 | -| [`LN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ln) | 返回参数的自然对数 | -| [`LOG()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log) | 返回第一个参数的自然对数 | -| [`LOG2()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log2) | 返回参数以 2 为底的对数 | -| [`LOG10()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_log10) | 返回参数以 10 为底的对数 | -| [`PI()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_pi) | 返回 pi 的值 | -| [`TAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_tan) | 返回参数的正切值 | -| [`COT()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_cot) | 返回参数的余切值 | -| [`SIN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sin) | 返回参数的正弦值 | -| [`COS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_cos) | 返回参数的余弦值 | -| [`ATAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_atan) | 返回参数的反正切值 | -| [`ATAN2(), ATAN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_atan2) | 返回两个参数的反正切值 | -| [`ASIN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_asin) | 返回参数的反正弦值 | -| [`ACOS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_acos) | 返回参数的反余弦值 | -| [`RADIANS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_radians) | 返回由度转化为弧度的参数 | -| [`DEGREES()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_degrees) | 返回由弧度转化为度的参数 | -| [`MOD()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_mod) | 返回余数 | -| [`ABS()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_abs) | 返回参数的绝对值 | -| [`CEIL()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceil) | 返回不小于参数的最小整数值 | -| [`CEILING()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_ceiling) | 返回不小于参数的最小整数值 | -| [`FLOOR()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_floor) | 返回不大于参数的最大整数值 | -| [`ROUND()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_round) | 返回参数最近似的整数或指定小数位数的数值 | -| [`RAND()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_rand) | 返回一个随机浮点值 | -| [`SIGN()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_sign) | 返回参数的符号 | -| [`CONV()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_conv) | 不同数基间转换数字，返回数字的字符串表示 | -| [`TRUNCATE()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_truncate) | 返回被舍位至指定小数位数的数字 | -| [`CRC32()`](https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html#function_crc32)           | 计算循环冗余码校验值并返回一个 32 位无符号值                     | diff --git a/v3.1/reference/sql/functions-and-operators/operators.md b/v3.1/reference/sql/functions-and-operators/operators.md deleted file mode 100644 index 5873bd446bf4..000000000000 --- a/v3.1/reference/sql/functions-and-operators/operators.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: 操作符 -category: reference ---- - -# 操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`AND`, &&](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_and) | 逻辑与 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-equal) | 赋值 (可用于 [`SET`](https://dev.mysql.com/doc/refman/5.7/en/set-variable.html) 语句中, 或用于 [`UPDATE`](https://dev.mysql.com/doc/refman/5.7/en/update.html) 语句的 `SET` 中 ) | -| [`:=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-value) | 赋值 | -| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_between) | 判断值满足范围 | -| [`BINARY`](https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#operator_binary) | 将一个字符串转换为一个二进制字符串 | -| [&](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-and) | 位与 | -| [~](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-invert) | 位非 | -| [`\|`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-or) | 位或 | -| [`^`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_bitwise-xor) | 按位异或 | -| [`CASE`](https://dev.mysql.com/doc/refman/5.7/en/control-flow-functions.html#operator_case) | case 操作符 | -| [`DIV`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_div) | 整数除 | -| [`/`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_divide) | 除法 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal) | 相等比较 | -| [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to) | 空值安全型相等比较 | -| [`>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than) | 大于 | -| [`>=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than-or-equal) | 大于或等于 | -| [`IS`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is) | 判断一个值是否等于一个布尔值 | -| [`IS NOT`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not) | 判断一个值是否不等于一个布尔值 | -| [`IS NOT NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not-null) | 非空判断 | -| [`IS NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-null) | 空值判断 | -| [`<<`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_left-shift) | 左移 | -| [`<`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than) | 小于 | -| [`<=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than-or-equal) | 小于或等于 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 简单模式匹配 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_minus) | 减 | -| [`%`, `MOD`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod) | 求余 | -| [`NOT`, `!`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_not) | 取反 | -| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-between) | 判断值是否不在范围内 | -| [`!=`, `<>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-equal) | 不等于 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 不符合简单模式匹配 | -| [`NOT REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_not-regexp) | 不符合正则表达式模式匹配 | -| [`\|\|`, `OR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_or) | 逻辑或 | -| [`+`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_plus) | 加 | -| [`REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 使用正则表达式进行模式匹配 | -| [`>>`](https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html#operator_right-shift) | 右移 | -| [`RLIKE`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | REGEXP 同义词 | -| [`*`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_times) | 乘 | -| [`-`](https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_unary-minus) | 取反符号 | -| [`XOR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_xor) | 逻辑亦或 | - -## 操作符优先级 - -操作符优先级显示在以下列表中，从最高优先级到最低优先级。同一行显示的操作符具有相同的优先级。 - -```sql -INTERVAL -BINARY -! -- (unary minus), ~ (unary bit inversion) -^ -*, /, DIV, %, MOD --, + -<<, >> -& -| -= (comparison), <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN -BETWEEN, CASE, WHEN, THEN, ELSE -NOT -AND, && -XOR -OR, || -= (assignment), := -``` - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/operator-precedence.html). - -## 比较方法和操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_between) | 判断值是否在范围内 | -| [`COALESCE()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_coalesce) | 返回第一个非空值 | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal) | 相等比较 | -| [`<=>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_equal-to) | 空值安全型相等比较 | -| [`>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than) | 大于 | -| [`>=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_greater-than-or-equal) | 大于或等于 | -| [`GREATEST()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_greatest) | 返回最大值 | -| [`IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_in) | 判断值是否在一个值的集合内 | -| [`INTERVAL()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_interval) | 返回一个小于第一个参数的参数的下标 | -| [`IS`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is) | 判断是否等于一个布尔值 | -| [`IS NOT`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not) | 判断是否不等于一个布尔值 | -| [`IS NOT NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-not-null) | 非空判断 | -| [`IS NULL`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_is-null) | 空值判断 | -| [`ISNULL()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_isnull) | 判断参数是否为空 | -| [`LEAST()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_least) | 返回最小值 | -| [`<`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than) | 小于 | -| [`<=`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_less-than-or-equal) | 小于或等于 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 简单模式匹配 | -| [`NOT BETWEEN ... AND ...`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-between) | 判断值是否不在范围内 | -| [`!=`, `<>`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#operator_not-equal) | 不等于 | -| [`NOT IN()`](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html#function_not-in) | 判断值是否不在一个值的集合内 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 不满足简单模式匹配 | -| [`STRCMP()`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#function_strcmp) | 比较两个字符串 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/comparison-operators.html). - -## 逻辑操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`AND`, &&](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_and) | 逻辑与 | -| [`NOT`, `!`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_not) | 逻辑非 | -| [`\|\|`, `OR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_or) | 逻辑或 | -| [`XOR`](https://dev.mysql.com/doc/refman/5.7/en/logical-operators.html#operator_xor) | 逻辑亦或 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/group-by-handling.html). - -## 赋值操作符 - -| 操作符名 | 功能描述 | -| ------- | -------------------------------- | -| [`=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-equal) | 赋值 (可用于 [`SET`](https://dev.mysql.com/doc/refman/5.7/en/set-variable.html) 语句中, 或用于 [`UPDATE`](https://dev.mysql.com/doc/refman/5.7/en/update.html) 语句的 `SET` 中 ) | -| [`:=`](https://dev.mysql.com/doc/refman/5.7/en/assignment-operators.html#operator_assign-value) | 赋值 | - -详情参见 [这里](https://dev.mysql.com/doc/refman/5.7/en/group-by-functional-dependence.html). diff --git a/v3.1/reference/sql/functions-and-operators/precision-math.md b/v3.1/reference/sql/functions-and-operators/precision-math.md deleted file mode 100644 index dc6953bb5a23..000000000000 --- a/v3.1/reference/sql/functions-and-operators/precision-math.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: 精度数学 -category: reference ---- - -# 精度数学 - -TiDB 中精度数学计算与 MySQL 中基本一致, 详情请参见: [Precision Math](https://dev.mysql.com/doc/refman/5.7/en/precision-math.html). - -- 数值类型 -- DECIMAL 数据类型的特性 - -## 数值类型 - -精确数值运算的范围包括精确值数据类型(整型和 DECIMAL 类型), 以及精确值数字字面量. 近似值数据类型和近似值数字字面量被作为浮点数来处理. - -精确值数字字面量包含整数部分或小数部分, 或二者都包含. 精确值数字字面量可以包含符号位. 例如: 1, .2, 3.4, -5, -6.78, +9.10. - -近似值数字字面量以一个包含尾数和指数的科学计数法表示(基数为 10). 其中尾数和指数可以分别或同时带有符号位. 例如: 1.2E3, 1.2E-3, -1.2E3, -1.2E-3. - -两个看起来相似的数字可能会被以不同的方式进行处理. 例如, 2.34 是精确值(定点数), 而 2.3E0 是近似值(浮点数). - -DECIMAL 数据类型是定点数类型, 其运算是精确计算. FLOAT 和 DOUBLE 数据类型是浮点类型, 其运算是近似计算. - -## DECIMAL 数据类型的特性 - -本节讨论 DECIMAL 数据类型的特性, 主要涉及以下几点: - -1. 最大位数 -2. 存储格式 -3. 存储要求 - -DECIMAL 列的声明语法为 DECIMAL(M, D). 其中参数值意义及其范围如下: - -- M 表示最大的数字位数 (精度). 1<= M <= 65. -- D 表示小数点右边数字的位数 (标度). 1 <= D <= 30 且 不大于 M. - -M 的最大值 65 表示 DECIMAL 值的计算精确到 65 位数字. 该精度同样适用于其精确值字面量. - -DECIMAL 列的值采用二进制进行存储, 其将每 9 位十进制数字包装成 4 个字节. 其中整数和小数部分分别确定所需的存储空间. 如果数字位数为 9 的倍数, 则每 9 位十进制数字各采用 4 个字节进行存储, 对于剩余不足 9 位的数字, 所需的存储空间如下表所示. - -| 剩余数字位数 | 存储所需字节数 | -| --- | --- | -| 0 | 0 | -| 1–2 | 1 | -| 3–4 | 2 | -| 5–6 | 3 | -| 7–9 | 4 | - -例如, 定义类型为 DECIMAL(18, 9) 的列, 其小数点两侧均各包含 9 位十进制数字, 因此, 分别需要 4 个字节的存储空间. 定义类型为 DECIMAL(20, 6) 的列, 其小数部分包含 6 位十进制数字, 整数部分包含 14 位十进制数字. 整数部分中 9 位数字需要 4 个字节进行存储, 其余 5 位数字需要 3 个字节进行存储. 小数部分 6 位数字需要 3 个字节进行存储. - -DECIMAL 列不存储前导的字符 `+` 或字符 `-` 或数字 `0`. 如果将 +0003.1 插入到 DECIMAL(5, 1) 列中, 则将其存储为3.1. 对于负数, 不存储字符 `-` 的字面值. - -DECIMAL 列不允许插入大于列定义的隐含范围的值. 例如, DECIMAL(3, 0) 列范围为 -999 到 999. DECIMAL(M, D) 列小数点左边部分最多支持 M-D 位数字. - -有关 DECIMAL 值的内部格式完整说明, 请参阅 TiDB 源码文件 [types/mydecimal.go](https://github.com/pingcap/tidb/blob/master/types/mydecimal.go). - -## 表达式计算 - -在涉及精度数学计算的表达式中，TiDB 会尽可能不做任何修改的使用每个输入的数值。比如：在计算比较函数时，参与运算的数字将不做任何改变。在严格 SQL 模式下，向一个数据列插入一个值时，如果该值处于这一列的值域范围内，这个值将直接不做任何修改的直接插入进去，提取这个值的时候，取得的值和插入的值将会是同一个值。当处于非严格 SQL 模式时，TiDB 会允许数据插入过程中发生的数据截断。 - -处理数值类型表达式取决于这个表达式参数的具体值： - -* 当表达式参数中包含近似值时，这个表达式的结果也是近似值，TiDB 会使用浮点数对应的计算逻辑返回一个浮点数的结果 -* 当表达式参数中不包含任何近似值时（也就是说表达式的参数全部是精确值），如果某个精确值包含小数部分，TIDB 会对这个表达式使用 `DECIMAL` 对应的计算逻辑，返回一个 `DECIMAL` 的结果，精确到 65 位数字 -* 其他情况下，表达式只会包含整数参数，这个表达式的结果也是精确的，TiDB 会使用整数对应的计算逻辑返回一个整数结果，精度和 `BIGINT` 保持一致（64位） - -如果数值类型表达式中包含字符串参数，这些字符串参数将被转换成双精度浮点数，这个表达式的计算结果将是个近似值。 - -向一个数值类型列插入数据的具体行为会受到 SQL 模式的影响。接下来的讨论将围绕严格模式以及 `ERROR_FOR_DIVISION_BY_ZERO` 模式展开，如果要打开所有的限制，可以简单的使用 `TRADITIONAL` 模式，这个模式将同时使用严格模式以及 `ERROR_FOR_DIVISION_BY_ZERO` 模式： - -{{< copyable "sql" >}} - -```sql -SET sql_mode = 'TRADITIONAL'; -``` - -向一个具有精确值类型（`DECIMAL` 或者整数类型）的列插入数据时，如果插入的数据位于该列的值域范围内将使用该数据的精确值。如果该数据的小数部分太长，将会发生数值修约，这时会有 warning 产生，具体内容可以看"数值修约"。 - -如果该数据整数部分太长： - -* 如果没有开启严格模式，这个值会被截断并产生一个 warning -* 如果开启了严格模式，将会产生一个数据溢出的 error - -如果向一个数值类型列插入字符串，如果该字符串中包含非数值部分，TiDB 将这样做类型转换： - -* 在严格模式下，没有以数字开头的字符串（即使是一个空字符串）不能被被用作数字值并会返回一个 error 或者是 warning； -* 以数字开头的字符串可以被转换，不过末尾的非数字部分会被截断。如果被截断的部分包含的不全是空格，在严格模式下这回产生一个 error 或者 warning - -默认情况下，如果计算的过程中发生了除数是 0 的现象将会得到一个 `NULL` 结果，并且不会有 warning 产生。通过设置适当的 SQL 模式，除以 0 的操作可以被限制：当设置 `ERROR_FOR_DIVISION_BY_ZERO` SQL 模式时，TiDB 的行为是： - -* 如果设置了严格 SQL 模式，`INSERT` 和 `UPDATE` 的过程中如果发生了除以 0 的操作，正在进行的 `INSERT` 或者 `UPDATE` 操作会被禁止，并且会返回一个 error -* 如果没有设置严格 SQL 模式，除以 0 的操作仅会返回一个 warning - -假设我们有如下的 SQL 语句： - -{{< copyable "sql" >}} - -```sql -INSERT INTO t SET i = 1/0; -``` - -不同的 SQL 模式将会导致不同的结果如下： - -| `sql_mode` 的值 | 结果 | -| :--- | :--- | -| '' | 没有 warning，没有 error，i 被设为 NULL | -| strict | 没有 warning，没有 error，i 被设为 NULL | -| `ERROR_FOR_DIVISION_BY_ZERO` | 有 warning，没有 error，i 被设为 NULL | -| strict, `ERROR_FOR_DIVISION_BY_ZERO` | 有 error，插入失败 | - -## 数值修约 - -`round()` 函数的结果取决于他的参数是否是精确值： - -* 如果参数是精确值，`round()` 函数将使用四舍五入的规则 -* 如果参数是一个近似值，`round()` 表达式的结果可能和 MySQL 不太一样 - -{{< copyable "sql" >}} - -```sql -SELECT ROUND(2.5), ROUND(25E-1); -``` - -``` -+------------+--------------+ -| ROUND(2.5) | ROUND(25E-1) | -+------------+--------------+ -| 3 | 3 | -+------------+--------------+ -1 row in set (0.00 sec) -``` - -向一个 `DECIMAL` 或者整数类型列插入数据时，round 的规则将采用 [round half away from zero](https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero) 的方式： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t (d DECIMAL(10,0)); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t VALUES(2.5),(2.5E0); -``` - -``` -Query OK, 2 rows affected, 2 warnings (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT d FROM t; -``` - -``` -+------+ -| d | -+------+ -| 3 | -| 3 | -+------+ -2 rows in set (0.00 sec) -``` diff --git a/v3.1/reference/sql/functions-and-operators/reference.md b/v3.1/reference/sql/functions-and-operators/reference.md deleted file mode 100644 index 2ab42cf1e8bd..000000000000 --- a/v3.1/reference/sql/functions-and-operators/reference.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: 函数和操作符概述 -category: reference ---- - -# 函数和操作符概述 - -TiDB 中函数和操作符使用方法与 MySQL 基本一致，详情参见: [Functions and Operators](https://dev.mysql.com/doc/refman/5.7/en/functions.html)。 - -在 SQL 语句中，表达式可用于诸如 `SELECT` 语句的 `ORDER BY` 或 `HAVING` 子句，`SELECT`/`DELETE`/`UPDATE` 语句的 `WHERE` 子句，或 `SET` 语句之类的地方。 - -可使用字面值，列名，NULL，内置函数，操作符等来书写表达式。其中有些表达式下推到 TiKV 上执行，详见[下推到 TiKV 的表达式列表](/v3.1/reference/sql/functions-and-operators/expressions-pushed-down.md)。 \ No newline at end of file diff --git a/v3.1/reference/sql/functions-and-operators/string-functions.md b/v3.1/reference/sql/functions-and-operators/string-functions.md deleted file mode 100644 index 6ebc49116845..000000000000 --- a/v3.1/reference/sql/functions-and-operators/string-functions.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: 字符串函数 -category: reference ---- - -# 字符串函数 - -TiDB 支持使用 MySQL 5.7 中提供的大部分[字符串函数](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html)。 - -## 支持的函数 - -| 函数名 | 功能描述 | -|:----------|:-----------------------| -| [`ASCII()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ascii) | 返回最左字符的数值 | -| [`BIN()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_bin) | 返回一个数的二进制值的字符串表示 | -| [`BIT_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_bit-length) | 返回字符串的位长度 | -| [`CHAR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_char)    | 返回由整数的代码值所给出的字符组成的字符串 | -| [`CHAR_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_char-length) | 返回字符串的字符长度 | -| [`CHARACTER_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_character-length) | 与 `CHAR_LENGTH()` 功能相同 | -| [`CONCAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_concat) | 返回连接的字符串 | -| [`CONCAT_WS()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_concat-ws) | 返回由分隔符连接的字符串 | -| [`ELT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_elt) | 返回指定位置的字符串 | -| [`EXPORT_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_export-set) | 返回一个字符串，其中值位中设置的每个位，可以得到一个 on 字符串，而每个未设置的位，可以得到一个 off 字符串 | -| [`FIELD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_field) | 返回参数在后续参数中出现的第一个位置 | -| [`FIND_IN_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_find-in-set) | 返回第一个参数在第二个参数中出现的位置 | -| [`FORMAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_format) | 返回指定小数位数格式的数字 | -| [`FROM_BASE64()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_from-base64) | 解码 base-64 表示的字符串，并返回结果 | -| [`HEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_hex) | 返回一个十进制数或字符串值的 16 进制表示 | -| [`INSERT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_insert) | 在指定位置插入一个子字符串，最多不超过指定字符数 | -| [`INSTR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_instr) | 返回第一次出现的子字符串的索引 | -| [`LCASE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lcase) | 与 `LOWER()` 功能相同 | -| [`LEFT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_left) | 返回最左侧指定长度的字符 | -| [`LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_length) | 返回字符串长度，单位为字节 | -| [`LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_like) | 进行简单模式匹配 | -| [`LOCATE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_locate) | 返回第一次出现的子字符串的位置 | -| [`LOWER()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lower) | 返回全小写的参数 | -| [`LPAD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_lpad) | 返回字符串参数，左侧添加指定字符串 | -| [`LTRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ltrim) | 去掉前缀空格 | -| [`MAKE_SET()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_make-set) | 返回一组用逗号分隔的字符串，这些字符串的位数与给定的 bits 参数对应 | -| [`MID()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_mid) | 返回一个以指定位置开始的子字符串 | -| [`NOT LIKE`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#operator_not-like) | 否定简单模式匹配 | -| [`NOT REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_not-regexp) | `REGEXP` 的否定形式 | -| [`OCT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_oct) | 返回一个数值的八进制表示，形式为字符串 | -| [`OCTET_LENGTH()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_octet-length) | 与 `LENGTH()` 功能相同 | -| [`ORD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ord) | 返回该参数最左侧字符的字符编码 | -| [`POSITION()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_position) | 与 `LOCATE()` 功能相同 | -| [`QUOTE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_quote) | 使参数逃逸，为了在 SQL 语句中使用 | -| [`REGEXP`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 使用正则表达式匹配模式 | -| [`REPEAT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_repeat) | 以指定次数重复一个字符串 | -| [`REPLACE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_replace) | 替换所有出现的指定字符串 | -| [`REVERSE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_reverse) | 反转字符串里的所有字符 | -| [`RIGHT()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_right) | 返回指定数量的最右侧的字符 | -| [`RLIKE`](https://dev.mysql.com/doc/refman/5.7/en/regexp.html#operator_regexp) | 与 `REGEXP` 功能相同 | -| [`RPAD()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_rpad) | 以指定次数添加字符串 | -| [`RTRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_rtrim) | 去掉后缀空格 | -| [`SPACE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_space) | 返回指定数量的空格，形式为字符串 | -| [`STRCMP()`](https://dev.mysql.com/doc/refman/5.7/en/string-comparison-functions.html#function_strcmp) | 比较两个字符串 | -| [`SUBSTR()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substr) | 返回指定的子字符串 | -| [`SUBSTRING()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substring) | 返回指定的子字符串 | -| [`SUBSTRING_INDEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_substring-index) | 从一个字符串中返回指定出现次数的定界符之前的子字符串 | -| [`TO_BASE64()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_to-base64) | 返回转化为 base-64 表示的字符串参数 | -| [`TRIM()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_trim) | 去掉前缀和后缀空格 | -| [`UCASE()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_ucase) | 与 `UPPER()` 功能相同 | -| [`UNHEX()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_unhex) | 返回一个数的十六进制表示，形式为字符串 | -| [`UPPER()`](https://dev.mysql.com/doc/refman/5.7/en/string-functions.html#function_upper) | 参数转换为大写形式 | - -## 不支持的函数 - -* `LOAD_FILE()` -* `MATCH` -* `SOUNDEX()` -* `SOUNDS LIKE` -* `WEIGHT_STRING()` diff --git a/v3.1/reference/sql/functions-and-operators/type-conversion.md b/v3.1/reference/sql/functions-and-operators/type-conversion.md deleted file mode 100644 index 1a88da5de4da..000000000000 --- a/v3.1/reference/sql/functions-and-operators/type-conversion.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: 表达式求值的类型转换 -category: reference ---- - -# 表达式求值的类型转换 - -TiDB 中表达式求值的类型转换与 MySQL 基本一致，详情参见 [MySQL 表达式求值的类型转换](https://dev.mysql.com/doc/refman/5.7/en/type-conversion.html)。 diff --git a/v3.1/reference/sql/functions-and-operators/window-functions.md b/v3.1/reference/sql/functions-and-operators/window-functions.md deleted file mode 100644 index e9f47078d46f..000000000000 --- a/v3.1/reference/sql/functions-and-operators/window-functions.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 窗口函数 -category: reference ---- - -# 窗口函数 - -TiDB 中窗口函数的使用方法与 MySQL 8.0 基本一致，详情可参见 [MySQL 窗口函数](https://dev.mysql.com/doc/refman/8.0/en/window-functions.html)。由于窗口函数会使用一些保留关键字，可能导致原先可以正常执行的 SQL 语句在升级 TiDB 后无法被解析语法，此时可以将 `tidb_enable_window_function` 设置为 `0`，该参数的默认值为 `1`。 - -TiDB 支持的窗口函数如下所示： - -| 函数名 | 功能描述 | -| :-------------- | :------------------------------------- | -| [`CUME_DIST()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_cume-dist) | 返回一组值中的累积分布 | -| [`DENSE_RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_dense-rank) | 返回分区中当前行的排名，并且排名是连续的| -| [`FIRST_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_first-value) | 当前窗口中第一行的表达式值 | -| [`LAG()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_lag) | 分区中当前行前面第 N 行的表达式值| -| [`LAST_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_last-value) | 当前窗口中最后一行的表达式值 | -| [`LEAD()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_lead) | 分区中当前行后面第 N 行的表达式值 | -| [`NTH_VALUE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_nth-value) | 当前窗口中第 N 行的表达式值 | -| [`NTILE()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_ntile)| 将分区划分为 N 桶，为分区中的每一行分配桶号 | -| [`PERCENT_RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_percent-rank)|返回分区中小于当前行的百分比 | -| [`RANK()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_rank)| 返回分区中当前行的排名，排名可能不连续 | -| [`ROW_NUMBER()`](https://dev.mysql.com/doc/refman/8.0/en/window-function-descriptions.html#function_row-number)| 返回分区中当前行的编号 | diff --git a/v3.1/reference/sql/generated-columns.md b/v3.1/reference/sql/generated-columns.md deleted file mode 100644 index 265ea888ba68..000000000000 --- a/v3.1/reference/sql/generated-columns.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: 生成列 -category: reference ---- - -# 生成列 - -为了在功能上兼容 MySQL 5.7，TiDB 支持生成列 (generated column)。生成列的主要的作用之一：从 JSON 数据类型中解出数据，并为该数据建立索引。 - -## 使用 generated column 对 JSON 建索引 - -MySQL 5.7 及 TiDB 都不能直接为 JSON 类型的列添加索引，即**不支持**如下表结构： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - KEY (address_info) -); -``` - -为 JSON 列添加索引之前，首先必须抽取该列为 generated column。 - -以 `city` generated stored column 为例，你可以添加索引： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED, - KEY (city) -); -``` - -该表中，`city` 列是一个 **generated stored column**。顾名思义，此列由该表的其他列生成，对此列进行插入或更新操作时，并不能对之赋值。此列按其定义的表达式生成，并存储在数据库中，这样在读取此列时，就可以直接读取，不用再读取其依赖的 `address_info` 列后再计算得到。`city` 列的索引**存储在数据库中**，并使用和 `varchar(64)` 类的其他索引相同的结构。 - -可使用 generated stored column 的索引，以提高如下语句的执行速度： - -{{< copyable "sql" >}} - -```sql -SELECT name, id FROM person WHERE city = 'Beijing'; -``` - -如果 `$.city` 路径中无数据，则 `JSON_EXTRACT` 返回 `NULL`。如果想增加约束，`city` 列必须是 `NOT NULL`，则可按照以下方式定义 virtual column： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) STORED NOT NULL, - KEY (city) -); -``` - -`INSERT` 和 `UPDATE` 语句都会检查 virtual column 的定义。未通过有效性检测的行会返回错误： - -{{< copyable "sql" >}} - -```sql -INSERT INTO person (name, address_info) VALUES ('Morgan', JSON_OBJECT('Country', 'Canada')); -``` - -``` -ERROR 1048 (23000): Column 'city' cannot be null -``` - -## 使用 generated virtual column - -TiDB 也支持 generated virtual column，和 generated store column 不同的是，此列按需生成，并不存储在数据库中，也不占用内存空间，因而是**虚拟的**。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE person ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(255) NOT NULL, - address_info JSON, - city VARCHAR(64) AS (JSON_UNQUOTE(JSON_EXTRACT(address_info, '$.city'))) VIRTUAL -); -``` - -## 局限性 - -目前 JSON and generated column 有以下局限性： - -- 不能通过 `ALTER TABLE` 增加 `STORED` 存储方式的 generated column； -- 不能通过 `ALTER TABLE` 将 generated stored column 转换为普通列，也不能将普通列转换成 generated stored column； -- 不能通过 `ALTER TABLE` 修改 generated stored column 的**生成列表达式**； -- 并未支持所有的 [JSON 函数](/v3.1/reference/sql/functions-and-operators/json-functions.md)。 diff --git a/v3.1/reference/sql/language-structure/comment-syntax.md b/v3.1/reference/sql/language-structure/comment-syntax.md deleted file mode 100644 index 2c29acb67fb6..000000000000 --- a/v3.1/reference/sql/language-structure/comment-syntax.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: 注释语法 -category: reference ---- - -# 注释语法 - -TiDB 支持三种注释风格： - -* 用 `#` 注释一行 -* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。 -* 用 `/* */` 注释一块，可以注释多行。 - -例： - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; # 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1; -- 注释文字 -``` - -``` -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1 /* 这是行内注释文字 */ + 1; -``` - -``` -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+ - -> /* - /*> 这是一条 - /*> 多行注释 - /*> */ - -> 1; -``` - -``` -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1+1--1; -``` - -``` -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) -``` - -TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： - -``` -/*! Specific code */ -``` - -在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 - -例如：`SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...` - -在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` - -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。 - -还有一种注释会被当做是优化器 Hint 特殊对待： - -{{< copyable "sql" >}} - -```sql -SELECT /*+ hint */ FROM ...; -``` - -由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments - -TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/v3.1/reference/performance/optimizer-hints.md) - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 diff --git a/v3.1/reference/sql/language-structure/expression-syntax.md b/v3.1/reference/sql/language-structure/expression-syntax.md deleted file mode 100644 index d11a4ad8cf16..000000000000 --- a/v3.1/reference/sql/language-structure/expression-syntax.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: 表达式语法 -category: reference ---- - -# 表达式语法 (Expression Syntax) - -在 TiDB 中，以下规则是表达式的语法，你可以在 `parser/parser.y` 中找到定义。TiDB 的语法解析是基于 yacc 的。 - -``` -Expression: - singleAtIdentifier assignmentEq Expression - | Expression logOr Expression - | Expression "XOR" Expression - | Expression logAnd Expression - | "NOT" Expression - | Factor IsOrNotOp trueKwd - | Factor IsOrNotOp falseKwd - | Factor IsOrNotOp "UNKNOWN" - | Factor - -Factor: - Factor IsOrNotOp "NULL" - | Factor CompareOp PredicateExpr - | Factor CompareOp singleAtIdentifier assignmentEq PredicateExpr - | Factor CompareOp AnyOrAll SubSelect - | PredicateExpr - -PredicateExpr: - PrimaryFactor InOrNotOp '(' ExpressionList ')' - | PrimaryFactor InOrNotOp SubSelect - | PrimaryFactor BetweenOrNotOp PrimaryFactor "AND" PredicateExpr - | PrimaryFactor LikeOrNotOp PrimaryExpression LikeEscapeOpt - | PrimaryFactor RegexpOrNotOp PrimaryExpression - | PrimaryFactor - -PrimaryFactor: - PrimaryFactor '|' PrimaryFactor - | PrimaryFactor '&' PrimaryFactor - | PrimaryFactor "<<" PrimaryFactor - | PrimaryFactor ">>" PrimaryFactor - | PrimaryFactor '+' PrimaryFactor - | PrimaryFactor '-' PrimaryFactor - | PrimaryFactor '*' PrimaryFactor - | PrimaryFactor '/' PrimaryFactor - | PrimaryFactor '%' PrimaryFactor - | PrimaryFactor "DIV" PrimaryFactor - | PrimaryFactor "MOD" PrimaryFactor - | PrimaryFactor '^' PrimaryFactor - | PrimaryExpression - -PrimaryExpression: - Operand - | FunctionCallKeyword - | FunctionCallNonKeyword - | FunctionCallAgg - | FunctionCallGeneric - | Identifier jss stringLit - | Identifier juss stringLit - | SubSelect - | '!' PrimaryExpression - | '~' PrimaryExpression - | '-' PrimaryExpression - | '+' PrimaryExpression - | "BINARY" PrimaryExpression - | PrimaryExpression "COLLATE" StringName -``` diff --git a/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md b/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md deleted file mode 100644 index 75b1ea3ec5b7..000000000000 --- a/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md +++ /dev/null @@ -1,483 +0,0 @@ ---- -title: 关键字和保留字 -category: reference ---- - -# 关键字和保留字 - -关键字在 SQL 中有特殊的意义， 例如 `SELECT`，`UPDATE`，`DELETE`，在作为表名跟函数名的时候，需要特殊对待，例如作为表名，保留字需要被反引号包住： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE select (a INT); -``` - -``` -ERROR 1105 (HY000): line 0 column 19 near " (a INT)" (total length 27) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `select` (a INT); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -`BEGIN` 和 `END` 是关键字， 但不是保留字，所以不需要反引号： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `select` (BEGIN int, END int); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -有一种特殊情况， 如果使用了限定符 `.`，那么也不需要用反引号： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.select (BEGIN int, END int); -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -下表列出了 TiDB 中的关键字和保留字。保留字用 `(R)` 来标识。[窗口函数](/v3.1/reference/sql/functions-and-operators/window-functions.md)的保留字用 `(R-Window)` 来标识： - -{{< tabs-panel "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z" >}} - -A - -- ACTION -- ADD (R) -- ADDDATE -- ADMIN -- AFTER -- ALL (R) -- ALTER (R) -- ALWAYS -- ANALYZE(R) -- AND (R) -- ANY -- AS (R) -- ASC (R) -- ASCII -- AUTO_INCREMENT -- AVG -- AVG_ROW_LENGTH - -B - -- BEGIN -- BETWEEN (R) -- BIGINT (R) -- BINARY (R) -- BINLOG -- BIT -- BIT_XOR -- BLOB (R) -- BOOL -- BOOLEAN -- BOTH (R) -- BTREE -- BY (R) -- BYTE - -C - -- CASCADE (R) -- CASE (R) -- CAST -- CHANGE (R) -- CHAR (R) -- CHARACTER (R) -- CHARSET -- CHECK (R) -- CHECKSUM -- COALESCE -- COLLATE (R) -- COLLATION -- COLUMN (R) -- COLUMNS -- COMMENT -- COMMIT -- COMMITTED -- COMPACT -- COMPRESSED -- COMPRESSION -- CONNECTION -- CONSISTENT -- CONSTRAINT (R) -- CONVERT (R) -- COUNT -- CREATE (R) -- CROSS (R) -- CUME_DIST (R-Window) -- CURRENT_DATE (R) -- CURRENT_TIME (R) -- CURRENT_TIMESTAMP (R) -- CURRENT_USER (R) -- CURTIME - -D - -- DATA -- DATABASE (R) -- DATABASES (R) -- DATE -- DATE_ADD -- DATE_SUB -- DATETIME -- DAY -- DAY_HOUR (R) -- DAY_MICROSECOND (R) -- DAY_MINUTE (R) -- DAY_SECOND (R) -- DDL -- DEALLOCATE -- DEC -- DECIMAL (R) -- DEFAULT (R) -- DELAY_KEY_WRITE -- DELAYED (R) -- DELETE (R) -- DENSE_RANK (R-Window) -- DESC (R) -- DESCRIBE (R) -- DISABLE -- DISTINCT (R) -- DISTINCTROW (R) -- DIV (R) -- DO -- DOUBLE (R) -- DROP (R) -- DUAL (R) -- DUPLICATE -- DYNAMIC - -E - -- ELSE (R) -- ENABLE -- ENCLOSED -- END -- ENGINE -- ENGINES -- ENUM -- ESCAPE -- ESCAPED -- EVENTS -- EXCLUSIVE -- EXECUTE -- EXISTS -- EXPLAIN (R) -- EXTRACT - -F - -- FALSE (R) -- FIELDS -- FIRST -- FIRST_VALUE (R-Window) -- FIXED -- FLOAT (R) -- FLUSH -- FOR (R) -- FORCE (R) -- FOREIGN (R) -- FORMAT -- FROM (R) -- FULL -- FULLTEXT (R) -- FUNCTION - -G - -- GENERATED (R) -- GET_FORMAT -- GLOBAL -- GRANT (R) -- GRANTS -- GROUP (R) -- GROUP_CONCAT -- GROUPS (R-Window) - -H - -- HASH -- HAVING (R) -- HIGH_PRIORITY (R) -- HOUR -- HOUR_MICROSECOND (R) -- HOUR_MINUTE (R) -- HOUR_SECOND (R) - -I - -- IDENTIFIED -- IF (R) -- IGNORE (R) -- IN (R) -- INDEX (R) -- INDEXES -- INFILE (R) -- INNER (R) -- INSERT (R) -- INT (R) -- INTEGER (R) -- INTERVAL (R) -- INTO (R) -- IS (R) -- ISOLATION - -J - -- JOBS -- JOIN (R) -- JSON - -K - -- KEY (R) -- KEY_BLOCK_SIZE -- KEYS (R) -- KILL (R) - -L - -- LAG (R-Window) -- LAST_VALUE (R-Window) -- LEAD (R-Window) -- LEADING (R) -- LEFT (R) -- LESS -- LEVEL -- LIKE (R) -- LIMIT (R) -- LINES (R) -- LOAD (R) -- LOCAL -- LOCALTIME (R) -- LOCALTIMESTAMP (R) -- LOCK (R) -- LONGBLOB (R) -- LONGTEXT (R) -- LOW_PRIORITY (R) - -M - -- MAX -- MAX_ROWS -- MAXVALUE (R) -- MEDIUMBLOB (R) -- MEDIUMINT (R) -- MEDIUMTEXT (R) -- MICROSECOND -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND (R) -- MINUTE_SECOND (R) -- MIN -- MIN_ROWS -- MINUTE -- MINUTE_MICROSECOND -- MINUTE_SECOND -- MOD (R) -- MODE -- MODIRY -- MONTH - -N - -- NAMES -- NATIONAL -- NATURAL (R) -- NO -- NO_WRITE_TO_BINLOG (R) -- NONE -- NOT (R) -- NOW -- NTH_VALUE (R-Window) -- NTILE (R-Window) -- NULL (R) -- NUMERIC (R) -- NVARCHAR (R) - -O - -- OFFSET -- ON (R) -- ONLY -- OPTION (R) -- OR (R) -- ORDER (R) -- OUTER (R) -- OVER (R-Window) - -P - -- PARTITION (R) -- PARTITIONS -- PASSWORD -- PERCENT_RANK (R-Window) -- PLUGINS -- POSITION -- PRECISION (R) -- PREPARE -- PRIMARY (R) -- PRIVILEGES -- PROCEDURE (R) -- PROCESS -- PROCESSLIST - -Q - -- QUARTER -- QUERY -- QUICK - -R - -- RANGE (R) -- RANK (R-Window) -- READ (R) -- REAL (R) -- REDUNDANT -- REFERENCES (R) -- REGEXP (R) -- RENAME (R) -- REPEAT (R) -- REPEATABLE -- REPLACE (R) -- RESTRICT (R) -- REVERSE -- REVOKE (R) -- RIGHT (R) -- RLIKE (R) -- ROLLBACK -- ROW -- ROW_COUNT -- ROW_FORMAT -- ROW_NUMBER (R-Window) -- ROWS (R-Window) - -S - -- SCHEMA -- SCHEMAS -- SECOND -- SECOND_MICROSECOND (R) -- SELECT (R) -- SERIALIZABLE -- SESSION -- SET (R) -- SHARE -- SHARED -- SHOW (R) -- SIGNED -- SMALLINT (R) -- SNAPSHOT -- SOME -- SQL_CACHE -- SQL_CALC_FOUND_ROWS (R) -- SQL_NO_CACHE -- START -- STARTING (R) -- STATS -- STATS_BUCKETS -- STATS_HISTOGRAMS -- STATS_META -- STATS_PERSISTENT -- STATUS -- STORED (R) -- SUBDATE -- SUBSTR -- SUBSTRING -- SUM -- SUPER - -T - -- TABLE (R) -- TABLES -- TERMINATED (R) -- TEXT -- THAN -- THEN (R) -- TIDB -- TIDB_INLJ -- TIDB_SMJ -- TIME -- TIMESTAMP -- TIMESTAMPADD -- TIMESTAMPDIFF -- TINYBLOB (R) -- TINYINT (R) -- TINYTEXT (R) -- TO (R) -- TRAILING (R) -- TRANSACTION -- TRIGGER (R) -- TRIGGERS -- TRIM -- TRUE (R) -- TRUNCATE - -U - -- UNCOMMITTED -- UNION (R) -- UNIQUE (R) -- UNKNOWN -- UNLOCK (R) -- UNSIGNED (R) -- UPDATE (R) -- USE (R) -- USER -- USING (R) -- UTC_DATE (R) -- UTC_TIME (R) -- UTC_TIMESTAMP (R) - -V - -- VALUE -- VALUES (R) -- VARBINARY (R) -- VARCHAR (R) -- VARIABLES -- VIEW -- VIRTUAL (R) - -W - -- WARNINGS -- WEEK -- WHEN (R) -- WHERE (R) -- WINDOW (R-Window) -- WITH (R) -- WRITE (R) - -X - -- XOR (R) - -Y - -- YEAR -- YEAR_MONTH (R) - -Z - -- ZEROFILL (R) diff --git a/v3.1/reference/sql/language-structure/literal-values.md b/v3.1/reference/sql/language-structure/literal-values.md deleted file mode 100644 index c4d5c89bd5ab..000000000000 --- a/v3.1/reference/sql/language-structure/literal-values.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: 字面值 -category: reference ---- - -# 字面值 - -## String Literals - -String Literals 是一个 bytes 或者 characters 的序列，两端被单引号 `'` 或者双引号 `"` 包围，例如： - -``` -'example string' -"example string" -``` - -如果字符串是连续的，会被合并为一个独立的 string。以下表示是一样的： - -``` -'a string' -'a' ' ' 'string' -"a" ' ' "string" -``` - -如果 `ANSI_QUOTES` SQL MODE 开启了，那么只有单引号内的会被认为是 String Literals，对于双引号内的字符串，会被认为是一个 identifier。 - -binary string 是一串 bytes 组成的字符串，每一个 binary string 有一个叫做 `binary` 的 character set 和 collation。一个非二进制的字符串是一个由字符组成的字符串，它有除 `binary` 外的 character set和与之兼容的 collation。 - -对于两种字符串类型，比较都是基于每个字符的数值。对于 binary string 而言，比较单元就是字节，对于非二进制的字符串，那么单元就是字符，而有的字符集支持多字节字符。 - -一个 String Literal 可以拥有一个可选的 `character set introducer` 和 `COLLATE clause`，可以用来指派特定的字符集跟 collation（TiDB 对此只是做了语法上的兼容，并不实质做处理)。 - -``` -[_charset_name]'string' [COLLATE collation_name] -``` - -例如： - -{{< copyable "sql" >}} - -```sql -SELECT _latin1'string'; -SELECT _binary'string'; -SELECT _utf8'string' COLLATE utf8_bin; -``` - -你可以使用 N'literal' 或者 n'literal' 来创建使用 national character set 的字符串，下列语句是一样的： - -{{< copyable "sql" >}} - -```sql -SELECT N'some text'; -SELECT n'some text'; -SELECT _utf8'some text'; -``` - -转义字符： - -- \\0: ASCII NUL (X'00') 字符 -- \\': 单引号 -- \\": 双引号 -- \\b: 退格符号 -- \\n: 换行符 -- \\r: 回车符 -- \\t: tab 符（制表符） -- \\z: ASCII 26 (Ctrl + Z) -- \\\\: 反斜杠 \\ -- \\%: \% -- \\_: \_ - -如果要在 string literal 中使用 `'` 或者 `"`，有以下几种办法： - -* 在 `'` 引用的字符串中，可以用 `''` 来表示单引号。 -* 在 `"` 引用的字符串中，可以用 `""` 来表示双引号。 -* 前面接转义符`\`。 -* 在 `'` 中表示 `"` 或者在 `"` 中表示 `'` 都不需要特别的处理。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/string-literals.html)。 - -## Numeric Literals - -数值字面值包括 integer 跟 Decimal 类型跟浮点数字面值。 - -integer 可以包括 `.` 作为小数点分隔，数字前可以有 `-` 或者 `+` 来表示正数或者负数。 - -精确数值字面值可以表示为如下格式：`1, .2, 3.4, -5, -6.78, +9.10`. - -科学记数法也是被允许的，表示为如下格式：`1.2E3, 1.2E-3, -1.2E3, -1.2E-3`。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/number-literals.html)。 - -## NULL Values - -`NULL` 代表数据为空，它是大小写不敏感的，与 `\N`(大小写敏感) 同义。 - -> **注意：** -> -> `NULL` 跟 `0` 并不一样，跟空字符串 `''` 也不一样。 - -## Hexadecimal Literals - -十六进制字面值是有 `X` 和 `0x` 前缀的字符串，后接表示十六进制的数字。注意 `0x` 是大小写敏感的，不能表示为 `0X`。 - -例: - -``` -X'ac12' -X'12AC' -x'ac12' -x'12AC' -0xac12 -0x12AC -``` - -以下是不合法的十六进制字面值： - -``` -X'1z' (z 不是合法的十六进制值) -0X12AC (0X 必须用小写的 0x) -``` - -对于使用 `X'val'` 格式的十六进制字面值，`val` 必须要有一个数字，可以在前面补一个 0 来避免语法错误。 - -{{< copyable "sql" >}} - -```sql -select X'aff'; -``` - -``` -ERROR 1105 (HY000): line 0 column 13 near ""hex literal: invalid hexadecimal format, must even numbers, but 3 (total length 13) -``` - -{{< copyable "sql" >}} - -```sql -select X'0aff'; -``` - -``` -+---------+ -| X'0aff' | -+---------+ -| - | -+---------+ -1 row in set (0.00 sec) -``` - -默认情况，十六进制字面值是一个二进制字符串。 - -如果需要将一个字符串或者数字转换为十六进制字面值，可以使用内建函数 `HEX()`： - -{{< copyable "sql" >}} - -```sql -SELECT HEX('TiDB'); -``` - -``` -+-------------+ -| HEX('TiDB') | -+-------------+ -| 54694442 | -+-------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT X'54694442'; -``` - -``` -+-------------+ -| X'54694442' | -+-------------+ -| TiDB | -+-------------+ -1 row in set (0.00 sec) -``` - -## Date and Time Literals - -Date 跟 Time 字面值有几种格式，例如用字符串表示，或者直接用数字表示。在 TiDB 里面，当 TiDB 期望一个 Date 的时候，它会把 `'2017-08-24'`， `'20170824'`，`20170824` 当做是 Date。 - -TiDB 的 Date 值有以下几种格式： - -* `'YYYY-MM-DD'` 或者 `'YY-MM-DD'`，这里的 `-` 分隔符并不是严格的，可以是任意的标点符号。比如 `'2017-08-24'`，`'2017&08&24'`， `'2012@12^31'` 都是一样的。唯一需要特别对待的是 '.' 号，它被当做是小数点，用于分隔整数和小数部分。 - Date 和 Time 部分可以被 'T' 分隔，它的作用跟空格符是一样的，例如 `2017-8-24 10:42:00` 跟 `2017-8-24T10:42:00` 是一样的。 -* `'YYYYMMDDHHMMSS'` 或者 `'YYMMDDHHMMSS'`，例如 `'20170824104520'` 和 `'170824104520'` 被当做是 `'2017-08-24 10:45:20'`，但是如果你提供了一个超过范围的值，例如`'170824304520'`，那这就不是一个有效的 Date 字面值。 -* `YYYYMMDDHHMMSS` 或者 `YYMMDDHHMMSS` 注意这里没有单引号或者双引号，是一个数字。例如 `20170824104520`表示为 `'2017-08-24 10:45:20'`。 - -DATETIME 或者 TIMESTAMP 值可以接一个小数部分，用来表示微秒（精度最多到小数点后 6 位），用小数点 `.` 分隔。 - -Dates 如果 year 部分只有两个数字，这是有歧义的（推荐使用四个数字的格式），TiDB 会尝试用以下的规则来解释： - -* year 值如果在 `70-99` 范围，那么被转换成 `1970-1999`。 -* year 值如果在 `00-69` 范围，那么被转换成 `2000-2069`。 - -对于小于 10 的 month 或者 day 值，`'2017-8-4'` 跟 `'2017-08-04'` 是一样的。对于 Time 也是一样，比如 `'2017-08-24 1:2:3'` 跟 `'2017-08-24 01:02:03'`是一样的。 - -在需要 Date 或者 Time 的语境下, 对于数值，TiDB 会根据数值的长度来选定指定的格式： - -* 6 个数字，会被解释为 `YYMMDD`。 -* 12 个数字，会被解释为 `YYMMDDHHMMSS`。 -* 8 个数字，会解释为 `YYYYMMDD`。 -* 14 个数字，会被解释为 `YYYYMMDDHHMMSS`。 - -对于 Time 类型，TiDB 用以下格式来表示： - -* `'D HH:MM:SS'`，或者 `'HH:MM:SS'`，`'HH:MM'`，`'D HH:MM'`，`'D HH'`，`'SS'`，这里的 D 表示 days，合法的范围是 `0-34`。 -* 数值 `HHMMSS`，例如 `231010` 被解释为`'23:10:10'`。 -* 数值 `SS`，`MMSS`，`HHMMSS` 都是可以被当做 Time。 - -Time 类型的小数点也是 `.`，精度最多小数点后 6 位。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-literals.html)。 - -## Boolean Literals - -常量 `TRUE` 和 `FALSE` 等于 1 和 0，它是大小写不敏感的。 - -{{< copyable "sql" >}} - -```sql -SELECT TRUE, true, tRuE, FALSE, FaLsE, false; -``` - -``` -+------+------+------+-------+-------+-------+ -| TRUE | true | tRuE | FALSE | FaLsE | false | -+------+------+------+-------+-------+-------+ -| 1 | 1 | 1 | 0 | 0 | 0 | -+------+------+------+-------+-------+-------+ -1 row in set (0.00 sec) -``` - -## Bit-Value Literals - -位值字面值用 `b` 或者 `0b` 做前缀，后接以 0 跟 1 组成的二进制数字。其中 `0b` 是区分大小写的，`0B` 是会报错的。 - -合法的 Bit-value： - -* b'01' -* B'01' -* 0b01 - -非法的 Bit-value： - -* b'2' (2 不是二进制数值, 必须为 0 或 1) -* 0B01 (0B 必须是小写 0b) - -默认情况，位值字面值是一个二进制字符串。 - -Bit-value 是作为二进制返回的，所以输出到 MySQL Client 可能会显示不出来，如果要转换为可打印的字符，可以使用内建函数 `BIN()` 或者 `HEX()`： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t (b BIT(8)); -INSERT INTO t SET b = b'00010011'; -INSERT INTO t SET b = b'1110'; -INSERT INTO t SET b = b'100101'; -``` - -{{< copyable "sql" >}} - -```sql -SELECT b+0, BIN(b), HEX(b) FROM t; -``` - -``` -+------+--------+--------+ -| b+0 | BIN(b) | HEX(b) | -+------+--------+--------+ -| 19 | 10011 | 13 | -| 14 | 1110 | E | -| 37 | 100101 | 25 | -+------+--------+--------+ -3 rows in set (0.00 sec) -``` diff --git a/v3.1/reference/sql/language-structure/schema-object-names.md b/v3.1/reference/sql/language-structure/schema-object-names.md deleted file mode 100644 index 07a2a7d519c4..000000000000 --- a/v3.1/reference/sql/language-structure/schema-object-names.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Schema Object Names -category: reference ---- - -# Schema Object Names - -在 TiDB 中，包括 database，table，index，column，alias 等等都被认为是 identifier (标识符，之后阐述用英文). - -在 TiDB 中，identifier可以被反引号 (\`) 包裹，为了阐述方便，我们叫这种情况为 `被引用`。identifier 也可以不被 \` 包裹。但是如果一个 identifier 存在一个特殊符号或者是一个保留关键字，那么你必须要 `引用` 它。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM `table` WHERE `table`.id = 20; -``` - -如果`ANSI_QUOTES` sql mode 被设置了，那么我们认为被双引号 `"` 包裹的字符串为 identifier。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE "test" (a varchar(10)); -``` - -``` -ERROR 1105 (HY000): line 0 column 19 near " (a varchar(10))" (total length 35) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION sql_mode='ANSI_QUOTES'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE "test" (a varchar(10)); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -如果你需要在被引用的 identifier 中使用反引号这个字符，那你需要重复两次，例如你需要创建一个表为 a`b： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE `a``b` (a int); -``` - -在 select 语句中，alias 语句可以用 identifier 或者字符串： - -{{< copyable "sql" >}} - -```sql -SELECT 1 AS `identifier`, 2 AS 'string'; -``` - -``` -+------------+--------+ -| identifier | string | -+------------+--------+ -| 1 | 2 | -+------------+--------+ -1 row in set (0.00 sec) -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/identifiers.html) - -## Identifier Qualifiers - -Object Names (对象名字) 可以被限定也可以不用。例如你可以在创建表的时候不指定 database names： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t (i int); -``` - -但是如果你之前没有设定过默认的数据库，会报 `ERROR 1046 (3D000): No database selected` 错误。当然你也可以指定数据库限定名： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.t (i int); -``` - -对于 `.` 左右两端可以出现空格，`table_name.col_name` 等于 `table_name . col_name`。 - -如果你要引用这个 identifier，那么请使用： - -``` -`table_name`.`col_name` -``` - -而不是： - -``` -`table_name.col_name` -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/identifier-qualifiers.html) diff --git a/v3.1/reference/sql/language-structure/user-defined-variables.md b/v3.1/reference/sql/language-structure/user-defined-variables.md deleted file mode 100644 index 3e47672a1af8..000000000000 --- a/v3.1/reference/sql/language-structure/user-defined-variables.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: 用户自定义变量 -category: reference ---- - -# 用户自定义变量 - -用户自定义变量格式为 `@var_name`。`var_name` 目前只支持字母，数字，`_$`组成。用户自定义变量是大小写不敏感的。 - -用户自定义变量是跟 session 绑定的，也就是说只有当前连接可以看见设置的用户变量，其他客户端连接无法查看到。 - -用 `SET` 语句可以设置用户自定义变量： - -{{< copyable "sql" >}} - -```sql -SET @var_name = expr [, @var_name = expr] ...; -``` - -或 - -{{< copyable "sql" >}} - -```sql -SET @var_name := expr; -``` - -对于 `SET` 语句，赋值操作符可以是 `=` 也可以是 `:=` - -例： - -{{< copyable "sql" >}} - -```sql -SET @a1=1, @a2=2, @a3:=4; -``` - -{{< copyable "sql" >}} - -```sql -SELECT @a1, @a2, @t3, @a4 := @a1+@a2+@a3; -``` - -``` -+------+------+------+--------------------+ -| @a1 | @a2 | @a3 | @a4 := @a1+@a2+@a3 | -+------+------+------+--------------------+ -| 1 | 2 | 4 | 7 | -+------+------+------+--------------------+ -``` - -如果设置用户变量用了 `HEX` 或者 `BIT` 值，TiDB会把它当成二进制字符串。如果你要将其设置成数字，那么需要手动加上 `CAST转换`: `CAST(.. AS UNSIGNED)`： - -{{< copyable "sql" >}} - -```sql -SELECT @v1, @v2, @v3; -``` - -``` -+------+------+------+ -| @v1 | @v2 | @v3 | -+------+------+------+ -| A | 65 | 65 | -+------+------+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @v1 = b'1000001'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @v2 = b'1000001'+0; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @v3 = CAST(b'1000001' AS UNSIGNED); -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT @v1, @v2, @v3; -``` - -``` -+------+------+------+ -| @v1 | @v2 | @v3 | -+------+------+------+ -| A | 65 | 65 | -+------+------+------+ -1 row in set (0.00 sec) -``` - -如果获取一个没有设置过的变量，会返回一个 NULL： - -{{< copyable "sql" >}} - -```sql -select @not_exist; -``` - -``` -+------------+ -| @not_exist | -+------------+ -| NULL | -+------------+ -1 row in set (0.00 sec) -``` - -用户自定义变量不能直接在 SQL 语句中被当成 identifier，例： - -{{< copyable "sql" >}} - -```sql -select * from t; -``` - -``` -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @col = "a"; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT @col FROM t; -``` - -``` -+------+ -| @col | -+------+ -| a | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT `@col` FROM t; -``` - -``` -ERROR 1054 (42S22): Unknown column '@col' in 'field list' -``` - -{{< copyable "sql" >}} - -```sql -SET @col = "`a`"; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT @col FROM t; -``` - -``` -+------+ -| @col | -+------+ -| `a` | -+------+ -1 row in set (0.01 sec) -``` - -但是有一个例外是如果你在 PREPARE 语句中使用它，是可以的： - -{{< copyable "sql" >}} - -```sql -PREPARE stmt FROM "SELECT @c FROM t"; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE stmt; -``` - -``` -+------+ -| @c | -+------+ -| a | -+------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE stmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/user-variables.html)。 diff --git a/v3.1/reference/sql/partitioning.md b/v3.1/reference/sql/partitioning.md deleted file mode 100644 index bd78f0cd6e82..000000000000 --- a/v3.1/reference/sql/partitioning.md +++ /dev/null @@ -1,913 +0,0 @@ ---- -title: 分区表 -category: reference ---- - -# 分区表 - -本文介绍 TiDB 的分区表。 - -## 分区类型 - -本节介绍在 TiDB 中的分区类型。当前支持的类型包括 Range 分区和 Hash 分区。Range 分区可以用于解决业务中大量删除带来的性能问题，支持快速删除分区。Hash 分区则可以用于大量写入场景下的数据打散。 - -### Range 分区 - -一个表按 range 分区是指，对于表的每个分区中包含的所有行，按分区表达式计算的值都落在给定的范围内。Range 必须是连续的，并且不能有重叠，通过使用 `VALUES LESS THAN` 操作进行定义。 - -下列场景中，假设你要创建一个人事记录的表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -); -``` - -你可以根据需求按各种方式进行 range 分区。其中一种方式是按 `store_id` 列进行分区。你可以这样做： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -) - -PARTITION BY RANGE (store_id) ( - PARTITION p0 VALUES LESS THAN (6), - PARTITION p1 VALUES LESS THAN (11), - PARTITION p2 VALUES LESS THAN (16), - PARTITION p3 VALUES LESS THAN (21) -); -``` - -在这个分区模式中，所有 `store_id` 为 1 到 5 的员工，都存储在分区 `p0` 里面，`store_id` 为 6 到 10 的员工则存储在分区 `p1` 里面。range 分区要求，分区的定义必须是有序的，按从小到大递增。 - -新插入一行数据 `(72, 'Mitchell', 'Wilson', '1998-06-25', NULL, 13)` 将会落到分区 `p2` 里面。但如果你插入一条 `store_id` 大于 20 的记录，则会报错，因为 TiDB 无法知晓应该将它插入到哪个分区。这种情况下，可以在建表时使用最大值： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -) - -PARTITION BY RANGE (store_id) ( - PARTITION p0 VALUES LESS THAN (6), - PARTITION p1 VALUES LESS THAN (11), - PARTITION p2 VALUES LESS THAN (16), - PARTITION p3 VALUES LESS THAN MAXVALUE -); -``` - -`MAXVALUE` 表示一个比所有整数都大的整数。现在，所有 `store_id` 列大于等于 16 的记录都会存储在 `p3` 分区中。 - -你也可以按员工的职位编号进行分区，也就是使用 `job_code` 列的值进行分区。假设两位数字编号是用于普通员工，三位数字编号是用于办公室以及客户支持，四位数字编号是管理层职位，那么你可以这样建表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT NOT NULL, - store_id INT NOT NULL -) - -PARTITION BY RANGE (job_code) ( - PARTITION p0 VALUES LESS THAN (100), - PARTITION p1 VALUES LESS THAN (1000), - PARTITION p2 VALUES LESS THAN (10000) -); -``` - -在这个例子中，所有普通员工存储在 `p0` 分区，办公室以及支持人员在 `p1` 分区，管理者在 `p2` 分区。 - -除了可以按 `store_id` 切分，你还可以按日期切分。例如，假设按员工离职的年份进行分区： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT, - store_id INT -) - -PARTITION BY RANGE ( YEAR(separated) ) ( - PARTITION p0 VALUES LESS THAN (1991), - PARTITION p1 VALUES LESS THAN (1996), - PARTITION p2 VALUES LESS THAN (2001), - PARTITION p3 VALUES LESS THAN MAXVALUE -); -``` - -在 range 分区中，可以基于 `timestamp` 列的值分区，并使用 `unix_timestamp()` 函数，例如： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE quarterly_report_status ( - report_id INT NOT NULL, - report_status VARCHAR(20) NOT NULL, - report_updated TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP -) - -PARTITION BY RANGE ( UNIX_TIMESTAMP(report_updated) ) ( - PARTITION p0 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-01-01 00:00:00') ), - PARTITION p1 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-04-01 00:00:00') ), - PARTITION p2 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-07-01 00:00:00') ), - PARTITION p3 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-10-01 00:00:00') ), - PARTITION p4 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-01-01 00:00:00') ), - PARTITION p5 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-04-01 00:00:00') ), - PARTITION p6 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-07-01 00:00:00') ), - PARTITION p7 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-10-01 00:00:00') ), - PARTITION p8 VALUES LESS THAN ( UNIX_TIMESTAMP('2010-01-01 00:00:00') ), - PARTITION p9 VALUES LESS THAN (MAXVALUE) -); -``` - -对于 timestamp 值，使用其它的分区表达式是不允许的。 - -Range 分区在下列条件之一或者多个都满足时，尤其有效： - -* 删除旧数据。如果你使用之前的 `employees` 表的例子，你可以简单使用 `ALTER TABLE employees DROP PARTITION p0;` 删除所有在 1991 年以前停止继续在这家公司工作的员工记录。这会比使用 `DELETE FROM employees WHERE YEAR(separated) <= 1990;` 执行快得多。 -* 使用包含时间或者日期的列，或者是其它按序生成的数据。 -* 频繁查询分区使用的列。例如执行这样的查询 `EXPLAIN SELECT COUNT(*) FROM employees WHERE separated BETWEEN '2000-01-01' AND '2000-12-31' GROUP BY store_id;` 时，TiDB 可以迅速确定，只需要扫描 `p2` 分区的数据，因为其它的分区不满足 `where` 条件。 - -### Hash 分区 - -Hash 分区主要用于保证数据均匀地分散到一定数量的分区里面。在 range 分区中你必须为每个分区指定值的范围；在 hash 分区中，你只需要指定分区的数量。 - -使用 hash 分区时，需要在 `CREATE TABLE` 后面添加 `PARTITION BY HASH (expr)`，其中 `expr` 是一个返回整数的表达式。当这一列的类型是整数类型时，它可以是一个列名。此外，你很可能还需要加上 `PARTITIONS num`，其中 `num` 是一个正整数，表示将表划分多少分区。 - -下面的语句将创建一个 hash 分区表，按 `store_id` 分成 4 个分区： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT, - store_id INT -) - -PARTITION BY HASH(store_id) -PARTITIONS 4; -``` - -如果不指定 `PARTITIONS num`，默认的分区数量为 1。 - -你也可以使用一个返回整数的 SQL 表达式。例如，你可以按入职年份分区： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL, - fname VARCHAR(30), - lname VARCHAR(30), - hired DATE NOT NULL DEFAULT '1970-01-01', - separated DATE NOT NULL DEFAULT '9999-12-31', - job_code INT, - store_id INT -) - -PARTITION BY HASH( YEAR(hired) ) -PARTITIONS 4; -``` - -最高效的 hash 函数是作用在单列上，并且函数的单调性是跟列的值是一样递增或者递减的，因为这种情况可以像 range 分区一样裁剪。 - -例如，`date_col` 是类型为 `DATE` 的列，表达式 `TO_DAYS(date_col)` 的值是直接随 `date_col` 的值变化的。`YEAR(date_col)` 跟 `TO_DAYS(date_col)` 就不太一样，因为不是每次 `date_col` 变化时 `YEAR(date_col)` 都会得到不同的值。即使如此，`YEAR(date_col)` 也仍然是一个比较好的 hash 函数，因为它的结果是随着 `date_col` 的值的比例变化的。 - -作为对比，假设我们有一个类型是 INT 的 `int_col` 的列。考虑一下表达式 `POW(5-int_col,3) + 6`，这并不是一个比较好的 hash 函数，因为随着 `int_col` 的值的变化，表达式的结果不会成比例地变化。改变 `int_col` 的值会使表达式的结果的值变化巨大。例如，`int_col` 从 5 变到 6 表达式的结果变化是 -1，但是从 6 变到 7 的时候表达式的值的变化是 -7。 - -总而言之，表达式越接近 `y = cx` 的形式，它越是适合作为 hash 函数。因为表达式越是非线性的，在各个分区上面的数据的分布越是倾向于不均匀。 - -理论上，hash 分区也是可以做分区裁剪的。而实际上对于多列的情况，实现很难并且计算很耗时。因此，不推荐 hash 分区在表达式中涉及多列。 - -使用 `PARTITIION BY HASH` 的时候，TiDB 通过表达式的结果做“取余”运算，决定数据落在哪个分区。换句话说，如果分区表达式是 `expr`，分区数是 `num`，则由 `MOD(expr, num)` 决定存储的分区。假设 `t1` 定义如下： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATE) - PARTITION BY HASH( YEAR(col3) ) - PARTITIONS 4; -``` - -向 `t1` 插入一行数据，其中 `col3` 列的值是 '2005-09-15'，这条数据会被插入到分区 1 中： - -``` -MOD(YEAR('2005-09-01'),4) -= MOD(2005,4) -= 1 -``` - -### 分区对 NULL 值的处理 - -TiDB 允许计算结果为 NULL 的分区表达式。注意，NULL 不是一个整数类型，NULL 小于所有的整数类型值，正如 `ORDER BY` 的规则一样。 - -#### Range 分区对 NULL 的处理 - -如果插入一行到 range 分区表，它的分区列的计算结果是 NULL，那么这一行会被插入到最小的那个分区。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - c1 INT, - c2 VARCHAR(20) -) - -PARTITION BY RANGE(c1) ( - PARTITION p0 VALUES LESS THAN (0), - PARTITION p1 VALUES LESS THAN (10), - PARTITION p2 VALUES LESS THAN MAXVALUE -); -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1 partition(p0); -``` - -``` -+------|--------+ -| c1 | c2 | -+------|--------+ -| NULL | mothra | -+------|--------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1 partition(p1); -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1 partition(p2); -``` - -``` -Empty set (0.00 sec) -``` - -删除 `p0` 后验证： - -{{< copyable "sql" >}} - -```sql -alter table t1 drop partition p0; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from t1; -``` - -``` -Empty set (0.00 sec) -``` - -#### Hash 分区对 NULL 的处理 - -在 Hash 分区中 NULL 值的处理有所不同，如果分区表达式的计算结果为 NULL，它会被当作 0 值处理。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE th ( - c1 INT, - c2 VARCHAR(20) -) - -PARTITION BY HASH(c1) -PARTITIONS 2; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO th VALUES (NULL, 'mothra'), (0, 'gigan'); -``` - -``` -Query OK, 2 rows affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from th partition (p0); -``` - -``` -+------|--------+ -| c1 | c2 | -+------|--------+ -| NULL | mothra | -| 0 | gigan | -+------|--------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from th partition (p1); -``` - -``` -Empty set (0.00 sec) -``` - -可以看到，插入的记录 `(NULL, 'mothra')` 跟 `(0, 'gigan')` 落在了同一个分区。 - -## 分区管理 - -通过 `ALTER TABLE` 语句可以执行一些添加、删除、合并、切分、重定义分区的操作。 - -### Range 分区管理 - -创建分区表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE members ( - id INT, - fname VARCHAR(25), - lname VARCHAR(25), - dob DATE -) - -PARTITION BY RANGE( YEAR(dob) ) ( - PARTITION p0 VALUES LESS THAN (1980), - PARTITION p1 VALUES LESS THAN (1990), - PARTITION p2 VALUES LESS THAN (2000) -); -``` - -删除分区： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members DROP PARTITION p2; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -清空分区： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members TRUNCATE PARTITION p1; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -> **注意：** -> -> `ALTER TABLE ... REORGANIZE PARTITION` 在 TiDB 中暂不支持。 - -添加分区： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members ADD PARTITION (PARTITION p3 VALUES LESS THAN (2010)); -``` - -Range 分区中，`ADD PARTITION` 只能在分区列表的最后面添加，如果是添加到已存在的分区范围则会报错： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE members - ADD PARTITION ( - PARTITION n VALUES LESS THAN (1970)); -``` - -``` -ERROR 1463 (HY000): VALUES LESS THAN value must be strictly » - increasing for each partition -``` - -### Hash 分区管理 - -跟 Range 分区不同，Hash 分区不能够 `DROP PARTITION`。 - -目前 TiDB 的实现暂时不支持 `ALTER TABLE ... COALESCE PARTITION`。 - -## 分区裁剪 - -有一个优化叫做“分区裁剪”，它基于一个非常简单的概念：不需要扫描那些匹配不上的分区。 - -假设创建一个分区表 `t1`： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - fname VARCHAR(50) NOT NULL, - lname VARCHAR(50) NOT NULL, - region_code TINYINT UNSIGNED NOT NULL, - dob DATE NOT NULL -) - -PARTITION BY RANGE( region_code ) ( - PARTITION p0 VALUES LESS THAN (64), - PARTITION p1 VALUES LESS THAN (128), - PARTITION p2 VALUES LESS THAN (192), - PARTITION p3 VALUES LESS THAN MAXVALUE -); -``` - -如果你想获得这个 select 语句的结果： - -{{< copyable "sql" >}} - -```sql -SELECT fname, lname, region_code, dob - FROM t1 - WHERE region_code > 125 AND region_code < 130; -``` - -很显然，结果必然是在分区 `p1` 或者 `p2` 里面，也就是说，我们只需要在 `p1` 和 `p2` 里面去搜索匹配的行。去掉不必要的分区就是所谓的裁剪。优化器如果能裁剪掉一部分的分区，则执行会快于处理整个不做分区的表的相同查询。 - -优化器可以通过 where 条件裁剪的两个场景： - -* partition_column = constant -* partition_column IN (constant1, constant2, ..., constantN) - -## 分区选择 - -SELECT 语句中支持分区选择。实现通过使用一个 `PARTITION` 选项实现。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE employees ( - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, - fname VARCHAR(25) NOT NULL, - lname VARCHAR(25) NOT NULL, - store_id INT NOT NULL, - department_id INT NOT NULL -) - -PARTITION BY RANGE(id) ( - PARTITION p0 VALUES LESS THAN (5), - PARTITION p1 VALUES LESS THAN (10), - PARTITION p2 VALUES LESS THAN (15), - PARTITION p3 VALUES LESS THAN MAXVALUE -); - -INSERT INTO employees VALUES - ('', 'Bob', 'Taylor', 3, 2), ('', 'Frank', 'Williams', 1, 2), - ('', 'Ellen', 'Johnson', 3, 4), ('', 'Jim', 'Smith', 2, 4), - ('', 'Mary', 'Jones', 1, 1), ('', 'Linda', 'Black', 2, 3), - ('', 'Ed', 'Jones', 2, 1), ('', 'June', 'Wilson', 3, 1), - ('', 'Andy', 'Smith', 1, 3), ('', 'Lou', 'Waters', 2, 4), - ('', 'Jill', 'Stone', 1, 4), ('', 'Roger', 'White', 3, 2), - ('', 'Howard', 'Andrews', 1, 2), ('', 'Fred', 'Goldberg', 3, 3), - ('', 'Barbara', 'Brown', 2, 3), ('', 'Alice', 'Rogers', 2, 2), - ('', 'Mark', 'Morgan', 3, 3), ('', 'Karen', 'Cole', 3, 2); -``` - -你可以查看存储在分区 `p1` 中的行： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM employees PARTITION (p1); -``` - -``` -+----|-------|--------|----------|---------------+ -| id | fname | lname | store_id | department_id | -+----|-------|--------|----------|---------------+ -| 5 | Mary | Jones | 1 | 1 | -| 6 | Linda | Black | 2 | 3 | -| 7 | Ed | Jones | 2 | 1 | -| 8 | June | Wilson | 3 | 1 | -| 9 | Andy | Smith | 1 | 3 | -+----|-------|--------|----------|---------------+ -5 rows in set (0.00 sec) -``` - -如果希望获得多个分区中的行，可以提供分区名的列表，用逗号隔开。例如，`SELECT * FROM employees PARTITION (p1, p2)` 返回分区 `p1` 和 `p2` 的所有行。 - -使用分区选择时，仍然可以使用 where 条件，以及 ORDER BY 和 LIMIT 等选项。使用 HAVING 和 GROUP BY 等聚合选项也是支持的。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM employees PARTITION (p0, p2) - WHERE lname LIKE 'S%'; -``` - -``` -+----|-------|-------|----------|---------------+ -| id | fname | lname | store_id | department_id | -+----|-------|-------|----------|---------------+ -| 4 | Jim | Smith | 2 | 4 | -| 11 | Jill | Stone | 1 | 4 | -+----|-------|-------|----------|---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT id, CONCAT(fname, ' ', lname) AS name - FROM employees PARTITION (p0) ORDER BY lname; -``` - -``` -+----|----------------+ -| id | name | -+----|----------------+ -| 3 | Ellen Johnson | -| 4 | Jim Smith | -| 1 | Bob Taylor | -| 2 | Frank Williams | -+----|----------------+ -4 rows in set (0.06 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT store_id, COUNT(department_id) AS c - FROM employees PARTITION (p1,p2,p3) - GROUP BY store_id HAVING c > 4; -``` - -``` -+---|----------+ -| c | store_id | -+---|----------+ -| 5 | 2 | -| 5 | 3 | -+---|----------+ -2 rows in set (0.00 sec) -``` - -分支选择支持所有类型的分区表，无论是 range 分区或是 hash 分区等。对于 hash 分区，如果没有指定分区名，会自动使用 `p0`、`p1`、`p2`、……、或 `pN-1` 作为分区名。 - -在 `INSERT ... SELECT` 的 `SELECT` 中也是可以使用分区选择的。 - -## 分区的约束和限制 - -本节介绍当前 TiDB 分区表的一些约束和限制。 - -### 分区键，主键和唯一键 - -本节讨论分区键，主键和唯一键之间的关系。一句话总结它们之间的关系要满足的规则：**分区表的每个唯一键，必须包含分区表达式中用到的所有列**。 - -> every unique key on the table must use every column in the table's partitioning expression. - -这里所指的唯一也包含了主键，因为根据主键的定义，主键必须是唯一的。例如，下面这些建表语句就是无效的： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col2) -) - -PARTITION BY HASH(col3) -PARTITIONS 4; - -CREATE TABLE t2 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1), - UNIQUE KEY (col3) -) - -PARTITION BY HASH(col1 + col3) -PARTITIONS 4; -``` - -它们都是有唯一键但没有包含所有分区键的。 - -下面是一些合法的语句的例子： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col2, col3) -) - -PARTITION BY HASH(col3) -PARTITIONS 4; - -CREATE TABLE t2 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col3) -) - -PARTITION BY HASH(col1 + col3) -PARTITIONS 4; -``` - -下例中会产生一个报错： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t3 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col2), - UNIQUE KEY (col3) -) - -PARTITION BY HASH(col1 + col3) - PARTITIONS 4; -``` - -``` -ERROR 1491 (HY000): A PRIMARY KEY must include all columns in the table's partitioning function -``` - -原因是 `col1` 和 `col3` 出现在分区键中，但是几个唯一键定义并没有完全包含它们。 - -下面这个表就没法做分区了，因为无论如何都不可能找到满足条件的分区键： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t4 ( - col1 INT NOT NULL, - col2 INT NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - UNIQUE KEY (col1, col3), - UNIQUE KEY (col2, col4) -); -``` - -根据定义，主键也是唯一键，下面两个建表语句是无效的： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t5 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - PRIMARY KEY(col1, col2) -) - -PARTITION BY HASH(col3) -PARTITIONS 4; - -CREATE TABLE t6 ( - col1 INT NOT NULL, - col2 DATE NOT NULL, - col3 INT NOT NULL, - col4 INT NOT NULL, - PRIMARY KEY(col1, col3), - UNIQUE KEY(col2) -) - -PARTITION BY HASH( YEAR(col2) ) -PARTITIONS 4; -``` - -两个例子中，主键都没有包含分区表达式中的全部的列。 - -如果既没有主键，也没有唯一键，则不存在这个限制。 - -DDL 变更时，添加唯一索引也需要考虑到这个限制。比如创建了这样一个表： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t_no_pk (c1 INT, c2 INT) - PARTITION BY RANGE(c1) ( - PARTITION p0 VALUES LESS THAN (10), - PARTITION p1 VALUES LESS THAN (20), - PARTITION p2 VALUES LESS THAN (30), - PARTITION p3 VALUES LESS THAN (40) - ); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -通过 `ALTER TABLE` 添加非唯一索引是可以的。但是添加唯一索引时，唯一索引里面必须包含 `c1` 列。 - -### 关于函数的分区限制 - -只有以下函数可以用于分区表达式： - -``` -ABS() -CEILING() (see CEILING() and FLOOR()) -DATEDIFF() -DAY() -DAYOFMONTH() -DAYOFWEEK() -DAYOFYEAR() -EXTRACT() (see EXTRACT() function with WEEK specifier) -FLOOR() (see CEILING() and FLOOR()) -HOUR() -MICROSECOND() -MINUTE() -MOD() -MONTH() -QUARTER() -SECOND() -TIME_TO_SEC() -TO_DAYS() -TO_SECONDS() -UNIX_TIMESTAMP() (with TIMESTAMP columns) -WEEKDAY() -YEAR() -YEARWEEK() -``` - -### 兼容性 - -目前 TiDB 里面只实现了 Range 分区和 Hash 分区，其它的 MySQL 分区类型比如 List 分区和 Key 分区尚不支持。 - -对于 Range Columns 类型的分区表，目前只支持单列的场景。 - -分区管理方面，只要底层实现可能会涉及数据挪到的操作，目前都暂不支持。包括且不限于：调整 Hash 分区表的分区数量，修改 Range 分区表的范围，合并分区，交换分区等。 - -对于暂不支持的分区类型，在 TiDB 中建表时会忽略分区信息，以普通表的形式创建，并且会报 Warning。 - -INFORMATION_SCHEMA.PARTITION 表暂不支持。 - -Load Data 暂时不支持分区选择。 - -{{< copyable "sql" >}} - -```sql -create table t (id int, val int) partition by hash(id) partitions 4; -``` - -普通的 Load Data 操作在 TiDB 中是支持的，如下： - -{{< copyable "sql" >}} - -```sql -load local data infile "xxx" into t ... -``` - -但 Load Data 不支持分区选择操作： - -{{< copyable "sql" >}} - -```sql -load local data infile "xxx" into t partition (p1)... -``` - -对于分区表，`select * from t` 的返回结果是分区之间无序的。这跟 MySQL 不同，MySQL 的返回结果是分区之间有序，分区内部无序。 - -{{< copyable "sql" >}} - -```sql -create table t (id int, val int) partition by range (id) ( - partition p0 values less than (3), - partition p1 values less than (7), - partition p2 values less than (11)); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values (1, 2), (3, 4),(5, 6),(7,8),(9,10); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -TiDB 每次返回结果会不同，例如： - -{{< copyable "sql" >}} - -``` -select * from t; -``` - -``` -+------|------+ -| id | val | -+------|------+ -| 7 | 8 | -| 9 | 10 | -| 1 | 2 | -| 3 | 4 | -| 5 | 6 | -+------|------+ -5 rows in set (0.00 sec) -``` - -MySQL 的返回结果： - -{{< copyable "sql" >}} - -``` -select * from t; -``` - -``` -+------|------+ -| id | val | -+------|------+ -| 1 | 2 | -| 3 | 4 | -| 5 | 6 | -| 7 | 8 | -| 9 | 10 | -+------|------+ -5 rows in set (0.00 sec) -``` diff --git a/v3.1/reference/sql/sql-mode.md b/v3.1/reference/sql/sql-mode.md deleted file mode 100644 index 31f30793da4a..000000000000 --- a/v3.1/reference/sql/sql-mode.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: SQL Mode -category: reference ---- - -# SQL 模式 - -TiDB 服务器采用不同 SQL 模式来操作，且不同客户端可以应用不同模式。SQL 模式定义 TiDB 支持哪些 SQL 语法及执行哪种数据验证检查. - -TiDB 启动之前采用修改 `--sql-mode="modes"` 配项设置 SQL 模式。 - -TiDB 启动之后采用 `SET [ SESSION | GLOBAL ] sql_mode='modes'`设置 SQL 模式。设置 GLOBAL 级别的 SQL 模式时用户需要有 SUPER 权限，并且只会影响到从设置 SQL 模式开始后续新建立的连接（注：老连接不受影响)。 SESSION 级别的 SQL 模式的变化只会影响当前的客户端。 - -Modes 是用逗号 (',') 间隔开的一系列不同的模式。使用 `SELECT @@sql_mode` 语句查询当前 SQL 模式，SQL 模式默认值：`ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION`。 - -## 重要的 sql_mode 值 - -* ANSI: 符合标准 SQL ，对数据进行校验，如果不符合定义类型或长度，对数据类型调整或截断保存，且返回warning警告。 -* STRICT_TRANS_TABLES: 严格模式，对数据进严格校验，但数据出现错误时，插入到表中，并且返回错误。 -* TRADITIONAL: 采用此模式使 TiDB 的行为象 "传统" SQL 数据库系统，当在列中插入不正确的值时“给出错误而不是警告”，一旦发现错误立即放弃INSERT/UPDATE。 - -## SQL mode 列表 - -| 名称 | 含义 | -| --- | --- | -| PIPES_AS_CONCAT | 将 "\|\|" 视为字符串连接操作符（＋）(同CONCAT())，而不视为OR（支持) | -| ANSI_QUOTES | 将 `"` 视为识别符，如果启用 ANSI_QUOTES，只单引号内的会被认为是 String Literals，双引号被解释为识别符，因此不能用双引号来引用字符串（支持）| -| IGNORE_SPACE | 若开启该模式，系统忽略空格。例如：“user” 和 “user “ 是相同的（支持）| -| ONLY_FULL_GROUP_BY | 如果 GROUP BY 出现的列并没有在 SELECT，HAVING，ORDER BY 中出现，此 SQL 不合法，因为不在 GROUP BY 中的列被查询展示出来不符合正常现象 （支持) | -| NO_UNSIGNED_SUBTRACTION | 在减运算中，如果某个操作数没有符号，不要将结果标记为UNSIGNED （支持）| -| NO_DIR_IN_CREATE | 创建表时，忽视所有 INDEX DIRECTORY 和 DATA DIRECTORY 指令，该选项仅对从复制服务器有用 （仅语法支持）| -| NO_KEY_OPTIONS | 使用 SHOW CREATE TABLE 时不会输出 MySQL 特有的语法部分，如 ENGINE ，使用 mysqldump 跨DB种类迁移的时需要考虑此选项（仅语法支持）| -| NO_FIELD_OPTIONS | 使用 SHOW CREATE TABLE 时不会输出 MySQL 特有的语法部分，如 ENGINE ，使用 mysqldump 跨DB种类迁移的时需要考虑此选项（仅语法支持）| -| NO_TABLE_OPTIONS | 使用 SHOW CREATE TABLE 时不会输出 MySQL 特有的语法部分，如 ENGINE ，使用 mysqldump 跨DB种类迁移的时需要考虑此选项（仅语法支持）| -| NO_AUTO_VALUE_ON_ZERO | 若启用该模式，在AUTO_INCREMENT列的处理传入的值是 0 或者具体数值时系统直接将该值写入此列，传入 NULL 时系统自动生成下一个序列号（支持）| -| NO_BACKSLASH_ESCAPES | 若启用该模式，`\` 反斜杠符号仅代表它自己（支持）| -| STRICT_TRANS_TABLES | 对于事务存储引擎启用严格模式，insert非法值之后，回滚整条语句（支持）| -| STRICT_ALL_TABLES | 对于事务型表，写入非法值之后，回滚整个事务语句（支持）| -| NO_ZERO_IN_DATE | 在严格模式，不接受月或日部分为0的日期。如果使用IGNORE选项，我们为类似的日期插入'0000-00-00'。在非严格模式，可以接受该日期，但会生成警告 （支持） -| NO_ZERO_DATE | 在严格模式，不要将 '0000-00-00'做为合法日期。你仍然可以用IGNORE选项插入零日期。在非严格模式，可以接受该日期，但会生成警告 （支持）| -| ALLOW_INVALID_DATES | 不检查全部日期的合法性，仅检查月份值在 1 到 12 及 日期值在 1 到31 之间，仅适用于 DATE 和 DATATIME 列，TIMESTAMP 列需要全部检查其合法性 （支持）| -| ERROR_FOR_DIVISION_BY_ZERO | 若启用该模式，在 INSERT 或 UPDATE 过程中，被除数为 0 值时，系统产生错误
若未启用该模式，被除数为 0 值时，系统产生警告，并用 NULL 代替 （支持） | -| NO_AUTO_CREATE_USER | 防止GRANT自动创建新用户，但指定密码除外 （支持）| -| HIGH_NOT_PRECEDENCE | NOT 操作符的优先级是表达式。例如： NOT a BETWEEN b AND c 被解释为 NOT (a BETWEEN b AND c)。在部份旧版本MySQL中， 表达式被解释为(NOT a) BETWEEN b AND c (支持) | -| NO_ENGINE_SUBSTITUTION | 如果需要的存储引擎被禁用或未编译，可以防止自动替换存储引擎 （仅语法支持）| -| PAD_CHAR_TO_FULL_LENGTH | 若启用该模式，系统对于 CHAR 类型不会截断尾部空格（支持）| -| REAL_AS_FLOAT | 将REAL视为FLOAT的同义词，而不是DOUBLE的同义词 （支持）| -| POSTGRESQL | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS （支持）| -| MSSQL | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、 NO_FIELD_OPTIONS （支持）| -| DB2 | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS （支持）| -| MAXDB | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS、NO_AUTO_CREATE_USER （支持）| -| MySQL323 | 等同于 NO_FIELD_OPTIONS、HIGH_NOT_PRECEDENCE (支持)| -| MYSQL40 | 等同于 NO_FIELD_OPTIONS、HIGH_NOT_PRECEDENCE （支持）| -| ANSI | 等同于 REAL_AS_FLOAT、PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE （支持）| -| TRADITIONAL | 等同于 STRICT_TRANS_TABLES、STRICT_ALL_TABLES、NO_ZERO_IN_DATE、NO_ZERO_DATE、ERROR_FOR_DIVISION_BY_ZERO、NO_AUTO_CREATE_USER(支持) | -| ORACLE | 等同于 PIPES_AS_CONCAT、ANSI_QUOTES、IGNORE_SPACE、NO_KEY_OPTIONS、NO_TABLE_OPTIONS、NO_FIELD_OPTIONS、NO_AUTO_CREATE_USER （支持）| diff --git a/v3.1/reference/sql/statements/add-column.md b/v3.1/reference/sql/statements/add-column.md deleted file mode 100644 index 81bcb0316c3f..000000000000 --- a/v3.1/reference/sql/statements/add-column.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: ADD COLUMN -summary: TiDB 数据库中 ADD COLUMN 的使用概况。 -category: reference ---- - -# ADD COLUMN - -`ALTER TABLE.. ADD COLUMN` 语句用于在已有表中添加列。在 TiDB 中，`ADD COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (NULL); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+ -| id | -+----+ -| 1 | -+----+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD COLUMN c1 INT NOT NULL; -``` - -``` -Query OK, 0 rows affected (0.28 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 0 | -+----+----+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD c2 INT NOT NULL AFTER c1; -``` - -``` -Query OK, 0 rows affected (0.28 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+----+ -| id | c1 | c2 | -+----+----+----+ -| 1 | 0 | 0 | -+----+----+----+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持同时添加多列。 -* 不支持将新添加的列设为 `PRIMARY KEY`。 -* 不支持将新添加的列设为 `AUTO_INCREMENT`。 - -## 另请参阅 - -* [ADD INDEX](/v3.1/reference/sql/statements/add-index.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) diff --git a/v3.1/reference/sql/statements/add-index.md b/v3.1/reference/sql/statements/add-index.md deleted file mode 100644 index cfe3c73e430b..000000000000 --- a/v3.1/reference/sql/statements/add-index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: ADD INDEX -summary: TiDB 数据库中 ADD INDEX 的使用概况。 -category: reference ---- - -# ADD INDEX - -`ALTER TABLE.. ADD INDEX` 语句用于在已有表中添加一个索引。在 TiDB 中，`ADD INDEX` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引（类似于 MySQL 5.7）。 -* 目前尚不支持同时添加多个索引。 -* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/v3.1/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [CREATE INDEX](/v3.1/reference/sql/statements/create-index.md) -* [DROP INDEX](/v3.1/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v3.1/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/v3.1/reference/sql/statements/add-column.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [EXPLAIN](/v3.1/reference/sql/statements/explain.md) diff --git a/v3.1/reference/sql/statements/admin.md b/v3.1/reference/sql/statements/admin.md deleted file mode 100644 index b5c0d8bf7773..000000000000 --- a/v3.1/reference/sql/statements/admin.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: ADMIN -category: reference ---- - -# ADMIN - -`ADMIN` 语句是 TiDB 扩展语法，用于查看 TiDB 自身的状态，并对 TiDB 中的表数据进行校验。示例如下。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL; -``` - -`ADMIN SHOW DDL` 用于查看当前正在执行的 DDL 作业。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOBS; -``` - -`ADMIN SHOW DDL JOBS` 用于查看当前 DDL 作业队列中的所有结果（包括正在运行以及等待运行的任务）以及已执行完成的 DDL 作业队列中的最近十条结果。 - -{{< copyable "sql" >}} - -```sql -ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CANCEL DDL JOBS job_id [, job_id] ...; -``` - -{{< copyable "sql" >}} - -```sql -ADMIN CHECK TABLE tbl_name [, tbl_name] ...; -``` - -## 语句概览 - -**AdminStmt**： - -![AdminStmt](/media/sqlgram/AdminStmt.png) - -## 使用示例 - -{{< copyable "sql" >}} - -```sql -admin show ddl jobs; -``` - -``` -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -| JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -| 45 | test | t1 | add index | write reorganization | 32 | 37 | 0 | 2019-01-10 12:38:36.501 +0800 CST | running | -| 44 | test | t1 | add index | none | 32 | 37 | 0 | 2019-01-10 12:36:55.18 +0800 CST | rollback done | -| 43 | test | t1 | add index | public | 32 | 37 | 6 | 2019-01-10 12:35:13.66 +0800 CST | synced | -| 42 | test | t1 | drop index | none | 32 | 37 | 0 | 2019-01-10 12:34:35.204 +0800 CST | synced | -| 41 | test | t1 | add index | public | 32 | 37 | 0 | 2019-01-10 12:33:22.62 +0800 CST | synced | -| 40 | test | t1 | drop column | none | 32 | 37 | 0 | 2019-01-10 12:33:08.212 +0800 CST | synced | -| 39 | test | t1 | add column | public | 32 | 37 | 0 | 2019-01-10 12:32:55.42 +0800 CST | synced | -| 38 | test | t1 | create table | public | 32 | 37 | 0 | 2019-01-10 12:32:41.956 +0800 CST | synced | -| 36 | test | | drop table | none | 32 | 34 | 0 | 2019-01-10 11:29:59.982 +0800 CST | synced | -| 35 | test | | create table | public | 32 | 34 | 0 | 2019-01-10 11:29:40.741 +0800 CST | synced | -| 33 | test | | create schema | public | 32 | 0 | 0 | 2019-01-10 11:29:22.813 +0800 CST | synced | -+--------+---------+------------+---------------+----------------------+-----------+----------+-----------+-----------------------------------+---------------+ -``` - -* `JOB_ID`：每个 DDL 操作对应一个 DDL 作业，`JOB_ID` 全局唯一。 -* `DB_NAME`：执行 DDL 操作的数据库的名称。 -* `TABLE_NAME`：执行 DDL 操作的表的名称。 -* `JOB_TYPE`：DDL 操作的类型。 -* `SCHEMA_STATE`：schema 的当前状态。如果 `JOB_TYPE` 是 `add index`，则为 index 的状态；如果是 `add column`，则为 column 的状态，如果是 `create table`，则为 table 的状态。常见的状态有以下几种： - * `none`：表示不存在。一般 `drop` 操作或者 `create` 操作失败回滚后，会变为 `none` 状态。 - * `delete only`、`write only`、`delete reorganization`、`write reorganization`：这四种状态是中间状态，在 [Online, Asynchronous Schema Change in F1](http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/41376.pdf) 论文中有详细说明，在此不再赘述。由于中间状态转换很快，一般操作中看不到这几种状态，只有执行 `add index` 操作时能看到处于 `write reorganization` 状态，表示正在添加索引数据。 - * `public`：表示存在且可用。一般 `create table` 和 `add index/column` 等操作完成后，会变为 `public` 状态，表示新建的 table/column/index 可以正常读写了。 -* `SCHEMA_ID`：执行 DDL 操作的数据库的 ID。 -* `TABLE_ID`：执行 DDL 操作的表的 ID。 -* `ROW_COUNT`：执行 `add index` 操作时，当前已经添加完成的数据行数。 -* `START_TIME`：DDL 操作的开始时间。 -* `STATE`：DDL 操作的状态。常见的状态有以下几种： - * `none`：表示该操作任务已经进入 DDL 作业队列中，但尚未执行，因为还在排队等待前面的 DDL 作业完成。另一种原因可能是执行 `drop` 操作后，会变为 `none` 状态，但是很快会更新为 `synced` 状态，表示所有 TiDB 实例都已经同步到该状态。 - * `running`：表示该操作正在执行。 - * `synced`：表示该操作已经执行成功，且所有 TiDB 实例都已经同步该状态。 - * `rollback done`：表示该操作执行失败，回滚完成。 - * `rollingback`：表示该操作执行失败，正在回滚。 - * `cancelling`：表示正在取消该操作。这个状态只有在用 `ADMIN CANCEL DDL JOBS` 命令取消 DDL 作业时才会出现。 - -- `ADMIN SHOW DDL JOB QUERIES job_id [, job_id] ...`：用于查看 `job_id` 对应的 DDL 任务的原始 SQL 语句。这个 `job_id` 只会搜索正在运行中的 DDL 作业以及 DDL 历史作业队列中最近的十条结果。 -- `ADMIN CANCEL DDL JOBS job_id [, job_id] ...`：用于取消当前正在运行的 DDL 作业，并返回对应作业是否取消成功。如果取消失败，会显示失败的具体原因。 - - > **注意：** - > - > - 只有该操作可以取消 DDL 作业，其他所有的操作和环境变更（例如机器重启、集群重启）都不会取消 DDL 作业。 - > - 该操作可以同时取消多个 DDL 作业。可以通过 `ADMIN SHOW DDL JOBS` 语句来获取 DDL 作业的 ID。 - > - 如果希望取消的作业已经完成，则取消操作将会失败。 - -- `ADMIN CHECK TABLE tbl_name [, tbl_name] ...`：用于对给定表中的所有数据和对应索引进行一致性校验，若通过校验，则返回空的查询结果；否则返回数据不一致的错误信息。 - -## MySQL 兼容性 - -ADMIN 语句是 TiDB 对于 MySQL 语法的扩展。 diff --git a/v3.1/reference/sql/statements/alter-database.md b/v3.1/reference/sql/statements/alter-database.md deleted file mode 100644 index 8af454433e31..000000000000 --- a/v3.1/reference/sql/statements/alter-database.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: ALTER DATABASE -summary: TiDB 数据库中 ALTER DATABASE 的使用概况。 -category: reference ---- - -# ALTER DATABASE - -`ALTER DATABASE` 用于修改指定或当前数据库的默认字符集和排序规则。`ALTER SCHEMA` 跟 `ALTER DATABASE` 操作效果一样。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -ALTER {DATABASE | SCHEMA} [db_name] - alter_specification ... -alter_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -`alter_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/v3.1/reference/sql/character-set.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v3.1/reference/sql/statements/create-database.md) -* [SHOW DATABASES](/v3.1/reference/sql/statements/show-databases.md) diff --git a/v3.1/reference/sql/statements/alter-table.md b/v3.1/reference/sql/statements/alter-table.md deleted file mode 100644 index 1f7d5d6b6dfe..000000000000 --- a/v3.1/reference/sql/statements/alter-table.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: ALTER TABLE -summary: TiDB 数据库中 ALTER TABLE 的使用概况。 -category: reference ---- - -# ALTER TABLE - -`ALTER TABLE` 语句用于对已有表进行修改，以符合新表结构。`ALTER TABLE` 语句可用于： - -* [`ADD`](/v3.1/reference/sql/statements/add-index.md)，[`DROP`](/v3.1/reference/sql/statements/drop-index.md)，或 [`RENAME`](/v3.1/reference/sql/statements/rename-index.md) 索引 -* [`ADD`](/v3.1/reference/sql/statements/add-column.md)，[`DROP`](/v3.1/reference/sql/statements/drop-column.md)，[`MODIFY`](/v3.1/reference/sql/statements/modify-column.md) 或 [`CHANGE`](/v3.1/reference/sql/statements/change-column.md) 列 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 支持除空间类型外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 - -## 另请参阅 - -* [ADD COLUMN](/v3.1/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v3.1/reference/sql/statements/drop-column.md) -* [ADD INDEX](/v3.1/reference/sql/statements/add-index.md) -* [DROP INDEX](/v3.1/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v3.1/reference/sql/statements/rename-index.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) diff --git a/v3.1/reference/sql/statements/alter-user.md b/v3.1/reference/sql/statements/alter-user.md deleted file mode 100644 index 3ad50a53e67c..000000000000 --- a/v3.1/reference/sql/statements/alter-user.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: ALTER USER -summary: TiDB 数据库中 ALTER USER 的使用概况。 -category: reference ---- - -# ALTER USER - -`ALTER USER` 语句用于更改 TiDB 权限系统内的已有用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**AlterUserStmt:** - -![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'newuser'; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*5806E04BBEE79E1899964C6A04D68BCA69B1A879' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER USER 'newuser' IDENTIFIED BY 'newnewpassword'; -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'newuser'; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*FB8A1EA1353E8775CA836233E367FBDFCB37BE73' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，`ALTER` 语句用于更改属性，例如使密码失效。但 TiDB 尚不支持此功能。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/v3.1/reference/security/compatibility.md) -* [CREATE USER](/v3.1/reference/sql/statements/create-user.md) -* [DROP USER](/v3.1/reference/sql/statements/drop-user.md) -* [SHOW CREATE USER](/v3.1/reference/sql/statements/show-create-user.md) diff --git a/v3.1/reference/sql/statements/analyze-table.md b/v3.1/reference/sql/statements/analyze-table.md deleted file mode 100644 index 72df5d4a2b65..000000000000 --- a/v3.1/reference/sql/statements/analyze-table.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: ANALYZE TABLE -summary: TiDB 数据库中 ANALYZE TABLE 的使用概况。 -category: reference ---- - -# ANALYZE TABLE - -`ANALYZE TABLE` 语句用于更新 TiDB 在表和索引上留下的统计信息。执行大批量更新或导入记录后，或查询执行计划不是最佳时，建议运行 `ANALYZE TABLE`。 - -当 TiDB 逐渐发现这些统计数据与预估不一致时，也会自动更新其统计数据。 - -## 语法图 - -**AnalyzeTableStmt:** - -![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 ADD INDEX (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -analyze table t1; -``` - -``` -Query OK, 0 rows affected (0.13 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+---------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------------------------------------------+ -| IndexReader_6 | 1.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 1.00 | cop | table:t1, index:c1, range:[3,3], keep order:false | -+-------------------+-------+------+---------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`ANALYZE TABLE` 在语法上与 MySQL 类似。但 `ANALYZE TABLE` 在 TiDB 上执行所需时间可能长得多，因为它的内部运行方式不同。 - -## 另请参阅 - -* [EXPLAIN](/v3.1/reference/sql/statements/explain.md) -* [EXPLAIN ANALYZE](/v3.1/reference/sql/statements/explain-analyze.md) diff --git a/v3.1/reference/sql/statements/begin.md b/v3.1/reference/sql/statements/begin.md deleted file mode 100644 index 13daa9de7680..000000000000 --- a/v3.1/reference/sql/statements/begin.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: BEGIN -summary: TiDB 数据库中 BEGIN 的使用概况。 -category: reference ---- - -# BEGIN - -`BEGIN` 语句用于在 TiDB 内启动一个新事务，类似于 `START TRANSACTION` 和 `SET autocommit=0` 语句。 - -在没有 `BEGIN` 语句的情况下，每个语句默认在各自的事务中自动提交，从而确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`BEGIN` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上[提交 issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v3.1/reference/sql/statements/commit.md) -* [ROLLBACK](/v3.1/reference/sql/statements/rollback.md) -* [START TRANSACTION](/v3.1/reference/sql/statements/start-transaction.md) diff --git a/v3.1/reference/sql/statements/change-column.md b/v3.1/reference/sql/statements/change-column.md deleted file mode 100644 index a7ab575e912c..000000000000 --- a/v3.1/reference/sql/statements/change-column.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: CHANGE COLUMN -summary: TiDB 数据库中 CHANGE COLUMN 的使用概况。 -category: reference ---- - -# CHANGE COLUMN - -`ALTER TABLE.. CHANGE COLUMN` 语句用于在已有表上更改列，包括对列进行重命名，和将数据改为兼容类型。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col1 col2 INT; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col2 col3 BIGINT, ALGORITHM=INSTANT; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col3 INT; -``` - -``` -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col3 BLOB; -``` - -``` -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 CHANGE col3 col4 BIGINT, CHANGE id id2 INT NOT NULL; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前尚不支持在单个 `ALTER TABLE` 语句中进行多个更改。 -* 仅支持特定的数据类型更改。例如，支持将 `INTEGER` 更改为 `BIGINT`，但不支持将 `BIGINT` 更改为 `INTEGER`。不支持从整数更改为字符串格式或 BLOB 类型。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/v3.1/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v3.1/reference/sql/statements/drop-column.md) -* [MODIFY COLUMN](/v3.1/reference/sql/statements/modify-column.md) diff --git a/v3.1/reference/sql/statements/commit.md b/v3.1/reference/sql/statements/commit.md deleted file mode 100644 index e2442e7281f9..000000000000 --- a/v3.1/reference/sql/statements/commit.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: COMMIT -summary: TiDB 数据库中 COMMIT 的使用概况。 -category: reference ---- - -# COMMIT - -`COMMIT` 语句用于在 TiDB 服务器内部提交事务。 - -在不使用 `BEGIN` 或 `START TRANSACTION` 语句的情况下，TiDB 中每一个查询语句本身也会默认作为事务处理，自动提交，确保了与 MySQL 的兼容。 - -## 语法图 - -**CommitStmt:** - -![CommitStmt](/media/sqlgram/CommitStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -* 在 MySQL 中，除了有多个 primary 的群组复制以外，`COMMIT` 语句通常不会导致错误。相比之下，TiDB 使用乐观并发控制，冲突可能导致 `COMMIT` 返回错误。 -* 默认情况下，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。 - -## 另请参阅 - -* [START TRANSACTION](/v3.1/reference/sql/statements/start-transaction.md) -* [ROLLBACK](/v3.1/reference/sql/statements/rollback.md) -* [BEGIN](/v3.1/reference/sql/statements/begin.md) -* [事务的惰性检查](/v3.1/reference/transactions/overview.md#事务的惰性检查) \ No newline at end of file diff --git a/v3.1/reference/sql/statements/create-database.md b/v3.1/reference/sql/statements/create-database.md deleted file mode 100644 index 6ad2d4894284..000000000000 --- a/v3.1/reference/sql/statements/create-database.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: CREATE DATABASE -summary: TiDB 数据库中 CREATE DATABASE 的使用概况。 -category: reference ---- - -# CREATE DATABASE - -`CREATE DATABASE` 语句用于在 TiDB 上创建新数据库。按照 SQL 标准，“数据库” 一词在 MySQL 术语中最接近 “schema”。 - -## 语法图 - -**CreateDatabaseStmt:** - -![CreateDatabaseStmt](/media/sqlgram/CreateDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -**DatabaseOptionListOpt:** - -![DatabaseOptionListOpt](/media/sqlgram/DatabaseOptionListOpt.png) - -## 语法说明 - -`CREATE DATABASE` 用于创建数据库，并可以指定数据库的默认属性（如数据库默认字符集、排序规则）。`CREATE SCHEMA` 跟 `CREATE DATABASE` 操作效果一样。 - -{{< copyable "sql" >}} - -```sql -CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] db_name - [create_specification] ... - -create_specification: - [DEFAULT] CHARACTER SET [=] charset_name - | [DEFAULT] COLLATE [=] collation_name -``` - -当创建已存在的数据库且不指定使用 `IF NOT EXISTS` 时会报错。 - -`create_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/v3.1/reference/sql/character-set.md)。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE mynewdatabase; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -USE mynewdatabase; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+-------------------------+ -| Tables_in_mynewdatabase | -+-------------------------+ -| t1 | -+-------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [USE](/v3.1/reference/sql/statements/use.md) -* [ALTER DATABASE](/v3.1/reference/sql/statements/alter-database.md) -* [DROP DATABASE](/v3.1/reference/sql/statements/drop-database.md) -* [SHOW DATABASES](/v3.1/reference/sql/statements/show-databases.md) diff --git a/v3.1/reference/sql/statements/create-index.md b/v3.1/reference/sql/statements/create-index.md deleted file mode 100644 index 749e8b7d26b4..000000000000 --- a/v3.1/reference/sql/statements/create-index.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: CREATE INDEX -summary: CREATE INDEX 在 TiDB 中的使用概况 -category: reference ---- - -# CREATE INDEX - -`CREATE INDEX` 语句用于在已有表中添加新索引，功能等同于 `ALTER TABLE .. ADD INDEX`。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**CreateIndexStmt:** - -![CreateIndexStmt](/media/sqlgram/CreateIndexStmt.png) - -**CreateIndexStmtUnique:** - -![CreateIndexStmtUnique](/media/sqlgram/CreateIndexStmtUnique.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -**IndexTypeOpt:** - -![IndexTypeOpt](/media/sqlgram/IndexTypeOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**IndexColNameList:** - -![IndexColNameList](/media/sqlgram/IndexColNameList.png) - -**IndexOptionList:** - -![IndexOptionList](/media/sqlgram/IndexOptionList.png) - -**IndexOption:** - -![IndexOption](/media/sqlgram/IndexOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE UNIQUE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.31 sec) -``` - -## 相关 session 变量 - -和 `CREATE INDEX` 语句相关的全局变量有 `tidb_ddl_reorg_worker_cnt`，`tidb_ddl_reorg_batch_size` 和 `tidb_ddl_reorg_priority`，具体可以参考 [TiDB 特定系统变量](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_ddl_reorg_worker_cnt)。 - -## MySQL 兼容性 - -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* 不支持降序索引 （类似于 MySQL 5.7）。 -* 默认无法向表中添加 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/v3.1/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [ADD INDEX](/v3.1/reference/sql/statements/add-index.md) -* [DROP INDEX](/v3.1/reference/sql/statements/drop-index.md) -* [RENAME INDEX](/v3.1/reference/sql/statements/rename-index.md) -* [ADD COLUMN](/v3.1/reference/sql/statements/add-column.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [EXPLAIN](/v3.1/reference/sql/statements/explain.md) diff --git a/v3.1/reference/sql/statements/create-table-like.md b/v3.1/reference/sql/statements/create-table-like.md deleted file mode 100644 index 82b547833b55..000000000000 --- a/v3.1/reference/sql/statements/create-table-like.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: CREATE TABLE LIKE -summary: TiDB 数据库中 CREATE TABLE LIKE 的使用概况。 -category: reference ---- - -# CREATE TABLE LIKE - -`CREATE TABLE LIKE` 语句用于复制已有表的定义，但不复制任何数据。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**LikeTableWithOrWithoutParen:** - -![LikeTableWithOrWithoutParen](/media/sqlgram/LikeTableWithOrWithoutParen.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.13 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`CREATE TABLE LIKE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) \ No newline at end of file diff --git a/v3.1/reference/sql/statements/create-table.md b/v3.1/reference/sql/statements/create-table.md deleted file mode 100644 index 892296a700ee..000000000000 --- a/v3.1/reference/sql/statements/create-table.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: CREATE TABLE -summary: TiDB 数据库中 CREATE TABLE 的使用概况 -category: reference ---- - -# CREATE TABLE - -`CREATE TABLE` 语句用于在当前所选数据库中创建新表。另可参阅单独的 `CREATE TABLE LIKE` 文档。 - -## 语法图 - -**CreateTableStmt:** - -![CreateTableStmt](/media/sqlgram/CreateTableStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**TableElementListOpt:** - -![TableElementListOpt](/media/sqlgram/TableElementListOpt.png) - -**TableElement:** - -![TableElement](/media/sqlgram/TableElement.png) - -**PartitionOpt:** - -![PartitionOpt](/media/sqlgram/PartitionOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -**Type:** - -![Type](/media/sqlgram/Type.png) - -**ColumnOptionListOpt:** - -![ColumnOptionListOpt](/media/sqlgram/ColumnOptionListOpt.png) - -**TableOptionListOpt:** - -![TableOptionListOpt](/media/sqlgram/TableOptionListOpt.png) - -## 语法说明 - -`CREATE TABLE` 用于创建一个表。目前不支持临时表，不支持 `CHECK` 约束，不支持创建表的同时从其它表导入数据功能。在语法上也支持一些 `Partition_options`，但是并不完全，就不做列举了。 - -以下是 `CREATE TABLE` 相关的语法说明： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - (create_definition,...) - [table_options] -``` - -使用 `IF NOT EXIST` 时，即使创建的表已经存在，也不会报错，如果不指定时，则报错。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE [IF NOT EXISTS] tbl_name - { LIKE old_tbl_name | (LIKE old_tbl_name) } -``` - -使用 `LIKE` 基于一个表的定义创建一个空表，包括这个表中的列属性和索引属性。 - -```sql -create_definition: - col_name column_definition - | [CONSTRAINT [symbol]] PRIMARY KEY [index_type] (index_col_name,...) - [index_option] ... - | {INDEX|KEY} [index_name] [index_type] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] UNIQUE [INDEX|KEY] - [index_name] [index_type] (index_col_name,...) - [index_option] ... - | {FULLTEXT} [INDEX|KEY] [index_name] (index_col_name,...) - [index_option] ... - | [CONSTRAINT [symbol]] FOREIGN KEY - [index_name] (index_col_name,...) reference_definition -``` - -`create_definition` 中 `FULLTEXT` 和 `FOREIGN KEY` 目前只是语法上支持。 - -```sql -column_definition: - data_type [NOT NULL | NULL] [DEFAULT default_value] - [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] - [COMMENT 'string'] - [reference_definition] - | data_type [GENERATED ALWAYS] AS (expression) - [VIRTUAL | STORED] [UNIQUE [KEY]] [COMMENT comment] - [NOT NULL | NULL] [[PRIMARY] KEY] - -data_type: - BIT[(length)] - | TINYINT[(length)] [UNSIGNED] [ZEROFILL] - | SMALLINT[(length)] [UNSIGNED] [ZEROFILL] - | MEDIUMINT[(length)] [UNSIGNED] [ZEROFILL] - | INT[(length)] [UNSIGNED] [ZEROFILL] - | INTEGER[(length)] [UNSIGNED] [ZEROFILL] - | BIGINT[(length)] [UNSIGNED] [ZEROFILL] - | REAL[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DOUBLE[(length,decimals)] [UNSIGNED] [ZEROFILL] - | FLOAT[(length,decimals)] [UNSIGNED] [ZEROFILL] - | DECIMAL[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | NUMERIC[(length[,decimals])] [UNSIGNED] [ZEROFILL] - | DATE - | TIME[(fsp)] - | TIMESTAMP[(fsp)] - | DATETIME[(fsp)] - | YEAR - | CHAR[(length)] [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | VARCHAR(length) [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | BINARY[(length)] - | VARBINARY(length) - | TINYBLOB - | BLOB - | MEDIUMBLOB - | LONGBLOB - | TINYTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | TEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | MEDIUMTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | LONGTEXT [BINARY] - [CHARACTER SET charset_name] [COLLATE collation_name] - | ENUM(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | SET(value1,value2,value3,...) - [CHARACTER SET charset_name] [COLLATE collation_name] - | JSON -``` - -`data_type` 请参考[数据类型](/v3.1/reference/sql/data-types/overview.md)章节。 - -```sql -index_col_name: - col_name [(length)] [ASC | DESC] -``` - -`index_col_name` 中 `[ASC | DESC]` 目前只是语法上支持。 - -```sql -index_type: - USING {BTREE | HASH} -``` - -`index_type` 目前只是语法上支持。 - -```sql -index_option: - KEY_BLOCK_SIZE [=] value - | index_type - | COMMENT 'string' -``` - -`index_option` 中 `KEY_BLOCK_SIZE` 目前只是语法上支持。 - -```sql -reference_definition: - REFERENCES tbl_name (index_col_name,...) - [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] - [ON DELETE reference_option] - [ON UPDATE reference_option] - -reference_option: - RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT -``` - -```sql -table_options: - table_option [[,] table_option] ... - -table_option: - AUTO_INCREMENT [=] value - | AVG_ROW_LENGTH [=] value - | SHARD_ROW_ID_BITS [=] value - | PRE_SPLIT_REGIONS [=] value - | [DEFAULT] CHARACTER SET [=] charset_name - | CHECKSUM [=] {0 | 1} - | [DEFAULT] COLLATE [=] collation_name - | COMMENT [=] 'string' - | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'} - | CONNECTION [=] 'connect_string' - | DELAY_KEY_WRITE [=] {0 | 1} - | ENGINE [=] engine_name - | KEY_BLOCK_SIZE [=] value - | MAX_ROWS [=] value - | MIN_ROWS [=] value - | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT} - | STATS_PERSISTENT [=] {DEFAULT|0|1} -``` - -`table_option` 目前支持的只有 `AUTO_INCREMENT`、`SHARD_ROW_ID_BITS`（详情介绍请参考 [TiDB 专用系统变量和语法](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）、`PRE_SPLIT_REGIONS`、`CHARACTER SET`、`COLLATE` 和 `COMMENT`，其它只是语法上支持。具体内容参考下表，各个子句之间用逗号隔开。 - -| 参数 |含义 |举例 | -|----------------|--------------------------------------|----------------------------| -|`AUTO_INCREMENT`|自增字段初始值 |`AUTO_INCREMENT` = 5| -|`SHARD_ROW_ID_BITS`|用来设置隐式 _tidb_rowid 的分片数量的 bit 位数 |`SHARD_ROW_ID_BITS` = 4| -|`PRE_SPLIT_REGIONS`|用来在建表时预先均匀切分 `2^(PRE_SPLIT_REGIONS)` 个 Region |`PRE_SPLIT_REGIONS` = 4| -|`CHARACTER SET` |指定该表所使用的字符集 | `CHARACTER SET` = 'utf8mb4'| -|`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| -|`COMMENT` |注释信息 | `COMMENT` = 'comment info'| - -`split-table` 配置项默认情况下会开启，在此配置项开启时，建表操作会为每个表建立单独的 Region。 - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESC t1; -``` - -``` -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 不支持 `CREATE TEMPORARY TABLE` 语法。 -* 支持除空间类型以外的所有数据类型。 -* 不支持 `FULLTEXT`，`HASH` 和 `SPATIAL` 索引。 -* `KEY_BLOCK_SIZE` 和 `ENGINE` 属性可被解析，但会被忽略。 -* `index_col_name` 属性支持 length 选项，最大长度限制为 3072 字节。此长度限制不会更改，具体取决于存储引擎和建表时使用的字符集。 -* `index_col_name` 属性支持 `ASC` 和 `DESC` 的索引排序选项。 -* `COMMENT` 属性最多支持 1024 个字符，不支持 `WITH PARSER` 选项。 -* TiDB 在单个表中最多支持 512 列。InnoDB 中相应的数量限制为 1017，MySQL 中的硬限制为 4096。 - -## 另请参阅 - -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [CREATE TABLE LIKE](/v3.1/reference/sql/statements/create-table-like.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) diff --git a/v3.1/reference/sql/statements/create-user.md b/v3.1/reference/sql/statements/create-user.md deleted file mode 100644 index 208218034d84..000000000000 --- a/v3.1/reference/sql/statements/create-user.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: CREATE USER -summary: TiDB 数据库中 CREATE USER 的使用概况。 -category: reference ---- - -# CREATE USER - -`CREATE USER` 语句用于创建带有指定密码的新用户。和 MySQL 一样，在 TiDB 权限系统中，用户是用户名和用户名所连接主机的组合。因此，可创建一个用户 `'newuser2'@'192.168.1.1'`，使其只能通过 IP 地址 `192.168.1.1` 进行连接。相同的用户名从不同主机登录时可能会拥有不同的权限。 - -## 语法图 - -**CreateUserStmt:** - -![CreateUserStmt](/media/sqlgram/CreateUserStmt.png) - -**IfNotExists:** - -![IfNotExists](/media/sqlgram/IfNotExists.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) - -**AuthOption:** - -![AuthOption](/media/sqlgram/AuthOption.png) - -**StringName:** - -![StringName](/media/sqlgram/StringName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser2'@'192.168.1.1' IDENTIFIED BY 'newuserpassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -## MySQL 兼容性 - -* TiDB 尚不支持若干 `CREATE` 选项。这些选项可被解析，但会被忽略。 - -## 另请参阅 - -* [Security Compatibility with MySQL](/v3.1/reference/security/compatibility.md) -* [DROP USER](/v3.1/reference/sql/statements/drop-user.md) -* [SHOW CREATE USER](/v3.1/reference/sql/statements/show-create-user.md) -* [ALTER USER](/v3.1/reference/sql/statements/alter-user.md) -* [Privilege Management](/v3.1/reference/security/privilege-system.md) diff --git a/v3.1/reference/sql/statements/create-view.md b/v3.1/reference/sql/statements/create-view.md deleted file mode 100644 index 16f476daac33..000000000000 --- a/v3.1/reference/sql/statements/create-view.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: CREATE VIEW -summary: TiDB 数据库中 CREATE VIEW 的使用概况。 -category: reference ---- - -# CREATE VIEW - -使用 `CREATE VIEW` 语句将 `SELECT` 语句保存为类似于表的可查询对象。TiDB 中的视图是非物化的，这意味着在查询视图时，TiDB 将在内部重写查询，以将视图定义与 SQL 查询结合起来。 - -## 语法图 - -**CreateViewStmt:** - -![CreateViewStmt](/media/sqlgram/CreateViewStmt.png) - -**OrReplace:** - -![OrReplace](/media/sqlgram/OrReplace.png) - -**ViewAlgorithm:** - -![ViewAlgorithm](/media/sqlgram/ViewAlgorithm.png) - -**ViewDefiner:** - -![ViewDefiner](/media/sqlgram/ViewDefiner.png) - -**ViewSQLSecurity:** - -![ViewSQLSecurity](/media/sqlgram/ViewSQLSecurity.png) - -**ViewName:** - -![ViewName](/media/sqlgram/ViewName.png) - -**ViewFieldList:** - -![ViewFieldList](/media/sqlgram/ViewFieldList.png) - -**ViewCheckOption:** - -![ViewCheckOption](/media/sqlgram/ViewCheckOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (6); -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -| 6 | 6 | -+----+----+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO v1 (c1) VALUES (7); -``` - -``` -ERROR 1105 (HY000): insert into view v1 is not supported now. -``` - -## MySQL 兼容性 - -* 目前 TiDB 中的视图不可插入且不可更新。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) diff --git a/v3.1/reference/sql/statements/deallocate.md b/v3.1/reference/sql/statements/deallocate.md deleted file mode 100644 index d30e01350366..000000000000 --- a/v3.1/reference/sql/statements/deallocate.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: DEALLOCATE -summary: TiDB 数据库中 DEALLOCATE 的使用概况。 -category: reference ---- - -# DEALLOCATE - -`DEALLOCATE` 语句用于为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**DeallocateStmt:** - -![DeallocateStmt](/media/sqlgram/DeallocateStmt.png) - -**DeallocateSym:** - -![DeallocateSym](/media/sqlgram/DeallocateSym.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`DEALLOCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/v3.1/reference/sql/statements/prepare.md) -* [EXECUTE](/v3.1/reference/sql/statements/execute.md) diff --git a/v3.1/reference/sql/statements/delete.md b/v3.1/reference/sql/statements/delete.md deleted file mode 100644 index b34919f46c35..000000000000 --- a/v3.1/reference/sql/statements/delete.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: DELETE -summary: TiDB 数据库中 DELETE 的使用概况。 -category: reference ---- - -# DELETE - -`DELETE` 语句用于从指定的表中删除行。 - -## 语法图 - -**DeleteFromStmt:** - -![DeleteFromStmt](/media/sqlgram/DeleteFromStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DELETE FROM t1 WHERE id = 4; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 5 | 5 | -+----+----+ -4 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DELETE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v3.1/reference/sql/statements/insert.md) -* [SELECT](/v3.1/reference/sql/statements/select.md) -* [UPDATE](/v3.1/reference/sql/statements/update.md) -* [REPLACE](/v3.1/reference/sql/statements/replace.md) diff --git a/v3.1/reference/sql/statements/desc.md b/v3.1/reference/sql/statements/desc.md deleted file mode 100644 index e34b305c9508..000000000000 --- a/v3.1/reference/sql/statements/desc.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESC -summary: TiDB 数据库中 DESC 的使用概况。 -category: reference ---- - -# DESC - -`DESC` 语句是 [`EXPLAIN`](/v3.1/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v3.1/reference/sql/statements/describe.md b/v3.1/reference/sql/statements/describe.md deleted file mode 100644 index a74a98697ac5..000000000000 --- a/v3.1/reference/sql/statements/describe.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: DESCRIBE -summary: TiDB 数据库中 DESCRIBE 的使用概况。 -category: reference ---- - -# DESCRIBE - -`DESCRIBE` 语句为 [`EXPLAIN`](/v3.1/reference/sql/statements/explain.md) 的别名。包含该语句提供了 MySQL 兼容性。 \ No newline at end of file diff --git a/v3.1/reference/sql/statements/do.md b/v3.1/reference/sql/statements/do.md deleted file mode 100644 index ddbfbfa22256..000000000000 --- a/v3.1/reference/sql/statements/do.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: DO | TiDB SQL Statement Reference -summary: TiDB 数据库中 DO 的使用概况。 -category: reference ---- - -# DO - -`DO` 语句用于执行表达式，而不返回结果。在 MySQL 中，`DO` 的一个常见用例是执行存储的程序，而无需处理结果。但是 TiDB 不提供存储例程，因此该功能的使用较为受限。 - -## 语法图 - -**DoStmt:** - -![DoStmt](/media/sqlgram/DoStmt.png) - -**ExpressionList:** - -![ExpressionList](/media/sqlgram/ExpressionList.png) - -**Expression:** - -![Expression](/media/sqlgram/Expression.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SELECT SLEEP(5); -``` - -``` -+----------+ -| SLEEP(5) | -+----------+ -| 0 | -+----------+ -1 row in set (5.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DO SLEEP(5); -``` - -``` -Query OK, 0 rows affected (5.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DO SLEEP(1), SLEEP(1.5); -``` - -``` -Query OK, 0 rows affected (2.50 sec) -``` - -## MySQL 兼容性 - -`DO` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SELECT](/v3.1/reference/sql/statements/select.md) diff --git a/v3.1/reference/sql/statements/drop-column.md b/v3.1/reference/sql/statements/drop-column.md deleted file mode 100644 index 3d6f906c845d..000000000000 --- a/v3.1/reference/sql/statements/drop-column.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: DROP COLUMN -summary: TiDB 数据库中 DROP COLUMN 的使用概况。 -category: reference ---- - -# DROP COLUMN - -`DROP COLUMN` 语句用于从指定的表中删除列。在 TiDB 中，`COLUMN` 为在线操作，不会阻塞表中的数据读写。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnName:** - -![ColumnName](/media/sqlgram/ColumnName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, col1 INT NOT NULL, col2 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1,col2) VALUES (1,1),(2,2),(3,3),(4,4),(5,5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP COLUMN col1, DROP COLUMN col2; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+------+ -| id | col1 | col2 | -+----+------+------+ -| 1 | 1 | 1 | -| 2 | 2 | 2 | -| 3 | 3 | 3 | -| 4 | 4 | 4 | -| 5 | 5 | 5 | -+----+------+------+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP COLUMN col1; -``` - -``` -Query OK, 0 rows affected (0.27 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+------+ -| id | col2 | -+----+------+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 不支持使用相同语句删除多个列。 - -## 另请参阅 - -* [ADD COLUMN](/v3.1/reference/sql/statements/add-column.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) diff --git a/v3.1/reference/sql/statements/drop-database.md b/v3.1/reference/sql/statements/drop-database.md deleted file mode 100644 index b45651268ef3..000000000000 --- a/v3.1/reference/sql/statements/drop-database.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: DROP DATABASE -summary: TiDB 数据库中 DROP DATABASE 的使用概况。 -category: reference ---- - -# DROP DATABASE - -`DROP DATABASE` 语句用于永久删除指定的数据库 schema，以及删除所有在 schema 中创建的表和视图。与被删数据库相关联的用户权限不受影响。 - -## 语法图 - -**DropDatabaseStmt:** - -![DropDatabaseStmt](/media/sqlgram/DropDatabaseStmt.png) - -**DatabaseSym:** - -![DatabaseSym](/media/sqlgram/DatabaseSym.png) - -**IfExists:** - -![IfExists](/media/sqlgram/IfExists.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP DATABASE test; -``` - -``` -Query OK, 0 rows affected (0.25 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -+--------------------+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP DATABASE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v3.1/reference/sql/statements/create-database.md) -* [ALTER DATABASE](/v3.1/reference/sql/statements/alter-database.md) diff --git a/v3.1/reference/sql/statements/drop-index.md b/v3.1/reference/sql/statements/drop-index.md deleted file mode 100644 index b73826c6d3bc..000000000000 --- a/v3.1/reference/sql/statements/drop-index.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: DROP INDEX -summary: TiDB 数据库中 DROP INDEX 的使用概况。 -category: reference ---- - -# DROP INDEX - -`DROP INDEX` 语句用于从指定的表中删除索引，并在 TiKV 中将空间标记为释放。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_7 | 10.00 | root | data:Selection_6 | -| └─Selection_6 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_5 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE INDEX c1 ON t1 (c1); -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE c1 = 3; -``` - -``` -+-------------------+-------+------+-----------------------------------------------------------------+ -| id | count | task | operator info | -+-------------------+-------+------+-----------------------------------------------------------------+ -| IndexReader_6 | 10.00 | root | index:IndexScan_5 | -| └─IndexScan_5 | 10.00 | cop | table:t1, index:c1, range:[3,3], keep order:false, stats:pseudo | -+-------------------+-------+------+-----------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -``` -Query OK, 0 rows affected (0.30 sec) -``` - -## MySQL 兼容性 - -* 默认不支持删除 `PRIMARY KEY`，在开启 `alter-primary-key` 配置项后可支持此功能，详情参考：[alter-primary-key](/v3.1/reference/configuration/tidb-server/configuration-file.md#alter-primary-key)。 - -## 另请参阅 - -* [SHOW INDEX](/v3.1/reference/sql/statements/show-index.md) -* [CREATE INDEX](/v3.1/reference/sql/statements/create-index.md) -* [ADD INDEX](/v3.1/reference/sql/statements/add-index.md) -* [RENAME INDEX](/v3.1/reference/sql/statements/rename-index.md) diff --git a/v3.1/reference/sql/statements/drop-table.md b/v3.1/reference/sql/statements/drop-table.md deleted file mode 100644 index cfa4770c279c..000000000000 --- a/v3.1/reference/sql/statements/drop-table.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: DROP TABLE -summary: TiDB 数据库中 DROP TABLE 的使用概况。 -category: reference ---- - -# DROP TABLE - -`DROP TABLE` 语句用于从当前所选的数据库中删除表。如果表不存在则会报错，除非使用 `IF EXISTS` 修饰符。 - -按照设计，`DROP TABLE` 也会删除视图，因为视图与表共享相同的命名空间。 - -## 语法图 - -**DropTableStmt:** - -![DropTableStmt](/media/sqlgram/DropTableStmt.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE t1; -``` - -``` -Query OK, 0 rows affected (0.22 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE table_not_exists; -``` - -``` -ERROR 1051 (42S02): Unknown table 'test.table_not_exists' -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE IF EXISTS table_not_exists; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT 1; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP TABLE v1; -``` - -``` -Query OK, 0 rows affected (0.23 sec) -``` - -## MySQL 兼容性 - -* 在尝试删除不存在的表时，使用 `IF EXISTS` 删除表不会返回警告。[Issue #7867](https://github.com/pingcap/tidb/issues/7867) - -## 另请参阅 - -* [DROP VIEW](/v3.1/reference/sql/statements/drop-view.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [SHOW TABLES](/v3.1/reference/sql/statements/show-tables.md) diff --git a/v3.1/reference/sql/statements/drop-user.md b/v3.1/reference/sql/statements/drop-user.md deleted file mode 100644 index 6190bb5ef7d9..000000000000 --- a/v3.1/reference/sql/statements/drop-user.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: DROP USER -summary: TiDB 数据库中 DROP USER 的使用概况。 -category: reference ---- - -# DROP USER - -`DROP USER` 语句用于从 TiDB 系统数据库中删除用户。如果用户不存在，使用关键词 `IF EXISTS` 可避免出现警告。 - -## 语法图 - -**DropUserStmt:** - -![DropUserStmt](/media/sqlgram/DropUserStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -DROP USER idontexist; -``` - -``` -ERROR 1396 (HY000): Operation DROP USER failed for idontexist@% -``` - -{{< copyable "sql" >}} - -```sql -DROP USER IF EXISTS idontexist; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REVOKE ALL ON test.* FROM 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP USER newuser; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR newuser; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -* 在 TiDB 中删除不存在的用户时，使用 `IF EXISTS` 可避免出现警告。[Issue #10196](https://github.com/pingcap/tidb/issues/10196)。 - -## 另请参阅 - -* [CREATE USER](/v3.1/reference/sql/statements/create-user.md) -* [ALTER USER](/v3.1/reference/sql/statements/alter-user.md) -* [SHOW CREATE USER](/v3.1/reference/sql/statements/show-create-user.md) -* [Privilege Management](/v3.1/reference/security/privilege-system.md) diff --git a/v3.1/reference/sql/statements/drop-view.md b/v3.1/reference/sql/statements/drop-view.md deleted file mode 100644 index 7810b6ae4858..000000000000 --- a/v3.1/reference/sql/statements/drop-view.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: DROP VIEW -summary: TiDB 数据库中 DROP VIEW 的使用概况。 -category: reference ---- - -# DROP VIEW - -`DROP VIEW` 语句用于从当前所选定的数据库中删除视图对象。视图所引用的基表不受影响。 - -## 语法图 - -**DropViewStmt:** - -![DropViewStmt](/media/sqlgram/DropViewStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -CREATE VIEW v1 AS SELECT * FROM t1 WHERE c1 > 2; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM v1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP VIEW v1; -``` - -``` -Query OK, 0 rows affected (0.23 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`DROP VIEW` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## See also - -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [CREATE VIEW](/v3.1/reference/sql/statements/create-view.md) diff --git a/v3.1/reference/sql/statements/execute.md b/v3.1/reference/sql/statements/execute.md deleted file mode 100644 index f74dfe74f324..000000000000 --- a/v3.1/reference/sql/statements/execute.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: EXECUTE -summary: TiDB 数据库中 EXECUTE 的使用概况。 -category: reference ---- - -# EXECUTE - -`EXECUTE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**ExecuteStmt:** - -![ExecuteStmt](/media/sqlgram/ExecuteStmt.png) - -**Identifier:** - -![Identifier](/media/sqlgram/Identifier.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`EXECUTE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [PREPARE](/v3.1/reference/sql/statements/prepare.md) -* [DEALLOCATE](/v3.1/reference/sql/statements/deallocate.md) diff --git a/v3.1/reference/sql/statements/explain-analyze.md b/v3.1/reference/sql/statements/explain-analyze.md deleted file mode 100644 index 1ba87b586555..000000000000 --- a/v3.1/reference/sql/statements/explain-analyze.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: EXPLAIN ANALYZE -summary: TiDB 数据库中 EXPLAIN ANALYZE 的使用概况。 -category: reference ---- - -# EXPLAIN ANALYZE - -`EXPLAIN ANALYZE` 语句的工作方式类似于 `EXPLAIN`，主要区别在于前者实际上会执行语句。这样可以将查询计划中的估计值与执行时所遇到的实际值进行比较。如果估计值与实际值显著不同，那么应考虑在受影响的表上运行 `ANALYZE TABLE`。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN ANALYZE SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+---------------------------+ -| id | count | task | operator info | execution info | -+-------------+-------+------+--------------------+---------------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | time:0ns, loops:0, rows:0 | -+-------------+-------+------+--------------------+---------------------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN ANALYZE SELECT * FROM t1; -``` - -``` -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| id | count | task | operator info | execution info | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -| TableReader_5 | 10000.00 | root | data:TableScan_4 | time:931.759µs, loops:2, rows:3 | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | time:0s, loops:0, rows:3 | -+-------------------+----------+------+-------------------------------------------------------------+----------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -该语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/v3.1/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN](/v3.1/reference/sql/statements/explain.md) -* [ANALYZE TABLE](/v3.1/reference/sql/statements/analyze-table.md) -* [TRACE](/v3.1/reference/sql/statements/trace.md) diff --git a/v3.1/reference/sql/statements/explain.md b/v3.1/reference/sql/statements/explain.md deleted file mode 100644 index dd87c4d99d68..000000000000 --- a/v3.1/reference/sql/statements/explain.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: EXPLAIN -summary: TiDB 数据库中 EXPLAIN 的使用概况。 -category: reference ---- - -# EXPLAIN - -`EXPLAIN` 语句仅用于显示查询的执行计划，而不执行查询。`EXPLAIN ANALYZE` 可执行查询，补充 `EXPLAIN` 语句。如果 `EXPLAIN` 的输出与预期结果不匹配，可考虑在查询的每个表上执行 `ANALYZE TABLE`。 - -语句 `DESC` 和 `DESCRIBE` 是 `EXPLAIN` 的别名。`EXPLAIN ` 的替代用法记录在 [`SHOW [FULL] COLUMNS FROM`](/v3.1/reference/sql/statements/show-columns-from.md) 下。 - -## 语法图 - -**ExplainSym:** - -![ExplainSym](/media/sqlgram/ExplainSym.png) - -**ExplainStmt:** - -![ExplainStmt](/media/sqlgram/ExplainStmt.png) - -**ExplainableStmt:** - -![ExplainableStmt](/media/sqlgram/ExplainableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT 1; -``` - -``` -+-------------------+-------+------+---------------+ -| id | count | task | operator info | -+-------------------+-------+------+---------------+ -| Projection_3 | 1.00 | root | 1 | -| └─TableDual_4 | 1.00 | root | rows:1 | -+-------------------+-------+------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESC SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DESCRIBE SELECT * FROM t1 WHERE id = 1; -``` - -``` -+-------------+-------+------+--------------------+ -| id | count | task | operator info | -+-------------+-------+------+--------------------+ -| Point_Get_1 | 1.00 | root | table:t1, handle:1 | -+-------------+-------+------+--------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN INSERT INTO t1 (c1) VALUES (4); -``` - -``` -ERROR 1105 (HY000): Unsupported type *core.Insert -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN UPDATE t1 SET c1=5 WHERE c1=3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXPLAIN DELETE FROM t1 WHERE c1=3; -``` - -``` -+---------------------+----------+------+-------------------------------------------------------------+ -| id | count | task | operator info | -+---------------------+----------+------+-------------------------------------------------------------+ -| TableReader_6 | 10.00 | root | data:Selection_5 | -| └─Selection_5 | 10.00 | cop | eq(test.t1.c1, 3) | -| └─TableScan_4 | 10000.00 | cop | table:t1, range:[-inf,+inf], keep order:false, stats:pseudo | -+---------------------+----------+------+-------------------------------------------------------------+ -3 rows in set (0.00 sec) -``` - -如果未指定 `FORMAT`，或未指定 `FORMAT ="row"`，那么 `EXPLAIN` 语句将以表格格式输出结果。更多信息，可参阅 [Understand the Query Execution Plan](https://pingcap.com/docs/v3.1/reference/performance/understanding-the-query-execution-plan/)。 - -除 MySQL 标准结果格式外，TiDB 还支持 DotGraph。需按照下列所示指定 `FORMAT ="dot"`： - -{{< copyable "sql" >}} - -```sql -create table t(a bigint, b bigint); -desc format = "dot" select A.a, B.b from t A join t B on A.a > B.b where A.a < 10; -``` - -```+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dot contents | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| -digraph HashRightJoin_7 { -subgraph cluster7{ -node [style=filled, color=lightgrey] -color=black -label = "root" -"HashRightJoin_7" -> "TableReader_10" -"HashRightJoin_7" -> "TableReader_12" -} -subgraph cluster9{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"Selection_9" -> "TableScan_8" -} -subgraph cluster11{ -node [style=filled, color=lightgrey] -color=black -label = "cop" -"TableScan_11" -} -"TableReader_10" -> "Selection_9" -"TableReader_12" -> "TableScan_11" -} - | -+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -如果你的计算机上安装了 `dot` 程序（在 `graphviz` 包中），可使用以下方法生成 PNG 文件： - -{{< copyable "shell-regular" >}} - -```bash -dot xx.dot -T png -O -``` - -The `xx.dot` is the result returned by the above statement. - -如果你的计算机上未安装 `dot` 程序，可将结果复制到 [本网站](http://www.webgraphviz.com/) 以获取树形图： - -![Explain Dot](/media/explain_dot.png) - -## MySQL 兼容性 - -* `EXPLAIN` 的格式和 TiDB 中潜在的执行计划都与 MySQL 有很大不同。 -* TiDB 不像 MySQL 那样支持 `EXPLAIN FORMAT = JSON`。 -* TiDB 目前不支持插入语句的 `EXPLAIN`。 - -## 另请参阅 - -* [Understanding the Query Execution Plan](/v3.1/reference/performance/understanding-the-query-execution-plan.md) -* [EXPLAIN ANALYZE](/v3.1/reference/sql/statements/explain-analyze.md) -* [ANALYZE TABLE](/v3.1/reference/sql/statements/analyze-table.md) -* [TRACE](/v3.1/reference/sql/statements/trace.md) diff --git a/v3.1/reference/sql/statements/flush-privileges.md b/v3.1/reference/sql/statements/flush-privileges.md deleted file mode 100644 index ca81b4c66c08..000000000000 --- a/v3.1/reference/sql/statements/flush-privileges.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: FLUSH PRIVILEGES -summary: TiDB 数据库中 FLUSH PRIVILEGES 的使用概况。 -category: reference ---- - -# FLUSH PRIVILEGES - -`FLUSH PRIVILEGES` 语句可触发 TiDB 从权限表中重新加载权限的内存副本。在对如 `mysql.user` 一类的表进行手动编辑后，应当执行 `FLUSH PRIVILEGES`。使用如 `GRANT` 或 `REVOKE` 一类的权限语句后，不需要执行 `FLUSH PRIVILEGES` 语句。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -FLUSH PRIVILEGES; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`FLUSH PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [GRANT ](/v3.1/reference/sql/statements/grant-privileges.md) -* [REVOKE](/v3.1/reference/sql/statements/revoke-privileges.md) -* [Privilege Management](/v3.1/reference/security/privilege-system.md) diff --git a/v3.1/reference/sql/statements/flush-status.md b/v3.1/reference/sql/statements/flush-status.md deleted file mode 100644 index db488f322292..000000000000 --- a/v3.1/reference/sql/statements/flush-status.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: FLUSH STATUS -summary: TiDB 数据库中 FLUSH STATUS 的使用概况。 -category: reference ---- - -# FLUSH STATUS - -`FLUSH STATUS` 语句用于提供 MySQL 兼容性，但在 TiDB 上并无作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -show global status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -flush status; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| ddl_schema_version | 141 | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `FLUSH STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] STATUS](/v3.1/reference/sql/statements/show-status.md) diff --git a/v3.1/reference/sql/statements/flush-tables.md b/v3.1/reference/sql/statements/flush-tables.md deleted file mode 100644 index dc635f231575..000000000000 --- a/v3.1/reference/sql/statements/flush-tables.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: FLUSH TABLES -summary: TiDB 数据库中 FLUSH TABLES 的使用概况。 -category: reference ---- - -# FLUSH TABLES - -`FLUSH TABLES` 语句用于提供 MySQL 兼容性，但在 TiDB 中并无有效用途。 - -## 语法图 - -**FlushStmt:** - -![FlushStmt](/media/sqlgram/FlushStmt.png) - -**NoWriteToBinLogAliasOpt:** - -![NoWriteToBinLogAliasOpt](/media/sqlgram/NoWriteToBinLogAliasOpt.png) - -**FlushOption:** - -![FlushOption](/media/sqlgram/FlushOption.png) - -**TableOrTables:** - -![TableOrTables](/media/sqlgram/TableOrTables.png) - -**TableNameListOpt:** - -![TableNameListOpt](/media/sqlgram/TableNameListOpt.png) - -**WithReadLockOpt:** - -![WithReadLockOpt](/media/sqlgram/WithReadLockOpt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -FLUSH TABLES; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -FLUSH TABLES WITH READ LOCK; -``` - -``` -ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported. Please use @@tidb_snapshot -``` - -## MySQL 兼容性 - -* TiDB 没有 MySQL 中的表缓存这一概念。所以，`FLUSH TABLES` 因 MySQL 兼容性会在 TiDB 中解析出但会被忽略掉。 -* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads] 来实现锁表。 - -## 另请参阅 - -* [Read historical data](/v3.1/how-to/get-started/read-historical-data.md) diff --git a/v3.1/reference/sql/statements/grant-privileges.md b/v3.1/reference/sql/statements/grant-privileges.md deleted file mode 100644 index 811b5a4a9f7f..000000000000 --- a/v3.1/reference/sql/statements/grant-privileges.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: GRANT -summary: TiDB 数据库中 GRANT 的使用概况。 -category: reference ---- - -# GRANT - -`GRANT ` 语句用于为 TiDB 中已存在的用户分配权限。TiDB 中的权限系统同 MySQL 一样，都基于数据库/表模式来分配凭据。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* 与 MySQL 类似，`USAGE` 权限表示登录 TiDB 服务器的能力。 -* 目前不支持列级权限。 -* 与 MySQL 类似，不存在 `NO_AUTO_CREATE_USER` sql 模式时，`GRANT` 语句将在用户不存在时自动创建一个空密码的新用户。删除此 sql-mode（默认情况下已启用）会带来安全风险。 - -## 另请参阅 - -* [REVOKE ](/v3.1/reference/sql/statements/revoke-privileges.md) -* [SHOW GRANTS](/v3.1/reference/sql/statements/show-grants.md) -* [Privilege Management](/v3.1/reference/security/privilege-system.md) diff --git a/v3.1/reference/sql/statements/insert.md b/v3.1/reference/sql/statements/insert.md deleted file mode 100644 index 8b455961a201..000000000000 --- a/v3.1/reference/sql/statements/insert.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: INSERT -summary: TiDB 数据库中 INSERT 的使用概况。 -category: reference ---- - -# INSERT - -使用 `INSERT` 语句在表中插入新行。 - -## 语法图 - -**InsertIntoStmt:** - -![InsertIntoStmt](/media/sqlgram/InsertIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IgnoreOptional:** - -![IgnoreOptional](/media/sqlgram/IgnoreOptional.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t2 LIKE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (a) VALUES (1); -``` - -``` -Query OK, 1 row affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t2 SELECT * FROM t1; -``` - -``` -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -+------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t2 VALUES (2),(3),(4); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t2; -``` - -``` -+------+ -| a | -+------+ -| 1 | -| 1 | -| 2 | -| 3 | -| 4 | -+------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`INSERT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/v3.1/reference/sql/statements/delete.md) -* [SELECT](/v3.1/reference/sql/statements/select.md) -* [UPDATE](/v3.1/reference/sql/statements/update.md) -* [REPLACE](/v3.1/reference/sql/statements/replace.md) diff --git a/v3.1/reference/sql/statements/kill.md b/v3.1/reference/sql/statements/kill.md deleted file mode 100644 index 0f244e379e10..000000000000 --- a/v3.1/reference/sql/statements/kill.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: KILL [TIDB] -summary: TiDB 数据库中 KILL [TIDB] 的使用概况。 -category: reference ---- - -# KILL [TIDB] - -`KILL TIDB` 语句用于终止 TiDB 中的连接。 - -按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。 - -## 语法图 - -**KillStmt:** - -![KillStmt](/media/sqlgram/KillStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW PROCESSLIST; -``` - -``` -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -KILL TIDB 2; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -* `KILL TIDB` 语句是 TiDB 的扩展语法。如果正尝试终止的会话位于同一个 TiDB 服务器上，可在配置文件里设置 [`compatible-kill-query = true`](/v3.1/reference/configuration/tidb-server/configuration-file.md#compatible-kill-query)。 - -## 另请参阅 - -* [SHOW \[FULL\] PROCESSLIST](/v3.1/reference/sql/statements/show-processlist.md) diff --git a/v3.1/reference/sql/statements/load-data.md b/v3.1/reference/sql/statements/load-data.md deleted file mode 100644 index 69667d91515d..000000000000 --- a/v3.1/reference/sql/statements/load-data.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: LOAD DATA -summary: TiDB 数据库中 LOAD DATA 的使用概况。 -category: reference ---- - -# LOAD DATA - -`LOAD DATA` 语句用于将数据批量加载到 TiDB 表中。 - -## 语法图 - -**LoadDataStmt:** - -![LoadDataStmt](/media/sqlgram/LoadDataStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE trips ( - -> trip_id bigint NOT NULL PRIMARY KEY AUTO_INCREMENT, - -> duration integer not null, - -> start_date datetime, - -> end_date datetime, - -> start_station_number integer, - -> start_station varchar(255), - -> end_station_number integer, - -> end_station varchar(255), - -> bike_number varchar(255), - -> member_type varchar(255) - -> ); -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -LOAD DATA LOCAL INFILE '/mnt/evo970/data-sets/bikeshare-data/2017Q4-capitalbikeshare-tripdata.csv' INTO TABLE trips FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\r\n' IGNORE 1 LINES (duration, start_date, end_date, start_station_number, start_station, end_station_number, end_station, bike_number, member_type); -``` - -``` -Query OK, 815264 rows affected (39.63 sec) -Records: 815264 Deleted: 0 Skipped: 0 Warnings: 0 -``` - -## MySQL 兼容性 - -* 默认情况下，TiDB 每 20,000 行会进行一次提交。这类似于 MySQL NDB Cluster，但并非 InnoDB 存储引擎的默认配置。 - -> **注意：** -> -> 这种拆分事务提交的方式是以打破事务的原子性和隔离性为代价的，使用该特性时，使用者需要保证没有其他对正在处理的表的**任何**操作，并且在出现报错时，需要及时**人工介入，检查数据的一致性和完整性**。因此，不建议在生产环境中使用。 - -## 另请参阅 - -* [INSERT](/v3.1/reference/sql/statements/insert.md) -* [乐观事务模型](/v3.1/reference/transactions/transaction-optimistic.md) diff --git a/v3.1/reference/sql/statements/modify-column.md b/v3.1/reference/sql/statements/modify-column.md deleted file mode 100644 index fba03bacdf61..000000000000 --- a/v3.1/reference/sql/statements/modify-column.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: MODIFY COLUMN -summary: TiDB 数据库中 MODIFY COLUMN 的使用概况。 -category: reference ---- - -# MODIFY COLUMN - -`ALTER TABLE .. MODIFY COLUMN` 语句用于修改已有表上的列，包括列的数据类型和属性。若要同时重命名，可改用 [`CHANGE COLUMN`](/v3.1/reference/sql/statements/change-column.md) 语句。 - -## 语法图 - -**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) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (col1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BIGINT; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `col1` bigint(20) DEFAULT NULL, - PRIMARY KEY (`id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=30001 -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 INT; -``` - -``` -ERROR 1105 (HY000): unsupported modify column length 11 is less than origin 20 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BLOB; -``` - -``` -ERROR 1105 (HY000): unsupported modify column type 252 not match origin 8 -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 MODIFY col1 BIGINT, MODIFY id BIGINT NOT NULL; -``` - -``` -ERROR 1105 (HY000): can't run multi schema change -``` - -## MySQL 兼容性 - -* 目前不支持使用单个 `ALTER TABLE` 语句进行多个修改。 -* 仅支持特定类型的数据类型更改。例如，支持将 `INTEGER` 改为 `BIGINT`，但不支持将 `BIGINT` 改为 `INTEGER`。不支持将整数改为字符串格式或 BLOB 格式。 -* 不支持修改 decimal 类型的精度。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [ADD COLUMN](/v3.1/reference/sql/statements/add-column.md) -* [DROP COLUMN](/v3.1/reference/sql/statements/drop-column.md) -* [CHANGE COLUMN](/v3.1/reference/sql/statements/change-column.md) diff --git a/v3.1/reference/sql/statements/prepare.md b/v3.1/reference/sql/statements/prepare.md deleted file mode 100644 index 2f1c882a8c59..000000000000 --- a/v3.1/reference/sql/statements/prepare.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: PREPARE -summary: TiDB 数据库中 PREPARE 的使用概况。 -category: reference ---- - -# PREPARE - -`PREPARE` 语句为服务器端预处理语句提供 SQL 接口。 - -## 语法图 - -**PreparedStmt:** - -![PreparedStmt](/media/sqlgram/PreparedStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -PREPARE mystmt FROM 'SELECT ? as num FROM DUAL'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET @number = 5; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -EXECUTE mystmt USING @number; -``` - -``` -+------+ -| num | -+------+ -| 5 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DEALLOCATE PREPARE mystmt; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -## MySQL 兼容性 - -`PREPARE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [EXECUTE](/v3.1/reference/sql/statements/execute.md) -* [DEALLOCATE](/v3.1/reference/sql/statements/deallocate.md) diff --git a/v3.1/reference/sql/statements/recover-table.md b/v3.1/reference/sql/statements/recover-table.md deleted file mode 100644 index 93b4c9845fd5..000000000000 --- a/v3.1/reference/sql/statements/recover-table.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: RECOVER TABLE -category: reference ---- - -# RECOVER TABLE - -`RECOVER TABLE` 的功能是恢复被删除的表及其数据。在 `DROP TABLE` 后，在 GC life time 时间内，可以用 `RECOVER TABLE` 语句恢复被删除的表以及其数据。 - -## 语法 - -{{< copyable "sql" >}} - -```sql -RECOVER TABLE table_name -``` - -{{< copyable "sql" >}} - -```sql -RECOVER TABLE BY JOB ddl_job_id -``` - -## 注意事项 - -如果删除表后并过了 GC lifetime，就不能再用 `RECOVER TABLE` 来恢复被删除的表了，执行 `RECOVER TABLE` 语句会返回类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -对于 3.0.0 及之后的 TiDB 版本，不推荐在使用 TiDB Binlog 的情况下使用 `RECOVER TABLE` 功能。 - -TiDB Binlog 在 3.0.1 支持 `RECOVER TABLE` 后，可在下面的情况下使用 `RECOVER TABLE`： - -* 3.0.1+ 版本的 TiDB Binlog -* 主从集群都使用 TiDB 3.0 -* 从集群 GC lifetime 一定要长于主集群（不过由于上下游同步的延迟，可能也会造成下游 recover 失败） - -### TiDB Binlog 同步错误处理 - -当使用 TiDB Binlog 同步工具时，上游 TiDB 使用 `RECOVER TABLE` 后，TiDB Binlog 可能会因为下面几个原因造成同步中断： - -* 下游数据库不支持 `RECOVER TABLE` 语句。类似错误：`check the manual that corresponds to your MySQL server version for the right syntax to use near 'RECOVER TABLE table_name'`。 - -* 上下游数据库的 GC lifetime 不一样。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -* 上下游数据库的同步延迟。类似错误：`snapshot is older than GC safe point 2019-07-10 13:45:57 +0800 CST`。 - -只能通过重新[全量导入被删除的表](/v3.1/reference/tools/user-guide.md#tidb-集群数据的全量备份及恢复-1)来恢复 TiDB Binlog 的数据同步。 - -## 示例 - -- 根据表名恢复被删除的表。 - - {{< copyable "sql" >}} - - ```sql - DROP TABLE t; - ``` - - {{< copyable "sql" >}} - - ```sql - RECOVER TABLE t; - ``` - - 根据表名恢复被删除的表需满足以下条件： - - - 最近 DDL JOB 历史中找到的第一个 `DROP TABLE` 操作，且 - - `DROP TABLE` 所删除的表的名称与 `RECOVER TABLE` 语句指定表名相同 - -- 根据删除表时的 DDL JOB ID 恢复被删除的表。 - - 如果第一次删除表 t 后，又新建了一个表 t，然后又把新建的表 t 删除了，此时如果想恢复最开始删除的表 t, 就需要用到指定 DDL JOB ID 的语法了。 - - {{< copyable "sql" >}} - - ```sql - DROP TABLE t; - ``` - - {{< copyable "sql" >}} - - ```sql - ADMIN SHOW DDL JOBS 1; - ``` - - 上面这个语句用来查找删除表 t 时的 DDL JOB ID，这里是 53： - - ``` - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - | JOB_ID | DB_NAME | TABLE_NAME | JOB_TYPE | SCHEMA_STATE | SCHEMA_ID | TABLE_ID | ROW_COUNT | START_TIME | STATE | - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - | 53 | test | | drop table | none | 1 | 41 | 0 | 2019-07-10 13:23:18.277 +0800 CST | synced | - +--------+---------+------------+------------+--------------+-----------+----------+-----------+-----------------------------------+--------+ - ``` - - {{< copyable "sql" >}} - - ```sql - RECOVER TABLE BY JOB 53; - ``` - - 根据删除表时的 DDL JOB ID 恢复被删除的表，会直接用 DDL JOB ID 找到被删除表进行恢复。如果指定的 DDL JOB ID 的 DDL JOB 不是 `DROP TABLE` 类型，会报错。 - -## 原理 - -TiDB 在删除表时，实际上只删除了表的元信息，并将需要删除的表数据（行数据和索引数据）写一条数据到 `mysql.gc_delete_range` 表。TiDB 后台的 GC Worker 会定期从 `mysql.gc_delete_range` 表中取出超过 GC lifetime 相关范围的 key 进行删除。 - -所以，RECOVER TABLE 只需要在 GC Worker 还没删除表数据前，恢复表的元信息并删除 `mysql.gc_delete_range` 表中相应的行记录就可以了。恢复表的元信息可以用 TiDB 的快照读实现。具体的快照读内容可以参考[读取历史数据](/v3.1/how-to/get-started/read-historical-data.md)文档。 - -TiDB 中表的恢复是通过快照读获取表的元信息后，再走一次类似于 `CREATE TABLE` 的建表流程，所以 `RECOVER TABLE` 实际上也是一种 DDL。 diff --git a/v3.1/reference/sql/statements/rename-index.md b/v3.1/reference/sql/statements/rename-index.md deleted file mode 100644 index 1fa418b5ac45..000000000000 --- a/v3.1/reference/sql/statements/rename-index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: RENAME INDEX -summary: TiDB 数据库中 RENAME INDEX 的使用概况。 -category: reference ---- - -# RENAME INDEX - -`ALTER TABLE .. RENAME INDEX` 语句用于对已有索引进行重命名。这在 TiDB 中是即时操作的，仅需更改元数据。 - -## 语法图 - -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**KeyOrIndex:** - -![KeyOrIndex](/media/sqlgram/KeyOrIndex.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL, INDEX col1 (c1)); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `col1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 RENAME INDEX col1 TO c1; -``` - -``` -Query OK, 0 rows affected (0.09 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `c1` int(11) NOT NULL, - PRIMARY KEY (`id`), - KEY `c1` (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME INDEX` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [CREATE INDEX](/v3.1/reference/sql/statements/create-index.md) -* [DROP INDEX](/v3.1/reference/sql/statements/drop-index.md) -* [SHOW INDEX](/v3.1/reference/sql/statements/show-index.md) diff --git a/v3.1/reference/sql/statements/rename-table.md b/v3.1/reference/sql/statements/rename-table.md deleted file mode 100644 index d1db0881594c..000000000000 --- a/v3.1/reference/sql/statements/rename-table.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: RENAME TABLE -summary: TiDB 数据库中 RENAME TABLE 的使用概况。 -category: reference ---- - -# RENAME TABLE - -`RENAME TABLE` 语句用于对已有表进行重命名。 - -## 语法图 - -**RenameTableStmt:** - -![RenameTableStmt](/media/sqlgram/RenameTableStmt.png) - -**TableToTable:** - -![TableToTable](/media/sqlgram/TableToTable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -+----------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -RENAME TABLE t1 TO t2; -``` - -``` -Query OK, 0 rows affected (0.08 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------+ -| Tables_in_test | -+----------------+ -| t2 | -+----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`RENAME TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW TABLES](/v3.1/reference/sql/statements/show-tables.md) -* [ALTER TABLE](/v3.1/reference/sql/statements/alter-table.md) diff --git a/v3.1/reference/sql/statements/replace.md b/v3.1/reference/sql/statements/replace.md deleted file mode 100644 index 9dcd6fbd9f80..000000000000 --- a/v3.1/reference/sql/statements/replace.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: REPLACE -summary: TiDB 数据库中 REPLACE 的使用概况。 -category: reference ---- - -# REPLACE - -从语义上看，`REPLACE` 语句是 `DELETE` 语句和 `INSERT` 语句的结合，可用于简化应用程序代码。 - -## 语法图 - -**ReplaceIntoStmt:** - -![ReplaceIntoStmt](/media/sqlgram/ReplaceIntoStmt.png) - -**PriorityOpt:** - -![PriorityOpt](/media/sqlgram/PriorityOpt.png) - -**IntoOpt:** - -![IntoOpt](/media/sqlgram/IntoOpt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**InsertValues:** - -![InsertValues](/media/sqlgram/InsertValues.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REPLACE INTO t1 (id, c1) VALUES(3, 99); -``` - -``` -Query OK, 2 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 99 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`REPLACE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [DELETE](/v3.1/reference/sql/statements/delete.md) -* [INSERT](/v3.1/reference/sql/statements/insert.md) -* [SELECT](/v3.1/reference/sql/statements/select.md) -* [UPDATE](/v3.1/reference/sql/statements/update.md) diff --git a/v3.1/reference/sql/statements/revoke-privileges.md b/v3.1/reference/sql/statements/revoke-privileges.md deleted file mode 100644 index 892b87a604a3..000000000000 --- a/v3.1/reference/sql/statements/revoke-privileges.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: REVOKE -summary: TiDB 数据库中 REVOKE 的使用概况。 -category: reference ---- - -# REVOKE - -`REVOKE ` 语句用于删除已有用户的权限。 - -## 语法图 - -**GrantStmt:** - -![GrantStmt](/media/sqlgram/GrantStmt.png) - -**PrivElemList:** - -![PrivElemList](/media/sqlgram/PrivElemList.png) - -**PrivElem:** - -![PrivElem](/media/sqlgram/PrivElem.png) - -**PrivType:** - -![PrivType](/media/sqlgram/PrivType.png) - -**ObjectType:** - -![ObjectType](/media/sqlgram/ObjectType.png) - -**PrivLevel:** - -![PrivLevel](/media/sqlgram/PrivLevel.png) - -**UserSpecList:** - -![UserSpecList](/media/sqlgram/UserSpecList.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE USER newuser IDENTIFIED BY 'mypassword'; -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT ALL ON test.* TO 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------------------+ -| Grants for newuser@% | -+-------------------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -| GRANT ALL PRIVILEGES ON test.* TO 'newuser'@'%' | -+-------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -REVOKE ALL ON test.* FROM 'newuser'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'newuser'; -``` - -``` -+-------------------------------------+ -| Grants for newuser@% | -+-------------------------------------+ -| GRANT USAGE ON *.* TO 'newuser'@'%' | -+-------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -DROP USER newuser; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR newuser; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'newuser' on host '%' -``` - -## MySQL 兼容性 - -`REVOKE ` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [GRANT ](/v3.1/reference/sql/statements/grant-privileges.md) -* [SHOW GRANTS](/v3.1/reference/sql/statements/show-grants.md) -* [Privilege Management](/v3.1/reference/security/privilege-system.md) diff --git a/v3.1/reference/sql/statements/rollback.md b/v3.1/reference/sql/statements/rollback.md deleted file mode 100644 index 239a8b54a91e..000000000000 --- a/v3.1/reference/sql/statements/rollback.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: ROLLBACK -summary: TiDB 数据库中 ROLLBACK 的使用概况。 -category: reference ---- - -# ROLLBACK - -`ROLLBACK` 语句用于还原 TiDB 内当前事务中的所有更改，作用与 `COMMIT` 语句相反。 - -## 语法图 - -**Statement:** - -![Statement](/media/sqlgram/Statement.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -Empty set (0.01 sec) -``` - -## MySQL 兼容性 - -`ROLLBACK` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v3.1/reference/sql/statements/commit.md) -* [BEGIN](/v3.1/reference/sql/statements/begin.md) -* [START TRANSACTION](/v3.1/reference/sql/statements/start-transaction.md) diff --git a/v3.1/reference/sql/statements/select.md b/v3.1/reference/sql/statements/select.md deleted file mode 100644 index e29649208502..000000000000 --- a/v3.1/reference/sql/statements/select.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: SELECT -summary: TiDB 数据库中 SELECT 的使用概况。 -category: reference ---- - -# SELECT - -`SELECT` 语句用于从 TiDB 读取数据。 - -## 语法图 - -**SelectStmt:** - -![SelectStmt](/media/sqlgram/SelectStmt.png) - -**FromDual:** - -![FromDual](/media/sqlgram/FromDual.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtOpts:** - -![SelectStmtOpts](/media/sqlgram/SelectStmtOpts.png) - -**SelectStmtFieldList:** - -![SelectStmtFieldList](/media/sqlgram/SelectStmtFieldList.png) - -**TableRefsClause:** - -![TableRefsClause](/media/sqlgram/TableRefsClause.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -**SelectStmtGroup:** - -![SelectStmtGroup](/media/sqlgram/SelectStmtGroup.png) - -**HavingClause:** - -![HavingClause](/media/sqlgram/HavingClause.png) - -**OrderByOptional:** - -![OrderByOptional](/media/sqlgram/OrderByOptional.png) - -**SelectStmtLimit:** - -![SelectStmtLimit](/media/sqlgram/SelectStmtLimit.png) - -**SelectLockOpt:** - -![SelectLockOpt](/media/sqlgram/SelectLockOpt.png) - -## 语法元素说明 - -|语法元素 | 说明 | -| --------------------- | -------------------------------------------------- | -|`ALL`、`DISTINCT`、`DISTINCTROW` | 查询结果集中可能会包含重复值。指定 DISTINCT/DISTINCTROW 则在查询结果中过滤掉重复的行；指定 ALL 则列出所有的行。默认为 ALL。| -|`HIGH_PRIORITY` | 该语句为高优先级语句，TiDB 在执行阶段会优先处理这条语句| -|`SQL_CALC_FOUND_ROWS` | TiDB 出于兼容性解析这个语法，但是不做任何处理| -|`SQL_CACHE`、`SQL_NO_CACHE` | 是否把请求结果缓存到 TiKV (RocksDB) 的 `BlockCache` 中。对于一次性的大数据量的查询，比如 `count(*)` 查询，为了避免冲掉 `BlockCache` 中用户的热点数据，建议填上 `SQL_NO_CACHE` | -|`STRAIGHT_JOIN`|`STRAIGHT_JOIN` 会强制优化器按照 `FROM` 子句中所使用的表的顺序做联合查询。当优化器选择的 Join 顺序并不优秀时，你可以使用这个语法来加速查询的执行| -|`select_expr` | 投影操作列表，一般包括列名、表达式，或者是用 '\*' 表示全部列| -|`FROM table_references` | 表示数据来源，数据来源可以是一个表（`select * from t;`）或者是多个表 (`select * from t1 join t2;`) 或者是0个表 (`select 1+1 from dual;`, 等价于 `select 1+1;`)| -|`WHERE where_condition` | Where 子句用于设置过滤条件，查询结果中只会包含满足条件的数据| -|`GROUP BY` | GroupBy 子句用于对查询结果集进行分组| -|`HAVING where_condition` | Having 子句与 Where 子句作用类似，Having 子句可以让过滤 GroupBy 后的各种数据，Where 子句用于在聚合前过滤记录。| -|`ORDER BY` | OrderBy 子句用于指定结果排序顺序，可以按照列、表达式或者是 `select_expr` 列表中某个位置的字段进行排序。| -|`LIMIT` | Limit 子句用于限制结果条数。Limit 接受一个或两个数字参数，如果只有一个参数，那么表示返回数据的最大行数；如果是两个参数，那么第一个参数表示返回数据的第一行的偏移量（第一行数据的偏移量是 0），第二个参数指定返回数据的最大条目数。| -|`FOR UPDATE` | 对查询结果集所有行上锁（对于在查询条件内，但是不在结果集的行，将不会加锁，如事务启动后由其他事务写入的行），以监测其他事务对这些的并发修改。使用[乐观事务模型](/v3.1/reference/transactions/transaction-optimistic.md)时，语句执行期间不会检测锁，因此，不会像 PostgreSQL 之类的数据库一样，在当前事务结束前阻止其他事务执行 `UPDATE`、`DELETE` 和 `SELECT FOR UPDATE`。在事务的提交阶段 `SELECT FOR UPDATE` 读到的行，也会进行两阶段提交，因此，它们也可以参与事务冲突检测。如发生写入冲突，那么包含 `SELECT FOR UPDATE` 语句的事务会提交失败。如果没有冲突，事务将成功提交，当提交结束时，这些被加锁的行，会产生一个新版本，可以让其他尚未提交的事务，在将来提交时发现写入冲突。若使用悲观事务，则行为与其他数据库基本相同，不一致之处参考[和 MySQL InnoDB 的差异](/v3.1/reference/transactions/transaction-pessimistic.md#和-mysql-innodb-的差异)。 | -|`LOCK IN SHARE MODE` | TiDB 出于兼容性解析这个语法，但是不做任何处理| - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.03 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -| 4 | 4 | -| 5 | 5 | -+----+----+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SELECT` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v3.1/reference/sql/statements/insert.md) -* [DELETE](/v3.1/reference/sql/statements/delete.md) -* [UPDATE](/v3.1/reference/sql/statements/update.md) -* [REPLACE](/v3.1/reference/sql/statements/replace.md) diff --git a/v3.1/reference/sql/statements/set-names.md b/v3.1/reference/sql/statements/set-names.md deleted file mode 100644 index a2b41c71d9c6..000000000000 --- a/v3.1/reference/sql/statements/set-names.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: SET [NAMES|CHARACTER SET] -summary: TiDB 数据库中 SET [NAMES|CHARACTER SET] 的使用概况。 -category: reference ---- - -# SET [NAMES|CHARACTER SET] - -`SET NAMES`，`SET CHARACTER SET` 和 `SET CHARSET` 语句用于修改当前连接的变量 `character_set_client`，`character_set_results` 和 `character_set_connection`。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET NAMES utf8; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_connection | utf8 | -| character_set_system | utf8 | -| character_set_results | utf8 | -| character_set_client | utf8 | -| character_set_server | utf8mb4 | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET CHARACTER SET utf8mb4; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW VARIABLES LIKE 'character_set%'; -``` - -``` -+--------------------------+--------------------------------------------------------+ -| Variable_name | Value | -+--------------------------+--------------------------------------------------------+ -| character_set_connection | utf8mb4 | -| character_set_system | utf8 | -| character_set_results | utf8mb4 | -| character_set_client | utf8mb4 | -| character_sets_dir | /usr/local/mysql-5.6.25-osx10.8-x86_64/share/charsets/ | -| character_set_database | utf8mb4 | -| character_set_filesystem | binary | -| character_set_server | utf8mb4 | -+--------------------------+--------------------------------------------------------+ -8 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [NAMES|CHARACTER SET]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/v3.1/reference/sql/statements/show-variables.md) -* [SET ](/v3.1/reference/sql/statements/set-variable.md) -* [Character Set Support](/v3.1/reference/sql/character-set.md) diff --git a/v3.1/reference/sql/statements/set-password.md b/v3.1/reference/sql/statements/set-password.md deleted file mode 100644 index e9fbcab5f759..000000000000 --- a/v3.1/reference/sql/statements/set-password.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: SET PASSWORD -summary: TiDB 数据库中 SET PASSWORD 的使用概况。 -category: reference ---- - -# SET PASSWORD - -`SET PASSWORD` 语句用于更改 TiDB 系统数据库中的用户密码。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SET PASSWORD='test'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER 'newuser' IDENTIFIED BY 'test'; -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET PASSWORD FOR newuser = 'test'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET PASSWORD FOR newuser = PASSWORD('test'); -``` - -上述语法是早期 MySQL 版本的过时语法。 - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER newuser; -``` - -```+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for newuser@% | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'newuser'@'%' IDENTIFIED WITH 'mysql_native_password' AS '*94BDCEBE19083CE2A1F959FD02F964C7AF4CFC29' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET PASSWORD` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE USER](/v3.1/reference/sql/statements/create-user.md) -* [Privilege Management](/v3.1/reference/security/privilege-system.md) diff --git a/v3.1/reference/sql/statements/set-transaction.md b/v3.1/reference/sql/statements/set-transaction.md deleted file mode 100644 index 7edbca7740da..000000000000 --- a/v3.1/reference/sql/statements/set-transaction.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: SET TRANSACTION -summary: TiDB 数据库中 SET TRANSACTION 的使用概况。 -category: reference ---- - -# SET TRANSACTION - -`SET TRANSACTION` 语句用于在 `GLOBAL` 或 `SESSION` 的基础上更改当前的隔离级别，是 `SET transaction_isolation ='new-value'` 的替代语句，提供 MySQL 和 SQL 标准的兼容性。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -**TransactionChar:** - -![TransactionChar](/media/sqlgram/TransactionChar.png) - -**IsolationLevel:** - -![IsolationLevel](/media/sqlgram/IsolationLevel.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+----------------+ -| Variable_name | Value | -+-----------------------+----------------+ -| transaction_isolation | READ-COMMITTED | -+-----------------------+----------------+ -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION transaction_isolation = 'REPEATABLE-READ'; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES like 'transaction_isolation'; -``` - -``` -+-----------------------+-----------------+ -| Variable_name | Value | -+-----------------------+-----------------+ -| transaction_isolation | REPEATABLE-READ | -+-----------------------+-----------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 支持仅在语法中将事务设置为只读的功能。 -* 不支持隔离级别 `READ-UNCOMMITTED` 和 `SERIALIZABLE`。 -* 隔离级别 `REPEATABLE-READ` 在技术上属于快照隔离（Snapshot Isolation）。在 TiDB 中称为 `REPEATABLE-READ` 是为了和 MySQL 保持一致。 - -## 另请参阅 - -* [SET \[GLOBAL|SESSION\] ](/v3.1/reference/sql/statements/set-variable.md) -* [Isolation Levels](/v3.1/reference/transactions/transaction-isolation.md) diff --git a/v3.1/reference/sql/statements/set-variable.md b/v3.1/reference/sql/statements/set-variable.md deleted file mode 100644 index ac8d0385522f..000000000000 --- a/v3.1/reference/sql/statements/set-variable.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: SET [GLOBAL|SESSION] -summary: TiDB 数据库中 SET [GLOBAL|SESSION] 的使用概况。 -category: reference ---- - -# SET [GLOBAL|SESSION] - -`SET [GLOBAL|SESSION]` 语句用于在 `SESSION` 或 `GLOBAL` 的范围内，对某个 TiDB 的内置变量进行更改。需注意，对 `GLOBAL` 变量的更改不适用于已有连接或本地连接，这与 MySQL 类似。只有新会话才会反映值的变化。 - -## 语法图 - -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET GLOBAL sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -``` - -``` -Query OK, 0 rows affected (0.03 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable_name | Value | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| sql_mode | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION | -+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER'; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW SESSION VARIABLES LIKE 'sql_mode'; -``` - -``` -+---------------+-----------------------------------------+ -| Variable_name | Value | -+---------------+-----------------------------------------+ -| sql_mode | STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER | -+---------------+-----------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SET [GLOBAL|SESSION]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW \[GLOBAL|SESSION\] VARIABLES](/v3.1/reference/sql/statements/show-variables.md) diff --git a/v3.1/reference/sql/statements/show-character-set.md b/v3.1/reference/sql/statements/show-character-set.md deleted file mode 100644 index 3ce025d15240..000000000000 --- a/v3.1/reference/sql/statements/show-character-set.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: SHOW CHARACTER SET -summary: TiDB 数据库中 SHOW CHARACTER SET 的使用概况。 -category: reference ---- - -# SHOW CHARACTER SET - -`SHOW CHARACTER SET` 语句提供 TiDB 中可用字符集的静态列表。此列表不反映当前连接或用户的任何属性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**CharsetKw:** - -![CharsetKw](/media/sqlgram/CharsetKw.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW CHARACTER SET; -``` - -``` -+---------+---------------+-------------------+--------+ -| Charset | Description | Default collation | Maxlen | -+---------+---------------+-------------------+--------+ -| utf8 | UTF-8 Unicode | utf8_bin | 3 | -| utf8mb4 | UTF-8 Unicode | utf8mb4_bin | 4 | -| ascii | US ASCII | ascii_bin | 1 | -| latin1 | Latin1 | latin1_bin | 1 | -| binary | binary | binary | 1 | -+---------+---------------+-------------------+--------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CHARACTER SET` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW COLLATION](/v3.1/reference/sql/statements/show-collation.md) diff --git a/v3.1/reference/sql/statements/show-collation.md b/v3.1/reference/sql/statements/show-collation.md deleted file mode 100644 index a89feb2a190e..000000000000 --- a/v3.1/reference/sql/statements/show-collation.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: SHOW COLLATION -summary: TiDB 数据库中 SHOW COLLATION 的使用概况。 -category: reference ---- - -# SHOW COLLATION - -`SHOW COLLATION` 语句用于提供一个静态的排序规则列表，确保与 MySQL 客户端库的兼容性。 - -> **注意:** TiDB 目前仅支持二进制排序规则。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW COLLATION; -``` - -``` -+--------------------------+----------+------+---------+----------+---------+ -| Collation | Charset | Id | Default | Compiled | Sortlen | -+--------------------------+----------+------+---------+----------+---------+ -| big5_chinese_ci | big5 | 1 | Yes | Yes | 1 | -| latin2_czech_cs | latin2 | 2 | | Yes | 1 | -| dec8_swedish_ci | dec8 | 3 | Yes | Yes | 1 | -| cp850_general_ci | cp850 | 4 | Yes | Yes | 1 | -| latin1_german1_ci | latin1 | 5 | | Yes | 1 | -| hp8_english_ci | hp8 | 6 | Yes | Yes | 1 | -| koi8r_general_ci | koi8r | 7 | Yes | Yes | 1 | -| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | -| latin2_general_ci | latin2 | 9 | Yes | Yes | 1 | -| swe7_swedish_ci | swe7 | 10 | Yes | Yes | 1 | -| ascii_general_ci | ascii | 11 | Yes | Yes | 1 | -| ujis_japanese_ci | ujis | 12 | Yes | Yes | 1 | -| sjis_japanese_ci | sjis | 13 | Yes | Yes | 1 | -| cp1251_bulgarian_ci | cp1251 | 14 | | Yes | 1 | -| latin1_danish_ci | latin1 | 15 | | Yes | 1 | -| hebrew_general_ci | hebrew | 16 | Yes | Yes | 1 | -| tis620_thai_ci | tis620 | 18 | Yes | Yes | 1 | -| euckr_korean_ci | euckr | 19 | Yes | Yes | 1 | -| latin7_estonian_cs | latin7 | 20 | | Yes | 1 | -| latin2_hungarian_ci | latin2 | 21 | | Yes | 1 | -| koi8u_general_ci | koi8u | 22 | Yes | Yes | 1 | -| cp1251_ukrainian_ci | cp1251 | 23 | | Yes | 1 | -| gb2312_chinese_ci | gb2312 | 24 | Yes | Yes | 1 | -| greek_general_ci | greek | 25 | Yes | Yes | 1 | -| cp1250_general_ci | cp1250 | 26 | Yes | Yes | 1 | -| latin2_croatian_ci | latin2 | 27 | | Yes | 1 | -| gbk_chinese_ci | gbk | 28 | Yes | Yes | 1 | -| cp1257_lithuanian_ci | cp1257 | 29 | | Yes | 1 | -| latin5_turkish_ci | latin5 | 30 | Yes | Yes | 1 | -| latin1_german2_ci | latin1 | 31 | | Yes | 1 | -| armscii8_general_ci | armscii8 | 32 | Yes | Yes | 1 | -| utf8_general_ci | utf8 | 33 | Yes | Yes | 1 | -| cp1250_czech_cs | cp1250 | 34 | | Yes | 1 | -| ucs2_general_ci | ucs2 | 35 | Yes | Yes | 1 | -| cp866_general_ci | cp866 | 36 | Yes | Yes | 1 | -| keybcs2_general_ci | keybcs2 | 37 | Yes | Yes | 1 | -| macce_general_ci | macce | 38 | Yes | Yes | 1 | -| macroman_general_ci | macroman | 39 | Yes | Yes | 1 | -| cp852_general_ci | cp852 | 40 | Yes | Yes | 1 | -| latin7_general_ci | latin7 | 41 | Yes | Yes | 1 | -| latin7_general_cs | latin7 | 42 | | Yes | 1 | -| macce_bin | macce | 43 | | Yes | 1 | -| cp1250_croatian_ci | cp1250 | 44 | | Yes | 1 | -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| latin1_bin | latin1 | 47 | | Yes | 1 | -| latin1_general_ci | latin1 | 48 | | Yes | 1 | -| latin1_general_cs | latin1 | 49 | | Yes | 1 | -| cp1251_bin | cp1251 | 50 | | Yes | 1 | -| cp1251_general_ci | cp1251 | 51 | Yes | Yes | 1 | -| cp1251_general_cs | cp1251 | 52 | | Yes | 1 | -| macroman_bin | macroman | 53 | | Yes | 1 | -| utf16_general_ci | utf16 | 54 | Yes | Yes | 1 | -| utf16_bin | utf16 | 55 | | Yes | 1 | -| utf16le_general_ci | utf16le | 56 | Yes | Yes | 1 | -| cp1256_general_ci | cp1256 | 57 | Yes | Yes | 1 | -| cp1257_bin | cp1257 | 58 | | Yes | 1 | -| cp1257_general_ci | cp1257 | 59 | Yes | Yes | 1 | -| utf32_general_ci | utf32 | 60 | Yes | Yes | 1 | -| utf32_bin | utf32 | 61 | | Yes | 1 | -| utf16le_bin | utf16le | 62 | | Yes | 1 | -| binary | binary | 63 | Yes | Yes | 1 | -| armscii8_bin | armscii8 | 64 | | Yes | 1 | -| ascii_bin | ascii | 65 | | Yes | 1 | -| cp1250_bin | cp1250 | 66 | | Yes | 1 | -| cp1256_bin | cp1256 | 67 | | Yes | 1 | -| cp866_bin | cp866 | 68 | | Yes | 1 | -| dec8_bin | dec8 | 69 | | Yes | 1 | -| greek_bin | greek | 70 | | Yes | 1 | -| hebrew_bin | hebrew | 71 | | Yes | 1 | -| hp8_bin | hp8 | 72 | | Yes | 1 | -| keybcs2_bin | keybcs2 | 73 | | Yes | 1 | -| koi8r_bin | koi8r | 74 | | Yes | 1 | -| koi8u_bin | koi8u | 75 | | Yes | 1 | -| latin2_bin | latin2 | 77 | | Yes | 1 | -| latin5_bin | latin5 | 78 | | Yes | 1 | -| latin7_bin | latin7 | 79 | | Yes | 1 | -| cp850_bin | cp850 | 80 | | Yes | 1 | -| cp852_bin | cp852 | 81 | | Yes | 1 | -| swe7_bin | swe7 | 82 | | Yes | 1 | -| utf8_bin | utf8 | 83 | | Yes | 1 | -| big5_bin | big5 | 84 | | Yes | 1 | -| euckr_bin | euckr | 85 | | Yes | 1 | -| gb2312_bin | gb2312 | 86 | | Yes | 1 | -| gbk_bin | gbk | 87 | | Yes | 1 | -| sjis_bin | sjis | 88 | | Yes | 1 | -| tis620_bin | tis620 | 89 | | Yes | 1 | -| ucs2_bin | ucs2 | 90 | | Yes | 1 | -| ujis_bin | ujis | 91 | | Yes | 1 | -| geostd8_general_ci | geostd8 | 92 | Yes | Yes | 1 | -| geostd8_bin | geostd8 | 93 | | Yes | 1 | -| latin1_spanish_ci | latin1 | 94 | | Yes | 1 | -| cp932_japanese_ci | cp932 | 95 | Yes | Yes | 1 | -| cp932_bin | cp932 | 96 | | Yes | 1 | -| eucjpms_japanese_ci | eucjpms | 97 | Yes | Yes | 1 | -| eucjpms_bin | eucjpms | 98 | | Yes | 1 | -| cp1250_polish_ci | cp1250 | 99 | | Yes | 1 | -| utf16_unicode_ci | utf16 | 101 | | Yes | 1 | -| utf16_icelandic_ci | utf16 | 102 | | Yes | 1 | -| utf16_latvian_ci | utf16 | 103 | | Yes | 1 | -| utf16_romanian_ci | utf16 | 104 | | Yes | 1 | -| utf16_slovenian_ci | utf16 | 105 | | Yes | 1 | -| utf16_polish_ci | utf16 | 106 | | Yes | 1 | -| utf16_estonian_ci | utf16 | 107 | | Yes | 1 | -| utf16_spanish_ci | utf16 | 108 | | Yes | 1 | -| utf16_swedish_ci | utf16 | 109 | | Yes | 1 | -| utf16_turkish_ci | utf16 | 110 | | Yes | 1 | -| utf16_czech_ci | utf16 | 111 | | Yes | 1 | -| utf16_danish_ci | utf16 | 112 | | Yes | 1 | -| utf16_lithuanian_ci | utf16 | 113 | | Yes | 1 | -| utf16_slovak_ci | utf16 | 114 | | Yes | 1 | -| utf16_spanish2_ci | utf16 | 115 | | Yes | 1 | -| utf16_roman_ci | utf16 | 116 | | Yes | 1 | -| utf16_persian_ci | utf16 | 117 | | Yes | 1 | -| utf16_esperanto_ci | utf16 | 118 | | Yes | 1 | -| utf16_hungarian_ci | utf16 | 119 | | Yes | 1 | -| utf16_sinhala_ci | utf16 | 120 | | Yes | 1 | -| utf16_german2_ci | utf16 | 121 | | Yes | 1 | -| utf16_croatian_ci | utf16 | 122 | | Yes | 1 | -| utf16_unicode_520_ci | utf16 | 123 | | Yes | 1 | -| utf16_vietnamese_ci | utf16 | 124 | | Yes | 1 | -| ucs2_unicode_ci | ucs2 | 128 | | Yes | 1 | -| ucs2_icelandic_ci | ucs2 | 129 | | Yes | 1 | -| ucs2_latvian_ci | ucs2 | 130 | | Yes | 1 | -| ucs2_romanian_ci | ucs2 | 131 | | Yes | 1 | -| ucs2_slovenian_ci | ucs2 | 132 | | Yes | 1 | -| ucs2_polish_ci | ucs2 | 133 | | Yes | 1 | -| ucs2_estonian_ci | ucs2 | 134 | | Yes | 1 | -| ucs2_spanish_ci | ucs2 | 135 | | Yes | 1 | -| ucs2_swedish_ci | ucs2 | 136 | | Yes | 1 | -| ucs2_turkish_ci | ucs2 | 137 | | Yes | 1 | -| ucs2_czech_ci | ucs2 | 138 | | Yes | 1 | -| ucs2_danish_ci | ucs2 | 139 | | Yes | 1 | -| ucs2_lithuanian_ci | ucs2 | 140 | | Yes | 1 | -| ucs2_slovak_ci | ucs2 | 141 | | Yes | 1 | -| ucs2_spanish2_ci | ucs2 | 142 | | Yes | 1 | -| ucs2_roman_ci | ucs2 | 143 | | Yes | 1 | -| ucs2_persian_ci | ucs2 | 144 | | Yes | 1 | -| ucs2_esperanto_ci | ucs2 | 145 | | Yes | 1 | -| ucs2_hungarian_ci | ucs2 | 146 | | Yes | 1 | -| ucs2_sinhala_ci | ucs2 | 147 | | Yes | 1 | -| ucs2_german2_ci | ucs2 | 148 | | Yes | 1 | -| ucs2_croatian_ci | ucs2 | 149 | | Yes | 1 | -| ucs2_unicode_520_ci | ucs2 | 150 | | Yes | 1 | -| ucs2_vietnamese_ci | ucs2 | 151 | | Yes | 1 | -| ucs2_general_mysql500_ci | ucs2 | 159 | | Yes | 1 | -| utf32_unicode_ci | utf32 | 160 | | Yes | 1 | -| utf32_icelandic_ci | utf32 | 161 | | Yes | 1 | -| utf32_latvian_ci | utf32 | 162 | | Yes | 1 | -| utf32_romanian_ci | utf32 | 163 | | Yes | 1 | -| utf32_slovenian_ci | utf32 | 164 | | Yes | 1 | -| utf32_polish_ci | utf32 | 165 | | Yes | 1 | -| utf32_estonian_ci | utf32 | 166 | | Yes | 1 | -| utf32_spanish_ci | utf32 | 167 | | Yes | 1 | -| utf32_swedish_ci | utf32 | 168 | | Yes | 1 | -| utf32_turkish_ci | utf32 | 169 | | Yes | 1 | -| utf32_czech_ci | utf32 | 170 | | Yes | 1 | -| utf32_danish_ci | utf32 | 171 | | Yes | 1 | -| utf32_lithuanian_ci | utf32 | 172 | | Yes | 1 | -| utf32_slovak_ci | utf32 | 173 | | Yes | 1 | -| utf32_spanish2_ci | utf32 | 174 | | Yes | 1 | -| utf32_roman_ci | utf32 | 175 | | Yes | 1 | -| utf32_persian_ci | utf32 | 176 | | Yes | 1 | -| utf32_esperanto_ci | utf32 | 177 | | Yes | 1 | -| utf32_hungarian_ci | utf32 | 178 | | Yes | 1 | -| utf32_sinhala_ci | utf32 | 179 | | Yes | 1 | -| utf32_german2_ci | utf32 | 180 | | Yes | 1 | -| utf32_croatian_ci | utf32 | 181 | | Yes | 1 | -| utf32_unicode_520_ci | utf32 | 182 | | Yes | 1 | -| utf32_vietnamese_ci | utf32 | 183 | | Yes | 1 | -| utf8_unicode_ci | utf8 | 192 | | Yes | 1 | -| utf8_icelandic_ci | utf8 | 193 | | Yes | 1 | -| utf8_latvian_ci | utf8 | 194 | | Yes | 1 | -| utf8_romanian_ci | utf8 | 195 | | Yes | 1 | -| utf8_slovenian_ci | utf8 | 196 | | Yes | 1 | -| utf8_polish_ci | utf8 | 197 | | Yes | 1 | -| utf8_estonian_ci | utf8 | 198 | | Yes | 1 | -| utf8_spanish_ci | utf8 | 199 | | Yes | 1 | -| utf8_swedish_ci | utf8 | 200 | | Yes | 1 | -| utf8_turkish_ci | utf8 | 201 | | Yes | 1 | -| utf8_czech_ci | utf8 | 202 | | Yes | 1 | -| utf8_danish_ci | utf8 | 203 | | Yes | 1 | -| utf8_lithuanian_ci | utf8 | 204 | | Yes | 1 | -| utf8_slovak_ci | utf8 | 205 | | Yes | 1 | -| utf8_spanish2_ci | utf8 | 206 | | Yes | 1 | -| utf8_roman_ci | utf8 | 207 | | Yes | 1 | -| utf8_persian_ci | utf8 | 208 | | Yes | 1 | -| utf8_esperanto_ci | utf8 | 209 | | Yes | 1 | -| utf8_hungarian_ci | utf8 | 210 | | Yes | 1 | -| utf8_sinhala_ci | utf8 | 211 | | Yes | 1 | -| utf8_german2_ci | utf8 | 212 | | Yes | 1 | -| utf8_croatian_ci | utf8 | 213 | | Yes | 1 | -| utf8_unicode_520_ci | utf8 | 214 | | Yes | 1 | -| utf8_vietnamese_ci | utf8 | 215 | | Yes | 1 | -| utf8_general_mysql500_ci | utf8 | 223 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+--------------------------+----------+------+---------+----------+---------+ -219 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -TiDB 不支持二进制以外的排序规则。`SHOW COLLATION` 语句仅用于确保与 MySQL 的兼容性。 - -## 另请参阅 - -* [SHOW CHARACTER SET](/v3.1/reference/sql/statements/show-character-set.md) diff --git a/v3.1/reference/sql/statements/show-columns-from.md b/v3.1/reference/sql/statements/show-columns-from.md deleted file mode 100644 index 745811de115a..000000000000 --- a/v3.1/reference/sql/statements/show-columns-from.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: SHOW [FULL] COLUMNS FROM -summary: TiDB 数据库中 SHOW [FULL] COLUMNS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] COLUMNS FROM - -`SHOW [FULL] COLUMNS FROM` 语句用于以表格格式描述表或视图中的列。可选关键字 `FULL` 用于显示当前用户对该列的权限，以及表定义中的 `comment`。 - -`SHOW [FULL] FIELDS FROM`，`DESC `，`DESCRIBE
` 和 `EXPLAIN
` 语句都是 `SHOW [FULL] COLUMNS FROM` 的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -create view v1 as select 1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -show columns from v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -desc v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -describe v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -explain v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show fields from v1; -``` - -``` -+-------+-----------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+-----------+------+------+---------+-------+ -| 1 | bigint(1) | YES | | NULL | | -+-------+-----------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show full columns from v1; -``` - -``` -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -| 1 | bigint(1) | NULL | YES | | NULL | | select,insert,update,references | | -+-------+-----------+-----------+------+------+---------+-------+---------------------------------+---------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -show full columns from mysql.user; -``` - -``` -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Field | Type | Collation | Null | Key | Default | Extra | Privileges | Comment | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -| Host | char(64) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| User | char(32) | utf8mb4_bin | NO | PRI | NULL | | select,insert,update,references | | -| Password | char(41) | utf8mb4_bin | YES | | NULL | | select,insert,update,references | | -| Select_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Insert_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Update_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Delete_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Process_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Grant_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| References_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_db_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Super_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_tmp_table_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Lock_tables_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Execute_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Show_view_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Alter_routine_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Index_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_user_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Event_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Trigger_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Create_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Drop_role_priv | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -| Account_locked | enum('N','Y') | utf8mb4_bin | NO | | N | | select,insert,update,references | | -+-----------------------+---------------+-------------+------+------+---------+-------+---------------------------------+---------+ -29 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] COLUMNS FROM` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) diff --git a/v3.1/reference/sql/statements/show-create-table.md b/v3.1/reference/sql/statements/show-create-table.md deleted file mode 100644 index ed05ce08fde7..000000000000 --- a/v3.1/reference/sql/statements/show-create-table.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: SHOW CREATE TABLE -summary: TiDB 数据库中 SHOW CREATE TABLE 的使用概况。 -category: reference ---- - -# SHOW CREATE TABLE - -`SHOW CREATE TABLE` 语句用于显示用 SQL 重新创建已有表的确切语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -``` -+-------+------------------------------------------------------------------------------------------------------------+ -| Table | Create Table | -+-------+------------------------------------------------------------------------------------------------------------+ -| t1 | CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | -+-------+------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW CREATE TABLE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [SHOW TABLES](/v3.1/reference/sql/statements/show-tables.md) -* [SHOW COLUMNS FROM](/v3.1/reference/sql/statements/show-columns-from.md) diff --git a/v3.1/reference/sql/statements/show-create-user.md b/v3.1/reference/sql/statements/show-create-user.md deleted file mode 100644 index 23c6880a5189..000000000000 --- a/v3.1/reference/sql/statements/show-create-user.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: SHOW CREATE USER -summary: TiDB 数据库中 SHOW CREATE USER 的使用概况。 -category: reference ---- - -# SHOW CREATE USER - -`SHOW CREATE USER` 语句用于显示如何使用 `CREATE USER` 语法来重新创建用户。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW CREATE USER 'root'; -``` - -```+--------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER for root@% | -+--------------------------------------------------------------------------------------------------------------------------+ -| CREATE USER 'root'@'%' IDENTIFIED WITH 'mysql_native_password' AS '' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK | -+--------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) - -mysql> SHOW GRANTS FOR 'root'; -+-------------------------------------------+ -| Grants for root@% | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `SHOW CREATE USER` 的输出结果旨在匹配 MySQL，但 TiDB 尚不支持若干 `CREATE` 选项。尚未支持的选项在语句执行过程中会被解析但会被跳过执行。详情可参阅 [security compatibility]。 - -## 另请参阅 - -* [CREATE USER](/v3.1/reference/sql/statements/create-user.md) -* [SHOW GRANTS](/v3.1/reference/sql/statements/show-grants.md) -* [DROP USER](/v3.1/reference/sql/statements/drop-user.md) diff --git a/v3.1/reference/sql/statements/show-databases.md b/v3.1/reference/sql/statements/show-databases.md deleted file mode 100644 index 1fe8751d7c22..000000000000 --- a/v3.1/reference/sql/statements/show-databases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: SHOW DATABASES -summary: TiDB 数据库中 SHOW DATABASES 的使用概况。 -category: reference ---- - -# SHOW DATABASES - -`SHOW DATABASES` 语句用于显示当前用户有权访问的数据库列表。当前用户无权访问的数据库将从列表中隐藏。`information_schema` 数据库始终出现在列表的最前面。 - -`SHOW SCHEMAS` 是 `SHOW DATABASES` 语句的别名。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mysql | -| test | -+--------------------+ -4 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE mynewdb; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW DATABASES; -``` - -``` -+--------------------+ -| Database | -+--------------------+ -| INFORMATION_SCHEMA | -| PERFORMANCE_SCHEMA | -| mynewdb | -| mysql | -| test | -+--------------------+ -5 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW DATABASES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW SCHEMAS](/v3.1/reference/sql/statements/show-schemas.md) -* [DROP DATABASE](/v3.1/reference/sql/statements/drop-database.md) -* [CREATE DATABASE](/v3.1/reference/sql/statements/create-database.md) diff --git a/v3.1/reference/sql/statements/show-engines.md b/v3.1/reference/sql/statements/show-engines.md deleted file mode 100644 index 800f8deaced4..000000000000 --- a/v3.1/reference/sql/statements/show-engines.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SHOW ENGINES -summary: TiDB 数据库中 SHOW ENGINES 的使用概况。 -category: reference ---- - -# SHOW ENGINES - -`SHOW ENGINES` 语句仅提供 MySQL 兼容性。 - -## 语法图 - -```sql -SHOW ENGINES; -``` - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW ENGINES; -``` - -``` -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -| Engine | Support | Comment | Transactions | XA | Savepoints | -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -| InnoDB | DEFAULT | Supports transactions, row-level locking, and foreign keys | YES | YES | YES | -+--------+---------+------------------------------------------------------------+--------------+------+------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -* `SHOW ENGINES` 语句始终只返回 InnoDB 作为其支持的引擎。但 TiDB 内部通常使用 TiKV 作为存储引擎。 diff --git a/v3.1/reference/sql/statements/show-errors.md b/v3.1/reference/sql/statements/show-errors.md deleted file mode 100644 index e0f3ffd4a0ca..000000000000 --- a/v3.1/reference/sql/statements/show-errors.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: SHOW ERRORS -summary: TiDB 数据库中 SHOW ERRORS 的使用概况。 -category: reference ---- - -# SHOW ERRORS - -`SHOW ERRORS` 语句用于显示已执行语句中的错误。一旦先前的语句成功执行，就会清除错误缓冲区，这时 `SHOW ERRORS` 会返回一个空集。 - -当前的 `sql_mode` 很大程度决定了哪些语句会产生错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -select invalid; -``` - -``` -ERROR 1054 (42S22): Unknown column 'invalid' in 'field list' -``` - -{{< copyable "sql" >}} - -```sql -create invalid; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" -``` - -{{< copyable "sql" >}} - -```sql -SHOW ERRORS; -``` - -``` -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Level | Code | Message | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Error | 1054 | Unknown column 'invalid' in 'field list' | -| Error | 1064 | You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 14 near "invalid" | -+-------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE invalid2; -``` - -``` -ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your TiDB version for the right syntax to use line 1 column 15 near "invalid2" -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1; -``` - -``` -+------+ -| 1 | -+------+ -| 1 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW ERRORS; -``` - -``` -Empty set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW ERRORS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW WARNINGS](/v3.1/reference/sql/statements/show-warnings.md) diff --git a/v3.1/reference/sql/statements/show-fields-from.md b/v3.1/reference/sql/statements/show-fields-from.md deleted file mode 100644 index 1c219629b09a..000000000000 --- a/v3.1/reference/sql/statements/show-fields-from.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW [FULL] FIELDS FROM -summary: TiDB 数据库中 SHOW [FULL] FIELDS FROM 的使用概况。 -category: reference ---- - -# SHOW [FULL] FIELDS FROM - -`SHOW [FULL] FIELDS FROM` 是 [`SHOW [FULL] COLUMNS FROM`](/v3.1/reference/sql/statements/show-columns-from.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/v3.1/reference/sql/statements/show-grants.md b/v3.1/reference/sql/statements/show-grants.md deleted file mode 100644 index d14659a93ba0..000000000000 --- a/v3.1/reference/sql/statements/show-grants.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: SHOW GRANTS -summary: TiDB 数据库中 SHOW GRANTS 的使用概况。 -category: reference ---- - -# SHOW GRANTS - -`SHOW GRANTS` 语句用于显示与用户关联的权限列表。与在 MySQL 中一样，`USAGE` 权限表示登录 TiDB 的能力。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**Username:** - -![Username](/media/sqlgram/Username.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS; -``` - -``` -+-------------------------------------------+ -| Grants for User | -+-------------------------------------------+ -| GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' | -+-------------------------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR 'u1'; -``` - -``` -ERROR 1141 (42000): There is no such grant defined for user 'u1' on host '%' -``` - -{{< copyable "sql" >}} - -```sql -CREATE USER u1; -``` - -``` -Query OK, 1 row affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -GRANT SELECT ON test.* TO u1; -``` - -``` -Query OK, 0 rows affected (0.04 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GRANTS FOR u1; -``` - -``` -+------------------------------------+ -| Grants for u1@% | -+------------------------------------+ -| GRANT USAGE ON *.* TO 'u1'@'%' | -| GRANT Select ON test.* TO 'u1'@'%' | -+------------------------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW GRANTS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE USER](/v3.1/reference/sql/statements/show-create-user.md) -* [GRANT](/v3.1/reference/sql/statements/grant-privileges.md) diff --git a/v3.1/reference/sql/statements/show-index.md b/v3.1/reference/sql/statements/show-index.md deleted file mode 100644 index e2c516c52ef2..000000000000 --- a/v3.1/reference/sql/statements/show-index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW INDEX [FROM|IN] -summary: TiDB 数据库中 SHOW INDEX [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEX [FROM|IN] - -`SHOW INDEX [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/v3.1/reference/sql/statements/show-indexes.md) 的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/v3.1/reference/sql/statements/show-indexes.md b/v3.1/reference/sql/statements/show-indexes.md deleted file mode 100644 index dbf07d1a7f26..000000000000 --- a/v3.1/reference/sql/statements/show-indexes.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: SHOW INDEXES [FROM|IN] -summary: TiDB 数据库中 SHOW INDEXES [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW INDEXES [FROM|IN] - -`SHOW INDEXES [FROM|IN]` 语句用于列出指定表上的索引。`SHOW INDEX [FROM | IN]` 和 `SHOW KEYS [FROM | IN]` 是该语句的别名。包含该语句提供了 MySQL 兼容性。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowIndexKwd:** - -![ShowIndexKwd](/media/sqlgram/ShowIndexKwd.png) - -**FromOrIn:** - -![FromOrIn](/media/sqlgram/FromOrIn.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT, col1 INT, INDEX(col1)); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEXES FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEX FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW KEYS FROM t1; -``` - -``` -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -| t1 | 0 | PRIMARY | 1 | id | A | 0 | NULL | NULL | | BTREE | | | -| t1 | 1 | col1 | 1 | col1 | A | 0 | NULL | NULL | YES | BTREE | | | -+-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW INDEXES [FROM|IN]` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) -* [DROP INDEX](/v3.1/reference/sql/statements/drop-index.md) -* [CREATE INDEX](/v3.1/reference/sql/statements/create-index.md) diff --git a/v3.1/reference/sql/statements/show-keys.md b/v3.1/reference/sql/statements/show-keys.md deleted file mode 100644 index 959f27dbb061..000000000000 --- a/v3.1/reference/sql/statements/show-keys.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW KEYS [FROM|IN] -summary: TiDB 数据库中 SHOW KEYS [FROM|IN] 的使用概况。 -category: reference ---- - -# SHOW KEYS [FROM|IN] - -`SHOW KEYS [FROM|IN]` 语句是 [`SHOW INDEXES [FROM|IN]`](/v3.1/reference/sql/statements/show-indexes.md) 语句的别名。包含该语句提供了 MySQL 兼容性。 diff --git a/v3.1/reference/sql/statements/show-privileges.md b/v3.1/reference/sql/statements/show-privileges.md deleted file mode 100644 index b3e21360a634..000000000000 --- a/v3.1/reference/sql/statements/show-privileges.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: SHOW PRIVILEGES -summary: TiDB 数据库中 SHOW PRIVILEGES 的使用概况。 -category: reference ---- - -# SHOW PRIVILEGES - -`SHOW PRIVILEGES` 语句用于显示 TiDB 中可分配权限的列表。此列表为静态列表，不反映当前用户的权限。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show privileges; -``` - -``` -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Privilege | Context | Comment | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -| Alter | Tables | To alter the table | -| Alter | Tables | To alter the table | -| Alter routine | Functions,Procedures | To alter or drop stored functions/procedures | -| Create | Databases,Tables,Indexes | To create new databases and tables | -| Create routine | Databases | To use CREATE FUNCTION/PROCEDURE | -| Create temporary tables | Databases | To use CREATE TEMPORARY TABLE | -| Create view | Tables | To create new views | -| Create user | Server Admin | To create new users | -| Delete | Tables | To delete existing rows | -| Drop | Databases,Tables | To drop databases, tables, and views | -| Event | Server Admin | To create, alter, drop and execute events | -| Execute | Functions,Procedures | To execute stored routines | -| File | File access on server | To read and write files on the server | -| Grant option | Databases,Tables,Functions,Procedures | To give to other users those privileges you possess | -| Index | Tables | To create or drop indexes | -| Insert | Tables | To insert data into tables | -| Lock tables | Databases | To use LOCK TABLES (together with SELECT privilege) | -| Process | Server Admin | To view the plain text of currently executing queries | -| Proxy | Server Admin | To make proxy user possible | -| References | Databases,Tables | To have references on tables | -| Reload | Server Admin | To reload or refresh tables, logs and privileges | -| Replication client | Server Admin | To ask where the slave or master servers are | -| Replication slave | Server Admin | To read binary log events from the master | -| Select | Tables | To retrieve rows from table | -| Show databases | Server Admin | To see all databases with SHOW DATABASES | -| Show view | Tables | To see views with SHOW CREATE VIEW | -| Shutdown | Server Admin | To shut down the server | -| Super | Server Admin | To use KILL thread, SET GLOBAL, CHANGE MASTER, etc. | -| Trigger | Tables | To use triggers | -| Create tablespace | Server Admin | To create/alter/drop tablespaces | -| Update | Tables | To update existing rows | -| Usage | Server Admin | No privileges - allow connect only | -+-------------------------+---------------------------------------+-------------------------------------------------------+ -32 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW PRIVILEGES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW GRANTS](/v3.1/reference/sql/statements/show-grants.md) -* [GRANT ](/v3.1/reference/sql/statements/grant-privileges.md) diff --git a/v3.1/reference/sql/statements/show-processlist.md b/v3.1/reference/sql/statements/show-processlist.md deleted file mode 100644 index 7dafed95be7e..000000000000 --- a/v3.1/reference/sql/statements/show-processlist.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: SHOW [FULL] PROCESSLIST -summary: TiDB 数据库中 SHOW [FULL] PROCESSLIST 的使用概况。 -category: reference ---- - -# SHOW [FULL] PROCESSLIST - -`SHOW [FULL] PROCESSLIST` 语句列出连接到相同 TiDB 服务器的当前会话。`Info` 列包含查询文本，除非指定可选关键字 `FULL`，否则文本会被截断。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**OptFull:** - -![OptFull](/media/sqlgram/OptFull.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW PROCESSLIST; -``` - -``` -+------+------+-----------+------+---------+------+-------+------------------+ -| Id | User | Host | db | Command | Time | State | Info | -+------+------+-----------+------+---------+------+-------+------------------+ -| 1 | root | 127.0.0.1 | test | Query | 0 | 2 | SHOW PROCESSLIST | -| 2 | root | 127.0.0.1 | | Sleep | 4 | 2 | | -+------+------+-----------+------+---------+------+-------+------------------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -* TiDB 中的 `State` 列是非描述性的。在 TiDB 中，将状态表示为单个值更复杂，因为查询是并行执行的，而且每个 GO 线程在任一时刻都有不同的状态。 - -## 另请参阅 - -* [KILL \[TIDB\]](/v3.1/reference/sql/statements/kill.md) diff --git a/v3.1/reference/sql/statements/show-schemas.md b/v3.1/reference/sql/statements/show-schemas.md deleted file mode 100644 index d7943fe94920..000000000000 --- a/v3.1/reference/sql/statements/show-schemas.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: SHOW SCHEMAS -summary: TiDB 数据库中 SHOW SCHEMAS 的使用概况。 -category: reference ---- - -# SHOW SCHEMAS - -`SHOW SCHEMAS` 语句是 [`SHOW DATABASES`](/v3.1/reference/sql/statements/show-databases.md) 的别名。包含该语句提供了 MySQL 兼容性。。 diff --git a/v3.1/reference/sql/statements/show-status.md b/v3.1/reference/sql/statements/show-status.md deleted file mode 100644 index 3aef16c414c0..000000000000 --- a/v3.1/reference/sql/statements/show-status.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] STATUS -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] STATUS 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] STATUS - -`SHOW [GLOBAL|SESSION] STATUS` 语句用于提供 MySQL 兼容性，对 TiDB 没有作用。因为 TiDB 使用 Prometheus 和 Grafana 而非 `SHOW STATUS` 来进行集中度量收集。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -show status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher_list | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| Ssl_cipher | | -+--------------------+--------------------------------------+ -6 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -show global status; -``` - -``` -+--------------------+--------------------------------------+ -| Variable_name | Value | -+--------------------+--------------------------------------+ -| Ssl_cipher | | -| Ssl_cipher_list | | -| Ssl_verify_mode | 0 | -| Ssl_version | | -| server_id | 93e2e07d-6bb4-4a1b-90b7-e035fae154fe | -| ddl_schema_version | 141 | -+--------------------+--------------------------------------+ -6 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] STATUS` 语句仅用于提供 MySQL 兼容性。 - -## 另请参阅 - -* [FLUSH STATUS](/v3.1/reference/sql/statements/flush-status.md) diff --git a/v3.1/reference/sql/statements/show-table-regions.md b/v3.1/reference/sql/statements/show-table-regions.md deleted file mode 100644 index eed0dd4d2fa7..000000000000 --- a/v3.1/reference/sql/statements/show-table-regions.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: SHOW TABLE REGIONS -summary: 了解如何使用 TiDB 数据库中的 SHOW TABLE REGIONS。 -category: reference ---- - -# SHOW TABLE REGIONS - -`SHOW TABLE REGIONS` 语句用于显示 TiDB 中某个表的 Region 信息。 - -## 语法图 - -```sql -SHOW TABLE [table_name] REGIONS [WhereClauseOptional]; - -SHOW TABLE [table_name] INDEX [index_name] REGIONS [WhereClauseOptional]; -``` - -`SHOW TABLE REGIONS` 会返回如下列： - -* `REGION_ID`：Region 的 ID。 -* `START_KEY`：Region 的 Start key。 -* `END_KEY`：Region 的 End key。 -* `LEADER_ID`：Region 的 Leader ID。 -* `LEADER_STORE_ID`：Region leader 所在的 store (TiKV) ID。 -* `PEERS`：Region 所有副本的 ID。 -* `SCATTERING`：Region 是否正在调度中。1 表示正在调度。 -* `WRITTEN_BYTES`：估算的 Region 在 1 个心跳周期内的写入数据量大小，单位是 byte。 -* `READ_BYTES`：估算的 Region 在 1 个心跳周期内的读数据量大小，单位是 byte。 -* `APPROXIMATE_SIZE(MB)`：估算的 Region 的数据量大小，单位是 MB。 -* `APPROXIMATE_KEYS`：估算的 Region 内 Key 的个数。 - -> **注意：** -> -> `WRITTEN_BYTES`，`READ_BYTES`，`APPROXIMATE_SIZE(MB)`，`APPROXIMATE_KEYS` 的值是 PD 根据 Region 的心跳汇报信息统计，估算出来的数据，所以不是精确的数据。 - -## 示例 - -```sql -test> create table t (id int key,name varchar(50), index (name)); -Query OK, 0 rows affected - --- 默认新建表后会单独 split 出一个 Region 来存放该表的数据，开始时行数据和索引数据都会写到这个 Region。 -test> show table t regions; -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ -| 3 | t_43_ | | 73 | 9 | 5, 73, 93 | 0 | 35 | 0 | 1 | 0 | -+-----------+-----------+---------+-----------+-----------------+-----------+------------+---------------+------------+----------------------+------------------+ --- 上面 START_KEY 列的值 t_43_ 中，t 是表数据的前缀，43 是表 t 的 table ID。 --- END_KEY 列的值为空（""）表示无穷大。 -1 row in set - --- 用 `SPLIT TABLE REGION` 语法切分行数据的 Region，下面语法把表 t 的行数据切分成 5 个 Region。 -test> split table t between (0) and (100000) regions 5; -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 5 | 1.0 | -+--------------------+----------------------+ --- TOTAL_SPLIT_REGION 表示新切的 region 数量，这是新切了 5 个 region. --- SCATTER_FINISH_RATIO 表示新切的 region 的打散成功率，1.0 表示都已经打散了。 - --- 表 t 现在一共有 6 个 Region，其中 102、106、110、114、3 用来存行数据，Region 98 用来存索引数据。 -test> show table t regions; -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | -| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 107, 108, 120 | 0 | 23 | 0 | 1 | 0 | -| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | -| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | -| 3 | t_43_r_80000 | | 93 | 8 | 5, 73, 93 | 0 | 0 | 0 | 1 | 0 | -| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+--------------+--------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ - --- Region 102 的 START_KEY 和 END_KEY 中，t_43 是表数据前缀和 table ID，_r 是表 t record 数据的前缀，索引数据的前缀是 _i， --- 所以 Region 102 的 START_KEY 和 END_KEY 表示用来存储 [-inf, 20000) 之前的 record 数据。其他 Region (103, 109, 113, 2) 的存储范围依次类推。 --- Region 98 用来存储索引数据存储。表 t 索引数据的起始 key 是 t_43_i，处于 Region 98 的存储范围内。 -6 rows in set - --- 查看表 t 在 store 1 上的 region，用 where 条件过滤。 -test> show table t regions where leader_store_id =1; -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ -| 98 | t_43_ | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+-----------+---------+-----------+-----------------+--------------+------------+---------------+------------+----------------------+------------------+ - - --- 用 `SPLIT TABLE REGION` 语法切分索引数据的 Region，下面语法把表 t 的索引 name 数据在 [a,z] 范围内切分成 2 个 Region。 -test> split table t index name between ("a") and ("z") regions 2; -+--------------------+----------------------+ -| TOTAL_SPLIT_REGION | SCATTER_FINISH_RATIO | -+--------------------+----------------------+ -| 2 | 1.0 | -+--------------------+----------------------+ -1 row in set - --- 现在表 t 一共有 7 个 Region，其中 5 个 Region (102, 106, 110, 114, 3) 用来存表 t 的 record 数据，另外 2 个 Region (135, 98) 用来存 name 索引的数据。 -test> show table t regions; -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| REGION_ID | START_KEY | END_KEY | LEADER_ID | LEADER_STORE_ID | PEERS | SCATTERING | WRITTEN_BYTES | READ_BYTES | APPROXIMATE_SIZE(MB) | APPROXIMATE_KEYS | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -| 102 | t_43_r | t_43_r_20000 | 118 | 7 | 105, 118, 119 | 0 | 0 | 0 | 1 | 0 | -| 106 | t_43_r_20000 | t_43_r_40000 | 120 | 7 | 108, 120, 126 | 0 | 0 | 0 | 1 | 0 | -| 110 | t_43_r_40000 | t_43_r_60000 | 112 | 9 | 112, 113, 121 | 0 | 0 | 0 | 1 | 0 | -| 114 | t_43_r_60000 | t_43_r_80000 | 122 | 7 | 115, 122, 123 | 0 | 35 | 0 | 1 | 0 | -| 3 | t_43_r_80000 | | 93 | 8 | 73, 93, 128 | 0 | 0 | 0 | 1 | 0 | -| 135 | t_43_i_1_ | t_43_i_1_016d80000000000000 | 139 | 2 | 138, 139, 140 | 0 | 35 | 0 | 1 | 0 | -| 98 | t_43_i_1_016d80000000000000 | t_43_r | 99 | 1 | 99, 100, 101 | 0 | 0 | 0 | 1 | 0 | -+-----------+-----------------------------+-----------------------------+-----------+-----------------+---------------+------------+---------------+------------+----------------------+------------------+ -7 rows in set -``` - -## 另请参阅 - -* [SPLIT REGION](/v3.1/reference/sql/statements/split-region.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) diff --git a/v3.1/reference/sql/statements/show-table-status.md b/v3.1/reference/sql/statements/show-table-status.md deleted file mode 100644 index ac00f5f495cc..000000000000 --- a/v3.1/reference/sql/statements/show-table-status.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: SHOW TABLE STATUS -summary: TiDB 数据库中 SHOW TABLE STATUS 的使用概况。 -category: reference ---- - -# SHOW TABLE STATUS - -`SHOW TABLE STATUS` 语句用于显示 TiDB 中表的各种统计信息。如果显示统计信息过期，建议运行 [`ANALYZE TABLE`](/v3.1/reference/sql/statements/analyze-table.md)。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLE STATUS LIKE 't1'; -``` - -``` -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 0 - Avg_row_length: 0 - Data_length: 0 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -analyze table t1; -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLE STATUS LIKE 't1'; -``` - -``` -*************************** 1. row *************************** - Name: t1 - Engine: InnoDB - Version: 10 - Row_format: Compact - Rows: 5 - Avg_row_length: 16 - Data_length: 80 -Max_data_length: 0 - Index_length: 0 - Data_free: 0 - Auto_increment: 30001 - Create_time: 2019-04-19 08:32:06 - Update_time: NULL - Check_time: NULL - Collation: utf8mb4_bin - Checksum: - Create_options: - Comment: -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW TABLE STATUS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW TABLES](/v3.1/reference/sql/statements/show-tables.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) diff --git a/v3.1/reference/sql/statements/show-tables.md b/v3.1/reference/sql/statements/show-tables.md deleted file mode 100644 index 99bd1b1e2ba5..000000000000 --- a/v3.1/reference/sql/statements/show-tables.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: SHOW [FULL] TABLES -summary: TiDB 数据库中 SHOW [FULL] TABLES 的使用概况。 -category: reference ---- - -# SHOW [FULL] TABLES - -`SHOW [FULL] TABLES` 语句用于显示当前所选数据库中表和视图的列表。可选关键字 `FULL` 说明表的类型是 `BASE TABLE` 还是 `VIEW`。 - -若要在不同的数据库中显示表，可使用 `SHOW TABLES IN DatabaseName` 语句。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**ShowDatabaseNameOpt:** - -![ShowDatabaseNameOpt](/media/sqlgram/ShowDatabaseNameOpt.png) - -## 示例 - -```sql -mysql> CREATE TABLE t1 (a int); -Query OK, 0 rows affected (0.12 sec) - -mysql> CREATE VIEW v1 AS SELECT 1; -Query OK, 0 rows affected (0.10 sec) - -mysql> SHOW TABLES; -+----------------+ -| Tables_in_test | -+----------------+ -| t1 | -| v1 | -+----------------+ -2 rows in set (0.00 sec) - -mysql> SHOW FULL TABLES; -+----------------+------------+ -| Tables_in_test | Table_type | -+----------------+------------+ -| t1 | BASE TABLE | -| v1 | VIEW | -+----------------+------------+ -2 rows in set (0.00 sec) - -mysql> SHOW TABLES IN mysql; -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [FULL] TABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) diff --git a/v3.1/reference/sql/statements/show-variables.md b/v3.1/reference/sql/statements/show-variables.md deleted file mode 100644 index dafc1791a3cc..000000000000 --- a/v3.1/reference/sql/statements/show-variables.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: SHOW [GLOBAL|SESSION] VARIABLES -summary: TiDB 数据库中 SHOW [GLOBAL|SESSION] VARIABLES 的使用概况。 -category: reference ---- - -# SHOW [GLOBAL|SESSION] VARIABLES - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句用于显示 `GLOBAL` 或 `SESSION` 范围的变量列表。如果未指定范围，则应用默认范围 `SESSION`。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -**GlobalScope:** - -![GlobalScope](/media/sqlgram/GlobalScope.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'tidb%'; -``` - -``` -+-------------------------------------+---------------+ -| Variable_name | Value | -+-------------------------------------+---------------+ -| tidb_retry_limit | 10 | -| tidb_enable_streaming | 0 | -| tidb_hashagg_final_concurrency | 4 | -| tidb_disable_txn_auto_retry | 1 | -| tidb_mem_quota_query | 34359738368 | -| tidb_skip_isolation_level_check | 0 | -| tidb_ddl_reorg_batch_size | 1024 | -| tidb_constraint_check_in_place | 0 | -| tidb_current_ts | 0 | -| tidb_opt_insubq_to_join_and_agg | 1 | -| tidb_enable_window_function | 1 | -| tidb_ddl_error_count_limit | 512 | -| tidb_checksum_table_concurrency | 4 | -| tidb_config | | -| tidb_batch_insert | 0 | -| tidb_opt_join_reorder_threshold | 0 | -| tidb_auto_analyze_end_time | 23:59 +0000 | -| tidb_index_lookup_size | 20000 | -| tidb_projection_concurrency | 4 | -| tidb_opt_correlation_threshold | 0.9 | -| tidb_enable_table_partition | auto | -| tidb_wait_split_region_timeout | 300 | -| tidb_skip_utf8_check | 0 | -| tidb_dml_batch_size | 20000 | -| tidb_backoff_weight | 2 | -| tidb_txn_mode | | -| tidb_mem_quota_indexlookupjoin | 34359738368 | -| tidb_hashagg_partial_concurrency | 4 | -| tidb_enable_radix_join | 0 | -| tidb_mem_quota_topn | 34359738368 | -| tidb_hash_join_concurrency | 5 | -| tidb_max_chunk_size | 1024 | -| tidb_mem_quota_indexlookupreader | 34359738368 | -| tidb_expensive_query_time_threshold | 60 | -| tidb_enable_cascades_planner | 0 | -| tidb_mem_quota_mergejoin | 34359738368 | -| tidb_auto_analyze_ratio | 0.5 | -| tidb_index_lookup_concurrency | 4 | -| tidb_force_priority | NO_PRIORITY | -| tidb_ddl_reorg_priority | PRIORITY_LOW | -| tidb_index_lookup_join_concurrency | 4 | -| tidb_index_join_batch_size | 25000 | -| tidb_index_serial_scan_concurrency | 1 | -| tidb_mem_quota_nestedloopapply | 34359738368 | -| tidb_auto_analyze_start_time | 00:00 +0000 | -| tidb_snapshot | | -| tidb_low_resolution_tso | 0 | -| tidb_batch_commit | 0 | -| tidb_init_chunk_size | 32 | -| tidb_build_stats_concurrency | 4 | -| tidb_backoff_lock_fast | 100 | -| tidb_optimizer_selectivity_level | 0 | -| tidb_batch_delete | 0 | -| tidb_distsql_scan_concurrency | 15 | -| tidb_scatter_region | 0 | -| tidb_opt_correlation_exp_factor | 1 | -| tidb_ddl_reorg_worker_cnt | 16 | -| tidb_wait_split_region_finish | 1 | -| tidb_mem_quota_sort | 34359738368 | -| tidb_general_log | 0 | -| tidb_opt_write_row_id | 0 | -| tidb_check_mb4_value_in_utf8 | 1 | -| tidb_enable_fast_analyze | 0 | -| tidb_slow_query_file | tidb-slow.log | -| tidb_slow_log_threshold | 300 | -| tidb_opt_agg_push_down | 0 | -| tidb_mem_quota_hashjoin | 34359738368 | -| tidb_query_log_max_len | 2048 | -+-------------------------------------+---------------+ -68 rows in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW GLOBAL VARIABLES LIKE 'time_zone%'; -``` - -``` -+---------------+--------+ -| Variable_name | Value | -+---------------+--------+ -| time_zone | SYSTEM | -+---------------+--------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW [GLOBAL|SESSION] VARIABLES` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SET](/v3.1/reference/sql/statements/set-variable.md) diff --git a/v3.1/reference/sql/statements/show-warnings.md b/v3.1/reference/sql/statements/show-warnings.md deleted file mode 100644 index 972bea502c7a..000000000000 --- a/v3.1/reference/sql/statements/show-warnings.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: SHOW WARNINGS -summary: TiDB 数据库中 SHOW WARNINGS 的使用概况。 -category: reference ---- - -# SHOW WARNINGS - -`SHOW WARNINGS` 语句用于显示当前客户端连接中已执行语句的报错列表。与在 MySQL 中一样，`sql_mode` 极大地影响哪些语句会导致错误与警告。 - -## 语法图 - -**ShowStmt:** - -![ShowStmt](/media/sqlgram/ShowStmt.png) - -**ShowTargetFilterable:** - -![ShowTargetFilterable](/media/sqlgram/ShowTargetFilterable.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT UNSIGNED); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (0); -``` - -``` -Query OK, 1 row affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT 1/a FROM t1; -``` - -``` -+------+ -| 1/a | -+------+ -| NULL | -+------+ -1 row in set, 1 warning (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW WARNINGS; -``` - -``` -+---------+------+---------------+ -| Level | Code | Message | -+---------+------+---------------+ -| Warning | 1365 | Division by 0 | -+---------+------+---------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (-1); -``` - -``` -ERROR 1264 (22003): Out of range value for column 'a' at row 1 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 0 | -+------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SET sql_mode=''; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (-1); -``` - -``` -Query OK, 1 row affected, 1 warning (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW WARNINGS; -``` - -``` -+---------+------+---------------------------+ -| Level | Code | Message | -+---------+------+---------------------------+ -| Warning | 1690 | constant -1 overflows int | -+---------+------+---------------------------+ -1 row in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+------+ -| a | -+------+ -| 0 | -| 0 | -+------+ -2 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`SHOW WARNINGS` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [SHOW ERRORS](/v3.1/reference/sql/statements/show-errors.md) diff --git a/v3.1/reference/sql/statements/split-region.md b/v3.1/reference/sql/statements/split-region.md deleted file mode 100644 index 85b382b03676..000000000000 --- a/v3.1/reference/sql/statements/split-region.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Split Region 使用文档 -category: reference ---- - -# Split Region 使用文档 - -在 TiDB 中新建一个表后，默认会单独切分出 1 个 Region 来存储这个表的数据，这个默认行为由配置文件中的 `split-table` 控制。当这个 Region 中的数据超过默认 Region 大小限制后，这个 Region 会开始分裂成 2 个 Region。 - -上述情况中，如果在新建的表上发生大批量写入，则会造成热点，因为开始只有一个 Region，所有的写请求都发生在该 Region 所在的那台 TiKV 上。 - -为解决上述场景中的热点问题，TiDB 引入了预切分 Region 的功能，即可以根据指定的参数，预先为某个表切分出多个 Region，并打散到各个 TiKV 上去。 - -## Split Region 的使用 - -Split Region 有 2 种不同的语法，具体如下： - -```sql -SPLIT TABLE table_name [INDEX index_name] BETWEEN (lower_value) AND (upper_value) REGIONS region_num -``` - -`BETWEEN lower_value AND upper_value REGIONS region_num` 语法是通过指定上、下边界和 Region 数量，然后在上、下边界之间均匀切分出 `region_num` 个 Region。 - -```sql -SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ... -``` - -`BY value_list…` 语法将手动指定一系列的点，然后根据这些指定的点切分 Region，适用于数据不均匀分布的场景。 - -### Split Table Region - -表中行数据的 key 由 `table_id` 和 `row_id` 编码组成，格式如下： - -```go -t[table_id]_r[row_id] -``` - -例如，当 `table_id` 是 22，`row_id` 是 11 时： - -```go -t22_r11 -``` - -同一表中行数据的 `table_id` 是一样的，但 `row_id` 肯定不一样，所以可以根据 `row_id` 来切分 Region。 - -#### 均匀切分 - -由于 `row_id` 是整数，所以根据指定的 `lower_value`、`upper_value` 以及 `region_num`，可以推算出需要切分的 key。TiDB 先计算 step（`step = (upper_value - lower_value)/num`），然后在 `lower_value` 和 `upper_value` 之间每隔 step 区间切一次，最终切出 `num` 个 Region。 - -例如，对于表 t，如果想要从 `minInt64`~`maxInt64` 之间均匀切割出 16 个 Region，可以用以下语句： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 从 minInt64 到 maxInt64 之间均匀切割出 16 个 Region。如果已知主键的范围没有这么大，比如只会在 0~1000000000 之间，那可以用 0 和 1000000000 分别代替上面的 minInt64 和 maxInt64 来切分 Region。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BETWEEN (0) AND (1000000000) REGIONS 16; -``` - -#### 不均匀切分 - -如果已知数据不是均匀分布的，比如想要 -inf ~ 10000 切一个 Region，10000 ~ 90000 切一个 Region，90000 ~ +inf 切一个 Region，可以通过手动指定点来切分 Region，示例如下： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t BY (10000), (90000); -``` - -### Split Index Region - -表中索引数据的 key 由 `table_id`、`index_id` 以及索引列的值编码组成，格式如下： - -```go -t[table_id]_i[index_id][index_value] -``` - -例如，当 `table_id` 是 22，`index_id` 是 5，`index_value` 是 abc 时： - -```go -t22_i5abc -``` - -同一表中同一索引数据的 `table_id` 和 `index_id` 是一样的，所以要根据 `index_value` 切分索引 Region。 - -#### 均匀切分 - -索引均匀切分与行数据均匀切分的原理一样，只是计算 step 的值较为复杂，因为 `index_value` 可能不是整数。 - -`upper` 和 `lower` 的值会先编码成 byte 数组，去掉 `lower` 和 `upper` byte 数组的最长公共前缀后，从 `lower` 和 `upper` 各取前 8 字节转成 uint64，再计算 `step = (upper - lower)/num`。计算出 step 后再将 step 编码成 byte 数组，添加到之前 `upper`和 `lower`的最长公共前缀后面组成一个 key 后去做切分。示例如下： - -如果索引 idx 的列也是整数类型，可以用如下 SQL 语句切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx BETWEEN (-9223372036854775808) AND (9223372036854775807) REGIONS 16; -``` - -该语句会把表 t 中 idx 索引数据 Region 从 `minInt64` 到 `maxInt64` 之间均匀切割出 16 个 Region。 - -如果索引 idx1 的列是 varchar 类型，希望根据前缀字母来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx1 BETWEEN ("a") AND ("z") REGIONS 26; -``` - -该语句会把表 t 中 idx1 索引数据的 Region 从 a~z 切成 26 个 Region，region1 的范围是 [minIndexValue, b)，region2 的范围是 [b, c)，……，region26 的范围是 [z, maxIndexValue)。对于 idx 索引以 a 为前缀的数据都会写到 region1，以 b 为前缀的索引数据都会写到 region2，以此类推。 - -如果索引 idx2 的列是 timestamp/datetime 等时间类型，希望根据时间区间来切分索引数据： - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx2 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -该语句会把表 t 中 idx2 的索引数据 Region 从 `2010-01-01 00:00:00` 到 `2020-01-01 00:00:00` 切成 10 个 Region。region1 的范围是从 `[minIndexValue, 2011-01-01 00:00:00)`，region2 的范围是 `[2011-01-01 00:00:00, 2012-01-01 00:00:00)`…… - -其他索引列类型的切分方法也是类似的。 - -对于联合索引的数据 Region 切分，唯一不同的是可以指定多个 column 的值。 - -比如索引 `idx3 (a, b)` 包含 2 列，a 是 timestamp，b 是 int。如果只想根据 a 列做时间范围的切分，可以用切分单列时间索引的 SQL 语句来切分，`lower_value` 和 `upper_velue` 中不指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00") AND ("2020-01-01 00:00:00") REGIONS 10; -``` - -如果想在时间相同的情况下，根据 b 列再做一次切分，在切分时指定 b 列的值即可。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t INDEX idx3 BETWEEN ("2010-01-01 00:00:00", "a") AND ("2010-01-01 00:00:00", "z") REGIONS 10; -``` - -该语句在 a 列时间前缀相同的情况下，根据 b 列的值从 a~z 切了 10 个 Region。如果指定的 a 列的值不相同，那么可能不会用到 b 列的值。 - -#### 不均匀切分 - -索引数据也可以根据用户指定的索引值来做切分。 - -假如有 idx4 (a,b)，其中 a 列是 varchar 类型， b 列是 timestamp 类型。 - -{{< copyable "sql" >}} - -```sql -SPLIT TABLE t1 INDEX idx4 BY ("a", "2000-01-01 00:00:01"), ("b", "2019-04-17 14:26:19"), ("c", ""); -``` - -该语句指定了 3 个值，会切分出 4 个 Region，每个 Region 的范围如下。 - -``` -region1 [ minIndexValue , ("a", "2000-01-01 00:00:01")) -region2 [("a", "2000-01-01 00:00:01") , ("b", "2019-04-17 14:26:19")) -region3 [("b", "2019-04-17 14:26:19") , ("c", "") ) -region4 [("c", "") , maxIndexValue ) -``` - -## pre_split_regions - -使用带有 `shard_row_id_bits` 的表时，如果希望建表时就均匀切分 Region，可以考虑配合 `pre_split_regions` 一起使用，用来在建表成功后就开始预均匀切分 `2^(pre_split_regions)` 个 Region。 - -> **注意：** -> -> `pre_split_regions` 必须小于等于 `shard_row_id_bits`。 - -### 示例 - -{{< copyable "sql" >}} - -```sql -create table t (a int, b int,index idx1(a)) shard_row_id_bits = 4 pre_split_regions=2; -``` - -该语句在建表后，会对这个表 t 预切分出 4 + 1 个 Region。4 (2^2) 个 Region 是用来存 table 的行数据的，1 个 Region 是用来存 idx1 索引的数据。 - -4 个 table Region 的范围区间如下： - -``` -region1: [ -inf , 1<<61 ) -region2: [ 1<<61 , 2<<61 ) -region3: [ 2<<61 , 3<<61 ) -region4: [ 3<<61 , +inf ) -``` - -## 相关 session 变量 - -和 `SPLIT REGION` 语句相关的 session 变量有 `tidb_scatter_region`，`tidb_wait_split_region_finish` 和 `tidb_wait_split_region_timeout`，具体可参考 [TiDB 专用系统变量和语法](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md)。 diff --git a/v3.1/reference/sql/statements/start-transaction.md b/v3.1/reference/sql/statements/start-transaction.md deleted file mode 100644 index 0a4c3a2eccc9..000000000000 --- a/v3.1/reference/sql/statements/start-transaction.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: START TRANSACTION -summary: TiDB 数据库中 START TRANSACTION 的使用概况。 -category: reference ---- - -# START TRANSACTION - -`START TRANSACTION` 语句用于在 TiDB 内部启动新事务。它类似于语句 `BEGIN` 和 `SET autocommit = 0`。 - -在没有 `START TRANSACTION` 语句的情况下，每个语句都会在各自的事务中自动提交，这样可确保 MySQL 兼容性。 - -## 语法图 - -**BeginTransactionStmt:** - -![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.12 sec) -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1); -``` - -``` -Query OK, 1 row affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -## MySQL 兼容性 - -`START TRANSACTION` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [COMMIT](/v3.1/reference/sql/statements/commit.md) -* [ROLLBACK](/v3.1/reference/sql/statements/rollback.md) -* [BEGIN](/v3.1/reference/sql/statements/begin.md) diff --git a/v3.1/reference/sql/statements/trace.md b/v3.1/reference/sql/statements/trace.md deleted file mode 100644 index 779a323163e1..000000000000 --- a/v3.1/reference/sql/statements/trace.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: TRACE -summary: TiDB 数据库中 TRACE 的使用概况。 -category: reference ---- - -# TRACE - -`TRACE` 语句用于提供查询执行的详细信息，可通过 TiDB 服务器状态端口所公开的图形界面进行查看。 - -## 语法图 - -**TraceStmt:** - -![TraceStmt](/media/sqlgram/TraceStmt.png) - -**TraceableStmt:** - -![TraceableStmt](/media/sqlgram/TraceableStmt.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -trace format='row' select * from mysql.user; -``` - -``` -+---------------------------+-----------------+------------+ -| operation | startTS | duration | -+---------------------------+-----------------+------------+ -| session.getTxnFuture | 10:33:34.647148 | 3.847µs | -| ├─session.Execute | 10:33:34.647146 | 536.233µs | -| ├─session.ParseSQL | 10:33:34.647182 | 19.868µs | -| ├─executor.Compile | 10:33:34.647219 | 295.688µs | -| ├─session.runStmt | 10:33:34.647533 | 116.229µs | -| ├─session.CommitTxn | 10:33:34.647631 | 5.44µs | -| ├─recordSet.Next | 10:33:34.647707 | 833.103µs | -| ├─tableReader.Next | 10:33:34.647709 | 806.783µs | -| ├─recordSet.Next | 10:33:34.648572 | 19.367µs | -| └─tableReader.Next | 10:33:34.648575 | 1.783µs | -+---------------------------+-----------------+------------+ -10 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id int not null primary key AUTO_INCREMENT); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.02 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -TRACE FORMAT='json' SELECT * FROM t1 WHERE id = 2; -``` - -``` -operation: [ - {"ID":{"Trace":"60d20d005593de87","Span":"44e5b309242ffe2f","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5nZXRUeG5GdXR1cmU="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTQ3ODYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MjA0MDYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":[ - {"ID":{"Trace":"60d20d005593de87","Span":"4dbf8f2ca373b4b0","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5QYXJzZVNRTA=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2NjE1MTQtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MDYxNjgtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6b6d6916df809604","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"ZXhlY3V0b3IuQ29tcGlsZQ=="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NTcyODUtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3MzE0MjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"3f1bcdd402a72911","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5Db21taXRUeG4="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3OTgyNjItMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MDU1NzYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"58c1f7d66dc5afbc","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5ydW5TdG10"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Msg","Value":"eyJzcWwiOiJTRUxFQ1QgKiBGUk9NIHQxIFdIRVJFIGlkID0gMiJ9"}, - {"Key":"Time","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3ODA1NjgtMDY6MDA="}, - {"Key":"_schema:log","Value":null}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4MTk5MzMtMDY6MDA="}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE3NzcyNDItMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"6bd8cc440fb31ed7","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"c2Vzc2lvbi5FeGVjdXRl"}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE2MTEwODktMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NTU0My0wNjowMA=="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"61d0b809f6cc018b","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDE4NzQ1NTYtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIyOTg4NjYtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null}, - {"ID":{"Trace":"60d20d005593de87","Span":"2bd2c3d47ccb1133","Parent":"79d146dac9a29a7e"}, - "Annotations":[ - {"Key":"Name","Value":"cmVjb3JkU2V0Lk5leHQ="}, - {"Key":"_schema:name","Value":null}, - {"Key":"Span.Start","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjY0ODgtMDY6MDA="}, - {"Key":"Span.End","Value":"MjAxOS0wNC0xN1QxMDozOToxMC45NDIzMjkwMDMtMDY6MDA="}, - {"Key":"_schema:Timespan","Value":null} - ], - "Sub":null} - ] - } -] -1 row in set (0.00 sec) -``` - -可将 JSON 格式的跟踪文件粘贴到跟踪查看器中。查看器可通过 TiDB 状态端口访问： - -![TiDB Trace Viewer-1](/media/trace-paste.png) - -![TiDB Trace Viewer-2](/media/trace-view.png) - -## MySQL 兼容性 - -`TRACE` 语句是 TiDB 对 MySQL 语法的扩展。 - -## 另请参阅 - -* [EXPLAIN ANALYZE](/v3.1/reference/sql/statements/explain-analyze.md) diff --git a/v3.1/reference/sql/statements/truncate.md b/v3.1/reference/sql/statements/truncate.md deleted file mode 100644 index 45e2a39d3ab5..000000000000 --- a/v3.1/reference/sql/statements/truncate.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: TRUNCATE -summary: TiDB 数据库中 TRUNCATE 的使用概况。 -category: reference ---- - -# TRUNCATE - -`TRUNCATE` 语句以非事务方式从表中删除所有数据。可认为 `TRUNCATE` 语句同 `DROP TABLE` + `CREATE TABLE` 组合在语义上相同，定义与 `DROP TABLE` 语句相同。 - -`TRUNCATE TABLE tableName` 和 `TRUNCATE tableName` 均为有效语法。 - -## 语法图 - -**TruncateTableStmt:** - -![TruncateTableStmt](/media/sqlgram/TruncateTableStmt.png) - -**OptTable:** - -![OptTable](/media/sqlgram/OptTable.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT NOT NULL PRIMARY KEY); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+---+ -| a | -+---+ -| 1 | -| 2 | -| 3 | -| 4 | -| 5 | -+---+ -5 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -TRUNCATE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sqlS -INSERT INTO t1 VALUES (1),(2),(3),(4),(5); -``` - -``` -Query OK, 5 rows affected (0.01 sec) -Records: 5 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -TRUNCATE TABLE t1; -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -## MySQL 兼容性 - -`TRUNCATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [DROP TABLE](/v3.1/reference/sql/statements/drop-table.md) -* [DELETE](/v3.1/reference/sql/statements/delete.md) -* [CREATE TABLE](/v3.1/reference/sql/statements/create-table.md) -* [SHOW CREATE TABLE](/v3.1/reference/sql/statements/show-create-table.md) diff --git a/v3.1/reference/sql/statements/update.md b/v3.1/reference/sql/statements/update.md deleted file mode 100644 index 27d0cae925be..000000000000 --- a/v3.1/reference/sql/statements/update.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: UPDATE -summary: TiDB 数据库中 UPDATE 的使用概况。 -category: reference ---- - -# UPDATE - -`UPDATE` 语句用于修改指定表中的数据。 - -## 语法图 - -**UpdateStmt:** - -![UpdateStmt](/media/sqlgram/UpdateStmt.png) - -**TableRef:** - -![TableRef](/media/sqlgram/TableRef.png) - -**TableRefs:** - -![TableRefs](/media/sqlgram/TableRefs.png) - -**AssignmentList:** - -![AssignmentList](/media/sqlgram/AssignmentList.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL); -``` - -``` -Query OK, 0 rows affected (0.11 sec) -``` - -{{< copyable "sql" >}} - -```sql -INSERT INTO t1 (c1) VALUES (1), (2), (3); -``` - -``` -Query OK, 3 rows affected (0.02 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 3 | -+----+----+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -UPDATE t1 SET c1=5 WHERE c1=3; -``` - -``` -Query OK, 1 row affected (0.01 sec) -Rows matched: 1 Changed: 1 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1; -``` - -``` -+----+----+ -| id | c1 | -+----+----+ -| 1 | 1 | -| 2 | 2 | -| 3 | 5 | -+----+----+ -3 rows in set (0.00 sec) -``` - -## MySQL 兼容性 - -`UPDATE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [INSERT](/v3.1/reference/sql/statements/insert.md) -* [SELECT](/v3.1/reference/sql/statements/select.md) -* [DELETE](/v3.1/reference/sql/statements/delete.md) -* [REPLACE](/v3.1/reference/sql/statements/replace.md) diff --git a/v3.1/reference/sql/statements/use.md b/v3.1/reference/sql/statements/use.md deleted file mode 100644 index fe9483895d0b..000000000000 --- a/v3.1/reference/sql/statements/use.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: USE -summary: TiDB 数据库中 USE 的使用概况。 -category: reference ---- - -# USE - -`USE` 语句可为用户会话选择当前数据库。 - -## 语法图 - -**UseStmt:** - -![UseStmt](/media/sqlgram/UseStmt.png) - -**DBName:** - -![DBName](/media/sqlgram/DBName.png) - -## 示例 - -{{< copyable "sql" >}} - -```sql -USE mysql; -``` - -``` -Reading table information for completion of table and column names -You can turn off this feature to get a quicker startup with -A - -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+----------------------+ -| Tables_in_mysql | -+----------------------+ -| GLOBAL_VARIABLES | -| bind_info | -| columns_priv | -| db | -| default_roles | -| gc_delete_range | -| gc_delete_range_done | -| help_topic | -| role_edges | -| stats_buckets | -| stats_feedback | -| stats_histograms | -| stats_meta | -| tables_priv | -| tidb | -| user | -+----------------------+ -16 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE DATABASE newtest; -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -USE newtest; -``` - -``` -Database changed -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -Empty set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a int); -``` - -``` -Query OK, 0 rows affected (0.10 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES; -``` - -``` -+-------------------+ -| Tables_in_newtest | -+-------------------+ -| t1 | -+-------------------+ -1 row in set (0.00 sec) -``` - -## MySQL 兼容性 - -`USE` 语句与 MySQL 完全兼容。如有任何兼容性差异，请在 GitHub 上提交 [issue](/v3.1/report-issue.md)。 - -## 另请参阅 - -* [CREATE DATABASE](/v3.1/reference/sql/statements/create-database.md) -* [SHOW TABLES](/v3.1/reference/sql/statements/show-tables.md) diff --git a/v3.1/reference/sql/view.md b/v3.1/reference/sql/view.md deleted file mode 100644 index ffd1bbcc345f..000000000000 --- a/v3.1/reference/sql/view.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: 视图 -category: reference ---- - -# 视图 - -TiDB 支持视图，视图是一张虚拟表，该虚拟表的结构由创建视图时的 `SELECT` 语句定义。使用视图一方面可以对用户只暴露安全的字段及数据，进而保证底层表的敏感字段及数据的安全。另一方面，将频繁出现的复杂查询定义为视图，可以使复杂查询更加简单便捷。 - -## 查询视图 - -查询一个视图和查询一张普通表类似。但是 TiDB 在真正执行查询视图时，会将视图展开成创建视图时定义的 `SELECT` 语句，进而执行展开后的查询语句。 - -## 样例 - -以下例子将创建一个视图，并在该视图上进行查询，最后删除该视图。 - -{{< copyable "sql" >}} - -```sql -create table t(a int, b int); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into t values(1, 1),(2,2),(3,3); -``` - -``` -Query OK, 3 rows affected (0.00 sec) -Records: 3 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -create table s(a int); -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -insert into s values(2),(3); -``` - -``` -Query OK, 2 rows affected (0.01 sec) -Records: 2 Duplicates: 0 Warnings: 0 -``` - -{{< copyable "sql" >}} - -```sql -create view v as select s.a from t left join s on t.a = s.a; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from v; -``` - -``` -+------+ -| a | -+------+ -| NULL | -| 2 | -| 3 | -+------+ -3 rows in set (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -drop view v; -``` - -``` -Query OK, 0 rows affected (0.02 sec) -``` - -## 局限性 - -目前 TiDB 中的视图有以下局限性： - -- 不支持物化视图。 -- TiDB 中视图为只读视图，不支持对视图进行 `UPDATE`、`INSERT`、`DELETE` 等写入操作。 -- 对已创建的视图仅支持 `DROP` 的 DDL 操作，即 `DROP [VIEW | TABLE]`。 - -## 扩展阅读 - -- [创建视图](/v3.1/reference/sql/statements/create-view.md) -- [删除视图](/v3.1/reference/sql/statements/drop-view.md) diff --git a/v3.1/reference/supported-clients.md b/v3.1/reference/supported-clients.md deleted file mode 100644 index f749c8ca066a..000000000000 --- a/v3.1/reference/supported-clients.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: 连接器和 API -category: reference ---- - -# 连接器和 API - -数据库连接器为客户端提供了连接数据库服务端的方式，APIs 提供了使用 MySQL 协议和资源的底层接口。无论是连接器还是 API，都可以用来在不同的语言和环境内连接服务器并执行 sql 语句，包括 odbc、java(jdbc)、Perl、Python、PHP、Ruby 和 C。 - -TiDB 兼容 MySQL(5.6、5.7) 的所有连接器和 API，包括： - -+ [MySQL Connector/C++](https://dev.mysql.com/doc/refman/5.7/en/connector-cpp-info.html) -+ [MySQL Connector/J](https://dev.mysql.com/doc/refman/5.7/en/connector-j-info.html) -+ [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html) -+ [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html) -+ [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html) -+ [MySQL C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html) -+ [MySQL PHP API](https://dev.mysql.com/doc/refman/5.7/en/apis-php-info.html) -+ [MySQL Perl API](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html) -+ [MySQL Python API](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html) -+ [MySQL Ruby APIs](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby.html) -+ [MySQL Tcl API](https://dev.mysql.com/doc/refman/5.7/en/apis-tcl.html) -+ [MySQL Eiffel Wrapper](https://dev.mysql.com/doc/refman/5.7/en/apis-eiffel.html) -+ [Mysql Go API](https://github.com/go-sql-driver/mysql) - -## 使用 MySQL 连接器连接 TiDB - -Oracle 官方提供了以下 API，TiDB 可以兼容所有这些 API。 - -+ [MySQL Connector/C++](https://dev.mysql.com/doc/refman/5.7/en/connector-cpp-info.html)：C++ 语言的客户端库 -+ [MySQL Connector/J](https://dev.mysql.com/doc/refman/5.7/en/connector-j-info.html)：Java 语言的客户端库，基于标准 JDBC 接口 -+ [MySQL Connector/Net](https://dev.mysql.com/doc/refman/5.7/en/connector-net-info.html)：.Net 语言的客户端库，[MySQL for Visual Studio](https://dev.mysql.com/doc/visual-studio/en/)使用这个库，支持 Microsoft Visual Studio 2012，2013，2015和2017版本 -+ [MySQL Connector/ODBC](https://dev.mysql.com/doc/refman/5.7/en/connector-odbc-info.html)：标准的 ODBC 接口，支持 Windows，Unix 和 OS X -+ [MySQL Connector/Python](https://dev.mysql.com/doc/refman/5.7/en/connector-python-info.html)：Python 语言的客户端包，和 [Python DB API version 2.0](http://www.python.org/dev/peps/pep-0249/) 一致 - -## 使用 MySQL C API 连接 TiDB - -如果使用 C 语言程序直接连接 TiDB，可以直接链接 libmysqlclient 库，使用 MySQL 的 [C API](https://dev.mysql.com/doc/refman/5.7/en/c-api.html)，这是最主要的一种 C 语言连接方式，被各种客户端和 API 广泛使用，包括 Connector/C。 - -## 使用 MySQL 第三方 API 连接 TiDB - -第三方 API 非 Oracle 官方提供，下表列出了常用的第三方 API： - -| Environment | API | Type | Notes | -| -------------- | ---------------------------------------- | -------------------------------- | ---------------------------------------- | -| Ada | GNU Ada MySQL Bindings | `libmysqlclient` | See [MySQL Bindings for GNU Ada](http://gnade.sourceforge.net/) | -| C | C API | `libmysqlclient` | See [Section 27.8, “MySQL C API”](https://dev.mysql.com/doc/refman/5.7/en/c-api.html). | -| C++ | Connector/C++ | `libmysqlclient` | See [MySQL Connector/C++ Developer Guide](https://dev.mysql.com/doc/connector-cpp/en/). | -| | MySQL++ | `libmysqlclient` | See [MySQL++ Web site](http://tangentsoft.net/mysql++/doc/). | -| | MySQL wrapped | `libmysqlclient` | See [MySQL wrapped](http://www.alhem.net/project/mysql/). | -| Go | go-sql-driver | Native Driver | See [Mysql Go API](https://github.com/go-sql-driver/mysql) | -| Cocoa | MySQL-Cocoa | `libmysqlclient` | Compatible with the Objective-C Cocoa environment. See | -| D | MySQL for D | `libmysqlclient` | See [MySQL for D](https://github.com/mysql-d/mysql-native). | -| Eiffel | Eiffel MySQL | `libmysqlclient` | See [Section 27.14, “MySQL Eiffel Wrapper”](https://dev.mysql.com/doc/refman/5.7/en/apis-eiffel.html). | -| Erlang | `erlang-mysql-driver` | `libmysqlclient` | See [`erlang-mysql-driver`.](http://code.google.com/p/erlang-mysql-driver/) | -| Haskell | Haskell MySQL Bindings | Native Driver | See [Brian O'Sullivan's pure Haskell MySQL bindings](http://www.serpentine.com/blog/software/mysql/). | -| | `hsql-mysql` | `libmysqlclient` | See [MySQL driver for Haskell](http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hsql-mysql-1.7). | -| Java/JDBC | Connector/J | Native Driver | See [MySQL Connector/J 5.1 Developer Guide](https://dev.mysql.com/doc/connector-j/5.1/en/). | -| Lua | LuaSQL | `libmysqlclient` | See [LuaSQL](http://keplerproject.github.io/luasql/manual.html). | -| .NET/Mono | Connector/Net | Native Driver | See [MySQL Connector/Net Developer Guide](https://dev.mysql.com/doc/connector-net/en/). | -| Objective Caml | OBjective Caml MySQL Bindings | `libmysqlclient` | See [MySQL Bindings for Objective Caml](http://raevnos.pennmush.org/code/ocaml-mysql/). | -| Octave | Database bindings for GNU Octave | `libmysqlclient` | See [Database bindings for GNU Octave](http://octave.sourceforge.net/database/index.html). | -| ODBC | Connector/ODBC | `libmysqlclient` | See [MySQL Connector/ODBC Developer Guide](https://dev.mysql.com/doc/connector-odbc/en/). | -| Perl | `DBI`/`DBD::mysql` | `libmysqlclient` | See [Section 27.10, “MySQL Perl API”](https://dev.mysql.com/doc/refman/5.7/en/apis-perl.html). | -| | `Net::MySQL` | Native Driver | See [`Net::MySQL`](http://search.cpan.org/dist/Net-MySQL/MySQL.pm) at CPAN | -| PHP | `mysql`, `ext/mysql`interface (deprecated) | `libmysqlclient` | See [Original MySQL API](https://dev.mysql.com/doc/apis-php/en/apis-php-mysql.html). | -| | `mysqli`, `ext/mysqli`interface | `libmysqlclient` | See [MySQL Improved Extension](https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.html). | -| | `PDO_MYSQL` | `libmysqlclient` | See [MySQL Functions (PDO_MYSQL)](https://dev.mysql.com/doc/apis-php/en/apis-php-pdo-mysql.html). | -| | PDO mysqlnd | Native Driver | | -| Python | Connector/Python | Native Driver | See [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/). | -| Python | Connector/Python C Extension | `libmysqlclient` | See [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/). | -| | MySQLdb | `libmysqlclient` | See [Section 27.11, “MySQL Python API”](https://dev.mysql.com/doc/refman/5.7/en/apis-python.html). | -| Ruby | MySQL/Ruby | `libmysqlclient` | Uses `libmysqlclient`. See [Section 27.12.1, “The MySQL/Ruby API”](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby-mysqlruby.html). | -| | Ruby/MySQL | Native Driver | See [Section 27.12.2, “The Ruby/MySQL API”](https://dev.mysql.com/doc/refman/5.7/en/apis-ruby-rubymysql.html). | -| Scheme | `Myscsh` | `libmysqlclient` | See [`Myscsh`](https://github.com/aehrisch/myscsh). | -| SPL | `sql_mysql` | `libmysqlclient` | See [`sql_mysql` for SPL](http://www.clifford.at/spl/spldoc/sql_mysql.html). | -| Tcl | MySQLtcl | `libmysqlclient` | See [Section 27.13, “MySQL Tcl API”](https://dev.mysql.com/doc/refman/5.7/en/apis-tcl.html). | - -## TiDB 支持的连接器版本 - -| Connector | Connector version | -| ---------------- | ---------------------------- | -| Connector/C | 6.1.0 GA | -| Connector/C++ | 1.0.5 GA | -| Connector/J | 5.1.8 | -| Connector/Net | 6.9.9 GA | -| Connector/Net | 6.8.8 GA | -| Connector/ODBC | 5.1 | -| Connector/ODBC | 3.51 (Unicode not supported) | -| Connector/Python | 2.0 | -| Connector/Python | 1.2 | diff --git a/v3.1/reference/system-databases/information-schema.md b/v3.1/reference/system-databases/information-schema.md deleted file mode 100644 index d4d690895304..000000000000 --- a/v3.1/reference/system-databases/information-schema.md +++ /dev/null @@ -1,756 +0,0 @@ ---- -title: Information Schema -category: reference ---- - -# Information Schema - -为了和 MySQL 保持兼容，TiDB 支持很多 `INFORMATION_SCHEMA` 表，其中有不少表都支持相应的 `SHOW` 命令。查询 `INFORMATION_SCHEMA` 表也为表的连接操作提供了可能。 - -## ANALYZE_STATUS 表 - -`ANALYZE_STATUS` 表提供正在执行的收集统计信息的任务以及有限条历史任务记录。 - -{{< copyable "sql" >}} - -```sql -select * from `ANALYZE_STATUS`; -``` - -``` -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -| TABLE_SCHEMA | TABLE_NAME | PARTITION_NAME | JOB_INFO | PROCESSED_ROWS | START_TIME | STATE | -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -| test | t | | analyze index idx | 2 | 2019-06-21 19:51:14 | finished | -| test | t | | analyze columns | 2 | 2019-06-21 19:51:14 | finished | -| test | t1 | p0 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p3 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p1 | analyze columns | 0 | 2019-06-21 19:51:15 | finished | -| test | t1 | p2 | analyze columns | 1 | 2019-06-21 19:51:15 | finished | -+--------------+------------+----------------+-------------------+----------------+---------------------+----------+ -6 rows in set -``` - -## CHARACTER_SETS 表 - -`CHARACTER_SETS` 表提供[字符集](/v3.1/reference/sql/character-set.md)相关的信息。TiDB 目前仅支持部分字符集。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM character_sets; -``` - -``` -+--------------------+----------------------+---------------+--------+ -| CHARACTER_SET_NAME | DEFAULT_COLLATE_NAME | DESCRIPTION | MAXLEN | -+--------------------+----------------------+---------------+--------+ -| utf8 | utf8_bin | UTF-8 Unicode | 3 | -| utf8mb4 | utf8mb4_bin | UTF-8 Unicode | 4 | -| ascii | ascii_bin | US ASCII | 1 | -| latin1 | latin1_bin | Latin1 | 1 | -| binary | binary | binary | 1 | -+--------------------+----------------------+---------------+--------+ -5 rows in set (0.00 sec) -``` - -## COLLATIONS 表 - -`COLLATIONS` 表提供了 `CHARACTER_SETS` 表中字符集对应的排序规则列表。TiDB 当前仅支持二进制排序规则，包含该表仅为兼容 MySQL。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM collations WHERE character_set_name='utf8mb4'; -``` - -``` -+------------------------+--------------------+------+------------+-------------+---------+ -| COLLATION_NAME | CHARACTER_SET_NAME | ID | IS_DEFAULT | IS_COMPILED | SORTLEN | -+------------------------+--------------------+------+------------+-------------+---------+ -| utf8mb4_general_ci | utf8mb4 | 45 | Yes | Yes | 1 | -| utf8mb4_bin | utf8mb4 | 46 | | Yes | 1 | -| utf8mb4_unicode_ci | utf8mb4 | 224 | | Yes | 1 | -| utf8mb4_icelandic_ci | utf8mb4 | 225 | | Yes | 1 | -| utf8mb4_latvian_ci | utf8mb4 | 226 | | Yes | 1 | -| utf8mb4_romanian_ci | utf8mb4 | 227 | | Yes | 1 | -| utf8mb4_slovenian_ci | utf8mb4 | 228 | | Yes | 1 | -| utf8mb4_polish_ci | utf8mb4 | 229 | | Yes | 1 | -| utf8mb4_estonian_ci | utf8mb4 | 230 | | Yes | 1 | -| utf8mb4_spanish_ci | utf8mb4 | 231 | | Yes | 1 | -| utf8mb4_swedish_ci | utf8mb4 | 232 | | Yes | 1 | -| utf8mb4_turkish_ci | utf8mb4 | 233 | | Yes | 1 | -| utf8mb4_czech_ci | utf8mb4 | 234 | | Yes | 1 | -| utf8mb4_danish_ci | utf8mb4 | 235 | | Yes | 1 | -| utf8mb4_lithuanian_ci | utf8mb4 | 236 | | Yes | 1 | -| utf8mb4_slovak_ci | utf8mb4 | 237 | | Yes | 1 | -| utf8mb4_spanish2_ci | utf8mb4 | 238 | | Yes | 1 | -| utf8mb4_roman_ci | utf8mb4 | 239 | | Yes | 1 | -| utf8mb4_persian_ci | utf8mb4 | 240 | | Yes | 1 | -| utf8mb4_esperanto_ci | utf8mb4 | 241 | | Yes | 1 | -| utf8mb4_hungarian_ci | utf8mb4 | 242 | | Yes | 1 | -| utf8mb4_sinhala_ci | utf8mb4 | 243 | | Yes | 1 | -| utf8mb4_german2_ci | utf8mb4 | 244 | | Yes | 1 | -| utf8mb4_croatian_ci | utf8mb4 | 245 | | Yes | 1 | -| utf8mb4_unicode_520_ci | utf8mb4 | 246 | | Yes | 1 | -| utf8mb4_vietnamese_ci | utf8mb4 | 247 | | Yes | 1 | -+------------------------+--------------------+------+------------+-------------+---------+ -26 rows in set (0.00 sec) -``` - -## COLLATION_CHARACTER_SET_APPLICABILITY 表 - -`COLLATION_CHARACTER_SET_APPLICABILITY` 表将排序规则映射至适用的字符集名称。和 `COLLATIONS` 表一样，包含此表也是为了兼容 MySQL。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM collation_character_set_applicability WHERE character_set_name='utf8mb4'; -``` - -``` -+------------------------+--------------------+ -| COLLATION_NAME | CHARACTER_SET_NAME | -+------------------------+--------------------+ -| utf8mb4_general_ci | utf8mb4 | -| utf8mb4_bin | utf8mb4 | -| utf8mb4_unicode_ci | utf8mb4 | -| utf8mb4_icelandic_ci | utf8mb4 | -| utf8mb4_latvian_ci | utf8mb4 | -| utf8mb4_romanian_ci | utf8mb4 | -| utf8mb4_slovenian_ci | utf8mb4 | -| utf8mb4_polish_ci | utf8mb4 | -| utf8mb4_estonian_ci | utf8mb4 | -| utf8mb4_spanish_ci | utf8mb4 | -| utf8mb4_swedish_ci | utf8mb4 | -| utf8mb4_turkish_ci | utf8mb4 | -| utf8mb4_czech_ci | utf8mb4 | -| utf8mb4_danish_ci | utf8mb4 | -| utf8mb4_lithuanian_ci | utf8mb4 | -| utf8mb4_slovak_ci | utf8mb4 | -| utf8mb4_spanish2_ci | utf8mb4 | -| utf8mb4_roman_ci | utf8mb4 | -| utf8mb4_persian_ci | utf8mb4 | -| utf8mb4_esperanto_ci | utf8mb4 | -| utf8mb4_hungarian_ci | utf8mb4 | -| utf8mb4_sinhala_ci | utf8mb4 | -| utf8mb4_german2_ci | utf8mb4 | -| utf8mb4_croatian_ci | utf8mb4 | -| utf8mb4_unicode_520_ci | utf8mb4 | -| utf8mb4_vietnamese_ci | utf8mb4 | -+------------------------+--------------------+ -26 rows in set (0.00 sec) -``` - -## COLUMNS 表 - -`COLUMNS` 表提供了表的所有列的信息。 - -{{< copyable "sql" >}} - -```sql -CREATE TABLE test.t1 (a int); -``` - -``` -1 row in set (0.01 sec) -``` - -{{< copyable "sql" >}} - -```sql -SELECT * FROM information_schema.columns WHERE table_schema='test' AND TABLE_NAME='t1'; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: t1 - COLUMN_NAME: a - ORDINAL_POSITION: 1 - COLUMN_DEFAULT: NULL - IS_NULLABLE: YES - DATA_TYPE: int -CHARACTER_MAXIMUM_LENGTH: NULL - CHARACTER_OCTET_LENGTH: NULL - NUMERIC_PRECISION: 11 - NUMERIC_SCALE: 0 - DATETIME_PRECISION: NULL - CHARACTER_SET_NAME: NULL - COLLATION_NAME: NULL - COLUMN_TYPE: int(11) - COLUMN_KEY: - EXTRA: - PRIVILEGES: select,insert,update,references - COLUMN_COMMENT: - GENERATION_EXPRESSION: -1 row in set (0.01 sec) -``` - -对应的 `SHOW` 语句如下： - -{{< copyable "sql" >}} - -```sql -SHOW COLUMNS FROM t1 FROM test; -``` - -``` -+-------+---------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------+---------+------+------+---------+-------+ -| a | int(11) | YES | | NULL | | -+-------+---------+------+------+---------+-------+ -1 row in set (0.00 sec) -``` - -## ENGINES 表 - -`ENGINES` 表提供了关于存储引擎的信息。从和 MySQL 兼容性上考虑，TiDB 会一直将 InnoDB 描述为唯一支持的引擎。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM engines; -``` - -``` -*************************** 1. row *************************** - ENGINE: InnoDB - SUPPORT: DEFAULT - COMMENT: Supports transactions, row-level locking, and foreign keys -TRANSACTIONS: YES - XA: YES - SAVEPOINTS: YES -1 row in set (0.00 sec) -``` - -## KEY_COLUMN_USAGE 表 - -`KEY_COLUMN_USAGE` 表描述了列的键约束，比如主键约束。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM key_column_usage WHERE table_schema='mysql' and table_name='user'; -``` - -``` -*************************** 1. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: Host - ORDINAL_POSITION: 1 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -*************************** 2. row *************************** - CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: PRIMARY - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - COLUMN_NAME: User - ORDINAL_POSITION: 2 -POSITION_IN_UNIQUE_CONSTRAINT: NULL - REFERENCED_TABLE_SCHEMA: NULL - REFERENCED_TABLE_NAME: NULL - REFERENCED_COLUMN_NAME: NULL -2 rows in set (0.00 sec) -``` - -## PROCESSLIST 表 - -`PROCESSLIST` 和 `show processlist` 的功能一样，都是查看当前正在处理的请求。 - -`PROCESSLIST` 表会比 `show processlist` 多一个 `MEM` 列，`MEM` 是指正在处理的请求已使用的内存，单位是 byte。 - -```sql -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -| ID | USER | HOST | DB | COMMAND | TIME | STATE | INFO | MEM | -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -| 1 | root | ::1 | INFORMATION_SCHEMA | Query | 0 | 2 | select * from PROCESSLIST | 0 | -+----+------+------+--------------------+---------+------+-------+---------------------------+-----+ -``` - -## SCHEMATA 表 - -`SCHEMATA` 表提供了关于数据库的信息。表中的数据与 `SHOW DATABASES` 语句的执行结果等价。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM schemata; -``` - -``` -+--------------+--------------------+----------------------------+------------------------+----------+ -| CATALOG_NAME | SCHEMA_NAME | DEFAULT_CHARACTER_SET_NAME | DEFAULT_COLLATION_NAME | SQL_PATH | -+--------------+--------------------+----------------------------+------------------------+----------+ -| def | INFORMATION_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | mynewdb | utf8mb4 | utf8mb4_bin | NULL | -| def | mysql | utf8mb4 | utf8mb4_bin | NULL | -| def | PERFORMANCE_SCHEMA | utf8mb4 | utf8mb4_bin | NULL | -| def | test | utf8mb4 | utf8mb4_bin | NULL | -+--------------+--------------------+----------------------------+------------------------+----------+ -5 rows in set (0.00 sec) -``` - -## SESSION_VARIABLES 表 - -`SESSION_VARIABLES` 表提供了关于 session 变量的信息。表中的数据跟 `SHOW SESSION VARIABLES` 语句执行结果类似。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM session_variables LIMIT 10; -``` - -``` -+----------------------------------+----------------------+ -| VARIABLE_NAME | VARIABLE_VALUE | -+----------------------------------+----------------------+ -| max_write_lock_count | 18446744073709551615 | -| server_id_bits | 32 | -| net_read_timeout | 30 | -| innodb_online_alter_log_max_size | 134217728 | -| innodb_optimize_fulltext_only | OFF | -| max_join_size | 18446744073709551615 | -| innodb_read_io_threads | 4 | -| session_track_gtids | OFF | -| have_ssl | DISABLED | -| max_binlog_cache_size | 18446744073709547520 | -+----------------------------------+----------------------+ -10 rows in set (0.00 sec) -``` - -## SLOW_QUERY 表 - -`SLOW_QUERY` 表中提供了慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，列名和慢日志中的字段名是一一对应。关于如何使用该表调查和改善慢查询请参考[慢查询日志文档](/v3.1/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)。 - -```sql -mysql> desc information_schema.slow_query; -+---------------+---------------------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+------+---------+-------+ -| Time | timestamp unsigned | YES | | NULL | | -| Txn_start_ts | bigint(20) unsigned | YES | | NULL | | -| User | varchar(64) | YES | | NULL | | -| Host | varchar(64) | YES | | NULL | | -| Conn_ID | bigint(20) unsigned | YES | | NULL | | -| Query_time | double unsigned | YES | | NULL | | -| Process_time | double unsigned | YES | | NULL | | -| Wait_time | double unsigned | YES | | NULL | | -| Backoff_time | double unsigned | YES | | NULL | | -| Request_count | bigint(20) unsigned | YES | | NULL | | -| Total_keys | bigint(20) unsigned | YES | | NULL | | -| Process_keys | bigint(20) unsigned | YES | | NULL | | -| DB | varchar(64) | YES | | NULL | | -| Index_ids | varchar(100) | YES | | NULL | | -| Is_internal | tinyint(1) unsigned | YES | | NULL | | -| Digest | varchar(64) | YES | | NULL | | -| Stats | varchar(512) | YES | | NULL | | -| Cop_proc_avg | double unsigned | YES | | NULL | | -| Cop_proc_p90 | double unsigned | YES | | NULL | | -| Cop_proc_max | double unsigned | YES | | NULL | | -| Cop_proc_addr | varchar(64) | YES | | NULL | | -| Cop_wait_avg | double unsigned | YES | | NULL | | -| Cop_wait_p90 | double unsigned | YES | | NULL | | -| Cop_wait_max | double unsigned | YES | | NULL | | -| Cop_wait_addr | varchar(64) | YES | | NULL | | -| Mem_max | bigint(20) unsigned | YES | | NULL | | -| Succ | tinyint(1) unsigned | YES | | NULL | | -| Query | longblob unsigned | YES | | NULL | | -+---------------+---------------------+------+------+---------+-------+ -``` - -## STATISTICS 表 - -`STATISTICS` 表提供了关于表索引的信息。 - -{{< copyable "sql" >}} - -```sql -desc statistics; -``` - -``` -+---------------|---------------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------|---------------------|------|------|---------|-------+ -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| TABLE_SCHEMA | varchar(64) | YES | | NULL | | -| TABLE_NAME | varchar(64) | YES | | NULL | | -| NON_UNIQUE | varchar(1) | YES | | NULL | | -| INDEX_SCHEMA | varchar(64) | YES | | NULL | | -| INDEX_NAME | varchar(64) | YES | | NULL | | -| SEQ_IN_INDEX | bigint(2) UNSIGNED | YES | | NULL | | -| COLUMN_NAME | varchar(21) | YES | | NULL | | -| COLLATION | varchar(1) | YES | | NULL | | -| CARDINALITY | bigint(21) UNSIGNED | YES | | NULL | | -| SUB_PART | bigint(3) UNSIGNED | YES | | NULL | | -| PACKED | varchar(10) | YES | | NULL | | -| NULLABLE | varchar(3) | YES | | NULL | | -| INDEX_TYPE | varchar(16) | YES | | NULL | | -| COMMENT | varchar(16) | YES | | NULL | | -| INDEX_COMMENT | varchar(1024) | YES | | NULL | | -+---------------|---------------------|------|------|---------|-------+ -``` - -下列语句是等价的： - -{{< copyable "sql" >}} - -```sql -SELECT * FROM INFORMATION_SCHEMA.STATISTICS - WHERE table_name = 'tbl_name' - AND table_schema = 'db_name' -``` - -{{< copyable "sql" >}} - -```sql -SHOW INDEX - FROM tbl_name - FROM db_name -``` - -## TABLES 表 - -`TABLES` 表提供了数据库里面关于表的信息。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: mysql - TABLE_NAME: user - TABLE_TYPE: BASE TABLE - ENGINE: InnoDB - VERSION: 10 - ROW_FORMAT: Compact - TABLE_ROWS: 0 - AVG_ROW_LENGTH: 0 - DATA_LENGTH: 0 -MAX_DATA_LENGTH: 0 - INDEX_LENGTH: 0 - DATA_FREE: 0 - AUTO_INCREMENT: 0 - CREATE_TIME: 2019-03-29 09:17:27 - UPDATE_TIME: NULL - CHECK_TIME: NULL -TABLE_COLLATION: utf8mb4_bin - CHECKSUM: NULL - CREATE_OPTIONS: - TABLE_COMMENT: - TIDB_TABLE_ID: 5 -1 row in set (0.00 sec) -``` - -以下操作是等价的： - -{{< copyable "sql" >}} - -```sql -SELECT table_name FROM INFORMATION_SCHEMA.TABLES - WHERE table_schema = 'db_name' - [AND table_name LIKE 'wild'] -``` - -{{< copyable "sql" >}} - -```sql -SHOW TABLES - FROM db_name - [LIKE 'wild'] -``` - -## TABLE_CONSTRAINTS 表 - -`TABLE_CONSTRAINTS` 表记录了表的约束信息。 - -{{< copyable "sql" >}} - -```sql -SELECT * FROM table_constraints WHERE constraint_type='UNIQUE'; -``` - -``` -*************************** 1. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: name - TABLE_SCHEMA: mysql - TABLE_NAME: help_topic - CONSTRAINT_TYPE: UNIQUE -*************************** 2. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_meta - CONSTRAINT_TYPE: UNIQUE -*************************** 3. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_histograms - CONSTRAINT_TYPE: UNIQUE -*************************** 4. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: tbl - TABLE_SCHEMA: mysql - TABLE_NAME: stats_buckets - CONSTRAINT_TYPE: UNIQUE -*************************** 5. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range - CONSTRAINT_TYPE: UNIQUE -*************************** 6. row *************************** -CONSTRAINT_CATALOG: def - CONSTRAINT_SCHEMA: mysql - CONSTRAINT_NAME: delete_range_done_index - TABLE_SCHEMA: mysql - TABLE_NAME: gc_delete_range_done - CONSTRAINT_TYPE: UNIQUE -6 rows in set (0.00 sec) -``` - -其中： - -* `CONSTRAINT_TYPE` 的取值可以是 `UNIQUE`，`PRIMARY KEY`，或者 `FOREIGN KEY`。 -* `UNIQUE` 和 `PRIMARY KEY` 信息与 `SHOW INDEX` 语句的执行结果类似。 - -## TIDB_HOT_REGIONS 表 - -`TIDB_HOT_REGIONS` 表提供了关于热点 REGION 的相关信息。 - -{{< copyable "sql" >}} - -```sql -desc TIDB_HOT_REGIONS; -``` - -``` -+----------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------+---------------------+------+-----+---------+-------+ -| TABLE_ID | bigint(21) unsigned | YES | | | | -| INDEX_ID | bigint(21) unsigned | YES | | | | -| DB_NAME | varchar(64) | YES | | | | -| TABLE_NAME | varchar(64) | YES | | | | -| INDEX_NAME | varchar(64) | YES | | | | -| TYPE | varchar(64) | YES | | | | -| MAX_HOT_DEGREE | bigint(21) unsigned | YES | | | | -| REGION_COUNT | bigint(21) unsigned | YES | | | | -| FLOW_BYTES | bigint(21) unsigned | YES | | | | -+----------------+---------------------+------+-----+---------+-------+ -``` - -## TIDB_INDEXES 表 - -`TIDB_INDEXES` 记录了所有表中的 INDEX 信息。 - -{{< copyable "sql" >}} - -```sql -desc TIDB_INDEXES; -``` - -``` -+---------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+---------------+---------------------+------+-----+---------+-------+ -| TABLE_SCHEMA | varchar(64) | YES | | | | -| TABLE_NAME | varchar(64) | YES | | | | -| NON_UNIQUE | bigint(21) unsigned | YES | | | | -| KEY_NAME | varchar(64) | YES | | | | -| SEQ_IN_INDEX | bigint(21) unsigned | YES | | | | -| COLUMN_NAME | varchar(64) | YES | | | | -| SUB_PART | bigint(21) unsigned | YES | | | | -| INDEX_COMMENT | varchar(2048) | YES | | | | -| INDEX_ID | bigint(21) unsigned | YES | | | | -+---------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_REGION_PEERS 表 - -`TIKV_REGION_PEERS` 表提供了所有 REGION 的 peer 信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_REGION_PEERS; -``` - -``` -+--------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+---------------------+------+-----+---------+-------+ -| REGION_ID | bigint(21) unsigned | YES | | | | -| PEER_ID | bigint(21) unsigned | YES | | | | -| STORE_ID | bigint(21) unsigned | YES | | | | -| IS_LEARNER | tinyint(1) unsigned | YES | | | | -| IS_LEADER | tinyint(1) unsigned | YES | | | | -| STATUS | varchar(10) | YES | | | | -| DOWN_SECONDS | bigint(21) unsigned | YES | | | | -+--------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_REGION_STATUS 表 - -`TIKV_REGION_STATUS` 表提供了所有 REGION 的状态信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_REGION_STATUS; -``` - -``` -+------------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+------------------+---------------------+------+-----+---------+-------+ -| REGION_ID | bigint(21) unsigned | YES | | | | -| START_KEY | text | YES | | | | -| END_KEY | text | YES | | | | -| EPOCH_CONF_VER | bigint(21) unsigned | YES | | | | -| EPOCH_VERSION | bigint(21) unsigned | YES | | | | -| WRITTEN_BYTES | bigint(21) unsigned | YES | | | | -| READ_BYTES | bigint(21) unsigned | YES | | | | -| APPROXIMATE_SIZE | bigint(21) unsigned | YES | | | | -| APPROXIMATE_KEYS | bigint(21) unsigned | YES | | | | -+------------------+---------------------+------+-----+---------+-------+ -``` - -## TIKV_STORE_STATUS 表 - -`TIKV_STORE_STATUS` 表提供了所有 TiKV Store 的状态信息。 - -{{< copyable "sql" >}} - -```sql -desc TIKV_STORE_STATUS; -``` - -``` -+-------------------+---------------------+------+-----+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+-------------------+---------------------+------+-----+---------+-------+ -| STORE_ID | bigint(21) unsigned | YES | | | | -| ADDRESS | varchar(64) | YES | | | | -| STORE_STATE | bigint(21) unsigned | YES | | | | -| STORE_STATE_NAME | varchar(64) | YES | | | | -| LABEL | json unsigned | YES | | | | -| VERSION | varchar(64) | YES | | | | -| CAPACITY | varchar(64) | YES | | | | -| AVAILABLE | varchar(64) | YES | | | | -| LEADER_COUNT | bigint(21) unsigned | YES | | | | -| LEADER_WEIGHT | bigint(21) unsigned | YES | | | | -| LEADER_SCORE | bigint(21) unsigned | YES | | | | -| LEADER_SIZE | bigint(21) unsigned | YES | | | | -| REGION_COUNT | bigint(21) unsigned | YES | | | | -| REGION_WEIGHT | bigint(21) unsigned | YES | | | | -| REGION_SCORE | bigint(21) unsigned | YES | | | | -| REGION_SIZE | bigint(21) unsigned | YES | | | | -| START_TS | datetime unsigned | YES | | | | -| LAST_HEARTBEAT_TS | datetime unsigned | YES | | | | -| UPTIME | varchar(64) | YES | | | | -+-------------------+---------------------+------+-----+---------+-------+ -``` - -## USER_PRIVILEGES 表 - -`USER_PRIVILEGES` 表提供了关于全局权限的信息。该表的数据根据 `mysql.user` 系统表生成。 - -{{< copyable "sql" >}} - -```sql -desc USER_PRIVILEGES; -``` - -``` -+----------------|--------------|------|------|---------|-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------|--------------|------|------|---------|-------+ -| GRANTEE | varchar(81) | YES | | NULL | | -| TABLE_CATALOG | varchar(512) | YES | | NULL | | -| PRIVILEGE_TYPE | varchar(64) | YES | | NULL | | -| IS_GRANTABLE | varchar(3) | YES | | NULL | | -+----------------|--------------|------|------|---------|-------+ -4 rows in set (0.00 sec) -``` - -## VIEWS 表 - -`VIEWS` 表提供了关于 SQL 视图的信息。 - -{{< copyable "sql" >}} - -```sql -create view test.v1 as select 1; -``` - -``` -Query OK, 0 rows affected (0.00 sec) -``` - -{{< copyable "sql" >}} - -```sql -select * from views; -``` - -``` -*************************** 1. row *************************** - TABLE_CATALOG: def - TABLE_SCHEMA: test - TABLE_NAME: v1 - VIEW_DEFINITION: select 1 - CHECK_OPTION: CASCADED - IS_UPDATABLE: NO - DEFINER: root@127.0.0.1 - SECURITY_TYPE: DEFINER -CHARACTER_SET_CLIENT: utf8 -COLLATION_CONNECTION: utf8_general_ci -1 row in set (0.00 sec) -``` - -## 不支持的 Information Schema 表 - -TiDB 包含以下 `INFORMATION_SCHEMA` 表，但仅会返回空行： - -* `COLUMN_PRIVILEGES` -* `EVENTS` -* `FILES` -* `GLOBAL_STATUS` -* `GLOBAL_VARIABLES` -* `OPTIMIZER_TRACE` -* `PARAMETERS` -* `PARTITIONS` -* `PLUGINS` -* `PROFILING` -* `REFERENTIAL_CONSTRAINTS` -* `ROUTINES` -* `SCHEMA_PRIVILEGES` -* `SESSION_STATUS` -* `TABLESPACES` -* `TABLE_PRIVILEGES` -* `TRIGGERS` diff --git a/v3.1/reference/system-databases/mysql.md b/v3.1/reference/system-databases/mysql.md deleted file mode 100644 index 57e26eb07952..000000000000 --- a/v3.1/reference/system-databases/mysql.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: TiDB 系统表 -category: reference ---- - -# TiDB 系统表 - -本文档主要介绍 TiDB 支持的系统表。 - -## 权限系统表 - -这些系统表里面包含了用户账户以及相应的授权信息： - -* `user` 用户账户，全局权限，以及其它一些非权限的列 -* `db` 数据库级别的权限 -* `tables_priv` 表级的权限 -* `columns_priv` 列级的权限 - -## 服务端帮助信息系统表 - -* `help_topic` 目前为空 - -## 统计信息相关系统表 - -* `stats_buckets` 统计信息的桶 -* `stats_histograms` 统计信息的直方图 -* `stats_meta` 表的元信息，比如总行数和修改数 - -## GC Worker 相关系统表 - -* `gc_delete_range` - -## 其它系统表 - -* `GLOBAL_VARIABLES` 全局系统变量表 -* `tidb` 用于 TiDB 在 bootstrap 的时候记录相关版本信息 diff --git a/v3.1/reference/tidb-binlog/binlog-slave-client.md b/v3.1/reference/tidb-binlog/binlog-slave-client.md deleted file mode 100644 index 252be8c3f016..000000000000 --- a/v3.1/reference/tidb-binlog/binlog-slave-client.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Binlog Slave Client 用户文档 -category: reference ---- - -# Binlog Slave Client 用户文档 - -目前 Drainer 提供了多种输出方式，包括 MySQL、TiDB、file 等。但是用户往往有一些自定义的需求，比如输出到 Elasticsearch、Hive 等，这些需求 Drainer 现在还没有实现，因此 Drainer 增加了输出到 Kafka 的功能，将 binlog 数据解析后按一定的格式再输出到 Kafka 中，用户编写代码从 Kafka 中读出数据再进行处理。 - -## 配置 Kafka Drainer - -修改 Drainer 的配置文件，设置输出为 Kafka，相关配置如下： - -``` -[syncer] -db-type = "kafka" - -[syncer.to] -# Kafka 地址 -kafka-addrs = "127.0.0.1:9092" -# Kafka 版本号 -kafka-version = "0.8.2.0" -``` - -## 自定义开发 - -### 数据格式 - -首先需要了解 Drainer 写入到 Kafka 中的数据格式： - -``` -// Column 保存列的数据，针对数据的类型，保存在对应的变量中 -message Column { - // 数据是否为 null - optional bool is_null = 1 [ default = false ]; - // 保存 int 类型的数据 - optional int64 int64_value = 2; - // 保存 uint、enum, set 类型的数据 - optional uint64 uint64_value = 3; - // 保存 float、double 类型的数据 - optional double double_value = 4; - // 保存 bit、blob、binary、json 类型的数据 - optional bytes bytes_value = 5; - // 保存 date、time、decimal、text、char 类型的数据 - optional string string_value = 6; -} - -// ColumnInfo 保存列的信息，包括列名、类型、是否为主键 -message ColumnInfo { - optional string name = 1 [ (gogoproto.nullable) = false ]; - // MySQL 中小写的列字段类型 - // https://dev.mysql.com/doc/refman/8.0/en/data-types.html - // numeric 类型：int bigint smallint tinyint float double decimal bit - // string 类型：text longtext mediumtext char tinytext varchar - // blob longblob mediumblob binary tinyblob varbinary - // enum set - // json 类型：json - optional string mysql_type = 2 [ (gogoproto.nullable) = false ]; - optional bool is_primary_key = 3 [ (gogoproto.nullable) = false ]; -} - -// Row 保存一行的具体数据 -message Row { repeated Column columns = 1; } - -// MutationType 表示 DML 的类型 -enum MutationType { - Insert = 0; - Update = 1; - Delete = 2; -} - -// Table 包含一个表的数据变更 -message Table { - optional string schema_name = 1; - optional string table_name = 2; - repeated ColumnInfo column_info = 3; - repeated TableMutation mutations = 4; -} - -// TableMutation 保存一行数据的变更 -message TableMutation { - required MutationType type = 1; - // 修改后的数据 - required Row row = 2; - // 修改前的数据，只对 Update MutationType 有效 - optional Row change_row = 3; -} - -// DMLData 保存一个事务所有的 DML 造成的数据变更 -message DMLData { - // `tables` 包含事务中所有表的数据变更 - repeated Table tables = 1; -} - -// DDLData 保存 DDL 的信息 -message DDLData { - // 当前使用的数据库 - optional string schema_name = 1; - // 相关表 - optional string table_name = 2; - // `ddl_query` 是原始的 DDL 语句 query - optional bytes ddl_query = 3; -} - -// BinlogType 为 Binlog 的类型，分为 DML 和 DDL -enum BinlogType { - DML = 0; // Has `dml_data` - DDL = 1; // Has `ddl_query` -} - -// Binlog 保存一个事务所有的变更，Kafka 中保存的数据为该结构数据序列化后的结果 -message Binlog { - optional BinlogType type = 1 [ (gogoproto.nullable) = false ]; - optional int64 commit_ts = 2 [ (gogoproto.nullable) = false ]; - optional DMLData dml_data = 3; - optional DDLData ddl_data = 4; -} -``` - -查看数据格式的具体定义，参见 [binlog.proto](https://github.com/pingcap/tidb-tools/blob/master/tidb-binlog/slave_binlog_proto/proto/binlog.proto)。 - -### Driver - -TiDB-Tools 项目提供了用于读取 Kafka 中 binlog 数据的 Driver，具有如下功能： - -* 读取 Kafka 的数据 -* 根据 commit ts 查找 binlog 在 kafka 中的储存位置 - -使用该 Driver 时，用户需要配置如下信息： - -* KafkaAddr：Kafka 集群的地址 -* CommitTS：从哪个 commit ts 开始读取 binlog -* Offset：从 Kafka 哪个 offset 开始读取，如果设置了 CommitTS 就不用配置该参数 -* ClusterID：TiDB 集群的 cluster ID -* Topic: Kafka Topic 名称，如果 Topic 名称为空，将会使用 drainer _obinlog 中的默认名称 - -用户以包的形式引用 Driver 的代码即可使用，可以参考 Driver 中提供的示例代码来学习如何使用 Driver 以及 binlog 数据的解析，目前提供了两个例子： - -* 使用该 Driver 将数据同步到 MySQL，该示例包含将 binlog 转化为 SQL 的具体方法 -* 使用该 Driver 将数据打印出来 - -Driver 项目地址：[Binlog Slave Driver](https://github.com/pingcap/tidb-tools/tree/master/tidb-binlog/driver)。 - -> **注意：** -> -> - 示例代码仅仅用于示范如何使用 Driver，如果需要用于生产环境需要优化代码。 -> - 目前仅提供了 golang 版本的 Driver 以及示例代码。如果需要使用其他语言，用户需要根据 binlog 的 proto 文件生成相应语言的代码文件，并自行开发程序读取 Kafka 中的 binlog 数据、解析数据、输出到下游。也欢迎用户优化 example 代码，以及提交其他语言的示例代码到 [TiDB-Tools](https://github.com/pingcap/tidb-tools)。 diff --git a/v3.1/reference/tidb-binlog/deploy.md b/v3.1/reference/tidb-binlog/deploy.md deleted file mode 100644 index 60b4eb16ec51..000000000000 --- a/v3.1/reference/tidb-binlog/deploy.md +++ /dev/null @@ -1,627 +0,0 @@ ---- -title: TiDB Binlog 集群部署 -category: reference ---- - -# TiDB Binlog 集群部署 - -## 服务器要求 - -Pump 和 Drainer 均可部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台上。在开发、测试和生产环境下，对服务器硬件配置的要求和建议如下： - -| 服务 | 部署数量 | CPU | 磁盘 | 内存 | -| :-------- | :-------- | :--------| :--------------- | :------ | -| Pump | 3 | 8核+ | SSD, 200 GB+ | 16G | -| Drainer | 1 | 8核+ | SAS, 100 GB+ （如果输出 binlog 为本地文件，磁盘大小视保留数据天数而定） | 16G | - -## 使用 TiDB Ansible 部署 TiDB Binlog - -### 第 1 步：下载 TiDB Ansible - -1. 以 TiDB 用户登录中控机并进入 `/home/tidb` 目录。以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - - | TiDB Ansible 分支 | TiDB 版本 | 备注 | - | ---------------- | --------- | --- | - | release-3.0 | 3.0 版本 | 最新 3.0 稳定版本，可用于生产环境（建议）。 | - -2. 使用以下命令从 GitHub [TiDB Ansible 项目](https://github.com/pingcap/tidb-ansible)上下载 TiDB Ansible 相应分支，默认的文件夹名称为 `tidb-ansible`。 - - - 下载 3.0 版本： - - {{< copyable "shell-regular" >}} - - ```bash - git clone -b release-3.0 https://github.com/pingcap/tidb-ansible.git - ``` - -### 第 2 步：部署 Pump - -1. 修改 tidb-ansible/inventory.ini 文件 - - 1. 设置 `enable_binlog = True`，表示 TiDB 集群开启 binlog。 - - ```ini - ## binlog trigger - enable_binlog = True - ``` - - 2. 为 `pump_servers` 主机组添加部署机器 IP。 - - ```ini - ## Binlog Part - [pump_servers] - 172.16.10.72 - 172.16.10.73 - 172.16.10.74 - ``` - - 默认 Pump 保留 7 天数据，如需修改可修改 `tidb-ansible/conf/pump.yml`（TiDB 3.0.2 及之前版本中为 `tidb-ansible/conf/pump-cluster.yml`）文件中 `gc` 变量值，并取消注释。 - - {{< copyable "" >}} - - ```yaml - global: - # an integer value to control the expiry date of the binlog data, which indicates for how long (in days) the binlog data would be stored - # must be bigger than 0 - # gc: 7 - ``` - - 请确保部署目录有足够空间存储 binlog，详见[调整部署目录](/v3.1/how-to/deploy/orchestrated/ansible.md#调整部署目录)，也可为 Pump 设置单独的部署目录。 - - ```ini - ## Binlog Part - [pump_servers] - pump1 ansible_host=172.16.10.72 deploy_dir=/data1/pump - pump2 ansible_host=172.16.10.73 deploy_dir=/data2/pump - pump3 ansible_host=172.16.10.74 deploy_dir=/data3/pump - ``` - -2. 部署并启动含 Pump 组件的 TiDB 集群 - - 参照上文配置完 `inventory.ini` 文件后，从以下两种方式中选择一种进行部署。 - - **方式一**：在已有的 TiDB 集群上增加 Pump 组件，需按以下步骤逐步进行。 - - 1. 部署 pump_servers 和 node_exporters - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=pump -l ${pump1_ip},${pump2_ip},[${alias1_name},${alias2_name}] - ``` - - > **注意：** - > - > 以上命令中，逗号后不要加空格，否则会报错。 - - 2. 启动 pump_servers - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=pump - ``` - - 3. 更新并重启 tidb_servers - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=tidb - ``` - - 4. 更新监控信息 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - - **方式二**：从零开始部署含 Pump 组件的 TiDB 集群 - - 使用 Ansible 部署 TiDB 集群，方法参考 [使用 TiDB Ansible 部署 TiDB 集群](/v3.1/how-to/deploy/orchestrated/ansible.md)。 - -3. 查看 Pump 服务状态 - - 使用 binlogctl 查看 Pump 服务状态，pd-urls 参数请替换为集群 PD 地址，结果 State 为 online 表示 Pump 启动成功。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible && - resources/bin/binlogctl -pd-urls=http://172.16.10.72:2379 -cmd pumps - ``` - - ``` - INFO[0000] pump: {NodeID: ip-172-16-10-72:8250, Addr: 172.16.10.72:8250, State: online, MaxCommitTS: 403051525690884099, UpdateTime: 2018-12-25 14:23:37 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-73:8250, Addr: 172.16.10.73:8250, State: online, MaxCommitTS: 403051525703991299, UpdateTime: 2018-12-25 14:23:36 +0800 CST} - INFO[0000] pump: {NodeID: ip-172-16-10-74:8250, Addr: 172.16.10.74:8250, State: online, MaxCommitTS: 403051525717360643, UpdateTime: 2018-12-25 14:23:35 +0800 CST} - ``` - -### 第 3 步：部署 Drainer - -1. 获取 initial_commit_ts 的值 - - Drainer 初次启动时需要获取 initial_commit_ts 这个时间戳信息。 - - - 如果从最近的时间点开始同步，initial_commit_ts 使用 `-1` 即可。 - - - 如果下游为 MySQL 或 TiDB，为了保证数据的完整性，需要进行全量数据的备份与恢复。此时 initial_commit_ts 的值必须是全量备份的时间戳。 - - 如果使用 mydumper 进行全量备份，可以在导出目录中找到 metadata 文件，其中的 `Pos` 字段值即全量备份的时间戳。metadata 文件示例如下： - - ``` - Started dump at: 2019-12-30 13:25:41 - SHOW MASTER STATUS: - Log: tidb-binlog - Pos: 413580274257362947 - GTID: - - Finished dump at: 2019-12-30 13:25:41 - ``` - -2. 修改 `tidb-ansible/inventory.ini` 文件 - - 为 `drainer_servers` 主机组添加部署机器 IP，initial_commit_ts 请设置为获取的 initial_commit_ts，仅用于 Drainer 第一次启动。 - - - 以下游为 MySQL 为例，别名为 `drainer_mysql`。 - - ```ini - [drainer_servers] - drainer_mysql ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - - - 以下游为 file 为例，别名为 `drainer_file`。 - - ```ini - [drainer_servers] - drainer_file ansible_host=172.16.10.71 initial_commit_ts="402899541671542785" - ``` - -3. 修改配置文件 - - - 以下游为 MySQL 为例 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible/conf && - cp drainer.toml drainer_mysql_drainer.toml && - vi drainer_mysql_drainer.toml - ``` - - > **注意：** - > - > 配置文件名命名规则为 `别名_drainer.toml`，否则部署时无法找到自定义配置文件。 - > 但是需要注意 v3.0.0，v3.0.1 的配置文件命名规则与其余版本略有不同，为 `别名_drainer-cluster.toml`。 - - db-type 设置为 "mysql"， 配置下游 MySQL 信息。 - - {{< copyable "" >}} - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "mysql" - - # the downstream MySQL protocol database - [syncer.to] - host = "172.16.10.72" - user = "root" - password = "123456" - port = 3306 - ``` - - - 以下游为增量备份文件为例 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/tidb-ansible/conf && - cp drainer.toml drainer_file_drainer.toml && - vi drainer_file_drainer.toml - ``` - - db-type 设置为 "file"。 - - {{< copyable "" >}} - - ```toml - [syncer] - # downstream storage, equal to --dest-db-type - # Valid values are "mysql", "file", "tidb", "kafka". - db-type = "file" - - # Uncomment this if you want to use "file" as "db-type". - [syncer.to] - # default data directory: "{{ deploy_dir }}/data.drainer" - dir = "data.drainer" - ``` - -4. 部署 Drainer - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy_drainer.yml - ``` - -5. 启动 Drainer - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start_drainer.yml - ``` - -## 使用 Binary 部署 TiDB Binlog - -### 下载官方 Binary - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，Pump 和 Drainer 已经包含在 TiDB 的下载包中，其他版本需要单独下载 Pump 和 Drainer: - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-binlog-latest-linux-amd64.sha256 -``` - -### 使用样例 - -假设有三个 PD，一个 TiDB，另外有两台机器用于部署 Pump，一台机器用于部署 Drainer。各个节点信息如下： - -``` -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -Pump="192.168.0.11" -Pump="192.168.0.12" -Drainer="192.168.0.13" -``` - -下面以此为例，说明 Pump/Drainer 的使用。 - -1. 使用 binary 部署 Pump - - - Pump 命令行参数说明（以在 “192.168.0.11” 上部署为例） - - ```bash - Usage of Pump: - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.11:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.11:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置; - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里的配置。 - -data-dir string - Pump 数据存储位置路径 - -gc int - Pump 只保留多少天以内的数据 (默认 7) - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -node-id string - Pump 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -fake-binlog-interval int - Pump 节点生成 fake binlog 的频率 (默认 3，单位 秒) - ``` - - - Pump 配置文件（以在 “192.168.0.11” 上部署为例） - - ```toml - # Pump Configuration - - # Pump 绑定的地址 - addr = "192.168.0.11:8250" - - # Pump 对外提供服务的地址 - advertise-addr = "192.168.0.11:8250" - - # Pump 只保留多少天以内的数据 (默认 7) - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 2 - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/drainer.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/drainer-key.pem" - - # [storage] - # 设置为 true（默认值）来保证可靠性，确保 binlog 数据刷新到磁盘 - # sync-log = true - - # 当可用磁盘容量小于该设置值时，Pump 将停止写入数据，v3.0.1 后支持该功能 - # 42 MB -> 42000000, 42 mib -> 44040192 - # default: 10 gib - # stop-write-at-available-space = "10 gib" - - # Pump 内嵌的 LSM DB 设置，除非对该部分很了解，否则一般注解掉 - # [storage.kv] - # block-cache-capacity = 8388608 - # block-restart-interval = 16 - # block-size = 4096 - # compaction-L0-trigger = 8 - # compaction-table-size = 67108864 - # compaction-total-size = 536870912 - # compaction-total-size-multiplier = 8.0 - # write-buffer = 67108864 - # write-L0-pause-trigger = 24 - # write-L0-slowdown-trigger = 17 - ``` - - - 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -2. 使用 binary 部署 Drainer - - - Drainer 命令行参数说明（以在 “192.168.0.13” 上部署为例） - - ```bash - Usage of Drainer - -L string - 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.13:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -cache-binlog-count int - 缓存中的 binlog 数目限制（默认 8） - 如果上游的单个 binlog 较大导致 Drainer 出现 OOM 时，可尝试调小该值减少内存使用 - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的配置 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql，支持 tidb、kafka、file) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则每个 binlog - 按顺序依次还原成单个事务进行同步（下游服务类型为 MySQL，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts（默认为 `-1`） - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - 该参数值为 `-1` 时，Drainer 会自动从 PD 获取一个最新的时间戳 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位：秒） - -node-id string - v3.0.2 后支持该功能，drainer 节点的唯一识别 ID，如果不指定程序会根据主机名和监听端口自动生成 - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -safe-mode - 是否开启安全模式使得下游 MySQL/TiDB 可被重复写入 - 即将 insert 语句换为 replace 语句，将 update 语句拆分为 delete + replace 语句 - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - - - Drainer 配置文件（以在 “192.168.0.13” 上部署为例） - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.13:8249") - addr = "192.168.0.13:8249" - - # Drainer 对外提供服务的地址 - advertise-addr = "192.168.0.13:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # PD 集群节点的地址 (英文逗号分割，中间不加空格) - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Drainer 从 Pump 获取 binlog 时对数据进行压缩，值可以为 "gzip"，如果不配置则不进行压缩 - # compressor = "gzip" - - # [security] - # 如无特殊安全设置需要，该部分一般都注解掉 - # 包含与集群连接的受信任 SSL CA 列表的文件路径 - # ssl-ca = "/path/to/ca.pem" - # 包含与集群连接的 PEM 形式的 X509 certificate 的路径 - # ssl-cert = "/path/to/pump.pem" - # 包含与集群链接的 PEM 形式的 X509 key 的路径 - # ssl-key = "/path/to/pump-key.pem" - - # Syncer Configuration - [syncer] - # 如果设置了该项，会使用该 sql-mode 解析 DDL 语句，此时如果下游是 MySQL 或 TiDB 则 - # 下游的 sql-mode 也会被设置为该值 - # sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" - - # 输出到下游数据库一个事务的 SQL 语句数量 (默认 20) - txn-batch = 20 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (默认 16) - worker-count = 16 - - # 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 MySQL, 该项设置为 False） - disable-dispatch = false - - # safe mode 会使写下游 MySQL/TiDB 可被重复写入 - # 会用 replace 替换 insert 语句，用 delete + replace 替换 update 语句 - safe-mode = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql"，"tidb"，"file"，"kafka" - db-type = "mysql" - - # 事务的 commit ts 若在该列表中，则该事务将被过滤，不会同步至下游，v3.0.2 后支持该功能 - ignore-txn-commit-ts = [] - - # db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - # 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。 - # 以 '~' 开始声明使用正则表达式 - - # replicate-do-db = ["~^b.*","s1"] - - # [syncer.relay] - # 保存 relay log 的目录，空值表示不开启。 - # 只有下游是 TiDB 或 MySQL 时该配置才生效。 - # log-dir = "" - # 每个文件的大小上限 - # max-file-size = 10485760 - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "log" - - # [[syncer.replicate-do-table]] - # db-name ="test" - # tbl-name = "~^a.*" - - # 忽略同步某些表 - # [[syncer.ignore-table]] - # db-name = "test" - # tbl-name = "log" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.13" - user = "root" - password = "" - # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 - # encrypted_password 非空时 password 会被忽略 - encrypted_password = "" - port = 3306 - - [syncer.to.checkpoint] - # 当 checkpoint type 是 mysql 或 tidb 时可以开启该选项，以改变保存 checkpoint 的数据库 - # schema = "tidb_binlog" - # 目前只支持 mysql 或者 tidb 类型。可以去掉注释来控制 checkpoint 保存的位置。 - # db-type 默认的 checkpoint 保存方式是: - # mysql/tidb -> 对应的下游 mysql/tidb - # file/kafka -> file in `data-dir` - # type = "mysql" - # host = "127.0.0.1" - # user = "root" - # password = "" - # 使用 `./binlogctl -cmd encrypt -text string` 加密的密码 - # encrypted_password 非空时 password 会被忽略 - # encrypted_password = "" - # port = 3306 - - # db-type 设置为 file 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - - # db-type 设置为 kafka 时，Kafka 相关配置 - # [syncer.to] - # kafka-addrs 和 zookeeper-addrs 只需要一个，两者都有时程序会优先用 zookeeper 中的 kafka 地址 - # zookeeper-addrs = "127.0.0.1:2181" - # kafka-addrs = "127.0.0.1:9092" - # kafka-version = "0.8.2.0" - # kafka-max-messages = 1024 - - # 保存 binlog 数据的 Kafka 集群的 topic 名称，默认值为 _obinlog - # 如果运行多个 Drainer 同步数据到同一个 Kafka 集群，每个 Drainer 的 topic-name 需要设置不同的名称 - # topic-name = "" - - ``` - - - 启动示例 - - > **注意：** - > - > 如果下游为 MySQL/TiDB，为了保证数据的完整性，在 Drainer 初次启动前需要获取 `initial-commit-ts` 的值，并进行全量数据的备份与恢复。详细信息参见[部署 Drainer](#第-3-步部署-drainer)。 - - 初次启动时使用参数 `initial-commit-ts`， 命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml -initial-commit-ts {initial-commit-ts} - ``` - - 如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 - -> **注意：** -> -> - 在运行 TiDB 时，需要保证至少一个 Pump 正常运行。 -> - 通过给 TiDB 增加启动参数 `enable-binlog` 来开启 binlog 服务。尽量保证同一集群的所有 TiDB 都开启了 binlog 服务，否则在同步数据时可能会导致上下游数据不一致。如果要临时运行一个不开启 binlog 服务的 TiDB 实例，需要在 TiDB 的配置文件中设置 `run_ddl= false`。 -> - Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 -> - 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取**快照时间戳**，然后导入全量备份，最后启动 Drainer 从对应的快照时间戳开始同步增量数据。 -> - 下游使用 MySQL 或 TiDB 时应当保证上下游数据库的 sql_mode 具有一致性，即下游数据库同步每条 SQL 语句时的 sql_mode 应当与上游数据库执行该条 SQL 语句时的 sql_mode 保持一致。可以在上下游分别执行 `select @@sql_mode;` 进行查询和比对。 -> - 如果存在上游 TiDB 能运行但下游 MySQL 不支持的 DDL 语句时（例如下游 MySQL 使用 InnoDB 引擎时同步语句 `CREATE TABLE t1(a INT) ROW_FORMAT=FIXED;`），Drainer 也会同步失败，此时可以在 Drainer 配置中跳过该事务，同时在下游手动执行兼容的语句，详见[跳过事务](/v3.1/reference/tidb-binlog/faq.md#同步时出现上游数据库支持但是下游数据库执行会出错的-ddl应该怎么办)。 diff --git a/v3.1/reference/tidb-binlog/faq.md b/v3.1/reference/tidb-binlog/faq.md deleted file mode 100644 index 5dcd5a3e525a..000000000000 --- a/v3.1/reference/tidb-binlog/faq.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: TiDB Binlog 常见问题 -category: FAQ ---- - -# TiDB Binlog 常见问题 - -本文介绍 TiDB Binlog 使用过程中的常见问题及解决方案。 - -## 开启 binog 对 TiDB 的性能有何影响？ - -- 对于查询无影响。 - -- 对于有写入或更新数据的事务有一点性能影响。延迟上，在 Prewrite 阶段要并发写一条 p-binlog 成功后才可以提交事务，一般写 binlog 比 KV Prewrite 快，所以不会增加延迟。可以在 Pump 的监控面板看到写 binlog 的响应时间。 - -## Drainer 同步下游 TiDB/MySQL 的帐号需要哪些权限？ - -Drainer 同步帐号需要有如下权限： - -* Insert -* Update -* Delete -* Create -* Drop -* Alter -* Execute -* Index -* Select - -## Pump 磁盘快满了怎么办？ - -确认 GC 正常： - -- 确认 pump 监控面板 **gc_tso** 时间是否与配置一致，版本 <= v3.0.0 的 pump 会保证非 `offline` 状态 Drainer 消费了数据才会 gc，如果有不再使用的 Drainer 需要使用 binlogctl 下线。 - -如 gc 正常以下调整可以降低单个 pump 需要的空间大小： - -- 调整 pump **GC** 参数减少保留数据天数。 -- 添加 pump 结点。 - -## Drainer 同步中断怎么办？ - -使用以下 binlogctl 命令查看 Pump 状态是否正常，以及是否全部非 `offline`状态的 Pump 都在正常运行。 - -{{< copyable "shell-regular" >}} - -```bash -binlogctl -cmd pumps -``` - -查看 Drainer 监控与日志是否有对应报错，根据具体问题进行处理。 - -## Drainer 同步下游 TiDB/MySQL 慢怎么办？ - -特别关注以下监控项： - -- 通过 Drainer 监控 **drainer event**，可以看到 Drainer 当前每秒同步 Insert/Update/Delete 事件到下游的速度。 -- 通过 Drainer 监控 **sql query time**，可以看到 Drainer 在下游执行 SQL 的响应时间。 - -同步慢的可能原因与解决方案： - -- 同步的数据库包含没有主键或者唯一索引的表，需要给表加上主键。 -- Drainer 与下游之间延迟大，可以调大 Drainer `worker-count` 参数（跨机房同步建议将 Drainer 部署在下游）。 -- 下游负载不高，可以尝试调大 Drainer `worker-count` 参数。 - -## 假如有一个 Pump crash 了会怎样？ - -Drainer 会因为获取不到这个 Pump 的数据没法同步数据到下游。如果这个 Pump 能恢复，Drainer 就能恢复同步。 - -如果 Pump 没法恢复，可采用以下方式进行处理： - -1. 使用 [binlogctl 将该 Pump 状态修改为 `offline`](/v3.1/reference/tidb-binlog/maintain.md)（丢失这个 Pump 的数据） -2. Drainer 获取到的数据会丢失这个 Pump 上的数据，下游跟上游数据会不一致，需要重新做全量 + 增量同步。具体步骤如下： - 1. 停止当前 Drainer。 - 2. 上游做全量备份。 - 3. 清理掉下游数据，包括 checkpoint 表 `tidb_binlog.checkpoint`。 - 4. 使用上游的全量备份恢复下游数据。 - 5. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 什么是 checkpoint？ - -Checkpoint 记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 -Drainer 日志 `["write save point"] [ts=411222863322546177]` 表示保存对应时间戳的 checkpoint。 - -下游类型不同，checkpoint 的保存方式也不同： - -- 下游 MySQL/TiDB 保存在 `tidb_binlog.checkpoint` 表。 -- 下游 kafka/file 保存在对应配置目录里的文件。 - -因为 kafka/file 的数据内容包含了 commit-ts，所以如果 checkpoint 丢失，可以消费下游最新的一条数据看写到下游数据的最新 commit-ts。 - -Drainer 启动的时候会去读取 checkpoint，如果读取不到，就会使用配置的 `initial-commit-ts` 做为初次启动开始的同步时间点。 - -## Drainer 机器发生故障，下游数据还在，如何在新机器上重新部署 Drainer？ - -如果下游数据还在，只要保证能从对应 checkpoint 接着同步即可。 - -假如 checkpoint 还在，可采用以下方式进行处理： - -1. 部署新的 Drainer 并启动即可（参考 checkpoint 介绍，Drainer 可以读取 checkpoint 接着同步）。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/v3.1/reference/tidb-binlog/maintain.md)。 - -假如 checkpoint 不在，可以如下处理： - -1. 获取之前 Drainer 的 checkpoint `commit-ts`，做为新部署 Drainer 的 `initial-commit-ts` 配置来部署新的 Drainer。 -2. 使用 [binlogctl 将老的 Drainer 状态修改成 `offline`](/v3.1/reference/tidb-binlog/maintain.md)。 - -## 如何用全量 + binlog 备份文件来恢复一个集群？ - -1. 清理集群数据并使用全部备份恢复数据。 -2. 使用 reparo 设置 `start-tso` = {全量备份文件快照时间戳+1}，`end-ts` = 0（或者指定时间点），恢复到备份文件最新的数据。 - -## 主从同步开启 `ignore-error` 触发 critical error 后如何重新部署？ - -TiDB 配置开启 `ignore-error` 写 binlog 失败后触发 critical error 告警，后续都不会再写 binlog，所以会有 binlog 数据丢失。如果要恢复同步，需要如下处理： - -1. 停止当前 Drainer。 -2. 重启触发 critical error 的 `tidb-server` 实例重新开始写 binlog（触发 critical error 后不会再写 binlog 到 pump）。 -3. 上游做全量备份。 -4. 清理掉下游数据包括 checkpoint 表 `tidb_binlog.checkpoint`。 -5. 使用上游的全量备份恢复下游。 -6. 部署 Drainer，使用 `initialCommitTs`= {从全量备份获取快照的时间戳}。 - -## 同步时出现上游数据库支持但是下游数据库执行会出错的 DDL，应该怎么办？ - -1. 查看 drainer.log 日志，查找 `exec failed` 找到 Drainer 退出前最后一条执行失败的 DDL。 -2. 将 DDL 改为下游兼容支持的版本，在下游数据库中手动执行。 -3. 查看 drainer.log 日志，查找执行失败的 DDL 语句，可以查询到该 DDL 的 commit-ts。 -4. 编辑 `drainer.toml` 配置文件，在 `ignore-txn-commit-ts` 项中添加该 commit-ts，重启 Drainer。 - -在绝大部分情况下，TiDB 和 MySQL 的语句都是兼容的。用户需要注意的是上下游的 `sql_mode` 应当保持一致。 - -## 在什么情况下暂停和下线 Pump/Drainer？ - -首先需要通过以下内容来了解 Pump/Drainer 的状态定义和启动、退出的流程。 - -暂停主要针对临时需要停止服务的场景，例如： - -- 版本升级：停止进程后使用新的 binary 启动服务。 -- 服务器维护：需要对服务器进行停机维护。退出进程，等维护完成后重启服务。 - -下线主要针对永久（或长时间）不再使用该服务的场景，例如： - -- Pump 缩容：不再需要那么多 Pump 服务了，所以下线部分服务。 -- 同步任务取消：不再需要将数据同步到某个下游，所以下线对应的 Drainer。 -- 服务器迁移：需要将服务迁移到其他服务器。下线服务，在新的服务器上重新部署。 - -## 可以通过哪些方式暂停 Pump/Drainer？ - -- 直接 kill 进程。 - - >**注意：** - > - > 不能使用 `kill -9` 命令，否则 Pump/Drainer 无法对信号进行处理 - -- 如果 Pump/Drainer 运行在前台，则可以通过按下 Ctrl+C 来暂停。 -- 使用 binlogctl 的 `pause-pump` 或 `pause-drainer` 命令。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来下线 Pump/Drainer 服务吗？ - -不可以。使用 `update-pump`/`update-drainer` 命令会直接修改 PD 中保存的状态信息，并且不会通知 Pump/Drainer 做相应的操作。使用不当时，可能会干扰数据同步，某些情况下还可能会造成**数据不一致**的严重后果。例如： - -- 当 Pump 正常运行或者处于暂停状态时，如果使用 `update-pump` 将该 Pump 设置为 `offline`，那么 Drainer 会放弃获取处于 `offline` 状态的 Pump 的 binlog 数据，导致该 Pump 最新的 binlog 数据没有同步到 Drainer，造成上下游数据不一致。 -- 当 Drainer 正常运行时，使用 `update-drainer` 命令将该 Drainer 设置为 `offline`。如果这时启动一个 Pump 节点，Pump 只会通知 `online` 状态的 Drainer，导致该 Drainer 没有及时获取到该 Pump 的 binlog 数据，造成上下游数据不一致。 - -## 可以使用 binlogctl 的 `update-pump`/`update-drainer` 命令来暂停 Pump/Drainer 服务吗？ - -不可以。`update-pump`/`update-drainer` 命令直接修改 PD 中保存的状态信息。执行这个命令并不会通知 Pump/Drainer 做相应的操作，**而且使用不当会使数据同步中断，甚至造成数据丢失。** - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `paused`？ - -在某些异常情况下，Pump 没有正确维护自己的状态，实际上状态应该为 `paused`。这时可以使用 `update-pump` 对状态进行修正，例如： - -- Pump 异常退出（可能由 panic 或者误操作执行 `kill -9` 命令直接 kill 掉进程导致），Pump 保存在 PD 中的状态仍然为 `online`。如果暂时不需要重启 Pump 恢复服务，可以使用 `update-pump` 把该 Pump 状态设置为 `paused`，避免对 TiDB 写 binlog 和 Drainer 获取 binlog 造成干扰。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `paused`？ - -在某些异常情况下，Drainer 没有正确维护自己的状态，，对数据同步造成了影响，实际上状态应该为 `paused`。这时可以使用 `update-drainer` 对状态进行修正，例如： - -- Drainer 异常退出（出现 panic 直接退出进程，或者误操作执行 `kill -9` 命令直接 kill 掉进程），Drainer 保存在 PD 中的状态仍然为 `online`。当 Pump 启动时无法正常通知该 Drainer（报错 `notify drainer ...`），导致 Pump 无法正常运行。这个时候可以使用 `update-drainer` 将 Drainer 状态更新为 `paused`，再启动 Pump。 - -## 可以通过哪些方式下线 Pump/Drainer？ - -目前只可以使用 binlogctl 的 `offline-pump` 和 `offline-drainer` 命令来下线 Pump 和 Drainer。 - -## 什么情况下使用 binlogctl 的 `update-pump` 命令设置 Pump 状态为 `offline`? - -> **警告：** -> -> 仅在可以容忍 binlog **数据丢失、上下游数据不一致**或者确认不再需要使用该 Pump 存储的 binlog 数据的情况下，才能使用 `update-pump` 修改 Pump 状态为 `offline`。 - -可以使用 `update-pump` 修改 Pump 状态为 `offline` 的情况有： - -- 在某些情况下，Pump 异常退出进程，且无法恢复服务，同步就会中断。如果希望恢复同步且可以容忍部分 binlog 数据丢失，可以使用 `update-pump` 命令将该 Pump 状态设置为 `offline`，则 Drainer 会放弃拉取该 Pump 的 binlog 然后继续同步数据。 -- 有从历史任务遗留下来且不再使用的 Pump 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-pump` 将该 Pump 设置为 `offline`。 - -在其他情况下一定要使用 `offline-pump` 命令让 Pump 走正常的下线处理流程。 - -## Pump 进程已经退出，且状态为 `paused`，现在不想使用这个 Pump 节点了，能否用 binlogctl 的 `update-pump` 命令设置节点状态为 `offline`？ - -Pump 以 `paused` 状态退出进程时，不保证所有 binlog 数据被下游 Drainer 消费。所以这样做会有上下游数据不一致的风险。正确的做法是重新启动 Pump，然后使用 `offline-pump` 下线该 Pump。 - -## 什么情况下使用 binlogctl 的 `update-drainer` 命令设置 Drainer 状态为 `offline`？ - -- 有从历史任务遗留下来且不再使用的 Drainer 且进程已经退出（例如测试使用的服务），之后不再需要使用该服务，使用 `update-drainer` 将该 Drainer 设置为 `offline`。 - -## 可以使用 `change pump`、`change drainer` 等 SQL 操作来暂停或者下线 Pump/Drainer 服务吗？ - -目前还不支持。这种 SQL 操作会直接修改 PD 中保存的状态，在功能上等同于使用 binlogctl 的 `update-pump`、`update-drainer` 命令。如果需要暂停或者下线，仍然要使用 binlogctl。 diff --git a/v3.1/reference/tidb-binlog/glossary.md b/v3.1/reference/tidb-binlog/glossary.md deleted file mode 100644 index 473cfa7fece0..000000000000 --- a/v3.1/reference/tidb-binlog/glossary.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB Binlog 术语表 -summary: 学习 TiDB Binlog 相关术语 -category: glossary ---- - -# TiDB Binlog 术语表 - -本文档介绍 TiDB Binlog 相关术语。 - -## Binlog - -在 TiDB Binlog 中，Binlog 通常 TiDB 写的 Binlog 数据，注意 TiDB Binlog 的格式跟 MySQL 不同，也指 Drainer 写到 Kafka 或者文件的 Binlog 数据，但他们的格式不一样。 - -## Binlog event - -TiDB 写的 DML Binlog 有 3 种 event, 分别是 Insert, Update, Delete, Drainer 监控面板 可以看到对应同步数据不同 event 的个数。 - -## Checkpoint - -Checkpoint 指保存的断点信息，记录了 Drainer 同步到下游的 commit-ts，Drainer 重启时可以读取 checkpoint 接着从对应 commit-ts 同步数据到下游。 - -## Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在 Drainer 启动的前 5 分钟会自动启动 Safe mode，另外也可以配置文件中通过 `safe-mode` 参数手动开启。 - -该配置仅对下游是 MySQL/TiDB 有效。 diff --git a/v3.1/reference/tidb-binlog/maintain.md b/v3.1/reference/tidb-binlog/maintain.md deleted file mode 100644 index 028b3aa08307..000000000000 --- a/v3.1/reference/tidb-binlog/maintain.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: TiDB Binlog 集群运维 -category: reference ---- - -# TiDB Binlog 集群运维 - -本文首先介绍 Pump 和 Drainer 的状态及启动、退出的内部处理流程，然后说明如何通过 binlogctl 工具或者直接在 TiDB 执行 SQL 操作来管理 binlog 集群，最后的 FAQ 部分会介绍一些常见问题以及处理方法。 - -## Pump/Drainer 的状态 - -Pump/Drainer 中状态的定义： - -* online：正常运行中 -* pausing：暂停中 -* paused：已暂停 -* closing：下线中 -* offline：已下线 - -这些状态由 Pump/Drainer 服务自身进行维护，并定时将状态信息更新到 PD 中。 - -## Pump/Drainer 的启动、退出流程 - -### Pump - -* 启动：Pump 启动时会通知所有 online 状态的 Drainer，如果通知成功，则 Pump 将状态设置为 online，否则 Pump 将报错，然后将状态设置为 paused 并退出进程。 -* 退出：Pump 进程正常退出前要选择进入暂停或者下线状态；非正常退出（kill -9、进程 panic、宕机）都依然保持 online 状态。 - - * 暂停：使用 kill（非 kill -9）、Ctrl+C 或者使用 binlogctl 的 pause-pump 命令都可以暂停 Pump。接收到暂停指令后，Pump 会变更状态为 pausing，并停止接受 binlog 的写请求，也停止向 Drainer 提供 binlog 数据。安全退出所有线程后，更新状态为 paused 然后退出进程。 - * 下线：仅在使用 binlogctl 的 offline-pump 命令的情况下才会下线 Pump。接收到下线指令后，Pump 会变更状态为 closing，并停止接受 binlog 的写请求。Pump 继续向 Drainer 提供 binlog，等待所有 binlog 数据都被 Drainer 消费后再将状态设置为 offline 并退出进程。 - -### Drainer - -* 启动：Drainer 启动时将状态设置为 online，并尝试从所有非 offline 状态的 Pump 获取 binlog，如果获取 binlog 失败，会不断尝试重新获取。 -* 退出：Drainer 进程正常退出前要选择进入暂停或者下线状态；非正常退出（kill -9 、进程 panic、宕机）都依然保持 online 状态。 - - * 暂停：使用 kill（非 kill -9）、Ctrl+C 或者使用 binlogctl 的 pause-drainer 命令都可以暂停 Drainer。接收到指令后，Drainer 会变更状态为 pausing，并停止从 Pump 获取 binlog。安全退出所有线程后，更新状态为 paused 然后退出进程。 - * 下线：仅在使用 binlogctl 的 offline-drainer 命令的情况下才会下线 Drainer。接收到下线指令后，Drainer 变更状态为 closing，并停止从 Pump 获取 binlog。安全退出所有线程后，更新状态为 offline 然后退出进程。 - -关于 Pump/Drainer 暂停、下线、状态查询、状态修改等具体的操作方法，参考如下 binlogctl 工具的使用方法介绍。 - -## binlogctl 工具 - -支持如下这些功能： - -* 查看 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer -* Pump/Drainer 异常状态处理 - -使用 binlogctl 的场景： - -* 同步出现故障/检查运行情况，需要查看 Pump/Drainer 的状态 -* 维护集群，需要暂停/下线 Pump/Drainer -* Pump/Drainer 异常退出，状态没有更新，或者状态不符合预期，对业务造成影响 - -binlogctl 下载链接： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-{version}-linux-amd64.sha256 -``` - -对于 v2.1.0 GA 及以上版本，binlogctl 已经包含在 TiDB 的下载包中，其他版本需要单独下载 binlogctl: - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz && \ -wget https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-enterprise-tools-latest-linux-amd64.sha256 -``` - -binlogctl 使用说明： - -命令行参数： - -```bash -Usage of binlogctl: --V -输出 binlogctl 的版本信息 --cmd string - 命令模式，包括 "generate_meta"（已废弃）, "pumps", "drainers", "update-pump" ,"update-drainer", "pause-pump", "pause-drainer", "offline-pump", "offline-drainer" --data-dir string - 保存 Drainer 的 checkpoint 的文件的路径 (默认 "binlog_position")（已废弃） --node-id string - Pump/Drainer 的 ID --pd-urls string - PD 的地址，如果有多个，则用"," 连接 (默认 "http://127.0.0.1:2379") --ssl-ca string - SSL CAs 文件的路径 --ssl-cert string - PEM 格式的 X509 认证文件的路径 --ssl-key string - PEM 格式的 X509 key 文件的路径 --time-zone string - 如果设置时区，在 "generate_meta" 模式下会打印出获取到的 tso 对应的时间。例如 "Asia/Shanghai" 为 CST 时区，"Local" 为本地时区 --show-offline-nodes - 在用 -cmd pumps 或 -cmd drainers 时使用，这两个命令默认不显示 offline 的节点，仅当明确指定 -show-offline-nodes 时会显示 -``` - -命令示例： - -- 查询所有的 Pump/Drainer 的状态： - - 设置 `cmd` 为 `pumps` 或者 `drainers` 来查看所有 Pump 或者 Drainer 的状态。例如： - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pumps - ``` - - ``` - [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=pump] [node="{NodeID: 1.1.1.1:8250, Addr: pump:8250, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"] - ``` - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd drainers - ``` - - ``` - [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=drainer] [node="{NodeID: 1.1.1.1:8249, Addr: 1.1.1.1:8249, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"] - ``` - -- 暂停/下线 Pump/Drainer - - binlogctl 提供以下命令暂停/下线服务： - - | cmd | 说明 | 示例 | - | --------------- | ------------- | ------------------------------------------------------------------------------------------------| - | pause-pump | 暂停 Pump | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-pump -node-id ip-127-0-0-1:8250` | - | pause-drainer | 暂停 Drainer | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-drainer -node-id ip-127-0-0-1:8249` | - | offline-pump | 下线 Pump | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-pump -node-id ip-127-0-0-1:8250` | - | offline-drainer | 下线 Drainer | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-drainer -node-id ip-127-0-0-1:8249` | - - binlogctl 会发送 HTTP 请求给 Pump/Drainer，Pump/Drainer 收到命令后会主动执行对应的退出流程。 - -- 异常情况下修改 Pump/Drainer 的状态 - - 在服务正常运行以及符合流程的暂停、下线过程中，Pump/Drainer 的状态都是可以正确的。但是在一些异常情况下 Pump/Drainer 无法正确维护自己的状态，可能会影响数据同步任务，在这种情况下需要使用 binlogctl 修复状态信息。 - - 设置 `cmd` 为 `update-pump` 或者 `update-drainer` 来更新 Pump 或者 Drainer 的状态。Pump 和 Drainer 的状态可以为 paused 或者 offline。例如： - - {{< copyable "shell-regular" >}} - - ```bash - bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd update-pump -node-id ip-127-0-0-1:8250 -state paused - ``` - - > **注意：** - > - > Pump/Drainer 在正常运行过程中会定期在 PD 中更新自己的状态，而这条命令是直接去修改 Pump/Drainer 保存在 PD 中的状态，所以在 Pump/Drainer 服务正常的情况下使用这些命令是没有意义的。仅在 Pump/Drainer 服务异常的情况下使用，具体哪些场景下使用这条命令可以参考 FAQ。 - -## 使用 TiDB SQL 管理 Pump/Drainer - -要查看和管理 binlog 相关的状态，可在 TiDB 中执行相应的 SQL 语句。 - -- 查看 TiDB 是否开启 binlog - - {{< copyable "sql" >}} - - ```sql - show variables like "log_bin"; - ``` - - ``` - +---------------+-------+ - | Variable_name | Value | - +---------------+-------+ - | log_bin | ON | - +---------------+-------+ - ``` - - 值为 `ON` 时表示 TiDB 开启了 binlog。 - -- 查看 Pump/Drainer 状态 - - {{< copyable "sql" >}} - - ```sql - show pump status; - ``` - - ``` - +--------|----------------|--------|--------------------|---------------------| - | NodeID | Address | State | Max_Commit_Ts | Update_Time | - +--------|----------------|--------|--------------------|---------------------| - | pump1 | 127.0.0.1:8250 | Online | 408553768673342237 | 2019-05-01 00:00:01 | - +--------|----------------|--------|--------------------|---------------------| - | pump2 | 127.0.0.2:8250 | Online | 408553768673342335 | 2019-05-01 00:00:02 | - +--------|----------------|--------|--------------------|---------------------| - ``` - - {{< copyable "sql" >}} - - ```sql - show drainer status; - ``` - - ``` - +----------|----------------|--------|--------------------|---------------------| - | NodeID | Address | State | Max_Commit_Ts | Update_Time | - +----------|----------------|--------|--------------------|---------------------| - | drainer1 | 127.0.0.3:8249 | Online | 408553768673342532 | 2019-05-01 00:00:03 | - +----------|----------------|--------|--------------------|---------------------| - | drainer2 | 127.0.0.4:8249 | Online | 408553768673345531 | 2019-05-01 00:00:04 | - +----------|----------------|--------|--------------------|---------------------| - ``` - -- 异常情况下修改 Pump/Drainer 状态 - - {{< copyable "sql" >}} - - ```sql - change pump to node_state ='paused' for node_id 'pump1'; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - change drainer to node_state ='paused' for node_id 'drainer1'; - ``` - - ``` - Query OK, 0 rows affected (0.01 sec) - ``` - - 该 SQL 的功能和 binlogctl 中的 update-pump 和 update-drainer 命令的功能一样，因此也只有在 Pump/Drainer 异常的情况下使用。 - -> **注意：** -> -> 1. 查看 binlog 开启状态以及 Pump/Drainer 状态的功能在 TiDB v2.1.7 及以上版本中支持。 -> 2. 修改 Pump/Drainer 状态的功能在 TiDB v3.0.0-rc.1 及以上版本中支持。该功能只修改 PD 中存储的 Pump/Drainer 状态，如果需要暂停/下线节点，仍然需要使用 `binlogctl`。 diff --git a/v3.1/reference/tidb-binlog/monitor.md b/v3.1/reference/tidb-binlog/monitor.md deleted file mode 100644 index 65b5217dda36..000000000000 --- a/v3.1/reference/tidb-binlog/monitor.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: TiDB Binlog 集群监控 -category: reference ---- - -# TiDB Binlog 集群监控 - -使用 Ansible 成功部署 TiDB Binlog 集群后，可以进入 Grafana Web 界面（默认地址: ，默认账号：admin，密码：admin）查看 Pump 和 Drainer 的运行状态。 - -## 监控指标 - -### Pump - -| metric 名称 | 说明 | -|:----|:------------| -| Storage Size | 记录磁盘的总空间大小 (capacity)，以及可用磁盘空间大小 (available) | -| Metadata | 记录每个 Pump 的可删除 binlog 的最大 tso (gc_tso)，以及保存的 binlog 的最大的 commit tso (max_commit_tso)。 | -| Write Binlog QPS by Instance | 每个 Pump 接收到的写 binlog 请求的 QPS | -| Write Binlog Latency | 记录每个 Pump 写 binlog 的延迟时间 | -| Storage Write Binlog Size | Pump 写 binlog 数据的大小 | -| Storage Write Binlog Latency | Pump 中的 storage 模块写 binlog 数据的延迟 | -| Pump Storage Error By Type | Pump 遇到的 error 数量，按照 error 的类型进行统计 | -| Query TiKV | Pump 通过 TiKV 查询事务状态的次数 | - -### Drainer - -| metric 名称 | 说明 | -|:----|:------------| -| Checkpoint TSO | Drainer 已经同步到下游的 binlog 的最大 TSO 对应的时间。可以通过该指标估算同步延迟时间 | -| Pump Handle TSO | 记录 Drainer 从各个 Pump 获取到的 binlog 的最大 TSO 对应的时间 | | Pull Binlog QPS by Pump NodeID | Drainer 从每个 Pump 获取 binlog 的 QPS | -| 95% Binlog Reach Duration By Pump | 记录 binlog 从写入 Pump 到被 Drainer 获取到这个过程的延迟时间 | -| Error By Type | Drainer 遇到的 error 数量，按照 error 的类型进行统计 | -| SQL Query Time| Drainer 在下游执行 SQL 的耗时 | -| Drainer Event | 各种类型 event 的数量，event 包括 ddl、insert、delete、update、flush、savepoint | -| Execute Time | 写入 binlog 到同步下游模块所消耗的时间 | -| 95% Binlog Size | Drainer 从各个 Pump 获取到 binlog 数据的大小 | -| DL Job Count | Drainer 处理的 DDL 的数量| -| Queue Size | Drainer 内部工作队列大小 | - -## 监控报警规则 - -本节介绍了 TiDB Binlog 组件的报警项及相应的报警规则。根据严重级别，报警项可分为三类，按照严重程度由高到低依次为：紧急级别 (Emergency)、重要级别 (Critical)、警告级别 (Warning)。 - -### 紧急级别报警项 - -紧急级别的报警通常由于服务停止或节点故障导致，此时需要马上进行人工干预操作。 - -#### `binlog_pump_storage_error_count` - -* 报警规则： - - `changes(binlog_pump_storage_error_count[1m]) > 0` - -* 规则描述： - - Pump 写 binlog 到本地存储时失败。 - -* 处理方法： - - 确认 `pump_storage_error` 监控是否存在错误，查看 Pump 日志确认原因。 - -### 重要级别报警项 - -对于重要级别的报警，需要密切关注异常指标。 - -#### `binlog_drainer_checkpoint_high_delay` - -* 报警规则： - - `(time() - binlog_drainer_checkpoint_tso / 1000) > 3600` - -* 规则描述： - - Drainer 同步落后延迟超过 1 个小时。 - -* 处理方法： - - * 判断从 Pump 获取数据是否太慢： - - 监控 Pump handle tso 可以看每个 Pump 最近一条消息的时间，是不是有延迟特别大的 Pump，确认对应 Pump 正常运行。 - - * 根据 Drainer event 和 Drainer execute latency 来判断是否下游同步太慢： - - * 如果 Drainer execute time 过大，则检查到目标库网络带宽和延迟，以及目标库状态。 - * 如果 Drainer execute time 不大，Drainer event 过小，则增加 work count 和 batch 进行重试。 - - * 如果上面都不满足或者操作后没有改观，则报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -### 警告级别报警项 - -警告级别的报警是对某一问题或错误的提醒。 - -#### `binlog_pump_write_binlog_rpc_duration_seconds_bucket` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_pump_rpc_duration_seconds_bucket{method="WriteBinlog"}[5m])) > 1` - -* 规则描述： - - Pump 处理 TiDB 写 Binlog 请求耗时过大。 - -* 处理方法： - - * 确认磁盘性能压力，通过 `node exported` 查看 disk performance 监控。 - * 如果 `disk latency` 和 `util` 都很低，那么报备开发人员 [support@pingcap.com](mailto:support@pingcap.com) 进行处理。 - -#### `binlog_pump_storage_write_binlog_duration_time_bucket` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_pump_storage_write_binlog_duration_time_bucket{type="batch"}[5m])) > 1` - -* 规则描述： - - Pump 写本地 binlog 到本地盘的耗时。 - -* 处理方法： - - 确认 Pump 本地盘情况，进行修复。 - -#### `binlog_pump_storage_available_size_less_than_20G` - -* 报警规则： - - `binlog_pump_storage_storage_size_bytes{type="available"} < 20 * 1024 * 1024 * 1024` - -* 规则描述： - - Pump 剩余可用磁盘空间不足 20 G。 - -* 处理方法： - - 监控确认 Pump 的 `gc_tso` 是否正常。如果不正常，调整 Pump 的 GC 时间配置或者下线对应 Pump。 - -#### `binlog_drainer_checkpoint_tso_no_change_for_1m` - -* 报警规则： - - `changes(binlog_drainer_checkpoint_tso[1m]) < 1` - -* 规则描述： - - Drainer 的 `checkpoint` 在 1 分钟内没有更新。 - -* 处理方法： - - 确认所有非下线的 Pump 是否正常运行。 - -#### `binlog_drainer_execute_duration_time_more_than_10s` - -* 报警规则： - - `histogram_quantile(0.9, rate(binlog_drainer_execute_duration_time_bucket[1m])) > 10` - -* 规则描述： - - Drainer 同步到 TiDB 的事务耗时。如果这个值过大，会影响 Drainer 同步。 - -* 处理方法： - - * 查看 TiDB 集群的状态。 - * 查看 Drainer 日志或监控，如果是 DDL 操作导致了该问题，则忽略。 diff --git a/v3.1/reference/tidb-binlog/overview.md b/v3.1/reference/tidb-binlog/overview.md deleted file mode 100644 index 28e97cb07782..000000000000 --- a/v3.1/reference/tidb-binlog/overview.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: TiDB Binlog 简介 -category: reference ---- - -# TiDB Binlog 简介 - -TiDB Binlog 是一个用于收集 TiDB 的 binlog，并提供准实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景： - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog 整体架构 - -![TiDB Binlog 架构](/media/tidb_binlog_cluster_architecture.png) - -TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl 工具： - -### Pump - -[Pump](https://github.com/pingcap/tidb-binlog/blob/master/pump) 用于实时记录 TiDB 产生的 Binlog，并将 Binlog 按照事务的提交时间进行排序，再提供给 Drainer 进行消费。 - -### Drainer - -[Drainer](https://github.com/pingcap/tidb-binlog/tree/master/drainer) 从各个 Pump 中收集 Binlog 进行归并，再将 Binlog 转化成 SQL 或者指定格式的数据，最终同步到下游。 - -### binlogctl 工具 - -[`binlogctl`](https://github.com/pingcap/tidb-binlog/tree/master/binlogctl) 是一个 TiDB Binlog 配套的运维工具，具有如下功能： - -* 获取 TiDB 集群当前的 TSO -* 查看 Pump/Drainer 状态 -* 修改 Pump/Drainer 状态 -* 暂停/下线 Pump/Drainer - -## 主要特性 - -* 多个 Pump 形成一个集群，可以水平扩容。 -* TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。 -* Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。 -* Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。 -* Drainer 支持 [relay log](/v3.1/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。 - -## 注意事项 - -* 需要使用 TiDB v2.0.8-binlog、v2.1.0-rc.5 及以上版本，否则不兼容该版本的 TiDB Binlog。 - -* Drainer 支持将 Binlog 同步到 MySQL、TiDB、Kafka 或者本地文件。如果需要将 Binlog 同步到其他 Drainer 不支持的类型的系统中，可以设置 Drainer 将 Binlog 同步到 Kafka，然后根据 binlog slave protocol 进行定制处理，参考 [binlog slave client 用户文档](/v3.1/reference/tidb-binlog/binlog-slave-client.md)。 - -* 如果 TiDB Binlog 用于增量恢复，可以设置配置项 `db-type="file"`，Drainer 会将 binlog 转化为指定的 [proto buffer 格式](https://github.com/pingcap/tidb-binlog/blob/master/proto/binlog.proto)的数据，再写入到本地文件中。这样就可以使用 [Reparo](/v3.1/reference/tidb-binlog/reparo.md) 恢复增量数据。 - - 关于 `db-type` 的取值，应注意： - - - 如果 TiDB 版本 < 2.1.9，则 `db-type="pb"`。 - - 如果 TiDB 版本 > = 2.1.9，则 `db-type="file"` 或 `db-type="pb"`。 - -* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/v3.1/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。 diff --git a/v3.1/reference/tidb-binlog/relay-log.md b/v3.1/reference/tidb-binlog/relay-log.md deleted file mode 100644 index cf54ee9b06ba..000000000000 --- a/v3.1/reference/tidb-binlog/relay-log.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB Binlog Relay Log -category: reference -aliases: ['/docs-cn/v3.1/reference/tools/tidb-binlog/relay-log/'] ---- - -# TiDB Binlog Relay Log - -Drainer 同步 binlog 时会拆分上游的事务，并将拆分的事务并发同步到下游。在极端情况下，上游集群不可用并且 Drainer 异常退出后，下游集群（MySQL 或 TiDB）可能处于数据不一致的中间状态。在此场景下，Drainer 借助 relay log 可以确保将下游集群同步到一个一致的状态。 - -## Drainer 同步时的一致性状态 - -下游集群达到一致的状态是指：下游集群的数据等同于上游设置了 `tidb_snapshot = ts` 的快照。 - -checkpoint 状态一致性是指：Drainer checkpoint 通过 `consistent` 保存了同步的一致性状态。Drainer 运行时 `consistent` 为 `false`，Drainer 正常退出后 `consistent` 更新为 `true`。 - -查询下游 checkpoint 表的示例如下： - -``` -mysql> select * from tidb_binlog.checkpoint; -+---------------------+----------------------------------------------------------------+ -| clusterID | checkPoint | -+---------------------+----------------------------------------------------------------+ -| 6791641053252586769 | {"consistent":false,"commitTS":414529105591271429,"ts-map":{}} | -+---------------------+----------------------------------------------------------------+ -``` - -## 工作原理 - -Drainer 开启 relay log 后会先将 binlog event 写到磁盘上，然后再同步给下游集群。如果上游集群不可用，Drainer 可以通过读取 relay log 把下游集群恢复到一个一致的状态。 - -> **注意：** -> -> 若同时丢失 relay log 数据，该方法将不可用，不过这是概率极小的事件。此外可以使用 NFS 等网络文件系统来保证 relay log 的数据安全。 - -### Drainer 从 relay log 消费 binlog 的触发场景 - -如果 Drainer 启动时无法连接到上游集群的 PD，并且探测到 checkpoint 的 `consistent = false`，此时会尝试读取 relay log，并将下游集群恢复到一致的状态。然后 Drainer 进程将 checkpoint 的 `status` 设置为 `0` 后主动退出。 - -### Relay log 的清理（GC）机制 - -Drainer 在运行时，如果确认已经将一个 relay log 文件的全部数据都成功同步到下游了，就会马上删除这个文件，所以 relay log 不会占用过多空间。一个 relay log 文件大小达到 10MB（默认）时就会做切分，数据开始写入新的 relay log 文件。 - -## 配置 - -在 Drainer 中添加以下配置来开启 relay log 功能： - -{{< copyable "" >}} - -``` -[syncer.relay] -# 保存 relay log 的目录，空值表示不开启。 -# 只有下游是 TiDB 或 MySQL 时该配置才有生效。 -log-dir = "/dir/to/save/log" -``` diff --git a/v3.1/reference/tidb-binlog/reparo.md b/v3.1/reference/tidb-binlog/reparo.md deleted file mode 100644 index 6aa579d8e3a3..000000000000 --- a/v3.1/reference/tidb-binlog/reparo.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Reparo 使用文档 -category: reference ---- - -# Reparo 使用文档 - -Reparo 是 TiDB Binlog 的一个配套工具，用于增量的恢复。使用 TiDB Binlog 中的 Drainer 将 binlog 按照 protobuf 格式输出到文件，通过这种方式来备份增量数据。当需要恢复增量数据时，使用 Reparo 解析文件中的 binlog，并将其应用到 TiDB／MySQL 中。 - -下载链接：[tidb-binlog-cluster-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-binlog-cluster-latest-linux-amd64.tar.gz) - -## Reparo 使用 - -### 命令行参数说明 - -``` -Usage of Reparo: --L string - 日志输出信息等级设置：debug, info, warn, error, fatal（默认值：info）。 --V 打印版本信息。 --c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好（默认 16）。 --config string - 配置文件路径，如果指定了配置文件，Reparo 会首先读取配置文件的配置；如果对应的配置在命令行参数里面也存在，Reparo 就会使用命令行参数的配置来覆盖配置文件里面的。 --data-dir string - Drainer 输出的 protobuf 格式 binlog 文件的存储路径 (默认值： data.drainer)。 --dest-type string - 下游服务类型。 取值为 print, mysql（默认值：print）。当值为 print 时，只做解析打印到标准输出，不执行 SQL；如果为 mysql，则需要在配置文件内配置 host、port、user、password 等信息。 --log-file string - log 文件路径。 --log-rotate string - log 文件切换频率，取值为 hour、day。 --start-datetime string - 用于指定开始恢复的时间点，格式为 “2006-01-02 15:04:05”。如果不设置该参数则从最早的 binlog 文件开始恢复。 --stop-datetime string - 用于指定结束恢复的时间点，格式同上。如果不设置该参数则恢复到最后一个 binlog 文件。 --safe-mode bool - 指定是否开启安全模式，开启后可支持反复同步。 --txn-batch int - 输出到下游数据库一个事务的 SQL 语句数量（默认 20）。 -``` - -### 配置文件说明 - -```toml -# Drainer 输出的 protobuf 格式 binlog 文件的存储路径。 -data-dir = "./data.drainer" - -# 使用索引文件来搜索 ts 的位置，当设置了 `start-ts` 时设置该参数，文件的路径为 {data-dir}/{index-name}。 -# index-name = "binlog.index" -# log-file = "" -# log-rotate = "hour" - -# 日志输出信息等级设置：debug, info, warn, error, fatal (默认值：info)。 -log-level = "info" - -# 使用 start-datetime 和 stop-datetime 来选择恢复指定时间范围内的 binlog，格式为 “2006-01-02 15:04:05”。 -# start-datetime = "" -# stop-datetime = "" - -# start-tso、stop-tso 分别对应 start-datetime 和 stop-datetime，也是用于恢复指定时间范围内的 binlog，用 tso 的值来设置。如果已经设置了 start-datetime 和 stop-datetime，就不需要再设置 start-tso 和 stop-tso。 -# start-tso = 0 -# stop-tso = 0 - -# 下游服务类型。 取值为 print, mysql（默认值：print）。当值为 print 时，只做解析打印到标准输出，不执行 SQL；如果为 mysql，则需要在 [dest-db] 中配置 host、port、user、password 等信息。 -dest-type = "mysql" - -# 输出到下游数据库一个事务的 SQL 语句数量（默认 20）。 -txn-batch = 20 - -# 同步下游的并发数，该值设置越高同步的吞吐性能越好（默认 16）。 -worker-count = 16 - -# 安全模式配置。取值为 true 或 false（默认值：false）。当值为 true 时，Reparo 会将 update 语句拆分为 delete + replace 语句。 -safe-mode = false - -# replicate-do-db 和 replicate-do-table 用于指定恢复的库和表，replicate-do-db 的优先级高于 replicate-do-table。支持使用正则表达式来配置，需要以 '~' 开始声明使用正则表达式。 -# 注：replicate-do-db 和 replicate-do-table 使用方式与 Drainer 的使用方式一致。 -# replicate-do-db = ["~^b.*","s1"] -# [[replicate-do-table]] -# db-name ="test" -# tbl-name = "log" -# [[replicate-do-table]] -# db-name ="test" -# tbl-name = "~^a.*" - -# 如果 dest-type 设置为 mysql, 需要配置 dest-db。 -[dest-db] -host = "127.0.0.1" -port = 3309 -user = "root" -password = "" -``` - -### 启动示例 - -{{< copyable "shell-regular" >}} - -```bash -./bin/reparo -config reparo.toml -``` - -> **注意：** -> -> - data-dir 用于指定 Drainer 输出的 binlog 文件目录。 -> - start-datatime 和 start-tso 效果一样，只是时间格式上的区别，用于指定开始恢复的时间点；如果不指定，则默认在第一个 binlog 文件开始恢复。 -> - stop-datetime 和 stop-tso 效果一样，只是时间格式上的区别，用于指定结束恢复的时间点；如果不指定，则恢复到最后一个 binlog 文件的结尾。 -> - dest-type 指定目标类型，取值为 `mysql`、`print`。 当值为 `mysql` 时，可以恢复到 MySQL/TiDB 等使用或兼容 MySQL 协议的数据库，需要在配置下面的 [dest-db] 填写数据库信息；当取值为 `print` 的时候，只是打印 binlog 信息，通常用于 debug，以及查看 binlog 的内容，此时不需要填写 `[dest-db]`。 -> - replicate-do-db 用于指定恢复的库，不指定的话，则全部都恢复。 -> - replicate-do-table 用于指定要恢复的表，不指定的话，则全部都恢复。 diff --git a/v3.1/reference/tidb-binlog/tidb-binlog-kafka.md b/v3.1/reference/tidb-binlog/tidb-binlog-kafka.md deleted file mode 100644 index c1bb2b199a0f..000000000000 --- a/v3.1/reference/tidb-binlog/tidb-binlog-kafka.md +++ /dev/null @@ -1,457 +0,0 @@ ---- -title: TiDB Binlog kafka 部署方案 -category: reference ---- - -# TiDB Binlog Kafka 部署方案 - -本文档介绍如何部署 Kafka 版本的 TiDB Binlog。 - -## TiDB Binlog 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -- **数据同步**：同步 TiDB 集群数据到其他数据库 -- **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复 - -## TiDB Binlog Kafka 架构 - -首先介绍 TiDB Binlog 的整体架构。 - -![TiDB Binlog 架构](/media/tidb_binlog_kafka_architecture.png) - -TiDB Binlog 集群主要分为三个组件： - -### Pump - -Pump 是一个守护进程，在每个 TiDB 主机的后台运行。其主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入 Kafka 中。 - -### Drainer - -Drainer 从 Kafka 中收集 Binlog，并按照 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件。 - -### Kafka & ZooKeeper - -Kafka 集群用来存储由 Pump 写入的 Binlog 数据，并提供给 Drainer 进行读取。 - -> **注意：** -> -> Local 版本将 Binlog 存储在文件中，Kafka 版本则使用 Kafka 存储。 - -## TiDB Binlog 安装 - -以下为 TiDB Ansible 分支与 TiDB 版本的对应关系，版本选择可咨询官方 info@pingcap.com。 - -| TiDB Ansible 分支 | TiDB 版本 | 备注 | -|:----|:----|:----| -| release-2.0 | 2.0 版本 | 最新 2.0 稳定版本，可用于生产环境。 | - -### 下载官方 Binary - -环境：CentOS 7+ - -下载压缩包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz && -wget https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c tidb-binlog-kafka-linux-amd64.sha256 -``` - -解开压缩包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf tidb-binlog-kafka-linux-amd64.tar.gz && -cd tidb-binlog-kafka-linux-amd64 -``` - -### TiDB Binlog 部署 - -#### 注意事项 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 的方式输出 Binlog。 - -* 手动部署时，启动顺序为：Pump > TiDB。停止顺序为 TiDB > Pump。 - - 设置 TiDB 启动参数 `binlog-socket` 为对应的 Pump 参数 `socket` 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。 - -* 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取 savepoint，然后导入全量备份，最后启动 Drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 Pump 运行 10 分钟左右后按顺序进行如下操作： - - * 使用 [binlogctl](https://github.com/pingcap/tidb-tools/tree/binlog-kafka/tidb_binlog/binlogctl) 工具生成 Drainer 初次启动所需的 position - * 全量备份，例如 Mydumper 备份 TiDB - * 全量导入备份到目标系统 - * Kafka 版本 Drainer 启动的 savepoint 默认保存在下游 database tidb_binlog 下的 checkpoint 表中，如果 checkpoint 表中没有有效的数据，可以通过设置 `initial-commit-ts` 启动 Drainer 从指定位置开始消费 - `bin/drainer --config=conf/drainer.toml --initial-commit-ts=${position}` - -* Drainer 输出为 pb，要在配置文件中设置如下参数： - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -* Drainer 输出为 kafka，要在配置文件中设置如下参数： - - ```toml - [syncer] - db-type = "kafka" - - # when db-type is kafka, you need to use this to config the down stream kafka, or it will be the same kafka addrs where drainer pull binlog from. - [syncer.to] - kafka-addrs = "127.0.0.1:9092" - kafka-version = "0.8.2.0" - ``` - - 输出到 kafka 的数据为按 ts 排好序的 protobuf 定义 binlog 格式，可以参考 [driver](https://github.com/pingcap/tidb-tools/tree/master/tidb-binlog/driver) 获取数据同步到下游。 - -* Kafka 和 ZooKeeper 集群需要在部署 TiDB Binlog 之前部署好。Kafka 需要 0.9 及以上版本。 - -#### Kafka 集群配置推荐 - -|名字|数量|内存|CPU|硬盘| -|:---:|:---:|:---:|:---:|:---:| -|Kafka|3+|16G|8+|2+ 1TB| -|ZooKeeper|3+|8G|4+|2+ 300G| - -#### Kafka 配置参数推荐 - -- `auto.create.topics.enable = true`：如果还没有创建 topic，Kafka 会在 broker 上自动创建 topic -- `broker.id`：用来标识 Kafka 集群的必备参数，不能重复，如 `broker.id = 1` -- `fs.file-max = 1000000`：Kafka 会使用大量文件和网络 socket，建议修改成 1000000，通过 `vi /etc/sysctl.conf` 进行修改 -- 修改以下配置为1G, 否则很容易出现事务修改数据较多导致单个消息过大写 kafka 失败 - - * `message.max.bytes=1073741824` - * `replica.fetch.max.bytes=1073741824` - * `fetch.message.max.bytes=1073741824` - -#### 使用 TiDB Ansible 部署 Pump - -- 如无 Kafka 集群，可使用 [kafka-ansible](https://github.com/pingcap/thirdparty-ops/tree/master/kafka-ansible) 部署 Kafka 集群。 -- 使用 [tidb-ansible](https://github.com/pingcap/tidb-ansible) 部署 TiDB 集群时，修改 `tidb-ansible/inventory.ini` 文件，设置 `enable_binlog = True`，并配置 `zookeeper_addrs` 变量为 Kafka 集群的 ZooKeeper 地址，这样部署 TiDB 集群时会部署 Pump。 - -配置样例: - -```ini -# binlog trigger -enable_binlog = True -# ZooKeeper address of Kafka cluster, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -# You can also append an optional chroot string to the URLs to specify the root directory for all Kafka znodes, example: -# zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" -zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" -``` - -#### 使用 Binary 部署 Pump - -使用样例： - -假设我们有三个 PD，三个 ZooKeeper，一个 TiDB，各个节点信息如下： - -```ini -TiDB="192.168.0.10" -PD1="192.168.0.16" -PD2="192.168.0.15" -PD3="192.168.0.14" -ZK1="192.168.0.13" -ZK2="192.168.0.12" -ZK3="192.168.0.11" -``` - -在 ip="192.168.0.10" 的机器上面部署 Drainer/Pump。 - -对应的 PD 集群的 ip="192.168.0.16,192.168.0.15,192.168.0.14"。 - -对应的 Kafka 集群的 ZooKeeper 的 ip="192.168.0.13,192.168.0.12,192.168.0.11"。以此为例，说明 Pump/Drainer 的使用。 - -1. Pump 命令行参数说明 - - ``` - Usage of Pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - Pump 提供服务的 RPC 地址(-addr="192.168.0.10:8250") - -advertise-addr string - Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.10:8250") - -config string - 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里面的。 - -data-dir string - Pump 数据存储位置路径 - -enable-tolerant - 开启 tolerant 后，如果 binlog 写入失败，Pump 不会报错（默认开启） - -zookeeper-addrs string (-zookeeper_addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181") - ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，需要和 Kafka 中配置相同 - -gc int - 日志最大保留天数 (默认 7)，设置为 0 可永久保存 - -heartbeat-interval int - Pump 向 PD 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -socket string - unix socket 模式服务监听地址（默认 unix:///tmp/pump.sock） - ``` - -2. Pump 配置文件 - - ```toml - # Pump Configuration. - - # Pump 提供服务的 RPC 地址("192.168.0.10:8250") - addr = "192.168.0.10:8250" - - # Pump 对外提供服务的 RPC 地址("192.168.0.10:8250") - advertise-addr = "" - - # binlog 最大保留天数 (默认 7)，设置为 0 可永久保存 - gc = 7 - - # Pump 数据存储位置路径 - data-dir = "data.pump" - - # ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，若 Kafka 中配置了命名空间，则此处需同样配置 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" - # 配置了命令空间的 ZooKeeper 地址配置示例 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" - - # Pump 向 PD 发送心跳的间隔 (单位 秒) - heartbeat-interval = 3 - - # PD 集群节点的地址 - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of Drainer: - -L string - 日志输出信息等级设置：debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - Drainer 提供服务的地址(-addr="192.168.0.10:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径，Drainer 会首先读取配置文件的配置； - 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - Drainer 数据存储位置路径 (默认 "data.drainer") - -zookeeper-addrs string (-zookeeper-addrs="192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181") - ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，需要和 Kafka 中配置相同 - -dest-db-type string - Drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步（下游服务类型为 mysql，该项设置为 False） - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -initial-commit-ts (默认为 0) - 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率，hour/day - -metrics-addr string - Prometheus pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率（默认 15，单位 秒） - -pd-urls string - PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") - -txn-batch int - 输出到下游数据库一个事务的 SQL 数量（默认 1） - ``` - -2. Drainer 配置文件 - - ```toml - # Drainer Configuration. - - # Drainer 提供服务的地址("192.168.0.10:8249") - addr = "192.168.0.10:8249" - - # 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # Drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # ZooKeeper 地址，该选项从 ZooKeeper 中获取 Kafka 地址，若 Kafka 中配置了命名空间，则此处需同样配置 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181" - # 配置了命令空间的 ZooKeeper 地址配置示例 - # zookeeper-addrs = "192.168.0.11:2181,192.168.0.12:2181,192.168.0.13:2181/kafka/123" - - # PD 集群节点的地址 - pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 SQL 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步（下游服务类型为 mysql, 该项设置为 False） - disable-dispatch = false - - # Drainer 下游服务类型（默认为 mysql） - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db prioritizes over replicate-do-table when they have the same db name - # and we support regex expressions, - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "192.168.0.10" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时，存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## 下载 PbReader 工具 (Linux) - -PbReader 用于解析 Drainer 生成的 Pb 文件，并翻译成对应的 SQL 语句。 - -环境：CentOS 7+ - -下载 PbReader 压缩包： - -{{< copyable "shell-regular" >}} - -```bash -wget https://download.pingcap.org/pb_reader-latest-linux-amd64.tar.gz && -wget https://download.pingcap.org/pb_reader-latest-linux-amd64.sha256 -``` - -检查文件完整性，返回 ok 则正确： - -{{< copyable "shell-regular" >}} - -```bash -sha256sum -c pb_reader-latest-linux-amd64.sha256 -``` - -解开压缩包： - -{{< copyable "shell-regular" >}} - -```bash -tar -xzf pb_reader-latest-linux-amd64.tar.gz && -cd pb_reader-latest-linux-amd64 -``` - -PbReader 使用示例： - -{{< copyable "shell-regular" >}} - -```bash -./bin/pbReader -binlog-file=${path}/binlog-0000000000000000 -``` - -## TiDB Binlog 监控 - -本部分主要介绍如何对 TiDB Binlog 的状态、性能做监控，并通过 Prometheus + Grafana 展现 metrics 数据。 - -### Pump/Drainer 配置 - -使用 Ansible 部署的 Pump 服务已经在启动参数设置 metrics。启动 Drainer 时可以设置以下两个参数： - -- `--metrics-addr`：设为 Push Gateway 的地址 -- `--metrics-interval`：设为 push 的频率，单位为秒，默认值为 15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号：admin，密码：admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 - - > **注意：** - > - > Type 选 Prometheus，URL 为 Prometheus 地址，根据实际情况添加/填写。 - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/syncer.json)上传 -> 选择对应的 data source diff --git a/v3.1/reference/tidb-binlog/tidb-binlog-local.md b/v3.1/reference/tidb-binlog/tidb-binlog-local.md deleted file mode 100644 index 5ddb5d201eee..000000000000 --- a/v3.1/reference/tidb-binlog/tidb-binlog-local.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: TiDB Binlog Local 部署方案 -category: reference ---- - -# TiDB Binlog Local 部署方案 - -## TiDB Binlog Local 简介 - -TiDB Binlog 是用于收集 TiDB 的 Binlog，并提供实时备份和同步功能的商业工具。 - -TiDB Binlog 支持以下功能场景: - -* **数据同步**：同步 TiDB 集群数据到其他数据库。 -* **实时备份和恢复**：备份 TiDB 集群数据，同时可以用于 TiDB 集群故障时恢复。 - -## TiDB Binlog Local 架构 - -下图为 TiDB Binlog Local的整体架构。 - -![TiDB Binlog 架构](/media/architecture.jpeg) - -TiDB Binlog Local 主要分为两个组件： - -- **Pump** 是一个守护进程，在每个 TiDB 的主机上后台运行。他的主要功能是实时记录 TiDB 产生的 Binlog 并顺序写入磁盘文件 - -- **Drainer** 从各个 Pump 节点收集 Binlog，并按照在 TiDB 中事务的提交顺序转化为指定数据库兼容的 SQL 语句，最后同步到目的数据库或者写到顺序文件 - -## TiDB Binlog Local 安装 - -### TiDB Binlog Local 下载 - -TiDB Binlog 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v3.1/reference/tools/download.md)。 - -### TiDB Binlog Local 部署 - -#### 注意 - -* 需要为一个 TiDB 集群中的每台 TiDB server 部署一个 Pump，目前 TiDB server 只支持以 unix socket 方式的输出 binlog。 -* 手动部署时， 启动顺序为： Pump > TiDB，停止顺序为 TiDB > Pump - - 我们设置 TiDB 启动参数 binlog-socket 为对应的 Pump 的参数 socket 所指定的 unix socket 文件路径，最终部署结构如下图所示： - - ![TiDB pump 模块部署结构](/media/tidb-pump-deployment.png) - -* drainer 不支持对 ignore schemas（在过滤列表中的 schemas） 的 table 进行 rename DDL 操作 - -* 在已有的 TiDB 集群中启动 drainer，一般需要全量备份 并且获取 savepoint，然后导入全量备份，最后启动 drainer 从 savepoint 开始同步。 - - 为了保证数据的完整性，在 pump 运行 10 分钟左右后按顺序进行下面的操作 - - * 以 gen-savepoint model 运行 drainer 生成 drainer savepint 文件，`bin/drainer -gen-savepoint --data-dir= ${drainer_savepoint_dir} --pd-urls=${pd_urls}` - * 全量备份，例如 Mydumper 备份 tidb - * 全量导入备份到目标系统 - * 设置 savepoint 文件路径，然后启动 drainer，`bin/drainer --config=conf/drainer.toml --data-dir=${drainer_savepoint_dir}` - -* drainer 输出的 pb, 需要在配置文件设置下面的参数 - - ```toml - [syncer] - db-type = "pb" - disable-dispatch = true - - [syncer.to] - dir = "/path/pb-dir" - ``` - -#### 使用 TiDB Ansible 部署 Pump (推荐) - -* 搭建全新的 TiDB Cluster，启动顺序 pd-server -> tikv-server -> pump -> tidb-server -> drainer - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook deploy.yml - * 执行 ansible-playbook start.yml - * drainer 目前需要手动部署 - -* 对已有的 TiDB Cluster 部署 binlog - * 修改 tidb-ansible inventory.ini 文件 - * enable_binlog = True - * 执行 ansible-playbook rolling_update.yml --tags=tidb - * drainer 目前需要手动部署 - -#### 使用 Binary 部署 Pump - -1. PUMP 命令行参数说明 - - ``` - Usage of pump: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -advertise-addr string - pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - -config string - 配置文件路径,如果你指定了配置文件，pump 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，pump 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - pump 数据存储位置路径 - -gc int - 日志最大保留天数 (默认 7)， 设置为 0 可永久保存 - -heartbeat-interval uint - pump 向 pd 发送心跳间隔 (单位 秒) - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -socket string - unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - ``` - - 2. PUMP 配置文件 - - ```toml - # pump Configuration. - # pump 提供服务的 rpc 地址(默认 "127.0.0.1:8250") - addr = "127.0.0.1:8250" - # pump 对外提供服务的 rpc 地址(默认 "127.0.0.1:8250") - advertise-addr = "" - # binlog 最大保留天数 (默认 7)， 设置为 0 可永久保存 - gc = 7 - # pump 数据存储位置路径 - data-dir = "data.pump" - # pump 向 pd 发送心跳间隔 (单位 秒) - heartbeat-interval = 3 - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - # unix socket 模式服务监听地址 (默认 unix:///tmp/pump.sock) - socket = "unix:///tmp/pump.sock" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/pump -config pump.toml - ``` - -#### 使用 Binary 部署 Drainer - -1. Drainer 命令行参数说明 - - ``` - Usage of drainer: - -L string - 日志输出信息等级设置: debug, info, warn, error, fatal (默认 "info") - -V - 打印版本信息 - -addr string - drainer 提供服务的地址(默认 "127.0.0.1:8249") - -c int - 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - -config string - 配置文件路径, drainer 会首先读取配置文件的配置 - 如果对应的配置在命令行参数里面也存在，drainer 就会使用命令行参数的配置来覆盖配置文件里面的 - -data-dir string - drainer 数据存储位置路径 (默认 "data.drainer") - -dest-db-type string - drainer 下游服务类型 (默认为 mysql) - -detect-interval int - 向 pd 查询在线 Pump 的时间间隔 (默认 10，单位 秒) - -disable-dispatch - 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - -gen-savepoint - 如果设置为 true, 则只生成 drainer 的 savepoint meta 文件, 可以配合 Mydumper 使用 - -ignore-schemas string - db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - -log-file string - log 文件路径 - -log-rotate string - log 文件切换频率, hour/day - -metrics-addr string - Prometheus Pushgateway 地址，不设置则禁止上报监控信息 - -metrics-interval int - 监控信息上报频率 (默认 15，单位 秒) - -pd-urls string - pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - -txn-batch int - 输出到下游数据库一个事务的 sql 数量 (default 1) - ``` - -2. Drainer 配置文件 - - ```toml - # drainer Configuration. - - # drainer 提供服务的地址(默认 "127.0.0.1:8249") - addr = "127.0.0.1:8249" - - # 向 pd 查询在线 pump 的时间间隔 (默认 10，单位 秒) - detect-interval = 10 - - # drainer 数据存储位置路径 (默认 "data.drainer") - data-dir = "data.drainer" - - # pd 集群节点的地址 (默认 "http://127.0.0.1:2379") - pd-urls = "http://127.0.0.1:2379" - - # log 文件路径 - log-file = "drainer.log" - - # Syncer Configuration. - [syncer] - - ## db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test"), - ## 不支持对 ignore schemas 的 table 进行 rename DDL 操作 - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - - # 输出到下游数据库一个事务的 sql 数量 (default 1) - txn-batch = 1 - - # 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) - worker-count = 1 - - # 是否禁用拆分单个 binlog 的 sqls 的功能，如果设置为 true，则按照每个 binlog - # 顺序依次还原成单个事务进行同步( 下游服务类型为 mysql, 该项设置为 False ) - disable-dispatch = false - - # drainer 下游服务类型 (默认为 mysql) - # 参数有效值为 "mysql", "pb" - db-type = "mysql" - - # replicate-do-db priority over replicate-do-table if have same db name - # and we support regex expression , - # 以 '~' 开始声明使用正则表达式 - - #replicate-do-db = ["~^b.*","s1"] - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "log" - - #[[syncer.replicate-do-table]] - #db-name ="test" - #tbl-name = "~^a.*" - - # db-type 设置为 mysql 时，下游数据库服务器参数 - [syncer.to] - host = "127.0.0.1" - user = "root" - password = "" - port = 3306 - - # db-type 设置为 pb 时,存放 binlog 文件的目录 - # [syncer.to] - # dir = "data.drainer" - ``` - -3. 启动示例 - - {{< copyable "shell-regular" >}} - - ```bash - ./bin/drainer -config drainer.toml - ``` - -## TiDB Binlog Local 监控 - -这部分主要对 TiDB Binlog 的状态、性能做监控，通过 Prometheus + Grafana 展现 metrics 数据， - -### pump/drainer 配置 - -使用 ansible 部署的 pump 服务，已经在启动参数设置 metrics 。 - -drainer 启动时可以设置 `--metrics-addr` 和 `--metrics-interval` 两个参数，其中 metrics-addr 设为 Push Gateway 的地址，metrics-interval 为 push 的频率，单位为秒，默认值为15 - -### Grafana 配置 - -+ 进入 Grafana Web 界面（默认地址: `http://localhost:3000`，默认账号: admin 密码: admin） - - 点击 Grafana Logo -> 点击 Data Sources -> 点击 Add data source -> 填写 data source 信息 ( 注: Type 选 Prometheus，Url 为 Prometheus 地址，根据实际情况 添加/填写 ） - -+ 导入 dashboard 配置文件 - - 点击 Grafana Logo -> 点击 Dashboards -> 点击 Import -> 选择需要的 [dashboard 配置文件](https://github.com/pingcap/tidb-ansible/blob/master/scripts/binlog.json)上传 -> 选择对应的 data source diff --git a/v3.1/reference/tidb-binlog/troubleshoot/binlog.md b/v3.1/reference/tidb-binlog/troubleshoot/binlog.md deleted file mode 100644 index e4d928c55c45..000000000000 --- a/v3.1/reference/tidb-binlog/troubleshoot/binlog.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: TiDB Binlog 故障诊断 -category: reference -aliases: ['/docs-cn/v3.1/how-to/troubleshoot/tidb-binlog/'] ---- - -# TiDB Binlog 故障诊断 - -本文总结了在 TiDB Binlog 的使用过程中遇到问题的诊断流程，并指引用户通过监控、状态、日志等信息查找相应的解决方案。 - -如果你在使用 TiDB Binlog 时出现了异常，请尝试以下方式排查问题： - -1. 查看各个监控指标是否异常，参见[TiDB Binlog 集群监控](/v3.1/reference/tidb-binlog/monitor.md)。 - -2. 使用 [binlogctl 工具](/v3.1/reference/tidb-binlog/maintain.md#binlogctl-工具)查看各个 Pump、Drainer 的状态是否有异常。 - -3. 查看 Pump、Drainer 日志中是否有 `ERROR`、`WARN`，并根据详细的日志信息初步判断问题原因。 - -通过以上方式定位到问题后，在 [FAQ](/v3.1/reference/tidb-binlog/faq.md) 以及 [常见错误及修复](/v3.1/reference/tidb-binlog/troubleshoot/error-handling.md) 中查找解决方案，如果没有查找到解决方案或者提供的解决方案无法解决问题，请提交 [issue](https://github.com/pingcap/tidb-binlog/issues) 或者联系相关技术支持人员。 diff --git a/v3.1/reference/tidb-binlog/troubleshoot/error-handling.md b/v3.1/reference/tidb-binlog/troubleshoot/error-handling.md deleted file mode 100644 index 3b2b307706fa..000000000000 --- a/v3.1/reference/tidb-binlog/troubleshoot/error-handling.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: TiDB Binlog 常见错误修复 -category: reference ---- - -# TiDB Binlog 常见错误修复 - -本文档介绍 TiDB Binlog 中常见的错误以及修复方法。 - -## Drainer 同步数据到 Kafka 时报错 "kafka server: Message was too large, server rejected it to avoid allocation error" - -报错原因：如果在 TiDB 中执行了大事务，则生成的 binlog 数据会比较大，可能超过了 Kafka 的消息大小限制。 - -解决方法：需要调整 Kafka 的配置参数，如下所示。 - -``` -message.max.bytes=1073741824 -replica.fetch.max.bytes=1073741824 -fetch.message.max.bytes=1073741824 -``` - -## Pump 报错 "no space left on device" - -报错原因：本地磁盘空间不足，Pump 无法正常写 binlog 数据。 - -解决方法：需要清理磁盘空间，然后重启 Pump。 - -## Pump 启动时报错 "fail to notify all living drainer" - -报错原因：Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。 - -解决方法：可以使用 [binlogctl 工具](/v3.1/reference/tidb-binlog/maintain.md#binlogctl-工具)查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。 diff --git a/v3.1/reference/tidb-binlog/upgrade.md b/v3.1/reference/tidb-binlog/upgrade.md deleted file mode 100644 index 389e136fe6b0..000000000000 --- a/v3.1/reference/tidb-binlog/upgrade.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: TiDB Binlog 版本升级方法 -category: reference -aliases: ['/docs-cn/v3.1/how-to/upgrade/tidb-binlog/','/docs-cn/v3.1/reference/tools/tidb-binlog/upgrade/'] ---- - -# TiDB Binlog 版本升级方法 - -如未特别指明，文中出现的 TiDB Binlog 均指最新的 [Cluster](/v3.1/reference/tidb-binlog/overview.md) 版本。 - -本文会分 Ansible 部署和手动部署两种情况介绍 TiDB Binlog 版本升级的方法，另外有一小节介绍如何从更早的不兼容版本（Kafka/Local 版本）升级到最新版本。 - -## Ansible 部署 - -本节适用于使用 [TiDB Ansible Playbook](https://github.com/pingcap/tidb-ansible) 部署的情况。 - -### 升级 Pump - -1. 将新版本的二进制文件 `pump` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook rolling_update.yml --tags=pump` 命令来滚动升级 Pump - -### 升级 Drainer - -1. 将新版本的二进制文件 `drainer` 复制到 `{{ resources_dir }}/bin` 目录中 -2. 执行 `ansible-playbook stop_drainer.yml --tags=drainer` 命令 -3. 执行 `ansible-playbook start_drainer.yml --tags=drainer` 命令 - -## 手动部署 - -### 升级 Pump - -对集群里的每个 Pump 逐一升级，确保集群中总有 Pump 可以接收 TiDB 发来的 Binlog。 - -1. 用新版本的 `pump` 替换原来的文件 -2. 重启 Pump 进程 - -### 升级 Drainer - -1. 用新版本的 `drainer` 替换原来的文件 -2. 重启 Drainer 进程 - -## 从 Kafka/Local 版本升级到 Cluster 版本 - -新版本的 TiDB（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）不兼容 [Kafka 版本](/v3.1/reference/tidb-binlog/tidb-binlog-kafka.md)以及 [Local 版本](/v3.1/reference/tidb-binlog/tidb-binlog-local.md)的 TiDB Binlog，集群升级到新版本后只能使用 Cluster 版本的 TiDB Binlog。如果在升级前已经使用了 Kafka／Local 版本的 TiDB Binlog，必须将其升级到 Cluster 版本。 - -TiDB Binlog 版本与 TiDB 版本的对应关系如下： - -| TiDB Binlog 版本 | TiDB 版本 | 说明 | -|---|---|---| -| Local | TiDB 1.0 及更低版本 || -| Kafka | TiDB 1.0 ~ TiDB 2.1 RC5 | TiDB 1.0 支持 local 版本和 Kafka 版本的 TiDB Binlog。 | -| Cluster | TiDB v2.0.8-binlog，TiDB 2.1 RC5 及更高版本 | TiDB v2.0.8-binlog 是一个支持 Cluster 版本 TiDB Binlog 的 2.0 特殊版本。 | - -### 升级流程 - -> **注意：** -> -> 如果能接受重新导全量数据，则可以直接废弃老版本，按 [TiDB Binlog 集群部署](/v3.1/reference/tidb-binlog/deploy.md)中的步骤重新部署。 - -如果想从原来的 checkpoint 继续同步，使用以下升级流程： - -1. 部署新版本 Pump。 -2. 暂停 TiDB 集群业务。 -3. 更新 TiDB 以及配置，写 Binlog 到新的 Pump Cluster。 -4. TiDB 集群重新接入业务。 -5. 确认老版本的 Drainer 已经将老版本的 Pump 的数据完全同步到下游。 - - 查询 Drainer 的 `status` 接口，示例命令如下： - - {{< copyable "shell-regular" >}} - - ```bash - curl 'http://172.16.10.49:8249/status' - ``` - - ``` - {"PumpPos":{"172.16.10.49:8250":{"offset":32686}},"Synced": true ,"DepositWindow":{"Upper":398907800202772481,"Lower":398907799455662081}} - ``` - - 如果返回的 `Synced` 为 true，则可以认为 Binlog 数据已经全部同步到了下游。 - -6. 启动新版本 Drainer； -7. 下线老版本的 Pump、Drainer 以及依赖的 Kafka 和 ZookeSeper。 diff --git a/v3.1/reference/tispark.md b/v3.1/reference/tispark.md deleted file mode 100644 index f358fc3269a5..000000000000 --- a/v3.1/reference/tispark.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: TiSpark 用户指南 -category: reference ---- - -# TiSpark 用户指南 - -TiSpark 是 PingCAP 为解决用户复杂 OLAP 需求而推出的产品。它借助 Spark 平台，同时融合 TiKV 分布式集群的优势，和 TiDB 一起为用户一站式解决 HTAP (Hybrid Transactional/Analytical Processing) 的需求。TiSpark 依赖于 TiKV 集群和 Placement Driver (PD)，也需要你搭建一个 Spark 集群。 - -本文简单介绍如何部署和使用 TiSpark。本文假设你对 Spark 有基本认知。你可以参阅 [Apache Spark 官网](https://spark.apache.org/docs/latest/index.html) 了解 Spark 的相关信息。 - -## 概述 - -TiSpark 是将 Spark SQL 直接运行在分布式存储引擎 TiKV 上的 OLAP 解决方案。其架构图如下： - -![TiSpark Architecture](/media/tispark-architecture.png) - -+ TiSpark 深度整合了 Spark Catalyst 引擎, 可以对计算提供精确的控制，使 Spark 能够高效的读取 TiKV 中的数据，提供索引支持以实现高速的点查。 -+ 通过多种计算下推减少 Spark SQL 需要处理的数据大小，以加速查询；利用 TiDB 的内建的统计信息选择更优的查询计划。 -+ 从数据集群的角度看，TiSpark + TiDB 可以让用户无需进行脆弱和难以维护的 ETL，直接在同一个平台进行事务和分析两种工作，简化了系统架构和运维。 -+ 除此之外，用户借助 TiSpark 项目可以在 TiDB 上使用 Spark 生态圈提供的多种工具进行数据处理。例如，使用 TiSpark 进行数据分析和 ETL；使用 TiKV 作为机器学习的数据源；借助调度系统产生定时报表等等。 - -## 环境准备 - -现有 TiSpark 2.x 版本支持 Spark 2.3.x 和 Spark 2.4.x。如果你希望使用 Spark 2.1.x 版本，需使用 TiSpark 1.x。 - -TiSpark 需要 JDK 1.8+ 以及 Scala 2.11（Spark2.0+ 默认 Scala 版本）。 - -TiSpark 可以在 YARN，Mesos，Standalone 等任意 Spark 模式下运行。 - -## 推荐配置 - -本部分描述了 TiKV 与 TiSpark 集群分开部署、Spark 与 TiSpark 集群独立部署，以及TiSpark 与 TiKV 集群混合部署的建议配置。 - -### TiKV 与 TiSpark 集群分开部署的配置 - -对于 TiKV 与 TiSpark 分开部署的场景，可以参考如下建议配置： - -+ 硬件配置建议 - - 普通场景可以参考 [TiDB 和 TiKV 硬件配置建议](/v3.1/how-to/deploy/hardware-recommendations.md)，但是如果是偏重分析的场景，可以将 TiKV 节点增加到至少 64G 内存。 - -### Spark 与 TiSpark 集群独立部署的配置 - -关于 Spark 的详细硬件推荐配置请参考[官网](https://spark.apache.org/docs/latest/hardware-provisioning.html)，如下是 TiSpark 所需环境的简单描述： - -Spark 推荐 32G 内存以上的配额。请在配置中预留 25% 的内存给操作系统。 - -Spark 推荐每台计算节点配备 CPU 累计 8 到 16 核以上。你可以初始设定分配所有 CPU 核给 Spark。 - -Spark 的具体配置方式也请参考[官方说明](https://spark.apache.org/docs/latest/spark-standalone.html)。以下为根据 `spark-env.sh` 配置的范例： - -{{< copyable "" >}} - -``` -SPARK_EXECUTOR_CORES: 5 -SPARK_EXECUTOR_MEMORY: 10g -SPARK_WORKER_CORES: 5 -SPARK_WORKER_MEMORY: 10g -``` - -在 `spark-defaults.conf` 中，增加如下配置： - -{{< copyable "" >}} - -``` -spark.tispark.pd.addresses $your_pd_servers -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -`your_pd_servers` 是用逗号分隔的 PD 地址，每个地址使用 `地址:端口` 的格式。 - -例如你有一组 PD 在`10.16.20.1`，`10.16.20.2`，`10.16.20.3`，那么 PD 配置格式是`10.16.20.1:2379,10.16.20.2:2379,10.16.20.3:2379`。 - -### TiSpark 与 TiKV 集群混合部署的配置 - -对于 TiKV 与 TiSpark 混合部署的场景，需在原有 TiKV 预留资源之外累加 Spark 所需部分，并分配 25% 的内存作为系统本身占用。 - -## 部署 TiSpark - -TiSpark 的 jar 包可以在 [TiSpark Releases 页面](https://github.com/pingcap/tispark/releases)下载对应版本的 jar 包并拷贝到合适的目录。 - -### 已有 Spark 集群的部署方式 - -如果在已有 Spark 集群上运行 TiSpark，无需重启集群。可以使用 Spark 的 `--jars` 参数将 TiSpark 作为依赖引入： - -{{< copyable "shell-regular" >}} - -```shell -spark-shell --jars $TISPARK_FOLDER/tispark-${name_with_version}.jar -``` - -### 没有 Spark 集群的部署方式 - -如果没有使用中的 Spark 集群，推荐使用 Saprk Standalone 方式部署。这里简单介绍下 Standalone 部署方式。如果遇到问题，可以去官网寻求[帮助](https://spark.apache.org/docs/latest/spark-standalone.html)；也欢迎在我们的 GitHub 上提 [issue](https://github.com/pingcap/tispark/issues/new)。 - -#### 下载安装包并安装 - -你可以在 [Apache Spark™ 下载页面](https://spark.apache.org/downloads.html)下载 Apache Spark。 - -对于 Standalone 模式且无需 Hadoop 支持，则选择 Spark 2.3.x 或者 Spark 2.4.x 且带有 Hadoop 依赖的 Pre-build with Apache Hadoop 2.x 任意版本。如有需要配合使用的 Hadoop 集群，则选择对应的 Hadoop 版本号。你也可以选择从源代码[自行构建](https://spark.apache.org/docs/latest/building-spark.html)以配合官方 Hadoop 2.x 之前的版本。 - -如果你已经有了 Spark 二进制文件，并且当前 PATH 为 SPARKPATH，需将 TiSpark jar 包拷贝到 `${SPARKPATH}/jars` 目录下。 - -#### 启动 Master - -在选中的 Spark Master 节点执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -cd $SPARKPATH -``` - -{{< copyable "shell-regular" >}} - -```bash -./sbin/start-master.sh -``` - -在这步完成以后，屏幕上会打印出一个 log 文件。检查 log 文件确认 Spark-Master 是否启动成功。你可以打开 查看集群信息（如果你没有改动 Spark-Master 默认 Port Numebr）。在启动 Spark-Slave 的时候，也可以通过这个面板来确认 Slave 是否已经加入集群。 - -#### 启动 Slave - -类似地，可以用如下命令启动 Spark-Slave 节点： - -{{< copyable "shell-regular" >}} - -```bash -./sbin/start-slave.sh spark://spark-master-hostname:7077 -``` - -命令返回以后，即可通过刚才的面板查看这个 Slave 是否已经正确地加入了 Spark 集群。在所有 Slave 节点重复刚才的命令。确认所有的 Slave 都可以正确连接 Master，这样你就拥有了一个 Standalone 模式的 Spark 集群。 - -#### Spark SQL shell 和 JDBC 服务器 - -当前版本的 TiSpark 可以直接使用 `spark-sql` 和 Spark 的 ThriftServer JDBC 服务器。 - -## 一个使用范例 - -假设你已经按照上述步骤成功启动了 TiSpark 集群，下面简单介绍如何使用 Spark SQL 来做 OLAP 分析。这里我们用名为 tpch 数据库中的 lineitem 表作为范例。 - -假设你的 PD 节点位于 192.168.1.100，端口为 2379，在 `$SPARK_HOME/conf/spark-defaults.conf` 加入： - -{{< copyable "" >}} - -``` -spark.tispark.pd.addresses 192.168.1.100:2379 -``` - -{{< copyable "" >}} - -``` -spark.sql.extensions org.apache.spark.sql.TiExtensions -``` - -然后在 Spark-Shell 里像原生 Spark 一样输入下面的命令： - -{{< copyable "" >}} - -```scala -spark.sql("use tpch") -``` - -{{< copyable "" >}} - -```scala -spark.sql("select count(*) from lineitem").show -``` - -结果为： - -``` -+-------------+ -| Count (1) | -+-------------+ -| 600000000 | -+-------------+ -``` - -Spark SQL 交互 Shell 和原生 Spark 一致： - -{{< copyable "" >}} - -```shell -spark-sql> use tpch; -``` - -``` -Time taken: 0.015 seconds -``` - -{{< copyable "" >}} - -```shell -spark-sql> select count(*) from lineitem; -``` - -``` -2000 -Time taken: 0.673 seconds, Fetched 1 row(s) -``` - -SQuirreLSQL 和 hive-beeline 可以使用 JDBC 连接 Thrift 服务器。 -例如，使用 beeline 连接： - -{{< copyable "shell-regular" >}} - -```shell -./beeline -``` - -``` -Beeline version 1.2.2 by Apache Hive -``` - -{{< copyable "" >}} - -```shell -beeline> !connect jdbc:hive2://localhost:10000 -``` - -{{< copyable "" >}} - -```shell -1: jdbc:hive2://localhost:10000> use testdb; -``` - -``` -+---------+--+ -| Result | -+---------+--+ -+---------+--+ -No rows selected (0.013 seconds) -``` - -{{< copyable "sql" >}} - -```sql -select count(*) from account; -``` - -``` -+-----------+--+ -| count(1) | -+-----------+--+ -| 1000000 | -+-----------+--+ -1 row selected (1.97 seconds) -``` - -## 和 Hive 一起使用 TiSpark - -TiSpark 可以和 Hive 混合使用。 -在启动 Spark 之前，需要添加 HADOOP_CONF_DIR 环境变量指向 Hadoop 配置目录并且将 `hive-site.xml` 拷贝到 `$SPARK_HOME/conf` 目录下。 - -``` -val tisparkDF = spark.sql("select * from tispark_table").toDF -tisparkDF.write.saveAsTable("hive_table") // save table to hive -spark.sql("select * from hive_table a, tispark_table b where a.col1 = b.col1").show // join table across Hive and Tispark -``` - -## 通过 JDBC 将 DataFrame 写入 TiDB - -暂时 TiSpark 不支持直接将数据写入 TiDB 集群，但可以使用 Spark 原生的 JDBC 支持进行写入： - -```scala -import org.apache.spark.sql.execution.datasources.jdbc.JDBCOptions - -val customer = spark.sql("select * from customer limit 100000") -// you might repartition source to make it balance across nodes -// and increase concurrency -val df = customer.repartition(32) -df.write -.mode(saveMode = "append") -.format("jdbc") -.option("driver", "com.mysql.jdbc.Driver") - // replace host and port as your and be sure to use rewrite batch -.option("url", "jdbc:mysql://127.0.0.1:4000/test?rewriteBatchedStatements=true") -.option("useSSL", "false") -// As tested, 150 is good practice -.option(JDBCOptions.JDBC_BATCH_INSERT_SIZE, 150) -.option("dbtable", s"cust_test_select") // database name and table name here -.option("isolationLevel", "NONE") // recommended to set isolationLevel to NONE if you have a large DF to load. -.option("user", "root") // TiDB user here -.save() -``` - -推荐将 `isolationLevel` 设置为 `NONE`，否则单一大事务有可能造成 TiDB 服务器内存溢出。 - -## 统计信息 - -TiSpark 可以使用 TiDB 的统计信息： - -1. 选择代价最低的索引或扫表访问 -2. 估算数据大小以决定是否进行广播优化 - -如果希望使用统计信息支持，需要确保所涉及的表已经被分析。请阅读[这份文档](https://pingcap.com/docs-cn/v3.1/reference/performance/statistics/)了解如何进行表分析。 - -从 TiSpark 2.0 开始，统计信息将会默认被读取。 - -统计信息将在 Spark Driver 进行缓存，请确定 Driver 内存足够缓存统计信息。 -可以在`spark-defaults.conf`中开启或关闭统计信息读取： - -| Property Name | Default | Description -| -------- | -----: | :----: | -| spark.tispark.statistics.auto_load | true | 是否默认进行统计信息读取 | - -## TiSpark FAQ - -- Q. 是独立部署还是和现有 Spark／Hadoop 集群共用资源？ - - A. 可以利用现有 Spark 集群无需单独部署，但是如果现有集群繁忙，TiSpark 将无法达到理想速度。 - -- Q. 是否可以和 TiKV 混合部署？ - - A. 如果 TiDB 以及 TiKV 负载较高且运行关键的线上任务，请考虑单独部署 TiSpark；并且考虑使用不同的网卡保证 OLTP 的网络资源不被侵占而影响线上业务。如果线上业务要求不高或者机器负载不大，可以考虑与 TiKV 混合部署。 - -- Q. Spark 执行中报 warning：WARN ObjectStore:568 - Failed to get database - - A. Warning 忽略即可，原因是 Spark 找不到对应的 hive 库，因为这个库是在 TIKV 中，而不是在 hive 中。可以考虑调整 [log4j 日志](https://github.com/pingcap/tidb-docker-compose/blob/master/tispark/conf/log4j.properties#L43)，将该参数添加到 spark 下 conf 里 log4j 文件(如果后缀是 template 那先 mv 成后缀 properties)。 - -- Q. Spark 执行中报 java.sql.BatchUpdateException: Data Truncated - - A. 写入的数据长度超过了数据库定义的数据类型的长度，可以确认 target table 的字段长度，进行调整。 - -- Q. TiSpark 任务是否默认读取 Hive 的元数据？ - - A. TiSpark 通过读取 hive-site 里的 meta 来搜寻 hive 的库。如果搜寻不到，就通过读取 tidb meta 搜寻 tidb 库。如果不需要该行为，可不在 hive site 中配置 hive 的 meta。 - -- Q. TiSpark 执行 Spark 任务时报：Error：java.io.InvalidClassException: com.pingcap.tikv.region.TiRegion; local class incompatible: stream classdesc serialVersionUID ... - - A. 该报错日志中显示 serialVersionUID 冲突，说明存在不同版本的 class 和 TiRegion。因为 TiRegion 是 TiSpark 独有的，所以可能存在多个版本的 TiSpark 包。要解决该报错，请确保集群中各节点的 TiSpark 依赖包版本一致。 diff --git a/v3.1/reference/tools/br/br.md b/v3.1/reference/tools/br/br.md deleted file mode 100644 index 4513c0a45639..000000000000 --- a/v3.1/reference/tools/br/br.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -title: 使用 BR 进行备份与恢复 -summary: 了解如何使用 BR 工具进行集群数据备份和恢复。 -category: how-to -aliases: ['/docs-cn/v3.1/how-to/maintain/backup-and-restore/br/'] ---- - -# 使用 BR 进行备份与恢复 - -Backup & Restore（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`mydumper`/`loader`](/v3.1/how-to/maintain/backup-and-restore/mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。 - -## 使用限制 - -- BR 只支持 TiDB v3.1 及以上版本。 -- 目前只支持在全新的集群上执行恢复操作。 -- BR 备份最好串行执行，否则不同备份任务之间会相互影响。 - -## 推荐部署配置 - -- 推荐 BR 部署在 PD 节点上。 -- 推荐使用一块高性能 SSD 网盘，挂载到 BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。 - -## 下载 Binary - -详见[下载链接](/v3.1/reference/tools/download.md#快速备份和恢复br)。 - -## 工作原理 - -BR 是分布式备份恢复的工具，它将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。 - -### 备份原理 - -BR 执行备份操作时，会先从 PD 获取到以下信息： - -- 当前的 TS 作为备份快照的时间点 -- 当前集群的 TiKV 节点信息 - -然后 BR 根据这些信息，在内部启动一个 TiDB 实例，获取对应 TS 的数据库或表信息，同时过滤掉系统库 (`information_schema`，`performance_schema`，`mysql`)。 - -此时根据备份子命令，会有两种备份逻辑： - -- 全量备份：BR 遍历全部库表，并且根据每一张表构建需要备份的 KV Range -- 单表备份：BR 根据该表构建需要备份的 KV Range - -最后，BR 将需要备份的 KV Range 收集后，构造完整的备份请求分发给集群内的 TiKV 节点。 - -该请求的主要结构如下： - -``` -BackupRequest{ - ClusterId, // 集群 ID - StartKey, // 备份起始点，startKey 会被备份 - EndKey, // 备份结束点，endKey 不会被备份 - EndVersion, // 备份快照时间点 - StorageBackend, // 备份文件存储地址 - RateLimit, // 备份速度 (MB/s) - Concurrency, // 执行备份操作的线程数（默认为 4） -} -``` - -TiKV 节点收到备份请求后，会遍历节点上所有的 Region Leader，找到和请求中 KV Range 有重叠范围的 Region，将该范围下的部分或者全部数据进行备份，在备份路径下生成对应的 SST 文件。 - -TiKV 节点在备份完对应 Region Leader 的数据后将元信息返回给 BR。BR 将这些元信息收集并存储进 `backupmeta` 文件中，等待恢复时使用。 - -如果执行命令时开启了 checksum，那么 BR 在最后会对备份的每一张表计算 checksum 用于校验。 - -#### 备份文件类型 - -备份路径下会生成以下两种类型文件： - -- SST 文件：存储 TiKV 备份下来的数据信息 -- `backupmeta` 文件：存储本次备份的元信息，包括备份文件数、备份文件的 Key 区间、备份文件大小和备份文件 Hash (sha256) 值 - -#### SST 文件命名格式 - -SST 文件以 `storeID_regionID_regionEpoch_keyHash_cf` 的格式命名。格式名的解释如下： - -- storeID：TiKV 节点编号 -- regionID：Region 编号 -- regionEpoch：Region 版本号 -- keyHash：Range startKey 的 Hash (sha256) 值，确保唯一性 -- cf：RocksDB 的 ColumnFamily（默认为 `default` 或 `write`） - -### 恢复原理 - -BR 执行恢复操作时，会按顺序执行以下任务： - -1. 解析备份路径下的 backupMeta 文件，根据解析出来的库表信息，在内部启动一个 TiDB 实例在新集群创建对应的库表。 - -2. 把解析出来的 SST 文件，根据表进行聚合。 - -3. 根据 SST 文件的 Key Range 进行预切分 Region，使得每个 Region 至少对应一个 SST 文件。 - -4. 遍历要恢复的每一张表，以及这个表对应的 SST 文件。 - -5. 找到该文件对应的 Region，发送下载文件的请求到对应的 TiKV 节点，并在下载成功后，发送加载请求。 - -TiKV 收到加载 SST 文件的请求后，利用 Raft 机制保证加载 SST 数据的强一致性。在加载成功后，下载下来的 SST 文件会被异步删除。 - -在执行完恢复操作后，BR 会对恢复后的数据进行 checksum 计算，用于和备份下来的数据进行对比。 - -![br-arch](/media/br-arch.png) - -## BR 命令行描述 - -一条 `br` 命令是由子命令、选项和参数组成的。子命令即不带 `-` 或者 `--` 的字符。选项即以 `-` 或者 `--` 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。 - -以下是一条完整的 `br` 命令行： - -`br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"` - -命令行各部分的解释如下： - -* `backup`：`br` 的子命令 -* `full`：`backup` 的子命令 -* `-s` 或 `--storage`：备份保存的路径 -* `"local:///tmp/backup"`：`-s` 的参数，保存的路径为本地磁盘的 `/tmp/backup` -* `--pd`：PD 服务地址 -* `"${PDIP}:2379"`：`--pd` 的参数 - -### 命令和子命令 - -BR 由多层命令组成。目前，BR 包含 `backup`、`restore` 和 `version` 三个子命令: - -* `br backup` 用于备份 TiDB 集群 -* `br restore` 用于恢复 TiDB 集群 -* `br version` 用于查看 BR 工具版本信息 - -以上三个子命令可能还包含这些子命令： - -* `full`：可用于备份或恢复全部数据。 -* `db`：可用于备份或恢复集群中的指定数据库。 -* `table`：可用于备份或恢复集群指定数据库中的单张表。 - -### 常用选项 - -* `--pd`：用于连接的选项，表示 PD 服务地址，例如 `"${PDIP}:2379"`。 -* `-h`/`--help`：获取所有命令和子命令的使用帮助。例如 `br backup --help`。 -* `--ca`：指定 PEM 格式的受信任 CA 的证书文件路径。 -* `--cert`：指定 PEM 格式的 SSL 证书文件路径。 -* `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。 -* `--status-addr`：BR 向 Prometheus 提供统计数据的监听地址。 - -## 备份集群数据 - -使用 `br backup` 命令来备份集群数据。可选择添加 `full` 或 `table` 子命令来指定备份的范围：全部集群数据或单张表的数据。 - -如果备份时间可能超过设定的 [`tikv_gc_life_time`](/v3.1/reference/garbage-collection/configuration.md#tikv_gc_life_time)（默认 `10m0s`），则需要将该参数调大。 - -例如，将 `tikv_gc_life_time` 调整为 `720h`： - -{{< copyable "sql" >}} - -```sql -mysql -h${TiDBIP} -P4000 -u${TIDB_USER} ${password_str} -Nse \ - "update mysql.tidb set variable_value='720h' where variable_name='tikv_gc_life_time'"; -``` - -### 备份全部集群数据 - -要备份全部集群数据，可使用 `br backup full` 命令。该命令的使用帮助可以通过 `br backup full -h` 或 `br backup full --help` 来获取。 - -用例：将所有集群数据备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backupfull.log -``` - -以上命令中，`--ratelimit` 和 `--concurrency` 选项限制了**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）和并发数上限。`--log-file` 选项指定把 BR 的 log 写到 `backupfull.log` 文件中。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。进度条效果如下： - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backupfull.log -Full Backup <---------/................................................> 17.12%. -``` - -### 备份单个数据库的数据 - -要备份集群中指定单个数据库的数据，可使用 `br backup db` 命令。同样可通过 `br backup db -h` 或 `br backup db --help` 来获取子命令 `db` 的使用帮助。 - -用例：将数据库 `test` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup db \ - --pd "${PDIP}:2379" \ - --db test \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backuptable.log -``` - -`db` 子命令的选项为 `--db`，用来指定数据库名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 - -### 备份单张表的数据 - -要备份集群中指定单张表的数据，可使用 `br backup table` 命令。同样可通过 `br backup table -h` 或 `br backup table --help` 来获取子命令 `table` 的使用帮助。 - -用例：将表 `test.usertable` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup table \ - --pd "${PDIP}:2379" \ - --db test \ - --table usertable \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --concurrency 4 \ - --log-file backuptable.log -``` - -`table` 子命令有 `--db` 和 `--table` 两个选项，分别用来指定数据库名和表名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 - -## 恢复集群数据 - -使用 `br restore` 命令来恢复备份数据。可选择添加 `full`、`db` 或 `table` 子命令来指定恢复操作的范围：全部集群数据、某个数据库或某张数据表。 - -> **注意：** -> -> 如果备份的集群没有网络存储，在恢复前需要将所有备份的 SST 文件拷贝到各个 TiKV 节点上 `--storage` 指定的目录下。 - -### 恢复全部备份数据 - -要将全部备份数据恢复到集群中来，可使用 `br restore full` 命令。该命令的使用帮助可以通过 `br restore full -h` 或 `br restore full --help` 来获取。 - -用例：将 `/tmp/backup` 路径中的全部备份数据恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --concurrency 128 \ - --log-file restorefull.log -``` - -`--concurrency` 指定了该恢复任务内部的子任务的并发数。`--log-file` 选项指定把 BR 的 log 写到 `restorefull.log` 文件中。 - -恢复期间还有进度条会在终端中显示，当进度条前进到 100% 时，说明恢复已完成。在完成恢复后，BR 为了确保数据安全性，还会校验恢复数据。进度条效果如下： - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -Full Restore <---------/...............................................> 17.12%. -``` - -### 恢复单个数据库的数据 - -要将备份数据中的某个数据库恢复到集群中，可以使用 `br restore db` 命令。该命令的使用帮助可以通过 `br restore db -h` 或 `br restore db --help` 来获取。 - -用例：将 `/tmp/backup` 路径中备份数据中的某个数据库恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore db \ - --pd "${PDIP}:2379" \ - --db "test" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -以上命令中 `--db` 选项指定了需要恢复的数据库名字。其余选项的含义与[恢复全部备份数据](#恢复全部备份数据)相同。 - -### 恢复单张表的数据 - -要将备份数据中的某张数据表恢复到集群中，可以使用 `br restore table` 命令。该命令的使用帮助可通过 `br restore table -h` 或 `br restore table --help` 来获取。 - -用例：将 `/tmp/backup` 路径下的备份数据中的某个数据表恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore table \ - --pd "${PDIP}:2379" \ - --db "test" \ - --table "usertable" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -以上命令中 `--table` 选项指定了需要恢复的表名。其余选项的含义与[恢复某个数据库](#恢复某个数据库)相同。 - -## 最佳实践 - -- 推荐在 `-s` 指定的备份路径上挂载一个共享存储，例如 NFS。这样能方便收集和管理备份文件。 -- 在使用共享存储时，推荐使用高吞吐的存储硬件，因为存储的吞吐会限制备份或恢复的速度。 -- 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。 - -更多最佳实践内容，参见 [BR 备份与恢复场景示例](/v3.1/reference/tools/br/use-cases.md)。 - -## 备份和恢复示例 - -本示例展示如何对已有的集群数据进行备份和恢复操作。可以根据机器性能、配置、数据规模来预估一下备份和恢复的性能。 - -### 数据规模和机器配置 - -假设对 TiKV 集群中的 10 张表进行备份和恢复。每张表有 500 万行数据，数据总量为 35 GB。 - -```sql -MySQL [sbtest]> show tables; -+------------------+ -| Tables_in_sbtest | -+------------------+ -| sbtest1 | -| sbtest10 | -| sbtest2 | -| sbtest3 | -| sbtest4 | -| sbtest5 | -| sbtest6 | -| sbtest7 | -| sbtest8 | -| sbtest9 | -+------------------+ - -MySQL [sbtest]> select count(*) from sbtest1; -+----------+ -| count(*) | -+----------+ -| 5000000 | -+----------+ -1 row in set (1.04 sec) -``` - -表结构如下： - -```sql -CREATE TABLE `sbtest1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `k` int(11) NOT NULL DEFAULT '0', - `c` char(120) NOT NULL DEFAULT '', - `pad` char(60) NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=5138499 -``` - -示例假设有 4 个 TiKV 节点，每个节点配置如下： - -| CPU | 内存 | 磁盘 | 副本数 | -| :--- | :--- | :--- | :--- | -| 16 核 | 32 GB | SSD | 3 | - -### 备份示例 - -- 备份前需确认已将 GC 时间调长，确保备份期间不会因为数据丢失导致中断 -- 备份前需确认 TiDB 集群没有执行 DDL 操作 - -执行以下命令对集群中的全部数据进行备份： - -{{< copyable "shell-regular" >}} - -``` -bin/br backup full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file backup.log -``` - -``` -[INFO] [collector.go:165] ["Full backup summary: total backup ranges: 2, total success: 2, total failed: 0, total take(s): 0.00, total kv: 4, total size(Byte): 133, avg speed(Byte/s): 27293.78"] ["backup total regions"=2] ["backup checksum"=1.640969ms] ["backup fast checksum"=227.885µs] -``` - -### 恢复示例 - -恢复操作前，需确认待恢复的 TiKV 集群是全新的集群。 - -执行以下命令对全部数据进行恢复： - -{{< copyable "shell-regular" >}} - -``` -bin/br restore full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file restore.log -``` - -``` -[INFO] [collector.go:165] ["Full Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 0.26, total kv: 20000, total size(MB): 10.98, avg speed(MB/s): 41.95"] ["restore files"=3] ["restore ranges"=2] ["split region"=0.562369381s] ["restore checksum"=36.072769ms] -``` diff --git a/v3.1/reference/tools/br/use-cases.md b/v3.1/reference/tools/br/use-cases.md deleted file mode 100644 index 4cb272f21bef..000000000000 --- a/v3.1/reference/tools/br/use-cases.md +++ /dev/null @@ -1,415 +0,0 @@ ---- -title: BR 备份与恢复场景示例 -category: reference -aliases: ['/docs-cn/v3.1/how-to/maintain/backup-and-restore/br-best-practices/','/docs-cn/v3.1/reference/tools/br/br-best-practices/'] ---- - -# BR 备份与恢复场景示例 - -[Backup & Restore](/v3.1/reference/tools/br/br.md)（下文简称 BR）一款分布式的快速备份和恢复工具。本文展示了[四种备份和恢复场景](#使用场景)下的 BR 操作过程，以帮助读者达到以下目标： - -* 正确使用网络盘或本地盘进行备份或恢复 -* 通过相关监控指标了解备份或恢复的状态 -* 了解在备份或恢复时如何调优性能 -* 处理备份时可能发生的异常 - -> **注意：** -> -> 使用 BR 时应注意[使用限制](/v3.1/reference/tools/br/br.md#使用限制)。 - -## 目标读者 - -读者需要对 TiDB 和 TiKV 有一定的了解。在阅读本文前，推荐先阅读[使用 BR 进行备份与恢复](/v3.1/reference/tools/br/br.md)。 - -## 环境准备 - -本部分介绍推荐的 TiDB 的部署方式、示例中的集群版本、TiKV 集群硬件信息和集群配置。读者可根据自己的硬件和配置来预估备份恢复的性能。 - -### 部署方式 - -推荐使用 [TiDB Ansible](/v3.1/how-to/deploy/orchestrated/ansible.md) 部署 TiDB 集群，再下载 [TiDB Toolkit](/v3.1/reference/tools/download.md#快速备份和恢复br) 获取 BR 应用。 - -### 集群版本 - -* TiKV: v3.1.0-beta.1 -* PD: v3.1.0-beta.1 -* br: v3.1.0-beta.1 - -### TiKV 集群硬件信息 - -* 操作系统：CentOS Linux release 7.6.1810 (Core) -* CPU：16-Core Common KVM processor -* RAM：32GB -* 硬盘：500G SSD * 2 -* 网卡：10000MB/s - -### 配置 - -BR 可以直接将命令下发到 TiKV 集群来执行备份和恢复，不依赖 TiDB server 组件，因此无需对 TiDB server 进行配置。 - -* TiKV: 默认配置 -* PD : 默认配置 - -## 使用场景 - -本文描述以下四种使用场景： - -* [将单表数据备份到网络盘（推荐）](#将单表数据备份到网络盘推荐) -* [从网络磁盘恢复备份数据（推荐）](#从网络磁盘恢复备份数据推荐) -* [将单表数据备份到本地磁盘](#将单表数据备份到本地磁盘) -* [从本地磁盘恢复备份数据](#从本地磁盘恢复备份数据) - -推荐使用网络盘来进行备份和恢复操作，这样可以省去收集备份数据文件的繁琐步骤。尤其在 TiKV 集群规模较大的情况下，使用网络盘可以大幅提升操作效率。 - -> **注意：** -> -> 在进行备份或恢复操作前，需要先进行备份或恢复的准备工作。 - -### 备份前的准备工作 - -`br backup` 命令的详细使用方法请参考 [BR 命令行描述](/v3.1/reference/tools/br/br.md#br-命令行描述)。 - -1. 运行 `br backup` 命令前，查询 TiDB 集群的 [`tikv_gc_life_time`](/v3.1/reference/garbage-collection/configuration.md#tikv_gc_life_time) 配置项的值，并使用 MySQL 客户端将该项调整至合适的值，确保备份期间不会发生 [Garbage Collection](/v3.1/reference/garbage-collection/overview.md) (GC)。 - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - UPDATE mysql.tidb SET VARIABLE_VALUE = '720h' WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 在备份完成后，将该参数调回原来的值。 - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -### 恢复前的准备工作 - -`br restore` 命令的详细使用方法请参考 [BR 命令行描述](/v3.1/reference/tools/br/br.md#br-命令行描述)。 - -> **注意：** -> -> 运行 `br restore` 前检查新集群确保没有同名的表。 - -### 将单表数据备份到网络盘（推荐） - -使用 `br backup` 命令，将单表数据 `--db batchmark --table order_line` 备份到指定的网络盘路径 `local:///br_data` 下。 - -#### 前置要求 - -* 配置一台高性能 SSD 硬盘主机为 NFS server 存储数据。其他所有 BR 节点和 TiKV 节点为 NFS client，挂载相同的路径（例如 `/br_data`）到 NFS server 上以访问 NFS server。 -* NFS server 和 NFS client 间的数据传输速率至少要达到备份集群的 `TiKV 实例数 * 150MB/s`。否则网络 I/O 有可能成为性能瓶颈。 - -#### 部署拓扑 - -部署拓扑如下图所示： - -![img](/media/br/backup-nfs-deploy.png) - -#### 运行备份 - -备份操作前，在 TiDB 中使用 `admin checksum table order_line` 命令获得备份目标表 `--db batchmark --table order_line` 的统计信息。统计信息示例如下： - -![img](/media/br/total-data.png) - -运行 BR 备份命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br backup table --db batchmark --table order_line -s local:///br_data --pd 172.16.5.198:2379 --log-file backup-nfs.log -``` - -#### 备份过程中的运行指标 - -在 BR 备份过程中，需关注以下监控面版中的运行指标来了解备份的状态。 - -**Backup CPU Utilization**：参与备份的 TiKV 节点（例如 backup-worker 和 backup-endpoint）的 CPU 使用率。 - -![img](/media/br/backup-cpu.png) - -**IO Utilization**：参与备份的 TiKV 节点的 I/O 使用率。 - -![img](/media/br/backup-io.png) - -**BackupSST Generation Throughput**：参与备份的 TiKV 节点生成 backupSST 文件的吞吐。正常时单个 TiKV 节点的吞吐在 150MB/s 左右。 - -![img](/media/br/backup-throughput.png) - -**One Backup Range Duration**：备份一个 range 的操作耗时，包括扫描耗时 (scan KV) 和保存耗时（保存为 backupSST 文件）。 - -![img](/media/br/backup-range-duration.png) - -**One Backup Subtask Duration**： 一次备份任务会被拆分成多个子任务。该监控项显示子任务的耗时。 - -> **注意：** -> -> * 虽然本次任务是备份单表，但因为表中有 3 个索引，所以正常会拆分成 4 个子任务。 -> * 下图中有 13 个点，说明有 9 次 (13-4) 重试。备份过程中可能发生 Region 调度行为，少量重试是正常的。 - -![img](/media/br/backup-subtask-duration.png) - -**Backup Errors**：备份过程中的错误。正常时无错误。即使出现少量错误，备份操作也有重试机制，可能会导致备份时间增加，但不会影响备份的正确性。 - -![img](/media/br/backup-errors.png) - -**Checksum Request Duration**：对备份集群执行 admin checksum 的耗时统计。 - -![img](/media/br/checksum-duration.png) - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从路径下存放的日志中可以获取此次备份的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table backup summary: total backup ranges: 4, total success: 4, total failed: 0, total take(s): 986.43, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 358.09"] ["backup total regions"=7196] ["backup checksum"=6m28.291772955s] ["backup fast checksum"=24.950298ms] -``` - -以上日志信息中包含以下内容： - -* 备份耗时：`total take(s): 986.43` -* 数据大小：`total size(MB): 353227.18` -* 备份吞吐：`avg speed(MB/s): 358.09` -* 校验耗时：`take=6m28.29s` - -通过以上数据可以计算得到单个 TiKV 实例的吞吐为：`avg speed(MB/s)`/`tikv_count` = `89`。 - -#### 性能调优 - -如果 TiKV 的资源使用没有出现明显的瓶颈（例如[备份过程中的运行指标](#备份过程中的运行指标)中的 **Backup CPU Utilization** 最高为 `1500%` 左右，**IO Utilization** 普遍低于 `30%`），可以尝试调大 `--concurrency` 参数以进行性能调优。该方法不适用于存在许多小表的场景。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -bin/br backup table --db batchmark --table order_line -s local:///br_data/ --pd 172.16.5.198:2379 --log-file backup-nfs.log --concurrency 16 -``` - -![img](/media/br/backup-diff.png) - -![img](/media/br/backup-diff2.png) - -性能调优后的结果如下所示（保持数据大小不变）： - -* 备份耗时：`total take(s)` 从 `986.43` 减少到 `535.53` -* 数据大小：`total size(MB): 353227.18` -* 备份吞吐：`avg speed(MB/s)` 从 `358.09` 提升到 `659.59` -* 单个 TiKV 实例的吞吐：`avg speed(MB/s)/tikv_count` 从 `89` 提升到 `164.89` - -### 从网络磁盘恢复备份数据（推荐） - -使用 `br restore` 命令，将一份完整的备份数据恢复到一个离线集群。暂不支持恢复到在线集群。 - -#### 前置要求 - -无 - -#### 部署拓扑 - -部署拓扑如下图所示： - -![img](/media/br/restore-nfs-deploy.png) - -#### 运行恢复 - -运行 `br restore` 命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br restore table --db batchmark --table order_line -s local:///br_data --pd 172.16.5.198:2379 --log-file restore-nfs.log -``` - -#### 恢复过程中的运行指标 - -在 BR 恢复过程中，需关注以下监控面版中的运行指标来了解恢复的状态。 - -**CPU Utilization**：参与恢复的 TiKV 节点 CPU 使用率。 - -![img](/media/br/restore-cpu.png) - -**IO Utilization**：参与恢复的 TiKV 节点的 I/O 使用率。 - -![img](/media/br/restore-io.png) - -**Region** 分布：Region 分布越均匀，说明恢复资源利用越充分。 - -![img](/media/br/restore-region.png) - -**Process SST Duration**：处理 SST 文件的延迟。恢复一张表时时，如果 `tableID` 发生了变化，需要对 `tableID` 进行 `rewrite`，否则会进行 `rename`。通常 `rewrite` 延迟要高于 `rename` 的延迟。 - -![img](/media/br/restore-process-sst.png) - -**DownLoad SST Throughput**：从 External Storage 下载 SST 文件的吞吐。 - -![img](/media/br/restore-download-sst.png) - -**Restore Errors**：恢复过程中的错误。 - -![img](/media/br/restore-errors.png) - -**Checksum Request duration**：对恢复集群执行 admin checksum 的耗时统计，会比备份时的 checksum 延迟高。 - -![img](/media/br/restore-checksum.png) - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从路径下存放的日志中可以获取此次恢复的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 961.37, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 367.42"] ["restore files"=9263] ["restore ranges"=6888] ["split region"=49.049182743s] ["restore checksum"=6m34.879439498s] -``` - -以上日志信息中包含以下内容： - -* 恢复耗时：`total take(s):961.37` -* 数据大小：`total size(MB): 353227.18` -* 恢复吞吐：`avg speed(MB/s): 367.42` -* `Region Split` 耗时：`take=49.049182743s` -* 校验耗时：`take=6m34.879439498s` - -根据上表数据可以计算得到： - -* 单个 TiKV 吞吐：`avg speed(MB/s)`/`tikv_count` = `91.8` -* 单个 TiKV 平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` = `87.4` - -#### 性能调优 - -如果 TiKV 资源使用没有明显的瓶颈，可以尝试调大 `--concurrency` 参数（默认为 `128`），示例如下： - -{{< copyable "shell-regular" >}} - -```shell -bin/br restore table --db batchmark --table order_line -s local:///br_data/ --pd 172.16.5.198:2379 --log-file restore-concurrency.log --concurrency 1024 -``` - -性能调优后的结果如下表所示（保持数据大小不变）： - -* 恢复耗时：`total take(s)` 从 `961.37` 减少到 `443.49` -* 恢复吞吐：`avg speed(MB/s)` 从 `367.42` 提升到 `796.47` -* 单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` 从 `91.8` 提升到 `199.1` -* 单个 TiKV 实例的平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` 从 `87.4` 提升到 `162.3` - -### 将单表数据备份到本地磁盘 - -使用 `br backup 命令`，将单表数据 `--db batchmark --table order_line` 备份到指定的本地磁盘路径 `local:///home/tidb/backup_local` 下。 - -#### 前置要求 - -* 各个 TiKV 节点有单独的磁盘用来存放 backupSST 数据。 -* `backup_endpoint` 节点有单独的磁盘用来存放备份的 `backupmeta` 文件。 -* TiKV 和 `backup_endpoint` 节点需要有相同的备份目录，例如 `/home/tidb/backup_local`。 - -#### 部署拓扑 - -![img](/media/br/backup-local-deploy.png) - -#### 运行备份 - -备份前在 TiDB 里通过 `admin checksum table order_line` 获得备份的目标表 `--db batchmark --table order_line` 的统计信息。统计信息示例如下： - -![img](/media/br/total-data.png) - -运行 `br backup` 命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br backup table --db batchmark --table order_line -s local:///home/tidb/backup_local/ --pd 172.16.5.198:2379 --log-file backup_local.log -``` - -运行备份时，参考[备份过程中的运行指标](#备份过程中的运行指标)对相关指标进行监控，以了解备份状态。 - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从该路径下存放的日志获取此次备份的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table backup summary: total backup ranges: 4, total success: 4, total failed: 0, total take(s): 551.31, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 640.71"] ["backup total regions"=6795] ["backup checksum"=6m33.962719217s] ["backup fast checksum"=22.995552ms] -``` - -以上日志信息中包含以下内容： - -* 备份耗时：`total take(s): 551.31` -* 数据大小：`total size(MB): 353227.18` -* 备份吞吐：`avg speed(MB/s): 640.71` -* 校验耗时：`take=6m33.962719217s` - -根据上表数据可以计算得到单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` = `160`。 - -### 从本地磁盘恢复备份数据 - -使用 `br restore` 命令，将一份完整的备份数据恢复到一个离线集群。暂不支持恢复到在线集群。 - -#### 前置要求 - -* 集群中没有与备份数据相同的库表。目前 BR 不支持 table route。 -* 集群中各个 TiKV 节点有单独的磁盘用来存放要恢复的 backupSST 数据。 -* `restore_endpoint` 节点有单独的磁盘用来存放要恢复的 `backupmeta` 文件。 -* 集群中 TiKV 和 `restore_endpoint` 节点需要有相同的备份目录，例如 `/home/tidb/backup_local/`。 - -如果备份数据存放在本地磁盘，那么需要执行以下的步骤： - -1. 汇总所有 backupSST 文件到一个统一的目录下。 -2. 将汇总后的 backupSST 文件到复制到集群的所有 TiKV 节点下。 -3. 将 `backupmeta` 文件复制到到 `restore endpoint` 节点下。 - -#### 部署拓扑 - -![img](/media/br/restore-local-deploy.png) - -#### 运行恢复 - -运行 `br restore` 命令： - -{{< copyable "shell-regular" >}} - -```shell -bin/br restore table --db batchmark --table order_line -s local:///home/tidb/backup_local/ --pd 172.16.5.198:2379 --log-file restore_local.log -``` - -运行恢复时，参考[恢复过程中的运行指标](#恢复过程中的运行指标)对相关指标进行监控，以了解恢复状态。 - -#### 结果解读 - -使用 BR 前已设置日志的存放路径。从该日志中可以获取此次恢复的相关统计信息。在日志中搜关键字 "summary"，可以看到以下信息： - -``` -["Table Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 908.42, total kv: 5659888624, total size(MB): 353227.18, avg speed(MB/s): 388.84"] ["restore files"=9263] ["restore ranges"=6888] ["split region"=58.7885518s] ["restore checksum"=6m19.349067937s] -``` - -以上日志信息中包含以下内容： - -* 恢复耗时：`total take(s): 908.42` -* 数据大小：`total size(MB): 353227.18` -* 恢复吞吐：`avg speed(MB/s): 388.84` -* `Region Split` 耗时：`take=58.7885518s` -* 校验耗时：`take=6m19.349067937s` - -根据上表数据可以计算得到： - -* 单个 TiKV 实例的吞吐：`avg speed(MB/s)`/`tikv_count` = `97.2` -* 单个 TiKV 实例的平均恢复速度：`total size(MB)`/(`split time` + `restore time`)/`tikv_count` = `92.4` - -### 异常处理 - -本部分介绍如何处理备份过程中出现的常见错误。 - -#### 备份日志中出现 `key locked Error` - -日志中的错误消息：`log - ["backup occur kv error"][error="{\"KvError\":{\"locked\":` - -如果在备份过程中遇到 key 被锁住，目前 BR 会尝试清锁。少量报错不会影响备份的正确性。 - -#### 备份失败 - -日志中的错误消息：`log - Error: msg:"Io(Custom { kind: AlreadyExists, error: \"[5_5359_42_123_default.sst] is already exists in /dir/backup_local/\" })"` - -若备份失败并出现以上错误消息，采取以下其中一种操作后再重新备份： - -* 更换备份数据目录。例如将 `/dir/backup-2020-01-01/` 改为 `/dir/backup_local/`。 -* 删除所有 TiKV 和 BR 节点的备份目录。 diff --git a/v3.1/reference/tools/data-migration/cluster-operations.md b/v3.1/reference/tools/data-migration/cluster-operations.md deleted file mode 100644 index 7fb6c854003a..000000000000 --- a/v3.1/reference/tools/data-migration/cluster-operations.md +++ /dev/null @@ -1,489 +0,0 @@ ---- -title: DM 集群操作 -category: reference ---- - -# DM 集群操作 - -本文介绍 DM 集群操作以及使用 DM-Ansible 管理 DM 集群时需要注意的事项。 - -## 启动集群 - -运行以下命令以启动整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook start.yml -``` - -## 下线集群 - -运行以下命令以下线整个集群的所有组件（包括 DM-master、DM-worker 和监控组件）： - -{{< copyable "shell-regular" >}} - -```bash -ansible-playbook stop.yml -``` - -## 重启集群组件 - -在以下情况下，需要更新 DM 集群组件： - -- 您想要[更新组件版本](#更新组件版本)。 -- 发生了严重的错误，您需要重启组件完成临时恢复。 -- DM 集群所在的机器由于某种原因重启。 - -### 重启注意事项 - -该部分描述重启 DM 各组件时需要了解的事项。 - -#### DM-worker 重启事项 - -**全量数据导入过程中：** - -对于全量数据导入时的 SQL 文件，DM 使用下游数据库记录断点信息，DM-worker 会在本地 meta 文件记录子任务信息。DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -**增量数据同步过程中：** - -对于增量数据导入过程中的 binlog，DM 使用下游数据库记录断点信息，并会在同步任务开始或恢复后的第一个五分钟之内开启安全模式。 - -+ 未启用 sharding DDL 同步 - - 如果 DM-worker 上运行的任务未启用 sharding DDL 同步功能，DM-worker 重启时会检查断点信息和本地记录的子任务信息，重启前处于运行中状态的任务会自动恢复数据同步。 - -+ 已启用 sharding DDL 同步 - - - DM 同步 sharding DDL 语句时，如果 DM-worker 成功执行（或跳过）sharding DDL 的 binlog event，与 DM-worker 中的 sharding DDL 语句相关的所有表的断点信息都会被更新至 DDL 语句对应的 binlog event 之后的位置。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步开始前或完成后，DM-worker 会根据断点信息和本地记录的子任务信息自动恢复数据同步。 - - - 当 DM-worker 重启发生在 sharding DDL 语句同步过程中，可能会出现作为 DDL lock owner 的 DM-worker 实例已执行了 DDL 语句并成功变更了下游数据库表结构，但其他 DM-worker 实例重启而无法跳过 DDL 语句也无法更新断点的情况。 - - 此时 DM 会再次尝试同步这些未跳过执行的 DDL 语句。然而，由于未重启的 DM-worker 实例已经执行到了此 DDL 对应的 binlog event 之后，重启的 DM-worker 实例会被阻滞在重启前 DDL binlog event 对应的位置。 - - 要解决这个问题，请按照[手动处理 Sharding DDL Lock](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#场景二unlock-过程中部分-dm-worker-重启) 中描述的步骤操作。 - -**总结**：尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -#### DM-master 重启事项 - -由 DM-master 维护的信息包括以下两种。重启 DM-master 不会持久化保存这些信息的相关数据。 - -- 任务信息 -- Sharding DDL lock 信息 - -DM-master 重启时会自动向每个 DM-worker 实例请求任务信息，重建任务与 DM-worker 之间的对应关系，并从每个 DM-worker 实例获取 sharding DDL 信息。这样，就可以准确重建相应的 DDL lock，也可以自动解除 sharding DDL lock。 - -### 重启 DM-worker - -> **注意：** -> -> 尽量避免在 sharding DDL 同步过程中重启 DM-worker。 - -使用以下两种方法中任一种重启 DM-worker 组件： - -- 对 DM-worker 执行滚动升级。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - -- 先停止 DM-worker，然后重启。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker && - ansible-playbook start.yml --tags=dm-worker - ``` - -### 重启 DM-master - -在以下两种方法中任选一种，重启 DM-master 组件： - -- 对 DM-master 执行滚动升级。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -- 停止 DM-master，然后重启。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-master && - ansible-playbook start.yml --tags=dm-master - ``` - -## 更新组件版本 - -1. 下载 DM 二进制文件。 - - 1. 从 `downloads` 目录删除已有文件。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - rm -rf downloads - ``` - - 2. 用 Playbook 下载 inventory.ini 文件中指定版本的最新 DM 二进制文件。这会自动替换 `/home/tidb/dm-ansible/resource/bin/` 中已有文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook local_prepare.yml - ``` - -2. 使用 Ansible 执行滚动升级。 - - 1. 对 DM-worker 实例执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-worker - ``` - - 2. 对 DM-master 实例执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - - 3. 升级 dmctl： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dmctl - ``` - - 4. 对 DM-worker， DM-master， 以及 dmctl 整体执行滚动升级： - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml - ``` - -## 创建 DM-worker 实例 - -假设您想要在机器 `172.16.10.74` 上创建一个名为 `dm_worker3` 的 DM-worker 实例，按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v3.1/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 用户登录至中控机，并将 `172.16.10.74` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.74 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.74`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.74` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 修改 `inventory.ini` 文件，创建新 DM-worker 实例 `dm_worker3`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -3. 部署新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-worker -l dm_worker3 - ``` - -4. 启用新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-worker -l dm_worker3 - ``` - -5. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -6. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 下线 DM-worker 实例 - -假设您想要下线的 DM-worker 实例为 `dm_worker3`。按以下步骤操作： - -1. 关闭您想要下线的 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker -l dm_worker3 - ``` - -2. 修改 `inventory.ini` 文件，注释或删除 `dm_worker3` 实例所在行。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - # dm_worker3 source_id="mysql-replica-03" ansible_host=172.16.10.74 server_id=103 mysql_host=172.16.10.83 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 # Comment or delete this line - ``` - -3. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -4. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -## 替换/迁移 DM-master 实例 - -假设机器 `172.16.10.71` 需要进行维护或者已崩溃，需要将 DM-master 实例从 `172.16.10.71` 迁移至 `172.16.10.80`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v3.1/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.80` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.80 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.80`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.80` 机器上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 关闭待替换的 DM-master 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-master - ``` - -3. 修改 `inventory.ini` 文件。注释或删除待替换实例所在行，同时为新 DM-master 实例添加相关信息。 - - ```ini - [dm_master_servers] - # dm_master ansible_host=172.16.10.71 - dm_master ansible_host=172.16.10.80 - ``` - -4. 部署新 DM-master 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-master - ``` - -5. 启用新 DM-master 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-master - ``` - -6. 更新 dmctl 配置文件。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dmctl - ``` - -## 替换/迁移 DM-worker 实例 - -假设机器 `172.16.10.72` 需要进行维护或者已崩溃，您需要将 `dm_worker1` 实例从 `172.16.10.72` 迁移至 `172.16.10.75`。按以下步骤操作： - -1. 为中控机设置 SSH 互信以及 sudo 规则。 - - 1. 参考[在中控机上配置 SSH 互信和 sudo 规则](/v3.1/how-to/deploy/data-migration-with-ansible.md#第-5-步在中控机上配置-ssh-互信和-sudo-规则)，使用 `tidb` 账户登录至中控机，并将 `172.16.10.75` 添加至 `hosts.ini` 文件中的 `[servers]` 部分。 - - {{< copyable "shell-regular" >}} - - ```bash - cd /home/tidb/dm-ansible && - vi hosts.ini - ``` - - ``` - [servers] - 172.16.10.75 - - [all:vars] - username = tidb - ``` - - 2. 运行以下命令。根据屏幕提示，输入 `root` 用户密码以部署 `172.16.10.85`。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook -i hosts.ini create_users.yml -u root -k - ``` - - 该步在 `172.16.10.75` 上创建了一个 `tidb` 用户，设置了 sudo 规则，并为中控机与该机器配置了 SSH 互信。 - -2. 下线待替换 DM-worker 实例。 - - > **注意：** - > - > 如果机器 `172.16.10.71` 宕机，无法通过 SSH 登录，请忽略此步。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook stop.yml --tags=dm-worker -l dm_worker1 - ``` - -3. 修改 `inventory.ini` 文件，为新 DM-worker 实例添加相关信息。 - - 修改 `inventory.ini` 文件。注释或删除旧 `dm_worker1` 实例所在行；同时为新 `dm_worker1` 实例添加相关信息。 - - 如果希望从不同的 binlog position 或 GTID Sets 拉取 relay log，则也需要更新对应的 `{relay_binlog_name}` 或 `{relay_binlog_gtid}`。 - - ```ini - [dm_worker_servers] - dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.75 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - # dm_worker1 source_id="mysql-replica-01" ansible_host=172.16.10.72 server_id=101 mysql_host=172.16.10.81 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - - dm_worker2 source_id="mysql-replica-02" ansible_host=172.16.10.73 server_id=102 mysql_host=172.16.10.82 mysql_user=root mysql_password='VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=' mysql_port=3306 - ``` - -4. 部署新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook deploy.yml --tags=dm-worker -l dm_worker1 - ``` - -5. 迁移 relay log 数据。 - - - 如果待替换 DM-worker 实例所在机器仍能访问，则可直接将该实例的 `{dm_worker_relay_dir}` 目录下的所有数据复制到新 DM-worker 实例的对应目录。 - - - 如果待替换 DM-worker 实例所在机器已无法访问，可能需在第 9 步中手动恢复 relay log 目录等信息。 - -6. 启动新 DM-worker 实例。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook start.yml --tags=dm-worker -l dm_worker1 - ``` - -7. 配置并重启 DM-master 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update.yml --tags=dm-master - ``` - -8. 配置并重启 Prometheus 服务。 - - {{< copyable "shell-regular" >}} - - ```bash - ansible-playbook rolling_update_monitor.yml --tags=prometheus - ``` - -9. 启动并验证数据迁移任务。 - - 使用 `start-task` 命令启动数据迁移任务，如果任务运行正常，则表示 DM-worker 迁移顺利完成；如果报类似如下错误，则需要对 relay log 目录进行手动修复。 - - ```log - fail to initial unit Sync of subtask test-task : UUID suffix 000002 with UUIDs [1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001] not found - ``` - - 如果待替换 DM-worker 所连接的上游 MySQL 已发生过切换，则会产生如上错误。此时可通过如下步骤手动修复： - - 1. 使用 `stop-task` 命令停止数据迁移任务。 - - 2. 通过 `$ ansible-playbook stop.yml --tags=dm-worker -l dm_worker1` 停止 DM-worker 实例。 - - 3. 更新 relay log 子目录的后缀，例如将 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 重命名为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 4. 更新 relay log 子目录索引文件 `server-uuid.index`，例如将其中的内容由 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000001` 变更为 `1ddbf6d3-d3b2-11e9-a4e9-0242ac140003.000002`。 - - 5. 通过 `$ ansible-playbook start.yml --tags=dm-worker -l dm_worker1` 启动 DM-worker 实例。 - - 6. 再次启动并验证数据迁移任务。 diff --git a/v3.1/reference/tools/data-migration/configure/dm-master-configuration-file.md b/v3.1/reference/tools/data-migration/configure/dm-master-configuration-file.md deleted file mode 100644 index 6d01371b976b..000000000000 --- a/v3.1/reference/tools/data-migration/configure/dm-master-configuration-file.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: DM-master 配置文件介绍 -category: reference ---- - -# DM-master 配置文件介绍 - -本文介绍 DM-master 的配置文件，包括配置文件示例与配置项说明。 - -## 配置文件示例 - -DM-master 的示例配置文件如下所示： - -```toml -# log configuration -log-file = "dm-master.log" - -# DM-master listening address -master-addr = ":8261" - -# DM-worker deployment. It will be refined when the new deployment function is available. -[[deploy]] -source-id = "mysql-replica-01" -dm-worker = "172.16.10.72:8262" - -[[deploy]] -source-id = "mysql-replica-02" -dm-worker = "172.16.10.73:8262" -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置，日志会输出到标准输出中。 | -| `master-addr` | DM-master 服务的地址，可以省略 IP 信息，例如：":8261"。 | - -### DM-Worker 的配置 - -配置在 `deploy` 中，每一个 DM-worker 都需要设置一个 `deploy`。 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `source-id` | 一个 replication group 或者 MySQL/MariaDB 实例的标识，需要和 DM-worker 中的 `source-id` 一致。 | -| `dm-worker` | DM-worker 的服务地址。 | diff --git a/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md b/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md deleted file mode 100644 index 4b794e2f49f7..000000000000 --- a/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: DM-worker 完整配置说明 -category: reference ---- - -# DM-worker 完整配置说明 - -本文完整地介绍 DM-worker 的配置，包括配置文件示例与配置项说明。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-level = "info" -log-file = "dm-worker.log" - -# DM-worker listening address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in the replication group should have a different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory used to store relay log. -relay-dir = "./relay_log" - -# Enables gtid in the relay log unit -enable-gtid = false - -relay-binlog-name = "" -relay-binlog-gtid = "" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 - -# Relay log purge strategy. -[purge] -interval = 3600 -expires = 24 -remain-space = 15 - -# Task status checker. -[checker] -check-enable = true -backoff-rollback = "5m" -backoff-max = "5m" -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-level` | 日志等级，值可以为 "debug"、"info"、"warn"、"error"、"fatal"，默认值为 "info"。一般情况下不需要手动配置，如果需要排查问题，可以将等级设置为 "debug"。 | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。 | -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中必须是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | -| `enable-gtid` | 是否使用 GTID 方式从上游拉取 binlog，默认值为 false。一般情况下不需要手动配置，如果上游数据库启用了 GTID 支持，且需要做主从切换，则将该配置项设置为 true。 | -| `relay-binlog-name` | 拉取上游 binlog 的起始文件名，例如 "mysql-bin.000002"，该配置在 `enable-gtid` 为 false 的情况下生效。如果不配置该项，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog 文件开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 | -| `relay-binlog-gtid` | 拉取上游 binlog 的起始 GTID，例如 "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"，该配置在 `enable-gtid` 为 true 的情况下生效。如果不配置该项，v1.0.2 之前版本的 DM-worker 将从上游 MySQL 或 MariaDB 现有最早时间点的 binlog GTID 开始拉取 binlog，拉取到数据同步任务需要的最新 binlog 可能需要很长时间；v1.0.2 及之后版本的 DM-worker 将从最新时间点的 binlog GTID 开始拉取 binlog，一般情况下不需要手动配置。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。 | -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -### relay log 清理策略配置（purge 配置项） - -一般情况下不需要手动配置，如果 relay log 数据量较大，磁盘空间不足，则可以通过该配置项设置，避免 relay log 写满磁盘。 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `interval` | 定期检查 relay log 是否过期的间隔时间，默认值：3600，单位：秒。 | -| `expires` | relay log 的过期时间，默认值为 0，单位：小时。超过过期时间的 relay log 会被 DM 删除。如果不设置则 DM 不会自动清理过期的 relay log。 | -| `remain-space` | 设置最小的可用磁盘空间。当磁盘可用空间小于这个值时，DM-worker 会尝试删除 relay log，默认值：15，单位：GB。 | - -> **注意：** -> -> 仅在 `interval` 不为 0 且 `expires` 和 `remain-space` 两个配置项中至少有一个不为 0 的情况下 DM 的自动清理策略才会生效。 - -### 任务检查模块配置（checker 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `check-enable` | 是否开启任务状态检查。开启后 DM 会尝试自动恢复因错误而暂停的数据同步任务，默认值：true。 | -| `backoff-rollback` | 任务检查模块中，定时调整恢复等待时间的间隔，默认值："5m0s"。 | -| `backoff-max` | 任务检查模块中，检查出错误后等待自动恢复的最长时间间隔，默认值："5m0s"。 | - -> **注意：** -> -> 用户只需要通过配置 `check-enable` 开启或者关闭任务状态检查功能。对于 `backoff-rollback` 和 `backoff-max` 一般情况下不需要修改，如果对该参数的作用没有深入的了解，不建议修改这两项参数。 diff --git a/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md b/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md deleted file mode 100644 index a4510c7116a6..000000000000 --- a/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: DM-worker 配置文件介绍 -category: reference ---- - -# DM-worker 配置文件介绍 - -本文档主要介绍 DM-worker 的基础配置文件。在一般场景中，用户只需要使用基础配置即可完成 DM-worker 的部署。 - -完整配置项参考 [DM-worker 完整配置说明](/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 - -## 配置文件示例 - -```toml -# Worker Configuration. - -# Log configuration. -log-file = "dm-worker.log" - -# DM-worker listen address. -worker-addr = ":8262" - -# Represents a MySQL/MariaDB instance or a replication group. -source-id = "mysql-replica-01" - -# Server id of slave for binlog replication. -# Each instance (master and slave) in replication group should have different server id. -server-id = 101 - -# flavor: mysql/mariadb -flavor = "mysql" - -# The directory that used to store relay log. -relay-dir = "./relay_log" - -[from] -host = "127.0.0.1" -user = "root" -password = "Up8156jArvIPymkVC+5LxkAT6rek" -port = 3306 -``` - -## 配置项说明 - -### Global 配置 - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `log-file` | 日志文件，如果不配置日志会输出到标准输出中。 | -| `worker-addr` | DM-worker 服务的地址，可以省略 IP 信息，例如：":8262"。| -| `source-id` | 标识一个 MySQL/MariaDB 实例或者 replication group。 | -| `server-id` | DM-worker 作为上游 MySQL/MariaDB slave 来获取 binlog 的 server id，该值在一个 replication group （包括 master 和 slave）中是唯一的。v1.0.2 及以上版本的 DM 会自动生成，不需要手动配置该项。 | -| `flavor` | 上游数据库的类型，目前值可以为 "mysql" 或者 "mariadb"。v1.0.2 及以上版本的 DM 会自动判断上游版本，不需要手动配置该项。 | -| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。 | - -### 数据库链接配置（from 配置项） - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `host` | 上游数据库的 host。| -| `port` | 上游数据库的端口。 | -| `user` | 连接数据库使用的用户名。 | -| `password` | 连接数据库使用的密码。注意：需要使用 dmctl 加密后的密码。 | - -> **注意：** -> -> 以上配置为部署 DM-worker 的基础配置，一般情况下使用基础配置即可，更多配置项参考 [DM-worker 完整配置说明](/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file-full.md)。 diff --git a/v3.1/reference/tools/data-migration/configure/overview.md b/v3.1/reference/tools/data-migration/configure/overview.md deleted file mode 100644 index f41afe53dde9..000000000000 --- a/v3.1/reference/tools/data-migration/configure/overview.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: DM 配置简介 -category: reference ---- - -# DM 配置简介 - -本文档简要介绍 DM (Data Migration) 的配置文件和数据同步任务的配置。 - -## 配置文件 - -- `inventory.ini`：使用 DM-Ansible 部署 DM 集群的配置文件。需要根据所选用的集群拓扑来进行编辑。详见[编辑 `inventory.ini` 配置文件](/v3.1/how-to/deploy/data-migration-with-ansible.md#第-7-步编辑-inventoryini-配置文件)。 -- `dm-master.toml`：DM-master 进程的配置文件，包括 DM 集群的拓扑信息、MySQL 实例与 DM-worker 之间的关系（必须为一对一的关系）。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-master.toml` 文件，各项配置说明详见 [DM-master 配置文件介绍](/v3.1/reference/tools/data-migration/configure/dm-master-configuration-file.md) -- `dm-worker.toml`：DM-worker 进程的配置文件，包括上游 MySQL 实例的配置和 relay log 的配置。使用 DM-Ansible 部署 DM 集群时，会自动生成 `dm-worker.toml` 文件，各项配置说明详见 [DM-worker 配置文件介绍](/v3.1/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - -## 同步任务配置 - -### 任务配置文件 - -使用 DM-Ansible 部署 DM 集群时，`/conf` 中提供了任务配置文件模板：`task.yaml.exmaple` 文件。该文件是 DM 同步任务配置的标准文件，每一个具体的任务对应一个 `task.yaml` 文件。关于该配置文件的详细介绍，参见 [任务配置文件](/v3.1/reference/tools/data-migration/configure/task-configuration-file.md)。 - -### 创建数据同步任务 - -你可以基于 `task.yaml.example` 文件来创建数据同步任务，具体步骤如下： - -1. 复制 `task.yaml.example` 为 `your_task.yaml`。 -2. 参考[任务配置文件](/v3.1/reference/tools/data-migration/configure/task-configuration-file.md)来修改 `your_task.yaml` 文件。 -3. [使用 dmctl 创建数据同步任务](/v3.1/reference/tools/data-migration/manage-tasks.md#创建数据同步任务)。 - -### 关键概念 - -DM 配置的关键概念如下： - -| 概念 | 解释 | 配置文件 | -| :------------ | :------------ | :------------------ | -| source-id | 唯一确定一个 MySQL 或 MariaDB 实例，或者一个具有主从结构的复制组，字符串长度不大于 32 | `inventory.ini` 的 `source_id`；
`dm-master.toml` 的 `source-id`；
`task.yaml` 的 `source-id` | -| DM-worker ID | 唯一确定一个 DM-worker（取值于 `dm-worker.toml` 的 `worker-addr` 参数） | `dm-worker.toml` 的 `worker-addr`；
dmctl 命令行的 `-worker` / `-w` flag | diff --git a/v3.1/reference/tools/data-migration/configure/task-configuration-file-full.md b/v3.1/reference/tools/data-migration/configure/task-configuration-file-full.md deleted file mode 100644 index 7dbfbb05383d..000000000000 --- a/v3.1/reference/tools/data-migration/configure/task-configuration-file-full.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: DM 任务完整配置文件介绍 -category: reference ---- - -# DM 任务完整配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务完整的配置文件 [`task_advanced.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_advanced.yaml)，包含[全局配置](#全局配置) 和[实例配置](#实例配置) 两部分。 - -关于各配置项的功能和配置，请参阅[数据同步功能](/v3.1/reference/tools/data-migration/features/overview.md#同步功能介绍)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/v3.1/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 完整配置文件示例 - -下面是一个完整的配置文件示例，通过该示例可以完成复杂的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" -is-sharding: true # 是否为分库分表合并任务 -meta-schema: "dm_meta" # 下游储存 `meta` 信息的数据库 -remove-meta: false # 是否在任务同步开始前移除该任务名对应的 `meta`（`checkpoint` 和 `onlineddl` 等）。 -enable-heartbeat: false # 是否开启 `heartbeat` 功能 - -target-database: # 下游数据库实例配置 - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - - -## ******** 功能配置集 ********** - -routes: # 上游和下游表之间的路由 table routing 规则集 - route-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - target-schema: "test" # 目标库名称 - target-table: "t" # 目标表名称 - route-rule-2: - schema-pattern: "test_*" - target-schema: "test" - -filters: # 上游数据库实例匹配的表的 binlog event filter 规则集 - filter-rule-1: # 配置名称 - schema-pattern: "test_*" # 库名匹配规则，支持通配符 "*" 和 "?" - table-pattern: "t_*" # 表名匹配规则，支持通配符 "*" 和 "?" - events: ["truncate table", "drop table"] # 匹配哪些 event 类型 - action: Ignore # 对与符合匹配规则的 binlog 同步（Do）还是忽略(Ignore) - filter-rule-2: - schema-pattern: "test_*" - events: ["all dml"] - action: Do - -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 配置名称 - do-dbs: ["~^test.*", "user"] # 同步哪些库 - ignore-dbs: ["mysql", "account"] # 忽略哪些库 - do-tables: # 同步哪些表 - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "user" - tbl-name: "information" - ignore-tables: # 忽略哪些表 - - db-name: "user" - tbl-name: "log" - -mydumpers: # mydumper 处理单元运行配置参数 - global: # 配置名称 - mydumper-path: "./bin/mydumper" # mydumper binary 文件地址，默认值为 "./bin/mydumper" - threads: 4 # mydumper 从上游数据库实例导出数据的线程数量，默认值为 4 - chunk-filesize: 64 # mydumper 生成的数据文件大小，默认值为 64，单位为 MB - skip-tz-utc: true # 忽略对时间类型数据进行时区转化，默认值为 true - extra-args: "--no-locks" # mydumper 的其他参数，在 v1.0.2 版本中 DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置 - -loaders: # loader 处理单元运行配置参数 - global: # 配置名称 - pool-size: 16 # loader 并发执行 mydumper 的 SQL 文件的线程数量，默认值为 16 - dir: "./dumped_data" # loader 读取 mydumper 输出文件的地址，同实例对应的不同任务必须不同（mydumper 会根据这个地址输出 SQL 文件），默认值为 "./dumped_data" - -syncers: # syncer 处理单元运行配置参数 - global: # 配置名称 - worker-count: 16 # syncer 并发同步 binlog event 的线程数量，默认值为 16 - batch: 100 # syncer 同步到下游数据库的一个事务批次 SQL 语句数，默认值为 100 - -# ----------- 实例配置 ----------- -mysql-instances: - - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - meta: # `task-mode` 为 `incremental` 且下游数据库的 `checkpoint` 不存在时 binlog 同步开始的位置; 如果 checkpoint 存在，则以 `checkpoint` 为准 - binlog-name: binlog.000001 - binlog-pos: 4 - - route-rules: ["route-rule-1", "route-rule-2"] # 该上游数据库实例匹配的表到下游数据库的 table routing 规则名称 - filter-rules: ["filter-rule-1"] # 该上游数据库实例匹配的表的 binlog event filter 规则名称 - black-white-list: "bw-rule-1" # 该上游数据库实例匹配的表的 black & white list 过滤规则名称 - - mydumper-config-name: "global" # mydumper 配置名称 - loader-config-name: "global" # loader 配置名称 - syncer-config-name: "global" # Syncer 配置名称 - - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id` 配置 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，等同于 mydumper 处理单元配置中的 `threads`，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，等同于 loader 处理单元配置中的 `pool-size`, 在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，等同于 syncer 处理单元配置中的 `worker-count`，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基本信息配置`和`实例配置`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。其中 `task-mode` 需要特殊说明： - -`task-mode` - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -全局配置主要包含下列功能配置集： - -| 配置项 | 说明 | -| :------------ | :--------------------------------------- | -| `routes` | 上游和下游表之间的路由 table routing 规则集。如果上游与下游的库名、表名一致，则不需要配置该项。使用场景及示例配置参见 [Table Routing](/v3.1/reference/tools/data-migration/features/overview.md#table-routing) | -| `filters` | 上游数据库实例匹配的表的 binlog event filter 规则集。如果不需要对 binlog 进行过滤，则不需要配置该项。使用场景及示例配置参见 [Binlog Event Filter](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) | -| `black-white-list` | 该上游数据库实例匹配的表的 black & white list 过滤规则集。建议通过该项指定需要同步的库和表，否则会同步所有的库和表。使用场景及示例配置参见 [Black & White Lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) | -| `mydumpers` | mydumper 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `mydumper-thread` 对 `thread` 配置项单独进行配置。 | -| `loaders` | loader 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `loader-thread` 对 `pool-size` 配置项单独进行配置。 | -| `syncers` | syncer 处理单元运行配置参数。如果默认配置可以满足需求，则不需要配置该项，也可以只使用 `syncer-thread` 对 `worker-count` 配置项单独进行配置。 | - -各个功能配置集的参数及解释参见[完整配置文件示例](#完整配置文件示例)中的注释说明。 - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 - -在该项配置中设置数据同步子任务中各个功能对应的配置集中的配置名称，关于这些配置项的更多配置细节，参见[功能配置集](#功能配置集)的相关配置项，对应关系如下： - -| 配置项 | 相关配置项 | -| :------ | :------------------ | -| `route-rules` | `routes` | -| `filter-rules` | `filters` | -| `black-white-list` | `black-white-list` | -| `mydumper-config-name` | `mydumpers` | -| `loader-config-name` | `loaders` | -| `syncer-config-name` | `syncers` | diff --git a/v3.1/reference/tools/data-migration/configure/task-configuration-file.md b/v3.1/reference/tools/data-migration/configure/task-configuration-file.md deleted file mode 100644 index 2e2ad1dd3137..000000000000 --- a/v3.1/reference/tools/data-migration/configure/task-configuration-file.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: DM 任务配置文件介绍 -category: reference ---- - -# DM 任务配置文件介绍 - -本文档主要介绍 Data Migration (DM) 的任务基础配置文件 [`task_basic.yaml`](https://github.com/pingcap/dm/blob/master/dm/master/task_basic.yaml)，包含[全局配置](#全局配置)和[实例配置](#实例配置)两部分。 - -完整的任务配置参见 [DM 任务完整配置文件介绍](/v3.1/reference/tools/data-migration/configure/task-configuration-file-full.md) - -关于各配置项的功能和配置，请参阅[数据同步功能](/v3.1/reference/tools/data-migration/features/overview.md)。 - -## 关键概念 - -关于包括 `source-id` 和 DM-worker ID 在内的关键概念的介绍，请参阅[关键概念](/v3.1/reference/tools/data-migration/configure/overview.md#关键概念)。 - -## 基础配置文件示例 - -下面是一个基础的配置文件示例，通过该示例可以完成简单的数据同步功能。 - -```yaml ---- - -# ----------- 全局配置 ----------- -## ********* 基本信息配置 ********* -name: test # 任务名称，需要全局唯一 -task-mode: all # 任务模式，可设为 "full"、"incremental"、"all" - -target-database: # 下游数据库实例配置 - host: "127.0.0.1" - port: 4000 - user: "root" - password: "" # 如果不为空则需经过 dmctl 加密 - -## ******** 功能配置集 ********** -black-white-list: # 上游数据库实例匹配的表的 black & white list 过滤规则集 - bw-rule-1: # 黑白名单配置的名称 - do-dbs: ["all_mode"] # 同步哪些库 - -# ----------- 实例配置 ----------- -mysql-instances: - - source-id: "mysql-replica-01" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 - - - source-id: "mysql-replica-02" # 上游实例或者复制组 ID，参考 `dm-master.toml` 的 `source-id` 配置 - black-white-list: "bw-rule-1" # 黑白名单配置名称 - mydumper-thread: 4 # mydumper 用于导出数据的线程数量，在 v1.0.2 版本引入 - loader-thread: 16 # loader 用于导入数据的线程数量，在 v1.0.2 版本引入 - syncer-thread: 16 # syncer 用于同步增量数据的线程数量，在 v1.0.2 版本引入 -``` - -## 配置顺序 - -通过上面的配置文件示例，可以看出配置文件总共分为两个部分：`全局配置`和`实例配置`，其中`全局配置`又分为`基础信息配置`和`功能配置集`，配置顺序如下： - -1. 编辑[全局配置](#全局配置)。 -2. 根据全局配置编辑[实例配置](#实例配置)。 - -## 全局配置 - -### 任务基本信息配置 - -配置任务的基本信息，配置项的说明参见以上示例配置文件中的注释。关于 `task-mode` 的特殊说明如下： - -- 描述：任务模式，可以通过任务模式来指定需要执行的数据迁移工作。 -- 值为字符串（`full`，`incremental` 或 `all`）。 - - `full`：只全量备份上游数据库，然后将数据全量导入到下游数据库。 - - `incremental`：只通过 binlog 把上游数据库的增量修改同步到下游数据库, 可以设置实例配置的 `meta` 配置项来指定增量同步开始的位置。 - - `all`：`full` + `incremental`。先全量备份上游数据库，将数据全量导入到下游数据库，然后从全量数据备份时导出的位置信息 (binlog position) 开始通过 binlog 增量同步数据到下游数据库。 - -### 功能配置集 - -对于一般的业务场景，只需要配置黑白名单过滤规则集，配置说明参见以上示例配置文件中 `black-white-list` 的注释以及 [Black & white table lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) - -## 实例配置 - -本小节定义具体的数据同步子任务，DM 支持从单个或者多个上游 MySQL 实例同步数据到同一个下游数据库实例。 -配置项说明参见以上示例配置文件中 `mysql-instances` 的注释。 diff --git a/v3.1/reference/tools/data-migration/deploy.md b/v3.1/reference/tools/data-migration/deploy.md deleted file mode 100644 index 141c8d7eaceb..000000000000 --- a/v3.1/reference/tools/data-migration/deploy.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: 使用 DM 同步数据 -category: reference ---- - -# 使用 DM 同步数据 - -本文介绍如何使用 DM (Data Migration) 同步数据。 - -## 第 1 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照 [使用 DM-Ansible 部署 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md)；也可以使用 binary 部署 DM 集群用于体验或者测试，具体部署方法参照[使用 DM binary 部署 DM 集群](/v3.1/how-to/deploy/data-migration-with-binary.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 2 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 MySQL-1 | 172.16.10.81 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 MySQL-2 | 172.16.10.82 | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - - > **注意：** - > - > `{ansible deploy}/conf/dm-master.toml` 中的 `{ansible deploy}` 表示使用 DM-Ansible 部署 DM 时通过 `deploy_dir` 参数指定的目录。 - -## 第 3 步：配置任务 - -假设需要将 MySQL-1 和 MySQL-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - mydumper-path: "./bin/mydumper" # Mydumper 二进制文件的路径。 - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 4 步：启动任务 - -为了提前发现数据同步任务的一些配置错误，DM 中增加了[前置检查](/v3.1/reference/tools/data-migration/precheck.md)功能： - -- 启动数据同步任务时，DM 自动检查相应的权限和配置。 -- 也可使用 `check-task` 命令手动前置检查上游的 MySQL 实例配置是否符合 DM 的配置要求。 - -> **注意：** -> -> 第一次启动数据同步任务时，必须确保上游数据库已配置。否则，启动任务时会报错。 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/`。 - -2. 执行以下命令启动 dmctl。 - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务。其中，`task.yaml` 是之前编辑的配置文件。 - - {{< copyable "" >}} - - ```bash - » start-task ./task.yaml - ``` - - - 如果执行该命令后返回的结果如下，则表明任务已成功启动。 - - ```json - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.10.72:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.10.73:8262", - "msg": "" - } - ] - } - ``` - - - 如果任务启动失败，可根据返回结果的提示进行配置变更后执行 `start-task task.yaml` 命令重新启动任务。 - -## 第 5 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "" >}} - -```bash -» query-status -``` - -## 第 6 步：停止任务 - -如果不再需要进行数据同步，可以在 dmctl 内使用以下命令停止同步任务： - -{{< copyable "" >}} - -```bash -» stop-task test -``` - -其中的 `test` 是 `task.yaml` 配置文件中 `name` 配置项设置的任务名。 - -## 第 7 步：监控任务与查看日志 - -如果使用 DM-Ansible 部署 DM 集群时，正确部署了 Prometheus 与 Grafana，且 Grafana 的地址为 `172.16.10.71`，可在浏览器中打开 进入 Grafana，选择 DM 的 dashboard 即可查看 DM 相关监控项。 - -DM 在运行过程中，DM-worker, DM-master 及 dmctl 都会通过日志输出相关信息。各组件的日志目录如下： - -- DM-master 日志目录：通过 DM-master 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-master 节点的 `{ansible deploy}/log/dm-master.log`。 -- DM-worker 日志目录：通过 DM-worker 进程参数 `--log-file` 设置。如果使用 DM-Ansible 部署 DM，则日志目录位于 DM-worker 节点的 `{ansible deploy}/log/dm-worker.log`。 -- dmctl 日志目录：与其二进制文件目录相同。 diff --git a/v3.1/reference/tools/data-migration/dm-portal.md b/v3.1/reference/tools/data-migration/dm-portal.md deleted file mode 100644 index 27be786693fe..000000000000 --- a/v3.1/reference/tools/data-migration/dm-portal.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: DM Portal 简介 -category: reference ---- - -# DM Portal 简介 - -当前版本的 DM 提供了丰富多样的功能特性，包括 [Table routing](/v3.1/reference/tools/data-migration/features/overview.md#table-routing)，[Black & white table lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists)，[Binlog event filter](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 等。但这些功能特性同时也增加了用户使用 DM 的复杂度，尤其在编写 [DM 任务配置](/v3.1/reference/tools/data-migration/configure/task-configuration-file.md)的时候。 - -针对这个问题，DM 提供了一个精简的网页程序 DM Portal，能够帮助用户以可视化的方式去配置需要的同步任务，并且生成可以直接让 DM 直接执行的 `task.yaml` 文件。 - -## 功能描述 - -### 同步模式配置 - -支持 DM 的三种同步模式： - -- 全量同步 -- 增量同步 -- All（全量+增量） - -### 实例信息配置 - -支持配置库表同步路由方式，能够支持 DM 中分库分表合并的配置方式。 - -### binlog 过滤配置 - -支持对数据库、数据表配置 binlog event 过滤。 - -### 配置文件生成 - -支持配置文件创建，能够将配置文件下载到本地并且同时会在 dm-portal 服务器的 `/tmp/` 目录下自动创建。 - -### 使用限制 - -当前的 DM 配置可视化生成页面能够覆盖绝大部分的 DM 配置场景，但也有一定的使用限制： - -- 不支持 [Binlog event filter](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 的 SQL pattern 方式 -- 编辑功能不支持解析用户之前写的 `task.yaml` 文件，页面只能编辑由页面生成的 `task.yaml` 文件 -- 编辑功能不支持修改实例配置信息，如果用户需要调整实例配置，需要重新生成 `task.yaml` 文件 -- 页面的上游实例配置仅用于获取上游库表结构，DM-worker 里依旧需要配置对应的上游实例信息 -- 生成的 `task.yaml` 中，默认 mydumper-path 为 `./bin/mydumper`，如果实际使用其他路径，需要在生成的配置文件中进行手动修改。 - -## 部署使用 - -### Binary 部署 - -DM Portal 可以在 [dm-portal-latest-linux-amd64.tar.gz](https://download.pingcap.org/dm-portal-latest-linux-amd64.tar.gz) 下载，通过 `./dm-portal` 的命令即可直接启动。 - -* 如果在本地启动，浏览器访问 `127.0.0.1:8280` 即可使用。 -* 如果在服务器上启动，需要为服务器上配置访问代理。 - -### DM Ansible 部署 - -可以使用 DM Ansible 部署 DM Portal，具体部署方法参照[使用 DM Ansible 部署 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md)。 - -## 使用说明 - -### 新建规则 - -#### 功能描述 - -用于新建一个 `task.yaml` 文件，需要选择同步模式、配置上下游实例、配置库表路由，配置 binlog 过滤。 - -#### 操作步骤 - -登录 dm-portal 页面，点击**新建任务规则**。 - -### 基础信息配置 - -#### 功能描述 - -用于填写任务名称，以及选择任务类型。 - -#### 前置条件 - -已选择**新建同步规则**。 - -#### 操作步骤 - -1. 填写任务名称。 -2. 选择任务类型。 - -![DM Portal BasicConfig](/media/dm-portal-basicconfig.png) - -### 实例信息配置 - -#### 功能描述 - -用于配置上下游实例信息，包括 Host、Port、Username、Password。 - -#### 前置条件 - -已填写任务名称和选择任务类型。 - -#### 注意事项 - -如果任务类型选择**增量**或者 **All**，在配置上游实例信息时候，还需要配置 binlog-file 和 binlog-pos。 - -#### 操作步骤 - -1. 填写上游实例信息。 -2. 填写下游实例信息。 -3. 点击**下一步**。 - -![DM Portal InstanceConfig](/media/dm-portal-instanceconfig.png) - -### binlog 过滤配置 - -#### 功能描述 - -用于配置上游的 binlog 过滤，可以选择需要过滤的 DDL/DML，并且在数据库上配置的 filter 后会自动给其下的数据表继承。 - -#### 前置条件 - -已经配置好上下游实例信息并且连接验证没问题。 - -#### 注意事项 - -* binlog 过滤配置只能在上游实例处进行修改编辑，一旦数据库或者数据表被移动到下游实例后，就不可以进行修改编辑。 -* 在数据库上配置的 binlog 过滤会自动被其下的数据表继承。 - -#### 操作步骤 - -1. 点击需要配置的数据库或者数据表。 -2. 点击编辑按钮，选择需要过滤的 binlog 类型。 - -![DM Portal InstanceShow](/media/dm-portal-instanceshow.png) - -![DM Portal BinlogFilter 1](/media/dm-portal-binlogfilter-1.png) - -![DM Portal BinlogFilter 2](/media/dm-portal-binlogfilter-2.png) - -### 库表路由配置 - -#### 功能描述 - -可以选择需要同步的数据库和数据表，并且进行修改名称、合并库、合并表等操作。可以对上一步操作进行撤销，可以对库表路由配置进行全部重置。在完成任务配置后，DM Portal 会帮忙生成对应的 `task.yaml` 文件。 - -#### 前置条件 - -* 已经配置好需要的 binlog 过滤规则。 - -#### 注意事项 - -* 在合并库表操作的时候，不允许批量操作，只能逐一拖动。 -* 在合表库表操作的时候，只能对数据表进行拖动操作，不能对数据库进行数据库进行拖动操作。 - -#### 操作步骤 - -1. 在**上游实例**处，选择需要同步的数据库和数据表。 -2. 点击移动按钮，将需要同步的库表移动至**下游实例**处。 -3. 点击右键按钮，可以对库表进行改名操作。 -4. 选中需要操作的数据表，可以拖动至别的数据表图标上创建出合并表；可以拖动到数据库图标上移动至该库下；可以拖动到 target-instance 图标上移动到一个新的数据库下。 -5. 点击**完成**，自动下载 `task.yaml` 到本地，并且在 DM Portal 服务器上的 `/tmp/` 目录下自动创建一份 `task.yaml` 配置文件。 - -##### 移动同步库表 - -![DM Portal TableRoute 1](/media/dm-portal-tableroute-1.png) - -![DM Portal TableRoute 2](/media/dm-portal-tableroute-2.png) - -##### 右键修改库表名称 - -![DM Portal ChangeTableName](/media/dm-portal-changetablename.png) - -##### 合并数据表操作 - -![DM Portal MergeTable 1](/media/dm-portal-mergetable-1.png) - -![DM Portal MergeTable 2](/media/dm-portal-mergetable-2.png) - -##### 移动数据表至其他数据库 - -![DM Portal MoveToDB 1](/media/dm-portal-movetodb-1.png) - -![DM Portal MoveToDB 2](/media/dm-portal-movetodb-2.png) - -##### 移动数据表至新建默认数据库 - -![DM Portal MoveToNewDB 1](/media/dm-portal-movetonewdb-1.png) - -![DM Portal MoveToNewDB 2](/media/dm-portal-movetonewdb-2.png) - -##### 撤销本次操作 - -![DM Portal Revert](/media/dm-portal-revert.png) - -##### 清空下游实例 - -![DM Portal Reset](/media/dm-portal-reset.png) - -##### 完成并下载 - -![DM Portal GenerateConfig](/media/dm-portal-generateconfig.png) - -### 编辑规则 - -#### 功能描述 - -可以将之前创建的 `task.yaml` 上传后，解析出来之前的填写的配置信息，对部分配置进行修改。 - -#### 前置条件 - -* 已经创建出 `task.yaml` 文件。 -* 非 DM Portal 创建出来的 `task.yaml` 文件不可使用。 - -#### 注意事项 - -* 不允许修改实例配置信息 - -#### 操作步骤 - -1. 在首页，点击**编辑同步规则**。 -2. 选择上传 `task.yaml` 文件。 -3. 解析成功后，页面会自动跳转。 - -![DM Portal EditConfig](/media/dm-portal-editconfig.png) - -![DM Portal UploadConfig](/media/dm-portal-uploadconfig.png) diff --git a/v3.1/reference/tools/data-migration/dm-upgrade.md b/v3.1/reference/tools/data-migration/dm-upgrade.md deleted file mode 100644 index 9c559b7a195f..000000000000 --- a/v3.1/reference/tools/data-migration/dm-upgrade.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: DM 版本升级 -category: reference ---- - -# DM 版本升级 - -本文档主要介绍各 DM (Data Migration) 版本间的升级操作步骤。 - -> **注意：** -> -> - 若无特殊说明，各版本的升级操作均为从前一个有升级指引的版本向当前版本升级。 -> - 若无特殊说明，各升级操作示例均假定已经下载了对应版本的 DM 和 DM-Ansible 且 DM binary 存在于 DM-Ansible 的相应目录中（下载 DM binary 可以参考[更新组件版本](/v3.1/reference/tools/data-migration/cluster-operations.md#更新组件版本)）。 -> - 若无特殊说明，各升级操作示例均假定升级前已停止所有同步任务，升级完成后手动重新启动所有同步任务。 -> - 以下版本升级指引逆序展示。 - -## 升级到 v1.0.3 - -### 版本信息 - -```bash -Release Version: v1.0.3 -Git Commit Hash: 41426af6cffcff9a325697a3bdebeadc9baa8aa6 -Git Branch: release-1.0 -UTC Build Time: 2019-12-13 07:04:53 -Go Version: go version go1.13 linux/amd64 -``` - -### 主要变更 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.3` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.3 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.2 - -### 版本信息 - -```bash -Release Version: v1.0.2 -Git Commit Hash: affc6546c0d9810b0630e85502d60ed5c800bf25 -Git Branch: release-1.0 -UTC Build Time: 2019-10-30 05:08:50 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 支持自动为 DM-worker 生成部分配置项，减少人工配置成本 -- 支持自动生成 mydumper 库表参数，减少人工配置成本 -- 优化 `query-status` 默认输出，突出重点信息 -- 直接管理到下游的 DB 连接而不是使用内置连接池，优化 SQL 错误处理与重试 -- 修复 DM-worker 进程启动时、执行 DML 失败时可能 panic 的 bug -- 修复执行 sharding DDL（如 ADD INDEX）超时后可能造成后续 sharding DDL 无法正确协调的 bug -- 修复了有部分 DM-worker 不可访问时无法 `start-task` 的 bug -- 完善了对 1105 错误的自动重试策略 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible，确认 `inventory.ini` 文件中 `dm_version = v1.0.2` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.2 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.1 - -### 版本信息 - -```bash -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 修复某些情况下 DM 会频繁重建数据库连接的问题 -- 修复使用 `query-status` 时潜在的 panic 问题 - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.1` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0.1 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-10-geb2889c9 (1.0 GA) - -### 版本信息 - -```bash -Release Version: v1.0.0-10-geb2889c9 -Git Commit Hash: eb2889c9dcfbff6653be9c8720a32998b4627db9 -Git Branch: release-1.0 -UTC Build Time: 2019-09-06 03:18:48 -Go Version: go version go1.12 linux/amd64 -``` - -### 主要变更 - -- 常见的异常场景支持自动尝试恢复同步任务 -- 提升 DDL 语法兼容性 -- 修复上游数据库连接异常时可能丢失数据的 bug - -### 升级操作示例 - -1. 下载新版本 DM-Ansible, 确认 `inventory.ini` 文件中 `dm_version = v1.0.0` -2. 执行 `ansible-playbook local_prepare.yml` 下载新的 DM binary 到本地 -3. 执行 `ansible-playbook rolling_update.yml` 滚动升级 DM 集群组件 -4. 执行 `ansible-playbook rolling_update_monitor.yml` 滚动升级 DM 监控组件 - -> **注意：** -> -> 更新至 DM 1.0 GA 版本时，需要确保 DM 所有组件 (dmctl/DM-master/DM-worker) 同时升级。不支持部分组件升级使用。 - -## 升级到 v1.0.0-rc.1-12-gaa39ff9 - -### 版本信息 - -```bash -Release Version: v1.0.0-rc.1-12-gaa39ff9 -Git Commit Hash: aa39ff981dfb3e8c0fa4180127246b253604cc34 -Git Branch: dm-master -UTC Build Time: 2019-07-24 02:26:08 -Go Version: go version go1.11.2 linux/amd64 -``` - -### 主要变更 - -从此版本开始，将对所有的配置进行严格检查，遇到无法识别的配置会报错，以确保用户始终准确地了解自己的配置。 - -### 升级操作示例 - -启动 DM-master 或 DM-worker 前，必须确保已经删除废弃的配置信息，且没有多余的配置项，否则会启动失败。可根据失败信息删除多余的配置。 -可能遗留的废弃配置： - -- `dm-worker.toml` 中的 `meta-file` -- `task.yaml` 中的 `mysql-instances` 中的 `server-id` diff --git a/v3.1/reference/tools/data-migration/dm-worker-intro.md b/v3.1/reference/tools/data-migration/dm-worker-intro.md deleted file mode 100644 index 2cdeb0c22b7a..000000000000 --- a/v3.1/reference/tools/data-migration/dm-worker-intro.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: DM-worker 简介 -category: reference ---- - -# DM-worker 简介 - -DM-worker 是 DM (Data Migration) 的一个组件，负责执行具体的数据同步任务。 - -其主要功能如下： - -- 注册为一台 MySQL 或 MariaDB 服务器的 slave。 -- 读取 MySQL 或 MariaDB 的 binlog event，并将这些 event 持久化保存在本地 (relay log)。 -- 单个 DM-worker 支持同步一个 MySQL 或 MariaDB 实例的数据到下游的多个 TiDB 实例。 -- 多个 DM-Worker 支持同步多个 MySQL 或 MariaDB 实例的数据到下游的一个 TiDB 实例。 - -## DM-worker 处理单元 - -DM-worker 任务包含如下多个逻辑处理单元。 - -### Relay log - -Relay log 持久化保存从上游 MySQL 或 MariaDB 读取的 binlog，并对 binlog replication 处理单元提供读取 binlog event 的功能。 - -其原理和功能与 MySQL slave relay log 类似，详见 [Slave Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html)。 - -### Dumper - -Dumper 从上游 MySQL 或 MariaDB 导出全量数据到本地磁盘。 - -### Loader - -Loader 读取 dumper 处理单元的数据文件，然后加载到下游 TiDB。 - -### Binlog replication/Syncer - -Binlog replication/Syncer 读取 relay log 处理单元的 binlog event，将这些 event 转化为 SQL 语句，再将这些 SQL 语句应用到下游 TiDB。 - -## DM-worker 所需权限 - -本小节主要介绍使用 DM-worker 时所需的上下游数据库用户权限以及各处理单元所需的用户权限。 - -### 上游数据库用户权限 - -上游数据库 (MySQL/MariaDB) 用户必须拥有以下权限： - -| 权限 | 作用域 | -|:----|:----| -| `SELECT` | Tables | -| `RELOAD` | Global | -| `REPLICATION SLAVE` | Global | -| `REPLICATION CLIENT` | Global | - -如果要同步 `db1` 的数据到 TiDB，可执行如下的 `GRANT` 语句： - -{{< copyable "sql" >}} - -```sql -GRANT RELOAD,REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'your_user'@'your_wildcard_of_host' -GRANT SELECT ON db1.* TO 'your_user'@'your_wildcard_of_host'; -``` - -如果还要同步其他数据库的数据到 TiDB, 请确保已赋予这些库跟 `db1` 一样的权限。 - -### 下游数据库用户权限 - -下游数据库 (TiDB) 用户必须拥有以下权限： - -| 权限 | 作用域 | -|:----|:----| -| `SELECT` | Tables | -| `INSERT` | Tables | -| `UPDATE`| Tables | -| `DELETE` | Tables | -| `CREATE` | Databases，tables | -| `DROP` | Databases，tables | -| `ALTER` | Tables | -| `INDEX` | Tables | - -对要执行同步操作的数据库或表执行下面的 `GRANT` 语句： - -{{< copyable "sql" >}} - -```sql -GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,INDEX ON db.table TO 'your_user'@'your_wildcard_of_host'; -``` - -### 处理单元所需的最小权限 - -| 处理单元 | 最小上游 (MySQL/MariaDB) 权限 | 最小下游 (TiDB) 权限 | 最小系统权限 | -|:----|:--------------------|:------------|:----| -| Relay log | `REPLICATION SLAVE` (读取 binlog）
`REPLICATION CLIENT` (`show master status`, `show slave status`) | 无 | 本地读/写磁盘 | -| Dumper | `SELECT`
`RELOAD`（获取读锁将表数据刷到磁盘，进行一些操作后，再释放读锁对表进行解锁）| 无 | 本地写磁盘 | -| Loader | 无 | `SELECT`（查询 checkpoint 历史）
`CREATE`（创建数据库或表）
`DELETE`（删除 checkpoint）
`INSERT`（插入 dump 数据）| 读/写本地文件 | -| Binlog replication | `REPLICATION SLAVE`（读 binlog）
`REPLICATION CLIENT` (`show master status`, `show slave status`) | `SELECT`（显示索引和列）
`INSERT` (DML)
`UPDATE` (DML)
`DELETE` (DML)
`CREATE`（创建数据库或表）
`DROP`（删除数据库或表）
`ALTER`（修改表）
`INDEX`（创建或删除索引）| 本地读/写磁盘 | - -> **注意：** -> -> 这些权限并非一成不变。随着需求改变，这些权限也可能会改变。 diff --git a/v3.1/reference/tools/data-migration/faq.md b/v3.1/reference/tools/data-migration/faq.md deleted file mode 100644 index 39ec44e0bfd3..000000000000 --- a/v3.1/reference/tools/data-migration/faq.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Data Migration 常见问题 -category: FAQ ---- - -# Data Migration 常见问题 - -## DM 是否支持同步阿里 RDS 以及其他云数据库的数据？ - -DM 仅支持解析标准版本的 MySQL/MariaDB 的 binlog，对于阿里云 RDS 以及其他云数据库没有进行过测试，如果确认其 binlog 为标准格式，则可以支持。 - -## task 配置中的黑白名单的正则表达式是否支持`非获取匹配`（?!）？ - -目前不支持，DM 仅支持 golang 标准库的正则，可以通过 [re2-syntax](https://github.com/google/re2/wiki/Syntax) 了解 golang 支持的正则表达式。 - -## 如果在上游执行的一个 statement 包含多个 DDL 操作，DM 是否支持同步？ - -DM 会尝试将包含多个 DDL 变更操作的单条语句拆分成只包含一个 DDL 操作的多条语句，但是可能没有覆盖所有的场景。建议在上游执行的一条 statement 中只包含一个 DDL 操作，或者在测试环境中验证一下，如果不支持，可以给 DM 提 [issue](https://github.com/pingcap/dm/issues)。 - -## 如何处理不兼容的 DDL 语句？ - -你需要使用 dmctl 手动处理 TiDB 不兼容的 DDL 语句（包括手动跳过该 DDL 语句或使用用户指定的 DDL 语句替换原 DDL 语句，详见[跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句](/v3.1/reference/tools/data-migration/skip-replace-sqls.md)）。 - -> **注意：** -> -> TiDB 目前并不兼容 MySQL 支持的所有 DDL 语句。 - -## 如何重置数据同步任务？ - -在以下情况中，你需要重置整个数据同步任务： - -- 上游数据库中人为执行了 `RESET MASTER`，造成 relay log 同步出错 - -- relay log 或上游 binlog event 损坏或者丢失 - -此时，relay 处理单元通常会发生错误而退出，且无法优雅地自动恢复，因此需要通过手动方式恢复数据同步： - -1. 使用 `stop-task` 命令停止当前正在运行的所有同步任务。 - -2. 使用 Ansible [停止整个 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md#第-10-步关闭-dm-集群)。 - -3. 手动清理掉与 binlog event 被重置的 MySQL master 相对应的 DM-worker 的 relay log 目录。 - - - 如果是使用 Ansible 部署，relay log 目录即 `/relay_log` 目录。 - - 如果是使用二进制文件手动部署，relay log 目录即 relay-dir 参数设置的目录。 - -4. 清理掉下游已同步的数据。 - -5. 使用 Ansible [启动整个 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md#第-9-步部署-dm-集群)。 - -6. 以新的任务名重启数据同步任务，或设置 `remove-meta` 为 `true` 且 `task-mode` 为 `all`。 diff --git a/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md b/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md deleted file mode 100644 index f152eeee4ddd..000000000000 --- a/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md +++ /dev/null @@ -1,540 +0,0 @@ ---- -title: 手动处理 Sharding DDL Lock -category: reference ---- - -# 手动处理 Sharding DDL Lock - -DM (Data Migration) 使用 sharding DDL lock 来确保分库分表的 DDL 操作可以正确执行。绝大多数情况下，该锁定机制可自动完成；但在部分异常情况发生时，需要使用 `unlock-ddl-lock`/`break-ddl-lock` 手动处理异常的 DDL lock。 - -> **注意：** -> -> - 不要轻易使用 `unlock-ddl-lock`/`break-ddl-lock` 命令，除非完全明确当前场景下使用这些命令可能会造成的影响，并能接受这些影响。 -> - 在手动处理异常的 DDL lock 前，请确保已经了解 DM 的[分库分表合并同步原理](/v3.1/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)。 - -## 命令介绍 - -### `show-ddl-locks` - -该命令用于查询当前 DM-master 上存在的 DDL lock 信息。 - -#### 命令示例 - -{{< copyable "" >}} - -```bash -show-ddl-locks [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，查询所有 DM-worker 相关的 lock 信息；指定时，仅查询与这组 DM-worker 相关的 lock 信息，可重复多次指定 - -+ `task-name`： - - 非 flag 参数，string，可选 - - 不指定时，查询与所有任务相关的 lock 信息；指定时，仅查询特定任务相关的 lock 信息 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -» show-ddl-locks test -``` - -``` -{ - "result": true, # 查询 lock 操作本身是否成功 - "msg": "", # 查询 lock 操作失败时的原因或其它描述信息（如不存在任务 lock） - "locks": [ # DM-master 上存在的 lock 信息列表 - { - "ID": "test-`shard_db`.`shard_table`", # lock 的 ID 标识，当前由任务名与 DDL 对应的 schema/table 信息组成 - "task": "test", # lock 所属的任务名 - "owner": "127.0.0.1:8262", # lock 的 owner（第一个遇到该 DDL 的 DM-worker） - "DDLs": [ # lock 对应的 DDL 列表 - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;" - ], - "synced": [ # 已经收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8262" - ], - "unsynced": [ # 尚未收到对应 MySQL 实例内所有分表 DDL 的 DM-worker 列表 - "127.0.0.1:8263" - ] - } - ] -} -``` - -### `unlock-ddl-lock` - -该命令用于主动请求 DM-master 解除指定的 DDL lock，包括的操作：请求 owner 执行 DDL 操作，请求其他非 owner 的 DM-worker 跳过 DDL 操作，移除 DM-master 上的 lock 信息。 - -#### 命令示例 - -{{< copyable "" >}} - -```bash -» unlock-ddl-lock [--worker=127.0.0.1:8262] [--owner] [--force-remove] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选 - - 不指定时，对所有已经在等待该 lock 的 DM-worker 发起跳过 DDL 操作请求；指定时，仅对这组 DM-worker 发起跳过 DDL 操作请求，可重复多次指定 - -+ `owner`： - - flag 参数，string，`--owner`，可选 - - 不指定时，请求默认的 owner（`show-ddl-locks` 返回结果中的 `owner`）执行 DDL 操作；指定时，请求该 DM-worker（替代默认的 owner）执行 DDL 操作 - -+ `force-remove`： - - flag 参数，boolean，`--force-remove`，可选 - - 不指定时，仅在 owner 执行 DDL 成功时移除 lock 信息；指定时，即使 owner 执行 DDL 失败也强制移除 lock 信息（此后将无法再次查询或操作该 lock） - -+ `lock-ID`： - - 非 flag 参数，string，必选 - - 指定需要执行 unlock 操作的 DDL lock ID（即 `show-ddl-locks` 返回结果中的 `ID`） - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -» unlock-ddl-lock test-`shard_db`.`shard_table` -``` - -``` -{ - "result": true, # unlock lock 操作是否成功 - "msg": "", # unlock lock 操作失败时的原因 - "workers": [ # 各 DM-worker 执行/跳过 DDL 操作结果信息列表 - { - "result": true, # 该 DM-worker 执行/跳过 DDL 操作是否成功 - "worker": "127.0.0.1:8262", # DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker 执行/跳过 DDL 失败时的原因 - } - ] -} -``` - -### break-ddl-lock - -该命令用于主动请求 DM-worker 强制打破当前正在等待 unlock 的 DDL lock，包括请求 DM-worker 执行或跳过 DDL 操作、移除该 DM-worker 上的 DDL lock 信息。 - -#### 命令示例 - -{{< copyable "" >}} - -```bash -» break-ddl-lock <--worker=127.0.0.1:8262> [--remove-id] [--exec] [--skip] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，必选 - - 指定需要执行 break 操作的 DM-worker - -+ `remove-id`：已废弃 - -+ `exec`： - - flag 参数，boolean，`--exec`，可选 - - 不可与 `--skip` 参数同时指定 - - 指定时，请求该 DM-worker 执行（execute）当前 lock 对应的 DDL - -+ `skip`： - - flag 参数，boolean，`--skip`，可选 - - 不可与 `--exec` 参数同时指定 - - 指定时，请求该 DM-worker 跳过（skip）当前 lock 对应的 DDL - -+ `task-name`： - - 非 flag 参数，string，必选 - - 指定要执行 break 操作的 lock 所在的 task 名称（要查看各 task 上是否存在 lock，可通过 [query-status](/v3.1/reference/tools/data-migration/query-status.md) 获得） - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -» break-ddl-lock -w 127.0.0.1:8262 --exec test -``` - -``` -{ - "result": true, # break lock 操作是否成功 - "msg": "", # break lock 操作失败时的原因 - "workers": [ # 执行 break lock 操作的 DM-worker 列表（当前单次操作仅支持对一个 DM-worker 执行 break lock） - { - "result": false, # 该 DM-worker break lock 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 地址 (DM-worker ID) - "msg": "" # DM-worker break lock 失败时的原因 - } - ] -} -``` - -## 支持场景 - -目前，使用 `unlock-ddl-lock`/`break-ddl-lock` 命令仅支持处理以下三种 sharding DDL lock 异常情况。 - -### 场景一：部分 DM-worker 下线 - -#### Lock 异常原因 - -在 DM-master 尝试自动 unlock sharding DDL lock 之前，需要等待所有 DM-worker 的 sharding DDL events 全部到达（详见[分库分表合并同步原理](/v3.1/reference/tools/data-migration/usage-scenarios/shard-merge.md#实现原理)）。如果 sharding DDL 已经在同步过程中，且有部分 DM-worker 下线，并且不再计划重启它们（按业务需求移除了这部分 DM-worker），则会由于永远无法等齐所有的 DDL 而造成 lock 无法自动 unlock。 - -#### 手动处理示例 - -假设上游有 MySQL-1 和 MySQL-2 两个实例，其中 MySQL-1 中有 `shard_db_1`.`shard_table_1` 和 `shard_db_1`.`shard_table_2` 两个表，MySQL-2 中有 `shard_db_2`.`shard_table_1` 和 `shard_db_2`.`shard_table_2` 两个表。现在需要将这 4 个表合并后同步到下游 TiDB 的 `shard_db`.`shard_table` 表中。 - -初始表结构如下： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE shard_db_1.shard_table_1; -``` - -``` -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -上游分表将执行以下 DDL 语句变更表结构： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE shard_db_*.shard_table_* ADD COLUMN c2 INT; -``` - -MySQL 及 DM 操作与处理流程如下： - -1. MySQL-1 对应的 DM-worker-1 的两个分表执行了对应的 DDL 操作进行表结构变更。 - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE shard_db_1.shard_table_1 ADD COLUMN c2 INT; - ``` - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE shard_db_1.shard_table_2 ADD COLUMN c2 INT; - ``` - -2. DM-worker-1 接受到两个分表的 DDL 之后，将对应 MySQL-1 相关的 DDL 信息发送给 DM-master，DM-master 创建相应的 DDL lock。 -3. 使用 `show-ddl-lock` 查看当前的 DDL lock 信息。 - - {{< copyable "" >}} - - ```bash - » show-ddl-locks test - ``` - - ``` - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8262", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8262" - ], - "unsynced": [ - "127.0.0.1:8263" - ] - } - ] - } - ``` - -4. 由于业务需要，DM-worker-2 对应的 MySQL-2 的数据不再需要同步到下游 TiDB，对 DM-worker-2 执行了下线处理。 -5. DM-master 上 ID 为 ```test-`shard_db`.`shard_table` ``` 的 lock 无法等到 DM-worker-2 的 DDL 操作信息。 - - `show-ddl-locks` 返回的 `unsynced` 中一直包含 DM-worker-2 的信息（`127.0.0.1:8263`）。 - -6. 使用 `unlock-dll-lock` 来请求 DM-master 主动 unlock 该 DDL lock。 - - - 如果 DDL lock 的 owner 也已经下线，可以使用 `--owner` 参数指定其他 DM-worker 作为新 owner 来执行 DDL。 - - 当存在任意 DM-worker 报错时，`result` 将为 `false`，此时请仔细检查各 DM-worker 的错误是否是预期可接受的。 - - 已下线的 DM-worker 会返回 `rpc error: code = Unavailable` 错误属于预期行为，可以忽略。 - - 如果其它未下线的 DM-worker 返回错误，则需要根据情况额外处理。 - - {{< copyable "" >}} - - ```bash - » unlock-ddl-lock test-`shard_db`.`shard_table` - ``` - - ``` - { - "result": false, - "msg": "github.com/pingcap/tidb-enterprise-tools/dm/master/server.go:1472: DDL lock test-`shard_db`.`shard_table` owner ExecuteDDL successfully, so DDL lock removed. but some dm-workers ExecuteDDL fail, you should to handle dm-worker directly", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - }, - { - "result": false, - "worker": "127.0.0.1:8263", - "msg": "rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = \"transport: Error while dialing dial tcp 127.0.0.1:8263: connect: connection refused\"" - } - ] - } - ``` - -7. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 - - ```bash - show-ddl-locks test - ``` - - ``` - { - "result": true, - "msg": "no DDL lock exists", - "locks": [ - ] - } - ``` - -8. 查看下游 TiDB 中的表结构是否变更成功。 - - {{< copyable "sql" >}} - - ```sql - SHOW CREATE TABLE shard_db.shard_table; - ``` - - ``` - +-------------+--------------------------------------------------+ - | Table | Create Table | - +-------------+--------------------------------------------------+ - | shard_table | CREATE TABLE `shard_table` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 COLLATE=latin1_bin | - +-------------+--------------------------------------------------+ - ``` - -9. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -使用 `unlock-ddl-lock` 手动执行 unlock 操作后，由于该任务的配置信息中仍然包含了已下线的 DM-worker，如果不进行处理，则当下次 sharding DDL 到达时，仍会出现 lock 无法自动完成同步的情况。 - -因此，在手动解锁 DDL lock 后，需要再执行以下操作： - -1. 使用 `stop-task` 停止运行中的任务。 -2. 更新任务配置文件，将已下线 DM-worker 对应的信息从配置文件中移除。 -3. 使用 `start-task` 及新任务配置文件重新启动任务。 - -> **注意：** -> -> 在 `unlock-ddl-lock` 之后，如果已下线的 DM-worker 重新上线并尝试对其中的分表进行数据同步，则会由于数据与下游的表结构不匹配而发生错误。 - -### 场景二：unlock 过程中部分 DM-worker 重启 - -#### Lock 异常原因 - -在 DM-master 收到所有 DM-worker 的 DDL 信息后，执行自动 unlock DDL lock 的操作主要包括以下步骤： - -1. 请求 lock owner 执行 DDL 操作，并更新对应分表的 checkpoint。 -2. 在 owner 执行 DDL 操作成功后，移除 DM-master 上保存的 DDL lock 信息。 -3. 在 owner 执行 DDL 操作成功后，请求其他所有 DM-worker 跳过 DDL 操作并更新对应分表的 checkpoint。 - -上述 unlock DDL lock 的操作不是原子的，当 owner 执行 DDL 操作成功后，请求其他 DM-worker 跳过 DDL 操作时，如果该 DM-worker 发生了重启，则会造成该 DM-worker 跳过 DDL 操作失败。 - -此时 DM-master 上的 lock 信息被移除，但该 DM-worker 重启后将尝试继续重新同步该 DDL 操作。但是，由于其他 DM-worker（包括原 owner）已经同步完该 DDL 操作，并已经在继续后续的同步，该 DM-worker 将永远无法等待该 DDL 操作对应 lock 的自动 unlock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -当在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息；但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于 DM-worker-2 发生了重启而跳过 DDL 操作失败。 - -DM-worker-2 重启后，将尝试重新同步重启前已经在等待的 DDL lock。此时将在 DM-master 上创建一个新的 lock，并且该 DM-worker 将成为 lock 的 owner（其他 DM-worker 此时已经执行或跳过 DDL 操作并在进行后续同步）。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上存在该 DDL 操作对应的 lock。 - - 应该仅有该重启的 DM-worker（`127.0.0.1:8263`）处于 `syned` 状态： - - {{< copyable "" >}} - - ```bash - » show-ddl-locks - ``` - - ``` - { - "result": true, - "msg": "", - "locks": [ - { - "ID": "test-`shard_db`.`shard_table`", - "task": "test", - "owner": "127.0.0.1:8263", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "synced": [ - "127.0.0.1:8263" - ], - "unsynced": [ - "127.0.0.1:8262" - ] - } - ] - } - ``` - -2. 使用 `unlock-ddl-lock` 请求 DM-master unlock 该 lock。 - - - 使用 `--worker` 参数限定操作仅针对该重启的 DM-worker（`127.0.0.1:8263`）。 - - Lock 过程中该 DM-worker 会尝试再次向下游执行该 DDL 操作（重启前的原 owner 已向下游执行过该 DDL 操作），需要确保该 DDL 操作可被多次执行。 - - {{< copyable "" >}} - - ```bash - » unlock-ddl-lock --worker=127.0.0.1:8263 test-`shard_db`.`shard_table` - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -3. 使用 `show-ddl-locks` 确认 DDL lock 是否被成功 unlock。 -4. 使用 `query-status` 确认同步任务是否正常。 - -#### 手动处理后的影响 - -手动 unlock sharding DDL lock 后，后续的 sharding DDL 将可以自动正常同步。 - -### 场景三：unlock 过程中部分 DM-worker 临时不可达 - -#### Lock 异常原因 - -与 [unlock 过程中部分 DM-worker 重启](#场景二unlock-过程中部分-dm-worker-重启) 造成 lock 异常的原因类似。当请求 DM-worker 跳过 DDL 操作时，如果该 DM-worker 临时不可达，则会造成该 DM-worker 跳过 DDL 操作失败。此时 DM-master 上的 lock 信息被移除，但该 DM-worker 将处于等待一个不再存在的 DDL lock 的状态。 - -场景三与[场景二](#场景二unlock-过程中部分-dm-worker-重启)的区别在于，场景三中 DM-master 没有 lock，而场景二中 DM-master 有一个新的 lock。 - -#### 手动处理示例 - -仍然假设是 [部分 DM-worker 下线](#场景一部分-dm-worker-下线) 示例中的上下游表结构及合表同步需求。 - -在 DM-master 自动执行 unlock 操作的过程中，owner (DM-worker-1) 成功执行了 DDL 操作且开始继续进行后续同步，并移除了 DM-master 上的 DDL lock 信息，但在请求 DM-worker-2 跳过 DDL 操作的过程中，由于网络原因等临时不可达而跳过 DDL 操作失败。 - -处理流程如下： - -1. 使用 `show-ddl-locks` 确认 DM-master 上不再存在该 DDL 操作对应的 lock。 -2. 使用 `query-status` 确认 DM-worker 仍在等待 lock 同步。 - - {{< copyable "" >}} - - ```bash - » query-status test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - ... - { - ... - "worker": "127.0.0.1:8263", - "subTaskStatus": [ - { - ... - "unresolvedDDLLockID": "test-`shard_db`.`shard_table`", - "sync": { - ... - "blockingDDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "unresolvedGroups": [ - { - "target": "`shard_db`.`shard_table`", - "DDLs": [ - "USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` ADD COLUMN `c2` int(11);" - ], - "firstPos": "(mysql-bin|000001.000003, 1752)", - "synced": [ - "`shard_db_2`.`shard_table_1`", - "`shard_db_2`.`shard_table_2`" - ], - "unsynced": [ - ] - } - ], - "synced": false - } - } - ] - ... - } - ] - } - ``` - -3. 使用 `break-ddl-lock` 请求强制 break 该 DM-worker 当前正在等待的 DDL lock。 - - 由于 owner 已经向下游执行了 DDL 操作，因此在 break 时使用 `--skip` 参数。 - - {{< copyable "" >}} - - ```bash - » break-ddl-lock --worker=127.0.0.1:8263 --skip test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8263", - "msg": "" - } - ] - } - ``` - -4. 使用 `query-status` 确认同步任务是否正常且不再处于等待 lock 的状态。 - -#### 手动处理后的影响 - -手动强制 break lock 后，后续 sharding DDL 将可以自动正常同步。 diff --git a/v3.1/reference/tools/data-migration/features/overview.md b/v3.1/reference/tools/data-migration/features/overview.md deleted file mode 100644 index 87c9fa9e2001..000000000000 --- a/v3.1/reference/tools/data-migration/features/overview.md +++ /dev/null @@ -1,529 +0,0 @@ ---- -title: 数据同步功能 -summary: DM 提供的功能及其配置介绍 -category: reference ---- - -# 数据同步功能 - -本文将详细介绍 DM 提供的数据同步功能，以及相关的配置选项。 - -## Table routing - -Table routing 提供将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的功能。 - -> **注意：** -> -> - 不支持对同一个表设置多个不同的路由规则。 -> - Schema 的匹配规则需要单独设置，用来同步 `create/drop schema xx`，例如下面[参数配置](#参数配置)中的 rule-2。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -routes: - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -### 参数解释 - -将根据 [`schema-pattern`/`table-pattern`](/v3.1/reference/tools/data-migration/table-selector.md) 匹配上该规则的上游 MySQL/MariaDB 实例的表同步到下游的 `target-schema`/`target-table`。 - -### 使用示例 - -下面展示了三个不同场景下的配置示例。 - -#### 分库分表合并 - -假设存在分库分表场景，需要将上游两个 MySQL 实例的表 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的一张表 `test`.`t`。 - -为了同步到下游实例的表 `test`.`t` 需要创建两个 table routing 规则： - -- `rule-1` 用来同步匹配上 `schema-pattern: "test_*"` 和 `table-pattern: "t_*"` 的表的 DML/DDL 语句到下游的 `test`.`t`。 -- `rule-2` 用来同步匹配上 `schema-pattern: "test_*"` 的库的 DDL 语句，例如 `create/drop schema xx`。 - -> **注意：** -> -> - 如果下游 TiDB `schema: test` 已经存在， 并且不会被删除，则可以省略 `rule-2`。 -> - 如果下游 TiDB `schema: test` 不存在，只设置了 `rule_1`，则同步会报错 `schema test doesn't exist`。 - -{{< copyable "" >}} - -```yaml - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 分库合并 - -假设存在分库场景，将上游两个 MySQL 实例 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t_{1,2,3...}`，创建一条路由规则即可： - -{{< copyable "" >}} - -```yaml - rule-1: - schema-pattern: "test_*" - target-schema: "test" -``` - -#### 错误的 table routing - -假设存在下面两个路由规则，`test_1_bak`.`t_1_bak` 可以匹配上 `rule-1` 和 `rule-2`，违反 table 路由的限制而报错。 - -{{< copyable "" >}} - -```yaml - rule-0: - schema-pattern: "test_*" - target-schema: "test" - rule-1: - schema-pattern: "test_*" - table-pattern: "t_*" - target-schema: "test" - target-table: "t" - rule-2: - schema-pattern: "test_1_bak" - table-pattern: "t_1_bak" - target-schema: "test" - target-table: "t_bak" -``` - -## Black & white table lists - -上游数据库实例表的黑白名单过滤规则，可以用来过滤或者只同步某些 `database/table` 的所有操作。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -black-white-list: - rule-1: - do-dbs: ["~^test.*"] # 以 ~ 字符开头，表示规则是正则表达式 -​ ignore-dbs: ["mysql"] - do-tables: - - db-name: "~^test.*" - tbl-name: "~^t.*" - - db-name: "test" - tbl-name: "t" - ignore-tables: - - db-name: "test" - tbl-name: "log" -``` - -### 参数解释 - -- `do-dbs`：要同步的库的白名单，类似于 MySQL 中的 [`replicate-do-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-db)。 -- `ignore-dbs`：要同步的库的黑名单，类似于 MySQL 中的 [`replicate-ignore-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-db)。 -- `do-tables`：要同步的表的白名单，类似于 MySQL 中的 [`replicate-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-do-table)。 -- `ignore-tables`：要同步的表的黑名单，类似于 MySQL 中的 [`replicate-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-ignore-table)。 - -以上参数值以 `~` 开头时均支持使用[正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)来匹配库名、表名。 - -### 过滤规则 - -`do-dbs` 与 `ignore-dbs` 对应的过滤规则与 MySQL 中的 [Evaluation of Database-Level Replication and Binary Logging Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-db-options.html) 类似，`do-tables` 与 `ignore-tables` 对应的过滤规则与 MySQL 中的 [Evaluation of Table-Level Replication Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-table-options.html) 类似。 - -> **注意：** -> -> DM 中黑白名单过滤规则与 MySQL 中相应规则存在以下区别： -> -> - MySQL 中存在 [`replicate-wild-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-do-table) 与 [`replicate-wild-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-slave.html#option_mysqld_replicate-wild-ignore-table) 用于支持通配符，DM 中各配置参数直接支持以 `~` 字符开头的正则表达式。 -> - DM 当前只支持 `ROW` 格式的 binlog，不支持 `STATEMENT`/`MIXED` 格式的 binlog，因此应与 MySQL 中 `ROW` 格式下的规则对应。 -> - 对于 DDL，MySQL 仅依据默认的 database 名称（`USE` 语句显式指定的 database）进行判断，而 DM 优先依据 DDL 中的 database 名称部分进行判断，并当 DDL 中不包含 database 名称时再依据 `USE` 部分进行判断。假设需要判断的 SQL 为 `USE test_db_2; CREATE TABLE test_db_1.test_table (c1 INT PRIMARY KEY)`，且 MySQL 配置了 `replicate-do-db=test_db_1`、DM 配置了 `do-dbs: ["test_db_1"]`，则对于 MySQL 该规则不会生效，而对于 DM 该规则会生效。 - -判断 table `test`.`t` 是否应该被过滤的过滤流程如下： - -1. 首先 **schema 过滤判断** - - - 如果 `do-dbs` 不为空，判断 `do-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则进入 **table 过滤判断**。 - - 如果不存在，则过滤 `test`.`t`。 - - - 如果 `do-dbs` 为空并且 `ignore-dbs` 不为空，判断 `ignore-dbs` 中是否存在一个匹配的 schema。 - - - 如果存在，则过滤 `test`.`t`。 - - 如果不存在，则进入 **table 过滤判断**。 - - - 如果 `do-dbs` 和 `ignore-dbs` 都为空，则进入 **table 过滤判断**。 - -2. 进行 **table 过滤判断** - - 1. 如果 `do-tables` 不为空，判断 `do-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则同步 `test`.`t`。 - - 如果不存在，则过滤 `test`.`t`。 - - 2. 如果 `ignore-tables` 不为空，判断 `ignore-tables` 中是否存在一个匹配的 table。 - - - 如果存在，则过滤 `test`.`t`. - - 如果不存在，则同步 `test`.`t`。 - - 3. 如果 `do-tables` 和 `ignore-tables` 都为空，则同步 `test`.`t`。 - -> **注意：** -> -> 判断 schema `test` 是否被过滤，只进行 **schema 过滤判断** - -### 使用示例 - -假设上游 MySQL 实例包含以下表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -``` - -配置如下： - -{{< copyable "" >}} - -```yaml -black-white-list: - bw-rule: - do-dbs: ["forum_backup_2018", "forum"] - ignore-dbs: ["~^forum_backup_"] - do-tables: - - db-name: "logs" - tbl-name: "~_2018$" - - db-name: "~^forum.*" -​ tbl-name: "messages" - ignore-tables: - - db-name: "~.*" -​ tbl-name: "^messages.*" -``` - -应用 `bw-rule` 规则后： - -| table | 是否过滤| 过滤的原因 | -|:----|:----|:--------------| -| `logs`.`messages_2016` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2017` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `logs`.`messages_2018` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2016`.`messages` | 是 | schema `forum_backup_2016` 没有匹配到 `do-dbs` 任意一项 | -| `forum_backup_2017`.`messages` | 是 | schema `forum_backup_2017` 没有匹配到 `do-dbs` 任意一项 | -| `forum`.`users` | 是 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 没有匹配到 `do-tables` 和 `ignore-tables` 中任意一项，并且 `do-tables` 不为空，因此过滤 | -| `forum`.`messages` | 否 | 1. schema `forum` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | -| `forum_backup_2018`.`messages` | 否 | 1. schema `forum_backup_2018` 匹配到 `do-dbs` 进入 table 过滤
2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` | - -## Binlog event filter - -Binlog event filter 是比同步表黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema / table` 的指定类型 binlog，比如 `INSERT`，`TRUNCATE TABLE`。 - -> **注意：** -> -> 同一个表匹配上多个规则，将会顺序应用这些规则，并且黑名单的优先级高于白名单，即如果同时存在规则 `Ignore` 和 `Do` 应用在某个 table 上，那么 `Ignore` 生效。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -filters: - rule-1: - schema-pattern: "test_*" - ​table-pattern: "t_*" - ​events: ["truncate table", "drop table"] - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - ​action: Ignore -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/v3.1/reference/tools/data-migration/table-selector.md)：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句进行以下规则过滤。 - -- `events`：binlog events 数组。 - - | Event | 分类 | 解释 | - | --------------- | ---- | ----------------------------- | - | all | | 代表包含下面所有的 events | - | all dml | | 代表包含下面所有 DML events | - | all ddl | | 代表包含下面所有 DDL events | - | none | | 代表不包含下面所有 events | - | none ddl | | 代表不包含下面所有 DDL events | - | none dml | | 代表不包含下面所有 DML events | - | insert | DML | insert DML event | - | update | DML | update DML event | - | delete | DML | delete DML event | - | create database | DDL | create database event | - | drop database | DDL | drop database event | - | create table | DDL | create table event | - | create index | DDL | create index event | - | drop table | DDL | drop table event | - | truncate table | DDL | truncate table event | - | rename table | DDL | rename table event | - | drop index | DDL | drop index event | - | alter table | DDL | alter table event | - -- `sql-pattern`：用于过滤指定的 DDL SQL 语句，支持正则表达式匹配，例如上面示例 `"^DROP\\s+PROCEDURE"`。 - -- `action`：string(`Do` / `Ignore`)；进行下面规则判断，满足其中之一则过滤，否则不过滤。 - - - `Do`：白名单。binlog event 如果满足下面两个条件之一就会被过滤掉： - - 不在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 没有匹配上 `sql-pattern` 中任意一项。 - - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉： - - 在该 rule 的 `events` 中。 - - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 可以匹配上 `sql-pattern` 中任意一项。 - -### 使用示例 - -#### 过滤分库分表的所有删除操作 - -需要设置下面两个 `Binlog event filter rule` 来过滤掉所有的删除操作： - -- `filter-table-rule` 过滤掉所有匹配到 pattern `test_*`.`t_*` 的 table 的 `turncate table`、`drop table`、`delete statement` 操作。 -- `filter-schema-rule` 过滤掉所有匹配到 pattern `test_*` 的 schema 的 `drop database` 操作。 - -{{< copyable "" >}} - -```yaml -filters: - filter-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - filter-schema-rule: - schema-pattern: "test_*" - events: ["drop database"] - action: Ignore -``` - -#### 只同步分库分表的 DML 操作 - -需要设置下面两个 `Binlog event filter rule` 只同步 DML 操作： - -- `do-table-rule` 只同步所有匹配到 pattern `test_*`.`t_*` 的 table 的 `create table`、`insert`、`update`、`delete` 操作。 -- `do-schema-rule` 只同步所有匹配到 pattern `test_*` 的 schema 的 `create database` 操作。 - -> **注意：** -> -> 同步 `create database/table` 的原因是创建库和表后才能同步 `DML`。 - -{{< copyable "" >}} - -```yaml -filters: - do-table-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - events: ["create table", "all dml"] - action: Do - do-schema-rule: - schema-pattern: "test_*" - events: ["create database"] - action: Do -``` - -#### 过滤 TiDB 不支持的 SQL 语句 - -可设置如下规则过滤 TiDB 不支持的 `PROCEDURE` 语句： - -{{< copyable "" >}} - -```yaml -filters: - filter-procedure-rule: - schema-pattern: "test_*" - table-pattern: "t_*" - sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"] - action: Ignore -``` - -#### 过滤 TiDB parser 不支持的 SQL 语句 - -对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 `schema`/`table` 信息，因此需要使用全局过滤规则：`schema-pattern: "*"`。 - -> **注意：** -> -> 全局过滤规则的设置必须尽可能严格，以避免预期之外地过滤掉需要同步的数据。 - -可设置如下规则过滤 TiDB parser 不支持的 `PARTITION` 语句： - -{{< copyable "" >}} - -```yaml -filters: - filter-partition-rule: - schema-pattern: "*" - sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"] - action: Ignore -``` - -## Column mapping - -> **注意：** -> -> 由于 Column mapping 的使用限制较多，我们不推荐使用 Column mapping 功能作为首选方案。我们优先推荐的方案请参考 [自增主键冲突处理](/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)。 - -Column mapping 提供对表的列值进行修改的功能。可以根据不同的表达式对表的指定列做不同的修改操作，目前只支持 DM 提供的内置表达式。 - -> **注意：** -> -> - 不支持修改 column 的类型和表结构。 -> - 不支持对同一个表设置多个不同的列值转换规则。 - -### 参数配置 - -{{< copyable "" >}} - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -### 参数解释 - -- [`schema-pattern`/`table-pattern`](/v3.1/reference/tools/data-migration/table-selector.md)：对匹配上该规则的上游 MySQL/MariaDB 实例的表按照指定 `expression` 进行列值修改操作。 -- `source-column`，`target-column`：对 `source-column` 列的值按照指定 `expression` 进行修改，将修改后的值赋值给 `target-column`。 -- `expression`：对数据进行转换的表达式，目前只支持下面的内置计算表达式。 - -#### `partition id` 表达式 - -`partition id` 目的是为了解决分库分表合并同步的自增主键的冲突。 - -**`partition id` 限制** - -注意下面的限制： - -- 只支持类型为 bigint 的列，通常为自增主键，联合主键或者联合唯一索引的其中一列 -- 如果 `schema 前缀` 不为空，则库名的组成必须为 `schema 前缀` 或者 `schema 前缀 + 分隔符 + 数字（即 schema ID）`，例如：支持 `s` 和 `s_1`，不支持 `s_a` -- 如果 `table 前缀` 不为空，则表名的组成必须为 `table 前缀` 或者 `table 前缀 + 分隔符 + 数字（即 table ID）` -- 如果库名/表名不包含 `… + 分隔符 + 数字` 部分，则对应的 ID 默认为 0 -- 对分库分表的规模支持限制如下 - - 支持最多 16 个 MySQL/MariaDB 实例，且需要满足 0 <= instance ID <= 15。 - - 每个实例支持最多 128 个 schema，且需要满足 0 <= schema ID <= 127。 - - 每个实例的每个 schema 支持最多 256 个 table，且需要满足 0 <= table ID <= 255。 - - 进行 Column mapping 的列的范围需要满足 0 <= ID <= 17592186044415。 - - `{instance ID, schema ID, table ID}` 组合需要保持唯一。 -- 目前该功能是定制功能，如果需要调整请联系相关开发人员进行调整 - -**`partition id` 参数配置** - -用户需要在 arguments 里面按顺序设置以下三个或四个参数： - -- `instance_id`：客户指定的上游分库分表的 MySQL/MariaDB instance ID（0 <= instance ID <= 15） -- `schema 前缀`：用来解析库名并获取 `schema ID` -- `table 前缀`：用来解释表名并获取 `table ID` -- 分隔符：用来分隔前缀与 ID，可省略，省略时分隔符默认为空字符串 - -`instance_id`、`schema 前缀` 和 `table 前缀` 这三个参数均可被设置为空字符串（`""`），表示对应的部分不会被编码进 `partition id`。 - -**`partition id` 表达式规则** - -`partition id` 会用 arguments 里面的数字来填充自增主键 ID 的首个比特位，计算出来一个 int64（即 MySQL bigint）类型的值，具体规则如下： - -| instance_id | schema 前缀 | table 前缀 | 编码 | -|:------------|:--------------|:-------------|---------:| -| ☑ 已定义 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 44 比特位] | -| ☐ 空 | ☑ 已定义 | ☑ 已定义 | [`S`: 1 比特位] [`D`: 7 比特位] [`T`: 8 比特位] [`P`: 48 比特位] | -| ☑ 已定义 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`I`: 4 比特位] [`T`: 8 比特位] [`P`: 51 比特位] | -| ☑ 已定义 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`D`: 7 比特位] [`P`: 52 比特位] | -| ☐ 空 | ☐ 空 | ☑ 已定义 | [`S`: 1 比特位] [`T`: 8 比特位] [`P`: 55 比特位] | -| ☐ 空 | ☑ 已定义 | ☐ 空 | [`S`: 1 比特位] [`D`: 7 比特位] [`P`: 56 比特位] | -| ☑ 已定义 | ☐ 空 | ☐ 空 | [`S`: 1 比特位] [`I`: 4 比特位] [`P`: 59 比特位] | - -- `S`：符号位，保留 -- `I`：instance ID，默认 4 比特位 -- `D`：schema ID，默认 7 比特位 -- `T`：table ID，默认 8 比特位 -- `P`：自增主键 ID，占据剩下的比特位（≥44 比特位） - -### 使用示例 - -假设存在分库分表场景：将上游两个 MySQL 实例的 `test_{1,2,3...}`.`t_{1,2,3...}` 同步到下游 TiDB 的 `test`.`t`，并且这些表都有自增主键。 - -需要设置下面两个规则： - -{{< copyable "" >}} - -```yaml -column-mappings: - rule-1: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["1", "test", "t", "_"] - rule-2: -​ schema-pattern: "test_*" -​ table-pattern: "t_*" -​ expression: "partition id" -​ source-column: "id" -​ target-column: "id" -​ arguments: ["2", "test", "t", "_"] -``` - -- MySQL instance 1 的表 `test_1`.`t_1` 的 `ID = 1` 的行经过转换后 ID = 1 变为 `1 << (64-1-4) | 1 << (64-1-4-7) | 1 << 44 | 1 = 580981944116838401` -- MySQL instance 2 的表 `test_1`.`t_2` 的 `ID = 1` 的行经过转换后 ID = 2 变为 `2 << (64-1-4) | 1 << (64-1-4-7) | 2 << 44 | 2 = 1157460288606306306` - -## 同步延迟监控 - -DM 支持通过 heartbeat 真实同步数据来计算每个同步任务与 MySQL/MariaDB 的实时同步延迟。 - -> **注意：** -> -> - 同步延迟的估算的精度在秒级别。 -> - heartbeat 相关的 binlog 不会同步到下游，在计算延迟后会被丢弃。 - -### 系统权限 - -如果开启 heartbeat 功能，需要上游 MySQL/MariaDB 实例提供下面的权限： - -- SELECT -- INSERT -- CREATE (databases, tables) - -### 参数配置 - -在 task 的配置文件中设置： - -``` -enable-heartbeat: true -``` - -### 原理介绍 - -- DM-worker 在对应的上游 MySQL/MariaDB 创建库 `dm_heartbeat`（当前不可配置） -- DM-worker 在对应的上游 MySQL/MariaDB 创建表 `heartbeat`（当前不可配置） -- DM-worker 每秒钟（当前不可配置）在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 表中，利用 `replace statement` 更新当前时间戳 `TS_master` -- DM-worker 每个任务拿到 `dm_heartbeat`.`heartbeat` 的 binlog 后，更新自己的同步时间 `TS_slave_task` -- DM-worker 每 10 秒在对应的上游 MySQL/MariaDB 的 `dm_heartbeat`.`heartbeat` 查询当前的 `TS_master`，并且对每个任务计算 `task_lag` = `TS_master` - `TS_slave_task` - -可以在 metrics 的 [binlog replication](/v3.1/reference/tools/data-migration/monitor.md#binlog-replication) 处理单元找到 replicate lag 监控项。 diff --git a/v3.1/reference/tools/data-migration/features/shard-merge.md b/v3.1/reference/tools/data-migration/features/shard-merge.md deleted file mode 100644 index 8c04d9266a4e..000000000000 --- a/v3.1/reference/tools/data-migration/features/shard-merge.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: 分库分表合并同步 -category: reference ---- - -# 分库分表合并同步 - -本文介绍了 DM 提供的分库分表合并同步功能。此功能用于将上游 MySQL/MariaDB 实例中结构相同的表同步到下游 TiDB 的同一个表中。DM 不仅支持同步上游的 DML 数据，也支持协调同步多个上游分表的 DDL 表结构变更。 - -> **注意：** -> -> 要执行分库分表合并同步任务，必须在任务配置文件中设置 `is-sharding: true`。 - -## 使用限制 - -DM 进行分表 DDL 的同步有以下几点使用限制： - -- 在一个逻辑 sharding group（需要合并同步到下游同一个表的所有分表组成的 group）内，所有上游分表必须以相同的顺序执行相同的 DDL 语句（库名和表名可以不同），并且只有在所有分表执行完当前一条 DDL 语句后，下一条 DDL 语句才能执行。 - - - 比如，如果在 table_1 表中先增加列 a 后再增加列 b，则在 table_2 表中就不能先增加列 b 后再增加列 a，因为 DM 不支持以不同的顺序来执行相同的 DDL 语句。 - -- 对于每个逻辑 sharding group，推荐使用一个独立的任务进行同步。 - - - 如果一个任务内存在多个 sharding group，则必须等待一个 sharding group 的 DDL 语句同步完成后，才能开始对其他 sharding group 执行 DDL 语句。 - -- 在一个逻辑 sharding group 内，所有上游分表都应该执行对应的 DDL 语句。 - - - 比如，若 DM-worker-2 对应的一个或多个上游分表未执行 DDL 语句，则其他已执行 DDL 语句的 DM-worker 都会暂停同步任务，直到等到 DM-worker-2 收到上游对应的 DDL 语句。 - -- sharding group 数据同步任务不支持 `DROP DATABASE/TABLE` 语句。 - - - DM-worker 中的 binlog 同步单元（sync）会自动忽略掉上游分表的 `DROP DATABASE` 和 `DROP TABLE` 语句。 - -- sharding group 数据同步任务支持 `RENAME TABLE` 语句，但有如下限制（online DDL 中的 `RENAME` 有特殊方案进行支持）： - - - 只支持 `RENAME TABLE` 到一个不存在的表。 - - 一条 `RENAME TABLE` 语句只能包含一个 `RENAME` 操作。 - -- 增量同步任务需要确认开始同步的 binlog position 上各分表的表结构必须一致，才能确保来自不同分表的 DML 语句能够同步到表结构确定的下游，并且后续各分表的 DDL 语句能够正确匹配与同步。 - -- 如果需要变更 [table routing 规则](/v3.1/reference/tools/data-migration/features/overview.md#table-routing)，必须先等所有 sharding DDL 语句同步完成。 - - - 在 sharding DDL 语句同步过程中，使用 dmctl 尝试变更 router-rules 会报错。 - -- 如果需要创建新表加入到一个正在执行 DDL 语句的 sharding group 中，则必须保持新表结构和最新更改的表结构一致。 - - - 比如，原 table_1, table_2 表初始时有 (a, b) 两列，sharding DDL 语句执行后有 (a, b, c) 三列，则同步完成后新创建的表也应当有 (a, b, c) 三列。 - -- 由于已经收到 DDL 语句的 DM-worker 会暂停任务以等待其他 DM-worker 收到对应的 DDL 语句，因此数据同步延迟会增加。 - -## 背景 - -目前，DM 使用 ROW 格式的 binlog 进行数据同步，且 binlog 中不包含表结构信息。在 ROW 格式的 binlog 同步过程中，如果不需要将多个上游表合并同步到下游的同一个表，则只存在一个上游表的 DDL 语句会更新对应下游表结构。ROW 格式的 binlog 可以认为是具有 self-description 属性。 - -分库分表合并同步过程中，可以根据 column values 及下游的表结构构造出相应的 DML 语句，但此时若上游的分表执行 DDL 语句进行了表结构变更，则必须对该 DDL 语句进行额外同步处理，以避免因为表结构和 binlog 数据不一致而造成同步出错的问题。 - -以下是一个简化后的例子： - -![shard-ddl-example-1](/media/shard-ddl-example-1.png) - -在上图的例子中，分表的合库合表过程简化成了上游只有两个 MySQL 实例，每个实例内只有一个表。假设在数据同步开始时，将两个分表的表结构版本记为 schema V1，将 DDL 语句执行完后的表结构版本记为 schema V2。 - -现在，假设数据同步过程中，DM-worker 内的 binlog 同步单元（sync）从两个上游分表收到的 binlog 数据有如下时序： - -1. 开始同步时，sync 从两个分表收到的都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到实例 1 上分表的 DDL 语句。 - -3. 从 t2 时刻开始，sync 从实例 1 收到的是 schema V2 版本的 DML 语句；但从实例 2 收到的仍是 schema V1 版本的 DML 语句。 - -4. 在 t3 时刻，sync 收到实例 2 上分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从实例 2 收到的也是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当实例 1 的 DDL 语句同步到下游后，下游的表结构会变更成为 schema V2 版本。但在 t2 到 t3 这段时间内，sync 从实例 2 上收到的仍是 schema V1 版本的 DML 语句。当尝试把这些 schema V1 版本的 DML 语句同步到下游时，就会由于 DML 语句与表结构的不一致而发生错误，从而无法正确同步数据。 - -## 实现原理 - -基于上述例子，本部分介绍了 DM 在合库合表过程中进行 DDL 同步的实现原理。 - -![shard-ddl-flow](/media/shard-ddl-flow.png) - -在这个例子中，DM-worker-1 负责同步来自 MySQL 实例 1 的数据，DM-worker-2 负责同步来自 MySQL 实例 2 的数据，DM-master 负责协调多个 DM-worker 间的 DDL 同步。 - -从 DM-worker-1 收到 DDL 语句开始，简化后的 DDL 同步流程为： - -1. 在 t1 时刻，DM-worker-1 收到来自 MySQL 实例 1 的 DDL 语句，自身暂停该 DDL 语句对应任务的 DDL 及 DML 数据同步，并将 DDL 相关信息发送给 DM-master。 - -2. DM-master 根据收到的 DDL 信息判断得知需要协调该 DDL 语句的同步，于是为该 DDL 语句创建一个锁，并将 DDL 锁信息发回给 DM-worker-1，同时将 DM-worker-1 标记为这个锁的 owner。 - -3. DM-worker-2 继续进行 DML 语句的同步，直到在 t3 时刻收到来自 MySQL 实例 2 的 DDL 语句，自身暂停该 DDL 语句对应任务的数据同步，并将 DDL 相关信息发送给 DM-master。 - -4. DM-master 根据收到的 DDL 信息判断得知该 DDL 语句对应的锁信息已经存在，于是直接将对应锁信息发回给 DM-worker-2。 - -5. 根据任务启动时的配置信息、上游 MySQL 实例分表信息、部署拓扑信息等，DM-master 判断得知自身已经收到了来自待合表的所有上游分表的 DDL 语句，于是请求 DDL 锁的 owner（DM-worker-1）向下游同步执行该 DDL。 - -6. DM-worker-1 根据第二步收到的 DDL 锁信息验证 DDL 语句执行请求；向下游执行 DDL，并将执行结果反馈给 DM-master；若 DDL 语句执行成功，则自身开始继续同步后续的（从 t2 时刻对应的 binlog 开始的）DML 语句。 - -7. DM-master 收到来自 owner 执行 DDL 语句成功的响应，于是请求在等待该 DDL 锁的所有其他 DM-worker（DM-worker-2）忽略该 DDL 语句，直接继续同步后续的（从 t4 时刻对应的 binlog 开始的）DML 语句。 - -根据上面的流程，可以归纳出 DM 协调多个 DM-worker 间 sharding DDL 同步的特点： - -- 根据任务配置与 DM 集群部署拓扑信息，DM-master 内部也会建立一个逻辑 sharding group 来协调 DDL 同步，group 中的成员为负责处理该同步任务拆解后的各子任务的 DM-worker。 - -- 各 DM-worker 从 binlog event 中收到 DDL 语句后，会将 DDL 信息发送给 DM-master。 - -- DM-master 根据来自 DM-worker 的 DDL 信息及 sharding group 信息创建或更新 DDL 锁。 - -- 如果 sharding group 的所有成员都收到了某一条相同的 DDL 语句，则表明上游分表在该 DDL 执行前的 DML 语句都已经同步完成，此时可以执行该 DDL 语句，并继续后续的 DML 同步。 - -- 上游所有分表的 DDL 在经过 [table router](/v3.1/reference/tools/data-migration/features/overview.md#table-routing) 转换后需要保持一致，因此仅需 DDL 锁的 owner 执行一次该 DDL 语句即可，其他 DM-worker 可直接忽略对应的 DDL 语句。 - -在上面的示例中，每个 DM-worker 对应的上游 MySQL 实例中只有一个待合并的分表。但在实际场景下，一个 MySQL 实例可能有多个分库内的多个分表需要进行合并，这种情况下，sharding DDL 的协调同步过程将更加复杂。 - -假设同一个 MySQL 实例中有 table_1 和 table_2 两个分表需要进行合并： - -![shard-ddl-example-2](/media/shard-ddl-example-2.png) - -在这个例子中，由于数据来自同一个 MySQL 实例，因此所有数据都是从同一个 binlog 流中获得，时序如下： - -1. 开始同步时，DM-worker 内的 sync 从两个分表收到的数据都是 schema V1 版本的 DML 语句。 - -2. 在 t1 时刻，sync 收到 table_1 分表的 DDL 语句。 - -3. 从 t2 到 t3 时刻，sync 收到的数据同时包含 table_1 的 DML 语句（schema V2 版本）及 table_2 的 DML 语句（schema V1 版本）。 - -4. 在 t3 时刻，sync 收到 table_2 分表的 DDL 语句。 - -5. 从 t4 时刻开始，sync 从两个分表收到的数据都是 schema V2 版本的 DML 语句。 - -假设在数据同步过程中，不对分表的 DDL 语句进行额外处理。当 table_1 的 DDL 语句同步到下游从而变更下游表结构后，table_2 的 DML 语句（schema V1 版本）将无法正常同步。因此，在单个 DM-worker 内部，我们也构造了与 DM-master 内类似的逻辑 sharding group，但 group 的成员是同一个上游 MySQL 实例的不同分表。 - -DM-worker 内协调处理 sharding group 的同步与 DM-master 处理 DM-worker 之间的同步不完全一致，主要原因包括： - -- 当 DM-worker 收到 table_1 分表的 DDL 语句时，同步不能暂停，需要继续解析 binlog 才能获得后续 table_2 分表的 DDL 语句，即需要从 t2 时刻继续解析直到 t3 时刻。 - -- 在继续解析 t2 到 t3 时刻的 binlog 的过程中，table_1 分表的 DML 语句（schema V2 版本）不能向下游同步；但当 sharding DDL 同步并执行成功后，这些 DML 语句则需要同步到下游。 - -DM-worker 内部 sharding DDL 同步的简化流程为： - -1. 在 t1 时刻，DM-worker 收到 table_1 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -2. DM-worker 继续向前解析 t2 到 t3 时刻的 binlog。 - -3. 对于 table_1 的 DML 语句（schema V2 版本），忽略；对于 table_2 的 DML 语句（schema V1 版本），正常同步到下游。 - -4. 在 t3 时刻，DM-worker 收到 table_2 的 DDL 语句，并记录 DDL 信息及此时的 binlog 位置点信息。 - -5. 根据同步任务配置信息、上游库表信息等，DM-worker 判断得知该 MySQL 实例上所有分表的 DDL 语句都已收到；于是将该 DDL 语句同步到下游执行并变更下游表结构。 - -6. DM-worker 设置 binlog 流的新解析起始位置点为第一步时保存的位置点。 - -7. DM-worker 重新开始解析从 t2 到 t3 时刻的 binlog。 - -8. 对于 table_1 的 DML 语句（schema V2 版本），正常同步到下游；对于 table_2 的 DML 语句（schema V1 版本），忽略。 - -9. 解析到达第四步时保存的 binlog 位置点，可得知在第三步时被忽略的所有 DML 语句都已经重新同步到下游。 - -10. DM-worker 继续从 t4 时刻对应的 binlog 位置点开始正常同步。 - -综上可知，DM 在处理 sharding DDL 同步时，主要通过两级 sharding group 来进行协调控制，简化的流程为： - -1. 各 DM-worker 独立地协调对应上游 MySQL 实例内多个分表组成的 sharding group 的 DDL 同步。 - -2. 当 DM-worker 收到所有分表的 DDL 语句时，向 DM-master 发送 DDL 相关信息。 - -3. DM-master 根据 DM-worker 发来的 DDL 信息，协调由各 DM-worker 组成的 sharing group 的 DDL 同步。 - -4. 当 DM-master 收到所有 DM-worker 的 DDL 信息时，请求 DDL 锁的 owner（某个 DM-worker） 执行该 DDL 语句。 - -5. DDL 锁的 owner 执行 DDL 语句，并将结果反馈给 DM-master；自身开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -6. 当 DM-master 收到 owner 执行 DDL 成功的消息后，请求其他所有 DM-worker 继续开始同步。 - -7. 其他所有 DM-worker 各自开始重新同步在内部协调 DDL 同步过程中被忽略的 DML 语句。 - -8. 在完成被忽略的 DML 语句的重新同步后，所有 DM-worker 继续正常同步。 diff --git a/v3.1/reference/tools/data-migration/from-aurora.md b/v3.1/reference/tools/data-migration/from-aurora.md deleted file mode 100644 index 3fe1225bb383..000000000000 --- a/v3.1/reference/tools/data-migration/from-aurora.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: 从 AWS Aurora MySQL 迁移数据 -summary: 使用 DM 从 AWS Aurora MySQL 迁移数据。 -category: reference ---- - -# 从 AWS Aurora MySQL 迁移数据 - -本文介绍如何使用 DM 从 [AWS Aurora MySQL](https://aws.amazon.com/cn/rds/aurora/details/mysql-details/) 迁移数据到 TiDB。 - -## 第 1 步：在 Aurora 集群中启用 binlog - -假设有两个 Aurora 集群需要迁移数据到 TiDB，其集群信息如下，其中 Aurora-1 包含一个独立的读取器节点。 - -| 集群 | 终端节点 | 端口 | 角色 | -|:-------- |:--- | :--- | :--- | -| Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | -| Aurora-1 | pingcap-1-us-east-2a.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 读取器 | -| Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | 写入器 | - -DM 在增量同步阶段依赖 `ROW` 格式的 binlog，如果未启用 binlog 及设置正确的 binlog 格式，则不能正常使用 DM 进行数据同步，具体可参见[检查内容](/v3.1/reference/tools/data-migration/precheck.md#检查内容)。 - -> **注意：** -> -> Aurora 读取器不能开启 binlog，因此不能作为 DM 数据迁移时的上游 master server。 - -如果需要基于 GTID 进行数据迁移，还需要为 Aurora 集群启用 GTID 支持。 - -> **注意：** -> -> 基于 GTID 的数据迁移需要 MySQL 5.7 (Aurora 2.04.1) 或更高版本。 - -### 为 Aurora 集群修改 binlog 相关参数 - -在 Aurora 集群中，binlog 相关参数是**集群参数组中的集群级参数**，有关如何为 Aurora 集群启用 binlog 支持，请参考[在复制主实例上启用二进制日志记录](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Replication.MySQL.html#AuroraMySQL.Replication.MySQL.EnableBinlog)。在使用 DM 进行数据迁移时，需要将 `binlog_format` 参数设置为 `ROW`。 - -如果需要基于 GTID 进行数据迁移，需要将 `gtid-mode` 与 `enforce_gtid_consistency` 均设置为 `ON`。有关如何为 Aurora 集群启用基于 GTID 的数据迁移支持，请参考 [Configuring GTID-Based Replication for an Aurora MySQL Cluster](https://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/mysql-replication-gtid.html#mysql-replication-gtid.configuring-aurora)。 - -> **注意：** -> -> 在 Aurora 管理后台中，`gtid_mode` 参数表示为 `gtid-mode`。 - -## 第 2 步：部署 DM 集群 - -目前推荐使用 DM-Ansible 部署 DM 集群，具体部署方法参照[使用 DM-Ansible 部署 DM 集群](/v3.1/how-to/deploy/data-migration-with-ansible.md)。 - -> **注意：** -> -> - 在 DM 所有的配置文件中，数据库的密码要使用 dmctl 加密后的密文。如果数据库密码为空，则不需要加密。关于如何使用 dmctl 加密明文密码，参考[使用 dmctl 加密上游 MySQL 用户密码](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 -> - 上下游数据库用户必须拥有相应的读写权限。 - -## 第 3 步：检查集群信息 - -使用 DM-Ansible 部署 DM 集群后，相关配置信息如下： - -- DM 集群相关组件配置信息 - - | 组件 | 主机 | 端口 | - |:------|:---- |:---- | - | dm_worker1 | 172.16.10.72 | 8262 | - | dm_worker2 | 172.16.10.73 | 8262 | - | dm_master | 172.16.10.71 | 8261 | - -- 上下游数据库实例相关信息 - - | 数据库实例 | 主机 | 端口 | 用户名 | 加密密码 | - |:-------- |:--- | :--- | :--- | :--- | - | 上游 Aurora-1 | pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 上游 Aurora-2 | pingcap-2.h8emfqdptyc4.us-east-2.rds.amazonaws.com | 3306 | root | VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= | - | 下游 TiDB | 172.16.10.83 | 4000 | root | | - -- dm-master 进程配置文件 `{ansible deploy}/conf/dm-master.toml` 中的配置 - - ```toml - # Master 配置。 - - [[deploy]] - source-id = "mysql-replica-01" - dm-worker = "172.16.10.72:8262" - - [[deploy]] - source-id = "mysql-replica-02" - dm-worker = "172.16.10.73:8262" - ``` - -## 第 4 步：配置任务 - -假设需要将 Aurora-1 和 Aurora-2 实例的 `test_db` 库的 `test_table` 表以**全量+增量**的模式同步到下游 TiDB 的 `test_db` 库的 `test_table` 表。 - -复制并编辑 `{ansible deploy}/conf/task.yaml.example`，生成如下任务配置文件 `task.yaml`： - -```yaml -# 任务名，多个同时运行的任务不能重名。 -name: "test" -# 全量+增量 (all) 同步模式。 -task-mode: "all" -# 下游 TiDB 配置信息。 -target-database: - host: "172.16.10.83" - port: 4000 - user: "root" - password: "" - -# 当前数据同步任务需要的全部上游 MySQL 实例配置。 -mysql-instances: -- - # 上游实例或者复制组 ID，参考 `inventory.ini` 的 `source_id` 或者 `dm-master.toml` 的 `source-id 配置`。 - source-id: "mysql-replica-01" - # 需要同步的库名或表名的黑白名单的配置项名称，用于引用全局的黑白名单配置，全局配置见下面的 `black-white-list` 的配置。 - black-white-list: "global" - # Mydumper 的配置项名称，用于引用全局的 Mydumper 配置。 - mydumper-config-name: "global" - -- - source-id: "mysql-replica-02" - black-white-list: "global" - mydumper-config-name: "global" - -# 黑白名单全局配置，各实例通过配置项名引用。 -black-white-list: - global: - do-tables: # 需要同步的上游表的白名单。 - - db-name: "test_db" # 需要同步的表的库名。 - tbl-name: "test_table" # 需要同步的表的名称。 - -# Mydumper 全局配置，各实例通过配置项名引用。 -mydumpers: - global: - extra-args: "-B test_db -T test_table" # mydumper 的其他参数，从 DM 1.0.2 版本开始，DM 会自动生成 table-list 配置，在其之前的版本仍然需要人工配置。 -``` - -## 第 5 步：启动任务 - -1. 进入 dmctl 目录 `/home/tidb/dm-ansible/resources/bin/` - -2. 执行以下命令启动 dmctl - - {{< copyable "shell-regular" >}} - - ```bash - ./dmctl --master-addr 172.16.10.71:8261 - ``` - -3. 执行以下命令启动数据同步任务，其中，`task.yaml` 是之前编辑的配置文件 - - {{< copyable "" >}} - - ```bash - » start-task ./task.yaml - ``` - - - 如果执行命令后的返回结果中不包含错误信息，则表明任务已经成功启动 - - 如果包含以下错误信息，则表明上游 Aurora 用户可能拥有 TiDB 不支持的权限类型 - - ```json - { - "id": 4, - "name": "source db dump privilege chcker", - "desc": "check dump privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - }, - { - "id": 5, - "name": "source db replication privilege chcker", - "desc": "check replication privileges of source DB", - "state": "fail", - "errorMsg": "line 1 column 285 near \"LOAD FROM S3, SELECT INTO S3 ON *.* TO 'root'@'%' WITH GRANT OPTION\" ...", - "instruction": "", - "extra": "address of db instance - pingcap-1.h8emfqdptyc4.us-east-2.rds.amazonaws.com" - } - ``` - - 此时可以选择以下两种处理方法中的任意一种进行处理后，再使用 `start-task` 尝试重新启动任务： - 1. 为用于进行数据迁移的 Aurora 用户移除不被 TiDB 支持的不必要的权限 - 2. 如果能确保 Aurora 用户拥有 DM 所需要的权限，可以在 `task.yaml` 配置文件中添加如下顶级配置项以跳过启用任务时的前置权限检查 - - ```yaml - ignore-checking-items: ["dump_privilege", "replication_privilege"] - ``` - -## 第 6 步：查询任务 - -如需了解 DM 集群中是否存在正在运行的同步任务及任务状态等信息，可在 dmctl 内使用以下命令进行查询： - -{{< copyable "" >}} - -```bash -» query-status -``` - -> **注意：** -> -> 如果查询命令的返回结果中包含以下错误信息，则表明在全量同步的 dump 阶段不能获得相应的 lock： -> -> ```bash -> Couldn't acquire global lock, snapshots will not be consistent: Access denied for user 'root'@'%' (using password: YES) -> ``` -> -> 此时如果能接受不使用 FTWL 来确保 dump 文件与 metadata 的一致或上游能暂时停止写入，可以通过为 `mydumpers` 下的 `extra-args` 添加 `--no-locks` 参数来进行绕过，具体方法为： -> -> 1. 使用 `stop-task` 停止当前由于不能正常 dump 而已经转为 paused 的任务 -> 2. 将原 task.yaml 中的 `extra-args: "-B test_db -T test_table"` 更新为 `extra-args: "-B test_db -T test_table --no-locks"` -> 3. 使用 `start-task` 重新启动任务 diff --git a/v3.1/reference/tools/data-migration/glossary.md b/v3.1/reference/tools/data-migration/glossary.md deleted file mode 100644 index e17fc93cc119..000000000000 --- a/v3.1/reference/tools/data-migration/glossary.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: TiDB Data Migration 术语表 -summary: 学习 TiDB Data Migration 相关术语 -category: glossary ---- - -# TiDB Data Migration 术语表 - -本文档介绍 TiDB Data Migration (TiDB DM) 相关术语。 - -## B - -### Binlog - -在 TiDB DM 中，Binlog 通常指 MySQL/MariaDB 生成的 binary log 文件，具体请参考 [MySQL Binary Log](https://dev.mysql.com/doc/internals/en/binary-log.html) 与 [MariaDB Binary Log](https://mariadb.com/kb/en/library/binary-log/)。 - -### Binlog event - -MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考 [MySQL Binlog Event](https://dev.mysql.com/doc/internals/en/binlog-event.html) 与 [MariaDB Binlog Event](https://mariadb.com/kb/en/library/1-binlog-events/)。 - -### Binlog event filter - -比 Black & white table list 更加细粒度的过滤功能，具体可参考 [Binlog event filter](/v3.1/reference/tools/data-migration/overview.md#binlog-event-filter)。 - -### Binlog position - -特定 Binlog event 在 Binlog 文件中的位置偏移信息，具体请参考 [MySQL `SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/8.0/en/show-binlog-events.html) 与 [MariaDB `SHOW BINLOG EVENTS`](https://mariadb.com/kb/en/library/show-binlog-events/)。 - -### Binlog replication 处理单元 - -DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游的处理单元，每个 Subtask 对应一个 Binlog replication 处理单元。在当前文档中，有时也称作 Sync 处理单元。 - -### Black & white table list - -针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Black & white table lists](/v3.1/reference/tools/data-migration/overview.md#black--white-table-lists)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。 - -## C - -### Checkpoint - -TiDB DM 在全量导入与增量复制过程中的断点信息，用于在重新启动或恢复任务时从之前已经处理过的位置继续执行。 - -- 对于全量导入，Checkpoint 信息对应于每个数据文件已经被成功导入的数据对应的文件内偏移量等信息，其在每个导入数据的事务中同步更新； -- 对于增量复制，Checkpoint 信息对应于已经成功解析并导入到下游的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 等信息，其在 DDL 导入成功后或距上次更新时间超过 30 秒等条件下更新。 - -另外，[Relay 处理单元](#relay-处理单元) 对应的 `relay.meta` 内记录的信息也相当于 Checkpoint，其对应于 Relay 处理单元已经成功从上游拉取并写入到 [Relay log](#relay-log) 的 [Binlog event](#binlog-event) 对应的 [Binlog position](#binlog-position) 或 [GTID](#GTID) 信息。 - -## D - -### Dump 处理单元 - -DM-worker 内部用于从上游导出全量数据的处理单元，每个 Subtask 对应一个 Dump 处理单元。 - -## G - -### GTID - -MySQL/MariaDB 的全局事务 ID，当启用该功能后会在 Binlog 文件中记录 GTID 相关信息，多个 GTID 即组成为 GTID Set，具体请参考 [MySQL GTID Format and Storage](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html) 与 [MariaDB Global Transaction ID](https://mariadb.com/kb/en/library/gtid/)。 - -## H - -### Heartbeat - -在增量数据迁移过程中，用于估算数据从在上游写入后到达 Binlog replication 处理单元延迟时间的机制，具体可参考[同步延迟监控](/v3.1/reference/tools/data-migration/features/overview.md#同步延迟监控)。 - -## L - -### Load 处理单元 - -DM-worker 内部用于将全量导出数据导入到下游的处理单元，每个 Subtask 对应一个 Load 处理单元。在当前文档中，有时也称作 Import 处理单元。 - -## R - -### Relay log - -DM-worker 从上游 MySQL/MariaDB 拉取 Binlog 后存储在本地的文件，当前其格式为标准的 Binlog 格式，可使用版本兼容的 [mysqlbinlog](https://dev.mysql.com/doc/refman/8.0/en/mysqlbinlog.html) 等工具进行解析。其作用与 [MySQL Relay Log](https://dev.mysql.com/doc/refman/5.7/en/slave-logs-relaylog.html) 及 [MariaDB Relay Log](https://mariadb.com/kb/en/library/relay-log/) 相近。 - -有关 TiDB DM 内 Relay log 的目录结构、初始同步规则、数据清理等内容，可参考 [TiDB DM Relay Log](https://pingcap.com/docs-cn/stable/reference/tools/data-migration/relay-log/)。 - -### Relay 处理单元 - -DM-worker 内部用于从上游拉取 Binlog 并写入数据到 Relay log 的处理单元，每个 DM-worker 实例内部仅存在一个该处理单元。 - -## S - -### Safe mode - -指增量复制过程中，用于支持在表结构中存在主键或唯一索引的条件下可重复导入 DML 的模式。 - -该模式的主要特点为将来自上游的 `INSERT` 改写为 `REPLACE`，将 `UPDATE` 改写为 `DELETE` 与 `REPLACE` 后再向下游执行。在启动或恢复增量迁移任务的前 5 分钟 TiDB DM 会自动启动 Safe mode，另外也可以在任务配置文件中通过 `safe-mode` 参数手动开启。 - -### Shard DDL - -指合库合表迁移过程中，在上游各分表 (shard) 上执行的需要 TiDB DM 进行协调迁移的 DDL。在当前文档中，有时也称作 Sharding DDL。 - -### Shard DDL lock - -用于协调 Shard DDL 迁移的锁机制，具体原理可查看[分库分表合并同步实现原理](/v3.1/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding DDL lock。 - -### Shard group - -指合库合表迁移过程中，需要合并迁移到下游同一张表的所有上游分表 (shard)，TiDB DM 内部具体实现时使用了两级抽象的 Shard group，具体可查看[分库分表合并同步实现原理](/v3.1/reference/tools/data-migration/features/shard-merge.md#实现原理)。在当前文档中，有时也称作 Sharding group。 - -### Subtask - -数据迁移子任务，即数据迁移任务运行在单个 DM-worker 实例上的部分。根据任务配置的不同，单个数据迁移任务可能只有一个子任务，也可能有多个子任务。 - -### Subtask status - -数据迁移子任务所处的状态，目前包括 `New`、`Running`、`Paused`、`Stopped` 及 `Finished` 5 种状态。有关数据迁移任务、子任务状态的更多信息可参考[任务状态](/v3.1/reference/tools/data-migration/query-status.md#任务状态)。 - -## T - -### Table routing - -用于支持将上游 MySQL/MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步，具体可参考 [Table routing](/v3.1/reference/tools/data-migration/features/overview.md#table-routing)。 - -### Task - -数据迁移任务，执行 `start-task` 命令成功后即启动一个数据迁移任务。根据任务配置的不同，单个数据迁移任务既可能只在单个 DM-worker 实例上运行，也可能同时在多个 DM-worker 实例上运行。 - -### Task status - -数据迁移子任务所处的状态，由 [Subtask status](#subtask-status) 整合而来，具体信息可查看[任务状态](/v3.1/reference/tools/data-migration/query-status.md#任务状态)。 diff --git a/v3.1/reference/tools/data-migration/manage-tasks.md b/v3.1/reference/tools/data-migration/manage-tasks.md deleted file mode 100644 index 7cefd3d05b46..000000000000 --- a/v3.1/reference/tools/data-migration/manage-tasks.md +++ /dev/null @@ -1,956 +0,0 @@ ---- -title: 管理数据同步任务 -category: reference ---- - -# 管理数据同步任务 - -本文介绍了如何使用 [dmctl](/v3.1/reference/tools/data-migration/overview.md#dmctl) 组件来进行数据同步任务的管理和维护。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 `dm-ansible/dmctl`。 - -dmctl 支持交互模式用于人工操作，同时也支持命令模式用于脚本。 - -## dmctl 交互模式 - -本部分描述了在交互模式下一些 dmctl 命令的基本用法。 - -### dmctl 使用帮助 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl --help -``` - -``` -Usage of dmctl: - -V prints version and exit - -config string - path to config file - # 按照 DM 提供的加密方法加密数据库密码，用于 DM 的配置文件 - -encrypt string - encrypt plaintext to ciphertext - # DM-master 访问地址，dmctl 与 DM-master 交互以完成任务管理操作 - -master-addr string - master API server addr - -rpc-timeout string - rpc timeout, default is 10m (default "10m") -``` - -### 加密数据库密码 - -在 DM 相关配置文件中，要求必须使用经 dmctl 加密后的密码，否则会报错。对于同一个原始密码，每次加密后密码不同。 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -encrypt 123456 -``` - -``` -VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU= -``` - -### 任务管理概览 - -进入交互模式，与 DM-master 进行交互： - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 -``` - -``` -Welcome to dmctl -Release Version: v1.0.1 -Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7 -Git Branch: release-1.0 -UTC Build Time: 2019-09-10 06:15:05 -Go Version: go version go1.12 linux/amd64 - -» help -DM control - -Usage: - dmctl [command] - -Available Commands: - break-ddl-lock forcefully break DM-worker's DDL lock - check-task check the config file of the task - help help about any command - migrate-relay migrate DM-worker's relay unit - pause-relay pause DM-worker's relay unit - pause-task pause a specified running task - purge-relay purge relay log files of the DM-worker according to the specified filename - query-error query task error - query-status query task status - refresh-worker-tasks refresh worker -> tasks mapper - resume-relay resume DM-worker's relay unit - resume-task resume a specified paused task - show-ddl-locks show un-resolved DDL locks - sql-inject inject (limited) SQLs into binlog replication unit as binlog events - sql-replace replace SQLs matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern); each SQL must end with a semicolon - sql-skip skip the binlog event matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern) - start-task start a task as defined in the config file - stop-task stop a specified task - switch-relay-master switch the master server of the DM-worker's relay unit - unlock-ddl-lock forcefully unlock DDL lock - update-master-config update the config of the DM-master - update-relay update the relay unit config of the DM-worker - update-task update a task's config for routes, filters, or black-white-list - -Flags: - -h, --help help for dmctl - -w, --worker strings DM-worker ID - -# 使用 `dmctl [command] --help` 来获取某个命令的更多信息 -``` - -## 管理数据同步任务 - -本部分描述了如何使用不同的任务管理命令来执行相应操作。 - -### 创建数据同步任务 - -`start-task` 命令用于创建数据同步任务。 当数据同步任务启动时，DM 将[自动对相应权限和配置进行前置检查](/v3.1/reference/tools/data-migration/precheck.md)。 - -{{< copyable "" >}} - -```bash -help start-task -``` - -``` -start a task as defined in the config file - -Usage: - dmctl start-task [-w worker ...] [flags] - -Flags: - -h, --help help for start-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -start-task [ -w "172.16.30.15:8262"] ./task.yaml -``` - -#### 参数解释 - -+ `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上执行 `task.yaml` - - 如果设置，则只启动指定任务在该组 DM-workers 上的子任务 -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -start-task task.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -### 查询数据同步任务状态 - -`query-status` 命令用于查询数据同步任务状态。有关查询结果及子任务状态，详见[查询状态](/v3.1/reference/tools/data-migration/query-status.md)。 - -{{< copyable "" >}} - -```bash -help query-status -``` - -``` -query task status - -Usage: - dmctl query-status [-w worker ...] [task-name] [flags] - -Flags: - -h, --help help for query-status - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -query-status -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 查询在指定的一组 DM-workers 上运行的数据同步任务的子任务 -- `task-name`： - - 可选 - - 指定任务名称 - - 如果未设置，则返回全部数据同步任务的查询结果 - -#### 返回结果示例 - -有关查询结果中各参数的意义，详见[查询状态结果](/v3.1/reference/tools/data-migration/query-status.md#查询结果)。 - -### 查询运行错误 - -`query-error` 可用于查询数据同步任务与 relay 处理单元的错误信息。相比于 `query-status`，`query-error` 一般不用于获取除错误信息之外的其他信息。 - -`query-error` 常用于获取 `sql-skip`/`sql-replace` 所需的 binlog position 信息，有关 `query-error` 的参数与结果解释，请参考 [跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 文档中的 query-error](/v3.1/reference/tools/data-migration/skip-replace-sqls.md#query-error)。 - -### 暂停数据同步任务 - -`pause-task` 命令用于暂停数据同步任务。 - -> **注意：** -> -> 有关 `pause-task` 与 `stop-task` 的区别如下： -> -> - 使用 `pause-task` 仅暂停同步任务的执行，但仍然会在内存中保留任务的状态信息等，且可通过 `query-status` 进行查询；使用 `stop-task` 会停止同步任务的执行，并移除内存中与该任务相关的信息，且不可再通过 `query-status` 进行查询，但不会移除已经写入到下游数据库中的数据以及其中的 checkpoint 等 `dm_meta` 信息。 -> - 使用 `pause-task` 暂停同步任务期间，由于任务本身仍然存在，因此不能再启动同名的新任务，且会阻止对该任务所需 relay log 的清理；使用 `stop-task` 停止任务后，由于任务不再存在，因此可以再启动同名的新任务，且不会阻止对 relay log 的清理。 -> - `pause-task` 一般用于临时暂停同步任务以排查问题等；`stop-task` 一般用于永久删除同步任务或通过与 `start-task` 配合以更新配置信息。 - -{{< copyable "" >}} - -```bash -help pause-task -``` - -``` -pause a specified running task - -Usage: - dmctl pause-task [-w worker ...] [flags] - -Flags: - -h, --help help for pause-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上暂停数据同步任务的子任务 - - 如果设置，则只暂停该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-task test -``` - -``` -{ - "op": "Pause", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Pause", - "logID": "2" - } - ] -} -``` - -### 恢复数据同步任务 - -`resume-task` 命令用于恢复处于 `Paused` 状态的数据同步任务，通常用于在人为处理完造成同步任务暂停的故障后手动恢复同步任务。 - -{{< copyable "" >}} - -```bash -help resume-task -``` - -``` -resume a specified paused task - -Usage: - dmctl resume-task [-w worker ...] [flags] - -Flags: - -h, --help help for resume-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上恢复数据同步任务的子任务 - - 如果设置，则只恢复该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-task test -``` - -``` -{ - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Resume", - "logID": "3" - } - ] -} -``` - -### 停止数据同步任务 - -`stop-task` 命令用于停止数据同步任务。有关 `stop-task` 与 `pause-task` 的区别，请参考[暂停数据同步任务](#暂停数据同步任务)中的相关说明。 - -{{< copyable "" >}} - -```bash -help stop-task -``` - -``` -stop a specified task - -Usage: - dmctl stop-task [-w worker ...] [flags] - -Flags: - -h, --help help for stop-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -stop-task [-w "127.0.0.1:8262"] task-name -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上停止数据同步任务的子任务 - - 如果设置，则只停止该任务在指定 DM-workers 上的子任务 -- `task-name`： - - 必选 - - 指定任务名称 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -stop-task test -``` - -``` -{ - "op": "Stop", - "result": true, - "msg": "", - "workers": [ - { - "meta": { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - }, - { - "meta": { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - }, - "op": "Stop", - "logID": "4" - } - ] -} -``` - -### 更新数据同步任务 - -`update-task` 命令用于更新数据同步任务。 - -支持的更新项包括： - -- Table routing 规则 -- Black & white table lists 规则 -- Binlog event filter 规则 - -其余项均不支持更新。 - -> **注意：** -> -> 如果能确保同步任务所需的 relay log 在任务停止期间不会被清理，则推荐使用[不支持更新项的更新步骤](#不支持更新项的更新步骤)来以统一的方式更新任务配置信息。 - -#### 支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若 `stage` 不为 `Paused`，则先使用 `pause-task ` 暂停任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `update-task task.yaml` 更新任务配置。 - -4. 使用 `resume-task ` 恢复任务。 - -#### 不支持更新项的更新步骤 - -1. 使用 `query-status ` 查询对应数据同步任务的状态。 - - - 若任务存在，则通过 `stop-task ` 停止任务。 - -2. 在 `task.yaml` 文件中更新需要修改的自定义配置或者错误配置。 - -3. 使用 `start-task ` 重启恢复任务。 - -{{< copyable "" >}} - -```bash -help update-task -``` - -``` -update a task's config for routes, filters, or black-white-list - -Usage: - dmctl update-task [-w worker ...] [flags] - -Flags: - -h, --help help for update-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -update-task [-w "127.0.0.1:8262"] ./task.yaml -``` - -#### 参数解释 - -- `-w`： - - 可选 - - 指定在特定的一组 DM-workers 上更新数据同步任务的子任务 - - 如果设置，则只更新指定 DM-workers 上的子任务配置 -- `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -update-task task_all_black.yaml -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - }, - { - "result": true, - "worker": "172.16.30.16:8262", - "msg": "" - } - ] -} -``` - -## 管理 DDL lock - -目前与 DDL lock 相关的命令主要包括 `show-ddl-locks`、`unlock-ddl-lock`、`break-ddl-lock` 等。有关它们的功能、用法以及适用场景等，请参考[手动处理 sharding DDL lock](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 其他任务与集群管理命令 - -除上述常用的任务管理命令外，DM 还提供了其他一些命令用于管理数据同步任务或 DM 集群本身。 - -### 检查任务配置文件 - -`check-task` 命令用于检查指定的数据同步任务配置文件（`task.yaml`）是否合法以及上下游数据库的配置、权限、表结构等是否满足同步需要。具体可参考[上游 MySQL 实例配置前置检查](/v3.1/reference/tools/data-migration/precheck.md)。 - -在使用 `start-task` 启动同步任务时，DM 也会执行 `check-task` 所做的全部检查。 - -{{< copyable "" >}} - -```bash -help check-task -``` - -``` -check the config file of the task - -Usage: - dmctl check-task [flags] - -Flags: - -h, --help help for check-task - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -check-task task.yaml -``` - -#### 参数解释 - -+ `config-file`： - - 必选 - - 指定 `task.yaml` 的文件路径 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -check-task task-test.yaml -``` - -``` -{ - "result": true, - "msg": "check pass!!!" -} -``` - -### 暂停 relay 处理单元 - -relay 处理单元在 DM-worker 进程启动后即开始自动运行。通过使用 `pause-relay` 命令，我们可以暂停 relay 处理单元的运行。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `pause-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help pause-relay -``` - -``` -pause DM-worker's relay unit - -Usage: - dmctl pause-relay <-w worker ...> [flags] - -Flags: - -h, --help help for pause-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要暂停 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -pause-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "PauseRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 恢复 relay 处理单元 - -`resume-relay` 用于恢复处于 `Paused` 状态的 relay 处理单元。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `resume-relay` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help resume-relay -``` - -``` -resume DM-worker's relay unit - -Usage: - dmctl resume-relay <-w worker ...> [flags] - -Flags: - -h, --help help for resume-relay - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要恢复 relay 处理单元的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -resume-relay -w "172.16.30.15:8262" -``` - -``` -{ - "op": "InvalidRelayOp", - "result": true, - "msg": "", - "workers": [ - { - "op": "ResumeRelay", - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 切换 relay log 到新的子目录 - -relay 处理单元通过使用不同的子目录来存储来自上游不同 MySQL 实例的 binlog 数据。通过使用 `switch-relay-master` 命令，我们可以变更 relay 处理单元以开始使用一个新的子目录。 - -当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 `switch-relay-master` 对 DM 执行变更。具体变更步骤请参考[虚拟 IP 环境下的上游主从切换](/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-IP-环境下的上游主从切换)。 - -{{< copyable "" >}} - -```bash -help switch-relay-master -``` - -``` -switch the master server of the DM-worker's relay unit - -Usage: - dmctl switch-relay-master <-w worker ...> [flags] - -Flags: - -h, --help help for switch-relay-master - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "127.0.0.1:8262" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要切换 relay 处理单元使用子目录的 DM-worker - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -switch-relay-master -w "172.16.30.15:8262" -``` - -``` -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "172.16.30.15:8262", - "msg": "" - } - ] -} -``` - -### 手动清理 relay log - -DM 支持[自动清理 relay log](/v3.1/reference/tools/data-migration/relay-log.md#自动数据清理)，但同时 DM 也支持使用 `purge-relay` 命令[手动清理 relay log](/v3.1/reference/tools/data-migration/relay-log.md#手动数据清理)。 - -{{< copyable "" >}} - -```bash -help purge-relay -``` - -``` -purge relay log files of the DM-worker according to the specified filename - -Usage: - dmctl purge-relay <-w worker> [--filename] [--sub-dir] [flags] - -Flags: - -f, --filename string name of the terminal file before which to purge relay log files. Sample format: "mysql-bin.000006" - -h, --help help for purge-relay - -s, --sub-dir string specify relay sub directory for --filename. If not specified, the latest one will be used. Sample format: "2ae76434-f79f-11e8-bde2-0242ac130008.000001" - -Global Flags: - -w, --worker strings DM-worker ID -``` - -#### 命令用法示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -#### 参数解释 - -- `-w`： - - 必选 - - 指定需要执行 relay log 清理操作的 DM-worker -- `--filename`： - - 必选 - - 指定标识 relay log 将要停止清理的文件名。如指定为 `mysql-bin.000100`，则只尝试清理到 `mysql-bin.000099` -- `--sub-dir`： - - 可选 - - 指定 `--filename` 对应的 relay log 子目录，如果不指定则会使用当前最新的子目录 - -#### 返回结果示例 - -{{< copyable "" >}} - -```bash -purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003" -``` - -``` -[warn] no --sub-dir specified for --filename; the latest one will be used -{ - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] -} -``` - -### 预设跳过 DDL 操作 - -`sql-skip` 命令用于预设一个跳过操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。相关参数与结果解释，请参考[`sql-skip`](/v3.1/reference/tools/data-migration/skip-replace-sqls.md#sql-skip)。 - -### 预设替换 DDL 操作 - -`sql-replace` 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替换执行操作。相关参数与结果解释，请参考[`sql-replace`](/v3.1/reference/tools/data-migration/skip-replace-sqls.md#sql-replace)。 - -### 强制刷新 `task => DM-workers` 映射关系 - -`refresh-worker-tasks` 命令用于强制刷新 DM-master 内存中维护的 `task => DM-workers` 映射关系。 - -> **注意：** -> -> 一般不需要使用此命令。仅当已确定 `task => DM-workers` 映射关系存在，但执行其它命令时仍提示必须刷新它时，你才需要使用此命令。 - -## dmctl 命令模式 - -命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。 - -> **注意：** -> -> + 一条 dmctl 命令只能跟一个任务操作 -> + 任务操作只能放在 dmctl 命令的最后 - -{{< copyable "shell-regular" >}} - -```bash -./dmctl -master-addr 172.16.30.14:8261 start-task task.yaml -./dmctl -master-addr 172.16.30.14:8261 stop-task task -./dmctl -master-addr 172.16.30.14:8261 query-status -``` - -``` -Available Commands: - break-ddl-lock break-ddl-lock <-w worker ...> [--remove-id] [--exec] [--skip] - check-task check-task - migrate-relay migrate-relay - pause-relay pause-relay <-w worker ...> - pause-task pause-task [-w worker ...] - purge-relay purge-relay <-w worker> [--filename] [--sub-dir] - query-error query-error [-w worker ...] [task-name] - query-status query-status [-w worker ...] [task-name] - refresh-worker-tasks refresh-worker-tasks - resume-relay resume-relay <-w worker ...> - resume-task resume-task [-w worker ...] - show-ddl-locks show-ddl-locks [-w worker ...] [task-name] - sql-inject sql-inject <-w worker> - sql-replace sql-replace <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - sql-skip sql-skip <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] - start-task start-task [-w worker ...] - stop-task stop-task [-w worker ...] - switch-relay-master switch-relay-master <-w worker ...> - unlock-ddl-lock unlock-ddl-lock [-w worker ...] - update-master-config update-master-config - update-relay update-relay [-w worker ...] - update-task update-task [-w worker ...] -``` - -## 废弃或不推荐使用的命令 - -以下命令已经被废弃或仅用于 debug，在接下来的版本中可能会被移除或修改其语义，**强烈不推荐使用**。 - -- `migrate-relay` -- `sql-inject` -- `update-master-config` -- `update-relay` diff --git a/v3.1/reference/tools/data-migration/monitor.md b/v3.1/reference/tools/data-migration/monitor.md deleted file mode 100644 index 8434f9bed694..000000000000 --- a/v3.1/reference/tools/data-migration/monitor.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: DM 监控指标 -summary: 介绍 DM 的监控指标 -category: reference ---- - -# DM 监控指标 - -使用 DM-Ansible 部署 DM 集群的时候，会默认部署一套[监控系统](/v3.1/reference/tools/data-migration/deploy.md#第-7-步监控任务与查看日志)。 - -> **注意：** -> -> 目前只有 DM-worker 提供了 metrics，DM-master 暂未提供。 - -## Task - -在 Grafana dashboard 中，DM 默认名称为 `DM-task`。 - -### overview - -overview 下包含运行当前选定 task 的所有 DM-worker instance 的部分监控指标。当前默认告警规则只针对于单个 DM-worker instance。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | N/A | N/A | -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | N/A | N/A | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -### task 状态 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时| critical | - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒| N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### Dump/Load unit - -下面 metrics 仅在 `task-mode` 为 `full` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| data file size | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的总大小 | N/A | N/A | -| dump process exits with error | dump unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| load process exits with error | load unit 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| table count | load unit 导入的全量数据中 table 的数量总和 | N/A | N/A | -| data file count | load unit 导入的全量数据中数据文件（内含 `INSERT INTO` 语句）的数量总和| N/A | N/A | -| latency of execute transaction | load unit 在执行事务的时延，单位：秒 | N/A | N/A | -| latency of query | load unit 执行 query 的耗时，单位：秒 | N/A | N/A | - -### Binlog replication - -下面 metrics 仅在 `task-mode` 为 `incremental` 或者 `all` 模式下会有值。 - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| remaining time to sync | 预计 Syncer 还需要多少分钟可以和 master 完全同步，单位：分钟 | N/A | N/A | -| replicate lag | master 到 Syncer 的 binlog 复制延迟时间，单位：秒 | N/A | N/A | -| process exist with error | binlog replication 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| binlog file gap between master and syncer | 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog file gap between relay and syncer | 与 relay 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog event qps | 单位时间内接收到的 binlog event 数量 (不包含需要跳过的 event) | N/A | N/A | -| skipped binlog event qps | 单位时间内接收到的需要跳过的 binlog event 数量 | N/A | N/A | -| cost of binlog event transform | Syncer 解析并且转换 binlog 成 SQLs 的耗时，单位：秒 | N/A | N/A | -| total sqls jobs | 单位时间内新增的 job 数量 | N/A | N/A | -| finished sqls jobs | 单位时间内完成的 job 数量 | N/A | N/A | -| execution latency | Syncer 执行 transaction 到下游的耗时，单位：秒 | N/A | N/A | -| unsynced tables | 当前子任务内还未收到 shard DDL 的分表数量 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | - -## Instance - -在 Grafana dashboard 中，instance 的默认名称为 `DM-instance`。 - -### Relay log - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| storage capacity | relay log 占有的磁盘的总容量 | N/A | N/A | -| storage remain | relay log 占有的磁盘的剩余可用容量 | 小于 10G 的时候需要告警 | critical | -| process exits with error | relay log 在 DM-worker 内部遇到错误并且退出了 | 立即告警 | critical | -| relay log data corruption | relay log 文件损坏的个数 | 立即告警 | emergency | -| fail to read binlog from master | relay 从上游的 MySQL 读取 binlog 时遇到的错误数 | 立即告警 | critical | -| fail to write relay log | relay 写 binlog 到磁盘时遇到的错误数 | 立即告警 | critical | -| binlog file index | relay log 最大的文件序列号。如 value = 1 表示 relay-log.000001 | N/A | N/A | -| binlog file gap between master and relay | relay 与上游 master 相比落后的 binlog file 个数 | 落后 binlog file 个数超过 1 个（不含 1 个）且持续 10 分钟时 | critical | -| binlog pos | relay log 最新文件的写入 offset | N/A | N/A | -| read binlog duration | relay log 从上游的 MySQL 读取 binlog 的时延，单位：秒 | N/A | N/A | -| write relay log duration | relay log 每次写 binlog 到磁盘的时延，单位：秒 | N/A | N/A | -| binlog size | relay log 写到磁盘的单条 binlog 的大小 | N/A | N/A | - -### task - -| metric 名称 | 说明 | 告警说明 | 告警级别 | -|:----|:------------|:----|:----| -| task state | 同步子任务的状态 | 当子任务状态处于 paused 超过 10 分钟时 | critical | -| load progress | load unit 导入过程的进度百分比，值变化范围为：0% - 100% | N/A | N/A | -| binlog file gap between master and syncer | 与上游 master 相比 binlog replication 落后的 binlog file 个数 | N/A | N/A | -| shard lock resolving | 当前子任务是否正在等待 shard DDL 同步，大于 0 表示正在等待同步 | N/A | N/A | diff --git a/v3.1/reference/tools/data-migration/overview.md b/v3.1/reference/tools/data-migration/overview.md deleted file mode 100644 index 30eb3e449192..000000000000 --- a/v3.1/reference/tools/data-migration/overview.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Data Migration 简介 -category: reference ---- - -# Data Migration 简介 - -[DM](https://github.com/pingcap/dm) (Data Migration) 是一体化的数据同步任务管理平台，支持从 MySQL 或 MariaDB 到 TiDB 的全量数据迁移和增量数据同步。使用 DM 工具有利于简化错误处理流程，降低运维成本。 - -## DM 架构 - -DM 主要包括三个组件：DM-master，DM-worker 和 dmctl。 - -![Data Migration architecture](/media/dm-architecture.png) - -### DM-master - -DM-master 负责管理和调度数据同步任务的各项操作。 - -- 保存 DM 集群的拓扑信息 -- 监控 DM-worker 进程的运行状态 -- 监控数据同步任务的运行状态 -- 提供数据同步任务管理的统一入口 -- 协调分库分表场景下各个实例分表的 DDL 同步 - -### DM-worker - -DM-worker 负责执行具体的数据同步任务。 - -- 将 binlog 数据持久化保存在本地 -- 保存数据同步子任务的配置信息 -- 编排数据同步子任务的运行 -- 监控数据同步子任务的运行状态 - -DM-worker 启动后，会自动同步上游 binlog 至本地配置目录（如果使用 DM-Ansible 部署 DM 集群，默认的同步目录为 `/relay_log`）。关于 DM-worker，详见 [DM-worker 简介](/v3.1/reference/tools/data-migration/dm-worker-intro.md)。关于 relay log，详见 [DM Relay Log](/v3.1/reference/tools/data-migration/relay-log.md)。 - -### dmctl - -dmctl 是用来控制 DM 集群的命令行工具。 - -- 创建、更新或删除数据同步任务 -- 查看数据同步任务状态 -- 处理数据同步任务错误 -- 校验数据同步任务配置的正确性 - -## 同步功能介绍 - -下面简单介绍 DM 数据同步功能的核心特性。 - -### Table routing - -[Table routing](/v3.1/reference/tools/data-migration/features/overview.md#table-routing) 是指将上游 MySQL 或 MariaDB 实例的某些表同步到下游指定表的路由功能，可以用于分库分表的合并同步。 - -### Black & white table lists - -[Black & white table lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) 是指上游数据库实例表的黑白名单过滤规则。其过滤规则类似于 MySQL `replication-rules-db`/`replication-rules-table`，可以用来过滤或只同步某些数据库或某些表的所有操作。 - -### Binlog event filter - -[Binlog event filter](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 是比库表同步黑白名单更加细粒度的过滤规则，可以指定只同步或者过滤掉某些 `schema`/`table` 的指定类型的 binlog events，比如 `INSERT`，`TRUNCATE TABLE`。 - -### Shard support - -DM 支持对原分库分表进行合库合表操作，但需要满足一些[使用限制](/v3.1/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -## 使用限制 - -在使用 DM 工具之前，需了解以下限制： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - - > **注意：** - > - > 如果上游 MySQL/MariaDB server 间构成主从复制结构，则 - > - > - 5.7.1 < MySQL 版本 < 8.0 - > - MariaDB 版本 >= 10.1.3 - - 在使用 dmctl 启动任务时，DM 会自动对任务上下游数据库的配置、权限等进行[前置检查](/v3.1/reference/tools/data-migration/precheck.md)。 - -+ DDL 语法 - - - 目前，TiDB 部分兼容 MySQL 支持的 DDL 语句。因为 DM 使用 TiDB parser 来解析处理 DDL 语句，所以目前仅支持 TiDB parser 支持的 DDL 语法。 - - DM 遇到不兼容的 DDL 语句时会报错。要解决此报错，需要使用 dmctl 手动处理，要么跳过该 DDL 语句，要么用指定的 DDL 语句来替换它。详见[如何处理不兼容的 DDL 语句](/v3.1/reference/tools/data-migration/faq.md#如何处理不兼容的-ddl-语句) - -+ 分库分表 - - - 如果业务分库分表之间存在数据冲突，可以参考[自增主键冲突处理](/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决；否则不推荐使用 DM 进行同步，如果进行同步则有冲突的数据会相互覆盖造成数据丢失。 - - 关于分库分表合并场景的其它限制，参见[使用限制](/v3.1/reference/tools/data-migration/features/shard-merge.md#使用限制)。 - -+ 操作限制 - - - DM-worker 重启后不能自动恢复数据同步任务，需要使用 dmctl 手动执行 `start-task`。详见[管理数据同步任务](/v3.1/reference/tools/data-migration/manage-tasks.md)。 - - 在一些情况下，DM-worker 重启后不能自动恢复 DDL lock 同步，需要手动处理。详见[手动处理 Sharding DDL Lock](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -+ DM-worker 切换 MySQL - - - 当 DM-worker 通过虚拟 IP（VIP）连接到 MySQL 且要切换 VIP 指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。如需切换 VIP 指向的 MySQL 实例，请参考[虚拟 IP 环境下的上游主从切换](/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md#虚拟-ip-环境下切换-dm-worker-与-mysql-实例的连接)对 DM 手动执行变更。 diff --git a/v3.1/reference/tools/data-migration/precheck.md b/v3.1/reference/tools/data-migration/precheck.md deleted file mode 100644 index fcb6d4a73ed0..000000000000 --- a/v3.1/reference/tools/data-migration/precheck.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 上游 MySQL 实例配置前置检查 -category: reference ---- - -# 上游 MySQL 实例配置前置检查 - -本文介绍了 DM 提供的前置检查功能，此功能用于在数据同步任务启动时提前检测出上游 MySQL 实例配置中可能存在的一些错误。 - -## 使用命令 - -`check-task` 命令用于对上游 MySQL 实例配置是否满足 DM 要求进行前置检查。 - -## 检查内容 - -上下游数据库用户必须具备相应读写权限。当数据同步任务启动时，DM 会自动检查下列权限和配置： - -+ 数据库版本 - - - 5.5 < MySQL 版本 < 8.0 - - MariaDB 版本 >= 10.1.2 - -+ MySQL binlog 配置 - - - binlog 是否开启（DM 要求 binlog 必须开启） - - 是否有 `binlog_format=ROW`（DM 只支持 ROW 格式的 binlog 同步） - - 是否有 `binlog_row_image=FULL`（DM 只支持 `binlog_row_image=FULL`） - -+ 上游 MySQL 实例用户的权限 - - DM 配置中的 MySQL 用户至少需要具备以下权限： - - - REPLICATION SLAVE - - REPLICATION CLIENT - - RELOAD - - SELECT - -+ 上游 MySQL 表结构的兼容性 - - TiDB 和 MySQL 的兼容性存在以下一些区别： - - - TiDB 不支持外键 - - 字符集的兼容性不同，详见 [TiDB 支持的字符集](/v3.1/reference/sql/character-set.md) - -+ 上游 MySQL 多实例分库分表的一致性 - - + 所有分表的表结构是否一致，检查内容包括： - - - Column 数量 - - Column 名称 - - Column 位置 - - Column 类型 - - 主键 - - 唯一索引 - - + 分表中自增主键冲突检查 - - - 在两种情况下会造成检查失败： - - - 分表存在自增主键，且自增主键 column 类型不为 bigint - - 分表存在自增主键，自增主键 column 类型为 bigint，但没有为其配置列值转换 - - - 其他情况下检查将成功 diff --git a/v3.1/reference/tools/data-migration/query-status.md b/v3.1/reference/tools/data-migration/query-status.md deleted file mode 100644 index b8bd3703ca8c..000000000000 --- a/v3.1/reference/tools/data-migration/query-status.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: DM 查询状态 -category: reference ---- - -# DM 查询状态 - -本文介绍 DM（Data Migration）`query-status` 命令的查询结果、任务状态与子任务状态。 - -## 查询结果 - -{{< copyable "" >}} - -```bash -» query-status -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "tasks": [ # 迁移 task 列表 - { - "taskName": "test-1", # 任务名称 - "taskStatus": "Running", # 任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped”，“Finished” 以及 “Error”。 - "workers": [ # 该任务所使用的 DM-workers 列表 - "127.0.0.1:8262" - ] - }, - { - "taskName": "test-2", - "taskStatus": "Error - Some error occurred in subtask", # 该任务的子任务存在运行错误并暂停的现象 - "workers": [ - "127.0.0.1:8262", - "127.0.0.1:8263" - ] - }, - { - "taskName": "test-3", - "taskStatus": "Error - Relay status is Error", # 该任务的某个处于 Sync 阶段的子任务对应的 Relay 处理单元出错 - "workers": [ - "127.0.0.1:8263", - "127.0.0.1:8264" - ] - } - ] -} -``` - -关于 tasks 下的 taskStatus 状态的详细定义，请参阅[任务状态](#任务状态)。 - -推荐的 `query-status` 使用方法是： - -1. 首先使用 query-status 查看各个 task 的运行状态是否正常。 -2. 如果发现其中某一 task 状态有问题，通过 `query-status <出错任务的 taskName>` 来得到更详细的错误信息。 - -## 任务状态 - -DM 的迁移任务状态取决于其分配到 DM-worker 上的[子任务状态](#子任务状态)，定义见下表： - -| 任务对应的所有子任务的状态 | 任务状态 | -| :--- | :--- | -| 任一子任务处于 “Paused” 状态且返回结果有错误信息 | Error - Some error occurred in subtask | -| 任一处于 Sync 阶段的子任务处于 “Running” 状态但其 Relay 处理单元未运行（处于 Error/Paused/Stopped 状态） | Error - Relay status is Error/Paused/Stopped | -| 任一子任务处于 “Paused” 状态且返回结果没有错误信息 | Paused | -| 所有子任务处于 “New” 状态 | New | -| 所有子任务处于 “Finished” 状态 | Finished | -| 所有子任务处于 “Stopped” 状态 | Stopped | -| 其他情况 | Running | - -## 详情查询结果 - -{{< copyable "" >}} - -```bash -» query-status test -``` - -``` -{ - "result": true, # 查询是否成功。 - "msg": "", # 查询失败原因描述。 - "workers": [ # DM-worker 列表。 - { - "result": true, - "worker": "172.17.0.2:8262", # DM-worker ID。 - "msg": "", - "subTaskStatus": [ # DM-worker 所有子任务的信息。 - { - "name": "test", # 子任务名称。 - "stage": "Running", # 子任务运行状态，包括 “New”，“Running”，“Paused”，“Stopped” 以及 “Finished”。 - "unit": "Sync", # DM 的处理单元，包括 “Check”，“Dump“，“Load” 以及 “Sync”。 - "result": null, # 子任务失败时显示错误信息。 - "unresolvedDDLLockID": "test-`test`.`t_target`", # sharding DDL lock ID，可用于异常情况下手动处理 sharding DDL lock。 - "sync": { # 当前 `Sync` 处理单元的同步信息。 - "totalEvents": "12", # 该子任务中同步的 binlog event 总数。 - "totalTps": "1", # 该子任务中每秒同步的 binlog event 数量。 - "recentTps": "1", # 该子任务中最后一秒同步的 binlog event 数量。 - "masterBinlog": "(bin.000001, 3234)", # 上游数据库当前的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库当前的 GTID 信息。 - "syncerBinlog": "(bin.000001, 2525)", # 已被 `Sync` 处理单元同步的 binlog position。 - "syncerBinlogGtid": "", # 当前版本总是为空（因为 `Sync` 处理单元暂不使用 GTID 同步数据）。 - "blockingDDLs": [ # 当前被阻塞的 DDL 列表。该项仅在当前 DM-worker 所有上游表都处于 “synced“ 状态时才有数值，此时该列表包含的是待执行或待跳过的 sharding DDL 语句. - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "unresolvedGroups": [ # 没有被解决的 sharding group 信息。 - { - "target": "`test`.`t_target`", # 待同步的下游表。 - "DDLs": [ - "USE `test`; ALTER TABLE `test`.`t_target` DROP COLUMN `age`;" - ], - "firstPos": "(bin|000001.000001, 3130)", # sharding DDL 语句起始 binlog position。 - "synced": [ # `Sync` 处理单元已经读到该 sharding DDL 的上游分表。 - "`test`.`t2`" - "`test`.`t3`" - "`test`.`t1`" - ], - "unsynced": [ # `Sync` 处理单元未读到该 sharding DDL 的上游分表。如有上游分表未完成同步，`blockingDDLs` 为空。 - ] - } - ], - "synced": false # 增量同步是否已追上上游。由于后台 `Sync` 单元并不会实时刷新保存点，当前值为 “false“ 并不一定代表发生了同步延迟。 - } - } - ], - "relayStatus": { # relay 单元的同步状态. - "masterBinlog": "(bin.000001, 3234)", # 上游数据库的 binlog position。 - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 上游数据库的 binlog GTID 信息。 - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", # 当前使用的 relay log 子目录。 - "relayBinlog": "(bin.000001, 3234)", # 已被拉取至本地存储的 binlog position。 - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-14", # 已被拉取至本地存储的 binlog GTID 信息。 - "relayCatchUpMaster": true, # 本地 relay log 同步进度是否与上游一致。 - "stage": "Running", # relay 处理单元状态 - "result": null - } - }, - { - "result": true, - "worker": "172.17.0.3:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Running", - "unit": "Load", - "result": null, - "unresolvedDDLLockID": "", - "load": { # `Load` 处理单元的同步信息。 - "finishedBytes": "115", # 已全量导入字节数。 - "totalBytes": "452", # 总计需要导入的字节数。 - "progress": "25.44 %" # 全量导入进度。 - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 28507)", - "masterBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relaySubDir": "c0149e17-dff1-11e8-b6a8-0242ac110004.000001", - "relayBinlog": "(bin.000001, 28507)", - "relayBinlogGtid": "c0149e17-dff1-11e8-b6a8-0242ac110004:1-96", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - } - }, - { - "result": true, - "worker": "172.17.0.6:8262", - "msg": "", - "subTaskStatus": [ - { - "name": "test", - "stage": "Paused", - "unit": "Load", - "result": { # 错误示例 - "isCanceled": false, - "errors": [ - { - "Type": "ExecSQL", - "msg": "Error 1062: Duplicate entry '1155173304420532225' for key 'PRIMARY'\n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:160: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/db.go:105: \n/home/jenkins/workspace/build_dm/go/src/github.com/pingcap/tidb-enterprise-tools/loader/loader.go:138: file test.t1.sql" - } - ], - "detail": null - }, - "unresolvedDDLLockID": "", - "load": { - "finishedBytes": "0", - "totalBytes": "156", - "progress": "0.00 %" - } - } - ], - "relayStatus": { - "masterBinlog": "(bin.000001, 1691)", - "masterBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relaySubDir": "97b5142f-e19c-11e8-808c-0242ac110005.000001", - "relayBinlog": "(bin.000001, 1691)", - "relayBinlogGtid": "97b5142f-e19c-11e8-808c-0242ac110005:1-9", - "relayCatchUpMaster": true, - "stage": "Running", - "result": null - } - } - ] -} -``` - -关于 `workers` 下 `subTaskStatus` 中 `stage` 状态和状态转换关系的详细信息，请参阅[子任务状态](#子任务状态)。 - -关于 `workers` 下 `subTaskStatus` 中 `unresolvedDDLLockID`的操作细节，请参阅[手动处理 Sharding DDL Lock](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md)。 - -## 子任务状态 - -### 状态描述 - -- `New`： - - - 初始状态。 - - 如果子任务没有发生错误，状态切换为 `Running`，其他情况则切换为 `Paused`。 - -- `Running`：正常运行状态。 - -- `Paused`： - - - 暂停状态。 - - 子任务发生错误，状态切换为 `Paused`。 - - 如在子任务为 `Running` 状态下执行 `pause-task` 命令，任务状态会切换为 `Paused`。 - - 如子任务处于该状态，可以使用 `resume-task` 命令恢复任务。 - -- `Stopped`： - - - 停止状态。 - - 如在子任务为 `Running` 或 `Paused` 状态下执行 `stop-task` 命令，任务状态会切换为 `Stopped`。 - - 如子任务处于该状态，不可使用 `resume-task` 命令恢复任务。 - -- `Finished`： - - - 任务完成状态。 - - 只有 `task-mode` 为 `full` 的任务正常完成后，任务才会切换为该状态。 - -### 状态转换图 - -``` - error occurs - New --------------------------------| - | | - | resume-task | - | |----------------------------| | - | | | | - | | | | - v v error occurs | v - Finished <-------------- Running -----------------------> Paused - ^ | or pause-task | - | | | - start task | | stop task | - | | | - | v stop task | - Stopped <-------------------------| -``` diff --git a/v3.1/reference/tools/data-migration/relay-log.md b/v3.1/reference/tools/data-migration/relay-log.md deleted file mode 100644 index 89a2c5eb426b..000000000000 --- a/v3.1/reference/tools/data-migration/relay-log.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: DM Relay Log -summary: 了解目录结构、初始同步规则和 DM relay log 的数据清理。 -category: reference ---- - -# DM Relay Log - -DM (Data Migration) 工具的 relay log 由一组有编号的文件和一个索引文件组成。这些有编号的文件包含了描述数据库更改的事件。索引文件包含所有使用过的 relay log 的文件名。 - -DM-worker 在启动后，会自动将上游 binlog 同步到本地配置目录（若使用 DM-Ansible 部署 DM，则同步目录默认为 ` / relay_log` ）。DM-worker 在运行过程中，会将上游 binlog 实时同步到本地文件。DM-worker 的处理单元 Syncer 会实时读取本地 relay log 的 binlog 事件，将这些事件转换为 SQL 语句，再将 SQL 语句同步到下游数据库。 - -本文档介绍 DM relay log 的目录结构、初始同步规则和数据清理方法。 - -## 目录结构 - -Relay-log 本地存储的目录结构示例如下： - -``` -/relay_log/ -|-- 7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001 -| |-- mysql-bin.000001 -| |-- mysql-bin.000002 -| |-- mysql-bin.000003 -| |-- mysql-bin.000004 -| `-- relay.meta -|-- 842965eb-091c-11e9-9e45-9a3bff03fa39.000002 -| |-- mysql-bin.000001 -| `-- relay.meta -`-- server-uuid.index -``` - -- `subdir`： - - - DM-worker 把从上游数据库同步到的 binlog 存储在同一目录下，每个目录都为一个 `subdir`。 - - `subdir` 的命名格式为 `<上游数据库 UUID>.<本地 subdir 序列号>`。 - - 在上游进行 master 和 slave 实例切换后，DM-worker 会生成一个序号递增的新 `subdir` 目录。 - - - 在以上示例中，对于 `7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001` 这一目录，`7e427cc0-091c-11e9-9e45-72b7c59d52d7` 是上游数据库的 UUID，`000001` 是本地 `subdir` 的序列号。 - -- `server-uuid.index`：记录当前可用的 `subdir` 目录。 - -- `relay.meta`：存储每个 `subdir` 中已同步的 binlog 信息。例如， - - ```bash - cat c0149e17-dff1-11e8-b6a8-0242ac110004.000001/relay.meta - ``` - - ``` - binlog-name = "mysql-bin.000010" # 当前同步的 binlog 名 - binlog-pos = 63083620 # 当前同步的 binlog 位置 - binlog-gtid = "c0149e17-dff1-11e8-b6a8-0242ac110004:1-3328" # 当前同步的 binlog GTID - ``` - - 也可能包含多个 GTID： - - ```bash - cat 92acbd8a-c844-11e7-94a1-1866daf8accc.000001/relay.meta - ``` - - ``` - binlog-name = "mysql-bin.018393" - binlog-pos = 277987307 - binlog-gtid = "3ccc475b-2343-11e7-be21-6c0b84d59f30:1-14,406a3f61-690d-11e7-87c5-6c92bf46f384:1-94321383,53bfca22-690d-11e7-8a62-18ded7a37b78:1-495,686e1ab6-c47e-11e7-a42c-6c92bf46f384:1-34981190,03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170,10b039fc-c843-11e7-8f6a-1866daf8d810:1-308290454" - ``` - -## 初始同步规则 - -DM-worker 每次启动时（或在 DM-worker 暂停后 relay log 恢复同步），同步的起始位置会出现以下几种情况： - -- 若是有效的本地 relay log（有效是指 relay log 具有有效的 `server-uuid.index`，`subdir` 和 `relay.meta` 文件），DM-worker 从 `relay.meta` 记录的位置恢复同步。 - -- 若不存在有效的本地 relay log，而且 DM 配置文件中未指定 `relay-binlog-name` 或 `relay-binlog-gtid`： - - - 在非 GTID 模式下，DM-worker 从初始的上游 binlog 开始同步，并将所有上游 binlog 文件连续同步至最新。 - - - 在 GTID 模式下，DM-worker 从初始上游 GTID 开始同步。 - - > **注意：** - > - > 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定同步的起始位置。 - -- 若不存在有效的本地 relay log： - - - 在非 GTID 模式下，若指定了 `relay-binlog-name`，则 DM-worker 从指定的 binlog 文件开始同步。 - - 在 GTID 模式下，若指定了 `relay-binlog-gtid`，则 DM-worker 从指定的 GTID 开始同步。 - -## 数据清理 - -因为存在文件读写的检测机制，所以 DM-worker 不会清理正在使用的 relay log，也不会清理当前任务稍后会使用到的 relay log。 - -Relay log 的数据清理包括自动清理和手动清理这两种方法。 - -### 自动数据清理 - -自动数据清理需对 DM-worker 命令行配置中的以下三项进行配置： - -- `purge-interval` - - 后台自动清理的时间间隔，以秒为单位。 - - 默认为 "3600"，表示每 3600 秒执行一次后台清理任务。 - -- `purge-expires` - - 未更新的 relay log 在被后台清理前可保留的小时数。 - - 默认为 "0"，表示不按 relay log 的更新时间执行数据清理。 - -- `purge-remain-space` - - 剩余磁盘空间，单位为 GB。若剩余磁盘空间小于该配置，则指定的 DM-worker 机器会在后台尝试自动清理可被安全清理的 relay-log。若这一数字被设为 "0"，则表示不按剩余磁盘空间来清理数据。 - - 默认为 "15"，表示可用磁盘空间小于 15GB 时，DM-master 会尝试安全地清理 relay log。 - -或者在 DM-woker 的配置文件中加入 purge 配置： - -```toml -# relay log purge strategy -[purge] -interval = 3600 -expires = 24 -remain-space = 15 -``` - -### 手动数据清理 - -手动数据清理是指使用 dmctl 提供的 `purge-relay` 命令，通过指定 `subdir` 和 binlog 文件名，来清理掉**指定 binlog 之前**的所有 relay log。若在命令中不填 `-subdir` 选项，则默认清理**最新 relay log 子目录之前**的所有 relay log。 - -假设当前 relay log 的目录结构如下： - -{{< copyable "shell-regular" >}} - -```bash -tree . -``` - -``` -. -|-- deb76a2b-09cc-11e9-9129-5242cf3bb246.000001 -| |-- mysql-bin.000001 -| |-- mysql-bin.000002 -| |-- mysql-bin.000003 -| `-- relay.meta -|-- deb76a2b-09cc-11e9-9129-5242cf3bb246.000003 -| |-- mysql-bin.000001 -| `-- relay.meta -|-- e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 -| |-- mysql-bin.000001 -| `-- relay.meta -`-- server-uuid.index -``` - -{{< copyable "shell-regular" >}} - -```bash -cat server-uuid.index -``` - -``` -deb76a2b-09cc-11e9-9129-5242cf3bb246.000001 -e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 -deb76a2b-09cc-11e9-9129-5242cf3bb246.000003 -``` - -在 dmctl 中使用 `purge-relay` 命令的示例如下： - -+ 以下命令指定的 relay log 子目录为 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，该子目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001`。所以该命令实际清空了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 子目录，保留 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002` 和 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。 - - {{< copyable "" >}} - - ```bash - » purge-relay -w 10.128.16.223:10081 --filename mysql-bin.000001 --sub-dir e4e0e8ab-09cc-11e9-9220-82cc35207219.000002 - ``` - -+ 以下命令默认 `--sub-dir` 为最新的 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。该目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 和 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，所以该命令实际清空了这两个子目录，保留了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003`。 - - {{< copyable "" >}} - - ```bash - » purge-relay -w 10.128.16.223:10081 --filename mysql-bin.000001 - ``` diff --git a/v3.1/reference/tools/data-migration/releases/1.0.2.md b/v3.1/reference/tools/data-migration/releases/1.0.2.md deleted file mode 100644 index 176073d7f66d..000000000000 --- a/v3.1/reference/tools/data-migration/releases/1.0.2.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: DM 1.0.2 Release Notes -category: Releases ---- - -# DM 1.0.2 Release Notes - -发版日期：2019 年 10 月 30 日 - -DM 版本：1.0.2 - -DM-Ansible 版本：1.0.2 - -## 改进提升 - -- 支持自动为 DM-worker 生成部分配置项 -- 支持自动为数据迁移任务生成部分配置项 -- 简化 `query-status` 在无参数时的默认输出 -- DM 直接管理到下游数据库的连接 - -## 问题修复 - -- 修复在进程启动过程中以及执行 SQL 失败时可能 panic 的问题 -- 修复 DDL 执行超时后可能造成 sharding DDL 协调异常的问题 -- 修复由于前置检查超时或部分 DM-worker 不可访问而不能启动数据迁移任务的问题 -- 修复 SQL 执行失败后可能错误重试的问题 - -## 详细变更及问题修复 - -- 支持自动为 DM-worker 生成随机的 `server-id` 配置项 [#337](https://github.com/pingcap/dm/pull/337) -- 支持自动为 DM-worker 生成 `flavor` 配置项 [#328](https://github.com/pingcap/dm/pull/328) -- 支持自动为 DM-worker 生成 `relay-binlog-name` 与 `relay-binlog-gtid` 配置项 [#318](https://github.com/pingcap/dm/pull/318) -- 支持根据黑白名单生成 mydumper 需要导出的表名配置项 [#326](https://github.com/pingcap/dm/pull/326) -- 为数据迁移任务增加并发度配置项 (`mydumper-thread`、`loader-thread` 与 `syncer-thread`) [#314](https://github.com/pingcap/dm/pull/314) -- 简化 `query-status` 在无参数时的默认输出 [#340](https://github.com/pingcap/dm/pull/340) -- 修复 DDL 执行超时后可能造成 sharding DDL 协调异常的问题 [#338](https://github.com/pingcap/dm/pull/338) -- 修复 DM-worker 从本地 meta 数据恢复数据迁移任务时可能 panic 的问题 [#311](https://github.com/pingcap/dm/pull/311) -- 修复提交事务失败时可能造成 DM-worker panic 的问题 [#313](https://github.com/pingcap/dm/pull/313) -- 修复监听端口被占用时 DM-worker 或 DM-master 启动过程中可能 panic 的问题 [#301](https://github.com/pingcap/dm/pull/301) -- 修复对 1105 错误码的部分重试问题 [#321](https://github.com/pingcap/dm/pull/321), [#332](https://github.com/pingcap/dm/pull/332) -- 修复对 `Duplicate entry` 与 `Data too long for column` 错误的重试问题 [#313](https://github.com/pingcap/dm/pull/313) -- 修复在上游存在大量需要迁移的表时可能造成启动任务前置检查超时中断的问题 [#327](https://github.com/pingcap/dm/pull/327) -- 修复部分 DM-worker 不可访问时无法启动数据迁移任务的问题 [#319](https://github.com/pingcap/dm/pull/319) -- 修复从损坏的 relay log 恢复时可能错误更新 GTID sets 信息的问题 [#339](https://github.com/pingcap/dm/pull/339) -- 修复 sync 处理单元计算 TPS 错误的问题 [#294](https://github.com/pingcap/dm/pull/294) -- DM 直接管理到下游数据库的连接 [#325](https://github.com/pingcap/dm/pull/325) -- 提升组件内错误信息的传递方式 [#320](https://github.com/pingcap/dm/pull/320) diff --git a/v3.1/reference/tools/data-migration/releases/1.0.3.md b/v3.1/reference/tools/data-migration/releases/1.0.3.md deleted file mode 100644 index 8ae6dda78d5e..000000000000 --- a/v3.1/reference/tools/data-migration/releases/1.0.3.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: DM 1.0.3 Release Notes -category: Releases ---- - -# DM 1.0.3 Release Notes - -发版日期：2019 年 12 月 13 日 - -DM 版本：1.0.3 - -DM-Ansible 版本：1.0.3 - -## 改进提升 - -- dmctl 支持命令式使用 -- 支持同步 `ALTER DATABASE` DDL 语句 -- 优化 DM 错误提示信息 - -## 问题修复 - -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 - -## 详细变更及问题修复 - -- dmctl 支持命令式使用 [#364](https://github.com/pingcap/dm/pull/364) -- 优化 DM 错误提示信息 [#351](https://github.com/pingcap/dm/pull/351) -- 优化 `query-status` 命令输出内容 [#357](https://github.com/pingcap/dm/pull/357) -- 优化 DM 不同任务类型的权限检查 [#374](https://github.com/pingcap/dm/pull/374) -- 支持对重复引用的路由配置和过滤配置进行检查 [#385](https://github.com/pingcap/dm/pull/385) -- 支持同步 `ALTER DATABASE` DDL 语句 [#389](https://github.com/pingcap/dm/pull/389) -- 优化 DM 异常重试机制 [#391](https://github.com/pingcap/dm/pull/391) -- 修复全量导入模块在暂停或退出时 data race 导致 panic 的问题 [#353](https://github.com/pingcap/dm/pull/353) -- 修复对下游进行重试操作时，`stop-task` 和 `pause-task` 可能不生效的问题 [#400](https://github.com/pingcap/dm/pull/400) -- 更新 Golang 版本至 1.13 以及其他依赖包版本 [#362](https://github.com/pingcap/dm/pull/362) -- 过滤 SQL 执行时出现的 `context canceled` 错误 [#382](https://github.com/pingcap/dm/pull/382) -- 修复使用 DM-ansible 滚动升级 DM 监控过程中出错导致升级失败的问题 [#408](https://github.com/pingcap/dm/pull/408) diff --git a/v3.1/reference/tools/data-migration/skip-replace-sqls.md b/v3.1/reference/tools/data-migration/skip-replace-sqls.md deleted file mode 100644 index 20eafa07bf53..000000000000 --- a/v3.1/reference/tools/data-migration/skip-replace-sqls.md +++ /dev/null @@ -1,661 +0,0 @@ ---- -title: 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 -category: reference ---- - -# 跳过 (skip) 或替代执行 (replace) 异常的 SQL 语句 - -本文介绍了如何使用 DM 来处理异常的 SQL 语句。 - -目前，TiDB 并不完全兼容所有的 MySQL 语法。当使用 DM 从 MySQL 同步数据到 TiDB 时，如果 TiDB 不支持对应的 SQL 语句，可能会造成错误并中断同步任务。在这种情况下，DM 提供以下两种方式来恢复同步： - -- 使用 dmctl 来手动跳过该 SQL 语句对应的 binlog event。 - -- 使用 dmctl 来手动指定其他 SQL 语句来替代该 SQL 语句对应的 binlog event，并向下游执行。 - -如果提前预知将要同步 TiDB 不支持的 SQL 语句，也可以使用 dmctl 来手动预设跳过/替代执行操作。当 DM 尝试将该 SQL 语句对应的 binlog event 同步到下游时，该预设的操作将自动执行，从而避免同步过程被中断。 - -## 使用限制 - -- 跳过/替代执行操作只适合用于一次性跳过/替代执行**下游 TiDB 不支持执行的 SQL 语句**，其它同步错误请不要使用此方式进行处理。 - - - 其它同步错误可尝试使用 [black & white table lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) 或 [binlog event filter](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter)。 - -- 如果业务不能接受下游 TiDB 跳过异常的 DDL 语句，也不接受使用其他 DDL 语句作为替代，则不适合使用此方式进行处理。 - - - 比如：`DROP PRIMARY KEY` - - 这种情况下，只能在下游重建一个（DDL 执行完后的）新表结构对应的表，并将原表的全部数据重新导入该新表。 - -- 单次跳过/替代执行操作都是针对单个 binlog event 的。 - -- `--sharding` 仅用于对 sharding group 预设一些操作，并且必须在 DDL 语句执行之前预设，不能在 DDL 语句已经执行后预设。 - - - `--sharding` 模式下只支持预设，并只能使用 `--sql-pattern` 来匹配 binlog event。 - - 有关使用 DM 处理 sharding DDL 同步的原理，请参阅[分库分表合并同步原理](/v3.1/reference/tools/data-migration/features/shard-merge.md#实现原理)。 - -## 匹配 binlog event - -当同步任务由于执行 SQL 语句出错而中断时，可以使用 `query-error` 命令获取对应 binlog event 的 position 信息。在执行 `sql-skip` / `sql-replace` 时，通过指定该 position 信息，即可与对应的 binlog event 进行匹配。 - -然而，在同步中断前主动处理不被支持的 SQL 语句的情况下，由于无法提前预知 binlog event 的 position 信息，则需要使用其他方式来确保与后续将到达的 binlog event 进行匹配。 - -在 DM 中，支持如下两种 binlog event 匹配模式（两种模式只能选择其中一种）： - -1. binlog position：binlog event 的 position 信息 - - - binlog position 在命令中使用 `--binlog-pos` 参数传入，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - DM 中 binlog filename 的格式与上游 MySQL 中 binlog filename 的格式不完全一致。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -2. DDL pattern：（仅限于 DDL 语句的）正则表达式匹配模式 - - - DDL pattern 在命令中使用 `--sql-pattern` 参数传入，如要匹配 ```ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` ```，则对应的正则表达式为 ```~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` ```。 - - 正则表达式必须以 `~` 为前缀，且不包含任何原始空格（正则表达式字符串中的空格均以 `\s` 或 `\s+` 表示）。 - -对于合库合表场景，如果需要由 DM 自动选择 DDL lock owner 来执行跳过/替代执行操作，则由于不同 DM-worker 上 DDL 语句对应的 binlog position 无逻辑关联且难以确定，因此只能使用 DDL pattern 匹配模式。 - -> **注意：** -> -> - 一个 binlog event 只能注册一个使用 `--binlog-pos` 指定的 operator，后注册的 operator 会覆盖之前已经注册的 operator。 -> - 不要尝试为一个 binlog event 同时使用 `--binlog-pos` 和 `--sql-pattern` 指定 operator。 -> - operator 在与 binlog event 匹配成功后（而非执行成功后）即会被删除，后续如果需要再进行（`--sql-pattern`）匹配则必须重新注册。 - -## 支持场景 - -- 场景一：同步过程中，上游执行了 TiDB 不支持的 DDL 语句并同步到了 DM，造成同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 跳过对该 DDL 语句的同步以恢复同步任务。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 替代该 DDL 的同步以恢复同步任务。 - -- 场景二：同步过程中，预先知道了上游将执行 TiDB 不支持的 DDL 语句，则需要提前处理以避免同步任务中断。 - - - 如果业务能接受下游 TiDB 不执行该 DDL 语句，则使用 `sql-skip` 预设一个跳过该 DDL 语句的操作，当执行到该 DDL 语句时即自动跳过。 - - 如果业务能接受下游 TiDB 执行其他 DDL 语句来作为替代，则使用 `sql-replace` 预设一个替代该 DDL 语句的操作，当执行到该 DDL 语句时即自动替代。 - -## 实现原理 - -DM 在进行增量数据同步时，简化后的流程大致为： - -1. relay 处理单元从上游拉取 binlog 存储在本地作为 relay log。 - -2. binlog 同步单元（sync）读取本地 relay log，获取其中的 binlog event。 - -3. binlog 同步单元解析该 binlog event 并构造 DDL/DML 语句，然后将这些语句向下游 TiDB 执行。 - -在 binlog 同步单元解析完 binlog event 并向下游 TiDB 执行时，可能会由于 TiDB 不支持对应的 SQL 语句而报错并造成同步中断。 - -在 DM 中，可以为 binlog event 注册一些跳过/替代执行操作（operator）。在向下游 TiDB 执行 SQL 语句前，将当前的 binlog event 信息（position、DDL 语句）与注册的 operator 进行比较。如果 position 或 DDL 语句与注册的某个 operator 匹配，则执行该 operator 对应的操作并将该 operator 移除。 - -**同步中断后使用 `sql-skip` 或 `sql-replace` 恢复同步的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 binlog position 或 DDL pattern 注册 operator。 - -2. 使用 `resume-task` 恢复之前由于同步出错导致中断的任务。 - -3. 重新解析获得之前造成同步出错的 binlog event。 - -4. 该 binlog event 与第一步注册的 operator 匹配成功。 - -5. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -**同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace` 为指定的 DDL pattern 注册 operator。 - -2. 从 relay log 中解析获得 binlog event。 - -3. （包含 TiDB 不支持 SQL 语句的）binlog event 与第一步注册的 operator 匹配成功。 - -4. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务，任务不发生中断。 - -**合库合表同步中断前使用 `sql-skip` 或 `sql-replace` 预设操作以避免同步中断的流程** - -1. 使用 `sql-skip` 或 `sql-replace`（在 DM-master 上）为指定的 DDL pattern 注册 operator。 - -2. 各 DM-worker 从 relay log 中解析获得 binlog event。 - -3. DM-master 协调各个 DM-worker 进行 DDL lock 同步。 - -4. DM-master 判断得知 DDL lock 同步成功后，将第一步注册的 operator 发送给 DDL lock owner。 - -5. DM-master 请求 DDL lock owner 执行 DDL 语句。 - -6. DDL lock owner 将要执行的 DDL 语句与第四步收到的 operator 匹配成功。 - -7. 执行 operator 对应的操作（跳过/替代执行）后，继续执行同步任务。 - -## 命令介绍 - -使用 dmctl 手动处理 TiDB 不支持的 SQL 语句时，主要使用的命令包括 `query-status`、`query-error`、`sql-skip` 和 `sql-replace`。 - -### query-status - -`query-status` 命令用于查询当前 DM-worker 内子任务及 relay 单元等的状态，详见[查询状态](/v3.1/reference/tools/data-migration/query-status.md)。 - -### query-error - -`query-error` 命令用于查询 DM-worker 内子任务及 relay 单元当前在运行中存在的错误。 - -#### 命令用法 - -```bash -query-error [--worker=127.0.0.1:8262] [task-name] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`，可选； - - 不指定时查询所有 DM-worker 上的错误，指定时仅查询特定一组 DM-worker 上的错误。 - -+ `task-name`： - - 非 flag 参数，string，可选； - - 不指定时查询所有任务内的错误，指定时仅查询特定任务内的错误。 - -#### 结果示例 - -{{< copyable "" >}} - -```bash -» query-error test -``` - -``` -{ - "result": true, # query-error 操作本身是否成功 - "msg": "", # query-error 操作失败的说明信息 - "workers": [ # DM-worker 信息列表 - { - "result": true, # 该 DM-worker 上 query-error 操作是否成功 - "worker": "127.0.0.1:8262", # 该 DM-worker 的 IP:port（worker-id） - "msg": "", # 该 DM-worker 上 query-error 操作失败的说明信息 - "subTaskError": [ # 该 DM-worker 上运行子任务的错误信息 - { - "name": "test", # 任务名 - "stage": "Paused", # 当前任务的状态 - "unit": "Sync", # 当前正在处理任务的处理单元 - "sync": { # binlog 同步单元（sync）的错误信息 - "errors": [ # 当前处理单元的错误信息列表 - { - // 错误信息描述 - "msg": "exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, err:Error 1105: unsupported modify column length 10 is less than origin 11", - // 发生错误的 binlog event 的 position - "failedBinlogPosition": "mysql-bin|000001.000003:34642", - // 发生错误的 SQL 语句 - "errorSQL": "[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]" - } - ] - } - } - ], - "RelayError": { # 该 DM-worker 上 relay 处理单元的错误信息 - "msg": "" # 错误信息描述 - } - } - ] -} -``` - -### sql-skip - -`sql-skip` 命令用于预设一个跳过操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该跳过操作。 - -#### 命令用法 - -```bash -sql-skip <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -#### 参数解释 - -+ `worker`： - - flag 参数，string，`--worker`； - - 未指定 `--sharding` 时必选，指定 `--sharding` 时禁止使用； - - `worker` 指定预设操作将生效的 DM-worker。 - -+ `binlog-pos`： - - flag 参数，string，`--binlog-pos`； - - `binlog-pos` 与 `--sql-pattern` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `binlog-pos` 与 binlog event 的 position 匹配时生效，格式为 `binlog-filename:binlog-pos`，如 `mysql-bin|000001.000003:3270`。 - - 在同步执行出错后，binlog position 可直接从 `query-error` 返回的 `failedBinlogPosition` 中获得。 - -+ `sql-pattern`： - - flag 参数，string，`--sql-pattern`； - - `--sql-pattern` 与 `binlog-pos` 必须指定其中一个，且只能指定其中一个。 - - 在指定时表示操作将在 `sql-pattern` 与 binlog event 对应的（经过可选的 router-rule 转换后的）DDL 语句匹配时生效。格式为以 `~` 为前缀的正则表达式，如 ```~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT```。 - - 暂时不支持正则表达式中包含原始空格，需要使用 `\s` 或 `\s+` 替代空格。 - - 正则表达式必须以 `~` 为前缀，详见[正则表达式语法](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。 - - 正则表达式中的库名和表名必须是经过可选的 router-rule 转换后的名字，即对应下游的目标库名和表名。如上游为 ``` `shard_db_1`.`shard_tbl_1` ```，下游为 ``` `shard_db`.`shard_tbl` ```，则应该尝试匹配 ``` `shard_db`.`shard_tbl` ```。 - - 正则表达式中的库名、表名及列名需要使用 ``` ` ``` 标记，如 ``` `db1`.`tbl1` ```。 - -+ `sharding`： - - flag 参数，boolean，`--sharding`； - - 未指定 `--worker` 时必选，指定 `--worker` 时禁止使用； - - 在指定时表示预设的操作将在 sharding DDL 同步过程中的 DDL lock owner 内生效。 - -+ `task-name`： - - 非 flag 参数，string，必选； - - 指定预设的操作将生效的任务。 - -### sql-replace - -`sql-replace` 命令用于预设一个替代执行操作，当 binlog event 的 position 或 SQL 语句与指定的 `binlog-pos` 或 `sql-pattern` 匹配时，执行该替代执行操作。 - -#### 命令用法 - -```bash -sql-replace <--worker=127.0.0.1:8262> [--binlog-pos=mysql-bin|000001.000003:3270] [--sql-pattern=~(?i)ALTER\s+TABLE\s+`db1`.`tbl1`\s+ADD\s+COLUMN\s+col1\s+INT] [--sharding] -``` - -#### 参数解释 - -+ `worker`： - - 与 `sql-skip` 命令的 `--worker` 参数解释一致。 - -+ `binlog-pos`： - - 与 `sql-skip` 命令的 `--binlog-pos` 参数解释一致。 - -+ `sql-pattern`： - - 与 `sql-skip` 命令的 `--sql-pattern` 参数解释一致。 - -+ `sharding`： - - 与 `sql-skip` 命令的 `--sharding` 参数解释一致。 - -+ `task-name`： - - 与 `sql-skip` 命令的 `task-name` 参数解释一致。 - -+ `SQLs`： - - 非 flag 参数，string，必选； - - `SQLs` 指定将用于替代原 binlog event 的新的 SQL 语句。多条 SQL 语句间以 `;` 分隔，如 ```ALTER TABLE shard_db.shard_table drop index idx_c2;ALTER TABLE shard_db.shard_table DROP COLUMN c2;```。 - -## 使用示例 - -### 同步中断后被动执行跳过操作 - -#### 应用场景 - -假设现在需要将上游的 `db1.tbl1` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE db1.tbl1; -``` - -``` -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl1 | CREATE TABLE `tbl1` ( - `c1` int(11) NOT NULL, - `c2` decimal(11,3) DEFAULT NULL, - PRIMARY KEY (`c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（将列的 DECIMAL(11, 3) 修改为 DECIMAL(10, 3)）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE db1.tbl1 CHANGE c2 c2 DECIMAL (10, 3); -``` - -则会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -``` -exec sqls[[USE `db1`; ALTER TABLE `db1`.`tbl1` CHANGE COLUMN `c2` `c2` decimal(10,3);]] failed, -err:Error 1105: unsupported modify column length 10 is less than origin 11 -``` - -此时使用 `query-status` 查询任务状态，可看到 `stage` 转为了 `Paused`，且 `errors` 中有相关的错误描述信息。 - -使用 `query-error` 可以获取该错误的详细信息。比如，执行 `query-error test` 可获得出错的 binlog event 的 position（`failedBinlogPosition`）为 `mysql-bin|000001.000003:34642`。 - -#### 被动跳过 SQL 语句 - -假设业务上可以接受下游 TiDB 不执行此 DDL 语句（即继续保持原有的表结构），则可以通过使用 `sql-skip` 命令跳过该 DDL 语句以恢复同步任务。操作步骤如下： - -1. 使用 `query-error` 获取同步出错的 binlog event 的 position 信息。 - - position 信息可直接由 `query-error` 返回的 `failedBinlogPosition` 获得。 - - 本示例中的 position 为 `mysql-bin|000001.000003:34642`。 - -2. 使用 `sql-skip` 预设一个 binlog event 跳过操作，该操作将在使用 `resume-task` 后同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-skip --worker=127.0.0.1:8262 --binlog-pos=mysql-bin|000001.000003:34642 test - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 11:17:51 operator.go:121: [info] [sql-operator] set a new operator - uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - on replication unit - ``` - -3. 使用 `resume-task` 恢复之前出错中断的同步任务。 - - {{< copyable "" >}} - - ```bash - » resume-task --worker=127.0.0.1:8262 test - ``` - - ``` - { - "op": "Resume", - "result": true, - "msg": "", - "workers": [ - { - "op": "Resume", - "result": true, - "worker": "127.0.0.1:8262", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 11:27:46 operator.go:158: [info] [sql-operator] binlog-pos (mysql-bin|000001.000003, 34642) matched, - applying operator uuid: 6bfcf30f-2841-4d70-9a34-28d7082bdbd7, pos: (mysql-bin|000001.000003, 34642), op: SKIP, args: - ``` - -4. 使用 `query-status` 确认该任务的 `stage` 已经转为 `Running`。 - -5. 使用 `query-error` 确认原错误信息已不再存在。 - -### 同步中断前主动执行替代执行操作 - -#### 应用场景 - -假设现在需要将上游的 `db2.tbl2` 表同步到下游 TiDB（非合库合表同步场景），初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE db2.tbl2; -``` - -``` -+-------+--------------------------------------------------+ -| Table | Create Table | -+-------+--------------------------------------------------+ -| tbl2 | CREATE TABLE `tbl2` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+-------+--------------------------------------------------+ -``` - -此时，上游执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE db2.tbl2 DROP COLUMN c2; -``` - -当同步该 DDL 语句对应的 binlog event 到下游时，会由于 TiDB 不支持该 DDL 语句而导致 DM 同步任务中断且报如下错误： - -``` -exec sqls[[USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 为该 DDL 语句预设一个跳过（skip）或替代执行（replace）操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP 列 c2。 - -#### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的 DDL 语句（经过可选的 router-rule 转换后的 DDL 语句）设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE db2.tbl2 DROP COLUMN c2;`。 - - 由于该 DDL 语句不存在 router-rule 转换，可设计如下正则表达式： - - ``` - ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`; - ``` - -3. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-replace --worker=127.0.0.1:8262 --sql-pattern=~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2;ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - - ``` - { - "result": true, - "msg": "", - "workers": [ - { - "result": true, - "worker": "", - "msg": "" - } - ] - } - ``` - - 对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 15:33:13 operator.go:121: [info] [sql-operator] set a new operator - uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - on replication unit - ``` - -4. 在上游 MySQL 执行该 DDL 语句。 - -5. 观察下游表结构是否变更成功，对应 DM-worker 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 15:33:45 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `db2`; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2`;, - applying operator uuid: c699a18a-8e75-47eb-8e7e-0e5abde2053c, - pattern: ~(?i)ALTER\s+TABLE\s+`db2`.`tbl2`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `db2`.`tbl2` DROP INDEX idx_c2; ALTER TABLE `db2`.`tbl2` DROP COLUMN `c2` - ``` - -6. 使用 `query-status` 确认该任务的 `stage` 持续为 `Running`。 - -7. 使用 `query-error` 确认不存在 DDL 执行错误。 - -### 合库合表场景下同步中断后被动执行跳过操作 - -#### 应用场景 - -假设现在通过多个 DM-worker 将上游多个 MySQL 实例内的多个表进行合库合表同步到下游 TiDB 的同一个表，并且上游各分表执行了 TiDB 不支持的 DDL 语句。 - -DM-master 通过 DDL lock 协调 DDL 同步、并请求 DDL lock owner 向下游 TiDB 执行该 DDL 语句后，由于 TiDB 不支持该 DDL 语句，同步任务会报错并中断。 - -#### 被动跳过 SQL 语句 - -合库合表场景下，被动跳过 TiDB 不支持的 DDL 语句的处理方式与非合库合表场景下的[同步中断后被动执行跳过操作](#同步中断后被动执行跳过操作)基本一致。 - -但在合库合表场景下，只需要 DDL lock owner 向下游同步该 DDL 语句，因此在两种场景下的处理过程主要存在以下区别： - -1. 合库合表场景下，仅需要对 DDL lock owner 执行 `sql-skip`（`--worker={DDL-lock-owner}`）。 - -2. 合库合表场景下，仅需要对 DDL lock owner 执行 `resume-task`（`--worker={DDL-lock-owner}`）。 - -### 合库合表场景下同步中断前主动执行替代执行操作 - -#### 应用场景 - -假设现在存在如下四个上游表需要合并同步到下游的同一个表 ``` `shard_db`.`shard_table` ```： - -- MySQL 实例 1 内有 `shard_db_1` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 -- MySQL 实例 2 内有 `shard_db_2` 逻辑库，包括 `shard_table_1` 和 `shard_table_2` 两个表。 - -初始时表结构为： - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE shard_db_1.shard_table_1; -``` - -``` -+---------------+------------------------------------------+ -| Table | Create Table | -+---------------+------------------------------------------+ -| shard_table_1 | CREATE TABLE `shard_table_1` ( - `c1` int(11) NOT NULL, - `c2` int(11) DEFAULT NULL, - PRIMARY KEY (`c1`), - KEY `idx_c2` (`c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 | -+---------------+------------------------------------------+ -``` - -此时，在上游所有分表上都执行以下 DDL 操作修改表结构（即 DROP 列 c2）： - -{{< copyable "sql" >}} - -```sql -ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2; -``` - -则当 DM 通过 sharding DDL lock 协调两个 DM-worker 同步该 DDL 语句、并请求 DDL lock owner 向下游执行该 DDL 语句时，会由于 TiDB 不支持该 DDL 语句而导致同步任务中断且报如下错误： - -``` -exec sqls[[USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;]] failed, -err:Error 1105: can't drop column c2 with index covered now -``` - -**但如果在上游实际执行该 DDL 语句前，你已提前知道该 DDL 语句不被 TiDB 所支持**。则可以使用 `sql-skip` 或 `sql-replace` 命令为该 DDL 语句预设一个跳过/替代执行操作。 - -对于本示例中的 DDL 语句，由于 TiDB 暂时不支持 DROP 存在索引的列，因此可以使用两条新的 SQL 语句来进行替代执行操作，即可以先 DROP 索引、然后再 DROP c2 列。 - -#### 主动替代执行该 SQL 语句 - -1. 为将要在上游执行的（经过可选的 router-rule 转换后的）DDL 语句设计一个能匹配上的正则表达式。 - - 上游将执行的 DDL 语句为 `ALTER TABLE shard_db_*.shard_table_* DROP COLUMN c2`。 - - 由于存在 router-rule 会将表名转换为 ``` `shard_db`.`shard_table` ```，可设计如下正则表达式： - - ``` - ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` - ``` - -2. 为该 DDL 语句设计将用于替代执行的新的 DDL 语句： - - {{< copyable "sql" >}} - - ```sql - ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - -3. 由于这是合库合表场景，因此使用 `--sharding` 参数来由 DM 自动确定替代执行操作只发生在 DDL lock owner 上。 - -4. 使用 `sql-replace` 预设一个 binlog event 替代执行操作，该操作将在同步该 binlog event 到下游时生效。 - - {{< copyable "" >}} - - ```bash - » sql-replace --sharding --sql-pattern=~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` test ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - ``` - { - "result": true, - "msg": "request with --sharding saved and will be sent to DDL lock's owner when resolving DDL lock", - "workers": [ - ] - } - ``` - - **DM-master** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:53:33 operator.go:105: [info] [sql-operator] set a new operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" - op:REPLACE args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -5. 在上游 MySQL 实例的分表上执行 DDL 语句。 - -6. 观察下游表结构是否变更成功，对应的 DDL lock **owner** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:54:35 operator.go:121: [info] [sql-operator] set a new operator - uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - on replication unit - ``` - - ``` - 2018/12/28 16:54:35 operator.go:158: [info] [sql-operator] - sql-pattern ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`;, - applying operator uuid: c959f2fb-f1c2-40c7-a1fa-e73cd51736dd, - pattern: ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2`, - op: REPLACE, args: ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2` - ``` - - 另外，**DM-master** 节点中也可以看到类似如下日志： - - ``` - 2018/12/28 16:54:35 operator.go:122: [info] [sql-operator] get an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - with key ~(?i)ALTER\s+TABLE\s+`shard_db`.`shard_table`\s+DROP\s+COLUMN\s+`c2` matched SQL - USE `shard_db`; ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`; - ``` - - ``` - 2018/12/28 16:54:36 operator.go:145: [info] [sql-operator] remove an operator - uuid: eba35acd-6c5e-4bc3-b0b0-ae8bd1232351, request: name:"test" op:REPLACE - args:"ALTER TABLE `shard_db`.`shard_table` DROP INDEX idx_c2;" - args:"ALTER TABLE `shard_db`.`shard_table` DROP COLUMN `c2`" - sqlPattern:"~(?i)ALTER\\s+TABLE\\s+`shard_db`.`shard_table`\\s+DROP\\s+COLUMN\\s+`c2`" - sharding:true - ``` - -7. 使用 `query-status` 确认任务的 `stage` 持续为 `Running`，且不存在正阻塞同步的 DDL 语句（`blockingDDLs`）与待解决的 sharding group（`unresolvedGroups`）。 - -8. 使用 `query-error` 确认不存在 DDL 执行错误。 - -9. 使用 `show-ddl-locks` 确认不存在待解决的 DDL lock。 diff --git a/v3.1/reference/tools/data-migration/table-selector.md b/v3.1/reference/tools/data-migration/table-selector.md deleted file mode 100644 index 177548431eb6..000000000000 --- a/v3.1/reference/tools/data-migration/table-selector.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Table Selector -summary: 介绍 DM 的 Table Selector -category: reference ---- - -# Table Selector - -Table Selector 提供了一种基于[通配符](https://zh.wikipedia.org/wiki/%E9%80%9A%E9%85%8D%E7%AC%A6) 来匹配指定 `schema/table` 的功能。 - -## 通配符 - -table selector 在 `schema-pattern`/`table-pattern` 中可以使用以下两个通配符： - -+ 星号(`*`) - - 匹配零个或者多个字符。例如， `doc*` 匹配 `doc` 和 `document`，但是不匹配 `dodo`。 - - `*` 只能放在 pattern 的最后一位，例如，支持 `doc*`，但是不支持 `do*c`。 - -+ 问号(`?`) - - 匹配任意一个空字符除外的字符。 - -## 匹配规则 - -- `schema-pattern` 限制不能为空； -- `table-pattern` 可以设置为空。设置为空时，将只根据 `schema-pattern` 对 `schema` 进行匹配，然后返回匹配结果； -- `table-pattern` 不为空时，分别根据 `schema-pattern` 和 `table-pattern` 进行匹配，两个都匹配则结果为匹配。 - -## 使用示例 - -- 匹配所有库名以 `schema_` 开头的 schema 和 table - - ```yaml - schema-pattern： "schema_*" - table-pattern： "" - ``` - -- 匹配所有库名以 `schema_` 为前缀，并且表名以 `table_` 前缀的表 - - ```yaml - schema-pattern = "schema_*" - table-pattern = "table_*" - ``` diff --git a/v3.1/reference/tools/data-migration/troubleshoot/dm.md b/v3.1/reference/tools/data-migration/troubleshoot/dm.md deleted file mode 100644 index 154d8420de90..000000000000 --- a/v3.1/reference/tools/data-migration/troubleshoot/dm.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Data Migration 故障诊断 -category: reference ---- - -# Data Migration 故障诊断 - -本文总结了在 DM 工具使用过程中遇到问题的诊断流程，并指引用户通过错误信息查找相应的解决方案。 - -如果你在运行 DM 工具时出现了错误，请尝试以下解决方案： - -1. 执行 `query-status` 命令查看任务运行状态以及相关错误输出。 - -2. 查看与该错误相关的日志文件。日志文件位于 DM-master、DM-worker 部署节点上，通过 [Data Migration 错误含义](/v3.1/reference/tools/data-migration/troubleshoot/error-system.md) 获取错误的关键信息，然后查看 [Data Migration 常见错误及修复](/v3.1/reference/tools/data-migration/troubleshoot/error-handling.md)以寻找相应的解决方案。 - -3. 如果该错误还没有相应的解决方案，并且你无法通过查询日志或监控指标自行解决此问题，你可以联系相关销售人员进行支持。 - -4. 一般情况下，错误处理完成后，只需使用 dmctl 重启任务即可。 - - {{< copyable "shell-regular" >}} - - ```bash - resume-task ${task name} - ``` - -但在某些情况下，你还需要重置数据同步任务。有关何时需要重置以及如何重置，详见[重置数据同步任务](/v3.1/reference/tools/data-migration/faq.md#重置数据同步任务)。 diff --git a/v3.1/reference/tools/data-migration/troubleshoot/error-handling.md b/v3.1/reference/tools/data-migration/troubleshoot/error-handling.md deleted file mode 100644 index 9008f8993b22..000000000000 --- a/v3.1/reference/tools/data-migration/troubleshoot/error-handling.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Data Migration 常见错误修复 -category: reference ---- - -# Data Migration 常见错误修复 - -本文档介绍 DM 中常见的错误以及修复方法。 - -## 常见错误说明和处理方法 - -| 错误码 | 错误说明 | 解决方法 | -| :----------- | :------------------------------------------------------------ | :----------------------------------------------------------- | -| `code=10001` | 数据库操作异常 | 进一步分析错误信息和错误堆栈 | -| `code=10002` | 数据库底层的 `bad connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 | DM 提供针对此类错误的自动恢复。如果长时间未恢复，需要用户检查网络或 TiDB 状态。 | -| `code=10003` | 数据库底层 `invalid connection` 错误，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 | DM 提供针对此类错误的自动恢复。如果未能正常恢复，需要用户进一步检查错误信息并根据具体场景进行分析。 | -| `code=10005` | 数据库查询类语句出错 | | -| `code=10006` | 数据库 `EXECUTE` 类型语句出错，包括 DDL 和 `INSERT`/`UPDATE`/`DELETE` 类型的 DML。更详细的错误信息可通过错误 message 获取。错误 message 中通常包含操作数据库所返回的错误码和错误信息。 | | -| `code=11006` | DM 内置的 parser 解析不兼容的 DDL 时出错 | 可参考 [Data Migration 故障诊断-处理不兼容的 DDL 语句](/v3.1/reference/tools/data-migration/faq.md#处理不兼容的-ddl-语句) 提供的解决方案 | -| `code=20010` | 处理任务配置时，解密数据库的密码出错 | 检查任务配置中提供的下游数据库密码是否有[使用 dmctl 正确加密](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码) | -| `code=26002` | 任务检查创建数据库连接失败。更详细的错误信息可通过错误 message 获取。错误 message 中包含操作数据库所返回的错误码和错误信息。 | 检查 DM-master 所在的机器是否有权限访问上游 | -| `code=32001` | dump 处理单元异常 | 如果报错 `msg` 包含 `mydumper: argument list too long.`，则需要用户根据 black-white list，在 `task.yaml` 的 mydumper `extra-args` 参数中手动加上 `--regex` 正则表达式设置要导出的库表。例如，如果要导出所有库中表名字为 `hello` 的表，可加上 `--regex '.*\\.hello$'`，如果要导出所有表，可加上 `--regex '.*'`。 | -| `code=38008` | DM 组件间的 gRPC 通信出错 | 检查 `class`， 定位错误发生在哪些组件的交互环节，根据错误 message 判断是哪类通信错误。如果是 gRPC 建立连接出错，可检查通信服务端是否运行正常。 | - -## 同步任务中断并包含 `invalid connection` 错误 - -发生 `invalid connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。 - -由于 DM 中存在同步任务并发向下游复制数据的特性，因此在任务中断时可能同时包含多个错误（可通过 `query-status` 或 `query-error` 查询当前错误）。 - -- 如果错误中仅包含 `invalid connection` 类型的错误且当前处于增量复制阶段，则 DM 会自动进行重试。 -- 如果 DM 由于版本问题等未自动进行重试或自动重试未能成功，则可尝试先使用 `stop-task` 停止任务，然后再使用 `start-task` 重启任务。 - -## 同步任务中断并包含 `driver: bad connection` 错误 - -发生 `driver: bad connection` 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。 - -当前版本 DM 发生该类型错误时，需要先使用 `stop-task` 停止任务后再使用 `start-task` 重启任务。后续 DM 会完善对此错误类型的自动重试机制。 - -## relay 处理单元报错 `event from * in * diff from passed-in event *` 或同步任务中断并包含 `get binlog error ERROR 1236 (HY000)`、`binlog checksum mismatch, data may be corrupted` 等 binlog 获取或解析失败错误 - -在 DM 进行 relay log 拉取与增量同步过程中，如果遇到了上游超过 4GB 的 binlog 文件，就可能出现这两个错误。 - -原因是 DM 在写 relay log 时需要依据 binlog position 及文件大小对 event 进行验证，且需要保存同步的 binlog position 信息作为 checkpoint。但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，进而出现上面的错误。 - -对于 relay 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 停止 DM-worker。 -3. 将上游对应的 binlog 文件复制到 relay log 目录作为 relay log 文件。 -4. 更新 relay log 目录内对应的 `relay.meta` 文件以从下一个 binlog 开始拉取。 - - 例如：报错时有 `binlog-name = "mysql-bin.004451"` 与`binlog-pos = 2453`，则将其分别更新为 `binlog-name = "mysql-bin.004452"` 与`binlog-pos = 4`。 -5. 重启 DM-worker。 - -对于 binlog replication 处理单元，可通过以下步骤手动恢复： - -1. 在上游确认出错时对应的 binlog 文件的大小超出了 4GB。 -2. 通过 `stop-task` 停止同步任务。 -3. 将下游 `dm_meta` 数据库中 global checkpoint 与每个 table 的 checkpoint 中的 `binlog_name` 更新为出错的 binlog 文件，将 `binlog_pos` 更新为已同步过的一个合法的 position 值，比如 4。 - - 例如：出错任务名为 `dm_test`，对应的 `source-id` 为 `replica-1`，出错时对应的 binlog 文件为 `mysql-bin|000001.004451`，则执行 `UPDATE dm_test_syncer_checkpoint SET binlog_name='mysql-bin|000001.004451', binlog_pos = 4 WHERE id='replica-1';`。 -4. 在同步任务配置中为 `syncers` 部分设置 `safe-mode: true` 以保证可重入执行。 -5. 通过 `start-task` 启动同步任务。 -6. 通过 `query-status` 观察同步任务状态，当原造成出错的 relay log 文件同步完成后，即可还原 `safe-mode` 为原始值并重启同步任务。 - -## 执行 `query-status` 或查看日志时出现 `Access denied for user 'root'@'172.31.43.27' (using password: YES)` - -在所有 DM 配置文件中，数据库相关的密码都必须使用经 dmctl 加密后的密文（若数据库密码为空，则无需加密）。有关如何使用 dmctl 加密明文密码，参见[使用 dmctl 加密上游 MySQL 用户密码](/v3.1/how-to/deploy/data-migration-with-ansible.md#使用-dmctl-加密上游-mysql-用户密码)。 - -此外，在 DM 运行过程中，上下游数据库的用户必须具备相应的读写权限。在启动同步任务过程中，DM 会自动进行相应权限的前置检查，详见[上游 MySQL 实例配置前置检查](/v3.1/reference/tools/data-migration/precheck.md)。 diff --git a/v3.1/reference/tools/data-migration/troubleshoot/error-system.md b/v3.1/reference/tools/data-migration/troubleshoot/error-system.md deleted file mode 100644 index 3d5f69c5be65..000000000000 --- a/v3.1/reference/tools/data-migration/troubleshoot/error-system.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Data Migration 错误说明 -category: reference ---- - -# Data Migration 错误说明 - -本文介绍了 Data Migration (DM) 的错误系统，以及各种错误信息的详细含义。 - -## DM 错误系统 - -DM 1.0.0-GA 版本中引入了新的错误系统。该系统： - -+ 增加了错误码机制。 -+ 增加了 `class`、`scope`、`level` 等错误信息。 -+ 优化了错误描述内容、错误调用链信息和调用堆栈信息。 - -错误系统的详细设计和实现，可参阅 [RFC 文档: Proposal: Improve Error System](https://github.com/pingcap/dm/blob/master/docs/RFCS/20190722_error_handling.md)。 - -## 错误信息示例 - -以下是 DM 实际输出的一条错误信息。本文根据这条信息，对各个字段作详细说明。 - -``` -[code=38008:class=dm-master:scope=internal:level=high] grpc request error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused" -github.com/pingcap/dm/pkg/terror.(*Error).Delegate - /root/code/gopath/src/github.com/pingcap/dm/pkg/terror/terror.go:267 -github.com/pingcap/dm/dm/master/workerrpc.callRPC - /root/code/gopath/src/github.com/pingcap/dm/dm/master/workerrpc/rawgrpc.go:124 -github.com/pingcap/dm/dm/master/workerrpc.(*GRPCClient).SendRequest - /root/code/gopath/src/github.com/pingcap/dm/dm/master/workerrpc/rawgrpc.go:64 -github.com/pingcap/dm/dm/master.(*Server).getStatusFromWorkers.func2 - /root/code/gopath/src/github.com/pingcap/dm/dm/master/server.go:1125 -github.com/pingcap/dm/dm/master.(*AgentPool).Emit - /root/code/gopath/src/github.com/pingcap/dm/dm/master/agent_pool.go:117 -runtime.goexit - /root/.gvm/gos/go1.12/src/runtime/asm_amd64.s:1337 -``` - -DM 中的错误信息均按以下固定格式输出： - -``` -[错误基本信息] + 错误 message 描述 + 错误堆栈信息（可选） -``` - -### 错误基本信息 - -- `code`：错误码，错误唯一标识。 - - 同一种错误都使用相同的错误码。错误码不随 DM 版本改变。 - - 在 DM 迭代过程中，部分错误可能会被移除，但错误码不会。新增的错误会使用新的错误码，不会复用已有的错误码。 - -- `class`：错误分类。 - - 用于标记出现错误的系统子模块。 - - 下表展示所有的错误类别、错误对应的系统子模块、错误样例： - - | 错误类别 | 错误对应的系统子模块 | 错误样例 | - | :-------------- | :------------------------------ | :------------------------------------------------------------ | - | `database` | 执行数据库操作出现错误 | `[code=10003:class=database:scope=downstream:level=medium] database driver: invalid connection` | - | `functional` | 系统底层的基础函数错误 | `[code=11005:class=functional:scope=internal:level=high] not allowed operation: alter multiple tables in one statement` | - | `config` | 配置错误 | `[code=20005:class=config:scope=internal:level=medium] empty source-id not valid` | - | `binlog-op` | binlog 操作出现错误 | `[code=22001:class=binlog-op:scope=internal:level=high] empty UUIDs not valid` | - | `checkpoint` | checkpoint 相关操作出现错误 | `[code=24002:class=checkpoint:scope=internal:level=high] save point bin.1234 is older than current pos bin.1371` | - | `task-check` | 进行任务检查时出现错误 | `[code=26003:class=task-check:scope=internal:level=medium] new table router error` | - | `relay-event-lib`| 执行 relay 模块基础功能时出现错误 | `[code=28001:class=relay-event-lib:scope=internal:level=high] parse server-uuid.index` | - | `relay-unit` | relay 处理单元内出现错误 | `[code=30015:class=relay-unit:scope=upstream:level=high] TCPReader get event: ERROR 1236 (HY000): Could not open log file` | - | `dump-unit` | dump 处理单元内出现错误 | `[code=32001:class=dump-unit:scope=internal:level=high] mydumper runs with error: CRITICAL **: 15:12:17.559: Error connecting to database: Access denied for user 'root'@'172.17.0.1' (using password: NO)` | - | `load-unit` | load 处理单元内出现错误 | `[code=34002:class=load-unit:scope=internal:level=high] corresponding ending of sql: ')' not found` | - | `sync-unit` | sync 处理单元内出现错误 | `[code=36027:class=sync-unit:scope=internal:level=high] Column count doesn't match value count: 9 (columns) vs 10 (values)` | - | `dm-master` | DM-master 服务内部出现错误 | `[code=38008:class=dm-master:scope=internal:level=high] grpc request error: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused"` | - | `dm-worker` | DM-worker 服务内部出现错误 | `[code=40066:class=dm-worker:scope=internal:level=high] ExecuteDDL timeout, try use query-status to query whether the DDL is still blocking` | - | `dm-tracer` | DM-tracer 服务内部出现错误 | `[code=42004:class=dm-tracer:scope=internal:level=medium] trace event test.1 not found` | - -- `scope`：错误作用域。 - - 用于标识错误发生时 DM 作用对象的范围和来源，包括未设置 (not-set)、上游数据库 (upstream)、下游数据库 (downstream)、内部 (internal) 四种类型。 - - 如果错误发生的逻辑直接涉及到上下游数据库请求，作用域会设置为 upstream 或 downstream，其他出错场景目前都设置为 internal。 - -- `level`：错误级别。 - - 错误的严重级别，包括低级别 (low)、中级别 (medium)、高级别 (high) 三种。 - - 低级别通常是用户操作、输入错误，不影响正常同步任务；中级别通常是用户配置等错误，会影响部分新启动服务，不影响已有系统同步状态；高级别通常是用户需要关注的一些错误，可能存在同步任务中断等风险，需要用户进行处理。 - -在上述的错误样例中： - -- `code=38008` 表示 gRPC 通信出错的错误码。 -- `class=dm-master`，表示 DM-master 对外发送 gRPC 请求时出错（请求发送至 DM-worker）。 -- `scope=interal` 表示 DM 内部出现错误。 -- `level=high`，表示这是一个高级别错误，需要用户注意。可根据错误 message 和错误堆栈判断出更多错误信息。 - -### 错误 message 描述 - -错误 message 使用描述性语言来表示错误的详细信息。对于错误调用链上每一层额外增加的错误 message，采用 [errors.Wrap](https://godoc.org/github.com/pkg/errors#hdr-Adding_context_to_an_error) 的模式来叠加和保存错误 message。wrap 最外层的 message 是 DM 内部对该错误的描述，wrap 最内层的 message 是该错误最底层出错位置的错误描述。 - -以上述样例错误的 message 为例： - -- wrap 最外层 message，`grpc request error` 是 DM 对该错误的描述。 -- wrap 最内层 message，`connection error: desc = "transport: Error while dialing dial tcp 172.17.0.2:8262: connect: connection refused"`，是 gRPC 底层建立连接失败时返回的错误。 - -通过对基本错误信息和错误 message 进行分析，可以诊断出错误是在 DM-master 向 DM-worker 发送 gRPC 请求建立连接失败时出现的。该错误通常是由 DM-worker 未正常运行引起。 - -### 错误堆栈信息 - -DM 根据错误的严重程度和必要性来选择是否输出错误堆栈。错误堆栈记录了错误发生时完整的堆栈调用信息。如果用户通过错误基本信息和错误 message 描述不能完全诊断出错误发生的原因，可以通过错误堆栈进一步跟进出错时代码的运行路径。 - -## 常见错误码描述及处理 - -可在 DM 代码仓库[已发布的错误码](https://github.com/pingcap/dm/blob/master/_utils/terror_gen/errors_release.txt)中查询完整的错误码列表。 diff --git a/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md b/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md deleted file mode 100644 index 62df557d4f16..000000000000 --- a/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 分表合并数据迁移最佳实践 -summary: 使用 DM 对分库分表进行合并迁移时的最佳实践。 -category: reference ---- -# 分表合并数据迁移最佳实践 - -本文阐述了使用 TiDB Data Migration（以下简称 DM）对分库分表进行合并迁移的场景中，DM 相关功能的支持和限制，旨在给出一个业务的最佳实践。 - -## 独立的数据迁移任务 - -在[分库分表合并同步的实现原理部分](/v3.1/reference/tools/data-migration/features/shard-merge.md#实现原理)，我们介绍了 sharding group 的概念，简单来说可以理解为需要合并到下游同一个表的所有上游表即组成一个 sharding group。 - -当前的 sharding DDL 算法为了能协调在不同分表执行 DDL 对 schema 变更的影响，加入了一些[使用限制](/v3.1/reference/tools/data-migration/features/shard-merge.md#使用限制)。而当这些使用限制由于某些异常原因被打破时，我们需要[手动处理 Sharding DDL Lock](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) 甚至是完整重做整个数据迁移任务。 - -因此，为了减小异常发生时对数据迁移的影响，我们推荐将每一个 sharding group 拆分成一个独立的数据迁移任务。**这样当异常发生时，可能只有少部分迁移任务需要进行手动处理，其他数据迁移任务可以不受影响。** - -## 手动处理 sharding DDL lock - -从[分库分表合并同步的实现原理部分](/v3.1/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，DM 中的 sharding DDL lock 是用于协调不同上游分表向下游执行 DDL 的一种机制，本身并不是异常。 - -因此，当通过 `show-ddl-locks` 查看到 DM-master 上存在 sharding DDL lock 时，或通过 `query-status` 查看到某些 DM-worker 有 `unresolvedGroups` 或 `blockingDDLs` 时，并不要急于使用 `unlock-ddl-lock` 或 `break-ddl-lock` 尝试去手动解除 sharding DDL lock。 - -只有在确认当前未能自动解除 sharding DDL lock 是文档中所列的[支持场景](/v3.1/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md#支持场景)之一时，才能参照对应支持场景中的手动处理示例进行处理。对于其他未被支持的场景，我们建议完整重做整个数据迁移任务，即清空下游数据库中的数据以及该数据迁移任务相关的 `dm_meta` 信息后，重新执行全量数据及增量数据的迁移。 - -## 自增主键冲突处理 - -在 DM 中，我们提供了 [Column mapping](/v3.1/reference/tools/data-migration/features/overview.md#column-mapping) 用于处理 bigint 类型的自增主键在合并时可能出现冲突的问题，但我们**强烈不推荐**使用该功能。如果业务上允许，我们推荐使用以下两种处理方式。 - -### 去掉自增主键的主键属性 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_no_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -- `auto_pk_c1` 列对业务无意义，且不依赖该列的 `PRIMARY KEY` 属性。 -- `uk_c2` 列有 `UNIQUE KEY` 属性，且能保证在所有上游分表间全局唯一。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但将 `auto_pk_c1` 的 `PRIMARY KEY` 属性修改为普通索引。 - - ```sql - CREATE TABLE `tbl_no_pk_2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uk_c2` bigint(20) NOT NULL, - `content_c3` text, - INDEX (`auto_pk_c1`), - UNIQUE KEY `uk_c2` (`uk_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 使用联合主键 - -假设上游分表的表结构如下： - -```sql -CREATE TABLE `tbl_multi_pk` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`) -) ENGINE=InnoDB DEFAULT CHARSET=latin1 -``` - -如果满足下列条件： - -* 业务不依赖 `auto_pk_c1` 的 `PRIMARY KEY` 属性。 -* `auto_pk_c1` 与 `uuid_c2` 的组合能确保全局唯一。 -* 业务能接受将 `auto_pk_c1` 与 `uuid_c2` 组成联合 `PRIMARY KEY`。 - -则可以用以下步骤处理合表时可能由 `auto_pk_c1` 导致的 `ERROR 1062 (23000): Duplicate entry '***' for key 'PRIMARY'` 问题： - -1. 在开始执行全量数据迁移前，在下游数据库创建用于合表迁移的表，但不为 `auto_pk_c1` 指定 `PRIMARY KEY` 属性，而是将 `auto_pk_c1` 与 `uuid_c2` 一起组成 `PRIMARY KEY`。 - - ```sql - CREATE TABLE `tbl_multi_pk_c2` ( - `auto_pk_c1` bigint(20) NOT NULL, - `uuid_c2` bigint(20) NOT NULL, - `content_c3` text, - PRIMARY KEY (`auto_pk_c1`,`uuid_c2`) - ) ENGINE=InnoDB DEFAULT CHARSET=latin1 - ``` - -2. 启动数据迁移任务，执行全量与增量数据迁移。 - -3. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -## 合表迁移过程中在上游增/删表 - -从[分库分表合并同步的实现原理部分](/v3.1/reference/tools/data-migration/features/shard-merge.md#实现原理)我们可以知道，sharding DDL lock 的协调依赖于是否已收到上游已有各分表对应的 DDL，且当前 DM 在合表迁移过程中暂时**不支持**在上游动态增加或删除分表。如果需要在合表迁移过程中，对上游执行增、删分表操作，推荐按以下方式进行处理。 - -### 在上游增加分表 - -如果需要在上游增加新的分表，推荐按以下顺序执行操作： - -1. 等待在上游分表上执行过的所有 sharding DDL 协调同步完成。 -2. 通过 `stop-task` 停止任务。 -3. 在上游添加新的分表。 -4. 确保 `task.yaml` 配置能使新添加的分表与其他已有的分表能合并到同一个下游表。 -5. 通过 `start-task` 启动任务。 -6. 通过 `query-status` 验证数据迁移任务是否正常，在下游数据库中验证合表中是否已经存在了来自上游的数据。 - -### 在上游删除分表 - -如果需要在上游删除原有的分表，推荐按以下顺序执行操作： - -1. 在上游删除原有的分表，并通过 [`SHOW BINLOG EVENTS`](https://dev.mysql.com/doc/refman/5.7/en/show-binlog-events.html) 获取该 `DROP TABLE` 语句在 binlog 中对应的 `End_log_pos`，记为 _Pos-M_。 -2. 通过 `query-status` 获取当前 DM 已经处理完成的 binlog event 对应的 position（`syncerBinlog`），记为 _Pos-S_。 -3. 当 _Pos-S_ 比 _Pos-M_ 更大后，则说明 DM 已经处理完 `DROP TABLE` 语句，且该表在被删除前的数据都已经同步到下游，可以进行后续操作；否则，继续等待 DM 进行数据同步。 -4. 通过 `stop-task` 停止任务。 -5. 确保 `task.yaml` 配置能忽略上游已删除的分表。 -6. 通过 `start-task` 启动任务。 -7. 通过 `query-status` 验证数据迁移任务是否正常。 - -## 数据迁移限速/流控 - -当将多个上游 MySQL/MariaDB 实例的数据合并迁移到下游同一个 TiDB 集群时，由于每个与上游 MySQL/MariaDB 对应的 DM-worker 都会并发地进行全量与增量数据迁移，默认的并发度（全量阶段的 `pool-size` 与增量阶段的 `worker-count`）通过多个 DM-worker 累加后，可能会给下游造成过大的压力，此时应根据 TiDB 监控及 DM 监控进行初步的性能分析后，适当地调整各并发度参数的大小。后续 DM 也将考虑支持部分自动的流控策略。 diff --git a/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md b/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md deleted file mode 100644 index 1b9e8cc00d0e..000000000000 --- a/v3.1/reference/tools/data-migration/usage-scenarios/master-slave-switch.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 切换 DM-worker 与上游 MySQL 实例的连接 -summary: 了解如何切换 DM-worker 与上游 MySQL 实例的连接。 -category: reference ---- - -# 切换 DM-worker 与上游 MySQL 实例的连接 - -当需要对 DM-worker 所连接的上游 MySQL 实例进行停机维护或该实例意外宕机时，需要将 DM-worker 的连接切换到同一个主从复制集群内的另一个 MySQL 实例上。本文介绍如何将 DM-worker 的连接从一个 MySQL 实例切换到另一个 MySQL 实例上。 - -> **注意：** -> -> - 仅支持在同一个主从复制集内的 MySQL 实例间进行切换。 -> - 将要切换到的 MySQL 实例必须拥有 DM-worker 所需的 binlog。 -> - DM-worker 必须以 GTID sets 模式运行，即 DM 通过 DM-Ansible 部署时必须指定 `enable_gtid=true`。 -> - DM 仅支持以下两种切换场景，且必须严格按照各场景的步骤执行操作，否则可能需要根据切换后的 MySQL 实例重新搭建 DM 集群并完整重做数据迁移任务。 - -有关 GTID sets 的概念解释，请参考 [MySQL 文档](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids-concepts.html#replication-gtids-concepts-gtid-sets)。 - -## 虚拟 IP 环境下切换 DM-worker 与 MySQL 实例的连接 - -如果 DM-worker 通过虚拟 IP (VIP) 连接上游的 MySQL 实例，更改 VIP 所指向的 MySQL 实例，即是在 DM-worker 对应上游连接地址不变的情况下切换 DM-worker 实际所连接的 MySQL 实例。 - -> **注意：** -> -> 如果不对 DM 执行必要变更，当切换 VIP 所指向的 MySQL 实例时，DM 内部不同的 connection 可能会同时连接到切换前后不同的 MySQL 实例，造成 DM 拉取的 binlog 与从上游获取到的其他状态不一致，从而导致难以预期的异常行为甚至数据损坏。 - -如果 DM-worker 连接的 VIP 需要指向新的 MySQL 实例，需要按以下步骤进行操作： - -1. 使用 `query-status` 命令获取当前 relay 处理单元已从原 MySQL 实例获取到的 binlog 对应的 GTID sets (`relayBinlogGtid`)，记为 `gtid-W`。 -2. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_purged;` 获取已经被 purged 的 binlog 对应的 GTID sets，记为 `gtid-P`。 -3. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_executed;` 获取所有已经执行成功的事务对应的 GTID sets，记为 `gtid-E`。 -4. 确保满足以下关系，否则不支持将 DM-worker 连接切换到相应的 MySQL 实例： - - `gtid-W` 包含 `gtid-P`（`gtid-P` 可以为空） - - `gtid-E` 包含 `gtid-W` -5. 使用 `pause-relay` 命令暂停 relay 处理。 -6. 使用 `pause-task` 命令暂停所有运行中的数据迁移任务。 -7. 变更 VIP 以指向新的 MySQL 实例。 -8. 使用 `switch-relay-master` 命令通知 relay 处理单元进行主从切换。 -9. 使用 `resume-relay` 命令恢复 relay 处理，使其从新的 MySQL 实例读取 binlog。 -10. 使用 `resume-task` 命令恢复之前的数据迁移任务。 - -## 变更 DM-worker 连接的上游 MySQL 实例地址 - -若要变更 DM-worker 的配置信息来使 DM-worker 连接到新的上游 MySQL 实例，需要按以下步骤进行操作： - -1. 使用 `query-status` 命令获取当前 relay 处理单元已从原 MySQL 实例获取到的 binlog 对应的 GTID sets (`relayBinlogGtid`)，记为 `gtid-W`。 -2. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_purged;` 获取已经被 purged 的 binlog 对应的 GTID sets，记为 `gtid-P`。 -3. 在将要切换到的 MySQL 实例上使用 `SELECT @@GLOBAL.gtid_executed;` 获取所有已经执行成功的事务对应的 GTID sets，记为 `gtid-E`。 -4. 确保满足以下关系，否则不支持将 DM-worker 连接切换到相应的 MySQL 实例： - - `gtid-W` 包含 `gtid-P`（`gtid-P` 可以为空） - - `gtid-E` 包含 `gtid-W` -5. 使用 `stop-task` 命令停止所有运行中的数据迁移任务。 -6. 更新 `inventory.ini` 中的 DM-worker 配置，并使用 DM-Ansible 对 DM-worker 进行滚动升级操作。 -7. 使用 `start-task` 命令重新启动数据迁移任务。 diff --git a/v3.1/reference/tools/data-migration/usage-scenarios/shard-merge.md b/v3.1/reference/tools/data-migration/usage-scenarios/shard-merge.md deleted file mode 100644 index 98680283f475..000000000000 --- a/v3.1/reference/tools/data-migration/usage-scenarios/shard-merge.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: DM 分库分表合并场景 -category: reference ---- - -# DM 分库分表合并场景 - -本文介绍如何在分库分表合并场景中使用 Data Migration (DM)。使用场景中，三个上游 MySQL 实例的分库和分表数据需要同步至下游 TiDB 集群。 - -## 上游实例 - -假设上游库结构如下： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log_north, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log_east, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log_south, log_bak | - | store_01 | sale_01, sale_02 | - | store_02 | sale_01, sale_02 | - -## 同步需求 - -1. 合并三个实例中的 `user`.`information` 表至下游 TiDB 中的 `user`.`information` 表。 -2. 合并三个实例中的 `user`.`log_{north|south|east}` 表至下游TiDB中的 `user`.`log_{north|south|east}` 表。 -3. 合并三个实例中的 `store_{01|02}`.`sale_{01|02}` 表至下游TiDB中的 `store`.`sale` 表。 -4. 过滤掉三个实例的 `user`.`log_{north|south|east}` 表的所有删除操作。 -5. 过滤掉三个实例的 `user`.`information` 表的所有删除操作。 -6. 过滤掉三个实例的 `store_{01|02}`.`sale_{01|02}` 表的所有删除操作。 -7. 过滤掉三个实例的 `user`.`log_bak` 表。 -8. 因为 `store_{01|02}`.`sale_{01|02}` 表带有 bigint 型的自增主键，将其合并至 TiDB 时会引发冲突。你需要有相应的方案来避免冲突。 - -## 下游实例 - -假设同步后下游库结构如下： - -| Schema | Tables | -|:------|:------| -| user | information, log_north, log_east, log_south| -| store | sale | - -## 同步方案 - -- 要满足同步需求 #1 和 #2，配置 [Table routing 规则](/v3.1/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - {{< copyable "" >}} - - ```yaml - routes: - ... - user-route-rule: - schema-pattern: "user" - target-schema: "user" - ``` - -- 要满足同步需求 #3，配置 [table routing 规则](/v3.1/reference/tools/data-migration/features/overview.md#table-routing) 如下： - - {{< copyable "" >}} - - ```yaml - routes: - ... - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - ``` - -- 要满足同步需求 #4 和 #5，配置 [Binlog event filter 规则](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - {{< copyable "" >}} - - ```yaml - filters: - ... - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - ``` - - > **注意：** - > - > 同步需求 #4、#5 和 #7 的操作意味着过滤掉所有对 `user` 库的删除操作，所以此处配置了库级别的过滤规则。但是 `user` 库以后加入表的删除操作也都会被过滤。 - -- 要满足同步需求 #6，配置 [Binlog event filter 规则](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter) 如下： - - {{< copyable "" >}} - - ```yaml - filters: - ... - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - ``` - -- 要满足同步需求 #7，配置 [Black & white table lists](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists) 如下： - - {{< copyable "" >}} - - ```yaml - black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - ``` - -- 要满足同步需求 #8，首先参考[自增主键冲突处理](/v3.1/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md#自增主键冲突处理)来解决冲突，保证在同步到下游时不会因为分表中有相同的主键值而使同步出现异常；然后需要配置 `ignore-checking-items` 来跳过自增主键冲突的检查： - - {{< copyable "" >}} - - ```yaml - ignore-checking-items: ["auto_increment_ID"] - ``` - -## 同步任务配置 - -同步任务的完整配置如下。详情请参阅 [Data Migration 任务配置文件](/v3.1/reference/tools/data-migration/configure/task-configuration-file.md)。 - -{{< copyable "" >}} - -```yaml -name: "shard_merge" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false -ignore-checking-items: ["auto_increment_ID"] - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - - source-id: "instance-2" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["user-route-rule", "store-route-rule", "sale-route-rule"] - filter-rules: ["user-filter-rule", "store-filter-rule", "sale-filter-rule"] - black-white-list: "log-bak-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例共享的其他通用配置 - -routes: - user-route-rule: - schema-pattern: "user" - target-schema: "user" - store-route-rule: - schema-pattern: "store_*" - target-schema: "store" - sale-route-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - target-schema: "store" - target-table: "sale" - -filters: - user-filter-rule: - schema-pattern: "user" - events: ["truncate table", "drop table", "delete", "drop database"] - action: Ignore - sale-filter-rule: - schema-pattern: "store_*" - table-pattern: "sale_*" - events: ["truncate table", "drop table", "delete"] - action: Ignore - store-filter-rule: - schema-pattern: "store_*" - events: ["drop database"] - action: Ignore - -black-white-list: - log-bak-ignored: - ignore-tables: - - db-name: "user" - tbl-name: "log_bak" - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/v3.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md b/v3.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md deleted file mode 100644 index d74216fc43f8..000000000000 --- a/v3.1/reference/tools/data-migration/usage-scenarios/simple-synchronization.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Data Migration 简单使用场景 -category: reference ---- - -# Data Migration 简单使用场景 - -本文介绍了 DM 工具的一个简单使用场景（非分库分表合并场景）：将三个上游 MySQL 实例的数据同步到一个下游 TiDB 集群中。 - -## 上游实例 - -假设上游结构为： - -- 实例 1 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_bj, store_tj | - | log | messages | - -- 实例 2 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_sh, store_sz | - | log | messages | - -- 实例 3 - - | Schema | Tables | - |:------|:------| - | user | information, log | - | store | store_gz, store_sz | - | log | messages | - -## 同步要求 - -1. 不合并 `user` 库。 - - 1. 将实例 1 中的 `user` 库同步到下游 TiDB 的 `user_north` 库中。 - - 2. 将实例 2 中的 `user` 库同步到下游 TiDB 的 `user_east` 库中。 - - 3. 将实例 3 中的 `user` 库同步到下游 TiDB 的 `user_south` 库中。 - - 4. 任何情况下都不删除 `log` 表的任何数据。 - -2. 将上游 `store` 库同步到下游 `store` 库中，且同步过程中不合并表。 - - 1. 实例 2 和实例 3 中都存在 `store_sz` 表，且这两个 `store_sz` 表分别被同步到下游的 `store_suzhou` 表和 `store_shenzhen` 表中。 - - 2. 任何情况下都不删除 `store` 库的任何数据。 - -3. `log` 库需要被过滤掉。 - -## 下游实例 - -假设下游结构为： - -| Schema | Tables | -|:------|:------| -| user_north | information, log | -| user_east | information, log | -| user_south | information, log | -| store | store_bj, store_tj, store_sh, store_suzhou, store_gz, store_shenzhen | - -## 同步方案 - -- 为了满足[同步要求](#同步要求)中第一点的前三条要求，需要配置以下 [table routing 规则](/v3.1/reference/tools/data-migration/features/overview.md#table-routing)： - - {{< copyable "" >}} - - ```yaml - routes: - ... - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第一条要求，需要配置以下 [table routing 规则](/v3.1/reference/tools/data-migration/features/overview.md#table-routing)： - - {{< copyable "" >}} - - ```yaml - routes: - ... - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - ``` - -- 为了满足[同步要求](#同步要求)中第一点的第四条要求，需要配置以下 [binlog event filter 规则](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - {{< copyable "" >}} - - ```yaml - filters: - ... - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - ``` - -- 为了满足[同步要求](#同步要求)中第二点的第二条要求，需要配置以下 [binlog event filter 规则](/v3.1/reference/tools/data-migration/features/overview.md#binlog-event-filter)： - - {{< copyable "" >}} - - ```yaml - filters: - ... - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - ``` - - > **注意：** - > - > `store-filter-rule` 不同于 `log-filter-rule` 和 `user-filter-rule`。`store-filter-rule` 是针对整个 `store` 库的规则，而 `log-filter-rule` 和 `user-filter-rule` 是针对 `user` 库中 `log` 表的规则。 - -- 为了满足[同步要求](#同步要求)中的第三点要求，需要配置以下 [black & white table lists 规则](/v3.1/reference/tools/data-migration/features/overview.md#black--white-table-lists)： - - {{< copyable "" >}} - - ```yaml - black-white-list: - log-ignored: - ignore-dbs: ["log"] - ``` - -## 同步任务配置 - -以下是完整的同步任务配置，详见[配置介绍](/v3.1/reference/tools/data-migration/configure/task-configuration-file.md)。 - -{{< copyable "" >}} - -```yaml -name: "one-tidb-slave" -task-mode: all -meta-schema: "dm_meta" -remove-meta: false - -target-database: - host: "192.168.0.1" - port: 4000 - user: "root" - password: "" - -mysql-instances: - - - source-id: "instance-1" - route-rules: ["instance-1-user-rule"] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-2" - route-rules: ["instance-2-user-rule", instance-2-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - - - source-id: "instance-3" - route-rules: ["instance-3-user-rule", instance-3-store-rule] - filter-rules: ["log-filter-rule", "user-filter-rule" , "store-filter-rule"] - black-white-list: "log-ignored" - mydumper-config-name: "global" - loader-config-name: "global" - syncer-config-name: "global" - -# 所有实例的共有配置 - -routes: - instance-1-user-rule: - schema-pattern: "user" - target-schema: "user_north" - instance-2-user-rule: - schema-pattern: "user" - target-schema: "user_east" - instance-3-user-rule: - schema-pattern: "user" - target-schema: "user_south" - instance-2-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_suzhou" - instance-3-store-rule: - schema-pattern: "store" - table-pattern: "store_sz" - target-schema: "store" - target-table: "store_shenzhen" - -filters: - log-filter-rule: - schema-pattern: "user" - table-pattern: "log" - events: ["truncate table", "drop table", "delete"] - action: Ignore - user-filter-rule: - schema-pattern: "user" - events: ["drop database"] - action: Ignore - store-filter-rule: - schema-pattern: "store" - events: ["drop database", "truncate table", "drop table", "delete"] - action: Ignore - -black-white-list: - log-ignored: - ignore-dbs: ["log"] - -mydumpers: - global: - threads: 4 - chunk-filesize: 64 - skip-tz-utc: true - -loaders: - global: - pool-size: 16 - dir: "./dumped_data" - -syncers: - global: - worker-count: 16 - batch: 100 - max-retry: 100 -``` diff --git a/v3.1/reference/tools/download.md b/v3.1/reference/tools/download.md deleted file mode 100644 index d7268df92f37..000000000000 --- a/v3.1/reference/tools/download.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: TiDB 工具下载 -category: reference ---- - -# TiDB 工具下载 - -本页面汇总了 TiDB 周边工具官方维护版本的下载链接。 - -## TiDB Binlog - -如需下载最新版本的 [TiDB Binlog](/v3.1/reference/tidb-binlog/overview.md)，直接下载 TiDB 安装包即可，因为 TiDB Binlog 包含在 TiDB 安装包中。 - -以下表格中也提供了 Kafka 版本的 TiDB Binlog 下载链接。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (TiDB Binlog) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | -| `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.tar.gz`（Kafka 版本的 TiDB Binlog）| Linux | amd64 | `https://download.pingcap.org/tidb-binlog-kafka-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB Lightning - -使用下表中的链接下载 [TiDB Lightning](/v3.1/reference/tools/tidb-lightning/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB Lightning 的版本号。例如，`v3.0.5` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.0.5-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 快速备份和恢复（BR） - -使用下表中的链接下载 [快速备份和恢复（BR）](/v3.1/reference/tools/br/br.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 BR 的版本号。例如，`v3.1.0-beta` 版本的下载链接为 `https://download.pingcap.org/tidb-toolkit-v3.1.0-beta-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## TiDB DM (Data Migration) - -使用下表中的链接下载 [DM](/v3.1/reference/tools/data-migration/overview.md)： - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/dm-{version}-linux-amd64.tar.gz` | Linux | amd64 | `https://download.pingcap.org/dm-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 DM 的版本号。例如，`v1.0.1` 版本的下载链接为 `https://download.pingcap.org/dm-v1.0.1-linux-amd64.tar.gz`。可以通过 [DM Release](https://github.com/pingcap/dm/releases) 查看当前已发布版本。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## Syncer，Loader 和 Mydumper - -如需下载最新版本的 [Syncer](/v3.1/reference/tools/syncer.md)，[Loader](/v3.1/reference/tools/loader.md) 或 [Mydumper](/v3.1/reference/tools/mydumper.md)，直接下载 tidb-enterprise-tools 安装包即可，因为这些工具均包含在此安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| [tidb-enterprise-tools-latest-linux-amd64.tar.gz](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.tar.gz) | Linux | amd64 | [tidb-enterprise-tools-latest-linux-amd64.sha256](https://download.pingcap.org/tidb-enterprise-tools-latest-linux-amd64.sha256) | - -tidb-enterprise-tools 安装包包含以下工具： - -- Syncer -- Loader -- Mydumper -- ddl_checker -- [sync-diff-inspector](/v3.1/reference/tools/sync-diff-inspector/overview.md) diff --git a/v3.1/reference/tools/error-case-handling/lightning-misuse-handling.md b/v3.1/reference/tools/error-case-handling/lightning-misuse-handling.md deleted file mode 100644 index 34916ac67d01..000000000000 --- a/v3.1/reference/tools/error-case-handling/lightning-misuse-handling.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: TiDB Lightning 常见的错误用法 -category: reference ---- - -# TiDB Lightning 常见的错误用法 - -本文介绍了 [TiDB Lightning](/v3.1/reference/tools/tidb-lightning/overview.md) 使用过程中常见的出错场景以及相应的处理方式。 - -## 报错：`checksum mismatched remote vs local` - -在数据导入过程中遇到下面的报错 - -```log -Error: checksum mismatched remote vs local => (checksum: 3828723015727756136 vs 7895534721177712659) (total_kvs: 1221416844 vs 1501500000) (total_bytes:237660308510 vs 292158203078) -``` - -### 原因 - -* 先前使用过 TiDB Lightning 进行数据导入，但是对应的 [checkpoint](/v3.1/reference/tools/tidb-lightning/checkpoints.md) 的数据没有被清理，存在残留的数据。可以通过查看 TiDB Lightning 第一次启动 log 来确认： - * `[checkpoint] driver = file`，如果对应 TiDB Lightning 导入时间点的 log 存在 `open checkpoint file failed, going to create a new one`，那么 `checkpoint` 已经被正确清理，否则存在残留数据可能导致导入数据缺失； - * `[checkpoint] driver = mysql`，可以通过使用 TiDB API `curl http://{TiDBIP}:10080/schema/{checkpoint.schema}/{checkpoint.table}` 来查询对应 `checkpoint table` 的创建时间，从而判断是否正确清理了 `checkpoint`。 - -* TiDB Lightning 导入的数据源存在冲突的数据 - * 不同行的数据具有相同的主键或唯一键 - -### 解决方案 - -* 删除出现 `checksum mismatch` 错误的表的数据 - - ``` - tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all - ``` - -* 需要寻找办法检测数据源是否存在冲突数据，TiDB Lightning 一般需要处理大量的数据，所以目前还未提供有效的冲突检测和处理措施。 diff --git a/v3.1/reference/tools/error-case-handling/load-misuse-handling.md b/v3.1/reference/tools/error-case-handling/load-misuse-handling.md deleted file mode 100644 index ad44d830aac5..000000000000 --- a/v3.1/reference/tools/error-case-handling/load-misuse-handling.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: 全量数据导入过程常见报错处理 -category: reference ---- - -# 全量数据导入过程常见报错处理 - -本文介绍了使用 [Loader](/v3.1/reference/tools/loader.md) 或者 [TiDB Data Migration](/v3.1/reference/tools/data-migration/overview.md)（以下简称为 DM）进行全量数据导入过程中常见的因为使用造成的出错场景，以及这些错误发生的原因和处理方式。 - -## 报错：```Try adjusting the `max_allowed_packet` variable``` - -在全量数据导入过程中遇到下面的报错 - -``` -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -### 原因 - -* MySQL client 和 MySQL/TiDB Server 都有 `max_allowed_packet` 配额的限制，如果在使用过程中违反其中任何一个 `max_allowed_packet` 配额，客户端程序就会收到对应的报错。目前最新版本的 Syncer、Loader、DM 和 TiDB Server 的默认 `max_allowed_packet` 配额都为 `64M`。 - * 请使用最新版本，或者最新稳定版本的工具。[下载页面](/v3.1/reference/tools/download.md)。 -* Loader 或 DM 的全量数据导入处理模块不支持对 dump sqls 文件进行切分，原因是 Mydumper 采用了最简单的编码实现，正如 Mydumper 代码注释 `/* Poor man's data dump code */` 所言。如果在 Loader 或 DM 实现文件切分，那么需要在 `TiDB parser` 基础上实现一个完备的解析器才能正确的处理数据切分，但是随之会带来以下的问题： - * 工作量大 - * 复杂度高,不容易保证正确性 - * 性能的极大降低 - -### 解决方案 - -* 依据上面的原因，在代码层面不能简单的解决这个困扰，我们推荐的方式是：利用 Mydumper 提供的控制 `Insert Statement` 大小的功能 `-s, --statement-size`: `Attempted size of INSERT statement in bytes, default 1000000"`。 - - 依据默认的 `--statement-size` 设置，Mydumper 默认生成的 `Insert Statement` 大小会尽量接近在 `1M` 左右，使用默认值就可以确保绝大部分情况不会出现该问题。 - - 有时候在 dump 过程中会出现下面的 `WARN` log，但是这个报错不影响 dump 的过程，只是表达了 dump 的表可能是宽表。 - - ``` - Row bigger than statement_size for xxx - ``` - -* 如果宽表的单行超过了 `64M`，那么需要修改以下两个配置，并且使之生效。 - * 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728` （`134217728 = 128M`） - * 根据实际情况为 Loader 的配置文件或者 `DM task` 配置文件中的 db 配置增加类似 `max-allowed-packet=128M`，然后重启进程或者任务 diff --git a/v3.1/reference/tools/loader.md b/v3.1/reference/tools/loader.md deleted file mode 100644 index da77c13d85de..000000000000 --- a/v3.1/reference/tools/loader.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Loader 使用文档 -category: reference ---- - -# Loader 使用文档 - -## Loader 简介 - -Loader 是由 PingCAP 开发的数据导入工具，用于向 TiDB 中导入数据。 - -Loader 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v3.1/reference/tools/download.md)。 - -## 为什么我们要做这个工具 - -当数据量比较大的时候，如果用 mysqldump 这样的工具迁移数据会比较慢。我们尝试了 [Mydumper/myloader 套件](https://github.com/maxbube/mydumper)，能够多线程导出和导入数据。在使用过程中，Mydumper 问题不大，但是 myloader 由于缺乏出错重试、断点续传这样的功能，使用起来很不方便。所以我们开发了 loader，能够读取 Mydumper 的输出数据文件，通过 MySQL protocol 向 TiDB/MySQL 中导入数据。 - -## Loader 有哪些优点 - -* 多线程导入 -* 支持表级别的并发导入，分散写入热点 -* 支持对单个大表并发导入，分散写入热点 -* 支持 Mydumper 数据格式 -* 出错重试 -* 断点续导 -* 通过 system variable 优化 TiDB 导入数据速度 - -## 使用方法 - -### 注意事项 - -请勿使用 loader 导入 MySQL 实例中 `mysql` 系统数据库到下游 TiDB。 - -如果 Mydumper 使用 -m 参数，会导出不带表结构的数据，这时 loader 无法导入数据。 - -如果使用默认的 `checkpoint-schema` 参数，在导完一个 database 数据库后，请 `drop database tidb_loader` 后再开始导入下一个 database。 - -推荐数据库开始导入的时候，明确指定 `checkpoint-schema = "tidb_loader"` 参数。 - -### 参数说明 - -``` - -L string - log 级别设置，可以设置为 debug, info, warn, error, fatal (默认为 "info") - -P int - TiDB/MySQL 的端口 (默认为 4000) - -V - 打印 loader 版本 - -c string - 指定配置文件启动 loader - -checkpoint-schema string - checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后，会通过这个库获取上次运行的进度 (默认为 "tidb_loader") - -d string - 需要导入的数据存放路径 (default "./") - -h string - TiDB 服务 host IP (default "127.0.0.1") - -p string - TiDB 账户密码 - -status-addr string - Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 - -t int - 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 - -u string - TiDB 的用户名 (默认为 "root") -``` - -### 配置文件 - -除了使用命令行参数外，还可以使用配置文件来配置，配置文件的格式如下： - -```toml -# 日志输出等级；可以设置为 debug, info, warn, error, fatal (默认为 "info") -log-level = "info" - -# 指定 loader 日志目录 -log-file = "loader.log" - -# 需要导入的数据存放路径 (default "./") -dir = "./" - -## Prometheus 可以通过该地址拉取 Loader metrics, 也是 Loader 的 pprof 调试地址 (默认为 ":8272")。 -status-addr = ":8272" - -# checkpoint 数据库名，loader 在运行过程中会不断的更新这个数据库，在中断并恢复后， -# 会通过这个库获取上次运行的进度 (默认为 "tidb_loader") -checkpoint-schema = "tidb_loader" - -# 线程数 (默认为 16). 每个线程同一时刻只能操作一个数据文件。 -pool-size = 16 - -# 目标数据库信息 -[db] -host = "127.0.0.1" -user = "root" -password = "" -port = 4000 - -# 导入数据时数据库连接所使用的 session 级别的 `sql_mode`。如果 `sql-mode` 的值没有提供或者设置为 "@DownstreamDefault"，会使用下游 global 级别的 `sql_mode`。 -# sql-mode = "" -# `max-allowed-packet` 设置数据库连接允许的最大数据包大小，对应于系统参数中的 `max_allowed_packet`。 如果设置为 0，会使用下游数据库 global 级别的 `max_allowed_packet`。 -max-allowed-packet = 67108864 - -# sharding 同步规则，采用 wildcharacter -# 1\. 星号字符 (*) 可以匹配零个或者多个字符, -# 例子, doc* 匹配 doc 和 document, 但是和 dodo 不匹配; -# 星号只能放在 pattern 结尾，并且一个 pattern 中只能有一个 -# 2\. 问号字符 (?) 匹配任一一个字符 - -# [[route-rules]] -# pattern-schema = "shard_db_*" -# pattern-table = "shard_table_*" -# target-schema = "shard_db" -# target-table = "shard_table" -``` - -### 使用示例 - -通过命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -d ./test -h 127.0.0.1 -u root -P 4000 -``` - -或者使用配置文件 "config.toml": - -{{< copyable "shell-regular" >}} - -```bash -./bin/loader -c=config.toml -``` - -## FAQ - -### 合库合表场景案例说明 - -根据配置文件的 route-rules 可以支持将分库分表的数据导入到同一个库同一个表中，但是在开始前需要检查分库分表规则： - -+ 是否可以利用 route-rules 的语义规则表示 -+ 分表中是否包含唯一递增主键，或者合并后是否包含数据上有冲突的唯一索引或者主键 - -Loader 需要配置文件中开启 route-rules 参数以提供合库合表功能 - -+ 如果使用该功能，必须填写 `pattern-schema` 与 `target-schema` -+ 如果 `pattern-table` 与 `target-table` 为空，将不进行表名称合并或转换 - -```toml -[[route-rules]] -pattern-schema = "example_db" -pattern-table = "table_*" -target-schema = "example_db" -target-table = "table" -``` diff --git a/v3.1/reference/tools/mydumper.md b/v3.1/reference/tools/mydumper.md deleted file mode 100644 index 3b5908e0bba4..000000000000 --- a/v3.1/reference/tools/mydumper.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Mydumper 使用文档 -summary: 使用 Mydumper 从 TiDB 导出数据。 -category: reference ---- - -# Mydumper 使用文档 - -## Mydumper 简介 - -[Mydumper](https://github.com/pingcap/mydumper) 是一个 fork 项目，针对 TiDB 的特性进行了优化，推荐使用此工具对 TiDB 进行逻辑备份。 - -Mydumper 包含在 tidb-enterprise-tools 安装包中，可[在此下载](/v3.1/reference/tools/download.md)。 - -### 相比于普通的 Mydumper，此工具有哪些改进之处？ - -+ 对于 TiDB 可以设置 [tidb_snapshot](/v3.1/how-to/get-started/read-historical-data.md#操作流程) 的值指定备份数据的时间点，从而保证备份的一致性，而不是通过 `FLUSH TABLES WITH READ LOCK` 来保证备份一致性。 - -+ 使用 TiDB 的隐藏列 `_tidb_rowid` 优化了单表内数据的并发导出性能。 - -## 基本用法 - -### 新添参数 - -- `-z` 或 `--tidb-snapshot`：设置 `tidb_snapshot` 用于备份。默认值为当前 TSO（`SHOW MASTER STATUS` 输出的 `Position` 字段）。此参数可设为 TSO 或有效的 `datetime` 时间，例如：`-z "2016-10-08 16:45:26"`。 - -### 需要的权限 - -- SELECT -- RELOAD -- LOCK TABLES -- REPLICATION CLIENT - -### 使用举例 - -执行如下命令从 TiDB 备份数据，需要根据实际情况添加命令行参数： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -``` - -## 表内并发 Dump - -### 原理 - -Mydumper 首先计算 `min(_tidb_rowid)` 和 `max(_tidb_rowid)`，然后按照 `-r` 设定的值对表划分 chunks，将 chunks 分配到不同线程并发导出。 - -### 并发 Dump 相关参数 - -- `-t` 或 `--threads`：并发线程数，默认值为 `4`。 -- `-r` 或 `--rows`：每个 chunks 包含的最大行数。设置该值后，Mydumper 将会忽略 `--chunk-filesize` 值。 - -### 示例 - -以下是一条完整的 Mydumper 命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -h 127.0.0.1 -u root -P 4000 -r 10000 -t 4 -``` - -### 支持 `_tidb_rowid` 索引的 TiDB 版本 - -由于表内并发使用 TiDB 的隐藏列 `_tidb_rowid`，数据库需要支持 `_tidb_rowid` 索引才能发挥并发导出的优势。 - -以下 TiDB 版本支持 `_tidb_rowid` 索引： - -- v2.1.3 及以上 -- v3.0 及以上，包括 v3.1 及未来版本 - -### 性能评估 - -在 Dump 操作前需要进行性能评估。由于并发 Scan 操作对 TiDB、TiKV 集群都会产生一定压力，所以需要评估与测试 Dump 操作对数据库集群和业务的影响。 - -## FAQ - -### 如何判断使用的 Mydumper 是否为 PingCAP 优化的版本？ - -执行如下命令： - -{{< copyable "shell-regular" >}} - -```bash -./bin/mydumper -V -``` - -如果输出结果中包含 `githash`（如下列示例输出中的 `d3e6fec8b069daee772d0dbaa47579f67a5947e7`），则使用的 Mydumper 为 PingCAP 优化的版本。 - -``` -mydumper 0.9.5 (d3e6fec8b069daee772d0dbaa47579f67a5947e7), built against MySQL 5.7.24 -``` - -### 使用 Loader 恢复 Mydumper 备份出来的数据时报错 "invalid mydumper files for there are no `-schema-create.sql` files found"，应该如何解决？ - -检查使用 Mydumper 备份数据时是否使用了 `-T` 或者 `--tables-list` 配置，如果使用了这些配置，Mydumper 就不会生成包含建库 SQL 的文件。 - -**解决方法**：在 Mydumper 备份数据目录下创建文件 `{schema-name}-schema-create.sql`，在文件中写入 "CREATE DATABASE `{schema-name}`"，再运行 Loader 即可。 - -### 为什么使用 Mydumper 导出来的 TIMESTAMP 类型的数据和数据库中的数据不一致？ - -检查一下运行 Mydumper 的服务器的时区与数据库的时区是否一致，Mydumper 会根据运行所在服务器的时区对 TIMESTAMP 类型的数据进行转化，可以给 Mydumper 加上 `--skip-tz-utc` 参数禁止这种转化。 - -### 如何配置 Mydumper 的参数 `-F, --chunk-filesize`？ - -Mydumper 在备份时会根据这个参数的值把每个表的数据划分成多个 chunk，每个 chunk 保存到一个文件中，大小约为 `chunk-filesize`。根据这个参数把数据切分到多个文件中，这样就可以利用 Loader/TiDB Lightning 的并行处理逻辑提高导入速度。如果后续使用 Loader 对备份文件进行恢复，建议把该参数的值设置为 `64`（单位 MB）；如果使用 TiDB Lightning 恢复，则建议设置为 `256`（单位 MB）。 - -### 如何配置 Mydumper 的参数 `-s --statement-size`？ - -Mydumper 使用该参数控制 `Insert Statement` 的大小，默认值为 `10000000`（约 1 MB）。使用该参数来尽量避免在恢复数据时报以下错误： - -```log -packet for query is too large. Try adjusting the 'max_allowed_packet' variable -``` - -默认值在绝大部分情况下都可以满足需求，但是**如果表为宽表，单行数据的大小可能超过 statement-size 的限制，Mydumper 会报如下的 Warning**： - -```log -Row bigger than statement_size for xxx -``` - -此时恢复数据时仍然会报 `packet for query is too large` 的错误日志，这个时候需要修改以下两个配置（以设置为 `128M` 为例）： - -* 在 TiDB Server 执行 `set @@global.max_allowed_packet=134217728`（`134217728` = `128M`）。 -* 根据实际情况为 Loader 的配置文件或者 DM task 配置文件中的 db 配置增加类似 `max-allowed-packet=128M` 的语句，然后重启进程或者任务。 - -### 如何设置 Mydumper 的参数 `-l, --long-query-guard`？ - -把该参数设置为预估备份需要消耗的时间，如果 Mydumper 运行时间超过该参数的值，就会报错退出。推荐初次备份设置为 `7200`（单位：秒），之后可根据具体备份时间进行调整。 - -### 如何设置 Mydumper 的参数 `--tidb-force-priority`？ - -仅当备份 TiDB 的数据时才可以设置该参数，值可以为 `LOW_PRIORITY`，`DELAYED` 或者 `HIGH_PRIORITY`。如果不希望数据备份对线上业务造成影响，推荐将该参数设置为 `LOW_PRIORITY`；如果备份的优先级更高，则可以设置为 `HIGH_PRIORITY`。 - -### Mydumper 备份 TiDB 数据报错 "GC life time is shorter than transaction duration" 应该怎么解决？ - -Mydumper 备份 TiDB 数据时为了保证数据的一致性使用了 TiDB 的 snapshot 特性，如果备份过程中 snapshot 对应的历史数据被 TiDB GC 处理了，则会报该错误。解决步骤如下： - -1. 在备份前，使用 MySQL 客户端查询 TiDB 集群的 `tikv_gc_life_time` 的值，并将其调整为一个合适的值： - - {{< copyable "sql" >}} - - ```sql - SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - - ``` - +-----------------------+------------------------------------------------------------------------------------------------+ - | VARIABLE_NAME | VARIABLE_VALUE | - +-----------------------+------------------------------------------------------------------------------------------------+ - | tikv_gc_life_time | 10m0s | - +-----------------------+------------------------------------------------------------------------------------------------+ - 1 rows in set (0.02 sec) - ``` - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -2. 备份完成后，将 `tikv_gc_life_time` 调整为原来的值： - - {{< copyable "sql" >}} - - ```sql - update mysql.tidb set VARIABLE_VALUE = '10m0s' where VARIABLE_NAME = 'tikv_gc_life_time'; - ``` - -### Mydumper 的参数 `--tidb-rowid` 是否需要配置？ - -如果设置该参数为 true，则导出的数据中会包含 TiDB 的隐藏列的数据。将数据恢复到 TiDB 的时候使用隐藏列会有数据不一致的风险，目前不推荐使用该参数。 - -### Mydumper 报错 "Segmentation fault" 怎么解决？ - -该 bug 已修复。如果仍然报错，可尝试升级到最新版本。 - -### Mydumper 报错 "Error dumping table ({schema}.{table}) data: line ...... (total length ...)" 怎么解决？ - -Mydumper 解析 SQL 时报错，可尝试使用最新版本。如果仍然报错，可以提 issue 到 [mydumper/issues](https://github.com/pingcap/mydumper/issues)。 - -### Mydumper 报错 "Failed to set tidb_snapshot: parsing time \"20190901-10:15:00 +0800\" as \"20190901-10:15:00 +0700 MST\": cannot parse \"\" as \"MST\"" 如何解决？ - -检查 TiDB 的版本是否低于 v2.1.11。如果是的话，需要升级 TiDB 到 v2.1.11 或以上版本。 - -### 未来是否计划让 PingCAP 对 Mydumper 的改动合并到上游？ - -是的，PingCAP 团队计划将对 Mydumper 的改动合并到上游。参见 [PR #155](https://github.com/maxbube/mydumper/pull/155)。 diff --git a/v3.1/reference/tools/pd-control.md b/v3.1/reference/tools/pd-control.md deleted file mode 100644 index b4f1604cad37..000000000000 --- a/v3.1/reference/tools/pd-control.md +++ /dev/null @@ -1,1138 +0,0 @@ ---- -title: PD Control 使用说明 -category: reference ---- - -# PD Control 使用说明 - -PD Control 是 PD 的命令行工具，用于获取集群状态信息和调整集群。 - -## 源码编译 - -1. [Go](https://golang.org/) Version 1.9 以上 -2. 在 PD 项目根目录使用 `make` 命令进行编译，生成 bin/pd-ctl - -## 下载安装包 - -如需下载最新版本的 `pd-ctl`，直接下载 TiDB 安装包即可，因为 `pd-ctl` 包含在 TiDB 安装包中。 - -| 安装包 | 操作系统 | 架构 | SHA256 校验和 | -|:---|:---|:---|:---| -| `https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz` (pd-ctl) | Linux | amd64 | `https://download.pingcap.org/tidb-{version}-linux-amd64.sha256` | - -> **注意：** -> -> 下载链接中的 `{version}` 为 TiDB 的版本号。例如 `latest` 版本的下载链接为 `https://download.pingcap.org/tidb-latest-linux-amd64.tar.gz`。也可以使用 `latest` 替代 `{version}` 来下载最新的未发布版本。 - -## 简单例子 - -单命令模式： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl store -u http://127.0.0.1:2379 -``` - -交互模式： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -i -u http://127.0.0.1:2379 -``` - -使用环境变量： - -{{< copyable "shell-regular" >}} - -```bash -export PD_ADDR=http://127.0.0.1:2379 && -./pd-ctl -``` - -使用 TLS 加密： - -{{< copyable "shell-regular" >}} - -```bash -./pd-ctl -u https://127.0.0.1:2379 --cacert="path/to/ca" --cert="path/to/cert" --key="path/to/key" -``` - -## 命令行参数(flags) - -### --cacert - -- 指定 PEM 格式的受信任 CA 的证书文件路径 -- 默认值: "" - -### --cert - -- 指定 PEM 格式的 SSL 证书文件路径 -- 默认值: "" - -### \-\-detach,-d - -+ 使用单命令行模式（不进入 readline） -+ 默认值：true - -### \-\-interact,-i - -+ 使用交互模式（进入 readline） -+ 默认值：false - -### --key - -- 指定 PEM 格式的 SSL 证书密钥文件路径，即 `--cert` 所指定的证书的私钥 -- 默认值: "" - -### \-\-pd,-u - -+ 指定 PD 的地址 -+ 默认地址：`http://127.0.0.1:2379` -+ 环境变量：`PD_ADDR` - -### --version,-V - -- 打印版本信息并退出 -- 默认值: false - -## 命令(command) - -### cluster - -用于显示集群基本信息。 - -示例： - -{{< copyable "" >}} - -```bash ->> cluster -``` - -``` -{ - "id": 6493707687106161130, - "max_peer_count": 3 -} -``` - -### config [show | set \
` 操作 -# 来验证数据的完整性。 -checksum = true -# 如果设置为 true，会在导入每张表后执行一次 level-1 Compact。 -# 默认值为 false。 -level-1-compact = false -# 如果设置为 true，会在导入过程结束时对整个 TiKV 集群执行一次 full Compact。 -# 默认值为 false。 -compact = false -# 如果设置为 true，会对所有表逐个执行 `ANALYZE TABLE
` 操作。 -analyze = true - -# 设置周期性后台操作。 -# 支持的单位：h（时）、m（分）、s（秒）。 -[cron] -# Lightning 自动刷新导入模式状态的持续时间，该值应小于 TiKV 对应的设定值。 -switch-mode = "5m" -# 在日志中打印导入进度的持续时间。 -log-progress = "5m" - -# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 -# [black-white-list] -# ... -``` - -### TiKV Importer 配置参数 - -```toml -# TiKV Importer 配置文件模版 - -# 日志文件 -log-file = "tikv-importer.log" -# 日志等级：trace, debug, info, warn, error 和 off -log-level = "info" - -[server] -# tikv-importer 的监听地址，tidb-lightning 需要连到这个地址进行数据写入。 -addr = "192.168.20.10:8287" -# gRPC 服务器的线程池大小。 -grpc-concurrency = 16 - -[metric] -# 给 Prometheus 客户端推送的 job 名称。 -job = "tikv-importer" -# 给 Prometheus 客户端推送的间隔。 -interval = "15s" -# Prometheus Pushgateway 的地址。 -address = "" - -[rocksdb] -# background job 的最大并发数。 -max-background-jobs = 32 - -[rocksdb.defaultcf] -# 数据在刷新到硬盘前能存于内存的容量上限。 -write-buffer-size = "1GB" -# 内存中写缓冲器的最大数量。 -max-write-buffer-number = 8 - -# 各个压缩层级使用的算法。 -# 第 0 层的算法用于压缩 KV 数据。 -# 第 6 层的算法用于压缩 SST 文件。 -# 第 1 至 5 层的算法目前尚未使用。 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[rocksdb.writecf] -# 同上 -compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"] - -[import] -# 存储引擎文件的文件夹路径 -import-dir = "/mnt/ssd/data.import/" -# 处理 RPC 请求的线程数 -num-threads = 16 -# 导入 job 的并发数。 -num-import-jobs = 24 -# 预处理 Region 最长时间。 -# max-prepare-duration = "5m" -# 把要导入的数据切分为这个大小的 Region。 -#region-split-size = "512MB" -# 设置 stream-channel-window 的大小。 -# channel 满了之后 stream 会处于阻塞状态。 -# stream-channel-window = 128 -# 同时打开引擎文档的最大数量。 -max-open-engines = 8 -# Importer 上传至 TiKV 的最大速度（字节/秒）。 -# upload-speed-limit = "512MB" -# 目标存储可用空间比率（store_available_space/store_capacity）的最小值。 -# 如果目标存储空间的可用比率低于该值，Importer 将会暂停上传 SST -# 来为 PD 提供足够时间进行 Regions 负载均衡。 -min-available-ratio = 0.05 -``` - -## 命令行参数 - -### `tidb-lightning` - -使用 `tidb-lightning` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:----| -| --config *file* | 从 *file* 读取全局设置。如果没有指定则使用默认设置。 | | -| -V | 输出程序的版本 | | -| -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | -| -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | -| --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | -| --log-file *file* | 日志文件路径 | `lightning.log-file` | -| --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | -| --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | -| --pd-urls *host:port* | PD endpoint 的地址 | `tidb.pd-addr` | -| --tidb-host *host* | TiDB Server 的 host | `tidb.host` | -| --tidb-port *port* | TiDB Server 的端口（默认为 4000） | `tidb.port` | -| --tidb-status *port* | TiDB Server 的状态端口的（默认为 10080） | `tidb.status-port` | -| --tidb-user *user* | 连接到 TiDB 的用户名 | `tidb.user` | -| --tidb-password *password* | 连接到 TiDB 的密码 | `tidb.password` | - -如果同时对命令行参数和配置文件中的对应参数进行更改，命令行参数将优先生效。例如，在 `cfg.toml` 文件中，不管对日志等级做出什么修改，运行 `./tidb-lightning -L debug --config cfg.toml` 命令总是将日志级别设置为 “debug”。 - -### `tidb-lightning-ctl` - -使用 `tidb-lightning-ctl` 可以对下列参数进行配置： - -| 参数 | 描述 | -|:----|:----------| -| --compact | 执行 full compact | -| --switch-mode *mode* | 将每个 TiKV Store 切换到指定模式（normal 或 import） | -| --import-engine *uuid* | 将 TiKV Importer 上关闭的引擎文件导入到 TiKV 集群 | -| --cleanup-engine *uuid* | 删除 TiKV Importer 上的引擎文件 | -| --checkpoint-dump *folder* | 将当前的断点以 CSV 格式存储到文件夹中 | -| --checkpoint-error-destroy *tablename* | 删除断点，如果报错则删除该表 | -| --checkpoint-error-ignore *tablename* | 忽略指定表中断点的报错 | -| --checkpoint-remove *tablename* | 无条件删除表的断点 | - -*tablename* 必须是`` `db`.`tbl` `` 中的限定表名（包括反引号），或关键词 `all`。 - -此外，上表中所有 `tidb-lightning` 的参数也适用于 `tidb-lightning-ctl`。 - -### `tikv-importer` - -使用 `tikv-importer` 可以对下列参数进行配置： - -| 参数 | 描述 | 对应配置项 | -|:----|:----|:-------| -| -C, --config *file* | 从 *file* 读取配置。如果没有指定，则使用默认设置| | -| -V, --version | 输出程序的版本 | | -| -A, --addr *ip:port* | TiKV Importer 服务器的监听地址 | `server.addr` | -| --import-dir *dir* | 引擎文件的存储目录 | `import.import-dir` | -| --log-level *level* | 日志的等级： trace、debug、info、warn、error 或 off | `log-level` | -| --log-file *file* | 日志文件路径 | `log-file` | diff --git a/v3.1/reference/tools/tidb-lightning/csv.md b/v3.1/reference/tools/tidb-lightning/csv.md deleted file mode 100644 index b0a593fee745..000000000000 --- a/v3.1/reference/tools/tidb-lightning/csv.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: CSV 支持 -category: reference ---- - -# CSV 支持 - -TiDB Lightning 支持读取 CSV（逗号分隔值）的数据源，以及其他定界符格式如 TSV（制表符分隔值）。 - -## 文件名 - -包含整张表的 CSV 文件需命名为 `db_name.table_name.csv`，该文件会被解析为数据库 `db_name` 里名为 `table_name` 的表。 - -如果一个表分布于多个 CSV 文件，这些 CSV 文件命名需加上文件编号的后缀，如 `db_name.table_name.003.csv`。 - -文件扩展名必须为 `*.csv`，即使文件的内容并非逗号分隔。 - -## 表结构 - -CSV 文件是没有表结构的。要导入 TiDB，就必须为其提供表结构。可以通过以下任一方法实现： - -* 创建包含 DDL 语句 `CREATE TABLE` 的文件 `db_name.table_name-schema.sql`。 -* 首先在 TiDB 中直接创建空表，然后在 `tidb-lightning.toml` 中设置 `[mydumper] no-schema = true`。 - -## 配置 - -CSV 格式可在 `tidb-lightning.toml` 文件中 `[mydumper.csv]` 下配置。 -大部分设置项在 MySQL [`LOAD DATA`] 语句中都有对应的项目。 - -```toml -[mydumper.csv] -# 字段分隔符，必须为 ASCII 字符。 -separator = ',' -# 引用定界符，可以为 ASCII 字符或空字符。 -delimiter = '"' -# CSV 文件是否包含表头。 -# 如果为 true，首行将会被跳过。 -header = true -# CSV 是否包含 NULL。 -# 如果为 true，CSV 文件的任何列都不能解析为 NULL。 -not-null = false -# 如果 `not-null` 为 false（即 CSV 可以包含 NULL）， -# 为以下值的字段将会被解析为 NULL。 -null = '\N' -# 是否解析字段内的反斜线转义符。 -backslash-escape = true -# 是否移除以分隔符结束的行。 -trim-last-separator = false -``` - -[`LOAD DATA`]: https://dev.mysql.com/doc/refman/8.0/en/load-data.html - -### `separator` - -- 指定字段分隔符。 -- 必须为单个 ASCII 字符。 -- 常用值： - - * CSV 用 `','` - * TSV 用 `"\t"` - -- 对应 LOAD DATA 语句中的 `FIELDS TERMINATED BY` 项。 - -### `delimiter` - -- 指定引用定界符。 -- 如果 `delimiter` 为空，所有字段都会被取消引用。 -- 常用值： - - * `'"'` 使用双引号引用字段，和 [RFC 4180] 一致。 - * `''` 不引用 - -- 对应 LOAD DATA 语句中的 `FIELDS ENCLOSED BY` 项。 - -[RFC 4180]: https://tools.ietf.org/html/rfc4180 - -### `header` - -- 是否*所有* CSV 文件都包含表头行。 -- 如为 true，第一行会被用作*列名*。如为 false，第一行并无特殊性，按普通的数据行处理。 - -### `not-null` 和 `null` - -- `not-null` 决定是否所有字段不能为空。 -- 如果 `not-null` 为 false，设定了 `null` 的字符串会被转换为 SQL NULL 而非具体数值。 -- 引用不影响字段是否为空。 - - 例如有如下 CSV 文件： - - ```csv - A,B,C - \N,"\N", - ``` - - 在默认设置（`not-null = false; null = '\N'`）下，列 `A` and `B` 导入 TiDB 后都将会转换为 NULL。列 `C` 是空字符串 `''`，但并不会解析为 NULL。 - -### `backslash-escape` - -- 是否解析字段内的反斜线转义符。 -- 如果 `backslash-escape` 为 true，下列转义符会被识别并转换。 - - | 转义符 | 转换为 | - |----------|--------------------------| - | `\0` | 空字符 (U+0000) | - | `\b` | 退格 (U+0008) | - | `\n` | 换行 (U+000A) | - | `\r` | 回车 (U+000D) | - | `\t` | 制表符 (U+0009) | - | `\Z` | Windows EOF (U+001A) | - - 其他情况下（如 `\"`）反斜线会被移除，仅在字段中保留其后面的字符（`"`）。 - -- 引用不会影响反斜线转义符的解析与否。 - -- 对应 LOAD DATA 语句中的 `FIELDS ESCAPED BY '\'` 项。 - -### `trim-last-separator` - -- 将 `separator` 字段当作终止符，并移除尾部所有分隔符。 - - 例如有如下 CSV 文件： - - ```csv - A,,B,, - ``` - -- 当 `trim-last-separator = false`，该文件会被解析为包含 5 个字段的行 `('A', '', 'B', '', '')`。 -- 当 `trim-last-separator = true`，该文件会被解析为包含 3 个字段的行 `('A', '', 'B')`。 - -### 不可配置项 - -TiDB Lightning 并不完全支持 `LOAD DATA` 语句中的所有配置项。例如： - -* 行终止符只能是 CR（`\r`），LF（`\n`）或 CRLF（`\r\n`），也就是说，无法自定义 `LINES TERMINATED BY`。 -* 不可使用行前缀 （`LINES STARTING BY`）。 -* 不可跳过表头（`IGNORE n LINES`）。如有表头，必须是有效的列名。 -* 定界符和分隔符只能为单个 ASCII 字符。 - -## 通用配置 - -### CSV - -默认设置已按照 RFC 4180 调整。 - -```toml -[mydumper.csv] -separator = ',' -delimiter = '"' -header = true -not-null = false -null = '\N' -backslash-escape = true -trim-last-separator = false -``` - -示例内容： - -``` -ID,Region,Count -1,"East",32 -2,"South",\N -3,"West",10 -4,"North",39 -``` - -### TSV - -```toml -[mydumper.csv] -separator = "\t" -delimiter = '' -header = true -not-null = false -null = 'NULL' -backslash-escape = false -trim-last-separator = false -``` - -示例内容： - -``` -ID Region Count -1 East 32 -2 South NULL -3 West 10 -4 North 39 -``` - -### TPC-H DBGEN - -```toml -[mydumper.csv] -separator = '|' -delimiter = '' -header = false -not-null = true -backslash-escape = false -trim-last-separator = true -``` - -示例内容： - -``` -1|East|32| -2|South|0| -3|West|10| -4|North|39| -``` diff --git a/v3.1/reference/tools/tidb-lightning/deployment.md b/v3.1/reference/tools/tidb-lightning/deployment.md deleted file mode 100644 index d7e38a1de131..000000000000 --- a/v3.1/reference/tools/tidb-lightning/deployment.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: TiDB Lightning 部署与执行 -category: reference -aliases: ['/docs-cn/tools/lightning/deployment/'] ---- - -# TiDB Lightning 部署与执行 - -本文主要介绍 TiDB Lightning 使用 Importer-backend（默认）进行数据导入的硬件需求，以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 - -如果你想改用 TiDB-backend 进行数据导入，参考 [TiDB Lightning TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 - -## 注意事项 - -在使用 TiDB Lightning 前，需注意以下事项： - -- TiDB Lightning 运行后，TiDB 集群将无法正常对外提供服务。 -- 若 `tidb-lightning` 崩溃，集群会留在“导入模式”。若忘记转回“普通模式”，集群会产生大量未压缩的文件，继而消耗 CPU 并导致延迟。此时，需要使用 `tidb-lightning-ctl` 手动将集群转回“普通模式”： - - {{< copyable "shell-regular" >}} - - ```sh - bin/tidb-lightning-ctl -switch-mode=normal - ``` - -- TiDB Lightning 需要下游 TiDB 有如下权限： - - | 权限 | 作用域 | - |:----|:------| - | SELECT | Tables | - | INSERT | Tables | - | UPDATE | Tables | - | DELETE | Tables | - | CREATE | Databases, tables | - | DROP | Databases, tables | - | ALTER | Tables | - - 如果配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 - -## 硬件需求 - -`tidb-lightning` 和 `tikv-importer` 这两个组件皆为资源密集程序，建议各自单独部署。 - -为了优化效能，建议硬件配置如下： - -- `tidb-lightning` - - - 32+ 逻辑核 CPU - - 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程默认会占满 CPU，建议单独部署。条件不允许的情况下可以和其他组件（比如 `tidb-server`）部署在同一台机器上，然后通过配置 `region-concurrency` 限制 `tidb-lightning` 使用 CPU 资源。 - -- `tikv-importer` - - - 32+ 逻辑核 CPU - - 40 GB+ 内存 - - 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000） - * 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。 - - 使用万兆网卡，带宽需 300 MB/s 以上 - - 运行过程中 CPU、I/O 和网络带宽都可能占满，建议单独部署。 - -如果机器充裕的话，可以部署多套 `tidb-lightning` + `tikv-importer`，然后将源数据以表为粒度进行切分，并发导入。 - -> **注意：** -> -> - `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 资源分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 “24”。 -> -> - `tikv-importer` 将中间数据存储缓存到内存上以加速导入过程。占用内存大小可以通过 **(`max-open-engines` × `write-buffer-size` × 2) + (`num-import-jobs` × `region-split-size` × 2)** 计算得来。如果磁盘写入速度慢，缓存可能会带来更大的内存占用。 - -此外，目标 TiKV 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](/v3.1/how-to/deploy/hardware-recommendations.md)以外，目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](/v3.1/faq/tidb.md#326-每个-region-的-replica-数量可配置吗调整的方法是) × 2**。例如集群默认使用 3 副本，那么总存储空间需为数据源大小的 6 倍以上。 - -## 导出数据 - -使用 [`mydumper`](/v3.1/reference/tools/mydumper.md) 从 MySQL 导出数据，如下： - -{{< copyable "shell-regular" >}} - -```sh -./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/ -``` - -其中： - -- `-B test`：从 `test` 数据库导出。 -- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。 -- `-t 16`：使用 16 个线程导出数据。 -- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。 -- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。 - -如果数据源是 CSV 文件，请参考 [CSV 支持](/v3.1/reference/tools/tidb-lightning/csv.md)获取配置信息。 - -## 部署 TiDB Lightning - -本节介绍 TiDB Lightning 的两种部署方式：[使用 Ansible 部署](#使用-ansible-部署-tidb-lightning)和[手动部署](#手动部署-tidb-lightning)。 - -### 使用 Ansible 部署 TiDB Lightning - -TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/v3.1/how-to/deploy/orchestrated/ansible.md)。 - -1. 编辑 `inventory.ini`，分别配置一个 IP 来部署 `tidb-lightning` 和 `tikv-importer`。 - - ```ini - ... - - [importer_server] - 192.168.20.9 - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 修改 `group_vars/*.yml` 的变量配置这两个工具。 - - - `group_vars/all.yml` - - ```yaml - ... - # tikv-importer 的监听端口。需对 tidb-lightning 服务器开放。 - tikv_importer_port: 8287 - ... - ``` - - - `group_vars/lightning_server.yml` - - ```yaml - --- - dummy: - - # 提供监控告警的端口。需对监控服务器 (monitoring_server) 开放。 - tidb_lightning_pprof_port: 8289 - - # 获取数据源（Mydumper SQL dump 或 CSV）的路径。 - data_source_dir: "{{ deploy_dir }}/mydumper" - ``` - - - `group_vars/importer_server.yml` - - ```yaml - --- - dummy: - - # 储存引擎文件的路径。需存放在空间足够大的分区。 - import_dir: "{{ deploy_dir }}/data.import" - ``` - -3. 开始部署。 - - {{< copyable "shell-regular" >}} - - ```sh - ansible-playbook bootstrap.yml && - ansible-playbook deploy.yml - ``` - -4. 将数据源写入 `data_source_dir` 指定的路径。 - -5. 登录 `tikv-importer` 的服务器，并执行以下命令来启动 Importer。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_importer.sh - ``` - -6. 登录 `tidb-lightning` 的服务器，并执行以下命令来启动 Lightning，开始导入过程。 - - {{< copyable "shell-regular" >}} - - ```sh - scripts/start_lightning.sh - ``` - -7. 完成后，在 `tikv-importer` 的服务器执行 `scripts/stop_importer.sh` 来关闭 Importer。 - -### 手动部署 TiDB Lightning - -#### 第 1 步：部署 TiDB 集群 - -在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群 (版本要求 2.0.9 以上)，建议使用最新版。部署方法可参考 [TiDB 快速入门指南](/v3.1/overview.md#部署方式)。 - -#### 第 2 步：下载 TiDB Lightning 安装包 - -在[工具下载](/v3.1/reference/tools/download.md#tidb-lightning)页面下载 TiDB Lightning 安装包（需选择与 TiDB 集群相同的版本）。 - -#### 第 3 步：启动 `tikv-importer` - -1. 从安装包上传 `bin/tikv-importer`。 - -2. 配置 `tikv-importer.toml`。 - - ```toml - # TiKV Importer 配置文件模版 - - # 日志文件。 - log-file = "tikv-importer.log" - # 日志等级：trace、debug、info、warn、error、off。 - log-level = "info" - - [server] - # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。 - addr = "192.168.20.10:8287" - - [metric] - # 给 Prometheus 客户端的推送任务名称。 - job = "tikv-importer" - # 给 Prometheus 客户端的推送间隔。 - interval = "15s" - # Prometheus Pushgateway 地址。 - address = "" - - [import] - # 存储引擎文档 (engine file) 的文件夹路径。 - import-dir = "/mnt/ssd/data.import/" - ``` - - 上面仅列出了 `tikv-importer` 的基本配置。完整配置请参考[`tikv-importer` 配置说明](/v3.1/reference/tools/tidb-lightning/config.md#tikv-importer)。 - -3. 运行 `tikv-importer`。 - - {{< copyable "shell-regular" >}} - - ```sh - nohup ./tikv-importer -C tikv-importer.toml > nohup.out & - ``` - -#### 第 4 步：启动 `tidb-lightning` - -1. 从安装包上传 `bin/tidb-lightning` 及 `bin/tidb-lightning-ctl`。 - -2. 将数据源写入到同样的机器。 - -3. 配置 `tidb-lightning.toml`。对于没有出现在下述模版中的配置，TiDB Lightning 给出配置错误的提醒并退出。 - - ```toml - [lightning] - - # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。 - # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。 - # region-concurrency = - - # 日志 - level = "info" - file = "tidb-lightning.log" - - [tikv-importer] - # tikv-importer 的监听地址，需改成 tikv-importer 服务器的实际地址。 - addr = "172.16.31.10:8287" - - [mydumper] - # Mydumper 源数据目录。 - data-source-dir = "/data/my_database" - - [tidb] - # 目标集群的信息。tidb-server 的监听地址，填一个即可。 - host = "172.16.31.1" - port = 4000 - user = "root" - password = "" - # 表架构信息在从 TiDB 的“状态端口”获取。 - status-port = 10080 - ``` - - 上面仅列出了 `tidb-lightning` 的基本配置。完整配置请参考[`tidb-lightning` 配置说明](/v3.1/reference/tools/tidb-lightning/config.md#tidb-lightning-全局配置)。 - -4. 运行 `tidb-lightning`。如果直接在命令行中用 `nohup` 启动程序，可能会因为 SIGHUP 信号而退出，建议把 `nohup` 放到脚本里面，如： - - {{< copyable "shell-regular" >}} - - ```sh - #!/bin/bash - nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & - ``` - -## 升级 TiDB Lightning - -你可以通过替换二进制文件升级 TiDB Lightning，无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/v3.1/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 - -如果当前有运行的导入任务，推荐任务完成后再升级 TiDB Lightning。否则，你可能需要从头重新导入，因为无法保证断点可以跨版本工作。 \ No newline at end of file diff --git a/v3.1/reference/tools/tidb-lightning/glossary.md b/v3.1/reference/tools/tidb-lightning/glossary.md deleted file mode 100644 index 43b4775bb859..000000000000 --- a/v3.1/reference/tools/tidb-lightning/glossary.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: TiDB Lightning 术语表 -summary: 了解 TiDB Lightning 相关的术语及定义。 -category: glossary ---- - -# TiDB Lightning 术语表 - -本术语表提供了 TiDB Lightning 相关的术语和定义，这些术语会出现在 TiDB Lightning 的日志、监控指标、配置和文档中。 - - - -## A - -### Analyze - -统计信息分析。指重建 TiDB 表中的统计信息，即运行 [`ANALYZE TABLE`](/v3.1/reference/sql/statements/analyze-table.md) 语句。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，统计信息不会自动更新，所以 TiDB Lightning 在导入后显式地分析每个表。如果不需要该操作，可以将 `post-restore.analyze` 设置为 `false`。 - -### `AUTO_INCREMENT_ID` - -用于为自增列分配默认值的自增 ID 计数器。每张表都有一个相关联的 `AUTO_INCREMENT_ID` 计数器。在 TiDB 中，该计数器还用于分配行 ID。 - -因为 TiDB Lightning 不通过 TiDB 导入数据，`AUTO_INCREMENT_ID` 计数器不会自动更新，所以 TiDB Lightning 显式地将 `AUTO_INCREMENT_ID` 改为一个有效值。即使表中没有自增列，这步仍是会执行。 - - - -## B - -### Backend - -也称作 Back end（后端），用于接受 TiDB Lightning 解析结果。 - -详情参阅 [TiDB Lightning TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md)。 - -### Black-white list - -黑白名单配置列表。用于指定要导入、忽略哪些表和库。 - -详情参阅 [TiDB Lightning 表库过滤](/v3.1/reference/tools/tidb-lightning/table-filter.md)。 - - - -## C - -### Checkpoint - -断点。用于保证 TiDB Lightning 在导入数据时不断地将进度保存到本地文件或远程数据库中。这样即使进程崩溃，TiDB Lightning 也能从中间状态恢复。 - -详情参见 [TiDB Lightning 断点续传](/v3.1/reference/tools/tidb-lightning/checkpoints.md)。 - -### Checksum - -校验和。一种用于[验证导入数据正确性](/v3.1/faq/tidb-lightning.md#如何校验导入的数据的正确性)的方法。 - -在 TiDB Lightning 中，表的校验和是由 3 个数字组成的集合，由该表中每个键值对的内容计算得出。这些数字分别是： - -* 键值对的数量 -* 所有键值对的总长度 -* 每个键值对 [CRC-64-ECMA](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) 按位异或的结果 - -TiDB Lightning 通过比较每个表的[本地校验和](#local-checksum)和[远程校验和](#remote-checksum)来验证导入数据的正确性。如果有任一对校验和不匹配，导入进程就会停止。如果你需要跳过校验和检查，可以将 `post-restore.checksum` 设置为 `false` 。 - -遇到校验和不匹配的问题时，参考[故障排查](/v3.1/how-to/troubleshoot/tidb-lightning.md#checksum-failed-checksum-mismatched-remote-vs-local)进行处理。 - -### Chunk - -指数据源中的单个文件。 - -### Compaction - -压缩。指将多个小 SST 文件合并为一个大 SST 文件并清理已删除的条目。TiDB Lightning 导入数据时，TiKV 在后台会自动压缩数据。 - -> **注意：** -> -> 出于遗留原因，你仍然可以将 TiDB Lightning 配置为在每次导入表时进行显式压缩，但是官方不推荐采用该操作，且该操作的相关设置默认是禁用的。 -> -> 技术细节参阅 [RocksDB 关于压缩的说明](https://github.com/facebook/rocksdb/wiki/Compaction)。 - - - -## D - -### Data engine - -数据引擎。用于对实际的行数据进行排序的[引擎](#engine)。 - -当一个表数据很多的时候，表的数据会被放置在多个数据引擎中以改善任务流水线并节省 TiKV Importer 的空间。默认条件下，每 100 GB 的 SQL 数据会打开一个新的数据引擎（可通过 `mydumper.batch-size` 配置项进行更改）。 - -TiDB Lightning 同时处理多个数据引擎（可通过 `lightning.table-concurrency` 配置项进行更改）。 - - - -## E - -### Engine - -引擎。在 TiKV Importer 中，一个引擎就是一个用于排序键值对的 RocksDB 实例。 - -TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先打开一个引擎，向其发送未排序的键值对，然后关闭引擎。随后，引擎会对收到的键值对进行排序操作。这些关闭的引擎可以进一步上传至 TiKV store 中为 [Ingest](#ingest) 做准备。 - -引擎使用 TiKV Importer 的 `import-dir` 作为临时存储，有时也会被称为引擎文件 (engine files)。 - -另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 - - - -## I - -### Import mode - -导入模式。指通过降低读取速度和减少空间使用，来优化 TiKV 写入的配置模式。 - -导入过程中，TiDB Lightning 自动在导入模式和[普通模式](#normal-mode)中来回切换。如果 TiKV 卡在导入模式，你可以使用 `tidb-lightning-ctl` [强制切换回普通模式](/v3.1/faq/tidb-lightning.md#为什么用过-tidb-lightning-之后tidb-集群变得又慢又耗-cpu)。 - -### Index engine - -索引引擎。用于对索引进行排序的[引擎](#engine)。 - -不管表中有多少索引，每张表都只对应**一个**索引引擎。 - -TiDB Lightning 可同时处理多个索引引擎（可通过 `lightning.index-concurrency` 配置项进行更改）。由于每张表正好对应一个索引引擎，`lightning.index-concurrency` 配置项也限定了可同时处理的表的最大数量。 - -### Ingest - -指将 [SST 文件](#sst-file)的全部内容插入到 RocksDB（TiKV）store 中的操作。 - -与逐个插入键值对相比，Ingest 的效率非常高。因此，该操作直接决定了 TiDB Lightning 的性能。 - -技术细节参阅 [RocksDB 关于创建、Ingest SST 文件的 wiki 页面](https://github.com/facebook/rocksdb/wiki/Creating-and-Ingesting-SST-files)。 - - - -## K - -### KV pair - -即 key-value pair（键值对）。 - -### KV encoder - -用于将 SQL 或 CSV 行解析为键值对的例程。多个 KV encoder 会并行运行以加快处理速度。 - - - -## L - -### Local checksum - -本地校验和。在将键值对发送到 TiKV Importer 前，由 TiDB Lightning 计算的表的校验和。 - - - -## N - -### Normal mode - -普通模式。未启用[导入模式](#import-mode)时的模式。 - - - -## P - -### Post-processing - -指整个数据源被解析发送到 TiKV Importer 之后的一段时间。此时 TiDB Lightning 正在等待 TiKV Importer 上传、[Ingest](#ingest) [SST 文件](#sst-file)。 - - - -## R - -### Remote checksum - -远程校验和。指导入 TiDB 后所计算的表的[校验和](#checksum)。 - - - -## S - -### Scattering - -指随机再分配 [Region](/v3.1/glossary.md#regionpeerraft-group) 中 leader 和 peer 的操作。Scattering 确保导入的数据在 TiKV store 中均匀分布，这样可以降低 PD 调度的压力。 - -### Splitting - -指 TiKV Importer 在上传之前会将单个引擎文件拆分为若干小 [SST 文件](#sst-file)的操作。这是因为引擎文件通常很大（约为 100 GB），在 TiKV 中不适合视为单一的 [Region](/v3.1/glossary.md#regionpeerraft-group)。拆分的文件大小可通过 `import.region-split-size` 配置项更改。 - -### SST file - -Sorted string table file（排序字符串表文件）。SST 文件是一种在 RocksDB 中（因而也是 TiKV 中）键值对集合在本地的存储形式。 - -TiKV Importer 从关闭的[引擎](#engine)中生成 SST 文件。这些 SST 文件接着被上传、[ingest](#ingest) 到 TiKV store 中。 diff --git a/v3.1/reference/tools/tidb-lightning/monitor.md b/v3.1/reference/tools/tidb-lightning/monitor.md deleted file mode 100644 index 1378cba5d0c8..000000000000 --- a/v3.1/reference/tools/tidb-lightning/monitor.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: TiDB Lightning 监控告警 -category: reference ---- - -# TiDB Lightning 监控告警 - -`tidb-lightning` 和 `tikv-importer` 都支持使用 [Prometheus](https://prometheus.io/) 采集监控指标 (metrics)。本文主要介绍 TiDB Lightning 的监控配置与监控指标。 - -## 监控配置 - -- 如果是使用 TiDB Ansible 部署 Lightning，只要将服务器地址加到 `inventory.ini` 文件里的 `[monitored_servers]` 部分即可。 -- 如果是手动部署 Lightning，则参照以下步骤进行配置。 - -### `tikv-importer` - -`tikv-importer` v2.1 使用 [Pushgateway](https://github.com/prometheus/pushgateway) 来推送监控指标。需要配置 `tikv-importer.toml` 来连接 Pushgateway： - -```toml -[metric] - -# 给 Prometheus 客户端的推送任务名称。 -job = "tikv-importer" - -# 给 Prometheus 客户端的推送间隔。 -interval = "15s" - -# Prometheus Pushgateway 地址。 -address = "" -``` - -### `tidb-lightning` - -只要 Prometheus 能发现 `tidb-lightning` 的监控地址，就能收集监控指标。 - -监控的端口可在 `tidb-lightning.toml` 中配置： - -```toml -[lightning] -# 用于调试和 Prometheus 监控的 HTTP 端口。输入 0 关闭。 -pprof-port = 8289 - -... -``` - -要让 Prometheus 发现 Lightning，可以将地址直接写入其配置文件，例如： - -{{< copyable "" >}} - -```yaml -... -scrape_configs: - - job_name: 'tidb-lightning' - static_configs: - - targets: ['192.168.20.10:8289'] -``` - -## Grafana 面板 - -[Grafana](https://grafana.com/) 的可视化面板可以让你在网页上监控 Prometheus 指标。 - -使用 TiDB Ansible 部署 TiDB 集群时，会同时部署一套 Grafana + Prometheus 的监控系统。 - -如果使用其他方式部署 TiDB Lightning，需先导入[面板的 JSON 文件](https://raw.githubusercontent.com/pingcap/tidb-ansible/master/scripts/lightning.json)。 - -### 第一行：速度面板 - -![第一行速度面板](/media/lightning-grafana-row-1.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Import speed | write from lightning | 从 TiDB Lightning 向 TiKV Importer 发送键值对的速度，取决于每个表的复杂性 | -| Import speed | upload to tikv | 从 TiKV Importer 上传 SST 文件到所有 TiKV 副本的总体速度 | -| Chunk process duration | | 完全编码单个数据文件所需的平均时间 | - -有时导入速度会降到 0，这是为了平衡其他部分的速度，属于正常现象。 - -### 第二行：进度面板 - -![第二行进度面板](/media/lightning-grafana-row-2.png) - -| 面板名称 | 描述 | -|:-----|:-----| -| Import progress | 已编码的文件所占百分比 | -| Checksum progress | 已导入的表所占百分比 | -| Failures | 导入失败的表的数量以及故障点，通常为空 | - -### 第三行：资源使用面板 - -![第三行资源使用面板](/media/lightning-grafana-row-3.png) - -| 面板名称 | 描述 | -|:-----|:-----| -| Memory usage | 每个服务占用的内存 | -| Number of Lightning Goroutines | TiDB Lightning 使用的运行中的 goroutines 数量 | -| CPU% | 每个服务使用的逻辑 CPU 数量 | - -### 第四行：配额使用面板 - -![第四行配额使用面板](/media/lightning-grafana-row-4.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Idle workers | io | 未使用的 `io-concurrency` 的数量，通常接近配置值（默认为 5），接近 0 时表示磁盘运行太慢 | -| Idle workers | closed-engine | 已关闭但未清理的引擎数量，通常接近 `index-concurrency` 与 `table-concurrency` 的和（默认为 8），接近 0 时表示 TiDB Lightning 比 TiKV Importer 快，导致 TiDB Lightning 延迟 | -| Idle workers | table | 未使用的 `table-concurrency` 的数量，通常为 0，直到进程结束 | -| Idle workers | index | 未使用的 `index-concurrency` 的数量，通常为 0，直到进程结束 | -| Idle workers | region | 未使用的 `region-concurrency` 的数量，通常为 0，直到进程结束 | -| External resources | KV Encoder | 已激活的 KV encoder 的数量，通常与 `region-concurrency` 的数量相同，直到进程结束 | -| External resources | Importer Engines | 打开的引擎文件数量，不应超过 `max-open-engines` 的设置 | - -### 第五行：读取速度面板 - -![第五行读取速度面板](/media/lightning-grafana-row-5.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Chunk parser read block duration | read block | 读取一个字节块来准备解析时所消耗的时间 | -| Chunk parser read block duration | apply worker | 等待 `io-concurrency` 空闲所消耗的时间 | -| SQL process duration | row encode | 解析和编码单行所消耗的时间 | -| SQL process duration | block deliver | 将一组键值对发送到 TiKV Importer 所消耗的时间 | - -如果上述项的持续时间过长，则表示 TiDB Lightning 使用的磁盘运行太慢或 I/O 太忙。 - -### 第六行：存储空间面板 - -![第六行存储空间面板](/media/lightning-grafana-row-6.png) - -| 面板名称 | 序列 |描述 | -|:-----|:-----|:-----| -| SQL process rate | data deliver rate | 向 TiKV Importer 发送数据键值对的速度 | -| SQL process rate | index deliver rate | 向 TiKV Importer 发送索引键值对的速度 | -| SQL process rate | total deliver rate | 发送数据键值对及索引键值对的速度之和 | -| Total bytes | parser read size | TiDB Lightning 正在读取的字节数 | -| Total bytes | data deliver size | 已发送到 TiKV Importer 的数据键值对的字节数 | -| Total bytes | index deliver size | 已发送到 TiKV Importer 的索引键值对的字节数 | -| Total bytes | storage_size/3 | TiKV 集群占用的存储空间大小的 1/3（3 为默认的副本数量）| - -### 第七行：导入速度面板 - -![第七行导入速度面板](/media/lightning-grafana-row-7.png) - -| 面板名称 | 序列 | 描述 | -|:-----|:-----|:-----| -| Delivery duration | Range delivery | 将一个 range 的键值对上传到 TiKV 集群所消耗的时间 | -| Delivery duration | SST delivery | 将单个 SST 文件上传到 TiKV 集群所消耗的时间 | -| SST process duration | Split SST | 将键值对流切分成若干 SST 文件所消耗的时间 | -| SST process duration | SST upload | 上传单个 SST 文件所消耗的时间 | -| SST process duration | SST ingest | ingest 单个 SST 文件所消耗的时间 | -| SST process duration | SST size | 单个 SST 文件的大小 | - -## 监控指标 - -本节将详细描述 `tikv-importer` 和 `tidb-lightning` 的监控指标。 - -### `tikv-importer` - -`tikv-importer` 的监控指标皆以 `tikv_import_*` 为前缀。 - -- **`tikv_import_rpc_duration`**（直方图） - - 完成一次 RPC 用时直方图。标签： - - - **request**：所执行 RPC 请求的类型 - * `switch_mode` — 将一个 TiKV 节点切换为 import/normal 模式 - * `open_engine` — 打开引擎文件 - * `write_engine` — 接收数据并写入引擎文件 - * `close_engine` — 关闭一个引擎文件 - * `import_engine` — 导入一个引擎文件到 TiKV 集群中 - * `cleanup_engine` — 删除一个引擎文件 - * `compact_cluster` — 显式压缩 TiKV 集群 - * `upload` — 上传一个 SST 文件 - * `ingest` — Ingest 一个 SST 文件 - * `compact` — 显式压缩一个 TiKV 节点 - - **result**：RPC 请求的执行结果 - * `ok` - * `error` - -- **`tikv_import_write_chunk_bytes`**（直方图） - - 从 Lightning 接收的键值对区块大小（未压缩）的直方图。 - -- **`tikv_import_write_chunk_duration`**（直方图） - - 从 `tidb-lightning` 接收每个键值对区块所需时间的直方图。 - -- **`tikv_import_upload_chunk_bytes`**（直方图） - - 上传到 TiKV 的每个 SST 文件区块大小（压缩）的直方图。 - -- **`tikv_import_range_delivery_duration`**（直方图） - - 将一个 range 的键值对发送至 `dispatch-job` 任务所需时间的直方图。 - -- **`tikv_import_split_sst_duration`**（直方图） - - 将 range 从引擎文件中分离到单个 SST 文件中所需时间的直方图。 - -- **`tikv_import_sst_delivery_duration`**（直方图） - - 将 SST 文件从 `dispatch-job` 任务发送到 `ImportSSTJob` 任务所需时间的直方图 - -- **`tikv_import_sst_recv_duration`**（直方图） - - `ImportSSTJob` 任务接收从 `dispatch-job` 任务发送过来的 SST 文件所需时间的直方图。 - -- **`tikv_import_sst_upload_duration`**（直方图） - - 从 `ImportSSTJob` 任务上传 SST 文件到 TiKV 节点所需时间的直方图。 - -- **`tikv_import_sst_chunk_bytes`**（直方图） - - 上传到 TiKV 节点的 SST 文件（压缩）大小的直方图。 - -- **`tikv_import_sst_ingest_duration`**（直方图） - - 将 SST 文件传入至 TiKV 所需时间的直方图。 - -- **`tikv_import_each_phase`**（测量仪） - - 表示运行阶段。值为 1 时表示在阶段内运行，值为 0 时表示在阶段内运行。标签： - - - **phase**：`prepare` / `import` - -- **`tikv_import_wait_store_available_count`**（计数器） - - 计算出现 TiKV 节点没有充足空间上传 SST 文件现象的次数。标签： - - - **store_id**： TiKV 存储 ID。 - -- **`tikv_import_upload_chunk_duration`**（直方图） - - 上传到 TiKV 的每个区块所需时间的直方图。 - -### `tidb-lightning` - -`tidb-lightning` 的监控指标皆以 `lightning_*` 为前缀。 - -- **`lightning_importer_engine`**（计数器） - - 计算已开启及关闭的引擎文件数量。标签： - - - **type**: - * `open` - * `closed` - -- **`lightning_idle_workers`**（计量表盘） - - 计算闲置的 worker。标签： - - - **name**： - * `table` — 未使用的 `table-concurrency` 的数量，通常为 0，直到进程结束 - * `index` — 未使用的 `index-concurrency` 的数量，通常为 0，直到进程结束 - * `region` — 未使用的 `region-concurrency` 的数量，通常为 0，直到进程结束 - * `io` — 未使用的 `io-concurrency` 的数量，通常接近配置值（默认为 5），接近 0 时表示磁盘运行太慢 - * `closed-engine` — 已关闭但未清理的引擎数量，通常接近 `index-concurrency` 与 `table-concurrency` 的和（默认为 8），接近 0 时表示 TiDB Lightning 比 TiKV Importer 快，导致 TiDB Lightning 延迟 - -- **`lightning_kv_encoder`**（计数器） - - 计算已开启及关闭的 KV 编码器。KV 编码器是运行于内存的 TiDB 实例，用于将 SQL 的 `INSERT` 语句转换成键值对。此度量的净值（开启减掉关闭）在正常情况下不应持续增长。标签： - - - **type**: - * `open` - * `closed` - -- **`lightning_tables`**（计数器） - - 计算处理过的表及其状态。标签： - - - **state**：表的状态，表明当前应执行的操作 - * `pending` — 等待处理 - * `written` — 所有数据已编码和传输 - * `closed` — 所有对应的引擎文件已关闭 - * `imported` — 所有引擎文件已上传到目标集群 - * `altered_auto_inc` — 自增 ID 已改 - * `checksum` — 已计算校验和 - * `analyzed` — 已进行统计信息分析 - * `completed` — 表格已完全导入并通过验证 - - **result**：当前操作的执行结果 - * `success` — 成功 - * `failure` — 失败（未完成） - -- **`lightning_engines`**（计数器） - - 计算处理后引擎文件的数量以及其状态。标签： - - - **state**：引擎文件的状态，表明当前应执行的操作 - * `pending` — 等待处理 - * `written` — 所有数据已编码和传输 - * `closed` — 引擎文件已关闭 - * `imported` — 当前引擎文件已上传到目标集群 - * `completed` — 当前引擎文件已完全导入 - - **result**：当前操作的执行结果 - * `success` — 成功 - * `failure` — 失败（未完成） - -- **`lightning_chunks`**（计数器） - - 计算处理过的 Chunks 及其状态。标签： - - - **state**: 单个 Chunk 的状态，表明该 Chunk 当前所处的阶段 - * `estimated` — （非状态）当前任务中 Chunk 的数量 - * `pending` — 已载入但未执行 - * `running` — 正在编码和发送数据 - * `finished` — 该 Chunk 已处理完毕 - * `failed` — 处理过程中发生错误 - -- **`lightning_import_seconds`**（直方图） - - 导入每个表所需时间的直方图。 - -- **`lightning_row_read_bytes`**（直方图） - - 单行 SQL 数据大小的直方图。 - -- **`lightning_row_encode_seconds`**（直方图） - - 解码单行 SQL 数据到键值对所需时间的直方图。 - -- **`lightning_row_kv_deliver_seconds`**（直方图） - - 发送一组与单行 SQL 数据对应的键值对所需时间的直方图。 - -- **`lightning_block_deliver_seconds`**（直方图） - - 每个键值对中的区块传送到 `tikv-importer` 所需时间的直方图。 - -- **`lightning_block_deliver_bytes`**（直方图） - - 发送到 Importer 的键值对中区块（未压缩）的大小的直方图。 - -- **`lightning_chunk_parser_read_block_seconds`**（直方图） - - 数据文件解析每个 SQL 区块所需时间的直方图。 - -- **`lightning_checksum_seconds`**（直方图） - - 计算表中 Checksum 所需时间的直方图。 - -- **`lightning_apply_worker_seconds`**（直方图） - - 获取闲置 worker 等待时间的直方图 (参见 `lightning_idle_workers` 计量表盘)。标签： - - - **name**： - * `table` - * `index` - * `region` - * `io` - * `closed-engine` diff --git a/v3.1/reference/tools/tidb-lightning/overview.md b/v3.1/reference/tools/tidb-lightning/overview.md deleted file mode 100644 index 7b03dce68473..000000000000 --- a/v3.1/reference/tools/tidb-lightning/overview.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: TiDB Lightning 简介 -category: reference ---- - -# TiDB Lightning 简介 - -TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量数据的备份恢复。目前，支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning： - -- **迅速**导入**大量新**数据。 -- 备份恢复所有数据。 - -## TiDB Lightning 整体架构 - -TiDB Lightning 主要包含两个部分： - -- **`tidb-lightning`**（“前端”）：主要完成适配工作，通过读取数据源，在下游 TiDB 集群建表、将数据转换成键值对（KV 对）发送到 `tikv-importer`、检查数据完整性等。 -- **`tikv-importer`**（“后端”）：主要完成将数据导入 TiKV 集群的工作，对 `tidb-lightning` 写入的键值对进行缓存、排序、切分操作并导入到 TiKV 集群。 - -![TiDB Lightning 整体架构](/media/tidb-lightning-architecture.png) - -TiDB Lightning 整体工作原理如下： - -1. 在导数据之前，`tidb-lightning` 会自动将 TiKV 集群切换为“导入模式” (import mode)，优化写入效率并停止自动压缩。 - -2. `tidb-lightning` 会在目标数据库建立架构和表，并获取其元数据。 - -3. 每张表都会被分割为多个连续的**区块**，这样来自大表 (200 GB+) 的数据就可以用增量方式导入。 - -4. `tidb-lightning` 会通过 gRPC 让 `tikv-importer` 为每一个区块准备一个“引擎文件 (engine file)”来处理键值对。`tidb-lightning` 会并发读取 SQL dump，将数据源转换成与 TiDB 相同编码的键值对，然后发送到 `tikv-importer` 里对应的引擎文件。 - -5. 当一个引擎文件数据写入完毕时，`tikv-importer` 便开始对目标 TiKV 集群数据进行分裂和调度，然后导入数据到 TiKV 集群。 - - 引擎文件包含两种：**数据引擎**与**索引引擎**，各自又对应两种键值对：行数据和次级索引。通常行数据在数据源里是完全有序的，而次级索引是无序的。因此，数据引擎文件在对应区块写入完成后会被立即上传，而所有的索引引擎文件只有在整张表所有区块编码完成后才会执行导入。 - -6. 整张表相关联的所有引擎文件完成导入后，`tidb-lightning` 会对比本地数据源及下游集群的校验和 (checksum)，确保导入的数据无损，然后让 TiDB 分析 (`ANALYZE`) 这些新增的数据，以优化日后的操作。同时，`tidb-lightning` 调整 `AUTO_INCREMENT` 值防止之后新增数据时发生冲突。 - - 表的自增 ID 是通过行数的**上界**估计值得到的，与表的数据文件总大小成正比。因此，最后的自增 ID 通常比实际行数大得多。这属于正常现象，因为在 TiDB 中自增 ID [不一定是连续分配的](/v3.1/reference/mysql-compatibility.md#auto-increment-id)。 - -7. 在所有步骤完毕后，`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode)，此后 TiDB 集群可以正常对外提供服务。 - -TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似，使用 TiDB-backend 时，`tidb-lightning` 将数据转换为 `INSERT` 语句，然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md)。 \ No newline at end of file diff --git a/v3.1/reference/tools/tidb-lightning/table-filter.md b/v3.1/reference/tools/tidb-lightning/table-filter.md deleted file mode 100644 index 00cd77e41c7a..000000000000 --- a/v3.1/reference/tools/tidb-lightning/table-filter.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: TiDB Lightning 表库过滤 -summary: 使用黑白名单把一些表剔出要导入的范围。 -category: reference ---- - -# TiDB Lightning 表库过滤 - -TiDB Lightning 支持使用黑名单和白名单来过滤掉某些数据库和表。这可以用来跳过一些用作暂存、毋须迁移的表，或用来手动切分数据源，让多机同时导入。 - -这些过滤规则与 MySQL 的 `replication-rules-db`/`replication-rules-table` 类似。 - -## 过滤数据库 - -```toml -[black-white-list] -do-dbs = ["pattern1", "pattern2", "pattern3"] -ignore-dbs = ["pattern4", "pattern5"] -``` - -* 如果 `[black-white-list]` 下的 `do-dbs` 列表不为空， - * 如数据库名称匹配 `do-dbs` 列表中**任何**一项，则数据库会被导入。 - * 否则，数据库会被略过。 -* 否则，如果数据库名称匹配 `ignore-dbs` 列表中**任何**一项，数据库会被略过。 -* 如果数据库名称**同时**匹配 `do-dbs` 和 `ignore-dbs` 列表，数据库会被导入。 - -如果匹配项首字符为 `~`，它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 - -> **注意：** -> -> 无论你如何设置过滤规则，系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 - -## 过滤表 - -```toml -[[black-white-list.do-tables]] -db-name = "db-pattern-1" -tbl-name = "table-pattern-1" - -[[black-white-list.do-tables]] -db-name = "db-pattern-2" -tbl-name = "table-pattern-2" - -[[black-white-list.do-tables]] -db-name = "db-pattern-3" -tbl-name = "table-pattern-3" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-4" -tbl-name = "table-pattern-4" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-5" -tbl-name = "table-pattern-5" -``` - -* 如果 `do-tables` 列表不为空， - * 如果表的限定名称匹配 `do-tables` 列表中**任何**一对，则表会被导入。 - * 否则，表会被略过。 -* 否则，如果表的限定名称匹配 `ignore-tables` 列表中**任何**一对，表会被略过。 -* 如果表的限定名称**同时**匹配 `do-tables` 和 `ignore-tables` 列表，表会被导入。 - -> **注意：** -> -> Lightning 会先执行数据库过滤规则，之后才执行表的过滤规则。所以，如果一个数据库已被 `ignore-dbs` 略过，即使其下的表匹配 `do-tables` 也不会再被导入。 - -## 例子 - -以下例子演示过滤规则的操作原理。假设数据源包含这些表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -`admin`.`secrets` -``` - -我们使用以下设置： - -```toml -[black-white-list] -do-dbs = [ - "forum_backup_2018", # 规则 A - "~^(logs|forum)$", # 规则 B -] -ignore-dbs = [ - "~^forum_backup_", # 规则 C -] - -[[black-white-list.do-tables]] # 规则 D -db-name = "logs" -tbl-name = "~_2018$" - -[[black-white-list.ignore-tables]] # 规则 E -db-name = "~.*" -tbl-name = "~^messages.*" - -[[black-white-list.do-tables]] # 规则 F -db-name = "~^forum.*" -tbl-name = "messages" -``` - -首先进行数据库过滤： - -| 数据库 | 结果 | -|---------------------------|--------------| -| `` `logs` `` | 导入（规则 B） | -| `` `forum` `` | 导入（规则 B） | -| `` `forum_backup_2016` `` | 略过（规则 C） | -| `` `forum_backup_2017` `` | 略过（规则 C） | -| `` `forum_backup_2018` `` | 导入（规则 A）（不会考虑规则 C） | -| `` `admin` `` | 略过（`do-dbs` 不为空，且没有匹配的项目） | - -然后进行表过滤： - -| 表 | 结果 | -|--------------------------------------|--------------| -| `` `logs`.`messages_2016` `` | 略过（规则 E） | -| `` `logs`.`messages_2017` `` | 略过（规则 E） | -| `` `logs`.`messages_2018` `` | 导入（规则 D）（不会考虑规则 E） | -| `` `forum`.`users` `` | 略过（`do-tables` 不为空，且没有匹配的项目） | -| `` `forum`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `forum_backup_2016`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2017`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2018`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `admin`.`secrets` `` | 略过（数据库已被剔除） | diff --git a/v3.1/reference/tools/tidb-lightning/tidb-backend.md b/v3.1/reference/tools/tidb-lightning/tidb-backend.md deleted file mode 100644 index 9703033a2834..000000000000 --- a/v3.1/reference/tools/tidb-lightning/tidb-backend.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: TiDB Lightning TiDB-Backend -summary: 了解 TiDB Lightning TiDB-backend。 -category: reference ---- - -# TiDB Lightning TiDB-Backend - -TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前，TiDB Lightning 支持 Importer-backend（默认）和 TiDB-backend 两种后端，两者导入数据的区别如下： - -* **Importer-backend**：`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对，由 `tikv-importer` 对写入的键值对进行排序，然后把这些键值对 Ingest 到 TiKV 节点中。 - -* **TiDB-backend**：`tidb-lightning` 先将数据编码成 `INSERT` 语句，然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 - -| 后端 | Importer-backend | TiDB-backend | -|:---|:---|:---| -| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | -| 资源使用率 | 高 | 低 | -| 导入时是否满足 ACID | 否 | 是 | -| 目标表 | 必须为空 | 可以不为空 | - -## 部署 TiDB-backend - -使用 TiDB-backend 时，你无需部署 `tikv-importer`。与[标准部署过程](/v3.1/reference/tools/tidb-lightning/deployment.md)相比，部署 TiDB-backend 时有如下不同： - -* 可以跳过所有涉及 `tikv-importer` 的步骤。 -* 必须更改相应配置申明使用的是 TiDB-backend。 - -### 硬件需求 - -使用 TiDB-backend 时， TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此，即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下： - -* 16 逻辑核 CPU -* 足够储存整个数据源的 SSD 硬盘，读取速度越快越好 -* 千兆网卡 - -### 使用 Ansible 部署 - -1. `inventory.ini` 文件中，`[importer_server]` 部分可以留空。 - - ```ini - ... - - [importer_server] - # keep empty - - [lightning_server] - 192.168.20.10 - - ... - ``` - -2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置，`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 - - ```yaml - ... - tikv_importer: - backend: "tidb" # <-- 改成 “tidb” - ... - ``` - -3. 启动、部署集群。 - -4. 为 TiDB Lightning 挂载数据源。 - -5. 启动 `tidb-lightning`。 - -### 手动部署 - -手动部署时，你无需下载和配置 `tikv-importer`。 - -在运行 `tidb-lightning` 之前，在配置文件中加上如下几行： - -```toml -[tikv-importer] -backend = "tidb" -``` - -或者在用命令行启动 `tidb-lightning` 时，传入参数 `--backend tidb`。 - -## 冲突解决 - -TiDB-backend 支持导入到已填充的表（非空表）。但是，新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为： - -```toml -[tikv-importer] -backend = "tidb" -on-duplicate = "replace" # 或者 “error”、“ignore” -``` - -| 设置 | 冲突时默认行为 | 对应 SQL 语句 | -|:---|:---|:---| -| replace | 新数据替代旧数据 | `REPLACE INTO ...` | -| ignore | 保留旧数据，忽略新数据 | `INSERT IGNORE INTO ...` | -| error | 中止导入 | `INSERT INTO ...` | - -## 从 Loader 迁移到 TiDB Lightning TiDB-backend - -TiDB Lightning TiDB-backend 可以完全取代 [Loader](/v3.1/reference/tools/loader.md)。下表说明了如何将 [Loader](/v3.1/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/v3.1/reference/tools/tidb-lightning/config.md)中： - -
- - - - - - - - - -
LoaderTiDB Lightning
- -```toml -# 日志 -log-level = "info" -log-file = "loader.log" -# Prometheus -status-addr = ":8272" -# 线程数 -pool-size = 16 -``` - - - -```toml -[lightning] -# 日志 -level = "info" -file = "tidb-lightning.log" -# Prometheus -pprof-port = 8289 -# 并发度 (最好使用默认设置) -#region-concurrency = 16 -``` - -
- -```toml -# 断点数据库名 -checkpoint-schema = "tidb_loader" -``` - - - -```toml -[checkpoint] -# 断点存储 -enable = true -schema = "tidb_lightning_checkpoint" -# 断点默认存储在本地的文件系统，这样更高效。但你也可以 -# 选择将断点存储在目标数据库中，设置如下： -# driver = "mysql" -``` - -
- -```toml -``` - - - -```toml -[tikv-importer] -# 使用 TiDB-backend -backend = "tidb" -``` - -
- -```toml -# 数据源目录 -dir = "/data/export/" -``` - - - -```toml -[mydumper] -# 数据源目录 -data-source-dir = "/data/export" -``` - -
- -```toml -[db] -# TiDB 连接参数 -host = "127.0.0.1" -port = 4000 -user = "root" -password = "" -#sql-mode = "" -``` - - - -```toml -[tidb] -# TiDB 连接参数 -host = "127.0.0.1" -port = 4000 -status-port = 10080 # <- 必须有的参数 -user = "root" -password = "" -#sql-mode = "" -``` - -
diff --git a/v3.1/reference/tools/tidb-lightning/web.md b/v3.1/reference/tools/tidb-lightning/web.md deleted file mode 100644 index a27fd4167219..000000000000 --- a/v3.1/reference/tools/tidb-lightning/web.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: TiDB Lightning Web 界面 -summary: 了解 TiDB Lightning 的服务器模式——通过 Web 界面来控制 TiDB Lightning。 -category: reference ---- - -# TiDB Lightning Web 界面 - -TiDB Lightning 支持在网页上查看导入进度或执行一些简单任务管理，这就是 TiDB Lightning 的**服务器模式**。本文将介绍服务器模式下的 Web 界面和一些常见操作。 - -启用服务器模式的方式有如下几种： - -1. 在启动 `tidb-lightning` 时加上命令行参数 `--server-mode`。 - - ```sh - ./tidb-lightning --server-mode --status-addr :8289 - ``` - -2. 在配置文件中设置 `lightning.server-mode`。 - - ```toml - [lightning] - server-mode = true - status-addr = ':8289' - ``` - -TiDB Lightning 启动后，可以访问 `http://127.0.0.1:8289` 来管理程序（实际的 URL 取决于你的 `status-addr` 设置）。 - -服务器模式下，TiDB Lightning 不会立即开始运行，而是通过用户在 web 页面提交（多个）**任务**来导入数据。 - -## TiDB Lightning Web 首页 - -![TiDB Lightning Web 首页](/media/lightning-web-frontpage.png) - -标题栏上图标所对应的功能，从左到右依次为： - -| 图标 | 功能 | -|:----|:----| -| "TiDB Lightning" | 点击即返回首页 | -| ⚠ | 显示**前一个**任务的所有错误信息 | -| ⓘ | 列出当前及队列中的任务，可能会出现一个标记提示队列中任务的数量 | -| + | 提交单个任务 | -| ⏸/▶ | 暂停/继续当前操作 | -| ⟳ | 设置网页自动刷新 | - -标题栏下方的三个面板显示了不同状态下的所有表： - -* Active：当前正在导入这些表 -* Completed：这些表导入成功或失败 -* Pending：这些表还没有被处理 - -每个面板都包含用于描述表状态的卡片。 - -## 提交任务 - -点击标题栏的 **+** 图标提交任务。 - -![提交任务对话框](/media/lightning-web-submit.png) - -任务 (task) 为 TOML 格式的文件，具体参考 [TiDB Lightning 任务配置](/v3.1/reference/tools/tidb-lightning/config.md#tidb-lightning-任务配置参数)。你也可以点击 **UPLOAD** 上传一个本地的 TOML 文件。 - -点击 **SUBMIT** 运行任务。如果当前有任务正在运行，新增任务会加入队列并在当前任务结束后执行。 - -## 查看导入进度 - -点击首页表格卡片上的 **>** 图标，查看表格导入的详细进度。 - -![表格导入进度](/media/lightning-web-table.png) - -该页显示每张表的引擎文件的导入过程。 - -点击标题栏上的 **TiDB Lightning** 返回首页。 - -## 管理任务 - -单击标题栏上的 **ⓘ** 图标来管理当前及队列中的任务。 - -![任务管理页面](/media/lightning-web-queue.png) - -每个任务都是依据提交时间来标记。点击该任务将显示 JSON 格式的配置文件。 - -点击任务上的 **⋮** 可以对该任务进行管理。你可以立即停止任务，或重新排序队列中的任务。 diff --git a/v3.1/reference/tools/tikv-control.md b/v3.1/reference/tools/tikv-control.md deleted file mode 100644 index 77e63b91387a..000000000000 --- a/v3.1/reference/tools/tikv-control.md +++ /dev/null @@ -1,414 +0,0 @@ ---- -title: TiKV Control 使用说明 -category: reference ---- - -# TiKV Control 使用说明 - -TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管理 TiKV 集群。 - -编译 TiKV 的同时也会编译 tikv-ctl 命令。如果通过 Ansible 部署集群，则对应的 `tidb-ansible/resources/bin` 目录下会存在 `tikv-ctl` 二进制文件。如果使用二进制文件部署集群，bin 目录下会包含 `tikv-ctl` 文件及 `tidb-server`、`pd-server`、以及 `tikv-server` 等其他文件。 - -## 通用参数 - -tikv-ctl 提供以下两种运行模式： - -- **远程模式**。通过 `--host` 选项接受 TiKV 的服务地址作为参数。在此模式下，如果 TiKV 启用了 SSL，则 tikv-ctl 也需要指定相关的证书文件，例如： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --ca-path ca.pem --cert-path client.pem --key-path client-key.pem --host 127.0.0.1:20160 - ``` - - 某些情况下，tikv-ctl 与 PD 进行通信，而不与 TiKV 通信。此时你需要使用 `--pd` 选项而非 `--host` 选项，例如： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --pd 127.0.0.1:2379 compact-cluster - ``` - - ``` - store:"127.0.0.1:20160" compact db:KV cf:default range:([], []) success! - ``` - -- **本地模式**。通过 `--db` 选项来指定本地 TiKV 数据的目录路径。在此模式下，需要停止正在运行的 TiKV 实例。 - -以下如无特殊说明，所有命令都同时支持这两种模式。 - -除此之外，tikv-ctl 还有两个简单的命令 `--to-hex` 和 `--to-escaped`，用于对 key 的形式作简单的变换。一般使用 `escaped` 形式，示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --to-escaped 0xaaff -``` - -``` -\252\377 -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --to-hex "\252\377" -``` - -``` -AAFF -``` - -> **注意：** -> -> 在命令行上指定 `escaped` 形式的 key 时，需要用双引号引起来，否则 bash 会将反斜杠吃掉，导致结果错误。 - -## 各项子命令及部分参数、选项 - -下面逐一对 tikv-ctl 支持的子命令进行举例说明。有的子命令支持很多可选参数，要查看全部细节，可运行 `tikv-ctl --help `。 - -### 查看 Raft 状态机的信息 - -`raft` 子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 **RegionLocalState**、**RaftLocalState** 和 **RegionApplyState** 三个结构体，及某一条 log 对应的 Entries。 - -您可以使用 `region` 和 `log` 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。它们的用法及输出内容如下所示： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 raft region -r 2 -``` - -``` -region id: 2 -region state key: \001\003\000\000\000\000\000\000\000\002\001 -region state: Some(region {id: 2 region_epoch {conf_ver: 3 version: 1} peers {id: 3 store_id: 1} peers {id: 5 store_id: 4} peers {id: 7 store_id: 6}}) -raft state key: \001\002\000\000\000\000\000\000\000\002\002 -raft state: Some(hard_state {term: 307 vote: 5 commit: 314617} last_index: 314617) -apply state key: \001\002\000\000\000\000\000\000\000\002\003 -apply state: Some(applied_index: 314617 truncated_state {index: 313474 term: 151}) -``` - -### 查看 Region 的大小 - -`size` 命令可以查看 Region 的大小： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db size -r 2 -``` - -``` -region id: 2 -cf default region size: 799.703 MB -cf write region size: 41.250 MB -cf lock region size: 27616 -``` - -### 扫描查看给定范围的 MVCC - -`scan` 命令的 `--from` 和 `--to` 参数接受两个 escaped 形式的 raw key，并用 `--show-cf` 参数指定只需要查看哪些列族。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db scan --from 'zm' --limit 2 --show-cf lock,default,write -``` - -``` -key: zmBootstr\377a\377pKey\000\000\377\000\000\373\000\000\000\000\000\377\000\000s\000\000\000\000\000\372 - write cf value: start_ts: 399650102814441473 commit_ts: 399650102814441475 short_value: "20" -key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371 - write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002" - write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001" -``` - -### 查看给定 key 的 MVCC - -与上个命令类似，`mvcc` 命令可以查看给定 key 的 MVCC： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db mvcc -k "zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371" --show-cf=lock,write,default -``` - -``` -key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371 - write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002" - write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001" -``` - -> **注意：** -> -> 该命令中，key 同样需要是 escaped 形式的 raw key。 - -### 打印某个 key 的值 - -打印某个 key 的值需要用到 `print` 命令。示例从略。 - -### 打印 Region 的 properties 信息 - -为了记录 Region 的状态信息，TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 `region-properties` 运行 tikv-ctl 来查看这些 properties 信息。例如： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host localhost:20160 region-properties -r 2 -``` - -``` -num_files: 0 -num_entries: 0 -num_deletes: 0 -mvcc.min_ts: 18446744073709551615 -mvcc.max_ts: 0 -mvcc.num_rows: 0 -mvcc.num_puts: 0 -mvcc.num_versions: 0 -mvcc.max_row_versions: 0 -middle_key_by_approximate_size: -``` - -这些 properties 信息可以用于检查某个 Region 是否健康或者修复不健康的 Region。例如，使用 `middle_key_approximate_size` 可以手动分裂 Region。 - -### 手动 compact 单个 TiKV 的数据 - -`compact` 命令可以对单个 TiKV 进行手动 compact。如果指定 `--from` 和 `--to` 选项，那么它们的参数也是 escaped raw key 形式的。`--host` 参数可以指定要 compact 的 TiKV，`-d` 参数可以指定要 compact 的 RocksDB，有 `kv` 和 `raft` 参数值可以选。`--threads` 参数可以指定 compact 的并发数，默认值是 8。一般来说，并发数越大， compact 的速度越快，但是也会对服务造成影响，所以需要根据情况选择合适的并发数。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 compact -d kv -``` - -``` -success! -``` - -### 手动 compact 整个 TiKV 集群的数据 - -`compact-cluster` 命令可以对整个 TiKV 集群进行手动 compact。该命令参数的含义和使用与 `compact` 命令一样。 - -### 设置一个 Region 为 tombstone - -`tombstone` 命令常用于没有开启 sync-log，因为机器掉电导致 Raft 状态机丢失部分写入的情况。它可以在一个 TiKV 实例上将一些 Region 设置为 Tombstone 状态，从而在重启时跳过这些 Region。这些 Region 应该在其他 TiKV 上有足够多的健康的副本以便能够继续通过 Raft 机制进行读写。 - -{{< copyable "" >}} - -```shell -pd-ctl>> operator add remove-peer -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r -``` - -``` -success! -``` - -> **注意：** -> -> - **该命令只支持本地模式** -> - `-p` 选项的参数指定 PD 的 endpoints，无需 `http` 前缀。指定 PD 的 endpoints 是为了询问 PD 是否可以安全切换至 Tombstone 状态。因此，在将 PD 置为 Tombstone 之前往往还需要在 `pd-ctl` 中把该 Region 在机器上的对应 Peer 拿掉。 - -### 向 TiKV 发出 consistency-check 请求 - -`consistency-check` 命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败，TiKV 自身会 panic。如果 `--host` 指定的 TiKV 不是这个 Region 的 Leader，则会报告错误。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2 -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:21061 consistency-check -r 2 -``` - -``` -DebugClient::check_region_consistency: RpcFailure(RpcStatus { status: Unknown, details: Some("StringError(\"Leader is on store 1\")") }) -``` - -> **注意：** -> -> - **该命令只支持远程模式**。 -> - 即使该命令返回了成功信息，也需要检查是否有 TiKV panic 了。因为该命令只是向 Leader 请求进行一致性检查，但整个检查流程是否成功并不能在客户端知道。 - -### Dump snapshot 元文件 - -这条子命令可以用于解析指定路径下的 Snapshot 元文件并打印结果。 - -### 打印 Raft 状态机出错的 Region - -前面 `tombstone` 命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态，避免 TiKV 启动时对它们进行检查。在运行 `tombstone` 命令之前，可使用 `bad-regions` 命令找到出错的 Region，以便将多个工具组合起来进行自动化的处理。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db bad-regions -``` - -``` -all regions are healthy -``` - -命令执行成功后会打印以上信息，否则会打印出有错误的 Region 列表。目前可以检出的错误包括 `last index`、`commit index` 和 `apply index` 之间的不匹配，以及 Raft log 的丢失。其他一些情况，比如 Snapshot 文件损坏等仍然需要后续的支持。 - -### 查看 Region 属性 - -本地查看部署在 `/path/to/tikv` 的 tikv 上面 Region 2 的 properties 信息： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/data/db region-properties -r 2 -``` - -在线查看运行在 `127.0.0.1:20160` 的 tikv 上面 Region 2 的 properties 信息： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --host 127.0.0.1:20160 region-properties -r 2 -``` - -### 动态修改 TiKV 的 RocksDB 相关配置 - -使用 `modify-tikv-config` 命令可以动态修改配置参数，暂时仅支持对于 RocksDB 相关参数的动态更改。 - -- `-m` 用于指定要修改的模块，有 `storage`、`kvdb` 和 `raftdb` 三个值可以选择。 -- `-n` 用于指定配置名。配置名可以参考 [TiKV 配置模版](https://github.com/pingcap/tikv/blob/master/etc/config-template.toml#L213-L500)中 `[storage]`、`[rocksdb]` 和 `[raftdb]` 下的参数，分别对应 `storage`、`kvdb` 和 `raftdb`。同时，还可以通过 `default|write|lock + . + 参数名` 的形式来指定的不同 CF 的配置。对于 `kvdb` 有 `default`、`write` 和 `lock` 可以选择，对于 `raftdb` 仅有 `default` 可以选择。 -- `-v` 用于指定配置值。 - -设置 `shared block cache` 的大小： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m storage -n block_cache.capacity -v 10GB -``` - -``` -success! -``` - -当禁用 `shared block cache` 时，为 `write` CF 设置 `block cache size`： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m kvdb -n write.block_cache_size -v 256MB -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m kvdb -n max_background_jobs -v 8 -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl modify-tikv-config -m raftdb -n default.disable_auto_compactions -v true -``` - -``` -success! -``` - -### 强制 Region 从多副本失败状态恢复服务 - -`unsafe-recover remove-fail-stores` 命令可以将故障机器从指定 Region 的 peer 列表中移除。运行命令之前，需要目标 TiKV 先停掉服务以便释放文件锁。 - -`-s` 选项接受多个以逗号分隔的 `store_id`，并使用 `-r` 参数来指定包含的 Region。如果要对某一个 store 上的全部 Region 都执行这个操作，可简单指定 `--all-regions`。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 3 -r 1001,1002 -``` - -``` -success! -``` - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 4,5 --all-regions -``` - -之后启动 TiKV，这些 Region 便可以使用剩下的健康副本继续提供服务了。此命令常用于多个 TiKV store 损坏或被删除的情况。 - -> **注意：** -> -> - 该命令只支持本地模式。在运行成功后，会打印 `success!`。 -> - 一般来说，您需要为指定 Region 的 peers 所在的每个 store 运行此命令。 -> - 如果使用 `--all-regions`，通常需要在集群剩余所有健康的 store 上执行此命令。 - -### 恢复损坏的 MVCC 数据 - -`recover-mvcc` 命令用于 MVCC 数据损坏导致 TiKV 无法正常运行的情况。为了从不同种类的不一致情况中恢复，该命令会交叉检查 3 个 CF ("default", "write", "lock")。 - -`-r` 选项可以通过 `region_id` 指定包含的 Region，`-p` 选项可以指定 PD 的 endpoints。 - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl --db /path/to/tikv/db recover-mvcc -r 1001,1002 -p 127.0.0.1:2379 -``` - -``` -success! -``` - -> **注意：** -> -> - 该命令只支持本地模式。在运行成功后，会打印 `success!`。 -> - `-p` 选项指定 PD 的 endpoint，不使用 `http` 前缀，用于查询指定的 `region_id` 是否有效。 -> - 对于指定 Region 的 peers 所在的每个 store，均须执行该命令。 - -### Ldb 命令 - -ldb 命令行工具提供多种数据访问以及数据库管理命令。下方列出了一些示例用法。详细信息请在运行 `tikv-ctl ldb` 命令时查看帮助消息或查阅 RocksDB 文档。 - -数据访问序列示例如下。 - -用 HEX 格式 dump 现有 RocksDB 数据: - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl ldb --hex --db=/tmp/db dump -``` - -dump 现有 RocksDB 的声明： - -{{< copyable "shell-regular" >}} - -```shell -tikv-ctl ldb --hex manifest_dump --path=/tmp/db/MANIFEST-000001 -``` - -您可以通过 `--column_family=` 指定查询的目标列族。 - -通过 `--try_load_options` 命令加载数据库选项文件以打开数据库。在数据库运行时，建议您保持该命令为开启的状态。如果您使用默认配置打开数据库，LSM-tree 存储组织可能会出现混乱，且无法自动恢复。 diff --git a/v3.1/reference/tools/user-guide.md b/v3.1/reference/tools/user-guide.md deleted file mode 100644 index 04b59d94d27d..000000000000 --- a/v3.1/reference/tools/user-guide.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: TiDB 生态工具使用指南 -category: reference -aliases: ['/docs-cn/v3.1/how-to/migrate/from-mysql/', '/docs-cn/v3.1/how-to/migrate/incrementally-from-mysql/', '/docs-cn/v3.1/how-to/migrate/overview/', '/docs-cn/v3.1/reference/tools/use-guide/'] ---- - -# TiDB 生态工具使用指南 - -目前 TiDB 生态工具较多，有些工具之间有功能重叠，也有些属于版本迭代关系。本文档将对各个工具进行介绍，说明各个工具之间的关系，并且说明各个版本、场景下应该使用哪些工具。 - -## TiDB 生态工具概览 - -TiDB 生态工具可以分为几种： - -- 数据导入类，包括全量导入工具、备份和恢复工具、增量导入工具等 -- 数据导出类，包括全量导出工具、增量导出工具等 - -下面将分别介绍这两类工具。 - -### 数据导入类 - -#### 全量导入工具 Loader（停止维护，不推荐使用） - -[Loader](/v3.1/reference/tools/loader.md) 是一款轻量级的全量数据导入工具，数据以 SQL 的形式导入到 TiDB 中。目前这个工具正在逐步被 [TiDB Lightning](#全量导入工具-tidb-lightning) 替换掉，参见 [TiDB Lightning TiDB-backend 文档](/v3.1/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。 - -以下是 Loader 的一些基本信息： - -- Loader 的输入：Mydumper 输出的文件 -- Loader 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：[备份与恢复](/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md) - -#### 全量导入工具 TiDB Lightning - -[TiDB Lightning](/v3.1/reference/tools/tidb-lightning/overview.md) 是将全量数据快速导入到一个新的 TiDB 集群的工具。 - -注意用 TiDB Lightning 导入数据到 TiDB 的时候，有两种模式： - -- 默认模式：`tikv-importer` 为后端，这种模式下导入数据过程中集群无法提供正常的服务，用于导入大量的数据（TB 级别）。 -- 第二种模式：`TiDB` 为后端（相当于 Loader 的功能），相对默认模式导入速度较慢，但是可以在线导入。 - -以下是 TiDB Lightning 的一些基本信息： - -- Lightning 的输入 - - Mydumper 输出文件 - - CSV 格式文件 -- 适用 TiDB 版本：v2.1 及以上 -- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](/v3.1/tidb-in-kubernetes/maintain/lightning.md) - -#### 备份和恢复工具 BR - -[BR](/v3.1/reference/tools/br/br.md) 是 TiDB 进行分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 Mydumper 和 Loader，BR 更适合大数据量的场景，有更高效的备份和恢复效率。 - -以下是 BR 的一些基本信息： - -- [备份输出和恢复输入的文件类型](/v3.1/reference/tools/br/br.md#备份文件类型)：SST + `backupmeta` 文件 -- 适用 TiDB 版本：v3.1 及 v4.0 -- Kubernetes 支持：已支持，文档撰写中 - -#### 增量导入工具 Syncer（已停止维护，不推荐使用） - -[Syncer](/v3.1/reference/tools/syncer.md) 是将 MySQL/MariaDB 增量 binlog 数据实时复制导入到 TiDB 的工具。目前推荐使用 [TiDB Data Migration](#增量导入工具-tidb-data-migration) 替换该工具。 - -以下是 Syncer 的一些基本信息： - -- Syncer 的输入：MySQL/MariaDB 的 binlog -- Syncer 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：不支持 - -#### 增量导入工具 TiDB Data Migration - -[TiDB Data Migration (DM)](/v3.1/reference/tools/data-migration/overview.md) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的同步。 - -以下是 DM 的一些基本信息： - -- DM 的输入：MySQL/MariaDB 的全量数据以及 binlog -- DM 的输出：以 SQL 形式写入 TiDB -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：开发中 - -### 数据导出类 - -#### 全量导出工具 Mydumper - -[Mydumper](/v3.1/reference/tools/mydumper.md) 用于对 MySQL/TiDB 进行全量逻辑备份。 - -以下是 Mydumper 的一些基本信息： - -- Mydumper 的输入：MySQL/TiDB 集群 -- Mydumper 的输出：SQL 文件 -- 适用 TiDB 版本：所有版本 -- Kubernetes 支持：[备份与恢复](/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md) - -#### 增量导出工具 TiDB Binlog - -[TiDB Binlog](/v3.1/reference/tidb-binlog/overview.md) 是收集 TiDB 的 binlog，并提供准实时同步和备份的工具。 - -以下是 TiDB Binlog 的一些基本信息： - -- TiDB Binlog 的输入：TiDB 集群 -- TiDB Binlog 的输出：MySQL、TiDB、Kafka 或者增量备份文件 -- 适用 TiDB 版本：v2.1 及以上 -- Kubernetes 支持：[TiDB Binlog 运维文档](/v3.1/tidb-in-kubernetes/maintain/tidb-binlog.md)，[Kubernetes 上的 TiDB Binlog Drainer 配置](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - -## 工具演进路线 - -下面简单的介绍一下 TiDB 生态工具集的演进，方便大家了解工具之间的关系。 - -### TiDB 备份与恢复 - -Mydumper、Loader -> BR： - -Mydumper 和 Loader 都是在逻辑层面进行备份和恢复，效率较低；BR 使用 TiDB 的特性进行备份和恢复，适合数据量比较大的场景，备份效率大大提升。 - -### TiDB 全量恢复 - -Loader -> TiDB Lightning： - -Loader 使用 SQL 的方式进行全量数据恢复，效率较低。TiDB Lightning 将数据直接导入 TiKV，大大提升了全量数据恢复的效率，适合将大量数据（TB 级别以上数据）快速导入到一个全新的 TiDB 集群中；且 TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/v3.1/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，支持在线导入数据。 - -### MySQL 数据迁移 - -- Mydumper、Loader、Syncer -> DM： - - 使用 Mydumper、Loader、Syncer 将 MySQL 数据迁移到 TiDB，迁移过程比较繁琐。DM 提供了一体化的数据迁移方案，提高了易用性，而且 DM 还支持分库分表的合并。 - -- Loader -> TiDB Lightning： - - TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/v3.1/reference/tools/tidb-lightning/tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，由 TiDB Lightning 统一提供全量数据恢复功能。 - -## 数据迁移解决方案 - -针对 TiDB 的 2.1，3.0 以及 3.1 版本，下面给出典型业务场景下的数据迁移方案。 - -### TiDB 3.0 全链路数据迁移方案 - -#### MySQL 数据迁移到 TiDB - -如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： - -1. 使用 Mydumper 导出 MySQL 全量数据 -2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 -3. 使用 DM 同步 MySQL 增量数据到 TiDB - -如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 - -#### TiDB 集群数据的同步 - -使用 TiDB Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 - -#### TiDB 集群数据的全量备份及恢复 - -推荐步骤： - -1. 使用 Mydumper 进行全量数据的备份 -2. 使用 TiDB Lightning 将全量数据恢复到 TiDB/MySQL - -### TiDB 3.1 全链路数据迁移方案 - -#### MySQL 数据迁移到 TiDB - -如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下： - -1. 使用 Mydumper 导出 MySQL 全量数据 -2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群 -3. 使用 DM 同步 MySQL 增量数据到 TiDB - -如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。 - -#### TiDB 集群数据的同步 - -使用 TiDB-Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。 - -#### TiDB 集群数据的全量备份及恢复 - -- 恢复到 TiDB - - - 使用 BR 进行全量数据的备份 - - 使用 BR 进行全量数据的恢复 - -- 恢复到 MySQL - - - 使用 Mydumper 进行全量数据的备份 - - 使用 TiDB Lightning 进行全量数据的恢复 diff --git a/v3.1/reference/transactions/overview.md b/v3.1/reference/transactions/overview.md deleted file mode 100644 index a3775339ba58..000000000000 --- a/v3.1/reference/transactions/overview.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB 事务概览 -summary: 了解 TiDB 中的事务。 -category: reference ---- - -# TiDB 事务概览 - -TiDB 支持完整的分布式事务，提供[乐观事务](/v3.1/reference/transactions/transaction-optimistic.md)与[悲观事务](/v3.1/reference/transactions/transaction-pessimistic.md)（TiDB 3.0 中引入）两种事务模型。本文主要介绍涉及到事务的语句、显式/隐式事务、事务的隔离级别和惰性检查，以及事务大小的限制。 - -常用的变量包括 [`autocommit`](#自动提交)、[`tidb_disable_txn_auto_retry`](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_disable_txn_auto_retry) 以及 [`tidb_retry_limit`](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_retry_limit)。 - -## 常用事务语句 - -### `BEGIN` 和 `START TRANSACTION` - -语法： - -{{< copyable "sql" >}} - -```sql -BEGIN; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -``` - -{{< copyable "sql" >}} - -```sql -START TRANSACTION WITH CONSISTENT SNAPSHOT; -``` - -以上三条语句都用于开启事务，效果相同。执行开启事务语句可以显式地开启一个新的事务。如果执行以上语句时，当前 Session 正处于一个事务的中间过程，那么系统会先自动提交当前事务，再开启一个新的事务。 - -### `COMMIT` - -语法： - -{{< copyable "sql" >}} - -```sql -COMMIT; -``` - -该语句用于提交当前的事务，包括从 `[BEGIN|START TRANSACTION]` 到 `COMMIT` 之间的所有修改。 - -### `ROLLBACK` - -语法： - -{{< copyable "sql" >}} - -```sql -ROLLBACK; -``` - -该语句用于回滚当前事务，撤销从 `[BEGIN|START TRANSACTION]` 到 `ROLLBACK` 之间的所有修改。 - -## 自动提交 - -语法： - -{{< copyable "sql" >}} - -```sql -SET autocommit = {0 | 1} -``` - -当 `autocommit = 1` 时（默认），当前的 Session 为自动提交状态，即每条语句运行后，TiDB 会自动将修改提交到数据库中。设置 `autocommit = 0` 时更改当前 Session 更改为非自动提交状态，通过执行 `COMMIT` 语句来手动提交事务。 - -> **注意：** -> -> 某些语句执行后会导致隐式提交。例如，执行 `[BEGIN|START TRANCATION]` 语句时，TiDB 会试图提交上一个事务，并开启一个新的事务。详情参见 [implicit commit](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html)。 - -另外，`autocommit` 也是一个系统变量，你可以通过变量赋值语句修改当前 Session 或 Global 的值。 - -{{< copyable "sql" >}} - -```sql -SET @@SESSION.autocommit = {0 | 1}; -``` - -{{< copyable "sql" >}} - -```sql -SET @@GLOBAL.autocommit = {0 | 1}; -``` - -## 显式事务和隐式事务 - -TiDB 可以显式地使用事务（通过 `[BEGIN|START TRANSACTION]`/`COMMIT` 语句定义事务的开始和结束) 或者隐式地使用事务 (`SET autocommit = 1`)。 - -在自动提交状态下，使用 `[BEGIN|START TRANSACTION]` 语句会显式地开启一个事务，同时也会禁用自动提交，使隐式事务变成显式事务。直到执行 `COMMIT` 或 `ROLLBACK` 语句时才会恢复到此前默认的自动提交状态。 - -对于 DDL 语句，会自动提交并且不能回滚。如果运行 DDL 的时候，正在一个事务的中间过程中，会先自动提交当前事务，再执行 DDL。 - -## 事务隔离级别 - -TiDB **只支持** `SNAPSHOT ISOLATION`，可以通过下面的语句将当前 Session 的隔离级别设置为 `READ COMMITTED`，这只是语法上的兼容，事务依旧是以 `SNAPSHOT ISOLATION` 来执行。 - -{{< copyable "sql" >}} - -```sql -SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; -``` - -## 惰性检查 - -TiDB 中，对于普通的 `INSERT` 语句写入的值，会进行惰性检查。惰性检查的含义是，不在 `INSERT` 语句执行时进行唯一约束的检查，而在事务提交时进行唯一约束的检查。 - -举例： - -{{< copyable "sql" >}} - -```sql -CREATE TABLE T (I INT KEY); -INSERT INTO T VALUES (1); -BEGIN; -INSERT INTO T VALUES (1); -- MySQL 返回错误；TiDB 返回成功 -INSERT INTO T VALUES (2); -COMMIT; -- MySQL 提交成功；TiDB 返回错误，事务回滚 -SELECT * FROM T; -- MySQL 返回 1 2；TiDB 返回 1 -``` - -惰性检查的意义在于，如果对事务中每个 `INSERT` 语句都立刻进行唯一性约束检查，将造成很高的网络开销。而在提交时进行一次批量检查，将会大幅提升性能。 - -> **注意：** -> -> 本优化仅对普通的 `INSERT` 语句生效，对 `INSERT IGNORE` 和 `INSERT ON DUPLICATE KEY UPDATE` 不会生效。 - -## 语句回滚 - -TiDB 支持语句执行的原子性回滚。在事务内部执行一个语句，遇到错误时，该语句整体不会生效。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -commit; -``` - -上面的例子里面，第二条语句执行失败，但第一和第三条语句仍然能正常提交。 - -{{< copyable "sql" >}} - -```sql -begin; -insert into test values (1); -insert into tset values (2); -- tset 拼写错误，使该语句执行出错。 -insert into test values (3); -rollback; -``` - -以上例子中，第二条语句执行失败。由于调用了 `ROLLBACK`，因此事务不会将任何数据写入数据库。 - -## 事务大小 - -对于 TiDB 事务而言，事务太大或太小，都会影响事务的执行效率。 - -### 小事务 - -以如下 query 为例，当 `autocommit = 1` 时，下面三条语句各为一个事务： - -{{< copyable "sql" >}} - -```sql -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -``` - -此时每一条语句都需要经过两阶段提交，频繁的网络交互致使延迟率高。为提升事务执行效率，可以选择使用显式事务，即在一个事务内执行三条语句。 - -优化后版本： - -{{< copyable "sql" >}} - -```sql -START TRANSACTION; -UPDATE my_table SET a ='new_value' WHERE id = 1; -UPDATE my_table SET a ='newer_value' WHERE id = 2; -UPDATE my_table SET a ='newest_value' WHERE id = 3; -COMMIT; -``` - -同理，执行 `INSERT` 语句时，建议使用显式事务。 - -> **注意：** -> -> 由于 TiDB 中的资源是分布式的，TiDB 中单线程 workload 可能不会很好地利用分布式资源，因此性能相比于单实例部署的 MySQL 较低。这与 TiDB 中的事务延迟较高的情況类似。 - -### 大事务 - -由于 TiDB 两阶段提交的要求，修改数据的单个事务过大时会存在以下问题： - -* 客户端在提交之前，数据都写在内存中，而数据量过多时易导致 OOM (Out of Memory) 错误。 -* 在第一阶段写入数据耗时增加，与其他事务出现写冲突的概率会指数级增长。 -* 最终导致事务完成提交的耗时增加。 - -因此，TiDB 对事务做了一些限制： - -* 单个事务包含的 SQL 语句不超过 5000 条（默认） -* 每个键值对不超过 6 MB -* 键值对的总数不超过 300000 -* 键值对的总大小不超过 100 MB - -为了使性能达到最优，建议每 100～500 行写入一个事务。 \ No newline at end of file diff --git a/v3.1/reference/transactions/transaction-isolation.md b/v3.1/reference/transactions/transaction-isolation.md deleted file mode 100644 index 4530591f1eb4..000000000000 --- a/v3.1/reference/transactions/transaction-isolation.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 事务隔离级别 -summary: 了解 TiDB 事务的隔离级别。 -category: reference ---- - -# TiDB 事务隔离级别 - -事务隔离级别是数据库事务处理的基础，[ACID](/v3.1/glossary.md#acid) 中的 “I”，即 Isolation，指的就是事务的隔离性。 - -SQL-92 标准定义了 4 种隔离级别：读未提交 (READ UNCOMMITTED)、读已提交 (READ COMMITTED)、可重复读 (REPEATABLE READ)、串行化 (SERIALIZABLE)。详见下表： - -| Isolation Level | Dirty Write | Dirty Read | Fuzzy Read | Phantom | -| ---------------- | ------------ | ------------ | ------------ | ------------ | -| READ UNCOMMITTED | Not Possible | Possible | Possible | Possible | -| READ COMMITTED | Not Possible | Not possible | Possible | Possible | -| REPEATABLE READ | Not Possible | Not possible | Not possible | Possible | -| SERIALIZABLE | Not Possible | Not possible | Not possible | Not possible | - -TiDB 实现了快照隔离 (Snapshot Isolation, SI) 级别的一致性。为与 MySQL 保持一致，又称其为“可重复读”。该隔离级别不同于 [ANSI 可重复读隔离级别](#与-ansi-可重复读隔离级别的区别)和 [MySQL 可重复读隔离级别](#与-mysql-可重复读隔离级别的区别)。 - -> **注意：** -> -> 在 TiDB v3.0 中，事务的自动重试功能默认为禁用状态。关于该项功能对隔离级别的影响以及如何开启该项功能，请参考[事务重试](/v3.1/reference/transactions/transaction-optimistic.md#重试机制)。 - -## 可重复读 - -当事务隔离级别为可重复读时，只能读到该事务启动时已经提交的其他事务修改的数据，未提交的数据或在事务启动后其他事务提交的数据是不可见的。对于本事务而言，事务语句可以看到之前的语句做出的修改。 - -对于运行于不同节点的事务而言，不同事务启动和提交的顺序取决于从 PD 获取时间戳的顺序。 - -处于可重复读隔离级别的事务不能并发的更新同一行，当时事务提交时发现该行在该事务启动后，已经被另一个已提交的事务更新过，那么该事务会回滚并启动自动重试。示例如下： - -```sql -create table t1(id int); -insert into t1 values(0); - -start transaction; | start transaction; -select * from t1; | select * from t1; -update t1 set id=id+1; | update t1 set id=id+1; -commit; | - | commit; -- 事务提交失败，回滚 -``` - -### 与 ANSI 可重复读隔离级别的区别 - -尽管名称是可重复读隔离级别，但是 TiDB 中可重复读隔离级别和 ANSI 可重复隔离级别是不同的。按照 [A Critique of ANSI SQL Isolation Levels](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf) 论文中的标准，TiDB 实现的是论文中的快照隔离级别。该隔离级别不会出现狭义上的幻读 (A3)，但不会阻止广义上的幻读 (P3)，同时，SI 还会出现写偏斜，而 ANSI 可重复读隔离级别不会出现写偏斜，会出现幻读。 - -### 与 MySQL 可重复读隔离级别的区别 - -MySQL 可重复读隔离级别在更新时并不检验当前版本是否可见，也就是说，即使该行在事务启动后被更新过，同样可以继续更新。这种情况在 TiDB 会导致事务回滚，导致事务最终失败，而 MySQL 是可以更新成功的。MySQL 的可重复读隔离级别并非快照隔离级别，MySQL 可重复读隔离级别的一致性要弱于快照隔离级别，也弱于 TiDB 的可重复读隔离级别。 - -## 更多阅读 - -- [TiKV 的 MVCC (Multi-Version Concurrency Control) 机制](https://pingcap.com/blog-cn/mvcc-in-tikv/) \ No newline at end of file diff --git a/v3.1/reference/transactions/transaction-optimistic.md b/v3.1/reference/transactions/transaction-optimistic.md deleted file mode 100644 index d84194c481ce..000000000000 --- a/v3.1/reference/transactions/transaction-optimistic.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: TiDB 乐观事务模型 -summary: 了解 TiDB 的乐观事务模型。 -category: reference -aliases: ['/docs-cn/v3.1/reference/transactions/transaction-model/'] ---- - -# TiDB 乐观事务模型 - -本文介绍 TiDB 乐观事务的原理，以及相关特性。本文假定你对 [TiDB 的整体架构](/v3.1/architecture.md#tidb-整体架构)、[Percolator](https://www.usenix.org/legacy/event/osdi10/tech/full_papers/Peng.pdf) 事务模型以及事务的 [ACID 特性](/v3.1/glossary.md#acid)都有一定了解。 - -TiDB 默认使用乐观事务模型，不会出现读写冲突，所有的读操作都不会被写操作阻塞。对于写写冲突，只有在客户端执行 `COMMIT` 时，才会触发两阶段提交并检测是否存在写写冲突。 - -> **注意：** -> -> 自 v3.0.8 开始，TiDB 默认使用[悲观事务模型](/v3.1/reference/transactions/transaction-pessimistic.md)。但如果从 3.0.7 及之前的版本升级到 >= 3.0.8 的版本，不会改变默认事务模型，即**只有新创建的集群才会默认使用悲观事务模型**。 - -## 乐观事务原理 - -TiDB 中事务使用两阶段提交，流程如下： - -![TiDB 中的两阶段提交](/media/2pc-in-tidb.png) - -1. 客户端开始一个事务。 - - TiDB 从 PD 获取一个全局唯一递增的版本号作为当前事务的开始版本号，这里定义为该事务的 `start_ts` 版本。 - -2. 客户端发起读请求。 - - 1. TiDB 从 PD 获取数据路由信息，即数据具体存在哪个 TiKV 节点上。 - 2. TiDB 从 TiKV 获取 `start_ts` 版本下对应的数据信息。 - -3. 客户端发起写请求。 - - TiDB 校验写入数据是否符合一致性约束（如数据类型是否正确、是否符合唯一索引约束等）。**校验通过的数据将存放在内存里。** - -4. 客户端发起 commit。 - -5. TiDB 开始两阶段提交，保证分布式事务的原子性，让数据真正落盘。 - - 1. TiDB 从当前要写入的数据中选择一个 Key 作为当前事务的 Primary Key。 - 2. TiDB 从 PD 获取所有数据的写入路由信息，并将所有的 Key 按照所有的路由进行分类。 - 3. TiDB 并发地向所有涉及的 TiKV 发起 prewrite 请求。TiKV 收到 prewrite 数据后，检查数据版本信息是否存在冲突或已过期。符合条件的数据会被加锁。 - 4. TiDB 收到所有 prewrite 响应且所有 prewrite 都成功。 - 5. TiDB 向 PD 获取第二个全局唯一递增版本号，定义为本次事务的 `commit_ts`。 - 6. TiDB 向 Primary Key 所在 TiKV 发起第二阶段提交。TiKV 收到 commit 操作后，检查数据合法性，清理 prewrite 阶段留下的锁。 - 7. TiDB 收到两阶段提交成功的信息。 - -6. TiDB 向客户端返回事务提交成功的信息。 - -7. TiDB 异步清理本次事务遗留的锁信息。 - -## 优缺点分析 - -通过分析 TiDB 中事务的处理流程，可以发现 TiDB 事务有如下优点： - -* 实现原理简单，易于理解。 -* 基于单实例事务实现了跨节点事务。 -* 锁管理实现了去中心化。 - -但 TiDB 事务也存在以下缺点： - -* 两阶段提交使网络交互增多。 -* 需要一个中心化的版本管理服务。 -* 事务数据量过大时易导致内存暴涨。 - -实际应用中，你可以[根据事务的大小进行针对性处理](/v3.1/reference/transactions/overview.md#事务大小)，以提高事务的执行效率。 - -## 事务的重试 - -使用乐观事务模型时，在高冲突率的场景中，事务很容易提交失败。而 MySQL 内部使用的是悲观事务模型，在执行 SQL 语句的过程中进行冲突检测，所以提交时很难出现异常。为了兼容 MySQL 的悲观事务行为，TiDB 提供了重试机制。 - -### 重试机制 - -当事务提交后，如果发现冲突，TiDB 内部重新执行包含写操作的 SQL 语句。你可以通过设置 `tidb_disable_txn_auto_retry = off` 开启自动重试，并通过 `tidb_retry_limit` 设置重试次数： - -```sql -# 设置是否禁用自动重试，默认为 “on”，即不重试。 -tidb_disable_txn_auto_retry = off -# 控制重试次数，默认为 “10”。只有自动重试启用时该参数才会生效。 -# 当 “tidb_retry_limit= 0” 时，也会禁用自动重试。 -tidb_retry_limit = 10 -``` - -你也可以修改当前 Session 或 Global 的值： - -- Session 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@tidb_retry_limit = 10; - ``` - -- Global 级别设置： - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_disable_txn_auto_retry = off; - ``` - - {{< copyable "sql" >}} - - ```sql - set @@global.tidb_retry_limit = 10; - ``` - -> **注意：** -> -> `tidb_retry_limit` 变量决定了事务重试的最大次数。当它被设置为 0 时，所有事务都不会自动重试，包括自动提交的单语句隐式事务。这是彻底禁用 TiDB 中自动重试机制的方法。禁用自动重试后，所有冲突的事务都会以最快的方式上报失败信息 (`try again later`) 给应用层。 - -### 重试的局限性 - -TiDB 默认不进行事务重试，因为重试事务可能会导致更新丢失，从而破坏[可重复读的隔离级别](/v3.1/reference/transactions/transaction-isolation.md)。 - -事务重试的局限性与其原理有关。事务重试可概括为以下三个步骤： - -1. 重新获取 `start_ts`。 -2. 重新执行包含写操作的 SQL 语句。 -3. 再次进行两阶段提交。 - -第二步中，重试时仅重新执行包含写操作的 SQL 语句，并不涉及读操作的 SQL 语句。但是当前事务中读到数据的时间与事务真正开始的时间发生了变化，写入的版本变成了重试时获取的 `start_ts` 而非事务一开始时获取的 `start_ts`。因此，当事务中存在依赖查询结果来更新的语句时，重试将无法保证事务原本可重复读的隔离级别，最终可能导致结果与预期出现不一致。 - -如果业务可以容忍事务重试导致的异常，或并不关注事务是否以可重复读的隔离级别来执行，则可以开启自动重试。 - -## 冲突检测 - -乐观事务下，检测底层数据是否存在写写冲突是一个很重要的操作。具体而言，TiKV 在 prewrite 阶段就需要读取数据进行检测。为了优化这一块性能，TiDB 集群会在内存里面进行一次冲突预检测。 - -作为一个分布式系统，TiDB 在内存中的冲突检测主要在两个模块进行： - -- TiDB 层。如果发现 TiDB 实例本身就存在写写冲突，那么第一个写入发出后，后面的写入已经清楚地知道自己冲突了，无需再往下层 TiKV 发送请求去检测冲突。 -- TiKV 层。主要发生在 prewrite 阶段。因为 TiDB 集群是一个分布式系统，TiDB 实例本身无状态，实例之间无法感知到彼此的存在，也就无法确认自己的写入与别的 TiDB 实例是否存在冲突，所以会在 TiKV 这一层检测具体的数据是否有冲突。 - -其中 TiDB 层的冲突检测可以根据场景需要选择打开或关闭，具体配置项如下： - -```toml -# 事务内存锁相关配置，当本地事务冲突比较多时建议开启。 -[txn-local-latches] -# 是否开启内存锁，默认为 false，即不开启。 -enabled = false -# Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。 -# 每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据）， -# 设置过小会导致变慢，性能下降。（默认为 2048000） -capacity = 2048000 -``` - -配置项 `capacity` 主要影响到冲突判断的正确性。在实现冲突检测时，不可能把所有的 Key 都存到内存里，所以真正存下来的是每个 Key 的 Hash 值。有 Hash 算法就有碰撞也就是误判的概率，这里可以通过配置 `capacity` 来控制 Hash 取模的值： - -* `capacity` 值越小，占用内存小，误判概率越大。 -* `capacity` 值越大，占用内存大，误判概率越小。 - -实际应用时，如果业务场景能够预判断写入不存在冲突（如导入数据操作），建议关闭冲突检测。 - -相应地，在 TiKV 层检测内存中是否存在冲突也有类似的机制。不同的是，TiKV 层的检测会更严格且不允许关闭，仅支持对 Hash 取模值进行配置： - -```toml -# scheduler 内置一个内存锁机制，防止同时对一个 Key 进行操作。 -# 每个 Key hash 到不同的 slot。（默认为 2048000） -scheduler-concurrency = 2048000 -``` - -此外，TiKV 支持监控等待 latch 的时间： - -![Scheduler latch wait duration](/media/optimistic-transaction-metric.png) - -当 `Scheduler latch wait duration` 的值特别高时，说明大量时间消耗在等待锁的请求上。如果不存在底层写入慢的问题，基本上可以判断该段时间内冲突比较多。 - -## 更多阅读 - -- [Percolator 和 TiDB 事务算法](https://pingcap.com/blog-cn/percolator-and-txn/) \ No newline at end of file diff --git a/v3.1/reference/transactions/transaction-pessimistic.md b/v3.1/reference/transactions/transaction-pessimistic.md deleted file mode 100644 index 5dd3cb24ff2c..000000000000 --- a/v3.1/reference/transactions/transaction-pessimistic.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: TiDB 悲观事务模型 -summary: 了解 TiDB 的悲观事务模型。 -category: reference ---- - -# TiDB 悲观事务模型 - -在 v3.0.8 之前，TiDB 默认使用的乐观事务模式会导致事务提交时因为冲突而失败。为了保证事务的成功率，需要修改应用程序，加上重试的逻辑。悲观事务模式可以避免这个问题，应用程序无需添加重试逻辑，就可以正常执行。 - -## 悲观事务的使用方法 - -进入悲观事务模式有以下三种方式: - -- 执行 `BEGIN PESSIMISTIC;` 语句开启的事务，会进入悲观事务模式。 -可以通过写成注释的形式 `BEGIN /*!90000 PESSIMISTIC */;` 来兼容 MySQL 语法。 - -- 执行 `set @@tidb_txn_mode = 'pessimistic';`，使这个 session 执行的所有显式事务（即非 autocommit 的事务）都会进入悲观事务模式。 - -- 执行 `set @@global.tidb_txn_mode = 'pessimistic';`，使之后整个集群所有新创建 session 执行的所有显示事务（即非 autocommit 的事务）都会进入悲观事务模式。 - -在配置了 `global.tidb_txn_mode` 为 `pessimistic` 之后，默认进入悲观事务模式，但是可以用以下三种方式使事务进入乐观事务模式： - -- 执行 `BEGIN OPTIMISTIC;` 语句开启的事务，会进入乐观事务模式。 -可以通过写成注释的形式 `BEGIN /*!90000 OPTIMISTIC */;` 来兼容 MySQL 语法。 - -- 执行 `set @@tidb_txn_mode = 'optimistic';` 或 `set @@tidb_txn_mode = '';`，使当前的 session 执行的事务进入乐观事务模式。 - -- 执行 `set @@global.tidb_txn_mode = 'optimistic;'` 或 `set @@global.tidb_txn_mode = '';`，使之后整个集群所有新创建 session 执行的事务都进入乐观事务模式。 - -`BEGIN PESSIMISTIC;` 和 `BEGIN OPTIMISTIC;` 语句的优先级高于 `tidb_txn_mode` 系统变量。使用这两个语句开启的事务，会忽略系统变量，从而支持悲观、乐观事务混合使用。 - -如果想要禁用悲观事务特性，可以修改 TiDB 配置文件，在 `[pessimistic-txn]` 类别下添加 `enable = false`。 - -## 悲观事务模式的行为 - -悲观事务的行为和 MySQL 基本一致（不一致之处详见[和 MySQL InnoDB 的差异](#和-mysql-innodb-的差异)）： - -- `SELECT FOR UPDATE` 会读取已提交的最新数据，并对读取到的数据加悲观锁。 - -- `UPDATE`、`DELETE` 和 `INSERT` 语句都会读取已提交的最新的数据来执行，并对修改的数据加悲观锁。 - -- 当一行数据被加了悲观锁以后，其他尝试修改这一行的写事务会被阻塞，等待悲观锁的释放。 - -- 当一行数据被加了悲观锁以后，其他尝试读取这一行的事务不会被阻塞，可以读到已提交的数据。 - -- 事务提交或回滚的时候，会释放所有的锁。 - -- 当有多个事务同时等待同一个锁释放时，会尽可能按照事务 start ts 顺序获取锁，但不能严格保证。 - -- 如果并发事务出现死锁，会被死锁检测器检测到，随机终止掉其中一个事务并返回兼容 MySQL 的错误码 `1213`。 - -- 乐观事务和悲观事务可以共存，事务可以任意指定使用乐观模式或悲观模式来执行。 - -- 通过设置 `innodb_wait_timeout` 变量，设置等锁超时时间，等锁超时后返回兼容 MySQL 的错误码 `1205`。 - -## 和 MySQL InnoDB 的差异 - -1. TiDB 使用 range 作为 WHERE 条件，执行 DML 和 `SELECT FOR UPDATE` 语句时不会阻塞范围内并发的 `INSERT` 语句的执行。 - - InnoDB 通过实现 gap lock，支持阻塞 range 内并发的 `INSERT` 语句的执行，其主要目的是为了支持 statement based binlog，因此有些业务会通过将隔离级别降低至 READ COMMITTED 来避免 gap lock 导致的并发性能问题。TiDB 不支持 gap lock，也就不需要付出相应的并发性能的代价。 - -2. TiDB 不支持 `SELECT LOCK IN SHARE MODE`。 - - 使用这个语句执行的时候，效果和没有加锁是一样的，不会阻塞其他事务的读写。 - -3. DDL 可能会导致悲观事务提交失败。 - - MySQL 在执行 DDL 时会被正在执行的事务阻塞住，而在 TiDB 中 DDL 操作会成功，造成悲观事务提交失败：`ERROR 1105 (HY000): Information schema is changed. [try again later]`。 - -4. `START TRANSACTION WITH CONSISTENT SNAPSHOT` 之后，MySQL 仍然可以读取到之后在其他事务创建的表，而 TiDB 不能。 - -5. autocommit 事务不支持悲观锁 - - 所有自动提交的语句都不会加悲观锁，该类语句在用户侧感知不到区别，因为悲观事务的本质是把整个事务的重试变成了单个 DML 的重试，autocommit 事务即使在 TiDB 关闭重试时也会自动重试，效果和悲观事务相同。 - - 自动提交的 select for update 语句也不会等锁。 - -## 常见问题 - -1. TiDB 日志出现 `pessimistic write conflict, retry statement`。 - - 当发生 write conflict 时，乐观事务会直接终止，而悲观事务会尝试用最新数据重试该语句直到没有 write conflict，每次重试都会打印该 log，不用特别关注。 - -2. 执行 DML 时报错 `pessimistic lock retry limit reached`。 - - 悲观事务每个语句有重试次数限制，当因 write conflict 重试超过该限制时会报该错误，默认为 256 次，可通过 TiDB 配置文件 `[pessimistic-txn]` 类别下的 `max-retry-limit` 修改。 - -3. 悲观事务执行时间限制。 - - 除了有事务执行时间不能超出 `tikv_gc_life_time` 的限制外，悲观事务的 TTL 有 10 分钟上限，所以执行时间超过 10 分钟的悲观事务有可能提交失败。 diff --git a/v3.1/releases/11alpha.md b/v3.1/releases/11alpha.md deleted file mode 100644 index e7d5f179b235..000000000000 --- a/v3.1/releases/11alpha.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB 1.1 Alpha Release Notes -category: Releases ---- - -# TiDB 1.1 Alpha Release Notes - -2018 年 1 月 19 日，TiDB 发布 1.1 Alpha 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -- SQL parser - - 兼容更多语法 -- SQL 查询优化器 - - 统计信息减小内存占用 - - 优化统计信息启动时载入的时间 - - 更精确的代价估算 - - 使用 `Count-Min Sketch` 更精确地估算点查的代价 - - 支持更复杂的条件，更充分使用索引 -- SQL 执行器 - - 使用 Chunk 结构重构所有执行器算子，提升分析型语句执行性能，减少内存占用 - - 优化 `INSERT IGNORE` 语句性能 - - 下推更多的类型和函数 - - 支持更多的 `SQL_MODE` - - 优化 `Load Data` 性能，速度提升 10 倍 - - 优化 `Use Database` 性能 - - 支持对物理算子内存使用进行统计 -- Server - - 支持 PROXY protocol - -## PD - -- 增加更多的 API -- 支持 TLS -- 给 Simulator 增加更多的 case -- 调度适应不同的 Region size -- Fix 了一些调度的 bug - -## TiKV - -- 支持 Raft learner -- 优化 Raft Snapshot，减少 I/O 开销 -- 支持 TLS -- 优化 RocksDB 配置，提升性能 -- 优化 Coprocessor `count (*)` 和点查 unique index 的性能 -- 增加更多的 Failpoint 以及稳定性测试 case -- 解决 PD 和 TiKV 之间重连的问题 -- 增强数据恢复工具 `tikv-ctl` 的功能 -- Region 支持按 table 进行分裂 -- 支持 `Delete Range` 功能 -- 支持设置 snapshot 导致的 I/O 上限 -- 完善流控机制 diff --git a/v3.1/releases/11beta.md b/v3.1/releases/11beta.md deleted file mode 100644 index be72f038e76f..000000000000 --- a/v3.1/releases/11beta.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB 1.1 Beta Release Notes -category: Releases ---- - -# TiDB 1.1 Beta Release Notes - -2018 年 2 月 24 日，TiDB 发布 1.1 Beta 版。该版本在 1.1 Alpha 版的基础上，对 MySQL 兼容性、系统稳定性做了很多改进。 - -## TiDB - -+ 添加更多监控项, 优化日志 -+ 兼容更多 MySQL 语法 -+ 在 `information_schema` 中支持显示建表时间 -+ 提速包含 `MaxOneRow` 算子的查询 -+ 控制 Join 产生的中间结果集大小，进一步减少 Join 的内存使用 -+ 增加 `tidb_config` session 变量，输出当前 TiDB 配置 -+ 修复 `Union` 和 `Index Join` 算子中遇到的 panic 问题 -+ 修复 `Sort Merge Join` 算子在部分场景下结果错误的问题 -+ 修复 `Show Index` 语句显示正在添加过程中的索引的问题 -+ 修复 `Drop Stats` 语句失败的问题 -+ 优化 SQL 引擎查询性能，Sysbench 的 Select/OLTP 测试结果提升 10% -+ 使用新的执行引擎提升优化器中的子查询计算速度；相比 1.0 版本，在 TPC-H 以及 TPC-DS 等测试中有显著提升 - -## PD - -+ 增加 Drop Region 调试接口 -+ 支持设置 PD leader 优先级 -+ 支持配置特定 label 的节点不调度 Raft leader -+ 增加枚举各个 PD health 状态的接口 -+ 添加更多 metrics -+ PD leader 尽量与 etcd leader 保持同步 -+ 提高 TiKV 宕机时数据恢复优先级和恢复速度 -+ 完善 `data-dir` 配置项的合法性较验 -+ 优化 Region heartbeat 性能 -+ 修复热点调度破坏 label 约束的问题 -+ 其他稳定性问题修复 - -## TiKV - -+ 使用 offset + limit 遍历 lock，消除潜在的 GC 问题 -+ 支持批量 resolve lock，提升 GC 速度 -+ 支持并行 GC，提升 GC 速度 -+ 使用 RocksDB compaction listener 更新 Region Size，让 PD 更精确的进行调度 -+ 使用 `DeleteFilesInRanges` 批量删除过期数据，提高 TiKV 启动速度 -+ 设置 Raft snapshot max size，防止遗留文件占用太多空间 -+ `tikv-ctl` 支持更多修复操作 -+ 优化有序流式聚合操作 -+ 完善 metrics，修复 bug \ No newline at end of file diff --git a/v3.1/releases/2.0.10.md b/v3.1/releases/2.0.10.md deleted file mode 100644 index 4eced6e55285..000000000000 --- a/v3.1/releases/2.0.10.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.0.10 Release Notes -category: Releases ---- - -# TiDB 2.0.10 Release Notes - -2018 年 12 月 18 日，TiDB 发布 2.0.10 版，TiDB Ansible 相应发布 2.0.10 版本。该版本在 2.0.9 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复取消 DDL 任务的时候可能导致的问题 [#8513](https://github.com/pingcap/tidb/pull/8513) -- 修复 `ORDER BY`，`UNION` 语句无法引用带表名的列的问题 [#8514](https://github.com/pingcap/tidb/pull/8514) -- 修复 `UNCOMPRESS` 函数没有判断错误输入长度的问题 [#8607](https://github.com/pingcap/tidb/pull/8607) -- 修复 `ANSI_QUOTES SQL_MODE` 在 TiDB 升级的时候遇到的问题 [#8575](https://github.com/pingcap/tidb/pull/8575) -- 修复某些情况下 `select` 返回结果错误的问题 [#8570](https://github.com/pingcap/tidb/pull/8570) -- 修复 TiDB 在收到退出信号的时候可能无法退出的问题 [#8501](https://github.com/pingcap/tidb/pull/8501) -- 修复某些情况下 `IndexLookUpJoin` 返回错误结果的问题 [#8508](https://github.com/pingcap/tidb/pull/8508) -- 避免下推有 `GetVar` 或 `SetVar 的 filter` [#8454](https://github.com/pingcap/tidb/pull/8454) -- 修复某些情况下 `UNION` 语句结果长度错误的问题 [#8491](https://github.com/pingcap/tidb/pull/8491) -- 修复 `PREPARE FROM @var_name` 的问题 [#8488](https://github.com/pingcap/tidb/pull/8488) -- 修复某些情况下导出统计信息 panic 的问题 [#8464](https://github.com/pingcap/tidb/pull/8464) -- 修复统计信息某些情况下对点查估算的问题 [#8493](https://github.com/pingcap/tidb/pull/8493) -- 修复某些情况下返回 Enum 默认值为字符串导致的 panic [#8476](https://github.com/pingcap/tidb/pull/8476) -- 修复在宽表场景下，占用太多内存的问题 [#8467](https://github.com/pingcap/tidb/pull/8467) -- 修复 Parser 对取模操作错误格式化导致的问题 [#8431](https://github.com/pingcap/tidb/pull/8431) -- 修复某些情况下添加外键约束导致的 panic 问题 [#8421](https://github.com/pingcap/tidb/pull/8421)，[#8410](https://github.com/pingcap/tidb/pull/8410) -- 修复 `YEAR` 类型错误转换零值的问题 [#8396](https://github.com/pingcap/tidb/pull/8396) -- 修复 `VALUES` 函数在参数不为列的时候 panic 的问题 [#8404](https://github.com/pingcap/tidb/pull/8404) -- 存在子查询的语句禁用 Plan Cache [#8395](https://github.com/pingcap/tidb/pull/8395) - -## PD - -- 修复 RaftCluster 在退出时可能的死锁问题 [#1370](https://github.com/pingcap/pd/pull/1370) - -## TiKV - -- 修复迁移 Leader 到新节点时造成请求延时问题 [#3929](https://github.com/tikv/tikv/pull/3929) -- 修复多余的 Region 心跳 [#3930](https://github.com/tikv/tikv/pull/3930) diff --git a/v3.1/releases/2.0.11.md b/v3.1/releases/2.0.11.md deleted file mode 100644 index e8e0a83aa9d1..000000000000 --- a/v3.1/releases/2.0.11.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: TiDB 2.0.11 Release Notes -category: Releases ---- - -# TiDB 2.0.11 Release Notes - -2019 年 1 月 3 日，TiDB 发布 2.0.11 版，TiDB Ansible 相应发布 2.0.11 版本。该版本在 2.0.10 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复 PD 发生异常的情况下，Error 没有被正确处理的问题 [#8764](https://github.com/pingcap/tidb/pull/8764) -- 修复 Rename 相同表的行为，跟 MySQL 保持一致 [#8809](https://github.com/pingcap/tidb/pull/8809) -- 修复 `ADMIN CHECK TABLE` 在 `ADD INDEX` 过程中误报的问题 [#8750](https://github.com/pingcap/tidb/pull/8750) -- 修复前缀索引在某些情况下，开闭范围区间错误的问题 [#8877](https://github.com/pingcap/tidb/pull/8877) -- 修复在某些添加列的情况下，`UPDATE` 语句 panic 的问题 [#8904](https://github.com/pingcap/tidb/pull/8904) - -## TiKV - -- 修复了两个 Region merge 相关的问题 -[#4003](https://github.com/tikv/tikv/pull/4003)，[#4004](https://github.com/tikv/tikv/pull/4004) \ No newline at end of file diff --git a/v3.1/releases/2.0ga.md b/v3.1/releases/2.0ga.md deleted file mode 100644 index bf90ec62748a..000000000000 --- a/v3.1/releases/2.0ga.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: TiDB 2.0 release notes -category: Releases ---- - -# TiDB 2.0 Release Notes - -2018 年 4 月 27 日，TiDB 发布 2.0 GA 版。相比 1.0 版本，该版本对 MySQL 兼容性、系统稳定性、优化器和执行器做了很多改进。 - -## TiDB - -- SQL 优化器 - - 精简统计信息数据结构，减小内存占用 - - 加快进程启动时加载统计信息速度 - - 支持统计信息动态更新 [experimental] - - 优化代价模型，对代价估算更精准 - - 使用 `Count-Min Sketch` 更精确地估算点查的代价 - - 支持分析更复杂的条件，尽可能充分的使用索引 - - 支持通过 `STRAIGHT_JOIN` 语法手动指定 Join 顺序 - - `GROUP BY`子句为空时使用 Stream Aggregation 算子，提升性能 - - 支持使用索引计算 `Max/Min` 函数 - - 优化关联子查询处理算法，支持将更多类型的关联子查询解关联并转化成 `Left Outer Join` - - 扩大 `IndexLookupJoin` 的使用范围，索引前缀匹配的场景也可以使用该算法 -- SQL 执行引擎 - - 使用 Chunk 结构重构所有执行器算子，提升分析型语句执行性能，减少内存占用，显著提升 TPC-H 结果 - - 支持 Streaming Aggregation 算子下推 - - 优化 `Insert Into Ignore` 语句性能，提升 10 倍以上 - - 优化 `Insert On Duplicate Key Update` 语句性能，提升 10 倍以上 - - 下推更多的数据类型和函数到 TiKV 计算 - - 优化 `Load Data` 性能，提升 10 倍以上 - - 支持对物理算子内存使用进行统计，通过配置文件以及系统变量指定超过阈值后的处理行为 - - 支持限制单条 SQL 语句使用内存的大小，减少程序 OOM 风险 - - 支持在 CRUD 操作中使用隐式的行 ID - - 提升点查性能 -- Server - - 支持 Proxy Protocol - - 添加大量监控项, 优化日志 - - 支持配置文件的合法性检测 - - 支持 HTTP API 获取 TiDB 参数信息 - - 使用 Batch 方式 Resolve Lock，提升垃圾回收速度 - - 支持多线程垃圾回收 - - 支持 TLS -- 兼容性 - - 支持更多 MySQL 语法 - - 支持配置文件修改 `lower_case_table_names` 系统变量，用于支持 OGG 数据同步工具 - - 提升对 Navicat 的兼容性 - - 在 `Information_Schema` 中支持显示建表时间 - - 修复部分函数/表达式返回类型和 MySQL 不同的问题 - - 提升对 JDBC 兼容性 - - 支持更多的 `SQL_MODE` -- DDL - - 优化 `Add Index` 的执行速度，部分场景下速度大幅度提升 - - `Add Index` 操作变更为低优先级，降低对线上业务影响 - - `Admin Show DDL Jobs` 输出更详细的 DDL 任务状态信息 - - 支持 `Admin Show DDL Job Queries JobID` 查询当前正在运行的 DDL 任务的原始语句 - - 支持 `Admin Recover Index` 命令，用于灾难恢复情况下修复索引数据 - - 支持通过 `Alter` 语句修改 Table Options - -## PD - -- 增加 `Region Merge` 支持，合并数据删除后产生的空 Region [experimental] -- 增加 `Raft Learner` 支持 [experimental] -- 调度器优化 - - 调度器适应不同的 Region size - - 提升 TiKV 宕机时数据恢复的优先级和恢复速度 - - 提升下线 TiKV 节点搬迁数据的速度 - - 优化 TiKV 节点空间不足时的调度策略，尽可能防止空间不足时磁盘被写满 - - 提升 balance-leader scheduler 的调度效率 - - 减少 balance-region scheduler 调度开销 - - 优化 hot-region scheduler 的执行效率 -- 运维接口及配置 - - 增加 TLS 支持 - - 支持设置 PD leader 优先级 - - 支持基于 label 配置属性 - - 支持配置特定 label 的节点不调度 Region leader - - 支持手动 Split Region，可用于处理单 Region 热点的问题 - - 支持打散指定 Region，用于某些情况下手动调整热点 Region 分布 - - 增加配置参数检查规则，完善配置项的合法性较验 -- 调试接口 - - 增加 `Drop Region` 调试接口 - - 增加枚举各个 PD health 状态的接口 -- 统计相关 - - 添加异常 Region 的统计 - - 添加 Region 隔离级别的统计 - - 添加调度相关 metrics -- 性能优化 - - PD leader 尽量与 etcd leader 保持同步，提升写入性能 - - 优化 Region heartbeat 性能，现可支持超过 100 万 Region - -## TiKV - -- 功能 - - 保护关键配置，防止错误修改 - - 支持 `Region Merge` [experimental] - - 添加 `Raw DeleteRange` API - - 添加 `GetMetric` API - - 添加 `Raw Batch Put`，`Raw Batch Get`，`Raw Batch Delete` 和 `Raw Batch Scan` - - 给 Raw KV API 增加 Column Family 参数，能对特定 Column Family 进行操作 - - Coprocessor 支持 streaming 模式，支持 streaming 聚合 - - 支持配置 Coprocessor 请求的超时时间 - - 心跳包携带时间戳 - - 支持在线修改 RocksDB 的一些参数，包括 `block-cache-size` 大小等 - - 支持配置 Coprocessor 遇到某些错误时的行为 - - 支持以导数据模式启动，减少导数据过程中的写放大 - - 支持手动对 region 进行对半 split - - 完善数据修复工具 tikv-ctl - - Coprocessor 返回更多的统计信息，以便指导 TiDB 的行为 - - 支持 ImportSST API，可以用于 SST 文件导入 [experimental] - - 新增 TiKV Importer 二进制，与 TiDB Lightning 集成用于快速导入数据 [experimental] -- 性能 - - 使用 ReadPool 优化读性能，`raw_get/get/batch_get` 提升 30% - - 提升 metrics 的性能 - - Raft snapshot 处理完之后立即通知 PD，加快调度速度 - - 解决 RocksDB 刷盘导致性能抖动问题 - - 提升在数据删除之后的空间回收 - - 加速启动过程中的垃圾清理过程 - - 使用 `DeleteFilesInRanges` 减少副本迁移时 I/O 开销 -- 稳定性 - - 解决在 PD leader 发送切换的情况下 gRPC call 不返回问题 - - 解决由于 snapshot 导致下线节点慢的问题 - - 限制搬移副本临时占用的空间大小 - - 如果有 Region 长时间没有 Leader，进行上报 - - 根据 compaction 事件及时更新统计的 Region size - - 限制单次 scan lock 请求的扫描的数据量，防止超时 - - 限制接收 snapshot 过程中的内存占用，防止 OOM - - 提升 CI test 的速度 - - 解决由于 snapshot 太多导致的 OOM 问题 - - 配置 gRPC 的 `keepalive` 参数 - - 修复 Region 增多容易 OOM 的问题 - -## TiSpark - -TiSpark 使用独立的版本号，现为 1.0 GA。TiSpark 1.0 版本组件提供了针对 TiDB 上的数据使用 Apache Spark 进行分布式计算的能力。 - -- 提供了针对 TiKV 读取的 gRPC 通信框架 -- 提供了对 TiKV 组件数据的和通信协议部分的编码解码 -- 提供了计算下推功能，包含： - - 聚合下推 - - 谓词下推 - - TopN 下推 - - Limit 下推 -- 提供了索引相关的支持 - - 谓词转化聚簇索引范围 - - 谓词转化次级索引 - - Index Only 查询优化 - - 运行时索引退化扫表优化 -- 提供了基于代价的优化 - - 统计信息支持 - - 索引选择 - - 广播表代价估算 -- 多种 Spark Interface 的支持 - - Spark Shell 支持 - - ThriftServer/JDBC 支持 - - Spark-SQL 交互支持 - - PySpark Shell 支持 - - SparkR 支持 diff --git a/v3.1/releases/2.1.1.md b/v3.1/releases/2.1.1.md deleted file mode 100644 index c4f0c6f1b339..000000000000 --- a/v3.1/releases/2.1.1.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: TiDB 2.1.1 Release Notes -category: Releases ---- - -# TiDB 2.1.1 Release Notes - -2018 年 12 月 12 日，TiDB 发布 2.1.1 版。相比 2.1.0 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复时间为负值时的四舍五入错误 [#8574](https://github.com/pingcap/tidb/pull/8574) - - 修复 `uncompress` 函数未检查数据长度的问题 [#8606](https://github.com/pingcap/tidb/pull/8606) - - 在执行 `execute` 命令后重置 `prepare` 语句绑定的变量 [#8652](https://github.com/pingcap/tidb/pull/8652) - - 支持对分区表自动收集统计信息 [#8649](https://github.com/pingcap/tidb/pull/8649) - - 修复在下推 `abs` 函数时设置错误的整数类型 [#8628](https://github.com/pingcap/tidb/pull/8628) - - 修复 JSON 列的数据竞争问题 [#8660](https://github.com/pingcap/tidb/pull/8660) -+ Server - - 修复在 PD 故障时获取错误 TSO 的问题 [#8567](https://github.com/pingcap/tidb/pull/8567) - - 修复不规范的语句导致启动失败的问题 [#8576](https://github.com/pingcap/tidb/pull/8576) - - 修复在事务重试时使用了错误的参数 [#8638](https://github.com/pingcap/tidb/pull/8638) -+ DDL - - 将表的默认字符集和排序规则改为 `utf8mb4` 和 `utf8mb4_bin` [#8590](https://github.com/pingcap/tidb/pull/8590) - - 增加变量 `ddl_reorg_batch_size` 来控制添加索引的速度 [#8614](https://github.com/pingcap/tidb/pull/8614) - - DDL 中的 character set 和 collation 选项内容不再大小写敏感 [#8611](https://github.com/pingcap/tidb/pull/8611) - - 修复对于生成列添加索引的问题 [#8655](https://github.com/pingcap/tidb/pull/8655) - -## PD - -- 修复一些配置项无法在配置文件中设置为 `0` 的问题 [#1334](https://github.com/pingcap/pd/pull/1334) -- 启动时检查未定义的配置 [#1362](https://github.com/pingcap/pd/pull/1362) -- 避免 transfer leader 至新创建的 Peer，优化可能产生的延迟增加问题 [#1339](https://github.com/pingcap/pd/pull/1339) -- 修复 RaftCluster 在退出时可能的死锁问题 [#1370](https://github.com/pingcap/pd/pull/1370) - -## TiKV - -- 避免 transfer leader 至新创建的 Peer，优化可能产生的延迟增加问题 [#3878](https://github.com/tikv/tikv/pull/3878) - -## Tools - -+ Lightning - - 优化对导入表的 `analyze` 机制，提升了导入速度 - - 支持 checkpoint 信息储存在本地文件 -+ TiDB Binlog - - 修复 pb files 输出 bug，表只有主键列则无法产生 pb event \ No newline at end of file diff --git a/v3.1/releases/2.1.10.md b/v3.1/releases/2.1.10.md deleted file mode 100644 index 907002e6486e..000000000000 --- a/v3.1/releases/2.1.10.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: TiDB 2.1.10 Release Notes -category: Releases ---- - -# TiDB 2.1.10 Release Notes - -发版日期：2019 年 5 月 22 日 - -TiDB 版本：2.1.10 - -TiDB Ansible 版本：2.1.10 - -## TiDB - -- 修复在使用 `tidb_snapshot` 读取历史数据的时候，某些异常情况导致的表结构不正确 [#10359](https://github.com/pingcap/tidb/pull/10359) -- 修复 `NOT` 函数在某些情况下导致的读取结果错误的问题 [#10363](https://github.com/pingcap/tidb/pull/10363) -- 修复 `Generated Column` 在 `Replace` 或者 `Insert on duplicate update` 语句中的错误行为 [#10385](https://github.com/pingcap/tidb/pull/10385) -- 修复 `BETWEEN` 函数在 `DATE`/`DATETIME` 类型比较的一个 bug [#10407](https://github.com/pingcap/tidb/pull/10407) -- 修复使用 `SLOW_QUERY` 表查询慢日志时，单行慢日志长度过长导致的报错 [#10412](https://github.com/pingcap/tidb/pull/10412) -- 修复某些情况下 `DATETIME` 和 `INTERVAL` 相加的结果跟 MySQL 不一致的问题 [#10416](https://github.com/pingcap/tidb/pull/10416)，[#10418](https://github.com/pingcap/tidb/pull/10418) -- 增加闰年二月的非法时间的检查 [#10417](https://github.com/pingcap/tidb/pull/10417) -- 内部的初始化操作限制只在 DDL Owner 中执行，避免了初始化集群的时候出现的大量冲突报错 [#10426](https://github.com/pingcap/tidb/pull/10426) -- 修复 `DESC` 在输出时间戳列的默认值为 `default current_timestamp on update current_timestamp` 时跟 MySQL 不兼容的问题 [#10337](https://github.com/pingcap/tidb/issues/10337) -- 修复 `Update` 语句中权限检查出错的问题 [#10439](https://github.com/pingcap/tidb/pull/10439) -- 修复 `CHAR` 类型的列在某些情况下 `RANGE` 计算错误导致的错误结果的问题 [#10455](https://github.com/pingcap/tidb/pull/10455) -- 避免 `ALTER SHARD_ROW_ID_BITS` 缩小 shard bits 位数在极低概率下，可能导致的数据错误 [#9868](https://github.com/pingcap/tidb/pull/9868) -- 修复 `ORDER BY RAND()` 不返回随机数字的问题 [#10064](https://github.com/pingcap/tidb/pull/10064) -- 禁止 `ALTER` 语句修改 DECIMAL 的精度 [#10458](https://github.com/pingcap/tidb/pull/10458) -- 修复 `TIME_FORMAT` 函数与 MySQL 的兼容问题 [#10474](https://github.com/pingcap/tidb/pull/10474) -- 检查 `PERIOD_ADD` 中参数的合法性 [#10430](https://github.com/pingcap/tidb/pull/10430) -- 修复非法的 `YEAR` 字符串在 TiDB 中的表现跟 MySQL 不兼容的问题 [#10493](https://github.com/pingcap/tidb/pull/10493) -- 支持 `ALTER DATABASE` 语法 [#10503](https://github.com/pingcap/tidb/pull/10503) -- 修复 `SLOW_QUERY` 内存表在慢语句没有 `;` 的情况下报错的问题 [#10536](https://github.com/pingcap/tidb/pull/10536) -- 修复某些情况下 `Partitioned Table` 的表 `Add index` 操作没有办法取消的问题 [#10533](https://github.com/pingcap/tidb/pull/10533) -- 修复在某些情况下无法抓住内存使用太多导致 OOM 的问题 [#10545](https://github.com/pingcap/tidb/pull/10545) -- 增强 DDL 操作改写表元信息的安全性 [#10547](https://github.com/pingcap/tidb/pull/10547) - -## PD - -- 修复 Leader 优先级不生效的问题 [#1533](https://github.com/pingcap/pd/pull/1533) - -## TiKV - -- 拒绝在最近发生过成员变更的 Region 上执行 transfer leader，防止迁移失败 [#4684](https://github.com/tikv/tikv/pull/4684) -- Coprocessor metrics 上添加 priority 标签 [#4643](https://github.com/tikv/tikv/pull/4643) -- 修复 transfer leader 中可能发生的脏读问题 [#4724](https://github.com/tikv/tikv/pull/4724) -- 修复某些情况下 `CommitMerge` 导致 TiKV 不能重启的问题 [#4615](https://github.com/tikv/tikv/pull/4615) -- 修复 unknown 的日志 [#4730](https://github.com/tikv/tikv/pull/4730) - -## Tools - -- TiDB Lightning - - 新增 TiDB Lightning 发送数据到 importer 失败时进行重试 [#176](https://github.com/pingcap/tidb-lightning/pull/176) -- TiDB Binlog - - 优化 Pump storage 组件 log，以利于排查问题 [#607](https://github.com/pingcap/tidb-binlog/pull/607) - -## TiDB Ansible - -- 更新 TiDB Lightning 配置文件，新增 `tidb_lightning_ctl` 脚本 [#d3a4a368](https://github.com/pingcap/tidb-ansible/commit/d3a4a368810a421c49980899a286cf010569b4c7) diff --git a/v3.1/releases/2.1.11.md b/v3.1/releases/2.1.11.md deleted file mode 100644 index 46abfc3b9d69..000000000000 --- a/v3.1/releases/2.1.11.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: TiDB 2.1.11 Release Notes -category: Releases ---- - -# TiDB 2.1.11 Release Notes - -发版日期：2019 年 6 月 03 日 - -TiDB 版本：2.1.11 - -TiDB Ansible 版本：2.1.11 - -## TiDB - -- 修复 delete 多表 join 的结果时使用错误 schema 的问题 [#10595](https://github.com/pingcap/tidb/pull/10595) -- 修复 `CONVERT()` 函数返回错误的字段类型的问题 [#10263](https://github.com/pingcap/tidb/pull/10263) -- 更新统计信息时合并不重叠的反馈信息 [#10569](https://github.com/pingcap/tidb/pull/10569) -- 修复 `unix_timestamp()-unix_timestamp(now())` 计算错误的问题 [#10491](https://github.com/pingcap/tidb/pull/10491) -- 修复 `period_diff` 与 MySQL 8.0 不兼容的问题 [#10501](https://github.com/pingcap/tidb/pull/10501) -- 收集统计信息的时候，忽略 `Virtual Column`，避免异常报错 [#10628](https://github.com/pingcap/tidb/pull/10628) -- 支持 `SHOW OPEN TABLES` 语句 [#10374](https://github.com/pingcap/tidb/pull/10374) -- 修复某些情况下导致的 goroutine 泄露问题 [#10656](https://github.com/pingcap/tidb/pull/10656) -- 修复某些情况下设置 `tidb_snapshot` 变量时间格式解析出错的问题 [#10637](https://github.com/pingcap/tidb/pull/10637) - -## PD - -- 修复因为 `balance-region` 可能会导致热点 Region 没有机会调度的问题 [#1551](https://github.com/pingcap/pd/pull/1551) -- 将热点相关调度的优先级改为高优先级 [#1551](https://github.com/pingcap/pd/pull/1551) -- 新增配置项 `hot-region-schedule-limit` 控制同时进行热点调度任务的数量及新增 `hot-region-cache-hits-threshold` 控制判断是否为热点 Region [#1551](https://github.com/pingcap/pd/pull/1551) - -## TiKV - -- 修复在仅有一个 leader，learner 时，learner 读到空 index 的问题 [#4751](https://github.com/tikv/tikv/pull/4751) -- 将 `ScanLock` 和 `ResolveLock` 放在高优先级线程池中处理，减少对普通优先级命令的影响 [#4791](https://github.com/tikv/tikv/pull/4791) -- 同步所有收到的 snapshot 的文件 [#4811](https://github.com/tikv/tikv/pull/4811) - -## Tools - -- TiDB Binlog - - 新增 GC 删数据限速功能，避免因为删除数据导致 QPS 降低的问题 [#620](https://github.com/pingcap/tidb-binlog/pull/620) - -## TiDB Ansible - -- 新增 Drainer 参数 [#760](https://github.com/pingcap/tidb-ansible/pull/760) diff --git a/v3.1/releases/2.1.12.md b/v3.1/releases/2.1.12.md deleted file mode 100644 index 4461812971e9..000000000000 --- a/v3.1/releases/2.1.12.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: TiDB 2.1.12 Release Notes -category: Releases ---- - -# TiDB 2.1.12 Release Notes - -发版日期：2019 年 6 月 13 日 - -TiDB 版本：2.1.12 - -TiDB Ansible 版本：2.1.12 - -## TiDB - -- 修复在使用 feedback 时由于类型不匹配导致进程 panic 的问题 [#10755](https://github.com/pingcap/tidb/pull/10755) -- 修复某些情况下改变字符集导致 BLOB 类型变成 TEXT 类型的问题 [#10745](https://github.com/pingcap/tidb/pull/10745) -- 修复某些情况下在事务中的 `GRANT` 操作误报 "Duplicate Entry" 错误的问题 [#10739](https://github.com/pingcap/tidb/pull/10739) -- 提升以下功能跟 MySQL 的兼容性 - - `DAYNAME` 函数 [#10732](https://github.com/pingcap/tidb/pull/10732) - - `MONTHNAME` 函数 [#10733](https://github.com/pingcap/tidb/pull/10733) - - `EXTRACT` 函数在处理 `MONTH` 的时候支持零值 [#10702](https://github.com/pingcap/tidb/pull/10702) - - `DECIMAL` 类型转换成 `TIMESTAMP` 或者 `DATETIME` 类型 [#10734](https://github.com/pingcap/tidb/pull/10734) -- 修改表的字符集时，同步修改列的字符集 [#10714](https://github.com/pingcap/tidb/pull/10714) -- 修复某些情况下 `DECIMAL` 转换成浮点数的溢出问题 [#10730](https://github.com/pingcap/tidb/pull/10730) -- 修复 TiDB 跟 TiKV 在 gRPC 最大封包设置不一致导致的某些超大封包报 "grpc: received message larger than max" 错误的问题 [#10710](https://github.com/pingcap/tidb/pull/10710) -- 修复某些情况下 `ORDER BY` 没有过滤 NULL 值导致的 panic 问题 [#10488](https://github.com/pingcap/tidb/pull/10488) -- 修复 `UUID` 函数的返回值，在多机器情况可能出现重复的问题 [#10711](https://github.com/pingcap/tidb/pull/10711) -- `CAST(-num as datetime)` 的返回值由错误变更为 NULL 值 [#10703](https://github.com/pingcap/tidb/pull/10703) -- 修复某些情况下 unsigned 列直方图遇到 signed 越界的问题 [#10695](https://github.com/pingcap/tidb/pull/10695) -- 修复统计信息的 feedback 遇到 bigint unsigned 主键时处理不正确导致读数据时报错的问题 [#10307](https://github.com/pingcap/tidb/pull/10307) -- 修复分区表某些情况下 `Show Create Table` 结果显示不正确的问题 [#10690](https://github.com/pingcap/tidb/pull/10690) -- 修复在某些关联子查询上聚合函数 `GROUP_CONCAT` 计算不正确的问题 [#10670](https://github.com/pingcap/tidb/pull/10670) -- 修复某些情况下 slow query 内存表在解析慢日志的时候导致的显示结果错乱的问题 [#10776](https://github.com/pingcap/tidb/pull/10776) - -## PD - -- 修复极端情况下 etcd Leader 选举阻塞的问题 [#1576](https://github.com/pingcap/pd/pull/1576) - -## TiKV - -- 修复极端条件下 Leader 迁移过程中 Region 不可用的问题 [#4799](https://github.com/tikv/tikv/pull/4734) -- 修复在机器异常掉电时由于接收 snapshot 未及时将数据刷新到磁盘导致丢数据的问题 [#4850](https://github.com/tikv/tikv/pull/4850) diff --git a/v3.1/releases/2.1.13.md b/v3.1/releases/2.1.13.md deleted file mode 100644 index 781c56bb8cc2..000000000000 --- a/v3.1/releases/2.1.13.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.13 Release Notes -category: Releases ---- - -# TiDB 2.1.13 Release Notes - -发版日期：2019 年 6 月 21 日 - -TiDB 版本：2.1.13 - -TiDB Ansible 版本：2.1.13 - -## TiDB - -- 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 [#10788](https://github.com/pingcap/tidb/pull/10788) -- 优化无效 DDL 元信息存活时间，缩短集群升级后恢复 DDL 操作正常执行所需的时间 [#10789](https://github.com/pingcap/tidb/pull/10789) -- 修复因持有 `execdetails.ExecDetails` 指针时 Coprocessor 的资源无法快速释放导致的在大并发场景下 OOM 的问题 [#10833](https://github.com/pingcap/tidb/pull/10833) -- 新增 `update-stats`配置项，控制是否更新统计信息 [#10772](https://github.com/pingcap/tidb/pull/10772) -- 新增 3 个 TiDB 特有语法，支持预先切分 Region，解决热点问题： - - 新增 Table Option `PRE_SPLIT_REGIONS` 选项 [#10863](https://github.com/pingcap/tidb/pull/10863) - - 新增 `SPLIT TABLE table_name INDEX index_name` 语法 [#10865](https://github.com/pingcap/tidb/pull/10865) - - 新增 `SPLIT TABLE [table_name] BETWEEN (min_value...) AND (max_value...) REGIONS [region_num]` 语法 [#10882](https://github.com/pingcap/tidb/pull/10882) -- 修复某些情况下 `KILL` 语句导致的 panic 问题 [#10879](https://github.com/pingcap/tidb/pull/10879) -- 增强 `ADD_DATE` 在某些情况下跟 MySQL 的兼容性 [#10718](https://github.com/pingcap/tidb/pull/10718) -- 修复 index join 中内表过滤条件在某些情况下的选择率估计错误的问题 [#10856](https://github.com/pingcap/tidb/pull/10856) - -## TiKV - -- 修复因迭代器未检查状态导致系统生成残缺 snapshot 的问题 [#4940](https://github.com/tikv/tikv/pull/4940) -- 新增检查 `block-size` 配置的有效性功能 [#4930](https://github.com/tikv/tikv/pull/4930) - -## Tools - -TiDB Binlog - -- 修复 Pump 因写入失败时未检查返回值导致偏移量错误问题 [#640](https://github.com/pingcap/tidb-binlog/pull/640) -- Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 [#634](https://github.com/pingcap/tidb-binlog/pull/634) diff --git a/v3.1/releases/2.1.14.md b/v3.1/releases/2.1.14.md deleted file mode 100644 index 068864c31bc5..000000000000 --- a/v3.1/releases/2.1.14.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: TiDB 2.1.14 Release Notes -category: Releases ---- - -# TiDB 2.1.14 Release Notes - -发版日期：2019 年 7 月 4 日 - -TiDB 版本：2.1.14 - -TiDB Ansible 版本：2.1.14 - -## TiDB - -- 修复某些情况下列裁剪导致查询结果不正确的问题 [#11019](https://github.com/pingcap/tidb/pull/11019) -- 修复 `show processlist` 中 `db` 和 `info` 列信息显示有误的问题 [#11000](https://github.com/pingcap/tidb/pull/11000) -- 修复 `MAX_EXECUTION_TIME` 作为 SQL hint 和全局变量在某些情况下不生效的问题 [#10999](https://github.com/pingcap/tidb/pull/10999) -- 支持根据负载情况自动调整 Auto ID 分配的步长 [#10997](https://github.com/pingcap/tidb/pull/10997) -- 修复 SQL 查询结束时 `MemTracker` 统计的 DistSQL 内存信息未正确清理的问题 [#10971](https://github.com/pingcap/tidb/pull/10971) -- `information_schema.processlist` 表中新增 `MEM` 列用于描述 Query 的内存使用情况 [#10896](https://github.com/pingcap/tidb/pull/10896) -- 新增全局系统变量 `max_execution_time`，用于控制查询的最大执行时间 [10940](https://github.com/pingcap/tidb/pull/10940) -- 修复使用未支持的聚合函数导致 TiDB panic 的问题 [#10911](https://github.com/pingcap/tidb/pull/10911) -- 新增 `load data` 语句失败后自动回滚最后一个事务功能 [#10862](https://github.com/pingcap/tidb/pull/10862) -- 修复 TiDB 超过内存配额的行为配置为 CANCEL 时，某些情况下 TiDB 返回结果不正确的问题 [#11016](https://github.com/pingcap/tidb/pull/11016) -- 禁用 `TRACE` 语句，避免 TiDB panic 问题 [#11039](https://github.com/pingcap/tidb/pull/11039) -- 新增 `mysql.expr_pushdown_blacklist` 系统表，控制动态开启/关闭 TiDB 下推到 Coprocessor 的函数 [#10998](https://github.com/pingcap/tidb/pull/10998) -- 修复 `ANY_VALUE` 函数在 `ONLY_FULL_GROUP_BY` 模式下不生效的问题 [#10994](https://github.com/pingcap/tidb/pull/10994) -- 修复给字符串类型的用户量赋值时因未深度拷贝导致赋值不正确的问题 [#11043](https://github.com/pingcap/tidb/pull/11043) - -## TiKV - -- 优化 Raftstore 消息处理中对空回调的处理流程，避免发送不必要的消息 [#4682](https://github.com/tikv/tikv/pull/4682) - -## PD - -- 调整当读取到无效配置项时日志信息输出的级别，由 Error 调整为 Warning [#1577](https://github.com/pingcap/pd/pull/1577) - -## Tools - -TiDB Binlog - -- Reparo - - 新增 `safe-mode` 配置项，开启后支持导入重复的数据 [#662](https://github.com/pingcap/tidb-binlog/pull/662) -- Pump - - 新增 `stop-write-at-available-space` 配置项，限制 Binlog 空间保留的大小 [#659](https://github.com/pingcap/tidb-binlog/pull/659) - - 修复 LevelDB L0 文件个数为 0 时 GC 有时不生效的问题 [#648](https://github.com/pingcap/tidb-binlog/pull/648) - - 优化 log 文件删除的算法，加速释放空间 [#648](https://github.com/pingcap/tidb-binlog/pull/648) -- Drainer - - 修复下游 TiDB BIT 类型列更新失败的问题 [#655](https://github.com/pingcap/tidb-binlog/pull/655) - -## TiDB Ansible - -- 新增 `ansible` 命令及其 `jmespath`、`Jinja2` 依赖包的预检查功能 [#807](https://github.com/pingcap/tidb-ansible/pull/807) -- Pump 新增 `stop-write-at-available-space` 参数，当磁盘剩余空间小于该值（默认 10 GiB）时，Pump 停止写入 Binlog [#807](https://github.com/pingcap/tidb-ansible/pull/807) diff --git a/v3.1/releases/2.1.15.md b/v3.1/releases/2.1.15.md deleted file mode 100644 index e1b2be612ef3..000000000000 --- a/v3.1/releases/2.1.15.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB 2.1.15 Release Notes -category: Releases ---- - -# TiDB 2.1.15 Release Notes - -发版日期：2019 年 7 月 18 日 - -TiDB 版本：2.1.15 - -TiDB Ansible 版本：2.1.15 - -## TiDB - -+ 修复 `DATE_ADD` 函数处理微秒时由于没有对齐导致结果不正确的问题 [#11289](https://github.com/pingcap/tidb/pull/11289) -+ 修复 `DELETE` 语句中，字符串列中的空值与 FLOAT/INT 做比较时会报错的问题 [#11279](https://github.com/pingcap/tidb/pull/11279) -+ 修复 `INSERT` 函数参数有 `NULL` 值时，未正确返回 `NULL` 值的问题 [#11249](https://github.com/pingcap/tidb/pull/11249) -+ 修复在非字符串类型且长度为 0 的列建立索引时出错的问题 [#11215](https://github.com/pingcap/tidb/pull/11215) -+ 新增 `SHOW TABLE REGIONS` 的语句，支持通过 SQL 查询表的 Region 分布情况 [#11238](https://github.com/pingcap/tidb/pull/11238) -+ 修复 `UPDATE … SELECT` 语句因 `SELECT` 子查询中使用投影消除来优化规则所导致的报错 [#11254](https://github.com/pingcap/tidb/pull/11254) -+ 新增 `ADMIN PLUGINS ENABLE/DISABLE` SQL 语句，支持通过 SQL 动态开启/关闭 Plugin [#11189](https://github.com/pingcap/tidb/pull/11189) -+ Audit Plugin 新增审记连接功能 [#11189](https://github.com/pingcap/tidb/pull/11189) -+ 修复点查时，某列被查询多次而且结果为 NULL 时会 Panic 的问题 [#11227](https://github.com/pingcap/tidb/pull/11227) -+ 新增 `tidb_scatter_region` 配置项，控制创建表时是否开启自己打散 Record Region [#11213](https://github.com/pingcap/tidb/pull/11213) -+ 修复 `RAND` 函数由于非线程安全的 `rand.Rand` 导致的 Data Race 问题 [#11170](https://github.com/pingcap/tidb/pull/11170) -+ 修复某些情况下整数和非整数比较结果不正确的问题 [#11191](https://github.com/pingcap/tidb/pull/11191) -+ 支持修改 Database/Table 的 Collate，条件限制为 Database/Table 字符集必须是 UTF8/UTF8MB4 [#11085](https://github.com/pingcap/tidb/pull/11085) -+ 修复 `CURRENT_TIMESTAMP` 作为列的默认值且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11087](https://github.com/pingcap/tidb/pull/11087) - -## TiKV - -+ 统一日志格式 [#5083](https://github.com/tikv/tikv/pull/5083) -+ 提高 region approximate size/key 在极端情况下的准确性，提升调度准确度 [#5085](https://github.com/tikv/tikv/pull/5085) - -## PD - -+ 统一日志格式 [#1625](https://github.com/pingcap/pd/pull/1625) - -## Tools - -TiDB Binlog - -+ 优化 Pump GC 策略，去掉了未被在线 drainer 消费到的 binlog 保证不清理的限制 [#663](https://github.com/pingcap/tidb-binlog/pull/663) - -TiDB Lightning - -+ 修复 SQL dump 指明的列名不是小写时导入错误的问题 [#210](https://github.com/pingcap/tidb-lightning/pull/210) - -## TiDB Ansible - -+ TiDB Dashboard 新增 `parse duration` 和 `compile duration` 监控项，用于监测 SQL 语句解析耗时和执行计划编译耗时 [#815](https://github.com/pingcap/tidb-ansible/pull/815) diff --git a/v3.1/releases/2.1.16.md b/v3.1/releases/2.1.16.md deleted file mode 100644 index f0db29e15a9f..000000000000 --- a/v3.1/releases/2.1.16.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: TiDB 2.1.16 Release Notes -category: Releases ---- - -# TiDB 2.1.16 Release Notes - -发版日期：2019 年 8 月 15 日 - -TiDB 版本：2.1.16 - -TiDB Ansible 版本：2.1.16 - -## TiDB - -+ SQL 优化器 - - 修复时间列上的等值条件 Row Count 估算不准确的问题 [#11526](https://github.com/pingcap/tidb/pull/11526) - - 修复 `TIDB_INLJ` Hint 不生效或者对非指定的表生效的问题 [#11361](https://github.com/pingcap/tidb/pull/11361) - - 将查询中的 NOT EXISTS 由 OUTER JOIN 实现方式改为 ANTI JOIN ，便于找到更优执行计划 [#11291](https://github.com/pingcap/tidb/pull/11291) - - 支持在 `SHOW` 语句中使用子查询，现在可以支持诸如 `SHOW COLUMNS FROM tbl WHERE FIELDS IN (SELECT 'a')` 的写法 [#11461](https://github.com/pingcap/tidb/pull/11461) - - 修复常量折叠优化导致 `SELECT … CASE WHEN … ELSE NULL ...` 查询结果不正确的问题 [#11441](https://github.com/pingcap/tidb/pull/11441) -+ SQL 执行引擎 - - 修复函数 DATE_ADD 在 INTERVAL 为负的情况下结果错误的问题 [#11616](https://github.com/pingcap/tidb/pull/11616) - - 修复 `DATE_ADD` 函数接受 `FLOAT`、`DOUBLE` 和 `DECIMAL` 类型的参数时，没有正确地进行类型转换而导致结果可能不正确的问题 [#11628](https://github.com/pingcap/tidb/pull/11628) - - 修复 CAST(JSON AS SIGNED) 出现 OVERFLOW 时错误信息不准确的问题 [#11562](https://github.com/pingcap/tidb/pull/11562) - - 修复在关闭 Executor 的过程中，子节点关闭返回错误时其他子节点未关闭的问题 [#11598](https://github.com/pingcap/tidb/pull/11598) - - 支持 SPLIT TABLE 语句返回切分成功的 REGION 数量，并且当部分 REGION SCATTER 在超时未完成调度时，不再返回错误，而是返回完成调度的比例 [#11487](https://github.com/pingcap/tidb/pull/11487) - - 修复 `REGEXP BINARY` 函数对大小写敏感，与 MySQL 不兼容的问题 [#11505](https://github.com/pingcap/tidb/pull/11505) - - 修复 DATE_ADD / DATE_SUB 结果中 YEAR 小于 0 或 大于 65535 时溢出导致结果没有正确返回 NULL 值的问题 [#11477](https://github.com/pingcap/tidb/pull/11477) - - 慢查询表中添加用于表示是否执行成功的 `Succ` 字段 [#11412](https://github.com/pingcap/tidb/pull/11421) - - 修复一条 SQL 语句在涉及当前时间计算时（例如 `CURRENT_TIMESTAMP` 或者 `NOW`），多次取当前时间值，结果与 MySQL不兼容的问题：现在同一条SQL语句中取当前时间时，均使用相同值 [#11392](https://github.com/pingcap/tidb/pull/11392) - - 修复 AUTO INCREMENT 列未处理 FLOAT / DOUBLE 的问题 [#11389](https://github.com/pingcap/tidb/pull/11389) - - 修复 `CONVERT_TZ` 函数在参数不合法时，没有正确返回 NULL 的问题 [#11357](https://github.com/pingcap/tidb/pull/11357) - - 修复 PARTITION BY LIST 报错的问题（仅添加语法支持，TiDB 执行时候会作为普通表创建并提供提示信息） [#11236](https://github.com/pingcap/tidb/pull/11236) - - 修复 `Mod(%)`、`Multiple(*)` 和 `Minus(-)` 返回结果为 0 时，在小数位数较多（例如 `select 0.000 % 0.11234500000000000000`）的情况下与 MySQL 位数不一致的问题 [#11353](https://github.com/pingcap/tidb/pull/11353) -+ Server - - 修复插件在 OnInit 回调中获取 Domain 为 NULL 的问题 [#11426](https://github.com/pingcap/tidb/pull/11426) - - 修复当 Schema 删除后，依然可以通过 HTTP 接口获取该 Schema 中表信息的问题 [#11586](https://github.com/pingcap/tidb/pull/11586) -+ DDL - - 禁止 DROP 自增列索引，修复因为 DROP 自增列上的索引导致自增列结果可能出错的问题 [#11402](https://github.com/pingcap/tidb/pull/11402) - - 修复列和表使用不同的 CHARSET 和 COLLATE 创建表和修改表时，列的字符集不正确的问题 [#11423](https://github.com/pingcap/tidb/pull/11423) - - 修复并行执行 “alter table ... set default...” 和其他修改此列信息的 DDL，可能导致此列的结构出错的问题 [#11374](https://github.com/pingcap/tidb/pull/11374) - - 修复当 Generated column A 依赖 Generated column B 时，使用 A 创建索引，数据回填失败的问题 [#11538](https://github.com/pingcap/tidb/pull/11538) - - 提升 ADMIN CHECK TABLE 的速度 [#11538](https://github.com/pingcap/tidb/pull/11676) - -## TiKV - -+ 访问正在关闭的 TiKV Region 时返回 Close 错误 [#4820](https://github.com/tikv/tikv/pull/4820) -+ 支持逆向 `raw_scan` 和逆向 `raw_batch_scan` 接口 [#5148](https://github.com/tikv/tikv/pull/5148) - -## Tools - -+ TiDB Binlog - - Drainer 增加 `ignore-txn-commit-ts` 配置项，用于跳过执行某些事务语句 [#697](https://github.com/pingcap/tidb-binlog/pull/697) - - 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#708](https://github.com/pingcap/tidb-binlog/pull/708) - - Drainer 增加 `node-id` 配置，用于指定固定逻辑 Drainer [#706](https://github.com/pingcap/tidb-binlog/pull/706) -+ TiDB Lightning - - 修复 2 个 checksum 同时运行的情况下，`tikv_gc_life_time` 没有正常修改回原本值的问题 [#224](https://github.com/pingcap/tidb-lightning/pull/224) - -## TiDB Ansible - -+ Spark 新增 log4j 日志配置 [#842](https://github.com/pingcap/tidb-ansible/pull/842) -+ 更新 tispark jar 包为 v2.1.2 版本 [#863](https://github.com/pingcap/tidb-ansible/pull/863) -+ 修复了 TiDB Binlog 使用 Kafka 或者 ZooKeeper 时导致生成的 Prometheus 配置文件格式错误的问题 [#845](https://github.com/pingcap/tidb-ansible/pull/845) -+ 修复执行 `rolling_update.yml` 操作时，切换 PD Leader 失效的 Bug [#888](https://github.com/pingcap/tidb-ansible/pull/888) -+ 优化滚动升级 PD 节点的逻辑，先升级 Follower 再升级 Leader，提高稳定性 [#895](https://github.com/pingcap/tidb-ansible/pull/895) diff --git a/v3.1/releases/2.1.17.md b/v3.1/releases/2.1.17.md deleted file mode 100644 index 5dd52c509daa..000000000000 --- a/v3.1/releases/2.1.17.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 2.1.17 Release Notes -category: Releases ---- - -# TiDB 2.1.17 Release Notes - -发版日期：2019 年 9 月 11 日 - -TiDB 版本：2.1.17 - -TiDB Ansible 版本：2.1.17 - -- 新特性 - - TiDB 的 `SHOW TABLE REGIONS` 语法新增 `WHERE` 条件子句 - - TiKV、PD 新增 `config-check` 功能，用于配置项检查 - - pd-ctl 新增 `remove-tomestone` 命令，支持清理 tombstone store 记录 - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 - -- 改进提升 - - PD 优化调度流程，支持主动下发调度 - - TiKV 优化启动流程，减少重启节点带来的抖动 - -- 行为变更 - - TiDB 慢日志中的 `start ts` 由最后一次重试的时间改为第一次执行的时间 - - TiDB 慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 - - TiDB 配置文件中添加 `split-region-max-num` 参数，用于调整 `SPLIT TABLE` 语法允许的最大 Region 数量，默认配置下，允许的数量由 1,000 增加至 10,000 - -## TiDB - -+ SQL 优化器 - - 修复 `EvalSubquery` 在构建 `Executor` 出现错误时，错误信息没有被正确返回的问题 [#11811](https://github.com/pingcap/tidb/pull/11811) - - 修复 Index Lookup Join 中，外表的行数大于一个 batch 时，查询的结果可能不正确的问题；扩大 Index Lookup Join 的作用范围：可以使用 `UnionScan` 作为 `IndexJoin` 的子节点 [#11843](https://github.com/pingcap/tidb/pull/11843) - - 针对统计信息的反馈过程可能产生失效 Key 的情况，`SHOW STAT_BUCKETS` 语句现在增加了失效 Key 的显示，例如：`invalid encoded key flag 252` [#12098](https://github.com/pingcap/tidb/pull/12098) -+ SQL 执行引擎 - - 修复 `CAST` 函数在进行数值类型转换时，首先将数值转换为 `UINT` 导致一些结果不正确的问题（例如，`select cast(13835058000000000000 as double)`）[#11712](https://github.com/pingcap/tidb/pull/11712) - - 修复 `DIV` 运算的被除数为 `DECIMAL` 类型且运算含有负数时，运算结果可能不正确的问题 [#11812](https://github.com/pingcap/tidb/pull/11812) - - 添加 `ConvertStrToIntStrict` 函数，修复执行 `SELECT`/`EXPLAIN` 语句时，一些字符串转换 `INT` 类型结果与 MySQL 不兼容的问题 [#11892](https://github.com/pingcap/tidb/pull/11892) - - 修复使用 `EXPLAIN ... FOR CONNECTION` 语法时，`stmtCtx` 没有正确设置导致 `Explain` 结果可能不正确的问题 [#11978](https://github.com/pingcap/tidb/pull/11978) - - 修复 `unaryMinus` 函数，当 Int 结果溢出时，返回结果类型没有为 Decimal 导致与 MySQL 不兼容的问题 [#11990](https://github.com/pingcap/tidb/pull/11990) - - 修复 `LOAD DATA` 语句执行时，计数顺序导致的 `last_insert_id()` 可能不正确的问题 [#11994](https://github.com/pingcap/tidb/pull/11994) - - 修复用户显式、隐式混合写入自增列数据时，`last_insert_id()` 可能不正确的问题 [#12001](https://github.com/pingcap/tidb/pull/12001) - - 修复一个 `JSON_UNQUOTE` 函数兼容性问题：只有在双引号（`"`）内的值需要 Unquote，例如 `SELECT JSON_UNQUOTE("\\\\")` 应当为 "`\\`"（不进行 Unquote）[#12096](https://github.com/pingcap/tidb/pull/12096) -+ Server - - TiDB 事务重试时，记录在慢日志中的 `start ts` 由最后一次重试的时间改为第一次执行的时间 [#11878](https://github.com/pingcap/tidb/pull/11878) - - 在 `LockResolver` 中添加事务的 Key 数量：当 Key 数量较少时，可以避免对整个 Region 的 Scan 操作，减小清锁的代价 [#11889](https://github.com/pingcap/tidb/pull/11889) - - 修复慢日志中，`succ` 字段值可能不正确的问题 [#11886](https://github.com/pingcap/tidb/pull/11886) - - 将慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 [#12063](https://github.com/pingcap/tidb/pull/12063) - - 修复 `Duration` 内容中包含 `-` 时（例如 `select time(‘--’)`），TiDB 解析为 EOF Error 导致连接断开的错误 [#11910](https://github.com/pingcap/tidb/pull/11910) - - 改进 `RegionCache`：当一个 Region 失效时，它将会更快地从 `RegionCache` 中移除，减少向该 Region 发送请求的个数 [#11931](https://github.com/pingcap/tidb/pull/11931) - - 修复 `oom-action = "cancel"` 时，当 `Insert Into … Select` 语句发生 OOM，OOM Panic 没有被正确处理而导致连接断开的问题 [#12126](https://github.com/pingcap/tidb/pull/12126) -+ DDL - - 为 `tikvSnapshot` 添加逆序扫描接口用于高效地查询 DDL History Job，使用该接口后 `ADMIN SHOW DDL JOBS` 的执行时间有明显降低 [#11789](https://github.com/pingcap/tidb/pull/11789) - - 改进 `CREATE TABLE ... PRE_SPLIT_REGION` 的语义：当指定 `PRE_SPLIT_REGION = N` 时，将预切分的 Region 个数由 2^(N-1) 改为 2^N [#11797](https://github.com/pingcap/tidb/pull/11797/files) - - 根据[线上负载与 Add Index 相互影响测试](https://pingcap.com/docs-cn/dev/benchmark/add-index-with-load)，调小 Add Index 后台工作线程的默认参数以避免对线上负载造成较大影响 [#11875](https://github.com/pingcap/tidb/pull/11875) - - 改进 `SPLIT TABLE` 语法的行为：当使用 `SPLIT TABLE ... REGIONS N` 对 Region 切分时，会生成 N 个数据 Region 和 1 个索引 Region [#11929](https://github.com/pingcap/tidb/pull/11929) - - 在配置文件中添加 `split-region-max-num` 参数，使得 `SPLIT TABLE` 语法允许的最大 Region 数量可调整，该参数默认值 `10000` [#12080](https://github.com/pingcap/tidb/pull/12080) - - 修复写 binlog 时，`CREATE TABLE` 语句中 `PRE_SPLIT_REGIONS` 部分没有被注释，导致语句不能被下游 MySQL 解析的问题 [#12121](https://github.com/pingcap/tidb/pull/12121) - - `SHOW TABLE … REGIONS` 和 `SHOW TABLE .. INDEX … REGIONS` 语法新增 `WHERE` 条件子句 [#12124](https://github.com/pingcap/tidb/pull/12124) -+ Monitor - - 增加监控指标 `connection_transient_failure_count`，用于统计 `tikvclient` 的 gRPC 连接错误数量 [#12092](https://github.com/pingcap/tidb/pull/12092) - -## TiKV - -- 解决某些情况下 Region 内 key 个数统计不准的问题 [#5415](https://github.com/tikv/tikv/pull/5415) -- TiKV 新增 `config-check` 选项，用于检查 TiKV 配置项是否合法 [#5391](https://github.com/tikv/tikv/pull/5391) -- 优化启动流程，减少重启节点带来的抖动 [#5277](https://github.com/tikv/tikv/pull/5277) -- 优化某些情况下解锁的流程，加速事务解锁 [#5339](https://github.com/tikv/tikv/pull/5339) -- 优化 `get_txn_commit_info` 的流程，加速事务提交 [#5062](https://github.com/tikv/tikv/pull/5062) -- 简化 Raft 相关的 log [#5425](https://github.com/tikv/tikv/pull/5425) -- 解决在某些情况下 TiKV 异常退出的问题 [#5441](https://github.com/tikv/tikv/pull/5441) - -## PD - -- PD 新增 `config-check` 选项，用于检查 PD 配置项是否合法 [#1725](https://github.com/pingcap/pd/pull/1725) -- pd-ctl 新增 `remove-tomestone` 命令，支持清理 tombstone store 记录 [#1705](https://github.com/pingcap/pd/pull/1705) -- 支持主动下发 Operator，加快调度速度 [#1686](https://github.com/pingcap/pd/pull/1686) - -## Tools - -+ TiDB Binlog - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 [#746](https://github.com/pingcap/tidb-binlog/pull/746) - - Drainer 优化内存使用，提升同步执行效率 [#735](https://github.com/pingcap/tidb-binlog/pull/735) - - Pump 修复有时候无法正常下线的 bug [#739](https://github.com/pingcap/tidb-binlog/pull/739) - - Pump 优化 LevelDB 处理逻辑，提升 GC 执行效率 [#720](https://github.com/pingcap/tidb-binlog/pull/720) - -+ TiDB Lightning - - 修复从 checkpoint 点重新导入可能会导致 tidb-lightning 崩溃的 bug [#239](https://github.com/pingcap/tidb-lightning/pull/239) - -## TiDB Ansible - -- 更新 Spark 版本为 2.4.3，同时更新 TiSpark 为兼容该 Spark 的 2.2.0 版本 [#914](https://github.com/pingcap/tidb-ansible/pull/914)，[#919](https://github.com/pingcap/tidb-ansible/pull/927) -- 修复了当远程机器密码过期时长时间连接等待的问题 [#937](https://github.com/pingcap/tidb-ansible/pull/937)，[#948](https://github.com/pingcap/tidb-ansible/pull/948) diff --git a/v3.1/releases/2.1.18.md b/v3.1/releases/2.1.18.md deleted file mode 100644 index 7f5cc2c6bd73..000000000000 --- a/v3.1/releases/2.1.18.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: TiDB 2.1.18 Release Notes -category: Releases ---- - -# TiDB 2.1.18 Release Notes - -发版日期：2019 年 11 月 4 日 - -TiDB 版本：2.1.18 - -TiDB Ansible 版本：2.1.18 - -## TiDB - -+ SQL 优化器 - - 修复 Feedback 切分查询范围出错的问题 [#12172](https://github.com/pingcap/tidb/pull/12172) - - 修复点查中权限检查不正确的问题 [#12341](https://github.com/pingcap/tidb/pull/12341) - - 将 Limit 算子下推到 `IndexLookUpReader` 执行逻辑中，优化 `select ... limit ... offset ...` 的执行性能 [#12380](https://github.com/pingcap/tidb/pull/12380) - - 支持在 `ORDER BY`、`GROUP BY` 和 `LIMIT OFFSET` 中使用参数 [#12514](https://github.com/pingcap/tidb/pull/12514) - - 修复 partition 表上的 IndexJoin 返回错误结果的问题 [#12713](https://github.com/pingcap/tidb/pull/12713) - - 修复 TiDB 中 `str_to_date` 函数在日期字符串和格式化字符串不匹配的情况下，返回结果与 MySQL 不一致的问题 [#12757](https://github.com/pingcap/tidb/pull/12757) - - 修复当查询条件中包含 cast 函数时 outer join 被错误转化为 inner join 的问题 [#12791](https://github.com/pingcap/tidb/pull/12791) - - 修复 AntiSemiJoin 的 join 条件中错误的表达式传递 [#12800](https://github.com/pingcap/tidb/pull/12800) -+ SQL 执行引擎 - - 修复时间取整不正确的问题 (如 2019-09-11 11:17:47.999999666 应该被取整到 2019-09-11 11:17:48) [#12259](https://github.com/pingcap/tidb/pull/12259) - - 修复 `PREPARE` 语句类型没有记录在监控中的问题 [#12329](https://github.com/pingcap/tidb/pull/12329) - - 修复 `FROM_UNIXTIME` 在检查 NULL 值时 panic 的错误 [#12572](https://github.com/pingcap/tidb/pull/12572) - - 修复 `YEAR` 类型数据插入非法年份时，结果为 `NULL` 而不是 `0000` 的兼容性问题 [#12744](https://github.com/pingcap/tidb/pull/12744) - - 改进 AutoIncrement 列隐式分配时的行为，与 MySQL 自增锁的默认模式 (["consecutive" lock mode](https://dev.mysql.com/doc/refman/5.7/en/innodb-auto-increment-handling.html)) 保持一致：对于单行 Insert 语句的多个自增 AutoIncrement ID 的隐式分配，TiDB 保证分配值的连续性。该改进保证 JDBC `getGeneratedKeys()` 方法在任意场景下都能得到正确的结果。 [#12619](https://github.com/pingcap/tidb/pull/12619) - - 修复当 HashAgg 作为 Apply 子节点时查询 hang 住的问题 [#12769](https://github.com/pingcap/tidb/pull/12769) - - 修复逻辑表达式 AND / OR 在涉及类型转换时返回错误结果的问题 [#12813](https://github.com/pingcap/tidb/pull/12813) -+ Server - - 修复 `KILL TIDB QUERY` 语法对 `SLEEP()` 语句无效的问题 [#12159](https://github.com/pingcap/tidb/pull/12159) - - 修复 AUTO INCREMENT 分配 MAX int64 和 MAX uint64 没有报错的问题 [#12210](https://github.com/pingcap/tidb/pull/12210) - - 修复日志级别设置为 `ERROR` 时，慢日志不会被记录的问题 [#12373](https://github.com/pingcap/tidb/pull/12373) - - 将缓存 100 个 Schema 变更相关的表信息调整成 1024 个，且支持通过 `tidb_max_delta_schema_count` 系统变量修改 [#12515](https://github.com/pingcap/tidb/pull/12515) - - 将 SQL 的统计方式开始时间由“开始执行”改为“开始编译”，使得 SQL 性能统计更加准确 [#12638](https://github.com/pingcap/tidb/pull/12638) - - 在 TiDB 日志中添加 `set session autocommit` 的记录 [#12568](https://github.com/pingcap/tidb/pull/12568) - - 将 SQL 的开始时间记录在 `SessionVars` 中，避免计划执行时，该时间被重置 [#12676](https://github.com/pingcap/tidb/pull/12676) - - 在 `Order By`/`Group By`/`Limit Offset` 字句中支持 `?` 占位符 [#12514](https://github.com/pingcap/tidb/pull/12514) - - 慢日志中添加 `Prev_stmt` 字段，用于最后一条语句是 `COMMIT` 时输出前一条语句 [#12724](https://github.com/pingcap/tidb/pull/12724) - - 当一个显式提交的事务 `COMMIT` 时出错，在日志中记录 `COMMIT` 前一条语句 [#12747](https://github.com/pingcap/tidb/pull/12747) - - 优化在 TiDB Server 执行 SQL 时，对前一条语句的保存方式以提升性能 [#12751](https://github.com/pingcap/tidb/pull/12751) - - 修复 `skip-grant-table=true` 时，`FLUSH PRIVILEGES` 语句导致系统 Panic 的问题 [#12816](https://github.com/pingcap/tidb/pull/12816) - - 将 AutoID 的最小申请步长从 1000 增加为 30000，避免短时间大量写入时频繁请求 AutoID 造成性能瓶颈 [#12891](https://github.com/pingcap/tidb/pull/12891) - - 修复 Prepared 语句在 TiDB 发生 panic 时错误日志中未打印出错 SQL 的问题 [#12954](https://github.com/pingcap/tidb/pull/12954) - - 修复 COM_STMT_FETCH 慢日志时间记录和 MySQL 不一致问题 [#12953](https://github.com/pingcap/tidb/pull/12953) - - 当遇到写冲突时，在报错信息中添加错误码，以方便对冲突原因进行诊断 [#12878](https://github.com/pingcap/tidb/pull/12878) -+ DDL - - 为避免误操作，TiDB 默认不再允许删除列的 `AUTO INCREMENT` 属性，当确实需要删除时，请更改系统变量 `tidb_allow_remove_auto_inc`；相关文档请见：[TiDB 专用系统变量和语法](https://pingcap.com/docs-cn/v3.1/reference/configuration/tidb-server/tidb-specific-variables/) [#12146](https://github.com/pingcap/tidb/pull/12146) - - 支持 Create Table 语句中建唯一索引时带多个 Unique [#12469](https://github.com/pingcap/tidb/pull/12469) - - 修复 `CreateTable` 语句中指定外键约束时，外键表在没有指定 Database 时未能使用主表的 Database 导致报错的问题 [#12678](https://github.com/pingcap/tidb/pull/12678) - - 修复 `ADMIN CANCEL DDL JOBS` 时报 `invalid list index` 错的问题 [#12681](https://github.com/pingcap/tidb/pull/12681) -+ Monitor - - Backoff 监控添加类型，且补充之前没有统计到的 Backoff，比如 commit 时遇到的 Backoff [#12326](https://github.com/pingcap/tidb/pull/12326) - - 添加统计 Add Index 操作进度的监控 [#12389](https://github.com/pingcap/tidb/pull/12389) - -## PD - -- 修复 pd-ctl `--help` 命令输出内容 [#1772](https://github.com/pingcap/pd/pull/1772) - -## Tools - -+ TiDB Binlog - - 修复 `ALTER DATABASE` 相关 DDL 会导致 Drainer 异常退出的问题 [#770](https://github.com/pingcap/tidb-binlog/pull/770) - - 支持对 Commit binlog 查询事务状态信息，提升同步效率 [#761](https://github.com/pingcap/tidb-binlog/pull/761) - - 修复当 Drainer 的 `start_ts` 大于 Pump 中最大的 `commit_ts` 时候有可能引起 Pump panic 的问题 [#759](https://github.com/pingcap/tidb-binlog/pull/759) - -## TiDB Ansible - -- TiDB Binlog 增加 queue size 和 query histogram 监控项 [#952](https://github.com/pingcap/tidb-ansible/pull/952) -- 更新 TiDB 告警表达式 [#961](https://github.com/pingcap/tidb-ansible/pull/961) -- 新增配置文件检查功能，部署或者更新前会检查配置是否合理 [#973](https://github.com/pingcap/tidb-ansible/pull/973) -- TiDB 新增加索引速度监控项 [#987](https://github.com/pingcap/tidb-ansible/pull/987) -- 更新 TiDB Binlog 监控 Dashboard，兼容 4.6.3 版本的 Grafana [#993](https://github.com/pingcap/tidb-ansible/pull/993) diff --git a/v3.1/releases/2.1.19.md b/v3.1/releases/2.1.19.md deleted file mode 100644 index bafa841c7c20..000000000000 --- a/v3.1/releases/2.1.19.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 2.1.19 Release Notes -category: Releases ---- - -# TiDB 2.1.19 Release Notes - -发版日期：2019 年 12 月 27 日 - -TiDB 版本：2.1.19 - -TiDB Ansible 版本：2.1.19 - -## TiDB - -+ SQL 优化器 - - 优化 `select max(_tidb_rowid) from t` 的场景，避免全表扫 [#13294](https://github.com/pingcap/tidb/pull/13294) - - 修复当查询语句中赋予用户变量错误的值且将谓词下推后导致错误的输出结果 [#13230](https://github.com/pingcap/tidb/pull/13230) - - 修复更新统计信息时可能存在数据竞争，导致统计信息不准确的问题 [#13690](https://github.com/pingcap/tidb/pull/13690) - - 修复 `UPDATE` 语句中同时包含子查询和 stored generated column 时结果错误的问题；修复 `UPDATE` 语句中包含不同数据库的两个表名相同时，`UPDATE` 执行报错的问题 [#13357](https://github.com/pingcap/tidb/pull/13357) - - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14134](https://github.com/pingcap/tidb/pull/14134) - - 移除 `minAutoAnalyzeRatio` 约束使自动 `ANALYZE` 更及时 [#14013](https://github.com/pingcap/tidb/pull/14013) - - 当 `WHERE` 子句上有 `UNIQUE KEY` 的等值条件时，估算行数应该不大于 `1` [#13385](https://github.com/pingcap/tidb/pull/13385) -+ SQL 执行引擎 - - 修复 `ConvertJSONToInt` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#13036](https://github.com/pingcap/tidb/pull/13036) - - 修复查询中包含 `SLEEP` 函数时（例如 `select 1 from (select sleep(1)) t;)`），由于列裁剪导致查询中的 `sleep(1)` 失效的问题 [#13039](https://github.com/pingcap/tidb/pull/13039) - - 通过实现在 `INSERT ON DUPLICATE UPDATE` 语句中复用 `Chunk` 来降低内存开销 [#12999](https://github.com/pingcap/tidb/pull/12999) - - 给 `slow_query` 表添加事务相关的信息段 [#13129](https://github.com/pingcap/tidb/pull/13129)，如下： - - `Prewrite_time` - - `Commit_time` - - `Get_commit_ts_time` - - `Commit_backoff_time` - - `Backoff_types` - - `Resolve_lock_time` - - `Local_latch_wait_time` - - `Write_key` - - `Write_size` - - `Prewrite_region` - - `Txn_retry` - - 修复 `UPDATE` 语句中包含子查询时转换子查询出现的错误和当 `UPDATE` 的 `WHERE` 条件中包含子查询时更新失败的问题 [#13120](https://github.com/pingcap/tidb/pull/13120) - - 支持在分区表上执行 `ADMIN CHECK TABLE` [#13143](https://github.com/pingcap/tidb/pull/13143) - - 修复 `ON UPDATE CURRENT_TIMESTAMP` 作为列的属性且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#12462](https://github.com/pingcap/tidb/pull/12462) - - 修复在 `DROP/MODIFY/CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14162](https://github.com/pingcap/tidb/pull/14162) - - 修复 TiDB 开启 `Streaming` 后返回数据可能重复的问题 [#13255](https://github.com/pingcap/tidb/pull/13255) - - 修复夏令时导致的“无效时间格式”问题 [#13624](https://github.com/pingcap/tidb/pull/13624) - - 修复整型数据被转换为无符号 `Real`/`Decimal` 类型时，精度可能丢失的问题 [#13756](https://github.com/pingcap/tidb/pull/13756) - - 修复 `Quote` 函数处理 `null` 值时返回值类型出错的问题 [#13681](https://github.com/pingcap/tidb/pull/13681) - - 修复从字符串解析日期时，由于使用 `golang time.Local` 本地时区导致解析结果的时区不正确的问题 [#13792](https://github.com/pingcap/tidb/pull/13792) - - 修复 `builtinIntervalRealSig` 的实现中，由于 `binSearch` 方法不会返回 error，导致最终结果可能不正确的问题 [#13768](https://github.com/pingcap/tidb/pull/13768) - - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14009](https://github.com/pingcap/tidb/pull/14009) - - 修复 `sum(distinct)` 函数输出结果不正确的问题 [#13041](https://github.com/pingcap/tidb/pull/13041) - - 修复由于对 `jsonUnquoteFunction` 函数的返回类型长度赋值不正确的值，导致在 `union` 中同位置数据上进行 `cast` 转换时会截断数据的问题 [#13645](https://github.com/pingcap/tidb/pull/13645) - - 修复由于权限检查过于严格导致设置密码失败的问题 [#13805](https://github.com/pingcap/tidb/pull/13805) -+ Server - - 修复 `KILL CONNECTION` 可能出现 goroutine 泄漏的问题 [#13252](https://github.com/pingcap/tidb/pull/13252) - - 新增通过 HTTP API 的 `info/all` 接口获取所有 TiDB 节点的 binlog 状态功能 [#13188](https://github.com/pingcap/tidb/pull/13188) - - 修复在 Windows 上 build TiDB 项目失败的问题 [#13650](https://github.com/pingcap/tidb/pull/13650) - - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13904](https://github.com/pingcap/tidb/pull/13904) - - 修复通过 Go1.13 版本编译的二进制程序 `plugin` 不能正常运行的问题 [#13527](https://github.com/pingcap/tidb/pull/13527) -+ DDL - - 新增创建表时如果表包含 `COLLATE` 则列的 `COLLATE` 使用表的 `COLLATE` [#13190](https://github.com/pingcap/tidb/pull/13190) - - 新增创建表时限制索引名字的长度的功能 [#13311](https://github.com/pingcap/tidb/pull/13311) - - 修复 rename table 时未检查表名长度的问题 [#13345](https://github.com/pingcap/tidb/pull/13345) - - 新增 `BIT` 列的宽度范围检查的功能 [#13511](https://github.com/pingcap/tidb/pull/13511) - - 优化 `change/modify column` 的输出的错误信息，让人更容易理解 [#13798](https://github.com/pingcap/tidb/pull/13798) - - 修复执行 `drop column` 操作且下游 Drainer 还没有执行此 `drop column` 操作时，下游可能会收到不带此列的 DML 的问题 [#13974](https://github.com/pingcap/tidb/pull/13974) - -## TiKV - -+ Raftstore - - 修复 Region merge 和应用 Compact log 过程中系统若有重启，当重启时由于未正确设置 `is_merging` 的值导致系统 panic 的问题 [#5884](https://github.com/tikv/tikv/pull/5884) -+ Importer - - 取消 gRPC 的消息长度限制 [#5809](https://github.com/tikv/tikv/pull/5809) - -## PD - -- 提升获取 Region 列表的 HTTP API 性能 [#1988](https://github.com/pingcap/pd/pull/1988) -- 升级 etcd，修复 etcd PreVote 无法选出 leader 的问题（升级后无法降级） [#2052](https://github.com/pingcap/pd/pull/2052) - -## Tools - -+ TiDB Binlog - - 优化通过 binlogctl 输出的节点状态信息 [#777](https://github.com/pingcap/tidb-binlog/pull/777) - - 修复当 Drainer 过滤配置为 `nil` 时 panic 的问题 [#802](https://github.com/pingcap/tidb-binlog/pull/802) - - 优化 Pump 的 `Graceful` 退出方式 [#825](https://github.com/pingcap/tidb-binlog/pull/825) - - 新增 Pump 写 binlog 数据时更详细的监控指标 [#830](https://github.com/pingcap/tidb-binlog/pull/830) - - 优化 Drainer 在执行 DDL 后刷新表结构信息的逻辑 [#836](https://github.com/pingcap/tidb-binlog/pull/836) - - 修复 Pump 在没有收到 DDL 的 commit binlog 时该 binlog 被忽略的问题 [#855](https://github.com/pingcap/tidb-binlog/pull/855) - -## TiDB Ansible - -- TiDB 服务 `Uncommon Error OPM` 监控项更名为 `Write Binlog Error` 并增加对应的告警 [#1038](https://github.com/pingcap/tidb-ansible/pull/1038) -- 升级 TiSpark 版本为 2.1.8 [#1063](https://github.com/pingcap/tidb-ansible/pull/1063) diff --git a/v3.1/releases/2.1.2.md b/v3.1/releases/2.1.2.md deleted file mode 100644 index 532a6b0c2c57..000000000000 --- a/v3.1/releases/2.1.2.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.2 Release Notes -category: Releases ---- - -# TiDB 2.1.2 Release Notes - -2018 年 12 月 22 日，TiDB 发布 2.1.2 版，TiDB Ansible 相应发布 2.1.2 版本。该版本在 2.1.1 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 兼容 Kafka 版本的 TiDB Binlog [#8747](https://github.com/pingcap/tidb/pull/8747) -- 完善滚动升级下 TiDB 的退出机制 [#8707](https://github.com/pingcap/tidb/pull/8707) -- 修复在某些情况下为 generated column 增加索引 panic 的问题 [#8676](https://github.com/pingcap/tidb/pull/8676) -- 修复在某些情况下语句有 `TIDB_SMJ Hint` 的时候优化器无法找到正确执行计划的问题 [#8729](https://github.com/pingcap/tidb/pull/8729) -- 修复在某些情况下 `AntiSemiJoin` 返回错误结果的问题 [#8730](https://github.com/pingcap/tidb/pull/8730) -- 增强 `utf8` 字符集的有效字符检查 [#8754](https://github.com/pingcap/tidb/pull/8754) -- 修复事务中先写后读的情况下时间类型字段可能返回错误结果的问题 [#8746](https://github.com/pingcap/tidb/pull/8746) - -## PD - -- 修复 Region Merge 相关的 Region 信息更新问题 [#1377](https://github.com/pingcap/pd/pull/1377) - -## TiKV - -- 支持以日 (`d`) 为时间单位的配置格式，并解决配置兼容性问题 [#3931](https://github.com/tikv/tikv/pull/3931) -- 修复 Approximate Size Split 可能会 panic 的问题 [#3942](https://github.com/tikv/tikv/pull/3942) -- 修复两个 Region merge 相关问题 [#3822](https://github.com/tikv/tikv/pull/3822)，[#3873](https://github.com/tikv/tikv/pull/3873) - -## Tools - -+ TiDB Lightning - - 支持最小 TiDB 集群版本为 2.1.0 - - 修复解析包含 JSON 类型数据的文件内容出错 [#144](https://github.com/pingcap/tidb-tools/issues/144) - - 修复使用 checkpoint 重启后 `Too many open engines` 错误 -+ TiDB Binlog - - 消除了 Drainer 往 Kafka 写数据的一些瓶颈点 - - TiDB 支持写 [Kafka 版本的 TiDB Binlog](https://github.com/pingcap/docs-cn/blob/master/v2.1/reference/tidb-binlog/tidb-binlog-kafka.md) diff --git a/v3.1/releases/2.1.3.md b/v3.1/releases/2.1.3.md deleted file mode 100644 index ece2ccd5cf96..000000000000 --- a/v3.1/releases/2.1.3.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: TiDB 2.1.3 Release Notes -category: Releases ---- - -# TiDB 2.1.3 Release Notes - -2019 年 01 月 28 日，TiDB 发布 2.1.3 版，TiDB Ansible 相应发布 2.1.3 版本。相比 2.1.2 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复某些情况下 Prepared Plan Cache panic 的问题 [#8826](https://github.com/pingcap/tidb/pull/8826) - - 修复在有前缀索引的某些情况下，Range 计算错误的问题 [#8851](https://github.com/pingcap/tidb/pull/8851) - - 当 `SQL_MODE` 不为 STRICT 时, `CAST(str AS TIME(N))` 在 `str` 为非法的 TIME 格式的字符串时返回 NULL [#8966](https://github.com/pingcap/tidb/pull/8966) - - 修复某些情况下 Generated Column 在 Update 中 Panic 的问题 [#8980](https://github.com/pingcap/tidb/pull/8980) - - 修复统计信息直方图某些情况下上界溢出的问题 [#8989](https://github.com/pingcap/tidb/pull/8989) - - 支持对 `_tidb_rowid` 构造查询的 Range，避免全表扫，减轻集群压力 [#9059](https://github.com/pingcap/tidb/pull/9059) - - `CAST(AS TIME)` 在精度太大的情况下返回一个错误 [#9058](https://github.com/pingcap/tidb/pull/9058) - - 允许把 `Sort Merge Join` 用于笛卡尔积 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 修复统计信息的 worker 在某些情况下 panic 之后无法恢复的问题 [#9085](https://github.com/pingcap/tidb/pull/9085) - - 修复某些情况下 `Sort Merge Join` 结果不正确的问题 [#9046](https://github.com/pingcap/tidb/pull/9046) - - 支持在 `CASE` 子句返回 JSON 类型 [#8355](https://github.com/pingcap/tidb/pull/8355) -+ Server - - 当语句中有非 TiDB hint 的注释时返回警告，而不是错误 [#8766](https://github.com/pingcap/tidb/pull/8766) - - 验证设置的 TIMEZONE 的合法性 [#8879](https://github.com/pingcap/tidb/pull/8879) - - 优化 Metrics 项 `QueryDurationHistogram`，展示更多语句的类型 [#8875](https://github.com/pingcap/tidb/pull/8875) - - 修复 bigint 某些情况下下界溢出的问题 [#8544](https://github.com/pingcap/tidb/pull/8544) - - 支持 `ALLOW_INVALID_DATES` SQL mode [#9110](https://github.com/pingcap/tidb/pull/9110) -+ DDL - - 修复一个 RENAME TABLE 的兼容性问题，保持行为跟 MySQL 一致 [#8808](https://github.com/pingcap/tidb/pull/8808) - - 支持 `ADD INDEX` 的并发修改即时生效 [#8786](https://github.com/pingcap/tidb/pull/8786) - - 修复在 `ADD COLUMN` 的过程中，某些情况 Update 语句 panic 的问题 [#8906](https://github.com/pingcap/tidb/pull/8906) - - 修复某些情况下并发创建 Table Partition 的问题 [#8902](https://github.com/pingcap/tidb/pull/8902) - - 支持把 `utf8` 字符集转换为 `utf8mb4` 字符集 [#8951](https://github.com/pingcap/tidb/pull/8951) [#9152](https://github.com/pingcap/tidb/pull/9152) - - 处理 Shard Bits 溢出的问题 [#8976](https://github.com/pingcap/tidb/pull/8976) - - 支持 `SHOW CREATE TABLE` 输出列的字符集 [#9053](https://github.com/pingcap/tidb/pull/9053) - - 修复 varchar 最大支持字符数在 `utf8mb4` 下限制的问题 [#8818](https://github.com/pingcap/tidb/pull/8818) - - 支持 `ALTER TABLE TRUNCATE TABLE PARTITION` [#9093](https://github.com/pingcap/tidb/pull/9093) - - 修复创建表的时候缺省字符集推算的问题 [#9147](https://github.com/pingcap/tidb/pull/9147) - -## PD - -- 修复 Leader 选举相关的 Watch 问题 [#1396](https://github.com/pingcap/pd/pull/1396) - -## TiKV - -- 支持了使用 HTTP 方式获取监控信息 [#3855](https://github.com/tikv/tikv/pull/3855) -- 修复 `data_format` 遇到 NULL 时的问题 [#4075](https://github.com/tikv/tikv/pull/4075) -- 添加验证 Scan 请求的边界合法性 [#4124](https://github.com/tikv/tikv/pull/4124) - -## Tools - -+ TiDB Binlog - - 修复在启动或者重启时 `no available pump` 的问题 [#157](https://github.com/pingcap/tidb-tools/pull/158) - - 开启 Pump client log 输出 [#165](https://github.com/pingcap/tidb-tools/pull/165) - - 修复表只有 unique key 没有 primary key 的情况下，unique key 包含 NULL 值导致数据更新不一致的问题 diff --git a/v3.1/releases/2.1.4.md b/v3.1/releases/2.1.4.md deleted file mode 100644 index f3887706372a..000000000000 --- a/v3.1/releases/2.1.4.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB 2.1.4 Release Notes -category: Releases ---- - -# TiDB 2.1.4 Release Notes - -2019 年 2 月 15 日，TiDB 发布 2.1.4 版，TiDB Ansible 相应发布 2.1.4 版本。相比 2.1.3 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 修复 `VALUES` 函数未正确处理 FLOAT 类型的问题 [#9223](https://github.com/pingcap/tidb/pull/9223) - - 修复某些情况下 `CAST` 浮点数成字符串结果不正确的问题 [#9227](https://github.com/pingcap/tidb/pull/9227) - - 修复 `FORMAT` 函数在某些情况下结果不正确的问题 [#9235](https://github.com/pingcap/tidb/pull/9235) - - 修复某些情况下处理 Join 查询时 panic 的问题 [#9264](https://github.com/pingcap/tidb/pull/9264) - - 修复 `VALUES` 函数未正确处理 ENUM 类型的问题 [#9280](https://github.com/pingcap/tidb/pull/9280) - - 修复 `DATE_ADD`/`DATE_SUB` 在某些情况下结果不正确的问题 [#9284](https://github.com/pingcap/tidb/pull/9284) -+ Server - - 优化 reload privilege success 日志，将其调整为 DEBUG 级别 [#9274](https://github.com/pingcap/tidb/pull/9274) -+ DDL - - `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 变成 GLOBAL 变量 [#9134](https://github.com/pingcap/tidb/pull/9134) - - 修复某些异常情况下，在 Generated column 增加索引导致的 Bug [#9289](https://github.com/pingcap/tidb/pull/9289) - -## TiKV - -- 修复在 TiKV 关闭时可能发生重复写的问题 [#4146](https://github.com/tikv/tikv/pull/4146) -- 修复某些情况下 event listener 结果处理异常的问题 [#4132](https://github.com/tikv/tikv/pull/4132) - -## Tools - -+ Lightning - - 优化内存使用 [#107](https://github.com/pingcap/tidb-lightning/pull/107)，[#108](https://github.com/pingcap/tidb-lightning/pull/108) - - 去掉 dump files 的 chunk 划分，减少对 dump files 的一次额外解析 [#109](https://github.com/pingcap/tidb-lightning/pull/109) - - 限制读取 dump files 的 I/O 并发，避免过多的 cache miss 导致性能下降 [#110](https://github.com/pingcap/tidb-lightning/pull/110) - - 对单个表实现 batch 导入，提高导入的稳定性 [#110](https://github.com/pingcap/tidb-lightning/pull/113) - - TiKV 在 import 模式下开启 auto compactions [#4199](https://github.com/tikv/tikv/pull/4199) - - 增加禁用 TiKV periodic Level-1 compaction 参数，因为当 TiKV 集群为 2.1.4 或更高版本时，在导入模式下会自动执行 Level-1 compaction [#119](https://github.com/pingcap/tidb-lightning/pull/119) - - 限制 import engines 数量，避免过大占用 importer 磁盘空间 [#119](https://github.com/pingcap/tidb-lightning/pull/119) -+ 数据同步对比统计 (sync-diff-inspector) 支持使用 TiDB 统计信息来划分 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) \ No newline at end of file diff --git a/v3.1/releases/2.1.5.md b/v3.1/releases/2.1.5.md deleted file mode 100644 index da0cddef07ef..000000000000 --- a/v3.1/releases/2.1.5.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: TiDB 2.1.5 Release Notes -category: Releases ---- - -# TiDB 2.1.5 Release Notes - -2019 年 2 月 28 日，TiDB 发布 2.1.5 版，TiDB Ansible 相应发布 2.1.5 版本。相比 2.1.4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 当列的字符集信息和表的字符集信息相同时，`SHOW CREATE TABLE` 不再打印列的字符集信息，使其结果更加兼容 MySQL [#9306](https://github.com/pingcap/tidb/pull/9306) - - 将 `Sort` 算子中的表达计算抽取出来用一个 `Project` 算子完成，简化 `Sort` 算子的计算逻辑，修复某些情况下 `Sort` 算子结果不正确或者 panic 的问题 [#9319](https://github.com/pingcap/tidb/pull/9319) - - 移除 `Sort` 算子中的数值为常量的排序字段 [#9335](https://github.com/pingcap/tidb/pull/9335)，[#9440](https://github.com/pingcap/tidb/pull/9440) - - 修复向无符号整数列插入数据时数据溢出的问题 [#9339](https://github.com/pingcap/tidb/pull/9339) - - 目标 binary 的长度超过 `max_allowed_packet` 时，将 `cast_as_binary` 设置为 `NULL` [#9349](https://github.com/pingcap/tidb/pull/9349) - - 优化 `IF` 和 `IFNULL` 的常量折叠过程 [#9351](https://github.com/pingcap/tidb/pull/9351) - - 使用 skyline pruning 优化 TiDB 的索引选择，增加简单查询的稳定性 [#9356](https://github.com/pingcap/tidb/pull/9356) - - 支持对析取范式计算选择率 [#9405](https://github.com/pingcap/tidb/pull/9405) - - 修复 `!=ANY()` 和 `=ALL()` 在某些情况下 SQL 查询结果不正确的问题 [#9403](https://github.com/pingcap/tidb/pull/9403) - - 修复执行 Merge Join 操作的两个表的 Join Key 类型不同时结果可能不正确或者 panic 的问题 [#9438](https://github.com/pingcap/tidb/pull/9438) - - 修复某些情况下 `RAND()` 函数结果和 MySQL 不兼容的问题 [#9446](https://github.com/pingcap/tidb/pull/9446) - - 重构 Semi Join 对 `NULL` 值和空结果集的处理逻辑，使其返回正确的结果，更加兼容 MySQL [#9449](https://github.com/pingcap/tidb/pull/9449) -+ Server - - 增加系统变量 `tidb_constraint_check_in_place`，在 `INSERT` 语句执行时即检查数据的唯一性约束 [#9401](https://github.com/pingcap/tidb/pull/9401) - - 修复系统变量 `tidb_force_priority` 的值和配置文件中的设置的值不一致的问题 [#9347](https://github.com/pingcap/tidb/pull/9347) - - 在 general log 中增加 “current_db” 字段打印当前使用的数据库 [#9346](https://github.com/pingcap/tidb/pull/9346) - - 增加通过表 ID 来获取表信息的 HTTP API [#9408](https://github.com/pingcap/tidb/pull/9408) - - 修复 `LOAD DATA` 在某些情况下导入数据不正确的问题 [#9414](https://github.com/pingcap/tidb/pull/9414) - - 修复某些情况下，客户端建立连接慢的问题 [#9451](https://github.com/pingcap/tidb/pull/9451) -+ DDL - - 修复撤销 `DROP COLUMN` 操作中的一些问题 [#9352](https://github.com/pingcap/tidb/pull/9352) - - 修复撤销 `DROP`/`ADD` 分区表操作中的一些问题 [#9376](https://github.com/pingcap/tidb/pull/9376) - - 修复某些情况下 `ADMIN CHECK TABLE` 误报数据索引不一致的问题 [#9399](https://github.com/pingcap/tidb/pull/9399) - - 修复 `TIMESTAMP` 类型的默认值在时区上的一些问题 [#9108](https://github.com/pingcap/tidb/pull/9108) - -## PD - -- `GetAllStores` 接口提供了 `exclude_tombstone_stores` 选项，将 Tombstone store 从返回结果中去除 [#1444](https://github.com/pingcap/pd/pull/1444) - -## TiKV - -- 修复了某些情况下 Importer 导入失败的问题 [#4223](https://github.com/tikv/tikv/pull/4223) -- 修复了某些情况下 "key not in region" 错误 [#4125](https://github.com/tikv/tikv/pull/4125) -- 修复了某些情况下 Region merge 导致 panic 的问题 [#4235](https://github.com/tikv/tikv/pull/4235) -- 添加了详细的 `StoreNotMatch` 错误信息 [#3885](https://github.com/tikv/tikv/pull/3885) - -## Tools - -+ Lightning - - 集群中有 Tombstone store 时 Lightning 不会再报错退出 [#4223](https://github.com/tikv/tikv/pull/4223) -+ TiDB Binlog - - 修正 DDL Binlog 同步方案，确保 DDL 同步的正确性 [#9304](https://github.com/pingcap/tidb/issues/9304) diff --git a/v3.1/releases/2.1.6.md b/v3.1/releases/2.1.6.md deleted file mode 100644 index 1c55c70b466b..000000000000 --- a/v3.1/releases/2.1.6.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.1.6 Release Notes -category: Releases ---- - -# TiDB 2.1.6 Release Notes - -2019 年 3 月 15 日，TiDB 发布 2.1.6 版，TiDB Ansible 相应发布 2.1.6 版本。相比 2.1.5 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 优化器/执行器 - - 当两个表在 `TIDB_INLJ` 的 Hint 中时，基于代价来选择外表 [#9615](https://github.com/pingcap/tidb/pull/9615) - - 修复在某些情况下，没有正确选择 IndexScan 的问题 [#9587](https://github.com/pingcap/tidb/pull/9587) - - 修复聚合函数在子查询里面的检查跟 MySQL 不兼容的行为 [#9551](https://github.com/pingcap/tidb/pull/9551) - - 使 `show stats_histograms` 语句只输出合法的列，避免 Panic [#9502](https://github.com/pingcap/tidb/pull/9502) -+ Server - - 支持变量 `log_bin`，用于开启/关闭 Binlog [#9634](https://github.com/pingcap/tidb/pull/9634) - - 在事务中添加一个防御性检查，避免错误的事务提交 [#9559](https://github.com/pingcap/tidb/pull/9559) - - 修复设置变量导致的 Panic 的问题 [#9539](https://github.com/pingcap/tidb/pull/9539) -+ DDL - - 修复 Create Table Like 语句在某些情况导致 Panic 的问题 [#9652](https://github.com/pingcap/tidb/pull/9652) - - 打开 etcd client 的 AutoSync 特性，防止某些情况下 TiDB 无法连接上 etcd 的问题 [#9600](https://github.com/pingcap/tidb/pull/9600) - -## TiKV - -- 修复在某些情况下解析 protobuf 失败导致 `StoreNotMatch` 错误的问题 [#4303](https://github.com/tikv/tikv/pull/4303) - -## Tools - -+ Lightning - - importer 的默认的 region-split-size 变更为 512 MiB [#4369](https://github.com/tikv/tikv/pull/4369) - - 保存原先在内存中的中间状态的 SST 到磁盘，减少内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 限制 RocksDB 的内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 修复 Region 还没有调度完成时进行 scatter 的问题 [#4369](https://github.com/tikv/tikv/pull/4369) - - 将大表的数据和索引分离导入，在分批导入时能有效降低耗时 [#132](https://github.com/pingcap/tidb-lightning/pull/132) - - 支援 CSV [#111](https://github.com/pingcap/tidb-lightning/pull/111) - - 修复库名中含非英数字符时导入失败的错误 [#9547](https://github.com/pingcap/tidb/pull/9547) diff --git a/v3.1/releases/2.1.7.md b/v3.1/releases/2.1.7.md deleted file mode 100644 index 8ac63197224f..000000000000 --- a/v3.1/releases/2.1.7.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB 2.1.7 Release Notes -category: Releases ---- - -# TiDB 2.1.7 Release Notes - -发版日期：2019 年 3 月 28 日 - -TiDB 版本：2.1.7 - -TiDB Ansible 版本：2.1.7 - -## TiDB - -- 修复因 DDL 被取消导致升级程序时启动时间变长问题 [#9768](https://github.com/pingcap/tidb/pull/9768) -- 修复配置项 `check-mb4-value-in-utf8` 在 `config.example.toml` 中位置错误的问题 [#9852](https://github.com/pingcap/tidb/pull/9852) -- 提升内置函数 `str_to_date` 跟 MySQL 的兼容性 [#9817](https://github.com/pingcap/tidb/pull/9817) -- 修复内置函数 `last_day` 的兼容性问题 [#9750](https://github.com/pingcap/tidb/pull/9750) -- `infoschema.tables` 添加 `tidb_table_id` 列，方便通过 SQL 语句获取 `table_id`，新增 `tidb_indexes` 系统表管理 Table 与 Index 之间的关系 [#9862](https://github.com/pingcap/tidb/pull/9862) -- 增加 Table Partition 定义为空的检查 [#9663](https://github.com/pingcap/tidb/pull/9663) -- 将 `Truncate Table` 需要的权限由删除权限变为删表权限，与 MySQL 保持一致 [#9876](https://github.com/pingcap/tidb/pull/9876) -- 支持在 `DO` 语句中使用子查询 [#9877](https://github.com/pingcap/tidb/pull/9877) -- 修复变量 `default_week_format` 在 week 函数中不生效的问题 [#9753](https://github.com/pingcap/tidb/pull/9753) -- 支持插件机制 [#9880](https://github.com/pingcap/tidb/pull/9880)，[#9888](https://github.com/pingcap/tidb/pull/9888) -- 支持使用系统变量 `log_bin` 查看 binlog 开启状况 [#9634](https://github.com/pingcap/tidb/pull/9634) -- 支持使用 SQL 语句查看 Pump/Drainer 状态 [#9896](https://github.com/pingcap/tidb/pull/9896) -- 修复升级时对 utf8 检查 mb4 字符的兼容性 [#9887](https://github.com/pingcap/tidb/pull/9887) -- 修复某些情况下对 JSON 数据的聚合函数在计算过程中 Panic 的问题 [#9927](https://github.com/pingcap/tidb/pull/9927) - -## PD - -- 修改副本数为 1 时 balance-region 无法迁移 leader 问题 [#1462](https://github.com/pingcap/pd/pull/1462) - -## Tools - -- 支持 binlog 同步 generated column [#491](https://github.com/pingcap/tidb-binlog/pull/491) - -## TiDB Ansible - -- Prometheus 监控数据默认保留时间改成 30d diff --git a/v3.1/releases/2.1.8.md b/v3.1/releases/2.1.8.md deleted file mode 100644 index fec9580a22d7..000000000000 --- a/v3.1/releases/2.1.8.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: TiDB 2.1.8 Release Notes -category: Releases ---- - -# TiDB 2.1.8 Release Notes - -发版日期：2019 年 4 月 12 日 - -TiDB 版本：2.1.8 - -TiDB Ansible 版本：2.1.8 - -## TiDB - -- 修复 `GROUP_CONCAT` 函数在参数存在 NULL 值情况下与 MySQL 处理逻辑不兼容的问题 [#9930](https://github.com/pingcap/tidb/pull/9930) -- 修复在 Distinct 模式下 decimal 类型值之间相等比较的问题 [#9931](https://github.com/pingcap/tidb/pull/9931) -- 修复 `SHOW FULL COLUMNS` 语句在 date，datetime，timestamp 类型的 Collation 的兼容性问题 - - [#9938](https://github.com/pingcap/tidb/pull/9938) - - [#10114](https://github.com/pingcap/tidb/pull/10114) -- 修复过滤条件存在关联列的时候统计信息估算行数不准确的问题 [#9937](https://github.com/pingcap/tidb/pull/9937) -- 修复 `DATE_ADD` 跟 `DATE_SUB` 函数的兼容性问题 - - [#9963](https://github.com/pingcap/tidb/pull/9963) - - [#9966](https://github.com/pingcap/tidb/pull/9966) -- `STR_TO_DATE` 函数支持格式 `%H`，提升兼容性 [#9964](https://github.com/pingcap/tidb/pull/9964) -- 修复 `GROUP_CONCAT` 函数在 group by 唯一索引的情况下结果错误的问题 [#9969](https://github.com/pingcap/tidb/pull/9969) -- 当 Optimizer Hints 存在不匹配的表名的时候返回 warning [#9970](https://github.com/pingcap/tidb/pull/9970) -- 统一日志格式规范，利于工具收集分析 [日志规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md) -- 修复大量 NULL 值导致统计信息估算不准确的问题 [#9979](https://github.com/pingcap/tidb/pull/9979) -- 修复 TIMESTAMP 类型默认值为边界值的时候报错的问题 [#9987](https://github.com/pingcap/tidb/pull/9987) -- 检查设置 `time_zone` 值的合法性 [#10000](https://github.com/pingcap/tidb/pull/10000) -- 支持时间格式 `2019.01.01` [#10001](https://github.com/pingcap/tidb/pull/10001) -- 修复某些情况下 `EXPLAIN` 结果中行数估计错误显示的问题 [#10044](https://github.com/pingcap/tidb/pull/10044) -- 修复 `KILL TIDB [session id]` 某些情况下无法快速停止语句执行的问题 [#9976](https://github.com/pingcap/tidb/pull/9976) -- 修复常量过滤条件在某些情况中谓词下推的问题 [#10049](https://github.com/pingcap/tidb/pull/10049) -- 修复某些情况下 READ-ONLY 语句没有被当成 READ-ONLY 来处理的问题 [#10048](https://github.com/pingcap/tidb/pull/10048) - -## PD - -- 修复 Scatter Region 产生无效 Operator Step 的问题 [#1482](https://github.com/pingcap/pd/pull/1482) -- 修复 store 读热点的 key 统计不正确问题 [#1487](https://github.com/pingcap/pd/pull/1487) -- 修复 Region Merge Operator 超时时间过短的问题 [#1495](https://github.com/pingcap/pd/pull/1495) -- 添加 PD server 端处理 TSO 请求的耗时 metrics [#1502](https://github.com/pingcap/pd/pull/1502) - -## TiKV - -- 修复读流量统计错误的问题 [#4441](https://github.com/tikv/tikv/pull/4441) -- 修复 Region 数过多的情况下 raftstore 的性能问题 [#4484](https://github.com/tikv/tikv/pull/4484) -- 调整当 level 0 SST 数量超过 `level_zero_slowdown_writes_trigger/2` 时不再继续 ingest file [#4464](https://github.com/tikv/tikv/pull/4464) - -## Tools - -- Lightning 优化导入表的顺序，按照表的数据大小顺序进行导入，减少导入过程中大表执行 `Checksum` 和 `Analyze` 对集群的影响，并且提高 `Checksum` 和 `Analyze` 的成功率 [#156](https://github.com/pingcap/tidb-lightning/pull/156) -- 提升 Lightning encode SQL 性能，性能提升 50%，直接解析数据源文件内容成 TiDB 的 `types.Datum`，省去 KV encoder 的多余解析工作 [#145](https://github.com/pingcap/tidb-lightning/pull/145) -- TiDB Binlog Pump 新增 `storage.sync-log` 配置项，支持 Pump 本地存储异步刷盘 [#529](https://github.com/pingcap/tidb-binlog/pull/529) -- TiDB Binlog Pump 和 Drainer 之间通讯支持流量压缩 [#530](https://github.com/pingcap/tidb-binlog/pull/530) -- TiDB Binlog Drainer 新增 `syncer.sql-mode` 配置项，支持使用不同 `sql-mode` 解析 DDL query [#513](https://github.com/pingcap/tidb-binlog/pull/513) -- TiDB Binlog Drainer 新增 `syncer.ignore-table` 配置项，支持过滤不需要同步的表 [#526](https://github.com/pingcap/tidb-binlog/pull/526) - -## TiDB Ansible - -- 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 [#734](https://github.com/pingcap/tidb-ansible/pull/734) -- 添加检测系统是否支持 `epollexclusive` [#728](https://github.com/pingcap/tidb-ansible/pull/728) -- 增加滚动升级版本限制，不允许从 2.0.1 及以下版本滚动升级到 2.1 及以上版本 [#728](https://github.com/pingcap/tidb-ansible/pull/728) diff --git a/v3.1/releases/2.1.9.md b/v3.1/releases/2.1.9.md deleted file mode 100644 index 3f38b3a77279..000000000000 --- a/v3.1/releases/2.1.9.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: TiDB 2.1.9 Release Notes -category: Releases ---- - -# TiDB 2.1.9 Release Notes - -发版日期：2019 年 5 月 6 日 - -TiDB 版本：2.1.9 - -TiDB Ansible 版本：2.1.9 - -## TiDB - -- 修复 `MAKETIME` 函数在 unsigned 类型溢出时的兼容性 [#10089](https://github.com/pingcap/tidb/pull/10089) -- 修复常量折叠在某些情况下导致的栈溢出 [#10189](https://github.com/pingcap/tidb/pull/10189) -- 修复 Update 在某些有别名的情况下权限检查的问题 [#10157](https://github.com/pingcap/tidb/pull/10157) [#10326](https://github.com/pingcap/tidb/pull/10326) -- 追踪以及控制 DistSQL 中的内存使用 [#10197](https://github.com/pingcap/tidb/pull/10197) -- 支持指定 collation 为 utf8mb4_0900_ai_ci [#10201](https://github.com/pingcap/tidb/pull/10201) -- 修复主键为 Unsigned 类型的时候，MAX 函数结果错误的问题 [#10209](https://github.com/pingcap/tidb/pull/10209) -- 修复在非 Strict SQL Mode 下可以插入 NULL 值到 NOT NULL 列的问题 [#10254](https://github.com/pingcap/tidb/pull/10254) -- 修复 COUNT 函数在 DISTINCT 有多列的情况下结果错误的问题 [#10270](https://github.com/pingcap/tidb/pull/10270) -- 修复 LOAD DATA 解析不规则的 CSV 文件时候 Panic 的问题 [#10269](https://github.com/pingcap/tidb/pull/10269) -- 忽略 Index Lookup Join 中内外 join key 类型不一致的时候出现的 overflow 错误 [#10244](https://github.com/pingcap/tidb/pull/10244) -- 修复某些情况下错误判定语句为 point-get 的问题 [#10299](https://github.com/pingcap/tidb/pull/10299) -- 修复某些情况下时间类型未转换时区导致的结果错误问题 [#10345](https://github.com/pingcap/tidb/pull/10345) -- 修复 TiDB 字符集在某些情况下大小写比较不一致的问题 [#10354](https://github.com/pingcap/tidb/pull/10354) -- 支持控制算子返回的行数 [#9166](https://github.com/pingcap/tidb/issues/9166) - - Selection & Projection [#10110](https://github.com/pingcap/tidb/pull/10110) - - StreamAgg & HashAgg [#10133](https://github.com/pingcap/tidb/pull/10133) - - TableReader & IndexReader & IndexLookup [#10169](https://github.com/pingcap/tidb/pull/10169) -- 慢日志改进 - - 增加 SQL Digest 用于区分同类 SQL [#10093](https://github.com/pingcap/tidb/pull/10093) - - 增加慢语句使用的统计信息的版本信息 [#10220](https://github.com/pingcap/tidb/pull/10220) - - 输出语句内存使用量 [#10246](https://github.com/pingcap/tidb/pull/10246) - - 调整 Coprocessor 相关信息的输出格式，让其能被 pt-query-digest 解析 [#10300](https://github.com/pingcap/tidb/pull/10300) - - 修复慢语句中带有 `#` 字符的问题 [#10275](https://github.com/pingcap/tidb/pull/10275) - - 增加一些信息的列到慢查询的内存表 [#10317](https://github.com/pingcap/tidb/pull/10317) - - 将事务提交时间算入慢语句执行时间 [#10310](https://github.com/pingcap/tidb/pull/10310) - - 修复某些时间格式无法被 pt-query-digest 解析的问题 [#10323](https://github.com/pingcap/tidb/pull/10323) - -## PD - -- 支持 GetOperator 服务 [#1514](https://github.com/pingcap/pd/pull/1514) - -## TiKV - -- 修复在 transfer leader 时非预期的 quorum 变化 [#4604](https://github.com/tikv/tikv/pull/4604) - -## Tools - -- TiDB Binlog - - 修复 unsigned int 类型的主键列的 binlog 数据为负数，造成同步出错中断的问题 [#574](https://github.com/pingcap/tidb-binlog/pull/574) - - 删除下游是 `pb` 时的压缩选项，修改下游名字 `pb` 成 `file` [#597](https://github.com/pingcap/tidb-binlog/pull/575) - - 修复 2.1.7 引入的 Reparo 生成错误 update 语句的 bug [#576](https://github.com/pingcap/tidb-binlog/pull/576) -- TiDB Lightning - - 修复 parser 解析 bit 类型的 column 数据错误的 bug [#164](https://github.com/pingcap/tidb-lightning/pull/164) - - 使用 row id 或者列的默认值填充 dump 文件中缺少的 column 数据 [#174](https://github.com/pingcap/tidb-lightning/pull/174) - - Importer 修复部分 SST 导入失败依然返回导入成功的 bug [#4566](https://github.com/tikv/tikv/pull/4566) - - Importer 支持 upload SST 到 TiKV 限速 [#4607](https://github.com/tikv/tikv/pull/4607) - - 修改 Importer RocksDB SST 压缩方法为 `lz4`，减少 CPU 消耗 [#4624](https://github.com/tikv/tikv/pull/4624) -- sync-diff-inspector - - 支持 checkpoint [#227](https://github.com/pingcap/tidb-tools/pull/227) - -## TiDB Ansible - -- 更新 tidb-ansible 中的文档链接，兼容重构之后的文档 [#740](https://github.com/pingcap/tidb-ansible/pull/740)，[#741](https://github.com/pingcap/tidb-ansible/pull/741) -- 移除 `inventory.ini` 中的 `enable_slow_query_log` 参数，默认即将 slow log 输出到单独的日志文件中 [#742](https://github.com/pingcap/tidb-ansible/pull/742) diff --git a/v3.1/releases/2.1ga.md b/v3.1/releases/2.1ga.md deleted file mode 100644 index a440fd6e77e6..000000000000 --- a/v3.1/releases/2.1ga.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: TiDB 2.1 GA Release Notes -category: Releases ---- - -# TiDB 2.1 GA Release Notes - -2018 年 11 月 30 日，TiDB 发布 2.1 GA 版。相比 2.0 版本，该版本对系统稳定性、性能、兼容性、易用性做了大量改进。 - -## TiDB - -+ SQL 优化器 - - - 优化 `Index Join` 选择范围，提升执行性能 - - 优化 `Index Join` 外表选择，使用估算的行数较少的表作为外表 - - 扩大 Join Hint `TIDB_SMJ` 的作用范围，在没有合适索引可用的情况下也可使用 Merge Join - - 加强 Join Hint `TIDB_INLJ` 的能力，可以指定 Join 中的内表 - - 优化关联子查询，包括下推 Filter 和扩大索引选择范围，部分查询的效率有数量级的提升 - - 支持在 `UPDATE` 和 `DELETE` 语句中使用 Index Hint 和 Join Hint - - 支持更多函数下推：`ABS`/`CEIL`/`FLOOR`/`IS TRUE`/`IS FALSE` - - 优化内建函数 `IF` 和 `IFNULL` 的常量折叠算法 - - 优化 `EXPLAIN` 语句输出格式, 使用层级结构表示算子之间的上下游关系 - -+ SQL 执行引擎 - - - 重构所有聚合函数，提升 `Stream` 和 `Hash` 聚合算子的执行效率 - - 实现并行 `Hash Aggregate` 算子，部分场景下有 350% 的性能提升 - - 实现并行 `Project` 算子，部分场景有 74% 的性能提升 - - 并发地读取 `Hash Join` 的 `Inner` 表和 `Outer` 表的数据，提升执行性能 - - 优化 `REPLACE INTO` 语句的执行速度，性能提升 10x - - 优化时间类型的内存占用，时间类型数据的内存使用降低为原来的一半 - - 优化点查的查询性能，Sysbench 点查效率提升 60% - - TiDB 插入和更新宽表，性能提升接近 20 倍 - - 支持在配置文件中设置单个查询的内存使用上限 - - 优化 `Hash Join` 的执行过程，当 Join 类型为 `Inner Join` 或者 `Semi Join` 时，如果内表为空，不再读取外表数据，快速返回结果 - - 支持 `EXPLAIN ANALYZE` 语句，用于查看 Query 执行过程中各个算子的运行时间，返回结果行数等运行时统计信息 - -+ 统计信息 - - - 支持只在一天中的某个时间段开启统计信息自动 ANALYZE 的功能 - - 支持根据查询的反馈自动更新表的统计信息 - - 支持通过 `ANALYZE TABLE WITH BUCKETS` 语句配置直方图中桶的个数 - - 优化等值查询和范围查询混合的情况下使用直方图估算 Row Count 的算法 - -+ 表达式 - - + 支持内建函数： - - - `json_contains` - - `json_contains_path` - - `encode/decode` - -+ Server - - - 支持在单个 tidb-server 实例内部对冲突事务排队，优化事务间冲突频繁的场景下的性能 - - 支持 Server Side Cursor - - 新增 HTTP 管理接口 - - 打散 table 的 Regions 在 TiKV 集群中的分布 - - 控制是否打开 `general log` - - 在线修改日志级别 - - 查询 TiDB 集群信息 - - 添加 `auto_analyze_ratio` 系统变量控制自动 Analyze 的阈值 - - 添加 `tidb_retry_limit` 系统变量控制事务自动重试的次数 - - 添加 `tidb_disable_txn_auto_retry` 系统变量控制事务是否自动重试 - - 支持使用 `admin show slow` 语句来获取慢查询语句 - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 - -+ DDL - - - 支持 Add Index 语句与其他 DDL 语句并行执行，避免耗时的 Add Index 操作阻塞其他操作 - - 优化 `Add Index` 的速度，在某些场景下速度大幅提升 - - 支持 `select tidb_is_ddl_owner()` 语句，方便判断 TiDB 是否为 `DDL Owner` - - 支持 `ALTER TABLE FORCE` 语法 - - 支持 `ALTER TABLE RENAME KEY TO` 语法 - - `Admin Show DDL Jobs` 输出结果中添加表名、库名等信息 - - 支持使用 `ddl/owner/resign` HTTP 接口释放 DDL Owner 并开启新一轮 DDL Owner 选举 - -+ 兼容性 - - - 支持更多 MySQL 语法 - - `BIT` 聚合函数支持 `ALL` 参数 - - 支持 `SHOW PRIVILEGES` 语句 - - 支持 `LOAD DATA` 语句的 `CHARACTER SET` 语法 - - 支持 `CREATE USER` 语句的 `IDENTIFIED WITH` 语法 - - 支持 `LOAD DATA IGNORE LINES` 语句 - - `Show ProcessList` 语句返回更准确信息 - -## PD (Placement Driver) - -+ 可用性优化 - - - 引入 TiKV 版本控制机制，支持集群滚动兼容升级 - - PD 节点间开启 `Raft PreVote`，避免网络隔离后恢复时产生的重新选举 - - 开启 `raft learner` 功能，降低调度时出现宕机导致数据不可用的风险 - - TSO 分配不再受系统时间回退影响 - - 支持 `Region merge` 功能，减少元数据带来的开销 - -+ 调度器优化 - - - 优化 Down Store 的处理流程，加快发生宕机后补副本的速度 - - 优化热点调度器，在流量统计信息抖动时适应性更好 - - 优化 Coordinator 的启动，减少重启 PD 时带来的不必要调度 - - 优化 Balance Scheduler 频繁调度小 Region 的问题 - - 优化 Region merge，调度时考虑 Region 中数据的行数 - - 新增一些控制调度策略的开关 - - 完善调度模拟器，添加调度场景模拟 - -+ API 及运维工具 - - - 新增 `GetPrevRegion` 接口，用于支持 TiDB reverse scan 功能 - - 新增 `BatchSplitRegion` 接口，用于支持 TiKV 快速 Region 分裂 - - 新增 `GCSafePoint` 接口，用于支持 TiDB 并发分布式 GC - - 新增 `GetAllStores` 接口，用于支持 TiDB 并发分布式 GC - + pd-ctl 新增： - - - 使用统计信息进行 Region split - - 调用 `jq` 来格式化 JSON 输出 - - 查询指定 store 的 Region 信息 - - 查询按 version 排序的 topN 的 Region 列表 - - 查询按 size 排序的 topN 的 Region 列表 - - 更精确的 TSO 解码 - - - pd-recover 不再需要提供 max-replica 参数 - -+ 监控 - - - 增加 `Filter`相关的监控 - - 新增 etcd Raft 状态机相关监控 - -+ 性能优化 - - - 优化处理 Region heartbeat 的性能，减少 heartbeat 带来的内存开销 - - 优化 Region tree 性能 - - 优化计算热点统计的性能问题 - -## TiKV - -+ Coprocessor - - - 新增支持大量内建函数 - - 新增 Coprocessor ReadPool，提高请求处理并发度 - - 修复时间函数解析以及时区相关问题 - - 优化下推聚合计算的内存使用 - -+ Transaction - - - 优化 MVCC 读取逻辑以及内存使用效率，提高扫描操作的性能，Count 全表性能比 2.0 版本提升 1 倍 - - 折叠 MVCC 中连续的 Rollback 记录，保证记录的读取性能 - - 新增 `UnsafeDestroyRange` API 用于在 drop table/index 的情况下快速回收空间 - - GC 模块独立出来，减少对正常写入的影响 - - kv_scan 命令支持设置 upper bound - -+ Raftstore - - - 优化 snapshot 文件写入流程避免导致 RocksDB stall - - 增加 LocalReader 线程专门处理读请求，降低读请求的延迟 - - 支持 `BatchSplit` 避免大量写入导致产生特别大的 Region - - 支持按照统计信息进行 Region Split，减少 IO 开销 - - 支持按照 Key 的数量进行 Region Split，提高索引扫描的并发度 - - 优化部分 Raft 消息处理流程，避免 Region Split 带来不必要的延迟 - - 启用 `PreVote` 功能，减少网络隔离对服务的影响 - -+ 存储引擎 - - - 修复 RocksDB `CompactFiles` 的 bug，可能影响 Lightning 导入的数据 - - 升级 RocksDB 到 v5.15，解决 snapshot 文件可能会被写坏的问题 - - 优化 `IngestExternalFile`，避免 flush 卡住写入的问题 - -+ tikv-ctl - - - 新增 ldb 命令，方便排查 RocksDB 相关问题 - - compact 命令支持指定是否 compact bottommost 层的数据 - -## Tools - -- 全量数据快速导入工具 TiDB Lightning -- 支持新版本 TiDB Binlog - -## 升级兼容性说明 - -+ 由于新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 -+ 从 2.0.6 之前的版本升级到 2.1 之前，最好确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 Add Index 操作，等 DDL 操作完成后再执行升级操作 -+ 因为 2.1 版本启用了并行 DDL，对于早于 2.0.1 版本的集群，无法滚动升级到 2.1，可以选择下面两种方案： - - - 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 2.1 - - 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 2.1 版本 diff --git a/v3.1/releases/201.md b/v3.1/releases/201.md deleted file mode 100644 index f716920f38cc..000000000000 --- a/v3.1/releases/201.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: TiDB 2.0.1 release notes -category: Releases ---- - - -# TiDB 2.0.1 Release Notes - -2018 年 5 月 16 日，TiDB 发布 2.0.1 版。该版本在 2.0.0 (GA) 版的基础上，对 MySQL 兼容性、系统稳定性做出了改进。 - -## TiDB - -- 实时更新 `Add Index` 的进度到 DDL 任务信息中 -- 添加 Session 变量 `tidb_auto_analyze_ratio` 控制统计信息自动更新阈值 -- 修复当事务提交失败时可能未清理所有的残留状态的问题 -- 修复加索引在部分情况下的 Bug -- 修复 DDL 修改表面操作在某些并发场景下的正确性问题 -- 修复某些情况下 `LIMIT` 结果不正确的问题 -- 修复 `ADMIN CHECK INDEX` 语句索引名字区分大小写问题 -- 修复 `UNION` 语句的兼容性问题 -- 修复插入 `TIME` 类型数据的兼容性问题 -- 修复某些情况下 `copIteratorTaskSender` 导致的 goroutine 泄漏问题 -- 增加一个选项，用于设置 TiDB 在写 Binlog 失败的情况下的行为 -- 优化 Coprocessor 慢请求日志格式，区分处理时间长与排队时间长的任务 -- MySQL 协议握手阶段发生错误不打印日志，避免 KeepAlive 造成大量日志 -- 优化 `Out of range value for column` 的错误信息 -- 修复 `Update` 语句中遇到子查询导致结果错误的问题 -- 调整 TiDB 进程处理 `SIGTERM` 的行为，不等待正在执行的 Query 完成 - -## PD - -- 添加 `Scatter Range` 调度，调度指定 Key Range 包含的 Region -- 优化 `Merge Region` 调度，使新分裂不久的 Region 不能被合并 -- 添加 learner 相关的 metrics -- 修复重启误删 scheduler 的问题 -- 修复解析配置文件出错问题 -- 修复 etcd leader 和 PD leader 不同步的问题 -- 修复关闭 learner 情况下还有 learner 出现的问题 -- 修复读取包过大造成 load Regions 失败的问题 - -## TiKV - -- 修复 `SELECT FOR UPDATE` 阻止其他人读的问题 -- 优化慢查询的日志 -- 减少 `thread_yield` 的调用次数 -- 修复生成 snapshot 会意外阻塞 raftstore 的 bug -- 修复特殊情况下开启 learner 无法选举成功的问题 -- 修复极端情况下分裂可能导致的脏读问题 -- 修正读线程池的配置默认值 -- 修正删大数据表会影响写性能的问题 diff --git a/v3.1/releases/202.md b/v3.1/releases/202.md deleted file mode 100644 index fcc3842152e3..000000000000 --- a/v3.1/releases/202.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: TiDB 2.0.2 release notes -category: Releases ---- - -# TiDB 2.0.2 Release Notes - -2018 年 5 月 21 日，TiDB 发布 2.0.2 版。该版本在 2.0.1 版的基础上，对系统稳定性做出了改进。 - -## TiDB - -- 修复 Decimal 除法内置函数下推的问题 -- 支持 `Delete` 语句中使用 `USE INDEX` 的语法 -- 禁止在带有 `Auto-Increment` 的列中使用 `shard_row_id_bits` 特性 -- 增加写入 Binlog 的超时机制 - -## PD - -- 使 balance leader scheduler 过滤失连节点 -- 更改 transfer leader operator 的超时时间为 10 秒 -- 修复 label scheduler 在集群 Regions 不健康状态下不调度的问题 -- 修复 evict leader scheduler 调度不当的问题 - -## TiKV - -- 修复 Raft 日志没有打出来的问题 -- 支持配置更多 gRPC 相关参数 -- 支持配置选举超时的取值范围 -- 修复过期 learner 没有删掉的问题 -- 修复 snapshot 中间文件被误删的问题 \ No newline at end of file diff --git a/v3.1/releases/203.md b/v3.1/releases/203.md deleted file mode 100644 index 75974a1d1090..000000000000 --- a/v3.1/releases/203.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: TiDB 2.0.3 release notes -category: Releases ---- - -# TiDB 2.0.3 Release Notes - -2018 年 6 月 1 日，TiDB 发布 2.0.3 版。该版本在 2.0.2 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 支持在线更改日志级别 -- 支持 `COM_CHANGE_USER` 命令 -- 支持二进制协议情况下使用时间类型参数 -- 优化带 `BETWEEN` 表达式的查询条件代价估算 -- 在 `SHOW CREATE TABLE` 里不显示 `FOREIGN KEY` 信息 -- 优化带 `LIMIT` 子句的查询代价估算 -- 修复 `YEAR` 类型作为唯一索引的问题 -- 修复在没有唯一索引的情况下 `ON DUPLICATE KEY UPDATE` 的问题 -- 修复 `CEIL` 函数的兼容性问题 -- 修复 `DECIMAL` 类型计算 `DIV` 的精度问题 -- 修复 `ADMIN CHECK TABLE` 误报的问题 -- 修复 `MAX`/`MIN` 在特定表达式参数下 panic 的问题 -- 修复特殊情况下 `JOIN` 结果为空的问题 -- 修复 `IN` 表达式构造查询 `Range` 的问题 -- 修复使用 `Prepare` 方式进行查询且启用 `Plan Cache` 情况下的 Range 计算问题 -- 修复异常情况下频繁加载 Schema 信息的问题 - -## PD - -- 修复在特定条件下收集 hot-cache metrics 会 panic 的问题 -- 修复对旧的 Region 产生调度的问题 - -## TiKV - -- 修复 learner flag 错误上报给 PD 的 bug -- 在 `do_div_mod` 中 `divisor/dividend` 为 0 时返回错误 \ No newline at end of file diff --git a/v3.1/releases/204.md b/v3.1/releases/204.md deleted file mode 100644 index 23aa7846b142..000000000000 --- a/v3.1/releases/204.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB 2.0.4 release notes -category: Releases ---- - -# TiDB 2.0.4 Release Notes - -2018 年 6 月 15 日，TiDB 发布 2.0.4 版。该版本在 2.0.3 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 支持 `ALTER TABLE t DROP COLUMN a CASCADE` 语法 -- 支持设置 `tidb_snapshot` 变量的值为 `TSO` -- 优化监控项中语句类型展示 -- 优化查询代价估计精度 -- 设置 gRPC 的 `backoff max delay` 参数 -- 支持通过配置文件设置单条语句的内存使用阈值 -- 重构 Optimizer 的 error -- 解决 Cast Decimal 数据的副作用问题 -- 解决特定场景下 `Merge Join` 算子结果错误的问题 -- 解决转换 `Null` 对象到 String 的问题 -- 解决 Cast JSON 数据为 JSON 类型的问题 -- 解决 `Union` + `OrderBy` 情况下结果顺序和 MySQL 不一致的问题 -- 解决 `Union` 语句中对 `Limit`/`OrderBy` 子句的合法性检查规则问题 -- 解决 `Union All` 的结果兼容性问题 -- 解决谓词下推中的一个 Bug -- 解决 `Union` 语句对 `For Update` 子句的兼容性问题 -- 解决 `concat_ws` 函数对结果错误截断的问题 - -## PD - -- 改进 `max-pending-peer-count` 调度参数未设置时的行为，调整为不限制最大 `PendingPeer` 的数量 - -## TiKV - -- 新增 RocksDB `PerfContext` 接口用于调试 -- 移除 `import-mode` 参数 -- 为 `tikv-ctl` 添加 `region-properties` 命令 -- 优化有大量 RocksDB tombstone 时 `reverse-seek` 过慢的问题 -- 修复 `do_sub` 导致的崩溃问题 -- 当 GC 遇到有太多版本的数据时记录日志 diff --git a/v3.1/releases/205.md b/v3.1/releases/205.md deleted file mode 100644 index 588bed594a4d..000000000000 --- a/v3.1/releases/205.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: TiDB 2.0.5 release notes -category: Releases ---- - -# TiDB 2.0.5 Release Notes - -2018 年 7 月 6 日，TiDB 发布 2.0.5 版。该版本在 2.0.4 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- New Features - - 增加一个系统变量 `tidb_disable_txn_auto_retry`，用于关闭事务自动重试 [#6877](https://github.com/pingcap/tidb/pull/6877) -- Improvements - - 调整计算 `Selection` 代价的方式，结果更准确 [#6989](https://github.com/pingcap/tidb/pull/6989) - - 查询条件能够完全匹配唯一索引或者主键时，直接选择作为查询路径 [#6966](https://github.com/pingcap/tidb/pull/6966) - - 启动服务失败时，做必要的清理工作 [#6964](https://github.com/pingcap/tidb/pull/6964) - - 在 `Load Data` 语句中，将 `\N` 处理为 NULL [#6962](https://github.com/pingcap/tidb/pull/6962) - - 优化 CBO 代码结构 [#6953](https://github.com/pingcap/tidb/pull/6953) - - 启动服务时，尽早上报监控数据 [#6931](https://github.com/pingcap/tidb/pull/6931) - - 对慢查询日志格式进行优化：去除 SQL 语句中的换行符，增加用户信息 [#6920](https://github.com/pingcap/tidb/pull/6920) - - 支持注释中存在多个星号的情况 [#6858](https://github.com/pingcap/tidb/pull/6858) -- Bug Fixes - - 修复 `KILL QUERY` 语句权限检查问题 [#7003](https://github.com/pingcap/tidb/pull/7003) - - 修复用户数量超过 1024 时可能造成无法登录的问题 [#6986](https://github.com/pingcap/tidb/pull/6986) - - 修复一个写入无符号类型 `float`/`double` 数据的问题 [#6940](https://github.com/pingcap/tidb/pull/6940) - - 修复 `COM_FIELD_LIST` 命令的兼容性，解决部分 MariaDB 客户端遇到 Panic 的问题 [#6929](https://github.com/pingcap/tidb/pull/6929) - - 修复 `CREATE TABLE IF NOT EXISTS LIKE` 行为 [#6928](https://github.com/pingcap/tidb/pull/6928) - - 修复一个 TopN 下推过程中的问题 [#6923](https://github.com/pingcap/tidb/pull/6923) - - 修复 `Add Index` 过程中遇到错误时当前处理的行 ID 记录问题 [#6903](https://github.com/pingcap/tidb/pull/6903) - -## PD - -- 修复某些场景下副本迁移导致 TiKV 磁盘空间耗尽的问题 -- 修复 `AdjacentRegionScheduler` 导致的崩溃问题 - -## TiKV - -- 修复 decimal 运算中潜在的溢出问题 -- 修复 merge 过程中可能发生的脏读问题 \ No newline at end of file diff --git a/v3.1/releases/206.md b/v3.1/releases/206.md deleted file mode 100644 index 439798282357..000000000000 --- a/v3.1/releases/206.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TiDB 2.0.6 release notes -category: Releases ---- - -# TiDB 2.0.6 Release Notes - -2018 年 8 月 6 日，TiDB 发布 2.0.6 版。该版本在 2.0.5 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- Improvements - - 精简 "set system variable" 日志的长度，减少日志文件体积 [#7031](https://github.com/pingcap/tidb/pull/7031) - - 在日志中记录 `ADD INDEX` 执行过程中的慢操作，便于定位问题 [#7083](https://github.com/pingcap/tidb/pull/7083) - - 减少更新统计信息操作中的事务冲突 [#7138](https://github.com/pingcap/tidb/pull/7138) - - 当待估算的值超过统计信息范围时，提高行数估计的准确度 [#7185](https://github.com/pingcap/tidb/pull/7185) - - 当使用 `Index Join` 时，选择行数估计较小的表作为驱动表，提高 `Index Join` 的执行效率 [#7227](https://github.com/pingcap/tidb/pull/7227) - - 为 `ANALYZE TABLE` 语句执行过程中发生的 panic 添加 recover 机制，避免收集统计信息过程中的异常行为导致 tidb-server 不可用 [#7228](https://github.com/pingcap/tidb/pull/7228) - - 当 `RPAD`/`LPAD` 的结果超过设置系统变量 `max_allowed_packet` 时，返回 `NULL` 和对应的 warning，兼容 MySQL [#7244](https://github.com/pingcap/tidb/pull/7244) - - 设置 `PREPARE` 语句中占位符数量上限为 65535，兼容 MySQL [#7250](https://github.com/pingcap/tidb/pull/7250) -- Bug Fixes - - 修复某些情况下，`DROP USER` 语句和 MySQL 行为不兼容的问题 [#7014](https://github.com/pingcap/tidb/pull/7014) - - 修复当 `tidb_batch_insert` 打开后，`INSERT`/`LOAD DATA` 等语句在某些场景下 OOM 的问题 [#7092](https://github.com/pingcap/tidb/pull/7092) - - 修复某个表的数据持续更新时，其统计信息自动更新失效的问题 [#7093](https://github.com/pingcap/tidb/pull/7093) - - 修复防火墙断掉不活跃的 gRPC 连接的问题 [#7099](https://github.com/pingcap/tidb/pull/7099) - - 修复某些场景下使用前缀索引结果不正确的问题 [#7126](https://github.com/pingcap/tidb/pull/7126) - - 修复某些场景下统计信息过时导致 panic 的问题 [#7155](https://github.com/pingcap/tidb/pull/7155) - - 修复某些场景下 `ADD INDEX` 后索引数据少一条的问题 [#7156](https://github.com/pingcap/tidb/pull/7156) - - 修复某些场景下查询唯一索引上的 `NULL` 值结果不正确的问题 [#7172](https://github.com/pingcap/tidb/pull/7172) - - 修复某些场景下 `DECIMAL` 的乘法结果出现乱码的问题 [#7212](https://github.com/pingcap/tidb/pull/7212) - - 修复某些场景下 `DECIMAL` 的取模运算结果不正确的问题 [#7245](https://github.com/pingcap/tidb/pull/7245) - - 修复某些特殊语句序列下在事务中执行 `UPDATE`/`DELETE` 语句后结果不正确的问题 [#7219](https://github.com/pingcap/tidb/pull/7219) - - 修复某些场景下 `UNION ALL`/`UPDATE` 语句在构造执行计划过程中 panic 的问题 [#7225](https://github.com/pingcap/tidb/pull/7225) - - 修复某些场景下前缀索引的索引范围计算错误的问题 [#7231](https://github.com/pingcap/tidb/pull/7231) - - 修复某些场景下 `LOAD DATA` 语句不写 binlog 的问题 [#7242](https://github.com/pingcap/tidb/pull/7242) - - 修复某些场景下在 `ADD INDEX` 过程中 `SHOW CREATE TABLE` 结果不正确的问题 [#7243](https://github.com/pingcap/tidb/pull/7243) - - 修复某些场景下 `Index Join` 因为没有初始化事务时间戳而 panic 的问题 [#7246](https://github.com/pingcap/tidb/pull/7246) - - 修复 `ADMIN CHECK TABLE` 因为误用 session 中的时区而导致误报的问题 [#7258](https://github.com/pingcap/tidb/pull/7258) - - 修复 `ADMIN CLEANUP INDEX` 在某些场景下索引没有清除干净的问题 [#7265](https://github.com/pingcap/tidb/pull/7265) - - 禁用 Read Committed 事务隔离级别 [#7282](https://github.com/pingcap/tidb/pull/7282) - -## TiKV - -- Improvements - - 扩大默认 scheduler slots 值以减少假冲突现象 - - 减少回滚事务的连续标记以提升冲突极端严重下的读性能 - - 限制 RocksDB log 文件的大小和个数以减少长时间运行下不必要的磁盘占用 -- Bug Fixes - - 修复字符串转 Decimal 时出现的 crash \ No newline at end of file diff --git a/v3.1/releases/207.md b/v3.1/releases/207.md deleted file mode 100644 index 82cba1593466..000000000000 --- a/v3.1/releases/207.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: TiDB 2.0.7 release notes -category: Releases ---- - -# TiDB 2.0.7 Release Notes - -2018 年 9 月 7 日，TiDB 发布 2.0.7 版。该版本在 2.0.6 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- New Feature - - 在 `information_schema` 里添加 `PROCESSLIST` 表 [#7286](https://github.com/pingcap/tidb/pull/7286) -- Improvements - - 收集更多语句执行细节，并输出在 `SLOW QUERY` 日志里 [#7364](https://github.com/pingcap/tidb/pull/7364) - - `SHOW CREATE TABLE` 不再输出分区信息 [#7388](https://github.com/pingcap/tidb/pull/7388) - - 通过设置 RC 隔离级别和低优先级优化 `ANALYZE` 语句执行效率 [#7500](https://github.com/pingcap/tidb/pull/7500) - - 加速 `ADD UNIQUE INDEX` [#7562](https://github.com/pingcap/tidb/pull/7562) - - 增加控制 DDL 并发度的选项 [#7563](https://github.com/pingcap/tidb/pull/7563) -- Bug Fixes - - 修复 `PRIMARY KEY` 为整数的表，无法使用 `USE INDEX(PRIMARY)` 的问题 [#7298](https://github.com/pingcap/tidb/pull/7298) - - 修复 `Merge Join` 和 `Index Join` 在 inner row 为 `NULL` 时输出多余结果的问题 [#7301](https://github.com/pingcap/tidb/pull/7301) - - 修复 chunk size 设置过小时，`Join` 输出多余结果的问题 [#7315](https://github.com/pingcap/tidb/pull/7315) - - 修复建表语句中包含 `range column` 语法导致 panic 的问题 [#7379](https://github.com/pingcap/tidb/pull/7379) - - 修复 `admin check table` 对时间类型的列误报的问题 [#7457](https://github.com/pingcap/tidb/pull/7457) - - 修复以默认值 `current_timestamp` 插入的数据无法用 `=` 条件查询到的问题 [#7467](https://github.com/pingcap/tidb/pull/7467) - - 修复以 `ComStmtSendLongData` 命令插入空字符串参数被误解析为 `NULL` 的问题 [#7508](https://github.com/pingcap/tidb/pull/7508) - - 修复特定场景下 `auto analyze` 不断重复执行的问题 [#7556](https://github.com/pingcap/tidb/pull/7556) - - 修复 parser 无法解析以换行符结尾的单行注释的问题 [#7635](https://github.com/pingcap/tidb/pull/7635) - -## TiKV - -- Improvement - - 空集群默认打开 `dynamic-level-bytes` 参数减少空间放大 -- Bug Fix - - 在 Region merge 之后更新 Region 的 `approximate size` 和 keys \ No newline at end of file diff --git a/v3.1/releases/208.md b/v3.1/releases/208.md deleted file mode 100644 index 1e1e1791c1d1..000000000000 --- a/v3.1/releases/208.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: TiDB 2.0.8 release notes -category: Releases ---- - -# TiDB 2.0.8 Release Notes - -2018 年 10 月 16 日，TiDB 发布 2.0.8 版。该版本在 2.0.7 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -+ 功能改进 - - 在 `Update` 没有更改相应 AUTO-INCREMENT 列情况下，防止 AUTO-ID 被消耗过快 [#7846](https://github.com/pingcap/tidb/pull/7846) -+ Bug 修复 - - 在 PD Leader 异常宕机的情况下，TiDB 快速创建 etcd Session 恢复服务 [#7810](https://github.com/pingcap/tidb/pull/7810) - - 修复 `DateTime` 类型使用默认值时候没有考虑时区的问题 [#7672](https://github.com/pingcap/tidb/pull/7672) - - 修复 `duplicate key update` 在某些情况下没有正确插入值的问题 [#7685](https://github.com/pingcap/tidb/pull/7685) - - 修复 `UnionScan` 中谓词条件没有下推的问题 [#7726](https://github.com/pingcap/tidb/pull/7726) - - 修复增加 `TIMESTAMP` 索引没有正确处理时区的问题 [#7812](https://github.com/pingcap/tidb/pull/7812) - - 修复某些情况下统计信息模块导致的内存泄露问题 [#7864](https://github.com/pingcap/tidb/pull/7864) - - 修复在某些异常情况下，无法获得 `ANALYZE` 结果的问题 [#7871](https://github.com/pingcap/tidb/pull/7871) - - 令 `SYSDATE` 不做表达式展开，以返回正确的结果 [#7894](https://github.com/pingcap/tidb/pull/7894) - - 修复某些情况下，`substring_index` panic 的问题 [#7896](https://github.com/pingcap/tidb/pull/7896) - - 修复某些情况下，错误将 `OUTER JOIN` 转为 `INNER JOIN` 的问题 [#7899](https://github.com/pingcap/tidb/pull/7899) - -## TiKV - -+ Bug 修复 - - 修复节点宕机时 Raftstore `EntryCache` 占用内存持续上升的问题 [#3529](https://github.com/tikv/tikv/pull/3529) \ No newline at end of file diff --git a/v3.1/releases/209.md b/v3.1/releases/209.md deleted file mode 100644 index 430587a019a9..000000000000 --- a/v3.1/releases/209.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: TiDB 2.0.9 Release Notes -category: Releases ---- - -# TiDB 2.0.9 Release Notes - -2018 年 11 月 19 日，TiDB 发布 2.0.9 版。该版本在 2.0.8 版的基础上，对系统兼容性、稳定性做出了改进。 - -## TiDB - -- 修复统计信息直方图为空的时候导致的问题 [#7927](https://github.com/pingcap/tidb/pull/7927) -- 修复 `UNION ALL` 语句在某些情况下 panic 的问题 [#7942](https://github.com/pingcap/tidb/pull/7942) -- 修复错误的 DDL JOB 情况下导致的递归溢出问题 [#7959](https://github.com/pingcap/tidb/pull/7959) -- 为 `Commit` 操作加上慢操作日志 [#7983](https://github.com/pingcap/tidb/pull/7983) -- 修复 `Limit` 值太大的情况下导致的 panic 问题 [#8004](https://github.com/pingcap/tidb/pull/8004) -- 支持 `USING` 子句指定 `utf8mb4` 字符集 [#8048](https://github.com/pingcap/tidb/pull/8048) -- 内建函数 `TRUNCATE` 支持类型为 unsigned int 的参数 [#8069](https://github.com/pingcap/tidb/pull/8069) -- 修复统计信息模块在某些情况下主键选择率估算的问题 [#8150](https://github.com/pingcap/tidb/pull/8150) -- 增加 `Session` 变量来控制是否允许写入 `_tidb_rowid` [#8126](https://github.com/pingcap/tidb/pull/8126) -- 修复 `PhysicalProjection` 在某些情况下 panic 的问题 [#8154](https://github.com/pingcap/tidb/pull/8154) -- 修复 `Union` 语句在某些情况下结果不稳定的问题 [#8168](https://github.com/pingcap/tidb/pull/8168) -- 修复在非插入语句下 `values` 没有返回 `NULL` 的问题 [#8179](https://github.com/pingcap/tidb/pull/8179) -- 修复某些情况下统计信息模块无法清除过期统计数据的问题 [#8184](https://github.com/pingcap/tidb/pull/8184) -- 让事务允许的最长运行时间变成一个可配置项 [#8209](https://github.com/pingcap/tidb/pull/8209) -- 修复 `expression rewriter` 某些情况下错误的比较逻辑 [#8288](https://github.com/pingcap/tidb/pull/8288) -- 消除 `UNION ORDER BY` 语句生成的多余列的问题 [#8307](https://github.com/pingcap/tidb/pull/8307) -- 支持 `admin show next_row_id` 语句 [#8274](https://github.com/pingcap/tidb/pull/8274) -- 修复 `Show Create Table` 语句中特殊字符转义的问题 [#8321](https://github.com/pingcap/tidb/pull/8321) -- 修复 `UNION` 语句在某些情况下遇到非预期错误的问题 [#8318](https://github.com/pingcap/tidb/pull/8318) -- 修复某些情况下取消 DDL 任务导致的 Schema 没有回滚的问题 [#8312](https://github.com/pingcap/tidb/pull/8312) -- 把变量 `tidb_max_chunk_size` 变成全局环境变量 [#8333](https://github.com/pingcap/tidb/pull/8333) -- ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8309](https://github.com/pingcap/tidb/pull/8309) [#8310](https://github.com/pingcap/tidb/pull/8310) - -## PD - -- 修复 etcd 启动失败导致的服务挂起问题 [#1267](https://github.com/pingcap/pd/pull/1267) -- 修复 `pd-ctl` 读取 Region key 的相关问题 [#1298](https://github.com/pingcap/pd/pull/1298) [#1299](https://github.com/pingcap/pd/pull/1299) [#1308](https://github.com/pingcap/pd/pull/1308) -- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -- 修复 PD join 失败后无法重新 join 的问题 [1279](https://github.com/pingcap/pd/pull/1279) - -## TiKV - -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) -- 废弃配置 `max-tasks-xxx` 并新增 `max-tasks-per-worker-xxx` [#3093](https://github.com/tikv/tikv/pull/3093) -- 修复 RocksDB `CompactFiles` 的问题 [#3789](https://github.com/tikv/tikv/pull/3789) \ No newline at end of file diff --git a/v3.1/releases/21beta.md b/v3.1/releases/21beta.md deleted file mode 100644 index 18cafa4e0de7..000000000000 --- a/v3.1/releases/21beta.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: TiDB 2.1 Beta Release Notes -category: Releases ---- - -# TiDB 2.1 Beta Release Notes - -2018 年 6 月 29 日，TiDB 发布 2.1 Beta 版。相比 2.0 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 优化 `Index Join` 选择范围，提升执行性能 - - 优化关联子查询，下推 Filter 和扩大索引选择范围，部分查询的效率有数量级的提升 - - 在 `UPDATE`、`DELETE` 语句中支持 `Index Hint` 和 `Join Hint` - - 优化器 Hint `TIDM_SMJ` 在没有索引可用的情况下可生效 - - 支持更多函数下推：`ABS`/`CEIL`/`FLOOR`/`IS TRUE`/`IS FALSE` - - 在常量折叠过程中特殊处理函数 `IF` 和 `IFNULL` - - 优化 `EXPLAIN` 语句输出格式 -- SQL 执行引擎 - - 实现并行 `Hash Aggregate` 算子，部分场景下能提高 `Hash Aggregate` 计算性能 350% - - 实现并行 `Project` 算子，部分场景下性能提升达 74% - - 并发地读取 `Hash Join` 的 `Inner` 表和 `Outer` 表的数据，提升执行性能 - - 修复部分场景下 `INSERT … ON DUPLICATE KEY UPDATE …` 结果不正确的问题 - - 修复 `CONCAT_WS`/`FLOOR`/`CEIL`/`DIV` 内建函数的结果不正确的问题 -- Server - - 添加 HTTP API 打散 table 的 Regions 在 TiKV 集群中的分布 - - 添加 `auto_analyze_ratio` 系统变量控制自动 analyze 的阈值 - - 添加 HTTP API 控制是否打开 `general log` - - 添加 HTTP API 在线修改日志级别 - - 在 `general log` 和 `slow query log` 中添加 user 信息 - - 支持 Server side cursor -- 兼容性 - - 支持更多 MySQL 语法 - - `BIT` 聚合函数支持 `ALL` 参数 - - 支持 `SHOW PRIVILEGES` 语句 -- DML - - 减少 `INSERT INTO SELECT` 语句的内存占用 - - 修复 Plan Cache 的性能问题 - - 添加 `tidb_retry_limit` 系统变量控制事务自动重试的次数 - - 添加 `tidb_disable_txn_auto_retry` 系统变量控制事务是否自动重试 - - 修复写入 `time` 类型的数据精度问题 - - 支持本地冲突事务排队，优化冲突事务性能 - - 修复 `UPDATE` 语句的 `Affected Rows` - - 优化 `insert ignore on duplicate key update` 语句性能 - - 优化 `Create Table` 语句的执行速度 - - 优化 `Add index` 的速度，在某些场景下速度大幅提升 - - 修复 `Alter table add column` 增加列超过表的列数限制的问题 - - 修复在某些异常情况下 DDL 任务重试导致 TiKV 压力增加的问题 - - 修复在某些异常情况下 TiDB 不断重载 Schema 信息的问题 -- DDL - - `Show Create Table` 不再输出外键相关的内容 - - 支持 `select tidb_is_ddl_owner()` 语句，方便判断 TiDB 是否为 `DDL Owner` - - 修复某些场景下 `YEAR` 类型删除索引的问题 - - 修复并发执行场景下的 `Rename table` 的问题 - - 支持 `ALTER TABLE FORCE` 语法 - - 支持 `ALTER TABLE RENAME KEY TO` 语法 - - `admin show ddl jobs` 输出信息中添加表名、库名等信息 - -## PD - -- PD 节点间开启 `Raft PreVote`，避免网络隔离后恢复时产生的重新选举 -- 优化 Balance Scheduler 频繁调度小 Region 的问题 -- 优化热点调度器，在流量统计信息抖动时适应性更好 -- `region merge` 调度时跳过数据行数较多的 Region -- 默认开启 `raft learner` 功能，降低调度时出现宕机导致数据不可用的风险 -- `pd-recover` 移除 max-replica 参数 -- 增加 `Filter` 相关的 metrics -- 修复 tikv-ctl unsafe recovery 之后 Region 信息没更新的问题 -- 修复某些场景下副本迁移导致 TiKV 磁盘空间耗尽的问题 -- 兼容性提示 - - 由于新版本存储引擎更新，不支持在升级后回退至 2.0.x 或更旧版本 - - 新版本默认开启 `raft learner` 功能，如果从 1.x 版本集群升级至 2.1 版本，须停机升级或者先滚动升级 TiKV，完成后再滚动升级 PD - -## TiKV - -- 升级 Rust 到 `nightly-2018-06-14` 版本 -- 开启 `PreVote`，避免网络隔离后恢复时产生的重新选举 -- 添加 metric，显示 RocksDB 内部每层的文件数和 `ingest` 相关的信息 -- GC 运行时打印版本太多的 `key` -- 使用 `static metric` 优化多 label metric 性能（YCSB raw get 提升 3%） -- 去掉多个模块的 `box`，使用范型提升运行时性能（YCSB raw get 提升 3%） -- 使用 `asynchronous log` 提升写日志性能 -- 增加收集线程状态的 metric -- 通过减少程序中 `box` 的使用来减少内存拷贝的次数，提升性能 diff --git a/v3.1/releases/21rc1.md b/v3.1/releases/21rc1.md deleted file mode 100644 index eb077d0078db..000000000000 --- a/v3.1/releases/21rc1.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: TiDB 2.1 RC1 Release Notes -category: Releases ---- - -# TiDB 2.1 RC1 Release Notes - -2018 年 8 月 24 日，TiDB 发布 2.1 RC1 版。相比 2.1 Beta 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 修复某些情况下关联子查询去关联后结果不正确的问题 [#6972](https://github.com/pingcap/tidb/pull/6972) - - 优化 `Explain` 输出结果 [#7011](https://github.com/pingcap/tidb/pull/7011)[#7041](https://github.com/pingcap/tidb/pull/7041) - - 优化 `IndexJoin` 驱动表选择策略[#7019](https://github.com/pingcap/tidb/pull/7019) - - 去掉非 `PREPARE` 语句的 Plan Cache [#7040](https://github.com/pingcap/tidb/pull/7040) - - 修复某些情况下 `INSERT` 语句无法正常解析执行的问题 [#7068](https://github.com/pingcap/tidb/pull/7068) - - 修复某些情况下 `IndexJoin` 结果不正确的问题 [#7150](https://github.com/pingcap/tidb/pull/7150) - - 修复某些情况下使用唯一索引不能查询到 `NULL` 值的问题 [#7163](https://github.com/pingcap/tidb/pull/7163) - - 修复 UTF-8 编码情况下前缀索引的范围计算不正确的问题 [#7194](https://github.com/pingcap/tidb/pull/7194) - - 修复某些情况下 `Project` 算子消除导致的结果不正确的问题 [#7257](https://github.com/pingcap/tidb/pull/7257) - - 修复主键为整数类型时无法使用 `USE INDEX(PRIMARY)` 的问题 [#7316](https://github.com/pingcap/tidb/pull/7316) - - 修复某些情况下使用关联列无法计算索引范围的问题 [#7357](https://github.com/pingcap/tidb/pull/7357) -- SQL 执行引擎 - - 修复某些情况下夏令时时间计算结果不正确的问题 [#6823](https://github.com/pingcap/tidb/pull/6823) - - 重构聚合函数框架，提升 `Stream` 和 `Hash` 聚合算子的执行效率 [#6852](https://github.com/pingcap/tidb/pull/6852) - - 修复某些情况下 `Hash` 聚合算子不能正常退出的问题 [#6982](https://github.com/pingcap/tidb/pull/6982) - - 修复 `BIT_AND`/`BIT_OR`/`BIT_XOR` 没有正确处理非整型数据的问题 [#6994](https://github.com/pingcap/tidb/pull/6994) - - 优化 `REPLACE INTO` 语句的执行速度，性能提升近 10 倍 [#7027](https://github.com/pingcap/tidb/pull/7027) - - 优化时间类型的内存占用，时间类型数据的内存使用降低为原来的一半 [#7043](https://github.com/pingcap/tidb/pull/7043) - - 修复 `UNION` 语句整合有符号和无符号型整数结果时与 MySQL 不兼容的问题 [#7112](https://github.com/pingcap/tidb/pull/7112) - - 修复 `LPAD`/`RPAD`/`TO_BASE64`/`FROM_BASE64`/`REPEAT` 因为申请过多内存导致 TiDB panic 的问题 [#7171](https://github.com/pingcap/tidb/pull/7171) [#7266](https://github.com/pingcap/tidb/pull/7266) [#7409](https://github.com/pingcap/tidb/pull/7409) [#7431](https://github.com/pingcap/tidb/pull/7431) - - 修复 `MergeJoin`/`IndexJoin` 在处理 `NULL` 值时结果不正确的问题 [#7255](https://github.com/pingcap/tidb/pull/7255) - - 修复某些情况下 Outer Join 结果不正确的问题 [#7288](https://github.com/pingcap/tidb/pull/7288) - - 增强 `Data Truncated` 的报错信息，便于定位出错的数据和表中对应的字段 [#7401](https://github.com/pingcap/tidb/pull/7401) - - 修复某些情况下 Decimal 计算结果不正确的问题 [#7001](https://github.com/pingcap/tidb/pull/7001) [#7113](https://github.com/pingcap/tidb/pull/7113) [#7202](https://github.com/pingcap/tidb/pull/7202) [#7208](https://github.com/pingcap/tidb/pull/7208) - - 优化点查的查询性能 [#6937](https://github.com/pingcap/tidb/pull/6937) - - 禁用 `Read Committed` 隔离级别，避免潜在的问题 [#7211](https://github.com/pingcap/tidb/pull/7211) - - 修复某些情况下 `LTRIM`/`RTRIM`/`TRIM` 结果不正确的问题 [#7291](https://github.com/pingcap/tidb/pull/7291) - - 修复 `MaxOneRow` 算子无法保证返回结果不超过 1 行的问题 [#7375](https://github.com/pingcap/tidb/pull/7375) - - 拆分 range 个数过多的 Coprocessor 请求 [#7454](https://github.com/pingcap/tidb/pull/7454) -- 统计信息 - - 优化统计信息动态收集机制 [#6796](https://github.com/pingcap/tidb/pull/6796) - - 解决数据频繁更新场景下 `Auto Analyze` 不工作的问题 [#7022](https://github.com/pingcap/tidb/pull/7022) - - 减少统计信息动态更新过程中的写入冲突 [#7124](https://github.com/pingcap/tidb/pull/7124) - - 优化统计信息不准确情况下的代价估算 [#7175](https://github.com/pingcap/tidb/pull/7175) - - 优化 `AccessPath` 的代价估算策略 [#7233](https://github.com/pingcap/tidb/pull/7233) -- Server - - 修复加载权限信息时的 bug [#6976](https://github.com/pingcap/tidb/pull/6976) - - 修复 `Kill` 命令对权限的检查过严问题 [#6954](https://github.com/pingcap/tidb/pull/6954) - - 解决 Binary 协议中某些数值类型移除的问题 [#6922](https://github.com/pingcap/tidb/pull/6922) - - 精简日志输出 [#7029](https://github.com/pingcap/tidb/pull/7029) - - 处理 `mismatchClusterID` 问题 [#7053](https://github.com/pingcap/tidb/pull/7053) - - 增加 `advertise-address` 配置项 [#7078](https://github.com/pingcap/tidb/pull/7078) - - 增加 `GrpcKeepAlive` 选项 [#7100](https://github.com/pingcap/tidb/pull/7100) - - 增加连接或者 `Token` 时间监控 [#7110](https://github.com/pingcap/tidb/pull/7110) - - 优化数据解码性能 [#7149](https://github.com/pingcap/tidb/pull/7149) - - `INFORMMATION_SCHEMA` 中增加 `PROCESSLIST` 表 [#7236](https://github.com/pingcap/tidb/pull/7236) - - 解决权限验证时多条规则可以命中情况下的顺序问题 [#7211](https://github.com/pingcap/tidb/pull/7211) - - 将部分编码相关的系统变量默认值改为 UTF-8 [#7198](https://github.com/pingcap/tidb/pull/7198) - - 慢查询日志显示更详细的信息 [#7302](https://github.com/pingcap/tidb/pull/7302) - - 支持在 PD 注册 tidb-server 的相关信息并通过 HTTP API 获取 [#7082](https://github.com/pingcap/tidb/pull/7082) -- 兼容性 - - 支持 `Session` 变量 `warning_count` 和 `error_count` [#6945](https://github.com/pingcap/tidb/pull/6945) - - 读取系统变量时增加 Scope 检查 [#6958](https://github.com/pingcap/tidb/pull/6958) - - 支持 `MAX_EXECUTION_TIME` 语法 [#7012](https://github.com/pingcap/tidb/pull/7012) - - 支持更多的 `SET` 语法 [#7020](https://github.com/pingcap/tidb/pull/7020) - - Set 系统变量值过程中增加合法性校验 [#7117](https://github.com/pingcap/tidb/pull/7117) - - 增加 `Prepare` 语句中 `PlaceHolder` 数量的校验 [#7162](https://github.com/pingcap/tidb/pull/7162) - - 支持 `set character_set_results = null` [#7353](https://github.com/pingcap/tidb/pull/7353) - - 支持 `flush status` 语法 [#7369](https://github.com/pingcap/tidb/pull/7369) - - 修复 `SET` 和 `ENUM` 类型在 `information_schema` 里的 column size [#7347](https://github.com/pingcap/tidb/pull/7347) - - 支持建表语句里的 `NATIONAL CHARACTER` 语法 [#7378](https://github.com/pingcap/tidb/pull/7378) - - 支持 `LOAD DATA` 语句的 `CHARACTER SET` 语法 [#7391](https://github.com/pingcap/tidb/pull/7391) - - 修复 `SET` 和 `ENUM` 类型的 column info [#7417](https://github.com/pingcap/tidb/pull/7417) - - 支持 `CREATE USER` 语句的 `IDENTIFIED WITH` 语法 [#7402](https://github.com/pingcap/tidb/pull/7402) - - 修复 `TIMESTAMP` 类型计算过程中丢失精度的问题 [#7418](https://github.com/pingcap/tidb/pull/7418) - - 支持更多 `SYSTEM` 变量的合法性验证 [#7196](https://github.com/pingcap/tidb/pull/7196) - - 修复 `CHAR_LENGTH` 函数在计算 binary string 时结果不正确的问题 [#7410](https://github.com/pingcap/tidb/pull/7410) - - 修复在包含 `GROUP BY` 的语句里 `CONCAT` 结果不正确的问题 [#7448](https://github.com/pingcap/tidb/pull/7448) - - 修复 `DECIMAL` 类型 CAST 到 `STRING` 类型时，类型长度不准确的问题 [#7451](https://github.com/pingcap/tidb/pull/7451) -- DML - - 解决 `Load Data` 语句的稳定性 [#6927](https://github.com/pingcap/tidb/pull/6927) - - 解决一些 `Batch` 操作情况下的内存使用问题 [#7086](https://github.com/pingcap/tidb/pull/7086) - - 提升 `Replace Into` 语句的性能 [#7027](https://github.com/pingcap/tidb/pull/7027) - - 修复写入 `CURRENT_TIMESTAMP` 时，精度不一致的问题 [#7355](https://github.com/pingcap/tidb/pull/7355) -- DDL - - 改进 DDL 判断 `Schema` 是否已经同步的方法, 避免某些情况下的误判 [#7319](https://github.com/pingcap/tidb/pull/7319) - - 修复在 `ADD INDEX` 过程中的 `SHOW CREATE TABLE` 结果 [#6993](https://github.com/pingcap/tidb/pull/6993) - - 非严格 `sql-mode` 模式下, `text`/`blob`/`json` 的默认值可以为空 [#7230](https://github.com/pingcap/tidb/pull/7230) - - 修复某些特定场景下 `ADD INDEX` 的问题 [#7142](https://github.com/pingcap/tidb/pull/7142) - - 大幅度提升添加 `UNIQUE-KEY` 索引操作的速度 [#7132](https://github.com/pingcap/tidb/pull/7132) - - 修复 Prefix-index 在 UTF-8 字符集的场景下的截断问题 [#7109](https://github.com/pingcap/tidb/pull/7109) - - 增加环境变量 `tidb_ddl_reorg_priority` 来控制 `add-index` 操作的优先级 [#7116](https://github.com/pingcap/tidb/pull/7116) - - 修复 `information_schema.tables` 中 `AUTO-INCREMENT` 的显示问题 [#7037](https://github.com/pingcap/tidb/pull/7037) - - 支持 `admin show ddl jobs ` 命令, 支持输出 number 个 DDL jobs [#7028](https://github.com/pingcap/tidb/pull/7028) - - 支持并行 DDL 任务执行 [#6955](https://github.com/pingcap/tidb/pull/6955) -- [Table Partition](https://github.com/pingcap/tidb/projects/6)（实验性） - - 支持一级分区 - - 支持 `Range Partition` - -## PD - -- 新特性 - - 引入版本控制机制，支持集群滚动兼容升级 - - 开启 `Region merge` 功能 - - 支持 `GetPrevRegion` 接口 - - 支持批量 `split Region` - - 支持存储 GC safepoint -- 功能改进 - - 优化系统时间回退影响 TSO 分配的问题 - - 优化处理 Region heartbeat 的性能 - - 优化 Region tree 性能 - - 优化计算热点统计的性能问题 - - 优化 API 接口错误码返回 - - 新增一些控制调度策略的开关 - - 禁止在 `label` 中使用特殊字符 - - 完善调度模拟器 - - pd-ctl 支持使用统计信息进行 Region split - - pd-ctl 支持调用 `jq` 来格式化 JSON 输出 - - 新增 etcd Raft 状态机相关 metrics -- Bug 修复 - - 修复 leader 切换后 namespace 未重新加载的问题 - - 修复 namespace 调度超出 schedule limit 配置的问题 - - 修复热点调度超出 schedule limit 的问题 - - 修复 PD client 关闭时输出一些错误日志的问题 - - 修复 Region 心跳延迟统计有误的问题 - -## TiKV - -- 新特性 - - 支持 `batch split`，防止热点 Region 写入产生超大 Region - - 支持设置根据数据行数 split Region，提升 index scan 效率 -- 性能优化 - - 使用 `LocalReader` 将 Read 操作从 raftstore 线程分离，减少 Read 延迟 - - 重构 MVCC 框架，优化 memory 使用，提升 scan read 性能 - - 支持基于统计估算进行 Region split，减少 I/O 开销 - - 优化连续写入 Rollback 记录后影响读性能的问题 - - 减少下推聚合计算的内存开销 -- 功能改进 - - 增加大量内建函数下推支持，更完善的 charset 支持 - - 优化 GC 流程，提升 GC 速度并降低 GC 对系统的影响 - - 开启 `prevote`，加快网络异常时的恢复服务速度 - - 增加 RocksDB 日志文件相关的配置项 - - 调整 `scheduler latch` 默认配置 - - 使用 tikv-ctl 手动 compact 时可设定是否 compact RocksDB 最底层数据 - - 增加启动时的环境变量检查 - - 支持基于已有数据动态设置 `dynamic_level_bytes` 参数 - - 支持自定义日志格式 - - tikv-ctl 整合 tikv-fail 工具 - - 增加 threads IO metrics -- Bug 修复 - - 修复 decimal 相关问题 - - 修复 `gRPC max_send_message_len` 设置有误的问题 - - 修复 `region_size` 配置不当时产生的问题 diff --git a/v3.1/releases/21rc2.md b/v3.1/releases/21rc2.md deleted file mode 100644 index 426e4289e60d..000000000000 --- a/v3.1/releases/21rc2.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: TiDB 2.1 RC2 Release Notes -category: Releases ---- - -# TiDB 2.1 RC2 Release Notes - -2018 年 9 月 14 日，TiDB 发布 2.1 RC2 版。相比 2.1 RC1 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -- SQL 优化器 - - 新版 Planner 设计方案 [#7543](https://github.com/pingcap/tidb/pull/7543) - - 提升常量传播优化规则 [#7276](https://github.com/pingcap/tidb/pull/7276) - - 增强 Range 的计算逻辑使其能够同时处理多个 `IN` 或者等值条件 [#7577](https://github.com/pingcap/tidb/pull/7577) - - 修复当 Range 为空时，`TableScan` 的估算结果不正确的问题 [#7583](https://github.com/pingcap/tidb/pull/7583) - - 为 `UPDATE` 语句支持 `PointGet` 算子 [#7586](https://github.com/pingcap/tidb/pull/7586) - - 修复 `FirstRow` 聚合函数某些情况下在执行过程中 panic 的问题 [#7624](https://github.com/pingcap/tidb/pull/7624) -- SQL 执行引擎 - - 解决 HashJoin 算子在遇到错误的情况下潜在的 DataRace 问题 [#7554](https://github.com/pingcap/tidb/pull/7554) - - HashJoin 算子同时读取内表数据和构建 Hash 表 [#7544](https://github.com/pingcap/tidb/pull/7544) - - 优化 Hash 聚合算子性能 [#7541](https://github.com/pingcap/tidb/pull/7541) - - 优化 Join 算子性能 [#7493](https://github.com/pingcap/tidb/pull/7493)、[#7433](https://github.com/pingcap/tidb/pull/7433) - - 修复 `UPDATE JOIN` 在 Join 顺序改变后结果不正确的问题 [#7571](https://github.com/pingcap/tidb/pull/7571) - - 提升 Chunk 迭代器的性能 [#7585](https://github.com/pingcap/tidb/pull/7585) -- 统计信息 - - 解决重复自动 Analyze 统计信息的问题 [#7550](https://github.com/pingcap/tidb/pull/7550) - - 解决统计信息无变化时更新统计信息遇到错误的问题 [#7530](https://github.com/pingcap/tidb/pull/7530) - - `Analyze` 执行时使用低优先级以及 RC 隔离级别 [#7496](https://github.com/pingcap/tidb/pull/7496) - - 支持只在一天中的某个时间段开启统计信息自动更新的功能 [#7570](https://github.com/pingcap/tidb/pull/7570) - - 修复统计信息写日志时发生的 panic [#7588](https://github.com/pingcap/tidb/pull/7588) - - 支持通过 `ANALYZE TABLE WITH BUCKETS` 语句配置直方图中桶的个数 [#7619](https://github.com/pingcap/tidb/pull/7619) - - 修复更新空的直方图时 panic 的问题 [#7640](https://github.com/pingcap/tidb/pull/7640) - - 使用统计信息更新 `information_schema.tables.data_length` [#7657](https://github.com/pingcap/tidb/pull/7657) -- Server - - 增加 Trace 相关的依赖库 [#7532](https://github.com/pingcap/tidb/pull/7532) - - 开启 Golang 的 mutex profile 功能 [#7512](https://github.com/pingcap/tidb/pull/7512) - - `Admin` 语句需要 `Super_priv` 权限 [#7486](https://github.com/pingcap/tidb/pull/7486) - - 禁止用户 Drop 关键的系统表 [#7471](https://github.com/pingcap/tidb/pull/7471) - - 从 `juju/errors` 切换到 `pkg/errors` [#7151](https://github.com/pingcap/tidb/pull/7151) - - 完成 SQL Tracing 功能原型 [#7016](https://github.com/pingcap/tidb/pull/7016) - - 删除 goroutine pool [#7564](https://github.com/pingcap/tidb/pull/7564) - - 支持使用 `USER1` 信号来查看 goroutine 信息 [#7587](https://github.com/pingcap/tidb/pull/7587) - - 将 TiDB 启动时的内部 SQL 设置为高优先级 [#7616](https://github.com/pingcap/tidb/pull/7616) - - 在监控中用不同的标签区分内部 SQL 和用户 SQL [#7631](https://github.com/pingcap/tidb/pull/7631) - - 缓存最近一周内最慢的 30 条慢查询日志在 TiDB Server 上 [#7646](https://github.com/pingcap/tidb/pull/7646) - - TiDB 集群设置时区的方案 [#7656](https://github.com/pingcap/tidb/pull/7656) - - 丰富 `GC life time is shorter than transaction duration` 错误信息 [#7658](https://github.com/pingcap/tidb/pull/7658) - - 在 TiDB 集群启动时设置集群时区信息 [#7638](https://github.com/pingcap/tidb/pull/7638) -- 兼容性 - - `Year` 类型字段增加 unsigned flag [#7542](https://github.com/pingcap/tidb/pull/7542) - - 修复在 Prepare/Execute 模式下，`Year` 类型结果长度设置问题 [#7525](https://github.com/pingcap/tidb/pull/7525) - - 修复 Prepare/Execute 模式下时间 0 值的处理问题 [#7506](https://github.com/pingcap/tidb/pull/7506) - - 解决整数类型除法实现中的错误处理问题 [#7492](https://github.com/pingcap/tidb/pull/7492) - - 解决 `ComStmtSendLongData` 处理过程中的兼容性问题 [#7485](https://github.com/pingcap/tidb/pull/7485) - - 解决字符串转为整数类型过程中的错误处理问题 [#7483](https://github.com/pingcap/tidb/pull/7483) - - 优化 `information_schema.columns_in_table` 表中的值精度 [#7463](https://github.com/pingcap/tidb/pull/7463) - - 修复使用 MariaDB 客户端对字符串类型数据的写入和更新的兼容性问题 [#7573](https://github.com/pingcap/tidb/pull/7573) - - 修复返回值别名的兼容性问题 [#7600](https://github.com/pingcap/tidb/pull/7600) - - 修复 `information_schema.COLUMNS` 表中浮点数的 `NUMERIC_SCALE` 值不正确的问题 [#7602](https://github.com/pingcap/tidb/pull/7602) - - 解决单行注释内容为空 Parser 报错的问题 [#7612](https://github.com/pingcap/tidb/pull/7612) -- 表达式 - - 在 `insert` 函数中检查 `max_allowed_packet` 的值 [#7528](https://github.com/pingcap/tidb/pull/7528) - - 支持内建函数 `json_contains` [#7443](https://github.com/pingcap/tidb/pull/7443) - - 支持内建函数 `json_contains_path` [#7596](https://github.com/pingcap/tidb/pull/7596) - - 支持内建函数 `encode/decode` [#7622](https://github.com/pingcap/tidb/pull/7622) - - 修复一些时间相关的函数在某些情况下和 MySQL 行为不兼容的问题 [#7636](https://github.com/pingcap/tidb/pull/7636) - - 解决从字符串中解析时间类型数据的兼容性问题 [#7654](https://github.com/pingcap/tidb/pull/7654) - - 解决计算 `DateTime` 类型数据的默认值时没有考虑时区的问题 [#7655](https://github.com/pingcap/tidb/pull/7655) -- DML - - `InsertOnDuplicateUpdate` 语句设置正确的 `last_insert_id` [#7534](https://github.com/pingcap/tidb/pull/7534) - - 减少需要更新 `auto_increment_id` 计数器的情况 [#7515](https://github.com/pingcap/tidb/pull/7515) - - 优化 `Duplicate Key` 错误的报错信息 [#7495](https://github.com/pingcap/tidb/pull/7495) - - 修复 `insert...select...on duplicate key update` 问题 [#7406](https://github.com/pingcap/tidb/pull/7406) - - 支持 `LOAD DATA IGNORE LINES` 语句 [#7576](https://github.com/pingcap/tidb/pull/7576) -- DDL - - 在监控中增加 DDL Job 的类型和当前 Schema 版本的信息 [#7472](https://github.com/pingcap/tidb/pull/7472) - - 完成 `Admin Restore Table` 功能方案设计 [#7383](https://github.com/pingcap/tidb/pull/7383) - - 解决 Bit 类型的默认值超过 128 的问题 [#7249](https://github.com/pingcap/tidb/pull/7249) - - 解决 Bit 类型默认值不能为 `NULL` 的问题 [#7604](https://github.com/pingcap/tidb/pull/7604) - - 减少 DDL 队列中检查 `CREATE TABLE/DATABASE` 任务的时间间隔 [#7608](https://github.com/pingcap/tidb/pull/7608) - - 使用 `ddl/owner/resign` HTTP 接口释放 DDL Owner 并开启新一轮 Owner 选举 [#7649](https://github.com/pingcap/tidb/pull/7649) -- TiKV Go Client - - 支持 `Seek` 操作只获取 `Key` [#7419](https://github.com/pingcap/tidb/pull/7419) -- [Table Partition](https://github.com/pingcap/tidb/projects/6)（实验性） - - 解决无法使用 Bigint 类型列作为 Partition Key 的问题 [#7520](https://github.com/pingcap/tidb/pull/7520) - - 支持 Partitioned Table 添加索引过程中遇到问题回滚操作 [#7437](https://github.com/pingcap/tidb/pull/7437) - -## PD - -- 新特性 - - 支持 `GetAllStores`的接口 [#1228](https://github.com/pingcap/pd/pull/1228) - - Simulator 添加评估调度的统计信息 [#1218](https://github.com/pingcap/pd/pull/1218) -- 功能改进 - - 优化 Down Store 的处理流程，尽快地补副本 [#1222](https://github.com/pingcap/pd/pull/1222) - - 优化 Coordinator 的启动，减少重启 PD 带来的不必要调度 [#1225](https://github.com/pingcap/pd/pull/1225) - - 优化内存使用，减少 heartbeat 带来的内存开销 [#1195](https://github.com/pingcap/pd/pull/1195) - - 优化错误处理，完善日志信息 [#1227](https://github.com/pingcap/pd/pull/1227) - - pd-ctl 支持查询指定 store 的 Region 信息 [#1231](https://github.com/pingcap/pd/pull/1231) - - pd-ctl 支持查询按 version 比对的 topN 的 Region 信息 [#1233](https://github.com/pingcap/pd/pull/1233) - - pd-ctl 支持更精确的 TSO 解码 [#1242](https://github.com/pingcap/pd/pull/1242) -- Bug 修复 - - 修复 pd-ctl 使用 hot store 命令错误退出的问题 [#1244](https://github.com/pingcap/pd/pull/1244) - -## TiKV - -- 性能优化 - - 支持基于统计估算进行 Region split，减少 I/O 开销 [#3511](https://github.com/tikv/tikv/pull/3511) - - 减少部分组件的内存拷贝 [#3530](https://github.com/tikv/tikv/pull/3530) -- 功能改进 - - 增加大量内建函数下推支持 - - 增加 `leader-transfer-max-log-lag` 配置解决特定场景 leader 调度失败的问题 [#3507](https://github.com/tikv/tikv/pull/3507) - - 增加 `max-open-engines` 配置限制 `tikv-importer` 同时打开的 engine 个数 [#3496](https://github.com/tikv/tikv/pull/3496) - - 限制垃圾数据的清理速度，减少对 `snapshot apply` 的影响 [#3547](https://github.com/tikv/tikv/pull/3547) - - 对关键 Raft 消息广播 commit 信息，避免不必要的延迟 [#3592](https://github.com/tikv/tikv/pull/3592) -- Bug 修复 - - 修复新分裂 Region 的 PreVote 消息被丢弃导致的 leader 选举问题 [#3557](https://github.com/tikv/tikv/pull/3557) - - 修复 Region merge 以后 follower 的相关统计信息 [#3573](https://github.com/tikv/tikv/pull/3573) - - 修复 local reader 使用过期 Region 信息的问题 [#3565](https://github.com/tikv/tikv/pull/3565) diff --git a/v3.1/releases/21rc3.md b/v3.1/releases/21rc3.md deleted file mode 100644 index 04170e77ceac..000000000000 --- a/v3.1/releases/21rc3.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: TiDB 2.1 RC3 Release Notes -category: Releases ---- - -# TiDB 2.1 RC3 Release Notes - -2018 年 9 月 29 日，TiDB 发布 2.1 RC3 版。相比 2.1 RC2 版本，该版本对系统稳定性、兼容性、优化器以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复语句内包含内嵌的 `LEFT OUTER JOIN` 时，结果不正确的问题 [#7689](https://github.com/pingcap/tidb/pull/7689) - - 增强 `JOIN` 语句上的 predicate pushdown 优化规则 [#7645](https://github.com/pingcap/tidb/pull/7645) - - 修复 `UnionScan` 算子的 predicate pushdown 优化规则 [#7695](https://github.com/pingcap/tidb/pull/7695) - - 修复 `Union` 算子的 unique key 属性设置不正确的问题 [#7680](https://github.com/pingcap/tidb/pull/7680) - - 增强常量折叠的优化规则 [#7696](https://github.com/pingcap/tidb/pull/7696) - - 把常量传播后的 filter 是 null 的 data source 优化成 table dual [#7756](https://github.com/pingcap/tidb/pull/7756) -+ SQL 执行引擎 - - 优化事务内读请求的性能 [#7717](https://github.com/pingcap/tidb/pull/7717) - - 优化部分执行器 Chunk 内存分配的开销 [#7540](https://github.com/pingcap/tidb/pull/7540) - - 修复点查全部为 NULL 的列导致数组越界的问题 [#7790](https://github.com/pingcap/tidb/pull/7790) -+ Server - - 修复配置文件里内存配额选项不生效的问题 [#7729](https://github.com/pingcap/tidb/pull/7729) - - 添加 tidb_force_priority 系统变量用来整体设置语句执行的优先级 [#7694](https://github.com/pingcap/tidb/pull/7694) - - 支持使用 `admin show slow` 语句来获取 SLOW QUERY LOG [#7785](https://github.com/pingcap/tidb/pull/7785) -+ 兼容性 - - 修复 `information_schema.schemata` 里 `charset/collation` 结果不正确的问题 [#7751](https://github.com/pingcap/tidb/pull/7751) - - 修复 `hostname` 系统变量的值为空的问题 [#7750](https://github.com/pingcap/tidb/pull/7750) -+ 表达式 - - 内建函数 `AES_ENCRYPT/AES_DECRYPT` 支持 `init_vecter` 参数 [#7425](https://github.com/pingcap/tidb/pull/7425) - - 修复部分表达式 `Format` 结果不正确的问题 [#7770](https://github.com/pingcap/tidb/pull/7770) - - 支持内建函数 `JSON_LENGTH` [#7739](https://github.com/pingcap/tidb/pull/7739) - - 修复 unsigned integer 类型 cast 为 decimal 类型结果不正确的问题 [#7792](https://github.com/pingcap/tidb/pull/7792) -+ DML - - 修复 `INSERT … ON DUPLICATE KEY UPDATE` 语句在 unique key 更新时结果不正确的问题 [#7675](https://github.com/pingcap/tidb/pull/7675) -+ DDL - - 修复在新建的 timestamp 类型的列上新建索引时，索引值没有做时区转换的问题 [#7724](https://github.com/pingcap/tidb/pull/7724) - - 支持 enum 类型 append 新的值 [#7767](https://github.com/pingcap/tidb/pull/7767) - - 快速新建 etcd session，使网络隔离后，集群更快恢复可用 [#7774](https://github.com/pingcap/tidb/pull/7774) - -## PD - -+ 新特性 - - 添加获取按大小逆序排序的 Region 列表 API (/size) [#1254](https://github.com/pingcap/pd/pull/1254) -+ 功能改进 - - Region API 会返回更详细的信息 [#1252](https://github.com/pingcap/pd/pull/1252) -+ Bug 修复 - - 修复 PD 切换 leader 以后 `adjacent-region-scheduler` 可能会导致 crash 的问题 [#1250](https://github.com/pingcap/pd/pull/1250) - -## TiKV - -+ 性能优化 - - 优化函数下推的并发支持 [#3515](https://github.com/tikv/tikv/pull/3515) -+ 新特性 - - 添加对 Log 函数的支持 [#3603](https://github.com/tikv/tikv/pull/3603) - - 添加对 `sha1` 函数的支持 [#3612](https://github.com/tikv/tikv/pull/3612) - - 添加 `truncate_int` 函数的支持 [#3532](https://github.com/tikv/tikv/pull/3532) - - 添加 `year` 函数的支持 [#3622](https://github.com/tikv/tikv/pull/3622) - - 添加 `truncate_real` 函数的支持 [#3633](https://github.com/tikv/tikv/pull/3633) -+ Bug 修复 - - 修正时间函数相关的报错行为 [#3487](https://github.com/tikv/tikv/pull/3487) [#3615](https://github.com/tikv/tikv/pull/3615) - - 修复字符串解析成时间与 TiDB 不一致的问题 [#3589](https://github.com/tikv/tikv/pull/3589) \ No newline at end of file diff --git a/v3.1/releases/21rc4.md b/v3.1/releases/21rc4.md deleted file mode 100644 index 6a46324f7c82..000000000000 --- a/v3.1/releases/21rc4.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: TiDB 2.1 RC4 Release Notes -category: Releases ---- - -# TiDB 2.1 RC4 Release Notes - -2018 年 10 月 23 日，TiDB 发布 2.1 RC4 版。相比 2.1 RC3 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复某些情况下 `UnionAll` 的列裁剪不正确的问题 [#7941](https://github.com/pingcap/tidb/pull/7941) - - 修复某些情况下 `UnionAll` 算子结果不正确的问题 [#8007](https://github.com/pingcap/tidb/pull/8007) -+ SQL 执行引擎 - - 修复 `AVG` 函数的精度问题 [#7874](https://github.com/pingcap/tidb/pull/7874) - - 支持通过 `EXPLAIN ANALYZE` 语句查看 Query 执行过程中各个算子的运行时间，返回结果行数等运行时统计信息 [#7925](https://github.com/pingcap/tidb/pull/7925) - - 修复多次引用同一列时 `PointGet` 算子 panic 的问题 [#7943](https://github.com/pingcap/tidb/pull/7943) - - 修复当 `Limit` 子句中的值太大时 panic 的问题 [#8002](https://github.com/pingcap/tidb/pull/8002) - - 修复某些情况下 `AddDate`/`SubDate` 执行过程中 panic 的问题 [#8009](https://github.com/pingcap/tidb/pull/8009) -+ 统计信息 - - 修复将组合索引的直方图下边界前缀判断为越界的问题 [#7856](https://github.com/pingcap/tidb/pull/7856) - - 修复统计信息收集引发的内存泄漏问题 [#7873](https://github.com/pingcap/tidb/pull/7873) - - 修复直方图为空时 panic 的问题 [#7928](https://github.com/pingcap/tidb/pull/7928) - - 修复加载统计信息时直方图边界越界的问题 [#7944](https://github.com/pingcap/tidb/pull/7944) - - 限制统计信息采样过程中数值的最大长度 [#7982](https://github.com/pingcap/tidb/pull/7982) -+ Server - - 重构 Latch，避免事务冲突误判，提升并发事务的执行性能 [#7711](https://github.com/pingcap/tidb/pull/7711) - - 修复某些情况下收集 Slow Query 导致的 panic 问题 [#7874](https://github.com/pingcap/tidb/pull/7847) - - 修复 `LOAD DATA` 语句中，`ESCAPED BY` 为空字符串时 panic 的问题 [#8005](https://github.com/pingcap/tidb/pull/8005) - - 完善 “coprocessor error” 日志信息 [#8006](https://github.com/pingcap/tidb/pull/8006) -+ 兼容性 - - 当 Query 为空时，将 `SHOW PROCESSLIST` 结果中的 `Command` 字段设置为 “Sleep” [#7839](https://github.com/pingcap/tidb/pull/7839) -+ 表达式 - - 修复 `SYSDATE` 函数被常量折叠的问题 [#7895](https://github.com/pingcap/tidb/pull/7895) - - 修复 `SUBSTRING_INDEX` 在某些情况下 panic 的问题 [#7897](https://github.com/pingcap/tidb/pull/7897) -+ DDL - - 修复抛出 “invalid ddl job type” 的错误时导致栈溢出的问题 [#7958](https://github.com/pingcap/tidb/pull/7958) - - 修复某些情况下 `ADMIN CHECK TABLE` 结果不正确的问题 [#7975](https://github.com/pingcap/tidb/pull/7975) - -## PD - -- 修复下线后的 TiKV 没有从 Grafana 面板中移除的问题 [#1261](https://github.com/pingcap/pd/pull/1261) -- 修复 grpc-go 设置 status 时的 data race 问题[#1265](https://github.com/pingcap/pd/pull/1265) -- 修复 etcd 启动失败导致的服务挂起问题 [#1267](https://github.com/pingcap/pd/pull/1267) -- 修复 leader 切换过程中可能产生的 data race [#1273](https://github.com/pingcap/pd/pull/1273) -- 修复下线 TiKV 时可能输出多余 warning 日志的问题 [#1280](https://github.com/pingcap/pd/pull/1273) - -## TiKV - -- 优化 apply snapshot 导致的 RocksDB Write stall 的问题 [#3606](https://github.com/tikv/tikv/pull/3606) -- 增加 raftstore tick 相关 metrics [#3657](https://github.com/tikv/tikv/pull/3657) -- 升级 RocksDB，修复写入卡死及 IngestExternalFile 时可能写坏源文件的问题 [#3661](https://github.com/tikv/tikv/pull/3661) -- 升级 grpcio，修复 “too many pings” 误报的问题 [#3650](https://github.com/tikv/tikv/pull/3650) diff --git a/v3.1/releases/21rc5.md b/v3.1/releases/21rc5.md deleted file mode 100644 index 5439ec3dffc5..000000000000 --- a/v3.1/releases/21rc5.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: TiDB 2.1 RC5 Release Notes -category: Releases ---- - - - -# TiDB 2.1 RC5 Release Notes - -2018 年 11 月 12 日，TiDB 发布 2.1 RC5 版。相比 2.1 RC4 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 修复 `IndexReader` 在某些情况下读取的 handle 不正确的问题 [#8132](https://github.com/pingcap/tidb/pull/8132) - - 修复 `IndexScan Prepared` 语句在使用 `Plan Cache` 的时候的问题 [#8055](https://github.com/pingcap/tidb/pull/8055) - - 修复 `Union` 语句结果不稳定的问题 [#8165](https://github.com/pingcap/tidb/pull/8165) -+ 执行器 - - 提升 TiDB 插入和更新宽表的性能 [#8024](https://github.com/pingcap/tidb/pull/8024) - - 内建函数 `Truncate` 支持 unsigned `int` 参数 [#8068](https://github.com/pingcap/tidb/pull/8068) - - 修复转换 JSON 数据到 decimal 类型出错的问题 [#8109](https://github.com/pingcap/tidb/pull/8109) - - 修复 float 类型在 `Update` 时出错的问题 [#8170](https://github.com/pingcap/tidb/pull/8170) -+ 统计信息 - - 修复点查在某些情况下，统计信息出现错误的问题 [#8035](https://github.com/pingcap/tidb/pull/8035) - - 修复统计信息某些情况下在 primary key 的选择率的问题 [#8149](https://github.com/pingcap/tidb/pull/8149) - - 修复被删除的表的统计信息长时间没有清理的问题 [#8182](https://github.com/pingcap/tidb/pull/8182) -+ Server - + 提升日志的可读性，完善日志信息 - - [#8063](https://github.com/pingcap/tidb/pull/8063) - - [#8053](https://github.com/pingcap/tidb/pull/8053) - - [#8224](https://github.com/pingcap/tidb/pull/8224) - - 修复获取 `infoschema.profiling` 表数据出错的问题 [#8096](https://github.com/pingcap/tidb/pull/8096) - - 替换 unix socket，使用 pumps client 来写 binlog [#8098](https://github.com/pingcap/tidb/pull/8098) - - 增加环境变量 `tidb_slow_log_threshold` 动态设置 slow log 的阈值 [#8094](https://github.com/pingcap/tidb/pull/8094) - - 增加环境变量 `tidb_query_log_max_len` 动态设置日志中被截断的原始 SQL 语句的长度 [#8200](https://github.com/pingcap/tidb/pull/8200) - - 增加环境变量 `tidb_opt_write_row_id` 来控制是否允许写入 `_tidb_rowid` [#8218](https://github.com/pingcap/tidb/pull/8218) - - ticlient `Scan` 命令增加边界，解决数据扫出边界的问题 [#8081](https://github.com/pingcap/tidb/pull/8081)，[#8247](https://github.com/pingcap/tidb/pull/8247) -+ DDL - - 修复在事务中某些情况下执行 DDL 语句出错的问题 [#8056](https://github.com/pingcap/tidb/pull/8056) - - 修复 partition 分区表执行 `truncate table` 没有生效的问题 [#8103](https://github.com/pingcap/tidb/pull/8103) - - 修复某些情况下 DDL 操作在被 cancel 之后没有正确回滚的问题 [#8057](https://github.com/pingcap/tidb/pull/8057) - - 增加命令 `admin show next_row_id`，返回下一个可用的行 ID [#8268](https://github.com/pingcap/tidb/pull/8268) - -## PD - -+ 修复 `pd-ctl` 读取 Region key 的相关问题 - - [#1298](https://github.com/pingcap/pd/pull/1298) - - [#1299](https://github.com/pingcap/pd/pull/1299) - - [#1308](https://github.com/pingcap/pd/pull/1308) - -- 修复 `regions/check` API 输出错误的问题 [#1311](https://github.com/pingcap/pd/pull/1311) -- 修复 PD join 失败后无法重新 join 的问题 [#1279](https://github.com/pingcap/pd/pull/1279) -- 修复某些情况下 watch leader 会丢失事件的问题 [#1317](https://github.com/pingcap/pd/pull/1317) - -## TiKV - -- 优化 `WriteConflict` 报错信息 [#3750](https://github.com/tikv/tikv/pull/3750) -- 增加 panic 标记文件 [#3746](https://github.com/tikv/tikv/pull/3746) -- 降级 grpcio，避免新版本 gRPC 导致的 segment fault 问题 [#3650](https://github.com/tikv/tikv/pull/3650) -- 增加 `kv_scan` 接口扫描上界的限制 [#3749](https://github.com/tikv/tikv/pull/3749) - -## Tools - -- TiDB 支持 TiDB Binlog cluster，不兼容旧版本 TiDB Binlog [#8093](https://github.com/pingcap/tidb/pull/8093)，[使用文档](/v3.1/reference/tidb-binlog/overview.md) diff --git a/v3.1/releases/2rc1.md b/v3.1/releases/2rc1.md deleted file mode 100644 index 5df84ccb29ec..000000000000 --- a/v3.1/releases/2rc1.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 2.0 RC1 Release Notes -category: Releases ---- - -# TiDB 2.0 RC1 Release Notes - -2018 年 3 月 9 日，TiDB 发布 2.0 RC1 版。该版本在上一版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -+ 支持限制单条 SQL 语句使用内存的大小，减少程序 OOM 风险 -+ 支持下推流式聚合算子到 TiKV -+ 支持配置文件的合法性检测 -+ 支持 HTTP API 获取 TiDB 参数信息 -+ Parser 兼容更多 MySQL 语法 -+ 提升对 Navicat 的兼容性 -+ 优化器提升，提取多个 OR 条件的公共表达式，选取更优执行计划 -+ 优化器提升，在更多场景下将子查询转换成 Join 算子，选取更优查询计划 -+ 使用 Batch 方式 Resolve Lock，提升垃圾回收速度 -+ 修复 Boolean 类型的字段长度，提升兼容性 -+ 优化 Add Index 操作，所有的读写操作采用低优先级，减小对在线业务的影响 - -## PD - -+ 优化检查 Region 状态的代码逻辑，提升程序性能 -+ 优化异常情况下日志信息输出，便于调试 -+ 修复监控中关于 TiKV 节点磁盘空间不足情况的统计 -+ 修复开启 TLS 时健康检查接口误报的问题 -+ 修复同时添加副本数量可能超过配置阈值的问题，提升程序稳定性 - -## TiKV - -+ 修复 PD leader 切换，gRPC call 没被 cancel 的问题 -+ 对重要配置进行保护，第一次设置之后不允许变更 -+ 增加获取 metrics 的 gRPC API -+ 启动时候，检查是否使用 SSD -+ 使用 ReadPool 优化读性能，`raw get` 测试性能提升 30% -+ 完善 metrics，优化 metrics 的使用 \ No newline at end of file diff --git a/v3.1/releases/2rc3.md b/v3.1/releases/2rc3.md deleted file mode 100644 index 4489e7e0ab15..000000000000 --- a/v3.1/releases/2rc3.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: TiDB 2.0 RC3 Release Notes -category: Releases ---- - -# TiDB 2.0 RC3 Release Notes - -2018 年 3 月 23 日，TiDB 发布 2.0 RC3 版。该版本在 2.0 RC2 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 修复部分场景下 `MAX/MIN` 结果不正确的问题 -- 修复部分场景下 `Sort Merge Join` 结果未按照 Join Key 有序的问题 -- 修复边界条件下 `uint` 和 `int` 比较的错误 -- 完善浮点数类型的长度和精度检查，提升 MySQL 兼容性 -- 完善时间类型解析报错日志，添加更多错误信息 -- 完善内存控制，新增对 `IndexLookupExecutor` 的内存统计 -- 优化 `ADD INDEX` 的执行速度，部分场景下速度大幅度提升 -- `GROUP BY` 子句为空时使用 Stream Aggregation 算子，提升速度 -- 支持通过 `STRAIGHT_JOIN` 来关闭优化器的 `Join Reorder` 优化 -- `ADMIN SHOW DDL JOBS` 输出更详细的 DDL 任务状态信息 -- 支持 `ADMIN SHOW DDL JOB QUERIES` 查询当前正在运行的 DDL 任务的原始语句 -- 支持 `ADMIN RECOVER INDEX` 命令，用于灾难恢复情况下修复索引数据 -- `ADD INDEX` 操作变更为低优先级，降低对线上业务影响 -- 支持参数为 JSON 类型的 `SUM/AVG` 等聚合函数 -- 支持配置文件修改 `lower_case_table_names` 系统变量，用于支持 OGG 数据同步工具 -- 提升对 Navicat 管理工具的兼容性 -- 支持在 CRUD 操作中使用隐式的行 ID - -## PD - -- 支持 Region Merge，合并数据删除后产生的空 Region 或小 Region -- 添加副本时忽略有大量 pending peer 的节点，提升恢复副本及下线的速度 -- 优化有大量空 Region 时产生的频繁调度问题 -- 优化不同 label 中资源不均衡的场景中 leader balance 调度的速度 -- 添加更多异常 Region 的统计 - -## TiKV - -- 支持 Region Merge -- Raft snapshot 流程完成之后立刻通知 PD，加速调度 -- 增加 Raw DeleteRange API -- 增加 GetMetric API -- 减缓 RocksDB sync 文件造成的 I/O 波动 -- 优化了对 delete 掉数据的空间回收机制 -- 完善数据恢复工具 `tikv-ctl` -- 解决了由于 snapshot 导致下线节点慢的问题 -- Coprocessor 支持 streaming -- 支持 Readpool，`raw_get/get/batch_get` 性能提升 30% -- 支持配置 Coprocessor 请求超时时间 -- Coprocessor 支持 streaming aggregation -- 上报 Region heartbeat 时携带时间信息 -- 限制 snapshot 文件的空间使用，防止占用过多磁盘空间 -- 对长时间不能选出 leader 的 Region 进行记录上报 -- 加速启动阶段的垃圾清理工作 -- 根据 compaction 事件及时更新对应 Region 的 size 信息 -- 对 `scan lock` 的大小进行限制，防止请求超时 -- 使用 `DeleteRange` 加速 Region 删除 -- 支持在线修改 RocksDB 的参数 \ No newline at end of file diff --git a/v3.1/releases/2rc4.md b/v3.1/releases/2rc4.md deleted file mode 100644 index 9858c86e4959..000000000000 --- a/v3.1/releases/2rc4.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: TiDB 2.0 RC4 Release Notes -category: Releases ---- - -# TiDB 2.0 RC4 Release Notes - -2018 年 3 月 30 日，TiDB 发布 2.0 RC4 版。该版本在 2.0 RC3 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 支持 `SHOW GRANTS FOR CURRENT_USER();` -- 修复 `UnionScan` 里的 `Expression` 没有 Clone 的问题 -- 支持 `SET TRANSACTION` 语法 -- 修复 `copIterator` 中潜在的 goroutine 泄露问题 -- 修复 `admin check table` 对包含 null 的 unique index 误判的问题 -- 支持用科学计数法显示浮点数 -- 修复 binary literal 计算时的类型推导 -- 修复解析 `CREATE VIEW` 语句的问题 -- 修复语句中同时包含 `ORDER BY` 和 `LIMIT 0` 时 panic 的问题 -- 提升 `DecodeBytes` 执行性能 -- 优化 `LIMIT 0` 为 `TableDual`，避免无用的执行计划构建 - -## PD - -- 支持手动 split Region，可用于处理单 Region 热点的问题 -- 修复 `pdctl` 运行 `config show all` 不显示 label property 的问题 -- metrics 及代码结构相关的优化 - -## TiKV - -- 限制接收 snapshot 时的内存使用，解决极端情况下的 OOM -- 可以配置 Coprocessor 在遇到 warnings 时的行为 -- TiKV 支持导数据模式 -- 支持 Region 从正中间分裂 -- 提升 CI test 的速度 -- 使用 `crossbeam channel` -- 改善 TiKV 在被隔离的情况下由于 leader missing 输出太多日志的问题 diff --git a/v3.1/releases/2rc5.md b/v3.1/releases/2rc5.md deleted file mode 100644 index 709bcef9cd7f..000000000000 --- a/v3.1/releases/2rc5.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: TiDB 2.0 RC5 Release Notes -category: Releases ---- - -# TiDB 2.0 RC5 Release Notes - -2018 年 4 月 17 日，TiDB 发布 2.0 RC5 版。该版本在 RC4 版的基础上，对 MySQL 兼容性、系统稳定性和优化器做了很多改进。 - -## TiDB - -- 修复应用 `Top-N` 下推规则的问题 -- 修复对包含 NULL 值的列的行数估算 -- 修复 Binary 类型的 0 值 -- 修复事务内的 `BatchGet` 问题 -- 回滚 `Add Index` 操作的时候，清除清除已写入的数据，减少空间占用 -- 优化 `insert on duplicate key update` 语句性能，提升 10 倍以上 -- 修复 `UNIX_TIMESTAMP` 函数返回结果类型问题返回结果类型问题 -- 修复在添加 NOT NULL 列的过程中，插入 NULL 值的问题 -- `Show Process List` 语句支持显示执行语句的内存占用 -- 修复极端情况下 `Alter Table Modify Column` 出错问题 -- 支持通过 `Alter` 语句设置 table comment - -## PD - -- 添加 Raft Learner 支持 -- 优化 Balance Region Scheduler，减少调度开销 -- 调整默认 `schedule-limit` 配置 -- 修复频繁分配 ID 问题 -- 修复添加调度兼容性问题 - -## TiKV - -- `tikv-ctl` 支持 compact 指定的 Region -- Raw KV 支持 Batch Put、Batch Get、Batch Delete 和 Batch Scan -- 解决太多 snapshot 导致的 OOM 问题 -- Coprocessor 返回更详细的错误信息 -- 支持通过 `tikv-ctl` 动态修改 TiKV 的 `block-cache-size` -- 进一步完善 importer 功能 -- 简化 `ImportSST::Upload` 接口 -- 设置 gRPC 的 `keepalive` 属性 -- `tikv-importer` 作为独立的 binary 从 TiKV 中分离出来 -- 统计 Coprocessor 每个 scan range 命令扫描了多少行数据 -- 解决在 macOS 系统上的编译问题 -- 优化 metric 相关的内容 -- 解决 snapshot 相关的一个潜在 bug -- 解决误用了一个 RocksDB metric 的问题 -- Coprocessor 支持 `overflow as warning` 选项 \ No newline at end of file diff --git a/v3.1/releases/3.0-ga.md b/v3.1/releases/3.0-ga.md deleted file mode 100644 index 2d7962a367a9..000000000000 --- a/v3.1/releases/3.0-ga.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: TiDB 3.0 GA Release Notes -category: Releases ---- - -# TiDB 3.0 GA Release Notes - -发版日期：2019 年 6 月 28 日 - -TiDB 版本：3.0.0 - -TiDB Ansible 版本：3.0.0 - -## Overview - -2019 年 6 月 28 日，TiDB 发布 3.0 GA 版本，对应的 TiDB Ansible 版本为 3.0.0。 -相比于 V2.1，V3.0.0 版本在以下方面有重要改进： - -- 稳定性方面，显著提升了大规模集群的稳定性，集群支持 150+ 存储节点，300+ TB 存储容量长期稳定运行。 -- 易用性方面有显著的提升，降低用户运维成本，例如：标准化慢查询日志，制定日志文件输出规范，新增 `EXPLAIN ANALYZE`，SQL Trace 功能方便排查问题等。 -- 性能方面，与 2.1 相比，TPC-C 性能提升约 4.5 倍，Sysbench 性能提升约 1.5 倍。因支持 View，TPC-H 50G Q15 可正常运行。 -- 新功能方面增加了窗口函数、视图（**实验特性**）、分区表、插件系统、悲观锁（**实验特性**）、`SQL Plan Management` 等特性。 - -## TiDB - -+ 新功能 - - 新增 Window Function，支持所有 MySQL 8.0 中的窗口函数，包括 `NTILE`，`LEAD`，`LAG`、`PERCENT_RANK`、`NTH_VALUE`、`CUME_DIST`、`FIRST_VALUE`、`LAST_VALUE`、`RANK`、`DENSE_RANK`、`ROW_NUMBER` 函数 - - 新增 View 功能（**实验特性**） - - 完善 Table Partition 功能： - - Range Partition - - Hash Partition - - 新增插件系统，官方提供 IP 白名单（**企业版特性**），审记日志（**企业版特性**）等插件 - - 新增 `SQL Plan Management` 功能，通过绑定 SQL 执行计划确保查询的稳定性（**实验特性**） -+ SQL 优化器 - - 优化`NOT EXISTS` 子查询，转化为 Anti Semi Join 提升性能 - - 优化 `Outer Join` 常量传播，新增 `Outer Join` 消除优化规则，避免无效计算，提升性能 - - 优化 `IN` 子查询，先聚合后执行 `Inner Join`，提升性能 - - 优化 Index Join，适应更多的场景，提升性能 - - 优化 Range Partition 的 Partition Pruning 优化规则，提升性能 - - 优化 `_tidb_rowid` 查询逻辑，避免全表扫描，提升性能 - - 当过滤条件中包含相关列时，在抽取复合索引的访问条件时尽可能多地匹配索引的前缀列，提升性能 - - 利用列之间的顺序相关性，提升代价估算准确度 - - 基于统计信息的贪心算法及动态规划算法改进了 `Join Order`，提升多表关联的执行速度 - - 新增 Skyline Pruning，利用规则防止执行计划过于依赖统计信息，提升查询的稳定性 - - 提升单列索引上值为 NULL 时行数估算准确度 - - 新增 `FAST ANALYZE`，通过在各个 Region 中随机采样避免全表扫描的方式提升统计信息收集性能 - - 新增单调递增的索引列增量 `Analyze` 功能，提升统计信息收集性能 - - 支持 `DO` 语句中使用子查询 - - 支持在事务中使用 Index Join - - 优化 `prepare`/`execute`，支持不带参数的 DDL 语句 - - 修改变量 `stats-lease` 值为 0 时系统的行为，使其自动加载统计 - - 新增导出历史统计信息功能 - - 新增导入导出列的关联性信息功能 -+ SQL 执行引擎 - - 优化日志输出，`EXECUTE` 语句输出用户变量，`COMMIT` 语句输出慢查询日志，方便排查问题 - - 新增 `EXPLAIN ANALYZE` 功能，提升SQL 调优易用性 - - 新增 `admin show next_row_id` 功能，方便获取下一行 ID - - 新增`JSON_QUOTE`、`JSON_ARRAY_APPEND`、`JSON_MERGE_PRESERVE`、`BENCHMARK`、`COALESCE`、`NAME_CONST` 6 个内建函数 - - 优化 Chunk 大小控制逻辑，根据查询上下文件动态调整，降低 SQL 执行时间和资源消耗，提升性能 - - 新增 `TableReader`、`IndexReader` 和 `IndexLookupReader` 算子内存追踪控制 - - 优化 Merge Join 算子，使其支持空的 `ON` 条件 - - 优化单个表列较多时写入性能，提升数倍性能 - - 通过支持逆序扫数据提升 `admin show ddl jobs` 的性能 - - 新增 `split table region` 语句，手动分裂表的 Region，缓解热点问题 - - 新增 `split index region` 语句，手动分裂索引的 Region，缓解热点问题 - - 新增黑名单禁止下推表达式到 Coprocessor 功能 - - 优化 Expensive Query 日志，在日志中打印执行时间或者使用内存超过阈值的 SQL 查询 -+ DDL - - 支持字符集从 `utf8` 转换到 `utf8mb4` 的功能 - - 修改默认字符集从 `utf8` 变为 `utf8mb4` - - 新增 `alter schema` 语句修改数据库 charset 和 collation 功能 - - 新增 ALTER ALGORITHM `INPLACE`/`INSTANT` 功能 - - 新增 `SHOW CREATE VIEW` 功能 - - 新增 `SHOW CREATE USER` 功能 - - 新增快速恢复误删除的表功能 - - 新增动态调整 `ADD INDEX` 的并发数功能 - - 新增 pre_split_regions 选项，在 `CREATE TABLE` 时预先分配 Region，缓解建表后大量写入造成的写热点问题 - - 新增通过 SQL 语句指定表的索引及范围分裂 Region，缓解热点问题 - - 新增 `ddl_error_count_limit` 全局变量，控制 DDL 任务重次数 - - 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 - - 优化无效 DDL 元信息存活时间，使集群升级后一段时间 DDL 操作比较慢的情况变短 -+ 事务 - - 新增悲观事务模型（**实验特性**） - - 优化事务处理逻辑，适应更多场景，具体如下： - - `tidb_disable_txn_auto_retry` 的默认值为 `on`，即不会重试非自动提交的事务 - - 新增 `tidb_batch_commit` 系统变量控制将事务拆分成多个事务并发执行 - - 新增 `tidb_low_resolution_tso` 系统变量控制批量获取 `tso` 个数，减少事务获取 `tso` 的次数以适应某些数据一致性要求较低的场景 - - 新增 `tidb_skip_isolation_level_check` 变量控制事务检查隔离级别设置为 SERIALIZABLE 时是否报错 - - 修改 `tidb_disable_txn_auto_retry` 系统变量的行为，修改为影响所有的可重试错误 -+ 权限管理 - - 对 `ANALYZE`、`USE`、`SET GLOBAL`、`SHOW PROCESSLIST` 语句进行权限检查 - - 新增基于角色的权限访问控制功能 (RBAC)（**实验特性**） -+ Server - - 优化慢查询日志，具体包括： - - 重构慢查询日志格式 - - 优化慢查询日志内容 - - 优化查询慢查询日志的方法，通过内存表 `INFORMATION_SCHEMA.SLOW_QUERY`，`ADMIN SHOW SLOW` 语句查询慢查询日志 - - 制定日志格式规范，重构日志系统，方便工具收集分析 - - 新增 SQL 语句管理 TiDB Binlog 服务功能，包括查询状态，开启 TiDB Binlog，维护发送 TiDB Binlog 策略 - - 新增通过 `unix_socket` 方式连接数据库 - - 新增 SQL 语句 `Trace` 功能 - - 新增 `/debug/zip` HTTP 接口，获取 TiDB 实例的信息，方便排查问题 - - 优化监控项，方便排查问题，如下： - - 新增 `high_error_rate_feedback_total` 监控项，监控真实数据量与统计信息估算数据量之间的差距 - - 新增 Database 维度的 QPS 监控项 - - 优化系统初始化流程，仅允许 DDL Owner 执行初始化操作，缩短初始化或升级过程中的启动时间 - - 优化 `kill query` 语句执行逻辑，提升性能，确保资源正确释放 - - 新增启动选项 `config-check` 检查配置文件合法性 - - 新增 `tidb_back_off_weight` 系统变量，控制内部出错重试的退避时间 - - 新增 `wait_timeout`、`interactive_timeout` 系统变量，控制连接空闲超过变量的值，系统自动断开连接。 - - 新增连接 TiKV 的连接池，减少连接创建时间 -+ 兼容性 - - 支持 `ALLOW_INVALID_DATES` SQL mode - - 支持 MySQL 320 握手协议 - - 支持将 unsigned bigint 列声明为自增列 - - 支持 `SHOW CREATE DATABASE IF NOT EXISTS` 语法 - - 优化 load data 对 CSV 文件的容错 - - 过滤条件中包含用户变量时谓词不下推，兼容 MySQL Window Function 中使用用户变量行为 - -## PD - -+ 新增从单个节点重建集群的功能 -+ 将 Region 元信息从 etcd 移到 go-leveldb 存储引擎，解决大规模集群 etcd 存储瓶颈问题 -+ API - - 新增 `remove-tombstone` 接口，用于清理 Tombstone Store - - 新增 `ScanRegions` 接口，用于批量查询 Region 信息 - - 新增 `GetOperator` 接口，用于查询运行中的 Operator - - 优化 `GetStores` 接口的性能 -+ 配置 - - 优化配置检查逻辑，防止配置项错误 - - 新增 `enable-two-way-merge`，用于控制 Region merge 的方向 - - 新增 `hot-region-schedule-limit`，用于控制热点 Region 调度速度 - - 新增 `hot-region-cache-hits-threshold`，连续命中阀值用于判断热点 - - 新增 `store-balance-rate` 配置，用于控制每分钟产生 balance Region Operator 数量的上限 -+ 调度器优化 - - 添加 Store Limit 机制限制调度速度，使得速度限制适用于不同规模的集群 - - 添加 `waitingOperator` 队列，用于优化不同调度器之间资源竞争的问题 - - 支持调度限速功能，主动向 TiKV 下发调度操作，限制单节点同时执行调度任务的个数，提升调度速度 - - Region Scatter 调度不再受 limit 机制限制，提升调度的速度 - - 新增 `shuffle-hot-region` 调度器，解决稳定性测试易用性问题 -+ 模拟器 - - 新增数据导入场景模拟 - - 新增为 Store 设置不同的心跳间隔的功能 -+ 其他 - - 升级 etcd，解决输出日志格式不一致，prevote 时选举不出 Leader，Lease 死锁等问题 - - 制定日志格式规范，重构日志系统，方便工具收集分析 - - 新增调度参数，集群 Label 信息，PD 处理 TSO 请求的耗时，Store ID 与地址信息等监控指标 - -## TiKV - -+ 新增分布式 GC 以及并行 Resolve Lock 功能，提升 GC 的性能 -+ 新增逆向 `raw_scan` 和 `raw_batch_scan` 功能 -+ 新增多线程 Raftstore 和 Apply 功能，提升单节点内可扩展性，提升单节点内并发处理能力，提升单节点的资源利用率，降低延时，同等压力情况下性能提升 70% -+ 新增批量接收和发送 Raft 消息功能，写入密集的场景 TPS 提升 7% -+ 新增 Apply snapshot 之前检查 RocksDB level 0 文件的优化，避免产生 Write stall -+ 新增 Titan 存储引擎插件，提升 Value 超过 1KiB 时系统的性能，一定程度上缓解写放大问题（**实验特性**） -+ 新增悲观事务模型（**实验特性**） -+ 新增通过 HTTP 方式获取监控信息功能 -+ 修改 Insert 语义，仅在 Key 不存在的时候 Prewrite 才成功 -+ 制定日志格式规范，重构日志系统，方便工具收集分析 -+ 新增配置信息，Key 越界相关的性能监控指标 -+ RawKV 使用 Local Reader，提升性能 -+ Engine - - 优化内存管理，减少 `Iterator Key Bound Option` 的内存分配和拷贝，提升性能 - - 支持多个 column family 共享 block cache，提升资源的利用率 -+ Server - - 优化 `batch commands` 的上下文切换开销，提升性能 - - 删除 txn scheduler - - 新增 read index，GC worker 相关监控项 -+ RaftStore - - 新增 hibernate Regions 功能，优化 RaftStore CPU 的消耗（**实验特性**） - - 删除 local reader 线程 -+ Coprocessor - - 重构计算框架，实现向量化算子、向量化表达式计算、向量化聚合，提升性能 - - 支持为 TiDB `EXPLAIN ANALYZE` 语句提供算子执行详情 - - 改用 work-stealing 线程池模型，减少上下文切换 - -## Tools - -+ TiDB Lightning - - 支持数据表重定向同步功能 - - 新增导入 CSV 文件功能 - - 提升 SQL 转 KV 对的性能 - - 单表支持批量导入功能，提升单表导入的性能 - - 支持将大表的数据和索引分别导入，提升 `TiKV-Importer` 导入数据性能 - - 支持对新增文件中缺少 Column 数据时使用 row id 或者列的默认值填充缺少的 column 数据 - - `TiKV-Importer` 支持对 upload SST 到 TiKV 限速功能 -+ TiDB Binlog - - Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 - - Pump 使用 TiKV GetMvccByKey 接口加快事务状态查询 - - 新增组件之间通讯数据压缩功能，减少网络资源消耗 - - 新增 Arbiter 工具支持从 Kafka 读取 binlog 并同步到 MySQL 功能 - - Reparo 支持过滤不需要被同步的文件的功能 - - 新增同步 Generated column 功能 - - 新增 syncer.sql-mode 配置项，支持采用不同的 SQL mode 解析 DDL - - 新增 syncer.ignore-table 配置项，过滤不需要被同步的表 -+ sync-diff-inspector - - 新增 checkpoint 功能，支持从断点继续校验的功能 - - 新增 only-use-checksum 配置项，控制仅通过计算 checksum 校验数据的一致性 - - 新增采用 TiDB 统计信息以及使用多个 Column 划分 Chunk 的功能，适应更多的场景 - -## TiDB Ansible - -- 升级监控组件版本到安全的版本 - - Prometheus 从 2.2.1 升级到 2.8.1 版本 - - Pushgateway 从 0.4.0 升级到 0.7.0 版本 - - Node_exporter 从 0.15.2 升级到 0.17.0 版本 - - Alertmanager 从 0.14.0 升级到 0.17.0 版本 - - Grafana 从 4.6.3 升级到 6.1.6 版本 - - Ansible 从 2.5.14 升级到 2.7.11 版本 -- 新增 TiKV summary 监控面板，方便查看集群状态 -- 新增 TiKV trouble_shooting 监控面板，删除重复项，方便排查问题 -- 新增 TiKV details 监控面板，方便调试排查问题 -- 新增滚动升级并发检测版本是否一致功能，提升滚动升级性能 -- 新增 lightning 部署运维功能 -- 优化 `table-regions.py` 脚本，新增按表显示 leader 分布功能 -- 优化 TiDB 监控，新增以 SQL 类别显示延迟的监控项 -- 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 -- 新增预测集群最大 QPS 的监控项，默认隐藏 diff --git a/v3.1/releases/3.0.0-beta.1.md b/v3.1/releases/3.0.0-beta.1.md deleted file mode 100644 index 375e14e0b3f6..000000000000 --- a/v3.1/releases/3.0.0-beta.1.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: TiDB 3.0.0 Beta.1 Release Notes -category: Releases ---- - -# TiDB 3.0.0 Beta.1 Release Notes - -发版日期：2019 年 3 月 26 日 - -TiDB 版本：3.0.0-beta.1 - -TiDB Ansible 版本：3.0.0-beta.1 - -## Overview - -2019 年 03 月 26 日，TiDB 发布 3.0.0 Beta.1 版，对应的 TiDB Ansible 版本为 3.0.0 Beta.1。相比 3.0.0 Beta 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 支持使用 Sort Merge Join 计算笛卡尔积 [#9032](https://github.com/pingcap/tidb/pull/9037) - - 支持 Skyline Pruning，用一些规则来防止执行计划过于依赖统计信息 [#9337](https://github.com/pingcap/tidb/pull/9337) - + 支持 Window Functions - - `NTILE` [#9682](https://github.com/pingcap/tidb/pull/9682) - - `LEAD` 和 `LAG` [#9672](https://github.com/pingcap/tidb/pull/9672) - - `PERCENT_RANK` [#9671](https://github.com/pingcap/tidb/pull/9671) - - `NTH_VALUE` [#9596](https://github.com/pingcap/tidb/pull/9596) - - `CUME_DIST` [#9619](https://github.com/pingcap/tidb/pull/9619) - - `FIRST_VALUE` 和 `LAST_VALUE` [#9560](https://github.com/pingcap/tidb/pull/9560) - - `RANK` 和 `DENSE_RANK` [#9500](https://github.com/pingcap/tidb/pull/9500) - - `RANGE FRAMED` [#9450](https://github.com/pingcap/tidb/pull/9450) - - `ROW FRAMED` [#9358](https://github.com/pingcap/tidb/pull/9358) - - `ROW NUMBER` [#9098](https://github.com/pingcap/tidb/pull/9098) - - 增加了一类统计信息，表示列和 handle 列之间顺序的相关性 [#9315](https://github.com/pingcap/tidb/pull/9315) -+ SQL 执行引擎 - + 增加内建函数 - - `JSON_QUOTE` [#7832](https://github.com/pingcap/tidb/pull/7832) - - `JSON_ARRAY_APPEND` [#9609](https://github.com/pingcap/tidb/pull/9609) - - `JSON_MERGE_PRESERVE` [#8931](https://github.com/pingcap/tidb/pull/8931) - - `BENCHMARK` [#9252](https://github.com/pingcap/tidb/pull/9252) - - `COALESCE` [#9087](https://github.com/pingcap/tidb/pull/9087) - - `NAME_CONST` [#9261](https://github.com/pingcap/tidb/pull/9261) - - 根据查询上下文优化 Chunk 大小，降低 SQL 执行时间和集群的资源消耗 [#6489](https://github.com/pingcap/tidb/issues/6489) -+ 权限管理 - - 支持 `SET ROLE` 和 `CURRENT_ROLE` [#9581](https://github.com/pingcap/tidb/pull/9581) - - 支持 `DROP ROLE` [#9616](https://github.com/pingcap/tidb/pull/9616) - - 支持 `CREATE ROLE` [#9461](https://github.com/pingcap/tidb/pull/9461) -+ Server - - 新增 `/debug/zip` HTTP 接口，获取当前 TiDB 实例的信息 [#9651](https://github.com/pingcap/tidb/pull/9651) - - 支持使用 `show pump status`/`show drainer status` 语句查看 Pump/Drainer 状态 [#9456](https://github.com/pingcap/tidb/pull/9456) - - 支持使用 SQL 语句在线修改 Pump/Drainer 状态 [#9789](https://github.com/pingcap/tidb/pull/9789) - - 支持给 SQL 文本加上 HASH 指纹，方便追查慢 SQL [#9662](https://github.com/pingcap/tidb/pull/9662) - - 新增 `log_bin` 系统变量，默认：0，管理 binlog 开启状态，当前仅支持查看状态 [#9343](https://github.com/pingcap/tidb/pull/9343) - - 支持通过配置文件管理发送 binlog 策略 [#9864](https://github.com/pingcap/tidb/pull/9864) - - 支持通过内存表 `INFORMATION_SCHEMA.SLOW_QUERY` 查询慢日志 [#9290](https://github.com/pingcap/tidb/pull/9290) - - 将 TiDB 显示的 MySQL Version 从 5.7.10 变更为 5.7.25 [#9553](https://github.com/pingcap/tidb/pull/9553) - - 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 - - 增加监控项 `high_error_rate_feedback_total`，记录实际数据量与统计信息估算数据量差距情况 [#9209](https://github.com/pingcap/tidb/pull/9209) - - 新增 Database 维度的 QPS 监控项 , 可以通过配置项开启 [#9151](https://github.com/pingcap/tidb/pull/9151) -+ DDL - - 增加`ddl_error_count_limit`全局变量，默认值：512，限制 DDL 任务重试次数，超过限制次数会取消出错的 DDL [#9295](https://github.com/pingcap/tidb/pull/9295) - - 支持 ALTER ALGORITHM `INPLACE`/`INSTANT` [#8811](https://github.com/pingcap/tidb/pull/8811) - - 支持 `SHOW CREATE VIEW` 语句 [#9309](https://github.com/pingcap/tidb/pull/9309) - - 支持 `SHOW CREATE USER` 语句 [#9240](https://github.com/pingcap/tidb/pull/9240) - -## PD - -+ 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 -+ 模拟器 - - 支持不同 store 可采用不同的心跳间隔时间 [#1418](https://github.com/pingcap/pd/pull/1418) - - 添加导入数据的场景 [#1263](https://github.com/pingcap/pd/pull/1263) -+ 热点调度可配置化 [#1412](https://github.com/pingcap/pd/pull/1412) -+ 增加 store 地址为维度的监控项，代替原有的 Store ID [#1429](https://github.com/pingcap/pd/pull/1429) -+ 优化 `GetStores` 开销，加快 Region 巡检周期 [#1410](https://github.com/pingcap/pd/pull/1410) -+ 新增删除 Tombstone Store 的接口 [#1472](https://github.com/pingcap/pd/pull/1472) - -## TiKV - -+ 优化 Coprocessor 计算执行框架，完成 TableScan 算子，单 TableScan 即扫表操作性能提升 5% ~ 30% -实现行 `BatchRows` 和列 `BatchColumn` 的定义 [#3660](https://github.com/tikv/tikv/pull/3660) - - 实现 `VectorLike` 使得编码和解码的数据能够用统一的方式访问 [#4242](https://github.com/tikv/tikv/pull/4242) - - 定义 `BatchExecutor` 接口，实现将请求转化为 `BatchExecutor` 的方法 [#4243](https://github.com/tikv/tikv/pull/4243) - - 实现将表达式树转化成 RPN 格式 [#4329](https://github.com/tikv/tikv/pull/4329) - - TableScan 算子实现为 Batch 方式，通过向量化计算加速计算 [#4351](https://github.com/tikv/tikv/pull/4351) -+ 统一[日志格式规范](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)，利于工具收集分析 -+ 支持 Raw Read 接口使用 Local Reader 进行读 [#4222](https://github.com/tikv/tikv/pull/4222) -+ 新增配置信息的 Metrics [#4206](https://github.com/tikv/tikv/pull/4206) -+ 新增 Key 越界的 Metrics [#4255](https://github.com/tikv/tikv/pull/4255) -+ 新增碰到扫越界错误时 Panic 或者报错选项 [#4254](https://github.com/tikv/tikv/pull/4254) -+ 增加 Insert 语义，只有在 Key 不存在的时候 Prewrite 才成功，消除 Batch Get [#4085](https://github.com/tikv/tikv/pull/4085) -+ Batch System 使用更加公平的 batch 策略 [#4200](https://github.com/tikv/tikv/pull/4200) -+ tikv-ctl 支持 Raw scan [#3825](https://github.com/tikv/tikv/pull/3825) - -## Tools - -+ TiDB Binlog - - 新增 Arbiter 工具支持从 Kafka 读取 binlog 同步到 MySQL - - Reparo 支持过滤不需要同步的文件 - - 支持同步 generated column -+ Lightning - - 支持禁用 TiKV periodic Level-1 compaction，当 TiKV 集群为 2.1.4 或更高时，在导入模式下会自动执行 Level-1 compaction [#119](https://github.com/pingcap/tidb-lightning/pull/119)，[#4199](https://github.com/tikv/tikv/pull/4199) - - 根据 `table_concurrency` 配置项限制 import engines 数量，默认值：16，防止过多占用 importer 磁盘空间 [#119](https://github.com/pingcap/tidb-lightning/pull/119) - - 支持保存中间状态的 SST 到磁盘，减少内存使用 [#4369](https://github.com/tikv/tikv/pull/4369) - - 优化 TiKV-Importer 导入性能，支持将大表的数据和索引分离导入 [#132](https://github.com/pingcap/tidb-lightning/pull/132) - - 支持 CSV 文件导入 [#111](https://github.com/pingcap/tidb-lightning/pull/111) -+ 数据同步对比工具 (sync-diff-inspector) - - 支持使用 TiDB 统计信息来划分对比的 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) - - 支持使用多个 column 来划分对比的 chunk [#197](https://github.com/pingcap/tidb-tools/pull/197) diff --git a/v3.1/releases/3.0.0-rc.1.md b/v3.1/releases/3.0.0-rc.1.md deleted file mode 100644 index 96a8eb344669..000000000000 --- a/v3.1/releases/3.0.0-rc.1.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: TiDB 3.0.0-rc.1 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.1 Release Notes - -发版日期：2019 年 5 月 10 日 - -TiDB 版本：3.0.0-rc.1 - -TiDB Ansible 版本：3.0.0-rc.1 - -## Overview - -2019 年 5 月 10 日，TiDB 发布 3.0.0-rc.1 版，对应的 TiDB Ansible 版本为 3.0.0-rc.1。相比 3.0.0-beta.1 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 利用列之间的顺序相关性提升代价估算准确度，并提供启发式参数 `tidb_opt_correlation_exp_factor` 用于控制在相关性无法被直接用于估算的场景下对索引扫描的偏好程度。[#9839](https://github.com/pingcap/tidb/pull/9839) - - 当过滤条件中包含相关列时，在抽取复合索引的访问条件时尽可能多地匹配索引的前缀列。[#10053](https://github.com/pingcap/tidb/pull/10053) - - 用动态规划决定连接的执行顺序，当参与连接的表数量不多于 `tidb_opt_join_reorder_threshold` 时启用。[#8816](https://github.com/pingcap/tidb/pull/8816) - - 在构造 Index Join 的的内表中，以复合索引作为访问条件时，尽可能多地匹配索引的前缀列。[#8471](https://github.com/pingcap/tidb/pull/8471) - - 提升对单列索引上值为 NULL 的行数估算准确度。[#9474](https://github.com/pingcap/tidb/pull/9474) - - 在逻辑优化阶段消除聚合函数时特殊处理 `GROUP_CONCAT` ，防止产生错误的执行结果。[#9967](https://github.com/pingcap/tidb/pull/9967) - - 当过滤条件为常量时，正确地将它下推到连接算子的子节点上。[#9848](https://github.com/pingcap/tidb/pull/9848) - - 在逻辑优化阶段列剪裁时特殊处理一些函数，例如 `RAND()` ，防止产生和 MySQL 不兼容的执行结果。[#10064](https://github.com/pingcap/tidb/pull/10064) - - 支持 `FAST ANALYZE`，通过`tidb_enable_fast_analyze` 变量控制。该特性通过用对 Region 进行采样取代扫描整个 region 的方式加速统计信息收集。[#10258](https://github.com/pingcap/tidb/pull/10258) - - 支持 `SQL PLAN MANAGEMENT`。该特性通过对 SQL 进行执行计划绑定，以确保执行稳定性。该特性目前处于测试阶段，仅支持对 SELECT 语句使用绑定的执行计划，不建议在生产场景中直接使用。[#10284](https://github.com/pingcap/tidb/pull/10284) - -+ 执行引擎 - - 支持对 `TableReader`、`IndexReader` 和 `IndexLookupReader` 算子进行内存追踪控制。[#10003](https://github.com/pingcap/tidb/pull/10003) - - 在慢日志中展示更多 COPROCESSOR 端执行任务相关细节。如 COPROCESSOR 任务数，平均/最长/90% 执行/等待时间，执行/等待时间最长的 TiKV 地址等。[#10165](https://github.com/pingcap/tidb/pull/10165) - - 支持 PREPARE 不含占位符的 DDL 语句。[#10144](https://github.com/pingcap/tidb/pull/10144) - -+ Server - - TiDB 启动时，只允许 DDL owner 执行 bootstrap [#10029](https://github.com/pingcap/tidb/pull/10029) - - 新增 `tidb_skip_isolation_level_check` 变量控制检查隔离级别设置为 SERIALIZABLE 时不报错 [#10065](https://github.com/pingcap/tidb/pull/10065) - - 在慢日志中，将隐式提交的时间与 SQL 执行时间融合在一起 [#10294](https://github.com/pingcap/tidb/pull/10294) - + RBAC 权限管理 - - 支持 `SHOW GRANT` [#10016](https://github.com/pingcap/tidb/pull/10016) - - 支持 `SET DEFAULT ROLE` [#9949](https://github.com/pingcap/tidb/pull/9949) - - 支持 `GRANT ROLE` [#9721](https://github.com/pingcap/tidb/pull/9721) - - 修正了插件退出时导致 TiDB 退出的问题 [#9889](https://github.com/pingcap/tidb/pull/9889) - - 修正只读语句被错误地放到事务历史中的问题 [#9723](https://github.com/pingcap/tidb/pull/9723) - - kill 语句可以更快的结束 SQL 的执行，并快速释放资源 [#9844](https://github.com/pingcap/tidb/pull/9844) - - 增加启动选项 `config-check` 来检查配置文件的合法性 [#9855](https://github.com/pingcap/tidb/pull/9855) - - 修正非严格模式下对于写入 NULL 字段的合法性检查 [#10161](https://github.com/pingcap/tidb/pull/10161) - -+ DDL - - 为 CREATE TABLE 添加了 pre_split_regions 选项，该选项可以在建表时预先分配 Table Region，避免建表后大量写入造成的写热点 [#10138](https://github.com/pingcap/tidb/pull/10138) - - 优化了部分 DDL 语句的执行性能 [#10170](https://github.com/pingcap/tidb/pull/10170) - - FULLTEXT KEY 新增不支持全文索引的 warning [#9821](https://github.com/pingcap/tidb/pull/9821) - - 修正了旧版本 TiDB 中，UTF8 和 UTF8MB4 编码的兼容性问题 [#9820](https://github.com/pingcap/tidb/pull/9820) - - 修正了一个表的 shard_row_id_bits 的潜在 BUG [#9868](https://github.com/pingcap/tidb/pull/9868) - - 修正了 ALTER TABLE Charset 后，Column Charset 不会跟随变化的 BUG [#9790](https://github.com/pingcap/tidb/pull/9790) - - 修正了使用 BINARY/BIT 作为 Column Default Value 时，SHOW COLUMN 可能出错的 BUG [#9897](https://github.com/pingcap/tidb/pull/9897) - - 修正了 SHOW FULL COLUMNS 语句中，CHARSET / COLLATION 显示的兼容性问题 [#10007](https://github.com/pingcap/tidb/pull/10007) - - 现在 SHOW COLLATIONS 语句只会列出 TiDB 所实际支持的 COLLATIONS [#10186](https://github.com/pingcap/tidb/pull/10186) - -## PD - -+ 升级 ETCD 版本 [#1452](https://github.com/pingcap/pd/pull/1452) - - 统一 etcd 的日志格式与 pd server 一致 - - 修复 prevote 可能无法选出 Leader 的问题 - - 快速 drop 掉会失败的 propose 和 read 请求，减少阻塞后面的请求时间 - - 修复 Lease 的死锁问题 -+ 修复 store 读热点的 keys 统计不正确问题 [#1487](https://github.com/pingcap/pd/pull/1487) -+ 支持从单一 PD 节点强制重建 PD 集群 [#1485](https://github.com/pingcap/pd/pull/1485) -+ 修复 Scatter Region 产生无效 Operator Step 的问题 [#1482](https://github.com/pingcap/pd/pull/1482) -+ 修复 Region Merge Operator 超时时间过短的问题 [#1495](https://github.com/pingcap/pd/pull/1495) -+ 热点调度使用高优先级 [#1492](https://github.com/pingcap/pd/pull/1492) -+ 添加 PD server 端处理 TSO 请求的耗时 Metrics [#1502](https://github.com/pingcap/pd/pull/1502) -+ 添加相对应的 Store ID 和 Address 到 store 相关的 Metrics [#1506](https://github.com/pingcap/pd/pull/1506) -+ 支持 GetOperator 服务 [#1477](https://github.com/pingcap/pd/pull/1477) -+ 修复 Heartbeat stream 下发送 error 找不到 store 的问题 [#1521](https://github.com/pingcap/pd/pull/1521) - -## TiKV - -+ Engine - - 修复读流量统计不准确问题 [#4436](https://github.com/tikv/tikv/pull/4436) - - 修复 prefix extractor panic 的问题 [#4503](https://github.com/tikv/tikv/pull/4503) - - 优化内存管理，减少 `Iterator Key Bound Option` 的内存分配和拷贝 [#4537](https://github.com/tikv/tikv/pull/4537) - - 修复 Merge Region 时未考虑 Learner log gap 造成的 panic 问题 [#4559](https://github.com/tikv/tikv/pull/4559) - - 支持不同的 `column families` 共享 `block cache` [#4612](https://github.com/tikv/tikv/pull/4612) -+ Server - - 减少 `batch commands` 的上下文切换开销 [#4473](https://github.com/tikv/tikv/pull/4473) - - 检查 seek iterator status 的合法性 [#4470](https://github.com/tikv/tikv/pull/4470) -+ RaftStore - - 可配置化 `properties index distance` [#4517](https://github.com/tikv/tikv/pull/4517) -+ Coprocessor - - 新增 batch index scan executor [#4419](https://github.com/tikv/tikv/pull/4419) - - 新增向量化 evaluation 框架 [#4322](https://github.com/tikv/tikv/pull/4322) - - 新增 batch 执行器统计框架 [#4433](https://github.com/tikv/tikv/pull/4433) - - 构建 RPN expression 时检查 max column 以防止 evaluation 阶段 column offset 越界的问题 [#4481](https://github.com/tikv/tikv/pull/4481) - - 实现 `BatchLimitExecutor` [#4469](https://github.com/tikv/tikv/pull/4469) - - ReadPool 使用 `tokio-threadpool` 替换原本的 `futures-cpupool`，减少 context switch [#4486](https://github.com/tikv/tikv/pull/4486) - - 新增 batch 聚合框架 [#4533](https://github.com/tikv/tikv/pull/4533) - - 新增 `BatchSelectionExecutor` [#4562](https://github.com/tikv/tikv/pull/4562) - - 实现 batch aggression function `AVG` [#4570](https://github.com/tikv/tikv/pull/4570) - - 实现 RPN function `LogicalAnd` [#4575](https://github.com/tikv/tikv/pull/4575) -+ Misc - - 支持选用 tcmalloc 为内存分配器 [#4370](https://github.com/tikv/tikv/pull/4370) - -## Tools - -+ TiDB Binlog - - 修复 unsigned int 类型的主键列的 binlog 数据为负数，造成同步出错中断的问题 [#573](https://github.com/pingcap/tidb-binlog/pull/573) - - 删除下游是 pb 时的压缩选项，修改下游名字 pb 成 file [#559](https://github.com/pingcap/tidb-binlog/pull/559) - - Pump 新增 storage.sync-log 配置项，支持 Pump 本地存储异步刷盘 [#509](https://github.com/pingcap/tidb-binlog/pull/509) - - Pump 和 Drainer 之间通讯支持流量压缩 [#495](https://github.com/pingcap/tidb-binlog/pull/495) - - Drainer 新增 syncer.sql-mode 配置项，支持使用不同 sql-mode 解析 DDL query [#511](https://github.com/pingcap/tidb-binlog/pull/511) - - Drainer 新增 syncer.ignore-table 配置项，支持过滤不需要同步的表 [#520](https://github.com/pingcap/tidb-binlog/pull/520) -+ Lightning - - 使用 row id 或者列的默认值填充 dump 文件中缺少的 column 数据 [#170](https://github.com/pingcap/tidb-lightning/pull/170) - - Importer 修复部分 SST 导入失败依然返回导入成功的 bug [#4566](https://github.com/tikv/tikv/pull/4566) - - Importer 支持 upload SST 到 TiKV 限速 [#4412](https://github.com/tikv/tikv/pull/4412) - - Lightning 优化导入表的顺序，按照表的数据大小顺序进行导入，减少导入过程中大表执行 checksum 和 Analyze 对集群的影响，并且提高 Checksum 和 Analyze 的成功率 [#156](https://github.com/pingcap/tidb-lightning/pull/156) - - 提升 Lightning encode SQL 性能，性能提升 50%，直接解析数据源文件内容成 TiDB 的 types.Datum，省去 KV encoder 的多余解析工作 [#145](https://github.com/pingcap/tidb-lightning/pull/145) - - 日志格式改为 [Unified Log Format](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md) [#162](https://github.com/pingcap/tidb-lightning/pull/162) - - 新增一些命令行选项，即使缺少配置文件也能使用。[#157](https://github.com/pingcap/tidb-lightning/pull/157) -+ 数据同步对比工具 (sync-diff-inspector) - - 支持 checkpoint，记录校验状态，重启后从上次进度继续校验 [#224](https://github.com/pingcap/tidb-tools/pull/224) - - 增加配置项 only-use-checksum，只通过计算 checksum 来检查数据是否一致 [#215](https://github.com/pingcap/tidb-tools/pull/215) - -## TiDB Ansible - -+ TiKV 监控变更以及更新 Ansible、Grafana、Prometheus 版本 [#727](https://github.com/pingcap/tidb-ansible/pull/727) - - summary 监控适用于用户查看集群状态 - - trouble_shooting 监控适用于 DBA 排查问题 - - details 监控适用于开发分析问题 -+ 修复下载 Kafka 版本 Binlog 失败的 BUG [#730](https://github.com/pingcap/tidb-ansible/pull/730) -+ 修改操作系统版本限制，仅支持 CentOS 7.0 及以上，Red Hat 7.0 及以上版本的操作系统 [#733](https://github.com/pingcap/tidb-ansible/pull/733) -+ 滚动升级时的版本检测改为多并发 [#736](https://github.com/pingcap/tidb-ansible/pull/736) -+ 更新 README 中文档链接[#740](https://github.com/pingcap/tidb-ansible/pull/740) -+ 移除重复的 TiKV 监控项，新增 trouble shooting 监控项 [#735](https://github.com/pingcap/tidb-ansible/pull/735) -+ 优化 `table-regions.py` 脚本，按表显示 leader 分布 [#739](https://github.com/pingcap/tidb-ansible/pull/739) -+ 更新 drainer 配置文件 [#745](https://github.com/pingcap/tidb-ansible/pull/745) -+ 优化 TiDB 监控，新增以 SQL 类别显示延迟的监控项 [#747](https://github.com/pingcap/tidb-ansible/pull/747) -+ 更新 Lightning 配置文件，新增 tidb_lightning_ctl 脚本 [#1e946f8](https://github.com/pingcap/tidb-ansible/commit/1e946f89908e8fd6ef84128c6da3064ddfccf6a8) diff --git a/v3.1/releases/3.0.0-rc.2.md b/v3.1/releases/3.0.0-rc.2.md deleted file mode 100644 index 930f646c735c..000000000000 --- a/v3.1/releases/3.0.0-rc.2.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: TiDB 3.0.0-rc.2 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.2 Release Notes - -发版日期：2019 年 5 月 28 日 - -TiDB 版本：3.0.0-rc.2 - -TiDB Ansible 版本：3.0.0-rc.2 - -## Overview - -2019 年 5 月 28 日，TiDB 发布 3.0.0-rc.2 版本，对应的 TiDB Ansible 版本为 3.0.0-rc.2。相比 3.0.0-rc.1 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 在更多的场景中支持 Index Join [#10540](https://github.com/pingcap/tidb/pull/10540) - - 支持导出历史统计信息 [#10291](https://github.com/pingcap/tidb/pull/10291) - - 支持对单调递增的索引列增量 `Analyze` [#10355](https://github.com/pingcap/tidb/pull/10355) - - 忽略 `Order By` 子句中的 NULL 值 [#10488](https://github.com/pingcap/tidb/pull/10488) - - 修复精简列信息时逻辑算子 `UnionAll` 的 Schema 信息的计算不正确的问题 [#10384](https://github.com/pingcap/tidb/pull/10384) - - 下推 `Not` 操作符时避免修改原表达式 [#10363](https://github.com/pingcap/tidb/pull/10363) - - 支持导入导出列的关联性信息 [#10573](https://github.com/pingcap/tidb/pull/10573) - -+ 执行引擎 - - 有唯一索引的虚拟生成列可以在 `replace on duplicate key update`/`insert on duplicate key update` 语句中被正确地处理 [#10370](https://github.com/pingcap/tidb/pull/10370) - - 修复 CHAR 列上的扫描范围计算 [#10124](https://github.com/pingcap/tidb/pull/10124) - - 修复 `PointGet` 处理负数不正确问题 [#10113](https://github.com/pingcap/tidb/pull/10113) - - 合并具有相同窗口名的窗口函数，提高执行效率 [#9866](https://github.com/pingcap/tidb/pull/9866) - - 窗口函数中 Range Frame 可以无需 `Order By` 子句 [#10496](https://github.com/pingcap/tidb/pull/10496) - -+ Server - - 修复 TiKV 故障时，TiDB 不断创建与 TiKV 的新连接的问题 [#10301](https://github.com/pingcap/tidb/pull/10301) - - `tidb_disable_txn_auto_retry` 不再只影响写入冲突错误，而是影响所有的可重试错误 [#10339](https://github.com/pingcap/tidb/pull/10339) - - 不带参数的 DDL 语句可以通过 `prepare`/`execute` 来执行 [#10144](https://github.com/pingcap/tidb/pull/10144) - - 新增 `tidb_back_off_weight` 变量，控制 TiDB 内部 back off 时间的长短 [#10266](https://github.com/pingcap/tidb/pull/10266) - - `tidb_disable_txn_auto_retry` 的默认值改为 on，即默认情况下，TiDB 不会重试非自动提交的事务 [#10266](https://github.com/pingcap/tidb/pull/10266) - - 修复 RBAC 中对 role 的数据库权限的判断不正确的问题 [#10261](https://github.com/pingcap/tidb/pull/10261) - - 支持悲观事务模型（实验性）[#10297](https://github.com/pingcap/tidb/pull/10297) - - 降低某些情况下处理锁冲突时的等待时间 [#10006](https://github.com/pingcap/tidb/pull/10006) - - 重构 Region cache，增加在 Region 故障时的轮询逻辑 [#10256](https://github.com/pingcap/tidb/pull/10256) - - 新增 `tidb_low_resolution_tso` 变量，控制批量获取 `tso` 个数，减少事务获取 `tso` 的次数，以适应某些数据一致性要求较低的场景 [#10428](https://github.com/pingcap/tidb/pull/10428) - -+ DDL - - 修复旧版本的 TiDB 存储的字符集名称大写的问题 [#10272](https://github.com/pingcap/tidb/pull/10272) - - 支持 table partition 预分裂 Region 功能，该选项可以在建表时预先分配 table Region，避免建表后大量写入造成的写热点 [#10221](https://github.com/pingcap/tidb/pull/10221) - - 修复某些情况下 TiDB 更新版本信息到 PD 不准确的问题 [#10324](https://github.com/pingcap/tidb/pull/10324) - - 支持通过 `alter schema` 语句修改数据库 charset 和 collation [#10393](https://github.com/pingcap/tidb/pull/10393) - - 支持通过语句按指定表的索引及范围分裂 Region，用于缓解热点问题 [#10203](https://github.com/pingcap/tidb/pull/10203) - - 禁止 `alter table` 语句修改 `decimal` 列的精度 [#10433](https://github.com/pingcap/tidb/pull/10433) - - 修复 hash partition 中对表达式和函数的约束 [#10273](https://github.com/pingcap/tidb/pull/10273) - - 修复某些情况下对含有 partition 的 table 添加索引时引发 TiDB panic 的问题 [#10475](https://github.com/pingcap/tidb/pull/10475) - - 添加对某些极端情况下导致 schema 出错的防护功能 [#10464](https://github.com/pingcap/tidb/pull/10464) - - 创建 range partition 若有单列或者创建 hash partition 时默认开启分区功能 [#9936](https://github.com/pingcap/tidb/pull/9936) - -## PD - -- 默认开启 Region storage 将 Region 元信息存储到 Region storage 中 [#1524](https://github.com/pingcap/pd/pull/1524) -- 修复热点调度受其他调度器抢占的问题 [#1522](https://github.com/pingcap/pd/pull/1522) -- 修复 Leader 优先级不生效的问题 [#1533](https://github.com/pingcap/pd/pull/1533) -- 新增 `ScanRegions` 的 gRPC 接口 [#1535](https://github.com/pingcap/pd/pull/1535) -- 主动下发 operator 加快调度速度 [#1536](https://github.com/pingcap/pd/pull/1536) -- 添加 store limit 机制，限制单个 store 的调度速度 [#1474](https://github.com/pingcap/pd/pull/1474) -- 修复 `config` 状态不一致的问题 [#1476](https://github.com/pingcap/pd/pull/1476) - -## TiKV - -+ Engine - - 支持多个 column family 共享 block cache [#4563](https://github.com/tikv/tikv/pull/4563) -+ Server - - 移除 txn scheduler [#4098](https://github.com/tikv/tikv/pull/4098) - - 支持悲观锁事务 [#4698](https://github.com/tikv/tikv/pull/4698) -+ Raftstore - - 新增 hibernate Regions 特性，减少 raftstore CPU 的消耗 [#4591](https://github.com/tikv/tikv/pull/4591) - - 移除 local reader 线程 [#4558](https://github.com/tikv/tikv/pull/4558) - - 修复 Leader 不回复 Learner `ReadIndex` 请求的问题 [#4653](https://github.com/tikv/tikv/pull/4653) - - 修复在某些情况下 transfer leader 失败的问题 [#4684](https://github.com/tikv/tikv/pull/4684) - - 修复在某些情况下可能发生的脏读问题 [#4688](https://github.com/tikv/tikv/pull/4688) - - 修复在某些情况下 snapshot 少包含数据的问题 [#4716](https://github.com/tikv/tikv/pull/4716) -+ Coprocessor - - 新增更多的 RPN 函数 - - `LogicalOr` [#4691](https://github.com/tikv/tikv/pull/4601) - - `LTReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `LEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `GTReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `GEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `NEReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `EQReal` [#4602](https://github.com/tikv/tikv/pull/4602) - - `IsNull` [#4720](https://github.com/tikv/tikv/pull/4720) - - `IsTrue` [#4720](https://github.com/tikv/tikv/pull/4720) - - `IsFalse` [#4720](https://github.com/tikv/tikv/pull/4720) - - 支持 `Int` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Decimal` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `String` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Time` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Duration` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Json` 比较运算 [#4625](https://github.com/tikv/tikv/pull/4625) - - 支持 `Int` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Real` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Decimal` 加法运算 [#4733](https://github.com/tikv/tikv/pull/4733) - - 支持 `Int` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Real` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Decimal` 求余函数 [#4727](https://github.com/tikv/tikv/pull/4727) - - 支持 `Int` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - - 支持 `Real` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - - 支持 `Decimal` 减法运算 [#4746](https://github.com/tikv/tikv/pull/4746) - -## Tools - -+ TiDB Binlog - - Drainer 增加下游同步延迟监控项 `checkpoint_delay` [#594](https://github.com/pingcap/tidb-binlog/pull/594) - -+ TiDB Lightning - - 支持数据库合并，数据表合并同步功能 [#95](https://github.com/pingcap/tidb-lightning/pull/95) - - 新增 KV 写入失败重试机制 [#176](https://github.com/pingcap/tidb-lightning/pull/176) - - 配置项 `table-concurrency` 默认值修改为 6 [#175](https://github.com/pingcap/tidb-lightning/pull/175) - - 减少必要的配置项，`tidb.port` 和 `tidb..pd-addr` 支持自动获取 [#173](https://github.com/pingcap/tidb-lightning/pull/173) diff --git a/v3.1/releases/3.0.0-rc.3.md b/v3.1/releases/3.0.0-rc.3.md deleted file mode 100644 index 141b3c897e54..000000000000 --- a/v3.1/releases/3.0.0-rc.3.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: TiDB 3.0.0-rc.3 Release Notes -category: Releases ---- - -# TiDB 3.0.0-rc.3 Release Notes - -发版日期：2019 年 6 月 21 日 - -TiDB 版本：3.0.0-rc.3 - -TiDB Ansible 版本：3.0.0-rc.3 - -## Overview - -2019 年 6 月 21 日，TiDB 发布 3.0.0-rc.3 版本，对应的 TiDB Ansible 版本为 3.0.0-rc.3。相比 3.0.0-rc.2 版本，该版本对系统稳定性、易用性、功能、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ SQL 优化器 - - 删除收集虚拟生成列的统计信息功能 [#10629](https://github.com/pingcap/tidb/pull/10629) - - 修复点查时主键常量溢出的问题 [#10699](https://github.com/pingcap/tidb/pull/10699) - - 修复 `fast analyze` 因使用未初始化的信息导致 panic [#10691](https://github.com/pingcap/tidb/pull/10691) - - 修复 prepare `create view` 语句执行过程中因列信息错误导致执行失败的问题 [#10713](https://github.com/pingcap/tidb/pull/10713) - - 修复在处理 window function 时列信息未拷贝的问题 [#10720](https://github.com/pingcap/tidb/pull/10720) - - 修复 index join 中内表过滤条件在某些情况下的选择率估计错误的问题 [#10854](https://github.com/pingcap/tidb/pull/10854) - - 新增变量 `stats-lease` 值为 0 时系统自动加载统计数据功能 [#10811](https://github.com/pingcap/tidb/pull/10811) - -+ 执行引擎 - - 修复在 `StreamAggExec` 调用 `Close` 函数资源未正确释放问题 [#10636](https://github.com/pingcap/tidb/pull/10636) - - 修复对分区表执行 `show create table` 结果中 `table_option` 与 `partition_options` 顺序不正确问题 [#10689](https://github.com/pingcap/tidb/pull/10689) - - 通过支持逆序扫数据提升 `admin show ddl jobs` 的性能 [#10687](https://github.com/pingcap/tidb/pull/10687) - - 修复 RBAC 中对 `show grants` 语句带 `current_user` 字段时结果与 MySQL 不兼容的问题 [#10684](https://github.com/pingcap/tidb/pull/10684) - - 修复 UUID 在多节点上可能生成重复值的问题 [#10712](https://github.com/pingcap/tidb/pull/10712) - - 修复 `explain` 没考虑 `show view` 权限的问题 [#10635](https://github.com/pingcap/tidb/pull/10635) - - 新增 `split table region` 语句，手动分裂表的 Region，缓解热点问题 [#10765](https://github.com/pingcap/tidb/pull/10765) - - 新增 `split index region` 语句，手动分裂索引的 region 缓解热点问题 [#10764](https://github.com/pingcap/tidb/pull/10764) - - 修复连续执行多个 `create user`、`grant` 或 `revoke` 等类似语句执行不正确的问题 [#10737](https://github.com/pingcap/tidb/pull/10737) - - 新增黑名单禁止下推表达式到 coprocessor 功能 [#10791](https://github.com/pingcap/tidb/pull/10791) - - 新增查询超出内存配置限制时打印 `expensive query` 日志的功能 [#10849](https://github.com/pingcap/tidb/pull/10849) - - 新增 `bind-info-lease` 配置项控制修改绑定执行计划的更新时间 [#10727](https://github.com/pingcap/tidb/pull/10727) - - 修复因持有 `execdetails.ExecDetails` 指针时 Coprocessor 的资源无法快速释放导致的在大并发场景下 OOM 的问题 [#10832](https://github.com/pingcap/tidb/pull/10832) - - 修复某些情况下 `kill` 语句导致的 panic 问题 [#10876](https://github.com/pingcap/tidb/pull/10876) - -+ Server - - 修复 GC 时可能发生的 goroutine 泄露问题 [#10683](https://github.com/pingcap/tidb/pull/10683) - - 支持 slow query 里面显示 `host` 信息 [#10693](https://github.com/pingcap/tidb/pull/10693) - - 支持循环利用与 TiKV 交互的空闲链接 [#10632](https://github.com/pingcap/tidb/pull/10632) - - 修复 RBAC 对开启 `skip-grant-table` 选项的支持问题 [#10738](https://github.com/pingcap/tidb/pull/10738) - - 修复 `pessimistic-txn` 配置失效的问题 [#10825](https://github.com/pingcap/tidb/pull/10825) - - 修复主动取消的 ticlient 请求还会被重试的问题 [#10850](https://github.com/pingcap/tidb/pull/10850) - - 提高在悲观事务和乐观事务冲突情况下的性能 [#10881](https://github.com/pingcap/tidb/pull/10881) - -+ DDL - - 修复在使用 `alter table` 修改 charset 时导致 `blob` 类型改变的问题 [#10698](https://github.com/pingcap/tidb/pull/10698) - - 新增列属性包含 `AUTO_INCREMENT` 时利用 `SHARD_ROW_ID_BITS` 打散行 ID 功能，缓解热点问题 [#10794](https://github.com/pingcap/tidb/pull/10794) - - 禁止通过 `alter table` 添加存储的生成列 [#10808](https://github.com/pingcap/tidb/pull/10808) - - 优化无效 DDL 元信息存活时间，使集群升级后一段时间 DDL 操作比较慢的情况变短 [#10795](https://github.com/pingcap/tidb/pull/10795) - -## PD - -- 新增 `enable-two-way-merge` 配置项，控制合并时仅允许单向合并 [#1583](https://github.com/pingcap/pd/pull/1583) -- 新增 `AddLightLearner` 和 `AddLightPeer` 的调度操作，Region Scatter 调度不受 limit 机制限 [#1563](https://github.com/pingcap/pd/pull/1563) -- 修复系统启动时因数据可能只进行一副本复制而导致可靠性不足的问题 [#1581](https://github.com/pingcap/pd/pull/1581) -- 优化配置检查逻辑，防止配置项错误 [#1585](https://github.com/pingcap/pd/pull/1585) -- 调整 `store-balance-rate` 配置的定义为每分钟产生 balance operator 数量的上限 [#1591](https://github.com/pingcap/pd/pull/1591) -- 修复 store 可能一直无法产生调度操作的问题 [#1590](https://github.com/pingcap/pd/pull/1590) - -## TiKV - -+ Engine - - 修复因迭代器未检查状态导致系统生成残缺 snapshot 的问题 [#4936](https://github.com/tikv/tikv/pull/4936) - - 修复在机器异常掉电时由于接收 snapshot 未及时将数据刷新到磁盘导致丢数据的问题 [#4937](https://github.com/tikv/tikv/pull/4937) - -+ Server - - 新增检查 `block-size` 配置的有效性功能 [#4928](https://github.com/tikv/tikv/pull/4928) - - 新增 read index 相关监控项 [#4830](https://github.com/tikv/tikv/pull/4830) - - 新增 GC worker 相关监控项 [#4922](https://github.com/tikv/tikv/pull/4922) - -+ Raftstore - - 修复 local reader 的 cache 没有正确清理的问题 [#4778](https://github.com/tikv/tikv/pull/4778) - - 修复进行 transfer leader 和 conf change 时可能导致请求延迟增加的问题 [#4734](https://github.com/tikv/tikv/pull/4734) - - 修复误报 stale command 的问题 [#4682](https://github.com/tikv/tikv/pull/4682) - - 修复 command 可能一直 pending 的问题 [#4810](https://github.com/tikv/tikv/pull/4810) - - 修复 snapshot 文件未及时落盘而导致掉电后文件损坏的问题 [#4807](https://github.com/tikv/tikv/pull/4807)，[#4850](https://github.com/tikv/tikv/pull/4850) - -+ Coprocessor - - 向量计算支持 Top-N [#4827](https://github.com/tikv/tikv/pull/4827) - - 向量计算支持 Stream 聚合 [#4786](https://github.com/tikv/tikv/pull/4786) - - 向量计算中支持 AVG 聚合函 [#4777](https://github.com/tikv/tikv/pull/4777) - - 向量计算中支持 First 聚合函数 [#4771](https://github.com/tikv/tikv/pull/4771) - - 向量计算中支持 SUM 聚合函数 [#4797](https://github.com/tikv/tikv/pull/4797) - - 向量计算中支持 MAX/MIN 聚合函数 [#4837](https://github.com/tikv/tikv/pull/4837) - - 向量计算中支持 Like 表达式 [#4747](https://github.com/tikv/tikv/pull/4747) - - 向量计算中支持 MultiplyDecimal 表达式 [#4849](https://github.com/tikv/tikv/pull/4849 ) - - 向量计算中支持 BitAnd/BitOr/BitXor 表达式 [#4724](https://github.com/tikv/tikv/pull/4724) - - 向量计算中支持 UnaryNot 表达式 [#4808](https://github.com/tikv/tikv/pull/4808) - -+ Transaction - - 修复悲观事务中非悲观锁冲突导致出错的问题 [#4801](https://github.com/tikv/tikv/pull/4801)，[#4883](https://github.com/tikv/tikv/pull/4883) - - 减少在开启悲观事务后乐观事务的无用计算，提高性能 [#4813](https://github.com/tikv/tikv/pull/4813) - - 新增单语句 rollback，保证在当前语句发生死锁时不需要 rollback 整个事务 [#4848](https://github.com/tikv/tikv/pull/4848) - - 新增悲观事务相关监控项 [#4852](https://github.com/tikv/tikv/pull/4852) - - 支持 `ResolveLockLite` 命令用于轻量级清锁以优化在冲突严重时的性能 [#4882](https://github.com/tikv/tikv/pull/4882) - -+ tikv-ctl - - 新增 `bad-regions` 命令支持检测更多的异常情况 [#4862](https://github.com/tikv/tikv/pull/4862) - - `tombstone` 命令新增强制执行功能 [#4862](https://github.com/tikv/tikv/pull/4862) - -+ Misc - - 新增 `dist_release` 编译命令 [#4841](https://github.com/tikv/tikv/pull/4841) - -## Tools - -+ TiDB Binlog - - 修复 Pump 因写入失败时未检查返回值导致偏移量错误的问题 [#640](https://github.com/pingcap/tidb-binlog/pull/640) - - Drainer 新增 `advertise-addr` 配置，支持容器环境中使用桥接模式 [#634](https://github.com/pingcap/tidb-binlog/pull/634) - - Pump 新增 `GetMvccByEncodeKey` 函数，加快事务状态查询 [#632](https://github.com/pingcap/tidb-binlog/pull/632) - -## TiDB Ansible - -- 新增预测集群最大 QPS 的监控项（默认隐藏）[#f5cfa4d](https://github.com/pingcap/tidb-ansible/commit/f5cfa4d903bbcd77e01eddc8d31eabb6e6157f73) \ No newline at end of file diff --git a/v3.1/releases/3.0.1.md b/v3.1/releases/3.0.1.md deleted file mode 100644 index e8f66f04e20d..000000000000 --- a/v3.1/releases/3.0.1.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: TiDB 3.0.1 Release Notes -category: Releases ---- - -# TiDB 3.0.1 Release Notes - -发版日期：2019 年 7 月 16 日 - -TiDB 版本：3.0.1 - -TiDB Ansible 版本：3.0.1 - -## TiDB - -+ 新增对 `MAX_EXECUTION_TIME` 特性的支持 [#11026](https://github.com/pingcap/tidb/pull/11026) -+ 新增 `tidb_wait_split_region_finish_backoff` Session 变量，用于控制 Region 打散的 Backoff 时间 [#11166](https://github.com/pingcap/tidb/pull/11166) -+ 新增根据负载情况自动调整 Auto ID 分配的步长功能，步长自动调整范围最小 1000，最大 2000000 [#11006](https://github.com/pingcap/tidb/pull/11006) -+ 新增 `ADMIN PLUGINS ENABLE`/`ADMIN PLUGINS DISABLE` SQL 语句，管理 Plugin 的动态开启或关闭 [#11157](https://github.com/pingcap/tidb/pull/11157) -+ Audit Plugin 新增审记连接功能 [#11013](https://github.com/pingcap/tidb/pull/11013) -+ 修改 Region 打散时的默认行为为等待 PD 调度完成 [#11166](https://github.com/pingcap/tidb/pull/11166) -+ 禁止 Window Function 在 Prepare Plan Cache 中被缓存，避免某些情况下出现结果不正确的问题 [#11048](https://github.com/pingcap/tidb/pull/11048) -+ 禁止使用 Alter 语句修改 Stored Generated Column 的定义 [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 禁止将 Virtual Generated Column 更改为 Stored Generated Column [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 禁止改变带有索引的 Generated Column 的表达式 [#11068](https://github.com/pingcap/tidb/pull/11068) -+ 支持 TiDB 在 ARM64 架构下的编译 [#11150](https://github.com/pingcap/tidb/pull/11150) -+ 支持修改 Database/Table 的 Collate，条件限制为 Database/Table 字符集必须是 UTF8/UTF8MB4 [#11086](https://github.com/pingcap/tidb/pull/11086) -+ 修复 `UPDATE … SELECT` 语句中，`SELECT` 子查询没有解析到 `UPDATE` 表达式中的列而被误裁剪，导致报错的问题 [#11252](https://github.com/pingcap/tidb/pull/11252) -+ 修复点查时，某列被查询多次而且结果为 NULL 时会 Panic 的问题 [#11226](https://github.com/pingcap/tidb/pull/11226) -+ 修复 `RAND` 函数由于非线程安全的 `rand.Rand` 导致的 Data Race 问题 [#11169](https://github.com/pingcap/tidb/pull/11169) -+ 修复 `oom-action="cancel"` 时，某些情况下 SQL 内存使用超阈值没有被取消执行，返回结果不正确的问题 [#11004](https://github.com/pingcap/tidb/pull/11004) -+ 修复 MemTracker 未正确清理统计的内存使用值导致 `SHOW PROCESSLIST` 显示内存使用不为 0 的问题 [#10970](https://github.com/pingcap/tidb/pull/10970) -+ 修复某些情况下整数和非整数比较结果不正确的问题 [#11194](https://github.com/pingcap/tidb/pull/11194) -+ 修复在显式事务中查询对 Table Partition 的查询包含谓词时，查询结果不正确的问题 [#11196](https://github.com/pingcap/tidb/pull/11196) -+ 修复 DDL Job 由于 `infoHandle` 可能为 `NULL` 导致 Panic 的问题 [#11022](https://github.com/pingcap/tidb/pull/11022) -+ 修复嵌套聚合查询时，由于被查询列在子查询中没有引用而被误裁剪导致查询结果错误的问题 [#11020](https://github.com/pingcap/tidb/pull/11020) -+ 修复 `Sleep` 函数响应 Kill 命令不及时的问题 [#11028](https://github.com/pingcap/tidb/pull/11028) -+ 修复 `SHOW PROCESSLIST` 命令显示的 `DB` 和 `INFO` 列与 MySQL 不兼容的问题 [#11003](https://github.com/pingcap/tidb/pull/11003) -+ 修复 `skip-grant-table=true` 时，`FLUSH PRIVILEGES` 语句导致系统 Panic 的问题 [#11027](https://github.com/pingcap/tidb/pull/11027) -+ 修复表主键为 `UNSIGNED` 整数时，`FAST ANALYZE` 收集主键的统计信息不正确的问题 [#11099](https://github.com/pingcap/tidb/pull/11099) -+ 修复某些情况下 `FAST ANALYZE` 语句报 “invalid key” Error 的问题 [#11098](https://github.com/pingcap/tidb/pull/11098) -+ 修复 `CURRENT_TIMESTAMP` 作为列的默认值且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11088](https://github.com/pingcap/tidb/pull/11088) -+ 修复窗口函数报错时函数名没有小写的问题，兼容 MySQL [#11118](https://github.com/pingcap/tidb/pull/11118) -+ 修复 TiKV Client Batch gRPC 的后台线程 panic 后导致 TiDB 无法正常连接 TiKV 进而无法提供服务的问题 [#11101](https://github.com/pingcap/tidb/pull/11101) -+ 修复 `SetVar` 方法由于字符串浅拷贝导致设置的变量不正确的问题 [#11044](https://github.com/pingcap/tidb/pull/11044) -+ 修复 `INSERT … ON DUPLICATE` 语句作用在 Table Partition 时执行失败报错的问题 [#11231](https://github.com/pingcap/tidb/pull/11231) -+ 悲观锁（实验性特性） - - 修复悲观锁进行点查且数据为空时，由于行锁未生效导致结果不正确的问题 [#10976](https://github.com/pingcap/tidb/pull/10976) - - 修复使用悲观锁查询时由于没有使用 `SELECT … FOR UPDATE` 的 TSO 导致查询结果不正确的问题 [#11015](https://github.com/pingcap/tidb/pull/11015) - - 修改乐观锁与悲观锁同时使用时，乐观事务遇到悲观锁冲突时，检测行为由立即检测冲突修改为等待，防止锁冲突进一步恶化 [#11051](https://github.com/pingcap/tidb/pull/11051) - -## TiKV - -- 统计信息中新增对 Blob 文件大小的统计 [#5060](https://github.com/tikv/tikv/pull/5060) -- 修复由于进程退出未正确清理内存资源导致进程在退出时 core dump 问题 [#5053](https://github.com/tikv/tikv/pull/5053) -- 新增与 Titan 引擎相关的所有监控指标 [#4772](https://github.com/tikv/tikv/pull/4772)，[#4836](https://github.com/tikv/tikv/pull/4836) -- 统计打开文件句柄数量时，新增 Titan 引擎打开文件句柄数量，防止因文件句柄数统计不准确导致系统无文件句柄可用的问题 [#5026](https://github.com/tikv/tikv/pull/5026) -- 通过设置 `blob_run_mode` 来决定是否在某个 CF 上启动 Titan 引擎 [#4991](https://github.com/tikv/tikv/pull/4991) -- 修复读操作读不到悲观事务 commit 信息的问题 [#5067](https://github.com/tikv/tikv/pull/5067) -- 新增 `blob-run-mode` 配置参数控制 Titan 引擎的运行模式，取值：normal、read-only、fallback [#4865](https://github.com/tikv/tikv/pull/4865) -- 提升死锁检测的性能 [#5089](https://github.com/tikv/tikv/pull/5089) - -## PD - -- 修复热点 Region 调度时，调度限制会自动调整为 0 的问题 [#1552](https://github.com/pingcap/pd/pull/1552) -- 新增 `enable-grpc-gateway` 的配置选项，用于开启 etcd 的 grpc gateway 功能 [#1596](https://github.com/pingcap/pd/pull/1596) -- 新增 `store-balance-rate`、`hot-region-schedule-limit` 等与调度器配置相关的统计信息 [#1601](https://github.com/pingcap/pd/pull/1601) -- 优化热点 Region 调度策略，调度时跳过缺失副本的 Region，防止多个副本调度到同一个机房 [#1609](https://github.com/pingcap/pd/pull/1609) -- 优化 Region Merge 处理逻辑，优先 Merge Region Size 较小的 Region，提升 Region Merge 的速度 [#1613](https://github.com/pingcap/pd/pull/1613) -- 优化单次调度热点 Region 的限制值为 64，防止调度任务过多占用系统资源，影响性能 [#1616](https://github.com/pingcap/pd/pull/1616) -- 优化 Region 调度策略，新增优先调度 Pending 状态的 Region 功能 [#1617](https://github.com/pingcap/pd/pull/1617) -- 修复无法添加 `random-merge` 和 `admin-merge-region` operator 的问题 [#1634](https://github.com/pingcap/pd/pull/1634) -- 调整日志中输出 Region 中 Key 的格式为 16 进制，方便用户查看 [#1639](https://github.com/pingcap/pd/pull/1639) - -## Tools - -TiDB Binlog - -- 优化 Pump GC 策略，删除保证未被消费的 Binlog 不被清理的限制，确保资源不会长期占用 [#646](https://github.com/pingcap/tidb-binlog/pull/646) - -TiDB Lightning - -- 修正 SQL dump 指明的列名不是小写时导入错误的问题 [#210](https://github.com/pingcap/tidb-lightning/pull/210) - -## TiDB Ansible - -- 新增 `ansible` 命令及其 `jmespath`、`Jinja2` 依赖包的预检查功能 [#803](https://github.com/pingcap/tidb-ansible/pull/803)，[#813](https://github.com/pingcap/tidb-ansible/pull/813) -- Pump 新增 `stop-write-at-available-space` 参数，控制当磁盘剩余空间小于该值（默认 10 GiB）时，Pump 停止写入 Binlog [#806](https://github.com/pingcap/tidb-ansible/pull/806) -- 更新 TiKV 监控中的 IO 监控项，兼容新版本监控组件 [#820](https://github.com/pingcap/tidb-ansible/pull/820) -- 更新 PD 监控信息，并修复 Disk Performance Dashboard 中 Disk Latency 显示为空的异常 [#817](https://github.com/pingcap/tidb-ansible/pull/817) -- TiKV Details Dashboard 新增 Titan 监控项 [#824](https://github.com/pingcap/tidb-ansible/pull/824) diff --git a/v3.1/releases/3.0.10.md b/v3.1/releases/3.0.10.md deleted file mode 100644 index 99ad46fff3e4..000000000000 --- a/v3.1/releases/3.0.10.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: TiDB 3.0.10 Release Notes -category: Releases ---- - -# TiDB 3.0.10 Release Notes - -发版日期：2020 年 02 月 20 日 - -TiDB 版本：3.0.10 - -TiDB Ansible 版本：3.0.10 - -## TiDB - -- 修复 IndexLookUpJoin 在利用 OtherCondition 构造 InnerRange 时出现错误 Join 结果 [#14599](https://github.com/pingcap/tidb/pull/14599) -- 删除 `tidb_pprof_sql_cpu` 配置项，新增 Server 级别的 `tidb_pprof_sql_cpu` 变量 [#14416](https://github.com/pingcap/tidb/pull/14416) -- 修复用户只在具有全局权限时才能查询所有数据库的问题 [#14386](https://github.com/pingcap/tidb/pull/14386) -- 修复执行 point-get 时由于事务超时导致数据的可见性不符合预期的问题 [#14480](https://github.com/pingcap/tidb/pull/14480) -- 将悲观事务激活的时机改为延迟激活，与乐观事务模型保持一致 [#14474](https://github.com/pingcap/tidb/pull/14474) -- 修复 unixtimestamp 表达式在计算分区表分区的时区不正确的问题 [#14476](https://github.com/pingcap/tidb/pull/14476) -- 新增`tidb_session_statement_deadlock_detect_duration_seconds` 监控项，用于监控死锁检测时间 [#14484](https://github.com/pingcap/tidb/pull/14484) -- 修复 GC worker 由于部分逻辑不正确导致系统 panic 的问题 [#14439](https://github.com/pingcap/tidb/pull/14439) -- 修复 IsTrue 函数的表达式名称不正确的问题 [#14516](https://github.com/pingcap/tidb/pull/14516) -- 修复部分内存使用统计不准确的问题 [#14533](https://github.com/pingcap/tidb/pull/14533) -- 修复统计信息 CM-Sketch 初始化时由于处理逻辑不正确导致系统 panic 的问题 [#14470](https://github.com/pingcap/tidb/pull/14470) -- 修复查询分区表时分区裁剪（partition pruning）不准确的问题 [#14546](https://github.com/pingcap/tidb/pull/14546) -- 修复 SQL 绑定中 SQL 语句默认数据库名设置不正确的问题 [#14548](https://github.com/pingcap/tidb/pull/14548) -- 修复 json_key 与 MySQL 不兼容的问题 [#14561](https://github.com/pingcap/tidb/pull/14561) -- 新增分区表自动更新统计信息的功能 [#14566](https://github.com/pingcap/tidb/pull/14566) -- 修复执行 point-get时 plan id 会变化的问题，正常情况 plan id 始终是 1 [#14595](https://github.com/pingcap/tidb/pull/14595) -- 修复 SQL 绑定不完全匹配时处理逻辑不正确导致系统 panic 的问题 [#14263](https://github.com/pingcap/tidb/pull/14263) -- 新增 `tidb_session_statement_pessimistic_retry_count` 监控项，用于监控悲观事务加锁失败后重试次数 [#14619](https://github.com/pingcap/tidb/pull/14619) -- 修复 `show binding` 语句权限检查不正确的问题 [#14618](https://github.com/pingcap/tidb/pull/14618) -- 修复由于 backoff 的逻辑里没有检查 killed 标记，导致 kill 无法正确执行的问题 [#14614](https://github.com/pingcap/tidb/pull/14614) -- 通过减少持有内部锁的时间来提高 statement summary 的性能 [#14627](https://github.com/pingcap/tidb/pull/14627) -- 修复 TiDB 从字符串解析成时间与 MySQL 不兼容的问题 [#14570](https://github.com/pingcap/tidb/pull/14570) -- 新增审计日志记录用户登录失败的功能 [#14620](https://github.com/pingcap/tidb/pull/14620) -- 新增 `tidb_session_ statement_lock_keys_count` 监控项，用于监控悲观事务的 lock keys 的数量 [#14634](https://github.com/pingcap/tidb/pull/14634) -- 修复 json 对 `&` `<` `>` 等字符输出转义不正确的问题 [#14637](https://github.com/pingcap/tidb/pull/14637) -- 修复 hash-join 在建 hash-table 时由于内存使用过多导致系统 panic 的问题 [#14642](https://github.com/pingcap/tidb/pull/14642) -- 修复 SQL 绑定处理不合法记录时处理逻辑不正确导致 panic 的问题 [#14645](https://github.com/pingcap/tidb/pull/14645) -- 修复 Decimal 除法计算与 MySQL 不兼容的问题，Decimal 除法计算中增加 Truncated 错误检测 [#14673](https://github.com/pingcap/tidb/pull/14673) -- 修复给用户授权不存在的表执行成功的问题 [#14611](https://github.com/pingcap/tidb/pull/14611) - -## TiKV - -+ Raftstore - - 修复由于 Region merge 失败导致系统 Panic [#6460](https://github.com/tikv/tikv/issues/6460) 或者数据丢失 [#598](https://github.com/tikv/tikv/issues/5981) 的问题 [#6481](https://github.com/tikv/tikv/pull/6481) - - 支持 yield 优化调度公平性，支持预迁移 leader 优化 leader 调度的稳定性 [#6563](https://github.com/tikv/tikv/pull/6563) - -## PD - -- 当系统流量有变化时，系统自动更新 Region 缓存信息，解决缓存失效的问题 [#2103](https://github.com/pingcap/pd/pull/2103) -- 采用 leader 租约时间确定 TSO 的有效时间 [#2117](https://github.com/pingcap/pd/pull/2117) - -## Tools - -+ TiDB Binlog - - Drainer 支持 relay log [#893](https://github.com/pingcap/tidb-binlog/pull/893) -+ TiDB Lightning - - 优化配置项，部分配置项在没有设置的时候使用默认配置 [#255](https://github.com/pingcap/tidb-lightning/pull/255) - - 修复在非 server mode 模式下 web 界面无法打开的问题 [#259](https://github.com/pingcap/tidb-lightning/pull/259) - -## TiDB Ansible - -- 修复某些场景获取不到 PD Leader 导致命令执行失败的问题 [#1121](https://github.com/pingcap/tidb-ansible/pull/1121) -- TiDB Dashboard 新增 `Deadlock Detect Duration` 监控项 [#1127](https://github.com/pingcap/tidb-ansible/pull/1127) -- TiDB Dashboard 新增 `Statement Lock Keys Count` 监控项 [#1132](https://github.com/pingcap/tidb-ansible/pull/1132) -- TiDB Dashboard 新增 `Statement Pessimistic Retry Count` 监控项 [#1133](https://github.com/pingcap/tidb-ansible/pull/1133) diff --git a/v3.1/releases/3.0.2.md b/v3.1/releases/3.0.2.md deleted file mode 100644 index 99d71d4b5e84..000000000000 --- a/v3.1/releases/3.0.2.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: TiDB 3.0.2 Release Notes -category: Releases ---- - -# TiDB 3.0.2 Release Notes - -发版日期：2019 年 8 月 7 日 - -TiDB 版本：3.0.2 - -TiDB Ansible 版本：3.0.2 - -## TiDB - -+ SQL 优化器 - - 修复当同一张表在查询里出现多次且逻辑上查询结果恒为空时报错 “Can’t find column in schema” 的问题 [#11247](https://github.com/pingcap/tidb/pull/11247) - - 修复了 `TIDB_INLJ` Hint 无法以指定表为 Inner 表构建 IndexJoin 时仍，会强制将其作为 Outer 表构建 IndexJoin，同时 Hint 可能会在不应生效的地方生效的错误，该错误是由于强制选取 IndexJoin 的判断逻辑有误，以及对表别名的处理有误导致的；该错误仅对包含 `TIDB_INLJ` 的查询产生影响 [#11362](https://github.com/pingcap/tidb/pull/11362) - - 修复某些情况下（例如 `SELECT IF(1,c,c) FROM t`），查询结果的列名称不正确的问题 [#11379](https://github.com/pingcap/tidb/pull/11379) - - 修复 `LIKE` 表达式某些情况下被隐式转换为 0，导致诸如 `SELECT 0 LIKE 'a string'` 返回结果为 `TRUE` 的问题 [#11411](https://github.com/pingcap/tidb/pull/11411) - - 支持在 `SHOW` 语句中使用子查询，现在可以支持诸如 `SHOW COLUMNS FROM tbl WHERE FIELDS IN (SELECT 'a')` 的写法 [#11459](https://github.com/pingcap/tidb/pull/11459) - - 修复 `outerJoinElimination` 优化规则没有正确处理列的别名，导致找不到聚合函数的相关列而查询报错的问题；改进了优化过程中对别名的解析，以使得优化可以覆盖更多类型的查询 [#11377](https://github.com/pingcap/tidb/pull/11377) - - 修复 Window Function 中多个违反语义约束（例如 `UNBOUNDED PRECEDING` 不允许在 Frame 定义的最后）时没有报错的问题 [#11543](https://github.com/pingcap/tidb/pull/11543) - - 修复 `ERROR 3593 (HY000): You cannot use the window function FUNCTION_NAME in this context` 报错信息中，`FUNCTION_NAME` 不为小写的问题，导致与 MySQL 不兼容 [#11535](https://github.com/pingcap/tidb/pull/11535) - - 修复 Window Function 中 `IGNORE NULLS` 语法尚未实现，但使用时没有报错的问题 [#11593](https://github.com/pingcap/tidb/pull/11593) - - 修复优化器对时间类型数据的等值条件代价估算不准确的问题 [#11512](https://github.com/pingcap/tidb/pull/11512) - - 支持根据反馈信息对统计信息 Top-N 进行更新 [#11507](https://github.com/pingcap/tidb/pull/11507) -+ SQL 执行引擎 - - 修复 `INSERT` 函数在参数中包含 `NULL` 时，返回值不为 `NULL` 的问题 [#11248](https://github.com/pingcap/tidb/pull/11248) - - 修复 `ADMIN CHECKSUM` 语句在检查分区表时计算结果不正确的问题 [#11266](https://github.com/pingcap/tidb/pull/11266) - - 修复 INDEX JOIN 在使用前缀索引时可能结果不正确的问题 [#11246](https://github.com/pingcap/tidb/pull/11246) - - 修复 `DATE_ADD` 函数在进行涉及微秒的日期减法时，没有正确地对日期的小数位数进行对齐导致结果不正确的问题 [#11288](https://github.com/pingcap/tidb/pull/11288) - - 修复 `DATE_ADD` 函数没有正确地对 INTERVAL 中的负数部分处理导致结果不正确的问题 [#11325](https://github.com/pingcap/tidb/pull/11325) - - 修复 `Mod(%)`、`Multiple(*)` 和 `Minus(-)` 返回结果为 0 时，在小数位数较多（例如 `select 0.000 % 0.11234500000000000000`）的情况下与 MySQL 位数不一致的问题 [#11251](https://github.com/pingcap/tidb/pull/11251) - - 修复 `CONCAT` 和 `CONCAT_WS` 函数在返回结果长度超过 `max_allowed_packet` 时，没有正确返回 NULL 和 Warning 的问题 [#11275](https://github.com/pingcap/tidb/pull/11275) - - 修复 `SUBTIME` 和 `ADDTIME` 函数在参数不合法时，没有正确返回 NULL 和 Warning 的问题 [#11337](https://github.com/pingcap/tidb/pull/11337) - - 修复 `CONVERT_TZ` 函数在参数不合法时，没有正确返回 NULL 的问题 [#11359](https://github.com/pingcap/tidb/pull/11359) - - `EXPLAIN ANALYZE` 结果中添加了 `MEMORY` 列，显示 QUERY 的内存使用 [#11418](https://github.com/pingcap/tidb/pull/11418) - - `EXPLAIN` 结果中，为笛卡尔积 Join 添加了 `CARTESIAN` 关键字 [#11429](https://github.com/pingcap/tidb/pull/11429) - - 修复类型为 FLOAT 和 DOUBLE 的自增列数据不正确的问题 [#11385](https://github.com/pingcap/tidb/pull/11385) - - 修复 Dump Pseudo Statistics 时，由于部分信息为 `nil` 导致 panic 的问题 [#11460](https://github.com/pingcap/tidb/pull/11460) - - 修复常量折叠优化导致 `SELECT … CASE WHEN … ELSE NULL …` 查询结果不正确的问题 [#11441](https://github.com/pingcap/tidb/pull/11441) - - 修复 `floatStrToIntStr` 对诸如 `+999.9999e2` 的输入没有正确解析的问题 [#11473](https://github.com/pingcap/tidb/pull/11473) - - 修复 `DATE_ADD` 和 `DATE_SUB` 函数结果超出合法范围时，某些情况下不会返回 `NULL` 的问题 [#11476](https://github.com/pingcap/tidb/pull/11476) - - 修复长字符串转换为整型时，若字符串包含不合法字符，转换结果与 MySQL 不一致的问题 [#11469](https://github.com/pingcap/tidb/pull/11469) - - 修复 `REGEXP BINARY` 函数对大小写敏感，导致与 MySQL 不兼容的问题 [#11504](https://github.com/pingcap/tidb/pull/11504) - - 修复 `GRANT ROLE` 语句在接受 `CURRENT_ROLE` 时报错的问题；修复 `REVOKE ROLE` 语句没有能够正确收回 `mysql.default_role` 权限的问题 [#11356](https://github.com/pingcap/tidb/pull/11356) - - 修复执行诸如 `SELECT ADDDATE('2008-01-34', -1)` 时，`Incorrect datetime value` Warning 信息的显示格式问题 [#11447](https://github.com/pingcap/tidb/pull/11447) - - 修复将 JSON 数据中的 Float 类型字段转为 Int 类型溢出时，报错信息中应当提示 `constant … overflows bigint` 而不应当为 `constant … overflows float` 的问题 [#11534](https://github.com/pingcap/tidb/pull/11534) - - 修复 `DATE_ADD` 函数接受 `FLOAT`、`DOUBLE` 和 `DECIMAL` 类型的列参数时，没有正确地进行类型转换而导致结果可能不正确的问题 [#11527](https://github.com/pingcap/tidb/pull/11527) - - 修复 `DATE_ADD` 函数中，没有正确处理 INTERVAL 小数部分的符号而导致结果不正确的问题 [#11615](https://github.com/pingcap/tidb/pull/11615) - - 修复 `Ranger` 没有正确处理前缀索引，导致 Index Lookup Join 中包含前缀索引时，查询结果不正确的问题 [#11565](https://github.com/pingcap/tidb/pull/11565) - - 修复 `NAME_CONST` 函数第二个参数为负数时执行会报 `Incorrect arguments to NAME_CONST` 的问题 [#11268](https://github.com/pingcap/tidb/pull/11268) - - 修复一条 SQL 语句在涉及当前时间计算时（例如 `CURRENT_TIMSTAMP` 或者 `NOW`），多次取当前时间值，结果与 MySQL不兼容的问题：现在同一条SQL语句中取当前时间时，均使用相同值 [#11394](https://github.com/pingcap/tidb/pull/11394) - - 修复了父 Executor `Close` 出现错误时，没有对 `ChildExecutor` 调用 `Close` 的问题，该问题可能导致 `KILL` 语句失效时，子 `ChildExecutor` 没有关闭而导致 Goroutine 泄露 [#11576](https://github.com/pingcap/tidb/pull/11576) -+ Server - - 修复 `LOAD DATA` 处理 CSV 文件中缺失的 `TIMESTAMP` 字段时，自动补充的值是 0 不是当前时间戳的问题 [#11250](https://github.com/pingcap/tidb/pull/11250) - - 修复 `SHOW CREATE USER` 语句没有正确检查相关权限的问题，以及 `SHOW CREATE USER CURRENT_USER()` 结果中 USER、HOST 可能不正确的问题 [#11229](https://github.com/pingcap/tidb/pull/11229) - - 修复在 JDBC 中使用 `executeBatch` 可能返回结果不正确的问题 [#11290](https://github.com/pingcap/tidb/pull/11290) - - TiKV Server 在更换端口时，减少 Streaming Client 的报错信息的日志打印 [#11370](https://github.com/pingcap/tidb/pull/11370) - - 优化 Streaming Client 在重新与 TiKV Server 连接时的逻辑：现在 Streaming Client 不会长时间被 Block [#11372](https://github.com/pingcap/tidb/pull/11372) - - `INFORMATION_SCHEMA.TIDB_HOT_REGIONS` 中新增 `REGION_ID`[#11350](https://github.com/pingcap/tidb/pull/11350) - - 取消了从 PD API 获取 Region 相关信息时的超时时间，保证在 Region 数量较大时，调用 TiDB API `http://{TiDBIP}:10080/regions/hot` 不会因为 PD 超时而获取失败 [#11383](https://github.com/pingcap/tidb/pull/11383) - - 修复 HTTP API 中，与 Region 相关的请求没有返回分区表相关的 Region 问题 [#11466](https://github.com/pingcap/tidb/pull/11466) - - 做以下改动以降低用户手动验证悲观锁时，操作较慢导致锁超时的概率 [#11521](https://github.com/pingcap/tidb/pull/11521)： - - 悲观锁的默认 TTL 时间由 30 秒提升为 40 秒 - - 最大允许的 TTL 时间由 60 秒提升为 120 秒 - - 悲观锁的持续时间改为从第一次 `LockKeys` 请求时开始计算 - - 修改 TiKV Client 中的 `SendRequest` 函数逻辑：当连接无法建立时，由一直等待改为尽快尝试连接其他 Peer [#11531](https://github.com/pingcap/tidb/pull/11531) - - 优化 Region Cache：当一个 Store 下线，同时另一个 Store 以同样的地址上线时，将已下线的 Store 标记为失效以尽快在 Cache 中更新 Store 的信息 [#11567](https://github.com/pingcap/tidb/pull/11567) - - 为 `http://{TiDB_ADDRESS:TIDB_IP}/mvcc/key/{db}/{table}/{handle}` API 的返回结果添加 Region ID 信息 [#11557](https://github.com/pingcap/tidb/pull/11557) - - 修复 Scatter Table API 没有对 Range Key 进行转义导致 Scatter Table 不生效的问题 [#11298](https://github.com/pingcap/tidb/pull/11298) - - 优化 Region Cache：当 Region 所在的 Store 无法访问时，将对应的 Store 信息标记失效以避免对这些 Store 的访问造成查询性能下降 [#11498](https://github.com/pingcap/tidb/pull/11498) - - 修复了多次 DROP 同名 DATABASE 后，DATABASE 内的表结构仍然能够通过 HTTP API 获取到的错误 [#11585](https://github.com/pingcap/tidb/pull/11585) -+ DDL - - 修复在非字符串类型且长度为 0 的列建立索引时出错的问题 [#11214](https://github.com/pingcap/tidb/pull/11214) - - 禁止对带有外键约束和全文索引的列进行修改（注意：TiDB 仍然仅在语法上支持外键约束和全文索引）[#11274](https://github.com/pingcap/tidb/pull/11274) - - 修复并发使用 `ALTER TABLE` 语句更改的位置和列的默认值时，可能导致列的索引 Offset 出错的问题 [#11346](https://github.com/pingcap/tidb/pull/11346) - - 修复解析 JSON 文本的两个问题： - - `ConvertJSONToFloat` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#11433](https://github.com/pingcap/tidb/pull/11433) - - `ConvertJSONToInt` 中使用 `int64` 作为 `uint64` 的中间解析结果，导致精度溢出的问题 [#11551](https://github.com/pingcap/tidb/pull/11551) - - 禁止 DROP 自增列索引，修复因为 DROP 自增列上的索引导致自增列结果可能出错的问题 [#11399](https://github.com/pingcap/tidb/pull/11399) - - 修复以下问题 [#11492](https://github.com/pingcap/tidb/pull/11492)： - - 修复显式指定列的排序规则但没有指定字符集时，列的字符集与排序规则不一致的问题 - - 修复 `ALTER TABLE … MODIFY COLUMN` 指定的字符集和排序规则冲突时，没有正确报错的问题 - - 修复 `ALTER TABLE … MODIFY COLUMN` 指定多次字符集和排序规则时，行为与 MySQL 不兼容的问题 - - 为 `TRACE` 语句的结果添加子查询的 trace 细节信息 [#11458](https://github.com/pingcap/tidb/pull/11458) - - 优化 `ADMIN CHECK TABLE` 执行性能，大幅降低了语句的执行耗时 [#11547](https://github.com/pingcap/tidb/pull/11547) - - 为 `SPLIT TABLE … REGIONS/INDEX` 添加了返回结果，结果包含 `TOTAL_SPLIT_REGION` 和 `SCATTER_FINISH_RATIO` 展示在超时时间内，切分成功的 Region 数量 [#11484](https://github.com/pingcap/tidb/pull/11484) - - 修复 `ON UPDATE CURRENT_TIMESTAMP` 作为列的属性且指定浮点精度时，`SHOW CREATE TABLE` 等语句显示精度不完整的问题 [#11591](https://github.com/pingcap/tidb/pull/11591) - - 修复一个虚拟生成列的表达式中含有另一个虚拟生成列时，该列的索引结果不能正确被计算的问题 [#11475](https://github.com/pingcap/tidb/pull/11475) - - 修复 `ALTER TABLE … ADD PARTITION …` 语句中，`VALUE LESS THAN` 后不能出现负号的问题 [#11581](https://github.com/pingcap/tidb/pull/11581) -+ Monitor - - 修复 `TiKVTxnCmdCounter` 监控指标没有注册导致数据没有被收集上报的问题 [#11316](https://github.com/pingcap/tidb/pull/11316) - - 为 Bind Info 添加了 `BindUsageCounter`、`BindTotalGauge` 和 `BindMemoryUsage` 监控指标 [#11467](https://github.com/pingcap/tidb/pull/11467) - -## TiKV - -- 修复由于 Raft Log 写入不及时可能导致 TiKV panic 的 bug [#5160](https://github.com/tikv/tikv/pull/5160) -- 修复 TiKV panic 后 panic 信息不会写入日志的 bug [#5198](https://github.com/tikv/tikv/pull/5198) -- 修复了悲观事务下 Insert 行为可能不正确的 bug [#5203](https://github.com/tikv/tikv/pull/5203) -- 降低一部分不需要人工干预的日志输出级别为 INFO [#5193](https://github.com/tikv/tikv/pull/5193) -- 提高存储引擎大小监控项的准确程度 [#5200](https://github.com/tikv/tikv/pull/5200) -- 提高 tikc-ctl 中 Region size 的准确程度 [#5195](https://github.com/tikv/tikv/pull/5195) -- 提高悲观锁死锁检测性能 [#5192](https://github.com/tikv/tikv/pull/5192) -- 提高 Titan 存储引擎 GC 性能 [#5197](https://github.com/tikv/tikv/pull/5197) - -## PD - -- 修复 Scatter Region 调度器不能工作的 bug [#1642](https://github.com/pingcap/pd/pull/1642) -- 修复 pd-ctl 中不能进行 merge Region 操作的 bug [#1653](https://github.com/pingcap/pd/pull/1653) -- 修复 pd-ctl 中不能进行 remove-tombstone 操作的 bug [#1651](https://github.com/pingcap/pd/pull/1651) -- 修复 scan region 不能找到 key 范围相交的 Region 的问题 [#1648](https://github.com/pingcap/pd/pull/1648) -- 增加重试机制确保 PD 增加成员成功 [#1643](https://github.com/pingcap/pd/pull/1643) - -## Tools - -TiDB Binlog - -- 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#687](https://github.com/pingcap/tidb-binlog/pull/687) -- Drainer 增加 `node-id` 配置，用于指定固定逻辑 Drainer [#684](https://github.com/pingcap/tidb-binlog/pull/684) - -TiDB Lightning - -- 修复 2 个 checksum 同时运行的情况下，`tikv_gc_life_time` 没有正常修改回原本值的问题 [#218](https://github.com/pingcap/tidb-lightning/pull/218) -- 增加启动时配置项检查功能，遇到不合法配置项会退出运行并给出错误信息 [#217](https://github.com/pingcap/tidb-lightning/pull/217) - -## TiDB Ansible - -- 修复 Disk Performance 监控把 second 作为 ms 的单位错误的问题 [#840](https://github.com/pingcap/tidb-ansible/pull/840) -- Spark 新增 log4j 日志配置 [#841](https://github.com/pingcap/tidb-ansible/pull/841) -- 修复在开启了 Binlog 并且设置了 Kafka 或者 ZooKeeper 时导致生成的 Prometheus 配置文件格式错误的问题 [#844](https://github.com/pingcap/tidb-ansible/pull/844) -- 修复生成的 TiDB 配置文件中遗漏 `pessimistic-txn` 配置参数的问题 [#850](https://github.com/pingcap/tidb-ansible/pull/850) -- TiDB Dashboard 新增和优化 Metrics [#853](https://github.com/pingcap/tidb-ansible/pull/853) -- TiDB Dashboard 上每个监控项增加描述 [#854](https://github.com/pingcap/tidb-ansible/pull/854) -- 新增 TiDB Summary Dashboard，用于更好的查看集群状态和排查问题 [#855](https://github.com/pingcap/tidb-ansible/pull/855) -- TiKV Dashboard 更新 Allocator Stats 监控项 [#857](https://github.com/pingcap/tidb-ansible/pull/857) -- 修复 Node Exporter 的告警表达式单位错误的问题 [#860](https://github.com/pingcap/tidb-ansible/pull/860) -- 更新 tispark jar 包为 v2.1.2 版本 [#862](https://github.com/pingcap/tidb-ansible/pull/862) -- 更新 Ansible Task 功能描述 [#867](https://github.com/pingcap/tidb-ansible/pull/867) -- 兼容 TiDB 变更，TiDB Dashboard 更新 Local reader requests 监控项的表达式 [#874](https://github.com/pingcap/tidb-ansible/pull/874) -- Overview Dashboard 更新 TiKV Memory 监控项的表达式，修复监控显示错误的问题 [#879](https://github.com/pingcap/tidb-ansible/pull/879) -- 移除 Kafka 模式 Binlog 的支持 [#878](https://github.com/pingcap/tidb-ansible/pull/878) -- 修复执行 `rolling_update.yml` 操作时，切换 PD Leader 失效的 Bug [#887](https://github.com/pingcap/tidb-ansible/pull/887) diff --git a/v3.1/releases/3.0.3.md b/v3.1/releases/3.0.3.md deleted file mode 100644 index 6a3aa4260a59..000000000000 --- a/v3.1/releases/3.0.3.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: TiDB 3.0.3 Release Notes -category: Releases ---- - -# TiDB 3.0.3 Release Notes - -发版日期：2019 年 8 月 29 日 - -TiDB 版本：3.0.3 - -TiDB Ansible 版本：3.0.3 - -## TiDB - -+ SQL 优化器 - - 添加 `opt_rule_blacklist` 表，用于禁用一些逻辑优化规则，比如 `aggregation_eliminate`，`column_prune` 等 [#11658](https://github.com/pingcap/tidb/pull/11658) - - 修复 Index join 的 join key 中使用前缀索引或者使用 unsigned 的索引列等于负数时结果不正确的问题 -[#11759](https://github.com/pingcap/tidb/pull/11759) - - 修复 `create … binding ...` 的 Select 语句中带有 `”` 或者 `\` 时解析报错的问题 [#11726](https://github.com/pingcap/tidb/pull/11726) -+ SQL 执行引擎 - - 修复 `Quote` 函数处理 null 值的返回值类型出错的问题 [#11619](https://github.com/pingcap/tidb/pull/11619) - - 修复 Max 和 Min 在推导类型时没有去除 NotNullFlag 导致 `ifnull` 结果错误的问题 [#11641](https://github.com/pingcap/tidb/pull/11641) - - 修复对字符形式的 Bit 类型数据比较出错的问题 [#11660](https://github.com/pingcap/tidb/pull/11660) - - 减少需要顺序读取数据的并发度，以降低 OOM 出现概率 [#11679](https://github.com/pingcap/tidb/pull/11679) - - 修复对应含有多个参数的内置函数（如 `if`、`coalesce` 等），在多个参数都为 unsigned 时类型推导不正确的问题 [#11621](https://github.com/pingcap/tidb/pull/11621) - - 修复 `Div` 函数处理 unsigned 的 decimal 类型时与 MySQL 行为不兼容的问题 [#11813](https://github.com/pingcap/tidb/pull/11813) - - 修复执行修改 Pump/Drainer 状态的 SQL 时会报 panic 的问题 [#11827](https://github.com/pingcap/tidb/pull/11827) - - 修复在 Autocommit = 1 且没有 begin 的时，`select ... for update` 出现 panic 的问题 [#11736](https://github.com/pingcap/tidb/pull/11736) - - 修复执行 `set default role` 语句时权限检查出错的问题 [#11777](https://github.com/pingcap/tidb/pull/11777) - - 修复执行 `create user` 和`drop user` 语句出现权限检查错误的问题 [#11814](https://github.com/pingcap/tidb/pull/11814) - - 修复 `select ... for update` 在构建为 PointGetExecutor 时会重试的问题 [#11718](https://github.com/pingcap/tidb/pull/11718) - - 修复 Window function 处理 Partition 时边界出错的问题 [#11825](https://github.com/pingcap/tidb/pull/11825) - - 修复 `time` 函数在处理错误格式参数时直接断链接的问题 [#11893](https://github.com/pingcap/tidb/pull/11893) - - 修复 Window function 没有检查传入参数的问题 [#11705](https://github.com/pingcap/tidb/pull/11705) - - 修复 Explain 查看的 Plan 结果跟真实执行的 Plan 结果不一致的问题 [#11186](https://github.com/pingcap/tidb/pull/11186) - - 修复 Window function 内存重复引用导致崩溃或结果不正确的问题 [#11823](https://github.com/pingcap/tidb/pull/11823) - - 修复 Slow log 里面 Succ 字段信息错误的问题 [#11887](https://github.com/pingcap/tidb/pull/11887) -+ Server - - 重命名 `tidb_back_off_weight` 变量为 `tidb_backoff_weight` [#11665](https://github.com/pingcap/tidb/pull/11665) - - 更新与当前 TiDB 兼容的最低版本的 TiKV 为 v3.0.0 的信息 [#11618](https://github.com/pingcap/tidb/pull/11618) - - 支持 `make testSuite` 来确保测试中的 Suite 都被正确使用 [#11685](https://github.com/pingcap/tidb/pull/11685) -+ DDL - - 禁止不支持的 Partition 相关的 DDL 的执行，其中包括修改 Partition 类型，同时删除多个 Partition 等 [#11373](https://github.com/pingcap/tidb/pull/11373) - - 禁止 Generated Column 的位置在它依赖的列前 [#11686](https://github.com/pingcap/tidb/pull/11686) - - 修改添加索引操作中使用的 `tidb_ddl_reorg_worker_cnt` 和 `tidb_ddl_reorg_batch_size` 变量的默认值 [#11874](https://github.com/pingcap/tidb/pull/11874) -+ Monitor - - Backoff 监控添加类型，且补充之前没有统计到的 Backoff，比如 commit 时遇到的 Backoff [#11728](https://github.com/pingcap/tidb/pull/11728) - -## TiKV - -- 修复 ReadIndex 请求可能由于重复 Context 而无法响应请求的问题 [#5256](https://github.com/tikv/tikv/pull/5256) -- 修复 `PutStore` 过早而引起一些调度造成抖动的问题 [#5277](https://github.com/tikv/tikv/pull/5277) -- 修复 Region Heartbeat 上报的时间戳不准的问题 [#5296](https://github.com/tikv/tikv/pull/5296) -- 剔除 share block cache 信息减少 coredump 文件大小 [#5322](https://github.com/tikv/tikv/pull/5322) -- 修复 Region merge 中会引起 TiKV panic 的问题 [#5291](https://github.com/tikv/tikv/pull/5291) -- 加快死锁检测器器的 leader 变更检查 [#5317](https://github.com/tikv/tikv/pull/5317) -- 使用 grpc env 创建 deadlock 的客户端 [#5346](https://github.com/tikv/tikv/pull/5346) -- 添加 `config-check` 检查配置是否正确 [#5349](https://github.com/tikv/tikv/pull/5349) -- 修复 ReadIndex 请求在没有 leader 情况下不返回的问题 [#5351](https://github.com/tikv/tikv/pull/5351) - -## PD - -- `pdctl` 返回成功信息 [#1685](https://github.com/pingcap/pd/pull/1685) - -## Tools - -+ TiDB Binlog - - 将 Drainer `defaultBinlogItemCount` 默认值从 65536 改为 512，减少 Drainer 启动时 OOM 的情况 [#721](https://github.com/pingcap/tidb-binlog/pull/721) - - 优化 Pump server 下线处理逻辑，避免出现 Pump 下线阻塞的问题 [#701](https://github.com/pingcap/tidb-binlog/pull/701) -+ TiDB Lightning - - 导入时默认过滤系统库 `mysql`，`information_schema`，`performance_schema`，`sys` [#225](https://github.com/pingcap/tidb-lightning/pull/225) - -## TiDB Ansible - -- 优化滚动升级 PD 的操作，提高稳定性 [#894](https://github.com/pingcap/tidb-ansible/pull/894) -- 移除当前 Grafana 版本不支持的 Grafana Collector 组件 [#892](https://github.com/pingcap/tidb-ansible/pull/892) -- 更新 TiKV 告警规则 [#898](https://github.com/pingcap/tidb-ansible/pull/898) -- 修复生成的 TiKV 配置遗漏 `pessimistic-txn` 参数的问题 [#911](https://github.com/pingcap/tidb-ansible/pull/911) -- 更新 Spark 版本为 2.4.3，同时更新 TiSpark 为兼容该 Spark 的 2.1.4 版本 [#913](https://github.com/pingcap/tidb-ansible/pull/913) [#918](https://github.com/pingcap/tidb-ansible/pull/918) diff --git a/v3.1/releases/3.0.4.md b/v3.1/releases/3.0.4.md deleted file mode 100644 index 9031256608c8..000000000000 --- a/v3.1/releases/3.0.4.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: TiDB 3.0.4 Release Notes -category: Releases ---- - -# TiDB 3.0.4 Release Notes - -发版日期：2019 年 10 月 8 日 - -TiDB 版本：3.0.4 - -TiDB Ansible 版本：3.0.4 - -- 新特性 - - 新增系统表 `performance_schema.events_statements_summary_by_digest`，用于排查 SQL 级别的性能问题 - - TiDB 的 `SHOW TABLE REGIONS` 语法新增 `WHERE` 条件子句 - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 -- 改进提升 - - TiKV 支持批量 `Split` 和空的 `Split` 命令，使得 Split 可以批量进行 - - TiKV 添加 RocksDB 双向链表支持，提升逆序扫性能 - - Ansible 新增 `iosnoop` 和 `funcslower` 两个 perf 工具，方便诊断集群状态 - - TiDB 优化慢日志输出内容，删除冗余字段 -- 行为变更 - - TiDB 修改 `txn-local-latches.enable` 默认值为 `false`，默认不启用本地事务冲突检测 - - TiDB 添加全局作用域系统变量 `tidb_txn_mode`，允许配置使用悲观锁，请注意默认情况下，TiDB 仍然使用乐观锁 - - TiDB 慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 - - TiDB 配置文件中添加 `split-region-max-num` 参数，用于调整 `SPLIT TABLE` 语法允许的最大 Region 数量 - - TiDB 修改 SQL 超出内存限制后的行为，从断开链接修改为返回 `Out Of Memory Quota` 错误 - - 为避免误操作，TiDB 默认不再允许删除列的 `AUTO_INCREMENT` 属性，当确实需要删除时，请更改系统变量 `tidb_allow_remove_auto_inc` -- 问题修复 - - TiDB 修复特殊语法 `PRE_SPLIT_REGIONS` 没有使用注释的方式向下游同步的问题 - - TiDB 修复使用游标获取 `PREPARE` + `EXECUTE` 执行结果时，慢日志不正确的问题 - - PD 修复相邻小 Region 无法 Merge 的问题 - - TiKV 修复空闲集群中文件描述符泄漏导致长期运行可能会引起 TiKV 进程异常退出的问题 -- 社区贡献者 - - 感谢以下社区贡献者参与本次发版： - - [sduzh](https://github.com/sduzh) - - [lizhenda](https://github.com/lizhenda) - -## TiDB - -- SQL 优化器 - - 修复 `Feedback` 切分查询范围出错的问题 [#12170](https://github.com/pingcap/tidb/pull/12170) - - 修改当 `SHOW STATS_BUCKETS` 结果中包含无效 Key 时的行为，将返回错误修改为使用 16 进制显示 [#12094](https://github.com/pingcap/tidb/pull/12094) - - 修复查询中包含 `SLEEP` 函数时（例如 `select 1 from (select sleep(1)) t;)`），由于列裁剪导致查询中的 `sleep(1)` 失效的问题 [#11953](https://github.com/pingcap/tidb/pull/11953) - - 当查询只关心表的行数而不关心表数据时，使用索引扫描降低 IO [#12112](https://github.com/pingcap/tidb/pull/12112) - - 当 `use index()` 中没有指定索引时不去使用任何索引，和 MySQL 兼容 (如 `explain select a from t use index();`) [#12100](https://github.com/pingcap/tidb/pull/12100) - - 严格限制统计信息 `CMSketch` 中 `TopN` 记录的数量，修复快速 `analyze` 因为超过事务大小限制而失败的问题 [#11914](https://github.com/pingcap/tidb/pull/11914) - - 修复 `Update` 语句包含子查询时，转换子查询出现的错误 [#12483](https://github.com/pingcap/tidb/pull/12483) - - 将 Limit 算子下推到 `IndexLookUpReader` 执行逻辑中优化 `select ... limit ... offset ...` 的执行性能 [#12378](https://github.com/pingcap/tidb/pull/12378) -- SQL 执行引擎 - - `PREPARED` 语句执行错误时，在日志中打印 SQL 语句 [#12191](https://github.com/pingcap/tidb/pull/12191) - - 分区表使用 `UNIX_TIMESTAMP` 函数分区时，支持分区裁剪 [#12169](https://github.com/pingcap/tidb/pull/12169) - - 修复 `AUTO INCREMENT` 分配 `MAX int64` 和 `MAX uint64` 没有报错的问题 [#12162](https://github.com/pingcap/tidb/pull/12162) - - `SHOW TABLE … REGIONS` 和 `SHOW TABLE .. INDEX … REGIONS` 语法新增 `WHERE` 条件子句 [#12123](https://github.com/pingcap/tidb/pull/12123) - - 修改 SQL 超出内存限制后的行为，从断开链接修改为返回 `Out Of Memory Quota` 错误 [#12127](https://github.com/pingcap/tidb/pull/12127) - - 修复 `JSON_UNQUOTE` 函数处理 JSON 文本结果不正确的问题 [#11955](https://github.com/pingcap/tidb/pull/11955) - - 修复 `INSERT` 语句中，第一行中为 `AUTO_INCREMENT` 列赋值，`LAST INSERT ID` 不正确的问题（例如 `insert into t (pk, c) values (1, 2), (NULL, 3)`）[#12002](https://github.com/pingcap/tidb/pull/12002) - - 修复 `PREPARE` 语句中，`GroupBY` 解析规则错误的问题 [#12351](https://github.com/pingcap/tidb/pull/12351) - - 修复点查中权限检查不正确的问题 [#12340](https://github.com/pingcap/tidb/pull/12340) - - 修复 `PREPARE` 语句类型没有记录在监控中的问题 [#12331](https://github.com/pingcap/tidb/pull/12331) - - 支持点查中表名使用别名（例如 `select * from t tmp where a = "aa"`）[#12282](https://github.com/pingcap/tidb/pull/12282) - - 修复向 BIT 类型列插入数值时，值没有作为无符号类型处理而导致插入负数报错的问题 [#12423](https://github.com/pingcap/tidb/pull/12423) - - 修复时间取整不正确的问题（例如 `2019-09-11 11:17:47.999999666` 应该被取整到 `2019-09-11 11:17:48`）[#12258](https://github.com/pingcap/tidb/pull/12258) - - 调整表达式黑名单系统表的用法（例如 `<` 与 `lt` 等价）[#11975](https://github.com/pingcap/tidb/pull/11975) - - 调整函数不存在的错误消息，添加数据库前缀（例如 `[expression:1305]FUNCTION test.std_samp does not exist`）[#12111](https://github.com/pingcap/tidb/pull/12111) -- Server - - 慢日志中添加 `Prev_stmt` 字段，用于最后一条语句是 `COMMIT` 时输出前一条语句 [#12180](https://github.com/pingcap/tidb/pull/12180) - - 优化慢日志输出内容，删除冗余字段 [#12144](https://github.com/pingcap/tidb/pull/12144) - - 修改 `txn-local-latches.enable` 默认值为 `false`，默认不启用本地事务冲突检测 [#12095](https://github.com/pingcap/tidb/pull/12095) - - 将慢日志中的 `Index_ids` 字段替换为 `Index_names` 字段，提升慢日志易用性 [#12061](https://github.com/pingcap/tidb/pull/12061) - - 添加全局作用域系统变量 `tidb_txn_mode`，允许配置使用悲观锁 [#12049](https://github.com/pingcap/tidb/pull/12049) - - 慢日志中添加 `Backoff` 字段，用来记录 2PC Commit 阶段的 Backoff 信息 [#12335](https://github.com/pingcap/tidb/pull/12335) - - 修复使用游标获取 `PREPARE` + `EXECUTE` 执行结果时，慢日志不正确的问题（例如 `PREPARE stmt1FROM SELECT * FROM t WHERE a > ?; EXECUTE stmt1 USING @variable`）[#12392](https://github.com/pingcap/tidb/pull/12392) - - 支持使用 `tidb_enable_stmt_summary`，开启后会对 SQL 语句进行统计，并可以使用系统表 `performance_schema.events_statements_summary_by_digest` 查询统计结果 [#12308](https://github.com/pingcap/tidb/pull/12308) - - 调整了 tikv-client 中部分日志级别（例如由于连接断开使得打印的 `batchRecvLoop fails` 日志级别由 `ERROR` 改为 `INFO`）[#12383](https://github.com/pingcap/tidb/pull/12383) -- DDL - - 新增变量 `tidb_allow_remove_auto_inc`，默认禁止删除列 `AUTO INCREMENT` 属性 [#12145](https://github.com/pingcap/tidb/pull/12145) - - 修复 TiDB 特殊语法 `PRE_SPLIT_REGIONS` 没有使用注释的方式向下游同步，导致下游数据库报错的问题 [#12120](https://github.com/pingcap/tidb/pull/12120) - - 在配置文件中添加 `split-region-max-num` 参数，使得 `SPLIT TABLE` 语法允许的最大 Region 数量可调整，该参数默认值 `10000` [#12097](https://github.com/pingcap/tidb/pull/12079) - - 支持将一个 Region 切分成多个 Region，并修复打散 Region 超时的问题 [#12343](https://github.com/pingcap/tidb/pull/12343) - - 修复当索引包含自增列，并且该自增列被两个索引引用时删除失败的问题 [#12344](https://github.com/pingcap/tidb/pull/12344) -- Monitor - - 增加监控指标 `connection_transient_failure_count`，用于统计 `tikvclient` 的 gRPC 连接错误数量 [#12093](https://github.com/pingcap/tidb/pull/12093) - -## TiKV - -- Raftstore - - 修复 Raftstore 统计空 Region 中 key 个数不准确问题 [#5414](https://github.com/tikv/tikv/pull/5414) - - 添加 RocksDB 双向链表支持，提升逆序扫性能 [#5368](https://github.com/tikv/tikv/pull/5368) - - 支持 PD 批量 `Split` 和空的 `Split` 命令, 使得 Split 可以批量进行，提高 Split 效率 [#5470](https://github.com/tikv/tikv/pull/5470) -- Server - - 修复查看版本命令的输出格式与 2.X 格式不一致的问题 [#5501](https://github.com/tikv/tikv/pull/5501) - - 更新 Titan 至 3.0 分支最新版本 [#5517](https://github.com/tikv/tikv/pull/5517) - - 更新 grpcio 至 v0.4.5 版本 [#5523](https://github.com/tikv/tikv/pull/5523) - - 修复 gRPC coredump 问题，支持内存共享，以避免此处引起 OOM [#5524](https://github.com/tikv/tikv/pull/5524) - - 修复空闲集群中文件描述符泄漏导致长期运行可能会引起 TiKV 进程异常退出的问题 [#5567](https://github.com/tikv/tikv/pull/5567) -- Storage - - 支持悲观锁事务心跳检测 API，以使得 TiDB 的悲观锁行为与 MySQL 尽量一致 [#5507](https://github.com/tikv/tikv/pull/5507) - - 修复部分情况下点查性能较低的问题 [#5495](https://github.com/tikv/tikv/pull/5495) [#5463](https://github.com/tikv/tikv/pull/5463) - -## PD - -- 修复相邻小 Region 无法 Merge 的问题 [#1726](https://github.com/pingcap/pd/pull/1726) -- 修复 pd-ctl 的 TLS 启用参数失效问题 [#1738](https://github.com/pingcap/pd/pull/1738) -- 修复可能导致 PD operator 被意外移除的线程安全问题 [#1734](https://github.com/pingcap/pd/pull/1734) -- Region syncer 支持 TLS [#1739](https://github.com/pingcap/pd/pull/1739) - -## Tools - -- TiDB Binlog - - Reparo 新增 `worker-count` 和 `txn-batch` 配置项，用于控制恢复速率 [#746](https://github.com/pingcap/tidb-binlog/pull/746) - - Drainer 优化内存使用，提升同步执行效率 [#737](https://github.com/pingcap/tidb-binlog/pull/737) -- TiDB Lightning - - 修复从 checkpoint 点重新导入可能会导致 TiDB Lightning 崩溃的问题 [#237](https://github.com/pingcap/tidb-lightning/pull/237) - - 修改计算 `AUTO_INCREMENT` 的算法，降低溢出的风险 [#227](https://github.com/pingcap/tidb-lightning/pull/227) - -## TiDB Ansible - -- 更新 TiSpark 版本至 2.2.0 [#926](https://github.com/pingcap/tidb-ansible/pull/926) -- 更新 TiDB 配置项 `pessimistic_txn` 的默认值为 `true` [#933](https://github.com/pingcap/tidb-ansible/pull/933) -- 新增更多系统级别监控到 `node_exporter` [#938](https://github.com/pingcap/tidb-ansible/pull/938) -- 新增 `iosnoop` 和 `funcslower` 两个 perf 工具，方便诊断集群状态 [#946](https://github.com/pingcap/tidb-ansible/pull/946) -- Ansible 的 Raw 模块更新成 Shell 模块，解决密码过期等场景发生的长时间等待问题 [#949](https://github.com/pingcap/tidb-ansible/pull/949) -- 更新 TiDB 配置项 `txn_local_latches` 的默认值为 `false` -- 优化 Grafana dashboard 监控项和告警规则 [#962](https://github.com/pingcap/tidb-ansible/pull/962) [#963](https://github.com/pingcap/tidb-ansible/pull/963) [#969](https://github.com/pingcap/tidb-ansible/pull/963) -- 新增配置文件检查功能，在部署和升级之前检查配置文件是否正确 [#934](https://github.com/pingcap/tidb-ansible/pull/934) [#972](https://github.com/pingcap/tidb-ansible/pull/972) diff --git a/v3.1/releases/3.0.5.md b/v3.1/releases/3.0.5.md deleted file mode 100644 index 1245eaa65f9d..000000000000 --- a/v3.1/releases/3.0.5.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: TiDB 3.0.5 Release Notes -category: Releases ---- - -# TiDB 3.0.5 Release Notes - -发版日期：2019 年 10 月 25 日 - -TiDB 版本：3.0.5 - -TiDB Ansible 版本：3.0.5 - -## TiDB - -+ SQL 优化器 - - 支持对 Window Functions 进行边界检查 [#12404](https://github.com/pingcap/tidb/pull/12404) - - 修复 partition 表上的 `IndexJoin` 返回错误结果的问题 [#12712](https://github.com/pingcap/tidb/pull/12712) - - 修复外连接 Apply 算子上层的 `ifnull` 函数返回错误结果的问题 [#12694](https://github.com/pingcap/tidb/pull/12694) - - 修复当 `UPDATE` 的 `where` 条件中包含子查询时更新失败的问题 [#12597](https://github.com/pingcap/tidb/pull/12597) - - 修复当查询条件中包含 `cast` 函数时 outer join 被错误转化为 inner join 的问题 [#12790](https://github.com/pingcap/tidb/pull/12790) - - 修复 `AntiSemiJoin` 的 join 条件中错误的表达式传递 [#12799](https://github.com/pingcap/tidb/pull/12799) - - 修复初始化统计信息时由于浅拷贝造成的统计信息出错问题 [#12817](https://github.com/pingcap/tidb/pull/12817) - - 修复 TiDB 中 `str_to_date` 函数在日期字符串和格式化字符串不匹配的情况下，返回结果与 MySQL 不一致的问题 [#12725](https://github.com/pingcap/tidb/pull/12725) -+ SQL 执行引擎 - - 修复在 `from_unixtime` 函数处理 null 时发生 panic 的问题 [#12551](https://github.com/pingcap/tidb/pull/12551) - - 修复 Admin Cancel DDL jobs 时报 `invalid list index` 错的问题 [#12671](https://github.com/pingcap/tidb/pull/12671) - - 修复使用 Window Functions 时发生数组越界的问题 [#12660](https://github.com/pingcap/tidb/pull/12660) - - 改进 `AutoIncrement` 列隐式分配时的行为，与 MySQL 自增锁的默认模式 (["consecutive" lock mode](https://dev.mysql.com/doc/refman/5.7/en/innodb-auto-increment-handling.html)) 保持一致：对于单行 Insert 语句的多个自增 `AutoIncrement` ID 的隐式分配，TiDB 保证分配值的连续性。该改进保证 JDBC `getGeneratedKeys()` 方法在任意场景下都能得到正确的结果。[#12602](https://github.com/pingcap/tidb/pull/12602) - - 修复当 `HashAgg` 作为 Apply 子节点时查询 hang 住的问题 [#12766](https://github.com/pingcap/tidb/pull/12766) - - 修复逻辑表达式 `AND` 或 `OR` 在涉及类型转换时返回错误结果的问题 [#12811](https://github.com/pingcap/tidb/pull/12811) -+ Server - - 实现修改事务 TTL 的接口函数，以助后续支持大事务 [#12397](https://github.com/pingcap/tidb/pull/12397) - - 支持将事务的 TTL 按需延长（最长可到 10min），用于支持悲观事务 [#12579](https://github.com/pingcap/tidb/pull/12579) - - 将 TiDB 缓存 schema 变更及相关表信息的次数从 100 调整为 1024，且支持通过 `tidb_max_delta_schema_count` 系统变量修改 [#12502](https://github.com/pingcap/tidb/pull/12502) - - 更新了 `kvrpc.Cleanup` 协议的行为，不再清理未超时事务的锁 [#12417](https://github.com/pingcap/tidb/pull/12417) - - 支持将 Partition 表信息记录到 `information_schema.tables` 表 [#12631](https://github.com/pingcap/tidb/pull/12631) - - 支持通过 `region-cache-ttl` 配置修改 Region Cache 的 TTL [#12683](https://github.com/pingcap/tidb/pull/12683) - - 支持在慢日志中打印执行计划压缩编码后的信息，此功能默认开启，可以通过 `slow-log-plan` 配置或者 `tidb_record_plan_in_slow_log` 变量进行开关控制。另外支持 `tidb_decode_plan` 函数将慢日志中的执行计划列编码信息解析成执行计划信息。[#12808](https://github.com/pingcap/tidb/pull/12808) - - 在 `information_schema.processlist` 表中支持显示内存使用信息 [#12801](https://github.com/pingcap/tidb/pull/12801) - - 修复 TiKV Client 判断连接空闲时可能出错并出现非预期的告警的问题 [#12846](https://github.com/pingcap/tidb/pull/12846) - - 修复 `tikvSnapshot` 没有正确对 `BatchGet()` 的 KV 结果进行缓存，导致 `INSERT IGNORE` 语句性能有所下降的问题 [#12872](https://github.com/pingcap/tidb/pull/12872) - - 修复了因建立到部分 KV 服务的连接较慢最终导致 TiDB 响应速度相对变慢的情况 [#12814](https://github.com/pingcap/tidb/pull/12814) -+ DDL - - 修复 `Create Table` 操作对 Set 列不能正确设置 Int 类型默认值的问题 [#12267](https://github.com/pingcap/tidb/pull/12267) - - 支持 `Create Table` 语句中建唯一索引时带多个 Unique [#12463](https://github.com/pingcap/tidb/pull/12463) - - 修复使用 `Alter Table` 添加 Bit 类型列时，对存在的行填充此列的默认值可能出错的问题 [#12489](https://github.com/pingcap/tidb/pull/12489) - - 修复 Range 分区表以 Date 或 Datetime 类型列作为分区键时，添加分区失败的问题 [#12815](https://github.com/pingcap/tidb/pull/12815) - - 对于 Date 或 Datetime 类型列作为分区键的 Range 分区表，在建表或者添加分区时，支持检查分区类型与分区键类型的统一性 [#12792](https://github.com/pingcap/tidb/pull/12792) - - 在创建 Range 分区表时，添加对 Unique Key 列集合需大于等于分区列集合的检查 [#12718](https://github.com/pingcap/tidb/pull/12718) -+ Monitor - - 添加统计 Commit 与 Rollback 操作的监控到 **Transaction OPS** 面板 [#12505](https://github.com/pingcap/tidb/pull/12505) - - 添加统计 `Add Index` 操作进度的监控 [#12390](https://github.com/pingcap/tidb/pull/12390) - -## TiKV - -+ Storage - - 悲观事务新特性：事务 Cleanup 接口支持只清理 TTL 已经过期的锁 [#5589](https://github.com/tikv/tikv/pull/5589) - - 修复事务 Primary key 的 Rollback 被折叠的问题 [#5646](https://github.com/tikv/tikv/pull/5646)，[#5671](https://github.com/tikv/tikv/pull/5671) - - 修复悲观锁下点查可能返回历史旧版本的问题 [#5634](https://github.com/tikv/tikv/pull/5634) -+ Raftstore - - 减少 Raftstore 消息的 flush 操作，以提升性能，减少 CPU 占用 [#5617](https://github.com/tikv/tikv/pull/5617) - - 优化获取 Region 的大小和 key 个数估计值的开销，减少心跳的开销，降低 CPU 占用 [#5620](https://github.com/tikv/tikv/pull/5620) - - 修复 Raftstore 取到非法数据时打印错误日志并 panic 的问题 [#5643](https://github.com/tikv/tikv/pull/5643) -+ Engine - - 打开 RocksDB `force_consistency_checks`，提高数据安全性 [#5662](https://github.com/tikv/tikv/pull/5662) - - 修复 Titan 并发 flush 情况下有可能造成数据丢失的问题 [#5672](https://github.com/tikv/tikv/pull/5672) - - 更新 rust-rocksdb 版本以避开 intra-L0 compaction 导致 TiKV 崩溃重启的问题 [#5710](https://github.com/tikv/tikv/pull/5710) - -## PD - -- 提高 Region 占用空间的精度 [#1782](https://github.com/pingcap/pd/pull/1782) -- 修复 `--help` 命令输出内容 [#1763](https://github.com/pingcap/pd/pull/1763) -- 修复 TLS 开启后 http 请求重定向失败的问题 [#1777](https://github.com/pingcap/pd/pull/1777) -- 修复 pd-ctl 使用 `store shows limit` 命令 panic 的问题 [#1808](https://github.com/pingcap/pd/pull/1808) -- 提高 label 监控可读性以及当 leader 发生切换后重置原 leader 的监控数据，防止误报 [#1815](https://github.com/pingcap/pd/pull/1815) - -## Tools - -+ TiDB Binlog - - 修复 `ALTER DATABASE` 相关 DDL 会导致 Drainer 异常退出的问题 [#769](https://github.com/pingcap/tidb-binlog/pull/769) - - 支持对 Commit binlog 查询事务状态信息，提升同步效率 [#757](https://github.com/pingcap/tidb-binlog/pull/757) - - 修复当 Drainer 的 `start_ts` 大于 Pump 中最大的 `commit_ts` 时，有可能引起 Pump panic 的问题 [#758](https://github.com/pingcap/tidb-binlog/pull/758) -+ TiDB Lightning - - 整合 Loader 全量逻辑导入功能，支持配置 backend 模式 [#221](https://github.com/pingcap/tidb-lightning/pull/221) - -## TiDB Ansible - -- 增加 TiDB 添加索引速度的监控 [#986](https://github.com/pingcap/tidb-ansible/pull/986) -- 精简配置文件内容，移除不需要用户配置的参数 [#1043c](https://github.com/pingcap/tidb-ansible/commit/1043c3df7ddb72eb234c55858960e9fdd3830a14)，[#998](https://github.com/pingcap/tidb-ansible/pull/998) -- 修复 performance read 和 performance write 监控表达式错误的问题 [#e90e7](https://github.com/pingcap/tidb-ansible/commit/e90e79f5117bb89197e01b1391fd02e25d57a440) -- 更新 raftstore CPU 使用率的监控显示方式以及 raftstore CPU 使用率的告警规则 [#992](https://github.com/pingcap/tidb-ansible/pull/992) -- 更新 **Overview** 监控面板中 TiKV 的 CPU 监控项，过滤掉多余的监控内容 [#1001](https://github.com/pingcap/tidb-ansible/pull/1001) diff --git a/v3.1/releases/3.0.6.md b/v3.1/releases/3.0.6.md deleted file mode 100644 index 8966bfcea701..000000000000 --- a/v3.1/releases/3.0.6.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: TiDB 3.0.6 Release Notes -category: Releases ---- - -# TiDB 3.0.6 Release Notes - -发版日期：2019 年 11 月 28 日 - -TiDB 版本：3.0.6 - -TiDB Ansible 版本：3.0.6 - -## TiDB - -+ SQL 优化器 - - 修复窗口函数 AST Restore SQL 文本后结果不正确问题，`over w` 不应被 restore 成 `over (w)` [#12933](https://github.com/pingcap/tidb/pull/12933) - - 修复 stream aggregation 下推给 double read 的问题 [#12690](https://github.com/pingcap/tidb/pull/12690) - - 修复 SQL bind 中引号处理不正确的问题 [#13117](https://github.com/pingcap/tidb/pull/13117) - - 优化 `select max(_tidb_rowid) from t` 场景，避免全表扫 [#13095](https://github.com/pingcap/tidb/pull/13095) - - 修复当查询语句中包含变量赋值表达式时查询结果不正确的问题 [#13231](https://github.com/pingcap/tidb/pull/13231) - - 修复 `UPDATE` 语句中同时包含子查询和 generated column 时结果错误的问题；修复 `UPDATE` 语句中包含不同数据库的两个表名相同的表时，`UPDATE` 执行报错的问题 [#13350](https://github.com/pingcap/tidb/pull/13350) - - 支持用 `_tidb_rowid` 做点查 [#13416](https://github.com/pingcap/tidb/pull/13416) - - 修复分区表统计信息使用错误导致生成执行计划不正确的问题 [#13628](https://github.com/pingcap/tidb/pull/13628) -+ SQL 执行引擎 - - 修复 year 类型对于无效值的处理时和 MySQL 不兼容问题 [#12745](https://github.com/pingcap/tidb/pull/12745) - - 在 `INSERT ON DUPLICATE UPDATE` 语句中复用 `Chunk` 以降低内存开销 [#12998](https://github.com/pingcap/tidb/pull/12998) - - 添加内置函数 `JSON_VALID` 的支持 [#13133](https://github.com/pingcap/tidb/pull/13133) - - 支持在分区表上执行 `ADMIN CHECK TABLE` [#13140](https://github.com/pingcap/tidb/pull/13140) - - 修复对空表进行 `FAST ANALYZE` 时 panic 的问题 [#13343](https://github.com/pingcap/tidb/pull/13343) - - 修复在包含多列索引的空表上执行 Fast Analyze 时 panic 的问题 [#13394](https://github.com/pingcap/tidb/pull/13394) - - 修复当 `WHERE` 子句上有 UNIQUE KEY 的等值条件时，估算行数大于 1 的问题 [#13382](https://github.com/pingcap/tidb/pull/13382) - - 修复当 TiDB 开启 `Streaming` 后返回数据有可能重复的问题 [#13254](https://github.com/pingcap/tidb/pull/13254) - - 将 `CMSketch` 中出现次数最多的 N 个值抽取出来，提高估算准确度 [#13429](https://github.com/pingcap/tidb/pull/13429) -+ Server - - 当 gRPC 请求超时时，提前让发往 TiKV 的请求失败 [#12926](https://github.com/pingcap/tidb/pull/12926) - - 添加以下虚拟表：[#13009](https://github.com/pingcap/tidb/pull/13009) - - `performance_schema.tidb_profile_allocs` - - `performance_schema.tidb_profile_block` - - `performance_schema.tidb_profile_cpu` - - `performance_schema.tidb_profile_goroutines` - - 修复 query 在等待悲观锁时，kill query 不生效的问题 [#12989](https://github.com/pingcap/tidb/pull/12989) - - 当悲观事务上锁失败，且事务只涉及一个 key 的修改时，不再异步回滚 [#12707](https://github.com/pingcap/tidb/pull/12707) - - 修复 split Region 请求的 response 为空时 panic 的问题 [#13092](https://github.com/pingcap/tidb/pull/13092) - - 悲观事务在其他事务先锁住导致上锁失败时，避免重复 backoff [#13116](https://github.com/pingcap/tidb/pull/13116) - - 修改 TiDB 检查配置时的行为，出现不能识别的配置选项时，打印警告日志 [#13272](https://github.com/pingcap/tidb/pull/13272) - - 支持通过 `/info/all` 接口获取所有 TiDB 节点的 binlog 状态 [#13187](https://github.com/pingcap/tidb/pull/13187) - - 修复 kill connection 时可能出现 goroutine 泄漏的问题 [#13251](https://github.com/pingcap/tidb/pull/13251) - - 让 `innodb_lock_wait_timeout` 参数在悲观事务中生效，用于控制悲观锁的等锁超时时间 [#13165](https://github.com/pingcap/tidb/pull/13165) - - 当悲观事务的 query 被 kill 后，停止更新悲观事务的 TTL，避免其他的事务做不必要的等待 [#13046](https://github.com/pingcap/tidb/pull/13046) -+ DDL - - 修复 `SHOW CREATE VIEW` 结果与 MySQL 不一致的问题 [#12912](https://github.com/pingcap/tidb/pull/12912) - - 支持基于 UNION 创建 View，例如 `create view v as select * from t1 union select * from t2` [#12955](https://github.com/pingcap/tidb/pull/12955) - - 给 `slow_query` 表添加更多事务相关的字段：[#13072](https://github.com/pingcap/tidb/pull/13072) - - `Prewrite_time` - - `Commit_time` - - `Get_commit_ts_time` - - `Commit_backoff_time` - - `Backoff_types` - - `Resolve_lock_time` - - `Local_latch_wait_time` - - `Write_key` - - `Write_size` - - `Prewrite_region` - - `Txn_retry` - - 创建表时如果表包含 collate 则列使用表的 collate 而不是系统默认的字符集 [#13174](https://github.com/pingcap/tidb/pull/13174) - - 创建表时限制索引名字的长度 [#13310](https://github.com/pingcap/tidb/pull/13310) - - 修复 rename table 时未检查表名长度的问题 [#13346](https://github.com/pingcap/tidb/pull/13346) - - 新增 `alter-primary-key` 配置来支持 TiDB add/drop primary key，该配置默认关闭 [#13522](https://github.com/pingcap/tidb/pull/13522) - -## TiKV - -- 修复 `acquire_pessimistic_lock` 接口返回错误 `txn_size` 的问题 [#5740](https://github.com/tikv/tikv/pull/5740) -- 限制 GC worker 每秒写入量，降低对性能的影响 [#5735](https://github.com/tikv/tikv/pull/5735) -- 优化 lock manager 的准确度 [#5845](https://github.com/tikv/tikv/pull/5845) -- 悲观锁支持 `innodb_lock_wait_timeout` [#5848](https://github.com/tikv/tikv/pull/5848) -- 添加 Titan 相关配置检测 [#5720](https://github.com/tikv/tikv/pull/5720) -- 支持用 tikv-ctl 动态修改 GC 限流配置：`tikv-ctl --host=ip:port modify-tikv-config -m server -n gc.max_write_bytes_per_sec -v 10MB` [#5957](https://github.com/tikv/tikv/pull/5957) -- 减少无用的 clean up 请求，降低死锁检测器的压力 [#5965](https://github.com/tikv/tikv/pull/5965) -- 悲观事务 prewrite 时避免 TTL 被缩短 [#6056](https://github.com/tikv/tikv/pull/6056) -- 修复 Titan 可能发生 missing blob file 的问题 [#5968](https://github.com/tikv/tikv/pull/5968) -- 修复 Titan 可能导致 `RocksDBOptions` 不生效的问题 [#6009](https://github.com/tikv/tikv/pull/6009) - -## PD - -- 为每个过滤器添加一个名为 `ActOn` 的新维度，以指示每个 scheduler 和 checker 受过滤器的影响。删除两个未使用的过滤器：`disconnectFilter` 和 `rejectLeaderFilter` [#1911](https://github.com/pingcap/pd/pull/1911) -- 当 PD 生成时间戳的时间超过5毫秒时，将打印一条 warning 日志 [#1867](https://github.com/pingcap/pd/pull/1867) -- 当存在 endpoint 不可用时，降低 client 日志级别 [#1856](https://github.com/pingcap/pd/pull/1856) -- 修复 `region_syncer` 同步时 gRPC 消息包可能过大的问题 [#1952](https://github.com/pingcap/pd/pull/1952) - -## Tools - -+ TiDB Binlog - - Drainer 配置 `initial-commit-ts` 为 -1 时，从 PD 处获取初始同步时间戳 [#788](https://github.com/pingcap/tidb-binlog/pull/788) - - Drainer checkpoint 存储与下游解耦，支持选择配置 checkpoint 保存到 MySQL 或者本地文件 [#790](https://github.com/pingcap/tidb-binlog/pull/790) - - 修复 Drainer 在配置同步库表过滤使用空值会导致 Panic 的问题 [#801](https://github.com/pingcap/tidb-binlog/pull/801) - - 修复 Drainer 因为向下游应用 Binlog 失败而 Panic 后进程没有退出而是进入死锁状态的问题 [#807](https://github.com/pingcap/tidb-binlog/pull/807) - - 修复 Pump 下线因为 gRPC 的 `GracefulStop` 流程而 hang 住的问题 [#817](https://github.com/pingcap/tidb-binlog/pull/817) - - 修复 Drainer 在 TiDB 执行 `DROP COLUMN` DDL 期间收到缺少一列的 binlog 而同步出错的问题（要求 TiDB 3.0.6 以上）[#827](https://github.com/pingcap/tidb-binlog/pull/827) -+ TiDB Lightning - - TiDB Backend 模式新增 `max-allowed-packet` 配置项，默认值为 64M [#248](https://github.com/pingcap/tidb-lightning/pull/248) diff --git a/v3.1/releases/3.0.7.md b/v3.1/releases/3.0.7.md deleted file mode 100644 index 61e9ea511223..000000000000 --- a/v3.1/releases/3.0.7.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: TiDB 3.0.7 Release Notes -category: Releases ---- - -# TiDB 3.0.7 Release Notes - -发版日期：2019 年 12 月 4 日 - -TiDB 版本：3.0.7 - -TiDB Ansible 版本：3.0.7 - -## TiDB - -- 修复 TiDB server 本地时间落后于 TSO 时间时，可能造成锁的 TTL 过大的问题 [#13868](https://github.com/pingcap/tidb/pull/13868) -- 修复从字符串解析日期时，由于使用本地时区 (`gotime.Local`) 而导致解析结果的时区不正确的问题 [#13793](https://github.com/pingcap/tidb/pull/13793) -- 修复 `builtinIntervalRealSig` 的实现中，`binSearch` 方法不会返回 error，导致最终结果可能不正确的问题 [#13767](https://github.com/pingcap/tidb/pull/13767) -- 修复整型数据被转换为无符号浮点/Decimal 类型时，精度可能丢失造成数据错误的问题 [#13755](https://github.com/pingcap/tidb/pull/13755) -- 修复 Natural Outer Join 和 Outer Join 使用 `USING` 语法时，`not null` 标记没有被重置导致结果错误的问题 [#13739](https://github.com/pingcap/tidb/pull/13739) -- 修复更新统计信息时可能存在数据竞争，导致统计信息不准确的问题 [#13687](https://github.com/pingcap/tidb/pull/13687) - -## TiKV - -- 判断死锁检测服务的第一个 Region 时，加上 Region 合法检测，防止信息不完整的 Region 导致误判 [#6110](https://github.com/tikv/tikv/pull/6110) -- 修复潜在的内存泄漏问题 [#6128](https://github.com/tikv/tikv/pull/6128) diff --git a/v3.1/releases/3.0.8.md b/v3.1/releases/3.0.8.md deleted file mode 100644 index 10fdb6998485..000000000000 --- a/v3.1/releases/3.0.8.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: TiDB 3.0.8 Release Notes -category: Releases ---- - -# TiDB 3.0.8 Release Notes - -发版日期：2019 年 12 月 31 日 - -TiDB 版本：3.0.8 - -TiDB Ansible 版本：3.0.8 - -## TiDB - -+ SQL 优化器 - - 修复 SQL Binding 因为 cache 更新不及时，导致绑定计划错误的问题 [#13891](https://github.com/pingcap/tidb/pull/13891) - - 修复当 SQL 包含符号列表（类似于 "?, ?, ?" 这样的占位符）时，SQL Binding 可能失效的问题 [#14004](https://github.com/pingcap/tidb/pull/14004) - - 修复 SQL Binding 由于原 SQL 以 `;` 结尾而不能创建/删除的问题 [#14113](https://github.com/pingcap/tidb/pull/14113) - - 修复 `PhysicalUnionScan` 算子没有正确设置统计信息，导致查询计划可能选错的问题 [#14133](https://github.com/pingcap/tidb/pull/14133) - - 移除 `minAutoAnalyzeRatio` 约束使自动 analyze 更及时 [#14015](https://github.com/pingcap/tidb/pull/14015) -+ SQL 执行引擎 - - 修复 `INSERT/REPLACE/UPDATE ... SET ... = DEFAULT` 语法会报错的问题，修复 `DEFAULT` 表达式与虚拟生成列配合使用会报错的问题 [#13682](https://github.com/pingcap/tidb/pull/13682) - - 修复 `INSERT` 语句在进行字符串类型到浮点类型转换时，可能会报错的问题 [#14011](https://github.com/pingcap/tidb/pull/14011) - - 修复 `HashAgg` Executor 并发值未被正确初始化，导致聚合操作执行在一些情况下效率低的问题 [#13811](https://github.com/pingcap/tidb/pull/13811) - - 修复 group by item 被括号包含时执行报错的问题 [#13658](https://github.com/pingcap/tidb/pull/13658) - - 修复 TiDB 没有正确计算 group by item，导致某些情况下 OUTER JOIN 执行会报错的问题 [#14014](https://github.com/pingcap/tidb/pull/14014) - - 修复向 Range 分区表写入超过 Range 外的数据时，报错信息不准确的问题 [#14107](https://github.com/pingcap/tidb/pull/14107) - - 鉴于 MySQL 8 即将废弃 `PadCharToFullLength`，revert PR [#10124](https://github.com/pingcap/tidb/pull/10124) 并撤销 `PadCharToFullLength` 的效果，以避免一些特殊情况下查询结果不符合预期 [#14157](https://github.com/pingcap/tidb/pull/14157) - - 修复 `ExplainExec` 中没有保证 `close()` 的调用而导致 `EXPLAIN ANALYZE` 时造成 goroutine 泄露的问题 [#14226](https://github.com/pingcap/tidb/pull/14226) -+ DDL - - 优化 "change column"/"modify column" 的输出的报错信息，让人更容易理解 [#13796](https://github.com/pingcap/tidb/pull/13796) - - 新增 `SPLIT PARTITION TABLE` 语法，支持分区表切分 Region 功能 [#13929](https://github.com/pingcap/tidb/pull/13929) - - 修复创建索引时，没有正确检查长度，导致索引长度超过 3072 字节没有报错的问题 [#13779](https://github.com/pingcap/tidb/pull/13779) - - 修复由于分区表添加索引时若花费时间过长，可能导致输出 `GC life time is shorter than transaction duration` 报错信息的问题 [#14132](https://github.com/pingcap/tidb/pull/14132) - - 修复在 `DROP COLUMN`/`MODIFY COLUMN`/`CHANGE COLUMN` 时没有检查外键导致执行 `SELECT * FROM information_schema.KEY_COLUMN_USAGE` 语句时发生 panic 的问题 [#14105](https://github.com/pingcap/tidb/pull/14105) -+ Server - - Statement Summary 功能改进： - - 新增大量的 SQL 指标字段，便于对 SQL 进行更详细的统计分析 [#14151](https://github.com/pingcap/tidb/pull/14151)，[#14168](https://github.com/pingcap/tidb/pull/14168) - - 新增 `stmt-summary.refresh-interval` 参数用于控制定期将 `events_statements_summary_by_digest` 表中过期的数据移到 `events_statements_summary_by_digest_history` 表，默认间隔时间：30min [#14161](https://github.com/pingcap/tidb/pull/14161) - - 新增 `events_statements_summary_by_digest_history` 表，保存从 `events_statements_summary_by_digest` 中过期的数据 [#14166](https://github.com/pingcap/tidb/pull/14166) - - 修复执行 RBAC 相关的内部 SQL 时，错误输出 binlog 的问题 [#13890](https://github.com/pingcap/tidb/pull/13890) - - 新增 `server-version` 配置项来控制修改 TiDB server 版本的功能 [#13906](https://github.com/pingcap/tidb/pull/13906) - - 新增通过 HTTP 接口恢复 TiDB binlog 写入功能 [#13892](https://github.com/pingcap/tidb/pull/13892) - - 将 `GRANT roles TO user` 所需要的权限由 `GrantPriv` 修改为 `ROLE_ADMIN` 或 `SUPER`，以与 MySQL 保持一致 [#13932](https://github.com/pingcap/tidb/pull/13932) - - 当 `GRANT` 语句未指定 database 名时，TiDB 行为由使用当前 database 改为报错 `No database selected`，与 MySQL 保持兼容 [#13784](https://github.com/pingcap/tidb/pull/13784) - - 修改 `REVOKE` 语句执行权限从 `SuperPriv` 改成用户只需要有对应 Schema 的权限，就可以执行 `REVOKE` 语句，与 MySQL 保持一致 [#13306](https://github.com/pingcap/tidb/pull/13306) - - 修复 `GRANT ALL` 语法在没有 `WITH GRANT OPTION` 时，错误地将 `GrantPriv` 授权给目标用户的问题 [#13943](https://github.com/pingcap/tidb/pull/13943) - - 修复 `LoadDataInfo` 中调用 `addRecord` 报错时，报错信息不包含导致 `LOAD DATA` 语句行为不正确信息的问题 [#13980](https://github.com/pingcap/tidb/pull/13980) - - 修复因查询中多个 SQL 语句共用同一个 `StartTime` 导致输出错误的慢查询信息的问题 [#13898](https://github.com/pingcap/tidb/pull/13898) - - 修复 `batchClient` 处理大事务时可能造成内存泄露的问题 [#14032](https://github.com/pingcap/tidb/pull/14032) - - 修复 `system_time_zone` 固定显示为 `CST` 的问题，现在 TiDB 的 `system_time_zone` 会从 `mysql.tidb` 表中的 `systemTZ` 获取 [#14086](https://github.com/pingcap/tidb/pull/14086) - - 修复 `GRANT ALL` 语法授予权限不完整（例如 `Lock_tables_priv`）的问题 [#14092](https://github.com/pingcap/tidb/pull/14092) - - 修复 `Priv_create_user` 权限不能 `CREATE ROLE` 和 `DROP ROLE`的问题 [#14088](https://github.com/pingcap/tidb/pull/14088) - - 将 `ErrInvalidFieldSize` 的错误码从 `1105(Unknow Error)` 改成 `3013` [#13737](https://github.com/pingcap/tidb/pull/13737) - - 新增 `SHUTDOWN` 命令用于停止 TiDB Server，并新增 `ShutdownPriv` 权限 [#14104](https://github.com/pingcap/tidb/pull/14104) - - 修复 `DROP ROLE` 语句的原子性问题，避免语句执行失败时，一些 ROLE 仍然被非预期地删除 [#14130](https://github.com/pingcap/tidb/pull/14130) - - 修复 3.0 以下版本升级到 3.0 时，`tidb_enable_window_function` 在 `SHOW VARIABLE` 语句的查询结果错误输出 1 的问题，修复后输出 0 [#14131](https://github.com/pingcap/tidb/pull/14131) - - 修复 TiKV 节点下线时，由于 `gcworker` 持续重试导致可能出现 goroutine 泄露的问题 [#14106](https://github.com/pingcap/tidb/pull/14106) - - 在慢日志中记录 Binlog 的 `Prewrite` 的时间，提升问题追查的易用性 [#14138](https://github.com/pingcap/tidb/pull/14138) - - `tidb_enable_table_partition` 变量支持 GLOBAL SCOPE 作用域 [#14091](https://github.com/pingcap/tidb/pull/14091) - - 修复新增权限时未正确将新增的权限赋予对应的用户导致用户权限可能缺失或者被误添加的问题 [#14178](https://github.com/pingcap/tidb/pull/14178) - - 修复当 TiKV 链接断开时，由于 `rpcClient` 不会关闭而导致 `CheckStreamTimeoutLoop` goroutine 会泄露的问题 [#14227](https://github.com/pingcap/tidb/pull/14227) -+ Transaction - - 创建新集群时，`tidb_txn_mode` 变量的默认值由 `""` 改为 `"pessimistic"` [#14171](https://github.com/pingcap/tidb/pull/14171) - - 修复悲观事务模式，事务重试时单条语句的等锁时间没有被重置导致等锁时间过长的问题 [#13990](https://github.com/pingcap/tidb/pull/13990) - - 修复悲观事务模式，因对没有修改的数据未加锁导致可能读到不正确数据的问题 [#14050](https://github.com/pingcap/tidb/pull/14050) - - 修复 mocktikv 中 prewrite 时，没有区分事务类型，导致重复的 insert value 约束检查 [#14175](https://github.com/pingcap/tidb/pull/14175) - - 修复 `session.TxnState` 状态为 `Invalid` 时，事务没有被正确处理导致 panic 的问题 [#13988](https://github.com/pingcap/tidb/pull/13988) - - 修复 mocktikv 中 `ErrConfclit` 结构未包含 `ConflictCommitTS` 的问题 [#14080](https://github.com/pingcap/tidb/pull/14080) - - 修复 TiDB 在 Resolve Lock 之后，没有正确处理锁超时检查导致事务卡住的问题 [#14083](https://github.com/pingcap/tidb/pull/14083) -+ Monitor - - `LockKeys` 新增 `pessimistic_lock_keys_duration` 监控 [#14194](https://github.com/pingcap/tidb/pull/14194) - -## TiKV - -+ Coprocessor - - 修改 Coprocessor 遇到错误时输出日志的级别从 `error` 改成 `warn` [#6051](https://github.com/tikv/tikv/pull/6051) - - 修改统计信息采样数据的更新行为从直接更行改成先删除再插入，更新行为与 tidb-server 保持一致 [#6069](https://github.com/tikv/tikv/pull/6096) -+ Raftstore - - 修复因重复向 `peerfsm` 发送 destory 消息，`peerfsm` 被多次销毁导致 panic 的问题 [#6297](https://github.com/tikv/tikv/pull/6297) - - `split-region-on-table` 默认值由 `true` 改成 `false`，默认关闭按 table 切分 Region 的功能 [#6253](https://github.com/tikv/tikv/pull/6253) -+ Engine - - 修复极端条件下因 RocksDB 迭代器错误未正确处理导致可能返回空数据的问题 [#6326](https://github.com/tikv/tikv/pull/6326) -+ 事务 - - 修复悲观锁因锁未被正确清理导致 Key 无法写入数据，且出现 GC 卡住的问题 [#6354](https://github.com/tikv/tikv/pull/6354) - - 优化悲观锁等锁机制，提升锁冲突严重场景的性能 [#6296](https://github.com/tikv/tikv/pull/6296) -+ 将内存分配库的默认值由 `tikv_alloc/default` 改成 `jemalloc` [#6206](https://github.com/tikv/tikv/pull/6206) - -## PD - -- Client - - 新增通过 `context` 创建新 client，创建新 client 时可设置超时时间 [#1994](https://github.com/pingcap/pd/pull/1994) - - 新增创建 `KeepAlive` 连接功能 [#2035](https://github.com/pingcap/pd/pull/2035) -- 优化`/api/v1/regions` API 的性能 [#1986](https://github.com/pingcap/pd/pull/1986) -- 修复删除 `tombstone` 状态的 Store 可能会导致 panic 的隐患 [#2038](https://github.com/pingcap/pd/pull/2038) -- 修复从磁盘加载 Region 信息时错误的将范围有重叠的 Region 删除的问题 [#2011](https://github.com/pingcap/pd/issues/2011)，[#2040](https://github.com/pingcap/pd/pull/2040) -- 将 etcd 版本从 3.4.0 升级到 3.4.3 稳定版本，注意升级后只能通过 pd-recover 工具降级 [#2058](https://github.com/pingcap/pd/pull/2058) - -## Tools - -+ TiDB Binlog - - 修复 Pump 由于没有收到 DDL 的 commit binlog 导致 binlog 被忽略的问题 [#853](https://github.com/pingcap/tidb-binlog/pull/853) - -## TiDB Ansible - -- 回滚被精简的配置项 [#1053](https://github.com/pingcap/tidb-ansible/pull/1053) -- 优化滚动升级时 TiDB 版本检查的逻辑 [#1056](https://github.com/pingcap/tidb-ansible/pull/1056) -- TiSpark 版本升级到 2.1.8 [#1061](https://github.com/pingcap/tidb-ansible/pull/1061) -- 修复 Grafana 监控上 PD 页面 Role 监控项显示不正确的问题 [#1065](https://github.com/pingcap/tidb-ansible/pull/1065) -- 优化 Grafana 监控上 TiKV Detail 页面上 `Thread Voluntary Context Switches` 和 `Thread Nonvoluntary Context Switches` 监控项 [#1071](https://github.com/pingcap/tidb-ansible/pull/1071) diff --git a/v3.1/releases/3.0.9.md b/v3.1/releases/3.0.9.md deleted file mode 100644 index 3b35cfaaac19..000000000000 --- a/v3.1/releases/3.0.9.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: TiDB 3.0.9 Release Notes -category: Releases ---- - -# TiDB 3.0.9 Release Notes - -发版日期：2020 年 01 月 14 日 - -TiDB 版本：3.0.9 - -TiDB Ansible 版本：3.0.9 - -## TiDB - -+ Executor - - 修复聚合函数作用于枚举和集合列时结果不正确的问题 [#14364](https://github.com/pingcap/tidb/pull/14364) -+ Server - - 支持系统变量 `auto_increment_increment` 和 `auto_increment_offset` [#14396](https://github.com/pingcap/tidb/pull/14396) - - 新增 `tidb_tikvclient_ttl_lifetime_reach_total` 监控项，监控悲观事务 TTL 达到 10 分钟的数量 [#14300](https://github.com/pingcap/tidb/pull/14300) - - 执行 SQL 过程中当发生 panic 时输出导致 panic 的 SQL 信息 [#14322](https://github.com/pingcap/tidb/pull/14322) - - statement summary 系统表新增 `plan` 和 `plan_digest` 字段，记录当前正在执行的 `plan` 和 `plan` 的签名 [#14285](https://github.com/pingcap/tidb/pull/14285) - - 配置项 `stmt-summary.max-stmt-count` 的默认值从 `100` 调整至 `200` [#14285](https://github.com/pingcap/tidb/pull/14285) - - slow query 表新增 `plan_digest` 字段，记录 `plan` 的签名 [#14292](https://github.com/pingcap/tidb/pull/14292) -+ DDL - - 修复 `alter table ... add index` 语句创建匿名索引行为与 MySQL 不一致的问题 [#14310](https://github.com/pingcap/tidb/pull/14310) - - 修复 `drop table` 错误删除视图的问题 [#14052](https://github.com/pingcap/tidb/pull/14052) -+ Planner - - 提升类似 `select max(a), min(a) from t` 语句的性能。如果 `a` 列表上有索引，该语句会被优化为 `select * from (select a from t order by a desc limit 1) as t1, (select a from t order by a limit 1) as t2` 以避免全表扫 [#14410](https://github.com/pingcap/tidb/pull/14410) - -## TiKV - -+ Raftstore - - 提升 Raft 成员变更的速度 [#6421](https://github.com/tikv/tikv/pull/6421) -+ Transaction - - 新增 `tikv_lock_manager_waiter_lifetime_duration`、`tikv_lock_manager_detect_duration`、`tikv_lock_manager_detect_duration` 监控项，用于监控 `waiter` 的生命周期、死锁检测耗费时间、`wait table` 的状态 [#6392](https://github.com/tikv/tikv/pull/6422) - - 通过优化配置项 `wait-for-lock-time` 默认值从 `3s` 调整到 `1s`、`wake-up-delay-duration` 默认值从 `100ms` 调整为 `20ms`，以降低极端场景下 Region Leader 切换、切换死锁检测的 leader 导致的事务执行延迟 [#6429](https://github.com/tikv/tikv/pull/6429) - - 修复 Region Merge 过程中可能导致死锁检测器 leader 角色误判的问题 [#6431](https://github.com/tikv/tikv/pull/6431) - -## PD - -+ 新增 location label 的名字中允许使用斜杠 `/` 的功能 [#2083](https://github.com/pingcap/pd/pull/2083) -+ 修复因为不正确地统计了 tombstone 的标签，导致该统计信息不准的问题 [#2060](https://github.com/pingcap/pd/issues/2060) - -## Tools - -+ TiDB Binlog - - Drainer 输出的 binlog 协议中新增 unique key 信息 [#862](https://github.com/pingcap/tidb-binlog/pull/862) - - Drainer 支持使用加密后的数据库连接密码 [#868](https://github.com/pingcap/tidb-binlog/pull/868) - -## TiDB Ansible - -+ 优化 Lightning 部署，自动创建相关目录 [#1105](https://github.com/pingcap/tidb-ansible/pull/1105) diff --git a/v3.1/releases/3.0beta.md b/v3.1/releases/3.0beta.md deleted file mode 100644 index b538dc6d68bf..000000000000 --- a/v3.1/releases/3.0beta.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: TiDB 3.0 Beta Release Notes -category: Releases ---- - -# TiDB 3.0 Beta Release Notes - -2019 年 1 月 19 日，TiDB 发布 3.0 Beta 版，TiDB Ansible 相应发布 3.0 Beta 版本。相比 2.1 版本，该版本对系统稳定性、优化器、统计信息以及执行引擎做了很多改进。 - -## TiDB - -+ 新特性 - - 支持 View - - 支持窗口函数 - - 支持 Range 分区 - - 支持 Hash 分区 -+ SQL 优化器 - - 重新支持聚合消除的优化规则 [#7676](https://github.com/pingcap/tidb/pull/7676) - - 优化 `NOT EXISTS` 子查询，将其转化为 Anti Semi Join [#7842](https://github.com/pingcap/tidb/pull/7842) - - 添加 `tidb_enable_cascades_planner` 变量以支持新的 Cascades 优化器。目前 Cascades 优化器尚未实现完全，默认关闭 [#7879](https://github.com/pingcap/tidb/pull/7879) - - 支持在事务中使用 Index Join [#7877](https://github.com/pingcap/tidb/pull/7877) - - 优化 Outer Join 上的常量传播，使得对 Join 结果里和 Outer 表相关的过滤条件能够下推过 Outer Join 到 Outer 表上，减少 Outer Join 的无用计算量，提升执行性能 [#7794](https://github.com/pingcap/tidb/pull/7794) - - 调整投影消除的优化规则到聚合消除之后，消除掉冗余的 `Project` 算子 [#7909](https://github.com/pingcap/tidb/pull/7909) - - 优化 `IFNULL` 函数，当输入参数具有非 NULL 的属性的时候，消除该函数 [#7924](https://github.com/pingcap/tidb/pull/7924) - - 支持对 `_tidb_rowid` 构造查询的 Range，避免全表扫，减轻集群压力 [#8047](https://github.com/pingcap/tidb/pull/8047) - - 优化 `IN` 子查询为先聚合后做 Inner Join 并，添加变量 `tidb_opt_insubq_to_join_and_agg` 以控制是否开启该优化规则并默认打开 [#7531](https://github.com/pingcap/tidb/pull/7531) - - 支持在 `DO` 语句中使用子查询 [#8343](https://github.com/pingcap/tidb/pull/8343) - - 添加 Outer Join 消除的优化规则，减少不必要的扫表和 Join 操作，提升执行性能 [#8021](https://github.com/pingcap/tidb/pull/8021) - - 修改 `TIDB_INLJ` 优化器 Hint 的行为，优化器将使用 Hint 中指定的表当做 Index Join 的 Inner 表 [#8243](https://github.com/pingcap/tidb/pull/8243) - - 更大范围的启用 `PointGet`，使得当 Prepare 语句的执行计划缓存生效时也能利用上它 [#8108](https://github.com/pingcap/tidb/pull/8108) - - 引入贪心的 Join Reorder 算法，优化多表 Join 时 Join 顺序选择的问题 [#8394](https://github.com/pingcap/tidb/pull/8394) - - 支持 View [#8757](https://github.com/pingcap/tidb/pull/8757) - - 支持 Window Function [#8630](https://github.com/pingcap/tidb/pull/8630) - - 当 `TIDB_INLJ` 未生效时，返回 warning 给客户端，增强易用性 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 支持根据过滤条件和表的统计信息推导过滤后数据的统计信息的功能 [#7921](https://github.com/pingcap/tidb/pull/7921) - - 增强 Range Partition 的 Partition Pruning 优化规则 [#8885](https://github.com/pingcap/tidb/pull/8885) -+ SQL 执行引擎 - - 优化 Merge Join 算子，使其支持空的 `ON` 条件 [#9037](https://github.com/pingcap/tidb/pull/9037) - - 优化日志，打印执行 `EXECUTE` 语句时使用的用户变量 [#7684](https://github.com/pingcap/tidb/pull/7684) - - 优化日志，为 `COMMIT` 语句打印慢查询信息 [#7951](https://github.com/pingcap/tidb/pull/7951) - - 支持 `EXPLAIN ANALYZE` 功能，使得 SQL 调优过程更加简单 [#7827](https://github.com/pingcap/tidb/pull/7827) - - 优化列很多的宽表的写入性能 [#7935](https://github.com/pingcap/tidb/pull/7935) - - 支持 `admin show next_row_id` [#8242](https://github.com/pingcap/tidb/pull/8242) - - 添加变量 `tidb_init_chunk_size` 以控制执行引擎使用的初始 Chunk 大小 [#8480](https://github.com/pingcap/tidb/pull/8480) - - 完善 `shard_row_id_bits`，对自增 ID 做越界检查 [#8936](https://github.com/pingcap/tidb/pull/8936) -+ `Prepare` 语句 - - 对包含子查询的 `Prepare` 语句，禁止其添加到 `Prepare` 语句的执行计划缓存中，确保输入不同的用户变量时执行计划的正确性 [#8064](https://github.com/pingcap/tidb/pull/8064) - - 优化 `Prepare` 语句的执行计划缓存，使得当语句中包含非确定性函数的时候，该语句的执行计划也能被缓存 [#8105](https://github.com/pingcap/tidb/pull/8105) - - 优化 `Prepare` 语句的执行计划缓存，使得 `DELETE`/`UPDATE`/`INSERT` 的执行计划也能被缓存 [#8107](https://github.com/pingcap/tidb/pull/8107) - - 优化 `Prepare` 语句的执行计划缓存，当执行 `DEALLOCATE` 语句时从缓存中剔除对应的执行计划 [#8332](https://github.com/pingcap/tidb/pull/8332) - - 优化 `Prepare` 语句的执行计划缓存，通过控制其内存使用以避免缓存过多执行计划导致 TiDB OOM 的问题 [#8339](https://github.com/pingcap/tidb/pull/8339) - - 优化 `Prepare` 语句，使得 `ORDER BY`/`GROUP BY`/`LIMIT` 子句中可以使用 “?” 占位符 [#8206](https://github.com/pingcap/tidb/pull/8206) -+ 权限管理 - - 增加对 `ANALYZE` 语句的权限检查 [#8486](https://github.com/pingcap/tidb/pull/8486) - - 增加对 `USE` 语句的权限检查 [#8414](https://github.com/pingcap/tidb/pull/8418) - - 增加对 `SET GLOBAL` 语句的权限检查 [#8837](https://github.com/pingcap/tidb/pull/8837) - - 增加对 `SHOW PROCESSLIST` 语句的权限检查 [#7858](https://github.com/pingcap/tidb/pull/7858) -+ Server - - 支持了对 SQL 语句的 `Trace` 功能 [#9029](https://github.com/pingcap/tidb/pull/9029) - - 支持了插件框架 [#8788](https://github.com/pingcap/tidb/pull/8788) - - 支持同时使用 `unix_socket` 和 TCP 两种方式连接数据库 [#8836](https://github.com/pingcap/tidb/pull/8836) - - 支持了系统变量 `interactive_timeout` [#8573](https://github.com/pingcap/tidb/pull/8573) - - 支持了系统变量 `wait_timeout` [#8346](https://github.com/pingcap/tidb/pull/8346) - - 提供了变量 `tidb_batch_commit`，可以按语句数将事务分解为多个事务 [#8293](https://github.com/pingcap/tidb/pull/8293) - - 支持 `ADMIN SHOW SLOW` 语句，方便查看慢日志 [#7785](https://github.com/pingcap/tidb/pull/7785) -+ 兼容性 - - 支持了 `ALLOW_INVALID_DATES` 这种 SQL mode [#9027](https://github.com/pingcap/tidb/pull/9027) - - 提升了 load data 对 CSV 文件的容错能力 [#9005](https://github.com/pingcap/tidb/pull/9005) - - 支持了 MySQL 320 握手协议 [#8812](https://github.com/pingcap/tidb/pull/8812) - - 支持将 unsigned bigint 列声明为自增列 [#8181](https://github.com/pingcap/tidb/pull/8181) - - 支持 `SHOW CREATE DATABASE IF NOT EXISTS` 语法 [#8926](https://github.com/pingcap/tidb/pull/8926) - - 当过滤条件中包含用户变量时不对其进行谓词下推的操作，更加兼容 MySQL 中使用用户变量模拟 Window Function 的行为 [#8412](https://github.com/pingcap/tidb/pull/8412) -+ DDL - - 支持快速恢复误删除的表 [#7937](https://github.com/pingcap/tidb/pull/7937) - - 支持动态调整 ADD INDEX 的并发数 [#8295](https://github.com/pingcap/tidb/pull/8295) - - 支持更改表或者列的字符集到 utf8/utf8mb4 [#8037](https://github.com/pingcap/tidb/pull/8037) - - 默认字符集从 `utf8` 变为 `utf8mb4` [#7965](https://github.com/pingcap/tidb/pull/7965) - - 支持 RANGE PARTITION [#8011](https://github.com/pingcap/tidb/pull/8011) - -## Tools - -+ TiDB Lightning - - 大幅优化 SQL 转 KV 的处理速度 [#110](https://github.com/pingcap/tidb-lightning/pull/110) - - 对单表支持 batch 导入，提高导入性能和稳定性 [#113](https://github.com/pingcap/tidb-lightning/pull/113) - -## PD - -- 增加 `RegionStorage` 单独存储 Region 元信息 [#1237](https://github.com/pingcap/pd/pull/1237) -- 增加 shuffle hot region 调度 [#1361](https://github.com/pingcap/pd/pull/1361) -- 增加调度参数相关 Metrics [#1406](https://github.com/pingcap/pd/pull/1406) -- 增加集群 Label 信息相关 Metrics [#1402](https://github.com/pingcap/pd/pull/1402) -- 增加导入数据场景模拟 [#1263](https://github.com/pingcap/pd/pull/1263) -- 修复 Leader 选举相关的 Watch 问题 [#1396](https://github.com/pingcap/pd/pull/1396) - -## TiKV - -- 支持了分布式 GC [#3179](https://github.com/tikv/tikv/pull/3179) -- 在 Apply snapshot 之前检查 RocksDB level 0 文件，避免产生 Write stall [#3606](https://github.com/tikv/tikv/pull/3606) -- 支持了逆向 `raw_scan` 和 `raw_batch_scan` [#3742](https://github.com/tikv/tikv/pull/3724) -- 更好的夏令时支持 [#3786](https://github.com/tikv/tikv/pull/3786) -- 支持了使用 HTTP 方式获取监控信息 [#3855](https://github.com/tikv/tikv/pull/3855) -- 支持批量方式接收和发送 Raft 消息 [#3931](https://github.com/tikv/tikv/pull/3913) -- 引入了新的存储引擎 Titan [#3985](https://github.com/tikv/tikv/pull/3985) -- 升级 gRPC 到 v1.17.2 [#4023](https://github.com/tikv/tikv/pull/4023) -- 支持批量方式接收客户端请求和发送回复 [#4043](https://github.com/tikv/tikv/pull/4043) -- 多线程 Apply [#4044](https://github.com/tikv/tikv/pull/4044) -- 多线程 Raftstore [#4066](https://github.com/tikv/tikv/pull/4066) diff --git a/v3.1/releases/3.1.0-beta.1.md b/v3.1/releases/3.1.0-beta.1.md deleted file mode 100644 index d8f71b04a6e7..000000000000 --- a/v3.1/releases/3.1.0-beta.1.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB 3.1 Beta.1 Release Notes -category: Releases ---- - -# TiDB 3.1 Beta.1 Release Notes - -发版日期：2020 年 1 月 10 日 - -TiDB 版本：3.1.0-beta.1 - -TiDB Ansible 版本：3.1.0-beta.1 - -## TiKV - -+ backup - - 备份文件的名称由 `start_key` 改为 `start_key` 的 hash 值，减少文件名的长度，方便阅读 [#6198](https://github.com/tikv/tikv/pull/6198) - - 关闭 RocksDB `force_consistency_checks` 检查功能，避免一致性检查误报的问题 [#6249](https://github.com/tikv/tikv/pull/6249) - - 新增增量备份功能 [#6286](https://github.com/tikv/tikv/pull/6286) -+ sst_importer - - 修复恢复后 SST 文件没有 MVCC Properties 的问题 [#6378](https://github.com/tikv/tikv/pull/6378) - - 新增 `tikv_import_download_duration`、`tikv_import_download_bytes`、`tikv_import_ingest_duration`、`tikv_import_ingest_bytes`、`tikv_import_error_counter` 等监控项，用于观察 Download SST 和 Ingest SST 的开销 [#6404](https://github.com/tikv/tikv/pull/6404) -+ raftstore - - 修复因 Follower Read 在 leader 变更时读到旧数据的问题，导致事务的隔离性被破坏的问题 [#6343](https://github.com/tikv/tikv/pull/6343) - -## Tools - -+ BR (Backup and Restore) - - 修复备份进度信息不准确的问题 [#127](https://github.com/pingcap/br/pull/127) - - 提升 split Region 的性能 [#122](https://github.com/pingcap/br/pull/122) - - 新增备份恢复分区表的功能 [#137](https://github.com/pingcap/br/pull/137) - - 新增自动调度 PD schedulers 功能 [#123](https://github.com/pingcap/br/pull/123) - - 修复非 PKIsHandle 表恢复后数据覆盖的问题 [#139](https://github.com/pingcap/br/pull/139) - -## TiDB Ansible - -- 新增初始化阶段自动关闭操作系统 THP 的功能 [#1086](https://github.com/pingcap/tidb-ansible/pull/1086) -- 新增 BR 组件的 Grafana 监控 [#1093](https://github.com/pingcap/tidb-ansible/pull/1093) -- 优化 TiDB Lightning 部署，自动创建相关目录 [#1104](https://github.com/pingcap/tidb-ansible/pull/1104) diff --git a/v3.1/releases/3.1.0-beta.md b/v3.1/releases/3.1.0-beta.md deleted file mode 100644 index b9762840961d..000000000000 --- a/v3.1/releases/3.1.0-beta.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: TiDB 3.1 Beta Release Notes -category: Releases ---- - -# TiDB 3.1 Beta Release Notes - -发版日期：2019 年 12 月 20 日 - -TiDB 版本：3.1.0-beta - -TiDB Ansible 版本：3.1.0-beta - -## TiDB - -+ SQL 优化器 - - 丰富 SQL hint [#12192](https://github.com/pingcap/tidb/pull/12192) -+ 新功能 - - TiDB 支持 Follower Read 功能 [#12535](https://github.com/pingcap/tidb/pull/12535) - -## TiKV - -- 支持分布式备份恢复功能 [#5532](https://github.com/tikv/tikv/pull/5532) -- TiKV 支持 Follower Read 功能 [#5562](https://github.com/tikv/tikv/pull/5562) - -## PD - -- 支持分布式备份恢复功能 [#1896](https://github.com/pingcap/pd/pull/1896) diff --git a/v3.1/releases/ga.md b/v3.1/releases/ga.md deleted file mode 100644 index 65743083591f..000000000000 --- a/v3.1/releases/ga.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: TiDB 1.0 release notes -category: Releases ---- - -# TiDB 1.0 Release Notes - -2017 年 10 月 16 日，TiDB 发布 GA 版（TiDB 1.0）。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -+ SQL 查询优化器 - - 调整代价模型 - - Analyze 下推 - - 函数签名下推 - -+ 优化内部数据格式，减小中间结果大小 -+ 提升 MySQL 兼容性 -+ 支持 `NO_SQL_CACHE` 语法，控制存储引擎对缓存的使用 -+ 重构 Hash Aggregator 算子，降低内存使用 -+ 支持 Stream Aggragator 算子 - -## PD - -+ 支持基于读流量的热点调度 -+ 支持设置 Store 权重，以及基于权重的调度 - -## TiKV - -+ Coprocessor 支持更多下推函数 -+ 支持取样操作下推 -+ 支持手动触发数据 Compact，用于快速回收空间 -+ 提升性能和稳定性 -+ 增加 Debug API，方便调试 - -## TiSpark Beta Release - -+ 支持可配置框架 -+ 支持 ThriftSever/JDBC 和 Spark SQL 脚本入口 - -## 源码地址 - -[源码地址](https://github.com/pingcap/tidb) - -## 鸣谢 - -### 特别感谢参与项目的企业和团队 - -- Archon -- Mobike -- SpeedyCloud -- UCloud -- 腾讯云 -- 韩国三星研究院 - -### 感谢以下组织/个人提供出色的开源软件/服务 - -- Asta Xie -- CNCF -- CoreOS -- Databricks -- Docker -- Github -- Grafana -- gRPC -- Jepsen -- Kubernetes -- Namazu -- Prometheus -- RedHat -- RocksDB Team -- Rust Team - -### 感谢社区个人贡献者 TiDB Contributor - -- 8cbx -- Akihiro Suda -- aliyx -- alston111111 -- andelf -- Andy Librian -- Arthur Yang -- astaxie -- Bai, Yang -- bailaohe -- Bin Liu -- Blame cosmos -- Breezewish -- Carlos Ferreira -- Ce Gao -- Changjian Zhang -- Cheng Lian -- Cholerae Hu -- Chu Chao -- coldwater -- Cole R Lawrence -- cuiqiu -- cuiyuan -- Cwen -- Dagang -- David Chen -- David Ding -- dawxy -- dcadevil -- Deshi Xiao -- Di Tang -- disksing -- dongxu -- dreamquster -- Drogon -- Du Chuan -- Dylan Wen -- eBoyy -- Eric Romano -- Ewan Chou -- Fiisio -- follitude -- Fred Wang -- follitude -- fud -- fudali -- gaoyangxiaozhu -- Gogs -- goroutine -- Gregory Ian -- Guanqun Lu -- Guilherme Hübner Franco -- Haibin Xie -- Han Fei -- Hiroaki Nakamura -- hiwjd -- Hongyuan Wang -- Hu Ming -- Hu Ziming -- Huachao Huang -- HuaiyuXu -- Huxley Hu -- iamxy -- Ian -- insion -- iroi44 -- Ivan.Yang -- Jack Yu -- jacky liu -- Jan Mercl -- Jason W -- Jay -- Jay Lee -- Jianfei Wang -- Jiaxing Liang -- Jie Zhou -- jinhelin -- Jonathan Boulle -- Karl Ostendorf -- knarfeh -- Kuiba -- leixuechun -- li -- Li Shihai -- Liao Qiang -- Light -- lijian -- Lilian Lee -- Liqueur Librazy -- Liu Cong -- Liu Shaohui -- liubo0127 -- liyanan -- lkk2003rty -- Louis -- louishust -- luckcolors -- Lynn -- Mae Huang -- maiyang -- maxwell -- mengshangqi -- Michael Belenchenko -- mo2zie -- morefreeze -- MQ -- mxlxm -- Neil Shen -- netroby -- ngaut -- Nicole Nie -- nolouch -- onlymellb -- overvenus -- PaladinTyrion -- paulg -- Priya Seth -- qgxiaozhan -- qhsong -- Qiannan -- qiuyesuifeng -- queenypingcap -- qupeng -- Rain Li -- ranxiaolong -- Ray -- Rick Yu -- shady -- ShawnLi -- Shen Li -- Sheng Tang -- Shirly -- Shuai Li -- ShuNing -- ShuYu Wang -- siddontang -- silenceper -- Simon J Mudd -- Simon Xia -- skimmilk6877 -- sllt -- soup -- Sphinx -- Steffen -- sumBug -- sunhao2017 -- Tao Meng -- Tao Zhou -- tennix -- tiancaiamao -- TianGuangyu -- Tristan Su -- ueizhou -- UncP -- Unknwon -- v01dstar -- Van -- WangXiangUSTC -- wangyisong1996 -- weekface -- wegel -- Wei Fu -- Wenbin Xiao -- Wenting Li -- Wenxuan Shi -- winkyao -- woodpenker -- wuxuelian -- Xiang Li -- xiaojian cai -- Xuanjia Yang -- Xuanwo -- XuHuaiyu -- Yang Zhexuan -- Yann Autissier -- Yanzhe Chen -- Yiding Cui -- Yim -- youyouhu -- Yu Jun -- Yuwen Shen -- Zejun Li -- Zhang Yuning -- zhangjinpeng1987 -- ZHAO Yijun -- ZhengQian -- ZhengQianFang -- zhengwanbo -- Zhe-xuan Yang -- ZhiFeng Hu -- Zhiyuan Zheng -- Zhou Tao -- Zhoubirdblue -- zhouningnan -- Ziyi Yan -- zs634134578 -- zyguan -- zz-jason -- qiukeren -- hawkingrei -- wangyanjun -- zxylvlp diff --git a/v3.1/releases/prega.md b/v3.1/releases/prega.md deleted file mode 100644 index 75d0d1fcfa44..000000000000 --- a/v3.1/releases/prega.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: TiDB Pre-GA Release Notes -category: Releases ---- - -# TiDB Pre-GA Release Notes - -2017 年 8 月 30 日，TiDB 发布 Pre-GA 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。 - -## TiDB - -+ SQL 查询优化器 - - 调整代价模型 - - 优化索引选择，支持不同类型字段比较的索引选择 - - 支持基于贪心算法的 Join Reorder -+ 大量 MySQL 兼容性相关功能 -+ 支持 Natural Join -+ 完成 JSON 类型支持 (Experimental)，包括对 JSON 中的字段查询、更新、建索引 -+ 裁剪无用数据，减小执行器内存消耗 -+ 支持在 SQL 语句中设置优先级，并根据查询类型自动设置部分语句的优先级 -+ 完成表达式重构，执行速度提升 30% 左右 - -## PD - -+ 支持手动切换 PD 集群 Leader - -## TiKV - -+ Raft Log 使用独立的 RocksDB 实例 -+ 使用 DeleteRange 加快删除副本速度 -+ Coprocessor 支持更多运算符下推 -+ 提升性能，提升稳定性 - -## TiSpark Beta Release - -+ 支持谓词下推 -+ 支持聚合下推 -+ 支持范围裁剪 -+ 通过 TPC-H 测试 (除去一个需要 View 的 Query) diff --git a/v3.1/releases/rc1.md b/v3.1/releases/rc1.md deleted file mode 100644 index cf7f40d3fdc4..000000000000 --- a/v3.1/releases/rc1.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: TiDB RC1 Release Notes -category: Releases ---- - -# TiDB RC1 Release Notes - -2016 年 12 月 23 日，分布式关系型数据库 TiDB 正式发布 RC1。 - -## TiKV - -+ 提升写入速度 -+ 降低磁盘空间占用 -+ 支持百 TB 级别数据 -+ 提升稳定性，集群规模支持 200 个节点 -+ 提供 Raw KV API，以及 Golang client - -## PD - -+ PD 调度策略框架优化，策略更加灵活合理 -+ 添加 label 支持，支持跨 DC 调度 -+ 提供 PD Controler，方便操作 PD 集群 - -## TiDB - -+ SQL 查询优化器 - - 支持 eager aggregate - - 更详细的 explain 信息 - - union 算子并行化 - - 子查询性能优化 - - 条件下推优化 - - 优化 CBO 框架 -+ 重构 time 相关类型的实现，提升和 MySQL 的兼容性 -+ 支持更多的 MySQL 内建函数 -+ Add Index 语句提速 -+ 支持用 change column 语句修改列名；支持使用 Alter table 的 modify column 和 change column 完成部分列类型转换 - -## 工具 - -+ Loader：兼容 Percona 的 Mydumper 数据格式，提供多线程导入、出错重试、断点续传等功能，并且针对 TiDB 有优化 -+ 开发完成一键部署工具 diff --git a/v3.1/releases/rc2.md b/v3.1/releases/rc2.md deleted file mode 100644 index ff0f2cf18865..000000000000 --- a/v3.1/releases/rc2.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: TiDB RC2 Release Notes -category: Releases ---- - -# TiDB RC2 Release Notes - -2017 年 3 月 1 日，TiDB 正式发布 RC2 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。对于 OLTP 场景，读取性能提升 60%，写入性能提升 30%。另外提供了权限管理功能，用户可以按照 MySQL 的权限管理方式控制数据访问权限。 - -## TiDB - -+ SQL 查询优化器 - - 统计信息收集和使用 - - 关联子查询优化 - - 优化 CBO 框架 - - 通过 Unique Key 信息消除聚合 - - 重构 Expression - - Distinct 转换为 GroupBy - - 支持 topn 操作下推 -+ 支持基本权限管理 -+ 新增大量 MySQL 内建函数 -+ 完善 Alter Table 语句，支持修改表名、默认值、注释 -+ 支持 Create Table Like 语句 -+ 支持 Show Warnings 语句 -+ 支持 Rename Table 语句 -+ 限制单个事务大小，避免大事务阻塞整个集群 -+ Load Data 过程中对数据进行自动拆分 -+ 优化 AddIndex、Delete 语句性能 -+ 支持 "ANSI_QUOTES" sql_mode -+ 完善监控 -+ 修复 Bug -+ 修复内存泄漏问题 - -## PD - -+ 支持 Label 对副本进行 Location 调度 -+ 基于 region 数量的快速调度 -+ pd-ctl 支持更多功能 - - 添加、删除 PD - - 通过 Key 获取 Region 信息 - - 添加、删除 scheduler 和 operator - - 获取集群 label 信息 - -## TiKV - -+ 支持 Async Apply 提升整体写入性能 -+ 使用 prefix seek 提升 Write CF 的读取性能 -+ 使用 memory hint prefix 提升 Raft CF 插入性能 -+ 优化单行读事务性能 -+ 支持更多下推功能 -+ 加入更多统计 -+ 修复 Bug diff --git a/v3.1/releases/rc3.md b/v3.1/releases/rc3.md deleted file mode 100644 index 8c2705dd5e2d..000000000000 --- a/v3.1/releases/rc3.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: TiDB RC3 Release Notes -category: Releases ---- - -# TiDB RC3 Release Notes - -2017 年 6 月 16 日，TiDB 正式发布 RC3 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。性能方面重点优化了负载均衡调度策略和流程。功能方面进一步完善权限管理功能，用户可以按照 MySQL 的权限管理方式控制数据访问权限。另外 DDL 的速度也得到显著的提升。 -同时为了简化运维工作，开源了 TiDB Ansible 项目，可以一键部署/升级/启停 TiDB 集群。 - -## TiDB - -+ SQL 查询优化器 - - 统计信息收集和使用 - - 关联子查询优化 - - 优化 CBO 框架 - - 通过 Unique Key 信息消除聚合 - - 重构 Expression - - Distinct 转换为 GroupBy - - 支持 topn 操作下推 -+ 支持基本权限管理 -+ 新增大量 MySQL 内建函数 -+ 完善 Alter Table 语句，支持修改表名、默认值、注释 -+ 支持 Create Table Like 语句 -+ 支持 Show Warnings 语句 -+ 支持 Rename Table 语句 -+ 限制单个事务大小，避免大事务阻塞整个集群 -+ Load Data 过程中对数据进行自动拆分 -+ 优化 AddIndex、Delete 语句性能 -+ 支持 "ANSI_QUOTES" sql_mode -+ 完善监控 -+ 修复 Bug -+ 修复内存泄漏问题 - -## PD - -+ 支持 Label 对副本进行 Location 调度 -+ 基于 region 数量的快速调度 -+ pd-ctl 支持更多功能 - - 添加、删除 PD - - 通过 Key 获取 Region 信息 - - 添加、删除 scheduler 和 operator - - 获取集群 label 信息 - -## TiKV - -+ 支持 Async Apply 提升整体写入性能 -+ 使用 prefix seek 提升 Write CF 的读取性能 -+ 使用 memory hint prefix 提升 Raft CF 插入性能 -+ 优化单行读事务性能 -+ 支持更多下推功能 -+ 加入更多统计 -+ 修复 Bug diff --git a/v3.1/releases/rc4.md b/v3.1/releases/rc4.md deleted file mode 100644 index fb4e0eeea71c..000000000000 --- a/v3.1/releases/rc4.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: TiDB RC4 Release Notes -category: Releases ---- - -# TiDB RC4 Release Notes - -2017 年 8 月 4 日，TiDB 正式发布 RC4 版。该版本对 MySQL 兼容性、SQL 优化器、系统稳定性、性能做了大量的工作。性能方面重点优化了写入速度，计算任务调度支持优先级，避免分析型大事务影响在线事务。SQL 优化器全新改版，查询代价估算更加准确，且能够自动选择 Join 物理算子。功能方面进一步 MySQL 兼容性。 -同时为了更好的支持 OLAP 业务，开源了 TiSpark 项目，可以通过 Spark 读取和分析 TiKV 中的数据。 - -## TiDB - -+ SQL 查询优化器重构 - - 更好的支持 TopN 查询 - - 支持 Join 算子根据代价自动选择 - - 更完善的 Projection Elimination -+ Schema 版本检查区分 Table，避免 DDL 干扰其他正在执行的事务 -+ 支持 BatchIndexJoin -+ 完善 Explain 语句 -+ 提升 Index Scan 性能 -+ 大量 MySQL 兼容性相关功能 -+ 支持 Json 类型及其操作 -+ 支持查询优先级、隔离级别的设置 - -## PD - -+ 支持通过 PD 设置 TiKV location labels -+ 调度优化 - - 支持 PD 主动向 TiKV 下发调度命令 - - 加快 region heartbeat 响应速度 - - 优化 balance 算法 -+ 优化数据加载，加快 failover 速度 - -## TiKV - -+ 支持查询优先级设置 -+ 支持 RC 隔离级别 -+ 完善 Jepsen，提升稳定性 -+ 支持 Document Store -+ Coprocessor 支持更多下推函数 -+ 提升性能，提升稳定性 - -## TiSpark Beta Release - -+ 支持谓词下推 -+ 支持聚合下推 -+ 支持范围裁剪 -+ 通过 TPC-H 测试 (除去一个需要 View 的 Query) diff --git a/v3.1/releases/rn.md b/v3.1/releases/rn.md deleted file mode 100644 index dcd886180673..000000000000 --- a/v3.1/releases/rn.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: TiDB 版本发布历史 -category: release ---- - -# TiDB 版本发布历史 - -TiDB 历史版本发布声明如下： - -## 3.1 - -- [3.1.0-beta.1](/v3.1/releases/3.1.0-beta.1.md) -- [3.1.0-beta](/v3.1/releases/3.1.0-beta.md) - -## 3.0 - -- [3.0.10](/v3.1/releases/3.0.10.md) -- [3.0.9](/v3.1/releases/3.0.9.md) -- [3.0.8](/v3.1/releases/3.0.8.md) -- [3.0.7](/v3.1/releases/3.0.7.md) -- [3.0.6](/v3.1/releases/3.0.6.md) -- [3.0.5](/v3.1/releases/3.0.5.md) -- [3.0.4](/v3.1/releases/3.0.4.md) -- [3.0.3](/v3.1/releases/3.0.3.md) -- [3.0.2](/v3.1/releases/3.0.2.md) -- [3.0.1](/v3.1/releases/3.0.1.md) -- [3.0 GA](/v3.1/releases/3.0-ga.md) -- [3.0.0-rc.3](/v3.1/releases/3.0.0-rc.3.md) -- [3.0.0-rc.2](/v3.1/releases/3.0.0-rc.2.md) -- [3.0.0-rc.1](/v3.1/releases/3.0.0-rc.1.md) -- [3.0.0-beta.1](/v3.1/releases/3.0.0-beta.1.md) -- [3.0.0-beta](/v3.1/releases/3.0beta.md) - -## 2.1 - -- [2.1.19](/v3.1/releases/2.1.19.md) -- [2.1.18](/v3.1/releases/2.1.18.md) -- [2.1.17](/v3.1/releases/2.1.17.md) -- [2.1.16](/v3.1/releases/2.1.16.md) -- [2.1.15](/v3.1/releases/2.1.15.md) -- [2.1.14](/v3.1/releases/2.1.14.md) -- [2.1.13](/v3.1/releases/2.1.13.md) -- [2.1.12](/v3.1/releases/2.1.12.md) -- [2.1.11](/v3.1/releases/2.1.11.md) -- [2.1.10](/v3.1/releases/2.1.10.md) -- [2.1.9](/v3.1/releases/2.1.9.md) -- [2.1.8](/v3.1/releases/2.1.8.md) -- [2.1.7](/v3.1/releases/2.1.7.md) -- [2.1.6](/v3.1/releases/2.1.6.md) -- [2.1.5](/v3.1/releases/2.1.5.md) -- [2.1.4](/v3.1/releases/2.1.4.md) -- [2.1.3](/v3.1/releases/2.1.3.md) -- [2.1.2](/v3.1/releases/2.1.2.md) -- [2.1.1](/v3.1/releases/2.1.1.md) -- [2.1 GA](/v3.1/releases/2.1ga.md) -- [2.1 RC5](/v3.1/releases/21rc5.md) -- [2.1 RC4](/v3.1/releases/21rc4.md) -- [2.1 RC3](/v3.1/releases/21rc3.md) -- [2.1 RC2](/v3.1/releases/21rc2.md) -- [2.1 RC1](/v3.1/releases/21rc1.md) -- [2.1 Beta](/v3.1/releases/21beta.md) - -## 2.0 - -- [2.0.11](/v3.1/releases/2.0.11.md) -- [2.0.10](/v3.1/releases/2.0.10.md) -- [2.0.9](/v3.1/releases/209.md) -- [2.0.8](/v3.1/releases/208.md) -- [2.0.7](/v3.1/releases/207.md) -- [2.0.6](/v3.1/releases/206.md) -- [2.0.5](/v3.1/releases/205.md) -- [2.0.4](/v3.1/releases/204.md) -- [2.0.3](/v3.1/releases/203.md) -- [2.0.2](/v3.1/releases/202.md) -- [2.0.1](/v3.1/releases/201.md) -- [2.0](/v3.1/releases/2.0ga.md) -- [2.0 RC5](/v3.1/releases/2rc5.md) -- [2.0 RC4](/v3.1/releases/2rc4.md) -- [2.0 RC3](/v3.1/releases/2rc3.md) -- [2.0 RC1](/v3.1/releases/2rc1.md) -- [1.1 Beta](/v3.1/releases/11beta.md) -- [1.1 Alpha](/v3.1/releases/11alpha.md) - -## 1.0 - -- [1.0](/v3.1/releases/ga.md) -- [Pre-GA](/v3.1/releases/prega.md) -- [RC4](/v3.1/releases/rc4.md) -- [RC3](/v3.1/releases/rc3.md) -- [RC2](/v3.1/releases/rc2.md) -- [RC1](/v3.1/releases/rc1.md) diff --git a/v3.1/report-issue.md b/v3.1/report-issue.md deleted file mode 100644 index 070d8e04416a..000000000000 --- a/v3.1/report-issue.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 提交 Issue -category: report issue ---- - -# 提交 Issue - -我们正在努力使 TiDB 与 MySQL 5.7 兼容。如果您发现了任何未记录在文档中的表现差异、bug 或奇怪的性能特征，请[在 GitHub 中提交新的 Issue](https://github.com/pingcap/tidb/issues)。 - -在 GitHub 上提交的新 Issue 分为以下几种： - -- 错误报告 (Bug Reports) -- 功能请求 (Feature Requests) -- 常规问题 (General Questions) -- 性能问题 (Performance Questions) - -请确保您完全按照 Issue 模板进行填写，以便我们迅速定位问题并作出回应。 diff --git a/v3.1/roadmap.md b/v3.1/roadmap.md deleted file mode 100644 index 095c7f81d8b9..000000000000 --- a/v3.1/roadmap.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: TiDB 路线图 -category: Roadmap ---- - -# TiDB 路线图 - -## TiDB - -- [ ] 优化器 - - [ ] 统计信息优化 - - [ ] Multi-Column Statistics - - [ ] Cascades Planner - - [ ] Plan Management - - [ ] SQL Tuning Advisor - - [ ] Robust Access Path Selection：增加启发式规则，提升 OLTP 场景中索引选择正确率 - - [ ] Adaptive Query Optimization -- [ ] 执行引擎 - - [ ] 算子并行化 - - [ ] 内存控制 - - [ ] 并发控制 - - [ ] Shuffle 算子 - - [ ] Vectorized 表达式计算 - - [ ] UDF -- [ ] SQL 功能 - - [ ] 支持 View - - [ ] 支持窗口函数 - - [ ] 支持 Common Table Expression - - [ ] 支持 Hash 分区表 - - [ ] 支持 utf8_general_ci collation -- [ ] DDL 改进 - - [ ] 支持 Table Lock - - [ ] 支持 Change column type - - [ ] 支持单条语句中多个 DDL 操作 - - [ ] 支持不可见索引（invisible index） -- [ ] 支持插件系统 - - [ ] 支持白名单插件 - - [ ] 支持审计日志插件 - - [ ] 支持 RBAC 插件 - - [ ] 支持诊断插件 -- [ ] 支持 Query Tracing -- [ ] 支持行列混合存储引擎 -- [ ] 支持 New Storage Row Format，提升性能并减小内存占用 -- [ ] RowID 实现非整数类型 -- [ ] 事务 - - [ ] 减少读写冲突 - - [ ] 优化事务调度机制 - - [ ] 改善模型，降低延迟 - - [ ] 支持最小事务 (like the mini-transaction of InnoDB) - -## TiKV - -+ Raft - - [x] Region Merge - 合并小的 Region 以减少开销 - - [x] Local Read Thread - 把读请求放在一个单独的线程处理 - - [x] 批量 Region Split - 加速大的 Region 的分裂 - - [x] Raft Learner - 支持 Raft learner 使得成员变更过程更加平滑 - - [x] Raft Pre-voter - 支持 Raft Pre-vote 避免网络隔离带来不必要的选举 - - [ ] Joint Consensus - 安全地进行多个成员变更 - - [ ] 多线程 Raftstore - 在多个线程处理不同 Region 的 Raft 逻辑 - - [ ] 多线程 Apply Pool - 在多个线程执行不同 Region 已经提交了的命令 -+ Engine - - [ ] Titan - 把大的 key-values 从 LSM-Tree 中分离出来 - - [ ] 可拔插的 Engine 接口 - 简化接口逻辑并且提供可扩展性 -+ Storage - - [ ] 在 scheduler 里做流控提前避免 write stall -+ Transaction - - [x] 优化事务冲突 - - [ ] 分布式 GC - 把 MVCC 垃圾回收的逻辑分布到 TiKV 控制 -+ Coprocessor - - [x] Streaming - 把大的数据集切成小块返回以减少内存消耗 - - [ ] Chunk Execution - 按 chunk 的方式来处理数据以提高性能 - - [ ] 请求跟踪 - 提供单个请求执行的详细信息 -+ Tools - - [x] TiKV Importer - 通过直接导入 SST 文件的方式加速数据导入 -+ Client - - [ ] 提供 Rust 版本的 TiKV client - - [ ] gRPC 消息批量化 - 减少消息交互的开销 - -## PD - -- [x] Namespace 完善 - - [x] 不同 Namespace 或者 Table 配置不同的副本策略 -- [x] Table Region 分散调度 -- [x] 调度支持优先级，更加可控 -- [ ] 使用机器学习优化调度 -- [ ] 优化 Region 元信息存储 - 把元信息存储在一个独立的存储引擎里 - -## TiSpark - -- [ ] Limit/Order 下推 -- [x] DAG 接口接入（废除 Select 接口） -- [ ] Index Join 和并行 merge join -- [ ] Data Federation（桥接其他数据源，最好能和社区同步，这个接进来可以比较好扩展 Usecase，如果再做一个 InputFormat 适配就可以接 Hive 和 Presto 这些 Hadoop 上的数仓） - -## Tools - -- [x] 集群部署工具 -- [X] 高性能数据导入工具（lightning） -- [X] 集群备份和恢复工具（包括全量+增量备份，Mydumper + drainer/reparo） -- [X] 改进 TiDB Binlog 架构 -- [ ] 数据在线迁移工具（Syncer 升级版） -- [ ] 集群诊断和分析工具 diff --git a/v3.1/support-resources.md b/v3.1/support-resources.md deleted file mode 100644 index f705fb131484..000000000000 --- a/v3.1/support-resources.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 支持资源 -category: resources ---- - -# 支持资源 - -您可以通过以下任何一种方式找到我们的社区成员： - -+ Slack Channel: [https://pingcap.com/tidbslack](https://pingcap.com/tidbslack) -+ Stack Overflow: [https://stackoverflow.com/questions/tagged/tidb](https://stackoverflow.com/questions/tagged/tidb) -+ Reddit: [https://www.reddit.com/r/TiDB](https://www.reddit.com/r/TiDB) -+ GitHub: [https://github.com/pingcap/tidb/issues](https://github.com/pingcap/tidb/issues) - -有关企业支持合作的信息，请[联系我们](mailto:info@pingcap.com)。 diff --git a/v3.1/tidb-in-kubernetes/deploy/access-tidb.md b/v3.1/tidb-in-kubernetes/deploy/access-tidb.md deleted file mode 100644 index b35e73b759c9..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/access-tidb.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: 访问 Kubernetes 上的 TiDB 集群 -category: how-to ---- - -# 访问 Kubernetes 上的 TiDB 集群 - -在 Kubernetes 集群内访问 TiDB 时，使用 TiDB service 域名 `-tidb.` 即可。若需要在集群外访问，则需将 TiDB 服务端口暴露出去。在 `tidb-cluster` Helm chart 中，通过 `values.yaml` 文件中的 `tidb.service` 字段进行配置： - -{{< copyable "" >}} - -```yaml -tidb: - service: - type: NodePort - # externalTrafficPolicy: Cluster - # annotations: - # cloud.google.com/load-balancer-type: Internal -``` - -## NodePort - -在没有 LoadBalancer 时，可选择通过 NodePort 暴露。NodePort 有两种模式： - -- `externalTrafficPolicy=Cluster`：集群所有的机器都会给 TiDB 分配 TCP 端口，此为默认值 - - 使用 `Cluster` 模式时，可以通过任意一台机器的 IP 加同一个端口访问 TiDB 服务，如果该机器上没有 TiDB Pod，则相应请求会转发到有 TiDB Pod 的机器上。 - - > **注意：** - > - > 该模式下 TiDB 服务获取到的请求源 IP 是主机 IP，并不是真正的客户端源 IP，所以基于客户端源 IP 的访问权限控制在该模式下不可用。 - -- `externalTrafficPolicy=Local`：只有运行 TiDB 的机器会分配 TCP 端口，用于访问本地的 TiDB 实例 - - 使用 `Local` 模式时，建议打开 tidb-scheduler 的 `StableScheduling` 特性。tidb-scheduler 会尽可能在升级过程中将新 TiDB 实例调度到原机器，这样集群外的客户端便不需要在 TiDB 重启后更新配置。 - -### 查看 NodePort 模式下对外暴露的 IP/PORT - -查看 Service 分配的 Node Port，可通过获取 TiDB 的 Service 对象来获知： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n get svc -tidb -ojsonpath="{.spec.ports[?(@.name=='mysql-client')].nodePort}{'\n'}" -``` - -查看可通过哪些节点的 IP 访问 TiDB 服务，有两种情况： - -- `externalTrafficPolicy` 为 `Cluster` 时，所有节点 IP 均可 -- `externalTrafficPolicy` 为 `Local` 时，可通过以下命令获取指定集群的 TiDB 实例所在的节点 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl -n get pods -l "app.kubernetes.io/component=tidb,app.kubernetes.io/instance=" -ojsonpath="{range .items[*]}{.spec.nodeName}{'\n'}{end}" - ``` - -## LoadBalancer - -若运行在有 LoadBalancer 的环境，比如 GCP/AWS 平台，建议使用云平台的 LoadBalancer 特性。 - -访问 [Kubernetes Service 文档](https://kubernetes.io/docs/concepts/services-networking/service/)，了解更多 Service 特性以及云平台 Load Balancer 支持。 diff --git a/v3.1/tidb-in-kubernetes/deploy/alibaba-cloud.md b/v3.1/tidb-in-kubernetes/deploy/alibaba-cloud.md deleted file mode 100644 index 6e1cd9743519..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/alibaba-cloud.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: 在阿里云上部署 TiDB 集群 -category: how-to ---- - -# 在阿里云上部署 TiDB 集群 - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在阿里云上部署 TiDB 集群。 - -## 环境需求 - -- [aliyun-cli](https://github.com/aliyun/aliyun-cli) >= 3.0.15 并且[配置 aliyun-cli](https://www.alibabacloud.com/help/doc-detail/90766.htm?spm=a2c63.l28256.a3.4.7b52a893EFVglq) - - > **注意：** - > - > Access Key 需要具有操作相应资源的权限。 - -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.12 -- [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.1 且 <= 2.11.0 -- [jq](https://stedolan.github.io/jq/download/) >= 1.6 -- [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) 0.12.* - -你可以使用阿里云的[云命令行](https://shell.aliyun.com)服务来进行操作，云命令行中已经预装并配置好了所有工具。 - -### 权限 - -完整部署集群需要具备以下权限： - -- AliyunECSFullAccess -- AliyunESSFullAccess -- AliyunVPCFullAccess -- AliyunSLBFullAccess -- AliyunCSFullAccess -- AliyunEIPFullAccess -- AliyunECIFullAccess -- AliyunVPNGatewayFullAccess -- AliyunNATGatewayFullAccess - -## 概览 - -默认配置下，会创建： - -- 一个新的 VPC -- 一台 ECS 实例作为堡垒机 -- 一个托管版 ACK（阿里云 Kubernetes）集群以及一系列 worker 节点： - - 属于一个伸缩组的 2 台 ECS 实例（2 核 2 GB）托管版 Kubernetes 的默认伸缩组中必须至少有两台实例，用于承载整个的系统服务，例如 CoreDNS - - 属于一个伸缩组的 3 台 `ecs.g5.large` 实例，用于部署 PD - - 属于一个伸缩组的 3 台 `ecs.i2.2xlarge` 实例，用于部署 TiKV - - 属于一个伸缩组的 2 台 `ecs.c5.4xlarge` 实例用于部署 TiDB - - 属于一个伸缩组的 1 台 `ecs.c5.xlarge` 实例用于部署监控组件 - - 一块 100 GB 的云盘用作监控数据存储 - -除了默认伸缩组之外的其它所有实例都是跨可用区部署的。而伸缩组 (Auto-scaling Group) 能够保证集群的健康实例数等于期望数值。因此，当发生节点故障甚至可用区故障时，伸缩组能够自动为我们创建新实例来确保服务可用性。 - -## 安装部署 - -1. 设置目标 Region 和阿里云密钥（也可以在运行 `terraform` 命令时根据命令提示输入）： - - {{< copyable "shell-regular" >}} - - ```shell - export TF_VAR_ALICLOUD_REGION= && \ - export TF_VAR_ALICLOUD_ACCESS_KEY= && \ - export TF_VAR_ALICLOUD_SECRET_KEY= - ``` - - 用于部署集群的各变量的默认值存储在 `variables.tf` 文件中，如需定制可以修改此文件或在安装时通过 `-var` 参数覆盖。 - -2. 使用 Terraform 进行安装： - - {{< copyable "shell-regular" >}} - - ```shell - git clone --depth=1 https://github.com/pingcap/tidb-operator && \ - cd tidb-operator/deploy/aliyun - ``` - - {{< copyable "shell-regular" >}} - - ```shell - terraform init - ``` - - `apply` 过程中需要输入 `yes` 来确认执行： - - {{< copyable "shell-regular" >}} - - ```shell - terraform apply - ``` - - 假如在运行 `terraform apply` 时出现报错，可根据报错信息（例如缺少权限）进行修复后再次运行 `terraform apply`。 - - 整个安装过程大约需要 5 至 10 分钟，安装完成后会输出集群的关键信息（想要重新查看这些信息，可以运行 `terraform output`）： - - ``` - Apply complete! Resources: 3 added, 0 changed, 1 destroyed. - - Outputs: - - bastion_ip = 47.96.174.214 - cluster_id = c2d9b20854a194f158ef2bc8ea946f20e - kubeconfig_file = /tidb-operator/deploy/aliyun/credentials/kubeconfig - monitor_endpoint = 121.199.195.236:3000 - region = cn-hangzhou - ssh_key_file = /tidb-operator/deploy/aliyun/credentials/my-cluster-keyZ.pem - tidb_endpoint = 172.21.5.171:4000 - tidb_version = v3.0.0 - vpc_id = vpc-bp1v8i5rwsc7yh8dwyep5 - ``` - -3. 用 `kubectl` 或 `helm` 对集群进行操作： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG=$PWD/credentials/kubeconfig - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl version - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm ls - ``` - -## 连接数据库 - -通过堡垒机可连接 TiDB 集群进行测试，相关信息在安装完成后的输出中均可找到： - -{{< copyable "shell-regular" >}} - -```shell -ssh -i credentials/-key.pem root@ -``` - -{{< copyable "shell-regular" >}} - -```shell -mysql -h -P 4000 -u root -``` - -## 监控 - -访问 `` 就可以查看相关的 Grafana 监控面板。相关信息可在安装完成后的输出中找到。默认帐号密码为： - -- 用户名：admin -- 密码：admin - -> **警告：** -> -> 出于安全考虑，假如你已经或将要配置 VPN 用于访问 VPC，强烈建议将 `deploy/modules/aliyun/tidb-cluster/values/default.yaml` 文件里 `monitor.grafana.service.annotations` 中的 `service.beta.kubernetes.io/alicloud-loadbalancer-address-type` 设置为 `intranet` 以禁止监控服务的公网访问。 - -## 升级 TiDB 集群 - -设置 `variables.tf` 中的 `tidb_version` 参数，并再次运行 `terraform apply` 即可完成升级。 - -升级操作可能会执行较长时间，可以通过以下命令来持续观察进度： - -{{< copyable "shell-regular" >}} - -``` -kubectl get pods --namespace -o wide --watch -``` - -## TiDB 集群水平伸缩 - -按需修改 `variables.tf` 中的 `tikv_count` 和 `tidb_count` 数值，再次运行 `terraform apply` 即可完成 TiDB 集群的水平伸缩。 - -## 销毁集群 - -{{< copyable "shell-regular" >}} - -```shell -terraform destroy -``` - -假如 Kubernetes 集群没有创建成功，那么在 destroy 时会出现报错，无法进行正常清理。此时需要手动将 Kubernetes 资源从本地状态中移除： - -{{< copyable "shell-regular" >}} - -```shell -terraform state list -``` - -{{< copyable "shell-regular" >}} - -```shell -terraform state rm module.ack.alicloud_cs_managed_kubernetes.k8s -``` - -销毁集群操作需要执行较长时间。 - -> **注意：** -> -> 监控组件挂载的云盘需要在阿里云管理控制台中手动删除。 - -## 配置 - -### 配置 TiDB Operator - -通过调整 `variables.tf` 内的值来配置 TiDB Operator，大多数配置项均能按照 `variable` 的注释理解语义后进行修改。需要注意的是，`operator_helm_values` 配置项允许为 TiDB Operator 提供一个自定义的 `values.yaml` 配置文件，示例如下： - -- 在 `terraform.tfvars` 中设置 `operator_helm_values`： - - ```hcl - operator_helm_values = "./my-operator-values.yaml" - ``` - -- 在 `main.tf` 中设置 `operator_helm_values`： - - ```hcl - operator_helm_values = file("./my-operator-values.yaml") - ``` - -同时，在默认配置下 Terraform 脚本会创建一个新的 VPC，假如要使用现有的 VPC，可以在 `variable.tf` 中设置 `vpc_id`。注意，当使用现有 VPC 时，没有设置 vswitch 的可用区将不会部署 Kubernetes 节点。 - -### 配置 TiDB 集群 - -TiDB 集群会使用 `./my-cluster.yaml` 作为集群的 `values.yaml` 配置文件，修改该文件即可配置 TiDB 集群。支持的配置项可参考 [Kubernetes 上的 TiDB 集群配置](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 - -## 管理多个 TiDB 集群 - -需要在一个 Kubernetes 集群下管理多个 TiDB 集群时，需要编辑 `./main.tf`，按实际需要新增 `tidb-cluster` 声明，示例如下： - -```hcl -module "tidb-cluster-dev" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "dev-cluster" - ack = module.tidb-operator - - pd_count = 1 - tikv_count = 1 - tidb_count = 1 - override_values = file("dev-cluster.yaml") -} - -module "tidb-cluster-staging" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "staging-cluster" - ack = module.tidb-operator - - pd_count = 3 - tikv_count = 3 - tidb_count = 2 - override_values = file("staging-cluster.yaml") -} -``` - -注意，多个 TiDB 集群之间 `cluster_name` 必须保持唯一。下面是 `tidb-cluster` 模块的所有可配置参数： - -| 参数名 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `ack` | 封装目标 Kubernetes 集群信息的结构体，必填 | `nil` | -| `cluster_name` | TiDB 集群名，必填且必须唯一 | `nil` | -| `tidb_version` | TiDB 集群版本 | `v3.0.1` | -| `tidb_cluster_chart_version` | `tidb-cluster` helm chart 的版本 | `v1.0.1` | -| `pd_count` | PD 节点数 | 3 | -| `pd_instance_type` | PD 实例类型 | `ecs.g5.large` | -| `tikv_count` | TiKV 节点数 | 3 | -| `tikv_instance_type` | TiKV 实例类型 | `ecs.i2.2xlarge` | -| `tidb_count` | TiDB 节点数 | 2 | -| `tidb_instance_type` | TiDB 实例类型 | `ecs.c5.4xlarge` | -| `monitor_instance_type` | 监控组件的实例类型 | `ecs.c5.xlarge` | -| `override_values` | TiDB 集群的 `values.yaml` 配置文件，通常通过 `file()` 函数从文件中读取 | `nil` | -| `local_exec_interpreter` | 执行命令行指令的解释器 | `["/bin/sh", "-c"]` | - -## 管理多个 Kubernetes 集群 - -推荐针对每个 Kubernetes 集群都使用单独的 Terraform 模块进行管理（一个 Terraform Module 即一个包含 `.tf` 脚本的目录）。 - -`deploy/aliyun` 实际上是将 `deploy/modules` 中的数个可复用的 Terraform 脚本组合在了一起。当管理多个集群时（下面的操作在 `tidb-operator` 项目根目录下进行）： - -1. 首先针对每个集群创建一个目录，如： - - {{< copyable "shell-regular" >}} - - ```shell - mkdir -p deploy/aliyun-staging - ``` - -2. 参考 `deploy/aliyun` 的 `main.tf`，编写自己的脚本，下面是一个简单的例子： - - ```hcl - provider "alicloud" { - region = - access_key = - secret_key = - } - - module "tidb-operator" { - source = "../modules/aliyun/tidb-operator" - - region = - access_key = - secret_key = - cluster_name = "example-cluster" - key_file = "ssh-key.pem" - kubeconfig_file = "kubeconfig" - } - - provider "helm" { - alias = "default" - insecure = true - install_tiller = false - kubernetes { - config_path = module.tidb-operator.kubeconfig_filename - } - } - - module "tidb-cluster" { - source = "../modules/aliyun/tidb-cluster" - providers = { - helm = helm.default - } - - cluster_name = "example-cluster" - ack = module.tidb-operator - } - - module "bastion" { - source = "../modules/aliyun/bastion" - - bastion_name = "example-bastion" - key_name = module.tidb-operator.key_name - vpc_id = module.tidb-operator.vpc_id - vswitch_id = module.tidb-operator.vswitch_ids[0] - enable_ssh_to_worker = true - worker_security_group_id = module.tidb-operator.security_group_id - } - ``` - -上面的脚本可以自由定制，比如，假如不需要堡垒机则可以移除 `module "bastion"` 相关声明。 - -你也可以直接拷贝 `deploy/aliyun` 目录，但要注意不能拷贝已经运行了 `terraform apply` 的目录，建议重新 clone 仓库再进行拷贝。 - -## 使用限制 - -目前，`pod cidr`，`service cidr` 和节点型号等配置在集群创建后均无法修改。 diff --git a/v3.1/tidb-in-kubernetes/deploy/aws-eks.md b/v3.1/tidb-in-kubernetes/deploy/aws-eks.md deleted file mode 100644 index 1fa1a0517151..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/aws-eks.md +++ /dev/null @@ -1,527 +0,0 @@ ---- -title: 在 AWS EKS 上部署 TiDB 集群 -category: how-to ---- - -# 在 AWS EKS 上部署 TiDB 集群 - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在 AWS EKS (Elastic Kubernetes Service) 上部署 TiDB 集群。 - -## 环境配置准备 - -部署前，请确认已安装以下软件并完成配置： - -* [awscli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) >= 1.16.73，控制 AWS 资源 - - 要与 AWS 交互，必须[配置 `awscli`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)。最快的方式是使用 `aws configure` 命令: - - {{< copyable "shell-regular" >}} - - ``` shell - aws configure - ``` - - 替换下面的 AWS Access Key ID 和 AWS Secret Access Key： - - ``` - AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE - AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - Default region name [None]: us-west-2 - Default output format [None]: json - ``` - - > **注意：** - > - > Access key 必须至少具有以下权限：创建 VPC、创建 EBS、创建 EC2 和创建 Role。 - -* [terraform](https://learn.hashicorp.com/terraform/getting-started/install.html) >= 0.12 -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.11 -* [helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.0 且 < 3.0.0 -* [jq](https://stedolan.github.io/jq/download/) -* [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html)，AWS 权限鉴定工具，确保安装在 `PATH` 路径下。 - - 最简单的安装方法是下载编译好的二进制文件 `aws-iam-authenticator`，如下所示。 - - Linux 用户下载二进制文件： - - {{< copyable "shell-regular" >}} - - ``` shell - curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/linux/amd64/aws-iam-authenticator - ``` - - macOS 用户下载二进制文件： - - {{< copyable "shell-regular" >}} - - ``` shell - curl -o aws-iam-authenticator https://amazon-eks.s3-us-west-2.amazonaws.com/1.12.7/2019-03-27/bin/darwin/amd64/aws-iam-authenticator - ``` - - 二进制文件下载完成后，执行以下操作： - - {{< copyable "shell-regular" >}} - - ``` shell - chmod +x ./aws-iam-authenticator && \ - sudo mv ./aws-iam-authenticator /usr/local/bin/aws-iam-authenticator - ``` - -## 部署集群 - -默认部署会创建一个新的 VPC、一个 t2.micro 实例作为堡垒机，并包含以下 ec2 实例作为工作节点的 EKS 集群： - -* 3 台 m5.xlarge 实例，部署 PD -* 3 台 c5d.4xlarge 实例，部署 TiKV -* 2 台 c5.4xlarge 实例，部署 TiDB -* 1 台 c5.2xlarge 实例，部署监控组件 - -使用如下命令部署集群。 - -从 Github 克隆代码并进入指定路径： - -{{< copyable "shell-regular" >}} - -``` shell -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator/deploy/aws -``` - -使用 `terraform` 命令初始化并部署集群： - -{{< copyable "shell-regular" >}} - -``` shell -terraform init -``` - -{{< copyable "shell-regular" >}} - -``` shell -terraform apply -``` - -> **注意：** -> -> `terraform apply` 过程中必须输入 "yes" 才能继续。 - -整个过程可能至少需要 10 分钟。`terraform apply` 执行成功后，控制台会输出类似如下的信息： - -``` -Apply complete! Resources: 67 added，0 changed，0 destroyed. - -Outputs: - -bastion_ip = [ - "34.219.204.217", -] -default-cluster_monitor-dns = a82db513ba84511e9af170283460e413-1838961480.us-west-2.elb.amazonaws.com -default-cluster_tidb-dns = a82df6d13a84511e9af170283460e413-d3ce3b9335901d8c.elb.us-west-2.amazonaws.com -eks_endpoint = https://9A9A5ABB8303DDD35C0C2835A1801723.yl4.us-west-2.eks.amazonaws.com -eks_version = 1.12 -kubeconfig_filename = credentials/kubeconfig_my-cluster -region = us-west-21 -``` - -你可以通过 `terraform output` 命令再次获取上面的输出信息。 - -> **注意：** -> -> 1.14 版本以前的 EKS 不支持自动开启 NLB 跨可用区负载均衡，因此默认配置下 会出现各台 TiDB 实例压力不均衡额状况。生产环境下，强烈建议参考 [AWS 官方文档](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-disable-crosszone-lb.html#enable-cross-zone)手动开启 NLB 的跨可用区负载均衡。 - -## 访问数据库 - -`terraform apply` 完成后，可先通过 `ssh` 远程连接到堡垒机，再通过 MySQL client 来访问 TiDB 集群。 - -所需命令如下（用上面的输出信息替换 `<>` 部分内容)： - -{{< copyable "shell-regular" >}} - -```shell -ssh -i credentials/.pem centos@ -``` - -{{< copyable "shell-regular" >}} - -```shell -mysql -h -P 4000 -u root -``` - -`eks_name` 默认为 `my-cluster`。如果 DNS 名字无法解析，请耐心等待几分钟。 - -你还可以通过 `kubectl` 和 `helm` 命令使用 kubeconfig 文件 `credentials/kubeconfig_` 和 EKS 集群交互，主要有两种方式，如下所示。 - -- 指定 --kubeconfig 参数： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl --kubeconfig credentials/kubeconfig_ get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm --kubeconfig credentials/kubeconfig_ ls - ``` - -- 或者，设置 KUBECONFIG 环境变量： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG=$PWD/credentials/kubeconfig_ - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm ls - ``` - -## Grafana 监控 - -你可以通过浏览器访问 `:3000` 地址查看 Grafana 监控指标。 - -Grafana 默认登录信息： - -- 用户名：admin -- 密码：admin - -## 升级 TiDB 集群 - -要升级 TiDB 集群，可编辑 `variables.tf` 文件，修改 `default_cluster_version` 变量到更高版本，然后运行 `terraform apply`。 - -例如，要升级 TiDB 集群到 3.0.1，则修改 `default_cluster_version` 为 `v3.0.1`： - -```hcl -variable "default_cluster_version" { - default = "v3.0.1" -} -``` - -> **注意：** -> -> 升级过程会持续一段时间，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察升级进度。 - -## 扩容 TiDB 集群 - -若要扩容 TiDB 集群，可按需修改 `variables.tf` 文件中的 `default_cluster_tikv_count` 或者 `default_cluster_tidb_count` 变量，然后运行 `terraform apply`。 - -例如，可以将 `default_cluster_tidb_count` 从 2 改为 4 以扩容 TiDB： - -```hcl - variable "default_cluster_tidb_count" { - default = 4 - } -``` - -> **注意：** -> -> - 由于缩容过程中无法确定会缩掉哪个节点，目前还不支持 TiDB 集群的缩容。 -> - 扩容过程会持续几分钟，你可以通过 `kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch` 命令持续观察进度。 - -## 自定义 - -你可以按需修改 `variables.tf` 文件中的默认值，例如集群名称和镜像版本等。 - -### 自定义 AWS 相关的资源 - -默认情况下 terraform 脚本会新建 VPC。你也可以通过设置 `create_vpc` 为 `false`，并指定 `vpc_id`、`private_subnet_ids` 和 `public_subnet_ids` 变量为已有的 VPC id、subnet ids 来使用现有的网络。 - -> **注意：** -> -> - 由于 AWS 和 Terraform 的限制，还不支持复用已有 EKS 集群的 VPC 和 subnets，所以请确保只在你手动创建 VPC 的情况下修改该参数； -> - EKS Node 上的 CNI 插件会为每个节点预留一部分 IP 资源，因此 IP 消耗较大，在手动创建 VPC 时，建议将每个 subnet 的掩码长度设置在 18~20 以确保 IP 资源充足，或参考 [EKS CNI 插件文档](https://github.com/aws/amazon-vpc-cni-k8s#cni-configuration-variables)将节点预留的 IP 资源数调低。 - -由于 TiDB 服务通过 [Internal Elastic Load Balancer](https://aws.amazon.com/blogs/aws/internal-elastic-load-balancers/) 暴露，默认情况下，会创建一个 Amazon EC2 实例作为堡垒机，访问创建的 TiDB 集群。堡垒机上预装了 MySQL 和 Sysbench，所以你可以通过 SSH 方式登陆到堡垒机后通过 ELB 访问 TiDB。如果你的 VPC 中已经有了类似的 EC2 实例，你可以通过设置 `create_bastion` 为 `false` 禁掉堡垒机的创建。 - -TiDB 版本和组件数量也可以在 `variables.tf` 中修改，你可以按照自己的需求配置。 - -目前，由于 PD 和 TiKV 依赖 [NVMe SSD 实例存储卷](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html)，TiDB 集群组件的实例类型不能修改。 - -### 自定义 TiDB 参数配置 - -Terraform 脚本中为运行在 EKS 上的 TiDB 集群提供了合理的默认配置。有自定义需求时，你可以在 `clusters.tf` 中通过 `override_values` 参数为每个 TiDB 集群指定一个 `values.yaml` 文件来自定义集群参数配置。 - -作为例子，默认集群使用了 `./default-cluster.yaml` 作为 `values.yaml` 配置文件，并在配置中打开了"配置文件滚动更新"特性。 - -值得注意的是，在 EKS 上部分配置项无法在 `values.yaml` 中进行修改，包括集群版本、副本数、`NodeSelector` 以及 `Tolerations`。`NodeSelector` 和 `Tolerations` 由 Terraform 直接管理以确保基础设施与 TiDB 集群之间的一致性。集群版本和副本数可以通过 `cluster.tf` 文件中的 `tidb-cluster` module 参数来修改。 - -> **注意：** -> -> 自定义 `values.yaml` 配置文件中，不建议包含如下配置（`tidb-cluster` module 默认固定配置）： - -``` -pd: - storageClassName: ebs-gp2 -tikv: - stroageClassName: local-storage -tidb: - service: - type: LoadBalancer - annotations: - service.beta.kubernetes.io/aws-load-balancer-internal: '0.0.0.0/0' - service.beta.kubernetes.io/aws-load-balancer-type: nlb - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: >'true' - separateSlowLog: true -monitor: - storage: 100Gi - storageClassName: ebs-gp2 - persistent: true - grafana: - config: - GF_AUTH_ANONYMOUS_ENABLED: "true" - service: - type: LoadBalancer -``` - -### 自定义 TiDB Operator - -你可以通过 `variables.tf` 中的 `operator_values` 参数传入自定义的 `values.yaml` 内容来配置 TiDB Operator。示例如下： - -```hcl -variable "operator_values" { - description = "The helm values file for TiDB Operator, path is relative to current working dir" - default = "./operator_values.yaml" -} -``` - -## 管理多个 TiDB 集群 - -一个 `tidb-cluster` 模块的实例对应一个 TiDB 集群，你可以通过编辑 `clusters.tf` 添加新的 `tidb-cluster` 模块实例来新增 TiDB 集群，示例如下： - -```hcl -module example-cluster { - source = "../modules/aws/tidb-cluster" - - # The target EKS, required - eks = local.eks - # The subnets of node pools of this TiDB cluster, required - subnets = local.subnets - # TiDB cluster name, required - cluster_name = "example-cluster" - - # Helm values file - override_values = file("example-cluster.yaml") - # TiDB cluster version - cluster_version = "v3.0.0" - # SSH key of cluster nodes - ssh_key_name = module.key-pair.key_name - # PD replica number - pd_count = 3 - # TiKV instance type - pd_instance_type = "t2.xlarge" - # TiKV replica number - tikv_count = 3 - # TiKV instance type - tikv_instance_type = "t2.xlarge" - # The storage class used by TiKV, if the TiKV instance type do not have local SSD, you should change it to storage class - # TiDB replica number - tidb_count = 2 - # TiDB instance type - tidb_instance_type = "t2.xlarge" - # Monitor instance type - monitor_instance_type = "t2.xlarge" - # The version of tidb-cluster helm chart - tidb_cluster_chart_version = "v1.0.0" -} -``` - -> **注意：** -> -> `cluster_name` 必须是唯一的。 - -你可以通过 `kubectl` 获取新集群的监控系统地址与 TiDB 地址。假如你希望让 Terraform 脚本输出这些地址，可以通过在 `outputs.tf` 中增加相关的输出项实现： - -```hcl -output "example-cluster_tidb-hostname" { - value = module.example-cluster.tidb_hostname -} - -output "example-cluster_monitor-hostname" { - value = module.example-cluster.monitor_hostname -} -``` - -修改完成后，执行 `terraform init` 和 `terraform apply` 创建集群。 - -最后，只要移除 `tidb-cluster` 模块调用，对应的 TiDB 集群就会被销毁，EC2 资源也会随之释放。 - -## 仅管理基础设施 - -通过调整配置，你可以控制 Terraform 脚本只创建 Kubernetes 集群和 TiDB Operator。操作步骤如下： - -* 修改 `clusters.tf` 中 TiDB 集群的 `create_tidb_cluster_release` 配置项： - - ```hcl - module "default-cluster" { - ... - create_tidb_cluster_release = false - } - ``` - - 如上所示，当 `create_tidb_cluster_release` 设置为 `false` 时，Terraform 脚本不会创建和修改 TiDB 集群，但仍会创建 TiDB 集群所需的计算和存储资源。此时，你可以使用 Helm 等工具来独立管理集群。 - -> **注意：** -> -> 在已经部署的集群上将 `create_tidb_cluster_release` 调整为 `false` 会导致已安装的 TiDB 集群被删除，对应的 TiDB 集群对象也会随之被删除。 - -## 销毁集群 - -可以通过如下命令销毁集群： - -{{< copyable "shell-regular" >}} - -```shell -terraform destroy -``` - -> **注意：** -> -> * 该操作会销毁 EKS 集群以及部署在该 EKS 集群上的所有 TiDB 集群。 -> * 如果你不再需要存储卷中的数据，在执行 `terraform destroy` 后，你需要在 AWS 控制台手动删除 EBS 卷。 - -## 管理多个 Kubernetes 集群 - -本节详细介绍了如何管理多个 Kubernetes 集群（EKS），并在每个集群上部署一个或更多 TiDB 集群。 - -上述文档中介绍的 Terraform 脚本组合了多个 Terraform 模块： - -- `tidb-operator` 模块，用于创建 EKS 集群并在 EKS 集群上安装配置 [TiDB Operator](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md)。 -- `tidb-cluster` 模块，用于创建 TiDB 集群所需的资源池并部署 TiDB 集群。 -- EKS 上的 TiDB 集群专用的 `vpc` 模块、`key-pair`模块和`bastion` 模块 - -管理多个 Kubernetes 集群的最佳实践是为每个 Kubernetes 集群创建一个单独的目录，并在新目录中自行组合上述 Terraform 模块。这种方式能够保证多个集群间的 Terraform 状态不会互相影响，也便于自由定制和扩展。下面是一个例子： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p deploy/aws-staging -vim deploy/aws-staging/main.tf -``` - -`deploy/aws-staging/main.tf` 的内容可以是： - -```hcl -provider "aws" { - region = "us-west-1" -} - -# 创建一个 ssh key，用于登录堡垒机和 Kubernetes 节点 -module "key-pair" { - source = "../modules/aws/key-pair" - - name = "another-eks-cluster" - path = "${path.cwd}/credentials/" -} - -# 创建一个新的 VPC -module "vpc" { - source = "../modules/aws/vpc" - - vpc_name = "another-eks-cluster" -} - -# 在上面的 VPC 中创建一个 EKS 并部署 tidb-operator -module "tidb-operator" { - source = "../modules/aws/tidb-operator" - - eks_name = "another-eks-cluster" - config_output_path = "credentials/" - subnets = module.vpc.private_subnets - vpc_id = module.vpc.vpc_id - ssh_key_name = module.key-pair.key_name -} - -# 特殊处理，确保 helm 操作在 EKS 创建完毕后进行 -resource "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.eks] - sensitive_content = module.tidb-operator.eks.kubeconfig - filename = module.tidb-operator.eks.kubeconfig_filename -} -provider "helm" { - alias = "eks" - insecure = true - install_tiller = false - kubernetes { - config_path = local_file.kubeconfig.filename - } -} - -# 在上面的 EKS 集群上创建一个 TiDB 集群 -module "tidb-cluster-a" { - source = "../modules/aws/tidb-cluster" - providers = { - helm = "helm.eks" - } - - cluster_name = "tidb-cluster-a" - eks = module.tidb-operator.eks - ssh_key_name = module.key-pair.key_name - subnets = module.vpc.private_subnets -} - -# 在上面的 EKS 集群上创建另一个 TiDB 集群 -module "tidb-cluster-b" { - source = "../modules/aws/tidb-cluster" - providers = { - helm = "helm.eks" - } - - cluster_name = "tidb-cluster-b" - eks = module.tidb-operator.eks - ssh_key_name = module.key-pair.key_name - subnets = module.vpc.private_subnets -} - -# 创建一台堡垒机 -module "bastion" { - source = "../modules/aws/bastion" - - bastion_name = "another-eks-cluster-bastion" - key_name = module.key-pair.key_name - public_subnets = module.vpc.public_subnets - vpc_id = module.vpc.vpc_id - target_security_group_id = module.tidb-operator.eks.worker_security_group_id - enable_ssh_to_workers = true -} - -# 输出 tidb-cluster-a 的 TiDB 服务地址 -output "cluster-a_tidb-dns" { - description = "tidb service endpoints" - value = module.tidb-cluster-a.tidb_hostname -} - -# 输出 tidb-cluster-b 的监控地址 -output "cluster-b_monitor-dns" { - description = "tidb service endpoint" - value = module.tidb-cluster-b.monitor_hostname -} - -# 输出堡垒机 IP -output "bastion_ip" { - description = "Bastion IP address" - value = module.bastion.bastion_ip -} -``` - -上面的例子很容易进行定制，比如，假如你不需要堡垒机，便可以删去对 `bastion` 模块的调用。同时，项目中提供的 Terraform 模块均设置了合理的默认值，因此在调用这些 Terraform 模块时，你可以略去大部分的参数。 - -你可以参考默认的 Terraform 脚本来定制每个模块的参数，也可以参考每个模块的 `variables.tf` 文件来了解所有可配置的参数。 - -另外，这些 Terraform 模块可以很容易地集成到你自己的 Terraform 工作流中。假如你对 Terraform 非常熟悉，这也是我们推荐的一种使用方式。 - -> **注意：** -> -> * 由于 Terraform 本身的限制（[hashicorp/terraform#2430](https://github.com/hashicorp/terraform/issues/2430#issuecomment-370685911)），在你自己的 Terraform 脚本中，也需要保留上述例子中对 `helm provider` 的特殊处理。 -> * 创建新目录时，需要注意与 Terraform 模块之间的相对路径，这会影响调用模块时的 `source` 参数。 -> * 假如你想在 tidb-operator 项目之外使用这些模块，你需要确保 `modules` 目录中的所有模块的相对路径保持不变。 - -假如你不想自己写 Terraform 代码，也可以直接拷贝 `deploy/aws` 目录来创建新的 Kubernetes 集群。但要注意不能拷贝已经运行过 `terraform apply` 的目录（已经有 Terraform 的本地状态）。这种情况下，推荐在拷贝前克隆一个新的仓库。 diff --git a/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md b/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md deleted file mode 100644 index b1f817070f6b..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md +++ /dev/null @@ -1,740 +0,0 @@ ---- -title: 在 GCP GKE 上部署 TiDB 集群 -summary: 了解如何在 GCP GKE 上部署 TiDB 集群。 -category: how-to ---- - -# 在 GCP GKE 上部署 TiDB 集群 - - - -本文介绍了如何使用个人电脑（Linux 或 macOS 系统）在 GCP GKE 上部署 TiDB 集群。 - -> **警告：** -> -> 当前多磁盘聚合功能[存在一些已知问题](https://github.com/pingcap/tidb-operator/issues/684)，不建议在生产环境中每节点配置一块以上磁盘。我们正在修复此问题。 - -## 环境准备 - -部署前，确认已安装以下软件： - -* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -* [Google Cloud SDK](https://cloud.google.com/sdk/install) -* [Terraform](https://www.terraform.io/downloads.html) >= 0.12 -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) >= 1.14 -* [Helm](https://helm.sh/docs/using_helm/#installing-the-helm-client) >= 2.9.0 且 < 3.0.0 -* [jq](https://stedolan.github.io/jq/download/) - -## 配置 - -为保证部署顺利，需要提前进行一些配置。在开始配置 Google Cloud SDK、API、Terraform 前，先下载以下资源： - -{{< copyable "shell-regular" >}} - -```bash -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator/deploy/gcp -``` - -### 配置 Google Cloud SDK - -安装 Google Cloud SDK 后，需要执行 `gcloud init` 进行[初始化](https://cloud.google.com/sdk/docs/initializing)。 - -### 配置 API - -如果使用的 GCP 项目是新项目，需确保以下 API 已启用： - -{{< copyable "shell-regular" >}} - -```bash -gcloud services enable cloudresourcemanager.googleapis.com \ -cloudbilling.googleapis.com iam.googleapis.com \ -compute.googleapis.com container.googleapis.com -``` - -### 配置 Terraform - -要执行 Terraform 脚本，需要设置以下 3 个环境变量。你可以等 Terraform 提示再输入，也可以提前在 `.tfvars` 文件中定义变量。 - -+ `GCP_CREDENTIALS_PATH`：GCP 证书文件路径。 - - - 建议另建一个服务账号给 Terraform 使用，参考[创建与管理服务账号文档](https://cloud.google.com/iam/docs/creating-managing-service-accounts)。`./create-service-account.sh` 会创建最低权限的服务账号。 - - - 参考[服务账号密钥文档](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)来创建服务账号密钥。下面脚本中的步骤详细说明了如何使用 `deploy/gcp` 目录中提供的脚本执行此操作。或者，如果自己创建服务账号和密钥，可以在创建时选择 `JSON` 类型的密钥。下载的包含私钥的 `JSON` 文件即所需的证书文件。 - -+ `GCP_REGION`：创建资源所在的区域，例如：`us-west1`。 -+ `GCP_PROJECT`：GCP 项目的名称。 - -要使用以上 3 个环境变量来配置 Terraform，可执行以下步骤： - -1. 将 `GCP_REGION` 替换为你的 GCP Region。 - - {{< copyable "shell-regular" >}} - - ```bash - echo GCP_REGION=\"us-west1\" >> terraform.tfvars - ``` - -2. 将 `GCP_PROJECT` 替换为你的 GCP 项目名称，确保连接的是正确的 GCP 项目。 - - {{< copyable "shell-regular" >}} - - ```bash - echo "GCP_PROJECT=\"$(gcloud config get-value project)\"" >> terraform.tfvars - ``` - -3. 初始化 Terraform。 - - {{< copyable "shell-regular" >}} - - ```bash - terraform init - ``` - -4. 为 Terraform 创建一个有限权限的服务账号，并设置证书路径。 - - {{< copyable "shell-regular" >}} - - ```bash - ./create-service-account.sh - ``` - -Terraform 自动加载和填充匹配 `terraform.tfvars` 或 `*.auto.tfvars` 文件的变量。相关详细信息，请参阅 [Terraform 文档](https://learn.hashicorp.com/terraform/getting-started/variables.html)。上述步骤会使用 `GCP_REGION` 和 `GCP_PROJECT` 填充 `terraform.tfvars` 文件，使用 `GCP_CREDENTIALS_PATH` 填充 `credentials.auto.tfvars` 文件。 - -## 部署 TiDB 集群 - -本小节介绍如何部署 TiDB 集群。 - -1. 确定实例类型。 - - - 如果只是想试一下 TiDB，又不想花费太高成本，可以采用轻量级的配置： - - {{< copyable "shell-regular" >}} - - ```bash - cat small.tfvars >> terraform.tfvars - ``` - - - 如果要对生产环境的部署进行 benchmark 测试，则建议采用生产级的配置： - - {{< copyable "shell-regular" >}} - - ```bash - cat prod.tfvars >> terraform.tfvars - ``` - - `prod.tfvars` 会默认创建一个新的 VPC，两个子网和一个 f1-micro 实例作为堡垒机，以及使用以下实例类型作为工作节点的 GKE 集群： - - * 3 台 n1-standard-4 实例：部署 PD - * 3 台 n1-highmem-8 实例：部署 TiKV - * 3 台 n1-standard-16 实例：部署 TiDB - * 3 台 n1-standard-2 实例：部署监控组件 - - 如上所述，生产环境的部署需要 91 个 CPU，超过了 GCP 项目的默认配额。可以参考[配额](https://cloud.google.com/compute/quotas)来增加项目配额。扩容同样需要更多 CPU。 - - > **注意：** - > - > 工作节点的数量取决于指定 Region 中可用区的数量。大部分 Region 有 3 个可用区，但是 `us-central1` 有 4 个可用区。参考 [Regions and Zones](https://cloud.google.com/compute/docs/regions-zones/) 查看更多信息。参考[自定义](#自定义)部分来自定义区域集群的节点池。 - -2. 启动脚本来部署 TiDB 集群： - - {{< copyable "shell-regular" >}} - - ```bash - terraform apply - ``` - - > **注意：** - > - > 如果未提前设置上文所述的 3 个环境变量，执行 `terraform apply` 过程中会有提示出现，要求对 3 个变量进行设置。详情请参考[配置 Terraform](#配置-terraform)。 - - 整个过程可能至少需要 10 分钟。`terraform apply` 执行成功后，会输出类似如下的信息: - - ``` - Apply complete! Resources: 23 added, 0 changed, 0 destroyed. - - Outputs: - - how_to_connect_to_default_cluster_tidb_from_bastion = mysql -h 172.31.252.20 -P 4000 -u root - how_to_ssh_to_bastion = gcloud compute ssh tidb-cluster-bastion --zone us-west1-b - how_to_set_reclaim_policy_of_pv_for_default_tidb_cluster_to_delete = kubectl --kubeconfig /.../credentials/kubeconfig_tidb-cluster get pvc -n tidb-cluster -o jsonpath='{.items[*].spec.volumeName}'|fmt -1 | xargs -I {} kubectl --kubeconfig /.../credentials/kubeconfig_tidb-cluster patch pv {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - kubeconfig_file = ./credentials/kubeconfig_tidb-cluster - monitor_lb_ip = 35.227.134.146 - monitor_port = 3000 - region = us-west1 - tidb_version = v3.0.1 - ``` - -## 访问 TiDB 数据库 - -`terraform apply` 运行完成后，可执行以下步骤来访问 TiDB 数据库。注意用[部署 TiDB 集群](#部署-tidb-集群)小节的输出信息替换 `<>` 部分的内容。 - -1. 通过 `ssh` 远程连接到堡垒机。 - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute ssh -bastion --zone - ``` - -2. 通过 MySQL 客户端来访问 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```bash - mysql -h -P 4000 -u root - ``` - - > **注意：** - > - > 通过 MySQL 连接 TiDB 前，需要先安装 MySQL 客户端。 - -## 与 GKE 集群交互 - -你可以通过 `kubectl` 和 `helm` 使用 kubeconfig 文件 `credentials/kubeconfig_` 和 GKE 集群交互。交互方式主要有以下两种。 - -> **注意：** -> -> `gke_cluster_name` 默认为 `tidb-cluster`，可以通过 `variables.tf` 中 `gke_name` 修改。 - -- 指定 `--kubeconfig` 参数： - - {{< copyable "shell-regular" >}} - - ```bash - kubectl --kubeconfig credentials/kubeconfig_ get po -n - ``` - - > **注意：** - > - > 下面这条命令使用的 `--kubeconfig` 参数至少需要 Helm 2.10.0 版本以上。 - - {{< copyable "shell-regular" >}} - - ```bash - helm --kubeconfig credentials/kubeconfig_ ls - ``` - -- 设置 `KUBECONFIG` 环境变量： - - {{< copyable "shell-regular" >}} - - ```bash - export KUBECONFIG=$PWD/credentials/kubeconfig_ - ``` - - {{< copyable "shell-regular" >}} - - ```bash - kubectl get po -n - ``` - - {{< copyable "shell-regular" >}} - - ```bash - helm ls - ``` - -## 升级 TiDB 集群 - -要升级 TiDB 集群，可执行以下步骤： - -1. 编辑 `variables.tf` 文件，将 `tidb_version` 变量的值修改为更高版本。 -2. 运行 `terraform apply`。 - -例如，要将 TiDB 集群升级到 3.0.0-rc.2，可修改 `tidb_version` 为 `v3.0.0-rc.2`： - -``` -variable "tidb_version" { - description = "TiDB version" - default = "v3.0.0-rc.2" -} -``` - -升级过程会持续一段时间。你可以通过以下命令来持续观察升级进度： - -{{< copyable "shell-regular" >}} - -```bash -kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch -``` - -然后，你可以[访问数据库](#访问-tidb-数据库)并通过 `tidb_version()` 确认 TiDB 集群是否升级成功： - -{{< copyable "sql" >}} - -```sql -select tidb_version(); -``` - -``` -*************************** 1. row *************************** -tidb_version(): Release Version: v3.0.0-rc.2 -Git Commit Hash: 06f3f63d5a87e7f0436c0618cf524fea7172eb93 -Git Branch: HEAD -UTC Build Time: 2019-05-28 12:48:52 -GoVersion: go version go1.12 linux/amd64 -Race Enabled: false -TiKV Min Version: 2.1.0-alpha.1-ff3dd160846b7d1aed9079c389fc188f7f5ea13e -Check Table Before Drop: false -1 row in set (0.001 sec) -``` - -## 管理多个 TiDB 集群 - -一个 `tidb-cluster` 模块的实例对应一个 GKE 集群中的 TiDB 集群。要添加一个新的 TiDB 集群，可执行以下步骤： - -1. 编辑 `tidbclusters.tf` 文件来添加一个 `tidb-cluster` 模块。 - - 例如： - - {{< copyable "" >}} - - ```hcl - module "example-tidb-cluster" { - providers = { - helm = "helm.gke" - } - source = "../modules/gcp/tidb-cluster" - cluster_id = module.tidb-operator.cluster_id - tidb_operator_id = module.tidb-operator.tidb_operator_id - gcp_project = var.GCP_PROJECT - gke_cluster_location = local.location - gke_cluster_name = - cluster_name = - cluster_version = "v3.0.1" - kubeconfig_path = local.kubeconfig - tidb_cluster_chart_version = "v1.0.0" - pd_instance_type = "n1-standard-1" - tikv_instance_type = "n1-standard-4" - tidb_instance_type = "n1-standard-2" - monitor_instance_type = "n1-standard-1" - pd_node_count = 1 - tikv_node_count = 2 - tidb_node_count = 1 - monitor_node_count = 1 - } - ``` - - > **注意：** - > - > - 每个集群的 `cluster_name` 必须是唯一的。 - > - 为任一组件实际创建的总节点数等于配置文件中的节点数乘以该 Region 中可用区的个数。 - - 你可以通过 `kubectl` 获取创建的 TiDB 集群和监控组件的地址。如果你希望 Terraform 脚本打印此信息，可在 `outputs.tf` 中添加一个 `output` 配置项，如下所示： - - {{< copyable "" >}} - - ```hcl - output "how_to_connect_to_example_tidb_cluster_from_bastion" { - value = module.example-tidb-cluster.how_to_connect_to_tidb_from_bastion - } - ``` - - 上述配置可使该脚本打印出用于连接 TiDB 集群的命令。 - -2. 修改完成后，执行以下命令来创建集群。 - - {{< copyable "shell-regular" >}} - - ```bash - terraform init - ``` - - {{< copyable "shell-regular" >}} - - ```bash - terraform apply - ``` - -## 扩容 - -如果需要扩容 TiDB 集群，可执行以下步骤： - -1. 按需修改 `variables.tf` 文件中的 `tikv_count`、`tidb_count` 变量。 -2. 运行 `terraform apply`。 - -> **警告：** -> -> 由于缩容过程中无法确定哪个节点会被删除，因此目前不支持集群缩容。通过修改 `tikv_count` 来进行缩容可能会导致数据丢失。 - -扩容过程会持续几分钟，你可以通过以下命令来持续观察进度： - -{{< copyable "shell-regular" >}} - -``` -kubectl --kubeconfig credentials/kubeconfig_ get po -n --watch -``` - -例如，可以将 `tidb_count` 从 1 改为 2 来扩容 TiDB： - -```hcl -variable "tidb_count" { - description = "Number of TiDB nodes per availability zone" - default = 2 -} -``` - -> **注意：** -> -> 增加节点数量会在每个可用区都增加节点。 - -## 自定义 - -你可以更改 `variables.tf` 中的默认值，例如集群名称和镜像版本等，但更建议在 `terraform.tfvars` 文件或其它相关文件中来指定值。 - -### 自定义 GCP 资源 - -GCP 允许 `n1-standard-1` 或者更大的实例类型挂载本地 SSD，这提供了更好的自定义特性。 - -### 自定义 TiDB 参数配置 - -Terraform 脚本为 GKE 中的 TiDB 集群提供了默认设置。你也可以在 `tidbclusters.tf` 中为每个 TiDB 集群指定一个覆盖配置 `override_values` 或者覆盖配置文件 `override_values_file`。如果同时配置两个变量，`override_values` 配置将生效，该自定义配置会覆盖默认设置，示例如下： - -{{< copyable "" >}} - -``` -override_values = <}} - -``` -override_values_file = "./test-cluster.yaml" -``` - -集群默认使用 `deploy/modules/gcp/tidb-cluster` 模块中的 `values/default.yaml` 作为覆盖配置文件。 - -在 GKE 中，某些值不支持在 `values.yaml` 中自定义，包括集群版本、副本数、`NodeSelector` 以及 `Tolerations`。`NodeSelector` 和 `Tolerations` 由 Terraform 直接管理，以确保基础设施与 TiDB 集群之间的一致性。 - -如果需要自定义集群版本和副本数，可以修改 `tidbclusters.tf` 文件中每个 `tidb-cluster` module 的参数。 - -> **注意：** -> -> 自定义配置中，不建议在 `values.yaml` 中包含以下配置（`tidb-cluster` module 默认固定配置）： - -```yaml -pd: - storageClassName: pd-ssd -tikv: - stroageClassName: local-storage -tidb: - service: - type: LoadBalancer - annotations: - cloud.google.com/load-balancer-type: "Internal" - separateSlowLog: true -monitor: - storageClassName: pd-ssd - persistent: true - grafana: - config: - GF_AUTH_ANONYMOUS_ENABLED: "true" - service: - type: LoadBalancer -``` - -### 自定义 TiDB Operator - -如果要自定义 TiDB Operator，可以使用 `operator_helm_values` 变量来指定覆盖配置或者使用 `operator_helm_values_file` 变量来指定覆盖配置文件。如果同时配置两个变量，`operator_helm_values` 配置将生效，该自定义配置会传递给 `tidb-operator` 模块，示例如下： - -{{< copyable "" >}} - -``` -operator_helm_values = <}} - -``` -operator_helm_values_file = "./test-operator.yaml" -``` - -### 自定义日志 - -GKE 使用 [Fluentd](https://www.fluentd.org/) 作为其默认的日志收集工具，然后将日志转发到 Stackdriver。Fluentd 进程可能会占用大量资源，消耗大量的 CPU 和 RAM。[Fluent Bit](https://fluentbit.io/) 是一种性能更高，资源占用更少的替代方案。与 Fluentd 相比，更建议在生产环境中使用 Fluent Bit。可参考[在 GKE 集群中设置 Fluent Bit 的示例](https://github.com/pingcap/k8s-fluent-bit-stackdriver)。 - -### 自定义节点池 - -集群是按区域 (regional) 而非按可用区 (zonal) 来创建的。也就是说，GKE 向每个可用区复制相同的节点池，以实现更高的可用性。但对于 Grafana 这样的监控服务来说，通常没有必要维护相同的可用性。你可以通过 `gcloud` 手动删除节点。 - -> **注意：** -> -> GKE 节点池通过实例组管理。如果你使用 `gcloud compute instances delete` 命令删除某个节点，GKE 会自动重新创建节点并将其添加到集群。 - -如果你需要从监控节点池中删掉一个节点，可采用如下步骤： - -1. 获取托管的实例组和所在可用区。 - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed list | grep monitor - ``` - - 输出结果类似： - - ``` - gke-tidb-monitor-pool-08578e18-grp us-west1-b zone gke-tidb-monitor-pool-08578e18 0 0 gke-tidb-monitor-pool-08578e18 no - gke-tidb-monitor-pool-7e31100f-grp us-west1-c zone gke-tidb-monitor-pool-7e31100f 1 1 gke-tidb-monitor-pool-7e31100f no - gke-tidb-monitor-pool-78a961e5-grp us-west1-a zone gke-tidb-monitor-pool-78a961e5 1 1 gke-tidb-monitor-pool-78a961e5 no - ``` - - 第一列是托管的实例组，第二列是所在的可用区。 - -2. 获取实例组中的实例名字。 - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed list-instances --zone - ``` - - 示例： - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed list-instances gke-tidb-monitor-pool-08578e18-grp --zone us-west1-b - ``` - - 输出结果类似： - - ``` - NAME ZONE STATUS ACTION INSTANCE_TEMPLATE VERSION_NAME LAST_ERROR - gke-tidb-monitor-pool-08578e18-c7vd us-west1-b RUNNING NONE gke-tidb-monitor-pool-08578e18 - ``` - -3. 通过指定托管的实例组和实例的名称来删掉该实例。 - - 例如： - - {{< copyable "shell-regular" >}} - - ```bash - gcloud compute instance-groups managed delete-instances gke-tidb-monitor-pool-08578e18-grp --instances=gke-tidb-monitor-pool-08578e18-c7vd --zone us-west1-b - ``` - -## 销毁 TiDB 集群 - -如果你不想再继续使用 TiDB 集群，可以通过如下命令进行销毁： - -{{< copyable "shell-regular" >}} - -```bash -terraform destroy -``` - -> **注意：** -> -> 在执行 `terraform destroy` 过程中，可能会发生错误：`Error reading Container Cluster "tidb": Cluster "tidb" has status "RECONCILING" with message""`。当 GCP 升级 Kubernetes master 节点时会出现该问题。一旦问题出现，就无法删除集群，需要等待 GCP 升级结束，再次执行 `terraform destroy`。 - -### 删除磁盘 - -如果你不再需要之前的数据，并且想要删除正在使用的磁盘，有以下两种方法可以完成此操作： - -- 手动删除：在 Google Cloud Console 中删除磁盘，或使用 `gcloud` 命令行工具执行删除操作。 - -- 自动删除：在执行 `terraform destroy` 之前将 Kubernetes 的 PV (Persistent Volume) 回收策略设置为 `Delete`，具体操作为在 `terraform destroy` 之前运行以下 `kubectl` 命令： - - {{< copyable "shell-regular" >}} - - ```bash - kubectl --kubeconfig /path/to/kubeconfig/file get pvc -n namespace-of-tidb-cluster -o jsonpath='{.items[*].spec.volumeName}'|fmt -1 | xargs -I {} kubectl --kubeconfig /path/to/kubeconfig/file patch pv {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - ``` - - 上述命令将获取 TiDB 集群命名空间中的 PVC (Persistent Volume Claim)，并将绑定的 PV 的回收策略设置为 `Delete`。在执行 `terraform destroy` 过程中删除 PVC 时，也会将磁盘删除。 - - 下面是一个名为 `change-pv-reclaimpolicy.sh` 的脚本。相对于仓库根目录来说，它在 `deploy/gcp` 目录，简化了上述过程。 - - {{< copyable "shell-regular" >}} - - ```bash - ./change-pv-reclaimpolicy.sh /path/to/kubeconfig/file - ``` - -## 管理多个 Kubernetes 集群 - -本节介绍管理多个 Kubernetes 集群的最佳实践，其中每个 Kubernetes 集群都可以部署一个或多个 TiDB 集群。 - -在 TiDB 的案例中，Terraform 模块通常结合了几个子模块： - -- `tidb-operator`：为 TiDB 集群提供 [Kubernetes Control Plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) 并部署 TiDB Operator。 -- `tidb-cluster`：在目标 Kubernetes 集群中创建资源池并部署 TiDB 集群。 -- 一个 `vpc` 模块，一个 `bastion` 模块和一个 `project-credentials` 模块：专门用于 GKE 上的 TiDB 集群。 - -管理多个 Kubernetes 集群的最佳实践有以下两点： - -1. 为每个 Kubernetes 集群创建一个新目录。 -2. 根据具体需求，使用 Terraform 脚本将上述模块进行组合。 - -如果采用了最佳实践，集群中的 Terraform 状态不会相互干扰，并且可以很方便地管理多个 Kubernetes 集群。示例如下（假设已在项目根目录）： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p deploy/gcp-staging && \ -vim deploy/gcp-staging/main.tf -``` - -`deploy/gcp-staging/main.tf` 中的内容类似： - -```hcl -provider "google" { - credentials = file(var.GCP_CREDENTIALS_PATH) - region = var.GCP_REGION - project = var.GCP_PROJECT -} - -// required for taints on node pools -provider "google-beta" { - credentials = file(var.GCP_CREDENTIALS_PATH) - region = var.GCP_REGION - project = var.GCP_PROJECT -} - -locals { - gke_name = "another-gke-name" - credential_path = "${path.cwd}/credentials" - kubeconfig = "${local.credential_path}/kubeconfig_${var.gke_name}" -} - - -module "project-credentials" { - source = "../modules/gcp/project-credentials" - - path = local.credential_path -} - -module "vpc" { - source = "../modules/gcp/vpc" - create_vpc = true - gcp_project = var.GCP_PROJECT - gcp_region = var.GCP_REGION - vpc_name = "${locals.gke_name}-vpc-network" - private_subnet_name = "${locals.gke_name}-private-subnet" - public_subnet_name = "${locals.gke_name}-public-subnet" -} - -module "tidb-operator" { - source = "../modules/gcp/tidb-operator" - gke_name = locals.gke_name - vpc_name = module.vpc.vpc_name - subnetwork_name = module.vpc.private_subnetwork_name - gcp_project = var.GCP_PROJECT - gcp_region = var.GCP_REGION - kubeconfig_path = local.kubeconfig - tidb_operator_version = "v1.0.0" -} - -module "bastion" { - source = "../modules/gcp/bastion" - vpc_name = module.vpc.vpc_name - public_subnet_name = module.vpc.public_subnetwork_name - gcp_project = var.GCP_PROJECT - bastion_name = "${locals.gke_name}-tidb-bastion" -} - -# HACK: 强制使 Helm 依赖 GKE 集群 -data "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.cluster_id] - filename = module.tidb-operator.kubeconfig_path -} -resource "local_file" "kubeconfig" { - depends_on = [module.tidb-operator.cluster_id] - content = data.local_file.kubeconfig.content - filename = module.tidb-operator.kubeconfig_path -} - -provider "helm" { - alias = "gke" - insecure = true - install_tiller = false - kubernetes { - config_path = local_file.kubeconfig.filename - } -} -module "tidb-cluster-a" { - providers = { - helm = "helm.gke" - } - source = "../modules/gcp/tidb-cluster" - gcp_project = var.GCP_PROJECT - gke_cluster_location = var.GCP_REGION - gke_cluster_name = locals.gke_name - cluster_name = "tidb-cluster-a" - cluster_version = "v3.0.1" - kubeconfig_path = module.tidb-operator.kubeconfig_path - tidb_cluster_chart_version = "v1.0.0" - pd_instance_type = "n1-standard-1" - tikv_instance_type = "n1-standard-4" - tidb_instance_type = "n1-standard-2" - monitor_instance_type = "n1-standard-1" -} - -module "tidb-cluster-b" { - providers = { - helm = "helm.gke" - } - source = "../modules/gcp/tidb-cluster" - gcp_project = var.GCP_PROJECT - gke_cluster_location = var.GCP_REGION - gke_cluster_name = locals.gke_name - cluster_name = "tidb-cluster-b" - cluster_version = "v3.0.1" - kubeconfig_path = module.tidb-operator.kubeconfig_path - tidb_cluster_chart_version = "v1.0.0" - pd_instance_type = "n1-standard-1" - tikv_instance_type = "n1-standard-4" - tidb_instance_type = "n1-standard-2" - monitor_instance_type = "n1-standard-1" -} - -output "how_to_ssh_to_bastion" { - value= module.bastion.how_to_ssh_to_bastion -} - -output "connect_to_tidb_cluster_a_from_bastion" { - value = module.tidb-cluster-a.how_to_connect_to_default_cluster_tidb_from_bastion -} - -output "connect_to_tidb_cluster_b_from_bastion" { - value = module.tidb-cluster-b.how_to_connect_to_default_cluster_tidb_from_bastion -} - -``` - -如上述代码所示，你可以在每个模块调用中省略几个参数，因为有合理的默认值，并且可以轻松地自定义配置。例如，如果你不需要调用堡垒机模块，将其删除即可。 - -如果要自定义每个字段，可使用以下两种方法中的一种： - -- 直接修改 `*.tf` 文件中 `module` 的参数配置。 -- 参考每个模块的 `variables.tf` 文件，了解所有可修改的参数，并在 `terraform.tfvars` 中设置自定义值。 - -> **注意：** -> -> - 创建新目录时，请注意其与 Terraform 模块的相对路径，这会影响模块调用期间的 `source` 参数。 -> - 如果要在 tidb-operator 项目之外使用这些模块，务必确保复制整个 `modules` 目录并保持目录中每个模块的相对路径不变。 -> - 由于 Terraform 的限制[（参见 hashicorp/terraform＃2430）](https://github.com/hashicorp/terraform/issues/2430#issuecomment-370685911)，上面示例中添加了 **HACK: 强制使 Helm 依赖 GKE 集群**部分对 Helm provider 进行处理。如果自己编写 tf 文件，需要包含这部分内容。 - -如果你不愿意编写 Terraform 代码，还可以复制 `deploy/gcp` 目录来创建新的 Kubernetes 集群。但需要注意，不能复制已被执行 `terraform apply` 命令的目录。在这种情况下，建议先克隆新的仓库再复制目录。 diff --git a/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md b/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md deleted file mode 100644 index 625e241c3332..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 在标准 Kubernetes 上部署 TiDB 集群 -category: how-to ---- - -# 在标准 Kubernetes 上部署 TiDB 集群 - -本文主要描述了如何在标准的 Kubernetes 集群上通过 TiDB Operator 部署 TiDB 集群。 - -## 前置条件 - -* 参考 [TiDB Operator](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md) 完成集群中的 TiDB Operator 部署； -* 参考 [使用 Helm](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 - -## 配置 TiDB 集群 - -通过下面命令获取待安装的 tidb-cluster chart 的 `values.yaml` 配置文件： - -{{< copyable "shell-regular" >}} - -```shell -mkdir -p /home/tidb/ && \ -helm inspect values pingcap/tidb-cluster --version= > /home/tidb//values-.yaml -``` - -> **注意：** -> -> - `/home/tidb` 可以替换为你想用的目录。 -> - `release-name` 将会作为 Kubernetes 相关资源（例如 Pod，Service 等）的前缀名，可以起一个方便记忆的名字，要求全局唯一，通过 `helm ls -q` 可以查看集群中已经有的 `release-name`。 -> - `chart-version` 是 tidb-cluster chart 发布的版本，可以通过 `helm search -l tidb-cluster` 查看当前支持的版本。 -> - 下文会用 `values.yaml` 指代 `/home/tidb//values-.yaml`。 - -### 存储类型 - -集群默认使用 `local-storage` 存储类型。 - -- 生产环境：推荐使用本地存储，但实际 Kubernetes 集群中本地存储可能按磁盘类型进行了分类，例如 `nvme-disks`，`sas-disks`。 -- 演示环境或功能性验证：可以使用网络存储，例如 `ebs`，`nfs` 等。 - -另外 TiDB 集群不同组件对磁盘的要求不一样，所以部署集群前要根据当前 Kubernetes 集群支持的存储类型以及使用场景为 TiDB 集群各组件选择合适的存储类型，通过修改 `values.yaml` 中各组件的 `storageClassName` 字段设置存储类型。关于 Kubernetes 集群支持哪些[存储类型](/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md)，请联系系统管理员确定。 - -> **注意：** -> -> 如果创建集群时设置了集群中不存在的存储类型，则会导致集群创建处于 Pending 状态，需要[将集群彻底销毁掉](/v3.1/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md)。 - -### 集群拓扑 - -默认部署的集群拓扑是：3 个 PD Pod，3 个 TiKV Pod，2 个 TiDB Pod 和 1 个监控 Pod。在该部署拓扑下根据数据高可用原则，TiDB Operator 扩展调度器要求 Kubernetes 集群中至少有 3 个节点。如果 Kubernetes 集群节点个数少于 3 个，将会导致有一个 PD Pod 处于 Pending 状态，而 TiKV 和 TiDB Pod 也都不会被创建。 - -Kubernetes 集群节点个数少于 3 个时，为了使 TiDB 集群能启动起来，可以将默认部署的 PD 和 TiKV Pod 个数都减小到 1 个，或者将 `values.yaml` 中 `schedulerName` 改为 Kubernetes 内置调度器 `default-scheduler`。 - -> **警告：** -> -> `default-scheduler` 仅适用于演示环境，改为 `default-scheduler` 后，TiDB 集群的调度将无法保证数据高可用，另外一些其它特性也无法支持，例如 [TiDB Pod StableScheduling](https://github.com/pingcap/tidb-operator/blob/master/docs/design-proposals/tidb-stable-scheduling.md) 等。 - -其它更多配置参数请参考 [TiDB 集群部署配置文档](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)。 - -## 部署 TiDB 集群 - -TiDB Operator 部署并配置完成后，可以通过下面命令部署 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster --name= --namespace= --version= -f /home/tidb//values-.yaml -``` - -> **注意：** -> -> `namespace` 是[命名空间](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)，你可以起一个方便记忆的名字，比如和 `release-name` 相同的名称。 - -通过下面命令可以查看 Pod 状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get po -n -l app.kubernetes.io/instance= -``` - -单个 Kubernetes 集群中可以利用 TiDB Operator 部署管理多套 TiDB 集群，重复以上命令并将 `release-name` 替换成不同名字即可。不同集群既可以在相同 `namespace` 中，也可以在不同 `namespace` 中，可根据实际需求进行选择。 diff --git a/v3.1/tidb-in-kubernetes/deploy/prerequisites.md b/v3.1/tidb-in-kubernetes/deploy/prerequisites.md deleted file mode 100644 index 427f19de2b98..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/prerequisites.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群环境需求 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群环境需求 - -本文介绍在 Kubernetes 上部署 TiDB 集群的软硬件环境需求。 - -## 软件版本要求 - -| 软件名称 | 版本 | -| :--- | :--- | -| Docker | Docker CE 18.09.6 | -| Kubernetes | v1.12.5+ | -| CentOS | CentOS 7.6，内核要求为 3.10.0-957 或之后版本 | - -## 内核参数设置 - -| 配置项 | 设置值 | -| :--- | :--- | -| net.core.somaxconn | 32768 | -| vm.swappiness | 0 | -| net.ipv4.tcp_syncookies | 0 | -| net.ipv4.ip_forward | 1 | -| fs.file-max | 1000000 | -| fs.inotify.max_user_watches | 1048576 | -| fs.inotify.max_user_instances | 1024 | -| net.ipv4.conf.all.rp_filter | 1 | -| net.ipv4.neigh.default.gc_thresh1 | 80000 | -| net.ipv4.neigh.default.gc_thresh2 | 90000 | -| net.ipv4.neigh.default.gc_thresh3 | 100000 | -| net.bridge.bridge-nf-call-iptables | 1 | -| net.bridge.bridge-nf-call-arptables | 1 | -| net.bridge.bridge-nf-call-ip6tables | 1 | - -在设置 `net.bridge.bridge-nf-call-*` 这几项参数时，如果选项报错，则可通过如下命令检查是否已经加载该模块： - -{{< copyable "shell-regular" >}} - -```shell -lsmod|grep br_netfilter -``` - -如果没有加载，则执行如下命令加载： - -{{< copyable "shell-regular" >}} - -```shell -modprobe br_netfilter -``` - -同时还需要关闭每个部署 Kubernetes 节点的 swap，执行如下命令： - -{{< copyable "shell-regular" >}} - -```shell -swapoff -a -``` - -执行如下命令检查 swap 是否已经关闭： - -{{< copyable "shell-regular" >}} - -```shell -free -m -``` - -如果执行命令后输出显示 swap 一列全是 0，则表明 swap 已经关闭。 - -此外，为了永久性地关闭 swap，还需要将 `/etc/fstab` 中 swap 相关的条目全部删除。 - -在上述内容都设置完成后，还需要检查是否给机器配置了 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt)，也就是将各个设备对应的中断号分别绑定到不同的 CPU 上，以防止所有中断请求都落在同一个 CPU 上而引发性能瓶颈。对于 TiDB 集群来说，网卡处理包的速度对集群的吞吐率影响很大。因此下文主要描述如何将网卡中断号绑定到特定的 CPU 上，充分利用多核的优势来提高集群的吞吐率。首先可以通过以下命令来查看网卡对应的中断号： - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/interrupts|grep |awk '{print $1,$NF}' -``` - -以上命令输出的第一列是中断号，第二列是设备名称。如果是多队列网卡，上面的命令会显示多行信息，网卡的每个队列对应一个中断号。通过以下命令可以查看该中断号被绑定到哪个 CPU 上： - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/irq//smp_affinity -``` - -上面命令输出 CPU 序号对应的十六进制值。输出结果欠直观。具体计算方法可参见 [SMP IRQ Affinity](https://cs.uwaterloo.ca/~brecht/servers/apic/SMP-affinity.txt) 文档。 - -{{< copyable "shell-regular" >}} - -```shell -cat /proc/irq//smp_affinity_list -``` - -上面命令输出 CPU 序号对应的十进制值，输出结果较为直观。 - -如果多队列网卡对应的所有中断号都已被绑定到不同的 CPU 上，那么该机器的 SMP IRQ Affinity 配置是正确的。如果中断号都落在同一个 CPU 上，则需要进行调整。调整的方式有以下两种： - -+ 方法一：开启 [irqbalance](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-tool_reference-irqbalance) 服务。在 centos7 系统上的开启命令如下: - - {{< copyable "shell-regular" >}} - - ```shell - systemctl start irqbalance - ``` - -+ 方法二：禁用 irqbalance，自定义中断号和 CPU 的绑定关系。详情参见脚本 [set_irq_affinity.sh](https://gist.githubusercontent.com/SaveTheRbtz/8875474/raw/0c6e500e81e161505d9111ac77115a2367180d12/set_irq_affinity.sh)。 - -上文所描述的是处理多队列网卡和多核心的场景。单队列网卡和多核的场景则有不同的处理方式。在这种场景下，可以使用 [RPS/RFS](https://www.kernel.org/doc/Documentation/networking/scaling.txt) 在软件层面模拟实现硬件的网卡多队列功能 (RSS)。此时不能使用方法一所述的 irqbalance 服务，而是通过使用方法二提供的脚本来设置 RPS。RFS 的配置可以参考[这里](https://access.redhat.com/documentation/zh-cn/red_hat_enterprise_linux/7/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-networking-configuration_tools#sect-Red_Hat_Enterprise_Linux-Performance_Tuning_Guide-Configuration_tools-Configuring_Receive_Flow_Steering_RFS)。 - -## 硬件和部署要求 - -与使用 binary 方式部署 TiDB 集群一致，要求选用 Intel x86-64 架构的 64 位通用硬件服务器，使用万兆网卡。关于 TiDB 集群在物理机上的具体部署需求，参考 [TiDB 软件和硬件环境建议配置](/v3.1/how-to/deploy/hardware-recommendations.md)。 - -对于服务器 disk、memory、CPU 的选择要根据对集群的容量规划以及部署拓扑来定。线上 Kubernetes 集群部署为了保证高可用，一般需要部署三个 master 节点、三个 etcd 节点以及若干个 worker 节点。同时，为了充分利用机器资源，master 节点一般也充当 worker 节点（也就是 master 节点上也可以调度负载）。通过 kubelet 设置[预留资源](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/)来保证机器上的系统进程以及 Kubernetes 的核心进程在工作负载很高的情况下仍然有足够的资源来运行，从而保证整个系统的稳定。 - -下面按 3 Kubernetes master + 3 etcd + 若干 worker 节点部署方案进行分析。Kubernetes 的多 master 节点高可用部署可参考[官方文档](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/)。 - -## Kubernetes 系统资源要求 - -- 每台机器需要一块比较大的 SAS 盘（至少 1T），这块盘用来存 Docker 和 kubelet 的数据目录。Docker 的数据主要包括镜像和容器日志数据，kubelet 主要占盘的数据是 [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) 所使用的数据。 - -- 如果需要部署 Kubernetes 集群的监控系统, 且监控数据需要落盘，则也需要考虑为 Prometheus 准备一块 SAS 盘，后面日志监控系统也需要大的 SAS 盘，同时考虑到机器采购最好是同构的这一因素，因此每台机器最好有两块大的 SAS 盘。 - - > **注意：** - > - > 生产环境建议给这两种类型的盘做 RAID5，至于使用多少块来做 RAID5 可自己决定。 - -- etcd 的分布建议是和 Kubernetes master 节点保持一致，即有多少个 master 节点就部署多少个 etcd 节点。etcd 数据建议使用 SSD 盘存放。 - -## TiDB 集群资源需求 - -TiDB 集群由 PD、TiKV、TiDB 三个组件组成，在做容量规划的时候一般按照可以支持多少套 TiDB 集群来算。这里按照标准的 TiDB 集群（3 个 PD + 3 个 TiKV + 2 个 TiDB）来算，下面是对每个组件规划的一种建议： - -- PD 组件：PD 占用资源较少，这种集群规模下分配 2C 4GB 即可，占用少量本地盘。 - - 为了便于管理，可以将所有集群的 PD 都放在 master 节点，比如需要支持 5 套 TiDB 集群，则可以规划 3 个 master 节点，每个节点支持部署 5 个 PD 实例，5 个 PD 实例使用同一块 SSD 盘即可（两三百 GB 的盘即可）。通过 bind mount 的方式在这块 SSD 上创建 5 个目录作为挂载点，操作方式见 [Sharing a disk filesystem by multiple filesystem PVs](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)。 - - 如果后续要添加更多机器支持更多的 TiDB 集群，可以在 master 上用这种方式继续增加 PD 实例。如果 master 上资源耗尽，可以找其它的 worker 节点机器用同样的方式添加 PD 实例。这种方式的好处就是方便规划和管理 PD 实例，坏处就是由于 PD 实例过于集中，这些机器中如果有两台宕机会导致所有的 TiDB 集群不可用。 - - 因此建议从所有集群里面的机器都拿出一块 SSD 盘像 master 节点一样提供 PD 实例。比如总共 7 台机器，要支持 7 套 TiDB 标准集群的情况下，则需要每台机器上都能支持部署 3 个 PD 实例，如果后续有集群需要通过扩容机器增加容量，也只需要在新的机器上创建 PD 实例。 - -- TiKV 组件：因为 TiKV 组件的性能很依赖磁盘 I/O 且数据量一般较大，因此建议每个 TiKV 实例独占一块 NVMe 的盘，资源配置为 8C 32GB。如果想要在一个机器上支持部署多个 TiKV 实例，则建议参考这些参数去选择合适的机器，同时在规划容量的时候应当预留出足够的 buffer。 - -- TiDB 组件：TiDB 组件因为不占用磁盘，因此在规划的时候只需要考虑其占用的 CPU 和内存资源即可，这里也按 8C 32 GB 的容量来计算。 - -## TiDB 集群规划示例 - -通过上面的分析，这里给出一个支持部署 5 套规模为 3 个 PD + 3 个 TiKV + 2 个 TiDB 集群的例子，其中 PD 配置为 2C 4GB，TiDB 配置为 8C 32GB，TiKV 配置为 8C 32GB。Kubernetes 节点有 7 个，其中有 3 个节点既是 master 又是 worker 节点，另外 4 个是纯 worker 节点。各组件分布情况如下： - -+ 单个 master 节点： - - - 1 etcd (2C 4GB) + 2 PD (2 \* 2C 2 \* 4GB) + 3 TiKV (3 \* 8C 3 \* 32GB) + 1 TiDB (8C 32GB)，总共是 38C 140GB - - 两块 SSD 盘，一块给 etcd，另外一块给 2 个 PD 实例 - - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 - - 三块 NVMe 盘给 TiKV 实例 - -+ 单个 worker 节点： - - - 3 PD (3 \* 2C 3 \* 4GB) + 2 TiKV (2 \* 8C 2 \* 32GB) + 2 TiDB (2 \* 8C 2 \* 32GB)，总共是 38C 140GB - - 一块 SSD 盘给三个 PD 实例 - - 做了 RAID5 的 SAS 盘，给 Docker 和 kubelet 做数据盘 - - 两块 NVMe 盘给 TiKV 实例 - -从上面的分析来看，要支持 5 套 TiDB 集群容量共需要 7 台物理机，其中 3 台为 master 兼 worker 节点，其余 4 台为 worker 节点，机器配置需求如下： - -- master 兼 worker 节点：48C 192GB；2 块 SSD 盘，一块做了 RAID5 的 SAS 盘，三块 NVMe 盘 -- worker 节点：48C 192GB；1 块 SSD 盘，一块做了 RAID5 的 SAS 盘，两块 NVMe 盘 - -使用上面的机器配置，除去各个组件占用的资源外，还有比较多的预留资源。如果要考虑加监控和日志组件，则可以用同样的方法去规划需要采购的机器类型以及配置。 - -另外，在生产环境的使用上尽量不要在 master 节点部署 TiDB 实例，或者尽可能少地部署 TiDB 实例。这里的主要考虑点是网卡带宽，因为 master 节点网卡满负荷工作会影响到 worker 节点和 master 节点之间的心跳信息汇报，导致比较严重的问题。 diff --git a/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md b/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md deleted file mode 100644 index 0ef82d4ec79e..000000000000 --- a/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: 在 Kubernetes 上部署 TiDB Operator -summary: 了解如何在 Kubernetes 上部署 TiDB Operator -category: how-to ---- - -# 在 Kubernetes 上部署 TiDB Operator - -本文介绍如何在 Kubernetes 上部署 TiDB Operator。 - -## 准备环境 - -TiDB Operator 部署前，请确认以下软件需求： - -* Kubernetes v1.12 或者更高版本 -* [DNS 插件](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/) -* [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) -* [RBAC](https://kubernetes.io/docs/admin/authorization/rbac) 启用（可选） -* [Helm](https://helm.sh) 版本 >= v2.8.2 && < v3.0.0 - -> **注意：** -> -> - 尽管 TiDB Operator 可以使用网络卷持久化 TiDB 数据，TiDB 数据自身会存多副本，再走额外的网络卷通常会比较慢。强烈建议搭建[本地卷](https://kubernetes.io/docs/concepts/storage/volumes/#local)以提高性能。 -> - 跨多可用区的网络卷需要 Kubernetes v1.12 或者更高版本。在 `tidb-backup` chart 配置中，建议使用网络卷存储备份数据。 - -## 部署 Kubernetes 集群 - -TiDB Operator 运行在 Kubernetes 集群，你可以使用 [Getting started 页面](https://kubernetes.io/docs/setup/)列出的任何一种方法搭建一套 Kubernetes 集群。只要保证 Kubernetes 版本大于等于 v1.12。如果你使用 AWS、GKE 或者本机，下面是快速上手教程： - -* [kind 教程](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) -* [Google GKE 教程](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) -* [AWS EKS 教程](/v3.1/tidb-in-kubernetes/deploy/aws-eks.md) - -如果你要使用不同环境，必须在 Kubernetes 集群中安装 DNS 插件。可以根据[官方文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-dns-cluster/)搭建 DNS 插件。 - -TiDB Operator 使用[持久化卷](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)持久化存储 TiDB 集群数据（包括数据库，监控和备份数据），所以 Kubernetes 集群必须提供至少一种持久化卷。为提高性能，建议使用本地 SSD 盘作为持久化卷。可以根据[这一步](#配置本地持久化卷)自动配置本地持久化卷。 - -Kubernetes 集群建议启用 [RBAC](https://kubernetes.io/docs/admin/authorization/rbac)。否则，需要在 `tidb-operator` 和 `tidb-cluster` chart 的 `values.yaml` 中设置 `rbac.create` 为 `false`。 - -TiDB 默认会使用很多文件描述符，工作节点和上面的 Docker 进程的 `ulimit` 必须设置大于等于 `1048576`： - -* 设置工作节点的 `ulimit` 值，详情可以参考[如何设置 ulimit](https://access.redhat.com/solutions/61334) - - {{< copyable "shell-regular" >}} - - ```shell - sudo vim /etc/security/limits.conf - ``` - - 设置 root 账号的 `soft` 和 `hard` 的 `nofile` 大于等于 `1048576` - -* 设置 Docker 服务的 `ulimit` - - {{< copyable "shell-regular" >}} - - ```shell - sudo vim /etc/systemd/system/docker.service - ``` - - 设置 `LimitNOFILE` 大于等于 `1048576`。 - -> **注意：** -> -> `LimitNOFILE` 需要显式设置为 `1048576` 或者更大，而不是默认的 `infinity`，由于 `systemd` 的 [bug](https://github.com/systemd/systemd/commit/6385cb31ef443be3e0d6da5ea62a267a49174688#diff-108b33cf1bd0765d116dd401376ca356L1186)，`infinity` 在 `systemd` 某些版本中指的是 `65536`。 - -## 安装 Helm - -参考 [使用 Helm](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 安装 Helm 并配置 PingCAP 官方 chart 仓库。 - -## 配置本地持久化卷 - -### 准备本地卷 - -参考[本地 PV 配置](/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)在你的 Kubernetes 集群中配置本地持久化卷。 - -## 安装 TiDB Operator - -TiDB Operator 使用 [CRD (Custom Resource Definition)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) 扩展 Kubernetes，所以要使用 TiDB Operator，必须先创建 `TidbCluster` 自定义资源类型。只需要在你的 Kubernetes 集群上创建一次即可： - -{{< copyable "shell-regular" >}} - -```shell -kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/crd.yaml && \ -kubectl get crd tidbclusters.pingcap.com -``` - -创建 `TidbCluster` 自定义资源类型后，接下来在 Kubernetes 集群上安装 TiDB Operator。 - -1. 获取你要安装的 `tidb-operator` chart 中的 `values.yaml` 文件： - - {{< copyable "shell-regular" >}} - - ```shell - mkdir -p /home/tidb/tidb-operator && \ - helm inspect values pingcap/tidb-operator --version= > /home/tidb/tidb-operator/values-tidb-operator.yaml - ``` - - > **注意：** - > - > `` 在后续文档中代表 chart 版本，例如 `v1.0.0`，可以通过 `helm search -l tidb-operator` 查看当前支持的版本。 - -2. 配置 TiDB Operator - - TiDB Operator 里面会用到 `k8s.gcr.io/kube-scheduler` 镜像，如果下载不了该镜像，可以修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 文件中的 `scheduler.kubeSchedulerImageName` 为 `registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler`。 - -3. 安装 TiDB Operator - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-operator --name=tidb-operator --namespace=tidb-admin --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml && \ - kubectl get po -n tidb-admin -l app.kubernetes.io/name=tidb-operator - ``` - -## 自定义 TiDB Operator - -通过修改 `/home/tidb/tidb-operator/values-tidb-operator.yaml` 中的配置自定义 TiDB Operator。后续文档使用 `values.yaml` 指代 `/home/tidb/tidb-operator/values-tidb-operator.yaml`。 - -TiDB Operator 有两个组件： - -* tidb-controller-manager -* tidb-scheduler - -这两个组件是无状态的，通过 `Deployment` 部署。你可以在 `values.yaml` 中自定义资源 `limit`、`request` 和 `replicas`。 - -修改为 `values.yaml` 后，执行下面命令使配置生效： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade tidb-operator pingcap/tidb-operator --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml -``` diff --git a/v3.1/tidb-in-kubernetes/faq.md b/v3.1/tidb-in-kubernetes/faq.md deleted file mode 100644 index 900a53625aa0..000000000000 --- a/v3.1/tidb-in-kubernetes/faq.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群常见问题 -category: FAQ ---- - -# Kubernetes 上的 TiDB 集群常见问题 - -本文介绍 Kubernetes 上的 TiDB 集群常见问题以及解决方案。 - -## 如何修改时区设置？ - -默认情况下，在 Kubernetes 集群上部署的 TiDB 集群各组件容器中的时区为 UTC，如果要修改时区配置，有下面两种情况： - -* 第一次部署集群 - - 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后部署 TiDB 集群。 - -* 集群已经在运行 - - 如果 TiDB 集群已经在运行，需要做如下修改： - - * 在 TiDB 集群的 `values.yaml` 文件中，修改 `timezone` 配置，例如：`timezone: Asia/Shanghai`，然后升级 TiDB 集群。 - * 参考[时区支持](/v3.1/how-to/configure/time-zone.md)，修改 TiDB 服务时区配置。 - -## TiDB 相关组件可以配置 HPA 或 VPA 么？ - -TiDB 集群目前还不支持 HPA（Horizontal Pod Autoscaling，自动水平扩缩容）和 VPA（Vertical Pod Autoscaling，自动垂直扩缩容），因为对于数据库这种有状态应用而言，实现自动扩缩容难度较大，无法仅通过 CPU 和 memory 监控数据来简单地实现。 - -## 使用 TiDB Operator 编排 TiDB 集群时，有什么场景需要人工介入操作吗？ - -如果不考虑 Kubernetes 集群本身的运维，TiDB Operator 存在以下可能需要人工介入的场景： - -* TiKV 自动故障转移之后的集群调整，参考[自动故障转移](/v3.1/tidb-in-kubernetes/maintain/auto-failover.md)； -* 维护或下线指定的 Kubernetes 节点，参考[维护节点](/v3.1/tidb-in-kubernetes/maintain/kubernetes-node.md)。 - -## 在公有云上使用 TiDB Operator 编排 TiDB 集群时，推荐的部署拓扑是怎样的？ - -首先，为了实现高可用和数据安全，我们在推荐生产环境下的 TiDB 集群中至少部署在三个可用区 (Available Zone)。 - -当考虑 TiDB 集群与业务服务的部署拓扑关系时，TiDB Operator 支持下面几种部署形态。它们有各自的优势与劣势，具体选型需要根据实际业务需求进行权衡： - -* 将 TiDB 集群与业务服务部署在同一个 VPC 中的同一个 Kubernetes 集群上； -* 将 TiDB 集群与业务服务部署在同一个 VPC 中的不同 Kubernetes 集群上； -* 将 TiDB 集群与业务服务部署在不同 VPC 中的不同 Kubernetes 集群上。 - -## TiDB Operator 支持 TiSpark 吗？ - -TiDB Operator 尚不支持自动编排 TiSpark。 - -假如要为 TiDB in Kubernetes 添加 TiSpark 组件，你需要在**同一个** Kubernetes 集群中自行维护 Spark，确保 Spark 能够访问到 PD 和 TiKV 实例的 IP 与端口，并为 Spark 安装 TiSpark 插件，TiSpark 插件的安装方式可以参考 [TiSpark](/v3.1/reference/tispark.md#已有-Spark-集群的部署方式)。 - -在 Kubernetes 上维护 Spark 可以参考 Spark 的官方文档：[Spark on Kubernetes](http://spark.apache.org/docs/latest/running-on-kubernetes.html)。 - -## 如何查看 TiDB 集群配置？ - -如果需要查看当前集群的 PD、TiKV、TiDB 组件的配置信息，可以执行下列命令: - -* 查看 PD 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -n -- cat /etc/pd/pd.toml - ``` - -* 查看 TiKV 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -n -- cat /etc/tikv/tikv.toml - ``` - -* 查看 TiDB 配置文件 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -it -c tidb -n -- cat /etc/tidb/tidb.toml - ``` - -## 部署 TiDB 集群时调度失败是什么原因？ - -TiDB Operator 调度 Pod 失败的原因可能有三种情况： - -* 资源不足，导致 Pod 一直阻塞在 `Pending` 状态。详细说明参见[集群故障诊断](/v3.1/tidb-in-kubernetes/troubleshoot.md)。 - -* 部分 Node 被打了 `taint`，导致 Pod 无法调度到对应的 Node 上。详请参考 [taint & toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)。 - -* 调度错误，导致 Pod 一直阻塞在 `ContainerCreating` 状态。这种情况发生时请检查 Kubernetes 集群中是否部署过多个 TiDB Operator。重复的 TiDB Operator 自定义调度器的存在，会导致同一个 Pod 的调度周期不同阶段会分别被不同的调度器处理，从而产生冲突。 - - 执行以下命令，如果有两条及以上记录，就说明 Kubernetes 集群中存在重复的 TiDB Operator，请根据实际情况删除多余的 TiDB Operator。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get deployment --all-namespaces |grep tidb-scheduler - ``` diff --git a/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md b/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md deleted file mode 100644 index eb0230bd234f..000000000000 --- a/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -title: 在 GCP 上通过 Kubernetes 部署 TiDB 集群 -summary: 在 GCP 上通过 Kubernetes 部署 TiDB 集群教程 -category: how-to ---- - -# 在 GCP 上通过 Kubernetes 部署 TiDB 集群 - -本文介绍如何使用 [TiDB Operator](https://github.com/pingcap/tidb-operator) 在 GCP 上部署 TiDB 集群。本教程需要在 [Google Cloud Shell](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/pingcap/tidb-operator&tutorial=docs/google-kubernetes-tutorial.md) 上运行。 - -所包含的步骤如下： - -- 启动一个包含 3 个节点的 Kubernetes 集群（可选） -- 安装 Kubernetes 包管理工具 Helm -- 部署 TiDB Operator -- 部署 TiDB 集群 -- 访问 TiDB 集群 -- 扩容 TiDB 集群 -- 删除 Kubernetes 集群（可选） - -> **警告：** -> -> 对于生产环境，不要使用此方式进行部署。 - -## 选择一个项目 - -本教程会启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。价格信息可以参考 [All pricing](https://cloud.google.com/compute/pricing)。 - -继续之前请选择一个项目： - - - - -## 启用 API - -本教程需要使用计算和容器 API。继续之前请启用： - - - - -## 配置 gcloud - -这一步配置 glcoud 默认访问你要用的项目和[可用区](https://cloud.google.com/compute/docs/regions-zones/)，可以简化后面用到的命令： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud config set project {{project-id}} && \ -gcloud config set compute/zone us-west1-a -``` - -## 启动 3 个节点的 Kubernetes 集群 - -下面命令启动一个包含 3 个 `n1-standard-1` 类型节点的 Kubernetes 集群。 - -命令执行需要几分钟时间： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud container clusters create tidb -``` - -集群启动完成后，将其设置为默认集群： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud config set container/cluster tidb -``` - -最后验证 `kubectl` 可以访问集群并且 3 个节点正常运行： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get nodes -``` - -如果所有节点状态为 `Ready`，恭喜你，你已经成功搭建你的第一个 Kubernetes 集群。 - -## 安装 Helm - -Helm 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 - -安装 `helm`： - -{{< copyable "shell-regular" >}} - -``` shell -curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash -``` - -复制 `helm` 到你的 `$HOME` 目录下，这样即使 Google Cloud Shell 超时断开连接，再次登录后仍然可以访问 Helm： - -{{< copyable "shell-regular" >}} - -``` shell -mkdir -p ~/bin && \ -cp /usr/local/bin/helm ~/bin && \ -echo 'PATH="$PATH:$HOME/bin"' >> ~/.bashrc -``` - -Helm 正常工作需要一定的权限： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl apply -f ./manifests/tiller-rbac.yaml && \ -helm init --service-account tiller --upgrade -``` - -`tiller` 是 Helm 的服务端组件，初始化完成需要几分钟时间： - -{{< copyable "shell-regular" >}} - -``` shell -watch "kubectl get pods --namespace kube-system | grep tiller" -``` - -当 Pod 状态为 `Running`，Ctrl+C 停止并继续下一步。 - -## 添加 Helm 仓库 - -PingCAP Helm 仓库中存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。使用下面命令添加仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo add pingcap https://charts.pingcap.org/ && \ -helm repo list -``` - -然后你可以查看可用的 chart： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo update && \ -helm search tidb-cluster -l && \ -helm search tidb-operator -l -``` - -## 部署 TiDB 集群 - -> **注意：** -> -> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 - -第一个要安装的 TiDB 组件是 TiDB Operator，TiDB Operator 是管理组件，结合 Kubernetes 启动 TiDB 集群并保证集群正常运行。执行下面命令之前请确保在 `tidb-operator` 目录下： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl apply -f ./manifests/crd.yaml && \ -kubectl apply -f ./manifests/gke/persistent-disk.yaml && \ -helm install pingcap/tidb-operator -n tidb-admin --namespace=tidb-admin --version= -``` - -可以通过下面命令观察 Operator 启动情况： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb-admin -o wide --watch -``` - -如果 tidb-scheduler 和 tidb-controller-manager 状态都为 `Running`，Ctrl+C 停止并继续下一步部署一个 TiDB 集群！ - -## 部署你的第一个 TiDB 集群 - -我们可以一键部署一个 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster -n demo --namespace=tidb --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd --version= -``` - -集群启动需要几分钟时间，可以通过下面命令观察状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb -o wide --watch -``` - -TiDB 集群包含 2 个 TiDB pod，3 个 TiKV pod 和 3 个 PD pod。如果所有 pod 状态都为 `Running`，Ctrl+C 停止并继续！ - -## 访问 TiDB 集群 - -从 pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get svc -n tidb --watch -``` - -如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 - -要访问 Kubernetes 集群中的 TiDB 服务，可以在 TiDB 服务和 Google Cloud Shell 之间建立一条隧道。建议这种方式只用于调试，因为如果 Google Cloud Shell 重启，隧道不会自动重新建立。要建立隧道： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n tidb port-forward svc/demo-tidb 4000:4000 &>/tmp/port-forward.log & -``` - -在 Cloud Shell 上运行： - -{{< copyable "shell-regular" >}} - -``` shell -sudo apt-get install -y mysql-client && \ -mysql -h 127.0.0.1 -u root -P 4000 -``` - -在 MySQL 终端中输入一条 MySQL 命令： - -{{< copyable "sql" >}} - -``` sql -select tidb_version(); -``` - -如果用 Helm 安装的过程中没有指定密码，现在可以设置： - -{{< copyable "sql" >}} - -``` sql -SET PASSWORD FOR 'root'@'%' = ''; -``` - -> **注意：** -> -> 这条命令中包含一些特殊字符，Google Cloud Shell 无法自动填充，你需要手动复制、粘贴到控制台中。 - -恭喜，你已经启动并运行一个兼容 MySQL 的分布式 TiDB 数据库！ - -## 扩容 TiDB 集群 - -我们可以一键扩容 TiDB 集群。如下命令可以扩容 TiKV： - -{{< copyable "shell-regular" >}} - -``` shell -helm upgrade demo pingcap/tidb-cluster --set pd.storageClassName=pd-ssd,tikv.storageClassName=pd-ssd,tikv.replicas=5 --version= -``` - -TiKV 的 Pod 数量从 3 增加到了 5。可以通过下面命令查看： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get po -n tidb -``` - -## 访问 Grafana 面板 - -要访问 Grafana 面板，可以在 Grafana 服务和 shell 之间建立一条隧道，可以使用如下命令： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n tidb port-forward svc/demo-grafana 3000:3000 &>/dev/null & -``` - -在 Cloud Shell 中，点击 Web Preview 按钮并输入端口 3000，将打开一个新的浏览器标签页访问 Grafana 面板。或者也可以在新浏览器标签或者窗口中直接访问 URL：。 - -如果没有使用 Cloud Shell，可以在浏览器中访问 `localhost:3000`。 - -## 销毁 TiDB 集群 - -如果不再需要这个 TiDB 集群，可以使用下面命令删除集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm delete demo --purge -``` - -上面的命令只会删除运行的 Pod，但是数据还会保留。如果你不再需要那些数据，可以执行下面的命令清除数据和动态创建的持久化磁盘： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl delete pvc -n tidb -l app.kubernetes.io/instance=demo,app.kubernetes.io/managed-by=tidb-operator && \ -kubectl get pv -l app.kubernetes.io/namespace=tidb,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` - -## 删除 Kubernetes 集群 - -实验结束后，可以使用如下命令删除 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -gcloud container clusters delete tidb -``` - -## 更多信息 - -我们还提供简单的[基于 Terraform 的部署方案](/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md)。 diff --git a/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md b/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md deleted file mode 100644 index 8619907636ee..000000000000 --- a/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: 使用 kind 在 Kubernetes 上部署 TiDB 集群 -summary: 使用 kind 在 Kubernetes 上部署 TiDB 集群。 -category: how-to -aliases: ['/docs-cn/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-dind/'] ---- - -# 使用 kind 在 Kubernetes 上部署 TiDB 集群 - -本文介绍了如何在个人电脑（Linux 或 MacOS）上采用 [kind](https://kind.sigs.k8s.io/) 方式在 Kubernetes 上部署 [TiDB Operator](https://github.com/pingcap/tidb-operator) 和 TiDB 集群。 - -kind 通过使用 Docker 容器作为集群节点模拟出一个本地的 Kubernetes 集群。kind 的设计初衷是为了在本地进行 Kubernetes 集群的一致性测试。Kubernetes 集群版本取决于 kind 使用的镜像，你可以指定任一镜像版本用于集群节点，并在 [Docker hub](https://hub.docker.com/r/kindest/node/tags) 中找到想要部署的 Kubernetes 版本。 - -> **警告：** -> -> 对于生产环境，不要使用此方式进行部署。 - -## 环境准备 - -部署前，请确认软件、资源等满足如下需求： - -- 资源需求：CPU 2 核+、内存 4G+ - - > **注意：** - > - > 对于 macOS 系统，需要给 Docker 分配 2 核+ CPU 和 4G+ 内存。详情请参考 [Mac 上配置 Docker](https://docs.docker.com/docker-for-mac/#advanced)。 - -- [Docker](https://docs.docker.com/install/)：版本 >= 17.03 -- [Helm Client](https://helm.sh/docs/intro/install/)：版本 >= 2.9.0 并且 < 3.0.0 -- [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)：版本 >= 1.10，建议 1.13 或更高版本 - - > **注意：** - > - > 不同 kubectl 版本，输出可能略有不同。 - -- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/)：版本 >= 0.4.0 -- [net.ipv4.ip_forward](https://linuxconfig.org/how-to-turn-on-off-ip-forwarding-in-linux) 需要被设置为 `1` - -## 第 1 步：通过 kind 部署 Kubernetes 集群 - -首先确认 Docker 进程正常运行，然后你可以通过脚本命令快速启动一个本地的 Kubernetes 集群。 - -1. Clone 官方提供的代码： - - {{< copyable "shell-regular" >}} - - ``` shell - git clone --depth=1 https://github.com/pingcap/tidb-operator && \ - cd tidb-operator - ``` - -2. 运行脚本，在本地创建一个 Kubernetes 集群： - - {{< copyable "shell-regular" >}} - - ``` shell - hack/kind-cluster-build.sh - ``` - - > **注意：** - > - > 通过该脚本启动的 Kubernetes 集群默认有 6 个节点，Kubernetes 版本默认为 v1.12.8，每个节点默认挂载数为 9。你可以通过启动参数去修改这些参数： - > - > {{< copyable "shell-regular" >}} - > - > ```shell - > hack/kind-cluster-build.sh --nodeNum 2 --k8sVersion v1.14.6 --volumeNum 3 - > ``` - -3. 集群创建完毕后，执行下列命令将 kubectl 的默认配置文件切换到 `kube-config`，从而连接到该本地 Kubernetes 集群： - - {{< copyable "shell-regular" >}} - - ```shell - export KUBECONFIG="$(kind get kubeconfig-path)" - ``` - -4. 查看该 kubernetes 集群信息： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl cluster-info - ``` - - 输出如下类似信息： - - ``` shell - Kubernetes master is running at https://127.0.0.1:50295 - KubeDNS is running at https://127.0.0.1:50295/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy - ``` - -5. 查看该 Kubernetes 集群的 `storageClass`： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl get storageClass - ``` - - 输出如下类似信息： - - ``` shell - NAME PROVISIONER AGE - local-storage kubernetes.io/no-provisioner 7m50s - standard (default) kubernetes.io/host-path 8m29s - ``` - -## 第 2 步：在 Kubernetes 集群上部署 TiDB Operator - -1. 安装 Helm 并配置 PingCAP 官方 chart 仓库，参考 [使用 Helm](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 小节中的操作。 - -2. 部署 TiDB Operator，参考 [安装 TiDB Operator](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md#安装-tidb-operator) 小节中的操作。 - -## 第 3 步：在 Kubernetes 集群中部署 TiDB 集群 - -参考[在标准 Kubernetes 上部署 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md#部署-tidb-集群)中的操作。 - -## 访问数据库和监控面板 - -通过 `kubectl port-forward` 暴露服务到主机，可以访问 TiDB 集群。命令中的端口格式为：`<主机端口>:`。 - -- 通过 MySQL 客户端访问 TiDB - - 在访问 TiDB 集群之前，请确保已安装 MySQL client。 - - 1. 使用 kubectl 暴露 TiDB 服务端口： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/-tidb 4000:4000 --namespace= - ``` - - > **注意：** - > - > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:4000 -> 4000`。测试完成后按 `Ctrl + C` 停止代理并退出。 - - 2. 然后，通过 MySQL 客户端访问 TiDB，打开一个**新**终端标签或窗口，执行下面的命令： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -u root - ``` - -- 查看监控面板 - - 1. 使用 kubectl 暴露 Grafana 服务端口： - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/-grafana 3000:3000 --namespace= - ``` - - > **注意：** - > - > 如果代理建立成功，会打印类似输出：`Forwarding from 0.0.0.0:3000 -> 3000`。测试完成后按 `Ctrl + C` 停止代理并退出。 - - 2. 然后，在浏览器中打开 访问 Grafana 监控面板： - - - 默认用户名：admin - - 默认密码：admin - - > **注意：** - > - > 如果你不是在本地 PC 而是在远程主机上部署的 kind 环境，可能无法通过 localhost 访问远程主机的服务。 - > - > 如果使用 kubectl 1.13 或者更高版本，可以在执行 `kubectl port-forward` 命令时添加 `--address 0.0.0.0` 选项，在 `0.0.0.0` 暴露端口而不是默认的 `127.0.0.1`： - > - > {{< copyable "shell-regular" >}} - > - > ``` - > kubectl port-forward --address 0.0.0.0 -n tidb svc/-grafana 3000:3000 - > ``` - > - > 然后，在浏览器中打开 `http://<远程主机 IP>:3000` 访问 Grafana 监控面板。 - -## 删除 TiDB 集群 与 Kubernetes 集群 - -删除本地 TiDB 集群可参考[销毁 TiDB 集群](/v3.1/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md#销毁-kubernetes-上的-tidb-集群)。 - -通过下面命令删除该 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -kind delete cluster -``` diff --git a/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md b/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md deleted file mode 100644 index 7174e088e603..000000000000 --- a/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -title: 在 Minikube 集群上部署 TiDB 集群 -summary: 在 Minikube 集群上部署 TiDB 集群 -category: how-to ---- - -# 在 Minikube 集群上部署 TiDB 集群 - -[Minikube](https://kubernetes.io/docs/setup/minikube/) 可以让你在个人电脑上的虚拟机中创建一个 Kubernetes 集群，支持 macOS、Linux 和 Windows 系统。本文介绍如何在 Minikube 集群上部署 TiDB 集群。 - -> **警告：** -> -> - 对于生产环境，不要使用此方式进行部署。 -> -> - 尽管 Minikube 支持通过 `--vm-driver=none` 选项使用主机 Docker 而不使用虚拟机，但是目前尚没有针对 TiDB Operator 做过全面的测试，可能会无法正常工作。如果你想在不支持虚拟化的系统（例如，VPS）上试用 TiDB Operator，可以考虑使用 [kind](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)。 - -## 安装 Minikube 并启动 Kubernetes 集群 - -参考[安装 Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/)，在你的机器上安装 Minikube 1.0.0+。 - -安装完 Minikube 后，可以执行下面命令启动一个 Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -minikube start -``` - -对于中国大陆用户，可以使用国内 gcr.io mirror 仓库，例如 `registry.cn-hangzhou.aliyuncs.com/google_containers`。 - -{{< copyable "shell-regular" >}} - -``` shell -minikube start --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers -``` - -或者给 Docker 配置 HTTP/HTTPS 代理。 - -将下面命令中的 `127.0.0.1:1086` 替换为你自己的 HTTP/HTTPS 代理地址： - -{{< copyable "shell-regular" >}} - -``` shell -minikube start --docker-env https_proxy=http://127.0.0.1:1086 \ - --docker-env http_proxy=http://127.0.0.1:1086 -``` - -> **注意：** -> -> 由于 Minikube 通过虚拟机（默认）运行，`127.0.0.1` 是虚拟机本身，有些情况下你可能想要使用你的主机的实际 IP。 - -参考 [Minikube setup](https://kubernetes.io/docs/setup/minikube/) 查看配置虚拟机和 Kubernetes 集群的更多选项。 - -## 安装 kubectl 并访问集群 - -Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/user-guide/kubectl/)，可以让你执行命令访问 Kubernetes 集群。 - -参考 [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) 安装和配置 kubectl。 - -kubectl 安装完成后，测试 Minikube Kubernetes 集群： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl cluster-info -``` - -## 安装 TiDB Operator 并运行 TiDB 集群 - -### 安装 Helm - -[Helm](https://helm.sh/) 是 Kubernetes 包管理工具，通过 Helm 可以一键安装 TiDB 的所有分布式组件。安装 Helm 需要同时安装服务端和客户端组件。 - -{{< copyable "shell-regular" >}} - -``` shell -curl https://raw.githubusercontent.com/helm/helm/master/scripts/get | bash -``` - -安装 helm tiller： - -{{< copyable "shell-regular" >}} - -``` shell -helm init -``` - -如果无法访问 gcr.io，你可以尝试 mirror 仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm init --upgrade --tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:$(helm version --client --short | grep -Eo 'v[0-9]\.[0-9]+\.[0-9]+') -``` - -安装完成后，执行 `helm version` 会同时显示客户端和服务端组件版本： - -{{< copyable "shell-regular" >}} - -``` shell -helm version -``` - -输出类似如下内容： - -``` -Client: &version.Version{SemVer:"v2.13.1", -GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} -Server: &version.Version{SemVer:"v2.13.1", -GitCommit:"618447cbf203d147601b4b9bd7f8c37a5d39fbb4", GitTreeState:"clean"} -``` - -如果只显示客户端版本，表示 `helm` 无法连接到服务端。通过 `kubectl` 查看 tiller pod 是否在运行： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl -n kube-system get pods -l app=helm -``` - -### 添加 Helm 仓库 - -Helm 仓库 (`https://charts.pingcap.org/`) 存放着 PingCAP 发布的 charts，例如 tidb-operator、tidb-cluster 和 tidb-backup 等等。可使用以下命令添加仓库： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo add pingcap https://charts.pingcap.org/ && \ -helm repo list -``` - -然后可以查看可用的 chart： - -{{< copyable "shell-regular" >}} - -``` shell -helm repo update && \ -helm search tidb-cluster -l && \ -helm search tidb-operator -l -``` - -### 在 Kubernetes 集群上安装 TiDB Operator - -> **注意：** -> -> `` 在后面文档中代表 chart 版本，例如 `v1.0.0`。 - -克隆 tidb-operator 代码库并安装 TiDB Operator： - -{{< copyable "shell-regular" >}} - -``` shell -git clone --depth=1 https://github.com/pingcap/tidb-operator && \ -cd tidb-operator && \ -kubectl apply -f ./manifests/crd.yaml && \ -helm install pingcap/tidb-operator --name tidb-operator --namespace tidb-admin --version= -``` - -然后，可以通过如下命令查看 TiDB Operator 的启动情况： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace tidb-admin -o wide --watch -``` - -如果无法访问 gcr.io（Pod 由于 ErrImagePull 无法启动），可以尝试从 mirror 仓库中拉取 kube-scheduler 镜像。可以通过以下命令升级 tidb-operator： - -{{< copyable "shell-regular" >}} - -``` shell -helm upgrade tidb-operator pingcap/tidb-operator --namespace tidb-admin --set \ - scheduler.kubeSchedulerImageName=registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler --version= -``` - -如果 tidb-scheduler 和 tidb-controller-manager 都进入 running 状态，你可以继续下一步启动一个 TiDB 集群。 - -### 启动 TiDB 集群 - -通过下面命令启动 TiDB 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm install pingcap/tidb-cluster --name demo --set \ - schedulerName=default-scheduler,pd.storageClassName=standard,tikv.storageClassName=standard,pd.replicas=1,tikv.replicas=1,tidb.replicas=1 --version= -``` - -可以通过下面命令观察集群的状态： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pods --namespace default -l app.kubernetes.io/instance=demo -o wide --watch -``` - -通过 Ctrl+C 停止观察。 - -## 测试 TiDB 集群 - -测试 TiDB 集群之前，请确保已经安装 MySQL 客户端。从 Pod 启动、运行到服务可以访问有一些延时，可以通过下面命令查看服务： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get svc --watch -``` - -如果看到 `demo-tidb` 出现，说明服务已经可以访问，可以 Ctrl+C 停止。 - -按照以下步骤访问 TiDB 集群： - -1. 转发本地端口到 TiDB 端口。 - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/demo-tidb 4000:4000 - ``` - -2. 在另一个终端窗口中，通过 MySQL 客户端访问 TiDB： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -uroot - ``` - - 或者可以直接执行 SQL 命令： - - {{< copyable "shell-regular" >}} - - ``` shell - mysql -h 127.0.0.1 -P 4000 -uroot -e 'select tidb_version();' - ``` - -## 监控 TiDB 集群 - -按照以下步骤监控 TiDB 集群状态： - -1. 转发本地端口到 Grafana 端口。 - - {{< copyable "shell-regular" >}} - - ``` shell - kubectl port-forward svc/demo-grafana 3000:3000 - ``` - -2. 打开浏览器，通过 `http://localhost:3000` 访问 Grafana。 - - 或者，Minikube 提供了 `minikube service` 的方式暴露 Grafana 服务，可以更方便的接入。 - - {{< copyable "shell-regular" >}} - - ``` shell - minikube service demo-grafana - ``` - - 上述命令会自动搭建代理并在浏览器中打开 Grafana。 - -### 删除 TiDB 集群 - -通过下面命令删除 demo 集群： - -{{< copyable "shell-regular" >}} - -``` shell -helm delete --purge demo -``` - -更新 demo 集群使用的 PV 的 reclaim 策略为 Delete： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl get pv -l app.kubernetes.io/instance=demo -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` - -删除 PVC： - -{{< copyable "shell-regular" >}} - -``` shell -kubectl delete pvc -l app.kubernetes.io/managed-by=tidb-operator -``` - -## FAQ - -### Minikube 上的 TiDB 集群不响应或者响应非常慢 - -Minikube 虚拟机默认配置为 2048 MB 内存和 2 个 CPU。可以在 `minikube start` 时通过`--memory` 和 `--cpus` 选项为其分配更多资源。注意，为了使配置修改生效，你需要重新创建 Minikube 虚拟机。 - -{{< copyable "shell-regular" >}} - -``` shell -minikube delete && \ -minikube start --cpus 4 --memory 4096 ... -``` diff --git a/v3.1/tidb-in-kubernetes/initialize-cluster.md b/v3.1/tidb-in-kubernetes/initialize-cluster.md deleted file mode 100644 index 6533295fc8e9..000000000000 --- a/v3.1/tidb-in-kubernetes/initialize-cluster.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Kubernetes 上的集群初始化配置 -category: how-to ---- - -# Kubernetes 上的集群初始化配置 - -本文介绍如何对 Kubernetes 上的集群进行初始化配置完成初始化账号和密码设置，以及批量自动执行 SQL 语句对数据库进行初始化。 - -> **注意：** -> -> 以下功能只在第一次创建集群时有作用，集群创建之后再设置或修改不会生效。 - -## 设置初始化账号和密码 - -集群创建时默认会创建 `root` 账号，但是密码为空，这会带来一些安全性问题。可以通过如下步骤为 `root` 账号设置初始密码： - -1. 创建 `Namespace` - - 在部署集群前通过下面命令创建 [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create namespace - ``` - -2. 创建 `Secret` - - 在部署集群前通过下面命令创建 [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) 指定 root 账号密码： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic tidb-secret --from-literal=root= --namespace= - ``` - - 如果希望能自动创建其它用户，可以在上面命令里面再加上其他用户的 username 和 password，例如： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic tidb-secret --from-literal=root= --from-literal=developer= --namespace= - ``` - - 该命令会创建 `root` 和 `developer` 两个用户的密码，存到 `tidb-secret` 的 Secret 里面。并且创建的普通用户 `developer` 默认只有 `USAGE` 权限，其他权限请在 `tidb.initSql` 中设置。 - -3. 设置允许访问 TiDB 的主机 - - 在部署集群前可以通过 `tidb.permitHost` 配置项来设置允许访问 TiDB 的主机 **host_name**。如果不设置，则允许所有主机访问。详情请参考 [Mysql GRANT host name](https://dev.mysql.com/doc/refman/5.7/en/grant.html)。 - - ``` - tidb: - passwordSecretName: tidb-secret - permitHost: - ``` - -4. 部署集群 - - 创建 Secret 之后，通过下面命令部署集群： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster -f values.yaml --name= --namespace= --version= - ``` - - 以上命令指定 `tidb.passwordSecretName` 之后，创建的集群会自动创建一个初始化的 Job，该 Job 在集群创建过程中会尝试利用提供的 secret 给 root 账号创建初始密码，并且创建其它账号和密码，如果指定了的话。注意由于 Job 创建时 TiDB 集群的 Pod 还没完全创建，所以可能会失败几次，初始化完成后 Pod 状态会变成 Completed。之后通过 MySQL 客户端登录时需要指定这里设置的密码。 - -## 批量执行初始化 SQL 语句 - -集群在初始化过程还可以自动执行 `tidb.initSql` 中的 SQL 语句用于初始化，该功能可以用于默认给集群创建一些 database 或者 table，并且执行一些用户权限管理类的操作。例如如下设置会在集群创建完成后自动创建名为 `app` 的 database，并且赋予 `developer` 账号对 `app` 的所有管理权限： - -{{< copyable "yaml" >}} - -```yaml -tidb: - passwordSecretName: tidb-secret - initSql: |- - CREATE DATABASE app; - GRANT ALL PRIVILEGES ON app.* TO 'developer'@'%'; -``` - -将上述内容保存到 `values.yaml` 文件，然后执行下面命令部署集群： - -{{< copyable "shell-regular" >}} - -```bash -helm install pingcap/tidb-cluster -f values.yaml --name= --namespace= --version= -``` - -> **注意：** -> -> 目前没有对 initSql 做校验，尽管也可以在 initSql 里面创建账户和设置密码，但这种方式会将密码以明文形式存到 initializer Job 对象上，不建议这么做。 diff --git a/v3.1/tidb-in-kubernetes/maintain/auto-failover.md b/v3.1/tidb-in-kubernetes/maintain/auto-failover.md deleted file mode 100644 index 2b164cb20f91..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/auto-failover.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群故障自动转移 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群故障自动转移 - -故障自动转移是指在 TiDB 集群的某些节点出现故障时，TiDB Operator 会自动添加一个节点，保证 TiDB 集群的高可用，类似于 K8s 的 `Deployment` 行为。 - -由于 TiDB Operator 基于 `StatefulSet` 来管理 Pod，但 `StatefulSet` 在某些 Pod 发生故障时不会自动创建新节点来替换旧节点，所以，TiDB Operator 扩展了 `StatefulSet` 的这种行为，添加了 Auto Failover 功能。 - -Auto Failover 功能在 TiDB Operator 中默认关闭。部署 TiDB Operator 时，可通过设置 `charts/tidb-operator/values.yaml` 文件的 `controllerManager.autoFailover` 为 `true` 开启该功能： - -```yaml -controllerManager: - serviceAccount: tidb-controller-manager - logLevel: 2 - replicas: 1 - resources: - limits: - cpu: 250m - memory: 150Mi - requests: - cpu: 80m - memory: 50Mi - # autoFailover is whether tidb-operator should auto failover when failure occurs - autoFailover: true - # pd failover period default(5m) - pdFailoverPeriod: 5m - # tikv failover period default(5m) - tikvFailoverPeriod: 5m - # tidb failover period default(5m) - tidbFailoverPeriod: 5m -``` - -`pdFailoverPeriod`、`tikvFailoverPeriod` 和 `tidbFailoverPeriod` 默认均为 5 分钟，它们的含义是在确认实例故障后的等待超时时间，超过这个时间后，TiDB Operator 就开始做自动的故障转移。 - -## 实现原理 - -TiDB 集群有 PD、TiKV 和 TiDB 三个组件，它们的故障转移策略有所不同，本节将详细介绍这三种策略。 - -### PD 故障转移策略 - -假设 PD 集群有 3 个节点，如果一个 PD 节点挂掉超过 5 分钟（`pdFailoverPeriod` 可配置），TiDB Operator 首先会将这个 PD 节点下线，然后再添加一个新的 PD 节点。此时会有 4 个 Pod 同时存在，待挂掉的 PD 节点恢复后，TiDB Operator 会将新启动的节点删除掉，恢复成原来的 3 个节点。 - -### TiKV 故障转移策略 - -当一个 TiKV 节点无法正常工作后，该节点的状态会变为 `Disconnected`，30 分钟（通过 `pd.config` 文件中 `[schedule]` 部分的 `max-store-down-time = "30m"` 来配置）后会变成 `Down` 状态，TiDB Operator 会在此基础上再等待 5 分钟（`tikvFailoverPeriod` 可配置），如果该 TiKV 节点仍不能恢复，就会新起一个 TiKV 节点。待挂掉的 TiKV 节点恢复后，TiDB Operator 不会自动删除新起的节点，用户需要手动减少 TiKV 节点，恢复成原来的节点数。操作方法是将该 TiKV 节点从 `TidbCluster` 对象的 `status.tikv.failureStores` 字段中删除： - -{{< copyable "shell-regular" >}} - -```shell -kubectl edit tc -n -``` - -``` -... -status - tikv: - failureStores: - "1": - podName: cluster1-tikv-0 - storeID: "1" - "2": - podName: cluster1-tikv-1 - storeID: "2" -... -``` - -`cluster1-tikv-0` 节点恢复后，将其删除后变为： - -``` -... -status - tikv: - failureStores: - "2": - podName: cluster1-tikv-1 - storeID: "2" -... -``` - -### TiDB 故障转移策略 - -假设 TiDB 集群有 3 个节点，TiDB 的故障转移策略跟 Kubernetes 中的 `Deployment` 的是一致的。如果一个 TiDB 节点挂掉超过 5 分钟（`tidbFailoverPeriod` 可配置），TiDB Operator 会添加一个新的 TiDB 节点。此时会有 4 个 Pod 同时存在，待挂掉的 TiDB 节点恢复后，TiDB Operator 会将新启动的节点删除掉，恢复成原来的 3 个节点。 diff --git a/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md b/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md deleted file mode 100644 index ad9d3128147f..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群备份恢复 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群备份与恢复 - -这篇文档详细描述了如何对 Kubernetes 上的 TiDB 集群进行数据备份和数据恢复。 - -Kubernetes 上的 TiDB 集群支持两种备份策略： - -* [全量备份](#全量备份)（定时执行或 Ad-hoc）：使用 [`mydumper`](/v3.1/reference/tools/mydumper.md) 获取集群的逻辑备份； -* [增量备份](#增量备份)：使用 [`TiDB Binlog`](/v3.1/reference/tidb-binlog/overview.md) 将 TiDB 集群的数据实时复制到其它数据库中或实时获得增量数据备份； - -目前，Kubernetes 上的 TiDB 集群只对 `mydumper` 获取的全量备份数据提供自动化的数据恢复操作。恢复 `TiDB-Binlog` 获取的增量数据需要手动进行。 - -## 全量备份 - -全量备份使用 `mydumper` 来获取 TiDB 集群的逻辑备份数据。全量备份任务会创建一个 PVC ([PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)) 来存储数据。 - -默认配置下，备份任务使用 PV ([Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes)) 来存储备份数据。你也可以通过修改配置将备份数据存储到 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，在这种情况下，数据在上传到对象存储前，会临时存储在 PV 中。参考 [Kubernetes 上的 TiDB 集群备份配置](/v3.1/tidb-in-kubernetes/reference/configuration/backup.md) 了解所有的配置选项。 - -你可以配置一个定时执行的全量备份任务，也可以临时执行一个全量备份任务。 - -### 定时全量备份 - -定时全量备份是一个与 TiDB 集群一同创建的定时任务，它会像 `crontab` 任务那样周期性地运行。 - -你可以修改 TiDB 集群的 `values.yaml` 文件来配置定时全量备份： - -1. 将 `scheduledBackup.create` 设置为 `true`； -2. 将 `scheduledBackup.storageClassName` 设置为用于存储数据的 PV 的 `storageClass`； - - > **注意：** - > - > 你必须将定时全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 - -3. 按照 [Cron](https://en.wikipedia.org/wiki/Cron) 格式设置 `scheduledBackup.schedule` 来定义任务的执行周期与时间； -4. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) 该用户必须拥有数据备份所需的数据库相关权限，同时，将 `scheduledBackup.secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -5. 通过 `helm install` 创建一个配置了定时全量备份的 TiDB 集群，针对现有集群，则使用 `helm upgrade` 为集群打开定时全量备份： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -### Ad-hoc 全量备份 - -Ad-hoc 全量备份封装在 `pingcap/tidb-backup` 这个 Helm chart 中。根据 `values.yaml` 文件中的 `mode` 配置，该 chart 可以执行全量备份或数据恢复。我们会在[数据恢复](#数据恢复)一节中描述如何执行数据恢复。 - -你可以通过下面的步骤执行一次 Ad-hoc 全量备份： - -1. 修改 `values.yaml`： - * 将 `clusterName` 设置为目标 TiDB 集群名字； - * 将 `mode` 设置为 `backup`； - * 将 `storage.className` 设置为用于存储数据的 PV 的 `storageClass`； - * 根据数据量调整 `storage.size`； - - > **注意：** - > - > 你必须将 Ad-hoc 全量备份使用的 PV 的 [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy) 设置为 `Retain` 来确保你的数据安全。 - -2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -3. 使用下面的命令执行一次 Ad-hoc 全量备份： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-backup --name= --namespace= -f values.yaml --version= - ``` - -### 查看备份 - -对于存储在 PV 中的备份，你可以使用下面的命令进行查看： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pvc -n -l app.kubernetes.io/component=backup,pingcap.com/backup-cluster-name= -``` - -假如你将数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你可以用这些存储系统自带的图形界面或命令行工具查看全量备份。 - -## 数据恢复 - - 使用 `pingcap/tidb-backup` 这个 Helm chart 进行数据恢复，步骤如下： - -1. 修改 `values.yaml`： - * 将 `clusterName` 设置为目标 TiDB 集群名； - * 将 `mode` 设置为 `restore`； - * 将 `name` 设置为用于恢复的备份名字（你可以参考[查看备份](#查看备份)来寻找可用的备份数据）。假如备份数据存储在 [Google Cloud Storage](https://cloud.google.com/storage/)，[Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/) 或 [Amazon S3](https://aws.amazon.com/s3/) 中，你必须保证这些存储的相关配置与执行[全量备份](#全量备份)时一致。 -2. 创建一个包含数据库用户名和密码的 Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)，该用户必须拥有数据备份所需的数据库相关权限，同时，将 `values.yaml` 中的 `secretName` 设置为该 `Secret` 的名字（默认为 `backup-secret`，假如你在[全量备份](#全量备份)时已经创建了该 Secret，则可以跳过这步）： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user= --from-literal=password= - ``` - -3. 恢复数据： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-backup --namespace= --name= -f values.yaml --version= - ``` - -## 增量备份 - -增量备份使用 [TiDB Binlog](/v3.1/reference/tidb-binlog/overview.md) 工具从 TiDB 集群收集 Binlog，并提供实时备份和向其它数据库的实时同步能力。 - -有关 Kubernetes 上运维 TiDB Binlog 的详细指南，可参阅 [TiDB Binlog](/v3.1/tidb-in-kubernetes/maintain/tidb-binlog.md)。 - -### Pump 缩容 - -缩容 Pump 需要先将单个 Pump 节点从集群中下线，然后运行 `helm upgrade` 命令将对应的 Pump Pod 删除，并对每个节点重复上述步骤。 - -1. 下线 Pump 节点： - - 假设现在有 3 个 Pump 节点，我们需要下线第 3 个 Pump 节点，将 `` 替换成 `2`，操作方式如下（`` 为当前 TiDB 的版本）。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl run offline-pump- --image=pingcap/tidb-binlog: --namespace= --restart=OnFailure -- /binlogctl -pd-urls=http://-pd:2379 -cmd offline-pump -node-id -pump-:8250 - ``` - - 然后查看 Pump 的日志输出，输出 `pump offline, please delete my pod` 后即可确认该节点已经成功下线。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl logs -f -n -pump- - ``` - -2. 删除对应的 Pump Pod： - - 修改 `values.yaml` 文件中 `binlog.pump.replicas` 为 `2`，然后执行如下命令来删除 Pump Pod： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` diff --git a/v3.1/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md b/v3.1/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md deleted file mode 100644 index 15fb7c2f9c93..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 销毁 Kubernetes 上的 TiDB 集群 -category: how-to ---- - -# 销毁 Kubernetes 上的 TiDB 集群 - -本文描述了如何销毁 Kubernetes 集群上的 TiDB 集群 - -要销毁 TiDB 集群，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -helm delete --purge -``` - -上述命令只是删除运行的 Pod，数据仍然会保留。如果你不再需要那些数据，可以通过下面命令清除数据： - -> **警告：** -> -> 下列命令会彻底删除数据，务必考虑清楚再执行。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pvc -n -l app.kubernetes.io/instance=,app.kubernetes.io/managed-by=tidb-operator -``` - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pv -l app.kubernetes.io/namespace=,app.kubernetes.io/managed-by=tidb-operator,app.kubernetes.io/instance= -o name | xargs -I {} kubectl patch {} -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' -``` diff --git a/v3.1/tidb-in-kubernetes/maintain/kubernetes-node.md b/v3.1/tidb-in-kubernetes/maintain/kubernetes-node.md deleted file mode 100644 index a0e9c6dab914..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/kubernetes-node.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: 维护 TiDB 集群所在的 Kubernetes 节点 -category: how-to ---- - -# 维护 TiDB 集群所在的 Kubernetes 节点 - -TiDB 是高可用数据库，可以在部分数据库节点下线的情况下正常运行，因此，我们可以安全地对底层 Kubernetes 节点进行停机维护。在具体操作时，针对 PD、TiKV 和 TiDB 实例的不同特性，我们需要采取不同的操作策略。 - -本文档将详细介绍如何对 Kubernetes 节点进行临时或长期的维护操作。 - -环境准备： - -- [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [`tkctl`](/v3.1/tidb-in-kubernetes/reference/tools/tkctl.md) -- [`jq`](https://stedolan.github.io/jq/download/) - -> **注意：** -> -> 长期维护节点前，需要保证 Kubernetes 集群的剩余资源足够运行 TiDB 集群。 - -## 维护 PD 和 TiDB 实例所在节点 - -PD 和 TiDB 实例的迁移较快，可以采取主动驱逐实例到其它节点上的策略进行节点维护： - -1. 检查待维护节点上是否有 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pod --all-namespaces -o wide | grep - ``` - - 假如存在 TiKV 实例，请参考[维护 TiKV 实例所在节点](#维护-tikv-实例所在节点)。 - -2. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl cordon - ``` - -3. 使用 `kubectl drain` 命令将待维护节点上的数据库实例迁移到其它节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl drain --ignore-daemonsets --delete-local-data - ``` - - 运行后，该节点上的 TiDB 实例会自动迁移到其它可用节点上，PD 实例则会在 5 分钟后触发自动故障转移补齐节点。 - -4. 此时，假如希望下线该 Kubernetes 节点，则可以将该节点删除： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete node - ``` - - 假如希望恢复 Kubernetes 节点，则需要在恢复节点后确认其健康状态： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl get node - ``` - - 观察到节点进入 `Ready` 状态后，继续操作。 - -5. 使用 `kubectl uncordon` 命令解除节点的调度限制： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl uncordon - ``` - -6. 观察 Pod 是否全部恢复正常运行： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl get -n $namespace pod -o wide - ``` - - 或者： - - {{< copyable "shell-regular" >}} - - ```sql - watch tkctl get all - ``` - - Pod 恢复正常运行后，操作结束。 - -## 维护 TiKV 实例所在节点 - -TiKV 实例迁移较慢，并且会对集群造成一定的数据迁移负载，因此在维护 TiKV 实例所在节点前，需要根据维护需求选择操作策略： - -- 假如是维护短期内可恢复的节点，则不需要迁移 TiKV 节点，在维护结束后原地恢复节点； -- 假如是维护短期内不可恢复的节点，则需要规划 TiKV 的迁移工作。 - -### 维护短期内可恢复的节点 - -针对短期维护，我们可以通过调整 PD 集群的 `max-store-down-time` 配置来增大集群所允许的 TiKV 实例下线时间，在此时间内维护完毕并恢复 Kubernetes 节点后，所有该节点上的 TiKV 实例会自动恢复。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward svc/-pd 2379:2379 -``` - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -d config set max-store-down-time 10m -``` - -调整 `max-store-down-time` 到合理的值后，后续的操作方式与[维护 PD 和 TiDB 实例所在节点](#维护-pd-和-tidb-实例所在节点)相同。 - -### 维护短期内不可恢复的节点 - -针对短期内不可恢复的节点维护，如节点长期下线等情形，需要使用 `pd-ctl` 主动通知 TiDB 集群下线对应的 TiKV 实例，再手动解除 TiKV 实例与该节点的绑定。 - -1. 使用 `kubectl cordon` 命令防止新的 Pod 调度到待维护节点上： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl cordon - ``` - -2. 查看待维护节点上的 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - tkctl get -A tikv | grep - ``` - -3. 使用 `pd-ctl` 主动下线 TiKV 实例。 - - > **注意：** - > - > 下线 TiKV 实例前，需要保证集群中剩余的 TiKV 实例数不少于 PD 配置中的 TiKV 数据副本数（配置项：`max-replicas`）。假如不符合该条件，需要先操作扩容 TiKV。 - - 查看 TiKV 实例的 `store-id`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get tc -ojson | jq '.status.tikv.stores | .[] | select ( .podName == "" ) | .id' - ``` - - 下线实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward svc/-pd 2379:2379 - ``` - - {{< copyable "shell-regular" >}} - - ```shell - pd-ctl -d store delete - ``` - -4. 等待 store 状态（`state_name`）转移为 `Tombstone`： - - {{< copyable "shell-regular" >}} - - ```shell - watch pd-ctl -d store - ``` - -5. 解除 TiKV 实例与节点本地盘的绑定。 - - 查询 Pod 使用的 `PesistentVolumeClaim`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n pod -ojson | jq '.spec.volumes | .[] | select (.name == "tikv") | .persistentVolumeClaim.claimName' - ``` - - 删除该 `PesistentVolumeClaim`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pvc - ``` - -6. 删除 TiKV 实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pod - ``` - -7. 观察该 TiKV 实例是否正常调度到其它节点上： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 假如待维护节点上还有其它 TiKV 实例，则重复同样的操作步骤直到所有的 TiKV 实例都迁移到其它节点上。 - -8. 确认节点不再有 TiKV 实例后，再逐出节点上的其它实例： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl drain --ignore-daemonsets --delete-local-data - ``` - -9. 再次确认节点不再有任何 TiKV、TiDB 和 PD 实例运行： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pod --all-namespaces | grep - ``` - -10. 最后（可选），假如是长期下线节点，建议将节点从 Kubernetes 集群中删除： - - {{< copyable "shell-regular" >}} - - ```shell - kuebctl delete node - ``` - -至此，操作完成。 diff --git a/v3.1/tidb-in-kubernetes/maintain/lightning.md b/v3.1/tidb-in-kubernetes/maintain/lightning.md deleted file mode 100644 index d25508ba6664..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/lightning.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 恢复 Kubernetes 上的 TiDB 集群数据 -summary: 使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据。 -category: how-to ---- - -# 恢复 Kubernetes 上的 TiDB 集群数据 - -本文介绍了如何使用 [TiDB Lightning](https://github.com/pingcap/tidb-lightning) 快速恢复 Kubernetes 上的 TiDB 集群数据。 - -TiDB Lightning 包含两个组件：tidb-lightning 和 tikv-importer。在 Kubernetes 上，tikv-importer 位于 TiDB 集群的 Helm chart 内，被部署为一个副本数为 1 (`replicas=1`) 的 `StatefulSet`；tidb-lightning 位于单独的 Helm chart 内，被部署为一个 `Job`。 - -为了使用 TiDB Lightning 恢复数据，tikv-importer 和 tidb-lightning 都必须分别部署。 - -## 部署 tikv-importer - -tikv-importer 可以在一个现有的 TiDB 集群上启用，或者在新建 TiDB 集群时启用。 - -* 在新建一个 TiDB 集群时启用 tikv-importer： - - 1. 在 `tidb-cluster` 的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 - - 2. 部署该集群。 - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster --name= --namespace= -f values.yaml --version= - ``` - -* 配置一个现有的 TiDB 集群以启用 tikv-importer： - - 1. 在该 TiDB 集群的 `values.yaml` 文件中将 `importer.create` 设置为 `true`。 - - 2. 升级该 TiDB 集群。 - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -## 部署 tidb-lightning - -1. 配置 TiDB Lightning - - 使用如下命令获得 TiDB Lightning 的默认配置。 - - {{< copyable "shell-regular" >}} - - ```shell - helm inspect values pingcap/tidb-lightning --version= > tidb-lightning-values.yaml - ``` - - tidb-lightning Helm chart 支持恢复本地或远程的备份数据。 - - * 本地模式 - - 本地模式要求 Mydumper 备份数据位于其中一个 Kubernetes 节点上。要启用该模式，你需要将 `dataSource.local.nodeName` 设置为该节点名称，将 `dataSource.local.hostPath` 设置为 Mydumper 备份数据目录路径，该路径中需要包含名为 `metadata` 的文件。 - - * 远程模式 - - 与本地模式不同，远程模式需要使用 [rclone](https://rclone.org) 将 Mydumper 备份 tarball 文件从网络存储中下载到 PV 中。远程模式能在 rclone 支持的任何云存储下工作，目前已经有以下存储进行了相关测试：[Google Cloud Storage (GCS)](https://cloud.google.com/storage/)、[AWS S3](https://aws.amazon.com/s3/) 和 [Ceph Object Storage](https://ceph.com/ceph-storage/object-storage/)。 - - 1. 确保 `values.yaml` 中的 `dataSource.local.nodeName` 和 `dataSource.local.hostPath` 被注释掉。 - - 2. 新建一个包含 rclone 配置的 `Secret`。rclone 配置示例如下。一般只需要配置一种云存储。有关其他的云存储，请参考 [rclone 官方文档](https://rclone.org/)。 - - {{< copyable "" >}} - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: cloud-storage-secret - type: Opaque - stringData: - rclone.conf: | - [s3] - type = s3 - provider = AWS - env_auth = false - access_key_id = - secret_access_key = - region = us-east-1 - [ceph] - type = s3 - provider = Ceph - env_auth = false - access_key_id = - secret_access_key = - endpoint = - region = :default-placement - [gcs] - type = google cloud storage - # 该服务账号必须被授予 Storage Object Viewer 角色。 - # 该内容可以通过 `cat | jq -c .` 命令获取。 - service_account_credentials = - ``` - - 使用你的实际配置替换上述配置中的占位符，并将该文件存储为 `secret.yaml`。然后通过 `kubectl apply -f secret.yaml -n ` 命令创建该 `Secret`。 - - 3. 将 `dataSource.remote.storageClassName` 设置为 Kubernetes 集群中现有的一个存储类型。 - -2. 部署 TiDB Lightning - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-lightning --name= --namespace= --set failFast=true -f tidb-lightning-values.yaml --version= - ``` - -当 TiDB Lightning 未能成功恢复数据时，不能简单地直接重启进程，必须进行**手动干预**，否则将很容易出现错误。因此，tidb-lightning 的 `Job` 重启策略被设置为 `Never`。 - -> **注意：** -> -> 目前，即使数据被成功恢复，TiDB Lightning 也会[报出非零错误码并退出](https://github.com/pingcap/tidb-lightning/pull/230)，这会导致 `Job` 失败。因此，数据恢复成功与否需要通过查看 tidb-lightning pod 的日志进行确认。 - -如果 TiDB Lightning 未能成功恢复数据，需要采用以下步骤进行手动干预： - -1. 运行 `kubectl delete job -n -tidb-lightning`，删除 lightning `Job`。 - -2. 运行 `helm template pingcap/tidb-lightning --name --set failFast=false -f tidb-lightning-values.yaml | kubectl apply -n -f -`，重新创建禁用 `failFast` 的 lightning `Job`。 - -3. 当 lightning pod 重新运行时，在 lightning 容器中执行 `kubectl exec -it -n sh` 命令。 - -4. 运行 `cat /proc/1/cmdline`，获得启动脚本。 - -5. 参考[故障排除指南](/v3.1/how-to/troubleshoot/tidb-lightning.md#tidb-lightning-troubleshooting)，对 lightning 进行诊断。 - -## 销毁 TiDB Lightning - -目前，TiDB Lightning 只能在线下恢复数据。当恢复过程结束、TiDB 集群需要向外部应用提供服务时，可以销毁 TiDB Lightning 以节省开支。 - -删除 tikv-importer 的步骤： - -1. 在 TiDB 集群 chart 的 `values.yaml` 文件中将 `importer.create` 设置为 `false`。 - -2. 然后运行 `helm upgrade pingcap/tidb-cluster -f values.yaml`。 - -删除 tidb-lightning 的方法： - -* 运行 `helm delete --purge`。 diff --git a/v3.1/tidb-in-kubernetes/maintain/log-collecting.md b/v3.1/tidb-in-kubernetes/maintain/log-collecting.md deleted file mode 100644 index c1fe3fd6310a..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/log-collecting.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: 日志收集 -category: how-to ---- - -# 日志收集 - -系统与程序的运行日志对排查问题以及实现一些自动化操作可能非常有用。本文将简要说明收集 TiDB 及相关组件日志的方法。 - -## TiDB 与 Kubernetes 组件运行日志 - -通过 TiDB Operator 部署的 TiDB 各组件默认将日志输出在容器的 `stdout` 和 `stderr` 中。对于 Kubernetes 而言，这些日志会被存放在宿主机的 `/var/log/containers` 目录下，并且文件名中包含了 Pod 和容器名称等信息。因此，对容器中应用的日志收集可以直接在宿主机上完成。 - -如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将 Kubernetes 所在的宿主机上的 `/var/log/containers/*.log` 文件加入采集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。 - -Kubernetes 官方文档中提供了 [ElasticSearch](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/) 和 [Stackdriver](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/) 两种日志收集方案可供参考。 - -常见的可用于收集 Kubernetes 日志的开源工具有： - -- [Fluentd](https://www.fluentd.org/) -- [Fluent-bit](https://fluentbit.io/) -- [Filebeat](https://www.elastic.co/products/beats/filebeat) -- [Logstash](https://www.elastic.co/products/logstash) - -收集到的日志通常可以汇总存储在某一特定的服务器上，或存放到 ElasticSearch 等专用的存储、分析系统当中。 - -一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。 - -如果不通过单独的日志收集工具汇总日志，你也可以直接使用 `kubectl` 工具查看某个容器的运行日志，但这一方法无法查看已销毁容器的日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -n -``` - -若需查看容器重启之前的日志，可以在执行上述命令时添加 `-p` 参数。 - -如果需要从多个 Pod 获取日志，可以使用 [`stern`](https://github.com/wercker/stern)： - -{{< copyable "shell-regular" >}} - -```shell -stern -n tidb -c slowlog -``` - -## TiDB 慢查询日志 - -对于 3.0 之前的版本，在默认情况下，TiDB 会打印慢查询日志到标准输出，和应用日志混在一起。 - -- 如果 TiDB 版本 <= v2.1.7，你可以通过关键字 `SLOW_QUERY` 来筛选慢查询日志，例如： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl logs -n | grep SLOW_QUERY - ``` - -- 如果 TiDB 版本 >= v2.1.8，由于慢查询日志格式发生变化，不太方便分离慢查询日志，建议参考下面内容配置 `separateSlowLog: true` 单独查看慢查询日志。 - -在一些情况下，你可能希望使用一些工具或自动化系统对日志内容进行分析、处理。TiDB 各组件的应用日志使用了[统一的日志格式](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)以便于程序解析，但由于慢查询日志使用的是与 MySQL 兼容的多行格式，与应用日志混在一起时可能会对解析造成困难。 - -如果希望将慢查询日志和应用日志区分开，可以在 `values.yaml` 文件中配置 `separateSlowLog` 参数，将慢查询日志输出到一个专用的旁路容器中，这样慢查询日志在宿主机上会被输出到一个单独的文件，和应用日志分开。 - -修改方法为编辑 `values.yaml` 文件，将 `separateSlowLog` 参数设置为 `true`： - -```yaml -# Uncomment the following line to enable separate output of the slow query log - separateSlowLog: true -``` - -之后再运行 `helm upgrade` 使配置生效，然后可以通过名为 `slowlog` 的 sidecar 容器查看慢查询日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -n -c slowlog -``` - -对于 3.0 及更新的版本，TiDB 将慢查询日志输出到独立的 `slowlog.log` 文件中，并且 `separateSlowLog` 是默认开启的，所以可以直接通过 sidecar 容器查看慢查询日志，无需额外设置。 - -> **注意：** -> -> 慢查询日志的格式与 MySQL 的慢查询日志相同，但由于 TiDB 自身的特点，其中的一些具体字段可能存在差异，因此解析 MySQL 慢查询日志的工具不一定能完全兼容 TiDB 的慢查询日志。 - -## 系统日志 - -系统日志可以通过常规方法在 Kubernetes 宿主机上收集，如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将相关服务器和日志文件添加到收集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。 - -上文提到的几种常见日志收集工具均支持对系统日志的收集，一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。 diff --git a/v3.1/tidb-in-kubernetes/maintain/restart.md b/v3.1/tidb-in-kubernetes/maintain/restart.md deleted file mode 100644 index c17138c41384..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/restart.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: 重启 Kubernetes 上的 TiDB 集群 -summary: 了解如何重启 Kubernetes 集群上的 TiDB 集群。 -category: how-to ---- - -# 重启 Kubernetes 上的 TiDB 集群 - -本文描述了如何强制重启 Kubernetes 集群上的 TiDB 集群，包括重启某个 Pod，重启某个组件的所有 Pod 和重启 TiDB 集群的所有 Pod。 - -> **注意：** -> -> TiDB Operator v1.0.x 版本只支持强制重启 Pod。 -> -> - 在强制重启 PD Pod 过程中，如果被重启的 PD Pod 是 Leader，重启过程不会自动迁移 Leader，这会导致 PD 服务短时间中断。 -> - 在强制重启 TiKV Pod 过程中，不会自动迁移 TiKV 的 Region Leader，会导致访问对应数据的请求异常。 -> - 在强制重启 TiDB Pod 过程中，会导致访问对应 TiDB 的请求失败。 - -## 强制重启某个 Pod - -要强制重启某个 Pod，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pod -n -``` - -## 强制重启某个组件的所有 Pod - -通过以下命令可以列出组件目前有哪些 Pod： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pod -n -l app.kubernetes.io/component= -``` - -要强制重启某个组件的所有 Pod，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pod -n -l app.kubernetes.io/component= -``` - -把 `` 分别替换为 `pd`、`tidb`、`tikv`，可以分别强制重启 `PD`、`TiDB`、`TiKV` 组件所有 Pod。 - -## 强制重启 TiDB 集群的所有 Pod - -通过以下命令可以列出 TiDB 集群目前有哪些 Pod，包括 `monitor`、`discovery` 等： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get pod -n -l app.kubernetes.io/instance= -``` - -要强制重启 TiDB 集群的所有 Pod，包括 `monitor`、`discovery` 等，执行以下命令： - -{{< copyable "shell-regular" >}} - -```shell -kubectl delete pod -n -l app.kubernetes.io/instance= -``` diff --git a/v3.1/tidb-in-kubernetes/maintain/tidb-binlog.md b/v3.1/tidb-in-kubernetes/maintain/tidb-binlog.md deleted file mode 100644 index d18d21b37181..000000000000 --- a/v3.1/tidb-in-kubernetes/maintain/tidb-binlog.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: TiDB Binlog 运维 -summary: 了解如何在 Kubernetes 上运维 TiDB 集群的 TiDB Binlog。 -category: how-to ---- - -# TiDB Binlog 运维 - -本文档介绍如何在 Kubernetes 上运维 TiDB 集群的 [TiDB Binlog](/v3.1/reference/tidb-binlog/overview.md)。 - -## 运维准备 - -- [部署 TiDB Operator](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md)； -- [安装 Helm](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm) 并配置 PingCAP 官方 chart 仓库。 - -## 启用 TiDB 集群的 TiDB Binlog - -默认情况下，TiDB Binlog 在 TiDB 集群中处于禁用状态。若要创建一个启用 TiDB Binlog 的 TiDB 集群，或在现有 TiDB 集群中启用 TiDB Binlog，可根据以下步骤进行操作： - -1. 按照以下说明修改 `values.yaml` 文件： - - * 将 `binlog.pump.create` 的值设为 `true`。 - * 将 `binlog.drainer.create` 的值设为 `true`。 - * 将 `binlog.pump.storageClassName` 和 `binlog.drainer.storageClassName` 设为所在 Kubernetes 集群上可用的 `storageClass`。 - * 将 `binlog.drainer.destDBType` 设为所需的下游存储类型。 - - TiDB Binlog 支持三种下游存储类型： - - * PersistenceVolume：默认的下游存储类型。可通过修改 `binlog.drainer.storage` 来为 `drainer` 配置大 PV。 - - * 与 MySQL 兼容的数据库：通过将 `binlog.drainer.destDBType` 设置为 `mysql` 来启用。同时，必须在 `binlog.drainer.mysql` 中配置目标数据库的地址和凭据。 - - * Apache Kafka：通过将 `binlog.drainer.destDBType` 设置为 `kafka` 来启用。同时，必须在 `binlog.drainer.kafka` 中配置目标集群的 zookeeper 地址和 Kafka 地址。 - -2. 为 TiDB 与 Pump 组件设置亲和性和反亲和性： - - > **注意：** - > - > 如果在生产环境中开启 TiDB Binlog，建议为 TiDB 与 Pump 组件设置亲和性和反亲和性。如果在内网测试环境中尝试使用开启 TiDB Binlog，可以跳过此步。 - - 默认情况下，TiDB 的 affinity 亲和性设置为 `{}`。由于目前 Pump 组件与 TiDB 组件默认并非一一对应，当启用 TiDB Binlog 时，如果 Pump 与 TiDB 组件分开部署并出现网络隔离，而且 TiDB 组件还开启了 `ignore-error`，则会导致 TiDB 丢失 Binlog。推荐通过亲和性特性将 TiDB 组件与 Pump 部署在同一台 Node 上，同时通过反亲和性特性将 Pump 分散在不同的 Node 上，每台 Node 上至多仅需一个 Pump 实例。 - - > **注意：** - > - > `` 需要替换为目标 `tidb-cluster` 的 Helm release name。 - - * 将 `tidb.affinity` 按照如下设置： - - ```yaml - tidb: - affinity: - podAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "pump" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - ``` - - * 将 `binlog.pump.affinity` 按照如下设置： - - ```yaml - binlog: - pump: - affinity: - podAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "tidb" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: "app.kubernetes.io/component" - operator: In - values: - - "pump" - - key: "app.kubernetes.io/managed-by" - operator: In - values: - - "tidb-operator" - - key: "app.kubernetes.io/name" - operator: In - values: - - "tidb-cluster" - - key: "app.kubernetes.io/instance" - operator: In - values: - - - topologyKey: kubernetes.io/hostname - ``` - -3. 创建一个新的 TiDB 集群或更新现有的集群： - - * 创建一个启用 TiDB Binlog 的 TiDB 新集群： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-cluster --name= --namespace= --version= -f - ``` - - * 更新现有的 TiDB 集群以启用 TiDB Binlog： - - > **注意：** - > - > 如果设置了 TiDB 组件的亲和性，那么更新现有的 TiDB 集群将引起 TiDB 集群中的 TiDB 组件滚动更新。 - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster --version= -f - ``` - -## 部署多个 drainer - -默认情况下，仅创建一个下游 drainer。可安装 `tidb-drainer` Helm chart 来为 TiDB 集群部署多个 drainer，示例如下： - -1. 确保 PingCAP Helm 库是最新的： - - {{< copyable "shell-regular" >}} - - ```shell - helm repo update - ``` - - {{< copyable "shell-regular" >}} - - ```shell - helm search tidb-drainer -l - ``` - -2. 获取默认的 `values.yaml` 文件以方便自定义： - - {{< copyable "shell-regular" >}} - - ```shell - helm inspect values pingcap/tidb-drainer --version= > values.yaml - ``` - -3. 修改 `values.yaml` 文件以指定源 TiDB 集群和 drainer 的下游数据库。示例如下： - - ```yaml - clusterName: example-tidb - clusterVersion: v3.0.0 - storageClassName: local-storage - storage: 10Gi - config: | - detect-interval = 10 - [syncer] - worker-count = 16 - txn-batch = 20 - disable-dispatch = false - ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" - safe-mode = false - db-type = "tidb" - [syncer.to] - host = "slave-tidb" - user = "root" - password = "" - port = 4000 - ``` - - `clusterName` 和 `clusterVersion` 必须匹配所需的源 TiDB 集群。 - - 有关完整的配置详细信息，请参阅 [Kubernetes 上的 TiDB Binlog Drainer 配置](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-drainer.md)。 - -4. 部署 drainer： - - {{< copyable "shell-regular" >}} - - ```shell - helm install pingcap/tidb-drainer --name= --namespace= --version= -f values.yaml - ``` - - > **注意：** - > - > 该 chart 必须与源 TiDB 集群安装在相同的命名空间中。 diff --git a/v3.1/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md b/v3.1/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md deleted file mode 100644 index 842ec5fbc275..000000000000 --- a/v3.1/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群监控 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群监控 - -基于 Kubernetes 环境部署的 TiDB 集群监控可以大体分为两个部分：对 TiDB 集群本身的监控、对 Kubernetes 集群及 TiDB Operator 的监控。本文将对两者进行简要说明。 - -## TiDB 集群的监控 - -TiDB 通过 Prometheus 和 Grafana 监控 TiDB 集群。在通过 TiDB Operator 创建新的 TiDB 集群时，对于每个 TiDB 集群，会同时创建、配置一套独立的监控系统，与 TiDB 集群运行在同一 Namespace，包括 Prometheus 和 Grafana 两个组件。 - -监控数据默认没有持久化，如果由于某些原因监控容器重启，已有的监控数据会丢失。可以在 `values.yaml` 中设置 `monitor.persistent` 为 `true` 来持久化监控数据。开启此选项时应将 `storageClass` 设置为一个当前集群中已有的存储，并且此存储应当支持将数据持久化，否则仍然会存在数据丢失的风险。 - -在 [TiDB 集群监控](/v3.1/how-to/monitor/monitor-a-cluster.md)中有一些监控系统配置的细节可供参考。 - -### 查看监控面板 - -可以通过 `kubectl port-forward` 查看监控面板： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-grafana 3000:3000 &>/tmp/portforward-grafana.log -``` - -然后在浏览器中打开 [http://localhost:3000](http://localhost:3000)，默认用户名和密码都为 `admin`。 - -Grafana 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.grafana.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问面板。 - -如果不需要使用 Grafana，可以在部署时在 `values.yaml` 中将 `monitor.grafana.create` 设置为 `false` 来节省资源。这一情况下需要使用其他已有或新部署的数据可视化工具直接访问监控数据来完成可视化。 - -### 访问监控数据 - -对于需要直接访问监控数据的情况，可以通过 `kubectl port-forward` 来访问 Prometheus： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-prometheus 9090:9090 &>/tmp/portforward-prometheus.log -``` - -然后在浏览器中打开 [http://localhost:9090](http://localhost:9090)，或通过客户端工具访问此地址即可。 - -Prometheus 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.prometheus.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问监控数据。 - -## Kubernetes 的监控 - -随集群部署的 TiDB 监控只关注 TiDB 本身各组件的运行情况，并不包括对容器资源、宿主机、Kubernetes 组件和 TiDB Operator 等的监控。对于这些组件或资源的监控，需要在整个 Kubernetes 集群维度部署监控系统来实现。 - -### 宿主机监控 - -对宿主机及其资源的监控与传统的服务器物理资源监控相同。 - -如果在你的现有基础设施中已经有针对物理服务器的监控系统，只需要通过常规方法将 Kubernetes 所在的宿主机添加到现有监控系统中即可；如果没有可用的监控系统，或者希望部署一套独立的监控系统用于监控 Kubernetes 所在的宿主机，也可以使用你熟悉的任意监控系统。 - -新部署的监控系统可以运行于独立的服务器、直接运行于 Kubernetes 所在的宿主机，或运行于 Kubernetes 集群内，不同部署方式除在安装配置与资源利用上存在少许差异，在使用上并没有重大区别。 - -常见的可用于监控服务器资源的开源监控系统有： - -- [CollectD](https://collectd.org/) -- [Nagios](https://www.nagios.org/) -- [Prometheus](http://prometheus.io/) & [node_exporter](https://github.com/prometheus/node_exporter) -- [Zabbix](https://www.zabbix.com/) - -一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的监控解决方案可以选择。 - -我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 在 Kubernetes 集群内部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于 Kubernetes 自身组件的监控。 - -### Kubernetes 组件监控 - -对 Kubernetes 组件的监控可以参考[官方文档](https://kubernetes.io/docs/tasks/debug-application-cluster/resource-usage-monitoring/)提供的方案，也可以使用其他兼容 Kubernetes 的监控系统来进行。 - -一些云服务商可能提供了自己的 Kubernetes 组件监控方案，一些专门的性能监控服务商也有各自的 Kubernetes 集成方案可以选择。 - -由于 TiDB Operator 实际上是运行于 Kubernetes 中的容器，选择任一可以覆盖对 Kubernetes 容器状态及资源进行监控的监控系统即可覆盖对 TiDB Operator 的监控，无需再额外部署监控组件。 - -我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于对宿主机资源的监控。 - -## 报警配置 - -### TiDB 集群报警 - -在随 TiDB 集群部署 Prometheus 时，会自动导入一些默认的报警规则，可以通过浏览器访问 Prometheus 的 Alerts 页面查看当前系统中的所有报警规则和状态。 - -我们目前暂不支持报警规则的自定义配置，如果确实需要修改报警规则，可以手动下载 charts 进行修改。 - -默认的 Prometheus 和报警配置不能发送报警消息，如需发送报警消息，可以使用任意支持 Prometheus 报警的工具与其集成。推荐通过 [AlertManager](https://prometheus.io/docs/alerting/alertmanager/) 管理与发送报警消息。 - -如果在你的现有基础设施中已经有可用的 AlertManager 服务，可以在 `values.yaml` 文件中修改 `monitor.prometheus.alertmanagerURL` 配置其地址供 Prometheus 使用；如果没有可用的 AlertManager 服务，或者希望部署一套独立的服务，可以参考官方的[说明](https://github.com/prometheus/alertmanager)部署。 - -### Kubernetes 报警 - -如果使用 Prometheus Operator 部署针对 Kubernetes 宿主机和服务的监控，会默认配置一些告警规则，并且会部署一个 AlertManager 服务，具体的设置方法请参阅 [kube-prometheus](https://github.com/coreos/kube-prometheus) 的说明。 - -如果使用其他的工具或服务对 Kubernetes 宿主机和服务进行监控，请查阅该工具或服务提供商的对应资料。 diff --git a/v3.1/tidb-in-kubernetes/reference/configuration/backup.md b/v3.1/tidb-in-kubernetes/reference/configuration/backup.md deleted file mode 100644 index a64a430e57ed..000000000000 --- a/v3.1/tidb-in-kubernetes/reference/configuration/backup.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群备份配置 -category: reference ---- - -# Kubernetes 上的 TiDB 集群备份配置 - -`tidb-backup` 是一个用于 Kubernetes 上 TiDB 集群备份和恢复的 Helm Chart。本文详细介绍了 `tidb-backup` 的可配置参数。 - -## `mode` - -+ 运行模式 -+ 默认："backup" -+ 可选值为 `backup`（备份集群数据）和 `restore`（恢复集群数据） - -## `clusterName` - -+ 目标集群名字 -+ 默认："demo" -+ 指定要从哪个集群进行备份或将数据恢复到哪个集群中 - -## `name` - -+ 备份名 -+ 默认值："fullbackup-"，`` 是备份的开始时间，精确到分钟 -+ 备份名用于区分不同的备份数据 - -## `secretName` - -+ 访问目标集群时使用的凭据 -+ 默认："backup-secret" -+ 该 Kubernetes Secret 中需要存储目标集群的登录用户名和密码，你可以通过以下命令来创建这个 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic backup-secret -n --from-literal=user=root --from-literal=password= - ``` - -## `storage.className` - -+ Kubernetes StorageClass -+ 默认："local-storage" -+ 备份任务需要绑定一个持久卷 (Persistent Volume, PV) 来永久或临时存储备份数据，`StorageClass` 用于声明持久卷使用的存储类型，需要确保该 `StorageClass` 在 Kubernetes 集群中存在。 - -## `storage.size` - -+ 持久卷的空间大小 -+ 默认："100Gi" - -## `backupOptions` - -+ 备份参数 -+ 默认："--chunk-filesize=100" -+ 为备份数据时使用的 [Mydumper](https://github.com/maxbube/mydumper/blob/master/docs/mydumper_usage.rst#options) 指定额外的运行参数 - -## `restoreOptions` - -+ 恢复参数 -+ 默认："-t 16" -+ 为恢复数据时使用的 [Loader](/v3.1/reference/tools/loader.md) 指定额外的运行参数 - -## `gcp.bucket` - -+ Google Cloud Storage 的 bucket 名字 -+ 默认："" -+ 用于存储备份数据到 Google Cloud Storage 上 - -> **注意：** -> -> 一旦设置了 `gcp` 下的任何参数，备份和恢复就会使用 Google Cloud Storage 进行数据存储。也就是说，假如要设置 `gcp` 下的参数，就需要保证所有 `gcp` 相关参数都得到正确配置，否则会造成备份恢复失败。 - -## `gcp.secretName` - -+ 访问 GCP 时使用的凭据 -+ 默认："" -+ 该 Kubernetes Secret 中需要存储 GCP 的 Service Account 凭据，你可以参考 [Google Cloud Documentation](https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually) 来下载凭据文件，然后通过下面的命令创建 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic gcp-backup-secret -n --from-file=./credentials.json - ``` - -## `ceph.endpoint` - -+ Ceph 对象存储的 Endpoint -+ 默认："" -+ 用于访问 Ceph 对象存储 - -> **注意：** -> -> 一旦设置了 `ceph` 下的任何参数，备份和恢复就会使用 Ceph 对象存储进行数据存储。也就是说，假如要设置 `ceph` 下的参数，就需要保证所有 `ceph` 相关参数都得到正确配置，否则会造成备份恢复失败。 - -## `ceph.bucket` - -+ Ceph 对象存储的 bucket 名字 -+ 默认："" -+ 用于存储数据到 Ceph 对象存储上 - -## `ceph.secretName` - -+ 访问 Ceph 对象存储时使用的凭据 -+ 默认："" -+ 该 Kubernetes Secret 中需要存储访问 Ceph 时使用的 `access_key` 和 `secret_key`。可使用如下命令来创建这个 Secret： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl create secret generic ceph-backup-secret -n --from-literal=access_key= --from-literal=secret_key= - ``` diff --git a/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md b/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md deleted file mode 100644 index ff73c75b8806..000000000000 --- a/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: Kubernetes 上的持久化存储类型配置 -category: reference ---- - -# Kubernetes 上的持久化存储类型配置 - -TiDB 集群中 PD、TiKV、监控等组件以及 TiDB Binlog 和备份等工具都需要使用将数据持久化的存储。Kubernetes 上的数据持久化需要使用 [PersistentVolume (PV)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)。Kubernetes 提供多种[存储类型](https://kubernetes.io/docs/concepts/storage/volumes/)，主要分为两大类： - -* 网络存储 - - 存储介质不在当前节点，而是通过网络方式挂载到当前节点。一般有多副本冗余提供高可用保证，在节点出现故障时，对应网络存储可以再挂载到其它节点继续使用。 - -* 本地存储 - - 存储介质在当前节点，通常能提供比网络存储更低的延迟，但没有多副本冗余，一旦节点出故障，数据就有可能丢失。如果是 IDC 服务器，节点故障可以一定程度上对数据进行恢复，但公有云上使用本地盘的虚拟机在节点故障后，数据是**无法找回**的。 - -PV 一般由系统管理员或 volume provisioner 自动创建，PV 与 Pod 是通过 [PersistentVolumeClaim (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) 进行关联的。普通用户在使用 PV 时并不需要直接创建 PV，而是通过 PVC 来申请使用 PV，对应的 volume provisioner 根据 PVC 创建符合要求的 PV，并将 PVC 与该 PV 进行绑定。 - -> **警告：** -> -> 为了数据安全，任何情况下都不要直接删除 PV，除非对 volume provisioner 原理非常清楚。 - -## TiDB 集群推荐存储类型 - -TiKV 自身借助 Raft 实现了数据复制，出现节点故障后，PD 会自动进行数据调度补齐缺失的数据副本，同时 TiKV 要求存储有较低的读写延迟，所以生产环境强烈推荐使用本地 SSD 存储。 - -PD 同样借助 Raft 实现了数据复制，但作为存储集群元信息的数据库，并不是 IO 密集型应用，所以一般本地普通 SAS 盘或网络 SSD 存储（例如 AWS 上 gp2 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）就可以满足要求。 - -监控组件以及 TiDB Binlog、备份等工具，由于自身没有做多副本冗余，所以为保证可用性，推荐用网络存储。其中 TiDB Binlog 的 pump 和 drainer 组件属于 IO 密集型应用，需要较低的读写延迟，所以推荐用高性能的网络存储（例如 AWS 上的 io1 类型的 EBS 存储卷，GCP 上的持久化 SSD 盘）。 - -在利用 TiDB Operator 部署 TiDB 集群或者备份工具的时候，需要持久化存储的组件都可以通过 values.yaml 配置文件中对应的 `storageClassName` 设置存储类型。不设置时默认都使用 `local-storage`。 - -## 网络 PV 配置 - -Kubernetes 1.11 及以上的版本支持[网络 PV 的动态扩容](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/)，但用户需要为相应的 `StorageClass` 开启动态扩容支持。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl patch storageclass -p '{"allowVolumeExpansion": true}' -``` - -开启动态扩容后，通过下面方式对 PV 进行扩容： - -1. 修改 PVC 大小 - - 假设之前 PVC 大小是 10 Gi，现在需要扩容到 100 Gi - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pvc -n -p '{"spec": {"resources": {"requests": {"storage": "100Gi"}}}' - ``` - -2. 查看 PV 扩容成功 - - 扩容成功后，通过 `kubectl get pvc -n ` 显示的大小仍然是初始大小，但查看 PV 大小会显示已经扩容到预期的大小。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get pv | grep - ``` - -## 本地 PV 配置 - -Kubernetes 当前支持静态分配的本地存储。可使用 [local-static-provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner) 项目中的 `local-volume-provisioner` 程序创建本地存储对象。创建流程如下： - -1. 参考 Kubernetes 提供的[操作文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md)，在集群节点中预分配本地存储。 - -2. 部署 `local-volume-provisioner` 程序。 - - {{< copyable "shell-regular" >}} - - ```shell - kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml - ``` - - 通过下面命令查看 Pod 和 PV 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l app=local-volume-provisioner && \ - kubectl get pv | grep local-storage - ``` - - `local-volume-provisioner` 会为发现目录 (discovery directory) 下的每一个挂载点创建一个 PV。注意，在 GKE 上，默认只能创建大小为 375 GiB 的本地卷。 - -更多信息，可参阅 [Kubernetes 本地存储](https://kubernetes.io/docs/concepts/storage/volumes/#local)和 [local-static-provisioner 文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner#overview)。 - -### 最佳实践 - -- Local PV 的路径是本地存储卷的唯一标示符。为了保证唯一性并避免冲突，推荐使用设备的 UUID 来生成唯一的路径 -- 如果想要 IO 隔离，建议每个存储卷使用一块物理盘会比较恰当，在硬件层隔离 -- 如果想要容量隔离，建议每个存储卷一个分区或者每个存储卷使用一块物理盘来实现 - -更多信息，可参阅 local-static-provisioner 的[最佳实践文档](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/best-practices.md)。 - -### 示例 - -如果监控、TiDB Binlog、备份等组件都使用本地盘存储数据，可以挂载普通 SAS 盘，并分别创建不同的 `StorageClass` 供这些组件使用，具体操作如下： - -- 给监控数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/disks` 目录，后续创建 `local-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量。1 个目录会对应创建 1 个 PV。每个 TiDB 集群的监控数据会使用 1 个 PV。 - -- 给 TiDB Binlog 和备份数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/backup` 目录，后续创建 `backup-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量、每个集群内的 Pump 数量及备份方式。1 个目录会对应创建 1 个 PV。每个 Pump 会使用 1 个 PV，每个 drainer 会使用 1 个 PV，每次 [Ad-hoc 全量备份](/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md#ad-hoc-全量备份)会使用 1 个 PV，所有[定时全量备份](/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md#定时全量备份)会共用 1 个 PV。 - -- 给 PD 数据使用的盘，可以参考[步骤](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#sharing-a-disk-filesystem-by-multiple-filesystem-pvs)挂载盘，创建目录，并将新建的目录以 bind mount 方式挂载到 `/mnt/sharedssd` 目录，后续创建 `shared-ssd-storage` `StorageClass`。 - - > **注意：** - > - > 该步骤中创建的目录个数取决于规划的 TiDB 集群数量及每个集群内的 PD 数量。1 个目录会对应创建 1 个 PV。每个 PD 会使用一个 PV。 - -- 给 TiKV 数据使用的盘，可通过[普通挂载](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/blob/master/docs/operations.md#use-a-whole-disk-as-a-filesystem-pv)方式将盘挂载到 `/mnt/ssd` 目录，后续创建 `ssd-storage` `StorageClass`。 - -盘挂载完成后，需要根据上述磁盘挂载情况修改 [`local-volume-provisioner` yaml 文件](https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml)，配置发现目录并创建必要的 `StorageClass`。以下是根据上述挂载修改的 yaml 文件示例： - -``` -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "local-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "ssd-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "shared-ssd-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "backup-storage" -provisioner: "kubernetes.io/no-provisioner" -volumeBindingMode: "WaitForFirstConsumer" ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: local-provisioner-config - namespace: kube-system -data: - nodeLabelsForPV: | - - kubernetes.io/hostname - storageClassMap: | - shared-ssd-storage: - hostDir: /mnt/sharedssd - mountDir: /mnt/sharedssd - ssd-storage: - hostDir: /mnt/ssd - mountDir: /mnt/ssd - local-storage: - hostDir: /mnt/disks - mountDir: /mnt/disks - backup-storage: - hostDir: /mnt/backup - mountDir: /mnt/backup ---- - -...... - - volumeMounts: - - ...... - - - mountPath: /mnt/ssd - name: local-ssd - mountPropagation: "HostToContainer" - - mountPath: /mnt/sharedssd - name: local-sharedssd - mountPropagation: "HostToContainer" - - mountPath: /mnt/disks - name: local-disks - mountPropagation: "HostToContainer" - - mountPath: /mnt/backup - name: local-backup - mountPropagation: "HostToContainer" - volumes: - - ...... - - - name: local-ssd - hostPath: - path: /mnt/ssd - - name: local-sharedssd - hostPath: - path: /mnt/sharedssd - - name: local-disks - hostPath: - path: /mnt/disks - - name: local-backup - hostPath: - path: /mnt/backup -...... - -``` - -最后通过 `kubectl apply` 命令部署 `local-volume-provisioner` 程序。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/local-dind/local-volume-provisioner.yaml -``` - -后续创建 TiDB 集群或备份等组件的时候，再配置相应的 `StorageClass` 供其使用。 - -## 数据安全 - -一般情况下 PVC 在使用完删除后，与其绑定的 PV 会被 provisioner 清理回收再放入资源池中被调度使用。为避免数据意外丢失，可在全局配置 `StorageClass` 的回收策略 (reclaim policy) 为 `Retain` 或者只将某个 PV 的回收策略修改为 `Retain`。`Retain` 模式下，PV 不会自动被回收。 - -* 全局配置 - - `StorageClass` 的回收策略一旦创建就不能再修改，所以只能在创建时进行设置。如果创建时没有设置，可以再创建相同 provisioner 的 `StorageClass`，例如 GKE 上默认的 pd 类型的 `StorageClass` 默认保留策略是 `Delete`，可以再创建一个名为 `pd-standard` 的保留策略是 `Retain` 的存储类型，并在创建 TiDB 集群时将相应组件的 `storageClassName` 修改为 `pd-standard`。 - - {{< copyable "" >}} - - ```yaml - apiVersion: storage.k8s.io/v1 - kind: StorageClass - metadata: - name: pd-standard - parameters: - type: pd-standard - provisioner: kubernetes.io/gce-pd - reclaimPolicy: Retain - volumeBindingMode: Immediate - ``` - -* 配置单个 PV - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' - ``` - -> **注意：** -> -> TiDB Operator 默认会自动将 PD 和 TiKV 的 PV 保留策略修改为 `Retain` 以确保数据安全。 - -PV 保留策略是 `Retain` 时，如果确认某个 PV 的数据可以被删除，需要通过下面的操作来删除 PV 以及对应的数据： - -1. 删除 PV 对应的 PVC 对象： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete pvc --namespace= - ``` - -2. 设置 PV 的保留策略为 `Delete`，PV 会被自动删除并回收： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}' - ``` - -要了解更多关于 PV 的保留策略可参考[修改 PV 保留策略](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/)。 diff --git a/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md b/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md deleted file mode 100644 index 6ad4b69cc5d3..000000000000 --- a/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群配置 -category: reference ---- - -# Kubernetes 上的 TiDB 集群配置 - -本文介绍 Kubernetes 上 TiDB 集群的配置参数、资源配置，以及容灾配置。 - -## 配置参数 - -TiDB Operator 使用 Helm 部署和管理 TiDB 集群。通过 Helm 获取的配置文件默认提供了基本的配置，通过这个基本配置，可以快速启动一个 TiDB 集群。但是如果用户需要特殊配置或是用于生产环境，则需要根据以下配置参数列表手动配置对应的配置项。 - -> **注意：** -> -> 下文用 `values.yaml` 指代要修改的 TiDB 集群配置文件。 - -| 参数名 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `rbac.create` | 是否启用 Kubernetes 的 RBAC | `true` | -| `clusterName` | TiDB 集群名，默认不设置该变量，`tidb-cluster` 会直接用执行安装时的 `ReleaseName` 代替 | `nil` | -| `extraLabels` | 添加额外的 labels 到 `TidbCluster` 对象 (CRD) 上，参考：[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) | `{}` | -| `schedulerName` | TiDB 集群使用的调度器 | `tidb-scheduler` | -| `timezone` | TiDB 集群默认时区 | `UTC` | -| `pvReclaimPolicy` | TiDB 集群使用的 PV (Persistent Volume)的 reclaim policy | `Retain` | -| `services[0].name` | TiDB 集群对外暴露服务的名字 | `nil` | -| `services[0].type` | TiDB 集群对外暴露服务的类型，(从 `ClusterIP`、`NodePort`、`LoadBalancer` 中选择) | `nil` | -| `discovery.image` | TiDB 集群 PD 服务发现组件的镜像，该组件用于在 PD 集群第一次启动时，为各个 PD 实例提供服务发现功能以协调启动顺序 | `pingcap/tidb-operator:v1.0.0-beta.3` | -| `discovery.imagePullPolicy` | PD 服务发现组件镜像的拉取策略 | `IfNotPresent` | -| `discovery.resources.limits.cpu` | PD 服务发现组件的 CPU 资源限额 | `250m` | -| `discovery.resources.limits.memory` | PD 服务发现组件的内存资源限额 | `150Mi` | -| `discovery.resources.requests.cpu` | PD 服务发现组件的 CPU 资源请求 | `80m` | -| `discovery.resources.requests.memory` | PD 服务发现组件的内存资源请求 | `50Mi` | -| `enableConfigMapRollout` | 是否开启 TiDB 集群自动滚动更新。如果启用，则 TiDB 集群的 ConfigMap 变更时，TiDB 集群自动更新对应组件。该配置只在 tidb-operator v1.0 及以上版本才支持 | `false` | -| `pd.config` | 配置文件格式的 PD 的配置，请参考 [`pd/conf/config.toml`](https://github.com/pingcap/pd/blob/master/conf/config.toml) 查看默认 PD 配置文件（选择对应 PD 版本的 tag），可以参考 [PD 配置文件描述](/v3.1/reference/configuration/pd-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置** | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
`[replication]`
`location-labels = ["region", "zone", "rack", "host"]`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"`
    `[replication]`
    `location-labels = ["region", "zone", "rack", "host"]` | -| `pd.replicas` | PD 的 Pod 数 | `3` | -| `pd.image` | PD 镜像 | `pingcap/pd:v3.0.0-rc.1` | -| `pd.imagePullPolicy` | PD 镜像的拉取策略 | `IfNotPresent` | -| `pd.logLevel` | PD 日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[log]`
`level = "info"` | `info` | -| `pd.storageClassName` | PD 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `pd.maxStoreDownTime` | `pd.maxStoreDownTime` 指一个 store 节点断开连接多长时间后状态会被标记为 `down`，当状态变为 `down` 后，store 节点开始迁移数据到其它 store 节点
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[schedule]`
`max-store-down-time = "30m"` | `30m` | -| `pd.maxReplicas` | `pd.maxReplicas` 是 TiDB 集群的数据的副本数
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `pd.config` 配置：
`[replication]`
`max-replicas = 3` | `3` | -| `pd.resources.limits.cpu` | 每个 PD Pod 的 CPU 资源限额 | `nil` | -| `pd.resources.limits.memory` | 每个 PD Pod 的内存资源限额 | `nil` | -| `pd.resources.limits.storage` | 每个 PD Pod 的存储容量限额 | `nil` | -| `pd.resources.requests.cpu` | 每个 PD Pod 的 CPU 资源请求 | `nil` | -| `pd.resources.requests.memory` | 每个 PD Pod 的内存资源请求 | `nil` | -| `pd.resources.requests.storage` | 每个 PD Pod 的存储容量请求 | `1Gi` | -| `pd.affinity` | `pd.affinity` 定义 PD 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `pd.nodeSelector` | `pd.nodeSelector` 确保 PD Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `pd.tolerations` | `pd.tolerations` 应用于 PD Pods，允许 PD Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `pd.annotations` | 为 PD Pods 添加特定的 `annotations` | `{}` | -| `tikv.config` | 配置文件格式的 TiKV 的配置，请参考 [`tikv/etc/config-template.toml`](https://github.com/tikv/tikv/blob/master/etc/config-template.toml) 查看默认 TiKV 配置文件（选择对应 TiKV 版本的 tag），可以参考 [TiKV 配置文件描述](https://pingcap.com/docs-cn/v3.1/reference/configuration/tikv-server/configuration-file/)查看配置参数的具体介绍（请选择对应的文档版本），这里只需要**按照配置文件中的格式修改配置**

以下两个配置项需要显式配置：

`[storage.block-cache]`
  `shared = true`
  `capacity = "1GB"`
推荐设置：`capacity` 设置为 `tikv.resources.limits.memory` 的 50%

`[readpool.coprocessor]`
  `high-concurrency = 8`
  `normal-concurrency = 8`
  `low-concurrency = 8`
推荐设置：设置为 `tikv.resources.limits.cpu` 的 80%| TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`log-level = "info"`
配置示例：
  `config:` \|
    `log-level = "info"` | -| `tikv.replicas` | TiKV 的 Pod 数 | `3` | -| `tikv.image` | TiKV 的镜像 | `pingcap/tikv:v3.0.0-rc.1` | -| `tikv.imagePullPolicy` | TiKV 镜像的拉取策略 | `IfNotPresent` | -| `tikv.logLevel` | TiKV 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`log-level = "info"` | `info` | -| `tikv.storageClassName` | TiKV 使用的 storageClass，storageClassName 指代一种由 Kubernetes 集群提供的存储类型，不同的类可能映射到服务质量级别、备份策略或集群管理员确定的任意策略。详细参考：[storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `tikv.syncLog` | syncLog 指是否启用 raft 日志同步功能，启用该功能能保证在断电时数据不丢失
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[raftstore]`
`sync-log = true` | `true` | -| `tikv.grpcConcurrency` | 配置 gRPC server 线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[server]`
`grpc-concurrency = 4` | `4` | -| `tikv.resources.limits.cpu` | 每个 TiKV Pod 的 CPU 资源限额 | `nil` | -| `tikv.resources.limits.memory` | 每个 TiKV Pod 的内存资源限额 | `nil` | -| `tikv.resources.limits.storage` | 每个 TiKV Pod 的存储容量限额 | `nil` | -| `tikv.resources.requests.cpu` | 每个 TiKV Pod 的 CPU 资源请求 | `nil` | -| `tikv.resources.requests.memory` | 每个 TiKV Pod 的内存资源请求 | `nil` | -| `tikv.resources.requests.storage` | 每个 TiKV Pod 的存储容量请求 | `10Gi` | -| `tikv.affinity` | `tikv.affinity` 定义 TiKV 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `tikv.nodeSelector` | `tikv.nodeSelector`确保 TiKV Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tikv.tolerations` | `tikv.tolerations` 应用于 TiKV Pods，允许 TiKV Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `tikv.annotations` | 为 TiKV Pods 添加特定的 `annotations` | `{}` | -| `tikv.defaultcfBlockCacheSize` | 指定 block 缓存大小，block 缓存用于缓存未压缩的 block，较大的 block 缓存设置可以加快读取速度。一般推荐设置为 `tikv.resources.limits.memory` 的 30%-50%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.defaultcf]`
`block-cache-size = "1GB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `1GB` | -| `tikv.writecfBlockCacheSize` | 指定 writecf 的 block 缓存大小，一般推荐设置为 `tikv.resources.limits.memory` 的 10%-30%
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[rocksdb.writecf]`
`block-cache-size = "256MB"`
从 TiKV v3.0.0 开始，不再需要配置 `[rocksdb.defaultcf].block-cache-size` 和 `[rocksdb.writecf].block-cache-size`，改为配置 `[storage.block-cache].capacity` | `256MB` | -| `tikv.readpoolStorageConcurrency` | TiKV 存储的高优先级/普通优先级/低优先级操作的线程池大小
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.storage]`
`high-concurrency = 4`
`normal-concurrency = 4`
`low-concurrency = 4` | `4` | -| `tikv.readpoolCoprocessorConcurrency` | 一般如果 `tikv.resources.limits.cpu` > 8，则 `tikv.readpoolCoprocessorConcurrency` 设置为`tikv.resources.limits.cpu` * 0.8
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[readpool.coprocessor]`
`high-concurrency = 8`
`normal-concurrency = 8`
`low-concurrency = 8` | `8` | -| `tikv.storageSchedulerWorkerPoolSize` | TiKV 调度程序的工作池大小，应在重写情况下增加，同时应小于总 CPU 核心
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tikv.config` 配置：
`[storage]`
`scheduler-worker-pool-size = 4` | `4` | -| `tidb.config` | 配置文件格式的 TiDB 的配置，请参考[配置文件](https://github.com/pingcap/tidb/blob/master/config/config.toml.example)查看默认 TiDB 配置文件（选择对应 TiDB 版本的 tag），可以参考 [TiDB 配置文件描述](/v3.1/reference/configuration/tidb-server/configuration-file.md)查看配置参数的具体介绍（请选择对应的文档版本）。这里只需要**按照配置文件中的格式修改配置**。

以下配置项需要显式配置：

`[performance]`
  `max-procs = 0`
推荐设置：`max-procs` 设置为 `tidb.resources.limits.cpu` 对应的核心数 | TiDB Operator 版本 <= v1.0.0-beta.3，默认值为：
`nil`
TiDB Operator 版本 > v1.0.0-beta.3，默认值为：
`[log]`
`level = "info"`
配置示例：
  `config:` \|
    `[log]`
    `level = "info"` | -| `tidb.replicas` | TiDB 的 Pod 数 | `2` | -| `tidb.image` | TiDB 的镜像 | `pingcap/tidb:v3.0.0-rc.1` | -| `tidb.imagePullPolicy` | TiDB 镜像的拉取策略 | `IfNotPresent` | -| `tidb.logLevel` | TiDB 的日志级别
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[log]`
`level = "info"` | `info` | -| `tidb.resources.limits.cpu` | 每个 TiDB Pod 的 CPU 资源限额 | `nil` | -| `tidb.resources.limits.memory` | 每个 TiDB Pod 的内存资源限额 | `nil` | -| `tidb.resources.requests.cpu` | 每个 TiDB Pod 的 CPU 资源请求 | `nil` | -| `tidb.resources.requests.memory` | 每个 TiDB Pod 的内存资源请求 | `nil` | -| `tidb.passwordSecretName`| 存放 TiDB 用户名及密码的 Secret 的名字，该 Secret 可以使用以下命令创建机密：`kubectl create secret generic tidb secret--from literal=root=--namespace=`，如果没有设置，则 TiDB 根密码为空 | `nil` | -| `tidb.initSql`| 在 TiDB 集群启动成功后，会执行的初始化脚本 | `nil` | -| `tidb.affinity` | `tidb.affinity` 定义 TiDB 的调度规则和偏好，详细请参考：[affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | -| `tidb.nodeSelector` | `tidb.nodeSelector`确保 TiDB Pods 只调度到以该键值对作为标签的节点，详情参考：[nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tidb.tolerations` | `tidb.tolerations` 应用于 TiDB Pods，允许 TiDB Pods 调度到含有指定 taints 的节点上，详情参考：[taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `tidb.annotations` | 为 TiDB Pods 添加特定的 `annotations` | `{}` | -| `tidb.maxFailoverCount` | TiDB 最大的故障转移数量，假设为 3 即最多支持同时 3 个 TiDB 实例故障转移 | `3` | -| `tidb.service.type` | TiDB 服务对外暴露类型 | `NodePort` | -| `tidb.service.externalTrafficPolicy` | 表示此服务是否希望将外部流量路由到节点本地或集群范围的端点。有两个可用选项：`Cluster`（默认）和 `Local`。`Cluster` 隐藏了客户端源 IP，可能导致流量需要二次跳转到另一个节点，但具有良好的整体负载分布。`Local` 保留客户端源 IP 并避免 LoadBalancer 和 NodePort 类型服务流量的第二次跳转，但存在潜在的不均衡流量传播风险。详细参考：[外部负载均衡器](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) | `nil` | -| `tidb.service.loadBalancerIP` | 指定 tidb 负载均衡 IP，某些云提供程序允许您指定loadBalancerIP。在这些情况下，将使用用户指定的loadBalancerIP创建负载平衡器。如果未指定loadBalancerIP字段，则将使用临时IP地址设置loadBalancer。如果指定loadBalancerIP但云提供程序不支持该功能，则将忽略您设置的loadbalancerIP字段 | `nil` | -| `tidb.service.mysqlNodePort` | TiDB 服务暴露的 mysql NodePort 端口 | | -| `tidb.service.exposeStatus` | TiDB 服务是否暴露状态端口 | `true` | -| `tidb.service.statusNodePort` | 指定 TiDB 服务的状态端口暴露的 `NodePort` | | -| `tidb.separateSlowLog` | 是否以 sidecar 方式运行独立容器输出 TiDB 的 SlowLog | 如果 TiDB Operator 版本 <= v1.0.0-beta.3，默认值为 `false`
如果 TiDB Operator 版本 > v1.0.0-beta.3，默认值为 `true` | -| `tidb.slowLogTailer.image` | TiDB 的 slowLogTailer 的镜像，slowLogTailer 是一个 sidecar 类型的容器，用于输出 TiDB 的 SlowLog，该配置仅在 `tidb.separateSlowLog`=`true` 时生效 | `busybox:1.26.2` | -| `tidb.slowLogTailer.resources.limits.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源限额 | `100m` | -| `tidb.slowLogTailer.resources.limits.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源限额 | `50Mi` | -| `tidb.slowLogTailer.resources.requests.cpu` | 每个 TiDB Pod 的 slowLogTailer 的 CPU 资源请求 | `20m` | -| `tidb.slowLogTailer.resources.requests.memory` | 每个 TiDB Pod 的 slowLogTailer 的内存资源请求 | `5Mi` | -| `tidb.plugin.enable` | 是否启用 TiDB 插件功能 | `false` | -| `tidb.plugin.directory` | 指定 TiDB 插件所在的目录 | `/plugins` | -| `tidb.plugin.list` | 指定 TiDB 加载的插件列表，plugin ID 命名规则：插件名-版本，例如：'conn_limit-1' | `[]` | -| `tidb.preparedPlanCacheEnabled` | 是否启用 TiDB 的 prepared plan 缓存
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`enabled = false` | `false` | -| `tidb.preparedPlanCacheCapacity` | TiDB 的 prepared plan 缓存数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[prepared-plan-cache]`
`capacity = 100` | `100` | -| `tidb.txnLocalLatchesEnabled` | 是否启用事务内存锁，当本地事务冲突比较多时建议开启
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`enabled = false` | `false` | -| `tidb.txnLocalLatchesCapacity` | 事务内存锁的容量，Hash 对应的 slot 数，会自动向上调整为 2 的指数倍。每个 slot 占 32 Bytes 内存。当写入数据的范围比较广时（如导数据），设置过小会导致变慢，性能下降。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[txn-local-latches]`
`capacity = 10240000` | `10240000` | -| `tidb.tokenLimit` | TiDB 并发执行会话的限制
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`token-limit = 1000` | `1000` | -| `tidb.memQuotaQuery` | TiDB 查询的内存限额，默认 32GB
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`mem-quota-query = 34359738368` | `34359738368` | -| `tidb.checkMb4ValueInUtf8` | 用于控制当字符集为 utf8 时是否检查 mb4 字符
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`check-mb4-value-in-utf8 = true` | `true` | -| `tidb.treatOldVersionUtf8AsUtf8mb4` | 用于升级兼容性。设置为 `true` 将把旧版本的表/列的 `utf8` 字符集视为 `utf8mb4` 字符集
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`treat-old-version-utf8-as-utf8mb4 = true` | `true` | -| `tidb.lease` | `tidb.lease`是 TiDB Schema lease 的期限，对其更改是非常危险的，除非你明确知道可能产生的结果，否则不建议更改。
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`lease = "45s"` | `45s` | -| `tidb.maxProcs` | 最大可使用的 CPU 核数，0 代表机器/Pod 上的 CPU 数量
如果 TiDB Operator 版本 > v1.0.0-beta.3，请通过 `tidb.config` 配置：
`[performance]`
`max-procs = 0` | `0` | - -## 资源配置说明 - -部署前需要根据实际情况和需求，为 TiDB 集群各个组件配置资源，其中 PD、TiKV、TiDB 是 TiDB 集群的核心服务组件，在生产环境下它们的资源配置还需要按组件要求指定，具体参考：[资源配置推荐](/v3.1/how-to/deploy/hardware-recommendations.md)。 - -为了保证 TiDB 集群的组件在 Kubernetes 中合理的调度和稳定的运行，建议为其设置 Guaranteed 级别的 QoS，通过在配置资源时让 limits 等于 requests 来实现, 具体参考：[配置 QoS](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/)。 - -如果使用 NUMA 架构的 CPU，为了获得更好的性能，需要在节点上开启 `Static` 的 CPU 管理策略。为了 TiDB 集群组件能独占相应的 CPU 资源，除了为其设置上述 Guaranteed 级别的 QoS 外，还需要保证 CPU 的配额必须是大于或等于 1 的整数。具体参考: [CPU 管理策略](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies)。 - -## 容灾配置说明 - -TiDB 是分布式数据库，它的容灾需要做到在任一个物理拓扑节点发生故障时，不仅服务不受影响，还要保证数据也是完整和可用。下面分别具体说明这两种容灾的配置。 - -### TiDB 服务的容灾 - -TiDB 服务容灾本质上基于 Kubernetes 的调度功能来实现的，为了优化调度，TiDB Operator 提供了自定义的调度器，该调度器通过指定的调度算法能在 host 层面，保证 TiDB 服务的容灾，而且目前 TiDB Cluster 使用该调度器作为默认调度器，设置项是上述列表中的 `schedulerName` 配置项。 - -其它层面的容灾（例如 rack，zone，region）是通过 Affinity 的 `PodAntiAffinity` 来保证，通过 `PodAntiAffinity` 能尽量避免同一组件的不同实例部署到同一个物理拓扑节点上，从而达到容灾的目的，Affinity 的使用参考：[Affinity & AntiAffinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity)。 - -下面是一个典型的容灾设置例子： - -{{< copyable "shell-regular" >}} - -```shell -affinity: - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - # this term works when the nodes have the label named region - - weight: 10 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "region" - namespaces: - - - # this term works when the nodes have the label named zone - - weight: 20 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "zone" - namespaces: - - - # this term works when the nodes have the label named rack - - weight: 40 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "rack" - namespaces: - - - # this term works when the nodes have the label named kubernetes.io/hostname - - weight: 80 - podAffinityTerm: - labelSelector: - matchLabels: - app.kubernetes.io/instance: - app.kubernetes.io/component: "pd" - topologyKey: "kubernetes.io/hostname" - namespaces: - - -``` - -### 数据的容灾 - -在开始数据容灾配置前，首先请阅读[集群拓扑信息配置](/v3.1/how-to/deploy/geographic-redundancy/location-awareness.md)。该文档描述了 TiDB 集群数据容灾的实现原理。 - -在 Kubernetes 上支持数据容灾的功能，需要如下操作： - -* 为 PD 设置拓扑位置 Label 集合 - - > **注意：** - > - > 除 `kubernetes.io/hostname` 外，目前 PD 暂不支持名字中带 `/` 的 Label。 - - 用 Kubernetes 集群 Node 节点上描述拓扑位置的 Label 集合替换 `pd.config` 配置项中里的 `location-labels` 信息。 - -* 为 TiKV 节点设置所在的 Node 节点的拓扑信息 - - TiDB Operator 会自动为 TiKV 获取其所在 Node 节点的拓扑信息，并调用 PD 接口将这些信息设置为 TiKV 的 store labels 信息，这样 TiDB 集群就能基于这些信息来调度数据副本。 - - 如果当前 Kubernetes 集群的 Node 节点没有表示拓扑位置的 Label，或者已有的拓扑 Label 名字中带有 `/`，可以通过下面的命令手动给 Node 增加标签： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl label node region= zone= rack= kubernetes.io/hostname= - ``` - - 其中 `region`、`zone`、`rack`、`kubernetes.io/hostname` 只是举例，要添加的 Label 名字和数量可以任意定义，只要符合规范且和 `pd.config` 里的 `location-labels` 设置的 Labels 保持一致即可。 diff --git a/v3.1/tidb-in-kubernetes/reference/configuration/tidb-drainer.md b/v3.1/tidb-in-kubernetes/reference/configuration/tidb-drainer.md deleted file mode 100644 index 029fc22cc1f6..000000000000 --- a/v3.1/tidb-in-kubernetes/reference/configuration/tidb-drainer.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Kubernetes 上的 TiDB Binlog Drainer 配置 -summary: 了解 Kubernetes 上的 TiDB Binlog Drainer 配置 -category: reference ---- - -# Kubernetes 上的 TiDB Binlog Drainer 配置 - -本文档介绍 Kubernetes 上 TiDB Binlog drainer 的配置参数。 - -## 配置参数 - -下表包含所有用于 `tidb-drainer` chart 的配置参数。关于如何配置这些参数，可参阅[使用 Helm](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md#使用-helm)。 - -| 参数 | 说明 | 默认值 | -| :----- | :---- | :----- | -| `clusterName` | 源 TiDB 集群的名称 | `demo` | -| `clusterVersion` | 源 TiDB 集群的版本 | `v3.0.1` | -| `baseImage` | TiDB Binlog 的基础镜像 | `pingcap/tidb-binlog` | -| `imagePullPolicy` | 镜像的拉取策略 | `IfNotPresent` | -| `logLevel` | drainer 进程的日志级别 | `info` | -| `storageClassName` | drainer 所使用的 `storageClass`。`storageClassName` 是 Kubernetes 集群提供的一种存储，可以映射到服务质量级别、备份策略或集群管理员确定的任何策略。详情可参阅 [storage-classes](https://kubernetes.io/docs/concepts/storage/storage-classes) | `local-storage` | -| `storage` | drainer Pod 的存储限制。请注意，如果 `db-type` 设为 `pd`，则应将本参数值设得大一些 | `10Gi` | -| `disableDetect` | 决定是否禁用事故检测 | `false` | -| `initialCommitTs` | 如果 drainer 没有断点，则用于初始化断点 | `0` | -| `config` | 传递到 drainer 的配置文件。详情可参阅 [drainer.toml](https://github.com/pingcap/tidb-binlog/blob/master/cmd/drainer/drainer.toml) |（见下文）| -| `resources` | drainer Pod 的资源限制和请求 | `{}` | -| `nodeSelector` | 确保 drainer Pod 仅被调度到具有特定键值对作为标签的节点上。详情可参阅 [nodeselector](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#nodeselector) | `{}` | -| `tolerations` | 适用于 drainer Pod，允许将 Pod 调度到有指定 taint 的节点上。详情可参阅 [taint-and-toleration](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration) | `{}` | -| `affinity` | 定义 drainer Pod 的调度策略和首选项。详情可参阅 [affinity-and-anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-Pod-node/#affinity-and-anti-affinity) | `{}` | - -`config` 的默认值为： - -```toml -detect-interval = 10 -compressor = "" -[syncer] -worker-count = 16 -disable-dispatch = false -ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql" -safe-mode = false -txn-batch = 20 -db-type = "file" -[syncer.to] -dir = "/data/pb" -``` diff --git a/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md b/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md deleted file mode 100644 index b22180ae2e6a..000000000000 --- a/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 工具指南 -category: reference ---- - -# Kubernetes 上的 TiDB 工具指南 - -Kubernetes 上的 TiDB 运维管理需要使用一些开源工具。同时，在 Kubernetes 上使用 TiDB 生态工具时，也有特殊的操作要求。本文档详细描述 Kubernetes 上的 TiDB 相关的工具及其使用方法。 - -## 在 Kubernetes 上使用 PD Control - -[PD Control](/v3.1/reference/tools/pd-control.md) 是 PD 的命令行工具，在使用 PD Control 操作 Kubernetes 上的 TiDB 集群时，需要先使用 `kubectl port-forward` 打开本地到 PD 服务的连接： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & -``` - -执行上述命令后，就可以通过 `127.0.0.1:2379` 访问到 PD 服务，从而直接使用 `pd-ctl` 命令的默认参数执行操作，如： - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -d config show -``` - -假如你本地的 2379 被占据，则需要选择其它端口： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & -``` - -此时，需要为 `pd-ctl` 命令显式指定 PD 端口： - -{{< copyable "shell-regular" >}} - -```shell -pd-ctl -u 127.0.0.1: -d config show -``` - -## 在 Kubernetes 上使用 TiKV Control - -[TiKV Control](/v3.1/reference/tools/tikv-control.md) 是 TiKV 的命令行工具。在使用 TiKV Control 操作 Kubernetes 上的 TiDB 集群时，针对 TiKV Control 的不同操作模式，有不同的操作步骤。 - -* **远程模式**：此模式下 `tikv-ctl` 命令需要通过网络访问 TiKV 服务或 PD 服务，因此需要先使用 `kubectl port-forward` 打开本地到 PD 服务以及目标 TiKV 节点的连接： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & - ``` - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n 20160:20160 &>/tmp/portforward-tikv.log & - ``` - - 打开连接后，即可通过本地的对应端口访问 PD 服务和 TiKV 节点： - - {{< copyable "shell-regular" >}} - - ```shell - $ tikv-ctl --host 127.0.0.1:20160 - ``` - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --pd 127.0.0.1:2379 compact-cluster - ``` - -* **本地模式**：本地模式需要访问 TiKV 的数据文件，并且需要停止正在运行的 TiKV 实例。需要先使用[诊断模式](/v3.1/tidb-in-kubernetes/troubleshoot.md#诊断模式)关闭 TiKV 实例自动重启，关闭 TiKV 进程，再使用 `tkctl debug` 命令在目标 TiKV Pod 中启动一个包含 `tikv-ctl` 可执行文件的新容器来执行操作，步骤如下： - - 1. 进入诊断模式： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl annotate pod -n runmode=debug - ``` - - 2. 关闭 TiKV 进程： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl exec -n -c tikv -- kill -s TERM 1 - ``` - - 3. 启动 debug 容器： - - {{< copyable "shell-regular" >}} - - ```shell - tkctl debug -c tikv - ``` - - 4. 开始使用 `tikv-ctl` 的本地模式，需要注意的是 `tikv` 容器的根文件系统在 `/proc/1/root` 下，因此执行命令时也需要调整数据目录的路径： - - {{< copyable "shell-regular" >}} - - ```shell - tikv-ctl --db /path/to/tikv/db size -r 2 - ``` - - Kubernetes 上 TiKV 实例在 debug 容器中的的默认 db 路径是 `/proc/1/root/var/lib/tikv/db size -r 2` - -## 在 Kubernetes 上使用 TiDB Control - -[TiDB Control](/v3.1/reference/tools/tidb-control.md) 是 TiDB 的命令行工具，使用 TiDB Control 时，需要从本地访问 TiDB 节点和 PD 服务，因此建议使用 `kubectl port-forward` 打开到集群中 TiDB 节点和 PD 服务的连接： - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n svc/-pd 2379:2379 &>/tmp/portforward-pd.log & -``` - -{{< copyable "shell-regular" >}} - -```shell -kubectl port-forward -n 10080:10080 &>/tmp/portforward-tidb.log & -``` - -接下来便可开始使用 `tidb-ctl` 命令： - -{{< copyable "shell-regular" >}} - -```shell -tidb-ctl schema in mysql -``` - -## 使用 Helm - -[Helm](https://helm.sh/) 是一个 Kubernetes 的包管理工具，你可以参考 [Helm 官方文档](https://github.com/helm/helm#install) 安装 Helm，步骤如下： - -1. 安装 Helm 客户端 - - {{< copyable "shell-regular" >}} - - ```shell - curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash - ``` - - 如果使用 macOS，可以通过 homebrew 安装 Helm：`brew install kubernetes-helm`。 - -2. 安装 Helm 服务端 - - {{< copyable "shell-regular" >}} - - 在集群中应用 helm 服务端组件 `tiller` 所需的 `RBAC` 规则并安装 `tiller`： - - ```shell - kubectl apply -f https://raw.githubusercontent.com/pingcap/tidb-operator/master/manifests/tiller-rbac.yaml && \ - helm init --service-account=tiller --upgrade - ``` - - 通过下面命令确认 `tiller` Pod 进入 running 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l name=tiller - ``` - - 如果 Kubernetes 集群没有启用 `RBAC`，那么可以直接使用下列命令安装 `tiller`： - - {{< copyable "shell-regular" >}} - - ```shell - helm init --upgrade - ``` - -Kubernetes 应用在 helm 中被打包为 chart。PingCAP 针对 Kubernetes 上的 TiDB 部署运维提供了三个 Helm chart： - -* `tidb-operator`：用于部署 TiDB Operator； -* `tidb-cluster`：用于部署 TiDB 集群； -* `tidb-backup`：用于 TiDB 集群备份恢复； - -这些 chart 都托管在 PingCAP 维护的 helm chart 仓库 `https://charts.pingcap.org/` 中，你可以通过下面的命令添加该仓库： - -{{< copyable "shell-regular" >}} - -```shell -helm repo add pingcap https://charts.pingcap.org/ -``` - -添加完成后，可以使用 `helm search` 搜索 PingCAP 提供的 chart： - -{{< copyable "shell-regular" >}} - -```shell -helm search pingcap -l -``` - -``` -NAME CHART VERSION APP VERSION DESCRIPTION -pingcap/tidb-backup v1.0.0 A Helm chart for TiDB Backup or Restore -pingcap/tidb-cluster v1.0.0 A Helm chart for TiDB Cluster -pingcap/tidb-operator v1.0.0 tidb-operator Helm chart for Kubernetes -``` - -当新版本的 chart 发布后，你可以使用 `helm repo update` 命令更新本地对于仓库的缓存： - -{{< copyable "shell-regular" >}} - -``` -helm repo update -``` - -Helm 的常用操作有部署（`helm install`）、升级（`helm upgrade`)、销毁（`helm del`)、查询（`helm ls`）。Helm chart 往往都有很多可配置参数，通过命令行进行配置比较繁琐，因此推荐使用 YAML 文件的形式来编写这些配置项，基于 Helm 社区约定俗称的命名方式，我们在文档中将用于配置 chart 的 YAML 文件称为 `values.yaml` 文件。 - -执行部署、升级、销毁等操作前，可以使用 `helm ls` 查看集群中已部署的应用： - -{{< copyable "shell-regular" >}} - -```shell -helm ls -``` - -在执行部署和升级操作时，必须指定使用的 chart 名字（`chart-name`）和部署后的应用名（`release-name`），还可以指定一个或多个 `values.yaml` 文件来配置 chart。此外，假如对 chart 有特定的版本需求，则需要通过 `--version` 参数指定 `chart-version` (默认为最新的 GA 版本）。命令形式如下： - -* 执行安装： - - {{< copyable "shell-regular" >}} - - ```shell - helm install --name= --namespace= --version= -f - ``` - -* 执行升级（升级可以是修改 `chart-version` 升级到新版本的 chart，也可以是修改 `values.yaml` 文件更新应用配置）： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade --version= -f - ``` - -最后，假如要删除 helm 部署的应用，可以执行： - -{{< copyable "shell-regular" >}} - -```shell -helm del --purge -``` - -更多 helm 的相关文档，请参考 [Helm 官方文档](https://helm.sh/docs/)。 - -## 使用 Terraform - -[Terraform](https://www.terraform.io/) 是一个基础设施即代码（Infrastructure as Code）管理工具。它允许用户使用声明式的风格描述自己的基础设施，并针对描述生成执行计划来创建或调整真实世界的计算资源。Kubernetes 上的 TiDB 使用 Terraform 来在公有云上创建和管理 TiDB 集群。 - -你可以参考 [Terraform 官方文档](https://www.terraform.io/downloads.html) 来安装 Terraform。 diff --git a/v3.1/tidb-in-kubernetes/reference/tools/tkctl.md b/v3.1/tidb-in-kubernetes/reference/tools/tkctl.md deleted file mode 100644 index 3071f8abc7bd..000000000000 --- a/v3.1/tidb-in-kubernetes/reference/tools/tkctl.md +++ /dev/null @@ -1,395 +0,0 @@ ---- -title: tkctl 使用指南 -category: reference ---- - -# tkctl 使用指南 - -`tkctl` (TiDB Kubernetes Control) 是为 TiDB in Kubernetes 设计的命令行工具，用于运维集群和诊断集群问题。 - -## 安装 - -安装 `tkctl` 时，可以直接下载预编译的可执行文件，也可以自行从源码进行编译。 - -### 下载预编译的可执行文件 - -- [MacOS](https://download.pingcap.org/tkctl-darwin-amd64-latest.tgz) -- [Linux](https://download.pingcap.org/tkctl-linux-amd64-latest.tgz) -- [Windows](https://download.pingcap.org/tkctl-windows-amd64-latest.tgz) - -下载解压后，将 `tkctl` 可执行文件加入到可执行文件路径 (`PATH`) 中即完成安装。 - -### 源码编译 - -要求：[Go](https://golang.org/) 版本 1.11 及以上 - -{{< copyable "shell-regular" >}} - -```shell -git clone https://github.com/pingcap/tidb-operator.git && \ -GOOS=${YOUR_GOOS} make cli && \ -mv tkctl /usr/local/bin/tkctl -``` - -## 命令自动补全 - -你可以配置 `tkctl` 的自动补全以简化使用。 - -为 BASH 配置自动补全（需要预先安装 [bash-completion](https://github.com/scop/bash-completion)）的方法如下。 - -在当前 shell 中设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -source <(tkctl completion bash) -``` - -永久设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -echo "if hash tkctl 2>/dev/null; then source <(tkctl completion bash); fi" >> ~/.bashrc -``` - -为 ZSH 配置自动补全的方法如下。 - -在当前 shell 中设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -source <(tkctl completion zsh) -``` - -永久设置自动补全： - -{{< copyable "shell-regular" >}} - -```shell -echo "if hash tkctl 2>/dev/null; then source <(tkctl completion zsh); fi" >> ~/.zshrc -``` - -## Kubernetes 配置 - -`tkctl` 复用了 `kubeconfig` 文件（默认位置是 `~/.kube/config`）来连接 Kubernetes 集群。你可以通过下面的命令来验证 `kubeconfig` 是否设置正确： - -{{< copyable "shell-regular" >}} - -```shell -tkctl version -``` - -假如上面的命令正确输出服务端的 TiDB Operator 版本，则 `kubeconfig` 配置正确。 - -## 所有命令 - -### tkctl version - -该命令用于展示本地 **tkctl** 和集群中 **tidb-operator** 的版本： - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl version -``` - -``` -Client Version: v1.0.0-beta.1-p2-93-g6598b4d3e75705-dirty -TiDB Controller Manager Version: pingcap/tidb-operator:latest -TiDB Scheduler Version: pingcap/tidb-operator:latest -``` - -### tkctl list - -该命令用于列出所有已安装的 TiDB 集群： - -| 参数 | 缩写 | 说明 | -| ----- | --------- | ----------- | -| --all-namespaces | -A | 是否查询所有的 Kubernetes Namespace | -| --output | -o | 输出格式，可选值有 [default,json,yaml]，默认值为 `default` | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl list -A -``` - -``` -NAMESPACE NAME PD TIKV TIDB AGE -foo demo-cluster 3/3 3/3 2/2 11m -bar demo-cluster 3/3 3/3 1/2 11m -``` - -### tkctl use - -该命令用于指定当前 `tkctl` 操作的 TiDB 集群，在使用该命令设置当前操作的 TiDB 集群后，所有针对集群的操作命令会自动选定该集群，从而可以略去 `--tidbcluster` 参数。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl use --namespace=foo demo-cluster -``` - -``` -Tidb cluster switched to foo/demo-cluster -``` - -### tkctl info - -该命令用于展示 TiDB 集群的信息。 - -| 参数 | 缩写 | 说明 | -| ----- | --------- | ----------- | -| --tidb-cluster | -t | 指定 TiDB 集群，默认为当前使用的 TiDB 集群 | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl info -``` - -``` -Name: demo-cluster -Namespace: foo -CreationTimestamp: 2019-04-17 17:33:41 +0800 CST -Overview: - Phase Ready Desired CPU Memory Storage Version - ----- ----- ------- --- ------ ------- ------- - PD: Normal 3 3 200m 1Gi 1Gi pingcap/pd:v3.0.0-rc.1 - TiKV: Normal 3 3 1000m 2Gi 10Gi pingcap/tikv:v3.0.0-rc.1 - TiDB Upgrade 1 2 500m 1Gi pingcap/tidb:v3.0.0-rc.1 -Endpoints(NodePort): - - 172.16.4.158:31441 - - 172.16.4.155:31441 -``` - -### tkctl get [component] - -该命令用于获取 TiDB 集群中组件的详细信息。 - -可选的组件 (`component`) 有： `pd`、`tikv`、`tidb`、`volume` 和 `all`（用于同时查询所有组件）。 - -| 参数 | 缩写 | 说明 | -| ----- | --------- | ----------- | -| --tidb-cluster | -t | 指定 TiDB 集群，默认为当前使用的 TiDB 集群 | -| --output | -o | 输出格式，可选值有 `default`、`json` 和 `yaml`，默认值为 `default` | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl get tikv -``` - -``` -NAME READY STATUS MEMORY CPU RESTARTS AGE NODE -demo-cluster-tikv-0 2/2 Running 2098Mi/4196Mi 2/2 0 3m19s 172.16.4.155 -demo-cluster-tikv-1 2/2 Running 2098Mi/4196Mi 2/2 0 4m8s 172.16.4.160 -demo-cluster-tikv-2 2/2 Running 2098Mi/4196Mi 2/2 0 4m45s 172.16.4.157 -``` - -{{< copyable "shell-regular" >}} - -```shell -tkctl get volume -``` - -``` -VOLUME CLAIM STATUS CAPACITY NODE LOCAL -local-pv-d5dad2cf tikv-demo-cluster-tikv-0 Bound 1476Gi 172.16.4.155 /mnt/disks/local-pv56 -local-pv-5ade8580 tikv-demo-cluster-tikv-1 Bound 1476Gi 172.16.4.160 /mnt/disks/local-pv33 -local-pv-ed2ffe50 tikv-demo-cluster-tikv-2 Bound 1476Gi 172.16.4.157 /mnt/disks/local-pv13 -local-pv-74ee0364 pd-demo-cluster-pd-0 Bound 1476Gi 172.16.4.155 /mnt/disks/local-pv46 -local-pv-842034e6 pd-demo-cluster-pd-1 Bound 1476Gi 172.16.4.158 /mnt/disks/local-pv74 -local-pv-e54c122a pd-demo-cluster-pd-2 Bound 1476Gi 172.16.4.156 /mnt/disks/local-pv72 -``` - -### tkctl debug [pod_name] - -该命令用于诊断 TiDB 集群中的 Pod。 - -实际使用时，该命令会在目标 Pod 的宿主机上以指定镜像启动一个 debug 容器，该容器会与目标 Pod 中的容器共享 namespace，因此可以无缝使用 debug 容器中的各种工具对目标容器进行诊断。 - -| 参数 | 缩写 | 描述 | -| ----- | --------- | ----------- | -| --image | | 指定 debug 容器使用的镜像，默认为 `pingcap/tidb-debug:latest` | -| --container | -c | 选择需要诊断的容器，默认为 Pod 定义中的第一个容器 | -| --docker-socket | | 指定目标节点上的 Docker Socket，默认为 `/var/run/docker.sock` | -| --privileged | | 是否为 debug 容器开启 [privileged](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) 模式 | - -> **注意：** -> -> Debug 容器使用的默认镜像包含了绝大多数的诊断工具，因此体积较大，假如只需要 `pd-ctl` 和 `tidb-ctl`，可以使用 `--image=pingcap/tidb-control:latest` 来指定使用 `tidb-control` 镜像。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl debug demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -ps -ef -``` - -由于 debug 容器和目标容器拥有不同的根文件系统，在 `tidb-debug` 容器中使用 GDB 和 perf 等工具时可能会碰到一些问题，下面将补充说明如何解决这些问题。 - -#### GDB - -使用 GDB 调试目标容器中的进程时，需要将 `program` 参数设置为目标容器中的可执行文件。假如是在 `tidb-debug` 以外的其它 debug 容器中进行调试，或者调试的目标进行 pid 不为 1，则需要使用 `set sysroot` 命令调整动态链接库的加载位置。操作如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl debug demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -gdb /proc/${pid:-1}/root/tikv-server 1 -``` - -`tidb-debug` 中预配置的 `.gdbinit` 会将 `sysroot` 设置为 `/proc/1/root/`，因此在 `tidb-debug` 中，假如目标容器的 pid 为 1，则下面的命令可以省略。 - -{{< copyable "shell-regular" >}} - -```shell -(gdb) set sysroot /proc/${pid}/root/ -``` - -开始调试： - -{{< copyable "shell-regular" >}} - -```shell -(gdb) thread apply all bt -``` - -{{< copyable "shell-regular" >}} - -```shell -(gdb) info threads -``` - -#### Perf 以及火焰图 - -使用 `perf` 命令和 `run-flamegraph.sh` 脚本时，需要将目标容器的可执行文件拷贝到 Debug 容器中： - -{{< copyable "shell-regular" >}} - -```shell -tkctl debug demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -cp /proc/1/root/tikv-server / -``` - -{{< copyable "shell-regular" >}} - -```shell -./run_flamegraph.sh 1 -``` - -该脚本会自动将生成的火焰图（SVG 格式）上传至 transfer.sh，通过访问脚本输出的链接即可下载火焰图。 - -### tkctl ctop - -命令的完整形式：`tkctl ctop [pod_name | node/node_name ]`。 - -该命令用于查看集群中 Pod 或 Node 的实时监控信息，和 `kubectl top` 相比，`tkctl ctop` 还会展示网络和磁盘的使用信息。 - -| 参数 | 简写 | 描述 | -| ----- | --------- | ----------- | -| --image | | 指定 ctop 的镜像，默认为 `quay.io/vektorlab/ctop:0.7.2` | -| --docker-socket | | 指定 ctop 使用的 Docker Socket，默认为 `/var/run/docker.sock` | - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl ctop demo-cluster-tikv-0 -``` - -{{< copyable "shell-regular" >}} - -```shell -tkctl ctop node/172.16.4.155 -``` - -### tkctl help [command] - -该命令用于展示各个子命令的帮助信息。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl help debug -``` - -### tkctl options - -该命令用于展示 `tkctl` 的所有的全局参数。 - -示例如下： - -{{< copyable "shell-regular" >}} - -```shell -tkctl options -``` - -``` -The following options can be passed to any command: - - --alsologtostderr=false: log to standard error as well as files - --as='': Username to impersonate for the operation - --as-group=[]: Group to impersonate for the operation, this flag can be repeated to specify multiple groups. - --cache-dir='/Users/alei/.kube/http-cache': Default HTTP cache directory - --certificate-authority='': Path to a cert file for the certificate authority - --client-certificate='': Path to a client certificate file for TLS - --client-key='': Path to a client key file for TLS - --cluster='': The name of the kubeconfig cluster to use - --context='': The name of the kubeconfig context to use - --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will -make your HTTPS connections insecure - --kubeconfig='': Path to the kubeconfig file to use for CLI requests. - --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace - --log_dir='': If non-empty, write log files in this directory - --logtostderr=true: log to standard error instead of files - -n, --namespace='': If present, the namespace scope for this CLI request - --request-timeout='0': The length of time to wait before giving up on a single server request. Non-zero values -should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. - -s, --server='': The address and port of the Kubernetes API server - --stderrthreshold=2: logs at or above this threshold go to stderr - -t, --tidbcluster='': Tidb cluster name - --token='': Bearer token for authentication to the API server - --user='': The name of the kubeconfig user to use - -v, --v=0: log level for V logs - --vmodule=: comma-separated list of pattern=N settings for file-filtered logging -``` - -这些参数主要用于指定如何连接 Kubernetes 集群，其中最常用的参数是： - -- `--context`：指定目标 Kubernetes 集群 -- `--namespace`：指定 Namespace diff --git a/v3.1/tidb-in-kubernetes/scale-in-kubernetes.md b/v3.1/tidb-in-kubernetes/scale-in-kubernetes.md deleted file mode 100644 index 5ff69f9143ea..000000000000 --- a/v3.1/tidb-in-kubernetes/scale-in-kubernetes.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群扩缩容 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群扩缩容 - -本文介绍 TiDB 在 Kubernetes 中如何进行水平扩缩容和垂直扩缩容。 - -## 水平扩缩容 - -TiDB 水平扩缩容操作指的是通过增加或减少节点的数量，来达到集群扩缩容的目的。扩缩容 TiDB 集群时，会按照填入的 replicas 值，对 PD、TiKV、TiDB 进行顺序扩缩容操作。扩容操作按照节点编号由小到大增加节点，缩容操作按照节点编号由大到小删除节点。 - -### 水平扩缩容操作 - -1. 修改集群的 `value.yaml` 文件中的 `pd.replicas`、`tidb.replicas`、`tikv.replicas` 至期望值。 - -2. 执行 `helm upgrade` 命令进行扩缩容： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看集群水平扩缩容状态： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有组件的 Pod 数量都达到了预设值，并且都进入 `Running` 状态后，水平扩缩容完成。 - -> **注意：** -> -> - PD、TiKV 组件在滚动升级的过程中不会触发扩缩容操作。 -> - TiKV 组件在缩容过程中会调用 PD 接口将对应 TiKV 标记为下线，然后将其上数据迁移到其它 TiKV 节点，在数据迁移期间 TiKV Pod 依然是 `Running` 状态，数据迁移完成后对应 Pod 才会被删除，缩容时间与待缩容的 TiKV 上的数据量有关，可以通过 `kubectl get tidbcluster -n -o json | jq '.status.tikv.stores'` 查看 TiKV 是否处于下线 `Offline` 状态。 -> - PD、TiKV 组件在缩容过程中被删除的节点的 PVC 会保留，并且由于 PV 的 `Reclaim Policy` 设置为 `Retain`，即使 PVC 被删除，数据依然可以找回。 -> - TiKV 组件不支持在缩容未完成时进行扩容操作，强制执行此操作可能导致集群状态异常。假如异常已经发生，可以参考 [TiKV Store 异常进入 Tombstone 状态](/v3.1/tidb-in-kubernetes/troubleshoot.md#tikv-store-异常进入-tombstone-状态) 进行解决。 - -## 垂直扩缩容 - -垂直扩缩容操作指的是通过增加或减少节点的资源限制，来达到集群扩缩容的目的。垂直扩缩容本质上是节点滚动升级的过程。 - -### 垂直扩缩容操作 - -1. 修改 `values.yaml` 文件中的 `tidb.resources`、`tikv.resources`、`pd.resources` 至期望值。 - -2. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，垂直扩缩容完成。 - -> **注意：** -> -> - 如果在垂直扩容时修改了资源的 `requests` 字段，由于 PD、TiKV 使用了 `Local PV`，升级后还需要调度回原节点，如果原节点资源不够，则会导致 Pod 一直处于 `Pending` 状态而影响服务。 -> - TiDB 作为一个可水平扩展的数据库，推荐通过增加节点个数发挥 TiDB 集群可水平扩展的优势，而不是类似传统数据库升级节点硬件配置来实现垂直扩容。 diff --git a/v3.1/tidb-in-kubernetes/tidb-operator-overview.md b/v3.1/tidb-in-kubernetes/tidb-operator-overview.md deleted file mode 100644 index 035aa5447abe..000000000000 --- a/v3.1/tidb-in-kubernetes/tidb-operator-overview.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: TiDB Operator 简介 -category: reference ---- - -# TiDB Operator 简介 - -TiDB Operator 是 Kubernetes 上的 TiDB 集群自动运维系统，提供包括部署、升级、扩缩容、备份恢复、配置变更的 TiDB 全生命周期管理。借助 TiDB Operator，TiDB 可以无缝运行在公有云或私有部署的 Kubernetes 集群上。 - -> **注意：** -> -> 每个 Kubernetes 集群中只能部署一个 TiDB Operator。 - -## TiDB Operator 整体架构 - -![TiDB Operator Overview](/media/tidb-operator-overview.png) - -其中，`TidbCluster` 是由 CRD（`CustomResourceDefinition`）定义的自定义资源，用于描述用户期望的 TiDB 集群状态。TiDB 集群的编排和调度逻辑则由下列组件负责： - -* `tidb-controller-manager` 是一组 Kubernetes 上的自定义控制器。这些控制器会不断对比 `TidbCluster` 对象中记录的期望状态与 TiDB 集群的实际状态，并调整 Kubernetes 中的资源以驱动 TiDB 集群满足期望状态； -* `tidb-scheduler` 是一个 Kubernetes 调度器扩展，它为 Kubernetes 调度器注入 TiDB 集群特有的调度逻辑。 - -此外，TiDB Operator 还提供了命令行接口 `tkctl` 用于运维集群和诊断集群问题。 - -![TiDB Operator Control Flow](/media/tidb-operator-control-flow.png) - -上图是 TiDB Operator 的控制流程解析。由于 TiDB 集群还需要监控、初始化、定时备份、Binlog 等组件，TiDB Operator 中使用 Helm Chart 封装了 TiDB 集群定义。整体的控制流程如下： - -1. 用户通过 Helm 创建 `TidbCluster` 对象和相应的一系列 Kubernetes 原生对象，比如执行定时备份的 `CronJob`； -2. TiDB Operator 会 watch `TidbCluster` 以及其它相关对象，基于集群的实际状态不断调整 PD、TiKV、TiDB 的 `StatefulSet` 和 `Service` 对象； -3. Kubernetes 的原生控制器根据 `StatefulSet`、`Deployment`、`CronJob` 等对象创建更新或删除对应的 `Pod`； -4. PD、TiKV、TiDB 的 `Pod` 声明中会指定使用 `tidb-scheduler` 调度器，`tidb-scheduler` 会在调度对应 `Pod` 时应用 TiDB 的特定调度逻辑。 - -基于上述的声明式控制流程，TiDB Operator 能够自动进行集群节点健康检查和故障恢复。部署、升级、扩缩容等操作也可以通过修改 `TidbCluster` 对象声明“一键”完成。 - -## 使用 TiDB Operator 管理 TiDB 集群 - -TiDB Operator 提供了多种方式来部署 Kubernetes 上的 TiDB 集群： - -+ 测试环境： - - [kind](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md)：采用 [kind](https://kind.sigs.k8s.io/) 方式在本地 Kubernetes 集群上部署 TiDB 集群； - - [Minikube](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md)：使用 TiDB Operator 在本地 Minikube 环境部署 TiDB 集群； - - [GKE](/v3.1/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md)：使用 TiDB Operator 在 GKE 上部署 TiDB 集群。 - -+ 生产环境： - - - 公有云：参考 [AWS 部署文档](/v3.1/tidb-in-kubernetes/deploy/aws-eks.md)，[GKE 部署文档 (beta)](/v3.1/tidb-in-kubernetes/deploy/gcp-gke.md)，或[阿里云部署文档](/v3.1/tidb-in-kubernetes/deploy/alibaba-cloud.md)在对应的公有云上一键部署生产可用的 TiDB 集群并进行后续的运维管理； - - - 现有 Kubernetes 集群：首先按照[部署 TiDB Operator](/v3.1/tidb-in-kubernetes/deploy/tidb-operator.md)在集群中安装 TiDB Operator，再根据[在标准 Kubernetes 集群上部署 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md)来部署你的 TiDB 集群。对于生产级 TiDB 集群，你还需要参考 [TiDB 集群环境要求](/v3.1/tidb-in-kubernetes/deploy/prerequisites.md)调整 Kubernetes 集群配置并根据[本地 PV 配置](/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)为你的 Kubernetes 集群配置本地 PV，以满足 TiKV 的低延迟本地存储需求。 - -在任何环境上部署前，都可以参考 [TiDB 集群配置](/v3.1/tidb-in-kubernetes/reference/configuration/tidb-cluster.md)来自定义 TiDB 配置。 - -部署完成后，你可以参考下面的文档进行 Kubernetes 上 TiDB 集群的使用和运维： - -+ [部署 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/general-kubernetes.md) -+ [访问 TiDB 集群](/v3.1/tidb-in-kubernetes/deploy/access-tidb.md) -+ [TiDB 集群扩缩容](/v3.1/tidb-in-kubernetes/scale-in-kubernetes.md) -+ [TiDB 集群升级](/v3.1/tidb-in-kubernetes/upgrade/tidb-cluster.md#升级-tidb-版本) -+ [TiDB 集群配置变更](/v3.1/tidb-in-kubernetes/upgrade/tidb-cluster.md#更新-tidb-集群配置) -+ [TiDB 集群备份恢复](/v3.1/tidb-in-kubernetes/maintain/backup-and-restore.md) -+ [配置 TiDB 集群故障自动转移](/v3.1/tidb-in-kubernetes/maintain/auto-failover.md) -+ [监控 TiDB 集群](/v3.1/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) -+ [TiDB 集群日志收集](/v3.1/tidb-in-kubernetes/maintain/log-collecting.md) -+ [维护 TiDB 所在的 Kubernetes 节点](/v3.1/tidb-in-kubernetes/maintain/kubernetes-node.md) - -当集群出现问题需要进行诊断时，你可以： - -+ 查阅 [Kubernetes 上的 TiDB FAQ](/v3.1/tidb-in-kubernetes/faq.md) 寻找是否存在现成的解决办法； -+ 参考 [Kubernetes 上的 TiDB 故障诊断](/v3.1/tidb-in-kubernetes/troubleshoot.md)解决故障。 - -Kubernetes 上的 TiDB 提供了专用的命令行工具 `tkctl` 用于集群管理和辅助诊断，同时，在 Kubernetes 上，TiDB 的部分生态工具的使用方法也有所不同，你可以： - -+ 参考 [`tkctl` 使用指南](/v3.1/tidb-in-kubernetes/reference/tools/tkctl.md) 来使用 `tkctl`； -+ 参考 [Kubernetes 上的 TiDB 相关工具使用指南](/v3.1/tidb-in-kubernetes/reference/tools/in-kubernetes.md)来了解 TiDB 生态工具在 Kubernetes 上的使用方法。 - -最后，当 TiDB Operator 发布新版本时，你可以参考[升级 TiDB Operator](/v3.1/tidb-in-kubernetes/upgrade/tidb-operator.md) 进行版本更新。 diff --git a/v3.1/tidb-in-kubernetes/troubleshoot.md b/v3.1/tidb-in-kubernetes/troubleshoot.md deleted file mode 100644 index e0e6f1da8af7..000000000000 --- a/v3.1/tidb-in-kubernetes/troubleshoot.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: Kubernetes 上的 TiDB 集群故障诊断 -category: how-to ---- - -# Kubernetes 上的 TiDB 集群故障诊断 - -本文介绍了 Kubernetes 上 TiDB 集群的一些常见故障以及诊断解决方案。 - -## 诊断模式 - -当 Pod 处于 `CrashLoopBackoff` 状态时，Pod 内会容器不断退出，导致无法正常使用 `kubectl exec` 或 `tkctl debug`，给诊断带来不便。为了解决这个问题，TiDB in Kubernetes 提供了 PD/TiKV/TiDB Pod 诊断模式。在诊断模式下，Pod 内的容器启动后会直接挂起，不会再进入重复 Crash 的状态，此时，便可以通过 `kubectl exec` 或 `tkctl debug` 连接 Pod 内的容器进行诊断。 - -操作方式： - -首先，为待诊断的 Pod 添加 Annotation： - -{{< copyable "shell-regular" >}} - -```shell -kubectl annotate pod -n runmode=debug -``` - -在 Pod 内的容器下次重启时，会检测到该 Annotation，进入诊断模式。等待 Pod 进入 Running 状态即可开始诊断： - -{{< copyable "shell-regular" >}} - -```shell -watch kubectl get pod -n -``` - -下面是使用 `kubectl exec` 进入容器进行诊断工作的例子： - -{{< copyable "shell-regular" >}} - -```shell -kubectl exec -it -n -- /bin/sh -``` - -诊断完毕，修复问题后，删除 Pod： - -```shell -kubectl delete pod -n -``` - -Pod 重建后会自动回到正常运行模式。 - -## 集群意外删除后恢复 - -TiDB Operator 使用 PV (Persistent Volume)、PVC (Persistent Volume Claim) 来存储持久化的数据，如果不小心使用 `helm delete` 意外删除了集群，PV/PVC 对象以及数据都会保留下来，以最大程度保证数据安全。 - -此时集群恢复的办法就是使用 `helm install` 命令来创建一个同名的集群，之前保留下来未被删除的 PV/PVC 以及数据会被复用： - -{{< copyable "shell-regular" >}} - -```shell -helm install pingcap/tidb-cluster -n --namespace= --version= -f values.yaml -``` - -## Pod 未正常创建 - -通过 `helm install` 创建集群后，如果 Pod 没有创建，则可以通过以下方式进行诊断： - -{{< copyable "shell-regular" >}} - -```shell -kubectl get tidbclusters -n -kubectl get statefulsets -n -kubectl describe statefulsets -n -pd -``` - -## Pod 之间网络不通 - -针对 TiDB 集群而言，绝大部分 Pod 间的访问均通过 Pod 的域名（使用 Headless Service 分配）进行，例外的情况是 TiDB Operator 在收集集群信息或下发控制指令时，会通过 PD Service 的 `service-name` 访问 PD 集群。 - -当通过日志或监控确认 Pod 间存在网络连通性问题，或根据故障情况推断出 Pod 间网络连接可能不正常时，可以按照下面的流程进行诊断，逐步缩小问题范围： - -1. 确认 Service 和 Headless Service 的 Endpoints 是否正常： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl -n get endpoints -pd - kubectl -n get endpoints -tidb - kubectl -n get endpoints -pd-peer - kubectl -n get endpoints -tikv-peer - kubectl -n get endpoints -tidb-peer - ``` - - 以上命令展示的 `ENDPOINTS` 字段中，应当是由逗号分隔的 `cluster_ip:port` 列表。假如字段为空或不正确，请检查 Pod 的健康状态以及 `kube-controller-manager` 是否正常工作。 - -2. 进入 Pod 的 Network Namespace 诊断网络问题： - - {{< copyable "shell-regular" >}} - - ``` - tkctl debug -n - ``` - - 远端 shell 启动后，使用 `dig` 命令诊断 DNS 解析，假如 DNS 解析异常，请参照[诊断 Kubernetes DNS 解析](https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/)进行故障排除： - - {{< copyable "shell-regular" >}} - - ```shell - dig - ``` - - 使用 `ping` 命令诊断到目的 IP 的三层网络是否连通（目的 IP 为使用 `dig` 解析出的 ClusterIP）: - - {{< copyable "shell-regular" >}} - - ```shell - ping - ``` - - 假如 ping 检查失败，请参照[诊断 Kubernetes 网络](https://www.praqma.com/stories/debugging-kubernetes-networking/)进行故障排除。 - - 假如 ping 检查正常，继续使用 `telnet` 检查目标端口是否打开： - - {{< copyable "shell-regular" >}} - - ```shell - telnet - ``` - - 假如 `telnet` 检查失败，则需要验证 Pod 的对应端口是否正确暴露以及应用的端口是否配置正确： - - {{< copyable "shell-regular" >}} - - ```shell - # 检查端口是否一致 - kubectl -n get po -ojson | jq '.spec.containers[].ports[].containerPort' - - # 检查应用是否被正确配置服务于指定端口上 - # PD, 未配置时默认为 2379 端口 - kubectl -n -it exec -- cat /etc/pd/pd.toml | grep client-urls - # TiKV, 未配置时默认为 20160 端口 - kubectl -n -it exec -- cat /etc/tikv/tikv.toml | grep addr - # TiDB, 未配置时默认为 4000 端口 - kubectl -n -it exec -- cat /etc/tidb/tidb.toml | grep port - ``` - -## Pod 处于 Pending 状态 - -Pod 处于 Pending 状态，通常都是资源不满足导致的，比如： - -* 使用持久化存储的 PD、TiKV、Monitor Pod 使用的 PVC 的 StorageClass 不存在或 PV 不足 -* Kubernetes 集群中没有节点能满足 Pod 申请的 CPU 或内存 -* PD 或者 TiKV Replicas 数量和集群内节点数量不满足 tidb-scheduler 高可用调度策略 - -此时，可以通过 `kubectl describe pod` 命令查看 Pending 的具体原因： - -{{< copyable "shell-regular" >}} - -``` -kubectl describe po -n -``` - -如果是 CPU 或内存资源不足，可以通过降低对应组件的 CPU 或内存资源申请使其能够得到调度，或是增加新的 Kubernetes 节点。 - -如果是 PVC 的 StorageClass 找不到，需要在 `values.yaml` 里面将 `storageClassName` 修改为集群中可用的 StorageClass 名字，执行 `helm upgrade`，然后将 Statefulset 删除，并且将对应的 PVC 也都删除，可以通过以下命令获取集群中可用的 StorageClass： - -{{< copyable "shell-regular" >}} - -``` -kubectl get storageclass -``` - -如果集群中有 StorageClass，但可用的 PV 不足，则需要添加对应的 PV 资源。对于 Local PV，可以参考[本地 PV 配置](/v3.1/tidb-in-kubernetes/reference/configuration/storage-class.md#本地-pv-配置)进行扩充。 - -tidb-scheduler 针对 PD 和 TiKV 定制了高可用调度策略。对于同一个 TiDB 集群，假设 PD 或者 TiKV 的 Replicas 数量为 N，那么可以调度到每个节点的 PD Pod 数量最多为 `M=(N-1)/2`（如果 N<3，M=1），可以调度到每个节点的 TiKV Pod 数量最多为 `M=ceil(N/3)`（ceil 表示向上取整，如果 N<3，M=1）。如果 Pod 因为不满足高可用调度策略而导致状态为 Pending，需要往集群内添加节点。 - -## Pod 处于 CrashLoopBackOff 状态 - -Pod 处于 CrashLoopBackOff 状态意味着 Pod 内的容器重复地异常退出（异常退出后，容器被 Kubelet 重启，重启后又异常退出，如此往复）。可能导致 CrashLoopBackOff 的原因有很多，此时，最有效的定位办法是查看 Pod 内容器的日志： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n logs -f -``` - -假如本次日志没有能够帮助诊断的有效信息，可以添加 `-p` 参数输出容器上次启动时的日志信息： - -{{< copyable "shell-regular" >}} - -```shell -kubectl -n logs -p -``` - -确认日志中的错误信息后，可以根据 [tidb-server 启动报错](/v3.1/how-to/troubleshoot/cluster-setup.md#tidb-server-启动报错)，[tikv-server 启动报错](/v3.1/how-to/troubleshoot/cluster-setup.md#tikv-server-启动报错)，[pd-server 启动报错](/v3.1/how-to/troubleshoot/cluster-setup.md#pd-server-启动报错)中的指引信息进行进一步排查解决。 - -若是 TiKV Pod 日志中出现 "cluster id mismatch" 信息，则 TiKV Pod 使用的数据可能是其他或之前的 TiKV Pod 的旧数据。在集群配置本地存储时未清除机器上本地磁盘上的数据，或者强制删除了 PV 导致数据并没有被 local volume provisioner 程序回收，可能导致 PV 遗留旧数据，导致错误。 - -在确认该 TiKV 应作为新节点加入集群、且 PV 上的数据应该删除后，可以删除该 TiKV Pod 和关联 PVC。TiKV Pod 将自动重建并绑定新的 PV 来使用。集群本地存储配置中，应对机器上的本地存储删除，避免 Kubernetes 使用机器上遗留的数据。集群运维中，不可强制删除 PV ，应由 local volume provisioner 程序管理。用户通过创建、删除 PVC 以及设置 PV 的 reclaimPolicy 来管理 PV 的生命周期。 - -另外，TiKV 在 ulimit 不足时也会发生启动失败的状况，对于这种情况，可以修改 Kubernetes 节点的 `/etc/security/limits.conf` 调大 ulimit： - -``` -root soft nofile 1000000 -root hard nofile 1000000 -root soft core unlimited -root soft stack 10240 -``` - -假如通过日志无法确认失败原因，ulimit 也设置正常，那么可以通过[诊断模式](#诊断模式)进行进一步排查。 - -## 无法访问 TiDB 服务 - -TiDB 服务访问不了时，首先确认 TiDB 服务是否部署成功，确认方法如下： - -查看该集群的所有组件是否全部都启动了，状态是否为 Running。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl get po -n -``` - -检查 TiDB 组件的日志，看日志是否有报错。 - -{{< copyable "shell-regular" >}} - -```shell -kubectl logs -f -n -c tidb -``` - -如果确定集群部署成功，则进行网络检查： - -1. 如果你是通过 `NodePort` 方式访问不了 TiDB 服务，请在 node 上尝试使用 service domain 或 clusterIP 访问 TiDB 服务，假如 serviceName 或 clusterIP 的方式能访问，基本判断 Kubernetes 集群内的网络是正常的，问题可能出在下面两个方面： - - * 客户端到 node 节点的网络不通。 - * 查看 TiDB service 的 `externalTrafficPolicy` 属性是否为 Local。如果是 Local 则客户端必须通过 TiDB Pod 所在 node 的 IP 来访问。 - -2. 如果 service domain 或 clusterIP 方式也访问不了 TiDB 服务，尝试用 TiDB服务后端的 `:4000` 连接看是否可以访问，如果通过 PodIP 可以访问 TiDB 服务，可以确认问题出在 service domain 或 clusterIP 到 PodIP 之间的连接上，排查项如下： - - * 检查 DNS 服务是否正常： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l k8s-app=kube-dns - dig - ``` - - * 检查各个 node 上的 kube-proxy 是否正常运行： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get po -n kube-system -l k8s-app=kube-proxy - ``` - - * 检查 node 上的 iptables 规则中 TiDB 服务的规则是否正确 - - {{< copyable "shell-regular" >}} - - ```shell - iptables-save -t nat |grep - ``` - - * 检查对应的 endpoint 是否正确 - -3. 如果通过 PodIP 访问不了 TiDB 服务，问题出在 Pod 层面的网络上，排查项如下： - - * 检查 node 上的相关 route 规则是否正确 - * 检查网络插件服务是否正常 - * 参考上面的 [Pod 之间网络不通](#pod-之间网络不通)章节 - -## TiKV Store 异常进入 Tombstone 状态 - -正常情况下，当 TiKV Pod 处于健康状态时（Pod 状态为 `Running`），对应的 TiKV Store 状态也是健康的（Store 状态为 `UP`）。但并发进行 TiKV 组件的扩容和缩容可能会导致部分 TiKV Store 异常并进入 Tombstone 状态。此时，可以按照以下步骤进行修复： - -1. 查看 TiKV Store 状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n tidbcluster -ojson | jq '.status.tikv.stores' - ``` - -2. 查看 TiKV Pod 运行状态： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl get -n po -l app.kubernetes.io/component=tikv - ``` - -3. 对比 Store 状态与 Pod 运行状态。假如某个 TiKV Pod 所对应的 Store 处于 `Offline` 状态，则表明该 Pod 的 Store 正在异常下线中。此时，可以通过下面的命令取消下线进程，进行恢复： - - 1. 打开到 PD 服务的连接： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl port-forward -n svc/-pd :2379 &>/tmp/portforward-pd.log & - ``` - - 2. 上线对应 Store： - - {{< copyable "shell-regular" >}} - - ```shell - curl -X POST http://127.0.0.1:2379/pd/api/v1/store//state?state=Up - ``` - -4. 假如某个 TiKV Pod 所对应的 `lastHeartbeatTime` 最新的 Store 处于 `Tombstone` 状态 ，则表明异常下线已经完成。此时，需要重建 Pod 并绑定新的 PV 进行恢复： - - 1. 将该 Store 对应 PV 的 `reclaimPolicy` 调整为 `Delete`： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl patch $(kubectl get pv -l app.kubernetes.io/instance=,tidb.pingcap.com/store-id= -o name) -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}} - ``` - - 2. 删除 Pod 使用的 PVC： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pvc tikv- --wait=false - ``` - - 3. 删除 Pod，等待 Pod 重建： - - {{< copyable "shell-regular" >}} - - ```shell - kubectl delete -n pod - ``` - - Pod 重建后，会以在集群中注册一个新的 Store，恢复完成。 - -## TiDB 长连接被异常中断 - -许多负载均衡器 (Load Balancer) 会设置连接空闲超时时间。当连接上没有数据传输的时间超过设定值，负载均衡器会主动将连接中断。若发现 TiDB 使用过程中，长查询会被异常中断，可检查客户端与 TiDB 服务端之间的中间件程序。若其连接空闲超时时间较短，可尝试增大该超时时间。若不可修改，可打开 TiDB `tcp-keep-alive` 选项，启用 TCP keepalive 特性。 - -默认情况下，Linux 发送 keepalive 探测包的等待时间为 7200 秒。若需减少该时间，可通过 `podSecurityContext` 字段配置 `sysctls`。 - -- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 允许配置 `--allowed-unsafe-sysctls=net.*`，请为 `kubelet` 配置该参数，并按如下方式配置 TiDB： - - {{< copyable "" >}} - - ```yaml - tidb: - ... - podSecurityContext: - sysctls: - - name: net.ipv4.tcp_keepalive_time - value: "300" - ``` - -- 如果 Kubernetes 集群内的 [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 不允许配置 `--allowed-unsafe-sysctls=net.*`，请按如下方式配置 TiDB： - - {{< copyable "" >}} - - ```yaml - tidb: - annotations: - tidb.pingcap.com/sysctl-init: "true" - podSecurityContext: - sysctls: - - name: net.ipv4.tcp_keepalive_time - value: "300" - ... - ``` - -> **注意：** -> -> 进行以上配置要求 TiDB Operator 1.1 及以上版本。 diff --git a/v3.1/tidb-in-kubernetes/upgrade/tidb-cluster.md b/v3.1/tidb-in-kubernetes/upgrade/tidb-cluster.md deleted file mode 100644 index 376882b3b162..000000000000 --- a/v3.1/tidb-in-kubernetes/upgrade/tidb-cluster.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: 滚动升级 Kubernetes 上的 TiDB 集群 -category: how-to ---- - -# 滚动升级 Kubernetes 上的 TiDB 集群 - -滚动更新 TiDB 集群时，会按 PD、TiKV、TiDB 的顺序，串行删除 Pod，并创建新版本的 Pod，当新版本的 Pod 正常运行后，再处理下一个 Pod。 - -滚动升级过程会自动处理 PD、TiKV 的 Leader 迁移与 TiDB 的 DDL Owner 迁移。因此，在多节点的部署拓扑下（最小环境：PD \* 3、TiKV \* 3、TiDB \* 2），滚动更新 TiKV、PD 不会影响业务正常运行。 - -对于有连接重试功能的客户端，滚动更新 TiDB 同样不会影响业务。对于无法进行重试的客户端，滚动更新 TiDB 则会导致连接到被关闭节点的数据库连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能或在低峰期进行 TiDB 的滚动升级操作。 - -滚动更新可以用于升级 TiDB 版本，也可以用于更新集群配置。 - -## 升级 TiDB 版本 - -1. 修改集群的 `values.yaml` 文件中的 `tidb.image`、`tikv.image`、`pd.image` 的值为新版本镜像； -2. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -3. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 - -## 更新 TiDB 集群配置 - -默认条件下，修改配置文件不会自动应用到 TiDB 集群中，只有在实例重启时，才会重新加载新的配置文件。 - -您可以开启配置文件自动更新特性，在每次配置文件更新时，自动执行滚动更新，将修改后的配置应用到集群中。操作步骤如下： - -1. 修改集群的 `values.yaml` 文件，将 `enableConfigMapRollout` 的值设为 `true`； -2. 根据需求修改 `values.yaml` 中需要调整的集群配置项； -3. 执行 `helm upgrade` 命令进行升级： - - {{< copyable "shell-regular" >}} - - ```shell - helm upgrade pingcap/tidb-cluster -f values.yaml --version= - ``` - -4. 查看升级进度： - - {{< copyable "shell-regular" >}} - - ```shell - watch kubectl -n get pod -o wide - ``` - - 当所有 Pod 都重建完毕进入 `Running` 状态后，升级完成。 - -> **注意：** -> -> - 将 `enableConfigMapRollout` 特性从关闭状态打开时，即使没有配置变更，也会触发一次 PD、TiKV、TiDB 的滚动更新。 - -## 强制升级 TiDB 集群 - -如果 PD 集群因为 PD 配置错误、PD 镜像 tag 错误、NodeAffinity 等原因不可用，[TiDB 集群扩缩容](/v3.1/tidb-in-kubernetes/scale-in-kubernetes.md)、[升级 TiDB 版本](#升级-tidb-版本)和[更新 TiDB 集群配置](#更新-tidb-集群配置)这三种操作都无法成功执行。 - -这种情况下，可使用 `force-upgrade`（TiDB Operator 版本 > v1.0.0-beta.3 ）强制升级集群以恢复集群功能。 -首先为集群设置 `annotation`： - -{{< copyable "shell-regular" >}} - -```shell -kubectl annotate --overwrite tc -n tidb.pingcap.com/force-upgrade=true -``` - -然后执行对应操作中的 `helm upgrade` 命令： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade pingcap/tidb-cluster -f values.yaml --version= -``` - -> **警告：** -> -> PD 集群恢复后，**必须**执行下面命令禁用强制升级功能，否则下次升级过程可能会出现异常： -> -> {{< copyable "shell-regular" >}} -> -> ```shell -> kubectl annotate tc -n tidb.pingcap.com/force-upgrade- -> ``` diff --git a/v3.1/tidb-in-kubernetes/upgrade/tidb-operator.md b/v3.1/tidb-in-kubernetes/upgrade/tidb-operator.md deleted file mode 100644 index c3a097840532..000000000000 --- a/v3.1/tidb-in-kubernetes/upgrade/tidb-operator.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 升级 TiDB Operator -category: how-to ---- - -# 升级 TiDB Operator - -本文介绍如何升级 TiDB Operator。升级 TiDB Operator 和自定义 TiDB Operator 类似，修改 `values.yaml` 中的镜像版本，然后执行 `helm upgrade`： - -{{< copyable "shell-regular" >}} - -```shell -helm upgrade tidb-operator pingcap/tidb-operator --version= -f /home/tidb/tidb-operator/values-tidb-operator.yaml -``` - -当新版本 tidb-operator 发布，只要更新 `values.yaml` 中的 `operatorImage` 然后执行上述命令就可以。但是安全起见，最好从新版本 `tidb-operator` chart 中获取新版本 `values.yaml` 并和旧版本 `values.yaml` 合并生成新的 `values.yaml`，然后升级。 - -TiDB Operator 是用来管理 TiDB 集群的，也就是说，如果 TiDB 集群已经启动并正常运行，你甚至可以停掉 TiDB Operator，而 TiDB 集群仍然能正常工作，直到你需要维护 TiDB 集群，比如伸缩、升级等等。 - -## 升级 Kubernetes - -当你的 Kubernetes 集群有版本升级，请确保 `kubeSchedulerImageTag` 与之匹配。默认情况下，这个值是由 Helm 在安装或者升级过程中生成的，要修改它你需要执行 `helm upgrade`。